Skip to content

Commit e16f214

Browse files
committed
docs: unified verb facade (council-hardened, compressed)
Six verbs (define/query/relate/act/subscribe/authorize) as step_type names on the existing OrchestrationBridge/UnifiedStep — not a new layer, not "on the emitter". SurrealDB's matching verbs are a borrowed silhouette; the engine is the compiled ClassView (#137). 5+3 council ran (8/8 → REVISE, land the safe subset). Folded findings: - only `define` truly converges (schema-in/schema-out); the other five borrow the name over OGAR's own EdgeBlock/ActionDef/scheduler/RBAC — egress only (OGAR → SurrealQL), never DDL → behavior. - `authorize` split into filter (query-plane) + admit (command-plane); must not fuse (AR-OGAR §11 item 11). - fixed two phantom cells the runtime-archaeologist caught: `CommitGate` (→ CommitHook) and `Authorization{enforcement_phase}` (→ ClassRbac/OgarRbac). - `authorize.*` + lifecycle-`act` reserved-dormant, gated on Phase-B items 11/9. - dropped "two spines"; one live spine (compiled ClassView), SurrealQL egress rides lite-unified (#540, default-OFF). CONJECTURE until F1/F3 pass. Renamed from the pre-council UNIFIED-EMITTER-API-v1.md ("Emitter" invited reading the facade as the spine). Registers ADR-026; cross-link pending. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 6d34bcb commit e16f214

1 file changed

Lines changed: 65 additions & 0 deletions

File tree

docs/UNIFIED-VERB-FACADE-v1.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
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

Comments
 (0)