]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/slice-21i-xtm-variant-resourceref.md
Implement XTM occurrence reification with native conformance evidence
[topic-maps.git] / docs / slice-21i-xtm-variant-resourceref.md
1 # Slice 21I — XTM Variant ResourceRef
2
3 ## Ausgangszustand und begrenzte Änderung
4
5 Branch: `codex/xtm-slice-21i`. Ausgangscommit und vorgesehener Parent:
6 `034d2c14fbf6a58a062351e4b64680283d241d22`.
7 Der vorgefundene Branch war `codex/xtm-slice-21h`; Index und Arbeitsbaum waren
8 sauber. [initial-state.json](../reports/slice-21i/initial-state.json) sichert alle
9 ursprünglich versionierten Dateien über SHA-256.
10
11 Vor der Reader-Änderung wurden die 1414 XTM-Prüfungen und alle 124
12 Originaldiagnosen in einem frischen Offline-Prozess reproduziert. Die Ergebnisse
13 sind identisch zu Slice 21H: **XTM 57 PASS, 0 FAIL, 67 NOT-RUN** und
14 **CTM 262 PASS, 4 FAIL, 7 NOT-RUN**.
15 Siehe [baseline.log](../reports/slice-21i/baseline.log),
16 [baseline-xtm.json](../reports/slice-21i/baseline-xtm.json) und
17 [before-diagnostics.json](../reports/slice-21i/before-diagnostics.json).
18
19 Nur `src/xtm/reader.lisp` enthält eine Produktionsänderung:
20
21 - `validate-source` akzeptiert die bereits eingeordnete Variant-Alternative
22 `resourceRef` nach der vorhandenen `leaf-href`-Validierung.
23 - `read-variant` verwendet für `resourceRef` denselben `leaf-href`-/IRI-Pfad und
24 übergibt dessen absoluten Locator sowie `iri-datatype` an `add-variant`.
25 Für textuelles `resourceData` bleibt der Wertpfad mit `string-datatype` erhalten.
26 - Scope-Vereinigung, echte Obermengenbedingung, Normalisierung und kanonische
27 Handles verwenden weiterhin die bestehenden TMDM-Operationen. Die
28 Topic-Referenzauflösung `reference-iri` wird weiterhin nur für die Scope-Topics
29 verwendet; der Ressourcenlocator löst keine Topic-Suche oder Erzeugung aus.
30
31 Es gibt keine Produktionsänderung an TMDM, CTM, CXTM oder XML und keine zweite
32 IRI-Implementierung. `resourceData` mit `xsd:anyURI`, andere neue Datentypen,
33 Variant-Item-Identifier, Reification, Occurrences, explizite Associations/Roles,
34 XTM-`mergeMap` und XTM 2.1 bleiben außerhalb des implementierten Umfangs.
35
36 ## Normative Herleitung
37
38 [XTM 2.0 §§4.3.3–4.3.4](https://www.isotopicmaps.org/sam/sam-xtm/)
39 verlangen UTF-8-Prozentdekodierung und absolute Auflösung gegen die Document
40 IRI. §4.17 ordnet den Ressourcenlocator dem Variant-Wert und `xsd:anyURI` dem
41 Datentyp zu. §§4.12–4.13 vereinigen den expliziten Scope mit dem Name-Scope.
42 Anders als `topicRef` braucht `resourceRef` keinen XPointer-Shorthand-Fragmentbezeichner.
43 [TMDM §5.5](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
44 verlangt einen Variant-Scope als echte Obermenge des Parent-Name-Scope und
45 bestimmt Variant-Gleichheit über Parent, Value, Datatype und Scope.
46 Die folgenden Befunde stammen aus der tatsächlichen Ausführung.
47
48 ## Zwei unveränderte Originalverträge
49
50 | Original | Quellbytes | Tatsächliches `href` | CXTM-Ist/Soll-Bytes | Vergleich |
51 | --- | ---: | --- | ---: | --- |
52 | `variant-resourceref.xtm` | 324 | `http://example.org/command.wav` | 621/621 | PASS |
53 | `variant-resourceref-relative.xtm` | 311 | `topic-command.wav` | 608/608 | PASS |
54
55 Für jeden Vertrag lautet die Document IRI:
56 `https://xtm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/`
57 plus dessen Case-ID `xtm2/in/<Dateiname>`. Der Source Key ist die Case-ID.
58 Die unveränderten Rohbytes werden über `topic-maps.xtm:deserialize-octets` und
59 den qualifizierten XML-Parser deserialisiert.
60
61 Tatsächlich gespeicherte absolute Ressourcenwerte:
62
63 ```text
64 http://example.org/command.wav
65 https://xtm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/xtm2/in/topic-command.wav
66 ```
67
68 Beide Variants haben den Datentyp
69 `http://www.w3.org/2001/XMLSchema#anyURI`.
70 Die relative Darstellung `topic-command.wav` in der zweiten CXTM-Baseline ist
71 eine Darstellung der Kanonisierung; im TMDM-Modell steht der oben geprüfte
72 absolute Locator. Beide vollständigen Originalvergleiche sind byteidentisch,
73 `firstDifferentByte` und tatsächliche Condition sind jeweils `null`.
74
75 Native Assertions prüfen für beide Originale:
76
77 - Genau drei Topics, keine Associations, ein Name mit Value `Topic` und ein
78 Variant. Der Owner hat nur `DocumentIRI#topic` als Item Identifier, der
79 Theme-Topic nur `DocumentIRI#command`. Der Default-Name-Type hat nur den
80 vorgesehenen Subject Identifier. Es entstehen keine Ressourcen-Topics,
81 Subject Locators oder zusätzlichen Subject/Item Identifier.
82 - Name-Parent und Owner sind `EQ`, Variant-Parent und Name sind `EQ`, Name-
83 und Variant-Handles sind kanonisch. Der Name-Scope ist leer, der Variant-Scope
84 enthält genau den kanonischen `command`-Topic. Keine Item Identifier oder
85 Reifier entstehen an Name oder Variant.
86 - Die Kanonisierung ist deterministisch und lässt native Modellzustände und
87 Rohbytes unverändert. Ein unabhängiger Source Key bei gleichem Document IRI
88 ergibt dasselbe vollständige Modell und dieselben CXTM-Bytes.
89
90 Der bestehende Case-Record-Executor klassifiziert erst nach Deserialisierung,
91 nativen Prüfungen und Erzeugung der tatsächlichen CXTM-Bytes. Nur identische
92 Originalbytes/Baselines ergeben `cxtm-match` und PASS. Jeder der beiden Fälle
93 wird genau einmal im regulären ASDF-Lauf ausgeführt. Insgesamt sind es 59
94 verschiedene Case Records: 51 positive und acht ursachenqualifizierte negative
95 Originalverträge. Alle bisherigen 57 Originalergebnisse sind unverändert.
96
97 [variant-resource-ref-originals.json](../reports/slice-21i/variant-resource-ref-originals.json)
98 enthält Rohbytes als Hex und Text, Document IRI, tatsächliche Modelle, sämtliche
99 CXTM-Texte und Hashes. Die unveränderten Originalbaselines und die tatsächlichen
100 Ausgaben in [actual/](../reports/slice-21i/actual/) haben dieselben SHA-256-Werte:
101
102 | Original | SHA-256 Quelle | SHA-256 Baseline und tatsächliche Ausgabe |
103 | --- | --- | --- |
104 | `variant-resourceref.xtm` | `3ef9cc70f8738b2729d446c4e685bd9a60d39ecef7c222cb2932a307791008ad` | `d4df2bef650becff7918ee85af338631c87a4309ad65e64a26ee93edbb42a8bb` |
105 | `variant-resourceref-relative.xtm` | `7eac62ef6eb43dd582f6bdf2810529161bcbec2cb6704ffed1c7a5b20515ef4e` | `2b5d69bc4bc9bb0bf5c7c3846a19344560b28f7fbd5c20b651be5189911787f0` |
106
107 ## Dauerhafte Gegenproben und tatsächliche Conditions
108
109 Der ASDF-Testlauf führt **1557 eindeutige XTM-Prüfungen** aus:
110 1414 bisherige Prüfungen, davon zwölf sinnvoll umbenannte
111 Unsupported-Gegenproben, und 143 neue Prüfungen. Die relative
112 Ausführungsreihenfolge der bisherigen Prüfungen bleibt erhalten.
113
114 Die **48 neuen protokollierten Kontrollen** umfassen 14 positive XTM-Eingaben,
115 neun schrittweise Merge-Prüfungen und 25 Syntax-/Modell-/XML-Fehlerprüfungen.
116 Geprüft werden absolute, relative, leere und Fragmentreferenzen, Unicode,
117 UTF-8-Prozentkodierung, reservierte Prozentzeichen, XML-Escaping, abweichende
118 Document IRI, Datei- und externe XML-Locators ohne Abruf sowie identische
119 Locatorstrings als Ressourcenwerte und vorhandene Topic-Identifikatoren.
120 Ein zusätzlicher Zähler weist genau einen primären XML-Parse nach; es findet
121 keine rekursive Deserialisierung der referenzierten XML-Ressource statt.
122 Die Tests laufen mit Netzwerksperre. Auch ein nicht vorhandener `file:`-Locator
123 wird als Wert akzeptiert, ohne die Datei zu öffnen.
124
125 Scope-Vererbung, Forward References, doppelte Themes, gleichwertige Variants,
126 Trennung bei verschiedenen Values/Datatypes/Scopes und SI-/SL-/II-Merging
127 werden an tatsächlichen Modellobjekten geprüft. Die vorhandene schrittweise
128 Merge-Prüfung hält alte Name-, Variant- und Theme-Handles fest; alle neun
129 Kombinationen aus Parent-/Name-Scope-/Variant-Scope-Merging und SI/SL/II behalten
130 kanonische `EQ`-Referenzen. Unzulässige Scope-Kollapse werden in drei nativen
131 SI-/SL-/II-Gegenproben atomar und ohne Verlust vorhandener Handles abgelehnt.
132
133 Die tatsächlichen Fehler sind in
134 [xtm.json](../reports/slice-21i/xtm.json), Feld `variantResourceRefControls`,
135 mit Eingabe, Kontext und gegebenenfalls Cause dokumentiert. SAX-Positionen sind
136 ungefähre Zeichenpositionen; TMDM-Conditions besitzen keine Quellposition.
137
138 | Gegenprobe | Condition | Code | Zeile:Spalte |
139 | --- | --- | --- | --- |
140 | `missing-href` | `XTM-REJECTION` | `missing-attribute` | 1:158 |
141 | `extra-attribute` | `XTM-REJECTION` | `unexpected-attribute` | 1:183 |
142 | `namespaced-attribute` | `XTM-REJECTION` | `unexpected-attribute` | 1:202 |
143 | `child` | `XTM-REJECTION` | `unexpected-child` | 1:170 |
144 | `text` | `XTM-REJECTION` | `unexpected-text` | 1:170 |
145 | `invalid-iri` | `XTM-REJECTION` | `invalid-iri` | 1:175 |
146 | `invalid-decoded-iri` | `XTM-REJECTION` | `invalid-iri` | 1:174 |
147 | `invalid-relative-iri` | `XTM-REJECTION` | `invalid-iri` | 1:179 |
148 | `percent-short` | `XTM-REJECTION` | `invalid-percent-escape` | 1:173 |
149 | `percent-hex` | `XTM-REJECTION` | `invalid-percent-escape` | 1:174 |
150 | `percent-incomplete-utf8` | `XTM-REJECTION` | `invalid-percent-utf8` | 1:174 |
151 | `percent-overlong-utf8` | `XTM-REJECTION` | `invalid-percent-utf8` | 1:177 |
152 | `percent-surrogate` | `XTM-REJECTION` | `invalid-percent-utf8` | 1:180 |
153 | `mixed-ref-data` | `XTM-REJECTION` | `variant-resource-cardinality` | 1:185 |
154 | `multiple-ref` | `XTM-REJECTION` | `variant-resource-cardinality` | 1:198 |
155 | `wrong-order` | `XTM-REJECTION` | `missing-variant-scope` | 1:135 |
156 | `scope-after-resource` | `XTM-REJECTION` | `element-order` | 1:178 |
157 | `equal-scope` | `VARIANT-ERROR` | `invalid-variant-scope` | nicht vorhanden (TMDM) |
158 | `duplicate-scope-no-new-theme` | `VARIANT-ERROR` | `invalid-variant-scope` | nicht vorhanden (TMDM) |
159 | `SI-alias-adds-no-theme` | `VARIANT-ERROR` | `invalid-variant-scope` | nicht vorhanden (TMDM) |
160 | `forward-merge-collapses-proper-scope` | `VARIANT-ERROR` | `variant-scope-collapse` | nicht vorhanden (TMDM) |
161 | `invalid-raw-UTF8` | `XTM-XML-ERROR` | `xml-not-well-formed` | 1:7 |
162 | `collapse-SUBJECT-IDENTIFIER` | `VARIANT-ERROR` | `variant-scope-collapse` | nicht vorhanden (TMDM) |
163 | `collapse-SUBJECT-LOCATOR` | `VARIANT-ERROR` | `variant-scope-collapse` | nicht vorhanden (TMDM) |
164 | `collapse-ITEM-IDENTIFIER` | `VARIANT-ERROR` | `variant-scope-collapse` | nicht vorhanden (TMDM) |
165
166 Die rohe ungültige UTF-8-Eingabe hat zusätzlich die Cause
167 `WELL-FORMEDNESS-VIOLATION` mit der Meldung über das ungültige Startbyte `11111111`.
168 Syntaxfehler, XML-Fehler, TMDM-Konflikte und Unsupported bleiben getrennte
169 Ergebnisklassen.
170
171 ## Anpassung bestehender Unsupported-Gegenproben
172
173 Da `resourceRef` jetzt unterstützt wird, prüfen die vorhandenen Unsupported-
174 Kontrollen stattdessen gültiges, weiterhin ausgeschlossenes `resourceData` mit
175 Datentyp `xsd:anyURI`. Ihre konkrete Ablehnungsursache lautet
176 `XTM-UNSUPPORTED/:resource-data-datatype`. Fünf Zeilen der bestehenden
177 XTM-Kontrollreports ändern sich dadurch gezielt; alle übrigen alten
178 Kontrollzeilen und alle Originalergebnisse bleiben erhalten.
179
180 Der erste vollständige Regressionsversuch fand dieselbe veraltete Erwartung im
181 CTM/XTM-Testadapter. Nur dessen Testeingabe, Label und erwarteter spezifischer
182 Fehlercode wurden korrigiert; kein CTM-Produktionscode wurde geändert.
183 [preliminary-execution.json](../reports/slice-21i/preliminary-execution.json)
184 und [preliminary-regression.log](../reports/slice-21i/preliminary-regression.log)
185 erhalten den abgebrochenen Versuch ausdrücklich als nicht abgenommen.
186
187 Von 48 übernommenen Nicht-XTM-Reports sind **46 strukturell identisch** zu
188 Slice 21H. Zwei Mergemap-Reports unterscheiden sich ausschließlich in den fünf
189 zugehörigen Prüfungslabels und der einen Unsupported-Condition. Der Validator
190 prüft diese konkrete Transformation gegen historische Eingaben, ohne
191 historische Reportdateien umzuschreiben. Alle Original-Case-Records und
192 Konformitätszahlen dieser Reports bleiben unverändert.
193
194 ## Alle 124 Diagnosedifferenzen
195
196 Die Vorher-/Nachher-Diagnose führt alle 124 Originalquellen aus. Genau zwei
197 Beobachtungen ändern sich:
198
199 | Original | Vorherige Condition und Position | Tatsächliches Ergebnis danach |
200 | --- | --- | --- |
201 | `variant-resourceref.xtm` | `XTM-UNSUPPORTED/:unsupported-construct`, 9:61 | keine Condition, 621/621 Bytes identisch |
202 | `variant-resourceref-relative.xtm` | `XTM-UNSUPPORTED/:unsupported-construct`, 9:48 | keine Condition, 608/608 Bytes identisch |
203
204 Ursache ist ausschließlich die nun unterstützte Variant-ResourceRef-Alternative.
205 Die übrigen **122 vollständigen Beobachtungen bleiben identisch**.
206 Insbesondere bleibt `variant-resourcedata-uri.xtm` unverändert
207 `XTM-UNSUPPORTED/:resource-data-datatype`.
208 [diagnostic-changes.json](../reports/slice-21i/diagnostic-changes.json) enthält
209 beide vollständigen Beobachtungen und deren konkrete Begründung.
210 Die Diagnose bewirkt keine weiteren Konformitätsregistrierungen.
211
212 ## Erfolgreiche vollständige Offline-Abnahme
213
214 Alle Testprozesse verwenden frisches **SBCL 2.5.4** ohne System- oder
215 Benutzerinitialisierung. Die vorhandenen gepinnten lokalen Abhängigkeiten und
216 bestehenden XML-Patches werden in temporären Verzeichnissen qualifiziert.
217 Quellvorbereitung und Tests laufen zusätzlich unter:
218
219 ```text
220 (version 1)(allow default)(deny network*)(deny file-write* (subpath "/Users/rgb/workspace/topic-maps"))
221 ```
222
223 Die reguläre `require_escalated`-Freigabe war erfolgreich. Es gibt keine
224 Änderung an `~/.nix-profile` oder der Sandbox-Konfiguration. Es gab keine neuen
225 Abhängigkeitsdownloads, keinen Zugriff auf langlebige Lisp-Images und keinen
226 vollständigen Nix-Neubau. Letzterer ist ausdrücklich NOT-RUN; die geforderte
227 frische Offline-SBCL-Regression wurde vollständig ausgeführt.
228
229 | Bereich | Bestandene Prüfungen |
230 | --- | ---: |
231 | Bisherige Lisp-Regression einschließlich TMDM, CTM/CXTM, Include und Mergemap | 12100 |
232 | XTM einschließlich aller bisherigen Originale und neuer ResourceRef-Verträge | 1557 |
233 | XML-Qualifikation | 146 |
234 | XTM-MERGEMAP | 217 |
235 | REGISTERED-ORIGINALS | 286 |
236 | REGISTERED-NEGATIVES | 25 |
237 | PROLOG | 171 |
238 | EMPTY2 | 13 |
239 | CTM-INTEGER | 112 |
240 | TRIPLE | 226 |
241 | ENCODING | 722 |
242 | Python-Unit-Tests | 2 |
243 | NFC-Oracle-Vergleiche | 16294 |
244 | Isolierte, erwartet scheiternde Fehlerpfadkontrollen | 45 |
245
246 Die 45 Fehlerpfadkontrollen enthalten die bisherigen 35 Kontrollen sowie für
247 jedes neue Original fünf weitere: Byteabweichung, XML-Fehler, Unsupported,
248 TMDM-Fehler und falsche XTM-Condition. Alle bewirken den erwarteten ASDF-Exit 1
249 und werden niemals als positiver PASS gewertet. Die übrigen Original-PASS vor
250 dem jeweiligen Ziel bleiben erhalten. Siehe
251 [failure-controls.json](../reports/slice-21i/failure-controls.json) und die
252 zugehörigen einzelnen Logs und Case-Record-Reports.
253
254 Tatsächlich registrierter Stand nach erfolgreicher Abnahme:
255
256 | Korpus | PASS | FAIL | NOT-RUN |
257 | --- | ---: | ---: | ---: |
258 | XTM | 59 | 0 | 65 |
259 | CTM | 262 | 4 | 7 |
260
261 Die XTM-NOT-RUN-Zahl umfasst 62 positive und drei negative unregistrierte
262 Originalverträge. Die vier bekannten CTM-FAILs bleiben `include-template.ctm`,
263 `include-wildcard2.ctm`, `occurrence-datetime-timezone2.ctm` und
264 `occurrence-datetime2.ctm`.
265
266 ## Integrität und Reproduktion
267
268 Alle **2006 gepinnten Korpusdateien** entsprechen
269 weiterhin in Größe und SHA-256 `references/corpus-lock.json`.
270 Alle **2154 historischen Reportdateien** und
271 **4396 geschützten Dateien** des Ausgangscommits
272 bleiben byteidentisch. Die vollständigen Hashlisten und Ausführungsquellen
273 stehen in [integrity.json](../reports/slice-21i/integrity.json).
274
275 [execution.json](../reports/slice-21i/execution.json) protokolliert sämtliche
276 Befehle, UTC-Zeitpunkte, Sandboxregeln, erwarteten und tatsächlichen Exitcodes,
277 Konformitätsstände und Retargeting-Listen.
278 [precommit-audit.json](../reports/slice-21i/precommit-audit.json) prüft den
279 finalen Änderungsumfang; [artifacts.json](../reports/slice-21i/artifacts.json)
280 sichert alle neuen Dateien über Größe und SHA-256.
281
282 Reproduktion mit unbenutztem Ausgabeverzeichnis außerhalb des Repositorys:
283
284 ```sh
285 python3 scripts/validate-slice-21i.py --sbcl /nix/store/hlsiblxpxr1hax3dw9x8znd6zy097ddj-sbcl-2.5.4/bin/sbcl --output /private/tmp/topic-maps-21i-recheck
286 ```
287
288 Reader-Erweiterung, Tests, Dokumentation und geprüfte Ausführungsevidenz werden
289 zusammen lokal committet. Slice 21I endet damit.