|
| 1 | +# Unified Verb Facade — one small set of verbs over the ClassView |
| 2 | + |
| 3 | +> **Status:** council-hardened v1 (5+3 ran 2026-07-01, 8/8 → REVISE, land the |
| 4 | +> safe subset). Renamed from `UNIFIED-EMITTER-API-v1.md`. |
| 5 | +> **Under:** #546, #137 ("the spine is the compiled ClassView, not SurrealQL"), |
| 6 | +> `SURREAL-AST-AS-ADAPTER.md`. |
| 7 | +
|
| 8 | +## The idea, plainly |
| 9 | + |
| 10 | +Give consumers **six verbs** — `define · query · relate · act · subscribe · |
| 11 | +authorize` — as `step_type` names on the **existing** `OrchestrationBridge` / |
| 12 | +`UnifiedStep`. Nothing new underneath. These are just the natural things you do |
| 13 | +to a ClassView node. |
| 14 | + |
| 15 | +SurrealDB happens to have the same-looking verbs (`DEFINE`, `SELECT`, `RELATE`, |
| 16 | +`LIVE`, …). That's a **familiar shape we borrow, not the engine.** The engine is |
| 17 | +the compiled ClassView. Think "same silhouette, different body." |
| 18 | + |
| 19 | +## The one honest rule the council found |
| 20 | + |
| 21 | +Only **`define` really matches** SurrealDB (schema in → schema out, no runtime). |
| 22 | +The other five just **borrow the name** — underneath they're OGAR's own things |
| 23 | +(EdgeBlock, ActionDef, the scheduler, RBAC). So: |
| 24 | + |
| 25 | +- Direction is always **OGAR → SurrealQL (out)**, never SurrealQL → behavior (in). |
| 26 | +- **`authorize` is two verbs, never one**: `authorize.filter` (who can *see*) and |
| 27 | + `authorize.admit` (who can *do*). Merging them is a bug. |
| 28 | +- Ship only what's built: `define`, `query`, `relate`, `subscribe`, and basic |
| 29 | + `act`. Leave `authorize.*` and lifecycle-`act` as **reserved names** until the |
| 30 | + Core pieces (`Authorization`, `StateMachineDecl`) land. |
| 31 | + |
| 32 | +## What's actually built vs. borrowed |
| 33 | + |
| 34 | +| Verb | Built? | |
| 35 | +|---|---| |
| 36 | +| `define` | **yes** — `OgarClassView` (ClassView × FieldMask), tested | |
| 37 | +| `query` | mostly — `Backend::MailboxSoa` scans work; no Cypher entry point yet | |
| 38 | +| `relate` | partly — `EdgeBlock` struct decodes; write/traverse not done | |
| 39 | +| `act` | data yes (`ActionDef`), runtime later (via `CommitHook`, not "CommitGate" — that name doesn't exist) | |
| 40 | +| `subscribe` | trait yes (`VersionScheduler`), live binding later | |
| 41 | +| `authorize` | RBAC exists (`ClassRbac`/`OgarRbac`), but the two-plane split is not built | |
| 42 | + |
| 43 | +## First step (safe now) |
| 44 | + |
| 45 | +A `step_type` name list + a `UnifiedStep` builder. **No new code that runs**, no |
| 46 | +SurrealQL, no OSINT state machine yet. It's a **proposal, not proven**, until the |
| 47 | +parity tests (F1/F3 below) pass. |
| 48 | + |
| 49 | +Tests to pass later: **F1** a `query` step returns the same nodes as the raw scan; |
| 50 | +**F2** filter-rules never hit the admit-gate and vice-versa; **F3** with SurrealQL |
| 51 | +off, behaviour is identical; **F4** no new type beyond a builder; **F5** every verb |
| 52 | +names a real symbol in code (fixed the two fake ones this pass). |
| 53 | + |
| 54 | +## Council (5+3), one line each |
| 55 | + |
| 56 | +- **convergence** — only `define` truly converges; the rest just share a name. |
| 57 | +- **core-first** — the ClassView is the authority, not SurrealDB; drop "two spines". |
| 58 | +- **integration-lead** — 4 verbs are safe today; reserve `authorize`/lifecycle-`act`. |
| 59 | +- **cross-domain** — an API over a running DB ≠ an API over emitted code; home is the bridge. |
| 60 | +- **runtime-archaeologist** — `CommitGate` and `Authorization{enforcement_phase}` don't exist yet; point at the real types. |
| 61 | +- **overclaim** — don't call unbuilt things "shipped"; one backend is live, not two. |
| 62 | +- **doctrine** — split `authorize`; `act` is egress-only; rename off "SurrealQL-shaped"; add ADR-026. |
| 63 | +- **dilution/collapse** — keep it "silhouette, not spine"; split `authorize` in the table itself. |
| 64 | + |
| 65 | +**Verdict: revise, land the safe subset, keep the big claim as a proposal until tested.** |
0 commit comments