@wrenai/genbi 0.0.3 → 0.0.5

package/dist-server/harness/compile/pipeline.js

@@ -1,16 +1,25 @@
 import { execFile } from "node:child_process";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createFileSystemCompileCache } from "./cache.js";
 import { composeUserProfile } from "./compose-profile.js";
+import { getContextLoaderIdentity, resolveContextLoader } from "./context-loader.js";
 import { WarbleCommandFailedError } from "./errors.js";
 import { hashDirectory, hashFiles } from "./fingerprint.js";
 import { resolveHubDir, resolveWarbleBinary } from "./resolve-binary.js";
 import { getWarbleIdentity } from "./warble-identity.js";
+import { planDigest, VERCEL_HOST_CONTRACT } from "../components/plan.js";
 /** Fixed `providerFragmentHash` for `"native"` mode, which never reads `--provider` fragments at all. */
 const NATIVE_MODE_PROVIDER_HASH = "native:no-providers";
+/**
+ * Fixed `contextLoaderIdentity` for `compileRawProfile`, which compiles a raw-source binding and so
+ * never runs the `wren-context-loader` generator. A sentinel rather than an empty string, for the
+ * same reason `NATIVE_MODE_PROVIDER_HASH` is one: "the generator was not involved" is a distinct
+ * fact, not an alias for some generator that happened to hash to nothing.
+ */
+const RAW_PROFILE_CONTEXT_LOADER_IDENTITY = "raw-profile:no-context-loader";
 /**
  * This package's bundled wren capability-provider fragment (`providers/wren.provider.yaml`) — the
  * default `--provider` for in-process dispatch, matching how `fixtures/genbi-default.native.bundle.json`
@@ -29,6 +38,13 @@ const WARBLE_COMMAND_TIMEOUT_MS = 2 * 60 * 1000;
  * mode — additionally `warble dispatch --target vercel` for the vercel bundle this package's
  * `runAgent()` consumes.
  *
+ * The rebind runs WrenAI's own `wren-context-loader` generator over `userProject` and binds its
+ * output as a `kind: prepared` document, so Warble reads a projection WrenAI produced rather than
+ * introspecting the semantic layer itself. Resolving that generator loud-fails
+ * ({@link ContextLoaderNotFoundError}) — there is no fallback to Warble's built-in `wren_project`
+ * adapter, because the compiled IR is byte-identical either way and a silent degrade would be
+ * undetectable from the artifact.
+ *
  * A cache hit (see below) never *executes* `warble`, but by default DOES need to resolve + read
  * the binary — its content hash and the Hub root derived from its location are both cache-key
  * inputs (see `warbleIdentity` and `hubDir` below), so a hit can't be trusted without knowing which
@@ -43,13 +59,14 @@ const WARBLE_COMMAND_TIMEOUT_MS = 2 * 60 * 1000;
  * the same no-shell, structured-result `execFile` convention `harness/exec/local.ts` already uses.
  *
  * Results are cached on (profile content hash x user-context fingerprint x mode x resolved
- * provider-fragment content hash x warble binary identity x resolved Hub root) — see `./cache.js` —
- * so an unchanged profile/context/providers/compiler/Hub tuple returns the previous artifact
- * instead of recompiling. Folding in the provider-fragment hash, warble identity and Hub root
- * (rather than just profile+context+mode) matters: otherwise a custom `options.providers` and this
- * package's default fragment collide on the same key, and editing a provider fragment, rebuilding
- * `warble`, or compiling against a different component library would keep serving a stale artifact
- * forever, since there's no TTL/eviction.
+ * provider-fragment content hash x warble binary identity x `wren-context-loader` binary identity x
+ * resolved Hub root) — see `./cache.js` — so an unchanged profile/context/providers/compiler/
+ * generator/Hub tuple returns the previous artifact instead of recompiling. Folding in the
+ * provider-fragment hash, warble identity, generator identity and Hub root (rather than just
+ * profile+context+mode) matters: otherwise a custom `options.providers` and this package's default
+ * fragment collide on the same key, and editing a provider fragment, rebuilding `warble`, rebuilding
+ * the generator, or compiling against a different component library would keep serving a stale
+ * artifact forever, since there's no TTL/eviction.
  *
  * The `warble` invocations run inside a temporary scratch directory (the composed profile + raw
  * compiler output). When the cache relocates the artifacts to a durable home outside that scratch
@@ -60,10 +77,21 @@ const WARBLE_COMMAND_TIMEOUT_MS = 2 * 60 * 1000;
  * a caller-supplied `workDir` is never deleted.
  */
 export async function compileProfile(options) {
-    return compileProfileSource(options, await hashDirectory(path.resolve(options.userProject)), (workDir) => composeUserProfile({
+    // Resolving the generator is memoized here the same way `ensureWarbleBin` memoizes warble below:
+    // both the identity computation (a cache-key input) and the compose step (on a miss) need it, and
+    // resolution loud-fails rather than degrading to Warble's built-in adapter.
+    let resolvedLoader;
+    const ensureContextLoader = () => {
+        resolvedLoader ??= resolveContextLoader(options.contextLoaderBin);
+        return resolvedLoader;
+    };
+    return compileProfileSource(options, 
+    // The compiled binding embeds the absolute project path, even for identical bytes.
+    planDigest({ project: path.resolve(options.userProject), content: await hashDirectory(path.resolve(options.userProject)) }), async () => options.contextLoaderIdentity ?? getContextLoaderIdentity(ensureContextLoader()), (workDir) => composeUserProfile({
         profileSource: options.profileSource,
         userProject: options.userProject,
         destDir: workDir,
+        contextLoaderBin: ensureContextLoader().bin,
     }));
 }
 /**
@@ -73,13 +101,18 @@ export async function compileProfile(options) {
  * the entry whenever the source profile changes.
  */
 export async function compileRawProfile(options) {
-    return compileProfileSource(options, "raw-profile-context", async () => path.resolve(options.profileSource));
+    return compileProfileSource(options, "raw-profile-context", async () => RAW_PROFILE_CONTEXT_LOADER_IDENTITY, async () => path.resolve(options.profileSource));
 }
-async function compileProfileSource(options, contextFingerprint, prepareProfile) {
+async function compileProfileSource(options, contextFingerprint, 
+/**
+ * Deferred so `compileRawProfile` never resolves a generator it has no use for, and so the
+ * `contextLoaderIdentity` escape hatch can still skip touching the binary on a hit.
+ */
+contextLoaderIdentityOf, prepareProfile) {
     const cache = options.cache ?? createFileSystemCompileCache();
     const profileHash = await hashDirectory(path.resolve(options.profileSource));
     const providerPaths = options.providers ?? [DEFAULT_WREN_PROVIDER_PATH];
-    const providerFragmentHash = options.mode === "agnostic" ? await hashFiles(providerPaths) : NATIVE_MODE_PROVIDER_HASH;
+    const providerFragmentHash = options.mode === "agnostic" ? `${await hashFiles(providerPaths)}:${planDigest(VERCEL_HOST_CONTRACT)}` : NATIVE_MODE_PROVIDER_HASH;
     // Resolving `warble` is memoized here so it happens at most once per call no matter how many of
     // the two spots below need it (identity computation, and — on a miss — actually running it).
     let resolvedWarbleBin;
@@ -101,7 +134,16 @@ async function compileProfileSource(options, contextFingerprint, prepareProfile)
     // without resolving the binary. `undefined` here means no `--hub-dir` is passed at all and
     // warble's compiled-in default applies — today's behaviour, preserved.
     const hubDir = options.hubDir ?? resolveHubDir(await ensureWarbleBin());
-    const cacheKey = { profileHash, contextFingerprint, mode: options.mode, providerFragmentHash, warbleIdentity, hubDir };
+    const contextLoaderIdentity = await contextLoaderIdentityOf();
+    const cacheKey = {
+        profileHash,
+        contextFingerprint,
+        mode: options.mode,
+        providerFragmentHash,
+        warbleIdentity,
+        contextLoaderIdentity,
+        hubDir,
+    };
     const cached = await cache.get(cacheKey);
     if (cached !== undefined) {
         return { ...cached, cacheHit: true, ...(resolvedWarbleBin !== undefined ? { warbleBin: resolvedWarbleBin } : {}) };
@@ -126,7 +168,13 @@ async function compileProfileSource(options, contextFingerprint, prepareProfile)
         if (options.mode === "agnostic") {
             const bundleOutDir = path.join(workDir, "bundle");
             const providerArgs = providerPaths.flatMap((provider) => ["--provider", provider]);
-            await runWarble(warbleBin, ["dispatch", "--target", "vercel", ...providerArgs, irPath, "--out", bundleOutDir]);
+            const ir = JSON.parse(await readFile(irPath, "utf8"));
+            const composed = ir.components.some((component) => component.llm_calls.some((step) => (step.component_calls?.length ?? 0) > 0));
+            const hostPath = path.join(workDir, "component-host.json");
+            if (composed)
+                await writeFile(hostPath, JSON.stringify(VERCEL_HOST_CONTRACT), { mode: 0o600 });
+            await runWarble(warbleBin, ["dispatch", "--target", "vercel", ...providerArgs,
+                ...(composed ? ["--host-contract", hostPath] : []), irPath, "--out", bundleOutDir]);
             bundlePath = path.join(bundleOutDir, "bundle.json");
         }
         const freshEntry = { irPath, ...(bundlePath !== undefined ? { bundlePath } : {}) };

package/dist-server/harness/compile/resolve-binary.d.ts

@@ -46,8 +46,8 @@ export declare function resolveWarbleBinary(explicit?: string): Promise<string>;
  * 1. The binary's own checkout — a `<root>/target/release/warble` puts the Hub at
  *    `<root>/hub/components`. Skipped for a bare `"warble"` resolved off `PATH`, which names no
  *    directory to walk up from.
- * 2. A sibling `warble` checkout's `hub/components`, via the same ancestor walk tier 3 of
- *    {@link resolveWarbleBinary} uses.
+ * 2. A sibling `warble` checkout's `hub/components`, only when the explicit sibling-checkout
+ *    development mode is enabled. An installed release must use its own default Hub.
  *
  * Returns `undefined` when neither resolves; callers then pass no `--hub-dir` at all, leaving
  * today's compiled-in default in charge rather than pointing warble at a directory we guessed.

package/dist-server/harness/compile/resolve-binary.js

@@ -31,6 +31,16 @@ import { isWarbleSiblingCheckoutDevModeEnabled, resolveInstalledPackageBin } fro
  */
 export async function resolveWarbleBinary(explicit) {
     if (explicit !== undefined) {
+        // A value with no path separator is a command name, not a file path, and is
+        // resolved on PATH — the same reading the native-session preflight gives it.
+        // Requiring it to exist relative to the working directory made `"warble"` an
+        // explicit value that could never resolve, while the preflight found it and
+        // reported the producer healthy: one string, two answers.
+        if (!explicit.includes(path.sep) && !path.isAbsolute(explicit)) {
+            if (await isExecutableOnPath(explicit))
+                return explicit;
+            throw new WarbleBinaryNotFoundError([`explicit warbleBin "${explicit}" is not on PATH`]);
+        }
         if (!existsSync(explicit)) {
             throw new WarbleBinaryNotFoundError([`explicit warbleBin "${explicit}" does not exist`]);
         }
@@ -88,8 +98,8 @@ function isExecutableOnPath(bin) {
  * 1. The binary's own checkout — a `<root>/target/release/warble` puts the Hub at
  *    `<root>/hub/components`. Skipped for a bare `"warble"` resolved off `PATH`, which names no
  *    directory to walk up from.
- * 2. A sibling `warble` checkout's `hub/components`, via the same ancestor walk tier 3 of
- *    {@link resolveWarbleBinary} uses.
+ * 2. A sibling `warble` checkout's `hub/components`, only when the explicit sibling-checkout
+ *    development mode is enabled. An installed release must use its own default Hub.
  *
  * Returns `undefined` when neither resolves; callers then pass no `--hub-dir` at all, leaving
  * today's compiled-in default in charge rather than pointing warble at a directory we guessed.
@@ -103,7 +113,7 @@ export function resolveHubDir(warbleBin) {
         if (existsSync(candidate))
             return candidate;
     }
-    return findSiblingWarbleEntry("hub", "components");
+    return isWarbleSiblingCheckoutDevModeEnabled() ? findSiblingWarbleEntry("hub", "components") : undefined;
 }
 /**
  * Walks up from this package's own directory (`harness/compile/` in source, `dist/compile/` once

package/dist-server/harness/compile/types.d.ts

@@ -26,6 +26,20 @@ export interface CompileCacheKey {
      * compiled, instead of silently serving an artifact built by a now-stale `warble`.
      */
     readonly warbleIdentity: string;
+    /**
+     * Content identity of the resolved `wren-context-loader` binary — the generator that renders the
+     * user's semantic layer into the prepared-context document a `kind: prepared` binding reads (see
+     * `getBinaryIdentity`). Fixed sentinel for `compileRawProfile`, which binds a raw source and never
+     * runs the generator at all.
+     *
+     * This is here for the *generator's* identity, not the project's: `contextFingerprint` already
+     * content-hashes the user project's semantic-layer files, so folding in the generated document
+     * would say nothing new about the project. What it would miss is a changed generator — a new
+     * version that projects the same layer differently (or extracts a facet the old one dropped)
+     * produces a different document, and therefore a different compiled artifact, from byte-identical
+     * project inputs. Same reason `warbleIdentity` is here, one stage earlier in the pipeline.
+     */
+    readonly contextLoaderIdentity: string;
     /**
      * The Hub component-library root passed to `warble compile --hub-dir` (see `resolveHubDir`), or
      * `undefined` when none could be derived and the compile therefore ran against warble's own
@@ -75,6 +89,21 @@ export interface CompileProfileOptions {
      * hit skip touching the binary at all.
      */
     readonly warbleIdentity?: string;
+    /**
+     * Explicit path to the `wren-context-loader` binary. See `resolveContextLoaderBinary` for the
+     * resolution order when omitted (explicit → `WREN_HARNESS_CONTEXT_LOADER_BIN` → in-repo build →
+     * verified exact `@wrenai/context-loader` package → loud failure; there is no fallback to
+     * Warble's built-in `wren_project` adapter).
+     */
+    readonly contextLoaderBin?: string;
+    /**
+     * Precomputed identity for the resolved `wren-context-loader` binary (see
+     * `CompileCacheKey.contextLoaderIdentity`). Same purpose as `warbleIdentity`: without it,
+     * computing the cache key has to resolve and read the generator even for what would otherwise be
+     * a cache hit. Pass this, `warbleIdentity` and `hubDir` together to make a hit touch no binary at
+     * all. Ignored by `compileRawProfile`, which never runs the generator.
+     */
+    readonly contextLoaderIdentity?: string;
     /**
      * Explicit Hub component-library root for `warble compile --hub-dir`. When omitted it is derived
      * from the resolved `warble` binary (see `resolveHubDir`) so the compiler and its Hub always come

package/dist-server/harness/compile/warble-identity.d.ts

@@ -10,3 +10,14 @@
  * override), a cache hit still never *executes* warble, only resolves + reads its file.
  */
 export declare function getWarbleIdentity(binPath: string): Promise<string>;
+/**
+ * The generic form of {@link getWarbleIdentity}: a memoized content hash of any binary whose
+ * identity belongs in the compile cache key. Also used for the `wren-context-loader` generator (see
+ * `CompileCacheKey.contextLoaderIdentity`), which is a compiler of the same kind one stage earlier
+ * — it turns the user's semantic layer into the prepared-context document Warble then compiles.
+ *
+ * Hashes content rather than shelling out for a version string: it needs no subprocess, so folding
+ * a binary's identity into the key never costs an execution, and it catches a rebuild that keeps
+ * the same version number.
+ */
+export declare function getBinaryIdentity(binPath: string): Promise<string>;

package/dist-server/harness/compile/warble-identity.js

@@ -19,6 +19,19 @@ const identityCache = new Map();
  * override), a cache hit still never *executes* warble, only resolves + reads its file.
  */
 export async function getWarbleIdentity(binPath) {
+    return getBinaryIdentity(binPath);
+}
+/**
+ * The generic form of {@link getWarbleIdentity}: a memoized content hash of any binary whose
+ * identity belongs in the compile cache key. Also used for the `wren-context-loader` generator (see
+ * `CompileCacheKey.contextLoaderIdentity`), which is a compiler of the same kind one stage earlier
+ * — it turns the user's semantic layer into the prepared-context document Warble then compiles.
+ *
+ * Hashes content rather than shelling out for a version string: it needs no subprocess, so folding
+ * a binary's identity into the key never costs an execution, and it catches a rebuild that keeps
+ * the same version number.
+ */
+export async function getBinaryIdentity(binPath) {
     const resolved = path.resolve(binPath);
     let cached = identityCache.get(resolved);
     if (cached === undefined) {

package/dist-server/harness/components/ai-step.d.ts

@@ -0,0 +1,4 @@
+import { type LanguageModel } from "ai";
+import type { StepResponse, StepRun } from "./runner.js";
+/** A fresh AI SDK loop for each host-owned step. No caller history or ambient tools. */
+export declare function runAiComponentStep(run: StepRun, model: LanguageModel): Promise<StepResponse>;

package/dist-server/harness/components/ai-step.js

@@ -0,0 +1,40 @@
+import { ToolLoopAgent, isStepCount, jsonSchema, tool } from "ai";
+import { readSlots } from "./egress.js";
+const SINGLE_ANSWER_STEPS = 12;
+/**
+ * Model turns one step may take. A per-slot step gets two turns per slot (a query and one
+ * retry, for a model that issues one tool call per turn) plus four for lookups and the answer.
+ */
+function stepCap(run) {
+    const read = run.perSlot ? readSlots(run) : undefined;
+    const slots = read && !("error" in read) ? read.slots.length : 0;
+    return Math.max(SINGLE_ANSWER_STEPS, 2 * slots + 4);
+}
+/** A fresh AI SDK loop for each host-owned step. No caller history or ambient tools. */
+export async function runAiComponentStep(run, model) {
+    const tools = {};
+    for (const [name, execute] of Object.entries(run.tools)) {
+        const inputSchema = run.toolSchemas[name];
+        if (!inputSchema)
+            throw new Error("Component tool has no closed input schema");
+        tools[name] = tool({ description: run.toolDescriptions[name] ?? name,
+            inputSchema: jsonSchema(inputSchema),
+            execute: async (input) => execute(input), });
+    }
+    const prompt = JSON.stringify({ request: run.request, input: run.input, consumes: run.consumes });
+    const agent = new ToolLoopAgent({ model, tools, stopWhen: isStepCount(stepCap(run)),
+        instructions: [run.brief, run.prompt].filter(Boolean).join("\n\n"),
+    });
+    const result = await agent.generate({ prompt, abortSignal: run.signal });
+    const toolErrors = result.steps.some((step) => step.content.some((part) => part.type === "tool-error"));
+    // A single-answer step fails on any tool error, so the declared repair step runs and an
+    // unrepaired failure ends the child. In a per-slot invocation a tool error is one slot's
+    // outcome (the model reports it as `{slot_id, status: "unanswerable"}` and answers the rest);
+    // the step itself fails only when the loop did not complete. Normalization still grounds
+    // every answered slot in an observed query, so the leniency cannot promote a claim to data.
+    return {
+        value: result.text,
+        failed: result.finishReason !== "stop" || (!run.perSlot && toolErrors),
+        usage: { inputTokens: result.totalUsage.inputTokens ?? 0, outputTokens: result.totalUsage.outputTokens ?? 0 },
+    };
+}

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

@@ -0,0 +1,60 @@
+import type { ComponentEvidence, ComponentPlan, ExecutionPlan, RunnerHost, StepResponse, StepRun } from "./runner.js";
+import type { ComponentInvocationResult } from "@warble/claude-agent-sdk";
+/** Captured by the host from its project, session and approved runtime records. */
+export interface ComponentIdentity {
+    readonly session: string;
+    readonly vendor: string;
+    readonly account: string;
+    readonly generation: string;
+    readonly project: string;
+    readonly bindingRevision: string;
+    readonly contextDigest: string;
+    readonly planDigest: string;
+}
+export interface ComponentAccess {
+    /** Must execute against the captured project and enforce read-only access. */
+    query(input: {
+        sql: string;
+        limit: number;
+    }, signal: AbortSignal): Promise<unknown>;
+    inspect(signal: AbortSignal): Promise<unknown>;
+    close(): Promise<void>;
+}
+/** Which host context a step receives: the full prepared snapshot (private zone) or the capability card (public zone). */
+export interface ContextSurface {
+    readonly kind: "snapshot" | "card";
+    readonly text: string;
+}
+/** The step run as the host's `step` sees it: the assembled prompt plus its named parts for fingerprinting. */
+export type BrokeredStepRun = StepRun & {
+    /** Named prompt parts exactly as assembled into `prompt`, for the per-surface fingerprint (per surface and in total). Absent when a host bypasses the broker. */
+    readonly surfaces?: Readonly<Record<string, string>>;
+    readonly contextKind?: ContextSurface["kind"] | "none";
+};
+export interface ComponentBrokerOptions {
+    readonly plan: ExecutionPlan;
+    /** Fresh snapshots captured from the same project binding used by prepare(). */
+    readonly contexts: Readonly<Record<string, {
+        binding: Readonly<Record<string, unknown>>;
+        snapshot: unknown;
+    }>>;
+    readonly verifierBinary: string;
+    readonly identity: ComponentIdentity;
+    readonly currentIdentity: () => ComponentIdentity | undefined;
+    /** Opens the exact model/tool authority represented by the verified host context. */
+    readonly prepare: (component: ComponentPlan, identity: ComponentIdentity, signal: AbortSignal) => Promise<ComponentAccess>;
+    readonly step: (run: BrokeredStepRun, component: ComponentPlan, identity: ComponentIdentity) => Promise<StepResponse>;
+    /**
+     * Chooses the host context surface for one step. Default: the component's prepared snapshot.
+     * A zone-aware host returns the capability card for public-zone steps so the snapshot never
+     * reaches a public model.
+     */
+    readonly contextSurface?: (component: ComponentPlan, run: StepRun) => ContextSurface | undefined;
+    readonly normalize: (component: ComponentPlan, evidence: ComponentEvidence, signal: AbortSignal, context: unknown) => Promise<ComponentInvocationResult>;
+    readonly persistRoot?: RunnerHost["persistRoot"];
+    /** The egress verification seam; see `RunnerHost.verifyChild`. */
+    readonly verifyChild?: RunnerHost["verifyChild"];
+    readonly onEvent?: RunnerHost["onEvent"];
+}
+/** Typed host access only: models cannot supply paths, connection config, identity or commands. */
+export declare function createComponentBroker(options: ComponentBrokerOptions): RunnerHost;

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

@@ -0,0 +1,117 @@
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { planDigest } from "./plan.js";
+import { verifyComponentContext } from "./context.js";
+const queryInput = z.object({ sql: z.string().trim().min(1).max(65_536), limit: z.number().int().positive().optional() }).strict();
+const emptyInput = z.object({}).strict();
+const QUERY_SCHEMA = { type: "object", additionalProperties: false, required: ["sql"], properties: {
+        sql: { type: "string", minLength: 1, maxLength: 65_536 }, limit: { type: "integer", minimum: 1 },
+    } };
+const INSPECT_SCHEMA = { type: "object", additionalProperties: false, properties: {} };
+/** Typed host access only: models cannot supply paths, connection config, identity or commands. */
+export function createComponentBroker(options) {
+    const identity = Object.freeze({ ...options.identity });
+    if (Object.values(identity).some((value) => !value.trim()))
+        throw new Error("Missing component execution identity");
+    const plan = structuredClone(options.plan);
+    const contexts = structuredClone(options.contexts);
+    if (identity.planDigest !== plan.identity || identity.contextDigest !== planDigest(contexts))
+        throw new Error("Component plan/context identity mismatch");
+    const owners = new WeakMap();
+    const current = () => isDeepStrictEqual(identity, options.currentIdentity());
+    const check = (signal) => { signal.throwIfAborted(); if (!current())
+        throw new Error("Component binding expired"); };
+    return {
+        async prepare(component, signal) {
+            check(signal);
+            if (!isDeepStrictEqual(plan.components[component.id], component))
+                throw new Error("Component plan mismatch");
+            const context = contexts[component.id];
+            if (context && !isDeepStrictEqual(context.binding, component.declaration.context_binding))
+                throw new Error("Component context binding mismatch");
+            const conditions = component.declaration.context_precondition;
+            if (conditions !== undefined && !Array.isArray(conditions))
+                throw new Error("Invalid component preconditions");
+            if (Array.isArray(conditions) && conditions.length > 0) {
+                if (!context)
+                    throw new Error("Missing component context");
+                await verifyComponentContext(options.verifierBinary, context.snapshot, conditions, signal);
+            }
+            check(signal);
+            const guards = z.array(z.object({ name: z.string(), locked: z.boolean(), threshold: z.number().positive().optional() }).passthrough()).parse(component.declaration.guardrails);
+            if (!guards.some((guard) => guard.name === "read_only_execution" && guard.locked))
+                throw new Error("Component read-only guard is required");
+            const rowLimit = Math.min(10_000, guards.find((guard) => guard.name === "row_limit")?.threshold ?? 1000);
+            const timeoutMs = Math.min(120_000, (guards.find((guard) => guard.name === "statement_timeout")?.threshold ?? 30) * 1000);
+            const grants = [...new Map(component.steps.flatMap((step) => step.tools).map((grant) => [`${grant.source}:${grant.name}`, grant])).values()];
+            const operations = grants.map((grant) => {
+                if ((grant.source === "native" && grant.name === "query") || grant.source === "host:sql_execution:read_only")
+                    return "query";
+                if ((grant.source === "native" && grant.name === "semantic_introspect") || grant.source === "host:semantic_introspection")
+                    return "inspect";
+                throw new Error("Unsupported component tool binding");
+            });
+            const access = await options.prepare(component, identity, signal);
+            let closed = false;
+            let closing;
+            const close = () => { closed = true; return closing ??= access.close(); };
+            try {
+                check(signal);
+            }
+            catch (error) {
+                await close();
+                throw error;
+            }
+            const binding = {
+                isCurrent: current, close,
+                tools: grants.map((grant, index) => ({ ...grant,
+                    inputSchema: operations[index] === "query" ? QUERY_SCHEMA : INSPECT_SCHEMA,
+                    async execute(input, parent) {
+                        check(parent);
+                        if (closed)
+                            throw new Error("Component access is closed");
+                        const bounded = AbortSignal.any([parent, AbortSignal.timeout(timeoutMs)]);
+                        let result;
+                        if (operations[index] === "query") {
+                            const parsed = queryInput.parse(input);
+                            result = await access.query({ sql: parsed.sql, limit: Math.min(rowLimit, parsed.limit ?? rowLimit) }, bounded);
+                        }
+                        else {
+                            emptyInput.parse(input);
+                            result = await access.inspect(bounded);
+                        }
+                        check(bounded);
+                        if (closed)
+                            throw new Error("Component access is closed");
+                        return result;
+                    },
+                })),
+                async normalize(evidence, parent) { check(parent); if (closed)
+                    throw new Error("Component access is closed"); return options.normalize(component, evidence, parent, structuredClone(context?.snapshot)); },
+            };
+            owners.set(binding, component);
+            return binding;
+        },
+        async runStep(run, binding) {
+            check(run.signal);
+            const component = owners.get(binding);
+            if (!component || !binding.isCurrent())
+                throw new Error("Invalid component binding");
+            const context = contexts[component.id];
+            const render = z.object({ render_blocks: z.array(z.object({ type: z.string(), fields: z.record(z.string(), z.string()) }).strict()).optional() }).passthrough().parse(component.declaration.effect ?? {}).render_blocks;
+            const surface = options.contextSurface ? options.contextSurface(component, run)
+                : context ? { kind: "snapshot", text: `Host semantic context:\n${JSON.stringify(context.snapshot)}` } : undefined;
+            const renderText = run.terminal && render?.length ? `Render output: Return only one JSON object with a blocks array. Each block has a type and its declared fields. Use only these block contracts (a trailing ? means optional): ${JSON.stringify(render)}. Copy data and definitions only from successful host tool or child results. A KPI label must identify its returned column; do not invent units or deltas. If evidence is insufficient, return {"status":"refused","message":"Insufficient verified data"}.` : "";
+            const surfaces = { prompt: run.prompt };
+            if (surface)
+                surfaces["context"] = surface.text;
+            if (renderText)
+                surfaces["render"] = renderText;
+            const prompt = [run.prompt, surface?.text ?? "", renderText].filter(Boolean).join("\n\n");
+            return options.step({ ...run, prompt, surfaces: Object.freeze(surfaces), contextKind: surface?.kind ?? "none" }, component, identity);
+        },
+        ...(options.persistRoot ? { persistRoot: options.persistRoot } : {}),
+        ...(options.verifyChild ? { verifyChild: options.verifyChild } : {}),
+        ...(options.onEvent ? { onEvent: options.onEvent } : {}),
+    };
+}

package/dist-server/harness/components/capability-card.d.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import type { DisclosurePolicy } from "../providers/zone.js";
+/** The catalog fields the card may read. Everything else the document carries is dropped here. */
+export declare const capabilityCatalogSchema: z.ZodObject<{
+    catalog_version: z.ZodLiteral<1>;
+    project: z.ZodDefault<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        data_source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    models: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        primary_key: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        columns: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodString;
+            not_null: z.ZodOptional<z.ZodBoolean>;
+            is_calculated: z.ZodOptional<z.ZodBoolean>;
+            is_hidden: z.ZodOptional<z.ZodBoolean>;
+            relationship: z.ZodOptional<z.ZodString>;
+            enum_values: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                meaning: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    relationships: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        models: z.ZodArray<z.ZodString>;
+        join_type: z.ZodString;
+        condition: z.ZodString;
+    }, z.core.$strip>>>;
+    cubes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        base_object: z.ZodString;
+        measures: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodString;
+            granularities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            date_range: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+        }, z.core.$strip>>>;
+        dimensions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodString;
+            granularities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            date_range: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+        }, z.core.$strip>>>;
+        time_dimensions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodString;
+            granularities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            date_range: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    views: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CapabilityCatalog = z.infer<typeof capabilityCatalogSchema>;
+export interface CapabilityCard {
+    readonly text: string;
+    readonly bytes: number;
+    readonly truncated: boolean;
+    /** sha256 hex over `text`; the value a public step's `context` surface fingerprint carries when it received the card. */
+    readonly digest: string;
+    /** Lines dropped by the size bound, for the trace warning. */
+    readonly omittedLines: number;
+}
+/** The disclosure-policy fields the card may carry. Nothing else of the policy is read. */
+export type CardDisclosureLimits = Pick<DisclosurePolicy, "min_group_size" | "max_rows" | "allowed_shapes">;
+export interface CapabilityCardOptions {
+    /** Upper bound on the rendered card in UTF-8 bytes. Default 32 KiB. */
+    readonly maxBytes?: number;
+    /**
+     * The bound disclosure policy, when there is one. The card states its shape limits so the
+     * planner plans within them instead of planning slots egress then refuses. Only the three
+     * fields of `CardDisclosureLimits` are read; patterns and the judge budget never reach the card.
+     */
+    readonly disclosure?: CardDisclosureLimits;
+}
+export declare const DEFAULT_CARD_MAX_BYTES: number;
+/** Renders the card's lines from an already allow-listed catalog. Pure and order-preserving. */
+export declare function renderCapabilityCardLines(catalog: CapabilityCatalog, disclosure?: CardDisclosureLimits): string[];
+/**
+ * Builds the card from a raw catalog document. Deterministic: the same
+ * catalog yields the same bytes. Size-bounded: when the rendering exceeds
+ * `maxBytes`, trailing lines are dropped until it fits and a marker line
+ * says how many were omitted; the caller traces that as a warning. The
+ * disclosure limits are never dropped: with a policy bound, the whole head
+ * is kept even when that alone exceeds `maxBytes`.
+ */
+export declare function buildCapabilityCard(catalog: unknown, options?: CapabilityCardOptions): CapabilityCard;