]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/slice-21k-xtm-variant-item-identity.md
feat(xtm): support item identifiers on name variants
[topic-maps.git] / docs / slice-21k-xtm-variant-item-identity.md
1 # Slice 21K — Item Identity of Name Variants
2
3 ## Ausgangszustand und normative Zuordnung
4
5 Branch: `codex/xtm-slice-21k`. Ausgangscommit und vorgesehener Parent:
6 `49e4f2efb3df426d8ce249bc9b714bbd81323525`.
7 Der vorgefundene Branch war `codex/xtm-slice-21j`; Index und Arbeitsbaum waren
8 sauber. [initial-state.json](../reports/slice-21k/initial-state.json) bewahrt den
9 Ausgangszustand und die SHA-256-Werte aller damals versionierten Dateien.
10
11 Ein frischer Offline-SBCL-Prozess reproduzierte vor der Reader-Änderung alle
12 1713 XTM-Prüfungen und sämtliche 124 Originaldiagnosen identisch zu Slice 21J.
13 Ausgangsstand: **XTM 60 PASS, 0 FAIL, 64 NOT-RUN** und
14 **CTM 262 PASS, 4 FAIL, 7 NOT-RUN**. Siehe
15 [baseline.log](../reports/slice-21k/baseline.log),
16 [baseline-xtm.json](../reports/slice-21k/baseline-xtm.json) und
17 [before-diagnostics.json](../reports/slice-21k/before-diagnostics.json).
18
19 Normativ hergeleitet aus
20 [XTM 2.0 §§4.3.1, 4.6 und 4.12](https://www.isotopicmaps.org/sam/sam-xtm/):
21 `itemIdentity*` steht im Variant vor Scope und Ressourcenwert. Sein Locator
22 gehört zum Information Item des Elternelements, hier dem Variant. Die
23 vorhandenen XTM-IRI-Regeln lösen `href` gegen die Document IRI auf.
24 [TMDM §§5.1, 5.5 und 6.4](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
25 bestimmen globale Item-Identifier-Eindeutigkeit, Variant-Gleichheit anhand von
26 Parent, Value, Datatype und Scope sowie Identifier-Erhaltung beim Merging.
27 Die folgenden Aussagen sind tatsächliche Ausführungsbefunde.
28
29 ## Vorhandene TMDM-API und minimale Reader-Erweiterung
30
31 Vor der Reader-Änderung prüfte
32 [api-preflight.lisp](../reports/slice-21k/api-preflight.lisp) die unveränderte
33 native API in einem frischen Offline-Prozess. `add-variant` normalisiert und
34 liefert den kanonischen Variant. Bereits zugewiesene Identifier bleiben dabei
35 erhalten; derselbe Identifier ist am selben kanonischen Item idempotent.
36 `add-item-identifier` weist Identifier dem aktuellen Variant zu und lehnt
37 Kollisionen mit verschiedenen Items vor Mutation ab. Retained Handles und
38 Identifier-Mengen bleiben beim fehlgeschlagenen Zuweisungsversuch unverändert.
39 Der Test wurde in der vollständigen Abnahme erneut ausgeführt; beide Logs sind
40 erhalten. Es war keine TMDM-Änderung erforderlich.
41
42 Nur `src/xtm/reader.lisp` enthält Produktionsänderungen:
43
44 1. `validate-source` erlaubt null oder mehrere Variant-`itemIdentity`-Elemente
45 in Phase 0 vor Scope und Ressourcenwert. Die bestehende allgemeine
46 `itemIdentity`-/`leaf-href`-Validierung prüft Attribute, Inhalt und IRI.
47 2. `read-variant` erzeugt zunächst den vollständigen Variant mit Parent, Value,
48 Datatype und Scope über `add-variant`. Erst an dessen kanonischem Ergebnis
49 weist `add-item-identifier` die aufgelösten Identifier zu. Jeder Rückgabewert
50 wird als aktuelles Variant-Handle weiterverwendet und zurückgegeben.
51
52 Diese Reihenfolge ist für das doppelte Original wesentlich: Der zweite
53 normativ gleiche Variant fällt bereits vor der erneuten Zuweisung von
54 `#the-variant` mit dem ersten zusammen. Unterschiedliche Variants werden durch
55 einen kollidierenden Identifier nicht gleichgesetzt.
56
57 Es gibt keine zweite Identifier-Registry oder Variant-Repräsentation.
58 Owner-Prüfungen durchsuchen ausschließlich die aktuellen nativen Information
59 Items mit `map-information-items` und vergleichen deren tatsächliche Handles.
60 TMDM, CTM, CXTM und XML bleiben unverändert. Reification, weitere Datentypen,
61 XML-Kanonisierung, Occurrences, explizite Associations/Roles, XTM-`mergeMap` und
62 XTM 2.1 wurden nicht implementiert. Die bisherigen Resource-Pfade bleiben
63 bestehen.
64
65 ## Zwei unveränderte Originalverträge
66
67 | Original | Quellbytes | Variant-Elemente | kanonische Variants | CXTM Ist/Soll | Ergebnis |
68 | --- | ---: | ---: | ---: | ---: | --- |
69 | `itemid-variant.xtm` | 351 | 1 | 1 | 666/666 | PASS |
70 | `variant-duplicate-iid.xtm` | 543 | 2 | 1 | 666/666 | PASS |
71
72 Das tatsächliche XML enthält jeweils den Owner-Topic `id="topic"`, den Name
73 `Topic`, einen leeren Name-Scope und textuelles `resourceData` mit Value
74 `TOPIC!` und Standarddatentyp `xsd:string`. Jeder Variant enthält vor seinem
75 Scope ein `itemIdentity href="#the-variant"`. Der explizite Scope referenziert
76 `#command`. Das zweite Original enthält zwei solche vollständig gleichwertigen
77 Variant-Elemente. Weitere neue Sprachunterstützung ist für beide nicht nötig.
78
79 Document IRI ist jeweils
80 `https://xtm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/`
81 plus Case-ID `xtm2/in/<Dateiname>`. Der Source Key ist die Case-ID.
82 Beide unveränderten Rohquellen werden über
83 `topic-maps.xtm:deserialize-octets` und den qualifizierten XML-Parser verarbeitet.
84
85 Tatsächlich gespeicherte absolute Variant-Identifier:
86
87 ```text
88 https://xtm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/xtm2/in/itemid-variant.xtm#the-variant
89 https://xtm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/xtm2/in/variant-duplicate-iid.xtm#the-variant
90 ```
91
92 Native Modellprüfungen belegen für jedes Original:
93
94 - Drei Topics, keine Associations, ein Name und genau ein kanonischer Variant.
95 `TOPIC!` und `http://www.w3.org/2001/XMLSchema#string` bleiben erhalten.
96 - Owner und Name-Parent sind `EQ`; Name und Variant-Parent sind `EQ`.
97 Name-, Variant-, Type- und Theme-Handles sind kanonisch. Der Variant-Scope
98 besteht genau aus dem kanonischen `DocumentIRI#command`-Topic.
99 - Ausschließlich der Variant hat den oben angegebenen Item Identifier.
100 Die Suche über alle aktuellen Information Items liefert per `EQ` genau ihn.
101 Der Owner hat nur `DocumentIRI#topic`, der Theme-Topic nur
102 `DocumentIRI#command`. Der Default-Name-Type hat nur seinen vorgesehenen SI.
103 Map und Name haben keine Item Identifier, es entstehen keine Subject
104 Locators, zusätzlichen Subject Identifier oder Reifier.
105 - Die globale Identifier-Eindeutigkeit besteht. Die zwei Quellvarianten des
106 zweiten Originals normalisieren zu einem Variant mit einem Identifier.
107
108 Alle vollständigen CXTM-Bytes entsprechen den unveränderten Originalbaselines,
109 jeweils **666/666 Bytes** einschließlich abschließendem LF.
110 `firstDifferentByte` und tatsächliche Condition sind jeweils `null`.
111 Die Kanonisierung ist deterministisch und verändert native Modellzustände und
112 Rohbytes nicht. Ein unabhängiger Source Key bei gleicher Document IRI erzeugt
113 dasselbe Modell und dieselben CXTM-Bytes.
114
115 | Original | SHA-256 Quelle | SHA-256 Baseline und tatsächliche Ausgabe |
116 | --- | --- | --- |
117 | `itemid-variant.xtm` | `73cd8cd0cea5d56f990f0653428b0cb954d730f2c2785f95cd5a0979d05dc9e3` | `e35c1eb8965421ab8c2125856623bb86079c59c07f094e0719735b3628f8382b` |
118 | `variant-duplicate-iid.xtm` | `33bad7a941744e476b2facc1a89ab8a7cea1efe063a5869c211cc9053ea6f879` | `e35c1eb8965421ab8c2125856623bb86079c59c07f094e0719735b3628f8382b` |
119
120 [variant-item-identity-originals.json](../reports/slice-21k/variant-item-identity-originals.json)
121 enthält vollständige Rohbytes als Hex und Text, Document IRI, Identifier,
122 tatsächliche Modelle, Conditions sowie alle tatsächlichen und erwarteten
123 CXTM-Texte. Die beiden tatsächlichen Ausgabedateien sind in
124 [actual/](../reports/slice-21k/actual/) erhalten.
125
126 Der bestehende Case-Record-Executor klassifiziert nur nach tatsächlicher
127 Deserialisierung, nativen Modellprüfungen und vollständigem Bytevergleich als
128 `cxtm-match`/PASS. Beide Originale werden genau einmal im regulären ASDF-Lauf
129 ausgeführt. Insgesamt bestehen 62 eindeutige Case Records: 54 positive und
130 acht ursachenqualifizierte negative Originale. Die bisherigen 60 Ergebnisse
131 bleiben unverändert. Synthetische Gegenproben zählen nicht als Originalverträge.
132
133 ## Native Identifier-, Normalisierungs- und Handle-Prüfungen
134
135 Die **49 neuen protokollierten Kontrollen** umfassen zwölf positive XTM-
136 Eingaben, neun schrittweise Merge-Prüfungen, 22 Syntax-/Konflikt-/Unsupported-
137 Prüfungen, einen rohen UTF-8-Fehler und fünf native Atomaritätsprüfungen.
138
139 Geprüft werden absolute, relative, Fragment- und leere IRI-Referenzen, Unicode,
140 Prozent-/UTF-8-Dekodierung, eine andere Document IRI sowie mehrere und doppelte
141 Identifier am selben Variant. `itemIdentity` hat keine TopicRef-Shorthand-
142 Einschränkung. Gleichwertige Variants mit demselben Identifier normalisieren
143 idempotent; gleichwertige Variants mit verschiedenen Identifiern bewahren deren
144 Vereinigung. `resourceRef` und anyURI-`resourceData` behalten Value und Datatype
145 auch mit Variant-Identifiern. Ein gleichlautender Topic-SI und Variant-II
146 bewirken keine implizite Reification oder Topic-Vereinigung.
147
148 Alle neun Kombinationen aus SI-/SL-/II-Merging von Parent-Topics, Name-Scope-
149 Themes und Variant-Scope-Themes werden mit den bestehenden Reader-Operationen
150 schrittweise ausgeführt. Vor dem Merge sind zwei Variants und deren Identifier
151 verschieden. Nach dem Merge zeigen alle festgehaltenen Name-, Variant- und
152 Theme-Handles auf die korrekten kanonischen Objekte. Die Identifier
153 `urn:v1` und `urn:v2` gehören danach ausschließlich zum gemeinsamen kanonischen
154 Variant. Retained Variant-Handles liefern beide Identifier; Parent und Scope
155 bleiben per `EQ` korrekt. Die globale Identifierprüfung und reine CXTM-
156 Kanonisierung bestehen jeweils.
157
158 Fünf separate native `add-item-identifier`-Konfliktversuche betreffen Map,
159 Owner-Topic, Name, Theme-Topic und einen anderen Variant. Für jeden Versuch
160 bleiben der vollständige native Modellzustand, Identifier-Mengen und
161 kanonischen Handles unverändert. Diese Aussage betrifft die native Zuweisung;
162 es wird keine neue Transaktionssemantik für den gesamten Reader eingeführt.
163
164 Der reguläre Lauf besteht mit **1860 eindeutigen XTM-
165 Prüfungen**: 1713 bisherige Prüfungen, davon zwei sinnvoll umbenannte Labels,
166 und **147 neue**. Die relative Reihenfolge der bisherigen
167 Prüfungen bleibt erhalten.
168
169 ## Konkrete Conditions und Syntaxgrenzen
170
171 Die folgende Tabelle stammt aus `variantItemIdentityControls` in
172 [xtm.json](../reports/slice-21k/xtm.json). Dort sind vollständige Quelltexte,
173 Kontexte, native Modelle und gegebenenfalls Causes erhalten. SAX-Positionen
174 sind ungefähre Zeichenpositionen; native TMDM-Conditions haben keine
175 Quellposition.
176
177 | Gegenprobe | Condition | Fehlercode | Zeile:Spalte |
178 | --- | --- | --- | --- |
179 | `after-scope` | `XTM-REJECTION` | `element-order` | 1:172 |
180 | `after-resource` | `XTM-REJECTION` | `element-order` | 1:202 |
181 | `missing-href` | `XTM-REJECTION` | `missing-attribute` | 1:123 |
182 | `attribute` | `XTM-REJECTION` | `unexpected-attribute` | 1:148 |
183 | `child` | `XTM-REJECTION` | `unexpected-child` | 1:135 |
184 | `text` | `XTM-REJECTION` | `unexpected-text` | 1:135 |
185 | `invalid-iri` | `XTM-REJECTION` | `invalid-iri` | 1:140 |
186 | `percent-short` | `XTM-REJECTION` | `invalid-percent-escape` | 1:138 |
187 | `percent-hex` | `XTM-REJECTION` | `invalid-percent-escape` | 1:139 |
188 | `percent-utf8` | `XTM-REJECTION` | `invalid-percent-utf8` | 1:139 |
189 | `percent-overlong` | `XTM-REJECTION` | `invalid-percent-utf8` | 1:142 |
190 | `collision-map` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
191 | `collision-topic` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
192 | `collision-name` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
193 | `collision:different-value` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
194 | `collision:different-datatype` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
195 | `collision:different-scope` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
196 | `collision-different-parent` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
197 | `topicRef-does-not-reify-variant` | `OCCURRENCE-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
198 | `scope-not-proper-superset` | `VARIANT-ERROR` | `invalid-variant-scope` | nicht vorhanden (TMDM) |
199 | `reification-still-unsupported` | `XTM-UNSUPPORTED` | `reification` | 1:121 |
200 | `other-datatype-still-unsupported` | `XTM-UNSUPPORTED` | `resource-data-datatype` | 1:238 |
201 | `invalid-raw-UTF8` | `XTM-XML-ERROR` | `xml-not-well-formed` | 1:7 |
202 | `atomic-conflict:map` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
203 | `atomic-conflict:topic` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
204 | `atomic-conflict:name` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
205 | `atomic-conflict:theme` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
206 | `atomic-conflict:other-variant` | `ITEM-IDENTIFIER-ERROR` | `duplicate-item-identifier` | nicht vorhanden (TMDM) |
207
208 Kollisionen unterschiedlicher Variants bleiben auch bei unterschiedlichem
209 Value, Datatype, Scope oder Parent native `ITEM-IDENTIFIER-ERROR` mit
210 `:duplicate-item-identifier`. Ein `topicRef` auf einen Variant-II kann keinen
211 Topic aus diesem Variant machen; der bestehende Topic-Konstruktorpfad bewahrt
212 dafür seinen Kompatibilitätsnamen `OCCURRENCE-IDENTIFIER-ERROR`.
213 Die rohe UTF-8-Fehleingabe bewahrt die XML-Cause
214 `WELL-FORMEDNESS-VIOLATION` zum ungültigen Startbyte `11111111`.
215
216 Identifier nach Scope oder Ressourcenwert sind Syntaxfehler. Scope ohne echte
217 Erweiterung erreicht `VARIANT-ERROR/:invalid-variant-scope`. Gültige
218 Reification und gültiges, nicht implementiertes `xsd:integer` bleiben spezifisch
219 Unsupported. Keine beliebige Ablehnung zählt als bestandene negative Prüfung.
220 Die nativen Conditionklassen werden weder umbenannt noch generisch verpackt.
221
222 ## Gezielte Aktualisierung einer Unsupported-Fixture
223
224 Die alte gültige, inzwischen unterstützte Item-Identity-Gegenprobe wird um
225 `reifier="#r"` ergänzt. Dieses vollständige Konstrukt bleibt gültig und liegt
226 wegen Reification außerhalb des Slices. Das Label `itemIdentity` wird zu
227 `reified-itemIdentity`, der erwartete Code von `:unsupported-construct` zu
228 `:reification`. Beide Prüfungsnamen ändern sich entsprechend.
229
230 Genau eine Zeile des alten `variantControls`-Reports ändert sich dadurch.
231 Alle anderen alten Kontrollzeilen und sämtliche bisherigen Original- und
232 Resource-Reports bleiben identisch. Es werden keine historischen Berichte
233 umgeschrieben. Sämtliche 48 übernommenen Nicht-XTM-Reports sind strukturell
234 identisch zu Slice 21J.
235
236 ## Diagnosevergleich sämtlicher 124 Originale
237
238 Genau die beiden beauftragten Beobachtungen ändern sich:
239
240 | Original | Vorher | Tatsächliches Ergebnis danach |
241 | --- | --- | --- |
242 | `itemid-variant.xtm` | `XTM-UNSUPPORTED/:unsupported-construct`, 6:44 | keine Condition, 666/666 Bytes identisch |
243 | `variant-duplicate-iid.xtm` | `XTM-UNSUPPORTED/:unsupported-construct`, 6:44 | keine Condition, 666/666 Bytes identisch |
244
245 Ursache ist die nun unterstützte Identifier-Zuweisung an den zuvor erzeugten
246 kanonischen Variant. Die übrigen **122 vollständigen Beobachtungen bleiben
247 identisch**. [diagnostic-changes.json](../reports/slice-21k/diagnostic-changes.json)
248 erhält beide vollständigen Vorher-/Nachher-Beobachtungen mit konkretem Grund.
249 Es werden keine weiteren Originalverträge aus explorativen Befunden registriert.
250
251 ## Vollständige Offline-Abnahme
252
253 Alle Testprozesse verwenden frisches **SBCL 2.5.4** ohne System-/Benutzerinit.
254 Die vorhandenen gepinnten lokalen Abhängigkeiten und XML-Patches werden geprüft
255 und in temporären Verzeichnissen verwendet. Quellvorbereitung, API-Vorprüfung,
256 Tests und Diagnose laufen zusätzlich mit Netzwerk- und Repository-Schreibsperre:
257
258 ```text
259 (version 1)(allow default)(deny network*)(deny file-write* (subpath "/Users/rgb/workspace/topic-maps"))
260 ```
261
262 Die reguläre `require_escalated`-Freigabe war erfolgreich. Die Sandbox-
263 Konfiguration und `~/.nix-profile` wurden nicht geändert. Es gab keine neuen
264 Downloads, keine langlebigen Lisp-Image-Loads und keinen vollständigen
265 Nix-Neubau. Letzterer ist ausdrücklich NOT-RUN; die frische Offline-SBCL-
266 Regression wurde vollständig ausgeführt.
267
268 | Bereich | Bestandene Prüfungen |
269 | --- | ---: |
270 | Bisherige Lisp-Regression einschließlich TMDM, CTM/CXTM, Include und Mergemap | 12100 |
271 | XTM einschließlich aller bisherigen und beider neuer Originale | 1860 |
272 | XML-Qualifikation | 146 |
273 | XTM-MERGEMAP | 217 |
274 | REGISTERED-ORIGINALS | 286 |
275 | REGISTERED-NEGATIVES | 25 |
276 | PROLOG | 171 |
277 | EMPTY2 | 13 |
278 | CTM-INTEGER | 112 |
279 | TRIPLE | 226 |
280 | ENCODING | 722 |
281 | Python-Unittests | 2 |
282 | NFC-Oracle-Vergleiche | 16294 |
283 | Isolierte, erwartet scheiternde Executor-Kontrollen | 60 |
284
285 Zusätzlich besteht die native Variant-Identifier-API-Vorprüfung erneut.
286 Die **60 Executor-Kontrollen** erhalten alle bisherigen 50 Fehlerpfade und
287 fügen je neuem Original Byteabweichung, XML-Fehler, Unsupported, einen echten
288 Konflikt zwischen verschiedenen Variants und eine falsche XTM-Condition hinzu.
289 Alle erzeugen den erwarteten ASDF-Exit 1 und zählen niemals als positiver PASS.
290 Die davor registrierten Original-PASS bleiben jeweils erhalten. Siehe
291 [failure-controls.json](../reports/slice-21k/failure-controls.json) und die
292 zugehörigen einzelnen Logs und Case-Record-Reports.
293
294 Tatsächlich registrierter Stand nach erfolgreicher Ausführung:
295
296 | Korpus | PASS | FAIL | NOT-RUN |
297 | --- | ---: | ---: | ---: |
298 | XTM | 62 | 0 | 62 |
299 | CTM | 262 | 4 | 7 |
300
301 Die offenen XTM-Verträge umfassen 59 positive und drei negative Originale.
302 Die vier bekannten CTM-FAILs bleiben unverändert: `include-template.ctm`,
303 `include-wildcard2.ctm`, `occurrence-datetime-timezone2.ctm` und
304 `occurrence-datetime2.ctm`.
305
306 ## Integrität und Reproduktion
307
308 Alle **2006 gepinnten Korpusdateien** stimmen
309 weiterhin in Größe und SHA-256 mit `references/corpus-lock.json` überein.
310 Alle **2491 historischen Reportdateien** und
311 **4744 geschützten Dateien** des Ausgangscommits
312 bleiben byteidentisch. [integrity.json](../reports/slice-21k/integrity.json)
313 enthält vollständige Hashlisten und die geprüften Ausführungsquellen.
314
315 [execution.json](../reports/slice-21k/execution.json) protokolliert alle Befehle,
316 UTC-Zeitpunkte, Sandboxregeln, erwarteten und tatsächlichen Exitcodes und die
317 registrierten Stände. [precommit-audit.json](../reports/slice-21k/precommit-audit.json)
318 sichert den finalen Änderungsumfang;
319 [artifacts.json](../reports/slice-21k/artifacts.json) enthält Größen und
320 SHA-256-Werte aller neuen Artefakte.
321
322 Reproduktion mit unbenutztem Ausgabeverzeichnis außerhalb des Repositorys:
323
324 ```sh
325 python3 scripts/validate-slice-21k.py --sbcl /nix/store/hlsiblxpxr1hax3dw9x8znd6zy097ddj-sbcl-2.5.4/bin/sbcl --output /private/tmp/topic-maps-21k-recheck
326 ```
327
328 Reader-Erweiterung, Tests, Dokumentation und geprüfte Ausführungsevidenz werden
329 zusammen lokal committet. Slice 21K endet damit.