@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-source-family-dispatch.d.ts

@@ -0,0 +1,249 @@
+/**
+ * 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 { type RefillV3ActiveJob, type RefillV3ExhaustionInput, type RefillV3ExhaustionVerdict, type RefillV3LeadSourceFamily, type RefillV3ProviderSearchReference, type RefillV3SourceYieldEvidence, type RefillV3SourceYieldVerdict } from "./refill-v3-attention-packet-contract.js";
+import { type RefillV3CandidateVerdict, type RefillV3SourceCommand } from "./refill-v3-campaign-work.js";
+export declare const REFILL_V3_SOURCE_OWNER_KEYS: readonly ["refreshSenderPostEngagers", "continueSignalDiscoverySource", "broadenSignalSearch", "continueProviderSource", "broadenProviderSearch"];
+export type RefillV3SourceOwnerKey = (typeof REFILL_V3_SOURCE_OWNER_KEYS)[number];
+/**
+ * The CONSTANT family table. The public token `cold` maps INTERNALLY to the
+ * provider owners; no boundary rewrites it to another public token.
+ */
+export declare const REFILL_V3_SOURCE_FAMILY_TABLE: Readonly<Record<RefillV3LeadSourceFamily, {
+    continuation: RefillV3SourceOwnerKey;
+    broadening: RefillV3SourceOwnerKey;
+}>>;
+export declare const REFILL_V3_SOURCE_DISPATCH_REFUSALS: readonly ["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"];
+export type RefillV3SourceDispatchRefusal = (typeof REFILL_V3_SOURCE_DISPATCH_REFUSALS)[number];
+/**
+ * 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 declare const REFILL_V3_SOURCE_FAILURE_CLASSES: readonly ["owner_threw", "timeout", "provider_5xx", "rate_limit"];
+export type RefillV3SourceFailureClass = (typeof REFILL_V3_SOURCE_FAILURE_CLASSES)[number];
+/**
+ * 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 declare const REFILL_V3_NEGATIVE_SET_RELEASE_CONDITIONS: readonly ["campaign_icp_changed", "provider_inventory_refreshed", "evidence_window_rolled", "posts_refreshed_in_window"];
+export type RefillV3NegativeSetReleaseCondition = (typeof REFILL_V3_NEGATIVE_SET_RELEASE_CONDITIONS)[number];
+export declare const REFILL_V3_NEGATIVE_SET_PROVENANCE_UNAVAILABLE: "negative_set_provenance_unavailable";
+/**
+ * One canonical source-run / import lineage record. Every field already exists on
+ * the source-run and import lineage plus `actionSourceFingerprint` and
+ * `actionLeadSourceProvider`; nothing new is persisted.
+ */
+export type RefillV3SourceLineageRecord = {
+    campaignId: string;
+    family: RefillV3LeadSourceFamily;
+    provider: string | null;
+    sourceFingerprint: string;
+    /** Canonicalized semantic identity: incidental fields are already stripped. */
+    semanticFingerprint: string;
+    keywordBatch: readonly string[] | null;
+    postIds: readonly string[] | null;
+    importedCount: number;
+    yieldEvidence: RefillV3SourceYieldEvidence | null;
+    observedAt: string;
+    /** Only a COMPLETED search registers. An unexecuted attempt never does. */
+    searchCompleted: boolean;
+};
+export type RefillV3NegativeSetEntry = {
+    campaignId: string;
+    family: RefillV3LeadSourceFamily;
+    sourceFingerprint: string;
+    semanticFingerprint: string;
+    keywordBatch: readonly string[] | null;
+    postIds: readonly string[] | null;
+    releaseCondition: RefillV3NegativeSetReleaseCondition;
+    observedAt: string;
+};
+export type RefillV3NegativeSet = {
+    provenance: "derived";
+    entries: readonly RefillV3NegativeSetEntry[];
+    /** Rounds already spent on the posts-search avenue in this window. */
+    postsRoundsByCampaign: Readonly<Record<string, number>>;
+    /** Dry claims are keyed per `(family, campaignId)`, never globally. */
+    dryFamilies: readonly string[];
+} | {
+    provenance: typeof REFILL_V3_NEGATIVE_SET_PROVENANCE_UNAVAILABLE;
+    entries: readonly [];
+    postsRoundsByCampaign: Readonly<Record<string, number>>;
+    dryFamilies: readonly [];
+};
+export declare const REFILL_V3_SOURCE_DISPATCH_ACTIONS: readonly ["continue", "broaden", "record_exhaustion"];
+export type RefillV3SourceDispatchAction = (typeof REFILL_V3_SOURCE_DISPATCH_ACTIONS)[number];
+export type RefillV3SourceDispatchScope = {
+    workspaceId: string;
+    campaignId: string;
+    tableId: string;
+    sourceLeadListId?: string | null;
+    senderId: string;
+    date: string;
+    count: number;
+    campaignVersion: number;
+    evidenceFingerprint: string;
+    priorSourceFingerprint: string;
+    idempotencyKey: string;
+    providerSearchReference?: RefillV3ProviderSearchReference | null;
+};
+export type RefillV3SourceOwnerReceipt = {
+    ownerKey: RefillV3SourceOwnerKey;
+    requestFingerprint: string;
+    idempotencyKey: string;
+    sourceBeforeFingerprint: string;
+    sourceAfterFingerprint: string;
+    sourceBeforeCount: number;
+    sourceAfterCount: number;
+    importedCount: number;
+    effects: readonly string[];
+    replayState: "first" | "exact_replay" | "not_applicable";
+    rollback: {
+        available: true;
+        input: Record<string, unknown>;
+        result: string | null;
+    } | {
+        available: false;
+        reason: "not_applicable";
+    };
+    /** Per-post selection rationale, so a bad pick stays auditable. */
+    postRationales: readonly {
+        postId: string;
+        expectedYieldBasis: string;
+    }[] | null;
+    yieldEvidence: RefillV3SourceYieldEvidence | null;
+};
+export type RefillV3SourceOwnerOutcome = {
+    kind: "receipt";
+    receipt: RefillV3SourceOwnerReceipt;
+} | {
+    kind: "no_effect";
+    receipt: RefillV3SourceOwnerReceipt;
+} | {
+    kind: "failure";
+    failureClass: RefillV3SourceFailureClass;
+    detail: string;
+} | {
+    kind: "timeout";
+    effectIdentity: string | null;
+};
+export type RefillV3SourceFamilyOwners = Readonly<Record<RefillV3SourceOwnerKey, (request: {
+    scope: RefillV3SourceDispatchScope;
+    command: RefillV3SourceCommand;
+    providerPromptPackage: string | null;
+}) => Promise<RefillV3SourceOwnerOutcome>>>;
+export type RefillV3SourceDispatchInput = {
+    scope: RefillV3SourceDispatchScope;
+    action: RefillV3SourceDispatchAction;
+    /** The AI's already-bounded command. Never re-derived here. */
+    command: RefillV3SourceCommand;
+    owners: RefillV3SourceFamilyOwners;
+    lineage: readonly RefillV3SourceLineageRecord[] | null;
+    observedFamily: RefillV3LeadSourceFamily;
+    activeJob: RefillV3ActiveJob | null;
+    healthEvidence?: readonly string[];
+    /** Loaded provider guidance identity, when a new provider search needs it. */
+    providerPromptPackage?: string | null;
+    /** In-window authored-posts refresh receipt for `post_engager`. */
+    postsRefreshedInWindow?: boolean;
+    candidateVerdicts?: readonly RefillV3CandidateVerdict[] | null;
+    exhaustionEvidence?: RefillV3ExhaustionInput | null;
+};
+export type RefillV3SourceDispatchResult = {
+    kind: "dispatched";
+    ownerKey: RefillV3SourceOwnerKey;
+    family: RefillV3LeadSourceFamily;
+    receipt: RefillV3SourceOwnerReceipt;
+    yieldVerdict: RefillV3SourceYieldVerdict | null;
+    negativeSetAdditions: readonly RefillV3NegativeSetEntry[];
+    exhausted: false;
+    reobserveRequired: true;
+} | {
+    kind: "recorded_exhaustion";
+    family: RefillV3LeadSourceFamily;
+    receipt: RefillV3SourceOwnerReceipt;
+    exhausted: true;
+    reobserveRequired: true;
+} | {
+    kind: "refused";
+    refusal: RefillV3SourceDispatchRefusal;
+    detail: string;
+    matchingFingerprint: string | null;
+    releaseCondition: RefillV3NegativeSetReleaseCondition | null;
+    exhausted: false;
+    reobserveRequired: boolean;
+} | {
+    kind: "scoped_failure";
+    family: RefillV3LeadSourceFamily;
+    failureClass: RefillV3SourceFailureClass | "uncertain";
+    retryable: true;
+    effectIdentity: string | null;
+    detail: string;
+    exhausted: false;
+    reobserveRequired: true;
+};
+/**
+ * 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 declare function canonicalRefillV3SourceFingerprint(command: RefillV3SourceCommand): string;
+/**
+ * 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 declare function deriveRefillV3SearchedNegativeSet(lineage: readonly RefillV3SourceLineageRecord[] | null, options?: {
+    campaignId?: string;
+}): RefillV3NegativeSet;
+/**
+ * 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 declare function dispatchRefillV3SourceFamily(input: RefillV3SourceDispatchInput): Promise<RefillV3SourceDispatchResult>;
+/** Re-exported bounds so no consumer restates them. */
+export declare const REFILL_V3_SOURCE_DISPATCH_BOUNDS: Readonly<{
+    keywordBatchSize: 5;
+    maxSelectedPosts: 5;
+    postsRoundBudget: 3;
+    minSourceYield: 0.08;
+    yieldSample: 20;
+}>;
+/** The AI claim is ROUTED through the shared predicate, never re-tabled here. */
+export declare function falsifyRefillV3SourceExhaustion(evidence: RefillV3ExhaustionInput): RefillV3ExhaustionVerdict;
+export declare function evaluateRefillV3DispatchYield(evidence: RefillV3SourceYieldEvidence): RefillV3SourceYieldVerdict;
+export declare function isRefillV3LeadSourceFamily(value: unknown): value is RefillV3LeadSourceFamily;