@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/lib/merkle/semantic.js

@@ -0,0 +1,359 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import ts from 'typescript';
+import { comparePaths, fileHasher } from './hash.js';
+import { FILEMETA_FORMAT, FILEMETA_VERSION, metadataRoot } from './filemeta.js';
+const MAX_AST_BYTES = 2 * 1024 * 1024;
+
+const LANGUAGE_BY_EXTENSION = Object.freeze({
+  '.c': 'c', '.cc': 'cpp', '.cpp': 'cpp', '.cxx': 'cpp', '.css': 'css', '.go': 'go',
+  '.h': 'c', '.hpp': 'cpp', '.html': 'html', '.java': 'java', '.js': 'javascript',
+  '.jsx': 'javascript', '.json': 'json', '.md': 'markdown', '.mjs': 'javascript',
+  '.cjs': 'javascript', '.py': 'python', '.rs': 'rust', '.scss': 'scss', '.sql': 'sql',
+  '.ts': 'typescript', '.tsx': 'typescript', '.yaml': 'yaml', '.yml': 'yaml',
+});
+const AST_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
+const ASSET_EXTENSIONS = new Set([
+  '.avif', '.eot', '.gif', '.ico', '.jpeg', '.jpg', '.mp3', '.mp4', '.ogg', '.otf', '.pdf',
+  '.png', '.svg', '.ttf', '.wav', '.webm', '.webp', '.woff', '.woff2',
+]);
+const CONFIG_NAMES = new Set([
+  'package.json', 'tsconfig.json', 'wrangler.json', 'wrangler.jsonc', 'wrangler.toml',
+  'vite.config.js', 'vite.config.mjs', 'vite.config.ts', 'eslint.config.js', '.gitignore',
+]);
+
+function systemName(value) {
+  return String(value || '')
+    .replace(/^@[^/]+\//, '')
+    .replace(/^agentsam-sdk-/, '')
+    .replace(/^agentsam-/, '')
+    .replace(/[^a-zA-Z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase() || null;
+}
+
+function extensionOf(relative) {
+  const lower = relative.toLowerCase();
+  if (lower.endsWith('.d.ts')) return '.ts';
+  return path.posix.extname(lower);
+}
+
+function nearestPackage(relative, packages) {
+  let best = null;
+  for (const pkg of packages) {
+    if (!pkg.root || relative === pkg.root || relative.startsWith(pkg.root + '/')) {
+      if (!best || pkg.root.length > best.root.length) best = pkg;
+    }
+  }
+  return best;
+}
+
+function inferLayer(relative, packageRoot) {
+  const local = packageRoot && relative.startsWith(packageRoot + '/') ? relative.slice(packageRoot.length + 1) : relative;
+  const parts = local.split('/');
+  for (const name of ['frontend', 'backend', 'shared']) if (parts.includes(name)) return name;
+  const src = parts.indexOf('src');
+  if (src >= 0 && parts[src + 1] && parts[src + 1].includes('.') === false) return parts[src + 1];
+  for (const name of ['test', 'tests', 'docs', 'scripts', 'protocol', 'templates', 'migrations']) if (parts[0] === name || parts.includes(name)) return name === 'tests' ? 'test' : name;
+  return parts.length > 1 ? parts[0] : 'root';
+}
+
+function inferCategory(relative) {
+  const filename = path.posix.basename(relative);
+  const ext = path.posix.extname(filename);
+  let stem = ext ? filename.slice(0, -ext.length) : filename;
+  if (stem === 'index' || stem === 'README') stem = path.posix.basename(path.posix.dirname(relative));
+  return stem.toLowerCase().replace(/[^a-z0-9_-]+/g, '-') || 'root';
+}
+
+function inferKind(relative, language) {
+  const lower = relative.toLowerCase();
+  const ext = extensionOf(relative);
+  if (/(^|\/)(__tests__|tests?|fixtures?)(\/|$)/.test(lower) || /\.(test|spec)\.[^.]+$/.test(lower)) return 'test';
+  if (ASSET_EXTENSIONS.has(ext)) return 'asset';
+  if (ext === '.md' || /(^|\/)docs?(\/|$)/.test(lower) || path.posix.basename(relative).toLowerCase().startsWith('readme')) return 'documentation';
+  if (ext === '.sql' || /(^|\/)migrations?(\/|$)/.test(lower)) return 'migration';
+  if (CONFIG_NAMES.has(path.posix.basename(relative)) || /(^|\/)(config|configs)(\/|$)/.test(lower)) return 'config';
+  if (language && !['json', 'yaml'].includes(language)) return 'source';
+  if (language) return 'data';
+  return 'file';
+}
+
+function inferRole(relative, layer, kind) {
+  const lower = relative.toLowerCase();
+  if (kind === 'test') return 'test';
+  if (kind === 'documentation') return 'documentation';
+  if (kind === 'migration') return 'database';
+  if (kind === 'config') return 'configuration';
+  if (/(^|\/)contracts?(\/|$)/.test(lower)) return 'contract';
+  if (/(^|\/)adapters?(\/|$)/.test(lower)) return 'adapter';
+  if (/(^|\/)providers?(\/|$)/.test(lower)) return 'provider';
+  if (/(^|\/)(routes?|api|server)(\/|$)/.test(lower) || ['routes', 'api', 'server'].includes(layer)) return 'transport';
+  if (layer === 'frontend') return 'ui';
+  if (layer === 'core') return 'business-logic';
+  if (layer === 'scripts') return 'tooling';
+  return kind === 'source' ? 'runtime' : kind;
+}
+
+function inferExecutionDomain(relative, layer, role, kind) {
+  const lower = relative.toLowerCase();
+  const parts = lower.split('/');
+  const filename = parts.at(-1) || '';
+  if (kind === 'test') return 'test';
+  if (/^(?:vite|vitest|eslint|tailwind|postcss|playwright|next|nuxt|astro)\.config\.[cm]?[jt]s$/.test(filename)) return 'tooling';
+  if (/\.gen\.[cm]?[jt]sx?$/.test(filename) || filename.endsWith('.generated.ts') || filename.endsWith('.generated.js')) return 'framework';
+  if (/\.server\.[cm]?[jt]sx?$/.test(filename) || /^(server|worker)\.[cm]?[jt]s$/.test(filename) || filename.includes('server-only')) return 'server';
+  if (parts.includes('backend') || parts.includes('worker') || /(^|\/)routes?\/api(\/|$)/.test(lower) || /(^|\/)api(\/|$)/.test(lower)) return 'server';
+  if (/\.client\.[cm]?[jt]sx?$/.test(filename)) return 'browser';
+  if (parts.includes('shared') || layer === 'shared' || role === 'contract') return 'shared';
+  if (parts.includes('frontend') || layer === 'frontend') return 'browser';
+  if (layer === 'backend' || layer === 'server' || layer === 'api') return 'server';
+  return 'unknown';
+}
+
+function globRegex(glob) {
+  let source = '^';
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    if (char === '*') {
+      if (glob[i + 1] === '*') { source += '.*'; i++; }
+      else source += '[^/]*';
+    } else if (char === '?') source += '[^/]';
+    else source += /[\\^$.*+?()[\]{}|]/.test(char) ? `\\${char}` : char;
+  }
+  return new RegExp(source + '$');
+}
+
+function packageRule(localPath, pkg) {
+  const rules = Array.isArray(pkg?.agentsam?.classify) ? pkg.agentsam.classify : [];
+  const out = {};
+  const tags = new Set();
+  for (const rule of rules) {
+    if (!rule || typeof rule.glob !== 'string' || !globRegex(rule.glob).test(localPath)) continue;
+    for (const key of ['system', 'category', 'layer', 'kind', 'language', 'role', 'execution_domain']) if (typeof rule[key] === 'string' && rule[key]) out[key] = rule[key];
+    if (Array.isArray(rule.tags)) for (const tag of rule.tags) if (typeof tag === 'string' && tag) tags.add(tag);
+  }
+  if (tags.size) out.tags = [...tags].sort();
+  return out;
+}
+
+function scriptKind(ext) {
+  if (ext === '.tsx') return ts.ScriptKind.TSX;
+  if (ext === '.jsx') return ts.ScriptKind.JSX;
+  if (ext === '.ts') return ts.ScriptKind.TS;
+  return ts.ScriptKind.JS;
+}
+
+function declarationNames(node) {
+  const out = [];
+  const addBinding = (name) => {
+    if (!name) return;
+    if (ts.isIdentifier(name)) out.push(name.text);
+    else if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) for (const element of name.elements) if (ts.isBindingElement(element)) addBinding(element.name);
+  };
+  if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node)) && node.name) out.push(node.name.text);
+  else if (ts.isVariableStatement(node)) for (const declaration of node.declarationList.declarations) addBinding(declaration.name);
+  return out;
+}
+
+function astMetadata(relative, source) {
+  const ext = extensionOf(relative);
+  const file = ts.createSourceFile(relative, source, ts.ScriptTarget.Latest, true, scriptKind(ext));
+  const symbols = new Set();
+  const imports = new Set();
+  const envAccesses = new Set();
+  for (const statement of file.statements) {
+    for (const name of declarationNames(statement)) symbols.add(name);
+    if (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) {
+      const value = statement.moduleSpecifier;
+      if (value && ts.isStringLiteralLike(value)) imports.add(value.text);
+    }
+  }
+  const recordEnvAccess = (node) => {
+    if (!ts.isPropertyAccessExpression(node) && !ts.isElementAccessExpression(node)) return;
+    const text = node.getText(file);
+    let match = text.match(/^(process\.env|import\.meta\.env)\.([A-Za-z_][A-Za-z0-9_]*)$/);
+    if (!match) match = text.match(/^(process\.env|import\.meta\.env)\[['\"]([A-Za-z_][A-Za-z0-9_]*)['\"]\]$/);
+    if (match) envAccesses.add(`${match[1]}:${match[2]}`);
+  };
+  const visit = (node) => {
+    recordEnvAccess(node);
+    if (ts.isCallExpression(node) && node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0])) {
+      if (ts.isIdentifier(node.expression) && node.expression.text === 'require') imports.add(node.arguments[0].text);
+      else if (node.expression.kind === ts.SyntaxKind.ImportKeyword) imports.add(node.arguments[0].text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  const symbolList = [...symbols].sort();
+  const importList = [...imports].sort();
+  const envList = [...envAccesses].sort().map((value) => {
+    const split = value.indexOf(':');
+    return { source: value.slice(0, split), name: value.slice(split + 1) };
+  });
+  return {
+    symbols: symbolList,
+    imports: importList,
+    env_accesses: envList,
+    ast: {
+      indexed: true,
+      parser: 'typescript',
+      symbol_count: symbolList.length,
+      dependency_count: importList.length,
+      env_access_count: envList.length,
+      parse_error_count: Array.isArray(file.parseDiagnostics) ? file.parseDiagnostics.length : 0,
+    },
+  };
+}
+
+function resolveLocalImport(sourcePath, specifier, files) {
+  if (!specifier.startsWith('.')) return null;
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(sourcePath), specifier));
+  const candidates = [base];
+  const ext = path.posix.extname(base);
+  if (!ext) {
+    for (const suffix of ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json']) candidates.push(base + suffix);
+    for (const suffix of ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json']) candidates.push(path.posix.join(base, 'index' + suffix));
+  } else if (['.js', '.jsx', '.mjs', '.cjs'].includes(ext)) {
+    const stem = base.slice(0, -ext.length);
+    for (const suffix of ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']) candidates.push(stem + suffix);
+  }
+  return candidates.find((candidate) => files.has(candidate)) || null;
+}
+
+function attachResolvedImports(entries) {
+  const files = new Set(entries.filter((entry) => entry.type === 'file').map((entry) => entry.path));
+  for (const entry of entries) {
+    if (!Array.isArray(entry.imports) || !entry.imports.length) continue;
+    entry.resolved_imports = entry.imports.map((specifier) => {
+      const target = resolveLocalImport(entry.path, specifier, files);
+      return target ? { specifier, target } : { specifier };
+    });
+  }
+}
+
+async function readVerifiedFile(rootPath, entry) {
+  const filename = path.join(rootPath, ...entry.path.split('/'));
+  const before = await fs.lstat(filename, { bigint: true });
+  if (!before.isFile()) throw new Error(`Semantic index expected a file: ${entry.path}`);
+  if (before.size > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error(`File is too large: ${entry.path}`);
+  const buffer = await fs.readFile(filename);
+  const after = await fs.lstat(filename, { bigint: true });
+  if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs) {
+    throw new Error(`File changed while building semantic metadata: ${entry.path}`);
+  }
+  const hash = fileHasher();
+  hash.update(buffer);
+  const verified = 'sha256:' + hash.digest('hex');
+  if (verified !== entry.hash || buffer.length !== entry.size) throw new Error(`Merkle/semantic content mismatch: ${entry.path}`);
+  return { buffer, mode: Number(after.mode & 0o7777n) };
+}
+
+async function readPackages(rootPath, tree) {
+  const manifests = tree.entries.filter((entry) => entry.type === 'file' && path.posix.basename(entry.path) === 'package.json');
+  const packages = [];
+  for (const entry of manifests) {
+    const { buffer } = await readVerifiedFile(rootPath, entry);
+    let parsed = {};
+    try { parsed = JSON.parse(buffer.toString('utf8')); } catch { parsed = {}; }
+    const agentsam = parsed.agentsam && typeof parsed.agentsam === 'object' && !Array.isArray(parsed.agentsam) ? parsed.agentsam : {};
+    packages.push({
+      root: path.posix.dirname(entry.path) === '.' ? '' : path.posix.dirname(entry.path),
+      name: typeof parsed.name === 'string' ? parsed.name : null,
+      agentsam,
+    });
+  }
+  return packages.sort((a, b) => comparePaths(a.root, b.root));
+}
+
+function summarize(entries, packages) {
+  const bySystem = {};
+  const byLanguage = {};
+  const byExecutionDomain = {};
+  let astIndexed = 0;
+  for (const entry of entries) {
+    if (entry.system) bySystem[entry.system] = (bySystem[entry.system] || 0) + 1;
+    if (entry.language) byLanguage[entry.language] = (byLanguage[entry.language] || 0) + 1;
+    if (entry.execution_domain) byExecutionDomain[entry.execution_domain] = (byExecutionDomain[entry.execution_domain] || 0) + 1;
+    if (entry.ast?.indexed) astIndexed++;
+  }
+  return {
+    entries: entries.length,
+    files: entries.filter((entry) => entry.type === 'file').length,
+    symlinks: entries.filter((entry) => entry.type === 'symlink').length,
+    packages: packages.length,
+    ast_indexed: astIndexed,
+    by_system: Object.fromEntries(Object.entries(bySystem).sort()),
+    by_language: Object.fromEntries(Object.entries(byLanguage).sort()),
+    by_execution_domain: Object.fromEntries(Object.entries(byExecutionDomain).sort()),
+  };
+}
+
+export async function buildSemanticMetadata(rootPath, tree) {
+  const packages = await readPackages(rootPath, tree);
+  const classifier = {
+    format: FILEMETA_FORMAT,
+    version: FILEMETA_VERSION,
+    source: 'path+package+ast+execution-boundary',
+    trust_boundary: 'execution-domain-v1',
+    ast_parser: 'typescript',
+    ast_parser_version: ts.version,
+  };
+  const entries = [];
+  for (const contentEntry of tree.entries) {
+    if (contentEntry.type === 'directory') continue;
+    const pkg = nearestPackage(contentEntry.path, packages);
+    const localPath = pkg?.root && contentEntry.path.startsWith(pkg.root + '/') ? contentEntry.path.slice(pkg.root.length + 1) : contentEntry.path;
+    const ext = extensionOf(contentEntry.path);
+    const language = LANGUAGE_BY_EXTENSION[ext] || null;
+    const layer = inferLayer(contentEntry.path, pkg?.root || '');
+    const kind = contentEntry.type === 'symlink' ? 'symlink' : inferKind(contentEntry.path, language);
+    const structuralSystem = (contentEntry.path.startsWith('packages/') || contentEntry.path.startsWith('apps/')) ? contentEntry.path.split('/')[1] : null;
+    const baseSystem = pkg?.agentsam?.system || pkg?.name || structuralSystem || contentEntry.path.split('/')[0];
+    const explicit = packageRule(localPath, pkg);
+    const tags = new Set([...(Array.isArray(pkg?.agentsam?.tags) ? pkg.agentsam.tags : []), ...(explicit.tags || [])].filter((tag) => typeof tag === 'string' && tag));
+    let mode = contentEntry.mode;
+    let sourceBuffer = null;
+    if (contentEntry.type === 'file' && AST_EXTENSIONS.has(ext) && contentEntry.size <= MAX_AST_BYTES) {
+      const verified = await readVerifiedFile(rootPath, contentEntry);
+      if (mode != null && verified.mode !== mode) throw new Error(`File mode changed while building semantic metadata: ${contentEntry.path}`);
+      mode = verified.mode;
+      sourceBuffer = verified.buffer;
+    }
+    if (mode == null) {
+      const filename = path.join(rootPath, ...contentEntry.path.split('/'));
+      mode = Number((await fs.lstat(filename, { bigint: true })).mode & 0o7777n);
+    }
+    const record = {
+      path: contentEntry.path,
+      type: contentEntry.type,
+      ...(contentEntry.type === 'file' ? { size: contentEntry.size } : {}),
+      mode,
+      hash: contentEntry.hash,
+      ...(pkg?.name ? { package: pkg.name } : {}),
+      ...(pkg ? { package_root: pkg.root || '.' } : {}),
+      ...(pkg?.agentsam?.kind ? { package_kind: pkg.agentsam.kind } : {}),
+      system: explicit.system || systemName(baseSystem),
+      category: explicit.category || inferCategory(contentEntry.path),
+      layer: explicit.layer || layer,
+      kind: explicit.kind || kind,
+      ...(explicit.language || language ? { language: explicit.language || language } : {}),
+      role: explicit.role || inferRole(contentEntry.path, explicit.layer || layer, explicit.kind || kind),
+      execution_domain: explicit.execution_domain || inferExecutionDomain(contentEntry.path, explicit.layer || layer, explicit.role || inferRole(contentEntry.path, explicit.layer || layer, explicit.kind || kind), explicit.kind || kind),
+      tags: [...tags].sort(),
+    };
+    if (sourceBuffer) Object.assign(record, astMetadata(contentEntry.path, sourceBuffer.toString('utf8')));
+    entries.push(record);
+  }
+  attachResolvedImports(entries);
+  entries.sort((a, b) => comparePaths(a.path, b.path));
+  return {
+    format: FILEMETA_FORMAT,
+    version: FILEMETA_VERSION,
+    algorithm: 'sha256',
+    classifier,
+    rootHash: metadataRoot(entries, classifier),
+    stats: summarize(entries, packages),
+    entries,
+  };
+}

package/src/lib/merkle/snapshot.js

@@ -1,9 +1,10 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { directoryHash, linkHash, comparePaths } from './hash.js';
+import { directoryHash, linkHash, comparePaths, policyHash } from './hash.js';
 import { validPath, normalizePolicy, isIgnored } from './policy.js';
 import { buildMerkleTree } from './tree.js';
+import { validateSemanticMetadata } from './filemeta.js';
 
 export function validateSnapshot(value) {
   const fail = (message) => { throw new Error(`Invalid Merkle snapshot: ${message}`); };
@@ -11,12 +12,15 @@ export function validateSnapshot(value) {
   if (typeof value.rootPath !== 'string' || !value.rootPath || value.rootPath.includes('\0')) fail('missing root path');
   if (!value.policy || !Array.isArray(value.entries) || value.entries.length === 0) fail('missing entries/policy');
   const policy = normalizePolicy(value.policy);
+  const normalizedPolicyHash = policyHash(policy);
+  if (value.policyHash != null && value.policyHash !== normalizedPolicyHash) fail('policy hash mismatch');
   const nodes = new Map();
   const children = new Map();
   const stats = { files: 0, symlinks: 0, directories: 0, bytes: 0 };
   for (const entry of value.entries) {
     if (!entry || !validPath(entry.path, true) || entry.path.split('/').length > 257 || nodes.has(entry.path)) fail('invalid/duplicate path');
     if (!/^sha256:[a-f0-9]{64}$/.test(entry.hash)) fail('invalid hash');
+    if (entry.mode != null && (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777)) fail('invalid mode');
     if (entry.path && isIgnored(entry.path, policy)) fail('entry contradicts ignore policy');
     if (entry.type === 'file') {
       if (!Number.isSafeInteger(entry.size) || entry.size < 0) fail('invalid file size');
@@ -43,9 +47,11 @@ export function validateSnapshot(value) {
     }
   }
   if (value.rootHash !== nodes.get('').hash) fail('root hash mismatch');
+  const entries = [...nodes.values()].sort((a, b) => comparePaths(a.path, b.path));
+  const semantic = value.semantic ? validateSemanticMetadata(value.semantic, entries) : null;
   return { format: value.format, version: 1, algorithm: 'sha256', rootPath: value.rootPath,
-    createdAt: value.createdAt, policy, rootHash: value.rootHash, stats,
-    entries: [...nodes.values()].sort((a, b) => comparePaths(a.path, b.path)) };
+    createdAt: value.createdAt, policy, policyHash: normalizedPolicyHash, rootHash: value.rootHash, stats,
+    entries, ...(semantic ? { semantic } : {}) };
 }
 
 export async function readSnapshot(filename) {

package/src/lib/merkle/tree.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import { constants } from 'node:fs';
 import path from 'node:path';
-import { directoryHash, fileHasher, linkHash, comparePaths } from './hash.js';
+import { directoryHash, fileHasher, linkHash, comparePaths, policyHash } from './hash.js';
 import { normalizePolicy, isIgnored, validPath } from './policy.js';
 
 const unchanged = (a, b) => ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs'].every((key) => a[key] === b[key]);
@@ -49,10 +49,10 @@ export async function buildMerkleTree(root = '.', options = {}) {
       const target = raw.toString('utf8');
       if (!Buffer.from(target).equals(raw)) throw new Error(`Symlink target is not UTF-8: ${relative}`);
       if (!unchanged(stat, await fs.lstat(absolute, { bigint: true }))) throw new Error(`Symlink changed while scanning: ${relative}`);
-      entry = { path: relative, type: 'symlink', hash: linkHash(target), target };
+      entry = { path: relative, type: 'symlink', hash: linkHash(target), target, mode: Number(stat.mode & 0o7777n) };
       stats.symlinks++;
     } else if (stat.isFile()) {
-      entry = { path: relative, type: 'file', ...await hashFile(absolute, stat, signal) };
+      entry = { path: relative, type: 'file', ...await hashFile(absolute, stat, signal), mode: Number(stat.mode & 0o7777n) };
       stats.files++; stats.bytes += entry.size;
     } else if (stat.isDirectory()) {
       const names = await namesAt(absolute, relative);
@@ -68,7 +68,7 @@ export async function buildMerkleTree(root = '.', options = {}) {
       }
       // Empty directories have no file content identity, including snapshot-only parents.
       if (relative && children.length === 0) return null;
-      entry = { path: relative, type: 'directory', hash: directoryHash(children) };
+      entry = { path: relative, type: 'directory', hash: directoryHash(children), mode: Number(stat.mode & 0o7777n) };
       stats.directories++;
     } else throw new Error(`Unsupported filesystem entry: ${relative} (only files, directories, and symlinks are supported)`);
     entries.push(entry);
@@ -76,7 +76,12 @@ export async function buildMerkleTree(root = '.', options = {}) {
     return entry;
   }
   const rootEntry = await walk('');
-  return { format: 'agentsam-merkle', version: 1, algorithm: 'sha256', rootPath,
-    createdAt: new Date().toISOString(), policy, rootHash: rootEntry.hash, stats,
+  const tree = { format: 'agentsam-merkle', version: 1, algorithm: 'sha256', rootPath,
+    createdAt: new Date().toISOString(), policy, policyHash: policyHash(policy), rootHash: rootEntry.hash, stats,
     entries: entries.sort((a, b) => comparePaths(a.path, b.path)) };
+  if (options.semantic) {
+    const { buildSemanticMetadata } = await import('./semantic.js');
+    tree.semantic = await buildSemanticMetadata(rootPath, tree);
+  }
+  return tree;
 }

package/src/lib/project-config.js

@@ -0,0 +1,227 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { tryResolveGitContext } from './git-context.js';
+
+export const PROJECT_CONFIG_PATH = '.agentsam/config.json';
+export const PROJECT_CONFIG_SCHEMA_VERSION = 2;
+
+function providerForHost(host) {
+  const value = String(host || '').toLowerCase();
+  if (value === 'github.com') return 'github';
+  if (value === 'gitlab.com') return 'gitlab';
+  if (value === 'bitbucket.org') return 'bitbucket';
+  return value ? 'git' : null;
+}
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function portableRepositoryIdFromGit(cwd = process.cwd()) {
+  const git = tryResolveGitContext({ cwd });
+  if (!git) return null;
+  const provider = providerForHost(git.remoteHost);
+  if (!provider || !git.repoFullName) return null;
+  const fullName = provider === 'github' ? git.repoFullName.toLowerCase() : git.repoFullName;
+  return `${provider}:${fullName}`;
+}
+
+export function newLocalRepositoryId() {
+  return `local:${randomUUID()}`;
+}
+
+export function createProjectManifest({
+  projectName,
+  preset = null,
+  profile = 'default',
+  runTarget = 'local',
+  sdkVersion = null,
+  repositoryId = null,
+  repositoryRemote = 'origin',
+} = {}) {
+  const name = clean(projectName);
+  if (!name) throw new Error('project_name_required');
+  const repoId = clean(repositoryId) || newLocalRepositoryId();
+  const target = clean(runTarget) || 'local';
+  return {
+    schema_version: PROJECT_CONFIG_SCHEMA_VERSION,
+    project: {
+      name,
+    },
+    repository: {
+      id: repoId,
+      remote: clean(repositoryRemote) || 'origin',
+    },
+    product: {
+      preset: preset ? clean(preset) : null,
+      features: [],
+      capabilities: [],
+    },
+    defaults: {
+      mode: 'agent',
+      profile: clean(profile) || 'default',
+      runtime: 'local',
+      model: 'auto',
+      deploy_target: target === 'local' ? null : target,
+    },
+    merkle: {
+      enabled: true,
+      semantic: true,
+      persistence: 'auto',
+    },
+    rules: {
+      file: '.agentsamrules',
+    },
+    knowledge: {
+      config: '.agentsam/knowledge.json',
+    },
+    local: {
+      database: '.agentsam/data/agentsam.sqlite',
+      schema: 'db/schema.sql',
+    },
+    sdk: {
+      created_with: sdkVersion || null,
+    },
+  };
+}
+
+export function projectConfigPath(root) {
+  return path.join(path.resolve(root), PROJECT_CONFIG_PATH);
+}
+
+export function readProjectConfig(root) {
+  return JSON.parse(fs.readFileSync(projectConfigPath(root), 'utf8'));
+}
+
+export function tryReadProjectConfig(root) {
+  try {
+    return readProjectConfig(root);
+  } catch {
+    return null;
+  }
+}
+
+export function writeProjectConfig(root, config) {
+  const filename = projectConfigPath(root);
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  fs.writeFileSync(filename, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return filename;
+}
+
+export function isProjectManifestV2(config) {
+  return Number(config?.schema_version) === PROJECT_CONFIG_SCHEMA_VERSION && Boolean(config?.project?.name);
+}
+
+// Accessors deliberately understand the old flat scaffold so existing projects keep working
+// while new projects use the committed portable v2 manifest.
+export function getProjectName(config, fallback = '') {
+  return clean(config?.project?.name || config?.project || fallback);
+}
+
+export function getProjectPreset(config) {
+  return clean(config?.product?.preset || config?.preset || config?.lane) || null;
+}
+
+export function getDefaultProfile(config) {
+  return clean(config?.defaults?.profile || config?.agent) || 'default';
+}
+
+export function getDefaultRuntime(config) {
+  return clean(config?.defaults?.runtime || config?.run_target) || 'local';
+}
+
+export function getDefaultModel(config) {
+  return clean(config?.defaults?.model) || 'auto';
+}
+
+export function getDeployTarget(config) {
+  return clean(config?.defaults?.deploy_target || config?.deploy_target) || null;
+}
+
+export function getRepositoryId(config) {
+  return clean(config?.repository?.id) || null;
+}
+
+export function getProjectRulesPath(config) {
+  return clean(config?.rules?.file) || '.agentsamrules';
+}
+
+export function getKnowledgeConfigPath(config) {
+  return clean(config?.knowledge?.config) || '.agentsam/knowledge.json';
+}
+
+export function getLocalDatabasePath(config) {
+  return clean(config?.local?.database || config?.db_path) || '.agentsam/data/agentsam.sqlite';
+}
+
+export function getLocalSchemaPath(config) {
+  return clean(config?.local?.schema || config?.db_schema) || 'db/schema.sql';
+}
+
+export function getCreatedWithVersion(config) {
+  return clean(config?.sdk?.created_with || config?.scaffold_version) || null;
+}
+
+export function setDeployTarget(config, target) {
+  const value = clean(target) || null;
+  if (isProjectManifestV2(config)) {
+    config.defaults ||= {};
+    config.defaults.deploy_target = value;
+  } else {
+    config.deploy_target = value;
+  }
+  return config;
+}
+
+export function setProductPreset(config, preset) {
+  if (isProjectManifestV2(config)) {
+    config.product ||= { preset: null, features: [], capabilities: [] };
+    config.product.preset = clean(preset?.id) || null;
+    config.product.features = [...(preset?.features || [])];
+    config.product.capabilities = [...(preset?.capabilities || [])];
+  } else {
+    config.preset = clean(preset?.id) || null;
+    config.features = [...(preset?.features || [])];
+    config.capabilities = [...(preset?.capabilities || [])];
+  }
+  return config;
+}
+
+export function setLocalModelCapability(config, provider = 'ollama') {
+  if (isProjectManifestV2(config)) {
+    config.models ||= { default: getDefaultModel(config) };
+    config.models.local = {
+      provider,
+      base_url_env: 'OLLAMA_BASE_URL',
+      model_env: 'OLLAMA_MODEL',
+      embed_model_env: 'OLLAMA_EMBED_MODEL',
+    };
+  } else {
+    config.local_model = {
+      provider,
+      local_only: true,
+      base_url_env: 'OLLAMA_BASE_URL',
+      model_env: 'OLLAMA_MODEL',
+      embed_model_env: 'OLLAMA_EMBED_MODEL',
+    };
+  }
+  return config;
+}
+
+export function ensureProjectManifest(root, options = {}) {
+  const existing = tryReadProjectConfig(root);
+  if (existing) return existing;
+  const gitId = portableRepositoryIdFromGit(root);
+  const manifest = createProjectManifest({
+    projectName: options.projectName || path.basename(path.resolve(root)),
+    preset: options.preset ?? null,
+    profile: options.profile || 'default',
+    runTarget: options.runTarget || 'local',
+    sdkVersion: options.sdkVersion || null,
+    repositoryId: options.repositoryId || gitId || newLocalRepositoryId(),
+    repositoryRemote: options.repositoryRemote || 'origin',
+  });
+  writeProjectConfig(root, manifest);
+  return manifest;
+}