@sellable/mcp 0.1.554 → 0.1.555

package/dist/refill-contract.d.ts

@@ -0,0 +1,157 @@
+export declare const REFILL_CONTRACT_VERSION: "2.0.0";
+export declare const REFILL_CONTRACT_CACHE_VERSION: "refill-contract-v1";
+export declare const REFILL_CONTRACT_SUPPORTED_MAJOR: 2;
+export declare const REFILL_CONTRACT_ERROR_CODES: readonly ["refill_contract_not_implemented", "unsupported_refill_contract_major", "refill_contract_hash_mismatch", "refill_contract_semantic_mismatch"];
+export type RefillContractErrorCode = (typeof REFILL_CONTRACT_ERROR_CODES)[number];
+export declare class RefillContractError extends Error {
+    readonly code: RefillContractErrorCode;
+    constructor(code: RefillContractErrorCode, message: string);
+}
+export declare const REFILL_SCOPE_IDS: readonly ["workspace_id", "target_date", "sender_selectors", "campaign_selectors", "approval_mode", "contract_identity", "installed_identity"];
+export declare const REFILL_GATE_IDS: readonly ["workspace_access", "approval_packet", "source_family", "threshold", "scheduler", "campaign_lifecycle", "send_time", "no_direct_send", "one_primitive", "fresh_reread", "normalized_accounting", "prep_circuit", "terminal_truth"];
+export declare const REFILL_STATE_IDS: readonly ["planning", "awaiting_approval", "executing", "settling", "replanning", "terminal"];
+export declare const REFILL_ACTION_IDS: readonly ["prepare_messages", "approve_messages", "rerun_errored_cells", "start_paused_campaign", "run_scheduler_sweep", "scheduler_first_settle", "wait_for_scheduler", "wait_for_active_work", "wait_for_source_import", "copy_selected_source_rows", "continue_signal_discovery_source", "continue_sales_nav_source", "continue_prospeo_source", "manual_source_replenishment", "refresh_paid_inmail_credits", "lower_paid_inmail_threshold", "switch_to_connection_lane", "create_connection_campaign", "next_campaign", "done"];
+export declare const REFILL_RECEIPT_IDS: readonly ["target_plan_receipt", "preparation_receipt", "scheduler_receipt", "run_receipt"];
+export declare const REFILL_SIDE_EFFECT_CLASS_IDS: readonly ["read_only", "message_preparation", "message_approval", "source_replenishment", "credit_refresh", "campaign_start", "scheduler_placement"];
+export declare const REFILL_FORBIDDEN_ACTION_IDS: readonly ["direct_send", "raw_scheduler_write", "campaign_create", "campaign_archive_delete", "threshold_lowering", "unselected_source_mutation", "unapproved_campaign_start", "sender_config_write"];
+export declare const REFILL_TERMINAL_REASON_IDS: readonly ["projected_full", "concrete_blocker", "deadline_reached", "iteration_limit", "operator_stopped", "capped_by_scheduler", "loaded_awaiting_scheduler", "lanes_exhausted", "not_an_evergreen_workspace", "no_refillable_campaigns"];
+export type RefillScopeId = (typeof REFILL_SCOPE_IDS)[number];
+export type RefillGateId = (typeof REFILL_GATE_IDS)[number];
+export type RefillStateId = (typeof REFILL_STATE_IDS)[number];
+export type RefillActionId = (typeof REFILL_ACTION_IDS)[number];
+export type RefillReceiptId = (typeof REFILL_RECEIPT_IDS)[number];
+export type RefillSideEffectClassId = (typeof REFILL_SIDE_EFFECT_CLASS_IDS)[number];
+export type RefillForbiddenActionId = (typeof REFILL_FORBIDDEN_ACTION_IDS)[number];
+export type RefillTerminalReasonId = (typeof REFILL_TERMINAL_REASON_IDS)[number];
+export type RefillAction = {
+    [Kind in RefillActionId]: {
+        kind: Kind;
+        actionKey: string;
+        sideEffectClass: RefillSideEffectClassId;
+    };
+}[RefillActionId];
+export type RefillReceipt = {
+    [Kind in RefillReceiptId]: {
+        kind: Kind;
+        actionKey: string;
+        recordedAt: string;
+    };
+}[RefillReceiptId];
+export type RefillTerminal = {
+    [Reason in RefillTerminalReasonId]: {
+        kind: "terminal";
+        reason: Reason;
+        evidence: Record<string, unknown>;
+    };
+}[RefillTerminalReasonId];
+export declare function canonicalizeRefillContract(value: unknown): string;
+export declare function computeRefillContractHash(value: unknown): string;
+export declare const REFILL_CONTRACT_HASH: string;
+export declare const refillContract: {
+    readonly contractHash: string;
+    readonly contractVersion: "2.0.0";
+    readonly cacheVersion: "refill-contract-v1";
+    readonly supportedMajor: 2;
+    readonly semantics: {
+        readonly scope: {
+            id: "workspace_id" | "target_date" | "sender_selectors" | "campaign_selectors" | "approval_mode" | "contract_identity" | "installed_identity";
+        }[];
+        readonly gates: {
+            id: "workspace_access" | "approval_packet" | "source_family" | "threshold" | "scheduler" | "campaign_lifecycle" | "send_time" | "no_direct_send" | "one_primitive" | "fresh_reread" | "normalized_accounting" | "prep_circuit" | "terminal_truth";
+        }[];
+        readonly states: {
+            id: "planning" | "awaiting_approval" | "executing" | "settling" | "replanning" | "terminal";
+        }[];
+        readonly actions: {
+            id: "prepare_messages" | "approve_messages" | "rerun_errored_cells" | "start_paused_campaign" | "run_scheduler_sweep" | "scheduler_first_settle" | "wait_for_scheduler" | "wait_for_active_work" | "wait_for_source_import" | "copy_selected_source_rows" | "continue_signal_discovery_source" | "continue_sales_nav_source" | "continue_prospeo_source" | "manual_source_replenishment" | "refresh_paid_inmail_credits" | "lower_paid_inmail_threshold" | "switch_to_connection_lane" | "create_connection_campaign" | "next_campaign" | "done";
+            sideEffectClass: "read_only" | "message_preparation" | "message_approval" | "source_replenishment" | "credit_refresh" | "campaign_start" | "scheduler_placement";
+        }[];
+        readonly receipts: readonly [{
+            readonly id: "target_plan_receipt";
+            readonly requiredFields: readonly ["refillLaneKey", "branchMetrics", "ledger", "targetDate", "actionKey", "targetShapeRevision", "stateRevision"];
+        }, {
+            readonly id: "preparation_receipt";
+            readonly requiredFields: readonly ["dependency", "circuit", "batchCalibration", "cooperativeStop"];
+        }, {
+            readonly id: "scheduler_receipt";
+            readonly requiredFields: readonly ["receiptVersion", "diagnosticsVersion", "status", "trigger", "workspaceId", "runId", "leaseFence", "expectedTargetsHash", "maxPlacements", "readyCellsFound", "cellsConsidered", "cellsScheduled", "cellsSkipped", "cellsDeferred", "campaignScopeSummary", "expectedTargetSummary", "changedCounts", "summary", "nextAction", "errorCount", "error"];
+        }, {
+            readonly id: "run_receipt";
+            readonly requiredFields: readonly ["runId", "fence", "gate", "gateSeq", "events", "doneReason"];
+        }];
+        readonly sideEffectClasses: {
+            id: "read_only" | "message_preparation" | "message_approval" | "source_replenishment" | "credit_refresh" | "campaign_start" | "scheduler_placement";
+        }[];
+        readonly forbiddenActions: {
+            id: "direct_send" | "raw_scheduler_write" | "campaign_create" | "campaign_archive_delete" | "threshold_lowering" | "unselected_source_mutation" | "unapproved_campaign_start" | "sender_config_write";
+        }[];
+        readonly terminalReasons: {
+            id: "projected_full" | "concrete_blocker" | "deadline_reached" | "iteration_limit" | "operator_stopped" | "capped_by_scheduler" | "loaded_awaiting_scheduler" | "lanes_exhausted" | "not_an_evergreen_workspace" | "no_refillable_campaigns";
+            terminalKind: string;
+        }[];
+        readonly transitions: readonly [{
+            readonly from: "planning";
+            readonly to: "awaiting_approval";
+        }, {
+            readonly from: "awaiting_approval";
+            readonly to: "executing";
+        }, {
+            readonly from: "executing";
+            readonly to: "settling";
+        }, {
+            readonly from: "settling";
+            readonly to: "replanning";
+        }, {
+            readonly from: "replanning";
+            readonly to: "executing";
+        }, {
+            readonly from: "replanning";
+            readonly to: "terminal";
+        }];
+    };
+    readonly backendBindings: {
+        readonly planner: {
+            readonly actions: ("prepare_messages" | "approve_messages" | "rerun_errored_cells" | "start_paused_campaign" | "run_scheduler_sweep" | "scheduler_first_settle" | "wait_for_scheduler" | "wait_for_active_work" | "wait_for_source_import" | "copy_selected_source_rows" | "continue_signal_discovery_source" | "continue_sales_nav_source" | "continue_prospeo_source" | "manual_source_replenishment" | "refresh_paid_inmail_credits" | "lower_paid_inmail_threshold" | "switch_to_connection_lane" | "create_connection_campaign" | "next_campaign" | "done")[];
+            readonly receiptFields: readonly ["refillLaneKey", "branchMetrics", "ledger", "targetDate", "actionKey", "targetShapeRevision", "stateRevision"];
+        };
+        readonly preparation: {
+            readonly dependencyClasses: readonly ["active", "transient", "permanent", "changed", "exhausted"];
+            readonly dependencyReasons: readonly ["active_cells", "dependency_timeout", "rate_limited", "provider_unavailable", "authentication_failed", "validation_failed", "schema_invalid", "config_epoch_changed", "source_epoch_changed", "frontier_exhausted", "unknown_dependency"];
+            readonly circuitStates: readonly ["closed", "open", "half_open", "reset"];
+            readonly cooperativeStopReasons: readonly ["target_satisfied_during_prep"];
+            readonly receiptFields: readonly ["dependency", "circuit", "batchCalibration", "cooperativeStop"];
+        };
+        readonly scheduler: {
+            readonly targetOutcomes: readonly ["included", "omitted"];
+            readonly omissionReasons: readonly ["no_ready_cells", "not_scheduler_eligible", "sender_mismatch", "capacity_prefiltered", "outside_target_date", "receipt_error"];
+            readonly runStatuses: readonly ["ran", "window_closed_noop", "failed"];
+            readonly nextActions: readonly ["refresh_paid_inmail_credits_then_rerun", "wait_for_capacity_or_window", "inspect_sender_mismatch", "no_ready_cells_continue_refill_prep", "scheduled_cells", "investigate_deferred_reasons", "investigate_scheduler_failure"];
+            readonly receiptFields: readonly ["receiptVersion", "diagnosticsVersion", "status", "trigger", "workspaceId", "runId", "leaseFence", "expectedTargetsHash", "maxPlacements", "readyCellsFound", "cellsConsidered", "cellsScheduled", "cellsSkipped", "cellsDeferred", "campaignScopeSummary", "expectedTargetSummary", "changedCounts", "summary", "nextAction", "errorCount", "error"];
+        };
+        readonly run: {
+            readonly gates: readonly ["g0_bootstrap", "g1_plan", "g2_execute", "g3_verify", "g4_terminal"];
+            readonly states: readonly ["planning", "awaiting_approval", "executing", "settling", "replanning", "terminal"];
+            readonly resultKinds: readonly ["started", "awaiting_approval", "active_run_in_progress", "resumed", "lease_lost", "scope_drift", "approval_expired", "approval_fingerprint_mismatch"];
+            readonly terminalReasons: readonly ["complete", "capped_by_scheduler", "loaded_awaiting_scheduler", "lanes_exhausted", "blocked", "not_an_evergreen_workspace", "no_refillable_campaigns"];
+            readonly refusals: readonly ["scope_drift", "approval_expired", "approval_fingerprint_mismatch", "legacy_read_only", "expected_target_overflow", "scheduler_receipt_incomplete"];
+            readonly scopeFields: readonly ["workspaceId", "intent", "senderIds", "campaignIds", "tableIds", "actionIds", "approvalMode", "dateSelector", "senderTimezones", "expectedTargetsHash", "maxPlacements", "contract", "installed"];
+            readonly approvalFields: readonly ["scopeHash", "targetShapeRevision", "actionFingerprint", "expectedTargetsHash", "sideEffectEnvelope", "maxPlacements", "approvalExpiresAt", "approvalFingerprint"];
+        };
+    };
+};
+export type RefillContract = typeof refillContract;
+export declare function assertSupportedRefillContractMajor(version: string): void;
+export declare function validateRefillContractAsset(value: unknown): RefillContract;
+export declare function refillContractSemanticProjection(): {
+    contractVersion: "2.0.0";
+    cacheVersion: "refill-contract-v1";
+    contractHash: string;
+    semanticIds: {
+        [k: string]: string[];
+    };
+};
+export declare function validateRefillFlowProjection(value: unknown): void;
+export declare function renderRefillBootstrapGuidance(): string;
+export declare function renderRefillSafetyGuidance(): string;
+export declare function renderRefillTerminalGuidance(): string;
+export declare function assertNeverRefillVariant(value: never): never;

package/dist/refill-contract.js

@@ -0,0 +1,487 @@
+import { createHash } from "node:crypto";
+export const REFILL_CONTRACT_VERSION = "2.0.0";
+export const REFILL_CONTRACT_CACHE_VERSION = "refill-contract-v1";
+export const REFILL_CONTRACT_SUPPORTED_MAJOR = 2;
+export const REFILL_CONTRACT_ERROR_CODES = [
+    "refill_contract_not_implemented",
+    "unsupported_refill_contract_major",
+    "refill_contract_hash_mismatch",
+    "refill_contract_semantic_mismatch",
+];
+export class RefillContractError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RefillContractError";
+    }
+}
+export const REFILL_SCOPE_IDS = [
+    "workspace_id",
+    "target_date",
+    "sender_selectors",
+    "campaign_selectors",
+    "approval_mode",
+    "contract_identity",
+    "installed_identity",
+];
+export const REFILL_GATE_IDS = [
+    "workspace_access",
+    "approval_packet",
+    "source_family",
+    "threshold",
+    "scheduler",
+    "campaign_lifecycle",
+    "send_time",
+    "no_direct_send",
+    "one_primitive",
+    "fresh_reread",
+    "normalized_accounting",
+    "prep_circuit",
+    "terminal_truth",
+];
+export const REFILL_STATE_IDS = [
+    "planning",
+    "awaiting_approval",
+    "executing",
+    "settling",
+    "replanning",
+    "terminal",
+];
+export const REFILL_ACTION_IDS = [
+    "prepare_messages",
+    "approve_messages",
+    "rerun_errored_cells",
+    "start_paused_campaign",
+    "run_scheduler_sweep",
+    "scheduler_first_settle",
+    "wait_for_scheduler",
+    "wait_for_active_work",
+    "wait_for_source_import",
+    "copy_selected_source_rows",
+    "continue_signal_discovery_source",
+    "continue_sales_nav_source",
+    "continue_prospeo_source",
+    "manual_source_replenishment",
+    "refresh_paid_inmail_credits",
+    "lower_paid_inmail_threshold",
+    "switch_to_connection_lane",
+    "create_connection_campaign",
+    "next_campaign",
+    "done",
+];
+export const REFILL_RECEIPT_IDS = [
+    "target_plan_receipt",
+    "preparation_receipt",
+    "scheduler_receipt",
+    "run_receipt",
+];
+export const REFILL_SIDE_EFFECT_CLASS_IDS = [
+    "read_only",
+    "message_preparation",
+    "message_approval",
+    "source_replenishment",
+    "credit_refresh",
+    "campaign_start",
+    "scheduler_placement",
+];
+export const REFILL_FORBIDDEN_ACTION_IDS = [
+    "direct_send",
+    "raw_scheduler_write",
+    "campaign_create",
+    "campaign_archive_delete",
+    "threshold_lowering",
+    "unselected_source_mutation",
+    "unapproved_campaign_start",
+    "sender_config_write",
+];
+export const REFILL_TERMINAL_REASON_IDS = [
+    "projected_full",
+    "concrete_blocker",
+    "deadline_reached",
+    "iteration_limit",
+    "operator_stopped",
+    "capped_by_scheduler",
+    "loaded_awaiting_scheduler",
+    "lanes_exhausted",
+    "not_an_evergreen_workspace",
+    "no_refillable_campaigns",
+];
+const plannerActions = [...REFILL_ACTION_IDS];
+const plannerReceiptFields = [
+    "refillLaneKey",
+    "branchMetrics",
+    "ledger",
+    "targetDate",
+    "actionKey",
+    "targetShapeRevision",
+    "stateRevision",
+];
+const preparationDependencyClasses = [
+    "active",
+    "transient",
+    "permanent",
+    "changed",
+    "exhausted",
+];
+const preparationDependencyReasons = [
+    "active_cells",
+    "dependency_timeout",
+    "rate_limited",
+    "provider_unavailable",
+    "authentication_failed",
+    "validation_failed",
+    "schema_invalid",
+    "config_epoch_changed",
+    "source_epoch_changed",
+    "frontier_exhausted",
+    "unknown_dependency",
+];
+const preparationCircuitStates = [
+    "closed",
+    "open",
+    "half_open",
+    "reset",
+];
+const preparationCooperativeStopReasons = [
+    "target_satisfied_during_prep",
+];
+const preparationReceiptFields = [
+    "dependency",
+    "circuit",
+    "batchCalibration",
+    "cooperativeStop",
+];
+const schedulerTargetOutcomes = ["included", "omitted"];
+const schedulerOmissionReasons = [
+    "no_ready_cells",
+    "not_scheduler_eligible",
+    "sender_mismatch",
+    "capacity_prefiltered",
+    "outside_target_date",
+    "receipt_error",
+];
+const schedulerRunStatuses = [
+    "ran",
+    "window_closed_noop",
+    "failed",
+];
+const schedulerNextActions = [
+    "refresh_paid_inmail_credits_then_rerun",
+    "wait_for_capacity_or_window",
+    "inspect_sender_mismatch",
+    "no_ready_cells_continue_refill_prep",
+    "scheduled_cells",
+    "investigate_deferred_reasons",
+    "investigate_scheduler_failure",
+];
+const schedulerReceiptFields = [
+    "receiptVersion",
+    "diagnosticsVersion",
+    "status",
+    "trigger",
+    "workspaceId",
+    "runId",
+    "leaseFence",
+    "expectedTargetsHash",
+    "maxPlacements",
+    "readyCellsFound",
+    "cellsConsidered",
+    "cellsScheduled",
+    "cellsSkipped",
+    "cellsDeferred",
+    "campaignScopeSummary",
+    "expectedTargetSummary",
+    "changedCounts",
+    "summary",
+    "nextAction",
+    "errorCount",
+    "error",
+];
+const runGates = [
+    "g0_bootstrap",
+    "g1_plan",
+    "g2_execute",
+    "g3_verify",
+    "g4_terminal",
+];
+const runResultKinds = [
+    "started",
+    "awaiting_approval",
+    "active_run_in_progress",
+    "resumed",
+    "lease_lost",
+    "scope_drift",
+    "approval_expired",
+    "approval_fingerprint_mismatch",
+];
+const runTerminalReasons = [
+    "complete",
+    "capped_by_scheduler",
+    "loaded_awaiting_scheduler",
+    "lanes_exhausted",
+    "blocked",
+    "not_an_evergreen_workspace",
+    "no_refillable_campaigns",
+];
+const runRefusals = [
+    "scope_drift",
+    "approval_expired",
+    "approval_fingerprint_mismatch",
+    "legacy_read_only",
+    "expected_target_overflow",
+    "scheduler_receipt_incomplete",
+];
+const runScopeFields = [
+    "workspaceId",
+    "intent",
+    "senderIds",
+    "campaignIds",
+    "tableIds",
+    "actionIds",
+    "approvalMode",
+    "dateSelector",
+    "senderTimezones",
+    "expectedTargetsHash",
+    "maxPlacements",
+    "contract",
+    "installed",
+];
+const runApprovalFields = [
+    "scopeHash",
+    "targetShapeRevision",
+    "actionFingerprint",
+    "expectedTargetsHash",
+    "sideEffectEnvelope",
+    "maxPlacements",
+    "approvalExpiresAt",
+    "approvalFingerprint",
+];
+const actionSideEffects = {
+    prepare_messages: "message_preparation",
+    approve_messages: "message_approval",
+    rerun_errored_cells: "message_preparation",
+    start_paused_campaign: "campaign_start",
+    run_scheduler_sweep: "scheduler_placement",
+    scheduler_first_settle: "read_only",
+    wait_for_scheduler: "read_only",
+    wait_for_active_work: "read_only",
+    wait_for_source_import: "read_only",
+    copy_selected_source_rows: "source_replenishment",
+    continue_signal_discovery_source: "source_replenishment",
+    continue_sales_nav_source: "source_replenishment",
+    continue_prospeo_source: "source_replenishment",
+    manual_source_replenishment: "source_replenishment",
+    refresh_paid_inmail_credits: "credit_refresh",
+    lower_paid_inmail_threshold: "read_only",
+    switch_to_connection_lane: "read_only",
+    create_connection_campaign: "read_only",
+    next_campaign: "read_only",
+    done: "read_only",
+};
+const semanticContract = {
+    scope: REFILL_SCOPE_IDS.map((id) => ({ id })),
+    gates: REFILL_GATE_IDS.map((id) => ({ id })),
+    states: REFILL_STATE_IDS.map((id) => ({ id })),
+    actions: REFILL_ACTION_IDS.map((id) => ({
+        id,
+        sideEffectClass: actionSideEffects[id],
+    })),
+    receipts: [
+        { id: "target_plan_receipt", requiredFields: plannerReceiptFields },
+        { id: "preparation_receipt", requiredFields: preparationReceiptFields },
+        { id: "scheduler_receipt", requiredFields: schedulerReceiptFields },
+        {
+            id: "run_receipt",
+            requiredFields: [
+                "runId",
+                "fence",
+                "gate",
+                "gateSeq",
+                "events",
+                "doneReason",
+            ],
+        },
+    ],
+    sideEffectClasses: REFILL_SIDE_EFFECT_CLASS_IDS.map((id) => ({ id })),
+    forbiddenActions: REFILL_FORBIDDEN_ACTION_IDS.map((id) => ({ id })),
+    terminalReasons: REFILL_TERMINAL_REASON_IDS.map((id) => ({
+        id,
+        terminalKind: id === "projected_full" ? "complete" : "stopped",
+    })),
+    transitions: [
+        { from: "planning", to: "awaiting_approval" },
+        { from: "awaiting_approval", to: "executing" },
+        { from: "executing", to: "settling" },
+        { from: "settling", to: "replanning" },
+        { from: "replanning", to: "executing" },
+        { from: "replanning", to: "terminal" },
+    ],
+};
+const backendBindings = {
+    planner: {
+        actions: plannerActions,
+        receiptFields: plannerReceiptFields,
+    },
+    preparation: {
+        dependencyClasses: preparationDependencyClasses,
+        dependencyReasons: preparationDependencyReasons,
+        circuitStates: preparationCircuitStates,
+        cooperativeStopReasons: preparationCooperativeStopReasons,
+        receiptFields: preparationReceiptFields,
+    },
+    scheduler: {
+        targetOutcomes: schedulerTargetOutcomes,
+        omissionReasons: schedulerOmissionReasons,
+        runStatuses: schedulerRunStatuses,
+        nextActions: schedulerNextActions,
+        receiptFields: schedulerReceiptFields,
+    },
+    run: {
+        gates: runGates,
+        states: REFILL_STATE_IDS,
+        resultKinds: runResultKinds,
+        terminalReasons: runTerminalReasons,
+        refusals: runRefusals,
+        scopeFields: runScopeFields,
+        approvalFields: runApprovalFields,
+    },
+};
+const contractWithoutHash = {
+    contractVersion: REFILL_CONTRACT_VERSION,
+    cacheVersion: REFILL_CONTRACT_CACHE_VERSION,
+    supportedMajor: REFILL_CONTRACT_SUPPORTED_MAJOR,
+    semantics: semanticContract,
+    backendBindings,
+};
+function canonicalValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key, entry]) => key !== "contractHash" &&
+            key !== "releaseIdentities" &&
+            entry !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, canonicalValue(entry)]));
+    }
+    return value;
+}
+export function canonicalizeRefillContract(value) {
+    return JSON.stringify(canonicalValue(value));
+}
+export function computeRefillContractHash(value) {
+    return createHash("sha256")
+        .update(canonicalizeRefillContract(value))
+        .digest("hex");
+}
+export const REFILL_CONTRACT_HASH = computeRefillContractHash(contractWithoutHash);
+export const refillContract = {
+    ...contractWithoutHash,
+    contractHash: REFILL_CONTRACT_HASH,
+};
+function objectRecord(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new RefillContractError("refill_contract_semantic_mismatch", `${path} must be an object`);
+    }
+    return value;
+}
+function semanticDifference(path, actual, expected) {
+    if (canonicalizeRefillContract(actual) === canonicalizeRefillContract(expected)) {
+        return;
+    }
+    const actualIds = Array.isArray(actual)
+        ? actual.map((entry) => typeof entry === "string"
+            ? entry
+            : String(entry?.id ?? ""))
+        : [];
+    const expectedIds = Array.isArray(expected)
+        ? expected.map((entry) => typeof entry === "string"
+            ? entry
+            : String(entry?.id ?? ""))
+        : [];
+    const missing = expectedIds.filter((id) => !actualIds.includes(id));
+    const extra = actualIds.filter((id) => !expectedIds.includes(id));
+    const detail = [
+        missing.length ? `missing=${missing.join(",")}` : "",
+        extra.length ? `extra=${extra.join(",")}` : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    throw new RefillContractError("refill_contract_semantic_mismatch", `${path} differs from the canonical refill contract${detail ? `: ${detail}` : ""}`);
+}
+export function assertSupportedRefillContractMajor(version) {
+    const major = Number.parseInt(version.split(".")[0] ?? "", 10);
+    if (major !== REFILL_CONTRACT_SUPPORTED_MAJOR) {
+        throw new RefillContractError("unsupported_refill_contract_major", `unsupported_refill_contract_major: expected ${REFILL_CONTRACT_SUPPORTED_MAJOR}, received ${version}`);
+    }
+}
+export function validateRefillContractAsset(value) {
+    const record = objectRecord(value, "contract");
+    const version = String(record.contractVersion ?? "");
+    assertSupportedRefillContractMajor(version);
+    if (version !== REFILL_CONTRACT_VERSION) {
+        throw new RefillContractError("refill_contract_semantic_mismatch", `contractVersion differs: expected ${REFILL_CONTRACT_VERSION}, received ${version}`);
+    }
+    if (record.cacheVersion !== REFILL_CONTRACT_CACHE_VERSION) {
+        throw new RefillContractError("refill_contract_semantic_mismatch", `cacheVersion differs: expected ${REFILL_CONTRACT_CACHE_VERSION}, received ${String(record.cacheVersion)}`);
+    }
+    const semantics = objectRecord(record.semantics, "semantics");
+    for (const [family, expected] of Object.entries(refillContract.semantics)) {
+        semanticDifference(`semantics.${family}`, semantics[family], expected);
+    }
+    semanticDifference("backendBindings", record.backendBindings, refillContract.backendBindings);
+    const computedHash = computeRefillContractHash(record);
+    if (record.contractHash !== computedHash) {
+        throw new RefillContractError("refill_contract_hash_mismatch", `refill_contract_hash_mismatch: expected ${computedHash}, received ${String(record.contractHash)}`);
+    }
+    return value;
+}
+export function refillContractSemanticProjection() {
+    return {
+        contractVersion: REFILL_CONTRACT_VERSION,
+        cacheVersion: REFILL_CONTRACT_CACHE_VERSION,
+        contractHash: REFILL_CONTRACT_HASH,
+        semanticIds: Object.fromEntries(Object.entries(refillContract.semantics)
+            .filter(([, entries]) => Array.isArray(entries))
+            .map(([family, entries]) => [
+            family,
+            entries.map((entry) => typeof entry === "string"
+                ? entry
+                : String(entry.id ?? "")),
+        ])),
+    };
+}
+export function validateRefillFlowProjection(value) {
+    const flow = objectRecord(value, "flow");
+    const projection = objectRecord(flow.refillContract, "flow.refillContract");
+    semanticDifference("flow.refillContract", projection, refillContractSemanticProjection());
+}
+function renderIds(label, ids) {
+    return `${label}: ${ids.join(", ")}`;
+}
+export function renderRefillBootstrapGuidance() {
+    return [
+        renderIds("scope", REFILL_SCOPE_IDS),
+        renderIds("gates", [
+            "approval_packet",
+            "one_primitive",
+            "fresh_reread",
+            "normalized_accounting",
+            "prep_circuit",
+        ]),
+        "release identities (independent of semantic hash): mcpPackageVersion, installPackageVersion, codexPluginVersion",
+    ].join("\n");
+}
+export function renderRefillSafetyGuidance() {
+    return renderIds("forbidden", REFILL_FORBIDDEN_ACTION_IDS);
+}
+export function renderRefillTerminalGuidance() {
+    return [
+        renderIds("terminal", REFILL_TERMINAL_REASON_IDS),
+        "ready_buffer_exists_is_not_complete",
+    ].join("\n");
+}
+export function assertNeverRefillVariant(value) {
+    throw new RefillContractError("refill_contract_semantic_mismatch", `Unhandled refill contract variant: ${String(value)}`);
+}

package/dist/refill-run-client.d.ts

@@ -5,6 +5,11 @@ export type RefillRunBlockerResult = {
     runId: string;
     gate?: string;
     gateSeq?: number;
+} | {
+    blocker: "scope_drift" | "approval_expired" | "approval_fingerprint_mismatch";
+    runId: string;
+    expectedScopeHash: string | null;
+    receivedScopeHash: string | null;
 };
 export declare function startRefillRunRemote(input: {
     workspaceId?: string;