@sellable/mcp 0.1.793 → 0.1.794

package/dist/agent-tool-names.d.ts

@@ -3,14 +3,14 @@
  * manifests. Keep this free of tool implementation imports so Next can bundle
  * it; registry parity is enforced in sellable-agent-tool-policy.test.ts.
  */
-export declare const SELLABLE_MCP_TOOL_NAMES: readonly ["add_column", "add_on_demand_leads", "add_rubric_item", "add_teammate", "add_to_comment_campaign", "add_to_connection_campaign", "add_to_inmail_campaign", "archive_campaign", "attach_recommended_sequence", "attach_sequence", "bootstrap_create_campaign", "bootstrap_engage", "bootstrap_engage_multi", "bootstrap_find_leads", "bulk_enrich_with_prospeo", "calculate_linkedin_hook_preview", "cancel_campaign_message_preparation", "cancel_find_leads", "cancel_lead_import", "capture_post_idea", "check_inbox_reply_eligibility", "check_rubric", "commit_blueprint", "complete_sender_research", "confirm_harvest_job_companies", "confirm_lead_list", "confirm_prospeo_company_accounts", "copy_sender_config", "create_campaign", "create_on_demand_campaign", "create_on_demand_table", "create_workflow_table", "create_workspace", "delete_column", "delete_rubric_item", "draft_rubrics", "duplicate_campaign", "enrich_with_prospeo", "export_table_csv", "export_workspace_csv", "fetch_company", "fetch_company_posts", "fetch_linkedin_posts", "fetch_linkedin_profile", "fetch_post_engagers", "fill_campaign_horizon", "get_active_workspace", "get_auth_status", "get_campaign", "get_campaign_context", "get_campaign_framework", "get_campaign_message_preparation_status", "get_campaign_messages_preview", "get_campaign_navigation_state", "get_campaign_refill_state", "get_campaign_table_schema", "get_campaign_waterfall", "get_campaigns", "get_column_schema", "get_company_info", "get_engage_memory", "get_engage_state", "get_engaged_posts", "get_find_leads_run", "get_inbox_thread", "get_integration_connection_status", "get_linkedin_profile", "get_or_create_direct_campaign_table", "get_post_draft", "get_post_find_leads_scout_registry", "get_post_idea", "get_prospeo_credits", "get_provider_prompt", "get_published_post", "get_refill_target_plan", "get_rows", "get_rows_minimal", "get_runtime_identity", "get_scheduler_fill_capacity", "get_sender", "get_sender_routing", "get_source_scout_registry", "get_subskill_asset", "get_subskill_prompt", "get_table_rows", "get_user_posts", "get_workspace", "import_leads", "init_on_demand_sequence", "integrations_call_tool", "integrations_describe_tool", "integrations_list_tools", "list_column_types", "list_dnc_entries", "list_post_draft_iterations", "list_post_drafts", "list_post_ideas", "list_published_posts", "list_senders", "list_subskill_prompts", "list_tables", "list_workspaces", "load_csv_dnc_entries", "load_csv_domains", "load_csv_linkedin_leads", "lookup_sales_nav_filter", "mark_post_published", "migrate_flat_configs", "pause_campaign", "pause_direct_campaign", "pause_on_demand_campaign", "preflight_find_leads_provider", "prepare_campaign_ab_test", "queue_campaign_cells", "queue_cells", "record_campaign_review_batch", "record_engage_proven_search", "refill_sends", "refresh_paid_inmail_credits", "refresh_sender_engagement", "reissue_find_leads_watch_link", "render_linkedin_post_preview", "reorder_columns", "resolve_campaign_fill_route", "revise_message_template_and_rerun", "run_scheduler_sweep", "save_domain_filters", "save_hook_research", "save_post_draft", "save_rubrics", "search_apollo", "search_available_integrations", "search_engagement_posts", "search_harvest_jobs", "search_inbox_threads", "search_prospeo", "search_prospeo_companies", "search_sales_nav", "search_signals", "search_subskill_prompts", "select_campaign_cells", "select_necessary_rubrics", "select_promising_posts", "send_inbox_draft", "send_inbox_manual_reply", "set_active_workspace", "set_campaign_waterfall_order", "set_company_info", "set_engage_state", "set_engage_style_guide", "set_headline_icp_criteria", "set_sender_calendar_link", "set_sender_routing", "setup_evergreen_campaigns", "start_campaign", "start_campaign_message_preparation", "start_cli_login", "start_direct_campaign", "start_integration_connection", "start_on_demand_campaign", "update_campaign", "update_campaign_brief", "update_cell", "update_column", "update_find_leads_run", "update_inbox_draft", "update_post_draft", "update_published_post_metrics", "update_rubric_item", "upsert_engage_tracked_person", "upsert_rubric", "validate_campaign1_kickoff_handoff", "verify_table_row", "wait_for_campaign_processing", "wait_for_campaign_table_ready", "wait_for_cli_login", "wait_for_find_leads_run", "wait_for_lead_list_ready", "wait_for_rubric_results"];
+export declare const SELLABLE_MCP_TOOL_NAMES: readonly ["add_column", "add_on_demand_leads", "add_rubric_item", "add_teammate", "add_to_comment_campaign", "add_to_connection_campaign", "add_to_inmail_campaign", "archive_campaign", "attach_recommended_sequence", "attach_sequence", "bootstrap_create_campaign", "bootstrap_engage", "bootstrap_engage_multi", "bootstrap_find_leads", "bulk_enrich_with_prospeo", "calculate_linkedin_hook_preview", "cancel_campaign_message_preparation", "cancel_find_leads", "cancel_lead_import", "capture_post_idea", "check_inbox_reply_eligibility", "check_rubric", "commit_blueprint", "complete_sender_research", "confirm_harvest_job_companies", "confirm_lead_list", "confirm_prospeo_company_accounts", "copy_sender_config", "create_campaign", "create_on_demand_campaign", "create_on_demand_table", "create_workflow_table", "create_workspace", "delete_column", "delete_rubric_item", "draft_rubrics", "duplicate_campaign", "enrich_with_prospeo", "export_table_csv", "export_workspace_csv", "fetch_company", "fetch_company_posts", "fetch_linkedin_posts", "fetch_linkedin_profile", "fetch_post_engagers", "fill_campaign_horizon", "get_active_workspace", "get_auth_status", "get_campaign", "get_campaign_context", "get_campaign_framework", "get_campaign_message_preparation_status", "get_campaign_messages_preview", "get_campaign_navigation_state", "get_campaign_refill_state", "get_campaign_table_schema", "get_campaign_waterfall", "get_campaigns", "get_column_schema", "get_company_info", "get_engage_memory", "get_engage_state", "get_engaged_posts", "get_find_leads_run", "get_inbox_thread", "get_integration_connection_status", "get_linkedin_profile", "get_or_create_direct_campaign_table", "get_post_draft", "get_post_find_leads_scout_registry", "get_post_idea", "get_prospeo_credits", "get_provider_prompt", "get_published_post", "get_refill_target_plan", "get_rows", "get_rows_minimal", "get_runtime_identity", "get_scheduler_fill_capacity", "get_sender", "get_sender_routing", "get_source_scout_registry", "get_subskill_asset", "get_subskill_prompt", "get_table_rows", "get_user_posts", "get_workspace", "import_leads", "init_on_demand_sequence", "integrations_call_tool", "integrations_describe_tool", "integrations_list_tools", "list_column_types", "list_dnc_entries", "list_post_draft_iterations", "list_post_drafts", "list_post_ideas", "list_published_posts", "list_senders", "list_subskill_prompts", "list_tables", "list_workspaces", "load_csv_dnc_entries", "load_csv_domains", "load_csv_linkedin_leads", "lookup_sales_nav_filter", "mark_post_published", "migrate_flat_configs", "pause_campaign", "pause_direct_campaign", "pause_on_demand_campaign", "preflight_find_leads_provider", "prepare_campaign_ab_test", "queue_campaign_cells", "queue_cells", "record_campaign_review_batch", "record_engage_proven_search", "refill_sends", "refill_v3_advance", "refill_v3_continue", "refill_v3_edit_selected_campaign", "refill_v3_fill_ready", "refill_v3_world_state", "refresh_paid_inmail_credits", "refresh_sender_engagement", "reissue_find_leads_watch_link", "render_linkedin_post_preview", "reorder_columns", "resolve_campaign_fill_route", "revise_message_template_and_rerun", "run_scheduler_sweep", "save_domain_filters", "save_hook_research", "save_post_draft", "save_rubrics", "search_apollo", "search_available_integrations", "search_engagement_posts", "search_harvest_jobs", "search_inbox_threads", "search_prospeo", "search_prospeo_companies", "search_sales_nav", "search_signals", "search_subskill_prompts", "select_campaign_cells", "select_necessary_rubrics", "select_promising_posts", "send_inbox_draft", "send_inbox_manual_reply", "set_active_workspace", "set_campaign_waterfall_order", "set_company_info", "set_engage_state", "set_engage_style_guide", "set_headline_icp_criteria", "set_sender_calendar_link", "set_sender_routing", "setup_evergreen_campaigns", "start_campaign", "start_campaign_message_preparation", "start_cli_login", "start_direct_campaign", "start_integration_connection", "start_on_demand_campaign", "update_campaign", "update_campaign_brief", "update_cell", "update_column", "update_find_leads_run", "update_inbox_draft", "update_post_draft", "update_published_post_metrics", "update_rubric_item", "upsert_engage_tracked_person", "upsert_rubric", "validate_campaign1_kickoff_handoff", "verify_table_row", "wait_for_campaign_processing", "wait_for_campaign_table_ready", "wait_for_cli_login", "wait_for_find_leads_run", "wait_for_lead_list_ready", "wait_for_rubric_results"];
 /**
  * Explicit mutation classification lives beside (but outside) the flat tool
  * registry. Neither this list nor `isMutatingTool` is an input to
  * `compileAgentToolPolicy`, so editing it cannot move the fleet-pinned
  * `policyHash`.
  */
-export declare const MUTATING_TOOL_NAMES: readonly ["pause_campaign", "archive_campaign", "update_campaign", "fill_campaign_horizon", "set_campaign_waterfall_order", "set_sender_routing", "send_inbox_draft", "send_inbox_manual_reply", "load_csv_dnc_entries", "update_cell", "queue_cells"];
+export declare const MUTATING_TOOL_NAMES: readonly ["pause_campaign", "archive_campaign", "update_campaign", "fill_campaign_horizon", "set_campaign_waterfall_order", "set_sender_routing", "send_inbox_draft", "send_inbox_manual_reply", "load_csv_dnc_entries", "update_cell", "queue_cells", "refill_v3_fill_ready", "refill_v3_edit_selected_campaign", "refill_v3_advance", "refill_v3_continue"];
 export declare function isMutatingTool(name: string): boolean;
 export declare const CROSS_WORKSPACE_EXPLICIT_WORKSPACE_REQUIRED: {
     readonly code: "cross_workspace_explicit_workspace_required";

package/dist/agent-tool-names.js

@@ -122,6 +122,11 @@ export const SELLABLE_MCP_TOOL_NAMES = [
     "record_campaign_review_batch",
     "record_engage_proven_search",
     "refill_sends",
+    "refill_v3_advance",
+    "refill_v3_continue",
+    "refill_v3_edit_selected_campaign",
+    "refill_v3_fill_ready",
+    "refill_v3_world_state",
     "refresh_paid_inmail_credits",
     "refresh_sender_engagement",
     "reissue_find_leads_watch_link",
@@ -202,6 +207,15 @@ export const MUTATING_TOOL_NAMES = [
     "load_csv_dnc_entries",
     "update_cell",
     "queue_cells",
+    // Phase 146.5 Plan 08: the bounded Refill V3 mutation. Its sibling
+    // `refill_v3_world_state` is an OBSERVATION and deliberately stays out.
+    "refill_v3_fill_ready",
+    // Phase 146.5 Plan 09: the narrow selected-campaign config/filter/source edit.
+    "refill_v3_edit_selected_campaign",
+    // Phase 146.5 Plan 10: the one-step coordinator. It executes at most ONE
+    // existing mutation authority per invocation, so it carries the guard.
+    "refill_v3_advance",
+    "refill_v3_continue",
 ];
 const MUTATING_TOOL_NAME_SET = new Set(MUTATING_TOOL_NAMES);
 export function isMutatingTool(name) {

package/dist/scheduler-envelope.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Scheduler envelope PACKAGE seam.
+ *
+ * This module is the SOLE owner of the scheduler envelope/receipt
+ * interpretation:
+ *
+ *  - `schedulerEnvelopeIsTerminal` — did THIS dispatch finish;
+ *  - `normalizeSchedulerPrimitiveResult` — the one primitive-result normalizer;
+ *  - `classifySchedulerReceiptState` — the closed STRUCTURAL receipt state
+ *    `executed | attached | superseded | typed_failure`; and
+ *  - the primitive value readers and `normalizeSchedulerChangedCounts` those
+ *    three depend on.
+ *
+ * It is deliberately DEPENDENCY-FREE. `mcp/sellable/src/tools/refill-executors.ts`
+ * imports and re-exports these symbols so its existing callers are unchanged,
+ * and the app service `src/lib/refill-v3/fill-ready.ts` imports ONLY this file.
+ * Importing the normalizers from `refill-executors.ts` directly would pull the
+ * whole MCP executor graph (`../api.js` `getApi`/`SellableApiError`, `./leads.js`,
+ * `./campaigns.js`, `./scheduler-run.js`) into the Next server bundle; the one
+ * established `src/lib` -> `mcp/sellable/src` seam is
+ * `src/lib/sellable-agent/security/agent-tool-policy.ts`, which re-exports a
+ * SELF-CONTAINED module. This file keeps that property.
+ *
+ * There is exactly ONE terminality predicate and ONE envelope normalizer in the
+ * codebase. A second interpretation inside a consumer is a defect by
+ * construction (error law 2: one rule = one owner = one enforcement point).
+ */
+export declare function recordValue(value: unknown): Record<string, unknown> | null;
+export declare function stringValue(value: unknown): string | null;
+export declare function numberValue(value: unknown): number | null;
+export declare function stringArray(value: unknown): string[];
+/**
+ * The structural shape one expected scheduler target carries. Declared here so
+ * the dependency-free module never has to reach into the executor graph for a
+ * type; `SchedulerExpectedTargetInput` is structurally assignable to it.
+ */
+export type SchedulerEnvelopeExpectedTarget = {
+    campaignId: string;
+    tableId: string;
+    refillLaneKey: string;
+    branchActionTypes: Array<"send_invite" | "send_inmail_open" | "send_inmail_closed">;
+    senderIds: string[];
+};
+export type SchedulerChangedCount = {
+    campaignId: string;
+    tableId: string;
+    actionType: string;
+    count: number;
+};
+export type SchedulerChangedCounts = {
+    complete: true;
+    truncated: false;
+    total: number;
+    byCampaignTableActionType: SchedulerChangedCount[];
+    byCampaignTableActionTypeSender: Array<SchedulerChangedCount & {
+        senderId: string;
+    }>;
+};
+export declare function normalizeSchedulerChangedCounts(value: unknown): SchedulerChangedCounts | null;
+/**
+ * fix(112ao-2): the scheduler's ATTACHING envelope statuses. These describe a
+ * dispatch that joined an existing run rather than producing its own outcome.
+ * They are terminal ONLY when the attach actually yielded a terminal receipt.
+ */
+export declare const SCHEDULER_ATTACHING_ENVELOPE_STATUSES: ReadonlySet<string>;
+/** The envelope statuses that report an outcome of this dispatch directly. */
+export declare const SCHEDULER_TERMINAL_ENVELOPE_STATUSES: ReadonlySet<string>;
+/**
+ * The envelope statuses that DECLINE to dispatch and name a retry instant. The
+ * authority attempted nothing, so they are neither an outcome nor a failure.
+ */
+export declare const SCHEDULER_DEFERRED_ENVELOPE_STATUSES: ReadonlySet<string>;
+/**
+ * The only receipt statuses that constitute a settled outcome. A receipt
+ * without one of these is not evidence that anything finished.
+ */
+export declare const SCHEDULER_TERMINAL_RECEIPT_STATUSES: ReadonlySet<string>;
+/**
+ * A dispatch replaced BEFORE execution names itself with one of these fields.
+ * The state is decided from the marker's PRESENCE as a value, never from the
+ * absence of a receipt.
+ */
+export declare const SCHEDULER_SUPERSEDED_MARKER_FIELDS: readonly ["supersededBy", "supersededAt"];
+export declare function hasTerminalSchedulerReceipt(receipt: Record<string, unknown> | null): boolean;
+export declare function schedulerEnvelopeIsTerminal(schedulerStatus: string, receipt?: Record<string, unknown> | null): boolean;
+export declare const SCHEDULER_RECEIPT_STATES: readonly ["executed", "attached", "superseded", "deferred", "typed_failure"];
+export type SchedulerReceiptState = (typeof SCHEDULER_RECEIPT_STATES)[number];
+/**
+ * The one receipt status that reports a settled FAILURE. Consumers compare
+ * against this constant instead of re-declaring the status vocabulary.
+ */
+export declare const SCHEDULER_FAILED_RECEIPT_STATUS: "failed";
+export type SchedulerReceiptClassification = {
+    state: "executed";
+    terminal: true;
+    envelopeStatus: string;
+    receiptStatus: string;
+    receipt: Record<string, unknown>;
+} | {
+    state: "attached";
+    /** True only when the joined run already yielded a terminal receipt. */
+    terminal: boolean;
+    envelopeStatus: string;
+    receiptStatus: string | null;
+    receipt: Record<string, unknown> | null;
+} | {
+    /** Replaced before execution: NO completion, NO deferral, NO counts. */
+    state: "superseded";
+    terminal: false;
+    envelopeStatus: string;
+    supersededBy: string | null;
+} | {
+    /**
+     * The authority DECLINED to dispatch and named when to come back: a
+     * workspace backoff window or another scope holding the lease. No work
+     * was attempted, so this is a WAIT — reporting it as a settled failure is
+     * what made a second placement in the same minute look broken.
+     */
+    state: "deferred";
+    terminal: false;
+    envelopeStatus: string;
+    code: string;
+    message: string;
+    retryAfterMs: number | null;
+} | {
+    state: "typed_failure";
+    terminal: true;
+    envelopeStatus: string;
+    code: string;
+    message: string;
+};
+/**
+ * Discriminate one scheduler envelope into the closed receipt-state vocabulary
+ * STRUCTURALLY.
+ *
+ * Every branch is decided from a VALUE that is present — an explicit superseded
+ * marker, an error code, the envelope status's membership in a closed set, or
+ * the receipt's OWN status. No branch is decided from the bare absence of a
+ * receipt: a bare negated-receipt guard silently merges "no receipt" with
+ * "replayed receipt",
+ * which is exactly P0-1(A)/(B), the defect that froze Dotwork at 0/50 across 21
+ * runs.
+ */
+export declare function classifySchedulerReceiptState(value: unknown): SchedulerReceiptClassification;
+export declare function normalizeSchedulerPrimitiveResult(value: unknown, expected?: {
+    expectedTargets: SchedulerEnvelopeExpectedTarget[];
+    expectedTargetsHash: string;
+    maxPlacements: number;
+}): {
+    retryAfterMs: number;
+    changedCounts: null;
+    auditComplete: false;
+    unsettledReceipt?: Record<string, unknown> | undefined;
+    status: "matching_scheduler_active";
+    schedulerStatus: string;
+    terminal: false;
+    disposition: "bounded_reread_wait";
+    receipt: null;
+    blocker?: undefined;
+} | {
+    status: string;
+    schedulerStatus: string;
+    disposition: "bounded_backoff_wait" | "diagnostic_stop";
+    receipt: {} | null;
+    retryAfterMs: number | null;
+    changedCounts: null;
+    auditComplete: false;
+    blocker: string;
+    terminal?: undefined;
+} | {
+    status: "scheduler_receipt_incomplete";
+    schedulerStatus: string;
+    receipt: {} | null;
+    retryAfterMs: number | null;
+    changedCounts: null;
+    auditComplete: false;
+    blocker: "scheduler_receipt_incomplete";
+    disposition?: undefined;
+    terminal?: undefined;
+} | {
+    status: string;
+    terminal: boolean;
+    receipt: {} | null;
+    retryAfterMs: number | null;
+    changedCounts: SchedulerChangedCounts;
+    auditComplete: true;
+    schedulerStatus?: undefined;
+    disposition?: undefined;
+    blocker?: undefined;
+};

package/dist/scheduler-envelope.js

@@ -0,0 +1,412 @@
+/**
+ * Scheduler envelope PACKAGE seam.
+ *
+ * This module is the SOLE owner of the scheduler envelope/receipt
+ * interpretation:
+ *
+ *  - `schedulerEnvelopeIsTerminal` — did THIS dispatch finish;
+ *  - `normalizeSchedulerPrimitiveResult` — the one primitive-result normalizer;
+ *  - `classifySchedulerReceiptState` — the closed STRUCTURAL receipt state
+ *    `executed | attached | superseded | typed_failure`; and
+ *  - the primitive value readers and `normalizeSchedulerChangedCounts` those
+ *    three depend on.
+ *
+ * It is deliberately DEPENDENCY-FREE. `mcp/sellable/src/tools/refill-executors.ts`
+ * imports and re-exports these symbols so its existing callers are unchanged,
+ * and the app service `src/lib/refill-v3/fill-ready.ts` imports ONLY this file.
+ * Importing the normalizers from `refill-executors.ts` directly would pull the
+ * whole MCP executor graph (`../api.js` `getApi`/`SellableApiError`, `./leads.js`,
+ * `./campaigns.js`, `./scheduler-run.js`) into the Next server bundle; the one
+ * established `src/lib` -> `mcp/sellable/src` seam is
+ * `src/lib/sellable-agent/security/agent-tool-policy.ts`, which re-exports a
+ * SELF-CONTAINED module. This file keeps that property.
+ *
+ * There is exactly ONE terminality predicate and ONE envelope normalizer in the
+ * codebase. A second interpretation inside a consumer is a defect by
+ * construction (error law 2: one rule = one owner = one enforcement point).
+ */
+// ───────────────────────────────────────────────────────────────────────────
+// Primitive value readers
+// ───────────────────────────────────────────────────────────────────────────
+export function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+export function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+export function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+export function normalizeSchedulerChangedCounts(value) {
+    const changedCounts = recordValue(value);
+    if (!changedCounts ||
+        changedCounts.complete !== true ||
+        changedCounts.truncated !== false) {
+        return null;
+    }
+    const total = numberValue(changedCounts.total);
+    if (total === null || total < 0 || !Number.isInteger(total))
+        return null;
+    if (!Array.isArray(changedCounts.byCampaignTableActionType))
+        return null;
+    const groups = [];
+    const seen = new Set();
+    for (const rawGroup of changedCounts.byCampaignTableActionType) {
+        const group = recordValue(rawGroup);
+        const campaignId = stringValue(group?.campaignId);
+        const tableId = stringValue(group?.tableId);
+        const actionType = stringValue(group?.actionType);
+        const count = numberValue(group?.count);
+        if (!campaignId ||
+            !tableId ||
+            !actionType ||
+            count === null ||
+            count <= 0 ||
+            !Number.isInteger(count)) {
+            return null;
+        }
+        const key = `${campaignId}:${tableId}:${actionType}`;
+        if (seen.has(key))
+            return null;
+        seen.add(key);
+        groups.push({ campaignId, tableId, actionType, count });
+    }
+    groups.sort((a, b) => {
+        if (a.campaignId !== b.campaignId) {
+            return a.campaignId.localeCompare(b.campaignId);
+        }
+        if (a.tableId !== b.tableId)
+            return a.tableId.localeCompare(b.tableId);
+        return a.actionType.localeCompare(b.actionType);
+    });
+    if (groups.reduce((sum, group) => sum + group.count, 0) !== total) {
+        return null;
+    }
+    if (!Array.isArray(changedCounts.byCampaignTableActionTypeSender)) {
+        return null;
+    }
+    const senderGroups = [];
+    const senderSeen = new Set();
+    for (const rawGroup of changedCounts.byCampaignTableActionTypeSender) {
+        const group = recordValue(rawGroup);
+        const campaignId = stringValue(group?.campaignId);
+        const tableId = stringValue(group?.tableId);
+        const actionType = stringValue(group?.actionType);
+        const senderId = stringValue(group?.senderId);
+        const count = numberValue(group?.count);
+        if (!campaignId ||
+            !tableId ||
+            !actionType ||
+            !senderId ||
+            count === null ||
+            count <= 0 ||
+            !Number.isInteger(count)) {
+            return null;
+        }
+        const key = `${campaignId}:${tableId}:${actionType}:${senderId}`;
+        if (senderSeen.has(key))
+            return null;
+        senderSeen.add(key);
+        senderGroups.push({ campaignId, tableId, actionType, senderId, count });
+    }
+    if (senderGroups.reduce((sum, group) => sum + group.count, 0) !== total) {
+        return null;
+    }
+    return {
+        complete: true,
+        truncated: false,
+        total,
+        byCampaignTableActionType: groups,
+        byCampaignTableActionTypeSender: senderGroups,
+    };
+}
+function completeExpectedTargetSummary(value, expectedTargets, maxPlacements) {
+    const summary = recordValue(value);
+    const items = Array.isArray(summary?.items) ? summary.items : [];
+    if (summary?.complete !== true ||
+        summary.truncated !== false ||
+        numberValue(summary.requested) !== expectedTargets.length ||
+        numberValue(summary.included) == null ||
+        numberValue(summary.omitted) == null ||
+        numberValue(summary.included) + numberValue(summary.omitted) !==
+            expectedTargets.length ||
+        numberValue(summary.maxPlacements) !== maxPlacements ||
+        items.length !== expectedTargets.length) {
+        return false;
+    }
+    return items.every((rawItem, index) => {
+        const item = recordValue(rawItem);
+        const target = expectedTargets[index];
+        const senderIds = stringArray(item?.senderIds).sort();
+        const bySender = Array.isArray(item?.bySender) ? item.bySender : [];
+        const accounted = bySender
+            .map((entry) => stringValue(recordValue(entry)?.senderId))
+            .filter((senderId) => Boolean(senderId))
+            .sort();
+        return (Boolean(target) &&
+            item?.campaignId === target?.campaignId &&
+            item?.tableId === target?.tableId &&
+            item?.refillLaneKey === target?.refillLaneKey &&
+            (item?.outcome === "included" || item?.outcome === "omitted") &&
+            JSON.stringify(senderIds) === JSON.stringify(target?.senderIds) &&
+            JSON.stringify(accounted) === JSON.stringify(target?.senderIds));
+    });
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Envelope status vocabularies
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * fix(112ao-2): the scheduler's ATTACHING envelope statuses. These describe a
+ * dispatch that joined an existing run rather than producing its own outcome.
+ * They are terminal ONLY when the attach actually yielded a terminal receipt.
+ */
+export const SCHEDULER_ATTACHING_ENVELOPE_STATUSES = new Set(["accepted", "attached"]);
+/** The envelope statuses that report an outcome of this dispatch directly. */
+export const SCHEDULER_TERMINAL_ENVELOPE_STATUSES = new Set(["ran", "window_closed_noop"]);
+/**
+ * The envelope statuses that DECLINE to dispatch and name a retry instant. The
+ * authority attempted nothing, so they are neither an outcome nor a failure.
+ */
+export const SCHEDULER_DEFERRED_ENVELOPE_STATUSES = new Set(["backoff"]);
+/**
+ * The only receipt statuses that constitute a settled outcome. A receipt
+ * without one of these is not evidence that anything finished.
+ */
+export const SCHEDULER_TERMINAL_RECEIPT_STATUSES = new Set(["ran", "window_closed_noop", "failed"]);
+/**
+ * A dispatch replaced BEFORE execution names itself with one of these fields.
+ * The state is decided from the marker's PRESENCE as a value, never from the
+ * absence of a receipt.
+ */
+export const SCHEDULER_SUPERSEDED_MARKER_FIELDS = [
+    "supersededBy",
+    "supersededAt",
+];
+export function hasTerminalSchedulerReceipt(receipt) {
+    const status = receipt ? stringValue(receipt.status) : null;
+    return Boolean(status && SCHEDULER_TERMINAL_RECEIPT_STATUSES.has(status));
+}
+export function schedulerEnvelopeIsTerminal(schedulerStatus, receipt = null) {
+    if (SCHEDULER_TERMINAL_ENVELOPE_STATUSES.has(schedulerStatus))
+        return true;
+    return (SCHEDULER_ATTACHING_ENVELOPE_STATUSES.has(schedulerStatus) &&
+        hasTerminalSchedulerReceipt(receipt));
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Closed structural receipt state
+// ───────────────────────────────────────────────────────────────────────────
+export const SCHEDULER_RECEIPT_STATES = [
+    "executed",
+    "attached",
+    "superseded",
+    "deferred",
+    "typed_failure",
+];
+/**
+ * The one receipt status that reports a settled FAILURE. Consumers compare
+ * against this constant instead of re-declaring the status vocabulary.
+ */
+export const SCHEDULER_FAILED_RECEIPT_STATUS = "failed";
+/**
+ * Discriminate one scheduler envelope into the closed receipt-state vocabulary
+ * STRUCTURALLY.
+ *
+ * Every branch is decided from a VALUE that is present — an explicit superseded
+ * marker, an error code, the envelope status's membership in a closed set, or
+ * the receipt's OWN status. No branch is decided from the bare absence of a
+ * receipt: a bare negated-receipt guard silently merges "no receipt" with
+ * "replayed receipt",
+ * which is exactly P0-1(A)/(B), the defect that froze Dotwork at 0/50 across 21
+ * runs.
+ */
+export function classifySchedulerReceiptState(value) {
+    const response = recordValue(value);
+    const receipt = recordValue(response?.receipt);
+    const envelopeStatus = stringValue(response?.status) ?? stringValue(receipt?.status) ?? "unknown";
+    const errorCode = stringValue(recordValue(response?.error)?.code);
+    // 1. A transition REPLACED before execution names itself. It is checked first
+    //    and records no completion, no deferral, and no counts.
+    for (const field of SCHEDULER_SUPERSEDED_MARKER_FIELDS) {
+        const marker = stringValue(receipt?.[field]) ?? stringValue(response?.[field]);
+        if (marker) {
+            return {
+                state: "superseded",
+                terminal: false,
+                envelopeStatus,
+                supersededBy: marker,
+            };
+        }
+    }
+    // 2. A typed failure carries either the uncertainty vocabulary or an explicit
+    //    error code. Uncertainty stays its own code rather than collapsing into a
+    //    generic failure.
+    if (envelopeStatus === "uncertain_outcome" ||
+        errorCode === "uncertain_outcome") {
+        return {
+            state: "typed_failure",
+            terminal: true,
+            envelopeStatus,
+            code: "uncertain_outcome",
+            message: "The matching scheduler attempt produced no terminal receipt evidence.",
+        };
+    }
+    // 2b. A DEFERRAL is named before any failure branch: the authority declined
+    //     to dispatch and said when to return. It carries no receipt, no counts,
+    //     and no settled outcome.
+    //     A deferral that hands back a TERMINAL receipt is not a deferral at all:
+    //     it is the completed work being replayed, and it keeps its facts.
+    if (SCHEDULER_DEFERRED_ENVELOPE_STATUSES.has(envelopeStatus) &&
+        !hasTerminalSchedulerReceipt(receipt)) {
+        return {
+            state: "deferred",
+            terminal: false,
+            envelopeStatus,
+            code: errorCode ?? envelopeStatus,
+            message: stringValue(recordValue(response?.error)?.message) ?? "",
+            retryAfterMs: numberValue(response?.retryAfterMs),
+        };
+    }
+    if (envelopeStatus === "failed" || errorCode) {
+        return {
+            state: "typed_failure",
+            terminal: true,
+            envelopeStatus,
+            code: errorCode ?? envelopeStatus,
+            message: stringValue(recordValue(response?.error)?.message) ?? "",
+        };
+    }
+    const receiptStatus = stringValue(receipt?.status);
+    const receiptIsTerminal = Boolean(receiptStatus && SCHEDULER_TERMINAL_RECEIPT_STATUSES.has(receiptStatus));
+    // 3. The envelope reports THIS dispatch's own outcome. Its receipt must carry
+    //    a settled status; an incomplete one is a typed failure, never a success.
+    if (SCHEDULER_TERMINAL_ENVELOPE_STATUSES.has(envelopeStatus)) {
+        if (receipt && receiptIsTerminal && receiptStatus) {
+            return {
+                state: "executed",
+                terminal: true,
+                envelopeStatus,
+                receiptStatus,
+                receipt,
+            };
+        }
+        return {
+            state: "typed_failure",
+            terminal: true,
+            envelopeStatus,
+            code: "scheduler_receipt_incomplete",
+            message: "The terminal envelope carried no settled receipt status of its own.",
+        };
+    }
+    // 4. The dispatch joined an existing run. It completes only from a receipt
+    //    that carries its own terminal status; a replayed terminal receipt is a
+    //    legitimate idempotent completion and keeps its facts.
+    return {
+        state: "attached",
+        terminal: receiptIsTerminal,
+        envelopeStatus,
+        receiptStatus: receiptIsTerminal ? receiptStatus : null,
+        receipt: receiptIsTerminal ? receipt : null,
+    };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Primitive result normalizer
+// ───────────────────────────────────────────────────────────────────────────
+export function normalizeSchedulerPrimitiveResult(value, expected) {
+    const response = recordValue(value);
+    const receipt = recordValue(response?.receipt);
+    const schedulerStatus = stringValue(response?.status) ?? stringValue(receipt?.status) ?? "unknown";
+    const errorCode = stringValue(recordValue(response?.error)?.code);
+    // fix(112ao-2): whether this dispatch finished is decided explicitly from the
+    // envelope status plus the RECEIPT'S OWN STATUS — never from the bare
+    // presence of a receipt field.
+    //
+    // The previous guard negated the receipt and OR-ed the attaching statuses.
+    // Truthiness is
+    // the wrong test: an attach that carries a receipt with no terminal status is
+    // not evidence that anything settled, yet it skipped this branch, ran the v3
+    // audit on that non-evidence, and could return auditComplete: true — a
+    // completion claim for a run still in flight, which the coordinator then
+    // treats as done rather than awaiting (Dotwork 2026-07-29: 21 exact runs,
+    // coverage frozen at sent:0/scheduled:0).
+    //
+    // The attach is NOT always in flight, and this deliberately does not treat it
+    // so: scheduler-run.ts only returns a receipt from
+    // waitForSchedulerRunReceipt when it is scope-matched to THIS request, so an
+    // attach carrying a terminal receipt is a legitimate idempotent completion of
+    // this exact operation and must keep its counters. Discarding it would report
+    // zero placements for a sweep that really placed cells.
+    //
+    // `ran`/`window_closed_noop` remain terminal. `backoff`/`failed` keep their
+    // existing handling — the run loop already unwraps a backoff envelope's
+    // replayed receipt deliberately (schedulerRunReceiptIsFreshZeroScheduled).
+    if (SCHEDULER_ATTACHING_ENVELOPE_STATUSES.has(schedulerStatus) &&
+        !hasTerminalSchedulerReceipt(receipt)) {
+        return {
+            status: "matching_scheduler_active",
+            schedulerStatus,
+            terminal: false,
+            disposition: "bounded_reread_wait",
+            receipt: null,
+            // A non-terminal receipt is not this dispatch's effect. Surfaced under a
+            // distinct name so it stays readable for diagnostics but can never be
+            // mistaken for a settled outcome.
+            ...(receipt ? { unsettledReceipt: receipt } : {}),
+            retryAfterMs: numberValue(response?.retryAfterMs) ?? 30_000,
+            changedCounts: null,
+            auditComplete: false,
+        };
+    }
+    if (errorCode === "scheduler_scope_busy" ||
+        errorCode === "uncertain_outcome" ||
+        schedulerStatus === "uncertain_outcome") {
+        const status = errorCode === "scheduler_scope_busy"
+            ? "scheduler_scope_busy"
+            : "uncertain_outcome";
+        return {
+            status,
+            schedulerStatus,
+            disposition: status === "scheduler_scope_busy"
+                ? "bounded_backoff_wait"
+                : "diagnostic_stop",
+            receipt: response?.receipt ?? null,
+            retryAfterMs: numberValue(response?.retryAfterMs),
+            changedCounts: null,
+            auditComplete: false,
+            blocker: status,
+        };
+    }
+    const changedCounts = normalizeSchedulerChangedCounts(receipt?.changedCounts ?? response?.changedCounts);
+    const targetAuditComplete = !expected ||
+        (receipt?.receiptVersion === 3 &&
+            receipt.expectedTargetsHash === expected.expectedTargetsHash &&
+            receipt.maxPlacements === expected.maxPlacements &&
+            completeExpectedTargetSummary(receipt.expectedTargetSummary, expected.expectedTargets, expected.maxPlacements));
+    if (!changedCounts || !targetAuditComplete) {
+        return {
+            status: "scheduler_receipt_incomplete",
+            schedulerStatus,
+            receipt: response?.receipt ?? null,
+            retryAfterMs: numberValue(response?.retryAfterMs),
+            changedCounts: null,
+            auditComplete: false,
+            blocker: "scheduler_receipt_incomplete",
+        };
+    }
+    return {
+        status: schedulerStatus,
+        // fix(112ao-2): the completion decision, carried explicitly instead of
+        // leaving each consumer to re-infer it from the status string.
+        terminal: schedulerEnvelopeIsTerminal(schedulerStatus, receipt),
+        receipt: response?.receipt ?? null,
+        retryAfterMs: numberValue(response?.retryAfterMs),
+        changedCounts,
+        auditComplete: true,
+    };
+}