@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/src/indexing/ingest/job-graph.js

@@ -0,0 +1,181 @@
+/**
+ * codebaseindex.job.graph.v1 — portable job graph for CLI / Gantt / Studio.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+export const JOB_GRAPH_SCHEMA = 'codebaseindex.job.graph.v1';
+
+const DEFAULT_NODES = [
+  'material.stage',
+  'repository.snapshot',
+  'inventory.classify',
+  'scope.resolve',
+  'profile.resolve',
+  'lane.resolve',
+  'plan.dry_run',
+  'ast.parse',
+  'chunks.build',
+  'embedding.generate',
+  'storage.write',
+  'generation.verify',
+  'search.smoke',
+];
+
+/**
+ * @param {object} [opts]
+ */
+export function createCodebaseindexJobGraph(opts = {}) {
+  const id = opts.id || `cidxjob_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+  const now = new Date().toISOString();
+  const nodes = (opts.nodes || DEFAULT_NODES).map((nodeId, index) => ({
+    id: nodeId,
+    status: opts.completed?.includes(nodeId) ? 'done'
+      : opts.current === nodeId ? 'run'
+        : 'pending',
+    ordinal: index,
+    started_at: null,
+    completed_at: null,
+    inputs: {},
+    outputs: {},
+    errors: [],
+  }));
+  return {
+    schema: JOB_GRAPH_SCHEMA,
+    id,
+    pipeline: 'sam.codebaseindex.index.run',
+    operation: 'codebaseindex.ingest',
+    created_at: now,
+    updated_at: now,
+    status: opts.status || 'planned',
+    current: nodes.find((node) => node.status === 'run')?.id || null,
+    nodes,
+    work_items: nodes.map((n) => ({
+      id: n.id,
+      title: n.id,
+      status: n.status === 'done' ? 'completed' : n.status === 'run' ? 'in_progress' : 'pending',
+      start: null,
+      end: null,
+    })),
+  };
+}
+
+/**
+ * Mark nodes through `throughId` as done; set next as run (or complete).
+ * @param {ReturnType<typeof createCodebaseindexJobGraph>} graph
+ * @param {string} throughId
+ */
+export function advanceJobGraph(graph, throughId) {
+  const next = structuredClone(graph);
+  next.updated_at = new Date().toISOString();
+  let found = false;
+  for (const node of next.nodes) {
+    if (!found) {
+      if (node.status !== 'skipped') {
+        node.status = 'done';
+        node.completed_at = next.updated_at;
+      }
+      if (node.id === throughId) found = true;
+    } else if (node.status === 'pending') {
+      node.status = 'run';
+      node.started_at = next.updated_at;
+      break;
+    }
+  }
+  syncWorkItems(next);
+  const allDone = next.nodes.every((n) => n.status === 'done' || n.status === 'skipped');
+  next.status = allDone ? 'completed' : 'running';
+  next.current = next.nodes.find((n) => n.status === 'run')?.id || null;
+  return next;
+}
+
+/**
+ * After a successful dry-run: freeze remaining nodes as planned (not "run").
+ * Prevents `→ ast.parse` looking like the CLI is waiting for another command.
+ *
+ * @param {ReturnType<typeof createCodebaseindexJobGraph>} graph
+ * @param {{ skipEmbedding?: boolean }} [opts]
+ */
+export function freezePlanJobGraph(graph, opts = {}) {
+  const next = structuredClone(graph);
+  next.updated_at = new Date().toISOString();
+  next.status = 'planned';
+  for (const node of next.nodes) {
+    if (node.status === 'done') continue;
+    if (opts.skipEmbedding && node.id === 'embedding.generate') {
+      node.status = 'skipped';
+      node.completed_at = next.updated_at;
+      continue;
+    }
+    // Clear accidental "run" pointer from advanceJobGraph
+    node.status = 'planned';
+    node.started_at = null;
+  }
+  next.current = null;
+  syncWorkItems(next);
+  return next;
+}
+
+/**
+ * Mark a graph node as intentionally skipped while preserving graph truth.
+ */
+export function skipJobGraphNode(graph, nodeId, reason = 'not_required') {
+  const next = structuredClone(graph);
+  next.updated_at = new Date().toISOString();
+
+  const node = next.nodes.find((candidate) => candidate.id === nodeId);
+  if (!node) throw new Error(`Unknown job graph node: ${nodeId}`);
+
+  node.status = 'skipped';
+  node.started_at = null;
+  node.completed_at = next.updated_at;
+  node.outputs = { ...(node.outputs || {}), skip_reason: reason };
+
+  syncWorkItems(next);
+
+  const allDone = next.nodes.every(
+    (candidate) => candidate.status === 'done' || candidate.status === 'skipped',
+  );
+
+  next.status = allDone ? 'completed' : 'running';
+  next.current = next.nodes.find((candidate) => candidate.status === 'run')?.id || null;
+
+  return next;
+}
+
+/**
+ * Human projection of the job graph for CLI notes.
+ * @param {ReturnType<typeof createCodebaseindexJobGraph>} graph
+ * @param {{ planOnly?: boolean }} [opts]
+ */
+export function formatJobGraphHuman(graph, opts = {}) {
+  const lines = [];
+  const planned = [];
+  for (const n of graph.nodes || []) {
+    if (n.status === 'done') lines.push(`✓ ${n.id}`);
+    else if (n.status === 'skipped') lines.push(`⊘ ${n.id}   skipped`);
+    else if (opts.planOnly || n.status === 'planned' || graph.status === 'planned') {
+      planned.push(n.id);
+    } else if (n.status === 'run') lines.push(`→ ${n.id}`);
+    else lines.push(`· ${n.id}`);
+  }
+  if (planned.length) {
+    lines.push('');
+    lines.push('PLANNED FOR RUN');
+    for (const id of planned) lines.push(`○ ${id}`);
+  }
+  return lines.join('\n');
+}
+
+function syncWorkItems(graph) {
+  graph.work_items = graph.nodes.map((n) => ({
+    id: n.id,
+    title: n.id,
+    status: n.status === 'done' || n.status === 'skipped' ? 'completed'
+      : n.status === 'run' ? 'in_progress'
+        : n.status === 'planned' ? 'planned'
+          : 'pending',
+    start: n.started_at,
+    end: n.completed_at,
+  }));
+}

package/src/indexing/ingest/materials.js

@@ -0,0 +1,210 @@
+/**
+ * Material intake for codebaseindex.ingest — paths pasted/dropped into the CLI.
+ * Handles archives (tar/zip), sites/builds, HTML, images, GLB, and mixed trees.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+const ARCHIVE_EXT = new Set(['.zip', '.tar', '.tgz', '.gz', '.tar.gz', '.tbz2', '.tar.bz2']);
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.bmp', '.avif']);
+const MODEL_3D_EXT = new Set(['.glb', '.gltf', '.obj', '.fbx', '.stl', '.usdz']);
+const DOC_EXT = new Set(['.html', '.htm', '.md', '.txt', '.css', '.scss', '.json', '.xml', '.csv']);
+const CODE_EXT = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.kt',
+  '.swift', '.c', '.h', '.cpp', '.cc', '.cs', '.rb', '.php', '.sql', '.sh', '.bash',
+  '.zsh', '.yaml', '.yml', '.toml', '.vue', '.svelte',
+]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function extOf(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith('.tar.gz')) return '.tar.gz';
+  if (lower.endsWith('.tar.bz2')) return '.tar.bz2';
+  return path.extname(lower);
+}
+
+/**
+ * Parse pasted CLI text into filesystem paths (one per line / whitespace-separated quoted).
+ * Terminal drag-drop typically pastes absolute paths; multi-line paste is supported.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parsePastedPaths(text) {
+  const raw = clean(text);
+  if (!raw) return [];
+  const paths = [];
+  const re = /"([^"]+)"|'([^']+)'|(`([^`]+)`)|(\S+)/g;
+  let match;
+  while ((match = re.exec(raw))) {
+    const candidate = match[1] || match[2] || match[4] || match[5];
+    if (!candidate || candidate.startsWith('-')) continue;
+    paths.push(candidate.replace(/\\ /g, ' '));
+  }
+  return [...new Set(paths)];
+}
+
+/**
+ * @param {string} filePath
+ */
+export function classifyMaterial(filePath) {
+  const resolved = path.resolve(filePath);
+  const ext = extOf(resolved);
+  const exists = fs.existsSync(resolved);
+  const stat = exists ? fs.statSync(resolved) : null;
+  let kind = 'unknown';
+  if (stat?.isDirectory()) kind = 'directory';
+  else if (ARCHIVE_EXT.has(ext) || resolved.toLowerCase().endsWith('.tar.gz')) kind = 'archive';
+  else if (IMAGE_EXT.has(ext)) kind = 'image';
+  else if (MODEL_3D_EXT.has(ext)) kind = 'model3d';
+  else if (DOC_EXT.has(ext)) kind = 'document';
+  else if (CODE_EXT.has(ext)) kind = 'code';
+  else if (stat?.isFile()) kind = 'file';
+  return {
+    path: resolved,
+    exists,
+    kind,
+    ext,
+    bytes: stat?.isFile() ? stat.size : null,
+    sha256: stat?.isFile() && stat.size <= 32 * 1024 * 1024 ? hashFile(resolved) : null,
+  };
+}
+
+function hashFile(filePath) {
+  try {
+    return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+function hasBin(name) {
+  const result = spawnSync(name, ['--help'], { stdio: 'ignore' });
+  // Some tools exit non-zero on --help; presence of spawn failure matters more.
+  return result.error == null;
+}
+
+/**
+ * Extract archive into destDir. Uses host tar/unzip (no extra npm deps).
+ * @param {string} archivePath
+ * @param {string} destDir
+ */
+export function extractArchive(archivePath, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const lower = archivePath.toLowerCase();
+  if (lower.endsWith('.zip')) {
+    if (!hasBin('unzip')) throw new Error('unzip_unavailable: install unzip to extract .zip materials');
+    execFileSync('unzip', ['-q', '-o', archivePath, '-d', destDir], { stdio: ['ignore', 'pipe', 'pipe'] });
+    return { tool: 'unzip', dest: destDir };
+  }
+  if (lower.endsWith('.tar') || lower.endsWith('.tar.gz') || lower.endsWith('.tgz')
+    || lower.endsWith('.tar.bz2') || lower.endsWith('.tbz2') || lower.endsWith('.gz')) {
+    if (!hasBin('tar')) throw new Error('tar_unavailable: install tar to extract archive materials');
+    execFileSync('tar', ['-xf', archivePath, '-C', destDir], { stdio: ['ignore', 'pipe', 'pipe'] });
+    return { tool: 'tar', dest: destDir };
+  }
+  throw new Error(`unsupported_archive:${path.basename(archivePath)}`);
+}
+
+/**
+ * Stage pasted/dropped materials under `.agentsam/ingest/<id>/`.
+ * Archives are extracted; files/dirs are copied or linked by relative include paths.
+ *
+ * @param {{ root: string, materials: string[], ingestId?: string }} opts
+ */
+export function stageMaterials(opts) {
+  const root = path.resolve(opts.root);
+  const ingestId = opts.ingestId || `ing_${randomUUID().replace(/-/g, '').slice(0, 12)}`;
+  const stageRoot = path.join(root, '.agentsam', 'ingest', ingestId);
+  fs.mkdirSync(stageRoot, { recursive: true });
+
+  /** @type {object[]} */
+  const items = [];
+  /** @type {string[]} */
+  const include = [];
+  /** @type {object[]} */
+  const assets = [];
+
+  for (const raw of opts.materials) {
+    const classified = classifyMaterial(raw);
+    if (!classified.exists) {
+      items.push({ ...classified, status: 'missing' });
+      continue;
+    }
+
+    if (classified.kind === 'archive') {
+      const dest = path.join(stageRoot, 'archives', path.basename(classified.path, classified.ext) || 'archive');
+      fs.mkdirSync(dest, { recursive: true });
+      const extracted = extractArchive(classified.path, dest);
+      const rel = path.relative(root, dest);
+      include.push(rel);
+      items.push({ ...classified, status: 'extracted', stage: dest, extract: extracted });
+      continue;
+    }
+
+    if (classified.kind === 'directory') {
+      const relInside = classified.path.startsWith(`${root}${path.sep}`) || classified.path === root
+        ? path.relative(root, classified.path) || '.'
+        : null;
+      if (relInside != null) {
+        include.push(relInside === '' ? '.' : relInside);
+        items.push({ ...classified, status: 'included', include: relInside || '.' });
+      } else {
+        const dest = path.join(stageRoot, 'trees', path.basename(classified.path) || 'tree');
+        copyTree(classified.path, dest);
+        const rel = path.relative(root, dest);
+        include.push(rel);
+        items.push({ ...classified, status: 'copied', stage: dest });
+      }
+      continue;
+    }
+
+    // Single file
+    const destDir = path.join(stageRoot, classified.kind === 'image' ? 'images'
+      : classified.kind === 'model3d' ? 'models3d'
+        : classified.kind === 'document' ? 'documents'
+          : 'files');
+    fs.mkdirSync(destDir, { recursive: true });
+    const dest = path.join(destDir, path.basename(classified.path));
+    fs.copyFileSync(classified.path, dest);
+    const rel = path.relative(root, dest);
+    include.push(path.dirname(rel));
+    assets.push({
+      kind: classified.kind,
+      path: rel,
+      bytes: classified.bytes,
+      sha256: classified.sha256,
+      ext: classified.ext,
+    });
+    items.push({ ...classified, status: 'staged', stage: dest, include: path.dirname(rel) });
+  }
+
+  const uniqueInclude = [...new Set(include.map((p) => p.replace(/\\/g, '/').replace(/\/$/, '') || '.'))].sort();
+  const manifest = {
+    schema: 'agentsam.ingest.materials.v1',
+    ingest_id: ingestId,
+    staged_at: new Date().toISOString(),
+    stage_root: path.relative(root, stageRoot),
+    items,
+    assets,
+    include: uniqueInclude,
+  };
+  fs.writeFileSync(path.join(stageRoot, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+function copyTree(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.agentsam') continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyTree(from, to);
+    else if (entry.isFile()) fs.copyFileSync(from, to);
+  }
+}

package/src/knowledge/config.js

@@ -31,31 +31,39 @@ export function validateConfig(input) {
     if (!object || typeof object !== 'object' || Array.isArray(object)) throw new Error(`${label} must be an object.`);
     for (const key of Object.keys(object)) if (!keys.includes(key)) throw new Error(`Unknown ${label} field: ${key}`);
   };
-  allowed(c, ['version', 'repository_id', 'workspace_id', 'scope', 'chunking', 'embedding', 'storage'], 'configuration');
+  allowed(c, ['version', 'repository_id', 'project_key', 'workspace_id', 'scope', 'chunking', 'embedding', 'storage', 'lane'], 'configuration');
   allowed(c.scope, ['name', 'include', 'exclude'], 'scope');
   allowed(c.chunking, ['max_chars'], 'chunking');
   allowed(c.embedding, ['provider', 'model', 'revision', 'dimensions', 'parameters'], 'embedding');
   allowed(c.storage, ['driver', 'connection_env'], 'storage');
-  if (c.version !== 1) throw new Error('Unsupported knowledge configuration version.');
+  if (c.lane != null) allowed(c.lane, ['id', 'backend', 'resource', 'binding', 'index', 'metric'], 'lane');
+  if (![1, 2].includes(c.version)) throw new Error('Unsupported knowledge configuration version.');
   if (typeof c.repository_id !== 'string' || !c.repository_id.trim()) throw new Error('repository_id is required.');
+  if (c.project_key != null && (typeof c.project_key !== 'string' || !c.project_key.trim())) throw new Error('project_key must be a non-empty string when present.');
   if (c.workspace_id != null && (typeof c.workspace_id !== 'string' || !c.workspace_id.trim())) throw new Error('workspace_id must be a non-empty string when present.');
   if (typeof c.scope?.name !== 'string' || !c.scope.name.trim() || !Array.isArray(c.scope.include) || !c.scope.include.length) throw new Error('A named scope with at least one include path is required.');
   c.scope.include = [...new Set(c.scope.include.map(relativeSelection))].sort();
   c.scope.exclude = [...new Set((c.scope.exclude || []).map(relativeSelection))].sort();
   if (!Number.isInteger(c.chunking?.max_chars) || c.chunking.max_chars < 256 || c.chunking.max_chars > 12000) throw new Error('chunking.max_chars must be 256..12000.');
   const e = c.embedding;
-  if (!e || ['provider', 'model', 'revision'].some(k => typeof e[k] !== 'string' || !e[k].trim()) || !Number.isInteger(e.dimensions) || e.dimensions < 1 || e.dimensions > 3072) throw new Error('Embedding provider, model, revision and dimensions (1..3072) are required.');
+  const disabledEmbedding = e?.provider === 'none' && e?.model === 'none' && e?.dimensions === 0;
+  if (!e || ['provider', 'model', 'revision'].some(k => typeof e[k] !== 'string' || !e[k].trim()) || !Number.isInteger(e.dimensions) || (!disabledEmbedding && (e.dimensions < 1 || e.dimensions > 3072))) throw new Error('Embedding provider, model, revision and dimensions (1..3072, or explicit none/0) are required.');
   if (!e.parameters || typeof e.parameters !== 'object' || Array.isArray(e.parameters)) throw new Error('Embedding parameters must be an object.');
   if (!['sqlite', 'postgres'].includes(c.storage?.driver)) throw new Error('storage.driver must be sqlite or postgres.');
   if (c.storage.driver === 'postgres' && !/^[A-Z_][A-Z0-9_]*$/.test(c.storage.connection_env || '')) throw new Error('Postgres requires a connection_env name, never a connection string in config.');
+  if (c.lane) {
+    if (typeof c.lane.id !== 'string' || !c.lane.id.trim() || !['local_exact', 'postgres_pgvector', 'supabase_pgvector', 'cloudflare_vectorize'].includes(c.lane.backend)) throw new Error('Knowledge lane requires an explicit supported backend.');
+    if (c.lane.backend === 'cloudflare_vectorize' && (!c.lane.binding || !c.lane.index)) throw new Error('Cloudflare Vectorize lanes require explicit binding and index.');
+  }
   return c;
 }
 export function defaultConfig({ include = ['.'], exclude = [], scope = 'default', target = 'local', dimensions = 768, repositoryId = '' } = {}) {
   if (!['local', 'production'].includes(target)) throw new Error('target must be local or production.');
-  return validateConfig({ version: 1, repository_id: String(repositoryId || '').trim() || randomUUID(),
+  return validateConfig({ version: 2, repository_id: String(repositoryId || '').trim() || randomUUID(), project_key: String(repositoryId || '').trim() || undefined,
     scope: { name: scope, include, exclude }, chunking: { max_chars: 4000 },
     embedding: { provider: 'gemini', model: 'gemini-embedding-2', revision: '1', dimensions, parameters: { task: 'code retrieval' } },
-    storage: target === 'local' ? { driver: 'sqlite' } : { driver: 'postgres', connection_env: 'AGENTSAM_DATABASE_URL' } });
+    storage: target === 'local' ? { driver: 'sqlite' } : { driver: 'postgres', connection_env: 'AGENTSAM_DATABASE_URL' },
+    lane: { id: `${scope}-default`, backend: target === 'local' ? 'local_exact' : 'postgres_pgvector', resource: null, binding: null, index: null, metric: 'cosine' } });
 }
 export function readConfig(root) { return validateConfig(JSON.parse(fs.readFileSync(path.join(root, CONFIG_PATH), 'utf8'))); }
 export function initRepository(root, options = {}) {

package/src/knowledge/engine.js

@@ -3,6 +3,7 @@ import { validateConfig, fingerprint, scopeKey, cacheNamespace, gitEvidence } fr
 import { PARSER, inventory, readSource, parseSource } from './source.js';
 import { createContextPack } from './context-pack.js';
 import { normalizeResultPolicy } from '../context/result-policy.js';
+import { buildMerkleTree } from '../../packages/agentsam-repository/src/merkle/index.js';
 
 export const embeddingProfileId = profile => fingerprint({ ...profile, input_format: 'agentsam-code-content:1' });
 export function validateVector(vector, dimensions) {
@@ -14,20 +15,27 @@ function changes(before = [], after = []) {
   return { added: after.filter(f => !old.has(f.path)).map(f => f.path), changed: after.filter(f => old.has(f.path) && old.get(f.path) !== f.hash).map(f => f.path), removed: before.filter(f => !now.has(f.path)).map(f => f.path) };
 }
 /** Planning never persists, calls an embedding provider, or changes active state. */
-export async function planIndex({ root, config: input, store, embed = false }) {
+export async function planIndex({ root, config: input, store, embed = false, limits = null }) {
   const config = validateConfig(input), scope = scopeKey(config), namespace = cacheNamespace(config);
+  if (embed && config.embedding.provider === 'none') throw new Error('Embedding is explicitly disabled for this knowledge profile. Configure a provider before --embed.');
+  const maxFiles = limits?.maxFiles == null ? Infinity : Number(limits.maxFiles);
+  const maxChunks = limits?.maxChunks == null ? Infinity : Number(limits.maxChunks);
+  if ((maxFiles !== Infinity && (!Number.isInteger(maxFiles) || maxFiles < 1)) || (maxChunks !== Infinity && (!Number.isInteger(maxChunks) || maxChunks < 1))) throw new Error('Index limits must be positive integers.');
   const previous = await store?.active(scope), profileId = embed ? embeddingProfileId(config.embedding) : null;
   const files = [], chunks = [], symbols = [], edges = [], parseWrites = [], skipped = [];
   const parseProfile = fingerprint([PARSER, config.chunking]);
   let parsedFiles = 0;
-  for (const file of inventory(root, config.scope)) {
+  for (const file of inventory(root, config.scope).slice(0, maxFiles)) {
     const source = readSource(root, file);
     if (!source) { skipped.push(file); continue; }
     const key = `${namespace}:parse:${fingerprint([source.hash, file.split('.').pop(), parseProfile])}`;
     let parsed = await store?.cacheGet(key);
     if (!parsed) { parsed = parseSource(file, source.content, config.chunking.max_chars); parseWrites.push([key, parsed]); parsedFiles++; }
     files.push({ path: file, hash: source.hash, bytes: source.bytes, parser: parsed.parser });
-    for (const [ordinal, c] of parsed.chunks.entries()) chunks.push({ ...c, path: file, ordinal, id: fingerprint([file, ordinal, c.content_hash]), embedding_key: embed ? `${namespace}:vector:${profileId}:${c.content_hash}` : null });
+    for (const [ordinal, c] of parsed.chunks.entries()) {
+      if (chunks.length >= maxChunks) break;
+      chunks.push({ ...c, path: file, ordinal, id: fingerprint([file, ordinal, c.content_hash]), embedding_key: embed ? `${namespace}:vector:${profileId}:${c.content_hash}` : null });
+    }
     symbols.push(...parsed.symbols.map(s => ({ ...s, path: file })));
     edges.push(...parsed.edges.map(e => ({ ...e, path: file })));
   }
@@ -36,19 +44,25 @@ export async function planIndex({ root, config: input, store, embed = false }) {
     if (!missing.has(chunk.embedding_key) && !(await store?.cacheGet(chunk.embedding_key))) missing.set(chunk.embedding_key, chunk.content);
   }
   const sourceHash = fingerprint(files.map(f => [f.path, f.hash]));
-  const configHash = fingerprint([config.scope, config.chunking, PARSER, profileId]);
+  const configHash = fingerprint([config.scope, config.chunking, PARSER, profileId, Number.isFinite(maxFiles) ? maxFiles : null, Number.isFinite(maxChunks) ? maxChunks : null]);
+  let merkle = null;
+  try { merkle = await buildMerkleTree(root, { semantic: true }); } catch { merkle = null; }
+  const previousMerkle = previous?.receipt?.merkle_root || null;
+  const changedMerklePaths = merkle && previousMerkle !== merkle.rootHash ? files.filter(file => !previous?.files?.some(before => before.path === file.path && before.hash === file.hash)).map(file => file.path) : [];
   const noChange = previous?.source_hash === sourceHash && previous?.config_hash === configHash && !missing.size;
   return { root, config, previous, files, chunks, symbols, edges, parseWrites, missing,
     receipt: { scope: config.scope, files: files.length, chunks: chunks.length, symbols: symbols.length, edges: edges.length,
       parsed_files: parsedFiles, embedding_inputs: missing.size, embedding_characters: [...missing.values()].reduce((n, s) => n + s.length, 0),
       estimated_tokens: Math.ceil([...missing.values()].reduce((n, s) => n + s.length + 24, 0) / 4), token_estimate_method: 'characters / 4; not billable usage',
-      profile_id: profileId, skipped, changes: changes(previous?.files, files), no_change: Boolean(noChange), source_hash: sourceHash, config_hash: configHash } };
+      profile_id: profileId, skipped, changes: changes(previous?.files, files), no_change: Boolean(noChange), source_hash: sourceHash, config_hash: configHash,
+      merkle_root: merkle?.rootHash || null, semantic_metadata_root: merkle?.semantic?.rootHash || null, merkle_changed_paths: changedMerklePaths,
+      limits: Number.isFinite(maxFiles) || Number.isFinite(maxChunks) ? { max_files: maxFiles, max_chunks: maxChunks } : null } };
 }
 
-export async function runIndex({ root, config, store, embedder, embed = false, maxInputs = 100, maxCharacters = 200000 }) {
+export async function runIndex({ root, config, store, embedder, embed = false, maxInputs = 100, maxCharacters = 200000, limits = null }) {
   if (!store) throw new Error('A writable knowledge store is required.');
   if (!Number.isInteger(maxInputs) || maxInputs < 0 || !Number.isInteger(maxCharacters) || maxCharacters < 0) throw new Error('Embedding budgets must be nonnegative integers.');
-  const plan = await planIndex({ root, config, store, embed });
+  const plan = await planIndex({ root, config, store, embed, limits });
   const { receipt } = plan;
   if (receipt.no_change) return { ...receipt, generation_id: plan.previous.id, published: false };
   if (receipt.embedding_inputs > maxInputs || receipt.embedding_characters > maxCharacters) throw new Error(`Embedding budget exceeded: ${receipt.embedding_inputs} unique inputs / ${receipt.embedding_characters} characters. Review index plan before raising limits.`);
@@ -64,7 +78,8 @@ export async function runIndex({ root, config, store, embedder, embed = false, m
   }
   // A generation describes one coherent source snapshot. Never publish after a mid-run edit.
   const check = [];
-  for (const file of inventory(root, plan.config.scope)) { const source = readSource(root, file); if (source) check.push([file, source.hash]); }
+  const checkFiles = inventory(root, plan.config.scope).slice(0, limits?.maxFiles == null ? Infinity : limits.maxFiles);
+  for (const file of checkFiles) { const source = readSource(root, file); if (source) check.push([file, source.hash]); }
   if (fingerprint(check) !== receipt.source_hash) throw new Error('Repository changed while indexing; cached work retained, active generation unchanged. Rerun.');
   const generation = { id: randomUUID(), scope_key: scopeKey(plan.config), created_at: new Date().toISOString(),
     source_hash: receipt.source_hash, config_hash: receipt.config_hash, config: plan.config, profile_id: receipt.profile_id,

package/src/knowledge/index.js

@@ -8,3 +8,4 @@ export { openSqliteStore } from './stores/sqlite.js';
 export { createPostgresStore, openPostgresStore, postgresSchema } from './stores/postgres.js';
 export { createGeminiEmbedder } from './providers/gemini.js';
 export { compareObservations } from './evolution.js';
+export { normalizeRetrievalLane, selectProjectRetrievalLanes, loadProjectRetrievalLanes } from './lane-registry.js';

package/src/knowledge/lane-registry.js

@@ -0,0 +1,46 @@
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function json(value, fallback = {}) { try { return JSON.parse(String(value || '')); } catch { return fallback; } }
+
+export function normalizeRetrievalLane(row = {}) {
+  return Object.freeze({
+    id: clean(row.id),
+    account_id: clean(row.account_id) || null,
+    repository_id: clean(row.repository_id) || null,
+    database_id: clean(row.database_id) || null,
+    backend_kind: clean(row.backend_kind || 'pgvector'),
+    provider_key: clean(row.provider_key) || null,
+    resource_id: clean(row.resource_id) || null,
+    binding_name: clean(row.binding_name) || null,
+    index_name: clean(row.index_name) || null,
+    // Namespace is provider/project-owned. Never silently force the shared
+    // `agentsam` schema onto a new application's retrieval lane.
+    schema_name: clean(row.schema_name) || null,
+    table_name: clean(row.table_name),
+    purpose: clean(row.purpose),
+    dimensions: Number(row.dimensions) || null,
+    metric: clean(row.metric || 'cosine'),
+    embedding_model: clean(row.embedding_model) || null,
+    metadata: json(row.metadata_json, {}),
+    is_active: Number(row.is_active) === 1,
+  });
+}
+
+/** Project selection is explicit; no global preferred vector store exists. */
+export function selectProjectRetrievalLanes(rows, { accountId, repositoryId, purpose } = {}) {
+  const account = clean(accountId);
+  const repository = clean(repositoryId);
+  if (!account || !repository) throw new Error('project_retrieval_identity_required');
+  return (Array.isArray(rows) ? rows : [])
+    .map(normalizeRetrievalLane)
+    .filter((lane) => lane.is_active && lane.account_id === account && lane.repository_id === repository && (!purpose || lane.purpose === purpose));
+}
+
+export async function loadProjectRetrievalLanes(db, identity = {}) {
+  if (!db?.prepare) throw new TypeError('database_required');
+  const result = await db.prepare(`
+    SELECT * FROM agentsam_pgvector_lane_registry
+    WHERE account_id = ? AND repository_id = ? AND is_active = 1
+    ORDER BY purpose, id
+  `).bind(clean(identity.accountId), clean(identity.repositoryId)).all();
+  return selectProjectRetrievalLanes(result?.results || [], identity);
+}

package/src/knowledge/providers/gemini.js

@@ -1,12 +1,20 @@
+import { AgentSamError, classifyGeminiFailure } from '../../errors/index.js';
+
 /** Gemini Embedding 2 adapter; profile is supplied per job, never read globally. */
 export function createGeminiEmbedder({ apiKey, fetchImpl = globalThis.fetch, sleep = ms => new Promise(r => setTimeout(r, ms)), maxAttempts = 3, timeoutMs = 30000 } = {}) {
-  if (!apiKey) throw new Error('GEMINI_API_KEY is required only for embedding/search with --semantic.');
-  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 5) throw new Error('maxAttempts must be 1..5.');
+  if (!apiKey) throw new AgentSamError(classifyGeminiFailure({
+    credential_state: 'missing',
+    message: 'GEMINI_API_KEY is required only for embedding/search with --semantic.',
+  }, { domain: 'knowledge', tool: 'gemini', stage: 'embedding' }));
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 5) throw new AgentSamError(classifyGeminiFailure({
+    status: 400,
+    message: 'maxAttempts must be 1..5.',
+  }, { domain: 'knowledge', tool: 'gemini', stage: 'configuration', request_origin: 'user' }));
   return {
     validate(profile) {
-      if (profile.provider !== 'gemini' || profile.model !== 'gemini-embedding-2') throw new Error('This adapter supports gemini-embedding-2; inject a different adapter for other models.');
-      if (profile.dimensions < 128 || profile.dimensions > 3072) throw new Error('Gemini Embedding 2 dimensions must be 128..3072.');
-      if (Object.keys(profile.parameters).some(k => k !== 'task') || !['code retrieval', 'search result', 'question answering'].includes(profile.parameters.task)) throw new Error('Unsupported Gemini embedding parameters.');
+      if (profile.provider !== 'gemini' || profile.model !== 'gemini-embedding-2') throw new AgentSamError(classifyGeminiFailure({ status: 400, message: 'This adapter supports gemini-embedding-2; inject a different adapter for other models.' }, { domain: 'knowledge', tool: 'gemini', stage: 'configuration', request_origin: 'user' }));
+      if (profile.dimensions < 128 || profile.dimensions > 3072) throw new AgentSamError(classifyGeminiFailure({ status: 400, message: 'Gemini Embedding 2 dimensions must be 128..3072.' }, { domain: 'knowledge', tool: 'gemini', stage: 'configuration', request_origin: 'user' }));
+      if (Object.keys(profile.parameters).some(k => k !== 'task') || !['code retrieval', 'search result', 'question answering'].includes(profile.parameters.task)) throw new AgentSamError(classifyGeminiFailure({ status: 400, message: 'Unsupported Gemini embedding parameters.' }, { domain: 'knowledge', tool: 'gemini', stage: 'configuration', request_origin: 'user' }));
     },
     async embed(text, profile, { kind = 'document' } = {}) {
       this.validate(profile);
@@ -19,10 +27,42 @@ export function createGeminiEmbedder({ apiKey, fetchImpl = globalThis.fetch, sle
             method: 'POST', headers: { 'Content-Type': 'application/json', 'x-goog-api-key': apiKey }, signal: AbortSignal.timeout(timeoutMs),
             body: JSON.stringify({ model: `models/${profile.model}`, content: { parts: [{ text: input }] }, outputDimensionality: profile.dimensions }),
           });
-        } catch { if (attempt + 1 === maxAttempts) throw new Error('Gemini embedding request failed or timed out.'); }
+        } catch (cause) {
+          if (attempt + 1 === maxAttempts) {
+            throw new AgentSamError(classifyGeminiFailure({
+              status: 504,
+              status_name: 'UNAVAILABLE',
+              message: 'Gemini embedding request failed or timed out.',
+              exception_type: cause?.name,
+              stack: cause?.stack,
+            }, { domain: 'knowledge', tool: 'gemini', stage: 'embedding', reason: 'transport_timeout' }), { cause });
+          }
+        }
         if (response?.ok) return (await response.json()).embedding?.values;
-        if (response && ![408, 429, 500, 502, 503, 504].includes(response.status)) throw new Error(`Gemini embedding failed (HTTP ${response.status}).`);
-        if (attempt + 1 === maxAttempts) throw new Error(`Gemini embedding retry limit reached${response ? ` (HTTP ${response.status})` : ''}.`);
+        let providerBody = null;
+        if (response) {
+          try { providerBody = await response.clone().json(); } catch { providerBody = null; }
+        }
+        if (response && ![408, 429, 500, 502, 503, 504].includes(response.status)) {
+          throw new AgentSamError(classifyGeminiFailure({
+            status: response.status,
+            status_name: providerBody?.error?.status,
+            code: providerBody?.error?.code,
+            message: providerBody?.error?.message || `Gemini embedding failed (HTTP ${response.status}).`,
+            headers: response.headers,
+            body: providerBody,
+          }, { domain: 'knowledge', tool: 'gemini', stage: 'embedding', request_origin: 'agentsam' }));
+        }
+        if (attempt + 1 === maxAttempts) {
+          throw new AgentSamError(classifyGeminiFailure({
+            status: response?.status || 503,
+            status_name: providerBody?.error?.status,
+            code: providerBody?.error?.code,
+            message: providerBody?.error?.message || `Gemini embedding retry limit reached${response ? ` (HTTP ${response.status})` : ''}.`,
+            headers: response?.headers,
+            body: providerBody,
+          }, { domain: 'knowledge', tool: 'gemini', stage: 'embedding' }));
+        }
         await response?.body?.cancel();
         await sleep(Math.min(10000, 500 * 2 ** attempt + Math.floor(Math.random() * 250)));
       }