pixivflow 2.19.1 → 2.19.3

package/dist/download/handlers/NovelTargetHandler.d.ts

@@ -6,6 +6,7 @@ import { DownloadPipeline } from '../pipeline/DownloadPipeline';
 import { NovelDownloader } from '../NovelDownloader';
 import { DeliveryService } from '../../delivery/DeliveryService';
 import { TargetOutcome } from '../../scheduler/TargetOutcome';
+import { TargetExecutionContext } from '../../scheduler/WorkIdentity';
 import type { TopicPipelineFactory } from '../../topic/createTopicPipeline';
 export declare class NovelTargetHandler {
     private readonly client;
@@ -16,8 +17,14 @@ export declare class NovelTargetHandler {
     private readonly topicPipelineFactory?;
     private readonly deliveryService?;
     private outcomes;
+    /**
+     * Cell identity for this handle() call. Set only for a single-work cell of a
+     * scheduled occurrence; null for ad-hoc runs and N-works-per-run targets, which
+     * have no single (slotId,targetId) -> workId identity to honour.
+     */
+    private execution;
     constructor(client: IPixivClient, database: IDatabase, rankingService: RankingService, pipeline: DownloadPipeline, novelDownloader: NovelDownloader, topicPipelineFactory?: TopicPipelineFactory | undefined, deliveryService?: DeliveryService | undefined);
-    handle(target: TargetConfig): Promise<TargetOutcome>;
+    handle(target: TargetConfig, execution?: TargetExecutionContext): Promise<TargetOutcome>;
     private summarize;
     private classifyError;
     private fetchNovels;
@@ -34,6 +41,25 @@ export declare class NovelTargetHandler {
     private handleUserNovels;
     private sortByPopularityAndLog;
     private logError;
+    /**
+     * Continue the work this cell ALREADY owns. Selection is deliberately skipped:
+     * no search, no ranking, no topic expansion, no backfill pool, and no
+     * "already downloaded / already delivered" exclusion — the cell's own work must
+     * never be filtered out of its own recovery.
+     *
+     * A locked work that is permanently gone is a terminal failure of THIS logical
+     * item (`LOCKED_WORK_UNAVAILABLE`). It is never silently replaced by another
+     * candidate; that would mutate the item's identity behind the operator's back.
+     */
+    private recoverLockedWork;
+    /**
+     * Process ONE candidate work for this cell.
+     *
+     * The cell is bound to `novel` BEFORE any side effect: it is the binding, not
+     * the candidate list, that decides what a later recovery resumes. The binding
+     * is only rolled back when the attempt produced no artifact at all, so in-run
+     * backfill still works for a cell that has committed to nothing.
+     */
     private downloadAndDeliver;
 }
 //# sourceMappingURL=NovelTargetHandler.d.ts.map

package/dist/download/handlers/NovelTargetHandler.js

@@ -5,6 +5,7 @@ const logger_1 = require("../../logger");
 const errors_1 = require("../../utils/errors");
 const pixiv_date_utils_1 = require("../../utils/pixiv-date-utils");
 const pixiv_utils_1 = require("../../utils/pixiv-utils");
+const WorkIdentity_1 = require("../../scheduler/WorkIdentity");
 const target_label_1 = require("../../utils/target-label");
 class NovelTargetHandler {
     client;
@@ -15,6 +16,12 @@ class NovelTargetHandler {
     topicPipelineFactory;
     deliveryService;
     outcomes = [];
+    /**
+     * Cell identity for this handle() call. Set only for a single-work cell of a
+     * scheduled occurrence; null for ad-hoc runs and N-works-per-run targets, which
+     * have no single (slotId,targetId) -> workId identity to honour.
+     */
+    execution = null;
     constructor(client, database, rankingService, pipeline, novelDownloader, topicPipelineFactory, deliveryService) {
         this.client = client;
         this.database = database;
@@ -24,8 +31,17 @@ class NovelTargetHandler {
         this.topicPipelineFactory = topicPipelineFactory;
         this.deliveryService = deliveryService;
     }
-    async handle(target) {
+    async handle(target, execution) {
         this.outcomes = [];
+        this.execution = execution && (0, WorkIdentity_1.isSingleWorkCell)(target) ? execution : null;
+        // A cell that already owns a work is in RECOVERY, not in a new selection.
+        // Crash/shutdown recovery is not an intentional second run: running the
+        // candidate pipeline here would re-rank and could bind this logical item to a
+        // different work than the one it already committed to.
+        if (this.execution?.lockedWorkId) {
+            await this.recoverLockedWork(target, this.execution.lockedWorkId);
+            return this.summarize();
+        }
         if (target.novelId !== undefined && target.novelId !== null && target.novelId !== '') {
             const novelNum = typeof target.novelId === 'number' ? target.novelId : Number(target.novelId);
             if (!Number.isFinite(novelNum)) {
@@ -410,10 +426,98 @@ class NovelTargetHandler {
             stack: error instanceof Error ? error.stack : undefined,
         });
     }
+    /**
+     * Continue the work this cell ALREADY owns. Selection is deliberately skipped:
+     * no search, no ranking, no topic expansion, no backfill pool, and no
+     * "already downloaded / already delivered" exclusion — the cell's own work must
+     * never be filtered out of its own recovery.
+     *
+     * A locked work that is permanently gone is a terminal failure of THIS logical
+     * item (`LOCKED_WORK_UNAVAILABLE`). It is never silently replaced by another
+     * candidate; that would mutate the item's identity behind the operator's back.
+     */
+    async recoverLockedWork(target, lockedWorkId) {
+        const displayTag = (0, target_label_1.getTargetLabel)(target);
+        logger_1.logger.info(`Recovering locked work ${lockedWorkId} for ${displayTag}; candidate selection is skipped`, {
+            slotId: this.execution?.slotId,
+            targetId: this.execution?.targetId,
+            lockedWorkId,
+        });
+        const novelId = Number(lockedWorkId);
+        if (!Number.isFinite(novelId)) {
+            this.outcomes.push({
+                kind: 'failed',
+                retryable: false,
+                error: `LOCKED_WORK_UNAVAILABLE: cell work id "${lockedWorkId}" is not a valid novel id`,
+            });
+            return;
+        }
+        try {
+            const detail = await this.client.getNovelDetail(novelId);
+            const novel = {
+                id: detail.id,
+                title: detail.title,
+                user: detail.user,
+                create_date: detail.create_date,
+            };
+            await this.downloadAndDeliver(novel, `novel-${novelId}`, target);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const retryable = (0, errors_1.isRetryableNetworkError)(error);
+            this.logError(error, `Failed to recover locked novel ${lockedWorkId}`);
+            this.outcomes.push({
+                kind: 'failed',
+                retryable,
+                error: retryable
+                    ? `locked work ${lockedWorkId} could not be fetched (will retry the SAME work): ${message}`
+                    : `LOCKED_WORK_UNAVAILABLE: locked work ${lockedWorkId} is no longer fetchable: ${message}`,
+            });
+        }
+    }
+    /**
+     * Process ONE candidate work for this cell.
+     *
+     * The cell is bound to `novel` BEFORE any side effect: it is the binding, not
+     * the candidate list, that decides what a later recovery resumes. The binding
+     * is only rolled back when the attempt produced no artifact at all, so in-run
+     * backfill still works for a cell that has committed to nothing.
+     */
     async downloadAndDeliver(novel, tag, target) {
-        const artifact = await this.novelDownloader.download(novel, tag, target);
-        if (!artifact)
+        const execution = this.execution;
+        const workId = String(novel.id);
+        // Recovery continues a work the cell already bound; it must never be released.
+        const recovering = Boolean(execution?.lockedWorkId);
+        if (execution && !recovering) {
+            const binding = execution.bind(workId, 'novel');
+            if (!binding.won) {
+                // Another writer elected a different work for this cell. First selection
+                // is authoritative: never process a work the cell does not own.
+                logger_1.logger.warn(`Cell is bound to work ${binding.workId}; declining to select ${workId}`, {
+                    slotId: execution.slotId,
+                    targetId: execution.targetId,
+                    boundWorkId: binding.workId,
+                });
+                return;
+            }
+        }
+        let artifact;
+        try {
+            artifact = await this.novelDownloader.download(novel, tag, target);
+        }
+        catch (error) {
+            // Nothing was persisted, so the cell may still pick another candidate.
+            if (execution && !recovering)
+                execution.release(workId);
+            throw error;
+        }
+        if (!artifact) {
+            if (execution && !recovering)
+                execution.release(workId);
             return;
+        }
+        // Committed: the artifact is durable and this work now defines the cell. Even
+        // if the delivery below throws, recovery must resume THIS work — never release.
         const isDelivery = target.storageMode === 'cache' && target.delivery?.target?.trim();
         if (!isDelivery || !this.deliveryService) {
             this.outcomes.push({ kind: 'stored', workId: artifact.pixivId, workType: artifact.type });

package/dist/notification/NotificationPolicy.d.ts

@@ -16,6 +16,17 @@ export declare class NotificationPolicy {
     private readonly config;
     constructor(database: Database, config: StandaloneConfig);
     private targetName;
+    /**
+     * Delivery targets that can actually RECEIVE an operational notification.
+     *
+     * `delivery.target` names a SUBMISSION endpoint (multipart POST of a work).
+     * Only targets that also declare a `notificationUrl` accept notifications —
+     * the same rule `config/validation.ts` enforces for `noMatchPolicy.notify`
+     * and that `docs/CONFIG.md` documents. A submission endpoint without one
+     * rejects every notification, so enqueuing to it would only grow an outbox
+     * row that can never be delivered.
+     */
+    private notifiableTargets;
     /** Stable slot-scoped keys (two occurrences on one date never collide). */
     static keys: {
         noMatch: (slotId: string, targetId: string) => string;

package/dist/notification/NotificationPolicy.js

@@ -21,6 +21,23 @@ class NotificationPolicy {
     targetName(target) {
         return target.delivery?.target?.trim() || null;
     }
+    /**
+     * Delivery targets that can actually RECEIVE an operational notification.
+     *
+     * `delivery.target` names a SUBMISSION endpoint (multipart POST of a work).
+     * Only targets that also declare a `notificationUrl` accept notifications —
+     * the same rule `config/validation.ts` enforces for `noMatchPolicy.notify`
+     * and that `docs/CONFIG.md` documents. A submission endpoint without one
+     * rejects every notification, so enqueuing to it would only grow an outbox
+     * row that can never be delivered.
+     */
+    notifiableTargets() {
+        const targets = this.config.delivery?.targets ?? {};
+        return new Set(Object.keys(targets).filter((name) => {
+            const target = targets[name];
+            return target?.type === 'httpMultipart' && Boolean(target.notificationUrl?.trim());
+        }));
+    }
     /** Stable slot-scoped keys (two occurrences on one date never collide). */
     static keys = {
         noMatch: (slotId, targetId) => `notification:${slotId}:${targetId}:no-candidate`,
@@ -32,6 +49,10 @@ class NotificationPolicy {
         const name = this.targetName(target);
         if (!name)
             return;
+        // No notifiable endpoint configured: drop the notification instead of
+        // enqueuing it against a submission target that will reject it forever.
+        if (!this.notifiableTargets().has(name))
+            return;
         const label = target.id || target.filterTag || target.tag || target.type;
         if (outcome.kind === 'no_candidate' && target.noMatchPolicy?.notify === true) {
             this.send(name, NotificationPolicy.keys.noMatch(slotId, target.id ?? label), [
@@ -53,11 +74,7 @@ class NotificationPolicy {
     }
     /** One consolidated summary per slot, delivered to every notifying target's endpoint. */
     sendSlotSummary(slot, schedule, rows) {
-        const targets = this.config.delivery?.targets ?? {};
-        const notifiable = new Set(Object.keys(targets).filter((n) => {
-            const target = targets[n];
-            return target?.type === 'httpMultipart' && Boolean(target.notificationUrl?.trim());
-        }));
+        const notifiable = this.notifiableTargets();
         if (notifiable.size === 0 || rows.length === 0)
             return;
         const icon = (s) => s === 'submitted' ? '✅' : s === 'no_candidate' ? '⚠️' : s === 'duplicate' ? '♱' : s === 'delivery_pending' ? '🕓' : '❌';

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow",
-  "version": "2.19.1",
+  "version": "2.19.3",
   "private": true
 }

package/dist/pixiv-client/TargetSearchRunner.js

@@ -56,10 +56,10 @@ class TargetSearchRunner {
         return target.limit ? sorted.slice(0, target.limit) : sorted;
     }
     async searchSingleIllust(target, tag, requestDelayMs, signal) {
-        return this.searchWithPagination(target, tag, requestDelayMs, (options) => this.kit.illustrations.searchPage(options), (t, g) => (0, query_mapper_1.mapTargetToIllustQuery)({ ...t, tag: g }), signal);
+        return this.searchWithPagination(target, tag, requestDelayMs, (options, cursor) => this.kit.illustrations.searchPage(options, cursor), (t, g) => (0, query_mapper_1.mapTargetToIllustQuery)({ ...t, tag: g }), signal);
     }
     async searchSingleNovel(target, tag, requestDelayMs, signal) {
-        return this.searchWithPagination(target, tag, requestDelayMs, (options) => this.kit.novels.searchPage(options), (t, g) => (0, query_mapper_1.mapTargetToNovelQuery)({ ...t, tag: g }), signal);
+        return this.searchWithPagination(target, tag, requestDelayMs, (options, cursor) => this.kit.novels.searchPage(options, cursor), (t, g) => (0, query_mapper_1.mapTargetToNovelQuery)({ ...t, tag: g }), signal);
     }
     /**
      * Date-aware pagination. Mirrors the legacy SearchService semantics:
@@ -96,23 +96,39 @@ class TargetSearchRunner {
         let cursor = null;
         let pageCount = 0;
         let shouldStop = false;
+        // Progress invariant: every iteration must terminate, advance to a cursor we
+        // have never fetched, or fail explicitly. A cursor that repeats (same `next`
+        // twice, or an A -> B -> A cycle) proves the upstream adapter is not making
+        // progress; re-requesting would spin forever, so we refuse instead.
+        const seenCursors = new Set();
         while ((!fetchLimit || results.length < fetchLimit) && !shouldStop) {
             (0, errors_1.throwIfAborted)(signal, 'search cancelled');
             pageCount++;
             // Dates are intentionally filtered CLIENT-side below (legacy behavior;
             // PixivFlow needs the early-stop walk on create_date).
+            //
+            // The cursor must travel as searchPage's SECOND POSITIONAL argument: the
+            // kit reads `options.cursor` only inside its own `search()`. Putting it in
+            // the options object left the cursor permanently null, so page 1 (the
+            // newest works) was re-fetched on every iteration and a search that found
+            // no in-range work on that page never terminated.
             const page = await fetchOne({
                 word: base.word,
                 sort: base.sort,
                 searchTarget: base.searchTarget,
                 includeR18: base.includeR18,
-                cursor,
-                // Threaded into the kit transport, which combines it with its per-request
-                // timeout and honours it in retry back-off. Without this the pager could
-                // stay blocked in a single hung request for the rest of the run.
                 signal,
-            });
-            cursor = page.next;
+            }, cursor);
+            const nextCursor = page.next;
+            if (nextCursor !== null) {
+                if (nextCursor === cursor || seenCursors.has(nextCursor)) {
+                    throw new errors_1.PaginationError(`Search pager for tag "${tag}" did not advance: page ${pageCount} returned a cursor that ` +
+                        (nextCursor === cursor ? 'equals the one just fetched' : 'was already fetched') +
+                        `. Refusing to re-request it indefinitely.`);
+                }
+                seenCursors.add(nextCursor);
+            }
+            cursor = nextCursor;
             for (const item of page.items) {
                 const decision = this.filterItemByDate(item, target, startDate, endDate, sortMode);
                 if (decision.shouldStop) {

package/dist/scheduler/SlotCoordinator.d.ts

@@ -3,6 +3,7 @@ import { Database } from '../storage/Database';
 import { CellStatus, SlotItemRecord, SlotRecord, SlotStatus } from '../storage/repositories/SlotRepository';
 import { TriggerSource } from './OccurrenceResolver';
 import { TargetOutcome } from './TargetOutcome';
+import { TargetExecutionContext, WorkBinding } from './WorkIdentity';
 /**
  * Execution-lease TTL and heartbeat cadence.
  *
@@ -54,6 +55,40 @@ export interface SlotResolveResult {
     error?: string;
     status?: number;
 }
+/**
+ * What a `delivery_pending` cell still owes downstream, read from the durable
+ * delivery ledger.
+ *
+ *  - `live`      : a non-terminal intent still owns the cell — the outbox is
+ *                  retrying THAT work toward a terminal ACK.
+ *  - `confirmed` : the ACK already landed but the cell promotion was lost.
+ *  - `lost`      : the intent is terminally failed; nobody will converge it.
+ *  - `unknown`   : no delivery fact for this cell (not a delivery cell).
+ */
+export type CellDeliveryState = {
+    kind: 'live';
+} | {
+    kind: 'confirmed';
+    workId: string;
+    workType: string;
+} | {
+    kind: 'lost';
+    reason: string;
+} | {
+    kind: 'unknown';
+};
+/**
+ * Port for the delivery ledger, injected by the runtime. It lets the slot FSM
+ * hand a `delivery_pending` cell to whoever owns its delivery without this class
+ * learning anything about TelePost, bots or any hosting platform (see below).
+ */
+export interface SchedulerDeliveryPort {
+    stateFor(input: {
+        deliveryTarget: string;
+        slotId: string;
+        targetId: string;
+    }): CellDeliveryState;
+}
 /**
  * Owns the Schedule Slot ledger for one scheduler run. A Slot is one durable
  * execution occurrence of a Schedule (NOT a morning/evening row). It ensures
@@ -66,7 +101,8 @@ export interface SlotResolveResult {
  */
 export declare class SlotCoordinator {
     private readonly database;
-    constructor(database: Database);
+    private readonly delivery?;
+    constructor(database: Database, delivery?: SchedulerDeliveryPort | undefined);
     /**
      * Resolve + validate the canonical occurrence for a trigger. Uses ONLY the
      * schedule's cron + timezone and the trigger instant (never a client-supplied
@@ -103,8 +139,33 @@ export declare class SlotCoordinator {
         target: TargetConfig;
         cell: SlotItemRecord;
     }[];
+    /**
+     * Build the per-target execution contexts for one run, so every handler
+     * receives the cell's durable identity instead of just a TargetConfig.
+     *
+     * This is the boundary where the identity used to be dropped (`pending` was
+     * reduced to `p.target`), which is what let a resume re-rank and re-point the
+     * logical item at a different work.
+     */
+    executionContextsFor(slotId: string, entries: {
+        target: TargetConfig;
+        cell: SlotItemRecord | null;
+    }[]): Map<string, TargetExecutionContext>;
     /** Lock the selected work for a cell (first selection wins; retries keep it). */
     lockWork(slotId: string, targetId: string, workId: string, workType: string): void;
+    /**
+     * CAS-bind a cell to the work a handler is about to process. Returns the
+     * authoritative binding: when another worker already elected a different work,
+     * `won` is false and the caller MUST continue with the returned `workId`
+     * instead of its own candidate.
+     */
+    lockWorkCas(slotId: string, targetId: string, workId: string, workType: string): WorkBinding;
+    /**
+     * Release a provisional binding whose work produced no local artifact, so the
+     * next candidate of an UNBOUND cell can be tried. Refused once anything was
+     * committed (see SlotRepository.releaseCellWork).
+     */
+    releaseWorkCas(slotId: string, targetId: string, workId: string): void;
     /** Record a cell's terminal state from the download/delivery outcome. */
     markCell(slotId: string, targetId: string, status: CellStatus, error?: string): void;
     /**
@@ -116,6 +177,18 @@ export declare class SlotCoordinator {
     applyOutcome(slotId: string, targetId: string, outcome: TargetOutcome): void;
     /** Promote a delivery_pending cell to submitted from a confirmed ACK. */
     markDelivered(slotId: string, targetId: string, workId: string, workType: string): void;
+    /**
+     * Decide what a `delivery_pending` cell owes, from the durable delivery
+     * ledger, and converge the FSM accordingly. Returns true when the scheduler
+     * must NOT run the target handler for it.
+     *
+     * Once an intent is durable the outbox owns the delivery: re-running selection
+     * could only produce a DIFFERENT work for the same logical item (and a second
+     * delivery, since the delivery idempotency key is work-scoped). A terminally
+     * failed delivery is converged explicitly — never "repaired" by picking
+     * another work behind the operator's back.
+     */
+    private settlePendingDelivery;
     private safeTransition;
     /** Cross-process execution lease. Duplicate triggers converge, never parallel-run. */
     claimRunLease(slotId: string, owner: string, leaseMs: number): boolean;

package/dist/scheduler/SlotCoordinator.js

@@ -4,6 +4,7 @@ exports.SlotCoordinator = exports.SLOT_HEARTBEAT_MS = exports.SLOT_LEASE_TTL_MS
 exports.timezoneForSchedule = timezoneForSchedule;
 const logger_1 = require("../logger");
 const OccurrenceResolver_1 = require("./OccurrenceResolver");
+const WorkIdentity_1 = require("./WorkIdentity");
 /**
  * Execution-lease TTL and heartbeat cadence.
  *
@@ -17,6 +18,13 @@ const OccurrenceResolver_1 = require("./OccurrenceResolver");
  */
 exports.SLOT_LEASE_TTL_MS = 3 * 60 * 1000;
 exports.SLOT_HEARTBEAT_MS = 30 * 1000;
+/** The delivery channel a scheduled cell publishes to (null = download-only). */
+function deliveryTargetOf(target) {
+    if (target.storageMode !== 'cache')
+        return null;
+    const name = target.delivery?.target;
+    return typeof name === 'string' && name.trim() ? name.trim() : null;
+}
 /**
  * Owns the Schedule Slot ledger for one scheduler run. A Slot is one durable
  * execution occurrence of a Schedule (NOT a morning/evening row). It ensures
@@ -29,8 +37,10 @@ exports.SLOT_HEARTBEAT_MS = 30 * 1000;
  */
 class SlotCoordinator {
     database;
-    constructor(database) {
+    delivery;
+    constructor(database, delivery) {
         this.database = database;
+        this.delivery = delivery;
     }
     /**
      * Resolve + validate the canonical occurrence for a trigger. Uses ONLY the
@@ -133,15 +143,65 @@ class SlotCoordinator {
                 continue;
             if (cell.status === 'submitted' || cell.status === 'no_candidate')
                 continue;
+            // A cell whose work already has a durable delivery intent is NOT the
+            // scheduler's to re-run: the OutboxWorker retries the SAME work to a
+            // terminal ACK. Re-selecting here is what let recovery stop pointing at the
+            // cell's own work (or enqueue a second one), so it is delegated instead.
+            if (cell.status === 'delivery_pending' && (0, WorkIdentity_1.isSingleWorkCell)(target) && this.settlePendingDelivery(slotId, target)) {
+                continue;
+            }
             out.push({ target, cell });
         }
         return out;
     }
+    /**
+     * Build the per-target execution contexts for one run, so every handler
+     * receives the cell's durable identity instead of just a TargetConfig.
+     *
+     * This is the boundary where the identity used to be dropped (`pending` was
+     * reduced to `p.target`), which is what let a resume re-rank and re-point the
+     * logical item at a different work.
+     */
+    executionContextsFor(slotId, entries) {
+        const contexts = new Map();
+        for (const { target, cell } of entries) {
+            if (!target.id || !cell)
+                continue;
+            const targetId = target.id;
+            contexts.set(targetId, {
+                slotId,
+                targetId,
+                lockedWorkId: cell.workId,
+                bind: (workId, workType) => this.lockWorkCas(slotId, targetId, workId, workType),
+                release: (workId) => this.releaseWorkCas(slotId, targetId, workId),
+            });
+        }
+        return contexts;
+    }
     /** Lock the selected work for a cell (first selection wins; retries keep it). */
     lockWork(slotId, targetId, workId, workType) {
         this.database.slots.ensureCell(slotId, targetId, workType);
         this.database.slots.lockCellWork(slotId, targetId, workId, workType);
     }
+    /**
+     * CAS-bind a cell to the work a handler is about to process. Returns the
+     * authoritative binding: when another worker already elected a different work,
+     * `won` is false and the caller MUST continue with the returned `workId`
+     * instead of its own candidate.
+     */
+    lockWorkCas(slotId, targetId, workId, workType) {
+        this.database.slots.ensureCell(slotId, targetId, workType);
+        const { cell, won } = this.database.slots.tryLockCellWork(slotId, targetId, workId, workType);
+        return { workId: cell.workId ?? workId, won };
+    }
+    /**
+     * Release a provisional binding whose work produced no local artifact, so the
+     * next candidate of an UNBOUND cell can be tried. Refused once anything was
+     * committed (see SlotRepository.releaseCellWork).
+     */
+    releaseWorkCas(slotId, targetId, workId) {
+        this.database.slots.releaseCellWork(slotId, targetId, workId);
+    }
     /** Record a cell's terminal state from the download/delivery outcome. */
     markCell(slotId, targetId, status, error) {
         const cell = this.database.slots.getCell(slotId, targetId);
@@ -203,6 +263,53 @@ class SlotCoordinator {
         this.database.slots.lockCellWork(slotId, targetId, workId, workType);
         this.safeTransition(slotId, targetId, 'submitted');
     }
+    /**
+     * Decide what a `delivery_pending` cell owes, from the durable delivery
+     * ledger, and converge the FSM accordingly. Returns true when the scheduler
+     * must NOT run the target handler for it.
+     *
+     * Once an intent is durable the outbox owns the delivery: re-running selection
+     * could only produce a DIFFERENT work for the same logical item (and a second
+     * delivery, since the delivery idempotency key is work-scoped). A terminally
+     * failed delivery is converged explicitly — never "repaired" by picking
+     * another work behind the operator's back.
+     */
+    settlePendingDelivery(slotId, target) {
+        const deliveryTarget = deliveryTargetOf(target);
+        if (!deliveryTarget || !this.delivery || !target.id)
+            return false;
+        const state = this.delivery.stateFor({ deliveryTarget, slotId, targetId: target.id });
+        switch (state.kind) {
+            case 'live':
+                logger_1.logger.info('Cell delivery still owned by the outbox; selection not re-run', {
+                    slot: slotId,
+                    target: target.id,
+                    deliveryTarget,
+                });
+                return true;
+            case 'confirmed':
+                // The ACK landed but the promotion was lost (crash between the delivery
+                // ledger write and the cell transition). Heal from the ledger — the work
+                // IS delivered, so re-selecting would post a second one.
+                logger_1.logger.info('Cell delivery already confirmed; promoting the cell from the ledger', {
+                    slot: slotId,
+                    target: target.id,
+                    workId: state.workId,
+                });
+                this.markDelivered(slotId, target.id, state.workId, state.workType);
+                return true;
+            case 'lost':
+                logger_1.logger.warn('Cell delivery failed terminally; failing the cell instead of re-selecting', {
+                    slot: slotId,
+                    target: target.id,
+                    reason: state.reason,
+                });
+                this.applyOutcome(slotId, target.id, { kind: 'failed', retryable: false, error: state.reason });
+                return true;
+            case 'unknown':
+                return false;
+        }
+    }
     safeTransition(slotId, targetId, next, error) {
         try {
             this.database.slots.transitionCell(slotId, targetId, next, error);

package/dist/scheduler/WorkIdentity.d.ts

@@ -0,0 +1,49 @@
+import { TargetConfig } from '../config';
+/**
+ * Work identity for a scheduled cell.
+ *
+ * Invariant: (slotId, targetId) -> ONE stable workId. The first selection wins,
+ * and every later crash / shutdown / lease recovery continues with THAT work.
+ * Re-running candidate selection on resume silently re-points the logical item
+ * at a different work (A -> B): the item then reports success while A sits
+ * downloaded-but-never-delivered, and if A's delivery intent was already
+ * durable both A and B get posted under different idempotency identities.
+ */
+export interface WorkBinding {
+    /** Authoritative work id for the cell after the attempt (the CAS winner). */
+    workId: string;
+    /** True when this caller established — or already held — the binding. */
+    won: boolean;
+}
+/**
+ * Per-cell execution context handed to a target handler, so the cell's identity
+ * travels with the work instead of being dropped at the dispatch boundary.
+ *
+ * `lockedWorkId` is an authoritative INPUT: when it is set, the handler must
+ * continue exactly that work and must not run ranking / topic selection /
+ * backfill / already-seen filtering. `bind()` is called for a candidate BEFORE
+ * any of its side effects, so a crash during the download can never resume the
+ * cell onto a different work.
+ */
+export interface TargetExecutionContext {
+    readonly slotId: string;
+    readonly targetId: string;
+    /** The work this logical item is already bound to; null for a fresh cell. */
+    readonly lockedWorkId: string | null;
+    /** CAS-bind the cell to `workId`; returns the authoritative binding. */
+    bind(workId: string, workType: string): WorkBinding;
+    /** Roll back a provisional binding for a work that produced no artifact. */
+    release(workId: string): void;
+}
+/**
+ * True when one cell of this target selects at most ONE work per run — the only
+ * shape the (slotId, targetId) -> workId invariant can hold for.
+ *
+ * A target that intentionally pulls N works per run (limit > 1, a novel series,
+ * a user feed) owns N works inside a single cell, so pinning that cell to one
+ * locked id on resume would silently shrink the run to a single work. Those keep
+ * per-run candidate selection; the work-identity contract covers single-work
+ * cells, which is what a scheduled "one post per slot" target is.
+ */
+export declare function isSingleWorkCell(target: TargetConfig): boolean;
+//# sourceMappingURL=WorkIdentity.d.ts.map