]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/slice-22u-project-work.md
docs(tmdm): coverage matrix, relationship readers, default name types; run report
[topic-maps.git] / docs / slice-22u-project-work.md
1 # Slice 22U — Die eigene Projektarbeit als Topicmap lesen und bearbeiten
2
3 ## Ergebnis und Reichweite
4
5 Die kleine [CTM-Quelle](../examples/project-work.ctm) wird vom produktiven
6 `topic-maps.ctm:deserialize-string` gelesen. Das optionale
7 [Common-Lisp-Beispiel](../examples/project-work.lisp) arbeitet ausschließlich
8 mit öffentlichen TMDM-Operationen und CXTM. Die **27 dauerhaften Prüfungen**
9 in [tests/project-work.lisp](../tests/project-work.lisp) werden über die
10 [ASDF-Anbindung](../topic-maps.asd) im normalen
11 [Offline-Lauf](../scripts/fresh-sbcl.lisp) tatsächlich ausgeführt.
12
13 Beobachtet sind **21 native Topics** einschließlich des lokalen Vokabulars
14 und des impliziten Name-Type-Topics, **sechs Associations mit zwölf Roles**.
15 Sechs fachliche Gegenstände bilden den Ausschnitt: Projekt, Slice 22T, sein
16 Commit, seine Ausführungsevidenz, Q-XTM-LOOP und die dokumentierte Disposition
17 aus 22O. Hinzu kommt ein als Übung gekennzeichneter Scope-Topic. Lokale Type-
18 und Role-Topics dienen nur diesem Beispiel; es wird keine allgemeine
19 Projektmanagement-Ontologie oder standardisierte PSI-Sammlung eingeführt.
20
21 Das gehaltene Topic-Objekt zu Q-XTM-LOOP bleibt über die Übungsänderung hinweg
22 `EQ`. Die vorhandenen historischen Occurrence-Objekte bleiben erhalten.
23 Eine neue Occurrence ergänzt eine ausdrücklich gescopte Übungsnotiz. Ihr
24 Value lautet: „Uebung: Frage fuer die Lektuere markiert; kein historischer
25 Statuswechsel.“ Der Datentyp ist `xsd:string`, ihr Scope enthält ausschließlich
26 den Topic „Uebung; keine historische Aussage“. Der ursprüngliche ungescopte
27 Status „offene normative Frage“ wird weder ersetzt noch umgedeutet.
28
29 | Beobachtete Eigenschaft | Vorher | Nachher |
30 | --- | --- | --- |
31 | Gehaltener Q-XTM-LOOP-Topic | derselbe native Handle | `EQ` zum erneut gefundenen Topic |
32 | Topic-Identifikatoren | lokaler II und eigener SI | unverändert |
33 | Associations und Roles | sechs / zwölf | unverändert |
34 | Historische Aussagen und Quellen | aus CTM gelesen | unverändert |
35 | Übungsnotiz | nicht vorhanden | eine gescopte Occurrence |
36 | Vollständige CXTM-Ausgabe | 7.914 Bytes | 8.191 Bytes |
37 | Erste CXTM-Abweichung | — | Byte 5.141, nullbasiert |
38 | Erneutes Lesen derselben CTM-Datei | ursprüngliche Map | wieder ursprünglicher Zustand |
39
40 [Vollständiger nativer Zustand vorher](../reports/slice-22u/after/project-before-native.sexp),
41 [nachher](../reports/slice-22u/after/project-after-native.sexp),
42 [CXTM vorher](../reports/slice-22u/after/project-before.cxtm),
43 [nachher](../reports/slice-22u/after/project-after.cxtm),
44 [tatsächliche Ausgabe der Demonstration](../reports/slice-22u/after/project-repl.txt).
45 Die Zustandsansichten werden bei jedem Aufruf aus den nativen Items gelesen;
46 sie sind keine unabhängig gepflegte Projektdarstellung und kein zweites Modell.
47
48 ## Sofort im frischen Lisp ausführen
49
50 Eine frische SBCL-Sitzung ohne Benutzer-/Systeminitialisierung starten,
51 z. B. mit `sbcl --no-sysinit --no-userinit`. Für die vollständige Abnahme wurde
52 SBCL 2.5.4 verwendet. Das Beispiel selbst benötigt keine XML-/CXML-Laufzeit;
53 es lädt nur die bestehenden CTM-, TMDM- und CXTM-Systeme über ASDF.
54 Die Beispielquelle ist absichtlich ASCII, damit ihre Leselogik ANSI-Common-Lisp-
55 Dateioperationen ohne implementierungsspezifisches External Format verwendet.
56 Die ASDF-Ladeschritte sind die vorhandene Projektinfrastruktur.
57
58 [Die folgenden Schritte als ausführbare Lisp-Datei](../reports/slice-22u/repl-steps.lisp)
59 lassen sich in der frischen Sitzung mit `LOAD` ausführen oder einzeln am REPL
60 untersuchen. Sie berühren keine SLY-Konfiguration oder laufende Lisp-Images.
61
62 ```lisp
63 (require :asdf)
64 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
65 (asdf:load-asd #p"/Users/rgb/workspace/topic-maps/topic-maps.asd")
66 (asdf:load-system "topic-maps/project-work-example")
67 (use-package '(:topic-maps.tmdm :topic-maps.project-work.example))
68
69 (defparameter *example-source* #p"/Users/rgb/workspace/topic-maps/examples/project-work.ctm")
70 (defparameter *example-map* (load-map *example-source*))
71 (defparameter *held-question*
72 (find-topic *example-map* "urn:topic-maps:question:Q-XTM-LOOP"))
73 (describe *held-question*)
74 (show-topic *held-question*)
75 ;; Native Associations and their actual Role Items are navigable:
76 (dolist (association (relations *held-question*))
77 (describe association)
78 (dolist (role (association-roles association)) (describe role)))
79
80 (defparameter *before-edit*
81 (topic-maps.cxtm:canonicalize-octets *example-map* :base-locator *document-iri*))
82 (defparameter *exercise-occurrence* (add-exercise-note *example-map*))
83 (assert (eq *held-question*
84 (find-topic *example-map* "urn:topic-maps:question:Q-XTM-LOOP")))
85 (show-topic *held-question*)
86 (defparameter *after-edit*
87 (topic-maps.cxtm:canonicalize-octets *example-map* :base-locator *document-iri*))
88 (list (length *before-edit*) (length *after-edit*) (mismatch *before-edit* *after-edit*))
89 ;; => (7914 8191 5141); mismatch uses a zero-based byte position.
90
91 (defparameter *same-note-again* (add-exercise-note *example-map*))
92 (assert (eq (canonical-occurrence *exercise-occurrence*) *same-note-again*))
93 (assert (equalp *after-edit*
94 (topic-maps.cxtm:canonicalize-octets *example-map* :base-locator *document-iri*)))
95 ;; The original CTM is untouched; a fresh read contains no exercise annotation:
96 (defparameter *fresh-original* (load-map *example-source* :source-key "re-read original"))
97 (assert (equalp *before-edit*
98 (topic-maps.cxtm:canonicalize-octets *fresh-original* :base-locator *document-iri*)))
99 ```
100
101 Für eine kompakte Vorher-/Nachher-Lektüre auf einer jeweils frischen Map genügt:
102
103 ```lisp
104 (topic-maps.project-work.example:demo
105 #p"/Users/rgb/workspace/topic-maps/examples/project-work.ctm")
106 ```
107
108 `demo` gibt als ersten Wert die tatsächlich veränderte native Map zurück.
109 Weitere Werte sind Vorher-/Nachher-Ansichten, die beiden vollständigen
110 CXTM-Octet-Vektoren, der Notiz-Handle, der ursprüngliche CTM-String, der vor der
111 Änderung gehaltene Frage-Topic und die vor der Änderung gehaltenen historischen
112 Occurrences. Damit lassen sich die gleichen Objekte weiter mit `DESCRIBE`
113 oder den öffentlichen Property-Lesern untersuchen.
114
115 ## Gegenstände, Identität, Beziehungen und Belege
116
117 Die Document IRI und CXTM-Basis sind ausdrücklich
118 `https://topic-maps.example.invalid/examples/project-work.ctm`. Diese IRI
119 ist ein projektlokaler Identitätskontext; es wird nichts darüber abgerufen.
120 CTM-Identifier wie `question` ergeben Item Identifier unter dieser IRI mit
121 `#question`. Diagnostische Source Keys werden getrennt vergeben und sind keine
122 Topic-Identitäten.
123
124 Eigene `urn:topic-maps:*`-Subject-Identifier benennen Projekt, Slice, Commit,
125 Frage und Übung. Sie sind bewusste Identifier dieses Beispiels, keine neuen
126 historischen Tatsachen und keine veröffentlichten Standard-PSIs.
127 Die Dokument-Topics für Evidenz und Disposition tragen Subject Locators auf
128 konkrete Dateien. `file:`-IRIs sind in dieser Demonstration Daten; weder Reader
129 noch Query-Helfer laden ihre Ziele. Die absoluten Quellenpfade sind auf das
130 beauftragte Repository zugeschnitten und müssen bei einem Repository-Umzug
131 bewusst angepasst werden. Es gibt keinen versteckten Netzwerk- oder Dateiresolver.
132
133 | Modellierter Zusammenhang | Native Association und Roles |
134 | --- | --- |
135 | Slice gehört zum Projekt | `part-of(part: slice, whole: project)` |
136 | Commit ist ein Ergebnis des Slices | `result-of(result: commit, work: slice)` |
137 | Testevidenz ist ein Ergebnis des Slices | `result-of(result: evidence, work: slice)` |
138 | Projektarbeit betrifft die offene Frage | `concerns(work: project, subject: question)` |
139 | Quelle für den Umgang mit der Frage | `documented-by(subject: question, source: disposition)` |
140 | Quelle für die dokumentierte Slice-Abnahme | `documented-by(subject: slice, source: evidence)` |
141
142 Die Tabelle erläutert die CTM-Deklarationen. Die ausgeführten Abfragen nehmen
143 ihre Antworten aus den tatsächlichen `topic-roles-played`,
144 `association-role-parent`, `association-role-type` und `association-role-player`.
145 Alle Parent-, Type-, Player- und Scope-Referenzen werden auf kanonische `EQ`-
146 Objekte derselben Map geprüft, einschließlich inverser `rolesPlayed`-Beziehungen.
147 Die Namen erleichtern das Lesen; identifiziert wird nicht allein durch Namen.
148 `find-topic` ist lediglich eine lineare Suche in den öffentlichen Topic-Mengen.
149 Es gibt keinen zusätzlichen Identitätsindex oder unabhängigen Beziehungsgraphen.
150
151 **Geprüfte historische Quellen:**
152
153 - [22T-Abschlussbericht](slice-22t-ctm-xtm-anytype-equivalence.md): dokumentierter
154 Abschluss des Slices, zugehöriger Commit und die Grenzen des Austauschnachweises.
155 - [22T-Ausführungsevidenz](../reports/slice-22t/after/execution.json):
156 `acceptancePassed=true`, 34 Reader-Paare, vier Kontraste, 728 Äquivalenzchecks.
157 - [22O-Disposition zu Q-XTM-LOOP](slice-22o-qualified-xtm-corpus-disposition.md),
158 Abschnitt „Normative Konformität / offene Frage Q-XTM-LOOP“ und „Disposition“:
159 ungeklärter normativer Zyklusabschluss, bestehende Unsupported-Grenze und
160 unveränderter Originalstatus NOT-RUN.
161
162 Die Daten in der kleinen CTM-Map sind eine quellengebundene manuelle Auswahl,
163 kein automatischer Import aller Projektdokumente. Die tatsächlichen aus den
164 nativen Items gelesenen Fakten und ihre überprüften Dateihashes stehen im
165 [Quellenaudit](../reports/slice-22u/after/source-grounding.json).
166 Damit wird keine neue Normentscheidung getroffen. Insbesondere wird aus der
167 Übungsnotiz weder eine Priorisierung noch eine Freigabe der Zyklusimplementierung
168 abgeleitet.
169
170 ## Was die Bearbeitung tatsächlich tut
171
172 `add-exercise-note` ruft die bestehende öffentliche Operation
173 `topic-maps.tmdm:add-occurrence` auf dem kanonischen Frage-Topic auf. Es werden
174 keine privaten Slots beschrieben. Der Topic erhält eine zusätzliche Characteristic;
175 seine Identität und die Projektbeziehungen bleiben erhalten. Der Scope trennt
176 bewusst die Übungsannotation von ungescopten historischen Aussagen; er ist
177 keine Zugriffskontrolle und kein automatisches Wahrheits-/Provenienzsystem.
178
179 Die zweimalige Eingabe derselben Notiz demonstriert die bestehende
180 Occurrence-Gleichheit anhand von Parent, Type, Scope, Value und Datatype.
181 Die beiden Notizen fallen auf ein kanonisches Item zusammen. Der zuerst
182 gehaltene Occurrence-Handle ist danach in der beobachteten Implementierung
183 nicht mehr selbst `EQ` zum lebenden Item; `canonical-occurrence` löst ihn
184 weiterhin auf dasselbe Item wie den Rückgabewert des zweiten Aufrufs auf.
185 Die zweite Annotation verändert die CXTM-Bytes nicht nochmals. Das ist von der
186 unveränderten `EQ`-Identität des Frage-Topics zu unterscheiden.
187
188 `intern-topic` mit einem schon vorhandenen Subject Identifier bzw. Subject
189 Locator liefert denselben nativen Topic, ohne eine zweite Darstellung zu
190 bauen. SI, SL und II bleiben getrennte Kategorien. `normalize-topic-map` ist
191 nach der Änderung idempotent. Ein Versuch mit einem Type aus einer fremden
192 Map erreicht die native `occurrence-error` mit Code `:foreign-type`; Modell
193 und CXTM bleiben dabei unverändert.
194
195 Es gelten drei unterschiedliche Bearbeitungsebenen:
196
197 1. **Native Map im Arbeitsspeicher:** `add-occurrence` verändert die Map dieser
198 Lisp-Sitzung. Die Property-Leser geben schützende Kopien ihrer Mengen zurück;
199 private Setter sind kein Bearbeitungspfad.
200 2. **CTM-Quelle:** Die ursprüngliche Datei wird durch diese Operation nicht
201 geändert. Erneutes Deserialisieren liefert den ursprünglichen Zustand.
202 Das Beispiel entwickelt keinen CTM-Writer und keinen Source-Patch-/Roundtrip-Pfad.
203 3. **Dauerhafte Speicherung:** Die Beispielquelle und Programme sind versionierte
204 Dateien; die native Übungsänderung wird nicht automatisch gespeichert.
205 Die vorhandene CXTM-Ausgabe kann explizit als Datei geschrieben werden,
206 ist hier jedoch Ausführungsevidenz und kein nachgewiesener wieder einlesbarer
207 Workspace-/Bearbeitungszustand. Transaktionen, Undo, eine Map-Datenbank und
208 Sitzungswiederaufnahme werden nicht behauptet.
209
210 ## Abnahme und erhaltene Verträge
211
212 [27 ausgeführte Beispielprüfungen und vollständige native Beobachtung](../reports/slice-22u/after/retained/core.json.project-work.json),
213 [Vollregression](../reports/slice-22u/after/execution.json),
214 [Kommandos, Zeiten und Loghashes](../reports/slice-22u/after/runs.json).
215 Die Quelle wurde mit beiden diagnostischen Source Keys produktiv gelesen;
216 ihre Datei bleibt unverändert. Wiederholte Kanonisierung erhält alle geprüften
217 Eigenschaften und gehaltenen kanonischen Referenzen.
218
219 Der bereits gestartete Lauf endete vollständig mit **119 erwarteten Prozessausgängen**,
220 inklusive aller **113 unveränderten Executor-Fehlerkontrollen**. Bei der Fortsetzung
221 wurde dieser gespeicherte Lauf mit `--audit-only` und den aktuellen Quellhashes
222 nochmals überprüft; er wird nicht als neu durchgeführter Testlauf ausgegeben.
223 Die isolierten Vorläufe sind in `reports/slice-22u/` getrennt erhalten. Die
224 nachträgliche Lektüreprüfung wird gesondert protokolliert.
225
226 Erhalten: 12.100 Kernchecks, 4.327 XTM-Checks, 146 XML-Prüfungen, alle bisherigen
227 Slice-20-/22-Stufen, CTM/XTM- und XTM-Mergemap, 34 Äquivalenzpaare und vier
228 Kontraste mit 728 Checks, zwei Python-Tests und 16.294 NFC-Vergleiche.
229 Sämtliche bisherigen gespeicherten Regressionsberichte sind byteidentisch;
230 neu hinzu kommt nur der gesonderte Projektbeispielbericht.
231 [Berichtsvergleich](../reports/slice-22u/after/retained-reports.json),
232 [Fehlerkontrollen](../reports/slice-22u/after/failure-controls-audit.json),
233 [124 unveränderte Originaldiagnosen](../reports/slice-22u/after/diagnostic-changes.json).
234
235 | Originalkorpus | PASS | FAIL | NOT-RUN |
236 | --- | ---: | ---: | ---: |
237 | XTM 2.0 | 121 | 0 | 3 |
238 | CTM | 262 | 4 | 7 |
239
240 Das Lernbeispiel ist kein neuer Originalkorpusvertrag und erzeugt keine
241 PASS-Registrierung. Sämtliche gepinnten Originale, Baselines, Case Records und
242 historischen Reports bleiben unverändert. [Integritätsnachweis](../reports/slice-22u/after/integrity.json): **11.912**
243 geschützte Basisdateien sind unverändert, darunter **2.006** Korpusdateien und
244 **9.590** historische Reportdateien. Alle Produktionsdateien unter `src/`
245 sowie `flake.nix` und `flake.lock` bleiben byteidentisch. Bestehende Dateien
246 ändern sich ausschließlich durch die zwei optionalen ASDF-Systeme und den
247 Aufruf ihrer Tests nach den bisherigen Stufen des frischen SBCL-Laufs.
248
249 ## Befund zu Z1 und Z4–Z6; Anforderungen an Z2
250
251 **Vorhanden und ausgeführt:** Gegenstände über Identifier auffinden, verschiedene
252 Dokumente als Belege referenzieren, Beziehungen über native Roles navigieren,
253 Items inspizieren, eine gescopte Annotation hinzufügen, Gleichheit normalisieren
254 und den resultierenden Zustand kanonisch vergleichen. Damit ist ein kleiner
255 realer Projektausschnitt lesbar, untersuchbar und im Modell bearbeitbar.
256
257 **Aus der Benutzung abgeleitete Anforderungen, keine freigegebenen Arbeitspakete:**
258 Eine spätere Oberfläche müsste Gegenstandsidentität neben lesbaren Namen zeigen,
259 kanonische Handles nach Normalisierung auflösen, Scopes sichtbar machen,
260 Belegverweise bewusst öffnen und zwischen Speicherzustand und CTM-Datei
261 unterscheiden. Gerade die zwei nebeneinander bestehenden Aussagen — dokumentierter
262 Status und Übungsannotation — zeigen den Bedarf, Perspektive und Bearbeitungsart
263 sichtbar zu halten. Die aktuelle Demonstration bleibt eine REPL-Lektüre mit
264 linearen Abfragen, ohne UI, allgemeine Queries, automatische Quellensynchronisation
265 oder persistente Arbeitsumgebung. Kein Bedarf wird als automatisch beauftragte
266 Produktionsänderung behandelt.
267
268 Eine allgemeine Wertänderungs- oder Löschoperation für Occurrences wird nicht
269 vorgeführt: Die öffentlichen Value-Leser sind keine Setter, und die verwendete
270 API bietet keinen allgemeinen `set-occurrence-value`-/Löschpfad. Das Beispiel
271 bearbeitet den Gegenstand durch Ergänzen einer Characteristic. Eine darüber
272 hinausgehende Editierfähigkeit wird weder vorausgesetzt noch nachimplementiert.
273
274 Die bestehende CTM-/TMDM-/CXTM-Fähigkeit reicht für diese begrenzte Aufgabe aus.
275 Es wurde keine wesentliche Modelloperation als Voraussetzung nachimplementiert.
276 HyperDoc, SLY, externe Abhängigkeiten, Normentscheidungen und weitere Slices
277 bleiben außerhalb des Auftrags. Nach dem lokalen Commit endet Slice 22U.