<feed xmlns='http://www.w3.org/2005/Atom'>
<title>sisudoc-abstraction-format, branch main-consider</title>
<subtitle>SiSU Spine: specs</subtitle>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/'/>
<entry>
<title>format 2.1: editor's notes</title>
<updated>2026-10-03T16:09:16+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=df09967a7f27012afe6e785ce77d5c3fd7432157'/>
<id>df09967a7f27012afe6e785ce77d5c3fd7432157</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.

(assisted by Claude-Code)
</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.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>format 2.1: poem is a container of verse (objects)</title>
<updated>2026-10-03T16:09:16+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=439bb7e946e5b6e6ac350b3d4cbd3794b5b0ff21'/>
<id>439bb7e946e5b6e6ac350b3d4cbd3794b5b0ff21</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 rather than the poem. Poem how 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 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.

(assisted by Claude-Code)
</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 rather than the poem. Poem how 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 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.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>derived values, that the model left unstated</title>
<updated>2026-10-03T16:09:16+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=f7f4063b351b98e372412d2b364b88ecbe0912c7'/>
<id>f7f4063b351b98e372412d2b364b88ecbe0912c7</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.

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)
</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.

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)
</pre>
</div>
</content>
</entry>
<entry>
<title>.ocda.db specified &amp; the two serialisations agree</title>
<updated>2026-10-03T16:09:16+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=9cfb55b80d85d98b081b3113311475ad74fea9ff'/>
<id>9cfb55b80d85d98b081b3113311475ad74fea9ff</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 reference collection, and both are now stated with
the check that establishes them.

The third document, derived from the writer and checked against the
document sample published databases: eight tables, one virtual table,
three views, fifty columns on objects.

The claim worth making and checked: 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 all that is different.

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.

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.

(assisted by Claude-Code)
</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 reference collection, and both are now stated with
the check that establishes them.

The third document, derived from the writer and checked against the
document sample published databases: eight tables, one virtual table,
three views, fifty columns on objects.

The claim worth making and checked: 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 all that is different.

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.

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.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>gaps: kinds, types, levels, make block, markers</title>
<updated>2026-10-03T16:09:16+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=280d692d075039f5a80a2b74310d1280d5cefae4'/>
<id>280d692d075039f5a80a2b74310d1280d5cefae4</id>
<content type='text'>
close gaps left in the first pass, measured against the document markup
sample set, (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. Only
  heading appears in all nine sections.

  Kind and type are two axes rather than one, and type 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. 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.

  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.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
close gaps left in the first pass, measured against the document markup
sample set, (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. Only
  heading appears in all nine sections.

  Kind and type are two axes rather than one, and type 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. 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.

  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.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>sisudoc-abstraction-format 2.0: ocda-model &amp; .ssp</title>
<updated>2026-10-03T16:07:15+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-04-19T00:28:29+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=0bf25dac62f2f8351367bc55ff9b373e380f7cf0'/>
<id>0bf25dac62f2f8351367bc55ff9b373e380f7cf0</id>
<content type='text'>
In the age of maleable, replacable, improvable, text, we here continue
to seek to being able to represent set text in a fixed, determinate way.

this is an effort using an LLM to extract the document abstraction
specifications for the program spine (Anthropic's Claude Code is used):

- within the program spine the document abstraction can be captured in
  a .ssp document abstraction serialization file, which is a peg
  parsable serialisation (from which other document abstractions can be
  derived, such as the sqlite ocda-db abstraction)
  https://git.sisudoc.org/sisudoc-spine/
  git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine

- here in the specification: capturing, describing, stating the
  specification of the abstraction as captured by the .ssp document
  serialization, with enough detail and precision to enable the
  independent reading and writing of the abstraction.
  https://git.sisudoc.org/sisudoc-abstraction-format/
  git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format

- in the tools/ namespace attempts are made to successfuly, perfectly
  re-read and write from the abstraction using the specification alone
  (without use of any other prior or outside knowledge of the .ssp
  serialization format)

sisudoc-abstraction-format is derived from the spine emitter,
sisudoc/ocda/abstraction/ssp.d, whose sspObjectRecord is the single
definition of what an object looks like, and checked against the
document markup sample set.

Should there be a difference the emitter is normative and the
specification is wrong; and it states so.

Three documents, so the model is described once rather than in each
format specification:

  ocda-model.md                    the model: what an object is, the
                                   citation number, structure,
                                   sections, segments, digests.  The
                                   part both serialisations share
  ssp-format-specification.md      the model written as text
  ocda-db-format-specification.md  the model written as sqlite, to
                                   come

The naming follows the three levels: ocda names the model,
abstraction names the pipeline stage, and .ssp and .ocda.db name the
two serialisations. A thing is named for the level it belongs to,
which is why this file is ssp-format-specification.md and not
ocda-format-specification.md: it specifies one serialisation, not the
model.

The specification states the version and the policy that governs it,
and separates conformance into what a reader must do, should do, and
what a writer must do. The single "should" is that a reader should
report what it ignored: without it, silence cannot be told from
understanding.

Both worked examples regenerated from spine 0.25.0.  The excerpt
carries one complete object embedding an image, so the .image record
and the image marker in the object text can be read against each
other.

The name .ssp is recorded: it belongs to the .sst, .ssm, .ssi family
and stands loosely for sisu peg or sisu parsable, .ssa for sisu
abstraction having been thought taken by other projects.

Add a top-level README.md identifying the repository as a
specification (not a program), summarising what .ssp is (a
human-readable, PEG-parsable serialisation of spine's in-memory
document abstraction), listing the line-type grammar at a glance,
and pointing readers at format-specification.md for the full
reference and at the two example .ssp files shipped alongside.

Canonical URLs use the new git.sisudoc.org/tools/ namespace,
matching the parallel moves in tree-sitter-sisu and ssp-reader
and the local rename of sisudoc-spine-utils/ to
sisudoc-spine-tools/. Cross-references to ssp-reader and
tree-sitter-sisu follow the same convention.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
In the age of maleable, replacable, improvable, text, we here continue
to seek to being able to represent set text in a fixed, determinate way.

this is an effort using an LLM to extract the document abstraction
specifications for the program spine (Anthropic's Claude Code is used):

- within the program spine the document abstraction can be captured in
  a .ssp document abstraction serialization file, which is a peg
  parsable serialisation (from which other document abstractions can be
  derived, such as the sqlite ocda-db abstraction)
  https://git.sisudoc.org/sisudoc-spine/
  git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine

- here in the specification: capturing, describing, stating the
  specification of the abstraction as captured by the .ssp document
  serialization, with enough detail and precision to enable the
  independent reading and writing of the abstraction.
  https://git.sisudoc.org/sisudoc-abstraction-format/
  git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format

- in the tools/ namespace attempts are made to successfuly, perfectly
  re-read and write from the abstraction using the specification alone
  (without use of any other prior or outside knowledge of the .ssp
  serialization format)

sisudoc-abstraction-format is derived from the spine emitter,
sisudoc/ocda/abstraction/ssp.d, whose sspObjectRecord is the single
definition of what an object looks like, and checked against the
document markup sample set.

Should there be a difference the emitter is normative and the
specification is wrong; and it states so.

Three documents, so the model is described once rather than in each
format specification:

  ocda-model.md                    the model: what an object is, the
                                   citation number, structure,
                                   sections, segments, digests.  The
                                   part both serialisations share
  ssp-format-specification.md      the model written as text
  ocda-db-format-specification.md  the model written as sqlite, to
                                   come

The naming follows the three levels: ocda names the model,
abstraction names the pipeline stage, and .ssp and .ocda.db name the
two serialisations. A thing is named for the level it belongs to,
which is why this file is ssp-format-specification.md and not
ocda-format-specification.md: it specifies one serialisation, not the
model.

The specification states the version and the policy that governs it,
and separates conformance into what a reader must do, should do, and
what a writer must do. The single "should" is that a reader should
report what it ignored: without it, silence cannot be told from
understanding.

Both worked examples regenerated from spine 0.25.0.  The excerpt
carries one complete object embedding an image, so the .image record
and the image marker in the object text can be read against each
other.

The name .ssp is recorded: it belongs to the .sst, .ssm, .ssi family
and stands loosely for sisu peg or sisu parsable, .ssa for sisu
abstraction having been thought taken by other projects.

Add a top-level README.md identifying the repository as a
specification (not a program), summarising what .ssp is (a
human-readable, PEG-parsable serialisation of spine's in-memory
document abstraction), listing the line-type grammar at a glance,
and pointing readers at format-specification.md for the full
reference and at the two example .ssp files shipped alongside.

Canonical URLs use the new git.sisudoc.org/tools/ namespace,
matching the parallel moves in tree-sitter-sisu and ssp-reader
and the local rename of sisudoc-spine-utils/ to
sisudoc-spine-tools/. Cross-references to ssp-reader and
tree-sitter-sisu follow the same convention.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
</feed>
