@paybond/kit 0.10.0 → 0.11.0

package/dist/completion-contract-digest.d.ts

@@ -0,0 +1,37 @@
+/**
+ * BLAKE3 digests for completion preset vendor_contract schema pinning.
+ * Matches `paybond-evidence::json_value_digest` and Harbor signing digests.
+ */
+import type { CompletionPreset } from "./completion-catalog.js";
+export type VendorContract = {
+    provider: "stripe" | "x402" | "mcp" | "generic";
+    api_version: string;
+    contract_kind: "json_schema" | "openapi_fragment" | "mapper_version";
+    schema_digest_hex: string;
+    canonical_schema_digest_hex: string;
+    quality_fields: string[];
+    supersedes?: string;
+    migration_notes?: string;
+};
+export type VendorContractDigests = {
+    schema_digest_hex: string;
+    canonical_schema_digest_hex: string;
+};
+/** Hex-encode a 32-byte BLAKE3 digest. */
+export declare function digestToHex(digest: Uint8Array): string;
+/** BLAKE3 hex digest of JCS-canonical JSON for a completion evidence schema object. */
+export declare function completionSchemaDigestHex(schema: Record<string, unknown>): string;
+/** Compute vendor and canonical schema digests for a vendor_pack preset. */
+export declare function computeVendorContractDigests(preset: {
+    vendor_evidence_schema: Record<string, unknown>;
+    evidence_schema: Record<string, unknown>;
+}): VendorContractDigests;
+/**
+ * Assert catalog-declared vendor_contract digests and quality_fields match computed values.
+ * @throws when a vendor_pack contract is missing, stale, or references unknown quality fields.
+ */
+export declare function verifyVendorContract(preset: CompletionPreset): void;
+/** Verify all vendor_pack presets in a catalog document. */
+export declare function verifyCatalogVendorContracts(catalog: {
+    presets: CompletionPreset[];
+}): void;

package/dist/completion-contract-digest.js

@@ -0,0 +1,73 @@
+/**
+ * BLAKE3 digests for completion preset vendor_contract schema pinning.
+ * Matches `paybond-evidence::json_value_digest` and Harbor signing digests.
+ */
+import { jsonValueDigest } from "./json-digest.js";
+/** Hex-encode a 32-byte BLAKE3 digest. */
+export function digestToHex(digest) {
+    return Buffer.from(digest).toString("hex");
+}
+/** BLAKE3 hex digest of JCS-canonical JSON for a completion evidence schema object. */
+export function completionSchemaDigestHex(schema) {
+    return digestToHex(jsonValueDigest(schema));
+}
+/** Compute vendor and canonical schema digests for a vendor_pack preset. */
+export function computeVendorContractDigests(preset) {
+    return {
+        schema_digest_hex: completionSchemaDigestHex(preset.vendor_evidence_schema),
+        canonical_schema_digest_hex: completionSchemaDigestHex(preset.evidence_schema),
+    };
+}
+function vendorSchemaFieldNames(schema) {
+    const props = schema.properties;
+    if (!props || typeof props !== "object" || Array.isArray(props)) {
+        return new Set();
+    }
+    return new Set(Object.keys(props));
+}
+/**
+ * Assert catalog-declared vendor_contract digests and quality_fields match computed values.
+ * @throws when a vendor_pack contract is missing, stale, or references unknown quality fields.
+ */
+export function verifyVendorContract(preset) {
+    if (preset.kind !== "vendor_pack") {
+        return;
+    }
+    const presetId = preset.preset_id;
+    const contract = preset.vendor_contract;
+    if (!contract) {
+        throw new Error(`${presetId}: vendor_pack missing vendor_contract`);
+    }
+    if (!preset.vendor_evidence_schema || !preset.evidence_schema) {
+        throw new Error(`${presetId}: vendor_pack missing evidence schemas`);
+    }
+    const computed = computeVendorContractDigests({
+        vendor_evidence_schema: preset.vendor_evidence_schema,
+        evidence_schema: preset.evidence_schema,
+    });
+    if (contract.schema_digest_hex !== computed.schema_digest_hex) {
+        throw new Error(`${presetId}: vendor_contract.schema_digest_hex mismatch (catalog=${contract.schema_digest_hex}, computed=${computed.schema_digest_hex})`);
+    }
+    if (contract.canonical_schema_digest_hex !== computed.canonical_schema_digest_hex) {
+        throw new Error(`${presetId}: vendor_contract.canonical_schema_digest_hex mismatch (catalog=${contract.canonical_schema_digest_hex}, computed=${computed.canonical_schema_digest_hex})`);
+    }
+    if (!contract.quality_fields?.length) {
+        throw new Error(`${presetId}: vendor_contract.quality_fields must be non-empty`);
+    }
+    const allowed = vendorSchemaFieldNames(preset.vendor_evidence_schema);
+    for (const field of contract.quality_fields) {
+        if (!allowed.has(field)) {
+            throw new Error(`${presetId}: quality_fields entry ${JSON.stringify(field)} is not a vendor_evidence_schema property`);
+        }
+    }
+}
+/** Verify all vendor_pack presets in a catalog document. */
+export function verifyCatalogVendorContracts(catalog) {
+    const vendorPacks = catalog.presets.filter((preset) => preset.kind === "vendor_pack");
+    if (vendorPacks.length === 0) {
+        throw new Error("catalog must contain at least one vendor_pack preset");
+    }
+    for (const preset of vendorPacks) {
+        verifyVendorContract(preset);
+    }
+}

package/dist/completion-forbidden-fields.d.ts

@@ -0,0 +1,5 @@
+import type { CompletionPreset } from "./completion-catalog.js";
+/** Returns top-level evidence keys that intersect the preset forbidden list. */
+export declare function forbiddenFieldsInEvidence(evidence: Record<string, unknown> | undefined, forbidden: string[] | undefined): string[];
+/** Checks vendor keys and their mapped canonical names against forbidden fields. */
+export declare function forbiddenFieldsInVendorPayload(preset: CompletionPreset, vendorPayload: Record<string, unknown> | undefined, forbidden: string[] | undefined): string[];

package/dist/completion-forbidden-fields.js

@@ -0,0 +1,26 @@
+/** Returns top-level evidence keys that intersect the preset forbidden list. */
+export function forbiddenFieldsInEvidence(evidence, forbidden) {
+    if (!evidence || !forbidden?.length) {
+        return [];
+    }
+    const blocked = new Set(forbidden);
+    return Object.keys(evidence).filter((key) => blocked.has(key));
+}
+/** Checks vendor keys and their mapped canonical names against forbidden fields. */
+export function forbiddenFieldsInVendorPayload(preset, vendorPayload, forbidden) {
+    if (!vendorPayload || !forbidden?.length) {
+        return [];
+    }
+    const blocked = new Set(forbidden);
+    const fieldMap = preset.evidence_field_map ?? {};
+    const hits = [];
+    for (const vendorKey of Object.keys(vendorPayload)) {
+        const canonicalKey = fieldMap[vendorKey] ?? vendorKey;
+        if (blocked.has(vendorKey) || blocked.has(canonicalKey)) {
+            if (!hits.includes(vendorKey)) {
+                hits.push(vendorKey);
+            }
+        }
+    }
+    return hits;
+}

package/dist/completion-init.d.ts

@@ -0,0 +1,8 @@
+export type CompletionInitOptions = {
+    preset: string;
+    out: string;
+    force: boolean;
+};
+export declare function parseCompletionInitArgs(argv: string[]): CompletionInitOptions | "help";
+export declare function scaffoldCompletionInit(options: CompletionInitOptions): Promise<void>;
+export declare function runCompletionInit(argv: string[]): Promise<number>;

package/dist/completion-init.js

@@ -0,0 +1,334 @@
+import fs from "node:fs/promises";
+import { getCompletionPreset, jsonLiteral, listCompletionPresetIds, } from "./completion-catalog.js";
+import { isVendorPack, resolveCompletionPreset, vendorEvidenceSchema, } from "./completion-resolve.js";
+function usage() {
+    const presets = listCompletionPresetIds().join("|");
+    return [
+        `Usage: paybond init completion --preset <${presets}> [--out <path>] [--force]`,
+        "",
+        "Scaffolds a completion evidence helper aligned with the shared preset catalog.",
+    ].join("\n");
+}
+export function parseCompletionInitArgs(argv) {
+    let preset = "";
+    let out = "";
+    let force = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            return "help";
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--preset") {
+            const raw = argv[i + 1];
+            i += 1;
+            if (!raw || !listCompletionPresetIds().includes(raw)) {
+                throw new Error("invalid --preset");
+            }
+            preset = raw;
+            continue;
+        }
+        if (arg === "--out") {
+            const raw = argv[i + 1];
+            i += 1;
+            if (!raw || raw.startsWith("-")) {
+                throw new Error("invalid --out");
+            }
+            out = raw;
+            continue;
+        }
+        throw new Error(`unknown argument: ${arg}`);
+    }
+    if (!preset) {
+        throw new Error("missing --preset");
+    }
+    if (!out) {
+        out = preset === "cost_and_completion"
+            ? "paybond-paid-tool-guard.ts"
+            : `paybond-completion-${preset.replaceAll("_", "-")}.ts`;
+    }
+    return { preset, out, force };
+}
+function schemaPropertyToTsType(schema) {
+    const type = schema.type;
+    if (type === "integer" || type === "number") {
+        return "number";
+    }
+    if (type === "array") {
+        const items = schema.items;
+        if (items?.type === "string") {
+            return "string[]";
+        }
+        return "unknown[]";
+    }
+    return "string";
+}
+function buildTsFieldLines(schema) {
+    const properties = (schema.properties ?? {});
+    const required = Array.isArray(schema.required)
+        ? schema.required
+        : Object.keys(properties);
+    return required.map((field) => {
+        const prop = properties[field] ?? { type: "string" };
+        return `  ${field}: ${schemaPropertyToTsType(prop)};`;
+    });
+}
+function buildTsFieldLinesFromPreset(preset) {
+    const vendorSchema = vendorEvidenceSchema(preset);
+    if (isVendorPack(preset) && vendorSchema) {
+        return buildTsFieldLines(vendorSchema);
+    }
+    return buildTsFieldLines(preset.evidence_schema);
+}
+function evidenceFieldComments(preset) {
+    const vendorSchema = vendorEvidenceSchema(preset);
+    const schemaForRequired = vendorSchema ?? preset.evidence_schema;
+    const required = Array.isArray(schemaForRequired.required)
+        ? schemaForRequired.required
+        : [];
+    const lines = [
+        `// Preset: ${preset.preset_id} (${preset.title})`,
+        isVendorPack(preset)
+            ? `// Vendor pack over archetype: ${preset.archetype_preset_id}`
+            : `// Harbor template: ${preset.harbor_template_id}`,
+        `// ${preset.human_summary}`,
+        "// Map each paid-tool operation to the evidence fields below before submitSandboxEvidence(...).",
+    ];
+    if (required.length > 0) {
+        lines.push(`// Required evidence fields: ${required.join(", ")}`);
+    }
+    lines.push("// Sandbox: bootstrap with completionPreset to evaluate a strong Harbor predicate on evidence submit.", "// Production: publish the managed template head, then create intents with policy_binding (signing v5).", `//   paybond policy templates`, `//   paybond policy preview --template ${preset.harbor_template_id} --parameters-file parameters.json --evidence-file evidence.json`);
+    return lines;
+}
+function typescriptTemplate(preset) {
+    const resolved = resolveCompletionPreset(preset.preset_id);
+    const fieldLines = buildTsFieldLinesFromPreset(preset);
+    const comments = evidenceFieldComments(preset).join("\n");
+    const sampleEvidence = jsonLiteral(isVendorPack(preset) && preset.vendor_sample_evidence
+        ? preset.vendor_sample_evidence
+        : preset.sample_evidence, 2);
+    const evidenceSchema = jsonLiteral(preset.evidence_schema, 2);
+    const parameters = jsonLiteral(resolved.parameters, 2);
+    const vendorContractExports = isVendorPack(preset) && preset.vendor_contract
+        ? `
+export const VENDOR_CONTRACT_API_VERSION = "${preset.vendor_contract.api_version}";
+export const VENDOR_SCHEMA_DIGEST_HEX = "${preset.vendor_contract.schema_digest_hex}";
+export const CANONICAL_SCHEMA_DIGEST_HEX = "${preset.vendor_contract.canonical_schema_digest_hex}";
+export const VENDOR_QUALITY_FIELDS = ${jsonLiteral(preset.vendor_contract.quality_fields, 2)} as const;
+`
+        : "";
+    const vendorPackHelpers = isVendorPack(preset)
+        ? `
+export type VendorEvidence = {
+${fieldLines.join("\n")}
+};
+
+export function mapVendorEvidenceToCanonical(fields: VendorEvidence): CompletionEvidence {
+  return mapVendorEvidenceFields(fields) as CompletionEvidence;
+}
+
+function mapVendorEvidenceFields(fields: VendorEvidence): Record<string, unknown> {
+  const fieldMap: Record<string, string> = ${jsonLiteral(preset.evidence_field_map ?? {}, 2)};
+  const out: Record<string, unknown> = {};
+  for (const [vendorKey, value] of Object.entries(fields)) {
+    const canonicalKey = fieldMap[vendorKey] ?? vendorKey;
+    out[canonicalKey] = value;
+  }
+  return out;
+}
+`
+        : "";
+    const buildFn = isVendorPack(preset)
+        ? `export function buildCompletionEvidence(fields: VendorEvidence): Record<string, unknown> {
+  return mapVendorEvidenceToCanonical(fields);
+}`
+        : `export function buildCompletionEvidence(fields: CompletionEvidence): Record<string, unknown> {
+  return { ...fields };
+}`;
+    return `import fs from "node:fs/promises";
+import {
+  Paybond,
+  type SandboxGuardrailBootstrapResult,
+  type SandboxGuardrailEvidenceResult,
+} from "@paybond/kit";
+
+declare const process: {
+  env: Record<string, string | undefined>;
+};
+
+${comments}
+
+export const COMPLETION_PRESET_ID = "${preset.preset_id}";
+export const HARBOR_TEMPLATE_ID = "${resolved.harborTemplateId}";
+${isVendorPack(preset) ? `export const ARCHETYPE_PRESET_ID = "${preset.archetype_preset_id}";` : ""}
+${vendorContractExports}
+
+export const completionEvidenceSchema = ${evidenceSchema} as const;
+
+export const completionTemplateParameters = ${parameters} as const;
+
+export const sampleCompletionEvidence = ${sampleEvidence} as const;
+
+export type CompletionEvidence = {
+${buildTsFieldLines(preset.evidence_schema).join("\n")}
+};
+${vendorPackHelpers}
+${buildFn}
+
+// Production: use buildSignedCreateIntentBodyWithPolicyBinding from @paybond/kit after publishing ${preset.harbor_template_id}.
+export const policyBindingStub = {
+  template_id: HARBOR_TEMPLATE_ID,
+  parameters: completionTemplateParameters,
+  // head_seq and digest_hex are assigned after: paybond policy publish ...
+};
+
+const DEFAULT_OPERATION = "paid_tool.operation";
+const DEFAULT_REQUESTED_SPEND_CENTS = ${preset.recommended_amount_cents ?? 500};
+
+export type SubmitCompletionEvidenceOptions = {
+  operation?: string;
+  requestedSpendCents?: number;
+  metadata?: Record<string, unknown>;
+  artifacts?: string[];
+  idempotencyKey?: string;
+};
+
+function readEnvValue(body: string, key: string): string | undefined {
+  const pattern = new RegExp("^\\\\s*(?:export\\\\s+)?" + key + "\\\\s*=\\\\s*(.*)$", "m");
+  const match = body.match(pattern);
+  if (!match) return undefined;
+  let value = (match[1] ?? "").trim();
+  if (value.startsWith('"') && value.endsWith('"')) {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      value = value.slice(1, -1);
+    }
+  } else if (value.startsWith("'") && value.endsWith("'")) {
+    value = value.slice(1, -1);
+  }
+  return value.trim() || undefined;
+}
+
+async function readTextFile(envFile: string): Promise<string | undefined> {
+  try {
+    return await fs.readFile(envFile, "utf8");
+  } catch (err) {
+    if ((err as { code?: unknown })?.code === "ENOENT") return undefined;
+    throw err;
+  }
+}
+
+export async function loadPaybondEnvFile(envFile = ".env.local"): Promise<void> {
+  if (process.env.PAYBOND_API_KEY?.trim()) return;
+  const body = await readTextFile(envFile);
+  if (body === undefined) return;
+  const apiKey = readEnvValue(body, "PAYBOND_API_KEY");
+  if (apiKey) {
+    process.env.PAYBOND_API_KEY = apiKey;
+  }
+}
+
+export async function openPaybondFromEnv(envFile = ".env.local"): Promise<Paybond> {
+  await loadPaybondEnvFile(envFile);
+  const apiKey = process.env.PAYBOND_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("PAYBOND_API_KEY is required; run paybond login or configure your agent host to pass it");
+  }
+  return Paybond.open({
+    apiKey,
+    gatewayBaseUrl: process.env.PAYBOND_GATEWAY_URL ?? process.env.PAYBOND_GATEWAY_BASE_URL,
+    expectedEnvironment: "sandbox",
+  });
+}
+
+export async function bootstrapSandboxGuardrailIntent(
+  paybond: Paybond,
+  options: {
+    operation?: string;
+    requestedSpendCents?: number;
+    currency?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+  } = {},
+): Promise<SandboxGuardrailBootstrapResult> {
+  return paybond.guardrails.bootstrapSandbox({
+    operation: options.operation ?? DEFAULT_OPERATION,
+    requestedSpendCents: options.requestedSpendCents ?? DEFAULT_REQUESTED_SPEND_CENTS,
+    currency: options.currency ?? "usd",
+    evidenceSchema: completionEvidenceSchema,
+    completionPreset: "${preset.preset_id}",
+    metadata: options.metadata,
+    idempotencyKey: options.idempotencyKey,
+  });
+}
+
+export async function submitCompletionEvidence(
+  paybond: Paybond,
+  guardrail: Pick<SandboxGuardrailBootstrapResult, "intent_id" | "operation" | "requested_spend_cents">,
+  evidence: ${isVendorPack(preset) ? "VendorEvidence" : "CompletionEvidence"},
+  options: SubmitCompletionEvidenceOptions = {},
+): Promise<SandboxGuardrailEvidenceResult> {
+  return paybond.guardrails.submitSandboxEvidence({
+    intentId: guardrail.intent_id,
+    payload: buildCompletionEvidence(evidence),
+    ${isVendorPack(preset) ? "vendorPayload: { ...evidence }," : ""}
+    artifacts: options.artifacts,
+    operation: options.operation ?? guardrail.operation,
+    requestedSpendCents: options.requestedSpendCents ?? guardrail.requested_spend_cents,
+    metadata: options.metadata,
+    idempotencyKey: options.idempotencyKey,
+  });
+}
+`;
+}
+function renderTemplate(preset) {
+    return typescriptTemplate(preset);
+}
+async function writeScaffold(out, body, force) {
+    try {
+        await fs.stat(out);
+        if (!force) {
+            throw new Error(`${out} already exists; pass --force to overwrite`);
+        }
+    }
+    catch (err) {
+        if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) {
+            if (!force) {
+                throw err;
+            }
+        }
+    }
+    await fs.writeFile(out, body, "utf8");
+}
+export async function scaffoldCompletionInit(options) {
+    const preset = getCompletionPreset(options.preset);
+    await writeScaffold(options.out, renderTemplate(preset), options.force);
+}
+export async function runCompletionInit(argv) {
+    let parsed;
+    try {
+        const result = parseCompletionInitArgs(argv);
+        if (result === "help") {
+            process.stdout.write(`${usage()}\n`);
+            return 0;
+        }
+        parsed = result;
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n\n${usage()}\n`);
+        return 1;
+    }
+    try {
+        await scaffoldCompletionInit(parsed);
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    process.stdout.write(`Created Paybond completion integration: ${parsed.out}\n`);
+    return 0;
+}

package/dist/completion-resolve.d.ts

@@ -0,0 +1,21 @@
+import { type CompletionPreset } from "./completion-catalog.js";
+export type CompletionPresetKind = "archetype" | "vendor_pack";
+export type ResolvedCompletionPreset = {
+    preset: CompletionPreset;
+    archetype: CompletionPreset;
+    kind: CompletionPresetKind;
+    harborTemplateId: string;
+    parameters: Record<string, unknown>;
+    evidenceSchema: Record<string, unknown>;
+};
+export declare function presetKind(preset: CompletionPreset): CompletionPresetKind;
+export declare function isVendorPack(preset: CompletionPreset): boolean;
+/** Resolves vendor packs to their underlying archetype for Harbor materialization. */
+export declare function resolveCompletionPreset(presetId: string): ResolvedCompletionPreset;
+/** Maps vendor-facing evidence fields to catalog canonical names for Harbor submit. */
+export declare function mapVendorEvidenceToCanonical(preset: CompletionPreset, vendorEvidence: Record<string, unknown>): Record<string, unknown>;
+/** Frozen completion contract metadata for intent pinning at create time. */
+export declare function contractSnapshotForPreset(presetId: string): import("./principal-intent.js").CompletionContractSnapshot;
+export declare function completionPresetDeprecationWarning(presetId: string): string | undefined;
+export declare function vendorEvidenceSchema(preset: CompletionPreset): Record<string, unknown> | undefined;
+export declare function listArchetypePresetIds(): string[];

package/dist/completion-resolve.js

@@ -0,0 +1,86 @@
+import { getCompletionPreset, loadCompletionCatalog, } from "./completion-catalog.js";
+import { completionSchemaDigestHex } from "./completion-contract-digest.js";
+export function presetKind(preset) {
+    return preset.kind === "vendor_pack" ? "vendor_pack" : "archetype";
+}
+export function isVendorPack(preset) {
+    return presetKind(preset) === "vendor_pack";
+}
+/** Resolves vendor packs to their underlying archetype for Harbor materialization. */
+export function resolveCompletionPreset(presetId) {
+    const preset = getCompletionPreset(presetId);
+    if (!isVendorPack(preset)) {
+        return {
+            preset,
+            archetype: preset,
+            kind: "archetype",
+            harborTemplateId: preset.harbor_template_id,
+            parameters: preset.parameters,
+            evidenceSchema: preset.evidence_schema,
+        };
+    }
+    const archetypeId = preset.archetype_preset_id;
+    if (!archetypeId) {
+        throw new Error(`vendor pack ${presetId} missing archetype_preset_id`);
+    }
+    const archetype = getCompletionPreset(archetypeId);
+    return {
+        preset,
+        archetype,
+        kind: "vendor_pack",
+        harborTemplateId: archetype.harbor_template_id,
+        parameters: { ...archetype.parameters, ...preset.parameters },
+        evidenceSchema: preset.evidence_schema,
+    };
+}
+/** Maps vendor-facing evidence fields to catalog canonical names for Harbor submit. */
+export function mapVendorEvidenceToCanonical(preset, vendorEvidence) {
+    const fieldMap = preset.evidence_field_map ?? {};
+    const out = {};
+    for (const [vendorKey, value] of Object.entries(vendorEvidence)) {
+        const canonicalKey = fieldMap[vendorKey] ?? vendorKey;
+        if (canonicalKey === "artifact_blake3_hex" && !Array.isArray(value)) {
+            out[canonicalKey] = [value];
+            continue;
+        }
+        out[canonicalKey] = value;
+    }
+    return out;
+}
+/** Frozen completion contract metadata for intent pinning at create time. */
+export function contractSnapshotForPreset(presetId) {
+    const preset = getCompletionPreset(presetId);
+    const contract = preset.vendor_contract;
+    if (contract) {
+        return {
+            completionPresetId: preset.preset_id,
+            vendorContractProvider: contract.provider,
+            vendorApiVersion: contract.api_version,
+            vendorSchemaDigestHex: contract.schema_digest_hex,
+            canonicalSchemaDigestHex: contract.canonical_schema_digest_hex,
+        };
+    }
+    if (preset.kind === "vendor_pack") {
+        throw new Error(`vendor pack ${presetId} missing vendor_contract`);
+    }
+    return {
+        completionPresetId: preset.preset_id,
+        canonicalSchemaDigestHex: completionSchemaDigestHex(preset.evidence_schema),
+    };
+}
+export function completionPresetDeprecationWarning(presetId) {
+    const preset = getCompletionPreset(presetId);
+    if (!preset.deprecated) {
+        return undefined;
+    }
+    const replacement = preset.superseded_by ?? "a newer preset";
+    return `completion preset ${presetId} is deprecated; use ${replacement} instead`;
+}
+export function vendorEvidenceSchema(preset) {
+    return preset.vendor_evidence_schema;
+}
+export function listArchetypePresetIds() {
+    return loadCompletionCatalog()
+        .presets.filter((entry) => !isVendorPack(entry))
+        .map((entry) => entry.preset_id);
+}

package/dist/completion-validate-evidence.d.ts

@@ -0,0 +1,24 @@
+/** Local pre-validation report aligned with Harbor `SchemaValidationReport`. */
+export type CompletionEvidenceValidationReport = {
+    preset_id: string;
+    vendor_schema_ok: boolean;
+    canonical_schema_ok: boolean;
+    quality_fields_missing: string[];
+    forbidden_fields_present: string[];
+    pack_stale: boolean;
+    drift_kinds: string[];
+    canonical_payload?: Record<string, unknown>;
+};
+/**
+ * Validates vendor and canonical completion evidence against catalog JSON Schemas.
+ * Signal-only: returns drift metadata without throwing on schema mismatch.
+ */
+export declare function validateCompletionEvidence(input: {
+    presetId: string;
+    vendorPayload?: Record<string, unknown>;
+    canonicalPayload?: Record<string, unknown>;
+    /** When set, compares catalog contract digests to detect pack_stale (intent pin drift). */
+    frozenVendorApiVersion?: string;
+    frozenVendorSchemaDigestHex?: string;
+    frozenCanonicalSchemaDigestHex?: string;
+}): CompletionEvidenceValidationReport;