forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/memory/router.js

@@ -0,0 +1,387 @@
+'use strict';
+
+/**
+ * @module memory/router
+ *
+ * Single dispatch seam for `forge remember` / `forge recall`. The DEFAULT is
+ * `local`, which now means the kernel `kernel_memories` table indexed by FTS5
+ * (via `lib/project-memory.js`) — the same knowledge layer decisions and issues
+ * share. The router exists so the opt-in `graphiti` knowledge-graph tier can slot
+ * in behind the same CLI verbs WITHOUT changing the clean default path.
+ *
+ * Public config surface is deliberately `local | graphiti` only. `graphiti` is
+ * EXPERIMENTAL — its config/doctor scaffolding ships but the runtime emitter is a
+ * fast-follow, so today it always writes the local kernel floor and the emit is a
+ * best-effort no-op unless a caller injects an emitter.
+ *
+ * Design: docs/work/2026-07-09-decision-store/design.md §B.1 (memory consolidation
+ * onto the kernel + FTS5). The retired flat JSONL store (`lib/memory-store.js`) is
+ * imported once into kernel_memories on first use, then never written again.
+ *
+ * Hard rule: `remember`/`recall` must NEVER hang or fail. Under `graphiti`, the
+ * emit is FIRE-AND-FORGET with a HARD FALLBACK to the local kernel store on any
+ * error/timeout — a down sidecar can never strand a note. The local kernel write
+ * is the floor and always happens. Strict validation (`assertMemoryConfigValid`)
+ * is a separate, explicit gate for tooling (e.g. `forge doctor`).
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const projectMemory = require('../project-memory');
+
+/** Supported PUBLIC backends, default first. */
+const MEMORY_BACKENDS = ['local', 'graphiti'];
+const DEFAULT_MEMORY_BACKEND = 'local';
+const ENV_VAR = 'FORGE_MEMORY_BACKEND';
+
+/** Default recall cap — newest-N, so `recall` with no query never dumps the whole store. */
+const DEFAULT_RECALL_LIMIT = 20;
+/** sourceAgent stamped on CLI `remember` notes (distinct from insights-written rows). */
+const REMEMBER_SOURCE_AGENT = 'forge remember';
+/** sourceAgent stamped on notes imported once from the retired JSONL store. */
+const IMPORT_SOURCE_AGENT = 'forge remember (imported)';
+/**
+ * The source_agents that are human `remember` notes — the scope of the DEFAULT (no-query)
+ * `recall` view, so machine/insights records never pollute or miscount the plain listing.
+ * A query, or `--all`, still reaches every stored memory.
+ */
+const HUMAN_MEMORY_AGENTS = [REMEMBER_SOURCE_AGENT, IMPORT_SOURCE_AGENT];
+/** The retired flat JSONL store, imported once into kernel_memories, then renamed. */
+const LEGACY_JSONL_RELATIVE = ['.forge', 'memory', 'notes.jsonl'];
+
+/**
+ * Safely read the `memory` block from `<projectRoot>/.forge/config.yaml`.
+ * Never throws — a missing or malformed file resolves to `{}` so the default
+ * (local) path is byte-identical to shipping no config at all.
+ *
+ * @param {string|undefined} projectRoot
+ * @returns {object} The parsed `memory` object, or `{}`.
+ */
+function readMemoryConfig(projectRoot) {
+  if (!projectRoot) return {};
+
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const configPath = path.join(projectRoot, '.forge', 'config.yaml');
+  if (!fs.existsSync(configPath)) return {};
+
+  let parsed;
+  try {
+    // Lazy-require keeps the default no-config path free of the YAML parser.
+    const YAML = require('yaml');
+    parsed = YAML.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return {};
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+  const memory = parsed.memory;
+  if (!memory || typeof memory !== 'object' || Array.isArray(memory)) return {};
+  return memory;
+}
+
+/**
+ * Gather the raw backend signal by precedence (deps > env > config), WITHOUT
+ * validation. Returns `{ value, source }` or `{ value: null, source: null }`.
+ */
+function collectBackendSignal({ deps = {}, env = process.env, projectRoot, config } = {}) {
+  if (typeof deps.memoryBackend === 'string' && deps.memoryBackend.trim()) {
+    return { value: deps.memoryBackend.trim(), source: 'deps' };
+  }
+
+  const envValue = env && env[ENV_VAR];
+  if (typeof envValue === 'string' && envValue.trim()) {
+    return { value: envValue.trim(), source: 'env' };
+  }
+
+  const memory = config || readMemoryConfig(projectRoot);
+  const configValue = memory && memory.backend;
+  if (typeof configValue === 'string' && configValue.trim()) {
+    return { value: configValue.trim(), source: 'config' };
+  }
+
+  return { value: null, source: null };
+}
+
+/**
+ * Resolve the active memory backend by precedence:
+ *   deps.memoryBackend > FORGE_MEMORY_BACKEND env > .forge/config.yaml > 'local'.
+ *
+ * An UNKNOWN value (from any source) warns and falls back to `local` so a typo
+ * — or a legacy `kernel` value — can never break `remember`/`recall`. Use
+ * `assertMemoryConfigValid` when you need a hard error instead.
+ *
+ * @param {object} [options]
+ * @returns {'local'|'graphiti'}
+ */
+function resolveMemoryBackend({
+  deps = {},
+  env = process.env,
+  projectRoot,
+  config,
+  warn = console.warn,
+} = {}) {
+  const { value, source } = collectBackendSignal({ deps, env, projectRoot, config });
+  if (!value) return DEFAULT_MEMORY_BACKEND;
+
+  const normalized = value.toLowerCase();
+  if (MEMORY_BACKENDS.includes(normalized)) return normalized;
+
+  warn(
+    `Unknown memory backend "${value}" from ${source}; `
+    + `falling back to "${DEFAULT_MEMORY_BACKEND}". Valid backends: ${MEMORY_BACKENDS.join(', ')}.`,
+  );
+  return DEFAULT_MEMORY_BACKEND;
+}
+
+/**
+ * Strict validation for the resolved backend. Unlike `resolveMemoryBackend`
+ * (which soft-falls-back), this THROWS a clear, actionable error when the
+ * selection is inconsistent. Used by tooling (e.g. `forge doctor`).
+ *
+ * @param {object} [options]
+ * @returns {{ backend: string, graphiti: object|null }}
+ */
+function assertMemoryConfigValid({ deps = {}, env = process.env, projectRoot, config } = {}) {
+  const memory = config || readMemoryConfig(projectRoot);
+  const backend = resolveMemoryBackend({ deps, env, projectRoot, config: memory, warn: () => {} });
+
+  if (backend !== 'graphiti') {
+    return { backend, graphiti: null };
+  }
+
+  const graphiti = memory && memory.graphiti;
+  const hasServerPath = graphiti
+    && typeof graphiti.mcpServerPath === 'string'
+    && graphiti.mcpServerPath.trim() !== '';
+  if (!hasServerPath) {
+    throw new Error(
+      'memory.backend is "graphiti" but memory.graphiti.mcpServerPath is not set. '
+      + 'Configure the Graphiti MCP server path (the checkout\'s mcp_server directory) '
+      + 'in .forge/config.yaml. See docs/guides/memory-backends.md. '
+      + 'The local store stays the default and the safety floor when unset.',
+    );
+  }
+  return { backend, graphiti };
+}
+
+/**
+ * Best-effort, fire-and-forget emit of an episode to the graph backend. This is
+ * a SEAM: the actual Graphiti MCP client lands in a fast-follow PR. It NEVER
+ * throws and NEVER blocks the caller — any error/timeout is swallowed so the
+ * local floor write is the only thing that can affect `remember`'s result.
+ *
+ * CONTRACT for the fast-follow emitter (MUST hold — safe today only because no
+ * emitter is constructed): the emitter MUST NOT keep the Node event loop alive
+ * or delay CLI exit. Any spawned process/socket/timer it creates MUST be
+ * `child.unref()`'d (or otherwise detached / left with no lingering handle), and
+ * any network/RPC call MUST be bounded by its OWN timeout so a hung sidecar can
+ * never stall `forge remember`. This function does NOT await the emit, so a
+ * lingering handle inside `emit()` would be the ONLY way to break the
+ * never-hang guarantee — the emitter, not this seam, owns preventing that.
+ *
+ * @param {object} [emitter] - optional `{ emit(entry) }` injected by callers.
+ * @param {object} entry - the persisted local entry.
+ */
+function fireAndForgetGraphitiEmit(emitter, entry) {
+  if (!emitter || typeof emitter.emit !== 'function') return;
+  try {
+    // Do not await: fire-and-forget. If it returns a promise, swallow rejection.
+    const maybePromise = emitter.emit(entry);
+    if (maybePromise && typeof maybePromise.then === 'function') {
+      maybePromise.then(() => {}, () => {});
+    }
+  } catch {
+    // Hard fallback: the local write already succeeded. Never surface emit errors.
+  }
+}
+
+/**
+ * Render a non-string memory value (e.g. an insights skill record) as a compact, READABLE
+ * one-liner rather than a raw JSON blob. Flattens the top level: primitive fields become
+ * `key: value`; nested fields fall back to compact JSON.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+function renderStructuredValue(value) {
+  if (value === null || value === undefined) return String(value);
+  if (typeof value !== 'object') return String(value);
+  if (Array.isArray(value)) {
+    return value.map(item => (item !== null && typeof item === 'object' ? JSON.stringify(item) : String(item))).join(', ');
+  }
+  return Object.entries(value)
+    .map(([key, val]) => (val !== null && typeof val === 'object' ? `${key}: ${JSON.stringify(val)}` : `${key}: ${val}`))
+    .join(' · ');
+}
+
+/**
+ * Map a kernel_memories entry to the CLI note shape `remember`/`recall` render. A string
+ * value IS the note text; a structured value (an insights/typed record) is rendered readably
+ * and flagged `machine` with its `sourceAgent` so the CLI can LABEL it rather than mislabel a
+ * raw JSON blob as a plain note.
+ *
+ * @param {object} entry - a kernel_memories entry ({ key, value, sourceAgent, timestamp, tags }).
+ * @returns {{ id: string, note: string, sourceAgent: string, machine: boolean, timestamp: string, tags: string[] }}
+ */
+function toNote(entry) {
+  if (!entry) return null;
+  const isString = typeof entry.value === 'string';
+  return {
+    id: entry.key,
+    note: isString ? entry.value : renderStructuredValue(entry.value),
+    sourceAgent: typeof entry.sourceAgent === 'string' ? entry.sourceAgent : '',
+    machine: !isString,
+    timestamp: typeof entry.timestamp === 'string' ? entry.timestamp : '',
+    tags: Array.isArray(entry.tags) ? entry.tags : [],
+  };
+}
+
+function legacyJsonlPath(projectRoot) {
+  return path.join(projectRoot, ...LEGACY_JSONL_RELATIVE);
+}
+
+// A STABLE key for a legacy record that lacks an `id`, derived from its content — so a
+// re-run (or a failed rename) upserts the same row instead of double-inserting under a
+// fresh random UUID.
+function legacyContentKey(parsed) {
+  const basis = JSON.stringify({
+    note: parsed.note,
+    timestamp: typeof parsed.timestamp === 'string' ? parsed.timestamp : '',
+    tags: Array.isArray(parsed.tags) ? parsed.tags.filter(tag => typeof tag === 'string') : [],
+  });
+  return `import:${crypto.createHash('sha256').update(basis).digest('hex').slice(0, 32)}`;
+}
+
+/**
+ * One-time import of the retired flat JSONL store into kernel_memories. Idempotent (keys
+ * are the original note ids, so a re-run upserts) and best-effort (a malformed record or a
+ * write error can never break `remember`/`recall`). After a pass the file is renamed so the
+ * import runs at most once and JSONL is never read or written again.
+ *
+ * @param {string} projectRoot
+ * @param {object} [options] - forwarded to `projectMemory.write` (e.g. an injected store).
+ */
+function migrateJsonlNotesOnce(projectRoot, options = {}) {
+  if (!projectRoot) return;
+  const storePath = legacyJsonlPath(projectRoot);
+  let raw;
+  try {
+    if (!fs.existsSync(storePath)) return;
+    raw = fs.readFileSync(storePath, 'utf8');
+  } catch {
+    return;
+  }
+
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue; // Skip an unparseable legacy line — one bad record can't block the import.
+    }
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.note !== 'string' || parsed.note.trim() === '') {
+      continue;
+    }
+    const entry = {
+      // A record with a stable id keys off it; one without keys off its content hash, so a
+      // re-import can never double-insert the same note.
+      key: typeof parsed.id === 'string' && parsed.id ? parsed.id : legacyContentKey(parsed),
+      value: parsed.note,
+      sourceAgent: IMPORT_SOURCE_AGENT,
+      tags: Array.isArray(parsed.tags) ? parsed.tags.filter(tag => typeof tag === 'string') : [],
+    };
+    if (typeof parsed.timestamp === 'string' && parsed.timestamp && !Number.isNaN(Date.parse(parsed.timestamp))) {
+      entry.timestamp = parsed.timestamp;
+    }
+    try {
+      projectMemory.write(projectRoot, entry, options);
+    } catch {
+      // Skip an unwritable legacy record; never break remember/recall on import.
+    }
+  }
+
+  try {
+    fs.renameSync(storePath, `${storePath}.migrated`);
+  } catch {
+    // Best-effort: the import is idempotent by key, so a failed rename re-imports safely.
+  }
+}
+
+/**
+ * Append a note through kernel_memories — the local floor for EVERY backend, always written
+ * first so a note is durably captured. `graphiti` additionally fires a best-effort,
+ * non-blocking emit toward the graph backend. Imports any retired JSONL store on first use.
+ *
+ * @param {string} projectRoot
+ * @param {string} note
+ * @param {object} [options] - { tags, deps, env, config, graphitiEmitter, store }
+ * @returns {{ id: string, note: string, timestamp: string, tags: string[] }}
+ */
+function append(projectRoot, note, options = {}) {
+  migrateJsonlNotesOnce(projectRoot, options);
+  const backend = resolveMemoryBackend({ ...options, projectRoot });
+  const written = projectMemory.write(projectRoot, {
+    key: crypto.randomUUID(),
+    value: note,
+    sourceAgent: REMEMBER_SOURCE_AGENT,
+    tags: Array.isArray(options.tags) ? options.tags : [],
+  }, options);
+  const entry = toNote(written);
+  if (backend === 'graphiti') {
+    fireAndForgetGraphitiEmit(options.graphitiEmitter, entry);
+  }
+  return entry;
+}
+
+/**
+ * Read notes back through the FTS-backed kernel layer. WITH a query: BM25 token-AND top-N.
+ * WITHOUT a query: the newest `limit` entries plus the total count (never a bare full dump).
+ * Imports any retired JSONL store on first use.
+ *
+ * A query searches the WHOLE store (human notes + insights/typed records), so anything the
+ * kernel knows is recallable. The default no-query view is scoped to human `remember` notes
+ * so machine/insights records never pollute or miscount the plain listing; `selection.all`
+ * widens it to every stored memory.
+ *
+ * @param {string} projectRoot
+ * @param {object} [selection] - { query, limit, all }
+ * @param {object} [options] - forwarded to the project-memory read paths (e.g. a store).
+ * @returns {{ notes: object[], total: number, capped: boolean, query: string, limit: number, scope: string }}
+ */
+function recall(projectRoot, selection = {}, options = {}) {
+  migrateJsonlNotesOnce(projectRoot, options);
+  const requested = selection.limit;
+  const limit = Number.isInteger(requested) && requested > 0 ? requested : DEFAULT_RECALL_LIMIT;
+  const query = String(selection.query || '').trim();
+  const includeAll = Boolean(selection.all);
+
+  if (query) {
+    const notes = projectMemory.searchRanked(projectRoot, query, limit, options).map(toNote);
+    // BM25 returns at most `limit`; a full result set signals there may be more.
+    return { notes, total: notes.length, capped: notes.length >= limit, query, limit, scope: 'all' };
+  }
+
+  const agents = includeAll ? undefined : HUMAN_MEMORY_AGENTS;
+  const readOptions = { ...options, agents };
+  const notes = projectMemory.recent(projectRoot, limit, readOptions).map(toNote);
+  const total = projectMemory.count(projectRoot, readOptions);
+  return { notes, total, capped: total > notes.length, query: '', limit, scope: includeAll ? 'all' : 'remembered' };
+}
+
+module.exports = {
+  MEMORY_BACKENDS,
+  DEFAULT_MEMORY_BACKEND,
+  DEFAULT_RECALL_LIMIT,
+  ENV_VAR,
+  readMemoryConfig,
+  resolveMemoryBackend,
+  assertMemoryConfigValid,
+  migrateJsonlNotesOnce,
+  toNote,
+  append,
+  recall,
+};

package/lib/memory/typed-api.js

@@ -0,0 +1,102 @@
+const projectMemory = require('../project-memory');
+
+const CATEGORIES = new Set([
+  'decisions',
+  'episodes',
+  'skills',
+  'state',
+  'issues',
+  'audit',
+  'preferences',
+]);
+
+function assertCategory(category) {
+  if (!CATEGORIES.has(category)) {
+    throw new Error(`Unknown memory category: ${category}`);
+  }
+}
+
+function assertProvenance(provenance) {
+  if (!provenance || typeof provenance !== 'object') {
+    throw new TypeError('typed memory provenance is required');
+  }
+  for (const field of ['actor', 'reason', 'source']) {
+    if (typeof provenance[field] !== 'string' || provenance[field].trim() === '') {
+      throw new TypeError(`typed memory provenance.${field} is required`);
+    }
+  }
+}
+
+function keyFor(category, key) {
+  if (typeof key !== 'string' || key.trim() === '') {
+    throw new TypeError('typed memory key is required');
+  }
+  return `${category}:${key.trim()}`;
+}
+
+function adapter(options = {}) {
+  return options.memory ?? projectMemory;
+}
+
+function stringArrayOption(value, fieldName) {
+  if (value === undefined) return undefined;
+  const values = Array.isArray(value) ? value : [value];
+  if (values.some(item => typeof item !== 'string')) {
+    throw new TypeError(`typed memory ${fieldName} must contain only strings`);
+  }
+  return values.map(item => item.trim()).filter(Boolean);
+}
+
+function writeTyped(projectRoot, category, key, data, options = {}) {
+  assertCategory(category);
+  assertProvenance(options.provenance);
+
+  const provenance = {
+    actor: options.provenance.actor.trim(),
+    reason: options.provenance.reason.trim(),
+    source: options.provenance.source.trim(),
+  };
+
+  return adapter(options).write(projectRoot, {
+    key: keyFor(category, key),
+    value: {
+      category,
+      data,
+      provenance,
+    },
+    sourceAgent: provenance.actor,
+    tags: [category, ...(stringArrayOption(options.tags, 'tags') ?? [])],
+    beadsRefs: stringArrayOption(options.beadsRefs, 'beadsRefs'),
+  }, options);
+}
+
+function readTyped(projectRoot, category, key, options = {}) {
+  assertCategory(category);
+  return adapter(options).read(projectRoot, keyFor(category, key), options);
+}
+
+function searchTyped(projectRoot, category, query, options = {}) {
+  assertCategory(category);
+  const prefix = `${category}:`;
+  const results = adapter(options).search(projectRoot, `${category} ${query ?? ''}`.trim(), options) ?? [];
+  if (!Array.isArray(results)) return [];
+  return results.filter(entry => typeof entry?.key === 'string' && entry.key.startsWith(prefix));
+}
+
+function categoryWriter(category) {
+  return (projectRoot, key, data, options = {}) => writeTyped(projectRoot, category, key, data, options);
+}
+
+module.exports = {
+  CATEGORIES: [...CATEGORIES],
+  writeTyped,
+  readTyped,
+  searchTyped,
+  writeDecision: categoryWriter('decisions'),
+  writeEpisode: categoryWriter('episodes'),
+  writeSkill: categoryWriter('skills'),
+  writeState: categoryWriter('state'),
+  writeIssue: categoryWriter('issues'),
+  writeAudit: categoryWriter('audit'),
+  writePreference: categoryWriter('preferences'),
+};

package/lib/memory-digest.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * @module memory-digest
+ *
+ * Builds the BOUNDED, token-capped memory digest that Forge PUSHES to an agent at
+ * session start (the `memory-inject` context intent in the hook contract). This is
+ * the missing "push" half of Forge memory: today an agent only sees remembered
+ * notes if it TYPES `forge recall`, so memory is effectively orphaned.
+ *
+ * Two layers, kept separate for testability:
+ *   - collectDigestData(projectRoot, opts) — BEST-EFFORT fetch (each source wrapped;
+ *     a failure yields [] for that source). Fetchers are injectable so tests never
+ *     touch a real DB. Async (issue reads are async).
+ *   - buildMemoryDigest(data, { budgetTokens }) — PURE formatting + token-capping via
+ *     orientation's applyBudget. Empty data → empty digest (the caller then injects
+ *     nothing). Never exceeds the budget.
+ *
+ * The digest is a small NUDGE, not a manual: the default budget is deliberately tiny.
+ */
+
+const { applyBudget, buildSection, estimateTokens } = require('./orientation');
+const { fenceUntrusted } = require('./untrusted-content');
+const { collectInbox, inboxSection } = require('./inbox');
+
+const DEFAULT_DIGEST_BUDGET_TOKENS = 400;
+const DEFAULT_NOTE_LIMIT = 5;
+const DEFAULT_ISSUE_LIMIT = 5;
+const DIGEST_HEADER = 'Forge memory (auto-injected at session start):';
+
+/** Run an async producer, returning `fallback` on any throw/rejection (never propagates). */
+async function safe(producer, fallback) {
+  try {
+    const value = await producer();
+    return value === undefined || value === null ? fallback : value;
+  } catch {
+    return fallback;
+  }
+}
+
+/** Default note fetch: newest remembered notes via the kernel-backed memory router. */
+function defaultFetchNotes(projectRoot, opts = {}) {
+  const memoryRouter = require('./memory/router');
+  const result = memoryRouter.recall(projectRoot, { limit: opts.noteLimit || DEFAULT_NOTE_LIMIT });
+  return Array.isArray(result && result.notes) ? result.notes : [];
+}
+
+/** Pull an issues array out of a runIssueOperation result, defensively (shape varies). */
+function extractIssues(result) {
+  let payload = result && result.data;
+  if (!payload && result && typeof result.output === 'string') {
+    try { payload = JSON.parse(result.output); } catch { return []; }
+  }
+  if (Array.isArray(payload)) return payload;
+  if (payload && Array.isArray(payload.issues)) return payload.issues;
+  return [];
+}
+
+/**
+ * Default issue fetch for a status kind ('ready' | 'in_progress'). Best-effort.
+ * The CLI `--limit` is NOT trusted (`forge issue ready --json --limit 2` empirically
+ * returns the whole set), so the result is HARD-CAPPED with `.slice(0, limit)` — else
+ * the digest dumps every ready issue and applyBudget truncates the claimed tail away.
+ * `opts.runIssueOperation` is injectable so tests exercise the cap deterministically.
+ */
+async function defaultFetchIssues(projectRoot, kind, opts = {}) {
+  const runIssueOperation = opts.runIssueOperation || require('./forge-issues').runIssueOperation;
+  const limit = opts.issueLimit || DEFAULT_ISSUE_LIMIT;
+  const [operation, args] = kind === 'ready'
+    ? ['ready', ['--json', '--limit', String(limit)]]
+    : ['list', ['--status', 'in_progress', '--json', '--limit', String(limit)]];
+  const result = await runIssueOperation(operation, args, projectRoot);
+  return extractIssues(result).slice(0, limit);
+}
+
+/** Default inbox fetch: pending targeted dashboard instruction comments (fail-open). */
+function defaultFetchInbox(projectRoot, opts = {}) {
+  return collectInbox(projectRoot, opts);
+}
+
+/**
+ * Best-effort gather of the digest inputs. Each source degrades to [] independently.
+ * @param {string} projectRoot
+ * @param {object} [opts] - { fetchNotes, fetchIssues, fetchInbox, noteLimit, issueLimit }
+ * @returns {Promise<{ notes: object[], ready: object[], claimed: object[], inbox: object[] }>}
+ */
+async function collectDigestData(projectRoot, opts = {}) {
+  const fetchNotes = opts.fetchNotes || defaultFetchNotes;
+  const fetchIssues = opts.fetchIssues || defaultFetchIssues;
+  const fetchInbox = opts.fetchInbox || defaultFetchInbox;
+  const notes = await safe(() => fetchNotes(projectRoot, opts), []);
+  const ready = await safe(() => fetchIssues(projectRoot, 'ready', opts), []);
+  const claimed = await safe(() => fetchIssues(projectRoot, 'in_progress', opts), []);
+  const inbox = await safe(() => fetchInbox(projectRoot, opts), []);
+  return {
+    notes: Array.isArray(notes) ? notes : [],
+    ready: Array.isArray(ready) ? ready : [],
+    claimed: Array.isArray(claimed) ? claimed : [],
+    inbox: Array.isArray(inbox) ? inbox : [],
+  };
+}
+
+/** `- [date ]note` for a recall note. */
+function formatNoteLine(note) {
+  const date = typeof note.timestamp === 'string' && note.timestamp ? `${note.timestamp.slice(0, 10)} ` : '';
+  return `- ${date}${note.note}`;
+}
+
+/** `- [label] title` for an issue row (title/id defensively resolved). */
+function formatIssueLine(label, issue) {
+  const title = (issue && (issue.title || issue.id)) || 'untitled';
+  return `- [${label}] ${title}`;
+}
+
+/** Build the notes section, or null when there are no notes. */
+function notesSection(notes) {
+  if (!notes.length) return null;
+  return buildSection({
+    id: 'digest_notes',
+    title: 'Remembered notes',
+    content: notes.map(formatNoteLine).join('\n'),
+    priority: 10,
+    preserve: false,
+    // Untrusted: a planted note is DATA, not instructions. Fenced after truncation.
+    untrustedSource: 'memory',
+  });
+}
+
+/**
+ * Build the open-issues section, or null when both are empty. CLAIMED lines come FIRST
+ * so that when applyBudget truncates the tail, it is the (less critical) ready list that
+ * is cut — the agent's own in-progress work must never be the vanished tail.
+ */
+function issuesSection(ready, claimed) {
+  const lines = [
+    ...claimed.map(issue => formatIssueLine('claimed', issue)),
+    ...ready.map(issue => formatIssueLine('ready', issue)),
+  ];
+  if (!lines.length) return null;
+  return buildSection({
+    id: 'digest_issues',
+    title: 'Open issues',
+    content: lines.join('\n'),
+    priority: 20,
+    preserve: false,
+    // Untrusted: an issue title is attacker-influenceable. Fenced after truncation.
+    untrustedSource: 'issue-titles',
+  });
+}
+
+/**
+ * Assemble the bounded digest text. PURE. Never exceeds `budgetTokens` (delegated to
+ * applyBudget). Empty inputs → { text: '', empty: true } so the caller injects nothing.
+ *
+ * @param {{ notes?: object[], ready?: object[], claimed?: object[] }} [data]
+ * @param {object} [options] - { budgetTokens }
+ * @returns {{ text: string, empty: boolean, tokens: number }}
+ */
+function buildMemoryDigest(data = {}, options = {}) {
+  const notes = Array.isArray(data.notes) ? data.notes : [];
+  const ready = Array.isArray(data.ready) ? data.ready : [];
+  const claimed = Array.isArray(data.claimed) ? data.claimed : [];
+  const inbox = Array.isArray(data.inbox) ? data.inbox : [];
+
+  // Inbox (priority 5) is a THIRD section beside notes + issues; a fresh human directive
+  // outranks stale notes (10) and the agent's own issue list (20) under budget pressure.
+  const sections = [inboxSection(inbox), notesSection(notes), issuesSection(ready, claimed)].filter(Boolean);
+  if (!sections.length) return { text: '', empty: true, tokens: 0 };
+
+  const budgetTokens = options.budgetTokens || DEFAULT_DIGEST_BUDGET_TOKENS;
+  const budgeted = applyBudget(sections, budgetTokens);
+  const body = budgeted.sections
+    .filter(section => section.content)
+    // Fence AFTER applyBudget truncates, so the ⟦END UNTRUSTED⟧ close marker always
+    // survives (fencing before truncation would let the budget cut the terminator and
+    // leave an unclosed fence a payload could exploit). Provenance-labelled per section.
+    .map(section => `${section.title}:\n${fenceUntrusted(section.content, { source: section.untrustedSource })}`)
+    .join('\n\n');
+  if (!body) return { text: '', empty: true, tokens: 0 };
+
+  const text = `${DIGEST_HEADER}\n\n${body}`;
+  return { text, empty: false, tokens: estimateTokens(text) };
+}
+
+module.exports = {
+  DEFAULT_DIGEST_BUDGET_TOKENS,
+  DIGEST_HEADER,
+  buildMemoryDigest,
+  collectDigestData,
+  extractIssues,
+  // exported for focused reuse / tests
+  defaultFetchNotes,
+  defaultFetchIssues,
+  defaultFetchInbox,
+};