- A poem is a container of verse, and stores its range of verse ocn,
  - its verse are the citable units with ocn.

- A note in the last verse of a poem previously was not gathered into
  the endnotes section, this now is fixed

Format 2.0 -> 2.1: the property is an addition, the poem is not a
citable object (but contans a range of objects), its verse are
(individual citable objects), and every reader checks the major version.
A 2.0 database reads as having no ranges.

(assisted by Claude-Code)

The markup documents ~[* note ]~ and ~[+ note ]~ as editor's notes, each
a separately numbered series, and a bare ~[ note ]~ which sisu put in
the asterisk series. They are included as notes. Each series is numbered
through the document, *1, *2 ... and +1, +2 ..., apart from the author's
notes.

(assisted by Claude-Code)

flags names tidied so that each names the artefact it acts on.

--ocda-db and --abstraction-db do the same thing. --ocda-db is the
official flag (--abstraction-db remains but undocumented)

--db-round-trip becomes --ocda-db-round-trip, so that it agrees with
--ssp-round-trip: each names the artefact it reads rather than one
naming a container and the other a format.

--abstraction-source is untouched named after he stage as it takes .sst,
a pod, .ssp or .ocda.db, rather than any one artefact.

(assisted by Claude-Code)

spine automatically builds some segments, including: (toc, endnotes,
glossary, bibliography, bookindex, blurb, _the_title) these are now
identified as reserved names and a user is now warned if any of these
names have been manually assigned to a heading by markup. A document
still builds but to disambiguate the ocn of the heading is attached to
the markup (reserved) name and this is seeded before a document not
after. It is read off the finished abstraction rather than reported by
the parser, and beside the ocn alignment check for the same reason: it
is a statement about a document rather than a step in building one.

  WARNING reserved segment name: the_autonomous_contract... [en]
    heading 1 at ocn 135 asks for "endnotes", which spine gives its
    own generated section
      it is named "endnotes-135" instead; ...

A warning: the document is correct and complete and the name it ends
up with works.

--strict makes it a failure for the run, as it does for ocn alignment,
and by the same reasoning: the outputs are written and can be looked at,
and the exit status is taken at the end.

Two of the thirty-six sample documents have reserved segment names,
"1~endnotes" heading. Output is unchanged: nothing here touches the
abstraction.

(assisted by Claude-Code)

need a character to split filenames on in certain circumstances.
there problems with use of a colon in filenames, which is legal on posix
but not on Windows."~" fits the bill better being legal on every
filesystem of interest and is unreserved in rfc 3986, needing no escaping in a url.

The reference abstraction is renamed, its content unchanged. Over
the sample collection two filenames move and nothing else does: the
abstraction and database digests are identical, the archive's
members and their sizes are unchanged, and only the member order
shifts, "~" collating after letters where ":" sorted before them. The
document's epub dc:identifier is a v5 uuid derived from the uid, so it
changes for those filenames.

Every document's uid changes in the search database (spine.search.db).

(assisted by Claude-Code)

The ja and pl translations were mended in the sample set, so the two
divergences this script asserted by name are gone. It failed and named
every stale expectation, which is what it was for.

The reference set is regenerated with two files affected:
live-manual.ja.ssp and live-manual.pl.ssp.

(assisted by Claude-Code)

- check that tools required for a test are present
  (check for sqlite3, epubcheck; add tools as
  needed)
- report a a skipped test as incomplete

(assisted by Claude-Code)

The acceptance test for the document source claim. Two runs of the
same spine with the same flags over the same document:
- the pod to artefacts and outputs, including database, and
- that run's database back to a pod and on to artefacts and outputs.
diff -r between the two trees must be empty.

One comparison covers the written pod tree with its markup, conf, images
and catalogues, the .ssp files, the database itself, the digests, and
the text, html and epub built from them. 690 files for live-manual, ten
languages and a catalogue tree and no images, and 58 for the wealth of
networks, ten images and one language: the two cover each other's gaps,
and SpineAcceptanceDocs widens the set.

--ocda-verify is asserted separately, before the build. The build would
check the same thing and stop, but asking on its own means a failure
says which claim broke: that the pod comes back, or that the abstraction
it makes is the one recorded with it.

The pod for the first run is copied out of the sample set rather than
read where it lies. Read in place it has a site configuration above it
and a materialised pod has none, and the site url reaches the generated
index pages: five files differing in a url, and nothing else, which
would read as corruption.

Both runs ask for the same flags, the dom structure tags the .ssp
records being computed only when an action needs them.

The archive is not compared. Neither run writes one: it is a container
around bytes compared here already, and its own bytes are not part of
what a database claims to carry.

(assisted by Claude-Code)

Check that they are the right files: source.digest is the sha256 over
one line per markup file, "<SHA256> <basename>", sorted and newline
joined, so the same value can be computed from the stored rows alone and
held against what the .ssp recorded. A file stored under the right name
with the wrong contents passes a count and fails this.

Two details the shell gets wrong by default: the sort has to be
LC_ALL=C, because the writer sorts by byte and a locale does not, and
the lines are joined with no trailing newline, so printf and not echo.

(assisted by Claude-Code)

Asserts the two known divergences in live-manual's translations by name
and value: ja two objects short of en, and pl's ocn 313 a paragraph in
English and a heading in Polish.

It asserts that nothing else is reported: exactly one document warned
about, exactly two languages of it.

Also the exit codes: 0 without --strict, non-zero with it on the
diverging document, and 0 with it on a single language document.

It will fail when those two translations are mended, which is the right
moment to hear about it, and the message names the expectation that went
stale.

test-abstraction-db.sh excludes translation.ocn_aligned from its header
block comparison, with the other two keys that are the database's notes
about the artefact rather than properties of the document.

(assisted by Claude-Code)