@semiont/jobs 0.6.9 → 0.6.11

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.

package/dist/index.js

@@ -9760,7 +9760,8 @@ Example format:
   /**
    * Build a prompt for detecting structural tags
    *
-   * @param content - The full text content to analyze (NOT truncated for structural analysis)
+   * @param content - The text content to analyze — a chunk sized by the
+   *   caller from derived provider limits; NEVER re-truncated here
    * @param category - The specific category to detect
    * @param schemaName - Human-readable schema name
    * @param schemaDescription - Schema description
@@ -10188,7 +10189,7 @@ ${piece}
   }
   if (items.length * YIELD_COLLAPSE_BAND < counted) {
     throw new YieldCollapseError(
-      `Extraction found ${items.length} entities where a count call reports ~${counted} mentions (band \xD7${YIELD_COLLAPSE_BAND}) on a ${piece.length}-char chunk \u2014 silent yield collapse (F7): deterministic \u2014 a same-size retry returns the identical under-report.`,
+      `Extraction found ${items.length} entities where a count call reports ~${counted} mentions (band \xD7${YIELD_COLLAPSE_BAND}) on a ${piece.length}-char chunk \u2014 silent yield collapse: deterministic \u2014 a same-size retry returns the identical under-report.`,
       [...items],
       { found: items.length, counted, pieceChars: piece.length }
     );
@@ -10737,9 +10738,8 @@ async function processCommentJob(content, inferenceClient, params, buildAnnotati
       found += comments.length;
       const fresh = dedupe(comments.map(
         (c) => (
-          // Match the pre-#651 CommentAnnotationWorker: include format and
-          // language on the body TextualBody. Optional in the schema, but
-          // consumers that do language-aware rendering rely on them.
+          // Format and language go on the body TextualBody: optional in the
+          // schema, but consumers that do language-aware rendering rely on them.
           buildAnnotation("commenting", c, [
             { type: "TextualBody", value: c.comment, purpose: "commenting", format: "text/plain", language: bodyLanguage }
           ])
@@ -10780,8 +10780,7 @@ async function processAssessmentJob(content, inferenceClient, params, buildAnnot
       const fresh = dedupe(assessments.map(
         (a) => (
           // Single-object body with purpose aligned to motivation, matching the
-          // pre-#651 AssessmentAnnotationWorker's shape and the majority of
-          // persisted assessments. Do not switch to an array or to
+          // majority of persisted assessments. Do not switch to an array or to
           // purpose='describing' — that loses the "this is an assessment, not
           // a description" signal and breaks existing readers that access
           // `body.value` directly on the object.
@@ -10849,11 +10848,11 @@ async function processReferenceJob(content, inferenceClient, params, buildAnnota
       params.includeDescriptiveReferences ?? false,
       logger,
       params.sourceLanguage,
-      // Liveness heartbeat (DETECTION-HEARTBEAT): fires at chunk boundaries and
-      // every ~15 s while a call is in flight, so a long single-chunk call is
-      // not silent. It repeats the current position rather than inventing an
-      // advance — the stall watchdog, janitor and client timeout need a signal,
-      // not a monotone.
+      // Liveness heartbeat: fires at chunk boundaries and every ~15 s while a
+      // call is in flight, so a long single-chunk call is not silent. It
+      // repeats the current position rather than inventing an advance — the
+      // stall watchdog, janitor and client timeout need a signal, not a
+      // monotone.
       () => emitTypeProgress(entityTypeName),
       (verdict) => {
         underReported = {
@@ -11010,7 +11009,7 @@ async function processGenerationJob(inferenceClient, params, onProgress, logger)
       `Unsupported outputMediaType for generation: ${outputMediaType}. Generation produces ${GENERATABLE_MEDIA_TYPES.join(" or ")}.`
     );
   }
-  const title = params.title ?? "Untitled";
+  const title = params.title;
   const entityTypes = (params.entityTypes ?? []).map(String);
   if (outputMediaType === "application/pdf") {
     onProgress(5, { code: "generating-resource" });
@@ -11289,26 +11288,25 @@ var WORKER_AWAITED_OPERATIONS = [
   "job:claim",
   "browse:resource-requested",
   // Canonical geometry for a geometry-bearing detection: the consult behind
-  // `ConsultAnchoredText` (SMELTER-OWNS-OCR P2). Its omission broke every
-  // PDF detection job at the transport probe
-  // (.plans/WORKER-ANCHORED-TEXT-CHANNEL.md); the census below now fails the
+  // `ConsultAnchoredText`, answered by the Smelter. Without it every PDF
+  // detection job fails at the transport probe; the census below fails the
   // BUILD when this list and the declared awaits drift.
   "browse:anchored-text-requested",
-  // Durability acknowledgement for a unit's annotations (JOB-RESTART-SAFETY
-  // P6). The worker AWAITS this one — a unit may not advance until its
-  // annotations are in the event log — so its replies must be in the narrow
-  // channel set or every commit fails fast with `bus.unsubscribed`.
+  // Durability acknowledgement for a unit's annotations. The worker AWAITS
+  // this one — a unit may not advance until its annotations are in the event
+  // log — so its replies must be in the narrow channel set or every commit
+  // fails fast with `bus.unsubscribed`.
   "mark:commit",
-  // The durability probe for a commit whose acknowledgement never routed
-  // (COMMIT-ACK-FALSE-FAILURE F1). SINGULAR by design: the annotation LIST
-  // channel is the multi-MB fan-out this narrowing exists to keep out, and a
-  // rare error path is no reason to let it back in.
+  // The durability probe for a commit whose acknowledgement never routed.
+  // SINGULAR by design: the annotation LIST channel is the multi-MB fan-out
+  // this narrowing exists to keep out, and a rare error path is no reason to
+  // let it in.
   "browse:annotation-requested"
 ];
 var WORKER_CONSUMED_BROADCASTS = [
   // The queue announcement the claim adapter races for.
   "job:queued",
-  // Cooperative cancellation of the ACTIVE job (JOB-RESTART-SAFETY P4).
+  // Cooperative cancellation of the ACTIVE job: it stops at a unit boundary.
   "job:cancel-requested"
 ];
 var WORKER_CHANNELS = [