]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-reification.md
feat(ctm): validate prologs and register three Slice 20C contracts
[topic-maps.git] / docs / reading-reification.md
1 # Reification within one Topic Map — Slice 16B
2
3 Reification connects an existing non-Topic construct with a Topic representing
4 its subject. It adds neither a second model nor another identity registry.
5 Source declarations, current Lisp objects and canonical XML remain separate.
6
7 ## Normative requirements
8
9 The published [TMDM](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
10 §§5.2–5.8 supply Reifier on Map, Name, Variant, Occurrence, Association and Role.
11 §§5.3.4–5.3.5 exclude Topic reification and define the computed Reified inverse
12 and Topic equality. §§5.4–5.8 retain structural item equality; Reifier and Item
13 Identifiers are metadata, not new non-Topic equality keys. §6.2 prohibits merging
14 Topics with different non-null Reified targets and replaces Reifier references.
15 §§6.3–6.7 merge Reifiers when their items merge, preserving identifier unions;
16 §6.1 requires subsequent duplicate removal. Variant Scope still obeys §5.5.
17
18 [CTM](https://www.isotopicmaps.org/ctm/ctm.html) §3.3.10 resolves `~ topic-ref`
19 through §§3.3.6–3.3.8, including Wildcards and Embedded Topics. Attachment points
20 are §3.5 (Map), §3.10 (Occurrence), §3.11 (Name, before Variants), §3.12 (Variant,
21 inside its parentheses) and §3.13 (individual Role and Association). Map Reifier
22 follows leading directives and precedes body declarations.
23
24 [CXTM](https://www.isotopicmaps.org/cxtm/cxtm.html) §§3.4–3.11 encode Reifier as
25 an attribute referencing the canonical Topic number; null is omitted. Existing
26 sort keys (§§4.6–4.11) remain unchanged. Reifier is not an ordering tie breaker.
27
28 ## API and object contracts
29
30 ```lisp
31 (topic-maps.tmdm:item-reifier item) ; actual current Topic or NIL
32 (topic-maps.tmdm:topic-reified topic) ; computed current item or NIL
33 (topic-maps.tmdm:set-item-reifier item topic)
34 ```
35
36 `set-item-reifier` returns the canonical item. As a local API choice, it asserts
37 Reification: an existing different Reifier Topic is merged with the supplied one.
38 It never silently discards that Topic's identity. Passing NIL explicitly clears
39 the relation. A foreign Topic, non-Topic argument, Topic as target, or a Topic
40 already reifying a different current item is rejected with `reification-error`.
41 Inspect `reification-error-code` for `:foreign-reifier`, `:invalid-reifier`,
42 `:not-reifiable`, `:invalid-item`, `:foreign-item` or `:reifier-conflict`.
43
44 Old Topic/item handles resolve through the existing canonical functions. Topic
45 has no Reifier slot. Its Reified property is computed by scanning actual live
46 Reifier properties; there is no independently maintained inverse identity store.
47 All stored Reifier references point to current Topics of the same Map.
48
49 ## Merge cascades and atomic API policy
50
51 Item replacement redirects old handles and child ownership before combining
52 Reifiers, so the Topic merge sees the new target, not two discarded items.
53 Normalizers rescan current owners after each replacement. This matters when a
54 Reifier is also a Parent, Type, Theme or Player. Normalization continues to a
55 fixed point. Association replacement retains both Role sets and merges matching
56 Roles, preserving both their Item Identifiers and Reifiers.
57
58 When a public Topic identity/merge operation or Reification assertion can affect
59 an existing relation, the same operation runs first on a disposable copy of the
60 current seven TMDM structures. It uses the same merge functions, not simulated
61 identity rules. Only after a successful full cascade does it run on original
62 objects. Nested steps do not repeat the outer copy. Tests cover scope collapse
63 at four cascade levels, through direct merge and both identifier APIs.
64
65 This is a bounded semantic preflight policy, not a general transaction engine
66 or a normative TMDM transaction requirement. It does not promise recovery from
67 resource exhaustion or interruption. Cost includes copying the current Map.
68 Two separately invoked public operations are not one transaction.
69
70 The historical Topic-SI/Occurrence-II overlap restriction is removed. Equal
71 locator strings alone establish no automatic Reification between a Topic and a
72 non-Topic item. TMDM §5.3.5's SI/II cross-identity rule concerns two Topics.
73 All general Item Identifier uniqueness rules from Slice 16A remain active.
74
75 ## Current evidence and boundaries
76
77 The eleven original positive Reifier CTM cases execute end-to-end and are
78 compared as UTF-8 bytes with unchanged upstream CXTM baselines. The two original
79 negative cases test `:reifier-conflict` and `:topic-map-reifier-position`, including
80 marker positions. Object snapshots and EQ assertions are separate from XML tests.
81 The independent Python checker connects observed Reifier Topic identities and
82 inverse assertions to the source and baseline. Execution context and source
83 hashes are recorded in `reports/slice-16b/execution.json`; object addresses in
84 `describe.log` belong only to that isolated process.
85
86 Templates, Include/Mergemap, cross-document merging, XTM deserialization, CTM
87 Associations above two roles, new datatypes and HyperDoc remain outside scope.
88 The two known DateTime baseline conflicts are unchanged.
89
90 ## Inspect actual objects in a fresh process
91
92 Run these forms from the checkout root:
93
94 ```lisp
95 (require :asdf)
96 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
97 (asdf:load-asd (truename "topic-maps.asd"))
98 (asdf:load-system "topic-maps/cxtm")
99 (let* ((map (topic-maps.tmdm:make-topic-map))
100 (a (topic-maps.tmdm:intern-topic map :subject-identifier "urn:owner:a"))
101 (b (topic-maps.tmdm:intern-topic map :subject-identifier "urn:owner:b"))
102 (r (topic-maps.tmdm:intern-topic map :subject-identifier "urn:reifier:r"))
103 (s (topic-maps.tmdm:intern-topic map :subject-identifier "urn:reifier:s"))
104 (n (topic-maps.tmdm:add-name a "N"))
105 (other (topic-maps.tmdm:add-name b "N")))
106 (topic-maps.tmdm:add-item-identifier n "urn:name:a")
107 (topic-maps.tmdm:add-item-identifier other "urn:name:b")
108 (topic-maps.tmdm:set-item-reifier n r)
109 (topic-maps.tmdm:set-item-reifier other s)
110 (topic-maps.tmdm:merge-topics a b)
111 (assert (eq (topic-maps.tmdm:canonical-topic-name n)
112 (topic-maps.tmdm:canonical-topic-name other)))
113 (assert (eq (topic-maps.tmdm:item-reifier n) (topic-maps.tmdm:canonical-topic s)))
114 (assert (eq (topic-maps.tmdm:canonical-topic-name n) (topic-maps.tmdm:topic-reified r)))
115 (describe (topic-maps.tmdm:canonical-topic-name n))
116 (describe (topic-maps.tmdm:item-reifier n))
117 (format t "~A" (topic-maps.cxtm:canonicalize map :base-locator "https://example.invalid/reification.ctm")))
118 ```