]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - src/tmdm/reification.lisp
Implement same-map reification with atomic merge preflight
[topic-maps.git] / src / tmdm / reification.lisp
1 (in-package #:topic-maps.tmdm)
2
3 (define-condition reification-error (error)
4 ((code :initarg :code :reader reification-error-code)
5 (detail :initarg :detail :reader reification-error-detail))
6 (:report (lambda (c out) (format out "Reification ~A: ~A" (reification-error-code c)
7 (reification-error-detail c)))))
8 (defun reification-problem (code detail) (error 'reification-error :code code :detail detail))
9 (defun reifiable-p (item)
10 (typep item '(or topic-map topic-name variant occurrence association association-role)))
11 (defun %item-reifier (item)
12 (etypecase item
13 (topic-map (%topic-map-reifier item)) (topic-name (%topic-name-reifier item))
14 (variant (%variant-reifier item)) (occurrence (%occurrence-reifier item))
15 (association (%association-reifier item)) (association-role (%association-role-reifier item))))
16 (defun (setf %item-reifier) (value item)
17 (etypecase item
18 (topic-map (setf (%topic-map-reifier item) value)) (topic-name (setf (%topic-name-reifier item) value))
19 (variant (setf (%variant-reifier item) value)) (occurrence (setf (%occurrence-reifier item) value))
20 (association (setf (%association-reifier item) value))
21 (association-role (setf (%association-role-reifier item) value))))
22 (defun item-reifier (item)
23 "Read the stored current Reifier Topic (or NIL); Topics cannot be reified."
24 (unless (reifiable-p item) (reification-problem :not-reifiable "Topics cannot be reified."))
25 (%item-reifier (canonical-item item)))
26 (defun topic-reified (topic)
27 "Computed TMDM 5.3.5 inverse, not an independently maintained identity index."
28 (let* ((topic (canonical-topic topic))
29 (items (remove-if-not (lambda (item) (and (reifiable-p item) (eq topic (%item-reifier item))))
30 (map-information-items (%topic-parent topic)))))
31 (when (rest items) (reification-problem :reifier-conflict "A Topic reifies different live information items."))
32 (first items)))
33 (defvar *reification-mutation-active* nil)
34 (defun needs-reification-preflight-p (map)
35 (and (not *reification-mutation-active*)
36 (some (lambda (item) (and (reifiable-p item) (%item-reifier item))) (map-information-items map))))
37
38 (defun copy-map-for-preflight (map)
39 "Disposable graph of the SAME seven TMDM structures, using the same merge code.
40 Old handles resolve through their canonical representatives; no second identity model."
41 (let ((copy (make-topic-map)) (copies (make-hash-table :test #'eq)))
42 (setf (gethash map copies) copy)
43 (labels ((ref (item) (and item (or (gethash (canonical-item item) copies)
44 (reification-problem :foreign-item "Reference is outside this Topic Map."))))
45 (refs (items) (mapcar #'ref items)))
46 (dolist (tpc (%topic-map-topics map)) (setf (gethash tpc copies) (%make-topic copy)))
47 (setf (%topic-map-topics copy) (refs (%topic-map-topics map)))
48 (dolist (tpc (%topic-map-topics map))
49 (let ((new (ref tpc)))
50 (setf (%topic-subject-identifiers new) (mapcar #'copy-seq (%topic-subject-identifiers tpc))
51 (%topic-subject-locators new) (mapcar #'copy-seq (%topic-subject-locators tpc)))
52 (dolist (n (%topic-names tpc))
53 (setf (gethash n copies) (%make-topic-name (%topic-name-value n) (ref (%topic-name-type n)) new)))
54 (setf (%topic-names new) (refs (%topic-names tpc)))
55 (dolist (n (%topic-names tpc))
56 (dolist (v (%topic-name-variants n))
57 (setf (gethash v copies) (%make-variant (%variant-value v) (%variant-datatype v) (ref n))))
58 (setf (%topic-name-variants (ref n)) (refs (%topic-name-variants n))))
59 (dolist (o (%topic-occurrences tpc))
60 (setf (gethash o copies) (%make-occurrence (%occurrence-value o) (%occurrence-datatype o)
61 (ref (%occurrence-type o)) new)))
62 (setf (%topic-occurrences new) (refs (%topic-occurrences tpc)))))
63 (dolist (a (%topic-map-associations map))
64 (setf (gethash a copies) (%make-association copy (ref (%association-type a))))
65 (dolist (r (%association-roles a))
66 (setf (gethash r copies) (%make-association-role (ref a) (ref (%association-role-type r))
67 (ref (%association-role-player r)))))
68 (setf (%association-roles (ref a)) (refs (%association-roles a))))
69 (setf (%topic-map-associations copy) (refs (%topic-map-associations map)))
70 (dolist (item (map-information-items map))
71 (let ((new (ref item)))
72 (setf (%item-identifiers new) (mapcar #'copy-seq (%item-identifiers item)))
73 (when (reifiable-p item) (setf (%item-reifier new) (ref (%item-reifier item))))
74 (typecase item
75 (topic-name (setf (%topic-name-scope new) (refs (%topic-name-scope item))))
76 (variant (setf (%variant-scope new) (refs (%variant-scope item))))
77 (occurrence (setf (%occurrence-scope new) (refs (%occurrence-scope item))))
78 (association (setf (%association-scope new) (refs (%association-scope item)))))))
79 (values copy #'ref))))
80 (defun preflight-reification-mutation (map operation)
81 "Validate the complete cascade on a disposable graph before changing originals.
82 This guarantees semantic rejection before mutation, not recovery from resource exhaustion."
83 (multiple-value-bind (copy resolve) (copy-map-for-preflight map)
84 (declare (ignore copy))
85 (let ((*reification-mutation-active* t)) (funcall operation resolve)))
86 (let ((*reification-mutation-active* t)) (funcall operation #'identity)))
87
88 (defun set-item-reifier (item topic)
89 "Assert same-map Reification, returning the current item. A different existing
90 Reifier is merged with TOPIC. NIL explicitly clears. Atomic validation is API policy."
91 (unless (reifiable-p item) (reification-problem :not-reifiable "Topics cannot be reified."))
92 (let* ((item (canonical-item item)) (map (item-topic-map item)))
93 (unless (member item (map-information-items map) :test #'eq)
94 (reification-problem :invalid-item "Item is not live in its Topic Map."))
95 (when topic
96 (unless (typep topic 'topic) (reification-problem :invalid-reifier "Reifier must be a Topic or NIL."))
97 (setf topic (live-topic topic))
98 (unless (eq map (%topic-parent topic)) (reification-problem :foreign-reifier "Reifier belongs to another Topic Map.")))
99 (when (needs-reification-preflight-p map)
100 (return-from set-item-reifier
101 (preflight-reification-mutation map (lambda (ref) (set-item-reifier (funcall ref item) (and topic (funcall ref topic)))))))
102 (when topic
103 (let ((other (topic-reified topic)))
104 (when (and other (not (eq other item)))
105 (reification-problem :reifier-conflict "Topic already reifies a different information item.")))
106 (let ((old (%item-reifier item)))
107 (when (and old (not (eq old topic))) (setf topic (merge-topics old topic)))))
108 (setf item (canonical-item item) (%item-reifier item) (and topic (canonical-topic topic)))
109 item))
110 (defun merge-item-reifiers (item a b)
111 ;; A/B have been replaced. Capture raw metadata; resolve again after cascades.
112 (dolist (r (list (%item-reifier a) (%item-reifier b)))
113 (when r (set-item-reifier (canonical-item item) (canonical-topic r))))
114 (canonical-item item))
115 (defun validate-map-reification (map)
116 "Validate stored references and the inverse without repair/mutation."
117 (dolist (item (map-information-items map))
118 (when (and (reifiable-p item) (%item-reifier item))
119 (let ((r (%item-reifier item)))
120 (unless (and (typep r 'topic) (eq r (canonical-topic r))
121 (eq map (%topic-parent r)) (member r (%topic-map-topics map) :test #'eq))
122 (reification-problem :invalid-reifier "Reifier must be a current same-map Topic."))
123 (unless (eq item (topic-reified r)) (reification-problem :reifier-conflict "Inconsistent inverse.")))))
124 t)