@jxsuite/studio 6.1.1 → 8.0.0

package/src/services/ai-tools.ts

@@ -10,7 +10,7 @@
 
 import { createToolDefinition } from "@jxsuite/ai/tools";
 import type { ToolRegistry, ToolResult, WriteLedger } from "@jxsuite/ai/tools";
-import type { JxMutableNode, JxPath, JxStateDefinition } from "@jxsuite/schema/types";
+import type { JsonObject, JxMutableNode, JxPath } from "@jxsuite/schema/types";
 import { getNodeAtPath } from "../state";
 import type { Tab } from "../tabs/tab";
 import {
@@ -32,7 +32,7 @@ import {
   snapshotBeforeWrite,
   translateValidationError,
 } from "./ai-write-report";
-import type { RenderVerdict } from "./ai-write-report";
+import type { CandidateDocument, RenderVerdict } from "./ai-write-report";
 
 /* Re-exported from its new home so `ai-project-tools.ts` and the tests keep their import: the
    translation moved with the verdict it belongs to (`ai-write-report.ts`), where every document
@@ -43,6 +43,14 @@ const PATH_DESCRIPTION =
   "Path to a node in the document, as a JSON array of keys/indices from the root " +
   '(e.g. ["children", 0, "children", 1]). Use read_document to discover valid paths.';
 
+/**
+ * The node at `path`, typed as what {@link getNodeAtPath} actually answers: a path the model made up
+ * runs off the tree, and that is `undefined`, which every tool here reports as "No node exists".
+ */
+function nodeAt(doc: JxMutableNode, path: JxPath): JxMutableNode | undefined {
+  return getNodeAtPath(doc, path);
+}
+
 /** Steering error for document tools called with no active tab. */
 function noDocError(): ToolResult {
   return {
@@ -64,8 +72,8 @@ function noDocError(): ToolResult {
  * @param {import("../tabs/tab").Tab} tab
  * @param {(t: import("../tabs/tab").Tab) => void} mutationFn
  * @param {string} summary
- * @param {(doc: unknown) => Promise<string[]>} validate
- * @param {((doc: unknown) => Promise<RenderVerdict>) | undefined} renderCheck
+ * @param {(doc: CandidateDocument) => Promise<string[]>} validate
+ * @param {((doc: CandidateDocument) => Promise<RenderVerdict>) | undefined} renderCheck
  * @param {Record<string, string> | undefined} projectStyle
  * @returns {Promise<import("@jxsuite/ai/tools").ToolResult>}
  */
@@ -74,8 +82,8 @@ async function applyAndValidate(
   tab: Tab,
   mutationFn: (t: Tab) => void,
   summary: string,
-  validate: (doc: unknown) => Promise<string[]>,
-  renderCheck: ((doc: unknown) => Promise<RenderVerdict>) | undefined,
+  validate: (doc: CandidateDocument) => Promise<string[]>,
+  renderCheck: ((doc: CandidateDocument) => Promise<RenderVerdict>) | undefined,
   projectStyle: Record<string, string> | undefined,
 ): Promise<ToolResult> {
   const deps = { getProjectStyle: () => projectStyle, renderCheck, validate };
@@ -109,9 +117,9 @@ async function applyAndValidate(
  * @param {import("@jxsuite/ai/tools").ToolRegistry} registry
  * @param {{
  *   getTab: () => import("../tabs/tab").Tab | null;
- *   validate?: (doc: unknown) => Promise<string[]>;
+ *   validate?: (doc: CandidateDocument) => Promise<string[]>;
  *   saveFile?: (relPath: string, content: string) => Promise<void>;
- *   renderCheck?: (doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>;
+ *   renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
  *   projectStyle?: Record<string, string>;
  *   getProjectStyle?: () => Record<string, string> | undefined;
  *   findOpenTab?: (path: string) => import("../tabs/tab").Tab | null;
@@ -131,9 +139,9 @@ export function registerAiTools(
     reloadTab,
   }: {
     getTab: () => Tab | null;
-    validate?: (doc: unknown) => Promise<string[]>;
+    validate?: (doc: CandidateDocument) => Promise<string[]>;
     saveFile?: (relPath: string, content: string) => Promise<void>;
-    renderCheck?: (doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>;
+    renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
     projectStyle?: Record<string, string> | undefined;
     /**
      * Live variant of `projectStyle` — takes precedence; re-read per tool call so a project
@@ -195,9 +203,11 @@ export function registerAiTools(
         if (!tab) {
           return noDocError();
         }
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, which refuses
+           a `path` that is present but not an array. Its items are not checked; a key that does
+           not resolve makes `nodeAt` answer undefined, reported just below. */
         const { path } = args as { path?: JxPath };
-        const node =
-          path && path.length > 0 ? getNodeAtPath(tab.doc.document, path) : tab.doc.document;
+        const node = path && path.length > 0 ? nodeAt(tab.doc.document, path) : tab.doc.document;
         if (node === undefined) {
           return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
         }
@@ -239,8 +249,12 @@ export function registerAiTools(
         if (!tab) {
           return noDocError();
         }
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `path` is a
+           present array and `key` a present string. `value` declares no type, so it is any JSON
+           value or absent, all of which `JxNodeValue` includes. A `path` whose items do not resolve
+           is caught by `nodeAt` just below. */
         const { path, key, value } = args as { path: JxPath; key: string; value?: JxNodeValue };
-        const node = getNodeAtPath(tab.doc.document, path);
+        const node = nodeAt(tab.doc.document, path);
         if (node === undefined) {
           return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
         }
@@ -286,6 +300,11 @@ export function registerAiTools(
         if (!tab) {
           return noDocError();
         }
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `parentPath` is
+           a present array, `node` a present object, and `index` a present number — or a numeric
+           string, which the validator also admits for an integer and `splice` coerces alike.
+           `node` is a model-written tree whose shape the schema check after the write judges, and
+           a `parentPath` that does not resolve is caught just below. */
         const {
           parentPath,
           index,
@@ -295,7 +314,7 @@ export function registerAiTools(
           index: number;
           node: JxMutableNode;
         };
-        const parent = getNodeAtPath(tab.doc.document, parentPath);
+        const parent = nodeAt(tab.doc.document, parentPath);
         if (parent === undefined) {
           return { success: false, error: `No node exists at path ${JSON.stringify(parentPath)}.` };
         }
@@ -373,12 +392,12 @@ export function registerAiTools(
         if (!tab) {
           return noDocError();
         }
-        const { path, property, value } = args as {
-          path: JxPath;
-          property: string;
-          value?: unknown;
-        };
-        if (getNodeAtPath(tab.doc.document, path) === undefined) {
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `path` is a
+           present array and `property` a present string; a `path` that does not resolve is caught
+           just below. `value` is read untyped and stringified. */
+        const { path, property } = args as { path: JxPath; property: string };
+        const { value } = args;
+        if (nodeAt(tab.doc.document, path) === undefined) {
           return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
         }
         const prop = property;
@@ -420,8 +439,11 @@ export function registerAiTools(
         if (!tab) {
           return noDocError();
         }
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `path` is a
+           present array and `value` a present string; a `path` that does not resolve is caught
+           just below. */
         const { path, value } = args as { path: JxPath; value: string };
-        if (getNodeAtPath(tab.doc.document, path) === undefined) {
+        if (nodeAt(tab.doc.document, path) === undefined) {
           return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
         }
         return applyAndValidate(
@@ -469,7 +491,10 @@ export function registerAiTools(
         if (!tab) {
           return noDocError();
         }
-        const { key, value } = args as { key: string; value: JxStateDefinition };
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, so `key` is a
+           present string. */
+        const { key } = args as { key: string };
+        const { value } = args;
         if (tab.doc.document.state && tab.doc.document.state[key] !== undefined) {
           return {
             success: false,
@@ -482,6 +507,10 @@ export function registerAiTools(
           /* `mutateAddDef` rather than `mutateUpdateProperty`: the latter deletes on "", which is
              wrong for a state default (`"title": ""`). It also records the op, so the canvas, the
              history and collaborators each get the edit as an edit. */
+          /* SAFETY: `value` is required, so the registry refused it missing or null; it is the
+             model's state entry, possibly a scalar default (`0`, `""`) the schema admits.
+             `mutateAddDef` only clones `def` and stores it under `state[key]`, never reading it
+             as the object its parameter names. */
           (t) => mutateAddDef(t, key, value as Record<string, JsonValue>),
           `Added state "${key}".`,
           validate,
@@ -519,7 +548,10 @@ export function registerAiTools(
         if (!tab) {
           return noDocError();
         }
-        const { key, value } = args as { key: string; value?: JxStateDefinition | null };
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, so `key` is a
+           present string. */
+        const { key } = args as { key: string };
+        const { value } = args;
         if (!tab.doc.document.state || tab.doc.document.state[key] === undefined) {
           return {
             success: false,
@@ -535,6 +567,9 @@ export function registerAiTools(
             if (value == null) {
               mutateRemoveDef(t, key);
             } else {
+              /* SAFETY: the model's state entry, possibly a scalar default the schema admits.
+                 `mutateAddDef` only clones `def` and stores it under `state[key]`, never reading
+                 it as the object its parameter names. */
               mutateAddDef(t, key, value as Record<string, JsonValue>);
             }
           },
@@ -580,6 +615,9 @@ export function registerAiTools(
         if (!tab) {
           return noDocError();
         }
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: both paths are
+           present arrays, and `toIndex` a present number or numeric string (the validator admits
+           both for an integer). Paths that do not resolve are caught just below. */
         const { fromPath, toParentPath, toIndex } = args as {
           fromPath: JxPath;
           toParentPath: JxPath;
@@ -588,13 +626,13 @@ export function registerAiTools(
         if (fromPath.length < 2) {
           return { success: false, error: "Cannot move the document root." };
         }
-        if (getNodeAtPath(tab.doc.document, fromPath) === undefined) {
+        if (nodeAt(tab.doc.document, fromPath) === undefined) {
           return {
             success: false,
             error: `No node exists at fromPath ${JSON.stringify(fromPath)}.`,
           };
         }
-        if (getNodeAtPath(tab.doc.document, toParentPath) === undefined) {
+        if (nodeAt(tab.doc.document, toParentPath) === undefined) {
           return {
             success: false,
             error: `No node exists at toParentPath ${JSON.stringify(toParentPath)}.`,
@@ -644,7 +682,10 @@ export function registerAiTools(
             error: "File operations are not available in this environment.",
           };
         }
-        const { path, content } = args as { path: string; content: object };
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `path` is a
+           present string and `content` a present JSON object (not an array, not null). Whether that
+           object is a Jx document is what `validate` and `renderCheck` below decide. */
+        const { path, content } = args as { path: string; content: JsonObject };
         // Inside the project or not at all (ai.md §4): the platform write is given this path.
         const relPath = normalizeRelPath(path);
         if (relPath === null) {
@@ -728,7 +769,10 @@ export function registerAiTools(
             error: "File operations are not available in this environment.",
           };
         }
-        const { path, content } = args as { path: string; content: object };
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `path` is a
+           present string and `content` a present JSON object (not an array, not null). Whether that
+           object is a Jx document is what `validate` and `renderCheck` below decide. */
+        const { path, content } = args as { path: string; content: JsonObject };
         const relPath = normalizeRelPath(path);
         if (relPath === null) {
           return invalidPathResult(path);

package/src/services/ai-write-report.ts

@@ -2,26 +2,27 @@
  * Ai-write-report.ts — what the model is told after a document write, whoever made it.
  *
  * Extracted from `ai-tools.ts`'s `applyAndValidate`, which used to own both halves of a document
- * tool: the transaction and the verdict on it. The verdict is the half every document write needs
- * — the seven hand-registered tree tools AND every command the assistant runs through
+ * tool: the transaction and the verdict on it. The verdict is the half every document write needs —
+ * the seven hand-registered tree tools AND every command the assistant runs through
  * `services/ai-command-tools.ts` — so it lives here, in two functions the caller brackets its write
  * with:
  *
- * 1. {@link snapshotBeforeWrite} reads the document's schema errors and render state BEFORE the
- *    write, because the loop's signal (specs/ai.md §3.1) is "what did this edit newly introduce",
- *    not "is the document valid": a page that was already broken must not make every subsequent
- *    edit read as the culprit.
+ * 1. {@link snapshotBeforeWrite} reads the document's schema errors and render state BEFORE the write,
+ *    because the loop's signal (specs/ai.md §3.1) is "what did this edit newly introduce", not "is
+ *    the document valid": a page that was already broken must not make every subsequent edit read
+ *    as the culprit.
  * 2. {@link reportDocumentWrite} compares AFTER the write, translating each new schema error into a
- *    fix hint the model can act on, running the render check only when rendering worked before,
- *    and appending the soft token-discipline hints to a success.
+ *    fix hint the model can act on, running the render check only when rendering worked before, and
+ *    appending the soft token-discipline hints to a success.
  *
- * The change stays applied either way (optimistic apply + undo, specs/ai.md §3.1); reporting the errors lets
- * the agent loop self-correct on the next round.
+ * The change stays applied either way (optimistic apply + undo, specs/ai.md §3.1); reporting the
+ * errors lets the agent loop self-correct on the next round.
  *
  * @license MIT
  */
 
 import type { ToolResult } from "@jxsuite/ai/tools";
+import type { JsonValue, JxMutableNode } from "@jxsuite/schema/types";
 import { toRaw } from "../reactivity";
 import type { Tab } from "../tabs/tab";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
@@ -29,12 +30,19 @@ import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
 /** A render probe's answer: rendered, or the message it threw. */
 export type RenderVerdict = { ok: true } | { ok: false; error: string };
 
+/**
+ * A document as the validator and the render probe receive it: the live tree of an open tab, or the
+ * JSON a tool was handed (a `create_page` argument, a parsed `write_file` body) before anything has
+ * said it is a document. Judging that is what the two of them are for.
+ */
+export type CandidateDocument = JxMutableNode | JsonValue;
+
 /** What a write reporter needs. Every member is what `registerAiTools` already takes by injection. */
 export interface WriteReportDeps {
   /** Schema errors for a document, as raw ajv sentences. */
-  validate: (doc: unknown) => Promise<string[]>;
+  validate: (doc: CandidateDocument) => Promise<string[]>;
   /** The detached-DOM render probe, when the host has one. */
-  renderCheck?: ((doc: unknown) => Promise<RenderVerdict>) | undefined;
+  renderCheck?: ((doc: CandidateDocument) => Promise<RenderVerdict>) | undefined;
   /** The project's design tokens, read per call so a project opened mid-session contributes. */
   getProjectStyle?: (() => Record<string, string> | undefined) | undefined;
 }

package/src/services/ai-writes.ts

@@ -22,7 +22,7 @@
  * @docs studio/ai/chat
  */
 
-import type { Message } from "@jxsuite/ai/chat-state";
+import type { LiveMessage } from "@jxsuite/ai/messages";
 import { createLedger } from "@jxsuite/ai/tools";
 import type { AiWrite, WriteLedger } from "@jxsuite/ai/tools";
 
@@ -113,7 +113,7 @@ export function summarizeWrites(writes: AiWrite[]): string {
     return failed > 0 ? `${failed} change${failed === 1 ? "" : "s"} failed` : "";
   }
   const files = `Changed ${paths.size} file${paths.size === 1 ? "" : "s"}`;
-  const diskPaths = new Set(applied.filter((w) => w.disk).map((w) => w.path));
+  const diskPaths = new Set(applied.flatMap((w) => (w.disk ? [w.path] : [])));
   const parts = [files];
   if (diskPaths.size > 0) {
     parts.push(
@@ -150,13 +150,13 @@ export function resetAiWrites(): void {
  * message in it belongs to some other conversation: filing there would draw "Changed 1 file", and
  * Restore, under a reply that changed nothing.
  *
- * @param {readonly Message[]} messages
+ * @param {readonly LiveMessage[]} messages
  * @param {string} [userId] - The id of the user message this turn answers; without one, the whole
  *   transcript is the turn
  * @returns {string | null} Null when the turn drew nothing (so it ran no tool either), or when its
  *   user message has left the transcript
  */
-export function turnAnchor(messages: readonly Message[], userId?: string): string | null {
+export function turnAnchor(messages: readonly LiveMessage[], userId?: string): string | null {
   let anchor: string | null = null;
   for (let index = messages.length - 1; index >= 0; index--) {
     const message = messages[index]!;

package/src/services/automation.ts

@@ -37,10 +37,12 @@ import { seedProjectList } from "../project-list";
 import { activeTab } from "../workspace/workspace";
 import { shell } from "../shell";
 import { collabState } from "../collab/collab-state";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { canvasPointAt, revealCanvasPath } from "../canvas/iframe-host";
 import { probeIdle } from "./idle";
 import type { CanvasPoint } from "../canvas/iframe-host";
 import type { IdleOptions } from "./idle";
+import type { CommandArgValues } from "../commands/command-args";
 import type { CommandContext } from "../commands/context";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { PeerPresence } from "../collab/collab-state";
@@ -50,9 +52,6 @@ import type { GitBranchesResult, GitStatusResult, ProjectListEntry } from "../ty
 import type { GitLogEntry } from "../shell";
 import type { JxPath } from "../state";
 
-/** Loosely-typed arguments, as they arrive from a manifest step, a palette prompt or a tool call. */
-export type AutomationArgs = Record<string, unknown>;
-
 /**
  * What the hook needs that it cannot import.
  *
@@ -93,13 +92,14 @@ export function isScriptable(command: AnyCommand): boolean {
 // ─── The registry-gap declaration ─────────────────────────────────────────────
 
 /**
- * How a manifest id the registry does not declare is going to stop existing.
+ * Why a manifest id the registry does not declare will never be one.
  *
- * - `command` — a thing a user does, so it becomes a registry record. The value names who lands it.
- * - `seed` — a remote's state, addressed through {@link AutomationApi.seed}.
- * - `refused` — §13.5 says the app will never provide it; the manifest step is deleted.
+ * There were three fates. `command` (a thing a user does, so it becomes a registry record) emptied
+ * when `media.browse` landed in `media/media-commands.ts`, the last of them; `seed` (a remote's
+ * state) is answered from {@link seedIds}. What is left is `refused`: §13.5 says the app will never
+ * provide it, and the manifest step is deleted.
  */
-export type GapDisposition = "command" | "seed" | "refused";
+export type GapDisposition = "refused";
 
 export interface ManifestId {
   disposition: GapDisposition;
@@ -118,19 +118,18 @@ export interface ManifestId {
  * — only to explain, when the registry refuses an id, which of the three fates that id has.
  *
  * This is a countdown, in the idiom of the checker's own `TOGGLE_DEBT`: it may only shrink. It went
- * 39 → 8 when the manifest converted, and 8 → 7 when `element.insertData` became `insert.data`
- * (`canvas/canvas-render.ts`). What left: every `seed` entry, now read off {@link seedIds} and
+ * 39 → 8 when the manifest converted, 8 → 7 when `element.insertData` became `insert.data`
+ * (`canvas/canvas-render.ts`), and down to five when `media.browse` became a record of its own
+ * (`media/media-commands.ts`). What left: every `seed` entry, now read off {@link seedIds} and
  * answered from the live registry rather than from a hand-kept list; every `toggle*` entry, which
- * {@link TOGGLE_ID} refuses before this map is ever consulted; and every `command` entry whose
- * record has since landed.
+ * {@link TOGGLE_ID} refuses before this map is ever consulted; and every `command` entry, each of
+ * whose records has landed.
  *
- * What is left is two kinds. Two `command` entries are the manifest's real registry gaps — each
- * reached today by an `input` step clicking a hand-stamped region, and each of those steps carries
- * an `unstable` hatch naming the phase that lands the record, so this map and that hatch count are
- * the same debt. Five `refused` entries are NOT a countdown: they are §13.5's normative refusals,
- * and they stay so that a caller reaching for one gets the reason instead of "unknown command".
+ * What is left is one kind, and it is NOT a countdown: five `refused` entries, §13.5's normative
+ * refusals, which stay so that a caller reaching for one gets the reason instead of "unknown
+ * command".
  */
-export const AUTOMATION_COMMANDS: Readonly<Record<string, ManifestId>> = {
+export const AUTOMATION_COMMANDS = {
   "file.contextMenu": {
     disposition: "refused",
     note: "opening a menu to press an item names a control; the ITEM is the command",
@@ -139,20 +138,25 @@ export const AUTOMATION_COMMANDS: Readonly<Record<string, ManifestId>> = {
     disposition: "refused",
     note: "matched RENDERED TEXT, which R1 of scripts/screenshots/README.md forbids; a row is addressed by its data-jx-path",
   },
-  "media.browse": { disposition: "command", note: "media.browse, site-architecture.md §9.4" },
   "project.showWelcome": {
     disposition: "refused",
     note: "cold start is a startup profile (?profile=fresh), not an action",
   },
   "settings.setSection": {
     disposition: "refused",
-    note: 'mirrored the section registry\'s LABELS; say settings.open { section: "cssVars" }',
+    note: 'mirrored the section registry\'s LABELS; say settings.open { section: "contexts" }',
   },
   "view.setStatus": {
     disposition: "refused",
     note: "the status bar is not staged — if a capture needs a calm shell, the app must BE calm",
   },
-};
+} as const satisfies Readonly<Record<string, ManifestId>>;
+
+/**
+ * {@link AUTOMATION_COMMANDS} keyed for lookup by an arbitrary id. A Map rather than an index into
+ * the object, so an id such as `"constructor"` finds nothing instead of `Object.prototype`'s.
+ */
+const COMMAND_GAPS: ReadonlyMap<string, ManifestId> = new Map(Object.entries(AUTOMATION_COMMANDS));
 
 // ─── The seed registry, under the Remote Rule ─────────────────────────────────
 
@@ -161,7 +165,7 @@ export interface SeedDefinition {
   id: string;
   /** The network or IPC boundary this seed stands in for. The Remote Rule, written down per seed. */
   boundary: string;
-  run: (args: AutomationArgs) => void | Promise<void>;
+  run: (args: CommandArgValues) => void | Promise<void>;
 }
 
 /**
@@ -170,7 +174,7 @@ export interface SeedDefinition {
  * Every one of these was a method on the old surface. Each writes state a USER writes, so each is a
  * COMMAND — and a fixture that stages it photographs a state no session could have reached.
  */
-export const REFUSED_SEEDS: Readonly<Record<string, string>> = {
+export const REFUSED_SEEDS = {
   openSettings: 'a user opens Settings — run("settings.open")',
   select: 'a user selects a node — run("selection.set", { path })',
   setActivity: 'a user picks a Navigator panel — run("navigator.showPanel", { panel })',
@@ -178,9 +182,12 @@ export const REFUSED_SEEDS: Readonly<Record<string, string>> = {
   setStatus:
     "the status bar reports what the app just did; staging it is the one lie the Remote Rule (studio.md §13.5) names outright",
   setZoom: 'a user zooms — run("canvas.setZoom", { zoom })',
-};
+} as const satisfies Readonly<Record<string, string>>;
+
+/** {@link REFUSED_SEEDS} keyed for lookup by an arbitrary seed name, as {@link COMMAND_GAPS} is. */
+const SEED_REFUSALS: ReadonlyMap<string, string> = new Map(Object.entries(REFUSED_SEEDS));
 
-function arrayArg<T>(args: AutomationArgs, key: string): T[] {
+function arrayArg<T>(args: CommandArgValues, key: string): T[] {
   const value = args[key];
   if (value === undefined) {
     return [];
@@ -188,23 +195,28 @@ function arrayArg<T>(args: AutomationArgs, key: string): T[] {
   if (!Array.isArray(value)) {
     throw new TypeError(`seed argument "${key}" must be an array`);
   }
+  /* SAFETY: a seed's arguments are a fixture written against the boundary type it stands in for
+     (the screenshot manifest's `seed` steps), so only the container is checked here — exactly as
+     much as the remote it replaces would have checked before handing its JSON over. */
   return value as T[];
 }
 
-function requiredArg<T>(args: AutomationArgs, key: string): T {
+function requiredArg<T>(args: CommandArgValues, key: string): T {
   const value = args[key];
-  if (value === null || typeof value !== "object") {
+  if (!isNonNullObject(value)) {
     throw new TypeError(`seed argument "${key}" must be an object`);
   }
+  /* SAFETY: as in `arrayArg`: a fixture written against the boundary type it stands in for, of
+     which only the object container is checked here. */
   return value as T;
 }
 
-function optionalString(args: AutomationArgs, key: string): string | undefined {
+function optionalString(args: CommandArgValues, key: string): string | undefined {
   const value = args[key];
   if (value === undefined) {
     return undefined;
   }
-  if (typeof value !== "string") {
+  if (!isString(value)) {
     throw new TypeError(`seed argument "${key}" must be a string`);
   }
   return value;
@@ -216,7 +228,9 @@ function optionalString(args: AutomationArgs, key: string): string | undefined {
  * Each one writes exactly what its named boundary would have written, and nothing else — the git
  * seed does not also open the Source Control panel, because a user does that.
  */
-export function createSeeds(deps: AutomationDeps): SeedDefinition[] {
+export function createSeeds(
+  deps: Pick<AutomationDeps, "seedAssistantMessages" | "seedPublishConnected">,
+): SeedDefinition[] {
   return [
     {
       boundary: "the assistant's model stream",
@@ -252,10 +266,13 @@ export function createSeeds(deps: AutomationDeps): SeedDefinition[] {
       id: "seed.publish",
       run: (args) => {
         const accountId = optionalString(args, "accountId");
-        deps.seedPublishConnected({
+        const connected: Parameters<AutomationDeps["seedPublishConnected"]>[0] = {
           deployment: requiredArg<PagesDeploymentInfo>(args, "deployment"),
-          ...(accountId ? { accountId } : {}),
-        });
+        };
+        if (accountId) {
+          connected.accountId = accountId;
+        }
+        deps.seedPublishConnected(connected);
       },
     },
     {
@@ -264,9 +281,16 @@ export function createSeeds(deps: AutomationDeps): SeedDefinition[] {
       run: (args) => {
         // The working tree really is a remote here: the git-panel shot photographs whatever the
         // Author happened to have dirty, because its project lives inside this repository.
-        shell.git.status = (args.status as GitStatusResult | undefined) ?? null;
-        shell.git.branches = (args.branches as GitBranchesResult | undefined) ?? null;
-        shell.git.logEntries = (args.log as GitLogEntry[] | undefined) ?? null;
+        /* SAFETY: as in `arrayArg`: a fixture written against the platform's git route answers it
+           stands in for, passed on as the route's JSON would have been, unchecked. */
+        const { status, branches, log } = args as {
+          status?: GitStatusResult;
+          branches?: GitBranchesResult;
+          log?: GitLogEntry[];
+        };
+        shell.git.status = status ?? null;
+        shell.git.branches = branches ?? null;
+        shell.git.logEntries = log ?? null;
         shell.git.loading = false;
         shell.git.error = null;
         render();
@@ -293,12 +317,9 @@ export function createSeeds(deps: AutomationDeps): SeedDefinition[] {
  * its `run`, never while building it, so the no-op deps below can never be called.
  */
 export function seedIds(): string[] {
-  const inert = {
-    registry: undefined as unknown as CommandRegistry,
-    seedAssistantMessages: () => {},
-    seedPublishConnected: () => {},
-  } satisfies AutomationDeps;
-  return createSeeds(inert).map((seed) => seed.id);
+  return createSeeds({ seedAssistantMessages: () => {}, seedPublishConnected: () => {} }).map(
+    (seed) => seed.id,
+  );
 }
 
 // ─── The API ──────────────────────────────────────────────────────────────────
@@ -340,8 +361,8 @@ export interface AutomationProbe {
 }
 
 export interface AutomationApi {
-  run: (id: string, args?: AutomationArgs) => Promise<void>;
-  seed: (id: string, args?: AutomationArgs) => Promise<void>;
+  run: (id: string, args?: CommandArgValues) => Promise<void>;
+  seed: (id: string, args?: CommandArgValues) => Promise<void>;
   probe: AutomationProbe;
 }
 
@@ -391,12 +412,9 @@ function unknownCommandMessage(
   if (seeds.has(id)) {
     return `"${id}" is a seed, not a command — call seed("${id}", …)`;
   }
-  const gap = AUTOMATION_COMMANDS[id];
-  if (gap?.disposition === "refused") {
-    return `"${id}" is refused by spec §13.5: ${gap.note}`;
-  }
+  const gap = COMMAND_GAPS.get(id);
   if (gap) {
-    return `"${id}" has no command record yet (${gap.note}) — __jxAutomation.run projects the registry and nothing else`;
+    return `"${id}" is refused by spec §13.5: ${gap.note}`;
   }
   const known = registry
     .list()
@@ -435,7 +453,7 @@ export function createAutomationApi(deps: AutomationDeps): AutomationApi {
     },
     async seed(id, args = {}) {
       const bare = id.startsWith("seed.") ? id.slice(5) : id;
-      const refusal = REFUSED_SEEDS[bare];
+      const refusal = SEED_REFUSALS.get(bare);
       if (refusal) {
         throw new AutomationRefusedError(
           id,
@@ -453,6 +471,11 @@ export function createAutomationApi(deps: AutomationDeps): AutomationApi {
   };
 }
 
+declare global {
+  /** The automation hook, installed only on a page load that opted in with `?automation=1`. */
+  var __jxAutomation: AutomationApi | undefined;
+}
+
 /** The hook is opt-in per page load: only `?automation=1` installs it. */
 export function shouldInstallAutomation(search: string): boolean {
   return new URLSearchParams(search).get("automation") === "1";
@@ -466,6 +489,6 @@ export function installAutomationHook(deps: AutomationDeps): boolean {
   if (!shouldInstallAutomation(location.search)) {
     return false;
   }
-  (globalThis as Record<string, unknown>).__jxAutomation = createAutomationApi(deps);
+  globalThis.__jxAutomation = createAutomationApi(deps);
   return true;
 }