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)

1 files changed, 90 insertions, 0 deletions

diff --git a/test/run-tests.sh b/test/run-tests.sh
new file mode 100755
index 0000000..c8869d8
--- /dev/null
+++ b/test/run-tests.sh
@@ -0,0 +1,90 @@
+#!/usr/bin/env sh
+# 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