ocda: the abstraction carries the document metadata output reads

.ssp format v0.1 -> v1.1, and the .ocda.db with it: they are two
serialisations of one format and now move together.

The gap this closes, measured against the writers' read set: of the 59
conf_make_meta fields outputs/io_out/ reads, 29 were in neither
artefact. Five are conf.* and stay out, being site and run scoped (urls,
papersize, the search db filename): the same abstraction published to
two sites must take each site's. Of the rest, three are never assigned
anywhere (title_short, publisher, original_publisher; read only by
sqlite.d, always empty) and one is a copy of a field already carried
(title_sub = title_subtitle), so 17 properties actually had to travel
and now do:

  make      breaks, footer, home_button_text
  meta      title.edition, date.added_to_site, language.document_char,
            original.{title,source,language,language_char},
            rights.copyright_{text,translation,illustrations,
            photographs,cover,audio,video}

make splits by when it acts, which is worth keeping in mind: these three
are read in outputs/io_out/ and must travel, while italics, bold,
emphasis, substitute and headings are read at parse time and their
effect is already in the objects.

New @source block, and source.* rows in the database, so a reader can
say which markup an abstraction came from rather than working from
stale content in silence:

  language    the document's own
  languages   the pod's list, which is what the inter-language links
              in html need and neither artefact carried
  digest      sha256 of the .sst; equals its digests.txt entry

The database adds source.ssp_digest, the sha256 of the .ssp it was built
from, since a file cannot hold its own hash. So the chain
.sst -> .ssp -> .ocda.db is checkable end to end.

The database's metadata table is now filled from the header blocks the
.ssp gives back, not from a second list read off doc_matters. One list,
in ssp.d: a property added there arrives in the database with nothing
else changed, and one that is not in the .ssp cannot be in the database
at all. That was the last place the two could drift; the objects stopped
being able to on 2026-09-07.

Version is checked on load. The major part must match, a newer minor is
accepted (a minor bump only adds properties, and an unknown property
line is ignored). A v0.1 artefact is now refused with a message saying
to regenerate it, rather than loading half populated.

test-abstraction-db.sh now compares the two artefacts' header blocks
property by property, 36 per document on the wealth of networks, where
it previously only checked that a schema.version row existed. Verified
non-vacuous: dropping one property is reported.

Reference regenerated, and the whole diff is this change and nothing
else: 320 lines added, 35 removed over 35 files, being 35 format lines
changed, 35 @source blocks (4 lines each), 35 language.document_char, 35
home_button_text (it has a default), 18 breaks, 16 footer,
4 date.added_to_site, 1 title.edition, 1 original.source.

Existing outputs unaffected.

(assisted by Claude-Code)

1 files changed, 37 insertions, 0 deletions

diff --git a/test/test-abstraction-db.sh b/test/test-abstraction-db.sh
index 31e5fa5..6a0e4e6 100755
--- a/test/test-abstraction-db.sh
+++ b/test/test-abstraction-db.sh
@@ -211,11 +211,48 @@ for ssp in $(find "$OUT_DIR/pod" -name "*.ssp" 2>/dev/null | sort); do
     rm -f "$OUT_DIR/.dbtxt.$$" "$OUT_DIR/.ssptxt.$$"
   done
 
+  # the header blocks: every @source/@meta/@make/@doc_has property in the .ssp
+  # must be in the database under its own key, with the same value. this is
+  # what catches a header property that reaches one artefact and not the
+  # other, which a count of objects cannot see.
+  awk '
+    /^@(source|meta|make|doc_has) \{$/ { blk=substr($1,2); next }
+    /^\}$/ { blk=""; next }
+    blk != "" && /^  [a-z_.]+: / {
+      k=$1; sub(/:$/,"",k)
+      v=substr($0, index($0,": ")+2)
+      pfx = (blk=="meta") ? "" : blk "."
+      print pfx k "\t" v
+    }
+  ' "$ssp" | sort > "$OUT_DIR/.sspmeta.$$"
+  sqlite3 -separator "$(printf '\t')" "$db" \
+    "select key, value from metadata where key not in
+       ('schema.name','schema.version','source.filename','source.ssp_digest');" \
+    2>/dev/null | sort > "$OUT_DIR/.dbmeta.$$"
+  if ! diff -q "$OUT_DIR/.sspmeta.$$" "$OUT_DIR/.dbmeta.$$" > /dev/null 2>&1; then
+    [ $doc_fail -eq 0 ] && echo "$base"
+    echo "  MISMATCH header blocks (.ssp against metadata table):"
+    diff "$OUT_DIR/.sspmeta.$$" "$OUT_DIR/.dbmeta.$$" | head -8 | sed 's/^/    /'
+    doc_fail=1
+  fi
+  rm -f "$OUT_DIR/.sspmeta.$$" "$OUT_DIR/.dbmeta.$$"
+
+  # the source filename, and the version the two share
+  sf=$(sqlite3 "$db" "select value from metadata where key='source.filename';" 2>/dev/null || echo '')
+  sf_ssp=$(sed -n 's/^% Source: //p' "$ssp" | head -1)
+  if [ "$sf" != "$sf_ssp" ]; then
+    [ $doc_fail -eq 0 ] && echo "$base"
+    echo "  MISMATCH source.filename: db '$sf' .ssp '$sf_ssp'"; doc_fail=1
+  fi
+  sv_ssp=$(sed -n 's/^% SiSU Document Abstraction v//p' "$ssp" | head -1)
   # the file says what it is
   sv=$(sqlite3 "$db" "select value from metadata where key='schema.version';" 2>/dev/null || echo '')
   if [ -z "$sv" ]; then
     [ $doc_fail -eq 0 ] && echo "$base"
     echo "  MISSING metadata schema.version"; doc_fail=1
+  elif [ "$sv" != "$sv_ssp" ]; then
+    [ $doc_fail -eq 0 ] && echo "$base"
+    echo "  MISMATCH format version: db '$sv' .ssp '$sv_ssp'"; doc_fail=1
   fi
 
   FAILURES=$((FAILURES + doc_fail))