]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/shop3-read-only-adapter-design.md
docs: design draft for a read-only SHOP3 adapter over TMDM objects
[topic-maps.git] / docs / shop3-read-only-adapter-design.md
1 # A read-only SHOP3 adapter over TMDM objects — design draft
2
3 Status: design only. Nothing described here is implemented, and no planning
4 infrastructure is added. The `topic-maps` library stays the only implementation
5 authority for TMDM objects; SHOP3 stays responsible for planning.
6
7 Based on `topic-maps` at `88994c1b` plus the readers for TMDM 7.2/7.3, and on
8 HyperDoc at `2b86477` (read, not changed).
9
10 ## 1. Place and direction
11
12 The adapter belongs in HyperDoc, next to the existing SHOP3 layer
13 (`dreyeck/shop3`), not in `topic-maps`: the library has no dependency on SHOP3
14 or HyperDoc and should not get one. The adapter
15
16 - takes one native `topic-maps.tmdm:topic-map`;
17 - reads it through the library's public readers only;
18 - returns a set of facts and, from them, a SHOP3 initial state;
19 - never writes to the map, and never creates TMDM items.
20
21 What exists in HyperDoc today:
22
23 - `dreyeck/shop3/plan-objects.lisp`: `hyperdoc-htn-plan-result`, with
24 `:execution-mode :plan-only`.
25 - `dreyeck/work/planning.lisp`: a SHOP3 domain whose initial state is written by
26 hand, e.g. `(source-known connections)`.
27 - `dreyeck/work/project`: the project CTM read into native TMDM objects, with
28 local helpers that read Associations by type and Role.
29
30 ## 2. Three layers that must stay distinguishable
31
32 Every fact the adapter produces belongs to exactly one layer.
33
34 1. **TMDM items as they are.** Topics, Topic Names, Occurrences, Associations
35 and Roles of the map. A fact of this layer restates one item, for example an
36 Occurrence of a given type on a Topic, or one Association with its Role
37 players.
38 2. **Relationships recognized by the library readers.** The type-instance and
39 supertype-subtype relationships of TMDM 7.2 and 7.3, as reported by
40 `type-instance-relationship`, `supertype-subtype-relationship` and the four
41 Topic readers. These are still stated in the map; the reader only recognizes
42 the structure the clause defines. The adapter must not re-derive them itself.
43 3. **Facts derived by named rules.** Anything the adapter computes beyond
44 layers 1 and 2: for example the transitive closure of supertype-subtype, or
45 "instance of a subtype is an instance of the supertype" (TMDM 7.3). Each
46 such fact names the rule that produced it and the facts it was produced from.
47
48 Layer 3 is optional. A first adapter can stop after layer 2.
49
50 ## 3. Fact records and warrant
51
52 A fact is a record held by the adapter, not a TMDM item:
53
54 | Field | Content |
55 |---|---|
56 | atom | the SHOP3 state atom, e.g. `(instance-of a b)` |
57 | layer | 1, 2 or 3 |
58 | source items | the TMDM item or items it restates or was recognized from |
59 | rule | for layer 3: the name of the rule; premises: the facts used |
60 | warrant | `observed`, `derived`, `inferred` or `hypothesized` |
61 | snapshot | identity of the map state the fact was read from |
62
63 The warrant belongs to the statement or derivation in the adapter. It is not
64 added to the TMDM model as a property, Occurrence or Scope.
65
66 - `observed`: layers 1 and 2. The atom corresponds to items present in the
67 snapshot.
68 - `derived`: layer 3. The atom follows from observed facts by a named rule.
69 - `inferred`, `hypothesized`: never produced by the adapter. If a caller
70 supplies such facts, they carry that label and are kept apart from the
71 exported TMDM facts.
72
73 If a map itself models provenance, for example by reifying an Association and
74 giving the Reifier Occurrences, that is ordinary TMDM content of layer 1. It is
75 read like any other content and is not the adapter's warrant.
76
77 ## 4. From facts to a SHOP3 problem
78
79 - The initial state is the list of atoms of the chosen facts.
80 - Method and operator preconditions query that state only. SHOP3 does not call
81 back into TMDM while planning, so a plan refers to one fixed snapshot.
82 - The result stays a plan-only object. Operators change the planner's state,
83 not the map.
84
85 Which TMDM statements become which predicates is declared in an explicit
86 vocabulary mapping (Association type and Role types to predicate and argument
87 order; Occurrence type to predicate). Nothing is exported that the mapping does
88 not name.
89
90 ## 5. Missing prerequisites for a plan over real TMDM objects
91
92 1. **Term names.** SHOP3 atoms need constants. A rule is needed that maps each
93 Topic to one stable constant and back. "The first Subject Identifier" is not
94 a rule: the order of a set is not significant. How SHOP3 unifies non-symbol
95 constants such as strings has to be checked before choosing a representation.
96 2. **Scope.** TMDM leaves open how a Scope defines a context (5.3.3). The
97 adapter needs a declared rule: for example, export only statements in the
98 unconstrained scope, or export a statement when its scope is contained in an
99 explicitly given set of themes. Layer 3 rules must say how they combine the
100 scopes of their premises (TMDM 7.3 gives an example).
101 3. **Vocabulary mapping.** For the project map: which Association types mean
102 dependency, which Occurrence type carries status, and what the planner's
103 predicates are called.
104 4. **Snapshot identity.** A way to tell that facts are stale, for example the
105 SHA-256 of the map's CXTM at export time.
106 5. **Derived closure.** A decision whether layer 3 is wanted at all, and if so
107 which rules.
108 6. **A planning domain.** Operators and methods are written by a person. They
109 cannot be read from the map.
110 7. **A library revision in HyperDoc that has the readers.** HyperDoc pins
111 `topic-maps` at `88994c1b`; the readers are not in that revision.
112 8. **Both default name type identifiers.** If names are exported, a Name Type
113 carrying `.../name-type` and one carrying `.../topic-name` are different
114 Topics and must not be merged into one "default" by the adapter.
115
116 ## 6. Smallest next integration task
117
118 Without any planning domain: a read-only function in HyperDoc that exports the
119 layer 2 facts of the existing project map, `instance-of` only, each with its
120 source Association, and a test that the number of exported facts equals the
121 number of Associations for which `type-instance-relationship` returns players.
122 That replaces the local type derivation in
123 `dreyeck/work/project/project-workspace.lisp` by the library reader and needs
124 only prerequisite 7 and a provisional answer to prerequisite 1.
125
126 ## 7. Out of scope
127
128 Writing plans back into a map, executing operators, a second TMDM model inside
129 HyperDoc, a user interface, and any change to identity, merging or scope in the
130 library.