]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-ctm-mergemap.md
feat(ctm): support triple-quoted strings and four originals
[topic-maps.git] / docs / reading-ctm-mergemap.md
1 # Reading CTM Mergemap
2
3 Slice 19B builds on `9ce2a2b5116edfd921a5240efcb2f604f9523693`.
4 The corpus remains pinned at `cd165b150176c1d6842b37be9cc9051b40d4996b`.
5
6 ## Normative basis
7
8 [CTM §3.16.3](https://www.isotopicmaps.org/ctm/ctm.html) productions 74–75
9 require resource and notation IRI references, immediate deserialization into a
10 separate model instance and addition of its Topics/Associations. §§3.2,
11 3.3.3–3.3.5 govern document order, Document IRI, relative resolution and QNames.
12 Both CTM and XTM notation support are mandatory for a conforming processor;
13 this slice implements CTM only. Unsupported notations are errors.
14
15 [TMDM §§5–6](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
16 provide identity, item equality, reference replacement and merging; §7.1 protects
17 Core Subjects. [CXTM §3.18](https://www.isotopicmaps.org/cxtm/cxtm.html)
18 explains base-relative locators in the supplied baselines. TMDM/CXTM implementations
19 are unchanged in this slice. The published standards outrank draft-era baselines.
20
21 ## Public resolver API
22
23 `deserialize-string` and `deserialize-file` accept two additional keywords:
24
25 - `:resource-resolver`: a function or NIL (default).
26 - `:max-resource-depth`: a nonnegative integer, default 32; zero disables imports.
27
28 The resolver is called as:
29
30 `(funcall resolver absolute-resource-iri :purpose :mergemap :from-document-iri parent-document-iri :notation notation-iri)`
31
32 Return two values: an octet vector and a string source key (or NIL). Any vector
33 of integer octets 0–255 is accepted, including an empty vector. NIL as first
34 value means unavailable/declined. NIL as second value defaults the diagnostic
35 source key to the resource IRI. The key never becomes the Document IRI. The
36 resource IRI, resolved by the existing IRI/QName reader, is the imported
37 Document IRI. A local filename used as a source key does not alter identity.
38
39 No implicit file or HTTP resolver exists. `deserialize-file` reads only the
40 explicit root file; imported bytes must still be supplied by the caller.
41 A finite IRI-to-bytes table suffices, and both original and synthetic tests use
42 one. The existing strict UTF-8 decoder/BOM handling is reused; other encodings
43 remain outside the reader subset. The existing absolute, fragment-free Document
44 IRI API boundary is retained.
45
46 ## Executable public inspection
47
48 The following runs from the repository root in a fresh Lisp process. The bytes
49 `#(97 46)` are exactly the CTM document `a.`. URNs here are explicit example
50 Document IRIs, not retrievable addresses or persistent object handles.
51
52 ```lisp
53 (require :asdf)
54 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
55 (asdf:load-asd (truename "topic-maps.asd"))
56 (asdf:load-system "topic-maps/ctm")
57 (let ((calls 0))
58 (multiple-value-bind (map counter)
59 (topic-maps.ctm:deserialize-string
60 "%mergemap <urn:child> <http://psi.topicmaps.org/iso13250/ctm>"
61 :document-iri "urn:parent" :source-name "memory:parent"
62 :resource-resolver
63 (lambda (iri &key purpose from-document-iri notation)
64 (assert (string= iri "urn:child"))
65 (assert (eq purpose :mergemap))
66 (assert (string= from-document-iri "urn:parent"))
67 (assert (string= notation "http://psi.topicmaps.org/iso13250/ctm"))
68 (incf calls)
69 (values #(97 46) "memory:child")))
70 (let ((topic (first (topic-maps.tmdm:topic-map-topics map))))
71 (assert (= calls 1))
72 (assert (= counter 0))
73 (assert (eq map (topic-maps.tmdm:topic-parent topic)))
74 (assert (equal '("urn:child#a") (topic-maps.tmdm:topic-item-identifiers topic)))
75 (describe map)
76 (describe topic)
77 (format t "~&MERGEMAP-INSPECTION-PASS: actual Topic with child Document IRI; parent is the caller Map.~%"))))
78 ```
79
80 ## Actual original contracts
81
82 Every original retains its deterministic Document IRI:
83 `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/<case-id>`.
84 The finite resolver table maps the corpus auxiliary IRIs to their unchanged
85 binary files. Source keys are corpus IDs, e.g. `ctm/in/mergemap.sub`.
86
87 | Original positive contract | Resource relative to its Document IRI | Expected/observed model | CXTM bytes |
88 |---|---|---|---:|
89 | `ctm/in/mergemap.ctm` | `mergemap.sub` | 7 Topics, 2 Associations, 4 Roles | 1511 |
90 | `ctm/in/mergemap-syntax-qname.ctm` | `mergemap.sub` | Same graph; notation `syn:ctm` resolves to the CTM IRI | 1511 |
91 | `ctm/in/mergemap-template.ctm` | `mergemap-template.sub` | 7 Topics, 2 Associations, 4 Roles; independent same-named Templates | 1529 |
92 | `ctm/in/mergemap-tm-reifier.ctm` | `mergemap-tm-reifier.sub` | One ordinary Topic, no target Map Reifier | 134 |
93
94 For the first three cases, parent `#lars`/`#person` and resource-local
95 `mergemap*.sub#lars`/`mergemap*.sub#person` are four distinct actual Topics.
96 Three Core Subject Topics (type-instance, instance, type) are shared by the
97 Associations through canonical references. Each Association relates its own
98 lars/person pair. No Include identifier aliases are created. The last case
99 copies the Topic identified by `mergemap-tm-reifier.sub#tm`; its source Map's
100 Reifier edge does not become a target Map edge.
101
102 | Original negative contract | Actual required diagnostic | Resolver calls |
103 |---|---|---:|
104 | `ctm/invalid/mergemap-missing-syntax-iri.ctm` | `CTM-REJECTION :EXPECTED-MERGEMAP-NOTATION`, character 35 | 0 |
105 | `ctm/invalid/mergemap-template.ctm` | `UNDEFINED-TEMPLATE :UNDEFINED-TEMPLATE`, character 72 | 1 |
106 | `ctm/invalid/mergemap-unknown-syntax.ctm` | `CTM-REJECTION :UNKNOWN-MERGEMAP-NOTATION`, character 0 | 0 |
107
108 The invalid Template resource has key `ctm/invalid/mergemap-template.sub`, not
109 `ctm/in/mergemap-template.sub`. Its definition is parsed successfully into its
110 own register. Calling that Template in the parent fails because definitions are
111 not imported. Neither a missing file nor a premature unsupported-directive
112 error counts as this rejection.
113
114 The actual XML results are saved under `reports/slice-19b/actual/`; exact source,
115 resource arguments, observed model properties and diagnostics appear in
116 `mergemap.json`. The full CXTM report independently checks the unchanged baseline
117 bytes. These are executed original contracts, separate from synthetic model tests.
118
119 ## Execution, namespaces and diagnostics
120
121 `read-directive` dispatches the existing Prefix reader and the new Mergemap
122 reader. The latter reads both IRI references, classifies the notation, requests
123 bytes, calls the existing CTM deserializer and then calls only
124 `topic-maps.tmdm:import-map-content`. It resumes the parent parser afterwards.
125
126 A fresh child parser has independent Prefixes, Templates, named Wildcards,
127 Document IRI and default Wildcard IRI/Counter. Parent overrides are not passed as
128 child wildcard state, and the child's final Counter is not assigned to the
129 parent. The same resolver and configured depth limit remain available for nested
130 resources. Each completed repeated directive calls the resolver and deserializes
131 again; there is no global imported-resource cache.
132
133 Cycle detection checks active Document IRIs. The maximum depth and cycle policy
134 signal `CTM-UNSUPPORTED :RESOURCE-DEPTH-LIMIT` / `:CYCLIC-MERGEMAP`; these are
135 resource policies, not additional normative CTM rejection rules.
136
137 A missing resolver signals `CTM-UNSUPPORTED :RESOURCE-RESOLVER-REQUIRED`.
138 Resolver exceptions, refusal/missing bytes and invalid results respectively
139 signal `CTM-RESOURCE-ERROR :RESOURCE-RESOLVER-FAILURE`, `:RESOURCE-UNAVAILABLE`
140 and `:INVALID-RESOURCE-RESULT`. Configuration errors use the same non-rejection
141 condition family. Malformed child CTM retains its specific rejection class/code,
142 source key and character/byte location. `error-context` adds Mergemap frames with
143 parent source, Document IRI, directive position, resource IRI, notation and child
144 source key. Printed diagnostics also show this chain. Imported TMDM conflicts
145 are reported at the parent directive with their existing specific codes.
146
147 Synthetic tests instrument the real public import in the fresh process to
148 observe Source/Target objects, held handles and EQ relations, then restore its
149 function binding. Metadata tests add non-Topic Item Identifiers through the
150 TMDM API before importing; they do not claim CTM syntax for those identifiers.
151 Both successful source preservation and atomic conflict rejection are checked
152 through raw slots/handles and CXTM. The transaction boundary is the individual
153 TMDM import, not arbitrary resolver side effects or the entire document parse.
154
155 ## Remaining limits
156
157 The standard XTM IRI is recognized as `CTM-UNSUPPORTED :XTM-MERGEMAP-NOTATION`;
158 `mergemap-xtm.ctm` remains NOT-RUN. This is partial CTM support, not full processor
159 conformance. `%include`, Include aliases, Template transport and XTM parsing
160 remain unimplemented. The two Include norm/corpus questions recorded in the
161 Slice 19 investigation remain explicitly open; this slice makes no finding
162 that resolves either one. The two known DateTime baseline FAILs are unchanged.