@nodetool-ai/execution 0.8.1

package/dist/session.js

@@ -0,0 +1,353 @@
+/**
+ * `ExecutionSession` — the one place that constructs `WorkflowRunner`.
+ *
+ * See the package README for the wiring-inventory table this facade is
+ * derived from (Track A / task A1 of docs/RELIABILITY_TASKS.md) and
+ * docs/RELIABILITY_ARCHITECTURE.md §7 for the target API shape.
+ */
+import { randomUUID } from "node:crypto";
+import { createLogger } from "@nodetool-ai/config";
+import { hydrateGraphNodeFlags } from "@nodetool-ai/node-sdk";
+import { Graph, WorkflowRunner, withExplicitNodeFlags } from "@nodetool-ai/kernel";
+import { PERMISSION_GATE_CONTEXT_KEY, connectPythonBridgeForGraph, headlessGate } from "@nodetool-ai/runtime";
+import { createExecutorResolver } from "./executor-resolver.js";
+import { WORKFLOW_RUN_HOST, buildWorkspaceExecutionContext } from "./service/workflow-workspace.js";
+import { normalizeGraph } from "./normalize-graph.js";
+import { assertPreflight } from "./preflight.js";
+import { rewriteOutputNames } from "./output-names.js";
+import { MessageStream } from "./message-stream.js";
+import { attachRunCostLedger, nodeTypeLookup } from "./cost-ledger.js";
+const log = createLogger("nodetool.execution.session");
+export class ExecutionSession {
+    jobId;
+    workflowId;
+    graph;
+    runner;
+    /** Null unless the caller opted into `captureMessages` (see options). */
+    stream;
+    persistence;
+    bridge;
+    resultPromise;
+    runTimeoutHandle = null;
+    _cancelReason = null;
+    constructor(init) {
+        this.jobId = init.jobId;
+        this.workflowId = init.workflowId;
+        this.graph = init.graph;
+        this.runner = init.runner;
+        this.persistence = init.persistence;
+        this.bridge = init.bridge;
+        this.stream = init.captureMessages
+            ? new MessageStream(init.context, init.messageBufferLimit)
+            : null;
+        // Every generation this run pays for lands in the ledger `nodetool costs`
+        // reads. Attached here, at the one seam all surfaces share, so image and
+        // video spend is recorded whether the run came from the CLI, the debug
+        // harness, an app, or the websocket server.
+        // No `projectId`/`documentId`: a session is constructed from a graph and a
+        // job id, and no host passes project attribution down to it. The rows carry
+        // a null rather than being attributed to the loose bucket.
+        const detachLedger = init.recordCosts
+            ? attachRunCostLedger(init.context, {
+                userId: init.userId,
+                workflowId: init.workflowId,
+                projectId: init.projectId ?? null,
+                documentId: init.documentId ?? null,
+                nodeType: nodeTypeLookup(init.graph.nodes),
+                resolveSecret: (key) => init.context.getSecret(key)
+            })
+            : null;
+        if (init.runTimeoutMs && init.runTimeoutMs > 0) {
+            this.runTimeoutHandle = setTimeout(() => {
+                this.cancel("timeout");
+            }, init.runTimeoutMs);
+        }
+        // Open the run boundary on the Python worker before the kernel starts, so
+        // an execute frame can never arrive ahead of the job it belongs to. Fire
+        // and forget: `jobStart` is a no-op on a pre-v4 worker and swallows its own
+        // failures, and blocking the kernel on worker bookkeeping would make an
+        // unreachable worker a run failure.
+        const boundary = {
+            jobId: init.jobId,
+            workflowId: init.workflowId,
+            userId: init.userId
+        };
+        void init.lifecycle?.jobStart(boundary);
+        const runRequest = {
+            job_id: init.jobId,
+            workflow_id: init.workflowId ?? undefined,
+            params: init.params
+        };
+        if (init.triggerEvent) {
+            runRequest.trigger_event = init.triggerEvent;
+        }
+        this.resultPromise = init.runner
+            .run(runRequest, init.graph)
+            .then((result) => {
+            void init.lifecycle?.jobEnd({
+                ...boundary,
+                reason: this.endReason(result.status)
+            });
+            return result;
+        }, (err) => {
+            // `run()` documents that it never rejects, but the boundary must
+            // close even if that ever stops being true — an abandoned run is
+            // exactly the leak `job.end` exists to prevent.
+            void init.lifecycle?.jobEnd({ ...boundary, reason: "abandoned" });
+            throw err;
+        })
+            .finally(async () => {
+            if (this.runTimeoutHandle) {
+                clearTimeout(this.runTimeoutHandle);
+                this.runTimeoutHandle = null;
+            }
+            init.closeBridge();
+            // The terminal message was emitted synchronously before run()
+            // resolved (ProcessingContext.emit() calls listeners inline), so the
+            // stream can close now without dropping it. The same holds for the
+            // ledger: every prediction/node_update it prices was already delivered.
+            detachLedger?.();
+            this.stream?.close();
+            try {
+                await init.context.workspace?.cleanupScratch?.();
+            }
+            catch (err) {
+                log.warn("Workspace scratch cleanup failed", {
+                    jobId: this.jobId,
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
+        });
+        this.resultPromise
+            .then((result) => this.persistence?.onTerminal?.(result))
+            .catch((err) => {
+            log.warn("persistence.onTerminal threw", {
+                jobId: this.jobId,
+                error: err instanceof Error ? err.message : String(err)
+            });
+        });
+    }
+    /** Map a kernel run status onto the `job.end` reason. */
+    endReason(status) {
+        if (status === "failed")
+            return "failed";
+        if (status === "cancelled")
+            return "cancelled";
+        return "completed";
+    }
+    static async create(options) {
+        if (options.limits?.nodeTimeoutMs) {
+            throw new Error("ExecutionSession: nodeTimeoutMs is not yet supported — the kernel " +
+                "has no per-node timeout hook (only run-level cancel()). Omit it " +
+                "or use limits.runTimeoutMs.");
+        }
+        if (!options.registry && !options.resolveExecutor) {
+            throw new Error("ExecutionSession: either registry or resolveExecutor must be provided " +
+                "(registry builds the default registry+bridge resolver; resolveExecutor " +
+                "bypasses it for a host with its own resolution, e.g. the WS runner).");
+        }
+        const jobId = options.jobId ?? randomUUID();
+        const workflowId = options.workflowId ?? null;
+        const registry = options.registry;
+        const normalized = normalizeGraph(options.graph);
+        // A caller that brings no context still gets one that can reach the
+        // secret store. The bare `new ProcessingContext(...)` this replaced
+        // resolved no secret at all, so a graph with a provider node failed on
+        // credentials the install had — the same defect the service-layer run
+        // path shipped with. Selected here, ahead of the bridge, because the
+        // preflight below resolves credentials through it.
+        const context = options.context ??
+            buildWorkspaceExecutionContext({
+                jobId,
+                workflowId,
+                userId: "1",
+                workspace: null,
+                durableFalGenerations: true
+            });
+        // This facade is the workflow host for every caller that builds its own
+        // context (`nodetool run`, the WebSocket job runner, the app simulator):
+        // a run is consent, so a context that arrived with no gate gets the
+        // headless one here. A caller that already has a user to ask — a chat
+        // turn's `run_node` — set its gate before handing the context in, and
+        // keeps it.
+        if (context.get(PERMISSION_GATE_CONTEXT_KEY) === undefined) {
+            context.set(PERMISSION_GATE_CONTEXT_KEY, headlessGate(WORKFLOW_RUN_HOST));
+        }
+        // Refuse a graph this runtime cannot honour before anything is paid for:
+        // ahead of the Python bridge (a worker spawn), ahead of
+        // `persistence.onAccepted` (a job row), and ahead of the kernel. Without
+        // this, a bad model id or a missing key failed at the node that needed it
+        // — after the upstream half of the graph had already run and billed.
+        // A context serving providers from its own resolver (a fake, a cassette,
+        // the e2e server's scripted provider) never reaches the registry and never
+        // reads a credential, so the registry's "is this key set" question does not
+        // apply to it — asking anyway refuses the run for a secret it would not
+        // have used. An explicit checker still wins: a host that knows its own
+        // registry says so itself.
+        const providerConfiguration = options.providerConfiguration ??
+            (context.hasProviderResolver ? () => [] : undefined);
+        await assertPreflight(normalized, {
+            catalogs: options.catalogs,
+            providerConfiguration,
+            resolveSecret: (key) => context.getSecret(key)
+        });
+        // A caller injecting its own `resolveExecutor` (see the option doc)
+        // typically also owns its own Python bridge — never connect a second one
+        // behind its back. `bridgeFactory` remains available for that caller to
+        // opt back in explicitly (e.g. handing this facade an already-connected
+        // bridge instance to close on its behalf).
+        const bridgeFactory = options.bridgeFactory ??
+            (options.resolveExecutor
+                ? async () => null
+                : connectPythonBridgeForGraph);
+        const bridge = await bridgeFactory(normalized.nodes, (t) => registry ? registry.has(t) : false);
+        let bridgeClosed = false;
+        const closeBridge = () => {
+            if (bridgeClosed)
+                return;
+            bridgeClosed = true;
+            bridge?.close();
+        };
+        let hydrated;
+        try {
+            if (options.resolveNodeType) {
+                // Richer path: resolves `propertyTypes`/`outputs` from registry
+                // metadata too (async — the resolver may lazy-load a namespace),
+                // matching `websocket-client-session.ts`'s `Graph.loadFromDict`
+                // hydration. Without this, multi-edge fan-in into a non-list
+                // property is misclassified as list aggregation (the kernel only
+                // gates on a populated `propertyTypes` map).
+                const loaded = await Graph.loadFromDict(normalized, {
+                    resolver: options.resolveNodeType
+                });
+                hydrated = { nodes: [...loaded.nodes], edges: [...loaded.edges] };
+            }
+            else if (registry) {
+                hydrated = hydrateGraphNodeFlags(normalized, registry);
+            }
+            else {
+                // No registry and no resolveNodeType: the caller hydrates its own
+                // graph before handing it to this facade (see the `registry` option
+                // doc) — default absent flags to `false` rather than guessing.
+                // `...node` on every field `withExplicitNodeFlags` doesn't touch
+                // means an already-resolved `propertyTypes`/`outputs` passes through
+                // unchanged.
+                hydrated = withExplicitNodeFlags(normalized);
+            }
+        }
+        catch (err) {
+            closeBridge();
+            throw err;
+        }
+        if (options.requireTerminalResult) {
+            rewriteOutputNames(hydrated);
+        }
+        const resolveExecutor = options.resolveExecutor ?? createExecutorResolver(registry, bridge);
+        const runnerOptions = {
+            resolveExecutor,
+            executionContext: context,
+            validateNode: options.validateNode,
+            bufferLimit: options.limits?.bufferLimit ?? null,
+            strict: options.strict
+        };
+        if (options.supervisor) {
+            runnerOptions.supervisor = options.supervisor;
+        }
+        const runner = new WorkflowRunner(jobId, runnerOptions);
+        try {
+            await options.persistence?.onAccepted?.(jobId);
+        }
+        catch (err) {
+            log.warn("persistence.onAccepted threw", {
+                jobId,
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+        return new ExecutionSession({
+            jobId,
+            workflowId,
+            graph: hydrated,
+            runner,
+            context,
+            persistence: options.persistence ?? null,
+            params: options.params ?? {},
+            triggerEvent: options.triggerEvent ?? null,
+            bridge,
+            lifecycle: options.jobLifecycleBridge ?? bridge,
+            userId: context.userId,
+            closeBridge,
+            runTimeoutMs: options.limits?.runTimeoutMs,
+            captureMessages: options.captureMessages === true,
+            messageBufferLimit: options.limits?.messageBufferLimit,
+            recordCosts: options.recordCosts !== false,
+            projectId: options.projectId,
+            documentId: options.documentId
+        });
+    }
+    /**
+     * Live message stream — closes once the run reaches a terminal state.
+     * Requires `captureMessages: true` at `create()`; without it nothing is
+     * queued (see that option) and reading this throws rather than handing back
+     * a stream that would silently yield nothing.
+     */
+    get messages() {
+        if (!this.stream) {
+            throw new Error("ExecutionSession: `messages` requires `captureMessages: true` at " +
+                "create() — message capture is opt-in so a host that only awaits " +
+                "`result` never queues a run's messages unread.");
+        }
+        return this.stream;
+    }
+    /** The run's terminal result. Never rejects — kernel failures resolve as `status: "failed"`. */
+    get result() {
+        return this.resultPromise;
+    }
+    /**
+     * Live resource counts, for leak accounting: after a terminal result every
+     * one of these must be back to zero. Measured, not inferred — the
+     * reliability harness's `cleanup-leaks` invariant asserts against these
+     * numbers and reports a violation when a driver can't produce them.
+     */
+    resourceCounters() {
+        return {
+            liveActors: this.runner.liveActorCount,
+            pendingControlResponses: this.runner.pendingControlResponseCount,
+            // The session's own run-timeout timer is the only timer it owns; it is
+            // cleared when the run settles.
+            pendingTimers: this.runTimeoutHandle === null ? 0 : 1,
+            pythonBridgePendingRequests: this.bridge?.pendingRequestCount ?? 0
+        };
+    }
+    /** The reason passed to the most recent `cancel()` call, if any. */
+    get cancelReason() {
+        return this._cancelReason;
+    }
+    /** Stream one more value into a live input node (mirrors the WS `stream_input` command). */
+    pushInput(inputName, value, sourceHandle) {
+        return this.runner.pushInputValue(inputName, value, sourceHandle);
+    }
+    /** Signal end-of-stream for a live input node (mirrors `end_input_stream`). */
+    finishInputStream(inputName, sourceHandle) {
+        this.runner.finishInputStream(inputName, sourceHandle);
+    }
+    /**
+     * Push property updates into a running node's executor instance (live
+     * parameter changes, e.g. a synth knob while a patch plays — mirrors the
+     * WS runner's `update_node_properties` command). Returns `true` when the
+     * node's executor exists and supports live updates; `false` is not an
+     * error — the caller's own state already holds the new value for the next
+     * run.
+     */
+    updateNodeProperties(nodeId, properties) {
+        return this.runner.updateNodeProperties(nodeId, properties);
+    }
+    /**
+     * The only cancel path. `runTimeoutMs` is implemented as
+     * `cancel("timeout")` — there is no separate timeout code path.
+     */
+    cancel(reason) {
+        this._cancelReason = reason ?? this._cancelReason ?? "cancelled";
+        this.runner.cancel();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/sketch-debug/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@nodetool-ai/execution/sketch-debug` — sketch validation + debug report.
+ *
+ * Pure, dependency-injected core: no DB, no canvas, no browser. Hosts (the CLI
+ * `sketch` command today) resolve the target and write the bundle.
+ */
+export type { SketchDebugIssue, SketchValidation, SketchInteractionRecord, SketchDebugTarget, SketchDocumentMeta, SketchDebugReport } from "./types.js";
+export { validateSketchDocument, type SketchValidationMeta } from "./validate.js";
+export { buildSketchDebugReport, type SketchDebugReportInput } from "./report.js";
+export { renderSketchReportMarkdown } from "./markdown.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sketch-debug/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sketch-debug/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EACL,sBAAsB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC"}

package/dist/sketch-debug/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@nodetool-ai/execution/sketch-debug` — sketch validation + debug report.
+ *
+ * Pure, dependency-injected core: no DB, no canvas, no browser. Hosts (the CLI
+ * `sketch` command today) resolve the target and write the bundle.
+ */
+export { validateSketchDocument } from "./validate.js";
+export { buildSketchDebugReport } from "./report.js";
+export { renderSketchReportMarkdown } from "./markdown.js";
+//# sourceMappingURL=index.js.map

package/dist/sketch-debug/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sketch-debug/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,EAAE,sBAAsB,EAA6B,MAAM,eAAe,CAAC;AAClF,OAAO,EACL,sBAAsB,EAEvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC"}

package/dist/sketch-debug/markdown.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Renders a `SketchDebugReport` as human-readable Markdown for the bundle.
+ */
+import type { SketchDebugReport } from "./types.js";
+export declare function renderSketchReportMarkdown(report: SketchDebugReport): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/sketch-debug/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/sketch-debug/markdown.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA+EtE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAyD5E"}

package/dist/sketch-debug/markdown.js

@@ -0,0 +1,93 @@
+import { isObjectLike, isString } from "../predicates.js";
+const short = (value, max = 120) => {
+    if (value === undefined)
+        return "—";
+    let s;
+    try {
+        s = isString(value) ? value : JSON.stringify(value);
+    }
+    catch {
+        s = String(value);
+    }
+    s = (s ?? "null").replace(/\s+/g, " ");
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+};
+const where = (issue) => {
+    const parts = [
+        issue.layerId ? `layer \`${issue.layerId}\`` : null,
+        issue.path ? `\`${issue.path}\`` : null
+    ].filter((part) => part !== null);
+    return parts.length > 0 ? parts.join(" · ") : "—";
+};
+function issueTable(title, issues, lines) {
+    if (issues.length === 0)
+        return;
+    lines.push("", `## ${title}`, "");
+    lines.push("| Severity | Code | Where | Message |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const issue of issues) {
+        lines.push(`| ${issue.severity} | \`${issue.code}\` | ${where(issue)} | ${short(issue.message, 300)} |`);
+    }
+}
+const asRecord = (value) => isObjectLike(value) ? value : null;
+/**
+ * The snapshot carries the whole layer stack; the markdown wants one line per
+ * layer, top of the stack first, rather than a JSON dump.
+ */
+function finalStateLines(state) {
+    const record = asRecord(state);
+    const layers = Array.isArray(record?.layers)
+        ? record.layers
+        : null;
+    if (!layers)
+        return [`- ${short(state, 600)}`];
+    const lines = [];
+    const canvas = `${String(record?.width ?? "?")}×${String(record?.height ?? "?")}`;
+    lines.push(`- canvas ${canvas}, active layer \`${String(record?.activeLayerId ?? "none")}\``);
+    for (const layer of [...layers].reverse()) {
+        lines.push(`- \`${layer.id ?? "?"}\`${layer.name ? ` "${layer.name}"` : ""} ` +
+            `${layer.type ?? "?"} · opacity ${layer.opacity ?? 1} · ${layer.blendMode ?? "normal"}` +
+            `${layer.visible === false ? " · hidden" : ""}${layer.hasBinding ? " · bound" : ""}`);
+    }
+    return lines;
+}
+export function renderSketchReportMarkdown(report) {
+    const lines = [];
+    const title = report.target.name ?? report.target.ref;
+    lines.push(`# Sketch debug: ${title}`);
+    lines.push("");
+    lines.push(`${report.verdict.ok ? "✅" : "❌"} ${report.verdict.headline}`);
+    lines.push("");
+    lines.push(`Target: \`${report.target.ref}\` (${report.target.kind})`);
+    lines.push(`Document: ${report.meta.width}×${report.meta.height} on ${report.meta.backgroundColor} · ` +
+        `${report.meta.layerCount} layer(s), ${report.meta.bindingCount} binding(s)`);
+    if (report.verdict.issues.length > 0) {
+        lines.push("", "## Issues", "");
+        for (const issue of report.verdict.issues)
+            lines.push(`- ${issue}`);
+    }
+    issueTable("Validation", [...report.validation.errors, ...report.validation.warnings], lines);
+    if (report.interactions.length > 0) {
+        lines.push("", "## Interactions", "");
+        lines.push("| Tool | OK | Input | Error |");
+        lines.push("| --- | --- | --- | --- |");
+        for (const step of report.interactions) {
+            lines.push(`| \`${step.tool}\` | ${step.ok ? "✅" : "❌"} | ${short(step.input)} | ${step.error ? short(step.error, 200) : "—"} |`);
+        }
+    }
+    if (report.finalValidation) {
+        issueTable("Validation after edits", [...report.finalValidation.errors, ...report.finalValidation.warnings], lines);
+    }
+    if (report.finalState !== undefined) {
+        lines.push("", "## Final state", "");
+        lines.push(...finalStateLines(report.finalState));
+    }
+    if (report.notSimulated.length > 0) {
+        lines.push("", "## Not simulated", "");
+        for (const entry of report.notSimulated)
+            lines.push(`- ${entry}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=markdown.js.map

package/dist/sketch-debug/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/sketch-debug/markdown.ts"],"names":[],"mappings":"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"}

package/dist/sketch-debug/report.d.ts

@@ -0,0 +1,15 @@
+import type { SketchDebugReport, SketchDebugTarget, SketchInteractionRecord } from "./types.js";
+import { type SketchValidationMeta } from "./validate.js";
+export interface SketchDebugReportInput {
+    target: SketchDebugTarget;
+    /** The document as loaded — untrusted, validated here. */
+    document: unknown;
+    meta?: SketchValidationMeta;
+    interactions?: SketchInteractionRecord[];
+    /** Bridge snapshot after the scripted session (`SketchBridgeFinalState`). */
+    finalState?: unknown;
+    /** Document reconstructed from the final state, validated as a second pass. */
+    finalDocument?: unknown;
+}
+export declare function buildSketchDebugReport(input: SketchDebugReportInput): SketchDebugReport;
+//# sourceMappingURL=report.d.ts.map

package/dist/sketch-debug/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/sketch-debug/report.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAEV,iBAAiB,EACjB,iBAAiB,EAEjB,uBAAuB,EAExB,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AAyGvB,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,YAAY,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACzC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,sBAAsB,GAC5B,iBAAiB,CAiCnB"}

package/dist/sketch-debug/report.js

@@ -0,0 +1,98 @@
+import { validateSketchDocument } from "./validate.js";
+import { isPositiveFiniteNumber, isString } from "../predicates.js";
+const DEFAULTS = {
+    width: 1024,
+    height: 1024,
+    backgroundColor: "#ffffff"
+};
+/**
+ * What a headless sketch run cannot answer. Fixed, because the boundary is a
+ * property of the harness, not of the document it was pointed at.
+ */
+const NOT_SIMULATED = [
+    "Pixels — layer bitmaps are never decoded, composited, or diffed.",
+    "Rendering and flattening — no canvas exists, so blend modes and effects produce nothing to look at.",
+    "Painting tools — brush, eraser, fill, gradient and transform strokes leave no marks headlessly.",
+    "Generation providers — no imagery is produced; bindings are checked structurally only.",
+    "Asset I/O — asset ids are never resolved, fetched, or uploaded.",
+    "Generation bindings after edits — the headless bridge tracks a layer's prompt/provider/model but not the persisted binding record, so a post-edit document is validated with no bindings."
+];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const count = (value) => Array.isArray(value) ? value.length : 0;
+function describeDocument(document, meta) {
+    const record = isRecord(document) ? document : {};
+    const sketch = isRecord(record.sketch) ? record.sketch : {};
+    const canvas = isRecord(sketch.canvas) ? sketch.canvas : {};
+    const pick = (value, fallback) => isPositiveFiniteNumber(value) ? value : fallback;
+    const background = isString(canvas.backgroundColor)
+        ? canvas.backgroundColor
+        : (meta?.backgroundColor ?? DEFAULTS.backgroundColor);
+    return {
+        width: pick(canvas.width, pick(meta?.width, DEFAULTS.width)),
+        height: pick(canvas.height, pick(meta?.height, DEFAULTS.height)),
+        backgroundColor: background,
+        layerCount: count(sketch.layers),
+        bindingCount: count(record.layerBindings)
+    };
+}
+const describe = (issue) => {
+    const where = issue.layerId ?? issue.path;
+    return where
+        ? `[${issue.code}] ${where}: ${issue.message}`
+        : `[${issue.code}] ${issue.message}`;
+};
+function buildSketchVerdict(validation, interactions, finalValidation) {
+    const failedSteps = interactions.filter((step) => !step.ok);
+    const issues = [
+        ...validation.errors.map(describe),
+        ...failedSteps.map((step) => `Interaction \`${step.tool}\` failed${step.error ? `: ${step.error}` : ""}`),
+        ...(finalValidation?.errors ?? []).map((issue) => `After edits — ${describe(issue)}`)
+    ];
+    const warnings = [
+        ...validation.warnings.map(describe),
+        ...(finalValidation?.warnings ?? []).map((issue) => `After edits — ${describe(issue)}`)
+    ];
+    const ok = issues.length === 0;
+    const warningCount = warnings.length;
+    const headline = ok
+        ? `Sketch is sound — ${interactions.length} interaction(s) ran clean` +
+            (warningCount > 0 ? `, ${warningCount} warning(s)` : "") +
+            "."
+        : `Sketch has ${issues.length} problem(s)` +
+            (failedSteps.length > 0
+                ? `, ${failedSteps.length} failed interaction(s)`
+                : "") +
+            (warningCount > 0 ? `, ${warningCount} warning(s)` : "") +
+            ` — ${issues[0]}`;
+    return warningCount > 0
+        ? { ok, headline, issues, warnings }
+        : { ok, headline, issues };
+}
+export function buildSketchDebugReport(input) {
+    const validation = validateSketchDocument(input.document, input.meta);
+    // The post-edit pass runs without `meta`: a session may have resized the
+    // canvas, and the stored row's size is then the stale number, not the bug.
+    const finalValidation = input.finalDocument === undefined
+        ? undefined
+        : validateSketchDocument(input.finalDocument);
+    const interactions = input.interactions ?? [];
+    // The final document is what the session left behind, so it — not the input
+    // — describes the sketch the report is about.
+    const meta = describeDocument(input.finalDocument ?? input.document, input.meta);
+    const report = {
+        target: input.target,
+        meta,
+        validation,
+        interactions,
+        notSimulated: [...NOT_SIMULATED],
+        verdict: buildSketchVerdict(validation, interactions, finalValidation)
+    };
+    if (input.finalState !== undefined) {
+        report.finalState = input.finalState;
+    }
+    if (finalValidation) {
+        report.finalValidation = finalValidation;
+    }
+    return report;
+}
+//# sourceMappingURL=report.js.map

package/dist/sketch-debug/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/sketch-debug/report.ts"],"names":[],"mappings":"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"}