pixivflow 2.22.1 → 2.23.0

package/dist/commands/SchedulerCommand.js

@@ -12,6 +12,7 @@ const ScheduleTriggerServer_1 = require("../scheduler/ScheduleTriggerServer");
 const SlotCoordinator_1 = require("../scheduler/SlotCoordinator");
 const schedules_1 = require("../scheduler/schedules");
 const scheduler_runtime_1 = require("./scheduler-runtime");
+const RecoveryOutcome_1 = require("../scheduler/RecoveryOutcome");
 const SchedulerIdleLifecycle_1 = require("./SchedulerIdleLifecycle");
 /**
  * Decide whether the authenticated HTTP trigger server should be mounted. It is
@@ -263,9 +264,17 @@ class SchedulerCommand extends Command_1.BaseCommand {
                     recoverStatus: (targetId, requestId) => {
                         const slot = runtime.database.slots.findRecoverySlot(requestId, targetId);
                         const cell = slot && runtime.database.slots.getCell(slot.id, targetId);
-                        return slot && cell
-                            ? { requestId, slotId: slot.id, state: cell.status, slotStatus: slot.status }
-                            : null;
+                        if (!slot || !cell)
+                            return null;
+                        const businessState = (0, RecoveryOutcome_1.recoveryOutcomeFor)(cell);
+                        return {
+                            requestId,
+                            slotId: slot.id,
+                            state: cell.status,
+                            slotStatus: slot.status,
+                            business_state: businessState,
+                            message: (0, RecoveryOutcome_1.recoveryUserMessage)(businessState),
+                        };
                     },
                     status: (scheduleId) => {
                         const cfg = resolveConfig();

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

@@ -119,6 +119,35 @@ export interface SchedulerRuntime {
     close(): void;
 }
 export declare function notifyScheduleFailure(config: StandaloneConfig, database: Database, schedule: ScheduleConfig, failure: JobFailure): Promise<void>;
+/**
+ * A `no_candidate` scan that attempted nothing and whose only candidate skips
+ * are `duplicate` is a TRUE dead-end: every candidate the scan surfaced was
+ * already delivered, and nothing was attempted to be widened. Advancing the
+ * fallback stage for this would re-fetch the SAME stale duplicate pool with a
+ * wider bound and burn the whole scheduler budget again (the production bug
+ * that turned an empty day on bot1 into a 30-minute OperationCancelledError).
+ * Terminalise it immediately instead of entering the fallback re-run loop.
+ */
+export interface CandidateExhaustionDiagnostic {
+    stage: 'candidate_selection';
+    result: 'no_candidate';
+    reason: 'duplicate_exhausted' | 'filter_exhausted' | 'no_candidate';
+    searched: number;
+    duplicates: number;
+    filtered: number;
+    attempted: number;
+}
+/**
+ * Structured diagnostic for a terminal `no_candidate`: what the scan surfaced
+ * (`searched`), how many were already-delivered duplicates, how many were
+ * filtered by the run's own rules, and how many were actually attempted.
+ * Emitted as a JSON log so a Mini App can show "当天候选均已投稿" instead of
+ * treating the slot as a system failure.
+ */
+export declare function candidateExhaustionDiagnostic(outcome: Extract<TargetOutcome, {
+    kind: 'no_candidate';
+}>): CandidateExhaustionDiagnostic | null;
+export declare function isDuplicateOnlyDeadEnd(outcome: TargetOutcome): boolean;
 /**
  * Expanded, still-bounded candidate scan bound for one fallback stage
  * (§schedule-recovery). Stage 0 is the primary pass; stage N scans

package/dist/commands/scheduler-runtime.js

@@ -45,6 +45,8 @@ exports.EXECUTION_MODES = void 0;
 exports.withDeliveryMode = withDeliveryMode;
 exports.shouldTerminaliseAbortedSlot = shouldTerminaliseAbortedSlot;
 exports.notifyScheduleFailure = notifyScheduleFailure;
+exports.candidateExhaustionDiagnostic = candidateExhaustionDiagnostic;
+exports.isDuplicateOnlyDeadEnd = isDuplicateOnlyDeadEnd;
 exports.fallbackScanLimit = fallbackScanLimit;
 exports.createSchedulerRuntime = createSchedulerRuntime;
 exports.runWithTimeout = runWithTimeout;
@@ -201,6 +203,44 @@ function buildProxyUrl(network) {
     const auth = proxy.username ? `${proxy.username}:${proxy.password ?? ''}@` : '';
     return `${protocol}://${auth}${proxy.host}:${proxy.port}`;
 }
+/**
+ * Structured diagnostic for a terminal `no_candidate`: what the scan surfaced
+ * (`searched`), how many were already-delivered duplicates, how many were
+ * filtered by the run's own rules, and how many were actually attempted.
+ * Emitted as a JSON log so a Mini App can show "当天候选均已投稿" instead of
+ * treating the slot as a system failure.
+ */
+function candidateExhaustionDiagnostic(outcome) {
+    const scan = outcome.scan;
+    if (!scan)
+        return null;
+    const skipped = scan.skipped;
+    const duplicates = skipped.filter((s) => s.code === 'duplicate').length;
+    const filtered = skipped.filter((s) => s.code !== 'duplicate' && s.code !== 'unavailable').length;
+    const reason = isDuplicateOnlyDeadEnd(outcome)
+        ? 'duplicate_exhausted'
+        : filtered > 0
+            ? 'filter_exhausted'
+            : 'no_candidate';
+    return {
+        stage: 'candidate_selection',
+        result: 'no_candidate',
+        reason,
+        searched: skipped.length,
+        duplicates,
+        filtered,
+        attempted: scan.attempted,
+    };
+}
+function isDuplicateOnlyDeadEnd(outcome) {
+    if (outcome.kind !== 'no_candidate' || !outcome.scan)
+        return false;
+    const s = outcome.scan;
+    return (s.attempted === 0 &&
+        s.outages.length === 0 &&
+        s.skipped.length > 0 &&
+        s.skipped.every((skip) => skip.code === 'duplicate'));
+}
 /**
  * Expanded, still-bounded candidate scan bound for one fallback stage
  * (§schedule-recovery). Stage 0 is the primary pass; stage N scans
@@ -536,13 +576,26 @@ async function createSchedulerRuntime(configPathArg) {
             // an exhausted occurrence reports the true cause — never a generic
             // "target did not complete".
             if (!scheduleSlot.manualRequestId &&
-                (outcome.kind === 'no_candidate' || outcome.kind === 'duplicate') &&
+                (outcome.kind === 'duplicate' ||
+                    (outcome.kind === 'no_candidate' && !isDuplicateOnlyDeadEnd(outcome))) &&
                 coordinator.cellFallbackStage(scheduleSlot.slotId, target.id) < maxFallbackStages - 1) {
                 coordinator.advanceFallback(scheduleSlot.slotId, target.id, outcome.kind === 'duplicate'
                     ? `duplicate candidates (stage ${coordinator.cellFallbackStage(scheduleSlot.slotId, target.id)})`
                     : outcome.reason ?? 'no eligible candidate', maxFallbackStages);
                 return;
             }
+            if (outcome.kind === 'no_candidate') {
+                const diag = candidateExhaustionDiagnostic(outcome);
+                if (diag) {
+                    logger_1.logger.info('candidate_exhaustion', {
+                        schedule_id: scheduleSlot.scheduleId,
+                        slot_id: scheduleSlot.slotId,
+                        bot_id: scheduleSlot.scheduleId?.split('-')[0],
+                        target_id: target.id,
+                        ...diag,
+                    });
+                }
+            }
             coordinator.applyOutcome(scheduleSlot.slotId, target.id, outcome);
             notificationPolicy.noteOutcome(scheduleSlot.slotId, scheduleSlot, schedule, target, outcome);
             if (scheduleSlot.manualRequestId && (outcome.kind === 'no_candidate' || outcome.kind === 'duplicate' ||

package/dist/download/exec/DownloadExecutor.js

@@ -26,8 +26,11 @@ class DownloadExecutor {
                         itemId: item?.id,
                         ...(contextProvider?.(item, index) ?? {}),
                     };
+                    const itemId = item?.id ?? item?.pixivId ?? String(item);
+                    logger_1.logger.info('download_started', { pixiv_id: itemId, attempt, stage: 'download' });
                     try {
                         const res = await task(item, index);
+                        logger_1.logger.info('download_completed', { pixiv_id: itemId, attempt, stage: 'download' });
                         results[index] = res;
                         break;
                     }
@@ -35,21 +38,27 @@ class DownloadExecutor {
                         onError?.(error, item, index, attempt);
                         const decision = recovery.decide(error, effectiveContext);
                         onDecision?.(decision, { item, index, attempt, error });
+                        const status = error?.status;
+                        const errMsg = error instanceof Error ? error.message : String(error);
                         if (decision.action === 'skip') {
-                            logger_1.logger.warn(`Skipping item at index ${index} after attempt ${attempt}${decision.reason ? `: ${decision.reason}` : ''}`);
+                            logger_1.logger.warn(status ? `download_http_failed` : `download_failed`, {
+                                pixiv_id: itemId, attempt, stage: 'download', http_status: status ?? null, error: errMsg,
+                            });
                             break;
                         }
                         if (decision.action === 'fail') {
+                            logger_1.logger.error(`download_failed`, { pixiv_id: itemId, attempt, stage: 'download', http_status: status ?? null, error: errMsg });
                             throw error instanceof Error ? error : new Error(String(error));
                         }
                         // retry/backoff
                         const delayMs = decision.delayMs ?? 0;
+                        logger_1.logger.warn(`download_retry`, { pixiv_id: itemId, attempt, stage: 'download', http_status: status ?? null, retry_delay_ms: delayMs, error: errMsg });
                         if (delayMs > 0) {
                             await new Promise((resolve) => setTimeout(resolve, delayMs));
                         }
                         attempt += 1;
                         if (attempt > (decision.maxAttempts ?? maxAttempts)) {
-                            logger_1.logger.error(`Max attempts reached for item at index ${index}; failing`);
+                            logger_1.logger.error(`download_failed`, { pixiv_id: itemId, attempt, stage: 'download', http_status: status ?? null, error: errMsg });
                             throw error instanceof Error ? error : new Error(String(error));
                         }
                     }

package/dist/download/handlers/IllustrationTargetHandler.js

@@ -8,6 +8,8 @@ const pixiv_utils_1 = require("../../utils/pixiv-utils");
 const TargetOutcome_1 = require("../../scheduler/TargetOutcome");
 const WorkIdentity_1 = require("../../scheduler/WorkIdentity");
 const target_label_1 = require("../../utils/target-label");
+const observability_1 = require("../../observability");
+const context_1 = require("../../observability/context");
 const DownloadPlanner_1 = require("../plan/DownloadPlanner");
 const deliveryContext_1 = require("./deliveryContext");
 class IllustrationTargetHandler {
@@ -159,6 +161,13 @@ class IllustrationTargetHandler {
     classifyError(error, displayTag, mode, target) {
         const message = error instanceof Error ? error.message : String(error);
         const scan = this.scan ?? undefined;
+        const cls = (0, observability_1.classifySystemError)(error, error.status, 'pixiv_download');
+        (0, observability_1.recordSystemError)(this.database, (0, context_1.targetErrorContext)(target, this.execution, {
+            message,
+            stage: 'pixiv_download',
+            ...cls,
+            trace_id: this.execution?.slotId,
+        }), cls);
         // A hard job-level outage is named as such and is never recorded as a
         // no-candidate business outcome, whatever its message happens to look like.
         const outage = (0, TargetOutcome_1.classifyJobLevelOutage)(error);
@@ -166,6 +175,8 @@ class IllustrationTargetHandler {
         logger_1.logger.error(`Illustration ${mode === 'ranking' ? 'ranking' : 'tag'} ${displayTag} failed`, {
             error: message,
             errorType: error instanceof Error ? error.constructor.name : typeof error,
+            error_type: cls.error_type,
+            retryable: cls.retryable,
             ...(outage ? { jobLevelOutage: outage } : {}),
         });
         if (outage) {
@@ -508,9 +519,13 @@ class IllustrationTargetHandler {
         if (endpoint) {
             errorMessage = `${errorMessage} [URL: ${endpoint}]`;
         }
+        const cls = (0, observability_1.classifySystemError)(error, error.status, 'pixiv_download');
+        (0, observability_1.recordSystemError)(this.database, (0, context_1.targetErrorContext)({ type: 'illustration' }, this.execution, { message: errorMessage, stage: 'pixiv_download', ...cls, trace_id: this.execution?.slotId }), cls);
         logger_1.logger.error(message, {
             error: errorMessage,
             errorType: error instanceof Error ? error.constructor.name : typeof error,
+            error_type: cls.error_type,
+            retryable: cls.retryable,
             stack: error instanceof Error ? error.stack : undefined,
         });
     }

package/dist/download/handlers/NovelTargetHandler.js

@@ -8,6 +8,8 @@ const pixiv_utils_1 = require("../../utils/pixiv-utils");
 const TargetOutcome_1 = require("../../scheduler/TargetOutcome");
 const WorkIdentity_1 = require("../../scheduler/WorkIdentity");
 const target_label_1 = require("../../utils/target-label");
+const observability_1 = require("../../observability");
+const context_1 = require("../../observability/context");
 const DownloadPlanner_1 = require("../plan/DownloadPlanner");
 const deliveryContext_1 = require("./deliveryContext");
 class NovelTargetHandler {
@@ -109,7 +111,7 @@ class NovelTargetHandler {
             return this.summarize();
         }
         catch (error) {
-            return this.classifyError(error, displayTag, mode);
+            return this.classifyError(error, displayTag, mode, target);
         }
     }
     /**
@@ -165,15 +167,19 @@ class NovelTargetHandler {
             ...(scan ? { scan } : {}),
         };
     }
-    classifyError(error, displayTag, mode) {
+    classifyError(error, displayTag, mode, target) {
         const message = error instanceof Error ? error.message : String(error);
         const scan = this.scan ?? undefined;
+        const cls = (0, observability_1.classifySystemError)(error, error.status, 'pixiv_download');
+        (0, observability_1.recordSystemError)(this.database, (0, context_1.targetErrorContext)(target, this.execution, { message, stage: 'pixiv_download', ...cls, trace_id: this.execution?.slotId }), cls);
         // A hard job-level outage is named as such and is never recorded as a
         // no-candidate business outcome, whatever its message happens to look like.
         const outage = (0, TargetOutcome_1.classifyJobLevelOutage)(error);
         this.database.logExecution(displayTag, 'novel', 'failed', message);
         logger_1.logger.error(`Novel ${mode === 'ranking' ? 'ranking' : 'tag'} ${displayTag} failed`, {
             error: message,
+            error_type: cls.error_type,
+            retryable: cls.retryable,
             ...(outage ? { jobLevelOutage: outage } : {}),
         });
         if (outage) {
@@ -535,9 +541,13 @@ class NovelTargetHandler {
         if (endpoint) {
             errorMessage = `${errorMessage} [URL: ${endpoint}]`;
         }
+        const cls = (0, observability_1.classifySystemError)(error, error.status, 'pixiv_download');
+        (0, observability_1.recordSystemError)(this.database, (0, context_1.targetErrorContext)({ type: 'novel' }, this.execution, { message: errorMessage, stage: 'pixiv_download', ...cls, trace_id: this.execution?.slotId }), cls);
         logger_1.logger.error(message, {
             error: errorMessage,
             errorType: error instanceof Error ? error.constructor.name : typeof error,
+            error_type: cls.error_type,
+            retryable: cls.retryable,
             stack: error instanceof Error ? error.stack : undefined,
         });
     }

package/dist/interfaces/IDatabase.d.ts

@@ -112,5 +112,16 @@ export interface IDatabase {
      * Update file path in database
      */
     updateFilePath(pixivId: string, type: 'illustration' | 'novel', oldPath: string, newPath: string): number;
+    /**
+     * Durable system-error ledger (observability; never throws).
+     */
+    readonly systemErrors: {
+        record(input: import('../observability/types').SystemErrorInput): void;
+        list(opts?: Record<string, unknown>): import('../observability/types').SystemErrorRow[];
+        markResolved(id: number): {
+            changes: number;
+        };
+        countSince(botId: string | null, hours: number): number;
+    };
 }
 //# sourceMappingURL=IDatabase.d.ts.map

package/dist/logger.d.ts

@@ -1,18 +1,42 @@
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type LogFormat = 'text' | 'json';
+export interface LogContext {
+    service?: string;
+    component?: string;
+    bot_id?: string;
+    schedule_id?: string;
+    slot_id?: string;
+    pixiv_id?: string;
+    stage?: string;
+    trace_id?: string;
+    [key: string]: unknown;
+}
 interface LogMeta {
     [key: string]: unknown;
 }
 declare class Logger {
     private static readonly levelOrder;
     private threshold;
+    private format;
     private logPath;
     setLevel(level: LogLevel): void;
+    setFormat(format: LogFormat): void;
+    /** Run `fn` with a log context that is merged into every log line emitted inside. */
+    runWithContext<T>(ctx: LogContext, fn: () => T): T;
     setLogPath(path: string): void;
     debug(message: string, meta?: LogMeta): void;
     info(message: string, meta?: LogMeta): void;
     warn(message: string, meta?: LogMeta): void;
     error(message: string, meta?: LogMeta): void;
     private write;
+    /**
+     * Rotate the current log file when it exceeds the size cap:
+     * rename to <name>-<ts>.log.gz, then prune archived logs older than
+     * retention days. Run inside write (low-traffic scheduler, acceptable;
+     * use a background job if this ever becomes a high-rate service).
+     */
+    private rotateIfNeeded;
+    private pruneArchives;
 }
 export declare const logger: Logger;
 export {};

package/dist/logger.js

@@ -3,6 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.logger = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const node_async_hooks_1 = require("node:async_hooks");
+const node_zlib_1 = require("node:zlib");
+const ctxStore = new node_async_hooks_1.AsyncLocalStorage();
+function defaultMaxBytes() {
+    const parsed = Number.parseInt(process.env.PIXIV_LOG_MAX_BYTES ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 20 * 1024 * 1024;
+}
+function retentionDays() {
+    const parsed = Number.parseInt(process.env.PIXIV_LOG_RETENTION_DAYS ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 30;
+}
 class Logger {
     static levelOrder = {
         debug: 10,
@@ -11,13 +22,20 @@ class Logger {
         error: 40,
     };
     threshold = 'info';
+    format = process.env.PIXIV_LOG_FORMAT === 'json' ? 'json' : 'text';
     logPath = null;
     setLevel(level) {
         this.threshold = level;
     }
+    setFormat(format) {
+        this.format = format;
+    }
+    /** Run `fn` with a log context that is merged into every log line emitted inside. */
+    runWithContext(ctx, fn) {
+        return ctxStore.run(ctx, fn);
+    }
     setLogPath(path) {
         this.logPath = path;
-        // Ensure log directory exists
         const logDir = (0, path_1.join)(path, '..');
         if (!(0, fs_1.existsSync)(logDir)) {
             (0, fs_1.mkdirSync)(logDir, { recursive: true });
@@ -36,13 +54,19 @@ class Logger {
         this.write('error', message, meta);
     }
     write(level, message, meta) {
-        if (Logger.levelOrder[level] < Logger.levelOrder[this.threshold]) {
+        if (Logger.levelOrder[level] < Logger.levelOrder[this.threshold])
             return;
-        }
-        const timestamp = new Date().toISOString();
-        const payload = meta ? `${message} ${JSON.stringify(meta)}` : message;
-        const logLine = `[${timestamp}] [${level.toUpperCase()}] ${payload}`;
-        // Output to console
+        const ctx = ctxStore.getStore();
+        const record = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            ...(ctx ?? {}),
+            ...(meta ?? {}),
+        };
+        const logLine = this.format === 'json'
+            ? JSON.stringify(record)
+            : `[${record.timestamp}] [${level.toUpperCase()}] ${message}${meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : ''}`;
         switch (level) {
             case 'debug':
                 console.debug(logLine);
@@ -56,20 +80,73 @@ class Logger {
             case 'error':
                 console.error(logLine);
                 break;
-            default:
-                console.log(logLine);
+            default: console.log(logLine);
         }
-        // Write to file if log path is set
         if (this.logPath) {
             try {
+                this.rotateIfNeeded();
                 (0, fs_1.appendFileSync)(this.logPath, logLine + '\n', 'utf-8');
             }
             catch (error) {
-                // Silently fail if file write fails to avoid breaking the application
                 console.error('Failed to write to log file', error);
             }
         }
     }
+    /**
+     * Rotate the current log file when it exceeds the size cap:
+     * rename to <name>-<ts>.log.gz, then prune archived logs older than
+     * retention days. Run inside write (low-traffic scheduler, acceptable;
+     * use a background job if this ever becomes a high-rate service).
+     */
+    rotateIfNeeded() {
+        if (!this.logPath)
+            return;
+        let size = 0;
+        try {
+            if ((0, fs_1.existsSync)(this.logPath))
+                size = (0, fs_1.statSync)(this.logPath).size;
+        }
+        catch {
+            return;
+        }
+        if (size < defaultMaxBytes())
+            return;
+        try {
+            const dir = (0, path_1.join)(this.logPath, '..');
+            const base = (0, path_1.basename)(this.logPath);
+            const name = base.replace(/\.log$/, '');
+            const stamped = (0, path_1.join)(dir, `${name}-${new Date().toISOString().replace(/[:.]/g, '-')}.log`);
+            (0, fs_1.renameSync)(this.logPath, stamped);
+            (0, fs_1.writeFileSync)(`${stamped}.gz`, (0, node_zlib_1.gzipSync)((0, fs_1.readFileSync)(stamped)));
+            (0, fs_1.unlinkSync)(stamped);
+            this.pruneArchives(dir, `${name}-`, retentionDays());
+        }
+        catch (error) {
+            console.error('Failed to rotate log file', error);
+        }
+    }
+    pruneArchives(dir, prefix, days) {
+        const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+        let entries;
+        try {
+            entries = (0, fs_1.readdirSync)(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.startsWith(prefix) || !entry.endsWith('.log.gz'))
+                continue;
+            try {
+                const p = (0, path_1.join)(dir, entry);
+                if ((0, fs_1.statSync)(p).mtimeMs < cutoff)
+                    (0, fs_1.unlinkSync)(p);
+            }
+            catch {
+                // best effort
+            }
+        }
+    }
 }
 exports.logger = new Logger();
 //# sourceMappingURL=logger.js.map

package/dist/observability/classify.d.ts

@@ -0,0 +1,7 @@
+import { SystemErrorClassification } from './types';
+/**
+ * Map an error (message / HTTP status / constructor name) to a stable
+ * download/system error class and whether it is safe to retry.
+ */
+export declare function classifySystemError(error: unknown, httpStatus?: number | null, stage?: string, messageHint?: string): SystemErrorClassification;
+//# sourceMappingURL=classify.d.ts.map

package/dist/observability/classify.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySystemError = classifySystemError;
+const KNOWN_SUBTYPES = {
+    pixiv_network_5xx: 'NETWORK_TIMEOUT',
+    pixiv_network_4xx: 'NETWORK_TIMEOUT',
+};
+/**
+ * Map an error (message / HTTP status / constructor name) to a stable
+ * download/system error class and whether it is safe to retry.
+ */
+function classifySystemError(error, httpStatus, stage, messageHint) {
+    const message = messageHint ?? (error instanceof Error ? error.message : String(error ?? ''));
+    const name = error instanceof Error ? error.constructor.name : typeof error;
+    const status = typeof httpStatus === 'number' ? httpStatus : null;
+    if (name === 'ConfigError' || /does not configure|unsupported .*target|invalid config/i.test(message)) {
+        return { error_type: 'CONFIG_ERROR', retryable: false };
+    }
+    if (status === 429 || /429|rate.?limit|cooldown/i.test(message)) {
+        return { error_type: 'PIXIV_RATE_LIMITED', retryable: true };
+    }
+    if (status === 401 || status === 403 || /login|auth|token|forbidden|invalid.*refresh|expired.*token/i.test(message)) {
+        const cdn = /cdn|i\.pximg|img\.pixiv/i.test(message);
+        return cdn
+            ? { error_type: 'PIXIV_CDN_FORBIDDEN', retryable: false }
+            : { error_type: 'PIXIV_AUTH_FAILED', retryable: status === 401 };
+    }
+    if (status === 404 || /404|not found|does not exist/i.test(message)) {
+        return { error_type: 'PIXIV_NOT_FOUND', retryable: false };
+    }
+    if (/timeout|timed out|abort|aborted|econn|enotfound|etimedout|network|socket|refused|unavailable|ECONN/i.test(message) || name === 'AbortError') {
+        return { error_type: 'NETWORK_TIMEOUT', retryable: true };
+    }
+    if (/corrupt|invalid image|unexpected eof|truncated/i.test(message)) {
+        return { error_type: 'DOWNLOAD_CORRUPTED', retryable: true };
+    }
+    if (stage === 'image_process' || /convert|processing|\bimage process/i.test(message)) {
+        return { error_type: 'IMAGE_PROCESS_FAILED', retryable: stage === 'image_process' };
+    }
+    if (/telegram|sendMessage|upload/i.test(message)) {
+        return { error_type: 'TELEGRAM_UPLOAD_FAILED', retryable: false };
+    }
+    if (typeof status === 'number' && status >= 500) {
+        return { error_type: 'NETWORK_TIMEOUT', retryable: true };
+    }
+    if (name in KNOWN_SUBTYPES) {
+        return { error_type: KNOWN_SUBTYPES[name], retryable: true };
+    }
+    return { error_type: 'INTERNAL_ERROR', retryable: true };
+}
+//# sourceMappingURL=classify.js.map

package/dist/observability/context.d.ts

@@ -0,0 +1,10 @@
+import { TargetConfig } from '../config';
+import { TargetExecutionContext } from '../scheduler/WorkIdentity';
+import { SystemErrorInput } from './types';
+/**
+ * Build the standard structured error fields for a target-cell handler from
+ * the cell identity plus the current stage/error. Nothing here throws.
+ * bot_id / schedule_id derive from the slot identity (`bot1-daily@...`).
+ */
+export declare function targetErrorContext(target: TargetConfig, execution: TargetExecutionContext | null, extra: Partial<SystemErrorInput>): SystemErrorInput;
+//# sourceMappingURL=context.d.ts.map

package/dist/observability/context.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.targetErrorContext = targetErrorContext;
+/**
+ * Build the standard structured error fields for a target-cell handler from
+ * the cell identity plus the current stage/error. Nothing here throws.
+ * bot_id / schedule_id derive from the slot identity (`bot1-daily@...`).
+ */
+function targetErrorContext(target, execution, extra) {
+    const slotId = execution?.slotId;
+    const scheduleId = slotId ? slotId.split('@')[0] : undefined;
+    const botId = scheduleId ? scheduleId.split('-')[0] : undefined;
+    return {
+        service: 'pixivflow',
+        component: target.type === 'novel' ? 'novel_target' : 'illustration_target',
+        schedule_id: scheduleId,
+        bot_id: botId,
+        slot_id: slotId,
+        ...extra,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/observability/index.d.ts

@@ -0,0 +1,7 @@
+import { IDatabase } from '../interfaces/IDatabase';
+import { SystemErrorClassification, SystemErrorInput } from './types';
+export { classifySystemError } from './classify';
+export * from './types';
+/** Record a structured system error with taxonomy; never throws. */
+export declare function recordSystemError(database: Pick<IDatabase, 'systemErrors'>, input: SystemErrorInput, classified?: SystemErrorClassification | null): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySystemError = void 0;
+exports.recordSystemError = recordSystemError;
+const logger_1 = require("../logger");
+const classify_1 = require("./classify");
+var classify_2 = require("./classify");
+Object.defineProperty(exports, "classifySystemError", { enumerable: true, get: function () { return classify_2.classifySystemError; } });
+__exportStar(require("./types"), exports);
+/** Record a structured system error with taxonomy; never throws. */
+function recordSystemError(database, input, classified = null) {
+    try {
+        const cls = classified ?? (0, classify_1.classifySystemError)(new Error(input.message), input.http_status ?? null, input.stage);
+        database.systemErrors.record({ ...input, ...cls });
+        logger_1.logger.error(`system_error recorded`, { error_type: cls.error_type, retryable: cls.retryable, ...input });
+    }
+    catch (error) {
+        // Observability must never break the business path.
+        console.error('Failed to persist system error', error);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/observability/types.d.ts

@@ -0,0 +1,23 @@
+export type SystemErrorType = 'PIXIV_AUTH_FAILED' | 'PIXIV_RATE_LIMITED' | 'PIXIV_NOT_FOUND' | 'PIXIV_CDN_FORBIDDEN' | 'NETWORK_TIMEOUT' | 'DOWNLOAD_CORRUPTED' | 'IMAGE_PROCESS_FAILED' | 'TELEGRAM_UPLOAD_FAILED' | 'CONFIG_ERROR' | 'INTERNAL_ERROR';
+export interface SystemErrorClassification {
+    error_type: SystemErrorType;
+    retryable: boolean;
+}
+export interface SystemErrorInput extends Partial<SystemErrorClassification> {
+    service?: string;
+    component?: string;
+    bot_id?: string;
+    schedule_id?: string;
+    slot_id?: string;
+    pixiv_id?: string;
+    stage?: string;
+    message: string;
+    http_status?: number | null;
+    trace_id?: string;
+}
+export interface SystemErrorRow extends SystemErrorInput {
+    id: number;
+    created_at: string;
+    resolved_at: string | null;
+}
+//# sourceMappingURL=types.d.ts.map