pixivflow 2.29.0 → 2.30.0

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.30.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)();

package/dist/storage/DatabaseMigration.js

@@ -222,6 +222,25 @@ class DatabaseMigration {
             scope TEXT PRIMARY KEY,
             state TEXT NOT NULL,
             updated_at INTEGER NOT NULL
+          )`,
+                // Phase 5 CandidateInventory: durable 待发池 for sparse topics. Same
+                // database and transaction world as the Slot Ledger; never a second
+                // state authority. Only populated when target.topicProfile.inventory.enabled.
+                `CREATE TABLE IF NOT EXISTS candidate_inventory (
+            pixiv_id TEXT NOT NULL,
+            work_type TEXT NOT NULL,
+            topic TEXT NOT NULL,
+            target_id TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending',
+            snapshot_json TEXT NOT NULL,
+            first_seen_date TEXT NOT NULL,
+            last_seen_date TEXT NOT NULL,
+            seen_count INTEGER NOT NULL DEFAULT 1,
+            attempt_count INTEGER NOT NULL DEFAULT 0,
+            expires_at TEXT NOT NULL,
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (pixiv_id, work_type, topic, target_id)
           )`,
                 // Durable error event ledger for observability (structured error
                 // taxonomy; populated by download/system handlers and shown in the
@@ -244,6 +263,7 @@ class DatabaseMigration {
             resolved_at DATETIME
           )`,
                 `CREATE INDEX IF NOT EXISTS idx_system_errors_bot_created ON system_errors(bot_id, created_at)`,
+                `CREATE INDEX IF NOT EXISTS idx_cinventory_pending ON candidate_inventory(status, first_seen_date, expires_at)`,
             ];
             // Phase 1: create tables (idempotent). Must run before any PRAGMA-based
             // column check, otherwise a fresh DB would report the table as missing and

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

@@ -0,0 +1,51 @@
+import { BaseRepository } from './BaseRepository';
+export type CandidateInventoryStatus = 'pending' | 'selected' | 'submitted' | 'filtered' | 'expired';
+export interface CandidateInventoryRow {
+    pixivId: string;
+    workType: 'illustration' | 'novel';
+    topic: string;
+    targetId: string;
+    status: CandidateInventoryStatus;
+    snapshotJson: string;
+    firstSeenDate: string;
+    lastSeenDate: string;
+    seenCount: number;
+    attemptCount: number;
+    expiresAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CandidateInventorySnapshot {
+    pixivId: string;
+    workType: 'illustration' | 'novel';
+    topic: string;
+    targetId: string;
+    snapshot: unknown;
+    date: string;
+    maxAgeDays: number;
+}
+/** Phase 5 durable 待发池 — same SQLite database as the Slot Ledger. */
+export declare class CandidateInventoryRepository extends BaseRepository {
+    upsert(input: CandidateInventorySnapshot): void;
+    /** Marks a claimed candidate and returns its snapshot for the pipeline. */
+    claimNext(input: {
+        topic: string;
+        targetId: string;
+        reserveSize: number;
+        date: string;
+    }): CandidateInventoryRow | null;
+    markSubmitted(pixivId: string, workType: string, topic: string, targetId: string): void;
+    markFiltered(pixivId: string, workType: string, topic: string, targetId: string): void;
+    markSelectedBackToPending(pixivId: string, workType: string, topic: string, targetId: string): void;
+    countPending(topic: string, targetId: string): number;
+    pendingSummary(topic: string, targetId: string): {
+        count: number;
+        oldestSeenDate: string | null;
+    };
+    /** Sweep rows past maxAgeDays; idempotent per scheduled scan. */
+    evictExpired(topic: string, targetId: string): number;
+    private toRow;
+    private todayUtc;
+    private addDaysUtc;
+}
+//# sourceMappingURL=CandidateInventoryRepository.d.ts.map

package/dist/storage/repositories/CandidateInventoryRepository.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CandidateInventoryRepository = void 0;
+const BaseRepository_1 = require("./BaseRepository");
+/** Phase 5 durable 待发池 — same SQLite database as the Slot Ledger. */
+class CandidateInventoryRepository extends BaseRepository_1.BaseRepository {
+    upsert(input) {
+        const expiresAt = this.addDaysUtc(input.date, input.maxAgeDays);
+        this.db
+            .prepare(`INSERT INTO candidate_inventory
+           (pixiv_id, work_type, topic, target_id, status, snapshot_json,
+            first_seen_date, last_seen_date, seen_count, attempt_count, expires_at)
+         VALUES
+           (@pixivId, @workType, @topic, @targetId, 'pending', @snapshot,
+            @date, @date, 1, 0, @expiresAt)
+         ON CONFLICT(pixiv_id, work_type, topic, target_id) DO UPDATE SET
+           snapshot_json = excluded.snapshot_json,
+           last_seen_date = excluded.last_seen_date,
+           seen_count = candidate_inventory.seen_count + 1,
+           status = CASE
+             WHEN candidate_inventory.status IN ('selected','submitted','filtered','expired')
+                  THEN candidate_inventory.status
+             ELSE 'pending'
+           END,
+           expires_at = excluded.expires_at,
+           updated_at = CURRENT_TIMESTAMP`)
+            .run({
+            pixivId: input.pixivId,
+            workType: input.workType,
+            topic: input.topic,
+            targetId: input.targetId,
+            snapshot: JSON.stringify(input.snapshot),
+            date: input.date,
+            expiresAt,
+        });
+    }
+    /** Marks a claimed candidate and returns its snapshot for the pipeline. */
+    claimNext(input) {
+        const rows = this.db
+            .prepare(`SELECT * FROM candidate_inventory
+         WHERE topic = ? AND target_id = ?
+           AND status = 'pending'
+           AND expires_at >= ?
+         ORDER BY first_seen_date ASC, seen_count ASC
+         LIMIT ?`)
+            .all(input.topic, input.targetId, this.addDaysUtc(input.date, 0), input.reserveSize);
+        for (const row of rows) {
+            const updated = this.db
+                .prepare(`UPDATE candidate_inventory
+           SET status = 'selected', attempt_count = attempt_count + 1, updated_at = CURRENT_TIMESTAMP
+           WHERE pixiv_id = ? AND work_type = ? AND topic = ? AND target_id = ? AND status = 'pending'`)
+                .run(row.pixiv_id, row.work_type, row.topic, row.target_id);
+            if (updated.changes > 0)
+                return this.toRow(row);
+        }
+        return null;
+    }
+    markSubmitted(pixivId, workType, topic, targetId) {
+        this.db
+            .prepare(`UPDATE candidate_inventory
+         SET status = 'submitted', updated_at = CURRENT_TIMESTAMP
+         WHERE pixiv_id = ? AND work_type = ? AND topic = ? AND target_id = ?`)
+            .run(pixivId, workType, topic, targetId);
+    }
+    markFiltered(pixivId, workType, topic, targetId) {
+        this.db
+            .prepare(`UPDATE candidate_inventory
+         SET status = 'filtered', updated_at = CURRENT_TIMESTAMP
+         WHERE pixiv_id = ? AND work_type = ? AND topic = ? AND target_id = ?`)
+            .run(pixivId, workType, topic, targetId);
+    }
+    markSelectedBackToPending(pixivId, workType, topic, targetId) {
+        this.db
+            .prepare(`UPDATE candidate_inventory
+         SET status = 'pending', updated_at = CURRENT_TIMESTAMP
+         WHERE pixiv_id = ? AND work_type = ? AND topic = ? AND target_id = ? AND status = 'selected'`)
+            .run(pixivId, workType, topic, targetId);
+    }
+    countPending(topic, targetId) {
+        const rows = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM candidate_inventory WHERE topic = ? AND target_id = ? AND status = 'pending' AND expires_at >= ?`)
+            .get(topic, targetId, this.todayUtc());
+        return Number(rows?.n ?? 0);
+    }
+    pendingSummary(topic, targetId) {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n, MIN(first_seen_date) AS oldest
+         FROM candidate_inventory
+         WHERE topic = ? AND target_id = ? AND status = 'pending' AND expires_at >= ?`)
+            .get(topic, targetId, this.todayUtc());
+        return { count: Number(row?.n ?? 0), oldestSeenDate: row?.oldest ?? null };
+    }
+    /** Sweep rows past maxAgeDays; idempotent per scheduled scan. */
+    evictExpired(topic, targetId) {
+        const info = this.db
+            .prepare(`UPDATE candidate_inventory
+         SET status = 'expired', updated_at = CURRENT_TIMESTAMP
+         WHERE topic = ? AND target_id = ? AND status IN ('pending','selected') AND expires_at < ?`)
+            .run(topic, targetId, this.todayUtc());
+        return info.changes;
+    }
+    toRow(row) {
+        return {
+            pixivId: String(row.pixiv_id),
+            workType: row.work_type,
+            topic: row.topic,
+            targetId: row.target_id,
+            status: row.status,
+            snapshotJson: row.snapshot_json,
+            firstSeenDate: row.first_seen_date,
+            lastSeenDate: row.last_seen_date,
+            seenCount: Number(row.seen_count ?? 1),
+            attemptCount: Number(row.attempt_count ?? 0),
+            expiresAt: row.expires_at,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+    todayUtc() {
+        return new Date().toISOString().slice(0, 10);
+    }
+    addDaysUtc(date, days) {
+        const d = new Date(`${date}T00:00:00.000Z`);
+        d.setUTCDate(d.getUTCDate() + days);
+        return d.toISOString().slice(0, 10);
+    }
+}
+exports.CandidateInventoryRepository = CandidateInventoryRepository;
+//# sourceMappingURL=CandidateInventoryRepository.js.map

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUILD = void 0;
 // GENERATED by scripts/write-version.js — do not edit manually.
-exports.BUILD = { version: '2.29.0', commit: '13e234a69cd2' };
+exports.BUILD = { version: '2.30.0', commit: '153116bd9b08' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow-webui-backend",
-  "version": "2.29.0",
+  "version": "2.30.0",
   "description": "PixivFlow WebUI Backend - CommonJS module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixivflow",
-  "version": "2.29.0",
+  "version": "2.30.0",
   "description": "🎨 Pixiv 下载、筛选与自动收集工具 - 批量下载插画和小说、按标签/热度/日期筛选、定时任务与可靠 HTTP 交付 | Pixiv downloader and automation toolkit with filtering, scheduling and reliable HTTP delivery",
   "repository": {
     "type": "git",