pixivflow 3.2.0 → 3.3.0

package/README.md

@@ -257,6 +257,31 @@ pixivflow outbox cancel <id>  # 只取消尚未执行的 row
 租约、pending 投递、dead 行，`--repair` 收敛）与 `pixivflow reconcile`
 （把下游已确认的历史重复登记进投递账本，默认 dry-run）。
 
+### 面向编排方的 Job API（Workflow Protocol v1）
+
+PixivFlow 只做「内容采集与处理引擎」：发现、筛选、下载、元数据与媒体处理、候选生成。
+**审核 / 替换 / 队列 / 发布等业务语义不在这里实现**，由编排方（如 TelePost）负责。
+两者之间通过一套稳定的 **Workflow Protocol v1** 用通用 Job 面交互，编排方不互调
+内部接口、也不往请求里塞业务字段。scheduler 对外暴露：
+
+| 端点 | 作用 |
+| --- | --- |
+| `GET /capabilities` | 能力发现：如实声明 `protocol_version` 与 `features`（`idempotency` / `cancel` / `events` / ...），能力声明必须诚实，没声明就是没有 |
+| `POST /jobs` | 提交一个采集任务（如 `candidate_search`）：`idempotency_key` 幂等，携带消费者声明的 `callback_url` 时事件会推送到该地址 |
+| `GET /jobs` · `GET /jobs/{job_id}` | 按幂等键或按 id 查作业状态（含 `status`、`created_at`、`heartbeat_at`、`deadline_at`、`result`/`error`） |
+| `GET /jobs/{job_id}/events` · `POST /jobs/{job_id}/events/ack` | 事件流与对账：`?after=` 续拉、`unacked` 计数、单调游标 ack；回调只是加速通道，漏送也能从这里补齐 |
+
+**作业生命周期可信、可查，不再永久静默。** 每个作业都是持久化的、带完整状态机
+（`queued → running → succeeded|failed|expired|cancelled`）、30 秒心跳、活性预算、
+启动恢复与终态事件；终态必有 `result` 或 `error`。编排方可以随时查询作业、订阅事件、
+对账补拉——再也回不到「点了重抓之后什么反应都没有」的那种状态。写入方与读取方都受
+[外包层](docs/architecture/delivery-runtime.md) 与仓库内 `protocol/v1/`（schema、夹具
+与验收清单）约束；规范与跨仓部署见
+[pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy)
+的 [Workflow Protocol 文档](https://github.com/redtidev1918/pixivflow-telepost-deploy/blob/main/docs/architecture/workflow-protocol.md)。
+旧的 `/internal/targets/:targetId/refetch` 仍作为字节兼容 shim 可用，与 Job 面共享同一
+身份空间，但新集成请走 Job 面 / `POST /jobs`。
+
 ## 常用命令
 
 | 命令 | 说明 |
@@ -316,7 +341,7 @@ PixivFlow 可以完全独立使用。下面是同一作者生态里与它相关
 
 | 项目 | 是什么 | 什么时候需要 |
 | --- | --- | --- |
-| [TelePost](https://github.com/redtidev1918/TelePost) | Telegram 频道投稿、审核与自动化发布平台 | 想把下载结果投进 Telegram 频道、先人工审核再发布时，把它配成 delivery 下游即可。这只是可选组合，PixivFlow 不依赖它 |
+| [TelePost](https://github.com/redtidev1918/TelePost) | Telegram 频道投稿、审核与自动化发布平台 | 作为投递下游接收下载结果，或作为**编排方**通过 [Workflow Protocol v1](#面向编排方的-job-apiworkflow-protocol-v1) 驱动 PixivFlow 提交候选查找作业（审核重抓即走此路）。这只是可选组合，PixivFlow 不依赖它 |
 | [pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy) | PixivFlow + TelePost 的部署与运维套件（Docker / VPS / 云平台） | 想一次性把上面两个项目部署并运维起来时。只跑 PixivFlow 不需要它 |
 | [pixivflow-webui](https://github.com/redtidev1918/pixivflow-webui) | PixivFlow 的 WebUI 前端 | 想用图形界面管理下载与计划 |
 | [pixivflow-desktop](https://github.com/redtidev1918/pixivflow-desktop) | PixivFlow 的官方桌面客户端（macOS / Windows / Linux），内置本仓库运行时与 WebUI | 想要双击即用的原生应用、不想自己装 Node 或起服务时。业务逻辑仍在本仓库，桌面端只负责启动、守护与打包 |

package/dist/commands/SchedulerCommand.js

@@ -10,6 +10,9 @@ const config_1 = require("../config");
 const MultiScheduleManager_1 = require("../scheduler/MultiScheduleManager");
 const ScheduleTriggerServer_1 = require("../scheduler/ScheduleTriggerServer");
 const SlotCoordinator_1 = require("../scheduler/SlotCoordinator");
+const ManualJobAdmission_1 = require("../scheduler/ManualJobAdmission");
+const ManualJobService_1 = require("../scheduler/ManualJobService");
+const ManualRefetchAdapter_1 = require("../scheduler/ManualRefetchAdapter");
 const schedules_1 = require("../scheduler/schedules");
 const targetRoutes_1 = require("../delivery/targetRoutes");
 const scheduler_runtime_1 = require("./scheduler-runtime");
@@ -82,6 +85,22 @@ class SchedulerCommand extends Command_1.BaseCommand {
                 const coordinator = new SlotCoordinator_1.SlotCoordinator(runtime.database);
                 const resolveConfig = () => manager['activeConfig'] ?? runtime.config;
                 const findPlan = (cfg, scheduleId) => cfg.schedules?.find((s) => s.id === scheduleId && s.enabled !== false);
+                // The ONE admission path for consumer-initiated candidate search. Both
+                // the legacy refetch endpoint (below) and the generic protocol job
+                // surface (`jobs`, below) translate their request into this call, so
+                // they share one identity space, one target resolution and one durable
+                // work item per idempotency key.
+                const admission = new ManualJobAdmission_1.ManualJobAdmission({
+                    database: runtime.database,
+                    coordinator,
+                    config: resolveConfig,
+                    admit: (planId, slot, targetId) => manager.triggerSchedule(planId, { slot, onlyTarget: targetId, triggerSource: 'manual' }),
+                });
+                const jobService = new ManualJobService_1.ManualJobService({
+                    database: runtime.database,
+                    config: resolveConfig,
+                    admission,
+                });
                 // Durable dispatch. The trigger endpoint records the occurrence FIRST,
                 // then hands it to the shared scheduler and answers immediately. It must
                 // never await the download itself: a 10-40 minute run outlives the
@@ -159,57 +178,18 @@ 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 deliveryName = (0, targetRoutes_1.primaryDeliveryName)(target);
-                        const delivery = deliveryName ? cfg.delivery?.targets?.[deliveryName] : undefined;
-                        if (delivery?.type !== 'httpMultipart' || !delivery.refetchOutcomeUrl?.trim()) {
-                            throw new Error('refetch outcome endpoint not configured');
-                        }
-                        if ((target.delivery?.fields?.refetch_request_id ?? delivery.fields?.refetch_request_id) !== '{{refetchRequestId}}') {
-                            throw new Error('refetch_request_id delivery field not configured');
-                        }
-                        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' };
-                    },
-                    refetchStatus: (targetId, requestId) => {
-                        const slot = runtime.database.slots.findManualSlot(requestId, targetId);
-                        const cell = slot && runtime.database.slots.getCell(slot.id, targetId);
-                        return slot && cell
-                            ? { requestId, slotId: slot.id, state: cell.status, slotStatus: slot.status }
-                            : null;
-                    },
+                    /**
+                     * The generic Workflow Protocol v1 job surface (`/capabilities`,
+                     * `/jobs`). It answers from the same ledger as the legacy endpoints
+                     * and submits through the same admission path, so a job submitted
+                     * here IS the work item a legacy refetch would have created.
+                     */
+                    jobs: jobService,
+                    // Legacy adapters (protocol §3.1): the historic refetch shape over
+                    // the same shared admission, so `requestId` and `idempotency_key`
+                    // are one identity space.
+                    refetch: (0, ManualRefetchAdapter_1.legacyRefetchSubmit)(admission),
+                    refetchStatus: (0, ManualRefetchAdapter_1.legacyRefetchStatus)(runtime.database),
                     /**
                      * Manual recovery of a FAILED target (§manual-recovery). Distinct
                      * from refetch: there is no review chain to replace and no

package/dist/commands/scheduler-runtime.js

@@ -61,12 +61,14 @@ const token_maintenance_1 = require("../utils/token-maintenance");
 const schedules_1 = require("../scheduler/schedules");
 const SlotCoordinator_1 = require("../scheduler/SlotCoordinator");
 const RecoveryPolicy_1 = require("../scheduler/RecoveryPolicy");
+const CandidateSearchParams_1 = require("../scheduler/CandidateSearchParams");
 const targetRoutes_1 = require("../delivery/targetRoutes");
 const DeliveryLedgerPort_1 = require("../delivery/DeliveryLedgerPort");
 const OutboxWorker_1 = require("../delivery/OutboxWorker");
 const settleDeliveryTerminal_1 = require("../delivery/settleDeliveryTerminal");
 const LegacyOutboxMigration_1 = require("../delivery/LegacyOutboxMigration");
 const NotificationPolicy_1 = require("../notification/NotificationPolicy");
+const JobEventStream_1 = require("../scheduler/JobEventStream");
 const node_crypto_1 = require("node:crypto");
 const placeholders_1 = require("../config/placeholders");
 const logger_1 = require("../logger");
@@ -293,8 +295,20 @@ async function createSchedulerRuntime(configPathArg) {
     // the long-running scheduler daemon; run-once drains explicitly before exit.
     const deliveryDispatcher = new DeliveryDispatcher_1.DeliveryDispatcher(config.delivery, buildProxyUrl(config.network));
     const notificationPolicy = new NotificationPolicy_1.NotificationPolicy(database, config);
+    // Consumer-facing job events (§events). The stream is a projection of the same
+    // `delivery_events` log; this sweep repairs a declared `callback_url` whose
+    // terminal event was lost with the process, exactly like
+    // reconcileScheduleSummaries repairs a terminal slot that was never notified.
+    const jobEvents = new JobEventStream_1.JobEventStream({
+        database,
+        config: () => config,
+        now: () => Date.now(),
+    });
     const outboxWorker = new OutboxWorker_1.OutboxWorker(database, deliveryDispatcher, {
-        beforeDrain: () => notificationPolicy.reconcileScheduleSummaries(),
+        beforeDrain: () => {
+            notificationPolicy.reconcileScheduleSummaries();
+            jobEvents.reconcileOutstanding();
+        },
         retryBaseMs: config.delivery?.outboxRetryBaseMs,
         retryMaxMs: config.delivery?.outboxRetryMaxMs,
         // A confirmed ACK settles the owning Slot cell (submitted / duplicate /
@@ -342,6 +356,30 @@ async function createSchedulerRuntime(configPathArg) {
                 targets: targets.map((t) => t.id),
             });
         }
+        // Occurrence-scoped RETRIEVAL view of a generic `candidate_search` job (§6).
+        // Same pattern as the recovery policy above: a pure map over THIS
+        // occurrence's target snapshot, never a write to the global config. A slot
+        // with no stored view (every scheduled occurrence, and every slot written
+        // before the column existed) keeps the configured behaviour untouched.
+        const requestedSearch = (0, CandidateSearchParams_1.parseCandidateSearchParamsJson)(providedSlot?.paramsJson);
+        if (requestedSearch) {
+            targets = targets.map((target) => (0, CandidateSearchParams_1.applyCandidateSearchParams)(target, requestedSearch));
+            logger_1.logger.info('Generic job retrieval view applied to this occurrence', {
+                scheduleId: schedule.id,
+                slot: providedSlot?.slotId,
+                targets: targets.map((t) => t.id),
+            });
+        }
+        // `constraints.exclude` is a run-level duplicate filter, so it joins the
+        // history the runner already refuses to select from instead of inventing a
+        // second exclusion mechanism.
+        const requestedExclusions = requestedSearch ? (0, CandidateSearchParams_1.excludedWorkIdsFromParams)(requestedSearch) : null;
+        const excludedWorkIds = requestedExclusions
+            ? {
+                illustration: [...(options.excludedWorkIds?.illustration ?? []), ...requestedExclusions.illustration],
+                novel: [...(options.excludedWorkIds?.novel ?? []), ...requestedExclusions.novel],
+            }
+            : options.excludedWorkIds;
         if (targets.length === 0) {
             logger_1.logger.warn('Scheduled plan has no selected targets; skipping', {
                 scheduleId: schedule.id,
@@ -362,6 +400,9 @@ async function createSchedulerRuntime(configPathArg) {
          * overwrite the terminal `failed` record the abandon path wrote).
          */
         let slotAbandoned = false;
+        // This run's lease identity. It is passed to `finish` so a rollup can tell
+        // "my own live lease" from "another worker is on this slot right now".
+        const runOwner = `run-${process.pid}-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
         if (!adhoc) {
             if (providedSlot) {
                 slotCtx = providedSlot;
@@ -380,7 +421,6 @@ async function createSchedulerRuntime(configPathArg) {
                 slotCtx = resolved.context;
             }
             const activeSlot = slotCtx;
-            const runOwner = `run-${process.pid}-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
             const prepared = coordinator.prepare(slotCtx, schedule, targets);
             if (prepared.alreadyCompleted && !onlyTarget) {
                 logger_1.logger.info('Slot already terminal; nothing to do', {
@@ -474,7 +514,7 @@ async function createSchedulerRuntime(configPathArg) {
         let runTargets = selected.map((p) => p.target);
         if (slotCtx && runTargets.length === 0) {
             logger_1.logger.info('All slot cells already complete', { slot: slotCtx.slotId });
-            coordinator.finish(slotCtx, schedule, targets);
+            coordinator.finish(slotCtx, schedule, targets, { leaseOwner: runOwner });
             for (const target of targets)
                 if (target.id)
                     notificationPolicy.noteTerminalRefetchCell(slotCtx.slotId, target.id);
@@ -540,8 +580,8 @@ async function createSchedulerRuntime(configPathArg) {
             const manager = new DownloadManager_1.DownloadManager(scoped, pixivClient, database, fileService);
             if (targetExecutionContexts)
                 manager.setTargetExecutionContexts(targetExecutionContexts);
-            if (options.excludedWorkIds)
-                manager.setProcessedWorkIds(options.excludedWorkIds);
+            if (excludedWorkIds)
+                manager.setProcessedWorkIds(excludedWorkIds);
             manager.setTargetOutcomeHook(outcomeHook);
             if (scheduleSlot) {
                 manager.slotContext = {
@@ -670,7 +710,7 @@ async function createSchedulerRuntime(configPathArg) {
                     //  - the process is going away (`shutdown`). Deliberately leave the Slot
                     //    non-terminal so recovery resumes the same occurrence after restart.
                     if (slotCtx && shouldTerminaliseAbortedSlot(activeAbortOrigin, slotAbandoned)) {
-                        coordinator.finish(slotCtx, schedule, targets);
+                        coordinator.finish(slotCtx, schedule, targets, { leaseOwner: runOwner });
                         for (const target of targets)
                             if (target.id)
                                 notificationPolicy.noteTerminalRefetchCell(slotCtx.slotId, target.id);
@@ -691,7 +731,7 @@ async function createSchedulerRuntime(configPathArg) {
             }
             const duration = Math.round((Date.now() - startTime) / 1000);
             if (slotCtx && !slotAbandoned) {
-                const summary = coordinator.finish(slotCtx, schedule, targets);
+                const summary = coordinator.finish(slotCtx, schedule, targets, { leaseOwner: runOwner });
                 for (const target of targets)
                     if (target.id)
                         notificationPolicy.noteTerminalRefetchCell(slotCtx.slotId, target.id);

package/dist/config/defaults.d.ts

@@ -24,6 +24,8 @@ export declare const DEFAULT_CONFIG: {
         readonly watchConfig: true;
         readonly reloadDebounceMs: 500;
         readonly queueLimit: 8;
+        readonly queuedTimeoutMs: number;
+        readonly stallTimeoutMs: number;
         readonly trigger: {
             readonly port: 8090;
             readonly host: "0.0.0.0";

package/dist/config/defaults.js

@@ -27,6 +27,12 @@ exports.DEFAULT_CONFIG = {
         watchConfig: true,
         reloadDebounceMs: 500,
         queueLimit: 8,
+        // Liveness budgets (§liveness). Generous on purpose: production runs take
+        // 10-40 minutes and are sometimes queued hours behind a busy account, so a
+        // slot is only terminalised when its LEASE is dead and it stopped
+        // progressing — never merely because it is slow.
+        queuedTimeoutMs: 30 * 60 * 1000,
+        stallTimeoutMs: 15 * 60 * 1000,
         trigger: {
             port: 8090,
             host: '0.0.0.0',

package/dist/config/types.d.ts

@@ -551,6 +551,26 @@ export interface SchedulerRuntimeConfig {
      * One pending run per plan is retained; extra ticks are skipped.
      */
     queueLimit?: number;
+    /**
+     * Liveness budget for admitted work that never started (§liveness). A Slot
+     * that is still `pending` with no live lease after this long is terminalised
+     * as `queued_too_long` (its cells fail with that reason) instead of being
+     * re-dispatched forever and reporting an eternal "unfinished" job. Values
+     * below one minute are ignored (the sweep then uses its default) and warned
+     * about at config validation; nothing here is fatal.
+     * Default: 1800000ms (30 minutes).
+     */
+    queuedTimeoutMs?: number;
+    /**
+     * Liveness budget for a claimed run that stopped progressing (§liveness). A
+     * `running` Slot whose lease expired AND whose last heartbeat is older than
+     * this is terminalised as `stalled_no_heartbeat`. A LIVE lease is never
+     * eligible, so a genuinely long search is never killed. Values below one
+     * minute are ignored (the sweep then uses its default) and warned about at
+     * config validation; nothing here is fatal.
+     * Default: 900000ms (15 minutes).
+     */
+    stallTimeoutMs?: number;
     /**
      * External-mode run-to-completion lifecycle. When true, the daemon exits the
      * process once its OWN durable ledger says there is nothing left to do, so a

package/dist/config/validation.js

@@ -639,6 +639,17 @@ function validateConfig(config, location, databasePath) {
         if (queueLimit !== undefined && (!Number.isInteger(queueLimit) || queueLimit < 0 || queueLimit > 100)) {
             errors.push('schedulerRuntime.queueLimit: Must be an integer between 0 and 100');
         }
+        // Liveness budgets (§liveness): a WARNING, never an error. A bad value must
+        // not stop the daemon from starting; the sweep clamps to its own default so
+        // the behaviour stays safe either way.
+        for (const key of ['queuedTimeoutMs', 'stallTimeoutMs']) {
+            const value = rt[key];
+            if (value === undefined)
+                continue;
+            if (typeof value !== 'number' || !Number.isInteger(value) || value < 60000) {
+                warnings.push(`schedulerRuntime.${key}: Should be an integer of at least 60000 (milliseconds); the liveness sweep uses its default instead`);
+            }
+        }
         if (rt.exitWhenIdle !== undefined && typeof rt.exitWhenIdle !== 'boolean') {
             errors.push('schedulerRuntime.exitWhenIdle: Must be a boolean');
         }

package/dist/delivery/DeliveryDispatcher.d.ts

@@ -1,10 +1,12 @@
 import { DeliveryConfig } from '../config';
+import { EventCallbackPayload } from './EventCallbackDelivery';
 import { ReadinessProbeResult } from './HttpMultipartDelivery';
 import { DeliveryNotificationRequest, DeliveryRequest, DeliveryResult } from './types';
 /** Resolves named delivery targets without coupling the outbox to a provider. */
 export declare class DeliveryDispatcher {
     private readonly config;
     private readonly proxyUrl?;
+    private readonly eventCallbacks;
     constructor(config: DeliveryConfig | undefined, proxyUrl?: string | undefined);
     hasTarget(name: string): boolean;
     isReady(name: string): Promise<boolean>;
@@ -12,5 +14,17 @@ export declare class DeliveryDispatcher {
     readinessProbe(name: string): Promise<ReadinessProbeResult>;
     deliver(name: string, request: DeliveryRequest): Promise<DeliveryResult>;
     notify(name: string, request: DeliveryNotificationRequest): Promise<DeliveryResult>;
+    /**
+     * Deliver one `$defs/Event` to a Task's declared `callback_url`.
+     *
+     * This does NOT go through a named delivery target: the endpoint is chosen by
+     * the consumer per Task, not by our config. It is still a delivery in every
+     * other sense — the caller is the outbox worker, so retry, backoff,
+     * dead-lettering and the idempotency index all apply unchanged.
+     */
+    deliverEventCallback(url: string, request: {
+        payload: EventCallbackPayload;
+        idempotencyKey: string;
+    }): Promise<number>;
 }
 //# sourceMappingURL=DeliveryDispatcher.d.ts.map

package/dist/delivery/DeliveryDispatcher.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeliveryDispatcher = void 0;
 const errors_1 = require("../utils/errors");
+const EventCallbackDelivery_1 = require("./EventCallbackDelivery");
 const HttpMultipartDelivery_1 = require("./HttpMultipartDelivery");
 const TelegramReviewDelivery_1 = require("./TelegramReviewDelivery");
 const WebhookDelivery_1 = require("./WebhookDelivery");
@@ -9,9 +10,11 @@ const WebhookDelivery_1 = require("./WebhookDelivery");
 class DeliveryDispatcher {
     config;
     proxyUrl;
+    eventCallbacks;
     constructor(config, proxyUrl) {
         this.config = config;
         this.proxyUrl = proxyUrl;
+        this.eventCallbacks = new EventCallbackDelivery_1.EventCallbackDelivery(proxyUrl);
     }
     hasTarget(name) {
         return Boolean(this.config?.targets?.[name]);
@@ -67,6 +70,17 @@ class DeliveryDispatcher {
         }
         return new HttpMultipartDelivery_1.HttpMultipartDelivery(target, this.proxyUrl).notifyOnce(request);
     }
+    /**
+     * Deliver one `$defs/Event` to a Task's declared `callback_url`.
+     *
+     * This does NOT go through a named delivery target: the endpoint is chosen by
+     * the consumer per Task, not by our config. It is still a delivery in every
+     * other sense — the caller is the outbox worker, so retry, backoff,
+     * dead-lettering and the idempotency index all apply unchanged.
+     */
+    async deliverEventCallback(url, request) {
+        return this.eventCallbacks.deliver({ url, payload: request.payload, idempotencyKey: request.idempotencyKey });
+    }
 }
 exports.DeliveryDispatcher = DeliveryDispatcher;
 //# sourceMappingURL=DeliveryDispatcher.js.map

package/dist/delivery/EventCallbackDelivery.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Deliver one `$defs/Event` to the `callback_url` an accepted `$defs/Task`
+ * declared.
+ *
+ * At-least-once, exactly like every other delivery in this repo: the caller is
+ * the EXISTING `OutboxWorker`, which owns retry, backoff and dead-lettering. So
+ * this module performs exactly ONE HTTP POST and reports the outcome as a thrown
+ * error whose `status` lets `classifyError` decide whether the mistake was
+ * retryable (5xx / 429 -> retry, 4xx -> dead-letter). Transport errors are
+ * rethrown untouched, which keeps them retryable by construction.
+ *
+ * A separate delivery path is deliberately NOT introduced: the callback rides
+ * the same outbox, the same `idx_outbox_key` idempotency index and the same
+ * `delivery_events` audit log as outcome delivery.
+ */
+export interface EventCallbackPayload {
+    /** The `$defs/Event`. The POST body is exactly this object. */
+    event: unknown;
+    job_id: string;
+    /**
+     * Correlation hint read by `OutboxWorker.contextCorrelation` so the outbox
+     * audit rows for this callback are linked to the job's slot.
+     */
+    context?: {
+        slotId?: string;
+    };
+}
+export declare const EVENT_CALLBACK_TIMEOUT_MS = 30000;
+/**
+ * A callback endpoint answered with a non-2xx status. `status` is carried as an
+ * own enumerable property because `Error.message` is not a machine-readable
+ * contract — the outbox hands it to `classifyError(error, status)`.
+ */
+export declare class EventCallbackError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare class EventCallbackDelivery {
+    private readonly proxyUrl?;
+    private readonly timeoutMs;
+    private readonly dispatcher?;
+    constructor(proxyUrl?: string | undefined, timeoutMs?: number);
+    /**
+     * One POST of one event. Resolves with the HTTP status on success; throws
+     * `EventCallbackError` on a non-2xx status and the raw transport error when
+     * the request never completed.
+     */
+    deliver(request: {
+        url: string;
+        payload: EventCallbackPayload;
+        idempotencyKey: string;
+    }): Promise<number>;
+}
+//# sourceMappingURL=EventCallbackDelivery.d.ts.map

package/dist/delivery/EventCallbackDelivery.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Deliver one `$defs/Event` to the `callback_url` an accepted `$defs/Task`
+ * declared.
+ *
+ * At-least-once, exactly like every other delivery in this repo: the caller is
+ * the EXISTING `OutboxWorker`, which owns retry, backoff and dead-lettering. So
+ * this module performs exactly ONE HTTP POST and reports the outcome as a thrown
+ * error whose `status` lets `classifyError` decide whether the mistake was
+ * retryable (5xx / 429 -> retry, 4xx -> dead-letter). Transport errors are
+ * rethrown untouched, which keeps them retryable by construction.
+ *
+ * A separate delivery path is deliberately NOT introduced: the callback rides
+ * the same outbox, the same `idx_outbox_key` idempotency index and the same
+ * `delivery_events` audit log as outcome delivery.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventCallbackDelivery = exports.EventCallbackError = exports.EVENT_CALLBACK_TIMEOUT_MS = void 0;
+exports.EVENT_CALLBACK_TIMEOUT_MS = 30_000;
+/**
+ * A callback endpoint answered with a non-2xx status. `status` is carried as an
+ * own enumerable property because `Error.message` is not a machine-readable
+ * contract — the outbox hands it to `classifyError(error, status)`.
+ */
+class EventCallbackError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'EventCallbackError';
+        this.status = status;
+    }
+}
+exports.EventCallbackError = EventCallbackError;
+class EventCallbackDelivery {
+    proxyUrl;
+    timeoutMs;
+    dispatcher;
+    constructor(proxyUrl, timeoutMs = exports.EVENT_CALLBACK_TIMEOUT_MS) {
+        this.proxyUrl = proxyUrl;
+        this.timeoutMs = timeoutMs;
+        if (proxyUrl) {
+            // Same egress path (and same undici ProxyAgent wiring) as every other
+            // outbound delivery.
+            const { ProxyAgent } = require('undici');
+            this.dispatcher = new ProxyAgent(proxyUrl);
+        }
+    }
+    /**
+     * One POST of one event. Resolves with the HTTP status on success; throws
+     * `EventCallbackError` on a non-2xx status and the raw transport error when
+     * the request never completed.
+     */
+    async deliver(request) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        timer.unref?.();
+        const options = {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-PixivFlow-Delivery': 'job-event',
+                // The consumer deduplicates on the event_id; the outbox deduplicates on
+                // its own key. Sending both is deliberate: either side can converge.
+                'X-Idempotency-Key': request.idempotencyKey,
+            },
+            body: JSON.stringify(request.payload.event),
+            signal: controller.signal,
+        };
+        if (this.dispatcher)
+            options.dispatcher = this.dispatcher;
+        try {
+            const response = await fetch(request.url, options);
+            // Drain (and bound) the body so the socket can be reused/closed.
+            await response.text().catch(() => '');
+            if (response.status >= 200 && response.status < 300)
+                return response.status;
+            // 409 means the consumer already recorded this event_id — idempotent
+            // convergence, not a failure.
+            if (response.status === 409)
+                return response.status;
+            throw new EventCallbackError(`job event callback answered HTTP ${response.status}`, response.status);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.EventCallbackDelivery = EventCallbackDelivery;
+//# sourceMappingURL=EventCallbackDelivery.js.map

package/dist/delivery/OutboxWorker.d.ts

@@ -81,6 +81,17 @@ export declare class OutboxWorker {
     private pump;
     /** Probe via structured readinessProbe when available; boolean fallback stays compatible. */
     private checkReadiness;
+    /**
+     * Honour a consumer cancel.
+     *
+     * A job cancelled while a delivery attempt was in flight (or waiting to
+     * retry) must not be delivered afterwards: the ledger's cell already carries
+     * the terminal `cancelled_by_consumer` verdict, so the intent behind this row
+     * is void. The row is dead-lettered rather than retried — no amount of
+     * retrying can make a cancelled delivery correct — and the skip is logged so
+     * the operator can see what did NOT happen.
+     */
+    private stopCancelledWork;
     /** Record at most one deferral per outbox row per 60s (cold-start poll guard). */
     private recordDeferred;
     /** Pull correlation fields out of payload.context without trusting its shape. */