pixivflow 2.22.1 → 2.24.0

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/notification/NotificationPolicy.js

@@ -50,12 +50,18 @@ class NotificationPolicy {
     };
     noteOutcome(slotId, slot, schedule, target, outcome) {
         const name = this.targetName(target);
-        if (!name)
+        if (!name) {
+            logger_1.logger.debug('Notification skipped: target has no delivery target name', {
+                targetId: target.id ?? target.filterTag ?? target.tag ?? target.type,
+            });
             return;
+        }
         // No notifiable endpoint configured: drop the notification instead of
         // enqueuing it against a submission target that will reject it forever.
-        if (!this.notifiableTargets().has(name))
+        if (!this.notifiableTargets().has(name)) {
+            logger_1.logger.debug(`Notification skipped for ${name}: no notifiable endpoint configured`, { targetName: name });
             return;
+        }
         const label = target.id || target.filterTag || target.tag || target.type;
         if (outcome.kind === 'no_candidate' && target.noMatchPolicy?.notify === true) {
             this.send(name, NotificationPolicy.keys.noMatch(slotId, target.id ?? label), [
@@ -77,8 +83,16 @@ class NotificationPolicy {
     }
     /** One consolidated summary per slot, delivered to every notifying target's endpoint. */
     sendSlotSummary(slot, schedule, rows) {
-        if (slot.manualRequestId || rows.length === 0 || rows.some((r) => !['submitted', 'no_candidate', 'duplicate', 'failed'].includes(r.status)))
+        if (slot.manualRequestId || rows.length === 0)
             return;
+        const nonSummaryRows = rows.filter((r) => !['submitted', 'no_candidate', 'duplicate', 'failed'].includes(r.status));
+        if (nonSummaryRows.length) {
+            logger_1.logger.warn(`Slot summary skipped: ${nonSummaryRows.length} row(s) with non-summarizable status`, {
+                slotId: slot.slotId,
+                targets: nonSummaryRows.map((r) => ({ targetId: r.targetId, status: r.status })),
+            });
+            return;
+        }
         const memberIds = new Set(rows.map((r) => r.targetId));
         const targets = this.targetsWithUrl('scheduleOutcomeUrl', memberIds);
         if (targets.size === 0)
@@ -174,8 +188,7 @@ class NotificationPolicy {
         }
         catch (error) {
             // Durable enqueue failure must not unwind the content run.
-            // eslint-disable-next-line no-console
-            console.warn('notification enqueue failed', { targetName, key, error: error.message });
+            logger_1.logger.warn('notification enqueue failed', { targetName, key, error: error.message });
         }
     }
     /**

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

package/dist/observability/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow",
-  "version": "2.22.1",
+  "version": "2.24.0",
   "private": true
 }

package/dist/scheduler/RecoveryOutcome.d.ts

@@ -0,0 +1,24 @@
+import type { SlotItemRecord } from '../storage/repositories/SlotRepository';
+/**
+ * Business outcome for one manual recovery request (「放宽条件重试」).
+ *
+ * Deliberately NOT the raw execution cell status: a recovery that found only
+ * already-published works is a NORMAL end (`recovery_duplicate_only`), never an
+ * `internal_error`. Callers (ScheduleTriggerServer / Mini App) get the
+ * user-facing `message` and admin-facing `business_state` together so the UI
+ * never has to translate internal terms.
+ */
+export type RecoveryOutcomeState = 'recovery_pending' | 'recovery_running' | 'recovery_success' | 'recovery_no_candidate' | 'recovery_duplicate_only' | 'recovery_failed';
+export declare function recoveryUserMessage(state: RecoveryOutcomeState): string;
+/**
+ * Map one durable recovery cell to a recovery business outcome.
+ *
+ * - terminal `submitted` (+ workId) → success
+ * - terminal `no_candidate` with terminal reason `duplicate_exhausted` →
+ *   duplicate_only
+ * - terminal `no_candidate` otherwise → no_candidate
+ * - terminal `failed` → failed
+ * - non-terminal (`pending`/`selected`/`running`/`delivery_pending`) → running/pending
+ */
+export declare function recoveryOutcomeFor(cell: SlotItemRecord | null): RecoveryOutcomeState;
+//# sourceMappingURL=RecoveryOutcome.d.ts.map

package/dist/scheduler/RecoveryOutcome.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoveryUserMessage = recoveryUserMessage;
+exports.recoveryOutcomeFor = recoveryOutcomeFor;
+const USER_MESSAGES = {
+    recovery_pending: '正在等待恢复任务...',
+    recovery_running: '正在尝试扩大搜索范围...',
+    recovery_success: '恢复成功，已找到并发布新作品。',
+    recovery_no_candidate: '扩大搜索范围后，仍未找到符合条件的新作品。\n任务已正常结束。',
+    recovery_duplicate_only: '扩大搜索范围后，找到的作品均已发布过。\n没有新的内容可发布。',
+    recovery_failed: '恢复任务执行失败。\n请查看日志或稍后重试。',
+};
+function recoveryUserMessage(state) {
+    return USER_MESSAGES[state];
+}
+/**
+ * Map one durable recovery cell to a recovery business outcome.
+ *
+ * - terminal `submitted` (+ workId) → success
+ * - terminal `no_candidate` with terminal reason `duplicate_exhausted` →
+ *   duplicate_only
+ * - terminal `no_candidate` otherwise → no_candidate
+ * - terminal `failed` → failed
+ * - non-terminal (`pending`/`selected`/`running`/`delivery_pending`) → running/pending
+ */
+function recoveryOutcomeFor(cell) {
+    if (!cell)
+        return 'recovery_pending';
+    if (cell.status === 'submitted')
+        return 'recovery_success';
+    if (cell.status === 'no_candidate') {
+        return cell.terminalReasonCode === 'duplicate_exhausted'
+            ? 'recovery_duplicate_only'
+            : 'recovery_no_candidate';
+    }
+    if (cell.status === 'duplicate')
+        return 'recovery_duplicate_only';
+    if (cell.status === 'failed')
+        return 'recovery_failed';
+    if (['pending', 'selected', 'artifact_ready', 'delivery_pending'].includes(cell.status))
+        return 'recovery_running';
+    return 'recovery_pending';
+}
+//# sourceMappingURL=RecoveryOutcome.js.map

package/dist/scheduler/ScheduleTriggerServer.d.ts

@@ -126,6 +126,10 @@ export interface TriggerHandlers {
         slotId: string;
         state: string;
         slotStatus: string;
+        /** Recovery business outcome (recovery_success / no_candidate / duplicate_only / failed / running / pending). */
+        business_state?: string;
+        /** User-facing copy; never leaks internal error names. */
+        message?: string;
     } | null;
 }
 export declare class ScheduleTriggerServer {

package/dist/scheduler/SlotBusinessStatus.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Business outcome taxonomy for one schedule occurrence.
+ *
+ * RULES (intent):
+ * - "no content to publish" is a NORMAL endpoint, not a system failure.
+ * - System failures (pixiv/network/download/processing/delivery) must be kept
+ *   disjoint from business no-content states so monitoring and Mini App never
+ *   show "internal_error" for an empty but healthy run.
+ *
+ * This is a DERIVED verdict over the existing terminal cell ledger; it does not
+ * change the persisted slot phase machine (pending/running/success/partial/
+ * failed remain untouched for ledger compatibility).
+ */
+export type SlotBusinessStatus = 'success' | 'partial_success' | 'no_candidate' | 'duplicate_only' | 'failed';
+export interface SlotBusinessCounts {
+    total: number;
+    submitted: number;
+    no_match: number;
+    duplicate: number;
+    /** Count of no_candidate cells whose terminal reason is duplicate_exhausted. */
+    duplicate_exhausted?: number;
+    executor_failed: number;
+    delivery_failed: number;
+}
+/** Pure projection: durable cell counts -> one business verdict. No I/O. */
+export declare function classifySlotBusinessStatus(counts: SlotBusinessCounts): SlotBusinessStatus;
+/**
+ * User-facing (Mini App / notification) copy for a terminal business status.
+ * Internal error names (OperationCancelledError, internal_error) never leak.
+ */
+export declare function userMessageForSlotBusinessStatus(status: SlotBusinessStatus): string;
+//# sourceMappingURL=SlotBusinessStatus.d.ts.map

package/dist/scheduler/SlotBusinessStatus.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySlotBusinessStatus = classifySlotBusinessStatus;
+exports.userMessageForSlotBusinessStatus = userMessageForSlotBusinessStatus;
+/** Pure projection: durable cell counts -> one business verdict. No I/O. */
+function classifySlotBusinessStatus(counts) {
+    const nonSubmitted = counts.total - counts.submitted;
+    const systemFailed = counts.executor_failed > 0 || counts.delivery_failed > 0;
+    const allNoContentAsDuplicate = counts.duplicate + (counts.duplicate_exhausted ?? 0) === nonSubmitted;
+    if (counts.submitted > 0 && nonSubmitted === 0)
+        return 'success';
+    if (counts.submitted > 0)
+        return 'partial_success';
+    if (nonSubmitted === 0)
+        return 'success'; // defensive: 0 targets / all submitted
+    if (!systemFailed) {
+        // Every non-submitted cell was a BUSINESS no-content verdict; all of them
+        // came from already-delivered candidates => duplicate_only.
+        if (allNoContentAsDuplicate)
+            return 'duplicate_only';
+        return 'no_candidate';
+    }
+    return 'failed';
+}
+/**
+ * User-facing (Mini App / notification) copy for a terminal business status.
+ * Internal error names (OperationCancelledError, internal_error) never leak.
+ */
+function userMessageForSlotBusinessStatus(status) {
+    switch (status) {
+        case 'success':
+            return '任务完成，已发布本轮内容。';
+        case 'partial_success':
+            return '任务部分完成，部分内容已发布。';
+        case 'no_candidate':
+            return '本轮没有发现新的可发布作品。任务已正常完成。';
+        case 'duplicate_only':
+            return '本轮没有发现新的可发布作品。任务已正常完成。';
+        case 'failed':
+            return '本轮任务遇到系统异常，请稍后重试或检查日志。';
+    }
+}
+//# sourceMappingURL=SlotBusinessStatus.js.map

package/dist/scheduler/SlotCoordinator.d.ts

@@ -3,6 +3,7 @@ import { Database } from '../storage/Database';
 import { CellStatus, SlotItemRecord, SlotRecord, SlotStatus } from '../storage/repositories/SlotRepository';
 import { TriggerSource } from './OccurrenceResolver';
 import { TargetOutcome } from './TargetOutcome';
+import { SlotBusinessStatus } from './SlotBusinessStatus';
 import { TargetExecutionContext, WorkBinding } from './WorkIdentity';
 /**
  * Execution-lease TTL and heartbeat cadence.
@@ -113,11 +114,17 @@ export interface ScheduleOutcomeCells {
  */
 export interface ScheduleOutcomeRecord {
     event: 'schedule.outcome';
+    /** Outcome taxonomy version; bump when business_status/reason gains codes. */
+    outcome_version: 1;
     schedule_id: string;
     slot_id: string;
     occurrence_at: string | undefined;
     occurrence_date: string;
     status: ScheduleOutcomeStatus;
+    /** Derived business verdict: success / partial_success / no_candidate / duplicate_only / failed. */
+    business_status: SlotBusinessStatus;
+    /** Monitoring gate: true only for system failures (business_status === 'failed'). */
+    alertable: boolean;
     /** From the slot row's own started_at/completed_at columns, when both exist. */
     duration_ms: number | undefined;
     cells: ScheduleOutcomeCells;

package/dist/scheduler/SlotCoordinator.js

@@ -5,6 +5,7 @@ exports.timezoneForSchedule = timezoneForSchedule;
 const logger_1 = require("../logger");
 const OccurrenceResolver_1 = require("./OccurrenceResolver");
 const TargetOutcome_1 = require("./TargetOutcome");
+const SlotBusinessStatus_1 = require("./SlotBusinessStatus");
 const WorkIdentity_1 = require("./WorkIdentity");
 /**
  * Execution-lease TTL and heartbeat cadence.
@@ -504,13 +505,25 @@ class SlotCoordinator {
             ? Math.max(0, completedMs - startedMs)
             : undefined;
         const occurrenceAt = slotRec?.occurrenceAt ?? slot.occurrenceAt;
+        const businessStatus = (0, SlotBusinessStatus_1.classifySlotBusinessStatus)({
+            total: cellRows.length,
+            submitted,
+            no_match,
+            duplicate,
+            duplicate_exhausted: targetsDetail.filter((t) => t.terminal_reason_code === 'duplicate_exhausted').length,
+            executor_failed,
+            delivery_failed,
+        });
         return {
             event: 'schedule.outcome',
+            outcome_version: 1,
             schedule_id: slotRec?.scheduleId ?? slot.scheduleId,
             slot_id: slot.slotId,
             occurrence_at: isoUtcOrUndefined(occurrenceAt),
             occurrence_date: slotRec?.occurrenceDate ?? slot.occurrenceDate,
             status: status,
+            business_status: businessStatus,
+            alertable: businessStatus === 'failed',
             duration_ms,
             cells: {
                 total: cellRows.length,

package/dist/storage/Database.d.ts

@@ -4,6 +4,7 @@ import { DeliveryRepository } from './repositories/DeliveryRepository';
 import { OutboxRepository } from './repositories/OutboxRepository';
 import { MetadataRepository } from './repositories/MetadataRepository';
 import { SQLiteRateLimitStateStore } from './repositories/RateLimitStateRepository';
+import { SystemErrorRepository } from './repositories/SystemErrorRepository';
 export interface AccessTokenStore {
     accessToken: string;
     expiresAt: number;
@@ -46,6 +47,7 @@ export declare class Database implements IDatabase {
     private outboxRepo;
     private metadataRepo;
     private rateLimitStateStore;
+    private systemErrorRepo;
     constructor(databasePath: string);
     migrate(): void;
     /** Absolute path of the SQLite file (used to locate sibling cache dirs). */
@@ -60,6 +62,8 @@ export declare class Database implements IDatabase {
     get metadata(): MetadataRepository;
     /** Persistent 429 gate state adapter for @redtidev/pixiv-client. */
     get rateLimitState(): SQLiteRateLimitStateStore;
+    /** Durable system-error ledger (observability; never throws). */
+    get systemErrors(): SystemErrorRepository;
     /** Raw transactional boundary for atomic multi-table intents. */
     transaction<T>(fn: () => T): T;
     /** Expose a prepared-statement helper if needed by services (pragmas etc). */

package/dist/storage/Database.js

@@ -17,6 +17,7 @@ const DeliveryRepository_1 = require("./repositories/DeliveryRepository");
 const OutboxRepository_1 = require("./repositories/OutboxRepository");
 const MetadataRepository_1 = require("./repositories/MetadataRepository");
 const RateLimitStateRepository_1 = require("./repositories/RateLimitStateRepository");
+const SystemErrorRepository_1 = require("./repositories/SystemErrorRepository");
 const NodeSqliteDriver_1 = require("./drivers/NodeSqliteDriver");
 class Database {
     databasePath;
@@ -33,6 +34,7 @@ class Database {
     outboxRepo;
     metadataRepo;
     rateLimitStateStore;
+    systemErrorRepo;
     constructor(databasePath) {
         this.databasePath = databasePath;
         try {
@@ -60,6 +62,7 @@ class Database {
             this.outboxRepo = new OutboxRepository_1.OutboxRepository(this.db);
             this.metadataRepo = new MetadataRepository_1.MetadataRepository(this.db);
             this.rateLimitStateStore = new RateLimitStateRepository_1.SQLiteRateLimitStateStore(this.db);
+            this.systemErrorRepo = new SystemErrorRepository_1.SystemErrorRepository(this.db);
         }
         catch (error) {
             throw new errors_1.DatabaseError(`Failed to initialize database at ${this.databasePath}`, error instanceof Error ? error : undefined);
@@ -95,6 +98,10 @@ class Database {
     get rateLimitState() {
         return this.rateLimitStateStore;
     }
+    /** Durable system-error ledger (observability; never throws). */
+    get systemErrors() {
+        return this.systemErrorRepo;
+    }
     /** Raw transactional boundary for atomic multi-table intents. */
     transaction(fn) {
         return this.db.transaction(fn)();