@semiont/jobs 0.6.9 → 0.6.10

package/README.md

@@ -10,7 +10,7 @@ The job worker for [Semiont](https://github.com/The-AI-Alliance/semiont): the pr
 
 ## Architecture Context
 
-Workers run in a separate process and connect to the Knowledge System (KS) over HTTP/SSE using a `SemiontSession` (from `@semiont/sdk`) driven by a `JobClaimAdapter`. Whenever a worker is idle it claims the next pending job of its types with `job:claim` (a `job:queued` announcement wakes a parked worker), and it emits domain events back to the KS via `session.client.transport.emit(...)`. The KS ingests these events onto its EventBus for SSE delivery to the Browser.
+Workers run in a separate process and connect to the knowledge base's gateway over HTTP/SSE using a `SemiontSession` (from `@semiont/sdk`), with a `JobClaimAdapter` on the session's bus connection. Whenever a worker is idle it claims the next pending job of its types with `job:claim` (a `job:queued` announcement wakes a parked worker), and it emits its lifecycle events onto the bus via `session.client.transport.emit(...)`. The gateway relays them over SSE to the dispatcher, the Stower and clients such as the Browser.
 
 ## Installation
 
@@ -19,11 +19,11 @@ npm install @semiont/jobs
 ```
 
 **Dependencies:**
-- `@semiont/core` — Core types, `SemiontProject`, EventBus, `BusRequestPrimitive`
+- `@semiont/core` — Core types, the bus protocol (`busRequest`, `BusRequestPrimitive`), the config loader
 - `@semiont/sdk` — `SemiontSession`, `SemiontClient` (worker process)
-- `@semiont/http-transport` — HTTP transport, OpenAPI types
+- `@semiont/http-transport` — `HttpTransport`, `HttpContentTransport`
 - `@semiont/inference` — InferenceClient for AI operations
-- `@semiont/content` — Content storage URI derivation
+- `@semiont/content` — Resource bytes read from the Archivist (`archivistContentReads`), PDF text-layer extraction, the output byte budget
 - `@semiont/event-sourcing` — Annotation id generation
 - `@semiont/observability` — Spans and job-outcome metrics
 
@@ -64,7 +64,7 @@ interface JobMetadata {
 }
 ```
 
-`userId` is the job's only identity — the DID the gateway verified on the `job:create`. The dispatcher records it as the requester when it accepts a claim, and that record is what lets the knowledge base attribute a write citing this job; a worker never states it. `completedUnits` and `unitCursors` are written by `checkpointUnits` (from `job:checkpoint`, as work lands) and by `failJob` (from `job:fail`), merged across attempts — see Failure discipline below.
+`userId` is the job's only identity — the DID the gateway verified on the `job:create`. The dispatcher records it as the requester when it accepts a claim, and that record is what lets the knowledge base attribute a write citing this job; a worker never states it. `completedUnits` and `unitCursors` are written by the dispatcher, from `job:checkpoint` (as work lands) and from `job:fail`, merged across attempts — see Failure discipline below.
 
 ## Progress
 
@@ -72,7 +72,7 @@ A running job's `progress` is `StoredProgress`: the last `JobProgress` its worke
 
 ## Annotation Workers
 
-The worker process (`worker-main.ts` → `startWorkerProcess` in `worker-process.ts`) claims jobs over the bus via a `JobClaimAdapter` and dispatches by `jobType` to a processor function. There are no per-type worker classes; each job type maps to one `process*Job` function:
+The worker process (`worker-main.ts` → `startAgentWorker` in `worker-runtime.ts` → `startWorkerProcess` in `worker-process.ts`) claims jobs over the bus via a `JobClaimAdapter` and dispatches by `jobType` to a processor function. There are no per-type worker classes; each job type maps to one `process*Job` function:
 
 | Job Type | Processor |
 |----------|-----------|
@@ -83,28 +83,28 @@ The worker process (`worker-main.ts` → `startWorkerProcess` in `worker-process
 | `comment-annotation` | `processCommentJob` |
 | `tag-annotation` | `processTagJob` |
 
-Detection logic lives in the `AnnotationDetection` class (`src/workers/annotation-detection.ts`); generation synthesis in `generateResourceFromTopic()` (`src/workers/generation/resource-generation.ts`). Processors never fetch content themselves — the worker process prepares it with `prepareDetection` (bytes through `contentReads` for text media, the Smelter's anchored text for geometry-bearing media such as PDF) and passes it in.
+Detection logic lives in the `AnnotationDetection` class (`src/workers/annotation-detection.ts`) and, for references, in `extractEntities` (`src/workers/detection/entity-extractor.ts`); generation synthesis in `generateResourceFromTopic()` (`src/workers/generation/resource-generation.ts`). Processors never fetch content themselves — the worker process prepares it with `prepareDetection` (bytes through `contentReads` for text media, the Smelter's anchored text for geometry-bearing media such as PDF) and passes it in.
 
 Workers emit lifecycle events via `session.client.transport.emit('job:start' | 'job:report-progress' | 'job:checkpoint' | 'job:complete' | 'job:fail', payload)` and persist annotations through the **awaited `mark:commit` operation** — a batch per unit of work that resolves only once the Stower actor in @semiont/make-meaning has appended every annotation to the event log. Unit completion and `job:complete` gate on that acknowledgement, never on emission, so a down persistence sink is a retryable failure instead of silent loss. The dispatcher's job command handlers mirror the lifecycle events into the queue (completion, checkpoints, retry-on-failure with `maxRetries`, progress-as-heartbeat). `job:fail` carries the fields the worker computes: `completedUnits` and `unitCursors` (the checkpoint), `failureClass`, and `willRetry` — see Failure discipline.
 
 ## Failure discipline
 
-Long inference work fails in bounded, classified, resumable ways — every piece below was built against a measured production failure, not a hypothetical:
+Long inference work fails in bounded, classified, resumable ways:
 
 - **Every inference call is bounded and truly cancelled.** A call gets 10 minutes (`INFERENCE_TIMEOUT_MS`); at the bound the worker aborts it at the transport (`AbortSignal` through the provider SDK to the socket — milliseconds to rejection, no zombie billing on) and fails the job with a typed `InferenceTimeoutError`. An in-flight heartbeat reports elapsed-time liveness every 15 s during long calls.
-- **Budgets are derived, never tuned** (`workers/detection/detection-chunking.ts`). Input:output allocation is 1:2 per entity type asked for (`input ≤ outputBudget / (2 × typesPerCall)`), and **every** provider gets a duration cap: per-call output is bounded at what the provider's worst-case rate finishes in HALF the bound — the published rate when there is one, a conservative assumed floor (`ASSUMED_OUTPUT_TOKENS_PER_HOUR`, 30 tok/s) for rate-silent providers like Ollama, where an unbounded budget turned model repetition loops into hour-long transient burns.
-- **Size-shaped failures subdivide in place** (`callChunkSubdividing`). Four failure families descend, each with its own floor: a **truncation** descends by size and gets one same-size re-roll at the floor; a **timeout** descends two levels then propagates; an **`'unknown'`-stop unreadable response** (garbage output with no stop reason — measured size-correlated on real documents) descends by size and propagates at the floor; and a **flagged under-report** (below) descends by size, and at the floor its salvage — everything it did find, every span write-time-verified — is **accepted loudly** rather than discarded. A piece that cannot actually shrink is at its floor regardless of arithmetic: at temperature 0, an identical re-run returns the identical failure. Sub-piece overlap duplicates fall to the existing span-keyed dedupe.
-- **Successful-looking extractions are verified** (`assertYieldNotCollapsed`). A local model can return a clean, schema-conforming response carrying a fraction of the entities present — deterministic and otherwise invisible. When the provider declares `verifyDetectionYield` (all real providers do), each chunk's item count is checked against a cheap parallel count call; an extraction under half the count is flagged and subdivided. Every anchoring outcome and every call — including flagged and failed ones — is recorded to `semiont.detection.*` metrics (`@semiont/observability`).
+- **Budgets are derived, never tuned** (`workers/detection/detection-chunking.ts`). Input:output allocation is 1:2 per entity type asked for (`input ≤ outputBudget / (2 × typesPerCall)`), and **every** provider gets a duration cap: per-call output is bounded at what the provider's worst-case rate finishes in HALF the bound — the published rate when there is one, a conservative assumed floor (`ASSUMED_OUTPUT_TOKENS_PER_HOUR`, 30 tok/s) for rate-silent providers like Ollama, where an unbounded budget turns a model repetition loop into an hour-long transient burn.
+- **Size-shaped failures subdivide in place** (`callChunkSubdividing`). Five failure families descend, each with its own floor: a **truncation** descends by size and gets one same-size re-roll at the floor; a **timeout** descends two levels then propagates; an **`'unknown'`-stop unreadable response** (garbage output with no stop reason — measured size-correlated on real documents) descends by size and propagates at the floor; an **unreadable response from a model that finished** (`end_turn`) descends two levels then propagates, as a timeout does; and a **flagged under-report** (below) descends by size, and at the floor its salvage — everything it did find, every span write-time-verified — is **accepted loudly** rather than discarded. A piece that cannot actually shrink is at its floor regardless of arithmetic: at temperature 0, an identical re-run returns the identical failure. Sub-piece overlap duplicates fall to the existing span-keyed dedupe.
+- **Successful-looking extractions are verified** (`assertYieldNotCollapsed`). A local model can return a clean, schema-conforming response carrying a fraction of the entities present — deterministic and otherwise invisible. When the provider declares `verifyDetectionYield` (all real providers do), each chunk's item count is checked against a cheap count call over the same text; an extraction under half the count is flagged and subdivided. Every anchoring outcome and every call — including flagged and failed ones — is recorded to `semiont.detection.*` metrics (`@semiont/observability`).
 - **Entity types run concurrently up to the provider's declared capacity** (`client.maxConcurrency`): a hosted API with rate headroom runs several types at once; a local single-model server runs them sequentially, because concurrent requests only split one GPU. Jobs never switches on provider identity — both behaviors are capabilities declared on the `InferenceClient`.
-- **Failures are classified at the worker, where errors are still typed** (`failure-class.ts`). Only KNOWN-deterministic failures — truncation at the subdivision floor, unsupported media, non-throttle 4xx — skip the retry budget; everything unrecognized stays retryable. The class rides `job:fail` as `failureClass`.
-- **Retries resume from the checkpoint.** Reference-annotation persists each entity type's annotations as that unit completes; completed units ride `job:checkpoint` and `job:fail` into `metadata.completedUnits`, and the retry processes only what's left.
+- **Failures are classified at the worker, where errors are still typed** (`failure-class.ts`). Only KNOWN-deterministic failures — truncation at the subdivision floor, unsupported media, a 4xx other than 408 or 429 — skip the retry budget; everything unrecognized stays retryable. The class rides `job:fail` as `failureClass`.
+- **Retries resume from the checkpoint.** Every detection job commits its annotations chunk by chunk; each committed chunk's cursor rides `job:checkpoint` and `job:fail` into `metadata.unitCursors`, and reference-annotation also records each finished entity type in `metadata.completedUnits`. The retry skips the completed units and resumes each unfinished one from its cursor.
 
 ## Adding a Job Type
 
 Workers are not subclassed. To add a job type:
 
-1. Add the new `JobType` and its params type in `src/types.ts`, and in the spec: the type in `JobType.json`, its category in `specs/src/jobs/storage.json`, and its result schema in the `JobResult` union. There is no progress type — every job reports `JobProgress`.
-2. Add a `process*Job` function in `src/processors.ts` that runs the inference and returns the annotations/result.
+1. Add the new type to the spec: its name in `JobType.json` (`JobType` in `src/types.ts` is generated from it), its category in `specs/src/jobs/storage.json`, and its result schema in the `JobResult` union. Add its params type in `src/types.ts`. There is no progress type — every job reports `JobProgress`.
+2. Add a `process*Job` function in `src/processors.ts` that runs the inference, commits its annotations through the per-chunk callback and returns the result.
 3. Dispatch the new `jobType` to that processor in `handleJobInner()` in `src/worker-process.ts`.
 
 Processors are transport-agnostic: they take content, an `InferenceClient`, the job params, a `buildAnnotation` closure (which carries the `generator` — the worker's own `Software` agent), an `onProgress` callback and a per-chunk commit callback, and return a result. No user identity reaches a processor: an annotation states what produced it, and who requested it is derived by the knowledge base from the job the commit cites. The worker process handles claiming, content fetching, committing, and lifecycle event emission.
@@ -148,6 +148,6 @@ Apache-2.0
 
 - [`@semiont/core`](../core/) — Domain types, `SemiontProject`, EventBus, `BusRequestPrimitive`
 - [`@semiont/sdk`](../sdk/) — `SemiontSession`, `SemiontClient`
-- [`@semiont/http-transport`](../http-transport/) — HTTP transport, OpenAPI types
+- [`@semiont/http-transport`](../http-transport/) — `HttpTransport`, `HttpContentTransport`
 - [`@semiont/inference`](../inference/) — AI inference client
 - [`@semiont/make-meaning`](../make-meaning/) — Actor model, Knowledge Base, service orchestration

package/dist/index.d.ts

@@ -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>;
 }
@@ -226,16 +225,16 @@ 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 {
@@ -286,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'];
@@ -309,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
@@ -324,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, 
 /**
@@ -361,18 +360,18 @@ 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;
@@ -396,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
@@ -423,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.
@@ -497,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[]>;
@@ -510,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[]>;
@@ -523,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[]>;
@@ -541,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`.
  */
 
 /**
@@ -582,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
@@ -619,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.
@@ -641,25 +632,27 @@ interface ActiveJob {
     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;
@@ -686,9 +679,9 @@ interface ClaimRefusal {
     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
@@ -766,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.