@wrenai/genbi 0.0.4 → 0.0.6

package/dist-server/harness/components/in-process.js

@@ -0,0 +1,245 @@
+import { randomUUID } from "node:crypto";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { fingerprintSurfaces } from "@warble/claude-agent-sdk";
+import { generatePreparedContext, generatePreparedContextAndCatalog, resolveContextLoader } from "../compile/context-loader.js";
+import { hashDirectory } from "../compile/fingerprint.js";
+import { resolveWarbleBinary } from "../compile/resolve-binary.js";
+import { createAgentEventEmitter } from "../events/emitter.js";
+import { createDefaultProviderRegistry, isZoneAwareBinding, resolveTierModel, resolveTierSpec } from "../providers/index.js";
+import { deriveAdapterSpec } from "../route/adapter-spec.js";
+import { resolveWrenBinary } from "../tools/index.js";
+import { runAiComponentStep } from "./ai-step.js";
+import { createComponentBroker } from "./broker.js";
+import { buildCapabilityCard } from "./capability-card.js";
+import { verifyEgress } from "./egress.js";
+import { createModelJudge } from "./egress-judge.js";
+import { normalizeComponentEvidence } from "./normalize.js";
+import { buildSlotTable, isReportComponent, materialiseReportPlan, normalizeReportEvidence, parseReportPlan, reportSteps } from "./report.js";
+import { planDigest } from "./plan.js";
+import { ComponentRunner } from "./runner.js";
+import { modelIdOf, summariseUsage } from "./usage.js";
+import { captureWrenAccessIdentity, openWrenComponentAccess } from "./wren-access.js";
+import { assertZoneGate } from "./zone-gate.js";
+const data = z.object({ columns: z.array(z.string()), rows: z.array(z.record(z.string(), z.unknown())) });
+/** Executable format 0.2 path; never flattened into the legacy agent tool union. */
+export async function runInProcessComponents(plan, options) {
+    if (options.mcpServers)
+        throw new Error("Composed execution requires component-owned host bindings");
+    // The historical default entry is `answer_query`; a composed profile with exactly one entry
+    // (the report profile: `plan_report` alone is an entry) runs that entry when none is named.
+    const entry = options.agentId ?? defaultEntry(plan);
+    // The binding is fixed and gated here, before any scratch state, context
+    // generation, provider construction or child process exists. A rejected
+    // binding therefore produces none of them.
+    const binding = {
+        tiers: structuredClone(options.tierBinding ?? Object.fromEntries(Object.values(plan.components).flatMap((component) => component.steps.map((step) => [step.tier,
+            deriveAdapterSpec(options.authChoice, options.model ? { model: options.model } : {})])))),
+        ...(options.disclosurePolicy !== undefined ? { disclosurePolicy: structuredClone(options.disclosurePolicy) } : {}),
+        ...(options.zoneRoles !== undefined ? { roles: structuredClone(options.zoneRoles) } : {}),
+    };
+    assertZoneGate(plan, entry, binding);
+    const controller = new AbortController();
+    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+    const scratch = await mkdtemp(path.join(os.tmpdir(), "genbi-component-context-"));
+    const emitter = createAgentEventEmitter(options.onEvent);
+    const traceSteps = [];
+    const surfaceRecords = [];
+    const usageRecords = [];
+    const trace = () => ({ steps: traceSteps.sort((a, b) => a.ordinal - b.ordinal), surfaces: surfaceRecords, usage: summariseUsage(usageRecords) });
+    const toolOrder = new Map();
+    const zoneAware = isZoneAwareBinding(binding);
+    emitter.emit({ kind: "run.start", mode: "A", agentId: entry });
+    try {
+        signal.throwIfAborted();
+        const project = path.resolve(options.userProject);
+        const fingerprint = await hashDirectory(project);
+        const accessIdentity = await captureWrenAccessIdentity(project);
+        const snapshotPath = path.join(scratch, "context.json");
+        const catalogPath = path.join(scratch, "catalog.json");
+        // A zone-aware run also needs the capability catalog: the card public-zone steps
+        // receive instead of the snapshot. One generator process reads the project once.
+        if (zoneAware)
+            await generatePreparedContextAndCatalog(resolveContextLoader().bin, project, snapshotPath, catalogPath);
+        else
+            await generatePreparedContext(resolveContextLoader().bin, project, snapshotPath);
+        const snapshot = JSON.parse(await readFile(snapshotPath, "utf8"));
+        let card;
+        if (zoneAware) {
+            // The bound policy's shape limits go on the card, so the planner plans within what egress allows.
+            const maxBytes = options.capabilityCard?.maxBytes;
+            card = buildCapabilityCard(JSON.parse(await readFile(catalogPath, "utf8")), { ...(maxBytes !== undefined ? { maxBytes } : {}),
+                ...(binding.disclosurePolicy ? { disclosure: binding.disclosurePolicy } : {}) });
+            if (card.truncated)
+                traceSteps.push({ id: "capability-card", tool: "capability_card", outcome: "success", ordinal: -1,
+                    detail: `warning: capability card truncated by the size bound (${card.omittedLines} lines omitted, ${card.bytes} bytes kept)` });
+        }
+        const zoneOf = (component, tier) => resolveTierSpec(binding, tier, component)?.spec.zone ?? "unbound";
+        const checkProject = async () => {
+            signal.throwIfAborted();
+            await accessIdentity.assertCurrent();
+            if (fingerprint !== await hashDirectory(project)) {
+                controller.abort();
+                throw new Error("Component project changed");
+            }
+        };
+        await checkProject();
+        const contexts = Object.fromEntries(Object.values(plan.components).map((component) => {
+            const binding = z.object({ project: z.string() }).passthrough().parse(component.declaration.context_binding);
+            if (path.resolve(binding.project) !== project)
+                throw new Error("Component is bound to another project");
+            return [component.id, { binding, snapshot }];
+        }));
+        const registry = createDefaultProviderRegistry();
+        const identity = { session: randomUUID(), vendor: "in-process", account: planDigest(binding), generation: randomUUID(),
+            project, bindingRevision: planDigest([fingerprint, accessIdentity.digest]), contextDigest: planDigest(contexts), planDigest: plan.identity };
+        const models = new Map();
+        // Counts only, attributed to the provider that served the call; the payload never enters the record.
+        const recordUsage = (at, spec, model, usage) => {
+            usageRecords.push({ ...at, zone: spec?.zone ?? "unbound", adapter: spec?.adapter ?? "unbound", model: model ? modelIdOf(model) : "unbound",
+                inputTokens: usage.inputTokens, outputTokens: usage.outputTokens });
+        };
+        // The egress verification seam is installed whenever a disclosure policy is
+        // bound. The gate has already required a private judge tier for it, so a
+        // missing judge here is an internal error, not a degrade.
+        const policy = binding.disclosurePolicy;
+        const judgeKey = binding.roles?.judge;
+        const judgeSpec = judgeKey !== undefined ? binding.tiers[judgeKey] : undefined;
+        if (policy && !judgeSpec)
+            throw new Error("Egress verification requires a bound judge tier");
+        const judgeModel = judgeSpec ? registry.create(judgeSpec.adapter, judgeSpec.config) : undefined;
+        const broker = createComponentBroker({ plan, contexts, verifierBinary: await resolveWarbleBinary(options.warbleBin),
+            identity, currentIdentity: () => signal.aborted ? undefined : identity,
+            ...(policy ? { verifyChild: async (context, result, parent) => {
+                    await checkProject();
+                    const judge = judgeModel ? createModelJudge(judgeModel, (usage) => recordUsage({ component: context.callee, step: "egress_judge", tier: judgeKey, depth: context.depth }, judgeSpec, judgeModel, usage)) : undefined;
+                    return verifyEgress(context.request, result, { policy, ...(judge ? { judge } : {}), signal: parent });
+                } } : {}),
+            async prepare(component, _identity, parent) {
+                await checkProject();
+                // Keyed on (mount, tier): a caller and callee sharing a tier name can bind different models.
+                models.set(component.id, new Map([...new Set(component.steps.map((step) => step.tier))]
+                    .map((tier) => [tier, resolveTierModel(binding, tier, registry, component.id)])));
+                if (component.steps.every((step) => step.tools.length === 0))
+                    return {
+                        async query() { throw new Error("No query grant"); }, async inspect() { throw new Error("No context grant"); }, async close() { },
+                    };
+                await resolveWrenBinary();
+                return openWrenComponentAccess({ executable: "wren", project, fingerprint, signal: parent, identity: accessIdentity });
+            },
+            // Public-zone steps never see the prepared snapshot; they get the card. Private steps get the snapshot as before.
+            ...(card ? { contextSurface: (component, run) => {
+                    if (zoneOf(component.id, run.tier) === "public")
+                        return { kind: "card", text: card.text };
+                    const context = contexts[component.id];
+                    return context ? { kind: "snapshot", text: `Host semantic context:\n${JSON.stringify(context.snapshot)}` } : undefined;
+                } } : {}),
+            async step(run, component) {
+                await checkProject();
+                const model = models.get(component.id)?.get(run.tier);
+                if (!model)
+                    throw new Error("Missing component tier binding");
+                // Host materialisation for a report's narrator: the layout it consumes is resolved from the
+                // slot table (the disclosed child answers) before the model reads it, so the values it sees
+                // are the verified ones and it never has to retype a number. The recorded product stays the
+                // planner's own output; only the consumed view is materialised (decision recorded in the design doc).
+                let consumes = run.consumes;
+                const report = isReportComponent(component) ? reportSteps(component) : undefined;
+                if (report && Object.hasOwn(run.consumes, report.layout.produces)) {
+                    const layout = parseReportPlan(run.consumes[report.layout.produces]);
+                    if (!layout)
+                        throw new Error("The planner did not produce a report layout");
+                    consumes = { ...run.consumes, [report.layout.produces]: materialiseReportPlan(layout, buildSlotTable(run.children)) };
+                }
+                // Every part of the assembled model input is fingerprinted, including the request and the
+                // consumed artifacts, so an audit of a public-tier prompt covers the values that crossed.
+                const surfaces = { ...(run.surfaces ?? { prompt: run.prompt }) };
+                if (plan.systemPrompt)
+                    surfaces["system"] = plan.systemPrompt;
+                if (run.brief !== undefined)
+                    surfaces["brief"] = run.brief;
+                surfaces["input"] = JSON.stringify({ request: run.request, input: run.input });
+                surfaces["consumes"] = JSON.stringify(consumes);
+                const fingerprint = fingerprintSurfaces(surfaces);
+                const stepName = plan.components[component.id]?.steps.find((step) => step.prompt === surfaces["prompt"] && step.tier === run.tier)?.name ?? "?";
+                surfaceRecords.push({ component: component.id, step: stepName, tier: run.tier, zone: zoneOf(component.id, run.tier), context: run.contextKind ?? "none",
+                    algorithm: fingerprint.algorithm, digest: fingerprint.digest, surfaces: fingerprint.surfaces });
+                const result = await runAiComponentStep({ ...run, consumes, prompt: [plan.systemPrompt, run.prompt].filter(Boolean).join("\n\n") }, model);
+                await checkProject();
+                return result;
+            },
+            async normalize(component, evidence) {
+                await checkProject();
+                // A report's envelope is synthesised by the host from the slot table; every other component keeps the generic path.
+                return isReportComponent(component) ? normalizeReportEvidence(component, evidence) : normalizeComponentEvidence(component, evidence, contexts[component.id]?.snapshot);
+            },
+            onEvent(event) {
+                if (event.kind === "usage" && event.step) {
+                    const tier = plan.components[event.component]?.steps.find((step) => step.name === event.step)?.tier ?? "unbound";
+                    recordUsage({ component: event.component, step: event.step, tier, depth: event.depth }, resolveTierSpec(binding, tier, event.component)?.spec, models.get(event.component)?.get(tier), event.usage ?? { inputTokens: 0, outputTokens: 0 });
+                    return;
+                }
+                if (event.kind === "egress") {
+                    // Slot id, status and reason category only: the payload never enters the trace.
+                    traceSteps.push({ id: `${event.callId}:egress:${event.slot}`, tool: "egress", outcome: event.egress === "refused" ? "error" : "success",
+                        ordinal: toolOrder.get(event.callId ?? "") ?? traceSteps.length, detail: `${event.tool}/${event.slot}: ${event.egress}${event.reason ? ` (${event.reason})` : ""}` });
+                    return;
+                }
+                if (event.callId && event.tool && event.kind === "tool.start")
+                    toolOrder.set(event.callId, toolOrder.size);
+                if (event.callId && event.tool && event.kind === "tool.finish")
+                    traceSteps.push({ id: event.callId, tool: event.tool,
+                        outcome: event.status === "ok" ? "success" : "error", ordinal: toolOrder.get(event.callId) ?? traceSteps.length });
+                if (!event.step)
+                    return;
+                const stepId = `${event.invocation}:${event.step}`;
+                if (event.kind === "step.start")
+                    emitter.emit({ kind: "step.start", stepId, name: event.step,
+                        tier: plan.components[event.component].steps.find((step) => step.name === event.step).tier,
+                        ...(event.parent ? { parent: event.parent } : {}), depth: event.depth });
+                if (event.kind === "step.finish")
+                    emitter.emit({ kind: "step.finish", stepId, name: event.step, status: event.status === "ok" ? "ok" : "error" });
+                if (event.tool && event.callId && event.kind === "tool.start")
+                    emitter.emit({ kind: "tool.call", stepId, callId: event.callId, tool: event.tool, depth: event.depth, status: "running" });
+                if (event.tool && event.callId && event.kind === "tool.finish")
+                    emitter.emit({ kind: "tool.result", stepId, callId: event.callId, tool: event.tool, status: event.status === "ok" ? "success" : "error" });
+            },
+        });
+        const result = await new ComponentRunner(plan, broker).run(entry, { request: options.question }, signal);
+        if (result.status === "error")
+            throw new Error("Component execution did not complete.");
+        if (result.status !== "ok") {
+            const envelope = { blocks: [], verified: false };
+            emitter.emit({ kind: "refusal", reason: result.message, envelope });
+            emitter.emit({ kind: "run.finish", status: "refusal" });
+            return { kind: "refusal", reason: result.message, envelope, trace: trace() };
+        }
+        const value = result.output.kind === "value" ? data.safeParse(result.output.value) : undefined;
+        const blocks = result.output.kind === "render" ? result.output.blocks : value?.success
+            ? [{ type: "table", columns: value.data.columns, rows: value.data.rows }]
+            : [{ type: "narrative", text: JSON.stringify(result.output.value) }];
+        const envelope = { blocks, verified: result.provenance?.verified === true,
+            ...(result.output.kind === "render" && result.output.summary !== undefined ? { summary: result.output.summary } : {}),
+            ...(result.provenance?.definition ? { definition: result.provenance.definition } : {}) };
+        emitter.emit({ kind: "answer", envelope });
+        emitter.emit({ kind: "run.finish", status: "answer" });
+        return { kind: "answer", envelope, trace: trace() };
+    }
+    catch (error) {
+        emitter.emit({ kind: "error", message: "Component preparation or execution failed." });
+        emitter.emit({ kind: "run.finish", status: "error" });
+        throw error;
+    }
+    finally {
+        controller.abort();
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/** `answer_query` when the plan has it, else the plan's single entry; a multi-entry plan without `answer_query` keeps the historical default and fails as before. */
+export function defaultEntry(plan) {
+    if (plan.entries.includes("answer_query"))
+        return "answer_query";
+    return plan.entries.length === 1 ? plan.entries[0] : "answer_query";
+}

package/dist-server/harness/components/normalize.d.ts

@@ -0,0 +1,35 @@
+import { type ComponentInvocationResult } from "@warble/claude-agent-sdk";
+import { z } from "zod";
+import { type ComponentEvidence, type ComponentPlan } from "./runner.js";
+declare const definitionSchema: z.ZodObject<{
+    sql: z.ZodString;
+    source_tables: z.ZodArray<z.ZodString>;
+    filters: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+declare const table: z.ZodObject<{
+    columns: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type Definition = z.infer<typeof definitionSchema>;
+type Observation = ComponentEvidence["tools"][number];
+export interface GroundedQuery {
+    readonly sql: string;
+    readonly queryId?: string;
+    readonly table: z.infer<typeof table>;
+    readonly definition: Definition;
+}
+export declare function groundedQuery(call: Pick<Observation, "input" | "output">): GroundedQuery | undefined;
+/**
+ * The executed query a citation names, grounded, else `undefined`. A citation by host-assigned
+ * `query_id` resolves to that observation only: an id no executed query carries is never grounded
+ * on another query or on its SQL text. Otherwise the last observation of the same SQL, compared
+ * whitespace- and terminator-insensitively (the model may reformat the SQL it names). An
+ * observation that cannot ground (see `groundingDefinition`) never matches.
+ */
+export declare function citedGroundedQuery(observations: readonly Pick<Observation, "input" | "output">[], citation: {
+    readonly queryId?: string | undefined;
+    readonly sql?: string | undefined;
+}): GroundedQuery | undefined;
+/** Child normalization is pure. Data evidence comes from observed tools, never a verified flag. */
+export declare function normalizeComponentEvidence(component: ComponentPlan, evidence: ComponentEvidence, context?: unknown): ComponentInvocationResult;
+export {};

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

@@ -0,0 +1,245 @@
+import { normalizeComponentResult } from "@warble/claude-agent-sdk";
+import { z } from "zod";
+import { checkSemanticGuards, querySemantics } from "./semantic-guards.js";
+import { namedAnswerQueryId, namedAnswerSql, selectAnsweringCandidate, sqlKey } from "../render/answering-query.js";
+import { isQueryGrant } from "./runner.js";
+import { batchEntry, parseTerminalJson } from "./terminal-json.js";
+const definitionSchema = z.object({ sql: z.string(), source_tables: z.array(z.string()), filters: z.array(z.string()) }).strict();
+/** A definition a render block may be grounded on: `filters` is optional in the block contract. */
+const lineageSchema = z.object({ sql: z.string(), source_tables: z.array(z.string()), filters: z.array(z.string()).optional() }).strict();
+const table = z.object({ columns: z.array(z.string()).min(1), rows: z.array(z.record(z.string(), z.unknown())) });
+const blocks = z.array(z.object({ type: z.string(), fields: z.record(z.string(), z.string()) }).strict());
+const capabilities = z.array(z.string());
+/** The host-assigned id of an executed query (`q<N>`, see the runner), read from the observed output only. */
+function queryIdOf(output) {
+    const id = output?.query_id;
+    return typeof id === "string" ? id : undefined;
+}
+/**
+ * The one test for whether a component's own tool observation may ground an answer, a render
+ * block or a batch entry: the result is a table, the tool itself proved a `definition` for the
+ * SQL it executed, and that definition reads at least one table. Returns the proven definition,
+ * else `undefined`. A definition the model claims never counts, so an observation without a
+ * proven one grounds nothing (fail closed).
+ *
+ * Known limit: this proves the query read a model, not where each projected value came from. A
+ * query that reads a model can still project literals (`SELECT CASE ... THEN 424 ... FROM orders`).
+ */
+function groundingDefinition(call) {
+    const sql = call.input?.sql;
+    if (typeof sql !== "string" || !table.safeParse(call.output).success)
+        return undefined;
+    const proven = definitionSchema.safeParse(call.output?.definition);
+    if (!proven.success || proven.data.sql !== sql)
+        return undefined;
+    return proven.data.source_tables.some((name) => name.length > 0) ? proven.data : undefined;
+}
+function canGround(call) {
+    return groundingDefinition(call) !== undefined;
+}
+export function groundedQuery(call) {
+    const definition = groundingDefinition(call);
+    const parsed = table.safeParse(call.output);
+    if (!definition || !parsed.success)
+        return undefined;
+    const queryId = queryIdOf(call.output);
+    return { sql: definition.sql, ...(queryId !== undefined ? { queryId } : {}), table: parsed.data, definition };
+}
+/**
+ * The executed query a citation names, grounded, else `undefined`. A citation by host-assigned
+ * `query_id` resolves to that observation only: an id no executed query carries is never grounded
+ * on another query or on its SQL text. Otherwise the last observation of the same SQL, compared
+ * whitespace- and terminator-insensitively (the model may reformat the SQL it names). An
+ * observation that cannot ground (see `groundingDefinition`) never matches.
+ */
+export function citedGroundedQuery(observations, citation) {
+    const { queryId } = citation;
+    const claimedSql = queryId === undefined ? citation.sql : undefined;
+    const observed = queryId !== undefined ? observations.find((call) => queryIdOf(call.output) === queryId && canGround(call))
+        : claimedSql === undefined ? undefined
+            : [...observations].reverse().find((call) => { const ran = call.input?.sql; return typeof ran === "string" && sqlKey(ran) === sqlKey(claimedSql) && canGround(call); });
+    return observed ? groundedQuery(observed) : undefined;
+}
+function refused() {
+    return { status: "refused", code: "callee_refused", message: "The component did not produce a grounded result." };
+}
+/** Child normalization is pure. Data evidence comes from observed tools, never a verified flag. */
+export function normalizeComponentEvidence(component, evidence, context) {
+    const grants = component.steps.flatMap((step) => step.tools);
+    const queryNames = new Set(grants.filter(isQueryGrant).map((grant) => grant.name));
+    const observations = evidence.tools.filter((call) => queryNames.has(call.tool));
+    const guards = z.array(z.record(z.string(), z.unknown())).parse(component.declaration.guardrails ?? []);
+    const semanticGuard = guards.some((guard) => (guard.name === "additivity_guard" && guard.locked === true) || guard.name === "drill_depth_limit");
+    const proofs = [];
+    for (const call of observations) {
+        const proof = querySemantics.safeParse(call.output?.semantics);
+        if (proof.success && proof.data.sql === call.input?.sql)
+            proofs.push(proof.data);
+        else if (semanticGuard)
+            return refused();
+    }
+    // The public child-result contract carries no semantic query proof. Do not infer
+    // additivity from a child's generic verified flag or from its model-authored value.
+    if (semanticGuard && evidence.children.length > 0)
+        return refused();
+    if (!checkSemanticGuards(guards, proofs, context))
+        return refused();
+    // Only observations that can ground become evidence, for the single answer, a batch entry and
+    // render blocks alike; a table-less or unproven query is as if it never returned a table.
+    const queries = observations.map(groundedQuery).filter((query) => query !== undefined);
+    const definitions = queries.map((query) => query.definition);
+    const data = queries.map((query) => query.table);
+    const declared = capabilities.parse(component.declaration.required_capabilities);
+    const render = blocks.parse(component.declaration.effect.render_blocks ?? []);
+    const steps = component.steps.filter((step) => Object.hasOwn(evidence.steps, step.produces));
+    const terminal = steps.at(-1);
+    if (!terminal)
+        return refused();
+    const lastProduct = evidence.steps[terminal.produces];
+    // Tool evidence cannot turn an explicit terminal refusal or error into success.
+    let terminalValue = lastProduct;
+    if (typeof lastProduct === "string") {
+        // Ordinary prose is normalized below. Only the parse is tolerant: the value feeds the refusal
+        // check and the value branches; the render path still parses the raw text.
+        const parsed = parseTerminalJson(lastProduct);
+        terminalValue = parsed.ok ? parsed.value : lastProduct;
+    }
+    if (terminalValue && typeof terminalValue === "object" && "status" in terminalValue
+        && ["refused", "error"].includes(String(terminalValue.status)))
+        return refused();
+    if (declared.includes("sql_execution:read_only") && data.length === 0)
+        return refused();
+    // A batch-shaped callee (answer_batch) ends in an array with one entry per slot. Each tabular
+    // entry is rebuilt from the observed query result its SQL names; the model's copy of the rows
+    // is never read, and an entry no executed query backs is returned as unanswerable.
+    if (render.length === 0 && Array.isArray(terminalValue))
+        return normalizeBatchTerminal(terminalValue, observations);
+    if (render.length === 0 && data.length > 0) {
+        // The answer is the query the terminal value names, never simply the last table: a model
+        // that runs a stray check after the right query must not turn that check into the answer.
+        // A value naming no query (by id or SQL) keeps the historical last-observation rule; a value
+        // naming a query that never ran is refused rather than answered with another table.
+        let chosen;
+        if (namedAnswerQueryId(terminalValue) === undefined && namedAnswerSql(terminalValue) === undefined) {
+            chosen = groundedQuery(observations[observations.length - 1]);
+        }
+        else {
+            chosen = selectAnsweringCandidate(queries, terminalValue);
+        }
+        if (!chosen)
+            return refused();
+        const definition = chosen.definition;
+        return { status: "ok", output: { kind: "value", value: { ...chosen.table, verified: true, summary: "Query completed.", definition } },
+            provenance: { verified: true, definition } };
+    }
+    const result = normalizeComponentResult(typeof lastProduct === "string" ? lastProduct : JSON.stringify(lastProduct), render).value;
+    if (result.status !== "ok")
+        return result;
+    const composed = component.steps.some((step) => step.calls.length > 0);
+    if (composed) {
+        if (evidence.children.length === 0 || evidence.children.some((child) => child.status !== "ok" || child.provenance?.verified !== true))
+            return refused();
+        for (const child of evidence.children) {
+            if (child.status !== "ok" || child.output.kind !== "value")
+                return refused();
+            const parsed = table.safeParse(child.output.value);
+            if (!parsed.success)
+                return refused();
+            data.push(parsed.data);
+            const definition = lineageSchema.safeParse(child.provenance?.definition);
+            if (definition.success)
+                definitions.push(definition.data);
+        }
+    }
+    if (result.output.kind === "render" && data.length > 0 && !grounded(result.output.blocks, data, definitions))
+        return refused();
+    // A render with data-bearing blocks cannot earn provenance from prose alone.
+    if (result.output.kind === "render" && result.output.blocks.some((block) => ["table", "chart", "kpi_card"].includes(String(block.type))) && data.length === 0)
+        return refused();
+    return { ...result, provenance: { ...result.provenance, verified: data.length > 0 } };
+}
+function grounded(render, data, definitions) {
+    return render.every((block) => {
+        // `filters` is optional in the block contract: compared only when both sides carry it.
+        if (block.type === "definition")
+            return definitions.some((definition) => definition.sql === block.sql
+                && JSON.stringify(definition.source_tables) === JSON.stringify(block.source_tables)
+                && (block.filters === undefined || definition.filters === undefined || JSON.stringify(definition.filters) === JSON.stringify(block.filters)));
+        if (block.type === "kpi_card")
+            return typeof block.label === "string" && data.some((source) => source.columns.includes(block.label)
+                && source.rows.some((row) => row[block.label] === block.value
+                    && (block.unit === undefined || (Object.hasOwn(row, "unit") && row.unit === block.unit))
+                    && (block.delta === undefined || (Object.hasOwn(row, "delta") && row.delta === block.delta))));
+        if (block.type !== "table" && block.type !== "chart")
+            return true;
+        if (!Array.isArray(block.rows))
+            return false;
+        const columns = block.type === "table" ? block.columns : [block.x, ...(Array.isArray(block.series) ? block.series : [])];
+        if (!Array.isArray(columns) || !columns.length || new Set(columns).size !== columns.length || !columns.every((value) => typeof value === "string"))
+            return false;
+        const sources = data.filter((source) => columns.every((name) => source.columns.includes(name)));
+        if (!sources.length)
+            return false;
+        if (block.rows.length === 0)
+            return sources.some((source) => source.rows.length === 0);
+        return block.rows.every((row) => {
+            if (Array.isArray(row) && row.length !== columns.length)
+                return false;
+            const values = Array.isArray(row) ? Object.fromEntries(columns.map((name, index) => [name, row[index]])) : row;
+            if (!values || typeof values !== "object")
+                return false;
+            if (Object.keys(values).length !== columns.length || !columns.every((name) => Object.hasOwn(values, name)))
+                return false;
+            return sources.some((source) => source.rows.some((observed) => Object.entries(values).every(([name, value]) => Object.hasOwn(observed, name) && JSON.stringify(observed[name]) === JSON.stringify(value))));
+        });
+    });
+}
+const REASON_LIMIT = 200;
+function sanitizedReason(value, fallback) {
+    const text = typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+    return (text.length > 0 ? text : fallback).slice(0, REASON_LIMIT);
+}
+/**
+ * One entry per slot, first entry per slot id wins. A tabular entry is
+ * accepted only when its `definition` cites a query this run executed with a
+ * result that can ground (see `groundingDefinition`): by `query_id` (the id the
+ * host attached to that tool result), else by `sql`. Its columns, rows and
+ * definition are then the observed ones. The model contributes `summary` only;
+ * every value comes from the tool. Entries the model marked
+ * `unanswerable` (or `refused`) pass through with a bounded reason.
+ */
+function normalizeBatchTerminal(entries, observations) {
+    const seen = new Set();
+    const value = [];
+    let answered = 0;
+    for (const raw of entries) {
+        const entry = batchEntry.safeParse(raw);
+        if (!entry.success || seen.has(entry.data.slot_id))
+            continue;
+        seen.add(entry.data.slot_id);
+        const item = entry.data;
+        if (item.status === "unanswerable" || item.status === "refused") {
+            value.push({ slot_id: item.slot_id, status: "unanswerable", reason: sanitizedReason(item.reason, "the callee could not answer this slot") });
+            continue;
+        }
+        const claimed = item.definition && typeof item.definition === "object" ? item.definition : undefined;
+        // An id no executed query carries, or a cited query that cannot ground, is unanswerable.
+        const query = citedGroundedQuery(observations, {
+            queryId: typeof claimed?.query_id === "string" ? claimed.query_id : undefined,
+            sql: typeof claimed?.sql === "string" ? claimed.sql : undefined,
+        });
+        if (!query) {
+            value.push({ slot_id: item.slot_id, status: "unanswerable", reason: "no executed query backs this answer" });
+            continue;
+        }
+        // Provenance is the observed query's tool-proven definition; any definition fields the
+        // model sends besides the citation are ignored.
+        answered += 1;
+        value.push({ slot_id: item.slot_id, columns: query.table.columns, rows: query.table.rows, verified: true,
+            summary: typeof item.summary === "string" ? item.summary : "Query completed.", definition: query.definition });
+    }
+    if (value.length === 0)
+        return refused();
+    // Spec §6.2: an array value is preserved as-is with no outer provenance; per-entry `verified`/`definition` stay on the entries.
+    return { status: "ok", output: { kind: "value", value }, ...(answered > 0 ? { provenance: { verified: true } } : {}) };
+}

package/dist-server/harness/components/plan.d.ts

@@ -0,0 +1,31 @@
+import type { ExecutionPlan } from "./runner.js";
+export declare const HOST_FEATURES: readonly ["immutable_step_authority", "isolated_component_tools", "fresh_child_context", "verified_context_preconditions", "component_owned_bindings", "exact_step_tiers", "exact_dataflow", "bounded_repair", "shared_admission_ledger", "deadline_and_descendant_cancellation", "normalized_child_results", "root_only_persistence", "redacted_usage_trace"];
+export declare const VERCEL_HOST_CONTRACT: Readonly<{
+    protocol: "warble-component-host/1";
+    bundle_version: "0.2";
+    features: readonly ["immutable_step_authority", "isolated_component_tools", "fresh_child_context", "verified_context_preconditions", "component_owned_bindings", "exact_step_tiers", "exact_dataflow", "bounded_repair", "shared_admission_ledger", "deadline_and_descendant_cancellation", "normalized_child_results", "root_only_persistence", "redacted_usage_trace"];
+    guardrails: string[];
+    tool_authority: {
+        query: {
+            source: string;
+            capabilities: string[];
+        };
+        semantic_introspect: {
+            source: string;
+            capabilities: string[];
+        };
+    };
+}>;
+/** SHA over recursively sorted JSON, matching the producer's documented digest form. */
+export declare function canonicalPlanJson(value: unknown): string;
+export declare function planDigest(value: unknown): string;
+export interface PlanReceipt {
+    /** Trusted host receipt captured from its successful producer invocation, never model input. */
+    readonly digest: string;
+    readonly inputIrDigest: string;
+    readonly contextBinding: Readonly<Record<string, unknown>>;
+    readonly declarations: Readonly<Record<string, unknown>>;
+    /** Exact host contract bytes passed to the direct-session producer. */
+    readonly directHostDocument?: string;
+}
+export declare function readExecutionPlan(document: string, receipt: PlanReceipt): ExecutionPlan;