test: database to pod to artefacts

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)

1 files changed, 191 insertions, 2 deletions

diff --git a/org/tests_for_document_abstraction_shell_scripts.org b/org/tests_for_document_abstraction_shell_scripts.org
index ab2dc35..d62bf17 100644
--- a/org/tests_for_document_abstraction_shell_scripts.org
+++ b/org/tests_for_document_abstraction_shell_scripts.org
@@ -46,7 +46,8 @@
 #   3 test-abstraction-db.sh             the two serialisations agree
 #   4 test-abstraction-db-roundtrip.sh   the .db can be read back whole
 #   5 test-ocn-alignment.sh              the languages agree on their ocns
-#   6 test-epub-validity.sh              the epubs a reader can actually open
+#   6 test-acceptance-db-to-pod.sh       a database gives its document back
+#   7 test-epub-validity.sh              the epubs a reader can actually open
 #
 # None of them calls another, and each can be run on its own. The order
 # matters only for reading the result:
@@ -65,6 +66,13 @@
 #     translations and reports nothing about the other documents. It will
 #     fail if those translations are mended, which is the right moment to
 #     hear about it.
+#   - 6 is the acceptance test for the document source claim, and the widest
+#     of them: it builds a document from its pod and again from the database
+#     that build produced, and requires the two output trees to be identical.
+#     Where 3 and 4 check one serialisation against another, this checks a
+#     whole document through the whole pipeline twice. If it fails and the
+#     others pass, what broke is the carrying or the materialising rather
+#     than the abstraction.
 
 set -e
 
@@ -91,6 +99,7 @@ test-abstraction-ssp-roundtrip.sh
 test-abstraction-db.sh
 test-abstraction-db-roundtrip.sh
 test-ocn-alignment.sh
+test-acceptance-db-to-pod.sh
 test-epub-validity.sh"
 
 PASSED=0
@@ -1073,7 +1082,186 @@ else
   exit 1
 fi
 #+END_SRC
-** 6. test epub validity
+** 6. test acceptance db to pod
+
+#+HEADER: :tangle ../test/test-acceptance-db-to-pod.sh
+#+HEADER: :tangle-mode (identity #o755)
+#+HEADER: :shebang "#!/usr/bin/env sh"
+#+BEGIN_SRC shell
+# test-acceptance-db-to-pod.sh
+#
+# The acceptance test for the document source claim: a .ocda.db carries
+# everything a pod does, so a pod written back out of it builds the same
+# document.
+#
+# Two runs of the same spine, with the same flags, over the same document:
+#
+#   A   the pod            ->  artefacts and outputs
+#   B   A's database       ->  pod  ->  artefacts and outputs
+#
+# and `diff -r` between the two output trees must be empty. That single
+# comparison covers more than it appears: the written pod tree (markup, conf,
+# images, translation catalogues), the .ssp files, the .ocda.db itself, the
+# digests.txt, and the text, html and epub built from them.
+#
+# Two things the runs must share for the comparison to mean anything:
+#
+#   the site configuration. The abstraction depends only on pod content,
+#     but a document's metadata pages carry the site's url, which comes from
+#     a .dr/config_local_site found *above* the pod. A materialised pod sits
+#     in a directory of the run's making with no such file, so the pod for
+#     run A is copied out of the sample set to a neutral place rather than
+#     read where it lies. Without that, a sound comparison shows ~22 files
+#     differing in a url and reads as corruption.
+#
+#   the flags.  The dom structure tags the .ssp records are computed only
+#     when an action needs them, so two runs asking for different things
+#     build different abstractions from the same markup. Both runs here ask
+#     for the same set.
+#
+# Not compared: the pod archive. --pod is not asked for, so neither run
+# writes one. The archive is a container around bytes that are compared
+# here already, and its own bytes are not part of what the database claims
+# to carry.
+#
+# Also asserted: --ocda-verify passes on the database, which is the other
+# half of the claim. The comparison says the pod comes back; verify says the
+# abstraction it makes is the one recorded with it.
+#
+# Usage:
+#   SpinePOD=../../markup/sisudoc-spine-samples/markup/pod-samples/pod \
+#     ./test/test-acceptance-db-to-pod.sh ./bin/spine-ldc
+#
+# Exit codes:
+#   0  every document round trips with no difference
+#   1  differences found (printed)
+#   2  set-up problem (no $SpinePOD, no binary, no samples)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SPINE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+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
+SAMPLES_RAW="$SPINE_DIR/$SpinePOD"
+if [ -d "$SAMPLES_RAW" ]; then
+  SAMPLES_DIR="$(cd "$SAMPLES_RAW" && pwd)"
+else
+  SAMPLES_DIR="$SAMPLES_RAW"
+fi
+if [ ! -d "$SAMPLES_DIR" ]; then
+  echo "ERROR: sample documents not found at $SAMPLES_DIR" >&2
+  exit 2
+fi
+
+SPINE_BIN="${1:-}"
+if [ -z "$SPINE_BIN" ]; then
+  if   [ -x "$SPINE_DIR/result/bin/spine" ]; then SPINE_BIN="$SPINE_DIR/result/bin/spine"
+  elif [ -x "$SPINE_DIR/bin/spine-ldc" ];    then SPINE_BIN="$SPINE_DIR/bin/spine-ldc"
+  elif [ -x "$SPINE_DIR/bin/spine" ];        then SPINE_BIN="$SPINE_DIR/bin/spine"
+  else
+    echo "ERROR: spine binary not found. Specify path as argument." >&2
+    exit 2
+  fi
+fi
+
+# the documents to round trip. live-manual is the one that exercises every
+# part: ten languages, inserts, and a tools/po4a catalogue tree. The second
+# has images, which live-manual has none of, and is a single language.
+DOCS="${SpineAcceptanceDocs:-live-manual the_wealth_of_networks.yochai_benkler}"
+
+# the same flags for both runs: the pod tree, both abstraction artefacts, and
+# three output formats over them
+FLAGS="--source --show-abstraction --ocda-db --text --html --epub"
+
+OUT_DIR="$SCRIPT_DIR/current-acceptance"
+rm -rf "$OUT_DIR"
+mkdir -p "$OUT_DIR/pods"
+
+echo "spine binary: $SPINE_BIN"
+echo "samples: $SAMPLES_DIR"
+
+FAILURES=0
+DOCS_DONE=0
+
+for doc in $DOCS; do
+  if [ ! -d "$SAMPLES_DIR/$doc" ]; then
+    echo "MISSING sample: $doc"
+    FAILURES=$((FAILURES + 1))
+    continue
+  fi
+  echo "── $doc"
+
+  # the pod, copied where no .dr/ sits above it
+  cp -a "$SAMPLES_DIR/$doc" "$OUT_DIR/pods/$doc"
+
+  # A: from the pod
+  if ! $SPINE_BIN $FLAGS --output="$OUT_DIR/a.$doc" "$OUT_DIR/pods/$doc" \
+      > "$OUT_DIR/a.$doc.out" 2> "$OUT_DIR/a.$doc.err"; then
+    echo "  FAIL: the run from the pod exited non-zero"
+    tail -3 "$OUT_DIR/a.$doc.err" | sed 's/^/    /'
+    FAILURES=$((FAILURES + 1))
+    continue
+  fi
+
+  db=$(find "$OUT_DIR/a.$doc/pod" -maxdepth 1 -name "*.ocda.db" | head -1)
+  if [ ! -f "$db" ]; then
+    echo "  FAIL: the run from the pod wrote no database"
+    FAILURES=$((FAILURES + 1))
+    continue
+  fi
+
+  # the database says the markup it carries still makes the abstraction it
+  # holds. Checked before the build, because a build from it checks the same
+  # thing and would stop; asked here on its own so that a failure says which
+  # of the two claims broke
+  if ! $SPINE_BIN --ocda-verify="$db" --output="$OUT_DIR/v.$doc" \
+      > "$OUT_DIR/v.$doc.out" 2> "$OUT_DIR/v.$doc.err"; then
+    echo "  FAIL: --ocda-verify on $(basename "$db")"
+    grep -E "no longer|records no" "$OUT_DIR/v.$doc.err" | head -3 | sed 's/^/    /'
+    FAILURES=$((FAILURES + 1))
+    continue
+  fi
+  verified=$(grep -E "^verify: " "$OUT_DIR/v.$doc.out" | head -1)
+  [ -n "$verified" ] && echo "  $verified"
+
+  # B: from the database
+  if ! $SPINE_BIN $FLAGS --output="$OUT_DIR/b.$doc" "$db" \
+      > "$OUT_DIR/b.$doc.out" 2> "$OUT_DIR/b.$doc.err"; then
+    echo "  FAIL: the run from the database exited non-zero"
+    tail -3 "$OUT_DIR/b.$doc.err" | sed 's/^/    /'
+    FAILURES=$((FAILURES + 1))
+    continue
+  fi
+
+  # and the whole of it, held against the whole of it
+  if diff -rq "$OUT_DIR/a.$doc" "$OUT_DIR/b.$doc" > "$OUT_DIR/d.$doc" 2>&1; then
+    n=$(find "$OUT_DIR/b.$doc" -type f | wc -l)
+    echo "  ok: $n files, no differences"
+    DOCS_DONE=$((DOCS_DONE + 1))
+  else
+    echo "  FAIL: $(grep -c . "$OUT_DIR/d.$doc") difference(s)"
+    head -8 "$OUT_DIR/d.$doc" | sed 's/^/    /'
+    FAILURES=$((FAILURES + 1))
+  fi
+done
+
+rm -rf "$OUT_DIR"
+
+if [ "$FAILURES" -eq 0 ]; then
+  echo "PASS: $DOCS_DONE document(s) build identically from their database"
+  exit 0
+else
+  echo "FAIL: $FAILURES document(s) do not"
+  exit 1
+fi
+#+END_SRC
+
+** 7. test epub validity
 
 #+HEADER: :tangle ../test/test-epub-validity.sh
 #+HEADER: :tangle-mode (identity #o755)
@@ -1195,6 +1383,7 @@ fi
 echo "PASS: $FATALS fatal and $ERRORS errors, both within what is recorded"
 exit 0
 #+END_SRC
+
 * collection search db + cgi form
 ** test search db schema