pixivflow 2.20.4 → 2.21.0

package/dist/scheduler/MultiScheduleManager.js

@@ -9,6 +9,7 @@ const node_fs_1 = require("node:fs");
 const cron_parser_1 = __importDefault(require("cron-parser"));
 const logger_1 = require("../logger");
 const Scheduler_1 = require("./Scheduler");
+const ResourceAdmission_1 = require("./ResourceAdmission");
 const schedules_1 = require("./schedules");
 const OccurrenceResolver_1 = require("./OccurrenceResolver");
 /**
@@ -23,57 +24,26 @@ function asTriggerSource(value) {
         ? value
         : 'catchup';
 }
-class SerialJobAdmission {
-    queueLimit;
-    active = false;
-    pendingIds = new Set();
-    queue = [];
-    constructor(queueLimit) {
-        this.queueLimit = queueLimit;
-    }
-    setQueueLimit(queueLimit) {
-        this.queueLimit = Math.max(0, queueLimit);
-    }
-    acquire(scheduleId) {
-        if (!this.active) {
-            this.active = true;
-            return Promise.resolve(this.createLease());
-        }
-        // A slow task may span multiple cron ticks. Retain at most one pending run
-        // for each plan so a temporary outage cannot create an unbounded backlog.
-        if (this.pendingIds.has(scheduleId) || this.queue.length >= this.queueLimit) {
-            return Promise.resolve(null);
-        }
-        this.pendingIds.add(scheduleId);
-        return new Promise((resolve) => {
-            this.queue.push({ scheduleId, resolve });
-        });
-    }
-    createLease() {
-        let released = false;
-        return {
-            release: () => {
-                if (released)
-                    return;
-                released = true;
-                this.releaseNext();
-            },
-        };
-    }
-    releaseNext() {
-        const next = this.queue.shift();
-        if (!next) {
-            this.active = false;
-            return;
-        }
-        this.pendingIds.delete(next.scheduleId);
-        next.resolve(this.createLease());
-    }
+/**
+ * Capacity resolver for one resource key, from the configuration's
+ * resource-governance block (§resource-governance). Unknown resources default
+ * to capacity 1. The key encodes the resource identity (`pixiv-account:<id>`),
+ * so two different accounts get two independent capacities.
+ */
+function capacityOfResourceKey(config, key) {
+    const prefix = 'pixiv-account:';
+    if (!key.startsWith(prefix))
+        return 1;
+    const accountId = key.slice(prefix.length);
+    const profile = config?.schedulerRuntime?.resourceGovernance?.pixivAccounts?.[accountId];
+    return Math.max(1, profile?.maxConcurrency ?? 1);
 }
 /**
  * Hosts many cron plans in one process. A validated config snapshot replaces
  * the complete cron table at once; invalid updates leave the previous table
- * running. All jobs share one bounded serial admission queue by default.
+ * running. All jobs that consume the same constrained resource (today: the
+ * shared Pixiv account) pass through ONE bounded resource admission; work for
+ * different resource identities runs concurrently.
  */
 class MultiScheduleManager {
     options;
@@ -83,9 +53,25 @@ class MultiScheduleManager {
     reloadTimer = null;
     recoveryTimer = null;
     watching = false;
-    admission = new SerialJobAdmission(8);
+    admission;
     constructor(options) {
         this.options = options;
+        // Capacity is read lazily from the current config snapshot so a hot
+        // reload that changes `resourceGovernance` applies immediately.
+        this.admission = new ResourceAdmission_1.ResourceAdmission((key) => capacityOfResourceKey(this.activeConfig, key), 8);
+    }
+    /**
+     * Deduplicated, log-safe observable: how many work items are parked waiting
+     * for any resource. Used by the idle lifecycle — waiting work is unfinished
+     * work and must prevent premature shutdown (§waiting-is-not-idle).
+     */
+    waitingWorkCount() {
+        return this.admission.waitingTotal();
+    }
+    /** The resource key a plan's work consumes (resource identity, never a bot/
+     *  schedule/target name). All Pixiv-consuming work shares the account id. */
+    resourceKeyForPlan() {
+        return (0, ResourceAdmission_1.pixivAccountResourceKey)(this.activeConfig?.pixiv?.accountId);
     }
     start(initialConfig) {
         const config = initialConfig ?? this.options.loadConfig();
@@ -180,6 +166,12 @@ class MultiScheduleManager {
                 slotDate: slot.slotDate || slot.occurrenceDate,
                 manualRequestId: slot.manualRequestId ?? undefined,
                 correlationId: slot.correlationId ?? undefined,
+                // A crashed manual recovery resumes with the SAME occurrence-scoped
+                // policy, never a re-resolution that would lose the override.
+                recoveryRequestId: slot.recoveryRequestId ?? undefined,
+                recoveryMode: slot.recoveryMode === 'relaxed' || slot.recoveryMode === 'normal'
+                    ? slot.recoveryMode
+                    : undefined,
             };
             const admitted = this.triggerSchedule(slot.scheduleId, {
                 triggerSource: context.triggerSource,
@@ -284,12 +276,15 @@ class MultiScheduleManager {
         this.activeConfig = config;
         this.generation++;
         const generation = this.generation;
-        this.admission.setQueueLimit(queueLimit);
+        // Bounded wait queue across ALL resources (mirrors the legacy queueLimit
+        // guard against an unbounded backlog); capacity itself is per resource key.
+        this.admission.setMaxWaiting(queueLimit);
+        const resourceKey = this.resourceKeyForPlan();
         for (const plan of enabledPlans) {
             // Watchdog: schedules without an explicit timeout still get a cap so a
             // wedged run cannot hold the shared admission queue forever.
             const schedulerConfig = plan.timeout !== undefined ? plan : { ...plan, timeout: Scheduler_1.DEFAULT_SCHEDULE_TIMEOUT_MS };
-            const scheduler = new Scheduler_1.Scheduler(schedulerConfig, this.options.database, this.options.telemetry, plan.id, this.admission, (failure) => this.options.onFailure?.(config, plan, failure), (abandoned) => this.options.onAbandoned?.(config, plan, abandoned));
+            const scheduler = new Scheduler_1.Scheduler(schedulerConfig, this.options.database, this.options.telemetry, plan.id, this.admission, (failure) => this.options.onFailure?.(config, plan, failure), (abandoned) => this.options.onAbandoned?.(config, plan, abandoned), resourceKey);
             scheduler[registerCron ? 'start' : 'init'](async (options) => {
                 // The closure keeps the exact validated snapshot for an in-flight run.
                 // Cron fires pass no options (runJob resolves the occurrence for now);
@@ -308,6 +303,7 @@ class MultiScheduleManager {
                 targets: plan.targetIds?.length ?? 'all',
             })),
             queueLimit,
+            resourceKey,
         });
         return { ok: true, generation, schedules: scheduleIds };
     }

package/dist/scheduler/RecoveryPolicy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Execution / acquisition policy preset (§recovery-policy).
+ *
+ * Operators do not tune `lookbackDays` / `candidateScanLimit` / language
+ * windows per attempt. The server defines a small number of named presets —
+ * `normal` and `relaxed` — and a recovery run reads the "effective policy"
+ * derived from the base config plus the occurrence-scoped override.
+ *
+ * Hard business constraints are NEVER relaxed by an ordinary recovery policy:
+ * security rules, explicit bans, wrong media type, data-integrity requirements,
+ * permission constraints, the selected topic/work-type boundary, delivery
+ * wiring and already-successfully-submitted exact duplicates are untouched.
+ * Only SOFT criteria (search range, candidate scan count, language-candidate
+ * window) may widen.
+ *
+ * The override is occurrence-scoped: `applyAcquisitionPolicy` is a pure
+ * function over a target snapshot. Nothing here ever writes the global config,
+ * so a manual relaxed recovery can never change future scheduled runs.
+ */
+import { TargetConfig } from '../config';
+export type RecoveryMode = 'normal' | 'relaxed';
+/** The soft levers an acquisition policy may adjust. */
+export interface AcquisitionPolicy {
+    /** Multiplier over the effective candidate scan limit (capped at 100). */
+    scanLimitMultiplier: number;
+    /** Multiplier over `noMatchPolicy.lookbackDays` (capped at the config max). */
+    lookbackDaysMultiplier: number;
+    /** Multiplier over the novel `languageCandidateLimit` search window. */
+    languageCandidateLimitMultiplier: number;
+}
+/**
+ * Server-defined presets. `normal` is the identity policy (the base config);
+ * `relaxed` widens only the soft criteria above.
+ */
+export declare const ACQUISITION_POLICIES: Record<RecoveryMode, AcquisitionPolicy>;
+/** Cap on the relaxed scan limit, mirroring the schedule fallback cap. */
+export declare const RELAXED_SCAN_LIMIT_CAP = 100;
+/** Cap on lookback days widened by a policy (matches the config validation cap). */
+export declare const RELAXED_LOOKBACK_DAYS_CAP = 7;
+/**
+ * Apply an acquisition policy to ONE target snapshot (pure; never mutates the
+ * input or global config). `normal` returns the target unchanged.
+ */
+export declare function applyAcquisitionPolicy(target: TargetConfig, mode: RecoveryMode): TargetConfig;
+//# sourceMappingURL=RecoveryPolicy.d.ts.map

package/dist/scheduler/RecoveryPolicy.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELAXED_LOOKBACK_DAYS_CAP = exports.RELAXED_SCAN_LIMIT_CAP = exports.ACQUISITION_POLICIES = void 0;
+exports.applyAcquisitionPolicy = applyAcquisitionPolicy;
+/**
+ * Server-defined presets. `normal` is the identity policy (the base config);
+ * `relaxed` widens only the soft criteria above.
+ */
+exports.ACQUISITION_POLICIES = {
+    normal: {
+        scanLimitMultiplier: 1,
+        lookbackDaysMultiplier: 1,
+        languageCandidateLimitMultiplier: 1,
+    },
+    relaxed: {
+        scanLimitMultiplier: 3,
+        lookbackDaysMultiplier: 3,
+        languageCandidateLimitMultiplier: 2,
+    },
+};
+/** Cap on the relaxed scan limit, mirroring the schedule fallback cap. */
+exports.RELAXED_SCAN_LIMIT_CAP = 100;
+/** Cap on lookback days widened by a policy (matches the config validation cap). */
+exports.RELAXED_LOOKBACK_DAYS_CAP = 7;
+/**
+ * Apply an acquisition policy to ONE target snapshot (pure; never mutates the
+ * input or global config). `normal` returns the target unchanged.
+ */
+function applyAcquisitionPolicy(target, mode) {
+    if (mode === 'normal')
+        return target;
+    const policy = exports.ACQUISITION_POLICIES[mode];
+    const scanLimit = target.candidateScanLimit !== undefined
+        ? cap(MULTIPLY(target.candidateScanLimit, policy.scanLimitMultiplier), exports.RELAXED_SCAN_LIMIT_CAP)
+        : undefined;
+    const languageCandidateLimit = target.languageCandidateLimit !== undefined
+        ? MULTIPLY(target.languageCandidateLimit, policy.languageCandidateLimitMultiplier)
+        : undefined;
+    const lookbackDays = widenLookback(target.noMatchPolicy?.lookbackDays, policy.lookbackDaysMultiplier);
+    if (scanLimit === undefined && languageCandidateLimit === undefined && lookbackDays === undefined) {
+        return target;
+    }
+    return {
+        ...target,
+        ...(scanLimit !== undefined ? { candidateScanLimit: scanLimit } : {}),
+        ...(languageCandidateLimit !== undefined ? { languageCandidateLimit } : {}),
+        ...(lookbackDays !== undefined
+            ? { noMatchPolicy: { ...(target.noMatchPolicy ?? {}), lookbackDays } }
+            : {}),
+    };
+}
+function MULTIPLY(value, multiplier) {
+    return Math.max(1, Math.floor(value * multiplier));
+}
+function cap(value, maximum) {
+    return Math.min(value, maximum);
+}
+function widenLookback(value, multiplier) {
+    if (value === undefined)
+        return undefined;
+    return Math.min(MULTIPLY(value, multiplier), exports.RELAXED_LOOKBACK_DAYS_CAP);
+}
+//# sourceMappingURL=RecoveryPolicy.js.map

package/dist/scheduler/ResourceAdmission.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Resource-scoped execution admission (§resource-governance).
+ *
+ * Concurrency is governed by the constrained RESOURCE a work item consumes
+ * (today: a Pixiv account), never by bot, schedule or target. Every work item
+ * that touches the scarce upstream — scheduled acquisition, fallback passes,
+ * manual refetch, manual normal/relaxed recovery — declares the resource key
+ * it needs and passes through this same bounded-capacity admission.
+ *
+ * Design constraints honoured here:
+ *
+ *  - Resource identity is a stable internal profile key (e.g.
+ *    `pixiv-account:<accountId>`). Tokens/cookies/session values are never a
+ *    resource key and never appear in logs.
+ *  - Capacity is config-driven per resource identity; the scheduler code does
+ *    not hardcode `1`.
+ *  - Waiting is FIFO (arrival order) per resource key, so no producer is
+ *    starved. Capacity is checked at the moment a lease is handed out, so a
+ *    single process never exceeds `capacity` active leases for one key.
+ *  - Different resource identities never block each other: account A and
+ *    account B run concurrently under independent capacities (no global lock).
+ *  - Waiting is NOT a failure: `acquire` resolves with `null` only when the
+ *    bounded wait queue itself is full (the caller then leaves the work in its
+ *    durable ledger for the recovery sweep). A queued work item is unfinished
+ *    work — it must keep the idle-detector from shutting the worker down
+ *    (see `waitingTotal` on the idle snapshot).
+ *
+ * Implementation level matches the production topology: one PixivFlow process
+ * owns the whole ledger on one machine, so an in-process FIFO semaphore is the
+ * correct mechanism. A durable/distributed lease would only be needed if the
+ * same resource could be consumed by multiple processes at once.
+ */
+export interface ResourceLease {
+    release(): void;
+}
+/**
+ * FIFO per-resource admission with config-driven capacity.
+ *
+ * `capacityOf(resourceKey)` returns the configured capacity for that key
+ * (default 1). `maxWaiting` bounds the TOTAL number of parked work items
+ * across all resources, mirroring the legacy `schedulerRuntime.queueLimit`
+ * guard against an unbounded backlog.
+ */
+export declare class ResourceAdmission {
+    private readonly capacityOf;
+    private maxWaiting;
+    private readonly active;
+    private readonly waiting;
+    constructor(capacityOf: (resourceKey: string) => number, maxWaiting?: number);
+    setMaxWaiting(maxWaiting: number): void;
+    /**
+     * Acquire a lease on `resourceKey`. Resolves immediately when capacity is
+     * available, parks the caller in a FIFO per-key queue otherwise, and resolves
+     * `null` (never rejects) when the bounded wait queue is full.
+     */
+    acquire(resourceKey: string): Promise<ResourceLease | null>;
+    private createLease;
+    private releaseNext;
+    /** Active leases for one resource key. */
+    activeCount(resourceKey: string): number;
+    /** Work items parked waiting for one resource key. */
+    waitingCount(resourceKey: string): number;
+    /** Work items parked waiting for ANY resource. Unfinished work, not failure. */
+    waitingTotal(): number;
+}
+/** The canonical resource identity for the process's Pixiv credential profile. */
+export declare function pixivAccountResourceKey(accountId: string | undefined): string;
+//# sourceMappingURL=ResourceAdmission.d.ts.map

package/dist/scheduler/ResourceAdmission.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceAdmission = void 0;
+exports.pixivAccountResourceKey = pixivAccountResourceKey;
+/**
+ * FIFO per-resource admission with config-driven capacity.
+ *
+ * `capacityOf(resourceKey)` returns the configured capacity for that key
+ * (default 1). `maxWaiting` bounds the TOTAL number of parked work items
+ * across all resources, mirroring the legacy `schedulerRuntime.queueLimit`
+ * guard against an unbounded backlog.
+ */
+class ResourceAdmission {
+    capacityOf;
+    maxWaiting;
+    active = new Map();
+    waiting = [];
+    constructor(capacityOf, maxWaiting = 8) {
+        this.capacityOf = capacityOf;
+        this.maxWaiting = maxWaiting;
+    }
+    setMaxWaiting(maxWaiting) {
+        this.maxWaiting = Math.max(0, maxWaiting);
+    }
+    /**
+     * Acquire a lease on `resourceKey`. Resolves immediately when capacity is
+     * available, parks the caller in a FIFO per-key queue otherwise, and resolves
+     * `null` (never rejects) when the bounded wait queue is full.
+     */
+    acquire(resourceKey) {
+        if (this.activeCount(resourceKey) < this.capacityOf(resourceKey)) {
+            this.active.set(resourceKey, this.activeCount(resourceKey) + 1);
+            return Promise.resolve(this.createLease(resourceKey));
+        }
+        if (this.waiting.length >= this.maxWaiting) {
+            return Promise.resolve(null);
+        }
+        return new Promise((resolve) => {
+            this.waiting.push({ resourceKey, resolve });
+        });
+    }
+    createLease(resourceKey) {
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.releaseNext(resourceKey);
+            },
+        };
+    }
+    releaseNext(resourceKey) {
+        // Hand the freed slot to the OLDEST waiter for this resource key (FIFO),
+        // skipping waiters of other resources so they never block this one.
+        const index = this.waiting.findIndex((entry) => entry.resourceKey === resourceKey);
+        if (index === -1) {
+            const remaining = Math.max(0, this.activeCount(resourceKey) - 1);
+            this.active.set(resourceKey, remaining);
+            return;
+        }
+        const [entry] = this.waiting.splice(index, 1);
+        entry.resolve(this.createLease(resourceKey));
+    }
+    /** Active leases for one resource key. */
+    activeCount(resourceKey) {
+        return this.active.get(resourceKey) ?? 0;
+    }
+    /** Work items parked waiting for one resource key. */
+    waitingCount(resourceKey) {
+        return this.waiting.filter((entry) => entry.resourceKey === resourceKey).length;
+    }
+    /** Work items parked waiting for ANY resource. Unfinished work, not failure. */
+    waitingTotal() {
+        return this.waiting.length;
+    }
+}
+exports.ResourceAdmission = ResourceAdmission;
+/** The canonical resource identity for the process's Pixiv credential profile. */
+function pixivAccountResourceKey(accountId) {
+    return `pixiv-account:${(accountId ?? 'default').trim() || 'default'}`;
+}
+//# sourceMappingURL=ResourceAdmission.js.map

package/dist/scheduler/ScheduleTriggerServer.d.ts

@@ -111,6 +111,22 @@ export interface TriggerHandlers {
         state: string;
         slotStatus: string;
     } | null;
+    /**
+     * Admit one manual RECOVERY of a failed target (§manual-recovery). `retryMode`
+     * selects a SERVER-DEFINED acquisition policy preset ('normal' | 'relaxed');
+     * callers never supply raw acquisition parameters. The run is
+     * occurrence-scoped: it never changes the global config or future schedules.
+     */
+    recover?(targetId: string, requestId: string, retryMode: 'normal' | 'relaxed', correlationId?: string): Promise<{
+        slotId: string;
+        disposition: string;
+    }>;
+    recoverStatus?(targetId: string, requestId: string): {
+        requestId: string;
+        slotId: string;
+        state: string;
+        slotStatus: string;
+    } | null;
 }
 export declare class ScheduleTriggerServer {
     private readonly token;

package/dist/scheduler/ScheduleTriggerServer.js

@@ -207,6 +207,61 @@ class ScheduleTriggerServer {
             }
             res.json(status);
         });
+        // Manual RECOVERY of a failed schedule target (§manual-recovery). Same
+        // authenticated manual-work family as refetch (PIXIVFLOW_REFETCH_TOKEN) but
+        // a DIFFERENT business intent: it re-runs the failed target(s) under a
+        // server-defined acquisition policy preset and reports through the
+        // schedule-outcome channel, so the daily summary is never rewritten.
+        // Admitting is all this endpoint does; if the resource is busy the run is
+        // queued (202 + disposition 'queued'), never failed.
+        app.post('/internal/targets/:targetId/recover', this.refetchAuth, async (req, res) => {
+            const requestId = req.body?.requestId;
+            if (typeof requestId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(requestId)) {
+                res.status(400).json({ status: 'error', error: 'requestId must be a UUID' });
+                return;
+            }
+            // Only a NAMED preset is accepted — never raw acquisition parameters.
+            const rawMode = req.body?.retryMode;
+            const retryMode = rawMode === undefined || rawMode === null || rawMode === '' ? 'normal' : rawMode;
+            if (retryMode !== 'normal' && retryMode !== 'relaxed') {
+                res.status(400).json({ status: 'error', error: 'retryMode must be "normal" or "relaxed"' });
+                return;
+            }
+            const correlationId = req.body?.correlationId;
+            if (correlationId !== undefined && (typeof correlationId !== 'string' || correlationId.length > 200)) {
+                res.status(400).json({ status: 'error', error: 'correlationId must be a string of at most 200 chars' });
+                return;
+            }
+            if (!this.handlers.recover) {
+                res.status(503).json({ status: 'error', error: 'manual recovery is unavailable' });
+                return;
+            }
+            try {
+                const result = await this.handlers.recover(req.params.targetId, requestId, retryMode, correlationId ?? undefined);
+                res.status(202).json({ status: 'accepted', retryMode, ...result });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const status = message === 'unknown target' ? 404 : message === 'ambiguous target' ? 409 : 500;
+                logger_1.logger.warn('Manual recovery rejected', {
+                    targetId: req.params.targetId, requestId, retryMode, status, error: message,
+                });
+                res.status(status).json({ status: 'error', error: status === 500 ? 'recovery admission failed' : message });
+            }
+        });
+        app.get('/internal/targets/:targetId/recover/:requestId', this.refetchAuth, (req, res) => {
+            const { targetId, requestId } = req.params;
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(requestId)) {
+                res.status(400).json({ status: 'error', error: 'requestId must be a UUID' });
+                return;
+            }
+            const status = this.handlers.recoverStatus?.(targetId, requestId);
+            if (!status) {
+                res.status(404).json({ status: 'error', error: 'manual recovery not found' });
+                return;
+            }
+            res.json(status);
+        });
         // Convergence endpoint: after a machine stop/start, an operator or an
         // external watcher can ask the process to flush due deliveries/notifications
         // without running candidate selection. Deployment-agnostic (no platform refs).

package/dist/scheduler/Scheduler.d.ts

@@ -56,7 +56,12 @@ export interface JobAbandoned {
 }
 /** Admission is acquired before timeout/accounting starts. */
 export interface JobAdmissionController {
-    acquire(scheduleId: string): Promise<JobLease | null>;
+    /**
+     * Acquire a lease on the work item's constrained RESOURCE. The key is a
+     * resource identity (`pixiv-account:<id>`), never a bot/schedule/target
+     * name. Resolves `null` only when the bounded wait queue is full.
+     */
+    acquire(resourceKey: string): Promise<JobLease | null>;
 }
 export declare class Scheduler {
     private readonly config;
@@ -66,6 +71,12 @@ export declare class Scheduler {
     private readonly admission?;
     private readonly onFailure?;
     private readonly onAbandoned?;
+    /**
+     * The constrained resource this schedule's work consumes (§resource-
+     * governance). All schedules whose targets share the same Pixiv account
+     * share the same key, so their runs queue under ONE capacity.
+     */
+    private readonly resourceKey?;
     private task;
     private job;
     private running;
@@ -76,7 +87,13 @@ export declare class Scheduler {
     private drainHandle;
     private stopped;
     private pending;
-    constructor(config: SchedulerConfig, database?: Database | undefined, telemetry?: JobTelemetry | undefined, scheduleId?: string, admission?: JobAdmissionController | undefined, onFailure?: ((failure: JobFailure) => Promise<void> | void) | undefined, onAbandoned?: ((abandoned: JobAbandoned) => Promise<void> | void) | undefined);
+    constructor(config: SchedulerConfig, database?: Database | undefined, telemetry?: JobTelemetry | undefined, scheduleId?: string, admission?: JobAdmissionController | undefined, onFailure?: ((failure: JobFailure) => Promise<void> | void) | undefined, onAbandoned?: ((abandoned: JobAbandoned) => Promise<void> | void) | undefined, 
+    /**
+     * The constrained resource this schedule's work consumes (§resource-
+     * governance). All schedules whose targets share the same Pixiv account
+     * share the same key, so their runs queue under ONE capacity.
+     */
+    resourceKey?: string | undefined);
     start(job: (options?: ScheduleRunOptions) => Promise<void>): void;
     /**
      * Arm the scheduler for external/manual triggers (runNow) WITHOUT registering

package/dist/scheduler/Scheduler.js

@@ -33,6 +33,7 @@ class Scheduler {
     admission;
     onFailure;
     onAbandoned;
+    resourceKey;
     task = null;
     job = null;
     running = false;
@@ -43,7 +44,13 @@ class Scheduler {
     drainHandle = null;
     stopped = false;
     pending = false;
-    constructor(config, database, telemetry, scheduleId = 'default', admission, onFailure, onAbandoned) {
+    constructor(config, database, telemetry, scheduleId = 'default', admission, onFailure, onAbandoned, 
+    /**
+     * The constrained resource this schedule's work consumes (§resource-
+     * governance). All schedules whose targets share the same Pixiv account
+     * share the same key, so their runs queue under ONE capacity.
+     */
+    resourceKey) {
         this.config = config;
         this.database = database;
         this.telemetry = telemetry;
@@ -51,6 +58,7 @@ class Scheduler {
         this.admission = admission;
         this.onFailure = onFailure;
         this.onAbandoned = onAbandoned;
+        this.resourceKey = resourceKey;
     }
     start(job) {
         this.arm(job, true);
@@ -149,15 +157,16 @@ class Scheduler {
             await new Promise((resolve) => setTimeout(resolve, this.config.failureRetryDelay));
         }
         this.pending = true;
-        const lease = this.admission ? await this.admission.acquire(this.scheduleId) : null;
+        const lease = this.admission ? await this.admission.acquire(this.resourceKey ?? this.scheduleId) : null;
         this.pending = false;
         if (this.stopped) {
             lease?.release();
             return;
         }
         if (this.admission && !lease) {
-            logger_1.logger.warn('Skipping scheduled job because the shared scheduler queue is full', {
+            logger_1.logger.warn('Work not admitted: the resource wait queue is full; the durable ledger will retry it', {
                 scheduleId: this.scheduleId,
+                resourceKey: this.resourceKey,
             });
             return;
         }

package/dist/scheduler/SlotCoordinator.d.ts

@@ -46,12 +46,26 @@ export interface SlotContext {
     manualRequestId?: string;
     /** Opaque caller correlation (review chain / review id). Null unless manual. */
     correlationId?: string;
+    /**
+     * Remote manual RECOVERY request UUID (§manual-recovery). Present only on
+     * slots opened by the authenticated recover endpoint; null for scheduled
+     * occurrences and review refetches. A recovery slot re-runs the failed
+     * target(s) under an occurrence-scoped recovery policy and reports through
+     * the schedule-outcome channel.
+     */
+    recoveryRequestId?: string;
+    /** Recovery policy preset ('normal' | 'relaxed'); null for non-recovery slots. */
+    recoveryMode?: 'normal' | 'relaxed';
 }
 export interface SlotCellSummary {
     targetId: string;
     status: CellStatus;
     workId: string | null;
     error?: string | null;
+    /** Normalized terminal failure code (§terminal-reason); null when not failed. */
+    terminalReasonCode?: string | null;
+    /** User-facing business reason message (§terminal-reason). */
+    terminalReasonMessage?: string | null;
 }
 export interface SlotRunSummary {
     scheduleId: string;
@@ -233,6 +247,12 @@ export declare class SlotCoordinator {
      * sole path to the submitted cell state.
      */
     applyOutcome(slotId: string, targetId: string, outcome: TargetOutcome): void;
+    /**
+     * Persist the normalized terminal reason (§terminal-reason) for a cell that
+     * just reached a terminal state. Never unwinds the run and never leaks raw
+     * error internals: only the stable code + business message are stored.
+     */
+    private persistTerminalReason;
     /** Promote a delivery_pending cell to submitted from a confirmed ACK. */
     markDelivered(slotId: string, targetId: string, workId: string, workType: string): void;
     /**