@paybond/kit 0.9.8 → 0.11.0

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>;

package/dist/policy/parse-text.js

@@ -0,0 +1,126 @@
+import { PaybondPolicyValidationError } from "./schema.js";
+function tokenizeYamlLines(text) {
+    const lines = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const trimmed = raw.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const indent = raw.search(/\S/);
+        if (indent < 0) {
+            continue;
+        }
+        lines.push({ indent, trimmed, raw });
+    }
+    return lines;
+}
+function parseYamlScalar(value) {
+    if (!value) {
+        return "";
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    if (/^-?\d+$/.test(value)) {
+        return Number.parseInt(value, 10);
+    }
+    if (/^-?\d+\.\d+$/.test(value)) {
+        return Number.parseFloat(value);
+    }
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function parseYamlBlock(lines, start, indent, sourceLabel) {
+    if (start >= lines.length || lines[start].indent < indent) {
+        return [{}, start];
+    }
+    if (lines[start].trimmed.startsWith("- ")) {
+        const items = [];
+        let index = start;
+        while (index < lines.length &&
+            lines[index].indent === indent &&
+            lines[index].trimmed.startsWith("- ")) {
+            const afterDash = lines[index].trimmed.slice(2).trim();
+            if (!afterDash) {
+                const [child, next] = parseYamlBlock(lines, index + 1, indent + 2, sourceLabel);
+                items.push(child);
+                index = next;
+                continue;
+            }
+            const inlineMap = /^([^:]+?):\s*(.*)$/.exec(afterDash);
+            if (inlineMap && !inlineMap[2]) {
+                const key = inlineMap[1].trim();
+                const [child, next] = parseYamlBlock(lines, index + 1, indent + 2, sourceLabel);
+                items.push({ [key]: child });
+                index = next;
+                continue;
+            }
+            if (inlineMap) {
+                items.push({
+                    [inlineMap[1].trim()]: parseYamlScalar(inlineMap[2].trim()),
+                });
+                index += 1;
+                continue;
+            }
+            items.push(parseYamlScalar(afterDash));
+            index += 1;
+        }
+        return [items, index];
+    }
+    const objectValue = {};
+    let index = start;
+    while (index < lines.length && lines[index].indent === indent) {
+        const match = /^([^:]+?):\s*(.*)$/.exec(lines[index].trimmed);
+        if (!match) {
+            throw new PaybondPolicyValidationError(`${sourceLabel} has invalid YAML line: ${lines[index].raw}`);
+        }
+        const key = match[1].trim();
+        const rest = match[2].trim();
+        if (rest) {
+            objectValue[key] = parseYamlScalar(rest);
+            index += 1;
+            continue;
+        }
+        const [child, next] = parseYamlBlock(lines, index + 1, indent + 2, sourceLabel);
+        objectValue[key] = child;
+        index = next;
+    }
+    return [objectValue, index];
+}
+function parseIndentedYaml(text, sourceLabel) {
+    const lines = tokenizeYamlLines(text);
+    if (lines.length === 0) {
+        throw new PaybondPolicyValidationError(`${sourceLabel} is empty`);
+    }
+    const [value] = parseYamlBlock(lines, 0, lines[0].indent, sourceLabel);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new PaybondPolicyValidationError(`${sourceLabel} must be a YAML object`);
+    }
+    return value;
+}
+/** Parse policy file text (JSON or YAML) into a raw document object. */
+export function parsePolicyDocumentText(text, sourceLabel = "policy file") {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        throw new PaybondPolicyValidationError(`${sourceLabel} is empty`);
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new PaybondPolicyValidationError(`${sourceLabel} must be a JSON object`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof PaybondPolicyValidationError) {
+            throw err;
+        }
+        return parseIndentedYaml(trimmed, sourceLabel);
+    }
+}

package/dist/policy/policy-api.d.ts

@@ -0,0 +1,45 @@
+import { maxSpend, maxSpendUsd, type PolicyGuardrailLayer } from "./guardrails.js";
+import { PaybondPolicy } from "./load.js";
+import { isLayeredPolicyPresetId } from "./presets.js";
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+export type VerticalPolicyOptions = {
+    /** Per side-effecting tool spend cap in cents. */
+    maxSpend?: number;
+    /** Intent budget cap in USD. */
+    maxSpendUsd?: number;
+    /** Additional guardrail layers applied after bundled defaults. */
+    guardrails?: PolicyGuardrailLayer[];
+};
+declare function composeToPolicy(domainDocument: PaybondPolicyDocumentV1, ...layers: PolicyGuardrailLayer[]): PaybondPolicy;
+/** Programmatic policy composition API (`paybond.policyPresets.*`). */
+export declare const paybondPolicyPresets: {
+    readonly travel: (options?: VerticalPolicyOptions) => PaybondPolicy;
+    readonly shopping: (options?: VerticalPolicyOptions) => PaybondPolicy;
+    readonly saas: (options?: VerticalPolicyOptions) => PaybondPolicy;
+    readonly aws: (options?: VerticalPolicyOptions) => PaybondPolicy;
+    readonly readOnly: () => PaybondPolicy;
+    readonly strict: () => PaybondPolicy;
+    readonly compose: typeof composeToPolicy;
+    readonly domain: {
+        readonly travel: typeof import("./domain.js").travel;
+        readonly shopping: typeof import("./domain.js").shopping;
+        readonly saas: typeof import("./domain.js").saas;
+        readonly aws: typeof import("./domain.js").aws;
+    };
+    readonly guardrails: {
+        readonly defaultDeny: typeof import("./guardrails.js").defaultDeny;
+        readonly maxSpend: typeof maxSpend;
+        readonly maxSpendUsd: typeof maxSpendUsd;
+        readonly readOnly: typeof import("./guardrails.js").readOnly;
+        readonly readOnlySearch: typeof import("./guardrails.js").readOnlySearch;
+        readonly strict: typeof import("./guardrails.js").strict;
+        readonly requireEvidence: typeof import("./guardrails.js").requireEvidence;
+        readonly auditOnly: typeof import("./guardrails.js").auditOnly;
+        readonly allowDryRun: typeof import("./guardrails.js").allowDryRun;
+        readonly fromDocument: typeof import("./guardrails.js").guardrailLayerFromDocument;
+    };
+    readonly resolvePresetDocument: (presetId: string) => PaybondPolicyDocumentV1;
+    readonly isLayeredPreset: typeof isLayeredPolicyPresetId;
+};
+export type PaybondPolicyPresets = typeof paybondPolicyPresets;
+export {};

package/dist/policy/policy-api.js

@@ -0,0 +1,61 @@
+import { bundledDefaultGuardrails, composeBundledPresetDefault, composePolicyLayers, } from "./compose.js";
+import { domain } from "./domain.js";
+import { guardrails, maxSpend, maxSpendUsd } from "./guardrails.js";
+import { PaybondPolicy } from "./load.js";
+import { isKnownPolicyPresetId, isLayeredPolicyPresetId, resolveComposedPresetDocument, } from "./presets.js";
+function verticalPolicy(presetId, options) {
+    const hasCustomizations = options?.maxSpend !== undefined ||
+        options?.maxSpendUsd !== undefined ||
+        (options?.guardrails?.length ?? 0) > 0;
+    if (!hasCustomizations) {
+        return PaybondPolicy.fromDocument(composeBundledPresetDefault(presetId));
+    }
+    const layers = [...bundledDefaultGuardrails(presetId)];
+    if (options?.maxSpend !== undefined) {
+        layers.push(maxSpend(options.maxSpend));
+    }
+    if (options?.maxSpendUsd !== undefined) {
+        layers.push(maxSpendUsd(options.maxSpendUsd));
+    }
+    if (options?.guardrails?.length) {
+        layers.push(...options.guardrails);
+    }
+    return PaybondPolicy.fromDocument(composePolicyLayers(domain[presetId](), ...layers));
+}
+function composeToPolicy(domainDocument, ...layers) {
+    return PaybondPolicy.fromDocument(composePolicyLayers(domainDocument, ...layers));
+}
+function presetPolicy(presetId) {
+    return PaybondPolicy.fromDocument(resolveComposedPresetDocument(presetId));
+}
+/** Programmatic policy composition API (`paybond.policyPresets.*`). */
+export const paybondPolicyPresets = {
+    travel(options) {
+        return verticalPolicy("travel", options);
+    },
+    shopping(options) {
+        return verticalPolicy("shopping", options);
+    },
+    saas(options) {
+        return verticalPolicy("saas", options);
+    },
+    aws(options) {
+        return verticalPolicy("aws", options);
+    },
+    readOnly() {
+        return presetPolicy("read-only");
+    },
+    strict() {
+        return presetPolicy("strict");
+    },
+    compose: composeToPolicy,
+    domain,
+    guardrails,
+    resolvePresetDocument(presetId) {
+        if (!isKnownPolicyPresetId(presetId)) {
+            throw new Error(`unknown policy preset: ${presetId}`);
+        }
+        return resolveComposedPresetDocument(presetId);
+    },
+    isLayeredPreset: isLayeredPolicyPresetId,
+};

package/dist/policy/presets.d.ts

@@ -0,0 +1,19 @@
+import type { LayeredPolicyPresetId } from "./compose.js";
+import { type PaybondPolicyDocumentV1 } from "./schema.js";
+export type { LayeredPolicyPresetId };
+declare const KNOWN_POLICY_PRESET_IDS: readonly ["travel", "shopping", "saas", "aws", "read-only", "strict"];
+export type PolicyPresetId = (typeof KNOWN_POLICY_PRESET_IDS)[number];
+/** True when `value` is a bundled vertical policy preset id (not a file path). */
+export declare function isKnownPolicyPresetId(value: string): value is PolicyPresetId;
+/** True when the preset is composed from domain + guardrails layers. */
+export declare function isLayeredPolicyPresetId(value: string): value is LayeredPolicyPresetId;
+/** List bundled vertical policy preset ids shipped with Paybond Kit. */
+export declare function listPolicyPresetIds(): PolicyPresetId[];
+/** Resolve a bundled preset id to an on-disk `paybond.policy.yaml` path. */
+export declare function resolvePolicyPresetPath(presetId: string): string;
+/** Load a bundled vertical policy preset as YAML text (for tests and scaffolding). */
+export declare function readPolicyPresetYaml(presetId: PolicyPresetId): string;
+/** Resolve a bundled preset to its composed v1 policy document. */
+export declare function resolveComposedPresetDocument(presetId: PolicyPresetId): PaybondPolicyDocumentV1;
+/** @deprecated Internal alias used by YAML flat-file parity checks. */
+export declare function readComposedPresetYamlObject(presetId: LayeredPolicyPresetId): Record<string, unknown>;

package/dist/policy/presets.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { composeBundledPresetDefault, composeLayeredPolicyPresetDocument, isLayeredPolicyPreset, } from "./compose.js";
+import { parsePolicyDocumentText } from "./parse-text.js";
+import { parsePaybondPolicyDocumentV1, } from "./schema.js";
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const KNOWN_POLICY_PRESET_IDS = [
+    "travel",
+    "shopping",
+    "saas",
+    "aws",
+    "read-only",
+    "strict",
+];
+function presetCandidatePaths(presetId) {
+    const fileName = `${presetId}.yaml`;
+    const roots = [
+        join(MODULE_DIR, "../../policy/presets"),
+        join(MODULE_DIR, "../../../policy/presets"),
+        join(MODULE_DIR, "../../../../kit/policy/presets"),
+    ];
+    return roots.map((root) => join(root, fileName));
+}
+/** True when `value` is a bundled vertical policy preset id (not a file path). */
+export function isKnownPolicyPresetId(value) {
+    return KNOWN_POLICY_PRESET_IDS.includes(value.trim());
+}
+/** True when the preset is composed from domain + guardrails layers. */
+export function isLayeredPolicyPresetId(value) {
+    return isLayeredPolicyPreset(value);
+}
+/** List bundled vertical policy preset ids shipped with Paybond Kit. */
+export function listPolicyPresetIds() {
+    return [...KNOWN_POLICY_PRESET_IDS];
+}
+/** Resolve a bundled preset id to an on-disk `paybond.policy.yaml` path. */
+export function resolvePolicyPresetPath(presetId) {
+    const trimmed = presetId.trim();
+    if (!isKnownPolicyPresetId(trimmed)) {
+        throw new Error(`unknown policy preset: ${trimmed}`);
+    }
+    for (const candidate of presetCandidatePaths(trimmed)) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`policy preset file not found for: ${trimmed}`);
+}
+/** Load a bundled vertical policy preset as YAML text (for tests and scaffolding). */
+export function readPolicyPresetYaml(presetId) {
+    const path = resolvePolicyPresetPath(presetId);
+    return readFileSync(path, "utf8");
+}
+/** Resolve a bundled preset to its composed v1 policy document. */
+export function resolveComposedPresetDocument(presetId) {
+    if (isLayeredPolicyPreset(presetId)) {
+        return composeBundledPresetDefault(presetId);
+    }
+    const flatPath = resolvePolicyPresetPath(presetId);
+    return parsePaybondPolicyDocumentV1(parsePolicyDocumentText(readPolicyPresetYaml(presetId), flatPath));
+}
+/** @deprecated Internal alias used by YAML flat-file parity checks. */
+export function readComposedPresetYamlObject(presetId) {
+    return composeLayeredPolicyPresetDocument(presetId);
+}

package/dist/policy/registry.d.ts

@@ -0,0 +1,7 @@
+import { PaybondToolRegistry } from "../agent/registry.js";
+import { PaybondToolRegistryConfig } from "../agent/types.js";
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+/** Convert a validated policy document into middleware registry config. */
+export declare function policyDocumentToToolRegistryConfig(document: PaybondPolicyDocumentV1): PaybondToolRegistryConfig;
+/** Build a validated {@link PaybondToolRegistry} from a policy document. */
+export declare function policyToToolRegistry(document: PaybondPolicyDocumentV1): PaybondToolRegistry;

package/dist/policy/registry.js

@@ -0,0 +1,33 @@
+import { createPaybondToolRegistry } from "../agent/registry.js";
+import { resolveSpendCentsFromJsonPath } from "./json-path.js";
+/** Convert a validated policy document into middleware registry config. */
+export function policyDocumentToToolRegistryConfig(document) {
+    const sideEffecting = {};
+    for (const [toolName, entry] of Object.entries(document.tools)) {
+        if (!entry.side_effecting) {
+            continue;
+        }
+        const policy = {
+            evidencePreset: entry.evidence_preset,
+        };
+        if (entry.operation?.trim()) {
+            policy.operation = entry.operation.trim();
+        }
+        if (entry.max_spend_cents !== undefined) {
+            policy.spendCents = entry.max_spend_cents;
+        }
+        else if (entry.spend_from_args) {
+            const path = entry.spend_from_args;
+            policy.spendCents = (args) => resolveSpendCentsFromJsonPath(args, path, toolName);
+        }
+        sideEffecting[toolName] = policy;
+    }
+    return {
+        defaultDeny: document.default_deny,
+        sideEffecting,
+    };
+}
+/** Build a validated {@link PaybondToolRegistry} from a policy document. */
+export function policyToToolRegistry(document) {
+    return createPaybondToolRegistry(policyDocumentToToolRegistryConfig(document));
+}