docs(do-arm): HIRO Automation is OGAR's DO arm + the lossless-DO rule

.claude/board/EPIPHANIES.md

@@ -7,6 +7,48 @@
 
 ---
 
+## 2026-06-23 — E-HIRO-IS-OGAR-DO-ARM — HIRO's Automation domain is a production, externally-validated instance of OGAR's DO arm; the lossless rule is identity-points-to-body
+
+**Status:** FINDING (shape, grounded `[G]`) + CONJECTURE (executable equivalence,
+`[H]`, gated on `PROBE-OGAR-DO-ARM-LIFT`). Investigating "can we lift actionable
+semantics from OGIT/MARS (HIRO)" — read the OGIT `NTO/Automation/entities/*` TTLs
+directly. The Automation domain is HIRO's actuator vocabulary and maps near-1:1
+onto OGAR's DO arm (`ActionDef` / `ActionInvocation` / `KausalSpec`):
+
+- `KnowledgeItem` = `ActionDef` (relations carry the contract; `uses Variable` =
+  params; `contains Trigger` = `KausalSpec::LifecycleTrigger`; `relates
+  MARSNodeTemplate` = `object_class`) — **and `knowledgeItemFormalRepresentation`
+  is an opaque body the schema references but never parses.**
+- `ActionHandler → ActionCapability → ActionApplicability` = `ActionDef` + the
+  `KausalSpec` guard (`environmentFilter` = "on `ogit/_id`"); `ActionHandler`
+  connects `Configuration` (= `auth_store` `0x0B01`) — **the DO arm and the
+  auth/RBAC arm meet at `ActionHandler`.**
+- `AutomationIssue` = `ActionInvocation`; `AutomationIssue generates History` is
+  literally OGAR-AST-CONTRACT's "state history IS the version log."
+
+**The lossless rule (the important answer):** a DO compiler is lossy when it
+flattens behavior into one target (DDL `DEFINE EVENT … WHEN … THEN`). Behavior
+has three irreducible slices — **identity** (Class), **contract+lifecycle**
+(ActionDef + the StateMachine/UnifiedStep interface), **executable body**
+(adapter) — joined by `classid`. **DO is lossless iff the `ActionDef` *points
+to* the body (content-addressed) instead of *compressing it into* DDL** — this is
+`I-VSA-IDENTITIES` applied to the DO arm. Export shape = ActionDef manifest
+(typed SoA, wire-truth per the Firewall) + payload table (opaque blobs) +
+ClassView, never DDL-inline. HIRO already IS this shape — it validates the
+encoding, it doesn't need inventing.
+
+**Consequence:** the MARS import lifted the structural arm (A→R→S→M); the
+Automation domain is the behavioral arm left on the table. A `do_arm` lift
+(extend `ogar-from-schema`) can emit `ActionDef{…, payload_ref}` from the
+Automation TTLs — but stays CONJECTURE until `PROBE-OGAR-DO-ARM-LIFT` proves
+`ActionDef → adapter → execute → result` reproduces the KI's behavior on a fixed
+corpus (same discipline as `PROBE-OGAR-RBAC-AUTHORIZE`). Full mapping +
+worked `KnowledgeItem→ActionDef` example + the producer plan:
+`docs/HIRO-DO-ARM-LIFT.md`. Cross-ref: `SURREAL-AST-AS-ADAPTER.md §0`,
+Core-First doctrine, the Firewall (ADR-022/023), `OGAR-AST-CONTRACT.md`.
+
+---
+
 ## 2026-06-23 — E-NINE-DOMAIN-PROMOTION-DEFERRED — the nine Lift-tested NTO domains correctly stay un-Cross-walked; bulk-minting class_ids is the WRONG move, per the catalogue's own rules
 
 **Status:** FINDING (promotion decision, 2026-06-23). Question raised: promote the

docs/HIRO-DO-ARM-LIFT.md

@@ -0,0 +1,156 @@
+# HIRO → OGAR DO-arm lift — lossless actionable semantics from the Automation domain
+
+> **Status:** FINDING (mapping + principle, grounded) + CONJECTURE (the producer).
+> **Preflight:** authored under `docs/SURREAL-AST-TRAP-PREFLIGHT.md` — behavior
+> flows **producer → OGAR `Class`+`ActionDef` → adapter**, never producer → DDL.
+> **Reads:** OGIT `NTO/Automation/entities/*` (KnowledgeItem · ActionHandler ·
+> ActionCapability · ActionApplicability · Trigger · Intent · AutomationIssue ·
+> History · Variable), `docs/OGAR-AST-CONTRACT.md` (the DO-arm types).
+
+The MARS import lifted the **structural** arm (A→R→S→M `Class`es). The
+**Automation** domain — HIRO's actuator vocabulary — is the **behavioral** arm
+the structural import left on the table. This doc maps it into OGAR's DO arm and
+pins the one rule that keeps the lift **lossless**.
+
+---
+
+## 1. The lossless-DO principle (the governing rule)
+
+A DO compiler is **lossy** when it tries to express behavior in **one flat
+target** (a DDL `DEFINE EVENT … WHEN … THEN …`, a single schema row). Behavior
+has **three irreducible slices**, and any single format holds at most one or two:
+
+| Slice | Home (lossless) | Carries |
+|---|---|---|
+| **Identity + structure** — *what* is acted on | `Class` / `ClassView` (THINK arm) | the **address** |
+| **Contract + lifecycle** — *how* it's invoked | `ActionDef` IR + the trait (`StateMachine` / `UnifiedStep`) | the typed **control** (predicate · object_class · `KausalSpec` · `results_in` · `on_enter` · `guard_failure_policy` · `state_timeout_millis` · idempotency) |
+| **Executable body** — the *actual* command | the **adapter** binding | the **behavior**, verbatim |
+
+> **The rule: DO is lossless iff the `ActionDef` *points to* the body
+> (content-addressed) instead of *compressing it into* DDL.** This is
+> `I-VSA-IDENTITIES` applied to the DO arm — an identity that points to content,
+> never a bundle of the content's register. The `classid` is the join key across
+> all three slices; nothing is projected away because each slice has a home that
+> holds it exactly.
+
+It is **not** "interfaces *vs* adapters *vs* classes" — it is **all three**. The
+lossiness is precisely what happens when one of them is forced to carry all three
+(the DDL flatten: keeps "when X then Y", drops the lifecycle / guard-failure
+modality / SLA / the `ActionDef`(static) ÷ `ActionInvocation`(dynamic) split —
+the "negative-beauty hijack" `SURREAL-AST-AS-ADAPTER.md §0` rejects).
+
+---
+
+## 2. Export shape — what NOT-lossy looks like on the wire
+
+Not a DDL. Export **three artifacts joined by `classid`**:
+
+1. **ActionDef manifest** — a typed SoA record (the contract). **Wire-truth** per
+   the Firewall (ADR-022/023): the IR *is* the wire, no re-serialization.
+2. **Payload table** — the body as an **opaque, content-addressed blob**
+   (`hash → bytes`), resolved by the adapter at invocation. The IR holds the
+   *pointer* (classid/hash), never the bytes.
+3. **ClassView** — identity (the join key).
+
+The adapter is *where behavior executes* (Core-First: it **assumes** the Core via
+`classid`, never carries its own state); the interface (`StateMachine` /
+`UnifiedStep`) is *how it's invoked*; the class is *what it's addressed by*.
+Round-trip is lossless: the body is preserved verbatim, the contract as typed IR.
+
+---
+
+## 3. HIRO is already this shape (the external proof) — `[G]`
+
+arago's Automation graph is a production, lossless DO encoding. Read directly:
+
+- **`KnowledgeItem`** carries the contract as relations + lifecycle attrs
+  (`uses Variable`, `contains Trigger`, `worksOn AutomationIssue`,
+  `relates MARSNodeTemplate`, `solves Task`, `generates Timeseries`,
+  `deployToEngine` / `deployStatus`) **and the body rides as
+  `knowledgeItemFormalRepresentation` — an opaque blob the schema references but
+  never parses.** That is the identity-points-to-body split, verbatim.
+- **`AutomationIssue generates History`** is literally OGAR-AST-CONTRACT's
+  "state history IS the version log."
+- **`ActionHandler` connects `Configuration` + `ActionCapability` +
+  `ActionApplicability`** — and `Configuration` ⊨ `auth_store` (`0x0B01`, the
+  family we minted). The **DO arm and the auth/RBAC arm meet at `ActionHandler`.**
+
+We do not invent the shape; we adopt the one arago validated at scale.
+
+---
+
+## 4. Mapping — OGIT Automation → OGAR DO arm
+
+| OGIT `Automation` entity | OGAR DO-arm target | Evidence (the actionable fields) |
+|---|---|---|
+| `KnowledgeItem` | **`ActionDef`** | `knowledgeItemFormalRepresentation` = opaque body (→ payload table); `uses Variable` = params/defaults; `relates MARSNodeTemplate` = `object_class`; `solves Task` / `generates Timeseries` = `results_in` |
+| `ActionCapability` | `ActionDef` params + **adapter binding** | `mandatoryParameters`; "remote execution via ssh" = the executor the adapter wires |
+| `ActionApplicability` | **`KausalSpec::StateGuard`** | `environmentFilter`; "on `ogit/_id`" = the guard predicate (WHEN the action applies) |
+| `ActionHandler` | the **adapter** (+ membrane) | connects `Configuration` (= `auth_store` `0x0B01`) + `Capability` + `Applicability` |
+| `Trigger` | **`KausalSpec::LifecycleTrigger`** | "Trigger of a KI having a set of Subitems" |
+| `Intent` | **`ActionDef.results_in`** / desiredState | "The Intent of a KI processing chain" |
+| `AutomationIssue` | **`ActionInvocation`** | situational data (Key/Value tuples); `worksOn MARSNode` = `object_instance`; `generates History` |
+| `History` | `ActionInvocation` **state log** | = the Lance version log ("state history IS the version log") |
+| `Variable` | `ActionDef` params / `defaults` | `uses Variable` |
+| `MARSNode` / `MARSNodeTemplate` | `object_class` / `object_instance` | the THINK arm — **already imported** structurally |
+| `Configuration` | `auth_store` (`0x0B01`) | already minted; the membrane the handler authorizes through |
+
+---
+
+## 5. Worked example — `KnowledgeItem` → `ActionDef`
+
+```text
+ogit.Automation:KnowledgeItem "restart-stuck-service"
+  knowledgeItemFormalRepresentation = <XML body / script>        ─┐  opaque
+  uses        ogit.Automation:Variable (serviceName, host)        │  payload
+  contains    ogit.Automation:Trigger (onIssueType=ServiceDown)   │  (content-
+  relates     ogit.Automation:MARSNodeTemplate (Software/Service) │   addressed,
+  worksOn     ogit.Automation:AutomationIssue                     │   never
+  generates   ogit:Timeseries (restart latency)                  ─┘   parsed)
+        │  lift (shape only — body stays a blob)
+        ▼
+ActionDef {
+  predicate:            "restart-stuck-service",
+  object_class:         Identity(Software/Service),        // ← relates MARSNodeTemplate
+  kausal:               LifecycleTrigger { on: ServiceDown }, // ← contains Trigger
+  defaults:             [serviceName, host],               // ← uses Variable
+  results_in:           Some(StateTransition::to(Restarted)), // ← Intent / generates
+  guard_failure_policy: Postponable,                       // ← env: transient → retry
+  payload_ref:          blake3(formalRepresentation),      // ← POINTER, not the bytes
+}
+// the <XML body> lives in the payload table @ blake3(...), executed by the adapter.
+```
+
+Lossless check: every lifecycle/guard/param field is a typed `ActionDef` field;
+the executable body is preserved verbatim behind a content hash. A DDL emit of
+this would keep "on ServiceDown, run X" and **lose** `guard_failure_policy`,
+`results_in` typing, and the `ActionDef`÷`ActionInvocation` split.
+
+---
+
+## 6. The producer (proposed) — `[H]`, gated on a probe
+
+Parallel to `ogar-from-schema` (structural arm), an Automation-domain DO lift
+(extend `ogar-from-schema` with a `do_arm` module, reusing its TTL parser):
+
+```text
+Automation/entities/*.ttl  →  ActionDef{ predicate, object_class, kausal,
+                                          defaults, results_in, payload_ref }
+                              + payload table (formalRepresentation blobs)
+```
+
+- **`payload_ref` only** — the lift NEVER inlines or reparses
+  `knowledgeItemFormalRepresentation`; it hashes it into the payload table.
+- **CONJECTURE until `PROBE-OGAR-DO-ARM-LIFT` is green:** an `ActionDef` →
+  adapter → execute → result must reproduce the KI's recorded behavior
+  bit-for-bit on a fixed corpus (the same falsification discipline as
+  `PROBE-OGAR-RBAC-AUTHORIZE`). Until then the mapping in §4 is a FINDING about
+  *shape*, not a certified executable equivalence.
+
+---
+
+## 7. One-line rule
+
+> **DO is lossless iff the `ActionDef` points to the body, never flattens it into
+> DDL.** Identity → content; three slices (class · interface · adapter) joined by
+> `classid`; export the typed manifest + the opaque payload, never the DDL.