]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-map-content-import.md
docs: design draft for a read-only SHOP3 adapter over TMDM objects
[topic-maps.git] / docs / reading-map-content-import.md
1 # Reading Map Content Import
2
3 Slice 19A builds on `0573c4f710982dab1c3f2c9284adf459caaf73e9`.
4 It changes the independent TMDM system; the CTM reader, CXTM canonicalizer and
5 pinned corpus (`cd165b150176c1d6842b37be9cc9051b40d4996b`) are unchanged.
6
7 ## Normative basis and local API choices
8
9 [TMDM 2006](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/):
10 §4.3 requires exact locator-string equality. §5.1 constrains identifier uniqueness;
11 §5.3.5 supplies Topic identity. §§5.4–5.8 define the structural item equalities.
12 §5.5 requires the Variant scope to properly contain its Name scope.
13 §6.1 requires duplicate removal after changes; §§6.2–6.7 specify replacement,
14 reference rewriting and metadata union, including Reifier merging. §6.2 rejects
15 merging Topics that reify different items; §7.1 protects distinct Core Subjects.
16
17 These are model requirements. The two-return-value API, source-preserving copy,
18 source Map exclusion, self-import rejection and preflight transaction policy
19 below are explicit implementation choices for this content-import operation.
20 The operation does not merge two root Map items and is not a CTM directive.
21
22 ## Public API and object lifetime
23
24 `(import-map-content target source)` returns `TARGET` and a resolver function.
25 Both arguments must be different valid Maps. Wrong argument types signal
26 `TYPE-ERROR`; self-import signals `MAP-IMPORT-ERROR`, code `:SAME-MAP`.
27
28 `(funcall resolve source-item)` returns the current canonical target object.
29 Several source objects can resolve to one target. The table contains original
30 source snapshot objects, never locator-to-subject identities. Existing source
31 aliases may resolve through their snapshot representative. A known snapshot
32 object still works if its source handle later forwards elsewhere. A newly
33 created source object is not automatically imported. Source Map, foreign objects
34 and objects outside the snapshot signal `MAP-IMPORT-ERROR :NOT-IMPORTED`.
35 No durable object IDs or URLs are manufactured. The resolver and source/target
36 object references belong to the calling Lisp process. Keep the resolver while
37 its mapping is needed; no global import registry is retained.
38
39 The target Map stays the parent. Source Map item identifiers and its Reifier
40 edge are excluded. The source's map-reifying Topic is still copied as an ordinary
41 content Topic; it does not thereby reify the target Map. Target root metadata
42 and its consistency constraints remain active.
43
44 ## Transfer and normalization
45
46 `copy-map-graph` generalizes the existing disposable preflight graph copier.
47 It first allocates same-model Topic shells, then Names/Variants/Occurrences and
48 Associations/Roles, and finally assigns rewritten Scopes, Reifiers and identifier
49 sets. The copy table only maps actual objects. New locator/value/datatype strings
50 and collections are copied too. Parent, Type, Player, Theme and Reifier references
51 remain inside the target. No source object's forwarding link is changed.
52
53 `normalize-topic-map` performs ordinary same-map merging on the complete graph.
54 A Reifier-first construction-order regression exposed premature conflict
55 selection in the old normalizer. Normalization now selects an available
56 nonconflicting equal Topic pair first. Owner/Type merging can then make the
57 reified items equal and merge their Reifiers by the existing item rules. If no
58 such pair can proceed, the existing Reifier-conflict check still rejects. Explicit
59 `merge-topics` conflict rules and the cross-map restriction are unchanged.
60
61 `validate-import-map` checks current graph membership, parents, canonical
62 references, Scope sets, identifier uniqueness, Reification, Variant and Core
63 constraints. Identifier collisions between unequal items are checked after
64 normalization; equal structural items can therefore union their metadata first.
65
66 The complete operation is tried on a fresh target copy before actual target
67 changes. Both paths use the same seven structures and merge functions. Semantic
68 failures leave both maps, stored strings and held handles unchanged. This is a
69 single-threaded API guarantee; allocation failure, asynchronous interruption or
70 concurrent external slot mutation does not have a rollback guarantee.
71
72 Repeat imports are tested through actual Topic identity and item equality,
73 without an already-imported list. Fixtures with shared identifiers produce no
74 new items on repetition. Different document-relative identities remain distinct
75 without identity evidence. No general promise based solely on import repetition
76 is used, and CXTM-normalized strings never determine TMDM identity.
77
78 ## Direct inspection in a fresh process
79
80 Run from the repository root. Only `topic-maps/tmdm` is required; no CTM, CXTM,
81 HyperDoc system or persistent image is loaded.
82
83 ```lisp
84 (require :asdf)
85 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
86 (asdf:load-asd (truename "topic-maps.asd"))
87 (asdf:load-system "topic-maps/tmdm")
88 (let* ((source (topic-maps.tmdm:make-topic-map))
89 (target (topic-maps.tmdm:make-topic-map))
90 (owner (topic-maps.tmdm:intern-topic source :subject-identifier "urn:owner"))
91 (type (topic-maps.tmdm:intern-topic source :subject-identifier "urn:type"))
92 (theme (topic-maps.tmdm:intern-topic source :subject-identifier "urn:theme"))
93 (name (topic-maps.tmdm:add-name owner "Name" :type type))
94 (variant (topic-maps.tmdm:add-variant name "V" :scope (list theme)))
95 (occ (topic-maps.tmdm:add-occurrence owner type "+0007"
96 :datatype (topic-maps.tmdm:integer-datatype) :scope (list theme)))
97 (association (topic-maps.tmdm:make-association source type (list (list type owner))))
98 (reifier (topic-maps.tmdm:intern-topic source :subject-identifier "urn:reifier")))
99 (topic-maps.tmdm:add-item-identifier source "urn:source-map-only")
100 (topic-maps.tmdm:add-item-identifier name "urn:name")
101 (topic-maps.tmdm:set-item-reifier name reifier)
102 (multiple-value-bind (result resolve) (topic-maps.tmdm:import-map-content target source)
103 (let* ((new-owner (funcall resolve owner)) (new-name (funcall resolve name))
104 (new-occ (funcall resolve occ)) (new-association (funcall resolve association)))
105 (assert (eq target result))
106 (assert (not (eq owner new-owner)))
107 (assert (eq source (topic-maps.tmdm:topic-parent owner)))
108 (assert (eq target (topic-maps.tmdm:topic-parent new-owner)))
109 (assert (eq new-owner (topic-maps.tmdm:topic-name-parent new-name)))
110 (assert (eq (funcall resolve type) (topic-maps.tmdm:topic-name-type new-name)))
111 (assert (eq new-name (topic-maps.tmdm:variant-parent (funcall resolve variant))))
112 (assert (eq new-owner (topic-maps.tmdm:occurrence-parent new-occ)))
113 (assert (eq new-owner (topic-maps.tmdm:association-role-player
114 (first (topic-maps.tmdm:association-roles new-association)))))
115 (assert (eq new-name (topic-maps.tmdm:topic-reified (funcall resolve reifier))))
116 (assert (null (topic-maps.tmdm:item-identifiers target)))
117 (mapc #'describe (list source target name new-name new-occ new-association))
118 (format t "~&IMPORT-INSPECTION-PASS: copied graph; actual EQ references; source unchanged.~%"))))
119 ```
120
121 ## Evidence and limits
122
123 `tests/map-import.lisp` checks six-kind transfers, all relevant references by EQ,
124 Topic identity categories, many-to-one mappings, all six imported kinds against
125 seven target kinds for identifier collisions, Reifier cascades, atomic conflicts,
126 source/target old handles, repeated import, construction order and CXTM purity.
127 It checks raw slots of live and retained objects plus source CXTM before/after.
128 `reports/slice-19a/map-import.json` records model witnesses and actual canonical
129 XML. Its independent Python checker verifies item counts, metadata and output
130 references. These are manually constructed model examples, not imported CTM/XTM
131 conformance contracts. `base-normalizer-control.log` reproduces the ordering
132 regression with the committed base normalizer in a separate disposable process.
133
134 No resource retrieval, `%include`, `%mergemap`, Include-local identifier aliases,
135 Template binding transport or XTM deserializer is provided. No new literal form
136 or HyperDoc integration is included. The two known DateTime baseline conflicts
137 remain visible. This slice does not claim complete CTM or TMDM conformance.