@paybond/kit 0.10.0 → 0.11.1

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;

package/dist/policy/merge.js

@@ -0,0 +1,297 @@
+import { PaybondPolicyValidationError, PAYBOND_POLICY_SCHEMA_VERSION, isPaybondPolicyDocumentV1, isPaybondPolicyOverlay, } from "./schema.js";
+function cloneToolEntry(entry) {
+    return { ...entry };
+}
+function mergeStricterDefaultDeny(...values) {
+    return values.some((value) => value === true);
+}
+function mergeToolFields(base, patch, toolName, report, denied) {
+    const merged = cloneToolEntry(base);
+    if (patch.side_effecting !== undefined) {
+        if (base.side_effecting && patch.side_effecting === false) {
+            denied.push({
+                path: `tools.${toolName}.side_effecting`,
+                code: "policy.cannot_disable_org_side_effecting_tool",
+                message: `cannot disable org-required side-effecting tool "${toolName}"`,
+            });
+        }
+        else {
+            merged.side_effecting = patch.side_effecting;
+            report.overrides_applied.push(`tools.${toolName}.side_effecting`);
+        }
+    }
+    if (patch.max_spend_cents !== undefined) {
+        if (base.max_spend_cents !== undefined &&
+            patch.max_spend_cents > base.max_spend_cents) {
+            denied.push({
+                path: `tools.${toolName}.max_spend_cents`,
+                code: "policy.cannot_raise_spend_cap",
+                message: `tenant max_spend_cents (${patch.max_spend_cents}) exceeds org cap (${base.max_spend_cents})`,
+            });
+        }
+        else {
+            merged.max_spend_cents = patch.max_spend_cents;
+            report.overrides_applied.push(`tools.${toolName}.max_spend_cents`);
+        }
+    }
+    if (patch.spend_from_args !== undefined) {
+        if (base.max_spend_cents !== undefined) {
+            denied.push({
+                path: `tools.${toolName}.spend_from_args`,
+                code: "policy.cannot_override_org_spend_mode",
+                message: `cannot replace org max_spend_cents with spend_from_args on "${toolName}"`,
+            });
+        }
+        else {
+            merged.spend_from_args = patch.spend_from_args;
+            delete merged.max_spend_cents;
+            report.overrides_applied.push(`tools.${toolName}.spend_from_args`);
+        }
+    }
+    if (patch.evidence_preset !== undefined) {
+        if (patch.evidence_preset !== base.evidence_preset &&
+            report.org_policy_id !== null) {
+            // Structural check only; catalog membership is validated downstream.
+            report.overrides_applied.push(`tools.${toolName}.evidence_preset`);
+        }
+        merged.evidence_preset = patch.evidence_preset;
+    }
+    if (patch.vendor_pack !== undefined) {
+        merged.vendor_pack = patch.vendor_pack;
+        report.overrides_applied.push(`tools.${toolName}.vendor_pack`);
+    }
+    if (patch.operation !== undefined) {
+        merged.operation = patch.operation;
+        report.overrides_applied.push(`tools.${toolName}.operation`);
+    }
+    if (merged.side_effecting && !merged.evidence_preset) {
+        denied.push({
+            path: `tools.${toolName}.evidence_preset`,
+            code: "policy.missing_evidence_preset",
+            message: `side-effecting tool "${toolName}" must declare evidence_preset after merge`,
+        });
+    }
+    if (merged.max_spend_cents !== undefined &&
+        merged.spend_from_args !== undefined) {
+        denied.push({
+            path: `tools.${toolName}`,
+            code: "policy.conflicting_spend_fields",
+            message: "max_spend_cents and spend_from_args are mutually exclusive",
+        });
+    }
+    return merged;
+}
+function mergePolicyBinding(base, overlay, override, denied, report) {
+    if (!base && !overlay && !override) {
+        return undefined;
+    }
+    const templateId = override?.template_id ?? overlay?.template_id ?? base?.template_id;
+    if (!templateId) {
+        return undefined;
+    }
+    const merged = { template_id: templateId };
+    const overlayTemplate = overlay?.template_id ?? override?.template_id;
+    if (base?.template_id && overlayTemplate && overlayTemplate !== base.template_id) {
+        denied.push({
+            path: "intent.policy_binding.template_id",
+            code: "policy.cannot_change_org_template",
+            message: `tenant template_id "${overlayTemplate}" must match org template "${base.template_id}"`,
+        });
+    }
+    const versionSeq = override?.version_seq ?? overlay?.version_seq ?? base?.version_seq;
+    if (versionSeq !== undefined) {
+        if (base?.version_seq !== undefined && versionSeq < base.version_seq) {
+            denied.push({
+                path: "intent.policy_binding.version_seq",
+                code: "policy.cannot_downgrade_template_version",
+                message: `tenant version_seq (${versionSeq}) is older than org version_seq (${base.version_seq})`,
+            });
+        }
+        else {
+            merged.version_seq = versionSeq;
+            if (override?.version_seq !== undefined) {
+                report.overrides_applied.push("intent.policy_binding.version_seq");
+            }
+        }
+    }
+    const headDigest = override?.head_digest ?? overlay?.head_digest ?? base?.head_digest;
+    if (headDigest !== undefined) {
+        if (base?.head_digest && headDigest !== base.head_digest) {
+            denied.push({
+                path: "intent.policy_binding.head_digest",
+                code: "policy.cannot_change_org_head_digest",
+                message: "tenant head_digest must match the org-pinned template head",
+            });
+        }
+        else {
+            merged.head_digest = headDigest;
+            if (override?.head_digest !== undefined) {
+                report.overrides_applied.push("intent.policy_binding.head_digest");
+            }
+        }
+    }
+    return merged;
+}
+function mergeBudget(base, overlay, override, denied, report) {
+    const merged = {
+        ...(base ?? {}),
+        ...(overlay ?? {}),
+        ...(override ?? {}),
+    };
+    if (!merged || Object.keys(merged).length === 0) {
+        return undefined;
+    }
+    const orgMax = base?.max_spend_usd;
+    const tenantMax = override?.max_spend_usd ?? overlay?.max_spend_usd;
+    if (orgMax !== undefined && tenantMax !== undefined && tenantMax > orgMax) {
+        denied.push({
+            path: "intent.budget.max_spend_usd",
+            code: "policy.cannot_raise_budget_cap",
+            message: `tenant max_spend_usd (${tenantMax}) exceeds org cap (${orgMax})`,
+        });
+    }
+    else if (override?.max_spend_usd !== undefined) {
+        report.overrides_applied.push("intent.budget.max_spend_usd");
+    }
+    return merged;
+}
+function intersectAllowedTools(orgAllowed, tenantAllowed, denied, report) {
+    if (!tenantAllowed || tenantAllowed.length === 0) {
+        return orgAllowed;
+    }
+    if (!orgAllowed || orgAllowed.length === 0) {
+        return tenantAllowed;
+    }
+    const orgSet = new Set(orgAllowed);
+    const widened = tenantAllowed.filter((tool) => !orgSet.has(tool));
+    if (widened.length > 0) {
+        denied.push({
+            path: "intent.allowed_tools",
+            code: "policy.cannot_widen_allowed_tools",
+            message: `tenant allowed_tools widens org allowlist: ${widened.join(", ")}`,
+        });
+    }
+    const intersection = tenantAllowed.filter((tool) => orgSet.has(tool));
+    if (intersection.length !== tenantAllowed.length) {
+        report.overrides_applied.push("intent.allowed_tools");
+    }
+    return intersection;
+}
+function baseDocumentToEffectiveV1(document) {
+    return {
+        version: PAYBOND_POLICY_SCHEMA_VERSION,
+        name: document.name,
+        default_deny: document.default_deny,
+        tools: Object.fromEntries(Object.entries(document.tools).map(([toolName, entry]) => [toolName, cloneToolEntry(entry)])),
+        intent: document.intent ? structuredClone(document.intent) : undefined,
+    };
+}
+function assertOverlay(document) {
+    if (!isPaybondPolicyOverlay(document)) {
+        throw new PaybondPolicyValidationError("merge requires a tenant overlay document with extends", [{ path: "extends", code: "required", message: "extends is required for overlay merge" }]);
+    }
+}
+/**
+ * Deterministically merge an org base policy with a tenant overlay.
+ * Returns a v1 effective document suitable for middleware and validation.
+ */
+export function mergePaybondPolicies(base, overlay, options = {}) {
+    assertOverlay(overlay);
+    const denied = [];
+    const report = {
+        org_policy_id: overlay.extends.org_policy_id,
+        org_id: overlay.extends.org_id,
+        base_policy_name: base.name,
+        overlay_policy_name: overlay.name,
+        overrides_applied: [],
+        denied_widenings: [],
+    };
+    const effective = baseDocumentToEffectiveV1(base);
+    effective.name = overlay.name;
+    effective.default_deny = mergeStricterDefaultDeny(base.default_deny, overlay.default_deny, overlay.overrides?.default_deny);
+    if (overlay.overrides?.default_deny !== undefined) {
+        report.overrides_applied.push("overrides.default_deny");
+    }
+    for (const [toolName, patch] of Object.entries(overlay.overrides?.tools ?? {})) {
+        const existing = effective.tools[toolName];
+        if (!existing) {
+            denied.push({
+                path: `overrides.tools.${toolName}`,
+                code: "policy.unknown_org_tool_override",
+                message: `cannot override unknown org tool "${toolName}"`,
+            });
+            continue;
+        }
+        effective.tools[toolName] = mergeToolFields(existing, patch, toolName, report, denied);
+    }
+    for (const [toolName, entry] of Object.entries(overlay.tools)) {
+        if (effective.tools[toolName]) {
+            denied.push({
+                path: `tools.${toolName}`,
+                code: "policy.cannot_replace_org_tool",
+                message: `tenant tools must append new entries; "${toolName}" already exists in org base`,
+            });
+            continue;
+        }
+        effective.tools[toolName] = cloneToolEntry(entry);
+    }
+    const orgAllowed = base.intent?.allowed_tools;
+    const tenantAllowed = overlay.overrides?.intent?.allowed_tools ?? overlay.intent?.allowed_tools;
+    const mergedAllowed = intersectAllowedTools(orgAllowed, tenantAllowed, denied, report);
+    if (!overlay.intent && !overlay.overrides?.intent) {
+        effective.intent = base.intent ? structuredClone(base.intent) : undefined;
+        if (mergedAllowed && effective.intent) {
+            effective.intent.allowed_tools = mergedAllowed;
+        }
+    }
+    else {
+        const mergedBinding = mergePolicyBinding(base.intent?.policy_binding, overlay.intent?.policy_binding, overlay.overrides?.intent?.policy_binding, denied, report);
+        const mergedBudget = mergeBudget(base.intent?.budget, overlay.intent?.budget, overlay.overrides?.intent?.budget, denied, report);
+        if (mergedBinding || mergedBudget || mergedAllowed) {
+            effective.intent = {
+                ...(mergedBinding ? { policy_binding: mergedBinding } : {}),
+                ...(mergedBudget ? { budget: mergedBudget } : {}),
+                ...(mergedAllowed ? { allowed_tools: mergedAllowed } : {}),
+            };
+        }
+        else if (base.intent) {
+            effective.intent = structuredClone(base.intent);
+        }
+    }
+    if (options.approvedEvidencePresets) {
+        const approved = new Set(options.approvedEvidencePresets);
+        for (const [toolName, entry] of Object.entries(effective.tools)) {
+            if (!entry.side_effecting || !entry.evidence_preset) {
+                continue;
+            }
+            const basePreset = base.tools[toolName]?.evidence_preset;
+            if (basePreset && entry.evidence_preset !== basePreset && !approved.has(entry.evidence_preset)) {
+                denied.push({
+                    path: `tools.${toolName}.evidence_preset`,
+                    code: "policy.evidence_preset_not_org_approved",
+                    message: `evidence preset "${entry.evidence_preset}" is not in the org-approved catalog subset`,
+                });
+            }
+        }
+    }
+    report.denied_widenings = denied;
+    if (denied.length > 0) {
+        const summary = denied.map((item) => `${item.path}: ${item.message}`).join("; ");
+        throw new PaybondPolicyValidationError(summary, denied.map((item) => ({
+            path: item.path,
+            code: item.code,
+            message: item.message,
+        })));
+    }
+    return { effective, report };
+}
+/** Normalize any supported policy document to a flat v1 effective document. */
+export function toEffectivePolicyDocument(document) {
+    if (isPaybondPolicyDocumentV1(document)) {
+        return baseDocumentToEffectiveV1(document);
+    }
+    if (isPaybondPolicyOverlay(document)) {
+        throw new PaybondPolicyValidationError("tenant overlay requires merge with an org base policy before use", [{ path: "extends", code: "merge_required", message: "resolve inheritance before producing effective policy" }]);
+    }
+    return baseDocumentToEffectiveV1(document);
+}

package/dist/policy/parse-text.d.ts

@@ -0,0 +1,2 @@
+/** Parse policy file text (JSON or YAML) into a raw document object. */
+export declare function parsePolicyDocumentText(text: string, sourceLabel?: string): Record<string, unknown>;