pixivflow 2.19.2 → 2.19.4

package/dist/commands/scheduler-runtime.js

@@ -57,7 +57,9 @@ const DeliveryDispatcher_1 = require("../delivery/DeliveryDispatcher");
 const token_maintenance_1 = require("../utils/token-maintenance");
 const schedules_1 = require("../scheduler/schedules");
 const SlotCoordinator_1 = require("../scheduler/SlotCoordinator");
+const DeliveryLedgerPort_1 = require("../delivery/DeliveryLedgerPort");
 const OutboxWorker_1 = require("../delivery/OutboxWorker");
+const settleDeliveryTerminal_1 = require("../delivery/settleDeliveryTerminal");
 const LegacyOutboxMigration_1 = require("../delivery/LegacyOutboxMigration");
 const NotificationPolicy_1 = require("../notification/NotificationPolicy");
 const node_crypto_1 = require("node:crypto");
@@ -240,22 +242,10 @@ async function createSchedulerRuntime(configPathArg) {
     const outboxWorker = new OutboxWorker_1.OutboxWorker(database, deliveryDispatcher, {
         retryBaseMs: config.delivery?.outboxRetryBaseMs,
         retryMaxMs: config.delivery?.outboxRetryMaxMs,
-        // A confirmed ACK promotes the delivery_pending cell to submitted.
+        // A confirmed ACK settles the owning Slot cell (submitted / duplicate /
+        // failed); see settleDeliveryTerminal for the invariant it enforces.
         onDeliveryTerminal: (deliveryId, ack) => {
-            const row = database.deliveries.getById(deliveryId);
-            if (!row || !row.slotId || !row.targetId)
-                return;
-            if (ack.kind === 'duplicate_existing') {
-                const coord = new SlotCoordinator_1.SlotCoordinator(database);
-                coord.applyOutcome(row.slotId, row.targetId, {
-                    kind: 'duplicate',
-                    workId: row.pixivId,
-                    reason: 'downstream attested historical duplicate',
-                });
-                return;
-            }
-            const coord = new SlotCoordinator_1.SlotCoordinator(database);
-            coord.markDelivered(row.slotId, row.targetId, row.pixivId, row.workType);
+            (0, settleDeliveryTerminal_1.settleDeliveryTerminal)(database, deliveryId, ack);
         },
     });
     const notificationPolicy = new NotificationPolicy_1.NotificationPolicy(database, config);
@@ -276,7 +266,7 @@ async function createSchedulerRuntime(configPathArg) {
             });
             return;
         }
-        const coordinator = new SlotCoordinator_1.SlotCoordinator(database);
+        const coordinator = new SlotCoordinator_1.SlotCoordinator(database, (0, DeliveryLedgerPort_1.createDeliveryLedgerPort)(database));
         // Ad-hoc/manual execution (run-once / explicit refetch) runs the download
         // plan WITHOUT a scheduled Slot: it can never mark a scheduled occurrence
         // complete or be resumed as one. Scheduled runs (cron/http/catchup) always
@@ -383,7 +373,14 @@ async function createSchedulerRuntime(configPathArg) {
         // re-runs a finished cell — that is what prevents a second post). Membership
         // comes from the materialized snapshot, so a config reload cannot add cells.
         const pending = slotCtx ? coordinator.pendingTargets(slotCtx.slotId, targets) : targets.map((target) => ({ target, cell: null }));
-        let runTargets = (onlyTarget ? pending.filter((p) => p.target.id === onlyTarget) : pending).map((p) => p.target);
+        const selected = onlyTarget ? pending.filter((p) => p.target.id === onlyTarget) : pending;
+        // Hand each cell its durable identity. Without this the handler cannot tell a
+        // first selection from a recovery, and would re-rank on resume — silently
+        // re-pointing the logical item at a different work than the one it owns.
+        const targetExecutionContexts = slotCtx
+            ? coordinator.executionContextsFor(slotCtx.slotId, selected)
+            : undefined;
+        let runTargets = selected.map((p) => p.target);
         if (slotCtx && runTargets.length === 0) {
             logger_1.logger.info('All slot cells already complete', { slot: slotCtx.slotId });
             coordinator.finish(slotCtx, schedule, targets);
@@ -424,6 +421,8 @@ async function createSchedulerRuntime(configPathArg) {
             });
         }
         const downloadManager = new DownloadManager_1.DownloadManager(scopedConfig, pixivClient, database, fileService);
+        if (targetExecutionContexts)
+            downloadManager.setTargetExecutionContexts(targetExecutionContexts);
         if (options.excludedWorkIds)
             downloadManager.setProcessedWorkIds(options.excludedWorkIds);
         activeDownloadManager = downloadManager;

package/dist/delivery/DeliveryAck.d.ts

@@ -35,6 +35,20 @@ export type DeliveryAck = {
     matchedKey?: string;
     raw?: unknown;
 }
+/**
+ * The provider accepted the request and persisted a record, but that record
+ * is in a TERMINAL FAILURE state (`failed`/`rejected`/`invalid`/`expired`).
+ * Nothing will ever be published from this intent, and because the provider
+ * keys its record by OUR idempotency_key, another attempt only returns the
+ * same failed record. Terminal: never retried, never reported as delivered.
+ */
+ | {
+    kind: 'remote_failed';
+    remoteId?: string;
+    remoteStatus: string;
+    error: string;
+    raw?: unknown;
+}
 /** Transient failure: timeouts, 5xx, 429, connection errors. Retryable. */
  | {
     kind: 'retryable_failure';

package/dist/delivery/DeliveryAck.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseDeliveryAck = parseDeliveryAck;
+/** Downstream record states that will never become a published delivery. */
+const TERMINAL_REMOTE_STATUSES = new Set(['failed', 'rejected', 'invalid', 'expired']);
 const DEFAULT_HINTS = {
     dataPath: 'data',
     idField: 'review_id',
@@ -49,6 +51,22 @@ function parseDeliveryAck(status, body, hints = {}) {
     const remoteId = typeof idValue === 'number' ? String(idValue) : asString(idValue);
     const remoteStatus = asString(rec[h.statusField]);
     const reused = rec[h.reusedField] === true;
+    // A 2xx envelope can still describe a RECORD THAT FAILED downstream: the
+    // provider persists the record before doing the real work, so "accepted" and
+    // "the persisted record is broken" arrive on the same HTTP status. The record
+    // is what gets published (and what a retry will find again), so its terminal
+    // state outranks the transport-level success of this request — otherwise a
+    // remote failure is recorded here as an end-to-end success.
+    const terminalStatus = remoteStatus?.trim().toLowerCase();
+    if (terminalStatus && TERMINAL_REMOTE_STATUSES.has(terminalStatus)) {
+        return {
+            kind: 'remote_failed',
+            remoteId,
+            remoteStatus: terminalStatus,
+            error: `delivery endpoint reported terminal status ${terminalStatus}`,
+            raw: body,
+        };
+    }
     if (!reused) {
         return { kind: 'accepted', remoteId, remoteStatus, raw: body };
     }

package/dist/delivery/DeliveryLedgerPort.d.ts

@@ -0,0 +1,14 @@
+import { Database } from '../storage/Database';
+import { SchedulerDeliveryPort } from '../scheduler/SlotCoordinator';
+/**
+ * Answers the slot FSM's only delivery question — "does this cell still have an
+ * owner downstream?" — from the durable delivery ledger.
+ *
+ * The distinction matters after a crash: a `delivery_pending` cell whose intent
+ * is still live must be left alone (the OutboxWorker retries THAT work to a
+ * terminal ACK), while one whose intent is terminally failed must be failed
+ * explicitly. Both are read from committed rows, so the answer is the same
+ * before and after a restart — which is exactly what a recovery decision needs.
+ */
+export declare function createDeliveryLedgerPort(database: Database): SchedulerDeliveryPort;
+//# sourceMappingURL=DeliveryLedgerPort.d.ts.map

package/dist/delivery/DeliveryLedgerPort.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeliveryLedgerPort = createDeliveryLedgerPort;
+/**
+ * Answers the slot FSM's only delivery question — "does this cell still have an
+ * owner downstream?" — from the durable delivery ledger.
+ *
+ * The distinction matters after a crash: a `delivery_pending` cell whose intent
+ * is still live must be left alone (the OutboxWorker retries THAT work to a
+ * terminal ACK), while one whose intent is terminally failed must be failed
+ * explicitly. Both are read from committed rows, so the answer is the same
+ * before and after a restart — which is exactly what a recovery decision needs.
+ */
+function createDeliveryLedgerPort(database) {
+    return {
+        stateFor({ deliveryTarget, slotId, targetId }) {
+            const rows = database.deliveries.listForCell(deliveryTarget, slotId, targetId);
+            if (rows.length === 0)
+                return { kind: 'unknown' };
+            const confirmed = rows.find((r) => r.status === 'delivered' || r.status === 'duplicate');
+            if (confirmed) {
+                return { kind: 'confirmed', workId: confirmed.pixivId, workType: confirmed.workType };
+            }
+            const pending = rows.filter((r) => r.status === 'pending');
+            // Still actionable = the outbox is going to try again. Its retry budget is
+            // the only thing that may converge this delivery, so keep hands off.
+            if (pending.some((r) => database.outbox.hasActionableDelivery(r.id))) {
+                return { kind: 'live' };
+            }
+            // Either the outbox exhausted its retries (dead/failed) or the intent was
+            // never queued. Nobody will converge it, and re-running selection would
+            // re-point the logical item at a different work — so fail it as-is.
+            if (pending.length > 0 || rows.some((r) => r.status === 'failed')) {
+                return {
+                    kind: 'lost',
+                    reason: 'delivery intent reached a terminal failure without an ACK; failing the cell instead of re-selecting a different work',
+                };
+            }
+            return { kind: 'unknown' };
+        },
+    };
+}
+//# sourceMappingURL=DeliveryLedgerPort.js.map

package/dist/delivery/OutboxWorker.js

@@ -312,6 +312,19 @@ class OutboxWorker {
                 });
                 this.onDeliveryTerminal?.(row.deliveryId, ack, payload);
                 break;
+            case 'remote_failed':
+                // The provider persisted the record, but it will never publish and the
+                // idempotency key pins us to that same record forever: retrying cannot
+                // change the outcome. Terminal, so the failure reaches the Slot instead
+                // of being masked as a delivered cell. Content is kept for inspection.
+                this.database.deliveries.recordAck(row.deliveryId, {
+                    status: 'failed',
+                    remoteId: ack.remoteId,
+                    remoteStatus: ack.remoteStatus,
+                    error: ack.error,
+                });
+                this.onDeliveryTerminal?.(row.deliveryId, ack, payload);
+                break;
             case 'permanent_failure':
                 // Deterministic rejection: still retry a couple times to survive a
                 // misconfigured blip, the outbox max-attempts then dead-letters it.

package/dist/delivery/settleDeliveryTerminal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Terminal-ACK settlement: the ONE place a confirmed downstream delivery ACK
+ * becomes a Slot cell state.
+ *
+ * The outbox worker already recorded the durable delivery ledger outcome before
+ * calling here; this maps that ack onto the Slot FSM. Keeping it as a named,
+ * dependency-light function (instead of an inline closure in the scheduler
+ * runtime) is what makes the central invariant directly testable:
+ *
+ *   REMOTE FAILURE MUST NOT BE REPORTED AS END-TO-END SUCCESS.
+ *
+ * A provider can answer HTTP 2xx while the record it persisted is terminally
+ * broken. The provider keys that record by OUR idempotency key, so a retry only
+ * returns the same broken record. Such an ack must settle the cell as `failed`,
+ * never promote it to `submitted` as though the content had been published.
+ */
+import type { Database } from '../storage/Database';
+import type { DeliveryAck } from './DeliveryAck';
+/**
+ * Apply a terminal delivery ack to the Slot cell that owns the delivery intent.
+ * Returns false when the delivery has no Slot cell (ad-hoc / batch runs), which
+ * is a normal no-op rather than an error.
+ */
+export declare function settleDeliveryTerminal(database: Database, deliveryId: string, ack: DeliveryAck): boolean;
+//# sourceMappingURL=settleDeliveryTerminal.d.ts.map

package/dist/delivery/settleDeliveryTerminal.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.settleDeliveryTerminal = settleDeliveryTerminal;
+const SlotCoordinator_1 = require("../scheduler/SlotCoordinator");
+/**
+ * Apply a terminal delivery ack to the Slot cell that owns the delivery intent.
+ * Returns false when the delivery has no Slot cell (ad-hoc / batch runs), which
+ * is a normal no-op rather than an error.
+ */
+function settleDeliveryTerminal(database, deliveryId, ack) {
+    const row = database.deliveries.getById(deliveryId);
+    if (!row || !row.slotId || !row.targetId)
+        return false;
+    const coord = new SlotCoordinator_1.SlotCoordinator(database);
+    if (ack.kind === 'duplicate_existing') {
+        // Historical duplicate: a record from a DIFFERENT intent already exists, so
+        // THIS intent published nothing. Never a successful submission.
+        coord.applyOutcome(row.slotId, row.targetId, {
+            kind: 'duplicate',
+            workId: row.pixivId,
+            reason: 'downstream attested historical duplicate',
+        });
+        return true;
+    }
+    if (ack.kind === 'remote_failed') {
+        // The downstream record is terminally broken, so nothing was published:
+        // settle the cell as failed instead of promoting it to submitted. Not
+        // retryable — the same idempotency key can only return that record.
+        coord.applyOutcome(row.slotId, row.targetId, {
+            kind: 'failed',
+            retryable: false,
+            error: `downstream reported terminal status ${ack.remoteStatus} (review ${ack.remoteId ?? 'unknown'})`,
+        });
+        return true;
+    }
+    // accepted / idempotent_replay: a confirmed ACK is the sole path to submitted.
+    coord.markDelivered(row.slotId, row.targetId, row.pixivId, row.workType);
+    return true;
+}
+//# sourceMappingURL=settleDeliveryTerminal.js.map

package/dist/download/DownloadManager.d.ts

@@ -5,6 +5,7 @@ import { IDatabase } from '../interfaces/IDatabase';
 import { IFileService } from '../interfaces/IFileService';
 import { DeliveryService } from '../delivery/DeliveryService';
 import { TargetOutcome } from '../scheduler/TargetOutcome';
+import { TargetExecutionContext } from '../scheduler/WorkIdentity';
 /**
  * Download Manager with Concurrency Control
  *
@@ -76,6 +77,10 @@ export declare class DownloadManager implements IDownloadManager {
         slotName: string;
         slotDate: string;
     };
+    /** Per-cell work identity for THIS run, keyed by target id (scheduled runs only). */
+    private targetExecutionContexts;
+    /** Publish the durable cell identity each handler must honour (scheduled runs). */
+    setTargetExecutionContexts(contexts: Map<string, TargetExecutionContext>): void;
     /**
      * Request cooperative cancellation of the current run. In-flight item
      * finishes; no further targets/items are started. runAllTargets() will

package/dist/download/DownloadManager.js

@@ -86,6 +86,12 @@ class DownloadManager {
     }
     /** Slot context propagated to delivery templates/outcomes for scheduled runs. */
     slotContext;
+    /** Per-cell work identity for THIS run, keyed by target id (scheduled runs only). */
+    targetExecutionContexts = new Map();
+    /** Publish the durable cell identity each handler must honour (scheduled runs). */
+    setTargetExecutionContexts(contexts) {
+        this.targetExecutionContexts = contexts;
+    }
     /**
      * Request cooperative cancellation of the current run. In-flight item
      * finishes; no further targets/items are started. runAllTargets() will
@@ -216,11 +222,15 @@ class DownloadManager {
         }
     }
     async dispatchTarget(target) {
+        // The cell identity must reach the handler or it cannot tell a first
+        // selection from a recovery: it would re-rank and silently re-point the
+        // logical item at a different work.
+        const execution = target.id ? this.targetExecutionContexts.get(target.id) : undefined;
         switch (target.type) {
             case 'illustration':
-                return await this.illustrationHandler.handle(target);
+                return await this.illustrationHandler.handle(target, execution);
             case 'novel':
-                return await this.novelHandler.handle(target);
+                return await this.novelHandler.handle(target, execution);
             default:
                 logger_1.logger.warn(`Unsupported target type ${target.type}`);
                 return { kind: 'failed', retryable: false, error: `unsupported target type ${target.type}` };

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

@@ -6,6 +6,7 @@ import { IllustrationDownloader } from '../IllustrationDownloader';
 import { DownloadPipeline } from '../pipeline/DownloadPipeline';
 import { DeliveryService } from '../../delivery/DeliveryService';
 import { TargetOutcome } from '../../scheduler/TargetOutcome';
+import { TargetExecutionContext } from '../../scheduler/WorkIdentity';
 import type { TopicPipelineFactory } from '../../topic/createTopicPipeline';
 export declare class IllustrationTargetHandler {
     private readonly client;
@@ -17,8 +18,14 @@ export declare class IllustrationTargetHandler {
     private readonly deliveryService?;
     /** Outcomes produced during this handle() call (deliveries + terminal non-matches). */
     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, illustrationDownloader: IllustrationDownloader, pipeline: DownloadPipeline, topicPipelineFactory?: TopicPipelineFactory | undefined, deliveryService?: DeliveryService | undefined);
-    handle(target: TargetConfig): Promise<TargetOutcome>;
+    handle(target: TargetConfig, execution?: TargetExecutionContext): Promise<TargetOutcome>;
     /** Reduce the outcomes collected while processing one target to one cell result. */
     private summarize;
     private classifyError;
@@ -35,6 +42,25 @@ export declare class IllustrationTargetHandler {
     private handleUserIllustrations;
     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 `illust` 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;
     /**
      * Turn a downloaded artifact into the target's business outcome. In cache

package/dist/download/handlers/IllustrationTargetHandler.js

@@ -5,6 +5,7 @@ const logger_1 = require("../../logger");
 const pixiv_date_utils_1 = require("../../utils/pixiv-date-utils");
 const errors_1 = require("../../utils/errors");
 const pixiv_utils_1 = require("../../utils/pixiv-utils");
+const WorkIdentity_1 = require("../../scheduler/WorkIdentity");
 const target_label_1 = require("../../utils/target-label");
 class IllustrationTargetHandler {
     client;
@@ -16,6 +17,12 @@ class IllustrationTargetHandler {
     deliveryService;
     /** Outcomes produced during this handle() call (deliveries + terminal non-matches). */
     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, illustrationDownloader, pipeline, topicPipelineFactory, deliveryService) {
         this.client = client;
         this.database = database;
@@ -25,8 +32,17 @@ class IllustrationTargetHandler {
         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(target);
+        }
         if (target.illustId) {
             await this.handleSingleIllustration(target);
             return this.summarize(target);
@@ -361,14 +377,96 @@ class IllustrationTargetHandler {
             stack: error instanceof Error ? error.stack : undefined,
         });
     }
-    async downloadAndDeliver(illust, tag, target) {
-        const artifact = await this.illustrationDownloader.downloadIllustration(illust, tag, {
-            aiMetadataCheck: target.aiMetadataCheck === true,
-            maxPageCount: target.maxPageCount,
-            includeDeliveryPreviews: Boolean(target.storageMode === 'cache' && target.delivery?.target?.trim()),
+    /**
+     * 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,
         });
-        if (!artifact)
+        const illustId = Number(lockedWorkId);
+        if (!Number.isFinite(illustId)) {
+            this.outcomes.push({
+                kind: 'failed',
+                retryable: false,
+                error: `LOCKED_WORK_UNAVAILABLE: cell work id "${lockedWorkId}" is not a valid illustration id`,
+            });
             return;
+        }
+        try {
+            const detail = await this.client.getIllustration(illustId);
+            await this.downloadAndDeliver(detail, displayTag, 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 illustration ${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 `illust` 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(illust, tag, target) {
+        const execution = this.execution;
+        const workId = String(illust.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, 'illustration');
+            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 = null;
+        try {
+            artifact = await this.illustrationDownloader.downloadIllustration(illust, tag, {
+                aiMetadataCheck: target.aiMetadataCheck === true,
+                maxPageCount: target.maxPageCount,
+                includeDeliveryPreviews: Boolean(target.storageMode === 'cache' && target.delivery?.target?.trim()),
+            });
+        }
+        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 enqueue throws below, recovery must resume THIS work — never release.
         this.recordArtifactOutcome(artifact, target);
     }
     /**

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