pixivflow 2.19.1 → 2.19.3

package/dist/commands/ExecuteSlotCommand.js

@@ -135,7 +135,7 @@ class ExecuteSlotCommand extends Command_1.BaseCommand {
                         (0, runDiagnostics_1.recordRunError)(outcome.error);
                 },
                 ...(excludedWorkIds ? { excludedWorkIds } : {}),
-            }), timeoutMs, () => runtime.cancelActive(`batch timeout after ${timeoutMs}ms`), `slot ${slotId}`);
+            }), timeoutMs, () => runtime.cancelActive(`batch timeout after ${timeoutMs}ms`, 'timeout'), `slot ${slotId}`);
             // Bounded drain: deliveries created by this run get one chance to confirm
             // before we report. Rows that cannot finish now stay durable and are
             // resolved by the control plane's reconciliation, never by a blind resend.

package/dist/commands/SchedulerCommand.js

@@ -57,7 +57,9 @@ class SchedulerCommand extends Command_1.BaseCommand {
                 telemetry: {
                     beginRun: () => runtime.database.getOverviewStats().totalDownloads,
                     endRun: () => runtime.database.getOverviewStats().totalDownloads,
-                    requestCancel: (reason) => runtime.cancelActive(reason),
+                    // `timeout`: the daemon stays alive, so the run's Slot must be taken
+                    // terminal (the abort path does that) instead of staying recoverable.
+                    requestCancel: (reason) => runtime.cancelActive(reason, 'timeout'),
                 },
             });
             const status = manager.start(runtime.config);

package/dist/commands/SchedulerRunOnceCommand.js

@@ -53,7 +53,7 @@ class SchedulerRunOnceCommand extends Command_1.BaseCommand {
                 // adhoc: a manual/operator run executes the download plan but never
                 // opens a scheduled Slot, so it can neither mark a scheduled
                 // occurrence complete nor be resumed as one. Explicit replacement.
-                runtime.runJob(runtime.config, plan, { adhoc: true, triggerSource: 'manual', onlyTarget: targetFilter }), timeoutMs, () => runtime.cancelActive(`run timeout after ${timeoutMs}ms`), `plan ${plan.id}`);
+                runtime.runJob(runtime.config, plan, { adhoc: true, triggerSource: 'manual', onlyTarget: targetFilter }), timeoutMs, () => runtime.cancelActive(`run timeout after ${timeoutMs}ms`, 'timeout'), `plan ${plan.id}`);
             }
             // Flush deliveries/notifications created by this one-shot before exit.
             // A bounded drain: durable rows survive if they cannot finish now and the

package/dist/commands/scheduler-runtime.d.ts

@@ -51,6 +51,29 @@ export type ExecutionMode = (typeof EXECUTION_MODES)[number];
 export declare function withDeliveryMode<T extends {
     delivery?: unknown;
 }>(targets: T[], mode: ExecutionMode | undefined): T[];
+/**
+ * Who asked for the cancellation, which decides whether the abandoned Slot is
+ * allowed to stay recoverable.
+ *
+ *  - `timeout`: a watchdog inside this process (scheduler timeout, run-once or
+ *    execute-slot bound). The process stays up, so nothing will ever finish the
+ *    Slot — it must be terminalised, or the recovery sweep re-dispatches the
+ *    same occurrence on every tick forever.
+ *  - `shutdown`: the process is going away. The Slot is deliberately left
+ *    non-terminal so recovery resumes the same occurrence after restart; no
+ *    worker survives to duplicate it.
+ */
+export type CancelOrigin = 'timeout' | 'shutdown';
+/**
+ * Decide a scheduled run's Slot fate when `runAllTargets()` aborts abnormally
+ * instead of reporting per-target failures.
+ *
+ * Returning `false` leaves the Slot recoverable, which is only correct when the
+ * process is genuinely going away — because `recoverableSlots()` treats a
+ * released/NULL lease as "recorded but never claimed", so a live process that
+ * merely drops its lease is re-dispatched on every recovery tick, forever.
+ */
+export declare function shouldTerminaliseAbortedSlot(origin: CancelOrigin | null, slotAbandoned: boolean): boolean;
 export interface SchedulerRuntime {
     config: StandaloneConfig;
     database: Database;
@@ -59,8 +82,14 @@ export interface SchedulerRuntime {
     tokenMaintenance: ReturnType<typeof createTokenMaintenanceService>;
     /** Run one schedule's enabled targets once (the same job the cron fires). */
     runJob(snapshot: StandaloneConfig, schedule: ScheduleConfig, options?: RunJobOptions): Promise<void>;
-    /** Cancel the in-flight download plan, if any. */
-    cancelActive(reason: string): void;
+    /**
+     * Cancel the in-flight download plan, if any holding a Slot.
+     *
+     * `origin` states whether this process is staying alive (`timeout`: the
+     * run is finished and its Slot must be terminalised) or going away
+     * (`shutdown`: leave the Slot non-terminal so recovery resumes it).
+     */
+    cancelActive(reason: string, origin?: CancelOrigin): void;
     /**
      * The active run never settled after its timeout and drain window. Stop
      * renewing its lease and take its Slot terminal so recovery cannot re-dispatch

package/dist/commands/scheduler-runtime.js

@@ -43,6 +43,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EXECUTION_MODES = void 0;
 exports.withDeliveryMode = withDeliveryMode;
+exports.shouldTerminaliseAbortedSlot = shouldTerminaliseAbortedSlot;
 exports.notifyScheduleFailure = notifyScheduleFailure;
 exports.createSchedulerRuntime = createSchedulerRuntime;
 exports.runWithTimeout = runWithTimeout;
@@ -56,6 +57,7 @@ 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 LegacyOutboxMigration_1 = require("../delivery/LegacyOutboxMigration");
 const NotificationPolicy_1 = require("../notification/NotificationPolicy");
@@ -74,6 +76,23 @@ function withDeliveryMode(targets, mode) {
         return targets;
     return targets.map((target) => (target.delivery ? { ...target, delivery: undefined } : target));
 }
+/**
+ * Decide a scheduled run's Slot fate when `runAllTargets()` aborts abnormally
+ * instead of reporting per-target failures.
+ *
+ * Returning `false` leaves the Slot recoverable, which is only correct when the
+ * process is genuinely going away — because `recoverableSlots()` treats a
+ * released/NULL lease as "recorded but never claimed", so a live process that
+ * merely drops its lease is re-dispatched on every recovery tick, forever.
+ */
+function shouldTerminaliseAbortedSlot(origin, slotAbandoned) {
+    // The abandon path already wrote a terminal `failed`; rolling up again would
+    // only overwrite it when the wedged job finally settles.
+    if (slotAbandoned)
+        return false;
+    // Shutdown is not a failure: recovery is meant to resume this occurrence.
+    return origin !== 'shutdown';
+}
 /**
  * Open the pixivflow database with a startup integrity check. A structurally
  * corrupt file (quick_check failure) is isolated aside and replaced with a
@@ -209,6 +228,13 @@ async function createSchedulerRuntime(configPathArg) {
      * Set while a lease is held and cleared as soon as it is released.
      */
     let activeLeaseHooks = null;
+    /**
+     * Why the in-flight run was cancelled, if it was. This is what lets the abort
+     * path tell a CRASH (nothing runs here — the process is gone) apart from an
+     * ABANDONMENT (this process is alive and will never touch the Slot again).
+     * `null` while no cancellation has been requested for the current run.
+     */
+    let activeAbortOrigin = null;
     // Independently-pumped durable outbox (content + notifications). Started in
     // the long-running scheduler daemon; run-once drains explicitly before exit.
     const deliveryDispatcher = new DeliveryDispatcher_1.DeliveryDispatcher(config.delivery, buildProxyUrl(config.network));
@@ -251,7 +277,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
@@ -311,6 +337,9 @@ async function createSchedulerRuntime(configPathArg) {
             // Only the process that actually owns the lease may report the slot as
             // running; the accepting adapter records it as pending instead.
             coordinator.markRunning(activeSlot.slotId);
+            // This run owns the Slot now: any cancellation recorded against a previous
+            // run must not decide how THIS run's abort is handled.
+            activeAbortOrigin = null;
             let cancelled = false;
             const heartbeat = setInterval(() => {
                 // A cancelled/timed-out run must stop renewing its lease. An infinitely
@@ -355,7 +384,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);
@@ -396,6 +432,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;
@@ -451,9 +489,24 @@ async function createSchedulerRuntime(configPathArg) {
         }
         catch (error) {
             if (!slotCtx || !(error instanceof Error) || !/^All \d+ target\(s\) failed\./.test(error.message)) {
-                // Abnormal abort: no roll-up is possible, so hand the slot back now
-                // instead of holding it until the lease TTL expires. Recovery sees a
-                // non-terminal slot with no live lease and resumes the SAME occurrence.
+                // Abnormal abort. Two very different situations land here, and treating
+                // them as one is what produced the production loop:
+                //
+                //  - this process cancelled itself (scheduler timeout / watchdog) and is
+                //    still alive. It will never touch the Slot again, so releasing the
+                //    lease while leaving the status `running` makes the Slot look exactly
+                //    like a crashed worker: `recoverableSlots()` matches a NULL lease on
+                //    purpose (its "recorded but never claimed" case), so the recovery
+                //    sweep re-dispatches the SAME occurrence on every tick, forever.
+                //    Terminalise it instead: the occurrence is finished, and failed.
+                //
+                //  - the process is going away (`shutdown`). Deliberately leave the Slot
+                //    non-terminal so recovery resumes the same occurrence after restart.
+                if (slotCtx && shouldTerminaliseAbortedSlot(activeAbortOrigin, slotAbandoned)) {
+                    coordinator.finish(slotCtx, schedule, targets);
+                }
+                // Hand the lease back either way: a terminal Slot cannot be re-dispatched,
+                // and a non-terminal one (shutdown) must not wait for its TTL to expire.
                 releaseLease?.();
                 throw error;
             }
@@ -491,12 +544,13 @@ async function createSchedulerRuntime(configPathArg) {
         });
         logger_1.logger.info('='.repeat(60));
     };
-    const cancelActive = (reason) => {
+    const cancelActive = (reason, origin = 'timeout') => {
+        activeAbortOrigin = origin;
         activeDownloadManager?.cancel(reason);
         // Scheduler timeout / process shutdown also stop the lease heartbeat. The run
         // is on its way out (or about to be killed with the process), so it must not
-        // keep the slot locked while it unwinds. A shutdown deliberately leaves the
-        // slot NON-terminal: recovery resumes the same occurrence after restart.
+        // keep the slot locked while it unwinds. Whether the Slot is then terminalised
+        // or left recoverable is decided by `origin` in the abort path of runJob.
         activeLeaseHooks?.stopHeartbeat();
     };
     const abandonActiveRun = (reason) => {
@@ -507,7 +561,7 @@ async function createSchedulerRuntime(configPathArg) {
     };
     const close = () => {
         outboxWorker.stop();
-        cancelActive('process shutdown');
+        cancelActive('process shutdown', 'shutdown');
         if (tokenMaintenance) {
             tokenMaintenance.stop();
         }

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.d.ts

@@ -78,6 +78,8 @@ export declare class OutboxWorker {
     private recordMediaFallback;
     private recordEvent;
     private process;
+    /** Terminal delivery failure: audit it, release the delivery, notify the hooks. */
+    private deadLetter;
     private handleDeliveryAck;
     private cleanup;
 }

package/dist/delivery/OutboxWorker.js

@@ -245,24 +245,21 @@ class OutboxWorker {
             return 'done';
         }
         catch (error) {
-            // Transport-level error (fetch threw) or ack-classified failure: retryable.
             const message = (0, redact_1.redactError)(error).slice(0, 1000);
             const { errorClass } = (0, errorClass_1.classifyError)(error);
+            // A local configuration error is deterministic: every attempt re-reads the
+            // same config, so retrying only parks the row in `retry_wait` until its
+            // attempt budget runs out. Dead-letter it now so it is visible instead.
+            if (errorClass === 'configuration_error') {
+                this.database.outbox.markDead(row.id, message);
+                this.deadLetter(row, `${message} (configuration error)`, errorClass);
+                return 'dead';
+            }
+            // Transport-level error (fetch threw) or ack-classified failure: retryable.
             const delay = backoffDelayMs(row.attempts + 1, this.retryBaseMs, this.retryMaxMs);
             const status = this.database.outbox.markRetry(row.id, Date.now() + delay, message);
             if (status === 'dead') {
-                logger_1.logger.error('Outbox item dead after max attempts', { outboxId: row.id, kind: row.kind, error: message });
-                this.recordEvent(row, {
-                    event: 'outbox.dead',
-                    errorClass,
-                    retryable: false,
-                    countsAsAttempt: 1,
-                    detail: { attempt: row.attempts + 1 },
-                });
-                this.onDead?.(row, message);
-                if (row.deliveryId) {
-                    this.database.deliveries.recordAck(row.deliveryId, { status: 'failed', error: message });
-                }
+                this.deadLetter(row, message, errorClass);
             }
             else {
                 logger_1.logger.warn('Outbox item will retry', { outboxId: row.id, kind: row.kind, attempt: row.attempts + 1, delayMs: delay });
@@ -277,6 +274,21 @@ class OutboxWorker {
             return status;
         }
     }
+    /** Terminal delivery failure: audit it, release the delivery, notify the hooks. */
+    deadLetter(row, message, errorClass) {
+        logger_1.logger.error('Outbox item dead', { outboxId: row.id, kind: row.kind, errorClass, error: message });
+        this.recordEvent(row, {
+            event: 'outbox.dead',
+            errorClass,
+            retryable: false,
+            countsAsAttempt: 1,
+            detail: { attempt: row.attempts + 1 },
+        });
+        this.onDead?.(row, message);
+        if (row.deliveryId) {
+            this.database.deliveries.recordAck(row.deliveryId, { status: 'failed', error: message });
+        }
+    }
     async handleDeliveryAck(row, ack, payload) {
         if (!row.deliveryId)
             return;

package/dist/delivery/errorClass.d.ts

@@ -2,7 +2,7 @@
  * Tiny pure error classification for delivery attempts.
  * Maps a thrown error / HTTP status to a stable audit category.
  */
-export type DeliveryErrorClass = 'dependency_not_ready' | 'network_timeout' | 'rate_limited' | 'remote_5xx' | 'remote_4xx' | 'invalid_payload' | 'telegram_send_failed' | 'duplicate' | 'internal_error';
+export type DeliveryErrorClass = 'dependency_not_ready' | 'network_timeout' | 'rate_limited' | 'remote_5xx' | 'remote_4xx' | 'invalid_payload' | 'telegram_send_failed' | 'configuration_error' | 'duplicate' | 'internal_error';
 export interface ErrorClassification {
     errorClass: DeliveryErrorClass;
     retryable: boolean;

package/dist/delivery/errorClass.js

@@ -4,6 +4,13 @@ exports.classifyError = classifyError;
 /** Classify one failed delivery attempt from its thrown error and/or HTTP status. */
 function classifyError(error, status) {
     const message = error instanceof Error ? error.message : String(error ?? '');
+    // A local ConfigError is thrown before any network call and is deterministic:
+    // retrying re-reads the exact same config, so the attempt budget only parks the
+    // row in `retry_wait` for hours. Terminal for the outbox.
+    if (error?.name === 'ConfigError' ||
+        /does not configure|unsupported delivery target/i.test(message)) {
+        return { errorClass: 'configuration_error', retryable: false };
+    }
     // Explicit HTTP status wins when present.
     if (status === 429)
         return { errorClass: 'rate_limited', retryable: true };

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);
     }
     /**