@inneranimalmedia/agentsam-sdk 2.4.0 → 2.5.0

package/src/lib/merkle/git-ignore.js

@@ -0,0 +1,24 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+
+/**
+ * Resolve Git-ignored paths using Git itself so every Merkle-backed consumer can
+ * build evidence from the same checkout policy. Non-Git directories simply
+ * return an empty list and still receive the protocol's built-in excludes.
+ */
+export async function gitIgnoredPaths(root) {
+  try {
+    const result = await execute('git', ['status', '--porcelain=v1', '--ignored=matching'], {
+      cwd: root,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return [...new Set(result.stdout.split('\n')
+      .filter((line) => line.startsWith('!! '))
+      .map((line) => line.slice(3).trim().replace(/\/$/, ''))
+      .filter((value) => value && !value.includes('\\') && !value.split('/').includes('..')))];
+  } catch {
+    return [];
+  }
+}

package/src/lib/merkle/hash.js

@@ -4,6 +4,7 @@ export const comparePaths = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from
 export const digest = (type, value) => 'sha256:' + createHash('sha256')
   .update(`agentsam-merkle:${type}:v1\0`).update(value).digest('hex');
 export const linkHash = (target) => digest('symlink', target);
+export const policyHash = (policy) => digest('policy', JSON.stringify(policy));
 export const directoryHash = (children) => digest('directory', JSON.stringify(
   [...children].sort((a, b) => comparePaths(a.name, b.name)).map(({ name, type, hash }) => [name, type, hash]),
 ));

package/src/lib/merkle/index.js

@@ -2,3 +2,25 @@ export { buildMerkleTree } from './tree.js';
 export { saveSnapshot, readSnapshot, validateSnapshot } from './snapshot.js';
 export { diffTrees } from './diff.js';
 export { DEFAULT_IGNORES, normalizePolicy } from './policy.js';
+export { policyHash } from './hash.js';
+export async function buildSemanticMetadata(...args) {
+  const semantic = await import('./semantic.js');
+  return semantic.buildSemanticMetadata(...args);
+}
+export { validateSemanticMetadata, metadataRoot, FILEMETA_FORMAT, FILEMETA_VERSION } from './filemeta.js';
+
+export {
+  MERKLE_SNAPSHOT_SCHEMA_SQL,
+  MERKLE_SNAPSHOT_STORAGE_PREFIX,
+  MERKLE_SNAPSHOT_TABLE,
+  MERKLE_WEBSITE_ASSETS_BINDING,
+  merkleSnapshotStorageKey,
+  normalizeMerkleStoragePrefix,
+} from './persistence.js';
+export {
+  buildMerklePersistencePlan,
+  merklePersistenceUpsertSql,
+  persistMerkleSnapshotCloudflare,
+  readWranglerPersistenceBindings,
+  resolveWranglerMerklePersistence,
+} from './cloudflare-persistence.js';

package/src/lib/merkle/persistence.js

@@ -0,0 +1,72 @@
+export const MERKLE_SNAPSHOT_TABLE = 'agentsam_fs_merkle_snapshots';
+export const MERKLE_SNAPSHOT_STORAGE_PREFIX = 'agentsam_fs_merkle_snapshots';
+export const MERKLE_WEBSITE_ASSETS_BINDING = 'WEBSITE_ASSETS';
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function safeSegment(value, name) {
+  const segment = clean(value);
+  if (!segment) throw new Error(`${name}_required`);
+  if (segment === '.' || segment === '..' || /[\u0000-\u001f\u007f]/.test(segment)) {
+    throw new Error(`${name}_invalid`);
+  }
+  return encodeURIComponent(segment);
+}
+
+export function normalizeMerkleStoragePrefix(value = MERKLE_SNAPSHOT_STORAGE_PREFIX) {
+  const prefix = clean(value || MERKLE_SNAPSHOT_STORAGE_PREFIX).replace(/^\/+|\/+$/g, '');
+  if (!prefix || prefix.split('/').some((part) => !part || part === '.' || part === '..')) {
+    throw new Error('merkle_storage_prefix_invalid');
+  }
+  return prefix;
+}
+
+/**
+ * Provider-neutral object key. The host chooses which physical bucket is bound
+ * to the logical WEBSITE_ASSETS role; the SDK never owns cloud credentials.
+ */
+export function merkleSnapshotStorageKey({ ownerUserId, repoId, snapshotId, prefix = MERKLE_SNAPSHOT_STORAGE_PREFIX } = {}) {
+  return `${normalizeMerkleStoragePrefix(prefix)}/${safeSegment(ownerUserId, 'owner_user_id')}/${safeSegment(repoId, 'repo_id')}/${safeSegment(snapshotId, 'snapshot_id')}.json`;
+}
+
+/** Portable D1/SQLite schema for hosts that opt into persisted Merkle snapshots. */
+export const MERKLE_SNAPSHOT_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${MERKLE_SNAPSHOT_TABLE} (
+  snapshot_id TEXT PRIMARY KEY NOT NULL,
+  owner_user_id TEXT NOT NULL,
+  repo_id TEXT NOT NULL,
+  repository TEXT,
+  source TEXT NOT NULL CHECK (source IN ('github','gitlab','bitbucket','local','upload')),
+  manifest_format TEXT NOT NULL DEFAULT 'agentsam-merkle',
+  manifest_version INTEGER NOT NULL DEFAULT 1,
+  hash_algorithm TEXT NOT NULL DEFAULT 'sha256',
+  root_hash TEXT NOT NULL,
+  policy_hash TEXT,
+  resolved_commit_sha TEXT,
+  resolved_tree_sha TEXT,
+  git_branch TEXT,
+  working_tree_dirty INTEGER NOT NULL DEFAULT 0,
+  connection_id TEXT,
+  runtime_lease_id TEXT,
+  storage_backend TEXT NOT NULL DEFAULT 'r2' CHECK (storage_backend IN ('r2','local_fs','inline','none')),
+  storage_bucket TEXT,
+  storage_key TEXT,
+  entry_count INTEGER,
+  file_count INTEGER,
+  directory_count INTEGER,
+  symlink_count INTEGER,
+  total_bytes INTEGER,
+  capture_kind TEXT NOT NULL DEFAULT 'manual' CHECK (capture_kind IN ('deploy','manual','agent','index')),
+  deployment_id TEXT,
+  worker_version_id TEXT,
+  reference_label TEXT,
+  created_at INTEGER NOT NULL,
+  persisted_at INTEGER,
+  metadata_root TEXT,
+  classifier_format TEXT,
+  classifier_version INTEGER,
+  classifier_source TEXT,
+  CHECK (storage_backend IN ('inline','none') OR (storage_bucket IS NOT NULL AND storage_key IS NOT NULL)),
+  CHECK (connection_id IS NOT NULL OR runtime_lease_id IS NOT NULL OR capture_kind = 'deploy')
+);`;

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/open-url.js

@@ -0,0 +1,66 @@
+import readline from 'node:readline';
+import { spawn } from 'node:child_process';
+
+function normalizeHttpUrl(value) {
+  const raw = String(value || '').trim();
+  if (!raw) throw new Error('URL is required');
+  let parsed;
+  try { parsed = new URL(raw); }
+  catch { throw new Error(`Invalid URL: ${raw}`); }
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`Unsupported URL protocol: ${parsed.protocol}`);
+  }
+  return parsed.toString();
+}
+
+export function browserCommand(url, platform = process.platform) {
+  const normalized = normalizeHttpUrl(url);
+  if (platform === 'darwin') return { command: 'open', args: [normalized] };
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'start', '', normalized] };
+  return { command: 'xdg-open', args: [normalized] };
+}
+
+export function openExternalUrl(url, {
+  platform = process.platform,
+  spawnImpl = spawn,
+} = {}) {
+  const invocation = browserCommand(url, platform);
+  const child = spawnImpl(invocation.command, invocation.args, {
+    stdio: 'ignore',
+    detached: true,
+  });
+  child.unref?.();
+  return invocation;
+}
+
+export async function promptToOpenUrl(url, {
+  heading = 'Open in your browser:',
+  prompt = 'Press ENTER to open in the browser, or copy the URL above.',
+  input = process.stdin,
+  output = process.stdout,
+  openImpl = openExternalUrl,
+} = {}) {
+  const normalized = normalizeHttpUrl(url);
+  output.write(`\n${heading}\n${normalized}\n`);
+
+  if (!input?.isTTY || !output?.isTTY) {
+    output.write('Open the URL above in a browser to continue.\n\n');
+    return { url: normalized, opened: false, interactive: false };
+  }
+
+  const rl = readline.createInterface({ input, output });
+  try {
+    await new Promise(resolve => rl.question(`\n${prompt}\n`, resolve));
+  } finally {
+    rl.close();
+  }
+
+  try {
+    openImpl(normalized);
+    output.write('\nBrowser opened. Complete the step there, then return here.\n\n');
+    return { url: normalized, opened: true, interactive: true };
+  } catch (error) {
+    output.write(`\nCould not open the browser automatically: ${error.message}\nOpen the URL above manually.\n\n`);
+    return { url: normalized, opened: false, interactive: true, error: error.message };
+  }
+}