@sapiom/harness 0.0.0 → 0.1.1

package/dist/core/canvas-enrich.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The AI enrichment runner: spawns ONE bounded, headless agent task per
+ * workflow (via TaskManager) that reads the workflow's step bodies and
+ * returns the JSON `CanvasEnrichment` contract — never HTML, never a file
+ * write. On success the validated enrichment is persisted to the workflow's
+ * cache file and the render file is rebuilt with it merged in; on any
+ * parse/validation failure the enrichment is discarded whole and the base
+ * render stands (core/canvas-enrichment.ts's contract). Task-process
+ * failures surface through the task record itself (the pane's error state +
+ * Retry), never as HTML on disk.
+ *
+ * Triggering (see server/index.ts):
+ * - bind / session create → `ensureFresh`: spawn only when no cache entry
+ *   matches the current source fingerprint; every skip reason is silent.
+ * - the visualize macro → `forceRefresh`: drop the extraction + enrichment
+ *   caches, re-render the base immediately, re-enrich; refusals propagate
+ *   (an already-running enrichment for this workflow → 409 via the macros
+ *   router, exactly like any other double-fired background macro).
+ *
+ * Dedupe is per WORKFLOW, not per session: TaskManager refuses a second
+ * running task with the same macroId + workflowPath regardless of which
+ * session asked (see TaskAlreadyRunningError) — two panes bound to the same
+ * workflow can never race its cache/render files.
+ */
+import type { BackgroundTask, HarnessKind } from "../shared/types.js";
+import { type CachedExtraction } from "./canvas-cache.js";
+import type { CanvasGraph } from "./canvas-graph.js";
+import { type RenderableWorkflow } from "./canvas-render.js";
+import type { RunTaskRequest } from "./task-manager.js";
+/** The macro identity enrichment tasks run under — the pane's Retry re-fires
+ *  this macro, which routes back through forceRefresh. */
+export declare const ENRICHMENT_MACRO_ID = "visualize";
+/** Model the enrichment task runs on — overridable per install. */
+export declare function enrichmentModel(env?: NodeJS.ProcessEnv): string;
+/**
+ * Builds the one-shot enrichment prompt: the extracted graph inline (the AI
+ * annotates THIS structure — it never invents nodes), pointed at the step
+ * sources for semantics, with the JSON contract and its hard limits stated
+ * verbatim so a well-behaved run needs no retry.
+ */
+export declare function buildEnrichmentPrompt(graph: CanvasGraph, workflowDir: string): string;
+/**
+ * Pulls the JSON object out of a task's final result text — either fenced
+ * (\`\`\`json ... \`\`\`) or raw, tolerating prose around it by falling back to
+ * the outermost {...} span. Null when nothing parses.
+ */
+export declare function extractEnrichmentJson(text: string): unknown | null;
+/** The slice of TaskManager the runner uses — injectable for tests. */
+export interface EnrichmentTaskRunner {
+    run(req: RunTaskRequest): Promise<BackgroundTask>;
+    onStatusChange(listener: (task: BackgroundTask) => void): () => void;
+}
+/** The session shape the coordinator needs — satisfied by HarnessSession. */
+export interface EnrichmentSession {
+    id: string;
+    cwd: string;
+    harness: HarnessKind;
+    boundWorkflowPath: string | null;
+}
+export interface EnrichmentCoordinatorOptions {
+    tasks: EnrichmentTaskRunner;
+    /** Rebuilds the workflow's render file (with the just-persisted enrichment
+     *  merged) after a successful run — the write alone hot-reloads any open
+     *  pane via the canvas watcher. */
+    rerender?: (cwd: string, workflow: RenderableWorkflow) => Promise<void>;
+    /** Injectable for tests — defaults to the real cached extraction. */
+    extractCached?: (dir: string) => Promise<CachedExtraction>;
+    env?: NodeJS.ProcessEnv;
+    now?: () => string;
+    onError?: (message: string) => void;
+}
+export declare class CanvasEnrichmentCoordinator {
+    private readonly tasks;
+    private readonly rerender;
+    private readonly extractCached;
+    private readonly env;
+    private readonly now;
+    private readonly onError;
+    constructor(options: EnrichmentCoordinatorOptions);
+    /**
+     * The bind/create trigger: spawn an enrichment task unless a cached
+     * enrichment already matches the workflow's current sources. Silent on
+     * every expected refusal — unbound session, failed extraction, fresh
+     * cache, an enrichment already in flight for this workflow, a harness
+     * with no headless mode, even a spawn failure (logged) — because nothing
+     * here was user-initiated and a bind must never fail on enrichment's
+     * account.
+     */
+    ensureFresh(session: EnrichmentSession, workflows: readonly RenderableWorkflow[]): Promise<void>;
+    /**
+     * The visualize macro: invalidate both caches, re-render the base diagram
+     * immediately (instant feedback, honest content — no leftover enrichment
+     * from sources that may have changed), then re-enrich. Refusals propagate
+     * to the macros router (TaskAlreadyRunningError → 409,
+     * TaskNotSupportedError → 400). Unbound session: just a no-op, matching
+     * the deterministic render's own unbound contract.
+     */
+    forceRefresh(session: EnrichmentSession, workflows: readonly RenderableWorkflow[]): Promise<void>;
+    private resolveBound;
+    private spawn;
+    /** Completed task → parse → validate → cache file → re-render. Any parse
+     *  or validation failure discards the enrichment whole; the base render
+     *  already on disk stands untouched. */
+    private persist;
+}
+//# sourceMappingURL=canvas-enrich.d.ts.map

package/dist/core/canvas-enrich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-enrich.d.ts","sourceRoot":"","sources":["../../src/core/canvas-enrich.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAyD,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACjH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AASrD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD;0DAC0D;AAC1D,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAO/C,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAuBrF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAgBlE;AAED,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAClD,cAAc,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACtE;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,WAAW,CAAC;IACrB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,oBAAoB,CAAC;IAC5B;;uCAEmC;IACnC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,qEAAqE;IACrE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED,qBAAa,2BAA2B;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+D;IACxF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6C;IAC3E,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,EAAE,4BAA4B;IASjD;;;;;;;;OAQG;IACG,WAAW,CAAC,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,SAAS,kBAAkB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAetG;;;;;;;OAOG;IACG,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,SAAS,kBAAkB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvG,OAAO,CAAC,YAAY;YAON,KAAK;IA+BnB;;4CAEwC;YAC1B,OAAO;CAqBtB"}

package/dist/core/canvas-enrich.js

@@ -0,0 +1,178 @@
+import { extractWorkflowGraphCached, invalidateExtractionCache } from "./canvas-cache.js";
+import { ENRICHMENT_LIMITS, normalizeCanvasEnrichmentCandidate, parseCanvasEnrichment, readEnrichmentCacheFile, removeEnrichmentCacheFile, writeEnrichmentCacheFile, } from "./canvas-enrichment.js";
+import { enrichmentCacheFileFor, renderWorkflowRenderFile, } from "./canvas-render.js";
+import { TaskAlreadyRunningError, TaskNotSupportedError } from "./task-manager.js";
+/** The macro identity enrichment tasks run under — the pane's Retry re-fires
+ *  this macro, which routes back through forceRefresh. */
+export const ENRICHMENT_MACRO_ID = "visualize";
+const ENRICHMENT_TASK_LABEL = "Visualize";
+/** Hard turn cap: read a few step files, answer. A run that needs more than
+ *  this is off the rails, not thorough. */
+const ENRICHMENT_MAX_TURNS = 8;
+const DEFAULT_ENRICHMENT_MODEL = "sonnet";
+/** Model the enrichment task runs on — overridable per install. */
+export function enrichmentModel(env = process.env) {
+    return env.SAPIOM_HARNESS_VISUALIZE_MODEL || DEFAULT_ENRICHMENT_MODEL;
+}
+/**
+ * Builds the one-shot enrichment prompt: the extracted graph inline (the AI
+ * annotates THIS structure — it never invents nodes), pointed at the step
+ * sources for semantics, with the JSON contract and its hard limits stated
+ * verbatim so a well-behaved run needs no retry.
+ */
+export function buildEnrichmentPrompt(graph, workflowDir) {
+    const L = ENRICHMENT_LIMITS;
+    return `You are annotating an already-rendered workflow diagram. The diagram's structure below is fixed — you only supply short text annotations, as one JSON object.
+
+Extracted workflow graph:
+${JSON.stringify(graph, null, 2)}
+
+Read the step run() bodies in ${workflowDir} to understand what each step actually does (what it calls, what it decides, why it branches), then RETURN ONLY a JSON object matching this schema — no prose before or after, no markdown required, and DO NOT write or modify any files:
+
+{
+  "summary": "what this workflow does, one line (max ${L.summary} chars)",
+  "nodeDetails": { "<nodeId>": { "sublabel": "short annotation shown in the node (max ${L.sublabel} chars)", "description": "one sentence, shown on hover (max ${L.description} chars)" } },
+  "edgeLabels": { "<fromNodeId>-><toNodeId>": "intent/condition name (max ${L.edgeLabel} chars)" },
+  "notes": ["up to ${L.noteCount} facts worth knowing, each max ${L.note} chars"],
+  "layoutHints": { "groups": [{ "label": "group name (max ${L.groupLabel} chars)", "nodeIds": ["..."] }], "laneOrder": { "<layerIndex>": ["nodeId", "..."] } },
+  "crossWorkflow": "how this workflow ties into the project's other workflows, if it does (max ${L.crossWorkflow} chars)"
+}
+
+Rules:
+- Every field is optional — omit what you have nothing useful for (omit, don't write null). Empty strings are worse than omissions.
+- Use ONLY node ids that appear in the graph above.
+- Length limits are hard caps and oversize strings get truncated mid-sentence — aim comfortably under each limit.
+- Your final message must be exactly the JSON object.`;
+}
+/**
+ * Pulls the JSON object out of a task's final result text — either fenced
+ * (\`\`\`json ... \`\`\`) or raw, tolerating prose around it by falling back to
+ * the outermost {...} span. Null when nothing parses.
+ */
+export function extractEnrichmentJson(text) {
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+    const candidates = [fenced?.[1], text];
+    const first = text.indexOf("{");
+    const last = text.lastIndexOf("}");
+    if (first !== -1 && last > first)
+        candidates.push(text.slice(first, last + 1));
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        try {
+            const parsed = JSON.parse(candidate.trim());
+            if (typeof parsed === "object" && parsed !== null)
+                return parsed;
+        }
+        catch {
+            // Try the next candidate shape.
+        }
+    }
+    return null;
+}
+export class CanvasEnrichmentCoordinator {
+    constructor(options) {
+        this.tasks = options.tasks;
+        this.rerender = options.rerender ?? (async (cwd, workflow) => void (await renderWorkflowRenderFile(cwd, workflow)));
+        this.extractCached = options.extractCached ?? extractWorkflowGraphCached;
+        this.env = options.env ?? process.env;
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.onError = options.onError ?? ((message) => console.error(`[harness] ${message}`));
+    }
+    /**
+     * The bind/create trigger: spawn an enrichment task unless a cached
+     * enrichment already matches the workflow's current sources. Silent on
+     * every expected refusal — unbound session, failed extraction, fresh
+     * cache, an enrichment already in flight for this workflow, a harness
+     * with no headless mode, even a spawn failure (logged) — because nothing
+     * here was user-initiated and a bind must never fail on enrichment's
+     * account.
+     */
+    async ensureFresh(session, workflows) {
+        const bound = this.resolveBound(session, workflows);
+        if (!bound)
+            return;
+        try {
+            const { result, fingerprint } = await this.extractCached(bound.path);
+            if (!result.ok)
+                return;
+            const entry = await readEnrichmentCacheFile(enrichmentCacheFileFor(session.cwd, bound.path));
+            if (entry && entry.sourceFingerprint === fingerprint)
+                return;
+            await this.spawn(session, bound, result.graph, fingerprint);
+        }
+        catch (err) {
+            if (err instanceof TaskAlreadyRunningError || err instanceof TaskNotSupportedError)
+                return;
+            this.onError(`canvas enrichment (auto) failed to start: ${err.message}`);
+        }
+    }
+    /**
+     * The visualize macro: invalidate both caches, re-render the base diagram
+     * immediately (instant feedback, honest content — no leftover enrichment
+     * from sources that may have changed), then re-enrich. Refusals propagate
+     * to the macros router (TaskAlreadyRunningError → 409,
+     * TaskNotSupportedError → 400). Unbound session: just a no-op, matching
+     * the deterministic render's own unbound contract.
+     */
+    async forceRefresh(session, workflows) {
+        const bound = this.resolveBound(session, workflows);
+        if (!bound)
+            return;
+        invalidateExtractionCache(bound.path);
+        await removeEnrichmentCacheFile(enrichmentCacheFileFor(session.cwd, bound.path));
+        await this.rerender(session.cwd, bound);
+        const { result, fingerprint } = await this.extractCached(bound.path);
+        if (!result.ok)
+            return;
+        await this.spawn(session, bound, result.graph, fingerprint);
+    }
+    resolveBound(session, workflows) {
+        return session.boundWorkflowPath ? workflows.find((w) => w.path === session.boundWorkflowPath) : undefined;
+    }
+    async spawn(session, workflow, graph, fingerprint) {
+        const task = await this.tasks.run({
+            macroId: ENRICHMENT_MACRO_ID,
+            label: ENRICHMENT_TASK_LABEL,
+            harnessSessionId: session.id,
+            harness: session.harness,
+            cwd: session.cwd,
+            prompt: buildEnrichmentPrompt(graph, workflow.path),
+            workflowPath: workflow.path,
+            model: enrichmentModel(this.env),
+            maxTurns: ENRICHMENT_MAX_TURNS,
+        });
+        // Subscribed synchronously right after run() resolves — the process's
+        // exit can only arrive via a later event-loop turn, so the terminal
+        // status can't be missed.
+        const unsubscribe = this.tasks.onStatusChange((update) => {
+            if (update.id !== task.id || update.status === "running")
+                return;
+            unsubscribe();
+            if (update.status !== "completed")
+                return; // pane shows the failure; nothing to persist
+            void this.persist(session.cwd, workflow, graph, fingerprint, update.resultText).catch((err) => {
+                this.onError(`canvas enrichment persist failed: ${err.message}`);
+            });
+        });
+    }
+    /** Completed task → parse → validate → cache file → re-render. Any parse
+     *  or validation failure discards the enrichment whole; the base render
+     *  already on disk stands untouched. */
+    async persist(cwd, workflow, graph, fingerprint, resultText) {
+        const candidate = resultText ? extractEnrichmentJson(resultText) : null;
+        const enrichment = candidate ? parseCanvasEnrichment(normalizeCanvasEnrichmentCandidate(candidate)) : null;
+        if (!enrichment) {
+            this.onError(`canvas enrichment for ${workflow.path} returned invalid output — discarded, base render stands`);
+            return;
+        }
+        await writeEnrichmentCacheFile(enrichmentCacheFileFor(cwd, workflow.path), {
+            graph,
+            enrichment,
+            sourceFingerprint: fingerprint,
+            enrichedAt: this.now(),
+        });
+        await this.rerender(cwd, workflow);
+    }
+}
+//# sourceMappingURL=canvas-enrich.js.map

package/dist/core/canvas-enrich.js.map

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

package/dist/core/canvas-enrichment.d.ts

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import type { CanvasGraph } from "./canvas-graph.js";
+export declare const ENRICHMENT_LIMITS: {
+    readonly summary: 160;
+    readonly sublabel: 48;
+    readonly description: 120;
+    readonly edgeLabel: 32;
+    readonly noteCount: 3;
+    readonly note: 140;
+    readonly groupLabel: 48;
+    readonly crossWorkflow: 160;
+};
+export declare const canvasEnrichmentSchema: z.ZodObject<{
+    /** One-liner under the panel header. */
+    summary: z.ZodOptional<z.ZodString>;
+    /** Per-node annotations, keyed by node id. */
+    nodeDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Second text line inside the node box. */
+        sublabel: z.ZodOptional<z.ZodString>;
+        /** Hover tooltip (SVG <title>) — room for a full sentence. */
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        sublabel?: string | undefined;
+    }, {
+        description?: string | undefined;
+        sublabel?: string | undefined;
+    }>>>;
+    /** Edge annotations (intent/condition names), keyed `"<from>-><to>"`. */
+    edgeLabels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Footer facts worth knowing that don't fit the diagram itself. */
+    notes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    layoutHints: z.ZodOptional<z.ZodObject<{
+        /** Named clusters rendered as background bands behind member nodes. */
+        groups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            nodeIds: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            label: string;
+            nodeIds: string[];
+        }, {
+            label: string;
+            nodeIds: string[];
+        }>, "many">>;
+        /** Preferred left-to-right node order per layout layer, keyed by the
+         *  layer index as a string. Reorders WITHIN the computed layer only —
+         *  it can never move a node between layers. */
+        laneOrder: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        groups?: {
+            label: string;
+            nodeIds: string[];
+        }[] | undefined;
+        laneOrder?: Record<string, string[]> | undefined;
+    }, {
+        groups?: {
+            label: string;
+            nodeIds: string[];
+        }[] | undefined;
+        laneOrder?: Record<string, string[]> | undefined;
+    }>>;
+    /** How this workflow ties into the workspace's other workflows. */
+    crossWorkflow: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    summary?: string | undefined;
+    nodeDetails?: Record<string, {
+        description?: string | undefined;
+        sublabel?: string | undefined;
+    }> | undefined;
+    edgeLabels?: Record<string, string> | undefined;
+    notes?: string[] | undefined;
+    layoutHints?: {
+        groups?: {
+            label: string;
+            nodeIds: string[];
+        }[] | undefined;
+        laneOrder?: Record<string, string[]> | undefined;
+    } | undefined;
+    crossWorkflow?: string | undefined;
+}, {
+    summary?: string | undefined;
+    nodeDetails?: Record<string, {
+        description?: string | undefined;
+        sublabel?: string | undefined;
+    }> | undefined;
+    edgeLabels?: Record<string, string> | undefined;
+    notes?: string[] | undefined;
+    layoutHints?: {
+        groups?: {
+            label: string;
+            nodeIds: string[];
+        }[] | undefined;
+        laneOrder?: Record<string, string[]> | undefined;
+    } | undefined;
+    crossWorkflow?: string | undefined;
+}>;
+export type CanvasEnrichment = z.infer<typeof canvasEnrichmentSchema>;
+export type CanvasLayoutHints = NonNullable<CanvasEnrichment["layoutHints"]>;
+/**
+ * Validates a candidate enrichment object. Returns null on ANY schema
+ * violation (oversize string, wrong shape, too many notes) — partial
+ * salvage is deliberately not attempted, so the contract stays a hard line
+ * the prompt can state truthfully: "invalid output is thrown away whole."
+ */
+export declare function parseCanvasEnrichment(value: unknown): CanvasEnrichment | null;
+/**
+ * Deterministic repair of the two ways an otherwise-good answer most often
+ * misses the contract, applied BEFORE strict validation:
+ * - `null` where the schema means "omit the field"
+ * - strings a few words over their cap (measured live: sonnet writes
+ *   excellent content but doesn't count characters — a single 160-char note
+ *   against the 140 cap discarded 3 of 4 real enrichments whole), truncated
+ *   to the cap with an ellipsis; extra notes beyond the count cap dropped
+ *
+ * The bound the caps exist for — the AI can never blow up the layout with
+ * unbounded text — is still enforced, just deterministically here instead
+ * of by rejection. Everything else (wrong shapes, wrong types, unknown
+ * structure) still fails `parseCanvasEnrichment` and discards the
+ * enrichment whole.
+ */
+export declare function normalizeCanvasEnrichmentCandidate(value: unknown): unknown;
+/**
+ * What one cache file holds. `sourceFingerprint` is canvas-cache.ts's cheap
+ * source fingerprint at the moment the enrichment task was SPAWNED — when it
+ * no longer matches the workflow's current sources, the base diagram
+ * re-renders immediately from fresh extraction while this enrichment stays
+ * displayed with a "stale" chip until a re-run replaces it.
+ */
+export interface EnrichmentCacheEntry {
+    /** The graph the enrichment was generated against (diagnostic context —
+     *  renders always use the freshly extracted graph, never this copy). */
+    graph: CanvasGraph;
+    enrichment: CanvasEnrichment;
+    sourceFingerprint: string;
+    enrichedAt: string;
+}
+/** Reads + validates one enrichment cache file. Null for missing, unparsable
+ *  or schema-invalid content — a bad cache degrades to "no enrichment". */
+export declare function readEnrichmentCacheFile(filePath: string): Promise<EnrichmentCacheEntry | null>;
+export declare function writeEnrichmentCacheFile(filePath: string, entry: EnrichmentCacheEntry): Promise<void>;
+/** Deletes one enrichment cache file (the visualize macro's force refresh).
+ *  Missing file is fine — the goal state is "no cache". */
+export declare function removeEnrichmentCacheFile(filePath: string): Promise<void>;
+//# sourceMappingURL=canvas-enrichment.d.ts.map

package/dist/core/canvas-enrichment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-enrichment.d.ts","sourceRoot":"","sources":["../../src/core/canvas-enrichment.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,eAAO,MAAM,iBAAiB;;;;;;;;;CASpB,CAAC;AAIX,eAAO,MAAM,sBAAsB;IAE/B,wCAAwC;;IAExC,8CAA8C;;QAKtC,4CAA4C;;QAE5C,8DAA8D;;;;;;;;;IAMtE,yEAAyE;;IAEzE,oEAAoE;;;QAIhE,uEAAuE;;;;;;;;;;;QAWvE;;uDAE+C;;;;;;;;;;;;;;;IAKnD,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG7D,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC,CAAC;AAE7E;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAG7E;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA6C1E;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;4EACwE;IACxE,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAmBD;2EAC2E;AAC3E,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAepG;AAED,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3G;AAED;2DAC2D;AAC3D,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/E"}

package/dist/core/canvas-enrichment.js

@@ -0,0 +1,192 @@
+/**
+ * The AI enrichment contract: everything the enrichment task is allowed to
+ * add to a deterministic canvas render, as a zod schema. The AI never writes
+ * HTML — it returns one JSON object of BOUNDED plain strings (every limit
+ * below is a hard cap, not advice) and the renderer decides where they go.
+ * Unknown keys are stripped; any parse failure means the whole enrichment is
+ * discarded and the base render stands — a malformed answer can degrade
+ * nothing but itself.
+ *
+ * Layout hints are the one structural concession: named groups (rendered as
+ * subtle background bands) and per-layer ordering. The renderer applies a
+ * hint only when every node id it references actually exists in the graph
+ * (see canvas-svg.ts) — ids are validated at render time, not here, because
+ * an enrichment can outlive the graph it was written against (the "stale"
+ * cache state).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { z } from "zod";
+export const ENRICHMENT_LIMITS = {
+    summary: 160,
+    sublabel: 48,
+    description: 120,
+    edgeLabel: 32,
+    noteCount: 3,
+    note: 140,
+    groupLabel: 48,
+    crossWorkflow: 160,
+};
+const bounded = (max) => z.string().max(max);
+export const canvasEnrichmentSchema = z
+    .object({
+    /** One-liner under the panel header. */
+    summary: bounded(ENRICHMENT_LIMITS.summary).optional(),
+    /** Per-node annotations, keyed by node id. */
+    nodeDetails: z
+        .record(z
+        .object({
+        /** Second text line inside the node box. */
+        sublabel: bounded(ENRICHMENT_LIMITS.sublabel).optional(),
+        /** Hover tooltip (SVG <title>) — room for a full sentence. */
+        description: bounded(ENRICHMENT_LIMITS.description).optional(),
+    })
+        .strip())
+        .optional(),
+    /** Edge annotations (intent/condition names), keyed `"<from>-><to>"`. */
+    edgeLabels: z.record(bounded(ENRICHMENT_LIMITS.edgeLabel)).optional(),
+    /** Footer facts worth knowing that don't fit the diagram itself. */
+    notes: z.array(bounded(ENRICHMENT_LIMITS.note)).max(ENRICHMENT_LIMITS.noteCount).optional(),
+    layoutHints: z
+        .object({
+        /** Named clusters rendered as background bands behind member nodes. */
+        groups: z
+            .array(z
+            .object({
+            label: bounded(ENRICHMENT_LIMITS.groupLabel),
+            nodeIds: z.array(z.string()).min(1),
+        })
+            .strip())
+            .optional(),
+        /** Preferred left-to-right node order per layout layer, keyed by the
+         *  layer index as a string. Reorders WITHIN the computed layer only —
+         *  it can never move a node between layers. */
+        laneOrder: z.record(z.array(z.string()).min(1)).optional(),
+    })
+        .strip()
+        .optional(),
+    /** How this workflow ties into the workspace's other workflows. */
+    crossWorkflow: bounded(ENRICHMENT_LIMITS.crossWorkflow).optional(),
+})
+    .strip();
+/**
+ * Validates a candidate enrichment object. Returns null on ANY schema
+ * violation (oversize string, wrong shape, too many notes) — partial
+ * salvage is deliberately not attempted, so the contract stays a hard line
+ * the prompt can state truthfully: "invalid output is thrown away whole."
+ */
+export function parseCanvasEnrichment(value) {
+    const parsed = canvasEnrichmentSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+function clampString(value, max) {
+    if (typeof value !== "string" || value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Removes null/undefined-valued properties (models write `"field": null`
+ *  to mean "omitted"; the schema means it as `undefined`). Shallow — called
+ *  per level below where object shapes are known. */
+function dropNulls(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, v]) => v != null));
+}
+/**
+ * Deterministic repair of the two ways an otherwise-good answer most often
+ * misses the contract, applied BEFORE strict validation:
+ * - `null` where the schema means "omit the field"
+ * - strings a few words over their cap (measured live: sonnet writes
+ *   excellent content but doesn't count characters — a single 160-char note
+ *   against the 140 cap discarded 3 of 4 real enrichments whole), truncated
+ *   to the cap with an ellipsis; extra notes beyond the count cap dropped
+ *
+ * The bound the caps exist for — the AI can never blow up the layout with
+ * unbounded text — is still enforced, just deterministically here instead
+ * of by rejection. Everything else (wrong shapes, wrong types, unknown
+ * structure) still fails `parseCanvasEnrichment` and discards the
+ * enrichment whole.
+ */
+export function normalizeCanvasEnrichmentCandidate(value) {
+    if (!isRecord(value))
+        return value;
+    const L = ENRICHMENT_LIMITS;
+    const out = { ...value };
+    out.summary = clampString(out.summary, L.summary);
+    out.crossWorkflow = clampString(out.crossWorkflow, L.crossWorkflow);
+    if (isRecord(out.nodeDetails)) {
+        out.nodeDetails = Object.fromEntries(Object.entries(out.nodeDetails).map(([id, details]) => {
+            if (!isRecord(details))
+                return [id, details];
+            return [
+                id,
+                dropNulls({
+                    ...details,
+                    sublabel: clampString(details.sublabel, L.sublabel),
+                    description: clampString(details.description, L.description),
+                }),
+            ];
+        }));
+    }
+    if (isRecord(out.edgeLabels)) {
+        out.edgeLabels = Object.fromEntries(Object.entries(out.edgeLabels).map(([key, label]) => [key, clampString(label, L.edgeLabel)]));
+    }
+    if (Array.isArray(out.notes)) {
+        out.notes = out.notes.slice(0, L.noteCount).map((note) => clampString(note, L.note));
+    }
+    if (isRecord(out.layoutHints)) {
+        const hints = dropNulls({ ...out.layoutHints });
+        if (Array.isArray(hints.groups)) {
+            hints.groups = hints.groups.map((group) => isRecord(group) ? dropNulls({ ...group, label: clampString(group.label, L.groupLabel) }) : group);
+        }
+        out.layoutHints = hints;
+    }
+    return dropNulls(out);
+}
+/** Envelope validation is deliberately shallow for `graph` (it's our own
+ *  writer's serialization, not AI output) and strict for `enrichment` (it IS
+ *  AI output — re-validated on every read, so a hand-edited or corrupted
+ *  cache file can never smuggle unbounded strings into a render). */
+const cacheEntrySchema = z.object({
+    graph: z.object({
+        manifestName: z.string(),
+        entry: z.string(),
+        nodes: z.array(z.record(z.unknown())),
+        edges: z.array(z.record(z.unknown())),
+        warnings: z.array(z.string()),
+    }),
+    enrichment: canvasEnrichmentSchema,
+    sourceFingerprint: z.string(),
+    enrichedAt: z.string(),
+});
+/** Reads + validates one enrichment cache file. Null for missing, unparsable
+ *  or schema-invalid content — a bad cache degrades to "no enrichment". */
+export async function readEnrichmentCacheFile(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = cacheEntrySchema.safeParse(JSON.parse(raw));
+        // The shallow node/edge validation above means this cast, not a full
+        // structural proof — see the schema's own comment for why that's enough.
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeEnrichmentCacheFile(filePath, entry) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(entry, null, 2), "utf8");
+}
+/** Deletes one enrichment cache file (the visualize macro's force refresh).
+ *  Missing file is fine — the goal state is "no cache". */
+export async function removeEnrichmentCacheFile(filePath) {
+    await fs.rm(filePath, { force: true });
+}
+//# sourceMappingURL=canvas-enrichment.js.map

package/dist/core/canvas-enrichment.js.map

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