@semiont/jobs 0.6.7 → 0.6.9

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { JobId, UserId, UnitCursor, ResourceId, EntityType, JobReferenceAnnotationResult, GenerationJobParams, JobHighlightAnnotationResult, JobAssessmentAnnotationResult, JobCommentAnnotationResult, TagSchema, JobTagAnnotationResult, Logger, EventBus, components, Annotation, SupportedMediaType, GatheredContext, EventMap } from '@semiont/core';
-import { SemiontState } from '@semiont/core/node';
+import { JobId, components, UserId, UnitCursor, ResourceId, EntityType, JobReferenceAnnotationResult, GenerationJobParams, JobHighlightAnnotationResult, JobAssessmentAnnotationResult, JobCommentAnnotationResult, TagSchema, JobTagAnnotationResult, Annotation, Logger, SupportedMediaType, GatheredContext, JobType as JobType$1, EventMap, BusRequestErrorCode, BusRequestPrimitive } from '@semiont/core';
 import { InferenceClient } from '@semiont/inference';
+import { Observable } from 'rxjs';
 
 /**
  * Job Queue Type Definitions - Discriminated Union Design
@@ -15,8 +15,8 @@ import { InferenceClient } from '@semiont/inference';
  * - State machine is explicit and type-safe
  */
 
-type JobType = 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-type JobStatus = 'pending' | 'running' | 'complete' | 'failed' | 'cancelled';
+type JobType = components['schemas']['JobType'];
+type JobStatus = components['schemas']['Job']['status'];
 /**
  * Job metadata - common to all states
  */
@@ -80,7 +80,7 @@ interface JobMetadata {
 /**
  * Detection job parameters
  */
-interface DetectionParams {
+type DetectionParams = {
     resourceId: ResourceId;
     entityTypes: EntityType[];
     includeDescriptiveReferences?: boolean;
@@ -88,21 +88,21 @@ interface DetectionParams {
     language?: string;
     /** Source-resource locale — see locale conventions above. */
     sourceLanguage?: string;
-}
+};
 /**
  * Highlight detection job parameters
  */
-interface HighlightDetectionParams {
+type HighlightDetectionParams = {
     resourceId: ResourceId;
     instructions?: string;
     density?: number;
     /** Source-resource locale — see locale conventions above. */
     sourceLanguage?: string;
-}
+};
 /**
  * Assessment detection job parameters
  */
-interface AssessmentDetectionParams {
+type AssessmentDetectionParams = {
     resourceId: ResourceId;
     instructions?: string;
     tone?: 'analytical' | 'critical' | 'balanced' | 'constructive';
@@ -111,11 +111,11 @@ interface AssessmentDetectionParams {
     language?: string;
     /** Source-resource locale — see locale conventions above. */
     sourceLanguage?: string;
-}
+};
 /**
  * Comment detection job parameters
  */
-interface CommentDetectionParams {
+type CommentDetectionParams = {
     resourceId: ResourceId;
     instructions?: string;
     tone?: 'scholarly' | 'explanatory' | 'conversational' | 'technical';
@@ -124,7 +124,7 @@ interface CommentDetectionParams {
     language?: string;
     /** Source-resource locale — see locale conventions above. */
     sourceLanguage?: string;
-}
+};
 /**
  * Tag detection job parameters.
  *
@@ -133,7 +133,7 @@ interface CommentDetectionParams {
  * at job-creation time and embeds the resolved schema here, keeping the
  * worker independent of the registry.
  */
-interface TagDetectionParams {
+type TagDetectionParams = {
     resourceId: ResourceId;
     schema: TagSchema;
     categories: string[];
@@ -141,70 +141,13 @@ interface TagDetectionParams {
     language?: string;
     /** Source-resource locale — see locale conventions above. */
     sourceLanguage?: string;
-}
-/**
- * Detection job progress
- */
-interface DetectionProgress {
-    totalEntityTypes: number;
-    processedEntityTypes: number;
-    entitiesFound: number;
-    entitiesEmitted: number;
-}
-/**
- * Generation job progress
- */
-interface YieldProgress {
-    /** The two real generation transitions — LLM call running, then persisting. */
-    stage: 'generating' | 'creating';
-    percentage: number;
-    message?: string;
-}
-/**
- * Generation job result
- */
-interface GenerationResult {
-    kind: 'generation';
-    resourceId: ResourceId;
-    resourceName: string;
-    /** True when the model stopped at the maxTokens ceiling — the artifact is cut off, not complete (GENERATE-FROM-RESOURCE D6). */
-    truncated: boolean;
-}
-/**
- * Highlight detection job progress
- */
-interface HighlightDetectionProgress {
-    stage: 'analyzing' | 'creating';
-    percentage: number;
-    message?: string;
-}
-/**
- * Assessment detection job progress
- */
-interface AssessmentDetectionProgress {
-    stage: 'analyzing' | 'creating';
-    percentage: number;
-    message?: string;
-}
-/**
- * Comment detection job progress
- */
-interface CommentDetectionProgress {
-    stage: 'analyzing' | 'creating';
-    percentage: number;
-    message?: string;
-}
+};
 /**
- * Tag detection job progress
+ * The progress a running job carries: the last its worker reported with
+ * `job:report-progress`, or an empty object before the first report. One shape
+ * for every job type, as the spec states it (JobRunning).
  */
-interface TagDetectionProgress {
-    stage: 'analyzing' | 'creating';
-    percentage: number;
-    currentCategory?: string;
-    processedCategories: number;
-    totalCategories: number;
-    message?: string;
-}
+type StoredProgress = components['schemas']['JobStoredProgress'];
 /**
  * Pending job - just created, waiting to be picked up
  */
@@ -216,12 +159,12 @@ interface PendingJob<P> {
 /**
  * Running job - actively being processed
  */
-interface RunningJob<P, PG> {
+interface RunningJob<P> {
     status: 'running';
     metadata: JobMetadata;
     params: P;
     startedAt: string;
-    progress: PG;
+    progress: StoredProgress;
 }
 /**
  * Complete job - successfully finished
@@ -258,464 +201,29 @@ interface CancelledJob<P> {
 /**
  * Generic job - discriminated union of all states
  */
-type Job<P, PG, R> = PendingJob<P> | RunningJob<P, PG> | CompleteJob<P, R> | FailedJob<P> | CancelledJob<P>;
-type DetectionJob = Job<DetectionParams, DetectionProgress, JobReferenceAnnotationResult>;
-type GenerationJob = Job<GenerationJobParams, YieldProgress, GenerationResult>;
-type HighlightDetectionJob = Job<HighlightDetectionParams, HighlightDetectionProgress, JobHighlightAnnotationResult>;
-type AssessmentDetectionJob = Job<AssessmentDetectionParams, AssessmentDetectionProgress, JobAssessmentAnnotationResult>;
-type CommentDetectionJob = Job<CommentDetectionParams, CommentDetectionProgress, JobCommentAnnotationResult>;
-type TagDetectionJob = Job<TagDetectionParams, TagDetectionProgress, JobTagAnnotationResult>;
+type Job<P, R> = PendingJob<P> | RunningJob<P> | CompleteJob<P, R> | FailedJob<P> | CancelledJob<P>;
+type DetectionJob = Job<DetectionParams, JobReferenceAnnotationResult>;
+/** A generation job's params carry the resource the dispatcher derived from the context's focus. */
+type GenerationJob = Job<GenerationJobParams & {
+    resourceId: ResourceId;
+}, components['schemas']['JobGenerationResult']>;
+type HighlightDetectionJob = Job<HighlightDetectionParams, JobHighlightAnnotationResult>;
+type AssessmentDetectionJob = Job<AssessmentDetectionParams, JobAssessmentAnnotationResult>;
+type CommentDetectionJob = Job<CommentDetectionParams, JobCommentAnnotationResult>;
+type TagDetectionJob = Job<TagDetectionParams, JobTagAnnotationResult>;
 /**
  * Discriminated union of all job types
  */
 type AnyJob = DetectionJob | GenerationJob | HighlightDetectionJob | AssessmentDetectionJob | CommentDetectionJob | TagDetectionJob;
+/** A job of any type, running: what a claim returns. */
+type RunningAnyJob = Extract<AnyJob, {
+    status: 'running';
+}>;
 declare function isPendingJob(job: AnyJob): job is PendingJob<any>;
-declare function isRunningJob(job: AnyJob): job is RunningJob<any, any>;
+declare function isRunningJob(job: AnyJob): job is RunningJob<any>;
 declare function isCompleteJob(job: AnyJob): job is CompleteJob<any, any>;
 declare function isFailedJob(job: AnyJob): job is FailedJob<any>;
 declare function isCancelledJob(job: AnyJob): job is CancelledJob<any>;
-interface JobQueryFilters {
-    status?: JobStatus;
-    type?: JobType;
-    userId?: UserId;
-    limit?: number;
-    offset?: number;
-}
-
-interface JobQueue {
-    initialize(): Promise<void>;
-    destroy(): void;
-    createJob(job: AnyJob): Promise<void>;
-    getJob(jobId: JobId): Promise<AnyJob | null>;
-    /**
-     * Atomically claim the NEXT pending job matching one of `types` — the ONE
-     * transition that makes this a queue rather than a state store
-     * (JOB-QUEUE-DRIVER P0; reshaped claim-by-TYPE in P2, while every worker
-     * is still ours). pending → running, `startedAt` stamped, progress empty.
-     * An announcement is a WAKE-UP, not a reservation: the claimed job may
-     * differ from any announced one, no ordering among matching pending jobs
-     * is promised, and an empty `types` accepts any type. Simultaneous claims
-     * admit one winner PER pending job; a claim that finds nothing is
-     * DECLINED (`none-available`), never an error.
-     */
-    claimNextJob(types: string[]): Promise<{
-        job: AnyJob;
-    } | {
-        declined: 'none-available';
-    }>;
-    /** Move a running job to `complete`. Returns false if the job isn't running. */
-    completeJob(jobId: JobId, result: Record<string, unknown>): Promise<boolean>;
-    /**
-     * Move a running job back to `pending` (retry, re-announced) while
-     * `retryCount < maxRetries`, else to `failed`. Returns what happened,
-     * or null if the job isn't running. `completedUnits` — the units the
-     * failing attempt fully emitted — are unioned into the record's
-     * checkpoint (ABANDONED-INFERENCE P2) so a retry skips them. A
-     * `failureClass` of 'deterministic' goes straight to `failed` with any
-     * budget remaining — a second identical attempt cannot succeed (P3).
-     */
-    failJob(jobId: JobId, error: string, completedUnits?: string[], failureClass?: 'transient' | 'deterministic', unitCursors?: Record<string, UnitCursor>): Promise<'retried' | 'failed' | null>;
-    /**
-     * Persist a running job's completed-unit checkpoint AT unit completion —
-     * not only when a job fails (JOB-RESTART-SAFETY P2). `failJob` carries the
-     * checkpoint on a clean failure, but a worker that DIES (crash/OOM/kill)
-     * never emits `job:fail`, so its finished units would be lost and the
-     * janitor's recovery would redo them. This writes them into the running
-     * file's metadata as each unit lands, unioned with any existing
-     * checkpoint, so recovery resumes rather than restarts. Unthrottled (a
-     * unit completion must never be dropped); a no-op for non-running jobs.
-     *
-     * `unitCursors` is the finer grain `completedUnits` cannot express
-     * (CHUNK-GRAIN-RESUME P2): how far an UNFINISHED unit got, so a job that
-     * dies mid-unit resumes there instead of at the top. It is written per
-     * committed chunk, not per unit.
-     *
-     * **The two merge differently, and the difference is the contract.**
-     * `completedUnits` is a set, so a union converges under concurrent snapshots
-     * — a set only grows. A cursor converges only if the merge is **monotone per
-     * unit**: a stale snapshot must never move one backward. `next` and `size`
-     * move TOGETHER as one observation; taking `size` from one snapshot and
-     * `next` from another would describe a chunk that never existed. A unit that
-     * reaches `completedUnits` drops its cursor, so "in progress with a cursor"
-     * and "complete" stay structurally exclusive rather than by convention.
-     *
-     * The rule belongs here rather than to any one driver because it is what
-     * makes a cursor safe to merge at all.
-     */
-    checkpointUnits(jobId: JobId, completedUnits: string[], unitCursors?: Record<string, UnitCursor>): Promise<void>;
-    /** Write progress into a running job's file (throttled, best-effort). */
-    recordProgress(jobId: JobId, progress: Record<string, unknown>): Promise<void>;
-    /**
-     * Cancel all pending jobs in a category — 'generation' is the
-     * `generation` type; 'annotation' is every `*-annotation` type.
-     * Running jobs are left to finish. Returns the number cancelled.
-     */
-    cancelPendingJobs(category: 'annotation' | 'generation'): Promise<number>;
-    cancelJob(jobId: JobId): Promise<boolean>;
-    getStats(): Promise<{
-        pending: number;
-        running: number;
-        complete: number;
-        failed: number;
-        cancelled: number;
-    }>;
-}
-/**
- * Every bus channel a queue DRIVER emits, maintained beside the interface
- * both drivers implement and censused against their sources
- * (queue-emits-census.test.ts). The gateway's signal bridge forwards these
- * from its local bus onto the plane — a queue announcement that stays on
- * the raw bus reaches no worker under a remote driver (the job:queued
- * starvation, 2026-09-15).
- */
-declare const JOB_QUEUE_EMITS: readonly ["job:queued"];
-/**
- * How long a job's record survives after it reaches a terminal state
- * (complete/failed/cancelled), and how often a driver enforces that.
- *
- * ONE pair for every driver. The window is a CONTRACT fact — a caller that
- * reads a finished job's result gets the same day whichever backing store the
- * stack runs — and the cadence is what turns the window from an aspiration
- * into a promise. Restated per driver the two numbers drift, and the drift is
- * invisible until someone compares two deployments.
- *
- * The METHOD that enforces retention is not on the interface and cannot be:
- * it is an unlink in one driver and a stream purge in another. The NUMBER is
- * here because it is the same number.
- */
-declare const TERMINAL_JOB_RETENTION_MS: number;
-/** How often a driver sweeps for records past `TERMINAL_JOB_RETENTION_MS`. */
-declare const TERMINAL_JOB_SWEEP_INTERVAL_MS: number;
-
-/**
- * Job Queue Manager
- *
- * Filesystem-based job queue with atomic operations.
- * Jobs are stored in directories by status; status transitions are
- * atomic delete + write across directories.
- */
-
-declare class FsJobQueue implements JobQueue {
-    private eventBus?;
-    private jobsDir;
-    private logger;
-    private reannounceTimer;
-    private cleanupTimer;
-    /** Per-job timestamp of the last progress write, for throttling. */
-    private lastProgressWrite;
-    constructor(
-    /** `SemiontState` and not `SemiontProject`: the queue reads ONE path,
-     *  and the gateway that owns it mounts no KB tree (SINGLE-KB-MOUNT P5). */
-    state: SemiontState, logger: Logger, eventBus?: EventBus | undefined);
-    /**
-     * Initialize job queue directories, announce any pending backlog,
-     * and start the re-announce interval. Idempotent.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Stop the re-announce and retention intervals
-     */
-    destroy(): void;
-    /**
-     * Emit `job:queued` for a pending job, if an EventBus is wired and
-     * the job carries a `resourceId` (every current job type does).
-     */
-    private announce;
-    /**
-     * Announce every job currently in `pending/`. Files that vanish or
-     * fail to parse mid-scan (claimed, cancelled, partially written)
-     * are skipped — they're either gone for a good reason or picked up
-     * on the next tick.
-     */
-    private announcePendingJobs;
-    /**
-     * Create a new job
-     */
-    createJob(job: AnyJob): Promise<void>;
-    /**
-     * Get a job by ID (searches all status directories)
-     */
-    getJob(jobId: JobId): Promise<AnyJob | null>;
-    /**
-     * Serializes claims. This driver's atomicity is single-process by design,
-     * but `claimJob`'s contract must hold even against interleaved awaits in
-     * that one process — a read-check-write with await points in it can admit
-     * two winners without this chain (the TOCTOU the operation exists to kill).
-     */
-    private claimChain;
-    claimNextJob(types: string[]): Promise<{
-        job: AnyJob;
-    } | {
-        declined: 'none-available';
-    }>;
-    private doClaimNext;
-    /**
-     * Update a job (atomic: delete old, write new)
-     */
-    /**
-     * Cross-status move (or in-place rewrite): delete old slot, write new.
-     * Private — the interface exposes named transitions only (JOB-QUEUE-DRIVER
-     * P0); a generic public patch is trivial on files and impossible on an
-     * in-flight message, so no driver may offer one. Re-entering `pending`
-     * announces, which is how failJob's retry reaches a listening worker.
-     */
-    private transition;
-    /**
-     * Move a running job to `complete`. Returns false (and changes
-     * nothing) if the job is missing or not running — which also makes
-     * duplicate `job:complete` events harmless.
-     */
-    completeJob(jobId: JobId, result: Record<string, unknown>): Promise<boolean>;
-    /**
-     * Retry-or-fail a running job. While `retryCount < maxRetries` the
-     * job goes back to `pending` with the count bumped (and is
-     * re-announced); after that it lands in `failed` with the error.
-     * Returns null (and changes nothing) if the job isn't running.
-     */
-    failJob(jobId: JobId, error: string, completedUnits?: string[], failureClass?: 'transient' | 'deterministic', unitCursors?: Record<string, UnitCursor>): Promise<'retried' | 'failed' | null>;
-    /**
-     * Persist a running job's completed-unit checkpoint at unit completion
-     * (JOB-RESTART-SAFETY P2). `failJob` writes this checkpoint on a clean
-     * failure, but a worker that dies without emitting `job:fail` would lose
-     * its finished units — so the janitor's recovery (which re-queues with
-     * whatever `metadata.completedUnits` the running file holds) would redo
-     * them. Writing it HERE, as each unit lands, makes a crash lose at most
-     * the in-flight unit. Unioned with any existing checkpoint, unthrottled
-     * (a unit completion is rare and must never be dropped), a no-op for
-     * non-running jobs. Written directly, like `recordProgress`, so it also
-     * refreshes the mtime heartbeat.
-     */
-    checkpointUnits(jobId: JobId, completedUnits: string[], unitCursors?: Record<string, UnitCursor>): Promise<void>;
-    /**
-     * Write progress into a running job's file. Throttled per job, and
-     * a no-op for jobs that aren't running. Beyond surfacing live
-     * progress to `job:status-requested`, each write refreshes the
-     * file's mtime — the heartbeat `recoverStaleRunningJobs` watches.
-     */
-    recordProgress(jobId: JobId, progress: Record<string, unknown>): Promise<void>;
-    /**
-     * List jobs with filters
-     */
-    listJobs(filters?: JobQueryFilters): Promise<AnyJob[]>;
-    /**
-     * Cancel a job
-     */
-    cancelJob(jobId: JobId): Promise<boolean>;
-    /**
-     * Cancel all pending jobs in a category — the granularity of the
-     * `job:cancel-requested` UI signal. Running jobs are left to finish:
-     * interrupting a worker mid-inference would need a worker-side kill
-     * channel that doesn't exist.
-     */
-    cancelPendingJobs(category: 'annotation' | 'generation'): Promise<number>;
-    /**
-     * Recover running jobs orphaned by a dead worker: any `running/`
-     * file whose mtime is older than the stale window is fed through
-     * the same retry-or-fail path as `job:fail`. Progress writes
-     * refresh the mtime, so a live worker is never recovered out from
-     * under itself as long as it reports within the window.
-     */
-    recoverStaleRunningJobs(): Promise<number>;
-    /**
-     * Delete terminal jobs whose `completedAt` is older than `retentionMs`.
-     * The window is a parameter with no default: the ONE value the queue runs
-     * on is `TERMINAL_JOB_RETENTION_MS`, and a default here would be a second
-     * copy of it that nobody notices going stale.
-     */
-    cleanupOldJobs(retentionMs: number): Promise<number>;
-    /**
-     * Get job file path
-     */
-    private getJobPath;
-    /**
-     * Get statistics about the queue
-     */
-    getStats(): Promise<{
-        pending: number;
-        running: number;
-        complete: number;
-        failed: number;
-        cancelled: number;
-    }>;
-}
-
-/**
- * JetStreamJobQueue — the JetStream driver behind the `JobQueue` interface
- * (JOB-QUEUE-DRIVER P1, topology ruling M: broker-mediated — the queue's own
- * process holds the broker connection and the leases; workers never touch the
- * broker. That process was the gateway; it is the dispatcher now.)
- *
- * Two primitives, one authority each:
- *
- *  - **KV bucket `jobs`** is the AUTHORITATIVE operational state: one entry
- *    per job (`{ job, lastProgressAt }`), every transition a revision-CAS —
- *    which is what makes `claimJob` atomic: simultaneous claims race on one
- *    revision and exactly one update wins. It holds LIVE jobs plus a day of
- *    concluded ones, not a history: `pruneTerminalJobs` is the retention the
- *    fs driver's janitor holds, and without it every scan over the bucket
- *    — `getStats` is one, on the metrics interval — grows forever.
- *  - **Stream `JOBS`** (subjects `jobs.<category>.<type>`, work-queue
- *    retention) is the DELIVERY vehicle and redelivery timer. A delivered
- *    message is the lease this process holds for a job; `working()`
- *    heartbeats extend it, and a dispatcher that dies stops heartbeating, so
- *    `AckWait` redelivers the job to a live instance — dispatcher-death
- *    recovery, protocol-native.
- *
- * Worker-death recovery is NOT AckWait's job under the mediated topology
- * (the dispatcher holding the lease is alive; the worker vanished): it is the
- * `lastProgressAt` sweep (`recoverStaleRunningJobs`), the same contract the
- * fs driver's mtime janitor implemented. The redelivery handler checks KV
- * state, so the two recovery paths can never double-apply.
- *
- * Battery ownership (JOB-QUEUE-DRIVER P0): the retry decision belongs to
- * `will-retry.ts` — `max_deliver` is unlimited and a deterministic failure
- * is `term()`ed, so the backend's retry engine never becomes a second
- * authority. The cursor merge belongs to `checkpoint-merge.ts`, shared with
- * every driver.
- *
- * The boundary is the point: no NATS type, subject string, or delivery
- * handle escapes this file.
- */
-
-interface JetStreamJobQueueOptions {
-    /** NATS server address(es), e.g. "192.168.64.42:4222". */
-    servers: string | string[];
-    /**
-     * Broker credentials (INTER-COMPONENT-ACCESS P3). The same broker the signal
-     * plane connects to, so the same pair. Absent means an unauthenticated
-     * broker — which is what every deployment had before this, and means anyone
-     * who can reach NATS can read and write the job stream.
-     */
-    user?: string;
-    pass?: string;
-    /** Worker presumed dead after this long without progress (default 30 min). */
-    staleRunningMs?: number;
-    /** Lease redelivery window when THIS process stops heartbeating (default 30 s). */
-    ackWaitMs?: number;
-    /** Re-announce + worker-death-sweep cadence (default 30 s; tests shrink it). */
-    tickMs?: number;
-    /** Reconnect on connection loss (default true; tests turn it off). */
-    reconnect?: boolean;
-}
-declare class JetStreamJobQueue implements JobQueue {
-    private readonly options;
-    private readonly logger;
-    private readonly eventBus?;
-    private nc;
-    private js;
-    private jsm;
-    private kv;
-    private iter;
-    /** Delivered messages this process holds — the lease, keyed by jobId,
-     *  with the job's type so a by-type claim can walk them without a read. */
-    private readonly held;
-    private heartbeat;
-    private reconciling;
-    private tick;
-    private ticking;
-    private cleanupTimer;
-    private readonly lastProgressWrite;
-    private readonly staleRunningMs;
-    private readonly ackWaitMs;
-    private readonly tickMs;
-    constructor(options: JetStreamJobQueueOptions, logger: Logger, eventBus?: EventBus | undefined);
-    initialize(): Promise<void>;
-    /** An outage is never silent: one line down, one line back, one line if the client gives up. */
-    private watchConnection;
-    destroy(): void;
-    /**
-     * A delivery is a job arriving at this dispatcher. What it means depends on
-     * the job's authoritative (KV) state:
-     *  - pending  → hold the lease, announce for a worker to claim;
-     *  - running  → hold silently (a claim raced ahead of the delivery, or a
-     *               redelivery reached a fresh instance after a dispatcher death);
-     *  - terminal → the work already concluded elsewhere; consume the message;
-     *  - unknown  → not ours to run; terminate it.
-     */
-    private onDelivery;
-    /** Same wire shape as the fs driver: only jobs with a resourceId announce. */
-    private announce;
-    private read;
-    private write;
-    /**
-     * Read-transform-CAS with bounded retries: the transform sees the current
-     * job and returns the replacement (or null to stop). Every state
-     * transition goes through here, which is what makes each one atomic.
-     */
-    private cas;
-    createJob(job: AnyJob): Promise<void>;
-    getJob(jobIdArg: JobId): Promise<AnyJob | null>;
-    claimNextJob(types: string[]): Promise<{
-        job: AnyJob;
-    } | {
-        declined: 'none-available';
-    }>;
-    /** CAS one pending job to running; null when someone else won it. */
-    private tryClaim;
-    completeJob(jobIdArg: JobId, result: Record<string, unknown>): Promise<boolean>;
-    failJob(jobIdArg: JobId, error: string, completedUnits?: string[], failureClass?: 'transient' | 'deterministic', unitCursors?: Record<string, UnitCursor>): Promise<'retried' | 'failed' | null>;
-    checkpointUnits(jobIdArg: JobId, completedUnits: string[], unitCursors?: Record<string, UnitCursor>): Promise<void>;
-    recordProgress(jobIdArg: JobId, progress: Record<string, unknown>): Promise<void>;
-    cancelPendingJobs(category: 'annotation' | 'generation'): Promise<number>;
-    cancelJob(jobIdArg: JobId): Promise<boolean>;
-    /**
-     * Counts by status. The three terminal counts are the RETENTION WINDOW, not
-     * lifetime totals — `pruneTerminalJobs` drops a record a day after it
-     * concluded — so they answer "recently finished", never "finished ever".
-     */
-    getStats(): Promise<{
-        pending: number;
-        running: number;
-        complete: number;
-        failed: number;
-        cancelled: number;
-    }>;
-    /**
-     * Worker-death recovery: the same contract the fs driver's mtime janitor
-     * implemented — a running job with no progress inside the stale window is
-     * retried or failed, checkpoint intact. Gateway-death recovery never comes
-     * through here; that is AckWait redelivery.
-     */
-    recoverStaleRunningJobs(): Promise<number>;
-    /**
-     * Terminal-job retention: the fs driver's hourly janitor, in this driver's
-     * terms. Without it the bucket keeps every job it has ever seen, and
-     * `getStats` — an OTel observable gauge, so a full bucket scan every metric
-     * interval — pays for all of them forever. Measured on a live stack
-     * 2026-09-24: 139 concluded records re-read every 30 seconds by a knowledge
-     * base that had done very little work.
-     *
-     * A SWEEP AND NOT A BUCKET TTL, deliberately. `ttl` on `views.kv()` is a
-     * BUCKET limit — the backing stream's `max_age` — so it expires every key
-     * by age, not the terminal ones by status: a pending job nobody claimed for
-     * a day, a running job whose worker went quiet, both evaporate alongside
-     * the finished ones. That is not a slower version of this bug, it is a
-     * worse one. This bucket is the AUTHORITATIVE record: with the entry gone
-     * `read` returns null, every CAS falls through to its `onMissing`, and the
-     * next delivery for that job is `term()`ed as unknown — the job disappears
-     * with no failure and no trace. The rule retention needs to express is
-     * about STATUS, and status is exactly what a bucket-wide clock cannot see.
-     * (A per-message TTL set at the terminal write would express it, but that
-     * is nats-server 2.11 plus a client that exposes it; nats.js 2.x does not.)
-     *
-     * Terminal is absorbing — no transition leaves `complete`/`failed`/
-     * `cancelled` — so a record this sweep reads as expired cannot come back to
-     * life under it, and the lease was settled at the transition that made it
-     * terminal.
-     */
-    pruneTerminalJobs(retentionMs: number): Promise<number>;
-    /** The heartbeat body — extend live leases, settle concluded ones. */
-    private reconcileHeld;
-    /**
-     * Materialize the KV key list BEFORE touching any entry: interleaving
-     * `get`/`update` with an open `keys()` iterator on the same connection
-     * makes the iterator drop entries (measured: the second pending job
-     * vanished from every sweep until this was split into two passes).
-     */
-    private allKeys;
-    /** Conclude this process's lease on a job, if it holds one. */
-    private settleLease;
-}
 
 /**
  * Citation-token resolver (INLINE-CITATIONS P1).
@@ -732,7 +240,7 @@ declare class JetStreamJobQueue implements JobQueue {
 
 interface GenerationCitation {
     /** The cited source resource (validated present in the embedded context). */
-    resourceId: string;
+    resourceId: ResourceId;
     /** The contributing annotation, when the cited excerpt was annotation-derived. */
     annotationId?: string;
     /** Claim span in the FINAL (token-stripped) content; substring(start, end) === exact. */
@@ -741,6 +249,17 @@ interface GenerationCitation {
     exact: string;
 }
 
+/**
+ * Job Processors
+ *
+ * Pure functions that take content + inference client + params,
+ * report progress via callback, and return annotations + results.
+ *
+ * No EventBus, no queue, no side effects except calling inference.
+ * Driven by the remote worker process (worker-process.ts), which claims
+ * jobs over SSE and dispatches by jobType to these functions.
+ */
+
 /** A detected span — offsets into the extracted `.text`, plus optional context. */
 type SpanMatch = {
     exact: string;
@@ -860,7 +379,7 @@ declare function processGenerationJob(inferenceClient: InferenceClient, params:
     title: string;
     format: SupportedMediaType;
     citations: GenerationCitation[];
-    result: GenerationResult;
+    truncated: boolean;
 }>;
 
 /**
@@ -1059,6 +578,186 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
     truncated: boolean;
 }>;
 
+/**
+ * Job Claim Adapter — worker-side job lifecycle glue on top of a
+ * shared bus.
+ *
+ * Replaces the old `WorkerStateUnit`, which owned its own actor and
+ * duplicated the SSE connection that `SemiontClient` already held.
+ * Workers construct a `SemiontSession` normally (one actor, one
+ * SSE connection) and use this adapter to attach job-claim behaviour
+ * on top of the session's bus. It does **not** own the bus, has no HTTP
+ * concerns, and has no modal state.
+ *
+ * THE MODEL — a worker asks the queue at every moment it becomes idle,
+ * and never otherwise. `job:claim` carries this worker's types; the
+ * dispatcher answers with the next pending job of those types, atomically
+ * claimed, or declines. Queue state is the truth; no message carries
+ * correctness. The idle moments:
+ *
+ *   - start, once the transport is open;
+ *   - settle — `completeJob` / `failJob` — immediately, with no timer;
+ *   - a matching `job:queued` while parked;
+ *   - reconnect — every `state$` edge into `open` after the first.
+ *
+ * `job:queued` is a WAKE-UP with no memory. While parked it triggers a
+ * pull; while a claim is in flight it sets a dirty bit that earns exactly
+ * one more pull before parking, so a wake-up cannot be lost in that window;
+ * while a job is held it is ignored, because the settle pulls. One claim
+ * in flight at a time — under one-job-at-a-time processing "drain" is one
+ * claim per idle moment and one at settle, never a loop of claims while a
+ * job is held. The type filter on the wake-up is a PRE-FILTER on
+ * information the announcement already carries, so a worker that cannot
+ * run the announced type does not spend a round trip to be declined; the
+ * claim's `types` argument is the rule.
+ *
+ * What the dispatcher's decline codes mean here (`BusRequestError.code`,
+ * promoted from the reply's `CommandError.code`): `bus.none-pending` is
+ * the quiet park — nothing to do until a wake-up, nothing emitted. Every
+ * other refusal goes out on `refused$` for the runtime to judge;
+ * `bus.unauthorized` is the one it exits on, because a credential that
+ * can never claim has nothing to do here and the launcher's preflight
+ * names the repair.
+ *
+ * The queue drivers' 30 s re-announce tick survives as INSURANCE against a
+ * lost wake-up on an idle worker — never as dispatch. A healthy stack never
+ * sees it act.
+ *
+ * The `bus` parameter is typed against the small `BusRequestPrimitive`
+ * interface (from `@semiont/core`) so the adapter is transport-neutral.
+ * HTTP workers pass `(session.client.transport as HttpTransport).actor`;
+ * an in-process worker could pass a shim wrapping `client.bus`.
+ */
+
+/** The job a `job:claimed` reply carries, running under this worker: the spec's `JobRunning`. */
+type ClaimedJob = EventMap['job:claimed']['response'];
+/**
+ * The claimed job as the worker holds it: the fields of the claimed record the
+ * worker reads, each with the type the spec gives it there.
+ */
+interface ActiveJob {
+    jobId: JobId;
+    type: JobType$1;
+    resourceId: ResourceId;
+    params: ClaimedJob['params'];
+    /**
+     * Entity-type units earlier failed attempts fully emitted
+     * (ABANDONED-INFERENCE P2 checkpointed resume) — carried on the claimed
+     * record's metadata by `failJob`. The worker skips them, so a retry
+     * neither redoes nor duplicates completed work. Empty on first attempts.
+     */
+    completedUnits: string[];
+    /**
+     * How far each UNFINISHED unit got on an earlier attempt
+     * (CHUNK-GRAIN-RESUME P2) — the grain `completedUnits` cannot express, and
+     * the only checkpoint a one-unit job can produce before it finishes. Empty
+     * on first attempts, and never overlapping `completedUnits`: a unit is
+     * either finished or partway, never both.
+     */
+    unitCursors: Record<string, UnitCursor>;
+    /**
+     * The claimed record's retry budget, carried so the worker can report
+     * `willRetry` on `job:fail` (JOB-RESTART-SAFETY P5). It is the same budget
+     * the queue re-reads at `failJob`, and only `failJob` changes it, so the
+     * two evaluations of `willRetryAfter` agree.
+     */
+    retryCount: number;
+    maxRetries: number;
+}
+interface JobClaimAdapterOptions {
+    /** Shared bus (typically the session's HTTP actor or an in-process bus shim). */
+    bus: BusRequestPrimitive;
+    /**
+     * Job types this worker can process — the claim's `types` argument, and
+     * the pre-filter on `job:queued` wake-ups. Empty array = accept any.
+     */
+    jobTypes: string[];
+}
+/**
+ * A claim the dispatcher refused for a reason other than "nothing pending".
+ *
+ * `code` is the `BusRequestError` code the reply was promoted to, or `null`
+ * when the failure was local — a thrown non-bus error — never a manufactured
+ * bus code. `bus.none-pending` never appears here: it is the quiet park, and
+ * emitting it would make an empty queue look like a fault.
+ */
+interface ClaimRefusal {
+    code: BusRequestErrorCode | null;
+    message: string;
+}
+/**
+ * Point-in-time liveness snapshot (WORKER-LIVENESS.md P1). The adapter
+ * is the only component that sees every wake-up, claim, and finish,
+ * so its snapshot is what `/health` reports and the stall watchdog reads.
+ *
+ * `lastQueuedEventAt` is any `job:queued` received, matching or not. It
+ * proves the transport delivered a broadcast, but on an idle stack with an
+ * empty queue it stands still by design — no announcement is owed — so a
+ * still stamp alone is not a transport fault; transport liveness proper is
+ * the actor's SSE heartbeat. `lastActivityAt` (claim, progress emission, or
+ * finish) is processing liveness; a job stuck mid-inference stops advancing
+ * it, and that is what the watchdog reads.
+ */
+interface WorkerVitals {
+    lastQueuedEventAt: string | null;
+    lastClaimAt: string | null;
+    /** Last completion or failure — a failing-but-moving worker is alive. */
+    lastFinishedAt: string | null;
+    lastActivityAt: string | null;
+    activeJob: {
+        jobId: string;
+        type: string;
+        since: string;
+    } | null;
+    jobsCompleted: number;
+}
+interface JobClaimAdapter {
+    /** Currently-claimed job, or null when idle. */
+    readonly activeJob$: Observable<ActiveJob | null>;
+    /** True while a claim is in flight or a job is being processed. */
+    readonly isProcessing$: Observable<boolean>;
+    /** Monotonically-incrementing count of successfully-completed jobs. */
+    readonly jobsCompleted$: Observable<number>;
+    /** Stream of job failures reported through `failJob`. */
+    readonly errors$: Observable<{
+        jobId: string;
+        error: string;
+    }>;
+    /**
+     * Claims the dispatcher refused for a reason the runtime must judge.
+     * `bus.unauthorized` means this credential can never claim; the runtime
+     * exits on it. Anything else is logged and the worker stays parked until
+     * the next wake-up. See `ClaimRefusal`.
+     */
+    readonly refused$: Observable<ClaimRefusal>;
+    /**
+     * Begin pulling: one claim now (once the transport is open), then on every
+     * settle, matching wake-up, and reconnect. Idempotent — calling `start()`
+     * twice is a no-op.
+     */
+    start(): void;
+    /** Stop pulling. Does not cancel an in-flight job. */
+    stop(): void;
+    /** Signal successful completion of `activeJob$`. Pulls the next job. */
+    completeJob(): void;
+    /** Signal failure of `activeJob$`. Emits on `errors$`, then pulls the next job. */
+    failJob(jobId: string, error: string): void;
+    /** Liveness snapshot for `/health` and the stall watchdog. */
+    vitals(): WorkerVitals;
+    /**
+     * Record processing activity. The worker process calls this on every
+     * progress emission so a long multi-call job keeps proving liveness
+     * between inference calls.
+     */
+    touchActivity(): void;
+    /** Release observables. Does not dispose the shared bus. */
+    dispose(): void;
+}
+/**
+ * Attach job-claim behaviour to a shared bus.
+ */
+declare function createJobClaimAdapter(options: JobClaimAdapterOptions): JobClaimAdapter;
+
 /**
  * Worker Runtime — the importable half of the worker host.
  *
@@ -1099,9 +798,9 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
  * wedged). The unbounded emit that caused that specific hang is now bounded
  * at the transport (`EMIT_TIMEOUT_MS`), so the loop errors instead of
  * blocking; but for any future blocked-loop bug the ONLY backstop is the
- * out-of-process one — the gateway's janitor sweeping this worker's job
- * files by mtime (`fs-job-queue.ts` `recoverStaleRunningJobs`). A liveness
- * guarantee a blocked loop defeats is not one; the janitor is the guarantee.
+ * out-of-process one — the dispatcher's sweep, which fails a running job
+ * whose worker has gone silent (docs/protocol/JOBS.md). A liveness guarantee a
+ * blocked loop defeats is not one; the sweep is the guarantee.
  */
 declare const STALL_THRESHOLD_MS: number;
 /**
@@ -1125,5 +824,5 @@ declare const WORKER_CONSUMED_BROADCASTS: readonly ["job:queued", "job:cancel-re
  */
 declare const WORKER_CHANNELS: readonly (keyof EventMap)[];
 
-export { AnnotationDetection, FsJobQueue, JOB_QUEUE_EMITS, JetStreamJobQueue, STALL_THRESHOLD_MS, TERMINAL_JOB_RETENTION_MS, TERMINAL_JOB_SWEEP_INTERVAL_MS, WORKER_CHANNELS, WORKER_CONSUMED_BROADCASTS, generateResourceFromTopic, isCancelledJob, isCompleteJob, isFailedJob, isPendingJob, isRunningJob, processAssessmentJob, processCommentJob, processGenerationJob, processHighlightJob, processReferenceJob, processTagJob };
-export type { AnyJob, AssessmentDetectionJob, AssessmentDetectionParams, AssessmentDetectionProgress, CancelledJob, CommentDetectionJob, CommentDetectionParams, CommentDetectionProgress, CompleteJob, DetectionJob, DetectionParams, DetectionProgress, FailedJob, GenerationJob, GenerationResult, HighlightDetectionJob, HighlightDetectionParams, HighlightDetectionProgress, JetStreamJobQueueOptions, JobMetadata, JobQueryFilters, JobQueue, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningJob, TagDetectionJob, TagDetectionParams, TagDetectionProgress, YieldProgress };
+export { AnnotationDetection, STALL_THRESHOLD_MS, WORKER_CHANNELS, WORKER_CONSUMED_BROADCASTS, createJobClaimAdapter, generateResourceFromTopic, isCancelledJob, isCompleteJob, isFailedJob, isPendingJob, isRunningJob, processAssessmentJob, processCommentJob, processGenerationJob, processHighlightJob, processReferenceJob, processTagJob };
+export type { ActiveJob, AnyJob, AssessmentDetectionJob, AssessmentDetectionParams, CancelledJob, ClaimRefusal, CommentDetectionJob, CommentDetectionParams, CompleteJob, DetectionJob, DetectionParams, FailedJob, GenerationJob, HighlightDetectionJob, HighlightDetectionParams, JobClaimAdapter, JobClaimAdapterOptions, JobMetadata, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningAnyJob, RunningJob, StoredProgress, TagDetectionJob, TagDetectionParams, WorkerVitals };