// CELL-OPEN — what `std/cell:open` rewrites to. Minting `*Cell<cell!>` through
// the `| cell` arm transfers the obligation into the caller's custody; only
// `hibernate` settles it.
~pub tor cell-open {
    shape: string,
    shape_def: string,
    id: string,
    scope: string,
    world: string
}
| cell *Cell<cell!>
| ?refused

// STATE — the shape's fields as a checked surface. `get`/`set` validate the
// field name against the baked manifest (`unknown-field` names the shape, not
// a shrug), and `set` coerces the value through the declared field type
// (`type-mismatch` names what the field wanted). This is the sketch — state
// is in-memory; hibernate loses it until a materializer lands.
~pub tor get { c: *Cell<cell>, field: string }
| value { kind: string, int: i64, float: f64, text: string, flag: bool }
| unknown-field { field: string, shape: string }
| unset string

~pub tor set { c: *Cell<cell>, field: string, value: string }
| set
| unknown-field { field: string, shape: string }
| type-mismatch { field: string, expected: string }

~pub tor fields { c: *Cell<cell> } -> string

// HIBERNATE — the standalone custodian's discharge: hang the session up and
// release the cell. For node-resident cells this is `std/node:evict`'s job —
// hibernating a cell is always the custodian's call, never the borrower's.
~pub tor hibernate { c: *Cell<!cell> }

~[keyword|comptime|transform|pre] pub tor capture {
    expr: Expression,
    shape: Expression,
    invocation: *const Invocation,
    item: std/compiler:*const Item,
    program: std/compiler:*const Program,
    reporter: std/compiler:*ErrorReporter,
    allocator: std.mem.Allocator
}
! as *
| ?captured *

// CELL.OPEN — `std/cell:open(room_state, id: "assistant")`: resolve the shape
// name against the program's protos and rewrite to `cell-open`. [pre] so the
// proto decl sites are still legible when we scan.
~[keyword|comptime|transform|pre] pub tor open {
    expr: Expression,
    invocation: *const Invocation,
    item: std/compiler:*const Item,
    program: std/compiler:*const Program,
    reporter: std/compiler:*ErrorReporter,
    allocator: std.mem.Allocator
} -> SiteResult

// RUN — dispatch a source turn into the cell's session over `std/bridge:run`,
// re-tiered to two required arms: `| result` when the turn completes, and a
// single `| error` carrying every failure class — the lossless union in
// RunError, `kind` naming the variant. The turn-completed findings
// (`defined`/`unhandled-branch`/`residue`/`partial`) stay armable as
// optionals; a caller who distinguishes failure classes sends `e` through
// `error-decode` instead of spelling nine arms at every call.
~pub tor run { c: *Cell<cell>, source: string<*> }
| result {
    value: @import("root").koru_std.koru_interpreter.Value,
    used: u64,
    handles: u32,
    bound: string,
    trace: string
}
| error RunError
| ?defined string
| ?unhandled-branch {
    branch: string,
    payload: string,
    handles: string,
    bound: string
}
| ?residue { report: string, observer: bool, bound: string, text: string }
| ?partial {
    ran: u32,
    total: u32,
    used: u64,
    handles: u32,
    report: string,
    wire_failures: u32
}

// ERROR-DECODE — the fine-grained arm set for callers that distinguish
// failure classes. `e` is the RunError a `run`'s `| error` arm bound; each
// optional arm fires for exactly one `kind`, carrying that variant's typed
// payload. A `kind` outside the known set routes to `unknown-error`; nothing
// here is required — the caller already answered the error once.
~pub tor error-decode { e: RunError }
| ?exhausted { used: u64, last_event: string, handles: u32 }
| ?parse-error { message: string, line: u32, column: u32 }
| ?validation-error string
| ?shape-error { branch: string, field: ?string, message: string }
| ?event-denied string
| ?dispatch-error { event_name: string, message: string, trace: string }
| ?scope-not-found string
| ?unknown-error { kind: string, message: string }