]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/slice-1-api-and-boundaries.md
feat(xtm): support resource references on name variants
[topic-maps.git] / docs / slice-1-api-and-boundaries.md
1 # Slice 1 reader and model boundary
2
3 The repository was observed clean at
4 `9c83db34eb1ba8091b004433f088056717dbaa7e` on `codex/ctm-slice-0` before
5 `git switch -c codex/ctm-slice-1 9c83db34eb1ba8091b004433f088056717dbaa7e`.
6 Implementation is in `/Users/rgb/workspace/topic-maps`. HyperDoc is not a base,
7 dependency or integration target in this slice.
8
9 ## Public reader API
10
11 ```lisp
12 (topic-maps.ctm:deserialize-string
13 "topic - \"Name\"."
14 :document-iri "https://example.invalid/lesson.ctm"
15 :source-name "lesson")
16
17 (topic-maps.ctm:deserialize-file
18 #p"/path/to/document.ctm"
19 :document-iri "https://example.invalid/lesson.ctm"
20 :source-name "lesson")
21 ```
22
23 Both return a new `topic-maps.tmdm:topic-map`. The Document IRI is required,
24 absolute and fragment-free (RFC 3987 absolute-IRI). File reading accepts UTF-8,
25 with an optional UTF-8 BOM. It uses ANSI binary I/O and a strict decoder,
26 including rejection of overlong sequences, surrogates and incomplete bytes.
27 A Common Lisp implementation unable to represent a needed Unicode scalar
28 signals UNSUPPORTED. The core reader/model depends on no third-party library.
29 ASDF is the loader, and UIOP is used only by the retained foundation/test tooling.
30
31 The dedicated lexer distinguishes identifiers, QNames, IRIs, strings and
32 punctuation. There is no use of Common Lisp READ, READ-FROM-STRING or EVAL on
33 CTM text. Character case is preserved. CTM identifier character ranges, quoted
34 string escapes, and single/nested multiline comments are handled explicitly.
35 IRI construction applies CTM's percent-octet UTF-8 decoding and relative
36 resolution from RFC 3986 §5.2. No fetching, host/scheme case normalization or
37 machine-path-derived Document IRI occurs. Full IRI grammar and scheme-specific
38 validation are not claimed; delimiter, character, relative-colon and fragment
39 checks cover the implemented path. No prefixes can be declared in this slice;
40 a QName produces a specific undefined-prefix rejection.
41
42 The syntax subset is Topic declarations with local, Subject Identifier,
43 Subject Locator or Item Identifier identity; quoted untyped names; required
44 periods; semicolon-separated names and optional trailing semicolon. Other
45 recognized CTM constructs signal `CTM-UNSUPPORTED`. Typed names, additional
46 identity assignments, associations, occurrences, scope, variants, reification,
47 templates, directives, wildcards and other encodings are outside this slice.
48 Unsupported input is not returned as an apparently valid partial map.
49 Each read creates its own private map; a failed read returns no model.
50
51 ## Conditions and positions
52
53 - `CTM-REJECTION`: an identified CTM/decoding/input-contract error.
54 - `UNDEFINED-PREFIX`: a subclass of rejection, code `:UNDEFINED-PREFIX`.
55 - `CTM-UNSUPPORTED`: separate from rejection; a recognized unavailable feature.
56 - File I/O exceptions propagate as file errors, not CTM rejections.
57
58 Accessors: `error-code`, `error-position`, `error-position-unit`, `error-line`,
59 `error-column`, `error-source`. Offsets are zero-based; character line/column
60 numbers are one-based, with CR, LF and CRLF handled. Invalid UTF-8 uses byte
61 offsets when decoded character positions are unavailable. `source-name` is an
62 optional logical source label; the harness supplies the stable case ID.
63 The selected invalid case reports character offset 1, line 2, column 1 because
64 its original file begins with a newline.
65
66 ## Model and identity
67
68 Ordinary ANSI Common Lisp structures represent a Topic Map, Topic and Topic
69 Name. Topics have separate Item Identifier, Subject Identifier and Subject
70 Locator sets (lists with unique locator strings), Name items and a map parent.
71 Names have value, a Topic as type and a Topic parent. Parent/type links are real
72 object references. Print methods avoid cycles; standard DESCRIBE works.
73 The remaining TMDM properties are implicitly initialized to empty sets or null
74 as appropriate for the supported inputs. This is a minimal representation,
75 not the complete TMDM information-item model.
76
77 The default type URI comes directly from CTM §3.11. Its Topic is interned in
78 the current map by Subject Identifier, reused if already present, and created
79 only when a name needs it. Reading an unnamed or empty document does not
80 create it. It receives no invented Item Identifier or name.
81
82 Same-map interning implements the applicable identity equality in TMDM §5.3.5:
83 same-category equal locators reuse a Topic, as does Item Identifier/Subject
84 Identifier overlap. Subject Locator equality is separate; equality of its
85 string with an Item or Subject Identifier does not conflate them. An unscoped
86 Name with the same value, type and parent is interned under TMDM §5.4 equality;
87 all supported names have implicitly empty scope/variants and null reifier.
88 Lists have deterministic observational order, not normative set ordering.
89 General merging procedures (§§6.2–6.3), cross-map/cross-document merging and
90 identities added by topic tails are not implemented. Interning avoids duplicate
91 items in this bounded subset rather than implementing an unrestricted merge
92 engine or global object registry.
93
94 Different Document IRIs produce different local Item Identifier strings.
95 Those local names alone add no Subject Identifier/Locator or evidence of a
96 shared Subject. Equal spelling does not establish cross-document identity.
97
98 ## Harness and canonicalization boundary
99
100 `topic-maps` remains the independent Slice 0 foundation; `topic-maps/tests`
101 retains its regressions. `topic-maps/tmdm` and `topic-maps/ctm` are opt-in
102 systems. `topic-maps/ctm/tests` adds semantic assertions and a selected executor.
103 There is no `topic-maps/cxtm` system. The former foundation assertion that no
104 reader/model system exists is adapted to prohibit the absent canonicalizer;
105 all discovery, integrity, selection, status and reporting tests remain.
106
107 The report writer takes an optional implementation descriptor. An inventory-only
108 call retains the foundation-only metadata; the Slice 1 executor explicitly
109 reports the implemented identity/name subset. That descriptor does not change
110 contracts or infer a result from the existence of implementation code.
111
112 Five positive cases produce separate semantic observations of actual model
113 objects. Their imported `CXTM-EQUAL` results remain NOT-RUN. The required
114 negative case becomes PASS only after verifying the precise undefined-prefix
115 condition. Remaining imported cases are untouched. The two JSON reports keep
116 semantic assertions and canonical contracts separate. Five original baselines
117 are read as expected-property evidence by a Python standard-library checker;
118 no XML is produced, incompletely serialized or byte-compared by this slice.
119
120 [Reading the First Five CTM Documents](reading-first-five-ctm-documents.md)
121 explains the absolute Document IRIs versus relative baseline locators and
122 provides exercised inspection forms. Normative editions, exact consulted
123 snapshot hashes, corpus revision and bounded clauses are recorded in
124 [the Slice 1 source record](../references/slice-1-sources.json).
125 The pinned suite targets the **CTM draft dated 2010-03-31**; passing it alone
126 would not establish full ISO/IEC 13250-6:2010 conformity. Published ISO standards
127 remain authoritative. No blocking conflict was found for the selected cases.