@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-waterfall-contract.js

@@ -0,0 +1,181 @@
+/**
+ * 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.
+ */
+export const REFILL_V3_WATERFALL_MAX_ORDER = 3;
+export const REFILL_V3_WATERFALL_REJECTIONS = [
+    "unissued_campaign_id",
+    "activation_not_start_eligible",
+    "activation_campaign_absent",
+    "duplicate_campaign_id",
+    "order_too_long",
+    "order_empty",
+    "malformed_output",
+];
+export const REFILL_V3_WATERFALL_PROPOSAL_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["order"],
+    properties: {
+        order: {
+            type: "array",
+            minItems: 1,
+            maxItems: REFILL_V3_WATERFALL_MAX_ORDER,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["campaignId", "rationale"],
+                properties: {
+                    campaignId: { type: "string", minLength: 1 },
+                    rationale: { type: "string", minLength: 1 },
+                },
+            },
+            description: "ordered campaigns for this row; every id must already be issued for the row",
+        },
+        activation: {
+            type: "object",
+            additionalProperties: false,
+            required: ["campaignId", "rationale"],
+            properties: {
+                campaignId: { type: "string", minLength: 1 },
+                rationale: { type: "string", minLength: 1 },
+            },
+            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 function decodeRefillV3WaterfallProposal(value, issued) {
+    if (!isRecord(value)) {
+        return malformed("Proposal must be an object.");
+    }
+    const unknownField = Object.keys(value).find((key) => !PROPOSAL_KEYS.has(key));
+    if (unknownField) {
+        return malformed(`Unknown proposal field: ${unknownField}`);
+    }
+    if (!Array.isArray(value.order)) {
+        return malformed("Proposal order must be an array.");
+    }
+    if (value.order.length === 0) {
+        return { ok: false, rejection: "order_empty", detail: "Order is empty." };
+    }
+    if (value.order.length > REFILL_V3_WATERFALL_MAX_ORDER) {
+        return {
+            ok: false,
+            rejection: "order_too_long",
+            detail: `Order has ${value.order.length} entries; at most ${REFILL_V3_WATERFALL_MAX_ORDER} are allowed.`,
+        };
+    }
+    const order = [];
+    for (const entry of value.order) {
+        const decoded = decodeEntry(entry);
+        if (decoded === null) {
+            return malformed("Every order entry needs a campaignId and a rationale.");
+        }
+        order.push(decoded);
+    }
+    let activation;
+    if (value.activation !== undefined) {
+        const decoded = decodeEntry(value.activation);
+        if (decoded === null) {
+            return malformed("An activation proposal needs exactly one campaignId and rationale.");
+        }
+        activation = decoded;
+    }
+    const activeIds = new Set(issued.activeCampaigns.map((entry) => entry.id));
+    for (const entry of order) {
+        if (!activeIds.has(entry.campaignId)) {
+            return {
+                ok: false,
+                rejection: "unissued_campaign_id",
+                detail: `Campaign ${entry.campaignId} was not issued for this row.`,
+            };
+        }
+    }
+    const orderedIds = new Set();
+    for (const entry of order) {
+        if (orderedIds.has(entry.campaignId)) {
+            return {
+                ok: false,
+                rejection: "duplicate_campaign_id",
+                detail: `Campaign ${entry.campaignId} appears more than once.`,
+            };
+        }
+        orderedIds.add(entry.campaignId);
+    }
+    if (activation) {
+        if (orderedIds.has(activation.campaignId)) {
+            return {
+                ok: false,
+                rejection: "duplicate_campaign_id",
+                detail: `Campaign ${activation.campaignId} is both ordered and proposed for activation.`,
+            };
+        }
+        const candidate = issued.inactiveCampaigns.find((entry) => entry.id === activation?.campaignId);
+        if (!candidate) {
+            return {
+                ok: false,
+                rejection: "activation_campaign_absent",
+                detail: `Campaign ${activation.campaignId} is not in the issued inactive set for this row.`,
+            };
+        }
+        if (candidate.startEligible !== true) {
+            return {
+                ok: false,
+                rejection: "activation_not_start_eligible",
+                detail: `Campaign ${activation.campaignId} is not start eligible.`,
+            };
+        }
+    }
+    return {
+        ok: true,
+        value: activation ? { order, activation } : { order },
+    };
+}
+const PROPOSAL_KEYS = new Set(["order", "activation"]);
+const ENTRY_KEYS = new Set(["campaignId", "rationale"]);
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function malformed(detail) {
+    return { ok: false, rejection: "malformed_output", detail };
+}
+/**
+ * An entry is projected FIELD BY FIELD from what the model actually named, so
+ * the validator can never invent, reorder, or substitute a campaign.
+ */
+function decodeEntry(value) {
+    if (!isRecord(value))
+        return null;
+    if (Object.keys(value).some((key) => !ENTRY_KEYS.has(key)))
+        return null;
+    if (typeof value.campaignId !== "string" ||
+        value.campaignId.trim().length === 0 ||
+        typeof value.rationale !== "string" ||
+        value.rationale.trim().length === 0) {
+        return null;
+    }
+    return { campaignId: value.campaignId, rationale: value.rationale };
+}

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

@@ -0,0 +1,136 @@
+/**
+ * Refill V3 waterfall-order RUNTIME VALIDATOR (Phase 146.5 Plan 09 T6, RV3WF-001).
+ *
+ * AI seam #1's owned runtime home. The subskill proposes an ORDER of up to three
+ * already-issued campaigns for one sender/lane row, with a rationale each, and
+ * MAY propose activating one PAUSED, start-eligible campaign. This module is the
+ * only thing standing between a model's free-text ordering and an unbounded
+ * campaign selector.
+ *
+ * It enforces the 144 rule through Plan 02's `decodeRefillV3WaterfallProposal`:
+ * the BACKEND issues the eligible set, the AI proposes an order, and the BACKEND
+ * validates and pins it. A campaign the backend did not issue can never enter.
+ *
+ * Every rejection is TYPED and NON-FATAL. A rejected proposal never halts the
+ * row, never mutates anything, and never causes the coordinator to skip the row:
+ * the run continues on the deterministic fallback order.
+ *
+ * It shares ONE failure taxonomy, receipt shape, and replay harness with the
+ * campaign-work validator (`A09-AI-SEAM-RUNTIME-HOME`, disposition D7) and does
+ * not fork a second AI-output framework.
+ */
+import { REFILL_V3_AI_OUTPUT_FAILURES, type RefillV3AiOutputFailure } from "./refill-v3-campaign-work.js";
+import { decodeRefillV3WaterfallProposal, REFILL_V3_WATERFALL_REJECTIONS, type RefillV3WaterfallInput, type RefillV3WaterfallOrderEntry, type RefillV3WaterfallProposal, type RefillV3WaterfallRejection } from "./refill-v3-waterfall-contract.js";
+/** The shared taxonomy, re-exported so consumers need one import. */
+export { REFILL_V3_AI_OUTPUT_FAILURES };
+export type { RefillV3AiOutputFailure };
+export declare const REFILL_V3_WATERFALL_ACTIVATION_LIMIT_PER_ROW = 1;
+export type RefillV3WaterfallRowScope = {
+    workspaceId: string;
+    senderId: string;
+    lane: string;
+    date: string;
+};
+/**
+ * The TASK-LOCAL pin. It is a plain in-memory value for one row's ephemeral FIFO
+ * queue: no durable waterfall storage, no cursor, no ledger, no database model.
+ */
+export type RefillV3WaterfallPinnedOrder = {
+    rowKey: string;
+    campaignIds: readonly string[];
+    rationales: Readonly<Record<string, string>>;
+    activation: RefillV3WaterfallOrderEntry | null;
+    source: "ai_validated" | "deterministic_fallback";
+};
+export type RefillV3WaterfallActivationReceipt = {
+    campaignId: string;
+    before: string;
+    after: string;
+    effectKey: string;
+    reobserveRequired: true;
+};
+export type RefillV3WaterfallDependencies = {
+    /** The EXISTING campaign mutation authority. Never a raw write. */
+    activateCampaign(input: {
+        workspaceId: string;
+        campaignId: string;
+        idempotencyKey: string;
+    }): Promise<{
+        before: string;
+        after: string;
+        effectKey: string;
+    }>;
+    reobserveExactSenderDates(input: {
+        workspaceId: string;
+        senderId: string;
+        date: string;
+    }): Promise<{
+        lanes: readonly string[];
+    }>;
+};
+export type RefillV3WaterfallCall = {
+    step: "validate" | "activate" | "reobserve";
+    detail: string;
+};
+export type RefillV3WaterfallOutcome = {
+    ok: true;
+    pinned: RefillV3WaterfallPinnedOrder;
+    activation: RefillV3WaterfallActivationReceipt | null;
+    callLog: readonly RefillV3WaterfallCall[];
+} | {
+    ok: false;
+    rejection: RefillV3WaterfallRejection | RefillV3AiOutputFailure;
+    detail: string;
+    /** A rejection is NON-FATAL: the row continues on this order. */
+    fallback: RefillV3WaterfallPinnedOrder;
+    callLog: readonly RefillV3WaterfallCall[];
+};
+/**
+ * TASK-LOCAL activation ledger, bounded to one activation per row per task.
+ * Nothing durable: it exists so a second activation inside one task is
+ * impossible, not to remember anything across tasks.
+ */
+export type RefillV3WaterfallTaskScope = {
+    readonly activationsByRow: Map<string, number>;
+};
+export declare function createRefillV3WaterfallTaskScope(): RefillV3WaterfallTaskScope;
+export declare function refillV3WaterfallRowKey(scope: RefillV3WaterfallRowScope): string;
+/**
+ * The deterministic FALLBACK order.
+ *
+ * It is the backend's own canonical issue order for the row, consumed verbatim.
+ * Deriving a second ordering rule here would put ordering policy in two places.
+ */
+export declare function refillV3FallbackWaterfallOrder(issued: RefillV3WaterfallInput, scope: RefillV3WaterfallRowScope): RefillV3WaterfallPinnedOrder;
+/**
+ * Validation is MEMBERSHIP, START-ELIGIBILITY, and SHAPE only.
+ *
+ * It deliberately holds no ordering policy: the model keeps the judgment, and a
+ * validator that re-sorted the proposal would silently replace that judgment
+ * with a second, undocumented ordering rule.
+ */
+export declare function validateRefillV3WaterfallProposal(value: unknown, issued: RefillV3WaterfallInput): {
+    ok: true;
+    value: RefillV3WaterfallProposal;
+} | {
+    ok: false;
+    rejection: RefillV3WaterfallRejection;
+    detail: string;
+};
+/**
+ * Validate ONE proposal, execute at most one activation through the EXISTING
+ * authority, and force the immediate two-lane re-observation.
+ *
+ * A rejection is a VALUE carrying the deterministic fallback: the row continues,
+ * and the caller never has to decide what a thrown validation error means.
+ */
+export declare function applyRefillV3WaterfallProposal(input: {
+    value: unknown;
+    issued: RefillV3WaterfallInput;
+    scope: RefillV3WaterfallRowScope;
+    dependencies: RefillV3WaterfallDependencies;
+    taskScope?: RefillV3WaterfallTaskScope;
+    idempotencyKey?: string;
+}): Promise<RefillV3WaterfallOutcome>;
+/** Re-exported so no consumer restates the closed rejection vocabulary. */
+export { decodeRefillV3WaterfallProposal, REFILL_V3_WATERFALL_REJECTIONS };

package/dist/tools/refill-v3-waterfall.js

@@ -0,0 +1,161 @@
+/**
+ * Refill V3 waterfall-order RUNTIME VALIDATOR (Phase 146.5 Plan 09 T6, RV3WF-001).
+ *
+ * AI seam #1's owned runtime home. The subskill proposes an ORDER of up to three
+ * already-issued campaigns for one sender/lane row, with a rationale each, and
+ * MAY propose activating one PAUSED, start-eligible campaign. This module is the
+ * only thing standing between a model's free-text ordering and an unbounded
+ * campaign selector.
+ *
+ * It enforces the 144 rule through Plan 02's `decodeRefillV3WaterfallProposal`:
+ * the BACKEND issues the eligible set, the AI proposes an order, and the BACKEND
+ * validates and pins it. A campaign the backend did not issue can never enter.
+ *
+ * Every rejection is TYPED and NON-FATAL. A rejected proposal never halts the
+ * row, never mutates anything, and never causes the coordinator to skip the row:
+ * the run continues on the deterministic fallback order.
+ *
+ * It shares ONE failure taxonomy, receipt shape, and replay harness with the
+ * campaign-work validator (`A09-AI-SEAM-RUNTIME-HOME`, disposition D7) and does
+ * not fork a second AI-output framework.
+ */
+import { REFILL_V3_AI_OUTPUT_FAILURES, } from "./refill-v3-campaign-work.js";
+import { decodeRefillV3WaterfallProposal, REFILL_V3_WATERFALL_MAX_ORDER, REFILL_V3_WATERFALL_REJECTIONS, } from "./refill-v3-waterfall-contract.js";
+/** The shared taxonomy, re-exported so consumers need one import. */
+export { REFILL_V3_AI_OUTPUT_FAILURES };
+export const REFILL_V3_WATERFALL_ACTIVATION_LIMIT_PER_ROW = 1;
+export function createRefillV3WaterfallTaskScope() {
+    return { activationsByRow: new Map() };
+}
+export function refillV3WaterfallRowKey(scope) {
+    return `${scope.workspaceId}:${scope.senderId}:${scope.lane}:${scope.date}`;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// STUB — behaviour lands at this task's GREEN commit.
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The deterministic FALLBACK order.
+ *
+ * It is the backend's own canonical issue order for the row, consumed verbatim.
+ * Deriving a second ordering rule here would put ordering policy in two places.
+ */
+export function refillV3FallbackWaterfallOrder(issued, scope) {
+    return {
+        rowKey: refillV3WaterfallRowKey(scope),
+        campaignIds: issued.activeCampaigns
+            .slice(0, REFILL_V3_WATERFALL_MAX_ORDER)
+            .map((entry) => entry.id),
+        rationales: {},
+        activation: null,
+        source: "deterministic_fallback",
+    };
+}
+/**
+ * Validation is MEMBERSHIP, START-ELIGIBILITY, and SHAPE only.
+ *
+ * It deliberately holds no ordering policy: the model keeps the judgment, and a
+ * validator that re-sorted the proposal would silently replace that judgment
+ * with a second, undocumented ordering rule.
+ */
+export function validateRefillV3WaterfallProposal(value, issued) {
+    const decoded = decodeRefillV3WaterfallProposal(value, issued);
+    return decoded.ok
+        ? { ok: true, value: decoded.value }
+        : { ok: false, rejection: decoded.rejection, detail: decoded.detail };
+}
+function pinnedFrom(proposal, scope) {
+    const rationales = {};
+    for (const entry of proposal.order) {
+        rationales[entry.campaignId] = entry.rationale;
+    }
+    return {
+        rowKey: refillV3WaterfallRowKey(scope),
+        // The model's exact order, projected entry by entry.
+        campaignIds: proposal.order.map((entry) => entry.campaignId),
+        rationales,
+        activation: proposal.activation ?? null,
+        source: "ai_validated",
+    };
+}
+/**
+ * Validate ONE proposal, execute at most one activation through the EXISTING
+ * authority, and force the immediate two-lane re-observation.
+ *
+ * A rejection is a VALUE carrying the deterministic fallback: the row continues,
+ * and the caller never has to decide what a thrown validation error means.
+ */
+export async function applyRefillV3WaterfallProposal(input) {
+    const { issued, scope, dependencies, taskScope } = input;
+    const callLog = [];
+    const fallback = refillV3FallbackWaterfallOrder(issued, scope);
+    const rowKey = refillV3WaterfallRowKey(scope);
+    const validated = validateRefillV3WaterfallProposal(input.value, issued);
+    callLog.push({ step: "validate", detail: rowKey });
+    if (!validated.ok) {
+        return {
+            ok: false,
+            rejection: validated.rejection,
+            detail: validated.detail,
+            fallback,
+            callLog,
+        };
+    }
+    const pinned = pinnedFrom(validated.value, scope);
+    const activation = validated.value.activation ?? null;
+    if (!activation) {
+        return { ok: true, pinned, activation: null, callLog };
+    }
+    // At most ONE activation per row per task. The bound is task-local and exists
+    // so a second activation inside one task is impossible.
+    const used = taskScope?.activationsByRow.get(rowKey) ?? 0;
+    if (used >= REFILL_V3_WATERFALL_ACTIVATION_LIMIT_PER_ROW) {
+        return {
+            ok: false,
+            rejection: "activation_campaign_absent",
+            detail: `This row already used its ${REFILL_V3_WATERFALL_ACTIVATION_LIMIT_PER_ROW} activation in this task.`,
+            fallback,
+            callLog,
+        };
+    }
+    let receipt;
+    try {
+        const effect = await dependencies.activateCampaign({
+            workspaceId: scope.workspaceId,
+            campaignId: activation.campaignId,
+            idempotencyKey: input.idempotencyKey ?? `waterfall:${rowKey}`,
+        });
+        callLog.push({ step: "activate", detail: activation.campaignId });
+        receipt = {
+            campaignId: activation.campaignId,
+            before: effect.before,
+            after: effect.after,
+            effectKey: effect.effectKey,
+            reobserveRequired: true,
+        };
+    }
+    catch (error) {
+        // An authority failure is typed and NON-FATAL: the row continues on the
+        // fallback rather than claiming an activation nobody observed.
+        return {
+            ok: false,
+            rejection: "activation_campaign_absent",
+            detail: `The existing campaign authority refused or failed for ${activation.campaignId}: ${error instanceof Error ? error.name : "unknown"}`,
+            fallback,
+            callLog,
+        };
+    }
+    taskScope?.activationsByRow.set(rowKey, used + 1);
+    // Immediate two-lane re-observation BEFORE any further decision.
+    await dependencies.reobserveExactSenderDates({
+        workspaceId: scope.workspaceId,
+        senderId: scope.senderId,
+        date: scope.date,
+    });
+    callLog.push({
+        step: "reobserve",
+        detail: `${scope.senderId}:${scope.date}`,
+    });
+    return { ok: true, pinned, activation: receipt, callLog };
+}
+/** Re-exported so no consumer restates the closed rejection vocabulary. */
+export { decodeRefillV3WaterfallProposal, REFILL_V3_WATERFALL_REJECTIONS };