From c446a8228017f405c3a2650ca893e9450ac7cd7b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 20:13:45 +0000 Subject: [PATCH] docs: design draft for a read-only SHOP3 adapter over TMDM objects A design note only: no adapter, no planning infrastructure and no code are added. It describes how a client such as HyperDoc could export SHOP3 state atoms from a native topic-map through the public readers, keeping three layers apart: the TMDM items as they are, the relationships recognized by the TMDM 7.2/7.3 readers, and facts derived by named rules. The warrant belongs to the fact record in the adapter, never to the TMDM model. It lists the prerequisites still missing for a plan over real TMDM objects and proposes the smallest next integration task. The adapter would live in the client, not in this library; the note is kept here because the library is where the readers it relies on are. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_014ewLGkKYU24V8KWmZKpjGx --- docs/shop3-read-only-adapter-design.md | 130 +++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 docs/shop3-read-only-adapter-design.md diff --git a/docs/shop3-read-only-adapter-design.md b/docs/shop3-read-only-adapter-design.md new file mode 100644 index 0000000..8658324 --- /dev/null +++ b/docs/shop3-read-only-adapter-design.md @@ -0,0 +1,130 @@ +# A read-only SHOP3 adapter over TMDM objects — design draft + +Status: design only. Nothing described here is implemented, and no planning +infrastructure is added. The `topic-maps` library stays the only implementation +authority for TMDM objects; SHOP3 stays responsible for planning. + +Based on `topic-maps` at `88994c1b` plus the readers for TMDM 7.2/7.3, and on +HyperDoc at `2b86477` (read, not changed). + +## 1. Place and direction + +The adapter belongs in HyperDoc, next to the existing SHOP3 layer +(`dreyeck/shop3`), not in `topic-maps`: the library has no dependency on SHOP3 +or HyperDoc and should not get one. The adapter + +- takes one native `topic-maps.tmdm:topic-map`; +- reads it through the library's public readers only; +- returns a set of facts and, from them, a SHOP3 initial state; +- never writes to the map, and never creates TMDM items. + +What exists in HyperDoc today: + +- `dreyeck/shop3/plan-objects.lisp`: `hyperdoc-htn-plan-result`, with + `:execution-mode :plan-only`. +- `dreyeck/work/planning.lisp`: a SHOP3 domain whose initial state is written by + hand, e.g. `(source-known connections)`. +- `dreyeck/work/project`: the project CTM read into native TMDM objects, with + local helpers that read Associations by type and Role. + +## 2. Three layers that must stay distinguishable + +Every fact the adapter produces belongs to exactly one layer. + +1. **TMDM items as they are.** Topics, Topic Names, Occurrences, Associations + and Roles of the map. A fact of this layer restates one item, for example an + Occurrence of a given type on a Topic, or one Association with its Role + players. +2. **Relationships recognized by the library readers.** The type-instance and + supertype-subtype relationships of TMDM 7.2 and 7.3, as reported by + `type-instance-relationship`, `supertype-subtype-relationship` and the four + Topic readers. These are still stated in the map; the reader only recognizes + the structure the clause defines. The adapter must not re-derive them itself. +3. **Facts derived by named rules.** Anything the adapter computes beyond + layers 1 and 2: for example the transitive closure of supertype-subtype, or + "instance of a subtype is an instance of the supertype" (TMDM 7.3). Each + such fact names the rule that produced it and the facts it was produced from. + +Layer 3 is optional. A first adapter can stop after layer 2. + +## 3. Fact records and warrant + +A fact is a record held by the adapter, not a TMDM item: + +| Field | Content | +|---|---| +| atom | the SHOP3 state atom, e.g. `(instance-of a b)` | +| layer | 1, 2 or 3 | +| source items | the TMDM item or items it restates or was recognized from | +| rule | for layer 3: the name of the rule; premises: the facts used | +| warrant | `observed`, `derived`, `inferred` or `hypothesized` | +| snapshot | identity of the map state the fact was read from | + +The warrant belongs to the statement or derivation in the adapter. It is not +added to the TMDM model as a property, Occurrence or Scope. + +- `observed`: layers 1 and 2. The atom corresponds to items present in the + snapshot. +- `derived`: layer 3. The atom follows from observed facts by a named rule. +- `inferred`, `hypothesized`: never produced by the adapter. If a caller + supplies such facts, they carry that label and are kept apart from the + exported TMDM facts. + +If a map itself models provenance, for example by reifying an Association and +giving the Reifier Occurrences, that is ordinary TMDM content of layer 1. It is +read like any other content and is not the adapter's warrant. + +## 4. From facts to a SHOP3 problem + +- The initial state is the list of atoms of the chosen facts. +- Method and operator preconditions query that state only. SHOP3 does not call + back into TMDM while planning, so a plan refers to one fixed snapshot. +- The result stays a plan-only object. Operators change the planner's state, + not the map. + +Which TMDM statements become which predicates is declared in an explicit +vocabulary mapping (Association type and Role types to predicate and argument +order; Occurrence type to predicate). Nothing is exported that the mapping does +not name. + +## 5. Missing prerequisites for a plan over real TMDM objects + +1. **Term names.** SHOP3 atoms need constants. A rule is needed that maps each + Topic to one stable constant and back. "The first Subject Identifier" is not + a rule: the order of a set is not significant. How SHOP3 unifies non-symbol + constants such as strings has to be checked before choosing a representation. +2. **Scope.** TMDM leaves open how a Scope defines a context (5.3.3). The + adapter needs a declared rule: for example, export only statements in the + unconstrained scope, or export a statement when its scope is contained in an + explicitly given set of themes. Layer 3 rules must say how they combine the + scopes of their premises (TMDM 7.3 gives an example). +3. **Vocabulary mapping.** For the project map: which Association types mean + dependency, which Occurrence type carries status, and what the planner's + predicates are called. +4. **Snapshot identity.** A way to tell that facts are stale, for example the + SHA-256 of the map's CXTM at export time. +5. **Derived closure.** A decision whether layer 3 is wanted at all, and if so + which rules. +6. **A planning domain.** Operators and methods are written by a person. They + cannot be read from the map. +7. **A library revision in HyperDoc that has the readers.** HyperDoc pins + `topic-maps` at `88994c1b`; the readers are not in that revision. +8. **Both default name type identifiers.** If names are exported, a Name Type + carrying `.../name-type` and one carrying `.../topic-name` are different + Topics and must not be merged into one "default" by the adapter. + +## 6. Smallest next integration task + +Without any planning domain: a read-only function in HyperDoc that exports the +layer 2 facts of the existing project map, `instance-of` only, each with its +source Association, and a test that the number of exported facts equals the +number of Associations for which `type-instance-relationship` returns players. +That replaces the local type derivation in +`dreyeck/work/project/project-workspace.lisp` by the library reader and needs +only prerequisite 7 and a provisional answer to prerequisite 1. + +## 7. Out of scope + +Writing plans back into a map, executing operators, a second TMDM model inside +HyperDoc, a user interface, and any change to identity, merging or scope in the +library. -- 2.39.5