@entrorove/skill 0.1.22 → 0.1.24

package/local-mutation-snapshot.mjs

@@ -0,0 +1,200 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256, snapshotHandoffBinding, verifySnapshotManifest } from './local-integrity.mjs';
+import { budgetBindingForRead } from './local-budget-reads.mjs';
+import { atomicMutationJson14, cleanupMutationDirectory14, mutationFail14, mutationId14, mutationPaths14,
+  mutationPath14, mutationRead14, mutationRoot14, mutationStateRoot14, mutationTarget14, privateMutationDirectory14,
+  readMutationJson14, writeMutationFile14 } from './local-mutation-files.mjs';
+
+const LOCAL_SCHEMA = 'entrorove.local-execution/1.0';
+const SNAPSHOT_SCHEMA = 'entrorove.snapshot/1.0';
+const RECEIPT_SCHEMA = 'entrorove.snapshot-receipt/1.0';
+const COPY_LAYOUT = 'files/1.0';
+const SHA256 = /^[0-9a-f]{64}$/;
+const MISSING_SHA256 = sha256('entrorove.missing-file/1.0');
+const repoKey = root => sha256(root).slice(0, 32);
+function layoutBinding(value) {
+  if (!Object.hasOwn(value, 'copyLayout')) return {};
+  if (value.copyLayout !== COPY_LAYOUT) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'snapshot copy layout is invalid');
+  return { copyLayout: value.copyLayout };
+}
+function handoffBinding(value) {
+  try { return snapshotHandoffBinding(value); }
+  catch { mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'snapshot handoff epoch and baseline receipt binding are invalid'); }
+}
+function receiptCore(receipt) {
+  return { schemaVersion: RECEIPT_SCHEMA, snapshotId: receipt.snapshotId, flowId: receipt.flowId, stepId: receipt.stepId,
+    repositoryDigest: receipt.repositoryDigest, snapshotDigest: receipt.snapshotDigest, contractDigest: receipt.contractDigest ?? null,
+    paths: receipt.paths, fileManifestDigest: receipt.fileManifestDigest, ...handoffBinding(receipt), ...layoutBinding(receipt) };
+}
+export function loadSnapshotReceipt14(receipt) {
+  if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt) || receipt.schemaVersion !== RECEIPT_SCHEMA
+    || !SHA256.test(String(receipt.snapshotDigest)) || !SHA256.test(String(receipt.fileManifestDigest))
+    || !SHA256.test(String(receipt.receiptDigest)) || !/^[0-9a-f]{32}$/.test(String(receipt.repositoryDigest))
+    || receipt.contractDigest !== null && receipt.contractDigest !== undefined && !SHA256.test(String(receipt.contractDigest))) {
+    mutationFail14('ENTROROVE_RECEIPT_INVALID', 'snapshot receipt fields are invalid');
+  }
+  for (const field of ['snapshotId', 'flowId', 'stepId']) mutationId14(receipt[field], field);
+  const paths = mutationPaths14(receipt.paths);
+  if (canonical(paths) !== canonical(receipt.paths)) mutationFail14('ENTROROVE_RECEIPT_INVALID', 'snapshot receipt paths must be sorted');
+  const core = receiptCore(receipt);
+  if (receipt.receiptDigest !== sha256(canonical(core))) mutationFail14('ENTROROVE_RECEIPT_INVALID', 'snapshot receipt digest is invalid');
+  return { ...core, paths: [...paths], receiptDigest: receipt.receiptDigest };
+}
+async function location(input, root, binding = input) {
+  for (const field of ['flowId', 'stepId', 'snapshotId']) mutationId14(binding[field], field);
+  const stateRoot = await mutationStateRoot14(input);
+  const snapshotRoot = path.join(stateRoot, 'snapshots', repoKey(root), binding.flowId, binding.snapshotId);
+  return { stateRoot, snapshotRoot, manifestPath: path.join(snapshotRoot, 'manifest.json') };
+}
+function checkManifest(manifest, root, binding) {
+  const integrity = verifySnapshotManifest(manifest, { snapshotId: binding.snapshotId, flowId: binding.flowId,
+    stepId: binding.stepId, repositoryDigest: repoKey(root) });
+  if (!integrity.verified) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', integrity.reason ?? 'snapshot manifest is invalid');
+  if (canonical(mutationPaths14(manifest.paths)) !== canonical(manifest.paths)) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'snapshot paths are invalid');
+  layoutBinding(manifest);
+  for (const file of manifest.files) {
+    if (file.exists ? !Number.isInteger(file.mode) || file.mode < 0 || file.mode > 0o777
+      : file.mode !== null || file.sha256 !== MISSING_SHA256) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'snapshot file existence or mode binding is invalid');
+  }
+  return manifest;
+}
+function copyRoot(snapshotRoot, manifest) {
+  return manifest.copyLayout === COPY_LAYOUT ? path.join(snapshotRoot, 'files') : snapshotRoot;
+}
+export function snapshotCopyPath14(manifest, snapshotRoot, relative) {
+  layoutBinding(manifest); mutationPath14(relative);
+  if (!Array.isArray(manifest.paths) || !manifest.paths.includes(relative)) mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'copy path is outside its snapshot path set');
+  return path.join(copyRoot(snapshotRoot, manifest), relative);
+}
+async function readCopy(input, snapshotRoot, root, relative) {
+  if (root === snapshotRoot || !await budgetBindingForRead(input)) return mutationRead14(input, root, relative);
+  // The unchanged budget reader recognizes its original snapshot path shape. A
+  // private, transient hardlink preserves that shape and charges the exact copy
+  // bytes under the original source path, including manifest.json user files.
+  const before = await mutationTarget14(root, relative);
+  const stateRoot = await mutationStateRoot14(input);
+  const repository = await mutationRoot14(input.repositoryRoot);
+  mutationId14(input.flowId, 'flowId');
+  const proxyRoot = path.join(stateRoot, 'snapshots', repoKey(repository), input.flowId, `read-${randomUUID()}`);
+  await privateMutationDirectory14(path.dirname(proxyRoot), { privateFrom: stateRoot });
+  const owned = await privateMutationDirectory14(proxyRoot, { exclusive: true, privateFrom: stateRoot });
+  let read;
+  try {
+    const proxy = path.join(proxyRoot, relative);
+    await privateMutationDirectory14(path.dirname(proxy), { privateFrom: stateRoot });
+    await fs.link(before.target, proxy);
+    read = await mutationRead14(input, proxyRoot, relative);
+  } finally { await cleanupMutationDirectory14(owned); }
+  const after = await mutationTarget14(root, relative);
+  if (before.stat.dev !== after.stat.dev || before.stat.ino !== after.stat.ino || read.stat.dev !== after.stat.dev
+    || read.stat.ino !== after.stat.ino || before.stat.size !== after.stat.size || before.stat.mtimeMs !== after.stat.mtimeMs) {
+    mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'snapshot copy changed during its budgeted read');
+  }
+  return { ...read, target: after.target, stat: after.stat, mode: after.stat.mode & 0o777 };
+}
+export async function readSnapshotCopy14(input, snapshotRoot, manifest, relative) {
+  const expected = manifest.files?.find(file => file.path === relative);
+  const target = snapshotCopyPath14(manifest, snapshotRoot, relative);
+  if (!expected || typeof expected.exists !== 'boolean') mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'snapshot copy file entry is invalid');
+  const root = copyRoot(snapshotRoot, manifest); await mutationRoot14(root);
+  const copy = await mutationTarget14(root, relative, true);
+  if (copy.exists !== expected.exists) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', `${relative} snapshot copy existence is invalid`);
+  if (!expected.exists) {
+    if (expected.sha256 !== MISSING_SHA256 || expected.mode !== null) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'missing snapshot copy binding is invalid');
+    return { target, path: relative, exists: false, content: null, sha256: MISSING_SHA256, mode: null, stat: null };
+  }
+  if (!Number.isInteger(expected.mode) || expected.mode < 0 || expected.mode > 0o777) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'snapshot source mode is invalid');
+  const read = await readCopy(input, snapshotRoot, root, relative);
+  if (read.sha256 !== expected.sha256 || read.stat.nlink !== 1) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', `${relative} snapshot copy is invalid`);
+  if (manifest.copyLayout && process.platform !== 'win32' && read.mode !== 0o600) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'snapshot copies must have private file permissions');
+  return { ...read, exists: true, sourceMode: expected.mode };
+}
+export async function preserveSnapshotCopies14(input, snapshotRoot, manifest, destination) {
+  const stateRoot = await mutationStateRoot14(input);
+  await privateMutationDirectory14(copyRoot(destination, manifest), { privateFrom: stateRoot });
+  for (const expected of manifest.files) {
+    const observed = await readSnapshotCopy14(input, snapshotRoot, manifest, expected.path);
+    if (expected.exists) await writeMutationFile14(snapshotCopyPath14(manifest, destination, expected.path),
+      observed.content, { privateFrom: stateRoot });
+  }
+}
+async function copyFacts(input, snapshotRoot, manifest) {
+  const files = [];
+  for (const expected of manifest.files) {
+    await readSnapshotCopy14(input, snapshotRoot, manifest, expected.path);
+    files.push({ path: expected.path, sourceHash: expected.sha256, snapshotHash: expected.sha256 });
+  }
+  return files;
+}
+export async function verifySnapshotSources14(input, root, manifest, { paths = manifest.paths } = {}) {
+  const selected = mutationPaths14(paths);
+  if (selected.some(relative => !manifest.paths.includes(relative))) mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'source verification is outside the snapshot path set');
+  for (const expected of manifest.files.filter(file => selected.includes(file.path))) {
+    const source = await mutationTarget14(root, expected.path, true);
+    if (source.exists !== expected.exists) mutationFail14('ENTROROVE_SNAPSHOT_CHANGED', `${expected.path} changed after snapshot`);
+    if (expected.exists) {
+      const read = await mutationRead14(input, root, expected.path);
+      if (read.sha256 !== expected.sha256 || read.mode !== expected.mode) mutationFail14('ENTROROVE_SNAPSHOT_CHANGED', `${expected.path} changed after snapshot`);
+    } else if (expected.sha256 !== MISSING_SHA256) mutationFail14('ENTROROVE_SNAPSHOT_CORRUPT', 'missing source hash is invalid');
+  }
+}
+async function copySource(input, root, snapshotRoot, relative, stateRoot) {
+  const source = await mutationTarget14(root, relative, true);
+  if (!source.exists) return { path: relative, exists: false, sha256: MISSING_SHA256, mode: null };
+  const read = await mutationRead14(input, root, relative);
+  await writeMutationFile14(path.join(snapshotRoot, 'files', relative), read.content, { privateFrom: stateRoot });
+  return { path: relative, exists: true, sha256: read.sha256, mode: read.mode };
+}
+export async function snapshotPlan14(input, { handoffBinding: binding = {} } = {}) {
+  const root = await mutationRoot14(input.repositoryRoot);
+  const flowId = mutationId14(input.flowId, 'flowId'); const stepId = mutationId14(input.stepId, 'stepId');
+  const paths = mutationPaths14(input.paths); const handoff = handoffBinding(binding);
+  const snapshotId = mutationId14(input.snapshotId ?? `snap-${randomUUID()}`, 'snapshotId');
+  const contractDigest = input.contractDigest ?? null;
+  if (contractDigest !== null && !SHA256.test(contractDigest)) mutationFail14('ENTROROVE_CONTRACT_DIGEST', 'contractDigest must be a lowercase SHA-256 digest');
+  const loc = await location(input, root, { flowId, stepId, snapshotId });
+  await privateMutationDirectory14(path.dirname(loc.snapshotRoot), { privateFrom: loc.stateRoot });
+  const owned = await privateMutationDirectory14(loc.snapshotRoot, { exclusive: true, privateFrom: loc.stateRoot });
+  try {
+    await privateMutationDirectory14(path.join(loc.snapshotRoot, 'files'), { privateFrom: loc.stateRoot });
+    const files = [];
+    for (const relative of paths) files.push(await copySource(input, root, loc.snapshotRoot, relative, loc.stateRoot));
+    const core = { snapshotId, flowId, stepId, paths, files, contractDigest, ...handoff };
+    const manifest = { schemaVersion: SNAPSHOT_SCHEMA, ...core, repositoryDigest: repoKey(root), copyLayout: COPY_LAYOUT,
+      createdAt: new Date().toISOString(), snapshotDigest: sha256(canonical(core)) };
+    await atomicMutationJson14(loc.manifestPath, manifest, { privateFrom: loc.stateRoot });
+    await copyFacts(input, loc.snapshotRoot, manifest);
+    await verifySnapshotSources14(input, root, manifest);
+    return { schemaVersion: LOCAL_SCHEMA, snapshotId, snapshotRoot: loc.snapshotRoot, manifestPath: loc.manifestPath,
+      paths, contractDigest, snapshotDigest: manifest.snapshotDigest, copyLayout: COPY_LAYOUT, forbidGitBranch: true, forbidWorktree: true };
+  } catch (error) {
+    try { await cleanupMutationDirectory14(owned); } catch { /* Preserve the primary error and refuse unsafe cleanup. */ }
+    throw error;
+  }
+}
+export async function snapshotVerify14(input) {
+  const root = await mutationRoot14(input.repositoryRoot); const loc = await location(input, root);
+  const manifest = checkManifest(await readMutationJson14(loc.manifestPath), root, input);
+  const files = await copyFacts(input, loc.snapshotRoot, manifest);
+  await verifySnapshotSources14(input, root, manifest);
+  const core = receiptCore({ ...manifest, fileManifestDigest: sha256(canonical(files)) });
+  const receipt = { ...core, receiptDigest: sha256(canonical(core)) };
+  return { schemaVersion: LOCAL_SCHEMA, verified: true, receipt };
+}
+export async function snapshotAuthority14(input, root, value) {
+  const actualRoot = await mutationRoot14(input.repositoryRoot);
+  if (actualRoot !== root) mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'snapshot authority root differs from its repository binding');
+  const receipt = loadSnapshotReceipt14(value);
+  if (receipt.flowId !== input.flowId || receipt.stepId !== input.stepId || receipt.repositoryDigest !== repoKey(root)
+    || input.snapshotId !== undefined && input.snapshotId !== receipt.snapshotId) mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'snapshot receipt scope is invalid');
+  const loc = await location(input, root, receipt);
+  const manifest = checkManifest(await readMutationJson14(loc.manifestPath), root, receipt);
+  if (manifest.snapshotDigest !== receipt.snapshotDigest || canonical(manifest.paths) !== canonical(receipt.paths)
+    || manifest.contractDigest !== receipt.contractDigest || canonical(handoffBinding(manifest)) !== canonical(handoffBinding(receipt))
+    || canonical(layoutBinding(manifest)) !== canonical(layoutBinding(receipt))) mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'snapshot receipt does not match its manifest or layout');
+  const files = await copyFacts(input, loc.snapshotRoot, manifest);
+  if (receipt.fileManifestDigest !== sha256(canonical(files))) mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'snapshot receipt file manifest digest is invalid');
+  return { manifest, manifestPath: loc.manifestPath, snapshotRoot: loc.snapshotRoot, copyRoot: copyRoot(loc.snapshotRoot, manifest) };
+}

package/local-mutation-wire.mjs

@@ -0,0 +1,89 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { canonicalHandoffSignature } from './local-task-handoff-overlay-wire.mjs';
+import { mutationFail14, mutationPaths14 } from './local-mutation-files.mjs';
+
+export const MUTATION_IDENTITY_FIELDS14 = ['flowId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'chainRevision',
+  'acceptanceReceiptId', 'acceptanceDigest', 'routeDigest', 'receiver', 'receiverDigest', 'stepId', 'leaseId', 'leaseDigest',
+  'generation', 'planId', 'planDigest', 'executionPlanSha256', 'executionAuthorityId', 'executionAuthorityDigest',
+  'executionAttemptNonce', 'epoch', 'runnerId', 'runnerKeyId', 'repositoryId', 'repositoryDigest', 'scopeBindingDigest',
+  'scopeArtifactDigest', 'scopeContractDigest', 'paths', 'newFilePaths', 'issuedAt', 'expiresAt'];
+const CHALLENGE_FIELDS = ['schemaVersion', 'challengeId', 'snapshotId', 'nonce', ...MUTATION_IDENTITY_FIELDS14];
+const PASS_FIELDS = ['schemaVersion', 'passId', 'challengeId', 'challengeDigest', 'challengeNonce', 'snapshotId', 'nonce',
+  ...MUTATION_IDENTITY_FIELDS14, 'handoffEpoch', 'snapshotDigest', 'snapshotReceiptDigest', 'snapshotReceipt',
+  'snapshotManifestDigest', 'attestationDigest', 'coordinationRequired'];
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const SHA = /^[0-9a-f]{64}$/;
+function exact(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('\0') !== [...fields].sort().join('\0')) {
+    mutationFail14('ENTROROVE_MUTATION_AUTHORITY_INVALID', 'Mutation authority has invalid fields');
+  }
+}
+export function mutationLifetime14(value, { live = true } = {}) {
+  const start = Date.parse(value.issuedAt), end = Date.parse(value.expiresAt);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || new Date(start).toISOString() !== value.issuedAt
+    || new Date(end).toISOString() !== value.expiresAt || start > Date.now() || end <= start || end - start > 90_000
+    || live && end <= Date.now()) mutationFail14('ENTROROVE_MUTATION_AUTHORITY_EXPIRED', 'Mutation authority is expired or has invalid issuance');
+}
+function pinnedAuthority() {
+  try {
+    const encoded = process.env.ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY;
+    if (!encoded) throw new Error();
+    const der = Buffer.from(encoded, 'base64'), key = createPublicKey({ key: der, type: 'spki', format: 'der' });
+    if (key.asymmetricKeyType !== 'ed25519' || key.export({ type: 'spki', format: 'der' }).toString('base64') !== encoded) throw new Error();
+    return { key, keyId: sha256(der) };
+  } catch { mutationFail14('ENTROROVE_MUTATION_AUTHORITY_INVALID', 'Pinned cloud mutation authority is unavailable or invalid'); }
+}
+function identity(payload) {
+  const ids = ['flowId', 'taskId', 'acceptanceReceiptId', 'stepId', 'leaseId', 'planId', 'executionAuthorityId',
+    'executionAttemptNonce', 'runnerId', 'repositoryId', 'snapshotId', 'nonce', 'challengeId'];
+  const digests = ['taskDigest', 'chainDigest', 'acceptanceDigest', 'routeDigest', 'receiverDigest', 'leaseDigest',
+    'planDigest', 'executionPlanSha256', 'executionAuthorityDigest', 'runnerKeyId', 'scopeBindingDigest',
+    'scopeArtifactDigest', 'scopeContractDigest'];
+  if (ids.some(field => typeof payload[field] !== 'string' || !ID.test(payload[field]))
+    || digests.some(field => typeof payload[field] !== 'string' || !SHA.test(payload[field]))
+    || !/^[0-9a-f]{32}$/.test(payload.repositoryDigest) || !/^[0-9a-f-]{36}$/.test(payload.ownerId)
+    || !Number.isSafeInteger(payload.epoch) || payload.epoch < 0
+    || ['generation', 'chainRevision'].some(field => !Number.isSafeInteger(payload[field]) || payload[field] < 1)) {
+    mutationFail14('ENTROROVE_MUTATION_AUTHORITY_INVALID', 'Mutation authority identity is invalid');
+  }
+  const paths = mutationPaths14(payload.paths);
+  if (canonical(paths) !== canonical(payload.paths) || !Array.isArray(payload.newFilePaths)
+    || payload.newFilePaths.some(value => !paths.includes(value)) || new Set(payload.newFilePaths).size !== payload.newFilePaths.length
+    || canonical([...payload.newFilePaths].sort()) !== canonical(payload.newFilePaths)) {
+    mutationFail14('ENTROROVE_MUTATION_AUTHORITY_INVALID', 'Mutation authority path set is invalid');
+  }
+  exact(payload.receiver, ['taskId', 'ownerId', 'projectId', 'hostId', 'threadId', 'descriptionDigest', 'taskDigest']);
+  if (payload.receiver.taskId !== payload.taskId || payload.receiver.ownerId !== payload.ownerId
+    || payload.receiver.taskDigest !== payload.taskDigest || !SHA.test(payload.receiver.descriptionDigest)
+    || sha256(canonical(payload.receiver)) !== payload.receiverDigest
+    || ['projectId', 'hostId', 'threadId'].some(field => !ID.test(String(payload.receiver[field])))) {
+    mutationFail14('ENTROROVE_MUTATION_AUTHORITY_INVALID', 'Mutation authority lost its original cloud receiver');
+  }
+}
+function authority(value, fields, schema, options) {
+  exact(value, [...fields, 'authorityReceipt']);
+  const { authorityReceipt: receipt, ...payload } = value;
+  exact(receipt, ['schemaVersion', 'keyId', 'payloadDigest', 'signature']);
+  const bytes = Buffer.from(canonical(payload)), key = pinnedAuthority();
+  let signature; try { signature = canonicalHandoffSignature(receipt.signature); }
+  catch { mutationFail14('ENTROROVE_MUTATION_AUTHORITY_INVALID', 'Cloud mutation signature encoding is invalid'); }
+  if (payload.schemaVersion !== schema || bytes.length > 1024 * 1024
+    || receipt.schemaVersion !== 'entrorove.workflow-authority-receipt/1.0' || receipt.keyId !== key.keyId
+    || receipt.payloadDigest !== sha256(bytes) || !verify(null, bytes, key.key, signature)) {
+    mutationFail14('ENTROROVE_MUTATION_AUTHORITY_INVALID', 'Mutation authority requires a valid pinned cloud signature');
+  }
+  identity(payload); mutationLifetime14(payload, options); return value;
+}
+export function mutationChallenge14(value, options) {
+  return authority(value, CHALLENGE_FIELDS, 'entrorove.mutation-snapshot-challenge/1.0', options);
+}
+export function mutationPass14(value, options) {
+  const pass = authority(value, PASS_FIELDS, 'entrorove.mutation-pass/1.0', options);
+  if (!ID.test(pass.passId) || !ID.test(pass.challengeNonce) || pass.handoffEpoch !== pass.epoch || pass.coordinationRequired !== false
+    || ['challengeDigest', 'snapshotDigest', 'snapshotReceiptDigest', 'snapshotManifestDigest', 'attestationDigest'].some(field => !SHA.test(pass[field]))) {
+    mutationFail14('ENTROROVE_MUTATION_AUTHORITY_INVALID', 'Mutation pass has invalid snapshot or original epoch bindings');
+  }
+  return pass;
+}

package/local-probe.mjs

@@ -1,13 +1,135 @@
-import { promises as fs } from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
+import { operationSchemasFor } from './local-contracts.mjs';
+import { observedGoalRisk, observedScopeRisk, scopeFail, scopeRoot, scopeDigest } from './local-scope-files.mjs';
+import { collectScopeFacts } from './local-scope-repository.mjs';
+import { initializeScope, retainedScope, scopeBinding, upgradeScope } from './local-scope-state.mjs';
+import { sha256 } from './local-integrity.mjs';
+import { attestScopeFacts } from './local-scope-signature.mjs';
+import { resolveScopePaths } from './local-scope-context.mjs';
+import { readScopeSnapshot, verifyFreshScopeSnapshot } from './local-scope-snapshot.mjs';
+import { rejectScopePrivileges, verifiedScopeCandidate } from './local-scope-candidate.mjs';
+import { budgetBindingForRead } from './local-budget-reads.mjs';
+import { budgetLocation, loadBudget } from './local-budget-store.mjs';
 
-const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
-function safe(value) { if (typeof value !== 'string' || !value || value !== value.normalize('NFC') || path.isAbsolute(value) || value.includes('\\') || /[\u0000-\u001f\u007f]/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..')) fail('ENTROROVE_PATH_UNSAFE', 'probe path is unsafe'); return value; }
-async function root(value) { if (typeof value !== 'string' || !path.isAbsolute(value)) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute'); const stat = await fs.lstat(value); if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be a real directory'); return fs.realpath(value); }
-async function filesUnder(rootPath, relative, result = []) { const target = path.resolve(rootPath, ...safe(relative).split('/')); const stat = await fs.lstat(target); if (stat.isSymbolicLink()) fail('ENTROROVE_FILE_INVALID', 'probe refuses symlinks'); if (stat.isFile()) { result.push({ path: relative, bytes: stat.size }); return result; } if (!stat.isDirectory()) fail('ENTROROVE_FILE_INVALID', 'probe path is not a file or directory'); for (const name of await fs.readdir(target)) if (!['.git', 'node_modules', '.entrorove', '.aimlock', '.archguard'].includes(name)) await filesUnder(rootPath, `${relative}/${name}`, result); return result; }
-export async function probe(input) { const rootPath = await root(input.repositoryRoot); const requested = input.paths ?? input.targetPaths ?? ['.']; const paths = requested.length === 1 && requested[0] === '.' ? (await fs.readdir(rootPath)).filter(name => !['.git', 'node_modules', '.entrorove'].includes(name)).map(name => name) : requested.map(safe); const files = []; for (const relative of paths) await filesUnder(rootPath, relative, files); const fileCount = files.length; const bytes = files.reduce((total, file) => total + file.bytes, 0); const lines = Math.ceil(bytes / 4); const mode = fileCount <= 1 && lines <= 500 ? 'lock' : fileCount <= 3 && lines <= 500 ? 'probe' : 'swarm'; return { schemaVersion: 'entrorove.local-execution/1.0', status: 'verified', repositoryRoot: rootPath, facts: { fileCount, bytes, tokenEstimate: lines, files: files.sort((left, right) => left.path.localeCompare(right.path)) }, classification: { mode, reason: mode === 'swarm' ? 'more than three files or over the 500-line budget' : mode === 'probe' ? 'bounded multi-file read' : 'single-file read' }, forbidGitBranch: true, forbidWorktree: true }; }
-export async function reassess(input) { const result = await probe(input); const order = ['lock', 'probe', 'swarm']; const requested = input.currentMode ?? result.classification.mode; if (!ID.test(requested) || !order.includes(requested)) fail('ENTROROVE_MODE_INVALID', 'currentMode must be lock, probe, or swarm'); const currentIndex = order.indexOf(requested); const actualIndex = order.indexOf(result.classification.mode); const nextMode = actualIndex > currentIndex ? order[Math.min(currentIndex + 1, order.length - 1)] : requested; return { ...result, operation: 'reassess', previousMode: requested, mode: nextMode, upgraded: nextMode !== requested, preservedSnapshotId: input.snapshotId ?? null }; }
+const types = new Set(['implementation', 'documentation', 'calculation', 'merge', 'review', 'decision', 'diagnosis']);
+const canonicalPaths = files => files.map(file => file.path).join('\0');
+const scopeModes = ['lock', 'probe', 'swarm'];
+export function classifyScope(facts, task) {
+  if (task !== undefined && (!task || typeof task !== 'object' || Array.isArray(task)
+    || !types.has(task.workType) || !['low', 'medium', 'high'].includes(task.difficulty)
+    || !['low', 'medium', 'high'].includes(task.risk) || typeof task.goal !== 'string' || !task.goal.trim())) scopeFail('ENTROROVE_TASK_INVALID', 'scope task requires goal, workType, difficulty, and risk');
+  const crossModule = facts.crossModule || task?.crossModule === true; const parallel = task?.parallel === true || task?.needParallel === true;
+  const overBudget = facts.estimatedChangedLines > 500 || facts.git.binary;
+  const risks = ['low', 'medium', 'high'];
+  const risk = risks[Math.max(risks.indexOf(task?.risk ?? 'low'), risks.indexOf(facts.risk ?? 'low'),
+    risks.indexOf(observedScopeRisk(facts.files)), risks.indexOf(observedGoalRisk(task?.goal ?? '')))];
+  const diagnosis = task?.workType === 'diagnosis';
+  const explicit = task?.explicitAimlockRequested === true || task?.explicitEntroroveRequested === true
+    || (Array.isArray(task?.userSpecifiedSkills) && task.userSpecifiedSkills.some(skill => typeof skill === 'string' && ['aimlock', 'entrorove'].includes(skill.toLowerCase())));
+  const mode = facts.fileCount > 3 || overBudget || crossModule || parallel ? 'swarm' : facts.fileCount > 1 || diagnosis ? 'probe' : 'lock';
+  const bypass = task !== undefined && !diagnosis && task.difficulty === 'low' && !overBudget && !crossModule && risk !== 'high'
+    && !parallel && !explicit && task.unclear !== true && task.architectureContract !== true && facts.importGraph.complete;
+  return { decision: bypass ? 'bypass' : 'active', mode, risk, crossModule, estimatedChangedLines: facts.estimatedChangedLines,
+    reason: bypass ? 'observed bounded low-risk task' : mode === 'swarm' ? 'observed scope, changed lines, package dependencies, or requested parallel work require Swarm'
+      : mode === 'probe' ? 'observed scope contains at most three files through 500 lines' : 'observed scope contains one file through 500 lines',
+    readOnly: ['diagnosis', 'review', 'calculation', 'decision'].includes(task?.workType), writeAllowed: false, workerCount: 0 };
+}
+async function observe(input, retained, fresh = false) {
+  const repositoryRoot = await scopeRoot(input.repositoryRoot);
+  const requested = await resolveScopePaths(input, repositoryRoot);
+  if (requested === undefined) scopeFail('ENTROROVE_SCOPE_EMPTY', 'explicit target paths are required');
+  const original = (!retained || fresh) && input.snapshotId != null ? await readScopeSnapshot(input, repositoryRoot) : null;
+  const facts = await collectScopeFacts(repositoryRoot, requested, input.baselineRef, fresh ? original.known : retained?.history.at(-1).facts.files ?? original?.known, input);
+  const classification = classifyScope(facts, input.task ?? retained?.originalTask ?? undefined);
+  return { schemaVersion: 'entrorove.local-execution/1.0', status: 'reported', repositoryRoot,
+    repositoryDigest: sha256(repositoryRoot).slice(0, 32), facts, factsDigest: scopeDigest(facts), classification,
+    forbidGitBranch: true, forbidWorktree: true, trusted: false };
+}
+async function handoffReadBudget(input) {
+  const binding = await budgetBindingForRead(input);
+  if (!binding) return false;
+  const loaded = await loadBudget(await budgetLocation(binding));
+  return loaded.state.enforced && loaded.state.grant?.purpose === 'handoff-read';
+}
+async function probeHandoffCandidate(input, root, candidate) {
+  scopeBinding(input);
+  const native = await import('./local-task-handoff-read-authority.mjs');
+  const readHome = await native.assertTaskHandoffReadHome({ ...input, taskId: candidate.receiverTaskId, ownerId: candidate.ownerId });
+  if (readHome.epoch !== candidate.receiverEpoch - 1 || readHome.mutationAllowed !== false) {
+    scopeFail('ENTROROVE_SCOPE_CANDIDATE_BINDING', 'candidate observation requires its actual current read-only receiver home');
+  }
+  const result = await observe(input, null, true);
+  result.classification.decision = 'active';
+  result.facts.snapshotEvidence = await verifyFreshScopeSnapshot(input, root, result.facts);
+  result.factsDigest = scopeDigest(result.facts);
+  await verifiedScopeCandidate(input, root, result.facts.snapshotEvidence.manifest);
+  return attestScopeFacts(input, { ...result, scopePurpose: 'handoff-candidate',
+    requiredMode: result.classification.mode, snapshotDigest: result.facts.snapshotEvidence.snapshotDigest,
+    preservedSnapshotDigest: null, preservedSnapshotId: null, currentSnapshotFresh: true,
+    receiverOrigin: { flowId: candidate.flowId, taskId: candidate.receiverTaskId,
+      scopeDigest: candidate.receiverOriginalScopeDigest, checkpointDigest: candidate.receiverCheckpointDigest,
+      acceptanceReceiptId: candidate.receiverAcceptanceReceiptId, sourceCopiesVerified: false } });
+}
+export async function probe(input) {
+  rejectScopePrivileges(input);
+  const root = await scopeRoot(input.repositoryRoot);
+  const candidate = await verifiedScopeCandidate(input, root);
+  if (candidate && await handoffReadBudget(input)) return probeHandoffCandidate(input, root, candidate);
+  const hasBinding = ['flowId', 'stepId', 'snapshotId'].some(field => input[field] !== undefined);
+  const retained = hasBinding ? await retainedScope(input, root, true) : null;
+  const fresh = !!candidate || (!!retained && retained.stepId !== input.stepId);
+  if (fresh && (!retained || typeof input.signerConfigPath !== 'string' || !input.signerConfigPath || typeof input.challenge !== 'string' || !input.challenge)) {
+    scopeFail('ENTROROVE_SCOPE_ATTESTATION_BINDING', 'a new-step observation requires its preserved original scope, configured signer and new challenge binding');
+  }
+  const result = await observe(input, retained, fresh);
+  if (fresh) result.classification.decision = 'active';
+  if (fresh && !candidate && canonicalPaths(result.facts.files) !== canonicalPaths(retained.history.at(-1).facts.files)) {
+    scopeFail('ENTROROVE_SCOPE_CHANGED', 'fresh original-scope observation cannot replace its original scope paths; reassess growth explicitly');
+  }
+  if (result.classification.decision === 'bypass') return result;
+  if (['flowId', 'stepId', 'snapshotId'].some(field => input[field] !== undefined)) {
+    scopeBinding(input);
+    result.facts.snapshotEvidence = await verifyFreshScopeSnapshot(input, result.repositoryRoot, result.facts);
+    result.factsDigest = scopeDigest(result.facts);
+    if (fresh) {
+      await verifiedScopeCandidate(input, result.repositoryRoot, result.facts.snapshotEvidence.manifest);
+      return attestScopeFacts(input, { ...result, scopePurpose: candidate ? 'handoff-candidate' : 'fresh-observation',
+        revision: retained.revision,
+        classification: { ...result.classification, mode: candidate ? result.classification.mode : retained.mode }, requiredMode: result.classification.mode,
+        originalBinding: { flowId: retained.flowId, stepId: retained.stepId, snapshotId: retained.originalSnapshot.snapshotId },
+        snapshotDigest: result.facts.snapshotEvidence.snapshotDigest, preservedSnapshotDigest: retained.originalSnapshot.digest,
+        preservedSnapshotId: retained.originalSnapshot.snapshotId, currentSnapshotFresh: true });
+    }
+    const saved = await initializeScope(input, result.repositoryRoot, result.facts, result.classification);
+    return attestScopeFacts(input, { ...result, revision: saved.state.revision, statePath: saved.statePath,
+      classification: { ...result.classification, mode: saved.state.mode }, requiredMode: result.classification.mode,
+      snapshotDigest: result.facts.snapshotEvidence.snapshotDigest, preservedSnapshotDigest: saved.state.originalSnapshot.digest,
+      preservedSnapshotId: saved.state.originalSnapshot.snapshotId, currentSnapshotFresh: true });
+  }
+  return attestScopeFacts(input, result);
+}
+function observationReassessment(input, result) {
+  const previousMode = input.currentMode === undefined ? result.classification.mode : input.currentMode;
+  const current = scopeModes.indexOf(previousMode), required = scopeModes.indexOf(result.classification.mode);
+  const mode = required > current ? scopeModes[Math.min(current + 1, scopeModes.length - 1)] : previousMode;
+  return { ...result, operation: 'reassess', previousMode, mode, requiredMode: result.classification.mode,
+    classification: { ...result.classification, mode }, upgraded: mode !== previousMode,
+    preservedSnapshotId: null, currentSnapshotFresh: false };
+}
+export async function reassess(input) {
+  rejectScopePrivileges(input);
+  if (Object.hasOwn(input, 'handoffCandidate')) scopeFail('ENTROROVE_SCOPE_INPUT_INVALID', 'temporary handoff candidates cannot reassess or replace the original scope');
+  if (input.currentMode !== undefined && !scopeModes.includes(input.currentMode)) scopeFail('ENTROROVE_MODE_INVALID', 'currentMode must be lock, probe, or swarm');
+  const bound = ['flowId', 'stepId', 'expectedRevision', 'taskDigest', 'ownerId', 'chainDigest', 'repositoryId', 'challenge']
+    .some(field => input[field] !== undefined) || input.snapshotId != null || input.signerConfigPath != null;
+  if (!bound) return observationReassessment(input, await observe(input, null));
+  scopeBinding(input); const retained = await retainedScope(input, await scopeRoot(input.repositoryRoot));
+  const result = await observe(input, retained);
+  const saved = await upgradeScope(input, result.repositoryRoot, result.facts, result.classification);
+  return { ...result, operation: 'reassess', previousMode: saved.previousMode, mode: saved.mode, requiredMode: saved.requiredMode,
+    classification: { ...result.classification, mode: saved.mode, decision: 'active' }, upgraded: saved.upgraded,
+    revision: saved.state.revision, statePath: saved.statePath, snapshotDigest: saved.state.originalSnapshot.digest,
+    preservedSnapshotId: saved.state.originalSnapshot.snapshotId, preservedFactsDigest: saved.state.originalFactsDigest,
+    historyDigest: saved.state.history.at(-1).recordDigest, currentSnapshotFresh: false };
+}
 export const LOCAL_PROBE_OPERATIONS = Object.freeze({ probe, reassess });
-export const LOCAL_PROBE_SCHEMAS = Object.freeze({ probe: { type: 'object', additionalProperties: false, required: ['repositoryRoot'] }, reassess: { type: 'object', additionalProperties: false, required: ['repositoryRoot', 'currentMode'] } });
+export const LOCAL_PROBE_SCHEMAS = operationSchemasFor(LOCAL_PROBE_OPERATIONS);

package/local-scope-candidate.mjs

@@ -0,0 +1,28 @@
+import { canonical } from './local-integrity.mjs';
+import { scopeFail } from './local-scope-files.mjs';
+import { readTaskHandoffSnapshotBinding } from './local-task-handoff-fence.mjs';
+import { HANDOFF_CANDIDATE_FIELDS, overlayAuthority } from './local-task-handoff-overlay-wire.mjs';
+
+export function rejectScopePrivileges(input) {
+  if (['approved', 'verified', 'accepted', 'trusted', 'writeAllowed', 'pass', 'nonce'].some(field => Object.hasOwn(input, field))) {
+    scopeFail('ENTROROVE_SCOPE_INPUT_INVALID', 'scope observations reject caller approval, execution rights and receipt nonce assertions');
+  }
+}
+export async function verifiedScopeCandidate(input, root, snapshot) {
+  if (!Object.hasOwn(input, 'handoffCandidate')) return null;
+  const candidate = overlayAuthority(input.handoffCandidate, HANDOFF_CANDIDATE_FIELDS, 'entrorove.task-handoff-scope-challenge/1.0');
+  const fields = ['flowId', 'stepId', 'ownerId', 'taskDigest', 'chainDigest', 'repositoryId'];
+  if (fields.some(field => input[field] !== candidate[field]) || input.challenge !== candidate.challengeId
+    || typeof input.signerConfigPath !== 'string' || !input.signerConfigPath
+    || canonical(input.paths) !== canonical(candidate.paths)) scopeFail('ENTROROVE_SCOPE_CANDIDATE_BINDING', 'temporary scope must bind its exact original task, flow, repository, signer and real cloud challenge');
+  const binding = await readTaskHandoffSnapshotBinding({ ...input, repositoryRoot: root });
+  if (binding.handoffEpoch !== candidate.receiverEpoch || binding.handoffBaselineReceiptDigest !== candidate.baselineReceiptDigest) {
+    scopeFail('ENTROROVE_SCOPE_CANDIDATE_BINDING', 'temporary scope requires its registered external runner and current cloud receiver epoch');
+  }
+  if (snapshot && (snapshot.handoffEpoch !== binding.handoffEpoch || snapshot.handoffBaselineReceiptDigest !== binding.handoffBaselineReceiptDigest
+    || canonical(snapshot.paths) !== canonical(candidate.paths) || Date.parse(snapshot.createdAt) < Date.parse(candidate.issuedAt)
+    || !Number.isFinite(Date.parse(snapshot.createdAt)) || Date.parse(snapshot.createdAt) > Date.now())) {
+    scopeFail('ENTROROVE_SCOPE_CANDIDATE_BINDING', 'temporary scope requires actual fresh candidate copies bound to the exact cloud epoch and release baseline');
+  }
+  return candidate;
+}

package/local-scope-context.mjs

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { sha256 } from './local-integrity.mjs';
+import { scopeFail, scopePath, scopeRead } from './local-scope-files.mjs';
+
+export async function resolveScopePaths(input, root) {
+  const literal = Object.hasOwn(input, 'paths') ? input.paths : input.targetPaths;
+  if (input.targetSymbols === undefined) return literal === undefined
+    && !['flowId', 'stepId'].some(field => input[field] !== undefined) && input.snapshotId == null ? ['.'] : literal;
+  if (!Array.isArray(input.targetSymbols) || !input.targetSymbols.length || input.targetSymbols.some(symbol => typeof symbol !== 'string' || !symbol.trim())) scopeFail('ENTROROVE_CONTEXT_SYMBOL_INVALID', 'targetSymbols must contain exact non-empty symbols');
+  if (typeof input.contextMapPath !== 'string') scopeFail('ENTROROVE_CONTEXT_MAP_REQUIRED', 'exact symbols require a fresh ContextBase map');
+  let map;
+  try { map = JSON.parse((await scopeRead(root, scopePath(input.contextMapPath), input)).content.toString('utf8')); }
+  catch (error) { if (error.code) throw error; scopeFail('ENTROROVE_CONTEXT_MAP_INVALID', 'ContextBase map is invalid JSON'); }
+  if (map.schemaVersion !== 'entrorove.context-map/1.0' || map.repositoryDigest !== sha256(root).slice(0, 32) || !Array.isArray(map.entries)) scopeFail('ENTROROVE_CONTEXT_MAP_INVALID', 'ContextBase map is not bound to this repository');
+  const resolved = [];
+  for (const symbol of input.targetSymbols) {
+    const candidates = map.entries.filter(entry => entry?.symbol === symbol);
+    if (!candidates.length) scopeFail('ENTROROVE_CONTEXT_SYMBOL_MISSING', 'the exact symbol is absent from the map');
+    if (candidates.length !== 1) scopeFail('ENTROROVE_CONTEXT_SYMBOL_AMBIGUOUS', 'the exact symbol has more than one map entry');
+    const entry = candidates[0]; const relative = scopePath(entry.path);
+    const file = await scopeRead(root, relative, input);
+    if (file.sha256 !== entry.fileSha256) scopeFail('ENTROROVE_CONTEXT_MAP_STALE', 'the exact symbol map no longer matches the source hash');
+    resolved.push(relative);
+  }
+  const paths = [...new Set([...(literal ?? []), ...resolved])];
+  if (paths.some(relative => path.isAbsolute(relative))) scopeFail('ENTROROVE_PATH_UNSAFE', 'ContextBase map must contain repository-relative paths');
+  return paths;
+}

package/local-scope-files.mjs

@@ -0,0 +1,106 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { readBudgetedProjectFile } from './local-budget-reads.mjs';
+
+export function scopeFail(code, message) { throw Object.assign(new Error(message), { code }); }
+export function observedScopeRisk(files) {
+  return files.some(file => /(?:^|\/)(?:auth|authentication|authorization|sessions?|secrets?|credentials?|payments?|billing|migrations?|sql|deploy(?:ment)?)(?:\/|[.-]|$)/i.test(file.path)
+    || /(?:^|\/)(?:\.env(?:\..*)?|[^/]*\.(?:pem|key))$/i.test(file.path)) ? 'high' : 'low';
+}
+export function observedGoalRisk(goal) {
+  return /生产数据|支付|用户隐私|财务|密码|密钥|线上环境|\b(?:production|payments?|billing|passwords?|secrets?|credentials?|financial|privacy)\b/i.test(goal) ? 'high' : 'low';
+}
+export function scopePath(value) {
+  if (typeof value !== 'string' || !value || value !== value.normalize('NFC') || path.isAbsolute(value)
+    || /^[A-Za-z]:/.test(value) || value.includes('\\') || /[\u0000-\u001f\u007f]/.test(value)
+    || value.split('/').some(part => !part || part === '.' || part === '..')) scopeFail('ENTROROVE_PATH_UNSAFE', 'scope path is unsafe');
+  return value;
+}
+export async function scopeRoot(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value)) scopeFail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute');
+  const stat = await fs.lstat(value);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) scopeFail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be a real directory');
+  return fs.realpath(value);
+}
+export async function scopeTarget(root, relative, allowMissing = false) {
+  let current = root;
+  const parts = scopePath(relative).split('/');
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part);
+    let stat;
+    try { stat = await fs.lstat(current); } catch (error) {
+      if (error.code === 'ENOENT' && allowMissing) return { target: path.join(root, relative), exists: false, stat: null };
+      throw error;
+    }
+    if (stat.isSymbolicLink() || (index < parts.length - 1 && !stat.isDirectory())) scopeFail('ENTROROVE_FILE_INVALID', 'scope refuses symlink or non-directory ancestors');
+    if (index === parts.length - 1) return { target: current, exists: true, stat };
+  }
+}
+async function safeScopeRead(root, relative, input) {
+  const target = await scopeTarget(root, relative);
+  if (!target.stat.isFile()) scopeFail('ENTROROVE_FILE_INVALID', 'scope source must be a regular file');
+  if (target.stat.size > 16_777_216) scopeFail('ENTROROVE_SCOPE_LIMIT', 'scope source exceeds the 16 MiB inspection bound');
+  const handle = await fs.open(target.target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = await handle.stat();
+    const content = input ? await readBudgetedProjectFile(input, target.target, { sourcePath: relative }) : await handle.readFile();
+    const after = await handle.stat();
+    const latest = await fs.lstat(target.target);
+    if (before.ino !== target.stat.ino || before.dev !== target.stat.dev || after.size !== before.size
+      || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || latest.ino !== after.ino
+      || latest.dev !== after.dev || latest.isSymbolicLink()) scopeFail('ENTROROVE_SCOPE_CHANGED', 'scope source changed during inspection');
+    await scopeTarget(root, relative);
+    return { content, mode: after.mode & 0o777, sha256: sha256(content), bytes: content.length };
+  } finally { await handle.close(); }
+}
+export const scopeRead = (root, relative, input = { repositoryRoot: root }) => safeScopeRead(root, relative, input);
+// Internal control roles only: signed manifest metadata and already validated private signer files.
+export const scopeControlRead = (root, relative) => safeScopeRead(root, relative, null);
+const excluded = new Set(['.git', 'node_modules', '.entrorove', '.aimlock', '.archguard']);
+export async function scopeFiles(root, requested, knownFiles = []) {
+  if (!Array.isArray(requested) || !requested.length) scopeFail('ENTROROVE_SCOPE_EMPTY', 'a non-empty target scope is required');
+  const found = new Set(); const known = new Set(knownFiles.map(file => file.path)); let visited = 0;
+  async function visit(relative) {
+    if (++visited > 10_000) scopeFail('ENTROROVE_SCOPE_LIMIT', 'scope exceeds the bounded path inspection limit');
+    const item = await scopeTarget(root, relative, known.has(relative));
+    if (!item.exists) { found.add(relative); return; }
+    if (item.stat.isFile()) { found.add(relative); return; }
+    if (!item.stat.isDirectory()) scopeFail('ENTROROVE_FILE_INVALID', 'scope target must be a regular file or directory');
+    for (const name of (await fs.readdir(item.target)).sort()) if (!excluded.has(name)) await visit(`${relative}/${name}`);
+  }
+  for (const relative of known) if (requested.some(target => target === '.' || target === relative || relative.startsWith(`${target}/`))) found.add(relative);
+  for (const relative of requested) {
+    if (relative === '.') {
+      for (const name of (await fs.readdir(root)).sort()) if (!excluded.has(name)) await visit(name);
+    } else await visit(scopePath(relative));
+  }
+  if (!found.size) scopeFail('ENTROROVE_SCOPE_EMPTY', 'target scope contains no files');
+  return [...found].sort();
+}
+export function lineCount(content) {
+  if (!content.length) return 0;
+  return content.toString('utf8').split(/\r\n|\n|\r/).length - (/[\r\n]$/.test(content.toString('utf8')) ? 1 : 0);
+}
+export async function packageBoundary(root, relative, input = { repositoryRoot: root }) {
+  let directory = path.posix.dirname(relative);
+  while (true) {
+    const manifestPath = directory === '.' ? 'package.json' : `${directory}/package.json`;
+    try {
+      const read = await scopeRead(root, manifestPath, input); let manifest;
+      try { manifest = JSON.parse(read.content.toString('utf8')); } catch { scopeFail('ENTROROVE_PACKAGE_INVALID', 'package manifest is not valid JSON'); }
+      return { path: directory, manifestPath, manifestDigest: read.sha256, name: typeof manifest.name === 'string' ? manifest.name : null };
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (directory === '.') break;
+    directory = path.posix.dirname(directory);
+  }
+  return { path: relative.includes('/') ? relative.split('/')[0] : '.', manifestPath: null, manifestDigest: null, name: null };
+}
+export async function stableScope(root, files, input = { repositoryRoot: root }) {
+  for (const file of files) {
+    if (file.exists === false) {
+      if ((await scopeTarget(root, file.path, true)).exists) scopeFail('ENTROROVE_SCOPE_CHANGED', 'a deleted target reappeared during inspection');
+    } else if ((await scopeRead(root, file.path, input)).sha256 !== file.sha256) scopeFail('ENTROROVE_SCOPE_CHANGED', 'scope files changed before the observation completed');
+  }
+}
+export const scopeDigest = value => sha256(canonical(value));