@paybond/kit 0.10.0 → 0.11.0

package/dist/policy/reload.js

@@ -0,0 +1,233 @@
+import { readFile } from "node:fs/promises";
+import { PaybondPolicy } from "./load.js";
+import { parsePolicyDocumentText } from "./parse-text.js";
+import { isPaybondPolicyDocumentV2, isPaybondPolicyOverlay, parsePaybondPolicyDocument, parsePaybondPolicyDocumentV1, } from "./schema.js";
+import { createPolicySnapshot, createPolicySnapshotFromEffective, } from "./snapshot.js";
+import { PolicyValidator } from "./validate.js";
+import { validatePolicyRemote, } from "./validate-remote.js";
+/** Structured reload failure (parse, validate, loosening, intent drift). */
+export class PaybondPolicyReloadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PaybondPolicyReloadError";
+        this.code = code;
+    }
+}
+/** Thrown internally when poll/file reload finds an unchanged digest. */
+export class PaybondPolicyReloadUnchangedError extends Error {
+    constructor() {
+        super("policy digest unchanged");
+        this.name = "PaybondPolicyReloadUnchangedError";
+    }
+}
+/** Load a versioned snapshot from a policy file path. */
+export async function loadPolicySnapshotFromFile(filePath) {
+    const policy = await PaybondPolicy.load(filePath);
+    const registry = policy.toToolRegistry();
+    return createPolicySnapshot({
+        document: policy.document,
+        registry,
+        source: "file",
+    });
+}
+/** Poll Gateway effective resolution; returns unchanged when digest matches. */
+export async function loadPolicySnapshotFromEffectivePoll(options) {
+    const text = await readFile(options.overlayPath, "utf8");
+    const overlayDoc = parsePaybondPolicyDocument(parsePolicyDocumentText(text));
+    if (!isPaybondPolicyDocumentV2(overlayDoc) || !isPaybondPolicyOverlay(overlayDoc)) {
+        throw new PaybondPolicyReloadError("invalid_overlay", "poll reload requires a v2 tenant overlay policy with extends.org_policy_id");
+    }
+    const orgPolicyId = overlayDoc.extends?.org_policy_id?.trim();
+    if (!orgPolicyId) {
+        throw new PaybondPolicyReloadError("invalid_overlay", "poll reload requires extends.org_policy_id on the overlay policy");
+    }
+    const resolved = await options.gateway.resolvePolicyEffective(orgPolicyId, overlayDoc, { currentDigest: options.currentDigest });
+    if (resolved.unchanged) {
+        return { unchanged: true };
+    }
+    const effective = parsePaybondPolicyDocumentV1(resolved.effective_policy);
+    const policy = PaybondPolicy.fromDocument(effective);
+    const registry = policy.toToolRegistry();
+    const snapshot = createPolicySnapshotFromEffective({
+        document: effective,
+        registry,
+        effectivePolicyDigest: resolved.effective_policy_digest,
+    });
+    return { snapshot, unchanged: false };
+}
+function readMaxSpendCents(entry) {
+    return typeof entry.max_spend_cents === "number" ? entry.max_spend_cents : undefined;
+}
+/** Detect policy loosening between two effective documents. */
+export function detectPolicyLoosening(previous, next) {
+    const reasons = [];
+    if (previous.default_deny && !next.default_deny) {
+        reasons.push("default_deny relaxed from true to false");
+    }
+    for (const [toolName, nextEntry] of Object.entries(next.tools)) {
+        const prevEntry = previous.tools[toolName];
+        if (!prevEntry) {
+            if (nextEntry.side_effecting) {
+                reasons.push(`new side-effecting tool "${toolName}"`);
+            }
+            continue;
+        }
+        const prevCap = readMaxSpendCents(prevEntry);
+        const nextCap = readMaxSpendCents(nextEntry);
+        if (prevCap !== undefined) {
+            if (nextCap === undefined) {
+                reasons.push(`tool "${toolName}" max_spend_cents cap removed`);
+            }
+            else if (nextCap > prevCap) {
+                reasons.push(`tool "${toolName}" max_spend_cents increased from ${prevCap} to ${nextCap}`);
+            }
+        }
+        if (!prevEntry.side_effecting && nextEntry.side_effecting) {
+            reasons.push(`tool "${toolName}" became side-effecting`);
+        }
+    }
+    return reasons;
+}
+/** True when reloaded policy requires operations outside the bound intent. */
+export function requiresIntentRebind(document, allowedTools) {
+    const intentTools = document.intent?.allowed_tools ?? [];
+    for (const operation of intentTools) {
+        if (!allowedTools.includes(operation)) {
+            return true;
+        }
+    }
+    for (const [toolName, entry] of Object.entries(document.tools)) {
+        if (!entry.side_effecting) {
+            continue;
+        }
+        const operation = entry.operation?.trim() || toolName;
+        if (!allowedTools.includes(operation)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function waitForInFlightInterceptors(interceptor, timeoutMs = 30_000) {
+    await waitForInFlightCount(() => interceptor.inFlightCount, timeoutMs);
+}
+async function waitForInFlightCount(readCount, timeoutMs = 30_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (readCount() > 0) {
+        if (Date.now() > deadline) {
+            throw new PaybondPolicyReloadError("in_flight_timeout", "timed out waiting for in-flight tool calls before policy reload");
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+}
+async function resolveReloadSnapshotForHandle(handle, options) {
+    const filePath = options.file?.trim() || handle.policyFilePath;
+    if (!filePath) {
+        throw new PaybondPolicyReloadError("missing_policy_file", "reload requires a policy file path (pass file or bind with reload.watch/poll)");
+    }
+    if (options.resolveInheritance && options.gateway) {
+        const polled = await loadPolicySnapshotFromEffectivePoll({
+            overlayPath: filePath,
+            gateway: options.gateway,
+            currentDigest: handle.policyDigest,
+        });
+        if (polled.unchanged) {
+            throw new PaybondPolicyReloadUnchangedError();
+        }
+        if (!polled.snapshot) {
+            throw new PaybondPolicyReloadError("effective_empty", "effective policy resolution returned no snapshot");
+        }
+        return polled.snapshot;
+    }
+    const snapshot = await loadPolicySnapshotFromFile(filePath);
+    if (handle.policyDigest && handle.policyDigest === snapshot.digest) {
+        throw new PaybondPolicyReloadUnchangedError();
+    }
+    return snapshot;
+}
+async function validateAndApplyPolicySnapshot(handle, snapshot, options, allowedTools) {
+    const previousDocument = handle.currentSnapshot?.document;
+    const nextDocument = snapshot.document;
+    const localReport = await PolicyValidator.validateDocument(nextDocument, {
+        strict: PolicyValidator.isStrictFromEnv(),
+    });
+    if (!localReport.valid) {
+        const first = localReport.errors[0];
+        throw new PaybondPolicyReloadError("local_validate_failed", first ? `${first.path}: ${first.message}` : "local policy validation failed");
+    }
+    if (options.remote && options.gateway) {
+        const remoteReport = await validatePolicyRemote(nextDocument, options.gateway, {
+            resolveInheritance: options.resolveInheritance,
+            strict: PolicyValidator.isStrictFromEnv(),
+        });
+        if (!remoteReport.valid) {
+            const first = remoteReport.errors[0];
+            throw new PaybondPolicyReloadError("remote_validate_failed", first ? `${first.path}: ${first.message}` : "remote policy validation failed");
+        }
+    }
+    if (allowedTools.length > 0 && requiresIntentRebind(nextDocument, allowedTools)) {
+        throw new PaybondPolicyReloadError("intent_rebind_required", "reloaded policy requires allowed_tools outside the bound intent; re-bind with a new intent");
+    }
+    if (previousDocument && !options.allowLoosen) {
+        const loosening = detectPolicyLoosening(previousDocument, nextDocument);
+        if (loosening.length > 0) {
+            throw new PaybondPolicyReloadError("loosening_denied", `policy loosening denied: ${loosening.join("; ")}`);
+        }
+    }
+    if (allowedTools.length > 0) {
+        snapshot.registry.validateForBind(allowedTools);
+    }
+    const previousDigest = handle.policyDigest;
+    if (previousDigest && previousDigest === snapshot.digest) {
+        return { applied: false, previousDigest, newDigest: snapshot.digest, unchanged: true };
+    }
+    handle.applyPolicySnapshot(snapshot);
+    return {
+        applied: true,
+        previousDigest: previousDigest ?? snapshot.digest,
+        newDigest: snapshot.digest,
+    };
+}
+/** Reload policy for any {@link PolicyReloadHandle} (agent run or MCP gate). */
+export async function reloadPolicyOnHandle(handle, options = {}) {
+    await waitForInFlightCount(() => handle.inFlightCount);
+    let snapshot;
+    try {
+        snapshot = await resolveReloadSnapshotForHandle(handle, options);
+    }
+    catch (err) {
+        if (err instanceof PaybondPolicyReloadUnchangedError) {
+            return {
+                applied: false,
+                previousDigest: handle.policyDigest,
+                newDigest: handle.policyDigest,
+                unchanged: true,
+            };
+        }
+        throw err;
+    }
+    const allowedTools = options.allowedTools ??
+        handle.currentSnapshot?.document.intent?.allowed_tools ??
+        [];
+    return validateAndApplyPolicySnapshot(handle, snapshot, options, allowedTools);
+}
+/** Apply a validated snapshot to a run (atomic registry swap). */
+export function applyPolicySnapshotToRun(run, snapshot) {
+    const previousDigest = run.policyDigest;
+    if (previousDigest && previousDigest === snapshot.digest) {
+        return { applied: false, previousDigest, newDigest: snapshot.digest, unchanged: true };
+    }
+    run.applyPolicySnapshot(snapshot);
+    return {
+        applied: true,
+        previousDigest: previousDigest ?? snapshot.digest,
+        newDigest: snapshot.digest,
+    };
+}
+/** Core reload pipeline: load, validate, guard, swap. */
+export async function reloadPolicyOnRun(run, options = {}) {
+    return reloadPolicyOnHandle(run, {
+        ...options,
+        allowedTools: run.allowedTools,
+    });
+}

package/dist/policy/render-yaml.d.ts

@@ -0,0 +1,3 @@
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+/** Serialize a validated v1 policy document to paybond.policy.yaml text. */
+export declare function renderPolicyDocumentYaml(document: PaybondPolicyDocumentV1): string;

package/dist/policy/render-yaml.js

@@ -0,0 +1,69 @@
+function yamlScalar(value) {
+    if (/^[a-z0-9_.-]+$/i.test(value)) {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+function renderToolEntry(entry, indent) {
+    const lines = [`${indent}side_effecting: ${entry.side_effecting}`];
+    if (entry.max_spend_cents !== undefined) {
+        lines.push(`${indent}max_spend_cents: ${entry.max_spend_cents}`);
+    }
+    if (entry.spend_from_args !== undefined) {
+        lines.push(`${indent}spend_from_args: ${yamlScalar(entry.spend_from_args)}`);
+    }
+    if (entry.evidence_preset !== undefined) {
+        lines.push(`${indent}evidence_preset: ${entry.evidence_preset}`);
+    }
+    if (entry.vendor_pack !== undefined) {
+        lines.push(`${indent}vendor_pack: ${entry.vendor_pack}`);
+    }
+    if (entry.operation !== undefined) {
+        lines.push(`${indent}operation: ${yamlScalar(entry.operation)}`);
+    }
+    return lines;
+}
+/** Serialize a validated v1 policy document to paybond.policy.yaml text. */
+export function renderPolicyDocumentYaml(document) {
+    const lines = [
+        `version: ${document.version}`,
+        `name: ${document.name}`,
+        `default_deny: ${document.default_deny}`,
+        "",
+        "tools:",
+    ];
+    for (const [toolName, entry] of Object.entries(document.tools)) {
+        lines.push(`  ${toolName}:`);
+        lines.push(...renderToolEntry(entry, "    "));
+        lines.push("");
+    }
+    if (document.intent) {
+        lines.push("intent:");
+        if (document.intent.allowed_tools?.length) {
+            lines.push("  allowed_tools:");
+            for (const tool of document.intent.allowed_tools) {
+                lines.push(`    - ${tool}`);
+            }
+        }
+        if (document.intent.budget) {
+            lines.push("  budget:");
+            if (document.intent.budget.currency) {
+                lines.push(`    currency: ${document.intent.budget.currency}`);
+            }
+            if (document.intent.budget.max_spend_usd !== undefined) {
+                lines.push(`    max_spend_usd: ${document.intent.budget.max_spend_usd}`);
+            }
+        }
+        if (document.intent.policy_binding) {
+            lines.push("  policy_binding:");
+            lines.push(`    template_id: ${document.intent.policy_binding.template_id}`);
+            if (document.intent.policy_binding.version_seq !== undefined) {
+                lines.push(`    version_seq: ${document.intent.policy_binding.version_seq}`);
+            }
+            if (document.intent.policy_binding.head_digest !== undefined) {
+                lines.push(`    head_digest: ${document.intent.policy_binding.head_digest}`);
+            }
+        }
+    }
+    return `${lines.join("\n").replace(/\n+$/u, "")}\n`;
+}

package/dist/policy/sandbox-bootstrap.d.ts

@@ -0,0 +1,19 @@
+import type { PaybondRunBindingSandboxBootstrapInput } from "../agent/types.js";
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+/** Raised when policy cannot derive sandbox bootstrap parameters. */
+export declare class PaybondPolicySandboxBootstrapError extends Error {
+    constructor(message: string);
+}
+export type PaybondPolicySandboxBootstrapOptions = {
+    /** Registry tool name to bootstrap against. */
+    toolName?: string;
+    /** Harbor operation string; matched against tool names and optional `operation` overrides. */
+    operation?: string;
+    requestedSpendCents?: number;
+    currency?: string;
+    evidenceSchema?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+};
+/** Build {@link PaybondAgentRun.bind} sandbox bootstrap input from a validated policy document. */
+export declare function policySandboxBootstrap(document: PaybondPolicyDocumentV1, options?: PaybondPolicySandboxBootstrapOptions): PaybondRunBindingSandboxBootstrapInput;

package/dist/policy/sandbox-bootstrap.js

@@ -0,0 +1,66 @@
+import { getCompletionPreset } from "../completion-catalog.js";
+/** Raised when policy cannot derive sandbox bootstrap parameters. */
+export class PaybondPolicySandboxBootstrapError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PaybondPolicySandboxBootstrapError";
+    }
+}
+function listSideEffectingTools(document) {
+    return Object.entries(document.tools).filter(([, entry]) => entry.side_effecting);
+}
+function resolveHarborOperation(toolName, entry) {
+    return entry.operation?.trim() || toolName;
+}
+function resolveSideEffectingTool(document, options) {
+    const sideEffecting = listSideEffectingTools(document);
+    if (sideEffecting.length === 0) {
+        throw new PaybondPolicySandboxBootstrapError("policy has no side-effecting tools for sandbox bootstrap");
+    }
+    if (options.toolName?.trim()) {
+        const toolName = options.toolName.trim();
+        const entry = document.tools[toolName];
+        if (!entry?.side_effecting) {
+            throw new PaybondPolicySandboxBootstrapError(`tool "${toolName}" is not a registered side-effecting tool in policy`);
+        }
+        return { toolName, entry };
+    }
+    if (options.operation?.trim()) {
+        const operation = options.operation.trim();
+        for (const [toolName, entry] of sideEffecting) {
+            const harborOperation = resolveHarborOperation(toolName, entry);
+            if (harborOperation === operation || toolName === operation) {
+                return { toolName, entry };
+            }
+        }
+        throw new PaybondPolicySandboxBootstrapError(`operation "${operation}" does not match any side-effecting tool in policy`);
+    }
+    const [toolName, entry] = sideEffecting[0];
+    return { toolName, entry };
+}
+/** Build {@link PaybondAgentRun.bind} sandbox bootstrap input from a validated policy document. */
+export function policySandboxBootstrap(document, options = {}) {
+    const { toolName, entry } = resolveSideEffectingTool(document, options);
+    const operation = resolveHarborOperation(toolName, entry);
+    const evidencePreset = entry.evidence_preset;
+    const preset = getCompletionPreset(evidencePreset);
+    let requestedSpendCents = options.requestedSpendCents;
+    if (requestedSpendCents === undefined) {
+        requestedSpendCents = entry.max_spend_cents ?? preset.recommended_amount_cents ?? 0;
+    }
+    if (!Number.isFinite(requestedSpendCents) || requestedSpendCents < 0) {
+        throw new PaybondPolicySandboxBootstrapError("requestedSpendCents must be a non-negative number");
+    }
+    return {
+        kind: "sandbox",
+        operation,
+        requestedSpendCents,
+        currency: options.currency ?? document.intent?.budget?.currency,
+        evidenceSchema: options.evidenceSchema ?? preset.evidence_schema,
+        completionPreset: evidencePreset,
+        metadata: options.metadata,
+        idempotencyKey: options.idempotencyKey,
+        templateId: preset.harbor_template_id,
+        parameters: preset.parameters,
+    };
+}

package/dist/policy/schema.d.ts

@@ -0,0 +1,204 @@
+import { z } from "zod";
+/** Supported `paybond.policy.yaml` schema revisions. */
+export declare const PAYBOND_POLICY_SCHEMA_VERSION: 1;
+export declare const PAYBOND_POLICY_SCHEMA_VERSION_V2: 2;
+declare const policyToolEntrySchema: z.ZodObject<{
+    side_effecting: z.ZodBoolean;
+    max_spend_cents: z.ZodOptional<z.ZodNumber>;
+    spend_from_args: z.ZodOptional<z.ZodString>;
+    evidence_preset: z.ZodOptional<z.ZodString>;
+    vendor_pack: z.ZodOptional<z.ZodString>;
+    operation: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const policyToolOverrideEntrySchema: z.ZodObject<{
+    side_effecting: z.ZodOptional<z.ZodBoolean>;
+    max_spend_cents: z.ZodOptional<z.ZodNumber>;
+    spend_from_args: z.ZodOptional<z.ZodString>;
+    evidence_preset: z.ZodOptional<z.ZodString>;
+    vendor_pack: z.ZodOptional<z.ZodString>;
+    operation: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const policyBindingSchema: z.ZodObject<{
+    template_id: z.ZodString;
+    version_seq: z.ZodOptional<z.ZodNumber>;
+    head_digest: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const policyBindingOverrideSchema: z.ZodObject<{
+    template_id: z.ZodOptional<z.ZodString>;
+    version_seq: z.ZodOptional<z.ZodNumber>;
+    head_digest: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const policyBudgetSchema: z.ZodObject<{
+    currency: z.ZodString;
+    max_spend_usd: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+declare const policyIntentSchema: z.ZodObject<{
+    policy_binding: z.ZodOptional<z.ZodObject<{
+        template_id: z.ZodString;
+        version_seq: z.ZodOptional<z.ZodNumber>;
+        head_digest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    budget: z.ZodOptional<z.ZodObject<{
+        currency: z.ZodString;
+        max_spend_usd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const policyIntentOverrideSchema: z.ZodObject<{
+    policy_binding: z.ZodOptional<z.ZodObject<{
+        template_id: z.ZodOptional<z.ZodString>;
+        version_seq: z.ZodOptional<z.ZodNumber>;
+        head_digest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    budget: z.ZodOptional<z.ZodObject<{
+        currency: z.ZodString;
+        max_spend_usd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const policyExtendsSchema: z.ZodObject<{
+    org_policy_id: z.ZodString;
+    org_id: z.ZodString;
+    base_digest: z.ZodOptional<z.ZodString>;
+    base_policy: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const policyOverridesSchema: z.ZodObject<{
+    default_deny: z.ZodOptional<z.ZodBoolean>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        side_effecting: z.ZodOptional<z.ZodBoolean>;
+        max_spend_cents: z.ZodOptional<z.ZodNumber>;
+        spend_from_args: z.ZodOptional<z.ZodString>;
+        evidence_preset: z.ZodOptional<z.ZodString>;
+        vendor_pack: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    intent: z.ZodOptional<z.ZodObject<{
+        policy_binding: z.ZodOptional<z.ZodObject<{
+            template_id: z.ZodOptional<z.ZodString>;
+            version_seq: z.ZodOptional<z.ZodNumber>;
+            head_digest: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        budget: z.ZodOptional<z.ZodObject<{
+            currency: z.ZodString;
+            max_spend_usd: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+        allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const paybondPolicyDocumentV1Schema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    default_deny: z.ZodBoolean;
+    tools: z.ZodRecord<z.ZodString, z.ZodObject<{
+        side_effecting: z.ZodBoolean;
+        max_spend_cents: z.ZodOptional<z.ZodNumber>;
+        spend_from_args: z.ZodOptional<z.ZodString>;
+        evidence_preset: z.ZodOptional<z.ZodString>;
+        vendor_pack: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    intent: z.ZodOptional<z.ZodObject<{
+        policy_binding: z.ZodOptional<z.ZodObject<{
+            template_id: z.ZodString;
+            version_seq: z.ZodOptional<z.ZodNumber>;
+            head_digest: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        budget: z.ZodOptional<z.ZodObject<{
+            currency: z.ZodString;
+            max_spend_usd: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+        allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const paybondPolicyDocumentV2Schema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    name: z.ZodString;
+    default_deny: z.ZodBoolean;
+    extends: z.ZodOptional<z.ZodObject<{
+        org_policy_id: z.ZodString;
+        org_id: z.ZodString;
+        base_digest: z.ZodOptional<z.ZodString>;
+        base_policy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    overrides: z.ZodOptional<z.ZodObject<{
+        default_deny: z.ZodOptional<z.ZodBoolean>;
+        tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            side_effecting: z.ZodOptional<z.ZodBoolean>;
+            max_spend_cents: z.ZodOptional<z.ZodNumber>;
+            spend_from_args: z.ZodOptional<z.ZodString>;
+            evidence_preset: z.ZodOptional<z.ZodString>;
+            vendor_pack: z.ZodOptional<z.ZodString>;
+            operation: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        intent: z.ZodOptional<z.ZodObject<{
+            policy_binding: z.ZodOptional<z.ZodObject<{
+                template_id: z.ZodOptional<z.ZodString>;
+                version_seq: z.ZodOptional<z.ZodNumber>;
+                head_digest: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            budget: z.ZodOptional<z.ZodObject<{
+                currency: z.ZodString;
+                max_spend_usd: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
+            allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    tools: z.ZodRecord<z.ZodString, z.ZodObject<{
+        side_effecting: z.ZodBoolean;
+        max_spend_cents: z.ZodOptional<z.ZodNumber>;
+        spend_from_args: z.ZodOptional<z.ZodString>;
+        evidence_preset: z.ZodOptional<z.ZodString>;
+        vendor_pack: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    intent: z.ZodOptional<z.ZodObject<{
+        policy_binding: z.ZodOptional<z.ZodObject<{
+            template_id: z.ZodString;
+            version_seq: z.ZodOptional<z.ZodNumber>;
+            head_digest: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        budget: z.ZodOptional<z.ZodObject<{
+            currency: z.ZodString;
+            max_spend_usd: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+        allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PaybondPolicyToolEntry = z.infer<typeof policyToolEntrySchema>;
+export type PaybondPolicyToolOverrideEntry = z.infer<typeof policyToolOverrideEntrySchema>;
+export type PaybondPolicyBinding = z.infer<typeof policyBindingSchema>;
+export type PaybondPolicyBindingOverride = z.infer<typeof policyBindingOverrideSchema>;
+export type PaybondPolicyBudget = z.infer<typeof policyBudgetSchema>;
+export type PaybondPolicyIntentSection = z.infer<typeof policyIntentSchema>;
+export type PaybondPolicyIntentOverrideSection = z.infer<typeof policyIntentOverrideSchema>;
+export type PaybondPolicyExtends = z.infer<typeof policyExtendsSchema>;
+export type PaybondPolicyOverrides = z.infer<typeof policyOverridesSchema>;
+export type PaybondPolicyDocumentV1 = z.infer<typeof paybondPolicyDocumentV1Schema>;
+export type PaybondPolicyDocumentV2 = z.infer<typeof paybondPolicyDocumentV2Schema>;
+export type PaybondPolicyDocument = PaybondPolicyDocumentV1 | PaybondPolicyDocumentV2;
+export type PaybondPolicyValidationIssue = {
+    path: string;
+    code: string;
+    message: string;
+};
+/** Raised when a policy document fails schema validation. */
+export declare class PaybondPolicyValidationError extends Error {
+    readonly issues: PaybondPolicyValidationIssue[];
+    constructor(message: string, issues?: PaybondPolicyValidationIssue[]);
+}
+/**
+ * Parse and validate a raw policy document (already-decoded JSON or YAML object).
+ * Accepts v1 flat policies and v2 org-base or tenant-overlay documents.
+ */
+export declare function parsePaybondPolicyDocument(raw: unknown): PaybondPolicyDocument;
+/** Parse a v1-only policy document. */
+export declare function parsePaybondPolicyDocumentV1(raw: unknown): PaybondPolicyDocumentV1;
+/** Parse a v2 policy document (org base or tenant overlay). */
+export declare function parsePaybondPolicyDocumentV2(raw: unknown): PaybondPolicyDocumentV2;
+/** Type guard for an already-validated v1 policy document. */
+export declare function isPaybondPolicyDocumentV1(value: unknown): value is PaybondPolicyDocumentV1;
+/** Type guard for an already-validated v2 policy document. */
+export declare function isPaybondPolicyDocumentV2(value: unknown): value is PaybondPolicyDocumentV2;
+/** True when a v2 document is a tenant overlay (declares extends). */
+export declare function isPaybondPolicyOverlay(document: PaybondPolicyDocumentV2): boolean;
+export {};