@semiont/make-meaning 0.5.24 → 0.5.26

package/dist/index.js

@@ -1,14 +1,13 @@
 import { STALL_THRESHOLD_MS, FsJobQueue } from '@semiont/jobs';
 import { FilesystemViewStorage, resolveStorageUri, EventQuery, createEventStore } from '@semiont/event-sourcing';
-import { getResourceEntityTypes, getResourceId, getTargetSource, resourceId, getPrimaryRepresentation, decodeRepresentation, getBodySource, getTargetSelector, deriveViews, getTextPositionSelector, annotationId, errField, userId, generateUuid, getExactText, busRequest, cloneToken, baseMediaType, isSupportedMediaType, capabilitiesOf, didToAgent, assembleAnnotation, jobId, entityType, baseUrl, busLog, BRIDGED_CHANNELS, burstBuffer, textExtractionOf, getPrimaryMediaType, extensionForMediaType, applyBodyOperations, softwareToAgent } from '@semiont/core';
+import { getResourceEntityTypes, getResourceId, getTargetSource, resourceId, getPrimaryRepresentation, decodeRepresentation, getBodySource, getTargetSelector, deriveViews, getTextPositionSelector, annotationId, errField, userId, generateUuid, getExactText, busRequest, cloneToken, baseMediaType, isSupportedMediaType, capabilitiesOf, didToAgent, assembleAnnotation, jobId, entityType, baseUrl, busLog, BRIDGED_CHANNELS, burstBuffer, textExtractionOf, chunkText, getPrimaryMediaType, extensionForMediaType, applyBodyOperations, softwareToAgent } from '@semiont/core';
 import { recordGatherDegrade, withActorSpan, recordBusEmit, withSpan, SpanKind, registerJobQueueProvider, registerVectorIndexSizeProvider } from '@semiont/observability';
 import { createInferenceClient } from '@semiont/inference';
-import { getGraphDatabase } from '@semiont/graph';
-import { WorkingTreeStore, deriveStorageUri, calculateChecksum } from '@semiont/content';
+import { compareByRecencyThenId, getGraphDatabase } from '@semiont/graph';
+import { WorkingTreeStore, createAnchoredTextStore, deriveStorageUri, anchoredTextStoreOverTransport, EXTRACTORS, calculateChecksum } from '@semiont/content';
 import { getEntityTypes, DEFAULT_ENTITY_TYPES } from '@semiont/ontology';
 import { promises } from 'fs';
 import * as path3 from 'path';
-import { chunkText } from '@semiont/vectors';
 import { createGzip, createGunzip } from 'zlib';
 import { pipeline, Readable } from 'stream';
 import { promisify } from 'util';
@@ -9889,6 +9888,10 @@ async function createKnowledgeBase(eventStore, project, graphDb, eventBus, logge
     project,
     logger.child({ component: "working-tree-store" })
   );
+  const anchoredText = createAnchoredTextStore(
+    project.anchoredTextDir,
+    logger.child({ component: "anchored-text-store" })
+  );
   const weaveProgress = createWeaveProgress(eventBus);
   const smeltProgress = createSmeltProgress(eventBus);
   if (!options?.skipRebuild) {
@@ -9898,6 +9901,7 @@ async function createKnowledgeBase(eventStore, project, graphDb, eventBus, logge
     eventStore,
     views,
     content,
+    anchoredText,
     graph: graphDb,
     weaveProgress,
     smeltProgress,
@@ -9933,13 +9937,6 @@ var GraphContext = class {
   static async getResourceConnections(resourceId10, kb) {
     return kb.graph.getResourceConnections(resourceId10);
   }
-  /**
-   * Search resources by name (cross-resource query)
-   * Requires full-text search - must use graph database
-   */
-  static async searchResources(query, kb, limit) {
-    return kb.graph.searchResources(query, limit);
-  }
   /**
    * Build the unified knowledge graph for a resource's neighborhood:
    * resources AND annotations as typed nodes, typed/directional edges.
@@ -10060,7 +10057,7 @@ Format as a simple list, one suggestion per line.`;
   }
   return response.split("\n").map((line) => line.replace(/^[-*•]\s*/, "").trim()).filter((line) => line.length > 0).slice(0, 3);
 }
-var ResourceContext = class _ResourceContext {
+var ResourceContext = class {
   /**
    * Get resource metadata from view storage
    */
@@ -10072,38 +10069,34 @@ var ResourceContext = class _ResourceContext {
     return view.resource;
   }
   /**
-   * List resources, optionally filtered.
+   * List resources, optionally filtered, as one page plus the size of the whole
+   * match set. Every filter is applied before pagination on both paths — a
+   * filter applied afterwards narrows the page rather than the match set, which
+   * is how a search scoped to an entity type can come back empty while hundreds
+   * of resources match.
    *
-   * When `search` is set, delegates to `kb.graph.searchResources`, which runs
-   * the name match in the graph engine instead of scanning every view in JS.
-   * The graph result is then narrowed by `archived` if requested.
+   * When `search` is set, the entire query — filtering, ordering and
+   * pagination — runs inside the graph engine.
    *
-   * When `search` is unset, falls back to scanning all materialized views.
-   * (TODO: also push the listing path through the graph for large KBs.)
+   * When `search` is unset, the materialized views answer instead. They are the
+   * barrier-stamped projection, so an unsearched listing is read-your-writes
+   * where the graph is only eventually consistent.
    */
   static async listResources(filters, kb) {
-    if (filters?.search) {
-      const matches = await kb.graph.searchResources(filters.search);
-      const filtered = filters.archived !== void 0 ? matches.filter((doc) => doc.archived === filters.archived) : matches;
-      return _ResourceContext.sortByDateDesc(filtered);
+    const { search: rawSearch, archived, entityType: entityType2, offset = 0, limit = 50 } = filters ?? {};
+    const search = rawSearch?.trim() || void 0;
+    if (search) {
+      return kb.graph.listResources({
+        search,
+        archived,
+        entityTypes: entityType2 ? [entityType2] : void 0,
+        offset,
+        limit
+      });
     }
     const allViews = await kb.views.getAll();
-    const resources = [];
-    for (const view of allViews) {
-      const doc = view.resource;
-      if (filters?.archived !== void 0 && doc.archived !== filters.archived) {
-        continue;
-      }
-      resources.push(doc);
-    }
-    return _ResourceContext.sortByDateDesc(resources);
-  }
-  static sortByDateDesc(resources) {
-    return [...resources].sort((a, b) => {
-      const aTime = a.dateCreated ? new Date(a.dateCreated).getTime() : 0;
-      const bTime = b.dateCreated ? new Date(b.dateCreated).getTime() : 0;
-      return bTime - aTime;
-    });
+    const matches = allViews.map((view) => view.resource).filter((doc) => archived === void 0 || doc.archived === archived).filter((doc) => !entityType2 || getResourceEntityTypes(doc).includes(entityType2)).sort(compareByRecencyThenId);
+    return { resources: matches.slice(offset, offset + limit), total: matches.length };
   }
   /**
    * Add content previews to resources (for search results)
@@ -10300,7 +10293,8 @@ Summary:`;
               resourceId: r.resourceId,
               annotationId: r.annotationId,
               score: r.score,
-              entityTypes: r.entityTypes
+              entityTypes: r.entityTypes,
+              ...r.machineRead ? { machineRead: true } : {}
             }))
           };
           logger?.debug("Semantic context found", { matches: results.length });
@@ -10642,7 +10636,8 @@ var LLMContext = class {
             resourceId: m.resourceId,
             ...m.annotationId ? { annotationId: m.annotationId } : {},
             score: m.score,
-            ...m.entityTypes ? { entityTypes: m.entityTypes } : {}
+            ...m.entityTypes ? { entityTypes: m.entityTypes } : {},
+            ...m.machineRead ? { machineRead: true } : {}
           })),
           ...excludeEntityTypes.length ? { excludedEntityTypes: excludeEntityTypes } : {}
         };
@@ -10879,7 +10874,7 @@ var Matcher = class {
    * Context-driven search: multi-source retrieval + composite scoring
    *
    * Retrieval sources:
-   * 1. Name match — graph.searchResources(searchTerm)
+   * 1. Name match — graph.listResources({ search: searchTerm })
    * 2. Entity type match — graph.listResources({ entityTypes })
    * 3. Graph neighborhood — connections from GatheredContext
    *
@@ -10895,7 +10890,7 @@ var Matcher = class {
     const views = deriveViews(context.graph, mainResourceId);
     const connections = views.connections;
     const [nameMatches, entityTypeMatches, semanticMatches] = await Promise.all([
-      this.kb.graph.searchResources(searchTerm),
+      this.kb.graph.listResources({ search: searchTerm, limit: 20 }).then((r) => r.resources),
       annotationEntityTypes.length > 0 ? this.kb.graph.listResources({ entityTypes: annotationEntityTypes, limit: 50 }).then((r) => r.resources) : Promise.resolve([]),
       // 4. Semantic match — vector similarity search (if vectors configured)
       this.searchVectors(searchTerm)
@@ -11632,6 +11627,21 @@ var Stower = class {
 // src/browser.ts
 var import_rxjs4 = __toESM(require_cjs());
 var import_operators4 = __toESM(require_operators());
+var ANCHORED_TEXT_SETTLE_TIMEOUT_MS = 15e3;
+async function readAnchoredText(kb, resourceId10) {
+  const view = await kb.views.get(resourceId(resourceId10));
+  const checksum = getPrimaryRepresentation(view?.resource)?.checksum;
+  if (!checksum) return null;
+  const hit = await kb.anchoredText.read(checksum);
+  if (hit) return hit;
+  try {
+    const outcome = await kb.smeltProgress.whenSettled(resourceId10, checksum, ANCHORED_TEXT_SETTLE_TIMEOUT_MS);
+    return outcome === "indexed" ? kb.anchoredText.read(checksum) : null;
+  } catch (error) {
+    if (error instanceof SmeltProgressTimeout) return null;
+    throw error;
+  }
+}
 async function readTagSchemasProjection(project) {
   const tagSchemasPath = path3.join(
     project.stateDir,
@@ -11746,6 +11756,7 @@ var Browser = class {
     );
     this.subscriptions.push(
       pipe("browse:resource-requested", (e) => this.handleBrowseResource(e)).subscribe({ error: errorHandler }),
+      pipe("browse:anchored-text-requested", (e) => this.handleAnchoredText(e)).subscribe({ error: errorHandler }),
       pipe("browse:resources-requested", (e) => this.handleBrowseResources(e)).subscribe({ error: errorHandler }),
       pipe("browse:annotations-requested", (e) => this.handleBrowseAnnotations(e)).subscribe({ error: errorHandler }),
       pipe("browse:annotation-requested", (e) => this.handleBrowseAnnotation(e)).subscribe({ error: errorHandler }),
@@ -11761,6 +11772,34 @@ var Browser = class {
   // ========================================================================
   // KB read handlers
   // ========================================================================
+  /**
+   * Serve a resource's derived coordinate map (ANCHORED-TEXT-CACHE Lane 5).
+   *
+   * Read-your-writes on the same barrier `llm-context` uses for vectors: a
+   * caller may arrive before the Smelter has finished the resource it just
+   * uploaded, so a miss waits for that content generation to settle rather than
+   * reporting "no map" for a document that is merely still being read.
+   *
+   * **This path never invokes the engine.** The Smelter is the sole producer.
+   * A miss that survives the barrier answers `null`, and the caller degrades —
+   * for a PDF annotation that means geometry with no quoted text, which is what
+   * shipped before any of this existed. OCR in a request path is precisely what
+   * this design exists to avoid.
+   */
+  async handleAnchoredText(event) {
+    try {
+      this.eventBus.get("browse:anchored-text-result").next({
+        correlationId: event.correlationId,
+        response: await readAnchoredText(this.kb, event.resourceId)
+      });
+    } catch (error) {
+      this.logger.error("Browse anchored text failed", { resourceId: event.resourceId, error: errField(error) });
+      this.eventBus.get("browse:anchored-text-failed").next({
+        correlationId: event.correlationId,
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
   async handleBrowseResource(event) {
     try {
       const response = await assembleResourceGraph(this.kb, resourceId(event.resourceId));
@@ -11785,22 +11824,21 @@ var Browser = class {
   }
   async handleBrowseResources(event) {
     try {
-      let filteredDocs = await ResourceContext.listResources({
-        search: event.search,
-        archived: event.archived
-      }, this.kb);
-      if (event.entityType) {
-        filteredDocs = filteredDocs.filter((doc) => getResourceEntityTypes(doc).includes(event.entityType));
-      }
       const offset = event.offset ?? 0;
       const limit = event.limit ?? 50;
-      const paginatedDocs = filteredDocs.slice(offset, offset + limit);
-      const formattedDocs = event.search ? await ResourceContext.addContentPreviews(paginatedDocs, this.kb) : paginatedDocs;
+      const { resources, total } = await ResourceContext.listResources({
+        search: event.search,
+        archived: event.archived,
+        entityType: event.entityType,
+        offset,
+        limit
+      }, this.kb);
+      const formattedDocs = event.search ? await ResourceContext.addContentPreviews(resources, this.kb) : resources;
       this.eventBus.get("browse:resources-result").next({
         correlationId: event.correlationId,
         response: {
           resources: formattedDocs,
-          total: filteredDocs.length,
+          total,
           offset,
           limit
         }
@@ -12916,6 +12954,7 @@ async function startMakeMeaning(project, config, eventBus, logger, options) {
   return {
     knowledgeSystem,
     jobQueue,
+    project,
     stop: async () => {
       logger.info("Stopping Make-Meaning service");
       jobStatusSubscription.unsubscribe();
@@ -13029,6 +13068,40 @@ var LocalContentTransport = class {
       "LocalContentTransport does not support putBinary() \u2014 create resources via bus emits (mark/yield namespaces) in local mode"
     );
   }
+  /**
+   * Store a derived coordinate map under the content checksum the producer
+   * read (PERSIST-ANCHORS decision A — see the interface doc for why the
+   * producer supplies the key). In local mode this is the same store the
+   * HTTP route writes to — one storage authority, reached the same way from
+   * every process (ANCHORED-TEXT-CACHE Lane 5).
+   */
+  async putAnchoredText(checksum, outcome, _options) {
+    busLog("PUT", "anchored-text", { checksum });
+    await this.ks.kb.anchoredText.write(checksum, outcome);
+  }
+  /** The stored outcome, or null when nothing has derived one — the common case. */
+  async getAnchoredText(resourceId10, _options) {
+    busLog("GET", "anchored-text", { resourceId: resourceId10 });
+    return readAnchoredText(this.ks.kb, resourceId10);
+  }
+  /**
+   * The cache-consult read (PERSIST-ANCHORS P2c), straight from the store —
+   * checksum-addressed, so no view resolution and no settle barrier: the
+   * caller holds the content identity already.
+   */
+  async getAnchoredTextByChecksum(checksum, _options) {
+    busLog("GET", "anchored-text-by-checksum", { checksum });
+    return this.ks.kb.anchoredText.read(checksum);
+  }
+  /**
+   * The store's would-hit keys, straight from the store — planning data for
+   * the reconcile diff (PERSIST-ANCHORS P0), so no settle barrier applies:
+   * presence is being asked, not content at a moment.
+   */
+  async listAnchoredTextKeys(_options) {
+    busLog("GET", "anchored-text-keys", {});
+    return this.ks.kb.anchoredText.list();
+  }
   async getBinary(resourceId10, _options) {
     busLog("GET", "content", { resourceId: resourceId10 });
     return withSpan(
@@ -13111,6 +13184,7 @@ function sameStringSet(a, b) {
 var WORK_ITEM_TYPES = /* @__PURE__ */ new Set([
   "smelt:embed",
   "smelt:restamp",
+  "smelt:reanchor",
   "smelt:purge",
   "smelt:embed-annotation",
   "smelt:purge-annotation"
@@ -13119,8 +13193,9 @@ function isWorkItem(input) {
   return WORK_ITEM_TYPES.has(input.type);
 }
 var Smelter = class _Smelter {
-  constructor(events$, vectorStore, embeddingProvider, content, bus, chunkingConfig, timing, logger) {
+  constructor(events$, rebuildAnchors$, vectorStore, embeddingProvider, content, bus, chunkingConfig, timing, logger) {
     this.events$ = events$;
+    this.rebuildAnchors$ = rebuildAnchors$;
     this.vectorStore = vectorStore;
     this.embeddingProvider = embeddingProvider;
     this.content = content;
@@ -13128,8 +13203,10 @@ var Smelter = class _Smelter {
     this.chunkingConfig = chunkingConfig;
     this.timing = timing;
     this.logger = logger;
+    this.anchoredStore = anchoredTextStoreOverTransport(content, logger.child({ component: "anchored-text-cache" }));
   }
   events$;
+  rebuildAnchors$;
   vectorStore;
   embeddingProvider;
   content;
@@ -13142,11 +13219,21 @@ var Smelter = class _Smelter {
   static RECONCILE_WAVE = 8;
   eventSubject = new import_rxjs9.Subject();
   sourceSubscription = null;
+  commandSubscription = null;
   pipelineSubscription = null;
   _eventsProcessed = 0;
   _reconcileState = { phase: "pending" };
   workDone = 0;
+  workFailed = 0;
   workWaiter = null;
+  /**
+   * Serializes every planner drain (reconcile, anchored-text rebuilds):
+   * there is one waiter slot, and the weave:rebuild rule — rebuilds never
+   * interleave — applies to every unit here being a potential multi-second
+   * OCR pass.
+   */
+  drainChain = Promise.resolve();
+  anchoredStore;
   get eventsProcessed() {
     return this._eventsProcessed;
   }
@@ -13174,7 +13261,7 @@ var Smelter = class _Smelter {
             return (0, import_rxjs9.from)(
               withActorSpan("smelter", inputOrBatch.type, async () => {
                 const ok = await this.safeProcessEvent(inputOrBatch);
-                if (isWorkItem(inputOrBatch)) this.noteWorkDone(1);
+                if (isWorkItem(inputOrBatch)) this.noteWorkDone(1, ok ? 0 : 1);
                 else if (ok) this._eventsProcessed++;
               })
             );
@@ -13188,18 +13275,26 @@ var Smelter = class _Smelter {
       this.logger.debug("Bus event received", { type: event.type, resourceId: event.resourceId });
       this.eventSubject.next(event);
     });
+    this.commandSubscription = this.rebuildAnchors$.pipe(
+      (0, import_operators7.concatMap)((command) => (0, import_rxjs9.from)(this.rebuildAnchors(command)))
+    ).subscribe({
+      error: (err) => this.logger.error("Smelter command pipeline error", { error: errField(err) })
+    });
     this.logger.info("Smelter pipeline initialized");
   }
   stop() {
     this.sourceSubscription?.unsubscribe();
     this.sourceSubscription = null;
+    this.commandSubscription?.unsubscribe();
+    this.commandSubscription = null;
     this.pipelineSubscription?.unsubscribe();
     this.pipelineSubscription = null;
     this.eventSubject.complete();
     this.logger.info("Smelter stopped");
   }
-  noteWorkDone(count) {
+  noteWorkDone(count, failed) {
     this.workDone += count;
+    this.workFailed += failed;
     if (this.workWaiter && this.workDone >= this.workWaiter.target) {
       this.workWaiter.resolve();
       this.workWaiter = null;
@@ -13213,12 +13308,15 @@ var Smelter = class _Smelter {
     let wireProcessed = 0;
     for (const run of partitionByType(events)) {
       const workRun = isWorkItem(run[0]);
+      let succeeded = 0;
       try {
         if (run.length === 1) {
           const ok = await this.safeProcessEvent(run[0]);
+          if (ok) succeeded = 1;
           if (ok && !workRun) wireProcessed++;
         } else {
           const processed = await this.applyBatchByType(run);
+          succeeded = processed;
           if (!workRun) wireProcessed += processed;
         }
       } catch (error) {
@@ -13228,7 +13326,7 @@ var Smelter = class _Smelter {
           error: errField(error)
         });
       } finally {
-        if (workRun) this.noteWorkDone(run.length);
+        if (workRun) this.noteWorkDone(run.length, run.length - succeeded);
       }
     }
     return wireProcessed;
@@ -13300,6 +13398,9 @@ var Smelter = class _Smelter {
       case "smelt:restamp":
         await this.restampResource(event);
         break;
+      case "smelt:reanchor":
+        await this.reanchorResource(event);
+        break;
       case "smelt:purge":
         await this.handleResourcePurge(event);
         break;
@@ -13326,6 +13427,45 @@ var Smelter = class _Smelter {
     await this.vectorStore.updateResourceEntityTypes(resourceId(rid), entityTypes);
     this.logger.info("Restamped resource entity types", { resourceId: rid, entityTypes });
   }
+  /**
+   * Re-derive a lost anchored-text artifact from the resource's current
+   * bytes (PERSIST-ANCHORS P0, the third drift class). Extraction is the
+   * cost here — the vectors are already correct, so this NEVER calls the
+   * embedding provider, the vector store, or the settled signal: the index
+   * decision was already made and announced at its checksum; only the map
+   * is missing. Name the work for what it does (the S13 discipline).
+   *
+   * The publish is STRICT, unlike the embed path's best-effort side
+   * publish: here the artifact IS the job, so a store failure must throw —
+   * the pipeline logs and counts it, and the rebuild command's partial-
+   * failure accounting depends on that throw.
+   */
+  async reanchorResource(event) {
+    const rid = event.resourceId;
+    if (!rid) return;
+    const { data, contentType } = await this.content.getBinary(resourceId(rid));
+    const bytes = Buffer.from(data);
+    const extractor = EXTRACTORS[textExtractionOf(contentType)];
+    if (!extractor?.yieldsGeometry) {
+      this.logger.info("Re-anchor found no geometry-capable extractor", { resourceId: rid, contentType });
+      return;
+    }
+    const checksum = calculateChecksum(bytes);
+    const extracted = await extractor.extract(bytes, contentType, {
+      key: checksum,
+      store: this.anchoredStore
+    });
+    if ("declined" in extracted || !extracted.items?.length) {
+      this.logger.info("Re-anchor extraction yielded no geometry", {
+        resourceId: rid,
+        contentType,
+        ..."declined" in extracted ? { declined: extracted.declined } : {}
+      });
+      return;
+    }
+    await this.content.putAnchoredText(checksum, { ...extracted, items: extracted.items });
+    this.logger.info("Re-anchored resource", { resourceId: rid, checksum, items: extracted.items.length });
+  }
   async handleResourcePurge(event) {
     const rid = event.resourceId;
     if (!rid) return;
@@ -13345,12 +13485,34 @@ var Smelter = class _Smelter {
       const { data, contentType } = await this.content.getBinary(resourceId(resourceId10));
       const bytes = Buffer.from(data);
       const checksum = calculateChecksum(bytes);
-      if (textExtractionOf(contentType) !== "decode") {
-        this.logger.debug("Skipping resource that does not decode as text", { resourceId: resourceId10, contentType });
-        return { kind: "skipped", checksum };
+      const extractor = EXTRACTORS[textExtractionOf(contentType)];
+      if (!extractor) {
+        this.logger.debug("Skipping resource with no extractor for its media type", { resourceId: resourceId10, contentType });
+        return { kind: "skipped", checksum, reason: "no-extractor" };
+      }
+      const extracted = await extractor.extract(bytes, contentType, {
+        key: checksum,
+        store: this.anchoredStore
+      });
+      if ("declined" in extracted) {
+        this.logger.debug("Extractor declined", { resourceId: resourceId10, contentType, reason: extracted.declined });
+        return { kind: "skipped", checksum, reason: extracted.declined };
       }
-      const text = decodeRepresentation(bytes, contentType);
-      return text.trim() ? { kind: "text", text, checksum } : { kind: "skipped", checksum };
+      if (extracted.ocrConfidence && extracted.ocrConfidence.lowConfidenceWords > 0) {
+        this.logger.info("OCR read words it was unsure of", {
+          resourceId: resourceId10,
+          contentType,
+          ...extracted.ocrConfidence
+        });
+      }
+      if (extracted.unreadPages?.length) {
+        this.logger.info("Partial extraction coverage", {
+          resourceId: resourceId10,
+          contentType,
+          unreadPages: extracted.unreadPages
+        });
+      }
+      return extracted.text.trim() ? { kind: "text", text: extracted.text, checksum, machineRead: extracted.method === "ocr" } : { kind: "skipped", checksum, reason: "empty" };
     } catch (error) {
       this.logger.warn("Content unavailable for embedding", { resourceId: resourceId10, error: errField(error) });
       return { kind: "unavailable" };
@@ -13362,9 +13524,9 @@ var Smelter = class _Smelter {
    * fold. Best-effort — waiters degrade to their bounded timeout; a signal
    * failure must never fail the embed.
    */
-  async emitSettled(resourceId10, contentChecksum, outcome) {
+  async emitSettled(resourceId10, contentChecksum, outcome, reason) {
     try {
-      await this.bus.emit("smelt:settled", { resourceId: resourceId10, contentChecksum, outcome });
+      await this.bus.emit("smelt:settled", { resourceId: resourceId10, contentChecksum, outcome, ...reason ? { reason } : {} });
     } catch (error) {
       this.logger.warn("Failed to emit smelt:settled", { resourceId: resourceId10, outcome, error: errField(error) });
     }
@@ -13392,12 +13554,14 @@ var Smelter = class _Smelter {
     const fetched = await this.fetchEmbeddableText(rid);
     if (fetched.kind === "unavailable") return;
     if (fetched.kind === "skipped") {
-      await this.emitSettled(rid, fetched.checksum, "skipped");
+      await this.vectorStore.deleteResourceVectors(resourceId(rid));
+      await this.emitSettled(rid, fetched.checksum, "skipped", fetched.reason);
       return;
     }
     const chunks = chunkText(fetched.text, this.chunkingConfig);
     if (chunks.length === 0) {
-      await this.emitSettled(rid, fetched.checksum, "skipped");
+      await this.vectorStore.deleteResourceVectors(resourceId(rid));
+      await this.emitSettled(rid, fetched.checksum, "skipped", "empty");
       return;
     }
     const entityTypes = await this.resolveEntityTypes(rid);
@@ -13407,7 +13571,7 @@ var Smelter = class _Smelter {
       text: t,
       embedding: embeddings[i]
     }));
-    await this.vectorStore.upsertResourceVectors(resourceId(rid), embeddingChunks, fetched.checksum, entityTypes);
+    await this.vectorStore.upsertResourceVectors(resourceId(rid), embeddingChunks, fetched.checksum, entityTypes, fetched.machineRead);
     await this.emitSettled(rid, fetched.checksum, "indexed");
     this.logger.info(logMessage, { resourceId: rid, chunks: chunks.length });
   }
@@ -13451,12 +13615,14 @@ var Smelter = class _Smelter {
     if (!exactText?.trim()) return;
     const aid = annotationId(annotation.id);
     const embedding = await this.embeddingProvider.embed(exactText);
+    const stamp = await this.vectorStore.getResourceStamp(resourceId(rid));
     const payload = {
       annotationId: aid,
       resourceId: resourceId(rid),
       motivation: annotation.motivation ?? "",
       entityTypes: annotation.entityTypes ?? [],
-      exactText
+      exactText,
+      ...stamp?.machineRead ? { machineRead: true } : {}
     };
     await this.vectorStore.upsertAnnotationVector(aid, embedding, payload);
     this.logger.info("Indexed annotation", { annotationId: String(aid) });
@@ -13481,28 +13647,30 @@ var Smelter = class _Smelter {
       const fetched = await this.fetchEmbeddableText(rid);
       if (fetched.kind === "unavailable") continue;
       if (fetched.kind === "skipped") {
-        await this.emitSettled(rid, fetched.checksum, "skipped");
+        await this.vectorStore.deleteResourceVectors(resourceId(rid));
+        await this.emitSettled(rid, fetched.checksum, "skipped", fetched.reason);
         continue;
       }
       const chunks = chunkText(fetched.text, this.chunkingConfig);
       if (chunks.length === 0) {
-        await this.emitSettled(rid, fetched.checksum, "skipped");
+        await this.vectorStore.deleteResourceVectors(resourceId(rid));
+        await this.emitSettled(rid, fetched.checksum, "skipped", "empty");
         continue;
       }
       const entityTypes = await this.resolveEntityTypes(rid);
-      resourceData.push({ rid: resourceId(rid), chunks, checksum: fetched.checksum, entityTypes });
+      resourceData.push({ rid: resourceId(rid), chunks, checksum: fetched.checksum, entityTypes, machineRead: fetched.machineRead });
       allChunks.push(...chunks);
     }
     if (allChunks.length === 0) return events.length;
     const allEmbeddings = await this.embeddingProvider.embedBatch(allChunks);
     let offset = 0;
-    for (const { rid, chunks, checksum, entityTypes } of resourceData) {
+    for (const { rid, chunks, checksum, entityTypes, machineRead } of resourceData) {
       const embeddingChunks = chunks.map((t, i) => ({
         chunkIndex: i,
         text: t,
         embedding: allEmbeddings[offset + i]
       }));
-      await this.vectorStore.upsertResourceVectors(rid, embeddingChunks, checksum, entityTypes);
+      await this.vectorStore.upsertResourceVectors(rid, embeddingChunks, checksum, entityTypes, machineRead);
       await this.emitSettled(String(rid), checksum, "indexed");
       this.logger.info("Batch-indexed resource", { resourceId: String(rid), chunks: chunks.length });
       offset += chunks.length;
@@ -13575,26 +13743,23 @@ var Smelter = class _Smelter {
     }
     this._reconcileState = { phase: "running" };
     try {
-      const [indexedResources, indexedAnnotations] = await Promise.all([
+      const [indexedResources, indexedAnnotations, anchoredKeys] = await Promise.all([
         this.vectorStore.listResourceStamps(),
-        this.vectorStore.listAnnotationIds()
+        this.vectorStore.listAnnotationIds(),
+        // The artifact store's would-hit keys — one bulk read, never a probe
+        // per resource (PERSIST-ANCHORS P0). Keys are resource ids today;
+        // P1 rekeys the store by content checksum and this lookup moves
+        // with it.
+        this.content.listAnchoredTextKeys().then((keys) => new Set(keys))
       ]);
       const resources = await this.listAllResources();
       this.logger.info("Reconcile started", {
         indexedResources: indexedResources.size,
         indexedAnnotations: indexedAnnotations.size,
+        anchoredArtifacts: anchoredKeys.size,
         liveResources: resources.length
       });
-      const embeddable = /* @__PURE__ */ new Map();
-      for (const resource of resources) {
-        const mediaType = getPrimaryMediaType(resource);
-        if (resource["@id"] && mediaType && textExtractionOf(mediaType) === "decode") {
-          embeddable.set(resource["@id"], {
-            checksum: getPrimaryRepresentation(resource)?.checksum,
-            entityTypes: getResourceEntityTypes(resource)
-          });
-        }
-      }
+      const embeddable = this.classifyEmbeddable(resources);
       const work = [];
       for (const rid of indexedResources.keys()) {
         if (!embeddable.has(rid)) work.push({ type: "smelt:purge", resourceId: rid, payload: {} });
@@ -13608,6 +13773,9 @@ var Smelter = class _Smelter {
         } else if (!sameStringSet(indexed.entityTypes, catalog.entityTypes)) {
           work.push({ type: "smelt:restamp", resourceId: rid, payload: {} });
         }
+        if (indexed && catalog.checksum !== void 0 && indexed.contentChecksum === catalog.checksum && catalog.yieldsGeometry && !anchoredKeys.has(catalog.checksum)) {
+          work.push({ type: "smelt:reanchor", resourceId: rid, payload: {} });
+        }
       }
       const liveAnnotationIds = /* @__PURE__ */ new Set();
       for (const resource of resources) {
@@ -13636,9 +13804,12 @@ var Smelter = class _Smelter {
       const summary = {
         resourcesEmbedded: work.filter((w) => w.type === "smelt:embed").length,
         resourcesRestamped: work.filter((w) => w.type === "smelt:restamp").length,
+        resourcesReanchored: work.filter((w) => w.type === "smelt:reanchor").length,
         resourceVectorsDeleted: work.filter((w) => w.type === "smelt:purge").length,
         annotationsEmbedded: work.filter((w) => w.type === "smelt:embed-annotation").length,
-        annotationVectorsDeleted: work.filter((w) => w.type === "smelt:purge-annotation").length
+        annotationVectorsDeleted: work.filter((w) => w.type === "smelt:purge-annotation").length,
+        resourcesEligible: embeddable.size,
+        resourcesIndexed: (await this.vectorStore.listResourceStamps()).size
       };
       this._reconcileState = { phase: "done", summary };
       this.logger.info("Reconcile complete", { ...summary });
@@ -13657,16 +13828,106 @@ var Smelter = class _Smelter {
    * completion. The pipeline ticks `noteWorkDone` for every consumed work
    * item (success or failure — failures are logged like any live event), so
    * each wave's waiter resolves exactly when its items have been processed.
+   *
+   * Serialized through `drainChain`: there is ONE waiter slot, and the
+   * planners that drain (reconcile, `smelt:rebuild-anchors`) must not
+   * interleave — a rebuild command arriving mid-reconcile waits its turn.
+   *
+   * @returns how many of THESE items failed — the rebuild command's
+   * partial-failure accounting (failure detail is in the logs).
    */
   async drain(work) {
-    for (let i = 0; i < work.length; i += _Smelter.RECONCILE_WAVE) {
-      const wave = work.slice(i, i + _Smelter.RECONCILE_WAVE);
-      const done = new Promise((resolve2) => {
-        this.workWaiter = { target: this.workDone + wave.length, resolve: resolve2 };
-      });
-      for (const item of wave) this.eventSubject.next(item);
-      await done;
+    let failures = 0;
+    const run = this.drainChain.then(async () => {
+      const failedBefore = this.workFailed;
+      for (let i = 0; i < work.length; i += _Smelter.RECONCILE_WAVE) {
+        const wave = work.slice(i, i + _Smelter.RECONCILE_WAVE);
+        const done = new Promise((resolve2) => {
+          this.workWaiter = { target: this.workDone + wave.length, resolve: resolve2 };
+        });
+        for (const item of wave) this.eventSubject.next(item);
+        await done;
+      }
+      failures = this.workFailed - failedBefore;
+    });
+    this.drainChain = run.then(() => void 0, () => void 0);
+    await run;
+    return failures;
+  }
+  /**
+   * `smelt:rebuild-anchors` — the operator's explicit re-derivation of
+   * anchored-text artifacts (PERSIST-ANCHORS P0), shaped after
+   * `weave:rebuild`: optionally scoped, strictly serialized (concatMap on
+   * the command stream + the drain chain), correlated ok/failed replies,
+   * and partial completion FAILS — a rebuild that quietly skipped resources
+   * would present exactly like a document with no text, which is the #845
+   * failure mode wearing different clothes.
+   *
+   * Never destructive: nothing is deleted first, stale entries are simply
+   * overwritten (the W5-frames lesson — a rebuild that clears before it
+   * re-derives turns a partial failure into a loss). Re-anchoring makes
+   * zero embedding calls; work items ride the normal per-resource lanes,
+   * so a rebuild can never interleave with live processing of the same
+   * resource (S1/S2).
+   */
+  async rebuildAnchors(command) {
+    const { correlationId, resourceId: resourceId10 } = command;
+    try {
+      let work;
+      if (resourceId10) {
+        work = [{ type: "smelt:reanchor", resourceId: resourceId10, payload: {} }];
+      } else {
+        const resources = await this.listAllResources();
+        work = [...this.classifyEmbeddable(resources)].filter(([, catalog]) => catalog.yieldsGeometry).map(([rid]) => ({ type: "smelt:reanchor", resourceId: rid, payload: {} }));
+      }
+      this.logger.info("Anchored-text rebuild started", { scoped: resourceId10 ?? null, resources: work.length });
+      const failed = await this.drain(work);
+      if (failed > 0) {
+        await this.bus.emit("smelt:rebuild-anchors-failed", {
+          ...correlationId ? { correlationId } : {},
+          message: `${failed} of ${work.length} resources failed to re-anchor \u2014 see smelter logs`
+        });
+        return;
+      }
+      await this.bus.emit("smelt:rebuild-anchors-ok", correlationId ? { correlationId } : {});
+      this.logger.info("Anchored-text rebuild complete", { scoped: resourceId10 ?? null, resources: work.length });
+    } catch (error) {
+      this.logger.error("Anchored-text rebuild failed", { error: errField(error) });
+      try {
+        await this.bus.emit("smelt:rebuild-anchors-failed", {
+          ...correlationId ? { correlationId } : {},
+          message: error instanceof Error ? error.message : String(error)
+        });
+      } catch (emitError) {
+        this.logger.warn("Failed to emit smelt:rebuild-anchors-failed", { error: errField(emitError) });
+      }
+    }
+  }
+  /**
+   * Embeddable live resources, each with the catalog's claims: the primary
+   * representation's checksum (the bytes the smelter would read), the
+   * current entity-type set (the discriminator the stamps must carry), and
+   * whether the media type's extractor derives geometry (whether an
+   * anchored-text artifact should exist). Embeddable ⇔ an extractor exists
+   * for the media type's strategy — the same registry the live fetch
+   * resolves, and `yieldsGeometry` is declared on the extractor itself, so
+   * every gate here and the live fetch's behavior are twins by construction.
+   * Shared by `reconcile()` and the `smelt:rebuild-anchors` planner.
+   */
+  classifyEmbeddable(resources) {
+    const embeddable = /* @__PURE__ */ new Map();
+    for (const resource of resources) {
+      const mediaType = getPrimaryMediaType(resource);
+      const extractor = mediaType ? EXTRACTORS[textExtractionOf(mediaType)] : null;
+      if (resource["@id"] && extractor) {
+        embeddable.set(resource["@id"], {
+          checksum: getPrimaryRepresentation(resource)?.checksum,
+          entityTypes: getResourceEntityTypes(resource),
+          yieldsGeometry: extractor.yieldsGeometry
+        });
+      }
     }
+    return embeddable;
   }
   /** Page through `browse:resources-requested` until the catalog is exhausted. */
   async listAllResources() {
@@ -13697,6 +13958,7 @@ var SMELTER_CHANNELS = [
   "mark:entity-tag-added",
   "mark:entity-tag-removed"
 ];
+var SMELTER_COMMAND_CHANNELS = ["smelt:rebuild-anchors"];
 function createSmelterActorStateUnit(options) {
   const { bus } = options;
   let started = false;
@@ -13711,12 +13973,14 @@ function createSmelterActorStateUnit(options) {
       )
     )
   );
+  const rebuildAnchors$ = bus.on$("smelt:rebuild-anchors");
   return {
     events$,
+    rebuildAnchors$,
     start: () => {
       if (started) return;
       started = true;
-      bus.addChannels?.([...SMELTER_CHANNELS]);
+      bus.addChannels?.([...SMELTER_CHANNELS, ...SMELTER_COMMAND_CHANNELS]);
     },
     dispose: () => {
       started = false;