<feed xmlns='http://www.w3.org/2005/Atom'>
<title>sisudoc-abstraction-format, branch claude-v2</title>
<subtitle>SiSU Spine: specs</subtitle>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/'/>
<entry>
<title>specs</title>
<updated>2026-10-01T16:59:10+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-10-01T16:59:10+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=16d97215e4fd46a5d190776d3fe1c126701176c3'/>
<id>16d97215e4fd46a5d190776d3fe1c126701176c3</id>
<content type='text'>
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
</pre>
</div>
</content>
</entry>
<entry>
<title>format 2.1: an editor's note is a note, and a note's three marks</title>
<updated>2026-09-29T21:57:00+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-29T21:57:00+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=78556648cc6055296072c062dd9fa2d7e6371b87'/>
<id>78556648cc6055296072c062dd9fa2d7e6371b87</id>
<content type='text'>
Spine now recognises the markup's editor's notes, ~[* ]~ and ~[+ ]~,
which it had passed through as text, and writes them as notes of their
own numbered series: *1, *2 ... and +1, +2 ..., each through the
document, apart from the author's notes. So a note mark now has three
forms, and a reader must take all three: digits, the author's notes;
symbols alone, the special notes; a symbol and digits, the editor's
notes. Section 3.2 says so and gives the pattern; the history row for
2.1, the same unreleased version as the poem's range, records it.

The counts are recounted over the regenerated reference set: 135 more
endnotes, 2,294 in all, and the properties an endnote carries with
them.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5.5 &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
Spine now recognises the markup's editor's notes, ~[* ]~ and ~[+ ]~,
which it had passed through as text, and writes them as notes of their
own numbered series: *1, *2 ... and +1, +2 ..., each through the
document, apart from the author's notes. So a note mark now has three
forms, and a reader must take all three: digits, the author's notes;
symbols alone, the special notes; a symbol and digits, the editor's
notes. Section 3.2 says so and gives the pattern; the history row for
2.1, the same unreleased version as the poem's range, records it.

The counts are recounted over the regenerated reference set: 135 more
endnotes, 2,294 in all, and the properties an endnote carries with
them.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5.5 &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
<entry>
<title>format 2.1: a poem is a container, cited as the range of its verses</title>
<updated>2026-09-29T18:02:30+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-29T18:02:30+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=0cbfcb1de61217fc0a9d5d973d32f3c14a7648ac'/>
<id>0cbfcb1de61217fc0a9d5d973d32f3c14a7648ac</id>
<content type='text'>
.ocn_range, the first and last ocn of what a container holds, as one
.ssp property and two .ocda.db columns. A poem is the one container:
its verses are the citable units and the poem is not. It now comes
before its first verse, carries ocn 0 and no identifier, and states
the range, where it came after its last verse carrying that verse's
ocn and identifier, so that one number named two objects: 48 such
pairs in the reference collection, none now.

So the model can now say that a non-zero ocn is unique within a
document, and does, keeping the older rule for artefacts written
before 2.1. A minor bump: an addition, a poem was never rendered and
has no text, the verses are unchanged, and a 2.0 reader reads a 2.1
file.

The property-count table is recounted over the regenerated reference
set, the method first checked against the old set, which it
reproduces. The one new endnote, a note in a poem's last verse now
gathered, accounts for the other moved counts; the poems' segment
names account for .segment_html_is and .segment_epub_is. Neither
example holds a poem, so each changed by its version line alone.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5.5 &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
.ocn_range, the first and last ocn of what a container holds, as one
.ssp property and two .ocda.db columns. A poem is the one container:
its verses are the citable units and the poem is not. It now comes
before its first verse, carries ocn 0 and no identifier, and states
the range, where it came after its last verse carrying that verse's
ocn and identifier, so that one number named two objects: 48 such
pairs in the reference collection, none now.

So the model can now say that a non-zero ocn is unique within a
document, and does, keeping the older rule for artefacts written
before 2.1. A minor bump: an addition, a poem was never rendered and
has no text, the verses are unchanged, and a 2.0 reader reads a 2.1
file.

The property-count table is recounted over the regenerated reference
set, the method first checked against the old set, which it
reproduces. The one new endnote, a note in a poem's last verse now
gathered, accounts for the other moved counts; the poems' segment
names account for .segment_html_is and .segment_epub_is. Neither
example holds a poem, so each changed by its version line alone.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5.5 &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
<entry>
<title>the derived values, which the model left unstated</title>
<updated>2026-09-26T02:28:50+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-26T02:28:50+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=66692f33128cedf6b41f7c23cee0110882b4347b'/>
<id>66692f33128cedf6b41f7c23cee0110882b4347b</id>
<content type='text'>
The model says nothing about an object's identifier or its anchor, and
both are derived: the identifier is the ocn where there is one, the
anchor is the segment name. The .ssp omits each where it can be worked
out; the .ocda.db states both on every row. In one reference document
that is 1,314 identifiers and 69 anchors present from one serialisation
and absent from the other.

This is existing behaviour, not a new rule. Spine's own .ssp reader has
always filled both in, which is why the database carries them: the
database is written from the .ssp read straight back. It should have
been written down first. Two readers written independently from these
documents disagreed for want of it, on nearly every object, and nothing
short of comparing whole models showed it.

ocda-model.md gains 3.1 the identifier, 7.1 the anchor and 9 derived
values, with the loading rule in a table; "what the model does not hold"
becomes 10.

The two format specifications gain what a reader needs and did not have:

- the .ssp's property table now says what the absent value is, not only
  when it is written;
- the .ocda.db gains 3.2.1, the metadata key prefix that carries what
  the .ssp puts in four blocks, which a reader must strip to give one
  model from either file, and the note that a value here may carry
  whitespace the text form cannot represent;
- 3.3 gains the element types of each JSON column and a warning to
  parse rather than scan: the encoder writes "/" as "\/" and every
  document in the reference collection has a heading containing one;
- 4.1 names the three places the two files are not symmetric,
  including translation.ocn_aligned, which a .ssp cannot hold because
  it is one language, and which a reader should keep out of the
  document model so that nothing built on the model can tell which
  file it was given.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
The model says nothing about an object's identifier or its anchor, and
both are derived: the identifier is the ocn where there is one, the
anchor is the segment name. The .ssp omits each where it can be worked
out; the .ocda.db states both on every row. In one reference document
that is 1,314 identifiers and 69 anchors present from one serialisation
and absent from the other.

This is existing behaviour, not a new rule. Spine's own .ssp reader has
always filled both in, which is why the database carries them: the
database is written from the .ssp read straight back. It should have
been written down first. Two readers written independently from these
documents disagreed for want of it, on nearly every object, and nothing
short of comparing whole models showed it.

ocda-model.md gains 3.1 the identifier, 7.1 the anchor and 9 derived
values, with the loading rule in a table; "what the model does not hold"
becomes 10.

The two format specifications gain what a reader needs and did not have:

- the .ssp's property table now says what the absent value is, not only
  when it is written;
- the .ocda.db gains 3.2.1, the metadata key prefix that carries what
  the .ssp puts in four blocks, which a reader must strip to give one
  model from either file, and the note that a value here may carry
  whitespace the text form cannot represent;
- 3.3 gains the element types of each JSON column and a warning to
  parse rather than scan: the encoder writes "/" as "\/" and every
  document in the reference collection has a heading containing one;
- 4.1 names the three places the two files are not symmetric,
  including translation.ocn_aligned, which a .ssp cannot hold because
  it is one language, and which a reader should keep out of the
  document model so that nothing built on the model can tell which
  file it was given.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
<entry>
<title>README: the repository specifies both forms, not only the .ssp</title>
<updated>2026-09-25T20:14:15+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-25T20:14:15+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=7a29812add5e3171bb5060dea3858a152dd0d998'/>
<id>7a29812add5e3171bb5060dea3858a152dd0d998</id>
<content type='text'>
The opening described the .ssp alone, which was true when there was
one document and has not been since the model and the sqlite form
were written.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
The opening described the .ssp alone, which was true when there was
one document and has not been since the model and the sqlite form
were written.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
<entry>
<title>named sisudoc-abstraction-format</title>
<updated>2026-09-25T20:09:02+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-25T20:09:02+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=c860f61ac3aa5c804b6522a62798c3d6fad475dd'/>
<id>c860f61ac3aa5c804b6522a62798c3d6fad475dd</id>
<content type='text'>
Every published project of this family carries the sisu or sisudoc
prefix: sisudoc-spine, sisudoc-spine-samples, sisu-markup-samples.
This was the exception, and a specification is the thing most likely
to be cited by someone else, where "doc-abstraction-format" says
nothing about whose it is and invites confusion with any number of
other document abstractions.

The files inside keep their names: ocda-model.md,
ssp-format-specification.md, ocda-db-format-specification.md.  The
repository is the label a stranger meets first; the files are read
once inside, where the precise terms belong.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
Every published project of this family carries the sisu or sisudoc
prefix: sisudoc-spine, sisudoc-spine-samples, sisu-markup-samples.
This was the exception, and a specification is the thing most likely
to be cited by someone else, where "doc-abstraction-format" says
nothing about whose it is and invites confusion with any number of
other document abstractions.

The files inside keep their names: ocda-model.md,
ssp-format-specification.md, ocda-db-format-specification.md.  The
repository is the label a stranger meets first; the files are read
once inside, where the precise terms belong.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
<entry>
<title>the validator found two things the specification did not say</title>
<updated>2026-09-24T18:13:02+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-24T18:13:02+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=765df2e2cc2fd0686d3862eb6bc069df55477aad'/>
<id>765df2e2cc2fd0686d3862eb6bc069df55477aad</id>
<content type='text'>
Writing a validator from this document alone, as the test of whether
it suffices, turned up two rules that a reader needs and that were
implied rather than stated.

A repeated property occurrences are consecutive: the four repeatable
properties share one position in the order and nothing is written
between them.  Without that said, a validator checking order cannot
tell a legitimate repeat from a property out of place.

And no property follows the text: the record is declaration, then
properties, then text lines, and once a text line has been written no
further property appears.

Both hold over the whole reference collection, and both are now
stated with the check that establishes them.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
Writing a validator from this document alone, as the test of whether
it suffices, turned up two rules that a reader needs and that were
implied rather than stated.

A repeated property occurrences are consecutive: the four repeatable
properties share one position in the order and nothing is written
between them.  Without that said, a validator checking order cannot
tell a legitimate repeat from a property out of place.

And no property follows the text: the record is declaration, then
properties, then text lines, and once a text line has been written no
further property appears.

Both hold over the whole reference collection, and both are now
stated with the check that establishes them.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
<entry>
<title>gitignore</title>
<updated>2026-09-24T16:50:31+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-24T16:48:04+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=88435b3a06d19ff053fb9657af23408f4b9c03c5'/>
<id>88435b3a06d19ff053fb9657af23408f4b9c03c5</id>
<content type='text'>
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
</pre>
</div>
</content>
</entry>
<entry>
<title>the .ocda.db specified, and the two serialisations shown to agree</title>
<updated>2026-09-24T15:55:13+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-24T15:55:13+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=836b3c891f842a1cb78802103e9ff4acf9c57326'/>
<id>836b3c891f842a1cb78802103e9ff4acf9c57326</id>
<content type='text'>
The third document, derived from the writer and checked against the
27 published databases: eight tables, one virtual table, three views,
fifty columns on objects.

The claim worth making, and it is now checked rather than asserted:
nothing is lost in either direction between the two serialisations.
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.  The mapping is given in full.  Six properties are renamed, the
text form preferring the short name and the database the explicit
one; two are expanded, .indent into base and hang and .has into five
columns; and the four repeatable properties become the four child
tables.  That is the whole of the difference.

Which follows from how the database is made: the document is emitted
as .ssp, read straight back, and what comes back is written.  So the
database cannot carry an object property the .ssp cannot express, and
the two cannot drift.  It is also why they share one version number.

Traps recorded rather than left to be found:

- citable is SELECT d.lang AS lang, o.*, and objects has a lang
  column of its own, so the view carries lang, the document's, and
  lang:1, the object's.  Quote the second to select it.
- the three file-level metadata rows are the only ones with doc_id
  null, and in SQL no null equals another, so UNIQUE(doc_id, key)
  does not constrain them.  A partial unique index over key alone
  where doc_id is null is what keeps them singular.
- parent_ocn 0 is a real non-substantive parent, so a recursive walk
  upward needs the guard or it does not terminate.

The compression column carries the literal none or zstd, so a reader
need not infer it from the role; images are the role that is stored
as read, png and jpeg being compressed already.

Verified while writing: 8 tables and 3 views as described, the three
file-level rows, the partial index as quoted, every JSON array valid
(10,260 of 10,260 in live-manual), and compression by role including
image=none on a document that has images.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
The third document, derived from the writer and checked against the
27 published databases: eight tables, one virtual table, three views,
fifty columns on objects.

The claim worth making, and it is now checked rather than asserted:
nothing is lost in either direction between the two serialisations.
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.  The mapping is given in full.  Six properties are renamed, the
text form preferring the short name and the database the explicit
one; two are expanded, .indent into base and hang and .has into five
columns; and the four repeatable properties become the four child
tables.  That is the whole of the difference.

Which follows from how the database is made: the document is emitted
as .ssp, read straight back, and what comes back is written.  So the
database cannot carry an object property the .ssp cannot express, and
the two cannot drift.  It is also why they share one version number.

Traps recorded rather than left to be found:

- citable is SELECT d.lang AS lang, o.*, and objects has a lang
  column of its own, so the view carries lang, the document's, and
  lang:1, the object's.  Quote the second to select it.
- the three file-level metadata rows are the only ones with doc_id
  null, and in SQL no null equals another, so UNIQUE(doc_id, key)
  does not constrain them.  A partial unique index over key alone
  where doc_id is null is what keeps them singular.
- parent_ocn 0 is a real non-substantive parent, so a recursive walk
  upward needs the guard or it does not terminate.

The compression column carries the literal none or zstd, so a reader
need not infer it from the role; images are the role that is stored
as read, png and jpeg being compressed already.

Verified while writing: 8 tables and 3 views as described, the three
file-level rows, the partial index as quoted, every JSON array valid
(10,260 of 10,260 in live-manual), and compression by role including
image=none on a document that has images.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
<entry>
<title>second pass: kinds and types, levels, the make block, the markers</title>
<updated>2026-09-24T15:36:25+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-24T15:36:25+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=ab71dd00d862fd2c27ff11931931b9667e07d495'/>
<id>ab71dd00d862fd2c27ff11931931b9667e07d495</id>
<content type='text'>
The three gaps left in the first pass, closed the same way the rest
was: measured against the reference collection rather than described
from memory, which caught four wrong counts and two traps.

ocda-model.md

  The sixteen object kinds are now defined rather than listed, each
  with the section it belongs to and its weight in the collection,
  from para at 41,885 down to group at 16.  Only heading appears in
  all nine sections.

  Kind and type turn out to be two axes rather than one, and the
  second is the useful one for a renderer: is_of_type takes just
  three values, para, block and comment, saying whether the text may
  be reflowed.  The mapping from kind to type is fixed, so a reader
  that has the type need not know all sixteen kinds to lay text out.

  A section on levels, which the first pass assumed: eight of them,
  A to D for the title matter and 1 to 4 for the body, index 0 to 7,
  and that index is what the eight-slot arrays are indexed by.  A
  heading's own OCN sits in its own level's slot, checked over 3,432
  headings of 3,432.  Collapsed levels explained as what they are, an
  artefact of the markup removed.

ssp-format-specification.md

  The @make keys are described rather than named.  auto_num_top_at_
  level and auto_num_top_lv are the same value twice, as the markup
  wrote it and as an index.  breaks is a small language of its own,
  new= and break= over comma separated levels, and the levels are
  written there as the markup wrote them.

  The marker table is now the full set from InlineMarkup with counts
  from the collection, and the counting corrected four markers the
  first pass had at zero: the table separator at 695, the inline line
  break at 184, the corner brackets at 67, the spaced line break at
  50.

  Two traps found by counting.  The spaced line break and the table
  close are the same character, and the object kind is what resolves
  them: it occurs in group objects and never in a table.  And the
  corner brackets are not markers in a .ssp at all: they wrap an
  object number in ODT output, which happens after the abstraction,
  so their occurrences here are Japanese quotation marks in the
  document's own text.

  The grammar says what it does and does not fix, and why the order
  of properties is left to the table rather than enumerated as 42
  optional terms that would need editing at every minor version.
  Every line of the collection matches one of its eight line shapes,
  721,363 lines with none left over.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
The three gaps left in the first pass, closed the same way the rest
was: measured against the reference collection rather than described
from memory, which caught four wrong counts and two traps.

ocda-model.md

  The sixteen object kinds are now defined rather than listed, each
  with the section it belongs to and its weight in the collection,
  from para at 41,885 down to group at 16.  Only heading appears in
  all nine sections.

  Kind and type turn out to be two axes rather than one, and the
  second is the useful one for a renderer: is_of_type takes just
  three values, para, block and comment, saying whether the text may
  be reflowed.  The mapping from kind to type is fixed, so a reader
  that has the type need not know all sixteen kinds to lay text out.

  A section on levels, which the first pass assumed: eight of them,
  A to D for the title matter and 1 to 4 for the body, index 0 to 7,
  and that index is what the eight-slot arrays are indexed by.  A
  heading's own OCN sits in its own level's slot, checked over 3,432
  headings of 3,432.  Collapsed levels explained as what they are, an
  artefact of the markup removed.

ssp-format-specification.md

  The @make keys are described rather than named.  auto_num_top_at_
  level and auto_num_top_lv are the same value twice, as the markup
  wrote it and as an index.  breaks is a small language of its own,
  new= and break= over comma separated levels, and the levels are
  written there as the markup wrote them.

  The marker table is now the full set from InlineMarkup with counts
  from the collection, and the counting corrected four markers the
  first pass had at zero: the table separator at 695, the inline line
  break at 184, the corner brackets at 67, the spaced line break at
  50.

  Two traps found by counting.  The spaced line break and the table
  close are the same character, and the object kind is what resolves
  them: it occurs in group objects and never in a table.  And the
  corner brackets are not markers in a .ssp at all: they wrap an
  object number in ODT output, which happens after the abstraction,
  so their occurrences here are Japanese quotation marks in the
  document's own text.

  The grammar says what it does and does not fix, and why the order
  of properties is left to the table rather than enumerated as 42
  optional terms that would need editing at every minor version.
  Every line of the collection matches one of its eight line shapes,
  721,363 lines with none left over.

(assisted by Claude-Code)

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
</feed>
