pixivflow 3.1.0 → 3.3.0

package/dist/scheduler/StallSweep.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STALL_SWEEP_BATCH_LIMIT = exports.DEFAULT_STALL_TIMEOUT_MS = exports.DEFAULT_QUEUED_TIMEOUT_MS = exports.STALL_SWEEP_MIN_TIMEOUT_MS = void 0;
+exports.resolveStallTimeouts = resolveStallTimeouts;
+exports.sweepStalledSlots = sweepStalledSlots;
+const TargetOutcome_1 = require("./TargetOutcome");
+const ledger_time_1 = require("./ledger-time");
+const logger_1 = require("../logger");
+/** Nothing is ever stalled before this: a floor against a misconfigured budget. */
+exports.STALL_SWEEP_MIN_TIMEOUT_MS = 60 * 1000;
+/** Admitted but never claimed for this long -> `queued_too_long`. */
+exports.DEFAULT_QUEUED_TIMEOUT_MS = 30 * 60 * 1000;
+/** No heartbeat/lease for this long while `running` -> `stalled_no_heartbeat`. */
+exports.DEFAULT_STALL_TIMEOUT_MS = 15 * 60 * 1000;
+/** Bounded batch: one tick must stay cheap on a large ledger. */
+exports.STALL_SWEEP_BATCH_LIMIT = 100;
+/** The two budgets as configured, each clamped to the floor / its default. */
+function resolveStallTimeouts(rt) {
+    return {
+        queuedTimeoutMs: positiveMs(rt?.queuedTimeoutMs, exports.DEFAULT_QUEUED_TIMEOUT_MS),
+        stallTimeoutMs: positiveMs(rt?.stallTimeoutMs, exports.DEFAULT_STALL_TIMEOUT_MS),
+    };
+}
+function positiveMs(value, fallback) {
+    return typeof value === 'number' &&
+        Number.isFinite(value) &&
+        value >= exports.STALL_SWEEP_MIN_TIMEOUT_MS
+        ? Math.trunc(value)
+        : fallback;
+}
+/** One bounded, liveness-aware sweep. Never throws for a single bad row. */
+function sweepStalledSlots(database, options = {}) {
+    const now = options.now ?? Date.now();
+    const limit = options.limit ?? exports.STALL_SWEEP_BATCH_LIMIT;
+    const { queuedTimeoutMs, stallTimeoutMs } = resolveStallTimeouts(options);
+    const skip = options.skipSlotIds;
+    const result = { scanned: 0, queuedTooLong: 0, stalledNoHeartbeat: 0 };
+    // Rule 1: admitted but never claimed.
+    const queued = database.slots.agedPendingSlots((0, ledger_time_1.sqliteUtcTimestamp)(now - queuedTimeoutMs), now, limit);
+    result.scanned += queued.length;
+    for (const slot of queued) {
+        if (skip?.has(slot.id))
+            continue;
+        if (terminaliseStalledSlot(database, slot, 'queued_too_long', now - queuedTimeoutMs)) {
+            result.queuedTooLong++;
+        }
+    }
+    // Rule 2: claimed, then lost its worker. The lease must be dead AND progress
+    // stale; either one alone is a healthy (or merely slow) run, never a stall.
+    const stalled = database.slots.stalledRunningSlots((0, ledger_time_1.sqliteUtcTimestamp)(now - stallTimeoutMs), now, limit);
+    result.scanned += stalled.length;
+    for (const slot of stalled) {
+        if (skip?.has(slot.id))
+            continue;
+        if (terminaliseStalledSlot(database, slot, 'stalled_no_heartbeat', now - stallTimeoutMs)) {
+            result.stalledNoHeartbeat++;
+        }
+    }
+    return result;
+}
+/**
+ * Terminalise one stalled Slot: every cell that never made progress becomes
+ * `failed` with the liveness reason, and the Slot derives its own rollup so a
+ * partially delivered occurrence still reports `partial` instead of being
+ * misreported as a plain failure. Returns false when nothing was written.
+ */
+function terminaliseStalledSlot(database, slot, code, sinceMs) {
+    const message = TargetOutcome_1.TERMINAL_REASON_MESSAGES[code];
+    const cells = database.slots.getCells(slot.id);
+    let failedCells = 0;
+    for (const cell of cells) {
+        if (cell.status !== 'pending' && cell.status !== 'selected')
+            continue;
+        try {
+            database.slots.transitionCell(slot.id, cell.targetId, 'failed', message);
+            database.slots.setCellTerminalReason(slot.id, cell.targetId, code, message);
+            failedCells++;
+        }
+        catch (error) {
+            logger_1.logger.debug('Stall sweep skipped a cell it could not terminalise', {
+                slot: slot.id,
+                target: cell.targetId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const derived = cells.length === 0 ? 'failed' : database.slots.deriveSlotStatus(slot.id);
+    // A stalled slot must never be reported as healthy: an empty ledger or a
+    // rollup that still contains an in-flight delivery cell stays `failed`.
+    const status = derived === 'success' || derived === 'running' ? 'failed' : derived;
+    database.slots.markSlotStatus(slot.id, status, message);
+    logger_1.logger.warn('Terminalising a slot that made no progress within its liveness budget', {
+        slot: slot.id,
+        schedule: slot.scheduleId,
+        trigger_source: slot.triggerSource,
+        manual_request_id: slot.manualRequestId,
+        correlation_id: slot.correlationId,
+        reason_code: code,
+        slot_status: slot.status,
+        cells_failed: failedCells,
+        stalled_since: new Date(sinceMs).toISOString(),
+    });
+    return true;
+}
+//# sourceMappingURL=StallSweep.js.map

package/dist/scheduler/TargetOutcome.d.ts

@@ -17,6 +17,7 @@
  *    item after its bounded candidate scan, including the scan bookkeeping so
  *    "completed with nothing done" is impossible to report silently.
  */
+import type { ProtocolErrorCode } from './ProtocolErrors';
 export type WorkType = 'illustration' | 'novel';
 /**
  * Why ONE candidate work was skipped without producing a business result.
@@ -330,7 +331,28 @@ export type TerminalReasonCode =
 /** Every candidate the scan saw was already delivered/pending for this target. */
  | 'duplicate_exhausted'
 /** Candidates existed but none passed the target's own filters. */
- | 'filter_exhausted' | 'download_timeout' | 'download_failed' | 'metadata_failed' | 'rate_limited' | 'auth_failed' | 'remote_http_error' | 'delivery_failed' | 'telepost_rejected' | 'telegram_failed' | 'network_error' | 'execution_timeout' | 'configuration_error' | 'internal_error';
+ | 'filter_exhausted' | 'download_timeout' | 'download_failed' | 'metadata_failed' | 'rate_limited' | 'auth_failed' | 'remote_http_error' | 'delivery_failed' | 'telepost_rejected' | 'telegram_failed' | 'network_error' | 'execution_timeout' | 'configuration_error' | 'internal_error'
+/**
+ * Liveness verdicts of the stall sweep (§liveness). The Slot was admitted but
+ * made no progress within its budget: either nothing ever claimed it
+ * (`queued_too_long`) or its owner stopped heartbeating and its lease expired
+ * (`stalled_no_heartbeat`). These describe the LEDGER, not a Pixiv failure.
+ */
+ | 'queued_too_long' | 'stalled_no_heartbeat'
+/**
+ * The owning run ended while a delivery intent had no actionable outbox row
+ * left (dead-lettered, cancelled by an operator, or lost with the process),
+ * so no worker would ever converge that cell.
+ */
+ | 'delivery_abandoned'
+/**
+ * A CONSUMER/operator stopped the work on purpose (§cancel). This is not a
+ * Pixiv failure and not a system failure: nothing went wrong, the work is
+ * simply no longer wanted, so it must never be alerted on or retried
+ * automatically. The cell is terminalised as `failed` (the existing FSM has no
+ * separate "cancelled" state and none is invented) with this code on it.
+ */
+ | 'cancelled_by_consumer';
 export interface TerminalReason {
     code: TerminalReasonCode;
     /** Business-language message an operator/reviewer reads directly. */
@@ -351,6 +373,22 @@ export interface OperationalReason extends TerminalReason {
 export declare function operationalReasonForCode(code: string, message?: string | null): OperationalReason | null;
 /** User-facing business messages — never stack traces, paths, SQL or tokens. */
 export declare const TERMINAL_REASON_MESSAGES: Record<TerminalReasonCode, string>;
+/**
+ * The producer→protocol error mapping (`protocol/v1/error-mapping.json`,
+ * `producer_internal`), expressed as an exhaustive `Record` so a NEW internal
+ * code cannot compile without a protocol mapping: an unmapped internal code
+ * would otherwise leak this service's private vocabulary to a consumer.
+ *
+ * The translation happens ONCE, at the job facade. The legacy manual endpoints
+ * keep reporting internal codes (diagnosis), and the generic surface reports the
+ * protocol code plus `detail.internal_code`.
+ */
+export declare const PROTOCOL_ERROR_CODE_BY_TERMINAL_REASON: Record<TerminalReasonCode, ProtocolErrorCode>;
+/**
+ * Protocol error code for a persisted internal terminal reason, or null when the
+ * code is absent/unknown (never guess a protocol code for an unrecognised one).
+ */
+export declare function protocolErrorCodeForTerminalReason(code: string | null | undefined): ProtocolErrorCode | null;
 /**
  * Map a typed terminal TargetOutcome onto the normalized reason. Returns null
  * for non-terminal outcomes (they have no terminal reason yet).

package/dist/scheduler/TargetOutcome.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TERMINAL_REASON_MESSAGES = void 0;
+exports.PROTOCOL_ERROR_CODE_BY_TERMINAL_REASON = exports.TERMINAL_REASON_MESSAGES = void 0;
 exports.emptyCandidateSupplyReport = emptyCandidateSupplyReport;
 exports.mergeCandidateSupplyReports = mergeCandidateSupplyReports;
 exports.withScanSkips = withScanSkips;
@@ -15,6 +15,7 @@ exports.mergeScanSummaries = mergeScanSummaries;
 exports.classifyCandidateFailure = classifyCandidateFailure;
 exports.classifyJobLevelOutage = classifyJobLevelOutage;
 exports.operationalReasonForCode = operationalReasonForCode;
+exports.protocolErrorCodeForTerminalReason = protocolErrorCodeForTerminalReason;
 exports.terminalReasonFor = terminalReasonFor;
 /**
  * A freshly-harvested upstream funnel with no candidates selected yet.
@@ -306,6 +307,10 @@ const OPERATIONAL_REASON_POLICY = {
     execution_timeout: { stage: 'execution', retryable: true, operatorHint: '检查执行耗时和资源使用后重试。' },
     configuration_error: { stage: 'configuration', retryable: false, operatorHint: '修正配置并完成校验后再重试。' },
     internal_error: { stage: 'execution', retryable: false, operatorHint: '查看对应执行记录；若重复发生，请提交诊断信息。' },
+    queued_too_long: { stage: 'execution', retryable: true, operatorHint: '队列长时间未开始执行：检查调度器是否在运行/被 resource 队列阻塞后重试。' },
+    stalled_no_heartbeat: { stage: 'execution', retryable: true, operatorHint: '执行中途失去心跳（进程中断或卡死）：重启后可重试。' },
+    delivery_abandoned: { stage: 'delivery', retryable: true, operatorHint: '投递意图已无重试队列（被拒绝或取消）：检查接收端后重新重抓。' },
+    cancelled_by_consumer: { stage: 'execution', retryable: false, operatorHint: '用户已取消，无需重试。' },
 };
 function operationalReasonForCode(code, message) {
     if (!(code in OPERATIONAL_REASON_POLICY))
@@ -335,7 +340,52 @@ exports.TERMINAL_REASON_MESSAGES = {
     execution_timeout: '执行超时',
     configuration_error: '配置错误',
     internal_error: '内部错误',
+    queued_too_long: '排队超时，未能开始执行',
+    stalled_no_heartbeat: '执行中断，长时间没有进展',
+    delivery_abandoned: '投稿未被处理，已放弃',
+    cancelled_by_consumer: '任务已被取消',
 };
+/**
+ * The producer→protocol error mapping (`protocol/v1/error-mapping.json`,
+ * `producer_internal`), expressed as an exhaustive `Record` so a NEW internal
+ * code cannot compile without a protocol mapping: an unmapped internal code
+ * would otherwise leak this service's private vocabulary to a consumer.
+ *
+ * The translation happens ONCE, at the job facade. The legacy manual endpoints
+ * keep reporting internal codes (diagnosis), and the generic surface reports the
+ * protocol code plus `detail.internal_code`.
+ */
+exports.PROTOCOL_ERROR_CODE_BY_TERMINAL_REASON = {
+    no_candidate: 'no_candidate',
+    duplicate_exhausted: 'no_candidate',
+    filter_exhausted: 'no_candidate',
+    download_timeout: 'source_error',
+    download_failed: 'source_error',
+    metadata_failed: 'source_error',
+    rate_limited: 'quota_exceeded',
+    auth_failed: 'auth_error',
+    remote_http_error: 'source_error',
+    delivery_failed: 'delivery_failed',
+    telepost_rejected: 'delivery_rejected',
+    telegram_failed: 'delivery_failed',
+    network_error: 'source_error',
+    execution_timeout: 'deadline_exceeded',
+    configuration_error: 'internal_error',
+    internal_error: 'internal_error',
+    queued_too_long: 'queued_too_long',
+    stalled_no_heartbeat: 'stalled_no_progress',
+    delivery_abandoned: 'delivery_abandoned',
+    cancelled_by_consumer: 'cancelled_by_consumer',
+};
+/**
+ * Protocol error code for a persisted internal terminal reason, or null when the
+ * code is absent/unknown (never guess a protocol code for an unrecognised one).
+ */
+function protocolErrorCodeForTerminalReason(code) {
+    if (!code)
+        return null;
+    return exports.PROTOCOL_ERROR_CODE_BY_TERMINAL_REASON[code] ?? null;
+}
 /**
  * Map a typed terminal TargetOutcome onto the normalized reason. Returns null
  * for non-terminal outcomes (they have no terminal reason yet).

package/dist/scheduler/ledger-time.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Conversions for the durable ledger's mixed timestamp shapes.
+ *
+ * `schedule_slots.created_at` / `started_at` / `completed_at` and
+ * `schedule_slot_items.created_at` / `updated_at` / `completed_at` come from
+ * SQLite `CURRENT_TIMESTAMP`: UTC "YYYY-MM-DD HH:MM:SS" with NO zone marker.
+ * `Date.parse` reads that shape as LOCAL time, so the zone is added explicitly
+ * instead of being trusted to the engine.
+ *
+ * `schedule_slots.heartbeat_at` / `lease_until` and the outbox/lease columns are
+ * epoch milliseconds written by this process. Both directions live here so a
+ * projection and a comparison query can never disagree about which shape a
+ * column is in.
+ */
+/** SQLite UTC datetime ("YYYY-MM-DD HH:MM:SS") -> epoch ms. */
+export declare function sqliteUtcMs(value: string | null | undefined): number | undefined;
+/**
+ * Epoch ms -> the exact string shape SQLite's `CURRENT_TIMESTAMP` writes, so a
+ * cutoff can be compared against string columns in SQL instead of loading the
+ * whole ledger to filter in JS.
+ */
+export declare function sqliteUtcTimestamp(epochMs: number): string;
+//# sourceMappingURL=ledger-time.d.ts.map

package/dist/scheduler/ledger-time.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Conversions for the durable ledger's mixed timestamp shapes.
+ *
+ * `schedule_slots.created_at` / `started_at` / `completed_at` and
+ * `schedule_slot_items.created_at` / `updated_at` / `completed_at` come from
+ * SQLite `CURRENT_TIMESTAMP`: UTC "YYYY-MM-DD HH:MM:SS" with NO zone marker.
+ * `Date.parse` reads that shape as LOCAL time, so the zone is added explicitly
+ * instead of being trusted to the engine.
+ *
+ * `schedule_slots.heartbeat_at` / `lease_until` and the outbox/lease columns are
+ * epoch milliseconds written by this process. Both directions live here so a
+ * projection and a comparison query can never disagree about which shape a
+ * column is in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sqliteUtcMs = sqliteUtcMs;
+exports.sqliteUtcTimestamp = sqliteUtcTimestamp;
+/** SQLite UTC datetime ("YYYY-MM-DD HH:MM:SS") -> epoch ms. */
+function sqliteUtcMs(value) {
+    if (!value)
+        return undefined;
+    const normalized = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)
+        ? `${value.replace(' ', 'T')}Z`
+        : value;
+    const ms = Date.parse(normalized);
+    return Number.isNaN(ms) ? undefined : ms;
+}
+/**
+ * Epoch ms -> the exact string shape SQLite's `CURRENT_TIMESTAMP` writes, so a
+ * cutoff can be compared against string columns in SQL instead of loading the
+ * whole ledger to filter in JS.
+ */
+function sqliteUtcTimestamp(epochMs) {
+    return new Date(epochMs).toISOString().slice(0, 19).replace('T', ' ');
+}
+//# sourceMappingURL=ledger-time.js.map

package/dist/storage/DatabaseMigration.js

@@ -282,6 +282,17 @@ class DatabaseMigration {
                 `CREATE INDEX IF NOT EXISTS idx_system_errors_bot_created ON system_errors(bot_id, created_at)`,
                 `CREATE INDEX IF NOT EXISTS idx_cinventory_pending ON candidate_inventory(status, first_seen_date, expires_at)`,
                 `CREATE INDEX IF NOT EXISTS idx_gateway_connections_type ON gateway_connections(type)`,
+                // Durable consumer ack cursor for the Workflow Protocol v1 event stream
+                // (§events). One row per job: the newest `delivery_events` row the
+                // consumer attests it has persisted. This is a cursor, NOT state — acking
+                // never touches the slot ledger, and `unacked` is derived by counting the
+                // job's projected events after this position. Monotonic by construction.
+                `CREATE TABLE IF NOT EXISTS job_event_cursors (
+            job_id TEXT PRIMARY KEY,
+            acked_at INTEGER NOT NULL,
+            acked_row_id INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL
+          )`,
             ];
             // Phase 1: create tables (idempotent). Must run before any PRAGMA-based
             // column check, otherwise a fresh DB would report the table as missing and
@@ -310,6 +321,11 @@ class DatabaseMigration {
                 correlation_id: 'ALTER TABLE schedule_slots ADD COLUMN correlation_id TEXT',
                 recovery_request_id: 'ALTER TABLE schedule_slots ADD COLUMN recovery_request_id TEXT',
                 recovery_mode: 'ALTER TABLE schedule_slots ADD COLUMN recovery_mode TEXT',
+                // Occurrence-scoped retrieval view of a generic `candidate_search` job
+                // (§6). Stored as JSON so a resumed worker re-applies exactly the
+                // retrieval the requester asked for; NULL means "as configured", which is
+                // every slot written before this column existed.
+                params_json: 'ALTER TABLE schedule_slots ADD COLUMN params_json TEXT',
             };
             const columnAlters = [];
             for (const [col, sql] of Object.entries(slotColumnMigrations)) {
@@ -352,6 +368,7 @@ class DatabaseMigration {
                 `CREATE INDEX IF NOT EXISTS idx_delivery_events_execution ON delivery_events(execution_id)`,
                 `CREATE INDEX IF NOT EXISTS idx_delivery_events_outbox ON delivery_events(outbox_id)`,
                 `CREATE INDEX IF NOT EXISTS idx_delivery_events_ts ON delivery_events(ts)`,
+                `CREATE INDEX IF NOT EXISTS idx_delivery_events_slot_event ON delivery_events(slot_id, event)`,
             ];
             const postMigration = this.db.transaction((stmts) => {
                 for (const sql of stmts) {
@@ -359,6 +376,37 @@ class DatabaseMigration {
                 }
             });
             postMigration([...columnAlters, ...indexes]);
+            // Manual-work IDENTITY (§identity): `manual_request_id` is the protocol's
+            // `idempotency_key`, and one key MUST resolve to exactly one durable slot.
+            // Partial unique index, following the `idx_outbox_key` precedent above:
+            // every scheduled row is NULL here, so it is unaffected.
+            //
+            // Guarded on purpose. A ledger written before this migration may hold two
+            // rows for one key (the same request id admitted under two plans), and
+            // throwing would abort the WHOLE migration and brick startup over
+            // historical data. So the conflict is reported loudly and the unique index
+            // is skipped; the admission path still refuses to create a second slot, and
+            // an operator can resolve the historical rows and restart.
+            try {
+                const duplicateKeys = this.db
+                    .prepare(`SELECT manual_request_id AS key, COUNT(*) AS rows FROM schedule_slots
+               WHERE manual_request_id IS NOT NULL AND manual_request_id <> ''
+               GROUP BY manual_request_id HAVING COUNT(*) > 1 LIMIT 5`)
+                    .all();
+                const manualIdentityIndex = `CREATE UNIQUE INDEX IF NOT EXISTS idx_slots_manual_request ON schedule_slots(manual_request_id) WHERE manual_request_id IS NOT NULL`;
+                if (duplicateKeys.length > 0) {
+                    logger_1.logger.warn('Duplicate manual_request_id rows prevent the unique identity index; deduplicate them and restart', { duplicates: duplicateKeys.map((row) => ({ key: row.key, rows: row.rows })) });
+                    this.db
+                        .prepare(`CREATE INDEX IF NOT EXISTS idx_slots_manual_request ON schedule_slots(manual_request_id) WHERE manual_request_id IS NOT NULL`)
+                        .run();
+                }
+                else {
+                    this.db.prepare(manualIdentityIndex).run();
+                }
+            }
+            catch (error) {
+                logger_1.logger.warn('Failed to create the manual identity index', { error });
+            }
             // Add is_active column to config_history if it doesn't exist
             try {
                 // Check if column exists by querying pragma_table_info

package/dist/storage/repositories/DeliveryRepository.d.ts

@@ -52,6 +52,12 @@ export declare class DeliveryRepository extends BaseRepository {
      * allowed to re-run selection for a `delivery_pending` cell.
      */
     listForCell(deliveryTarget: string, slotId: string, targetId: string): DeliveryRow[];
+    /**
+     * Every delivery intent recorded for one Slot CELL, across ALL delivery
+     * routes. The Slot rollup asks this before it is allowed to converge a cell
+     * that was never ACKed; see `SlotCoordinator.finish`.
+     */
+    listForSlotCell(slotId: string, targetId: string): DeliveryRow[];
     /**
      * True when this exact work is already CONFIRMED (delivered, or an attested
      * historical duplicate) for this target. Pending/failed intents do not block

package/dist/storage/repositories/DeliveryRepository.js

@@ -55,6 +55,19 @@ class DeliveryRepository extends BaseRepository_1.BaseRepository {
             .all(deliveryTarget, slotId, targetId);
         return rows.map((r) => this.toRow(r));
     }
+    /**
+     * Every delivery intent recorded for one Slot CELL, across ALL delivery
+     * routes. The Slot rollup asks this before it is allowed to converge a cell
+     * that was never ACKed; see `SlotCoordinator.finish`.
+     */
+    listForSlotCell(slotId, targetId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM deliveries
+         WHERE slot_id = ? AND target_id = ?
+         ORDER BY created_at ASC`)
+            .all(slotId, targetId);
+        return rows.map((r) => this.toRow(r));
+    }
     /**
      * True when this exact work is already CONFIRMED (delivered, or an attested
      * historical duplicate) for this target. Pending/failed intents do not block

package/dist/storage/repositories/OutboxRepository.d.ts

@@ -30,7 +30,41 @@ export interface RecordEventInput {
     /** Short pre-sanitized JSON-able detail. Never put secrets here. */
     detail?: Record<string, unknown> | null;
 }
-export type OutboxKind = 'delivery' | 'notification';
+/**
+ * A position in one job's durable event log: the `(ts, id)` of a
+ * `delivery_events` row. Total order, resolvable back to the row, and stable
+ * across restarts — which is what makes the ack cursor meaningful.
+ */
+export interface EventCursorPosition {
+    at: number;
+    rowId: number;
+}
+export interface JobEventCursor extends EventCursorPosition {
+    jobId: string;
+    updatedAt: number;
+}
+export interface SlotEventInput {
+    slotId: string;
+    event: string;
+    /** Honest instant of the transition. Clamped to the slot's newest event. */
+    at?: number;
+    /** Only set on the `job.requested` row: the declared callback_url. */
+    deliveryTarget?: string | null;
+    detail?: Record<string, unknown> | null;
+}
+export interface SlotEventWrite {
+    /** False when an identical lifecycle event was already durable. */
+    inserted: boolean;
+    event: DeliveryEvent;
+}
+/**
+ * Outbox row kinds. `event_callback` is a Workflow Protocol v1 §events
+ * obligation: deliver one `$defs/Event` to the Task's `callback_url`. It rides
+ * the SAME outbox, dedupe index and retry machinery as outcome delivery — it is
+ * not a second delivery system, and `hasActionableDelivery` (kind='delivery')
+ * and the delivery ledger are deliberately unaffected by it.
+ */
+export type OutboxKind = 'delivery' | 'notification' | 'event_callback';
 export type OutboxStatus = 'pending' | 'processing' | 'retry_wait' | 'done' | 'dead' | 'cancelled';
 export interface OutboxRow {
     id: string;
@@ -145,6 +179,44 @@ export declare class OutboxRepository extends BaseRepository {
      * `DELETE FROM delivery_events WHERE ts < ?` there (same age constant).
      */
     recordEvent(input: RecordEventInput, now?: number): void;
+    /**
+     * Append one job-lifecycle event at most once.
+     *
+     * Idempotent by construction: a single `INSERT ... SELECT ... WHERE NOT
+     * EXISTS` statement, so two callers cannot race a duplicate into the log, and
+     * no UNIQUE index is needed (an index over historical duplicate rows would
+     * brick the migration instead of reporting them).
+     */
+    recordSlotEventOnce(input: SlotEventInput, now?: number): SlotEventWrite;
+    /** Newest recorded `ts` for a slot; null when the slot has no events yet. */
+    newestSlotEventTs(slotId: string): number | null;
+    /** Newest row of one internal kind for a slot. */
+    slotEvent(slotId: string, event: string): DeliveryEvent | null;
+    /** One row by its durable `(slot_id, id)` identity — the ack resolver. */
+    slotEventById(slotId: string, id: number): DeliveryEvent | null;
+    /** A job's events of the given internal kinds, oldest first (ascending `at`). */
+    listSlotEvents(slotId: string, kinds: readonly string[], after?: EventCursorPosition | null, limit?: number): DeliveryEvent[];
+    /** How many of a job's events sit strictly after a cursor position. */
+    countSlotEvents(slotId: string, kinds: readonly string[], after?: EventCursorPosition | null): number;
+    /**
+     * Slots that declared a callback_url but whose terminal event is not durable
+     * yet. This is the sweep behind "a callback is never silently dropped": it is
+     * driven from durable rows only, so a crash between "job terminal" and
+     * "callback enqueued" is repaired, and it converges (each pass either writes
+     * the terminal event or the job is not terminal yet).
+     */
+    slotsAwaitingTerminalEvent(terminalKinds: readonly string[], limit?: number): string[];
+    /** The consumer's durable ack cursor for a job, or null when never acked. */
+    jobEventCursor(jobId: string): JobEventCursor | null;
+    /**
+     * Advance a job's ack cursor. Monotonic and idempotent: a position that is not
+     * strictly ahead of the stored one is a no-op and the stored position is
+     * returned unchanged. This only records what the consumer attests it has
+     * durably stored — it never touches the slot ledger.
+     */
+    advanceJobEventCursor(jobId: string, position: EventCursorPosition, now?: number): JobEventCursor;
+    private jobEventFilter;
+    private toCursor;
     listEvents(filter?: {
         executionId?: string;
         outboxId?: string;

package/dist/storage/repositories/OutboxRepository.js

@@ -297,6 +297,148 @@ class OutboxRepository extends BaseRepository_1.BaseRepository {
             detail: input.detail ? JSON.stringify(input.detail) : null,
         });
     }
+    // --- job event stream (Workflow Protocol v1 §events) ---
+    //
+    // The protocol event stream is a PROJECTION of this same durable log: no
+    // second event table, no second queue. `slot_id` is the job id, `event` is the
+    // internal kind, `ts` is the protocol `at`. Writers below guarantee the
+    // once-only and monotonic properties the protocol requires.
+    /**
+     * Append one job-lifecycle event at most once.
+     *
+     * Idempotent by construction: a single `INSERT ... SELECT ... WHERE NOT
+     * EXISTS` statement, so two callers cannot race a duplicate into the log, and
+     * no UNIQUE index is needed (an index over historical duplicate rows would
+     * brick the migration instead of reporting them).
+     */
+    recordSlotEventOnce(input, now = Date.now()) {
+        // `at` is never allowed to move backwards: the page is ordered by `at` and
+        // `next_after` is a row position, so ascending timestamps and ascending ids
+        // must agree.
+        const ts = Math.max(input.at ?? now, this.newestSlotEventTs(input.slotId) ?? 0);
+        const info = this.db
+            .prepare(`INSERT INTO delivery_events
+           (ts, slot_id, delivery_target, event, counts_as_attempt, actor, detail)
+         SELECT @ts, @slotId, @deliveryTarget, @event, 0, NULL, @detail
+         WHERE NOT EXISTS (
+           SELECT 1 FROM delivery_events WHERE slot_id = @slotId AND event = @event
+         )`)
+            .run({
+            ts,
+            slotId: input.slotId,
+            deliveryTarget: input.deliveryTarget ?? null,
+            event: input.event,
+            detail: input.detail ? JSON.stringify(input.detail) : null,
+        });
+        const event = this.slotEvent(input.slotId, input.event);
+        if (!event)
+            throw new Error(`job event ${input.event} for ${input.slotId} was not persisted`);
+        return { inserted: info.changes > 0, event };
+    }
+    /** Newest recorded `ts` for a slot; null when the slot has no events yet. */
+    newestSlotEventTs(slotId) {
+        const row = this.db
+            .prepare('SELECT MAX(ts) AS ts FROM delivery_events WHERE slot_id = ?')
+            .get(slotId);
+        return row?.ts ?? null;
+    }
+    /** Newest row of one internal kind for a slot. */
+    slotEvent(slotId, event) {
+        const row = this.db
+            .prepare('SELECT * FROM delivery_events WHERE slot_id = ? AND event = ? ORDER BY ts DESC, id DESC LIMIT 1')
+            .get(slotId, event);
+        return row ? this.toEvent(row) : null;
+    }
+    /** One row by its durable `(slot_id, id)` identity — the ack resolver. */
+    slotEventById(slotId, id) {
+        const row = this.db
+            .prepare('SELECT * FROM delivery_events WHERE slot_id = ? AND id = ?')
+            .get(slotId, id);
+        return row ? this.toEvent(row) : null;
+    }
+    /** A job's events of the given internal kinds, oldest first (ascending `at`). */
+    listSlotEvents(slotId, kinds, after = null, limit = 200) {
+        if (kinds.length === 0)
+            return [];
+        const { where, params } = this.jobEventFilter(slotId, kinds, after);
+        const rows = this.db
+            .prepare(`SELECT * FROM delivery_events WHERE ${where} ORDER BY ts ASC, id ASC LIMIT ?`)
+            .all(...params, Math.max(1, Math.min(limit, 500)));
+        return rows.map((r) => this.toEvent(r));
+    }
+    /** How many of a job's events sit strictly after a cursor position. */
+    countSlotEvents(slotId, kinds, after = null) {
+        if (kinds.length === 0)
+            return 0;
+        const { where, params } = this.jobEventFilter(slotId, kinds, after);
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM delivery_events WHERE ${where}`)
+            .get(...params);
+        return row.n;
+    }
+    /**
+     * Slots that declared a callback_url but whose terminal event is not durable
+     * yet. This is the sweep behind "a callback is never silently dropped": it is
+     * driven from durable rows only, so a crash between "job terminal" and
+     * "callback enqueued" is repaired, and it converges (each pass either writes
+     * the terminal event or the job is not terminal yet).
+     */
+    slotsAwaitingTerminalEvent(terminalKinds, limit = 50) {
+        if (terminalKinds.length === 0)
+            return [];
+        const placeholders = terminalKinds.map(() => '?').join(', ');
+        const rows = this.db
+            .prepare(`SELECT e.slot_id AS slot_id
+           FROM delivery_events e
+          WHERE e.event = 'job.requested'
+            AND e.delivery_target IS NOT NULL
+            AND e.slot_id IS NOT NULL
+            AND NOT EXISTS (
+                  SELECT 1 FROM delivery_events t
+                   WHERE t.slot_id = e.slot_id AND t.event IN (${placeholders})
+                )
+          GROUP BY e.slot_id
+          ORDER BY MAX(e.ts) DESC
+          LIMIT ?`)
+            .all(...terminalKinds, Math.max(1, Math.min(limit, 500)));
+        return rows.map((r) => r.slot_id);
+    }
+    /** The consumer's durable ack cursor for a job, or null when never acked. */
+    jobEventCursor(jobId) {
+        const row = this.db.prepare('SELECT * FROM job_event_cursors WHERE job_id = ?').get(jobId);
+        return row ? this.toCursor(row) : null;
+    }
+    /**
+     * Advance a job's ack cursor. Monotonic and idempotent: a position that is not
+     * strictly ahead of the stored one is a no-op and the stored position is
+     * returned unchanged. This only records what the consumer attests it has
+     * durably stored — it never touches the slot ledger.
+     */
+    advanceJobEventCursor(jobId, position, now = Date.now()) {
+        this.db
+            .prepare(`INSERT INTO job_event_cursors (job_id, acked_at, acked_row_id, updated_at)
+         VALUES (@jobId, @at, @rowId, @now)
+         ON CONFLICT(job_id) DO UPDATE SET
+           acked_at = @at,
+           acked_row_id = @rowId,
+           updated_at = @now
+         WHERE @at > acked_at OR (@at = acked_at AND @rowId > acked_row_id)`)
+            .run({ jobId, at: position.at, rowId: position.rowId, now });
+        return this.jobEventCursor(jobId);
+    }
+    jobEventFilter(slotId, kinds, after) {
+        const placeholders = kinds.map(() => '?').join(', ');
+        const clauses = ['slot_id = ?', `event IN (${placeholders})`];
+        const params = [slotId, ...kinds];
+        if (after) {
+            clauses.push('(ts > ? OR (ts = ? AND id > ?))');
+            params.push(after.at, after.at, after.rowId);
+        }
+        return { where: clauses.join(' AND '), params };
+    }
+    toCursor(row) {
+        return { jobId: row.job_id, at: row.acked_at, rowId: row.acked_row_id, updatedAt: row.updated_at };
+    }
     listEvents(filter = {}) {
         const clauses = [];
         const params = [];