pixivflow 3.1.0 → 3.3.0

package/dist/scheduler/JobFacade.js

@@ -0,0 +1,622 @@
+"use strict";
+/**
+ * The producer-side projection layer of Workflow Protocol v1 (§11.1).
+ *
+ * Everything a consumer sees about a job is built here from the SAME durable
+ * ledger the legacy endpoints read: no second state store, no parallel status
+ * machine, no consumer vocabulary. The projection deliberately speaks only
+ * protocol words — `job_id`, `status`, `progress`, `error` — while the internal
+ * `TerminalReasonCode` is preserved inside `error.detail.internal_code` for
+ * diagnosis and mapped to the closed protocol code at this single site.
+ *
+ * `GET /capabilities` is likewise derived from the live configuration, so a
+ * config change (budget, deadline ceiling) is reflected without a code change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_EVENT_FOR_INTERNAL_KIND = exports.TERMINAL_JOB_EVENT_KINDS = exports.JOB_EVENT_KINDS = exports.PROTOCOL_EVENT_TYPES = exports.PROTOCOL_VERSIONS = exports.JOB_TYPE_CANDIDATE_SEARCH = void 0;
+exports.protocolJobStatus = protocolJobStatus;
+exports.protocolProgressStage = protocolProgressStage;
+exports.buildProtocolJob = buildProtocolJob;
+exports.resolveDeadlineMs = resolveDeadlineMs;
+exports.resolveDefaultDeadlineMs = resolveDefaultDeadlineMs;
+exports.parseTaskBody = parseTaskBody;
+exports.buildCapabilities = buildCapabilities;
+exports.terminalJobEventKind = terminalJobEventKind;
+exports.projectedInternalKinds = projectedInternalKinds;
+exports.isProjectedInternalKind = isProjectedInternalKind;
+exports.protocolEventTypeFor = protocolEventTypeFor;
+exports.protocolEventId = protocolEventId;
+exports.parseProtocolEventId = parseProtocolEventId;
+exports.buildProtocolEvent = buildProtocolEvent;
+exports.buildEventPage = buildEventPage;
+exports.buildAckResult = buildAckResult;
+exports.parseAckBody = parseAckBody;
+exports.parseEventQuery = parseEventQuery;
+const logger_1 = require("../logger");
+const CandidateSearchParams_1 = require("./CandidateSearchParams");
+const ProtocolErrors_1 = require("./ProtocolErrors");
+const Scheduler_1 = require("./Scheduler");
+const SlotCoordinator_1 = require("./SlotCoordinator");
+const StallSweep_1 = require("./StallSweep");
+const TargetOutcome_1 = require("./TargetOutcome");
+/** Bounds that keep one request from becoming an unbounded allocation. */
+const MAX_IDEMPOTENCY_KEY_LENGTH = 200;
+const MAX_CORRELATION_ID_LENGTH = 200;
+const MAX_CALLBACK_URL_LENGTH = 2000;
+const MAX_TAG_LENGTH = 100;
+const MAX_TAGS = 20;
+const MAX_EXCLUSIONS = 100;
+/** The only job type this producer serves today. */
+exports.JOB_TYPE_CANDIDATE_SEARCH = 'candidate_search';
+/** `$defs/ProtocolVersion` — this producer speaks exactly one version. */
+exports.PROTOCOL_VERSIONS = ['1'];
+/**
+ * Classify the durable cell state.
+ *
+ * The CELL is the truth: it is the unit that executes and the unit the manual
+ * surface submits. Budget verdicts (`queued_too_long`, `stalled_no_heartbeat`,
+ * `execution_timeout`) end as protocol `expired` per §4 — they describe a lost
+ * liveness, not a Pixiv failure — while a consumer cancel is `cancelled`.
+ */
+function protocolJobStatus(projection) {
+    const cell = projection.state;
+    if (cell === 'submitted')
+        return 'succeeded';
+    if (cell === 'pending')
+        return 'queued';
+    if (cell === 'selected' || cell === 'artifact_ready' || cell === 'delivery_pending') {
+        return 'running';
+    }
+    const reason = projection.terminalReasonCode;
+    if (reason === 'cancelled_by_consumer')
+        return 'cancelled';
+    if (projection.slotStatus === 'expired' ||
+        reason === 'queued_too_long' ||
+        reason === 'stalled_no_heartbeat' ||
+        reason === 'execution_timeout') {
+        return 'expired';
+    }
+    return 'failed';
+}
+/** The protocol-visible stage label for a job status (§2 `Progress.stage`). */
+function protocolProgressStage(status, cellStatus) {
+    switch (status) {
+        case 'queued':
+            return 'queued';
+        case 'running':
+            return cellStatus === 'selected' ? 'searching' : 'delivering';
+        case 'succeeded':
+            return 'done';
+        default:
+            return status;
+    }
+}
+/** `$defs/Candidate.work_type` is a closed enum; anything else is `unknown`. */
+function protocolWorkType(workType) {
+    return workType === 'illustration' || workType === 'novel' ? workType : 'unknown';
+}
+/**
+ * Build the `$defs/Job` body for one job.
+ *
+ * A terminal job always carries `result` or `error` (§4). The result is built
+ * from what the ledger actually knows — the delivered work item and the
+ * persisted supply counts — never from a re-derived guestimate: `filtered` is
+ * omitted because per-work rejection reasons are not persisted (only counts).
+ */
+function buildProtocolJob(input) {
+    const now = input.now ?? Date.now();
+    const projection = input.projection;
+    const status = protocolJobStatus(projection);
+    const created = projection.createdAt ?? now;
+    const updated = projection.updatedAt ?? created;
+    const job = {
+        protocol_version: '1',
+        job_id: projection.slotId,
+        job_type: input.jobType ?? exports.JOB_TYPE_CANDIDATE_SEARCH,
+        status,
+        created_at: created,
+        updated_at: updated,
+        started_at: projection.startedAt,
+        heartbeat_at: projection.heartbeatAt,
+        deadline_at: input.deadlineAt ?? null,
+        lease_active: projection.leaseActive,
+        lease_expires_at: projection.leaseExpiresAt,
+        attempt: projection.attemptCount,
+        progress: {
+            stage: protocolProgressStage(status, projection.state),
+            at: updated,
+        },
+    };
+    if (projection.idempotencyKey)
+        job.idempotency_key = projection.idempotencyKey;
+    if (projection.correlationId)
+        job.correlation_id = projection.correlationId;
+    job.events_url = `/jobs/${job.job_id}/events`;
+    if (status === 'succeeded') {
+        job.result = buildCandidateSearchResult(input.delivered ?? null, input.supply ?? null);
+    }
+    else if (status === 'failed' || status === 'cancelled' || status === 'expired') {
+        const internal = projection.terminalReasonCode;
+        const code = (0, TargetOutcome_1.protocolErrorCodeForTerminalReason)(internal) ?? 'internal_error';
+        job.error = (0, ProtocolErrors_1.protocolErrorBody)(code, {
+            ...(projection.terminalReasonMessage ? { message: projection.terminalReasonMessage } : {}),
+            detail: internal ? { internal_code: internal } : undefined,
+        });
+    }
+    return job;
+}
+/**
+ * `$defs/Result_CandidateSearch` from the durable outcome.
+ *
+ * `scanned` is the persisted pre-filter count (`fetched`); when the ledger has
+ * no supply report the delivered candidate count is the only honest lower
+ * bound.
+ */
+function buildCandidateSearchResult(delivered, supply) {
+    const candidates = [];
+    if (delivered?.workId) {
+        candidates.push({
+            candidate_id: delivered.workId,
+            platform: 'pixiv',
+            work_id: delivered.workId,
+            work_type: protocolWorkType(delivered.workType),
+        });
+    }
+    return { candidates, scanned: supply?.fetched ?? candidates.length };
+}
+/**
+ * The execution ceiling this deployment enforces for one schedule's work:
+ * the plan's configured `timeout`, else the scheduler-wide default.
+ */
+function resolveDeadlineMs(config, scheduleId) {
+    const plan = (config.schedules ?? []).find((item) => item.id === scheduleId);
+    const timeout = plan?.timeout;
+    return typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0
+        ? timeout
+        : Scheduler_1.DEFAULT_SCHEDULE_TIMEOUT_MS;
+}
+/**
+ * The declared `default_deadline_ms`: the widest ceiling any enabled plan
+ * grants, so the declaration never promises more time than config allows, and
+ * never less than a plan that does grant it.
+ */
+function resolveDefaultDeadlineMs(config) {
+    const declared = (config.schedules ?? [])
+        .filter((plan) => plan.enabled !== false)
+        .map((plan) => plan.timeout)
+        .filter((timeout) => typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0);
+    return declared.length > 0 ? Math.max(...declared) : Scheduler_1.DEFAULT_SCHEDULE_TIMEOUT_MS;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function invalid(message, detail) {
+    return new ProtocolErrors_1.ProtocolRequestError('invalid_params', 400, { message, detail });
+}
+/**
+ * Parse and validate a `$defs/Task` body (§2/§3).
+ *
+ * Strict about the documented fields — a wrong type or an out-of-range value is
+ * a 400 `invalid_params`, never a silently coerced default — and deliberately
+ * tolerant about unknown keys, which §3 requires to be ignored so a newer
+ * consumer can talk to an older producer.
+ *
+ * `protocol_version` is judged by kind: absent is a malformed request
+ * (`invalid_params`), present-but-different is a version mismatch
+ * (`unsupported_protocol_version`). `job_type` uses `invalid_params`; the
+ * published error enum has no `unsupported_job_type` member and this producer
+ * does not invent protocol codes.
+ */
+function parseTaskBody(body) {
+    if (!isPlainObject(body)) {
+        throw invalid('body must be a JSON object');
+    }
+    const version = body.protocol_version;
+    if (version === undefined || version === null) {
+        throw invalid('protocol_version is required');
+    }
+    if (version !== exports.PROTOCOL_VERSIONS[0]) {
+        throw new ProtocolErrors_1.ProtocolRequestError('unsupported_protocol_version', 400, {
+            message: `unsupported protocol_version ${JSON.stringify(version)}`,
+            detail: { received: version, supported: [...exports.PROTOCOL_VERSIONS] },
+        });
+    }
+    if (body.job_type !== exports.JOB_TYPE_CANDIDATE_SEARCH) {
+        throw invalid(`unsupported job_type ${JSON.stringify(body.job_type ?? null)}`, {
+            reason: 'unsupported_job_type',
+            job_type: body.job_type ?? null,
+            supported: [exports.JOB_TYPE_CANDIDATE_SEARCH],
+        });
+    }
+    const rawKey = body.idempotency_key;
+    if (typeof rawKey !== 'string' || rawKey.trim() === '') {
+        throw invalid('idempotency_key must be a non-empty string');
+    }
+    const idempotencyKey = rawKey.trim();
+    if (idempotencyKey.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+        throw invalid(`idempotency_key must be at most ${MAX_IDEMPOTENCY_KEY_LENGTH} characters`);
+    }
+    let correlationId;
+    if (body.correlation_id !== undefined && body.correlation_id !== null) {
+        if (typeof body.correlation_id !== 'string' || body.correlation_id.length > MAX_CORRELATION_ID_LENGTH) {
+            throw invalid(`correlation_id must be a string of at most ${MAX_CORRELATION_ID_LENGTH} chars`);
+        }
+        correlationId = body.correlation_id;
+    }
+    let callbackUrl;
+    if (body.callback_url !== undefined && body.callback_url !== null) {
+        if (typeof body.callback_url !== 'string' || body.callback_url.length > MAX_CALLBACK_URL_LENGTH) {
+            throw invalid(`callback_url must be a string of at most ${MAX_CALLBACK_URL_LENGTH} chars`);
+        }
+        callbackUrl = body.callback_url;
+    }
+    let deadlineMs;
+    if (body.deadline_ms !== undefined && body.deadline_ms !== null) {
+        if (!Number.isInteger(body.deadline_ms) || body.deadline_ms < 1000) {
+            throw invalid('deadline_ms must be an integer of at least 1000 ms');
+        }
+        deadlineMs = body.deadline_ms;
+    }
+    if (body.labels !== undefined && body.labels !== null) {
+        if (!isPlainObject(body.labels)) {
+            throw invalid('labels must be an object of strings');
+        }
+        for (const [name, value] of Object.entries(body.labels)) {
+            if (typeof value !== 'string') {
+                throw invalid(`labels.${name} must be a string`);
+            }
+        }
+    }
+    const params = parseCandidateSearchParams(body.params);
+    return {
+        idempotencyKey,
+        ...(correlationId !== undefined ? { correlationId } : {}),
+        ...(params.source?.account !== undefined ? { account: params.source.account } : {}),
+        params,
+        ...(deadlineMs !== undefined ? { deadlineMs } : {}),
+        ...(callbackUrl !== undefined ? { callbackUrl } : {}),
+    };
+}
+/** `$defs/CandidateSearchParams`, validated field by field. */
+function parseCandidateSearchParams(raw) {
+    if (!isPlainObject(raw)) {
+        throw invalid('params must be a JSON object');
+    }
+    let source;
+    if (raw.source !== undefined && raw.source !== null) {
+        if (!isPlainObject(raw.source)) {
+            throw invalid('params.source must be a JSON object');
+        }
+        const platform = raw.source.platform;
+        if (platform !== undefined && platform !== null && platform !== 'pixiv') {
+            throw invalid(`params.source.platform must be 'pixiv'`, { received: platform });
+        }
+        const account = raw.source.account;
+        if (account !== undefined && account !== null) {
+            if (typeof account !== 'string' || account.trim() === '' || account.length > MAX_TAG_LENGTH) {
+                throw invalid('params.source.account must be a non-empty string');
+            }
+            source = { ...(platform === 'pixiv' ? { platform } : {}), account };
+        }
+        else if (platform === 'pixiv') {
+            source = { platform };
+        }
+    }
+    const query = raw.query;
+    if (!isPlainObject(query)) {
+        throw invalid('params.query must be a JSON object');
+    }
+    const tags = query.tags;
+    if (!Array.isArray(tags) || tags.length === 0) {
+        throw invalid('params.query.tags must be a non-empty array of strings');
+    }
+    if (tags.length > MAX_TAGS) {
+        throw invalid(`params.query.tags must contain at most ${MAX_TAGS} tags`);
+    }
+    for (const tag of tags) {
+        if (typeof tag !== 'string' || tag.trim() === '' || tag.length > MAX_TAG_LENGTH) {
+            throw invalid('params.query.tags must be a non-empty array of strings');
+        }
+    }
+    if (query.expand !== undefined && query.expand !== null && typeof query.expand !== 'boolean') {
+        throw invalid('params.query.expand must be a boolean');
+    }
+    const constraints = parseConstraints(raw.constraints);
+    return {
+        ...(source !== undefined ? { source } : {}),
+        query: {
+            tags: tags.map((tag) => tag.trim()),
+            ...(query.expand === true ? { expand: true } : {}),
+        },
+        ...(constraints !== undefined ? { constraints } : {}),
+    };
+}
+function parseConstraints(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isPlainObject(raw)) {
+        throw invalid('params.constraints must be a JSON object');
+    }
+    let exclude;
+    if (raw.exclude !== undefined && raw.exclude !== null) {
+        if (!Array.isArray(raw.exclude) || raw.exclude.length > MAX_EXCLUSIONS) {
+            throw invalid(`params.constraints.exclude must be an array of at most ${MAX_EXCLUSIONS} items`);
+        }
+        exclude = raw.exclude.map((entry) => {
+            if (!isPlainObject(entry) || !['work', 'candidate', 'tag'].includes(String(entry.kind))) {
+                throw invalid('params.constraints.exclude[].kind must be one of work, candidate, tag');
+            }
+            if (typeof entry.id !== 'string' || entry.id.trim() === '' || entry.id.length > MAX_TAG_LENGTH) {
+                throw invalid('params.constraints.exclude[].id must be a non-empty string');
+            }
+            return { kind: entry.kind, id: entry.id.trim() };
+        });
+    }
+    const limit = parsePositiveInteger(raw.limit, 'params.constraints.limit');
+    const scanLimit = parsePositiveInteger(raw.scan_limit, 'params.constraints.scan_limit');
+    let workTypes;
+    if (raw.work_types !== undefined && raw.work_types !== null) {
+        if (!Array.isArray(raw.work_types) || raw.work_types.some((type) => typeof type !== 'string' || type === '')) {
+            throw invalid('params.constraints.work_types must be an array of non-empty strings');
+        }
+        workTypes = [...raw.work_types];
+    }
+    return {
+        ...(exclude !== undefined ? { exclude } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(scanLimit !== undefined ? { scan_limit: Math.min(scanLimit, CandidateSearchParams_1.CANDIDATE_SEARCH_SCAN_LIMIT_MAX) } : {}),
+        ...(workTypes !== undefined ? { work_types: workTypes } : {}),
+    };
+}
+function parsePositiveInteger(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Number.isInteger(value) || value < 1) {
+        throw invalid(`${name} must be an integer of at least 1`);
+    }
+    return value;
+}
+/**
+ * `$defs/Capabilities`, derived from the live configuration: change a budget in
+ * config and this declaration follows without a code change.
+ */
+function buildCapabilities(config, now = Date.now()) {
+    const budgets = (0, StallSweep_1.resolveStallTimeouts)(config.schedulerRuntime);
+    return {
+        protocol_versions: [...exports.PROTOCOL_VERSIONS],
+        job_types: [
+            {
+                name: exports.JOB_TYPE_CANDIDATE_SEARCH,
+                params_schema: '#/$defs/CandidateSearchParams',
+                result_schema: '#/$defs/Result_CandidateSearch',
+                // Honest feature list. `exclude` and `tag_expansion` are real: the
+                // occurrence-scoped retrieval view applies `constraints.exclude` and
+                // `query.expand`. `events` is real too: `GET /jobs/:id/events` serves the
+                // durable stream and `POST /jobs/:id/events/ack` persists the cursor
+                // (`src/scheduler/JobEventStream.ts`), and a Task's `callback_url`
+                // receives `$defs/Event` bodies through the existing outbox.
+                features: ['events', 'progress', 'cancel', 'idempotency', 'exclude', 'tag_expansion'],
+                queued_timeout_ms: budgets.queuedTimeoutMs,
+                stall_timeout_ms: budgets.stallTimeoutMs,
+                heartbeat_interval_ms: SlotCoordinator_1.SLOT_HEARTBEAT_MS,
+                default_deadline_ms: resolveDefaultDeadlineMs(config),
+            },
+        ],
+        server_time: now,
+    };
+}
+// ---------------------------------------------------------------------------
+// The event stream (§events)
+//
+// Same durable log, protocol vocabulary. `delivery_events` already records every
+// lifecycle step; this section is the ONE place that decides which internal
+// kinds a consumer may see and what they are called. Nothing here invents state:
+// an event exists only because a durable row exists.
+// ---------------------------------------------------------------------------
+exports.PROTOCOL_EVENT_TYPES = [
+    'job.accepted',
+    'job.started',
+    'job.progress',
+    'job.succeeded',
+    'job.failed',
+    'job.expired',
+    'job.cancelled',
+];
+/**
+ * The internal job-lifecycle kinds PixivFlow persists for a job. They are
+ * deliberately NOT spelled like the protocol enum: the translation is a
+ * decision made here, never a string passthrough.
+ */
+exports.JOB_EVENT_KINDS = [
+    'job.requested',
+    'job.execution_started',
+    'job.progressed',
+    'job.outcome_succeeded',
+    'job.outcome_failed',
+    'job.outcome_expired',
+    'job.outcome_cancelled',
+];
+exports.TERMINAL_JOB_EVENT_KINDS = [
+    'job.outcome_succeeded',
+    'job.outcome_failed',
+    'job.outcome_expired',
+    'job.outcome_cancelled',
+];
+/** Protocol type for one durable terminal job status. */
+const TERMINAL_EVENT_FOR_STATUS = {
+    succeeded: 'job.outcome_succeeded',
+    failed: 'job.outcome_failed',
+    expired: 'job.outcome_expired',
+    cancelled: 'job.outcome_cancelled',
+};
+/** The internal kind that materialises the terminal event of a finished job. */
+function terminalJobEventKind(status) {
+    if (status === 'succeeded' || status === 'failed' || status === 'expired' || status === 'cancelled') {
+        return TERMINAL_EVENT_FOR_STATUS[status];
+    }
+    return null;
+}
+/**
+ * The ONE mapping from durable internal kinds to protocol event types.
+ *
+ * `null` means internal-only: the row stays in `delivery_events` for operators
+ * and `runs show`, and never reaches a consumer. Any kind absent from this map
+ * is DROPPED with a warning — an internal kind can never become an unknown
+ * protocol type by accident. The intersection type below makes the mapping
+ * exhaustive over `JobEventKind` at compile time, so adding a new lifecycle kind
+ * without mapping it fails `tsc` instead of shipping.
+ */
+exports.PROTOCOL_EVENT_FOR_INTERNAL_KIND = {
+    'job.requested': 'job.accepted',
+    'job.execution_started': 'job.started',
+    'job.progressed': 'job.progress',
+    'job.outcome_succeeded': 'job.succeeded',
+    'job.outcome_failed': 'job.failed',
+    'job.outcome_expired': 'job.expired',
+    'job.outcome_cancelled': 'job.cancelled',
+    // Internal-only: outbox/ledger telemetry that happens to carry a slot_id.
+    'execution.summary': null,
+    'delivery.duplicate': null,
+    'media.fallback': null,
+    'outbox.claimed': null,
+    'outbox.deferred': null,
+    'outbox.delivered': null,
+    'outbox.retry_scheduled': null,
+    'outbox.dead': null,
+    'outbox.cancelled': null,
+    'outbox.replay_requested': null,
+};
+/**
+ * The internal kinds a consumer is allowed to see. Callers use this as the SQL
+ * filter so `unacked` can never be pinned by rows that are not projectable.
+ */
+function projectedInternalKinds() {
+    return Object.keys(exports.PROTOCOL_EVENT_FOR_INTERNAL_KIND).filter((kind) => exports.PROTOCOL_EVENT_FOR_INTERNAL_KIND[kind] !== null);
+}
+/** True when an internal kind is visible to consumers (has a protocol type). */
+function isProjectedInternalKind(internalKind) {
+    return (Object.prototype.hasOwnProperty.call(exports.PROTOCOL_EVENT_FOR_INTERNAL_KIND, internalKind) &&
+        exports.PROTOCOL_EVENT_FOR_INTERNAL_KIND[internalKind] !== null);
+}
+/** Map one internal kind to its protocol type; null when internal-only. */
+function protocolEventTypeFor(internalKind) {
+    if (!Object.prototype.hasOwnProperty.call(exports.PROTOCOL_EVENT_FOR_INTERNAL_KIND, internalKind)) {
+        logger_1.logger.warn('Unmapped internal event kind dropped from the protocol event stream', {
+            event: internalKind,
+        });
+        return null;
+    }
+    return exports.PROTOCOL_EVENT_FOR_INTERNAL_KIND[internalKind];
+}
+/** `evt-<at>-<row id>`: opaque, unique, and resolvable back to the row. */
+function protocolEventId(at, rowId) {
+    return `evt-${at}-${rowId}`;
+}
+/** Resolve an opaque event_id to a durable position; null when unrecognised. */
+function parseProtocolEventId(value) {
+    const match = /^evt-(\d+)-(\d+)$/.exec(value);
+    if (!match)
+        return null;
+    return { at: Number(match[1]), rowId: Number(match[2]) };
+}
+/** Build one protocol event, or null when the internal kind is internal-only. */
+function buildProtocolEvent(input) {
+    const type = protocolEventTypeFor(input.source.internalKind);
+    if (!type)
+        return null;
+    const payload = {
+        detail: { internal_kind: input.source.internalKind },
+    };
+    // Terminal events carry the outcome, exactly like the vendored fixtures:
+    // `event.job.succeeded` carries `payload.job` + `payload.result`, and
+    // `event.job.expired` carries `payload.job` + `payload.error`.
+    const job = input.job ?? null;
+    if (type === 'job.succeeded' || type === 'job.failed' || type === 'job.expired' || type === 'job.cancelled') {
+        payload.job = job;
+        if (type === 'job.succeeded')
+            payload.result = job?.result ?? null;
+        else
+            payload.error = job?.error ?? null;
+    }
+    const event = {
+        protocol_version: '1',
+        event_id: protocolEventId(input.source.at, input.source.rowId),
+        job_id: input.jobId,
+        type,
+        at: input.source.at,
+        payload,
+    };
+    if (input.correlationId)
+        event.correlation_id = input.correlationId;
+    return event;
+}
+/**
+ * `$defs/EventPage` from durable rows. `events` is ordered by `at` (then by the
+ * durable row order, which is the same order because writers never move `at`
+ * backwards).
+ */
+function buildEventPage(input) {
+    const events = [];
+    for (const source of input.sources) {
+        const event = buildProtocolEvent({
+            jobId: input.jobId,
+            source,
+            job: input.job ?? null,
+            correlationId: input.correlationId ?? null,
+        });
+        if (event)
+            events.push(event);
+    }
+    const page = {
+        job_id: input.jobId,
+        events,
+        unacked: Math.max(0, input.unacked),
+        server_time: input.serverTime,
+    };
+    const last = events[events.length - 1];
+    if (input.hasMore && last)
+        page.next_after = last.event_id;
+    return page;
+}
+/** `$defs/AckResult` from the durable cursor. */
+function buildAckResult(input) {
+    return {
+        job_id: input.jobId,
+        acked: Math.max(0, input.acked),
+        unacked: Math.max(0, input.unacked),
+        server_time: input.serverTime,
+    };
+}
+/** `$defs/AckRequest`. */
+function parseAckBody(body) {
+    if (!isPlainObject(body))
+        throw invalid('request body must be a JSON object');
+    const ackThrough = body.ack_through;
+    if (typeof ackThrough !== 'string' || ackThrough.length === 0) {
+        throw invalid('ack_through is required', { field: 'ack_through' });
+    }
+    return { ackThrough };
+}
+/** Query parameters of `GET /jobs/:jobId/events`. */
+function parseEventQuery(query) {
+    const raw = query.after;
+    let after = null;
+    if (raw !== undefined && raw !== null) {
+        if (typeof raw !== 'string' || raw.length === 0) {
+            throw invalid('after must be a non-empty event_id', { field: 'after' });
+        }
+        after = raw;
+    }
+    const rawUnacked = query.unacked;
+    let unackedOnly = false;
+    if (rawUnacked !== undefined && rawUnacked !== null && rawUnacked !== '') {
+        const value = String(rawUnacked);
+        if (value === '1' || value === 'true')
+            unackedOnly = true;
+        else if (value !== '0' && value !== 'false') {
+            throw invalid('unacked must be 1 or 0', { field: 'unacked' });
+        }
+    }
+    return { after, unackedOnly };
+}
+//# sourceMappingURL=JobFacade.js.map

package/dist/scheduler/JobProjection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The generic Job projection (§liveness).
+ *
+ * One durable Slot cell, described in terms a consumer can act on WITHOUT
+ * knowing this service's internal column names, table layout or scheduler
+ * topology. This is the body a job-status endpoint returns; the manual-refetch
+ * GET endpoint is the first such consumer (and declares the legacy
+ * `requestId`/`slotId`/`state`/`slotStatus` aliases on top of it).
+ *
+ * Why the extra fields exist: a caller that receives only a coarse state cannot
+ * tell "queued two seconds ago" from "pending for three days behind a stopped
+ * scheduler", so it cannot implement a heartbeat-based watchdog — it can only
+ * poll forever. Timestamps + lease liveness + attempt count make the difference
+ * decidable, and `terminalReasonCode`/`terminalReasonMessage` give the
+ * first-level cause once the job is terminal.
+ *
+ * Timestamp normalisation (the columns do NOT share one shape):
+ *  - `schedule_slots.created_at` / `started_at` and
+ *    `schedule_slot_items.updated_at` are SQLite `CURRENT_TIMESTAMP` UTC
+ *    datetimes without a zone marker -> parsed as UTC (see `ledger-time`).
+ *  - `schedule_slots.heartbeat_at` / `lease_until` are already epoch ms.
+ *  - Every timestamp in this projection is epoch milliseconds UTC, or null when
+ *    the ledger has no such instant.
+ */
+import type { SlotItemRecord, SlotRecord } from '../storage/repositories/SlotRepository';
+export interface JobStatusProjection {
+    /** The caller's own request id, echoed back. */
+    requestId: string;
+    slotId: string;
+    /** Cell state from the Slot FSM (pending|selected|artifact_ready|delivery_pending|submitted|no_candidate|duplicate|failed). */
+    state: string;
+    /** Rolled-up Slot status (pending|running|success|partial|failed|expired). */
+    slotStatus: string;
+    createdAt: number | null;
+    /** When a worker first marked the slot running. */
+    startedAt: number | null;
+    /** Last cell update: the freshest durable progress signal for this target. */
+    updatedAt: number | null;
+    /** Last lease heartbeat written by the owning run. */
+    heartbeatAt: number | null;
+    /** When the current lease expires (null when nobody holds one). */
+    leaseExpiresAt: number | null;
+    /** A lease is held AND unexpired: some run owns this slot right now. */
+    leaseActive: boolean;
+    /** The slot left `pending` (claimed by a run or already terminal). */
+    claimed: boolean;
+    /** Delivery/execution attempts recorded on this cell. */
+    attemptCount: number;
+    terminalReasonCode: string | null;
+    terminalReasonMessage: string | null;
+    /** Internal name of the request that opened this job. */
+    manualRequestId: string | null;
+    /**
+     * Consumer-facing opaque key for the same request. A consumer groups work by
+     * this value and never needs to learn the column it came from.
+     */
+    idempotencyKey: string | null;
+    /** Opaque caller correlation (review chain / review id). */
+    correlationId: string | null;
+}
+/**
+ * Project one (slot, cell) pair. Pure: no clock reads beyond the injectable
+ * `now`, so the same ledger row always projects the same way for a given
+ * instant.
+ */
+export declare function buildJobProjection(requestId: string, slot: SlotRecord, cell: SlotItemRecord, now?: number): JobStatusProjection;
+//# sourceMappingURL=JobProjection.d.ts.map