@semiont/content 0.5.27 → 0.5.29

package/README.md

@@ -16,7 +16,7 @@ npm install @semiont/content
 
 ## Architecture Context
 
-**Infrastructure Ownership**: In production applications, the working tree store is **created and managed by [@semiont/make-meaning](../make-meaning/)'s `startMakeMeaning()` function**, which serves as the single orchestration point for all infrastructure components. Backend code accesses it as `knowledgeBase.content`.
+**Infrastructure Ownership**: In production applications, the working tree store is **created and managed by [@semiont/make-meaning](../make-meaning/)'s `startMakeMeaning()` function**, which serves as the single orchestration point for all infrastructure components. Gateway code accesses it as `knowledgeBase.content`.
 
 The quick start example below shows direct instantiation for **testing, CLI tools, or content management scripts**.
 
@@ -26,7 +26,9 @@ The quick start example below shows direct instantiation for **testing, CLI tool
 import { WorkingTreeStore, deriveStorageUri } from '@semiont/content';
 import { SemiontProject } from '@semiont/core/node';
 
-const project = new SemiontProject('/path/to/project');
+const project = new SemiontProject('/path/to/project', {
+  anchoredTextDir: process.env.SEMIONT_ANCHORED_TEXT_DIR!,
+});
 const store = new WorkingTreeStore(project);
 
 // Derive a stable file:// URI from a resource name

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { SemiontProject } from '@semiont/core/node';
-import { Logger, SupportedMediaType, ExtractionOutcome, PdfTextItem, TextExtraction, IContentTransport, AnchoredText } from '@semiont/core';
+import { Readable } from 'stream';
+import { SemiontProject, ArchivistAddressConfig } from '@semiont/core/node';
+import { Logger, ExtractionOutcome, PdfTextItem, TextExtraction, IContentTransport, AnchoredText } from '@semiont/core';
 
 /**
  * WorkingTreeStore - Manages files in the project working tree
@@ -12,9 +13,11 @@ import { Logger, SupportedMediaType, ExtractionOutcome, PdfTextItem, TextExtract
  * Two write paths:
  * - store(content, storageUri): Write bytes to disk (API/GUI/AI path).
  *   Used when the file does not yet exist and the caller provides content.
- * - register(storageUri, expectedChecksum?): Read an existing file and
- *   return its metadata (CLI path). The file is already on disk; we just
- *   verify and record it. If expectedChecksum is provided, throws on mismatch.
+ * - register(storageUri, expectedChecksum?): Adopt a file already on disk and
+ *   return its metadata. The CLI path (the file arrived by other means) and
+ *   the event-apply path (the Stower staging bytes an event names) both use
+ *   it. Streams the file to hash it — never holds it. If expectedChecksum is
+ *   provided, throws on mismatch.
  *
  * Storage layout:
  *   {projectRoot}/{path-from-uri}
@@ -44,20 +47,33 @@ declare class WorkingTreeStore {
     /**
      * Write content to disk at the location indicated by storageUri.
      *
-     * API/GUI/AI path: caller provides bytes; file may not yet exist.
+     * API/GUI/AI path: caller provides bytes — as a Buffer it already holds, or
+     * as a stream (the Archivist's write endpoint hands the request body
+     * straight through, SINGLE-KB-MOUNT P2/D7: memory stays bounded by the
+     * chunk, never the representation).
      *
-     * @param content - Raw bytes to write
+     * Atomic either way: bytes stream into a temp file beside the target and
+     * are renamed into place only once complete — and only once
+     * `expectedChecksum`, when given, agrees with what actually arrived. A
+     * mismatch or a torn stream leaves the target untouched (a version being
+     * overwritten survives) and no temp file behind, so the Stower's `register`
+     * can never find partial bytes an event names.
+     *
+     * @param content - Raw bytes to write, whole or streamed
      * @param storageUri - file:// URI (e.g. "file://docs/overview.md")
+     * @throws ChecksumMismatchError when expectedChecksum disagrees with the body
      * @returns Stored resource metadata
      */
-    store(content: Buffer, storageUri: string, options?: {
+    store(content: Buffer | Readable, storageUri: string, options?: {
         noGit?: boolean;
+        expectedChecksum?: string;
     }): Promise<StoredResource>;
     /**
      * Read an existing file and return its metadata.
      *
-     * CLI path: the file is already on disk. We read it to compute the checksum.
-     * If expectedChecksum is provided, throws ChecksumMismatchError on mismatch.
+     * The file is already on disk; this hashes it by streaming to confirm what
+     * it is, then stages it. If expectedChecksum is provided, throws
+     * ChecksumMismatchError on mismatch.
      *
      * @param storageUri - file:// URI (e.g. "file://docs/overview.md")
      * @param expectedChecksum - Optional SHA-256 to verify against
@@ -74,6 +90,19 @@ declare class WorkingTreeStore {
      * @param storageUri - file:// URI
      * @returns Raw bytes
      */
+    /**
+     * The same bytes as `retrieve`, streamed — for the byte paths that must not
+     * hold a whole representation in memory (SINGLE-KB-MOUNT D7: the Archivist
+     * serves content for every reader now, so its memory cannot be bounded by
+     * the largest file anyone asks for).
+     *
+     * Lazy by construction: the stream is created here but nothing is read
+     * until the caller iterates, so a missing file surfaces as an `error` event
+     * on the stream rather than a rejected promise. Callers that need the
+     * distinction up front should resolve the descriptor first — which is what
+     * `resolveRepresentation` does.
+     */
+    retrieveStream(storageUri: string): Readable;
     retrieve(storageUri: string): Promise<Buffer>;
     /**
      * Move a file from one URI to another.
@@ -128,26 +157,6 @@ declare class ChecksumMismatchError extends Error {
     constructor(storageUri: string, expected: string, actual: string);
 }
 
-/**
- * Storage URI Derivation
- *
- * Builds the file:// URI a resource lives at in the working tree from its
- * name and validated media type. Extensions come from the media-type
- * registry in @semiont/core; formats are validated upstream at the
- * create/yield boundary, so the lookup is strict — no fallback.
- */
-
-/**
- * Derive a file:// storage URI from a resource name and media type.
- *
- * The name is lowercased, runs of non-alphanumeric characters collapse to
- * single hyphens, and leading/trailing hyphens are stripped.
- *
- * @example
- * deriveStorageUri("My Document", "text/markdown") // => "file://my-document.md"
- */
-declare function deriveStorageUri(name: string, format: SupportedMediaType): string;
-
 /**
  * Checksum utilities for content verification
  */
@@ -187,13 +196,6 @@ declare function verifyChecksum(content: string | Buffer, checksum: string): boo
  * "no entry under the current checksum" as work (P0's third drift class).
  */
 
-/** The two halves of the wire record, split for storage. */
-type SuccessOutcome = Exclude<ExtractionOutcome, {
-    declined: string;
-}>;
-type DeclineOutcome = Extract<ExtractionOutcome, {
-    declined: string;
-}>;
 /**
  * One line of recognized text: the geometry every word on it shares, plus the
  * per-word parts that differ.
@@ -244,10 +246,14 @@ type CachedAnchoredText = ({
     stamp: string;
     text: string;
     lines: CachedLine[];
-} & Omit<SuccessOutcome, 'text' | 'items'>) | ({
+} & Omit<Extract<ExtractionOutcome, {
+    kind: 'extracted';
+}>, 'kind' | 'text' | 'items'>) | ({
     v: 2;
     stamp: string;
-} & DeclineOutcome);
+} & Omit<Extract<ExtractionOutcome, {
+    kind: 'declined';
+}>, 'kind'>);
 interface AnchoredTextStore {
     /**
      * The stored map for this key, or null for any miss. Never throws.
@@ -261,8 +267,19 @@ interface AnchoredTextStore {
      * key scheme here.
      */
     read(key: string): Promise<ExtractionOutcome | null>;
-    /** Record an extraction outcome under the content checksum of its source
-     *  bytes. A store that cannot write is still a store. */
+    /**
+     * Record an extraction outcome under the content checksum of its source
+     * bytes. **THROWS on failure: a write that returns has written.**
+     *
+     * Asymmetric with `read` above, which never throws, and deliberately so —
+     * a miss is a normal answer, a failed write is not. The store used to
+     * swallow for everyone, which forced the one caller that needs a throw
+     * (the Smelter's re-anchor publish, whose `smelt:rebuild-anchors-failed`
+     * accounting rides on it) to route around the store entirely. Now the
+     * contract is honest and **leniency is the caller's**, stated where it is
+     * wanted: the read-through seam in `pdf-extractor` catches, because a
+     * store may make extraction faster but must never make it fail.
+     */
     write(key: string, outcome: ExtractionOutcome): Promise<void>;
     /**
      * Every key `read()` would currently HIT — entries under a stale stamp or
@@ -307,6 +324,8 @@ declare function createAnchoredTextStore(dir: string, logger?: Logger): Anchored
  */
 
 interface ExtractedText {
+    /** Discriminant — mirrors the wire member (WIRE-UNION-DISCRIMINANTS P5c/D6). */
+    kind: 'extracted';
     /** Reading-order plain text, ready for the chunker. */
     text: string;
     /**
@@ -351,6 +370,8 @@ interface ExtractedText {
  * could not name its class; SMELTER-MEDIA-TYPES Phase 0 log, note a).
  */
 interface ExtractionDecline {
+    /** Discriminant — mirrors the wire member (WIRE-UNION-DISCRIMINANTS P5c/D6). */
+    kind: 'declined';
     declined: 'no-text-layer' | 'encrypted' | 'corrupt' | 'too-large';
 }
 /**
@@ -439,24 +460,54 @@ declare const MAX_PDF_BYTES: number;
 declare function withinByteBudget(bytes: number): boolean;
 
 /**
- * `AnchoredTextStore` over `IContentTransport` — how an out-of-process
- * extraction seam reaches the one real store (PERSIST-ANCHORS P2c).
+ * Reading a resource's bytes: the contract, the way it fails, and the
+ * implementation that reaches the Archivist over HTTP.
+ *
+ * These live in `@semiont/content` because this package IS the byte layer —
+ * the Archivist's whole job — and because the readers span the dependency
+ * graph. `@semiont/make-meaning` holds the Archivist itself and satisfies
+ * `ContentReads` in-process from the working tree; `@semiont/jobs` holds the
+ * Worker and can only reach the record over the wire. make-meaning depends on
+ * jobs, so anything both need has to sit under both (SINGLE-KB-MOUNT P4).
  *
- * Every cache consumer runs outside the backend — the smelter worker and the
- * detection workers — while the KnowledgeSystem owns the storage. This
- * adapter maps the store contract onto the transport's three
- * checksum-addressed calls, so `ExtractionCache { key, store }` works
- * identically in-process (LocalContentTransport → the store directly) and
- * over the wire (HttpContentTransport → the /anchored-text routes).
+ * Where the Archivist IS lives in `@semiont/core/node` (`archivistEndpoint`),
+ * not here: an address is a config value plus an environment variable, and
+ * the gateway needs it without needing a byte reader. One resolution, shared
+ * with the gateway's own proxying — the address and the secret are deployment
+ * facts, and a second copy of either is a second thing to get wrong.
  *
- * It honors the store contract's failure rule — the cache may make things
- * faster, never make them fail: a read or list failure is a miss, a write
- * failure is swallowed (debug-logged). Callers that need a write to be LOUD
- * — the re-anchor path, whose artifact IS the job — use the transport's
- * `putAnchoredText` directly, not this adapter.
+ * Absence fails loudly. A missing host or secret is a misconfiguration, never
+ * a reason to fall back to reading a tree locally — the point of
+ * SINGLE-KB-MOUNT is that exactly one process touches it.
  */
 
-declare function anchoredTextStoreOverTransport(content: IContentTransport, logger?: Logger): AnchoredTextStore;
+/**
+ * The byte read, and nothing else — DERIVED from the transport contract so it
+ * cannot drift from it. Keyed by ResourceId because that is the transport's
+ * key and the Archivist's: no caller converts to a tree address only to have
+ * the far side convert back.
+ */
+type ContentReads = Pick<IContentTransport, 'getBinary'>;
+/** Which half of the lookup failed — the gateway serves two different 404s. */
+type MissingReason = 'resource' | 'representation';
+declare class RepresentationMissing extends Error {
+    readonly resourceId: string;
+    readonly reason: MissingReason;
+    constructor(resourceId: string, reason: MissingReason);
+}
+/**
+ * `ContentReads` against the Archivist — how a fleet process that holds no KB
+ * mount reads bytes (SINGLE-KB-MOUNT P4).
+ *
+ * The address resolves HERE, at construction, not per read: a process with no
+ * Archivist configured must die while an operator is watching it boot, rather
+ * than fail every resource for the life of the process.
+ *
+ * A miss arrives as `RepresentationMissing` — the same error the in-process
+ * face throws for the same fact, so no caller can tell whether the bytes were
+ * a hop away. `reason` rides the wire precisely so this side need not guess.
+ */
+declare function archivistContentReads(config: ArchivistAddressConfig): ContentReads;
 
 /**
  * PDF Text Layer Types
@@ -532,5 +583,5 @@ interface PdfTextLayer extends AnchoredText {
 
 declare function extractPdfTextLayer(bytes: Uint8Array | Buffer): Promise<PdfTextLayer | null>;
 
-export { ChecksumMismatchError, EXTRACTORS, MAX_PDF_BYTES, WorkingTreeStore, anchoredTextStoreOverTransport, calculateChecksum, createAnchoredTextStore, deriveStorageUri, extractPdfTextLayer, verifyChecksum, withinByteBudget };
-export type { AnchoredTextStore, CachedAnchoredText, CachedLine, ContentExtractor, ExtractedText, ExtractionCache, ExtractionDecline, PdfFormField, PdfPageInfo, PdfTextLayer, StoredResource };
+export { ChecksumMismatchError, EXTRACTORS, MAX_PDF_BYTES, RepresentationMissing, WorkingTreeStore, archivistContentReads, calculateChecksum, createAnchoredTextStore, extractPdfTextLayer, verifyChecksum, withinByteBudget };
+export type { AnchoredTextStore, CachedAnchoredText, CachedLine, ContentExtractor, ContentReads, ExtractedText, ExtractionCache, ExtractionDecline, MissingReason, PdfFormField, PdfPageInfo, PdfTextLayer, StoredResource };

package/dist/index.js

@@ -1,20 +1,26 @@
 // src/working-tree-store.ts
-import { promises as fs } from "fs";
+import { promises as fs, createReadStream, createWriteStream } from "fs";
 import { execFileSync } from "child_process";
+import { createHash, randomUUID } from "crypto";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
 import path from "path";
-
-// src/checksum.ts
-import { createHash } from "crypto";
-function calculateChecksum(content) {
+function hashingTap() {
   const hash = createHash("sha256");
-  hash.update(content);
-  return hash.digest("hex");
-}
-function verifyChecksum(content, checksum) {
-  return calculateChecksum(content) === checksum;
+  let byteSize = 0;
+  return {
+    update(chunk2) {
+      hash.update(chunk2);
+      byteSize += chunk2.length;
+    },
+    get byteSize() {
+      return byteSize;
+    },
+    digest() {
+      return hash.digest("hex");
+    }
+  };
 }
-
-// src/working-tree-store.ts
 var WorkingTreeStore = class {
   projectRoot;
   gitSync;
@@ -30,34 +36,68 @@ var WorkingTreeStore = class {
   /**
    * Write content to disk at the location indicated by storageUri.
    *
-   * API/GUI/AI path: caller provides bytes; file may not yet exist.
+   * API/GUI/AI path: caller provides bytes — as a Buffer it already holds, or
+   * as a stream (the Archivist's write endpoint hands the request body
+   * straight through, SINGLE-KB-MOUNT P2/D7: memory stays bounded by the
+   * chunk, never the representation).
    *
-   * @param content - Raw bytes to write
+   * Atomic either way: bytes stream into a temp file beside the target and
+   * are renamed into place only once complete — and only once
+   * `expectedChecksum`, when given, agrees with what actually arrived. A
+   * mismatch or a torn stream leaves the target untouched (a version being
+   * overwritten survives) and no temp file behind, so the Stower's `register`
+   * can never find partial bytes an event names.
+   *
+   * @param content - Raw bytes to write, whole or streamed
    * @param storageUri - file:// URI (e.g. "file://docs/overview.md")
+   * @throws ChecksumMismatchError when expectedChecksum disagrees with the body
    * @returns Stored resource metadata
    */
   async store(content, storageUri, options) {
     const filePath = this.resolveUri(storageUri);
-    const checksum = calculateChecksum(content);
-    this.logger?.debug("Storing resource", { storageUri, byteSize: content.length });
+    const source = Buffer.isBuffer(content) ? Readable.from([content]) : content;
+    this.logger?.debug("Storing resource", { storageUri });
     await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, content);
-    if (this.shouldRunGit(options?.noGit)) {
-      execFileSync("git", ["add", filePath], { cwd: this.projectRoot });
+    const tempPath = `${filePath}.${randomUUID()}.tmp`;
+    const tap = hashingTap();
+    try {
+      await pipeline(
+        source,
+        async function* (chunks) {
+          for await (const chunk2 of chunks) {
+            tap.update(chunk2);
+            yield chunk2;
+          }
+        },
+        createWriteStream(tempPath)
+      );
+      const checksum = tap.digest();
+      const byteSize = tap.byteSize;
+      if (options?.expectedChecksum !== void 0 && options.expectedChecksum !== checksum) {
+        throw new ChecksumMismatchError(storageUri, options.expectedChecksum, checksum);
+      }
+      await fs.rename(tempPath, filePath);
+      if (this.shouldRunGit(options?.noGit)) {
+        execFileSync("git", ["add", filePath], { cwd: this.projectRoot });
+      }
+      this.logger?.info("Resource stored", { storageUri, checksum, byteSize });
+      return {
+        storageUri,
+        checksum,
+        byteSize,
+        created: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    } catch (error) {
+      await fs.rm(tempPath, { force: true });
+      throw error;
     }
-    this.logger?.info("Resource stored", { storageUri, checksum, byteSize: content.length });
-    return {
-      storageUri,
-      checksum,
-      byteSize: content.length,
-      created: (/* @__PURE__ */ new Date()).toISOString()
-    };
   }
   /**
    * Read an existing file and return its metadata.
    *
-   * CLI path: the file is already on disk. We read it to compute the checksum.
-   * If expectedChecksum is provided, throws ChecksumMismatchError on mismatch.
+   * The file is already on disk; this hashes it by streaming to confirm what
+   * it is, then stages it. If expectedChecksum is provided, throws
+   * ChecksumMismatchError on mismatch.
    *
    * @param storageUri - file:// URI (e.g. "file://docs/overview.md")
    * @param expectedChecksum - Optional SHA-256 to verify against
@@ -68,19 +108,23 @@ var WorkingTreeStore = class {
   async register(storageUri, expectedChecksum, options) {
     const filePath = this.resolveUri(storageUri);
     this.logger?.debug("Registering resource", { storageUri });
-    const content = await fs.readFile(filePath);
-    const checksum = calculateChecksum(content);
-    if (expectedChecksum !== void 0 && !verifyChecksum(content, expectedChecksum)) {
+    const tap = hashingTap();
+    for await (const chunk2 of createReadStream(filePath)) {
+      tap.update(chunk2);
+    }
+    const checksum = tap.digest();
+    if (expectedChecksum !== void 0 && checksum !== expectedChecksum) {
       throw new ChecksumMismatchError(storageUri, expectedChecksum, checksum);
     }
     if (this.shouldRunGit(options?.noGit)) {
       execFileSync("git", ["add", filePath], { cwd: this.projectRoot });
     }
-    this.logger?.info("Resource registered", { storageUri, checksum, byteSize: content.length });
+    const byteSize = tap.byteSize;
+    this.logger?.info("Resource registered", { storageUri, checksum, byteSize });
     return {
       storageUri,
       checksum,
-      byteSize: content.length,
+      byteSize,
       created: (/* @__PURE__ */ new Date()).toISOString()
     };
   }
@@ -90,6 +134,21 @@ var WorkingTreeStore = class {
    * @param storageUri - file:// URI
    * @returns Raw bytes
    */
+  /**
+   * The same bytes as `retrieve`, streamed — for the byte paths that must not
+   * hold a whole representation in memory (SINGLE-KB-MOUNT D7: the Archivist
+   * serves content for every reader now, so its memory cannot be bounded by
+   * the largest file anyone asks for).
+   *
+   * Lazy by construction: the stream is created here but nothing is read
+   * until the caller iterates, so a missing file surfaces as an `error` event
+   * on the stream rather than a rejected promise. Callers that need the
+   * distinction up front should resolve the descriptor first — which is what
+   * `resolveRepresentation` does.
+   */
+  retrieveStream(storageUri) {
+    return createReadStream(this.resolveUri(storageUri));
+  }
   async retrieve(storageUri) {
     const filePath = this.resolveUri(storageUri);
     try {
@@ -195,11 +254,15 @@ The file on disk differs from the recorded checksum. Has it been modified since
   actual;
 };
 
-// src/storage-uri.ts
-import { MEDIA_TYPES } from "@semiont/core";
-function deriveStorageUri(name, format) {
-  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-  return `file://${slug}${MEDIA_TYPES[format].extension}`;
+// src/checksum.ts
+import { createHash as createHash2 } from "crypto";
+function calculateChecksum(content) {
+  const hash = createHash2("sha256");
+  hash.update(content);
+  return hash.digest("hex");
+}
+function verifyChecksum(content, checksum) {
+  return calculateChecksum(content) === checksum;
 }
 
 // src/content-extractor.ts
@@ -725,7 +788,7 @@ function foldFormFields(layer) {
       height: field.height
     });
   }
-  return { text, items, method: "form", pdfClass: "E" };
+  return { kind: "extracted", text, items, method: "form", pdfClass: "E" };
 }
 function shapeTables(layer) {
   const pages = layer.pages.map((page) => {
@@ -748,7 +811,7 @@ function shapeTables(layer) {
       }
     }
   }
-  return { text, items, method: "table", pdfClass: "D" };
+  return { kind: "extracted", text, items, method: "table", pdfClass: "D" };
 }
 var pdfExtractor = {
   // Every non-declined PDF extraction carries positioned runs — native text
@@ -759,25 +822,29 @@ var pdfExtractor = {
     if (hit) return hit;
     const outcome = await extractPdf(content);
     if (cache) {
-      if ("declined" in outcome) await cache.store.write(cache.key, outcome);
-      else if (outcome.items) await cache.store.write(cache.key, { ...outcome, items: outcome.items });
+      try {
+        if (outcome.kind === "declined") await cache.store.write(cache.key, outcome);
+        else if (outcome.items) await cache.store.write(cache.key, { ...outcome, items: outcome.items });
+      } catch {
+      }
     }
     return outcome;
   }
 };
 async function extractPdf(content) {
-  if (!withinByteBudget(content.length)) return { declined: "too-large" };
+  if (!withinByteBudget(content.length)) return { kind: "declined", declined: "too-large" };
   let layer;
   try {
     layer = await extractPdfTextLayer(content);
   } catch (error) {
-    return { declined: classifyPdfError(error) };
+    return { kind: "declined", declined: classifyPdfError(error) };
   }
   if (!layer) {
     const ocr2 = await ocrPages(content);
-    if (!ocr2.text) return { declined: "no-text-layer" };
+    if (!ocr2.text) return { kind: "declined", declined: "no-text-layer" };
     const confidence2 = summarize(ocr2.confidences);
     return {
+      kind: "extracted",
       text: ocr2.text,
       items: ocr2.items,
       method: "ocr",
@@ -785,7 +852,7 @@ async function extractPdf(content) {
       ...confidence2 ? { ocrConfidence: confidence2 } : {}
     };
   }
-  const shaped = layer.fields.length > 0 ? foldFormFields(layer) : shapeTables(layer) ?? { text: layer.text, items: layer.items, method: "pdf-text-layer", pdfClass: "A" };
+  const shaped = layer.fields.length > 0 ? foldFormFields(layer) : shapeTables(layer) ?? { kind: "extracted", text: layer.text, items: layer.items, method: "pdf-text-layer", pdfClass: "A" };
   const unreadPages = layer.pages.filter((page) => !page.hasTextLayer).map((page) => page.pageNumber);
   if (unreadPages.length === 0) return shaped;
   const recovered = await ocrPages(content, unreadPages);
@@ -818,7 +885,7 @@ async function extractPdf(content) {
 var passthroughExtractor = {
   yieldsGeometry: false,
   async extract(content, mediaType) {
-    return { text: decodeRepresentation(content, mediaType), method: "text-passthrough" };
+    return { kind: "extracted", text: decodeRepresentation(content, mediaType), method: "text-passthrough" };
   }
 };
 var EXTRACTORS = {
@@ -896,9 +963,9 @@ function createAnchoredTextStore(dir, logger) {
         ...hit ? "declined" in hit ? { declined: hit.declined } : { lines: hit.lines.length } : {}
       });
       if (!hit) return null;
-      if ("declined" in hit) return { declined: hit.declined };
+      if ("declined" in hit) return { kind: "declined", declined: hit.declined };
       const { v: _v, stamp: _stamp, lines, text, ...provenance } = hit;
-      return { text, items: decodeLines(lines), ...provenance };
+      return { kind: "extracted", text, items: decodeLines(lines), ...provenance };
     },
     async write(key, outcome) {
       const target = fileFor(key);
@@ -906,8 +973,8 @@ function createAnchoredTextStore(dir, logger) {
         logger?.debug("Anchored-text cache: refusing invalid key", { key });
         return;
       }
-      const entry = "declined" in outcome ? { v: 2, stamp: STAMP, declined: outcome.declined } : (() => {
-        const { text, items, ...provenance } = outcome;
+      const entry = outcome.kind === "declined" ? { v: 2, stamp: STAMP, declined: outcome.declined } : (() => {
+        const { kind: _kind, text, items, ...provenance } = outcome;
         return { v: 2, stamp: STAMP, text, lines: encodeLines(items), ...provenance };
       })();
       const temp = `${target}.${process.pid}.tmp`;
@@ -915,9 +982,10 @@ function createAnchoredTextStore(dir, logger) {
         await fs2.promises.mkdir(path3.dirname(target), { recursive: true });
         await fs2.promises.writeFile(temp, JSON.stringify(entry), "utf8");
         await fs2.promises.rename(temp, target);
-      } catch {
+      } catch (error) {
         await fs2.promises.rm(temp, { force: true }).catch(() => {
         });
+        throw error;
       }
     },
     async list() {
@@ -987,39 +1055,40 @@ function createAnchoredTextStore(dir, logger) {
   };
 }
 
-// src/anchored-text-store-adapter.ts
-function anchoredTextStoreOverTransport(content, logger) {
+// src/representation-reads.ts
+import { archivistEndpoint } from "@semiont/core/node";
+var RepresentationMissing = class extends Error {
+  constructor(resourceId, reason) {
+    super(
+      reason === "resource" ? `Resource not found: ${resourceId}` : `Resource representation not found: no storageUri for ${resourceId}`
+    );
+    this.resourceId = resourceId;
+    this.reason = reason;
+    this.name = "RepresentationMissing";
+  }
+  resourceId;
+  reason;
+};
+function archivistContentReads(config) {
+  const { base, headers } = archivistEndpoint(config);
   return {
-    async read(key) {
-      try {
-        return await content.getAnchoredTextByChecksum(key);
-      } catch (error) {
-        logger?.debug("Anchored-text cache: transport read failed \u2014 treating as miss", {
-          key,
-          reason: error instanceof Error ? error.message : String(error)
-        });
-        return null;
-      }
-    },
-    async write(key, outcome) {
-      try {
-        await content.putAnchoredText(key, outcome);
-      } catch (error) {
-        logger?.debug("Anchored-text cache: transport write failed \u2014 entry not stored", {
-          key,
-          reason: error instanceof Error ? error.message : String(error)
-        });
+    getBinary: async (resourceId) => {
+      const url = `${base}/resources/${encodeURIComponent(String(resourceId))}/content`;
+      const res = await fetch(url, { headers });
+      if (res.status === 404) {
+        const { reason } = await res.json().catch(() => ({}));
+        throw new RepresentationMissing(
+          String(resourceId),
+          reason === "representation" ? "representation" : "resource"
+        );
       }
-    },
-    async list() {
-      try {
-        return await content.listAnchoredTextKeys();
-      } catch (error) {
-        logger?.debug("Anchored-text cache: transport list failed \u2014 treating as empty", {
-          reason: error instanceof Error ? error.message : String(error)
-        });
-        return [];
+      if (!res.ok) {
+        throw new Error(`Archivist content read failed for ${String(resourceId)}: ${res.status} ${res.statusText}`);
       }
+      return {
+        data: await res.arrayBuffer(),
+        contentType: res.headers.get("content-type") || "application/octet-stream"
+      };
     }
   };
 }
@@ -1027,11 +1096,11 @@ export {
   ChecksumMismatchError,
   EXTRACTORS,
   MAX_PDF_BYTES,
+  RepresentationMissing,
   WorkingTreeStore,
-  anchoredTextStoreOverTransport,
+  archivistContentReads,
   calculateChecksum,
   createAnchoredTextStore,
-  deriveStorageUri,
   extractPdfTextLayer,
   verifyChecksum,
   withinByteBudget