@etiquekit/etq 1.0.11 → 1.0.13

package/packages/control/src/ledger/indexer.ts

@@ -0,0 +1,542 @@
+import { Database } from 'bun:sqlite';
+import { existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import {
+  LEDGER_STATUS_EFFECTS,
+  assertLedgerTopicHints,
+  type LedgerAuthorityClass,
+  type LedgerEntryRefs,
+  type LedgerEntryType,
+  type LedgerExportClass,
+  type LedgerStatusEffect,
+} from './entry';
+
+const DOCUMENT_SCAN_DIRS = [
+  'docs/work/ledger',
+  'docs/work/receipts',
+  'docs/work/topic-snapshots',
+  'docs/work/ledger-digests',
+  'docs/work/consumer-registry',
+  'docs/work/bus-feed',
+];
+
+const TEXT_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.json', '.jsonl', '.ndjson', '.txt']);
+
+export interface ParsedLedgerLine {
+  entry_id: string;
+  schema: 'ledger-entry.v0' | 'ledger-entry.v0.1' | 'ledger-entry.v0.2';
+  created_at: string;
+  entry_type: LedgerEntryType | string;
+  spine_eligible: boolean;
+  authority_class: LedgerAuthorityClass | string;
+  grants_execution: boolean;
+  export_class: LedgerExportClass | string;
+  refs: LedgerEntryRefs;
+  topic_hints: string[];
+  status_effect: LedgerStatusEffect;
+  source_path: string;
+  line_no: number;
+  extra: Record<string, string>;
+}
+
+export interface LedgerIndexResult {
+  dbPath: string;
+  ledger_entries: number;
+  refs: number;
+  topics: number;
+  documents: number;
+}
+
+export interface CompactLedgerSearchResult {
+  entry_id: string;
+  title: string;
+  type: string;
+  topic_hints: string[];
+  status_effect: LedgerStatusEffect;
+  refs: string[];
+  confidence: 'metadata';
+  is_canonical: false;
+  regenerable: true;
+  can_authorize: false;
+}
+
+interface LedgerEntryRow {
+  entry_id: string;
+  entry_type: string;
+  topic_hints_json: string;
+  status_effect: LedgerStatusEffect;
+  refs_json: string;
+  source_path?: string;
+  line_no?: number;
+}
+
+export interface LedgerIndexEntryDetail extends CompactLedgerSearchResult {
+  source_path: string;
+  line_no: number;
+}
+
+export function defaultLedgerIndexDbPath(projectRoot: string): string {
+  return join(projectRoot, '.etiquette', 'state', 'ledger', 'index.db');
+}
+
+export function defaultPrivateVerbatimDbPath(projectRoot: string): string {
+  return join(projectRoot, '.etiquette', 'state', 'ledger', 'private-verbatim.db');
+}
+
+export async function ledgerIndexNeedsRebuild(options: {
+  projectRoot: string;
+  dbPath?: string;
+}): Promise<boolean> {
+  const projectRoot = resolve(options.projectRoot);
+  const dbPath = options.dbPath ?? defaultLedgerIndexDbPath(projectRoot);
+  if (!existsSync(dbPath)) return true;
+  const dbMtime = statSync(dbPath).mtimeMs;
+  const batches = await Promise.all(DOCUMENT_SCAN_DIRS.map((dir) => collectDocuments(projectRoot, dir)));
+  for (const relPath of new Set(batches.flat())) {
+    if (statSync(join(projectRoot, relPath)).mtimeMs > dbMtime) return true;
+  }
+  return false;
+}
+
+function compactWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function stripMarkdownHeading(value: string): string {
+  return compactWhitespace(value.replace(/^#+\s*/, ''));
+}
+
+function titleFromContent(content: string, fallback: string): string {
+  const heading = content.split('\n').find((line) => line.startsWith('# '));
+  return heading ? stripMarkdownHeading(heading) : fallback;
+}
+
+function parseKeyValueTokens(line: string): { created_at: string; fields: Record<string, string> } | null {
+  const match = /^-\s+(\S+)\s+(.*)$/.exec(line.trim());
+  if (!match) return null;
+  const [, createdAt, rest] = match;
+  const fields: Record<string, string> = {};
+  for (const token of rest.split(/\s+/)) {
+    const equalsAt = token.indexOf('=');
+    if (equalsAt <= 0) continue;
+    fields[token.slice(0, equalsAt)] = token.slice(equalsAt + 1);
+  }
+  return { created_at: createdAt, fields };
+}
+
+function parseBool(value: string | undefined): boolean {
+  return value === 'true';
+}
+
+function splitList(value: string | undefined): string[] {
+  if (!value || value === 'none') return [];
+  return value.split(',').map((part) => part.trim()).filter(Boolean);
+}
+
+function parseRefs(value: string | undefined): LedgerEntryRefs {
+  const refs: LedgerEntryRefs = {};
+  for (const item of splitList(value)) {
+    const colonAt = item.indexOf(':');
+    if (colonAt <= 0) continue;
+    const key = item.slice(0, colonAt) as keyof LedgerEntryRefs;
+    const ref = item.slice(colonAt + 1);
+    if (!['lanes', 'commits', 'prs', 'bus', 'artifacts', 'receipts'].includes(key)) continue;
+    refs[key] = [...(refs[key] ?? []), ref];
+  }
+  return refs;
+}
+
+function refPairs(refs: LedgerEntryRefs): { type: string; ref: string }[] {
+  const pairs: { type: string; ref: string }[] = [];
+  for (const key of ['lanes', 'commits', 'prs', 'bus', 'artifacts', 'receipts'] as const) {
+    for (const ref of refs[key] ?? []) {
+      pairs.push({ type: key, ref });
+    }
+  }
+  return pairs;
+}
+
+function statusEffect(value: string | undefined): LedgerStatusEffect {
+  if (!value) return 'none';
+  if (LEDGER_STATUS_EFFECTS.includes(value as LedgerStatusEffect)) {
+    return value as LedgerStatusEffect;
+  }
+  throw new Error(`unsupported ledger status_effect: ${value}`);
+}
+
+export function parseLedgerEntryLine(line: string, sourcePath = 'docs/work/ledger/LEDGER.md', lineNo = 0): ParsedLedgerLine | null {
+  const parsed = parseKeyValueTokens(line);
+  if (!parsed) return null;
+  const { created_at: createdAt, fields } = parsed;
+  if (fields.schema !== 'ledger-entry.v0' && fields.schema !== 'ledger-entry.v0.1' && fields.schema !== 'ledger-entry.v0.2') return null;
+  const entryId = fields.entry_id;
+  if (!entryId) return null;
+  const topicHints = splitList(fields.topic_hints);
+  assertLedgerTopicHints(topicHints);
+  const effect = statusEffect(fields.status_effect);
+  const known = new Set([
+    'schema',
+    'entry_id',
+    'entry_type',
+    'spine_eligible',
+    'authority_class',
+    'grants_execution',
+    'export_class',
+    'refs',
+    'topic_hints',
+    'status_effect',
+  ]);
+  const extra = Object.fromEntries(Object.entries(fields).filter(([key]) => !known.has(key)));
+  return {
+    entry_id: entryId,
+    schema: fields.schema,
+    created_at: createdAt,
+    entry_type: fields.entry_type ?? 'event',
+    spine_eligible: parseBool(fields.spine_eligible),
+    authority_class: fields.authority_class ?? 'advisory',
+    grants_execution: parseBool(fields.grants_execution),
+    export_class: fields.export_class ?? 'local_private',
+    refs: parseRefs(fields.refs),
+    topic_hints: topicHints,
+    status_effect: effect,
+    source_path: sourcePath,
+    line_no: lineNo,
+    extra,
+  };
+}
+
+function resetDbFiles(dbPath: string): void {
+  for (const path of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    if (existsSync(path)) rmSync(path, { force: true });
+  }
+}
+
+function applyLedgerIndexSchema(db: Database): void {
+  db.exec(`
+    PRAGMA journal_mode = DELETE;
+    PRAGMA busy_timeout = 5000;
+    CREATE TABLE IF NOT EXISTS ledger_entries (
+      entry_id TEXT PRIMARY KEY,
+      schema TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      entry_type TEXT NOT NULL,
+      spine_eligible INTEGER NOT NULL,
+      authority_class TEXT NOT NULL,
+      grants_execution INTEGER NOT NULL,
+      export_class TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      topic_hints_json TEXT NOT NULL,
+      status_effect TEXT NOT NULL,
+      refs_json TEXT NOT NULL,
+      source_path TEXT NOT NULL,
+      line_no INTEGER NOT NULL,
+      extra_json TEXT NOT NULL,
+      is_canonical INTEGER NOT NULL DEFAULT 0,
+      regenerable INTEGER NOT NULL DEFAULT 1,
+      can_authorize INTEGER NOT NULL DEFAULT 0,
+      indexed_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS refs (
+      entry_id TEXT NOT NULL,
+      ref_type TEXT NOT NULL,
+      ref TEXT NOT NULL,
+      FOREIGN KEY(entry_id) REFERENCES ledger_entries(entry_id)
+    );
+    CREATE TABLE IF NOT EXISTS topics (
+      entry_id TEXT NOT NULL,
+      topic TEXT NOT NULL,
+      source TEXT NOT NULL,
+      FOREIGN KEY(entry_id) REFERENCES ledger_entries(entry_id)
+    );
+    CREATE TABLE IF NOT EXISTS documents (
+      document_id TEXT PRIMARY KEY,
+      doc_type TEXT NOT NULL,
+      path TEXT NOT NULL,
+      title TEXT NOT NULL,
+      indexed_at TEXT NOT NULL
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS fts_chunks
+      USING fts5(chunk_id UNINDEXED, source_type UNINDEXED, source_id UNINDEXED, title, body, ref UNINDEXED);
+  `);
+}
+
+function documentType(relPath: string): string {
+  if (relPath.includes('/topic-snapshots/')) return 'topic_snapshot';
+  if (relPath.includes('/ledger-digests/')) return 'ledger_digest';
+  if (relPath.includes('/consumer-registry/')) return 'consumer_registry';
+  if (relPath.includes('/bus-feed/')) return 'bus_feed';
+  if (relPath.includes('/receipts/')) return 'receipt';
+  if (relPath.includes('/ledger/')) return 'ledger';
+  return 'document';
+}
+
+async function collectDocuments(root: string, relDir: string): Promise<string[]> {
+  const absDir = join(root, relDir);
+  if (!existsSync(absDir)) return [];
+  const out: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '_worktrees') continue;
+        await walk(abs);
+        continue;
+      }
+      if (!entry.isFile() || !TEXT_EXTENSIONS.has(extname(entry.name))) continue;
+      out.push(relative(root, abs));
+    }
+  }
+  await walk(absDir);
+  return out.sort();
+}
+
+async function insertDocuments(db: Database, projectRoot: string, indexedAt: string): Promise<number> {
+  const batches = await Promise.all(DOCUMENT_SCAN_DIRS.map((dir) => collectDocuments(projectRoot, dir)));
+  const docs = [...new Set(batches.flat())].sort();
+  const insertDoc = db.query(`
+    INSERT OR REPLACE INTO documents (document_id, doc_type, path, title, indexed_at)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+  const insertFts = db.query(`
+    INSERT INTO fts_chunks (chunk_id, source_type, source_id, title, body, ref)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+  for (const relPath of docs) {
+    const content = await readFile(join(projectRoot, relPath), 'utf-8');
+    const title = titleFromContent(content, relPath.split('/').at(-1) ?? relPath);
+    const id = `doc:${relPath}`;
+    const type = documentType(relPath);
+    insertDoc.run(id, type, relPath, title, indexedAt);
+    insertFts.run(`doc:${relPath}`, 'document', id, title, `${type} ${title} ${relPath}`, relPath);
+  }
+  return docs.length;
+}
+
+function compactRefsForSearch(refs: LedgerEntryRefs): string {
+  return refPairs(refs).map((pair) => `${pair.type}:${pair.ref}`).join(' ');
+}
+
+function insertLedgerEntry(db: Database, entry: ParsedLedgerLine, indexedAt: string): { refs: number; topics: number } {
+  const summary = [
+    entry.entry_type,
+    entry.entry_id,
+    entry.status_effect !== 'none' ? entry.status_effect : '',
+    entry.topic_hints.join(' '),
+    compactRefsForSearch(entry.refs),
+  ].filter(Boolean).join(' ');
+  db.query(`
+    INSERT OR REPLACE INTO ledger_entries
+      (entry_id, schema, created_at, entry_type, spine_eligible, authority_class,
+       grants_execution, export_class, summary, topic_hints_json, status_effect,
+       refs_json, source_path, line_no, extra_json, is_canonical, regenerable,
+       can_authorize, indexed_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 1, 0, ?)
+  `).run(
+    entry.entry_id,
+    entry.schema,
+    entry.created_at,
+    entry.entry_type,
+    entry.spine_eligible ? 1 : 0,
+    entry.authority_class,
+    entry.grants_execution ? 1 : 0,
+    entry.export_class,
+    summary,
+    JSON.stringify(entry.topic_hints),
+    entry.status_effect,
+    JSON.stringify(entry.refs),
+    entry.source_path,
+    entry.line_no,
+    JSON.stringify(entry.extra),
+    indexedAt,
+  );
+  db.query(`
+    INSERT INTO fts_chunks (chunk_id, source_type, source_id, title, body, ref)
+    VALUES (?, 'ledger_entry', ?, ?, ?, ?)
+  `).run(
+    `ledger:${entry.entry_id}`,
+    entry.entry_id,
+    entry.entry_id,
+    summary,
+    `${entry.source_path}:${entry.line_no}`,
+  );
+  let refs = 0;
+  for (const pair of refPairs(entry.refs)) {
+    db.query('INSERT INTO refs (entry_id, ref_type, ref) VALUES (?, ?, ?)').run(entry.entry_id, pair.type, pair.ref);
+    refs += 1;
+  }
+  let topics = 0;
+  for (const topic of entry.topic_hints) {
+    db.query('INSERT INTO topics (entry_id, topic, source) VALUES (?, ?, ?)').run(entry.entry_id, topic, 'topic_hints');
+    topics += 1;
+  }
+  return { refs, topics };
+}
+
+export async function rebuildLedgerIndex(options: {
+  projectRoot: string;
+  dbPath?: string;
+}): Promise<LedgerIndexResult> {
+  const projectRoot = resolve(options.projectRoot);
+  const dbPath = options.dbPath ?? defaultLedgerIndexDbPath(projectRoot);
+  mkdirSync(dirname(dbPath), { recursive: true });
+  resetDbFiles(dbPath);
+  const db = new Database(dbPath);
+  const indexedAt = new Date().toISOString();
+  try {
+    applyLedgerIndexSchema(db);
+    const ledgerPath = join(projectRoot, 'docs', 'work', 'ledger', 'LEDGER.md');
+    let ledgerEntries = 0;
+    let refs = 0;
+    let topics = 0;
+    if (existsSync(ledgerPath)) {
+      const relLedgerPath = relative(projectRoot, ledgerPath);
+      const lines = (await readFile(ledgerPath, 'utf-8')).split('\n');
+      for (const [index, line] of lines.entries()) {
+        const entry = parseLedgerEntryLine(line, relLedgerPath, index + 1);
+        if (!entry) continue;
+        const counts = insertLedgerEntry(db, entry, indexedAt);
+        ledgerEntries += 1;
+        refs += counts.refs;
+        topics += counts.topics;
+      }
+    }
+    const documents = await insertDocuments(db, projectRoot, indexedAt);
+    return { dbPath, ledger_entries: ledgerEntries, refs, topics, documents };
+  } finally {
+    db.close();
+  }
+}
+
+function mapSearchRow(row: LedgerEntryRow): CompactLedgerSearchResult {
+  const refs = refPairs(JSON.parse(row.refs_json) as LedgerEntryRefs).map((pair) => `${pair.type}:${pair.ref}`);
+  return {
+    entry_id: row.entry_id,
+    title: row.entry_id,
+    type: row.entry_type,
+    topic_hints: JSON.parse(row.topic_hints_json) as string[],
+    status_effect: row.status_effect,
+    refs,
+    confidence: 'metadata',
+    is_canonical: false,
+    regenerable: true,
+    can_authorize: false,
+  };
+}
+
+function mapDetailRow(row: Required<LedgerEntryRow>): LedgerIndexEntryDetail {
+  return {
+    ...mapSearchRow(row),
+    source_path: row.source_path,
+    line_no: row.line_no,
+  };
+}
+
+function searchTerms(query: string): string[] {
+  return compactWhitespace(query.toLowerCase()).split(/[^a-z0-9]+/).filter(Boolean).slice(0, 8);
+}
+
+function ftsQuery(terms: string[]): string {
+  return terms.map((term) => `"${term.replace(/"/g, '""')}"`).join(' ');
+}
+
+function likeSearchRows(db: Database, terms: string[], limit: number): LedgerEntryRow[] {
+  const like = `%${terms.join('%')}%`;
+  return db.query<LedgerEntryRow, [string, string, string, number]>(`
+    SELECT entry_id, entry_type, topic_hints_json, status_effect, refs_json
+    FROM ledger_entries
+    WHERE lower(summary) LIKE ?
+       OR lower(entry_id) LIKE ?
+       OR lower(topic_hints_json) LIKE ?
+    ORDER BY created_at DESC, entry_id ASC
+    LIMIT ?
+  `).all(like, like, like, limit);
+}
+
+export function searchLedgerIndex(options: {
+  dbPath: string;
+  query: string;
+  limit?: number;
+}): CompactLedgerSearchResult[] {
+  const db = new Database(options.dbPath, { readonly: true });
+  try {
+    const terms = searchTerms(options.query);
+    if (terms.length === 0) return [];
+    const limit = options.limit ?? 10;
+    let rows: LedgerEntryRow[];
+    try {
+      rows = db.query<LedgerEntryRow, [string, number]>(`
+        WITH matches AS (
+          SELECT source_id, bm25(fts_chunks) AS rank
+          FROM fts_chunks
+          WHERE fts_chunks MATCH ?
+            AND source_type = 'ledger_entry'
+        )
+        SELECT le.entry_id, le.entry_type, le.topic_hints_json, le.status_effect, le.refs_json
+        FROM ledger_entries le
+        JOIN matches ON matches.source_id = le.entry_id
+        ORDER BY matches.rank ASC, le.created_at DESC, le.entry_id ASC
+        LIMIT ?
+      `).all(ftsQuery(terms), limit);
+    } catch {
+      rows = likeSearchRows(db, terms, limit);
+    }
+    if (rows.length === 0) {
+      rows = likeSearchRows(db, terms, limit);
+    }
+    return rows.map(mapSearchRow);
+  } finally {
+    db.close();
+  }
+}
+
+export function showLedgerIndexEntry(options: {
+  dbPath: string;
+  entryIdOrRef: string;
+}): LedgerIndexEntryDetail | null {
+  const db = new Database(options.dbPath, { readonly: true });
+  try {
+    const row = db.query<Required<LedgerEntryRow>, [string, string]>(`
+      SELECT entry_id, entry_type, topic_hints_json, status_effect, refs_json, source_path, line_no
+      FROM ledger_entries
+      WHERE entry_id = ?
+         OR entry_id = (
+           SELECT entry_id FROM refs WHERE ref = ? ORDER BY entry_id ASC LIMIT 1
+         )
+      ORDER BY entry_id ASC
+      LIMIT 1
+    `).get(options.entryIdOrRef, options.entryIdOrRef);
+    return row ? mapDetailRow(row) : null;
+  } finally {
+    db.close();
+  }
+}
+
+export function initializePrivateVerbatimStore(options: {
+  projectRoot: string;
+  dbPath?: string;
+  explicitOptIn?: boolean;
+}): string {
+  if (!options.explicitOptIn) {
+    throw new Error('private verbatim ledger store requires explicit operator opt-in');
+  }
+  const dbPath = options.dbPath ?? defaultPrivateVerbatimDbPath(resolve(options.projectRoot));
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  try {
+    db.exec(`
+      PRAGMA journal_mode = DELETE;
+      CREATE TABLE IF NOT EXISTS verbatim_chunks (
+        chunk_id TEXT PRIMARY KEY,
+        source_ref TEXT NOT NULL,
+        body TEXT NOT NULL,
+        export_class TEXT NOT NULL DEFAULT 'local_private',
+        captured_at TEXT NOT NULL
+      );
+    `);
+  } finally {
+    db.close();
+  }
+  return dbPath;
+}

package/packages/control/src/memory/context.ts

@@ -0,0 +1,149 @@
+import { resolve } from 'node:path';
+import { assertSharedMemoryScopeId, assertSharedMemoryText } from './sanitize';
+import { defaultMemoryDbPath } from './indexer';
+import { openMemoryStore } from './store';
+import type { EvidenceRef, MemoryCategory, MemoryConfidence, RecallCapsule, StalenessStatus } from './types';
+
+export interface MemoryContextItem {
+  capsule_id: string;
+  title: string;
+  category: MemoryCategory;
+  summary: string;
+  why_it_matters: string;
+  confidence: MemoryConfidence;
+  stale_status: StalenessStatus;
+  evidence_refs: EvidenceRef[];
+  recommended_action: RecallCapsule['recommended_action'];
+}
+
+export interface MemoryContextPack {
+  schema: 'memory-context.v0';
+  generated_at: string;
+  query: string;
+  scope: {
+    org_id?: string;
+    workspace_id?: string;
+    lane_ref?: string;
+    task_ref?: string;
+  };
+  items: MemoryContextItem[];
+  content_boundary: {
+    summaries_only: true;
+    raw_ledger_body_included: false;
+    raw_event_body_included: false;
+    raw_prompt_included: false;
+    raw_tool_output_included: false;
+    source_snippets_included: false;
+    local_paths_included: false;
+  };
+  authority_boundary: {
+    can_authorize_work: false;
+    can_close_task: false;
+    can_replace_receipt: false;
+    can_mutate_ledger: false;
+    memory_is_execution_truth: false;
+  };
+}
+
+export interface BuildMemoryContextOptions {
+  projectRoot: string;
+  dbPath?: string;
+  query?: string;
+  laneRef?: string;
+  taskRef?: string;
+  orgId?: string;
+  workspaceId?: string;
+  limit: number;
+  at?: string;
+}
+
+function compactQuery(options: BuildMemoryContextOptions): string {
+  if (options.query?.trim()) {
+    const query = options.query.trim();
+    assertSharedMemoryText(query, 'memory context query');
+    return query;
+  }
+  const parts = [options.laneRef, options.taskRef]
+    .map((part) => part?.trim())
+    .filter((part): part is string => Boolean(part));
+  if (parts.length === 0) {
+    throw new Error('memory context requires --lane, --task, or --query');
+  }
+  const query = parts.join(' ');
+  assertSharedMemoryText(query, 'memory context query');
+  return query;
+}
+
+function validateScope(options: BuildMemoryContextOptions): MemoryContextPack['scope'] {
+  if (options.orgId) assertSharedMemoryScopeId(options.orgId, 'scope.org_id');
+  if (options.workspaceId) assertSharedMemoryScopeId(options.workspaceId, 'scope.workspace_id');
+  if (options.laneRef) assertSharedMemoryText(options.laneRef, 'scope.lane_ref');
+  if (options.taskRef) assertSharedMemoryText(options.taskRef, 'scope.task_ref');
+  return {
+    ...(options.orgId ? { org_id: options.orgId } : {}),
+    ...(options.workspaceId ? { workspace_id: options.workspaceId } : {}),
+    ...(options.laneRef ? { lane_ref: options.laneRef } : {}),
+    ...(options.taskRef ? { task_ref: options.taskRef } : {}),
+  };
+}
+
+function contextItem(capsule: RecallCapsule): MemoryContextItem {
+  return {
+    capsule_id: capsule.capsule_id,
+    title: capsule.title,
+    category: capsule.category,
+    summary: capsule.summary,
+    why_it_matters: capsule.why_it_matters,
+    confidence: capsule.confidence,
+    stale_status: capsule.staleness.status,
+    evidence_refs: capsule.evidence_refs,
+    recommended_action: capsule.recommended_action,
+  };
+}
+
+export function buildMemoryContext(options: BuildMemoryContextOptions): MemoryContextPack {
+  if (options.limit < 1 || options.limit > 50) {
+    throw new Error('memory context limit must be between 1 and 50');
+  }
+  const projectRoot = resolve(options.projectRoot);
+  const query = compactQuery(options);
+  const scope = validateScope(options);
+  const generatedAt = options.at ?? new Date().toISOString();
+  if (!Number.isFinite(Date.parse(generatedAt))) {
+    throw new Error('--at must be an ISO-8601 timestamp');
+  }
+
+  const store = openMemoryStore(options.dbPath ?? defaultMemoryDbPath(projectRoot));
+  try {
+    const hits = store.search(query, options.limit);
+    const items = hits
+      .map((hit) => store.show(hit.capsule_id))
+      .filter((capsule): capsule is RecallCapsule => capsule !== null)
+      .map(contextItem);
+    return {
+      schema: 'memory-context.v0',
+      generated_at: new Date(generatedAt).toISOString(),
+      query,
+      scope,
+      items,
+      content_boundary: {
+        summaries_only: true,
+        raw_ledger_body_included: false,
+        raw_event_body_included: false,
+        raw_prompt_included: false,
+        raw_tool_output_included: false,
+        source_snippets_included: false,
+        local_paths_included: false,
+      },
+      authority_boundary: {
+        can_authorize_work: false,
+        can_close_task: false,
+        can_replace_receipt: false,
+        can_mutate_ledger: false,
+        memory_is_execution_truth: false,
+      },
+    };
+  } finally {
+    store.close();
+  }
+}