@inneranimalmedia/agentsam-sdk 2.4.1 → 2.5.0

package/src/lib/detect-context.js

@@ -5,6 +5,7 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { coreBaseUrl } from './core-client.js';
+import { resolveSdkKey } from '../../packages/identity/src/contracts/auth-config.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -220,22 +221,22 @@ async function detectIam(explicitToken = '') {
     });
   }
 
-  const sdkToken = explicitToken || process.env.AGENTSAM_SDK_TOKEN || '';
+  const sdkToken = resolveSdkKey(process.env, explicitToken);
   if (sdkToken.trim()) {
     const probe = await probeSdkBearer(sdkToken);
     if (probe.valid) {
       return {
-        source: 'sdk-token',
+        source: 'sdk-key',
         ready: true,
-        detail: `AGENTSAM_SDK_TOKEN · user ${probe.user_id || '?'}`,
+        detail: `AGENTSAM_SDK_KEY · user ${probe.user_id || '?'}`,
         probe,
         aux,
       };
     }
     return {
-      source: 'sdk-token',
+      source: 'sdk-key',
       ready: false,
-      detail: `AGENTSAM_SDK_TOKEN invalid (${probe.error}) → will open browser`,
+      detail: `AGENTSAM_SDK_KEY invalid (${probe.error}) → will open browser`,
       probe,
       aux,
     };

package/src/lib/identity-scaffold.js

@@ -75,7 +75,7 @@ migrations_dir = "migrations"
   files['.env.example'] = `# Minted at install/build — secrets via wrangler secret put (never commit)
 # IAM_CLIENT_ID=          # plaintext var (public by OAuth design)
 # IAM_CLIENT_SECRET=      # wrangler secret put only
-# IAM_OAUTH_ISSUER=https://inneranimalmedia.com
+# IAM_ORIGIN=https://inneranimalmedia.com
 
 # Developer BYOK — takes /api/oauth/{google|github}/start when set
 # GOOGLE_CLIENT_ID=

package/src/lib/local-scaffold.js

@@ -4,6 +4,8 @@
  */
 
 import pkg from '../../package.json' with { type: 'json' };
+import { createProjectManifest } from './project-config.js';
+import { defaultProjectRules } from './project-rules.js';
 
 const LANE_KEYS = {
   '1': 'fullstack',
@@ -139,37 +141,24 @@ export function buildLocalScaffoldFiles({
   const migration = migrationSql(laneKey);
 
   return [
-    {
-      path: 'agentsam.config.js',
-      content: `export default {
-  project: '${projectName}',
-  lane: '${laneKey}',
-  agent: '${agent}',
-  runTarget: '${runTarget}',
-  api: { baseUrl: '/api/agentsam' },
-};
-`,
-    },
     {
       path: '.agentsam/config.json',
       content: `${JSON.stringify(
-        {
-          project: projectName,
-          lane: laneKey,
-          agent,
-          run_target: 'local',
-          deploy_target: runTarget === 'local' ? null : runTarget,
-          pty_port: 3099,
-          dev_port: 8787,
-          db_path: '.agentsam/data/agentsam.sqlite',
-          db_schema: 'db/schema.sql',
-          ui: 'terminal',
-          scaffold_version: sdkVersion,
-        },
+        createProjectManifest({
+          projectName,
+          preset: laneKey,
+          profile: agent,
+          runTarget,
+          sdkVersion,
+        }),
         null,
         2,
       )}\n`,
     },
+    {
+      path: '.agentsamrules',
+      content: defaultProjectRules(projectName),
+    },
     {
       path: '.agentsam/start-local.md',
       content: `# Agent Sam local project
@@ -187,9 +176,10 @@ Useful local surfaces:
 
 \`\`\`bash
 npm run db:status
-npm run tui
-npm run tui:rich -- --install   # optional Rich UI in isolated .agentsam venv
+npx agentsam                    # enter Agent Sam
 npx agentsam start-local        # PTY on ws://127.0.0.1:3099
+npm run ollama:setup            # optional local/free model config
+npm run ollama:status           # probe local Ollama + models
 \`\`\`
 
 The local SQLite database lives at \`.agentsam/data/agentsam.sqlite\` and is initialized from \`db/schema.sql\`.
@@ -209,7 +199,12 @@ npx agentsam deploy
 dist/
 .wrangler/
 .agentsam/data/
+.agentsam/cli.json
 .agentsam/tui-venv/
+.agentsam/knowledge/
+.agentsam/cache/
+.agentsam/merkle/
+.agentsam/merkle.json
 *.db
 *.sqlite
 *.sqlite-*
@@ -231,8 +226,8 @@ dist/
             'db:init': 'agentsam db init',
             'db:status': 'agentsam db status',
             pty: 'agentsam start-local',
-            tui: 'agentsam tui',
-            'tui:rich': 'agentsam tui rich',
+            'ollama:setup': 'agentsam ollama setup',
+            'ollama:status': 'agentsam ollama status',
             deploy: 'agentsam deploy',
           },
           engines: {
@@ -262,6 +257,11 @@ AGENTSAM_LANE=${laneKey}
 AGENTSAM_AGENT=${agent}
 AGENTSAM_DB=.agentsam/data/agentsam.sqlite
 PORT=8787
+
+# Optional free/local model runtime. Enable with: agentsam ollama setup
+# OLLAMA_BASE_URL=http://127.0.0.1:11434
+# OLLAMA_MODEL=qwen2.5-coder
+# OLLAMA_EMBED_MODEL=mxbai-embed-large
 `,
     },
     {
@@ -399,13 +399,15 @@ Local state:
 ## Agent Sam terminal experience
 
 \`\`\`bash
-npm run tui                  # zero-dependency ANSI dashboard
-npm run tui:rich             # Python Rich dashboard if installed
-npm run tui:rich -- --install
+npx agentsam                  # enter the interactive Agent Sam experience
 npm run pty                  # local PTY on ws://127.0.0.1:3099
 npm run db:status
+npm run ollama:setup         # optional local/free model config
+npm run ollama:status        # local Ollama + model readiness
 \`\`\`
 
+Ollama is optional and local-only; it is not deployed as an edge model. Remote AgentSam sessions can reach it by executing the CLI through the existing user-hosted terminal tunnel.
+
 No Worker or cloud account is required for local development.
 
 ## Graduate intentionally
@@ -443,9 +445,9 @@ export function buildLocalScaffoldMeta(body, sdkVersion = pkg.version) {
       'npm run smoke',
       'npm run status',
       'npm run dev',
-      'npm run tui',
+      'npx agentsam',
       'npm run db:status',
-      'Optional: npm run tui:rich -- --install',
+      'Optional free/local models: npm run ollama:setup',
       'Optional: npm run pty',
       'When ready for cloud: npm run deploy',
     ],

package/src/lib/local-status.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { tryResolveGitContext } from './git-context.js';
 import { inspectLocalSqlite } from '../local/sqlite.js';
+import { getCreatedWithVersion, getDefaultProfile, getDeployTarget, getLocalDatabasePath, getProjectName, getProjectPreset, getRepositoryId, tryReadProjectConfig } from './project-config.js';
 
 export function findAgentSamProjectRoot(startDir = process.cwd()) {
   let dir = path.resolve(startDir);
@@ -14,16 +15,6 @@ export function findAgentSamProjectRoot(startDir = process.cwd()) {
   return path.resolve(startDir);
 }
 
-function readProjectConfig(root) {
-  const configPath = path.join(root, '.agentsam', 'config.json');
-  if (!fs.existsSync(configPath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
 async function probe(url) {
   try {
     const response = await fetch(url, { signal: AbortSignal.timeout(500) });
@@ -35,12 +26,12 @@ async function probe(url) {
 
 export async function collectLocalStatus(cwd = process.cwd()) {
   const root = findAgentSamProjectRoot(cwd);
-  const config = readProjectConfig(root);
+  const config = tryReadProjectConfig(root);
   const git = tryResolveGitContext({ cwd: root });
 
   let db = { ok: false, exists: false, tables: [] };
   if (config) {
-    db = await inspectLocalSqlite(path.join(root, config.db_path || '.agentsam/data/agentsam.sqlite'));
+    db = await inspectLocalSqlite(path.join(root, getLocalDatabasePath(config)));
   }
 
   const devPort = config?.dev_port ?? 8787;
@@ -54,11 +45,12 @@ export async function collectLocalStatus(cwd = process.cwd()) {
     schemaVersion: 'agentsam-local-status-v1',
     configured: Boolean(config),
     root,
-    project: config?.project || path.basename(root),
-    lane: config?.lane || null,
-    agent: config?.agent || null,
-    deployTarget: config?.deploy_target || null,
-    scaffoldVersion: config?.scaffold_version || null,
+    project: getProjectName(config, path.basename(root)),
+    repositoryId: getRepositoryId(config),
+    lane: getProjectPreset(config),
+    agent: getDefaultProfile(config),
+    deployTarget: getDeployTarget(config),
+    scaffoldVersion: getCreatedWithVersion(config),
     git: git
       ? {
           repo: git.repoFullName || null,

package/src/lib/merkle/cloudflare-persistence.js

@@ -0,0 +1,321 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { resolveGitContext } from '../git-context.js';
+import {
+  MERKLE_SNAPSHOT_STORAGE_PREFIX,
+  MERKLE_SNAPSHOT_TABLE,
+  MERKLE_WEBSITE_ASSETS_BINDING,
+  merkleSnapshotStorageKey,
+  normalizeMerkleStoragePrefix,
+} from './persistence.js';
+
+const D1_BINDING = 'DB';
+const CAPTURE_KINDS = new Set(['deploy', 'manual', 'agent', 'index']);
+const SOURCES = new Set(['github', 'gitlab', 'bitbucket', 'local', 'upload']);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function stripJsonComments(input) {
+  let out = '';
+  let string = false;
+  let quote = '';
+  let escaped = false;
+  let line = false;
+  let block = false;
+  for (let i = 0; i < input.length; i += 1) {
+    const char = input[i];
+    const next = input[i + 1];
+    if (line) {
+      if (char === '\n') { line = false; out += char; }
+      continue;
+    }
+    if (block) {
+      if (char === '*' && next === '/') { block = false; i += 1; }
+      continue;
+    }
+    if (string) {
+      out += char;
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === quote) string = false;
+      continue;
+    }
+    if (char === '"' || char === "'") { string = true; quote = char; out += char; continue; }
+    if (char === '/' && next === '/') { line = true; i += 1; continue; }
+    if (char === '/' && next === '*') { block = true; i += 1; continue; }
+    out += char;
+  }
+  return out;
+}
+
+function parseTomlBindings(text) {
+  const rows = { r2_buckets: [], d1_databases: [] };
+  let current = null;
+  let currentType = null;
+  const flush = () => {
+    if (current && currentType) rows[currentType].push(current);
+    current = null;
+    currentType = null;
+  };
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    const header = line.match(/^\[\[(?:env\.([^.\]]+)\.)?(r2_buckets|d1_databases)\]\]$/);
+    if (header) {
+      flush();
+      currentType = header[2];
+      current = { environment: header[1] || null };
+      continue;
+    }
+    if (/^\[/.test(line)) { flush(); continue; }
+    if (!current || !line || line.startsWith('#')) continue;
+    const match = line.match(/^([A-Za-z0-9_]+)\s*=\s*["']([^"']*)["']/);
+    if (match) current[match[1]] = match[2];
+  }
+  flush();
+  return rows;
+}
+
+function rowsFromJson(parsed, environment) {
+  const base = parsed && typeof parsed === 'object' ? parsed : {};
+  const env = environment && base.env?.[environment] && typeof base.env[environment] === 'object'
+    ? base.env[environment]
+    : {};
+  return {
+    r2_buckets: [...(env.r2_buckets || []), ...(base.r2_buckets || [])],
+    d1_databases: [...(env.d1_databases || []), ...(base.d1_databases || [])],
+  };
+}
+
+export function readWranglerPersistenceBindings(configPath, { environment = null } = {}) {
+  const filename = path.resolve(configPath);
+  const text = fs.readFileSync(filename, 'utf8');
+  const ext = path.extname(filename).toLowerCase();
+  let rows;
+  if (ext === '.json' || ext === '.jsonc') rows = rowsFromJson(JSON.parse(stripJsonComments(text)), environment);
+  else rows = parseTomlBindings(text);
+  const scoped = (items) => {
+    if (!environment) return items.filter((row) => !row.environment);
+    const envRows = items.filter((row) => row.environment === environment);
+    return envRows.length ? envRows : items.filter((row) => !row.environment);
+  };
+  return { configPath: filename, r2_buckets: scoped(rows.r2_buckets), d1_databases: scoped(rows.d1_databases) };
+}
+
+export function resolveWranglerMerklePersistence({
+  configPath,
+  environment = null,
+  r2Binding = MERKLE_WEBSITE_ASSETS_BINDING,
+  d1Binding = D1_BINDING,
+  r2Only = false,
+} = {}) {
+  if (!clean(configPath)) throw new Error('wrangler_config_required');
+  const rows = readWranglerPersistenceBindings(configPath, { environment });
+  const r2 = rows.r2_buckets.find((row) => clean(row.binding) === clean(r2Binding));
+  if (!r2?.bucket_name) throw new Error(`wrangler_r2_binding_not_found:${r2Binding}`);
+  const d1 = rows.d1_databases.find((row) => clean(row.binding) === clean(d1Binding));
+  if (!r2Only && !d1?.database_name) throw new Error(`wrangler_d1_binding_not_found:${d1Binding}`);
+  return {
+    config_path: rows.configPath,
+    environment: environment || null,
+    r2_binding: r2Binding,
+    storage_bucket: String(r2.bucket_name),
+    d1_binding: r2Only ? null : d1Binding,
+    database_name: r2Only ? null : String(d1.database_name),
+  };
+}
+
+function providerRepoId(git) {
+  const host = clean(git?.remoteHost).toLowerCase();
+  const fullName = clean(git?.repoFullName);
+  if (!fullName) return null;
+  if (host === 'github.com') return `github:${fullName}`;
+  if (host === 'gitlab.com') return `gitlab:${fullName}`;
+  if (host === 'bitbucket.org') return `bitbucket:${fullName}`;
+  return null;
+}
+
+function safeId(value) {
+  return clean(value).replace(/[^A-Za-z0-9._-]+/g, '').slice(0, 96);
+}
+
+function snapshotIdFor({ snapshot, repoId, captureKind, deploymentId }) {
+  const deployment = safeId(deploymentId);
+  if (captureKind === 'deploy' && deployment) return `mrs_dep_${deployment.toLowerCase()}`;
+  const digest = createHash('sha256')
+    .update([repoId, snapshot.rootHash, snapshot.semantic?.rootHash || '', captureKind].join('\0'))
+    .digest('hex');
+  return `mrs_${digest.slice(0, 24)}`;
+}
+
+function sqlEsc(value) {
+  return String(value ?? '').replaceAll("'", "''");
+}
+
+function sqlText(value) {
+  return value == null || value === '' ? 'NULL' : `'${sqlEsc(value)}'`;
+}
+
+function sqlInt(value) {
+  return value == null || value === '' || !Number.isFinite(Number(value)) ? 'NULL' : String(Math.trunc(Number(value)));
+}
+
+export function buildMerklePersistencePlan({
+  snapshot,
+  root = process.cwd(),
+  ownerUserId,
+  repoId,
+  source = 'local',
+  captureKind = 'manual',
+  connectionId = null,
+  runtimeLeaseId = null,
+  deploymentId = null,
+  workerVersionId = null,
+  referenceLabel = null,
+  storagePrefix = MERKLE_SNAPSHOT_STORAGE_PREFIX,
+  wrangler,
+} = {}) {
+  if (!snapshot?.rootHash || !Array.isArray(snapshot?.entries)) throw new Error('merkle_snapshot_required');
+  const owner = clean(ownerUserId);
+  if (!owner) throw new Error('owner_user_id_required');
+  if (!CAPTURE_KINDS.has(captureKind)) throw new Error(`capture_kind_invalid:${captureKind}`);
+  if (!SOURCES.has(source)) throw new Error(`source_invalid:${source}`);
+  if (captureKind !== 'deploy' && !clean(connectionId) && !clean(runtimeLeaseId)) throw new Error('execution_provenance_required');
+  let git = null;
+  try { git = resolveGitContext({ cwd: root }); } catch { git = null; }
+  const resolvedRepoId = clean(repoId) || providerRepoId(git);
+  if (!resolvedRepoId) throw new Error('repo_id_required');
+  const snapshotId = snapshotIdFor({ snapshot, repoId: resolvedRepoId, captureKind, deploymentId });
+  const prefix = normalizeMerkleStoragePrefix(storagePrefix);
+  const storageKey = merkleSnapshotStorageKey({ ownerUserId: owner, repoId: resolvedRepoId, snapshotId, prefix });
+  const createdAt = Math.floor(Date.now() / 1000);
+  const classifier = snapshot.semantic?.classifier || null;
+  const row = {
+    snapshot_id: snapshotId,
+    owner_user_id: owner,
+    repo_id: resolvedRepoId,
+    repository: git?.remoteUrl || null,
+    source,
+    manifest_format: snapshot.format || 'agentsam-merkle',
+    manifest_version: snapshot.version || 1,
+    hash_algorithm: snapshot.algorithm || 'sha256',
+    root_hash: snapshot.rootHash,
+    policy_hash: snapshot.policyHash || null,
+    resolved_commit_sha: git?.revisionSha || null,
+    resolved_tree_sha: null,
+    git_branch: git?.branch || null,
+    working_tree_dirty: git?.dirty ? 1 : 0,
+    connection_id: clean(connectionId) || null,
+    runtime_lease_id: clean(runtimeLeaseId) || null,
+    storage_backend: 'r2',
+    storage_bucket: wrangler.storage_bucket,
+    storage_key: storageKey,
+    entry_count: snapshot.entries.length,
+    file_count: snapshot.stats?.files ?? null,
+    directory_count: snapshot.stats?.directories ?? null,
+    symlink_count: snapshot.stats?.symlinks ?? 0,
+    total_bytes: snapshot.stats?.bytes ?? null,
+    capture_kind: captureKind,
+    deployment_id: clean(deploymentId) || null,
+    worker_version_id: clean(workerVersionId) || null,
+    reference_label: clean(referenceLabel) || `${captureKind}:${snapshotId}`,
+    created_at: createdAt,
+    persisted_at: createdAt,
+    metadata_root: snapshot.semantic?.rootHash || null,
+    classifier_format: classifier?.format || null,
+    classifier_version: classifier?.version ?? null,
+    classifier_source: classifier?.source || null,
+  };
+  return { snapshot_id: snapshotId, storage_key: storageKey, row, wrangler, prefix };
+}
+
+export function merklePersistenceUpsertSql(row) {
+  return `INSERT INTO ${MERKLE_SNAPSHOT_TABLE} (
+  snapshot_id, owner_user_id, repo_id, repository, source,
+  manifest_format, manifest_version, hash_algorithm, root_hash, policy_hash,
+  resolved_commit_sha, resolved_tree_sha, git_branch, working_tree_dirty,
+  connection_id, runtime_lease_id, storage_backend, storage_bucket, storage_key,
+  entry_count, file_count, directory_count, symlink_count, total_bytes,
+  capture_kind, deployment_id, worker_version_id, reference_label,
+  created_at, persisted_at, metadata_root, classifier_format, classifier_version, classifier_source
+) VALUES (
+  ${sqlText(row.snapshot_id)}, ${sqlText(row.owner_user_id)}, ${sqlText(row.repo_id)}, ${sqlText(row.repository)}, ${sqlText(row.source)},
+  ${sqlText(row.manifest_format)}, ${sqlInt(row.manifest_version)}, ${sqlText(row.hash_algorithm)}, ${sqlText(row.root_hash)}, ${sqlText(row.policy_hash)},
+  ${sqlText(row.resolved_commit_sha)}, ${sqlText(row.resolved_tree_sha)}, ${sqlText(row.git_branch)}, ${sqlInt(row.working_tree_dirty)},
+  ${sqlText(row.connection_id)}, ${sqlText(row.runtime_lease_id)}, ${sqlText(row.storage_backend)}, ${sqlText(row.storage_bucket)}, ${sqlText(row.storage_key)},
+  ${sqlInt(row.entry_count)}, ${sqlInt(row.file_count)}, ${sqlInt(row.directory_count)}, ${sqlInt(row.symlink_count)}, ${sqlInt(row.total_bytes)},
+  ${sqlText(row.capture_kind)}, ${sqlText(row.deployment_id)}, ${sqlText(row.worker_version_id)}, ${sqlText(row.reference_label)},
+  ${sqlInt(row.created_at)}, ${sqlInt(row.persisted_at)}, ${sqlText(row.metadata_root)}, ${sqlText(row.classifier_format)}, ${sqlInt(row.classifier_version)}, ${sqlText(row.classifier_source)}
+)
+ON CONFLICT(snapshot_id) DO UPDATE SET
+  storage_backend=excluded.storage_backend,
+  storage_bucket=excluded.storage_bucket,
+  storage_key=excluded.storage_key,
+  persisted_at=excluded.persisted_at,
+  deployment_id=excluded.deployment_id,
+  worker_version_id=excluded.worker_version_id,
+  reference_label=excluded.reference_label,
+  metadata_root=excluded.metadata_root,
+  classifier_format=excluded.classifier_format,
+  classifier_version=excluded.classifier_version,
+  classifier_source=excluded.classifier_source;`;
+}
+
+function wranglerArgs(base, wrangler) {
+  const args = [...base, '--config', wrangler.config_path];
+  if (wrangler.environment) args.push('--env', wrangler.environment);
+  return args;
+}
+
+export function persistMerkleSnapshotCloudflare({
+  snapshotPath,
+  snapshot,
+  plan,
+  wranglerBin = process.env.WRANGLER_BIN || 'wrangler',
+  r2Only = false,
+  dryRun = false,
+} = {}) {
+  const filename = path.resolve(snapshotPath);
+  if (!fs.existsSync(filename)) throw new Error('snapshot_file_not_found');
+  const result = {
+    provider: 'cloudflare',
+    binding: plan.wrangler.r2_binding,
+    storage_bucket: plan.row.storage_bucket,
+    storage_key: plan.row.storage_key,
+    database_binding: plan.wrangler.d1_binding,
+    database_name: plan.wrangler.database_name,
+    table: r2Only ? null : MERKLE_SNAPSHOT_TABLE,
+    snapshot_id: plan.row.snapshot_id,
+    row: plan.row,
+    dry_run: Boolean(dryRun),
+  };
+  if (dryRun) return result;
+
+  const object = `${plan.row.storage_bucket}/${plan.row.storage_key}`;
+  execFileSync(wranglerBin, wranglerArgs(['r2', 'object', 'put', object, '--file', filename, '--remote'], plan.wrangler), {
+    stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+  });
+  if (r2Only) return result;
+
+  const tmp = path.join(os.tmpdir(), `agentsam-merkle-persist-${process.pid}-${Date.now()}.sql`);
+  fs.writeFileSync(tmp, `${merklePersistenceUpsertSql(plan.row)}\n`, { encoding: 'utf8', mode: 0o600 });
+  try {
+    execFileSync(wranglerBin, wranglerArgs(['d1', 'execute', plan.wrangler.database_name, '--remote', '--yes', `--file=${tmp}`], plan.wrangler), {
+      stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+    });
+  } catch (error) {
+    try {
+      execFileSync(wranglerBin, wranglerArgs(['r2', 'object', 'delete', object, '--remote'], plan.wrangler), {
+        stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+      });
+    } catch {}
+    throw error;
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+  return result;
+}

package/src/lib/merkle/filemeta.js

@@ -0,0 +1,43 @@
+import { createHash } from 'node:crypto';
+import { comparePaths } from './hash.js';
+
+export const FILEMETA_FORMAT = 'agentsam-filemeta';
+export const FILEMETA_VERSION = 1;
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+function semanticDigest(type, value) {
+  return 'sha256:' + createHash('sha256')
+    .update(`agentsam-filemeta:${type}:v1\0`)
+    .update(JSON.stringify(canonical(value)))
+    .digest('hex');
+}
+
+export function metadataRoot(entries, classifier) {
+  return semanticDigest('root', { classifier, entries: [...entries].sort((a, b) => comparePaths(a.path, b.path)) });
+}
+
+export function validateSemanticMetadata(value, contentEntries = []) {
+  const fail = (message) => { throw new Error(`Invalid semantic metadata: ${message}`); };
+  if (!value || value.format !== FILEMETA_FORMAT || value.version !== FILEMETA_VERSION || value.algorithm !== 'sha256') fail('unsupported format/version');
+  if (!value.classifier || !Array.isArray(value.entries)) fail('missing classifier/entries');
+  const content = new Map(contentEntries.filter((entry) => entry.type !== 'directory').map((entry) => [entry.path, entry]));
+  const seen = new Set();
+  for (const entry of value.entries) {
+    if (!entry || typeof entry.path !== 'string' || seen.has(entry.path)) fail('invalid/duplicate path');
+    seen.add(entry.path);
+    if (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777) fail(`invalid mode: ${entry.path}`);
+    if (!/^sha256:[a-f0-9]{64}$/.test(entry.hash || '')) fail(`invalid hash: ${entry.path}`);
+    const source = content.get(entry.path);
+    if (source && source.hash !== entry.hash) fail(`content hash mismatch: ${entry.path}`);
+    if (source?.type === 'file' && source.size !== entry.size) fail(`file size mismatch: ${entry.path}`);
+  }
+  if (content.size && seen.size !== content.size) fail('entry count does not match content tree');
+  const rootHash = metadataRoot(value.entries, value.classifier);
+  if (rootHash !== value.rootHash) fail('metadata root mismatch');
+  return { ...value, rootHash, entries: [...value.entries].sort((a, b) => comparePaths(a.path, b.path)) };
+}

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';