@wrenai/genbi 0.0.4 → 0.0.5

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

@@ -0,0 +1,14 @@
+import type { LanguageModel } from "ai";
+import type { UsageRecord, UsageTrace } from "../events/types.js";
+export interface StepUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+/** Provider-reported counts; a missing or malformed count is recorded as zero, never omitted. */
+export declare function reportedUsage(usage: {
+    readonly inputTokens?: number | undefined;
+    readonly outputTokens?: number | undefined;
+} | undefined): StepUsage;
+export declare function modelIdOf(model: LanguageModel): string;
+/** Per-step records plus their totals per provider, in first-seen order. */
+export declare function summariseUsage(records: readonly UsageRecord[]): UsageTrace;

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

@@ -0,0 +1,19 @@
+/** Provider-reported counts; a missing or malformed count is recorded as zero, never omitted. */
+export function reportedUsage(usage) {
+    const count = (value) => value !== undefined && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+    return { inputTokens: count(usage?.inputTokens), outputTokens: count(usage?.outputTokens) };
+}
+export function modelIdOf(model) {
+    return typeof model === "string" ? model : model.modelId;
+}
+/** Per-step records plus their totals per provider, in first-seen order. */
+export function summariseUsage(records) {
+    const providers = new Map();
+    for (const record of records) {
+        const key = JSON.stringify([record.zone, record.adapter, record.model]);
+        const total = providers.get(key) ?? { zone: record.zone, adapter: record.adapter, model: record.model, calls: 0, inputTokens: 0, outputTokens: 0 };
+        providers.set(key, { ...total, calls: total.calls + 1,
+            inputTokens: total.inputTokens + record.inputTokens, outputTokens: total.outputTokens + record.outputTokens });
+    }
+    return { steps: [...records], providers: [...providers.values()] };
+}

package/dist-server/harness/components/wren-access.d.ts

@@ -0,0 +1,29 @@
+import type { ComponentAccess } from "./broker.js";
+/**
+ * The closed vocabulary of governed query failures a model may see. The wire carries the
+ * class; the sentence shown to the model is owned here, so nothing a `wren` process writes
+ * (exception text, SQL, paths, credentials) can reach a model even if that process is stale
+ * or compromised. `transport` is host-only: the channel itself failed or closed.
+ */
+export declare const GOVERNED_ERROR_CLASSES: readonly ["invalid_request", "model_not_found", "policy_rejected", "invalid_sql", "execution_failed", "timeout", "datasource_unavailable", "result_too_large", "internal", "transport"];
+export type GovernedErrorClass = (typeof GOVERNED_ERROR_CLASSES)[number];
+export declare class GovernedWrenError extends Error {
+    readonly errorClass: GovernedErrorClass;
+    constructor(errorClass: GovernedErrorClass);
+}
+export interface WrenAccessIdentity {
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+    readonly digest: string;
+    assertCurrent(): Promise<void>;
+}
+/** Capture once per root, before preparing any component. Secrets never leave the host. */
+export declare function captureWrenAccessIdentity(project: string, source?: NodeJS.ProcessEnv): Promise<WrenAccessIdentity>;
+/** One owned process captures the project model, policy and credentials once. */
+export declare function openWrenComponentAccess(options: {
+    readonly executable: string;
+    readonly project: string;
+    readonly fingerprint: string;
+    readonly signal: AbortSignal;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly identity?: WrenAccessIdentity;
+}): Promise<ComponentAccess>;

package/dist-server/harness/components/wren-access.js

@@ -0,0 +1,233 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { hashDirectory } from "../compile/fingerprint.js";
+/**
+ * The closed vocabulary of governed query failures a model may see. The wire carries the
+ * class; the sentence shown to the model is owned here, so nothing a `wren` process writes
+ * (exception text, SQL, paths, credentials) can reach a model even if that process is stale
+ * or compromised. `transport` is host-only: the channel itself failed or closed.
+ */
+export const GOVERNED_ERROR_CLASSES = ["invalid_request", "model_not_found", "policy_rejected", "invalid_sql", "execution_failed",
+    "timeout", "datasource_unavailable", "result_too_large", "internal", "transport"];
+const GOVERNED_ERROR_TEXT = Object.freeze({
+    invalid_request: "The request did not match the governed operation contract.",
+    model_not_found: "The query references a table that is not a model in the bound semantic context; query only the models it defines.",
+    policy_rejected: "The read-only analytical policy rejected the query: use one SELECT over the bound models with standard analytical functions only.",
+    invalid_sql: "The SQL could not be parsed or planned against the semantic context.",
+    execution_failed: "The data source rejected the query at execution time, for example an unknown column or a type mismatch.",
+    timeout: "The query exceeded the statement time limit.",
+    datasource_unavailable: "The bound data source could not be reached.",
+    result_too_large: "The result exceeded the governed byte limit; narrow the query.",
+    internal: "The governed operation failed for an unclassified reason.",
+    transport: "Governed Wren operation is unavailable.",
+});
+export class GovernedWrenError extends Error {
+    errorClass;
+    constructor(errorClass) {
+        super(`Governed Wren query failed [${errorClass}]: ${GOVERNED_ERROR_TEXT[errorClass]}`);
+        this.errorClass = errorClass;
+        this.name = "GovernedWrenError";
+    }
+}
+/** Only the class crosses; a message from the wire is never forwarded, and an unknown class is `internal`. */
+function governedError(wire) {
+    const named = typeof wire === "string" ? undefined : wire.class;
+    const known = GOVERNED_ERROR_CLASSES.find((candidate) => candidate === named && candidate !== "transport");
+    return new GovernedWrenError(known ?? "internal");
+}
+const PROTOCOLS = ["wren-governed/1", "wren-governed/2"];
+const reply = z.object({ id: z.number().int().nonnegative(), protocol: z.enum(PROTOCOLS).optional(), result: z.unknown().optional(),
+    error: z.union([z.string(), z.object({ class: z.string().min(1).max(64), message: z.string().max(1024) }).strict()]).optional() }).strict();
+/** Capture once per root, before preparing any component. Secrets never leave the host. */
+export async function captureWrenAccessIdentity(project, source = process.env) {
+    const environment = Object.freeze({ ...source });
+    const home = path.resolve(environment.WREN_HOME ?? path.join(environment.HOME ?? os.homedir(), ".wren"));
+    const files = [path.join(project, ".env"), ...[".env", "profiles.yml", "config.json"].map((name) => path.join(home, name))];
+    const fingerprint = async () => {
+        const hash = createHash("sha256").update(JSON.stringify(environment));
+        for (const file of files) {
+            hash.update(file).update("\0");
+            try {
+                hash.update(await realpath(file)).update("\0").update(await readFile(file));
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw new Error("Wren configuration is unavailable");
+                hash.update("absent");
+            }
+        }
+        return hash.digest("hex");
+    };
+    const digest = await fingerprint();
+    return Object.freeze({ environment, digest, async assertCurrent() {
+            if (await fingerprint() !== digest)
+                throw new Error("Wren configuration changed");
+        } });
+}
+/** One owned process captures the project model, policy and credentials once. */
+export async function openWrenComponentAccess(options) {
+    options.signal.throwIfAborted();
+    const identity = options.identity ?? await captureWrenAccessIdentity(options.project, options.environment);
+    const assertProject = async () => {
+        await identity.assertCurrent();
+        if (await hashDirectory(options.project) !== options.fingerprint)
+            throw new Error("Component project changed");
+        options.signal.throwIfAborted();
+    };
+    await assertProject();
+    if (process.platform === "win32")
+        throw new Error("Governed process cleanup is unavailable on this platform");
+    const child = spawn(options.executable, ["governed-stdio", "--project", options.project], {
+        cwd: options.project, env: { ...identity.environment }, detached: true, stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stderr.resume();
+    let closed = false;
+    let closing;
+    let buffer = Buffer.alloc(0);
+    let nextId = 1;
+    let pending;
+    const unavailable = () => new GovernedWrenError("transport");
+    const ready = new Promise((resolve, reject) => { pending = { id: 0, resolve: () => resolve(), reject }; });
+    const signalGroup = (value) => {
+        if (!child.pid)
+            return;
+        try {
+            process.kill(-child.pid, value);
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                throw unavailable();
+        }
+    };
+    const alive = () => {
+        if (!child.pid)
+            return false;
+        try {
+            process.kill(-child.pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code !== "ESRCH";
+        }
+    };
+    const waitGone = async (ms) => {
+        const deadline = performance.now() + ms;
+        while (alive() && performance.now() < deadline)
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        return !alive();
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        closed = true;
+        pending?.reject(unavailable());
+        pending = undefined;
+        closing = (async () => {
+            try {
+                child.stdin.end();
+                if (await waitGone(100))
+                    return;
+                signalGroup("SIGTERM");
+                if (await waitGone(300))
+                    return;
+                signalGroup("SIGKILL");
+                if (!(await waitGone(2000)))
+                    throw new Error("Governed Wren cleanup failed");
+            }
+            finally {
+                options.signal.removeEventListener("abort", abort);
+                child.stdin.destroy();
+                child.stdout.destroy();
+                child.stderr.destroy();
+            }
+        })();
+        return closing;
+    };
+    const abort = () => { void close().catch(() => { }); };
+    options.signal.addEventListener("abort", abort, { once: true });
+    child.on("error", abort);
+    child.on("exit", abort);
+    child.stdin.on("error", abort);
+    child.stdout.on("error", abort);
+    child.stdout.on("data", (chunk) => {
+        if (closed)
+            return;
+        buffer = Buffer.concat([buffer, chunk]);
+        if (buffer.length > 1_048_577) {
+            abort();
+            return;
+        }
+        const newline = buffer.indexOf(10);
+        if (newline < 0)
+            return;
+        try {
+            const value = reply.parse(JSON.parse(buffer.subarray(0, newline).toString("utf8")));
+            buffer = buffer.subarray(newline + 1);
+            if (buffer.length || !pending || value.id !== pending.id)
+                throw unavailable();
+            if (value.id === 0 ? value.protocol === undefined || Object.keys(value).length !== 2
+                : value.protocol !== undefined || (Object.hasOwn(value, "result") === Object.hasOwn(value, "error")))
+                throw unavailable();
+            const waiter = pending;
+            pending = undefined;
+            if (value.error !== undefined)
+                waiter.reject(governedError(value.error));
+            else
+                waiter.resolve(value.result);
+        }
+        catch {
+            abort();
+        }
+    });
+    if (options.signal.aborted)
+        abort();
+    const timer = setTimeout(abort, 10_000);
+    try {
+        await ready;
+        await assertProject();
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let tail = Promise.resolve();
+    const execute = (payload, signal) => {
+        const operation = tail.then(async () => {
+            signal.throwIfAborted();
+            if (closed)
+                throw unavailable();
+            await assertProject();
+            const input = JSON.stringify({ id: nextId, ...payload }) + "\n";
+            if (Buffer.byteLength(input) > 65_536)
+                throw unavailable();
+            const result = new Promise((resolve, reject) => { pending = { id: nextId++, resolve, reject }; });
+            signal.addEventListener("abort", abort, { once: true });
+            if (signal.aborted)
+                abort();
+            else
+                child.stdin.write(input);
+            try {
+                const value = await result;
+                signal.throwIfAborted();
+                await assertProject();
+                return value;
+            }
+            finally {
+                signal.removeEventListener("abort", abort);
+            }
+        });
+        tail = operation.then(() => { }, () => { });
+        return operation;
+    };
+    return {
+        query: (input, signal) => execute({ operation: "query", ...input }, signal),
+        inspect: (signal) => execute({ operation: "inspect" }, signal), close,
+    };
+}

package/dist-server/harness/components/zone-dry-run.d.ts

@@ -0,0 +1,43 @@
+import type { AdapterSpec, TierBinding } from "../providers/binding.js";
+import type { ExecutionPlan } from "./runner.js";
+import { type ZoneGateResult } from "./zone-gate.js";
+export interface AdapterAudit {
+    readonly adapter: string;
+    readonly model: string;
+    readonly endpointHost: string;
+    readonly thinking: "on" | "off" | "unset";
+}
+export interface ZoneDryRunEdge {
+    readonly from: string;
+    readonly alias: string;
+    readonly to: string;
+}
+export interface ZoneDryRunOptions {
+    /** The capability card that public-zone steps would receive, when the project is known. */
+    readonly card?: {
+        readonly digest: string;
+        readonly bytes: number;
+        readonly truncated: boolean;
+    };
+}
+export interface ZoneDryRun {
+    readonly gate: ZoneGateResult;
+    readonly card?: ZoneDryRunOptions["card"];
+    /** Which host context each step would receive: the card on public steps, the snapshot elsewhere. */
+    readonly contexts: Readonly<Record<string, "card" | "snapshot">>;
+    readonly audits: Readonly<Record<string, AdapterAudit>>;
+    readonly edges: readonly ZoneDryRunEdge[];
+    /** 0 when the gate is not armed or found nothing; 1 on any violation. */
+    readonly exitCode: 0 | 1;
+}
+/**
+ * What an audit needs to know about the serving runtime behind a spec,
+ * read from the spec's configuration alone. No adapter is constructed, no
+ * request is made: the dry-run must stay runnable with no network and no
+ * credentials.
+ */
+export declare function auditAdapterSpec(spec: AdapterSpec): AdapterAudit;
+/** Evaluates the gate over the plan and collects everything an audit prints; pure, offline. */
+export declare function describeZoneDryRun(plan: ExecutionPlan, entry: string, binding: TierBinding, options?: ZoneDryRunOptions): ZoneDryRun;
+/** Renders a dry-run as the fixed-width text the CLI prints. */
+export declare function formatZoneDryRun(dryRun: ZoneDryRun): string;

package/dist-server/harness/components/zone-dry-run.js

@@ -0,0 +1,107 @@
+import { evaluateZoneGate } from "./zone-gate.js";
+function readString(record, key) {
+    if (typeof record !== "object" || record === null)
+        return undefined;
+    const value = record[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * What an audit needs to know about the serving runtime behind a spec,
+ * read from the spec's configuration alone. No adapter is constructed, no
+ * request is made: the dry-run must stay runnable with no network and no
+ * credentials.
+ */
+export function auditAdapterSpec(spec) {
+    const config = spec.config;
+    const baseURL = readString(config, "baseURL");
+    let endpointHost = "(adapter default)";
+    if (baseURL !== undefined) {
+        try {
+            endpointHost = new URL(baseURL).host;
+        }
+        catch {
+            endpointHost = `(invalid baseURL: ${baseURL})`;
+        }
+    }
+    else if (spec.adapter === "anthropic") {
+        endpointHost = "api.anthropic.com (adapter default)";
+    }
+    else if (spec.adapter === "openai") {
+        endpointHost = "api.openai.com (adapter default)";
+    }
+    else if (spec.adapter === "mock") {
+        endpointHost = "(none: mock)";
+    }
+    const extraBody = config?.["extraBody"];
+    const kwargs = typeof extraBody === "object" && extraBody !== null ? extraBody["chat_template_kwargs"] : undefined;
+    const enable = typeof kwargs === "object" && kwargs !== null ? kwargs["enable_thinking"] : undefined;
+    return {
+        adapter: spec.adapter,
+        model: readString(config, "model") ?? "(adapter default)",
+        endpointHost,
+        thinking: enable === true ? "on" : enable === false ? "off" : "unset",
+    };
+}
+/** Evaluates the gate over the plan and collects everything an audit prints; pure, offline. */
+export function describeZoneDryRun(plan, entry, binding, options = {}) {
+    const gate = evaluateZoneGate(plan, entry, binding);
+    const contexts = {};
+    for (const report of gate.steps)
+        contexts[`${report.component}.${report.step}`] = gate.armed && report.zone === "public" ? "card" : "snapshot";
+    const audits = {};
+    for (const report of gate.steps)
+        if (report.key !== undefined && report.spec)
+            audits[report.key] = auditAdapterSpec(report.spec);
+    for (const role of gate.roles)
+        if (role.spec)
+            audits[role.key] = auditAdapterSpec(role.spec);
+    const edges = [];
+    for (const report of gate.steps)
+        for (const edge of report.calls)
+            edges.push({ from: `${report.component}.${report.step}`, alias: edge.alias, to: edge.component });
+    return { gate, ...(options.card ? { card: options.card } : {}), contexts, audits, edges, exitCode: gate.armed && gate.violations.length > 0 ? 1 : 0 };
+}
+/** Renders a dry-run as the fixed-width text the CLI prints. */
+export function formatZoneDryRun(dryRun) {
+    const lines = [];
+    const { gate } = dryRun;
+    lines.push(`zone dry-run · entry ${gate.entry} · gate ${gate.armed ? "armed" : "NOT armed (legacy single-zone binding: no zone, disclosure_policy or roles declared)"}`);
+    lines.push("");
+    lines.push("steps");
+    for (const step of gate.steps) {
+        const audit = step.key !== undefined ? dryRun.audits[step.key] : undefined;
+        const where = audit ? `${audit.adapter} model=${audit.model} host=${audit.endpointHost} thinking=${audit.thinking}` : "(unbound)";
+        const tools = step.dataTools.length ? ` tools=${step.dataTools.join(",")}` : "";
+        const context = dryRun.contexts[`${step.component}.${step.step}`] ?? "snapshot";
+        const contextText = context === "card" ? `context=card${dryRun.card ? ` sha256:${dryRun.card.digest}` : ""}` : "context=snapshot";
+        lines.push(`  ${step.component}.${step.step}  role=${step.role}  tier=${step.tier}  key=${step.key ?? "-"}  zone=${step.zone}  ${contextText}  ${where}${tools}`);
+    }
+    if (dryRun.card)
+        lines.push(`  capability card: sha256:${dryRun.card.digest} (${dryRun.card.bytes} bytes${dryRun.card.truncated ? ", truncated" : ""}) — sent to public-zone steps only`);
+    lines.push("");
+    lines.push("call edges");
+    if (dryRun.edges.length === 0)
+        lines.push("  (none)");
+    for (const edge of dryRun.edges)
+        lines.push(`  ${edge.from} --[${edge.alias}]--> ${edge.to}`);
+    lines.push("");
+    lines.push("roles");
+    if (gate.roles.length === 0)
+        lines.push("  (none declared)");
+    for (const role of gate.roles) {
+        const audit = dryRun.audits[role.key];
+        const where = audit ? `${audit.adapter} model=${audit.model} host=${audit.endpointHost} thinking=${audit.thinking}` : "(unbound)";
+        lines.push(`  ${role.role}  key=${role.key}  zone=${role.zone}  ${where}`);
+    }
+    lines.push("");
+    if (!gate.armed)
+        lines.push("result: gate not armed; nothing was checked");
+    else if (gate.violations.length === 0)
+        lines.push("result: ok (no zone violations)");
+    else {
+        lines.push(`result: REJECTED (${gate.violations.length} violation${gate.violations.length === 1 ? "" : "s"})`);
+        for (const violation of gate.violations)
+            lines.push(`  - [${violation.code}] ${violation.message}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist-server/harness/components/zone-gate.d.ts

@@ -0,0 +1,76 @@
+import { type AdapterSpec, type TierBinding } from "../providers/binding.js";
+import type { Zone } from "../providers/zone.js";
+import type { ExecutionPlan } from "./runner.js";
+/** Where a step sits in the composition as seen from one entry. */
+export type ZoneStepRole = "caller" | "callee";
+export interface ZoneStepReport {
+    readonly component: string;
+    readonly step: string;
+    readonly tier: string;
+    readonly role: ZoneStepRole;
+    /** The binding key that bound this (mount, tier); undefined when nothing did. */
+    readonly key?: string;
+    readonly spec?: AdapterSpec;
+    readonly zone: Zone | "unbound";
+    /** Data-bearing tool grants on the step (query / semantic_introspect). */
+    readonly dataTools: readonly string[];
+    readonly calls: readonly {
+        readonly alias: string;
+        readonly component: string;
+    }[];
+}
+export interface ZoneRoleReport {
+    readonly role: "judge" | "render";
+    readonly key: string;
+    readonly spec?: AdapterSpec;
+    readonly zone: Zone | "unbound";
+}
+export type ZoneGateViolationCode = "callee_public" | "data_step_public" | "missing_zone" | "unbound_tier" | "judge_public" | "render_public" | "missing_judge" | "missing_policy" | "render_unbound";
+export interface ZoneGateViolation {
+    readonly code: ZoneGateViolationCode;
+    readonly component?: string;
+    readonly step?: string;
+    readonly tier: string;
+    readonly zone: Zone | "unbound";
+    readonly message: string;
+}
+export interface ZoneGateResult {
+    /** False for a legacy single-zone binding: nothing was checked and nothing is claimed. */
+    readonly armed: boolean;
+    readonly entry: string;
+    readonly steps: readonly ZoneStepReport[];
+    readonly roles: readonly ZoneRoleReport[];
+    readonly violations: readonly ZoneGateViolation[];
+}
+export declare class ZoneGateError extends Error {
+    readonly violations: readonly ZoneGateViolation[];
+    constructor(violations: readonly ZoneGateViolation[]);
+}
+/** The mounts reachable from `entry`, in first-visit order; the entry itself is first. */
+export declare function reachableMounts(plan: ExecutionPlan, entry: string): string[];
+/**
+ * The zone gate: a pure function over (plan, binding) that decides whether a
+ * binding may run a composition at all. Enforced at binding time, before any
+ * model, tool or child session starts; a violation is a loud failure, never a
+ * degrade.
+ *
+ * Rules, keyed on (mount, tier):
+ * 1. every step of a callee mount (reached through a call edge) resolves to `zone: private`;
+ * 2. every step that holds a data tool grant resolves to `zone: private`, whatever its mount;
+ * 3. the `judge` role tier, when declared, is private; a disclosure policy without a judge fails;
+ * 4. the `render` role tier, when declared, is private;
+ * 5. a tier referenced by any of the above without a `zone` fails — no default zone;
+ * 6. a caller step without data tools may be public, private, or leave zone unset;
+ * 7. a public (or zone-unset) caller step that calls a callee needs a `disclosure_policy`,
+ *    because that is the only way child results are verified before they cross;
+ * 8. an entry that renders a contract must name `roles.render` explicitly whenever the stage's
+ *    default tier (the entry's last independent step, which is where `render/envelope.ts`
+ *    would run a render model) is not private: rows reach the render stage, so leaving it on an
+ *    inherited public tier is rejected rather than assumed.
+ *
+ * A binding with no zone information anywhere is not zone-aware: the gate is
+ * not armed and the result carries no violations, only the step report.
+ */
+export declare function evaluateZoneGate(plan: ExecutionPlan, entry: string, binding: TierBinding): ZoneGateResult;
+/** Runs the gate and throws {@link ZoneGateError} when an armed gate finds any violation. */
+export declare function assertZoneGate(plan: ExecutionPlan, entry: string, binding: TierBinding): ZoneGateResult;

package/dist-server/harness/components/zone-gate.js

@@ -0,0 +1,144 @@
+import { isZoneAwareBinding, resolveTierSpec } from "../providers/binding.js";
+export class ZoneGateError extends Error {
+    violations;
+    constructor(violations) {
+        super(`zone gate rejected the binding:\n${violations.map((violation) => `  - ${violation.message}`).join("\n")}`);
+        this.violations = violations;
+        this.name = "ZoneGateError";
+    }
+}
+/** The mounts reachable from `entry`, in first-visit order; the entry itself is first. */
+export function reachableMounts(plan, entry) {
+    const closure = [];
+    const seen = new Set();
+    const visit = (id) => {
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        closure.push(id);
+        const node = plan.components[id];
+        if (!node)
+            throw new Error(`zone gate: plan has no component "${id}"`);
+        for (const step of node.steps)
+            for (const edge of step.calls)
+                visit(edge.component);
+    };
+    visit(entry);
+    return closure;
+}
+function dataToolNames(step) {
+    return step.tools.map((tool) => tool.name);
+}
+/**
+ * The zone gate: a pure function over (plan, binding) that decides whether a
+ * binding may run a composition at all. Enforced at binding time, before any
+ * model, tool or child session starts; a violation is a loud failure, never a
+ * degrade.
+ *
+ * Rules, keyed on (mount, tier):
+ * 1. every step of a callee mount (reached through a call edge) resolves to `zone: private`;
+ * 2. every step that holds a data tool grant resolves to `zone: private`, whatever its mount;
+ * 3. the `judge` role tier, when declared, is private; a disclosure policy without a judge fails;
+ * 4. the `render` role tier, when declared, is private;
+ * 5. a tier referenced by any of the above without a `zone` fails — no default zone;
+ * 6. a caller step without data tools may be public, private, or leave zone unset;
+ * 7. a public (or zone-unset) caller step that calls a callee needs a `disclosure_policy`,
+ *    because that is the only way child results are verified before they cross;
+ * 8. an entry that renders a contract must name `roles.render` explicitly whenever the stage's
+ *    default tier (the entry's last independent step, which is where `render/envelope.ts`
+ *    would run a render model) is not private: rows reach the render stage, so leaving it on an
+ *    inherited public tier is rejected rather than assumed.
+ *
+ * A binding with no zone information anywhere is not zone-aware: the gate is
+ * not armed and the result carries no violations, only the step report.
+ */
+export function evaluateZoneGate(plan, entry, binding) {
+    const armed = isZoneAwareBinding(binding);
+    const mounts = reachableMounts(plan, entry);
+    const steps = [];
+    const violations = [];
+    for (const mount of mounts) {
+        const node = plan.components[mount];
+        const role = mount === entry ? "caller" : "callee";
+        for (const step of node.steps) {
+            const resolved = resolveTierSpec(binding, step.tier, mount);
+            const zone = resolved?.spec.zone ?? "unbound";
+            const report = { component: mount, step: step.name, tier: step.tier, role,
+                ...(resolved ? { key: resolved.key, spec: resolved.spec } : {}), zone, dataTools: dataToolNames(step), calls: step.calls };
+            steps.push(report);
+            if (!armed)
+                continue;
+            const where = `step ${mount}.${step.name} (tier ${step.tier})`;
+            if (!resolved) {
+                violations.push({ code: "unbound_tier", component: mount, step: step.name, tier: step.tier, zone,
+                    message: `${where} has no binding entry (looked up ${mount}/${step.tier}, then ${step.tier})` });
+                continue;
+            }
+            const relevant = role === "callee" || report.dataTools.length > 0;
+            if (!relevant)
+                continue;
+            const why = role === "callee" ? "runs inside the callee" : `holds data tools ${report.dataTools.join(", ")}`;
+            if (zone === "unbound") {
+                violations.push({ code: "missing_zone", component: mount, step: step.name, tier: step.tier, zone,
+                    message: `${where} ${why} but binding entry "${resolved.key}" declares no zone` });
+            }
+            else if (zone !== "private") {
+                violations.push({ code: role === "callee" ? "callee_public" : "data_step_public", component: mount, step: step.name, tier: step.tier, zone,
+                    message: `${where} ${why} but binding entry "${resolved.key}" is zone: ${zone}; it must be private` });
+            }
+        }
+    }
+    const roles = [];
+    for (const role of ["judge", "render"]) {
+        const key = binding.roles?.[role];
+        if (key === undefined)
+            continue;
+        const spec = binding.tiers[key];
+        const zone = spec?.zone ?? "unbound";
+        roles.push({ role, key, ...(spec ? { spec } : {}), zone });
+        if (!armed)
+            continue;
+        if (!spec) {
+            violations.push({ code: "unbound_tier", tier: key, zone, message: `${role} role names binding entry "${key}", which does not exist` });
+        }
+        else if (zone === "unbound") {
+            violations.push({ code: "missing_zone", tier: key, zone, message: `${role} tier "${key}" declares no zone; it must be private` });
+        }
+        else if (zone !== "private") {
+            violations.push({ code: role === "judge" ? "judge_public" : "render_public", tier: key, zone,
+                message: `${role} tier "${key}" is zone: ${zone}; it ${role === "judge" ? "sees unfiltered answers" : "sees rows"} and must be private` });
+        }
+    }
+    if (armed && binding.disclosurePolicy === undefined) {
+        for (const report of steps) {
+            if (report.role === "caller" && report.calls.length > 0 && report.zone !== "private") {
+                violations.push({ code: "missing_policy", component: report.component, step: report.step, tier: report.tier, zone: report.zone,
+                    message: `step ${report.component}.${report.step} (tier ${report.tier}, zone ${report.zone}) calls ${report.calls.map((edge) => edge.component).join(", ")} but the binding has no disclosure_policy; child results would cross unverified` });
+            }
+        }
+    }
+    if (armed && binding.roles?.render === undefined) {
+        const node = plan.components[entry];
+        const render = node.declaration.effect?.render_blocks;
+        const terminal = node.steps.filter((step) => !step.repairOf).at(-1);
+        if (Array.isArray(render) && render.length > 0 && terminal) {
+            const zone = resolveTierSpec(binding, terminal.tier, entry)?.spec.zone ?? "unbound";
+            if (zone !== "private") {
+                violations.push({ code: "render_unbound", component: entry, step: terminal.name, tier: terminal.tier, zone,
+                    message: `entry ${entry} renders a contract but roles.render names no tier; the render stage sees rows and would inherit step ${entry}.${terminal.name} (tier ${terminal.tier}, zone ${zone}); bind it to a private tier explicitly` });
+            }
+        }
+    }
+    if (armed && binding.disclosurePolicy !== undefined && binding.roles?.judge === undefined) {
+        violations.push({ code: "missing_judge", tier: "(none)", zone: "unbound",
+            message: "disclosure_policy is set but roles.judge names no tier; the egress verification step needs a private judge" });
+    }
+    return { armed, entry, steps, roles, violations };
+}
+/** Runs the gate and throws {@link ZoneGateError} when an armed gate finds any violation. */
+export function assertZoneGate(plan, entry, binding) {
+    const result = evaluateZoneGate(plan, entry, binding);
+    if (result.armed && result.violations.length > 0)
+        throw new ZoneGateError(result.violations);
+    return result;
+}