summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-10-13 16:54:02 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-13 16:54:02 -0400
commitbb28568715e9feabfd7ee357d4802dd0d251bbac (patch)
treefb3395673a2351462189674047e058e44bedd4d3
parentformat 2.1: on poems and editor's notes (diff)
2.1.1: the patch part of a release number; the readers namedclaude-spec-matchup
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. A patch changes nothing a file can contain - a correction or clarification of this text, or a fix in a program - so a file declares major.minor only, as it always has, and spine and every reader are unaffected. Section 2.1 of the .ssp specification says so, beside the rule for the minor and major parts, and a new 2.3 lists the releases of this text: 2.0.0 the model and the .ssp, 2.0.1 the kinds, types, levels, make block and markers, 2.0.2 the .ocda.db and two rules a validator found, 2.0.3 the derived values, 2.1.0 .ocn_range and the editor's notes, 2.1.1 this. The README's version section says it in brief. The README's related projects name the first readers, sisudoc-ssp-reader and sisudoc-ocda-db-reader, published frozen as the record of readers written from this specification alone, their work now done by ocda-read in sisudoc-ocda-lib. claude-org/: ocda_specification.org with the same changes, so that it tangles every document exactly as committed, and the version and header file with its two local git+file blocks taken out; proposed replacements for their org/ counterparts. (assisted by Claude-Code) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
-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