@paybond/kit 0.9.8 → 0.11.0

package/dist/policy/intent-spec.js

@@ -0,0 +1,176 @@
+import { PaybondToolRegistryValidationError } from "../agent/types.js";
+import { resolveCompletionPreset, contractSnapshotForPreset } from "../completion-resolve.js";
+import { policyToToolRegistry } from "./registry.js";
+/** Raised when policy intent fields cannot be aligned to a Harbor create payload. */
+export class PaybondPolicyIntentSpecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PaybondPolicyIntentSpecError";
+    }
+}
+function normalizeDigestHex(digest) {
+    const trimmed = digest.trim().toLowerCase();
+    if (trimmed.startsWith("sha256:")) {
+        return trimmed.slice("sha256:".length);
+    }
+    return trimmed.replace(/^0x/, "");
+}
+function resolveAllowedHarborOperations(document, registry, override) {
+    const raw = override ?? document.intent?.allowed_tools;
+    if (!raw || raw.length === 0) {
+        throw new PaybondPolicyIntentSpecError("policy intent.allowed_tools is required for toIntentCreateInput");
+    }
+    const operations = registry.sideEffectingOperations();
+    const seen = new Set();
+    const resolved = [];
+    for (const name of raw) {
+        let operation;
+        if (registry.isSideEffecting(name)) {
+            operation = registry.resolveOperation(name);
+        }
+        else if (operations.includes(name)) {
+            operation = name;
+        }
+        else {
+            throw new PaybondPolicyIntentSpecError(`allowed_tools entry "${name}" is not a registered side-effecting tool or Harbor operation`);
+        }
+        if (!seen.has(operation)) {
+            seen.add(operation);
+            resolved.push(operation);
+        }
+    }
+    if (resolved.length === 0) {
+        throw new PaybondPolicyIntentSpecError("allowed_tools must resolve to at least one Harbor operation");
+    }
+    try {
+        registry.validateForBind(resolved);
+    }
+    catch (err) {
+        if (err instanceof PaybondToolRegistryValidationError) {
+            throw new PaybondPolicyIntentSpecError(err.message);
+        }
+        throw err;
+    }
+    return resolved;
+}
+function resolveEvidencePresetForOperations(registry, allowedOperations) {
+    const presets = new Set();
+    for (const operation of allowedOperations) {
+        for (const toolName of registry.sideEffectingToolNames()) {
+            if (registry.resolveOperation(toolName) !== operation) {
+                continue;
+            }
+            const preset = registry.getSideEffectingEntry(toolName)?.evidencePreset;
+            if (preset) {
+                presets.add(preset);
+            }
+        }
+    }
+    if (presets.size === 0) {
+        throw new PaybondPolicyIntentSpecError("could not resolve evidence_preset from policy allowed_tools");
+    }
+    if (presets.size > 1) {
+        throw new PaybondPolicyIntentSpecError(`allowed_tools reference multiple evidence_preset values: ${[...presets].join(", ")}`);
+    }
+    return [...presets][0];
+}
+function resolvePolicyBindingRef(document, publishedHead, override) {
+    const policyBinding = document.intent?.policy_binding;
+    if (!override && !policyBinding) {
+        throw new PaybondPolicyIntentSpecError("policy intent.policy_binding is required for toIntentCreateInput");
+    }
+    const binding = override ?? {
+        templateId: policyBinding.template_id,
+        versionSeq: policyBinding.version_seq ?? publishedHead.versionSeq,
+    };
+    if (binding.templateId !== publishedHead.templateId) {
+        throw new PaybondPolicyIntentSpecError("publishedPolicyHead.templateId must match policy intent.policy_binding.template_id");
+    }
+    if (binding.versionSeq !== publishedHead.versionSeq) {
+        throw new PaybondPolicyIntentSpecError("publishedPolicyHead.versionSeq must match policy intent.policy_binding.version_seq");
+    }
+    if (policyBinding?.version_seq !== undefined &&
+        policyBinding.version_seq !== publishedHead.versionSeq) {
+        throw new PaybondPolicyIntentSpecError("policy intent.policy_binding.version_seq does not match publishedPolicyHead.versionSeq");
+    }
+    const headDigest = policyBinding?.head_digest;
+    if (headDigest) {
+        const expected = normalizeDigestHex(headDigest);
+        const actual = normalizeDigestHex(publishedHead.policyContentDigestHex);
+        if (expected !== actual) {
+            throw new PaybondPolicyIntentSpecError("policy intent.policy_binding.head_digest does not match publishedPolicyHead.policyContentDigestHex");
+        }
+    }
+    return binding;
+}
+function resolveBudgetFields(document, overrides) {
+    if (overrides.budget !== undefined &&
+        overrides.currency !== undefined &&
+        overrides.amountCents !== undefined) {
+        return {
+            budget: overrides.budget,
+            currency: overrides.currency,
+            amountCents: overrides.amountCents,
+        };
+    }
+    const intentBudget = document.intent?.budget;
+    const currency = overrides.currency ??
+        (typeof intentBudget?.currency === "string" ? intentBudget.currency : undefined) ??
+        "usd";
+    let amountCents = overrides.amountCents;
+    if (amountCents === undefined && intentBudget && typeof intentBudget.max_spend_usd === "number") {
+        amountCents = Math.round(intentBudget.max_spend_usd * 100);
+    }
+    if (amountCents === undefined) {
+        throw new PaybondPolicyIntentSpecError("amountCents is required when policy intent.budget.max_spend_usd is not set");
+    }
+    const budget = overrides.budget ?? {
+        ...(intentBudget ?? {}),
+        max: amountCents,
+    };
+    if (!("max" in budget)) {
+        budget.max = amountCents;
+    }
+    return { budget, currency, amountCents };
+}
+/**
+ * Build {@link PaybondIntents.createWithPolicyBinding} input from a validated policy document.
+ * Merges policy intent alignment (`allowed_tools`, `budget`, `policy_binding`) with caller signing context.
+ */
+export function policyToIntentCreateInput(document, overrides) {
+    const registry = policyToToolRegistry(document);
+    const allowedTools = resolveAllowedHarborOperations(document, registry, overrides.allowedTools);
+    const policyBinding = resolvePolicyBindingRef(document, overrides.publishedPolicyHead, overrides.policyBinding);
+    const { budget, currency, amountCents } = resolveBudgetFields(document, overrides);
+    const completionPresetId = overrides.completionPresetId ??
+        resolveEvidencePresetForOperations(registry, allowedTools);
+    const resolvedPreset = resolveCompletionPreset(completionPresetId);
+    const evidenceSchema = overrides.evidenceSchema ?? resolvedPreset.evidenceSchema;
+    let completionContract;
+    try {
+        completionContract = contractSnapshotForPreset(completionPresetId);
+    }
+    catch (err) {
+        throw new PaybondPolicyIntentSpecError(err instanceof Error ? err.message : "failed to build completion contract snapshot");
+    }
+    return {
+        principalDid: overrides.principalDid,
+        principalSigningSeed: overrides.principalSigningSeed,
+        payeeDid: overrides.payeeDid,
+        payeeSigningSeed: overrides.payeeSigningSeed,
+        budget,
+        currency,
+        amountCents,
+        evidenceSchema,
+        deadlineRfc3339: overrides.deadlineRfc3339,
+        allowedTools,
+        settlementRail: overrides.settlementRail,
+        policyBinding,
+        publishedPolicyHead: overrides.publishedPolicyHead,
+        recognitionProof: overrides.recognitionProof,
+        intentId: overrides.intentId,
+        predicateRef: overrides.predicateRef,
+        completionPresetId,
+        completionContract,
+    };
+}

package/dist/policy/json-path.d.ts

@@ -0,0 +1,4 @@
+/** Read a dot-separated JSON path from tool call arguments. */
+export declare function resolveJsonPath(args: unknown, path: string): unknown;
+/** Resolve non-negative integer spend cents from a JSON path at intercept time. */
+export declare function resolveSpendCentsFromJsonPath(args: unknown, path: string, toolName: string): number | undefined;

package/dist/policy/json-path.js

@@ -0,0 +1,23 @@
+import { PaybondPolicyValidationError } from "./schema.js";
+/** Read a dot-separated JSON path from tool call arguments. */
+export function resolveJsonPath(args, path) {
+    let current = args;
+    for (const segment of path.split(".")) {
+        if (current === null || typeof current !== "object" || Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/** Resolve non-negative integer spend cents from a JSON path at intercept time. */
+export function resolveSpendCentsFromJsonPath(args, path, toolName) {
+    const value = resolveJsonPath(args, path);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new PaybondPolicyValidationError(`tool "${toolName}" spend_from_args path "${path}" must resolve to a non-negative integer`);
+    }
+    return value;
+}

package/dist/policy/layers-io.d.ts

@@ -0,0 +1,7 @@
+import type { LayeredPolicyPresetId } from "./compose.js";
+export declare function presetLayerCandidatePaths(subdir: string, fileName: string): string[];
+export declare function readPresetLayerYaml(subdir: string, fileName: string): string;
+/** Load a bundled domain layer YAML document. */
+export declare function loadBundledDomainDocument(presetId: LayeredPolicyPresetId): Record<string, unknown>;
+/** Load a bundled default guardrails layer YAML document. */
+export declare function loadBundledDefaultGuardrailsDocument(presetId: LayeredPolicyPresetId): Record<string, unknown>;

package/dist/policy/layers-io.js

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parsePolicyDocumentText } from "./parse-text.js";
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+export function presetLayerCandidatePaths(subdir, fileName) {
+    return [
+        join(MODULE_DIR, "../../policy/presets", subdir, fileName),
+        join(MODULE_DIR, "../../../policy/presets", subdir, fileName),
+        join(MODULE_DIR, "../../../../kit/policy/presets", subdir, fileName),
+    ];
+}
+export function readPresetLayerYaml(subdir, fileName) {
+    for (const candidate of presetLayerCandidatePaths(subdir, fileName)) {
+        if (existsSync(candidate)) {
+            return readFileSync(candidate, "utf8");
+        }
+    }
+    throw new Error(`policy preset layer not found: ${subdir}/${fileName}`);
+}
+/** Load a bundled domain layer YAML document. */
+export function loadBundledDomainDocument(presetId) {
+    return parsePolicyDocumentText(readPresetLayerYaml("domain", `${presetId}.yaml`), `domain/${presetId}.yaml`);
+}
+/** Load a bundled default guardrails layer YAML document. */
+export function loadBundledDefaultGuardrailsDocument(presetId) {
+    return parsePolicyDocumentText(readPresetLayerYaml("guardrails", `default-${presetId}.yaml`), `guardrails/default-${presetId}.yaml`);
+}

package/dist/policy/load-effective.d.ts

@@ -0,0 +1,22 @@
+import type { PaybondPolicyDocumentV2 } from "./schema.js";
+import type { PolicyMergeReport } from "./merge.js";
+export type PolicyEffectiveResolveResult = {
+    effective_policy: Record<string, unknown>;
+    effective_policy_digest: string;
+    effective_policy_version: string;
+    merge_report: PolicyMergeReport;
+    org_base_version_seq: number;
+    org_base_content_digest: string;
+    unchanged?: boolean;
+};
+/** Gateway client surface used by {@link resolvePolicyEffectiveRemote}. */
+export type PolicyEffectiveResolveClient = {
+    resolvePolicyEffective(orgPolicyId: string, overlay: Record<string, unknown>, options?: {
+        currentDigest?: string;
+    }): Promise<PolicyEffectiveResolveResult>;
+};
+export declare function parseMergeReport(value: unknown): PolicyMergeReport;
+/** Parse a Gateway org-policy effective resolution JSON body. */
+export declare function parsePolicyEffectiveResolveResponse(body: unknown): PolicyEffectiveResolveResult;
+/** Resolve merged effective policy via Gateway org-policy inheritance endpoint. */
+export declare function resolvePolicyEffectiveRemote(overlay: PaybondPolicyDocumentV2, client: PolicyEffectiveResolveClient): Promise<PolicyEffectiveResolveResult>;

package/dist/policy/load-effective.js

@@ -0,0 +1,77 @@
+export function parseMergeReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("merge_report must be an object");
+    }
+    const row = value;
+    return {
+        org_policy_id: row.org_policy_id == null ? null : String(row.org_policy_id),
+        org_id: row.org_id == null ? null : String(row.org_id),
+        base_policy_name: String(row.base_policy_name ?? ""),
+        overlay_policy_name: row.overlay_policy_name == null ? null : String(row.overlay_policy_name),
+        overrides_applied: Array.isArray(row.overrides_applied)
+            ? row.overrides_applied.map((item) => String(item))
+            : [],
+        denied_widenings: Array.isArray(row.denied_widenings)
+            ? row.denied_widenings
+                .map((item) => {
+                if (!item || typeof item !== "object" || Array.isArray(item)) {
+                    return null;
+                }
+                const denied = item;
+                const path = String(denied.path ?? "");
+                const code = String(denied.code ?? "");
+                const message = String(denied.message ?? "");
+                if (!path || !code || !message) {
+                    return null;
+                }
+                return { path, code, message };
+            })
+                .filter((item) => item !== null)
+            : [],
+    };
+}
+/** Parse a Gateway org-policy effective resolution JSON body. */
+export function parsePolicyEffectiveResolveResponse(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+        throw new Error("policy effective response must be a JSON object");
+    }
+    const row = body;
+    const digest = String(row.effective_policy_digest ?? "");
+    if (!digest) {
+        throw new Error("effective_policy_digest is required");
+    }
+    const version = String(row.effective_policy_version ?? "");
+    if (!version) {
+        throw new Error("effective_policy_version is required");
+    }
+    if (row.unchanged === true) {
+        return {
+            effective_policy: {},
+            effective_policy_digest: digest,
+            effective_policy_version: version,
+            merge_report: parseMergeReport(row.merge_report ?? {}),
+            org_base_version_seq: Number(row.org_base_version_seq ?? 0),
+            org_base_content_digest: String(row.org_base_content_digest ?? ""),
+            unchanged: true,
+        };
+    }
+    const effective = row.effective_policy;
+    if (!effective || typeof effective !== "object" || Array.isArray(effective)) {
+        throw new Error("effective_policy must be an object");
+    }
+    return {
+        effective_policy: effective,
+        effective_policy_digest: digest,
+        effective_policy_version: version,
+        merge_report: parseMergeReport(row.merge_report),
+        org_base_version_seq: Number(row.org_base_version_seq ?? 0),
+        org_base_content_digest: String(row.org_base_content_digest ?? ""),
+    };
+}
+/** Resolve merged effective policy via Gateway org-policy inheritance endpoint. */
+export async function resolvePolicyEffectiveRemote(overlay, client) {
+    if (!overlay.extends?.org_policy_id) {
+        throw new Error("overlay must declare extends.org_policy_id");
+    }
+    return client.resolvePolicyEffective(overlay.extends.org_policy_id, overlay);
+}

package/dist/policy/load.d.ts

@@ -0,0 +1,85 @@
+import type { PaybondToolRegistry } from "../agent/registry.js";
+import { type PaybondPolicyIntentCreateInput, type PaybondPolicyIntentCreateOverrides } from "./intent-spec.js";
+import { type PolicyMergeOptions, type PolicyMergeResult } from "./merge.js";
+import { type PaybondPolicyDocument, type PaybondPolicyDocumentV1 } from "./schema.js";
+import { type PaybondPolicySandboxBootstrapOptions } from "./sandbox-bootstrap.js";
+import { type PolicyValidatorOptions, type PolicyValidatorResult } from "./validate.js";
+import { type PolicyRemoteValidateClient, type PolicyRemoteValidateOptions, type PolicyRemoteValidateResult } from "./validate-remote.js";
+import { type PolicyEffectiveResolveClient } from "./load-effective.js";
+import type { PaybondRunBindingSandboxBootstrapInput } from "../agent/types.js";
+export type PaybondPolicyLoadEffectiveResult = {
+    policy: PaybondPolicy;
+    report: PolicyMergeResult["report"];
+    effectivePolicyDigest: string;
+    effectivePolicyVersion: string;
+    orgBaseVersionSeq: number;
+    orgBaseContentDigest: string;
+    unchanged?: boolean;
+};
+export type PaybondPolicyLoadSource = string | PaybondPolicyDocumentV1 | PaybondPolicyDocument | Record<string, unknown>;
+/**
+ * Portable policy-as-code document loaded from `paybond.policy.yaml` or an in-memory object.
+ * Drives tool registry construction and production intent create alignment.
+ */
+export declare class PaybondPolicy {
+    readonly document: PaybondPolicyDocumentV1;
+    readonly source?: string;
+    private constructor();
+    /** Policy name from the document (`name` field). */
+    get name(): string;
+    /** Whether unregistered side-effecting tools should fail closed at intercept time. */
+    get defaultDeny(): boolean;
+    /** Optional intent section from the policy file. */
+    get intent(): PaybondPolicyDocumentV1["intent"];
+    /**
+     * Load and validate a policy from a file path or pre-parsed document object.
+     * File paths accept JSON (`.json`) or YAML (`.yaml` / `.yml`).
+     */
+    static load(source: PaybondPolicyLoadSource): Promise<PaybondPolicy>;
+    private static resolveEffectiveDocument;
+    /**
+     * Resolve merged effective policy via Gateway org-policy inheritance.
+     * Production tenants should prefer this over {@link mergeLocal}.
+     */
+    static loadEffective(options: {
+        overlay: PaybondPolicyLoadSource;
+        gateway: PolicyEffectiveResolveClient;
+    }): Promise<PaybondPolicyLoadEffectiveResult>;
+    /** Synchronous variant for pre-parsed effective (v1) document objects only. */
+    static fromDocument(document: PaybondPolicyDocumentV1): PaybondPolicy;
+    /**
+     * Offline merge of org base + tenant overlay into an effective v1 policy.
+     * Best-effort for CI; production should use Gateway effective resolution.
+     */
+    static mergeLocal(options: {
+        base: PaybondPolicyLoadSource;
+        overlay: PaybondPolicyLoadSource;
+        merge?: PolicyMergeOptions;
+    }): Promise<PolicyMergeResult & {
+        policy: PaybondPolicy;
+    }>;
+    private static loadDocument;
+    /** Load a raw overlay document payload for server-side inheritance validation. */
+    static loadOverlayPayload(source: PaybondPolicyLoadSource): Promise<Record<string, unknown>>;
+    /**
+     * Validate a tenant overlay with server-side org-base merge
+     * (`POST /v1/policy/validate?resolve_inheritance=1`).
+     */
+    static validateOverlayRemote(overlay: PaybondPolicyLoadSource, gateway: PolicyRemoteValidateClient, options?: PolicyRemoteValidateOptions): Promise<PolicyRemoteValidateResult>;
+    /** Build the tool registry consumed by agent middleware. */
+    toToolRegistry(): PaybondToolRegistry;
+    /**
+     * Build params for {@link PaybondIntents.createWithPolicyBinding} from policy intent alignment
+     * plus caller signing context and a published managed-policy head.
+     */
+    toIntentCreateInput(overrides: PaybondPolicyIntentCreateOverrides): PaybondPolicyIntentCreateInput;
+    /** Run client-side alignment checks (registry, presets, optional gateway template lookup). */
+    validate(options?: PolicyValidatorOptions): Promise<PolicyValidatorResult>;
+    /**
+     * Validate this policy against the tenant-scoped Gateway registry (`POST /v1/policy/validate`).
+     * Requires a logged-in Gateway Harbor client from `paybond.open()`.
+     */
+    validateRemote(gateway: PolicyRemoteValidateClient, options?: PolicyRemoteValidateOptions): Promise<PolicyRemoteValidateResult>;
+    /** Build sandbox bootstrap input for {@link PaybondAgentRun.bind} from this policy. */
+    sandboxBootstrap(options?: PaybondPolicySandboxBootstrapOptions): PaybondRunBindingSandboxBootstrapInput;
+}

package/dist/policy/load.js

@@ -0,0 +1,164 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { policyToIntentCreateInput, } from "./intent-spec.js";
+import { mergePaybondPolicies, toEffectivePolicyDocument, } from "./merge.js";
+import { parsePolicyDocumentText } from "./parse-text.js";
+import { policyToToolRegistry } from "./registry.js";
+import { isPaybondPolicyDocumentV2, isPaybondPolicyOverlay, parsePaybondPolicyDocument, parsePaybondPolicyDocumentV1, } from "./schema.js";
+import { policySandboxBootstrap, } from "./sandbox-bootstrap.js";
+import { PolicyValidator } from "./validate.js";
+import { validatePolicyRemote, validatePolicyPayloadRemote, } from "./validate-remote.js";
+import { resolvePolicyEffectiveRemote, } from "./load-effective.js";
+/**
+ * Portable policy-as-code document loaded from `paybond.policy.yaml` or an in-memory object.
+ * Drives tool registry construction and production intent create alignment.
+ */
+export class PaybondPolicy {
+    document;
+    source;
+    constructor(document, source) {
+        this.document = document;
+        this.source = source;
+    }
+    /** Policy name from the document (`name` field). */
+    get name() {
+        return this.document.name;
+    }
+    /** Whether unregistered side-effecting tools should fail closed at intercept time. */
+    get defaultDeny() {
+        return this.document.default_deny;
+    }
+    /** Optional intent section from the policy file. */
+    get intent() {
+        return this.document.intent;
+    }
+    /**
+     * Load and validate a policy from a file path or pre-parsed document object.
+     * File paths accept JSON (`.json`) or YAML (`.yaml` / `.yml`).
+     */
+    static async load(source) {
+        if (typeof source === "string") {
+            const document = await PaybondPolicy.loadDocument(source);
+            const effective = await PaybondPolicy.resolveEffectiveDocument(document, source);
+            return new PaybondPolicy(effective, source);
+        }
+        const document = parsePaybondPolicyDocument(source);
+        const effective = await PaybondPolicy.resolveEffectiveDocument(document);
+        return new PaybondPolicy(effective);
+    }
+    static async resolveEffectiveDocument(document, sourcePath) {
+        if (isPaybondPolicyDocumentV2(document) && isPaybondPolicyOverlay(document)) {
+            const basePath = document.extends?.base_policy;
+            if (!basePath) {
+                return toEffectivePolicyDocument(document);
+            }
+            const resolvedBase = sourcePath
+                ? resolve(dirname(sourcePath), basePath)
+                : basePath;
+            const baseDoc = await PaybondPolicy.loadDocument(resolvedBase);
+            return mergePaybondPolicies(baseDoc, document).effective;
+        }
+        return toEffectivePolicyDocument(document);
+    }
+    /**
+     * Resolve merged effective policy via Gateway org-policy inheritance.
+     * Production tenants should prefer this over {@link mergeLocal}.
+     */
+    static async loadEffective(options) {
+        const overlayDoc = await PaybondPolicy.loadDocument(options.overlay);
+        if (!isPaybondPolicyDocumentV2(overlayDoc) || !isPaybondPolicyOverlay(overlayDoc)) {
+            throw new Error("overlay must be a v2 tenant policy with extends");
+        }
+        const resolved = await resolvePolicyEffectiveRemote(overlayDoc, options.gateway);
+        const effective = parsePaybondPolicyDocumentV1(resolved.effective_policy);
+        return {
+            policy: PaybondPolicy.fromDocument(effective),
+            report: resolved.merge_report,
+            effectivePolicyDigest: resolved.effective_policy_digest,
+            effectivePolicyVersion: resolved.effective_policy_version,
+            orgBaseVersionSeq: resolved.org_base_version_seq,
+            orgBaseContentDigest: resolved.org_base_content_digest,
+            ...(resolved.unchanged ? { unchanged: true } : {}),
+        };
+    }
+    /** Synchronous variant for pre-parsed effective (v1) document objects only. */
+    static fromDocument(document) {
+        return new PaybondPolicy(document);
+    }
+    /**
+     * Offline merge of org base + tenant overlay into an effective v1 policy.
+     * Best-effort for CI; production should use Gateway effective resolution.
+     */
+    static async mergeLocal(options) {
+        const baseDoc = await PaybondPolicy.loadDocument(options.base);
+        const overlayDoc = await PaybondPolicy.loadDocument(options.overlay);
+        if (!isPaybondPolicyDocumentV2(overlayDoc) || !isPaybondPolicyOverlay(overlayDoc)) {
+            throw new Error("overlay must be a v2 tenant policy with extends");
+        }
+        const merged = mergePaybondPolicies(baseDoc, overlayDoc, options.merge);
+        return {
+            ...merged,
+            policy: PaybondPolicy.fromDocument(merged.effective),
+        };
+    }
+    static async loadDocument(source) {
+        if (typeof source === "string") {
+            const text = await readFile(source, "utf8");
+            const raw = parsePolicyDocumentText(text, source);
+            return parsePaybondPolicyDocument(raw);
+        }
+        return parsePaybondPolicyDocument(source);
+    }
+    /** Load a raw overlay document payload for server-side inheritance validation. */
+    static async loadOverlayPayload(source) {
+        if (typeof source === "string") {
+            const text = await readFile(source, "utf8");
+            const raw = parsePolicyDocumentText(text, source);
+            if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+                throw new Error("overlay must be a JSON or YAML object");
+            }
+            return raw;
+        }
+        if (typeof source === "object" && source !== null && !Array.isArray(source)) {
+            return source;
+        }
+        throw new Error("overlay must be a file path or raw overlay object");
+    }
+    /**
+     * Validate a tenant overlay with server-side org-base merge
+     * (`POST /v1/policy/validate?resolve_inheritance=1`).
+     */
+    static async validateOverlayRemote(overlay, gateway, options) {
+        const payload = await PaybondPolicy.loadOverlayPayload(overlay);
+        return validatePolicyPayloadRemote(payload, gateway, {
+            ...options,
+            resolveInheritance: true,
+        });
+    }
+    /** Build the tool registry consumed by agent middleware. */
+    toToolRegistry() {
+        return policyToToolRegistry(this.document);
+    }
+    /**
+     * Build params for {@link PaybondIntents.createWithPolicyBinding} from policy intent alignment
+     * plus caller signing context and a published managed-policy head.
+     */
+    toIntentCreateInput(overrides) {
+        return policyToIntentCreateInput(this.document, overrides);
+    }
+    /** Run client-side alignment checks (registry, presets, optional gateway template lookup). */
+    validate(options) {
+        return PolicyValidator.validateDocument(this.document, options);
+    }
+    /**
+     * Validate this policy against the tenant-scoped Gateway registry (`POST /v1/policy/validate`).
+     * Requires a logged-in Gateway Harbor client from `paybond.open()`.
+     */
+    validateRemote(gateway, options) {
+        return validatePolicyRemote(this.document, gateway, options);
+    }
+    /** Build sandbox bootstrap input for {@link PaybondAgentRun.bind} from this policy. */
+    sandboxBootstrap(options = {}) {
+        return policySandboxBootstrap(this.document, options);
+    }
+}

package/dist/policy/merge.d.ts

@@ -0,0 +1,29 @@
+import { type PaybondPolicyDocument, type PaybondPolicyDocumentV1, type PaybondPolicyDocumentV2 } from "./schema.js";
+export type PolicyMergeDeniedWidening = {
+    path: string;
+    code: string;
+    message: string;
+};
+export type PolicyMergeReport = {
+    org_policy_id: string | null;
+    org_id: string | null;
+    base_policy_name: string;
+    overlay_policy_name: string | null;
+    overrides_applied: string[];
+    denied_widenings: PolicyMergeDeniedWidening[];
+};
+export type PolicyMergeResult = {
+    effective: PaybondPolicyDocumentV1;
+    report: PolicyMergeReport;
+};
+export type PolicyMergeOptions = {
+    /** When set, tenant evidence_preset swaps must stay within this catalog subset. */
+    approvedEvidencePresets?: readonly string[];
+};
+/**
+ * Deterministically merge an org base policy with a tenant overlay.
+ * Returns a v1 effective document suitable for middleware and validation.
+ */
+export declare function mergePaybondPolicies(base: PaybondPolicyDocumentV1 | PaybondPolicyDocumentV2, overlay: PaybondPolicyDocumentV2, options?: PolicyMergeOptions): PolicyMergeResult;
+/** Normalize any supported policy document to a flat v1 effective document. */
+export declare function toEffectivePolicyDocument(document: PaybondPolicyDocument): PaybondPolicyDocumentV1;