@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-fill-ready-contract.js

@@ -0,0 +1,324 @@
+/**
+ * Refill V3 fill-ready PACKAGE seam.
+ *
+ * This module is the SOLE owner of the fill-ready public result contract:
+ *  - `REFILL_V3_FILL_READY_OUTCOMES` and the closed reason/receipt/result types;
+ *  - `REFILL_V3_FILL_READY_REASON_CODES`, which EXTENDS the world-state code
+ *    vocabulary rather than forking it;
+ *  - `decodeRefillV3FillReadyResult`, the ONE unknown-value decoder; and
+ *  - `REFILL_V3_FILL_READY_OUTPUT_SCHEMA`, derived from the same closed
+ *    vocabulary so the central MCP envelope can always emit matching
+ *    `structuredContent`.
+ *
+ * It lives inside `@sellable/mcp` and compiles to
+ * `dist/tools/refill-v3-fill-ready-contract.js` plus `.d.ts`, so both the app
+ * service and the Plan 08 tool wrapper IMPORT these exact exports. Nothing here
+ * imports app `src/**`, and no consumer may copy the types, outcomes, decoder,
+ * or schema.
+ *
+ * Decoding rules: hand-rolled type guards plus as-const JSON-Schema literals,
+ * strict inbound, and fail-closed. Unlike the world-state observation, a
+ * fill-ready result describes a MUTATION, so an unrecognized member is rejected
+ * outright instead of being narrowed to a tolerant projection: a malformed
+ * mutation receipt must never be read as a partial success.
+ */
+import { REFILL_V3_WORLD_STATE_FORBIDDEN_LEAK_KEYS, REFILL_V3_WORLD_STATE_LANES, REFILL_V3_WORLD_STATE_REASON_CODES, } from "./refill-v3-world-state-contract.js";
+// ───────────────────────────────────────────────────────────────────────────
+// Closed output vocabularies
+// ───────────────────────────────────────────────────────────────────────────
+export const REFILL_V3_FILL_READY_SCHEMA_NAMESPACE = "refill_v3_fill_ready";
+export const REFILL_V3_FILL_READY_SCHEMA_MAJOR = 1;
+export const REFILL_V3_FILL_READY_SCHEMA_VERSION = "refill_v3_fill_ready.v1.0";
+/** The five terminal outcomes. There is deliberately no sixth member. */
+export const REFILL_V3_FILL_READY_OUTCOMES = [
+    "scheduled",
+    "partially_scheduled",
+    "awaiting_scheduler",
+    "campaign_exhausted",
+    "blocked",
+];
+/**
+ * Codes emitted ONLY by the fill-ready service. They EXTEND the world-state
+ * vocabulary; every one gets a row in the single exported code -> classification
+ * map, so retryability stays a property of the CODE rather than of a call site.
+ */
+export const REFILL_V3_FILL_READY_ONLY_REASON_CODES = [
+    /** No usable positive requested count could be derived. */
+    "zero_requested_count",
+    /** The caller key was reused with a changed exact scope. */
+    "idempotency_scope_mismatch",
+    /** Placement outcome unknown; never blindly retried under the same key. */
+    "uncertain_outcome",
+    /** A concurrent writer consumed the cohort under another sender. */
+    "placed_under_other_sender",
+    /** A concurrent writer consumed the cohort on another target date. */
+    "placed_off_target_date",
+    /** The paid-credit receipt is invalid at the schedule gate. */
+    "paid_inmail_credit_receipt_invalid",
+    /** A bounded poll budget expired with the stored receipt unchanged. */
+    "awaiting_external_change",
+    "approval_authority_invalid",
+    /**
+     * Another message-preparation job currently owns this campaign's approvals.
+     * That is a WAIT, not a configuration defect: the same request succeeds once
+     * the other preparation finishes (Plan 12, ARD-FINDING-5).
+     */
+    "approval_authority_in_flight",
+    "approval_dispatch_incomplete",
+    "ready_cells_unavailable",
+    "sender_affinity_conflict",
+    "scheduler_target_omitted",
+    "scheduler_failed",
+    "receipt_readback_mismatch",
+];
+/** The complete closed fill-ready code vocabulary. */
+export const REFILL_V3_FILL_READY_REASON_CODES = [
+    ...REFILL_V3_WORLD_STATE_REASON_CODES,
+    ...REFILL_V3_FILL_READY_ONLY_REASON_CODES,
+];
+/**
+ * Why a request was reduced. A clamp is NEVER silent: whenever
+ * `requestedCount !== appliedCount` the result carries this basis, except for
+ * the two concurrent-consumption codes where the shortfall is not a clamp at
+ * all and labelling it one would be a false statement.
+ */
+export const REFILL_V3_FILL_READY_CLAMP_BASES = [
+    "capacity",
+    "supply",
+    "candidates",
+];
+/** Codes for which a shortfall is concurrent consumption, never a clamp. */
+export const REFILL_V3_FILL_READY_CLAMP_EXEMPT_CODES = [
+    "placed_under_other_sender",
+    "placed_off_target_date",
+];
+/** Reused verbatim: a mutation result must not leak identity or internals. */
+export const REFILL_V3_FILL_READY_FORBIDDEN_LEAK_KEYS = REFILL_V3_WORLD_STATE_FORBIDDEN_LEAK_KEYS;
+export const REFILL_V3_FILL_READY_RESULT_KEYS = [
+    "outcome",
+    "requestedCount",
+    "appliedCount",
+    "approvedCount",
+    "scheduledCount",
+    "reason",
+    "clamp",
+    "receipt",
+    "pollKey",
+];
+// ───────────────────────────────────────────────────────────────────────────
+// Public output schema
+// ───────────────────────────────────────────────────────────────────────────
+const COUNT_SCHEMA = { type: "integer", minimum: 0 };
+const FILL_READY_REASON_SCHEMA = {
+    type: ["object", "null"],
+    additionalProperties: false,
+    required: ["code", "message", "retryable"],
+    properties: {
+        code: { type: "string", enum: [...REFILL_V3_FILL_READY_REASON_CODES] },
+        message: { type: "string" },
+        retryable: { type: "boolean" },
+        resumeAt: { type: "string" },
+    },
+};
+const FILL_READY_CLAMP_SCHEMA = {
+    type: ["object", "null"],
+    additionalProperties: false,
+    required: ["basis", "requested", "limit"],
+    properties: {
+        basis: { type: "string", enum: [...REFILL_V3_FILL_READY_CLAMP_BASES] },
+        requested: COUNT_SCHEMA,
+        limit: COUNT_SCHEMA,
+    },
+};
+const FILL_READY_RECEIPT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["idempotencyKey", "campaignId", "senderId", "targetDate"],
+    properties: {
+        idempotencyKey: { type: "string", minLength: 1 },
+        campaignId: { type: "string", minLength: 1 },
+        senderId: { type: "string", minLength: 1 },
+        targetDate: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+    },
+};
+/**
+ * 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. Every boundary the decoder closes is closed here too.
+ */
+export const REFILL_V3_FILL_READY_OUTPUT_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: [...REFILL_V3_FILL_READY_RESULT_KEYS],
+    properties: {
+        outcome: { type: "string", enum: [...REFILL_V3_FILL_READY_OUTCOMES] },
+        requestedCount: COUNT_SCHEMA,
+        appliedCount: COUNT_SCHEMA,
+        approvedCount: COUNT_SCHEMA,
+        scheduledCount: COUNT_SCHEMA,
+        reason: FILL_READY_REASON_SCHEMA,
+        clamp: FILL_READY_CLAMP_SCHEMA,
+        receipt: FILL_READY_RECEIPT_SCHEMA,
+        pollKey: { type: ["string", "null"] },
+    },
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Sole unknown-value decoder
+// ───────────────────────────────────────────────────────────────────────────
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function isOneOfFillReady(value, allowed) {
+    return (typeof value === "string" && allowed.includes(value));
+}
+/** Transport-only key the encoder adds. It is stripped, never business. */
+const FILL_READY_TRANSPORT_KEYS = ["schemaVersion"];
+const CANONICAL_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function onlyKeys(record, allowed) {
+    return Object.keys(record).every((key) => allowed.includes(key));
+}
+function nonNegativeCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function decodeFillReadyReason(value) {
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        return "invalid";
+    if (!onlyKeys(value, ["code", "message", "retryable", "resumeAt"]) ||
+        !isOneOfFillReady(value.code, REFILL_V3_FILL_READY_REASON_CODES) ||
+        typeof value.message !== "string" ||
+        typeof value.retryable !== "boolean") {
+        return "invalid";
+    }
+    if (value.resumeAt !== undefined && !nonEmptyString(value.resumeAt)) {
+        return "invalid";
+    }
+    return {
+        code: value.code,
+        message: value.message,
+        retryable: value.retryable,
+        ...(value.resumeAt === undefined
+            ? {}
+            : { resumeAt: value.resumeAt }),
+    };
+}
+function decodeFillReadyClamp(value) {
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        return "invalid";
+    if (!onlyKeys(value, ["basis", "requested", "limit"]) ||
+        !isOneOfFillReady(value.basis, REFILL_V3_FILL_READY_CLAMP_BASES) ||
+        !nonNegativeCount(value.requested) ||
+        !nonNegativeCount(value.limit)) {
+        return "invalid";
+    }
+    return {
+        basis: value.basis,
+        requested: value.requested,
+        limit: value.limit,
+    };
+}
+function decodeFillReadyReceipt(value) {
+    if (!isRecord(value))
+        return null;
+    const keys = ["idempotencyKey", "campaignId", "senderId", "targetDate"];
+    if (!onlyKeys(value, keys))
+        return null;
+    if (keys.some((key) => !nonEmptyString(value[key])))
+        return null;
+    if (!CANONICAL_DATE.test(value.targetDate))
+        return null;
+    return {
+        idempotencyKey: value.idempotencyKey,
+        campaignId: value.campaignId,
+        senderId: value.senderId,
+        targetDate: value.targetDate,
+    };
+}
+/**
+ * Sole unknown-value decoder for the public result. STRICT and FAIL-CLOSED: a
+ * fill-ready result describes a MUTATION, so an unknown key, a malformed count,
+ * a broken count invariant, or a leaked identity rejects the whole value rather
+ * than being narrowed into a confident partial success.
+ */
+export function decodeRefillV3FillReadyResult(value) {
+    if (!isRecord(value))
+        return null;
+    if (!onlyKeys(value, [
+        ...REFILL_V3_FILL_READY_RESULT_KEYS,
+        ...FILL_READY_TRANSPORT_KEYS,
+    ])) {
+        return null;
+    }
+    if (REFILL_V3_FILL_READY_RESULT_KEYS.some((key) => !(key in value))) {
+        return null;
+    }
+    if (!isOneOfFillReady(value.outcome, REFILL_V3_FILL_READY_OUTCOMES)) {
+        return null;
+    }
+    if (!nonNegativeCount(value.requestedCount) ||
+        !nonNegativeCount(value.appliedCount) ||
+        !nonNegativeCount(value.approvedCount) ||
+        !nonNegativeCount(value.scheduledCount)) {
+        return null;
+    }
+    if (value.appliedCount > value.requestedCount ||
+        value.approvedCount > value.requestedCount ||
+        value.scheduledCount > value.requestedCount) {
+        return null;
+    }
+    const reason = decodeFillReadyReason(value.reason);
+    if (reason === "invalid")
+        return null;
+    const clamp = decodeFillReadyClamp(value.clamp);
+    if (clamp === "invalid")
+        return null;
+    const receipt = decodeFillReadyReceipt(value.receipt);
+    if (!receipt)
+        return null;
+    if (value.pollKey !== null && !nonEmptyString(value.pollKey))
+        return null;
+    return {
+        outcome: value.outcome,
+        requestedCount: value.requestedCount,
+        appliedCount: value.appliedCount,
+        approvedCount: value.approvedCount,
+        scheduledCount: value.scheduledCount,
+        reason,
+        clamp,
+        receipt,
+        pollKey: value.pollKey,
+    };
+}
+/** Wire form of a decoded result. `schemaVersion` is TRANSPORT, not business. */
+export function encodeRefillV3FillReadyResult(result) {
+    return {
+        schemaVersion: REFILL_V3_FILL_READY_SCHEMA_VERSION,
+        outcome: result.outcome,
+        requestedCount: result.requestedCount,
+        appliedCount: result.appliedCount,
+        approvedCount: result.approvedCount,
+        scheduledCount: result.scheduledCount,
+        reason: result.reason
+            ? {
+                code: result.reason.code,
+                message: result.reason.message,
+                retryable: result.reason.retryable,
+                ...(result.reason.resumeAt === undefined
+                    ? {}
+                    : { resumeAt: result.reason.resumeAt }),
+            }
+            : null,
+        clamp: result.clamp ? { ...result.clamp } : null,
+        receipt: { ...result.receipt },
+        pollKey: result.pollKey,
+    };
+}
+/** The two lanes, re-exported so a consumer needs exactly one import. */
+export const REFILL_V3_FILL_READY_LANES = REFILL_V3_WORLD_STATE_LANES;

package/dist/tools/refill-v3-fill-ready.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Refill V3 fill-ready PUBLIC MCP projection (Phase 146.5 Plan 08, RV3MCP-002).
+ *
+ * This is a THIN projection over Plan 07's package-root contract and nothing
+ * else:
+ *
+ *  1. it mirrors Plan 07's closed seven-key request vocabulary so a
+ *     protocol-level validator refuses drift — including the alias `count` —
+ *     before the handler runs;
+ *  2. it applies the ONE shared explicit-workspace guard, because a bounded
+ *     mutation must name its target workspace instead of switching the shared
+ *     active workspace;
+ *  3. it posts the caller's exact values once to the authenticated route, whose
+ *     `parseRefillV3FillReadyInput` is the SOLE runtime authority; and
+ *  4. it returns only what Plan 07's SOLE closed decoder produced.
+ *
+ * It holds no approval, scheduler, cohort, clamp, or idempotency policy: the
+ * caller's replay identity is forwarded byte-for-byte, because rewriting it
+ * would silently turn a replay into a second mutation scope.
+ *
+ * A typed business blocker — including `blocked`, `campaign_exhausted`, and
+ * `awaiting_scheduler` — is a successful response VALUE and passes through
+ * VERBATIM through the central `toMcpToolResult`. Transport failure is the ONLY
+ * source of an error result (error law 6), so this module contains no branch
+ * that reads a decoded business field to decide failure.
+ *
+ * The declarative input schema is mirrored here rather than imported because the
+ * published package must never import app `src/**`. The mirror is not trusted:
+ * `tests/mcp/refill-v3/fill-ready-tool.test.ts` asserts its required key set and
+ * property set equal Plan 07's `REFILL_V3_FILL_READY_INPUT_KEYS`, so drift is a
+ * failing pin.
+ */
+import { type RefillV3FillReadyResult } from "./refill-v3-fill-ready-contract.js";
+/** The one authenticated backend boundary this projection may reach. */
+export declare const REFILL_V3_FILL_READY_ROUTE = "/api/v3/mcp/refill-v3/fill-ready";
+export declare const REFILL_V3_FILL_READY_TOOL_NAME: "refill_v3_fill_ready";
+export declare const refillV3FillReadyToolDefinitions: {
+    name: "refill_v3_fill_ready";
+    description: string;
+    inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["workspaceId", "senderId", "targetDate", "lane", "campaignId", "requestedCount", "idempotencyKey"];
+        readonly properties: {
+            readonly workspaceId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Explicit request-scoped workspace id. Pass this instead of switching the shared active workspace.";
+            };
+            readonly senderId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Exact Sender.id. Never pass a sender name.";
+            };
+            readonly targetDate: {
+                readonly type: "string";
+                readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                readonly description: "The sender-local calendar date to fill, YYYY-MM-DD.";
+            };
+            readonly lane: {
+                readonly type: "string";
+                readonly enum: readonly ["connection_invite", "paid_inmail"];
+                readonly description: "The exact lane to fill. The two lanes are independent.";
+            };
+            readonly campaignId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Exact id of the ONE campaign this request may touch, chosen from the world-state options.";
+            };
+            readonly requestedCount: {
+                readonly type: "integer";
+                readonly minimum: 0;
+                readonly description: "How many actions to place. The backend clamps it to real capacity, supply, and clean candidates and names the binding limit; 0 is a valid bounded no-op.";
+            };
+            readonly idempotencyKey: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Caller replay identity. Reuse the SAME key to retry one request; a new key means a new placement scope.";
+            };
+        };
+    };
+    outputSchema: Readonly<{
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["outcome", "requestedCount", "appliedCount", "approvedCount", "scheduledCount", "reason", "clamp", "receipt", "pollKey"];
+        readonly properties: {
+            readonly outcome: {
+                readonly type: "string";
+                readonly enum: readonly ["scheduled", "partially_scheduled", "awaiting_scheduler", "campaign_exhausted", "blocked"];
+            };
+            readonly requestedCount: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+            readonly appliedCount: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+            readonly approvedCount: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+            readonly scheduledCount: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+            readonly reason: {
+                readonly type: readonly ["object", "null"];
+                readonly additionalProperties: false;
+                readonly required: readonly ["code", "message", "retryable"];
+                readonly properties: {
+                    readonly code: {
+                        readonly type: "string";
+                        readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight", "zero_requested_count", "idempotency_scope_mismatch", "uncertain_outcome", "placed_under_other_sender", "placed_off_target_date", "paid_inmail_credit_receipt_invalid", "awaiting_external_change", "approval_authority_invalid", "approval_authority_in_flight", "approval_dispatch_incomplete", "ready_cells_unavailable", "sender_affinity_conflict", "scheduler_target_omitted", "scheduler_failed", "receipt_readback_mismatch"];
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                    };
+                    readonly retryable: {
+                        readonly type: "boolean";
+                    };
+                    readonly resumeAt: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly clamp: {
+                readonly type: readonly ["object", "null"];
+                readonly additionalProperties: false;
+                readonly required: readonly ["basis", "requested", "limit"];
+                readonly properties: {
+                    readonly basis: {
+                        readonly type: "string";
+                        readonly enum: readonly ["capacity", "supply", "candidates"];
+                    };
+                    readonly requested: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly limit: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                };
+            };
+            readonly receipt: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["idempotencyKey", "campaignId", "senderId", "targetDate"];
+                readonly properties: {
+                    readonly idempotencyKey: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly campaignId: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly senderId: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly targetDate: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                };
+            };
+            readonly pollKey: {
+                readonly type: readonly ["string", "null"];
+            };
+        };
+    }>;
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}[];
+export type RefillV3FillReadyToolInput = {
+    workspaceId?: string;
+    senderId?: string;
+    targetDate?: string;
+    lane?: string;
+    campaignId?: string;
+    requestedCount?: number;
+    idempotencyKey?: string;
+};
+/**
+ * Place ready outreach for ONE explicit workspace scope.
+ *
+ * The returned value is the plain canonical business receipt. Every failure that
+ * is NOT a decoded business fact — a refused request, an authorization refusal,
+ * an infrastructure failure, or a response the sole decoder rejects — propagates
+ * as a thrown transport error and can never become a plausible mutation receipt.
+ */
+export declare function fillRefillV3ReadyTool(input: RefillV3FillReadyToolInput): Promise<RefillV3FillReadyResult>;

package/dist/tools/refill-v3-fill-ready.js

@@ -0,0 +1,136 @@
+/**
+ * Refill V3 fill-ready PUBLIC MCP projection (Phase 146.5 Plan 08, RV3MCP-002).
+ *
+ * This is a THIN projection over Plan 07's package-root contract and nothing
+ * else:
+ *
+ *  1. it mirrors Plan 07's closed seven-key request vocabulary so a
+ *     protocol-level validator refuses drift — including the alias `count` —
+ *     before the handler runs;
+ *  2. it applies the ONE shared explicit-workspace guard, because a bounded
+ *     mutation must name its target workspace instead of switching the shared
+ *     active workspace;
+ *  3. it posts the caller's exact values once to the authenticated route, whose
+ *     `parseRefillV3FillReadyInput` is the SOLE runtime authority; and
+ *  4. it returns only what Plan 07's SOLE closed decoder produced.
+ *
+ * It holds no approval, scheduler, cohort, clamp, or idempotency policy: the
+ * caller's replay identity is forwarded byte-for-byte, because rewriting it
+ * would silently turn a replay into a second mutation scope.
+ *
+ * A typed business blocker — including `blocked`, `campaign_exhausted`, and
+ * `awaiting_scheduler` — is a successful response VALUE and passes through
+ * VERBATIM through the central `toMcpToolResult`. Transport failure is the ONLY
+ * source of an error result (error law 6), so this module contains no branch
+ * that reads a decoded business field to decide failure.
+ *
+ * The declarative input schema is mirrored here rather than imported because the
+ * published package must never import app `src/**`. The mirror is not trusted:
+ * `tests/mcp/refill-v3/fill-ready-tool.test.ts` asserts its required key set and
+ * property set equal Plan 07's `REFILL_V3_FILL_READY_INPUT_KEYS`, so drift is a
+ * failing pin.
+ */
+import { getApi } from "../api.js";
+import { decodeRefillV3FillReadyResult, REFILL_V3_FILL_READY_LANES, REFILL_V3_FILL_READY_OUTPUT_SCHEMA, } from "./refill-v3-fill-ready-contract.js";
+import { normalizeExplicitWorkspaceId, workspaceRequestOptions, } from "./workspace-context.js";
+/** The one authenticated backend boundary this projection may reach. */
+export const REFILL_V3_FILL_READY_ROUTE = "/api/v3/mcp/refill-v3/fill-ready";
+export const REFILL_V3_FILL_READY_TOOL_NAME = "refill_v3_fill_ready";
+/** Declarative mirror of Plan 07's closed seven-key request vocabulary. */
+const REFILL_V3_FILL_READY_TOOL_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+        "workspaceId",
+        "senderId",
+        "targetDate",
+        "lane",
+        "campaignId",
+        "requestedCount",
+        "idempotencyKey",
+    ],
+    properties: {
+        workspaceId: {
+            type: "string",
+            minLength: 1,
+            description: "Explicit request-scoped workspace id. Pass this instead of switching the shared active workspace.",
+        },
+        senderId: {
+            type: "string",
+            minLength: 1,
+            description: "Exact Sender.id. Never pass a sender name.",
+        },
+        targetDate: {
+            type: "string",
+            pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+            description: "The sender-local calendar date to fill, YYYY-MM-DD.",
+        },
+        lane: {
+            type: "string",
+            enum: [...REFILL_V3_FILL_READY_LANES],
+            description: "The exact lane to fill. The two lanes are independent.",
+        },
+        campaignId: {
+            type: "string",
+            minLength: 1,
+            description: "Exact id of the ONE campaign this request may touch, chosen from the world-state options.",
+        },
+        requestedCount: {
+            type: "integer",
+            minimum: 0,
+            description: "How many actions to place. The backend clamps it to real capacity, supply, and clean candidates and names the binding limit; 0 is a valid bounded no-op.",
+        },
+        idempotencyKey: {
+            type: "string",
+            minLength: 1,
+            description: "Caller replay identity. Reuse the SAME key to retry one request; a new key means a new placement scope.",
+        },
+    },
+};
+export const refillV3FillReadyToolDefinitions = [
+    {
+        name: REFILL_V3_FILL_READY_TOOL_NAME,
+        description: "Place just-in-time ready outreach for exactly one workspace, sender, sender-local date, lane, and campaign. It MUTATES product state: within the exact bounded cohort it approves prepared rows that still need approval, assigns sender affinity, and schedules ready actions through the on-demand scheduler. The two lanes connection_invite and paid_inmail are independent and a paid request re-attests paid-InMail credits immediately before placement. It never creates rows, imports leads, generates messages, starts or launches a campaign, changes thresholds, or sends anything directly. Every attempt is bounded by the required idempotencyKey: reuse the SAME idempotencyKey to retry one request, and expect a closed terminal outcome of scheduled, partially_scheduled, awaiting_scheduler, campaign_exhausted, or blocked, each with a typed reason and named clamp. An awaiting_scheduler answer carries a pollKey whose only valid follow-up is a status lookup, never a second placement.",
+        inputSchema: REFILL_V3_FILL_READY_TOOL_INPUT_SCHEMA,
+        outputSchema: REFILL_V3_FILL_READY_OUTPUT_SCHEMA,
+        annotations: {
+            title: "Refill V3 Fill Ready",
+            readOnlyHint: false,
+            // Destructive in the PRODUCT-STATE sense: approval and scheduling change
+            // durable customer state that a caller cannot undo from this tool.
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+];
+/**
+ * Place ready outreach for ONE explicit workspace scope.
+ *
+ * The returned value is the plain canonical business receipt. Every failure that
+ * is NOT a decoded business fact — a refused request, an authorization refusal,
+ * an infrastructure failure, or a response the sole decoder rejects — propagates
+ * as a thrown transport error and can never become a plausible mutation receipt.
+ */
+export async function fillRefillV3ReadyTool(input) {
+    const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
+    if (!workspaceId) {
+        throw new Error("Explicit workspaceId is required for refill_v3_fill_ready. Name the target workspace instead of switching the shared active workspace.");
+    }
+    const raw = await getApi().post(REFILL_V3_FILL_READY_ROUTE, {
+        workspaceId,
+        senderId: input.senderId,
+        targetDate: input.targetDate,
+        lane: input.lane,
+        campaignId: input.campaignId,
+        requestedCount: input.requestedCount,
+        // Forwarded byte-for-byte: rewriting the caller's replay identity would
+        // turn a retry into a second placement scope.
+        idempotencyKey: input.idempotencyKey,
+    }, workspaceRequestOptions(workspaceId));
+    const decoded = decodeRefillV3FillReadyResult(raw);
+    if (decoded === null) {
+        throw new Error("The Refill V3 fill-ready response failed the published result contract.");
+    }
+    return decoded;
+}