@vibecook/ice 0.4.0 → 0.7.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,102 @@
+import type { Component, Entity, World } from "@vibecook/strata-ecs";
+import type { GuestLedgerRecord, 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;
+    /**
+     * The EPHEMERAL singleton was quarantined this generation (I17): its facet
+     * is withdrawn and stays withdrawn until a fresh registration. Without this
+     * field a quarantined singleton is indistinguishable from a dormant one —
+     * withdrawal makes the instance depart, so `failed` reads 0. Always false
+     * for durable/runtime behaviors (their quarantine stays visible in `failed`).
+     */
+    readonly quarantined: boolean;
+}
+export interface BehaviorRegistrationOptions {
+    /** Stable host policy key. Explicitly ordered registrations run before unkeyed registrations. */
+    readonly orderKey?: string;
+    /** Prior breaker state, normally persisted by a host across engine generations. */
+    readonly ledger?: GuestLedgerRecord;
+}
+export interface BehaviorRuntime {
+    /** Compile + install a behavior. Returns an uninstaller. */
+    register(b: AnyBehaviorDef, options?: BehaviorRegistrationOptions): () => 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;