pixivflow 2.19.5 → 2.20.0

package/dist/commands/SchedulerCommand.js

@@ -157,6 +157,42 @@ class SchedulerCommand extends Command_1.BaseCommand {
                         };
                     },
                     drainOutbox: () => runtime.drainOutbox(),
+                    refetch: async (targetId, requestId, correlationId) => {
+                        const cfg = resolveConfig();
+                        const plans = (cfg.schedules ?? []).filter((plan) => plan.enabled !== false && (0, schedules_1.selectScheduleTargets)(cfg.targets, plan).some((target) => target.id === targetId));
+                        if (plans.length === 0)
+                            throw new Error('unknown target');
+                        if (plans.length !== 1)
+                            throw new Error('ambiguous target');
+                        const plan = plans[0];
+                        const target = (0, schedules_1.selectScheduleTargets)(cfg.targets, plan).find((item) => item.id === targetId);
+                        const now = new Date();
+                        const date = new Intl.DateTimeFormat('en-CA', {
+                            timeZone: plan.timezone ?? 'UTC', year: 'numeric', month: '2-digit', day: '2-digit',
+                        }).format(now);
+                        const slot = {
+                            slotId: `${plan.id}@manual-${requestId.toLowerCase()}`,
+                            scheduleId: plan.id,
+                            occurrenceAt: now.getTime(),
+                            occurrenceDate: date,
+                            occurrenceLabel: 'manual',
+                            timezone: plan.timezone ?? 'UTC',
+                            triggerSource: 'manual',
+                            slotName: '审核群重抓',
+                            slotDate: date,
+                            manualRequestId: requestId,
+                            correlationId: correlationId || undefined,
+                        };
+                        const existing = runtime.database.slots.getSlot(slot.slotId);
+                        if (existing && (existing.scheduleId !== plan.id || existing.targetIds.length !== 1 || existing.targetIds[0] !== targetId)) {
+                            throw new Error('ambiguous target');
+                        }
+                        const prepared = coordinator.prepare(slot, plan, [target]);
+                        if (prepared.alreadyCompleted)
+                            return { slotId: slot.slotId, disposition: 'already_completed' };
+                        const started = manager.triggerSchedule(plan.id, { slot, onlyTarget: targetId, triggerSource: 'manual' });
+                        return { slotId: slot.slotId, disposition: started ? 'accepted' : 'queued' };
+                    },
                     status: (scheduleId) => {
                         const cfg = resolveConfig();
                         const plan = findPlan(cfg, scheduleId);

package/dist/commands/SchedulerRunOnceCommand.d.ts

@@ -2,9 +2,8 @@
  * Scheduler run-once command
  *
  * Runs every enabled schedule's download plan exactly once, then exits.
- * This is the backend for the review-group "重抓/换一张" refetch button:
- * a second scheduler daemon would never exit (and would double-fire cron),
- * so refetch needs a bounded one-shot invocation instead.
+ * This is the local CLI path. Remote review-group refetch uses the authenticated
+ * trigger server and a durable manual Slot so a sleeping worker can recover it.
  */
 import { BaseCommand } from './Command';
 import { CommandCategory } from './metadata';

package/dist/commands/SchedulerRunOnceCommand.js

@@ -3,9 +3,8 @@
  * Scheduler run-once command
  *
  * Runs every enabled schedule's download plan exactly once, then exits.
- * This is the backend for the review-group "重抓/换一张" refetch button:
- * a second scheduler daemon would never exit (and would double-fire cron),
- * so refetch needs a bounded one-shot invocation instead.
+ * This is the local CLI path. Remote review-group refetch uses the authenticated
+ * trigger server and a durable manual Slot so a sleeping worker can recover it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SchedulerRunOnceCommand = void 0;

package/dist/commands/scheduler-runtime.js

@@ -438,10 +438,26 @@ async function createSchedulerRuntime(configPathArg) {
             if (!target.id)
                 return;
             options.onTargetOutcome?.(target.id, outcome);
-            if (!scheduleSlot)
+            if (!scheduleSlot) {
+                // No durable slot (run-once CLI): nothing to converge or report.
                 return;
+            }
             coordinator.applyOutcome(scheduleSlot.slotId, target.id, outcome);
             notificationPolicy.noteOutcome(scheduleSlot.slotId, scheduleSlot, schedule, target, outcome);
+            // A remote manual replacement ("重抓") must report its terminal verdict
+            // back to the reviewer. Only terminal outcomes are reported: a candidate
+            // the scan skipped is not a verdict, and a durable delivery intent
+            // ('delivery_pending' / later 'submitted') is reported through the
+            // replacement submission itself (the caller correlates on requestId).
+            const manualRequestId = scheduleSlot.manualRequestId;
+            if (manualRequestId) {
+                const terminal = outcome.kind === 'no_candidate' ||
+                    outcome.kind === 'duplicate' ||
+                    (outcome.kind === 'failed' && !outcome.retryable);
+                if (terminal) {
+                    notificationPolicy.noteRefetchOutcome(scheduleSlot, schedule, target, manualRequestId, outcome);
+                }
+            }
         });
         if (scheduleSlot) {
             downloadManager.slotContext = {

package/dist/config/types.d.ts

@@ -517,6 +517,13 @@ export interface HttpMultipartDeliveryConfig {
     url: string;
     /** Optional JSON endpoint used for no-match operational notifications. */
     notificationUrl?: string;
+    /**
+     * Optional JSON endpoint for remote manual replacement ("重抓") terminal
+     * verdicts (no_alternative / failed). Must be http(s); if unset, manual
+     * outcome reports are skipped (the work itself is still durable). Reuses
+     * `headers` for auth, so no extra credential is needed.
+     */
+    refetchOutcomeUrl?: string;
     method?: 'POST' | 'PUT';
     /** 支持 ${ENV_NAME} 环境变量插值 */
     headers?: Record<string, string>;

package/dist/config/validation.js

@@ -302,6 +302,16 @@ function validateConfig(config, location, databasePath) {
                     errors.push(`${prefix}.notificationUrl: Must be a valid HTTP or HTTPS URL`);
                 }
             }
+            if (delivery.refetchOutcomeUrl && !/\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(delivery.refetchOutcomeUrl)) {
+                try {
+                    const url = new URL(delivery.refetchOutcomeUrl);
+                    if (!['http:', 'https:'].includes(url.protocol))
+                        throw new Error('unsupported protocol');
+                }
+                catch {
+                    errors.push(`${prefix}.refetchOutcomeUrl: Must be a valid HTTP or HTTPS URL`);
+                }
+            }
             if (delivery.readinessUrl && !/\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(delivery.readinessUrl)) {
                 try {
                     const url = new URL(delivery.readinessUrl);

package/dist/delivery/DeliveryService.d.ts

@@ -19,6 +19,26 @@ export interface EnqueueResult {
     /** True when this call created a brand new delivery row. */
     created: boolean;
 }
+/**
+ * Machine-readable terminal verdict of a remote manual replacement ("重抓"),
+ * reported back to the requester (TelePost) through the durable outbox.
+ * Never contains credentials; ids are the opaque request UUID and Pixiv work ids.
+ */
+export interface RefetchOutcomePayload {
+    requestId: string;
+    /** 'no_alternative' | 'failed' (replacement success rides the submission). */
+    disposition: 'no_alternative' | 'failed';
+    reason?: string;
+    workId?: string;
+    /** Bounded candidate-scan bookkeeping for diagnostics (spec-compatible). */
+    scanned?: number;
+    skipped?: {
+        total: number;
+        duplicate: number;
+        invalid: number;
+        unavailable: number;
+    };
+}
 export declare class DeliveryService {
     private readonly database;
     constructor(database: Database);
@@ -76,7 +96,7 @@ export declare class DeliveryService {
         created: boolean;
     };
     /** Enqueue a durable notification (retried independently; never affects content). */
-    enqueueNotification(deliveryTarget: string, text: string, idempotencyKey: string): void;
+    enqueueNotification(deliveryTarget: string, text: string, idempotencyKey: string, refetchOutcome?: RefetchOutcomePayload): void;
     private guardCell;
     private contextFrom;
 }

package/dist/delivery/DeliveryService.js

@@ -175,12 +175,12 @@ class DeliveryService {
         return { deliveryId: row.id, created };
     }
     /** Enqueue a durable notification (retried independently; never affects content). */
-    enqueueNotification(deliveryTarget, text, idempotencyKey) {
+    enqueueNotification(deliveryTarget, text, idempotencyKey, refetchOutcome) {
         this.database.outbox.enqueue({
             kind: 'notification',
             deliveryTarget,
             idempotencyKey,
-            payload: { text },
+            payload: refetchOutcome ? { text, refetchOutcome } : { text },
         });
     }
     guardCell(slotId, targetId, next) {

package/dist/delivery/HttpMultipartDelivery.js

@@ -133,33 +133,54 @@ class HttpMultipartDelivery {
     }
     /** Single notification attempt; the outbox owns retries. */
     async notifyOnce(request) {
-        const url = this.config.notificationUrl?.trim();
-        if (!url)
-            throw new Error('HTTP delivery notificationUrl is not configured');
+        const outcome = request.refetchOutcome;
+        const url = (outcome ? this.config.refetchOutcomeUrl?.trim() : this.config.notificationUrl?.trim());
+        if (!url) {
+            throw new Error(outcome
+                ? 'HTTP delivery refetchOutcomeUrl is not configured'
+                : 'HTTP delivery notificationUrl is not configured');
+        }
         const headers = {
             ...this.resolveHeaders(this.config.headers ?? {}),
             'Content-Type': 'application/json',
         };
+        // Refetch verdicts are machine-readable JSON (the requester's review state
+        // machine consumes disposition, not prose). Plain notifications remain
+        // {text, idempotency_key}.
+        const body = outcome
+            ? {
+                request_id: outcome.requestId,
+                disposition: outcome.disposition,
+                reason: outcome.reason,
+                work_id: outcome.workId,
+                scanned: outcome.scanned,
+                skipped: outcome.skipped,
+            }
+            : { text: request.text, idempotency_key: request.idempotencyKey };
         const options = {
             method: 'POST',
             headers,
-            body: JSON.stringify({ text: request.text, idempotency_key: request.idempotencyKey }),
+            body: JSON.stringify(body),
         };
         if (this.dispatcher)
             options.dispatcher = this.dispatcher;
         const response = await fetch(this.interpolateEnvironment(url), options);
         const text = await response.text();
-        let body = text;
+        let parsed = text;
         if (text) {
             try {
-                body = JSON.parse(text);
+                parsed = JSON.parse(text);
             }
             catch { /* plain ok */ }
         }
         if (!response.ok)
             throw new Error(`notification endpoint returned HTTP ${response.status}`);
-        logger_1.logger.info('HTTP delivery notification sent', { url: (0, redact_1.redactUrl)(url), status: response.status });
-        return { status: response.status, body };
+        logger_1.logger.info('HTTP delivery notification sent', {
+            url: (0, redact_1.redactUrl)(url),
+            status: response.status,
+            hasRefetchOutcome: Boolean(outcome),
+        });
+        return { status: response.status, body: parsed };
     }
     async attempt(request) {
         const fields = this.resolveFields({ ...(this.config.fields ?? {}), ...(request.fields ?? {}) }, request);

package/dist/delivery/OutboxWorker.d.ts

@@ -29,6 +29,8 @@ export interface DeliveryPayload {
 /** Notification side-effect payload. */
 export interface NotificationPayload {
     text: string;
+    /** Optional structured remote-manual-replacement verdict (refetch outcome). */
+    refetchOutcome?: unknown;
 }
 /** Exponential backoff with jitter, capped. */
 export declare function backoffDelayMs(attempt: number, base: number, max: number): number;

package/dist/delivery/OutboxWorker.js

@@ -211,6 +211,9 @@ class OutboxWorker {
                 await this.dispatcher.notify(row.deliveryTarget, {
                     text: payload.text,
                     idempotencyKey: row.idempotencyKey ?? row.id,
+                    refetchOutcome: payload.refetchOutcome !== undefined
+                        ? payload.refetchOutcome
+                        : undefined,
                 });
             }
             else {

package/dist/delivery/types.d.ts

@@ -89,6 +89,24 @@ export interface DeliveryResult {
 export interface DeliveryNotificationRequest {
     text: string;
     idempotencyKey: string;
+    /**
+     * Optional structured remote-manual-replacement verdict. When present the
+     * delivery sends a JSON body to the target's `refetchOutcomeUrl` instead of
+     * a plain text notification to `notificationUrl` (auth reuses `headers`).
+     */
+    refetchOutcome?: {
+        requestId: string;
+        disposition: 'no_alternative' | 'failed';
+        reason?: string;
+        workId?: string;
+        scanned?: number;
+        skipped?: {
+            total: number;
+            duplicate: number;
+            invalid: number;
+            unavailable: number;
+        };
+    };
 }
 export interface DeliveryProvider {
     deliver(request: DeliveryRequest): Promise<DeliveryResult>;

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

@@ -110,6 +110,5 @@ export declare class IllustrationTargetHandler {
      * second concurrent worker lose this race instead of double-submitting.
      */
     private recordArtifactOutcome;
-    private executionContextFields;
 }
 //# sourceMappingURL=IllustrationTargetHandler.d.ts.map

package/dist/download/handlers/IllustrationTargetHandler.js

@@ -9,6 +9,7 @@ const TargetOutcome_1 = require("../../scheduler/TargetOutcome");
 const WorkIdentity_1 = require("../../scheduler/WorkIdentity");
 const target_label_1 = require("../../utils/target-label");
 const DownloadPlanner_1 = require("../plan/DownloadPlanner");
+const deliveryContext_1 = require("./deliveryContext");
 class IllustrationTargetHandler {
     client;
     database;
@@ -681,7 +682,7 @@ class IllustrationTargetHandler {
         const res = this.deliveryService.enqueue(artifact, target, {
             slotId,
             fields: target.delivery?.fields,
-            extraContext: this.executionContextFields(target),
+            extraContext: (0, deliveryContext_1.deliveryContextFields)(target),
         });
         if (res.duplicate) {
             return {
@@ -701,18 +702,6 @@ class IllustrationTargetHandler {
         });
         return { kind: 'selected', workId: artifact.pixivId, workType: artifact.type };
     }
-    executionContextFields(target) {
-        const ec = target.delivery;
-        return {
-            scheduleId: ec?.executionContext?.scheduleId,
-            executionId: ec?.executionContext?.slotId,
-            occurrenceAt: ec?.executionContext?.occurrenceAtIso,
-            triggerSource: ec?.executionContext?.triggerSource,
-            slotId: ec?.slotContext?.slotId ?? ec?.executionContext?.slotId,
-            slotName: ec?.slotContext?.slotName ?? ec?.executionContext?.slotName,
-            slotDate: ec?.slotContext?.slotDate ?? ec?.executionContext?.slotDate,
-        };
-    }
 }
 exports.IllustrationTargetHandler = IllustrationTargetHandler;
 //# sourceMappingURL=IllustrationTargetHandler.js.map

package/dist/download/handlers/NovelTargetHandler.js

@@ -9,6 +9,7 @@ const TargetOutcome_1 = require("../../scheduler/TargetOutcome");
 const WorkIdentity_1 = require("../../scheduler/WorkIdentity");
 const target_label_1 = require("../../utils/target-label");
 const DownloadPlanner_1 = require("../plan/DownloadPlanner");
+const deliveryContext_1 = require("./deliveryContext");
 class NovelTargetHandler {
     client;
     database;
@@ -702,6 +703,7 @@ class NovelTargetHandler {
         const res = this.deliveryService.enqueue(artifact, target, {
             slotId,
             fields: target.delivery?.fields,
+            extraContext: (0, deliveryContext_1.deliveryContextFields)(target),
         });
         if (res.duplicate) {
             return {

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

@@ -0,0 +1,16 @@
+import { TargetConfig } from '../../config';
+/**
+ * Delivery payload context for one target run, merging schedule/slot provenance
+ * with the optional remote manual replacement identity.
+ *
+ * Every key is ALWAYS present (empty string when absent) so delivery templates
+ * never render a literal `{{placeholder}}` into the submitted payload — a
+ * scheduled run and a manual refetch share the same field templates.
+ *
+ * `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.
+ */
+export declare function deliveryContextFields(target: TargetConfig): Record<string, unknown>;
+//# sourceMappingURL=deliveryContext.d.ts.map

package/dist/download/handlers/deliveryContext.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deliveryContextFields = deliveryContextFields;
+/**
+ * Delivery payload context for one target run, merging schedule/slot provenance
+ * with the optional remote manual replacement identity.
+ *
+ * Every key is ALWAYS present (empty string when absent) so delivery templates
+ * never render a literal `{{placeholder}}` into the submitted payload — a
+ * scheduled run and a manual refetch share the same field templates.
+ *
+ * `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.
+ */
+function deliveryContextFields(target) {
+    const ec = target.delivery;
+    const slotContext = ec?.slotContext;
+    const executionContext = ec?.executionContext;
+    return {
+        scheduleId: executionContext?.scheduleId ?? '',
+        executionId: executionContext?.slotId ?? '',
+        occurrenceAt: executionContext?.occurrenceAtIso ?? '',
+        triggerSource: executionContext?.triggerSource ?? '',
+        slotId: slotContext?.slotId ?? executionContext?.slotId ?? '',
+        slotName: slotContext?.slotName ?? executionContext?.slotName ?? '',
+        slotDate: slotContext?.slotDate ?? executionContext?.slotDate ?? '',
+        refetchRequestId: slotContext?.manualRequestId ?? '',
+    };
+}
+//# sourceMappingURL=deliveryContext.js.map

package/dist/notification/NotificationPolicy.d.ts

@@ -33,6 +33,7 @@ export declare class NotificationPolicy {
         hardFail: (slotId: string, targetId: string) => string;
         summary: (slotId: string) => string;
         dead: (slotId: string, targetId: string) => string;
+        refetchOutcome: (slotId: string, targetId: string) => string;
     };
     noteOutcome(slotId: string, slot: SlotContext, schedule: ScheduleConfig, target: TargetConfig, outcome: TargetOutcome): void;
     /** One consolidated summary per slot, delivered to every notifying target's endpoint. */
@@ -45,5 +46,16 @@ export declare class NotificationPolicy {
         error: string | null;
     }>): void;
     private send;
+    /**
+     * Report the terminal verdict of a REMOTE MANUAL replacement ("重抓") back to
+     * the requester through the durable outbox. Only terminal outcomes are
+     * reported (no_candidate / non-retryable failed); a successful replacement is
+     * correlated by the submission itself (its payload carries the request id).
+     *
+     * The key is anchored to the manual SLOT, so a slot recovered and re-run can
+     * never enqueue a second verdict for the same logical attempt, and helpers
+     * that already returned remain idempotent.
+     */
+    noteRefetchOutcome(slot: SlotContext, _schedule: ScheduleConfig, target: TargetConfig, requestId: string, outcome: TargetOutcome): void;
 }
 //# sourceMappingURL=NotificationPolicy.d.ts.map

package/dist/notification/NotificationPolicy.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotificationPolicy = void 0;
 const DeliveryService_1 = require("../delivery/DeliveryService");
+const logger_1 = require("../logger");
 /**
  * Central policy for all operational notifications. Handlers/scheduler do not
  * decide how or when to notify — they emit domain outcomes and this policy
@@ -44,6 +45,7 @@ class NotificationPolicy {
         hardFail: (slotId, targetId) => `notification:${slotId}:${targetId}:failed`,
         summary: (slotId) => `notification:${slotId}:summary`,
         dead: (slotId, targetId) => `notification:${slotId}:${targetId}:delivery-dead`,
+        refetchOutcome: (slotId, targetId) => `refetch-outcome:${slotId}:${targetId}`,
     };
     noteOutcome(slotId, slot, schedule, target, outcome) {
         const name = this.targetName(target);
@@ -104,6 +106,90 @@ class NotificationPolicy {
             console.warn('notification enqueue failed', { targetName, key, error: error.message });
         }
     }
+    /**
+     * Report the terminal verdict of a REMOTE MANUAL replacement ("重抓") back to
+     * the requester through the durable outbox. Only terminal outcomes are
+     * reported (no_candidate / non-retryable failed); a successful replacement is
+     * correlated by the submission itself (its payload carries the request id).
+     *
+     * The key is anchored to the manual SLOT, so a slot recovered and re-run can
+     * never enqueue a second verdict for the same logical attempt, and helpers
+     * that already returned remain idempotent.
+     */
+    noteRefetchOutcome(slot, _schedule, target, requestId, outcome) {
+        const name = this.targetName(target);
+        if (!name)
+            return;
+        const deliveryTarget = this.config.delivery?.targets?.[name];
+        if (!deliveryTarget || deliveryTarget.type !== 'httpMultipart')
+            return;
+        if (!deliveryTarget.refetchOutcomeUrl?.trim()) {
+            // No endpoint configured: skip the report (content is still durable).
+            logger_1.logger.info('Refetch outcome not reported: refetchOutcomeUrl unset', {
+                slot: slot.slotId,
+                target: target.id,
+                requestId,
+            });
+            return;
+        }
+        let payload;
+        if (outcome.kind === 'no_candidate' || outcome.kind === 'duplicate') {
+            payload = {
+                requestId,
+                disposition: 'no_alternative',
+                reason: outcome.reason,
+                workId: outcome.kind === 'duplicate' ? outcome.workId : undefined,
+                ...scanCounts(outcome.scan),
+            };
+        }
+        else if (outcome.kind === 'failed' && !outcome.retryable) {
+            payload = {
+                requestId,
+                disposition: 'failed',
+                reason: outcome.error,
+                ...scanCounts(outcome.scan),
+            };
+        }
+        else {
+            return; // not terminal for refetch purposes
+        }
+        try {
+            new DeliveryService_1.DeliveryService(this.database).enqueueNotification(name, `refetch outcome: ${payload.disposition} (slot ${slot.slotId})`, NotificationPolicy.keys.refetchOutcome(slot.slotId, target.id ?? target.type), payload);
+            logger_1.logger.info('Refetch outcome enqueued for report', {
+                slot: slot.slotId,
+                target: target.id,
+                requestId,
+                disposition: payload.disposition,
+            });
+        }
+        catch (error) {
+            // A failed VERDICT report never changes the terminal content state; it is
+            // retried by the operator/resume path, and never unwinds the run.
+            logger_1.logger.warn('Refetch outcome report enqueue failed', {
+                slot: slot.slotId,
+                target: target.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
 }
 exports.NotificationPolicy = NotificationPolicy;
+/** Fold a CandidateScanSummary into the refetch-outcome bookkeeping (bounded). */
+function scanCounts(scan) {
+    if (!scan)
+        return {};
+    const skipped = scan.skipped ?? [];
+    const duplicate = skipped.filter((s) => s.code === 'duplicate').length;
+    const unavailable = skipped.filter((s) => s.code === 'unavailable').length;
+    const invalid = skipped.filter((s) => ['deleted', 'access_denied', 'unsupported_media', 'invalid_metadata', 'filtered'].includes(s.code)).length;
+    return {
+        scanned: scan.attempted,
+        skipped: {
+            total: skipped.length,
+            duplicate,
+            invalid,
+            unavailable,
+        },
+    };
+}
 //# sourceMappingURL=NotificationPolicy.js.map

package/dist/package.json

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

package/dist/scheduler/MultiScheduleManager.js

@@ -178,6 +178,8 @@ class MultiScheduleManager {
                 triggerSource: asTriggerSource(slot.triggerSource),
                 slotName: slot.slotName || slot.occurrenceLabel,
                 slotDate: slot.slotDate || slot.occurrenceDate,
+                manualRequestId: slot.manualRequestId ?? undefined,
+                correlationId: slot.correlationId ?? undefined,
             };
             const admitted = this.triggerSchedule(slot.scheduleId, {
                 triggerSource: context.triggerSource,

package/dist/scheduler/ScheduleTriggerServer.d.ts

@@ -1,3 +1,4 @@
+import { Request } from 'express';
 import { SlotContext } from './SlotCoordinator';
 import { TriggerSource } from './OccurrenceResolver';
 /**
@@ -51,6 +52,30 @@ export interface TriggerRunResult {
         error?: string | null;
     }>;
 }
+/**
+ * Correlation id issued by the calling clock (`x-schedule-attempt-id`, falling
+ * back to `x-attempt-id`).
+ *
+ * Purely diagnostic: it is trimmed, reduced to `[A-Za-z0-9._:-]` and capped, and
+ * it NEVER participates in occurrence identity. When the clock sends nothing
+ * usable the field is omitted rather than synthesized — a made-up id would make
+ * a missing clock indistinguishable from a satisfied one, which is exactly the
+ * blindness this logging exists to remove.
+ */
+export declare function scheduleAttemptId(req: Request): string | undefined;
+/**
+ * Optional self-identification from the clock that fired: `X-Schedule-Provider`
+ * (e.g. `cron-job-org`, `cloudflare`, `manual`).
+ *
+ * OBSERVABILITY ONLY. It NEVER participates in authorization and NEVER in
+ * occurrence identity: a clock that lies about its name changes one log field
+ * and nothing else. That is deliberate — a self-declared header must not be able
+ * to alter which occurrence runs or whether the request is admitted. Sanitized
+ * and bounded like the attempt id, and omitted when the clock sends nothing
+ * usable rather than defaulted, so "we do not know which clock this was" stays
+ * distinguishable from "the clock identified itself".
+ */
+export declare function scheduleProvider(req: Request): string | undefined;
 export interface TriggerHandlers {
     /** Enabled schedule ids (for 404 on unknown / GET listing). */
     listSchedules(): string[];
@@ -75,16 +100,48 @@ export interface TriggerHandlers {
         retried?: number;
         dead?: number;
     }>;
+    /** Admit one target into a durable, separate manual Slot. */
+    refetch?(targetId: string, requestId: string, correlationId?: string): Promise<{
+        slotId: string;
+        disposition: string;
+    }>;
 }
 export declare class ScheduleTriggerServer {
     private readonly token;
     private readonly handlers;
+    private readonly refetchToken;
     private server;
-    constructor(token: string | undefined, handlers: TriggerHandlers);
+    constructor(token: string | undefined, handlers: TriggerHandlers, refetchToken?: string | undefined);
     /** Token from config or SCHEDULER_TRIGGER_TOKEN env; empty => fail closed. */
     static resolveToken(configured?: string): string | undefined;
     start(host: string, port: number): void;
+    /**
+     * Per-request correlation, installed before every route. It records only the
+     * sanitized attempt id and the arrival instant, so each later line can report
+     * the same `attempt_id` and a handler-relative `elapsed_ms`.
+     */
+    private correlate;
+    /**
+     * `trigger.received` — the clock arrived. Runs before auth, so it carries only
+     * non-sensitive request metadata: never the Authorization header, the bearer
+     * value, the configured token, or any fragment of them.
+     */
+    private received;
+    /**
+     * The single writer for every post-resolution `trigger.*` line. `event` and
+     * `http_status` are passed in from the caller's outcome table, so the line
+     * always describes the same status the response carried.
+     */
+    private triggerOutcome;
+    /**
+     * The non-sensitive correlation fields shared by every `schedule.trigger_*`
+     * line. `attempt_id` and `provider` are OMITTED (never defaulted) when the
+     * clock did not send them, so an unidentified clock stays visible as such.
+     */
+    private attemptMeta;
     private auth;
+    private refetchAuth;
+    private authenticate;
     stop(): void;
 }
 //# sourceMappingURL=ScheduleTriggerServer.d.ts.map