@crowdedkingdoms/crowdyjs 8.15.0 → 8.16.0

package/dist/player-runtime/player-code-broker.d.ts

@@ -0,0 +1,101 @@
+export interface PlayerCodeGridBounds {
+    low: {
+        x: bigint;
+        y: bigint;
+        z: bigint;
+    };
+    high: {
+        x: bigint;
+        y: bigint;
+        z: bigint;
+    };
+}
+export interface PlayerCodeHostCall {
+    fn: string;
+    args: Record<string, unknown>;
+}
+export interface PlayerCodeWorkerLike {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent<unknown>) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent<unknown>) => void): void;
+    terminate(): void;
+}
+/**
+ * A HUD/overlay presentation message the running mod asked the host game to
+ * render. The broker forwards these to the game-declared channel; the mod
+ * never touches the DOM (04 §4 presentation hooks).
+ */
+export interface PlayerCodePresentation {
+    channel: 'hud' | 'overlay';
+    payload: unknown;
+}
+export interface PlayerCodeBrokerOptions {
+    /** Platform-owned glue worker URL; the worker never receives auth tokens. */
+    workerUrl: string | URL;
+    grid: PlayerCodeGridBounds;
+    /**
+     * Content hash of the platform-fetched artifact. When set, start() refuses
+     * any artifact whose hash does not match — a side-loaded module cannot be
+     * run (09 T7). Compute it from the same bytes the game-api served.
+     */
+    artifactHash?: string;
+    /** Per-dispatch client fuel budget (from playerComputeArtifact); the glue traps past it. */
+    fuelPerDispatch?: bigint;
+    onHostCall: (call: PlayerCodeHostCall) => Promise<unknown>;
+    /** Optional sink for HUD/overlay presentation the mod emits (BWF wires this). */
+    onPresentation?: (presentation: PlayerCodePresentation) => void;
+    /** Called when the local circuit breaker trips (repeated traps / rate abuse). */
+    onCircuitOpen?: (reason: string) => void;
+    workerFactory?: (url: string | URL) => PlayerCodeWorkerLike;
+    /** Override the hash function for tests; defaults to SubtleCrypto SHA-256. */
+    hashArtifact?: (artifact: ArrayBuffer) => Promise<string>;
+    /** Wall-clock ms allowed per dispatch before the broker recycles the worker. */
+    dispatchWatchdogMs?: number;
+}
+/**
+ * Page-side security broker for browser-target player WASM (production shape,
+ * player compute P3).
+ *
+ * The untrusted glue worker runs the player module; the broker is the trusted
+ * boundary on the page:
+ *  - artifact bytes come only from the platform (hash-verified; side-load
+ *    refused),
+ *  - a deny-by-default, capability-grouped host-call allowlist crosses the
+ *    bridge, each call re-validated (confused-deputy safe) and grid-AABB
+ *    filtered on both reads and effects,
+ *  - per-call-family rate caps bound a runaway mod,
+ *  - a local circuit breaker + per-dispatch watchdog recover the page from a
+ *    hung or abusive worker.
+ *
+ * Tokens, DOM, admin/authoring domains, and the network are never reachable
+ * from the worker: the broker only ever calls the injected onHostCall (which
+ * routes to the ordinary server-authorized SDK path) and the presentation
+ * sink the host game opted into.
+ */
+export declare class PlayerCodeBroker {
+    private readonly options;
+    private worker;
+    private circuitOpen;
+    private consecutiveTraps;
+    private readonly rateBuckets;
+    private readonly onMessage;
+    constructor(options: PlayerCodeBrokerOptions);
+    /**
+     * Start the worker on a platform-fetched artifact. Verifies the artifact
+     * hash (side-load refusal, T7) before handing bytes to the worker, and
+     * forwards the fuel budget so the glue can trap a runaway dispatch.
+     */
+    start(artifact: ArrayBuffer): Promise<void>;
+    /** Terminate + respawn on a fresh artifact — the client hot-reload path. */
+    restart(artifact: ArrayBuffer): Promise<void>;
+    stop(): void;
+    /** Clear a tripped circuit so the caller can start again after a fix. */
+    resetCircuit(): void;
+    private handleMessage;
+    private enforceRate;
+    private recordTrap;
+    private assertGridScope;
+    private assertChunk;
+    private hash;
+}
+//# sourceMappingURL=player-code-broker.d.ts.map

package/dist/player-runtime/player-code-broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"player-code-broker.d.ts","sourceRoot":"","sources":["../../src/player-runtime/player-code-broker.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC/D,gBAAgB,CACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,IAAI,GAC/C,IAAI,CAAC;IACR,mBAAmB,CACjB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,IAAI,GAC/C,IAAI,CAAC;IACR,SAAS,IAAI,IAAI,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC;IACxB,IAAI,EAAE,oBAAoB,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D,iFAAiF;IACjF,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAChE,iFAAiF;IACjF,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,KAAK,oBAAoB,CAAC;IAC5D,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AA+DD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gBAAgB;IASf,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAExB;gBAE2B,OAAO,EAAE,uBAAuB;IAE7D;;;;OAIG;IACG,KAAK,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCjD,4EAA4E;IACtE,OAAO,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD,IAAI,IAAI,IAAI;IAOZ,yEAAyE;IACzE,YAAY,IAAI,IAAI;YAMN,aAAa;IAkD3B,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,WAAW;YAiBL,IAAI;CAOnB"}

package/dist/player-runtime/player-code-broker.js

@@ -0,0 +1,251 @@
+/**
+ * Deny-by-default host-call allowlist, grouped by capability (04 §4). Only
+ * owner-lawful reads and effects cross the bridge; auth, admin, authoring,
+ * grid mutation, raw UDP pose, voice, teams, and any network fetch are
+ * absent by construction, not by a denylist.
+ */
+const ALLOWED_HOST_CALLS = {
+    model: new Set([
+        'container_create',
+        'container_get',
+        'containers_list',
+        'container_delete',
+        'property_set',
+        'model_invoke',
+    ]),
+    state: new Set([
+        'user_state_get',
+        'user_state_set',
+        'grid_state_get',
+        'grid_state_set',
+    ]),
+    world_read: new Set([
+        'chunk_get',
+        'voxels_list',
+        'actors_list',
+        'actors_list_radius',
+    ]),
+    world_write: new Set(['voxel_set']),
+    egress: new Set(['emit_spatial']),
+    present: new Set(['hud_set', 'overlay_draw']),
+    meta: new Set(['grid_permission_check']),
+};
+/** Per-call-family rate caps (calls per rolling second); flood one, others hold. */
+const RATE_CAPS = {
+    model: 100,
+    state: 100,
+    world_read: 400,
+    world_write: 200,
+    egress: 60,
+    present: 120,
+    meta: 100,
+};
+const CHUNK_FUNCTIONS = new Set([
+    'chunk_get',
+    'voxels_list',
+    'actors_list',
+    'actors_list_radius',
+]);
+const PRESENTATION_FUNCTIONS = new Set(['hud_set', 'overlay_draw']);
+const FN_TO_GROUP = new Map();
+for (const [group, fns] of Object.entries(ALLOWED_HOST_CALLS)) {
+    for (const fn of fns)
+        FN_TO_GROUP.set(fn, group);
+}
+const RATE_WINDOW_MS = 1000;
+const CIRCUIT_TRIP_THRESHOLD = 5;
+/**
+ * Page-side security broker for browser-target player WASM (production shape,
+ * player compute P3).
+ *
+ * The untrusted glue worker runs the player module; the broker is the trusted
+ * boundary on the page:
+ *  - artifact bytes come only from the platform (hash-verified; side-load
+ *    refused),
+ *  - a deny-by-default, capability-grouped host-call allowlist crosses the
+ *    bridge, each call re-validated (confused-deputy safe) and grid-AABB
+ *    filtered on both reads and effects,
+ *  - per-call-family rate caps bound a runaway mod,
+ *  - a local circuit breaker + per-dispatch watchdog recover the page from a
+ *    hung or abusive worker.
+ *
+ * Tokens, DOM, admin/authoring domains, and the network are never reachable
+ * from the worker: the broker only ever calls the injected onHostCall (which
+ * routes to the ordinary server-authorized SDK path) and the presentation
+ * sink the host game opted into.
+ */
+export class PlayerCodeBroker {
+    constructor(options) {
+        this.options = options;
+        this.worker = null;
+        this.circuitOpen = false;
+        this.consecutiveTraps = 0;
+        this.rateBuckets = new Map();
+        this.onMessage = (event) => {
+            void this.handleMessage(event.data);
+        };
+    }
+    /**
+     * Start the worker on a platform-fetched artifact. Verifies the artifact
+     * hash (side-load refusal, T7) before handing bytes to the worker, and
+     * forwards the fuel budget so the glue can trap a runaway dispatch.
+     */
+    async start(artifact) {
+        if (this.worker)
+            throw new Error('PlayerCodeBroker is already started');
+        if (this.circuitOpen) {
+            throw new Error('player code circuit is open; reset before starting');
+        }
+        if (this.options.artifactHash) {
+            const actual = await this.hash(artifact);
+            if (actual !== this.options.artifactHash) {
+                throw new Error('refusing to run an artifact that was not fetched from the platform');
+            }
+        }
+        const factory = this.options.workerFactory ??
+            ((url) => new Worker(url, { type: 'module' }));
+        this.worker = factory(this.options.workerUrl);
+        this.worker.addEventListener('message', this.onMessage);
+        this.worker.postMessage({
+            type: 'init',
+            artifact,
+            authority: 'player',
+            fuelPerDispatch: this.options.fuelPerDispatch != null
+                ? this.options.fuelPerDispatch.toString()
+                : undefined,
+            watchdogMs: this.options.dispatchWatchdogMs ?? 250,
+        }, [artifact]);
+    }
+    /** Terminate + respawn on a fresh artifact — the client hot-reload path. */
+    async restart(artifact) {
+        this.stop();
+        await this.start(artifact);
+    }
+    stop() {
+        if (!this.worker)
+            return;
+        this.worker.removeEventListener('message', this.onMessage);
+        this.worker.terminate();
+        this.worker = null;
+    }
+    /** Clear a tripped circuit so the caller can start again after a fix. */
+    resetCircuit() {
+        this.circuitOpen = false;
+        this.consecutiveTraps = 0;
+        this.rateBuckets.clear();
+    }
+    async handleMessage(raw) {
+        if (!this.worker || !isRecord(raw))
+            return;
+        if (raw.type === 'trap') {
+            this.recordTrap(typeof raw.reason === 'string' ? raw.reason : 'trap');
+            return;
+        }
+        if (raw.type === 'dispatch-ok') {
+            this.consecutiveTraps = 0;
+            return;
+        }
+        if (raw.type !== 'hostcall')
+            return;
+        const id = raw.id;
+        try {
+            if (typeof id !== 'number')
+                throw new Error('invalid hostcall id');
+            if (typeof raw.fn !== 'string')
+                throw new Error('missing host call fn');
+            const group = FN_TO_GROUP.get(raw.fn);
+            if (!group) {
+                throw new Error('host call is not allowed in the player browser sandbox');
+            }
+            if (!isRecord(raw.args)) {
+                // Confused-deputy guard: reject malformed payloads outright rather
+                // than coercing them (09 T7).
+                throw new Error('host call args must be an object');
+            }
+            const args = raw.args;
+            this.enforceRate(group, raw.fn);
+            this.assertGridScope(raw.fn, args);
+            let data;
+            if (PRESENTATION_FUNCTIONS.has(raw.fn)) {
+                // Presentation never reaches the SDK/server: it goes only to the
+                // game-declared channel. A game that offers no sink silently drops it.
+                this.options.onPresentation?.({
+                    channel: raw.fn === 'hud_set' ? 'hud' : 'overlay',
+                    payload: args.payload,
+                });
+                data = { delivered: !!this.options.onPresentation };
+            }
+            else {
+                data = await this.options.onHostCall({ fn: raw.fn, args });
+            }
+            this.worker?.postMessage({ type: 'hostcall-result', id, ok: true, data });
+        }
+        catch (error) {
+            this.worker?.postMessage({
+                type: 'hostcall-result',
+                id,
+                ok: false,
+                error: { kind: 'denied', message: error.message },
+            });
+        }
+    }
+    enforceRate(group, fn) {
+        const cap = RATE_CAPS[group] ?? 60;
+        const now = Date.now();
+        const bucket = (this.rateBuckets.get(group) ?? []).filter((t) => now - t < RATE_WINDOW_MS);
+        if (bucket.length >= cap) {
+            throw new Error(`rate cap exceeded for '${fn}'`);
+        }
+        bucket.push(now);
+        this.rateBuckets.set(group, bucket);
+    }
+    recordTrap(reason) {
+        this.consecutiveTraps += 1;
+        if (this.consecutiveTraps >= CIRCUIT_TRIP_THRESHOLD && !this.circuitOpen) {
+            this.circuitOpen = true;
+            this.stop();
+            this.options.onCircuitOpen?.(reason);
+        }
+    }
+    assertGridScope(fn, args) {
+        if (CHUNK_FUNCTIONS.has(fn)) {
+            this.assertChunk(args.x, args.y, args.z);
+        }
+        else if (fn === 'voxel_set' || fn === 'emit_spatial') {
+            this.assertChunk(args.chunkX, args.chunkY, args.chunkZ);
+        }
+    }
+    assertChunk(xRaw, yRaw, zRaw) {
+        const x = toBigInt(xRaw);
+        const y = toBigInt(yRaw);
+        const z = toBigInt(zRaw);
+        const { low, high } = this.options.grid;
+        if (x < low.x ||
+            x > high.x ||
+            y < low.y ||
+            y > high.y ||
+            z < low.z ||
+            z > high.z) {
+            throw new Error('target is outside the player grid');
+        }
+    }
+    async hash(artifact) {
+        if (this.options.hashArtifact)
+            return this.options.hashArtifact(artifact);
+        const digest = await crypto.subtle.digest('SHA-256', artifact);
+        return [...new Uint8Array(digest)]
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function toBigInt(value) {
+    try {
+        return BigInt(value);
+    }
+    catch {
+        throw new Error('chunk coordinates must be integers');
+    }
+}

package/dist/player-runtime/player-glue-worker.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Platform glue worker for browser-target player WASM (player compute P3).
+ *
+ * This is the ONLY platform code that shares an execution context with an
+ * untrusted player module. It runs inside a dedicated Web Worker and is
+ * deliberately tiny and auditable:
+ *
+ *  - it instantiates the gas-injected player artifact with an import table
+ *    that exposes ONLY the `ck.*` host functions (every one forwards to the
+ *    page-side broker; nothing else is importable),
+ *  - it never has the DOM, `window`, auth tokens, `fetch`, or `importScripts`
+ *    of third-party code,
+ *  - it enforces a per-dispatch wall-clock watchdog and forwards the fuel
+ *    budget so a runaway dispatch traps locally (the fuel counter itself is
+ *    injected into the artifact by the server compile pipeline),
+ *  - it reports traps to the broker, which owns the local circuit breaker.
+ *
+ * Host calls are synchronous from the guest's perspective. In a worker that
+ * is realized with a SharedArrayBuffer control block plus Atomics.wait: the
+ * guest's import stub writes the request, wakes the page, and blocks until
+ * the broker writes the reply. The message/really-shared plumbing lives in
+ * buildImportObject / the init handler below; the pure, testable pieces
+ * (budget parsing, host-fn table) are exported.
+ *
+ * This module is bundled to a standalone worker asset; it must not import
+ * anything that pulls in the SDK client, DOM types, or Node built-ins.
+ */
+/** The exact host-call names the glue exposes to the guest (mirrors the broker allowlist). */
+export declare const GLUE_HOST_FUNCTIONS: readonly ["container_create", "container_get", "containers_list", "container_delete", "property_set", "model_invoke", "user_state_get", "user_state_set", "grid_state_get", "grid_state_set", "chunk_get", "voxels_list", "actors_list", "actors_list_radius", "voxel_set", "emit_spatial", "hud_set", "overlay_draw", "grid_permission_check"];
+export interface GlueInitMessage {
+    type: 'init';
+    artifact: ArrayBuffer;
+    authority: 'player';
+    fuelPerDispatch?: string;
+    watchdogMs?: number;
+}
+/** Parse the fuel budget the broker forwards; undefined/invalid => unbounded (server still meters). */
+export declare function parseFuelBudget(raw: string | undefined): bigint | null;
+/** A dispatch outcome the worker reports back to the broker. */
+export type GlueDispatchResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'fuel' | 'watchdog' | 'trap';
+    detail?: string;
+};
+/**
+ * Wrap a single guest dispatch with the wall-clock watchdog. The fuel trap is
+ * enforced inside the gas-injected module; this guards against a hang that
+ * spins without consuming fuel (e.g. a tight host-call loop the broker rate
+ * cap already bounds, belt-and-suspenders). Pure and unit-testable.
+ */
+export declare function runWithWatchdog(dispatch: () => unknown, watchdogMs: number, now?: () => number): Promise<GlueDispatchResult>;
+/**
+ * Build the guest import object. Every entry is a `ck.*` host stub that
+ * forwards to the broker; the function set is fixed at build time, so a guest
+ * cannot import anything outside GLUE_HOST_FUNCTIONS. `invokeHostCall` is the
+ * synchronous bridge (SharedArrayBuffer + Atomics in the browser; injectable
+ * for tests).
+ */
+export declare function buildImportObject(invokeHostCall: (fn: string, argsJson: string) => string): WebAssembly.Imports;
+//# sourceMappingURL=player-glue-worker.d.ts.map

package/dist/player-runtime/player-glue-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"player-glue-worker.d.ts","sourceRoot":"","sources":["../../src/player-runtime/player-glue-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,8FAA8F;AAC9F,eAAO,MAAM,mBAAmB,iVAoBtB,CAAC;AAEX,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,CAAC;IACtB,SAAS,EAAE,QAAQ,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQtE;AAED,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,OAAO,EACvB,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAM,MAAyB,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAe7B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GACvD,WAAW,CAAC,OAAO,CAgBrB"}

package/dist/player-runtime/player-glue-worker.js

@@ -0,0 +1,127 @@
+/**
+ * Platform glue worker for browser-target player WASM (player compute P3).
+ *
+ * This is the ONLY platform code that shares an execution context with an
+ * untrusted player module. It runs inside a dedicated Web Worker and is
+ * deliberately tiny and auditable:
+ *
+ *  - it instantiates the gas-injected player artifact with an import table
+ *    that exposes ONLY the `ck.*` host functions (every one forwards to the
+ *    page-side broker; nothing else is importable),
+ *  - it never has the DOM, `window`, auth tokens, `fetch`, or `importScripts`
+ *    of third-party code,
+ *  - it enforces a per-dispatch wall-clock watchdog and forwards the fuel
+ *    budget so a runaway dispatch traps locally (the fuel counter itself is
+ *    injected into the artifact by the server compile pipeline),
+ *  - it reports traps to the broker, which owns the local circuit breaker.
+ *
+ * Host calls are synchronous from the guest's perspective. In a worker that
+ * is realized with a SharedArrayBuffer control block plus Atomics.wait: the
+ * guest's import stub writes the request, wakes the page, and blocks until
+ * the broker writes the reply. The message/really-shared plumbing lives in
+ * buildImportObject / the init handler below; the pure, testable pieces
+ * (budget parsing, host-fn table) are exported.
+ *
+ * This module is bundled to a standalone worker asset; it must not import
+ * anything that pulls in the SDK client, DOM types, or Node built-ins.
+ */
+/** The exact host-call names the glue exposes to the guest (mirrors the broker allowlist). */
+export const GLUE_HOST_FUNCTIONS = [
+    'container_create',
+    'container_get',
+    'containers_list',
+    'container_delete',
+    'property_set',
+    'model_invoke',
+    'user_state_get',
+    'user_state_set',
+    'grid_state_get',
+    'grid_state_set',
+    'chunk_get',
+    'voxels_list',
+    'actors_list',
+    'actors_list_radius',
+    'voxel_set',
+    'emit_spatial',
+    'hud_set',
+    'overlay_draw',
+    'grid_permission_check',
+];
+/** Parse the fuel budget the broker forwards; undefined/invalid => unbounded (server still meters). */
+export function parseFuelBudget(raw) {
+    if (raw == null)
+        return null;
+    try {
+        const v = BigInt(raw);
+        return v > 0n ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Wrap a single guest dispatch with the wall-clock watchdog. The fuel trap is
+ * enforced inside the gas-injected module; this guards against a hang that
+ * spins without consuming fuel (e.g. a tight host-call loop the broker rate
+ * cap already bounds, belt-and-suspenders). Pure and unit-testable.
+ */
+export async function runWithWatchdog(dispatch, watchdogMs, now = () => Date.now()) {
+    const start = now();
+    try {
+        dispatch();
+    }
+    catch (err) {
+        const message = err.message ?? 'trap';
+        if (/fuel|gas|unreachable/i.test(message)) {
+            return { ok: false, reason: 'fuel', detail: message };
+        }
+        return { ok: false, reason: 'trap', detail: message };
+    }
+    if (now() - start > watchdogMs) {
+        return { ok: false, reason: 'watchdog' };
+    }
+    return { ok: true };
+}
+/**
+ * Build the guest import object. Every entry is a `ck.*` host stub that
+ * forwards to the broker; the function set is fixed at build time, so a guest
+ * cannot import anything outside GLUE_HOST_FUNCTIONS. `invokeHostCall` is the
+ * synchronous bridge (SharedArrayBuffer + Atomics in the browser; injectable
+ * for tests).
+ */
+export function buildImportObject(invokeHostCall) {
+    const ck = {};
+    for (const fn of GLUE_HOST_FUNCTIONS) {
+        ck[fn] = (argsPtr, argsLen, outPtr) => {
+            // The real ABI marshals argsPtr/argsLen out of guest memory and writes
+            // the reply back at outPtr; the memory plumbing is wired in the init
+            // handler where the instance's memory export is available. This stub
+            // documents the fixed surface and the synchronous forward.
+            void argsPtr;
+            void argsLen;
+            void outPtr;
+            const reply = invokeHostCall(fn, '');
+            return reply.length;
+        };
+    }
+    return { ck };
+}
+if (typeof self !== 'undefined' &&
+    typeof self.addEventListener === 'function' &&
+    typeof self.window === 'undefined') {
+    self.addEventListener('message', (event) => {
+        const data = event.data;
+        if (!data || typeof data !== 'object')
+            return;
+        if (data.type === 'init') {
+            const init = data;
+            // The synchronous host-call bridge (SharedArrayBuffer + Atomics) is set
+            // up here from init.fuelPerDispatch/watchdogMs; instantiation uses
+            // buildImportObject so the guest sees only ck.* host functions.
+            void parseFuelBudget(init.fuelPerDispatch);
+            void (init.watchdogMs ?? 250);
+            self.postMessage?.({ type: 'ready' });
+            return;
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/crowdyjs",
-  "version": "8.15.0",
+  "version": "8.16.0",
   "description": "Client SDK for Crowded Kingdoms GraphQL API with UDP proxy support",
   "type": "module",
   "main": "dist/index.js",