@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-edit-selected-campaign-contract.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Refill V3 selected-campaign EDIT result PACKAGE seam (Phase 146.5 Plan 09 T2,
+ * RV3EDIT-001).
+ *
+ * `refill_v3_edit_selected_campaign` is the fourth public V3 tool, so it needs a
+ * package-reachable result contract for the same reason the other three do: the
+ * INSTALLED client decodes the wire body, and a wrapper that declares its own
+ * shape drifts from the backend the moment either side changes.
+ *
+ * It is dependency-free apart from the sibling packet seam, which owns every
+ * shared vocabulary this module consumes. In particular the terminality question
+ * ("is there simply nothing left to edit?") is answered by the SHARED
+ * `REFILL_V3_EXHAUSTION_PREDICATE` rather than by a second truth table here.
+ *
+ * Constraints (`A02-NO-ZOD`): no app `src/**` import, no validation library,
+ * hand-rolled guards plus as-const JSON-Schema literals.
+ */
+import { type RefillV3ExhaustionInput, type RefillV3ExhaustionVerdict } from "./refill-v3-attention-packet-contract.js";
+/**
+ * The THREE closed edit actions, DERIVED from the shared attention-action
+ * vocabulary by suffix selection so this module can never grow a fourth action
+ * the AI seam does not know about.
+ *
+ * Rerun, same-meaning regeneration, and the guarded rubric trial are
+ * deliberately ABSENT: they are not edit-tool variants and keep their existing
+ * deterministic owners.
+ */
+export declare const REFILL_V3_EDIT_ACTIONS: RefillV3CampaignEditAction[];
+export type RefillV3CampaignEditAction = "repair_campaign_config" | "patch_filter_criteria" | "patch_source_criteria";
+export declare const REFILL_V3_EDIT_OUTCOMES: readonly ["applied", "replayed", "rolled_back", "blocked"];
+export type RefillV3CampaignEditOutcome = (typeof REFILL_V3_EDIT_OUTCOMES)[number];
+/**
+ * Every closed BUSINESS refusal. A member of this list is an HTTP 200 result
+ * with its typed reason; an infrastructure failure is non-2xx and never appears
+ * here, because a caller that reads `blocked` from a database outage will edit
+ * the campaign to work around a database problem.
+ */
+export declare const REFILL_V3_EDIT_REASONS: readonly ["cross_workspace_scope", "foreign_campaign_scope", "foreign_table_scope", "stale_campaign_version", "stale_evidence_fingerprint", "stale_prior_fingerprint", "disallowed_action", "protected_field", "value_shape_mismatch", "protected_invariant_weakened", "health_evidence_not_editable", "reobservation_scope_missing", "idempotency_input_changed", "no_edit_available", "uncertain_delegated_effect"];
+export type RefillV3CampaignEditReason = (typeof REFILL_V3_EDIT_REASONS)[number];
+export declare const REFILL_V3_EDIT_REPLAY_STATES: readonly ["first", "exact_replay", "not_applicable"];
+export type RefillV3CampaignEditReplayState = (typeof REFILL_V3_EDIT_REPLAY_STATES)[number];
+/**
+ * Fields this authority may never touch, whatever the action. `update_campaign`
+ * accepts every one of them; the point of this wrapper is that it does not.
+ */
+export declare const REFILL_V3_EDIT_PROTECTED_FIELDS: readonly ["name", "campaignBrief", "offerPositioning", "senderIds", "currentStep", "currentStepTransition", "clearCurrentStepIfMatches", "interactionMode", "flowVersion", "leadSourceProvider", "selectedLeadListId", "rubric", "watchNarration"];
+export type RefillV3EditProtectedField = (typeof REFILL_V3_EDIT_PROTECTED_FIELDS)[number];
+/**
+ * The MINIMAL per-action field allowlist. It is deliberately small: a field
+ * enters it only with evidence that a selected packet can prove the delta, and
+ * an action/field pair outside this table is `value_shape_mismatch`.
+ */
+export declare const REFILL_V3_EDIT_FIELD_ALLOWLIST: Readonly<Record<RefillV3CampaignEditAction, readonly string[]>>;
+export declare const REFILL_V3_EDIT_SCHEMA_NAMESPACE: "refill_v3_campaign_edit";
+export declare const REFILL_V3_EDIT_SCHEMA_MAJOR = 1;
+export declare const REFILL_V3_EDIT_SCHEMA_VERSION: "refill_v3_campaign_edit.v1.0";
+export type RefillV3CampaignEditRollback = {
+    available: boolean;
+    input: Record<string, unknown> | null;
+    result: string | null;
+};
+export type RefillV3CampaignEditReceipt = {
+    scopeEcho: string;
+    idempotencyKey: string;
+    effectKey: string;
+    beforeFingerprint: string;
+    afterFingerprint: string;
+    changedFields: string[];
+    replayState: RefillV3CampaignEditReplayState;
+    rollback: RefillV3CampaignEditRollback;
+};
+export type RefillV3CampaignEditReobservation = {
+    senderId: string;
+    date: string;
+    required: true;
+    lanes: string[];
+};
+export type RefillV3CampaignEditResult = {
+    outcome: RefillV3CampaignEditOutcome;
+    action: RefillV3CampaignEditAction;
+    reason: RefillV3CampaignEditReason | null;
+    receipt: RefillV3CampaignEditReceipt | null;
+    reobservation: RefillV3CampaignEditReobservation | null;
+    detail: string;
+};
+export declare const REFILL_V3_CAMPAIGN_EDIT_OUTPUT_SCHEMA: Readonly<{
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schemaVersion", "outcome", "action", "reason", "receipt", "reobservation", "detail"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly type: "string";
+            readonly const: "refill_v3_campaign_edit.v1.0";
+        };
+        readonly outcome: {
+            readonly type: "string";
+            readonly enum: readonly ["applied", "replayed", "rolled_back", "blocked"];
+        };
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly RefillV3CampaignEditAction[];
+        };
+        readonly reason: {
+            readonly type: readonly ["string", "null"];
+            readonly enum: readonly ["cross_workspace_scope", "foreign_campaign_scope", "foreign_table_scope", "stale_campaign_version", "stale_evidence_fingerprint", "stale_prior_fingerprint", "disallowed_action", "protected_field", "value_shape_mismatch", "protected_invariant_weakened", "health_evidence_not_editable", "reobservation_scope_missing", "idempotency_input_changed", "no_edit_available", "uncertain_delegated_effect", null];
+        };
+        readonly receipt: {
+            readonly type: readonly ["object", "null"];
+            readonly additionalProperties: false;
+            readonly required: readonly ["scopeEcho", "idempotencyKey", "effectKey", "beforeFingerprint", "afterFingerprint", "changedFields", "replayState", "rollback"];
+            readonly properties: {
+                readonly scopeEcho: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly idempotencyKey: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly effectKey: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly beforeFingerprint: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly afterFingerprint: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly changedFields: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                };
+                readonly replayState: {
+                    readonly type: "string";
+                    readonly enum: readonly ["first", "exact_replay", "not_applicable"];
+                };
+                readonly rollback: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["available", "input", "result"];
+                    readonly properties: {
+                        readonly available: {
+                            readonly type: "boolean";
+                        };
+                        readonly input: {
+                            readonly type: readonly ["object", "null"];
+                        };
+                        readonly result: {
+                            readonly type: readonly ["string", "null"];
+                        };
+                    };
+                };
+            };
+        };
+        readonly reobservation: {
+            readonly type: readonly ["object", "null"];
+            readonly additionalProperties: false;
+            readonly required: readonly ["senderId", "date", "required", "lanes"];
+            readonly properties: {
+                readonly senderId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly date: {
+                    readonly type: "string";
+                    readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                };
+                readonly required: {
+                    readonly type: "boolean";
+                    readonly const: true;
+                };
+                readonly lanes: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                };
+            };
+        };
+        readonly detail: {
+            readonly type: "string";
+        };
+    };
+}>;
+/**
+ * Sole unknown-value decoder for the edit result.
+ *
+ * Strict-in, lossless. `null` means "not this contract" — including an
+ * infrastructure error envelope, a raw campaign row leak, and an incompatible
+ * schema major — so a caller can never mistake an outage for a business answer.
+ */
+export declare function decodeRefillV3CampaignEditResult(value: unknown): RefillV3CampaignEditResult | null;
+export declare function encodeRefillV3CampaignEditResult(result: RefillV3CampaignEditResult): Record<string, unknown>;
+/**
+ * "Nothing left to edit" is a TERMINALITY claim, and terminality has exactly one
+ * owner in this phase. Routing it through the shared predicate is what stops the
+ * edit surface from growing a second, quietly divergent exhaustion rule.
+ */
+export declare function refillV3EditTerminalityVerdict(evidence: RefillV3ExhaustionInput): RefillV3ExhaustionVerdict;
+/** Transport gate, shared with every sibling contract. */
+export declare function resolveRefillV3EditSchemaVersion(value: unknown): import("./refill-v3-attention-packet-contract.js").RefillV3SchemaVersionSupport;

package/dist/tools/refill-v3-edit-selected-campaign-contract.js

@@ -0,0 +1,351 @@
+/**
+ * Refill V3 selected-campaign EDIT result PACKAGE seam (Phase 146.5 Plan 09 T2,
+ * RV3EDIT-001).
+ *
+ * `refill_v3_edit_selected_campaign` is the fourth public V3 tool, so it needs a
+ * package-reachable result contract for the same reason the other three do: the
+ * INSTALLED client decodes the wire body, and a wrapper that declares its own
+ * shape drifts from the backend the moment either side changes.
+ *
+ * It is dependency-free apart from the sibling packet seam, which owns every
+ * shared vocabulary this module consumes. In particular the terminality question
+ * ("is there simply nothing left to edit?") is answered by the SHARED
+ * `REFILL_V3_EXHAUSTION_PREDICATE` rather than by a second truth table here.
+ *
+ * Constraints (`A02-NO-ZOD`): no app `src/**` import, no validation library,
+ * hand-rolled guards plus as-const JSON-Schema literals.
+ */
+import { REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS, REFILL_V3_EXHAUSTION_PREDICATE, resolveRefillV3SchemaVersion, } from "./refill-v3-attention-packet-contract.js";
+// ───────────────────────────────────────────────────────────────────────────
+// Closed vocabularies
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The THREE closed edit actions, DERIVED from the shared attention-action
+ * vocabulary by suffix selection so this module can never grow a fourth action
+ * the AI seam does not know about.
+ *
+ * Rerun, same-meaning regeneration, and the guarded rubric trial are
+ * deliberately ABSENT: they are not edit-tool variants and keep their existing
+ * deterministic owners.
+ */
+export const REFILL_V3_EDIT_ACTIONS = REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS.filter((action) => action === "repair_campaign_config" ||
+    action === "patch_filter_criteria" ||
+    action === "patch_source_criteria");
+export const REFILL_V3_EDIT_OUTCOMES = [
+    "applied",
+    "replayed",
+    "rolled_back",
+    "blocked",
+];
+/**
+ * Every closed BUSINESS refusal. A member of this list is an HTTP 200 result
+ * with its typed reason; an infrastructure failure is non-2xx and never appears
+ * here, because a caller that reads `blocked` from a database outage will edit
+ * the campaign to work around a database problem.
+ */
+export const REFILL_V3_EDIT_REASONS = [
+    "cross_workspace_scope",
+    "foreign_campaign_scope",
+    "foreign_table_scope",
+    "stale_campaign_version",
+    "stale_evidence_fingerprint",
+    "stale_prior_fingerprint",
+    "disallowed_action",
+    "protected_field",
+    "value_shape_mismatch",
+    "protected_invariant_weakened",
+    "health_evidence_not_editable",
+    "reobservation_scope_missing",
+    "idempotency_input_changed",
+    "no_edit_available",
+    "uncertain_delegated_effect",
+];
+export const REFILL_V3_EDIT_REPLAY_STATES = [
+    "first",
+    "exact_replay",
+    "not_applicable",
+];
+/**
+ * Fields this authority may never touch, whatever the action. `update_campaign`
+ * accepts every one of them; the point of this wrapper is that it does not.
+ */
+export const REFILL_V3_EDIT_PROTECTED_FIELDS = [
+    "name",
+    "campaignBrief",
+    "offerPositioning",
+    "senderIds",
+    "currentStep",
+    "currentStepTransition",
+    "clearCurrentStepIfMatches",
+    "interactionMode",
+    "flowVersion",
+    "leadSourceProvider",
+    "selectedLeadListId",
+    "rubric",
+    "watchNarration",
+];
+/**
+ * The MINIMAL per-action field allowlist. It is deliberately small: a field
+ * enters it only with evidence that a selected packet can prove the delta, and
+ * an action/field pair outside this table is `value_shape_mismatch`.
+ */
+export const REFILL_V3_EDIT_FIELD_ALLOWLIST = Object.freeze({
+    repair_campaign_config: ["enableICPFilters", "useMessagingTemplate"],
+    patch_filter_criteria: ["enableICPFilters"],
+    patch_source_criteria: ["leadSourceType"],
+});
+export const REFILL_V3_EDIT_SCHEMA_NAMESPACE = "refill_v3_campaign_edit";
+export const REFILL_V3_EDIT_SCHEMA_MAJOR = 1;
+export const REFILL_V3_EDIT_SCHEMA_VERSION = "refill_v3_campaign_edit.v1.0";
+// ───────────────────────────────────────────────────────────────────────────
+// Output schema
+// ───────────────────────────────────────────────────────────────────────────
+export const REFILL_V3_CAMPAIGN_EDIT_OUTPUT_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: [
+        "schemaVersion",
+        "outcome",
+        "action",
+        "reason",
+        "receipt",
+        "reobservation",
+        "detail",
+    ],
+    properties: {
+        schemaVersion: { type: "string", const: REFILL_V3_EDIT_SCHEMA_VERSION },
+        outcome: { type: "string", enum: [...REFILL_V3_EDIT_OUTCOMES] },
+        action: { type: "string", enum: [...REFILL_V3_EDIT_ACTIONS] },
+        reason: {
+            type: ["string", "null"],
+            enum: [...REFILL_V3_EDIT_REASONS, null],
+        },
+        receipt: {
+            type: ["object", "null"],
+            additionalProperties: false,
+            required: [
+                "scopeEcho",
+                "idempotencyKey",
+                "effectKey",
+                "beforeFingerprint",
+                "afterFingerprint",
+                "changedFields",
+                "replayState",
+                "rollback",
+            ],
+            properties: {
+                scopeEcho: { type: "string", minLength: 1 },
+                idempotencyKey: { type: "string", minLength: 1 },
+                effectKey: { type: "string", minLength: 1 },
+                beforeFingerprint: { type: "string", minLength: 1 },
+                afterFingerprint: { type: "string", minLength: 1 },
+                changedFields: {
+                    type: "array",
+                    items: { type: "string", minLength: 1 },
+                },
+                replayState: {
+                    type: "string",
+                    enum: [...REFILL_V3_EDIT_REPLAY_STATES],
+                },
+                rollback: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["available", "input", "result"],
+                    properties: {
+                        available: { type: "boolean" },
+                        input: { type: ["object", "null"] },
+                        result: { type: ["string", "null"] },
+                    },
+                },
+            },
+        },
+        reobservation: {
+            type: ["object", "null"],
+            additionalProperties: false,
+            required: ["senderId", "date", "required", "lanes"],
+            properties: {
+                senderId: { type: "string", minLength: 1 },
+                date: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+                required: { type: "boolean", const: true },
+                lanes: { type: "array", items: { type: "string", minLength: 1 } },
+            },
+        },
+        detail: { type: "string" },
+    },
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Decoding
+// ───────────────────────────────────────────────────────────────────────────
+const RESULT_KEYS = new Set([
+    "schemaVersion",
+    "outcome",
+    "action",
+    "reason",
+    "receipt",
+    "reobservation",
+    "detail",
+]);
+const RECEIPT_KEYS = new Set([
+    "scopeEcho",
+    "idempotencyKey",
+    "effectKey",
+    "beforeFingerprint",
+    "afterFingerprint",
+    "changedFields",
+    "replayState",
+    "rollback",
+]);
+const ROLLBACK_KEYS = new Set(["available", "input", "result"]);
+const REOBSERVATION_KEYS = new Set(["senderId", "date", "required", "lanes"]);
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isOneOf(value, options) {
+    return (typeof value === "string" && options.includes(value));
+}
+function decodeRollback(value) {
+    if (!isRecord(value))
+        return null;
+    if (Object.keys(value).some((key) => !ROLLBACK_KEYS.has(key)))
+        return null;
+    if (typeof value.available !== "boolean")
+        return null;
+    if (!(value.input === null || isRecord(value.input)))
+        return null;
+    if (!(value.result === null || isNonEmptyString(value.result)))
+        return null;
+    return {
+        available: value.available,
+        input: value.input,
+        result: value.result,
+    };
+}
+function decodeReceipt(value) {
+    if (!isRecord(value))
+        return null;
+    if (Object.keys(value).some((key) => !RECEIPT_KEYS.has(key)))
+        return null;
+    for (const key of RECEIPT_KEYS) {
+        if (!(key in value))
+            return null;
+    }
+    if (!isNonEmptyString(value.scopeEcho) ||
+        !isNonEmptyString(value.idempotencyKey) ||
+        !isNonEmptyString(value.effectKey) ||
+        !isNonEmptyString(value.beforeFingerprint) ||
+        !isNonEmptyString(value.afterFingerprint) ||
+        !isOneOf(value.replayState, REFILL_V3_EDIT_REPLAY_STATES) ||
+        !Array.isArray(value.changedFields) ||
+        !value.changedFields.every(isNonEmptyString)) {
+        return null;
+    }
+    const rollback = decodeRollback(value.rollback);
+    if (rollback === null)
+        return null;
+    return {
+        scopeEcho: value.scopeEcho,
+        idempotencyKey: value.idempotencyKey,
+        effectKey: value.effectKey,
+        beforeFingerprint: value.beforeFingerprint,
+        afterFingerprint: value.afterFingerprint,
+        changedFields: [...value.changedFields],
+        replayState: value.replayState,
+        rollback,
+    };
+}
+function decodeReobservation(value) {
+    if (!isRecord(value))
+        return null;
+    if (Object.keys(value).some((key) => !REOBSERVATION_KEYS.has(key)))
+        return null;
+    if (!isNonEmptyString(value.senderId) ||
+        typeof value.date !== "string" ||
+        !/^\d{4}-\d{2}-\d{2}$/.test(value.date) ||
+        // `required` is a CONSTANT true: an optional re-observation is not a
+        // re-observation obligation at all.
+        value.required !== true ||
+        !Array.isArray(value.lanes) ||
+        !value.lanes.every(isNonEmptyString)) {
+        return null;
+    }
+    return {
+        senderId: value.senderId,
+        date: value.date,
+        required: true,
+        lanes: [...value.lanes],
+    };
+}
+/**
+ * Sole unknown-value decoder for the edit result.
+ *
+ * Strict-in, lossless. `null` means "not this contract" — including an
+ * infrastructure error envelope, a raw campaign row leak, and an incompatible
+ * schema major — so a caller can never mistake an outage for a business answer.
+ */
+export function decodeRefillV3CampaignEditResult(value) {
+    if (!isRecord(value))
+        return null;
+    if (Object.keys(value).some((key) => !RESULT_KEYS.has(key)))
+        return null;
+    for (const key of RESULT_KEYS) {
+        if (!(key in value))
+            return null;
+    }
+    if (!resolveRefillV3EditSchemaVersion(value.schemaVersion).supported) {
+        return null;
+    }
+    if (!isOneOf(value.outcome, REFILL_V3_EDIT_OUTCOMES) ||
+        !isOneOf(value.action, REFILL_V3_EDIT_ACTIONS) ||
+        typeof value.detail !== "string") {
+        return null;
+    }
+    if (!(value.reason === null || isOneOf(value.reason, REFILL_V3_EDIT_REASONS))) {
+        return null;
+    }
+    let receipt = null;
+    if (value.receipt !== null) {
+        receipt = decodeReceipt(value.receipt);
+        if (receipt === null)
+            return null;
+    }
+    let reobservation = null;
+    if (value.reobservation !== null) {
+        reobservation = decodeReobservation(value.reobservation);
+        if (reobservation === null)
+            return null;
+    }
+    return {
+        outcome: value.outcome,
+        action: value.action,
+        reason: value.reason,
+        receipt,
+        reobservation,
+        detail: value.detail,
+    };
+}
+export function encodeRefillV3CampaignEditResult(result) {
+    return {
+        schemaVersion: REFILL_V3_EDIT_SCHEMA_VERSION,
+        outcome: result.outcome,
+        action: result.action,
+        reason: result.reason,
+        receipt: result.receipt,
+        reobservation: result.reobservation,
+        detail: result.detail,
+    };
+}
+/**
+ * "Nothing left to edit" is a TERMINALITY claim, and terminality has exactly one
+ * owner in this phase. Routing it through the shared predicate is what stops the
+ * edit surface from growing a second, quietly divergent exhaustion rule.
+ */
+export function refillV3EditTerminalityVerdict(evidence) {
+    return REFILL_V3_EXHAUSTION_PREDICATE.evaluate(evidence);
+}
+/** Transport gate, shared with every sibling contract. */
+export function resolveRefillV3EditSchemaVersion(value) {
+    return resolveRefillV3SchemaVersion(value, REFILL_V3_EDIT_SCHEMA_NAMESPACE, REFILL_V3_EDIT_SCHEMA_MAJOR);
+}