carthagent 0.0.0-stage → 1.0.7

package/lib/cloud/ledger.mjs

@@ -0,0 +1,215 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const ENTRY_KINDS = new Set(['credit_grant', 'reservation', 'charge', 'reservation_release', 'refund', 'adjustment']);
+const FORBIDDEN_METADATA = /prompt|response|source|code|tool|argument|content|message/i;
+
+export function nanoUsd(value, name = 'amountNanoUsd') {
+  if (!Number.isSafeInteger(value)) throw new TypeError(`${name} must be a safe integer nano-USD amount`);
+  return value;
+}
+
+export function validateFinancialMetadata(metadata = {}) {
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) throw new TypeError('metadata must be an object');
+  const clean = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (FORBIDDEN_METADATA.test(key)) throw new Error(`financial metadata must not contain customer content (${key})`);
+    if (!['string', 'number', 'boolean'].includes(typeof value) && value !== null) throw new TypeError(`financial metadata value ${key} must be scalar`);
+    clean[key] = value;
+  }
+  return clean;
+}
+
+export function openLedger(path = ':memory:') {
+  if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path);
+  db.exec('PRAGMA foreign_keys = ON; PRAGMA journal_mode = WAL;');
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS accounts (
+      id TEXT PRIMARY KEY,
+      created_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS credit_grants (
+      id TEXT PRIMARY KEY,
+      account_id TEXT NOT NULL REFERENCES accounts(id),
+      original_nano_usd INTEGER NOT NULL CHECK(original_nano_usd > 0),
+      remaining_nano_usd INTEGER NOT NULL CHECK(remaining_nano_usd >= 0),
+      expires_at TEXT,
+      source TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS credit_grants_spendable ON credit_grants(account_id, expires_at, created_at);
+    CREATE TABLE IF NOT EXISTS reservations (
+      id TEXT PRIMARY KEY,
+      account_id TEXT NOT NULL REFERENCES accounts(id),
+      idempotency_key TEXT NOT NULL UNIQUE,
+      requested_nano_usd INTEGER NOT NULL CHECK(requested_nano_usd > 0),
+      status TEXT NOT NULL CHECK(status IN ('open','settled','released')),
+      request_id TEXT UNIQUE,
+      created_at TEXT NOT NULL,
+      settled_at TEXT
+    );
+    CREATE TABLE IF NOT EXISTS reservation_allocations (
+      reservation_id TEXT NOT NULL REFERENCES reservations(id),
+      grant_id TEXT NOT NULL REFERENCES credit_grants(id),
+      reserved_nano_usd INTEGER NOT NULL CHECK(reserved_nano_usd > 0),
+      consumed_nano_usd INTEGER NOT NULL DEFAULT 0 CHECK(consumed_nano_usd >= 0),
+      PRIMARY KEY(reservation_id, grant_id)
+    );
+    CREATE TABLE IF NOT EXISTS ledger_entries (
+      id TEXT PRIMARY KEY,
+      account_id TEXT NOT NULL REFERENCES accounts(id),
+      kind TEXT NOT NULL,
+      amount_nano_usd INTEGER NOT NULL,
+      idempotency_key TEXT NOT NULL UNIQUE,
+      reservation_id TEXT REFERENCES reservations(id),
+      gateway_request_id TEXT,
+      gateway_attempt_id TEXT,
+      metadata_json TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL
+    );
+  `);
+  return db;
+}
+
+export class CloudLedger {
+  constructor({ path = ':memory:', clock = () => new Date(), id = randomUUID } = {}) {
+    this.db = openLedger(path);
+    this.clock = clock;
+    this.id = id;
+  }
+
+  now() { return this.clock().toISOString(); }
+  close() { this.db.close(); }
+
+  createAccount(accountId = this.id()) {
+    this.db.prepare('INSERT OR IGNORE INTO accounts (id, created_at) VALUES (?, ?)').run(accountId, this.now());
+    return accountId;
+  }
+
+  entryByKey(key) {
+    return this.db.prepare('SELECT * FROM ledger_entries WHERE idempotency_key = ?').get(key);
+  }
+
+  appendEntry({ accountId, kind, amountNanoUsd, idempotencyKey, reservationId = null, gatewayRequestId = null, gatewayAttemptId = null, metadata = {} }) {
+    if (!ENTRY_KINDS.has(kind)) throw new Error(`unknown ledger entry kind: ${kind}`);
+    nanoUsd(amountNanoUsd);
+    if (!idempotencyKey) throw new Error('idempotencyKey is required');
+    const cleanMetadata = validateFinancialMetadata(metadata);
+    const existing = this.entryByKey(idempotencyKey);
+    if (existing) return existing;
+    const id = this.id();
+    this.db.prepare(`INSERT INTO ledger_entries
+      (id, account_id, kind, amount_nano_usd, idempotency_key, reservation_id, gateway_request_id, gateway_attempt_id, metadata_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+      id, accountId, kind, amountNanoUsd, idempotencyKey, reservationId, gatewayRequestId, gatewayAttemptId, JSON.stringify(cleanMetadata), this.now()
+    );
+    return this.db.prepare('SELECT * FROM ledger_entries WHERE id = ?').get(id);
+  }
+
+  grant({ accountId, amountNanoUsd, idempotencyKey, expiresAt = null, source = 'manual', metadata = {} }) {
+    nanoUsd(amountNanoUsd);
+    if (amountNanoUsd <= 0) throw new Error('grant amount must be positive');
+    this.createAccount(accountId);
+    const existing = this.entryByKey(idempotencyKey);
+    if (existing) return existing;
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const grantId = this.id();
+      this.db.prepare(`INSERT INTO credit_grants
+        (id, account_id, original_nano_usd, remaining_nano_usd, expires_at, source, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)`).run(grantId, accountId, amountNanoUsd, amountNanoUsd, expiresAt, source, this.now());
+      const entry = this.appendEntry({ accountId, kind: 'credit_grant', amountNanoUsd, idempotencyKey, metadata: { ...metadata, grantId } });
+      this.db.exec('COMMIT');
+      return entry;
+    } catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+
+  available(accountId, at = this.now()) {
+    const row = this.db.prepare(`SELECT COALESCE(SUM(remaining_nano_usd), 0) AS balance
+      FROM credit_grants WHERE account_id = ? AND remaining_nano_usd > 0 AND (expires_at IS NULL OR expires_at > ?)`).get(accountId, at);
+    return Number(row.balance);
+  }
+
+  reserve({ accountId, maximumNanoUsd, idempotencyKey }) {
+    nanoUsd(maximumNanoUsd, 'maximumNanoUsd');
+    if (maximumNanoUsd <= 0) throw new Error('reservation amount must be positive');
+    const existing = this.db.prepare('SELECT * FROM reservations WHERE idempotency_key = ?').get(idempotencyKey);
+    if (existing) return existing;
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const grants = this.db.prepare(`SELECT * FROM credit_grants
+        WHERE account_id = ? AND remaining_nano_usd > 0 AND (expires_at IS NULL OR expires_at > ?)
+        ORDER BY CASE WHEN expires_at IS NULL THEN 1 ELSE 0 END, expires_at, created_at, id`).all(accountId, this.now());
+      if (grants.reduce((sum, grant) => sum + Number(grant.remaining_nano_usd), 0) < maximumNanoUsd) throw new Error('insufficient_credit');
+      const reservationId = this.id();
+      this.db.prepare(`INSERT INTO reservations
+        (id, account_id, idempotency_key, requested_nano_usd, status, created_at)
+        VALUES (?, ?, ?, ?, 'open', ?)`).run(reservationId, accountId, idempotencyKey, maximumNanoUsd, this.now());
+      let remaining = maximumNanoUsd;
+      for (const grant of grants) {
+        if (!remaining) break;
+        const amount = Math.min(remaining, Number(grant.remaining_nano_usd));
+        this.db.prepare('UPDATE credit_grants SET remaining_nano_usd = remaining_nano_usd - ? WHERE id = ?').run(amount, grant.id);
+        this.db.prepare('INSERT INTO reservation_allocations (reservation_id, grant_id, reserved_nano_usd) VALUES (?, ?, ?)').run(reservationId, grant.id, amount);
+        remaining -= amount;
+      }
+      this.appendEntry({ accountId, kind: 'reservation', amountNanoUsd: -maximumNanoUsd, idempotencyKey: `reservation:${idempotencyKey}`, reservationId });
+      this.db.exec('COMMIT');
+      return this.db.prepare('SELECT * FROM reservations WHERE id = ?').get(reservationId);
+    } catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+
+  settle({ reservationId, actualNanoUsd, requestId, attemptId = null, idempotencyKey, metadata = {} }) {
+    nanoUsd(actualNanoUsd, 'actualNanoUsd');
+    if (actualNanoUsd < 0) throw new Error('actual charge cannot be negative');
+    const existing = this.entryByKey(idempotencyKey);
+    if (existing) return existing;
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const reservation = this.db.prepare('SELECT * FROM reservations WHERE id = ?').get(reservationId);
+      if (!reservation) throw new Error('reservation_not_found');
+      if (reservation.status !== 'open') throw new Error(`reservation_${reservation.status}`);
+      if (actualNanoUsd > reservation.requested_nano_usd) throw new Error('charge_exceeds_reservation');
+      const allocations = this.db.prepare('SELECT * FROM reservation_allocations WHERE reservation_id = ? ORDER BY rowid').all(reservationId);
+      let chargeRemaining = actualNanoUsd;
+      let released = 0;
+      for (const allocation of allocations) {
+        const consumed = Math.min(chargeRemaining, Number(allocation.reserved_nano_usd));
+        const release = Number(allocation.reserved_nano_usd) - consumed;
+        this.db.prepare('UPDATE reservation_allocations SET consumed_nano_usd = ? WHERE reservation_id = ? AND grant_id = ?').run(consumed, reservationId, allocation.grant_id);
+        if (release) this.db.prepare('UPDATE credit_grants SET remaining_nano_usd = remaining_nano_usd + ? WHERE id = ?').run(release, allocation.grant_id);
+        chargeRemaining -= consumed;
+        released += release;
+      }
+      const entry = this.appendEntry({ accountId: reservation.account_id, kind: 'charge', amountNanoUsd: -actualNanoUsd, idempotencyKey, reservationId, gatewayRequestId: requestId, gatewayAttemptId: attemptId, metadata });
+      if (released) this.appendEntry({ accountId: reservation.account_id, kind: 'reservation_release', amountNanoUsd: released, idempotencyKey: `release:${idempotencyKey}`, reservationId, gatewayRequestId: requestId });
+      this.db.prepare(`UPDATE reservations SET status = 'settled', request_id = ?, settled_at = ? WHERE id = ?`).run(requestId, this.now(), reservationId);
+      this.db.exec('COMMIT');
+      return entry;
+    } catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+
+  release({ reservationId, idempotencyKey }) {
+    const existing = this.entryByKey(idempotencyKey);
+    if (existing) return existing;
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const reservation = this.db.prepare('SELECT * FROM reservations WHERE id = ?').get(reservationId);
+      if (!reservation) throw new Error('reservation_not_found');
+      if (reservation.status !== 'open') throw new Error(`reservation_${reservation.status}`);
+      const allocations = this.db.prepare('SELECT * FROM reservation_allocations WHERE reservation_id = ?').all(reservationId);
+      for (const allocation of allocations) this.db.prepare('UPDATE credit_grants SET remaining_nano_usd = remaining_nano_usd + ? WHERE id = ?').run(allocation.reserved_nano_usd, allocation.grant_id);
+      const entry = this.appendEntry({ accountId: reservation.account_id, kind: 'reservation_release', amountNanoUsd: reservation.requested_nano_usd, idempotencyKey, reservationId });
+      this.db.prepare(`UPDATE reservations SET status = 'released', settled_at = ? WHERE id = ?`).run(this.now(), reservationId);
+      this.db.exec('COMMIT');
+      return entry;
+    } catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+
+  entries(accountId) {
+    return this.db.prepare('SELECT * FROM ledger_entries WHERE account_id = ? ORDER BY created_at, rowid').all(accountId).map(row => ({ ...row, metadata: JSON.parse(row.metadata_json) }));
+  }
+}

package/lib/codegraph-query.mjs

@@ -0,0 +1,60 @@
+import { isAbsolute, relative } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+// Bounded presentation of structural candidates, never runtime-resolution proof.
+export function queryCodeIndex(index, { op, name, path, container, limit = 50, offset = 0 }) {
+  const stats = index.stats();
+  if (op === 'status') return { op, coverage: stats };
+  if (!Number.isInteger(limit) || limit < 1 || limit > 200 || !Number.isInteger(offset) || offset < 0) throw Error('limit must be 1–200 and offset nonnegative');
+  name = name?.trim(); path = path?.replaceAll('\\', '/').replace(/^\.\//, '').trim();
+  if (path && isAbsolute(path)) {
+    if (existsSync(path) && statSync(path).isDirectory()) throw Error('path is a directory; omit path for repository symbol search. outline/imports need a source FILE. Use find/ls to locate files.');
+    path = relative(index.root, path).replaceAll('\\', '/');
+    if (path.startsWith('../')) throw Error('path must be inside the indexed workspace');
+  }
+  if (path && existsSync(`${index.root}/${path}`) && statSync(`${index.root}/${path}`).isDirectory()) throw Error('path is a directory; omit path for symbol search, or supply a source file for outline/imports');
+  let rows;
+  if (['definition', 'symbols', 'callers', 'callees'].includes(op) && !name) throw Error(`${op} requires name`);
+  if (['imports', 'importers', 'outline'].includes(op) && !path) throw Error(`${op} requires path`);
+  switch (op) {
+    case 'definition': rows = index.definition(name); break;
+    case 'symbols': rows = index.symbols(name); break;
+    case 'callers': rows = index.callers(name); break;
+    case 'callees': rows = index.callees(name, path); break;
+    case 'imports': rows = index.imports(path); break;
+    case 'importers': rows = index.importers(path); break;
+    case 'outline': rows = index.outline(path); break;
+    default: throw Error(`unknown op: ${op}`);
+  }
+  if (path && ['definition', 'symbols', 'callers'].includes(op)) rows = rows.filter(row => row.file === path);
+  if (container) rows = rows.filter(row => (op === 'callers' ? row.caller?.container : op === 'callees' ? row.callerDef?.container : row.container) === container);
+  const total = rows.length;
+  const results = rows.slice(offset, offset + limit);
+  const nextOffset = offset + results.length < total ? offset + results.length : null;
+  return { op, results, returned: results.length, total, offset, truncated: nextOffset !== null,
+    next: total === 0 ? 'No indexed matches. Use find/ls to locate a source file, outline that file, or remove path/container filters. grep handles strings and unsupported syntax.' : undefined,
+    nextOffset, coverage: { files: stats.files, discovered: stats.discovered, skipped: stats.skipped, unreadable: stats.unreadable, parseErrors: stats.parseErrors, complete: stats.complete },
+    semantics: ['callers', 'callees'].includes(op) ? 'Name-based structural candidates, not resolved runtime bindings. path filters call-site files for callers; container filters the enclosing caller.' : 'Indexed syntax only; excluded, unsupported and skipped files are outside coverage.' };
+}
+
+const FIELD_CAP = 256;
+const clip = value => {
+  if (typeof value === 'string') return value.length > FIELD_CAP ? `${value.slice(0, FIELD_CAP)}… [${value.length} chars]` : value;
+  if (Array.isArray(value)) return value.map(clip);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, v]) => [key, clip(v)]));
+  return value;
+};
+
+// Shrink the page, then clip oversized fields, so the envelope and nextOffset always stay parseable.
+export function boundedCodeNavResult(index, params, maxBytes = 23000) {
+  let result = queryCodeIndex(index, params);
+  let serialized = JSON.stringify(result);
+  while (Buffer.byteLength(serialized) > maxBytes && result.returned > 1) {
+    result = queryCodeIndex(index, { ...params, limit: Math.max(1, Math.floor(result.returned / 2)) });
+    serialized = JSON.stringify(result);
+  }
+  if (Buffer.byteLength(serialized) > maxBytes && result.results) {
+    result = { ...result, results: result.results.map(clip), clipped: `Fields over ${FIELD_CAP} chars were shortened; read the source file for full text.` };
+    serialized = JSON.stringify(result);
+  }
+  return serialized;
+}

package/lib/codegraph.mjs

@@ -0,0 +1,378 @@
+import { createRequire } from 'node:module';
+import { readdirSync, statSync, readFileSync } from 'node:fs';
+import { join, relative, extname, resolve, dirname, isAbsolute } from 'node:path';
+
+const require_ = createRequire(import.meta.url);
+
+const LANG_BY_EXT = {
+  '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript', '.jsx': 'javascript',
+  '.ts': 'typescript', '.mts': 'typescript', '.cts': 'typescript',
+  '.tsx': 'tsx',
+  '.py': 'python',
+  '.rs': 'rust',
+};
+
+const DEFAULT_IGNORES = new Set([
+  'node_modules', '.git', '.hg', '.svn', 'dist', 'build', 'out', 'coverage',
+  '.next', '.nuxt', 'target', 'vendor', '.venv', 'venv', '__pycache__',
+  '.idea', '.vscode', '.turbo', '.cache', '.harness', 'release',
+]);
+
+// ---- per-language AST extraction -------------------------------------------
+// Each spec: nameOf(node) → def name | null for def node types, callName(node)
+// → callee name for call node types, importSpec(node) → specifier string.
+
+const firstNamedOfType = (node, types) => {
+  for (const child of node.namedChildren) if (types.includes(child.type)) return child;
+  return null;
+};
+
+const fieldName = node => node.childForFieldName('name');
+const lastNamedChild = node => node.namedChildren[node.namedChildren.length - 1] || null;
+
+const jsSpec = {
+  defTypes: new Set(['function_declaration', 'generator_function_declaration', 'class_declaration',
+    'abstract_class_declaration', 'interface_declaration', 'type_alias_declaration',
+    'enum_declaration', 'method_definition']),
+  nameOf(node) {
+    const named = fieldName(node);
+    return named?.text || firstNamedOfType(node, ['identifier', 'type_identifier', 'property_identifier'])?.text || null;
+  },
+  defKind: node => node.type === 'method_definition' ? 'method'
+    : node.type.includes('class') ? 'class'
+      : node.type === 'interface_declaration' ? 'interface'
+        : node.type === 'type_alias_declaration' ? 'type'
+          : node.type === 'enum_declaration' ? 'enum' : 'function',
+  containerTypes: new Set(['class_declaration', 'abstract_class_declaration']),
+  isDef(node, parent) {
+    if (this.defTypes.has(node.type)) return true;
+    // const/let x = () => ... or = function ...
+    if (node.type === 'variable_declarator') {
+      const value = node.childForFieldName('value');
+      return !!value && ['arrow_function', 'function_expression', 'generator_function'].includes(value.type);
+    }
+    return false;
+  },
+  defName(node) {
+    if (node.type === 'variable_declarator') return node.childForFieldName('name')?.text || null;
+    return this.nameOf(node);
+  },
+  callTypes: new Set(['call_expression']),
+  callName(node) {
+    const fn = node.childForFieldName('function');
+    if (!fn) return null;
+    if (fn.type === 'identifier') return fn.text;
+    if (fn.type === 'member_expression') return fn.childForFieldName('property')?.text || null;
+    return null;
+  },
+  importTypes: new Set(['import_statement']),
+  importSpec(node) {
+    const src = node.childForFieldName('source') || firstNamedOfType(node, ['string']);
+    return src ? src.text.replace(/^['"`]|['"`]$/g, '') : null;
+  },
+  // require('x') as an import edge
+  extraImport(node) {
+    if (node.type !== 'call_expression') return null;
+    const fn = node.childForFieldName('function');
+    if (fn?.type !== 'identifier' || fn.text !== 'require') return null;
+    const arg = node.childForFieldName('arguments')?.namedChildren[0];
+    return arg?.type === 'string' ? arg.text.replace(/^['"`]|['"`]$/g, '') : null;
+  },
+};
+
+const pySpec = {
+  defTypes: new Set(['function_definition', 'class_definition']),
+  nameOf(node) { return firstNamedOfType(node, ['identifier'])?.text || null; },
+  defKind: node => node.type === 'class_definition' ? 'class' : 'function',
+  containerTypes: new Set(['class_definition']),
+  isDef(node) { return this.defTypes.has(node.type); },
+  defName(node) { return this.nameOf(node); },
+  callTypes: new Set(['call']),
+  callName(node) {
+    const fn = node.childForFieldName('function');
+    if (!fn) return null;
+    if (fn.type === 'identifier') return fn.text;
+    if (fn.type === 'attribute') return lastNamedChild(fn)?.text || null;
+    return null;
+  },
+  importTypes: new Set(['import_statement', 'import_from_statement']),
+  importSpec(node) {
+    const module = node.type === 'import_from_statement'
+      ? (node.childForFieldName('module_name') || firstNamedOfType(node, ['dotted_name', 'relative_import']))
+      : firstNamedOfType(node, ['dotted_name', 'aliased_import']);
+    if (!module) return null;
+    const aliased = module.type === 'aliased_import' ? firstNamedOfType(module, ['dotted_name']) : module;
+    return aliased?.text || null;
+  },
+  extraImport() { return null; },
+};
+
+const rustSpec = {
+  defTypes: new Set(['function_item', 'struct_item', 'enum_item', 'union_item', 'trait_item',
+    'type_item', 'const_item', 'static_item', 'mod_item', 'macro_definition']),
+  nameOf(node) { return firstNamedOfType(node, ['identifier', 'type_identifier'])?.text || null; },
+  defKind: node => node.type === 'function_item' ? 'function'
+    : node.type === 'struct_item' ? 'struct'
+      : node.type === 'enum_item' ? 'enum'
+        : node.type === 'trait_item' ? 'trait'
+          : node.type === 'mod_item' ? 'module' : 'item',
+  containerTypes: new Set(['impl_item', 'trait_item', 'mod_item']),
+  containerOf(node) { return firstNamedOfType(node, ['type_identifier', 'identifier'])?.text || null; },
+  isDef(node) { return this.defTypes.has(node.type); },
+  defName(node) { return this.nameOf(node); },
+  callTypes: new Set(['call_expression', 'macro_invocation']),
+  callName(node) {
+    if (node.type === 'macro_invocation') {
+      const macro = node.childForFieldName('macro') || firstNamedOfType(node, ['identifier', 'scoped_identifier']);
+      return macro ? `${macro.text.split('::').pop()}!` : null;
+    }
+    const fn = node.childForFieldName('function');
+    if (!fn) return null;
+    if (fn.type === 'identifier') return fn.text;
+    if (fn.type === 'field_expression') return fn.childForFieldName('field')?.text || null;
+    if (fn.type === 'scoped_identifier' || fn.type === 'generic_function') return lastNamedChild(fn)?.text || fn.text.split('::').pop();
+    return null;
+  },
+  importTypes: new Set(['use_declaration']),
+  importSpec(node) {
+    const arg = firstNamedOfType(node, ['scoped_identifier', 'identifier', 'use_list', 'scoped_use_list', 'use_as_clause']);
+    return arg ? arg.text : node.text.replace(/^use\s+/, '').replace(/;$/, '').trim() || null;
+  },
+  extraImport() { return null; },
+};
+
+const SPECS = { javascript: jsSpec, typescript: jsSpec, tsx: jsSpec, python: pySpec, rust: rustSpec };
+
+// ---- parser bootstrap --------------------------------------------------------
+// Dependency pin constraint: the tree-sitter-wasms grammars ship the pre-`dylink.0`
+// wasm section, which only web-tree-sitter ≤0.22.x accepts. Bump both together.
+
+let runtimePromise = null;
+const parsers = new Map(); // lang -> dedicated parser (setLanguage once; concurrent parses never share)
+
+async function parserFor(lang) {
+  if (!runtimePromise) {
+    runtimePromise = (async () => {
+      const Parser = require_('web-tree-sitter');
+      await Parser.init();
+      const wasmDir = require_.resolve('tree-sitter-wasms/package.json').replace(/package\.json$/, 'out');
+      const languages = new Map();
+      const load = async name => {
+        if (!languages.has(name)) languages.set(name, await Parser.Language.load(join(wasmDir, `tree-sitter-${name}.wasm`)));
+        return languages.get(name);
+      };
+      return { Parser, load };
+    })();
+  }
+  const { Parser, load } = await runtimePromise;
+  if (!parsers.has(lang)) {
+    const parser = new Parser();
+    parser.setLanguage(await load(lang));
+    parsers.set(lang, parser);
+  }
+  return parsers.get(lang);
+}
+
+// ---- index -------------------------------------------------------------------
+
+/**
+ * Create a structural index over a workspace. The index is per-process;
+ * `refresh()` re-parses only files whose mtime/size changed since last scan.
+ */
+export async function createCodeIndex(root, { maxFiles = 8000, maxBytes = 1_048_576, ignores = DEFAULT_IGNORES } = {}) {
+  if (!Number.isSafeInteger(maxFiles) || maxFiles < 1 || !Number.isSafeInteger(maxBytes) || maxBytes < 1) throw Error('Index limits must be positive safe integers');
+  const base = resolve(root);
+  const toRel = abs => relative(base, abs).replace(/\\/g, '/'); // index keys always POSIX-style
+  const files = new Map(); // relPath -> { mtimeMs, size, defs, calls, imports }
+  const defIndex = new Map(); // name -> [{file, line, kind, container}]
+  const callIndex = new Map(); // calleeName -> [{file, line, caller:{name,file,line}|null}]
+  const importEdges = new Map(); // file -> [spec]
+  const stats = { files: 0, symbols: 0, calls: 0, parsed: 0, parseErrors: 0, totalParseErrors: 0, parseMs: 0, skipped: 0, unreadable: 0, discovered: 0, complete: true };
+
+  const dropFile = rel => {
+    const prev = files.get(rel);
+    if (!prev) return;
+    for (const d of prev.defs) {
+      for (const key of d.keys) {
+        const list = defIndex.get(key);
+        if (list) { const i = list.findIndex(x => x.file === rel && x.line === d.line); if (i >= 0) list.splice(i, 1); if (!list.length) defIndex.delete(key); }
+      }
+      stats.symbols--;
+    }
+    for (const c of prev.calls) {
+      const list = callIndex.get(c.name);
+      if (list) { const i = list.findIndex(x => x.file === rel && x.line === c.line); if (i >= 0) list.splice(i, 1); if (!list.length) callIndex.delete(c.name); }
+      stats.calls--;
+    }
+    files.delete(rel);
+    importEdges.delete(rel);
+  };
+
+  const addDef = (rel, { name, kind, line, container }) => {
+    const keys = [name];
+    if (container) keys.push(`${container}.${name}`);
+    for (const key of keys) {
+      if (!defIndex.has(key)) defIndex.set(key, []);
+      defIndex.get(key).push({ file: rel, line, kind, container: container || null, name });
+    }
+    stats.symbols++;
+    return { name, kind, line, container: container || null, keys };
+  };
+
+  const extract = (tree, rel, spec) => {
+    const entry = { defs: [], calls: [], imports: [] };
+    const visit = (node, enclosing, container) => {
+      if (spec.isDef(node)) {
+        const name = spec.defName(node);
+        if (name) {
+          entry.defs.push(addDef(rel, { name, kind: spec.defKind(node), line: node.startPosition.row + 1, container }));
+          enclosing = { name, line: node.startPosition.row + 1, container: container || null };
+        }
+        if (spec.containerTypes.has(node.type)) container = spec.containerOf ? spec.containerOf(node) : name;
+      } else if (spec.containerTypes.has(node.type)) {
+        container = spec.containerOf ? spec.containerOf(node) : (spec.nameOf(node) || container);
+      }
+      if (spec.callTypes.has(node.type)) {
+        const name = spec.callName(node);
+        if (name) {
+          entry.calls.push({ name, line: node.startPosition.row + 1, caller: enclosing ? { ...enclosing, file: rel } : null });
+          if (!callIndex.has(name)) callIndex.set(name, []);
+          callIndex.get(name).push({ file: rel, line: node.startPosition.row + 1, caller: enclosing ? { ...enclosing, file: rel } : null });
+          stats.calls++;
+        }
+      }
+      if (spec.importTypes.has(node.type)) {
+        const specText = spec.importSpec(node);
+        if (specText) entry.imports.push(specText);
+      }
+      const extra = spec.extraImport(node);
+      if (extra) entry.imports.push(extra);
+      for (const child of node.namedChildren) visit(child, enclosing, container);
+    };
+    visit(tree.rootNode, null, null);
+    return entry;
+  };
+
+  const parseFile = async (abs, rel, lang, stat) => {
+    const source = readFileSync(abs, 'utf8');
+    const parser = await parserFor(lang);
+    const started = Date.now();
+    const tree = parser.parse(source);
+    stats.parseMs += Date.now() - started;
+    stats.parsed++;
+    const entry = extract(tree, rel, SPECS[lang]);
+    files.set(rel, { mtimeMs: stat.mtimeMs, size: stat.size, defs: entry.defs, calls: entry.calls, imports: entry.imports });
+    importEdges.set(rel, entry.imports);
+    tree.delete();
+  };
+
+  const scan = (dir, out) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { stats.unreadable++; return; }
+    for (const ent of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const abs = join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (ent.name.startsWith('.') || ignores.has(ent.name)) continue;
+        scan(abs, out);
+      } else if (ent.isFile()) {
+        const lang = LANG_BY_EXT[extname(ent.name)];
+        if (lang) out.push({ abs, lang });
+      }
+    }
+  };
+
+  const doRefresh = async () => {
+    const found = [];
+    stats.unreadable = 0;
+    scan(base, found);
+    stats.skipped = 0;
+    stats.parseErrors = 0;
+    stats.discovered = found.length;
+    if (found.length > maxFiles) { stats.skipped += found.length - maxFiles; found.length = maxFiles; }
+    const seen = new Set();
+    for (const { abs, lang } of found) {
+      const rel = toRel(abs);
+      seen.add(rel);
+      let stat;
+      try { stat = statSync(abs); } catch { dropFile(rel); stats.unreadable++; continue; }
+      if (stat.size > maxBytes) { dropFile(rel); stats.skipped++; continue; }
+      const prev = files.get(rel);
+      if (prev && prev.mtimeMs === stat.mtimeMs && prev.size === stat.size) continue;
+      dropFile(rel);
+      try { await parseFile(abs, rel, lang, stat); } catch { stats.parseErrors++; stats.totalParseErrors++; }
+    }
+    for (const rel of [...files.keys()]) if (!seen.has(rel)) dropFile(rel);
+    stats.files = files.size;
+    stats.complete = stats.skipped === 0 && stats.parseErrors === 0 && stats.unreadable === 0;
+    return stats;
+  };
+
+  const resolveImport = (fromFile, spec) => {
+    // Relative specifiers resolve to a repo file; bare specifiers stay as-is.
+    if (!spec.startsWith('.') && !spec.startsWith('/')) return null;
+    const stem = resolve(dirname(join(base, fromFile)), spec);
+    const rel = toRel(stem);
+    const candidates = [rel, ...Object.keys(LANG_BY_EXT).map(e => rel + e), `${rel}/index.ts`, `${rel}/index.tsx`, `${rel}/index.js`, `${rel}/__init__.py`, `${rel}/mod.rs`];
+    return candidates.find(c => files.has(c)) || null;
+  };
+
+  // Serialize refresh calls: overlapping refreshes would interleave dropFile/parseFile.
+  let refreshQueue = Promise.resolve();
+  const refresh = () => (refreshQueue = refreshQueue.then(doRefresh, doRefresh));
+
+  await refresh();
+
+  return {
+    root: base,
+    refresh,
+    stats: () => ({ ...stats }),
+    definition(name) {
+      return defIndex.get(name) || [];
+    },
+    symbols(query, limit = Infinity) {
+      const q = String(query || '').toLowerCase();
+      const out = [];
+      for (const [name, defs] of defIndex) {
+        if (!name.toLowerCase().includes(q)) continue;
+        for (const d of defs) out.push({ ...d, displayName: name });
+        if (out.length >= limit) break;
+      }
+      return out.slice(0, limit);
+    },
+    callers(name) { return callIndex.get(name) || []; },
+    callees(name, file) {
+      return (defIndex.get(name) || [])
+        .filter(d => !file || d.file === file)
+        .flatMap(def => collectCallsOf(def, def.name));
+    },
+    imports(file) { return files.get(file)?.imports || files.get(normalizeRel(file))?.imports || []; },
+    importers(file) {
+      const rel = normalizeRel(file);
+      const out = [];
+      for (const [f, specs] of importEdges) {
+        for (const spec of specs) {
+          if (resolveImport(f, spec) === rel || (!resolveImport(f, spec) && spec === rel)) { out.push({ file: f, spec }); break; }
+        }
+      }
+      return out;
+    },
+    outline(file) {
+      const rel = normalizeRel(file);
+      return (files.get(rel)?.defs || []).map(({ keys, ...d }) => d);
+    },
+  };
+
+  function normalizeRel(file) {
+    const s = String(file || '').replace(/^\.\//, '');
+    return (isAbsolute(s) ? toRel(s) : s).replace(/\\/g, '/');
+  }
+
+  function collectCallsOf(def, name) {
+    // calls made inside the def at def.file:def.line
+    const entry = files.get(def.file);
+    if (!entry) return [];
+    return entry.calls
+      .filter(c => c.caller && c.caller.name === name && c.caller.line === def.line && c.caller.file === def.file)
+      .map(c => ({ ...c, callerDef: def }));
+  }
+}

package/lib/context-archive.mjs

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { localPath } from './delivery.mjs';
+
+// Host storage boundary. Content-addressed originals must exist intact before
+// the outbound projection can substitute a pointer. No mutation of run state.
+export function archiveContext(cwd, directory, value) {
+  const text = JSON.stringify(value, null, 2);
+  const digest = createHash('sha256').update(text).digest('hex');
+  const root = localPath(cwd, join(directory, 'context-archive'));
+  mkdirSync(root, { recursive: true });
+  const path = localPath(cwd, join(root, `${digest}.json`));
+  try { writeFileSync(path, text, { flag: 'wx', mode: 0o600 }); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  if (readFileSync(path, 'utf8') !== text) throw Error('Context archive mismatch; original messages retained');
+  return { path, digest, bytes: Buffer.byteLength(text) };
+}