@entrorove/skill 0.1.22 → 0.1.24

package/local-budget-git-loader.mjs

@@ -0,0 +1,61 @@
+import { spawn, execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { fail, relativePath } from './local-budget-grants.mjs';
+
+const execute = promisify(execFile), oid = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const flags = ['--no-optional-locks', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-c', 'diff.external='];
+function invalid(message) { fail('ENTROROVE_GIT_SOURCE_INVALID', message); }
+export function gitReadExecution(root, deadlineAt, encoding = 'utf8') {
+  const remaining = deadlineAt - Date.now();
+  if (!Number.isFinite(remaining) || remaining <= 0) fail('ENTROROVE_BUDGET_LEASE_EXPIRED', 'fixed Git source authorization expired');
+  return { cwd: root, encoding, timeout: Math.max(1, Math.min(10000, remaining)), maxBuffer: 2097152,
+    killSignal: 'SIGKILL', env: { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(?:GIT_|DYLD_|LD_)/.test(key))),
+      GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1' } };
+}
+export function gitSourceDescriptor(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('\0') !== ['path', 'bytes', 'objectId', 'mode', 'role', 'commitId', ...(value.sourceKind === 'index' ? ['sourceKind'] : [])].sort().join('\0')) invalid('Git blob descriptor must have its exact fixed source fields');
+  const descriptor = structuredClone(value);
+  relativePath(descriptor.path);
+  if (descriptor.role !== 'git-blob' || !oid.test(descriptor.objectId ?? '') || (descriptor.sourceKind === 'index'
+      ? descriptor.commitId !== null : !oid.test(descriptor.commitId ?? '') || descriptor.objectId.length !== descriptor.commitId.length) || !['100644', '100755', '120000'].includes(descriptor.mode)
+    || !Number.isSafeInteger(descriptor.bytes) || descriptor.bytes < 0) invalid('Git blob needs its actual commit, original path, object ID, mode and size');
+  return Object.freeze(descriptor);
+}
+async function metadata(root, args, deadlineAt) {
+  try { return (await execute('/usr/bin/git', [...flags, ...args], gitReadExecution(root, deadlineAt))).stdout; }
+  catch (error) {
+    if (Date.now() >= deadlineAt || error.code === 'ENTROROVE_BUDGET_LEASE_EXPIRED') fail('ENTROROVE_BUDGET_LEASE_EXPIRED', 'fixed Git object metadata authorization expired');
+    fail('ENTROROVE_GIT_FAILED', 'fixed Git object metadata inspection failed');
+  }
+}
+export async function verifyFixedGitBlob(root, descriptor, deadlineAt) {
+  const stat = await fs.lstat(root);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || await fs.realpath(root) !== root) invalid('Git source requires its canonical original repository root');
+  if (await fs.realpath((await metadata(root, ['rev-parse', '--show-toplevel'], deadlineAt)).trim()) !== root) invalid('Git source lost its actual original repository');
+  if (descriptor.sourceKind === 'index') {
+    const index = await metadata(root, ['ls-files', '--stage', '-z', '--', `:(literal)${descriptor.path}`], deadlineAt);
+    if (index !== `${descriptor.mode} ${descriptor.objectId} 0\t${descriptor.path}\0`) invalid('Git source differs from its actual original-path stage-zero index blob');
+  } else {
+    if ((await metadata(root, ['cat-file', '-t', descriptor.commitId], deadlineAt)).trim() !== 'commit') invalid('Git source lost its actual immutable commit');
+    const tree = await metadata(root, ['ls-tree', '-z', '--full-tree', descriptor.commitId, '--', `:(literal)${descriptor.path}`], deadlineAt);
+    if (tree !== `${descriptor.mode} blob ${descriptor.objectId}\t${descriptor.path}\0`) invalid('Git source path, mode or blob differs from its selected commit');
+  }
+  if ((await metadata(root, ['cat-file', '-t', descriptor.objectId], deadlineAt)).trim() !== 'blob'
+    || (await metadata(root, ['cat-file', '-s', descriptor.objectId], deadlineAt)).trim() !== String(descriptor.bytes)) invalid('Git source exact blob type or byte size differs');
+}
+export function fixedGitBlobStream(root, descriptor, deadlineAt) {
+  const child = spawn('/usr/bin/git', [...flags, 'cat-file', 'blob', descriptor.objectId],
+    { ...gitReadExecution(root, deadlineAt, null), stdio: ['ignore', 'pipe', 'pipe'] });
+  child.stderr.resume();
+  const done = new Promise(resolve => { child.once('error', () => resolve(false)); child.once('close', code => resolve(code === 0)); });
+  return { chunks: child.stdout, done, close: () => child.kill('SIGKILL') };
+}
+export function verifyGitBlobBytes(descriptor, content) {
+  const digest = createHash(descriptor.objectId.length === 40 ? 'sha1' : 'sha256')
+    .update(`blob ${content.length}\0`).update(content).digest('hex');
+  if (content.length !== descriptor.bytes || digest !== descriptor.objectId) invalid('actual Git source bytes do not match the immutable selected blob and size');
+}

package/local-budget-git-native-attributes.mjs

@@ -0,0 +1,81 @@
+import { constants, promises as fs } from 'node:fs';
+import { withBudget, loadBudget, commitBudget } from './local-budget-store.mjs';
+import { consumeBudgetRenewal } from './local-budget-renewal.mjs';
+import { assertBudgetReadContext, assertDependencyReadAllowed } from './local-budget-reads.mjs';
+import { fail, requireLiveBudget } from './local-budget-grants.mjs';
+import { validateGitRead } from './local-budget-git.mjs';
+import { fixedNativeRequestStore } from './local-budget-git-native-request.mjs';
+import { assertGitScratchSessionInput, assertGitScratch } from './local-budget-git-scratch-loader.mjs';
+const requests = fixedNativeRequestStore('attributes');
+export async function createFixedNativeAttributeRequest(input, session, request) {
+  await assertGitScratchSessionInput(input, session);
+  if (!session.attributeDescriptors.length) fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'derived native reading requires genuine source segments');
+  return requests.issue(input, session, session.attributeDescriptors[0], request);
+}
+function parts(session, request, length, prior) {
+  const grouped = new Map();
+  for (const descriptor of session.attributeDescriptors) {
+    const start = Math.max(descriptor.start, request.offset), end = Math.min(descriptor.end, request.offset + length);
+    if (end <= start) continue;
+    const part = grouped.get(descriptor.path) ?? { descriptor, bytes: 0, prior: prior.derived?.[descriptor.path] ?? 0, started: Object.hasOwn(prior.derived ?? {}, descriptor.path) };
+    part.bytes += end - start; grouped.set(descriptor.path, part);
+  }
+  return [...grouped.values()].map(part => ({ ...part, tokens: Math.ceil((part.prior + part.bytes) / 4) - Math.ceil(part.prior / 4) }));
+}
+function charge(state, charged) {
+  const files = [...state.files];
+  for (const part of charged) if (!files.includes(part.descriptor.path)) files.push(part.descriptor.path);
+  return { ...state, files, readCalls: state.readCalls + charged.filter(part => !part.started).length,
+    tokenEstimate: state.tokenEstimate + charged.reduce((n, part) => n + part.tokens, 0) };
+}
+async function readActual(session, request, received) {
+  for (const descriptor of session.attributeDescriptors) await assertGitScratch(descriptor);
+  const handle = await fs.open(session.attributes, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat({ bigint: true });
+    if (!stat.isFile() || stat.ino !== session.attributeStat.ino || stat.dev !== session.attributeStat.dev) fail('ENTROROVE_GIT_SOURCE_INVALID', 'derived Git attribute cache changed its actual inode');
+    const capacity = Math.min(request.count, Math.max(0, Number(stat.size) - request.offset)), buffer = Buffer.alloc(capacity);
+    const { bytesRead } = await handle.read(buffer, 0, capacity, request.offset);
+    received.actual = buffer.subarray(0, bytesRead); return received.actual;
+  } finally { await handle.close(); }
+}
+export async function readFixedNativeAttributeChunk(input, session, receipt) {
+  await assertGitScratchSessionInput(input, session);
+  const { request, prior, readId } = await requests.consume(input, session.attributeDescriptors[0], receipt);
+  try { const result = await withBudget(input, async (location, loaded) => {
+    let state = loaded.state, committed = false; const received = { actual: null };
+    if (state.grant?.purpose === 'handoff-read') requireLiveBudget(state); else state = consumeBudgetRenewal({ state });
+    const event = charged => ({ readId, path: charged[0]?.descriptor.path ?? null,
+      bytes: charged.reduce((n, part) => n + part.bytes, 0), actualCacheBytes: received.actual.length,
+      tokens: charged.reduce((n, part) => n + part.tokens, 0), source: { role: 'git-process-derived',
+        native: request, segments: charged.map(part => ({ path: part.descriptor.path, sourceSha256: part.descriptor.sha256,
+          bytes: part.bytes, tokens: part.tokens, start: part.descriptor.start, end: part.descriptor.end })) } });
+    try {
+      await assertBudgetReadContext(input); await assertDependencyReadAllowed(input);
+      const expected = parts(session, request, request.count, prior), cap = expected.reduce((n, part) => n + part.tokens, 0);
+      for (const part of expected) await validateGitRead(input, state, part.descriptor, cap * 4);
+      const actual = await readActual(session, request, received), charged = parts(session, request, actual.length, prior);
+      for (const part of charged) { await assertGitScratch(part.descriptor); await validateGitRead(input, state, part.descriptor, cap * 4); }
+      if (charged.length) {
+        state = await commitBudget(location, loaded, charge(state, charged), 'budget-read', event(charged)); committed = true;
+      }
+      for (const part of charged) await validateGitRead(input, state, part.descriptor);
+      await assertBudgetReadContext(input);
+      return { actual, derived: { ...prior.derived, ...Object.fromEntries(charged.map(part => [part.descriptor.path, part.prior + part.bytes])) } };
+    } catch (error) {
+      let current = await loadBudget(location);
+      if (current.latest.data.readId === readId) committed = true;
+      if (!committed && received.actual !== null) {
+        const charged = parts(session, request, received.actual.length, prior);
+        if (charged.length) await commitBudget(location, current, charge(current.state, charged), 'budget-read', { ...event(charged), readIncomplete: true, notDelivered: true });
+      }
+      current = await loadBudget(location);
+      if (error.code?.startsWith('ENTROROVE_') && error.code !== 'ENTROROVE_BUDGET_CHAIN_INVALID') {
+        await commitBudget(location, current, current.state, 'budget-read-denied', { sourceRole: 'git-process-derived', code: error.code });
+      }
+      throw error;
+    }
+  });
+    requests.complete(receipt, result.actual.length, result.derived); return result;
+  } catch (error) { requests.failed(receipt); throw error; }
+}

package/local-budget-git-native-darwin.mjs

@@ -0,0 +1,104 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createHash } from 'node:crypto';
+import { fail } from './local-budget-grants.mjs';
+import { darwinGitNativeArtifacts } from './runtime/git-native-darwin-v1.mjs';
+const execute = promisify(execFile), hash = data => createHash('sha256').update(data).digest('hex');
+const sourceSHA = 'ae866387813c965acf6316733813be45f75d3df8d6f0f8afc2228cfcbdd4e830';
+const runtimes = new WeakMap(), builds = new Map(), auxiliaryRoots = new Map();
+const unsupported = () => fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed Darwin Git metering requires its actual root-owned Git, pinned native artifact and fixed codesign tool');
+const environment = () => ({ PATH: '/usr/bin:/bin', HOME: '/var/empty', LANG: 'C', LC_ALL: 'C', TMPDIR: '/tmp' });
+async function directory(target, create = false, owner = process.getuid(), privateMode = true) {
+  if (create) await fs.mkdir(target, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+  const stat = await fs.lstat(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== owner || stat.mode & (privateMode ? 0o7077 : 0o7022)
+    || await fs.realpath(target) !== target) unsupported();
+}
+async function identity(target, owner, privateMode = false, expected) {
+  const stat = await fs.lstat(target, { bigint: true });
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== BigInt(owner) || stat.mode & BigInt(privateMode ? 0o7077 : 0o7022)
+    || await fs.realpath(target) !== target) unsupported();
+  const handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  let sha;
+  try {
+    const opened = await handle.stat({ bigint: true });
+    if (opened.dev !== stat.dev || opened.ino !== stat.ino) unsupported();
+    sha = hash(await handle.readFile()); const after = await handle.stat({ bigint: true });
+    if (after.ctimeNs !== stat.ctimeNs || after.mtimeNs !== stat.mtimeNs || expected && sha !== expected) unsupported();
+  } finally { await handle.close(); }
+  return sha;
+}
+async function trustedTools() {
+  const xcrunSHA = await identity('/usr/bin/xcrun', 0), codesignSHA = await identity('/usr/bin/codesign', 0);
+  const result = await execute('/usr/bin/xcrun', ['--find', 'git'], { env: environment(), timeout: 5000, maxBuffer: 8192 });
+  await identity('/usr/bin/xcrun', 0, false, xcrunSHA);
+  const git = result.stdout.trim();
+  if (result.stderr || !path.isAbsolute(git) || git.includes('\n')
+    || !(git === '/Library/Developer/CommandLineTools/usr/bin/git'
+      || /^\/Applications\/[A-Za-z0-9._ -]+\.app\/Contents\/Developer\/usr\/bin\/git$/.test(git))) unsupported();
+  for (let target = path.dirname(git); target !== '/'; target = path.dirname(target)) await directory(target, false, 0, false);
+  return { git, gitSHA: await identity(git, 0), codesignSHA };
+}
+async function artifactState(home) {
+  if (!/[\s:]/.test(home)) {
+    const state = path.join(home, '.entrorove'); await directory(state, true); return state;
+  }
+  let pending = auxiliaryRoots.get(home);
+  if (!pending) {
+    pending = (async () => {
+      const temporary = await fs.realpath('/tmp'), stat = await fs.lstat(temporary);
+      if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== 0 || !(stat.mode & 0o1000)) unsupported();
+      const state = await fs.mkdtemp(path.join(temporary, `entrorove-fixed-git-${process.getuid()}-${hash(home).slice(0, 16)}-`));
+      await fs.chmod(state, 0o700); await directory(state); return state;
+    })();
+    auxiliaryRoots.set(home, pending); pending.catch(() => auxiliaryRoots.delete(home));
+  }
+  return pending;
+}
+async function build(home, tools, artifact) {
+  const state = await artifactState(home);
+  const parent = path.join(state, 'fixed-git'); await directory(parent, true);
+  const profile = hash(JSON.stringify({ home, ...tools, sourceSHA, librarySHA: artifact.sha256, arch: process.arch }));
+  const destination = path.join(parent, profile), staging = await fs.mkdtemp(path.join(parent, '.building-'));
+  try {
+    await fs.chmod(staging, 0o700);
+    const library = path.join(staging, 'entrorove-fixed-git.dylib'), bytes = Buffer.from(artifact.base64, 'base64');
+    if (hash(bytes) !== artifact.sha256 || !['cffaedfe', 'cefaedfe'].includes(bytes.subarray(0, 4).toString('hex'))) unsupported();
+    await fs.writeFile(library, bytes, { mode: 0o600, flag: 'wx' });
+    const librarySHA = await identity(library, process.getuid(), true, artifact.sha256);
+    await identity(tools.git, 0, false, tools.gitSHA); await identity('/usr/bin/codesign', 0, false, tools.codesignSHA);
+    const git = path.join(staging, 'entrorove-fixed-git');
+    await fs.copyFile(tools.git, git, constants.COPYFILE_EXCL);
+    await identity(git, process.getuid(), false, tools.gitSHA);
+    await execute('/usr/bin/codesign', ['--remove-signature', git], { env: environment(), timeout: 5000, maxBuffer: 8192 });
+    await execute('/usr/bin/codesign', ['--force', '--sign', '-', '--identifier', 'entrorove.fixed-git', git], { env: environment(), timeout: 5000, maxBuffer: 8192 });
+    await fs.chmod(git, 0o700);
+    const copySHA = await identity(git, process.getuid(), true);
+    await identity(tools.git, 0, false, tools.gitSHA); await identity('/usr/bin/codesign', 0, false, tools.codesignSHA);
+    await fs.rename(staging, destination).catch(error => { if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error; });
+    const runtime = Object.freeze({ directory: destination, git: path.join(destination, 'entrorove-fixed-git'), library: path.join(destination, 'entrorove-fixed-git.dylib'),
+      loaderEnv: Object.freeze({ DYLD_INSERT_LIBRARIES: path.join(destination, 'entrorove-fixed-git.dylib') }), platform: 'darwin' });
+    runtimes.set(runtime, { ...tools, librarySHA, copySHA }); await assertDarwinGitRuntime(runtime); return runtime;
+  } finally { await fs.rm(staging, { recursive: true, force: true }); }
+}
+export async function darwinGitNativeRuntime(input) {
+  try {
+    if (process.platform !== 'darwin' || !['arm64', 'x64'].includes(process.arch) || !input.home) unsupported();
+    const home = await fs.realpath(input.home);
+    const source = await fs.readFile(fileURLToPath(new URL('./local-budget-git-native.c', import.meta.url))); if (hash(source) !== sourceSHA) unsupported();
+    const artifact = darwinGitNativeArtifacts[process.arch]; if (!artifact || artifact.sourceSHA !== sourceSHA) unsupported();
+    const tools = await trustedTools(), key = JSON.stringify({ home, ...tools, sourceSHA, librarySHA: artifact.sha256 });
+    let pending = builds.get(key);
+    if (!pending) { pending = build(home, tools, artifact); builds.set(key, pending); pending.catch(() => builds.delete(key)); }
+    const runtime = await pending; await assertDarwinGitRuntime(runtime); return runtime;
+  } catch (error) { if (error.code?.startsWith('ENTROROVE_')) throw error; unsupported(); }
+}
+export async function assertDarwinGitRuntime(runtime) {
+  const expected = runtimes.get(runtime); if (!expected) unsupported();
+  await directory(runtime.directory);
+  await identity(expected.git, 0, false, expected.gitSHA); await identity('/usr/bin/codesign', 0, false, expected.codesignSHA);
+  await identity(runtime.git, process.getuid(), true, expected.copySHA); await identity(runtime.library, process.getuid(), true, expected.librarySHA);
+}

package/local-budget-git-native-linux.mjs

@@ -0,0 +1,93 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { fail } from './local-budget-grants.mjs';
+import { linuxGitNativeArtifacts } from './runtime/git-native-linux-v1.mjs';
+const hash = data => createHash('sha256').update(data).digest('hex');
+const sourceSHA = 'ae866387813c965acf6316733813be45f75d3df8d6f0f8afc2228cfcbdd4e830';
+const runtimes = new WeakMap(), builds = new Map(), auxiliaryRoots = new Map();
+const unsupported = () => fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed Linux Git metering requires its actual root-owned Git, pinned native artifact and glibc runtime');
+async function directory(target, create = false) {
+  if (create) await fs.mkdir(target, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+  const stat = await fs.lstat(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid() || stat.mode & 0o077 || await fs.realpath(target) !== target) unsupported();
+}
+async function identity(target, owner, privateMode = false, expected) {
+  const stat = await fs.lstat(target, { bigint: true });
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== BigInt(owner) || stat.mode & BigInt(privateMode ? 0o7077 : 0o7022)
+    || await fs.realpath(target) !== target) unsupported();
+  const handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  let sha;
+  try {
+    const opened = await handle.stat({ bigint: true });
+    if (opened.dev !== stat.dev || opened.ino !== stat.ino) unsupported();
+    sha = hash(await handle.readFile()); const after = await handle.stat({ bigint: true });
+    if (after.ctimeNs !== stat.ctimeNs || after.mtimeNs !== stat.mtimeNs || expected && sha !== expected) unsupported();
+  } finally { await handle.close(); }
+  return sha;
+}
+async function trustedGit() {
+  if (await fs.realpath('/usr/bin/git') !== '/usr/bin/git') unsupported();
+  for (const target of ['/usr', '/usr/bin']) {
+    const stat = await fs.lstat(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== 0 || stat.mode & 0o022) unsupported();
+  }
+  return { git: '/usr/bin/git', gitSHA: await identity('/usr/bin/git', 0) };
+}
+async function artifactState(home) {
+  if (!/[\s:]/.test(home)) {
+    const state = path.join(home, '.entrorove'); await directory(state, true); return state;
+  }
+  let pending = auxiliaryRoots.get(home);
+  if (!pending) {
+    pending = (async () => {
+      const temporary = await fs.realpath('/tmp'), stat = await fs.lstat(temporary);
+      if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== 0 || !(stat.mode & 0o1000)) unsupported();
+      const state = await fs.mkdtemp(path.join(temporary, `entrorove-fixed-git-${process.getuid()}-${hash(home).slice(0, 16)}-`));
+      await fs.chmod(state, 0o700); await directory(state); return state;
+    })();
+    auxiliaryRoots.set(home, pending); pending.catch(() => auxiliaryRoots.delete(home));
+  }
+  return pending;
+}
+async function build(home, tools, artifact) {
+  const state = await artifactState(home);
+  const parent = path.join(state, 'fixed-git-linux'); await directory(parent, true);
+  const profile = hash(JSON.stringify({ home, ...tools, sourceSHA, librarySHA: artifact.sha256, arch: process.arch }));
+  const destination = path.join(parent, profile), staging = await fs.mkdtemp(path.join(parent, '.building-'));
+  try {
+    await fs.chmod(staging, 0o700);
+    const library = path.join(staging, 'entrorove-fixed-git.so'), bytes = Buffer.from(artifact.base64, 'base64');
+    if (hash(bytes) !== artifact.sha256 || bytes.subarray(0, 4).toString('hex') !== '7f454c46') unsupported();
+    await fs.writeFile(library, bytes, { mode: 0o600, flag: 'wx' });
+    const librarySHA = await identity(library, process.getuid(), true, artifact.sha256);
+    await identity(tools.git, 0, false, tools.gitSHA);
+    const git = path.join(staging, 'entrorove-fixed-git');
+    await fs.copyFile(tools.git, git, constants.COPYFILE_EXCL); await fs.chmod(git, 0o700);
+    await identity(git, process.getuid(), true, tools.gitSHA);
+    await fs.rename(staging, destination).catch(error => { if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error; });
+    const runtime = Object.freeze({ directory: destination, git: path.join(destination, 'entrorove-fixed-git'), library: path.join(destination, 'entrorove-fixed-git.so'),
+      loaderEnv: Object.freeze({ LD_PRELOAD: path.join(destination, 'entrorove-fixed-git.so') }), platform: 'linux' });
+    runtimes.set(runtime, { ...tools, librarySHA }); await assertLinuxGitRuntime(runtime); return runtime;
+  } finally { await fs.rm(staging, { recursive: true, force: true }); }
+}
+export async function linuxGitNativeRuntime(input) {
+  try {
+    if (process.platform !== 'linux' || !['arm64', 'x64'].includes(process.arch) || !process.report.getReport().header.glibcVersionRuntime || !input.home) unsupported();
+    const home = await fs.realpath(input.home);
+    const source = await fs.readFile(fileURLToPath(new URL('./local-budget-git-native.c', import.meta.url))); if (hash(source) !== sourceSHA) unsupported();
+    const artifact = linuxGitNativeArtifacts[process.arch];
+    if (!artifact || artifact.sourceSHA !== sourceSHA) unsupported();
+    const tools = await trustedGit(), key = JSON.stringify({ home, ...tools, sourceSHA, librarySHA: artifact.sha256 });
+    let pending = builds.get(key);
+    if (!pending) { pending = build(home, tools, artifact); builds.set(key, pending); pending.catch(() => builds.delete(key)); }
+    const runtime = await pending; await assertLinuxGitRuntime(runtime); return runtime;
+  } catch (error) { if (error.code?.startsWith('ENTROROVE_')) throw error; unsupported(); }
+}
+export async function assertLinuxGitRuntime(runtime) {
+  const expected = runtimes.get(runtime); if (!expected) unsupported();
+  await directory(runtime.directory);
+  await identity(expected.git, 0, false, expected.gitSHA);
+  await identity(runtime.git, process.getuid(), true, expected.gitSHA); await identity(runtime.library, process.getuid(), true, expected.librarySHA);
+}

package/local-budget-git-native-reads.mjs

@@ -0,0 +1,88 @@
+import { constants, promises as fs } from 'node:fs';
+import { withBudget, loadBudget, commitBudget } from './local-budget-store.mjs';
+import { assertBudgetReadContext, assertDependencyReadAllowed } from './local-budget-reads.mjs';
+import { consumeBudgetRenewal } from './local-budget-renewal.mjs';
+import { requireLiveBudget, fail } from './local-budget-grants.mjs';
+import { validateGitRead } from './local-budget-git.mjs';
+import { fixedNativeRequestStore } from './local-budget-git-native-request.mjs';
+import { assertGitScratchInput, assertGitScratchSessionInput, assertGitScratch, verifyNativeScratchChunk } from './local-budget-git-scratch-loader.mjs';
+
+const requests = fixedNativeRequestStore('source');
+export const createFixedNativeGitRequest = (input, session, descriptor, request) => requests.issue(input, session, descriptor, request);
+function renewed(state) {
+  if (state.grant?.purpose === 'handoff-read') { requireLiveBudget(state); return state; }
+  return consumeBudgetRenewal({ state });
+}
+async function actualBytes(descriptor, request, received) {
+  await assertGitScratch(descriptor);
+  if (request.kind === 'readlink') {
+    if (descriptor.mode !== '120000' || request.offset || request.count < descriptor.bytes) fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed Git requested an invalid original symlink');
+    received.actual = Buffer.from(await fs.readlink(descriptor.target)); return received.actual;
+  }
+  if (descriptor.mode === '120000') fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed Git cannot dereference an original symlink source');
+  const handle = await fs.open(descriptor.target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat({ bigint: true });
+    if (!stat.isFile() || stat.ino !== descriptor.stat.ino || stat.dev !== descriptor.stat.dev) fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed Git source descriptor changed');
+    const capacity = Math.min(request.count, Math.max(0, descriptor.bytes - request.offset));
+    const buffer = Buffer.alloc(capacity), result = await handle.read(buffer, 0, capacity, request.offset);
+    received.actual = buffer.subarray(0, result.bytesRead); return received.actual;
+  } finally { await handle.close(); }
+}
+function charge(state, descriptor, bytes, prior) {
+  const tokens = Math.ceil((prior.bytes + bytes) / 4) - Math.ceil(prior.bytes / 4);
+  return { ...state, files: state.files.includes(descriptor.path) ? state.files : [...state.files, descriptor.path],
+    readCalls: state.readCalls + (prior.started ? 0 : 1), tokenEstimate: state.tokenEstimate + tokens };
+}
+export async function readFixedNativeGitChunk(input, descriptor, receipt) {
+  await assertGitScratchInput(input, descriptor);
+  const { request, prior, readId } = await requests.consume(input, descriptor, receipt);
+  try { const actual = await withBudget(input, async (location, loaded) => {
+    let state = renewed(loaded.state), actual = null, committed = false; const received = { actual: null };
+    const event = bytes => ({ path: descriptor.path, bytes,
+      tokens: Math.ceil((prior.bytes + bytes) / 4) - Math.ceil(prior.bytes / 4), readId,
+      source: { path: descriptor.path, role: 'git-process', bytes: descriptor.bytes, sha256: descriptor.sha256,
+        objectId: descriptor.objectId, commitId: descriptor.commitId, mode: descriptor.mode,
+        native: { kind: request.kind, operationId: request.id, offset: request.offset, count: request.count, index: request.index } } });
+    try {
+      await assertBudgetReadContext(input); await assertDependencyReadAllowed(input);
+      await validateGitRead(input, state, descriptor);
+      const expected = Math.min(request.count, Math.max(0, descriptor.bytes - request.offset));
+      const expectedTokens = Math.ceil((prior.bytes + expected) / 4) - Math.ceil(prior.bytes / 4);
+      await validateGitRead(input, state, descriptor, expectedTokens * 4);
+      actual = await actualBytes(descriptor, request, received);
+      verifyNativeScratchChunk(descriptor, request.offset, actual);
+      const tokens = Math.ceil((prior.bytes + actual.length) / 4) - Math.ceil(prior.bytes / 4);
+      await assertGitScratch(descriptor); await validateGitRead(input, state, descriptor, tokens * 4);
+      if (request.kind === 'mmap' && actual.length !== request.count) fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed Git mapping exceeded actual source bytes');
+      state = await commitBudget(location, loaded, charge(state, descriptor, actual.length, prior), 'budget-read', event(actual.length));
+      committed = true;
+      await validateGitRead(input, state, descriptor); await assertGitScratch(descriptor); await assertBudgetReadContext(input);
+      return actual;
+    } catch (error) {
+      actual ??= received.actual;
+      let current = await loadBudget(location);
+      if (current.latest.data.readId === readId) committed = true;
+      if (!committed && actual !== null) {
+        await commitBudget(location, current, charge(current.state, descriptor, actual.length, prior), 'budget-read',
+          { ...event(actual.length), readIncomplete: true, notDelivered: true });
+      }
+      current = await loadBudget(location);
+      if (error.code?.startsWith('ENTROROVE_') && error.code !== 'ENTROROVE_BUDGET_CHAIN_INVALID') {
+        await commitBudget(location, current, current.state, 'budget-read-denied', { path: descriptor.path, sourceRole: 'git-process', code: error.code });
+      }
+      throw error;
+    }
+  });
+    requests.complete(receipt, actual.length); return actual;
+  } catch (error) { requests.failed(receipt); throw error; }
+}
+export async function assertFixedNativeGitSources(input, session) {
+  await assertGitScratchSessionInput(input, session);
+  return withBudget(input, async (_location, loaded) => {
+    const state = renewed(loaded.state);
+    await assertBudgetReadContext(input); await assertDependencyReadAllowed(input);
+    for (const descriptor of [...session.descriptors, ...session.attributeDescriptors]) { await assertGitScratchInput(input, descriptor); await validateGitRead(input, state, descriptor); }
+    return state;
+  });
+}

package/local-budget-git-native-request.mjs

@@ -0,0 +1,53 @@
+import { randomUUID } from 'node:crypto';
+import { fail } from './local-budget-grants.mjs';
+import { assertGitScratchInput, assertGitScratchSessionInput } from './local-budget-git-scratch-loader.mjs';
+const invalid = () => fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed native reading requires a single-use adapter request receipt');
+function validated(value, descriptor) {
+  if (!value || Object.keys(value).sort().join(',') !== 'count,id,index,kind,length,offset'
+    || !['read', 'pread', 'mmap', 'readlink', 'stdio'].includes(value.kind)
+    || ['id', 'offset', 'count', 'length', 'index'].some(key => !Number.isSafeInteger(value[key]) || value[key] < 0)
+    || value.id < 1 || value.count < 1 || value.count > 65536 || value.length < value.count || value.length > 2147483647
+    || value.kind === 'readlink' && value.offset || value.kind === 'mmap' && value.offset + value.count > descriptor.bytes) invalid();
+  if (value.kind === 'readlink' && (descriptor.mode !== '120000' || value.count < descriptor.bytes)) {
+    fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed readlink must receive all original symlink bytes before charging');
+  }
+  return Object.freeze({ ...value });
+}
+// Each reader owns a private instance. Callers cannot construct receipts or edit actual completed-byte progress.
+export function fixedNativeRequestStore(role) {
+  if (!['source', 'attributes'].includes(role)) invalid();
+  const receipts = new WeakMap(), sessions = new WeakMap();
+  const issue = async (input, session, descriptor, value) => {
+    await assertGitScratchSessionInput(input, session); await assertGitScratchInput(input, descriptor);
+    if (!(role === 'source' ? session.descriptors : session.attributeDescriptors).includes(descriptor)) invalid();
+    const request = validated(value, descriptor);
+    let entry = sessions.get(session);
+    if (!entry) { entry = { id: randomUUID(), operations: new Map() }; sessions.set(session, entry); }
+    let progress = entry.operations.get(request.id);
+    if (!progress) {
+      if (request.index !== 0 || request.kind === 'mmap' && request.offset + request.length > descriptor.bytes) invalid();
+      progress = { bytes: 0, started: false, index: 0, offset: request.offset, length: request.length, descriptor, kind: request.kind };
+      entry.operations.set(request.id, progress);
+    }
+    if (progress.pending || progress.failed || progress.index !== request.index || progress.descriptor !== descriptor
+      || progress.kind !== request.kind || progress.length !== request.length || request.offset !== progress.offset + progress.bytes
+      || request.count !== Math.min(65536, progress.length - progress.bytes)) invalid();
+    const receipt = Object.freeze({ kind: 'entrorove.fixed-native-read-receipt/1' }); progress.pending = true;
+    receipts.set(receipt, { session, descriptor, request, progress, used: false, readId: `${entry.id}:${request.id}:${request.index}` });
+    return receipt;
+  };
+  const consume = async (input, descriptor, receipt) => {
+    const entry = receipts.get(receipt);
+    if (!entry || entry.used || entry.descriptor !== descriptor) invalid();
+    await assertGitScratchSessionInput(input, entry.session); await assertGitScratchInput(input, descriptor);
+    entry.used = true;
+    return { request: entry.request, prior: structuredClone({ bytes: entry.progress.bytes, started: entry.progress.started, derived: entry.progress.derived }), readId: entry.readId };
+  };
+  const complete = (receipt, length, derived) => {
+    const entry = receipts.get(receipt); if (!entry?.used) invalid();
+    entry.progress.bytes += length; entry.progress.started = true; entry.progress.index++;
+    entry.progress.derived = derived; entry.progress.pending = false;
+  };
+  const failed = receipt => { const entry = receipts.get(receipt); if (entry) entry.progress.failed = true; };
+  return Object.freeze({ issue, consume, complete, failed });
+}

package/local-budget-git-native-runtime.mjs

@@ -0,0 +1,18 @@
+import { linuxGitNativeRuntime, assertLinuxGitRuntime } from './local-budget-git-native-linux.mjs';
+import { darwinGitNativeRuntime, assertDarwinGitRuntime } from './local-budget-git-native-darwin.mjs';
+import { fail } from './local-budget-grants.mjs';
+export function fixedGitEnvironment() {
+  return { PATH: '/usr/bin:/bin', HOME: '/var/empty', LANG: 'C', LC_ALL: 'C', TMPDIR: '/tmp',
+    GIT_ATTR_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null', GIT_CONFIG_NOSYSTEM: '1',
+    GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1' };
+}
+export async function fixedGitNativeRuntime(input) {
+  if (process.platform === 'linux') return linuxGitNativeRuntime(input);
+  if (process.platform === 'darwin') return darwinGitNativeRuntime(input);
+  fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed Git metering requires its verified Linux or Darwin artifact');
+}
+export async function assertFixedGitRuntime(runtime) {
+  if (runtime?.platform === 'linux') return assertLinuxGitRuntime(runtime);
+  if (runtime?.platform === 'darwin') return assertDarwinGitRuntime(runtime);
+  fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed Git runtime identity is invalid');
+}