@semiont/jobs 0.5.34 → 0.5.35

package/dist/index.js

@@ -1,7 +1,7 @@
 import { promises, mkdtempSync, writeFileSync, readFileSync, rmSync } from 'fs';
 import * as path from 'path';
 import { join } from 'path';
-import { replyChannelsFor, jobId, deriveViews, GENERATABLE_MEDIA_TYPES, estimateTokens, chunkText, isObject, isString, reconcileSelector, getLocaleEnglishName } from '@semiont/core';
+import { replyChannelsFor, jobId, deriveViews, GENERATABLE_MEDIA_TYPES, estimateTokens, isObject, isString, reconcileSelector, getLocaleEnglishName, cutChunk, chunkText } from '@semiont/core';
 import { withSpan, recordAnchorOutcome, recordDetectionCall } from '@semiont/observability';
 import { StructuredReadError } from '@semiont/inference';
 import { execFileSync } from 'child_process';
@@ -22,6 +22,19 @@ function willRetryAfter(metadata, failureClass) {
 var REANNOUNCE_INTERVAL_MS = 3e4;
 var STALE_RUNNING_MS = 30 * 6e4;
 var PROGRESS_WRITE_MIN_INTERVAL_MS = 5e3;
+function mergeUnitCursors(existing, incoming, completed) {
+  const done = new Set(completed);
+  const merged = {};
+  for (const [unit, cursor] of Object.entries({ ...existing })) {
+    if (!done.has(unit)) merged[unit] = cursor;
+  }
+  for (const [unit, cursor] of Object.entries({ ...incoming })) {
+    if (done.has(unit)) continue;
+    const held = merged[unit];
+    if (!held || cursor.next > held.next) merged[unit] = cursor;
+  }
+  return merged;
+}
 var RETENTION_HOURS = 24;
 var CLEANUP_INTERVAL_MS = 36e5;
 var FsJobQueue = class {
@@ -202,14 +215,20 @@ var FsJobQueue = class {
    * re-announced); after that it lands in `failed` with the error.
    * Returns null (and changes nothing) if the job isn't running.
    */
-  async failJob(jobId, error, completedUnits, failureClass) {
+  async failJob(jobId, error, completedUnits, failureClass, unitCursors) {
     const job = await this.getJob(jobId);
     if (!job || job.status !== "running") {
       return null;
     }
     this.lastProgressWrite.delete(jobId);
     const checkpoint = [.../* @__PURE__ */ new Set([...job.metadata.completedUnits ?? [], ...completedUnits ?? []])];
-    const metadata = checkpoint.length > 0 ? { ...job.metadata, completedUnits: checkpoint } : job.metadata;
+    const cursors = mergeUnitCursors(job.metadata.unitCursors, unitCursors, checkpoint);
+    const { unitCursors: superseded, ...base } = job.metadata;
+    const metadata = {
+      ...base,
+      ...checkpoint.length > 0 ? { completedUnits: checkpoint } : {},
+      ...Object.keys(cursors).length > 0 ? { unitCursors: cursors } : {}
+    };
     if (willRetryAfter(job.metadata, failureClass)) {
       const retried = {
         status: "pending",
@@ -245,15 +264,24 @@ var FsJobQueue = class {
    * non-running jobs. Written directly, like `recordProgress`, so it also
    * refreshes the mtime heartbeat.
    */
-  async checkpointUnits(jobId, completedUnits) {
+  async checkpointUnits(jobId, completedUnits, unitCursors) {
     const job = await this.getJob(jobId);
     if (!job || job.status !== "running") {
       return;
     }
     const merged = [.../* @__PURE__ */ new Set([...job.metadata.completedUnits ?? [], ...completedUnits])];
+    const cursors = mergeUnitCursors(job.metadata.unitCursors, unitCursors, merged);
+    const { unitCursors: superseded, ...metadata } = job.metadata;
     const updated = {
       ...job,
-      metadata: { ...job.metadata, completedUnits: merged }
+      metadata: {
+        ...metadata,
+        completedUnits: merged,
+        // Absent rather than `{}`: an empty object would assert that units were
+        // tracked and none had progress, a different claim from a job that
+        // never reported a cursor at all.
+        ...Object.keys(cursors).length > 0 ? { unitCursors: cursors } : {}
+      }
     };
     await promises.writeFile(this.getJobPath(jobId, "running"), JSON.stringify(updated, null, 2), "utf-8");
   }
@@ -539,10 +567,33 @@ var DeterministicJobError = class extends Error {
   name = "DeterministicJobError";
 };
 
+// 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;
@@ -593,6 +644,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(
@@ -601,15 +653,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";
@@ -621,10 +699,19 @@ function outcomeOf(error) {
   return "error";
 }
 async function callChunkSubdividing(label, chunk, chunking, call, logger, 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,
@@ -655,6 +742,7 @@ async function callChunkSubdividing(label, chunk, chunking, call, logger, onUnde
       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;
@@ -690,7 +778,12 @@ async function callChunkSubdividing(label, chunk, chunking, call, logger, onUnde
       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;
@@ -1191,33 +1284,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 {
@@ -1229,7 +1326,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,
@@ -1238,6 +1335,7 @@ var AnnotationDetection = class {
       COMMENT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseComments(items, content),
       onActivity,
+      resume,
       onChunkResults
     );
   }
@@ -1248,7 +1346,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,
@@ -1257,6 +1355,7 @@ var AnnotationDetection = class {
       HIGHLIGHT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseHighlights(items, content),
       onActivity,
+      resume,
       onChunkResults
     );
   }
@@ -1267,7 +1366,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,
@@ -1276,6 +1375,7 @@ var AnnotationDetection = class {
       ASSESSMENT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseAssessments(items, content),
       onActivity,
+      resume,
       onChunkResults
     );
   }
@@ -1291,7 +1391,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}`);
@@ -1313,7 +1413,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);
   }
@@ -1365,7 +1466,7 @@ ${piece}
   }
   return counted;
 }
-async function extractEntities(exact, entityTypes, client, includeDescriptiveReferences, logger, sourceLanguage, onActivity, onUnderReport, onCounted, onChunkResults) {
+async function extractEntities(exact, entityTypes, client, includeDescriptiveReferences, logger, sourceLanguage, onActivity, onUnderReport, onCounted, resume, onChunkResults) {
   const entityTypesDescription = entityTypes.map((et) => {
     if (typeof et === "string") {
       return et;
@@ -1417,42 +1518,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;
   logger.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),
-        logger
-      );
-      logger.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, logger) : void 0;
-      return {
-        items: response.items,
-        ...response.usage ? { usage: response.usage } : {},
-        ...counted !== void 0 ? { counted } : {}
-      };
-    }, logger, 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),
+          logger
+        );
+        logger.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, logger) : void 0;
+        return {
+          items: response.items,
+          ...response.usage ? { usage: response.usage } : {},
+          ...counted !== void 0 ? { counted } : {}
+        };
+      },
+      logger,
+      onUnderReport,
+      onCounted
+    );
     const fromChunk = [];
     for (const e of items) {
       if (isObject(e) && isString(e.exact) && isString(e.entityType)) {
@@ -1467,11 +1581,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) {
@@ -1836,13 +1949,14 @@ function makeSpanDeduper() {
     return out;
   };
 }
-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,
@@ -1850,13 +1964,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);
@@ -1871,14 +1986,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,
@@ -1888,8 +2004,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) => (
@@ -1903,7 +2020,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);
@@ -1911,14 +2028,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,
@@ -1928,8 +2046,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) => (
@@ -1950,7 +2069,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);
@@ -1958,12 +2077,12 @@ async function processAssessmentJob(content, inferenceClient, params, buildAnnot
     result: { kind: "assessment-annotation", assessmentsFound: found, assessmentsCreated: created }
   };
 }
-async function processReferenceJob(content, inferenceClient, params, buildAnnotation, onProgress, logger, onUnitComplete, signal, onChunkComplete) {
+async function processReferenceJob(content, inferenceClient, params, buildAnnotation, onProgress, logger, 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;
@@ -1992,8 +2111,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,
@@ -2019,7 +2139,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, {
@@ -2039,9 +2160,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);
@@ -2073,13 +2199,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++) {
@@ -2095,7 +2221,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,
@@ -2104,12 +2232,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";
@@ -2125,7 +2254,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;