sentinelayer-cli 0.40.0 → 0.42.0

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/namespace.js

@@ -0,0 +1,89 @@
+/**
+ * ENGRAM §2 — namespaces (the tenancy boundary) + fail-closed authorization.
+ *
+ * A `scope` selects a NAMESPACE, formatted `<kind>:<id>` (e.g. `session:abc`,
+ * `project:web`, `org:acme`, `agent:codex`, or generic `ns:notes`). The kind
+ * prefix routes the store to a backend (session kind -> the SL session
+ * adapter; everything else -> the generic append-log). The engine itself
+ * knows NOTHING about kinds — that lives in the store adapter map — which is
+ * what makes the whole thing detachable/sellable.
+ *
+ * Authorization is FAIL-CLOSED: an action is denied unless the injected
+ * consent explicitly allows the caller's required scope. P0 ships a
+ * permissive-LOCAL consent (the local principal is trusted; guests/unknown
+ * are denied) behind the same seam the hosted AIdenID/UserAgentGrant path
+ * (§2.1) will implement.
+ */
+
+export class AccessDeniedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AccessDeniedError";
+    this.status = 403;
+    this.code = "access_denied";
+  }
+}
+
+/** Action -> required OAuth-style scope (aligns with the hosted scope set). */
+export const ACTION_SCOPES = Object.freeze({
+  write: "memory:write",
+  read: "memory:read",
+  summarize: "memory:read",
+});
+
+const NAMESPACE_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const NAMESPACE_KIND_RE = /^[a-z][a-z0-9_-]{0,31}$/;
+
+/**
+ * Parse + validate a namespace scope.
+ * @param {string} scope
+ * @returns {{kind: string, id: string, raw: string}}
+ */
+export function parseNamespace(scope) {
+  const raw = String(scope ?? "").trim();
+  if (!raw) throw new Error("namespace scope is required.");
+  const colon = raw.indexOf(":");
+  const kind = colon > 0 ? raw.slice(0, colon) : "ns";
+  const id = colon > 0 ? raw.slice(colon + 1) : raw;
+  if (!NAMESPACE_KIND_RE.test(kind)) throw new Error(`invalid namespace kind '${kind}'.`);
+  if (!NAMESPACE_ID_RE.test(id)) throw new Error("invalid namespace id.");
+  if (id.includes("..") || id.includes("/") || id.includes("\\")) {
+    throw new Error("namespace id must not contain path-traversal segments.");
+  }
+  return { kind, id, raw: `${kind}:${id}` };
+}
+
+/**
+ * Create a LOCAL consent policy (P0). Fail-closed by construction: a caller
+ * with no identity, or a guest (unless explicitly allowed), is denied.
+ * @param {object} [options]
+ * @param {boolean} [options.allowGuests=false]
+ * @returns {{allows: (caller:object, namespace:object, scope:string)=>boolean}}
+ */
+export function createLocalConsent({ allowGuests = false } = {}) {
+  return {
+    allows(caller, _namespace, _scope) {
+      if (!caller || !caller.id) return false; // no identity -> deny
+      if (caller.kind === "guest" && !allowGuests) return false; // guests denied by default
+      return true;
+    },
+  };
+}
+
+/**
+ * Fail-closed authorization. Throws AccessDeniedError (403) unless the
+ * consent explicitly allows the caller's required scope on the namespace.
+ * @returns {{ok: true, scope: string}}
+ */
+export function authorize(caller, namespace, action, { consent } = {}) {
+  const scope = ACTION_SCOPES[action];
+  if (!scope) throw new Error(`unknown action '${action}'.`);
+  const allowed =
+    consent && typeof consent.allows === "function" ? Boolean(consent.allows(caller, namespace, scope)) : false;
+  if (!allowed) {
+    throw new AccessDeniedError(
+      `caller '${caller?.id || "anonymous"}' lacks '${scope}' on namespace '${namespace?.raw || namespace}'.`,
+    );
+  }
+  return { ok: true, scope };
+}

package/src/engram/observations.js

@@ -0,0 +1,34 @@
+/** Generic Memory-as-a-Service item adapter for the pure observation core. */
+
+import { buildEventObservations } from "../session/recall/observation-core.js";
+import { normalizeString } from "../session/recall/text.js";
+
+export function buildObservationsFromItems(items = [], { namespace = "" } = {}) {
+  const events = (Array.isArray(items) ? items : []).map((item) => ({
+    stream: "sl_event",
+    event: normalizeString(item?.kind) || "memory",
+    eventId: normalizeString(item?.id) || undefined,
+    idempotencyToken: normalizeString(item?.idempotencyToken) || undefined,
+    agent: { id: normalizeString(item?.author || item?.agentId) || "writer" },
+    payload: {
+      message: normalizeString(item?.text),
+      topics: item?.topics,
+      files: item?.files,
+      to: item?.mentions,
+      __trust: item?.trust,
+      __sealed: item?.sealed === true,
+      __revoked: item?.revoked === true,
+    },
+    ts: normalizeString(item?.ts) || new Date().toISOString(),
+    sequenceId: item?.sequenceId,
+  }));
+
+  const built = buildEventObservations(events, { sessionId: namespace });
+  for (const observation of built.observations) {
+    const payload = observation?.raw?.payload || {};
+    if (payload.__trust) observation.trust = payload.__trust;
+    observation.sealed = payload.__sealed === true;
+    observation.revoked = payload.__revoked === true;
+  }
+  return built;
+}

package/src/engram/sla.js

@@ -0,0 +1,104 @@
+/**
+ * ENGRAM §2 — the Memory-as-a-Service quality SLA (namespace-agnostic).
+ *
+ * The §1 8-Needle harness (ENGRAM §11) becomes the MaaS SLA, run OVER A NAMESPACE
+ * through the shared store: corpora are `memory.write`-shaped items written to
+ * a namespace, then recalled through the same store the tools use. This proves
+ * the SLA holds for ANY namespace (not just sessions), which is the
+ * detachability guarantee.
+ *
+ * Reuses the §1 corpus builders + evaluators verbatim (no reimplementation).
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+
+import {
+  buildChainCorpus,
+  buildScatterCorpus,
+  evaluateChain,
+  evaluateScatter,
+  evaluateRecallAt10,
+} from "../session/recall/needle-eval.js";
+import { buildRecallIndex } from "../session/recall/index-core.js";
+import { createEmbedder } from "../session/recall/embedder.js";
+import { createStore } from "./store.js";
+import { parseNamespace } from "./namespace.js";
+
+function eventToItem(event) {
+  return {
+    id: event.eventId,
+    text: event?.payload?.message || "",
+    kind: event.event,
+    author: event?.agent?.id,
+    ts: event.ts,
+    topics: event?.payload?.topics,
+    sequenceId: event.sequenceId,
+  };
+}
+
+function latestTsMs(events) {
+  let max = 0;
+  for (const e of events) {
+    const ms = Date.parse(e.ts);
+    if (Number.isFinite(ms) && ms > max) max = ms;
+  }
+  return max;
+}
+
+/**
+ * Run the 8-Needle SLA over the namespace store.
+ * @param {object} [options]
+ * @returns {Promise<object>} metrics + pass/fail per gate
+ */
+export async function runEngramSla({
+  chains = 120,
+  chainLen = 8,
+  scatterQueries = 50,
+  relevants = 8,
+  seed = 1,
+  embedder = createEmbedder(),
+  storeRoot = null,
+  gates = { chain: 0.95, scatter: 0.95, recallAt10: 0.95 },
+} = {}) {
+  const root = storeRoot || (await mkdtemp(path.join(os.tmpdir(), "engram-sla-")));
+  const cleanup = !storeRoot;
+  try {
+    const store = createStore({ storeRoot: root, adapters: {} });
+    const chain = buildChainCorpus({ chains, chainLen, seed });
+    const scatter = buildScatterCorpus({ queries: scatterQueries, relevants, seed: seed + 100 });
+
+    const chainNs = parseNamespace("ns:sla-chain");
+    const scatterNs = parseNamespace("ns:sla-scatter");
+    await store.appendItems(chainNs, chain.events.map(eventToItem));
+    await store.appendItems(scatterNs, scatter.events.map(eventToItem));
+
+    const chainObs = await store.readObservations(chainNs);
+    const scatterObs = await store.readObservations(scatterNs);
+    const chainIndex = buildRecallIndex({ observations: chainObs, embedder, sessionId: chainNs.raw });
+    const scatterIndex = buildRecallIndex({ observations: scatterObs, embedder, sessionId: scatterNs.raw });
+
+    // Deterministic ACT-R clock, strictly after every corpus timestamp.
+    const nowMs = Math.max(latestTsMs(chain.events), latestTsMs(scatter.events)) + 10 * 60_000;
+
+    const chainResult = evaluateChain(chainIndex, chain.chainQueries, { k: 20, now: nowMs });
+    const scatterResult = evaluateScatter(scatterIndex, scatter.scatterQueries, { now: nowMs });
+    const recallAt10Result = evaluateRecallAt10(scatterIndex, scatter.scatterQueries, { now: nowMs });
+
+    const pass =
+      chainResult.rate >= gates.chain &&
+      scatterResult.rate >= gates.scatter &&
+      recallAt10Result.rate >= gates.recallAt10;
+
+    return {
+      config: { chains, chainLen, scatterQueries, relevants, seed, embedder: embedder.name, path: "namespace-store" },
+      needleChain: { rate: chainResult.rate, completed: chainResult.completed, total: chainResult.total, gate: gates.chain, pass: chainResult.rate >= gates.chain },
+      needleScatter: { rate: scatterResult.rate, total: scatterResult.total, gate: gates.scatter, pass: scatterResult.rate >= gates.scatter },
+      recallAt10: { rate: recallAt10Result.rate, total: recallAt10Result.total, gate: gates.recallAt10, pass: recallAt10Result.rate >= gates.recallAt10 },
+      pass,
+    };
+  } finally {
+    if (cleanup) await rm(root, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/engram/store.js

@@ -0,0 +1,120 @@
+/**
+ * ENGRAM §2 — the ONE shared namespace store.
+ *
+ * This is the single substrate the 3 tools, the 8-Needle SLA, and the
+ * token-cut measurement all read (relay ruling #5: no second store). A
+ * namespace's observations are the UNION of:
+ *   - a read-only SOURCE ADAPTER for its kind, if one is registered
+ *     (e.g. kind `session` -> the SL session adapter that maps session
+ *     events to observations). Adapters are INJECTED, so this module imports
+ *     NO session runtime and stays detachable.
+ *   - a generic append-log the tools write to (`memory.write`), one NDJSON
+ *     file per namespace, with content-hash dedup (ENGRAM §3 — idempotent).
+ *
+ * Detachability: imports ONLY the §1 engine core (observations + text) and
+ * node builtins. No SentinelLayer session/mcp/auth imports.
+ */
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { buildObservationsFromItems } from "./observations.js";
+import { contentHash, normalizeString } from "../session/recall/text.js";
+
+/**
+ * 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);
+}
+
+/** Stable, content-addressed item id (idempotent write — §3 dedup for free). */
+export function itemId(item = {}) {
+  const explicit = normalizeString(item.id) || normalizeString(item.idempotencyToken);
+  if (explicit) return explicit;
+  const basis = [item.kind, item.author || item.agentId, item.text, item.ts]
+    .map((value) => normalizeString(value))
+    .join("|");
+  return `h:${contentHash(basis)}`;
+}
+
+async function readItemsFile(file) {
+  try {
+    const raw = await fsp.readFile(file, "utf-8");
+    const items = [];
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        items.push(JSON.parse(line));
+      } catch {
+        // ignore malformed lines
+      }
+    }
+    return items;
+  } catch (error) {
+    if (error && error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+/**
+ * Create the namespace store.
+ * @param {object} options
+ * @param {string} options.storeRoot          Root dir for the append-log store.
+ * @param {Record<string, (id:string)=>Promise<object[]>>} [options.adapters]
+ *        Map of namespace-kind -> async source adapter returning observations.
+ * @returns {{
+ *   appendItems: (namespace:object, items:object[]) => Promise<{written:number, deduped:number, namespace:string}>,
+ *   readObservations: (namespace:object) => Promise<object[]>,
+ * }}
+ */
+export function createStore({ storeRoot, adapters = {} } = {}) {
+  const root = path.resolve(String(storeRoot || "."));
+
+  return {
+    async appendItems(namespace, items = []) {
+      const dir = namespaceDir(root, namespace);
+      const file = path.join(dir, "items.ndjson");
+      const existing = await readItemsFile(file);
+      const seen = new Set(existing.map((it) => itemId(it)));
+      const lines = [];
+      let written = 0;
+      let deduped = 0;
+      for (const item of Array.isArray(items) ? items : []) {
+        const id = itemId(item);
+        if (seen.has(id)) {
+          deduped += 1;
+          continue;
+        }
+        seen.add(id);
+        lines.push(JSON.stringify({ ...item, id }));
+        written += 1;
+      }
+      if (lines.length > 0) {
+        await fsp.mkdir(dir, { recursive: true });
+        await fsp.appendFile(file, `${lines.join("\n")}\n`, "utf-8");
+      }
+      return { written, deduped, namespace: namespace.raw };
+    },
+
+    async readObservations(namespace) {
+      const adapter = adapters[namespace.kind];
+      const adapterObservations = adapter
+        ? await Promise.resolve(adapter(namespace.id)).catch(() => [])
+        : [];
+      const file = path.join(namespaceDir(root, namespace), "items.ndjson");
+      const items = await readItemsFile(file);
+      const itemObservations = buildObservationsFromItems(items, { namespace: namespace.raw }).observations;
+
+      // Union, dedup by id (first wins — adapter source is authoritative for its ids).
+      const byId = new Map();
+      for (const obs of [...(Array.isArray(adapterObservations) ? adapterObservations : []), ...itemObservations]) {
+        if (obs && !byId.has(obs.id)) byId.set(obs.id, obs);
+      }
+      return Array.from(byId.values());
+    },
+  };
+}

package/src/engram/tools.js

@@ -0,0 +1,152 @@
+/**
+ * ENGRAM §2 — Memory-as-a-Service: the 3 MCP tools, EXACTLY.
+ *
+ *   memory.write({ scope, items })      — idempotent (content-hash dedup),
+ *                                         trust-sealed, late-binding.
+ *   memory.recall({ scope, query, k })  — REUSES the §1 engine verbatim
+ *                                         (dense int8 exact-scan + BM25 + RRF
+ *                                         + bounded diffusion + ACT-R) ->
+ *                                         ranked memories + provenance path.
+ *   memory.summarize({ scope, focus })  — retrieve-then-generate: recall
+ *                                         DETERMINISTICALLY selects the subset;
+ *                                         the injected renderer (Gemma) only
+ *                                         GENERATES prose. Never a model in
+ *                                         selection.
+ *
+ * This layer is a namespace + governance wrapper. It imports ONLY the §1
+ * engine core + the sibling engram seams — no session/mcp/auth runtime — so
+ * the product is detachable/sellable on its own.
+ */
+
+import { buildRecallIndex } from "../session/recall/index-core.js";
+import { recall as recallEngine } from "../session/recall/retrieve.js";
+import { createEmbedder } from "../session/recall/embedder.js";
+import { normalizeString } from "../session/recall/text.js";
+
+import { parseNamespace, authorize } from "./namespace.js";
+import { sealItem, visibleUnderScope, isAuthoritative, classifyObservation } from "./trust.js";
+
+function normalizeItem(raw) {
+  if (typeof raw === "string") return { text: raw };
+  if (!raw || typeof raw !== "object") return { text: "" };
+  return { ...raw, text: normalizeString(raw.text || raw.message || raw.content) };
+}
+
+/** Deterministic, non-model summary used when no renderer is injected. */
+function deterministicDigest(focus, memories) {
+  const lines = memories.map((m, i) => {
+    const seq = m.sequenceId ? `#${m.sequenceId} ` : "";
+    return `${i + 1}. ${seq}${m.snippet || ""} [why: ${m.provenance}]`;
+  });
+  return [`Focus: ${focus}`, `Grounded in ${memories.length} recalled memories:`, ...lines].join("\n");
+}
+
+/**
+ * Build the 3 MaaS tools over an injected store + governance + consent.
+ * @param {object} deps
+ * @param {object} deps.store         createStore(...)
+ * @param {object} deps.consent       { allows(caller, namespace, scope) }
+ * @param {object} deps.governance    createGovernance(...)
+ * @param {object} [deps.embedder]
+ * @param {{render: (ctx:object)=>Promise<string>|string}} [deps.renderer]  Gemma prose generator.
+ * @param {(caller:object, namespace:object)=>boolean} [deps.isAuthorizedForSealed]
+ * @param {()=>number} [deps.now]
+ */
+export function createMemoryTools({
+  store,
+  consent,
+  governance,
+  buildState = null,
+  embedder = createEmbedder(),
+  renderer = null,
+  isAuthorizedForSealed = () => false,
+  now = () => Date.now(),
+} = {}) {
+  async function write({ scope, items = [], caller } = {}) {
+    const namespace = parseNamespace(scope);
+    authorize(caller, namespace, "write", { consent }); // fail-closed 403
+    const sealed = (Array.isArray(items) ? items : []).map((it) => {
+      const item = normalizeItem(it);
+      if (!item.author && !item.agentId) item.author = caller?.id;
+      return sealItem(item, { caller });
+    });
+    const result = await store.appendItems(namespace, sealed);
+    const meter = await governance.meter({ namespace: namespace.raw, caller, action: "write", count: result.written });
+    return { ok: true, namespace: namespace.raw, written: result.written, deduped: result.deduped, meter };
+  }
+
+  // Shared retrieval core: authorize (fail-closed) + read + trust-filter +
+  // §1 engine recall + receipt. Metered by the CALLER tool exactly once, so
+  // summarize (which retrieves internally) is billed as one summarize, not
+  // recall+summarize.
+  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);
+    const visible = [];
+    for (const obs of all) {
+      if (!obs.trust) obs.trust = classifyObservation(obs);
+      if (visibleUnderScope(obs, { authorized: authorizedForSealed })) visible.push(obs);
+    }
+
+    const index = buildRecallIndex({ observations: visible, embedder, sessionId: namespace.raw });
+    const engineResult = recallEngine(index, { query: normalizeString(query), k, role, now: now() });
+    const results = engineResult.results.map((r) => {
+      const obs = index.byId.get(r.observationId);
+      const trust = obs?.trust || null;
+      return { ...r, trust, authoritative: isAuthoritative(trust) };
+    });
+    const receipt = await governance.emitRecallReceipt({
+      caller,
+      scope: namespace.raw,
+      namespace: namespace.raw,
+      query: normalizeString(query),
+      resultCount: results.length,
+    });
+    return { namespace, engineResult, results, receipt };
+  }
+
+  async function recall({ scope, query, k = 12, role = "", caller } = {}) {
+    const { namespace, engineResult, results, receipt } = await retrieveInternal({ scope, query, k, role, caller });
+    const meter = await governance.meter({ namespace: namespace.raw, caller, action: "recall", count: results.length });
+    return {
+      ok: true,
+      namespace: namespace.raw,
+      query: engineResult.query,
+      k: engineResult.k,
+      poolSize: engineResult.poolSize,
+      results,
+      receipt,
+      meter,
+    };
+  }
+
+  async function summarize({ scope, focus, k = 12, caller } = {}) {
+    // Deterministic SELECT via the shared retrieval; renderer only GENERATES.
+    const { namespace, results, receipt } = await retrieveInternal({ scope, query: focus, k, role: "", caller });
+    const summary =
+      renderer && typeof renderer.render === "function"
+        ? await renderer.render({ focus, memories: results })
+        : deterministicDigest(normalizeString(focus), results);
+    const meter = await governance.meter({ namespace: namespace.raw, caller, action: "summarize", count: results.length });
+    return {
+      ok: true,
+      namespace: namespace.raw,
+      focus: normalizeString(focus),
+      summary,
+      generated: Boolean(renderer && typeof renderer.render === "function"),
+      groundedIn: results.map((s) => ({ observationId: s.observationId, provenance: s.provenance })),
+      receipt,
+      meter,
+    };
+  }
+
+  return { write, recall, summarize };
+}