summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--README.md9
-rw-r--r--claude-org/ocda_specification.org1630
-rw-r--r--claude-org/sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org252
-rw-r--r--ssp-format-specification.md17
4 files changed, 1908 insertions, 0 deletions
diff --git a/README.md b/README.md
index 400bced..2054386 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,11 @@ when one changes meaning or goes away, and a reader checks the major
part and refuses what it does not know. The history is in the
specification.
+A release is numbered `major.minor.patch`. `major.minor` is the format, and
+is shared by the specification and the programs that implement it; the patch
+is each one's own, and changes nothing a file can contain, so it is not
+written in a file.
+
## What is `.ssp`?
Spine's processing pipeline goes
@@ -141,5 +146,9 @@ project.
- [sisudoc-ocda-writer](https://git.sisudoc.org/sisudoc-ocda-writer) -
sample writers over that library (text, markdown, html, epub, typst),
each checked against spine. To be published.
+- [sisudoc-ssp-reader](https://git.sisudoc.org/sisudoc-ssp-reader) and
+ [sisudoc-ocda-db-reader](https://git.sisudoc.org/sisudoc-ocda-db-reader) -
+ the first readers, written from this specification alone, in D and in
+ Gleam; frozen, their work now done by `ocda-read` in sisudoc-ocda-lib.
- [tree-sitter-sisu](https://git.sisudoc.org/tree-sitter-sisu) - grammar
for the .sst / .ssm markup spine reads before writing a .ssp.
diff --git a/claude-org/ocda_specification.org b/claude-org/ocda_specification.org
new file mode 100644
index 0000000..6bb169d
--- /dev/null
+++ b/claude-org/ocda_specification.org
@@ -0,0 +1,1630 @@
+-*- mode: org -*-
+#+TITLE: configuration git
+#+DESCRIPTION: documents - structuring, various output representations & search
+#+FILETAGS: :spine:hub:
+#+AUTHOR: Ralph Amissah
+#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
+#+COPYRIGHT: Copyright (C) 2015 (continuously updated, current 2026) Ralph Amissah
+#+LANGUAGE: en
+#+STARTUP: content hideblocks hidestars noindent entitiespretty
+#+PROPERTY: header-args+ :eval never-export :exports code
+#+PROPERTY: header-args+ :noweb yes :padline no
+#+PROPERTY: header-args+ :results silent :cache no
+#+PROPERTY: header-args+ :mkdirp yes
+#+OPTIONS: H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t
+
+* ./
+** README.md
+
+#+HEADER: :tangle ../README.md
+#+HEADER: :noweb yes
+#+BEGIN_SRC md
+# sisudoc-abstraction-format
+
+Specification of the **object-centric document abstraction** that
+[sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) builds from
+SiSU markup, and of the two forms it is written in: **`.ssp`**, text and
+PEG-parsable, and **`.ocda.db`**, sqlite.
+
+The two carry one version number between them, because neither may express
+what the other cannot.
+
+## What this is
+
+A specification, not a program. The repository ships:
+
+- [`ocda-model.md`](ocda-model.md) - **the model**: what an object is,
+ the citation number, structure, sections, segments, digests. The part
+ both serialisations share, and the place the three terms *ocda*,
+ *abstraction* and `.ssp` are told apart.
+- [`ssp-format-specification.md`](ssp-format-specification.md) - **the
+ `.ssp`**: the model written as text.
+- [`ocda-db-format-specification.md`](ocda-db-format-specification.md) -
+ **the `.ocda.db`**: the model written as sqlite.
+- [`example-autonomous-contract.ssp`](example-autonomous-contract.ssp) -
+ spine's output for that sample document, complete and unedited.
+- [`example-wealth-of-networks.ssp`](example-wealth-of-networks.ssp) -
+ an excerpt of spine's output for that sample document: verbatim
+ lines, marked elisions, keeping the preamble, the `@head` section
+ and a run of body objects that includes an object embedding an
+ image. The whole file runs to 27,769 lines.
+
+Both carry, in their opening comment lines, the command that
+regenerates them, so they can be diffed against a run rather than
+taken on trust. Both are output of **spine, format 2.1** (neither holds a
+poem, so from 2.0 to 2.1 each changed by its version line alone).
+
+## Version
+
+The format is at **2.1**, and says so on the first line of every
+file:
+
+```
+% SiSU Document Abstraction v2.1
+```
+
+The minor part is raised when a property is added, the major part
+when one changes meaning or goes away, and a reader checks the major
+part and refuses what it does not know. The history is in the
+specification.
+
+A release is numbered `major.minor.patch`. `major.minor` is the format, and
+is shared by the specification and the programs that implement it; the patch
+is each one's own, and changes nothing a file can contain, so it is not
+written in a file.
+
+## What is `.ssp`?
+
+Spine's processing pipeline goes
+,**markup -> abstraction -> output**. The abstraction stage builds an
+in-memory object model: every paragraph, heading, table, footnote
+etc. is a numbered object with parent / sibling / type metadata
+("OCN" - Object Citation Numbering). `.ssp` is a faithful text
+serialisation of that object model.
+
+It is designed for:
+
+- Inspecting and debugging spine's abstraction stage.
+- Diff-friendly version control of document structure (a `.ssp`
+ diff between two markup edits shows exactly which objects
+ changed).
+- Round-trip experiments: markup -> spine -> `.ssp` -> alternative
+ renderers (HTML, LLM-ready chunks, ...) without rerunning spine.
+- A stable contract between spine and downstream consumers that do
+ not want to link against spine's internal D types.
+
+Line types (full grammar in
+[`ssp-format-specification.md`](ssp-format-specification.md)):
+
+```
+@name { section / block open
+} section / block close
+[N] type ... object declaration (N = OCN, 0 if unnumbered)
+.name: value property of the preceding object
+| text content text line of the preceding object
+ blank line (object separator)
+% comment comment (ignored by parser)
+```
+
+## Audience
+
+- Developers writing readers / converters for spine's abstraction
+ (readers written from this specification alone:
+ sisudoc-ssp-reader, sisudoc-ocda-db-reader, now frozen with current readers
+ offered and maintained within sisudoc-ocda-lib).
+- Anyone studying spine's internal document model without reading
+ the D source.
+- LLM / search / indexing tooling that consumes structured
+ document data downstream of spine.
+
+End-user document authors do not need to read this; they write
+`.sst` / `.ssm` markup, which spine then turns into `.ssp` along
+the way to the final output formats.
+
+## Quickstart
+
+Read the spec:
+
+```sh
+$EDITOR ssp-format-specification.md
+```
+
+Look at a real example:
+
+```sh
+$EDITOR example-wealth-of-networks.ssp
+```
+
+Generate your own `.ssp` from a sample document via spine:
+
+```sh
+# inside sisudoc-spine/
+result/bin/spine --source --pod2 --output=/tmp/ssp path/to/pod
+ls /tmp/ssp/pod/*/media/abstraction/*.ssp
+```
+
+`--pod2` writes the abstraction as `.ssp` and bundles it into the
+source pod. (See sisudoc-spine's CLI help for the current flags.)
+
+## License
+
+AGPL-3.0-or-later, matching the parent
+[sisudoc-spine](https://git.sisudoc.org/sisudoc-spine)
+project.
+
+## Repository
+
+- **Canonical URL:** https://git.sisudoc.org/sisudoc-abstraction-format
+- **Clone:** `git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format`
+
+## Related projects
+
+- [sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) - the document
+ engine that writes `.ssp` and `.ocda.db` files.
+- [sisudoc-ocda-lib](https://git.sisudoc.org/sisudoc-ocda-lib) - the
+ abstraction read as a library, from a .ssp, a .ocda.db or a
+ .sisupod (D and Gleam). To be published.
+- [sisudoc-ocda-writer](https://git.sisudoc.org/sisudoc-ocda-writer) -
+ sample writers over that library (text, markdown, html, epub, typst),
+ each checked against spine. To be published.
+- [sisudoc-ssp-reader](https://git.sisudoc.org/sisudoc-ssp-reader) and
+ [sisudoc-ocda-db-reader](https://git.sisudoc.org/sisudoc-ocda-db-reader) -
+ the first readers, written from this specification alone, in D and in
+ Gleam; frozen, their work now done by `ocda-read` in sisudoc-ocda-lib.
+- [tree-sitter-sisu](https://git.sisudoc.org/tree-sitter-sisu) - grammar
+ for the .sst / .ssm markup spine reads before writing a .ssp.
+#+END_SRC
+
+** git .gitignore :gitignore:
+
+#+HEADER: :tangle "../.gitignore"
+#+BEGIN_SRC gitignore
+,*
+!.gitignore
+!*.nix
+!flake.lock
+!*.md
+!*.ssp
+!org/
+!**/*.org
+!**/COPYRIGHT
+#+END_SRC
+
+** ocda-model.md
+
+#+HEADER: :tangle ../ocda-model.md
+#+BEGIN_SRC md
+# The object-centric document abstraction (OCDA)
+
+,**The model.** What a document *is* once spine has parsed it, independent
+of any file it is written to.
+
+Two serialisations carry this model, and they carry **one version number
+between them**, because neither may express what the other cannot:
+
+| | |
+|----------------------------------------------------------------------|--------------------------------|
+| [`ssp-format-specification.md`](ssp-format-specification.md) | the OCDA as text, `.ssp` |
+| [`ocda-db-format-specification.md`](ocda-db-format-specification.md) | the OCDA as sqlite, `.ocda.db` |
+
+This document is what they share. It describes objects; they describe
+writing objects down.
+
+## 1. Three words, and what each names
+
+The terms are used precisely in this repository and in spine, and the
+distinction is worth holding:
+
+| level | term | names |
+|--------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| the model | **OCDA** | what a document is once parsed: numbered objects with structure, identity and digests. Independent of any file, any stage, any tool |
+| the stage | **abstraction** | the middle of spine's **markup -> abstraction -> output**: the act of building the model, and the point at which a document may now enter the pipeline |
+| the serialisations | **`.ssp`**, **`.ocda.db`** | the model written down, as text and as sqlite |
+
+A thing is named for the level it belongs to. Something true of the model
+whatever file it is in takes *ocda*; something about the pipeline stage
+takes *abstraction*; something that reads or writes one file form takes
+that form's name.
+
+## 2. The object
+
+A document is a sequence of **objects**, grouped into sections. An object
+is a paragraph, a heading, a table, an endnote, a line of verse: the unit
+the document is made of and the unit it is cited by.
+
+Every object carries:
+
+- an **object citation number** (OCN), section 3;
+- an **identifier**, section 3.1;
+- a **kind** and a **type**, section 2.1;
+- its **place in the structure**: parent, ancestors, and for a heading its
+ children and its last descendant, section 4;
+- the **segment** it is in, and for a heading an **anchor**, sections 7
+ and 7.1;
+- its **text**, in spine's internal representation;
+- a **digest** of that text.
+
+### 2.1 Kind and type: two axes, not one
+
+An object is classified twice, and the two answer different questions.
+
+,**Kind** (`is_a`) says *what the object is*, one of sixteen. Each kind
+belongs to one section, except `heading`, which appears in all nine:
+
+| kind | section | what it is | count |
+|----------------|--------------|--------------------------------------------------------------------------------|--------|
+| `para` | body | a paragraph, the ordinary unit of a document | 41,885 |
+| `heading` | *all nine* | a heading at one of the eight levels | 3,503 |
+| `toc` | toc | an entry in the generated table of contents | 3,215 |
+| `bookindex` | bookindex | an entry in the generated book index | 3,034 |
+| `endnote` | endnotes | a note, gathered from where it was called | 2,294 |
+| `code` | body | a code block | 1,623 |
+| `bibliography` | bibliography | a bibliography entry | 585 |
+| `comment` | body | markup comment, carried and not rendered | 450 |
+| `verse` | body | one verse of a poem | 151 |
+| `glossary` | glossary | a glossary entry | 56 |
+| `quote` | body | a block quotation | 53 |
+| `poem` | body | a poem: the container of its verses, OCN `0`, cited as their range (section 5) | 48 |
+| `block` | body | a block of grouped text | 45 |
+| `table` | body | a table, with its columns described | 32 |
+| `blurb` | blurb | a blurb entry | 28 |
+| `group` | body | a group block | 16 |
+
+,**Type** (`is_of_type`) says *how the object's text behaves*, and takes
+only three values:
+
+| type | means | kinds |
+|-----------|---------------------------------------------------------|---------------------------------------------------------------------------------------|
+| `para` | flowing text, wrapped as the output sees fit | `para`, `heading`, `toc`, `bookindex`, `endnote`, `bibliography`, `glossary`, `blurb` |
+| `block` | text whose line breaks are significant and must be kept | `code`, `verse`, `quote`, `poem`, `block`, `table`, `group` |
+| `comment` | not rendered | `comment` |
+
+The mapping from kind to type is fixed: every `code` object is of type
+`block`, every `para` object of type `para`. **A renderer that has the type
+does not need to know all sixteen kinds** to decide whether it may reflow
+the text, which is what the second axis is for.
+
+## 3. The object citation number
+
+The OCN is the heart of the model and the reason for it.
+
+,**An object's OCN is the same in every format spine writes.** A paragraph
+that is object 42 in the HTML is object 42 in the EPUB, in the PDF, in the
+plain text, in the search database and in both serialisations of the
+abstraction. A citation to object 42 of a document is therefore a citation
+to a fixed piece of text, not to a page in one edition or a scroll position
+in one rendering.
+
+Three properties follow, and each is a trap for a reader that assumes
+otherwise:
+
+- **Not every object has one.** Generated furniture, and objects the markup
+ has suppressed, carry `0`. There are many of them: 7,543 across the 36
+ document reference collection.
+- **`0` is therefore not an identity.** Objects sharing `0` are not the
+ same object, and `0` must never be used as a key.
+- **A non-zero OCN is unique within a document**, from format 2.1: checked
+ over the reference collection, no non-zero OCN occurs twice in any of the
+ 36 document-languages. **Before 2.1 it was not**: a poem carried the OCN of
+ its last verse, so the same number named two objects (48 such pairs in the
+ collection, 21 in `through_the_looking_glass`). A reader of an older
+ artefact keys on position within a section when one row is wanted.
+
+### 3.1 The identifier
+
+Every object also carries an **identifier**: the name by which an output
+refers to it. An HTML anchor, a LaTeX `\hypertarget`, a link from a book
+index entry to the object it indexes, are all written from the identifier.
+
+,**The identifier of an object with a non-zero OCN is its OCN**, written as
+text. That is the ordinary case and it is the reason a citation to object
+42 can be turned into a link without consulting anything.
+
+An object with OCN `0` has no OCN to take an identifier from, so one is
+assigned: `a1`, `a2`, `a3`, ... in document order over the objects that
+need one. There are few of them, eleven in a book, and they are the
+generated furniture of section 3.
+
+,**A reader must arrive at the identifier whether or not the serialisation
+wrote it down**; see section 9.
+
+## 4. Levels
+
+A document has **eight heading levels**, in two groups of four:
+
+| level | index | what it is |
+|-------|-------|----------------------------------------------|
+| `A` | 0 | the document title. Exactly one per document |
+| `B` | 1 | |
+| `C` | 2 | the title matter below it |
+| `D` | 3 | |
+| `1` | 4 | the top level of the document body |
+| `2` | 5 | |
+| `3` | 6 | below that |
+| `4` | 7 | |
+
+`A` to `D` are the title levels, `1` to `4` the body levels, and the index
+is what the eight-slot arrays of section 5 are indexed by. A heading that
+claims no level has 9, which is the "not a heading level" value and is why
+`.heading_lev_collapsed` is emitted only when it is below 9.
+
+,**Collapsed levels.** A document that uses `A` and then `1`, skipping `B`,
+`C` and `D`, has a gap in its levels that is an artefact of the markup
+rather than of the document. Every level-indexed array therefore comes in
+two forms: as marked up, and **collapsed**, with the unused levels removed
+so that the remaining ones are contiguous. Outputs that care about nesting
+depth use the collapsed form; anything tracing back to the markup uses the
+other.
+
+## 5. Structure
+
+Structure is carried by number, not by nesting: an object names its parent
+rather than containing its children. This is what lets the serialisations
+be flat and the model be walked in either direction.
+
+- **`parent`** - the OCN of the object this one hangs from.
+ **A parent of `0` is not "no parent"**: it is a parent heading the author
+ has made non-substantive, its OCN suppressed or a dummy heading
+ introduced to segment an output. The distinction is preserved
+ deliberately, and a reader walking upward must stop at `0` rather than
+ treat it as missing, or the walk will not terminate.
+- **`ancestors`** - **eight slots, indexed by level** (section 4): the OCN
+ of the heading at each level above this object, `0` where there is none,
+ so the path to the root is available without walking it.
+ **A heading's own OCN sits in its own level's slot**: checked over the
+ reference collection, 3,432 headings of 3,432. So for a heading the array
+ is its path including itself, and for any other object it is the path to
+ the heading above it.
+- **`ancestors_collapsed`** - the same, in collapsed levels.
+- **`children`** - a heading's child headings.
+- **`last_descendant`** - the last OCN under a heading, which makes a
+ subtree a **range** rather than a traversal: everything from the
+ heading's OCN to its last descendant is inside it.
+- **`ocn_range`** - for a **container**, the first and last OCN of what it
+ holds (2.1). A poem is the one container: its verses are the citable
+ units, one object each, and the poem is not; it carries OCN `0` and no
+ identifier, **comes immediately before its first verse**, and is cited as
+ the range of them (`173-180`). So a writer that meets a poem knows what
+ follows and where it ends, and can wrap the verses in one pass. The poem
+ has no text of its own. `0 0`, or absent, where the object is not a
+ container.
+ **Before 2.1** the poem came *after* its last verse, carried that verse's
+ OCN and identifier, and stated no range.
+
+## 6. Sections
+
+Objects are grouped into nine sections, in this order:
+
+```
+head toc body endnotes glossary bibliography bookindex blurb tail
+```
+
+`head` is the document's title matter, `body` the document proper, and the
+rest are generated or gathered. `tail` is the end of document some output
+writers use. A section with no objects is not carried.
+
+## 7. Segments
+
+An output may be one file or many. A **segment** is one of the many: a
+chapter-sized piece of HTML or EPUB with its own name and its own
+navigation.
+
+Two different questions are asked about segments, and the model answers
+both separately because the answers differ:
+
+- **which segment does this heading open?** Set on headings only.
+- **which segment is this object in?** Set on nearly every object.
+
+Without the second, a reader cannot say where a paragraph belongs. The
+search database reads the second.
+
+### 7.1 The anchor
+
+A heading carries an **anchor**: the name an output links to in order to
+arrive at that heading. It is what a table of contents entry and a
+cross reference point at.
+
+,**An object's anchor is its segment name**, in the ordinary case, because a
+heading that opens a segment is arrived at by arriving at the segment. It
+differs only where a heading is not the opening of the segment it sits in:
+69 of the 72 anchors in one reference document equal their segment and 3 do
+not.
+
+,**A reader must arrive at the anchor whether or not the serialisation wrote
+it down**; see section 9.
+
+## 8. Digests
+
+The model is checkable at four levels, and the chain is what lets an
+artefact be verified rather than trusted:
+
+```
+the markup files ──> a digest over every markup file of that language
+the serialisation ──> a digest of the .ssp a database was built from
+each object ──> a digest of the object's text
+each image ──> a digest of the image file, with its size in bytes and pixels
+```
+
+An object's digest is over its text alone, so a change to one paragraph
+moves one digest and no other.
+
+## 9. Derived values, and why a reader must derive them
+
+Two of the values above are **derived**: the identifier from the OCN
+(section 3.1), and the anchor from the segment name (section 7.1). The
+model holds them; a serialisation need not, and the text form does not.
+
+,**A serialisation may omit a value it can compute.** The `.ssp` writes a
+property only when it carries information, so it omits `.identifier` where
+the identifier is the OCN and `.anchor` where the anchor is the segment
+name. The `.ocda.db` is columns rather than lines and writes both
+unconditionally.
+
+Both are conforming. What is **not** conforming is a reader that takes the
+text form literally and hands on a model with those fields empty, because
+that model is not the same model the database gives, and a writer over it
+will produce different output from the two serialisations of one document.
+
+The size of the difference is easy to underestimate. In
+`free_culture.lawrence_lessig` the `.ssp` omits **1,314 identifiers and 69
+anchors** that the `.ocda.db` states, which is nearly every object in the
+document.
+
+So, on loading:
+
+| field | when absent | take |
+|------------|--------------------------|------------------------------------------------------------------|
+| identifier | OCN is non-zero | the OCN as text |
+| identifier | OCN is `0` | whatever the serialisation gave; there is nothing to derive from |
+| anchor | the object has a segment | the segment name |
+
+,**This is a property of the model, not of either format**, which is why it
+is stated here and not only in the two format specifications. It is stated
+here *because* two readers written independently from these documents
+disagreed for want of it: the rule was implied by the `.ssp`'s emission
+conditions and nowhere asserted.
+
+It is also what **spine's own reader** does, and always did, which is why
+the `.ocda.db` carries the derived values: the database is written from the
+`.ssp` read straight back, and the reading fills both in. So this section
+documents existing behaviour rather than prescribing new. It should have
+been written down first.
+
+## 10. What the model does not hold
+
+- **The markup.** The model is what the markup produced, not the markup
+ itself. An artefact that carries both is the `.ocda.db`, which carries
+ the markup alongside the model rather than within it.
+- **The images.** The model *names* them, with digest, byte size and pixel
+ size, and they must be found beside the file for a document to be
+ complete.
+- **Any output format.** No HTML, no page numbers, no typesetting.
+#+END_SRC
+
+** ssp-format-specification.md
+
+#+HEADER: :tangle ../ssp-format-specification.md
+#+BEGIN_SRC md
+# The `.ssp` format
+
+,**The object-centric document abstraction, written as text. Format version
+2.1**, as spine emits and reads it after 0.25.1.
+
+This document specifies *one serialisation*. The model it serialises is
+specified in [`ocda-model.md`](ocda-model.md), which the sqlite
+serialisation shares; read that first if the question is what an object
+,*is* rather than how it is written down.
+
+## The name
+
+`.ssp` belongs to the family of SiSU markup extensions, `.sst` (sisu text),
+`.ssm` (sisu master) and `.ssi` (sisu insert), and a short extension was
+wanted that sat with them. It stands loosely for **sisu peg**, or **sisu
+parsable**. `.ssa`, for sisu abstraction, was thought to be taken by other
+projects.
+
+So the extension names the *file family and its parsability*, where
+`.ocda.db` names the *model and its container*. The two are not parallel in
+construction and are not meant to be.
+
+## Status
+
+This specification is derived from the emitter
+(`sisudoc/ocda/abstraction/ssp.d` in sisudoc-spine, whose `sspObjectRecord`
+is "the single definition of what an object looks like in a `.ssp` file"),
+and every claim in it is checked against the project's 36 document
+reference set. Where the two could differ, the emitter is normative and
+this document is wrong.
+
+## 1. What a `.ssp` is
+
+A `.ssp` file is the serialisation, as text, of one language of one
+document after spine has parsed it: the object model, not the markup and
+not any output format.
+
+Spine's pipeline is **markup -> abstraction -> output**. A `.ssp` is the
+middle stage written down. Since spine 0.25.0 it is also read back, so a
+document may enter the pipeline at the abstraction stage instead of being
+parsed, and the output writers cannot tell which happened.
+
+The format is:
+
+- **line oriented.** Every construct is a whole line. No line continuations.
+- **order significant.** Sections appear in a fixed order, objects in
+ document order, and an object's properties in a fixed order (section 6.3).
+- **UTF-8**, without a byte order mark.
+- **lossless for the abstraction**, not for the markup: a `.ssp` read back
+ and re-emitted is byte identical, which the project's test suite asserts
+ over the whole reference set.
+
+### 1.1 What it is not
+
+It does not carry the markup it was made from, and it does not carry its
+images: it *names* them, with their digests and pixel sizes, and they must
+be found beside it (`../image/` within a pod) for the document to be
+complete. An artefact that carries both is the `.ocda.db`, which is built
+by reading a `.ssp` back, so it can hold nothing this format cannot express.
+
+## 2. Version and compatibility
+
+The version is declared **in band**, on the first line of every file:
+
+```
+% SiSU Document Abstraction v2.1
+```
+
+and by the sibling sqlite serialisation in its `schema.version` metadata
+row, so that one bump moves both.
+
+### 2.1 The rule
+
+- The **minor** part is raised when a property is **added**. A reader of the
+ newer format still reads the older one.
+- The **major** part is raised when a property **changes meaning or goes
+ away**.
+- A reader **checks the major part and refuses what it does not know**,
+ rather than loading an unfamiliar artefact half populated in silence.
+- A **patch** part, the third, numbers *releases* and not the format: a
+ correction or clarification of this text, or a fix in a program that
+ implements it, changes nothing a file can contain. So a file declares
+ `major.minor` only, and a release is `major.minor.patch`. The
+ specification and the programs that implement it share `major.minor`,
+ which is the format, and each numbers its own patches.
+
+### 2.2 History
+
+| version | date | what moved |
+|---------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 2.1 | 2026-09-29 | `.ocn_range`, the first and last ocn of what a container holds. A poem is a container of verses and is cited as their range: it now comes before its first verse, carries ocn `0` and no identifier, and states the range, where it had come after its last verse carrying that verse's ocn and identifier, so that one number named two objects. A minor bump: the property is an addition, the poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The same run gathers a note in a poem's last verse into the endnotes, which it had not been: one more endnote in the reference collection. And the editor's notes, `~[* ]~` and `~[+ ]~`, which spine had not recognised and passed through as text, are notes: a third form of note mark, a symbol and a number (`*1`, `+1`), each series numbered through the document; 135 more endnotes, 2,294 in all (section 3.2, "A note begins with its mark"). |
+| 2.0 | 2026-09-18 | `source.digest` changes meaning: it covers every markup file the document is made of, where it had been the digest of the master file alone. A change of meaning, so the major part. |
+| 1.1 | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`. |
+| 0.1 | | The first form. |
+
+### 2.3 Releases of this specification
+
+| release | format | what |
+|---------|--------|---------------------------------------------------------------------|
+| 2.0.0 | 2.0 | the model and the `.ssp` |
+| 2.0.1 | 2.0 | the object kinds and types, the levels, the make block, the markers |
+| 2.0.2 | 2.0 | the `.ocda.db`; two rules a validator found unstated |
+| 2.0.3 | 2.0 | the derived values: the identifier and the anchor |
+| 2.1.0 | 2.1 | `.ocn_range`, and the editor's notes |
+| 2.1.1 | 2.1 | the patch part of a release number, and this table |
+
+## 3. Lexical structure
+
+Six line types, distinguished by their first character. Nothing else is a
+valid line.
+
+| line | form | meaning |
+|--------------------|-----------------|-----------------------------------------------|
+| comment | `% ...` | file header only (section 4) |
+| block open | `@name {` | opens a preamble block or a section |
+| block close | `}` | closes it |
+| key | ` key: value` | inside a preamble block, two spaces of indent |
+| object declaration | `[ocn] kind...` | opens an object record (section 6.1) |
+| property | `.name: value` | a property of the object just declared |
+| text | `\| text` | a line of the object's text |
+| blank | | separates records; carries no meaning |
+
+A value runs to the **end of the line**. It is not quoted, and it is not
+trimmed beyond the single space after the colon. A value may therefore
+contain `:`, spaces, and any UTF-8 character except a line break.
+
+### 3.1 Escaping
+
+Only one value is escaped, because only one value is a **joined list**:
+`.heading_ancestors_text` joins eight slots with `|`. A slot that itself
+contains `|`, a backslash, or a line break would otherwise be unreadable.
+
+| in the value | written as |
+|-----------------|------------|
+| `\` | `\\` |
+| `\|` | `\\|` |
+| newline | `\n` |
+| carriage return | `\r` |
+
+Unescaping reads left to right: a backslash escapes the next character,
+`\n` and `\r` become the control characters, any other escaped character
+stands for itself, and an unescaped `|` ends the slot.
+
+,**No other value is escaped**, and text lines are not escaped at all: a
+text line is the object's text verbatim after the two-character `| `
+prefix.
+
+### 3.2 Object text is internal markup
+
+The text on `|` lines is spine's **internal** representation, neither the
+author's markup nor any output. It carries the markers spine uses to hold
+inline structure:
+
+The full set is defined in spine's `InlineMarkup` (`ocda/meta/defaults.d`).
+Counts are occurrences in object text across the 36 document reference
+collection, which distinguishes what a reader will certainly meet from what
+it may not.
+
+| marker | means | count | where |
+|-------------|---------------------------------------------|--------|----------------------|
+| `░` | non-breaking space | 23,048 | |
+| `┥` `┝` | link text, open and close | 20,290 | |
+| `┤` `├` | link target, open and close | 20,290 | |
+| `⑆` | a page number of the source edition follows | 19,099 | |
+| `┨` `┣` | that page number, open and close | 19,099 | |
+| `■` | monospace | 10,688 | |
+| `【` `】` | an inline note, its mark first (below) | 2,294 | |
+| `¤` | an internal site link | 2,157 | |
+| `┊` | table cell separator | 695 | `table` objects only |
+| `┙` | line break, inline | 184 | |
+| `☼` | an image, in a link's text slot | 63 | |
+| `┚` | line break, spaced | 50 | `group` objects only |
+| `〖` `〗` | a starred note | 0 | |
+| `‖` | a citation | 0 | |
+| `┘` | line break, plain | 0 | |
+| `┼` `┿` `╂` | page break: line, page, new page | 0 | |
+| `┏` `┆` | table open, table paragraph | 0 | |
+| `␣` | separator | 0 | |
+
+,**A count of 0 means the reference collection does not exercise it, not
+that it cannot appear.** All of these are defined by the emitter and a
+reader must be prepared for them.
+
+,**A note begins with its mark**, then whitespace, then the note: `【12 text】`.
+The mark is one of three forms, and a reader must take all three:
+
+| mark | what | example |
+|-------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------------------------|
+| digits | the author's notes, numbered through the document | `【12 ...】` |
+| `*` or `+`, repeated | a special note, marked by the symbols alone | `【** ...】` |
+| `*` or `+`, then digits | an editor's note (2.1): the markup's `~[* ]~` and `~[+ ]~`, each series numbered through the document apart from the author's | `【*3 ...】`, `【+1 ...】` |
+
+So the pattern is `【(\d+|[*+]+[0-9]*)\s`. Before 2.1 the third form did not
+occur: spine did not recognise the editor's-note markup, and it came through
+as text, `~[* ...]~` and all. Each note of every form is gathered into the
+`endnotes` section, where its `.anchor_tag` is `note_` and the mark
+(`note_12`, `note_*3`).
+
+Two traps in this table, both found by counting rather than by reading:
+
+,**`┚` is defined twice**, as the spaced line break and as the table close.
+In object text it occurs only in `group` objects, never in a `table`, so
+the object's kind resolves it. A reader should decide by kind rather than
+by character.
+
+,**`「` and `」` are not markers here.** They are defined in `InlineMarkup`
+as the wrapper spine's ODT writer puts around an object number, but that
+happens at output, after the abstraction. Their 67 occurrences in the
+reference collection are **Japanese corner brackets in the document's own
+text**, being quotation marks in Japanese. In a `.ssp` they are always
+content.
+
+Some markers are the ASCII characters `*`, `!`, `/`, `_`, `^` and `,` for
+emphasis, bold, italic, underscore, superscript and subscript. These are
+,**not distinguishable from ordinary text by inspection**, and a reader that
+needs them must follow spine's rules for where they apply rather than
+searching for the characters.
+
+A reader that renders text must decode all of this; a reader that only
+searches or counts need not, and one that wants plain text may strip the
+non-ASCII markers and take the ASCII ones as text. They are stable and they
+are part of the format.
+
+## 4. File shape
+
+In order, and this order is fixed:
+
+```
+% SiSU Document Abstraction v2.1
+% Source: <markup filename>
+
+@source { ... }
+
+@meta { ... }
+
+@make { ... }
+
+@doc_has { ... }
+
+@head { ... }
+@toc { ... }
+@body { ... }
+@endnotes { ... }
+@glossary { ... }
+@bibliography { ... }
+@bookindex { ... }
+@blurb { ... }
+@tail { ... }
+```
+
+The two `%` lines are the only comments in the file and appear only here.
+The four preamble blocks are always present and always in that order. The
+nine section blocks appear in that order. **A section is omitted entirely
+when the document has no objects for it**, though in practice that is rare:
+all 36 documents of the reference collection carry all nine, several of
+them holding a single generated object.
+
+## 5. The preamble blocks
+
+Inside a block, every line is ` key: value` with exactly two spaces of
+indent. Keys are unique within a block. **A key whose value is empty is
+omitted**, so the set of keys present varies by document; the exceptions
+are noted below.
+
+### 5.1 `@source` - what this abstraction was made from
+
+| key | always? | meaning |
+|-------------|----------------------------|-----------------------------------------------------------------------------|
+| `language` | yes | the language of *this* file |
+| `languages` | when the pod declares them | every language of the document, space separated |
+| `digest` | yes | sha256 over **every markup file the document is made of**, in a fixed order |
+
+The source *filename* is not repeated here; it is on the `% Source:` line.
+
+`digest` is what changed in 2.0. It had been the digest of the master file
+alone, which for a single file document was right and for a multi-file one
+was close to meaningless: any chapter could be edited without the digest
+moving.
+
+### 5.2 `@meta` - the document's own metadata
+
+Dublin-Core shaped, `group.name`. **43 keys are defined**; a given document
+carries only those it has. The 28 the reference collection exercises are
+marked; the remainder are defined and simply unused by these documents.
+
+| group | keys |
+|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `title.` | `main`*, `subtitle`*, `full`*, `language`*, `edition`* |
+| `creator.` | `author`*, `author_surname`*, `author_surname_fn`*, `author_email`*, `illustrator`*, `translator`* |
+| `date.` | `published`*, `created`*, `issued`*, `available`*, `modified`*, `valid`*, `added_to_site`* |
+| `rights.` | `copyright`*, `license`*, `copyright_text`, `copyright_translation`, `copyright_illustrations`, `copyright_photographs`, `copyright_cover`, `copyright_audio`, `copyright_video` |
+| `classify.` | `topic_register`*, `subject`, `keywords`, `loc`*, `dewey`* |
+| `identifier.` | `isbn`, `oclc` |
+| `notes.` | `summary`*, `abstract`*, `description`* |
+| `original.` | `source`*, `title`, `language`, `language_char` |
+| `language.` | `document_char`*, `document` |
+
+`classify.topic_register` is structured within its value: topics separated
+by `;`, levels within a topic by `:`, and alternatives at a level by `|`.
+
+### 5.3 `@make` - how the document is to be built
+
+| key | value | meaning |
+|-------------------------|--------------------------|--------------------------------------------------------------------------------------------------------|
+| `doc_type` | `article`, `book` | what kind of document this is |
+| `auto_num_top_at_level` | a level, e.g. `1` | the heading level automatic numbering starts at, **as written in the markup** |
+| `auto_num_top_lv` | that level's index, 0..8 | the same level as a number (section 4 of [`ocda-model.md`](ocda-model.md)); `9` where numbering is off |
+| `auto_num_depth` | e.g. `2` | how many levels down numbering continues |
+| `breaks` | see below | where the output starts a new page, and where it breaks one |
+| `footer` | slots joined with `\|` | the footer, each slot carrying link markup |
+| `home_button_text` | link markup | the home link, as internal markup |
+
+`auto_num_top_at_level` and `auto_num_top_lv` are **the same value twice**,
+as the markup wrote it and as an index: `1` and `4`, since the body levels
+begin at index 4.
+
+`breaks` is a small language of its own, `new=` for a new page and
+`break=` for a page break, each taking a comma separated list of levels,
+the two separated by `;`:
+
+```
+breaks: new=:A,:B; break=:C,1
+breaks: new=:B; break=1
+breaks: break=1
+```
+
+The level names here are written as they are in the markup, so with or
+without the leading colon as the document wrote them; a reader should not
+assume either form.
+
+### 5.4 `@doc_has` - what the document contains, by count
+
+Ten keys, **all ten always emitted**, zero included. This block is a
+summary a reader can use without walking the objects.
+
+```
+inline_links inline_notes_reg inline_notes_star tables codeblocks
+images poems groups blocks quotes
+```
+
+## 6. Objects
+
+The nine section blocks hold object records, in document order. An object
+record is an object declaration line, then its properties, then its text
+lines, then a blank line.
+
+### 6.1 The declaration line
+
+```
+[<ocn>] <kind>
+[<ocn>] heading :<level>
+[<ocn>] heading :<level> <identifier>
+```
+
+`<ocn>` is the **object citation number** (see
+[`ocda-model.md`](ocda-model.md) section 3). `[0]` means the object has
+none, is shared by many objects, and must never be used as a key; key on
+position within a section instead.
+
+`<kind>` is one of sixteen:
+
+```
+para heading toc bookindex endnote code bibliography comment
+verse glossary quote poem block table blurb group
+```
+
+A **heading** is the one kind whose declaration line carries more: its
+markup level after a colon (`:A` `:B` `:C` `:D` for the title levels,
+`:1`..`:4` for the body levels; `:D` is defined and unexercised by the
+reference collection), and then its identifier, when it has one
+that is not simply the ocn. Every other kind carries an identifier, on the
+same condition, as the `.identifier` property.
+
+> **A reader must derive the identifier where it is absent, and the anchor
+> likewise.** "when it has one that is not simply the ocn" means the
+> identifier *is* the ocn in every other case, and a reader that leaves the
+> field empty gives a different model from the one the `.ocda.db` gives, on
+> nearly every object. Section 9 of [`ocda-model.md`](ocda-model.md) states
+> both derivations and why they belong to the model rather than to either
+> format. Two readers written independently from these documents disagreed
+> for want of it.
+
+### 6.2 Text lines
+
+```
+| <text>
+```
+
+One line per line of the object's text, in order, each prefixed with
+`| ` (pipe, space). An object with no text has no text lines. The text is
+internal markup (section 3.2) and is not escaped.
+
+### 6.3 Properties
+
+,**Properties appear in a fixed order**, the order of the table below, and a
+reader may rely on it: checked over the reference set, no object among
+56,882 emits a property out of this order.
+
+,**A property is omitted when it holds its default**, so absence is
+meaningful and is defined per property in the table. Four properties
+repeat, appearing once per value rather than carrying a list: `.image`,
+`.stow_link`, `.lev4_subtoc` and `.anchor_tag`.
+
+Two consequences of the order, which a validator needs stated and which
+hold over the whole reference collection:
+
+- **a repeated property's occurrences are consecutive.** They share one
+ position in the order, and nothing is written between them. Checked: no
+ repeat in the collection is separated by another property.
+- **no property follows the text.** The record is declaration, then
+ properties, then text lines, and once a `|` line has been written no
+ further property appears. Checked: 0 occurrences in the collection.
+
+In the table, "emitted when" is the condition under which the property
+appears at all. Counts are occurrences across the 36 document reference
+set, as a guide to which parts of the format are load bearing.
+
+| # | property | value | emitted when | count |
+|----|---------------------------|-------------------------------|----------------------------------------------------------------------------------------------------|--------|
+| 1 | `.identifier` | string | a non-heading has an identifier that is not its ocn (**otherwise it is the ocn**: model section 9) | 353 |
+| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 57,018 |
+| 3 | `.section` | string | the object's own section differs from the block it sits in | 605 |
+| 4 | `.parent` | int | **every object except** the document root and `toc` entries | 53,767 |
+| 5 | `.last_descendant` | int | non-zero: the last ocn under this heading | 3,202 |
+| 6 | `.ocn_range` | 2 ints | the object is a container: the first and last ocn of what it holds (2.1; a poem, model section 5) | 48 |
+| 7 | `.children` | ints | the heading has child headings | 827 |
+| 8 | `.ancestors` | 8 ints | any is non-zero | 53,731 |
+| 9 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,731 |
+| 10 | `.dom_status` | 8 ints | any is non-zero | 3,319 |
+| 11 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 |
+| 12 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 |
+| 13 | `.parent_lev` | int | non-zero | 52,984 |
+| 14 | `.dummy` | `true` | the heading was introduced to segment an output | 183 |
+| 15 | `.ocn_off` | `true` | the object has no citation number | 7,543 |
+| 16 | `.is_of_type` | string | always, in practice | 57,018 |
+| 17 | `.attrib` | string | set | 1 |
+| 18 | `.meta_lang` | string | the object carries its own language | 0 |
+| 19 | `.meta_syntax` | string | the object carries its own markup syntax | 0 |
+| 20 | `.sha256` | hex | the object's text digest is non-zero | 51,253 |
+| 21 | `.image` | record | once **per image**, in order of appearance | 63 |
+| 22 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 |
+| 23 | `.bullet` | `true` | the object is a bullet item | 1,903 |
+| 24 | `.lang` | string | the text attributes carry a language | 0 |
+| 25 | `.has` | flags | any is set | 11,384 |
+| 26 | `.table_cols` | int | the object is a table with columns | 32 |
+| 27 | `.table_widths` | ints | the table has column widths | 32 |
+| 28 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 |
+| 29 | `.table_header` | `true` | the table has a header row | 29 |
+| 30 | `.code_linenumbers` | `true` | the code block is numbered | 1 |
+| 31 | `.stow_link` | url | once **per extracted link** | 1,014 |
+| 32 | `.segment` | string | the heading opens a segment | 3,355 |
+| 33 | `.anchor` | string | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9) | 68 |
+| 34 | `.segment_prev` | string | there is a previous segment | 1,022 |
+| 35 | `.segment_next` | string | there is a next segment | 1,022 |
+| 36 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 |
+| 37 | `.segment_epub` | string | the heading opens an epub segment | 3,355 |
+| 38 | `.segment_html_is` | string | the object is inside an html segment | 47,072 |
+| 39 | `.segment_epub_is` | string | the object is inside an epub segment | 47,072 |
+| 40 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 |
+| 41 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 |
+| 42 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 |
+| 43 | `.anchor_tag` | string | once **per anchor tag** | 8,019 |
+
+Three of these need a word here, the first two because the model behind
+them is easy to misread (see [`ocda-model.md`](ocda-model.md) sections 5
+and 7), the third because it is a property of this table rather than of the
+format.
+
+,**`.parent: 0` is emitted, not omitted.** A parent of 0 is a real,
+non-substantive parent and not a missing value, so the property is written
+out rather than defaulted away: omitting it would make the two cases
+indistinguishable in the file. A reader walking upward stops at 0.
+
+,**`.segment` and `.segment_html_is` are different questions**, and both are
+carried: what a heading opens, and what an object sits in. A reader wanting
+to know where a paragraph belongs needs the second.
+
+,**Count 0 does not mean "not in the format".** `.meta_lang`, `.meta_syntax`
+and `.lang` are emitted by spine under the conditions given, and no
+document in the reference collection meets them. A reader must handle them;
+a test corpus does not exercise them.
+
+### 6.4 The `.image` record
+
+```
+.image: <filename> sha256:<HEX> bytes:<n> px:<width>x<height>
+.image: <filename> missing:true
+```
+
+Filename first, as the object's handle on the image. The remaining fields
+are self describing `key:value` tokens, **so that further fields may be
+added without invalidating existing readers**; `px:` is omitted when the
+pixel size is unknown. `px:` is the file's own size, not the display size,
+which the object's text already carries.
+
+### 6.5 The `.has` flags
+
+Space separated, in this order, each present only when set:
+
+```
+links notes_reg notes_star images images_no_dim
+```
+
+## 7. Grammar
+
+,**This grammar is complete for the file shape and deliberately incomplete
+for one thing: the order of properties.** A grammar that fixed the order
+would have to enumerate 42 optional terms in sequence, would be unreadable,
+and would need editing at every minor version, which is exactly when a
+property is added. The order is a guarantee of the format (section 6.3) and
+is stated there, where it can be read; a parser that wants to check it can
+do so against the table.
+
+So: **a file that this grammar accepts and section 6.3 rejects is a
+malformed file, not an ambiguity in the format.** The grammar is the shape;
+the table is the contract.
+
+,**Checked**: every line of the 36 document reference collection matches one
+of the eight line shapes below, 721,363 lines with none left over.
+
+```peg
+Document <- Header Source Meta Make DocHas Section* EOF
+Header <- "% SiSU Document Abstraction v" Version EOL
+ "% Source: " Value EOL Blank
+Version <- Digit+ "." Digit+
+
+Source <- "@source {" EOL Pair+ "}" EOL Blank
+Meta <- "@meta {" EOL Pair* "}" EOL Blank
+Make <- "@make {" EOL Pair* "}" EOL Blank
+DocHas <- "@doc_has {" EOL Pair+ "}" EOL Blank
+Pair <- " " Key ": " Value EOL
+Key <- [a-z_]+ ("." [a-z_]+)?
+
+Section <- "@" SectionName " {" EOL Blank Object* "}" EOL Blank
+SectionName <- "head" / "toc" / "body" / "endnotes" / "glossary"
+ / "bibliography" / "bookindex" / "blurb" / "tail"
+
+Object <- Decl Property* TextLine* Blank
+Decl <- "[" Digit+ "] " (Heading / Kind) EOL
+Heading <- "heading :" Level (" " Identifier)?
+Level <- [A-D] / [1-4]
+Kind <- [a-z]+
+Property <- "." Name ": " Value EOL
+Name <- [a-z_0-9]+
+TextLine <- "| " Value EOL
+
+# a repeatable property appears once per value rather than carrying a list:
+# .image .stow_link .lev4_subtoc .anchor_tag
+# and .image has an inner shape of its own:
+Image <- ".image: " FileName (" " Field)* EOL
+Field <- Key ":" Value
+FileName <- (!" " !EOL .)+
+
+Value <- (!EOL .)*
+Blank <- EOL
+EOL <- "\n"
+Digit <- [0-9]
+```
+
+## 8. Conformance
+
+### 8.1 A reader must
+
+- **Check the major version** on the first line and refuse a major it does
+ not know. Loading an unknown major half populated, in silence, is the
+ failure this rule exists to prevent.
+- **Tolerate unknown properties** within a known major version, since the
+ minor part is raised precisely by adding them. Ignoring them is
+ conforming behaviour.
+- **Treat `[0]` as not an identity.** Objects with no citation number are
+ numerous and share the number.
+- **Stop at `.parent: 0`** when walking upward.
+
+### 8.2 A reader should
+
+- **Report what it ignored**, at least on request. A reader that silently
+ drops what it does not understand cannot tell its user whether it
+ understood the document, and cannot be used to check this specification
+ against an implementation.
+
+### 8.3 A writer must
+
+- Emit the blocks and sections in the order of section 4, an object's
+ properties in the order of section 6.3, and objects in document order.
+- Omit a property holding its default, per section 6.3.
+- Escape only what section 3.1 requires, and only where it requires it.
+
+## 9. Relationship to the model, and to the sqlite serialisation
+
+The model this format writes down is specified in
+[`ocda-model.md`](ocda-model.md): objects, citation numbers, structure,
+sections, segments and digests. This document adds nothing to the model and
+subtracts nothing from it; it says how the model is written as text.
+
+The `.ocda.db` is the same abstraction as sqlite, and is **built by reading
+a `.ssp` back**: the document is emitted as `.ssp`, read straight in, and
+what comes back is written. So the database cannot carry an object property
+this format cannot express, and the two cannot drift. They share the
+version, which is why a bump moves both.
+
+The database is not a competitor to this format. It carries every language
+of a document in one file, and the markup, images and configuration as
+well, which this format does not.
+
+## 10. Worked examples
+
+- `example-autonomous-contract.ssp` - one document, complete and unedited.
+- `example-wealth-of-networks.ssp` - an excerpt of a large one: verbatim
+ lines with marked elisions, keeping the preamble, the `@head` section,
+ and a run of body objects including one that embeds an image.
+
+Each carries, in its opening comments, the command that regenerates it.
+#+END_SRC
+
+** ocda-db-format-specification.md
+
+#+HEADER: :tangle ../ocda-db-format-specification.md
+#+BEGIN_SRC md
+# The `.ocda.db` format
+
+,**The object-centric document abstraction, written as sqlite. Format
+version 2.1**, as spine emits and reads it after 0.25.1.
+
+This document specifies *one serialisation*. The model it serialises is
+specified in [`ocda-model.md`](ocda-model.md), which the text serialisation
+shares; read that first if the question is what an object *is* rather than
+how it is stored.
+
+## Status
+
+Derived from the writer, `sisudoc/outputs/io_out/sqlite_ocda_db.d`, and
+checked against the 27 published databases of the project's reference
+collection. Where the two could differ the writer is normative and this
+document is wrong.
+
+## 1. What it is, and what makes it different
+
+One file per **document**, holding **every language of it**: a ten language
+document is one database with ten rows in `documents`, written one language
+at a time into the one file.
+
+Two things distinguish it from the `.ssp`:
+
+- **It carries its own source.** The markup, the images, `conf/document_make`,
+ `pod.manifest` and the `tools/po4a` catalogues are all inside it, in the
+ `files` table. A pod can be written back out of it, and spine does exactly
+ that when asked for an artefact that needs markup. The `.ssp` names its
+ images and carries none of them.
+- **It is queryable without being parsed.** A question about the document is
+ a SELECT, answered from the file with no spine and no reader.
+
+### 1.1 It is built from the `.ssp`
+
+The document is emitted as `.ssp`, **read straight back**, and what comes
+back is what is written. So **the database cannot carry an object property
+the `.ssp` cannot express**, and the two cannot drift. That is also why they
+share one version number: a bump moves both.
+
+The carried *files* are the deliberate exception. They come from the pod
+rather than from the abstraction, each with its digest.
+
+## 2. Version
+
+Declared in band, in the `metadata` table:
+
+```sql
+SELECT key, value FROM metadata WHERE doc_id IS NULL;
+-- build.spine_version | 0.25.0
+-- schema.name | sisu-abstraction-db
+-- schema.version | 2.1
+```
+
+The rule is the model's, and identical to the `.ssp`: the minor part is
+raised when a property is added, the major when one changes meaning or goes
+away, and **a reader checks the major part and refuses what it does not
+know**. See [`ssp-format-specification.md`](ssp-format-specification.md)
+section 2 for the history, which is shared.
+
+## 3. The schema
+
+Eight tables, one virtual table, three views.
+
+```
+ documents id, lang, source_filename, ssp_digest UNIQUE(lang)
+ │ doc_id
+ ├─ metadata doc_id, key, value UNIQUE(doc_id, key)
+ │
+ └─ objects id, doc_id, section, seq, ocn, ... 50 columns
+ UNIQUE(doc_id, section, seq)
+ ├─ object_images object_id, seq, name, bytes, sha256,
+ │ width, height, missing
+ ├─ object_links object_id, seq, url
+ ├─ object_anchors object_id, seq, anchor
+ └─ object_subtoc object_id, seq, entry
+
+ files id, role, name, bytes, sha256, width, height,
+ compression, data UNIQUE(role, name)
+
+ objects_fts fts5 over objects.text, external content over objects.id
+```
+
+### 3.1 `doc_id` is the language key
+
+`documents.id`, referred to as `doc_id` everywhere else, is **what tells one
+language's rows from another's**. It is the key to reach for in every query.
+
+`objects.lang` and `objects.meta_lang` are **properties of the object** and
+are not it. They are almost always empty (section 6).
+
+### 3.2 The file-level metadata rows
+
+`metadata` is keyed `UNIQUE(doc_id, key)` and not on key alone, because
+every language has a title and a creator and a key-only key would refuse the
+second.
+
+Three rows describe **the file** rather than a document in it, and are
+written with `doc_id` null: `schema.name`, `schema.version` and
+`build.spine_version`. In SQL no null equals another null, so
+`UNIQUE(doc_id, key)` does not constrain them, and a partial unique index
+over `key` alone `WHERE doc_id IS NULL` is what makes them singular.
+
+#### 3.2.1 The key prefix carries what the `.ssp` puts in blocks
+
+The `.ssp` has four preamble blocks, `@source`, `@meta`, `@make` and
+`@doc_has`. The database has **one** `metadata` table, and tells them apart
+by a **prefix on the key**:
+
+| `.ssp` block | database key |
+|--------------|-----------------------------------------------------------|
+| `@meta` | the key as it stands: `title.main`, `creator.author`, ... |
+| `@make` | `make.` + the key: `make.footer`, `make.doc_type` |
+| `@doc_has` | `doc_has.` + the key: `doc_has.images`, `doc_has.tables` |
+| `@source` | `source.` + the key: `source.language`, `source.digest` |
+
+,**A reader must strip the prefix and restore the grouping**, or a writer
+over it has to ask `metadata["make.footer"]` from a database and
+`make["footer"]` from a `.ssp`, which is exactly the difference the two
+serialisations exist not to make.
+
+`source.` also carries two keys with no `@source` counterpart,
+`source.filename` and `source.ssp_digest`; the `.ssp` puts the first in its
+`% Source:` comment and cannot hold the second, which is a digest *of* it.
+
+Values may carry leading or trailing whitespace here where the `.ssp`
+cannot represent it, its `key: value` line being unable to distinguish a
+value that begins with a space from the separator. **Strip on load**, as a
+reader of the text form necessarily does.
+
+### 3.3 Fixed-width arrays are JSON
+
+`children`, `ancestors`, `ancestors_collapsed`, `dom_status`,
+`dom_status_collapsed`, `heading_ancestors_text`, `table_widths` and
+`table_aligns` are stored as **JSON arrays**, with validity checks, so that
+`json_extract`, `json_each` and `json_array_length` reach inside them.
+
+> **Parse them as JSON.** A scan that strips `[`, `]`, `,` and `"` looks
+> adequate and is wrong on the first escape: the encoder writes `/` as
+> `\/`, so `FREE/OPEN-SOURCE SOFTWARE` comes back as
+> `FREE\/OPEN-SOURCE SOFTWARE`. All 36 document-languages of the reference
+> collection contain at least one, and the defect is invisible to any check
+> that does not compare the field itself.
+>
+> Note also that `table_widths` is an array of **integers except where the
+> columns divide evenly**, when it is `[33.3333,33.3333,33.3333]`. A decoder
+> that accepts strings and integers and then falls back to a default turns
+> a value it could not read into one that looks read.
+
+The **element types**, so that a decoder can be written to accept exactly
+what occurs:
+
+| column | elements |
+|--------------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers |
+| `table_widths` | integers, or floats where the columns divide evenly |
+| `table_aligns` | strings, one of `l` `c` `r` |
+| `heading_ancestors_text` | strings, eight of them, empty where that level is not an ancestor |
+
+The `.ssp` writes the first three groups **space separated** and
+`heading_ancestors_text` **`|` separated**. The empty slots of the last are
+significant: they say which levels a heading sits under, so the separators
+carry as much as the text does.
+
+The open-ended lists are **rows in the four child tables** instead of
+columns: images, links, anchor tags and sub-table-of-contents entries. Each
+child table carries `seq`, which preserves the order they appeared in.
+
+### 3.4 Indexes
+
+`objects(doc_id, section)`, `objects(ocn)`, `objects(parent_ocn)`,
+`objects(is_a)`, `objects(heading_level)` where it is a heading, and
+`files(role)`, `object_images(name)`.
+
+## 4. The relationship to the `.ssp`, column by column
+
+,**Nothing is lost in either direction.** Every `.ssp` property is a column
+or a child table; every column is a property, a value from the object
+declaration line, or a database key.
+
+Where the names differ they differ for a reason, the `.ssp` preferring the
+short form and the database the explicit one:
+
+| `.ssp` property | database |
+|--------------------|-----------------------|
+| `.parent` | `parent_ocn` |
+| `.last_descendant` | `last_descendant_ocn` |
+| `.dummy` | `dummy_heading` |
+| `.ocn_off` | `object_number_off` |
+| `.part` | `is_of_part` |
+| `.section` | `is_of_section` |
+
+Three are **expanded**, the `.ssp` folding what the database spreads:
+
+| `.ssp` property | database |
+|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| `.indent: <base> <hang>` | `indent_base`, `indent_hang` |
+| `.ocn_range: <first> <last>` | `ocn_range_first`, `ocn_range_last` (2.1: `0` where the object is not a container; a 2.0 database has neither column, and reads as no range) |
+| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` |
+
+The four **repeatable** properties become the four child tables:
+
+| `.ssp` property | database |
+|-----------------|------------------|
+| `.image` | `object_images` |
+| `.stow_link` | `object_links` |
+| `.anchor_tag` | `object_anchors` |
+| `.lev4_subtoc` | `object_subtoc` |
+
+And four columns come from outside the property list: `ocn`, `is_a` and
+`heading_level` from the object declaration line, and `text` from its `|`
+lines. `id`, `doc_id` and `seq` are the database's own keys; `seq` is the
+object's position within its section, and `(doc_id, section, seq)` is what
+identifies an object when `ocn` will not: `0`, or, before 2.1, a poem
+sharing its last verse's number (see [`ocda-model.md`](ocda-model.md)
+section 3).
+
+### 4.1 Where the two are not symmetric
+
+"Nothing is lost in either direction" is true of the model, and there are
+three places where the *files* nonetheless differ. A reader must know all
+three, because each of them made two independently written readers disagree.
+
+,**1. The database states what the `.ssp` derives.** `identifier` and
+`anchor` are written on every row. The `.ssp` omits each where it can be
+worked out, the identifier being the ocn and the anchor the segment name
+(sections 6.1 and 6.3 of
+[`ssp-format-specification.md`](ssp-format-specification.md), section 9 of
+[`ocda-model.md`](ocda-model.md)). In `free_culture.lawrence_lessig` that is
+,**1,314 identifiers and 69 anchors** stated here and absent there. Neither
+file is the poorer; a reader that does not derive is.
+
+,**2. `translation.ocn_aligned` is here and cannot be in a `.ssp`.** It says
+whether the languages of a document share one numbering, and a `.ssp` is one
+language. It is therefore a fact about **the file**, not about the document
+in it, and it is the one such fact either serialisation carries.
+
+A reader should **keep it out of the document model**, for the same reason
+the `schema.*` and `build.*` rows are kept out: a writer over the model must
+not be able to tell which serialisation it was handed, and a field that
+exists only when the input was a database is exactly that tell. The model
+has no place for collection-wide facts yet; when it grows one, this belongs
+there.
+
+,**3. Whitespace and grouping**, as section 3.2.1 gives them.
+
+## 5. The `files` table: what it carries, and how
+
+| role | named by | `compression` | `data` holds |
+|------------|----------------------------|---------------|------------------|
+| `image` | its bare filename | `none` | the file as read |
+| `source` | `media/text/<lang>/<file>` | `zstd` | a zstd frame |
+| `conf` | `conf/document_make` | `zstd` | a zstd frame |
+| `manifest` | `pod.manifest` | `zstd` | a zstd frame |
+| `tools` | `tools/po4a/...` | `zstd` | a zstd frame |
+
+The `compression` column carries the literal `none` or `zstd`, so a reader
+need not infer it from the role.
+
+Three rules make the file predictable:
+
+1. **Compression is decided by role, never by size.** The same kind of file
+ always stores the same way, so nobody need measure a document to know
+ what its database will look like. A very small file can come out a few
+ bytes larger inside a zstd frame; that is accepted rather than fixed with
+ a threshold, which would make two documents of the same kind store
+ differently for no reason a reader could see.
+2. **Images are not compressed.** png and jpeg are compressed already; zstd
+ gains nothing and costs a decompression on every read.
+3. **`objects.text` is never compressed.** The full text index reads that
+ column directly, and compressing it would stop search working completely
+ rather than subtly.
+
+,**`bytes` and `sha256` are always those of the original file**, whatever
+`compression` says. So a digest check, a `digests.txt` line and a rebuilt
+`source.digest` all keep working, and a reader that does not decompress can
+still say what it is looking at.
+
+## 6. Querying it
+
+`sqlite3` is all that is needed. The recipes below were run against the
+published databases.
+
+### 6.1 What is this file
+
+```sql
+SELECT key, value FROM metadata WHERE doc_id IS NULL;
+SELECT id, lang, source_filename FROM documents ORDER BY id;
+SELECT role, count(*), sum(bytes) FROM files GROUP BY role;
+```
+
+### 6.2 The views
+
+| view | gives |
+|------------------|---------------------------------------------------------------------------------------------|
+| `outline` | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text |
+| `citable` | every object with an ocn, ordered by ocn, language named |
+| `document_files` | what the file carries: role, name, bytes, sha256, pixel size |
+
+,**`outline` and `citable` name the language and order by it first.** A view
+over a file that may hold ten languages and does not say which would read as
+one document and be several.
+
+,**A trap in `citable`:** it is `SELECT d.lang AS lang, o.*`, and `objects`
+has a `lang` column of its own, so sqlite renames the second one. The view
+has **`lang`, the document's language, and `lang:1`, the object's own**.
+Quote the second if you want it: `SELECT "lang:1" FROM citable`.
+
+### 6.3 Structure
+
+A heading's subtree is a **range**, not a traversal, because every heading
+carries `last_descendant_ocn`:
+
+```sql
+SELECT count(*) FROM objects o,
+ (SELECT doc_id, ocn, last_descendant_ocn FROM objects
+ WHERE is_a='heading' AND ocn=66) h
+ WHERE o.doc_id = h.doc_id
+ AND o.ocn BETWEEN h.ocn AND h.last_descendant_ocn;
+```
+
+And the path back up, on `parent_ocn`:
+
+```sql
+WITH RECURSIVE up(ocn, parent_ocn, text) AS (
+ SELECT ocn, parent_ocn, text FROM objects WHERE doc_id=1 AND ocn=345
+ UNION ALL
+ SELECT o.ocn, o.parent_ocn, o.text FROM objects o
+ JOIN up ON o.ocn = up.parent_ocn AND o.doc_id=1 AND o.is_a='heading'
+ WHERE up.parent_ocn > 0)
+SELECT ocn, substr(text,1,44) FROM up;
+```
+
+,**Keep the `parent_ocn > 0` guard.** A parent of 0 is a real,
+non-substantive parent and not a missing value, and without the guard the
+recursion does not terminate.
+
+### 6.4 Full text
+
+```sql
+SELECT o.ocn, substr(o.text,1,44) FROM objects_fts f
+ JOIN objects o ON o.id = f.rowid
+ JOIN documents d ON d.id = o.doc_id
+ WHERE f.text MATCH 'commons' AND d.lang='en' AND o.ocn > 0
+ ORDER BY rank LIMIT 3;
+```
+
+fts5 syntax is available in full: `MATCH 'peer AND production'`,
+`MATCH '"peer production"'`, `MATCH 'peer NEAR production'`.
+
+The index is **external content** over `objects.id`: the text is indexed,
+not stored twice.
+
+### 6.5 Three things to know before trusting a query
+
+1. **An ocn is not unique within a document**, and `0` is shared by many
+ objects. Key on `objects.id`, or on `(doc_id, section, seq)`.
+2. **`objects.text` is internal markup**, neither the author's markup nor
+ any output. Fine for search and for reading structure, not for display
+ without decoding. The markers are in
+ [`ssp-format-specification.md`](ssp-format-specification.md) section 3.2.
+3. **A multi-language file answers an unfiltered query with every language
+ at once.** A single-language document has one `documents` row, so plain
+ queries read naturally there; anything else wants `WHERE lang='..'` or a
+ join to `documents`.
+
+## 7. Digests, and verifying a file
+
+```
+the markup files ──> metadata source.digest sha256 over every markup file
+ of that language
+the .ssp ──> documents.ssp_digest of the .ssp it was built from
+each object ──> objects.sha256 over the object's text
+each carried file──> files.sha256 over the original bytes
+the spine used ──> metadata build.spine_version
+```
+
+So `.sst -> .ssp -> .ocda.db` is checkable end to end, and
+`spine --ocda-verify=<file>` closes the loop by writing the carried markup
+back out and re-parsing it: **does this spine still make this abstraction
+from the markup this file carries?** It writes nothing and the exit status
+is the answer.
+
+,**Only this artefact can answer that from itself alone**, which is the
+strongest sense in which it is the one to work with.
+
+The database's own digest is taken once, when the last language has been
+written, and appears in `digests.txt`. The metadata page links the database
+and claims no hash for it, deliberately: the page is written per language
+while the database is added to per language, so a digest taken there would
+be of a file that no longer exists by the end of the run.
+
+## 8. Conformance
+
+A reader **must** check `schema.version`'s major part and refuse a major it
+does not know; **must** treat `ocn` as not an identity; **must** stop at
+`parent_ocn = 0` when walking upward; and **should** say what it did not
+understand, for the reason given in
+[`ssp-format-specification.md`](ssp-format-specification.md) section 8.2.
+
+A writer **must** keep `bytes` and `sha256` those of the original file
+whatever `compression` says, and **must not** compress `objects.text`.
+#+END_SRC
+
+* COPYRIGHT & LICENSE
+** notices
+*** project (project root) ./
+
+#+HEADER: :tangle "../COPYRIGHT"
+#+HEADER: :noweb yes
+#+BEGIN_SRC org
+- Name: spine - SiSU Spine, Doc Reform
+ <<sisudoc_spine_copyright>>
+
+ <<sisudoc_spine_license_agpl3>>
+
+ <<sisudoc_spine_summary>>
+
+<<sisudoc_spine_markup_samples>>
+#+END_SRC
+
+*** code org ./org
+
+- .org literate programming:
+ - copyright asserted
+ - omitted
+ - license
+ - dependency information
+
+#+HEADER: :tangle "../org/COPYRIGHT"
+#+HEADER: :noweb yes
+#+BEGIN_SRC text
+- Name: spine - SiSU Spine, Doc Reform
+ <<sisudoc_spine_copyright>>
+
+ <<sisudoc_spine_license_agpl3>>
+
+ <<sisudoc_spine_summary>>
+
+<<sisudoc_spine_markup_samples>>
+#+END_SRC
+
+** incorporate
+*** copyright
+
+#+NAME: sisudoc_spine_copyright
+#+BEGIN_SRC emacs-lisp
+<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_copyright()>>
+#+END_SRC
+
+*** agpl3
+
+#+NAME: sisudoc_spine_license_agpl3
+#+BEGIN_SRC emacs-lisp
+<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_license_agpl3()>>
+#+END_SRC
+
+*** spine_summary
+
+#+NAME: sisudoc_spine_summary
+#+BEGIN_SRC emacs-lisp
+<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_summary()>>
+#+END_SRC
+
+*** markup_samples
+
+#+NAME: sisudoc_spine_markup_samples
+#+BEGIN_SRC emacs-lisp
+<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_markup_samples()>>
+#+END_SRC
+
+* org includes
+** project version
+
+#+NAME: spine_version
+#+HEADER: :noweb yes
+#+BEGIN_SRC emacs-lisp
+<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:spine_project_version()>>
+#+END_SRC
+
+** year
+
+#+NAME: year
+#+HEADER: :noweb yes
+#+BEGIN_SRC emacs-lisp
+<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:year()>>
+#+END_SRC
+
+** document header including copyright & license
+
+#+NAME: doc_header_including_copyright_and_license
+#+HEADER: :noweb yes
+#+BEGIN_SRC emacs-lisp
+<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:spine_doc_header_including_copyright_and_license()>>
+#+END_SRC
+
+* nixpkgs source
+
+#+NAME: nixpkgs_unstable
+#+HEADER: :noweb yes
+#+BEGIN_SRC emacs-lisp
+<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:nixpkgs_unstable()>>
+#+END_SRC
+
+* __END__
diff --git a/claude-org/sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org b/claude-org/sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org
new file mode 100644
index 0000000..5ec2d52
--- /dev/null
+++ b/claude-org/sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org
@@ -0,0 +1,252 @@
+-*- mode: org -*-
+#+TITLE: sisudoc spine (doc_reform) object-centric document abstraction
+#+DESCRIPTION: documents - structuring, publishing in multiple formats & search
+#+FILETAGS: :spine:abstraction:
+#+AUTHOR: Ralph Amissah
+#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
+#+COPYRIGHT: Copyright (C) 2015 (continuously updated, current 2026) Ralph Amissah
+#+LANGUAGE: en
+#+STARTUP: content hideblocks hidestars noindent entitiespretty
+#+PROPERTY: header-args+ :eval never-export :exports code
+#+PROPERTY: header-args+ :noweb yes :padline no
+#+PROPERTY: header-args+ :results silent :cache no
+#+PROPERTY: header-args+ :mkdirp yes
+#+OPTIONS: H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t
+
+- [[./doc-reform.org][doc-reform.org]] [[./][org/]]
+
+* spine doc header including copyright & license
+
+#+NAME: spine_doc_header_including_copyright_and_license
+#+BEGIN_SRC org
+/+
+- Name: SisuDoc Spine, Doc Reform [a part of]
+ - Description: documents, structuring, processing, publishing, search
+ - static content generator
+
+ - Author: Ralph Amissah
+ [ralph.amissah@gmail.com]
+
+ - Copyright: (C) 2015 (continuously updated, current 2026) Ralph Amissah, All Rights Reserved.
+
+ - License: AGPL 3 or later:
+
+ Spine (SiSU), a framework for document structuring, publishing and
+ search
+
+ Copyright (C) Ralph Amissah
+
+ This program is free software: you can redistribute it and/or modify it
+ under the terms of the GNU AFERO General Public License as published by the
+ Free Software Foundation, either version 3 of the License, or (at your
+ option) any later version.
+
+ This program is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ more details.
+
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see [https://www.gnu.org/licenses/].
+
+ If you have Internet connection, the latest version of the AGPL should be
+ available at these locations:
+ [https://www.fsf.org/licensing/licenses/agpl.html]
+ [https://www.gnu.org/licenses/agpl.html]
+
+ - Spine (by Doc Reform, related to SiSU) uses standard:
+ - docReform markup syntax
+ - standard SiSU markup syntax with modified headers and minor modifications
+ - docReform object numbering
+ - standard SiSU object citation numbering & system
+
+ - Homepages:
+ [https://www.sisudoc.org]
+ [https://www.doc-reform.org]
+
+ - Git
+ [https://git.sisudoc.org/]
+
++/
+#+END_SRC
+
+** incorporate
+*** copyright
+
+#+NAME: sisudoc_spine_copyright
+#+BEGIN_SRC org
+- Description: documents, structuring, processing, publishing, search
+ - static content generator
+
+- Author: Ralph Amissah
+ [ralph.amissah@gmail.com]
+
+- Copyright: (C) 2015 - 2026 Ralph Amissah
+#+END_SRC
+
+*** license
+**** AGPLv3
+
+#+NAME: sisudoc_spine_license_agpl3
+#+BEGIN_SRC org
+- code under src/* src/sisudoc/*
+ - License: AGPL 3 or later:
+
+ Spine, Doc Reform (SiSU), a framework for document structuring, publishing and
+ search
+
+ Copyright (C) Ralph Amissah
+
+ This program is free software: you can redistribute it and/or modify it
+ under the terms of the GNU AFERO General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or (at your
+ option) any later version.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ for more details.
+
+ You should have received a copy of the GNU General Public License along
+ with this program. If not, see [https://www.gnu.org/licenses/].
+
+ If you have Internet connection, the latest version of the AGPL should be
+ available at these locations:
+ [https://www.fsf.org/licensing/licenses/agpl.html]
+ [https://www.gnu.org/licenses/agpl.html]
+#+END_SRC
+
+*** spine_summary
+
+#+NAME: sisudoc_spine_summary
+#+BEGIN_SRC org
+- Spine, Doc Reform (related to SiSU) uses standard:
+ - docReform markup syntax (based on SiSU markup)
+ - standard SiSU markup syntax with modified headers and minor
+ modifications
+ - docReform object numbering (based on SiSU object citation numbering)
+ - standard SiSU document object numbering
+
+- Homepages:
+ [https://www.sisudoc.org]
+#+END_SRC
+
+#+BEGIN_SRC org
+ - Homepages:
+ [https://www.sisudoc.org]
+ [https://www.sisudoc.org]
+
+ - Git
+ []
+#+END_SRC
+
+*** markup_samples
+
+#+NAME: sisudoc_spine_markup_samples
+#+BEGIN_SRC org
+- Spine, Doc Reform (SiSU) markup samples
+ Individual document content Copyright (Author) [as stated in document header]
+ Individual document content License (Author) [as stated in document header]
+#+END_SRC
+
+* spine version info SET VERSION
+** version in full
+
+#+NAME: spine_project_version
+#+BEGIN_SRC org
+<<spine_project_version_part_major>>.<<spine_project_version_part_minor>>.<<spine_project_version_part_patch>>
+#+END_SRC
+
+** version parts (major, minor, patch)
+
+#+NAME: spine_project_version_major_minor_patch
+#+BEGIN_SRC org
+<<spine_project_version_part_major>>, <<spine_project_version_part_minor>>, <<spine_project_version_part_patch>>
+#+END_SRC
+
+*** major
+
+#+NAME: spine_project_version_part_major
+#+BEGIN_SRC org
+0
+#+END_SRC
+
+*** minor
+
+#+NAME: spine_project_version_part_minor
+#+BEGIN_SRC org
+25
+#+END_SRC
+
+*** patch
+
+#+NAME: spine_project_version_part_patch
+#+BEGIN_SRC org
+2
+#+END_SRC
+
+* year
+
+#+NAME: year
+#+BEGIN_SRC org
+2026
+#+END_SRC
+
+* sisudoc spine git source SET
+** sisudoc-spine src
+
+#+NAME: sisudoc_spine_nix_src
+#+BEGIN_SRC org
+git://git.sisudoc.org/software/sisudoc-spine
+#+END_SRC
+
+** dlang overlay src
+
+#+NAME: sisudoc_dlang_nix_overlay_src
+#+BEGIN_SRC org
+git://git.sisudoc.org/package/dlang-nix-overlays-and-flake
+#+END_SRC
+
+* ocda ssp version format SET
+** ocda ssp version in full
+
+#+NAME: ocda_ssp_format_version
+#+BEGIN_SRC org
+<<ocda_ssp_format_version_part_major>>.<<ocda_ssp_format_version_part_minor>>
+#+END_SRC
+
+** parts
+*** major
+
+#+NAME: ocda_ssp_format_version_part_major
+#+BEGIN_SRC org
+2
+#+END_SRC
+
+*** minor
+
+#+NAME: ocda_ssp_format_version_part_minor
+#+BEGIN_SRC org
+1
+#+END_SRC
+
+* sqlite collection search db schema version
+
+#+NAME: sqlite_collection_search_db_schema_version
+#+BEGIN_SRC org
+1
+#+END_SRC
+
+* nipkgs source
+
+- github:NixOS/nixpkgs/nixpkgs-unstable
+- https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.zst
+
+#+NAME: nixpkgs_unstable
+#+BEGIN_SRC org
+https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.zst
+#+END_SRC
+
+#+BEGIN_SRC org
+github:NixOS/nixpkgs/nixpkgs-unstable
+#+END_SRC
diff --git a/ssp-format-specification.md b/ssp-format-specification.md
index a401947..6ac0030 100644
--- a/ssp-format-specification.md
+++ b/ssp-format-specification.md
@@ -77,6 +77,12 @@ row, so that one bump moves both.
away**.
- A reader **checks the major part and refuses what it does not know**,
rather than loading an unfamiliar artefact half populated in silence.
+- A **patch** part, the third, numbers *releases* and not the format: a
+ correction or clarification of this text, or a fix in a program that
+ implements it, changes nothing a file can contain. So a file declares
+ `major.minor` only, and a release is `major.minor.patch`. The
+ specification and the programs that implement it share `major.minor`,
+ which is the format, and each numbers its own patches.
### 2.2 History
@@ -87,6 +93,17 @@ row, so that one bump moves both.
| 1.1 | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`. |
| 0.1 | | The first form. |
+### 2.3 Releases of this specification
+
+| release | format | what |
+|---------|--------|---------------------------------------------------------------------|
+| 2.0.0 | 2.0 | the model and the `.ssp` |
+| 2.0.1 | 2.0 | the object kinds and types, the levels, the make block, the markers |
+| 2.0.2 | 2.0 | the `.ocda.db`; two rules a validator found unstated |
+| 2.0.3 | 2.0 | the derived values: the identifier and the anchor |
+| 2.1.0 | 2.1 | `.ocn_range`, and the editor's notes |
+| 2.1.1 | 2.1 | the patch part of a release number, and this table |
+
## 3. Lexical structure
Six line types, distinguished by their first character. Nothing else is a