]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/architecture.md
Support XTM topic name reification (Slice 21M)
[topic-maps.git] / docs / architecture.md
1 # Boundaries and execution contracts
2
3 `topic-maps` currently contains file discovery, case records, correspondence
4 checks, result classification and JSON reporting. `topic-maps/tests` tests
5 those mechanisms. Neither system reads CTM tokens or constructs Topic Maps.
6 No test invokes a disguised or mock parser.
7
8 Future components have distinct responsibilities:
9
10 | Future system | Responsibility | Slice 0 state |
11 | --- | --- | --- |
12 | `topic-maps/ctm` | CTM syntax plus orchestration of deserialization, prefix/template context and resource resolution | Not defined |
13 | `topic-maps/tmdm` | Semantic information items, identity/merging and model invariants | Not defined |
14 | `topic-maps/cxtm` | Canonical representation of a model for comparison | Not defined |
15 | `topic-maps/tests` | Contracts and independent fixtures, later executor adapters | Implemented as infrastructure only |
16
17 CTM's syntax-to-model mapping is governed by ISO/IEC 13250-6:2010, and model
18 semantics by ISO/IEC 13250-2:2006. A later CXTM implementation must consult the
19 applicable canonicalization standard, ISO/IEC 13250-4; the current baselines
20 are testing evidence, not its normative definition. Future CTM tests will need
21 both a reader/model and a canonicalizer to establish semantic equality with a
22 baseline. A reader that merely accepts a valid file will not suffice.
23
24 No HyperDoc classes, Inspector, HyperBook, CLOG, TALA or SQLite dependency is
25 present. No live SBCL image is changed. SBCL-specific launch flags are isolated
26 in `scripts/test.sh`; the library uses ANSI Common Lisp plus ASDF/UIOP.
27 `src/filesystem.lisp` isolates UIOP directory/path utilities because ANSI Common
28 Lisp lacks a portable recursive filesystem traversal operation. ASDF locates
29 project resources. SHA-256 verification is an external maintenance operation
30 using Python's standard library, not a dependency loaded into Lisp.
31
32 ## Document-IRI policy
33
34 Every imported case receives this explicit logical absolute Document IRI:
35
36 ```
37 https://ctm-tests.example.invalid/<pinned-commit>/<case-id>
38 ```
39
40 For example, `ctm/in/simple.ctm` gets
41 `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/ctm/in/simple.ctm`.
42 These are test execution inputs, not productive Subject Identifiers or web
43 endpoints. No request is made to them. `.invalid` deliberately prevents any
44 assumption of a real host. Case IDs are upstream-relative pathnames; the
45 revision is carried by corpus metadata and by the Document IRI.
46
47 Source pathnames can change when the checkout moves; Document IRIs cannot.
48 JSON pathnames are relative to `vendor/cxtm`, avoiding machine-specific paths.
49 `discover-corpus :document-base ...` allows an explicit alternate absolute
50 HTTP(S) directory IRI. No base is silently constructed from a temporary path.
51 The narrow fixture-IRI assignment is not a CTM IRI resolver: it performs no
52 percent decoding, URI normalization or CTM identifier interpretation.
53
54 CTM §3.2 makes the Document IRI an input to deserialization; §§3.3.3 and 3.3.6
55 use it for references and local identifiers. The clause links are in coverage.
56 A future executor must pass the recorded IRI, not the input's file URL, to the
57 reader. Its resource adapter will map the reported logical resource IRIs to
58 local pinned `.sub`/`.sub2` resources, including XML where supplied. The adapter
59 must preserve relative-reference behavior and restrict acquisition to local
60 fixtures during conformance testing. None of that executor is implemented here.
61
62 Baselines contain relative locators such as `#topic`. A future canonicalizer
63 must apply the standard's rules with the same Document-IRI context; this slice
64 does not normalize baselines, turn them into models or claim that the chosen
65 policy already produces matching canonical output. Absolute/relative reference
66 cases are among the proposed Slice 1 tests.
67
68 ## Outcomes are supplied, never inferred from missing implementation
69
70 Imported valid cases expect `:CXTM-EQUAL`; invalid cases expect
71 `:CTM-REJECTION`. At discovery, actual outcome is NIL and status is `:NOT-RUN`.
72 `record-result` classifies an executor-supplied result; it executes nothing.
73
74 | Supplied outcome | Expected CXTM equality | Expected CTM rejection |
75 | --- | --- | --- |
76 | `:CXTM-MATCH` | PASS | FAIL |
77 | `:CXTM-MISMATCH` | FAIL | FAIL |
78 | `:CTM-REJECTION` | FAIL | PASS |
79 | `:CTM-ACCEPTANCE` | FAIL | FAIL |
80 | `:UNSUPPORTED` | UNSUPPORTED | UNSUPPORTED |
81 | `:EXECUTION-ERROR` | FAIL | FAIL |
82 | No execution / `reset-result` | NOT-RUN | NOT-RUN |
83
84 An identified CTM syntax or semantic rejection is distinct from an unsupported
85 feature and from I/O/runtime failure. Exceptions must not automatically count
86 as successful invalid tests. A future adapter must classify them explicitly.
87 Recorded diagnostics survive until reset. Infrastructure fixtures exercise the
88 protocol using supplied outcomes without examining or recognizing CTM text.
89 Filesystem fixtures deliberately omit a baseline and include an orphan;
90 correspondence problems are reported without pretending any CTM was executed.
91
92 Reviewed specification clauses are stored in `references/reviewed-clauses.sexp`.
93 Other records have an empty clause list, meaning review pending. No mapping is
94 inferred from a filename alone. JSON encodes keywords as lowercase status
95 strings; the Lisp records retain the requested keyword statuses.