@vibecook/ice 0.4.0 → 0.7.0

package/dist/types/packages/core/src/behavior/types.d.ts

@@ -0,0 +1,358 @@
+/**
+ * `defineBehavior` — the type surface (design-009 §3–§4, the pinned API).
+ *
+ * ICE's userland surface is a triad: `defineWidget` (faces) · **behaviors**
+ * (logic + state) · `defineTool` (input policy). A behavior is the A-Frame-class
+ * unit — ONE named declaration carrying a data schema, a REQUIRED store class,
+ * and lifecycle hooks the engine runs on a curated phase set.
+ *
+ * `store:` is the load-bearing word: it routes where data lives, who sees it,
+ * what survives, WHICH WRITE VOCABULARY the hooks receive, at which cadence.
+ * That last routing is the reason the ctx types below are three interfaces and
+ * not one with optional members — a durable behavior must not see `ctx.write`
+ * in autocomplete at all, or "store routes everything" is a doc claim rather
+ * than a property of the product.
+ */
+import type { Component, Entity, Relation, Resource, Tag } from "@vibecook/strata-ecs";
+import type { GuardedTx } from "../guards/guarded-tx";
+import type { BooleanSpec, EntityKeySpec, EnumSpec, JsonShape, JsonSpec, NumberSpec, PropSpec, StringSpec } from "../widget/props";
+export type BehaviorStore = "durable" | "runtime" | "ephemeral";
+/**
+ * The CURATED phase set (design-009 §4.4, BF-D8) — a deliberate subset of the
+ * eleven pipeline groups. Authors get the four that mean something to logic;
+ * the control sweep (`ctl:*`), `input`, `react` and `cleanup` stay engine
+ * vocabulary. `publish` is not a pipeline group at all — it is the post-tick
+ * slot where ephemeral mutation is legal.
+ */
+export type BehaviorPhase = "simulate" | "derive" | "present" | "publish";
+/** Legal `phase` per store class — the §4.1 validation table, as data. */
+export declare const BEHAVIOR_PHASES: Readonly<Record<BehaviorStore, readonly BehaviorPhase[]>>;
+/** Default phase per store (the one most declarations want). */
+export declare const BEHAVIOR_DEFAULT_PHASE: Readonly<Record<BehaviorStore, BehaviorPhase>>;
+/** A behavior's declared data: the SAME `p.*` DSL `defineWidget` uses. */
+export type BehaviorSchema = Readonly<Record<string, PropSpec>>;
+export type BehaviorHookName = "init" | "update" | "changed" | "tick" | "dispose";
+export type BehaviorPropDescription = {
+    readonly kind: "string";
+    readonly default?: string;
+} | {
+    readonly kind: "number";
+    readonly default?: number;
+    readonly min?: number;
+    readonly max?: number;
+} | {
+    readonly kind: "boolean";
+    readonly default?: boolean;
+} | {
+    readonly kind: "enum";
+    readonly options: readonly string[];
+    readonly default?: string;
+} | {
+    readonly kind: "json";
+    readonly inner: JsonShape;
+    readonly default?: string;
+} | {
+    readonly kind: "entityKey";
+    readonly default?: string;
+};
+export interface BehaviorReadDescription {
+    readonly kind: "behavior" | "component" | "tag" | "relation" | "resource";
+    readonly name: string;
+}
+export interface BehaviorDescription {
+    readonly id: string;
+    readonly store: BehaviorStore;
+    readonly derived: boolean;
+    readonly deriveDuringGesture: boolean;
+    readonly version: number;
+    readonly phase: BehaviorPhase;
+    readonly budgetMs?: number;
+    readonly tickWhile: "all" | "visible";
+    readonly schema: readonly {
+        readonly name: string;
+        readonly spec: BehaviorPropDescription;
+    }[];
+    readonly reads: readonly BehaviorReadDescription[];
+    readonly writes: readonly string[];
+    readonly migrationFrom: readonly number[];
+    readonly hooks: readonly BehaviorHookName[];
+}
+type ValueOfSpec<S extends PropSpec> = S extends NumberSpec ? number : S extends BooleanSpec ? boolean : S extends EnumSpec ? string : S extends JsonSpec ? unknown : S extends StringSpec | EntityKeySpec ? string : never;
+/**
+ * The hook-facing data view. `p.json` fields arrive PARSED (the cell is a
+ * string; the snapshot carries the value) — parsing happens once per delivery,
+ * and delivery only runs on change, so the cost is keyed to churn rather than
+ * to frame rate. `ctx.write`/`tx.write` serialize back.
+ */
+export type DataOf<Sch extends BehaviorSchema> = {
+    readonly [K in keyof Sch]: ValueOfSpec<Sch[K]>;
+};
+/**
+ * Anything a behavior may declare in `reads:` — components, tags, relations,
+ * resources, or another behavior (its data component). Each kind is routed to
+ * a different change mechanism by the compiler (§5.2), which is why the
+ * partition is compiler work and not an author concern.
+ */
+export type BehaviorRead = Component | Tag | Relation | Resource | AnyBehaviorDef;
+/** The drained journal summary, valid only for the duration of the hook call. */
+export interface BehaviorChanges {
+    /** Rebuild everything: first run, `world.reset()`, coarse writes, or a poll fired. */
+    readonly full: boolean;
+    /** Journaled entities — re-read current state to act. */
+    readonly changed: readonly Entity[];
+    /** DESTROYED entities (packed handles; safe as removal keys). */
+    readonly removed: readonly Entity[];
+}
+/**
+ * `ctx.world` is a HOST-BUILT WRAPPER, not a `World` alias and not
+ * `ReadonlyWorld` (BF-D19): that type is `Omit<World, WorldMutatorName>`, which
+ * keeps `.runtime` — the full mutable store — so it is a naming convention, not
+ * a sandbox. This interface exposes exactly the read surface and nothing else.
+ *
+ * Honesty note: point reads through this wrapper are ATTRIBUTION-ONLY — strata
+ * enforces declared reads solely at `batch.col()`, so the compiled delivery
+ * walk (`ctx.query`) is where enforcement is real.
+ */
+export interface BehaviorWorld {
+    read<S>(e: Entity, c: Component<S>): S;
+    get<S>(e: Entity, c: Component<S>): S | undefined;
+    readField<S, K extends keyof S & string>(e: Entity, c: Component<S>, field: K): S[K] | undefined;
+    has(e: Entity, c: Component): boolean;
+    hasTag(e: Entity, t: Tag): boolean;
+    getRelation(e: Entity, r: Relation): Entity | undefined;
+    getRelations(e: Entity, r: Relation): Entity[];
+    getReverse(e: Entity, r: Relation): Entity[];
+    /** Sibling-sequence version for one parent — ordered relations (petition 8). */
+    orderStamp(parent: Entity, r: Relation): number;
+    getResource<S>(res: Resource<S>): S | undefined;
+    componentsOf(e: Entity): readonly Component[];
+    tagsOf(e: Entity): readonly Tag[];
+    isAlive(e: Entity): boolean;
+}
+/** A reads-scoped query walk. Terms are restricted to the behavior's `reads`. */
+export interface BehaviorQuery {
+    /** Every matching entity. The array is FRESH per call — retaining it is legal. */
+    entities(): Entity[];
+    /** Iterate matches one at a time (no array allocated). */
+    each(fn: (e: Entity) => void): void;
+    /** First match, or undefined. */
+    first(): Entity | undefined;
+}
+/** Query terms a behavior may build — its declared reads, positively or negatively. */
+export interface BehaviorQuerySpec {
+    /** Entities must carry ALL of these (components/tags from `reads`). */
+    readonly all?: readonly (Component | Tag | AnyBehaviorDef)[];
+    /** Entities must carry NONE of these. */
+    readonly none?: readonly (Component | Tag | AnyBehaviorDef)[];
+}
+/** Frame facts a `tick` hook reads. */
+export interface BehaviorFrame {
+    readonly dtMs: number;
+    readonly tick: number;
+    /** Accumulated CLAMPED dt — under-reports across freezes; never wall time. */
+    readonly clock: number;
+}
+/** One remote peer's facet of an ephemeral behavior (`ctx.peers()`). */
+export interface PeerFacet<Data> {
+    /** The remote presence-peer entity (runtime handle — do not persist). */
+    readonly entity: Entity;
+    readonly data: Readonly<Data>;
+}
+export interface BehaviorCtxBase<Data> {
+    /** The read wrapper (above). */
+    readonly world: BehaviorWorld;
+    /**
+     * A reads-SCOPED query. The framework compiles and caches one Query per
+     * distinct spec and walks it ATTRIBUTED — strata's only enforced read path,
+     * and its only zero-allocation bulk path. Without this, navigation was
+     * instances-outward only and `changed` got abused as a discovery channel.
+     *
+     * The navigation model, stated: behaviors navigate from their instances
+     * outward via relations, the change journal, and reads-scoped queries. There
+     * is no global search.
+     */
+    query(spec: BehaviorQuerySpec): BehaviorQuery;
+    /** This behavior's own instances, this frame (snapshot — do not retain). */
+    entities(): readonly Entity[];
+    /** The drained journal summary. Meaningful during `changed`; do not retain. */
+    changes(): BehaviorChanges;
+    /** The journal ∩ this behavior's instances — the exact set. Do not retain. */
+    changedEntities(): readonly Entity[];
+    /** Durable doc key for an entity (undefined when not doc-bound). */
+    keyOf(e: Entity): string | undefined;
+    /** The entity for a durable key — undefined while it is not yet projected. */
+    entityFor(key: string): Entity | undefined;
+    /** Aborts at generation teardown (`world.reset`), detach, or engine dispose. */
+    readonly signal: AbortSignal;
+    /** Namespaced logging — routed to the host's diagnostics, never raw console. */
+    log(message: string, ...rest: readonly unknown[]): void;
+}
+export interface DurableBehaviorCtx<Data> extends BehaviorCtxBase<Data> {
+    /**
+     * ONE labeled transaction. The transaction opens INSIDE the hook, in-system
+     * (design-002-blessed): values land synchronously and this frame's `notify`
+     * sees them — never queued past the tick. `label` is a stable MACHINE id
+     * (namespaced), never display text: it feeds undo and in-CRDT provenance.
+     *
+     * Refuses on a read-only document. `tx.setResource` is MASKED (the §9
+     * resource-write fence, made mechanical) — a behavior calling it DEV-throws
+     * naming the `singleton` v1.1 seam.
+     */
+    commit(label: string, fn: (tx: BehaviorTx<Data>) => void, opts?: {
+        undoable?: boolean;
+    }): void;
+}
+export interface RuntimeBehaviorCtx<Data> extends BehaviorCtxBase<Data> {
+    /** Write this behavior's OWN data on `e` (immediate; session-local). */
+    write(e: Entity, patch: Partial<Data>): void;
+    /** Write a declared runtime-store `writes:` target (immediate). */
+    set<S>(e: Entity, c: Component<S>, v: S): void;
+    attach(e: Entity, data?: Partial<Data>): void;
+    detach(e: Entity): void;
+    /** A runtime behavior may also commit durable state (a settle writing finals once). */
+    commit(label: string, fn: (tx: BehaviorTx<Data>) => void, opts?: {
+        undoable?: boolean;
+    }): void;
+}
+export interface EphemeralBehaviorCtx<Data> extends BehaviorCtxBase<Data> {
+    /**
+     * Publish THIS PEER's facet. No entity argument — the instance IS the local
+     * presence peer, and there is exactly one. Legal here because ephemeral hooks
+     * run at the publish slot, post-tick, where eph mutation is allowed.
+     */
+    write(patch: Partial<Data>): void;
+    /** REMOTE peers' facets of this behavior (read-only; `Not(Local)` projections). */
+    peers(): readonly PeerFacet<Data>[];
+}
+export type BehaviorCtxFor<S extends BehaviorStore, Data> = S extends "durable" ? DurableBehaviorCtx<Data> : S extends "runtime" ? RuntimeBehaviorCtx<Data> : EphemeralBehaviorCtx<Data>;
+/**
+ * The door's transaction: `GuardedTx` plus behavior attachment and typed
+ * own-data writes. `setResource` is absent by construction (§4.4's mask).
+ */
+export interface BehaviorTx<Data> extends Omit<GuardedTx, "setResource"> {
+    /** Write this behavior's own data on `e` (absolute, whole-value). */
+    write(e: Entity, patch: Partial<Data>): void;
+    /** Attach a behavior as a DOCUMENT op — syncs, undoes, runs on every peer. */
+    attach<D>(e: Entity, behavior: BehaviorHandle<D>, data?: Partial<D>): void;
+    detach(e: Entity, behavior: AnyBehaviorDef): void;
+}
+export interface BehaviorHooks<S extends BehaviorStore, Data> {
+    /**
+     * Instance appeared: attached locally, projected in (REMOTE included), or
+     * existing at generation start. Runs before that instance's first `tick`.
+     * A throw here marks the INSTANCE failed — no further hooks until re-attach.
+     */
+    init?(e: Entity, data: Readonly<Data>, ctx: BehaviorCtxFor<S, Data>): void;
+    /**
+     * OWN declared data changed since the last delivery — by ANY writer: this
+     * behavior's commit, another plugin's tx, UNDO, or a remote peer.
+     * Per-instance; `prev` is the last-delivered snapshot. "update is about you."
+     */
+    update?(e: Entity, data: Readonly<Data>, prev: Readonly<Data>, ctx: BehaviorCtxFor<S, Data>): void;
+    /**
+     * The reads-set changed. ONCE PER BEHAVIOR per frame, not per instance —
+     * N instances × one tag flip must not mean N journal scans.
+     * "changed is about the world."
+     */
+    changed?(ctx: BehaviorCtxFor<S, Data>): void;
+    /**
+     * Per frame per instance — OPT-IN cost. Default is ALL instances (Law 14: an
+     * off-screen spring still settles); `tick: { while: "visible" }` is the
+     * author's DECLARED suspension. `init`/`update`/`changed`/`dispose` never
+     * suspend: culling is not lifecycle, and state must be right the moment it
+     * becomes visible again.
+     */
+    tick?(e: Entity, data: Readonly<Data>, frame: BehaviorFrame, ctx: BehaviorCtxFor<S, Data>): void;
+    /**
+     * Instance gone: detached, despawned, disabled, or generation end. `e` may
+     * already be dead (world access is DEV-guarded) — this is for cache cleanup.
+     * Runs for ALL instances BEFORE `ctx.signal` aborts.
+     */
+    dispose?(e: Entity, ctx: BehaviorCtxFor<S, Data>): void;
+}
+export interface BehaviorSpec<S extends BehaviorStore, Sch extends BehaviorSchema> {
+    /** REQUIRED — routes everything (§3). */
+    readonly store: S;
+    /**
+     * This behavior's durable writes are COMPUTED from other state. Durable only.
+     * Bundles three protections: non-undoable output, the differ, and
+     * claim-scoped delivery suppression (§5.3).
+     */
+    readonly derived?: boolean;
+    /**
+     * Opt out of suppression: derive live during gestures (costs accepted).
+     * `derived` only.
+     */
+    readonly deriveDuringGesture?: boolean;
+    /** Durable only — the `engine.behavior.<name>.<v>` marker family (§5.6). */
+    readonly version?: number;
+    readonly schema?: Sch;
+    /** Durable only: fromVersion → idempotent absolute transform. */
+    readonly migrate?: Readonly<Record<number, (prev: Record<string, unknown>) => Record<string, unknown>>>;
+    /** Defaults per store (§4.4); validated against the legal set. */
+    readonly phase?: BehaviorPhase;
+    /** Per-frame budget request, ms. The breaker caps it at the seam ceiling. */
+    readonly budgetMs?: number;
+    readonly reads?: readonly BehaviorRead[];
+    readonly writes?: readonly Component[];
+    /**
+     * `tick` scope. `{ while: "visible" }` compiles a `Not(Culled)` term into the
+     * chunked tick system — declared suspension, never discovered.
+     */
+    readonly tick?: {
+        readonly while?: "visible" | "all";
+    };
+    readonly on?: BehaviorHooks<S, DataOf<Sch>>;
+}
+/** A behavior pre-attachment: `Layout.with({ gapX: 32 })`. */
+export interface BehaviorAttachSpec<Data = Record<string, unknown>> {
+    readonly behavior: BehaviorHandle<Data>;
+    readonly data: Partial<Data>;
+}
+/**
+ * The compiled declaration. Usable wherever a behavior is expected —
+ * `reads: [Glow]`, `behaviors: [Layout]`, `tx.attach(e, Layout)` — plus
+ * `.with(data)` for pre-attachment and `.component` for advanced read paths.
+ */
+export interface BehaviorHandle<Data> {
+    /** `<namespace>:<name>` — the process-global identity. */
+    readonly name: string;
+    readonly namespace: string;
+    readonly store: BehaviorStore;
+    readonly derived: boolean;
+    readonly deriveDuringGesture: boolean;
+    readonly version: number;
+    readonly phase: BehaviorPhase;
+    readonly budgetMs: number | undefined;
+    readonly schema: BehaviorSchema;
+    /** The generated data component (`behavior:<name>`). Advanced read paths. */
+    readonly component: Component<Record<string, string | number | boolean>>;
+    /** Every field at its declared default (the attach fill). */
+    readonly defaults: Readonly<Data>;
+    readonly reads: readonly BehaviorRead[];
+    readonly writes: readonly Component[];
+    readonly migrate: Readonly<Record<number, (prev: Record<string, unknown>) => Record<string, unknown>>>;
+    readonly tickWhile: "all" | "visible";
+    /**
+     * The hook set. MUTABLE by design: a same-shape re-definition (hot reload,
+     * a test re-importing a module) refreshes these in place, so the cached
+     * handle keeps its component and collector identity while the new code
+     * actually runs. Stale-hook HMR is the wart this avoids.
+     */
+    on: BehaviorHooks<BehaviorStore, Data>;
+    /** Pre-attachment with data: `behaviors: [Layout.with({ gapX: 32 })]`. */
+    with(data: Partial<Data>): BehaviorAttachSpec<Data>;
+    /** @internal brand — how `reads:` tells a behavior from a component. */
+    readonly __behavior: true;
+}
+/** A behavior handle of unknown data shape (registries, `reads:` lists). */
+export type AnyBehaviorDef = BehaviorHandle<any>;
+/**
+ * A pre-attachment of unknown data shape — what a LIST of them has to be typed
+ * as. `BehaviorAttachSpec<never>` looks like the shape-agnostic form and is
+ * not: `Layout.with({gapX: 32})` produces `BehaviorAttachSpec<{gapX: number}>`,
+ * which is not assignable to it, so the documented `with()` form would not
+ * typecheck in `defineWidget({behaviors})` at all.
+ */
+export type AnyBehaviorAttachSpec = BehaviorAttachSpec<any>;
+export {};

package/dist/types/packages/core/src/behavior/world-view.d.ts

@@ -0,0 +1,36 @@
+import type { Component, Entity, Query, Relation, Resource, SystemCtx, Tag, World } from "@vibecook/strata-ecs";
+import type { AnyBehaviorDef, BehaviorQuery, BehaviorQuerySpec, BehaviorWorld } from "./types";
+export declare function createBehaviorWorld(world: World): BehaviorWorld;
+/**
+ * The compiled-query cache for one behavior. Keyed on the term identity list,
+ * so the common case (a behavior calling `ctx.query` with the same spec every
+ * frame) compiles ONCE — `defineQuery` identity is strata's own cache key for
+ * the matched-archetype list, so re-compiling per call would defeat two caches.
+ */
+export declare function createQueryScope(behavior: AnyBehaviorDef, allowed: ReadonlySet<Component | Tag>): (walker: BehaviorWalker, spec: BehaviorQuerySpec) => BehaviorQuery;
+/**
+ * Where a behavior's walks and structural ops go, which depends on WHERE it is
+ * running — and the difference is not cosmetic.
+ *
+ * In a pipeline phase the behavior is inside a system: walks go through
+ * `SystemCtx` (attributed — strata's enforced read path), and structural ops
+ * are DEFERRED to the phase boundary because immediate `world.*` structural
+ * mutation throws at iteration depth > 0.
+ *
+ * At the publish slot there is no running system and no iteration bracket:
+ * walks are plain `world.query` (unattributed — nothing to attribute them to),
+ * and structural ops are immediate and legal. Ephemeral behaviors live here,
+ * which is exactly why eph structural writes are legal for them and illegal
+ * for everyone else.
+ */
+export interface BehaviorWalker {
+    each(q: Query, fn: (e: Entity) => void): void;
+    first(q: Query): Entity | undefined;
+    addComponent(e: Entity, c: Component, v: unknown): void;
+    removeComponent(e: Entity, c: Component): void;
+}
+export declare function systemWalker(ctx: SystemCtx): BehaviorWalker;
+export declare function publishWalker(world: World): BehaviorWalker;
+/** The term set a behavior may query: its own component ∪ declared components/tags. */
+export declare function allowedQueryTerms(behavior: AnyBehaviorDef, readComponents: readonly Component[], readTags: readonly Tag[]): ReadonlySet<Component | Tag>;
+export type { Relation, Resource };

package/dist/types/packages/core/src/engine/engine.d.ts

@@ -5,6 +5,12 @@
  *     setFrameInfo        FrameInfo resource — value write, pre-tick
  *     world.sync()        durable + presence drains land; projections place
  *     world.tick(...)     the phase-group pipeline (pipeline.ts)
+ *     guests              [2026-08-15, petition I14] the NAMED guest slot:
+ *                         plugin/host frame work under a circuit breaker
+ *                         (guests.ts). BEFORE publish so derived state has
+ *                         settled when presence I/O reads it, and before
+ *                         notify so the same frame reflects it. Guests are
+ *                         fault-ISOLATED — the one tier here that is.
  *     publish hooks       POST-TICK, PRE-NOTIFY: presence I/O home — eph
  *                         structural ops are illegal for the whole tick, this
  *                         step is theirs; `world.*` is legal here (outside the
@@ -22,6 +28,7 @@
 import type { World } from "@vibecook/strata-ecs";
 import type { AnySystem } from "./pipeline";
 import { type FrameControl } from "./frame-control";
+import { type GuestRegistry } from "./guests";
 import { type PhaseGroup } from "./pipeline";
 import { type ReflectorDef } from "./reflectors";
 export type PublishHook = (world: World) => void;
@@ -38,10 +45,29 @@ export interface FrameTelemetry {
     readonly systems: readonly SystemRunRecord[];
     readonly phaseFlushMicros: ReadonlyMap<string, number>;
     readonly reflectorsFlushed: readonly string[];
+    /**
+     * Total reflector-flush cost, µs (post-notify — OUTSIDE the tick, which is
+     * why it can never appear in `phaseFlushMicros`: that map is keyed by strata
+     * PHASE names and reflect is not a phase. Devtools' "reflect" lane read that
+     * map until 2026-08-15 and therefore never reported at all).
+     */
+    readonly reflectMicros: number;
+    /** Per-reflector flush cost, µs, for the same frame (registration order). */
+    readonly reflectorMicros: ReadonlyMap<string, number>;
 }
 export interface EngineOpts {
     /** Reflector fault sink (default: console.error, skip this frame). */
     readonly onReflectorFault?: (name: string, err: unknown) => void;
+    /** Guest fault sink (default: console.error). A guest throwing is contained
+     *  by the breaker; hosts route this to their own diagnostics. */
+    readonly onGuestFault?: (id: string, err: unknown) => void;
+    /**
+     * Guest breaker notices — suspensions and lenient-mode overruns (default:
+     * console.warn). Hosts SHOULD route this: a suspended derived guest means
+     * derived state silently stops updating, which reads to a user as a broken
+     * document rather than a broken plugin (design-009 §7).
+     */
+    readonly onGuestNotice?: (message: string) => void;
 }
 export interface Engine {
     readonly world: World;
@@ -53,6 +79,13 @@ export interface Engine {
     reflectorNames(): readonly string[];
     /** Register a publish-step hook (post-tick, pre-notify presence I/O). Returns a remover. */
     onPublish(hook: PublishHook): () => void;
+    /**
+     * The guest runtime (petition I14): frame-cadence work the engine did not
+     * write — plugin systems, host derived-state jobs, compiled behaviors — run
+     * in a named slot between the tick and the publish hooks, each fault-isolated
+     * and budgeted by a circuit breaker (guests.ts).
+     */
+    readonly guests: GuestRegistry;
     /** Run one full frame. `now` in ms (rAF timestamp or a test counter). */
     step(now: number): void;
     /**
@@ -65,8 +98,12 @@ export interface Engine {
      * hand exactly as before.
      */
     readonly frame: FrameControl;
-    /** Arm per-system run/skip + µs collection (idempotent; costs timer calls per system). */
+    /** Arm per-system run/skip + µs collection (idempotent; costs timer calls per system).
+     *  Also puts the guest breaker in LENIENT mode — devtools attached means a
+     *  debugger breakpoint must not suspend a healthy guest. */
     enableTelemetry(): void;
+    /** Tear down guest instances (the facade calls this from `dispose()`). */
+    disposeGuests(): void;
     /** The most recent completed frame's readout (undefined until telemetry armed + one step). */
     lastFrame(): FrameTelemetry | undefined;
 }

package/dist/types/packages/core/src/engine/guests.d.ts

@@ -0,0 +1,199 @@
+/**
+ * The guest runtime (petition I14 — the literal PA-28 "spine scheduler").
+ *
+ * A GUEST is frame-cadence work the engine did not write: a plugin's declared
+ * system, a host's derived-state job, and (from design-009) every compiled
+ * behavior. Guests get a NAMED slot in the frame contract — design-002 §1 as
+ * amended 2026-08-15:
+ *
+ *     setFrameInfo → sync → tick → GUESTS → publish hooks → notify → reflect
+ *
+ * Guests run BEFORE the publish hooks so derived state has settled by the time
+ * presence I/O reads it, and before `notify()` so the same frame reflects their
+ * writes. Three properties the engine owes anything it hosts here:
+ *
+ * 1. **Fault isolation.** A throwing guest is caught, struck, and skipped — it
+ *    never kills the loop, its neighbours, or the frame. (Engine systems and
+ *    publish hooks keep propagating loudly by design; guests are the untrusted
+ *    tier, and the breaker below is what makes hosting them honest.)
+ * 2. **The snapshot rule.** `runAll` iterates a snapshot with a liveness check,
+ *    so a guest that adds or removes guests mid-run never skips a neighbour —
+ *    the bug this same release fixed in the publish-hook and reflector loops.
+ *    A guest added during a run starts NEXT frame.
+ * 3. **A circuit breaker, named honestly.** A main-thread body cannot be
+ *    preempted: by the time we measure, the frame is already spent. What the
+ *    breaker guarantees is that no guest hurts the canvas TWICE sustained.
+ *
+ * GENERATIONS. `make(gen)` builds a per-generation instance; the generation
+ * boundary in ICE is `world.reset()` (doc close/switch — the world is reset in
+ * place, so systems, observers and this registry all survive while every entity
+ * dies). On reset we mark the generation dirty and rebuild at the TOP of the
+ * next guest step — never inside the observer emit, where structural writes are
+ * illegal and user code has no business running. `gen.signal` aborts when the
+ * generation ends or the guest is removed.
+ *
+ * THE LEDGER IS HOST-INJECTABLE. Downstream (VibeField) an engine is per-doc, so
+ * a registry-local ledger would reset on every doc switch and hand chronic
+ * offenders a fresh probation forever. `add({ledger})` seeds prior state and
+ * `onLedgerChange` reports every transition, so the host persists across
+ * generations it owns.
+ */
+import type { World } from "@vibecook/strata-ecs";
+/** Frame facts a guest may read (FrameInfo, pre-read by the engine). */
+export interface GuestFrame {
+    readonly dtMs: number;
+    readonly tick: number;
+    /** Accumulated CLAMPED dt — under-reports across freezes; never accumulate
+     *  wall time from it (frame-info.ts). */
+    readonly clock: number;
+}
+export type GuestRun = (frame: GuestFrame) => void;
+export interface GuestInstance {
+    run: GuestRun;
+    dispose?: () => void;
+    /**
+     * "I still owe visible work." Feeds the frame gate's settle walk, so a
+     * freeze taken mid-derive parks only AFTER the guest has caught up — the
+     * canvas is never photographed between a structural change and its reflow.
+     * A guest with no owed-work notion simply omits it (the frame gate then
+     * treats it as quiet, which is the honest default).
+     */
+    busy?: () => boolean;
+}
+export interface GuestGeneration {
+    readonly world: World;
+    /** Aborts at generation teardown (world reset), removal, or engine dispose. */
+    readonly signal: AbortSignal;
+}
+export type GuestFactory = (gen: GuestGeneration) => GuestInstance | GuestRun;
+/** The persistable half of a guest's breaker state. */
+export interface GuestLedgerRecord {
+    /** Cumulative over-budget/fault strikes (never reset by resume — honesty). */
+    readonly strikes: number;
+    readonly suspended: boolean;
+}
+export interface GuestSpec {
+    /** Stable id — the ledger key, the profiler lane name, the doctor's row. */
+    readonly id: string;
+    readonly make: GuestFactory;
+    /** Per-invocation budget request; the effective budget is
+     *  `min(budgetMs, seamCapMs)` — no single guest may claim the whole seam. */
+    readonly budgetMs?: number;
+    /** RESERVED. Hosted guests run in the publish slot only — and that is now the
+     *  settled shape, not a v1 placeholder: M13 reached pipeline cadence through
+     *  `addDriven` (behaviors run as pipeline systems and CHARGE this breaker)
+     *  instead of widening this field. A wider value would mean a second way to
+     *  put foreign code in the tick that `addDriven` already provides. */
+    readonly phase?: "publish";
+    /** Seed prior breaker state (host-persisted across engine generations). */
+    readonly ledger?: GuestLedgerRecord;
+}
+export interface GuestStatus {
+    readonly id: string;
+    readonly status: "running" | "suspended" | "failed";
+    /** Last invocation, ms. */
+    readonly lastMs: number;
+    /** p95 over the rolling window, ms. */
+    readonly p95Ms: number;
+    readonly strikes: number;
+    readonly budgetMs: number;
+}
+/**
+ * A guest whose CADENCE its owner drives (design-009 §7): compiled behaviors
+ * run as ordinary pipeline systems, in their declared phase, inside the tick —
+ * so nothing here can call their bodies. What they still need is everything
+ * ELSE a guest gets: one breaker, one ledger, one doctor row, one seam total.
+ * That is what this handle is — the breaker, detached from the scheduler.
+ */
+export interface DrivenGuest {
+    /** Breaker verdict. Cheap and never throws — poll it from a system `runIf`. */
+    suspended(): boolean;
+    /**
+     * Run `body` inside this guest's fault domain, ACCRUING its cost into the
+     * current frame's charge. Returns false when the guest is suspended (the
+     * body did not run) or the body threw (contained).
+     *
+     * Accrual, not per-call recording, is what makes the budget mean "per frame"
+     * for a CHUNKED body: a tick system's body runs once per matching chunk, and
+     * recording each chunk as its own invocation would compare a 2ms frame budget
+     * against a fraction of the work it was meant to bound. The accrued total is
+     * closed as ONE invocation at the guest slot, every frame.
+     */
+    run(body: () => void): boolean;
+    /**
+     * Report a fault the caller already CONTAINED — a per-instance hook throw
+     * that the delivery loop caught so one bad node cannot kill a 1000-node
+     * behavior (BF-D18). It takes the ordinary throw ladder.
+     */
+    fault(err: unknown): void;
+    /** Idempotent. */
+    remove(): void;
+}
+export interface DrivenGuestSpec {
+    readonly id: string;
+    readonly budgetMs?: number;
+    readonly ledger?: GuestLedgerRecord;
+    /** Owed-work reporter for the frame gate's settle walk. */
+    readonly busy?: () => boolean;
+}
+export interface GuestRegistry {
+    /** Register a guest. Returns a remover (idempotent; disposes the instance). */
+    add(spec: GuestSpec): () => void;
+    /**
+     * Register a guest the registry does NOT call (see {@link DrivenGuest}).
+     * Its cost still lands in this frame's seam total, its strikes in the same
+     * ledger, and its row in `list()`.
+     */
+    addDriven(spec: DrivenGuestSpec): DrivenGuest;
+    /** Live status for devtools/doctor — never throws, safe to poll. */
+    list(): readonly GuestStatus[];
+    /** Fires whenever a guest's persistable breaker state changes. */
+    onLedgerChange(cb: (id: string, record: GuestLedgerRecord) => void): () => void;
+    /** Clear a suspension (the doctor's explicit action). Cumulative strikes
+     *  survive; the rolling window is cleared so probation starts fresh. */
+    resume(id: string): void;
+}
+/** The engine-facing half (step drives it; hosts never see these). */
+export interface GuestRegistryInternal extends GuestRegistry {
+    runAll(frame: GuestFrame): void;
+    /** Any live guest reporting owed work — the engine's settle reporter. */
+    anyBusy(): boolean;
+    dispose(): void;
+}
+/**
+ * Breaker constants (design-009 §12 / door ED-D3). Exported so tests and the
+ * downstream doctor cite ONE source rather than re-deriving thresholds.
+ */
+export declare const GUEST_BUDGET: {
+    /** Default per-invocation budget when a guest declares none. */
+    readonly defaultBudgetMs: 2;
+    /** The whole guest seam's sustained budget — also the per-guest ceiling. */
+    readonly seamCapMs: 8;
+    /** Rolling window length, in invocations. */
+    readonly window: 120;
+    /** Trip: more than this many of the last `window` invocations over budget. */
+    readonly overBudgetTrip: 30;
+    /** Trip: this many CONSECUTIVE invocations at ≥ `heavyFactor` × budget. */
+    readonly consecutiveHeavy: 3;
+    readonly heavyFactor: 4;
+    /** Trip: this many CONSECUTIVE invocations over `stallMs` (one GC pause or
+     *  debugger breakpoint must never suspend — hence 2, not 1). */
+    readonly consecutiveStall: 2;
+    readonly stallMs: 50;
+    /** Trip: this many consecutive throws. */
+    readonly consecutiveThrows: 3;
+    /** Frames the whole seam may sit over `seamCapMs` before the worst offender
+     *  is suspended. */
+    readonly seamOverFrames: 3;
+};
+export interface GuestRegistryOpts {
+    /**
+     * Dev leniency: while true, TIMING strikes log and never suspend (the throw
+     * ladder still bites). Wired to `engine.enableTelemetry()` — i.e. devtools
+     * attached — so stepping in a debugger cannot suspend a healthy guest.
+     */
+    readonly lenient?: () => boolean;
+    readonly onFault?: (id: string, err: unknown) => void;
+    readonly onNotice?: (message: string) => void;
+}
+export declare function createGuestRegistry(world: World, opts?: GuestRegistryOpts): GuestRegistryInternal;