@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-world-state-contract.js

@@ -0,0 +1,790 @@
+/**
+ * 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 { REFILL_V3_ACTIVE_JOB_KINDS, REFILL_V3_ACTIVE_JOB_STATUSES, REFILL_V3_LEAD_SOURCE_FAMILIES, REFILL_V3_SCHEMA_VERSION_UNSUPPORTED, REFILL_V3_SUPPLY_BUCKETS, resolveRefillV3SchemaVersion, } from "./refill-v3-attention-packet-contract.js";
+// ───────────────────────────────────────────────────────────────────────────
+// Finite output vocabularies
+// ───────────────────────────────────────────────────────────────────────────
+export const REFILL_V3_WORLD_STATE_SCHEMA_NAMESPACE = "refill_v3_world_state";
+export const REFILL_V3_WORLD_STATE_SCHEMA_MAJOR = 1;
+export 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 const REFILL_V3_WORLD_STATE_LANES = [
+    "connection_invite",
+    "paid_inmail",
+];
+export const REFILL_V3_WORLD_STATE_REASON_KINDS = [
+    "unavailable",
+    "retry_required",
+    "invalid_campaign_configuration",
+];
+/**
+ * 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 const REFILL_V3_WORLD_STATE_COOLDOWN_CODES = [
+    "global_cooldown",
+    "connection_cooldown",
+    "paid_inmail_cooldown",
+];
+export const REFILL_V3_WORLD_STATE_REASON_CODES = [
+    ...REFILL_V3_WORLD_STATE_COOLDOWN_CODES,
+    "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",
+    /**
+     * A brand-new campaign whose lead source is not chosen yet, or whose source
+     * metadata names more than one family. The closed family vocabulary
+     * deliberately gains no `unknown` member, so the campaign is emitted with
+     * accurate facts and this typed reason instead of an invented family that
+     * would make the decoder reject the ENTIRE workspace observation.
+     */
+    "source_family_unresolved",
+    /**
+     * A live queued/running job already owns this campaign's next unit of work.
+     * It is the duplicate-work signal and outranks stale actionable supply.
+     */
+    "campaign_work_in_flight",
+];
+export const REFILL_V3_WORLD_STATE_CAMPAIGN_STATUSES = [
+    "ACTIVE",
+    "PAUSED",
+];
+export const REFILL_V3_WORLD_STATE_EFFECTIVENESS = [
+    "unknown",
+    "low",
+    "medium",
+    "high",
+];
+export const REFILL_V3_WORLD_STATE_SUPPLY_HEALTH = [
+    "unknown",
+    "healthy",
+    "thin",
+    "dry",
+];
+/**
+ * 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 const REFILL_V3_WORLD_STATE_CACHE_OUTCOMES = [
+    "not_checked",
+    "not_eligible",
+    "fresh_cache_used",
+    "refresh_started",
+    "refreshed",
+    "refresh_in_progress",
+    "refresh_failed",
+    "uncertain",
+];
+export const REFILL_V3_WORLD_STATE_PRODUCT_EFFECT_KEYS = [
+    "scheduled",
+    "placed",
+    "sent",
+    "campaignMutated",
+    "approved",
+    "enriched",
+    "generated",
+    "salesNavigatorActioned",
+];
+/**
+ * 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 const REFILL_V3_WORLD_STATE_FORBIDDEN_LEAK_KEYS = [
+    "campaignActionFacts",
+    "leaves",
+    "possibleActions",
+    "boundedRowIds",
+    "rowIds",
+    "rowId",
+    "cellId",
+    "cellIds",
+    "tableId",
+    "actionId",
+    "actionIds",
+    "actionColumnId",
+    "graph",
+    "rank",
+    "ranking",
+    "selectedCampaign",
+    "waterfall",
+    "queryDebug",
+];
+/** Every product mutation boolean, reported explicitly rather than omitted. */
+export const REFILL_V3_WORLD_STATE_ZERO_PRODUCT_EFFECTS = Object.freeze({
+    scheduled: false,
+    placed: false,
+    sent: false,
+    campaignMutated: false,
+    approved: false,
+    enriched: false,
+    generated: false,
+    salesNavigatorActioned: false,
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Public output schema
+// ───────────────────────────────────────────────────────────────────────────
+const REASON_SCHEMA = {
+    type: ["object", "null"],
+    additionalProperties: false,
+    required: ["kind", "codes", "message"],
+    properties: {
+        kind: { type: "string", enum: [...REFILL_V3_WORLD_STATE_REASON_KINDS] },
+        codes: {
+            type: "array",
+            items: { type: "string", enum: [...REFILL_V3_WORLD_STATE_REASON_CODES] },
+        },
+        message: { type: "string" },
+        resumeAt: { type: "string" },
+    },
+};
+const CAMPAIGN_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+        "id",
+        "name",
+        "status",
+        "lanes",
+        "eligible",
+        "reason",
+        "startEligible",
+        "activeJob",
+        "supply",
+        "leadSourceFamily",
+        "evidence",
+    ],
+    properties: {
+        id: { type: "string", minLength: 1 },
+        name: { type: "string" },
+        status: {
+            type: "string",
+            enum: [...REFILL_V3_WORLD_STATE_CAMPAIGN_STATUSES],
+        },
+        lanes: {
+            type: "array",
+            minItems: 1,
+            items: { type: "string", enum: [...REFILL_V3_WORLD_STATE_LANES] },
+        },
+        eligible: { type: "boolean" },
+        reason: REASON_SCHEMA,
+        startEligible: { type: "boolean" },
+        activeJob: {
+            type: ["object", "null"],
+            additionalProperties: false,
+            required: ["id", "kind", "status"],
+            properties: {
+                id: { type: "string", minLength: 1 },
+                kind: { type: "string", enum: [...REFILL_V3_ACTIVE_JOB_KINDS] },
+                status: { type: "string", enum: [...REFILL_V3_ACTIVE_JOB_STATUSES] },
+            },
+        },
+        supply: {
+            type: "object",
+            additionalProperties: false,
+            required: [...REFILL_V3_SUPPLY_BUCKETS],
+            properties: {
+                readyToSchedule: { type: "integer", minimum: 0 },
+                readyForApproval: { type: "integer", minimum: 0 },
+                readyForMessageGeneration: { type: "integer", minimum: 0 },
+                needsEnrichment: { type: "integer", minimum: 0 },
+            },
+        },
+        leadSourceFamily: {
+            type: "string",
+            enum: [...REFILL_V3_LEAD_SOURCE_FAMILIES],
+        },
+        evidence: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "evergreen",
+                "lastActualUseAt",
+                "lastScheduledUseAt",
+                "effectiveness",
+                "supplyHealth",
+            ],
+            properties: {
+                evergreen: { type: "boolean" },
+                lastActualUseAt: { type: ["string", "null"] },
+                lastScheduledUseAt: { type: ["string", "null"] },
+                effectiveness: {
+                    type: "string",
+                    enum: [...REFILL_V3_WORLD_STATE_EFFECTIVENESS],
+                },
+                supplyHealth: {
+                    type: "string",
+                    enum: [...REFILL_V3_WORLD_STATE_SUPPLY_HEALTH],
+                },
+                // ADDITIVE OPTIONAL (146.5-12 §87): the real numbers behind the
+                // effectiveness band; deliberately NOT in `required` so older
+                // backends stay schema-valid.
+                engagement: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["sends", "accepted", "replied", "acceptRate", "replyRate"],
+                    properties: {
+                        sends: { type: "number", minimum: 0 },
+                        accepted: { type: "number", minimum: 0 },
+                        replied: { type: "number", minimum: 0 },
+                        acceptRate: { type: "number", minimum: 0, maximum: 100 },
+                        replyRate: { type: "number", minimum: 0, maximum: 100 },
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * 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 const REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["rows", "durationMs", "observationSideEffects"],
+    properties: {
+        rows: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "date",
+                    "sender",
+                    "lane",
+                    "targetSlots",
+                    "takenSlots",
+                    "availableSlots",
+                    "reason",
+                    "activeCampaigns",
+                    "inactiveCampaigns",
+                ],
+                properties: {
+                    date: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+                    sender: {
+                        type: "object",
+                        additionalProperties: false,
+                        required: ["id", "name", "timezone"],
+                        properties: {
+                            id: { type: "string", minLength: 1 },
+                            name: { type: "string" },
+                            timezone: { type: "string", minLength: 1 },
+                        },
+                    },
+                    lane: { type: "string", enum: [...REFILL_V3_WORLD_STATE_LANES] },
+                    targetSlots: { type: "integer", minimum: 0 },
+                    takenSlots: { type: "integer", minimum: 0 },
+                    availableSlots: { type: "integer", minimum: 0 },
+                    reason: REASON_SCHEMA,
+                    activeCampaigns: { type: "array", items: CAMPAIGN_SCHEMA },
+                    inactiveCampaigns: { type: "array", items: CAMPAIGN_SCHEMA },
+                    // Additive optional (146.5-12 §84b): paid rows carry their credit
+                    // numbers so a 0-slot paid lane explains itself.
+                    paidCreditEvidence: {
+                        type: ["object", "null"],
+                        additionalProperties: false,
+                        required: [
+                            "availableCredits",
+                            "minimumRequired",
+                            "checkedAt",
+                            "fresh",
+                        ],
+                        properties: {
+                            availableCredits: { type: ["integer", "null"], minimum: 0 },
+                            minimumRequired: { type: ["integer", "null"], minimum: 0 },
+                            checkedAt: { type: ["string", "null"] },
+                            fresh: { type: "boolean" },
+                        },
+                    },
+                },
+            },
+        },
+        durationMs: { type: "number", minimum: 0 },
+        observationSideEffects: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                ...REFILL_V3_WORLD_STATE_PRODUCT_EFFECT_KEYS,
+                "paidCreditCache",
+            ],
+            properties: {
+                scheduled: { type: "boolean", enum: [false] },
+                placed: { type: "boolean", enum: [false] },
+                sent: { type: "boolean", enum: [false] },
+                campaignMutated: { type: "boolean", enum: [false] },
+                approved: { type: "boolean", enum: [false] },
+                enriched: { type: "boolean", enum: [false] },
+                generated: { type: "boolean", enum: [false] },
+                salesNavigatorActioned: { type: "boolean", enum: [false] },
+                paidCreditCache: {
+                    type: "string",
+                    enum: [...REFILL_V3_WORLD_STATE_CACHE_OUTCOMES],
+                },
+            },
+        },
+    },
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Decoder
+// ───────────────────────────────────────────────────────────────────────────
+// ───────────────────────────────────────────────────────────────────────────
+// Decoder
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * A policy leak found ANYWHERE rejects the whole result, while an unrecognized
+ * enum value only drops the unit that carries it. The two outcomes therefore
+ * cannot share `null`.
+ */
+const LEAK = Symbol("refill_v3_world_state_policy_leak");
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isWholeNumber(value) {
+    return Number.isInteger(value) && value >= 0;
+}
+function isOneOf(value, options) {
+    return (typeof value === "string" && options.includes(value));
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function isRoundTripDate(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return false;
+    }
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    return (!Number.isNaN(parsed.getTime()) &&
+        parsed.toISOString().slice(0, 10) === value);
+}
+function leaksPolicyKey(record) {
+    return REFILL_V3_WORLD_STATE_FORBIDDEN_LEAK_KEYS.some((key) => key in record);
+}
+function decodeReason(value) {
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        return null;
+    if (leaksPolicyKey(value))
+        return LEAK;
+    if (!isOneOf(value.kind, REFILL_V3_WORLD_STATE_REASON_KINDS) ||
+        !Array.isArray(value.codes) ||
+        !value.codes.every((code) => isOneOf(code, REFILL_V3_WORLD_STATE_REASON_CODES)) ||
+        typeof value.message !== "string" ||
+        !(value.resumeAt === undefined || typeof value.resumeAt === "string")) {
+        return null;
+    }
+    const reason = {
+        kind: value.kind,
+        codes: [...value.codes],
+        message: value.message,
+    };
+    if (value.resumeAt !== undefined)
+        reason.resumeAt = value.resumeAt;
+    return reason;
+}
+function decodeActiveJob(value) {
+    if (value === null)
+        return { ok: true, value: null };
+    if (!isRecord(value))
+        return { ok: false };
+    if (leaksPolicyKey(value))
+        return LEAK;
+    if (!isNonEmptyString(value.id) ||
+        !isOneOf(value.kind, REFILL_V3_ACTIVE_JOB_KINDS) ||
+        !isOneOf(value.status, REFILL_V3_ACTIVE_JOB_STATUSES)) {
+        return { ok: false };
+    }
+    return {
+        ok: true,
+        value: { id: value.id, kind: value.kind, status: value.status },
+    };
+}
+function decodeSupply(value) {
+    if (!isRecord(value))
+        return null;
+    if (leaksPolicyKey(value))
+        return LEAK;
+    for (const bucket of REFILL_V3_SUPPLY_BUCKETS) {
+        if (!isWholeNumber(value[bucket]))
+            return null;
+    }
+    return {
+        readyToSchedule: value.readyToSchedule,
+        readyForApproval: value.readyForApproval,
+        readyForMessageGeneration: value.readyForMessageGeneration,
+        needsEnrichment: value.needsEnrichment,
+    };
+}
+function decodeCampaignEvidence(value) {
+    if (!isRecord(value))
+        return null;
+    if (leaksPolicyKey(value))
+        return LEAK;
+    if (typeof value.evergreen !== "boolean" ||
+        !isNullableString(value.lastActualUseAt) ||
+        !isNullableString(value.lastScheduledUseAt) ||
+        !isOneOf(value.effectiveness, REFILL_V3_WORLD_STATE_EFFECTIVENESS) ||
+        !isOneOf(value.supplyHealth, REFILL_V3_WORLD_STATE_SUPPLY_HEALTH)) {
+        return null;
+    }
+    // ADDITIVE decode (146.5-12 §87): absent stays absent (older backend);
+    // a PRESENT engagement must decode strictly or the campaign drops —
+    // numbers are evidence, and malformed evidence is never half-kept.
+    let engagement;
+    if (value.engagement !== undefined && value.engagement !== null) {
+        const decoded = decodeCampaignEngagement(value.engagement);
+        if (decoded === null)
+            return null;
+        engagement = decoded;
+    }
+    return {
+        evergreen: value.evergreen,
+        lastActualUseAt: value.lastActualUseAt,
+        lastScheduledUseAt: value.lastScheduledUseAt,
+        effectiveness: value.effectiveness,
+        supplyHealth: value.supplyHealth,
+        ...(engagement ? { engagement } : {}),
+    };
+}
+function decodeCampaignEngagement(value) {
+    if (!isRecord(value))
+        return null;
+    const isCount = (entry) => typeof entry === "number" && Number.isFinite(entry) && entry >= 0;
+    if (!isCount(value.sends) ||
+        !isCount(value.accepted) ||
+        !isCount(value.replied) ||
+        !isCount(value.acceptRate) ||
+        !isCount(value.replyRate) ||
+        value.acceptRate > 100 ||
+        value.replyRate > 100) {
+        return null;
+    }
+    return {
+        sends: value.sends,
+        accepted: value.accepted,
+        replied: value.replied,
+        acceptRate: value.acceptRate,
+        replyRate: value.replyRate,
+    };
+}
+/** `null` drops only this campaign entry; `LEAK` rejects the whole result. */
+function decodeCampaign(value) {
+    if (!isRecord(value))
+        return null;
+    if (leaksPolicyKey(value))
+        return LEAK;
+    if (!isNonEmptyString(value.id) ||
+        typeof value.name !== "string" ||
+        !isOneOf(value.status, REFILL_V3_WORLD_STATE_CAMPAIGN_STATUSES) ||
+        !Array.isArray(value.lanes) ||
+        value.lanes.length === 0 ||
+        !value.lanes.every((lane) => isOneOf(lane, REFILL_V3_WORLD_STATE_LANES)) ||
+        typeof value.eligible !== "boolean" ||
+        typeof value.startEligible !== "boolean" ||
+        !isOneOf(value.leadSourceFamily, REFILL_V3_LEAD_SOURCE_FAMILIES)) {
+        return null;
+    }
+    const reason = decodeReason(value.reason);
+    if (reason === LEAK)
+        return LEAK;
+    if (value.reason !== null && reason === null)
+        return null;
+    const activeJob = decodeActiveJob(value.activeJob);
+    if (activeJob === LEAK)
+        return LEAK;
+    if (!activeJob.ok)
+        return null;
+    const supply = decodeSupply(value.supply);
+    if (supply === LEAK)
+        return LEAK;
+    if (supply === null)
+        return null;
+    const evidence = decodeCampaignEvidence(value.evidence);
+    if (evidence === LEAK)
+        return LEAK;
+    if (evidence === null)
+        return null;
+    return {
+        id: value.id,
+        name: value.name,
+        status: value.status,
+        lanes: [...value.lanes],
+        eligible: value.eligible,
+        reason,
+        startEligible: value.startEligible,
+        activeJob: activeJob.value,
+        supply,
+        leadSourceFamily: value.leadSourceFamily,
+        evidence,
+    };
+}
+function decodeCampaignList(value) {
+    if (!Array.isArray(value))
+        return null;
+    const options = [];
+    for (const entry of value) {
+        const option = decodeCampaign(entry);
+        if (option === LEAK)
+            return LEAK;
+        if (option === null)
+            continue;
+        options.push(option);
+    }
+    return options;
+}
+function decodeSender(value) {
+    if (!isRecord(value))
+        return null;
+    if (leaksPolicyKey(value))
+        return LEAK;
+    if (!isNonEmptyString(value.id) ||
+        typeof value.name !== "string" ||
+        !isNonEmptyString(value.timezone)) {
+        return null;
+    }
+    return { id: value.id, name: value.name, timezone: value.timezone };
+}
+/** `null` drops only this row; `LEAK` rejects the whole result. */
+function decodeRow(value) {
+    if (!isRecord(value))
+        return null;
+    if (leaksPolicyKey(value))
+        return LEAK;
+    if (!isRoundTripDate(value.date) ||
+        !isOneOf(value.lane, REFILL_V3_WORLD_STATE_LANES) ||
+        !isWholeNumber(value.targetSlots) ||
+        !isWholeNumber(value.takenSlots) ||
+        !isWholeNumber(value.availableSlots)) {
+        return null;
+    }
+    const remaining = Math.max(value.targetSlots - value.takenSlots, 0);
+    if (value.availableSlots > remaining)
+        return null;
+    const sender = decodeSender(value.sender);
+    if (sender === LEAK)
+        return LEAK;
+    if (sender === null)
+        return null;
+    const reason = decodeReason(value.reason);
+    if (reason === LEAK)
+        return LEAK;
+    if (value.reason !== null && reason === null)
+        return null;
+    const activeCampaigns = decodeCampaignList(value.activeCampaigns);
+    if (activeCampaigns === LEAK)
+        return LEAK;
+    if (activeCampaigns === null)
+        return null;
+    const inactiveCampaigns = decodeCampaignList(value.inactiveCampaigns);
+    if (inactiveCampaigns === LEAK)
+        return LEAK;
+    if (inactiveCampaigns === null)
+        return null;
+    const paidCreditEvidence = decodePaidCreditEvidence(value.paidCreditEvidence);
+    if (paidCreditEvidence === INVALID_CREDIT_EVIDENCE)
+        return null;
+    return {
+        date: value.date,
+        sender,
+        lane: value.lane,
+        targetSlots: value.targetSlots,
+        takenSlots: value.takenSlots,
+        availableSlots: value.availableSlots,
+        reason,
+        activeCampaigns,
+        inactiveCampaigns,
+        ...(paidCreditEvidence === undefined ? {} : { paidCreditEvidence }),
+    };
+}
+const INVALID_CREDIT_EVIDENCE = Symbol("invalid-credit-evidence");
+/**
+ * Additive optional decode (146.5-12 §84b): absent stays absent (older
+ * backends), null stays null, a well-formed object round-trips, and a
+ * malformed one drops the row rather than fabricating numbers.
+ */
+function decodePaidCreditEvidence(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        return INVALID_CREDIT_EVIDENCE;
+    const availableOk = value.availableCredits === null || isWholeNumber(value.availableCredits);
+    const minimumOk = value.minimumRequired === null || isWholeNumber(value.minimumRequired);
+    const checkedOk = value.checkedAt === null || typeof value.checkedAt === "string";
+    if (!availableOk || !minimumOk || !checkedOk) {
+        return INVALID_CREDIT_EVIDENCE;
+    }
+    if (typeof value.fresh !== "boolean")
+        return INVALID_CREDIT_EVIDENCE;
+    return {
+        availableCredits: value.availableCredits,
+        minimumRequired: value.minimumRequired,
+        checkedAt: value.checkedAt,
+        fresh: value.fresh,
+    };
+}
+function decodeSideEffects(value) {
+    if (!isRecord(value))
+        return null;
+    if (leaksPolicyKey(value))
+        return LEAK;
+    for (const key of REFILL_V3_WORLD_STATE_PRODUCT_EFFECT_KEYS) {
+        if (value[key] !== false)
+            return null;
+    }
+    if (typeof value.paidCreditCache !== "string")
+        return null;
+    return {
+        ...REFILL_V3_WORLD_STATE_ZERO_PRODUCT_EFFECTS,
+        // An unrecognized outcome is not a reason to fail an installed client
+        // closed. `uncertain` is the vocabulary's own "we do not know" member, so
+        // the honest projection preserves every row instead of blanking them.
+        paidCreditCache: isOneOf(value.paidCreditCache, REFILL_V3_WORLD_STATE_CACHE_OUTCOMES)
+            ? value.paidCreditCache
+            : "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 function decodeRefillWorldStateResult(value) {
+    if (!isRecord(value))
+        return null;
+    const support = resolveRefillV3SchemaVersion(value.schemaVersion, REFILL_V3_WORLD_STATE_SCHEMA_NAMESPACE, REFILL_V3_WORLD_STATE_SCHEMA_MAJOR);
+    if (!support.supported) {
+        return support.reason === REFILL_V3_SCHEMA_VERSION_UNSUPPORTED
+            ? REFILL_V3_SCHEMA_VERSION_UNSUPPORTED
+            : null;
+    }
+    if (leaksPolicyKey(value))
+        return null;
+    if (!Array.isArray(value.rows))
+        return null;
+    if (typeof value.durationMs !== "number" ||
+        !Number.isFinite(value.durationMs) ||
+        value.durationMs < 0) {
+        return null;
+    }
+    const observationSideEffects = decodeSideEffects(value.observationSideEffects);
+    if (observationSideEffects === LEAK || observationSideEffects === null) {
+        return null;
+    }
+    const rows = [];
+    for (const entry of value.rows) {
+        const row = decodeRow(entry);
+        if (row === LEAK)
+            return null;
+        if (row === null)
+            continue;
+        rows.push(row);
+    }
+    return { rows, durationMs: value.durationMs, observationSideEffects };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Encoder
+// ───────────────────────────────────────────────────────────────────────────
+function encodeReason(reason) {
+    if (reason === null)
+        return null;
+    const encoded = {
+        kind: reason.kind,
+        codes: [...reason.codes],
+        message: reason.message,
+    };
+    if (reason.resumeAt !== undefined)
+        encoded.resumeAt = reason.resumeAt;
+    return encoded;
+}
+function encodeCampaign(option) {
+    return {
+        id: option.id,
+        name: option.name,
+        status: option.status,
+        lanes: [...option.lanes],
+        eligible: option.eligible,
+        reason: encodeReason(option.reason),
+        startEligible: option.startEligible,
+        activeJob: option.activeJob,
+        supply: { ...option.supply },
+        leadSourceFamily: option.leadSourceFamily,
+        evidence: { ...option.evidence },
+    };
+}
+/**
+ * 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 function encodeRefillWorldStateResult(result) {
+    return {
+        schemaVersion: REFILL_V3_WORLD_STATE_SCHEMA_VERSION,
+        rows: result.rows.map((row) => ({
+            date: row.date,
+            sender: { ...row.sender },
+            lane: row.lane,
+            targetSlots: row.targetSlots,
+            takenSlots: row.takenSlots,
+            availableSlots: row.availableSlots,
+            reason: encodeReason(row.reason),
+            activeCampaigns: row.activeCampaigns.map(encodeCampaign),
+            inactiveCampaigns: row.inactiveCampaigns.map(encodeCampaign),
+        })),
+        durationMs: result.durationMs,
+        observationSideEffects: { ...result.observationSideEffects },
+    };
+}