@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-advance-contract.js

@@ -0,0 +1,920 @@
+/**
+ * Refill V3 `advance` PACKAGE seam (Phase 146.5 Plan 10, RV3FLOW-001).
+ *
+ * This module owns the PUBLIC vocabulary of the one-step coordinator:
+ *
+ *  1. the closed `{workspaceId,scope}` declarative input schema;
+ *  2. the closed five-variant result union plus its top-level output schema; and
+ *  3. the SOLE unknown-value result decoder every installed client runs.
+ *
+ * It declares NO packet shape and NO second AI action list: the
+ * `campaign_attention_required` packet, its decoder, its schema, and the closed
+ * action vocabulary are owned by Plan 02 T3 in
+ * `refill-v3-attention-packet-contract.ts` and only RE-EXPORTED through this
+ * seam (assumption `A10-PACKET-CONTRACT-IMPORTED`). The five-conjunct exhaustion
+ * predicate is likewise imported, never restated.
+ *
+ * Constraints inherited from the sibling contracts: zero imports outside this
+ * package, no app `src/**`, hand-rolled guards, as-const JSON-Schema literals,
+ * strict-in/tolerant-out decoding, and a compatible-RANGE schema-version gate.
+ */
+import { REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS, REFILL_V3_CAMPAIGN_ATTENTION_PACKET_SCHEMA, REFILL_V3_CAMPAIGN_ATTENTION_RESULTS, REFILL_V3_EXHAUSTION_PREDICATE, REFILL_V3_LEAD_SOURCE_FAMILIES, REFILL_V3_SCHEMA_VERSION_UNSUPPORTED, REFILL_V3_SUPPLY_BUCKETS, decodeRefillV3CampaignAttentionPacket, encodeRefillV3CampaignAttentionPacket, resolveRefillV3SchemaVersion, } from "./refill-v3-attention-packet-contract.js";
+import { REFILL_V3_FILL_READY_REASON_CODES } from "./refill-v3-fill-ready-contract.js";
+import { REFILL_V3_WORLD_STATE_LANES, } from "./refill-v3-world-state-contract.js";
+/**
+ * The imported seams, re-exported so a consumer needs exactly ONE import to
+ * produce a packet, validate an AI action, or evaluate exhaustion. These are
+ * VALUE re-exports of a single declaration, never a second declaration.
+ */
+export { REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS, REFILL_V3_CAMPAIGN_ATTENTION_RESULTS, REFILL_V3_EXHAUSTION_PREDICATE, decodeRefillV3CampaignAttentionPacket, encodeRefillV3CampaignAttentionPacket, };
+// ───────────────────────────────────────────────────────────────────────────
+// Schema identity
+// ───────────────────────────────────────────────────────────────────────────
+export const REFILL_V3_ADVANCE_SCHEMA_NAMESPACE = "refill_v3_advance";
+export const REFILL_V3_ADVANCE_SCHEMA_MAJOR = 1;
+export const REFILL_V3_ADVANCE_SCHEMA_VERSION = "refill_v3_advance.v1.0";
+export function resolveRefillV3AdvanceSchemaVersion(value) {
+    return resolveRefillV3SchemaVersion(value, REFILL_V3_ADVANCE_SCHEMA_NAMESPACE, REFILL_V3_ADVANCE_SCHEMA_MAJOR);
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Closed request vocabulary
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The ONE public key set.
+ *
+ * `yolo` is the OPERATOR'S AUTONOMY GRANT, and it is the only optional key. It
+ * is deliberately NOT a mode: it carries no campaign selection, no execution
+ * variant, and no enum. Evergreen-ness stays DERIVED from the workspace's own
+ * campaigns, so a caller still cannot ask for a particular campaign to start —
+ * it can only grant, or withhold, the autonomy to start one at all.
+ *
+ * The linkage is V1's, restored rather than invented: `flow.v1.json`'s
+ * `yoloMode` block carries `approvalSource: "explicit_yolo_flag"` and lists
+ * `start_paused_campaign` among its `autoExecutableActions`, and `refill_sends`
+ * states it as "In --yolo or after one Accept ... a fresh exact
+ * start_paused_campaign packet authorizes starting only that selected PAUSED
+ * fallback". The V3 cutover dropped that grant; this restores it.
+ */
+export const REFILL_V3_ADVANCE_INPUT_KEYS = [
+    "workspaceId",
+    "scope",
+    "yolo",
+];
+/** The keys a caller MUST supply. `yolo` is optional and defaults to false. */
+export const REFILL_V3_ADVANCE_REQUIRED_INPUT_KEYS = [
+    "workspaceId",
+    "scope",
+];
+/**
+ * Keys that recreate the durable state machine this phase deletes. They are
+ * enumerated so a REFUSAL can name the exact offending field instead of a
+ * generic "unknown key", and so a source scan can prove no caller sends them.
+ */
+export const REFILL_V3_ADVANCE_FORBIDDEN_INPUT_KEYS = [
+    "continuation",
+    "taskReceipts",
+    "authorityReceiptFacts",
+    "receiptFacts",
+    "retryCount",
+    "attempt",
+    "attempts",
+    "cursor",
+    "rows",
+    "row",
+    "actions",
+    "action",
+    "progress",
+    "runId",
+    "ledger",
+    "waterfall",
+    "evaluatedAt",
+];
+const ADVANCE_SCOPE_SCHEMA = {
+    oneOf: [
+        {
+            type: "object",
+            additionalProperties: false,
+            required: ["kind", "days"],
+            properties: {
+                kind: { type: "string", const: "sender_local_horizon" },
+                days: { type: "integer", minimum: 1, maximum: 3 },
+                senderIds: {
+                    type: "array",
+                    items: { type: "string", minLength: 1 },
+                    minItems: 1,
+                },
+            },
+        },
+        {
+            type: "object",
+            additionalProperties: false,
+            required: ["kind", "senderDates"],
+            properties: {
+                kind: { type: "string", const: "exact_sender_dates" },
+                senderDates: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "object",
+                        additionalProperties: false,
+                        required: ["senderId", "dates"],
+                        properties: {
+                            senderId: { type: "string", minLength: 1 },
+                            dates: {
+                                type: "array",
+                                minItems: 1,
+                                items: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    ],
+};
+export const REFILL_V3_ADVANCE_INPUT_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: [...REFILL_V3_ADVANCE_REQUIRED_INPUT_KEYS],
+    properties: {
+        workspaceId: {
+            type: "string",
+            minLength: 1,
+            description: "Explicit request-scoped workspace id. Pass this instead of switching the shared active workspace.",
+        },
+        scope: {
+            ...ADVANCE_SCOPE_SCHEMA,
+            description: "Either a 1-3 day sender-local horizon or an exact sender/date set. There is no lane input, no row input, and no mode input.",
+        },
+        yolo: {
+            type: "boolean",
+            description: "The operator's AUTONOMY GRANT, true only when the operator actually asked for --yolo. It is not a mode and selects nothing: WHICH campaign may start is derived from the workspace's own campaigns. It authorizes exactly one thing this call could not otherwise do — starting one already-eligible PAUSED derived-evergreen campaign once every active campaign for a row is exhausted. Omit it, or pass false, for a conservative run that reports that exhaustion instead of acting on it.",
+        },
+    },
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Closed result vocabulary
+// ───────────────────────────────────────────────────────────────────────────
+export const REFILL_V3_ADVANCE_RESULT_KINDS = [
+    "advanced",
+    "campaign_attention_required",
+    "awaiting_external_change",
+    "complete",
+    "blocked",
+];
+/**
+ * The closed set of transitions the coordinator may execute. Each names the ONE
+ * existing authority that owns it; the coordinator never invents an authority
+ * and never carries executable prose.
+ */
+export const REFILL_V3_ADVANCE_ACTION_KINDS = [
+    "refresh_paid_credit_fact",
+    "recheck_sender_connection",
+    "fill_ready",
+    "start_evergreen_campaign",
+];
+/** The exact existing owner each action key dispatches to. */
+export const REFILL_V3_ADVANCE_ACTION_AUTHORITIES = Object.freeze({
+    refresh_paid_credit_fact: "getOrRefreshPaidInmailCreditFact",
+    recheck_sender_connection: "recheckRefillV3SenderConnection",
+    fill_ready: "fillRefillV3Ready",
+    start_evergreen_campaign: "startRefillV3EvergreenCampaign",
+});
+/**
+ * The TOTAL action precedence. Two locked requirements otherwise appear to
+ * conflict: a required exact sender/lane refresh (111o hand-back) must preempt
+ * an otherwise-eligible ready action on the same paid row, and health must be
+ * resolved before the AI campaign seam is reachable at all.
+ */
+export const REFILL_V3_ADVANCE_ACTION_PRECEDENCE = [
+    "refresh_paid_credit_fact",
+    "recheck_sender_connection",
+    "fill_ready",
+    "campaign_attention",
+];
+/** Closed terminal codes. `complete` carries exactly one of these. */
+export const REFILL_V3_ADVANCE_TERMINAL_CODES = [
+    /** Every eligible campaign in every traversed row is receipt-proven spent. */
+    "active_campaigns_exhausted",
+    /**
+     * A row had positive capacity but ZERO eligible campaigns — a PAUSED-only
+     * workspace or a sender enrolled in nothing. It is NOT the vacuously-true
+     * "every campaign exhausted" and NOT a defect.
+     */
+    "no_eligible_campaigns",
+    /**
+     * Visible unclaimed CAMPAIGN supply with no chosen action. A typed DEFECT and
+     * a DEFERRED terminal for queue purposes, never clean exhaustion.
+     */
+    "campaign_supply_unclaimed_defect",
+    /** Every traversed row already met its capacity for this observation. */
+    "daily_targets_met",
+    /** The exact requested scope resolved to no sender at all. */
+    "scope_unresolved",
+];
+/**
+ * Codes emitted ONLY by the coordinator. They EXTEND the fill-ready vocabulary,
+ * which already extends the world-state vocabulary, so retryability stays a
+ * property of the code rather than of a call site.
+ */
+export const REFILL_V3_ADVANCE_ONLY_REASON_CODES = [
+    /** Recheck is impossible without an account id, so it is never attempted. */
+    "account_identity_missing",
+    /** A success-shaped receipt produced ZERO product-state delta. */
+    "no_progress_refused",
+    /** Two matching retryable paid failures already exist for this scope. */
+    "retryable_paid_attempts_exhausted",
+    /** A closed vocabulary carried a value this version does not understand. */
+    "unknown_transport_vocabulary",
+    /** Receipt facts did not match the observation a server load produced. */
+    "forged_authority_receipt_facts",
+    /** An authority threw or timed out; the effect is `uncertain`, not a no-op. */
+    "authority_failure_uncertain",
+    /** An exact reread whose sender no longer resolves. Terminal for that scope. */
+    "sender_scope_unresolved",
+    /** Unclaimed campaign supply the coordinator could not turn into an action. */
+    "campaign_supply_unclaimed",
+    /** Every eligible campaign for this sender/lane is receipt-proven spent. */
+    "lane_campaigns_exhausted",
+    /**
+     * The paid entitlement is ABSENT. It is a distinct fact from a zero balance and
+     * from a disconnected account, so it is never coerced into either.
+     */
+    "missing_balance",
+    /** A recorded permanent business blocker with no more specific code. */
+    "blocked",
+    /**
+     * Membership was revoked BETWEEN the fresh read and the mutation. The
+     * coordinator re-asserts membership inside the mutation path precisely so this
+     * is a refusal rather than an executed mutation.
+     */
+    "workspace_membership_revoked",
+];
+export const REFILL_V3_ADVANCE_REASON_CODES = [
+    ...REFILL_V3_FILL_READY_REASON_CODES,
+    ...REFILL_V3_ADVANCE_ONLY_REASON_CODES,
+];
+export const REFILL_V3_ADVANCE_RECEIPT_STATUSES = [
+    "executed",
+    "attached",
+    "failed",
+    "indeterminate",
+];
+/**
+ * Identity, payload, and bookkeeping classes NO result variant may carry at its
+ * OWN level. A raw row/cell/provider payload would move the table into the
+ * caller; a retry counter or cursor would recreate the deleted state machine.
+ *
+ * `tableId` is deliberately ABSENT from this list: the Plan 02 packet contract
+ * owns `packet.scope.tableId` as a required field, so banning it here would make
+ * the two contracts mutually unsatisfiable. Every other identity class stays
+ * banned, and the packet's own forbidden-key list governs the packet.
+ */
+export const REFILL_V3_ADVANCE_FORBIDDEN_RESULT_KEYS = [
+    "rows",
+    "cells",
+    "rowIds",
+    "cellIds",
+    "rowPayload",
+    "cellPayload",
+    "providerResponse",
+    "providerPayload",
+    "rank",
+    "ranking",
+    "graph",
+    "waterfall",
+    "retryCount",
+    "attempts",
+    "cursor",
+    "continuation",
+    "prompt",
+    "instructions",
+    "durationMs",
+    "evaluatedAt",
+];
+/** Required keys per variant. The decoder rejects any other key set. */
+export const REFILL_V3_ADVANCE_RESULT_KEYS = Object.freeze({
+    advanced: ["kind", "scope", "action", "receipt", "replacementObservation"],
+    campaign_attention_required: ["kind", "scope", "packet", "observation"],
+    awaiting_external_change: ["kind", "scope", "deferral", "observation"],
+    complete: ["kind", "scope", "terminal", "observation"],
+    blocked: ["kind", "scope", "blocker", "observation"],
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Public output schema
+// ───────────────────────────────────────────────────────────────────────────
+const SUPPLY_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: [...REFILL_V3_SUPPLY_BUCKETS],
+    properties: Object.fromEntries(REFILL_V3_SUPPLY_BUCKETS.map((bucket) => [
+        bucket,
+        { type: "integer", minimum: 0 },
+    ])),
+};
+const OBSERVATION_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+        "observationFingerprint",
+        "senderCount",
+        "rowCount",
+        "dates",
+        "availableSlots",
+        "supply",
+    ],
+    properties: {
+        observationFingerprint: { type: "string", minLength: 1 },
+        senderCount: { type: "integer", minimum: 0 },
+        rowCount: { type: "integer", minimum: 0 },
+        dates: {
+            type: "array",
+            items: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+        },
+        availableSlots: { type: "integer", minimum: 0 },
+        supply: SUPPLY_SCHEMA,
+    },
+};
+const SCOPE_ECHO_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["workspaceId", "scopeKind", "scopeFingerprint"],
+    properties: {
+        workspaceId: { type: "string", minLength: 1 },
+        scopeKind: {
+            type: "string",
+            enum: ["sender_local_horizon", "exact_sender_dates"],
+        },
+        scopeFingerprint: { type: "string", minLength: 1 },
+    },
+};
+const ROW_SCOPE_PROPERTIES = {
+    senderId: { type: "string", minLength: 1 },
+    date: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+    lane: { type: "string", enum: [...REFILL_V3_WORLD_STATE_LANES] },
+    campaignId: { type: ["string", "null"] },
+};
+/**
+ * A TOP-LEVEL OBJECT, never a union of arrays: an MCP client validates
+ * `structuredContent` against this declaration, and a tool whose answer the
+ * client rejects has its entire response discarded.
+ */
+export const REFILL_V3_ADVANCE_OUTPUT_SCHEMA = Object.freeze({
+    type: "object",
+    required: ["kind", "scope"],
+    properties: {
+        schemaVersion: { type: "string" },
+        kind: { type: "string", enum: [...REFILL_V3_ADVANCE_RESULT_KINDS] },
+        scope: SCOPE_ECHO_SCHEMA,
+        action: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "kind",
+                "actionKey",
+                "authority",
+                "senderId",
+                "date",
+                "lane",
+                "campaignId",
+                "evidenceFingerprint",
+            ],
+            properties: {
+                kind: { type: "string", enum: [...REFILL_V3_ADVANCE_ACTION_KINDS] },
+                actionKey: { type: "string", minLength: 1 },
+                authority: {
+                    type: "string",
+                    enum: Object.values(REFILL_V3_ADVANCE_ACTION_AUTHORITIES),
+                },
+                ...ROW_SCOPE_PROPERTIES,
+                evidenceFingerprint: { type: "string", minLength: 1 },
+            },
+        },
+        receipt: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "actionKey",
+                "status",
+                "effectFingerprint",
+                "productStateDelta",
+                "reasonCode",
+            ],
+            properties: {
+                actionKey: { type: "string", minLength: 1 },
+                status: {
+                    type: "string",
+                    enum: [...REFILL_V3_ADVANCE_RECEIPT_STATUSES],
+                },
+                effectFingerprint: { type: "string", minLength: 1 },
+                productStateDelta: { type: "boolean" },
+                reasonCode: {
+                    type: ["string", "null"],
+                    enum: [...REFILL_V3_ADVANCE_REASON_CODES, null],
+                },
+            },
+        },
+        // The Plan 02 packet schema, plus the ONE transport key its encoder attaches.
+        // The packet's own `additionalProperties: false` still governs its business
+        // fields; widening it here for `schemaVersion` only is what keeps the two
+        // contracts mutually satisfiable instead of mutually exclusive.
+        packet: {
+            ...REFILL_V3_CAMPAIGN_ATTENTION_PACKET_SCHEMA,
+            properties: {
+                ...REFILL_V3_CAMPAIGN_ATTENTION_PACKET_SCHEMA.properties,
+                schemaVersion: { type: "string" },
+            },
+        },
+        deferral: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "senderId",
+                "date",
+                "lane",
+                "campaignId",
+                "code",
+                "message",
+                "resumeAt",
+                "receiptRef",
+            ],
+            properties: {
+                ...ROW_SCOPE_PROPERTIES,
+                code: { type: "string", enum: [...REFILL_V3_ADVANCE_REASON_CODES] },
+                message: { type: "string" },
+                resumeAt: { type: ["string", "null"] },
+                receiptRef: { type: ["string", "null"] },
+            },
+        },
+        blocker: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "senderId",
+                "date",
+                "lane",
+                "campaignId",
+                "code",
+                "message",
+                "permanent",
+                "field",
+            ],
+            properties: {
+                ...ROW_SCOPE_PROPERTIES,
+                code: { type: "string", enum: [...REFILL_V3_ADVANCE_REASON_CODES] },
+                message: { type: "string" },
+                permanent: { type: "boolean" },
+                field: { type: ["string", "null"] },
+            },
+        },
+        terminal: {
+            type: "string",
+            enum: [...REFILL_V3_ADVANCE_TERMINAL_CODES],
+        },
+        observation: OBSERVATION_SCHEMA,
+        replacementObservation: OBSERVATION_SCHEMA,
+    },
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Sole unknown-value decoder
+// ───────────────────────────────────────────────────────────────────────────
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isOneOfAdvance(value, allowed) {
+    return (typeof value === "string" && allowed.includes(value));
+}
+const ADVANCE_TRANSPORT_KEYS = ["schemaVersion"];
+const CANONICAL_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function onlyKeys(record, allowed) {
+    return Object.keys(record).every((key) => allowed.includes(key));
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function count(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function decodeSupply(value) {
+    if (!isRecord(value) || !onlyKeys(value, REFILL_V3_SUPPLY_BUCKETS)) {
+        return null;
+    }
+    if (REFILL_V3_SUPPLY_BUCKETS.some((bucket) => !count(value[bucket]))) {
+        return null;
+    }
+    return {
+        readyToSchedule: value.readyToSchedule,
+        readyForApproval: value.readyForApproval,
+        readyForMessageGeneration: value.readyForMessageGeneration,
+        needsEnrichment: value.needsEnrichment,
+    };
+}
+function decodeObservation(value) {
+    if (!isRecord(value))
+        return null;
+    const keys = [
+        "observationFingerprint",
+        "senderCount",
+        "rowCount",
+        "dates",
+        "availableSlots",
+        "supply",
+    ];
+    if (!onlyKeys(value, keys) || keys.some((key) => !(key in value))) {
+        return null;
+    }
+    if (!nonEmptyString(value.observationFingerprint) ||
+        !count(value.senderCount) ||
+        !count(value.rowCount) ||
+        !count(value.availableSlots) ||
+        !Array.isArray(value.dates) ||
+        value.dates.some((date) => typeof date !== "string" || !CANONICAL_DATE.test(date))) {
+        return null;
+    }
+    const supply = decodeSupply(value.supply);
+    if (!supply)
+        return null;
+    return {
+        observationFingerprint: value.observationFingerprint,
+        senderCount: value.senderCount,
+        rowCount: value.rowCount,
+        dates: [...value.dates],
+        availableSlots: value.availableSlots,
+        supply,
+    };
+}
+function decodeScopeEcho(value) {
+    if (!isRecord(value))
+        return null;
+    const keys = ["workspaceId", "scopeKind", "scopeFingerprint"];
+    if (!onlyKeys(value, keys) || keys.some((key) => !(key in value)))
+        return null;
+    if (!nonEmptyString(value.workspaceId) ||
+        !nonEmptyString(value.scopeFingerprint) ||
+        !isOneOfAdvance(value.scopeKind, [
+            "sender_local_horizon",
+            "exact_sender_dates",
+        ])) {
+        return null;
+    }
+    return {
+        workspaceId: value.workspaceId,
+        scopeKind: value.scopeKind,
+        scopeFingerprint: value.scopeFingerprint,
+    };
+}
+function decodeRowScope(value) {
+    if (!nonEmptyString(value.senderId) ||
+        typeof value.date !== "string" ||
+        !CANONICAL_DATE.test(value.date) ||
+        !isOneOfAdvance(value.lane, REFILL_V3_WORLD_STATE_LANES) ||
+        (value.campaignId !== null && !nonEmptyString(value.campaignId))) {
+        return null;
+    }
+    return {
+        senderId: value.senderId,
+        date: value.date,
+        lane: value.lane,
+        campaignId: value.campaignId,
+    };
+}
+function decodeAction(value) {
+    if (!isRecord(value))
+        return null;
+    const keys = [
+        "kind",
+        "actionKey",
+        "authority",
+        "senderId",
+        "date",
+        "lane",
+        "campaignId",
+        "evidenceFingerprint",
+    ];
+    if (!onlyKeys(value, keys) || keys.some((key) => !(key in value)))
+        return null;
+    const rowScope = decodeRowScope(value);
+    if (!rowScope)
+        return null;
+    if (!isOneOfAdvance(value.kind, REFILL_V3_ADVANCE_ACTION_KINDS) ||
+        !nonEmptyString(value.actionKey) ||
+        !nonEmptyString(value.evidenceFingerprint)) {
+        return null;
+    }
+    // The authority is a CLOSED map lookup, so a mismatched pair is malformed
+    // transport rather than a plausible action.
+    if (value.authority !== REFILL_V3_ADVANCE_ACTION_AUTHORITIES[value.kind]) {
+        return null;
+    }
+    return {
+        kind: value.kind,
+        actionKey: value.actionKey,
+        authority: REFILL_V3_ADVANCE_ACTION_AUTHORITIES[value.kind],
+        ...rowScope,
+        evidenceFingerprint: value.evidenceFingerprint,
+    };
+}
+function decodeReceipt(value) {
+    if (!isRecord(value))
+        return null;
+    const keys = [
+        "actionKey",
+        "status",
+        "effectFingerprint",
+        "productStateDelta",
+        "reasonCode",
+    ];
+    if (!onlyKeys(value, keys) || keys.some((key) => !(key in value)))
+        return null;
+    if (!nonEmptyString(value.actionKey) ||
+        !isOneOfAdvance(value.status, REFILL_V3_ADVANCE_RECEIPT_STATUSES) ||
+        !nonEmptyString(value.effectFingerprint) ||
+        typeof value.productStateDelta !== "boolean") {
+        return null;
+    }
+    if (value.reasonCode !== null &&
+        !isOneOfAdvance(value.reasonCode, REFILL_V3_ADVANCE_REASON_CODES)) {
+        return null;
+    }
+    return {
+        actionKey: value.actionKey,
+        status: value.status,
+        effectFingerprint: value.effectFingerprint,
+        productStateDelta: value.productStateDelta,
+        reasonCode: value.reasonCode,
+    };
+}
+function decodeDeferral(value) {
+    if (!isRecord(value))
+        return null;
+    const keys = [
+        "senderId",
+        "date",
+        "lane",
+        "campaignId",
+        "code",
+        "message",
+        "resumeAt",
+        "receiptRef",
+    ];
+    if (!onlyKeys(value, keys) || keys.some((key) => !(key in value)))
+        return null;
+    const rowScope = decodeRowScope(value);
+    if (!rowScope)
+        return null;
+    if (!isOneOfAdvance(value.code, REFILL_V3_ADVANCE_REASON_CODES) ||
+        typeof value.message !== "string" ||
+        (value.resumeAt !== null && !nonEmptyString(value.resumeAt)) ||
+        (value.receiptRef !== null && !nonEmptyString(value.receiptRef))) {
+        return null;
+    }
+    return {
+        ...rowScope,
+        code: value.code,
+        message: value.message,
+        resumeAt: value.resumeAt,
+        receiptRef: value.receiptRef,
+    };
+}
+function decodeBlocker(value) {
+    if (!isRecord(value))
+        return null;
+    const keys = [
+        "senderId",
+        "date",
+        "lane",
+        "campaignId",
+        "code",
+        "message",
+        "permanent",
+        "field",
+    ];
+    if (!onlyKeys(value, keys) || keys.some((key) => !(key in value)))
+        return null;
+    const rowScope = decodeRowScope(value);
+    if (!rowScope)
+        return null;
+    if (!isOneOfAdvance(value.code, REFILL_V3_ADVANCE_REASON_CODES) ||
+        typeof value.message !== "string" ||
+        typeof value.permanent !== "boolean" ||
+        (value.field !== null && !nonEmptyString(value.field))) {
+        return null;
+    }
+    return {
+        ...rowScope,
+        code: value.code,
+        message: value.message,
+        permanent: value.permanent,
+        field: value.field,
+    };
+}
+/**
+ * Sole unknown-value decoder for the public advance result.
+ *
+ * STRICT and FAIL-CLOSED per variant: the union discriminator selects ONE exact
+ * key set, so a result that carries an `advanced` payload under a `complete`
+ * kind, an unknown action, a leaked row identity, or a missing replacement
+ * observation is rejected outright rather than narrowed into a confident
+ * partial success.
+ */
+export function decodeRefillV3AdvanceResult(value) {
+    if (!isRecord(value))
+        return null;
+    if (!isOneOfAdvance(value.kind, REFILL_V3_ADVANCE_RESULT_KINDS))
+        return null;
+    const required = REFILL_V3_ADVANCE_RESULT_KEYS[value.kind];
+    if (!onlyKeys(value, [...required, ...ADVANCE_TRANSPORT_KEYS]))
+        return null;
+    if (required.some((key) => !(key in value)))
+        return null;
+    if (value.schemaVersion !== undefined &&
+        !resolveRefillV3AdvanceSchemaVersion(value.schemaVersion).supported) {
+        return null;
+    }
+    const scope = decodeScopeEcho(value.scope);
+    if (!scope)
+        return null;
+    if (value.kind === "advanced") {
+        const action = decodeAction(value.action);
+        const receipt = decodeReceipt(value.receipt);
+        const replacementObservation = decodeObservation(value.replacementObservation);
+        if (!action || !receipt || !replacementObservation)
+            return null;
+        // The receipt must belong to the ACTION it claims to receipt.
+        if (receipt.actionKey !== action.actionKey)
+            return null;
+        return { kind: "advanced", scope, action, receipt, replacementObservation };
+    }
+    const observation = decodeObservation(value.observation);
+    if (!observation)
+        return null;
+    if (value.kind === "campaign_attention_required") {
+        const packet = decodeRefillV3CampaignAttentionPacket(value.packet);
+        // The typed unsupported VALUE is a different fact from `null`, but neither is
+        // a usable packet for this seam, so both reject the whole result.
+        if (packet === null || packet === REFILL_V3_SCHEMA_VERSION_UNSUPPORTED) {
+            return null;
+        }
+        return { kind: "campaign_attention_required", scope, packet, observation };
+    }
+    if (value.kind === "awaiting_external_change") {
+        const deferral = decodeDeferral(value.deferral);
+        if (!deferral)
+            return null;
+        return { kind: "awaiting_external_change", scope, deferral, observation };
+    }
+    if (value.kind === "complete") {
+        if (!isOneOfAdvance(value.terminal, REFILL_V3_ADVANCE_TERMINAL_CODES)) {
+            return null;
+        }
+        return { kind: "complete", scope, terminal: value.terminal, observation };
+    }
+    const blocker = decodeBlocker(value.blocker);
+    if (!blocker)
+        return null;
+    return { kind: "blocked", scope, blocker, observation };
+}
+/** Wire form of a decoded result. `schemaVersion` is TRANSPORT, not business. */
+export function encodeRefillV3AdvanceResult(result) {
+    const base = {
+        schemaVersion: REFILL_V3_ADVANCE_SCHEMA_VERSION,
+        kind: result.kind,
+        scope: { ...result.scope },
+    };
+    if (result.kind === "advanced") {
+        return {
+            ...base,
+            action: { ...result.action },
+            receipt: { ...result.receipt },
+            replacementObservation: {
+                ...result.replacementObservation,
+                dates: [...result.replacementObservation.dates],
+                supply: { ...result.replacementObservation.supply },
+            },
+        };
+    }
+    const observation = {
+        ...result.observation,
+        dates: [...result.observation.dates],
+        supply: { ...result.observation.supply },
+    };
+    if (result.kind === "campaign_attention_required") {
+        return {
+            ...base,
+            packet: encodeRefillV3CampaignAttentionPacket(result.packet),
+            observation,
+        };
+    }
+    if (result.kind === "awaiting_external_change") {
+        return { ...base, deferral: { ...result.deferral }, observation };
+    }
+    if (result.kind === "complete") {
+        return { ...base, terminal: result.terminal, observation };
+    }
+    return { ...base, blocker: { ...result.blocker }, observation };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// The canonical V3 flow asset and its COMPATIBLE-RANGE version gate
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The ONE canonical V3 flow asset. The authoritative consumer is the INSTALLED
+ * skill cache, not a file in this repository, so the gate is a compatible RANGE
+ * rather than an exact string: an exact pin would halt every installed caller the
+ * moment a compatible minor shipped.
+ */
+export const REFILL_V3_FLOW_ASSET = Object.freeze({
+    subskillName: "refill-sends-workflow",
+    assetPath: "core/flow.v3.json",
+    minimumVersion: "v3.0",
+    compatibleMajor: "v3",
+    versionPolicy: "compatible_range",
+});
+export const REFILL_V3_FLOW_VERSION_VERDICTS = [
+    "compatible",
+    "incompatible_major",
+    "below_minimum_minor",
+    "malformed",
+];
+/**
+ * The typed flow-asset version gate (error law 3): an incompatible major is a
+ * NAMED value, never a bare `false` and never a throw.
+ *
+ * It carries its own two-integer parser instead of importing
+ * `isCompatibleRefillFlowVersion`, because that symbol lives beside the V1 API
+ * client and a contract module must stay free of the transport layer. The two are
+ * bound by an executable agreement assertion in
+ * `tests/mcp/refill-v3/146-flow-v3-contract.ts` rather than by one of them
+ * silently forking.
+ */
+export function resolveRefillV3FlowAssetVersion(value, bounds = {}) {
+    const parse = (candidate) => {
+        if (typeof candidate !== "string")
+            return null;
+        const match = /^v(\d+)\.(\d+)$/.exec(candidate.trim());
+        if (!match)
+            return null;
+        return { major: Number(match[1]), minor: Number(match[2]) };
+    };
+    const actual = parse(value);
+    if (!actual)
+        return { verdict: "malformed" };
+    const minimum = parse(bounds.minimumVersion ?? REFILL_V3_FLOW_ASSET.minimumVersion);
+    const expectedMajor = parse(`${bounds.compatibleMajor ?? REFILL_V3_FLOW_ASSET.compatibleMajor}.0`);
+    if (!minimum || !expectedMajor)
+        return { verdict: "malformed" };
+    if (actual.major !== expectedMajor.major) {
+        return { verdict: "incompatible_major", ...actual };
+    }
+    if (actual.minor < minimum.minor) {
+        return { verdict: "below_minimum_minor", ...actual };
+    }
+    return { verdict: "compatible", ...actual };
+}
+/**
+ * Tokens no thin caller may contain. Each is a DECISION the deterministic plane
+ * owns: choosing a row, a campaign, a lane, an action, a terminal, or a retry.
+ */
+export const REFILL_V3_FLOW_FORBIDDEN_CALLER_TOKENS = [
+    "availableSlots",
+    "readyToSchedule",
+    "readyForApproval",
+    "needsEnrichment",
+    "leadSourceFamily",
+    "post_engager",
+    "signal_discovery",
+    "active_campaigns_exhausted",
+    "paid_inmail_connection_health_recheck_required",
+    "recheck_sender_connection",
+    "refresh_paid_credit_fact",
+    "refill_v3_fill_ready",
+    "retryCount",
+    "cursor",
+    "continuation",
+];
+/**
+ * The RETIRED public V3 names and the exact replacement an old caller must use.
+ *
+ * This covers the REAL skew, not just the new package: an already-installed skill
+ * or a cached flow asset can still invoke a removed tool name against the new
+ * server. A bare "Unknown tool" is an opaque dead end, so the refusal names the
+ * one surviving observation surface instead.
+ */
+export const REFILL_V3_RETIRED_TOOL_REPLACEMENTS = Object.freeze({
+    refill_v3_workspace_inventory: "refill_v3_world_state",
+    refill_v3_sender_date_eligibility: "refill_v3_world_state",
+    refill_v3_supply_assessment: "refill_v3_world_state",
+});
+/**
+ * The typed unknown-tool refusal message for a retired V3 name. It returns a
+ * VALUE, never a throw of its own, so the caller gets an actionable replacement
+ * with zero partial dispatch.
+ */
+export function refillV3RetiredToolRefusal(name) {
+    const replacement = REFILL_V3_RETIRED_TOOL_REPLACEMENTS[name];
+    return replacement
+        ? `Unknown tool: ${name}. It was retired in Refill V3; use ${replacement} instead, which returns the whole workspace observation in one call.`
+        : null;
+}
+/** The two lanes and the closed family list, re-exported for one-import use. */
+export const REFILL_V3_ADVANCE_LANES = REFILL_V3_WORLD_STATE_LANES;
+export const REFILL_V3_ADVANCE_LEAD_SOURCE_FAMILIES = REFILL_V3_LEAD_SOURCE_FAMILIES;