@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-advance-contract.d.ts

@@ -0,0 +1,618 @@
+/**
+ * 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_RESULTS, REFILL_V3_EXHAUSTION_PREDICATE, decodeRefillV3CampaignAttentionPacket, encodeRefillV3CampaignAttentionPacket, type RefillV3CampaignAttentionAction, type RefillV3CampaignAttentionPacket, type RefillV3SchemaVersionSupport, type RefillV3SupplyCounts } from "./refill-v3-attention-packet-contract.js";
+import { type RefillWorldStateLane } 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, };
+export type { RefillV3CampaignAttentionAction, RefillV3CampaignAttentionPacket, RefillV3SupplyCounts, };
+export declare const REFILL_V3_ADVANCE_SCHEMA_NAMESPACE: "refill_v3_advance";
+export declare const REFILL_V3_ADVANCE_SCHEMA_MAJOR = 1;
+export declare const REFILL_V3_ADVANCE_SCHEMA_VERSION: "refill_v3_advance.v1.0";
+export declare function resolveRefillV3AdvanceSchemaVersion(value: unknown): RefillV3SchemaVersionSupport;
+/**
+ * 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 declare const REFILL_V3_ADVANCE_INPUT_KEYS: readonly ["workspaceId", "scope", "yolo"];
+export type RefillV3AdvanceInputKey = (typeof REFILL_V3_ADVANCE_INPUT_KEYS)[number];
+/** The keys a caller MUST supply. `yolo` is optional and defaults to false. */
+export declare const REFILL_V3_ADVANCE_REQUIRED_INPUT_KEYS: readonly ["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 declare const REFILL_V3_ADVANCE_FORBIDDEN_INPUT_KEYS: readonly ["continuation", "taskReceipts", "authorityReceiptFacts", "receiptFacts", "retryCount", "attempt", "attempts", "cursor", "rows", "row", "actions", "action", "progress", "runId", "ledger", "waterfall", "evaluatedAt"];
+export declare const REFILL_V3_ADVANCE_INPUT_SCHEMA: Readonly<{
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["workspaceId", "scope"];
+    readonly properties: {
+        readonly workspaceId: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Explicit request-scoped workspace id. Pass this instead of switching the shared active workspace.";
+        };
+        readonly scope: {
+            readonly 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.";
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "days"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly const: "sender_local_horizon";
+                    };
+                    readonly days: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly maximum: 3;
+                    };
+                    readonly senderIds: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly minItems: 1;
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "senderDates"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly const: "exact_sender_dates";
+                    };
+                    readonly senderDates: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["senderId", "dates"];
+                            readonly properties: {
+                                readonly senderId: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly dates: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            }];
+        };
+        readonly yolo: {
+            readonly type: "boolean";
+            readonly 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.";
+        };
+    };
+}>;
+export declare const REFILL_V3_ADVANCE_RESULT_KINDS: readonly ["advanced", "campaign_attention_required", "awaiting_external_change", "complete", "blocked"];
+export type RefillV3AdvanceResultKind = (typeof REFILL_V3_ADVANCE_RESULT_KINDS)[number];
+/**
+ * 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 declare const REFILL_V3_ADVANCE_ACTION_KINDS: readonly ["refresh_paid_credit_fact", "recheck_sender_connection", "fill_ready", "start_evergreen_campaign"];
+export type RefillV3AdvanceActionKind = (typeof REFILL_V3_ADVANCE_ACTION_KINDS)[number];
+/** The exact existing owner each action key dispatches to. */
+export declare const REFILL_V3_ADVANCE_ACTION_AUTHORITIES: Readonly<{
+    readonly refresh_paid_credit_fact: "getOrRefreshPaidInmailCreditFact";
+    readonly recheck_sender_connection: "recheckRefillV3SenderConnection";
+    readonly fill_ready: "fillRefillV3Ready";
+    readonly start_evergreen_campaign: "startRefillV3EvergreenCampaign";
+}>;
+export type RefillV3AdvanceAuthority = (typeof REFILL_V3_ADVANCE_ACTION_AUTHORITIES)[RefillV3AdvanceActionKind];
+/**
+ * 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 declare const REFILL_V3_ADVANCE_ACTION_PRECEDENCE: readonly ["refresh_paid_credit_fact", "recheck_sender_connection", "fill_ready", "campaign_attention"];
+/** Closed terminal codes. `complete` carries exactly one of these. */
+export declare const REFILL_V3_ADVANCE_TERMINAL_CODES: readonly ["active_campaigns_exhausted", "no_eligible_campaigns", "campaign_supply_unclaimed_defect", "daily_targets_met", "scope_unresolved"];
+export type RefillV3AdvanceTerminalCode = (typeof REFILL_V3_ADVANCE_TERMINAL_CODES)[number];
+/**
+ * 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 declare const REFILL_V3_ADVANCE_ONLY_REASON_CODES: readonly ["account_identity_missing", "no_progress_refused", "retryable_paid_attempts_exhausted", "unknown_transport_vocabulary", "forged_authority_receipt_facts", "authority_failure_uncertain", "sender_scope_unresolved", "campaign_supply_unclaimed", "lane_campaigns_exhausted", "missing_balance", "blocked", "workspace_membership_revoked"];
+export type RefillV3AdvanceOnlyReasonCode = (typeof REFILL_V3_ADVANCE_ONLY_REASON_CODES)[number];
+export declare const REFILL_V3_ADVANCE_REASON_CODES: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight", "zero_requested_count", "idempotency_scope_mismatch", "uncertain_outcome", "placed_under_other_sender", "placed_off_target_date", "paid_inmail_credit_receipt_invalid", "awaiting_external_change", "approval_authority_invalid", "approval_authority_in_flight", "approval_dispatch_incomplete", "ready_cells_unavailable", "sender_affinity_conflict", "scheduler_target_omitted", "scheduler_failed", "receipt_readback_mismatch", "account_identity_missing", "no_progress_refused", "retryable_paid_attempts_exhausted", "unknown_transport_vocabulary", "forged_authority_receipt_facts", "authority_failure_uncertain", "sender_scope_unresolved", "campaign_supply_unclaimed", "lane_campaigns_exhausted", "missing_balance", "blocked", "workspace_membership_revoked"];
+export type RefillV3AdvanceReasonCode = (typeof REFILL_V3_ADVANCE_REASON_CODES)[number];
+export declare const REFILL_V3_ADVANCE_RECEIPT_STATUSES: readonly ["executed", "attached", "failed", "indeterminate"];
+export type RefillV3AdvanceReceiptStatus = (typeof REFILL_V3_ADVANCE_RECEIPT_STATUSES)[number];
+/**
+ * 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 declare const REFILL_V3_ADVANCE_FORBIDDEN_RESULT_KEYS: readonly ["rows", "cells", "rowIds", "cellIds", "rowPayload", "cellPayload", "providerResponse", "providerPayload", "rank", "ranking", "graph", "waterfall", "retryCount", "attempts", "cursor", "continuation", "prompt", "instructions", "durationMs", "evaluatedAt"];
+export type RefillV3AdvanceScopeEcho = {
+    workspaceId: string;
+    scopeKind: "sender_local_horizon" | "exact_sender_dates";
+    /** Stable identity of the requested scope. Never a clock or a nonce. */
+    scopeFingerprint: string;
+};
+/**
+ * The bounded observation summary every variant carries. It is a FINGERPRINT
+ * plus aggregate counts, never rows: a caller that needs rows calls
+ * `refill_v3_world_state`.
+ */
+export type RefillV3AdvanceObservation = {
+    observationFingerprint: string;
+    senderCount: number;
+    rowCount: number;
+    dates: string[];
+    availableSlots: number;
+    supply: RefillV3SupplyCounts;
+};
+export type RefillV3AdvanceActionIdentity = {
+    kind: RefillV3AdvanceActionKind;
+    /** Derived ONLY from product-state facts. No clock, nonce, or duration. */
+    actionKey: string;
+    authority: RefillV3AdvanceAuthority;
+    senderId: string;
+    date: string;
+    lane: RefillWorldStateLane;
+    campaignId: string | null;
+    evidenceFingerprint: string;
+};
+export type RefillV3AdvanceReceiptRef = {
+    actionKey: string;
+    status: RefillV3AdvanceReceiptStatus;
+    effectFingerprint: string;
+    productStateDelta: boolean;
+    reasonCode: RefillV3AdvanceReasonCode | null;
+};
+export type RefillV3AdvanceRowScope = {
+    senderId: string;
+    date: string;
+    lane: RefillWorldStateLane;
+    campaignId: string | null;
+};
+export type RefillV3AdvanceDeferral = RefillV3AdvanceRowScope & {
+    code: RefillV3AdvanceReasonCode;
+    message: string;
+    resumeAt: string | null;
+    /** The last matching authority receipt, by action key. */
+    receiptRef: string | null;
+};
+export type RefillV3AdvanceBlocker = RefillV3AdvanceRowScope & {
+    code: RefillV3AdvanceReasonCode;
+    message: string;
+    permanent: boolean;
+    /** The offending closed-vocabulary field for a fail-closed refusal. */
+    field: string | null;
+};
+export type RefillV3AdvanceResult = {
+    kind: "advanced";
+    scope: RefillV3AdvanceScopeEcho;
+    action: RefillV3AdvanceActionIdentity;
+    receipt: RefillV3AdvanceReceiptRef;
+    /** The MANDATORY exact-scope reread. Never the coordinator's own claim. */
+    replacementObservation: RefillV3AdvanceObservation;
+} | {
+    kind: "campaign_attention_required";
+    scope: RefillV3AdvanceScopeEcho;
+    packet: RefillV3CampaignAttentionPacket;
+    observation: RefillV3AdvanceObservation;
+} | {
+    kind: "awaiting_external_change";
+    scope: RefillV3AdvanceScopeEcho;
+    deferral: RefillV3AdvanceDeferral;
+    observation: RefillV3AdvanceObservation;
+} | {
+    kind: "complete";
+    scope: RefillV3AdvanceScopeEcho;
+    terminal: RefillV3AdvanceTerminalCode;
+    observation: RefillV3AdvanceObservation;
+} | {
+    kind: "blocked";
+    scope: RefillV3AdvanceScopeEcho;
+    blocker: RefillV3AdvanceBlocker;
+    observation: RefillV3AdvanceObservation;
+};
+/** Required keys per variant. The decoder rejects any other key set. */
+export declare const REFILL_V3_ADVANCE_RESULT_KEYS: Readonly<{
+    readonly advanced: readonly ["kind", "scope", "action", "receipt", "replacementObservation"];
+    readonly campaign_attention_required: readonly ["kind", "scope", "packet", "observation"];
+    readonly awaiting_external_change: readonly ["kind", "scope", "deferral", "observation"];
+    readonly complete: readonly ["kind", "scope", "terminal", "observation"];
+    readonly blocked: readonly ["kind", "scope", "blocker", "observation"];
+}>;
+/**
+ * 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 declare const REFILL_V3_ADVANCE_OUTPUT_SCHEMA: Readonly<{
+    readonly type: "object";
+    readonly required: readonly ["kind", "scope"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly type: "string";
+        };
+        readonly kind: {
+            readonly type: "string";
+            readonly enum: readonly ["advanced", "campaign_attention_required", "awaiting_external_change", "complete", "blocked"];
+        };
+        readonly scope: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["workspaceId", "scopeKind", "scopeFingerprint"];
+            readonly properties: {
+                readonly workspaceId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly scopeKind: {
+                    readonly type: "string";
+                    readonly enum: readonly ["sender_local_horizon", "exact_sender_dates"];
+                };
+                readonly scopeFingerprint: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly action: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["kind", "actionKey", "authority", "senderId", "date", "lane", "campaignId", "evidenceFingerprint"];
+            readonly properties: {
+                readonly evidenceFingerprint: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly senderId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly date: {
+                    readonly type: "string";
+                    readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                };
+                readonly lane: {
+                    readonly type: "string";
+                    readonly enum: readonly ["connection_invite", "paid_inmail"];
+                };
+                readonly campaignId: {
+                    readonly type: readonly ["string", "null"];
+                };
+                readonly kind: {
+                    readonly type: "string";
+                    readonly enum: readonly ["refresh_paid_credit_fact", "recheck_sender_connection", "fill_ready", "start_evergreen_campaign"];
+                };
+                readonly actionKey: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly authority: {
+                    readonly type: "string";
+                    readonly enum: ("getOrRefreshPaidInmailCreditFact" | "recheckRefillV3SenderConnection" | "fillRefillV3Ready" | "startRefillV3EvergreenCampaign")[];
+                };
+            };
+        };
+        readonly receipt: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["actionKey", "status", "effectFingerprint", "productStateDelta", "reasonCode"];
+            readonly properties: {
+                readonly actionKey: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly status: {
+                    readonly type: "string";
+                    readonly enum: readonly ["executed", "attached", "failed", "indeterminate"];
+                };
+                readonly effectFingerprint: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly productStateDelta: {
+                    readonly type: "boolean";
+                };
+                readonly reasonCode: {
+                    readonly type: readonly ["string", "null"];
+                    readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight", "zero_requested_count", "idempotency_scope_mismatch", "uncertain_outcome", "placed_under_other_sender", "placed_off_target_date", "paid_inmail_credit_receipt_invalid", "awaiting_external_change", "approval_authority_invalid", "approval_authority_in_flight", "approval_dispatch_incomplete", "ready_cells_unavailable", "sender_affinity_conflict", "scheduler_target_omitted", "scheduler_failed", "receipt_readback_mismatch", "account_identity_missing", "no_progress_refused", "retryable_paid_attempts_exhausted", "unknown_transport_vocabulary", "forged_authority_receipt_facts", "authority_failure_uncertain", "sender_scope_unresolved", "campaign_supply_unclaimed", "lane_campaigns_exhausted", "missing_balance", "blocked", "workspace_membership_revoked", null];
+                };
+            };
+        };
+        readonly packet: {
+            readonly properties: {
+                readonly schemaVersion: {
+                    readonly type: "string";
+                };
+            };
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["scope", "evidence"];
+        };
+        readonly deferral: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["senderId", "date", "lane", "campaignId", "code", "message", "resumeAt", "receiptRef"];
+            readonly properties: {
+                readonly code: {
+                    readonly type: "string";
+                    readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight", "zero_requested_count", "idempotency_scope_mismatch", "uncertain_outcome", "placed_under_other_sender", "placed_off_target_date", "paid_inmail_credit_receipt_invalid", "awaiting_external_change", "approval_authority_invalid", "approval_authority_in_flight", "approval_dispatch_incomplete", "ready_cells_unavailable", "sender_affinity_conflict", "scheduler_target_omitted", "scheduler_failed", "receipt_readback_mismatch", "account_identity_missing", "no_progress_refused", "retryable_paid_attempts_exhausted", "unknown_transport_vocabulary", "forged_authority_receipt_facts", "authority_failure_uncertain", "sender_scope_unresolved", "campaign_supply_unclaimed", "lane_campaigns_exhausted", "missing_balance", "blocked", "workspace_membership_revoked"];
+                };
+                readonly message: {
+                    readonly type: "string";
+                };
+                readonly resumeAt: {
+                    readonly type: readonly ["string", "null"];
+                };
+                readonly receiptRef: {
+                    readonly type: readonly ["string", "null"];
+                };
+                readonly senderId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly date: {
+                    readonly type: "string";
+                    readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                };
+                readonly lane: {
+                    readonly type: "string";
+                    readonly enum: readonly ["connection_invite", "paid_inmail"];
+                };
+                readonly campaignId: {
+                    readonly type: readonly ["string", "null"];
+                };
+            };
+        };
+        readonly blocker: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["senderId", "date", "lane", "campaignId", "code", "message", "permanent", "field"];
+            readonly properties: {
+                readonly code: {
+                    readonly type: "string";
+                    readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight", "zero_requested_count", "idempotency_scope_mismatch", "uncertain_outcome", "placed_under_other_sender", "placed_off_target_date", "paid_inmail_credit_receipt_invalid", "awaiting_external_change", "approval_authority_invalid", "approval_authority_in_flight", "approval_dispatch_incomplete", "ready_cells_unavailable", "sender_affinity_conflict", "scheduler_target_omitted", "scheduler_failed", "receipt_readback_mismatch", "account_identity_missing", "no_progress_refused", "retryable_paid_attempts_exhausted", "unknown_transport_vocabulary", "forged_authority_receipt_facts", "authority_failure_uncertain", "sender_scope_unresolved", "campaign_supply_unclaimed", "lane_campaigns_exhausted", "missing_balance", "blocked", "workspace_membership_revoked"];
+                };
+                readonly message: {
+                    readonly type: "string";
+                };
+                readonly permanent: {
+                    readonly type: "boolean";
+                };
+                readonly field: {
+                    readonly type: readonly ["string", "null"];
+                };
+                readonly senderId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly date: {
+                    readonly type: "string";
+                    readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                };
+                readonly lane: {
+                    readonly type: "string";
+                    readonly enum: readonly ["connection_invite", "paid_inmail"];
+                };
+                readonly campaignId: {
+                    readonly type: readonly ["string", "null"];
+                };
+            };
+        };
+        readonly terminal: {
+            readonly type: "string";
+            readonly enum: readonly ["active_campaigns_exhausted", "no_eligible_campaigns", "campaign_supply_unclaimed_defect", "daily_targets_met", "scope_unresolved"];
+        };
+        readonly observation: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["observationFingerprint", "senderCount", "rowCount", "dates", "availableSlots", "supply"];
+            readonly properties: {
+                readonly observationFingerprint: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly senderCount: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                };
+                readonly rowCount: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                };
+                readonly dates: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                };
+                readonly availableSlots: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                };
+                readonly supply: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                    readonly properties: {
+                        [k: string]: {
+                            type: string;
+                            minimum: number;
+                        };
+                    };
+                };
+            };
+        };
+        readonly replacementObservation: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["observationFingerprint", "senderCount", "rowCount", "dates", "availableSlots", "supply"];
+            readonly properties: {
+                readonly observationFingerprint: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly senderCount: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                };
+                readonly rowCount: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                };
+                readonly dates: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                };
+                readonly availableSlots: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                };
+                readonly supply: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                    readonly properties: {
+                        [k: string]: {
+                            type: string;
+                            minimum: number;
+                        };
+                    };
+                };
+            };
+        };
+    };
+}>;
+/**
+ * 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 declare function decodeRefillV3AdvanceResult(value: unknown): RefillV3AdvanceResult | null;
+/** Wire form of a decoded result. `schemaVersion` is TRANSPORT, not business. */
+export declare function encodeRefillV3AdvanceResult(result: RefillV3AdvanceResult): Record<string, unknown>;
+/**
+ * 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 declare const REFILL_V3_FLOW_ASSET: Readonly<{
+    readonly subskillName: "refill-sends-workflow";
+    readonly assetPath: "core/flow.v3.json";
+    readonly minimumVersion: "v3.0";
+    readonly compatibleMajor: "v3";
+    readonly versionPolicy: "compatible_range";
+}>;
+export declare const REFILL_V3_FLOW_VERSION_VERDICTS: readonly ["compatible", "incompatible_major", "below_minimum_minor", "malformed"];
+export type RefillV3FlowVersionVerdict = (typeof REFILL_V3_FLOW_VERSION_VERDICTS)[number];
+/**
+ * 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 declare function resolveRefillV3FlowAssetVersion(value: unknown, bounds?: {
+    minimumVersion?: string;
+    compatibleMajor?: string;
+}): {
+    verdict: RefillV3FlowVersionVerdict;
+    major?: number;
+    minor?: number;
+};
+/**
+ * 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 declare const REFILL_V3_FLOW_FORBIDDEN_CALLER_TOKENS: readonly ["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 declare const REFILL_V3_RETIRED_TOOL_REPLACEMENTS: Readonly<{
+    readonly refill_v3_workspace_inventory: "refill_v3_world_state";
+    readonly refill_v3_sender_date_eligibility: "refill_v3_world_state";
+    readonly refill_v3_supply_assessment: "refill_v3_world_state";
+}>;
+export type RefillV3RetiredToolName = keyof typeof REFILL_V3_RETIRED_TOOL_REPLACEMENTS;
+/**
+ * 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 declare function refillV3RetiredToolRefusal(name: string): string | null;
+/** The two lanes and the closed family list, re-exported for one-import use. */
+export declare const REFILL_V3_ADVANCE_LANES: readonly ["connection_invite", "paid_inmail"];
+export declare const REFILL_V3_ADVANCE_LEAD_SOURCE_FAMILIES: readonly ["post_engager", "signal_discovery", "cold"];