@wrenai/genbi 0.0.4 → 0.0.6

package/dist-server/harness/components/runner.js

@@ -0,0 +1,492 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { normalizeComponentRequest } from "@warble/claude-agent-sdk";
+import { readSlots, wholeChildDisclosure } from "./egress.js";
+import { parseTerminalJson } from "./terminal-json.js";
+import { reportedUsage } from "./usage.js";
+/** A grant that executes SQL: its successful results carry a host-assigned `query_id`. */
+export function isQueryGrant(grant) {
+    return grant.source === "host:sql_execution:read_only" || (grant.source === "native" && grant.name === "query");
+}
+export const COMPONENT_LIMITS = Object.freeze({
+    depth: 8, calls: 32, steps: 40, childSteps: 12,
+    requestBytes: 65_536, resultBytes: 1_048_576, timeoutMs: 120_000,
+});
+const normalizedResult = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("ok"), output: z.discriminatedUnion("kind", [
+            z.object({ kind: z.literal("value"), value: z.unknown() }).strict(),
+            z.object({ kind: z.literal("render"), blocks: z.array(z.record(z.string(), z.unknown())), summary: z.string().optional() }).strict(),
+        ]), provenance: z.object({ verified: z.boolean().optional(), definition: z.unknown().optional() }).strict().optional() }).strict(),
+    z.object({ status: z.literal("refused"), code: z.literal("callee_refused"), message: z.string() }).strict(),
+    z.object({ status: z.literal("error"), code: z.enum(["unsupported_callee", "invalid_request", "invalid_result", "budget_exhausted", "cancelled", "transient_transport", "callee_failed"]), message: z.string(), retryable: z.boolean() }).strict(),
+]);
+class ExecutionFailure extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+function safeError(error) {
+    return { status: "error", code: error instanceof ExecutionFailure ? error.code : "callee_failed",
+        message: "Component execution did not complete.", retryable: false };
+}
+function copy(value, maxBytes) {
+    const text = JSON.stringify(value);
+    if (text === undefined || Buffer.byteLength(text) > maxBytes)
+        throw new ExecutionFailure("invalid_result");
+    return JSON.parse(text);
+}
+function freeze(value) {
+    if (value && typeof value === "object") {
+        for (const item of Object.values(value))
+            freeze(item);
+        Object.freeze(value);
+    }
+    return value;
+}
+function object() { return Object.create(null); }
+/** Per-slot semantics come from a well-formed slot declaration only; a malformed one keeps the strict rule. */
+function isPerSlotRequest(request) {
+    const read = readSlots(request);
+    return !("error" in read) && !read.implicit;
+}
+/**
+ * A per-slot child whose terminal never parsed, after its repair step or with none declared:
+ * every declared slot is unanswerable, so the caller renders unavailable cells instead of
+ * receiving no envelope. Nothing is grounded, so there is nothing for normalization to verify.
+ */
+function unanswerableBatch(request) {
+    const read = readSlots(request);
+    if ("error" in read)
+        throw new ExecutionFailure("callee_failed");
+    return { status: "ok", output: { kind: "value", value: read.slots.map((slot) => ({ slot_id: slot.slot_id, status: "unanswerable", reason: "terminal_unparseable" })) } };
+}
+function unique(values) {
+    return values.every((value) => /^[A-Za-z0-9_-]+$/.test(value) && !["__proto__", "constructor", "prototype"].includes(value))
+        && new Set(values).size === values.length;
+}
+/** Immutable, root-scoped execution. Constructed only from a validated producer adapter. */
+export class ComponentRunner {
+    host;
+    plan;
+    controller = new AbortController();
+    bindings = new Map();
+    releases = new WeakMap();
+    used = false;
+    cleanupFailure = false;
+    get cleanupFailed() { return this.cleanupFailure; }
+    calls = 0;
+    steps = 0;
+    usage = { inputTokens: 0, outputTokens: 0 };
+    deadline = 0;
+    constructor(plan, host) {
+        this.host = host;
+        this.plan = freeze(copy(plan, 4 * 1024 * 1024));
+        this.validate();
+    }
+    cancel() { this.controller.abort(); }
+    get observedUsage() { return { ...this.usage }; }
+    async run(entry, request, signal) {
+        if (this.used)
+            throw new Error("Component runner is single-use");
+        this.used = true;
+        const abort = () => this.cancel();
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            this.cancel();
+        this.deadline = Date.now() + COMPONENT_LIMITS.timeoutMs;
+        const timer = setTimeout(abort, COMPONENT_LIMITS.timeoutMs);
+        let result;
+        try {
+            if (!this.plan.entries.includes(entry))
+                throw new ExecutionFailure("callee_failed");
+            // Prepare the entire reachable closure before any model or tool execution.
+            const closure = new Set();
+            const visit = (id) => {
+                if (closure.has(id))
+                    return;
+                closure.add(id);
+                for (const step of this.plan.components[id].steps)
+                    for (const edge of step.calls)
+                        visit(edge.component);
+            };
+            visit(entry);
+            for (const id of closure) {
+                this.check();
+                const pending = this.host.prepare(this.plan.components[id], this.controller.signal);
+                // A late prepare owns resources too: close it if cancellation won the race.
+                void pending.then(async (binding) => {
+                    if (this.controller.signal.aborted)
+                        await this.release(binding);
+                }).catch(() => { });
+                const binding = await this.wait(pending);
+                this.bindings.set(id, binding);
+                this.check();
+                const tools = binding.tools;
+                if (!unique(tools.map((tool) => tool.name)))
+                    throw new ExecutionFailure("callee_failed");
+                for (const step of this.plan.components[id].steps)
+                    for (const tool of step.tools) {
+                        if (!tools.some((bound) => bound.name === tool.name && bound.source === tool.source)) {
+                            throw new ExecutionFailure("callee_failed");
+                        }
+                    }
+            }
+            result = await this.invoke(entry, request, null, 0);
+            this.check();
+        }
+        catch (error) {
+            result = safeError(error);
+        }
+        if (result.status !== "ok")
+            this.cancel();
+        try {
+            // Persistence depends on successful required resource cleanup. Identity
+            // checks remain valid after resources close; no more step work is admitted.
+            const cleanup = await Promise.allSettled([...this.bindings.values()].map((binding) => this.release(binding)));
+            if (cleanup.some((item) => item.status === "rejected"))
+                return safeError(new ExecutionFailure("callee_failed"));
+            if (result.status === "ok") {
+                this.check();
+                if (this.host.persistRoot)
+                    await this.wait(this.host.persistRoot(result, this.bindings.get(entry), this.controller.signal));
+            }
+            return result;
+        }
+        catch (error) {
+            return safeError(error);
+        }
+        finally {
+            this.cancel();
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    /** Runs the host's egress seam, or passes the result through when the host installed none. */
+    async verifyChild(context, raw) {
+        if (!this.host.verifyChild)
+            return { disclosed: raw, decisions: [], provenance: [] };
+        if ("error" in context.request)
+            throw new ExecutionFailure("callee_failed");
+        const verified = await this.wait(this.host.verifyChild({ ...context, request: context.request.value }, raw, this.controller.signal));
+        // Narrowing only: a seam that returns success for a child that did not succeed is a host bug, never a disclosure.
+        // The one exception is the all-unavailable answer for a per-slot child that failed or was refused as a whole,
+        // matched exactly and with the category of what happened to the raw result: never one category for the other.
+        const admitted = raw.status === "error" && raw.code === "callee_failed" ? wholeChildDisclosure(context.request.value, "callee_error")
+            : raw.status === "refused" ? wholeChildDisclosure(context.request.value, "callee_refused") : undefined;
+        if (verified.disclosed.status === "ok" && raw.status !== "ok" && !(admitted !== undefined && isDeepStrictEqual(verified.disclosed, admitted))) {
+            throw new ExecutionFailure("callee_failed");
+        }
+        return verified;
+    }
+    release(binding) {
+        let pending = this.releases.get(binding);
+        if (!pending) {
+            pending = Promise.resolve().then(() => binding.close()).catch(() => { this.cleanupFailure = true; throw new Error("Component cleanup failed"); });
+            this.releases.set(binding, pending);
+        }
+        return pending;
+    }
+    check() {
+        if (this.controller.signal.aborted || Date.now() >= this.deadline)
+            throw new ExecutionFailure("cancelled");
+        if ([...this.bindings.values()].some((binding) => !binding.isCurrent())) {
+            this.cancel();
+            throw new ExecutionFailure("cancelled");
+        }
+    }
+    async wait(pending) {
+        this.check();
+        let stop;
+        const cancelled = new Promise((_, reject) => {
+            stop = () => reject(new ExecutionFailure("cancelled"));
+            this.controller.signal.addEventListener("abort", stop, { once: true });
+        });
+        try {
+            const result = await Promise.race([pending, cancelled]);
+            this.check();
+            return result;
+        }
+        finally {
+            this.controller.signal.removeEventListener("abort", stop);
+        }
+    }
+    /**
+     * A per-slot child behind an egress seam that throws `callee_failed` (an unrepaired step) reaches
+     * the seam as a `callee_failed` result instead of failing the caller, so the seam can answer every
+     * slot unavailable. A grandchild's seam-narrowing violation thrown as `callee_failed` inside the
+     * child lands here too and renders all-unavailable (fails closed). Cancellation, budget, invalid
+     * results and any other error keep propagating, as does every failure of a child without slots
+     * or without a seam. A refused child is returned as is; the seam discloses it with its own category.
+     */
+    async invokeChild(id, raw, parent, depth, perSlotBehindSeam) {
+        if (!perSlotBehindSeam)
+            return this.invoke(id, raw, parent, depth);
+        try {
+            return await this.invoke(id, raw, parent, depth);
+        }
+        catch (error) {
+            if (error instanceof ExecutionFailure && error.code === "callee_failed")
+                return safeError(error);
+            throw error;
+        }
+    }
+    async invoke(id, raw, parent, depth) {
+        this.check();
+        const request = normalizeComponentRequest(raw, COMPONENT_LIMITS.requestBytes);
+        if ("error" in request)
+            return request.error;
+        if (depth > COMPONENT_LIMITS.depth || (depth > 0 && ++this.calls > COMPONENT_LIMITS.calls)) {
+            throw new ExecutionFailure("budget_exhausted");
+        }
+        const component = this.plan.components[id];
+        const binding = this.bindings.get(id);
+        const perSlot = isPerSlotRequest(request.value);
+        const invocation = randomUUID();
+        const event = { invocation, parent, component: id, depth };
+        this.host.onEvent?.({ ...event, kind: "call.start" });
+        const products = object();
+        const tools = [];
+        const children = [];
+        const egress = [];
+        let childSteps = 0;
+        let failed;
+        // Ordinal of successful query results in this invocation, across its steps: `q1`, `q2`, ...
+        let executedQueries = 0;
+        // The last terminal step's text did not parse and no repair step remains to run for it.
+        let unparseable = false;
+        const lastPrimary = component.steps.indexOf(component.steps.filter((candidate) => !candidate.repairOf).at(-1));
+        try {
+            for (const step of component.steps) {
+                if (step.repairOf && step.repairOf !== failed)
+                    continue;
+                if (!step.repairOf && failed)
+                    throw new ExecutionFailure("callee_failed");
+                this.check();
+                if (++this.steps > COMPONENT_LIMITS.steps || (depth > 0 && ++childSteps > COMPONENT_LIMITS.childSteps)) {
+                    throw new ExecutionFailure("budget_exhausted");
+                }
+                const consumes = object();
+                for (const name of step.consumes) {
+                    if (!Object.hasOwn(products, name))
+                        throw new ExecutionFailure("callee_failed");
+                    consumes[name] = products[name];
+                }
+                let active = true;
+                let accepting = true;
+                let toolErrored = false;
+                // Each invocation has its own queue: siblings serialize, nested children do not deadlock.
+                let queue = Promise.resolve();
+                const queued = [];
+                const scoped = object();
+                const schemas = object();
+                const descriptions = object();
+                const assertActive = () => {
+                    this.check();
+                    if (!active)
+                        throw new ExecutionFailure("cancelled");
+                };
+                const trackTool = async (tool, execute, callId = randomUUID()) => {
+                    const toolEvent = { ...event, step: step.name, tool, callId };
+                    this.host.onEvent?.({ ...toolEvent, kind: "tool.start" });
+                    try {
+                        const value = await execute();
+                        this.host.onEvent?.({ ...toolEvent, kind: "tool.finish", status: "ok" });
+                        return value;
+                    }
+                    catch (error) {
+                        this.host.onEvent?.({ ...toolEvent, kind: "tool.finish", status: this.controller.signal.aborted ? "cancelled" : "error" });
+                        throw error;
+                    }
+                };
+                for (const grant of step.tools) {
+                    const tool = binding.tools.find((candidate) => candidate.name === grant.name && candidate.source === grant.source);
+                    if (tool.inputSchema)
+                        schemas[grant.name] = freeze(copy(tool.inputSchema, COMPONENT_LIMITS.requestBytes));
+                    scoped[grant.name] = (input) => {
+                        const pending = (async () => {
+                            assertActive();
+                            if (!accepting)
+                                throw new ExecutionFailure("cancelled");
+                            const saved = freeze(copy(input, COMPONENT_LIMITS.requestBytes));
+                            const result = await trackTool(grant.name, () => this.wait(tool.execute(saved, this.controller.signal)));
+                            assertActive();
+                            // The id is assigned here, once, so the evidence and the model's copy carry the same
+                            // one; a tool's own `query_id` field is overwritten. The terminal cites it instead of
+                            // re-typing SQL, and normalization resolves it against this evidence. The size guard
+                            // runs once, on the result as recorded, before anything is recorded.
+                            const output = copy(isQueryGrant(grant) && result !== null && typeof result === "object" && !Array.isArray(result)
+                                ? { ...result, query_id: `q${++executedQueries}` } : result, COMPONENT_LIMITS.resultBytes);
+                            tools.push(freeze({ step: step.name, tool: grant.name, input: saved, output: structuredClone(output) }));
+                            return output;
+                        })();
+                        // The model sees the rejection as a tool error and may recover within the step. For
+                        // the host, a failed tool call fails the *step* (so a declared repair step can run and
+                        // an unrepaired failure is still callee_failed), not the whole invocation; a per-slot
+                        // request treats it as one slot's outcome instead. Cancellation, budget and result
+                        // limits keep propagating.
+                        const tracked = pending.catch((error) => { if (error instanceof ExecutionFailure)
+                            throw error; toolErrored = true; });
+                        queued.push(tracked);
+                        void tracked.catch(() => { });
+                        return pending;
+                    };
+                }
+                for (const edge of step.calls) {
+                    schemas[edge.alias] = { type: "object", additionalProperties: false, required: ["request"], properties: {
+                            request: { type: "string", minLength: 1 }, input: { type: "object", additionalProperties: true },
+                        } };
+                    descriptions[edge.alias] = String(this.plan.components[edge.component].declaration.description ?? "Invoke the bound component with a fresh request.");
+                    scoped[edge.alias] = (input) => {
+                        // Reject replay before placing anything in the invocation queue.
+                        try {
+                            assertActive();
+                            if (!accepting)
+                                throw new ExecutionFailure("cancelled");
+                        }
+                        catch (error) {
+                            return Promise.reject(error);
+                        }
+                        const savedInput = copy(input, COMPONENT_LIMITS.requestBytes);
+                        const callId = randomUUID();
+                        const pending = queue.then(() => trackTool(edge.alias, async () => {
+                            assertActive();
+                            const childRequest = normalizeComponentRequest(savedInput, COMPONENT_LIMITS.requestBytes);
+                            const raw = await this.invokeChild(edge.component, savedInput, invocation, depth + 1, Boolean(this.host.verifyChild) && !("error" in childRequest) && isPerSlotRequest(childRequest.value));
+                            assertActive();
+                            // The egress seam: the caller only ever receives `disclosed`. The raw
+                            // child result exists on this stack frame and nowhere else.
+                            const verified = await this.verifyChild({ caller: id, step: step.name, alias: edge.alias, callee: edge.component, depth: depth + 1,
+                                request: childRequest }, raw);
+                            assertActive();
+                            for (const decision of verified.decisions) {
+                                this.host.onEvent?.({ ...event, kind: "egress", step: step.name, tool: edge.alias, callId, slot: decision.slot_id,
+                                    egress: decision.status, ...(decision.reason_category ? { reason: decision.reason_category } : {}) });
+                            }
+                            egress.push(...verified.provenance.map((item) => freeze(copy(item, COMPONENT_LIMITS.resultBytes))));
+                            const result = verified.disclosed;
+                            children.push(freeze(copy(result, COMPONENT_LIMITS.resultBytes)));
+                            // Tool transports may catch a rejection or ignore the returned value.
+                            // Retain failure in the host queue so root success cannot hide it.
+                            if (result.status !== "ok")
+                                throw new ExecutionFailure("callee_failed");
+                            return result;
+                        }, callId));
+                        queue = pending.catch(() => { });
+                        queued.push(pending);
+                        return pending;
+                    };
+                }
+                const terminal = component.steps.indexOf(step) >= lastPrimary;
+                this.host.onEvent?.({ ...event, kind: "step.start", step: step.name });
+                try {
+                    const pending = this.host.runStep({
+                        tier: step.tier, request: request.value.request,
+                        terminal,
+                        input: freeze(copy(request.value.input, COMPONENT_LIMITS.requestBytes)),
+                        ...(component.brief !== undefined ? { brief: component.brief } : {}),
+                        prompt: step.prompt, consumes: freeze(copy(consumes, COMPONENT_LIMITS.resultBytes)),
+                        children: freeze(copy(children, COMPONENT_LIMITS.resultBytes)),
+                        tools: Object.freeze(scoped), signal: this.controller.signal,
+                        toolSchemas: Object.freeze(schemas), toolDescriptions: Object.freeze(descriptions), perSlot,
+                    }, binding);
+                    // Keep observed usage even if cancellation makes a completion unusable.
+                    void pending.then((result) => {
+                        const usage = reportedUsage(result.usage);
+                        this.usage.inputTokens += usage.inputTokens;
+                        this.usage.outputTokens += usage.outputTokens;
+                        this.host.onEvent?.({ ...event, kind: "usage", step: step.name, usage });
+                    }).catch(() => { });
+                    const response = await this.wait(pending);
+                    accepting = false;
+                    // A transport cannot return while unobserved child calls still run.
+                    await this.wait(Promise.all(queued));
+                    const toolFailed = response.failed === true || (toolErrored && !perSlot);
+                    // A per-slot terminal must parse (the one tolerant definition normalization also uses).
+                    // When it does not and a repair step is declared for this step, the step fails so the
+                    // repair runs once; the repair receives the raw text alongside the parse error.
+                    const parsed = !toolFailed && perSlot && terminal && typeof response.value === "string" ? parseTerminalJson(response.value) : undefined;
+                    const unparsed = parsed && !parsed.ok ? `terminal_unparseable: ${parsed.error}` : undefined;
+                    const repairable = component.steps.some((candidate) => candidate.repairOf === step.name);
+                    const stepFailed = toolFailed || (unparsed !== undefined && repairable);
+                    unparseable = false;
+                    if (toolFailed) {
+                        products[step.produces] = { status: "error", code: "step_failed" };
+                        failed = step.name;
+                    }
+                    else if (stepFailed) {
+                        products[step.produces] = freeze(copy({ status: "error", code: "step_failed", reason: unparsed, text: response.value }, COMPONENT_LIMITS.resultBytes));
+                        failed = step.name;
+                    }
+                    else {
+                        products[step.produces] = freeze(copy(response.value, COMPONENT_LIMITS.resultBytes));
+                        failed = undefined;
+                        unparseable = unparsed !== undefined;
+                    }
+                    this.host.onEvent?.({ ...event, kind: "step.finish", step: step.name, status: stepFailed ? "error" : "ok" });
+                }
+                catch (error) {
+                    this.host.onEvent?.({ ...event, kind: "step.finish", step: step.name, status: this.controller.signal.aborted ? "cancelled" : "error" });
+                    throw error;
+                }
+                finally {
+                    active = false;
+                }
+            }
+            if (failed)
+                throw new ExecutionFailure("callee_failed");
+            const result = unparseable ? unanswerableBatch(request.value)
+                : copy(await this.wait(binding.normalize(freeze({ steps: products, tools, children, egress }), this.controller.signal)), COMPONENT_LIMITS.resultBytes);
+            if (!normalizedResult.safeParse(result).success)
+                throw new ExecutionFailure("invalid_result");
+            this.host.onEvent?.({ ...event, kind: "call.finish", status: result.status === "ok" ? "ok" : "error" });
+            return result;
+        }
+        catch (error) {
+            this.host.onEvent?.({ ...event, kind: "call.finish", status: this.controller.signal.aborted ? "cancelled" : "error" });
+            throw error;
+        }
+    }
+    validate() {
+        const nodes = this.plan.components;
+        if (!this.plan.identity || !this.plan.entries.length || Object.keys(nodes).length > 128 || !unique(this.plan.entries) || !unique(Object.keys(nodes)))
+            throw new Error("Invalid component plan");
+        const heights = new Map();
+        const visit = (id, active, depth) => {
+            const node = nodes[id];
+            if (!node || node.id !== id || active.has(id) || depth > COMPONENT_LIMITS.depth)
+                throw new Error("Invalid component closure");
+            const cached = heights.get(id);
+            if (cached !== undefined) {
+                if (depth + cached > COMPONENT_LIMITS.depth)
+                    throw new Error("Invalid component closure");
+                return;
+            }
+            if (!node.steps.length || node.steps.length > 128 || !unique(node.steps.map((step) => step.name)) || !unique(node.steps.map((step) => step.produces)))
+                throw new Error("Invalid component steps");
+            const products = new Set();
+            const next = new Set(active).add(id);
+            let height = 0;
+            for (const [index, step] of node.steps.entries()) {
+                if (!step.tier || !unique([...step.tools.map((tool) => tool.name), ...step.calls.map((edge) => edge.alias)]))
+                    throw new Error("Invalid step authority");
+                const previous = node.steps[index - 1];
+                if (step.repairOf && (!previous || previous.repairOf || previous.name !== step.repairOf || !step.consumes.includes(previous.produces)))
+                    throw new Error("Invalid repair");
+                if (step.consumes.some((name) => !products.has(name)))
+                    throw new Error("Invalid dataflow");
+                if (!step.repairOf)
+                    products.add(step.produces);
+                for (const edge of step.calls) {
+                    visit(edge.component, next, depth + 1);
+                    height = Math.max(height, 1 + heights.get(edge.component));
+                }
+            }
+            heights.set(id, height);
+        };
+        for (const entry of this.plan.entries)
+            visit(entry, new Set(), 0);
+    }
+}

package/dist-server/harness/components/semantic-guards.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare const querySemantics: z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    sql: z.ZodString;
+    metrics: z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    dimensions: z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    temporal_dimensions: z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type QuerySemantics = z.infer<typeof querySemantics>;
+/** Guard evidence originates in the bound query host; model products cannot satisfy it. */
+export declare function checkSemanticGuards(guards: readonly Record<string, unknown>[], proofs: readonly QuerySemantics[], context: unknown): boolean;

package/dist-server/harness/components/semantic-guards.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+const ref = z.object({ owner: z.string().min(1), name: z.string().min(1) }).strict();
+export const querySemantics = z.object({ version: z.literal("1"), sql: z.string(), metrics: z.array(ref).min(1), dimensions: z.array(ref), temporal_dimensions: z.array(ref) }).strict();
+const key = (value) => JSON.stringify([value.owner, value.name]);
+const prepared = z.object({ context_version: z.literal(2), parseable: z.literal(true),
+    metrics: z.array(ref.extend({ declared: z.boolean(), additivity: z.string().nullable() })),
+    dimensions: z.array(ref.extend({ is_temporal: z.boolean() })),
+});
+/** Guard evidence originates in the bound query host; model products cannot satisfy it. */
+export function checkSemanticGuards(guards, proofs, context) {
+    const additive = guards.some((guard) => guard.name === "additivity_guard" && guard.locked === true);
+    const drill = guards.find((guard) => guard.name === "drill_depth_limit");
+    if (!additive && !drill)
+        return true;
+    const snapshot = prepared.safeParse(context);
+    if (!snapshot.success || proofs.length === 0)
+        return false;
+    const limit = drill ? z.number().int().nonnegative().safeParse(drill.threshold) : undefined;
+    if (limit && !limit.success)
+        return false;
+    const dimensions = new Set();
+    let temporal = false;
+    for (const proof of proofs) {
+        for (const metric of proof.metrics) {
+            const matches = snapshot.data.metrics.filter((member) => key(member) === key(metric));
+            if (matches.length !== 1 || !matches[0].declared || (additive && matches[0].additivity !== "additive"))
+                return false;
+        }
+        for (const [members, isTemporal] of [[proof.dimensions, false], [proof.temporal_dimensions, true]]) {
+            for (const dimension of members) {
+                const matches = snapshot.data.dimensions.filter((member) => key(member) === key(dimension));
+                if (matches.length !== 1 || matches[0].is_temporal !== isTemporal)
+                    return false;
+                if (isTemporal)
+                    temporal = true;
+                else
+                    dimensions.add(key(dimension));
+            }
+        }
+    }
+    return temporal && (!limit?.success || dimensions.size <= limit.data);
+}

package/dist-server/harness/components/terminal-json.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/** One batch entry: a slot id plus whatever the model wrote; normalization decides what is kept. */
+export declare const batchEntry: z.ZodObject<{
+    slot_id: z.ZodString;
+}, z.core.$loose>;
+/**
+ * The single definition of "a terminal parses": the whole text as JSON, else the one JSON value
+ * a prose wrapper holds. A loose array counts only when it holds batch entries, so an incidental
+ * array in a single-answer terminal stays prose. Malformed JSON is refused, never repaired by guess;
+ * the error is the strict parse's message, for the repair step to act on.
+ */
+export declare function parseTerminalJson(text: string): {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};

package/dist-server/harness/components/terminal-json.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+/** One batch entry: a slot id plus whatever the model wrote; normalization decides what is kept. */
+export const batchEntry = z.object({ slot_id: z.string().min(1).max(128) }).passthrough();
+// An unclosed bracket rescans to the end, and a bracket that closes but does not parse (a Markdown
+// link) also counts: after this many failures the scan gives up and the text stays prose.
+const MAX_FAILED_STARTS = 64;
+/** The end index of the bracketed span opening at `start`, tracking JSON strings; -1 when it never closes. */
+function spanEnd(text, start) {
+    let depth = 0;
+    let inString = false;
+    for (let index = start; index < text.length; index++) {
+        const char = text[index];
+        if (inString) {
+            if (char === "\\")
+                index++;
+            else if (char === '"')
+                inString = false;
+        }
+        else if (char === '"')
+            inString = true;
+        else if (char === "{" || char === "[")
+            depth++;
+        else if (char === "}" || char === "]") {
+            depth--;
+            if (depth === 0)
+                return index;
+        }
+    }
+    return -1;
+}
+function parsedJson(text) {
+    try {
+        return { value: JSON.parse(text) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The one top-level JSON array or object in a prose terminal, after dropping reasoning tags
+ * and Markdown fences. Zero or several candidates return undefined, so the text stays prose.
+ */
+function soleJsonValue(raw) {
+    const untagged = raw.replace(/<think>[\s\S]*?<\/think>/gi, "");
+    // A lone closing tag: everything before it is treated as reasoning.
+    const closing = untagged.toLowerCase().lastIndexOf("</think>");
+    const text = (closing >= 0 ? untagged.slice(closing + "</think>".length) : untagged).replace(/```[\w-]*/g, "");
+    const found = [];
+    let failures = 0;
+    for (let index = 0; index < text.length; index++) {
+        if (text[index] !== "{" && text[index] !== "[")
+            continue;
+        const end = spanEnd(text, index);
+        const candidate = end >= 0 ? parsedJson(text.slice(index, end + 1)) : undefined;
+        if (candidate) {
+            found.push(candidate.value);
+            if (found.length > 1)
+                return undefined;
+            index = end;
+        }
+        else if (++failures > MAX_FAILED_STARTS)
+            return undefined;
+    }
+    return found.length === 1 ? found[0] : undefined;
+}
+/**
+ * The single definition of "a terminal parses": the whole text as JSON, else the one JSON value
+ * a prose wrapper holds. A loose array counts only when it holds batch entries, so an incidental
+ * array in a single-answer terminal stays prose. Malformed JSON is refused, never repaired by guess;
+ * the error is the strict parse's message, for the repair step to act on.
+ */
+export function parseTerminalJson(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch (error) {
+        const loose = soleJsonValue(text);
+        if (loose !== undefined && (!Array.isArray(loose) || loose.some((entry) => batchEntry.safeParse(entry).success)))
+            return { ok: true, value: loose };
+        return { ok: false, error: error instanceof Error ? error.message : "invalid JSON" };
+    }
+}