summer-engine 2.8.2 → 3.1.0

package/dist/{lib → core/capabilities}/creator.js

@@ -2,28 +2,16 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { lstat, readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { getCredentialMetadata, getCreatorToken, } from "./auth.js";
-import { getCreatorApiUrl, readSummerConfig, } from "./config.js";
-import { appendStoreJsonLine } from "./store.js";
+import { getCredentialMetadata, getCreatorToken, } from "../auth.js";
+import { getCreatorApiUrl, readSummerConfig, } from "../config.js";
+import { appendStoreJsonLine } from "../store.js";
+import { readJsonResponse } from "../util/http.js";
 export const CREATOR_API_CONTRACT = "summer.creator.v1";
 const CREATOR_PUBLISH_PATH = "/api/creator/v1/publish";
 const CREATOR_RELEASES_PATH = "/api/creator/v1/releases";
 const REQUIRED_SCOPE = "publish";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const VERSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
-export const CREATOR_API_AUDIT = {
-    auditedAt: "2026-07-30",
-    repository: "SummerEngine/summercraft",
-    contract: CREATOR_API_CONTRACT,
-    credentialAudience: "summercraft-creator",
-    requiredServerScope: REQUIRED_SCOPE,
-    operations: {
-        publish: { supported: true, route: CREATOR_PUBLISH_PATH },
-        releases: { supported: true, route: CREATOR_RELEASES_PATH },
-        logs: { supported: false, route: null },
-    },
-};
-const LOGS_RECOVERY = "Recovery: Summercraft must first own a durable runtime-log source with retention, redaction, project/release authorization, and a versioned query route. No placeholder logs were returned.";
 export class CreatorOperationError extends Error {
     code;
     operation;
@@ -55,7 +43,7 @@ async function resolveProjectId(explicit) {
 async function requireCreatorCredential(operation) {
     const token = await getCreatorToken();
     if (!token) {
-        throw new CreatorOperationError("creator_token_required", operation, "Creator publishing needs a separate Summercraft API token.", 'Recovery: run "summer login --creator", mint a token with the exact "publish" scope in the opened browser page, and paste its one-time sc_ value. Your core Summer login will not be changed.');
+        throw new CreatorOperationError("creator_token_required", operation, "Creator publishing needs a separate Summer Platform creator API token.", 'Recovery: run "summer login --creator", mint a token with the exact "publish" scope in the opened browser page, and paste its one-time sc_ value. Your core Summer login will not be changed.');
     }
     const metadata = await getCredentialMetadata();
     if (!metadata.creator?.scopes.includes(REQUIRED_SCOPE)) {
@@ -73,15 +61,12 @@ function recoveryForStatus(operation, status) {
     if (status === 409 && operation === "publish") {
         return "Recovery: read the server detail, bump an immutable version when required, then repeat the unconfirmed command to review the new exact target.";
     }
-    return `Recovery: retry once; if it repeats, check creator.apiUrl and the Summercraft creator API health.`;
+    return `Recovery: retry once; if it repeats, check creator.apiUrl and the Summer Platform creator API health.`;
 }
-async function readJsonResponse(response, operation) {
-    const text = await response.text();
-    let payload;
-    try {
-        payload = JSON.parse(text);
-    }
-    catch {
+async function readCreatorResponse(response, operation) {
+    const { json, parsed } = await readJsonResponse(response);
+    const payload = json;
+    if (!parsed) {
         throw new CreatorOperationError("creator_invalid_response", operation, `The creator API returned a non-JSON response (${response.status}).`, recoveryForStatus(operation, response.status), response.status);
     }
     if (!response.ok) {
@@ -116,7 +101,7 @@ async function creatorRequest(operation, path, token, deps, init = {}) {
     catch (error) {
         throw new CreatorOperationError("creator_network_failed", operation, `The creator API request failed: ${error instanceof Error ? error.message : String(error)}.`, "Recovery: check your network and creator.apiUrl, then retry. No successful release is being claimed.");
     }
-    return readJsonResponse(response, operation);
+    return readCreatorResponse(response, operation);
 }
 async function inspectArtifact(path) {
     const artifactPath = resolve(path);
@@ -152,7 +137,7 @@ async function readManifest(path) {
 }
 function assertUploadUrl(value) {
     if (typeof value !== "string") {
-        throw new CreatorOperationError("creator_invalid_response", "publish", "The prepare response did not contain an uploadUrl.", "Recovery: retry once; if it repeats, report the Summercraft creator API as unhealthy.");
+        throw new CreatorOperationError("creator_invalid_response", "publish", "The prepare response did not contain an uploadUrl.", "Recovery: retry once; if it repeats, report the Summer Platform creator API as unhealthy.");
     }
     let url;
     try {
@@ -173,7 +158,7 @@ function assertUploadUrl(value) {
 }
 function assertUploadHeaders(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new CreatorOperationError("creator_invalid_response", "publish", "The prepare response did not contain signed upload headers.", "Recovery: retry once; if it repeats, report the Summercraft creator API as unhealthy.");
+        throw new CreatorOperationError("creator_invalid_response", "publish", "The prepare response did not contain signed upload headers.", "Recovery: retry once; if it repeats, report the Summer Platform creator API as unhealthy.");
     }
     const headers = Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
     if (headers["content-type"] !== "application/octet-stream" ||
@@ -212,7 +197,7 @@ export async function publishCreator(input, overrides = {}) {
         (await readSummerConfig()).creator?.channel ||
         "production";
     if (channel !== "production") {
-        throw new CreatorOperationError("creator_channel_unsupported", "publish", `The Summercraft creator API has no "${channel}" release channel.`, 'Recovery: use --channel production or run "summer config set creator.channel production". No release was created.');
+        throw new CreatorOperationError("creator_channel_unsupported", "publish", `The Summer Platform creator API has no "${channel}" release channel.`, 'Recovery: use --channel production or run "summer config set creator.channel production". No release was created.');
     }
     const version = input.version?.trim();
     if (!version || !VERSION.test(version)) {
@@ -387,7 +372,3 @@ export async function listCreatorReleases(input, overrides = {}) {
         nextCursor: payload.nextCursor,
     };
 }
-export async function readCreatorLogs(input) {
-    await resolveProjectId(input.projectId);
-    throw new CreatorOperationError("creator_backend_unavailable", "logs", "Summercraft does not have a durable creator runtime-log API.", LOGS_RECOVERY);
-}

package/dist/{lib → core/capabilities}/debug-report.d.ts

@@ -1,4 +1,4 @@
-import { type DoctorResult } from "../commands/doctor.js";
+import { type DoctorResult } from "./doctor.js";
 export interface DebugReportOptions {
     issue?: string;
     outputPath?: string;

package/dist/{lib → core/capabilities}/debug-report.js

@@ -1,17 +1,15 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
 import { hostname, platform, release } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { EngineApiClient } from "./api-client.js";
-import { shapeEngineLogResponse } from "./log-filters.js";
-import { tildeify } from "./format.js";
-import { getMcpLogPath, readRecentMcpLogLines } from "./mcp-log.js";
-import { runDoctor } from "../commands/doctor.js";
-const require = createRequire(import.meta.url);
-const { version } = require("../../package.json");
-function sleep(ms) {
-    return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
-}
+import { EngineApiClient } from "../api-client.js";
+import { shapeEngineLogResponse } from "../log-filters.js";
+import { tildeify } from "../format.js";
+import { getMcpLogPath, readRecentMcpLogLines } from "../mcp-log.js";
+import { redactLogLine, redactSensitive } from "../redact.js";
+import { runDoctor } from "./doctor.js";
+import { asRecord } from "../util/json.js";
+import { sleep } from "../util/sleep.js";
+import { TOOLKIT_VERSION as version } from "../version.js";
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -21,11 +19,6 @@ function timestampForFile(date) {
 export function defaultDebugReportFilename(date = new Date()) {
     return `summer-debug-report-${timestampForFile(date)}.md`;
 }
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : null;
-}
 function pickString(value, keys) {
     const record = asRecord(value);
     if (!record)
@@ -122,21 +115,9 @@ async function collectPlaySession(client, options) {
     }
     return session;
 }
+/** Debug reports also blank hostnames — a support artifact needs none. */
 function redact(value) {
-    if (Array.isArray(value))
-        return value.map((item) => redact(item));
-    if (!value || typeof value !== "object")
-        return value;
-    const out = {};
-    for (const [key, nested] of Object.entries(value)) {
-        if (/token|secret|password|authorization|cookie|api[-_]?key|hostname/i.test(key)) {
-            out[key] = "[REDACTED]";
-        }
-        else {
-            out[key] = redact(nested);
-        }
-    }
-    return out;
+    return redactSensitive(value, { extraKeys: /hostname/i, strings: true });
 }
 export function redactDebugReport(report) {
     return redact(report);
@@ -193,7 +174,7 @@ ${report.doctor ? jsonBlock(report.doctor) : "Doctor was skipped."}
 
 Log path: ${tildeify(report.mcp.logPath)}
 
-${report.mcp.recentLog.length > 0 ? `\`\`\`jsonl\n${report.mcp.recentLog.join("\n")}\n\`\`\`` : "No MCP lifecycle log entries found."}
+${report.mcp.recentLog.length > 0 ? `\`\`\`jsonl\n${report.mcp.recentLog.map(redactLogLine).join("\n")}\n\`\`\`` : "No MCP lifecycle log entries found."}
 
 ## Engine Health
 

package/dist/{commands → core/capabilities}/doctor.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import { type ProjectMemorySummary } from "../../project-memory/project-memory.js";
 export type DoctorStatus = "ok" | "warning" | "fail";
 export interface DoctorCheck {
     id: string;
@@ -20,7 +20,12 @@ interface DoctorOptions {
     json?: boolean;
     quiet?: boolean;
 }
-export declare const doctorCommand: Command;
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorResult>;
+export declare function checkLogin(): Promise<DoctorCheck>;
+export declare function checkEngineInstall(): DoctorCheck;
+/** The one-line Project Memory verdict: Markdown counts plus the template pin
+ *  (`.summer/project.json` is memory too — the first fact a fresh agent
+ *  needs). Exported for tests. */
+export declare function describeProjectMemory(summary: ProjectMemorySummary): string;
 export declare function printDoctorResult(result: DoctorResult): void;
 export {};

package/dist/{commands → core/capabilities}/doctor.js

@@ -1,50 +1,20 @@
 import { spawn } from "child_process";
-import { existsSync } from "fs";
-import { createRequire } from "node:module";
-import { platform } from "os";
-import { Command } from "commander";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { getAuthToken, getUserInfo } from "../lib/auth.js";
-import { isGitAvailable } from "../lib/cloud/checkpoint.js";
-import { checkEngineHealth, getApiPort, getApiToken } from "../lib/engine.js";
-import { brandLine, c, pad, sym, tildeify } from "../lib/format.js";
-import { getMcpLogPath } from "../lib/mcp-log.js";
-import { getProjectMemorySummary } from "../lib/project-memory.js";
-import { buildCliVersionCheck, buildSkillsVersionCheck, defaultSkillMarkerCandidates, fetchLatestRegistryVersion, } from "../lib/version-check.js";
-const require = createRequire(import.meta.url);
-const { version } = require("../../package.json");
+import { getAuthToken, getUserInfo } from "../auth.js";
+import { ENGINE_BIN_ENV, ENGINE_BINARY_ENV, findEngineBinary } from "../engine-install.js";
+import { checkEngineHealth, getApiPort, getApiToken } from "../engine.js";
+import { c, pad, sym, tildeify } from "../format.js";
+import { getMcpLogPath } from "../mcp-log.js";
+import { formatProjectPin, getProjectMemorySummary, } from "../../project-memory/project-memory.js";
+import { buildCliVersionCheck, buildSkillsVersionCheck, defaultSkillMarkerCandidates, detectRecordedInstall, fetchLatestRegistryVersion, } from "../../installer/version-check.js";
+import { TOOLKIT_VERSION as version } from "../version.js";
 const MIN_EXPECTED_MCP_TOOLS = 50;
 const REQUIRED_MCP_TOOLS = [
     "summer_get_project_context",
     "summer_generate_image",
     "summer_create_debug_report",
 ];
-const MAC_ENGINE_PATHS = [
-    "/Applications/Summer.app/Contents/MacOS/Summer",
-    `${process.env.HOME}/Applications/Summer.app/Contents/MacOS/Summer`,
-];
-const WIN_ENGINE_PATHS = [
-    `${process.env.LOCALAPPDATA}\\SummerEngine\\current\\Summer.exe`,
-    `${process.env.LOCALAPPDATA}\\Programs\\Summer Engine\\Summer.exe`,
-    `${process.env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
-];
-export const doctorCommand = new Command("doctor")
-    .description("Diagnose Node, login, engine, project memory, local API, and MCP registration")
-    .option("--json", "Print diagnostics as JSON")
-    .action(async (opts) => {
-    if (!opts.json) {
-        const { createRequire: req } = await import("node:module");
-        const ver = req(import.meta.url)("../../package.json").version;
-        console.log("");
-        console.log(brandLine(ver));
-        console.log("");
-    }
-    const result = await runDoctor({ json: Boolean(opts.json) });
-    if (!result.ok) {
-        process.exit(1);
-    }
-});
 export async function runDoctor(options = {}) {
     const checks = [];
     checks.push(checkNodeVersion());
@@ -55,10 +25,9 @@ export async function runDoctor(options = {}) {
         message: `v${version}`,
     });
     checks.push(await checkCliVersionCurrent());
-    checks.push(checkSkillsVersion());
+    checks.push(await checkSkillsVersion());
     checks.push(await checkLogin());
     checks.push(checkEngineInstall());
-    checks.push(await checkGitForCheckpoints());
     checks.push(await checkLocalApi());
     checks.push(await checkProjectMemory());
     checks.push(await checkMcpBoot());
@@ -105,10 +74,17 @@ async function checkCliVersionCurrent() {
         details: result.details,
     };
 }
-function checkSkillsVersion() {
-    const result = buildSkillsVersionCheck({
+/** Stale skills are a warning, never a failure (TESTING.md §d: only failures
+ *  exit 1). The recommended refresh follows how the agent's MCP entry was
+ *  recorded by `summer setup`: a `--local-dev` link gets the local-dev form
+ *  so the fix does not replace the checkout with the published package. */
+async function checkSkillsVersion() {
+    const registry = await fetchLatestRegistryVersion();
+    const result = await buildSkillsVersionCheck({
         installedCliVersion: version,
         candidates: defaultSkillMarkerCandidates(),
+        recordedInstall: detectRecordedInstall,
+        ...(registry.ok ? { latestRegistryVersion: registry.version } : {}),
     });
     return {
         id: "skills-version-stale",
@@ -118,7 +94,7 @@ function checkSkillsVersion() {
         details: result.details,
     };
 }
-async function checkLogin() {
+export async function checkLogin() {
     const token = await getAuthToken();
     const user = await getUserInfo();
     if (!token) {
@@ -126,7 +102,15 @@ async function checkLogin() {
             id: "login",
             label: "Login",
             status: "warning",
-            message: "not signed in (run: summer login)",
+            message: "not signed in (run: summer login — only gateway features need it; engine tools work without)",
+        };
+    }
+    if (process.env.SUMMER_TOKEN?.trim()) {
+        return {
+            id: "login",
+            label: "Login",
+            status: "ok",
+            message: "token from SUMMER_TOKEN env",
         };
     }
     return {
@@ -136,7 +120,7 @@ async function checkLogin() {
         message: user ? user.email : "signed in",
     };
 }
-function checkEngineInstall() {
+export function checkEngineInstall() {
     const binary = findEngineBinary();
     if (binary) {
         // Shorten /Applications/Summer.app/Contents/MacOS/Summer -> /Applications/Summer.app
@@ -153,24 +137,7 @@ function checkEngineInstall() {
         id: "engine-install",
         label: "Engine",
         status: "warning",
-        message: "not installed (run: summer install)",
-    };
-}
-async function checkGitForCheckpoints() {
-    const available = await isGitAvailable();
-    if (available) {
-        return {
-            id: "git",
-            label: "Git (cloud checkpoints)",
-            status: "ok",
-            message: "git found on PATH",
-        };
-    }
-    return {
-        id: "git",
-        label: "Git (cloud checkpoints)",
-        status: "warning",
-        message: "git not found; Summer Cloud sync needs git for pre-sync safety checkpoints",
+        message: `not installed (run: summer install, or set ${ENGINE_BIN_ENV} / ${ENGINE_BINARY_ENV} to an existing binary)`,
     };
 }
 async function checkLocalApi() {
@@ -237,15 +204,29 @@ async function checkProjectMemory() {
         id: "project-memory",
         label: "Project Memory",
         status: "ok",
-        message: `${summary.files.length} files, ${summary.structured.fileCount} memory, ${summary.structured.lockedCount} locked`,
+        message: describeProjectMemory(summary),
         details: {
             projectPath: health.project_path,
             files: summary.files.length,
             memoryFiles: summary.structured.fileCount,
             locked: summary.structured.lockedCount,
+            pin: summary.pin,
+            ...(summary.pinError ? { pinError: summary.pinError } : {}),
         },
     };
 }
+/** The one-line Project Memory verdict: Markdown counts plus the template pin
+ *  (`.summer/project.json` is memory too — the first fact a fresh agent
+ *  needs). Exported for tests. */
+export function describeProjectMemory(summary) {
+    const pin = formatProjectPin(summary.pin);
+    const pinPart = summary.pinError
+        ? `pin unreadable (${summary.pinError})`
+        : pin
+            ? `pin ${pin}`
+            : "no pin";
+    return `${summary.files.length} files, ${summary.structured.fileCount} memory, ${summary.structured.lockedCount} locked, ${pinPart}`;
+}
 async function checkMcpBoot() {
     const resolved = resolveCurrentMcpCommand();
     if (!resolved) {
@@ -429,7 +410,8 @@ function summarizeChecks(checks) {
 export function printDoctorResult(result) {
     console.log(c.bold("Doctor"));
     console.log("");
-    const labelWidth = 14;
+    // Widest label + 2 so long labels ("CLI up to date") keep their gap.
+    const labelWidth = result.checks.reduce((w, check) => Math.max(w, check.label.length), 0) + 2;
     for (const check of result.checks) {
         const mark = check.status === "ok"
             ? sym.ok()
@@ -449,14 +431,6 @@ export function printDoctorResult(result) {
         console.log(c.green("Everything's wired up."));
     }
 }
-function findEngineBinary() {
-    const paths = platform() === "darwin" ? MAC_ENGINE_PATHS : WIN_ENGINE_PATHS;
-    for (const path of paths) {
-        if (path && existsSync(path))
-            return path;
-    }
-    return null;
-}
 function trimOutput(output) {
     return {
         stdout: output.stdout.trim().slice(0, 500),

package/dist/core/capabilities/engine-fallbacks.d.ts

@@ -0,0 +1,26 @@
+/**
+ * engine-fallbacks — the `engine_lacks_op` fallback sentences, ONE copy for
+ * every face (src/mcp/tools/spatial-tools.ts, src/mcp/tools/perception-tools.ts,
+ * src/core/capabilities/tool-dispatch.ts). Each names what an agent should do
+ * on an engine build that lacks the op, whether the capability pre-flight
+ * refused before sending (missingEngineOpResult) or the engine answered
+ * "unknown op" (withOldEngineHint) — the sentence is identical either way.
+ *
+ * Rule (E2E 2026-09-03 F-16): a fallback names ONLY tools every shipped engine
+ * has — summer_get_scene_tree, summer_inspect_node, summer_inspect_resource,
+ * summer_set_prop, summer_screenshot, a RunVerification probe.
+ * summer_world_snapshot is itself engine_lacks_op on every shipped build, so a
+ * fallback that routes through it sends the agent from one dead end to the
+ * next. The scripting fallbacks live with their op builders in ./scene-script.ts.
+ */
+export declare const WORLD_SNAPSHOT_FALLBACK = "read structure with summer_get_scene_tree (pass depth) and verify visually with summer_screenshot";
+export declare const SNAPSHOT_DIFF_FALLBACK = "re-read with summer_get_scene_tree (pass depth) and summer_inspect_node and compare against your earlier read yourself";
+export declare const RUNTIME_TREE_FALLBACK = "probe runtime state with a RunVerification probe (dump_tree/report \u2014 see the playbook's rawOpsViaBatch)";
+export declare const RUNTIME_NODE_FALLBACK = "probe the node from a RunVerification probe (report(key, value) \u2014 see the playbook's rawOpsViaBatch)";
+export declare const TEST_PLACEMENT_FALLBACK = "list the subject and its neighbours with summer_get_scene_tree, read their positions and mesh/shape sizes with summer_inspect_node (summer_inspect_resource for mesh/shape extents), judge clearance from those, then verify with summer_screenshot";
+export declare const SNAP_TO_SURFACE_FALLBACK = "read the support's position and mesh/shape size with summer_inspect_node / summer_inspect_resource, set the subject's position with summer_set_prop so its bottom sits on the support's top, and verify with summer_screenshot";
+export declare const ALIGN_DISTRIBUTE_FALLBACK = "compute the shared anchor or spacing from the subjects' positions and sizes (summer_inspect_node / summer_inspect_resource) and set each subject's position with summer_set_prop (or one summer_run_editor_script)";
+export declare const NAVIGATION_PROBE_FALLBACK = "probe reachability from a RunVerification probe (NavigationServer3D.map_get_path \u2014 see the playbook's rawOpsViaBatch)";
+export declare const STARCAST_FALLBACK = "read the subject and its neighbours with summer_get_scene_tree + summer_inspect_node and judge support, contact, and clearance from their positions and sizes, then verify with summer_screenshot";
+/** Every fallback, for the parity test: none may mention summer_world_snapshot. */
+export declare const ENGINE_OP_FALLBACKS: Readonly<Record<string, string>>;

package/dist/core/capabilities/engine-fallbacks.js

@@ -0,0 +1,36 @@
+/**
+ * engine-fallbacks — the `engine_lacks_op` fallback sentences, ONE copy for
+ * every face (src/mcp/tools/spatial-tools.ts, src/mcp/tools/perception-tools.ts,
+ * src/core/capabilities/tool-dispatch.ts). Each names what an agent should do
+ * on an engine build that lacks the op, whether the capability pre-flight
+ * refused before sending (missingEngineOpResult) or the engine answered
+ * "unknown op" (withOldEngineHint) — the sentence is identical either way.
+ *
+ * Rule (E2E 2026-09-03 F-16): a fallback names ONLY tools every shipped engine
+ * has — summer_get_scene_tree, summer_inspect_node, summer_inspect_resource,
+ * summer_set_prop, summer_screenshot, a RunVerification probe.
+ * summer_world_snapshot is itself engine_lacks_op on every shipped build, so a
+ * fallback that routes through it sends the agent from one dead end to the
+ * next. The scripting fallbacks live with their op builders in ./scene-script.ts.
+ */
+export const WORLD_SNAPSHOT_FALLBACK = "read structure with summer_get_scene_tree (pass depth) and verify visually with summer_screenshot";
+export const SNAPSHOT_DIFF_FALLBACK = "re-read with summer_get_scene_tree (pass depth) and summer_inspect_node and compare against your earlier read yourself";
+export const RUNTIME_TREE_FALLBACK = "probe runtime state with a RunVerification probe (dump_tree/report — see the playbook's rawOpsViaBatch)";
+export const RUNTIME_NODE_FALLBACK = "probe the node from a RunVerification probe (report(key, value) — see the playbook's rawOpsViaBatch)";
+export const TEST_PLACEMENT_FALLBACK = "list the subject and its neighbours with summer_get_scene_tree, read their positions and mesh/shape sizes with summer_inspect_node (summer_inspect_resource for mesh/shape extents), judge clearance from those, then verify with summer_screenshot";
+export const SNAP_TO_SURFACE_FALLBACK = "read the support's position and mesh/shape size with summer_inspect_node / summer_inspect_resource, set the subject's position with summer_set_prop so its bottom sits on the support's top, and verify with summer_screenshot";
+export const ALIGN_DISTRIBUTE_FALLBACK = "compute the shared anchor or spacing from the subjects' positions and sizes (summer_inspect_node / summer_inspect_resource) and set each subject's position with summer_set_prop (or one summer_run_editor_script)";
+export const NAVIGATION_PROBE_FALLBACK = "probe reachability from a RunVerification probe (NavigationServer3D.map_get_path — see the playbook's rawOpsViaBatch)";
+export const STARCAST_FALLBACK = "read the subject and its neighbours with summer_get_scene_tree + summer_inspect_node and judge support, contact, and clearance from their positions and sizes, then verify with summer_screenshot";
+/** Every fallback, for the parity test: none may mention summer_world_snapshot. */
+export const ENGINE_OP_FALLBACKS = {
+    GetWorldSnapshot: WORLD_SNAPSHOT_FALLBACK,
+    DiffWorldSnapshot: SNAPSHOT_DIFF_FALLBACK,
+    GetRuntimeSceneTree: RUNTIME_TREE_FALLBACK,
+    GetRuntimeNode: RUNTIME_NODE_FALLBACK,
+    TestPlacement3D: TEST_PLACEMENT_FALLBACK,
+    SnapToSurface: SNAP_TO_SURFACE_FALLBACK,
+    AlignDistribute3D: ALIGN_DISTRIBUTE_FALLBACK,
+    NavigationProbe3D: NAVIGATION_PROBE_FALLBACK,
+    Starcast3D: STARCAST_FALLBACK,
+};

package/dist/core/capabilities/engine-ops.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Engine op helpers shared by both faces — the MCP tools (src/mcp/tools/*) and
+ * the CLI dispatch table (src/core/capabilities/tool-dispatch.ts). ONE copy of
+ * the scene-mutation single-op contract and of the guarded-file safety checks.
+ */
+import type { EngineApiClient } from "../api-client.js";
+import { type JsonRecord } from "../util/json.js";
+export declare function isSingleOnlyOp(kind: string, singleOnly: ReadonlySet<string>): boolean;
+/** Append the transaction-boundary SaveScene (or validate the caller's). */
+export declare function sceneMutationOps(ops: JsonRecord[]): JsonRecord[];
+/** Split an op list into sequential engine requests: consecutive batchable ops
+ *  stay grouped, each single-only op becomes its own request. Order preserved. */
+export declare function chunkOpsForDispatch(ops: JsonRecord[], singleOnly: ReadonlySet<string>): JsonRecord[][];
+/** Execute an op list as sequential engine requests honoring the single-op
+ *  dispatch contract. Receipts from every request are preserved and merged, so
+ *  an op that applied followed by one that failed is reported honestly instead
+ *  of masked. */
+export declare function executeOpsChunked(send: (chunk: JsonRecord[]) => Promise<unknown>, ops: JsonRecord[], singleOnly: ReadonlySet<string>): Promise<unknown>;
+/** Scene mutation entry point: appends the transaction-boundary SaveScene, then
+ *  dispatches with the single-op contract (mutations batch together, SaveScene
+ *  and other single-only ops travel alone). */
+export declare function executeSceneMutation(client: EngineApiClient, scenePath: string, ops: JsonRecord[], options?: JsonRecord): Promise<unknown>;
+/** Normalize a project path; refuses anything that is not a traversal-free res:// path. */
+export declare function safeProjectPath(path: string): string;
+export declare function validSha256(value: unknown): value is string;
+/** Validate a ReadFile receipt for a safe text mutation: text content, not
+ *  truncated, with a full-file sha256 the follow-up WriteFile can guard on. */
+export declare function readTextPayload(result: unknown): {
+    content: string;
+    sha256: string;
+    size?: number;
+};
+export declare function occurrenceCount(content: string, needle: string): number;

package/dist/core/capabilities/engine-ops.js

@@ -0,0 +1,145 @@
+import { resolveSingleOnlyOps } from "../capability-skew.js";
+import { ToolInputError } from "../tool-errors.js";
+import { asRecord } from "../util/json.js";
+import { extractOpError } from "./engine-receipt.js";
+// ---------------------------------------------------------------------------
+// Scene-mutation dispatch. The engine rejects multi-op batches containing
+// single-only ops wholesale, and every scene mutation batch ends in exactly one
+// SaveScene. Single-only classification comes from the engine's /api/health
+// advert when present, else core/capability-skew FALLBACK_SINGLE_ONLY_OPS.
+// ---------------------------------------------------------------------------
+export function isSingleOnlyOp(kind, singleOnly) {
+    return singleOnly.has(kind) || kind.startsWith("Git");
+}
+/** Append the transaction-boundary SaveScene (or validate the caller's). */
+export function sceneMutationOps(ops) {
+    const saveIndexes = ops
+        .map((op, index) => (op.op === "SaveScene" ? index : -1))
+        .filter((index) => index >= 0);
+    if (saveIndexes.length > 1) {
+        throw new ToolInputError("A scene mutation batch may contain only one SaveScene");
+    }
+    if (saveIndexes.length === 1) {
+        if (saveIndexes[0] !== ops.length - 1) {
+            throw new ToolInputError("SaveScene must be the final operation in a scene mutation batch");
+        }
+        return ops;
+    }
+    return [...ops, { op: "SaveScene" }];
+}
+/** Split an op list into sequential engine requests: consecutive batchable ops
+ *  stay grouped, each single-only op becomes its own request. Order preserved. */
+export function chunkOpsForDispatch(ops, singleOnly) {
+    const chunks = [];
+    let current = [];
+    for (const op of ops) {
+        if (isSingleOnlyOp(String(op.op ?? ""), singleOnly)) {
+            if (current.length > 0) {
+                chunks.push(current);
+                current = [];
+            }
+            chunks.push([op]);
+        }
+        else {
+            current.push(op);
+        }
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/** Execute an op list as sequential engine requests honoring the single-op
+ *  dispatch contract. Receipts from every request are preserved and merged, so
+ *  an op that applied followed by one that failed is reported honestly instead
+ *  of masked. */
+export async function executeOpsChunked(send, ops, singleOnly) {
+    const chunks = chunkOpsForDispatch(ops, singleOnly);
+    if (chunks.length === 1)
+        return send(chunks[0]);
+    const receipts = [];
+    const combinedResults = [];
+    for (let i = 0; i < chunks.length; i++) {
+        const receipt = await send(chunks[i]);
+        receipts.push(receipt);
+        const envelope = (receipt ?? {});
+        if (Array.isArray(envelope.results)) {
+            combinedResults.push(...envelope.results);
+        }
+        if (extractOpError(receipt)) {
+            const failedKind = String(chunks[i][0]?.op ?? "batch");
+            const appliedOps = chunks.slice(0, i).flat().map((op) => String(op.op ?? ""));
+            const notSent = chunks.slice(i + 1).flat().map((op) => String(op.op ?? ""));
+            const baseError = (typeof envelope.error === "string" && envelope.error) || `Engine request failed (${failedKind}).`;
+            const honestError = appliedOps.length > 0
+                ? `${baseError} NOTE: ${appliedOps.length} earlier op(s) already applied (${appliedOps.join(", ")})` +
+                    (failedKind === "SaveScene"
+                        ? " — the scene is modified in the editor but NOT saved to disk. Fix the problem, then call summer_save_scene."
+                        : ".") +
+                    (notSent.length > 0 ? ` Not sent: ${notSent.join(", ")}.` : "")
+                : baseError;
+            return {
+                ...envelope,
+                error: honestError,
+                results: combinedResults,
+                receipts,
+            };
+        }
+    }
+    const last = (receipts[receipts.length - 1] ?? {});
+    return { ...last, results: combinedResults, requests: chunks.length, receipts };
+}
+/** Scene mutation entry point: appends the transaction-boundary SaveScene, then
+ *  dispatches with the single-op contract (mutations batch together, SaveScene
+ *  and other single-only ops travel alone). */
+export function executeSceneMutation(client, scenePath, ops, options) {
+    return executeOpsChunked((chunk) => client.executeIdentityBoundOps(chunk, { ...(options ?? {}), scenePath }), sceneMutationOps(ops), resolveSingleOnlyOps(client));
+}
+// ---------------------------------------------------------------------------
+// Guarded file helpers: fail-closed writes, sha256 receipts.
+// ---------------------------------------------------------------------------
+/** Normalize a project path; refuses anything that is not a traversal-free res:// path. */
+export function safeProjectPath(path) {
+    const normalized = path.trim().replace(/\\/g, "/");
+    if (!normalized.startsWith("res://") || normalized.includes("..")) {
+        throw new ToolInputError("File path must be a traversal-free res:// project path.");
+    }
+    return normalized;
+}
+export function validSha256(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/i.test(value);
+}
+/** Validate a ReadFile receipt for a safe text mutation: text content, not
+ *  truncated, with a full-file sha256 the follow-up WriteFile can guard on. */
+export function readTextPayload(result) {
+    const root = asRecord(result);
+    const data = asRecord(root?.data);
+    if (root?.ok === false) {
+        throw new Error(String(root.error ?? "Engine could not read the file."));
+    }
+    if (data?.encoding === "binary" || typeof data?.content !== "string") {
+        throw new Error("Safe text mutation refused: the engine did not return text content.");
+    }
+    if (data.truncated === true) {
+        throw new Error("Safe text mutation refused: the file exceeds the 1 MB read limit.");
+    }
+    const sha256 = typeof data.sha256 === "string" ? data.sha256 : undefined;
+    if (!validSha256(sha256)) {
+        throw new Error("Safe text mutation refused: the engine did not return a full-file sha256 receipt.");
+    }
+    return {
+        content: data.content,
+        sha256,
+        size: typeof data.size === "number" ? data.size : undefined,
+    };
+}
+export function occurrenceCount(content, needle) {
+    let count = 0;
+    let offset = 0;
+    while (true) {
+        const index = content.indexOf(needle, offset);
+        if (index < 0)
+            return count;
+        count++;
+        offset = index + needle.length;
+    }
+}