<feed xmlns='http://www.w3.org/2005/Atom'>
<title>sisudoc-abstraction-format/README.md, branch claude-markdown-1</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: a poem is a container, cited as the range of its verses</title>
<updated>2026-10-03T03:23:34+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=77c68e02c4562ad121891d66f915f16e21144b1f'/>
<id>77c68e02c4562ad121891d66f915f16e21144b1f</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)
</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)
</pre>
</div>
</content>
</entry>
<entry>
<title>README: the repository specifies both forms, not only the .ssp</title>
<updated>2026-10-03T03:23:34+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=4e87bab15cba80319d4c417abdb3a9479c3fc8d7'/>
<id>4e87bab15cba80319d4c417abdb3a9479c3fc8d7</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)
</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)
</pre>
</div>
</content>
</entry>
<entry>
<title>named sisudoc-abstraction-format</title>
<updated>2026-10-03T03:23:34+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=67fe3ee01f4db345dd51666aab41bc1df22857b0'/>
<id>67fe3ee01f4db345dd51666aab41bc1df22857b0</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)
</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)
</pre>
</div>
</content>
</entry>
<entry>
<title>the .ocda.db specified, and the two serialisations shown to agree</title>
<updated>2026-10-03T03:23:34+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=43fbb8b8b52b33dcb3eda4ffcf066ebfb76f5459'/>
<id>43fbb8b8b52b33dcb3eda4ffcf066ebfb76f5459</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)
</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)
</pre>
</div>
</content>
</entry>
<entry>
<title>explore spec</title>
<updated>2026-10-03T03:21:30+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=78c0b1bbdfbdeca58f7ef3159c887b3d895c44af'/>
<id>78c0b1bbdfbdeca58f7ef3159c887b3d895c44af</id>
<content type='text'>
(commit message #2):

explore spec

(commit message #3):

rename .sda references and files to .ssp

Rename file extension from .sda to .ssp throughout the
format specification and example files.

- example-autonomous-contract.sda -&gt; .ssp
- example-wealth-of-networks.sda -&gt; .ssp
- format-specification.md: all .sda references updated

(commit message #4):

docs: add README under git.sisudoc.org/tools/ namespace

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)

(commit message #5):

spec: image records, .image property

Documents the per-object image record that spine now emits, one
repeatable .image line per image, filename first then
self-describing key:value fields:

  .image: won_benkler_2_1.png sha256:5BA4...D128 bytes:93861 px:420x342
  .image: ffa.png missing:true

Covers the four fields (sha256, bytes, px, missing), the reader
requirements (repeatable, order-independent fields, ignore what is
not recognised, do not assume a field count), the distinction
between px (the file's own pixel size) and the w##h## display
dimensions carried in the object text, and the PEG rules for the
record. Notes why the pod digests.txt keeps its own flat form.

(assisted by Claude-Code)

(commit message #6):

spec: correct drift between documented and emitted properties

Found while documenting the image record: the property reference
had fallen behind the emitter. Checked property by property against
src/sisudoc/ocda/abstraction/ssp.d and against .ssp output for
the_wealth_of_networks; documented and emitted sets now agree.

Corrected names:
- .heading_ancestors  -&gt; .heading_ancestors_text
- .links (one line, space separated) -&gt; .stow_link (repeatable)
- .identifier: dropped, a heading's identifier is not a property,
  it follows the level on the declaration line: [5] heading :1 id

Documented, previously absent: .children, .heading_lev_collapsed,
.parent_lev, .o_n_type, .is_of_type, .attrib, .meta_lang,
.meta_syntax, .segment_epub, .heading_lev_anchor, .anchor_tag,
.lev4_subtoc, and the images_no_dim flag of .has.

Also: heading_lev_collapsed was listed as not serialised while
being emitted; @make showed a breaks: line that is not emitted and
lacked auto_num_top_lv; omission rules extended to the properties
above, with .section and .anchor stated more precisely (each is
omitted when it repeats the enclosing section / the .segment
value).

(assisted by Claude-Code)

(commit message #7):

examples: real spine output in place of the hand-written ones

Both example files said so in their own headers: "Hand-crafted
example showing what the serialized abstraction would look like",
with illustrative OCNs. They predated several format changes and
neither showed an object embedding an image.

example-autonomous-contract.ssp is now spine's output for that
sample document, complete and unedited but for the comment lines
naming the command that regenerates it.

example-wealth-of-networks.ssp is an excerpt of spine's output for
that document, the whole being some 19,500 lines: verbatim lines
with marked elisions, keeping the @meta / @make / @doc_has
preamble, the @head section, and body objects [95] to [99], among
them [97], which embeds an image and so carries an .image record.

Both parse: ssp-reader --tree and --images read them, the latter
reporting the image record of [97] against the digest the pod's
digests.txt gives for won_benkler_2_1.png.

README: the two files described separately (complete / excerpt),
and the quickstart names the flags that actually write a .ssp.

Carries with it the git.sisudoc.org namespace corrections to the
README links that were already staged in the working tree.

(assisted by Claude-Code)

(commit message #8):

spec: .parent emission rule, regenerate the worked example

.parent is no longer "omit when zero". spine emits it for every
object, 0 included, except the :A~ document root (no parent) and the
entries of the generated @toc section (furniture, placed by their
.indent level; the toc heading itself keeps .parent: 1). A missing
.parent must not be read as 0.

- omission table row and a new paragraph under Properties
- example-autonomous-contract.ssp regenerated from spine 0.22.0,
  which also picks up the ancestors / dom_status / last_descendant /
  parent_lev fixes made in spine since 2026-08-27, and the corrected
  .ocn_off on paragraph objects

example-wealth-of-networks.ssp is a hand-elided excerpt and has not
been regenerated; its verbatim lines predate these changes.

(assisted by Claude-Code)

(commit message #9):

format 2.0: the model and the .ssp, specified afresh

The previous specification described format 0.1 and was two major
versions behind: four properties were emitted and undocumented, two
of them on nearly every object; four were documented and never
emitted; and it mentioned neither the version banner nor the @source
block.  Both worked examples were 0.22.0 output.  Discarded rather
than revised.

Derived from the emitter, sisudoc/ocda/abstraction/ssp.d, whose
sspObjectRecord is the single definition of what an object looks
like, and checked against the 36 document reference set.  Where the
two could differ the emitter is normative and the specification is
wrong; it says so.

Three documents where there was one, so that 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.

What the mechanical derivation found that reading would not have:
the property set is 42 and not the 39 the corpus exercises, three
being emitted under conditions no sample document meets; property
order is fixed, and provably so, no object of 56,882 emitting one out
of the emitter order; @meta defines 43 keys where the collection uses
28; and a heading declaration line carries its level and identifier,
where every other kind carries the identifier as a property.

The specification now also states the version and the policy that
governs it, which the old file had no notion of, 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.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
(commit message #2):

explore spec

(commit message #3):

rename .sda references and files to .ssp

Rename file extension from .sda to .ssp throughout the
format specification and example files.

- example-autonomous-contract.sda -&gt; .ssp
- example-wealth-of-networks.sda -&gt; .ssp
- format-specification.md: all .sda references updated

(commit message #4):

docs: add README under git.sisudoc.org/tools/ namespace

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)

(commit message #5):

spec: image records, .image property

Documents the per-object image record that spine now emits, one
repeatable .image line per image, filename first then
self-describing key:value fields:

  .image: won_benkler_2_1.png sha256:5BA4...D128 bytes:93861 px:420x342
  .image: ffa.png missing:true

Covers the four fields (sha256, bytes, px, missing), the reader
requirements (repeatable, order-independent fields, ignore what is
not recognised, do not assume a field count), the distinction
between px (the file's own pixel size) and the w##h## display
dimensions carried in the object text, and the PEG rules for the
record. Notes why the pod digests.txt keeps its own flat form.

(assisted by Claude-Code)

(commit message #6):

spec: correct drift between documented and emitted properties

Found while documenting the image record: the property reference
had fallen behind the emitter. Checked property by property against
src/sisudoc/ocda/abstraction/ssp.d and against .ssp output for
the_wealth_of_networks; documented and emitted sets now agree.

Corrected names:
- .heading_ancestors  -&gt; .heading_ancestors_text
- .links (one line, space separated) -&gt; .stow_link (repeatable)
- .identifier: dropped, a heading's identifier is not a property,
  it follows the level on the declaration line: [5] heading :1 id

Documented, previously absent: .children, .heading_lev_collapsed,
.parent_lev, .o_n_type, .is_of_type, .attrib, .meta_lang,
.meta_syntax, .segment_epub, .heading_lev_anchor, .anchor_tag,
.lev4_subtoc, and the images_no_dim flag of .has.

Also: heading_lev_collapsed was listed as not serialised while
being emitted; @make showed a breaks: line that is not emitted and
lacked auto_num_top_lv; omission rules extended to the properties
above, with .section and .anchor stated more precisely (each is
omitted when it repeats the enclosing section / the .segment
value).

(assisted by Claude-Code)

(commit message #7):

examples: real spine output in place of the hand-written ones

Both example files said so in their own headers: "Hand-crafted
example showing what the serialized abstraction would look like",
with illustrative OCNs. They predated several format changes and
neither showed an object embedding an image.

example-autonomous-contract.ssp is now spine's output for that
sample document, complete and unedited but for the comment lines
naming the command that regenerates it.

example-wealth-of-networks.ssp is an excerpt of spine's output for
that document, the whole being some 19,500 lines: verbatim lines
with marked elisions, keeping the @meta / @make / @doc_has
preamble, the @head section, and body objects [95] to [99], among
them [97], which embeds an image and so carries an .image record.

Both parse: ssp-reader --tree and --images read them, the latter
reporting the image record of [97] against the digest the pod's
digests.txt gives for won_benkler_2_1.png.

README: the two files described separately (complete / excerpt),
and the quickstart names the flags that actually write a .ssp.

Carries with it the git.sisudoc.org namespace corrections to the
README links that were already staged in the working tree.

(assisted by Claude-Code)

(commit message #8):

spec: .parent emission rule, regenerate the worked example

.parent is no longer "omit when zero". spine emits it for every
object, 0 included, except the :A~ document root (no parent) and the
entries of the generated @toc section (furniture, placed by their
.indent level; the toc heading itself keeps .parent: 1). A missing
.parent must not be read as 0.

- omission table row and a new paragraph under Properties
- example-autonomous-contract.ssp regenerated from spine 0.22.0,
  which also picks up the ancestors / dom_status / last_descendant /
  parent_lev fixes made in spine since 2026-08-27, and the corrected
  .ocn_off on paragraph objects

example-wealth-of-networks.ssp is a hand-elided excerpt and has not
been regenerated; its verbatim lines predate these changes.

(assisted by Claude-Code)

(commit message #9):

format 2.0: the model and the .ssp, specified afresh

The previous specification described format 0.1 and was two major
versions behind: four properties were emitted and undocumented, two
of them on nearly every object; four were documented and never
emitted; and it mentioned neither the version banner nor the @source
block.  Both worked examples were 0.22.0 output.  Discarded rather
than revised.

Derived from the emitter, sisudoc/ocda/abstraction/ssp.d, whose
sspObjectRecord is the single definition of what an object looks
like, and checked against the 36 document reference set.  Where the
two could differ the emitter is normative and the specification is
wrong; it says so.

Three documents where there was one, so that 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.

What the mechanical derivation found that reading would not have:
the property set is 42 and not the 39 the corpus exercises, three
being emitted under conditions no sample document meets; property
order is fixed, and provably so, no object of 56,882 emitting one out
of the emitter order; @meta defines 43 keys where the collection uses
28; and a heading declaration line carries its level and identifier,
where every other kind carries the identifier as a property.

The specification now also states the version and the policy that
governs it, which the old file had no notion of, 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.

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