@vibecook/ice 0.4.0 → 0.6.0

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

@@ -0,0 +1,91 @@
+import type { Component, Entity, OrderPlace, Relation, Tag, World } from "@vibecook/strata-ecs";
+import type { GuardedTx } from "../guards/guarded-tx";
+export type RecOp = {
+    readonly kind: "set";
+    readonly e: Entity;
+    readonly c: Component;
+    readonly v: unknown;
+} | {
+    readonly kind: "add";
+    readonly e: Entity;
+    readonly c: Component;
+    readonly v: unknown;
+} | {
+    readonly kind: "removeComponent";
+    readonly e: Entity;
+    readonly c: Component;
+} | {
+    readonly kind: "destroy";
+    readonly e: Entity;
+} | {
+    readonly kind: "addTag";
+    readonly e: Entity;
+    readonly t: Tag;
+} | {
+    readonly kind: "removeTag";
+    readonly e: Entity;
+    readonly t: Tag;
+} | {
+    readonly kind: "setRelation";
+    readonly e: Entity;
+    readonly r: Relation;
+    readonly target: Entity;
+    readonly place?: OrderPlace;
+} | {
+    readonly kind: "addRelation";
+    readonly e: Entity;
+    readonly r: Relation;
+    readonly target: Entity;
+} | {
+    readonly kind: "removeRelation";
+    readonly e: Entity;
+    readonly r: Relation;
+    readonly target?: Entity;
+} | {
+    readonly kind: "moveRelation";
+    readonly e: Entity;
+    readonly r: Relation;
+    readonly place: OrderPlace;
+} | {
+    readonly kind: "move";
+    readonly e: Entity;
+    readonly to: {
+        x: number;
+        y: number;
+    };
+    readonly animateMs: number;
+};
+export interface DiffDeps {
+    readonly world: World;
+    /** The DOC's value for a cell — what a commit would actually be compared to. */
+    docValue(e: Entity, c: Component): unknown;
+    /** The behavior's declared `writes:` targets (the derived-output test). */
+    readonly writeTargets: ReadonlySet<Component>;
+}
+export interface DiffResult {
+    readonly ops: readonly RecOp[];
+    /**
+     * The commit touches a declared `writes:` target — it is derived OUTPUT, so
+     * it is forced non-undoable. A commit that only touches the behavior's OWN
+     * data is an authorial config edit and keeps normal undo.
+     */
+    readonly derivedOutput: boolean;
+    /** Entities this commit wrote — the next drain's subtraction set. */
+    readonly writtenEntities: readonly Entity[];
+    /**
+     * The VALUES the surviving ops commit, per entity per component. The echo
+     * snapshot needs these rather than a post-seal world read: a durable write
+     * lands in the doc now but projects into the world at the NEXT `world.sync()`,
+     * so reading the world here would capture the value the commit is replacing.
+     */
+    readonly writtenValues: ReadonlyMap<Entity, ReadonlyMap<Component, unknown>>;
+}
+/**
+ * Record a DERIVED commit body's ops without performing any of them. Only the
+ * derived path buffers: a plain durable behavior commits straight through, so
+ * it keeps `tx.spawn` and pays no recording cost.
+ */
+export declare function recordDerivedOps(behaviorName: string, build: (rec: GuardedTx) => void): RecOp[];
+export declare function diffOps(ops: readonly RecOp[], deps: DiffDeps): DiffResult;
+/** Replay diffed ops onto the real transaction. */
+export declare function replayOps(ops: readonly RecOp[], tx: GuardedTx): void;

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

@@ -0,0 +1,65 @@
+/**
+ * `createBehaviorHarness` — the testing story, shipped WITH the framework
+ * rather than after it (design-009 §7).
+ *
+ * A behavior is frame-cadence, collaboration-native, transaction-writing code.
+ * Testing that without a rig means standing up an engine, a document, a
+ * pipeline and a hand-driven clock — enough ceremony that most authors would
+ * simply not test the interesting parts. The interesting parts are exactly the
+ * ones they will get wrong:
+ *
+ *   - `claim(e)` fakes a live gesture claim, so an author can see their derived
+ *     behavior go quiet during a drag and coalesce at the settle. Suppression
+ *     is the single most surprising rule in the framework.
+ *   - `pair()` gives a SECOND engine on the same document. Convergence bugs are
+ *     invisible on one peer by definition, and "it works for me" is what a
+ *     collaborative editor's bug reports look like.
+ *   - `commits` records what actually reached the store, which is how you tell
+ *     "the differ dropped it" from "it never ran".
+ */
+import { type Entity, type World } from "@vibecook/strata-ecs";
+import { type Engine } from "../engine/engine";
+import { type DocSession } from "../doc/doc-kit";
+import { type BehaviorRuntime } from "./runtime";
+import type { AnyBehaviorDef } from "./types";
+/** One commit the harness observed reaching the store. */
+export interface HarnessCommit {
+    readonly undoable: boolean;
+    /** `{ behavior, label }` for a `ctx.commit`; undefined for anything else. */
+    readonly meta: Record<string, unknown> | undefined;
+}
+export interface BehaviorHarnessOpts {
+    /**
+     * Attach a document. Default TRUE — durable behaviors need one, and a
+     * runtime behavior is unharmed by having it. `false` exercises the doc-less
+     * path deliberately (where `ctx.commit` refuses, by design).
+     */
+    readonly docs?: boolean;
+    /** Extra behaviors to register beside the one under test. */
+    readonly also?: readonly AnyBehaviorDef[];
+}
+export interface BehaviorHarness {
+    readonly world: World;
+    readonly engine: Engine;
+    readonly runtime: BehaviorRuntime;
+    doc(): DocSession | undefined;
+    /** Drive `n` frames (default 1). The clock advances 16ms per frame. */
+    step(n?: number): void;
+    /** A bare durable node with Position + Size, for behaviors to ride. */
+    spawn(x?: number, y?: number): Entity;
+    /** Attach the behavior under test — durable through a transaction, else direct. */
+    attach(e: Entity, data?: Record<string, unknown>): void;
+    detach(e: Entity): void;
+    /** The behavior's live instances, as the runtime sees them. */
+    instances(): readonly Entity[];
+    /** Every commit that reached the store since construction. */
+    readonly commits: readonly HarnessCommit[];
+    /** Simulate a live gesture claim on `e`. Returns the release. */
+    claim(e: Entity): () => void;
+    /** A SECOND engine on this document — the two-peer rig. */
+    pair(): BehaviorHarness;
+    /** Exchange updates with every paired harness, both ways. */
+    sync(): void;
+    dispose(): void;
+}
+export declare function createBehaviorHarness(b: AnyBehaviorDef, opts?: BehaviorHarnessOpts): BehaviorHarness;

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

@@ -0,0 +1,87 @@
+/**
+ * Behavior schema evolution (design-009 §5.5–§5.6, BF-D14) — M13g.
+ *
+ * Markers are `engine.behavior.<name>.<v>` write-once keys: a monotone key SET,
+ * never a mutated cell, so concurrent peers converge on the union instead of
+ * racing a single slot. They are a SEPARATE FAMILY from `engine.pack.*`, and
+ * that separation is the whole point of this file.
+ *
+ * **Why not fold them into the pack compare.** The pack compare classifies a
+ * doc marker with no local counterpart as `newerInDoc`, which read-onlys the
+ * document. For prefabs that is right — an unknown prefab means the doc was
+ * written by a newer build. For behaviors it is catastrophic: behaviors ship in
+ * PLUGINS, so "no local counterpart" is the ordinary state of every document
+ * whose author had a plugin this reader does not. Folding them in would brick a
+ * document because a plugin is missing — design-008's exact failure shape,
+ * which cost us a release to learn.
+ *
+ * So behaviors get their own compare with the **absent-is-not-newer** rule:
+ *   - a locally-unregistered behavior name is IGNORED ENTIRELY (its cells sit
+ *     in the doc un-projected and dormant — strata's projection is
+ *     name-registry-driven, so they are inert, not corrupt);
+ *   - `v > installed` for an INSTALLED behavior triggers per-behavior DORMANCY
+ *     (refuse hook delivery — projection is version-blind, so newer-shaped data
+ *     WOULD otherwise flow into older hooks), never a doc verdict;
+ *   - `v < installed` runs the migration chain.
+ *
+ * Behavior version state NEVER affects the document's gate verdict. That is a
+ * standing guarantee, and the anti-brick test in CI is what keeps it one.
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import type { LiveWriter } from "../guards/live-writer";
+import type { AnyBehaviorDef } from "./types";
+export declare const BEHAVIOR_MARKER_PREFIX = "engine.behavior.";
+export declare function behaviorMarkerKey(name: string, version: number): string;
+export interface BehaviorMeta {
+    readMeta(key: string): string | undefined;
+    metaTransaction(fn: (meta: {
+        get(key: string): unknown;
+        set(key: string, value: string): void;
+    }) => void): void;
+}
+/** The highest marker version present for `name` (0 = never stamped). */
+export declare function docBehaviorVersion(meta: BehaviorMeta, name: string, installed: number): number;
+/** Stamp the marker for `version` if it is not already present (write-once). */
+export declare function stampBehaviorMarker(meta: BehaviorMeta, name: string, version: number): void;
+export type BehaviorVerdict = {
+    readonly kind: "ok";
+}
+/** The doc is at a NEWER version than this build installs — refuse delivery. */
+ | {
+    readonly kind: "dormant";
+    readonly docVersion: number;
+    readonly installed: number;
+}
+/** The doc is OLDER — the chain has work to do. */
+ | {
+    readonly kind: "migrate";
+    readonly from: number;
+    readonly installed: number;
+}
+/** Older, but the chain cannot reach `installed` from there. */
+ | {
+    readonly kind: "unreachable";
+    readonly from: number;
+    readonly installed: number;
+};
+export declare function classifyBehaviorVersion(b: AnyBehaviorDef, docVersion: number): BehaviorVerdict;
+export interface MigrateDeps {
+    readonly world: World;
+    readonly meta: BehaviorMeta;
+    /** The doc store, for the one `{undoable: false}` transaction. */
+    readonly store: any;
+    readonly liveWriter?: LiveWriter;
+    /** Every entity currently carrying the behavior's component. */
+    carriers(): readonly Entity[];
+}
+/**
+ * Run `b`'s migrate chain over every carrier, in ONE non-undoable transaction,
+ * then stamp the new marker.
+ *
+ * A SECOND plan+write pass, not a reuse of the M9 prefab runner: that one
+ * filters by `PrefabId`, and a behavior rides entities of any kind — its own
+ * component is the only thing that identifies its cells.
+ *
+ * Returns the number of migrated carriers.
+ */
+export declare function runBehaviorMigration(b: AnyBehaviorDef, from: number, deps: MigrateDeps): number;

package/dist/types/packages/core/src/behavior/public-reads.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The CURATED public read surface for behaviors (design-009 §9).
+ *
+ * The engine catalog is exposed to behaviors DELIBERATELY, not accidentally.
+ * Every name on this list is a published contract: it is what a behavior may
+ * declare in `reads:` and expect to keep working across engine versions. Adding
+ * a name here is a product decision — it is a promise about a shape, not a
+ * convenience.
+ *
+ * Everything else in the catalog is ENGINE VOCABULARY: recognizers, claims,
+ * gesture bookkeeping, one-tick markers. Reading it from a behavior is not
+ * forbidden (the escape hatch stays open for engine-grade code), but it
+ * dev-WARNS, because those shapes change whenever the interaction stack does
+ * and no one will think to tell a plugin author.
+ *
+ * Two notes authors need and will not guess:
+ *   - One-tick markers (`WentDown`, the `Just*` family) are already CLEARED by
+ *     the time the publish slot runs, so an ephemeral behavior can never see
+ *     them. That is not a bug to route around; it is what "one tick" means.
+ *   - `Grab` and the claim relations are deliberately OFF the list. A behavior
+ *     that wants to know "is this being dragged right now" is usually asking
+ *     for claim-scoped suppression, which it already gets for free.
+ */
+import type { Component, Relation, Resource, Tag } from "@vibecook/strata-ecs";
+/**
+ * The published set. Ordered by what an author reaches for first: geometry,
+ * then structure, then state, then the view.
+ */
+export declare const PUBLIC_READS: ReadonlySet<Component | Tag | Relation | Resource>;
+/** Is this handle part of the published behavior read surface? */
+export declare function isPublicRead(handle: Component | Tag | Relation | Resource): boolean;

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

@@ -0,0 +1,88 @@
+import type { Component, Entity, World } from "@vibecook/strata-ecs";
+import type { GuestRegistry } from "../engine/guests";
+import type { PhaseGroup } from "../engine/pipeline";
+import type { LiveWriter } from "../guards/live-writer";
+import { type BehaviorMeta } from "./migrate";
+import type { AnyBehaviorDef } from "./types";
+/** The slice of a doc session the runtime needs (structural: tests fake it). */
+export interface BehaviorSession {
+    readonly readOnly: boolean;
+    readonly liveWriter: LiveWriter;
+    readonly store: {
+        transaction(fn: (tx: never) => void, opts?: {
+            undoable?: boolean;
+        }): void;
+        keyOf(e: Entity): unknown;
+        resolve(key: never): Entity | undefined;
+        getComponent<S>(e: Entity, c: Component<S>): S | undefined;
+        /** The version-marker surface (behavior/migrate.ts). Absent = no markers. */
+        readonly snapshot?: BehaviorMeta;
+        metaTransaction?(fn: (meta: {
+            get(key: string): unknown;
+            set(key: string, value: string): void;
+        }) => void): void;
+    };
+}
+/**
+ * The slice of a presence session an ephemeral behavior needs. Structural so
+ * tests can fake it, and a FUNCTION on the opts so it can swap with the doc —
+ * presence attaches and detaches with `docs.join`, and a behavior installed
+ * before either must simply lie dormant until one exists.
+ */
+export interface BehaviorPresence {
+    /** The local peer entity. A GETTER upstream: a world reset re-mints it. */
+    readonly localPeer: Entity;
+    readonly eph: {
+        addComponent(e: Entity, c: Component<unknown>, v: unknown): void;
+        removeComponent(e: Entity, c: Component): void;
+        edit(e: Entity): {
+            set(c: Component<unknown>, v: unknown): unknown;
+        };
+    };
+}
+export interface BehaviorRuntimeOpts {
+    readonly world: World;
+    readonly engine: {
+        addSystems(group: PhaseGroup, ...systems: readonly never[]): () => void;
+        readonly guests: GuestRegistry;
+        onPublish(hook: (world: World) => void): () => void;
+    };
+    /** The FORWARDING session seam — the target swaps per doc open/close. */
+    readonly session?: () => BehaviorSession | undefined;
+    /**
+     * The presence seam. Absent (or returning undefined) leaves every ephemeral
+     * behavior DORMANT — installed, costing nothing, publishing nothing. That is
+     * honest state, not a failure: a presence-less engine has no peer to be.
+     */
+    readonly presence?: () => BehaviorPresence | undefined;
+    readonly onLog?: (behavior: string, message: string, rest: readonly unknown[]) => void;
+    /**
+     * A contained hook fault. Defaults to `console.error`. Hosts route this: a
+     * quarantined instance in a derived behavior means part of the document
+     * silently stops updating, which reads to a user as a broken document.
+     */
+    readonly onFault?: (behavior: string, hook: string, entity: Entity | undefined, err: unknown) => void;
+}
+export interface BehaviorStatus {
+    readonly name: string;
+    readonly store: string;
+    readonly phase: string;
+    readonly instances: number;
+    /** Instances quarantined by repeated hook throws (BF-D18). */
+    readonly failed: number;
+    readonly ticking: number;
+    readonly suspended: boolean;
+}
+export interface BehaviorRuntime {
+    /** Compile + install a behavior. Returns an uninstaller. */
+    register(b: AnyBehaviorDef): () => void;
+    registered(): readonly AnyBehaviorDef[];
+    /** Runtime/ephemeral attach from OUTSIDE a hook (the facade surface). */
+    attach(e: Entity, b: AnyBehaviorDef, data?: Record<string, unknown>): void;
+    detach(e: Entity, b: AnyBehaviorDef): void;
+    has(e: Entity, b: AnyBehaviorDef): boolean;
+    read(e: Entity, b: AnyBehaviorDef): Record<string, unknown> | undefined;
+    list(): readonly BehaviorStatus[];
+    dispose(): void;
+}
+export declare function createBehaviorRuntime(opts: BehaviorRuntimeOpts): BehaviorRuntime;

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

@@ -0,0 +1,312 @@
+/**
+ * `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, 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>>;
+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 {};