@crowdedkingdoms/crowdyjs 8.7.0 → 8.9.0

package/dist/kit/liveops.d.ts

@@ -0,0 +1,112 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+import type { EngineDetector } from './engine.js';
+/** Options for {@link LiveopsKit}. */
+export interface LiveopsKitOptions {
+    /** The `typePrefix` the liveops blueprint was deployed with. */
+    typePrefix?: string;
+    /** The scheduler engine module name. Defaults to `'liveops-scheduler'`. */
+    moduleName?: string;
+}
+/** A parsed event window. */
+export interface KitEventWindow {
+    containerId: string;
+    windowId: string;
+    active: boolean;
+    opensAtMs: number;
+    closesAtMs: number;
+    modifiers: Record<string, unknown>;
+}
+/** A parsed season definition (+ its battle-pass composition). */
+export interface KitSeason {
+    containerId: string;
+    seasonId: string;
+    active: boolean;
+    startsAtMs: number;
+    endsAtMs: number;
+    passTrack: string;
+    passFeatures: string[];
+}
+/** A parsed type-98 zone-change event (BR circles, event areas). */
+export interface ZoneChangeEvent {
+    kind: string;
+    phase: number | null;
+    radiusNow: number;
+    centerX: number;
+    centerZ: number;
+    body: Record<string, unknown>;
+}
+/**
+ * Runtime helpers for the liveops blueprint: event windows (admin CRUD +
+ * active reads — engine-backed when the liveops-scheduler is deployed),
+ * seasons with battle-pass composition, and the type-98 zone-change parser.
+ *
+ * Obtained via `client.kit(appId).liveops`.
+ */
+export declare class LiveopsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly engines?;
+    private readonly names;
+    private readonly moduleName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: LiveopsKitOptions, engines?: EngineDetector | undefined);
+    /** Is the liveops-scheduler engine deployed + enabled (cached)? */
+    engineAvailable(): Promise<boolean>;
+    /** STUDIO (admin) — create an event window. */
+    defineWindow(input: {
+        windowId: string;
+        displayName?: string;
+        opensAtMs?: number;
+        closesAtMs?: number;
+        modifiers?: Record<string, unknown>;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** Every window (model read). */
+    windows(): Promise<KitEventWindow[]>;
+    /**
+     * The ACTIVE windows. Engine path (scheduler deployed): the module's
+     * authoritative view; otherwise filters the model read.
+     */
+    activeWindows(): Promise<KitEventWindow[]>;
+    /** STUDIO (admin/automation) — open a window through the model function. */
+    openWindow(windowContainerId: string, sessionId?: string): Promise<import("./shared.js").KitInvokeResult<boolean>>;
+    /** STUDIO (admin/automation) — close a window through the model function. */
+    closeWindow(windowContainerId: string, sessionId?: string): Promise<import("./shared.js").KitInvokeResult<boolean>>;
+    /** STUDIO (admin) — create a season (+ battle-pass composition). */
+    defineSeason(input: {
+        seasonId: string;
+        displayName?: string;
+        startsAtMs?: number;
+        endsAtMs?: number;
+        passTrack?: string;
+        passFeatures?: string[];
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** Every season (model read). */
+    seasons(): Promise<KitSeason[]>;
+    /** The active season, when one exists. */
+    currentSeason(): Promise<KitSeason | null>;
+    /** STUDIO (admin/automation) — activate a season through the model function. */
+    activateSeason(seasonContainerId: string, sessionId?: string): Promise<import("./shared.js").KitInvokeResult<boolean>>;
+    /** Parse a type-98 zone-change server event (BR circles, event areas). */
+    parseZoneChange(bytes: Uint8Array): ZoneChangeEvent | null;
+}
+//# sourceMappingURL=liveops.d.ts.map

package/dist/kit/liveops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveops.d.ts","sourceRoot":"","sources":["../../src/kit/liveops.ts"],"names":[],"mappings":"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"}

package/dist/kit/liveops.js

@@ -0,0 +1,183 @@
+import { liveopsNames } from './blueprints/liveops.js';
+import { kitContainerProperties, kitInvoke } from './shared.js';
+import { parseEngineEvent, EVENT_ZONE_CHANGE } from './wire.js';
+/**
+ * Runtime helpers for the liveops blueprint: event windows (admin CRUD +
+ * active reads — engine-backed when the liveops-scheduler is deployed),
+ * seasons with battle-pass composition, and the type-98 zone-change parser.
+ *
+ * Obtained via `client.kit(appId).liveops`.
+ */
+export class LiveopsKit {
+    constructor(appId, gameModel, options = {}, engines) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.engines = engines;
+        this.names = liveopsNames(options.typePrefix ?? '');
+        this.moduleName = options.moduleName ?? 'liveops-scheduler';
+    }
+    /** Is the liveops-scheduler engine deployed + enabled (cached)? */
+    engineAvailable() {
+        if (!this.engines)
+            return Promise.resolve(false);
+        return this.engines.has(this.moduleName);
+    }
+    /** STUDIO (admin) — create an event window. */
+    async defineWindow(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.windowType,
+            displayName: input.displayName ?? `Window ${input.windowId}`,
+            properties: [
+                { key: 'window_id', valueType: 'string', valueJson: JSON.stringify(input.windowId) },
+                ...(input.opensAtMs !== undefined
+                    ? [{ key: 'opens_at_ms', valueType: 'int', valueJson: String(input.opensAtMs) }]
+                    : []),
+                ...(input.closesAtMs !== undefined
+                    ? [{ key: 'closes_at_ms', valueType: 'int', valueJson: String(input.closesAtMs) }]
+                    : []),
+                {
+                    key: 'modifiers',
+                    valueType: 'string',
+                    valueJson: JSON.stringify(JSON.stringify(input.modifiers ?? {})),
+                },
+            ],
+        });
+    }
+    /** Every window (model read). */
+    async windows() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.windowType,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            let modifiers = {};
+            try {
+                modifiers = JSON.parse(String(props.modifiers ?? '{}'));
+            }
+            catch {
+                /* opaque */
+            }
+            return {
+                containerId: c.containerId,
+                windowId: String(props.window_id ?? ''),
+                active: props.active === true,
+                opensAtMs: Number(props.opens_at_ms ?? 0),
+                closesAtMs: Number(props.closes_at_ms ?? 0),
+                modifiers,
+            };
+        }));
+    }
+    /**
+     * The ACTIVE windows. Engine path (scheduler deployed): the module's
+     * authoritative view; otherwise filters the model read.
+     */
+    async activeWindows() {
+        if (this.engines && (await this.engineAvailable())) {
+            const result = await this.engines.invoke(this.moduleName, 'active_windows', {});
+            if (result.success && Array.isArray(result.body.windows)) {
+                const all = await this.windows();
+                const activeIds = new Set(result.body.windows.map((w) => String(w.windowId)));
+                return all.filter((w) => activeIds.has(w.windowId));
+            }
+        }
+        return (await this.windows()).filter((w) => w.active);
+    }
+    /** STUDIO (admin/automation) — open a window through the model function. */
+    async openWindow(windowContainerId, sessionId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.openWindowFn,
+            selfContainerId: windowContainerId,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+        });
+    }
+    /** STUDIO (admin/automation) — close a window through the model function. */
+    async closeWindow(windowContainerId, sessionId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.closeWindowFn,
+            selfContainerId: windowContainerId,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+        });
+    }
+    /** STUDIO (admin) — create a season (+ battle-pass composition). */
+    async defineSeason(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.seasonType,
+            displayName: input.displayName ?? `Season ${input.seasonId}`,
+            properties: [
+                { key: 'season_id', valueType: 'string', valueJson: JSON.stringify(input.seasonId) },
+                ...(input.startsAtMs !== undefined
+                    ? [{ key: 'starts_at_ms', valueType: 'int', valueJson: String(input.startsAtMs) }]
+                    : []),
+                ...(input.endsAtMs !== undefined
+                    ? [{ key: 'ends_at_ms', valueType: 'int', valueJson: String(input.endsAtMs) }]
+                    : []),
+                ...(input.passTrack !== undefined
+                    ? [{ key: 'pass_track', valueType: 'string', valueJson: JSON.stringify(input.passTrack) }]
+                    : []),
+                {
+                    key: 'pass_features',
+                    valueType: 'string',
+                    valueJson: JSON.stringify(JSON.stringify(input.passFeatures ?? [])),
+                },
+            ],
+        });
+    }
+    /** Every season (model read). */
+    async seasons() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.seasonType,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            let passFeatures = [];
+            try {
+                passFeatures = JSON.parse(String(props.pass_features ?? '[]')).map(String);
+            }
+            catch {
+                /* opaque */
+            }
+            return {
+                containerId: c.containerId,
+                seasonId: String(props.season_id ?? ''),
+                active: props.active === true,
+                startsAtMs: Number(props.starts_at_ms ?? 0),
+                endsAtMs: Number(props.ends_at_ms ?? 0),
+                passTrack: String(props.pass_track ?? ''),
+                passFeatures,
+            };
+        }));
+    }
+    /** The active season, when one exists. */
+    async currentSeason() {
+        return (await this.seasons()).find((s) => s.active) ?? null;
+    }
+    /** STUDIO (admin/automation) — activate a season through the model function. */
+    async activateSeason(seasonContainerId, sessionId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.activateSeasonFn,
+            selfContainerId: seasonContainerId,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+        });
+    }
+    /** Parse a type-98 zone-change server event (BR circles, event areas). */
+    parseZoneChange(bytes) {
+        const parsed = parseEngineEvent(bytes);
+        if (!parsed || parsed.eventType !== EVENT_ZONE_CHANGE)
+            return null;
+        return {
+            kind: String(parsed.body.kind ?? ''),
+            phase: parsed.body.phase != null ? Number(parsed.body.phase) : null,
+            radiusNow: Number(parsed.body.radiusNow ?? 0),
+            centerX: Number(parsed.body.centerX ?? 0),
+            centerZ: Number(parsed.body.centerZ ?? 0),
+            body: parsed.body,
+        };
+    }
+}

package/dist/kit/loot.d.ts

@@ -1,8 +1,14 @@
 import type { GameModelAPI } from '../domains/gameModel.js';
+import type { EngineDetector } from './engine.js';
 import type { Scalars } from '../generated/graphql.js';
 import { type KitInvokeResult } from './shared.js';
 /** Options for {@link LootKit}. Must match the deployed loot blueprint. */
 export interface LootKitOptions {
+    /**
+     * The big-table loot module (pity timers, audit trails). Defaults to
+     * `'loot-engine'`; the gacha-shrine example ships this contract.
+     */
+    engineModuleName?: string;
     /** The `typePrefix` the loot blueprint was deployed with. */
     typePrefix?: string;
 }
@@ -29,9 +35,24 @@ export interface KitLootRoll {
 export declare class LootKit {
     private readonly appId;
     private readonly gameModel;
+    private readonly engines?;
     private readonly names;
     private readonly typePrefix;
-    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: LootKitOptions);
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: LootKitOptions, engines?: EngineDetector | undefined);
+    private readonly engineModuleName;
+    /**
+     * Is a big-table loot module deployed + enabled (cached per session)?
+     * When true, {@link enginePull} routes rolls through server-held RNG with
+     * pity timers + audit trails; the blueprint's weighted model rolls stay
+     * for small tables (the coexistence policy — "the server picks the path").
+     */
+    engineAvailable(): Promise<boolean>;
+    /** Pull from the module's table (pity-timer path); count caps at 10. */
+    enginePull(count?: number): Promise<Record<string, unknown>>;
+    /** Your pity counters + roll totals from the module. */
+    enginePity(): Promise<Record<string, unknown>>;
+    /** Your rolling audit trail from the module (dispute resolution). */
+    engineAudit(): Promise<Record<string, unknown>>;
     /**
      * Create an unrolled `LootRoll` for a table, owned by `ownerUserId` (who
      * will claim it). Event-drop automations pick from the pool of unrolled

package/dist/kit/loot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loot.d.ts","sourceRoot":"","sources":["../../src/kit/loot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,OAAO;IAKhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGjB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,cAAmB;IAM9B;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE;QACtB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAqBD;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAU9E;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAShF,6BAA6B;IACvB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAYjD;;;OAGG;IACG,KAAK,CACT,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAC1D,OAAO,CAAC,WAAW,EAAE,CAAC;IAwBzB;;;OAGG;IACG,OAAO,CACX,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;;;;;;;YAYtC,MAAM;CAoBrB"}
+{"version":3,"file":"loot.d.ts","sourceRoot":"","sources":["../../src/kit/loot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,OAAO;IAKhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAP3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGjB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,cAAmB,EACX,OAAO,CAAC,EAAE,cAAc,YAAA;IAO3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;;;;OAKG;IACH,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAKnC,wEAAwE;IAClE,UAAU,CAAC,KAAK,SAAI;IAO1B,wDAAwD;IAClD,UAAU;IAOhB,qEAAqE;IAC/D,WAAW;IAOjB;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE;QACtB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAqBD;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAU9E;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAShF,6BAA6B;IACvB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAYjD;;;OAGG;IACG,KAAK,CACT,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAC1D,OAAO,CAAC,WAAW,EAAE,CAAC;IAwBzB;;;OAGG;IACG,OAAO,CACX,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;;;;;;;YAYtC,MAAM;CAoBrB"}

package/dist/kit/loot.js

@@ -10,11 +10,51 @@ import { kitContainerProperties, kitInvoke, } from './shared.js';
  * Obtained via `client.kit(appId).loot`.
  */
 export class LootKit {
-    constructor(appId, gameModel, options = {}) {
+    constructor(appId, gameModel, options = {}, engines) {
         this.appId = appId;
         this.gameModel = gameModel;
+        this.engines = engines;
         this.typePrefix = options.typePrefix ?? '';
         this.names = lootNames(this.typePrefix);
+        this.engineModuleName = options.engineModuleName ?? 'loot-engine';
+    }
+    /**
+     * Is a big-table loot module deployed + enabled (cached per session)?
+     * When true, {@link enginePull} routes rolls through server-held RNG with
+     * pity timers + audit trails; the blueprint's weighted model rolls stay
+     * for small tables (the coexistence policy — "the server picks the path").
+     */
+    engineAvailable() {
+        if (!this.engines)
+            return Promise.resolve(false);
+        return this.engines.has(this.engineModuleName);
+    }
+    /** Pull from the module's table (pity-timer path); count caps at 10. */
+    async enginePull(count = 1) {
+        if (!this.engines)
+            throw new Error('loot engine unavailable: compute domain not wired');
+        const result = await this.engines.invoke(this.engineModuleName, 'pull', { count });
+        if (!result.success)
+            throw new Error(`loot.pull failed: ${result.reason ?? 'unknown'}`);
+        return result.body;
+    }
+    /** Your pity counters + roll totals from the module. */
+    async enginePity() {
+        if (!this.engines)
+            throw new Error('loot engine unavailable: compute domain not wired');
+        const result = await this.engines.invoke(this.engineModuleName, 'pity', {});
+        if (!result.success)
+            throw new Error(`loot.pity failed: ${result.reason ?? 'unknown'}`);
+        return result.body;
+    }
+    /** Your rolling audit trail from the module (dispute resolution). */
+    async engineAudit() {
+        if (!this.engines)
+            throw new Error('loot engine unavailable: compute domain not wired');
+        const result = await this.engines.invoke(this.engineModuleName, 'audit', {});
+        if (!result.success)
+            throw new Error(`loot.audit failed: ${result.reason ?? 'unknown'}`);
+        return result.body;
     }
     /**
      * Create an unrolled `LootRoll` for a table, owned by `ownerUserId` (who

package/dist/kit/matches.d.ts

@@ -1,10 +1,16 @@
 import type { ChannelsAPI } from '../domains/channels.js';
+import type { EngineDetector } from './engine.js';
 import type { GameModelAPI } from '../domains/gameModel.js';
 import type { UdpAPI } from '../domains/udp.js';
 import type { Scalars } from '../generated/graphql.js';
 import { type KitInvokeResult } from './shared.js';
 /** Options for {@link MatchesKit}. Must match the deployed matches blueprint. */
 export interface MatchesKitOptions {
+    /**
+     * The compute module driving server-side match lifecycle when the app
+     * runs an engine. Defaults to `'match-engine'`.
+     */
+    engineModuleName?: string;
     /** The `typePrefix` the matches blueprint was deployed with. */
     typePrefix?: string;
     /**
@@ -52,9 +58,11 @@ export declare class MatchesKit {
     private readonly gameModel;
     private readonly channels;
     private readonly udp;
+    private readonly engines?;
     private readonly names;
     private readonly actorUuid;
-    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, channels: ChannelsAPI | undefined, udp: UdpAPI | undefined, options?: MatchesKitOptions);
+    private readonly engineModuleName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, channels: ChannelsAPI | undefined, udp: UdpAPI | undefined, options?: MatchesKitOptions, engines?: EngineDetector | undefined);
     private requireChannels;
     private requireUdp;
     /**
@@ -136,5 +144,29 @@ export declare class MatchesKit {
      */
     onMatchChanged(match: KitMatch, callback: (match: KitMatch) => void): () => void;
     private toMatch;
+    /**
+     * Is a match compute engine deployed + enabled (cached per session)? When
+     * true the engine owns transitions (ready checks, turn order + timeouts,
+     * authoritative scoring); the blueprint's creator-driven functions remain
+     * for model-only deployments.
+     */
+    engineAvailable(): Promise<boolean>;
+    /**
+     * Declare ready on an engine match (a MatchMeta container id). The match
+     * starts server-side once every expected player is ready.
+     */
+    engineReady(matchId: string): Promise<Record<string, unknown>>;
+    /** Submit your move (the engine validates the turn + resolves). */
+    engineSubmitMove(matchId: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Forfeit an engine match. */
+    engineForfeit(matchId: string): Promise<Record<string, unknown>>;
+    /** The engine's live view: turn holder, timers, standings, summary. */
+    engineStatus(matchId: string): Promise<Record<string, unknown>>;
+    /**
+     * Resolve a matchmaking proposal to the match the engine created for it
+     * (poll after everyone accepts; see `kit.matchmaking`).
+     */
+    findByProposal(proposalId: string): Promise<string | null>;
+    private engineInvoke;
 }
 //# sourceMappingURL=matches.d.ts.map

package/dist/kit/matches.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matches.d.ts","sourceRoot":"","sources":["../../src/kit/matches.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"matches.d.ts","sourceRoot":"","sources":["../../src/kit/matches.ts"],"names":[],"mappings":"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"}

package/dist/kit/matches.js

@@ -12,12 +12,14 @@ import { kitContainerProperties, kitInvoke, } from './shared.js';
  * Obtained via `client.kit(appId).matches`.
  */
 export class MatchesKit {
-    constructor(appId, gameModel, channels, udp, options = {}) {
+    constructor(appId, gameModel, channels, udp, options = {}, engines) {
         this.appId = appId;
         this.gameModel = gameModel;
         this.channels = channels;
         this.udp = udp;
+        this.engines = engines;
         this.names = matchesNames(options.typePrefix ?? '');
+        this.engineModuleName = options.engineModuleName ?? 'match-engine';
         this.actorUuid = options.actorUuid ?? generateCrowdyUuid();
     }
     requireChannels() {
@@ -250,4 +252,57 @@ export class MatchesKit {
                 : {}),
         };
     }
+    // -- Engine path (Wave 2): server-driven lifecycle over the match engine --
+    /**
+     * Is a match compute engine deployed + enabled (cached per session)? When
+     * true the engine owns transitions (ready checks, turn order + timeouts,
+     * authoritative scoring); the blueprint's creator-driven functions remain
+     * for model-only deployments.
+     */
+    engineAvailable() {
+        if (!this.engines)
+            return Promise.resolve(false);
+        return this.engines.has(this.engineModuleName);
+    }
+    /**
+     * Declare ready on an engine match (a MatchMeta container id). The match
+     * starts server-side once every expected player is ready.
+     */
+    async engineReady(matchId) {
+        return this.engineInvoke('ready', { matchId });
+    }
+    /** Submit your move (the engine validates the turn + resolves). */
+    async engineSubmitMove(matchId, params = {}) {
+        return this.engineInvoke('submit_move', { matchId, ...params });
+    }
+    /** Forfeit an engine match. */
+    async engineForfeit(matchId) {
+        return this.engineInvoke('forfeit', { matchId });
+    }
+    /** The engine's live view: turn holder, timers, standings, summary. */
+    async engineStatus(matchId) {
+        return this.engineInvoke('status', { matchId });
+    }
+    /**
+     * Resolve a matchmaking proposal to the match the engine created for it
+     * (poll after everyone accepts; see `kit.matchmaking`).
+     */
+    async findByProposal(proposalId) {
+        if (!this.engines)
+            return null;
+        const result = await this.engines.invoke(this.engineModuleName, 'find_by_proposal', {
+            proposalId,
+        });
+        return result.success ? String(result.body.matchId ?? '') || null : null;
+    }
+    async engineInvoke(exportName, params) {
+        if (!this.engines) {
+            throw new Error('match engine unavailable: compute domain not wired');
+        }
+        const result = await this.engines.invoke(this.engineModuleName, exportName, params);
+        if (!result.success) {
+            throw new Error(`matches.${exportName} failed: ${result.reason ?? 'unknown'}`);
+        }
+        return result.body;
+    }
 }

package/dist/kit/matchmaking.d.ts

@@ -0,0 +1,57 @@
+import type { Scalars } from '../generated/graphql.js';
+import type { EngineDetector } from './engine.js';
+/** Options for {@link MatchmakingKit}. */
+export interface MatchmakingKitOptions {
+    /** The matchmaking module name. Defaults to `'matchmaking'`. */
+    moduleName?: string;
+}
+/** Your queue status: where you are queued and any live proposal. */
+export interface KitQueueStatus {
+    queuedIn: string | null;
+    proposal: {
+        proposalId: string;
+        mode: string;
+        players: string[];
+        accepted: string[];
+        handedOff: boolean;
+    } | null;
+    queueDepth: number;
+    rating: number;
+}
+/**
+ * Runtime helpers for the matchmaking engine (Wave 2): rating-bucketed
+ * queues with widening windows, party blocks, and accept-gated proposals
+ * that hand off to the match layer over compute events. After everyone
+ * accepts, resolve the created match with `kit.matches.findByProposal`.
+ *
+ * Obtained via `client.kit(appId).matchmaking`.
+ */
+export declare class MatchmakingKit {
+    private readonly engines;
+    private readonly moduleName;
+    constructor(_appId: Scalars['BigInt']['input'], engines: EngineDetector, options?: MatchmakingKitOptions);
+    /** Is the matchmaking engine deployed + enabled (cached per session)? */
+    engineAvailable(): Promise<boolean>;
+    /**
+     * Join a queue (optionally with a party block that must match together,
+     * and an explicit rating for games that keep rating on the progression
+     * layer).
+     */
+    queueJoin(input?: {
+        mode?: string;
+        rating?: number;
+        party?: string[];
+    }): Promise<Record<string, unknown>>;
+    /** Leave your queue (all modes, or one with `mode`). */
+    queueLeave(mode?: string): Promise<Record<string, unknown>>;
+    /** Your queue/proposal status. */
+    queueStatus(mode?: string): Promise<KitQueueStatus>;
+    /** Accept a proposal; when everyone has, the match handoff fires. */
+    accept(proposalId: string): Promise<Record<string, unknown>>;
+    /** Report the decided result (Elo-lite rating update + proposal close). */
+    reportResult(proposalId: string, winnerUserId: string): Promise<Record<string, unknown>>;
+    /** Engine totals (queues/proposals/rated players). */
+    status(): Promise<Record<string, unknown>>;
+    private invoke;
+}
+//# sourceMappingURL=matchmaking.d.ts.map

package/dist/kit/matchmaking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchmaking.d.ts","sourceRoot":"","sources":["../../src/kit/matchmaking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE;QACR,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,SAAS,EAAE,OAAO,CAAC;KACpB,GAAG,IAAI,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IAKvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGlC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjB,OAAO,EAAE,cAAc,EACxC,OAAO,GAAE,qBAA0B;IAKrC,yEAAyE;IACzE,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;;;OAIG;IACG,SAAS,CAAC,KAAK,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO;IAIhF,wDAAwD;IAClD,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM;IAI9B,kCAAkC;IAC5B,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAUzD,qEAAqE;IAC/D,MAAM,CAAC,UAAU,EAAE,MAAM;IAI/B,2EAA2E;IACrE,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAI3D,sDAAsD;IAChD,MAAM;YAIE,MAAM;CAOrB"}