@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-source-family-dispatch.js

@@ -0,0 +1,514 @@
+/**
+ * Refill V3 table-driven SOURCE-FAMILY DISPATCHER (Phase 146.5 Plan 09 T3/T4/T5,
+ * RV3PRM-002/003/004).
+ *
+ * EXECUTION PLUMBING ONLY. The AI seam decides WHY to broaden, which family,
+ * which contextual query, and which minimal filter/keyword/post delta. This
+ * module validates that already-bounded command and maps it, through a CONSTANT
+ * table, to exactly one existing owner. It contains no family inference, no
+ * query invention, no ranking, no yield projection, no provider retry, no import
+ * policy, and no fallback between families.
+ *
+ * It lives INSIDE the package beside its owners (`A09-DISPATCHER-IN-PACKAGE`):
+ * every named family owner is declared in `refill-executors.ts`, which reaches
+ * the backend over HTTP, so an app-side dispatcher would create an
+ * app -> MCP-api-client -> app-route loop and needs a route that was never
+ * defined.
+ *
+ * The searched-negative set is DERIVED from existing source-run/import lineage
+ * plus effect fingerprints (`A09-NEGATIVE-SET-OWNER`). There is no new database
+ * model, no attempt counter, and no durable ledger. Every entry is append-only,
+ * fingerprint-identified, and carries an explicit typed RELEASE CONDITION, so a
+ * bounded attempt can never harden into a standing claim.
+ */
+import { evaluateRefillV3SourceYield, REFILL_V3_EXHAUSTION_PREDICATE, REFILL_V3_LEAD_SOURCE_FAMILIES, REFILL_V3_MIN_SOURCE_YIELD, REFILL_V3_MIN_SOURCE_YIELD_SAMPLE, } from "./refill-v3-attention-packet-contract.js";
+import { REFILL_V3_POSTS_KEYWORD_BATCH_SIZE, REFILL_V3_POSTS_MAX_SELECTED, REFILL_V3_POSTS_ROUND_BUDGET, } from "./refill-v3-campaign-work.js";
+// ───────────────────────────────────────────────────────────────────────────
+// The constant owner table
+// ───────────────────────────────────────────────────────────────────────────
+export const REFILL_V3_SOURCE_OWNER_KEYS = [
+    "refreshSenderPostEngagers",
+    "continueSignalDiscoverySource",
+    "broadenSignalSearch",
+    "continueProviderSource",
+    "broadenProviderSearch",
+];
+/**
+ * The CONSTANT family table. The public token `cold` maps INTERNALLY to the
+ * provider owners; no boundary rewrites it to another public token.
+ */
+export const REFILL_V3_SOURCE_FAMILY_TABLE = Object.freeze({
+    post_engager: {
+        continuation: "refreshSenderPostEngagers",
+        broadening: "refreshSenderPostEngagers",
+    },
+    signal_discovery: {
+        continuation: "continueSignalDiscoverySource",
+        broadening: "broadenSignalSearch",
+    },
+    cold: {
+        continuation: "continueProviderSource",
+        broadening: "broadenProviderSearch",
+    },
+});
+export const REFILL_V3_SOURCE_DISPATCH_REFUSALS = [
+    "missing_scope",
+    "foreign_scope",
+    "unsupported_family",
+    "unsupported_action",
+    "malformed_command",
+    "stale_prior_fingerprint",
+    "missing_count",
+    "health_evidence_not_source_work",
+    "live_source_job",
+    "negative_set_replay",
+    "incidental_change_only",
+    "negative_set_provenance_unavailable",
+    "family_switch_prompt_missing",
+    "family_switch_negative_set",
+    "post_engager_refresh_required",
+    "exhaustion_falsified",
+    "keyword_batch_size",
+    "post_cap_exceeded",
+    "post_rationale_missing",
+    "posts_round_budget_spent",
+    "receipt_incomplete",
+];
+/**
+ * Provider INFRASTRUCTURE failure is never exhaustion. Each class is RETRYABLE,
+ * leaves the campaign NON-exhausted, and — critically — never enters the
+ * searched-negative set, because nothing was actually searched (repairs C18).
+ */
+export const REFILL_V3_SOURCE_FAILURE_CLASSES = [
+    "owner_threw",
+    "timeout",
+    "provider_5xx",
+    "rate_limit",
+];
+/**
+ * The ONE enumerated release-condition vocabulary shared by the negative-set
+ * WRITER and READER. Every entry must name a condition that is actually checked
+ * on every evidence change, or the set grows monotonically until every plausible
+ * query is refused and the campaign becomes permanently un-broadenable while
+ * exhaustion may still be falsified (`A09-NEGATIVE-SET-LIFECYCLE`).
+ */
+export const REFILL_V3_NEGATIVE_SET_RELEASE_CONDITIONS = [
+    "campaign_icp_changed",
+    "provider_inventory_refreshed",
+    "evidence_window_rolled",
+    "posts_refreshed_in_window",
+];
+export const REFILL_V3_NEGATIVE_SET_PROVENANCE_UNAVAILABLE = "negative_set_provenance_unavailable";
+// ───────────────────────────────────────────────────────────────────────────
+// Command, owners, receipts
+// ───────────────────────────────────────────────────────────────────────────
+export const REFILL_V3_SOURCE_DISPATCH_ACTIONS = [
+    "continue",
+    "broaden",
+    "record_exhaustion",
+];
+// ───────────────────────────────────────────────────────────────────────────
+// Canonical semantic identity
+// ───────────────────────────────────────────────────────────────────────────
+function canonicalScalar(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (Array.isArray(value)) {
+        // A reordered but equivalent list is the SAME search: order is incidental.
+        return [...value.map((entry) => canonicalScalar(entry))].sort().join(",");
+    }
+    if (typeof value === "object") {
+        return Object.keys(value)
+            .sort()
+            .map((key) => `${key}=${canonicalScalar(value[key])}`)
+            .join(";");
+    }
+    return String(value).trim().replace(/\s+/g, " ").toLowerCase();
+}
+/**
+ * The SEMANTIC identity of a source command.
+ *
+ * A timestamp, a counter, a reordered-but-equivalent filter list, and a
+ * whitespace edit are INCIDENTAL: they must not buy a second identical search.
+ * The caller's `requestFingerprint` is deliberately excluded — it is a transport
+ * identity, and including it would let a cosmetic edit re-run the same query.
+ */
+export function canonicalRefillV3SourceFingerprint(command) {
+    return [
+        command.family,
+        command.mode,
+        canonicalScalar(command.provider),
+        `q:${canonicalScalar(command.query)}`,
+        `f:${canonicalScalar(command.filterDelta)}`,
+        `k:${canonicalScalar(command.keywordBatch)}`,
+        `p:${canonicalScalar(command.selectedPostIds)}`,
+    ].join("|");
+}
+/**
+ * Which typed condition RELEASES an entry. Every value is checked on an evidence
+ * change, so the set cannot grow monotonically until the campaign is permanently
+ * un-broadenable.
+ */
+function releaseConditionFor(record) {
+    if (record.family === "post_engager")
+        return "posts_refreshed_in_window";
+    if (record.keywordBatch !== null || record.postIds !== null) {
+        return "evidence_window_rolled";
+    }
+    return record.provider === null
+        ? "campaign_icp_changed"
+        : "provider_inventory_refreshed";
+}
+/**
+ * Derive the searched-negative set from durable lineage ALONE.
+ *
+ * Because it is a pure function of canonical lineage, a cold restart and a new
+ * day reconstruct identical verdicts and process memory is never load-bearing.
+ * `null` lineage is NOT an empty set: silent shrinkage re-admits previously
+ * refused searches, so it yields the typed provenance marker instead.
+ */
+export function deriveRefillV3SearchedNegativeSet(lineage, options) {
+    if (lineage === null || lineage === undefined) {
+        return {
+            provenance: REFILL_V3_NEGATIVE_SET_PROVENANCE_UNAVAILABLE,
+            entries: [],
+            postsRoundsByCampaign: {},
+            dryFamilies: [],
+        };
+    }
+    const scoped = options?.campaignId
+        ? lineage.filter((record) => record.campaignId === options.campaignId)
+        : lineage;
+    const entries = [];
+    const postsRoundsByCampaign = {};
+    const dryFamilies = [];
+    const productive = new Set();
+    for (const record of scoped) {
+        // Only a COMPLETED search with an observed yield may register.
+        if (!record.searchCompleted)
+            continue;
+        entries.push({
+            campaignId: record.campaignId,
+            family: record.family,
+            sourceFingerprint: record.sourceFingerprint,
+            semanticFingerprint: record.semanticFingerprint,
+            keywordBatch: record.keywordBatch,
+            postIds: record.postIds,
+            releaseCondition: releaseConditionFor(record),
+            observedAt: record.observedAt,
+        });
+        if (record.keywordBatch !== null) {
+            postsRoundsByCampaign[record.campaignId] =
+                (postsRoundsByCampaign[record.campaignId] ?? 0) + 1;
+        }
+        const familyKey = `${record.family}:${record.campaignId}`;
+        if (record.importedCount > 0) {
+            productive.add(familyKey);
+        }
+        else if (!dryFamilies.includes(familyKey)) {
+            dryFamilies.push(familyKey);
+        }
+    }
+    return {
+        provenance: "derived",
+        entries,
+        postsRoundsByCampaign,
+        // Dry is keyed per `(family, campaignId)`: one exhausted family may never
+        // suppress another (repairs C17 and error law 9).
+        dryFamilies: dryFamilies.filter((key) => !productive.has(key)),
+    };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Dispatch
+// ───────────────────────────────────────────────────────────────────────────
+function refused(refusal, detail, extra = {}) {
+    return {
+        kind: "refused",
+        refusal,
+        detail,
+        matchingFingerprint: extra.matchingFingerprint ?? null,
+        releaseCondition: extra.releaseCondition ?? null,
+        exhausted: false,
+        reobserveRequired: extra.reobserveRequired ?? true,
+    };
+}
+function isNonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isPlainRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Validate ONE already-bounded AI command and map it through the constant table
+ * to exactly one existing owner.
+ *
+ * Every refusal happens BEFORE the single owner call, so a refused command costs
+ * zero external work. Nothing here chooses a family, a query, a filter, a post,
+ * a provider, or a retry.
+ */
+export async function dispatchRefillV3SourceFamily(input) {
+    const { scope, command, action } = input;
+    // 1. Connection health belongs to Plan 10. It is never source work.
+    if ((input.healthEvidence ?? []).length > 0) {
+        return refused("health_evidence_not_source_work", `Connection-health evidence (${(input.healthEvidence ?? []).join(", ")}) can never be answered with a source search.`);
+    }
+    // 2. Exact scope.
+    for (const key of [
+        "workspaceId",
+        "campaignId",
+        "tableId",
+        "senderId",
+        "date",
+        "evidenceFingerprint",
+        "priorSourceFingerprint",
+        "idempotencyKey",
+    ]) {
+        if (!isNonEmpty(scope[key])) {
+            return refused("missing_scope", `Source dispatch requires an exact ${key}.`);
+        }
+    }
+    if (!Number.isInteger(scope.count) || scope.count < 0) {
+        return refused("missing_count", `Source dispatch requires a whole non-negative count; got ${scope.count}.`);
+    }
+    if (action !== "record_exhaustion" &&
+        command.family !== "post_engager" &&
+        !isNonEmpty(scope.sourceLeadListId)) {
+        return refused("missing_scope", `Source dispatch for ${command.family} requires the campaign's exact selected source lead-list id.`);
+    }
+    // 3. Closed vocabularies.
+    if (!isRefillV3LeadSourceFamily(command.family)) {
+        return refused("unsupported_family", `${String(command.family)} is outside the closed family table.`);
+    }
+    if (!REFILL_V3_SOURCE_DISPATCH_ACTIONS.includes(action)) {
+        return refused("unsupported_action", `${String(action)} is outside the closed dispatch action set.`);
+    }
+    // 4. Bounded command shape. The dispatcher validates values; it never invents
+    //    or rewrites them.
+    if (!isNonEmpty(command.requestFingerprint)) {
+        return refused("malformed_command", "The command needs a requestFingerprint.");
+    }
+    if (command.query !== null && !isNonEmpty(command.query)) {
+        return refused("malformed_command", "An empty query is not a query.");
+    }
+    if (command.filterDelta !== null && !isPlainRecord(command.filterDelta)) {
+        return refused("malformed_command", "filterDelta must be an object or null.");
+    }
+    // 5. A live source expansion holds the campaign. A terminal history does not.
+    if (input.activeJob !== null && input.activeJob.kind === "source_expansion") {
+        return refused("live_source_job", `A ${input.activeJob.status} source expansion (${input.activeJob.id}) already holds this campaign; wait and re-observe rather than queueing a second one.`);
+    }
+    // 6. The derived negative set. Absent lineage BLOCKS a confident
+    //    "nothing has been searched" claim rather than reading as an empty set.
+    const negativeSet = deriveRefillV3SearchedNegativeSet(input.lineage, {
+        campaignId: scope.campaignId,
+    });
+    if (negativeSet.provenance === REFILL_V3_NEGATIVE_SET_PROVENANCE_UNAVAILABLE) {
+        return refused("negative_set_provenance_unavailable", "Source-run lineage is absent or pruned, so no prior-search claim can be trusted. Restore provenance before broadening or recording exhaustion.");
+    }
+    // 7. Optimistic concurrency against canonical lineage.
+    const latestForCampaign = negativeSet.entries[negativeSet.entries.length - 1];
+    if (latestForCampaign &&
+        latestForCampaign.sourceFingerprint !== scope.priorSourceFingerprint) {
+        return refused("stale_prior_fingerprint", `Canonical lineage is at ${latestForCampaign.sourceFingerprint}; the command carried ${scope.priorSourceFingerprint}.`);
+    }
+    const semantic = canonicalRefillV3SourceFingerprint(command);
+    const switching = command.family !== input.observedFamily;
+    const sameFamilyEntries = negativeSet.entries.filter((entry) => entry.family === command.family);
+    const semanticMatch = sameFamilyEntries.find((entry) => entry.semanticFingerprint === semantic);
+    // 8. A family switch needs BOTH the matching loaded guidance and a fingerprint
+    //    absent from THAT family's negative set.
+    if (switching) {
+        if (command.mode === "new_provider_search" &&
+            !isNonEmpty(input.providerPromptPackage ?? null)) {
+            return refused("family_switch_prompt_missing", `Switching from ${input.observedFamily} to ${command.family} requires the newly selected family's active provider guidance to be loaded first.`);
+        }
+        if (semanticMatch) {
+            return refused("family_switch_negative_set", `The proposed ${command.family} search is already in that family's negative set.`, {
+                matchingFingerprint: semanticMatch.sourceFingerprint,
+                releaseCondition: semanticMatch.releaseCondition,
+            });
+        }
+    }
+    // 9. Replay versus incidental change. An exact prior fingerprint is a replay; a
+    //    cosmetic edit of the same semantic query is not a material difference.
+    if (semanticMatch && !switching) {
+        const exact = semanticMatch.sourceFingerprint === command.requestFingerprint;
+        return refused(exact ? "negative_set_replay" : "incidental_change_only", exact
+            ? `Request fingerprint ${command.requestFingerprint} was already searched for this campaign.`
+            : `The proposed command differs only incidentally from the already-searched ${semanticMatch.sourceFingerprint}; incidental change is not material change.`, {
+            matchingFingerprint: semanticMatch.sourceFingerprint,
+            releaseCondition: semanticMatch.releaseCondition,
+        });
+    }
+    // 10. Posts-search sub-mechanics. The AI supplies the keywords and the picks;
+    //     the batch size, the post cap, the per-post rationale, and the round
+    //     budget are deterministic.
+    if (command.keywordBatch !== null) {
+        if (command.keywordBatch.length !== REFILL_V3_POSTS_KEYWORD_BATCH_SIZE) {
+            return refused("keyword_batch_size", `A posts-search round carries exactly ${REFILL_V3_POSTS_KEYWORD_BATCH_SIZE} keywords; ${command.keywordBatch.length} were supplied.`);
+        }
+        const roundsSpent = negativeSet.postsRoundsByCampaign[scope.campaignId] ?? 0;
+        if (roundsSpent >= REFILL_V3_POSTS_ROUND_BUDGET) {
+            return refused("posts_round_budget_spent", `The posts-search avenue is SPENT for this evidence window after ${roundsSpent} rounds. Other broadening classes and families may still apply.`);
+        }
+    }
+    if (command.selectedPostIds !== null) {
+        if (command.selectedPostIds.length > REFILL_V3_POSTS_MAX_SELECTED) {
+            return refused("post_cap_exceeded", `At most ${REFILL_V3_POSTS_MAX_SELECTED} candidate posts per round; ${command.selectedPostIds.length} were selected.`);
+        }
+        const explained = new Set((command.postRationales ?? []).map((entry) => entry.postId));
+        const unexplained = command.selectedPostIds.filter((postId) => !explained.has(postId));
+        if (unexplained.length > 0) {
+            return refused("post_rationale_missing", `Selected posts with no recorded expected-yield basis: ${unexplained.join(", ")}. A pick with no rationale is not auditable.`);
+        }
+    }
+    // 11. Exhaustion. Per-family PRECONDITIONS first, then the shared predicate.
+    if (action === "record_exhaustion") {
+        if (command.family === "post_engager" &&
+            input.postsRefreshedInWindow !== true) {
+            return refused("post_engager_refresh_required", "post_engager cannot be declared dry until the sender's authored-posts refresh has run inside the current evidence window.");
+        }
+        if (!input.exhaustionEvidence) {
+            return refused("exhaustion_falsified", "An exhaustion claim must carry the bounded evidence it was formed from.");
+        }
+        const verdict = falsifyRefillV3SourceExhaustion(input.exhaustionEvidence);
+        if (!verdict.exhausted) {
+            return refused("exhaustion_falsified", `Live evidence contradicts the claim: ${verdict.falsifyingClause}. The flow continues.`);
+        }
+        return {
+            kind: "recorded_exhaustion",
+            family: command.family,
+            receipt: {
+                ownerKey: REFILL_V3_SOURCE_FAMILY_TABLE[command.family].broadening,
+                requestFingerprint: command.requestFingerprint,
+                idempotencyKey: scope.idempotencyKey,
+                sourceBeforeFingerprint: scope.priorSourceFingerprint,
+                sourceAfterFingerprint: scope.priorSourceFingerprint,
+                sourceBeforeCount: 0,
+                sourceAfterCount: 0,
+                importedCount: 0,
+                effects: [],
+                replayState: "not_applicable",
+                rollback: { available: false, reason: "not_applicable" },
+                postRationales: null,
+                yieldEvidence: input.exhaustionEvidence.yieldEvidence,
+            },
+            exhausted: true,
+            reobserveRequired: true,
+        };
+    }
+    // 12. EXACTLY ONE call to the exact existing owner through the constant table.
+    const table = REFILL_V3_SOURCE_FAMILY_TABLE[command.family];
+    const ownerKey = action === "continue" ? table.continuation : table.broadening;
+    const outcome = await input.owners[ownerKey]({
+        scope,
+        command,
+        providerPromptPackage: input.providerPromptPackage ?? null,
+    });
+    // 13. Provider INFRASTRUCTURE failure is never exhaustion, and nothing that
+    //     never ran may register as searched.
+    if (outcome.kind === "failure") {
+        return {
+            kind: "scoped_failure",
+            family: command.family,
+            failureClass: outcome.failureClass,
+            retryable: true,
+            effectIdentity: null,
+            detail: `${ownerKey}: ${outcome.detail}`,
+            exhausted: false,
+            reobserveRequired: true,
+        };
+    }
+    if (outcome.kind === "timeout") {
+        return {
+            kind: "scoped_failure",
+            family: command.family,
+            failureClass: "uncertain",
+            retryable: true,
+            effectIdentity: outcome.effectIdentity,
+            detail: `${ownerKey} returned no value; reconcile by effect identity before another mutation.`,
+            exhausted: false,
+            reobserveRequired: true,
+        };
+    }
+    const receipt = outcome.receipt;
+    if (!isNonEmpty(receipt.sourceBeforeFingerprint) ||
+        !isNonEmpty(receipt.sourceAfterFingerprint) ||
+        !isNonEmpty(receipt.requestFingerprint) ||
+        !isNonEmpty(receipt.idempotencyKey)) {
+        return refused("receipt_incomplete", `${ownerKey} returned a receipt without complete source before/after and request evidence; uncertain evidence is never success.`);
+    }
+    // 14. The AI's recorded per-candidate verdicts feed the SHARED floor. The
+    //     arithmetic, the comparison, and the routing are deterministic; there is
+    //     no deterministic candidate judge.
+    const verdicts = input.candidateVerdicts ?? null;
+    const yieldVerdict = verdicts && verdicts.length > 0
+        ? evaluateRefillV3DispatchYield({
+            family: command.family,
+            evaluated: verdicts.length,
+            passes: verdicts.filter((entry) => entry.verdict === "pass").length,
+        })
+        : receipt.yieldEvidence
+            ? evaluateRefillV3DispatchYield(receipt.yieldEvidence)
+            : null;
+    // A round that MEETS the floor is a qualifying source: import and stop
+    // broadening, so its fingerprint is not a refusal for later rounds. Every
+    // other completed round registers so it cannot repeat unchanged.
+    const registers = yieldVerdict === null || yieldVerdict.decision !== "meets_floor";
+    const negativeSetAdditions = registers
+        ? [
+            {
+                campaignId: scope.campaignId,
+                family: command.family,
+                sourceFingerprint: command.requestFingerprint,
+                semanticFingerprint: semantic,
+                keywordBatch: command.keywordBatch,
+                postIds: command.selectedPostIds,
+                releaseCondition: releaseConditionFor({
+                    campaignId: scope.campaignId,
+                    family: command.family,
+                    provider: command.provider,
+                    sourceFingerprint: command.requestFingerprint,
+                    semanticFingerprint: semantic,
+                    keywordBatch: command.keywordBatch,
+                    postIds: command.selectedPostIds,
+                    importedCount: receipt.importedCount,
+                    yieldEvidence: receipt.yieldEvidence,
+                    observedAt: scope.date,
+                    searchCompleted: true,
+                }),
+                observedAt: scope.date,
+            },
+        ]
+        : [];
+    return {
+        kind: "dispatched",
+        ownerKey,
+        // The PUBLIC family token is returned unchanged.
+        family: command.family,
+        receipt,
+        yieldVerdict,
+        negativeSetAdditions,
+        exhausted: false,
+        reobserveRequired: true,
+    };
+}
+/** Re-exported bounds so no consumer restates them. */
+export const REFILL_V3_SOURCE_DISPATCH_BOUNDS = Object.freeze({
+    keywordBatchSize: REFILL_V3_POSTS_KEYWORD_BATCH_SIZE,
+    maxSelectedPosts: REFILL_V3_POSTS_MAX_SELECTED,
+    postsRoundBudget: REFILL_V3_POSTS_ROUND_BUDGET,
+    minSourceYield: REFILL_V3_MIN_SOURCE_YIELD,
+    yieldSample: REFILL_V3_MIN_SOURCE_YIELD_SAMPLE,
+});
+/** The AI claim is ROUTED through the shared predicate, never re-tabled here. */
+export function falsifyRefillV3SourceExhaustion(evidence) {
+    return REFILL_V3_EXHAUSTION_PREDICATE.evaluate(evidence);
+}
+export function evaluateRefillV3DispatchYield(evidence) {
+    return evaluateRefillV3SourceYield(evidence);
+}
+export function isRefillV3LeadSourceFamily(value) {
+    return (typeof value === "string" &&
+        REFILL_V3_LEAD_SOURCE_FAMILIES.includes(value));
+}

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

@@ -0,0 +1,156 @@
+/**
+ * Refill V3 campaign WATERFALL proposal/validation PACKAGE seam.
+ *
+ * The 144 authority split, restored: the BACKEND issues the complete eligible
+ * campaign set for one sender/lane row, the AI proposes an ORDER (up to three)
+ * with a rationale per entry and may propose activating one PAUSED,
+ * start-eligible campaign, and the BACKEND deterministically validates and pins
+ * that order. A proposal is never a campaign selector: a campaign the backend
+ * did not issue for that row can never enter the order.
+ *
+ * A rejection is TYPED and the row CONTINUES with the deterministic fallback
+ * order. A rejected proposal never halts the row.
+ *
+ * The validated order is pinned TASK-LOCALLY for that row's ephemeral FIFO
+ * queue. There is no durable waterfall storage, cursor, ledger, or database
+ * model, and `guidance` is caller-supplied additive context only.
+ *
+ * This module is dependency-free by design: it imports nothing, so it cannot
+ * drag app `src/**`, a validation library, or a sibling contract into the
+ * published package.
+ */
+/**
+ * The minimum campaign shape the validator needs. The world-state contract's
+ * `CampaignOption` satisfies it structurally, which keeps the waterfall seam
+ * dependency-free without declaring a second campaign vocabulary.
+ */
+export interface RefillV3WaterfallCampaignFact {
+    id: string;
+    /**
+     * ADDITIVE (146.5-12 §85, user ruling): every candidate entry in the AI's
+     * input packet also names its `campaignId` explicitly — the same value as
+     * `id`, under the name the PROPOSAL vocabulary uses — so a rationale, a
+     * receipt, or a bounded brief read can cite the campaign without a field
+     * rename in between. Optional for older callers; the validator keys on
+     * `id`.
+     */
+    campaignId?: string;
+    status: string;
+    startEligible: boolean;
+}
+export interface RefillV3WaterfallSender {
+    id: string;
+}
+/**
+ * Row-scoped input, built only from transport campaign facts the observer
+ * already emits. `inactiveCampaigns` contains ONLY PAUSED entries with
+ * canonical `startEligible: true`, which is what makes an activation proposal
+ * checkable without a second eligibility rule.
+ */
+export type RefillV3WaterfallInput = {
+    sender: RefillV3WaterfallSender;
+    lane: string;
+    activeCampaigns: readonly RefillV3WaterfallCampaignFact[];
+    inactiveCampaigns: readonly RefillV3WaterfallCampaignFact[];
+    /**
+     * ADDITIVE (146.5-12 §85): how many actions this row can still take today.
+     * SKILL.md has documented this packet field since Plan 09; the type now
+     * declares it instead of relying on structural pass-through.
+     */
+    availableSlots?: number;
+    /**
+     * ADDITIVE (146.5-12 cluster, user directive): the workspace's OWN
+     * per-family engagement aggregates — average accept/reply plus total sends
+     * per lead-source family, computed by the same engagement owner behind
+     * `evidence.engagement`. A family with no engagement facts is ABSENT (no
+     * data), never a fabricated zero. Real data leads; the SKILL's typical
+     * benchmarks fill the cold start.
+     */
+    familyBenchmarks?: Readonly<Record<string, {
+        sends: number;
+        accepted: number;
+        replied: number;
+        acceptRate: number;
+        replyRate: number;
+    }>>;
+    guidance?: RefillV3WaterfallGuidance;
+};
+/**
+ * Additive, caller-supplied context. It introduces no database model and no
+ * durable waterfall storage; both remain out of scope.
+ */
+export type RefillV3WaterfallGuidance = {
+    priorChoices?: readonly string[];
+    experimentPrecedence?: readonly string[];
+    operatorPreferredCampaignId?: string;
+};
+export declare const REFILL_V3_WATERFALL_MAX_ORDER = 3;
+export type RefillV3WaterfallOrderEntry = {
+    campaignId: string;
+    rationale: string;
+};
+export type RefillV3WaterfallProposal = {
+    order: RefillV3WaterfallOrderEntry[];
+    activation?: RefillV3WaterfallOrderEntry;
+};
+export declare const REFILL_V3_WATERFALL_REJECTIONS: readonly ["unissued_campaign_id", "activation_not_start_eligible", "activation_campaign_absent", "duplicate_campaign_id", "order_too_long", "order_empty", "malformed_output"];
+export type RefillV3WaterfallRejection = (typeof REFILL_V3_WATERFALL_REJECTIONS)[number];
+export type RefillV3WaterfallDecodeResult = {
+    ok: true;
+    value: RefillV3WaterfallProposal;
+} | {
+    ok: false;
+    rejection: RefillV3WaterfallRejection;
+    detail: string;
+};
+export declare const REFILL_V3_WATERFALL_PROPOSAL_SCHEMA: Readonly<{
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["order"];
+    readonly properties: {
+        readonly order: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly maxItems: 3;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["campaignId", "rationale"];
+                readonly properties: {
+                    readonly campaignId: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly rationale: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                };
+            };
+            readonly description: "ordered campaigns for this row; every id must already be issued for the row";
+        };
+        readonly activation: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["campaignId", "rationale"];
+            readonly properties: {
+                readonly campaignId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly rationale: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+            readonly description: "at most one PAUSED, start-eligible campaign proposed for activation";
+        };
+    };
+}>;
+/**
+ * Sole validator for an AI-proposed waterfall order.
+ *
+ * The issued set is REQUIRED: membership in the row's issued campaigns is the
+ * 144 rule, and it cannot be decided from the model's output alone.
+ */
+export declare function decodeRefillV3WaterfallProposal(value: unknown, issued: RefillV3WaterfallInput): RefillV3WaterfallDecodeResult;