]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-topic-merging.md
Support DateTime occurrences and expose normative baseline conflicts
[topic-maps.git] / docs / reading-topic-merging.md
1 # Reading Topic Identity and Merging
2
3 Slice 2 starts at the accepted `fb60afd548d679d83fd8ec76bc5ff384c1e23e5f`.
4 It adds same-map Topic merging to the existing Topic/Name model. It does not
5 implement associations, cross-document merging or CXTM canonicalization.
6
7 ## A late identity changes earlier references
8
9 ```ctm
10 a - "Same".
11 b - "Same".
12 a <urn:shared>.
13 b <urn:shared>; - "Later".
14 ```
15
16 Document IRI: `https://example.invalid/merging.ctm`.
17 Before the last declaration there are three live Topics: `a`, the default
18 name type, and `b`. The two named Topics have separate Name objects.
19 After the last declaration, this implementation observes:
20
21 ```text
22 M.TOPICS = (C TYPE)
23 C.PARENT = M
24 C.ITEM-IDENTIFIERS = {https://example.invalid/merging.ctm#a,
25 https://example.invalid/merging.ctm#b}
26 C.SUBJECT-IDENTIFIERS = {urn:shared}
27 C.SUBJECT-LOCATORS = {}
28 C.NAMES = (N-SAME N-LATER)
29 N-SAME.VALUE = "Same"; N-SAME.PARENT = C; N-SAME.TYPE = TYPE
30 N-LATER.VALUE = "Later"; N-LATER.PARENT = C; N-LATER.TYPE = TYPE
31 TYPE.SUBJECT-IDENTIFIERS = {http://psi.topicmaps.org/iso13250/model/topic-name}
32 TYPE.ITEM-IDENTIFIERS = {}; TYPE.SUBJECT-LOCATORS = {}; TYPE.NAMES = {}
33 TYPE.PARENT = M
34 ```
35
36 These braces denote sets, not a new CTM notation or canonical ordering.
37 The two identical Names coalesce after their parents become the same Topic.
38 No additional Subject Identifier is invented, and no identity across maps is
39 asserted. This is a local model observation, not a CXTM comparison result.
40
41 ## Normative basis and representation
42
43 [ISO/IEC 13250-2:2006](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
44 §5.3.5 supplies the identity equality rules; §§6.1–6.2 require merging and
45 replacement of references. §5.4 defines Name equality and the computed parent;
46 §6.3 covers equal Name merging. The implementation creates replacement Topic
47 and Name items, preserves identifier unions and rewrites stored Name parent
48 and type references. It repeats Topic equality merging to a fixed point.
49
50 [ISO/IEC 13250-6:2010](https://www.isotopicmaps.org/ctm/ctm.html) §3.3.6
51 maps topic identities; §3.9 adds tail identities to the current Topic and
52 requires applicable merges. §3.11 supplies the existing default name type.
53 Semicolons separate tail statements. Topic-tail assignments create locators,
54 not extra Topics. The original Document-IRI resolution policy is retained.
55
56 Only implemented Topic and unscoped Name properties are materialized.
57 Unimplemented set properties remain implicitly empty and nullable properties
58 implicitly null. Reification, scope, variants, occurrences, associations and
59 roles cannot carry references in this model; their merging is not claimed.
60 Both inspected editions remain authoritative over the draft-era test corpus.
61
62 ## Public model API and retained Lisp handles
63
64 | Function | Contract |
65 | --- | --- |
66 | `intern-topic map kind iri` | Lookup/create using the same identity rule as merging |
67 | `add-topic-identifier topic kind iri` | Add a distinct-category locator, merge as required, return the current Topic |
68 | `merge-topics a b` | Explicit same-map merge, return the current Topic; reject different maps before mutation |
69 | `normalize-topic-map map` | Merge equal Topics to a fixed point and remove equal Names; return the map |
70 | `canonical-topic topic` | Resolve a retained reference to a replaced Topic |
71 | `canonical-topic-name name` | Resolve a retained reference to a replaced Name |
72
73 Identifier kinds are `:ITEM-IDENTIFIER`, `:SUBJECT-IDENTIFIER` and
74 `:SUBJECT-LOCATOR`. The model accepts already resolved nonempty absolute
75 locator strings; CTM performs decoding, validation and resolution. Full IRI
76 grammar validation remains outside this slice.
77
78 `merge-topics` explicitly asserts a shared subject even without identifier
79 equality. The CTM reader does not use that discretionary operation: it adds
80 identifiers and lets the shared equality rule decide required merging.
81
82 The old objects A and B remain ordinary Lisp objects, but are removed from the
83 map's live Topic set. Their `EQ` identity cannot change. An internal `FORWARD`
84 slot records their replacement; it is bookkeeping, not a TMDM property.
85 Resolve retained handles before comparing them with `EQ` or using `DESCRIBE`.
86 These representative-resolution functions do not perform CXTM canonicalization.
87 Public property readers also resolve obsolete handles. Live model references
88 are actually rewritten, not merely concealed by those readers.
89
90 Version 0.2 makes public set readers return copies. Generated `SETF` writers
91 for Topic/Name properties are no longer the mutation interface. Use the above
92 model operations; private structure setters bypass invariants and are not API.
93 List ordering is observational and not normative. Pair scanning favors clarity
94 for small maps; this slice adds no identity index or cross-map registry.
95
96 ## Load and inspect
97
98 ```lisp
99 (require :asdf)
100 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
101 (asdf:load-asd #p"/Users/rgb/workspace/topic-maps/topic-maps.asd")
102 (asdf:load-system "topic-maps/ctm")
103 (defparameter *map*
104 (topic-maps.ctm:deserialize-string
105 "a - \"Same\". b - \"Same\". a <urn:shared>. b <urn:shared>; - \"Later\"."
106 :document-iri "https://example.invalid/merging.ctm"))
107 (describe *map*)
108 (describe (first (topic-maps.tmdm:topic-map-topics *map*)))
109 (dolist (name (topic-maps.tmdm:topic-names
110 (first (topic-maps.tmdm:topic-map-topics *map*))))
111 (describe name)
112 (describe (topic-maps.tmdm:topic-name-type name)))
113 ```
114
115 To inspect retained references explicitly:
116
117 ```lisp
118 (defparameter *m* (topic-maps.tmdm:make-topic-map))
119 (defparameter *a* (topic-maps.tmdm:intern-topic *m* :item-identifier "urn:a"))
120 (defparameter *b* (topic-maps.tmdm:intern-topic *m* :item-identifier "urn:b"))
121 (topic-maps.tmdm:add-topic-identifier *a* :subject-identifier "urn:shared")
122 (defparameter *c*
123 (topic-maps.tmdm:add-topic-identifier *b* :subject-identifier "urn:shared"))
124 (eq *a* *c*) ; => NIL: merging creates a replacement item
125 (eq (topic-maps.tmdm:canonical-topic *a*) *c*) ; => T
126 (eq (topic-maps.tmdm:canonical-topic *b*) *c*) ; => T
127 (describe *c*)
128 ```
129
130 ## Pinned cases and evidence boundary
131
132 Eleven additional original files are exercised: the plain/wrapped/duplicate
133 `topic-subject-identifier` cases; plain/wrapped/semi/duplicate
134 `topic-subject-locator` cases; plain/wrapped/duplicate `topic-item-identifier`
135 cases; and `name-duplicate.ctm`.
136
137 They use `https://ctm-tests.example.invalid/` plus pinned commit
138 `cd165b150176c1d6842b37be9cc9051b40d4996b`, `/`, and the original case ID.
139 Frozen baseline fragment locators are interpreted in that Document-IRI context.
140 The Python property oracle matches Topics by identifier sets and compares Name
141 references under that mapping. It does not rely on observation order matching
142 CXTM numbering and does not produce or canonicalize XML.
143
144 The original five case records remain unchanged. All 16 positive imported
145 CXTM-EQUAL contracts stay NOT-RUN. Only the existing undefined-prefix rejection
146 is an imported PASS; 272 imported contracts stay NOT-RUN. Unexecuted contracts
147 are unchanged. The corpus targets draft 2010-03-31 and cannot by itself prove
148 full ISO conformity. See `slice-2-validation.md` for execution evidence.