@entrorove/skill 0.1.23 → 0.1.25

package/local-scope-repository.mjs

@@ -0,0 +1,249 @@
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { builtinModules } from 'node:module';
+import ts from 'typescript';
+import { parse as parseVue } from '@vue/compiler-sfc';
+import { lineCount, observedScopeRisk, packageBoundary, scopeFail, scopeFiles, scopeRead, scopeTarget, stableScope } from './local-scope-files.mjs';
+import { sha256 } from './local-integrity.mjs';
+import { workspaceImport, workspaceIndex } from './local-scope-workspaces.mjs';
+import { assertBudgetRunnerAllowed } from './local-budget-reads.mjs';
+import { observeBudgetScopeGit, scopeGitBudgetEnforced } from './local-scope-git.mjs';
+import { scopeGitMetadata } from './local-scope-git-reads.mjs';
+
+const execute = promisify(execFile);
+async function git(root, args, allowed = [], input = { repositoryRoot: root }) {
+  await assertBudgetRunnerAllowed(input);
+  try {
+    return (await execute('git', ['--no-optional-locks', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-c', 'diff.external=', ...args],
+      { cwd: root, encoding: 'utf8', timeout: 10_000, maxBuffer: 2_097_152,
+        env: { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))), GIT_OPTIONAL_LOCKS: '0' } })).stdout;
+  } catch (error) {
+    if (allowed.includes(error.code)) return null;
+    scopeFail('ENTROROVE_GIT_FAILED', 'Git fact inspection failed or exceeded its execution bound');
+  }
+}
+function changedLines(output) {
+  let total = 0; let binary = false; let present = false;
+  for (const entry of output.split('\0')) {
+    const match = /^(\d+|-)\t(\d+|-)\t/.exec(entry);
+    if (!match) continue;
+    present = true;
+    if (match[1] === '-' || match[2] === '-') binary = true;
+    else total += Number(match[1]) + Number(match[2]);
+  }
+  return { lines: total, binary, present };
+}
+async function hasGitMarker(root) {
+  let directory = root;
+  while (true) {
+    try { await fs.lstat(path.join(directory, '.git')); return true; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const parent = path.dirname(directory);
+    if (parent === directory) return false;
+    directory = parent;
+  }
+}
+/** @typedef {{available:boolean, head:string|null, baseline:string|null, currentChangedLines:number, untrackedChangedLines?:number, recentChangedLines:number, binary:boolean, commits:Array<{commit:string, changedLines:number, binary:boolean}>}} GitScopeFacts */
+/** @typedef {{facts:GitScopeFacts, currentDiffPresent:boolean}} GitScopeObservation */
+/** @returns {Promise<GitScopeObservation>} */
+export async function observeGitFacts(root, files, baselineRef, input = { repositoryRoot: root }) {
+  const marker = await hasGitMarker(root);
+  if (marker && await scopeGitBudgetEnforced(input)) return observeBudgetScopeGit(root, files, baselineRef, input);
+  const top = marker ? await git(root, ['rev-parse', '--show-toplevel'], [128], input) : null;
+  if (top === null) {
+    if (baselineRef) scopeFail('ENTROROVE_GIT_BASELINE', 'baselineRef requires an actual Git repository');
+    return { facts: { available: false, head: null, baseline: null, currentChangedLines: 0, recentChangedLines: 0, binary: false, commits: [] }, currentDiffPresent: false };
+  }
+  if (await fs.realpath(top.trim()) !== root) scopeFail('ENTROROVE_GIT_ROOT', 'scope root must match the Git repository root');
+  const head = await git(root, ['rev-parse', '--verify', 'HEAD'], [128], input);
+  if (head === null) {
+    if (baselineRef) scopeFail('ENTROROVE_GIT_BASELINE', 'baselineRef requires a resolvable commit');
+    return { facts: { available: true, head: null, baseline: null, currentChangedLines: 0, recentChangedLines: 0, binary: false, commits: [] }, currentDiffPresent: false };
+  }
+  if (baselineRef !== undefined && (typeof baselineRef !== 'string' || !baselineRef || baselineRef.startsWith('-') || /[\u0000-\u001f]/.test(baselineRef))) scopeFail('ENTROROVE_GIT_BASELINE', 'baselineRef is invalid');
+  const base = await git(root, ['rev-parse', '--verify', `${baselineRef ?? 'HEAD'}^{commit}`], [128], input);
+  if (base === null) scopeFail('ENTROROVE_GIT_BASELINE', 'baselineRef must resolve to a real commit');
+  const pathspec = files.map(file => `:(literal)${file.path}`);
+  const current = changedLines(await git(root, ['diff', '--no-ext-diff', '--no-textconv', '--numstat', '-z', base.trim(), '--', ...pathspec], [], input));
+  const tracked = new Set((await git(root, ['ls-files', '--cached', '-z', '--', ...pathspec], [], input)).split('\0').filter(Boolean));
+  const untracked = files.filter(file => file.exists !== false && !tracked.has(file.path));
+  const untrackedChangedLines = untracked.reduce((sum, file) => sum + file.lines, 0);
+  const recent = (await git(root, ['log', '-5', '--format=%H', '--', ...pathspec], [], input)).trim().split('\n').filter(Boolean);
+  const commits = [];
+  for (const commit of recent) {
+    const count = changedLines(await git(root, ['show', '--format=', '--no-ext-diff', '--no-textconv', '--numstat', '-z', commit, '--', ...pathspec], [], input));
+    commits.push({ commit, changedLines: count.lines, binary: count.binary });
+  }
+  return { facts: { available: true, head: head.trim(), baseline: base.trim(), currentChangedLines: current.lines + untrackedChangedLines, untrackedChangedLines,
+    recentChangedLines: Math.max(0, ...commits.map(commit => commit.changedLines)), binary: current.binary || commits.some(commit => commit.binary), commits },
+    currentDiffPresent: current.present || untracked.length > 0 };
+}
+/** @returns {Promise<GitScopeFacts>} */
+export async function gitFacts(root, files, baselineRef, input = { repositoryRoot: root }) { return (await observeGitFacts(root, files, baselineRef, input)).facts; }
+
+const scriptKinds = new Map([['.ts', ts.ScriptKind.TS], ['.mts', ts.ScriptKind.TS], ['.cts', ts.ScriptKind.TS],
+  ['.tsx', ts.ScriptKind.TSX], ['.js', ts.ScriptKind.JS], ['.mjs', ts.ScriptKind.JS], ['.cjs', ts.ScriptKind.JS], ['.jsx', ts.ScriptKind.JSX]]);
+const dynamicNames = new Set(['eval', 'Function', 'createRequire']);
+function staticString(expression) {
+  while (expression && ts.isParenthesizedExpression(expression)) expression = expression.expression;
+  if (!expression || (!ts.isStringLiteral(expression) && !ts.isNoSubstitutionTemplateLiteral(expression))) return null;
+  return expression.text;
+}
+function moduleLiteral(expression) {
+  const value = staticString(expression);
+  if (value !== null && (!value || /[\u0000-\u001f\u007f]/.test(value))) scopeFail('ENTROROVE_IMPORT_INVALID', 'module literal is empty or contains control characters');
+  return value;
+}
+function globalObject(expression) {
+  while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
+    || ts.isTypeAssertionExpression(expression) || ts.isNonNullExpression(expression) || ts.isSatisfiesExpression(expression))) expression = expression.expression;
+  return expression && ts.isIdentifier(expression) && ['globalThis', 'global', 'window'].includes(expression.text);
+}
+// The same pinned TypeScript parser as the cloud scope analyzer visits actual
+// expressions inside templates and JSX; literal bodies never become code.
+function scriptImports(source, filename) {
+  const parsed = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true,
+    scriptKinds.get(path.extname(filename).toLowerCase()) ?? ts.ScriptKind.TS);
+  if (parsed.parseDiagnostics.length) scopeFail('ENTROROVE_IMPORT_INVALID', 'source has invalid or unterminated syntax');
+  const found = new Set(); let dynamic = false;
+  const add = expression => { const value = moduleLiteral(expression); if (value === null) dynamic = true; else found.add(value); };
+  const visit = node => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) { if (node.moduleSpecifier) add(node.moduleSpecifier); }
+    else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) add(node.moduleReference.expression);
+    else if (ts.isImportTypeNode(node)) add(ts.isLiteralTypeNode(node.argument) ? node.argument.literal : undefined);
+    else if (ts.isCallExpression(node)) {
+      const importer = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+      const requireCall = ts.isIdentifier(node.expression) && node.expression.text === 'require';
+      if (importer || requireCall) {
+        if (!node.arguments.length || node.arguments.length > (importer ? 2 : 1)) dynamic = true;
+        else add(node.arguments[0]);
+      }
+    }
+    if (ts.isIdentifier(node)) {
+      if (dynamicNames.has(node.text)) dynamic = true;
+      if (node.text === 'require' && !(ts.isCallExpression(node.parent) && node.parent.expression === node)
+        && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node)
+        && !(ts.isMethodDeclaration(node.parent) && node.parent.name === node)) dynamic = true;
+    }
+    if (ts.isElementAccessExpression(node)) {
+      const member = staticString(node.argumentExpression);
+      if (dynamicNames.has(member) || member === 'require' || member === null && globalObject(node.expression)) dynamic = true;
+    }
+    if (ts.isPropertyAccessExpression(node) && node.name.text === 'require' && globalObject(node.expression)) dynamic = true;
+    ts.forEachChild(node, visit);
+  };
+  visit(parsed); return { specifiers: [...found].sort(), dynamic };
+}
+function vueScripts(source, filename) {
+  const { descriptor, errors } = parseVue(source, { filename, sourceMap: false,
+    templateParseOptions: { expressionPlugins: ['typescript'] } });
+  if (errors.length) scopeFail('ENTROROVE_IMPORT_INVALID', 'component has invalid or unterminated syntax');
+  if (descriptor.customBlocks.length || descriptor.template?.lang || descriptor.template?.src) {
+    scopeFail('ENTROROVE_IMPORT_UNSUPPORTED', 'component dependency inspection requires supported inline template syntax');
+  }
+  const scripts = [];
+  for (const block of [descriptor.script, descriptor.scriptSetup].filter(Boolean)) {
+    const language = block.lang ?? 'js';
+    if (!['js', 'javascript', 'ts', 'typescript', 'jsx', 'tsx'].includes(language)) scopeFail('ENTROROVE_IMPORT_UNSUPPORTED', 'component script language is unsupported');
+    const extension = { javascript: 'js', typescript: 'ts' }[language] ?? language;
+    scripts.push({ source: block.src ? `import ${JSON.stringify(block.src)};` : block.content, filename: `${filename}.${extension}` });
+  }
+  const seen = new WeakSet();
+  const walk = node => {
+    if (!node || typeof node !== 'object' || seen.has(node)) return;
+    seen.add(node);
+    if (node.type === 7 && ['on', 'for'].includes(node.name) && node.exp?.content) {
+      scripts.push({ source: node.name === 'for' ? `for (${node.exp.content}) {}` : node.exp.content, filename: `${filename}.ts` });
+      seen.add(node.exp);
+    }
+    if (node.type === 4 && !node.isStatic && node.content) scripts.push({ source: `void (${node.content});`, filename: `${filename}.ts` });
+    for (const [key, child] of Object.entries(node)) if (!['loc', 'ast', 'parent', 'codegenNode'].includes(key)) {
+      if (Array.isArray(child)) child.forEach(walk); else walk(child);
+    }
+  };
+  walk(descriptor.template?.ast); return scripts;
+}
+function importSpecifiers(content, filename) {
+  try {
+    const source = content.toString('utf8'), parts = path.extname(filename).toLowerCase() === '.vue' ? vueScripts(source, filename) : [{ source, filename }];
+    const specifiers = new Set(); let dynamic = false;
+    for (const part of parts) { const parsed = scriptImports(part.source, part.filename); dynamic ||= parsed.dynamic;
+      for (const specifier of parsed.specifiers) specifiers.add(specifier); }
+    return { specifiers: [...specifiers].sort(), dynamic };
+  } catch (error) {
+    if (typeof error?.code === 'string' && error.code.startsWith('ENTROROVE_')) throw error;
+    if (error instanceof RangeError) scopeFail('ENTROROVE_SCOPE_LIMIT', 'dependency syntax exceeds the supported parser or traversal bound');
+    scopeFail('ENTROROVE_IMPORT_INVALID', 'dependency source could not be parsed');
+  }
+}
+const sourceExtension = /\.(?:[cm]?[jt]sx?|vue)$/i;
+async function resolveImport(root, from, specifier, workspace, input) {
+  if (/^(?:https?:|file:|data:)/i.test(specifier)) scopeFail('ENTROROVE_IMPORT_UNSUPPORTED', 'remote source imports cannot be inspected as local facts');
+  const localPackage = !specifier.startsWith('.') ? workspaceImport(workspace, specifier) : null;
+  if (!specifier.startsWith('.') && !localPackage) {
+    if (builtinModules.includes(specifier) || (specifier.startsWith('node:') && builtinModules.includes(specifier.slice(5)))) return null;
+    const boundary = await packageBoundary(root, from, input);
+    if (boundary.manifestPath) {
+      const manifest = JSON.parse((await scopeRead(root, boundary.manifestPath, input)).content.toString('utf8'));
+      const name = specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
+      if (['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'].some(field => Object.hasOwn(manifest[field] ?? {}, name))) return null;
+    }
+    scopeFail('ENTROROVE_IMPORT_UNRESOLVED', 'bare imports require a builtin, declared dependency, or actual workspace export; unresolved aliases cannot be assumed external');
+  }
+  const relative = localPackage ?? path.posix.normalize(path.posix.join(path.posix.dirname(from), specifier));
+  if (relative.startsWith('../') || relative === '..') scopeFail('ENTROROVE_PATH_UNSAFE', 'local import escapes the repository');
+  const replacements = /\.js$/.test(relative) ? [relative.replace(/\.js$/, '.ts'), relative.replace(/\.js$/, '.tsx')] : [];
+  for (const candidate of [relative, ...replacements, ...['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '/index.js', '/index.ts'].map(ext => relative + ext)]) {
+    const item = await scopeTarget(root, candidate, true);
+    if (item.exists && item.stat.isFile()) return candidate;
+  }
+  scopeFail('ENTROROVE_IMPORT_UNRESOLVED', 'a local import has no resolvable source file');
+}
+export async function importGraph(root, originals, input = { repositoryRoot: root }) {
+  const pending = originals.filter(file => file.exists !== false).map(file => file.path); const visited = new Map(); const edges = []; let dynamic = false;
+  const workspace = await workspaceIndex(root, input);
+  while (pending.length) {
+    const relative = pending.shift(); if (visited.has(relative)) continue;
+    if (visited.size >= 1000) scopeFail('ENTROROVE_SCOPE_LIMIT', 'import graph exceeds the 1000-file inspection bound');
+    const read = await scopeRead(root, relative, input); const boundary = await packageBoundary(root, relative, input);
+    visited.set(relative, { path: relative, sha256: read.sha256, module: boundary.path, boundary });
+    if (!sourceExtension.test(relative)) continue;
+    const imports = importSpecifiers(read.content, relative); dynamic ||= imports.dynamic;
+    for (const specifier of imports.specifiers.sort()) {
+      const target = await resolveImport(root, relative, specifier, workspace, input);
+      edges.push({ from: relative, to: target, external: target === null, specifier });
+      if (target !== null && !visited.has(target)) pending.push(target);
+    }
+  }
+  const nodes = [...visited.values()].sort((a, b) => a.path.localeCompare(b.path));
+  await stableScope(root, nodes, input);
+  await stableScope(root, workspace.metadata, input);
+  return { nodes, edges: edges.sort((a, b) => `${a.from}:${a.specifier}`.localeCompare(`${b.from}:${b.specifier}`)), dynamic, complete: !dynamic, workspaceMetadata: workspace.metadata };
+}
+export async function collectScopeFacts(root, requested, baselineRef, knownFiles = [], input = { repositoryRoot: root }) {
+  const selected = await scopeFiles(root, requested, knownFiles); const files = [];
+  for (const relative of selected) {
+    const target = await scopeTarget(root, relative, knownFiles.some(file => file.path === relative));
+    if (!target.exists) {
+      const previous = knownFiles.find(file => file.path === relative);
+      files.push({ path: relative, exists: false, sha256: sha256('entrorove.missing-file/1.0'), bytes: 0, lines: 0, module: previous.module });
+      continue;
+    }
+    const read = await scopeRead(root, relative, input); const boundary = await packageBoundary(root, relative, input);
+    files.push({ path: relative, exists: true, sha256: read.sha256, bytes: read.bytes, lines: lineCount(read.content), module: boundary.path });
+  }
+  const graph = await importGraph(root, files, input); const observedGit = await observeGitFacts(root, files, baselineRef, input); const history = observedGit.facts;
+  const modules = [...new Map(graph.nodes.map(node => [node.boundary.path, node.boundary])).values()].sort((a, b) => a.path.localeCompare(b.path));
+  await stableScope(root, files, input);
+  await stableScope(root, modules.filter(module => module.manifestPath).map(module => ({ path: module.manifestPath, sha256: module.manifestDigest })), input);
+  if (history.available && (await scopeGitMetadata(root, ['rev-parse', '--verify', 'HEAD'], input, [128]))?.trim() !== history.head) scopeFail('ENTROROVE_SCOPE_CHANGED', 'Git HEAD changed during scope inspection');
+  const sourceLines = files.reduce((sum, file) => sum + file.lines, 0); const bytes = files.reduce((sum, file) => sum + file.bytes, 0);
+  // An actual current diff (including empty untracked files) is authoritative; clean Git uses history, unknown Git uses source lines.
+  const estimatedChangedLines = history.available && history.head ? (observedGit.currentDiffPresent ? history.currentChangedLines : history.recentChangedLines)
+    : sourceLines + files.filter(file => !file.exists).reduce((sum, file) => sum + (knownFiles.find(previous => previous.path === file.path)?.lines ?? 0), 0);
+  return { targetPaths: [...new Set(requested)].sort(), fileCount: files.length, files, bytes, sourceLines, tokenEstimate: Math.ceil(bytes / 4), modules,
+    crossModule: modules.length > 1, risk: observedScopeRisk(files), importGraph: graph, git: history,
+    estimatedChangedLines };
+}

package/local-scope-signature.mjs

@@ -0,0 +1,70 @@
+import { createPrivateKey, createPublicKey, randomUUID, sign } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { scopeFail, scopeRead, scopeControlRead, scopeRoot } from './local-scope-files.mjs';
+import { collectScopeFacts } from './local-scope-repository.mjs';
+import { readScopeSnapshot, verifyFreshScopeSnapshot } from './local-scope-snapshot.mjs';
+import { resolveScopePaths } from './local-scope-context.mjs';
+import { rejectScopePrivileges, verifiedScopeCandidate } from './local-scope-candidate.mjs';
+
+async function privateFile(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) scopeFail('ENTROROVE_SCOPE_SIGNER_INVALID', 'scope signer control paths must be absolute');
+  const root = path.parse(file).root; const relative = file.slice(root.length);
+  const stat = await fs.lstat(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid())
+    || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)) scopeFail('ENTROROVE_SCOPE_SIGNER_INVALID', 'scope signer controls must be private regular files owned by the current account');
+  let ancestor = root;
+  for (const part of relative.split('/').slice(0, -1)) {
+    ancestor = path.join(ancestor, part); const parentStat = await fs.lstat(ancestor);
+    if (!parentStat.isSymbolicLink()) continue;
+    const systemAlias = process.platform === 'darwin' && ['/var', '/tmp'].includes(ancestor)
+      && parentStat.uid === 0 && await fs.realpath(ancestor) === `/private${ancestor}`;
+    if (!systemAlias) scopeFail('ENTROROVE_SCOPE_SIGNER_INVALID', 'scope signer control ancestors must not be symlinked');
+  }
+  const parent = await fs.realpath(path.dirname(file));
+  return (await scopeControlRead(parent, path.basename(file))).content.toString('utf8');
+}
+function binding(input, result) {
+  const text = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/; const digest = /^[0-9a-f]{64}$/;
+  for (const field of ['flowId', 'stepId', 'ownerId', 'repositoryId', 'challenge']) {
+    if (typeof input[field] !== 'string' || !text.test(input[field])) scopeFail('ENTROROVE_SCOPE_ATTESTATION_BINDING', 'scope signature requires the original task, owner, repository, step, and challenge');
+  }
+  for (const field of ['taskDigest', 'chainDigest']) if (!digest.test(String(input[field] ?? ''))) scopeFail('ENTROROVE_SCOPE_ATTESTATION_BINDING', 'scope signature requires original task and chain digests');
+  if (!digest.test(String(result.snapshotDigest ?? ''))) scopeFail('ENTROROVE_SCOPE_ATTESTATION_BINDING', 'scope signature requires a verified preserved snapshot digest');
+}
+export async function attestScopeFacts(input, result) {
+  rejectScopePrivileges(input);
+  if (input.signerConfigPath === undefined || input.signerConfigPath === null) return result;
+  binding(input, result);
+  const root = await scopeRoot(input.repositoryRoot); const snapshot = await readScopeSnapshot(input, root);
+  const actual = await collectScopeFacts(root, await resolveScopePaths(input, root), input.baselineRef, snapshot.known, input);
+  actual.snapshotEvidence = await verifyFreshScopeSnapshot(input, root, actual);
+  const candidate = await verifiedScopeCandidate(input, root, actual.snapshotEvidence.manifest);
+  if (root !== result.repositoryRoot || canonical(actual) !== canonical(result.facts)
+    || actual.snapshotEvidence.snapshotDigest !== result.snapshotDigest) scopeFail('ENTROROVE_SCOPE_ATTESTATION_BINDING', 'scope signer refuses facts or snapshot assertions that do not match independent inspection');
+  let config; let privateKey;
+  try {
+    config = JSON.parse(await privateFile(input.signerConfigPath));
+    if (config.schemaVersion !== 'entrorove.scope-signer/1.0' || !Number.isSafeInteger(config.receiptTtlMs)
+      || config.receiptTtlMs < 1 || config.receiptTtlMs > 300_000) scopeFail('ENTROROVE_SCOPE_SIGNER_INVALID', 'scope signer schema or receipt lifetime is invalid');
+    privateKey = createPrivateKey(await privateFile(config.privateKeyPath));
+    if (privateKey.asymmetricKeyType !== 'ed25519') scopeFail('ENTROROVE_SCOPE_SIGNER_INVALID', 'scope signer must use Ed25519');
+    const keyId = sha256(createPublicKey(privateKey).export({ type: 'spki', format: 'der' }));
+    if (keyId !== config.keyId) scopeFail('ENTROROVE_SCOPE_SIGNER_INVALID', 'scope signer key identity is invalid');
+    if (candidate && keyId !== candidate.runnerKeyId) scopeFail('ENTROROVE_SCOPE_SIGNER_INVALID', 'temporary scope signer must be the actual cloud registered candidate runner');
+  } catch (error) {
+    if (error.code === 'ENTROROVE_SCOPE_SIGNER_INVALID') throw error;
+    scopeFail('ENTROROVE_SCOPE_SIGNER_INVALID', 'scope signer configuration or signing key could not be read');
+  }
+  const now = Date.now();
+  const expiresAt = Math.min(now + config.receiptTtlMs, candidate ? Date.parse(candidate.expiresAt) : Infinity);
+  if (expiresAt <= now) scopeFail('ENTROROVE_SCOPE_ATTESTATION_BINDING', 'candidate challenge expired before its actual scope signature');
+  const core = { schemaVersion: 'entrorove.scope-facts/1.0', flowId: input.flowId, stepId: input.stepId,
+    taskDigest: input.taskDigest, ownerId: input.ownerId, chainDigest: input.chainDigest, repositoryId: input.repositoryId,
+    facts: result.facts, snapshotDigest: result.snapshotDigest, challenge: input.challenge,
+    issuedAt: new Date(now).toISOString(), expiresAt: new Date(expiresAt).toISOString(),
+    nonce: randomUUID(), keyId: config.keyId };
+  const signature = sign(null, Buffer.from(canonical(core)), privateKey).toString('base64url');
+  return { ...result, attestation: { ...core, signature }, trusted: false, status: 'reported' };
+}

package/local-scope-snapshot.mjs

@@ -0,0 +1,39 @@
+import { readSnapshotCopy14 } from './local-mutation-snapshot.mjs';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { sha256, verifySnapshotManifest } from './local-integrity.mjs';
+import { packageBoundary, scopeFail, scopeRead, scopeControlRead, scopeTarget } from './local-scope-files.mjs';
+
+export async function readScopeSnapshot(input, root) {
+  const id = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+  for (const field of ['flowId', 'stepId', 'snapshotId']) if (!id.test(String(input[field] ?? ''))) scopeFail('ENTROROVE_SCOPE_BINDING', 'scope snapshot requires original flow, step, and snapshot identities');
+  const home = input.home ?? os.homedir();
+  if (typeof home !== 'string' || !path.isAbsolute(home)) scopeFail('ENTROROVE_HOME_INVALID', 'home must be absolute');
+  const base = await fs.realpath(home); const relative = `.entrorove/snapshots/${sha256(root).slice(0, 32)}/${input.flowId}/${input.snapshotId}`;
+  await scopeTarget(base, relative);
+  const manifest = JSON.parse((await scopeControlRead(base, `${relative}/manifest.json`)).content.toString('utf8'));
+  const integrity = verifySnapshotManifest(manifest, { snapshotId: input.snapshotId, flowId: input.flowId, stepId: input.stepId, repositoryDigest: sha256(root).slice(0, 32) });
+  if (!integrity.verified) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'scope snapshot manifest integrity failed');
+  const directory = path.join(base, relative); const known = [];
+  for (const file of manifest.files) {
+    if (file.exists) {
+      if ((await readSnapshotCopy14(input, directory, manifest, file.path)).sha256 !== file.sha256) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'scope snapshot copy hash failed');
+    } else if (file.sha256 !== sha256('entrorove.missing-file/1.0') || (await readSnapshotCopy14(input, directory, manifest, file.path)).exists) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'scope missing-file snapshot is corrupt');
+    known.push({ ...file, module: (await packageBoundary(root, file.path, input)).path });
+  }
+  return { manifest, directory, known };
+}
+export async function verifyFreshScopeSnapshot(input, root, facts) {
+  const snapshot = await readScopeSnapshot(input, root);
+  if (snapshot.manifest.paths.join('\0') !== facts.files.map(file => file.path).join('\0')) scopeFail('ENTROROVE_SCOPE_SNAPSHOT_PATHS', 'fresh snapshot must cover exactly the observed target paths');
+  for (const file of snapshot.manifest.files) {
+    const actual = facts.files.find(observed => observed.path === file.path);
+    const target = await scopeTarget(root, file.path, !file.exists);
+    if (file.exists !== target.exists || actual?.exists !== file.exists || actual?.sha256 !== file.sha256
+      || (file.exists && (await scopeRead(root, file.path, input)).sha256 !== file.sha256)) scopeFail('ENTROROVE_SNAPSHOT_CHANGED', 'fresh scope snapshot no longer matches live files');
+  }
+  return { snapshotId: input.snapshotId, snapshotDigest: snapshot.manifest.snapshotDigest, flowId: input.flowId, stepId: input.stepId,
+    files: snapshot.manifest.files.map(file => ({ path: file.path, sha256: file.sha256, exists: file.exists })),
+    copiesVerified: true, currentSnapshotFresh: true, manifest: snapshot.manifest };
+}

package/local-scope-state.mjs

@@ -0,0 +1,204 @@
+import { readSnapshotCopy14, preserveSnapshotCopies14 } from './local-mutation-snapshot.mjs';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { canonical, sha256, verifySnapshotManifest } from './local-integrity.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { scopeFail, scopeRead, scopeControlRead, scopeTarget, stableScope } from './local-scope-files.mjs';
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const order = ['lock', 'probe', 'swarm'];
+export function scopeBinding(input) {
+  for (const field of ['flowId', 'stepId', 'snapshotId']) if (typeof input[field] !== 'string' || !ID.test(input[field])) scopeFail('ENTROROVE_SCOPE_BINDING', 'scope requires concrete flowId, stepId, and snapshotId');
+  return { flowId: input.flowId, stepId: input.stepId, snapshotId: input.snapshotId };
+}
+async function privateDirectory(directory) {
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const stat = await fs.lstat(directory);
+  if (stat.isSymbolicLink() || !stat.isDirectory() || (process.getuid && stat.uid !== process.getuid())) scopeFail('ENTROROVE_STATE_INVALID', 'scope state must be a directory owned by the current account');
+  if (process.platform !== 'win32') await fs.chmod(directory, 0o700);
+}
+async function stateRoot(input) {
+  const home = input.home ?? os.homedir();
+  if (typeof home !== 'string' || !path.isAbsolute(home)) scopeFail('ENTROROVE_HOME_INVALID', 'home must be absolute');
+  await fs.mkdir(home, { recursive: true, mode: 0o700 }); const homeStat = await fs.lstat(home);
+  if (!homeStat.isDirectory() || homeStat.isSymbolicLink()) scopeFail('ENTROROVE_HOME_INVALID', 'home must be a real directory');
+  const actual = await fs.realpath(home);
+  const state = path.join(actual, '.entrorove'); await privateDirectory(state);
+  return state;
+}
+async function scopeDirectory(input, root) {
+  const base = await stateRoot(input); let directory = base;
+  for (const part of ['scope', sha256(root).slice(0, 32), input.flowId]) {
+    directory = path.join(directory, part); await privateDirectory(directory);
+  }
+  return { directory, base, statePath: path.join(directory, 'state.json') };
+}
+async function privateJson(file) {
+  const stat = await fs.lstat(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid())
+    || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)) scopeFail('ENTROROVE_STATE_INVALID', 'scope state must be a private regular file');
+  return JSON.parse(await fs.readFile(file, 'utf8'));
+}
+async function atomicJson(file, value) {
+  const temporary = `${file}.${randomUUID()}.tmp`; let handle;
+  try {
+    handle = await fs.open(temporary, 'wx', 0o600); await handle.writeFile(`${canonical(value)}\n`); await handle.sync(); await handle.close(); handle = null;
+    await fs.rename(temporary, file);
+  } finally { if (handle) await handle.close(); await fs.rm(temporary, { force: true }); }
+}
+async function originalSnapshot(input, root, base) {
+  const relative = `snapshots/${sha256(root).slice(0, 32)}/${input.flowId}/${input.snapshotId}`;
+  await scopeTarget(base, relative);
+  const directory = path.join(base, relative); const manifest = JSON.parse((await scopeControlRead(base, `${relative}/manifest.json`)).content.toString('utf8'));
+  const integrity = verifySnapshotManifest(manifest, { ...scopeBinding(input), repositoryDigest: sha256(root).slice(0, 32) });
+  if (!integrity.verified) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'the original snapshot manifest is not valid for this scope');
+  for (const file of manifest.files) {
+    if (file.exists && (await readSnapshotCopy14(input, directory, manifest, file.path)).sha256 !== file.sha256) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'the original snapshot copy changed');
+    if (!file.exists) {
+      const target = await readSnapshotCopy14(input, directory, manifest, file.path);
+      if (target.exists) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'a missing-file snapshot contains a file');
+    }
+  }
+  return { manifest, directory, digest: manifest.snapshotDigest };
+}
+async function capture(root, files, directory, input) {
+  for (const file of files) {
+    if (file.exists === false) {
+      if ((await scopeTarget(root, file.path, true)).exists) scopeFail('ENTROROVE_SCOPE_CHANGED', 'a deleted source reappeared before preservation');
+      continue;
+    }
+    const read = await scopeRead(root, file.path, input);
+    if (read.sha256 !== file.sha256) scopeFail('ENTROROVE_SCOPE_CHANGED', 'scope source changed before snapshot preservation');
+    const destination = path.join(directory, file.path);
+    await fs.mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+    await fs.writeFile(destination, read.content, { mode: 0o600, flag: 'wx' });
+  }
+}
+function stateIntegrity(state, input, root) {
+  if (!state || !state.originalSnapshot || state.schemaVersion !== 'entrorove.scope-state/1.0' || state.repositoryDigest !== sha256(root).slice(0, 32)
+    || state.flowId !== input.flowId || state.stepId !== input.stepId || state.originalSnapshot.snapshotId !== input.snapshotId
+    || state.snapshotId !== state.originalSnapshot.snapshotId
+    || !Number.isSafeInteger(state.revision) || !order.includes(state.mode) || !Array.isArray(state.history)
+    || state.history.length !== state.revision || state.mode !== state.history.at(-1)?.mode
+    || state.taskDigest !== sha256(canonical(state.originalTask))
+    || canonical(state.originalFacts) !== canonical(state.history[0]?.facts)
+    || state.originalFactsDigest !== sha256(canonical(state.originalFacts))) scopeFail('ENTROROVE_SCOPE_STATE_CORRUPT', 'scope state is not bound or its original facts changed');
+  for (const [index, record] of state.history.entries()) {
+    const core = Object.fromEntries(Object.entries(record).filter(([key]) => key !== 'recordDigest'));
+    if (record.revision !== index + 1 || record.previousDigest !== (state.history[index - 1]?.recordDigest ?? null)
+      || record.recordDigest !== sha256(canonical(core))) scopeFail('ENTROROVE_SCOPE_STATE_CORRUPT', 'scope history integrity failed');
+  }
+}
+function historyRecord(state, facts, directory, mode) {
+  const previous = state.history.at(-1); const oldFiles = new Map((previous?.facts.files ?? []).map(file => [file.path, file.sha256]));
+  const changes = facts.files.filter(file => oldFiles.get(file.path) !== file.sha256).map(file => ({ path: file.path, before: oldFiles.get(file.path) ?? null, after: file.exists === false ? null : file.sha256 }));
+  const paths = new Set(facts.files.map(file => file.path));
+  for (const file of previous?.facts.files ?? []) if (!paths.has(file.path)) changes.push({ path: file.path, before: file.sha256, after: null });
+  const core = { revision: state.revision + 1, previousDigest: previous?.recordDigest ?? null, mode, facts, changes,
+    observedAt: new Date().toISOString(), snapshotDirectory: directory, factsDigest: sha256(canonical(facts)) };
+  return { ...core, recordDigest: sha256(canonical(core)) };
+}
+function preservedFiles(facts) {
+  const files = [...facts.files, ...facts.importGraph.workspaceMetadata.map(file => ({ ...file, exists: true })), ...facts.importGraph.nodes.map(node => ({ path: node.path, sha256: node.sha256, exists: true })),
+    ...facts.modules.filter(module => module.manifestPath).map(module => ({ path: module.manifestPath, sha256: module.manifestDigest, exists: true }))];
+  return [...new Map(files.map(file => [file.path, file])).values()];
+}
+async function saveRevision(location, root, state, facts, mode, initial, input) {
+  const staged = await fs.mkdtemp(path.join(location.directory, '.revision-'));
+  const final = path.join(location.directory, `revision-${state.revision + 1}-${randomUUID()}`); let committed = false;
+  try {
+    const currentDirectory = path.join(staged, 'current'); await fs.mkdir(currentDirectory, { mode: 0o700 });
+    await capture(root, preservedFiles(facts), currentDirectory, input);
+    if (initial) {
+      const original = path.join(staged, 'original'); await fs.mkdir(original, { mode: 0o700 });
+      await preserveSnapshotCopies14(input, initial.directory, initial.manifest, original);
+      await fs.writeFile(path.join(original, 'manifest.json'), `${canonical(initial.manifest)}\n`, { flag: 'wx', mode: 0o600 });
+    }
+    await stableScope(root, preservedFiles(facts), input); await fs.rename(staged, final);
+    const record = historyRecord(state, facts, path.join(final, 'current'), mode);
+    const next = { ...state, revision: record.revision, mode, history: [...state.history, record] };
+    if (initial) next.originalSnapshot = { ...next.originalSnapshot, directory: path.join(final, 'original') };
+    await atomicJson(location.statePath, next); committed = true;
+    return next;
+  } finally { await fs.rm(staged, { recursive: true, force: true }); if (!committed) await fs.rm(final, { recursive: true, force: true }); }
+}
+async function verifyPreserved(state, input) {
+  const manifest = JSON.parse((await scopeControlRead(state.originalSnapshot.directory, 'manifest.json')).content.toString('utf8'));
+  const integrity = verifySnapshotManifest(manifest, { flowId: state.flowId, stepId: state.stepId,
+    snapshotId: state.originalSnapshot.snapshotId, repositoryDigest: state.repositoryDigest });
+  if (!integrity.verified || manifest.snapshotDigest !== state.originalSnapshot.digest
+    || sha256(canonical(manifest)) !== state.originalSnapshot.manifestDigest) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'preserved original snapshot manifest or initial binding changed');
+  for (const file of manifest.files) {
+    if (file.exists && (await readSnapshotCopy14(input, state.originalSnapshot.directory, manifest, file.path)).sha256 !== file.sha256) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'preserved original snapshot copy changed');
+    if (!file.exists && (await readSnapshotCopy14(input, state.originalSnapshot.directory, manifest, file.path)).exists) {
+      scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'preserved missing original snapshot acquired source bytes');
+    }
+  }
+  for (const record of state.history) for (const file of preservedFiles(record.facts)) {
+    if (file.exists === false) {
+      if ((await scopeTarget(record.snapshotDirectory, file.path, true)).exists) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'a preserved deletion acquired source bytes');
+    } else if ((await scopeRead(record.snapshotDirectory, file.path, input)).sha256 !== file.sha256) scopeFail('ENTROROVE_SNAPSHOT_CORRUPT', 'a preserved completed-change snapshot changed');
+  }
+}
+export async function retainedScope(input, root, optionalFreshProbe = false) {
+  scopeBinding(input); const home = input.home ?? os.homedir();
+  if (typeof home !== 'string' || !path.isAbsolute(home)) scopeFail('ENTROROVE_HOME_INVALID', 'home must be absolute');
+  const relative = `.entrorove/scope/${sha256(root).slice(0, 32)}/${input.flowId}/state.json`;
+  let state;
+  try {
+    await scopeTarget(await fs.realpath(home), relative);
+    state = await privateJson(path.join(await fs.realpath(home), relative));
+  } catch (error) { if (optionalFreshProbe && error.code === 'ENOENT') return null; throw error; }
+  // Validate the retained origin against its physical manifest; probe separately verifies the current step's fresh snapshot.
+  stateIntegrity(state, optionalFreshProbe ? { ...input, stepId: state?.stepId, snapshotId: state?.originalSnapshot?.snapshotId } : input, root);
+  await verifyPreserved(state, input);
+  if (input.task !== undefined && sha256(canonical(input.task)) !== state.taskDigest) scopeFail('ENTROROVE_SCOPE_TASK_CHANGED', 'probe and reassess must preserve the original accepted task');
+  return state;
+}
+export async function initializeScope(input, root, facts, classification) {
+  scopeBinding(input); const location = await scopeDirectory(input, root);
+  return withStateLock(location.statePath, async () => {
+    const original = await originalSnapshot(input, root, location.base);
+    for (const file of original.manifest.files) {
+      const actual = facts.files.find(observed => observed.path === file.path);
+      if (file.exists && actual?.sha256 !== file.sha256) scopeFail('ENTROROVE_SNAPSHOT_CHANGED', 'initial scope does not match the verified original snapshot');
+    }
+    let existing;
+    try { existing = await privateJson(location.statePath); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (existing) {
+      stateIntegrity(existing, { ...input, snapshotId: existing.originalSnapshot.snapshotId }, root); await verifyPreserved(existing, input);
+      if (input.task !== undefined && existing.taskDigest !== sha256(canonical(input.task))) scopeFail('ENTROROVE_SCOPE_TASK_CHANGED', 'the original task must remain unchanged');
+      const comparable = value => Object.fromEntries(Object.entries(value).filter(([key]) => !['snapshotEvidence', 'targetPaths'].includes(key)));
+      if (canonical(comparable(existing.history.at(-1).facts)) !== canonical(comparable(facts))) scopeFail('ENTROROVE_SCOPE_CHANGED', 'use reassess to preserve changed scope facts before probing a fresh snapshot');
+      return { state: existing, statePath: location.statePath };
+    }
+    const state = { schemaVersion: 'entrorove.scope-state/1.0', ...scopeBinding(input), repositoryDigest: sha256(root).slice(0, 32), revision: 0,
+      mode: classification.mode, originalTask: input.task ?? null, taskDigest: sha256(canonical(input.task ?? null)), originalFacts: facts, originalFactsDigest: sha256(canonical(facts)), originalSnapshot: { snapshotId: input.snapshotId,
+        digest: original.digest, manifestDigest: sha256(canonical(original.manifest)), directory: null }, history: [] };
+    return { state: await saveRevision(location, root, state, facts, classification.mode, original, input), statePath: location.statePath };
+  });
+}
+export async function upgradeScope(input, root, facts, classification) {
+  scopeBinding(input);
+  if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 1) scopeFail('ENTROROVE_SCOPE_REVISION', 'reassess requires the exact persisted expectedRevision');
+  const location = await scopeDirectory(input, root);
+  return withStateLock(location.statePath, async () => {
+    let state;
+    try { state = await privateJson(location.statePath); } catch (error) {
+      if (error.code === 'ENOENT') scopeFail('ENTROROVE_SCOPE_STATE_MISSING', 'probe and preserve the original verified snapshot before reassess');
+      throw error;
+    }
+    stateIntegrity(state, input, root); await verifyPreserved(state, input);
+    if (state.revision !== input.expectedRevision) scopeFail('ENTROROVE_SCOPE_REVISION', 'scope revision changed; read the current scope before reassess');
+    if (input.task !== undefined && state.taskDigest !== sha256(canonical(input.task))) scopeFail('ENTROROVE_SCOPE_TASK_CHANGED', 'reassess must preserve the original task');
+    const observed = new Set(facts.files.map(file => file.path));
+    if (state.history.at(-1).facts.files.some(file => !observed.has(file.path))) scopeFail('ENTROROVE_SCOPE_SHRINK', 'reassess cannot discard a previously observed target');
+    if (input.currentMode !== undefined && input.currentMode !== state.mode) scopeFail('ENTROROVE_MODE_INVALID', 'currentMode must match the persisted mode');
+    const previousMode = state.mode; const current = order.indexOf(previousMode); const required = order.indexOf(classification.mode);
+    const mode = required > current ? order[Math.min(current + 1, order.length - 1)] : previousMode;
+    const next = await saveRevision(location, root, state, facts, mode, null, input);
+    return { state: next, statePath: location.statePath, previousMode, mode, requiredMode: classification.mode, upgraded: mode !== previousMode };
+  });
+}