]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/slice-13-validation.md
feat(xtm): support item identifiers on name variants
[topic-maps.git] / docs / slice-13-validation.md
1 # Slice 13 validation — Scope
2
3 Implemented on `codex/ctm-slice-13`, parent
4 `788899aea1a20b9cd8237c6106e6613e180d7362`. The initial checkout was clean on
5 `codex/ctm-slice-12a`, tree `ecfec2c84faa95352ea3ad012cec5a2bc72fa98f`.
6 The pinned corpus is unchanged at `cd165b150176c1d6842b37be9cc9051b40d4996b`.
7 No HyperDoc source or runtime was changed.
8
9 ## Current evidence
10
11 `reports/slice-13/execution.json` records UTC start/finish, exact execution
12 command, runtime, source hashes, unchanged protected files, imported status
13 transitions and artifact hashes. It represents the current local execution,
14 not merely a historical PASS. `tests.log` retains the actual output;
15 `describe.log` records execution of the reading document's inspection forms.
16
17 One fresh SBCL 2.5.4 process ran the complete retained suite, offline under
18 `(deny network*)`, followed by independent Python report/model/CXTM checks.
19 A separate fresh offline process executed the documented inspection example.
20 No additional SBCL version, checkout relocation or cache-management work was used.
21 The existing fresh-process launcher and its unchanged output translations were reused.
22
23 | Regression family | Passed checks |
24 | --- | ---: |
25 | Foundation | 54 |
26 | Topic Identity | 123 |
27 | Topic Merging | 646 |
28 | Associations / Roles | 657 |
29 | Initial CXTM | 445 |
30 | Occurrences | 1,101 |
31 | Prefixes / explicit datatypes | 150 |
32 | Integers | 665 |
33 | Decimals | 715 |
34 | Dates | 1,806 |
35 | DateTimes | 217 |
36 | Timezone canonicalization | 1,944 |
37 | Explicitly typed Names | 106 |
38 | Scope | 293 |
39 | **Total Lisp checks** | **8,922** |
40
41 Zero assertion failures. Two Python infrastructure fixtures and 16,294
42 independent NFC comparisons also pass. Independent validators pass for all
43 retained report families and the new Scope model/ordering witness.
44
45 Historical assertions that Scope syntax was unsupported were adapted explicitly:
46 valid scoped Name/Occurrence/Association inputs now assert actual deserialization;
47 Scope directly on a bare Topic asserts CTM rejection. The previous check totals
48 are retained, and other excluded constructs still assert unsupported conditions.
49
50 ## Original contracts
51
52 | Original source | Expected bytes = actual bytes | Result |
53 | --- | ---: | --- |
54 | `ctm/in/name-scope.ctm` | 615 | PASS |
55 | `ctm/in/occurrence-scope.ctm` | 646 | PASS |
56 | `ctm/in/association-scope.ctm` | 794 | PASS |
57
58 Only these three imported records transition from NOT-RUN to PASS.
59 All 58 previously executed CXTM records retain byte-identical actual/expected
60 outputs and outcomes. Those records comprise 56 matches and two known mismatches.
61 The independent check now verifies 59 matches and two documented DateTime
62 mismatches against original baselines. All eight prior negative CTM contracts pass.
63
64 Imported totals: **67 PASS, 2 FAIL, 0 UNSUPPORTED, 204 NOT-RUN**.
65 The two FAILs remain `occurrence-datetime2.ctm` and
66 `occurrence-datetime-timezone2.ctm`. No baseline was rewritten and no semantic
67 assertion was substituted for a CXTM comparison. Other Scope-related imported
68 contracts involving Embedded Topics, Templates, Variants or Reification remain
69 NOT-RUN; local unsupported probes do not promote their status.
70
71 `scopes.json` records actual source strings, Document IRIs, Topic identifier sets,
72 item properties and object-reference ordinals. Lisp assertions separately verify
73 EQ identity, Parent/Type/Player links and current raw Scope references.
74 `scripts/check-scopes.py` independently resolves those ordinals to identifier sets
75 and compares the relationships with the original XML. It also checks a separate
76 ordering witness without invoking the Lisp comparators as its oracle.
77
78 ## Merge, boundary and mutation controls
79
80 - Empty, single-theme and multiple-theme Scopes; duplicate and reordered inputs.
81 - Different Scope sets keep otherwise equal items distinct.
82 - Theme merging reduces `{A,B}` to `{C}` and `{A,B,Z}` to `{C,Z}` for each item kind.
83 Equal items then merge, and retained Name/Occurrence/Association/Role handles
84 resolve to the current representatives. Distinct remaining Scopes stay distinct.
85 - All six orders of transitive merging of three themes leave one canonical
86 Theme reference per Scope. Both directions of the two-theme merge are tested.
87 - Parent, Type, Role Type and Player may alias a Theme and remain current when
88 that Theme merges. Binary Associations also retain their Roles/Scope.
89 - Occurrence duplicate merging unions Item Identifiers in their own category.
90 Reusing an identifier with an unequal Scope is refused before mutation.
91 - Invalid finite/improper/circular lists, non-Topics and foreign-map Themes are
92 refused without model changes. Invalid default-Name Scope creates no type Topic.
93 Both caller-owned input lists and returned lists are detached from stored sets.
94 - Reader tests cover identifiers, QName/IRI references, Subject Locators and
95 explicit Item Identifiers, comments, Unicode, adjacent `@`, numeric/date/string
96 boundaries, and quoted explicit datatypes. Full Scope is known before creating
97 the Name/Occurrence/Association and performing duplicate normalization.
98 - Specific diagnostics include missing themes, trailing/doubled commas, invalid
99 Theme tokens, undefined prefixes and misplaced Scope, with offset/line/column.
100 Excluded features still signal unsupported conditions.
101 - Twenty-four item-construction permutations produce identical CXTM. Scope-set
102 cardinality and member ordering, all Topic references and RolePlayed references
103 are checked. Serialization preserves both live model state and retained handles.
104 - Corrupt internal Scope references (retired, foreign or duplicate Themes) are
105 explicitly rejected by the canonicalizer without normalizing the input.
106
107 Normative clauses, actual item relationships, API and executable inspection are
108 in [Reading Scope](reading-scope.md). No full CTM/TMDM conformity is claimed.
109
110 ## Reproduction
111
112 From the repository, using the existing installed development SBCL:
113
114 ```sh
115 PYTHONDONTWRITEBYTECODE=1 SBCL=/path/to/sbcl \
116 TOPIC_MAPS_REPORT=/tmp/topic-maps-slice-13.json \
117 sandbox-exec -p '(version 1)(allow default)(deny network*)' ./scripts/test.sh
118 ```
119
120 To reproduce this slice's evidence and the documentation inspection:
121
122 ```sh
123 PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate-slice-13.py \
124 --sbcl /path/to/sbcl --output /tmp/topic-maps-slice-13-evidence
125 ```
126
127 This command records a new execution in the selected output directory; it does
128 not import anything or change corpus baselines. Exact runtime and commands for
129 the delivered run are recorded in `reports/slice-13/execution.json`.
130
131 Scope support is complete only for the agreed identity-reference subset.
132 Embedded Topics, wildcards, Variants, Templates, Reification and cross-document
133 merging remain outside this slice. The HyperDoc Work-Topic representation question
134 remains separate. No next slice, server, push or deployment was started.