<feed xmlns='http://www.w3.org/2005/Atom'>
<title>sisudoc-abstraction-format/README.md, branch main</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: on poems and editor's notes</title>
<updated>2026-10-13T01:48:46+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=7532a04beb6f51665011cf3117d2b29c651a3442'/>
<id>7532a04beb6f51665011cf3117d2b29c651a3442</id>
<content type='text'>
- editor's notes:
  Updated here, spine now apart from author's notes recognises existing
  markup's editor's notes, ~[* ]~ and ~[+ ]~, and writes them as notes
  of their own numbered series: *1, *2 ... and +1, +2 ... document.

- a poem is a container of its verse:
  .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. A poem 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 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>
- editor's notes:
  Updated here, spine now apart from author's notes recognises existing
  markup's editor's notes, ~[* ]~ and ~[+ ]~, and writes them as notes
  of their own numbered series: *1, *2 ... and +1, +2 ... document.

- a poem is a container of its verse:
  .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. A poem 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 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>.ocda.db specified &amp; the two serialisations agree</title>
<updated>2026-10-04T01:50:59+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=0e307f24cfcbcb365a3fe2770a5ad718eeb41ca4'/>
<id>0e307f24cfcbcb365a3fe2770a5ad718eeb41ca4</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.

- Repeated occurrences of a property 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
sample set's 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.

- Repeated occurrences of a property 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
sample set's 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>sisudoc-abstraction-format 2.0: ocda-model &amp; .ssp</title>
<updated>2026-10-04T01:50:58+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=7f3a62f67a618db2bf0e52bb3220d953fbe941c4'/>
<id>7f3a62f67a618db2bf0e52bb3220d953fbe941c4</id>
<content type='text'>
In an age of malleable, replaceable, improvable text, we continue to
seek to represent set text in a fixed, determinate way.

This is an effort, using an LLM (Anthropic's Claude Code), to extract
and state the specification of the document abstraction of the
program spine:

- spine can write its document abstraction as a .ssp file, a
  PEG-parsable serialisation from which other forms of it, such as
  the sqlite .ocda.db, can be derived
  https://git.sisudoc.org/sisudoc-spine
  git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine

- this repository states the specification of that abstraction, as
  the .ssp writes it, in enough detail and with enough precision for
  the abstraction to be read and written independently
  git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format

- the claim is tested separately: with readers and writers built from
  the specification alone, with no other knowledge of the format, that
  read and write the abstraction exactly

The specification 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. Where the two differ the emitter is
normative and the specification is wrong; the specification says 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.

README.md identifies the repository as a specification, not a
program, summarises what a .ssp is, gives its line types at a glance,
and points to ssp-format-specification.md and the two examples.
org/ocda_specification.org is the literate source the documents are
tangled from.

2026-09-22

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

This is an effort, using an LLM (Anthropic's Claude Code), to extract
and state the specification of the document abstraction of the
program spine:

- spine can write its document abstraction as a .ssp file, a
  PEG-parsable serialisation from which other forms of it, such as
  the sqlite .ocda.db, can be derived
  https://git.sisudoc.org/sisudoc-spine
  git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine

- this repository states the specification of that abstraction, as
  the .ssp writes it, in enough detail and with enough precision for
  the abstraction to be read and written independently
  git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format

- the claim is tested separately: with readers and writers built from
  the specification alone, with no other knowledge of the format, that
  read and write the abstraction exactly

The specification 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. Where the two differ the emitter is
normative and the specification is wrong; the specification says 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.

README.md identifies the repository as a specification, not a
program, summarises what a .ssp is, gives its line types at a glance,
and points to ssp-format-specification.md and the two examples.
org/ocda_specification.org is the literate source the documents are
tangled from.

2026-09-22

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