sentinelayer-cli 0.41.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/index.js

@@ -28,10 +28,13 @@ export {
 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";
 
@@ -59,6 +62,12 @@ export function createMemoryService({
   isAuthorizedForSealed,
 } = {}) {
   const store = createStore({ storeRoot, adapters });
-  const tools = createMemoryTools({ store, consent, governance, embedder, renderer, isAuthorizedForSealed });
-  return { tools, store };
+  // 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 };
 }

package/src/engram/ingest-document.js

@@ -0,0 +1,107 @@
+/**
+ * ENGRAM — the document ingest path: the thing that makes the other three real.
+ *
+ * Before this, the pieces existed and none of them ran together:
+ *   document.js     could cut a document into span-carrying chunks -- nothing called it
+ *   build-state.js  could refuse a half-built namespace -- but nothing ever called
+ *                   `begin()`, so BUILDING was UNREACHABLE and the gate #808 wired
+ *                   could never actually fire
+ *
+ * A gate that is invoked but guards a state nothing can enter is a subtler version of
+ * a gate nobody invokes: it runs, it passes, and it has never once said no.
+ *
+ * ORDER IS THE WHOLE DESIGN, and it is chosen for the failure case rather than the
+ * happy one:
+ *
+ *   1. begin()      BEFORE the first chunk is written
+ *   2. write chunks
+ *   3. complete()   only after every chunk landed, with the count checked
+ *
+ * If the process dies at step 2 -- or the store throws, or the disk fills -- nothing
+ * runs step 3, so the namespace stays BUILDING and refuses queries FOREVER rather than
+ * silently serving a partial index. Recovery is to re-ingest, which is safe because
+ * chunk ids are content+position addressed: the chunks already written dedupe, the
+ * missing ones land, and the build completes.
+ *
+ * The alternative order -- write first, then mark building -- would leave a window
+ * where a partial index answers as though whole, which is the exact failure the
+ * lifecycle exists to prevent.
+ */
+
+import { ingestDocument } from "./document.js";
+import { parseNamespace } from "./namespace.js";
+
+/**
+ * Ingest a document into a namespace, under the build lifecycle.
+ *
+ * @param {object} options
+ * @param {string} options.scope        namespace, e.g. "document:handbook"
+ * @param {string} options.text         the document, verbatim
+ * @param {string} options.source       origin (filename, url, title) -- required
+ * @param {object} options.deps         { store, buildState }
+ * @param {object} [options.caller]
+ * @param {string} [options.ts]
+ * @param {number} [options.maxChars]
+ * @param {number} [options.linesPerPage]
+ * @returns {Promise<{ok:true, namespace:string, docDigest:string, chunks:number,
+ *                    written:number, deduped:number, state:string}>}
+ */
+export async function ingestDocumentIntoNamespace({
+  scope,
+  text,
+  source,
+  deps: { store, buildState } = {},
+  caller,
+  ts,
+  maxChars,
+  linesPerPage,
+} = {}) {
+  if (!store) throw new TypeError("a store is required");
+  if (!buildState) {
+    // Refuse rather than ingest without the lifecycle. Writing chunks with no
+    // build state would produce a namespace that is queryable while incomplete --
+    // the precise condition build-state.js exists to make impossible.
+    throw new TypeError("a buildState is required: ingesting without the lifecycle would leave a partial index queryable");
+  }
+
+  const namespace = parseNamespace(scope);
+  const cut = ingestDocument(text, {
+    source,
+    ...(caller?.id ? { author: caller.id } : {}),
+    ...(ts === undefined ? {} : { ts }),
+    ...(maxChars === undefined ? {} : { maxChars }),
+    ...(linesPerPage === undefined ? {} : { linesPerPage }),
+  });
+
+  // STEP 1 -- claim the namespace as BUILDING before a single chunk exists on disk.
+  await buildState.begin(namespace, {
+    docDigest: cut.docDigest,
+    expectedChunks: cut.items.length,
+  });
+
+  // STEP 2 -- write. If this throws, step 3 never runs and the namespace stays
+  // BUILDING, which is the correct outcome: an interrupted ingest must not answer.
+  const result = await store.appendItems(namespace, cut.items);
+
+  // STEP 3 -- complete, with the count. `complete` itself refuses if fewer chunks
+  // landed than were promised, so a short write cannot be stamped ready.
+  //
+  // The count is written + deduped, i.e. chunks PRESENT, not chunks newly added.
+  // Counting only new writes would make re-ingesting an already-complete document
+  // fail to complete (every chunk dedupes, so written === 0), which would strand a
+  // perfectly good namespace in BUILDING -- turning idempotent recovery into a way
+  // to break a working index.
+  const state = await buildState.complete(namespace, {
+    writtenChunks: result.written + result.deduped,
+  });
+
+  return {
+    ok: true,
+    namespace: namespace.raw,
+    docDigest: cut.docDigest,
+    chunks: cut.items.length,
+    written: result.written,
+    deduped: result.deduped,
+    state: state.state,
+  };
+}

package/src/engram/store.js

@@ -21,7 +21,12 @@ import path from "node:path";
 import { buildObservationsFromItems } from "./observations.js";
 import { contentHash, normalizeString } from "../session/recall/text.js";
 
-function namespaceDir(root, namespace) {
+/**
+ * Where a namespace's files live. EXPORTED so siblings (e.g. build-state.js) resolve
+ * the same directory rather than re-deriving the convention -- a second copy of this
+ * sanitization would drift and silently point at a different namespace.
+ */
+export function namespaceDir(root, namespace) {
   const safe = namespace.raw.replace(/[^A-Za-z0-9._-]/g, "_");
   return path.join(root, ".sentinelayer", "engram", safe);
 }

package/src/engram/tools.js

@@ -56,6 +56,7 @@ export function createMemoryTools({
   store,
   consent,
   governance,
+  buildState = null,
   embedder = createEmbedder(),
   renderer = null,
   isAuthorizedForSealed = () => false,
@@ -81,6 +82,11 @@ export function createMemoryTools({
   async function retrieveInternal({ scope, query, k, role, caller }) {
     const namespace = parseNamespace(scope);
     authorize(caller, namespace, "read", { consent }); // fail-closed 403
+    // A half-built index must not answer. Gated HERE, in the shared core, so recall
+    // and summarize cannot diverge -- a second door is how a rule ends up enforced on
+    // one path and not the other. `absent` is allowed: session namespaces are
+    // adapter-backed and never "built", so only an in-flight build is refused.
+    if (buildState) await buildState.assertNotBuilding(namespace);
     const authorizedForSealed = Boolean(isAuthorizedForSealed(caller, namespace));
 
     const all = await store.readObservations(namespace);

package/src/events/schema.js

@@ -125,6 +125,12 @@ export function createAgentEvent({
   cursor,
   sequenceId,
   sequence_id,
+  id,
+  messageRevision,
+  editedAt,
+  editedBy,
+  canEdit,
+  revisionEvidence,
 } = {}) {
   const normalizedEvent = normalizeNonEmptyString(event);
   const normalizedAgent = normalizeAgentShape({
@@ -149,6 +155,12 @@ export function createAgentEvent({
     workItemId: normalizeOptionalString(workItemId),
     requestId: normalizeOptionalString(requestId),
     eventId: normalizeOptionalString(eventId),
+    id: normalizeOptionalString(id),
+    messageRevision: normalizePositiveInteger(messageRevision),
+    editedAt: editedAt === null ? null : normalizeOptionalString(editedAt),
+    editedBy: editedBy === null ? null : isPlainObject(editedBy) ? { ...editedBy } : undefined,
+    canEdit: typeof canEdit === "boolean" ? canEdit : undefined,
+    revisionEvidence: isPlainObject(revisionEvidence) ? { ...revisionEvidence } : undefined,
     idempotencyToken: normalizeOptionalString(idempotencyToken),
     cursor: normalizeOptionalString(cursor),
     sequenceId: normalizePositiveInteger(sequenceId ?? sequence_id),
@@ -220,6 +232,12 @@ export function normalizeAgentEvent(evt, { allowLegacy = true } = {}) {
       workItemId: evt.workItemId,
       requestId: evt.requestId,
       eventId: evt.eventId,
+      id: evt.id,
+      messageRevision: evt.messageRevision,
+      editedAt: evt.editedAt,
+      editedBy: evt.editedBy,
+      canEdit: evt.canEdit,
+      revisionEvidence: evt.revisionEvidence,
       idempotencyToken: evt.idempotencyToken,
       cursor: evt.cursor,
       sequenceId: evt.sequenceId ?? evt.sequence_id,

package/src/legacy-cli.js

@@ -228,8 +228,8 @@ function printUsage() {
   console.log("  sl session action <id> working_on --target-sequence <n>  Claim work on a message");
   console.log("  sl session reply <id> <seq> \"msg\"  Thread a response under a message");
   console.log("  sl session comment <id> <seq> \"msg\"  Alias for threaded reply");
-  console.log("  sl session read <id> --remote --agent <id>  Read stream events and auto-record views");
-  console.log("  sl session view <id> <seq>          Manually backfill a read receipt");
+  console.log("  sl session read <id> --remote --agent <id>  Read events and advance delivery cursor");
+  console.log("  sl session edit <id> <seq|reply-uuid> \"msg\"  Edit your message without losing history");
   console.log("  sl session pins <id> --json         List pinned messages with content (readable by agents)");
   console.log("  sl session lock <id> <files...> --intent <why>  Claim file locks (fail-closed, TTL auto-release)");
   console.log("  sl session unlock <id> <files...>   Release file locks you hold");