ocda db: <doc>.ocda.db, and a script to run 4 tests

The per document database is now written as <doc_uid>.ocda.db
rather than <doc_uid>.abstraction.db. Shorter, and it says what is
in the file: the object centric document abstraction, not "some
abstraction". .ocda.db pairs with .ssp and cannot be mistaken for
the collection search database (spine.search.db).

test/run-tests.sh runs the four in sequence, one line of result
each, and a summary. It re-runs itself inside nix shell
"nixpkgs#sqlite" if sqlite3 is not on PATH, so this is all that
is needed:

  SpinePOD=../../markup/sisudoc-spine-samples/markup/pod-samples/pod \
    ./test/run-tests.sh ./bin/spine-ldc

The tests are independent (with test-abstraction-ssp.sh run
first):

  1 test-abstraction-ssp.sh            is first because it is the
    one that says whether the abstraction itself moved; if it
    fails the others are answering a different question than you
    think
  2 test-abstraction-ssp-roundtrip.sh  reads the committed
    reference set, so it is a statement about the current binary
    only if 1 passes
  3 test-abstraction-db.sh             and
  4 test-abstraction-db-roundtrip.sh   generate both artefacts
    themselves and depend on nothing committed

(assisted by Claude-Code)

4 files changed, 109 insertions, 12 deletions

diff --git a/org/in_source_files.org b/org/in_source_files.org
index 0a87ec4..04792ec 100644
--- a/org/in_source_files.org
+++ b/org/in_source_files.org
@@ -1096,7 +1096,7 @@ template spineAbstractionRead() {
 <<doc_header_including_copyright_and_license>>
 module sisudoc.ocda.abstraction.db_in;
 @safe:
-/+ ↓ read a <doc>.abstraction.db back into the document abstraction
+/+ ↓ read a <doc>.ocda.db back into the document abstraction
 
      the counterpart of sisudoc.outputs.io_out.create_abstraction_db, and the
      sibling of sisudoc.ocda.abstraction.ssp_in: it returns the same value,
diff --git a/org/out_src_abstraction_sqlite_db.org b/org/out_src_abstraction_sqlite_db.org
index 6159fdd..9e425bf 100644
--- a/org/out_src_abstraction_sqlite_db.org
+++ b/org/out_src_abstraction_sqlite_db.org
@@ -61,7 +61,7 @@ template spineAbstractionDb() {
     } catch (Exception ex) {
     }
     string db_file = ((base_pth.chainPath(
-      doc_matters.src.doc_uid_out ~ ".abstraction.db")).asNormalizedPath).array;
+      doc_matters.src.doc_uid_out ~ ".ocda.db")).asNormalizedPath).array;
 
     /+ ↓ remove existing file to start fresh +/
     try {
diff --git a/org/spine.org b/org/spine.org
index 84e4d04..438bdd8 100644
--- a/org/spine.org
+++ b/org/spine.org
@@ -464,7 +464,7 @@ auto helpInfo = getopt(args,
   "odt",                        "open document format text",                                      &opts["odt"],
   "output",                     "=/path/to/output/dir specify where to place output",             &settings["output"],
   "ssp-round-trip",             "=/path/to/file.ssp read a .ssp back and re-emit it on stdout",   &settings["ssp-round-trip"],
-  "db-round-trip",              "=/path/to/file.abstraction.db read it back and emit .ssp on stdout", &settings["db-round-trip"],
+  "db-round-trip",              "=/path/to/file.ocda.db read it back and emit .ssp on stdout",    &settings["db-round-trip"],
   "parallel",                   "parallelisation",                                                &opts["parallel"],
   "parallel-subprocesses",      "nested parallelisation",                                         &opts["parallel-subprocesses"],
   "pdf",                        "latex output for pdfs",                                          &opts["pdf"],
@@ -593,7 +593,7 @@ if (settings["ssp-round-trip"].length > 0) {
 
 #+NAME: read_spine_ocda_db_back_into_abstraction
 #+BEGIN_SRC d
-/+ ↓ read a <doc>.abstraction.db back into the abstraction and emit it as
+/+ ↓ read a <doc>.ocda.db back into the abstraction and emit it as
      .ssp on stdout. compared against the .ssp for the same document, this
      says whether the two artefacts really do carry the same thing
 +/
diff --git a/org/tests_for_document_abstraction_shell_scripts.org b/org/tests_for_document_abstraction_shell_scripts.org
index 100ea57..ec8bbc9 100644
--- a/org/tests_for_document_abstraction_shell_scripts.org
+++ b/org/tests_for_document_abstraction_shell_scripts.org
@@ -16,6 +16,103 @@
   after it) in org document. INVESTIGATE (org-mode CONFIG?) FIND & FIX
 
 * test shell scripts document abstraction
+** run tests
+
+#+HEADER: :tangle ../test/run-tests.sh
+#+HEADER: :tangle-mode (identity #o755)
+#+HEADER: :shebang "#!/usr/bin/env sh"
+#+BEGIN_SRC shell
+# run-tests.sh
+#
+# Runs the abstraction tests in sequence and reports one line each.
+#
+# Usage:
+#   SpinePOD=../../markup/sisudoc-spine-samples/markup/pod-samples/pod \
+#     ./test/run-tests.sh ./bin/spine-ldc
+#
+# sqlite3 is needed by two of the four. If it is not on PATH the script says
+# so and re-runs itself inside a nix shell that has it, so this works:
+#   SpinePOD=... ./test/run-tests.sh ./bin/spine-ldc
+#
+# Exit codes:
+#   0  every test passed
+#   n  the number of tests that failed
+#   2  set-up problem (no $SpinePOD, no binary)
+#
+# Order, and what depends on what:
+#
+#   1 test-abstraction-ssp.sh            the abstraction has not changed
+#   2 test-abstraction-ssp-roundtrip.sh  the .ssp can be read back whole
+#   3 test-abstraction-db.sh             the two serialisations agree
+#   4 test-abstraction-db-roundtrip.sh   the .db can be read back whole
+#
+# None of them calls another, and each can be run on its own. The order
+# matters only for reading the result:
+#
+#   - 1 is first because it is the one that says whether the abstraction
+#     itself moved. If it fails, the others are answering a different
+#     question than you think, and its failure is the one to look at.
+#   - 2 reads the committed reference set, so it is only a statement about
+#     the current binary if 1 passes. Run together, they say: the abstraction
+#     is unchanged, and this binary can read that abstraction back.
+#   - 3 and 4 generate both artefacts themselves and depend on nothing
+#     committed. Since the database is built from the .ssp, they are checks
+#     on the reader rather than on two independent writers.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SPINE_BIN="${1:-}"
+
+if [ -z "$SpinePOD" ]; then
+  echo "ERROR: \$SpinePOD is not set." >&2
+  echo "  e.g. SpinePOD=../../markup/sisudoc-spine-samples/markup/pod-samples/pod" >&2
+  exit 2
+fi
+
+if ! command -v sqlite3 > /dev/null 2>&1; then
+  if command -v nix > /dev/null 2>&1; then
+    echo "sqlite3 not on PATH, re-running inside nix shell \"nixpkgs#sqlite\""
+    exec nix shell "nixpkgs#sqlite" -c "$0" "$@"
+  fi
+  echo "ERROR: sqlite3 not on PATH and nix not available." >&2
+  exit 2
+fi
+
+TESTS="test-abstraction-ssp.sh
+test-abstraction-ssp-roundtrip.sh
+test-abstraction-db.sh
+test-abstraction-db-roundtrip.sh"
+
+PASSED=0
+FAILED=0
+RESULTS=""
+
+for t in $TESTS; do
+  printf '%s\n' "── $t"
+  if sh "$SCRIPT_DIR/$t" $SPINE_BIN 2>&1 | sed 's/^/   /'; then
+    PASSED=$((PASSED + 1))
+    RESULTS="$RESULTS
+  ok    $t"
+  else
+    FAILED=$((FAILED + 1))
+    RESULTS="$RESULTS
+  FAIL  $t"
+  fi
+done
+
+echo ""
+echo "summary:$RESULTS"
+echo ""
+if [ "$FAILED" -eq 0 ]; then
+  echo "PASS: $PASSED of $PASSED"
+  exit 0
+else
+  echo "FAIL: $FAILED of $((PASSED + FAILED))"
+  exit "$FAILED"
+fi
+#+END_SRC
+
 ** ssp document abstraction test/test-abstraction-ssp.sh
 
 #+HEADER: :tangle ../test/test-abstraction-ssp.sh
@@ -211,7 +308,7 @@ fi
 # test-abstraction-db.sh
 #
 # Cross-check for spine's two serialisations of the document abstraction:
-# the .ssp text file and the <doc>.abstraction.db sqlite database.
+# the .ssp text file and the <doc>.ocda.db sqlite database.
 #
 # It generates both for every sample document and asserts that they agree
 # object for object and field for field. There is no committed reference
@@ -272,7 +369,7 @@ OUT_DIR="$SCRIPT_DIR/current-db"
 
 echo "spine binary: $SPINE_BIN"
 echo "samples: $SAMPLES_DIR"
-echo "Generating .ssp and .abstraction.db ..."
+echo "Generating .ssp and .ocda.db ..."
 rm -rf "$OUT_DIR"
 mkdir -p "$OUT_DIR"
 $SPINE_BIN --show-abstraction --show-abstraction-db --skip-output \
@@ -332,7 +429,7 @@ report() { echo "  MISMATCH $1: .ssp $2, db $3"; }
 
 for ssp in "$OUT_DIR"/*/abstraction/*.ssp; do
   [ -f "$ssp" ] || continue
-  db="${ssp%.ssp}.abstraction.db"
+  db="${ssp%.ssp}.ocda.db"
   base=$(basename "$ssp" .ssp)
   if [ ! -f "$db" ]; then
     echo "MISSING db for $base"
@@ -431,7 +528,7 @@ done
 rm -rf "$OUT_DIR"
 
 if [ "$FAILURES" -eq 0 ]; then
-  echo "PASS: .ssp and .abstraction.db agree for all $DOCS documents"
+  echo "PASS: .ssp and .ocda.db agree for all $DOCS documents"
   exit 0
 else
   echo "FAIL: $FAILURES document(s) disagree"
@@ -537,7 +634,7 @@ fi
 #+BEGIN_SRC shell
 # test-abstraction-db-roundtrip.sh
 #
-# Reads each <doc>.abstraction.db back into the abstraction, emits it as
+# Reads each <doc>.ocda.db back into the abstraction, emits it as
 # .ssp, and requires the result to be byte identical to the .ssp written
 # from the same document.
 #
@@ -592,15 +689,15 @@ mkdir -p "$OUT_DIR"
 
 echo "spine binary: $SPINE_BIN"
 echo "samples: $SAMPLES_DIR"
-echo "Generating .ssp and .abstraction.db ..."
+echo "Generating .ssp and .ocda.db ..."
 $SPINE_BIN --show-abstraction --show-abstraction-db --skip-output \
   --output="$OUT_DIR" "$SAMPLES_DIR"/* 2>&1 | tail -1
 
 COUNT=0
 FAILURES=0
-for db in "$OUT_DIR"/*/abstraction/*.abstraction.db; do
+for db in "$OUT_DIR"/*/abstraction/*.ocda.db; do
   [ -f "$db" ] || continue
-  ssp="${db%.abstraction.db}.ssp"
+  ssp="${db%.ocda.db}.ssp"
   base=$(basename "$ssp")
   COUNT=$((COUNT + 1))
   if [ ! -f "$ssp" ]; then