@crowdedkingdoms/crowdyjs 17.13.0-dev.1 → 18.0.0-dev.1

package/dist/grid-mods/exec-client-halves.d.ts

@@ -0,0 +1,156 @@
+import type { ExecAPI, ExecClientCapabilitySummary, ExecGridClientMod } from '../domains/exec.js';
+import { type PlayerCodeBrokerOptions, type PlayerCodeGridBounds, type PlayerCodeHostCall, type PlayerCodeLogLine, type PlayerCodePresentation } from '../player-runtime/player-code-broker.js';
+/** The grid a player stands in: its id and chunk box. */
+export type ExecClientHalvesGrid = PlayerCodeGridBounds & {
+    gridId: string;
+};
+/**
+ * One question for the player. `author`: trust every CLIENT half of `authorId` on the grid, at
+ * the hash of their union (`exec.trustAuthor`). `mod`: consent to one CLIENT half at its hash
+ * (`exec.consentClientMod`).
+ */
+export interface ExecClientHalfPrompt {
+    kind: 'author' | 'mod';
+    gridId: string;
+    authorId: string;
+    /** What a yes consents to: the author's `authorCapabilityHash`, or the mod's `capabilityHash`. */
+    capabilityHash: string;
+    /** The summary to show: the author's union, or the one CLIENT half's. */
+    capabilitySummaryJson: string;
+    capabilitySummary: ExecClientCapabilitySummary | null;
+    /** The CLIENT halves a yes covers now. */
+    mods: readonly ExecGridClientMod[];
+}
+/**
+ * Why a CLIENT half stopped: no longer listed (`removed`), a new digest, capability hash or tick
+ * interval (`changed`), listed without the player's consent or trust (`unconsented`), refused by
+ * `filter` (`filtered`), the runner left the grid (`left-grid`) or was stopped (`stopped`), or
+ * the broker's circuit breaker tripped (`circuit-open`).
+ */
+export type ExecClientHalfStopReason = 'removed' | 'changed' | 'unconsented' | 'filtered' | 'left-grid' | 'stopped' | 'circuit-open';
+/** A consent, fetch or start that failed, and when that CLIENT half is tried again. */
+export interface ExecClientHalfError {
+    mod: ExecGridClientMod;
+    stage: 'consent' | 'fetch' | 'start';
+    /**
+     * `not-found`: not served to the player now (every refusal of the artifact, and a trust while
+     * not standing in the grid); `rate-limited`: 12 fetches a minute per player and mod;
+     * `conflict`: the hash moved on; `refused`: the served module was, for bytes that differ from
+     * its digest, an unknown CLIENT ABI or a capability summary that does not parse; `failed`:
+     * anything else.
+     */
+    reason: 'not-found' | 'rate-limited' | 'conflict' | 'refused' | 'failed';
+    error: unknown;
+    /** When the runner fetches or starts it again (epoch ms); absent for a consent. */
+    retryAt?: number;
+}
+/** The part of `PlayerCodeBroker` the runner drives. */
+export interface ExecClientHalfBroker {
+    start(artifact: ArrayBuffer): Promise<void>;
+    stop(): void;
+    /** `PlayerCodeBroker.invoke`: the module's `handle_invoke`. */
+    invoke?(payload: Uint8Array, options?: {
+        timeoutMs?: number;
+    }): Promise<Uint8Array>;
+}
+export interface ExecClientHalvesOptions {
+    exec: Pick<ExecAPI, 'gridClientMods' | 'consentClientMod' | 'trustAuthor' | 'modClientArtifactBytes'>;
+    appId: string;
+    /** The platform glue worker (`@crowdedkingdoms/crowdyjs/player-glue-worker`), same origin. */
+    workerUrl: string | URL;
+    /**
+     * Answers the host calls a CLIENT half makes that the broker does not answer itself, for
+     * example with `createGridHostCalls` over the grid's scope.
+     */
+    onHostCall: (call: PlayerCodeHostCall, mod: ExecGridClientMod) => Promise<unknown>;
+    onPresentation?: (presentation: PlayerCodePresentation, mod: ExecGridClientMod) => void;
+    /**
+     * Each CLIENT half's `crowdy::log` lines, bounded by the broker (see
+     * `PlayerCodeBrokerOptions.onLog`). The text is the mod author's: render it as text.
+     */
+    onLog?: (line: PlayerCodeLogLine, mod: ExecGridClientMod) => void;
+    /**
+     * Asks the player about CLIENT halves they neither consented to nor trust the author of; true
+     * consents. Without it, only what the player already agreed to runs. A declined question is
+     * not asked again on this grid until its hash changes.
+     */
+    confirm?: (prompt: ExecClientHalfPrompt) => boolean | Promise<boolean>;
+    /** `author` (the default): one question per author; `mod`: one per CLIENT half. */
+    ask?: 'author' | 'mod';
+    /** Leaves out the CLIENT halves it returns false for, e.g. the one Crowdy Studio previews. */
+    filter?: (mod: ExecGridClientMod) => boolean;
+    onStarted?: (mod: ExecGridClientMod) => void;
+    onStopped?: (mod: ExecGridClientMod, reason: ExecClientHalfStopReason) => void;
+    onError?: (error: ExecClientHalfError) => void;
+    /** How long a CLIENT half waits after `NOT_FOUND` before it is fetched again. Default 15 s. */
+    notFoundRetryMs?: number;
+    /** How long after `RATE_LIMITED`. Default 60 s, the limit's window. */
+    rateLimitedRetryMs?: number;
+    /** How long after any other failure, refused bytes included. Default 60 s. */
+    failedRetryMs?: number;
+    /** Modules kept by digest, across grids. Default 16. */
+    cacheSize?: number;
+    now?: () => number;
+    brokerFactory?: (options: PlayerCodeBrokerOptions) => ExecClientHalfBroker;
+}
+/**
+ * Runs the CLIENT halves of ck-exec mods that the grid a player stands in serves, the way a game
+ * should: tell it the grid ({@link enterGrid}) and call {@link refresh} on a cadence (every 10 s
+ * or so). Each refresh lists the grid's CLIENT halves (`exec.gridClientMods`), stops the workers
+ * whose mod is gone or whose `modId`, `digest`, `capabilityHash` or tick interval changed, asks
+ * the player once per author (or per CLIENT half) about the rest, fetches each consented one
+ * (`exec.modClientArtifactBytes`, which refuses bytes that differ from their digest) and runs it
+ * in a `PlayerCodeBroker` with `engine: 'ck-exec'`, its fuel budget and tick interval, bounded
+ * to the host calls of the capability summary the player consented to.
+ *
+ * Modules are cached by digest, since a digest never changes its bytes and the artifact query
+ * allows 12 fetches a minute per player and mod. A cached module starts without a fetch, so the
+ * serve checks that query makes (`run_client_code`, standing in the grid) are those of the fetch
+ * that filled the cache; consent and trust are the listing's, on every refresh.
+ *
+ * `NOT_FOUND` (not served to this player now) and `RATE_LIMITED` hold that CLIENT half back for
+ * a while instead of fetching on every refresh.
+ */
+export declare class ExecClientHalves {
+    private readonly options;
+    private grid;
+    private generation;
+    private readonly workers;
+    private readonly cache;
+    private readonly retryAt;
+    private readonly declined;
+    private readonly approved;
+    private inFlight;
+    constructor(options: ExecClientHalvesOptions);
+    /** The grid the player stands in, or null. Any change stops every CLIENT half of the old one. */
+    enterGrid(grid: ExecClientHalvesGrid | null): void;
+    /** The CLIENT halves running now. */
+    get running(): readonly ExecGridClientMod[];
+    /**
+     * One reconcile of the current grid; a call while one runs for the same grid joins it. Rejects
+     * when the grid's CLIENT halves cannot be listed, and what runs keeps running.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Calls the `handle_invoke` export of the running CLIENT half of mod `modId` with `payload`
+     * and resolves with its reply bytes (see `PlayerCodeBroker.invoke`). Rejects when that CLIENT
+     * half is not running.
+     */
+    invoke(modId: string, payload: Uint8Array, options?: {
+        timeoutMs?: number;
+    }): Promise<Uint8Array>;
+    /** Stops every CLIENT half and leaves the grid; the module cache stays. */
+    stop(): void;
+    private reconcile;
+    private stopStale;
+    /** Asks about what the player has not agreed to; true when a consent or trust went through. */
+    private askAbout;
+    private start;
+    private fail;
+    private remember;
+    private wanted;
+    private stopWorker;
+    private stopAll;
+    private now;
+}
+//# sourceMappingURL=exec-client-halves.d.ts.map

package/dist/grid-mods/exec-client-halves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-client-halves.d.ts","sourceRoot":"","sources":["../../src/grid-mods/exec-client-halves.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,2BAA2B,EAC3B,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,yCAAyC,CAAC;AAEjD,yDAAyD;AACzD,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,kGAAkG;IAClG,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,iBAAiB,EAAE,2BAA2B,GAAG,IAAI,CAAC;IACtD,0CAA0C;IAC1C,IAAI,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAChC,SAAS,GACT,SAAS,GACT,aAAa,GACb,UAAU,GACV,WAAW,GACX,SAAS,GACT,cAAc,CAAC;AAEnB,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,iBAAiB,CAAC;IACvB,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACrC;;;;;;OAMG;IACH,MAAM,EAAE,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzE,KAAK,EAAE,OAAO,CAAC;IACf,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI,IAAI,CAAC;IACb,+DAA+D;IAC/D,MAAM,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACrF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,aAAa,GAAG,wBAAwB,CAAC,CAAC;IACtG,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC;IACxB;;;OAGG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,sBAAsB,EAAE,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACxF;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClE;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,mFAAmF;IACnF,GAAG,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IACvB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC;IAC7C,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC7C,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAC;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC/C,+FAA+F;IAC/F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,oBAAoB,CAAC;CAC5E;AA4BD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAgB;IAUf,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,IAAI,CAAqC;IACjD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAA4D;gBAE/C,OAAO,EAAE,uBAAuB;IAE7D,iGAAiG;IACjG,SAAS,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI;IASlD,qCAAqC;IACrC,IAAI,OAAO,IAAI,SAAS,iBAAiB,EAAE,CAE1C;IAED;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAUxB;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAWjG,2EAA2E;IAC3E,IAAI,IAAI,IAAI;YAQE,SAAS;IAuBvB,OAAO,CAAC,SAAS;IAiBjB,+FAA+F;YACjF,QAAQ;YA8ER,KAAK;IAmFnB,OAAO,CAAC,IAAI;IAaZ,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,GAAG;CAGZ"}

package/dist/grid-mods/exec-client-halves.js

@@ -0,0 +1,356 @@
+import { CrowdyGraphQLError, CrowdyProtocolError } from '../errors.js';
+import { PlayerCodeBroker, } from '../player-runtime/player-code-broker.js';
+const identity = (m) => `${m.modId}\u0000${m.digest}\u0000${m.capabilityHash}\u0000${m.tickIntervalMs}`;
+function refusal(error) {
+    if (error instanceof CrowdyProtocolError)
+        return 'refused';
+    if (error instanceof CrowdyGraphQLError) {
+        if (error.code === 'NOT_FOUND')
+            return 'not-found';
+        if (error.code === 'RATE_LIMITED')
+            return 'rate-limited';
+        if (error.code === 'CONFLICT')
+            return 'conflict';
+    }
+    return 'failed';
+}
+/**
+ * Runs the CLIENT halves of ck-exec mods that the grid a player stands in serves, the way a game
+ * should: tell it the grid ({@link enterGrid}) and call {@link refresh} on a cadence (every 10 s
+ * or so). Each refresh lists the grid's CLIENT halves (`exec.gridClientMods`), stops the workers
+ * whose mod is gone or whose `modId`, `digest`, `capabilityHash` or tick interval changed, asks
+ * the player once per author (or per CLIENT half) about the rest, fetches each consented one
+ * (`exec.modClientArtifactBytes`, which refuses bytes that differ from their digest) and runs it
+ * in a `PlayerCodeBroker` with `engine: 'ck-exec'`, its fuel budget and tick interval, bounded
+ * to the host calls of the capability summary the player consented to.
+ *
+ * Modules are cached by digest, since a digest never changes its bytes and the artifact query
+ * allows 12 fetches a minute per player and mod. A cached module starts without a fetch, so the
+ * serve checks that query makes (`run_client_code`, standing in the grid) are those of the fetch
+ * that filled the cache; consent and trust are the listing's, on every refresh.
+ *
+ * `NOT_FOUND` (not served to this player now) and `RATE_LIMITED` hold that CLIENT half back for
+ * a while instead of fetching on every refresh.
+ */
+export class ExecClientHalves {
+    constructor(options) {
+        this.options = options;
+        this.grid = null;
+        this.generation = 0;
+        this.workers = new Map();
+        this.cache = new Map();
+        this.retryAt = new Map();
+        this.declined = new Set();
+        this.approved = new Set();
+        this.inFlight = null;
+    }
+    /** The grid the player stands in, or null. Any change stops every CLIENT half of the old one. */
+    enterGrid(grid) {
+        if (sameGrid(this.grid, grid))
+            return;
+        this.stopAll('left-grid');
+        this.grid = grid ? { ...grid } : null;
+        this.generation++;
+        this.declined.clear();
+        this.approved.clear();
+    }
+    /** The CLIENT halves running now. */
+    get running() {
+        return [...this.workers.values()].filter((w) => w.started).map((w) => w.mod);
+    }
+    /**
+     * One reconcile of the current grid; a call while one runs for the same grid joins it. Rejects
+     * when the grid's CLIENT halves cannot be listed, and what runs keeps running.
+     */
+    refresh() {
+        if (this.inFlight?.generation === this.generation)
+            return this.inFlight.done;
+        const generation = this.generation;
+        const done = this.reconcile(generation).finally(() => {
+            if (this.inFlight?.done === done)
+                this.inFlight = null;
+        });
+        this.inFlight = { generation, done };
+        return done;
+    }
+    /**
+     * Calls the `handle_invoke` export of the running CLIENT half of mod `modId` with `payload`
+     * and resolves with its reply bytes (see `PlayerCodeBroker.invoke`). Rejects when that CLIENT
+     * half is not running.
+     */
+    invoke(modId, payload, options) {
+        const worker = this.workers.get(modId);
+        if (!worker?.started) {
+            return Promise.reject(new Error(`the CLIENT half of mod ${modId} is not running`));
+        }
+        if (!worker.broker.invoke) {
+            return Promise.reject(new Error('this broker cannot invoke its module'));
+        }
+        return worker.broker.invoke(payload, options);
+    }
+    /** Stops every CLIENT half and leaves the grid; the module cache stays. */
+    stop() {
+        this.stopAll('stopped');
+        this.grid = null;
+        this.generation++;
+        this.declined.clear();
+        this.approved.clear();
+    }
+    async reconcile(generation) {
+        const grid = this.grid;
+        if (!grid)
+            return;
+        const { exec, appId } = this.options;
+        const current = () => generation === this.generation;
+        let listed = await exec.gridClientMods(appId, grid.gridId);
+        if (!current())
+            return;
+        this.stopStale(listed);
+        if (await this.askAbout(listed, grid, current)) {
+            if (!current())
+                return;
+            listed = await exec.gridClientMods(appId, grid.gridId);
+            if (!current())
+                return;
+            this.stopStale(listed);
+        }
+        for (const mod of listed) {
+            if (!current())
+                return;
+            if (!this.wanted(mod) || !(mod.callerConsented || mod.callerTrustsAuthor))
+                continue;
+            if (this.workers.has(mod.modId))
+                continue;
+            if ((this.retryAt.get(identity(mod)) ?? 0) > this.now())
+                continue;
+            await this.start(mod, grid, current);
+        }
+    }
+    stopStale(listed) {
+        const byId = new Map(listed.map((m) => [m.modId, m]));
+        for (const [modId, worker] of [...this.workers]) {
+            const next = byId.get(modId);
+            const reason = !next
+                ? 'removed'
+                : identity(next) !== identity(worker.mod)
+                    ? 'changed'
+                    : !this.wanted(next)
+                        ? 'filtered'
+                        : !(next.callerConsented || next.callerTrustsAuthor)
+                            ? 'unconsented'
+                            : null;
+            if (reason)
+                this.stopWorker(modId, reason);
+        }
+    }
+    /** Asks about what the player has not agreed to; true when a consent or trust went through. */
+    async askAbout(listed, grid, current) {
+        const pending = listed.filter((m) => this.wanted(m) && !m.callerConsented && !m.callerTrustsAuthor);
+        if (pending.length === 0)
+            return false;
+        const prompts = [];
+        if ((this.options.ask ?? 'author') === 'author') {
+            for (const authorId of new Set(pending.map((m) => m.authorId))) {
+                const theirs = listed.filter((m) => m.authorId === authorId);
+                const [first] = theirs;
+                prompts.push({
+                    key: `author\u0000${authorId}\u0000${first.authorCapabilityHash}`,
+                    prompt: {
+                        kind: 'author',
+                        gridId: grid.gridId,
+                        authorId,
+                        capabilityHash: first.authorCapabilityHash,
+                        capabilitySummaryJson: first.authorCapabilitySummaryJson,
+                        capabilitySummary: first.authorCapabilitySummary,
+                        mods: theirs,
+                    },
+                });
+            }
+        }
+        else {
+            for (const mod of pending) {
+                prompts.push({
+                    key: `mod\u0000${mod.modId}\u0000${mod.capabilityHash}`,
+                    prompt: {
+                        kind: 'mod',
+                        gridId: grid.gridId,
+                        authorId: mod.authorId,
+                        capabilityHash: mod.capabilityHash,
+                        capabilitySummaryJson: mod.capabilitySummaryJson,
+                        capabilitySummary: mod.capabilitySummary,
+                        mods: [mod],
+                    },
+                });
+            }
+        }
+        let agreed = false;
+        for (const { key, prompt } of prompts) {
+            if (!current())
+                return agreed;
+            if (this.declined.has(key))
+                continue;
+            if (!this.approved.has(key)) {
+                if (!this.options.confirm)
+                    continue;
+                const yes = await this.options.confirm(prompt);
+                if (!current())
+                    return agreed;
+                if (!yes) {
+                    this.declined.add(key);
+                    continue;
+                }
+                // Kept until it goes through: a trust refused while the player's presence is not yet
+                // registered is retried on the next refresh without asking again.
+                this.approved.add(key);
+            }
+            try {
+                const { exec, appId } = this.options;
+                if (prompt.kind === 'author') {
+                    await exec.trustAuthor(appId, grid.gridId, prompt.authorId, prompt.capabilityHash);
+                }
+                else {
+                    await exec.consentClientMod(appId, prompt.mods[0].modId, prompt.capabilityHash);
+                }
+                this.approved.delete(key);
+                agreed = true;
+            }
+            catch (error) {
+                const reason = refusal(error);
+                // The hash moved on: the next listing brings the new one, and a new question.
+                if (reason === 'conflict')
+                    this.approved.delete(key);
+                this.options.onError?.({ mod: prompt.mods[0], stage: 'consent', reason, error });
+            }
+        }
+        return agreed;
+    }
+    async start(mod, grid, current) {
+        // What the player consented to, and what the served artifact itself lists, bound the
+        // module's host calls in the broker.
+        const consented = mod.capabilitySummary?.hostFunctions;
+        if (!Array.isArray(consented)) {
+            this.fail(mod, 'start', new CrowdyProtocolError({
+                message: `CLIENT half of mod ${mod.modId}: its capability summary does not parse`,
+            }));
+            return;
+        }
+        let module = this.cache.get(mod.digest);
+        if (module) {
+            this.cache.delete(mod.digest);
+            this.cache.set(mod.digest, module);
+        }
+        else {
+            try {
+                const a = await this.options.exec.modClientArtifactBytes(this.options.appId, mod.modId);
+                module = {
+                    bytes: a.bytes,
+                    fuelPerDispatch: a.fuelPerDispatch,
+                    hostFunctions: a.capabilitySummary.hostFunctions,
+                };
+                this.remember(a.digest, module);
+                if (!current())
+                    return;
+                // Changed between the listing and the fetch: the next listing starts the new one.
+                if (a.digest !== mod.digest ||
+                    a.capabilityHash !== mod.capabilityHash ||
+                    a.tickIntervalMs !== mod.tickIntervalMs) {
+                    return;
+                }
+            }
+            catch (error) {
+                if (!current())
+                    return;
+                this.fail(mod, 'fetch', error);
+                return;
+            }
+        }
+        const served = module.hostFunctions;
+        const broker = (this.options.brokerFactory ?? ((o) => new PlayerCodeBroker(o)))({
+            engine: 'ck-exec',
+            workerUrl: this.options.workerUrl,
+            grid: { low: grid.low, high: grid.high, gridId: grid.gridId },
+            moduleName: mod.name,
+            artifactHash: mod.digest,
+            fuelPerDispatch: module.fuelPerDispatch,
+            tickIntervalMs: mod.tickIntervalMs,
+            consentedHostCalls: consented.filter((fn) => served.includes(fn)),
+            onHostCall: (call) => this.options.onHostCall(call, mod),
+            onPresentation: (presentation) => this.options.onPresentation?.(presentation, mod),
+            ...(this.options.onLog ? { onLog: (line) => this.options.onLog?.(line, mod) } : {}),
+            onCircuitOpen: () => {
+                if (this.workers.get(mod.modId)?.broker !== broker)
+                    return;
+                this.retryAt.set(identity(mod), this.now() + (this.options.failedRetryMs ?? 60000));
+                this.stopWorker(mod.modId, 'circuit-open');
+            },
+        });
+        const worker = { mod, broker, started: false };
+        this.workers.set(mod.modId, worker);
+        try {
+            await broker.start(module.bytes);
+        }
+        catch (error) {
+            if (this.workers.get(mod.modId) !== worker)
+                return;
+            this.workers.delete(mod.modId);
+            broker.stop();
+            if (current())
+                this.fail(mod, 'start', error);
+            return;
+        }
+        if (this.workers.get(mod.modId) !== worker)
+            return;
+        worker.started = true;
+        this.options.onStarted?.(mod);
+    }
+    fail(mod, stage, error) {
+        const reason = refusal(error);
+        const wait = reason === 'not-found'
+            ? (this.options.notFoundRetryMs ?? 15000)
+            : reason === 'rate-limited'
+                ? (this.options.rateLimitedRetryMs ?? 60000)
+                : (this.options.failedRetryMs ?? 60000);
+        const retryAt = this.now() + wait;
+        this.retryAt.set(identity(mod), retryAt);
+        this.options.onError?.({ mod, stage, reason, error, retryAt });
+    }
+    remember(digest, module) {
+        this.cache.set(digest, module);
+        const limit = Math.max(1, this.options.cacheSize ?? 16);
+        for (const oldest of this.cache.keys()) {
+            if (this.cache.size <= limit)
+                break;
+            this.cache.delete(oldest);
+        }
+    }
+    wanted(mod) {
+        return this.options.filter ? this.options.filter(mod) : true;
+    }
+    stopWorker(modId, reason) {
+        const worker = this.workers.get(modId);
+        if (!worker)
+            return;
+        this.workers.delete(modId);
+        worker.broker.stop();
+        if (worker.started)
+            this.options.onStopped?.(worker.mod, reason);
+    }
+    stopAll(reason) {
+        for (const modId of [...this.workers.keys()])
+            this.stopWorker(modId, reason);
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+}
+function sameGrid(a, b) {
+    if (!a || !b)
+        return a === b;
+    return (a.gridId === b.gridId &&
+        a.low.x === b.low.x &&
+        a.low.y === b.low.y &&
+        a.low.z === b.low.z &&
+        a.high.x === b.high.x &&
+        a.high.y === b.high.y &&
+        a.high.z === b.high.z);
+}

package/dist/grid-mods/grid-host-calls.d.ts

@@ -1,19 +1,32 @@
-import type { GridScope } from '../grid-scope.js';
+import type { GridChunk, GridScope } from '../grid-scope.js';
 import type { PlayerCodeHostCall } from '../player-runtime/player-code-broker.js';
+import type { AvatarsAPI } from '../domains/avatars.js';
 import type { ChunksAPI } from '../domains/chunks.js';
 import type { VoxelsAPI } from '../domains/voxels.js';
 import type { StateAPI } from '../domains/state.js';
-import type { GameModelAPI } from '../domains/gameModel.js';
 /**
- * Game-local fast paths. A game that already holds the world in memory (a
- * chunk store, an actor store) answers reads from there instead of a round
- * trip; anything it leaves out falls through to the server path.
+ * Game-local fast paths and knowledge. A game that already holds the world in memory (a chunk
+ * store, an actor store) answers reads from there instead of a round trip; anything it leaves
+ * out falls through to the server path. The calls only the game can answer (`actors_list*`,
+ * `avatar_state_get`, `grid_permission_check`, `pointer_clicks`) are refused without their
+ * hook.
  */
 export interface GridHostLocal {
     chunkVoxels?(x: bigint, y: bigint, z: bigint): {
         voxelsBase64: string | null;
     } | null;
     actorsInChunk?(x: bigint, y: bigint, z: bigint): Array<Record<string, unknown>>;
+    /**
+     * The chunk of the avatar's live actor, from the game's actor store, or null when the game
+     * sees none. `avatar_state_get` answers only for an avatar whose actor is inside the grid.
+     */
+    avatarChunk?(avatarId: string): GridChunk | null | undefined | Promise<GridChunk | null | undefined>;
+    /**
+     * The runtime permission keys the visiting player holds on this grid, as the game knows them
+     * (where Crowdy Studio's `targetPermissions` come from). `grid_permission_check` answers from
+     * these, for that player and this grid only; the server still enforces the permissions.
+     */
+    gridPermissionKeys?(): Iterable<string> | Promise<Iterable<string>>;
     setVoxel?(input: {
         chunk: {
             x: number;
@@ -36,15 +49,15 @@ export interface GridHostCallsOptions {
         chunks: ChunksAPI;
         voxels: VoxelsAPI;
         state: StateAPI;
-        gameModel: GameModelAPI;
+        /** For `avatar_state_get`, a public read (`avatarAppState`). */
+        avatars?: Pick<AvatarsAPI, 'appState'>;
     };
     local?: GridHostLocal;
     /**
-     * Let mods call Studio model functions as the player (`model_invoke`, the
-     * ordinary player authority path). Off by default: a game opts in when its
-     * functions are meant to be scriptable by visitors' mods.
+     * The visiting player's user id. `grid_permission_check` answers only about them, so without
+     * it the call is refused.
      */
-    allowModelInvoke?: boolean;
+    userId?: string;
     /**
      * Channels a mod may post to. Default: the grid's own channels only (the
      * server rule for grid code). A game may widen it to channels the player
@@ -60,11 +73,12 @@ export declare class GridHostCallRefused extends Error {
     constructor(fn: string, reason?: string);
 }
 /**
- * The page-side answer to every CLIENT host call in the platform catalog,
- * through ordinary CrowdyJS confined to one grid (DN-10 §4). Hand the result
- * to `PlayerCodeBroker({ onHostCall })`; the broker has already applied the
- * allowlist, rate caps and chunk clamps, and answers `grid_info`, `emit_event`,
- * `hud_set` and `overlay_draw` itself.
+ * The page-side answer to a CLIENT half's host calls (`EXEC_CLIENT_HOST_CALLS`,
+ * what crowdy-client-sdk wraps), through ordinary CrowdyJS confined to one grid
+ * (DN-10 §4). Hand the result to `PlayerCodeBroker({ onHostCall })`; the broker
+ * has already applied the allowlist, the player's consent, rate caps and chunk
+ * clamps, and answers `grid_info`, `emit_event`, `hud_set` and `overlay_draw`
+ * itself.
  */
 export declare function createGridHostCalls(options: GridHostCallsOptions): (call: PlayerCodeHostCall) => Promise<unknown>;
 //# sourceMappingURL=grid-host-calls.d.ts.map

package/dist/grid-mods/grid-host-calls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grid-host-calls.d.ts","sourceRoot":"","sources":["../../src/grid-mods/grid-host-calls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;QAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACtF,aAAa,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,QAAQ,CAAC,CAAC,KAAK,EAAE;QACf,KAAK,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB,kBAAkB,CAAC,IAAI,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,KAAK,EAAE,SAAS,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE;QACN,MAAM,EAAE,SAAS,CAAC;QAClB,MAAM,EAAE,SAAS,CAAC;QAClB,KAAK,EAAE,QAAQ,CAAC;QAChB,SAAS,EAAE,YAAY,CAAC;KACzB,CAAC;IACF,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,sEAAsE;AACtE,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM;gBAAV,EAAE,EAAE,MAAM,EAAE,MAAM,SAA+B;CAIvE;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CA+KhD"}
+{"version":3,"file":"grid-host-calls.d.ts","sourceRoot":"","sources":["../../src/grid-mods/grid-host-calls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;QAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACtF,aAAa,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF;;;OAGG;IACH,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrG;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,CAAC,KAAK,EAAE;QACf,KAAK,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB,kBAAkB,CAAC,IAAI,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,KAAK,EAAE,SAAS,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE;QACN,MAAM,EAAE,SAAS,CAAC;QAClB,MAAM,EAAE,SAAS,CAAC;QAClB,KAAK,EAAE,QAAQ,CAAC;QAChB,gEAAgE;QAChE,OAAO,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;KACxC,CAAC;IACF,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,sEAAsE;AACtE,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM;gBAAV,EAAE,EAAE,MAAM,EAAE,MAAM,SAA+B;CAIvE;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CA6JhD"}