@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-world-state-contract.d.ts

@@ -0,0 +1,666 @@
+/**
+ * Refill V3 world-state PACKAGE seam.
+ *
+ * This module is the SOLE owner of the public result contract:
+ *  - the canonical result/row/campaign/reason/effect types;
+ *  - the finite output vocabularies and the forbidden-leak key list;
+ *  - `REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA`; and
+ *  - `decodeRefillWorldStateResult`, the ONE unknown-value decoder.
+ *
+ * It lives inside `@sellable/mcp` so the public MCP tool can compile and ship
+ * the contract. The app seam `src/lib/refill-v3/world-state-contract.ts`
+ * imports FROM here and type-only re-exports these symbols; nothing here may
+ * import app `src/**`, and no consumer may copy the decoder.
+ *
+ * Decoding rules:
+ *  - hand-rolled type guards plus as-const JSON-Schema literals (A02-NO-ZOD);
+ *  - strict inbound, tolerant outbound, and lossless;
+ *  - an unrecognized ENUM VALUE drops only the SMALLEST unit that carries it,
+ *    so one new job kind can never blank a healthy workspace; and
+ *  - only a malformed envelope, a missing required top-level key, or a policy
+ *    leak key rejects the whole result.
+ */
+import { type RefillV3ActiveJob, type RefillV3LeadSourceFamily, type RefillV3SchemaVersionUnsupported, type RefillV3SupplyCounts } from "./refill-v3-attention-packet-contract.js";
+export type { RefillV3ActiveJob, RefillV3LeadSourceFamily, RefillV3SupplyCounts, };
+export declare const REFILL_V3_WORLD_STATE_SCHEMA_NAMESPACE: "refill_v3_world_state";
+export declare const REFILL_V3_WORLD_STATE_SCHEMA_MAJOR = 1;
+export declare const REFILL_V3_WORLD_STATE_SCHEMA_VERSION: "refill_v3_world_state.v1.0";
+/** The only two Refill V3 lanes in this version. There is no lane input. */
+export declare const REFILL_V3_WORLD_STATE_LANES: readonly ["connection_invite", "paid_inmail"];
+export type RefillWorldStateLane = (typeof REFILL_V3_WORLD_STATE_LANES)[number];
+export declare const REFILL_V3_WORLD_STATE_REASON_KINDS: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+export type RefillWorldStateReasonKind = (typeof REFILL_V3_WORLD_STATE_REASON_KINDS)[number];
+/**
+ * Exactly three PUBLIC cooldown codes. Canonical `endpoint_cooldown` survives
+ * as the separate finite blocker `endpoint_temporarily_unavailable` with a
+ * `resumeAt`; it is deliberately not a fourth cooldown.
+ */
+export declare const REFILL_V3_WORLD_STATE_COOLDOWN_CODES: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown"];
+export declare const REFILL_V3_WORLD_STATE_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"];
+export type RefillWorldStateReasonCode = (typeof REFILL_V3_WORLD_STATE_REASON_CODES)[number];
+export declare const REFILL_V3_WORLD_STATE_CAMPAIGN_STATUSES: readonly ["ACTIVE", "PAUSED"];
+export type RefillWorldStateCampaignStatus = (typeof REFILL_V3_WORLD_STATE_CAMPAIGN_STATUSES)[number];
+export declare const REFILL_V3_WORLD_STATE_EFFECTIVENESS: readonly ["unknown", "low", "medium", "high"];
+export type RefillWorldStateEffectiveness = (typeof REFILL_V3_WORLD_STATE_EFFECTIVENESS)[number];
+export declare const REFILL_V3_WORLD_STATE_SUPPLY_HEALTH: readonly ["unknown", "healthy", "thin", "dry"];
+export type RefillWorldStateSupplyHealth = (typeof REFILL_V3_WORLD_STATE_SUPPLY_HEALTH)[number];
+/**
+ * The PUBLIC paid-credit cache outcome. Observation performs zero product
+ * mutations, and this is the one bookkeeping effect it is allowed to report,
+ * which is why the tool must never claim literal `readOnlyHint: true`.
+ *
+ * The app's internal `REFILL_V3_PAID_CREDIT_CACHE_EFFECTS` is the OBSERVER-side
+ * vocabulary. It is a retained predecessor authority owned by Plan 01, so the
+ * two are bound by an executable set-equality assertion in the app suite rather
+ * than by one of them silently forking.
+ */
+export declare const REFILL_V3_WORLD_STATE_CACHE_OUTCOMES: readonly ["not_checked", "not_eligible", "fresh_cache_used", "refresh_started", "refreshed", "refresh_in_progress", "refresh_failed", "uncertain"];
+export type RefillWorldStateCacheOutcome = (typeof REFILL_V3_WORLD_STATE_CACHE_OUTCOMES)[number];
+export declare const REFILL_V3_WORLD_STATE_PRODUCT_EFFECT_KEYS: readonly ["scheduled", "placed", "sent", "campaignMutated", "approved", "enriched", "generated", "salesNavigatorActioned"];
+export type RefillWorldStateProductEffectKey = (typeof REFILL_V3_WORLD_STATE_PRODUCT_EFFECT_KEYS)[number];
+/**
+ * Policy and identity classes the public result must never carry. `leaves`,
+ * `campaignActionFacts`, and `possibleActions` are internal implementation
+ * terms; raw row/cell/table/action identities are fetched just in time by the
+ * diagnostic authority; and graph/rank/selection fields would move backend
+ * authority into the caller.
+ */
+export declare const REFILL_V3_WORLD_STATE_FORBIDDEN_LEAK_KEYS: readonly ["campaignActionFacts", "leaves", "possibleActions", "boundedRowIds", "rowIds", "rowId", "cellId", "cellIds", "tableId", "actionId", "actionIds", "actionColumnId", "graph", "rank", "ranking", "selectedCampaign", "waterfall", "queryDebug"];
+export type RefillWorldStateForbiddenLeakKey = (typeof REFILL_V3_WORLD_STATE_FORBIDDEN_LEAK_KEYS)[number];
+export type RefillWorldStateSender = {
+    id: string;
+    name: string;
+    timezone: string;
+};
+export type RefillWorldStateReason = {
+    kind: RefillWorldStateReasonKind;
+    codes: RefillWorldStateReasonCode[];
+    message: string;
+    resumeAt?: string;
+};
+/**
+ * REAL engagement numbers behind the `effectiveness` band (146.5-12 §87,
+ * user directive): computed from the product's OWN engagement owner
+ * (`getBatchEngagementStats` over LinkedInOutreach) — `sends` is the owner's
+ * non-FAILED sent count, `acceptRate`/`replyRate` are the SAME integer
+ * percentages the campaigns surface shows (`Math.round(x/sends*100)`,
+ * 0 when sends is 0). ADDITIVE and OPTIONAL: an older backend omits it and
+ * the band stays the only signal; numbers are never fabricated. `sends` is
+ * the sample size — small N is visible by construction.
+ */
+export type RefillWorldStateCampaignEngagement = {
+    sends: number;
+    accepted: number;
+    replied: number;
+    acceptRate: number;
+    replyRate: number;
+};
+export type RefillWorldStateCampaignEvidence = {
+    evergreen: boolean;
+    lastActualUseAt: string | null;
+    lastScheduledUseAt: string | null;
+    effectiveness: RefillWorldStateEffectiveness;
+    supplyHealth: RefillWorldStateSupplyHealth;
+    engagement?: RefillWorldStateCampaignEngagement;
+};
+/**
+ * The ONE canonical campaign entry. The app seam type-only re-exports this
+ * exact symbol; it declares no mirror and no widened variant.
+ */
+export type CampaignOption = {
+    id: string;
+    name: string;
+    status: RefillWorldStateCampaignStatus;
+    lanes: RefillWorldStateLane[];
+    eligible: boolean;
+    reason: RefillWorldStateReason | null;
+    startEligible: boolean;
+    activeJob: RefillV3ActiveJob | null;
+    supply: RefillV3SupplyCounts;
+    leadSourceFamily: RefillV3LeadSourceFamily;
+    evidence: RefillWorldStateCampaignEvidence;
+};
+/**
+ * The account-level paid-credit numbers behind a paid row's credit gate
+ * (146.5-12 §84, additive): the operator-reviewable evidence — best-known
+ * available credits, the lowest column floor among the sender's paid
+ * campaigns, when the fact was last proven, and whether the canonical validity
+ * predicate accepted it. Carried on paid rows only.
+ *
+ * PUBLIC per the coordinator ruling (146.5-12 §84b, typed-honesty law): an
+ * agent session must be able to tell the operator WHY a paid lane is 0, and
+ * the production e2e adjudicates against these numbers. Additive optional —
+ * absent on invite rows and on older backends.
+ */
+export type RefillWorldStatePaidCreditEvidence = {
+    availableCredits: number | null;
+    minimumRequired: number | null;
+    checkedAt: string | null;
+    fresh: boolean;
+};
+export type RefillWorldStateRow = {
+    date: string;
+    sender: RefillWorldStateSender;
+    lane: RefillWorldStateLane;
+    targetSlots: number;
+    takenSlots: number;
+    availableSlots: number;
+    reason: RefillWorldStateReason | null;
+    activeCampaigns: CampaignOption[];
+    inactiveCampaigns: CampaignOption[];
+    /** Present on paid rows once a credit observation ran; see the type doc. */
+    paidCreditEvidence?: RefillWorldStatePaidCreditEvidence | null;
+};
+export type RefillWorldStateObservationSideEffects = {
+    scheduled: false;
+    placed: false;
+    sent: false;
+    campaignMutated: false;
+    approved: false;
+    enriched: false;
+    generated: false;
+    salesNavigatorActioned: false;
+    paidCreditCache: RefillWorldStateCacheOutcome;
+};
+export type RefillWorldStateResult = {
+    rows: RefillWorldStateRow[];
+    durationMs: number;
+    observationSideEffects: RefillWorldStateObservationSideEffects;
+};
+/** Every product mutation boolean, reported explicitly rather than omitted. */
+export declare const REFILL_V3_WORLD_STATE_ZERO_PRODUCT_EFFECTS: Readonly<{
+    readonly scheduled: false;
+    readonly placed: false;
+    readonly sent: false;
+    readonly campaignMutated: false;
+    readonly approved: false;
+    readonly enriched: false;
+    readonly generated: false;
+    readonly salesNavigatorActioned: false;
+}>;
+/**
+ * A TOP-LEVEL OBJECT, never an array: an MCP client validates
+ * `structuredContent` against this declaration, and a tool that declares an
+ * output schema and answers with a shape the client rejects has its ENTIRE
+ * response discarded.
+ */
+export declare const REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA: Readonly<{
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["rows", "durationMs", "observationSideEffects"];
+    readonly properties: {
+        readonly rows: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["date", "sender", "lane", "targetSlots", "takenSlots", "availableSlots", "reason", "activeCampaigns", "inactiveCampaigns"];
+                readonly properties: {
+                    readonly date: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                    readonly sender: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["id", "name", "timezone"];
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly timezone: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                    };
+                    readonly lane: {
+                        readonly type: "string";
+                        readonly enum: readonly ["connection_invite", "paid_inmail"];
+                    };
+                    readonly targetSlots: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly takenSlots: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly availableSlots: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly reason: {
+                        readonly type: readonly ["object", "null"];
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["kind", "codes", "message"];
+                        readonly properties: {
+                            readonly kind: {
+                                readonly type: "string";
+                                readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                            };
+                            readonly codes: {
+                                readonly type: "array";
+                                readonly items: {
+                                    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"];
+                                };
+                            };
+                            readonly message: {
+                                readonly type: "string";
+                            };
+                            readonly resumeAt: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly activeCampaigns: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "name", "status", "lanes", "eligible", "reason", "startEligible", "activeJob", "supply", "leadSourceFamily", "evidence"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                                readonly status: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["ACTIVE", "PAUSED"];
+                                };
+                                readonly lanes: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["connection_invite", "paid_inmail"];
+                                    };
+                                };
+                                readonly eligible: {
+                                    readonly type: "boolean";
+                                };
+                                readonly reason: {
+                                    readonly type: readonly ["object", "null"];
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["kind", "codes", "message"];
+                                    readonly properties: {
+                                        readonly kind: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                                        };
+                                        readonly codes: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                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"];
+                                            };
+                                        };
+                                        readonly message: {
+                                            readonly type: "string";
+                                        };
+                                        readonly resumeAt: {
+                                            readonly type: "string";
+                                        };
+                                    };
+                                };
+                                readonly startEligible: {
+                                    readonly type: "boolean";
+                                };
+                                readonly activeJob: {
+                                    readonly type: readonly ["object", "null"];
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["id", "kind", "status"];
+                                    readonly properties: {
+                                        readonly id: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                        readonly kind: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["enrichment", "message_generation", "source_expansion", "scheduling"];
+                                        };
+                                        readonly status: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["queued", "running"];
+                                        };
+                                    };
+                                };
+                                readonly supply: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                                    readonly properties: {
+                                        readonly readyToSchedule: {
+                                            readonly type: "integer";
+                                            readonly minimum: 0;
+                                        };
+                                        readonly readyForApproval: {
+                                            readonly type: "integer";
+                                            readonly minimum: 0;
+                                        };
+                                        readonly readyForMessageGeneration: {
+                                            readonly type: "integer";
+                                            readonly minimum: 0;
+                                        };
+                                        readonly needsEnrichment: {
+                                            readonly type: "integer";
+                                            readonly minimum: 0;
+                                        };
+                                    };
+                                };
+                                readonly leadSourceFamily: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["post_engager", "signal_discovery", "cold"];
+                                };
+                                readonly evidence: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["evergreen", "lastActualUseAt", "lastScheduledUseAt", "effectiveness", "supplyHealth"];
+                                    readonly properties: {
+                                        readonly evergreen: {
+                                            readonly type: "boolean";
+                                        };
+                                        readonly lastActualUseAt: {
+                                            readonly type: readonly ["string", "null"];
+                                        };
+                                        readonly lastScheduledUseAt: {
+                                            readonly type: readonly ["string", "null"];
+                                        };
+                                        readonly effectiveness: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["unknown", "low", "medium", "high"];
+                                        };
+                                        readonly supplyHealth: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["unknown", "healthy", "thin", "dry"];
+                                        };
+                                        readonly engagement: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: false;
+                                            readonly required: readonly ["sends", "accepted", "replied", "acceptRate", "replyRate"];
+                                            readonly properties: {
+                                                readonly sends: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly accepted: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly replied: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly acceptRate: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                    readonly maximum: 100;
+                                                };
+                                                readonly replyRate: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                    readonly maximum: 100;
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                    readonly inactiveCampaigns: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "name", "status", "lanes", "eligible", "reason", "startEligible", "activeJob", "supply", "leadSourceFamily", "evidence"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                                readonly status: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["ACTIVE", "PAUSED"];
+                                };
+                                readonly lanes: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["connection_invite", "paid_inmail"];
+                                    };
+                                };
+                                readonly eligible: {
+                                    readonly type: "boolean";
+                                };
+                                readonly reason: {
+                                    readonly type: readonly ["object", "null"];
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["kind", "codes", "message"];
+                                    readonly properties: {
+                                        readonly kind: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                                        };
+                                        readonly codes: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                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"];
+                                            };
+                                        };
+                                        readonly message: {
+                                            readonly type: "string";
+                                        };
+                                        readonly resumeAt: {
+                                            readonly type: "string";
+                                        };
+                                    };
+                                };
+                                readonly startEligible: {
+                                    readonly type: "boolean";
+                                };
+                                readonly activeJob: {
+                                    readonly type: readonly ["object", "null"];
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["id", "kind", "status"];
+                                    readonly properties: {
+                                        readonly id: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                        readonly kind: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["enrichment", "message_generation", "source_expansion", "scheduling"];
+                                        };
+                                        readonly status: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["queued", "running"];
+                                        };
+                                    };
+                                };
+                                readonly supply: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                                    readonly properties: {
+                                        readonly readyToSchedule: {
+                                            readonly type: "integer";
+                                            readonly minimum: 0;
+                                        };
+                                        readonly readyForApproval: {
+                                            readonly type: "integer";
+                                            readonly minimum: 0;
+                                        };
+                                        readonly readyForMessageGeneration: {
+                                            readonly type: "integer";
+                                            readonly minimum: 0;
+                                        };
+                                        readonly needsEnrichment: {
+                                            readonly type: "integer";
+                                            readonly minimum: 0;
+                                        };
+                                    };
+                                };
+                                readonly leadSourceFamily: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["post_engager", "signal_discovery", "cold"];
+                                };
+                                readonly evidence: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["evergreen", "lastActualUseAt", "lastScheduledUseAt", "effectiveness", "supplyHealth"];
+                                    readonly properties: {
+                                        readonly evergreen: {
+                                            readonly type: "boolean";
+                                        };
+                                        readonly lastActualUseAt: {
+                                            readonly type: readonly ["string", "null"];
+                                        };
+                                        readonly lastScheduledUseAt: {
+                                            readonly type: readonly ["string", "null"];
+                                        };
+                                        readonly effectiveness: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["unknown", "low", "medium", "high"];
+                                        };
+                                        readonly supplyHealth: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["unknown", "healthy", "thin", "dry"];
+                                        };
+                                        readonly engagement: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: false;
+                                            readonly required: readonly ["sends", "accepted", "replied", "acceptRate", "replyRate"];
+                                            readonly properties: {
+                                                readonly sends: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly accepted: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly replied: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly acceptRate: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                    readonly maximum: 100;
+                                                };
+                                                readonly replyRate: {
+                                                    readonly type: "number";
+                                                    readonly minimum: 0;
+                                                    readonly maximum: 100;
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                    readonly paidCreditEvidence: {
+                        readonly type: readonly ["object", "null"];
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["availableCredits", "minimumRequired", "checkedAt", "fresh"];
+                        readonly properties: {
+                            readonly availableCredits: {
+                                readonly type: readonly ["integer", "null"];
+                                readonly minimum: 0;
+                            };
+                            readonly minimumRequired: {
+                                readonly type: readonly ["integer", "null"];
+                                readonly minimum: 0;
+                            };
+                            readonly checkedAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly fresh: {
+                                readonly type: "boolean";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly durationMs: {
+            readonly type: "number";
+            readonly minimum: 0;
+        };
+        readonly observationSideEffects: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["scheduled", "placed", "sent", "campaignMutated", "approved", "enriched", "generated", "salesNavigatorActioned", "paidCreditCache"];
+            readonly properties: {
+                readonly scheduled: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly placed: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly sent: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly campaignMutated: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly approved: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly enriched: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly generated: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly salesNavigatorActioned: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly paidCreditCache: {
+                    readonly type: "string";
+                    readonly enum: readonly ["not_checked", "not_eligible", "fresh_cache_used", "refresh_started", "refreshed", "refresh_in_progress", "refresh_failed", "uncertain"];
+                };
+            };
+        };
+    };
+}>;
+/**
+ * Sole unknown-value decoder for the public result.
+ *
+ * Strict inbound, tolerant outbound, lossless. `null` means "not this
+ * contract"; the typed unsupported VALUE means "a major this build cannot
+ * speak". Collapsing the second into the first, or into business zero, is the
+ * defect this separation exists to prevent.
+ */
+export declare function decodeRefillWorldStateResult(value: unknown): RefillWorldStateResult | RefillV3SchemaVersionUnsupported | null;
+/**
+ * Wire form of a decoded result. `schemaVersion` is TRANSPORT, not business:
+ * the canonical result stays exactly `{rows, durationMs,
+ * observationSideEffects}`. Every locked field is projected explicitly, because
+ * a silently dropped property is what turns a round trip into a confident wrong
+ * success.
+ */
+export declare function encodeRefillWorldStateResult(result: RefillWorldStateResult): Record<string, unknown>;