pixivflow 2.29.0 → 2.31.0

package/README.en.md

@@ -69,7 +69,7 @@ pixivflow scheduler             # long-running cron collection
 ```
 
 Prefer not to hand-write config? The interactive wizard `pixivflow setup` generates it.
-For a GUI, run `pixivflow webui` (frontend:
+For a GUI, run `pixivflow web` (frontend:
 [pixivflow-webui](https://github.com/redtidev1918/pixivflow-webui)).
 
 Downloading Pixiv ugoira additionally needs `python3` and `ffmpeg`: frames are
@@ -249,7 +249,7 @@ ledger; dry-run by default).
 | `pixivflow download --url <url>` | Direct download via URL |
 | `pixivflow random` | Random popular artwork |
 | `pixivflow scheduler` | Start scheduled jobs |
-| `pixivflow webui` | Start the WebUI |
+| `pixivflow web` | Start the WebUI |
 | `pixivflow config` | Manage config (view / edit / backup / restore) |
 | `pixivflow status` | Download stats and recent records |
 | `pixivflow health` | Health check: config, directories, connectivity |

package/README.md

@@ -64,7 +64,7 @@ pixivflow scheduler             # 按 cron 配置长期挂机自动收集
 ```
 
 不想手写配置？运行交互式向导 `pixivflow setup` 一步步生成。图形界面用
-`pixivflow webui`（前端见 [pixivflow-webui](https://github.com/redtidev1918/pixivflow-webui)）。
+`pixivflow web`（前端见 [pixivflow-webui](https://github.com/redtidev1918/pixivflow-webui)）。
 
 下载 Pixiv 动图（ugoira）还需要 `python3` 和 `ffmpeg`：程序按逐帧延迟合成循环 GIF，
 可直接作为动画交付给下游。官方 Docker 镜像已包含两者，详见
@@ -227,7 +227,7 @@ pixivflow outbox cancel <id>  # 只取消尚未执行的 row
 | `pixivflow download --url <url>` | 通过 URL 直接下载 |
 | `pixivflow random` | 随机下载热门作品 |
 | `pixivflow scheduler` | 启动定时任务 |
-| `pixivflow webui` | 启动 WebUI |
+| `pixivflow web` | 启动 WebUI |
 | `pixivflow config` | 配置管理（查看 / 编辑 / 备份 / 恢复） |
 | `pixivflow status` | 下载统计与最近记录 |
 | `pixivflow health` | 健康检查：配置、目录可写性、连通性 |

package/dist/commands/WebUICommand.d.ts

@@ -8,8 +8,8 @@ import { CommandContext, CommandArgs, CommandResult } from './types';
  * WebUI command - Start WebUI server
  */
 export declare class WebUICommand extends BaseCommand {
-    readonly name = "webui";
-    readonly description = "Start WebUI server";
+    readonly name = "web";
+    readonly description = "Start WebUI server (memory only when used)";
     readonly aliases: string[];
     readonly metadata: {
         category: CommandCategory;

package/dist/commands/WebUICommand.js

@@ -18,9 +18,9 @@ const child_process_1 = require("child_process");
  * WebUI command - Start WebUI server
  */
 class WebUICommand extends Command_1.BaseCommand {
-    name = 'webui';
-    description = 'Start WebUI server';
-    aliases = ['w'];
+    name = 'web';
+    description = 'Start WebUI server (memory only when used)';
+    aliases = ['w', 'webui'];
     metadata = {
         category: metadata_1.CommandCategory.UTILITY,
         requiresAuth: false,
@@ -437,10 +437,12 @@ Auto-Build Feature:
   the command will automatically build the frontend before starting.
 
 Examples:
-  pixivflow webui                                    # Auto-build if in source directory
-  pixivflow webui --port 8080                        # Use custom port
-  pixivflow webui --host 0.0.0.0                     # Bind to all interfaces
-  pixivflow webui --static-path ./webui-frontend/dist # Use custom static path`;
+  pixivflow web                                      # Start WebUI (loads frontend only now)
+  pixivflow web --port 8080                          # Use custom port
+  pixivflow web --host 0.0.0.0                       # Bind to all interfaces
+  pixivflow web --static-path ./webui-frontend/dist  # Use custom static path
+
+Backward-compatible aliases: pixivflow webui, pixivflow w`;
     }
 }
 exports.WebUICommand = WebUICommand;

package/dist/config/types.d.ts

@@ -27,6 +27,35 @@ export interface CandidateCollectionConfig {
     /** Minimum metadata-topic score to survive filtering (default 0.35). */
     minMetadataScore?: number;
 }
+/** Phase 4: topic-supply strategy (per-target, optional, default off). */
+export interface TopicProfileStrategyConfig {
+    /** Relative weight for publishing fresher works first (0..1, default 0.4). */
+    freshnessWeight?: number;
+    /** Relative weight for publishing higher-popularity works first (0..1, default 0.3). */
+    popularityWeight?: number;
+}
+/** Phase 5: durable candidate inventory ("待发池") for a target. */
+export interface CandidateInventoryConfig {
+    /** Master switch. Default false: no collection, no fallback, no new columns read. */
+    enabled?: boolean;
+    /** Max age (days) a pending candidate may stay usable for fallback. Default 30. */
+    maxAgeDays?: number;
+    /** Max pending rows retained per (topic,target). Default 20. */
+    reserveSize?: number;
+    /** When the fresh/lookback scan is empty, publish oldest pending inventory. Default true. */
+    fallback?: boolean;
+}
+/** Phase 4: TopicProfile (seed + related tags + supply strategy). */
+export interface TopicProfileConfig {
+    /** Primary seed tag(s); first item is the canonical topic when topic is unset. */
+    primary?: string[];
+    /** Related tags that strengthen topic membership evidence. */
+    related?: string[];
+    /** Ranking strategy knobs (Phase 4; wired after CandidateInventory). */
+    strategy?: TopicProfileStrategyConfig;
+    /** CandidateInventory policy (Phase 5). */
+    inventory?: CandidateInventoryConfig;
+}
 /** Behaviour when a target cannot produce the requested number of works. */
 export interface NoMatchPolicyConfig {
     /**
@@ -178,6 +207,8 @@ export interface TargetConfig {
     candidateCollection?: CandidateCollectionConfig;
     /** Bounded fallback and notification policy for an empty result. */
     noMatchPolicy?: NoMatchPolicyConfig;
+    /** Phase 4/5: topic supply profile + candidate inventory policy (all optional). */
+    topicProfile?: TopicProfileConfig;
     /**
      * Ranking mode (only used when mode='ranking')
      * - 'day': Daily ranking

package/dist/config/validation.js

@@ -240,6 +240,41 @@ function validateConfig(config, location, databasePath) {
             if (target.noMatchPolicy?.notify !== undefined && typeof target.noMatchPolicy.notify !== 'boolean') {
                 errors.push(`targets[${index}].noMatchPolicy.notify: Must be a boolean`);
             }
+            if (target.topicProfile) {
+                const tp = target.topicProfile;
+                if (tp.primary !== undefined && (!Array.isArray(tp.primary) || tp.primary.length === 0 || tp.primary.some((x) => typeof x !== 'string' || !x.trim()))) {
+                    errors.push(`targets[${index}].topicProfile.primary: Must be a non-empty string array`);
+                }
+                if (tp.related !== undefined && (!Array.isArray(tp.related) || tp.related.some((x) => typeof x !== 'string' || !x.trim()))) {
+                    errors.push(`targets[${index}].topicProfile.related: Must be a string array`);
+                }
+                const st = tp.strategy;
+                if (st) {
+                    for (const field of ['freshnessWeight', 'popularityWeight']) {
+                        const value = st[field];
+                        if (value !== undefined && (typeof value !== 'number' || value < 0 || value > 1)) {
+                            errors.push(`targets[${index}].topicProfile.strategy.${field}: Must be a number between 0 and 1`);
+                        }
+                    }
+                }
+                const inv = tp.inventory;
+                if (inv) {
+                    if (inv.enabled !== undefined && typeof inv.enabled !== 'boolean') {
+                        errors.push(`targets[${index}].topicProfile.inventory.enabled: Must be a boolean`);
+                    }
+                    const bound = (field) => {
+                        const value = inv[field];
+                        if (value !== undefined && (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 365)) {
+                            errors.push(`targets[${index}].topicProfile.inventory.${field}: Must be an integer between 1 and 365`);
+                        }
+                    };
+                    bound('maxAgeDays');
+                    bound('reserveSize');
+                    if (inv.fallback !== undefined && typeof inv.fallback !== 'boolean') {
+                        errors.push(`targets[${index}].topicProfile.inventory.fallback: Must be a boolean`);
+                    }
+                }
+            }
             if (target.noMatchPolicy?.notify === true) {
                 const deliveryTarget = target.delivery?.target?.trim();
                 const notifyTarget = deliveryTarget ? config.delivery?.targets?.[deliveryTarget] : undefined;

package/dist/download/handlers/IllustrationTargetHandler.d.ts

@@ -68,6 +68,14 @@ export declare class IllustrationTargetHandler {
     private fetchIllustrations;
     private fetchTopicIllustrations;
     private handleTopicWithLookback;
+    /**
+     * Phase 5 fallback: claim oldest pending candidate(s) from the durable
+     * 待发池 and try to publish them exactly like a normal day's pipeline run.
+     * Returns true when at least one work reached a delivery/stored outcome.
+     */
+    private tryInventoryFallback;
+    /** Mark inventory rows whose work reached a delivery/stored outcome. */
+    private markInventorySubmittedFromOutcomes;
     private resolveTopicDay;
     private shiftDay;
     private fetchRankingIllustrations;

package/dist/download/handlers/IllustrationTargetHandler.js

@@ -12,6 +12,7 @@ const observability_1 = require("../../observability");
 const context_1 = require("../../observability/context");
 const DownloadPlanner_1 = require("../plan/DownloadPlanner");
 const deliveryContext_1 = require("./deliveryContext");
+const inventory_1 = require("../inventory");
 class IllustrationTargetHandler {
     client;
     database;
@@ -233,6 +234,9 @@ class IllustrationTargetHandler {
         const pipeline = this.topicPipelineFactory();
         const { works, selection } = await pipeline.selectWorks(target, 'illustration', day, selectionLimit, target.topicDiscovery ?? {}, target.candidateCollection ?? {});
         logger_1.logger.info(`Topic "${topic}" illustration: tags=${selection.resolvedTagCount} raw=${selection.rawCount} deduped=${selection.dedupedCount} aiExcluded=${selection.aiExcludedCount} accepted=${selection.acceptedCount} candidates=${works.length} target=${limit}`);
+        // Phase 5: harvest the accepted-but-not-yet-delivered works into the
+        // durable 待发池 (idempotent; only when the target opts in).
+        (0, inventory_1.recordInventoryCandidates)(this.database, target, topic, day, works, 'illustration');
         // Candidate Supply Observability: fold this lookback day's upstream funnel
         // into the target's accumulated Candidate Report.
         const report = (0, TargetOutcome_1.emptyCandidateSupplyReport)();
@@ -270,6 +274,7 @@ class IllustrationTargetHandler {
             this.scan = (0, TargetOutcome_1.mergeScanSummaries)(this.scan, result.scan);
             if (result.downloaded > 0) {
                 this.handleDownloadResult(result, target, 'topic', illusts.length);
+                this.markInventorySubmittedFromOutcomes(target, (0, inventory_1.inventoryTopic)(target), 'illustration');
                 return;
             }
             if (this.scan && this.scan.outages.length > 0) {
@@ -278,6 +283,16 @@ class IllustrationTargetHandler {
                 return;
             }
         }
+        // Phase 5: when the fresh + lookback scan produced nothing, and the target
+        // opted into CandidateInventory, publish oldest pending reserve candidates.
+        const topic = (0, inventory_1.inventoryTopic)(target);
+        if (await this.tryInventoryFallback(target, topic, 'illustration')) {
+            return;
+        }
+        // Report how much reserve remains so the empty result is not a dead end.
+        if (this.supplyRep) {
+            this.supplyRep = (0, inventory_1.attachInventoryReport)(this.database, target, topic, this.supplyRep);
+        }
         const scan = this.scan;
         // An explicit no-eligible-candidate verdict needs something to have been
         // considered. When the scan is empty (nothing surfaced at all) the richer
@@ -297,6 +312,65 @@ class IllustrationTargetHandler {
             ...(scan ? { scan } : {}),
         });
     }
+    /**
+     * Phase 5 fallback: claim oldest pending candidate(s) from the durable
+     * 待发池 and try to publish them exactly like a normal day's pipeline run.
+     * Returns true when at least one work reached a delivery/stored outcome.
+     */
+    async tryInventoryFallback(target, topic, workType) {
+        const policy = (0, inventory_1.inventoryPolicy)(target);
+        if (!policy.enabled || policy.fallback === false)
+            return false;
+        const targetId = (0, inventory_1.inventoryTargetId)(target);
+        const repo = this.database.candidateInventory;
+        while (true) {
+            const row = repo.claimNext({ topic, targetId, reserveSize: policy.reserveSize, date: (0, pixiv_date_utils_1.getTodayDate)() });
+            if (!row)
+                break;
+            const id = Number(row.pixivId);
+            if (!Number.isFinite(id)) {
+                repo.markFiltered(row.pixivId, row.workType, topic, targetId);
+                continue;
+            }
+            let detail;
+            try {
+                detail = await this.client.getIllustration(id);
+            }
+            catch (error) {
+                this.logError(error, `Inventory candidate illustration ${id} could not be fetched`);
+                repo.markSelectedBackToPending(row.pixivId, row.workType, topic, targetId);
+                continue;
+            }
+            const attemptTarget = { ...target };
+            const result = await this.pipeline.run([detail], attemptTarget, 'illustration', (illust, tag) => this.downloadAndDeliver(illust, tag, attemptTarget));
+            this.scan = (0, TargetOutcome_1.mergeScanSummaries)(this.scan, result.scan);
+            if (result.downloaded > 0) {
+                this.handleDownloadResult(result, attemptTarget, 'topic', 1);
+                (0, inventory_1.markInventoryAttempt)(this.database, target, topic, row.pixivId, 'illustration', 'submitted');
+                return true;
+            }
+            if (this.scan && this.scan.outages.length > 0) {
+                // A dead token / dead network is not "no candidate": retry the same
+                // row on the next run instead of discarding it.
+                (0, inventory_1.markInventoryAttempt)(this.database, target, topic, row.pixivId, 'illustration', 'pending');
+                return false;
+            }
+            // The claimed work is no longer usable (deleted/private/duplicate): drop
+            // it permanently and try the next pending row.
+            (0, inventory_1.markInventoryAttempt)(this.database, target, topic, row.pixivId, 'illustration', 'filtered');
+        }
+        return false;
+    }
+    /** Mark inventory rows whose work reached a delivery/stored outcome. */
+    markInventorySubmittedFromOutcomes(target, topic, workType) {
+        if (!(0, inventory_1.inventoryPolicy)(target).enabled)
+            return;
+        for (const outcome of this.outcomes) {
+            if (outcome.kind === 'delivery_pending' || outcome.kind === 'submitted' || outcome.kind === 'stored') {
+                (0, inventory_1.markInventoryAttempt)(this.database, target, topic, outcome.workId, workType, 'submitted');
+            }
+        }
+    }
     resolveTopicDay(target) {
         return target.date === 'TODAY'
             ? (0, pixiv_date_utils_1.getTodayDate)()

package/dist/download/handlers/NovelTargetHandler.d.ts

@@ -67,6 +67,13 @@ export declare class NovelTargetHandler {
     private fetchNovels;
     private fetchTopicNovels;
     private handleTopicWithLookback;
+    /**
+     * Phase 5 fallback: claim pending novel candidates and publish them into the
+     * existing aggregate day-scan (same idempotent pipeline as a normal day).
+     */
+    private tryInventoryFallback;
+    /** Mark inventory rows whose work reached a delivery/stored outcome. */
+    private markInventorySubmittedFromOutcomes;
     private resolveTopicDay;
     private shiftDay;
     private fetchRankingNovels;

package/dist/download/handlers/NovelTargetHandler.js

@@ -12,6 +12,7 @@ const observability_1 = require("../../observability");
 const context_1 = require("../../observability/context");
 const DownloadPlanner_1 = require("../plan/DownloadPlanner");
 const deliveryContext_1 = require("./deliveryContext");
+const inventory_1 = require("../inventory");
 const TelePressRichNovel_1 = require("../../delivery/TelePressRichNovel");
 class NovelTargetHandler {
     client;
@@ -232,6 +233,7 @@ class NovelTargetHandler {
         const pipeline = this.topicPipelineFactory();
         const { works, selection } = await pipeline.selectWorks(target, 'novel', day, selectionLimit, target.topicDiscovery ?? {}, target.candidateCollection ?? {});
         logger_1.logger.info(`Topic "${topic}" novel: tags=${selection.resolvedTagCount} raw=${selection.rawCount} deduped=${selection.dedupedCount} accepted=${selection.acceptedCount} candidates=${works.length} target=${limit}`);
+        (0, inventory_1.recordInventoryCandidates)(this.database, target, topic, day, works, 'novel');
         const report = (0, TargetOutcome_1.emptyCandidateSupplyReport)();
         report.fetched = selection.rawCount;
         report.selected = selection.acceptedCount;
@@ -281,15 +283,84 @@ class NovelTargetHandler {
             aggregate.skipped += result.skipped;
             aggregate.alreadyDownloaded += result.alreadyDownloaded;
             aggregate.filteredOut += result.filteredOut;
+            if (result.downloaded > 0) {
+                this.markInventorySubmittedFromOutcomes(target, (0, inventory_1.inventoryTopic)(target), 'novel');
+            }
             if (aggregate.scan.outages.length > 0) {
                 // A dead token / dead database / dead network is not "no matching
                 // novel": stop looking back and let the job fail/retry.
                 break;
             }
         }
+        const topic = (0, inventory_1.inventoryTopic)(target);
+        await this.tryInventoryFallback(target, topic, aggregate);
+        if (this.supplyRep) {
+            this.supplyRep = (0, inventory_1.attachInventoryReport)(this.database, target, topic, this.supplyRep);
+        }
         this.scan = aggregate.scan;
         await this.handleDownloadResult(aggregate, target, 'topic', totalFound, checkedDays);
     }
+    /**
+     * Phase 5 fallback: claim pending novel candidates and publish them into the
+     * existing aggregate day-scan (same idempotent pipeline as a normal day).
+     */
+    async tryInventoryFallback(target, topic, aggregate) {
+        const policy = (0, inventory_1.inventoryPolicy)(target);
+        if (!policy.enabled || policy.fallback === false)
+            return;
+        // Only a fully-empty fresh/lookback window may draw from the reserve; a
+        // partial day stays on fresh supply rather than padding beyond the limit.
+        if (aggregate.downloaded > 0)
+            return;
+        const targetId = (0, inventory_1.inventoryTargetId)(target);
+        const repo = this.database.candidateInventory;
+        while (aggregate.downloaded < (target.limit || 1)) {
+            const row = repo.claimNext({ topic, targetId, reserveSize: policy.reserveSize, date: (0, pixiv_date_utils_1.getTodayDate)() });
+            if (!row)
+                break;
+            const id = Number(row.pixivId);
+            if (!Number.isFinite(id)) {
+                repo.markFiltered(row.pixivId, row.workType, topic, targetId);
+                continue;
+            }
+            let detail;
+            try {
+                detail = await this.client.getNovelDetail(id);
+            }
+            catch (error) {
+                this.logError(error, `Inventory candidate novel ${id} could not be fetched`);
+                repo.markSelectedBackToPending(row.pixivId, row.workType, topic, targetId);
+                continue;
+            }
+            const attemptTarget = {
+                ...target,
+                limit: (target.limit || 1) - aggregate.downloaded,
+            };
+            const result = await this.pipeline.run([detail], attemptTarget, 'novel', (novel, tag) => this.downloadAndDeliver(novel, tag, attemptTarget));
+            aggregate.scan = (0, TargetOutcome_1.mergeScanSummaries)(aggregate.scan, result.scan);
+            aggregate.downloaded += result.downloaded;
+            aggregate.skipped += result.skipped;
+            aggregate.alreadyDownloaded += result.alreadyDownloaded;
+            aggregate.filteredOut += result.filteredOut;
+            if (result.downloaded > 0) {
+                (0, inventory_1.markInventoryAttempt)(this.database, target, topic, row.pixivId, 'novel', 'submitted');
+                continue;
+            }
+            if (aggregate.scan.outages.length > 0)
+                return;
+            (0, inventory_1.markInventoryAttempt)(this.database, target, topic, row.pixivId, 'novel', 'filtered');
+        }
+    }
+    /** Mark inventory rows whose work reached a delivery/stored outcome. */
+    markInventorySubmittedFromOutcomes(target, topic, workType) {
+        if (!(0, inventory_1.inventoryPolicy)(target).enabled)
+            return;
+        for (const outcome of this.outcomes) {
+            if (outcome.kind === 'delivery_pending' || outcome.kind === 'submitted' || outcome.kind === 'stored') {
+                (0, inventory_1.markInventoryAttempt)(this.database, target, topic, outcome.workId, workType, 'submitted');
+            }
+        }
+    }
     resolveTopicDay(target) {
         return target.date === 'TODAY'
             ? (0, pixiv_date_utils_1.getTodayDate)()

package/dist/download/inventory.d.ts

@@ -0,0 +1,29 @@
+import type { TargetConfig } from '../config';
+import type { IDatabase } from '../interfaces/IDatabase';
+import type { CandidateSupplyReport } from '../scheduler/TargetOutcome';
+/** Defaults and bounds for the optional Phase 5 inventory. */
+export interface InventoryPolicy {
+    enabled: boolean;
+    maxAgeDays: number;
+    reserveSize: number;
+    fallback: boolean;
+}
+export declare function inventoryPolicy(target: TargetConfig): InventoryPolicy;
+export declare function inventoryTopic(target: TargetConfig): string;
+export declare function inventoryTargetId(target: TargetConfig): string;
+/**
+ * Phase 5: after a topic scan yields eligible works that were NOT delivered by
+ * this run's lookback loop, upsert them as idle pending inventory. Works that
+ * are already recorded as downloaded/delivered are skipped by the caller
+ * upstream (selectWorks already removed download-history rows); this method is
+ * deliberately idempotent.
+ */
+export declare function recordInventoryCandidates(database: IDatabase, target: TargetConfig, topic: string, date: string, works: Array<{
+    id: number;
+    type?: string;
+}>, workType: 'illustration' | 'novel'): void;
+/** Enrich a candidate report with the durable pending-count snapshot. */
+export declare function attachInventoryReport(database: IDatabase, target: TargetConfig, topic: string, report: CandidateSupplyReport): CandidateSupplyReport;
+/** Marks a claimed inventory row after a delivery attempt. */
+export declare function markInventoryAttempt(database: IDatabase, target: TargetConfig, topic: string, workId: string, workType: 'illustration' | 'novel', outcome: 'submitted' | 'filtered' | 'pending'): void;
+//# sourceMappingURL=inventory.d.ts.map

package/dist/download/inventory.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inventoryPolicy = inventoryPolicy;
+exports.inventoryTopic = inventoryTopic;
+exports.inventoryTargetId = inventoryTargetId;
+exports.recordInventoryCandidates = recordInventoryCandidates;
+exports.attachInventoryReport = attachInventoryReport;
+exports.markInventoryAttempt = markInventoryAttempt;
+function inventoryPolicy(target) {
+    const cfg = target.topicProfile?.inventory;
+    return {
+        enabled: cfg?.enabled === true,
+        maxAgeDays: cfg?.maxAgeDays ?? 30,
+        reserveSize: Math.min(Math.max(cfg?.reserveSize ?? 20, 1), 100),
+        fallback: cfg?.fallback ?? true,
+    };
+}
+function inventoryTopic(target) {
+    return (target.topicProfile?.primary?.[0] ?? target.topic ?? '').trim();
+}
+function inventoryTargetId(target) {
+    return target.id ?? inventoryTopic(target);
+}
+/**
+ * Phase 5: after a topic scan yields eligible works that were NOT delivered by
+ * this run's lookback loop, upsert them as idle pending inventory. Works that
+ * are already recorded as downloaded/delivered are skipped by the caller
+ * upstream (selectWorks already removed download-history rows); this method is
+ * deliberately idempotent.
+ */
+function recordInventoryCandidates(database, target, topic, date, works, workType) {
+    const policy = inventoryPolicy(target);
+    if (!policy.enabled)
+        return;
+    const targetId = inventoryTargetId(target);
+    for (const work of works) {
+        const id = String(work?.id);
+        if (!id)
+            continue;
+        database.candidateInventory.upsert({
+            pixivId: id,
+            workType,
+            topic,
+            targetId,
+            snapshot: work,
+            date,
+            maxAgeDays: policy.maxAgeDays,
+        });
+    }
+}
+/** Enrich a candidate report with the durable pending-count snapshot. */
+function attachInventoryReport(database, target, topic, report) {
+    const policy = inventoryPolicy(target);
+    if (!policy.enabled)
+        return report;
+    const summary = database.candidateInventory.pendingSummary(topic, inventoryTargetId(target));
+    return {
+        ...report,
+        inventory: {
+            pendingCount: summary.count,
+            reserveSize: policy.reserveSize,
+            maxAgeDays: policy.maxAgeDays,
+            oldestSeenDate: summary.oldestSeenDate,
+        },
+    };
+}
+/** Marks a claimed inventory row after a delivery attempt. */
+function markInventoryAttempt(database, target, topic, workId, workType, outcome) {
+    if (!inventoryPolicy(target).enabled)
+        return;
+    const targetId = inventoryTargetId(target);
+    const repo = database.candidateInventory;
+    if (outcome === 'submitted')
+        repo.markSubmitted(workId, workType, topic, targetId);
+    else if (outcome === 'filtered')
+        repo.markFiltered(workId, workType, topic, targetId);
+    else
+        repo.markSelectedBackToPending(workId, workType, topic, targetId);
+}
+//# sourceMappingURL=inventory.js.map

package/dist/interfaces/IDatabase.d.ts

@@ -1,4 +1,5 @@
 import { AccessTokenStore, DownloadRecordInput, ExecutionStatus, SchedulerExecutionRecord } from '../storage/Database';
+import { CandidateInventoryRepository } from '../storage/repositories/CandidateInventoryRepository';
 /**
  * Interface for database operations
  * Provides abstraction for data persistence
@@ -123,5 +124,7 @@ export interface IDatabase {
         };
         countSince(botId: string | null, hours: number): number;
     };
+    /** Phase 5 durable CandidateInventory (待发池). */
+    readonly candidateInventory: CandidateInventoryRepository;
 }
 //# sourceMappingURL=IDatabase.d.ts.map

package/dist/package.json

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

package/dist/scheduler/TargetOutcome.d.ts

@@ -109,6 +109,17 @@ export interface CandidateSupplyReason {
     code: string;
     count: number;
 }
+/** Phase 5: durable 待发池 snapshot for sparse topics (only when enabled). */
+export interface CandidateInventoryReport {
+    /** Rows still usable for fallback at report time. */
+    pendingCount: number;
+    /** Target's configured max retained rows. */
+    reserveSize: number;
+    /** Max age in days before a pending candidate expires. */
+    maxAgeDays: number;
+    /** Earliest still-pending first-seen date (YYYY-MM-DD), null when empty. */
+    oldestSeenDate: string | null;
+}
 /** Candidate-supply observability snapshot (Phase 1 Candidate Report). */
 export interface CandidateSupplyReport {
     /** Total works surfaced by the topic search before any filtering. */
@@ -119,6 +130,8 @@ export interface CandidateSupplyReport {
     rejected: number;
     /** Why candidates were rejected, by reason code (extensible). */
     reasons: CandidateSupplyReason[];
+    /** Phase 5: durable 待发池 reserve (optional, present only when enabled). */
+    inventory?: CandidateInventoryReport;
 }
 /**
  * A freshly-harvested upstream funnel with no candidates selected yet.

package/dist/scheduler/TargetOutcome.js

@@ -20,7 +20,7 @@ exports.terminalReasonFor = terminalReasonFor;
  * A freshly-harvested upstream funnel with no candidates selected yet.
  */
 function emptyCandidateSupplyReport() {
-    return { fetched: 0, selected: 0, rejected: 0, reasons: [] };
+    return { fetched: 0, selected: 0, rejected: 0, reasons: [], inventory: undefined };
 }
 /**
  * Fold two supply snapshots of the SAME logical target together, so a
@@ -43,6 +43,7 @@ function mergeCandidateSupplyReports(first, second) {
         selected: first.selected + second.selected,
         rejected: Math.max(0, first.fetched + second.fetched - (first.selected + second.selected)),
         reasons,
+        inventory: second.inventory ?? first.inventory,
     };
 }
 /**
@@ -68,6 +69,7 @@ function withScanSkips(report, scan) {
         selected,
         rejected: Math.max(0, base.fetched - selected),
         reasons,
+        inventory: base.inventory,
     };
 }
 /**

package/dist/storage/Database.d.ts

@@ -5,6 +5,7 @@ import { OutboxRepository } from './repositories/OutboxRepository';
 import { MetadataRepository } from './repositories/MetadataRepository';
 import { SQLiteRateLimitStateStore } from './repositories/RateLimitStateRepository';
 import { SystemErrorRepository } from './repositories/SystemErrorRepository';
+import { CandidateInventoryRepository } from './repositories/CandidateInventoryRepository';
 export interface AccessTokenStore {
     accessToken: string;
     expiresAt: number;
@@ -48,6 +49,7 @@ export declare class Database implements IDatabase {
     private metadataRepo;
     private rateLimitStateStore;
     private systemErrorRepo;
+    private candidateInventoryRepo;
     constructor(databasePath: string);
     migrate(): void;
     /** Absolute path of the SQLite file (used to locate sibling cache dirs). */
@@ -64,6 +66,8 @@ export declare class Database implements IDatabase {
     get rateLimitState(): SQLiteRateLimitStateStore;
     /** Durable system-error ledger (observability; never throws). */
     get systemErrors(): SystemErrorRepository;
+    /** Phase 5 CandidateInventory (待发池) for sparse topics. */
+    get candidateInventory(): CandidateInventoryRepository;
     /** 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

@@ -18,6 +18,7 @@ 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 CandidateInventoryRepository_1 = require("./repositories/CandidateInventoryRepository");
 const NodeSqliteDriver_1 = require("./drivers/NodeSqliteDriver");
 class Database {
     databasePath;
@@ -35,6 +36,7 @@ class Database {
     metadataRepo;
     rateLimitStateStore;
     systemErrorRepo;
+    candidateInventoryRepo;
     constructor(databasePath) {
         this.databasePath = databasePath;
         try {
@@ -63,6 +65,7 @@ class Database {
             this.metadataRepo = new MetadataRepository_1.MetadataRepository(this.db);
             this.rateLimitStateStore = new RateLimitStateRepository_1.SQLiteRateLimitStateStore(this.db);
             this.systemErrorRepo = new SystemErrorRepository_1.SystemErrorRepository(this.db);
+            this.candidateInventoryRepo = new CandidateInventoryRepository_1.CandidateInventoryRepository(this.db);
         }
         catch (error) {
             throw new errors_1.DatabaseError(`Failed to initialize database at ${this.databasePath}`, error instanceof Error ? error : undefined);
@@ -102,6 +105,10 @@ class Database {
     get systemErrors() {
         return this.systemErrorRepo;
     }
+    /** Phase 5 CandidateInventory (待发池) for sparse topics. */
+    get candidateInventory() {
+        return this.candidateInventoryRepo;
+    }
     /** Raw transactional boundary for atomic multi-table intents. */
     transaction(fn) {
         return this.db.transaction(fn)();