@sellable/mcp 0.1.556 → 0.1.557

package/dist/refill-contract.js

@@ -1,487 +0,0 @@
-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)}`);
-}