pixivflow 2.28.1 → 2.30.0

package/dist/commands/scheduler-runtime.js

@@ -709,6 +709,7 @@ async function createSchedulerRuntime(configPathArg) {
                             error: c.error ?? null,
                             terminal_reason_code: c.terminalReasonCode ?? null,
                             reason: c.terminalReasonMessage ?? null,
+                            candidateReport: c.candidateReport ?? null,
                         };
                     }));
                 }

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/delivery/DeliveryService.d.ts

@@ -50,6 +50,7 @@ export interface ScheduleOutcomePayload {
         workType: string;
         status: string;
         workId?: string | null;
+        candidateReport?: Record<string, unknown> | null;
     }>;
 }
 export declare class DeliveryService {

package/dist/delivery/HttpMultipartDelivery.js

@@ -176,6 +176,7 @@ class HttpMultipartDelivery {
                         stage: t.stage ?? null,
                         retryable: t.retryable ?? null,
                         operator_hint: t.operator_hint ?? null,
+                        candidate_report: t.candidate_report ?? null,
                     })),
                 }
                 : { text: request.text, idempotency_key: request.idempotencyKey };

package/dist/delivery/types.d.ts

@@ -146,6 +146,8 @@ export interface DeliveryNotificationRequest {
             /** Whether a later/manual attempt may succeed; terminal does not mean auto-retry pending. */
             retryable?: boolean | null;
             operator_hint?: string | null;
+            /** Phase 1 Candidate Supply Report ({fetched, selected, rejected, reasons}). */
+            candidate_report?: Record<string, unknown> | null;
         }>;
     };
 }

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

@@ -25,6 +25,11 @@ export declare class IllustrationTargetHandler {
      * explicit verdict instead of an ambiguous "completed".
      */
     private scan;
+    /**
+     * Upstream topic-supply funnel accumulated across a lookback scan (Phase 1
+     * Candidate Report: fetched/selected/rejected + reasons).
+     */
+    private supplyRep;
     /**
      * Global candidate-scan bound (`download.candidateScanLimit`), supplied by
      * DownloadManager. This is what lets the FETCH stage ask for more than one
@@ -63,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;
@@ -29,6 +30,11 @@ class IllustrationTargetHandler {
      * explicit verdict instead of an ambiguous "completed".
      */
     scan = null;
+    /**
+     * Upstream topic-supply funnel accumulated across a lookback scan (Phase 1
+     * Candidate Report: fetched/selected/rejected + reasons).
+     */
+    supplyRep = null;
     /**
      * Global candidate-scan bound (`download.candidateScanLimit`), supplied by
      * DownloadManager. This is what lets the FETCH stage ask for more than one
@@ -68,6 +74,7 @@ class IllustrationTargetHandler {
     async handle(target, execution) {
         this.outcomes = [];
         this.scan = null;
+        this.supplyRep = null;
         this.execution = execution && (0, WorkIdentity_1.isSingleWorkCell)(target) ? execution : null;
         // A cell that already owns a work is in RECOVERY, not in a new selection.
         // Crash/shutdown recovery is not an intentional second run: running the
@@ -113,6 +120,9 @@ class IllustrationTargetHandler {
      * scheduled slot report success after submitting nothing.
      */
     summarize(target) {
+        if (this.scan && this.supplyRep) {
+            this.scan = { ...this.scan, supply: (0, TargetOutcome_1.withScanSkips)(this.supplyRep, this.scan) };
+        }
         const scan = this.scan ?? undefined;
         const submitted = this.outcomes.find((o) => o.kind === 'submitted');
         if (submitted)
@@ -198,7 +208,8 @@ class IllustrationTargetHandler {
     }
     async fetchIllustrations(target, mode) {
         if (mode === 'topic') {
-            return this.fetchTopicIllustrations(target);
+            const { works } = await this.fetchTopicIllustrations(target);
+            return works;
         }
         if (mode === 'ranking') {
             return this.fetchRankingIllustrations(target);
@@ -223,7 +234,22 @@ 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}`);
-        return works;
+        // 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)();
+        report.fetched = selection.rawCount;
+        report.selected = selection.acceptedCount;
+        report.rejected = Math.max(0, selection.rawCount - selection.acceptedCount);
+        report.reasons = [
+            { code: 'duplicate', count: selection.duplicateRemovedCount },
+            { code: 'ai_filtered', count: selection.aiExcludedCount },
+            { code: 'metadata_filtered', count: Math.max(0, selection.dedupedCount - selection.acceptedCount) },
+        ].filter((r) => r.count > 0);
+        this.supplyRep = (0, TargetOutcome_1.mergeCandidateSupplyReports)(this.supplyRep ?? undefined, report);
+        return { works, selection };
     }
     async handleTopicWithLookback(target, displayTag) {
         const requested = target.limit || 1;
@@ -241,13 +267,14 @@ class IllustrationTargetHandler {
                     fallbackOffset: offset,
                 });
             }
-            const illusts = await this.fetchTopicIllustrations(attemptTarget);
+            const { works: illusts } = await this.fetchTopicIllustrations(attemptTarget);
             const result = await this.pipeline.run(illusts, attemptTarget, 'illustration', (illust, tag) => this.downloadAndDeliver(illust, tag, attemptTarget));
             // The lookback loop is one bounded scan: accumulate every day's
             // skips/outages so the final verdict covers all candidates attempted.
             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) {
@@ -256,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
@@ -275,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

@@ -24,6 +24,10 @@ export declare class NovelTargetHandler {
      * explicit verdict instead of an ambiguous "completed".
      */
     private scan;
+    /**
+     * Upstream topic-supply funnel accumulated across a lookback scan.
+     */
+    private supplyRep;
     /**
      * Global candidate-scan bound (`download.candidateScanLimit`), supplied by
      * DownloadManager. This is what lets the FETCH stage ask for more than one
@@ -63,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;
@@ -29,6 +30,10 @@ class NovelTargetHandler {
      * explicit verdict instead of an ambiguous "completed".
      */
     scan = null;
+    /**
+     * Upstream topic-supply funnel accumulated across a lookback scan.
+     */
+    supplyRep = null;
     /**
      * Global candidate-scan bound (`download.candidateScanLimit`), supplied by
      * DownloadManager. This is what lets the FETCH stage ask for more than one
@@ -68,6 +73,7 @@ class NovelTargetHandler {
     async handle(target, execution) {
         this.outcomes = [];
         this.scan = null;
+        this.supplyRep = null;
         this.execution = execution && (0, WorkIdentity_1.isSingleWorkCell)(target) ? execution : null;
         // A cell that already owns a work is in RECOVERY, not in a new selection.
         // Crash/shutdown recovery is not an intentional second run: running the
@@ -126,6 +132,9 @@ class NovelTargetHandler {
      * single-work RECOVERY path, whose cell identity is fixed.
      */
     summarize() {
+        if (this.scan && this.supplyRep) {
+            this.scan = { ...this.scan, supply: (0, TargetOutcome_1.withScanSkips)(this.supplyRep, this.scan) };
+        }
         const scan = this.scan ?? undefined;
         const submitted = this.outcomes.find((o) => o.kind === 'submitted');
         if (submitted)
@@ -200,7 +209,8 @@ class NovelTargetHandler {
     }
     async fetchNovels(target, mode) {
         if (mode === 'topic') {
-            return this.fetchTopicNovels(target);
+            const { works } = await this.fetchTopicNovels(target);
+            return works;
         }
         if (mode === 'ranking') {
             return this.fetchRankingNovels(target);
@@ -223,7 +233,17 @@ 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}`);
-        return works;
+        (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;
+        report.rejected = Math.max(0, selection.rawCount - selection.acceptedCount);
+        report.reasons = [
+            { code: 'duplicate', count: selection.duplicateRemovedCount },
+            { code: 'metadata_filtered', count: Math.max(0, selection.dedupedCount - selection.acceptedCount) },
+        ].filter((r) => r.count > 0);
+        this.supplyRep = (0, TargetOutcome_1.mergeCandidateSupplyReports)(this.supplyRep ?? undefined, report);
+        return { works, selection };
     }
     async handleTopicWithLookback(target, displayTag) {
         const requested = target.limit || 1;
@@ -253,7 +273,7 @@ class NovelTargetHandler {
                     fallbackOffset: offset,
                 });
             }
-            const novels = await this.fetchTopicNovels(attemptTarget);
+            const { works: novels } = await this.fetchTopicNovels(attemptTarget);
             totalFound += novels.length;
             const result = await this.pipeline.run(novels, attemptTarget, 'novel', (novel, tag) => this.downloadAndDeliver(novel, tag, attemptTarget));
             // The lookback loop is ONE bounded scan: accumulate every day's
@@ -263,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/notification/NotificationPolicy.d.ts

@@ -46,6 +46,7 @@ export declare class NotificationPolicy {
         error: string | null;
         terminal_reason_code?: string | null;
         reason?: string | null;
+        candidateReport?: Record<string, unknown> | null;
     }>): void;
     /**
      * Delivery targets whose HTTP target declares the given outcome URL.

package/dist/notification/NotificationPolicy.js

@@ -145,6 +145,7 @@ class NotificationPolicy {
                         stage: operational?.stage ?? null,
                         retryable: operational?.retryable ?? null,
                         operator_hint: operational?.operatorHint ?? null,
+                        candidate_report: r.candidateReport ?? null,
                     };
                 }),
             });

package/dist/package.json

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