pixivflow 3.4.1 → 3.4.3

package/dist/config/types.d.ts

@@ -945,10 +945,19 @@ export interface StandaloneConfig {
          * classified. 'skip' (default) is safe mode: never ship an unclassifiable
          * cover, and log `coverType=unknown` so a future Pixiv format change is
          * visible instead of silently leaking designs again. 'keep' prefers
-         * availability over certainty. A failed probe always keeps the cover.
+         * availability over certainty.
+         *
+         * `probeFailed` governs the separate case where the cover probe itself
+         * failed (network / auth / rate limit) and the bytes were never seen.
+         * 'skip' (default) is safe mode for the same reason: most novel covers ARE
+         * generated designs, so keeping an unseen cover re-ships what the 640x900
+         * classifier exists to suppress; the cost is one illustration when a real
+         * cover is transiently unreachable. 'keep' restores availability-first.
+         * Either way the `coverType=probe_failed` warning stays visible.
          */
         novelCover?: {
             unknown?: 'skip' | 'keep';
+            probeFailed?: 'skip' | 'keep';
         };
     };
 }

package/dist/config/validation.js

@@ -715,6 +715,11 @@ function validateConfig(config, location, databasePath) {
             config.download.novelCover.unknown !== 'keep') {
             errors.push(`download.novelCover.unknown: Must be "skip" or "keep" (got ${String(config.download.novelCover.unknown)})`);
         }
+        if (config.download.novelCover?.probeFailed !== undefined &&
+            config.download.novelCover.probeFailed !== 'skip' &&
+            config.download.novelCover.probeFailed !== 'keep') {
+            errors.push(`download.novelCover.probeFailed: Must be "skip" or "keep" (got ${String(config.download.novelCover.probeFailed)})`);
+        }
     }
     // The bounded candidate scan is what stops a page full of duplicates from
     // burning a whole scheduled slot, so a non-integer value is reported here.

package/dist/delivery/HttpMultipartDelivery.js

@@ -43,6 +43,7 @@ const node_crypto_1 = require("node:crypto");
 const node_stream_1 = require("node:stream");
 const logger_1 = require("../logger");
 const DeliveryAck_1 = require("./DeliveryAck");
+const refetchProvenance_1 = require("./refetchProvenance");
 const redact_1 = require("../utils/redact");
 /** Render an ISO timestamp to YYYY-MM-DD (create_date is JST). */
 function formatPublishedDate(iso) {
@@ -476,7 +477,10 @@ function buildTemplateVariables(request) {
         // Remote manual replacement ("重抓") request UUID; empty for scheduled runs.
         // Carried through the delivery payload context (extraContext) so the
         // receiving service can correlate the review with its refetch attempt.
-        refetchRequestId: c.refetchRequestId ?? '',
+        // Canonicalized at this last boundary before the wire: the receiver accepts
+        // only a canonical dashed lowercase UUID and rejects the whole submission
+        // otherwise (see delivery/refetchProvenance.ts).
+        refetchRequestId: (0, refetchProvenance_1.canonicalRefetchRequestId)(c.refetchRequestId),
     };
 }
 /**

package/dist/delivery/refetchProvenance.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The `refetch_request_id` wire contract.
+ *
+ * The receiving service (TelePost) validates this field as a *canonical* dashed
+ * lowercase UUID — `utils/api_server.py:706-715` answers HTTP 400
+ * `invalid_refetch_provenance` ("refetch_request_id 必须是 UUID") for anything
+ * else — and it rejects the whole submission, permanently, before any review
+ * exists. It is strict on purpose: the stored value must later match the
+ * refetch attempt's own `request_id`, which TelePost generates as
+ * `str(uuid.uuid4())`.
+ *
+ * Callers hand us their key in whatever spelling they generated it. Production
+ * incident 2026-09-27: a manual refetch arrived at the delivery with the bare
+ * 32-hex key `1e22b55cb33e47289f30c62e8ee1e11f` — a v4 UUID whose dashes were
+ * stripped — and the run ended in
+ * `permanent delivery failure: delivery endpoint HTTP 400:
+ *  {"code":"invalid_refetch_provenance","message":"refetch_request_id 必须是 UUID"}`.
+ *
+ * So the boundary canonicalizes instead of forwarding the raw key:
+ *
+ *   - a UUID in any spelling we can recognize (dashed, undashed, UPPER, braces,
+ *     `urn:uuid:` prefix) becomes the canonical dashed lowercase form, which
+ *     keeps the receiving service's identity match intact;
+ *   - a value that is not a UUID at all becomes `''` — an unusable provenance
+ *     must never fail an otherwise valid delivery, and the empty value is
+ *     already the documented shape of a scheduled (non-refetch) delivery.
+ *
+ * Identity is never touched here: the consumer's own idempotency key keeps its
+ * exact spelling as the durable `manual_request_id` (slot identity), and only
+ * the payload field that crosses the wire is normalized.
+ */
+/**
+ * Canonical dashed lowercase UUID for `value`, or `''` when `value` is not a
+ * UUID. Mirrors Python's `uuid.UUID()` leniency exactly: only hyphens may be
+ * removed, and what remains must be 32 hex digits.
+ */
+export declare function canonicalRefetchRequestId(value: unknown): string;
+//# sourceMappingURL=refetchProvenance.d.ts.map

package/dist/delivery/refetchProvenance.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * The `refetch_request_id` wire contract.
+ *
+ * The receiving service (TelePost) validates this field as a *canonical* dashed
+ * lowercase UUID — `utils/api_server.py:706-715` answers HTTP 400
+ * `invalid_refetch_provenance` ("refetch_request_id 必须是 UUID") for anything
+ * else — and it rejects the whole submission, permanently, before any review
+ * exists. It is strict on purpose: the stored value must later match the
+ * refetch attempt's own `request_id`, which TelePost generates as
+ * `str(uuid.uuid4())`.
+ *
+ * Callers hand us their key in whatever spelling they generated it. Production
+ * incident 2026-09-27: a manual refetch arrived at the delivery with the bare
+ * 32-hex key `1e22b55cb33e47289f30c62e8ee1e11f` — a v4 UUID whose dashes were
+ * stripped — and the run ended in
+ * `permanent delivery failure: delivery endpoint HTTP 400:
+ *  {"code":"invalid_refetch_provenance","message":"refetch_request_id 必须是 UUID"}`.
+ *
+ * So the boundary canonicalizes instead of forwarding the raw key:
+ *
+ *   - a UUID in any spelling we can recognize (dashed, undashed, UPPER, braces,
+ *     `urn:uuid:` prefix) becomes the canonical dashed lowercase form, which
+ *     keeps the receiving service's identity match intact;
+ *   - a value that is not a UUID at all becomes `''` — an unusable provenance
+ *     must never fail an otherwise valid delivery, and the empty value is
+ *     already the documented shape of a scheduled (non-refetch) delivery.
+ *
+ * Identity is never touched here: the consumer's own idempotency key keeps its
+ * exact spelling as the durable `manual_request_id` (slot identity), and only
+ * the payload field that crosses the wire is normalized.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalRefetchRequestId = canonicalRefetchRequestId;
+/**
+ * Canonical dashed lowercase UUID for `value`, or `''` when `value` is not a
+ * UUID. Mirrors Python's `uuid.UUID()` leniency exactly: only hyphens may be
+ * removed, and what remains must be 32 hex digits.
+ */
+function canonicalRefetchRequestId(value) {
+    if (typeof value !== 'string')
+        return '';
+    let candidate = value.trim().toLowerCase();
+    if (!candidate)
+        return '';
+    if (candidate.startsWith('urn:uuid:'))
+        candidate = candidate.slice('urn:uuid:'.length);
+    if (candidate.startsWith('{') && candidate.endsWith('}'))
+        candidate = candidate.slice(1, -1);
+    const hex = candidate.replace(/-/g, '');
+    if (!/^[0-9a-f]{32}$/.test(hex))
+        return '';
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+//# sourceMappingURL=refetchProvenance.js.map

package/dist/domain/media/NovelCoverPolicy.d.ts

@@ -15,14 +15,36 @@ export interface NovelCoverPolicy {
      * 'keep': prefer availability over certainty.
      */
     unknownCover: 'skip' | 'keep';
+    /**
+     * What to do when the cover probe itself failed (network / auth / rate
+     * limit), so the bytes were never fetched and no content type exists.
+     *
+     * 'skip' (default): safe mode — most novel covers ARE Pixiv's generated
+     * designs, so keeping an unseen probe failure re-ships exactly the covers
+     * the 640x900 classifier exists to suppress. The cost is one illustration
+     * when a real author cover happens to be transiently unreachable.
+     * 'keep': prefer availability over certainty — a failed probe never costs a
+     * cover, at the price of re-shipping generated designs whenever the CDN or
+     * the account is unreachable.
+     */
+    probeFailed: 'skip' | 'keep';
 }
-/** Production-safe default: an unclassifiable cover is never shipped. */
+/**
+ * Production-safe default: an unclassifiable cover is never shipped, and a
+ * probe that never produced bytes is not treated as evidence that the cover is
+ * real content.
+ */
 export declare const DEFAULT_NOVEL_COVER_POLICY: NovelCoverPolicy;
 /**
  * Classify fetched cover bytes. Returns `unknown` when the image header cannot
  * be read (no decoder in this project, so only the header is inspected).
  */
 export declare function classifyNovelCover(cover: ArrayBuffer | Uint8Array | null | undefined): NovelCoverType;
-/** The delivery decision for one classified cover under a policy. */
-export declare function coverDeliveryDecision(policy: NovelCoverPolicy, type: NovelCoverType): 'deliver' | 'skip';
+/**
+ * Everything `coverDeliveryDecision` can be asked about: the three results
+ * `classifyNovelCover` returns, plus the probe that never produced bytes.
+ */
+export type NovelCoverOutcome = NovelCoverType | 'probe_failed';
+/** The delivery decision for one cover outcome under a policy. */
+export declare function coverDeliveryDecision(policy: NovelCoverPolicy, outcome: NovelCoverOutcome): 'deliver' | 'skip';
 //# sourceMappingURL=NovelCoverPolicy.d.ts.map

package/dist/domain/media/NovelCoverPolicy.js

@@ -31,8 +31,15 @@ exports.coverDeliveryDecision = coverDeliveryDecision;
  * shipping generated covers again.
  *
  * A FAILED probe (network / auth / rate limit) is deliberately NOT `unknown`:
- * it is `probe_failed` and always keeps the cover, because a transient fetch
- * error must never cost a real one.
+ * it is `probe_failed` — the bytes were never seen, so no content type exists.
+ * It is a policy decision like `unknown` (`download.novelCover.probeFailed`),
+ * and the production-safe default is `skip`: the majority of novel covers ARE
+ * Pixiv's generated designs, so a probe failure that keeps the cover re-ships
+ * exactly the payloads the 640x900 classifier exists to suppress. `keep` stays
+ * available for an operator who prefers availability over certainty (a
+ * transient fetch error must never cost a real cover). Either way the loud
+ * `coverType=probe_failed` log line stays, so the decision is observable
+ * instead of silent.
  */
 const imageDimensions_1 = require("../../utils/imageDimensions");
 /**
@@ -43,8 +50,15 @@ const imageDimensions_1 = require("../../utils/imageDimensions");
  */
 exports.PIXIV_GENERATED_COVER_WIDTH = 640;
 exports.PIXIV_GENERATED_COVER_HEIGHT = 900;
-/** Production-safe default: an unclassifiable cover is never shipped. */
-exports.DEFAULT_NOVEL_COVER_POLICY = { unknownCover: 'skip' };
+/**
+ * Production-safe default: an unclassifiable cover is never shipped, and a
+ * probe that never produced bytes is not treated as evidence that the cover is
+ * real content.
+ */
+exports.DEFAULT_NOVEL_COVER_POLICY = {
+    unknownCover: 'skip',
+    probeFailed: 'skip',
+};
 /**
  * Classify fetched cover bytes. Returns `unknown` when the image header cannot
  * be read (no decoder in this project, so only the header is inspected).
@@ -59,12 +73,14 @@ function classifyNovelCover(cover) {
     }
     return 'custom';
 }
-/** The delivery decision for one classified cover under a policy. */
-function coverDeliveryDecision(policy, type) {
-    if (type === 'pixiv_generated')
+/** The delivery decision for one cover outcome under a policy. */
+function coverDeliveryDecision(policy, outcome) {
+    if (outcome === 'pixiv_generated')
         return 'skip';
-    if (type === 'unknown')
+    if (outcome === 'unknown')
         return policy.unknownCover === 'keep' ? 'deliver' : 'skip';
+    if (outcome === 'probe_failed')
+        return policy.probeFailed === 'keep' ? 'deliver' : 'skip';
     return 'deliver';
 }
 //# sourceMappingURL=NovelCoverPolicy.js.map

package/dist/download/DownloadManager.js

@@ -132,6 +132,7 @@ class DownloadManager {
             : MaterializationPolicy_1.DEFAULT_MATERIALIZATION_POLICY;
         const novelCoverPolicy = {
             unknownCover: config.download?.novelCover?.unknown ?? NovelCoverPolicy_1.DEFAULT_NOVEL_COVER_POLICY.unknownCover,
+            probeFailed: config.download?.novelCover?.probeFailed ?? NovelCoverPolicy_1.DEFAULT_NOVEL_COVER_POLICY.probeFailed,
         };
         this.novelDownloader = new NovelDownloader_1.NovelDownloader(client, database, fileService, database, undefined, materialization, novelCoverPolicy);
         this.planner = new DownloadPlanner_1.DownloadPlanner(database, {

package/dist/download/NovelDownloader.d.ts

@@ -34,8 +34,11 @@ export declare class NovelDownloader {
      *  - unknown         → policy decision, default 'skip' (safe mode), so a future
      *                      Pixiv cover-format change surfaces as a loud
      *                      `coverType=unknown` log instead of leaking silently
-     * A FAILED probe (network / auth / rate limit) is a separate case and always
-     * keeps the cover: a transient fetch error must never cost a real one.
+     *  - probe_failed    → policy decision, default 'skip': the bytes were never
+     *                      seen, and most novel covers are generated designs, so
+     *                      keeping an unseen cover re-ships what this classifier
+     *                      exists to suppress. `download.novelCover.probeFailed:
+     *                      keep` restores the availability-first behaviour.
      */
     private resolveCoverUrl;
 }

package/dist/download/NovelDownloader.js

@@ -418,8 +418,11 @@ class NovelDownloader {
      *  - unknown         → policy decision, default 'skip' (safe mode), so a future
      *                      Pixiv cover-format change surfaces as a loud
      *                      `coverType=unknown` log instead of leaking silently
-     * A FAILED probe (network / auth / rate limit) is a separate case and always
-     * keeps the cover: a transient fetch error must never cost a real one.
+     *  - probe_failed    → policy decision, default 'skip': the bytes were never
+     *                      seen, and most novel covers are generated designs, so
+     *                      keeping an unseen cover re-ships what this classifier
+     *                      exists to suppress. `download.novelCover.probeFailed:
+     *                      keep` restores the availability-first behaviour.
      */
     async resolveCoverUrl(novelId, coverUrl) {
         const normalized = (0, novelCover_1.normalizeNovelCoverUrl)(coverUrl);
@@ -430,13 +433,29 @@ class NovelDownloader {
             cover = await this.client.downloadImage(normalized);
         }
         catch (error) {
-            logger_1.logger.warn(`Novel ${novelId} cover probe failed; keeping the cover (coverType=probe_failed)`, {
+            const reason = error instanceof Error ? error.message : String(error);
+            // A failed probe is a policy decision, not an automatic keep: most novel
+            // covers ARE Pixiv's generated designs, so silently shipping an unseen
+            // cover re-ships exactly what the 640x900 classifier exists to suppress.
+            const probeDecision = (0, NovelCoverPolicy_1.coverDeliveryDecision)(this.novelCoverPolicy, 'probe_failed');
+            if (probeDecision === 'deliver') {
+                logger_1.logger.warn(`Novel ${novelId} cover probe failed; keeping the cover per novelCover.probeFailed=keep (coverType=probe_failed)`, {
+                    novelId,
+                    coverUrl: normalized,
+                    coverType: 'probe_failed',
+                    policy: this.novelCoverPolicy.probeFailed,
+                    reason,
+                });
+                return normalized;
+            }
+            logger_1.logger.warn(`Novel ${novelId} cover probe failed; skipping the cover per novelCover.probeFailed=skip (coverType=probe_failed)`, {
                 novelId,
                 coverUrl: normalized,
                 coverType: 'probe_failed',
-                reason: error instanceof Error ? error.message : String(error),
+                policy: this.novelCoverPolicy.probeFailed,
+                reason,
             });
-            return normalized;
+            return null;
         }
         const coverType = (0, NovelCoverPolicy_1.classifyNovelCover)(cover);
         const decision = (0, NovelCoverPolicy_1.coverDeliveryDecision)(this.novelCoverPolicy, coverType);

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

@@ -10,7 +10,11 @@ import { TargetConfig } from '../../config';
  * `refetchRequestId` is the request UUID of a remote manual replacement ("重抓")
  * that produced this delivery; it is empty for scheduled occurrences. The
  * receiving service (TelePost) correlates the incoming review with the refetch
- * attempt on this id.
+ * attempt on this id, and validates it as a canonical UUID — see
+ * `delivery/refetchProvenance.ts` for why an unusable key becomes empty instead
+ * of failing the whole delivery. The consumer's idempotency key itself keeps its
+ * exact spelling as the durable slot identity; only this wire field is
+ * normalized.
  */
 export declare function deliveryContextFields(target: TargetConfig): Record<string, unknown>;
 //# sourceMappingURL=deliveryContext.d.ts.map

package/dist/download/handlers/deliveryContext.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deliveryContextFields = deliveryContextFields;
+const logger_1 = require("../../logger");
+const refetchProvenance_1 = require("../../delivery/refetchProvenance");
 /**
  * Delivery payload context for one target run, merging schedule/slot provenance
  * with the optional remote manual replacement identity.
@@ -12,12 +14,34 @@ exports.deliveryContextFields = deliveryContextFields;
  * `refetchRequestId` is the request UUID of a remote manual replacement ("重抓")
  * that produced this delivery; it is empty for scheduled occurrences. The
  * receiving service (TelePost) correlates the incoming review with the refetch
- * attempt on this id.
+ * attempt on this id, and validates it as a canonical UUID — see
+ * `delivery/refetchProvenance.ts` for why an unusable key becomes empty instead
+ * of failing the whole delivery. The consumer's idempotency key itself keeps its
+ * exact spelling as the durable slot identity; only this wire field is
+ * normalized.
  */
 function deliveryContextFields(target) {
     const ec = target.delivery;
     const slotContext = ec?.slotContext;
     const executionContext = ec?.executionContext;
+    const manualRequestId = slotContext?.manualRequestId ?? '';
+    const refetchRequestId = (0, refetchProvenance_1.canonicalRefetchRequestId)(manualRequestId);
+    if (manualRequestId && !refetchRequestId) {
+        // Visible, not silent: the delivery still goes out (the receiving service
+        // treats an empty provenance as "not a refetch"), but the operator must be
+        // able to see that this manual run cannot be correlated remotely.
+        logger_1.logger.warn('Manual refetch request id is not a UUID; sending an empty refetch_request_id so the delivery is not rejected', {
+            slotId: slotContext?.slotId ?? '',
+            manualRequestIdLength: manualRequestId.length,
+            manualRequestIdPrefix: manualRequestId.slice(0, 8),
+        });
+    }
+    else if (manualRequestId && manualRequestId !== refetchRequestId) {
+        logger_1.logger.info('Canonicalized the manual refetch request id for the delivery payload', {
+            slotId: slotContext?.slotId ?? '',
+            canonicalRefetchRequestId: refetchRequestId,
+        });
+    }
     return {
         scheduleId: executionContext?.scheduleId ?? '',
         executionId: executionContext?.slotId ?? '',
@@ -26,7 +50,7 @@ function deliveryContextFields(target) {
         slotId: slotContext?.slotId ?? executionContext?.slotId ?? '',
         slotName: slotContext?.slotName ?? executionContext?.slotName ?? '',
         slotDate: slotContext?.slotDate ?? executionContext?.slotDate ?? '',
-        refetchRequestId: slotContext?.manualRequestId ?? '',
+        refetchRequestId,
     };
 }
 //# sourceMappingURL=deliveryContext.js.map

package/dist/notification/NotificationPolicy.js

@@ -4,6 +4,7 @@ exports.NotificationPolicy = void 0;
 const DeliveryService_1 = require("../delivery/DeliveryService");
 const targetRoutes_1 = require("../delivery/targetRoutes");
 const TargetOutcome_1 = require("../scheduler/TargetOutcome");
+const ProtocolErrors_1 = require("../scheduler/ProtocolErrors");
 const SlotCoordinator_1 = require("../scheduler/SlotCoordinator");
 const logger_1 = require("../logger");
 /**
@@ -227,6 +228,20 @@ class NotificationPolicy {
         const name = this.targetName(target);
         if (!name)
             return;
+        // A consumer/operator cancel is NOT a refetch failure (finding D). The
+        // cancelled cell keeps its terminal `cancelled_by_consumer` verdict, and no
+        // `disposition:"failed"` outcome may ever be emitted for it — the operator
+        // deliberately stopped the work, and the cancellation is already surfaced
+        // through the job status / events channel, never as a failed refetch report.
+        const cancelledCell = target.id ? this.database.slots.getCell(slot.slotId, target.id) : null;
+        if (cancelledCell?.terminalReasonCode === ProtocolErrors_1.CANCELLED_BY_CONSUMER) {
+            logger_1.logger.info('Refetch outcome suppressed: job was cancelled by the consumer', {
+                slot: slot.slotId,
+                target: target.id,
+                requestId,
+            });
+            return;
+        }
         const deliveryTarget = this.config.delivery?.targets?.[name];
         if (!deliveryTarget || deliveryTarget.type !== 'httpMultipart')
             return;

package/dist/package.json

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

package/dist/scheduler/SlotCoordinator.js

@@ -245,6 +245,13 @@ class SlotCoordinator {
         const cell = this.database.slots.getCell(slotId, targetId);
         if (!cell)
             return;
+        // A consumer/operator cancel is FINAL (see JobCancellation.ts). The abort of
+        // the interrupted run still lands here through the normal per-target outcome
+        // path; a late `failed` must never re-verdict a cancelled cell, or the
+        // protocol status flips from `cancelled` back to `failed` ~10s after the
+        // operator's cancel (finding D). Cancel verdicts are never re-written.
+        if (cell.terminalReasonCode === ProtocolErrors_1.CANCELLED_BY_CONSUMER)
+            return;
         switch (outcome.kind) {
             case 'submitted':
                 this.database.slots.lockCellWork(slotId, targetId, outcome.workId, outcome.workType);

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: '3.4.1', commit: 'd2e9c9e338bd' };
+exports.BUILD = { version: '3.4.3', commit: '74ffa4d29ec2' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

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

package/package.json

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