@paybond/kit 0.10.0 → 0.11.1

package/dist/policy/init.js

@@ -0,0 +1,351 @@
+import { access, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { getCompletionPreset } from "../completion-catalog.js";
+import { composePolicyLayers } from "./compose.js";
+import { domain } from "./domain.js";
+import { parseGuardrailSpecs } from "./guardrail-spec.js";
+import { resolveComposedPresetDocument } from "./presets.js";
+import { renderPolicyDocumentYaml } from "./render-yaml.js";
+import { PaybondPolicyValidationError } from "./schema.js";
+import { parsePolicyDocumentText } from "./parse-text.js";
+const ORG_ID_RE = /^org_[a-z][a-z0-9_]*$/;
+const POLICY_NAME_RE = /^[a-z][a-z0-9-]*$/;
+function policyPresetScaffoldHeader(regenerateCommand) {
+    return `# Reference implementation — edit freely. Regenerate with:\n# ${regenerateCommand}\n\n`;
+}
+function applyMaxSpendUsdOverride(document, maxSpendUsdValue) {
+    const cents = Math.round(maxSpendUsdValue * 100);
+    const next = {
+        ...document,
+        tools: Object.fromEntries(Object.entries(document.tools).map(([toolName, entry]) => [
+            toolName,
+            entry.side_effecting ? { ...entry, max_spend_cents: cents } : { ...entry },
+        ])),
+        intent: document.intent
+            ? {
+                ...document.intent,
+                budget: {
+                    ...document.intent.budget,
+                    currency: document.intent.budget?.currency ?? "usd",
+                    max_spend_usd: maxSpendUsdValue,
+                },
+            }
+            : {
+                budget: { currency: "usd", max_spend_usd: maxSpendUsdValue },
+            },
+    };
+    return next;
+}
+function resolvePresetInitDocument(options) {
+    const document = resolveComposedPresetDocument(options.presetId);
+    if (options.maxSpendUsd === undefined) {
+        return document;
+    }
+    return applyMaxSpendUsdOverride(document, options.maxSpendUsd);
+}
+function resolveComposedInitDocument(options) {
+    const layers = parseGuardrailSpecs(options.guardrails);
+    return composePolicyLayers(domain[options.domainId](), ...layers);
+}
+/** Parse `org_id/org_policy_id` extends reference used by CLI and docs. */
+export function parsePolicyExtendsRef(ref) {
+    const trimmed = ref.trim();
+    const slash = trimmed.indexOf("/");
+    if (slash <= 0 || slash === trimmed.length - 1) {
+        throw new PaybondPolicyValidationError("extends must be org_id/org_policy_id (example: org_acme_corp/acme-agent-spend-v1)");
+    }
+    const orgId = trimmed.slice(0, slash);
+    const orgPolicyId = trimmed.slice(slash + 1);
+    if (!ORG_ID_RE.test(orgId)) {
+        throw new PaybondPolicyValidationError(`org_id must match org_<snake_case>: ${orgId}`);
+    }
+    if (!POLICY_NAME_RE.test(orgPolicyId)) {
+        throw new PaybondPolicyValidationError(`org_policy_id must be a lowercase policy name: ${orgPolicyId}`);
+    }
+    return { orgId, orgPolicyId };
+}
+function overlayNameFromPolicyId(orgPolicyId, explicit) {
+    if (explicit?.trim()) {
+        return explicit.trim();
+    }
+    return orgPolicyId.endsWith("-overlay-v1") ? orgPolicyId : `${orgPolicyId}-overlay-v1`;
+}
+function policyNameFromOperation(operation) {
+    const slug = operation
+        .trim()
+        .toLowerCase()
+        .replace(/[._]+/g, "-")
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    const base = slug || "agent";
+    return base.endsWith("-v1") ? base : `${base}-v1`;
+}
+function templateIdStubForPreset(presetId) {
+    try {
+        return getCompletionPreset(presetId).harbor_template_id;
+    }
+    catch {
+        return "completion_v1";
+    }
+}
+/** Render a starter paybond.policy.yaml document. */
+export function renderPaybondPolicyYaml(options) {
+    const operation = options.operation.trim();
+    const evidencePreset = options.evidencePreset.trim();
+    if (!operation) {
+        throw new PaybondPolicyValidationError("operation is required");
+    }
+    if (!evidencePreset) {
+        throw new PaybondPolicyValidationError("evidence preset is required");
+    }
+    getCompletionPreset(evidencePreset);
+    const name = policyNameFromOperation(operation);
+    const templateId = templateIdStubForPreset(evidencePreset);
+    return `version: 1
+name: ${name}
+default_deny: true
+
+tools:
+  ${operation}:
+    side_effecting: true
+    evidence_preset: ${evidencePreset}
+    operation: ${operation}
+
+intent:
+  policy_binding:
+    template_id: ${templateId}
+  allowed_tools:
+    - ${operation}
+`;
+}
+/** Render a v2 org base policy document (no extends). */
+export function renderOrgBasePolicyYaml(options) {
+    const policyId = options.policyId.trim();
+    const operation = options.operation.trim();
+    const evidencePreset = options.evidencePreset.trim();
+    if (!policyId) {
+        throw new PaybondPolicyValidationError("policy_id is required");
+    }
+    if (!POLICY_NAME_RE.test(policyId)) {
+        throw new PaybondPolicyValidationError("policy_id must be a lowercase policy name");
+    }
+    if (!operation) {
+        throw new PaybondPolicyValidationError("operation is required");
+    }
+    if (!evidencePreset) {
+        throw new PaybondPolicyValidationError("evidence preset is required");
+    }
+    getCompletionPreset(evidencePreset);
+    const templateId = templateIdStubForPreset(evidencePreset);
+    const maxSpendLine = options.maxSpendCents !== undefined ? `\n    max_spend_cents: ${options.maxSpendCents}` : "";
+    return `version: 2
+name: ${policyId}
+default_deny: true
+
+tools:
+  ${operation}:
+    side_effecting: true
+    evidence_preset: ${evidencePreset}${maxSpendLine}
+    operation: ${operation}
+
+intent:
+  policy_binding:
+    template_id: ${templateId}
+  allowed_tools:
+    - ${operation}
+`;
+}
+/** Write a v2 org base policy file for platform operators. */
+export async function scaffoldOrgBasePolicy(options) {
+    if (!options.force) {
+        try {
+            await access(options.out, constants.F_OK);
+            throw new PaybondPolicyValidationError(`${options.out} already exists (pass --force to overwrite)`);
+        }
+        catch (err) {
+            if (err instanceof PaybondPolicyValidationError) {
+                throw err;
+            }
+        }
+    }
+    const yaml = renderOrgBasePolicyYaml(options);
+    await writeFile(options.out, yaml, "utf8");
+    return {
+        out: options.out,
+        policy_id: options.policyId.trim(),
+        operation: options.operation.trim(),
+        evidence_preset: options.evidencePreset.trim(),
+        bytes_written: Buffer.byteLength(yaml, "utf8"),
+    };
+}
+/** Render a v2 tenant overlay policy that extends an org base. */
+export function renderTenantOverlayPolicyYaml(options) {
+    const { orgId, orgPolicyId } = parsePolicyExtendsRef(options.extendsRef);
+    const name = overlayNameFromPolicyId(orgPolicyId, options.name);
+    if (!POLICY_NAME_RE.test(name)) {
+        throw new PaybondPolicyValidationError("overlay name must be a lowercase policy name");
+    }
+    const operation = options.operation?.trim();
+    const evidencePreset = options.evidencePreset?.trim();
+    if (operation && !evidencePreset) {
+        throw new PaybondPolicyValidationError("tenant-only tool requires --evidence-preset");
+    }
+    if (evidencePreset && !operation) {
+        throw new PaybondPolicyValidationError("--evidence-preset requires --operation for tenant-only tools");
+    }
+    if (evidencePreset) {
+        getCompletionPreset(evidencePreset);
+    }
+    const basePolicyLine = options.basePolicy?.trim()
+        ? `\n  base_policy: ${options.basePolicy.trim()}`
+        : "";
+    const toolsBlock = operation && evidencePreset
+        ? `tools:
+  ${operation}:
+    side_effecting: true
+    evidence_preset: ${evidencePreset}
+    operation: ${operation}
+`
+        : "";
+    return `version: 2
+name: ${name}
+extends:
+  org_policy_id: ${orgPolicyId}
+  org_id: ${orgId}${basePolicyLine}
+default_deny: true
+
+${toolsBlock}`;
+}
+/** Write a v2 tenant overlay policy file extending an org base. */
+export async function scaffoldTenantOverlayPolicy(options) {
+    const { orgId, orgPolicyId } = parsePolicyExtendsRef(options.extendsRef);
+    const name = overlayNameFromPolicyId(orgPolicyId, options.name);
+    if (!options.force) {
+        try {
+            await access(options.out, constants.F_OK);
+            throw new PaybondPolicyValidationError(`${options.out} already exists (pass --force to overwrite)`);
+        }
+        catch (err) {
+            if (err instanceof PaybondPolicyValidationError) {
+                throw err;
+            }
+        }
+    }
+    const yaml = renderTenantOverlayPolicyYaml(options);
+    await writeFile(options.out, yaml, "utf8");
+    const operation = options.operation?.trim();
+    const evidencePreset = options.evidencePreset?.trim();
+    return {
+        out: options.out,
+        name,
+        org_id: orgId,
+        org_policy_id: orgPolicyId,
+        ...(operation ? { operation } : {}),
+        ...(evidencePreset ? { evidence_preset: evidencePreset } : {}),
+        bytes_written: Buffer.byteLength(yaml, "utf8"),
+    };
+}
+/** Render a bundled preset as editable local YAML with a scaffold header comment. */
+export function renderPolicyPresetScaffoldYaml(presetId, options) {
+    const regenerate = options?.maxSpendUsd !== undefined
+        ? `paybond policy init --preset ${presetId} --max-spend ${options.maxSpendUsd} --force`
+        : `paybond policy init --preset ${presetId} --force`;
+    const body = renderPolicyDocumentYaml(options?.maxSpendUsd !== undefined
+        ? resolvePresetInitDocument({ out: "", presetId, maxSpendUsd: options.maxSpendUsd })
+        : resolveComposedPresetDocument(presetId)).trimEnd();
+    return `${policyPresetScaffoldHeader(regenerate)}${body}\n`;
+}
+/** Render a composed domain + guardrails policy as editable local YAML. */
+export function renderComposedPolicyScaffoldYaml(options) {
+    const regenerate = `paybond policy init --domain ${options.domainId} --guardrails ${options.guardrails} --force`;
+    const body = renderPolicyDocumentYaml(resolveComposedInitDocument(options)).trimEnd();
+    return `${policyPresetScaffoldHeader(regenerate)}${body}\n`;
+}
+/** Preview composed domain + guardrails YAML for `paybond policy presets show`. */
+export function renderComposedPolicyPreviewYaml(options) {
+    return renderPolicyDocumentYaml(resolveComposedInitDocument({ out: "", domainId: options.domainId, guardrails: options.guardrails }));
+}
+/** Preview composed policy YAML for `paybond policy presets show`. */
+export function renderPolicyPresetPreviewYaml(presetId, options) {
+    const document = options?.maxSpendUsd !== undefined
+        ? resolvePresetInitDocument({ out: "", presetId, maxSpendUsd: options.maxSpendUsd })
+        : resolveComposedPresetDocument(presetId);
+    return renderPolicyDocumentYaml(document);
+}
+/** Write a bundled vertical preset to an owned local policy file. */
+export async function scaffoldPolicyFromPreset(options) {
+    if (!options.force) {
+        try {
+            await access(options.out, constants.F_OK);
+            throw new PaybondPolicyValidationError(`${options.out} already exists (pass --force to overwrite)`);
+        }
+        catch (err) {
+            if (err instanceof PaybondPolicyValidationError) {
+                throw err;
+            }
+        }
+    }
+    const yaml = renderPolicyPresetScaffoldYaml(options.presetId, {
+        maxSpendUsd: options.maxSpendUsd,
+    });
+    await writeFile(options.out, yaml, "utf8");
+    const parsed = parsePolicyDocumentText(yaml, options.out);
+    const name = typeof parsed.name === "string" ? parsed.name : options.presetId;
+    return {
+        out: options.out,
+        preset: options.presetId,
+        name,
+        ...(options.maxSpendUsd !== undefined ? { max_spend_usd: options.maxSpendUsd } : {}),
+        bytes_written: Buffer.byteLength(yaml, "utf8"),
+    };
+}
+/** Write a composed domain + guardrails policy file. */
+export async function scaffoldComposedPolicy(options) {
+    if (!options.force) {
+        try {
+            await access(options.out, constants.F_OK);
+            throw new PaybondPolicyValidationError(`${options.out} already exists (pass --force to overwrite)`);
+        }
+        catch (err) {
+            if (err instanceof PaybondPolicyValidationError) {
+                throw err;
+            }
+        }
+    }
+    const yaml = renderComposedPolicyScaffoldYaml(options);
+    await writeFile(options.out, yaml, "utf8");
+    const parsed = parsePolicyDocumentText(yaml, options.out);
+    const name = typeof parsed.name === "string" ? parsed.name : options.domainId;
+    return {
+        out: options.out,
+        domain: options.domainId,
+        guardrails: options.guardrails,
+        name,
+        bytes_written: Buffer.byteLength(yaml, "utf8"),
+    };
+}
+/** Write a starter paybond.policy.yaml file. */
+export async function scaffoldPaybondPolicy(options) {
+    if (!options.force) {
+        try {
+            await access(options.out, constants.F_OK);
+            throw new PaybondPolicyValidationError(`${options.out} already exists (pass --force to overwrite)`);
+        }
+        catch (err) {
+            if (err instanceof PaybondPolicyValidationError) {
+                throw err;
+            }
+            // File does not exist — continue.
+        }
+    }
+    const yaml = renderPaybondPolicyYaml(options);
+    await writeFile(options.out, yaml, "utf8");
+    return {
+        out: options.out,
+        name: policyNameFromOperation(options.operation),
+        operation: options.operation.trim(),
+        evidence_preset: options.evidencePreset.trim(),
+        bytes_written: Buffer.byteLength(yaml, "utf8"),
+    };
+}

package/dist/policy/intent-spec.d.ts

@@ -0,0 +1,52 @@
+import type { CompletionContractSnapshot, PolicyBindingRef, PublishedPolicyHead, SettlementRail } from "../principal-intent.js";
+import { type PaybondPolicyDocumentV1 } from "./schema.js";
+/** Raised when policy intent fields cannot be aligned to a Harbor create payload. */
+export declare class PaybondPolicyIntentSpecError extends Error {
+    constructor(message: string);
+}
+/** Runtime fields required to build a production intent create payload from policy. */
+export type PaybondPolicyIntentCreateOverrides = {
+    principalDid: string;
+    principalSigningSeed: Uint8Array;
+    payeeDid: string;
+    payeeSigningSeed: Uint8Array;
+    deadlineRfc3339: string;
+    settlementRail: SettlementRail;
+    recognitionProof: Record<string, unknown>;
+    publishedPolicyHead: PublishedPolicyHead;
+    intentId?: string;
+    predicateRef?: string;
+    amountCents?: number;
+    currency?: string;
+    budget?: Record<string, unknown>;
+    allowedTools?: string[];
+    completionPresetId?: string;
+    evidenceSchema?: Record<string, unknown>;
+    policyBinding?: PolicyBindingRef;
+};
+/** Params for {@link PaybondIntents.createWithPolicyBinding} derived from policy + runtime signing context. */
+export type PaybondPolicyIntentCreateInput = {
+    principalDid: string;
+    principalSigningSeed: Uint8Array;
+    payeeDid: string;
+    payeeSigningSeed: Uint8Array;
+    budget: Record<string, unknown>;
+    currency: string;
+    amountCents: number;
+    evidenceSchema: Record<string, unknown>;
+    deadlineRfc3339: string;
+    allowedTools: string[];
+    settlementRail: SettlementRail;
+    policyBinding: PolicyBindingRef;
+    publishedPolicyHead: PublishedPolicyHead;
+    recognitionProof: Record<string, unknown>;
+    intentId?: string;
+    predicateRef?: string;
+    completionPresetId?: string;
+    completionContract?: CompletionContractSnapshot;
+};
+/**
+ * Build {@link PaybondIntents.createWithPolicyBinding} input from a validated policy document.
+ * Merges policy intent alignment (`allowed_tools`, `budget`, `policy_binding`) with caller signing context.
+ */
+export declare function policyToIntentCreateInput(document: PaybondPolicyDocumentV1, overrides: PaybondPolicyIntentCreateOverrides): PaybondPolicyIntentCreateInput;

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