@voltro/plugin-rooms 0.0.0-stage → 0.87.0

package/dist/bots.d.ts

@@ -0,0 +1,1485 @@
+import { DeclaredAccess } from '@voltro/protocol';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+
+export declare const aimError: (degrees: number, rng: RoomBotRandom) => number;
+
+declare type CollisionBody2D = {
+    readonly kind: 'circle';
+    readonly radius: number;
+} | {
+    readonly kind: 'aabb';
+    readonly halfWidth: number;
+    readonly halfHeight: number;
+};
+
+declare interface CollisionResult2D {
+    readonly transform: Transform2D;
+    readonly collided: ReadonlyArray<string>;
+    readonly iterations: number;
+}
+
+/** Pure authoring. The host must supply a player's actual visibility projection
+ * and route the resulting intentions through ordinary room input admission. */
+export declare const defineBot: <V extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, M extends Schema.Codec<unknown, unknown>>(input: RoomBotBehavior<V, I, M>) => RoomBotDescriptor<V, I, M>;
+
+/** Exact reduced integer ratio over admitted coordinates/differences of magnitude <= u32.
+ * Shared 2D/3D slab arithmetic; never round a fraction before comparing it. */
+declare interface FixedSlabFraction {
+    readonly numerator: number;
+    readonly denominator: number;
+}
+
+declare interface GeometryBoxOverlapOptions {
+    readonly maxTests?: number;
+}
+
+declare type GeometryChunk = GeometryTileChunk | GeometryHeightfieldChunk | GeometryShapesChunk | GeometryVoxelChunk;
+
+declare interface GeometryGridRayHit {
+    readonly kind: '2d-tiles' | '3d-voxel';
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    readonly cell: {
+        readonly x: number;
+        readonly y: number;
+        readonly z?: number;
+    };
+    /** Exact reduced infimum entry fraction on the offered segment, not a
+     * rounded contact point or a floating-point distance. */
+    readonly fraction: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+    readonly visitedCells: number;
+}
+
+declare interface GeometryGridRayOptions {
+    readonly maxVisitedCells?: number;
+}
+
+declare interface GeometryGridSweepHit {
+    readonly kind: '2d-tiles' | '3d-voxel';
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    readonly cell: {
+        readonly x: number;
+        readonly y: number;
+        readonly z?: number;
+    };
+    /** Infimum/supremum of positive-volume overlap, clipped to [0,1]. Contact
+     * alone is not an overlap; fractions are exact reduced integer ratios. */
+    readonly entry: FixedSlabFraction;
+    readonly exit: FixedSlabFraction;
+    readonly initialOverlap: boolean;
+    readonly testedCells: number;
+}
+
+/** A half-open raw box `[min, max)` on all three axes; a heightfield box needs its z extent. */
+declare interface GeometryHeightfieldBoxRaw {
+    readonly minXRaw: number;
+    readonly minYRaw: number;
+    readonly minZRaw: number;
+    readonly maxXRaw: number;
+    readonly maxYRaw: number;
+    readonly maxZRaw: number;
+}
+
+declare type GeometryHeightfieldChunk = (typeof GeometryHeightfieldChunkSchema)["Type"];
+
+declare const GeometryHeightfieldChunkSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"2d-heightfield">;
+    readonly formatVersion: Schema.Literal<1>;
+    readonly address: Schema.Struct<{
+        readonly worldId: Schema.String;
+        readonly layerSetId: Schema.String;
+        readonly cx: Schema.Int;
+        readonly cy: Schema.Int;
+    }>;
+    readonly version: Schema.String;
+    readonly width: Schema.Int;
+    readonly height: Schema.Int;
+    readonly sampleSpacingRaw: Schema.Int;
+    readonly baseHeightRaw: Schema.Int;
+    readonly heightQuantumRaw: Schema.Int;
+    readonly heights: Schema.$Array<Schema.Int>;
+}>;
+
+declare interface GeometryHeightfieldRayHit {
+    readonly kind: '2d-heightfield';
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    /** The first point on the segment at or below the surface, in global raw units. */
+    readonly point: GeometryHeightfieldRayPoint;
+    /** Exact reduced position on the offered segment whose raw-grid point is `point`. */
+    readonly fraction: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+    readonly visitedSamples: number;
+}
+
+declare interface GeometryHeightfieldRayPoint {
+    readonly xRaw: number;
+    readonly yRaw: number;
+    readonly zRaw: number;
+}
+
+declare interface GeometryHeightfieldSweepHit {
+    readonly kind: '2d-heightfield';
+    /** The first box position along the path that reaches under the surface, on the raw grid. */
+    readonly box: GeometryHeightfieldBoxRaw;
+    /** Exact reduced position of `box` on the path: raw steps along the longest axis over its length. */
+    readonly fraction: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+    /** The start box already reaches under the surface (fraction 0). */
+    readonly initialOverlap: boolean;
+    /** Overlap evaluations used, coarse and refining together. */
+    readonly evaluations: number;
+}
+
+declare type GeometryKind = GeometryChunk['kind'];
+
+declare interface GeometryPersistenceScope {
+    readonly tenantId: string;
+    readonly kind: GeometryKind;
+    readonly worldId: string;
+    readonly version: string;
+    readonly layerSetId: string;
+    readonly cx: number;
+    readonly cy: number;
+    readonly cz?: number | undefined;
+}
+
+declare interface GeometryPreparedScope {
+    readonly tenantId: string;
+    readonly kind: GeometryKind;
+    readonly worldId: string;
+    readonly layerSetId: string;
+    readonly version: string;
+}
+
+declare type GeometryShape = (typeof GeometryShapeSchema)["Type"];
+
+declare interface GeometryShapeRayHit {
+    readonly kind: '3d-shapes';
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    /** Native LOCAL shape; scope identifies its owning chunk. */
+    readonly shape: GeometryShape;
+    /** Encloses the exact infimum entry time; width <= 2^-52. Presentation only.
+     * Selection and ownership decisions never use these rounded bounds. */
+    readonly fractionBounds: {
+        readonly lower: number;
+        readonly upper: number;
+    };
+    readonly visitedChunks: number;
+    readonly testedShapes: number;
+}
+
+declare const GeometryShapeSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly halfXRaw: Schema.Int;
+    readonly halfYRaw: Schema.Int;
+    readonly halfZRaw: Schema.Int;
+    readonly id: Schema.String;
+    readonly xRaw: Schema.Int;
+    readonly yRaw: Schema.Int;
+    readonly zRaw: Schema.Int;
+    readonly kind: Schema.Literal<"aabb">;
+}>, Schema.Struct<{
+    readonly radiusRaw: Schema.Int;
+    readonly id: Schema.String;
+    readonly xRaw: Schema.Int;
+    readonly yRaw: Schema.Int;
+    readonly zRaw: Schema.Int;
+    readonly kind: Schema.Literal<"sphere">;
+}>]>;
+
+declare type GeometryShapesChunk = (typeof GeometryShapesChunkSchema)["Type"];
+
+declare const GeometryShapesChunkSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"3d-shapes">;
+    readonly formatVersion: Schema.Literal<1>;
+    readonly address: Schema.Struct<{
+        readonly worldId: Schema.String;
+        readonly layerSetId: Schema.String;
+        readonly cx: Schema.Int;
+        readonly cy: Schema.Int;
+        readonly cz: Schema.Int;
+    }>;
+    readonly version: Schema.String;
+    readonly extentXRaw: Schema.Int;
+    readonly extentYRaw: Schema.Int;
+    readonly extentZRaw: Schema.Int;
+    readonly shapes: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly halfXRaw: Schema.Int;
+        readonly halfYRaw: Schema.Int;
+        readonly halfZRaw: Schema.Int;
+        readonly id: Schema.String;
+        readonly xRaw: Schema.Int;
+        readonly yRaw: Schema.Int;
+        readonly zRaw: Schema.Int;
+        readonly kind: Schema.Literal<"aabb">;
+    }>, Schema.Struct<{
+        readonly radiusRaw: Schema.Int;
+        readonly id: Schema.String;
+        readonly xRaw: Schema.Int;
+        readonly yRaw: Schema.Int;
+        readonly zRaw: Schema.Int;
+        readonly kind: Schema.Literal<"sphere">;
+    }>]>>;
+}>;
+
+declare type GeometryTileChunk = (typeof GeometryTileChunkSchema)["Type"];
+
+declare const GeometryTileChunkSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"2d-tiles">;
+    readonly formatVersion: Schema.Literal<1>;
+    readonly address: Schema.Struct<{
+        readonly worldId: Schema.String;
+        readonly layerSetId: Schema.String;
+        readonly cx: Schema.Int;
+        readonly cy: Schema.Int;
+    }>;
+    readonly version: Schema.String;
+    readonly width: Schema.Int;
+    readonly height: Schema.Int;
+    readonly tileSizeRaw: Schema.Int;
+    readonly palette: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly solid: Schema.Boolean;
+    }>>;
+    readonly runs: Schema.$Array<Schema.Struct<{
+        readonly paletteIndex: Schema.Int;
+        readonly length: Schema.Int;
+    }>>;
+}>;
+
+declare interface GeometryTileCollisionOptions {
+    /** Total visited cells across every solver query, including its final check.
+     * May only narrow the world's maxOverlapTests. */
+    readonly maxTests?: number;
+    /** Existing discrete solver limit; defaults to 8, maximum 256. */
+    readonly maxIterations?: number;
+}
+
+declare type GeometryTileMaterial = (typeof GeometryTileMaterialSchema)["Type"];
+
+declare const GeometryTileMaterialSchema: Schema.Struct<{
+    readonly key: Schema.String;
+    readonly solid: Schema.Boolean;
+}>;
+
+declare type GeometryVoxelChunk = (typeof GeometryVoxelChunkSchema)["Type"];
+
+declare const GeometryVoxelChunkSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"3d-voxel">;
+    readonly formatVersion: Schema.Literal<1>;
+    readonly address: Schema.Struct<{
+        readonly worldId: Schema.String;
+        readonly layerSetId: Schema.String;
+        readonly cx: Schema.Int;
+        readonly cy: Schema.Int;
+        readonly cz: Schema.Int;
+    }>;
+    readonly version: Schema.String;
+    readonly side: Schema.Int;
+    readonly voxelSizeRaw: Schema.Int;
+    readonly palette: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly solid: Schema.Boolean;
+    }>>;
+    readonly sections: Schema.$Array<Schema.Struct<{
+        readonly sx: Schema.Int;
+        readonly sy: Schema.Int;
+        readonly sz: Schema.Int;
+        readonly runs: Schema.$Array<Schema.Struct<{
+            readonly paletteIndex: Schema.Int;
+            readonly length: Schema.Int;
+        }>>;
+    }>>;
+}>;
+
+/** Nonempty half-open raw box. Three-dimensional kinds require both Z fields. */
+declare interface GeometryWorldBoxRaw {
+    readonly minXRaw: number;
+    readonly minYRaw: number;
+    readonly maxXRaw: number;
+    readonly maxYRaw: number;
+    readonly minZRaw?: number;
+    readonly maxZRaw?: number;
+}
+
+declare interface GeometryWorldPointRaw {
+    readonly xRaw: number;
+    readonly yRaw: number;
+    readonly zRaw?: number;
+}
+
+declare type GeometryWorldRayHit = GeometryGridRayHit | GeometryShapeRayHit | GeometryHeightfieldRayHit;
+
+declare interface GeometryWorldRayOptions extends GeometryGridRayOptions {
+    /** Shapes only; narrows maxOverlapTests for the total shape scan. */
+    readonly maxTests?: number;
+}
+
+declare interface GeometryWorldShapeHit {
+    readonly scope: GeometryPersistenceScope;
+    readonly revision: number;
+    readonly shape: GeometryShape;
+}
+
+declare interface GeometryWorldView {
+    readonly kind: GeometryKind;
+    readonly scope: GeometryPreparedScope;
+    /** Discrete AABB/circle resolution in world units against current tile data.
+     * Reuses the Transform solver; no swept movement or velocity integration. */
+    collide(transform: Transform2D, body: CollisionBody2D, options?: GeometryTileCollisionOptions): CollisionResult2D;
+    /** Tiles/voxels only. Unloaded coordinates refuse, never implicit empty terrain. */
+    materialAtRaw(point: GeometryWorldPointRaw): GeometryTileMaterial;
+    /** Tiles/voxels/shapes: the stored solidity. Heightfields (points with `zRaw`): terrain is solid at and
+     * below its surface, the same surface `raycastRaw` hits. Heightfield material is not invented. */
+    solidAtRaw(point: GeometryWorldPointRaw): boolean;
+    /** Heightfield only, with exact existing native interpolation. */
+    heightAtRaw(point: GeometryWorldPointRaw): number;
+    /** Shapes only; hit volumes retain native LOCAL coordinates and exact chunk scope. */
+    shapesAtRaw(point: GeometryWorldPointRaw): ReadonlyArray<GeometryWorldShapeHit>;
+    /** Tiles/voxels return exact rational entry; shapes select exact quadratic
+     * entry and expose enclosing presentation bounds; heightfields (points with
+     * `zRaw`) return the first sampled point at or below the surface, refined to
+     * one raw unit (`raycastGeometryHeightfield`). Missing coverage refuses. */
+    raycastRaw(from: GeometryWorldPointRaw, to: GeometryWorldPointRaw, options?: GeometryWorldRayOptions): GeometryWorldRayHit | null;
+    /** Tiles/voxels/closed native shapes, clipped by half-open chunk ownership. Heightfields need the z extent:
+     * the box touches terrain when the highest surface point over its footprint is at or above `minZRaw`
+     * (`overlapsGeometryHeightfieldBox`). Nonempty half-open raw boxes only; missing data or work exhaustion refuses. */
+    overlapsBoxRaw(box: GeometryWorldBoxRaw, options?: GeometryBoxOverlapOptions): boolean;
+    /** Translation-only tile/voxel sweep. Shares maxOverlapTests; validates the
+     * whole swept bounding region before publishing the earliest overlap. */
+    sweepBoxRaw(from: GeometryWorldBoxRaw, to: GeometryWorldBoxRaw, options?: GeometryBoxOverlapOptions): GeometryGridSweepHit | null;
+    /** Heightfields only (boxes with a z extent): the first raw-grid position that reaches under the surface
+     * (`sweepGeometryHeightfieldBox`), coarse steps of a quarter sample spacing, at most
+     * `geometry.budgets.maxRayCells` overlap evaluations of `maxTests` reads each. */
+    sweepHeightfieldBoxRaw(from: GeometryHeightfieldBoxRaw, to: GeometryHeightfieldBoxRaw, options?: GeometryBoxOverlapOptions): GeometryHeightfieldSweepHit | null;
+}
+
+/** Detached rectangular 4-neighbor grid, deterministic A* tie order. No nav
+ * service/store/path cache or movement authority is created. */
+export declare const navGrid: (input: ReadonlyArray<ReadonlyArray<boolean>>) => RoomBotNavGrid;
+
+/** Compute delay data; no timer is allocated. All angular helper units are degrees. */
+export declare const reactionDelay: (milliseconds: number, jitterMilliseconds: number, rng: RoomBotRandom) => number;
+
+/** One authoritative actor. This module contains no store, socket or timer. */
+declare class RoomActor<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly id: string;
+    readonly descriptor: RoomDescriptor<S, I, O>;
+    private readonly clock;
+    readonly tenantId: string;
+    private currentState;
+    private lastGoodState;
+    private lastGoodTick;
+    readonly options: (O)["Type"];
+    private readonly members;
+    private readonly grace;
+    private readonly inputs;
+    private readonly outbox;
+    private readonly clientOperations;
+    private readonly schedules;
+    private readonly extensionDurationMs;
+    private readonly extensionOverruns;
+    private tick;
+    private droppedTicks;
+    private commandSeq;
+    readonly epoch: number;
+    private nextTickAt;
+    private emptyAt;
+    private locked;
+    private disposed;
+    private publicationHeldAt;
+    private drainFrozen;
+    private drainAt;
+    private retiring;
+    private faulted;
+    private ticking;
+    private lastNow;
+    private readonly app;
+    private readonly scheduler;
+    private readonly worldPreviews;
+    private readonly worldReceipts;
+    private readonly deferredWorldLeaves;
+    private worldMovement;
+    private worldMovementClamps;
+    private worldMovementMargin;
+    private worldMovementIntents;
+    private worldFinalizationHold;
+    private readonly worldPublishedTransitions;
+    private lifecycleTail;
+    private lifecycleRequests;
+    private lifecycleActive;
+    private readonly geometry;
+    constructor(id: string, descriptor: RoomDescriptor<S, I, O>, initialState: (S)["Type"], options: (O)["Type"], clock: RoomClock, tenantId: string, recovery?: RoomActorRecovery, geometry?: GeometryWorldView);
+    get state(): RoomState<(S)["Type"]>;
+    private now;
+    private ensureOpen;
+    private stage;
+    private schedule;
+    join(client: RoomClient): void;
+    joinAsync(client: RoomClient, signal?: AbortSignal): Promise<void>;
+    /** Only a trusted SQL seat adapter supplies this cursor; player Hello/input
+     * never contains it. The successful lifecycle commits cursor and membership. */
+    /** `authorizeCommit` runs before the join hook and again before publication; the World
+     * member its first run returns reaches `onJoin` as `world`. */
+    joinReservedAsync(client: RoomClient, consumed: RoomConsumedSeat, signal?: AbortSignal, authorizeCommit?: () => Promise<RoomWorldMember | undefined | void>): Promise<void>;
+    /** Trusted Host-only pending membership. The caller must separately establish
+     * current SQL transition/Seat authority; the marker itself grants nothing. */
+    joinWorldReservedAsync(client: RoomClient, consumed: RoomConsumedSeat, authorize: () => Promise<void | 'pending' | 'committed' | 'settled'>, signal?: AbortSignal): Promise<void>;
+    /** The author's view of a transition arrival becoming an active member (`world.onMemberEnter`). */
+    private worldMemberEntered;
+    /** The committed World point of one entity through `world.movement.position`: the last good state, never a
+     * draft. Null without a movement hook, without that entity, or without a finite point. */
+    worldEntityPoint(entityId: string): WorldPoint | null;
+    /** Release only after the Host has persisted actual target enter and rechecked
+     * SQL authority. The retained canonical enter receipt is required locally. */
+    activateWorldReservedAsync(binding: WorldTargetSeatBinding, authorize: () => Promise<void>): Promise<void>;
+    private assertWorldMemberEntity;
+    isWorldPending(sessionId: string): boolean;
+    /** Explicit trusted local-host admission. Authentication still follows the
+     * descriptor; the resulting capability is bound to this exact Member object,
+     * so a stale bot cannot submit to or release a later reused session ID. */
+    joinBotAsync(client: RoomClient, countsAsPlayer?: boolean, signal?: AbortSignal): Promise<RoomActorBotLease>;
+    playerCount(): number;
+    availablePlayerSlots(): number;
+    monotonicNow(): number;
+    roster(): ReadonlyArray<Pick<RoomClient, 'sessionId' | 'subjectId' | 'tenantId'> & {
+        readonly isBot: boolean;
+        readonly countsAsPlayer: boolean;
+    }>;
+    /** Check identity/lock and current counted/grace capacity before replacing a
+     * bot. Full prepareJoin repeats these immediately before membership commit. */
+    humanAdmissionNeedsReplacement(client: RoomClient): boolean;
+    private prepareClientIdentity;
+    private prepareJoin;
+    leave(sessionId: string, reason?: RoomLeaveReason): void;
+    leaveAsync(sessionId: string, reason?: RoomLeaveReason, signal?: AbortSignal): Promise<void>;
+    private prepareLeave;
+    private assertWorldArrival;
+    private enterWorldDraft;
+    /** Execute actual target admission on an isolated draft. Nothing is published
+     * or receipted here. Author Effects receive prepare phase and must supply their
+     * own external idempotency/compensation; this is not an ownership commit. */
+    previewWorldEnter(input: Parameters<RoomActor<S, I, O>['applyWorldHook']>[1], maxBytes: number, signal?: AbortSignal): Promise<void>;
+    /** Trusted server lifecycle only. The caller supplies the configured World
+     * byte budget and current epoch; this grants no SQL/transition admission. */
+    applyWorldHook(operation: 'enter' | 'exit' | 'ghost', input: RoomWorldHookInput<RoomWorldEntity<(S)["Type"]>>, maxBytes: number, signal?: AbortSignal, authorizeCommit?: () => Promise<void>, replaceExitReceipt?: boolean, previousGhost?: RoomWorldHookInput<RoomWorldEntity<(S)["Type"]>>, retainGhostProjection?: boolean, promoteGhosts?: ReadonlyArray<RoomWorldHookInput<RoomWorldEntity<(S)["Type"]>>>): Promise<void>;
+    private assertWorldHookResult;
+    private assertWorldEnterVacant;
+    /** Trusted Host terminal-proof path only; it checkpoints the removal before
+     * returning. No gameplay state or external effect is undone here. */
+    retireWorldReceipt(requestId: string, operation: 'enter' | 'exit' | 'ghost'): Promise<void>;
+    /** Failed transition compensation, guarded before draft publication. The
+     * author removes its projection in onGhost phase rollback; no source rewind. */
+    cancelWorldGhost(input: Parameters<RoomActor<S, I, O>['applyWorldHook']>[1], maxBytes: number, authorize: () => Promise<void>): Promise<void>;
+    cancelWorldPreview(requestId: string, authorize: () => Promise<void>): Promise<void>;
+    hasWorldReceipt(requestId: string, operation: 'enter' | 'exit' | 'ghost'): boolean;
+    worldReceiptSnapshot(): ReadonlyArray<RoomWorldReceipt>;
+    /** Capture the actual current actor entity, never a caller-provided replacement.
+     * Returned data is detached bounded JSON; persistence remains outside the tick. */
+    captureWorldEntity(entityId: string, epoch: number, maxBytes: number): Promise<{
+        readonly entity: RoomWorldEntity<(S)["Type"]>;
+        readonly data: unknown;
+    }>;
+    configureWorldCellMovement(epoch: number, bounds?: WorldBounds, marginUnits?: number): Promise<void>;
+    worldMovementSnapshot(): {
+        readonly bound: boolean;
+        readonly clamped: number;
+    };
+    captureWorldMovement(epoch: number): Promise<WorldMovementObservation>;
+    private constrainWorldMovement;
+    listWorldEntityIds(epoch: number, maximum: number, maxBytes: number): Promise<ReadonlyArray<string>>;
+    captureWorldProjection(entityId: string, epoch: number, maxBytes: number): Promise<{
+        readonly entity: RoomWorldEntity<(S)["Type"]>;
+        readonly data: unknown;
+        readonly tick: number;
+    }>;
+    private captureWorldEntityOwned;
+    /** Trusted Host handoff: one bounded room hold survives ambiguous durable writes.
+     * Completion must follow checkpoint acknowledgement; never release by timeout. */
+    finalizeWorldExit(input: {
+        readonly afterglow?: {
+            readonly requestId: string;
+            readonly expiresAt: number;
+        };
+        readonly subjectId?: string;
+        readonly epoch: number;
+        readonly entityId: string;
+        readonly requestId: string;
+        readonly location: WorldEntityLocation;
+    }, maxBytes: number, retain: (capture: {
+        readonly entity: RoomWorldEntity<(S)["Type"]>;
+        readonly data: unknown;
+    }) => Promise<void>, authorize: () => Promise<void>, expectedEntity?: unknown, signal?: AbortSignal): Promise<void>;
+    /** The actual Runtime supplies the synchronous bounded reliable enqueue. No
+     * network completion is awaited while the lifecycle/SQL fence is held. */
+    notifyWorldHandoff(input: Omit<RoomWorldHandoffFrame, 'tick'>, authorize: () => Promise<void>, enqueue: (frame: RoomWorldHandoffFrame) => void): Promise<void>;
+    /** Only the actual Host may call this after its durable checkpoint succeeds. */
+    completeWorldFinalization(requestId: string, authorize: () => Promise<void>): Promise<void>;
+    worldFinalizationAfterglow(): {
+        readonly requestId: string;
+        readonly expiresAt: number;
+    } | undefined;
+    worldFinalizationRequest(): string | null;
+    isWorldFinalizationHeld(): boolean;
+    /** Recovery-only source reconstruction from final durable capture. Caller owns
+     * unpublished successor/recovery authority and checkpoints before fence clear. */
+    reconcileWorldSource(input: {
+        readonly epoch: number;
+        readonly requestId: string;
+        readonly entity: RoomWorldEntity<(S)["Type"]>;
+        readonly location: WorldEntityLocation;
+    }, maxBytes: number, authorize: () => Promise<void>, signal?: AbortSignal): Promise<void>;
+    private assertSynchronousLifecycle;
+    private serializeLifecycle;
+    private mutateMemberAsync;
+    private pruneGrace;
+    private mutateMember;
+    /** encodedBytes is measured by the host transport, never supplied by a player. */
+    input(sessionId: string, seq: number, tickHint: number, payload: unknown, encodedBytes: number): boolean;
+    private send;
+    private extension;
+    holdPublication(): void;
+    releasePublication(): void;
+    /** Called by the host's single monotonic loop. Catch-up never spins unbounded. */
+    advance(): number;
+    drainOutbox(): ReadonlyArray<RoomOutboxCommand>;
+    private stageClientOperation;
+    /** Transport callbacks are invoked only by the supervisor after advance. */
+    flushClientOperations(): void;
+    /** Ordinary socket members and reconnect grace only. Local bots own no SQL
+     * seat. Queued-but-unapplied inputs never become applied receipts; discarded
+     * pending World inputs carry a separate durable rejection cursor. */
+    inputReceiptSnapshot(): ReadonlyArray<RoomInputReceipt>;
+    /** Runtime-only confirmation after the actual checkpoint port acknowledges.
+     * Inputs arriving during the write remain unconfirmed and block activation. */
+    confirmInputCheckpoint(receipts: ReadonlyArray<RoomInputReceipt>): void;
+    lastAppliedInputSeq(sessionId: string): number;
+    lock(): void;
+    unlock(): void;
+    dispose(): void;
+    isDisposed(): boolean;
+    isLifecycleBusy(): boolean;
+    /** Permanent local simulation fence before the final planned-handoff snapshot. */
+    freezeForDrain(): Promise<void>;
+    /** Only after real SQL ownership handoff. No leave/dispose game hooks, SQL,
+     * or new commands may run after the saved state has moved to its successor. */
+    releaseTransferred(): void;
+    disposeAsync(signal?: AbortSignal): Promise<void>;
+    isRetiring(): boolean;
+    /** Only the supervisor calls this after the final hibernated SQL receipt.
+     * Hibernate pauses a durable room; it must not run game-ending onDispose. */
+    releaseHibernated(): void;
+    isFaulted(): boolean;
+    commandCursor(): number;
+    scheduleSnapshot(): ReadonlyArray<RoomScheduleSnapshot>;
+    lastGoodSnapshot(): {
+        readonly tick: number;
+        readonly state: RoomState<(S)["Type"]>;
+    };
+    metrics(): RoomActorMetrics;
+}
+
+declare interface RoomActorBotLease {
+    readonly sessionId: string;
+    isCurrent(): boolean;
+    input(seq: number, tickHint: number, payload: unknown, encodedBytes: number): boolean;
+    leave(signal?: AbortSignal): Promise<void>;
+}
+
+declare interface RoomActorMetrics {
+    readonly tick: number;
+    readonly droppedTicks: number;
+    readonly queuedInputs: number;
+    readonly outboxCommands: number;
+    readonly clients: number;
+    readonly extensionDurationMs: Readonly<Record<string, number>>;
+    readonly extensionOverruns: Readonly<Record<string, number>>;
+}
+
+declare interface RoomActorRecovery {
+    /** SQL ownership generation; a new owner must use a strictly newer epoch. */
+    readonly epoch: number;
+    readonly commandCursor: number;
+    readonly tick?: number;
+    readonly rehydrate?: boolean;
+    readonly worldReceipts?: ReadonlyArray<RoomWorldReceipt> | undefined;
+    readonly schedules?: ReadonlyArray<RoomScheduleSnapshot>;
+}
+
+/** Commands are staged in memory and drained outside the tick. */
+declare interface RoomAppBridge {
+    publish(event: string, payload: unknown, options: {
+        readonly key: string;
+    }): string;
+    run(descriptor: string, input: unknown): string;
+}
+
+declare interface RoomAuthoringStrategies<S = unknown> {
+    readonly budgets?: (options: Readonly<Partial<RoomBudgets>>) => RoomBudgets;
+    readonly reconnectPolicy?: (options: Readonly<Partial<{
+        readonly graceMs: number;
+    }>>) => {
+        readonly graceMs: number;
+    };
+    readonly snapshotPolicy?: (options: Readonly<Partial<RoomSnapshotPolicy<S>>>) => RoomSnapshotPolicy<S>;
+    readonly spectatorPolicy?: (options: Readonly<Partial<RoomSpectatorPolicy>>) => RoomSpectatorPolicy;
+}
+
+export declare interface RoomBotBehavior<V extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, M extends Schema.Codec<unknown, unknown>> {
+    readonly name: string;
+    readonly view: V;
+    readonly input: I;
+    readonly memory: M;
+    readonly initialMemory: () => (M)["Type"];
+    readonly decide: (context: RoomBotDecisionContext<(V)["Type"], (M)["Type"]>) => ReadonlyArray<(I)["Type"]>;
+    readonly maxInputs?: number;
+    readonly maxRandomDraws?: number;
+}
+
+/** No actor state, seat, clock, timer, socket or store. Explicit send-cadence
+ * calls commit detached memory only after every intention passes its schema.
+ * Rejected decisions retain bounded random draws, so retry consumes the same
+ * stream rather than silently advancing the caller's generator again. */
+export declare class RoomBotBrain<V extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, M extends Schema.Codec<unknown, unknown>> {
+    private readonly rng;
+    readonly descriptor: RoomBotDescriptor<V, I, M>;
+    private memory;
+    private lastTick;
+    private readonly pendingRandom;
+    private deciding;
+    private decision;
+    constructor(descriptor: RoomBotDescriptor<V, I, M>, rng: RoomBotRandom);
+    step(view: unknown, tick: number, difficulty?: number): ReadonlyArray<(I)["Encoded"]>;
+    snapshot(): RoomBotBrainSnapshot<(M)["Type"]>;
+    restore(snapshot: RoomBotBrainSnapshot<(M)["Type"]>): void;
+}
+
+export declare interface RoomBotBrainSnapshot<M> {
+    readonly version: 1;
+    readonly memory: M;
+    readonly lastTick: number | null;
+    readonly pendingRandom: ReadonlyArray<number>;
+}
+
+export declare interface RoomBotDecisionContext<V, M> {
+    readonly view: V;
+    readonly memory: RoomState<M>;
+    readonly tick: number;
+    readonly difficulty: number;
+    readonly rng: RoomBotRandom;
+}
+
+export declare interface RoomBotDescriptor<V extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, M extends Schema.Codec<unknown, unknown>> extends Omit<RoomBotBehavior<V, I, M>, 'maxInputs' | 'maxRandomDraws'> {
+    readonly _tag: 'RoomBotDescriptor';
+    readonly maxInputs: number;
+    readonly maxRandomDraws: number;
+}
+
+/** Host-owned local fill. Explicit identities/RNG are mandatory; there is no
+ * fabricated Subject, remote credential, durable counter or SQL capacity claim.
+ * The host calls turn/admitHuman/close outside simulation and owns SQL seat
+ * coordination before integrating this helper into ordinary reservations. */
+export declare class RoomBotFill<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    private readonly actor;
+    private readonly options;
+    private readonly startedAt;
+    private lastTime;
+    private ordinal;
+    private readonly bots;
+    private current;
+    private kind;
+    private stopped;
+    private closing;
+    constructor(actor: RoomActor<S, I, O>, input: RoomBotFillOptions<S, I, O>);
+    metrics(): {
+        readonly humans: number;
+        readonly bots: number;
+        readonly npcs: number;
+        readonly ownedBots: number;
+    };
+    private desiredBots;
+    private execute;
+    turn(): Promise<void>;
+    /** Local capacity replacement is ordered leave -> ordinary human join. It is
+     * not an atomic SQL reservation and failed human join does not undo onLeave. */
+    admitHuman(client: RoomClient, signal?: AbortSignal): Promise<void>;
+    fence(): void;
+    close(): Promise<void>;
+}
+
+export declare interface RoomBotFillContext<S, O> {
+    readonly state: S;
+    readonly options: O;
+    readonly tick: number;
+    readonly roster: ReadonlyArray<RoomLocalBotIdentity & {
+        readonly isBot: boolean;
+        readonly countsAsPlayer: boolean;
+    }>;
+}
+
+export declare interface RoomBotFillOptions<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly toMin: number;
+    readonly afterMs?: number;
+    readonly removeWhenHuman?: boolean;
+    readonly behaviors: ReadonlyArray<RoomBotDescriptor<S, I, Schema.Codec<any, any>>>;
+    readonly makeIdentity: (ordinal: number) => RoomLocalBotIdentity;
+    readonly random: (ordinal: number) => RoomBotRandom;
+    readonly difficultyFrom?: (context: RoomBotFillContext<(S)["Type"], (O)["Type"]>) => number;
+}
+
+/** Explicit local host composition. Owns one actual actor Member capability;
+ * every intention goes through the normal actor schema/rate/byte/queue path.
+ * No SQL seat, provider, socket, timer or automatic runtime install is implied. */
+export declare class RoomBotLocalClient<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>, M extends Schema.Codec<unknown, unknown>> {
+    private readonly actor;
+    readonly identity: RoomLocalBotIdentity;
+    readonly countsAsPlayer: boolean;
+    private readonly brain;
+    private readonly codec;
+    private readonly now;
+    private readonly interval;
+    private readonly difficulty;
+    private readonly view;
+    private lease;
+    private nextSendAt;
+    private lastTime;
+    private sequence;
+    private stopped;
+    private cleaned;
+    private closing;
+    private failed;
+    private constructor();
+    static attach<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>, M extends Schema.Codec<unknown, unknown>>(actor: RoomActor<S, I, O>, identity: RoomLocalBotIdentity, descriptor: RoomBotDescriptor<S, I, M>, rng: RoomBotRandom, options?: RoomLocalBotOptions): Promise<RoomBotLocalClient<S, I, O, M>>;
+    get failure(): RoomBotNetworkFailure | null;
+    get isClosed(): boolean;
+    isCurrent(): boolean;
+    snapshot(): RoomBotBrainSnapshot<(M)["Type"]>;
+    turn(): ReadonlyArray<number>;
+    fence(): void;
+    /** Cleanup failures keep the exact lease for another cleanup attempt. Prior
+     * decision failure remains in failure; successful cleanup does not erase it. */
+    close(): Promise<void>;
+}
+
+export declare interface RoomBotNavGrid {
+    readonly width: number;
+    readonly height: number;
+    path(start: RoomBotVector, destination: RoomBotVector, maxVisited?: number): ReadonlyArray<RoomBotVector> | null;
+}
+
+/** Explicitly driven load/test client over the ordinary RoomConnection. It
+ * borrows that connection, reads only its delivered projection and submits
+ * intentions through its normal input/reconnect history. A failed send is an
+ * uncertain outcome: retain the failure and never assign a replacement input
+ * sequence. The connection itself may replay its original pending sequence. */
+export declare class RoomBotNetworkClient<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, M extends Schema.Codec<unknown, unknown>, JoinInput> {
+    private readonly connection;
+    private readonly brain;
+    private readonly now;
+    private readonly send;
+    private readonly interval;
+    private readonly difficulty;
+    private nextSendAt;
+    private lastTime;
+    private current;
+    private stopped;
+    private failed;
+    private submitted;
+    constructor(connection: RoomConnection<S, I, JoinInput>, descriptor: RoomBotDescriptor<S, I, M>, rng: RoomBotRandom, clock: RoomClock, options: RoomBotNetworkOptions);
+    get failure(): RoomBotNetworkFailure | null;
+    /** Submitted counts are local completed sends, never applied ACKs/throughput. */
+    metrics(): {
+        readonly submitted: number;
+        readonly stopped: boolean;
+        readonly failed: boolean;
+    };
+    snapshot(): RoomBotBrainSnapshot<(M)["Type"]>;
+    turn(): Promise<ReadonlyArray<number>>;
+    private execute;
+    /** Fencing prevents another decision/send; an already accepted send is awaited.
+     * Closing this borrowed wrapper never closes the app-owned connection. */
+    fence(): void;
+    close(): Promise<void>;
+}
+
+export declare interface RoomBotNetworkFailure {
+    readonly tick: number;
+    readonly intentionIndex: number | null;
+    readonly cause: unknown;
+}
+
+export declare interface RoomBotNetworkOptions {
+    readonly sendRate: number;
+    readonly difficulty?: number;
+}
+
+export declare type RoomBotRandom = () => number;
+
+export declare interface RoomBotUtilityAction<C, A> {
+    readonly id: string;
+    readonly action: A;
+    readonly score: (context: C) => number;
+}
+
+export declare interface RoomBotVector {
+    readonly x: number;
+    readonly y: number;
+}
+
+declare interface RoomBudgets {
+    readonly inputsPerSecond: number;
+    readonly bytesPerSecond: number;
+    readonly burst: number;
+    readonly maxQueuedInputs: number;
+    readonly maxOutboxCommands: number;
+    readonly maxScheduledHooks: number;
+    readonly maxQueuedLifecycleHooks: number;
+    readonly maxNpcs: number;
+    /** A player input acting on state older than this many milliseconds behind the newest state
+     * the Host sent that client is dropped (it arrived too late to apply fairly). */
+    readonly inputLatencyBudgetMs: number;
+}
+
+declare interface RoomChannel {
+    readonly schema: Schema.Codec<unknown, unknown>;
+    readonly direction: 'both' | 'server' | 'client';
+    readonly reliable: boolean;
+}
+
+declare interface RoomClient {
+    readonly sessionId: string;
+    readonly subjectId: string | null;
+    readonly tenantId: string;
+    /** App data the API resolved for this seat (`seatAttributes` on the Rooms API binding), signed into
+     * the seat; absent without one. Not a secret from the player: it travels in their seat token. */
+    readonly attributes?: RoomSeatAttributes | undefined;
+    /** Actor-owned classification, never accepted from a socket input. */
+    readonly isBot?: boolean | undefined;
+    readonly countsAsPlayer?: boolean | undefined;
+    send(channel: string, payload: unknown): void;
+    kick(reason: string): void;
+}
+
+/** API-facing reservation result. Credentials are retained only for Hello. */
+declare interface RoomClientReservation {
+    readonly roomId: string;
+    readonly sessionId: string;
+    readonly token: Uint8Array;
+    readonly address: string;
+    readonly expiresAt: number;
+    readonly endpoints?: RoomTransportEndpoints | undefined;
+}
+
+declare interface RoomClock {
+    now(): number;
+}
+
+declare type RoomClockPingCadence = (joinedForMs: number) => number;
+
+declare interface RoomClockSamplingOptions {
+    readonly maxPendingPings: number;
+    readonly pingTimeoutMs: number;
+}
+
+/** Framework-free reserve -> transport -> Hello orchestration. It preserves
+ * the last authoritative state during reconnect and never writes a token to
+ * persistent storage. RPC facade/platform/render-hook integration is pending. */
+declare class RoomConnection<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, JoinInput> {
+    readonly manifest: RoomWireManifest<S, I>;
+    readonly clock: RoomClock;
+    readonly reservations: RoomReservationClient<JoinInput>;
+    readonly connect: (address: string, signal: AbortSignal, endpoints?: RoomTransportEndpoints) => Promise<RoomTransport>;
+    private readonly controller;
+    private readonly listeners;
+    private readonly buffered;
+    private readonly pendingInputs;
+    private readonly options;
+    private session;
+    private handoffDetach;
+    private readonly handoffListeners;
+    private sessionDetach;
+    private currentState;
+    private currentStatus;
+    private currentError;
+    private reconnectTask;
+    private startTask;
+    private started;
+    private leaving;
+    private lastSessionId;
+    private lastTick;
+    private nextSeq;
+    private appliedSeq;
+    private clockTimer;
+    private readonly messageListeners;
+    private readonly messageDetach;
+    private reservation;
+    private readonly cleanupTasks;
+    private readonly cleanupFailures;
+    private pendingReservationCalls;
+    private pendingTransportCalls;
+    private readonly transportOwners;
+    private readonly transportLifetimes;
+    private withdrawalAttempted;
+    private leaveTask;
+    private left;
+    constructor(manifest: RoomWireManifest<S, I>, clock: RoomClock, reservations: RoomReservationClient<JoinInput>, connect: (address: string, signal: AbortSignal, endpoints?: RoomTransportEndpoints) => Promise<RoomTransport>, options: RoomConnectionOptions);
+    /* Excluded from this release type: captureGeometrySession */
+    /** `waking`: the pool scaled to zero and is starting a host; entry continues on its own. */
+    get status(): RoomSessionStatus | 'reserving' | 'waking';
+    get error(): unknown;
+    get state(): (S)["Type"] | null;
+    get id(): string | null;
+    /** Reserved Room identity, without exposing its seat credential. */
+    get roomId(): string | null;
+    get lastAppliedTick(): number;
+    get lastAppliedInputSeq(): number;
+    /** Exact current-session pairing; epoch changes need prediction reset. */
+    get reconciliationSnapshot(): RoomReconciliationSnapshot<(S)["Type"]> | null;
+    deliveredSnapshot(): RoomDeliveredState<(S)["Type"]> | null;
+    clockStats(): {
+        readonly rttMs: number | null;
+        readonly offsetMs: number | null;
+    };
+    serverNow(): number | null;
+    /** The current session's estimated datagram loss (0–1), null until measured. */
+    get lossRate(): number | null;
+    subscribe(listener: () => void): () => void;
+    private notify;
+    private active;
+    start(input: JoinInput): Promise<void>;
+    private attempt;
+    private install;
+    private waitForJoin;
+    private beginReconnect;
+    send(input: (I)["Type"]): Promise<number>;
+    private submit;
+    message(channel: string, payload: unknown): Promise<void>;
+    onWorldHandoff(listener: (frame: RoomWorldHandoffFrame) => void): () => void;
+    onMessage(channel: string, listener: (payload: unknown) => void): () => void;
+    private attachMessages;
+    private requestReservation;
+    private releaseReservation;
+    private stopClockSampling;
+    private releaseTransport;
+    private retainTransport;
+    private runTransportCleanup;
+    private startClockSampling;
+    private terminal;
+    leave(): Promise<void>;
+    private withdraw;
+}
+
+declare interface RoomConnectionOptions {
+    readonly graceMs: number;
+    readonly maxBufferedInputs?: number;
+    readonly maxPendingInputs?: number;
+    readonly initialBackoffMs?: number;
+    readonly maxBackoffMs?: number;
+    readonly connectTimeoutMs?: number;
+    readonly random?: () => number;
+    readonly sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+    readonly reconnectPolicy?: RoomReconnectPolicy;
+    readonly clockSampling?: RoomClockSamplingOptions;
+    readonly inputRedundancy?: RoomInputRedundancyOptions;
+    readonly clockPingCadence?: RoomClockPingCadence;
+    readonly maxPendingReservationCalls?: number;
+    readonly maxCleanupFailures?: number;
+    readonly maxPendingTransportCalls?: number;
+    /** How long entry keeps waiting while a scaled-to-zero pool starts a host (`RoomPoolWaking`). Default 180000. */
+    readonly wakeTimeoutMs?: number;
+}
+
+declare interface RoomConsumedSeat {
+    readonly lastAppliedSeq: number;
+    readonly discardedThrough?: number;
+    readonly worldTarget?: WorldTargetSeatBinding;
+}
+
+declare interface RoomDatagramLane {
+    readonly maxDatagramBytes: number;
+    send(frame: Uint8Array): void;
+    onFrame(listener: (frame: Uint8Array, receivedAt: number) => void): () => void;
+}
+
+declare interface RoomDefinition<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly name: string;
+    readonly mode?: 'state-sync';
+    readonly state: S;
+    readonly auth?: 'subject' | 'public';
+    readonly guards?: DeclaredAccess;
+    readonly openAccess?: string | undefined;
+    readonly input: I;
+    readonly options: O;
+    /** Author-owned initial state; no game values are guessed by the host. */
+    readonly initialState?: (options: (O)["Type"]) => (S)["Type"];
+    readonly tickRate?: number;
+    readonly sendRate?: number;
+    readonly maxClients?: number;
+    readonly maxCatchUpTicks?: number;
+    readonly lifecycleTimeoutMs?: number;
+    readonly budgets?: Partial<RoomBudgets>;
+    readonly strategies?: RoomAuthoringStrategies<(S)["Type"]> | undefined;
+    readonly reconnect?: {
+        readonly graceMs: number;
+    };
+    readonly autoDispose?: {
+        readonly afterEmptyMs: number;
+        readonly hibernate?: boolean;
+    };
+    readonly snapshot?: Partial<RoomSnapshotPolicy<(S)["Type"]>>;
+    /** Opt-in shared history; host must supply the actual common view/admission. */
+    readonly spectator?: Partial<RoomSpectatorPolicy> | undefined;
+    readonly messages?: Readonly<Record<string, RoomChannel>>;
+    readonly view?: (context: RoomViewContext<(S)["Type"]>) => (S)["Type"];
+    readonly viewBudgetMs?: number;
+    /** How the Room appears in `rooms.list`, derived from its state: `private` takes it off the list
+     * (it stays joinable by ID), `locked` refuses every new seat, `metadata` is shown to listers.
+     * Omitted fields keep their current value. The Host writes a change with the next checkpoint,
+     * which a change triggers at once. Synchronous and pure, like `view`. */
+    readonly listing?: (context: RoomListingContext<(S)["Type"], (O)["Type"]>) => RoomListing;
+    readonly extensions?: ReadonlyArray<RoomExtension<(S)["Type"], (I)["Type"]>>;
+    readonly world?: RoomWorldHooks<(S)["Type"]> | undefined;
+    readonly onCreate?: RoomSyncHook<Omit<RoomMemberContext<(S)["Type"], (O)["Type"]>, 'client'>>;
+    readonly onRehydrate?: RoomSyncHook<Omit<RoomMemberContext<(S)["Type"], (O)["Type"]>, 'client'>>;
+    readonly onJoin?: RoomLifecycleHook<RoomMemberContext<(S)["Type"], (O)["Type"]>>;
+    readonly onLeave?: RoomLifecycleHook<RoomMemberContext<(S)["Type"], (O)["Type"]> & {
+        readonly reason: RoomLeaveReason;
+    }>;
+    readonly onTick: RoomSyncHook<RoomTickContext<(S)["Type"], (I)["Type"]>>;
+    readonly onSchedule?: RoomSyncHook<RoomTickContext<(S)["Type"], (I)["Type"]> & {
+        readonly label: string;
+    }>;
+    readonly onDispose?: RoomLifecycleHook<{
+        readonly state: RoomState<(S)["Type"]> | undefined;
+        readonly app: RoomAppBridge;
+        readonly geometry?: GeometryWorldView;
+    }> | undefined;
+}
+
+declare interface RoomDeliveredState<S> {
+    readonly epoch: number;
+    readonly tick: number;
+    /** Local transport observation, not an authoritative server timestamp. */
+    readonly receivedAt: number;
+    readonly state: S;
+}
+
+declare interface RoomDescriptor<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> extends RoomDefinition<S, I, O> {
+    readonly _tag: 'RoomDescriptor';
+    readonly auth: 'subject' | 'public';
+    readonly guards: DeclaredAccess;
+    readonly tickRate: number;
+    readonly sendRate: number;
+    readonly maxClients: number;
+    readonly maxCatchUpTicks: number;
+    readonly lifecycleTimeoutMs: number;
+    readonly budgets: RoomBudgets;
+    readonly view: (context: RoomViewContext<(S)["Type"]>) => (S)["Type"];
+    readonly reconnect: {
+        readonly graceMs: number;
+    };
+    readonly autoDispose: {
+        readonly afterEmptyMs: number;
+        readonly hibernate: boolean;
+    };
+    readonly snapshot: RoomSnapshotPolicy<(S)["Type"]>;
+    readonly spectator?: RoomSpectatorPolicy | undefined;
+    readonly messages: Readonly<Record<string, RoomChannel>>;
+    readonly viewBudgetMs: number;
+    readonly extensions: ReadonlyArray<RoomExtension<(S)["Type"], (I)["Type"]>>;
+}
+
+declare interface RoomExtension<S, I> {
+    readonly name: string;
+    readonly fields: ReadonlyArray<Extract<keyof S, string>>;
+    readonly channel: string;
+    readonly tickBudgetMs: number;
+    readonly beforeTick?: RoomSyncHook<RoomExtensionContext<S, I>>;
+    readonly afterTick?: RoomSyncHook<RoomExtensionContext<S, I>>;
+}
+
+declare interface RoomExtensionContext<S, I> {
+    /** Prepared native CPU queries only, installed before actor lifecycle. */
+    readonly geometry?: GeometryWorldView | undefined;
+    readonly state: RoomState<Partial<S>>;
+    readonly tick: number;
+    readonly dt: number;
+    readonly inputs: ReadonlyArray<Omit<RoomInput<I>, 'client'> & {
+        readonly client: Pick<RoomClient, 'sessionId' | 'subjectId' | 'tenantId' | 'isBot' | 'countsAsPlayer' | 'attributes'>;
+    }>;
+    readonly clock: RoomClock;
+    send(sessionId: string, payload: unknown): void;
+}
+
+declare interface RoomInput<I> {
+    readonly client: RoomClient;
+    readonly seq: number;
+    readonly tickHint: number;
+    readonly input: I;
+}
+
+/** Captured outside the tick and stored with the exact state it describes. */
+declare interface RoomInputReceipt {
+    readonly sessionId: string;
+    readonly subjectId: string | null;
+    readonly lastAppliedSeq: number;
+    /** Intentionally discarded pending World input; never an applied ACK. */
+    readonly discardedThrough?: number;
+}
+
+declare interface RoomInputRedundancyOptions {
+    /** Input count is a redundancy budget, never a delivery guarantee. */
+    readonly inputRedundancy: number;
+    readonly maxInputHistoryBytes: number;
+}
+
+declare type RoomLeaveReason = 'left' | 'kicked' | 'reconnecting' | 'timeout' | 'disposed';
+
+/** Lifecycle Effects are run by the host outside the synchronous tick. `void` admits block bodies;
+ * a returned Promise is refused at runtime with an authoring error. */
+declare type RoomLifecycleHook<C> = (context: C) => void | Effect.Effect<void, unknown>;
+
+/** A Room's own listing; scalar metadata only, at most 16 keys and 2 KiB. */
+declare interface RoomListing {
+    readonly metadata?: Readonly<Record<string, RoomScalar>>;
+    readonly private?: boolean;
+    readonly locked?: boolean;
+}
+
+declare interface RoomListingContext<S, O> {
+    readonly state: S;
+    readonly options: O;
+}
+
+export declare type RoomLocalBotIdentity = Pick<RoomClient, 'sessionId' | 'subjectId' | 'tenantId'>;
+
+export declare interface RoomLocalBotOptions {
+    readonly sendRate?: number;
+    readonly difficulty?: number;
+    readonly countsAsPlayer?: boolean | undefined;
+}
+
+declare interface RoomMemberContext<S, O> {
+    /** Prepared native CPU queries only, installed before actor lifecycle. */
+    readonly geometry?: GeometryWorldView | undefined;
+    readonly state: RoomState<S>;
+    readonly options: O;
+    readonly client: RoomClient;
+    readonly app: RoomAppBridge;
+    readonly clock: RoomClock;
+    readonly scheduler: RoomScheduler;
+    /** World Rooms, ordinary player join: the server-owned entity this Session controls and
+     * its last persisted `persistEntity` data. Build the state entity from it when absent. */
+    readonly world?: RoomWorldMember | undefined;
+}
+
+declare interface RoomOutboxCommand {
+    readonly requestId: string;
+    readonly kind: 'publish' | 'run';
+    readonly name: string;
+    readonly payload: unknown;
+    readonly key?: string;
+}
+
+/** Framework-free binary session core. Reservation, reconnect orchestration and
+ * render hooks are separate; this core never persists a seat token. */
+declare interface RoomReconciliationSnapshot<S> {
+    readonly epoch: number;
+    readonly tick: number;
+    readonly lastAppliedSeq: number;
+    readonly state: S;
+}
+
+declare type RoomReconnectPolicy = (input: RoomReconnectPolicyInput) => number;
+
+declare interface RoomReconnectPolicyInput {
+    readonly attempt: number;
+    readonly initialBackoffMs: number;
+    readonly maxBackoffMs: number;
+    readonly remainingMs: number;
+    readonly random: number;
+}
+
+declare interface RoomReliableLane {
+    send(frame: Uint8Array): Promise<void>;
+    onFrame(listener: (frame: Uint8Array, receivedAt: number) => void): () => void;
+}
+
+declare interface RoomReservationClient<JoinInput> {
+    reserve(input: JoinInput, signal: AbortSignal): Promise<RoomClientReservation>;
+    resume(sessionId: string, signal: AbortSignal): Promise<RoomClientReservation>;
+    release?(sessionId: string, token: Uint8Array, signal: AbortSignal): Promise<void>;
+}
+
+declare type RoomScalar = string | number | boolean | null;
+
+declare interface RoomScheduler {
+    after(milliseconds: number, label: string): void;
+    every(milliseconds: number, label: string): void;
+    cancel(label: string): void;
+}
+
+declare interface RoomScheduleSnapshot {
+    readonly label: string;
+    readonly remainingMs: number;
+    readonly intervalMs: number | null;
+}
+
+/** App data for one seat, resolved by the API when the seat is reserved (`seatAttributes`) and signed
+ * into it; scalars only, at most 16 keys and 2 KiB. */
+declare type RoomSeatAttributes = Readonly<Record<string, RoomScalar>>;
+
+declare type RoomSessionStatus = 'connecting' | 'joined' | 'reconnecting' | 'left' | 'kicked' | 'gone';
+
+declare interface RoomSnapshotPolicy<S> {
+    readonly everyMs: number;
+    readonly onlyIfChanged: boolean;
+    readonly mode: 'full' | 'delta';
+    readonly fullEvery: number;
+    readonly keepFulls: number;
+    readonly store: 'auto';
+    /** Maximum inline codec payload; the host may impose a smaller cutoff. */
+    readonly maxInlineBytes: number;
+    /** Full-schema projection of volatile data; never a partial-state format. */
+    readonly pick: (state: S) => S;
+}
+
+declare interface RoomSpectatorPolicy {
+    readonly delayMs: number;
+    readonly retentionMs: number;
+    readonly maxFrames: number;
+    readonly maxBytes: number;
+    readonly maxFrameBytes: number;
+    readonly checkpointEveryMs: number;
+    readonly maxDeliveryFrames: number;
+}
+
+/** Plain mutable state; the author receives no store or database capability. */
+declare type RoomState<A> = A extends ReadonlyArray<infer V> ? Array<RoomState<V>> : A extends object ? {
+    -readonly [K in keyof A]: RoomState<A[K]>;
+} : A;
+
+/** Synchronous hook. `void` admits parameterless block bodies (TypeScript cannot narrow those to
+ * `undefined`); any returned value, a Promise included, is refused at runtime with an authoring error. */
+declare type RoomSyncHook<C> = (context: C) => void;
+
+declare interface RoomTickContext<S, I> {
+    /** Prepared native CPU queries only, installed before actor lifecycle. */
+    readonly geometry?: GeometryWorldView | undefined;
+    readonly state: RoomState<S>;
+    readonly tick: number;
+    readonly dt: number;
+    readonly inputs: ReadonlyArray<RoomInput<I>>;
+    readonly app: RoomAppBridge;
+    readonly clock: RoomClock;
+    readonly scheduler: RoomScheduler;
+    broadcast(channel: string, payload: unknown): void;
+}
+
+declare interface RoomTransport {
+    readonly name: 'ws' | 'wt';
+    readonly reliable: RoomReliableLane;
+    readonly unreliable?: RoomDatagramLane | undefined;
+    readonly signal: AbortSignal;
+    stats(): {
+        readonly rttMs: number | null;
+        readonly queuedBytes: number;
+        readonly droppedDatagrams: number;
+    };
+    close(code: number, reason: string): void;
+    /** When provided, joins actual parent/stream withdrawal and permits retry.
+     * Synchronous close alone does not establish native terminal evidence. */
+    closeAsync?(code: number, reason: string): Promise<void>;
+}
+
+/** Public routing metadata only. Neither endpoint conveys seat authority. */
+declare interface RoomTransportEndpoints {
+    readonly ws: string;
+    readonly wt?: string | undefined;
+    /** Base64 SHA-256 of a short-lived development certificate the browser pins
+     * through `serverCertificateHashes`. Absent for a publicly trusted certificate. */
+    readonly wtCertificateHash?: string | undefined;
+}
+
+declare interface RoomViewContext<S> {
+    readonly state: S;
+    readonly client: Pick<RoomClient, 'sessionId' | 'subjectId' | 'tenantId' | 'isBot' | 'countsAsPlayer' | 'attributes'>;
+    readonly role: 'player' | 'spectator';
+    readonly tick: number;
+}
+
+declare interface RoomWireManifest<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>> {
+    readonly state: S;
+    readonly input: I;
+    readonly messages?: Readonly<Record<string, RoomChannel>>;
+}
+
+/** World Rooms keep their authored entities in the declared state record. */
+declare type RoomWorldEntity<S> = S extends {
+    readonly entities: Readonly<Record<string, infer E>>;
+} ? RoomState<E> & {
+    readonly id: string;
+} : never;
+
+/** Render/connection coordination only: no token and no ownership assertion. */
+declare interface RoomWorldHandoffFrame {
+    readonly kind: 'WorldHandoff';
+    readonly phase: 'departed' | 'cancelled';
+    readonly transitionId: string;
+    readonly entityId: string;
+    readonly tick: number;
+    readonly sourceEpoch: number;
+    readonly targetRoomId: string;
+    readonly targetEpoch: number;
+    readonly holdMs: number;
+}
+
+declare interface RoomWorldHookContext<S> {
+    readonly state: RoomState<S>;
+    readonly phase: 'prepare' | 'commit' | 'rollback';
+    readonly requestId?: string | undefined;
+    readonly entity: RoomWorldEntity<S>;
+}
+
+declare interface RoomWorldHookInput<E = unknown> {
+    /** Actual target placement, distinct from the source location. Only guarded
+     * target entry uses it; source rollback must restore its exact snapshot. */
+    readonly arrival?: WorldEntityLocation;
+    readonly epoch: number;
+    readonly entity: E;
+    readonly location: WorldEntityLocation;
+    readonly requestId?: string | undefined;
+}
+
+declare interface RoomWorldHooks<S> {
+    /** Opt-in cell movement: synchronous author projection/write, no I/O. */
+    readonly movement?: RoomWorldMovement<S>;
+    /** Retained checkpoint receipts awaiting confirmed transition retirement. */
+    readonly maxPendingTransitions?: number;
+    readonly onEnter: RoomLifecycleHook<RoomWorldHookContext<S> & {
+        readonly from: WorldEntityLocation;
+        readonly to?: WorldEntityLocation;
+    }>;
+    readonly onExit: RoomLifecycleHook<RoomWorldHookContext<S> & {
+        readonly to: WorldEntityLocation;
+    }>;
+    /** Publish a projection on commit; remove that projection on rollback. Never
+     * promote it into authoritative entities. Rollback may retry after failure. */
+    readonly onGhost: RoomLifecycleHook<RoomWorldHookContext<S>>;
+    /** Synchronous, bounded JSON projection; no SQL or asynchronous effect here. */
+    readonly persistEntity: (context: {
+        readonly entity: RoomWorldEntity<S>;
+    }) => unknown;
+    /** A player who arrived by a World transition is now an active member. `onJoin` does not run for
+     * such arrivals (the entity came with `onEnter`); this is where the Room sees the arriving client,
+     * e.g. its seat attributes (`client.attributes`). */
+    readonly onMemberEnter?: RoomLifecycleHook<{
+        readonly state: RoomState<S>;
+        readonly client: RoomClient;
+        readonly entityId: string;
+    }>;
+}
+
+/** The server-owned entity an ordinary World player Session controls, as last persisted.
+ * The Room's `onJoin` receives it as `world` and builds the state entity when absent. */
+declare interface RoomWorldMember {
+    readonly entityId: string;
+    readonly worldId: string;
+    readonly zoneId: string;
+    readonly cellId: string;
+    readonly layer: number;
+    readonly revision: number;
+    /** The Room's `persistEntity` projection from the entity's last write. */
+    readonly data: unknown;
+}
+
+declare interface RoomWorldMovement<S> {
+    readonly maxEntities: number;
+    readonly maxBytesPerTick: number;
+    readonly position: (entity: RoomWorldEntity<S>) => WorldPoint;
+    readonly move: (entity: RoomWorldEntity<S>, at: WorldPoint) => void;
+}
+
+declare interface RoomWorldReceipt {
+    readonly requestId: string;
+    readonly operation: 'enter' | 'exit' | 'ghost';
+    readonly fingerprint: string;
+    readonly projection?: {
+        readonly entity: unknown;
+        readonly location: WorldEntityLocation;
+        readonly expiresAt?: number;
+    };
+}
+
+/** Returns an intention vector, never a claimed authoritative position. */
+export declare const steer: Readonly<{
+    seek: (from: RoomBotVector, to: RoomBotVector, magnitude?: number) => RoomBotVector;
+    flee: (from: RoomBotVector, threat: RoomBotVector, magnitude?: number) => RoomBotVector;
+    wander: (headingDegrees: number, maxTurnDegrees: number, rng: RoomBotRandom, magnitude?: number) => {
+        readonly headingDegrees: number;
+        readonly intention: RoomBotVector;
+    };
+}>;
+
+declare const Transform2D: Schema.Struct<{
+    readonly x: Schema.Number;
+    readonly y: Schema.Number;
+    readonly rot: Schema.Number;
+    readonly vx: Schema.optional<Schema.Number>;
+    readonly vy: Schema.optional<Schema.Number>;
+}>;
+
+declare type Transform2D = (typeof Transform2D)["Type"];
+
+/** Stable configuration order breaks ties; scorer failures do not choose an
+ * arbitrary action. Actual behavior owns interpretation of the returned data. */
+export declare const utilityAI: <C, A>(input: {
+    readonly actions: ReadonlyArray<RoomBotUtilityAction<C, A>>;
+}) => ((context: C) => A | null);
+
+declare type WorldBounds = readonly [minimum: WorldPoint, maximum: WorldPoint];
+
+declare interface WorldEntityLocation {
+    readonly worldId: string;
+    readonly zoneId: string;
+    readonly at: WorldPoint;
+    readonly layer: number;
+    readonly roomId: string;
+    readonly epoch: number;
+}
+
+declare interface WorldMovementIntent {
+    readonly entityId: string;
+    readonly sourceAt: WorldPoint;
+    readonly targetAt: WorldPoint;
+    readonly crossing: boolean;
+}
+
+declare interface WorldMovementObservation {
+    readonly epoch: number;
+    readonly tick: number;
+    readonly intents: ReadonlyArray<WorldMovementIntent>;
+}
+
+declare type WorldPoint = readonly [x: number, y: number];
+
+/** Private durable restriction, never a bearer or a grant of transition authority.
+ * The enclosing Seat supplies tenant, target Room, Subject and ownership epoch. */
+declare interface WorldTargetSeatBinding {
+    readonly transitionId: string;
+    readonly sourceRoomId: string;
+    readonly requestId: string;
+    readonly entityId: string;
+}
+
+export { }