@vgai/sdk 0.4.0-canary.20260715.0

package/src/play/lifecycle-operations.ts

@@ -0,0 +1,271 @@
+/**
+ * `play.start` / `play.pause` / `play.resume` / `play.stop` / `play.frameStep`
+ * (B4, §8 B4 "start, pause, resume, stop, and frame-step").
+ *
+ * All five are genuinely wired end to end against the real transport:
+ * `{type:'play'|'pause'|'resume'|'stop'|'step'}` are existing,
+ * already-handled cases in the browser's `handleCommand` switch
+ * (`packages/editor/src/command-listener.ts`), relayed through the same
+ * `POST /__editor/command` mechanism B3's `editor.*` ops use.
+ *
+ * READINESS (§8 B4 AC "Start returns only after the runtime reports
+ * readiness or a named timeout"): `case 'play'` in `handleCommand`
+ * `await`s `enterPlayMode()` — which itself awaits the ENTIRE async game
+ * boot (asset loads, procedural worldgen, `createGameRuntime`/
+ * `mountManifestWorlds`) — before acking back over
+ * `POST /__editor/command-result`. That ack is what unblocks the relay's
+ * HTTP response. So `play.start`'s `impl` genuinely does not resolve before
+ * the runtime is ready: it `await`s the transport call, and the transport
+ * call (real or mocked) does not resolve until the browser acks. The op
+ * additionally wraps that await in `withPlayTimeout(..., readyTimeoutMs)` so a
+ * transport that NEVER resolves (dead relay, hung browser) still fails with
+ * a NAMED `PLAY_START_TIMEOUT` error rather than hanging forever — this is
+ * the "or a named timeout" half of the AC. `readyTimeoutMs` defaults to
+ * `PLAY_START_TIMEOUT_MS` (125s — 5s above the real relay's own 120s
+ * `PLAY_COMMAND_TIMEOUT_MS`, so the server's own timeout/error message wins
+ * first in the real-transport case; this op's timeout only fires against a
+ * transport that doesn't even respond).
+ *
+ * STOP CLEANUP (§8 B4 AC "Stop cleans up the launched runtime"): `case
+ * 'stop'` calls `exitPlayMode()` synchronously, which (per `play-mode.ts`)
+ * removes the game canvas, disposes the live `GameSession` (Rapier world,
+ * RAF loop, WebGL context), ends the log-persistence session, and restores
+ * editor input — that full teardown is what a successful `play.stop`
+ * result means; nothing further needs to run client-side.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  getPlayTransport,
+  PLAY_COMMAND_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  PLAY_START_TIMEOUT_MS,
+  PlayTimeoutError,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+const COMMAND_FAILED_ERROR = {
+  code: 'COMMAND_FAILED',
+  summary:
+    'The connected editor rejected or failed to execute the relayed play command (e.g. scene ' +
+    "validation failed, or the game's setup() threw).",
+  data: z.object({ message: z.string() }),
+} as const;
+
+const PLAY_START_TIMEOUT_ERROR = {
+  code: 'PLAY_START_TIMEOUT',
+  summary:
+    'The runtime did not report readiness within the bound (named timeout, never an unbounded hang).',
+  data: z.object({ timeoutMs: z.number() }),
+} as const;
+
+const OkResult = z.object({ ok: z.literal(true) });
+
+async function relayAndCheck(
+  op: string,
+  send: () => Promise<{ ok: boolean; error?: string }>,
+  timeoutMs: number,
+): Promise<void> {
+  const result = await withPlayTimeout(send(), timeoutMs, op).catch((err: unknown) => ({
+    ok: false,
+    error: err instanceof Error ? err.message : String(err),
+  }));
+  if (!result.ok) {
+    throw new OperationError('COMMAND_FAILED', result.error ?? `${op} command failed`, {
+      message: result.error ?? `${op} command failed`,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// play.start
+// ---------------------------------------------------------------------------
+
+const PlayStartInput = z.object({
+  readyTimeoutMs: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      'Override the max wait for runtime readiness before failing with the named ' +
+        'PLAY_START_TIMEOUT error. Defaults to PLAY_START_TIMEOUT_MS (125s) — see module jsdoc.',
+    ),
+  seed: z
+    .number()
+    .int()
+    .optional()
+    .describe(
+      'D15/T-D15.6 — the explicit-config leg of the boot-time deterministic-seed precedence ' +
+        '(beats manifest.determinism.defaultSeed/?vgai-seed= on the editor page URL); baked in ' +
+        'before any world mounts (`enterPlayMode`/`mountManifestWorlds`, not a post-hoc reseed). ' +
+        'Mirrors `vgai play --seed <n>` — see docs/D15-DETERMINISM-DESIGN.md §2.d.',
+    ),
+});
+
+export const playStart = defineOperation({
+  name: 'play.start',
+  summary: 'Start (or restart) play mode in a connected editor session and wait for readiness.',
+  description:
+    'Relays {type:"play"} through POST /__editor/command — an existing, already-handled case ' +
+    "whose ack is gated on the game's ENTIRE async setup() (see module jsdoc), never acked early. " +
+    'A transport that never responds fails with the named PLAY_START_TIMEOUT error instead of hanging.',
+  input: PlayStartInput,
+  result: OkResult,
+  errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, PLAY_START_TIMEOUT_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: 'Launches (or restarts) the play runtime inside the connected editor session.',
+  },
+  async impl(input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const timeoutMs = input.readyTimeoutMs ?? PLAY_START_TIMEOUT_MS;
+    let result: { ok: boolean; error?: string };
+    try {
+      result = await withPlayTimeout(
+        transport.start(session, timeoutMs, input.seed),
+        timeoutMs,
+        'play.start',
+      );
+    } catch (err) {
+      if (err instanceof PlayTimeoutError) {
+        throw new OperationError(
+          'PLAY_START_TIMEOUT',
+          `The runtime did not report readiness within ${timeoutMs}ms.`,
+          { timeoutMs },
+        );
+      }
+      throw err;
+    }
+    if (!result.ok) {
+      throw new OperationError('COMMAND_FAILED', result.error ?? 'play command failed', {
+        message: result.error ?? 'play command failed',
+      });
+    }
+    return { ok: true as const };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// play.pause / play.resume / play.stop / play.frameStep
+// ---------------------------------------------------------------------------
+
+const NoInput = z.object({});
+
+export const playPause = defineOperation({
+  name: 'play.pause',
+  summary: 'Pause the running play session in a connected editor.',
+  description: 'Relays {type:"pause"} through POST /__editor/command (already-handled case).',
+  input: NoInput,
+  result: OkResult,
+  errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: 'Pauses the live play runtime only.' },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    await relayAndCheck(
+      'play.pause',
+      () => transport.pause(session, PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+    );
+    return { ok: true as const };
+  },
+});
+
+export const playResume = defineOperation({
+  name: 'play.resume',
+  summary: 'Resume a paused play session in a connected editor.',
+  description: 'Relays {type:"resume"} through POST /__editor/command (already-handled case).',
+  input: NoInput,
+  result: OkResult,
+  errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: 'Resumes the live play runtime only.' },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    await relayAndCheck(
+      'play.resume',
+      () => transport.resume(session, PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+    );
+    return { ok: true as const };
+  },
+});
+
+export const playStop = defineOperation({
+  name: 'play.stop',
+  summary: 'Stop play mode in a connected editor and clean up the launched runtime.',
+  description:
+    'Relays {type:"stop"} through POST /__editor/command, which calls exitPlayMode() — full ' +
+    'synchronous teardown of the launched runtime (canvas, GameSession, log-persistence session, ' +
+    'editor input restoration). See module jsdoc.',
+  input: NoInput,
+  result: OkResult,
+  errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: 'Stops and fully tears down the live play runtime.',
+  },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    await relayAndCheck(
+      'play.stop',
+      () => transport.stop(session, PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+    );
+    return { ok: true as const };
+  },
+});
+
+export const playFrameStep = defineOperation({
+  name: 'play.frameStep',
+  summary: 'Advance a paused play session by exactly one frame.',
+  description: 'Relays {type:"step"} through POST /__editor/command (already-handled case).',
+  input: NoInput,
+  result: OkResult,
+  errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: 'Advances the live play runtime by one frame only.' },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    await relayAndCheck(
+      'play.frameStep',
+      () => transport.frameStep(session, PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+    );
+    return { ok: true as const };
+  },
+});
+
+export function registerLifecycleOperations(registry: OperationRegistry): void {
+  registry.register(playStart);
+  registry.register(playPause);
+  registry.register(playResume);
+  registry.register(playStop);
+  registry.register(playFrameStep);
+}

package/src/play/log-operations.ts

@@ -0,0 +1,279 @@
+/**
+ * `play.log.discover` / `play.log.read` / `play.log.follow`
+ * (B4, §8 B4 "structured log discovery/read/follow").
+ *
+ * discover/read are FILE-NATIVE (`host: 'node'`, `requires: {project: true}`)
+ * — they read `<projectRoot>/logs/play-*.jsonl` directly off disk, the same
+ * files `play-mode.ts`'s `startLogSession`/`flushLogEntries` write via
+ * `POST /__editor/log-session` + `/__editor/log-entries`
+ * (`packages/editor/server/editor-server.ts`). No editor session or
+ * transport is needed to list/read them — they persist after play stops,
+ * and reading them should work whether or not an editor is even running
+ * (reusing "the logs/play-*.jsonl reader" per this unit's own brief, taken
+ * literally: read the files).
+ *
+ * IDENTITY FIELDS (§8 B4 AC "Logs identify session, project, world, and
+ * simulation speed"): the real persisted `LogEntry` shape
+ * (`packages/editor/src/editor-api.ts`) is `{t, level, source?, sub?, msg,
+ * meta?}` — NO session/project/world/simSpeed fields exist in the file
+ * format today (a genuine gap against this AC in the CURRENT persistence
+ * layer, which predates it; closing it for real would mean threading these
+ * fields through `play-mode.ts`'s log sink and `editor-server.ts`'s
+ * append handler — both outside this unit's file ownership,
+ * packages/editor/src|server). `play.log.read` satisfies the AC honestly,
+ * without fabricating anything:
+ *   - `session`: the log FILENAME itself (e.g. "play-2026-...jsonl") — the
+ *     closest real identity a persisted play run has today.
+ *   - `project`: `ctx.projectRoot`, always real (these ops require it).
+ *   - `world`/`simSpeed`: read from each entry's own `meta.world` /
+ *     `meta.simSpeed`, when the entry happens to carry them (`meta` is
+ *     already a free-form bag in the real format) — `null` otherwise. This
+ *     is the honest state of affairs: against TODAY's real files these are
+ *     always `null` (the current sink never stamps them); a test fixture
+ *     that DOES embed them in `meta` proves the read-through path for real.
+ *
+ * `play.log.follow` describes the REAL, existing poll-based subscription
+ * for the CURRENTLY ACTIVE play session's log (there is no push/SSE
+ * mechanism for log lines — `/__editor/events`'s SSE stream never carries
+ * them) — same "metadata only" contract B3's `editor.console.subscribe`
+ * established, `requires: {play: true}` because `activeLogFile` is only
+ * non-null while a play session is running.
+ */
+
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import {
+  FILE_NOT_FOUND_ERROR,
+  NO_PROJECT_ROOT_ERROR,
+  PATH_OUTSIDE_PROJECT_ERROR,
+  readFileWithHash,
+  requireProjectRoot,
+  resolveProjectPath,
+} from '../project/shared.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  getPlayTransport,
+  PLAY_READ_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+const PLAY_LOG_FOLLOW_UNAVAILABLE_ERROR = {
+  code: 'PLAY_LOG_FOLLOW_UNAVAILABLE',
+  summary: 'A session is connected but did not answer the log-entries read in time.',
+  data: z.object({}),
+} as const;
+
+// ---------------------------------------------------------------------------
+// play.log.discover
+// ---------------------------------------------------------------------------
+
+const PlayLogDiscoverInput = z
+  .object({})
+  .describe("No input — lists every persisted play-mode log file under the project's logs/ dir.");
+
+const PlayLogDiscoverResult = z.object({
+  logFiles: z
+    .array(z.string())
+    .describe('Filenames (e.g. "play-2026-07-11T10-00-00.jsonl"), oldest first (name-sorted).'),
+});
+
+export const playLogDiscover = defineOperation({
+  name: 'play.log.discover',
+  summary: "List every persisted play-mode log file under the project's logs/ directory.",
+  description:
+    'Reads <projectRoot>/logs/ directly off disk and filters play-*.jsonl (the exact naming ' +
+    "convention editor-server.ts's log-session handler writes). Works with no editor/play " +
+    'session running — these files persist after play stops.',
+  input: PlayLogDiscoverInput,
+  result: PlayLogDiscoverResult,
+  errors: [NO_PROJECT_ROOT_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: "Lists the project's logs/ directory; no writes." },
+  async impl(_input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const logsDir = join(projectRoot, 'logs');
+    let names: string[];
+    try {
+      names = readdirSync(logsDir);
+    } catch {
+      names = [];
+    }
+    const logFiles = names.filter((f) => f.startsWith('play-') && f.endsWith('.jsonl')).sort();
+    return { logFiles };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// play.log.read
+// ---------------------------------------------------------------------------
+
+const PlayLogEntrySchema = z.object({
+  t: z.number().describe('Entry timestamp (ms epoch), as persisted.'),
+  level: z.string(),
+  source: z.string().nullable(),
+  sub: z.string().nullable(),
+  msg: z.string(),
+  meta: z.record(z.string(), z.unknown()).nullable(),
+  session: z.string().describe('The log filename identifying this play run (see module jsdoc).'),
+  project: z.string().describe('Absolute project root this log belongs to.'),
+  world: z
+    .string()
+    .nullable()
+    .describe(
+      'Active world id for this entry, read from meta.world when the writer stamped it — null ' +
+        "otherwise (today's real sink never stamps this; see module jsdoc).",
+    ),
+  simSpeed: z
+    .number()
+    .nullable()
+    .describe(
+      'Simulation time-scale for this entry, read from meta.simSpeed when the writer stamped it ' +
+        "— null otherwise (today's real sink never stamps this; see module jsdoc).",
+    ),
+});
+
+const PlayLogReadInput = z.object({
+  file: z.string().describe('A filename returned by play.log.discover, project-relative to logs/.'),
+  offset: z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe('Skip this many entries from the start. Defaults to 0.'),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Max entries to return. Defaults to all remaining.'),
+});
+
+const PlayLogReadResult = z.object({
+  entries: z.array(PlayLogEntrySchema),
+  totalEntries: z.number().describe('Total entries in the file, regardless of offset/limit.'),
+});
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Parse one raw JSONL line into a `PlayLogEntrySchema`-shaped entry, stamping the identity fields (see module jsdoc). */
+function parseLogLine(
+  line: string,
+  session: string,
+  project: string,
+): z.infer<typeof PlayLogEntrySchema> {
+  const parsed: unknown = JSON.parse(line);
+  const rec = isRecord(parsed) ? parsed : {};
+  const meta = isRecord(rec['meta']) ? (rec['meta'] as Record<string, unknown>) : null;
+  const worldRaw = meta?.['world'];
+  const simSpeedRaw = meta?.['simSpeed'];
+  return {
+    t: typeof rec['t'] === 'number' ? rec['t'] : 0,
+    level: typeof rec['level'] === 'string' ? rec['level'] : 'log',
+    source: typeof rec['source'] === 'string' ? rec['source'] : null,
+    sub: typeof rec['sub'] === 'string' ? rec['sub'] : null,
+    msg: typeof rec['msg'] === 'string' ? rec['msg'] : '',
+    meta,
+    session,
+    project,
+    world: typeof worldRaw === 'string' ? worldRaw : null,
+    simSpeed: typeof simSpeedRaw === 'number' ? simSpeedRaw : null,
+  };
+}
+
+export const playLogRead = defineOperation({
+  name: 'play.log.read',
+  summary: 'Read entries from a persisted play-mode log file.',
+  description:
+    'Reads <projectRoot>/logs/<file> directly off disk, parsing each JSONL line. Each returned ' +
+    'entry is enriched with session (the log filename)/project (ctx.projectRoot) — both real — ' +
+    "plus world/simSpeed read from the entry's own meta bag when present, null otherwise (see " +
+    'module jsdoc for why the raw persisted format has no dedicated fields for these yet).',
+  input: PlayLogReadInput,
+  result: PlayLogReadResult,
+  errors: [NO_PROJECT_ROOT_ERROR, PATH_OUTSIDE_PROJECT_ERROR, FILE_NOT_FOUND_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads one file under logs/; no writes.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const absPath = resolveProjectPath(projectRoot, join('logs', input.file));
+    const { raw } = readFileWithHash(absPath);
+    const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+    const offset = input.offset ?? 0;
+    const limit = input.limit ?? lines.length;
+    const slice = lines.slice(offset, offset + limit);
+    const entries = slice.map((line) => parseLogLine(line, input.file, projectRoot));
+    return { entries, totalEntries: lines.length };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// play.log.follow
+// ---------------------------------------------------------------------------
+
+const PlayLogFollowInput = z
+  .object({})
+  .describe("No input — describes how to poll-follow the CURRENTLY active play session's log.");
+
+const PlayLogFollowResult = z.object({
+  logEntriesUrl: z
+    .string()
+    .describe('GET (read all buffered entries) / POST (append) — poll this to tail.'),
+  logSessionUrl: z
+    .string()
+    .describe('POST {action:"start"|"end"} — already bracketing the active play session.'),
+  bufferedLogCount: z
+    .number()
+    .describe('Live count of entries buffered for the active play session.'),
+});
+
+export const playLogFollow = defineOperation({
+  name: 'play.log.follow',
+  summary: "Describe how to poll-follow the currently active play session's log.",
+  description:
+    'Metadata only (no push/SSE for log lines exists today): reports the real ' +
+    'GET/POST /__editor/log-entries + /__editor/log-session endpoints for the CURRENTLY active ' +
+    'play session, plus a live buffered-entry count — same contract as editor.console.subscribe.',
+  input: PlayLogFollowInput,
+  result: PlayLogFollowResult,
+  errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, PLAY_LOG_FOLLOW_UNAVAILABLE_ERROR],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads live log-entry metadata only.' },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const metadata = await withPlayTimeout(
+      transport.getLogFollowMetadata(session, PLAY_READ_TIMEOUT_MS),
+      PLAY_READ_TIMEOUT_MS,
+      'play.log.follow',
+    ).catch(() => undefined);
+    if (!metadata) {
+      throw new OperationError(
+        'PLAY_LOG_FOLLOW_UNAVAILABLE',
+        'The connected editor session did not answer the log-entries read in time.',
+        {},
+      );
+    }
+    return metadata;
+  },
+});
+
+export function registerLogOperations(registry: OperationRegistry): void {
+  registry.register(playLogDiscover);
+  registry.register(playLogRead);
+  registry.register(playLogFollow);
+}

package/src/play/run-ticks-operations.ts

@@ -0,0 +1,141 @@
+/**
+ * `play.runTicks` (D15/T-D15.4, `docs/D15-DETERMINISM-DESIGN.md` §2.b) — the
+ * editor door (b) of the same run-ticks primitive `window.__vgai.runTicks`
+ * (door a, `runtime/debug-bridge.ts`) exposes: synchronously fast-forward a
+ * running play session `n` fixed gameplay ticks, decoupled from wall clock.
+ *
+ * Wire: relay case `run-ticks` (`command-listener.ts`) reaching the live
+ * session's `GameInternal.runTicks` through `play-mode.ts`'s
+ * `getPlayRuntimeAccess()` — itself backed by the SAME
+ * `DebugRegistry.getRunTicksTarget()` the bridge calls, so behavior is
+ * byte-identical across both doors (D17). Against a stale editor page the
+ * transport translates the structured `UNKNOWN_COMMAND_TYPE` marker into
+ * `undefined` and this op throws the declared `RUN_TICKS_UNSUPPORTED`.
+ *
+ * DETERMINISM-agnostic by design (per the D15 doc): `runTicks` is a DRIVER —
+ * it makes tick count exact-by-construction on any hardware, but says
+ * nothing about whether draws/physics are actually reproducible (that is
+ * `determinism.seededRandom`'s contract, a different unit). This op never
+ * checks or requires that manifest block.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  getPlayTransport,
+  PLAY_COMMAND_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  relayErrorMarker,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+const RUN_TICKS_UNSUPPORTED_ERROR = {
+  code: 'RUN_TICKS_UNSUPPORTED',
+  summary:
+    'The connected editor page predates the run-ticks relay command (version skew, matched on ' +
+    'the structured UNKNOWN_COMMAND_TYPE marker) — reload the editor tab. Never silently ' +
+    'reported as success.',
+  data: z.object({}),
+} as const;
+
+const RUN_TICKS_UNAVAILABLE_ERROR = {
+  code: 'RUN_TICKS_UNAVAILABLE',
+  summary:
+    'The live play session has no first-party Game mounted yet (no run-ticks target wired) — ' +
+    'wait for play.start to finish, or the session is running a foreign/ingested mount that ' +
+    'exposes no Game root.',
+  data: z.object({}),
+} as const;
+
+const RUN_TICKS_PAUSED_ERROR = {
+  code: 'RUN_TICKS_PAUSED',
+  summary:
+    'The live session is paused (Game.play.paused) — runTicks refuses outright rather than ' +
+    'silently ignoring pause; use play.step to advance a paused/frozen world instead.',
+  data: z.object({}),
+} as const;
+
+const COMMAND_FAILED_ERROR = {
+  code: 'COMMAND_FAILED',
+  summary: 'The connected editor rejected or failed to execute the relayed run-ticks command.',
+  data: z.object({ message: z.string() }),
+} as const;
+
+const PlayRunTicksInput = z.object({
+  n: z
+    .number()
+    .int()
+    .min(0)
+    .describe('Number of fixed gameplay ticks to run synchronously, decoupled from wall clock.'),
+  render: z
+    .enum(['last', 'all', 'none'])
+    .optional()
+    .describe(
+      "'last' (default): render only the final tick. 'all': render every tick. 'none': never " +
+        'render, not even the last tick. tick/simT and every non-render phase advance on EVERY ' +
+        'tick regardless.',
+    ),
+});
+
+const PlayRunTicksResult = z.object({ ok: z.literal(true) });
+
+export const playRunTicks = defineOperation({
+  name: 'play.runTicks',
+  summary: 'Synchronously fast-forward a running play session by n fixed gameplay ticks.',
+  description:
+    'Drives GameInternal.runTicks n times, decoupled from wall clock and the loop accumulator — ' +
+    'tick count is exact by construction on any hardware. Refuses (RUN_TICKS_PAUSED) while the ' +
+    'session is paused; never bypasses the input focus gate. Throws RUN_TICKS_UNSUPPORTED ' +
+    'against a stale editor page. DETERMINISM-agnostic: does not require determinism.seededRandom.',
+  input: PlayRunTicksInput,
+  result: PlayRunTicksResult,
+  errors: [
+    PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+    RUN_TICKS_UNSUPPORTED_ERROR,
+    RUN_TICKS_UNAVAILABLE_ERROR,
+    RUN_TICKS_PAUSED_ERROR,
+    COMMAND_FAILED_ERROR,
+  ],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: 'Advances the live play session simulation by n fixed ticks (no user-visible input).',
+  },
+  async impl(input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const result = await withPlayTimeout(
+      transport.runTicks(session, input.n, input.render, PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+      'play.runTicks',
+    ).catch(() => undefined);
+    if (!result) {
+      throw new OperationError(
+        'RUN_TICKS_UNSUPPORTED',
+        'The connected editor page predates the run-ticks relay command — reload it.',
+        {},
+      );
+    }
+    if (!result.ok) {
+      const marker = relayErrorMarker(result);
+      const message = result.error ?? 'run-ticks command failed';
+      if (marker?.code === 'RUN_TICKS_UNAVAILABLE') {
+        throw new OperationError('RUN_TICKS_UNAVAILABLE', message, {});
+      }
+      if (marker?.code === 'RUN_TICKS_PAUSED') {
+        throw new OperationError('RUN_TICKS_PAUSED', message, {});
+      }
+      throw new OperationError('COMMAND_FAILED', message, { message });
+    }
+    return { ok: true as const };
+  },
+});
+
+export function registerRunTicksOperations(registry: OperationRegistry): void {
+  registry.register(playRunTicks);
+}