sentinelayer-cli 0.40.0 → 0.42.0

package/src/engram/build-state.js

@@ -0,0 +1,183 @@
+/**
+ * ENGRAM — build lifecycle: absent | building | ready.
+ *
+ * An engram that is auto-built on session load is queryable by definition: something
+ * will ask it a question while it is still being written. The dangerous answer is not
+ * an error, it is a PLAUSIBLE one — a needle search over a half-ingested document
+ * finds the best match among the chunks that happen to exist and returns it with the
+ * same confidence it would give a complete index. The caller cannot tell the
+ * difference, because a partial index does not look partial from the outside.
+ *
+ * So readiness is a fact that must be RECORDED, never inferred:
+ *
+ *   absent    no build has started
+ *   building  a build started and has not recorded completion -- REFUSES queries
+ *   ready     a build recorded completion, and the counts and digest agree
+ *
+ * THE CASE THIS IS BUILT AROUND: a build that DIES halfway. Nothing gets to observe
+ * the crash, so the state must be wrong-by-default in the safe direction. `begin`
+ * writes `building` BEFORE any chunk is written and only `complete` moves it to
+ * `ready`, so a killed process leaves `building` on disk forever. That is the
+ * intended outcome -- an engram nobody finished must never answer as though someone
+ * had. Recovery is to re-run the build, which is safe because ingestion is idempotent.
+ *
+ * A torn or unparseable state file is treated as `building` for the same reason:
+ * every unreadable state resolves to the one that refuses.
+ */
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { namespaceDir } from "./store.js";
+
+export const BUILD_STATES = Object.freeze({
+  ABSENT: "absent",
+  BUILDING: "building",
+  READY: "ready",
+});
+
+const STATE_FILE = "build-state.json";
+
+/** Raised when a namespace is asked a question it cannot honestly answer yet. */
+export class EngramNotReadyError extends Error {
+  constructor(namespace, state) {
+    super(`engram namespace "${namespace}" is ${state}, not ready: refusing to answer from a partial index`);
+    this.name = "EngramNotReadyError";
+    this.state = state;
+    this.namespace = namespace;
+  }
+}
+
+function stateFile(root, namespace) {
+  return path.join(namespaceDir(root, namespace), STATE_FILE);
+}
+
+/**
+ * Write JSON so a crash mid-write cannot leave a half-file that parses.
+ * Temp file + rename is atomic within a directory on every platform we run on.
+ */
+async function writeAtomic(file, value) {
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fsp.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+  await fsp.rename(tmp, file);
+}
+
+export function createBuildState({ storeRoot } = {}) {
+  const root = path.resolve(String(storeRoot || "."));
+
+  async function read(namespace) {
+    let raw;
+    try {
+      raw = await fsp.readFile(stateFile(root, namespace), "utf-8");
+    } catch (error) {
+      if (error && error.code === "ENOENT") return { state: BUILD_STATES.ABSENT };
+      throw error;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      // Unreadable state resolves to the one that REFUSES, never to ready.
+      return { state: BUILD_STATES.BUILDING, reason: "state file is unreadable" };
+    }
+    if (!parsed || typeof parsed !== "object") {
+      return { state: BUILD_STATES.BUILDING, reason: "state file is not an object" };
+    }
+    if (parsed.state === BUILD_STATES.READY) {
+      // READY is only honoured when its own record is self-consistent. A count or
+      // digest that disagrees means something wrote this file without finishing the
+      // work it describes.
+      const consistent =
+        Number.isInteger(parsed.expectedChunks) &&
+        Number.isInteger(parsed.writtenChunks) &&
+        parsed.expectedChunks === parsed.writtenChunks &&
+        typeof parsed.completedAt === "string" &&
+        parsed.completedAt.length > 0;
+      if (!consistent) {
+        return { ...parsed, state: BUILD_STATES.BUILDING, reason: "ready record is inconsistent" };
+      }
+    }
+    return parsed;
+  }
+
+  return {
+    read,
+
+    /** Mark a build STARTED. Must be called before the first chunk is written. */
+    async begin(namespace, { docDigest = null, expectedChunks = null, startedAt } = {}) {
+      const record = {
+        state: BUILD_STATES.BUILDING,
+        namespace: namespace.raw,
+        docDigest,
+        expectedChunks,
+        writtenChunks: 0,
+        startedAt: startedAt || new Date().toISOString(),
+        completedAt: null,
+      };
+      await writeAtomic(stateFile(root, namespace), record);
+      return record;
+    },
+
+    /**
+     * Mark a build COMPLETE. Refuses when the work does not match what `begin`
+     * promised -- completing a build that wrote fewer chunks than expected would
+     * stamp `ready` on a partial index, which is the whole failure this module exists
+     * to prevent.
+     */
+    async complete(namespace, { writtenChunks, completedAt } = {}) {
+      const current = await read(namespace);
+      if (current.state === BUILD_STATES.ABSENT) {
+        throw new Error("cannot complete a build that never began");
+      }
+      if (!Number.isInteger(writtenChunks) || writtenChunks < 0) {
+        throw new TypeError("writtenChunks must be a non-negative integer");
+      }
+      if (Number.isInteger(current.expectedChunks) && current.expectedChunks !== writtenChunks) {
+        throw new Error(
+          `refusing to mark ready: expected ${current.expectedChunks} chunks, wrote ${writtenChunks}`,
+        );
+      }
+      const record = {
+        ...current,
+        state: BUILD_STATES.READY,
+        writtenChunks,
+        expectedChunks: Number.isInteger(current.expectedChunks) ? current.expectedChunks : writtenChunks,
+        completedAt: completedAt || new Date().toISOString(),
+        reason: undefined,
+      };
+      delete record.reason;
+      await writeAtomic(stateFile(root, namespace), record);
+      return record;
+    },
+
+    /**
+     * Throw ONLY when a build is in flight. The gate the RETRIEVAL path calls.
+     *
+     * Deliberately weaker than `assertQueryable`, and the difference is the whole
+     * reason this exists: `absent` must be ALLOWED. A session namespace is adapter-
+     * backed and live — nobody ever "builds" it, so it has no state file and never
+     * will. Requiring `ready` there would refuse every session recall in the product.
+     *
+     * What must be refused is the state where answering is actively misleading: a
+     * document half-written to disk, where recall would return the best match among
+     * the chunks that happen to exist and look exactly like a complete answer.
+     */
+    async assertNotBuilding(namespace) {
+      const current = await read(namespace);
+      if (current.state === BUILD_STATES.BUILDING) {
+        throw new EngramNotReadyError(namespace.raw, current.state);
+      }
+      return current;
+    },
+
+    /** Throw unless the namespace is ready. For callers that require a finished build. */
+    async assertQueryable(namespace) {
+      const current = await read(namespace);
+      if (current.state !== BUILD_STATES.READY) {
+        throw new EngramNotReadyError(namespace.raw, current.state);
+      }
+      return current;
+    },
+  };
+}

package/src/engram/canonical.js

@@ -0,0 +1,75 @@
+// canonical.js — the spine's canonical JSON encoder (ENGRAM identity substrate).
+//
+// Implements the JCS-subset of respawn contract §19.1 (docs/contracts/checkpoint-proof-identity.md,
+// respawn repo): RFC 8785 canonical JSON restricted to INTEGER-ONLY numbers. This is the encoder
+// whose output bytes are the preimage for content-addressed observation ids (sha256 over canonical
+// JSON). Conformance: tests/fixtures/engram/canonicalization-vectors-v1.json (published hash
+// 16b93737…, five vectors incl. the NFC/NFD never-normalize pair) — exercised by
+// tests/unit.engram-canonical.test.mjs (required glob) and conformance gate (i) (§21.3).
+//
+// Rules (each REFUSES rather than guessing — no third behavior, §19.1):
+//   • Object keys sorted by UTF-16 code units (RFC 8785 §3.2.3). No whitespace.
+//   • Strings serialized per JSON.stringify (JCS-compatible escaping), NEVER unicode-normalized:
+//     NFC and NFD spellings are DIFFERENT bytes and must yield different digests (vector 4).
+//   • Numbers: safe integers only. -0 encodes as 0. Non-integers, NaN, ±Infinity, unsafe
+//     magnitudes, and BigInt REFUSE at encode time.
+//   • Values: null, boolean, string, integer, array, PLAIN object only. Dates, Maps, class
+//     instances, functions, symbols, and undefined REFUSE — an identity encoder must never
+//     silently coerce. Circular structures REFUSE.
+//   • Object entries whose value is undefined REFUSE (not skipped): an absent optional is
+//     expressed by OMITTING the key (vector 3), and silently dropping undefined would let two
+//     different in-memory shapes share one identity.
+
+const REFUSE = (msg) => {
+  throw new TypeError(`canonicalize: ${msg}`);
+};
+
+function isPlainObject(v) {
+  if (v === null || typeof v !== "object") return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+function encode(value, seen, path) {
+  switch (typeof value) {
+    case "boolean":
+      return value ? "true" : "false";
+    case "number": {
+      if (!Number.isFinite(value)) REFUSE(`non-finite number at ${path} — integer-only (§19.1)`);
+      if (!Number.isInteger(value)) REFUSE(`non-integer number ${value} at ${path} — integer-only (§19.1)`);
+      if (!Number.isSafeInteger(value)) REFUSE(`integer magnitude beyond 2^53-1 at ${path} — unrepresentable exactly`);
+      return String(value === 0 ? 0 : value); // -0 → "0" (RFC 8785)
+    }
+    case "string":
+      return JSON.stringify(value); // JCS-compatible escaping; NO normalization
+    case "bigint":
+      REFUSE(`BigInt at ${path} — integer-only means JSON numbers (§19.1)`);
+      break;
+    case "undefined":
+      REFUSE(`undefined at ${path} — absent optionals OMIT the key`);
+      break;
+    case "function":
+    case "symbol":
+      REFUSE(`${typeof value} at ${path} — not a JSON value`);
+      break;
+  }
+  if (value === null) return "null";
+  if (seen.has(value)) REFUSE(`circular reference at ${path}`);
+  if (Array.isArray(value)) {
+    seen.add(value);
+    const parts = value.map((item, i) => encode(item, seen, `${path}[${i}]`));
+    seen.delete(value);
+    return `[${parts.join(",")}]`;
+  }
+  if (!isPlainObject(value)) REFUSE(`non-plain object (${value.constructor?.name ?? "unknown"}) at ${path} — refuse, never coerce`);
+  seen.add(value);
+  const keys = Object.keys(value).sort(); // default sort = UTF-16 code unit order (RFC 8785 §3.2.3)
+  const parts = keys.map((k) => `${JSON.stringify(k)}:${encode(value[k], seen, `${path}.${k}`)}`);
+  seen.delete(value);
+  return `{${parts.join(",")}}`;
+}
+
+/** Canonicalize a value to its §19.1 canonical JSON string (UTF-8 of this string is the digest preimage). */
+export function canonicalize(value) {
+  return encode(value, new Set(), "$");
+}

package/src/engram/document.js

@@ -0,0 +1,190 @@
+/**
+ * ENGRAM — document ingestion with SPAN-LEVEL PROVENANCE.
+ *
+ * The session adapter's atom is a message, addressed by `sequenceId`. A document
+ * has no such atom: it must be chunked, and the moment you chunk without recording
+ * each chunk's position you can name a chunk but cannot prove it is the line the
+ * caller asked for. "What is on page 3337 line 45" then gets answered by something
+ * that SOUNDS right, which is worse than not answering.
+ *
+ * So every chunk carries where it came from, and `resolveSpan` re-reads the source
+ * to prove the quote rather than trusting the stored copy.
+ *
+ * TWO THINGS THAT ARE NOT OBVIOUS AND ARE LOAD-BEARING:
+ *
+ * 1. IDENTITY MUST INCLUDE POSITION. `itemId` (store.js) hashes
+ *    [kind, author, text, ts] and the store DEDUPES on it. Documents repeat
+ *    themselves constantly -- blank lines, `---`, table rows, boilerplate, a
+ *    recurring header -- and every repeat after the first would be silently
+ *    dropped, its position unrecoverable, precisely when the queried line is a
+ *    common one. `itemId` honours an explicit `id`, so chunks set one that
+ *    includes the span. Same document re-ingested -> identical ids (idempotent,
+ *    which is what makes "build once, serve everyone" real); same text at a
+ *    different offset -> a different id, which is correct because it is a
+ *    different occurrence.
+ *
+ * 2. OFFSETS ARE UTF-16 CODE UNITS, NOT BYTES. They index the JS string, so
+ *    `text.slice(start, end)` is exact by construction. For any source containing
+ *    astral characters these differ from byte offsets, and calling them "byte
+ *    offsets" would be a claim this module does not support. `docDigest` is
+ *    SHA-256 over the UTF-8 encoding of the whole document -- that one IS
+ *    tamper-evidence, unlike the store's FNV-1a `contentHash`, which is a dedup
+ *    key and nothing more.
+ */
+
+import { createHash } from "node:crypto";
+
+/** Chunk kind. Distinct from `session` so a namespace's atoms are never confused. */
+export const DOCUMENT_CHUNK_KIND = "document";
+
+/** SHA-256 over the document's UTF-8 bytes. Tamper-evidence, not a dedup key. */
+export function documentDigest(text) {
+  return createHash("sha256").update(String(text ?? ""), "utf8").digest("hex");
+}
+
+/**
+ * Deterministic, position-inclusive chunk id.
+ * Same (document, span) -> same id, on every run and every machine.
+ */
+export function chunkId(digest, start, end) {
+  return `doc:${String(digest).slice(0, 16)}:${start}-${end}`;
+}
+
+/**
+ * Split on line boundaries, accumulating whole lines up to `maxChars`.
+ *
+ * Line-aligned deliberately: the caller's question is "page N line M", so a chunk
+ * that begins mid-line makes the answer harder to prove than it needs to be. A
+ * single line longer than `maxChars` is emitted whole rather than split, because
+ * truncating it would produce a chunk whose text is not what the source says.
+ *
+ * @param {string} text                 the whole document, verbatim
+ * @param {object} [options]
+ * @param {number} [options.maxChars]   soft ceiling per chunk (UTF-16 code units)
+ * @param {number} [options.linesPerPage] lines per page for the `page` coordinate
+ * @returns {{start:number,end:number,line:number,endLine:number,page:number,text:string}[]}
+ */
+export function splitIntoSpans(text, { maxChars = 1200, linesPerPage = 50 } = {}) {
+  const source = String(text ?? "");
+  if (!source) return [];
+  if (!Number.isInteger(maxChars) || maxChars < 1) {
+    throw new TypeError("maxChars must be a positive integer");
+  }
+  if (!Number.isInteger(linesPerPage) || linesPerPage < 1) {
+    throw new TypeError("linesPerPage must be a positive integer");
+  }
+
+  const spans = [];
+  let chunkStart = 0;
+  let cursor = 0;
+  let line = 1;
+  let chunkStartLine = 1;
+
+  const flush = (end, endLine) => {
+    if (end <= chunkStart) return;
+    spans.push({
+      start: chunkStart,
+      end,
+      line: chunkStartLine,
+      endLine,
+      page: Math.floor((chunkStartLine - 1) / linesPerPage) + 1,
+      text: source.slice(chunkStart, end),
+    });
+  };
+
+  while (cursor < source.length) {
+    const nl = source.indexOf("\n", cursor);
+    const lineEnd = nl === -1 ? source.length : nl + 1;
+    // Would adding this line overflow a non-empty chunk? Close the chunk first.
+    if (lineEnd - chunkStart > maxChars && cursor > chunkStart) {
+      flush(cursor, line - 1);
+      chunkStart = cursor;
+      chunkStartLine = line;
+    }
+    cursor = lineEnd;
+    if (nl !== -1) line += 1;
+  }
+  flush(cursor, lastCoveredLine(line, source));
+  return spans;
+}
+
+/** The last line number covered when the document does not end in a newline. */
+function lastCoveredLine(line, source) {
+  return source.endsWith("\n") ? Math.max(1, line - 1) : line;
+}
+
+/**
+ * Ingest a document as span-carrying store items.
+ *
+ * The span rides INSIDE the item (not alongside it) so it is covered by whatever
+ * digests the item, and the id encodes the span so the store's content-hash dedup
+ * cannot collapse two occurrences of the same text.
+ *
+ * @param {string} text
+ * @param {object} options
+ * @param {string} options.source   human-readable origin (filename, url, title)
+ * @param {string} [options.author]
+ * @param {string} [options.ts]     ISO timestamp; defaults to now
+ * @returns {{docDigest:string, source:string, chars:number, items:object[]}}
+ */
+export function ingestDocument(text, { source, author = "document", ts, maxChars, linesPerPage } = {}) {
+  const body = String(text ?? "");
+  const origin = String(source ?? "").trim();
+  if (!origin) throw new TypeError("source is required: an unattributed span cannot be verified");
+
+  const docDigest = documentDigest(body);
+  const stamp = ts || new Date().toISOString();
+  const spans = splitIntoSpans(body, {
+    ...(maxChars === undefined ? {} : { maxChars }),
+    ...(linesPerPage === undefined ? {} : { linesPerPage }),
+  });
+
+  const items = spans.map((span) => ({
+    id: chunkId(docDigest, span.start, span.end),
+    kind: DOCUMENT_CHUNK_KIND,
+    author,
+    ts: stamp,
+    text: span.text,
+    span: {
+      start: span.start,
+      end: span.end,
+      line: span.line,
+      endLine: span.endLine,
+      page: span.page,
+    },
+    docDigest,
+    source: origin,
+  }));
+
+  return { docDigest, source: origin, chars: body.length, items };
+}
+
+/**
+ * Re-derive a chunk's text FROM THE SOURCE and prove it matches what was stored.
+ *
+ * This is the whole point of the module: a needle answer is only trustworthy if
+ * the quote can be reproduced from the original at the coordinates it claims. A
+ * mismatch means the stored copy and the source have diverged, and the honest
+ * response is to refuse rather than serve the stored text as though verified.
+ *
+ * @returns {{ok:true, quote:string, start:number, end:number, line:number, page:number}
+ *          | {ok:false, reason:string}}
+ */
+export function resolveSpan(documentText, item) {
+  const source = String(documentText ?? "");
+  const span = item?.span;
+  if (!span || !Number.isInteger(span.start) || !Number.isInteger(span.end)) {
+    return { ok: false, reason: "item carries no integer span" };
+  }
+  if (span.start < 0 || span.end > source.length || span.end < span.start) {
+    return { ok: false, reason: "span does not lie within the document" };
+  }
+  if (item.docDigest && documentDigest(source) !== item.docDigest) {
+    return { ok: false, reason: "document digest does not match the one the span was cut from" };
+  }
+  const quote = source.slice(span.start, span.end);
+  if (typeof item.text === "string" && quote !== item.text) {
+    return { ok: false, reason: "stored text does not match the source at that span" };
+  }
+  return { ok: true, quote, start: span.start, end: span.end, line: span.line, page: span.page };
+}

package/src/engram/governance.js

@@ -0,0 +1,67 @@
+/**
+ * ENGRAM §2 — governance seams: signed recall receipts + per-call metering.
+ *
+ * Both are CLEAN INTERFACES with P0 stubs, because the real backing is not
+ * reachable in P0 (confirmed by the API scout):
+ *   - Receipt signing = AIdenID, which is an EXTERNAL service
+ *     (api.aidenid.com); this repo is only a client. §9 receipt shape is
+ *     {caller, scope, ts, sig}. P0 emits an UNSIGNED receipt (sig=null) and
+ *     marks stub:true — the seam is present so §2.1 drops in a real signer.
+ *   - Metering = the server usage ledger is session-welded
+ *     (SessionUsageLedgerEntry requires session_id + session_sequence_id).
+ *     §2.1 generalizes it to a namespace/tenant ledger keyed on
+ *     billing_account_id. P0 records a local stub entry.
+ *
+ * Never skip the seam — always emit (stub or real) so callers and tests can
+ * assert governance fired on every write/recall/summarize.
+ */
+
+/**
+ * @param {object} [options]
+ * @param {{sign: (payload:object)=>Promise<string>|string}} [options.signer]  Real receipt signer (§2.1 AIdenID).
+ * @param {{record: (entry:object)=>Promise<void>|void}} [options.meterSink]   Real usage-ledger sink (§2.1).
+ * @param {()=>string} [options.now]
+ */
+export function createGovernance({ signer = null, meterSink = null, now = () => new Date().toISOString() } = {}) {
+  return {
+    /**
+     * Emit a signed recall receipt (§9 {caller, scope, ts, sig}).
+     * @returns {Promise<object>}
+     */
+    async emitRecallReceipt({ caller, scope, namespace, query = "", resultCount = 0 } = {}) {
+      const base = {
+        caller: caller?.id || null,
+        scope,
+        namespace: namespace || scope,
+        query,
+        resultCount,
+        ts: now(),
+      };
+      if (signer && typeof signer.sign === "function") {
+        const sig = await signer.sign(base);
+        return { ...base, sig, stub: false };
+      }
+      return { ...base, sig: null, stub: true, seam: "aidenid-external-signer" };
+    },
+
+    /**
+     * Meter one MaaS call.
+     * @returns {Promise<object>}
+     */
+    async meter({ namespace, caller, action, count = 1, tokens = 0 } = {}) {
+      const entry = {
+        namespace,
+        caller: caller?.id || null,
+        action,
+        count,
+        tokens,
+        ts: now(),
+      };
+      if (meterSink && typeof meterSink.record === "function") {
+        await meterSink.record(entry);
+        return { ...entry, stub: false };
+      }
+      return { ...entry, stub: true, seam: "namespace-usage-ledger" };
+    },
+  };
+}

package/src/engram/index.js

@@ -0,0 +1,73 @@
+/**
+ * ENGRAM §2 — Memory-as-a-Service: detachable public entry point.
+ *
+ * This barrel is the sellable-alone surface: the 3 tools + the store, trust,
+ * governance, and namespace seams, over the §1 recall engine. It imports NO
+ * SentinelLayer session/mcp/auth runtime — the SL session is just ONE injected
+ * store adapter (see the CLI wiring in src/mcp/session-stdio-server.js).
+ */
+
+export { createStore, itemId } from "./store.js";
+export {
+  parseNamespace,
+  authorize,
+  createLocalConsent,
+  AccessDeniedError,
+  ACTION_SCOPES,
+} from "./namespace.js";
+export {
+  TRUST_LEVELS,
+  AUTHORITATIVE_FLOOR,
+  classifyWrite,
+  classifyObservation,
+  isAuthoritative,
+  trustRank,
+  sealItem,
+  visibleUnderScope,
+} from "./trust.js";
+export { createGovernance } from "./governance.js";
+export { createMemoryTools } from "./tools.js";
+export { runEngramSla } from "./sla.js";
+export { ingestDocumentIntoNamespace } from "./ingest-document.js";
+
+import { createStore } from "./store.js";
+import { createLocalConsent } from "./namespace.js";
+import { createGovernance } from "./governance.js";
+import { createBuildState } from "./build-state.js";
+import { ingestDocumentIntoNamespace } from "./ingest-document.js";
+import { createMemoryTools } from "./tools.js";
+import { createEmbedder } from "../session/recall/embedder.js";
+
+/**
+ * Convenience factory: wire a default CLI-local MaaS instance (permissive-local
+ * consent, stub governance, hash-projection embedder) over a store. Callers
+ * inject `adapters` (e.g. { session }) to make a kind a first-class namespace.
+ *
+ * @param {object} options
+ * @param {string} options.storeRoot
+ * @param {Record<string,Function>} [options.adapters]
+ * @param {object} [options.embedder]
+ * @param {object} [options.consent]
+ * @param {object} [options.governance]
+ * @param {object} [options.renderer]
+ * @returns {{tools: object, store: object}}
+ */
+export function createMemoryService({
+  storeRoot,
+  adapters = {},
+  embedder = createEmbedder(),
+  consent = createLocalConsent(),
+  governance = createGovernance(),
+  renderer = null,
+  isAuthorizedForSealed,
+} = {}) {
+  const store = createStore({ storeRoot, adapters });
+  // Wired by DEFAULT, not opt-in: a readiness gate nobody injects is a comment.
+  const buildState = createBuildState({ storeRoot });
+  const tools = createMemoryTools({ store, consent, governance, embedder, renderer, isAuthorizedForSealed, buildState });
+  // Exposed on the service so the lifecycle cannot be bypassed by a caller who has a
+  // store but forgets the buildState -- the deps are bound here, once.
+  const ingestDocument = (options) =>
+    ingestDocumentIntoNamespace({ ...options, deps: { store, buildState } });
+  return { tools, store, buildState, ingestDocument };
+}