@semiont/jobs 0.5.34 → 0.5.35

package/dist/worker-main.js

@@ -1,4 +1,4 @@
-import { replyChannelsFor, createTomlConfigLoader, didToAgent, baseUrl, STARTUP_FETCH_RETRY, retryWithBackoff, isTransientFetchError, isObject, isString, isNumber, busRequest, isArray, resourceId, getPrimaryMediaType, isGenerationJobParams, capabilitiesOf, assembleAnnotation, findClaimSpan, textSourceOf, yieldsGeometryOf, decodeRepresentation, GENERATABLE_MEDIA_TYPES, BusRequestError, locate, createFragmentSelector, deriveViews, annotationId, estimateTokens, chunkText, reconcileSelector, getLocaleEnglishName } from '@semiont/core';
+import { replyChannelsFor, createTomlConfigLoader, didToAgent, baseUrl, STARTUP_FETCH_RETRY, retryWithBackoff, isTransientFetchError, isObject, isString, isNumber, RETRY_RULES, busRequest, isArray, resourceId, getPrimaryMediaType, isGenerationJobParams, capabilitiesOf, assembleAnnotation, findClaimSpan, textSourceOf, yieldsGeometryOf, decodeRepresentation, GENERATABLE_MEDIA_TYPES, BusRequestError, locate, createFragmentSelector, deriveViews, annotationId, estimateTokens, reconcileSelector, getLocaleEnglishName, cutChunk, chunkText } from '@semiont/core';
 import { archivistContentReads, extractPdfTextLayer, withinByteBudget, MAX_PDF_BYTES } from '@semiont/content';
 import { withSpan, SpanKind, recordJobOutcome, recordAnchorOutcome, recordDetectionCall } from '@semiont/observability';
 import { createInferenceClient, StructuredReadError } from '@semiont/inference';
@@ -9208,31 +9208,22 @@ var require_cjs = __commonJS({
 
 // src/job-claim-adapter.ts
 var import_rxjs = __toESM(require_cjs());
-
-// src/worker-bus-primitive.ts
-function workerBusAsPrimitive(bus) {
-  return {
-    emit(channel, payload) {
-      return bus.emit(channel, payload);
-    },
-    stream(channel) {
-      return bus.on$(channel);
-    },
-    // Pass the real connection state through: a worker's first `job:claim`
-    // fires right after connect — exactly the attach-window emit the gate
-    // exists for (.plans/BUS-ATTACH-GATE.md).
-    state$: bus.state$,
-    // Pass the subscription probe through so a request against a transport
-    // whose narrowed channel set omits the replies fails fast
-    // (`bus.unsubscribed`) instead of timing out.
-    ...bus.isSubscribed ? { isSubscribed: (channel) => bus.isSubscribed(channel) } : {}
-  };
+function readUnitCursors(raw, completedUnits) {
+  if (!isObject(raw)) return {};
+  const done = new Set(completedUnits);
+  const cursors = {};
+  for (const [unit, value] of Object.entries(raw)) {
+    if (done.has(unit) || !isObject(value)) continue;
+    const { next, size, found, emitted } = value;
+    if (!isNumber(next) || !isNumber(size) || next < 0 || size < 1) continue;
+    if (!isNumber(found) || !isNumber(emitted) || found < 0 || emitted < 0) continue;
+    cursors[unit] = { next, size, found, emitted };
+  }
+  return cursors;
 }
-
-// src/job-claim-adapter.ts
 function createJobClaimAdapter(options) {
   const { bus, jobTypes } = options;
-  const requestBus = workerBusAsPrimitive(bus);
+  const requestBus = bus;
   const activeJob$ = new import_rxjs.BehaviorSubject(null);
   const isProcessing$ = new import_rxjs.BehaviorSubject(false);
   const jobsCompleted$ = new import_rxjs.BehaviorSubject(0);
@@ -9249,6 +9240,7 @@ function createJobClaimAdapter(options) {
     try {
       const job = await busRequest(requestBus, "job:claim", { jobId: assignment.jobId }, 1e4);
       const completedUnits = isArray(job.metadata?.completedUnits) ? job.metadata.completedUnits.filter(isString) : [];
+      const unitCursors = readUnitCursors(job.metadata?.unitCursors, completedUnits);
       return {
         jobId: assignment.jobId,
         type: assignment.type,
@@ -9256,6 +9248,7 @@ function createJobClaimAdapter(options) {
         userId: job.metadata?.userId ?? "",
         params: job.params ?? {},
         completedUnits,
+        unitCursors,
         // Absent or malformed metadata reads as "no budget left" — a worker
         // that cannot see the budget must not claim a retry is coming.
         retryCount: isNumber(job.metadata?.retryCount) ? job.metadata.retryCount : 0,
@@ -9274,7 +9267,7 @@ function createJobClaimAdapter(options) {
       if (started) return;
       started = true;
       bus.addChannels?.(["job:queued"]);
-      jobSubscription = bus.on$("job:queued").subscribe((event) => {
+      jobSubscription = bus.stream("job:queued").subscribe((event) => {
         lastQueuedEventAt = Date.now();
         const jobType = event.jobType;
         if (jobTypes.length > 0 && !jobTypes.includes(jobType)) return;
@@ -9452,16 +9445,39 @@ function classifyFailure(error) {
   if (name === "APIUserAbortError" || name === "AbortError") return "transient";
   const status = isNumber(error.status) ? error.status : void 0;
   if (status !== void 0) {
-    if (status === 408 || status === 429 || status >= 500) return "transient";
+    if (RETRY_RULES.job.retryable({ status })) return "transient";
     if (status >= 400) return "deterministic";
   }
   return void 0;
 }
 
+// src/workers/detection/chunk-size-controller.ts
+var DEFAULT_CHUNK_SIZING_POLICY = {
+  growBelow: 0.5,
+  shrinkAbove: 0.8,
+  growFactor: 1.5,
+  shrinkFactor: 0.7
+};
+function clamp(value, lo, hi) {
+  return Math.max(lo, Math.min(hi, value));
+}
+function nextChunkSize(outcome, current, bounds, policy = DEFAULT_CHUNK_SIZING_POLICY) {
+  const grow = () => clamp(Math.floor(current * policy.growFactor), bounds.floor, bounds.ceiling);
+  const shrink = () => clamp(Math.floor(current * policy.shrinkFactor), bounds.floor, bounds.ceiling);
+  const hold = () => clamp(current, bounds.floor, bounds.ceiling);
+  if (outcome.truncated) return shrink();
+  if (outcome.outputTokens === void 0) return hold();
+  if (bounds.outputBudget <= 0) return hold();
+  const utilization = outcome.outputTokens / bounds.outputBudget;
+  if (utilization < policy.growBelow) return grow();
+  if (utilization > policy.shrinkAbove) return shrink();
+  return hold();
+}
+
 // src/workers/detection/detection-chunking.ts
-function assertNotTruncated(response, label, chunk, totalChunks, outputBudget) {
+function assertNotTruncated(response, label, at, totalChars, outputBudget) {
   if (response.stopReason === "max_tokens") {
-    throw new DeterministicJobError(`${label} response truncated (max_tokens) on chunk ${chunk}/${totalChunks} despite the derived output budget of ${outputBudget} tokens \u2014 failing the job rather than under-reporting annotations.`);
+    throw new DeterministicJobError(`${label} response truncated (max_tokens) at character ${at} of ${totalChars} despite the derived output budget of ${outputBudget} tokens \u2014 failing the job rather than under-reporting annotations.`);
   }
 }
 var SELECTOR_CONTEXT_CHARS = 64;
@@ -9512,6 +9528,7 @@ function deriveDetectionBudget(limits, scaffoldTokens, typesPerCall) {
       outputBudget = durationSafeOutput;
     }
   }
+  const capacityInput = contextTokens - scaffoldTokens - outputBudget;
   inputBudget = Math.min(inputBudget, Math.floor(outputBudget / (2 * typesPerCall)));
   if (inputBudget <= OVERLAP_TOKENS) {
     throw new Error(
@@ -9520,15 +9537,41 @@ function deriveDetectionBudget(limits, scaffoldTokens, typesPerCall) {
   }
   return {
     chunking: { chunkSize: inputBudget, overlap: OVERLAP_TOKENS },
-    outputBudget
+    outputBudget,
+    bounds: {
+      // Two overlaps: at the floor a chunk is still half text it has not seen
+      // before, so the cursor keeps making progress rather than re-reading its
+      // own tail. Clamped under the opening size, because a cramped window can
+      // derive an opening below even that — and a floor above the opening would
+      // clamp every proposal upward, silently reversing the sizer.
+      floor: Math.min(inputBudget, 2 * OVERLAP_TOKENS),
+      // Never below the opening: a degenerate window can make the fit
+      // arithmetic smaller than the size already chosen, and a ceiling under
+      // the opening would clamp every proposal DOWN on the first call.
+      ceiling: Math.max(inputBudget, capacityInput),
+      outputBudget
+    }
   };
 }
+async function runAdaptiveChunks(text, budget, onChunk, resume) {
+  let at = resume?.next ?? 0;
+  let size = resume ? nextChunkSize({ truncated: true }, resume.size, budget.bounds) : budget.chunking.chunkSize;
+  while (at < text.length) {
+    const { piece, next } = cutChunk(text, at, { chunkSize: size, overlap: budget.chunking.overlap });
+    const outcome = await onChunk({ piece, size, at, next, totalChars: text.length });
+    at = next;
+    size = nextChunkSize(outcome, size, budget.bounds);
+  }
+}
 var MAX_SUBDIVISION_DEPTH = 2;
 function unknownUnreadable(error) {
   return error instanceof StructuredReadError && error.stopReason === "unknown";
 }
+function unreadableDespiteFinishing(error) {
+  return error instanceof StructuredReadError && error.stopReason === "end_turn";
+}
 function subdividable(error) {
-  return error instanceof InferenceTimeoutError || truncation(error) || unknownUnreadable(error);
+  return error instanceof InferenceTimeoutError || truncation(error) || unknownUnreadable(error) || unreadableDespiteFinishing(error);
 }
 function truncation(error) {
   return error instanceof DeterministicJobError || error instanceof StructuredReadError && error.stopReason === "max_tokens";
@@ -9540,10 +9583,19 @@ function outcomeOf(error) {
   return "error";
 }
 async function callChunkSubdividing(label, chunk, chunking, call, logger2, onUnderReport, onCounted) {
+  let outputTokens = 0;
+  let sizeShaped = false;
+  let callsMade = 0;
+  let callsMeasured = 0;
   async function recorded(piece, depth, reroll) {
     const start = performance.now();
     try {
       const result = await call(piece);
+      callsMade += 1;
+      if (result.usage) {
+        callsMeasured += 1;
+        outputTokens += result.usage.outputTokens;
+      }
       recordDetectionCall({
         label,
         pieceChars: piece.length,
@@ -9574,6 +9626,7 @@ async function callChunkSubdividing(label, chunk, chunking, call, logger2, onUnd
       return (await recorded(piece, depth, false)).items;
     } catch (error) {
       if (!subdividable(error)) throw error;
+      sizeShaped = true;
       const half = Math.floor(chunkSize / 2);
       const pieces = chunkText(piece, { chunkSize: half, overlap: chunking.overlap });
       const shrinks = pieces.length > 1 || pieces[0] !== piece;
@@ -9609,7 +9662,12 @@ async function callChunkSubdividing(label, chunk, chunking, call, logger2, onUnd
       return collected;
     }
   }
-  return attempt(chunk, chunking.chunkSize, 0);
+  const items = await attempt(chunk, chunking.chunkSize, 0);
+  const measured = callsMade > 0 && callsMeasured === callsMade;
+  return {
+    items,
+    outcome: { truncated: sizeShaped, ...measured ? { outputTokens } : {} }
+  };
 }
 function languageName(tag) {
   return getLocaleEnglishName(tag) || tag;
@@ -10110,33 +10168,37 @@ function logAnchorMethod(motivation, exact, anchorMethod) {
 }
 
 // src/workers/annotation-detection.ts
-async function detectInChunks(client, content, buildPrompt, motivation, elementSchema, parse, onActivity, onChunkResults) {
+async function detectInChunks(client, content, buildPrompt, motivation, elementSchema, parse, onActivity, resume, onChunkResults) {
   const limits = await client.limits();
   const scaffoldTokens = estimateTokens(buildPrompt(""));
-  const { chunking, outputBudget } = deriveDetectionBudget(limits, scaffoldTokens, 1);
-  const chunks = chunkText(content, chunking);
+  const budget = deriveDetectionBudget(limits, scaffoldTokens, 1);
+  const { outputBudget } = budget;
   const collected = [];
-  for (let i = 0; i < chunks.length; i++) {
-    const items = await callChunkSubdividing(motivation, chunks[i], chunking, async (piece) => {
-      const response = await boundedGenerateStructured(
-        client,
-        buildPrompt(piece),
-        outputBudget,
-        DETECTION_TEMPERATURE,
-        elementSchema,
-        // Still alive, same position (a long single call is otherwise silent).
-        () => onActivity?.(i, chunks.length)
-      );
-      assertNotTruncated(response, `${motivation} detection`, i + 1, chunks.length, outputBudget);
-      return { items: response.items, ...response.usage ? { usage: response.usage } : {} };
-    });
+  await runAdaptiveChunks(content, budget, async ({ piece: chunk, size, at, next, totalChars }) => {
+    const { items, outcome } = await callChunkSubdividing(
+      motivation,
+      chunk,
+      { chunkSize: size, overlap: budget.chunking.overlap },
+      async (piece) => {
+        const response = await boundedGenerateStructured(
+          client,
+          buildPrompt(piece),
+          outputBudget,
+          DETECTION_TEMPERATURE,
+          elementSchema,
+          // Still alive, same position (a long single call is otherwise silent).
+          () => onActivity?.(at, totalChars)
+        );
+        assertNotTruncated(response, `${motivation} detection`, at, totalChars, outputBudget);
+        return { items: response.items, ...response.usage ? { usage: response.usage } : {} };
+      }
+    );
     const fromChunk = parse(items);
     collected.push(...fromChunk);
-    await onChunkResults?.(fromChunk);
-    if (i < chunks.length - 1) {
-      onActivity?.(i + 1, chunks.length);
-    }
-  }
+    await onChunkResults?.(fromChunk, { next, size });
+    if (next < totalChars) onActivity?.(next, totalChars);
+    return outcome;
+  }, resume);
   return collected;
 }
 var AnnotationDetection = class {
@@ -10148,7 +10210,7 @@ var AnnotationDetection = class {
    * (source-resource locale). See `types.ts` "Locale conventions" for the
    * full discussion.
    */
-  static async detectComments(content, client, instructions, tone, density, language, sourceLanguage, onActivity, onChunkResults) {
+  static async detectComments(content, client, instructions, tone, density, language, sourceLanguage, onActivity, resume, onChunkResults) {
     return detectInChunks(
       client,
       content,
@@ -10157,6 +10219,7 @@ var AnnotationDetection = class {
       COMMENT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseComments(items, content),
       onActivity,
+      resume,
       onChunkResults
     );
   }
@@ -10167,7 +10230,7 @@ var AnnotationDetection = class {
    * applies, used in the prompt so the LLM analyzes non-English source
    * correctly.
    */
-  static async detectHighlights(content, client, instructions, density, sourceLanguage, onActivity, onChunkResults) {
+  static async detectHighlights(content, client, instructions, density, sourceLanguage, onActivity, resume, onChunkResults) {
     return detectInChunks(
       client,
       content,
@@ -10176,6 +10239,7 @@ var AnnotationDetection = class {
       HIGHLIGHT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseHighlights(items, content),
       onActivity,
+      resume,
       onChunkResults
     );
   }
@@ -10186,7 +10250,7 @@ var AnnotationDetection = class {
    * (annotation body locale). `sourceLanguage` is the locale of the content
    * being analyzed (source-resource locale).
    */
-  static async detectAssessments(content, client, instructions, tone, density, language, sourceLanguage, onActivity, onChunkResults) {
+  static async detectAssessments(content, client, instructions, tone, density, language, sourceLanguage, onActivity, resume, onChunkResults) {
     return detectInChunks(
       client,
       content,
@@ -10195,6 +10259,7 @@ var AnnotationDetection = class {
       ASSESSMENT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseAssessments(items, content),
       onActivity,
+      resume,
       onChunkResults
     );
   }
@@ -10210,7 +10275,7 @@ var AnnotationDetection = class {
    * identifiers, not LLM-generated text — so it's consumed at the body-stamp
    * site, not here.
    */
-  static async detectTags(content, client, schema, category, sourceLanguage, onActivity, onChunkResults) {
+  static async detectTags(content, client, schema, category, sourceLanguage, onActivity, resume, onChunkResults) {
     const categoryInfo = schema.tags.find((t) => t.name === category);
     if (!categoryInfo) {
       throw new Error(`Invalid category "${category}" for schema ${schema.id}`);
@@ -10232,7 +10297,8 @@ var AnnotationDetection = class {
       TAG_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseTags(items),
       onActivity,
-      onChunkResults ? async (raw) => onChunkResults(MotivationParsers.validateTagOffsets(raw, content, category)) : void 0
+      resume,
+      onChunkResults ? async (raw, cursor) => onChunkResults(MotivationParsers.validateTagOffsets(raw, content, category), cursor) : void 0
     );
     return MotivationParsers.validateTagOffsets(parsedTags, content, category);
   }
@@ -10284,7 +10350,7 @@ ${piece}
   }
   return counted;
 }
-async function extractEntities(exact, entityTypes, client, includeDescriptiveReferences, logger2, sourceLanguage, onActivity, onUnderReport, onCounted, onChunkResults) {
+async function extractEntities(exact, entityTypes, client, includeDescriptiveReferences, logger2, sourceLanguage, onActivity, onUnderReport, onCounted, resume, onChunkResults) {
   const entityTypesDescription = entityTypes.map((et) => {
     if (typeof et === "string") {
       return et;
@@ -10336,42 +10402,55 @@ Example output:
   const limits = await client.limits();
   const verifyYield = client.verifyDetectionYield;
   const scaffoldTokens = estimateTokens(buildPrompt(""));
-  const { chunking, outputBudget } = deriveDetectionBudget(limits, scaffoldTokens, entityTypes.length);
-  const chunks = chunkText(exact, chunking);
+  const budget = deriveDetectionBudget(limits, scaffoldTokens, entityTypes.length);
+  const { chunking, outputBudget } = budget;
   logger2.debug("Sending entity extraction request", {
     entityTypes: entityTypesDescription,
-    chunks: chunks.length,
-    chunkSizeTokens: chunking.chunkSize,
+    chars: exact.length,
+    // The size the run OPENS at, and how far measured yield may move it. The
+    // chunk COUNT is deliberately absent: with sizing decided as the run goes,
+    // there is no honest total until the cursor reaches the end.
+    openingChunkSizeTokens: chunking.chunkSize,
+    ceilingChunkSizeTokens: budget.bounds.ceiling,
     outputBudget
   });
   const collected = [];
-  for (let i = 0; i < chunks.length; i++) {
-    const items = await callChunkSubdividing("reference", chunks[i], chunking, async (piece) => {
-      const response = await boundedGenerateStructured(
-        client,
-        buildPrompt(piece),
-        outputBudget,
-        DETECTION_TEMPERATURE,
-        ENTITY_ELEMENT_SCHEMA,
-        // Still alive, same position: a long single call would otherwise emit
-        // nothing at all between start and finish.
-        () => onActivity?.(i, chunks.length),
-        logger2
-      );
-      logger2.debug("Got entity extraction response", {
-        chunk: i + 1,
-        chunks: chunks.length,
-        pieceChars: piece.length,
-        items: response.items.length
-      });
-      assertNotTruncated(response, "Entity extraction", i + 1, chunks.length, outputBudget);
-      const counted = verifyYield ? await assertYieldNotCollapsed(client, piece, response.items, entityTypesDescription, logger2) : void 0;
-      return {
-        items: response.items,
-        ...response.usage ? { usage: response.usage } : {},
-        ...counted !== void 0 ? { counted } : {}
-      };
-    }, logger2, onUnderReport, onCounted);
+  await runAdaptiveChunks(exact, budget, async ({ piece: chunk, size, at, next, totalChars }) => {
+    const { items, outcome } = await callChunkSubdividing(
+      "reference",
+      chunk,
+      { chunkSize: size, overlap: chunking.overlap },
+      async (piece) => {
+        const response = await boundedGenerateStructured(
+          client,
+          buildPrompt(piece),
+          outputBudget,
+          DETECTION_TEMPERATURE,
+          ENTITY_ELEMENT_SCHEMA,
+          // Still alive, same position: a long single call would otherwise emit
+          // nothing at all between start and finish.
+          () => onActivity?.(at, totalChars),
+          logger2
+        );
+        logger2.debug("Got entity extraction response", {
+          at,
+          totalChars,
+          chunkSizeTokens: size,
+          pieceChars: piece.length,
+          items: response.items.length
+        });
+        assertNotTruncated(response, "Entity extraction", at, totalChars, outputBudget);
+        const counted = verifyYield ? await assertYieldNotCollapsed(client, piece, response.items, entityTypesDescription, logger2) : void 0;
+        return {
+          items: response.items,
+          ...response.usage ? { usage: response.usage } : {},
+          ...counted !== void 0 ? { counted } : {}
+        };
+      },
+      logger2,
+      onUnderReport,
+      onCounted
+    );
     const fromChunk = [];
     for (const e of items) {
       if (isObject(e) && isString(e.exact) && isString(e.entityType)) {
@@ -10386,11 +10465,10 @@ Example output:
       }
     }
     collected.push(...fromChunk);
-    await onChunkResults?.(fromChunk);
-    if (i < chunks.length - 1) {
-      onActivity?.(i + 1, chunks.length);
-    }
-  }
+    await onChunkResults?.(fromChunk, { next, size });
+    if (next < totalChars) onActivity?.(next, totalChars);
+    return outcome;
+  }, resume);
   return collected;
 }
 function getLanguageName(locale) {
@@ -10855,13 +10933,14 @@ function buildPdfAnnotation(anchored, resourceId, userId, generator, motivation,
     ...body !== void 0 ? { body } : {}
   };
 }
-async function processHighlightJob(content, inferenceClient, params, buildAnnotation, onProgress, onChunkComplete) {
+async function processHighlightJob(content, inferenceClient, params, buildAnnotation, onProgress, onChunkComplete, resumeCursors) {
   const echo = detectionEcho(params);
   onProgress(10, { code: "loading" }, echo);
   onProgress(30, { code: "analyzing" }, echo);
   const dedupe = makeSpanDeduper();
-  let found = 0;
-  let created = 0;
+  const prior = resumeCursors?.["highlighting"];
+  let found = prior?.found ?? 0;
+  let created = prior?.emitted ?? 0;
   await AnnotationDetection.detectHighlights(
     content,
     inferenceClient,
@@ -10869,13 +10948,14 @@ async function processHighlightJob(content, inferenceClient, params, buildAnnota
     params.density,
     params.sourceLanguage,
     // Liveness (chunk boundaries + in-flight heartbeat): 30–60 band.
-    (completed, total) => onProgress(30 + Math.round(completed / total * 30), { code: "analyzing" }, echo),
-    async (matches) => {
+    (consumedChars, totalChars) => onProgress(30 + Math.round(consumedChars / totalChars * 30), { code: "analyzing" }, echo),
+    resumeCursors?.["highlighting"],
+    async (matches, cursor) => {
       found += matches.length;
       const fresh = dedupe(matches.map((h) => buildAnnotation("highlighting", h)));
       created += fresh.length;
       onProgress(60, { code: "creating-annotations", count: created }, echo);
-      await onChunkComplete(fresh);
+      await onChunkComplete(fresh, { unit: "highlighting", cursor: { ...cursor, found, emitted: created } });
     }
   );
   onProgress(100, { code: "complete-created", count: created, kind: "highlight" }, echo);
@@ -10890,14 +10970,15 @@ function detectionEcho(p) {
   if (p.density !== void 0) requestParams.push({ label: "density", value: String(p.density) });
   return requestParams.length > 0 ? { requestParams } : {};
 }
-async function processCommentJob(content, inferenceClient, params, buildAnnotation, onProgress, onChunkComplete) {
+async function processCommentJob(content, inferenceClient, params, buildAnnotation, onProgress, onChunkComplete, resumeCursors) {
   const echo = detectionEcho(params);
   onProgress(10, { code: "loading" }, echo);
   onProgress(30, { code: "analyzing" }, echo);
   const bodyLanguage = params.language ?? "en";
   const dedupe = makeSpanDeduper();
-  let found = 0;
-  let created = 0;
+  const prior = resumeCursors?.["commenting"];
+  let found = prior?.found ?? 0;
+  let created = prior?.emitted ?? 0;
   await AnnotationDetection.detectComments(
     content,
     inferenceClient,
@@ -10907,8 +10988,9 @@ async function processCommentJob(content, inferenceClient, params, buildAnnotati
     params.language,
     params.sourceLanguage,
     // Liveness (chunk boundaries + in-flight heartbeat): 30–60 band.
-    (completed, total) => onProgress(30 + Math.round(completed / total * 30), { code: "analyzing" }, echo),
-    async (comments) => {
+    (consumedChars, totalChars) => onProgress(30 + Math.round(consumedChars / totalChars * 30), { code: "analyzing" }, echo),
+    resumeCursors?.["commenting"],
+    async (comments, cursor) => {
       found += comments.length;
       const fresh = dedupe(comments.map(
         (c) => (
@@ -10922,7 +11004,7 @@ async function processCommentJob(content, inferenceClient, params, buildAnnotati
       ));
       created += fresh.length;
       onProgress(60, { code: "creating-annotations", count: created }, echo);
-      await onChunkComplete(fresh);
+      await onChunkComplete(fresh, { unit: "commenting", cursor: { ...cursor, found, emitted: created } });
     }
   );
   onProgress(100, { code: "complete-created", count: created, kind: "comment" }, echo);
@@ -10930,14 +11012,15 @@ async function processCommentJob(content, inferenceClient, params, buildAnnotati
     result: { kind: "comment-annotation", commentsFound: found, commentsCreated: created }
   };
 }
-async function processAssessmentJob(content, inferenceClient, params, buildAnnotation, onProgress, onChunkComplete) {
+async function processAssessmentJob(content, inferenceClient, params, buildAnnotation, onProgress, onChunkComplete, resumeCursors) {
   const echo = detectionEcho(params);
   onProgress(10, { code: "loading" }, echo);
   onProgress(30, { code: "analyzing" }, echo);
   const bodyLanguage = params.language ?? "en";
   const dedupe = makeSpanDeduper();
-  let found = 0;
-  let created = 0;
+  const prior = resumeCursors?.["assessing"];
+  let found = prior?.found ?? 0;
+  let created = prior?.emitted ?? 0;
   await AnnotationDetection.detectAssessments(
     content,
     inferenceClient,
@@ -10947,8 +11030,9 @@ async function processAssessmentJob(content, inferenceClient, params, buildAnnot
     params.language,
     params.sourceLanguage,
     // Liveness (chunk boundaries + in-flight heartbeat): 30–60 band.
-    (completed, total) => onProgress(30 + Math.round(completed / total * 30), { code: "analyzing" }, echo),
-    async (assessments) => {
+    (consumedChars, totalChars) => onProgress(30 + Math.round(consumedChars / totalChars * 30), { code: "analyzing" }, echo),
+    resumeCursors?.["assessing"],
+    async (assessments, cursor) => {
       found += assessments.length;
       const fresh = dedupe(assessments.map(
         (a) => (
@@ -10969,7 +11053,7 @@ async function processAssessmentJob(content, inferenceClient, params, buildAnnot
       ));
       created += fresh.length;
       onProgress(60, { code: "creating-annotations", count: created }, echo);
-      await onChunkComplete(fresh);
+      await onChunkComplete(fresh, { unit: "assessing", cursor: { ...cursor, found, emitted: created } });
     }
   );
   onProgress(100, { code: "complete-created", count: created, kind: "assessment" }, echo);
@@ -10977,12 +11061,12 @@ async function processAssessmentJob(content, inferenceClient, params, buildAnnot
     result: { kind: "assessment-annotation", assessmentsFound: found, assessmentsCreated: created }
   };
 }
-async function processReferenceJob(content, inferenceClient, params, buildAnnotation, onProgress, logger2, onUnitComplete, signal, onChunkComplete) {
+async function processReferenceJob(content, inferenceClient, params, buildAnnotation, onProgress, logger2, onUnitComplete, signal, onChunkComplete, resumeCursors) {
   const entityTypeNames = params.entityTypes.map(String);
   const requestParams = [{ label: "entity-types", value: entityTypeNames.join(", ") }];
   const completedItems = [];
-  let totalFound = 0;
-  let totalEmitted = 0;
+  let totalFound = Object.values(resumeCursors ?? {}).reduce((n, c) => n + c.found, 0);
+  let totalEmitted = Object.values(resumeCursors ?? {}).reduce((n, c) => n + c.emitted, 0);
   let errors = 0;
   let totalUnderReportedPieces = 0;
   let totalExpected = 0;
@@ -11011,8 +11095,9 @@ async function processReferenceJob(content, inferenceClient, params, buildAnnota
       { type: "TextualBody", value: entityTypeName, purpose: "tagging", format: "text/plain", language: bodyLanguage }
     ];
     const dedupe = makeSpanDeduper();
-    let unitFound = 0;
-    let unitPersisted = 0;
+    const priorUnit = resumeCursors?.[entityTypeName];
+    let unitFound = priorUnit?.found ?? 0;
+    let unitPersisted = priorUnit?.emitted ?? 0;
     let underReported;
     await extractEntities(
       content,
@@ -11038,7 +11123,8 @@ async function processReferenceJob(content, inferenceClient, params, buildAnnota
         totalExpected += counted;
         emitTypeProgress(entityTypeName);
       },
-      async (chunkEntities) => {
+      resumeCursors?.[entityTypeName],
+      async (chunkEntities, cursor) => {
         const built = [];
         for (const entity of chunkEntities) {
           const reconciled = reconcileSelector(content, {
@@ -11058,9 +11144,14 @@ async function processReferenceJob(content, inferenceClient, params, buildAnnota
           built.push(buildAnnotation("linking", toMatch(reconciled), unresolvedBody));
         }
         const fresh = dedupe(built);
-        await onChunkComplete?.(fresh);
-        unitFound += chunkEntities.length;
-        unitPersisted += fresh.length;
+        const nextFound = unitFound + chunkEntities.length;
+        const nextEmitted = unitPersisted + fresh.length;
+        await onChunkComplete?.(fresh, {
+          unit: entityTypeName,
+          cursor: { ...cursor, found: nextFound, emitted: nextEmitted }
+        });
+        unitFound = nextFound;
+        unitPersisted = nextEmitted;
         totalFound += chunkEntities.length;
         totalEmitted += fresh.length;
         emitTypeProgress(entityTypeName);
@@ -11092,13 +11183,13 @@ async function processReferenceJob(content, inferenceClient, params, buildAnnota
     }
   };
 }
-async function processTagJob(content, inferenceClient, params, buildAnnotation, onProgress, onChunkComplete) {
+async function processTagJob(content, inferenceClient, params, buildAnnotation, onProgress, onChunkComplete, resumeCursors) {
   onProgress(10, { code: "loading" });
   onProgress(30, { code: "analyzing-tags" });
   const bodyLanguage = params.language ?? "en";
   const dedupe = makeSpanDeduper();
   let found = 0;
-  let created = 0;
+  let created = Object.values(resumeCursors ?? {}).reduce((n, c) => n + c.emitted, 0);
   const byCategory = {};
   const completedItems = [];
   for (let c = 0; c < params.categories.length; c++) {
@@ -11114,7 +11205,9 @@ async function processTagJob(content, inferenceClient, params, buildAnnotation,
       { code: "analyzing-tags" },
       position()
     );
-    let categoryFound = 0;
+    const priorCategory = resumeCursors?.[category];
+    let categoryFound = priorCategory?.found ?? 0;
+    let categoryCreated = priorCategory?.emitted ?? 0;
     await AnnotationDetection.detectTags(
       content,
       inferenceClient,
@@ -11123,12 +11216,13 @@ async function processTagJob(content, inferenceClient, params, buildAnnotation,
       params.sourceLanguage,
       // Liveness (chunk boundaries + in-flight heartbeat): this category's
       // slice of the 30–60 band.
-      (completed, total) => onProgress(
-        30 + Math.round((c + completed / total) / params.categories.length * 30),
+      (consumedChars, totalChars) => onProgress(
+        30 + Math.round((c + consumedChars / totalChars) / params.categories.length * 30),
         { code: "analyzing-tags" },
         position()
       ),
-      async (matches) => {
+      resumeCursors?.[category],
+      async (matches, cursor) => {
         categoryFound += matches.length;
         const fresh = dedupe(matches.map((t) => {
           const cat = t.category ?? "unknown";
@@ -11144,7 +11238,11 @@ async function processTagJob(content, inferenceClient, params, buildAnnotation,
           byCategory[cat] = (byCategory[cat] ?? 0) + 1;
         }
         onProgress(60, { code: "creating-tag-annotations", count: created });
-        await onChunkComplete(fresh);
+        categoryCreated += fresh.length;
+        await onChunkComplete(fresh, {
+          unit: category,
+          cursor: { ...cursor, found: categoryFound, emitted: categoryCreated }
+        });
       }
     );
     found += categoryFound;
@@ -11356,7 +11454,7 @@ async function commitAnnotations(session, resourceId, annotations) {
   if (annotations.length === 0) return void 0;
   try {
     await busRequest(
-      workerBusAsPrimitive(session.client.transport.actor),
+      session.client.transport.actor,
       "mark:commit",
       { resourceId, annotations },
       MARK_COMMIT_TIMEOUT_MS
@@ -11399,6 +11497,7 @@ function startWorkerProcess(config) {
     jobTypes: config.jobTypes
   });
   const completedUnitsByJob = /* @__PURE__ */ new Map();
+  const unitCursorsByJob = /* @__PURE__ */ new Map();
   let activeCancel = null;
   httpTransport.actor.addChannels?.(["job:cancel-requested"]);
   httpTransport.on("job:cancel-requested", (event) => {
@@ -11413,14 +11512,17 @@ function startWorkerProcess(config) {
     logger2.info("Processing job", { jobId: job.jobId, type: job.type, resourceId: job.resourceId });
     const controller = new AbortController();
     activeCancel = { jobId: job.jobId, controller };
-    handleJob(adapter, config, job, completedUnitsByJob, controller.signal).then(() => {
+    handleJob(adapter, config, job, completedUnitsByJob, controller.signal, unitCursorsByJob).then(() => {
       completedUnitsByJob.delete(job.jobId);
+      unitCursorsByJob.delete(job.jobId);
     }).catch((error) => {
       const message = error instanceof Error ? error.message : String(error);
       const failureClass = classifyFailure(error);
       logger2.error("Job failed", { jobId: job.jobId, error: message, failureClass, stack: error instanceof Error ? error.stack : void 0 });
       const completedUnits = completedUnitsByJob.get(job.jobId);
+      const unitCursors = unitCursorsByJob.get(job.jobId);
       completedUnitsByJob.delete(job.jobId);
+      unitCursorsByJob.delete(job.jobId);
       const failAnnotationId = referenceIdOf(job);
       if (isJobType(job.type)) {
         emitEvent(session, "job:fail", {
@@ -11430,6 +11532,10 @@ function startWorkerProcess(config) {
           ...failAnnotationId ? { annotationId: failAnnotationId } : {},
           error: message,
           ...completedUnits && completedUnits.length > 0 ? { completedUnits } : {},
+          // Where each unfinished unit got to. Absent rather than `{}` when
+          // nothing was reached: an empty object would claim units were
+          // tracked and none progressed.
+          ...unitCursors && Object.keys(unitCursors).length > 0 ? { unitCursors } : {},
           ...failureClass !== void 0 ? { failureClass } : {},
           // What the commit path OBSERVED about durability, when the failure
           // came from a commit at all. Present only on that path: absent means
@@ -11452,13 +11558,13 @@ function startWorkerProcess(config) {
   adapter.start();
   return adapter;
 }
-async function handleJob(adapter, config, job, completedUnitsByJob = /* @__PURE__ */ new Map(), signal) {
+async function handleJob(adapter, config, job, completedUnitsByJob = /* @__PURE__ */ new Map(), signal, unitCursorsByJob = /* @__PURE__ */ new Map()) {
   const start = performance.now();
   let outcome = "completed";
   try {
     return await withSpan(
       `job:${job.type}`,
-      () => handleJobInner(adapter, config, job, completedUnitsByJob, signal),
+      () => handleJobInner(adapter, config, job, completedUnitsByJob, signal, unitCursorsByJob),
       {
         kind: SpanKind.CONSUMER,
         attrs: {
@@ -11475,7 +11581,7 @@ async function handleJob(adapter, config, job, completedUnitsByJob = /* @__PURE_
     recordJobOutcome(job.type, outcome, performance.now() - start);
   }
 }
-async function handleJobInner(adapter, config, job, completedUnitsByJob, signal) {
+async function handleJobInner(adapter, config, job, completedUnitsByJob, signal, unitCursorsByJob = /* @__PURE__ */ new Map()) {
   const { session, inferenceClient, generator } = config;
   const { userId, jobId } = job;
   if (!isJobType(job.type)) {
@@ -11485,10 +11591,12 @@ async function handleJobInner(adapter, config, job, completedUnitsByJob, signal)
   const jobType = job.type;
   const resourceId$1 = resourceId(job.resourceId);
   const annotationId = referenceIdOf(job);
+  const attempt = job.retryCount + 1;
   const lifecycleBase = {
     resourceId: resourceId$1,
     jobId,
     jobType,
+    attempt,
     ...annotationId ? { annotationId } : {}
   };
   let durability;
@@ -11548,6 +11656,17 @@ async function handleJobInner(adapter, config, job, completedUnitsByJob, signal)
     }).catch(() => {
     });
   };
+  const unitCursors = /* @__PURE__ */ new Map();
+  const commitChunk = async (annotations, checkpoint) => {
+    record(await commitAnnotations(session, String(resourceId$1), annotations));
+    unitCursors.set(checkpoint.unit, checkpoint.cursor);
+    unitCursorsByJob.set(job.jobId, Object.fromEntries(unitCursors));
+    await emitEvent(session, "job:checkpoint", {
+      jobId: job.jobId,
+      completedUnits: [...completedUnitsByJob.get(job.jobId) ?? []],
+      unitCursors: Object.fromEntries(unitCursors)
+    });
+  };
   if (jobType === "highlight-annotation") {
     const { result } = await processHighlightJob(
       ready.text,
@@ -11556,10 +11675,11 @@ async function handleJobInner(adapter, config, job, completedUnitsByJob, signal)
       ready.buildAnnotation,
       onProgress,
       // The durability write, per chunk, awaited; folds into the terminal
-      // durability evidence like every commit.
-      async (annotations) => {
-        record(await commitAnnotations(session, String(resourceId$1), annotations));
-      }
+      // durability evidence like every commit, and carries the unit's cursor.
+      commitChunk,
+      // …and the other direction: where an earlier attempt left each unit
+      // (CHUNK-GRAIN-RESUME P3). Empty on a first attempt.
+      job.unitCursors
     );
     await emitEvent(session, "job:complete", {
       ...terminalBase(),
@@ -11574,10 +11694,11 @@ async function handleJobInner(adapter, config, job, completedUnitsByJob, signal)
       ready.buildAnnotation,
       onProgress,
       // The durability write, per chunk, awaited; folds into the terminal
-      // durability evidence like every commit.
-      async (annotations) => {
-        record(await commitAnnotations(session, String(resourceId$1), annotations));
-      }
+      // durability evidence like every commit, and carries the unit's cursor.
+      commitChunk,
+      // …and the other direction: where an earlier attempt left each unit
+      // (CHUNK-GRAIN-RESUME P3). Empty on a first attempt.
+      job.unitCursors
     );
     await emitEvent(session, "job:complete", {
       ...terminalBase(),
@@ -11592,10 +11713,11 @@ async function handleJobInner(adapter, config, job, completedUnitsByJob, signal)
       ready.buildAnnotation,
       onProgress,
       // The durability write, per chunk, awaited; folds into the terminal
-      // durability evidence like every commit.
-      async (annotations) => {
-        record(await commitAnnotations(session, String(resourceId$1), annotations));
-      }
+      // durability evidence like every commit, and carries the unit's cursor.
+      commitChunk,
+      // …and the other direction: where an earlier attempt left each unit
+      // (CHUNK-GRAIN-RESUME P3). Empty on a first attempt.
+      job.unitCursors
     );
     await emitEvent(session, "job:complete", {
       ...terminalBase(),
@@ -11620,17 +11742,21 @@ async function handleJobInner(adapter, config, job, completedUnitsByJob, signal)
       config.logger,
       async (unit) => {
         committed.push(unit);
+        unitCursors.delete(unit);
+        unitCursorsByJob.set(job.jobId, Object.fromEntries(unitCursors));
         await emitEvent(session, "job:checkpoint", {
           jobId: job.jobId,
-          completedUnits: [...committed]
+          completedUnits: [...committed],
+          ...unitCursors.size > 0 ? { unitCursors: Object.fromEntries(unitCursors) } : {}
         });
       },
       signal,
       // The durability write, per chunk, awaited; folds into the terminal
-      // durability evidence like every commit.
-      async (annotations) => {
-        record(await commitAnnotations(session, String(resourceId$1), annotations));
-      }
+      // durability evidence like every commit, and carries the unit's cursor.
+      commitChunk,
+      // …and the other direction: where an earlier attempt left each unit
+      // (CHUNK-GRAIN-RESUME P3). Empty on a first attempt.
+      job.unitCursors
     );
     if (signal?.aborted) {
       await emitEvent(session, "job:cancel", {
@@ -11653,10 +11779,11 @@ async function handleJobInner(adapter, config, job, completedUnitsByJob, signal)
       ready.buildAnnotation,
       onProgress,
       // The durability write, per chunk, awaited; folds into the terminal
-      // durability evidence like every commit.
-      async (annotations) => {
-        record(await commitAnnotations(session, String(resourceId$1), annotations));
-      }
+      // durability evidence like every commit, and carries the unit's cursor.
+      commitChunk,
+      // …and the other direction: where an earlier attempt left each unit
+      // (CHUNK-GRAIN-RESUME P3). Empty on a first attempt.
+      job.unitCursors
     );
     await emitEvent(session, "job:complete", {
       ...terminalBase(),