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)

--help now names the five source forms before the options, and after
them states the contract: what a .ssp and a .ocda.db each carry and do
not, that both record the digest of the markup they were built from,
which five actions need that markup and what happens when they cannot
have it, and the three ways to verify.

And the version, 0.24.1 to 0.25.0, for abstraction format 2.0 and what
it made possible: (one database per document holding every language of
it, carrying the markup, images, configuration, manifest and
translation catalogues it was built from, with the implications that
carries)

(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)

ensure that db uses the names it carries in manifest which produce
deterministic output (and fix divergence in db rendering of output
names, (which previously also looked for variable input from the
environment))

Output built from a database with --config naming the site configuration
is now byte identical to output built from the pod, on the render route
as it already was on the materialise route.

(assisted by Claude-Code)

dr_document_make in three identifier spellings becomes document_make,
which is what the file has been called since the rename.

The mixin import audit, a template declares its imports at template
scope and they are then visible in every scope it is mixed into (which
is how a template-level split once hijacked a UFCS lookup in code that
had not been touched). Disabling htmlSnippet's imports and rebuilding
names the consumers that were relying on them rather than on their own:
across twelve mixin sites, exactly one. metadata.d now imports the `to`
it uses. The templates keep their imports, their own functions needing
them, and narrowing those is a change of its own rather than a cleanup.

And the standing FIX in source_pod.d: the insert digest line for a non
pod source recorded the insert's path, where every other line in
digests.txt is a filename and a digest naming a file that is not in
the pod under that name cannot be checked against it.

(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)

does this spine still produce this abstraction?

A database states an abstraction and carries the markup it was built
from, so re-parsing the one and comparing against the other says whether
the two still agree. Checked as follows:
- automatically and unskippably when a document is built from a
  database, at the moment it is parsed and before anything has been
  written from it.
- on --ocda-verify=<file>, an action of its own that materialises,
  parses every language, compares, reports and writes nothing, the exit
  status being the answer.
- on --no-verify as the escape, warning per document, for a newer spine
  reading an older artefact where the abstraction is expected to differ
  and the output is wanted anyway.

A build ends at the first failure rather than skipping the language.

A document rebuilt from a database now has its whole abstraction built.

(assisted by Claude-Code)