@semiont/jobs 0.6.8 → 0.6.10

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { JobId, components, UserId, UnitCursor, ResourceId, EntityType, JobReferenceAnnotationResult, GenerationJobParams, JobHighlightAnnotationResult, JobAssessmentAnnotationResult, JobCommentAnnotationResult, TagSchema, JobTagAnnotationResult, Annotation, Logger, SupportedMediaType, GatheredContext, BusRequestErrorCode, BusRequestPrimitive, EventMap } from '@semiont/core';
+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';
 
@@ -35,25 +35,24 @@ interface JobMetadata {
     retryCount: number;
     maxRetries: number;
     /**
-     * Checkpointed resume (ABANDONED-INFERENCE P2, HD1): the entity-type
-     * units whose annotations were fully emitted by earlier failed
-     * attempts. Written only by `failJob`, unioned across attempts — and
-     * because `failJob` rebuilds the retried record by spreading metadata,
-     * the checkpoint survives every subsequent rebuild for free. A retried
-     * claim skips these units, so completed work is neither redone nor
-     * duplicated.
+     * Checkpointed resume: the entity-type units whose annotations are fully
+     * committed. Written by the dispatcher's queue from `job:checkpoint` (as
+     * each unit lands) and from `job:fail`, unioned across attempts — and
+     * because a retried record keeps its metadata, the checkpoint survives
+     * every retry. A retried claim skips these units, so completed work is
+     * neither redone nor duplicated.
      */
     completedUnits?: string[];
     /**
-     * The finer grain `completedUnits` cannot express (CHUNK-GRAIN-RESUME P2):
-     * how far each UNFINISHED unit got, keyed by unit. Written per committed
-     * chunk, so a job that dies mid-unit resumes there rather than at the top —
-     * which for a one-unit job (every motivation job, and the 1958 document's
-     * single `Person` type) is the difference between resuming and restarting.
+     * The finer grain `completedUnits` cannot express: how far each UNFINISHED
+     * unit got, keyed by unit. Written per committed chunk, so a job that dies
+     * mid-unit resumes there rather than at the top — which for a one-unit job
+     * (every motivation job, and the 1958 document's single `Person` type) is
+     * the difference between resuming and restarting.
      *
      * A unit here is in progress, never complete; the two sets are disjoint by
-     * construction in `checkpointUnits`. Merged monotonically per unit, never
-     * unioned — see `mergeUnitCursors`.
+     * construction — the dispatcher's merge drops a completed unit's cursor.
+     * Merged monotonically per unit (the furthest cursor wins), never unioned.
      */
     unitCursors?: Record<string, UnitCursor>;
 }
@@ -142,16 +141,6 @@ type TagDetectionParams = {
     /** Source-resource locale — see locale conventions above. */
     sourceLanguage?: 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;
-}
 /**
  * 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
@@ -216,7 +205,7 @@ 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;
-}, GenerationResult>;
+}, components['schemas']['JobGenerationResult']>;
 type HighlightDetectionJob = Job<HighlightDetectionParams, JobHighlightAnnotationResult>;
 type AssessmentDetectionJob = Job<AssessmentDetectionParams, JobAssessmentAnnotationResult>;
 type CommentDetectionJob = Job<CommentDetectionParams, JobCommentAnnotationResult>;
@@ -236,21 +225,21 @@ declare function isFailedJob(job: AnyJob): job is FailedJob<any>;
 declare function isCancelledJob(job: AnyJob): job is CancelledJob<any>;
 
 /**
- * Citation-token resolver (INLINE-CITATIONS P1).
+ * Citation-token resolver.
  *
  * Under `cite`, the generation prompt asks the model to emit `[[<resourceId>]]` /
  * `[[<resourceId>/<annotationId>]]` transport tokens after each claim, citing ids
- * the context embedding put in front of it (CONTEXT-IDENTIFIERS). Tokens are
- * TRANSPORT, not content: this resolver parses them, validates each id against the
- * ids actually present in the embedded context (the hallucination guard — an
- * unknown id is dropped loudly, never silently linked), STRIPS them from the
- * content before upload, and returns claim-span citations the worker mints as W3C
- * linking annotations on the derived resource. See .plans/INLINE-CITATIONS.md.
+ * the context embedding put in front of it: every embedded excerpt carries a
+ * `[<resourceId>]` handle. Tokens are TRANSPORT, not content: this resolver parses
+ * them, validates each id against the ids actually present in the embedded context
+ * (the hallucination guard — an unknown id is dropped loudly, never silently
+ * linked), STRIPS them from the content before upload, and returns claim-span
+ * citations the worker mints as W3C linking annotations on the derived resource.
  */
 
 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. */
@@ -259,6 +248,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;
@@ -285,13 +285,12 @@ type BuildAnnotation = (motivation: Motivation, match: SpanMatch, body?: Annotat
  * on EVERY call: the client's `progress$` replaces its value per event, so a
  * field sent once disappears on the next tick.
  *
- * `message` is a CODE plus typed params, never a prose sentence
- * (ASSIST-PROGRESS-CONSOLIDATION A6). The producer reports what happened;
- * each client renders it in the user's language — react-ui from its 29
- * locales, the Go launcher from its English map. The vocabulary is frozen
- * by the census of these call sites: adding a shape means adding a variant
- * to `JobProgressMessage.json` and copy in every client, not composing a
- * new sentence here.
+ * `message` is a CODE plus typed params, never a prose sentence. The producer
+ * reports what happened; each client renders it in the user's language —
+ * react-ui from its 29 locales, the Go launcher from its English map. The
+ * vocabulary is frozen by the census of these call sites: adding a shape
+ * means adding a variant to `JobProgressMessage.json` and copy in every
+ * client, not composing a new sentence here.
  */
 type OnProgress = (percentage: number, message: JobProgressMessage, extra?: Partial<JobProgress>) => void;
 type JobProgress = components['schemas']['JobProgress'];
@@ -308,8 +307,9 @@ interface ProcessorResult<R> {
     result: R;
 }
 /**
- * Where one unit stands once the chunk just handed over is durable
- * (CHUNK-GRAIN-RESUME P2).
+ * Where one unit stands once the chunk just handed over is durable: the
+ * cursor a retry resumes that unit from, instead of re-running the chunks it
+ * already committed.
  *
  * The unit is named HERE rather than in the detection layer, which knows about
  * chunks and nothing about jobs: for `reference-annotation` a unit is an entity
@@ -323,32 +323,32 @@ interface UnitCheckpoint {
 declare function processHighlightJob(content: string, inferenceClient: InferenceClient, params: HighlightDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, 
 /** This chunk's novel annotations, awaited: the durability write. */
 onChunkComplete: (annotations: Annotation[], checkpoint: UnitCheckpoint) => Promise<void>, 
-/** Where earlier attempts left each unit (CHUNK-GRAIN-RESUME P3), keyed the
- * same way the checkpoint is. A unit absent here starts at the top, which is
- * every unit of a first attempt. */
+/** Where earlier attempts left each unit, keyed the same way the checkpoint
+ * is. A unit absent here starts at the top, which is every unit of a first
+ * attempt. */
 resumeCursors?: Record<string, UnitCursor>): Promise<ProcessorResult<JobHighlightAnnotationResult>>;
 declare function processCommentJob(content: string, inferenceClient: InferenceClient, params: CommentDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, 
 /** This chunk's novel annotations, awaited: the durability write. */
 onChunkComplete: (annotations: Annotation[], checkpoint: UnitCheckpoint) => Promise<void>, 
-/** Where earlier attempts left each unit (CHUNK-GRAIN-RESUME P3), keyed the
- * same way the checkpoint is. A unit absent here starts at the top, which is
- * every unit of a first attempt. */
+/** Where earlier attempts left each unit, keyed the same way the checkpoint
+ * is. A unit absent here starts at the top, which is every unit of a first
+ * attempt. */
 resumeCursors?: Record<string, UnitCursor>): Promise<ProcessorResult<JobCommentAnnotationResult>>;
 declare function processAssessmentJob(content: string, inferenceClient: InferenceClient, params: AssessmentDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, 
 /** This chunk's novel annotations, awaited: the durability write. */
 onChunkComplete: (annotations: Annotation[], checkpoint: UnitCheckpoint) => Promise<void>, 
-/** Where earlier attempts left each unit (CHUNK-GRAIN-RESUME P3), keyed the
- * same way the checkpoint is. A unit absent here starts at the top, which is
- * every unit of a first attempt. */
+/** Where earlier attempts left each unit, keyed the same way the checkpoint
+ * is. A unit absent here starts at the top, which is every unit of a first
+ * attempt. */
 resumeCursors?: Record<string, UnitCursor>): Promise<ProcessorResult<JobAssessmentAnnotationResult>>;
 /**
- * Reference detection commits per UNIT — one entity type — through
- * `onUnitComplete` (ABANDONED-INFERENCE P2, checkpointed resume): the
- * callback receives the unit's deduped annotations, and only after it
- * resolves does the unit count as complete. Emission belongs to the
- * callback alone; the processor returns only the result — returning the
- * annotations as well would recreate the post-run batch that N2 showed
- * discards completed work wholesale.
+ * Reference detection checkpoints per UNIT — one entity type — through
+ * `onUnitComplete`: only after the callback resolves does the unit count as
+ * complete, and a retried claim skips the units recorded that way.
+ * Annotations leave per chunk through `onChunkComplete`; the processor
+ * returns only the result — returning the annotations as well would make a
+ * post-run batch, where one failed call discards every completed unit's
+ * work wholesale.
  */
 declare function processReferenceJob(content: string, inferenceClient: InferenceClient, params: DetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, logger: Logger, 
 /**
@@ -360,25 +360,25 @@ declare function processReferenceJob(content: string, inferenceClient: Inference
 onUnitComplete: (entityType: string) => Promise<void>, signal?: AbortSignal, 
 /** This chunk's novel annotations, awaited: the durability write. */
 onChunkComplete?: (annotations: Annotation[], checkpoint: UnitCheckpoint) => Promise<void>, 
-/** Where earlier attempts left each entity-type unit (CHUNK-GRAIN-RESUME P3).
- * A unit absent here starts at the top; units already COMPLETE never reach
- * this function at all, the caller having filtered them out. */
+/** Where earlier attempts left each entity-type unit. A unit absent here
+ * starts at the top; units already COMPLETE never reach this function at
+ * all, the caller having filtered them out. */
 resumeCursors?: Record<string, UnitCursor>): Promise<{
     result: JobReferenceAnnotationResult;
 }>;
 declare function processTagJob(content: string, inferenceClient: InferenceClient, params: TagDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, 
 /** This chunk's novel annotations, awaited: the durability write. */
 onChunkComplete: (annotations: Annotation[], checkpoint: UnitCheckpoint) => Promise<void>, 
-/** Where earlier attempts left each CATEGORY (CHUNK-GRAIN-RESUME P3) — a tag
- * job's units are its categories, not its motivation: each walks the whole
- * document, so one shared cursor would skip text for all but one of them. */
+/** Where earlier attempts left each CATEGORY — a tag job's units are its
+ * categories, not its motivation: each walks the whole document, so one
+ * shared cursor would skip text for all but one of them. */
 resumeCursors?: Record<string, UnitCursor>): Promise<ProcessorResult<JobTagAnnotationResult>>;
 declare function processGenerationJob(inferenceClient: InferenceClient, params: GenerationJobParams, onProgress: OnProgress, logger: Logger): Promise<{
     content: Uint8Array;
     title: string;
     format: SupportedMediaType;
     citations: GenerationCitation[];
-    result: GenerationResult;
+    truncated: boolean;
 }>;
 
 /**
@@ -395,22 +395,17 @@ declare function processGenerationJob(inferenceClient: InferenceClient, params:
  *   `num_ctx`. What remains after the prompt scaffold is split
  *   input:output = 1:2 (annotation JSON echoes each span plus a fixed
  *   key/context envelope, so output needs the larger share). The 1:2 ratio
- *   is the plan's one allocation policy — doc-independent, tuned only on
- *   live evidence.
+ *   is the one allocation policy — doc-independent, tuned only on live
+ *   evidence.
  * - Separate ceilings (Anthropic): output takes its full ceiling (duration-
  *   capped below), and input follows the same 1:2 allocation — never more
  *   than half the output budget. Input does NOT get "the rest of the
- *   window": measured 2026-09-02, a window-sized chunk of entity-dense text
- *   demands more output than any budget holds, so the model grinds toward
- *   max_tokens for minutes (killed at the call bound as a "stall") or
- *   collapses to the degenerate []. Large documents chunk; that is the fix,
- *   not a cost.
+ *   window": a window-sized chunk of entity-dense text demands more output
+ *   than any budget holds, so the model grinds toward max_tokens for minutes
+ *   (killed at the call bound as a "stall") or collapses to the degenerate
+ *   []. Large documents chunk; that is the fix, not a cost.
  */
 
-/** One chunk handed out by `runAdaptiveChunks`, with the cursor either side of
- * it. `at`/`next` over `totalChars` is exact progress — and, once
- * CHUNK-GRAIN-RESUME lands, the checkpoint identity a variable boundary forces
- * (an ordinal cannot name a chunk whose size is decided while the job runs). */
 /**
  * The half of a `UnitCursor` the DETECTION layer can honestly report: where the
  * walk stands and how it is cutting. The tallies belong to the processor, which
@@ -422,9 +417,9 @@ type ChunkCursor = Pick<UnitCursor, 'next' | 'size'>;
 /**
  * Response parsers for annotation detection motivations
  *
- * Provides static methods to parse and validate AI responses for each motivation type.
- * Includes offset validation and correction logic.
- * Extracted from worker implementations to centralize parsing logic.
+ * Static methods that validate the model's already-parsed elements for each
+ * motivation type and anchor each span in the document: the model emits no
+ * offsets, `reconcileSelector` computes them.
  *
  * NOTE: These are static utility methods without logger access.
  * Console statements kept for debugging - consider adding logger parameter in future.
@@ -496,8 +491,7 @@ declare class AnnotationDetection {
      * full discussion.
      */
     static detectComments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onActivity?: (consumedChars: number, totalChars: number) => void, 
-    /** This chunk's matches, as the chunk completes. */
-    /** Where an earlier attempt left this unit (CHUNK-GRAIN-RESUME P3). */
+    /** Where an earlier attempt left this unit. */
     resume?: UnitCursor, 
     /** This chunk's matches, as the chunk completes. Kept LAST. */
     onChunkResults?: (matches: CommentMatch[], cursor: ChunkCursor) => Promise<void>): Promise<CommentMatch[]>;
@@ -509,8 +503,7 @@ declare class AnnotationDetection {
      * correctly.
      */
     static detectHighlights(content: string, client: InferenceClient, instructions?: string, density?: number, sourceLanguage?: string, onActivity?: (consumedChars: number, totalChars: number) => void, 
-    /** This chunk's matches, as the chunk completes. */
-    /** Where an earlier attempt left this unit (CHUNK-GRAIN-RESUME P3). */
+    /** Where an earlier attempt left this unit. */
     resume?: UnitCursor, 
     /** This chunk's matches, as the chunk completes. Kept LAST. */
     onChunkResults?: (matches: HighlightMatch[], cursor: ChunkCursor) => Promise<void>): Promise<HighlightMatch[]>;
@@ -522,8 +515,7 @@ declare class AnnotationDetection {
      * being analyzed (source-resource locale).
      */
     static detectAssessments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onActivity?: (consumedChars: number, totalChars: number) => void, 
-    /** This chunk's matches, as the chunk completes. */
-    /** Where an earlier attempt left this unit (CHUNK-GRAIN-RESUME P3). */
+    /** Where an earlier attempt left this unit. */
     resume?: UnitCursor, 
     /** This chunk's matches, as the chunk completes. Kept LAST. */
     onChunkResults?: (matches: AssessmentMatch[], cursor: ChunkCursor) => Promise<void>): Promise<AssessmentMatch[]>;
@@ -540,21 +532,22 @@ declare class AnnotationDetection {
      * site, not here.
      */
     static detectTags(content: string, client: InferenceClient, schema: TagSchema, category: string, sourceLanguage?: string, onActivity?: (consumedChars: number, totalChars: number) => void, 
+    /** Where an earlier attempt left this unit. */
+    resume?: UnitCursor, 
     /**
-     * This chunk's matches, ANCHORED before they leave: `parse` here yields
-     * raw tags, so this path runs `validateTagOffsets` per chunk — a per-item
-     * anchor against the full document, so partitioning changes nothing.
+     * This chunk's matches, as the chunk completes, ANCHORED before they
+     * leave: `parse` here yields raw tags, so this path runs
+     * `validateTagOffsets` per chunk — a per-item anchor against the full
+     * document, so partitioning changes nothing. Kept LAST.
      */
-    /** Where an earlier attempt left this unit (CHUNK-GRAIN-RESUME P3). */
-    resume?: UnitCursor, 
-    /** This chunk's matches, as the chunk completes. Kept LAST. */
     onChunkResults?: (matches: TagMatch[], cursor: ChunkCursor) => Promise<void>): Promise<TagMatch[]>;
 }
 
 /**
  * Resource Generation
  *
- * Generates markdown resources from topics using AI inference.
+ * Generates resource content from a topic using AI inference: markdown, plain
+ * text, or Typst source (which the worker compiles to PDF), by `outputMediaType`.
  */
 
 /**
@@ -581,12 +574,11 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
  * 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.
+ * on top of the session's bus, so the worker holds no second connection.
+ * 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
@@ -618,9 +610,9 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
  * 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 queue drivers' 30 s re-announce tick is INSURANCE against a lost
+ * wake-up on an idle worker — never 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.
@@ -628,32 +620,39 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
  * 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: string;
-    type: string;
-    resourceId: string;
-    userId: string;
-    params: Record<string, unknown>;
+    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.
+     * Entity-type units earlier attempts fully committed — the checkpoint a
+     * resume reads, carried on the claimed record's metadata, where the queue
+     * writes it from `job:checkpoint` and `job:fail`. 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.
+     * How far each UNFINISHED unit got on an earlier attempt: the offset where
+     * its last committed chunk ended and the size that chunk was cut at — 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.
+     * `willRetry` on `job:fail`. 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;
@@ -671,18 +670,18 @@ interface JobClaimAdapterOptions {
  * 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 — an unusable record, 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.
+ * 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.
+ * Point-in-time liveness snapshot. 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
@@ -760,53 +759,47 @@ declare function createJobClaimAdapter(options: JobClaimAdapterOptions): JobClai
  * a unit test needs to reach lives here instead, fully parameterized — no
  * module-scope env reads, no side effects at import.
  *
- * The load-bearing contract this module owns (and the reason it was
- * extracted): a worker's stamped identity is the DID the
- * `/api/tokens/agent` exchange MINTED for it, carried verbatim — never
- * re-derived from the URL the worker happens to dial. One logical agent
- * previously got two DIDs that way (.plans/bugs/agent-did-host-skew.md).
+ * The load-bearing contract this module owns: a worker's stamped identity is
+ * the DID the `/api/tokens/agent` exchange MINTED for it, carried verbatim —
+ * never re-derived from the URL the worker happens to dial: re-deriving gives
+ * one logical agent two DIDs.
  */
 
 /**
- * Stall watchdog (WORKER-LIVENESS.md P3) — the fail-fast line behind the
- * inference timeout. There is no poll timer to heartbeat — the worker pulls
- * when idle, and a parked idle worker is not a stall; the honest stall
- * signal is *processing without activity*: an agent holding a claimed job
- * whose `lastActivityAt` (claim / progress / finish) has stopped advancing
- * is wedged — the adapter defers every wake-up while a job is held and
- * pulls at settle, so a wedged agent never settles and never recovers on
- * its own. Silent hang → loud crash → whatever
- * restart policy the deployment chose.
+ * Stall watchdog — the fail-fast line behind the inference timeout. There
+ * is no poll timer to heartbeat — the worker pulls when idle, and a parked
+ * idle worker is not a stall; the honest stall signal is *processing
+ * without activity*: an agent holding a claimed job whose `lastActivityAt`
+ * (claim / progress / finish) has stopped advancing is wedged — the adapter
+ * defers every wake-up while a job is held and pulls at settle, so a wedged
+ * agent never settles and never recovers on its own. Silent hang → loud
+ * crash → whatever restart policy the deployment chose.
  *
  * Thresholds are fixed by design (no env knobs) and deliberately
- * layered: inference timeout (10 min, P2) fires first; this watchdog
+ * layered: inference timeout (10 min) fires first; this watchdog
  * (15 min) catches wedges where the loop still turns but activity has
  * stopped; the gateway's dead-worker janitor (30 min) re-queues the job
  * regardless.
  *
  * The layering matters because this watchdog has a hard limit: it is an
  * IN-PROCESS timer, so it cannot fire while the event loop itself is
- * blocked — the exact condition a blocked loop creates
- * (JOB-RESTART-SAFETY P7, the 2026-09-03 finalization hang: 18 min silent,
- * this watchdog never fired, an empty /health confirming the loop was
- * 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
+ * blocked — the exact condition a blocked loop creates. An emit is bounded
+ * at the transport (`EMIT_TIMEOUT_MS`), so the loop errors on one instead of
+ * blocking; but for any other blocked-loop bug the ONLY backstop is the
  * 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.
+ * 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;
 /**
  * The broadcasts a worker CONSUMES — announcements nobody replies to, which
  * therefore derive from no operation.
  *
- * One home, because the alternative was proven: these lived as `addChannels`
- * calls beside their consumers, so the worker's complete set existed nowhere
- * and a widening could be deleted without any list getting shorter. That is
- * the 2026-09-16 outage — every worker idle on a `job:queued` its transport
- * would never carry, `lastQueuedEventAt: null`, nothing thrown and nothing
- * logged.
+ * One home, because the alternative fails silently: as `addChannels` calls
+ * beside their consumers, the worker's complete set exists nowhere and a
+ * widening can be deleted without any list getting shorter — every worker
+ * then idles on a `job:queued` its transport never carries,
+ * `lastQueuedEventAt: null`, nothing thrown and nothing logged.
  *
  * An entry here must have a consumer and a consumer must have an entry; the
  * census beside this file asserts both directions.
@@ -819,4 +812,4 @@ declare const WORKER_CONSUMED_BROADCASTS: readonly ["job:queued", "job:cancel-re
 declare const WORKER_CHANNELS: readonly (keyof EventMap)[];
 
 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, GenerationResult, HighlightDetectionJob, HighlightDetectionParams, JobClaimAdapter, JobClaimAdapterOptions, JobMetadata, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningAnyJob, RunningJob, StoredProgress, TagDetectionJob, TagDetectionParams, WorkerVitals };
+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 };