pixivflow 2.18.0 → 2.19.0

package/dist/scheduler/Scheduler.d.ts

@@ -6,6 +6,19 @@ import { ScheduleRunOptions } from './OccurrenceResolver';
  * cap so a wedged download run cannot occupy the scheduler queue forever.
  */
 export declare const DEFAULT_SCHEDULE_TIMEOUT_MS: number;
+/**
+ * How long a run may keep draining after its timeout fired before the scheduler
+ * gives up on it.
+ *
+ * Cancellation is cooperative, so a request that never returns (or a retry loop
+ * that ignores the abort) can outlive the timeout indefinitely. Awaiting that
+ * forever is what kept a timed-out run holding its Slot lease: the scheduler
+ * stayed `running`, the runtime kept heart-beating, and the occurrence could
+ * never be recovered. After this window the run is declared abandoned — the
+ * scheduler slot is freed and the runtime takes the Slot terminal — so a wedged
+ * job degrades into one recorded failure instead of a permanent hang.
+ */
+export declare const ABORT_DRAIN_MS: number;
 /**
  * Optional integration hooks allowing the host command to provide real
  * accounting data and cooperative cancellation to the scheduler.
@@ -29,6 +42,18 @@ export interface JobFailure {
     consecutiveFailures: number;
     stopped: boolean;
 }
+/**
+ * Reported when a run was still executing after its timeout AND the drain window
+ * expired, so it can never be awaited to completion. The host must treat the run
+ * as finished: stop renewing any lease it owns and take its Slot terminal, or a
+ * recovery sweep will re-dispatch the same occurrence while this run is alive.
+ */
+export interface JobAbandoned {
+    scheduleId: string;
+    executionNumber: number;
+    errorMessage: string | null;
+    drainWindowMs: number;
+}
 /** Admission is acquired before timeout/accounting starts. */
 export interface JobAdmissionController {
     acquire(scheduleId: string): Promise<JobLease | null>;
@@ -40,6 +65,7 @@ export declare class Scheduler {
     private readonly scheduleId;
     private readonly admission?;
     private readonly onFailure?;
+    private readonly onAbandoned?;
     private task;
     private job;
     private running;
@@ -47,9 +73,10 @@ export declare class Scheduler {
     private executionCount;
     private consecutiveFailures;
     private timeoutHandle;
+    private drainHandle;
     private stopped;
     private pending;
-    constructor(config: SchedulerConfig, database?: Database | undefined, telemetry?: JobTelemetry | undefined, scheduleId?: string, admission?: JobAdmissionController | undefined, onFailure?: ((failure: JobFailure) => Promise<void> | void) | undefined);
+    constructor(config: SchedulerConfig, database?: Database | undefined, telemetry?: JobTelemetry | undefined, scheduleId?: string, admission?: JobAdmissionController | undefined, onFailure?: ((failure: JobFailure) => Promise<void> | void) | undefined, onAbandoned?: ((abandoned: JobAbandoned) => Promise<void> | void) | undefined);
     start(job: (options?: ScheduleRunOptions) => Promise<void>): void;
     /**
      * Arm the scheduler for external/manual triggers (runNow) WITHOUT registering

package/dist/scheduler/Scheduler.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Scheduler = exports.DEFAULT_SCHEDULE_TIMEOUT_MS = void 0;
+exports.Scheduler = exports.ABORT_DRAIN_MS = exports.DEFAULT_SCHEDULE_TIMEOUT_MS = void 0;
 const node_cron_1 = __importDefault(require("node-cron"));
 const logger_1 = require("../logger");
 const errors_1 = require("../utils/errors");
@@ -12,6 +12,19 @@ const errors_1 = require("../utils/errors");
  * cap so a wedged download run cannot occupy the scheduler queue forever.
  */
 exports.DEFAULT_SCHEDULE_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * How long a run may keep draining after its timeout fired before the scheduler
+ * gives up on it.
+ *
+ * Cancellation is cooperative, so a request that never returns (or a retry loop
+ * that ignores the abort) can outlive the timeout indefinitely. Awaiting that
+ * forever is what kept a timed-out run holding its Slot lease: the scheduler
+ * stayed `running`, the runtime kept heart-beating, and the occurrence could
+ * never be recovered. After this window the run is declared abandoned — the
+ * scheduler slot is freed and the runtime takes the Slot terminal — so a wedged
+ * job degrades into one recorded failure instead of a permanent hang.
+ */
+exports.ABORT_DRAIN_MS = 30 * 1000;
 class Scheduler {
     config;
     database;
@@ -19,6 +32,7 @@ class Scheduler {
     scheduleId;
     admission;
     onFailure;
+    onAbandoned;
     task = null;
     job = null;
     running = false;
@@ -26,15 +40,17 @@ class Scheduler {
     executionCount = 0;
     consecutiveFailures = 0;
     timeoutHandle = null;
+    drainHandle = null;
     stopped = false;
     pending = false;
-    constructor(config, database, telemetry, scheduleId = 'default', admission, onFailure) {
+    constructor(config, database, telemetry, scheduleId = 'default', admission, onFailure, onAbandoned) {
         this.config = config;
         this.database = database;
         this.telemetry = telemetry;
         this.scheduleId = scheduleId;
         this.admission = admission;
         this.onFailure = onFailure;
+        this.onAbandoned = onAbandoned;
     }
     start(job) {
         this.arm(job, true);
@@ -181,6 +197,11 @@ class Scheduler {
             scheduleId: this.scheduleId,
         });
         // Set up timeout if configured
+        let abandoned = false;
+        let resolveDrainExpired = null;
+        const drainExpired = new Promise((resolve) => {
+            resolveDrainExpired = resolve;
+        });
         if (this.config.timeout) {
             this.timeoutHandle = setTimeout(() => {
                 if (this.running) {
@@ -194,15 +215,33 @@ class Scheduler {
                     catch (cancelError) {
                         logger_1.logger.warn('Failed to request job cancellation', { error: cancelError });
                     }
-                    // Keep running=true until the aborted job actually settles so the
-                    // concurrent-run guard stays correct during the drain window.
+                    // Bounded drain. requestCancel is cooperative, so this run is only
+                    // guaranteed to be *asked* to stop; a request that ignores the abort
+                    // would otherwise hold `running` (and, through the host, the Slot
+                    // lease) for good. After the drain window the run is abandoned.
+                    this.drainHandle = setTimeout(() => {
+                        abandoned = true;
+                        errorMessage =
+                            `Execution timeout after ${this.config.timeout}ms; the job was still running after the ` +
+                                `${exports.ABORT_DRAIN_MS}ms drain window and has been abandoned`;
+                        logger_1.logger.error('Job did not settle within the drain window; abandoning it', {
+                            scheduleId: this.scheduleId,
+                            drainWindowMs: exports.ABORT_DRAIN_MS,
+                        });
+                        resolveDrainExpired?.();
+                    }, exports.ABORT_DRAIN_MS);
+                    this.drainHandle.unref?.();
+                    // Keep running=true until the aborted job settles (or the drain
+                    // expires) so the concurrent-run guard stays correct.
                 }
             }, this.config.timeout);
+            this.timeoutHandle.unref?.();
         }
+        const jobPromise = this.executeWithTracking(job, (count) => {
+            itemsDownloaded = count;
+        }, triggerOptions);
         try {
-            await this.executeWithTracking(job, (count) => {
-                itemsDownloaded = count;
-            });
+            await (this.config.timeout ? Promise.race([jobPromise, drainExpired]) : jobPromise);
             if (timeoutOccurred) {
                 status = 'timeout';
                 this.consecutiveFailures++;
@@ -245,6 +284,38 @@ class Scheduler {
                 clearTimeout(this.timeoutHandle);
                 this.timeoutHandle = null;
             }
+            if (this.drainHandle) {
+                clearTimeout(this.drainHandle);
+                this.drainHandle = null;
+            }
+            if (abandoned) {
+                // The job is still running somewhere. Its abort signal has been fired, so
+                // it unwinds at the next checkpoint, but we stop waiting for it: capture
+                // its eventual rejection (nothing else can) and let the host finish the
+                // bookkeeping it owns — stop the lease heartbeat and take the Slot
+                // terminal — so a recovery sweep cannot re-dispatch the same occurrence
+                // while this run is still alive.
+                void jobPromise.catch((error) => {
+                    logger_1.logger.warn('Abandoned job settled after the drain window', {
+                        scheduleId: this.scheduleId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                });
+                try {
+                    await this.onAbandoned?.({
+                        scheduleId: this.scheduleId,
+                        executionNumber,
+                        errorMessage,
+                        drainWindowMs: exports.ABORT_DRAIN_MS,
+                    });
+                }
+                catch (error) {
+                    logger_1.logger.warn('Failed to report an abandoned job', {
+                        scheduleId: this.scheduleId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
             const endTime = new Date();
             const duration = endTime.getTime() - startTime.getTime();
             // Log to database if available
@@ -298,6 +369,10 @@ class Scheduler {
             clearTimeout(this.timeoutHandle);
             this.timeoutHandle = null;
         }
+        if (this.drainHandle) {
+            clearTimeout(this.drainHandle);
+            this.drainHandle = null;
+        }
         logger_1.logger.info('Scheduler stopped', {
             totalExecutions: this.executionCount,
             consecutiveFailures: this.consecutiveFailures,

package/dist/scheduler/SlotCoordinator.d.ts

@@ -3,6 +3,19 @@ import { Database } from '../storage/Database';
 import { CellStatus, SlotItemRecord, SlotRecord, SlotStatus } from '../storage/repositories/SlotRepository';
 import { TriggerSource } from './OccurrenceResolver';
 import { TargetOutcome } from './TargetOutcome';
+/**
+ * Execution-lease TTL and heartbeat cadence.
+ *
+ * These describe how fast a DEAD worker is noticed — they are deliberately
+ * unrelated to `schedule.timeout` (which caps how long a run may take). Tying
+ * the two together made a crashed worker hold its slot for up to 31 minutes
+ * before any other trigger could resume it. A live worker renews its lease every
+ * SLOT_HEARTBEAT_MS, so the worst-case recovery delay after a crash/restart is
+ * about SLOT_LEASE_TTL_MS. The TTL stays comfortably above the heartbeat so an
+ * occasional stalled event loop cannot make a healthy run look dead.
+ */
+export declare const SLOT_LEASE_TTL_MS: number;
+export declare const SLOT_HEARTBEAT_MS: number;
 /**
  * Durable execution context attached to a run. A scheduled occurrence always
  * has a slotId; an ad-hoc/manual run has none (it never touches the slot ledger).
@@ -62,13 +75,25 @@ export declare class SlotCoordinator {
      */
     resolveOccurrence(schedule: ScheduleConfig, config: StandaloneConfig, triggerSource: TriggerSource, at?: Date, requestedSlotName?: string): SlotResolveResult;
     /**
-     * Open (or resume) an occurrence and snapshot its target membership on first
-     * creation. A later config reload cannot add/remove cells for this occurrence.
+     * Durably open (or resume) an occurrence and snapshot its target membership
+     * on first creation. A later config reload cannot add/remove cells for this
+     * occurrence.
+     *
+     * This deliberately does NOT mark the slot `running`: the HTTP trigger calls
+     * it before dispatch so that a crash between "accepted" and "claimed" still
+     * leaves a durable `pending` row for reconciliation to pick up (see
+     * `markRunning` and MultiScheduleManager's recovery loop).
      */
-    begin(slot: SlotContext, schedule: ScheduleConfig, targets: TargetConfig[]): {
+    prepare(slot: SlotContext, schedule: ScheduleConfig, targets: TargetConfig[]): {
         slotRec: SlotRecord;
         alreadyCompleted: boolean;
     };
+    /**
+     * Mark the occurrence as actually executing. Called by the worker that has
+     * already won the cross-process lease (never by the accepting adapter), so a
+     * slot is never reported `running` by a process that is not running it.
+     */
+    markRunning(slotId: string): void;
     /**
      * The targets that still need to run for this occurrence. Membership comes
      * from the materialized snapshot (stable), intersected with the targets the

package/dist/scheduler/SlotCoordinator.js

@@ -1,9 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SlotCoordinator = void 0;
+exports.SlotCoordinator = exports.SLOT_HEARTBEAT_MS = exports.SLOT_LEASE_TTL_MS = void 0;
 exports.timezoneForSchedule = timezoneForSchedule;
 const logger_1 = require("../logger");
 const OccurrenceResolver_1 = require("./OccurrenceResolver");
+/**
+ * Execution-lease TTL and heartbeat cadence.
+ *
+ * These describe how fast a DEAD worker is noticed — they are deliberately
+ * unrelated to `schedule.timeout` (which caps how long a run may take). Tying
+ * the two together made a crashed worker hold its slot for up to 31 minutes
+ * before any other trigger could resume it. A live worker renews its lease every
+ * SLOT_HEARTBEAT_MS, so the worst-case recovery delay after a crash/restart is
+ * about SLOT_LEASE_TTL_MS. The TTL stays comfortably above the heartbeat so an
+ * occasional stalled event loop cannot make a healthy run look dead.
+ */
+exports.SLOT_LEASE_TTL_MS = 3 * 60 * 1000;
+exports.SLOT_HEARTBEAT_MS = 30 * 1000;
 /**
  * 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
@@ -58,10 +71,16 @@ class SlotCoordinator {
         };
     }
     /**
-     * Open (or resume) an occurrence and snapshot its target membership on first
-     * creation. A later config reload cannot add/remove cells for this occurrence.
+     * Durably open (or resume) an occurrence and snapshot its target membership
+     * on first creation. A later config reload cannot add/remove cells for this
+     * occurrence.
+     *
+     * This deliberately does NOT mark the slot `running`: the HTTP trigger calls
+     * it before dispatch so that a crash between "accepted" and "claimed" still
+     * leaves a durable `pending` row for reconciliation to pick up (see
+     * `markRunning` and MultiScheduleManager's recovery loop).
      */
-    begin(slot, schedule, targets) {
+    prepare(slot, schedule, targets) {
         const targetIds = targets.map((t) => t.id).filter((id) => Boolean(id));
         const { slot: slotRec, created } = this.database.slots.getOrCreateSlot(slot.slotId, {
             scheduleId: slot.scheduleId,
@@ -86,9 +105,16 @@ class SlotCoordinator {
         if (slotRec.status === 'success' || slotRec.status === 'partial') {
             return { slotRec, alreadyCompleted: true };
         }
-        this.database.slots.markSlotStatus(slot.slotId, 'running');
         return { slotRec, alreadyCompleted: false };
     }
+    /**
+     * Mark the occurrence as actually executing. Called by the worker that has
+     * already won the cross-process lease (never by the accepting adapter), so a
+     * slot is never reported `running` by a process that is not running it.
+     */
+    markRunning(slotId) {
+        this.database.slots.markSlotStatus(slotId, 'running');
+    }
     /**
      * The targets that still need to run for this occurrence. Membership comes
      * from the materialized snapshot (stable), intersected with the targets the

package/dist/storage/repositories/SlotRepository.d.ts

@@ -115,6 +115,34 @@ export declare class SlotRepository extends BaseRepository {
     };
     /** Slots whose lease expired while still non-terminal (crashed workers). */
     slotsWithStaleLease(now?: number): string[];
+    /**
+     * Non-terminal slots no live worker currently owns, and which therefore should
+     * be re-dispatched.
+     *
+     * Two distinct situations qualify, and both must be recovered:
+     *  - `lease_until <= now`: a worker claimed the slot and then died (crash, OOM,
+     *    machine stop, redeploy). Its heartbeat stopped, so the lease expired.
+     *  - `lease_until IS NULL`: a durable slot was recorded (accepted) but no worker
+     *    ever claimed it — e.g. the process died between "occurrence recorded" and
+     *    "lease claimed". Nothing else will ever pick that up.
+     *
+     * Callers must NOT clear the lease from here. Recovery re-DISPATCHES the slot
+     * and the atomic CAS in `claimSlotLease` still elects the single winner, so a
+     * merely slow (but healthy) owner that heartbeats mid-scan cannot be robbed by
+     * a read-then-clear race.
+     */
+    recoverableSlots(now?: number): SlotRecord[];
+    /**
+     * Non-terminal Slots (pending/running): work this ledger still owes, whether
+     * or not a live worker currently holds their lease.
+     *
+     * Deliberately NOT `recoverableSlots()`. That query excludes slots with a live
+     * lease — i.e. exactly the slots being executed right now — so using it as an
+     * "is anything still running?" probe reports idle in the middle of a run. The
+     * external-worker lifecycle needs to answer the opposite question, so it asks
+     * this one instead.
+     */
+    countActiveSlots(): number;
     /** Record an error without changing terminality (retryable failure keeps the cell resumable). */
     setCellError(slotId: string, targetId: string, error: string): void;
     /** Work ids already locked in THIS slot (to stop two cells taking the same work). */

package/dist/storage/repositories/SlotRepository.js

@@ -211,12 +211,50 @@ class SlotRepository extends BaseRepository_1.BaseRepository {
     }
     /** Slots whose lease expired while still non-terminal (crashed workers). */
     slotsWithStaleLease(now = Date.now()) {
+        return this.recoverableSlots(now)
+            .filter((slot) => slot.leaseUntil !== null)
+            .map((slot) => slot.id);
+    }
+    /**
+     * Non-terminal slots no live worker currently owns, and which therefore should
+     * be re-dispatched.
+     *
+     * Two distinct situations qualify, and both must be recovered:
+     *  - `lease_until <= now`: a worker claimed the slot and then died (crash, OOM,
+     *    machine stop, redeploy). Its heartbeat stopped, so the lease expired.
+     *  - `lease_until IS NULL`: a durable slot was recorded (accepted) but no worker
+     *    ever claimed it — e.g. the process died between "occurrence recorded" and
+     *    "lease claimed". Nothing else will ever pick that up.
+     *
+     * Callers must NOT clear the lease from here. Recovery re-DISPATCHES the slot
+     * and the atomic CAS in `claimSlotLease` still elects the single winner, so a
+     * merely slow (but healthy) owner that heartbeats mid-scan cannot be robbed by
+     * a read-then-clear race.
+     */
+    recoverableSlots(now = Date.now()) {
         const rows = this.db
-            .prepare(`SELECT id FROM schedule_slots
-         WHERE lease_until IS NOT NULL AND lease_until < @now
-           AND status IN ('pending','running')`)
+            .prepare(`SELECT * FROM schedule_slots
+         WHERE status IN ('pending','running')
+           AND (lease_until IS NULL OR lease_until <= @now)
+         ORDER BY COALESCE(occurrence_at, 0) ASC`)
             .all({ now });
-        return rows.map((r) => r.id);
+        return rows.map((r) => this.toSlot(r));
+    }
+    /**
+     * Non-terminal Slots (pending/running): work this ledger still owes, whether
+     * or not a live worker currently holds their lease.
+     *
+     * Deliberately NOT `recoverableSlots()`. That query excludes slots with a live
+     * lease — i.e. exactly the slots being executed right now — so using it as an
+     * "is anything still running?" probe reports idle in the middle of a run. The
+     * external-worker lifecycle needs to answer the opposite question, so it asks
+     * this one instead.
+     */
+    countActiveSlots() {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) n FROM schedule_slots WHERE status IN ('pending','running')`)
+            .get();
+        return row.n;
     }
     /** Record an error without changing terminality (retryable failure keeps the cell resumable). */
     setCellError(slotId, targetId, error) {

package/dist/topic/TopicPipeline.d.ts

@@ -21,7 +21,21 @@ export declare class TopicPipeline {
     private readonly client;
     private readonly resolver;
     private readonly requestDelayMs;
-    constructor(client: TopicClient, resolver: TopicResolver, requestDelayMs?: number);
+    /**
+     * Run-scoped cancellation. Candidate acquisition is the longest stretch of
+     * network work in a run, so it must observe the same abort as the download
+     * pipeline; otherwise a cancelled run keeps searching tags and can never
+     * settle, which is what let a timed-out run hold its slot lease forever.
+     */
+    private readonly signal?;
+    constructor(client: TopicClient, resolver: TopicResolver, requestDelayMs?: number, 
+    /**
+     * Run-scoped cancellation. Candidate acquisition is the longest stretch of
+     * network work in a run, so it must observe the same abort as the download
+     * pipeline; otherwise a cancelled run keeps searching tags and can never
+     * settle, which is what let a timed-out run hold its slot lease forever.
+     */
+    signal?: AbortSignal | undefined);
     selectWorks<T extends WorkLike>(target: TargetConfig, contentType: TopicContentType, day: string, limit: number, discovery: TopicDiscoveryOptions, collect: TopicCollectOptions): Promise<{
         works: T[];
         selection: TopicSelection;

package/dist/topic/TopicPipeline.js

@@ -5,6 +5,7 @@ const promises_1 = require("node:timers/promises");
 const logger_1 = require("../logger");
 const pixiv_utils_1 = require("../utils/pixiv-utils");
 const ai_detection_1 = require("../utils/ai-detection");
+const errors_1 = require("../utils/errors");
 const COLLECT_DEFAULTS = { maxPerTag: 40, maxCandidates: 250, minMetadataScore: 0.35 };
 /** Small, platform-level tags that are never evidence of topic membership. */
 const STOP_TAGS = new Set([
@@ -24,10 +25,19 @@ class TopicPipeline {
     client;
     resolver;
     requestDelayMs;
-    constructor(client, resolver, requestDelayMs = 500) {
+    signal;
+    constructor(client, resolver, requestDelayMs = 500, 
+    /**
+     * Run-scoped cancellation. Candidate acquisition is the longest stretch of
+     * network work in a run, so it must observe the same abort as the download
+     * pipeline; otherwise a cancelled run keeps searching tags and can never
+     * settle, which is what let a timed-out run hold its slot lease forever.
+     */
+    signal) {
         this.client = client;
         this.resolver = resolver;
         this.requestDelayMs = requestDelayMs;
+        this.signal = signal;
     }
     async selectWorks(target, contentType, day, limit, discovery, collect) {
         const topic = (target.topic ?? '').trim();
@@ -44,6 +54,9 @@ class TopicPipeline {
         for (let i = 0; i < tagNames.length; i++) {
             if (byId.size >= maxCandidates)
                 break;
+            // Cancellation is checked between tags, so a cancelled run stops issuing
+            // new searches even when the aborted request itself had already returned.
+            (0, errors_1.throwIfAborted)(this.signal, 'topic collection cancelled');
             const tag = tagNames[i];
             const works = await this.searchDay(contentType, tag, day, maxPerTag, includeR18);
             rawCount += works.length;
@@ -99,7 +112,7 @@ class TopicPipeline {
     }
     async searchDay(contentType, tag, day, limit, includeR18) {
         try {
-            const opts = { startDate: day, endDate: day, includeR18 };
+            const opts = { startDate: day, endDate: day, includeR18, signal: this.signal };
             const works = contentType === 'illustration'
                 ? await this.client.searchIllustrationsForTags(tag, limit, opts)
                 : await this.client.searchNovelsForTags(tag, limit, opts);
@@ -107,6 +120,9 @@ class TopicPipeline {
             return works.filter((w) => this.onDay(w.create_date, day));
         }
         catch (error) {
+            // A cancellation must not be degraded into "no results for this tag": that
+            // would silently continue the cancelled run across the remaining tags.
+            (0, errors_1.rethrowIfCancelled)(error, this.signal);
             logger_1.logger.warn('[TopicCollector] search failed tag=' + tag + ' type=' + contentType + ': ' + (error instanceof Error ? error.message : String(error)));
             return [];
         }

package/dist/topic/TopicResolver.d.ts

@@ -12,8 +12,12 @@ export declare class TopicResolver {
     private readonly client;
     private readonly cache;
     private readonly requestDelayMs;
+    /** Run-scoped cancellation, forwarded to every discovery request. */
+    private readonly signal?;
     private readonly scorer;
-    constructor(client: TopicClient, cache: TopicCache, requestDelayMs?: number);
+    constructor(client: TopicClient, cache: TopicCache, requestDelayMs?: number, 
+    /** Run-scoped cancellation, forwarded to every discovery request. */
+    signal?: AbortSignal | undefined);
     /** Resolve tags for a topic+type, using cache when fresh. Never throws for
      *  discovery errors: it always returns at least the seed tag. */
     resolve(topic: string, contentType: TopicContentType, options?: TopicDiscoveryOptions): Promise<{

package/dist/topic/TopicResolver.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TopicResolver = void 0;
 const promises_1 = require("node:timers/promises");
 const logger_1 = require("../logger");
+const errors_1 = require("../utils/errors");
 const TopicTagScorer_1 = require("./TopicTagScorer");
 /** Platform-wide tags never worth searching as topic keys or scoring metadata. */
 const STOP_TAGS = new Set([
@@ -29,11 +30,15 @@ class TopicResolver {
     client;
     cache;
     requestDelayMs;
+    signal;
     scorer = new TopicTagScorer_1.TopicTagScorer();
-    constructor(client, cache, requestDelayMs = 500) {
+    constructor(client, cache, requestDelayMs = 500, 
+    /** Run-scoped cancellation, forwarded to every discovery request. */
+    signal) {
         this.client = client;
         this.cache = cache;
         this.requestDelayMs = requestDelayMs;
+        this.signal = signal;
     }
     /** Resolve tags for a topic+type, using cache when fresh. Never throws for
      *  discovery errors: it always returns at least the seed tag. */
@@ -117,19 +122,40 @@ class TopicResolver {
     }
     /** Serial, bounded fetches: autocomplete → topic sample → small background. */
     async gatherSamples(seed, contentType, sampleWorks, includeR18) {
-        const suggested = await this.client.getTagAutocomplete(seed).catch(() => []);
+        (0, errors_1.throwIfAborted)(this.signal, 'topic resolution cancelled');
+        // Discovery degrades to "no suggestions" / "no background" on ordinary
+        // failures, but a cancellation must abort the run rather than quietly
+        // continue against a stopped pipeline.
+        const suggested = await this.client
+            .getTagAutocomplete(seed, { signal: this.signal })
+            .catch((error) => {
+            (0, errors_1.rethrowIfCancelled)(error, this.signal);
+            return [];
+        });
         if (this.requestDelayMs > 0)
             await (0, promises_1.setTimeout)(this.requestDelayMs);
+        (0, errors_1.throwIfAborted)(this.signal, 'topic resolution cancelled');
         const topicWorks = contentType === 'illustration'
-            ? await this.client.searchIllustrationsForTags(seed, sampleWorks, { includeR18 })
-            : await this.client.searchNovelsForTags(seed, sampleWorks, { includeR18 });
+            ? await this.client.searchIllustrationsForTags(seed, sampleWorks, { includeR18, signal: this.signal })
+            : await this.client.searchNovelsForTags(seed, sampleWorks, { includeR18, signal: this.signal });
         // A small, cheap background sample (a common platform tag) estimates how
         // generic a co-occurring tag is. Bounded to keep requests/memory low.
         if (this.requestDelayMs > 0)
             await (0, promises_1.setTimeout)(this.requestDelayMs);
+        (0, errors_1.throwIfAborted)(this.signal, 'topic resolution cancelled');
         const backgroundWorks = contentType === 'illustration'
-            ? await this.client.searchIllustrationsForTags('イラスト', 40, { includeR18 }).catch(() => [])
-            : await this.client.searchNovelsForTags('小説', 40, { includeR18 }).catch(() => []);
+            ? await this.client
+                .searchIllustrationsForTags('イラスト', 40, { includeR18, signal: this.signal })
+                .catch((error) => {
+                (0, errors_1.rethrowIfCancelled)(error, this.signal);
+                return [];
+            })
+            : await this.client
+                .searchNovelsForTags('小説', 40, { includeR18, signal: this.signal })
+                .catch((error) => {
+                (0, errors_1.rethrowIfCancelled)(error, this.signal);
+                return [];
+            });
         return [suggested, topicWorks, backgroundWorks];
     }
     seedOnly(seed, contentType, cacheDays) {

package/dist/topic/createTopicPipeline.d.ts

@@ -9,8 +9,8 @@ export type TopicPipelineFactory = () => TopicPipeline;
 type DbPathSource = string | {
     getDatabasePath(): string;
 } | undefined;
-export declare function createTopicPipeline(client: IPixivClient, databasePath: DbPathSource, requestDelayMs?: number): TopicPipeline;
+export declare function createTopicPipeline(client: IPixivClient, databasePath: DbPathSource, requestDelayMs?: number, signal?: AbortSignal): TopicPipeline;
 /** Lazily builds one shared pipeline per download run (cache + resolver). */
-export declare function createTopicPipelineFactory(client: IPixivClient, databasePath: DbPathSource, requestDelayMs?: number): TopicPipelineFactory;
+export declare function createTopicPipelineFactory(client: IPixivClient, databasePath: DbPathSource, requestDelayMs?: number, signal?: AbortSignal): TopicPipelineFactory;
 export {};
 //# sourceMappingURL=createTopicPipeline.d.ts.map

package/dist/topic/createTopicPipeline.js

@@ -15,18 +15,18 @@ function resolveDbPath(source) {
     const absolute = raw && (0, node_path_1.isAbsolute)(raw) ? raw : (0, node_path_1.resolve)(process.cwd(), raw ?? 'data/pixiv-downloader.db');
     return absolute;
 }
-function createTopicPipeline(client, databasePath, requestDelayMs = 500) {
+function createTopicPipeline(client, databasePath, requestDelayMs = 500, signal) {
     const resolved = resolveDbPath(databasePath);
     const cache = new TopicCache_1.TopicCache((0, node_path_1.resolve)((0, node_path_1.dirname)(resolved), 'topic-cache'));
-    const resolver = new TopicResolver_1.TopicResolver(client, cache, requestDelayMs);
-    return new TopicPipeline_1.TopicPipeline(client, resolver, requestDelayMs);
+    const resolver = new TopicResolver_1.TopicResolver(client, cache, requestDelayMs, signal);
+    return new TopicPipeline_1.TopicPipeline(client, resolver, requestDelayMs, signal);
 }
 /** Lazily builds one shared pipeline per download run (cache + resolver). */
-function createTopicPipelineFactory(client, databasePath, requestDelayMs = 500) {
+function createTopicPipelineFactory(client, databasePath, requestDelayMs = 500, signal) {
     let instance;
     return () => {
         if (!instance)
-            instance = createTopicPipeline(client, databasePath, requestDelayMs);
+            instance = createTopicPipeline(client, databasePath, requestDelayMs, signal);
         return instance;
     };
 }

package/dist/topic/types.d.ts

@@ -67,7 +67,9 @@ export interface TopicCandidate {
 }
 /** Minimal surface the resolver/collector need from the Pixiv client. */
 export interface TopicClient {
-    getTagAutocomplete(seed: string): Promise<Array<{
+    getTagAutocomplete(seed: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Array<{
         name: string;
         translated_name?: string;
     }>>;
@@ -75,11 +77,13 @@ export interface TopicClient {
         startDate?: string;
         endDate?: string;
         includeR18?: boolean;
+        signal?: AbortSignal;
     }): Promise<Array<WorkLike>>;
     searchNovelsForTags(seed: string, limit: number, options?: {
         startDate?: string;
         endDate?: string;
         includeR18?: boolean;
+        signal?: AbortSignal;
     }): Promise<Array<WorkLike>>;
 }
 export interface WorkLike {