pixivflow 2.20.5 → 2.22.0

package/dist/scheduler/ResourceAdmission.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceAdmission = void 0;
+exports.pixivAccountResourceKey = pixivAccountResourceKey;
+/**
+ * FIFO per-resource admission with config-driven capacity.
+ *
+ * `capacityOf(resourceKey)` returns the configured capacity for that key
+ * (default 1). `maxWaiting` bounds the TOTAL number of parked work items
+ * across all resources, mirroring the legacy `schedulerRuntime.queueLimit`
+ * guard against an unbounded backlog.
+ */
+class ResourceAdmission {
+    capacityOf;
+    maxWaiting;
+    active = new Map();
+    waiting = [];
+    constructor(capacityOf, maxWaiting = 8) {
+        this.capacityOf = capacityOf;
+        this.maxWaiting = maxWaiting;
+    }
+    setMaxWaiting(maxWaiting) {
+        this.maxWaiting = Math.max(0, maxWaiting);
+    }
+    /**
+     * Acquire a lease on `resourceKey`. Resolves immediately when capacity is
+     * available, parks the caller in a FIFO per-key queue otherwise, and resolves
+     * `null` (never rejects) when the bounded wait queue is full.
+     */
+    acquire(resourceKey) {
+        if (this.activeCount(resourceKey) < this.capacityOf(resourceKey)) {
+            this.active.set(resourceKey, this.activeCount(resourceKey) + 1);
+            return Promise.resolve(this.createLease(resourceKey));
+        }
+        if (this.waiting.length >= this.maxWaiting) {
+            return Promise.resolve(null);
+        }
+        return new Promise((resolve) => {
+            this.waiting.push({ resourceKey, resolve });
+        });
+    }
+    createLease(resourceKey) {
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.releaseNext(resourceKey);
+            },
+        };
+    }
+    releaseNext(resourceKey) {
+        // Hand the freed slot to the OLDEST waiter for this resource key (FIFO),
+        // skipping waiters of other resources so they never block this one.
+        const index = this.waiting.findIndex((entry) => entry.resourceKey === resourceKey);
+        if (index === -1) {
+            const remaining = Math.max(0, this.activeCount(resourceKey) - 1);
+            this.active.set(resourceKey, remaining);
+            return;
+        }
+        const [entry] = this.waiting.splice(index, 1);
+        entry.resolve(this.createLease(resourceKey));
+    }
+    /** Active leases for one resource key. */
+    activeCount(resourceKey) {
+        return this.active.get(resourceKey) ?? 0;
+    }
+    /** Work items parked waiting for one resource key. */
+    waitingCount(resourceKey) {
+        return this.waiting.filter((entry) => entry.resourceKey === resourceKey).length;
+    }
+    /** Work items parked waiting for ANY resource. Unfinished work, not failure. */
+    waitingTotal() {
+        return this.waiting.length;
+    }
+}
+exports.ResourceAdmission = ResourceAdmission;
+/** The canonical resource identity for the process's Pixiv credential profile. */
+function pixivAccountResourceKey(accountId) {
+    return `pixiv-account:${(accountId ?? 'default').trim() || 'default'}`;
+}
+//# sourceMappingURL=ResourceAdmission.js.map

package/dist/scheduler/ScheduleTriggerServer.d.ts

@@ -111,6 +111,22 @@ export interface TriggerHandlers {
         state: string;
         slotStatus: string;
     } | null;
+    /**
+     * Admit one manual RECOVERY of a failed target (§manual-recovery). `retryMode`
+     * selects a SERVER-DEFINED acquisition policy preset ('normal' | 'relaxed');
+     * callers never supply raw acquisition parameters. The run is
+     * occurrence-scoped: it never changes the global config or future schedules.
+     */
+    recover?(targetId: string, requestId: string, retryMode: 'normal' | 'relaxed', correlationId?: string): Promise<{
+        slotId: string;
+        disposition: string;
+    }>;
+    recoverStatus?(targetId: string, requestId: string): {
+        requestId: string;
+        slotId: string;
+        state: string;
+        slotStatus: string;
+    } | null;
 }
 export declare class ScheduleTriggerServer {
     private readonly token;

package/dist/scheduler/ScheduleTriggerServer.js

@@ -207,6 +207,61 @@ class ScheduleTriggerServer {
             }
             res.json(status);
         });
+        // Manual RECOVERY of a failed schedule target (§manual-recovery). Same
+        // authenticated manual-work family as refetch (PIXIVFLOW_REFETCH_TOKEN) but
+        // a DIFFERENT business intent: it re-runs the failed target(s) under a
+        // server-defined acquisition policy preset and reports through the
+        // schedule-outcome channel, so the daily summary is never rewritten.
+        // Admitting is all this endpoint does; if the resource is busy the run is
+        // queued (202 + disposition 'queued'), never failed.
+        app.post('/internal/targets/:targetId/recover', this.refetchAuth, async (req, res) => {
+            const requestId = req.body?.requestId;
+            if (typeof requestId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(requestId)) {
+                res.status(400).json({ status: 'error', error: 'requestId must be a UUID' });
+                return;
+            }
+            // Only a NAMED preset is accepted — never raw acquisition parameters.
+            const rawMode = req.body?.retryMode;
+            const retryMode = rawMode === undefined || rawMode === null || rawMode === '' ? 'normal' : rawMode;
+            if (retryMode !== 'normal' && retryMode !== 'relaxed') {
+                res.status(400).json({ status: 'error', error: 'retryMode must be "normal" or "relaxed"' });
+                return;
+            }
+            const correlationId = req.body?.correlationId;
+            if (correlationId !== undefined && (typeof correlationId !== 'string' || correlationId.length > 200)) {
+                res.status(400).json({ status: 'error', error: 'correlationId must be a string of at most 200 chars' });
+                return;
+            }
+            if (!this.handlers.recover) {
+                res.status(503).json({ status: 'error', error: 'manual recovery is unavailable' });
+                return;
+            }
+            try {
+                const result = await this.handlers.recover(req.params.targetId, requestId, retryMode, correlationId ?? undefined);
+                res.status(202).json({ status: 'accepted', retryMode, ...result });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const status = message === 'unknown target' ? 404 : message === 'ambiguous target' ? 409 : 500;
+                logger_1.logger.warn('Manual recovery rejected', {
+                    targetId: req.params.targetId, requestId, retryMode, status, error: message,
+                });
+                res.status(status).json({ status: 'error', error: status === 500 ? 'recovery admission failed' : message });
+            }
+        });
+        app.get('/internal/targets/:targetId/recover/:requestId', this.refetchAuth, (req, res) => {
+            const { targetId, requestId } = req.params;
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(requestId)) {
+                res.status(400).json({ status: 'error', error: 'requestId must be a UUID' });
+                return;
+            }
+            const status = this.handlers.recoverStatus?.(targetId, requestId);
+            if (!status) {
+                res.status(404).json({ status: 'error', error: 'manual recovery not found' });
+                return;
+            }
+            res.json(status);
+        });
         // Convergence endpoint: after a machine stop/start, an operator or an
         // external watcher can ask the process to flush due deliveries/notifications
         // without running candidate selection. Deployment-agnostic (no platform refs).

package/dist/scheduler/Scheduler.d.ts

@@ -56,7 +56,12 @@ export interface JobAbandoned {
 }
 /** Admission is acquired before timeout/accounting starts. */
 export interface JobAdmissionController {
-    acquire(scheduleId: string): Promise<JobLease | null>;
+    /**
+     * Acquire a lease on the work item's constrained RESOURCE. The key is a
+     * resource identity (`pixiv-account:<id>`), never a bot/schedule/target
+     * name. Resolves `null` only when the bounded wait queue is full.
+     */
+    acquire(resourceKey: string): Promise<JobLease | null>;
 }
 export declare class Scheduler {
     private readonly config;
@@ -66,6 +71,12 @@ export declare class Scheduler {
     private readonly admission?;
     private readonly onFailure?;
     private readonly onAbandoned?;
+    /**
+     * The constrained resource this schedule's work consumes (§resource-
+     * governance). All schedules whose targets share the same Pixiv account
+     * share the same key, so their runs queue under ONE capacity.
+     */
+    private readonly resourceKey?;
     private task;
     private job;
     private running;
@@ -76,7 +87,13 @@ export declare class Scheduler {
     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, onAbandoned?: ((abandoned: JobAbandoned) => 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, 
+    /**
+     * The constrained resource this schedule's work consumes (§resource-
+     * governance). All schedules whose targets share the same Pixiv account
+     * share the same key, so their runs queue under ONE capacity.
+     */
+    resourceKey?: string | undefined);
     start(job: (options?: ScheduleRunOptions) => Promise<void>): void;
     /**
      * Arm the scheduler for external/manual triggers (runNow) WITHOUT registering

package/dist/scheduler/Scheduler.js

@@ -33,6 +33,7 @@ class Scheduler {
     admission;
     onFailure;
     onAbandoned;
+    resourceKey;
     task = null;
     job = null;
     running = false;
@@ -43,7 +44,13 @@ class Scheduler {
     drainHandle = null;
     stopped = false;
     pending = false;
-    constructor(config, database, telemetry, scheduleId = 'default', admission, onFailure, onAbandoned) {
+    constructor(config, database, telemetry, scheduleId = 'default', admission, onFailure, onAbandoned, 
+    /**
+     * The constrained resource this schedule's work consumes (§resource-
+     * governance). All schedules whose targets share the same Pixiv account
+     * share the same key, so their runs queue under ONE capacity.
+     */
+    resourceKey) {
         this.config = config;
         this.database = database;
         this.telemetry = telemetry;
@@ -51,6 +58,7 @@ class Scheduler {
         this.admission = admission;
         this.onFailure = onFailure;
         this.onAbandoned = onAbandoned;
+        this.resourceKey = resourceKey;
     }
     start(job) {
         this.arm(job, true);
@@ -149,15 +157,16 @@ class Scheduler {
             await new Promise((resolve) => setTimeout(resolve, this.config.failureRetryDelay));
         }
         this.pending = true;
-        const lease = this.admission ? await this.admission.acquire(this.scheduleId) : null;
+        const lease = this.admission ? await this.admission.acquire(this.resourceKey ?? this.scheduleId) : null;
         this.pending = false;
         if (this.stopped) {
             lease?.release();
             return;
         }
         if (this.admission && !lease) {
-            logger_1.logger.warn('Skipping scheduled job because the shared scheduler queue is full', {
+            logger_1.logger.warn('Work not admitted: the resource wait queue is full; the durable ledger will retry it', {
                 scheduleId: this.scheduleId,
+                resourceKey: this.resourceKey,
             });
             return;
         }

package/dist/scheduler/SlotCoordinator.d.ts

@@ -46,12 +46,26 @@ export interface SlotContext {
     manualRequestId?: string;
     /** Opaque caller correlation (review chain / review id). Null unless manual. */
     correlationId?: string;
+    /**
+     * Remote manual RECOVERY request UUID (§manual-recovery). Present only on
+     * slots opened by the authenticated recover endpoint; null for scheduled
+     * occurrences and review refetches. A recovery slot re-runs the failed
+     * target(s) under an occurrence-scoped recovery policy and reports through
+     * the schedule-outcome channel.
+     */
+    recoveryRequestId?: string;
+    /** Recovery policy preset ('normal' | 'relaxed'); null for non-recovery slots. */
+    recoveryMode?: 'normal' | 'relaxed';
 }
 export interface SlotCellSummary {
     targetId: string;
     status: CellStatus;
     workId: string | null;
     error?: string | null;
+    /** Normalized terminal failure code (§terminal-reason); null when not failed. */
+    terminalReasonCode?: string | null;
+    /** User-facing business reason message (§terminal-reason). */
+    terminalReasonMessage?: string | null;
 }
 export interface SlotRunSummary {
     scheduleId: string;
@@ -233,6 +247,12 @@ export declare class SlotCoordinator {
      * sole path to the submitted cell state.
      */
     applyOutcome(slotId: string, targetId: string, outcome: TargetOutcome): void;
+    /**
+     * Persist the normalized terminal reason (§terminal-reason) for a cell that
+     * just reached a terminal state. Never unwinds the run and never leaks raw
+     * error internals: only the stable code + business message are stored.
+     */
+    private persistTerminalReason;
     /** Promote a delivery_pending cell to submitted from a confirmed ACK. */
     markDelivered(slotId: string, targetId: string, workId: string, workType: string): void;
     /**

package/dist/scheduler/SlotCoordinator.js

@@ -4,6 +4,7 @@ exports.SlotCoordinator = exports.SLOT_HEARTBEAT_MS = exports.SLOT_LEASE_TTL_MS
 exports.timezoneForSchedule = timezoneForSchedule;
 const logger_1 = require("../logger");
 const OccurrenceResolver_1 = require("./OccurrenceResolver");
+const TargetOutcome_1 = require("./TargetOutcome");
 const WorkIdentity_1 = require("./WorkIdentity");
 /**
  * Execution-lease TTL and heartbeat cadence.
@@ -129,6 +130,8 @@ class SlotCoordinator {
             slotName: slot.slotName,
             manualRequestId: slot.manualRequestId ?? null,
             correlationId: slot.correlationId ?? null,
+            recoveryRequestId: slot.recoveryRequestId ?? null,
+            recoveryMode: slot.recoveryMode ?? null,
         });
         if (created) {
             // Freeze membership: materialize one cell per target id from the snapshot.
@@ -267,12 +270,15 @@ class SlotCoordinator {
             case 'no_candidate':
                 // Only terminal if the cell never locked a work; a locked work whose
                 // delivery is still pending must not be collapsed to no_candidate.
-                if (!cell.workId)
+                if (!cell.workId) {
                     this.safeTransition(slotId, targetId, 'no_candidate', outcome.reason);
+                    this.persistTerminalReason(slotId, targetId, outcome);
+                }
                 return;
             case 'duplicate':
                 this.database.slots.lockCellWork(slotId, targetId, outcome.workId, cell.workType ?? 'unknown');
                 this.safeTransition(slotId, targetId, 'duplicate', outcome.reason);
+                this.persistTerminalReason(slotId, targetId, outcome);
                 return;
             case 'failed':
                 if (outcome.retryable) {
@@ -282,7 +288,27 @@ class SlotCoordinator {
                     return;
                 }
                 this.safeTransition(slotId, targetId, 'failed', outcome.error);
+                this.persistTerminalReason(slotId, targetId, outcome);
+                return;
+        }
+    }
+    /**
+     * Persist the normalized terminal reason (§terminal-reason) for a cell that
+     * just reached a terminal state. Never unwinds the run and never leaks raw
+     * error internals: only the stable code + business message are stored.
+     */
+    persistTerminalReason(slotId, targetId, outcome) {
+        try {
+            const reason = (0, TargetOutcome_1.terminalReasonFor)(outcome);
+            if (!reason)
                 return;
+            this.database.slots.setCellTerminalReason(slotId, targetId, reason.code, reason.message);
+        }
+        catch (error) {
+            logger_1.logger.debug('Failed to persist terminal reason', {
+                slot: slotId, target: targetId,
+                error: error instanceof Error ? error.message : String(error),
+            });
         }
     }
     /** Promote a delivery_pending cell to submitted from a confirmed ACK. */
@@ -393,7 +419,19 @@ class SlotCoordinator {
                 continue;
             if (cell.status === 'pending' || cell.status === 'selected') {
                 // Ran but never reached a terminal state (target threw before delivery).
-                this.database.slots.setCellStatus(slot.slotId, targetId, 'failed', cell.lastError ?? 'target did not complete');
+                // Persist a normalized reason so the operator sees a first-level cause,
+                // not a bare "target did not complete".
+                const error = cell.lastError ?? 'target did not complete';
+                this.database.slots.setCellStatus(slot.slotId, targetId, 'failed', error);
+                try {
+                    this.database.slots.setCellTerminalReason(slot.slotId, targetId, 'internal_error', TargetOutcome_1.TERMINAL_REASON_MESSAGES.internal_error);
+                }
+                catch (reasonError) {
+                    logger_1.logger.debug('Failed to persist terminal reason in rollup', {
+                        slot: slot.slotId, target: targetId,
+                        error: reasonError instanceof Error ? reasonError.message : String(reasonError),
+                    });
+                }
             }
         }
         const status = this.database.slots.deriveSlotStatus(slot.slotId);
@@ -403,6 +441,8 @@ class SlotCoordinator {
             status: c.status,
             workId: c.workId,
             error: c.lastError,
+            terminalReasonCode: c.terminalReasonCode,
+            terminalReasonMessage: c.terminalReasonMessage,
         }));
         // Rolled up AFTER the slot row carries its terminal status/completed_at, so
         // the outcome reports the durable timestamps rather than a fresh clock read.
@@ -450,6 +490,8 @@ class SlotCoordinator {
                 status: cell.status,
                 work_id: cell.workId,
                 error: cell.lastError,
+                terminal_reason_code: cell.terminalReasonCode,
+                terminal_reason_message: cell.terminalReasonMessage,
             };
         });
         // A fully-submitted slot has no non-submitted cell at all, and reporting

package/dist/scheduler/TargetOutcome.d.ts

@@ -253,4 +253,35 @@ export declare function mergeScanSummaries(first: CandidateScanSummary | null, s
 export declare function classifyCandidateFailure(error: unknown, workId: string): CandidateFailure;
 /** Hard job-level outage for a directly-thrown error, or null. */
 export declare function classifyJobLevelOutage(error: unknown): JobLevelOutage | null;
+/**
+ * Normalized terminal failure taxonomy (§terminal-reason).
+ *
+ * These codes are what operators actually see: the FIRST-LEVEL cause of a
+ * terminal cell. Recovery exhaustion is an execution state, never a root
+ * cause — a cell that exhausted its fallback stages because every candidate
+ * was a duplicate reports `duplicate_exhausted`, not `recovery_exhausted`.
+ * Queue waiting is not a terminal reason at all.
+ *
+ * Codes are kept deliberately small (no giant taxonomy): each maps to one
+ * real failure path in this codebase.
+ */
+export type TerminalReasonCode = 
+/** The candidate scan was empty — nothing was found in the day's ranked pool. */
+'no_candidate'
+/** Every candidate the scan saw was already delivered/pending for this target. */
+ | 'duplicate_exhausted'
+/** Candidates existed but none passed the target's own filters. */
+ | 'filter_exhausted' | 'download_timeout' | 'download_failed' | 'metadata_failed' | 'rate_limited' | 'auth_failed' | 'remote_http_error' | 'delivery_failed' | 'telepost_rejected' | 'telegram_failed' | 'network_error' | 'execution_timeout' | 'configuration_error' | 'internal_error';
+export interface TerminalReason {
+    code: TerminalReasonCode;
+    /** Business-language message an operator/reviewer reads directly. */
+    message: string;
+}
+/** User-facing business messages — never stack traces, paths, SQL or tokens. */
+export declare const TERMINAL_REASON_MESSAGES: Record<TerminalReasonCode, string>;
+/**
+ * Map a typed terminal TargetOutcome onto the normalized reason. Returns null
+ * for non-terminal outcomes (they have no terminal reason yet).
+ */
+export declare function terminalReasonFor(outcome: TargetOutcome): TerminalReason | null;
 //# sourceMappingURL=TargetOutcome.d.ts.map

package/dist/scheduler/TargetOutcome.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TERMINAL_REASON_MESSAGES = void 0;
 exports.emptyCandidateScan = emptyCandidateScan;
 exports.isTerminalOutcome = isTerminalOutcome;
 exports.isSelectedAttempt = isSelectedAttempt;
@@ -10,6 +11,7 @@ exports.hasTransientFailure = hasTransientFailure;
 exports.mergeScanSummaries = mergeScanSummaries;
 exports.classifyCandidateFailure = classifyCandidateFailure;
 exports.classifyJobLevelOutage = classifyJobLevelOutage;
+exports.terminalReasonFor = terminalReasonFor;
 /**
  * A scan that attempted nothing. The real pipeline always reports its own scan;
  * this is for callers/tests that have no candidate-level information, so they
@@ -224,4 +226,130 @@ function classifyJobLevelOutage(error) {
     const failure = classifyCandidateFailure(error, '');
     return failure.scope === 'job' ? failure.outage : null;
 }
+/** User-facing business messages — never stack traces, paths, SQL or tokens. */
+exports.TERMINAL_REASON_MESSAGES = {
+    no_candidate: '没有找到合适的新作品',
+    duplicate_exhausted: '候选作品均已投稿过',
+    filter_exhausted: '没有符合筛选条件的新作品',
+    download_timeout: '图片下载超时',
+    download_failed: '图片下载失败',
+    metadata_failed: '作品信息获取失败',
+    rate_limited: 'Pixiv 请求频率受限',
+    auth_failed: 'Pixiv 登录已失效，需要重新登录',
+    remote_http_error: 'Pixiv 服务器返回错误',
+    delivery_failed: '投稿投递失败',
+    telepost_rejected: '投稿被接收端拒绝',
+    telegram_failed: 'Telegram 发送失败',
+    network_error: '网络异常',
+    execution_timeout: '执行超时',
+    configuration_error: '配置错误',
+    internal_error: '内部错误',
+};
+/**
+ * Map a typed terminal TargetOutcome onto the normalized reason. Returns null
+ * for non-terminal outcomes (they have no terminal reason yet).
+ */
+function terminalReasonFor(outcome) {
+    switch (outcome.kind) {
+        case 'submitted':
+        case 'stored':
+        case 'delivery_pending':
+            return null;
+        case 'no_candidate':
+            return reasonForNoCandidate(outcome);
+        case 'duplicate':
+            return {
+                code: 'duplicate_exhausted',
+                message: exports.TERMINAL_REASON_MESSAGES.duplicate_exhausted,
+            };
+        case 'failed':
+            return classifyFailedReason(outcome.error, outcome.scan);
+    }
+}
+/**
+ * Root cause for a `no_candidate` target, read from the scan's skip codes
+ * rather than from exhaustion bookkeeping: all duplicates ⇒
+ * `duplicate_exhausted`; otherwise the candidates were present but unusable
+ * (filter/deleted/denied/wrong media) ⇒ `filter_exhausted`; a scan that saw
+ * nothing at all ⇒ `no_candidate`.
+ */
+function reasonForNoCandidate(outcome) {
+    const skipped = outcome.scan?.skipped ?? [];
+    if (skipped.length > 0) {
+        const duplicates = skipped.filter((s) => s.code === 'duplicate').length;
+        if (duplicates === skipped.length) {
+            return { code: 'duplicate_exhausted', message: exports.TERMINAL_REASON_MESSAGES.duplicate_exhausted };
+        }
+        if (duplicates >= skipped.length / 2 || skipped.every((s) => s.code !== 'unavailable')) {
+            // Predominantly duplicates, or every skip was a hard work-level verdict:
+            // the pool contained works but none were usable for this target.
+            return { code: 'filter_exhausted', message: exports.TERMINAL_REASON_MESSAGES.filter_exhausted };
+        }
+    }
+    return { code: 'no_candidate', message: exports.TERMINAL_REASON_MESSAGES.no_candidate };
+}
+/**
+ * Classify a terminal `failed` reason from the error text + scan bookkeeping.
+ * Job-level outages from the scan win first (they describe the whole run), then
+ * message-shape heuristics; anything unclassifiable becomes `internal_error`
+ * rather than leaking raw error text to the review group.
+ */
+function classifyFailedReason(message, scan) {
+    const outage = scan?.outages?.[0];
+    if (outage === 'pixiv_auth_failure') {
+        return { code: 'auth_failed', message: exports.TERMINAL_REASON_MESSAGES.auth_failed };
+    }
+    if (outage === 'delivery_unavailable') {
+        return { code: 'delivery_failed', message: exports.TERMINAL_REASON_MESSAGES.delivery_failed };
+    }
+    if (outage === 'network_outage' || outage === 'database_unavailable') {
+        return { code: 'network_error', message: exports.TERMINAL_REASON_MESSAGES.network_error };
+    }
+    const text = String(message ?? '').slice(0, 600);
+    if (/\b429\b|rate ?limit/i.test(text)) {
+        return { code: 'rate_limited', message: exports.TERMINAL_REASON_MESSAGES.rate_limited };
+    }
+    if (/\b401\b|unauthorized|invalid grant|invalid refresh token|authentication failed|登录/i.test(text)) {
+        return { code: 'auth_failed', message: exports.TERMINAL_REASON_MESSAGES.auth_failed };
+    }
+    if (/timeout|timed ?out|timedout/i.test(text)) {
+        return /download|image|url|fetch/i.test(text)
+            ? { code: 'download_timeout', message: exports.TERMINAL_REASON_MESSAGES.download_timeout }
+            : { code: 'execution_timeout', message: exports.TERMINAL_REASON_MESSAGES.execution_timeout };
+    }
+    if (/502|503|504|bad gateway|service unavailable|server error|5\d\d/i.test(text)) {
+        return { code: 'remote_http_error', message: exports.TERMINAL_REASON_MESSAGES.remote_http_error };
+    }
+    if (/telegram/i.test(text)) {
+        return { code: 'telegram_failed', message: exports.TERMINAL_REASON_MESSAGES.telegram_failed };
+    }
+    // Configuration faults are reported as such even when they surface inside a
+    // delivery/submission path ("delivery target not configured"): the operator
+    // fixes configuration, not the upstream.
+    if (/not configured|missing (?:config|configuration|setting)|invalid config/i.test(text)) {
+        return { code: 'configuration_error', message: exports.TERMINAL_REASON_MESSAGES.configuration_error };
+    }
+    // A candidate's metadata could not be gathered/parsed: this is its own root
+    // cause (config is fine; the upstream work was unreadable), so it must not
+    // fall through to internal_error or configuration_error.
+    if (/\bmetadata\b.{0,60}\b(?:fail|error|unable|invalid|parse|serialize|gather)\b|failed to (?:gather|parse|fetch|load|save)\b.{0,40}\bmetadata\b/i.test(text)) {
+        return { code: 'metadata_failed', message: exports.TERMINAL_REASON_MESSAGES.metadata_failed };
+    }
+    // TelePost (or any theme/review submission endpoint) explicitly rejected the
+    // work with a client-side / payload verdict. This is not a delivery outage
+    // (5xx/unreachable — handled above) nor a generic delivery failure.
+    if (/\btele[ _-]?post\b[^.\n]{0,60}\b(?:reject|invalid|4\d\d)\b/i.test(text)) {
+        return { code: 'telepost_rejected', message: exports.TERMINAL_REASON_MESSAGES.telepost_rejected };
+    }
+    if (/delivery|submit(?:t?ed)?|publish|post|outbox/i.test(text)) {
+        return { code: 'delivery_failed', message: exports.TERMINAL_REASON_MESSAGES.delivery_failed };
+    }
+    if (/econnrefused|econnreset|enotfound|etimedout|ehostunreach|enetunreach|socket hang up|network is unreachable|getaddrinfo/i.test(text)) {
+        return { code: 'network_error', message: exports.TERMINAL_REASON_MESSAGES.network_error };
+    }
+    if (/config|missing|invalid/i.test(text)) {
+        return { code: 'configuration_error', message: exports.TERMINAL_REASON_MESSAGES.configuration_error };
+    }
+    return { code: 'internal_error', message: exports.TERMINAL_REASON_MESSAGES.internal_error };
+}
 //# sourceMappingURL=TargetOutcome.js.map

package/dist/storage/DatabaseMigration.js

@@ -108,6 +108,11 @@ class DatabaseMigration {
             -- the terminal outcome can be reported back to the requester
             -- without this service learning anything about the review.
             correlation_id TEXT,
+            -- Manual recovery request UUID + policy preset ("重试一次/放宽条件重试").
+            -- A recovery slot re-runs the failed target(s) under a per-occurrence
+            -- policy and reports through the schedule-outcome channel.
+            recovery_request_id TEXT,
+            recovery_mode TEXT,
             created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
             started_at DATETIME,
             completed_at DATETIME,
@@ -126,6 +131,10 @@ class DatabaseMigration {
             attempt_count INTEGER NOT NULL DEFAULT 0,
             fallback_stage INTEGER NOT NULL DEFAULT 0,
             last_error TEXT,
+            -- Normalized terminal failure reason (§terminal-reason): stable reason
+            -- code plus a user-facing business message, durable across restarts.
+            terminal_reason_code TEXT,
+            terminal_reason_message TEXT,
             created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
             updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
             completed_at DATETIME,
@@ -239,6 +248,8 @@ class DatabaseMigration {
                 heartbeat_at: 'ALTER TABLE schedule_slots ADD COLUMN heartbeat_at INTEGER',
                 manual_request_id: 'ALTER TABLE schedule_slots ADD COLUMN manual_request_id TEXT',
                 correlation_id: 'ALTER TABLE schedule_slots ADD COLUMN correlation_id TEXT',
+                recovery_request_id: 'ALTER TABLE schedule_slots ADD COLUMN recovery_request_id TEXT',
+                recovery_mode: 'ALTER TABLE schedule_slots ADD COLUMN recovery_mode TEXT',
             };
             const columnAlters = [];
             for (const [col, sql] of Object.entries(slotColumnMigrations)) {
@@ -249,6 +260,12 @@ class DatabaseMigration {
             if (!itemCols.includes('fallback_stage')) {
                 columnAlters.push(`ALTER TABLE schedule_slot_items ADD COLUMN fallback_stage INTEGER NOT NULL DEFAULT 0`);
             }
+            if (!itemCols.includes('terminal_reason_code')) {
+                columnAlters.push(`ALTER TABLE schedule_slot_items ADD COLUMN terminal_reason_code TEXT`);
+            }
+            if (!itemCols.includes('terminal_reason_message')) {
+                columnAlters.push(`ALTER TABLE schedule_slot_items ADD COLUMN terminal_reason_message TEXT`);
+            }
             // Create indexes for better query performance
             const indexes = [
                 `CREATE INDEX IF NOT EXISTS idx_downloads_pixiv_id_type ON downloads(pixiv_id, type)`,