@entrorove/skill 0.1.23 → 0.1.25

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

package/local-scope-git-attributes.mjs

@@ -0,0 +1,200 @@
+import { sealBudgetedGitAttributes } from './local-budget-git-attributes.mjs';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { sha256 } from './local-integrity.mjs';
+import { scopeFail, scopePath, scopeRead, scopeRoot, scopeTarget } from './local-scope-files.mjs';
+
+const objectId = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const unsupported = message => scopeFail('ENTROROVE_GIT_ATTRIBUTES_UNSUPPORTED', message);
+const trimGit = value => value.replace(/^[ \t\r]+|[ \t\r]+$/g, '');
+
+async function inspect(metadata, args, allowed = []) {
+  const value = await metadata(args, allowed);
+  if (value !== null && typeof value !== 'string') scopeFail('ENTROROVE_GIT_FAILED', 'Git attribute metadata is invalid');
+  return value;
+}
+
+async function optionalStat(target) {
+  try { return await fs.lstat(target); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function liveAttribute(root, relative, input) {
+  const target = await scopeTarget(root, relative, true);
+  if (!target.exists) return null;
+  if (!target.stat.isFile()) unsupported('Git attribute source must be a regular file');
+  const result = await scopeRead(root, relative, input);
+  return { content: result.content, evidence: { path: relative, sha256: result.sha256 } };
+}
+
+async function indexAttribute(relative, metadata, readIndexAttribute) {
+  const output = await inspect(metadata, ['ls-files', '--stage', '-z', '--', `:(literal)${relative}`]);
+  if (output === null || (output && !output.endsWith('\0'))) scopeFail('ENTROROVE_GIT_FAILED', 'Git attribute index metadata is unavailable or truncated');
+  let selected;
+  for (const record of output.split('\0').filter(Boolean)) {
+    const separator = record.indexOf('\t');
+    const match = /^([0-7]{6}) ([0-9a-f]+) ([0-3])$/.exec(record.slice(0, separator));
+    if (separator < 0 || !match || !objectId.test(match[2]) || record.slice(separator + 1) !== relative) scopeFail('ENTROROVE_GIT_FAILED', 'Git attribute index metadata is invalid');
+    if (match[3] !== '0') unsupported('Conflicted Git attribute index entries require a controlled stage-two source adapter');
+    if (selected) scopeFail('ENTROROVE_GIT_FAILED', 'Git attribute index metadata repeats stage zero');
+    if (!['100644', '100755'].includes(match[1])) unsupported('Git attribute index source must be a regular blob');
+    selected = { path: relative, mode: match[1], objectId: match[2], commitId: null, sourceKind: 'index' };
+  }
+  if (!selected) return null;
+  if (typeof readIndexAttribute !== 'function') scopeFail('ENTROROVE_BUDGET_SCOPE', 'Git attribute index source requires its original-path controlled reader');
+  const result = await readIndexAttribute(relative, selected);
+  if (!result || !Buffer.isBuffer(result.content) || result.sha256 !== sha256(result.content)) scopeFail('ENTROROVE_GIT_FAILED', 'Git attribute index source returned invalid content evidence');
+  if (result.content.length > 16_777_216) scopeFail('ENTROROVE_SCOPE_LIMIT', 'Git attribute index source exceeds the 16 MiB inspection bound');
+  const digest = createHash(selected.objectId.length === 40 ? 'sha1' : 'sha256').update(`blob ${result.content.length}\0`).update(result.content).digest('hex');
+  if (digest !== selected.objectId) scopeFail('ENTROROVE_GIT_FAILED', 'Git attribute index source does not match its actual object ID');
+  return { content: result.content, evidence: { path: relative, sha256: result.sha256, sourceKind: 'index', mode: selected.mode, objectId: selected.objectId } };
+}
+
+async function containedAttribute(root, candidate, input) {
+  const stat = await optionalStat(candidate);
+  if (!stat) return null;
+  const relative = path.relative(root, candidate);
+  if (!relative || relative === '..' || relative.startsWith('../') || path.isAbsolute(relative) || stat.isSymbolicLink()) scopeFail('ENTROROVE_BUDGET_SCOPE', 'Git attribute source must be an actual root-contained file covered by the read grant');
+  return liveAttribute(root, scopePath(relative), input);
+}
+
+async function configuredAttribute(root, input, metadata) {
+  const configured = await inspect(metadata, ['config', '--null', '--path', '--get', 'core.attributesFile'], [1]);
+  if (configured !== null && (!configured.endsWith('\0') || configured.slice(0, -1).includes('\0'))) scopeFail('ENTROROVE_GIT_FAILED', 'Git attributesFile metadata is invalid');
+  const value = configured === null ? null : configured.slice(0, -1);
+  if (value === '' || (value === null && !process.env.XDG_CONFIG_HOME && !process.env.HOME)) return null;
+  const defaultPath = path.join(process.env.XDG_CONFIG_HOME || path.join(process.env.HOME || '', '.config'), 'git', 'attributes');
+  return containedAttribute(root, path.resolve(root, value ?? defaultPath), input);
+}
+
+async function systemAttribute(root, input, metadata) {
+  const output = await inspect(metadata, ['var', 'GIT_ATTR_SYSTEM'], [1]);
+  if (output === null) return null;
+  if (!output.endsWith('\n') || !output.slice(0, -1) || output.slice(0, -1).includes('\n')) scopeFail('ENTROROVE_GIT_FAILED', 'Git system attribute metadata is invalid');
+  return containedAttribute(root, path.resolve(root, output.slice(0, -1)), input);
+}
+
+function quotedPattern(line) {
+  if (!line.startsWith('"')) {
+    const end = line.search(/[ \t\r]/);
+    return { pattern: end < 0 ? line : line.slice(0, end), rest: end < 0 ? '' : trimGit(line.slice(end)) };
+  }
+  const bytes = [];
+  const escaped = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '\\': 92, '"': 34 };
+  for (let index = 1; index < line.length; index++) {
+    const character = line[index];
+    if (character === '"') {
+      if (line[index + 1] && !/[ \t\r]/.test(line[index + 1])) unsupported('Quoted Git attribute pattern has trailing non-whitespace');
+      let pattern;
+      try { pattern = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.from(bytes)); }
+      catch { unsupported('Git attribute pattern must contain valid UTF-8'); }
+      return { pattern, rest: trimGit(line.slice(index + 1)) };
+    }
+    if (character !== '\\') {
+      const code = line.codePointAt(index);
+      bytes.push(...Buffer.from(String.fromCodePoint(code)));
+      if (code > 0xffff) index++;
+      continue;
+    }
+    const next = line[++index];
+    if (Object.hasOwn(escaped, next)) bytes.push(escaped[next]);
+    else if (/[0-3]/.test(next ?? '') && /^[0-7]{2}$/.test(line.slice(index + 1, index + 3))) {
+      bytes.push(parseInt(line.slice(index, index + 3), 8)); index += 2;
+    } else unsupported('Git attribute pattern contains an unsupported C escape');
+  }
+  unsupported('Git attribute pattern has an unterminated quote');
+}
+
+function gitQuote(value) {
+  const escaped = { '\\': '\\\\', '"': '\\"', '\n': '\\n', '\r': '\\r', '\t': '\\t', '\b': '\\b', '\f': '\\f' };
+  return `"${value.replace(/[\\"\u0000-\u001f\u007f]/g, character => escaped[character] ?? `\\${character.charCodeAt(0).toString(8).padStart(3, '0')}`)}"`;
+}
+
+function prefixPattern(pattern, directory, side) {
+  const base = directory ? `${directory.replace(/[\\*?\[\]]/g, value => `\\${value}`)}/` : '';
+  return `${side}/${base}${pattern.includes('/') ? pattern.replace(/^\//, '') : `**/${pattern}`}`;
+}
+
+function checkedAttributeLine(value) {
+  if (Buffer.byteLength(value, 'utf8') >= 2048) unsupported('Git attribute source or derived line reaches its 2048-byte parser bound');
+  return value;
+}
+
+function deriveAttribute(content, directory, drivers, sourceKind) {
+  if (content.includes(0)) unsupported('Git attribute sources containing NUL require a separate source-kind parser');
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(content); }
+  catch { unsupported('Git attribute source must contain valid UTF-8'); }
+  if (sourceKind !== 'index') text = text.replace(/^\uFEFF/, '');
+  const lines = [];
+  for (const original of text.split('\n')) {
+    checkedAttributeLine(original);
+    const line = trimGit(original);
+    if (!line || line.startsWith('#')) continue;
+    const { pattern, rest } = quotedPattern(line);
+    if (!pattern || pattern.includes('\0') || pattern.startsWith('!')) unsupported('Git attribute source contains an unsupported pattern');
+    const macro = pattern.length > '[attr]'.length && pattern.startsWith('[attr]');
+    if (macro && directory) unsupported('Nested Git attribute macros cannot be promoted into global scratch attributes');
+    for (const attribute of rest.split(/[ \t\r]+/).filter(Boolean)) {
+      if (attribute.startsWith('filter=')) unsupported('Git attribute filters require a separately controlled conversion adapter');
+      if (!attribute.startsWith('diff=')) continue;
+      const name = attribute.slice(5);
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) unsupported('Git diff driver name is outside the fixed metadata getter contract');
+      drivers.add(name);
+    }
+    if (macro) lines.push(checkedAttributeLine(`${gitQuote(pattern)}${rest ? ` ${rest}` : ''}`));
+    else if (rest) for (const side of ['before', 'after']) lines.push(checkedAttributeLine(`${gitQuote(prefixPattern(pattern, directory, side))} ${rest}`));
+  }
+  return lines;
+}
+
+export { deriveAttribute as deriveBudgetGitAttributeSource };
+
+function ancestorAttributes(paths) {
+  const directories = new Set(['']);
+  for (const relative of paths) {
+    const parts = relative.split('/');
+    for (let index = 1; index < parts.length; index++) directories.add(parts.slice(0, index).join('/'));
+  }
+  return [...directories].sort((left, right) => left.split('/').length - right.split('/').length || (left < right ? -1 : left > right ? 1 : 0));
+}
+
+async function binaryDrivers(names, metadata) {
+  const result = [];
+  for (const name of [...names].sort()) {
+    const output = await inspect(metadata, ['config', '--bool', '--get', `diff.${name}.binary`], [1]);
+    if (output === null) continue;
+    const value = output.trim();
+    if (!['true', 'false'].includes(value)) scopeFail('ENTROROVE_GIT_FAILED', 'Git diff binary configuration is invalid');
+    result.push({ name, binary: value === 'true' });
+  }
+  return result;
+}
+
+/** Internal options select Git command direction; never take them from the public task input. */
+export async function captureScopeGitAttributes(root, paths, input, metadata, readIndexAttribute, options = {}) {
+  if (!Array.isArray(paths) || !paths.length) scopeFail('ENTROROVE_SCOPE_EMPTY', 'Git attributes require a non-empty target scope');
+  const requested = [...new Set(paths.map(scopePath))];
+  if (typeof metadata !== 'function') scopeFail('ENTROROVE_GIT_FAILED', 'Git attributes require a metadata adapter');
+  if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(key => key !== 'indexFallback')
+    || (Object.hasOwn(options, 'indexFallback') && typeof options.indexFallback !== 'boolean')) scopeFail('ENTROROVE_GIT_FAILED', 'Git attribute capture options are invalid');
+  const canonicalRoot = await scopeRoot(root);
+  const gitDirectory = await optionalStat(path.join(canonicalRoot, '.git'));
+  if (!gitDirectory?.isDirectory() || gitDirectory.isSymbolicLink()) scopeFail('ENTROROVE_BUDGET_SCOPE', 'Git attribute capture requires an actual root-contained Git directory');
+  const sources = [];
+  const system = await systemAttribute(canonicalRoot, input, metadata);
+  if (system) sources.push({ ...system, directory: '' });
+  const configured = await configuredAttribute(canonicalRoot, input, metadata);
+  if (configured) sources.push({ ...configured, directory: '' });
+  for (const directory of ancestorAttributes(requested)) {
+    const relative = directory ? `${directory}/.gitattributes` : '.gitattributes';
+    const source = await liveAttribute(canonicalRoot, relative, input) ?? (options.indexFallback === false ? null : await indexAttribute(relative, metadata, readIndexAttribute));
+    if (source) sources.push({ ...source, directory });
+  }
+  const info = await liveAttribute(canonicalRoot, '.git/info/attributes', input);
+  if (info) sources.push({ ...info, directory: '' });
+  const names = new Set();
+  const lines = sources.flatMap(source => deriveAttribute(source.content, source.directory, names, source.evidence.sourceKind));
+  return { attributeBinding: await sealBudgetedGitAttributes(input, sources), attributes: lines.length ? `${lines.join('\n')}\n` : '', metadata: sources.map(source => source.evidence), binaryDrivers: await binaryDrivers(names, metadata) };
+}

package/local-scope-git-comparison.mjs

@@ -0,0 +1,8 @@
+import { compareBudgetedGitSources } from './local-budget-git-scratch.mjs';
+import { scopeFail } from './local-scope-files.mjs';
+
+export async function compareScopeGitSources(before, after, options) {
+  if (!options || typeof options !== 'object' || !options.input) scopeFail('ENTROROVE_BUDGET_BINDING_REQUIRED', 'Git comparison needs its original home, flow and repository input');
+  const { input, ...metadata } = options;
+  return compareBudgetedGitSources(input, before, after, metadata);
+}

package/local-scope-git-history.mjs

@@ -0,0 +1,72 @@
+import { scopeFail, scopePath } from './local-scope-files.mjs';
+
+const objectId = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+async function inspect(metadata, args) {
+  const output = await metadata(args, []);
+  if (typeof output !== 'string') scopeFail('ENTROROVE_GIT_FAILED', 'Git history metadata is unavailable');
+  return output;
+}
+
+function selectedPath(value, paths) {
+  return paths.some(selected => value === selected || value.startsWith(`${selected}/`));
+}
+
+function checkedPaths(files) {
+  if (!Array.isArray(files) || !files.length) scopeFail('ENTROROVE_SCOPE_EMPTY', 'Git history requires a non-empty target scope');
+  return [...new Set(files.map(scopePath))].sort();
+}
+
+export async function readScopeGitTree(commit, requested, metadata) {
+  const paths = checkedPaths(requested);
+  if (typeof commit !== 'string' || !objectId.test(commit) || typeof metadata !== 'function') scopeFail('ENTROROVE_GIT_FAILED', 'Git tree requires a valid object ID and metadata adapter');
+  const output = await inspect(metadata, ['ls-tree', '-r', '-z', '--full-tree', commit, '--', ...paths.map(value => `:(literal)${value}`)]);
+  if (output && !output.endsWith('\0')) scopeFail('ENTROROVE_GIT_FAILED', 'Git tree metadata is truncated');
+  const entries = [];
+  for (const record of output.split('\0').filter(Boolean)) {
+    const separator = record.indexOf('\t');
+    const match = /^([0-7]{6}) (blob|tree|commit) ([0-9a-f]+)$/.exec(record.slice(0, separator));
+    if (separator < 0 || !match || !objectId.test(match[3])) scopeFail('ENTROROVE_GIT_FAILED', 'Git tree metadata is invalid');
+    const relative = scopePath(record.slice(separator + 1));
+    if (!selectedPath(relative, paths)) scopeFail('ENTROROVE_GIT_FAILED', 'Git tree metadata exceeds the requested scope');
+    if (match[2] === 'blob') entries.push({ path: relative, mode: match[1], objectId: match[3], commitId: commit });
+  }
+  entries.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+  if (entries.some((entry, index) => index > 0 && entry.path === entries[index - 1].path)) scopeFail('ENTROROVE_GIT_FAILED', 'Git tree metadata repeats a path');
+  return entries;
+}
+
+function sameTree(before, after) {
+  return before.length === after.length && before.every((entry, index) => entry.path === after[index].path
+    && entry.mode === after[index].mode && entry.objectId === after[index].objectId);
+}
+
+async function commitStat(commit, paths, metadata, compare) {
+  const lineage = (await inspect(metadata, ['rev-list', '--parents', '-n', '1', commit])).trim().split(/\s+/);
+  if (lineage[0] !== commit || lineage.some(value => !objectId.test(value))) scopeFail('ENTROROVE_GIT_FAILED', 'Git commit ancestry is invalid');
+  const after = await readScopeGitTree(commit, paths, metadata);
+  let before = [];
+  for (const [index, parent] of lineage.slice(1).entries()) {
+    const parentEntries = await readScopeGitTree(parent, paths, metadata);
+    // Git's path-limited show suppresses a merge TREESAME to any parent for the whole selected set.
+    if (sameTree(parentEntries, after)) return { commit, changedLines: 0, binary: false };
+    if (index === 0) before = parentEntries;
+  }
+  if (sameTree(before, after)) return { commit, changedLines: 0, binary: false };
+  const result = await compare(before, after);
+  if (!result || !Number.isSafeInteger(result.lines) || result.lines < 0 || typeof result.binary !== 'boolean'
+    || typeof result.present !== 'boolean') scopeFail('ENTROROVE_GIT_FAILED', 'Git history comparison returned invalid facts');
+  return { commit, changedLines: result.lines, binary: result.binary };
+}
+
+/** Metadata never reads blobs; compare owns all source reads and their original-path budget bindings. */
+export async function collectBudgetGitHistory(files, metadata, compare) {
+  const paths = checkedPaths(files);
+  if (typeof metadata !== 'function' || typeof compare !== 'function') scopeFail('ENTROROVE_GIT_FAILED', 'Git history requires metadata and controlled comparison adapters');
+  const output = await inspect(metadata, ['log', '-5', '--format=%H', '--', ...paths.map(value => `:(literal)${value}`)]);
+  const recent = output.trim().split('\n').filter(Boolean);
+  if (recent.length > 5 || recent.some(commit => !objectId.test(commit)) || new Set(recent).size !== recent.length) scopeFail('ENTROROVE_GIT_FAILED', 'Git history metadata is invalid');
+  const commits = [];
+  for (const commit of recent) commits.push(await commitStat(commit, paths, metadata, compare));
+  return { commits, recentChangedLines: Math.max(0, ...commits.map(record => record.changedLines)), binary: commits.some(record => record.binary) };
+}

package/local-scope-git-reads.mjs

@@ -0,0 +1,66 @@
+import { compiledGitSystemAttributes } from './local-budget-git-system-attributes.mjs';
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promisify } from 'node:util';
+import { assertBudgetReadContext } from './local-budget-reads.mjs';
+import { readBudgetedGitBlob } from './local-budget-git.mjs';
+import { scopeFail, scopePath } from './local-scope-files.mjs';
+
+const execute = promisify(execFile), objectIdPattern = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const configFields = new Set(['core.attributesfile', 'core.filemode', 'core.autocrlf', 'core.eol', 'diff.algorithm', 'diff.indentheuristic', 'diff.renames', 'diff.renamelimit']);
+function metadataCommand(args) {
+  if (!Array.isArray(args) || args.some(value => typeof value !== 'string' || /[\0\r\n]/.test(value))) return false;
+  const [command, ...rest] = args;
+  if (command === 'var') return rest.length === 1 && rest[0] === 'GIT_ATTR_SYSTEM';
+  if (command === 'rev-parse') return rest.length === 1 && rest[0] === '--show-toplevel'
+    || rest.length === 2 && rest[0] === '--verify' && !rest[1].startsWith('-');
+  if (command === 'rev-list') return rest.length === 4 && rest[0] === '--parents' && rest[1] === '-n' && rest[2] === '1' && objectIdPattern.test(rest[3]);
+  if (command === 'cat-file') return rest.length === 2 && rest[0] === '-s' && objectIdPattern.test(rest[1]);
+  if (command === 'config') {
+    if (rest.length === 2 && rest[0] === '--get' && configFields.has(rest[1].toLowerCase())) return true;
+    if (rest.join(' ').toLowerCase() === '--null --path --get core.attributesfile') return true;
+    return rest.length === 3 && rest[0] === '--bool' && rest[1] === '--get' && /^diff\.[A-Za-z0-9_.-]+\.binary$/.test(rest[2]);
+  }
+  const separator = rest.indexOf('--');
+  if (separator < 0 || rest.slice(separator + 1).some(value => !value.startsWith(':(literal)'))) return false;
+  for (const value of rest.slice(separator + 1)) scopePath(value.slice(10));
+  const flags = rest.slice(0, separator);
+  if (command === 'ls-files') return ['--cached -z', '--stage -z'].includes(flags.join(' '));
+  if (command === 'log') return flags.join(' ') === '-5 --format=%H';
+  return command === 'ls-tree' && flags.length === 4 && flags.slice(0, 3).join(' ') === '-r -z --full-tree' && objectIdPattern.test(flags[3]);
+}
+function settings(root, control, bytes, encoding) {
+  const deadline = control?.deadlineAt === undefined ? Date.now() + 10000 : Number(control.deadlineAt);
+  if (!Number.isFinite(deadline) || deadline <= Date.now()) scopeFail('ENTROROVE_BUDGET_LEASE_EXPIRED', 'Git source read authorization expired');
+  return { cwd: root, encoding, timeout: Math.max(1, Math.min(10000, deadline - Date.now())), maxBuffer: bytes,
+    signal: control?.signal,
+    env: { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+      GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1' } };
+}
+const safeFlags = ['--no-optional-locks', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-c', 'diff.external='];
+export async function scopeGitMetadata(root, args, input, allowed = []) {
+  await assertBudgetReadContext(input);
+  if (!metadataCommand(args)) scopeFail('ENTROROVE_GIT_FAILED', 'Git metadata command is outside the fixed scope inspection vocabulary');
+  try { return (await execute('/usr/bin/git', [...safeFlags, ...args], settings(root, null, 2097152, 'utf8'))).stdout; }
+  catch (error) {
+    if (error.code === 129 && args.length === 2 && args[0] === 'var' && args[1] === 'GIT_ATTR_SYSTEM') {
+      return `${await compiledGitSystemAttributes()}\n`;
+    }
+    if (allowed.includes(error.code)) return null;
+    scopeFail('ENTROROVE_GIT_FAILED', 'Git metadata inspection failed or exceeded its execution bound');
+  }
+}
+export async function readScopeGitBlob(root, entry, input) {
+  const relative = scopePath(entry.path);
+  if (!objectIdPattern.test(entry.objectId)) scopeFail('ENTROROVE_GIT_SOURCE_INVALID', 'Git source needs a validated immutable object');
+  const size = (await scopeGitMetadata(root, ['cat-file', '-s', entry.objectId], input)).trim();
+  if (!/^(?:0|[1-9][0-9]*)$/.test(size) || !Number.isSafeInteger(Number(size))) scopeFail('ENTROROVE_GIT_SOURCE_INVALID', 'Git blob byte size is invalid');
+  const bytes = Number(size);
+  const descriptor = { path: relative, bytes, objectId: entry.objectId, mode: entry.mode, role: 'git-blob', commitId: entry.commitId ?? null };
+  if (entry.sourceKind === 'index') descriptor.sourceKind = 'index';
+  const content = await readBudgetedGitBlob(input, descriptor);
+  if (!Buffer.isBuffer(content) || content.length !== bytes) scopeFail('ENTROROVE_GIT_SOURCE_INVALID', 'Git blob bytes do not match their actual declared object size');
+  const digest = createHash(entry.objectId.length === 40 ? 'sha1' : 'sha256').update(`blob ${content.length}\0`).update(content).digest('hex');
+  if (digest !== entry.objectId) scopeFail('ENTROROVE_GIT_SOURCE_INVALID', 'Git blob bytes do not match their selected immutable object identity');
+  return { ...entry, content };
+}

package/local-scope-git.mjs

@@ -0,0 +1,124 @@
+import { promises as fs } from 'node:fs';
+import { budgetBindingForRead } from './local-budget-reads.mjs';
+import { budgetLocation, loadBudget } from './local-budget-store.mjs';
+import { compareScopeGitSources } from './local-scope-git-comparison.mjs';
+import { captureScopeGitAttributes } from './local-scope-git-attributes.mjs';
+import { collectBudgetGitHistory, readScopeGitTree } from './local-scope-git-history.mjs';
+import { readScopeGitBlob, scopeGitMetadata } from './local-scope-git-reads.mjs';
+import { scopeFail, scopePath, scopeRead } from './local-scope-files.mjs';
+import { canonical, sha256 } from './local-integrity.mjs';
+
+const oid = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+export async function scopeGitBudgetEnforced(input) {
+  const binding = await budgetBindingForRead(input);
+  return binding !== null && (await loadBudget(await budgetLocation(binding))).state.enforced;
+}
+function emptyGit(available) {
+  return { facts: { available, head: null, baseline: null, currentChangedLines: 0, recentChangedLines: 0,
+    binary: false, commits: [] }, currentDiffPresent: false };
+}
+function readIndex(output, paths) {
+  if (output && !output.endsWith('\0')) scopeFail('ENTROROVE_GIT_FAILED', 'Git index metadata is truncated');
+  const entries = new Map();
+  for (const record of output.split('\0').filter(Boolean)) {
+    const separator = record.indexOf('\t'), match = /^([0-7]{6}) ([0-9a-f]+) ([0-3])$/.exec(record.slice(0, separator));
+    if (!match || separator < 0 || !oid.test(match[2])) scopeFail('ENTROROVE_GIT_FAILED', 'Git index metadata is invalid');
+    const relative = scopePath(record.slice(separator + 1));
+    if (!paths.includes(relative)) scopeFail('ENTROROVE_GIT_FAILED', 'Git index metadata exceeds the selected source scope');
+    if (match[3] !== '0') scopeFail('ENTROROVE_GIT_SOURCE_INVALID', 'Unmerged Git index needs a controlled conflict comparison');
+    if (entries.has(relative)) scopeFail('ENTROROVE_GIT_FAILED', 'Git index metadata repeats a source path');
+    entries.set(relative, { path: relative, mode: match[1], objectId: match[2] });
+  }
+  return entries;
+}
+async function currentEntries(root, files, index, metadata, input) {
+  const configured = (await metadata(['config', '--get', 'core.filemode'], [1]))?.trim();
+  if (configured !== undefined && !['true', 'false'].includes(configured)) scopeFail('ENTROROVE_GIT_FAILED', 'Git filemode metadata is invalid');
+  const result = [];
+  for (const file of files) {
+    const tracked = index.get(file.path);
+    if (file.exists === false || !tracked) continue;
+    const actual = await scopeRead(root, file.path, input);
+    if (actual.sha256 !== file.sha256 || actual.bytes !== file.bytes) scopeFail('ENTROROVE_SCOPE_CHANGED', 'Git current source changed from the actual scope observation');
+    if (!['100644', '100755'].includes(tracked.mode)) scopeFail('ENTROROVE_GIT_SOURCE_INVALID', 'Git current scope requires actual regular files');
+    result.push({ path: file.path, mode: configured === 'false' ? tracked.mode : actual.mode & 0o111 ? '100755' : '100644',
+      objectId: null, commitId: null, content: actual.content });
+  }
+  return result;
+}
+async function diffOptions(metadata, attributes) {
+  const get = async field => (await metadata(['config', '--get', field], [1]))?.trim();
+  const options = { attributes: attributes.attributes, attributeBinding: attributes.attributeBinding, binaryDrivers: attributes.binaryDrivers };
+  const renames = await get('diff.renames'), algorithm = await get('diff.algorithm'), indent = await get('diff.indentheuristic');
+  if (renames !== undefined) {
+    if (!['true', 'false', 'copies', 'copy'].includes(renames)) scopeFail('ENTROROVE_GIT_FAILED', 'Git rename configuration is invalid');
+    options.renames = ['copy', 'copies'].includes(renames) ? 'copies' : renames === 'true';
+  }
+  if (algorithm !== undefined && algorithm !== 'default') options.algorithm = algorithm;
+  if (algorithm === 'default') options.algorithm = 'myers';
+  if (indent !== undefined) {
+    if (!['true', 'false'].includes(indent)) scopeFail('ENTROROVE_GIT_FAILED', 'Git indent configuration is invalid');
+    options.indentHeuristic = indent === 'true';
+  }
+  const autocrlf = await get('core.autocrlf'), eol = await get('core.eol'), renameLimit = await get('diff.renamelimit');
+  if (autocrlf !== undefined) options.autocrlf = autocrlf;
+  if (eol !== undefined) options.eol = eol;
+  if (renameLimit !== undefined) {
+    if (!/^(?:0|[1-9][0-9]*)$/.test(renameLimit) || !Number.isSafeInteger(Number(renameLimit))) scopeFail('ENTROROVE_GIT_FAILED', 'Git rename limit configuration is invalid');
+    options.renameLimit = Number(renameLimit);
+  }
+  return options;
+}
+async function blobEntries(root, entries, input, cache) {
+  const result = [];
+  for (const entry of entries) {
+    const key = `${entry.path}:${entry.mode}:${entry.objectId}`;
+    if (!cache.has(key)) cache.set(key, (await readScopeGitBlob(root, entry, input)).content);
+    result.push({ ...entry, content: cache.get(key) });
+  }
+  return result;
+}
+export async function observeBudgetScopeGit(root, files, baselineRef, input) {
+  const metadata = (args, allowed = []) => scopeGitMetadata(root, args, input, allowed);
+  const top = await metadata(['rev-parse', '--show-toplevel'], [128]);
+  if (top === null) {
+    if (baselineRef) scopeFail('ENTROROVE_GIT_BASELINE', 'baselineRef requires an actual Git repository');
+    return emptyGit(false);
+  }
+  if (await fs.realpath(top.trim()) !== root) scopeFail('ENTROROVE_GIT_ROOT', 'scope root must match the Git repository root');
+  const head = (await metadata(['rev-parse', '--verify', 'HEAD'], [128]))?.trim();
+  if (head === undefined) {
+    if (baselineRef) scopeFail('ENTROROVE_GIT_BASELINE', 'baselineRef requires a resolvable commit');
+    return emptyGit(true);
+  }
+  if (baselineRef !== undefined && (typeof baselineRef !== 'string' || !baselineRef || baselineRef.startsWith('-')
+    || /[\u0000-\u001f]/.test(baselineRef))) scopeFail('ENTROROVE_GIT_BASELINE', 'baselineRef is invalid');
+  const baseline = (await metadata(['rev-parse', '--verify', `${baselineRef ?? 'HEAD'}^{commit}`], [128]))?.trim();
+  if (!oid.test(head) || !oid.test(baseline ?? '')) scopeFail('ENTROROVE_GIT_BASELINE', 'baselineRef must resolve to a real commit');
+  const paths = files.map(file => scopePath(file.path)), cache = new Map();
+  const indexOutput = await metadata(['ls-files', '--stage', '-z', '--', ...paths.map(value => `:(literal)${value}`)]);
+  const index = readIndex(indexOutput, paths);
+  const capture = indexFallback => captureScopeGitAttributes(root, paths, input, metadata, async (_path, entry) => {
+    const actual = await readScopeGitBlob(root, entry, input);
+    return { content: actual.content, sha256: sha256(actual.content) };
+  }, { indexFallback });
+  const attributes = await capture(true), historyAttributes = await capture(false);
+  const options = await diffOptions(metadata, attributes);
+  const historyOptions = await diffOptions(metadata, historyAttributes);
+  const before = await blobEntries(root, await readScopeGitTree(baseline, paths, metadata), input, cache);
+  const after = await currentEntries(root, files, index, metadata, input);
+  const compare = async (left, right, settings, historical = false) => compareScopeGitSources(left, right, { ...settings, input,
+    attributes: `${settings.attributes}before/** -text -working-tree-encoding -filter -ident\n${historical ? 'after/** -text -working-tree-encoding -filter -ident\n' : ''}` });
+  const current = await compare(before, after, options);
+  const history = await collectBudgetGitHistory(paths, metadata, async (left, right) => compare(
+    await blobEntries(root, left, input, cache), await blobEntries(root, right, input, cache), historyOptions, true));
+  const untracked = files.filter(file => file.exists !== false && !index.has(file.path));
+  const untrackedChangedLines = untracked.reduce((total, file) => total + file.lines, 0);
+  if (canonical(await capture(true)) !== canonical(attributes) || canonical(await capture(false)) !== canonical(historyAttributes)
+    || canonical(await diffOptions(metadata, attributes)) !== canonical(options)) scopeFail('ENTROROVE_SCOPE_CHANGED', 'Actual Git attribute sources or diff metadata changed during comparison');
+  if (await metadata(['ls-files', '--stage', '-z', '--', ...paths.map(value => `:(literal)${value}`)]) !== indexOutput
+    || (await metadata(['rev-parse', '--verify', 'HEAD'], [128]))?.trim() !== head) scopeFail('ENTROROVE_SCOPE_CHANGED', 'Git metadata changed during source comparison');
+  return { facts: { available: true, head, baseline, currentChangedLines: current.lines + untrackedChangedLines,
+    untrackedChangedLines, recentChangedLines: history.recentChangedLines, binary: current.binary || history.binary,
+    commits: history.commits }, currentDiffPresent: current.present || untracked.length > 0 };
+}