sentinelayer-cli 0.39.2 → 0.41.0

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,64 @@
+/**
+ * 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";
+
+import { createStore } from "./store.js";
+import { createLocalConsent } from "./namespace.js";
+import { createGovernance } from "./governance.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 });
+  const tools = createMemoryTools({ store, consent, governance, embedder, renderer, isAuthorizedForSealed });
+  return { tools, store };
+}

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,115 @@
+/**
+ * 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";
+
+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,146 @@
+/**
+ * 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,
+  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
+    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 };
+}