]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-type-relationships.md
Document Topic Maps conformance closure plan for Slice 22A
[topic-maps.git] / docs / reading-type-relationships.md
1 # Reading isa, ako and Core Subject Consistency
2
3 Slice 17B starts from `bdc56a8236c6e6180df217d37e82846025026096`.
4 It uses the same seven information-item structures, ordinary Topic references,
5 Association/Role constructors, replacement handles and canonical serializer.
6
7 ## Normative requirements and the exact vocabulary
8
9 [CTM §3.9](https://www.isotopicmaps.org/ctm/ctm.html#sec-topic-tail),
10 productions 50–55, defines `isa topic-ref` and `ako topic-ref` as Topic Tail
11 elements. Each has one right-hand reference; repeated statements are separated
12 by semicolons. The common resolver also admits QNames, explicit SI/SL/II forms,
13 Wildcards and recursive Embedded Topics (§§3.3.6–3.3.8).
14
15 [TMDM §7.1](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
16 requires the Core Subjects defined in §7 to be distinct. Their published
17 Subject Identifiers use `http://psi.topicmaps.org/iso13250/model/` plus:
18
19 | Clause | Local parts |
20 |---|---|
21 | 7.2 | `type-instance`, `type`, `instance` |
22 | 7.3 | `supertype-subtype`, `supertype`, `subtype` |
23 | 7.4 | `sort` |
24 | 7.5 | `name-type` |
25
26 The protected set therefore has eight locators, including all six used by these
27 relationships. These constants are not Topic objects or another identity index.
28 `core-subject-identifiers` returns private copies of their strings.
29
30 The cited 2006 text spells §7.5's locator `.../name-type`. CTM §3.11 and the
31 accepted existing default Name mapping use `.../topic-name`. This slice does not
32 infer an alias between those two strings, rewrite existing Name Types, or extend
33 the protected set by guessing. All retained Name results stay unchanged.
34
35 The expansion mandated by TMDM §§7.2–7.3 is:
36
37 | Input | Association Type SI local part | Role Type SI → Player |
38 |---|---|---|
39 | `a isa b.` | `type-instance` | `instance → a`, `type → b` |
40 | `a ako b.` | `supertype-subtype` | `subtype → a`, `supertype → b` |
41
42 Each expansion has exactly two Role items, empty Scope and null Reifier.
43 Normal Associations remain n-ary. A differently structured Association using
44 these Subjects does not become a standardized relationship merely by its type.
45 No special Topic slots or another type hierarchy representation are introduced.
46
47 `isa` is not transitive. `ako` is transitive, but TMDM §7.3 does not require
48 materializing inferred Associations. Cycles do not imply Topic identity. Only
49 explicitly deserialized relationships are stored here. This is not a query or
50 inference engine.
51
52 ## Identity, equality, merging and API policy
53
54 TMDM §§5.3.5, 5.7–5.8 and 6.2/6.6–6.7 remain the identity/equality/merge rules.
55 Short and long Association syntax normalize to the same canonical items.
56 Subject Identifiers of distinct Core Subjects must never occur on one Topic.
57 The guard compares actual locator strings in that property, not CXTM-normalized
58 strings or an IRI merely occurring in a Subject Locator/Item Identifier slot.
59 An Item Identifier can nevertheless cause a conflict through the existing
60 SI/II Topic identity rule; this is checked before committing the mutation.
61
62 The public failure is `core-subject-error`, code `:core-subject-conflict`.
63 The affected operations are `merge-topics`, `add-topic-identifier` (also reached
64 by Topic `add-item-identifier`), `intern-topic`, `normalize-topic-map`, and
65 Reifier-triggered merging via `set-item-reifier`. `intern-topic` preflights
66 before appending a new Topic. Old handles still resolve through the existing
67 canonical accessors. Valid alias merges of the same Core Subject remain legal.
68
69 **Normative invariant:** the contradictory Core Subject state is forbidden.
70 **Local API policy:** reject the whole semantic operation before changing any
71 original item, identifier list or forward link. The existing disposable copy
72 of the same TMDM graph now covers Core conflicts as well as Reifier cascades;
73 its internal entry points are `needs-merge-preflight-p` and
74 `preflight-merge-mutation`. It is not a second model or a rollback engine, and
75 does not promise recovery from resource exhaustion. White-box normalization
76 tests explicitly identify intentionally unnormalized initial graphs.
77
78 The CTM layer reports Core conflicts as `ctm-rejection/:core-subject-conflict`.
79 Missing relationship targets and comma lists have dedicated rejection codes
80 and source positions; undefined prefixes retain their own condition class.
81 The CXTM validator rejects a deliberately corrupted Core state without mutation.
82 CXTM §§3.9–3.10 and 4.10–4.11 still supply the unchanged representation/sort rules:
83 [published CXTM](https://www.isotopicmaps.org/cxtm/cxtm.html).
84
85 ## Original contracts and current object observations
86
87 All sources/baselines are the untouched pinned corpus at
88 `cd165b150176c1d6842b37be9cc9051b40d4996b`. Its CTM tests target the draft of
89 2010-03-31; the published standards remain authoritative. For every row the
90 Document IRI is `https://ctm-tests.example.invalid/` + pin + `/ctm/in/` + filename.
91 Local Item Identifiers append `#identifier` to that absolute Document IRI.
92 The existing CXTM base-locator policy produces the relative locators in the
93 supplied baselines; no baseline or comparison normalization was changed.
94
95 | File | Topics | Associations | Actual/expected CXTM bytes |
96 |---|---:|---:|---:|
97 | `isa-relationship.ctm` | 5 | 1 | 963 / 963 |
98 | `isa-relationship-duplicate.ctm` | 5 | 1 | 963 / 963 |
99 | `isa-relationship-duplicate2.ctm` | 5 | 1 | 963 / 963 |
100 | `isa-relationship-embedded.ctm` | 6 | 1 | 1,181 / 1,181 |
101 | `isa-relationship-type-qname.ctm` | 5 | 1 | 991 / 991 |
102 | `ako-relationship.ctm` | 5 | 1 | 977 / 977 |
103 | `ako-relationship-duplicate.ctm` | 5 | 1 | 977 / 977 |
104 | `ako-relationship-duplicate2.ctm` | 5 | 1 | 977 / 977 |
105 | `ako-relationship-embedded.ctm` | 6 | 1 | 1,190 / 1,190 |
106 | `ako-relationship-supertype-qname.ctm` | 5 | 1 | 1,005 / 1,005 |
107 | `ako-merge-away.ctm` | 6 | 2 | 1,590 / 1,590 |
108 | `subject-identifier-topicref.ctm` | 5 | 1 | 989 / 989 |
109 | `item-identifier-topicref.ctm` | 5 | 1 | 985 / 985 |
110
111 All thirteen are real CTM→TMDM→CXTM byte-exact comparisons. Every Association has
112 two Roles. In `isa-relationship.ctm` the actual `type-instance` Topic is the
113 Association Type; Role Type `instance` points to the Topic with II `#ctm`, and
114 Role Type `type` points to II `#format`. Each Role's Parent is EQ to its actual
115 Association and the computed rolesPlayed inverse contains the same Role object.
116 `ako-relationship.ctm` analogously binds `subtype → #tm-syntax` and
117 `supertype → #syntax`. Embedded examples add an actual Name item and the existing
118 default Name-Type Topic. The QName and explicit identity cases preserve their
119 different SI/II bindings.
120
121 `ako-merge-away.ctm` binds local `haha`/`hehe`/`hoho` aliases to the standardized
122 Association/Role-Type Topics between two assertions. The resolver looks up the
123 Core locators anew and canonicalizes references; no stale Topic cache is used.
124 Both resulting Associations refer to the same current Type Topic.
125
126 `reports/slice-17b/relationships.json` records each unmodified source, absolute
127 Document IRI, actual Topic identities, Association Type, Scope, Role Type/Player,
128 and EQ/Parent/inverse observations. Its atomic-conflict records refer to executed
129 tests, not inferred runtime behavior. `execution.json` binds those observations
130 to source hashes, runtime and UTC interval. The independent Python checker
131 compares these reference graphs against the original XML separately from the
132 raw byte comparison. Norm interpretation, upstream evidence and current Lisp
133 observations are distinct evidence sources.
134
135 ## Fresh-process inspection
136
137 In a fresh SBCL process with `--no-sysinit --no-userinit`:
138
139 ```lisp
140 (require :asdf)
141 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
142 (asdf:load-asd #P"/Users/rgb/workspace/topic-maps/topic-maps.asd")
143 (asdf:load-system "topic-maps/ctm")
144 (let ((map (topic-maps.ctm:deserialize-string "a isa b; ako c."
145 :document-iri "https://example.invalid/relationships.ctm")))
146 (assert (= 2 (length (topic-maps.tmdm:topic-map-associations map))))
147 (dolist (association (topic-maps.tmdm:topic-map-associations map))
148 (describe association)
149 (dolist (role (topic-maps.tmdm:association-roles association))
150 (assert (eq association (topic-maps.tmdm:association-role-parent role)))
151 (describe role)
152 (format t "~&Role Type: ~S; Player II: ~S~%"
153 (topic-maps.tmdm:topic-subject-identifiers (topic-maps.tmdm:association-role-type role))
154 (topic-maps.tmdm:topic-item-identifiers (topic-maps.tmdm:association-role-player role))))))
155 ```
156
157 `describe.log` records one disposable execution of these forms; printed addresses
158 are historical process-local observations, not durable Topic identity.
159
160 Templates, Include/Mergemap, cross-document merging, XTM deserialization, further
161 datatypes and HyperDoc integration remain excluded. The two known DateTime
162 baseline discrepancies remain FAIL. Full CTM/TMDM conformance is not claimed.