@vgai/sdk 0.5.21 → 0.5.23

package/src/play/debug-command-operations.ts

@@ -1,5 +1,5 @@
 /**
- * `play.debugCommand.list` / `play.debugCommand.invoke` (Wave 5 — the
+ * `play.debugCommand.list` / `play.debugCommand.invoke` (the
  * editor/CLI/MCP door onto `ctx.debug.registerCommand` registrations).
  *
  * Debug commands are FIXTURES, never proofs (D16): they set up state so a

package/src/play/input-operations.ts

@@ -1,6 +1,6 @@
 /**
  * `play.input.inject` (B4, §8 B4 "input injection through normal input
- * paths"; wired for real in Wave 5).
+ * paths"; wired for real).
  *
  * MUST exercise the NORMAL input action path, never a direct game-state
  * mutation (§8 B4 AC). Two tiers, both engine-native:

package/src/play/log-format.ts

@@ -2,7 +2,7 @@
  * THE on-disk shape of `<project>/logs/play-*.jsonl` — one definition, shared
  * by the writer (`editor-server.ts`'s `/__editor/log-session` +
  * `/__editor/log-entries` handlers) and every reader (`play.log.*` here,
- * `vgai status`'s play-error banner, the project Logs utility).
+ * `vgai status`'s play-error banner, the project Analytics utility).
  *
  * A play log is JSONL with TWO record kinds:
  *

package/src/play/state-operations.ts

@@ -1,7 +1,7 @@
 /**
  * `play.gameplayState.inspect` / `play.gameplayState.list` (B4, §8 B4
  * "gameplay state/test-hook inspection when provided by the game";
- * implemented for real in Wave 5).
+ * implemented for real).
  *
  * The registration mechanism this file's old HONEST-GAP jsdoc anticipated
  * now exists: games register named state providers via

package/src/play/status-operations.ts

@@ -4,8 +4,7 @@
  *
  * status.playState is genuinely wired: `GET /__editor/state`'s `playState`
  * field, populated by `collectState()` (`packages/editor/src/command-listener.ts`)
- * after every relayed command. `seed`/`deterministic`/`timeScale` are ALL
- * real (D15/T-D15.6 landed seed/deterministic; timeScale since Wave 5) —
+ * after every relayed command. `seed`/`deterministic`/`timeScale` are ALL real:
  * `collectState` reports the live session's `ctx.random.seed`, whether its
  * manifest declares `determinism.seededRandom`, and the live `GameLoop
  * .timeScale`; each is `null`/`false` only when no session/Game is running

package/src/play/transport.ts

@@ -31,8 +31,8 @@
  * module jsdoc documents for its session-registry reader — a few lines
  * duplicated beats a much larger, unrelated interface coupling.
  *
- * REAL TRANSPORT SURFACE — what `HttpPlayTransport` actually talks to. Wave 5
- * closed the version-skew lie: `command-listener.ts`'s `handleCommand` now has
+ * REAL TRANSPORT SURFACE — what `HttpPlayTransport` actually talks to. There
+ * is no version-skew lie: `command-listener.ts`'s `handleCommand` has
  * a `default:` case answering `{ok:false, data:{code:'UNKNOWN_COMMAND_TYPE'}}`
  * for any command type the connected editor page predates, and the relay's
  * result leg carries `data` end to end (`reportCommandResult` →
@@ -72,10 +72,12 @@
  *    `editor.console.subscribe`.
  */
 
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
 import { z } from 'zod';
+import {
+  readLiveRegisteredSessions,
+  resolveRegisteredSession,
+  servedProjectAnswer,
+} from '../editor/session-registry-format';
 import { ToolError } from '../errors.js';
 import type { ToolErrorDefinition } from '../registry.js';
 import type { ToolContext } from '../types.js';
@@ -178,7 +180,7 @@ export interface PlaySessionInfo {
 export interface PlayCommandResult {
   ok: boolean;
   error?: string;
-  /** The relay's read-payload leg (Wave 5): the browser handler's structured
+  /** The relay's read-payload leg : the browser handler's structured
    *  result on success, or a structured `{ code, ... }` failure marker
    *  (registered-name lists, zod issues) on `ok: false`. */
   data?: unknown;
@@ -252,7 +254,7 @@ export interface PlayLogFollowMetadata {
 export type InputInjectionKind = 'axis' | 'vector2' | 'pointerDelta' | 'pointerPosition';
 
 /** Action-level injection (`kind: 'action'`, spec §3.2's `setVirtualAction` —
- *  PRIMARY since Wave 5: the honest, focus-gated path whose relay result
+ *  PRIMARY: the honest, focus-gated path whose relay result
  *  carries `{delivered, reason?}`) plus the four legacy named-test-source
  *  shapes (`InputManager.injectAxis` family, read back only through declared
  *  `test_*` bindings). `atTick` (D15/T-D15.5, action-kind only) defers the
@@ -306,7 +308,7 @@ export interface PlayTransport {
     session: PlaySessionInfo,
     timeoutMs: number,
   ): Promise<PlayLogFollowMetadata | undefined>;
-  /** Real since Wave 5 (relay case `inject-input`); `undefined` only against
+  /** Real (relay case `inject-input`); `undefined` only against
    *  a stale editor page (UNKNOWN_COMMAND_TYPE marker). On success `data`
    *  carries `{delivered, reason?}` for action-level injections. */
   injectInput(
@@ -330,14 +332,14 @@ export interface PlayTransport {
     seed: number,
     timeoutMs: number,
   ): Promise<PlayCommandResult | undefined>;
-  /** Real since Wave 5 (relay case `set-time-scale`, reaching
+  /** Real (relay case `set-time-scale`, reaching
    *  `GameLoop.timeScale`); `undefined` only against a stale editor page. */
   setTimeScale(
     session: PlaySessionInfo,
     timeScale: number,
     timeoutMs: number,
   ): Promise<PlayCommandResult | undefined>;
-  /** Real since Wave 5 (relay case `inspect-gameplay-state`): success `data`
+  /** Real (relay case `inspect-gameplay-state`): success `data`
    *  is `{ state: Record<string, unknown> | null }` (null when the running
    *  game exposes no debug adapter); `undefined` only against a stale editor
    *  page. Structured failures (`STATE_PROVIDER_NOT_FOUND`) ride
@@ -347,20 +349,20 @@ export interface PlayTransport {
     keys: string[] | undefined,
     timeoutMs: number,
   ): Promise<PlayCommandResult | undefined>;
-  /** Real since Wave 5 (relay case `list-gameplay-state`): success `data` is
+  /** Real (relay case `list-gameplay-state`): success `data` is
    *  `{ providers: {name, tier}[] }`. `undefined` = stale editor page. */
   listGameplayState(
     session: PlaySessionInfo,
     timeoutMs: number,
   ): Promise<PlayCommandResult | undefined>;
-  /** Real since Wave 5 (relay case `list-debug-commands`): success `data` is
+  /** Real (relay case `list-debug-commands`): success `data` is
    *  `{ commands: DebugCommandInfo[] }` (name/description/argsJsonSchema/
    *  locus). `undefined` = stale editor page. */
   listDebugCommands(
     session: PlaySessionInfo,
     timeoutMs: number,
   ): Promise<PlayCommandResult | undefined>;
-  /** Real since Wave 5 (relay case `invoke-debug-command`): success `data` is
+  /** Real (relay case `invoke-debug-command`): success `data` is
    *  `{ result: unknown }`; structured failures (`DEBUG_COMMAND_NOT_REGISTERED`/
    *  `DEBUG_COMMAND_ARGS_INVALID`/`DEBUG_COMMAND_FAILED`) ride `data.code`.
    *  `undefined` = stale editor page. */
@@ -390,69 +392,6 @@ export interface PlayTransport {
 // Real transport
 // ---------------------------------------------------------------------------
 
-interface RegistrySessionEntry {
-  project: string | null;
-  port: number;
-  pid: number;
-  startedAt: string;
-  kind?: string;
-}
-
-function isRegistrySessionEntry(v: unknown): v is RegistrySessionEntry {
-  if (typeof v !== 'object' || v === null) return false;
-  const s = v as Record<string, unknown>;
-  return (
-    (typeof s['project'] === 'string' || s['project'] === null) &&
-    typeof s['port'] === 'number' &&
-    typeof s['pid'] === 'number' &&
-    typeof s['startedAt'] === 'string' &&
-    (s['kind'] === undefined || typeof s['kind'] === 'string')
-  );
-}
-
-function pidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** Deliberate light duplicate of `../editor/transport.ts`'s identical reader — see module jsdoc. */
-function readRegisteredSessions(): RegistrySessionEntry[] {
-  const registryFile = join(homedir(), '.vgai', 'editor-sessions.json');
-  if (!existsSync(registryFile)) return [];
-  try {
-    const raw: unknown = JSON.parse(readFileSync(registryFile, 'utf8'));
-    return Array.isArray(raw)
-      ? raw.filter(isRegistrySessionEntry).filter((s) => pidAlive(s.pid))
-      : [];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * WHICH PROJECT a `/__editor/project` body says its server is serving — the
- * play lane's copy of `editor/transport.ts`'s `servedProjectPath` (deliberate
- * light duplicate of the read half, same as `readRegisteredSessions` above).
- *
- * `serving` is that server's own statement of "I AM serving this project, I
- * just cannot describe it" (its manifest is unparseable or fails strict
- * validation) — added to the route precisely because a bare `{ project: null }`
- * is indistinguishable from "no project open". Reading only `project.path`
- * collapses the two, and the cost is that every project-matched command loses
- * a live session the moment a save breaks its manifest.
- */
-function servedProjectPath(body: unknown): string | null {
-  const b = body as {
-    project?: { path?: string } | null;
-    serving?: { path?: string } | null;
-  };
-  return b.project?.path ?? b.serving?.path ?? null;
-}
-
 async function fetchJson(url: string, timeoutMs: number): Promise<unknown | undefined> {
   try {
     const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
@@ -566,13 +505,13 @@ export class HttpPlayTransport implements PlayTransport {
     const base = editorUrl.replace(/\/+$/, '');
     const body = await fetchJson(`${base}/__editor/project`, timeoutMs);
     if (body === undefined) return undefined;
-    const project = servedProjectPath(body);
+    const project = servedProjectAnswer(body).path;
     const port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80;
     return { port, project, pid: null, url: base };
   }
 
   async listSessions(timeoutMs: number): Promise<PlaySessionInfo[]> {
-    const registered = readRegisteredSessions();
+    const registered = readLiveRegisteredSessions();
     const perProbeTimeout = Math.min(PLAY_PROBE_TIMEOUT_MS, Math.max(200, timeoutMs));
     const probes = await Promise.all(
       registered.map(async (s) => {
@@ -581,7 +520,7 @@ export class HttpPlayTransport implements PlayTransport {
           perProbeTimeout,
         );
         if (body === undefined) return undefined;
-        const project = servedProjectPath(body);
+        const project = servedProjectAnswer(body).path;
         const info: PlaySessionInfo = {
           port: s.port,
           project,
@@ -631,7 +570,7 @@ export class HttpPlayTransport implements PlayTransport {
         }
       | undefined;
     if (!body) return undefined;
-    // timeScale is real since Wave 5 (`collectState` reports the live loop's
+    // timeScale is real (`collectState` reports the live loop's
     // value; null while not playing or from an older editor page). seed/
     // deterministic are real since D15/T-D15.6 (`collectState` reports the
     // live session's `ctx.random.seed` + whether the manifest declares
@@ -785,24 +724,6 @@ export const PLAY_RUNTIME_NOT_AVAILABLE_ERROR: ToolErrorDefinition = {
   data: z.object({ editorUrl: z.string().optional() }),
 };
 
-function canonicalize(p: string): string {
-  const absolute = resolve(p);
-  try {
-    return realpathSync(absolute);
-  } catch {
-    return absolute;
-  }
-}
-
-function portOf(url: string): number | undefined {
-  try {
-    const port = new URL(url).port;
-    return port ? Number(port) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * Deterministic session selection for `play.*` ops — see module jsdoc for
  * why this duplicates (rather than imports) `../editor/transport.ts`'s
@@ -814,49 +735,14 @@ export async function resolvePlaySession(
   transport: Pick<PlayTransport, 'listSessions' | 'probeSessionUrl'>,
 ): Promise<PlaySessionInfo> {
   const editorUrl = ctx.editorUrl;
-  const notRunning = (): never => {
-    throw new ToolError('EDITOR_NOT_RUNNING', 'No editor connected to host a play runtime.', {
-      ...(editorUrl !== undefined ? { editorUrl } : {}),
-    });
-  };
-
-  if (editorUrl !== undefined && transport.probeSessionUrl) {
-    try {
-      const session = await withPlayTimeout(
-        transport.probeSessionUrl(editorUrl, PLAY_PROBE_TIMEOUT_MS),
-        PLAY_PROBE_TIMEOUT_MS,
-        'explicit editor URL probe',
-      );
-      if (session) return session;
-    } catch {}
-    return notRunning();
-  }
-
-  let sessions: PlaySessionInfo[];
-  try {
-    sessions = await withPlayTimeout(
-      transport.listSessions(PLAY_SESSION_DISCOVERY_TIMEOUT_MS),
-      PLAY_SESSION_DISCOVERY_TIMEOUT_MS,
-      'play session discovery',
-    );
-  } catch {
-    return notRunning();
-  }
-  if (sessions.length === 0) return notRunning();
-
-  if (editorUrl !== undefined) {
-    const port = portOf(editorUrl);
-    const match = sessions.find((s) => s.port === port);
-    if (!match) return notRunning();
-    return { ...match, url: editorUrl.replace(/\/+$/, '') };
-  }
-
-  if (ctx.projectRoot !== undefined) {
-    const canon = canonicalize(ctx.projectRoot);
-    const match = sessions.find((s) => s.project !== null && canonicalize(s.project) === canon);
-    if (match) return match;
-    return notRunning();
-  }
-
-  return [...sessions].sort((a, b) => a.port - b.port)[0]!;
+  return resolveRegisteredSession<PlaySessionInfo>(ctx, transport, {
+    probeTimeoutMs: PLAY_PROBE_TIMEOUT_MS,
+    discoveryTimeoutMs: PLAY_SESSION_DISCOVERY_TIMEOUT_MS,
+    withTimeout: withPlayTimeout,
+    notRunning: (): never => {
+      throw new ToolError('EDITOR_NOT_RUNNING', 'No editor connected to host a play runtime.', {
+        ...(editorUrl !== undefined ? { editorUrl } : {}),
+      });
+    },
+  });
 }

package/src/project/build-discipline.ts

@@ -4,15 +4,15 @@
  * cheap project reads behind them.
  *
  * WHY THIS LIVES IN THE SDK. It started in the CLI, wired to `vgai status`
- * alone — and a measured 17-minute blind build ran the editor, `playtest` and
+ * alone — and a measured 17-minute blind build ran the editor and
  * `eval` while invoking `vgai status` ZERO times. The mechanisms were right;
  * the delivery assumption ("a building agent polls status constantly") was
  * false. Routing the SAME banners through the surfaces a build actually
- * crosses means three processes must compose them — the CLI, the editor dev
- * server, and a project's own `npm run playtest` — so the text and the
- * thresholds move to the layer all three already depend on (this package: CLI
- * -> SDK -> engine, never the reverse). There is exactly ONE owner of the
- * wording and ONE owner of the numbers; every channel calls it.
+ * crosses means two processes must compose them — the CLI and the editor dev
+ * server — so the text and the thresholds move to the layer both already
+ * depend on (this package: CLI -> SDK -> engine, never the reverse). There is
+ * exactly ONE owner of the wording and ONE owner of the numbers; every
+ * channel calls it.
  *
  * COMMIT CADENCE. Measured failure (blind-probe audit, three consecutive
  * probes): each quoted the project docs' "one commit per slice" bar back at
@@ -122,7 +122,7 @@ export function uncommittedWorkAge(
 }
 
 /** Which step the batch has reached — the ONE place the cadence thresholds are
- *  compared, so every channel (status, playtest, dev server, eval) agrees. */
+ *  compared, so every channel (status, dev server, eval) agrees. */
 export function commitCadenceTier(work: UncommittedWork | null): TripwireTier {
   if (!work || work.ageMs < CADENCE_NOTICE_MS) return 'silent';
   return work.ageMs < CADENCE_LOUD_MS ? 'notice' : 'loud';
@@ -223,7 +223,7 @@ function git(cwd: string, args: string[]): string | null {
  *
  * `null` — say nothing — when there is no project, no git work tree, or a
  * clean tree. Two `git` invocations plus one `stat` per dirty path (capped),
- * made on a caller's own event (a status request, a finished playtest run, a
+ * made on a caller's own event (a status request, a
  * save the dev server already validated) — never on a timer.
  */
 export function readUncommittedWork(
@@ -357,13 +357,11 @@ export function newestSourceMtime(projectRoot: string): number | null {
  * The newest mtime (epoch ms) among this project's LIVE-EVIDENCE artifacts, or
  * `null` when the game has never run.
  *
- * The two artifacts are the same pair the idiom checker's "has this ever been
- * played" rule reads, for the same reason: both are written by the tools
- * themselves while a real browser runs the real game, so neither can be
- * produced by intending to play.
+ * The artifact is the same one the idiom checker's "has this ever been
+ * played" rule reads, for the same reason: it is written by the editor server
+ * itself while a real browser runs the real game, so it cannot be produced by
+ * intending to play.
  *   - `logs/play-*.jsonl` — one per Play session, opened by the editor server.
- *   - `.vgai/last-run/**` — what a bot run leaves behind (screenshots, and the
- *     `playtest.json` verdict `npm run playtest` files).
  */
 export function newestEvidenceMtime(projectRoot: string): number | null {
   let newest: number | null = null;
@@ -384,13 +382,6 @@ export function newestEvidenceMtime(projectRoot: string): number | null {
   } catch {
     /* no logs dir */
   }
-
-  const runDir = join(projectRoot, '.vgai', 'last-run');
-  try {
-    for (const entry of readdirSync(runDir)) consider(join(runDir, entry));
-  } catch {
-    /* no run dir */
-  }
   return newest;
 }
 
@@ -421,7 +412,7 @@ export function staleEvidenceBanner(
   if (newestEvidence !== null && newestEvidence >= newestSource) return null;
   const gap =
     newestEvidence === null
-      ? '  no live evidence exists at all — no logs/play-*.jsonl, no .vgai/last-run artifacts.'
+      ? '  no live evidence exists at all — no logs/play-*.jsonl.'
       : `  newest source: ${new Date(newestSource).toISOString()}\n` +
         `  newest live evidence: ${new Date(newestEvidence).toISOString()}`;
   return [
@@ -436,8 +427,8 @@ export function staleEvidenceBanner(
     '  invisible mesh, camera inside the geometry) are invisible to every one',
     '  of them.',
     '',
-    '  Play or playtest before claiming it works: `vgai play`, then look, or',
-    '  `npm run playtest` for the bot proof.',
+    '  Play before claiming it works: `vgai play`, then look, and playtest',
+    '  live through `vgai eval`.',
     '================================================================',
   ].join('\n');
 }
@@ -481,7 +472,7 @@ export function unplayedSessionTier(
  * without ever producing live-play evidence — pure, driven directly by a test.
  *
  * The evidence signal is the SAME pair `newestEvidenceMtime` walks (a Play
- * session's `logs/play-*.jsonl`, a bot run's `.vgai/last-run/**`), so this
+ * session's `logs/play-*.jsonl`), so this
  * banner and the staleness banner can never disagree about what counts as
  * having run. Nothing new is instrumented on the game side: both artifacts are
  * already written by the tools themselves while a real browser runs the real
@@ -514,8 +505,8 @@ export function unplayedSessionBanner(
     '  nothing — are invisible to all of them, and the longer the first play',
     '  is deferred the more work is stacked on top of an unverified base.',
     '',
-    '  Play it now: `vgai play`, then look — or `npm run playtest` for the',
-    '  bot proof.',
+    '  Play it now: `vgai play`, then look — and direct the resident tester',
+    '  from the live session (`vgai eval`).',
     '================================================================',
   ].join('\n');
 }

package/src/project/index.ts

@@ -38,14 +38,11 @@ import { registerInspectionOperations } from './inspection-operation.js';
 import { registerManifestOperations } from './manifest-operations.js';
 
 /**
- * Register every B2 `project.*` operation onto `registry`.
+ * Register every `project.*` operation onto `registry`.
  *
- * WO-8 removed the twelve `.vscn` document tools:
- * `project.scene.{read,validate,diff,apply}`,
- * `project.scene.entity.{add,update,move,remove}` and
- * `project.scene.component.{list,add,update,remove}`. They read and wrote the
- * deleted scene format; a three root is authored as TSX source now, so the source
- * tools (`project.file.*` / the editor's own adapter seam) are what act on it.
+ * There are no scene-document tools here: a three root is authored as TSX
+ * SOURCE, so the source tools (`project.file.*` / the editor's own adapter
+ * seam) are what act on it.
  */
 export function registerProjectOperations(registry: ToolRegistry): void {
   registerManifestOperations(registry);

package/src/project/provenance.ts

@@ -3,62 +3,76 @@ import { GenerationBillingSchema } from '../generations.js';
 
 export const PROJECT_PROVENANCE_PATH = '.vgai/provenance.json';
 
-export const ProjectProvenanceOutputSchema = z.object({
-  path: z.string(),
-  bytes: z.number().int().nonnegative(),
-  sha256: z.string().regex(/^[a-f0-9]{64}$/),
-  mediaType: z.string().optional(),
-  role: z.enum(['asset', 'prefab', 'provenance', 'other']).optional(),
-});
+export const ProjectProvenanceOutputSchema = z
+  .object({
+    path: z.string(),
+    bytes: z.number().int().nonnegative(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    mediaType: z.string().optional(),
+    role: z.enum(['asset', 'prefab', 'provenance', 'other']).optional(),
+  })
+  .strict();
 
-export const ProjectProvenanceExecutionSchema = z.object({
-  mode: z.enum(['mock', 'direct', 'managed']),
-  provider: z.string(),
-  operation: z.string().optional(),
-  model: z.string().optional(),
-  requestId: z.string().optional(),
-  taskId: z.string().optional(),
-  managedJobId: z.string().optional(),
-  billing: GenerationBillingSchema.optional(),
-});
+export const ProjectProvenanceExecutionSchema = z
+  .object({
+    mode: z.enum(['mock', 'direct', 'managed']),
+    provider: z.string(),
+    operation: z.string().optional(),
+    model: z.string().optional(),
+    requestId: z.string().optional(),
+    taskId: z.string().optional(),
+    managedJobId: z.string().optional(),
+    billing: GenerationBillingSchema.optional(),
+  })
+  .strict();
 
-export const ProjectProvenanceOperationSchema = z.object({
-  createdAt: z.string().datetime(),
-  operation: z.object({
-    name: z.string(),
-    source: z.string().optional(),
-  }),
-  execution: ProjectProvenanceExecutionSchema.optional(),
-  executions: z.array(ProjectProvenanceExecutionSchema).min(2).optional(),
-  input: z.json().optional(),
-  outputs: z.array(ProjectProvenanceOutputSchema).min(1),
-});
+export const ProjectProvenanceOperationSchema = z
+  .object({
+    createdAt: z.string().datetime(),
+    operation: z
+      .object({
+        name: z.string(),
+        source: z.string().optional(),
+      })
+      .strict(),
+    execution: ProjectProvenanceExecutionSchema.optional(),
+    executions: z.array(ProjectProvenanceExecutionSchema).min(2).optional(),
+    input: z.json().optional(),
+    outputs: z.array(ProjectProvenanceOutputSchema).min(1),
+  })
+  .strict();
 
-export const ProjectProvenanceDocumentSchema = z.object({
-  version: z.literal(1),
-  operations: z.record(z.string(), ProjectProvenanceOperationSchema),
-});
+export const ProjectProvenanceDocumentSchema = z
+  .object({
+    version: z.literal(1),
+    operations: z.record(z.string(), ProjectProvenanceOperationSchema),
+  })
+  .strict();
 
 export type ProjectProvenanceDocument = z.infer<typeof ProjectProvenanceDocumentSchema>;
 export type ProjectProvenanceOperation = z.infer<typeof ProjectProvenanceOperationSchema>;
 export type ProjectProvenanceExecution = z.infer<typeof ProjectProvenanceExecutionSchema>;
 
-export const ProjectAttributionEntrySchema = z.object({
-  key: z.string(),
-  name: z.string().optional(),
-  source: z.string().optional(),
-  sourceUrl: z.string().url().optional(),
-  author: z.string(),
-  license: z.string(),
-  text: z.string(),
-  operationIds: z.array(z.string()),
-  outputPaths: z.array(z.string()),
-});
+export const ProjectAttributionEntrySchema = z
+  .object({
+    key: z.string(),
+    name: z.string().optional(),
+    source: z.string().optional(),
+    sourceUrl: z.string().url().optional(),
+    author: z.string(),
+    license: z.string(),
+    text: z.string(),
+    operationIds: z.array(z.string()),
+    outputPaths: z.array(z.string()),
+  })
+  .strict();
 
-export const ProjectAttributionReportSchema = z.object({
-  version: z.literal(1),
-  entries: z.array(ProjectAttributionEntrySchema),
-});
+export const ProjectAttributionReportSchema = z
+  .object({
+    version: z.literal(1),
+    entries: z.array(ProjectAttributionEntrySchema),
+  })
+  .strict();
 
 export type ProjectAttributionEntry = z.infer<typeof ProjectAttributionEntrySchema>;
 export type ProjectAttributionReport = z.infer<typeof ProjectAttributionReportSchema>;

package/src/project/run-name.ts

@@ -1,53 +1,18 @@
 /**
- * What a run is CALLED — one owner of the bound, and of the fallback a run
- * gets when nobody named it.
+ * What a run is CALLED — one owner of the bound.
  *
- * WHY THIS EXISTS. `vgai play --name <text>` and `npm run playtest --
- * '{"name":"…"}'` both exist so a run is findable by what it was testing, and
- * the measured answer to an optional field is that it stays empty: every play
- * event in the foundry probe's 45-minute session journal reads `"name":null`.
- * A label nobody supplies indexes nothing, so the run that DOES know what it
- * was testing supplies it — a route-targeted playtest is named after its
- * routes, and a full-suite run is named `playtest`. Nothing is taught and no
- * habit is required; the default carries the information.
+ * WHY THIS EXISTS. `vgai play --name <text>` exists so a run is findable by
+ * what it was testing.
  *
  * WHAT STAYS UNNAMED, deliberately: interactive `vgai play` with no `--name`.
  * A person pressing play is not testing a named thing, and inventing a label
  * for it would put noise in exactly the directory this makes greppable.
  *
  * Pure — no filesystem, no clock. `editor-server.ts`'s `playRunSlug` is the
- * OTHER half (slugging a name into a filename segment) and reads the same
- * bound from here, so the two can never disagree about how long a run name
- * may be.
+ * OTHER half (slugging a name into a filename segment) and reads the bound
+ * from here, so the two can never disagree about how long a run name may be.
  */
 
 /** Bound on a run's name — long enough to stay recognisable in a directory
  *  listing, short enough that the timestamp beside it is still readable. */
 export const MAX_RUN_NAME = 40;
-
-/** The name a full-suite run gets: it targets no route in particular, and
- *  "which run was that" is still a question worth being able to answer. */
-export const FULL_SUITE_RUN_NAME = 'playtest';
-
-/**
- * The name for one playtest run.
- *
- * An explicit name always wins — it is the caller saying what this run was,
- * and no derivation is better informed than that. Otherwise the routes name
- * it, joined with `+` (a separator that survives being read back as a list,
- * unlike the `-` that route names themselves use), bounded at
- * {@link MAX_RUN_NAME}; and a run that named no route is
- * {@link FULL_SUITE_RUN_NAME}.
- *
- * `null` is impossible by construction — every playtest run gets a name — but
- * an explicit blank/whitespace name is treated as no name at all, the same
- * case a missing one is.
- */
-export function derivePlaytestRunName(
-  explicit: string | null | undefined,
-  routes: readonly string[],
-): string {
-  if (typeof explicit === 'string' && explicit.trim() !== '') return explicit.trim();
-  if (routes.length === 0) return FULL_SUITE_RUN_NAME;
-  return routes.join('+').slice(0, MAX_RUN_NAME).replace(/\+$/, '');
-}