kapps-semantic-middleware 0.1.0__py3-none-any.whl

kapps_semantic_middleware/AGENTS.md

@@ -0,0 +1,170 @@
+# AGENTS.md
+
+Orientation for an agent building against `kapps_semantic_middleware`.
+
+This library lets a piece of Python code running on or next to a shopfloor resource expose its
+functionality through an RDF knowledge graph, and lets other middleware instances discover and
+invoke that functionality through the graph rather than through hardcoded network references.
+
+If you are prototyping against this middleware, read the consumption rules below first. They are
+constraints that **do not surface in type signatures** — most of them fail silently, producing
+structurally wrong behavior rather than an exception. Then read the mechanics pages for whichever
+part you are touching.
+
+## Where to read what
+
+**Vocabulary — what the words mean.** Read these before the mechanics pages; the mechanics pages
+assume their terms and do not re-define them.
+
+| File | Covers |
+|---|---|
+| [`CONTEXT-MAP.md`](CONTEXT-MAP.md) | The five contexts, how they depend on each other, and the three-module ontology layering |
+| [`src/kapps_semantic_middleware/CONTEXT.md`](src/kapps_semantic_middleware/CONTEXT.md) | The core vocabulary: Service, Workflow, Parameter, ClassScope, Projection, Binding descriptor, Operation, Mode |
+| [`src/kapps_semantic_middleware/shacl_interop/CONTEXT.md`](src/kapps_semantic_middleware/shacl_interop/CONTEXT.md) | Precondition and outcome shapes derived from a function's type hints |
+| [`examples/CONTEXT.md`](examples/CONTEXT.md) | The self-contained scenario notebooks |
+| [`demo/transferunits/CONTEXT.md`](demo/transferunits/CONTEXT.md) | The runnable multi-process factory demonstration |
+
+**Mechanics — how to use it.** Written in construction order; a reader can go start to finish
+without forward references.
+
+| Page | Covers |
+|---|---|
+| [`docs/mechanics/01-instantiation-and-lifecycle.md`](docs/mechanics/01-instantiation-and-lifecycle.md) | Constructing an instance, choosing a mode, what appears in the graph at startup, heartbeat, deregistration |
+| [`docs/mechanics/02-workflow-registration.md`](docs/mechanics/02-workflow-registration.md) | Declaring what a Service exposes, the ontology prerequisites, signature-derived shapes, address vs. endpoint |
+| [`docs/mechanics/03-state-and-parameters.md`](docs/mechanics/03-state-and-parameters.md) | Modelling resource state as Parameters, committed value vs. locator, where a parameter's shape comes from |
+| [`docs/mechanics/04-connector-binding.md`](docs/mechanics/04-connector-binding.md) | The recognition chain, adding a protocol the library does not ship, connector wiring, transports |
+| [`docs/mechanics/05-operation-coordination.md`](docs/mechanics/05-operation-coordination.md) | Dispatch, the event trigger, pull-and-run, the status lifecycle, handover, recovery |
+| [`docs/mechanics/06-views-and-projection.md`](docs/mechanics/06-views-and-projection.md) | Defining a ClassScope, what a view cannot select, what the northbound projection removes |
+| [`docs/mechanics/07-writing-to-the-graph-and-to-devices.md`](docs/mechanics/07-writing-to-the-graph-and-to-devices.md) | Every path that causes a write, naming the field that moved, northbound vs. southbound, IRI handling |
+| [`docs/mechanics/08-provisioning-and-seeding.md`](docs/mechanics/08-provisioning-and-seeding.md) | **Read first if `ogm=` is a mystery.** The bootstrap order, loading the shared ontologies, authoring the domain TBox, and seeding the instance data a Parameter needs |
+
+### A note on the citations you will find in the glossaries
+
+The `CONTEXT.md` files cite architecture decision records as **ADR 00nn** and **root ADR
+000n**. Those records are development-repository material and are **not part of this
+distribution** — no copy of them ships, and the release rewrites every path that pointed
+at one, so a citation here is never a link you can follow.
+
+**Do not go looking for them.** The citations are provenance markers, not links. Every mechanism a
+glossary cites a record for is explained in full by the mechanics page covering it — ADR 0004's
+subject is the "Address and endpoint" section of
+[`02-workflow-registration.md`](docs/mechanics/02-workflow-registration.md), ADR 0006's is "The
+graph-facing connector" in [`04-connector-binding.md`](docs/mechanics/04-connector-binding.md), and
+so on. If a citation seems to point at something the mechanics pages do not cover, that is a
+documentation bug worth reporting, not a missing file worth hunting.
+
+## Where the names come from
+
+This library re-exports much of its surface from its three dependencies, so the import you need is
+often *not* from `kapps_semantic_middleware`. Use this table rather than guessing.
+
+| Name | Import from |
+|---|---|
+| `SemanticMiddleware`, `Mode` | `kapps_semantic_middleware` |
+| `IRI`, `GraphDB` | `kapps_triplestore_interface` |
+| `OGM` | `kapps_ogm` |
+| `ClassScope` | `kapps_ogm.utils.class_scope` |
+| `SyncDirection` | `transitional_sync_middleware.middleware.sync.synced_connector` |
+| `ConnectionInfo` | `transitional_sync_middleware.middleware.registries` |
+| `INF` (the interface vocabulary) | `kapps_semantic_middleware.vocabulary` |
+| `graphdb_for`, `credentials_for` | `kapps_semantic_middleware.credentials` |
+| `DataModel`, `Reference`, `Identifier` | `kapps_semantic_middleware` (re-exported from `transitional_sync_middleware`) |
+
+Binding internals, if you are adding a protocol, live under
+`kapps_semantic_middleware.connectors` — `semantic`, `mqtt_binding`, `rest_binding`,
+`knowledge_graph_connector`, `wiring`.
+
+> `kapps_semantic_middleware/ontology/` is **not** a Python module. It is the directory holding the
+> three vocabulary files (`core.ttl`, `mes.ttl`, `service.ttl`). Importing from it fails.
+
+## Consumption rules
+
+### These fail silently
+
+**`GraphDB.from_env()` connects to whatever `GRAPHDB_REPOSITORY` names, and seeding destroys what it
+connects to.** `seeding.clear_repository` clears the default graph of the client's current
+repository, so a value left over in a shell — from another project, another checkout, a `.bashrc`
+written months ago — silently redirects a wipe. Nothing validates that the repository was the one you
+meant; it only has to exist. Use `credentials.graphdb_for("name")`, which names the repository in
+code and ignores the variable, for anything that seeds, clears, or re-seeds. Note this hazard belongs
+to the *variable*, not the server: pinning the repository does not stop `GRAPHDB_URL` pointing at a
+shared instance.
+
+**A `ClassScope` terminates at a Parameter and cannot select within one.** Any chain element below
+a complex property is silently discarded during fetch. A view that tries to reach inside a
+parameter blanknode materializes only as far as the parameter itself, with no error raised. A scope
+chooses *which* parameters, never *which parts* of one.
+
+**Connector bindings must be registered at construction, not later.** The framework calls
+`connect()` on everything in the connection registry before it runs `on_start_up` callbacks. A
+connector registered after construction never has `connect()` called, so inbound traffic dies
+silently — the listener task never starts and the queue is never fed — while outbound may limp
+along, making the fault one-directional and quiet.
+
+**A Parameter's shape comes from the TBox restriction on its property's range, not from the
+instance data.** Anything the restriction does not declare is dropped at materialization with only
+a warning logged. Metadata a connector needs must be declared in the restriction or it never
+arrives, and the connector fails with nothing raised.
+
+**Under the locator pattern a Parameter's value is not in the graph at all.** Fast-changing
+parameters keep only metadata in the graph; the live value exists only in the datamodel and over
+REST. An unobserved parameter materializes as an empty list, which means *not yet read* — not zero,
+and not null. Handle the empty case.
+
+**A persistence write must name the region of the model that changed.** The fan-out notifies only
+the connectors that region covers. A write that does not name its field notifies every synced
+connector, so devices are written that nobody touched — and for a settable parameter that
+fabricates a command rather than merely wasting traffic.
+
+**The northbound REST payload never carries protocol connection metadata.** Broker addresses,
+topics and endpoints are pruned from the served datamodel *before* any data is fetched. This is
+structural, not a permission check: the northbound model has no field able to carry a broker
+address. It stops a peer *learning* an address from this surface; it does not stop someone who
+already knows it.
+
+**OWL existential restrictions do not make a field required.** Only SHACL shapes enforce
+requiredness, and only at admission. A parameter with no observed value does not raise a validation
+error on materialization merely because its restriction declares `owl:someValuesFrom`. Absence of a
+triple means *unknown*, never *false*.
+
+**Any prettified or shortened IRI is display only.** Production code carries fully back-resolvable
+IRIs in their mangled form — REST path segments, datamodel field names, `svc:endpoint` triples. A
+consumer that parses a displayed IRI, or round-trips one back into a query, gets a wrong answer
+with no exception raised.
+
+### These fail loudly
+
+**Every class you register against must already exist in the ontology.** The middleware creates
+instances automatically but never mints classes. A domain-specific subclass of `svc:Service`,
+`svc:Workflow` or `svc:StateProperty`, and the `cfc:Capability` subclass a Workflow realizes, must
+all pre-exist. Startup fails immediately, naming the missing class.
+
+**All knowledge-graph writes go through the OGM.** Raw SPARQL `UPDATE` or direct
+`kapps_triplestore_interface` mutation calls bypass the validated write path, so the written node passes no
+shape check and a property replacement loses its atomicity — the intermediate state fails
+validation. Reads may use the access module directly; only writes are constrained.
+
+**`@mw.workflow` and `@mw.state` are resource-mode only.** Each raises `RuntimeError` when called
+on an instance in any other mode, and `ValueError` when a required class IRI is missing.
+
+### Structural facts
+
+**Build against `src/kapps_semantic_middleware/`. `examples/` and `demo/` are illustrations, not
+API.** They are teaching vehicles seeded against throwaway repositories, not production patterns to
+copy.
+
+**The demo imports as `kapps_semantic_middleware.demonstrations`, not `demo`.** The wheel remaps
+the `demo/` directory into the library namespace. `import demo.transferunits` works only in a
+development checkout.
+
+**There is one Service per middleware *instance*, not per Resource.** Several instances may wrap
+one Resource — a controller and a monitor, say — each owning its own Service node, address and
+heartbeat, all linked by `svc:isServiceOf`. Discovery may therefore return several Services for one
+Resource; select by address or by advertised capability rather than assuming exactly one.
+
+**Only `resource` and `watchdog` modes are implemented.** `server` is reserved and raises
+`NotImplementedError`. A graph-*consuming* participant — a planner, a controller, a mobile robot —
+is a resource-mode instance with its own Resource, not a server-mode one.
+
+**Docker is a prerequisite for running the examples, never for using the library.** The bundled
+`docker compose` file provides the GraphDB the scenarios and the factory need.

kapps_semantic_middleware/CONTEXT-MAP.md

@@ -0,0 +1,59 @@
+# Context Map
+
+## Contexts
+
+- [Core Middleware](./src/kapps_semantic_middleware/CONTEXT.md) — the middleware library itself.
+  It holds the Service/Workflow/Capability/Operation/Mode registration machinery and the
+  execution machinery.
+- [SHACL Interop](./src/kapps_semantic_middleware/shacl_interop/CONTEXT.md) — the temporary SHACL
+  seam for workflow precondition shapes and outcome shapes. It generates and parses them. It is
+  explicit scaffolding, will move to `kapps_ogm` (see its ADR 0001).
+- [Example Scenarios](./examples/CONTEXT.md) — self-contained demonstration notebooks, plus the
+  seed-data logic and the ontology-provisioning logic under them. That logic makes each notebook
+  reproducible against a dummy repository, and never against the production state.
+- [TransferUnit Factory](./demo/transferunits/CONTEXT.md) — the runnable multi-process demo. A
+  launcher seeds N units and starts one process per participant (ADR 0029). Its decisions live
+  with the Core Middleware ADRs, next to ADR 0029.
+- **Module Requirements** — requirements this project places on sibling KAPPS-family
+  modules (`kapps_ogm`, the not-yet-created visual-toolbox GUI). Not a code context, and its
+  documents are development-repository material that does not ship.
+
+## Relationships
+
+- **Core Middleware → SHACL Interop**: Core Middleware calls into SHACL Interop to read or write
+  a shape. The shape belongs to a Workflow class or a StateProperty class. The call happens when
+  `@mw.workflow` or `@mw.state` registers or resolves one. SHACL Interop has no dependency back
+  on Core Middleware. It operates on class IRIs and shapes, and not on types of the Core Middleware.
+- **Example Scenarios → Core Middleware**: Example Scenarios instantiate and exercise Core
+  Middleware end-to-end, against the ontology and the instance data they seed themselves. Core Middleware
+  has no dependency on Example Scenarios.
+- **TransferUnit Factory → Core Middleware**: the factory runs several instances of the library
+  in separate processes. That is one instance per unit, plus a controller. A monitor is
+  milestone 2 (ADR 0032) and is not built. Core Middleware has no dependency on the factory.
+- **Module Requirements** records obligations that Core Middleware and SHACL Interop place on
+  `kapps_ogm` and the visual-toolbox repo. It does not depend on the code contexts, and no code
+  context depends on it. It is a record for work that belongs elsewhere.
+
+## Ontology-module layering
+
+The vocabulary of the project is layered across three modules (Core Middleware ADR 0012):
+
+- **`cfc:` — Core** (`.../Core#`): published, external, superior — `Operation`/`Capability`/
+  `Resource`/`Task`. The system imports and specializes it. The system does not modify it.
+- **`mes:` — MES** (`.../MES#`, `src/kapps_semantic_middleware/ontology/mes.ttl`): a
+  **domain** ontology that imports Core and details it out — possession + handover ability.
+  What domain experts touch.
+- **`svc:` — Service** (`.../Service#`, `ontology/service.ttl`): middleware-to-middleware
+  **reachability and coordination only**, domain code does not touch it. It holds Service, Workflow and
+  StateProperty, the address, the endpoint and the heartbeat. It also holds the resolution chain,
+  and an Operation's status and provenance.
+
+`mes:` and `svc:` are siblings that both import Core. `mes:` is domain-facing, `svc:` is
+middleware-facing.
+
+## Where the decisions are written down
+
+The architecture decision records are development-repository material and are not part of
+this distribution. What they decided is described, without the deliberation, in
+[`docs/mechanics/`](docs/mechanics/); [`AGENTS.md`](AGENTS.md) indexes those pages.
+

kapps_semantic_middleware/CONTEXT.md

@@ -0,0 +1,349 @@
+# Core Middleware
+
+One of five contexts in this repo — see `/CONTEXT-MAP.md` at the repo root for the others
+(SHACL Interop, Example Scenarios, Module Requirements).
+
+> This file defines the **vocabulary**. For how to *use* the mechanisms it names — and for the
+> constraints that do not surface in a type signature — read `AGENTS.md` and the `docs/mechanics/`
+> set beside it. The `ADR 00nn` citations below are provenance markers for the development
+> repository; those records are not distributed, and `docs/mechanics/` is their shipped
+> replacement.
+
+The reference implementation of the KAPPS architecture's Semantic Middleware Runtime: the
+Interface-Layer component that lets a piece of Python code running on or next to a shopfloor
+resource (or as a standalone service) expose functionality through the knowledge graph, and
+lets other middleware instances discover and invoke that functionality via the graph rather
+than via hardcoded network references. This context owns the Service/Workflow/Capability/
+Operation/Mode registration and execution machinery. It delegates the actual generation and
+parsing of workflow precondition/outcome SHACL shapes to the SHACL Interop context.
+
+Built on `transitional_sync_middleware` (forked by inheritance, being incrementally reimplemented locally),
+`kapps_ogm` (all knowledge graph reads/writes), and `kapps_triplestore_interface` (raw triple store
+access, used directly where `kapps_ogm` has no equivalent yet, e.g. instance discovery).
+
+## Language
+
+**Service**:
+A distributed runtime entity wrapped by a single middleware instance (e.g. a door
+controller, a screwing-resource controller, a planning service). Typed via a
+domain-specific subclass of `svc:Service` that must pre-exist in the ontology.
+There is **one Service per middleware instance, not per Resource**: several instances may be bound to
+one Resource, each owning its own Service node, address and heartbeat, all linked by
+`svc:isServiceOf` (ADR 0022). Discovery may therefore return several Services for one Resource.
+_Avoid_: Middleware instance (that is the Python object; Service is its graph representation), Resource (Service *wraps* a Resource, it is not one); "the service of a resource" (there may be several).
+
+**Connector wiring** (of a resource-mode instance):
+A configuration of the one library, not a distinct class. Resource mode is a **library woven into a
+domain expert's Python package**, never a monolithic server. A wiring is two facts: a **protocol**
+and a **direction**. This is the only axis that describes an instance (ADR 0033).
+
+*Direction.* **Driving**: connectors wired bidirectionally, writes as well as reads. **Observing**:
+connectors wired `TO_PERSISTENCE`, reads live values, structurally unable to write. **Inspecting**:
+`autoregister_connectors=False`, nothing connected, structure and graph content only.
+
+*Protocol.* **MQTT** reaches a device, recognised on the parameter (`inf:hasMQTTTopic`). **REST**
+reaches another middleware instance over its ADR 0017 routes, recognised through the resource's
+Service (`svc:address`). A peer middleware is a device as far as the seam is concerned.
+
+Recognition and the **Projection** run identically in every combination, so connection metadata
+never reaches a **served datamodel** (ADR 0020, ADR 0032, ADR 0033).
+
+**The log path is held to the same claim** (issue #76, closed 2026-08-09). `activity.py` serves
+this package's INFO records over HTTP, which for a while made `/activity` a way around the
+projection: `connectors/mqtt_binding.py` logged each value with its topic at INFO. The topic now
+sits at DEBUG on both legs, and the feed's handler filters at its own level rather than the
+logger's — so widening the package logger to DEBUG for a debugging session still cannot put a
+topic on the page. The INFO line names the parameter and the value, which is what the feed is
+for.
+_Avoid_: Flavour, retired by ADR 0032. **Role**, retired by ADR 0033 — an instance has no property
+beyond its wiring. Consumer and Resource middleware as *defined* terms; they survive only as informal
+shorthand. Read-only mode, because a **Mode** is `resource`/`server`/`watchdog`, and a connector
+wiring is a configuration *within* resource mode. Monitor mode.
+
+**Transport**:
+The thing a connector dials, as opposed to the connector that dials it — an MQTT broker, and
+nothing else so far. A Parameter's connection metadata *names* a transport by address; it never
+provides one. A middleware may be asked to **ensure** a transport exists at a declared address
+before it registers the first connector aimed there, but it never holds a transport
+implementation: it states the need and the deployment meets it (ADR 0034). So a transport is the
+one part of the southbound path that is neither in the graph nor in this library.
+_Avoid_: Connector (the client this middleware constructs, one per topic — it *uses* a transport);
+Binding / Binding descriptor (the recognition rule that builds connectors, ADR 0023); Broker as a
+general term, since it is one transport and the seam is not MQTT-shaped; Endpoint and Address,
+which are northbound (`svc:address`, the ADR 0017 routes).
+
+**Workflow**:
+An invokable function exposed by a Service, registered with `@mw.workflow(...)`. Realizes
+exactly one Capability. Typed via a domain-specific subclass of `svc:Workflow` that must
+pre-exist in the ontology, carrying a SHACL shape describing its arguments (precondition)
+and return value (outcome) — see the SHACL Interop context for how that shape is read/
+written.
+_Avoid_: Skill, Action (AAS-tradition terms for the same invocation-interface idea; KAPPS
+reserves "Service" for the deployable middleware-wrapped entity and "Workflow" for what it
+exposes — see the paper's explicit divergence from the AAS capability-skill-service model).
+
+**Parameter** (interface-accessible parameter) — _supersedes StateProperty (ADR 0015)_:
+A readable and/or settable state of a Resource, modelled as **one graph node** carrying its
+value/unit **and** the metadata a protocol connector needs to reach the device (e.g. an MQTT
+topic + broker). It carries **no named `rdf:type`** — its only types are anonymous restriction nodes,
+which exist by inference and never survive an explicit-graph fetch — so it is recognised by the
+**Interface property** its domain property specializes, never by its class (ADR 0020).
+The middleware's former "readable state" and the shop-floor "parameter" are one thing seen from
+two directions — southbound (how the middleware reaches the device) and northbound (how peers
+reach the middleware). Whether it is externally settable is a **facet** (an access mode), not a
+subclass. Northbound it is **atomic**: value, unit
+and access mode are read and written together as one dict, because they share one blanknode — the
+locked circular-factory pattern for metadata about a property, RDF having no properties-about-
+properties (ADR 0017). Its **shape is the TBox restriction** on its property's `rdfs:range`, not the
+instance data: anything the restriction does not declare is dropped at materialization with only a
+warning, so metadata a connector needs must be declared there or it never arrives (ADR 0028).
+A complex property that matches no registered connector is **not** a Parameter — it is ordinary
+data the consumer asked for, displayed and readable, with nothing wired (ADR 0020).
+Whether its value lives in the graph is the domain's choice — see **Committed value** / **Locator**. It is
+also the deepest thing a binding can address: `ConnectionInfo` bottoms out at the Parameter, never at the
+value inside it (ADR 0023).
+_Avoid_: StateProperty (retired term, ADR 0015); Sensor value / Observation (those describe the
+data, not the graph node); Capability (states have none — there is no "light-barrier capability").
+
+**Interface class** — _retired term, do not use_:
+A protocol-specific parameter *class* (`inf:MQTTParameter`, `inf:OPCUAParameter`) that a connector was
+paired with one-to-one, resolved by the parameter's `rdf:type`. **The parameter node has no named
+type**, so nothing could ever match on it (ADR 0020, measured). The concept it reached for — the
+protocol-extensibility seam — survives intact as the **Interface property**, and the ontology terms it
+named are gone from the scenario-3 TBox. Use **Interface property**.
+_Avoid_: the term itself. Also Adapter, Driver.
+
+**ClassScope**:
+A **projection — a view** — over the graph, expressed (in the OGM) as a tree of property-chains
+rooted at a class. A view **belongs to its consumer** and is rooted at the node that consumer cares
+about. There is no single "the datamodel" for a resource. This is how one central ontology serves
+both the IT-OT boundary and the control/factory layer without duplicating concepts (ADR 0018).
+A view **terminates at a Parameter and cannot select within one**: below a complex property the
+chain is silently discarded, and the blanknode's contents are fixed by the TBox restriction, the
+same for every consumer (ADR 0028). A scope chooses *which* parameters, never *which parts* of one.
+An **empty** projection is legitimate — the graph holds the information, and a resource whose view
+is a bare individual serves a one-field datamodel and starts normally.
+_Avoid_: Filter, Query (a ClassScope is a reusable named view of which metadata to materialise).
+
+**Root** (of a view):
+The node a ClassScope is rooted at. Being a root is what makes a Resource a *top-level* thing rather
+than a component — TransferUnit1 is a unit and ConveyorBelt1_left is a part of it **because a view is
+rooted at the unit and reaches the belt**, not because of any part-of relation in the graph. There is
+no composition property in Core, and none is needed.
+_Avoid_: Top-level resource, Aggregate (both suggest an intrinsic property of the resource; rootedness
+is a property of the view).
+
+**User view**:
+The ClassScope a resource-mode middleware is constructed with, and the one it materializes into the
+datamodel it REST-exposes: the **northbound** projection. Stated by the domain code that embeds the
+library, since only that code knows what the instance is for. Omitting it falls back to an unscoped
+fetch, which materializes the `id` alone — a legitimate, if minimal, projection.
+Connection metadata is absent from it not because the view declines to fetch it (it cannot — see
+**ClassScope**) but because the **Projection** removes it (ADR 0028), so a peer cannot learn the
+broker address and bypass the middleware.
+_Avoid_: The datamodel, Schema (it is one view among many; a connector's view of the same resource is
+a different one).
+
+**Projection** (northbound):
+What keeps connection metadata out of the served datamodel: the middleware **removes the protocol
+properties from the ClassSpec before fetching**, and materializes the pruned spec (ADR 0028). What
+counts as protocol metadata is **read from the ontology**, per Parameter, at every startup: everything
+contributed by an **Interface property** strictly between the Parameter's own property and
+`inf:isInterfaceAccessibleParameter`. The Parameter's own range (value, unit) and the root's own range
+(`inf:accessMode`) stay. It runs for **every connector wiring**, including one that wires nothing — gating it
+would make the least-privileged instance the one that leaks.
+
+Deriving the set from the **registry** instead was tried and **fails open**: it knows only the
+protocols this middleware has code for, so a Parameter reachable over an unregistered protocol had its
+endpoint served (measured). A **Binding descriptor**'s connection metadata is now a *cross-check*
+against the ontology, not the source. A keep-list — naming what is safe — was rejected: it is a second
+closed-world moment (ADR 0025 allows exactly one) and it hides new domain content by default.
+_Avoid_: Deny-list *of field names* (the point is that the list is derived from the authoritative
+ontology, not enumerated); Access control (the Projection stops a peer *learning* the broker address
+from this REST surface, not someone who already knows it — that is future work).
+
+Earlier this was recorded as *not* a middleware step at all: a Parameter materializes to exactly what its
+property's restriction declares, so on the merge-depth reading a broker address physically could not
+reach a peer. That premise died when the `inf:` interface properties gained their own ranges (#53) —
+necessary so provisioning can write connection metadata through the OGM — because `PropertySpec` merges
+the entire `rdfs:subPropertyOf*` chain with no depth parameter. Measured: the unpruned belt materializes
+carrying topic, set topic and broker. Merge depth remains the right *description* of the two views; the
+middleware has to realize the shallow one itself (ADR 0019 stays retired as written; ADR 0026's
+projection claim is superseded).
+_Avoid_: Filter, Stripping *of data* (the prune is on the shape, before any data is read — the northbound
+model has no field to carry a broker address in); View (the view is the ClassScope, which selects *which*
+Parameters, not which parts of one).
+
+**Interface property**:
+The property a **Semantic connector** binds to — `inf:isInterfaceAccessibleMQTTParameter` and its
+siblings, under `inf:isInterfaceAccessibleParameter`. A resource's parameter declares its protocol by
+being a **subproperty** of one, which is how the authoritative upstream ontology already models it.
+Recognition is `rdfs:subPropertyOf*` against the registry. The parameter blanknode itself carries no
+named class to match on (ADR 0020).
+_Avoid_: Interface class (retained for the ontology concept, but the *match* is on the property).
+
+**Known primitives**:
+The bounded form of the system's flexibility: novel *combinations* are handled, novel *vocabulary* is
+not. A task assembled from grip/move/place may never have been seen in that combination, and a product
+may combine a screw and a gear never before combined — but grip, move, place, screw and gear are all
+known. Views and discovery listings are configured over known classes for this reason. It is a
+deliberate boundary, not a limitation to be engineered away.
+_Avoid_: Zero-configuration, Fully generic (both overclaim — the system does not discover concepts it
+has never been taught).
+
+**Semantic connector**:
+Any connector able to **register itself from the knowledge graph**. Every connector transitional_sync_middleware ships
+(MQTT, OPC-UA, HTTP, websocket, webhook, AAS client, model) is a candidate. Only the bare `Connector`
+protocol is not, being the interface specification itself. Realized as a **Binding descriptor**, not as a
+connector subclass (ADR 0023).
+_Avoid_: Connector (the bare transitional_sync_middleware protocol, without the metadata ontology); Adapter, Driver;
+MQTT connector as the archetype (MQTT is the first instance, not the shape of the concept).
+
+**Binding descriptor**:
+The object that makes a connector semantic: it names the **connector class** it builds, the **Interface
+property** it binds to, the connection-metadata properties its protocol needs — which are also exactly
+what the **Projection** hides northbound — and how to turn one Parameter's metadata into one or more
+framework registrations. It references its connector class rather than subclassing it, so a connector
+nobody here owns can still be made semantic. One binding may yield **two** connectors (a read topic and a
+write topic) against **one** binding target, differing only in direction. Built and registered **at
+construction**, from the ClassSpec and the graph — registering later means the framework never connects
+them and inbound traffic dies silently (ADR 0023).
+_Avoid_: Connector factory, Plugin (the descriptor is declarative — it states what a protocol needs, and
+building is one method on it).
+
+**Static facet**:
+A part of a Parameter that does not change with a reading — unit, access mode. Captured by the **Binding
+descriptor** at wiring time and reassembled into the payload on every inbound message, because
+`setattr` replaces the whole Parameter node and `Formatter.deserialize` sees only the payload, with no
+access to the current value. Free to carry, since `OGM.commit` filters unchanged triples (ADR 0018,
+ADR 0023).
+
+ADR 0027 retired the *graph* reason for this — a skolemised Parameter node is addressable, so a commit
+diffs per triple and an unchanged facet cannot be wiped. The **in-memory** reason stands and is why the
+reassembly remains: without it, a bare inbound scalar blanks the unit in the very model that is served
+over REST.
+_Avoid_: Constant, Config (a facet belongs to the Parameter and is authored in the ontology, not to the
+deployment).
+
+**Connector registry**:
+The universal map from **Interface property** to **Binding descriptor**. Built at middleware
+initialization from the known, tested descriptors shipped in the middleware, and extensible after init by
+injecting a domain-built one. Resolution is
+`parameter property rdfs:subPropertyOf* → interface property → binding descriptor`. Supporting a new
+protocol is registering a new entry, never a core change. Recognition runs over the **ClassSpec and the
+graph**, not over materialized instance data, which is what allows registration to happen early enough
+for the framework to connect them (ADR 0020, ADR 0023).
+_Avoid_: Connector factory, Plugin loader (the registry keys specifically on the interface property);
+keying on `rdf:type` (superseded — the parameter blanknode has no named type).
+
+**Committed value** / **Locator**:
+The two legitimate ways a domain may treat a Parameter's value, chosen per subproject — the middleware is
+agnostic and enforces neither. **Committed value**: the data point changes slowly, so the domain code
+commits it and the graph holds the value. `@state` is not involved. **Locator**: the data point changes
+fast, so the graph holds only *where the value lives* — unit, access mode, topic, broker — and never the
+value itself, which exists only in the datamodel and over REST. Scenario 3 is a locator, which is why its
+instance data carries no `inf:hasValue` literals. The restriction still declares the field, so an
+unobserved Parameter reads as `[]` (ADR 0024).
+_Avoid_: Cached value, Stale value (a committed value is authoritative for its update rate, not a stale
+copy); "the live value is never persisted" as a middleware rule (it is the locator pattern's property).
+
+**Capability**:
+Defined in Core (`cfc:Capability`, subclasses `EquippedCapability`/`FlexibilityCapability`/
+`ChangeabilityCapability`). An ability a Resource currently has. In this project's usage,
+every Capability instance is created automatically by the middleware from a pre-existing
+Capability *type* the moment a matching Workflow or StateProperty is registered — it is
+never instantiated by hand.
+_Avoid_: Skill (AAS term for a related but not identical concept).
+
+**Operation**:
+Defined in Core (`cfc:Operation`, subclass of `Task`). The executable, resource-assigned
+form of a task; links to a Capability via `cfc:implementsCapability`. A caller creates an
+Operation in the graph and dispatches it to the resource that will carry it out. That
+resource queues it, pulls it, runs it, and the outcome is recorded back onto it. The
+graph-level unit of work exchanged between middleware instances.
+_Avoid_: Workflow invocation, Job (Operation is the graph-level unit of work; a single
+Operation resolves to exactly one Workflow via its Capability).
+
+**Event trigger** (`execute()`):
+The receiver-side built-in Workflow that every resource-mode middleware exposes on its REST
+API. A caller "triggers" it to signal that an Operation addressed to that resource now exists in
+the graph. The receiver enqueues the Operation, `ogm.fetch`es it, and hands it to an optional
+domain callback (else leaves it `queued`). The trigger carries only the Operation IRI — the
+payload lives in the graph — and does not block on the work or return a business result.
+_Avoid_: RPC call, Invoke (the event trigger notifies; it does not run the work synchronously).
+
+**Dispatch**:
+The caller-side act of handing an Operation to another resource: create the Operation
+individual in the graph (through the OGM-routed write path) and then fire the receiver's
+event trigger. Accessed from domain Python as a transaction context manager — the body populates
+the Operation, the atomic exit performs the create-and-notify.
+_Avoid_: Send, Publish (there is no message bus; dispatch is a graph write plus an event trigger).
+
+**Operation queue**:
+A resource-mode middleware's pending-work list — the Operations addressed to its Resource
+that await or are in progress. Held in memory as a cache and reconstructed at startup by
+querying the graph (own `queued` operations, plus own orphaned `running` operations to
+reclaim); filled live by event triggers. A dead resource's stranded operations are swept
+centrally by a watchdog, not by per-resource polling.
+_Avoid_: Message queue, Broker (there is no broker; the queue is a view over graph state).
+
+**Operation status**:
+The lifecycle state of an Operation: `queued` (created and addressed, awaiting pull) →
+`running` (pulled, in progress) → `done` or `failed` (terminal). Drives coordination and
+recovery. Execution provenance (which Workflow ran it, when, the result) is written as part
+of the terminal transition, so the status is itself the provenance record — there is no
+separate success flag.
+
+**Pull-and-run**:
+The receiver-side transaction context manager by which domain code takes the next `queued`
+Operation, sets it `running` (re-fetching it under a domain-supplied `ClassScope`), runs the
+work in the body, and on atomic exit records the terminal `done`/`failed` state and
+provenance — dumping the Resource's datamodel to the graph on failure.
+_Avoid_: Poll, Consume (pull-and-run is the guarded unit of work, not the delivery mechanism).
+
+**Resource**:
+Defined in Core (`cfc:Resource`). The physical or logical thing a Service wraps (a door, a
+transformer cell, a screwing tool). Required at construction time in resource mode.
+
+**Mode**:
+A `SemanticMiddleware` construction-time choice governing what the instance is *for*:
+- `"resource"` — wraps one Resource; the REST surface is the user-registered Workflows/
+  StateProperties, the built-in `execute()` event trigger, and a CRUD REST API generated from
+  the resource's own datamodel (`generate_rest_api_for_data_model`; ADR 0005 #13 amendment). The
+  transactional context-manager surface (dispatch/`request`, pull-and-run, handover) and the
+  graph-write helpers stay Python-only, not REST-exposed.
+- `"server"` — wraps no Resource. CRUD/`execute` themselves are the REST surface (e.g. a
+  future data-serving "product server"). Not yet implemented, and deliberately still reserved: a
+  graph-*consuming* participant (a planner, a mobile robot, a controller) is a resource-mode
+  planner with its own Resource, not a server (ADR 0005, #32 amendment).
+- `"watchdog"` — wraps no Resource, exposes little to no REST surface; runs a sweep loop
+  that removes stale `svc:address`/`svc:endpoint` triples left by resource-mode instances
+  that stopped heartbeating.
+_Avoid_: Deployment type, Role (Mode is specifically the constructor discriminator).
+
+**Heartbeat**:
+A resource-mode Service's periodic re-assertion of its own liveness — refreshing
+`svc:lastHeartbeat` on its Service individual via an internal interval-based Workflow. Read
+by watchdog-mode instances to decide staleness.
+
+**Address vs. Endpoint**:
+`svc:address` is a Service's base URL, set on startup and removed on
+deregistration/staleness. `svc:endpoint` is the full, directly callable URL for one specific
+Workflow or StateProperty, also set on startup and removed on deregistration/staleness. Both
+being present is a deliberate divergence from the paper's literal "address on Service only"
+wording — see the "Address and endpoint" section of
+`docs/mechanics/02-workflow-registration.md`.
+_Avoid_: URL, endpoint URL used interchangeably for both — they are distinct properties on
+distinct entity types.
+
+**KnowledgeGraphConnector**:
+An `transitional_sync_middleware`-protocol `Connector` (`connect`/`disconnect`/`provide`/`consume`) whose
+`provide`/`consume` wrap `kapps_ogm.OGM.fetch`/`commit`. The mechanism by which any
+`transitional_sync_middleware` construct (workflows, synced connectors) can read/write the knowledge graph
+without going around the OGM's validated write path. See "The graph-facing connector"
+in `docs/mechanics/04-connector-binding.md`.
+
+**Deregistration**:
+The reverse of registration: on shutdown (or, for watchdog-mode-detected staleness), removing
+a Service's `svc:address` and its Workflows'/StateProperties' `svc:endpoint` triples while
+preserving the individuals themselves, for provenance.

kapps_semantic_middleware/__init__.py

@@ -0,0 +1,38 @@
+# Re-export full transitional_sync_middleware public API.
+# As each layer is migrated locally, swap the import below to point at the
+# local implementation instead of transitional_sync_middleware.
+from transitional_sync_middleware import (
+    Middleware,
+    AasMiddleware,
+    Reference,
+    Identifier,
+    DataModel,
+    DataModelRebuilder,
+    AAS,
+    Submodel,
+    SubmodelElementCollection,
+    Blob,
+    File,
+    formatting,
+    connectors,
+)
+from kapps_semantic_middleware.middleware import SemanticMiddleware
+from kapps_semantic_middleware.modes import Mode
+
+__all__ = [
+    "SemanticMiddleware",
+    "Mode",
+    "Middleware",
+    "AasMiddleware",
+    "Reference",
+    "Identifier",
+    "DataModel",
+    "DataModelRebuilder",
+    "AAS",
+    "Submodel",
+    "SubmodelElementCollection",
+    "Blob",
+    "File",
+    "formatting",
+    "connectors",
+]