@paybond/kit 0.9.8 → 0.11.0

package/dist/policy/schema.d.ts

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

package/dist/policy/schema.js

@@ -0,0 +1,255 @@
+import { z } from "zod";
+/** Supported `paybond.policy.yaml` schema revisions. */
+export const PAYBOND_POLICY_SCHEMA_VERSION = 1;
+export const PAYBOND_POLICY_SCHEMA_VERSION_V2 = 2;
+const IDENTIFIER_PATTERN = /^[a-z0-9_]{1,64}$/;
+const POLICY_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_.-]{0,127}$/;
+const JSON_PATH_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
+const HEAD_DIGEST_PATTERN = /^sha256:[0-9a-fA-F]{64}$/;
+const CURRENCY_PATTERN = /^[a-z]{3}$/;
+const ORG_ID_PATTERN = /^org_[a-z][a-z0-9_]{0,57}$/;
+const identifierSchema = z
+    .string()
+    .regex(IDENTIFIER_PATTERN, "must be snake_case identifier (1-64 chars)");
+const toolNameSchema = z
+    .string()
+    .regex(TOOL_NAME_PATTERN, "must be a lowercase tool name (dots allowed)");
+const jsonPathSchema = z
+    .string()
+    .regex(JSON_PATH_PATTERN, "must be a dot-separated JSON path");
+const headDigestSchema = z
+    .string()
+    .regex(HEAD_DIGEST_PATTERN, "must be sha256:<64-hex>");
+const orgIdSchema = z
+    .string()
+    .regex(ORG_ID_PATTERN, "must be an org identifier (org_<snake_case>)");
+function refineSpendExclusivity(entry, ctx, pathPrefix) {
+    if (entry.max_spend_cents !== undefined &&
+        entry.spend_from_args !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: [...pathPrefix, "spend_from_args"],
+            message: "max_spend_cents and spend_from_args are mutually exclusive",
+        });
+    }
+}
+function refineSideEffectingEvidence(entry, ctx, pathPrefix) {
+    if (entry.side_effecting && !entry.evidence_preset) {
+        ctx.addIssue({
+            code: "custom",
+            path: [...pathPrefix, "evidence_preset"],
+            message: "side-effecting tools must declare evidence_preset",
+        });
+    }
+}
+const policyToolEntrySchema = z
+    .object({
+    side_effecting: z.boolean(),
+    max_spend_cents: z.number().int().nonnegative().optional(),
+    spend_from_args: jsonPathSchema.optional(),
+    evidence_preset: identifierSchema.optional(),
+    vendor_pack: identifierSchema.optional(),
+    operation: z.string().min(1).max(128).optional(),
+})
+    .strict()
+    .superRefine((entry, ctx) => {
+    refineSideEffectingEvidence(entry, ctx, []);
+    refineSpendExclusivity(entry, ctx, []);
+});
+const policyToolOverrideEntrySchema = z
+    .object({
+    side_effecting: z.boolean().optional(),
+    max_spend_cents: z.number().int().nonnegative().optional(),
+    spend_from_args: jsonPathSchema.optional(),
+    evidence_preset: identifierSchema.optional(),
+    vendor_pack: identifierSchema.optional(),
+    operation: z.string().min(1).max(128).optional(),
+})
+    .strict()
+    .superRefine((entry, ctx) => {
+    if (Object.keys(entry).length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: [],
+            message: "tool override must set at least one field",
+        });
+    }
+    refineSideEffectingEvidence(entry, ctx, []);
+    refineSpendExclusivity(entry, ctx, []);
+});
+const policyBindingSchema = z
+    .object({
+    template_id: identifierSchema,
+    version_seq: z.number().int().positive().optional(),
+    head_digest: headDigestSchema.optional(),
+})
+    .strict();
+const policyBindingOverrideSchema = z
+    .object({
+    template_id: identifierSchema.optional(),
+    version_seq: z.number().int().positive().optional(),
+    head_digest: headDigestSchema.optional(),
+})
+    .strict()
+    .superRefine((binding, ctx) => {
+    if (Object.keys(binding).length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: [],
+            message: "policy_binding override must set at least one field",
+        });
+    }
+});
+const policyBudgetSchema = z
+    .object({
+    currency: z.string().regex(CURRENCY_PATTERN, "must be a lowercase ISO-4217 code"),
+    max_spend_usd: z.number().nonnegative().optional(),
+})
+    .passthrough();
+const policyIntentSchema = z
+    .object({
+    policy_binding: policyBindingSchema.optional(),
+    budget: policyBudgetSchema.optional(),
+    allowed_tools: z.array(toolNameSchema).optional(),
+})
+    .strict();
+const policyIntentOverrideSchema = z
+    .object({
+    policy_binding: policyBindingOverrideSchema.optional(),
+    budget: policyBudgetSchema.optional(),
+    allowed_tools: z.array(toolNameSchema).optional(),
+})
+    .strict()
+    .superRefine((intent, ctx) => {
+    if (Object.keys(intent).length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: [],
+            message: "intent override must set at least one field",
+        });
+    }
+});
+const policyExtendsSchema = z
+    .object({
+    org_policy_id: z
+        .string()
+        .regex(POLICY_NAME_PATTERN, "must be a lowercase policy name"),
+    org_id: orgIdSchema,
+    base_digest: headDigestSchema.optional(),
+    base_policy: z.string().min(1).max(512).optional(),
+})
+    .strict();
+const policyOverridesSchema = z
+    .object({
+    default_deny: z.boolean().optional(),
+    tools: z.record(toolNameSchema, policyToolOverrideEntrySchema).optional(),
+    intent: policyIntentOverrideSchema.optional(),
+})
+    .strict()
+    .superRefine((overrides, ctx) => {
+    if (overrides.default_deny === undefined &&
+        !overrides.tools &&
+        !overrides.intent) {
+        ctx.addIssue({
+            code: "custom",
+            path: [],
+            message: "overrides must set default_deny, tools, and/or intent",
+        });
+    }
+});
+export const paybondPolicyDocumentV1Schema = z
+    .object({
+    version: z.literal(PAYBOND_POLICY_SCHEMA_VERSION),
+    name: z.string().regex(POLICY_NAME_PATTERN, "must be a lowercase policy name"),
+    default_deny: z.boolean(),
+    tools: z
+        .record(toolNameSchema, policyToolEntrySchema)
+        .refine((tools) => Object.keys(tools).length > 0, {
+        message: "tools must declare at least one entry",
+    }),
+    intent: policyIntentSchema.optional(),
+})
+    .strict();
+export const paybondPolicyDocumentV2Schema = z
+    .object({
+    version: z.literal(PAYBOND_POLICY_SCHEMA_VERSION_V2),
+    name: z.string().regex(POLICY_NAME_PATTERN, "must be a lowercase policy name"),
+    default_deny: z.boolean(),
+    extends: policyExtendsSchema.optional(),
+    overrides: policyOverridesSchema.optional(),
+    tools: z.record(toolNameSchema, policyToolEntrySchema),
+    intent: policyIntentSchema.optional(),
+})
+    .strict()
+    .superRefine((document, ctx) => {
+    if (!document.extends && Object.keys(document.tools).length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["tools"],
+            message: "tools must declare at least one entry when extends is omitted",
+        });
+    }
+});
+/** Raised when a policy document fails schema validation. */
+export class PaybondPolicyValidationError extends Error {
+    issues;
+    constructor(message, issues = []) {
+        super(message);
+        this.name = "PaybondPolicyValidationError";
+        this.issues = issues;
+    }
+}
+function zodIssuesToPolicyIssues(issues) {
+    return issues.map((issue) => ({
+        path: issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)",
+        code: issue.code,
+        message: issue.message,
+    }));
+}
+function parseWithSchema(schema, raw) {
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        const issues = zodIssuesToPolicyIssues(result.error.issues);
+        const summary = issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+        throw new PaybondPolicyValidationError(summary || "invalid paybond.policy.yaml document", issues);
+    }
+    return result.data;
+}
+/**
+ * Parse and validate a raw policy document (already-decoded JSON or YAML object).
+ * Accepts v1 flat policies and v2 org-base or tenant-overlay documents.
+ */
+export function parsePaybondPolicyDocument(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new PaybondPolicyValidationError("(root) must be an object");
+    }
+    const version = raw.version;
+    if (version === PAYBOND_POLICY_SCHEMA_VERSION) {
+        return parseWithSchema(paybondPolicyDocumentV1Schema, raw);
+    }
+    if (version === PAYBOND_POLICY_SCHEMA_VERSION_V2) {
+        return parseWithSchema(paybondPolicyDocumentV2Schema, raw);
+    }
+    throw new PaybondPolicyValidationError(`version must be ${PAYBOND_POLICY_SCHEMA_VERSION} or ${PAYBOND_POLICY_SCHEMA_VERSION_V2}`, [{ path: "version", code: "invalid_literal", message: "unsupported policy schema version" }]);
+}
+/** Parse a v1-only policy document. */
+export function parsePaybondPolicyDocumentV1(raw) {
+    return parseWithSchema(paybondPolicyDocumentV1Schema, raw);
+}
+/** Parse a v2 policy document (org base or tenant overlay). */
+export function parsePaybondPolicyDocumentV2(raw) {
+    return parseWithSchema(paybondPolicyDocumentV2Schema, raw);
+}
+/** Type guard for an already-validated v1 policy document. */
+export function isPaybondPolicyDocumentV1(value) {
+    return paybondPolicyDocumentV1Schema.safeParse(value).success;
+}
+/** Type guard for an already-validated v2 policy document. */
+export function isPaybondPolicyDocumentV2(value) {
+    return paybondPolicyDocumentV2Schema.safeParse(value).success;
+}
+/** True when a v2 document is a tenant overlay (declares extends). */
+export function isPaybondPolicyOverlay(document) {
+    return document.extends !== undefined;
+}

package/dist/policy/snapshot.d.ts

@@ -0,0 +1,33 @@
+import type { PaybondToolRegistry } from "../agent/registry.js";
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+export type PaybondPolicySnapshotSource = "file" | "remote" | "effective";
+/** Versioned policy snapshot loaded at bind time (Tier 7 hot-reload foundation). */
+export type PaybondPolicySnapshot = {
+    /** `sha256:<hex>` digest of the canonical policy JSON. */
+    digest: string;
+    /** `{policy_name}@{digest_short}` label for audit and status output. */
+    version: string;
+    /** RFC3339 timestamp when this snapshot was loaded. */
+    loadedAt: string;
+    source: PaybondPolicySnapshotSource;
+    registry: PaybondToolRegistry;
+    /** Effective policy document backing this snapshot (used for reload loosening checks). */
+    document: PaybondPolicyDocumentV1;
+};
+export type CreatePolicySnapshotInput = {
+    document: PaybondPolicyDocumentV1;
+    registry: PaybondToolRegistry;
+    source: PaybondPolicySnapshotSource;
+    /** When omitted, digest is computed locally from the document. */
+    digest?: string;
+    loadedAt?: string;
+};
+/** Build a policy snapshot for {@link PaybondAgentRun.bind}. */
+export declare function createPolicySnapshot(input: CreatePolicySnapshotInput): PaybondPolicySnapshot;
+/** Build a snapshot from a Gateway effective-policy resolution. */
+export declare function createPolicySnapshotFromEffective(input: {
+    document: PaybondPolicyDocumentV1;
+    registry: PaybondToolRegistry;
+    effectivePolicyDigest: string;
+    loadedAt?: string;
+}): PaybondPolicySnapshot;

package/dist/policy/snapshot.js

@@ -0,0 +1,23 @@
+import { canonicalPolicyDocumentDigest, policyVersionLabel } from "./digest.js";
+/** Build a policy snapshot for {@link PaybondAgentRun.bind}. */
+export function createPolicySnapshot(input) {
+    const digest = input.digest?.trim() || canonicalPolicyDocumentDigest(input.document);
+    return {
+        digest,
+        version: policyVersionLabel(input.document.name, digest),
+        loadedAt: input.loadedAt ?? new Date().toISOString(),
+        source: input.source,
+        registry: input.registry,
+        document: input.document,
+    };
+}
+/** Build a snapshot from a Gateway effective-policy resolution. */
+export function createPolicySnapshotFromEffective(input) {
+    return createPolicySnapshot({
+        document: input.document,
+        registry: input.registry,
+        source: "effective",
+        digest: input.effectivePolicyDigest,
+        loadedAt: input.loadedAt,
+    });
+}

package/dist/policy/validate-remote.d.ts

@@ -0,0 +1,43 @@
+import type { PolicyMergeReport } from "./merge.js";
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+export type PolicyRemoteValidateIssue = {
+    path: string;
+    code: string;
+    message: string;
+};
+export type PolicyRemoteValidateCheck = {
+    name: string;
+    passed: boolean;
+};
+export type PolicyRemoteValidateResult = {
+    valid: boolean;
+    local_valid: boolean;
+    remote_valid: boolean;
+    policy_name: string | null;
+    tenant_id: string;
+    errors: PolicyRemoteValidateIssue[];
+    warnings: PolicyRemoteValidateIssue[];
+    checks: PolicyRemoteValidateCheck[];
+    effective_policy_digest?: string;
+    merge_report?: PolicyMergeReport;
+};
+export type PolicyRemoteValidateOptions = {
+    /** When true, side-effecting tools must appear in intent.allowed_tools when that list is set. */
+    strict?: boolean;
+    /** When true, treat the body as a v2 tenant overlay and merge org base server-side. */
+    resolveInheritance?: boolean;
+};
+/** Gateway client surface used by {@link validatePolicyRemote}. */
+export type PolicyRemoteValidateClient = {
+    validatePolicy(document: Record<string, unknown>, options?: PolicyRemoteValidateOptions): Promise<PolicyRemoteValidateResult>;
+};
+/** Build query parameters for Gateway `POST /v1/policy/validate`. */
+export declare function policyValidateQueryString(options?: PolicyRemoteValidateOptions): string;
+/** Parse a Gateway `POST /v1/policy/validate` JSON body. */
+export declare function parsePolicyRemoteValidateResponse(body: unknown): PolicyRemoteValidateResult;
+/** Serialize a remote validation report for CLI or logging output. */
+export declare function policyRemoteValidateResultToDict(result: PolicyRemoteValidateResult): Record<string, unknown>;
+/** Validate a raw policy payload against the tenant-scoped Gateway registry endpoint. */
+export declare function validatePolicyPayloadRemote(document: Record<string, unknown>, client: PolicyRemoteValidateClient, options?: PolicyRemoteValidateOptions): Promise<PolicyRemoteValidateResult>;
+/** Validate a policy document against the tenant-scoped Gateway registry endpoint. */
+export declare function validatePolicyRemote(document: PaybondPolicyDocumentV1, client: PolicyRemoteValidateClient, options?: PolicyRemoteValidateOptions): Promise<PolicyRemoteValidateResult>;

package/dist/policy/validate-remote.js

@@ -0,0 +1,104 @@
+import { policyDocumentToDict } from "./digest.js";
+import { parseMergeReport } from "./load-effective.js";
+function parseIssue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const row = value;
+    const path = String(row.path ?? "");
+    const code = String(row.code ?? "");
+    const message = String(row.message ?? "");
+    if (!path || !code || !message) {
+        return null;
+    }
+    return { path, code, message };
+}
+function parseCheck(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const row = value;
+    const name = String(row.name ?? "");
+    if (!name || typeof row.passed !== "boolean") {
+        return null;
+    }
+    return { name, passed: row.passed };
+}
+/** Build query parameters for Gateway `POST /v1/policy/validate`. */
+export function policyValidateQueryString(options = {}) {
+    const params = new URLSearchParams();
+    if (options.strict) {
+        params.set("strict", "1");
+    }
+    if (options.resolveInheritance) {
+        params.set("resolve_inheritance", "1");
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
+/** Parse a Gateway `POST /v1/policy/validate` JSON body. */
+export function parsePolicyRemoteValidateResponse(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+        throw new Error("policy validate response must be a JSON object");
+    }
+    const row = body;
+    const errors = Array.isArray(row.errors)
+        ? row.errors.map(parseIssue).filter((issue) => issue !== null)
+        : [];
+    const warnings = Array.isArray(row.warnings)
+        ? row.warnings.map(parseIssue).filter((issue) => issue !== null)
+        : [];
+    const checks = Array.isArray(row.checks)
+        ? row.checks.map(parseCheck).filter((check) => check !== null)
+        : [];
+    const result = {
+        valid: Boolean(row.valid),
+        local_valid: Boolean(row.local_valid),
+        remote_valid: Boolean(row.remote_valid),
+        policy_name: row.policy_name === null || row.policy_name === undefined
+            ? null
+            : String(row.policy_name),
+        tenant_id: String(row.tenant_id ?? ""),
+        errors,
+        warnings,
+        checks,
+    };
+    if (row.effective_policy_digest != null) {
+        const digest = String(row.effective_policy_digest);
+        if (digest) {
+            result.effective_policy_digest = digest;
+        }
+    }
+    if (row.merge_report != null) {
+        result.merge_report = parseMergeReport(row.merge_report);
+    }
+    return result;
+}
+/** Serialize a remote validation report for CLI or logging output. */
+export function policyRemoteValidateResultToDict(result) {
+    const payload = {
+        valid: result.valid,
+        local_valid: result.local_valid,
+        remote_valid: result.remote_valid,
+        policy_name: result.policy_name,
+        tenant_id: result.tenant_id,
+        errors: result.errors,
+        warnings: result.warnings,
+        checks: result.checks,
+    };
+    if (result.effective_policy_digest) {
+        payload.effective_policy_digest = result.effective_policy_digest;
+    }
+    if (result.merge_report) {
+        payload.merge_report = result.merge_report;
+    }
+    return payload;
+}
+/** Validate a raw policy payload against the tenant-scoped Gateway registry endpoint. */
+export async function validatePolicyPayloadRemote(document, client, options = {}) {
+    return client.validatePolicy(document, options);
+}
+/** Validate a policy document against the tenant-scoped Gateway registry endpoint. */
+export async function validatePolicyRemote(document, client, options = {}) {
+    return validatePolicyPayloadRemote(policyDocumentToDict(document), client, options);
+}