pixivflow 3.2.0 → 3.3.0

package/dist/scheduler/ManualJobService.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * The generic job surface: `$defs/Task` in, `$defs/Job` out.
+ *
+ * This is an ADAPTER, not a second execution system. Everything it does is a
+ * translation on top of the one durable ledger:
+ *   - admission      -> `ManualJobAdmission` (shared with the legacy refetch path)
+ *   - read model     -> `JobView` (`buildJobProjection` + `buildProtocolJob`)
+ *   - cancellation   -> `cancelConsumerJob` (one transaction)
+ *   - events/ack     -> `JobEventStream` (projection of `delivery_events`)
+ *
+ * Identity is the consumer's idempotency key, which IS the durable
+ * `manual_request_id`; `job_id` IS the slot id. A replay from either entry
+ * point therefore converges on the same job, and no second slot or delivery can
+ * be created for the same key.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManualJobService = void 0;
+const JobCancellation_1 = require("./JobCancellation");
+const JobEventStream_1 = require("./JobEventStream");
+const JobFacade_1 = require("./JobFacade");
+const JobView_1 = require("./JobView");
+class ManualJobService {
+    deps;
+    events;
+    constructor(deps) {
+        this.deps = deps;
+        this.events = new JobEventStream_1.JobEventStream(this.viewDeps());
+    }
+    now() {
+        return this.deps.now ? this.deps.now() : Date.now();
+    }
+    viewDeps() {
+        return {
+            database: this.deps.database,
+            config: this.deps.config,
+            now: () => this.now(),
+        };
+    }
+    capabilities() {
+        return (0, JobFacade_1.buildCapabilities)(this.deps.config(), this.now());
+    }
+    /** Create or replay the one work item this idempotency key owns. */
+    submitJob(body) {
+        const task = (0, JobFacade_1.parseTaskBody)(body);
+        const result = this.deps.admission.admit({
+            idempotencyKey: task.idempotencyKey,
+            ...(task.correlationId !== undefined ? { correlationId: task.correlationId } : {}),
+            ...(task.account !== undefined ? { account: task.account } : {}),
+            params: task.params,
+        });
+        // The admission event (and the declared callback_url) are recorded against
+        // the durable slot inside the one shared admission path, so a crash right
+        // after admission is repaired by the same reconcile that serves the stream.
+        // A replay never rewrites the endpoint the job already declared.
+        this.events.reconcile(result.slotId, task.callbackUrl ?? null);
+        return { job: this.viewBySlotId(result.slotId), replayed: result.reused };
+    }
+    jobStatus(jobId) {
+        return (0, JobView_1.protocolJobBySlotId)(this.viewDeps(), jobId);
+    }
+    jobsByIdempotencyKey(idempotencyKey) {
+        const slot = this.deps.database.slots.findManualSlotByKey(idempotencyKey);
+        return slot ? [(0, JobView_1.protocolJobForSlot)(this.viewDeps(), slot)] : [];
+    }
+    /** `GET /jobs/:jobId/events` — the durable stream, reconciled from the ledger. */
+    jobEvents(jobId, query) {
+        return this.events.page(jobId, query);
+    }
+    /** `POST /jobs/:jobId/events/ack` — O(1) durable cursor write, never a job mutation. */
+    ackJobEvents(jobId, body) {
+        return this.events.ack(jobId, body);
+    }
+    /**
+     * Idempotent: cancelling an already-terminal job reports its current
+     * projection instead of failing. `cancelConsumerJob` owns the one transaction
+     * that terminalises the work and stops further deliveries.
+     */
+    cancelJob(jobId) {
+        (0, JobCancellation_1.cancelConsumerJob)(this.deps.database, jobId, this.now());
+        // The cancellation is now durable, so its terminal event must be too — a
+        // consumer that polls after cancelling must never see an unterminated stream.
+        this.events.reconcile(jobId);
+        return this.viewBySlotId(jobId);
+    }
+    viewBySlotId(slotId) {
+        return (0, JobView_1.requireProtocolJobForSlotId)(this.viewDeps(), slotId);
+    }
+}
+exports.ManualJobService = ManualJobService;
+//# sourceMappingURL=ManualJobService.js.map

package/dist/scheduler/ManualRefetchAdapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Legacy adapters for the pre-protocol `refetch` surface.
+ *
+ * Workflow Protocol v1 §3.1: the historic endpoint is kept as a *shim* over the
+ * one shared admission, so both entry points create and resolve the SAME work
+ * item and share one identity space (`requestId` == `idempotency_key`). Nothing
+ * here may add behaviour of its own — it only translates shapes and, for the
+ * submit route, restores the historic message strings that route maps onto its
+ * HTTP statuses (`unknown target` -> 404, `ambiguous target` -> 409).
+ */
+import { Database } from '../storage/Database';
+import { JobStatusProjection } from './JobProjection';
+import { ManualJobAdmission } from './ManualJobAdmission';
+export interface LegacyRefetchSubmitResult {
+    slotId: string;
+    disposition: string;
+}
+/** `POST /internal/targets/:targetId/refetch` as a thin adapter. */
+export declare function legacyRefetchSubmit(admission: ManualJobAdmission): (targetId: string, requestId: string, correlationId?: string) => Promise<LegacyRefetchSubmitResult>;
+/**
+ * `GET /internal/targets/:targetId/refetch/:requestId`. The historic alias
+ * fields (`requestId`, `slotId`, `state`, `slotStatus`) are unchanged; the rest
+ * of the projection is additive liveness/cause detail.
+ */
+export declare function legacyRefetchStatus(database: Database): (targetId: string, requestId: string) => JobStatusProjection | null;
+//# sourceMappingURL=ManualRefetchAdapter.d.ts.map

package/dist/scheduler/ManualRefetchAdapter.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.legacyRefetchSubmit = legacyRefetchSubmit;
+exports.legacyRefetchStatus = legacyRefetchStatus;
+const JobProjection_1 = require("./JobProjection");
+const ProtocolErrors_1 = require("./ProtocolErrors");
+/** `POST /internal/targets/:targetId/refetch` as a thin adapter. */
+function legacyRefetchSubmit(admission) {
+    return async (targetId, requestId, correlationId) => {
+        try {
+            const result = admission.admit({
+                targetId,
+                idempotencyKey: requestId,
+                ...(correlationId ? { correlationId } : {}),
+            });
+            return { slotId: result.slotId, disposition: result.disposition };
+        }
+        catch (error) {
+            // The legacy route classifies by MESSAGE, not by code. Re-throwing the
+            // message preserves the deployed contract; the codes stay on the new
+            // surface where callers can rely on them.
+            if (error instanceof ProtocolErrors_1.ProtocolRequestError) {
+                throw new Error(error.body.message ?? error.body.code);
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * `GET /internal/targets/:targetId/refetch/:requestId`. The historic alias
+ * fields (`requestId`, `slotId`, `state`, `slotStatus`) are unchanged; the rest
+ * of the projection is additive liveness/cause detail.
+ */
+function legacyRefetchStatus(database) {
+    return (targetId, requestId) => {
+        const slot = database.slots.findManualSlot(requestId, targetId);
+        const cell = slot && database.slots.getCell(slot.id, targetId);
+        return slot && cell ? (0, JobProjection_1.buildJobProjection)(requestId, slot, cell) : null;
+    };
+}
+//# sourceMappingURL=ManualRefetchAdapter.js.map

package/dist/scheduler/MultiScheduleManager.d.ts

@@ -58,6 +58,23 @@ export declare class MultiScheduleManager {
      *  schedule/target name). All Pixiv-consuming work shares the account id. */
     private resourceKeyForPlan;
     start(initialConfig?: StandaloneConfig): ConfigReloadResult;
+    /**
+     * Liveness sweep (§liveness): terminalise slots that were admitted but never
+     * claimed, or that lost their worker, once they are older than the configured
+     * budget.
+     *
+     * Ordering is load-bearing. Recovery runs FIRST and reports the slots it
+     * re-dispatched; those are excluded here. A re-dispatched slot is owned by an
+     * asynchronous run that has not claimed its lease yet, so without the
+     * exclusion this tick would see "expired lease + stale heartbeat" and fail the
+     * very occurrence recovery just saved — and crash-resume (§manual-resume)
+     * would silently become "fail everything that was interrupted long enough".
+     * The sweep therefore answers the other half of the question: which slots is
+     * recovery UNABLE to rescue (no enabled plan, a stopped/failed Scheduler, or a
+     * queue that never drains)? Those are the ones that would otherwise stay
+     * non-terminal forever.
+     */
+    private runStallSweep;
     private startRecoveryLoop;
     /**
      * Re-dispatch occurrences that the durable ledger says are unfinished but that

package/dist/scheduler/MultiScheduleManager.js

@@ -12,6 +12,7 @@ const Scheduler_1 = require("./Scheduler");
 const ResourceAdmission_1 = require("./ResourceAdmission");
 const schedules_1 = require("./schedules");
 const OccurrenceResolver_1 = require("./OccurrenceResolver");
+const StallSweep_1 = require("./StallSweep");
 /**
  * How often the manager looks for unfinished occurrences that no live worker
  * owns. Combined with the slot lease TTL (SlotCoordinator), the worst case for a
@@ -82,11 +83,47 @@ class MultiScheduleManager {
         this.updateWatcher(config);
         // Recovery first: it acts on occurrences the ledger already knows about.
         // Catch-up is inference ("cron suggests a fire was missed") and runs after.
-        this.recoverInterruptedSlots();
+        const rescued = this.recoverInterruptedSlots();
+        this.runStallSweep(rescued);
         this.startRecoveryLoop();
         this.catchUpMissedRuns(config);
         return result;
     }
+    /**
+     * Liveness sweep (§liveness): terminalise slots that were admitted but never
+     * claimed, or that lost their worker, once they are older than the configured
+     * budget.
+     *
+     * Ordering is load-bearing. Recovery runs FIRST and reports the slots it
+     * re-dispatched; those are excluded here. A re-dispatched slot is owned by an
+     * asynchronous run that has not claimed its lease yet, so without the
+     * exclusion this tick would see "expired lease + stale heartbeat" and fail the
+     * very occurrence recovery just saved — and crash-resume (§manual-resume)
+     * would silently become "fail everything that was interrupted long enough".
+     * The sweep therefore answers the other half of the question: which slots is
+     * recovery UNABLE to rescue (no enabled plan, a stopped/failed Scheduler, or a
+     * queue that never drains)? Those are the ones that would otherwise stay
+     * non-terminal forever.
+     */
+    runStallSweep(rescued = new Set()) {
+        const database = this.options.database;
+        if (!database)
+            return;
+        try {
+            const result = (0, StallSweep_1.sweepStalledSlots)(database, {
+                ...(0, StallSweep_1.resolveStallTimeouts)(this.activeConfig?.schedulerRuntime),
+                skipSlotIds: rescued,
+            });
+            if (result.queuedTooLong > 0 || result.stalledNoHeartbeat > 0) {
+                logger_1.logger.warn('Liveness sweep terminalised stalled slots', { ...result });
+            }
+        }
+        catch (error) {
+            logger_1.logger.warn('Liveness sweep failed; will retry on the next tick', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     startRecoveryLoop() {
         if (!this.options.database)
             return;
@@ -97,7 +134,7 @@ class MultiScheduleManager {
         }
         this.recoveryTimer = setInterval(() => {
             try {
-                this.recoverInterruptedSlots();
+                this.runStallSweep(this.recoverInterruptedSlots());
             }
             catch (error) {
                 logger_1.logger.warn('Slot recovery sweep failed; will retry on the next tick', {
@@ -125,15 +162,16 @@ class MultiScheduleManager {
      */
     recoverInterruptedSlots() {
         const database = this.options.database;
+        const rescued = new Set();
         if (!database)
-            return;
+            return rescued;
         const config = this.activeConfig;
         const plans = new Map((0, schedules_1.resolveSchedules)(config)
             .filter((plan) => plan.enabled)
             .map((plan) => [plan.id, plan]));
         const recovered = database.slots.recoverableSlots();
         if (recovered.length === 0)
-            return;
+            return rescued;
         let reclaimed = 0;
         let skipped = 0;
         for (const slot of recovered) {
@@ -147,6 +185,9 @@ class MultiScheduleManager {
                     slot: slot.id,
                     schedule: slot.scheduleId,
                     status: slot.status,
+                    trigger_source: slot.triggerSource,
+                    manual_request_id: slot.manualRequestId,
+                    correlation_id: slot.correlationId,
                 });
                 continue;
             }
@@ -177,16 +218,37 @@ class MultiScheduleManager {
                 triggerSource: context.triggerSource,
                 slot: context,
             });
-            if (admitted)
+            if (admitted) {
                 reclaimed++;
-            else
+                rescued.add(slot.id);
+            }
+            else {
                 skipped++;
+                // NOT silent: a re-dispatch that keeps failing is exactly how a slot sat
+                // `pending` for days behind a stopped scheduler. Report the reason with
+                // the caller's own request id so a stuck manual job is traceable.
+                const scheduler = this.schedulers.get(slot.scheduleId);
+                const reason = !scheduler
+                    ? 'scheduler_not_instantiated'
+                    : scheduler.getStats().stopped
+                        ? 'schedule_stopped'
+                        : 'scheduler_busy';
+                logger_1.logger.warn('Cannot recover slot: its schedule could not be admitted', {
+                    slot: slot.id,
+                    schedule: slot.scheduleId,
+                    status: slot.status,
+                    reason,
+                    manual_request_id: slot.manualRequestId,
+                    correlation_id: slot.correlationId,
+                });
+            }
         }
         logger_1.logger.info('Recovered interrupted slots', {
             stale_slots_found: recovered.length,
             reclaimed,
             skipped,
         });
+        return rescued;
     }
     /**
      * Self-healing: if the daemon was down across a cron fire (deploy window,

package/dist/scheduler/ProtocolErrors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The Workflow Protocol v1 error vocabulary, producer side (§5 / §5.1).
+ *
+ * The protocol's error enum is CLOSED. PixivFlow keeps its own, richer internal
+ * `TerminalReasonCode` vocabulary for diagnosis, and translates it exactly once,
+ * at the job facade — a consumer never sees an internal code, and this service
+ * never invents a protocol code. `protocol/v1/error-mapping.json` (vendored from
+ * the deploy repo's SSOT) is the machine-checkable half of that contract; the
+ * `retryable` defaults below mirror its `protocol_codes` table, and
+ * `src/__tests__/protocol/contract.test.ts` keeps the two in step.
+ *
+ * Leaf module on purpose: no imports beyond types, so both the scheduler core
+ * and the HTTP facade can use it without a cycle.
+ */
+/** The protocol's closed error enum, verbatim from `$defs/Error` / `protocol_codes`. */
+export type ProtocolErrorCode = 'no_candidate' | 'source_error' | 'auth_error' | 'quota_exceeded' | 'resource_busy' | 'queued_too_long' | 'stalled_no_progress' | 'deadline_exceeded' | 'cancelled_by_consumer' | 'idempotency_conflict' | 'unsupported_protocol_version' | 'invalid_params' | 'delivery_failed' | 'delivery_rejected' | 'delivery_abandoned' | 'internal_error';
+/**
+ * A consumer/operator stop. Internal (`TerminalReasonCode`) and protocol
+ * (`ProtocolErrorCode`) name the same event with the same word, so it is
+ * defined once here — the delivery layer must recognise it without importing
+ * the scheduler.
+ */
+export declare const CANCELLED_BY_CONSUMER = "cancelled_by_consumer";
+/**
+ * `retryable` defaults, copied from `protocol/v1/error-mapping.json`
+ * (`protocol_codes[*].retryable`). A payload may override the flag; it may not
+ * omit it, so a consumer can always branch on it without guessing.
+ */
+export declare const PROTOCOL_ERROR_RETRYABLE: Record<ProtocolErrorCode, boolean>;
+/** `$defs/Error`: `code` is required; everything else is optional. */
+export interface ProtocolErrorBody {
+    code: ProtocolErrorCode;
+    message?: string;
+    retryable?: boolean;
+    detail?: Record<string, unknown>;
+}
+export interface ProtocolErrorOptions {
+    message?: string;
+    detail?: Record<string, unknown>;
+    /** Override the table default (never omit the field: `retryable` is always sent). */
+    retryable?: boolean;
+}
+/** Build a `$defs/Error` body with the protocol's `retryable` default applied. */
+export declare function protocolErrorBody(code: ProtocolErrorCode, options?: ProtocolErrorOptions): ProtocolErrorBody;
+/**
+ * A request that must be answered with a protocol `Error` body.
+ *
+ * `message` is the protocol-visible message (`$defs/Error.message`), NOT an
+ * internal detail: the legacy manual-work endpoints keep matching on a few
+ * stable message strings, so those strings are passed through verbatim here and
+ * the protocol body carries the same text. Nothing may branch on message text
+ * going forward (§5) — the `code` is the contract.
+ */
+export declare class ProtocolRequestError extends Error {
+    readonly status: number;
+    readonly body: ProtocolErrorBody;
+    constructor(code: ProtocolErrorCode, status: number, options?: ProtocolErrorOptions);
+}
+/**
+ * Coerce anything thrown by a handler into an HTTP status + protocol Error body.
+ * Unknown failures become `internal_error` (retryable: false) and never leak the
+ * internal message to the consumer.
+ */
+export declare function protocolErrorResponse(error: unknown): {
+    status: number;
+    body: ProtocolErrorBody;
+};
+//# sourceMappingURL=ProtocolErrors.d.ts.map

package/dist/scheduler/ProtocolErrors.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * The Workflow Protocol v1 error vocabulary, producer side (§5 / §5.1).
+ *
+ * The protocol's error enum is CLOSED. PixivFlow keeps its own, richer internal
+ * `TerminalReasonCode` vocabulary for diagnosis, and translates it exactly once,
+ * at the job facade — a consumer never sees an internal code, and this service
+ * never invents a protocol code. `protocol/v1/error-mapping.json` (vendored from
+ * the deploy repo's SSOT) is the machine-checkable half of that contract; the
+ * `retryable` defaults below mirror its `protocol_codes` table, and
+ * `src/__tests__/protocol/contract.test.ts` keeps the two in step.
+ *
+ * Leaf module on purpose: no imports beyond types, so both the scheduler core
+ * and the HTTP facade can use it without a cycle.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtocolRequestError = exports.PROTOCOL_ERROR_RETRYABLE = exports.CANCELLED_BY_CONSUMER = void 0;
+exports.protocolErrorBody = protocolErrorBody;
+exports.protocolErrorResponse = protocolErrorResponse;
+/**
+ * A consumer/operator stop. Internal (`TerminalReasonCode`) and protocol
+ * (`ProtocolErrorCode`) name the same event with the same word, so it is
+ * defined once here — the delivery layer must recognise it without importing
+ * the scheduler.
+ */
+exports.CANCELLED_BY_CONSUMER = 'cancelled_by_consumer';
+/**
+ * `retryable` defaults, copied from `protocol/v1/error-mapping.json`
+ * (`protocol_codes[*].retryable`). A payload may override the flag; it may not
+ * omit it, so a consumer can always branch on it without guessing.
+ */
+exports.PROTOCOL_ERROR_RETRYABLE = {
+    no_candidate: true,
+    source_error: true,
+    auth_error: false,
+    quota_exceeded: true,
+    resource_busy: true,
+    queued_too_long: true,
+    stalled_no_progress: true,
+    deadline_exceeded: true,
+    cancelled_by_consumer: false,
+    idempotency_conflict: false,
+    unsupported_protocol_version: false,
+    invalid_params: false,
+    delivery_failed: true,
+    delivery_rejected: false,
+    delivery_abandoned: true,
+    internal_error: false,
+};
+/** Build a `$defs/Error` body with the protocol's `retryable` default applied. */
+function protocolErrorBody(code, options = {}) {
+    return {
+        code,
+        ...(options.message !== undefined ? { message: options.message } : {}),
+        retryable: options.retryable ?? exports.PROTOCOL_ERROR_RETRYABLE[code],
+        ...(options.detail !== undefined ? { detail: options.detail } : {}),
+    };
+}
+/**
+ * A request that must be answered with a protocol `Error` body.
+ *
+ * `message` is the protocol-visible message (`$defs/Error.message`), NOT an
+ * internal detail: the legacy manual-work endpoints keep matching on a few
+ * stable message strings, so those strings are passed through verbatim here and
+ * the protocol body carries the same text. Nothing may branch on message text
+ * going forward (§5) — the `code` is the contract.
+ */
+class ProtocolRequestError extends Error {
+    status;
+    body;
+    constructor(code, status, options = {}) {
+        const body = protocolErrorBody(code, options);
+        super(body.message ?? code);
+        this.name = 'ProtocolRequestError';
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.ProtocolRequestError = ProtocolRequestError;
+/**
+ * Coerce anything thrown by a handler into an HTTP status + protocol Error body.
+ * Unknown failures become `internal_error` (retryable: false) and never leak the
+ * internal message to the consumer.
+ */
+function protocolErrorResponse(error) {
+    if (error instanceof ProtocolRequestError) {
+        return { status: error.status, body: error.body };
+    }
+    return {
+        status: 500,
+        body: protocolErrorBody('internal_error', { message: 'internal error' }),
+    };
+}
+//# sourceMappingURL=ProtocolErrors.js.map

package/dist/scheduler/ScheduleTriggerServer.d.ts

@@ -1,5 +1,9 @@
 import { Request } from 'express';
+import { Server } from 'node:http';
 import { SlotContext } from './SlotCoordinator';
+import { JobStatusProjection } from './JobProjection';
+import { ProtocolAckResult, ProtocolCapabilities, ProtocolEventPage, ProtocolJob } from './JobFacade';
+import type { JobEventQuery } from './JobEventStream';
 import { TriggerSource } from './OccurrenceResolver';
 /**
  * Authenticated HTTP schedule trigger — a DISPATCH endpoint, not a run endpoint.
@@ -105,12 +109,12 @@ export interface TriggerHandlers {
         slotId: string;
         disposition: string;
     }>;
-    refetchStatus?(targetId: string, requestId: string): {
-        requestId: string;
-        slotId: string;
-        state: string;
-        slotStatus: string;
-    } | null;
+    /**
+     * Generic Job projection for one manual job. The four legacy identity fields
+     * keep their exact meaning; the rest is additive liveness + terminal-cause
+     * detail (see `JobStatusProjection`). Null means "no such job" -> 404.
+     */
+    refetchStatus?(targetId: string, requestId: string): JobStatusProjection | null;
     /**
      * Admit one manual RECOVERY of a failed target (§manual-recovery). `retryMode`
      * selects a SERVER-DEFINED acquisition policy preset ('normal' | 'relaxed');
@@ -131,6 +135,42 @@ export interface TriggerHandlers {
         /** User-facing copy; never leaks internal error names. */
         message?: string;
     } | null;
+    /**
+     * Optional generic job facade (Workflow Protocol v1). Mounted on the SAME
+     * server and guarded by the SAME refetch token as the manual-work family, so
+     * there is exactly one HTTP system and one execution path: both this generic
+     * surface and the legacy `/internal/targets/:targetId/refetch` shim call the
+     * one shared admission function behind `submitJob`.
+     */
+    jobs?: JobHandlers;
+}
+/**
+ * The producer side of the generic Workflow Protocol v1 surface. Implementations
+ * own all business semantics; the server only authenticates, routes and shapes
+ * the HTTP response. Every failure is thrown as a `ProtocolRequestError` so the
+ * body is always a schema-valid `Error` with a closed-enum `code`.
+ */
+export interface JobHandlers {
+    /** `GET /capabilities` body (`$defs/Capabilities`), derived from live config. */
+    capabilities(): ProtocolCapabilities;
+    /** `POST /jobs`: parse a `$defs/Task`, admit it, project the `$defs/Job`. */
+    submitJob(body: unknown): {
+        job: ProtocolJob;
+        replayed: boolean;
+    };
+    /** `GET /jobs/{job_id}`: null means 404. */
+    jobStatus(jobId: string): ProtocolJob | null;
+    /** `GET /jobs?idempotency_key=`: 0 or 1 job. */
+    jobsByIdempotencyKey(idempotencyKey: string): ProtocolJob[];
+    /** `POST /jobs/{job_id}/cancel`: idempotent; always returns the current job. */
+    cancelJob(jobId: string): ProtocolJob;
+    /** `GET /jobs/{job_id}/events` (`$defs/EventPage`); throws 404 for an unknown job. */
+    jobEvents(jobId: string, query: JobEventQuery): ProtocolEventPage;
+    /**
+     * `POST /jobs/{job_id}/events/ack` (`$defs/AckResult`): monotonic, idempotent,
+     * and never a job mutation. An unknown or older cursor is a no-op.
+     */
+    ackJobEvents(jobId: string, body: unknown): ProtocolAckResult;
 }
 export declare class ScheduleTriggerServer {
     private readonly token;
@@ -140,7 +180,8 @@ export declare class ScheduleTriggerServer {
     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;
+    /** `start` returns the listening server so tests/callers can read the port. */
+    start(host: string, port: number): Server;
     /**
      * Per-request correlation, installed before every route. It records only the
      * sanitized attempt id and the arrival instant, so each later line can report
@@ -165,6 +206,14 @@ export declare class ScheduleTriggerServer {
      * clock did not send them, so an unidentified clock stays visible as such.
      */
     private attemptMeta;
+    /**
+     * Every generic-surface failure is written as a protocol `Error`: a closed-enum
+     * `code`, a `retryable` boolean from the published defaults, and a `detail`
+     * object. Nothing here judges a failure by its message text.
+     */
+    private jobFailure;
+    /** Fail closed when the generic surface is not mounted in this runtime. */
+    private jobUnavailableResponse;
     private auth;
     private refetchAuth;
     private authenticate;