]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/validation.md
docs: design draft for a read-only SHOP3 adapter over TMDM objects
[topic-maps.git] / docs / validation.md
1 # Slice 0 validation and handoff
2
3 **Ready for Slice 1: Yes.** This confirms the foundation is ready for review,
4 not that CTM is implemented. Slice 1 has not started. No reader, semantic model
5 or canonicalizer is present; all imported CTM cases remain NOT-RUN.
6
7 The imported suite targets the **CTM draft dated 2010-03-31**. Passing it alone
8 would not establish full ISO/IEC 13250-6:2010 conformity. Published ISO standards
9 remain normative; the corpus and Ontopia are independent evidence.
10
11 ## Observed results
12
13 | Check | Observed result |
14 | --- | --- |
15 | Complete vendored corpus integrity | All 2,006 original files match the pinned path/size/SHA-256 manifest |
16 | CTM inventory | 231 valid; 42 invalid; 231 baselines; 22 auxiliaries |
17 | Baseline correspondence | No missing input, missing baseline, unmatched baseline or duplicate case ID |
18 | Common Lisp infrastructure | 54 checks pass in fresh plain SBCL processes |
19 | Python integrity fixtures | 2 tests pass, including changed bytes, missing/extra files and incomplete correspondence |
20 | Independent report decoding | Standard-library JSON check passes, including all contracts and statuses |
21 | Imported CTM execution | 273 NOT-RUN; 0 PASS, 0 FAIL, 0 UNSUPPORTED |
22 | No implementation systems | `topic-maps/ctm`, `/tmdm` and `/cxtm` are not defined |
23 | Offline execution | OS sandbox denies network for the full test process |
24 | Relocated checkout | SBCL 2.4.10 reproduces the SBCL 2.5.4 report byte-for-byte at a different root |
25 | Primary ASDF test-op | `asdf:test-system "topic-maps"` routes to the passing infrastructure tests |
26 | Acquisition idempotence | Existing pinned corpus verified; nothing overwritten, no network |
27 | Nix shell | Pinned independent shell evaluates offline; no Nix build claimed |
28 | Existing HyperDoc checkouts | Both remain clean at their observed HEADs |
29
30 The successful final logs and exact environment/commands are stored in
31 [execution.json](../reports/execution.json), with SHA-256 digests.
32 [validation.json](../reports/validation.json) is the raw reproducible Lisp output,
33 including every case and the actual passing infrastructure-check names.
34 The checks test state transitions on independent fixtures; those outcomes are
35 not reported as upstream CTM conformance successes.
36
37 ## Commands actually used
38
39 From `/Users/rgb/workspace/topic-maps`:
40
41 ```sh
42 /usr/bin/sandbox-exec -p '(version 1)(allow default)(deny network*)' \
43 /usr/bin/env \
44 SBCL=/nix/store/hlsiblxpxr1hax3dw9x8znd6zy097ddj-sbcl-2.5.4/bin/sbcl \
45 TOPIC_MAPS_REPORT=/private/tmp/ctm-slice-0-report-final.json \
46 scripts/test.sh
47 ```
48
49 A copy of the project, excluding `.git` and Python caches, was placed at
50 `/private/tmp/ctm-slice-0-relocated`. Its final standard package-import test
51 files were updated before the final relocated run:
52
53 ```sh
54 /usr/bin/sandbox-exec -p '(version 1)(allow default)(deny network*)' \
55 /usr/bin/env \
56 SBCL=/nix/store/y96nx8571mpdvjd40krkdim2av0in972-sbcl-2.4.10/bin/sbcl \
57 TOPIC_MAPS_REPORT=/private/tmp/ctm-slice-0-report-relocated.json \
58 /private/tmp/ctm-slice-0-relocated/scripts/test.sh
59
60 cmp reports/validation.json /private/tmp/ctm-slice-0-report-relocated.json
61 ```
62
63 Both test commands and `cmp` exited zero. The macOS sandbox restriction is an
64 acceptance executor, not a library dependency. On other platforms use an
65 appropriate network-denial executor if required; `scripts/test.sh` itself does
66 not use the network. SBCL and Python must already be installed.
67
68 Also verified:
69
70 ```sh
71 python3 scripts/corpus.py acquire
72 python3 -m py_compile scripts/corpus.py scripts/check-report.py tests/test_corpus.py
73 nix eval --offline --raw \
74 'path:/Users/rgb/workspace/topic-maps#devShells.x86_64-darwin.default.name'
75 ```
76
77 The first command detects the already-present exact corpus and performs no
78 acquisition or write. The Nix command returned `nix-shell`. A separate fresh
79 SBCL process loaded `topic-maps.asd` with no inherited source registry and ran
80 `asdf:test-system "topic-maps"`; its complete command is recorded in execution.
81 No long-running Lisp image was modified, and no server, browser application,
82 SSH connection or deployment was started.
83
84 ## Repository and commit
85
86 Worktree/repository: `/Users/rgb/workspace/topic-maps`.
87 Branch: `codex/ctm-slice-0`.
88 Base: empty independent repository, no parent commit. The delivery is the root
89 commit, created only after the infrastructure tests passed. Retrieve its exact
90 SHA with:
91
92 ```sh
93 git -C /Users/rgb/workspace/topic-maps rev-parse HEAD
94 ```
95
96 A commit cannot contain its own hash without circularity; the final handoff
97 reports the observed delivery SHA. Implementation, infrastructure tests,
98 reference locks, original corpus and reports are delivered in that one commit.
99 The five proposed semantic cases and their rationale are in
100 [coverage.md](coverage.md). Review this foundation before authorizing Slice 1.
101
102 The staged upstream tree was also compared with the original Git tree: all
103 2,006 Git blobs match exactly. Whole-tree whitespace checking flags original
104 upstream text and deliberately significant whitespace in baselines; those bytes
105 are retained. Whitespace checking of authored files passes separately.