@entrorove/skill 0.1.23 → 0.1.25

package/local-budget-git-native.c

@@ -0,0 +1,313 @@
+#ifdef __linux__
+#define _GNU_SOURCE
+#endif
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+#include <errno.h>
+#include <stdint.h>
+#include <limits.h>
+#include <stdatomic.h>
+
+#ifdef __linux__
+#include <dlfcn.h>
+static ssize_t (*next_read)(int, void *, size_t);
+static ssize_t (*next_pread)(int, void *, size_t, off_t);
+static ssize_t (*next_readlink)(const char *, char *, size_t);
+static ssize_t (*next_readlinkat)(int, const char *, char *, size_t);
+static void *(*next_mmap)(void *, size_t, int, int, int, off_t);
+static int (*next_munmap)(void *, size_t);
+static FILE *(*next_fopen)(const char *, const char *);
+static FILE *(*next_fdopen)(int, const char *);
+static int (*next_fclose)(FILE *);
+static int (*next_fileno)(FILE *);
+__attribute__((constructor(101))) static void original_functions(void) {
+  next_read = dlsym(RTLD_NEXT, "read"); next_pread = dlsym(RTLD_NEXT, "pread");
+  next_readlink = dlsym(RTLD_NEXT, "readlink"); next_readlinkat = dlsym(RTLD_NEXT, "readlinkat");
+  next_mmap = dlsym(RTLD_NEXT, "mmap"); next_munmap = dlsym(RTLD_NEXT, "munmap");
+  next_fopen = dlsym(RTLD_NEXT, "fopen"); next_fdopen = dlsym(RTLD_NEXT, "fdopen");
+  next_fclose = dlsym(RTLD_NEXT, "fclose"); next_fileno = dlsym(RTLD_NEXT, "fileno");
+  if (!next_read || !next_pread || !next_readlink || !next_readlinkat || !next_mmap || !next_munmap
+    || !next_fopen || !next_fdopen || !next_fclose || !next_fileno) _exit(199);
+}
+#define read next_read
+#define pread next_pread
+#define readlink next_readlink
+#define mmap next_mmap
+#define munmap next_munmap
+#define fopen next_fopen
+#define fdopen next_fdopen
+#define fclose next_fclose
+#define fileno next_fileno
+#define INTERPOSE(replacement, original)
+#else
+#define INTERPOSE(replacement, original) \
+  __attribute__((used)) static struct { const void *next; const void *prior; } \
+  hook_##original __attribute__((section("__DATA,__interpose"))) = \
+  { (const void *)&replacement, (const void *)&original };
+#endif
+#define CHUNK 65536
+#define MAX_MAPPING 2147483647
+static atomic_uint_fast64_t sequence;
+struct mapping { void *address; size_t length; };
+static struct mapping mappings[512];
+
+static int write_exact(int fd, const void *buffer, size_t length) {
+  size_t sent = 0;
+  while (sent < length) {
+    ssize_t n = write(fd, (const char *)buffer + sent, length - sent);
+    if (n < 0 && errno == EINTR) continue;
+    if (n <= 0) return -1;
+    sent += (size_t)n;
+  }
+  return 0;
+}
+static int read_exact(int fd, void *buffer, size_t length) {
+  size_t received = 0;
+  while (received < length) {
+    ssize_t n = read(fd, (char *)buffer + received, length - received);
+    if (n < 0 && errno == EINTR) continue;
+    if (n <= 0) return -1;
+    received += (size_t)n;
+  }
+  return 0;
+}
+static int under_root(const char *target) {
+  const char *root = getenv("ENTROROVE_FIXED_GIT_ROOT");
+  size_t length = root ? strlen(root) : 0;
+  return root && strncmp(target, root, length) == 0 && target[length] == '/';
+}
+static int tracked(int fd, char *target) {
+#ifdef __linux__
+  char file[64]; snprintf(file, sizeof(file), "/proc/self/fd/%d", fd);
+  ssize_t length = readlink(file, target, PATH_MAX - 1);
+  if (length < 0 || length >= PATH_MAX - 1) return 0;
+  target[length] = 0; return under_root(target);
+#else
+  return fcntl(fd, F_GETPATH, target) == 0 && under_root(target);
+#endif
+}
+static ssize_t supply(const char *kind, const char *target, void *buffer, size_t length, off_t offset) {
+  char request[PATH_MAX + 160];
+  if (!length) return 0;
+  uint64_t read_id = atomic_fetch_add(&sequence, 1) + 1;
+  size_t received = 0, chunk_index = 0;
+  if (offset < 0 || length > MAX_MAPPING) { errno = EACCES; return -1; }
+  while (received < length) {
+    size_t ask = length - received > CHUNK ? CHUNK : length - received;
+    int n = snprintf(request, sizeof(request), "R\t%llu\t%s\t%s\t%lld\t%zu\t%zu\t%zu\n",
+      (unsigned long long)read_id, kind, target, (long long)(offset + received), ask, length, chunk_index++);
+    if (n <= 0 || n >= sizeof(request) || write_exact(3, request, n) < 0) return -1;
+    int32_t actual;
+    if (read_exact(4, &actual, sizeof(actual)) < 0 || actual < 0) { errno = EACCES; return -1; }
+    if ((size_t)actual > ask || read_exact(4, (char *)buffer + received, actual) < 0) { errno = EIO; return -1; }
+    received += (size_t)actual;
+    if ((size_t)actual < ask) break;
+  }
+  return (ssize_t)received;
+}
+__attribute__((constructor)) static void handshake(void) {
+  const char *nonce = getenv("ENTROROVE_FIXED_GIT_NONCE");
+  char request[200]; int32_t accepted;
+  if (!nonce || !getenv("ENTROROVE_FIXED_GIT_ROOT") || strlen(nonce) != 64) _exit(199);
+  int n = snprintf(request, sizeof(request), "HELLO\tentrorove.fixed-git/1\t%s\n", nonce);
+  if (n <= 0 || n >= sizeof(request) || write_exact(3, request, n) < 0
+    || read_exact(4, &accepted, sizeof(accepted)) < 0 || accepted != 1) _exit(199);
+}
+static ssize_t controlled_read(int fd, void *buffer, size_t length) {
+  char target[PATH_MAX];
+  if (!tracked(fd, target)) return read(fd, buffer, length);
+  off_t offset = lseek(fd, 0, SEEK_CUR);
+  ssize_t actual = supply("read", target, buffer, length, offset);
+  if (actual >= 0 && lseek(fd, offset + actual, SEEK_SET) < 0) return -1;
+  return actual;
+}
+static ssize_t controlled_pread(int fd, void *buffer, size_t length, off_t offset) {
+  char target[PATH_MAX];
+  return tracked(fd, target) ? supply("pread", target, buffer, length, offset) : pread(fd, buffer, length, offset);
+}
+static void *controlled_mmap(void *address, size_t length, int protection, int flags, int fd, off_t offset) {
+  char target[PATH_MAX];
+  if (!tracked(fd, target)) return mmap(address, length, protection, flags, fd, offset);
+  if (protection != PROT_READ || flags != MAP_PRIVATE || address || !length || length > MAX_MAPPING) {
+    errno = EACCES; return MAP_FAILED;
+  }
+  void *buffer = malloc(length);
+  if (!buffer) return MAP_FAILED;
+  ssize_t actual = supply("mmap", target, buffer, length, offset);
+  if (actual < 0 || (size_t)actual != length) { free(buffer); errno = EACCES; return MAP_FAILED; }
+  for (size_t i = 0; i < 512; i++) if (!mappings[i].address) {
+    mappings[i] = (struct mapping){ buffer, length }; return buffer;
+  }
+  free(buffer); errno = ENOMEM; return MAP_FAILED;
+}
+static int controlled_munmap(void *address, size_t length) {
+  for (size_t i = 0; i < 512; i++) if (mappings[i].address == address) {
+    if (mappings[i].length != length) { errno = EINVAL; return -1; }
+    mappings[i].address = NULL; free(address); return 0;
+  }
+  return munmap(address, length);
+}
+static int link_target(const char *file, char *target) {
+  char absolute[PATH_MAX], parent[PATH_MAX];
+  int n;
+  if (file[0] == '/') n = snprintf(absolute, sizeof(absolute), "%s", file);
+  else {
+    if (!getcwd(parent, sizeof(parent))) return -1;
+    n = snprintf(absolute, sizeof(absolute), "%s/%s", parent, file);
+  }
+  if (n <= 0 || n >= sizeof(absolute)) return -1;
+  char *name = strrchr(absolute, '/');
+  if (!name) return -1;
+  *name = 0;
+  if (!realpath(absolute, parent)) return -1;
+  n = snprintf(target, PATH_MAX, "%s/%s", parent, name + 1);
+  return n > 0 && n < PATH_MAX ? 0 : -1;
+}
+static ssize_t controlled_readlink(const char *file, char *buffer, size_t length) {
+  char target[PATH_MAX];
+  if (link_target(file, target) < 0) { errno = EINVAL; return -1; }
+  return under_root(target) ? supply("readlink", target, buffer, length, 0) : readlink(file, buffer, length);
+}
+struct memory_file { FILE *file; void *buffer; int fd; };
+static struct memory_file memory_files[128];
+struct stream_cursor { char target[PATH_MAX]; off_t offset; size_t length; int fd; };
+static ssize_t stream_read(void *cookie, char *buffer, size_t length) {
+  struct stream_cursor *cursor = cookie;
+  ssize_t actual = supply("stdio", cursor->target, buffer, length, cursor->offset);
+  if (actual >= 0) {
+    cursor->offset += actual;
+    if (lseek(cursor->fd, cursor->offset, SEEK_SET) < 0) return -1;
+  }
+  return actual;
+}
+static off_t stream_position(struct stream_cursor *cursor, off_t offset, int whence) {
+  off_t base;
+  if (whence == SEEK_SET) base = 0;
+  else if (whence == SEEK_CUR) base = cursor->offset;
+  else if (whence == SEEK_END) base = cursor->length;
+  else { errno = EINVAL; return -1; }
+  if (offset < -base || offset > MAX_MAPPING - base) { errno = EINVAL; return -1; }
+  off_t next = base + offset;
+  if (lseek(cursor->fd, next, SEEK_SET) < 0) return -1;
+  cursor->offset = next; return next;
+}
+#ifdef __linux__
+static int stream_seek(void *cookie, off64_t *offset, int whence) {
+  off_t next = stream_position(cookie, *offset, whence);
+  if (next < 0) return -1;
+  *offset = next; return 0;
+}
+#else
+static int stream_read_darwin(void *cookie, char *buffer, int length) { return stream_read(cookie, buffer, length); }
+static fpos_t stream_seek_darwin(void *cookie, fpos_t offset, int whence) { return stream_position(cookie, offset, whence); }
+#endif
+static FILE *memory_stream(const char *target, size_t length, int fd) {
+  struct stream_cursor *cursor = malloc(sizeof(*cursor));
+  if (!cursor) return NULL;
+  cursor->offset = lseek(fd, 0, SEEK_CUR); cursor->length = length; cursor->fd = fd;
+  if (cursor->offset < 0 || strlen(target) >= PATH_MAX) { free(cursor); errno = EACCES; return NULL; }
+  strcpy(cursor->target, target);
+#ifdef __linux__
+  cookie_io_functions_t functions = { stream_read, NULL, stream_seek, NULL };
+  FILE *memory = fopencookie(cursor, "r", functions);
+#else
+  FILE *memory = funopen(cursor, stream_read_darwin, NULL, stream_seek_darwin, NULL);
+#endif
+  if (!memory) { free(cursor); return NULL; }
+  for (size_t i = 0; i < 128; i++) if (!memory_files[i].file) {
+    memory_files[i] = (struct memory_file){ memory, cursor, fd }; return memory;
+  }
+  fclose(memory); free(cursor); errno = ENOMEM; return NULL;
+}
+static FILE *controlled_fdopen(int fd, const char *mode) {
+  char target[PATH_MAX];
+  if (!tracked(fd, target)) return fdopen(fd, mode);
+  struct stat stat;
+  if ((strcmp(mode, "r") && strcmp(mode, "rb")) || fstat(fd, &stat) < 0
+    || !S_ISREG(stat.st_mode) || stat.st_size < 0 || stat.st_size > MAX_MAPPING) {
+    errno = EACCES; return NULL;
+  }
+  return memory_stream(target, (size_t)stat.st_size, fd);
+}
+static FILE *controlled_fopen(const char *file, const char *mode) {
+  char target[PATH_MAX];
+  if (link_target(file, target) < 0 || !under_root(target)) return fopen(file, mode);
+  if (strcmp(mode, "r") && strcmp(mode, "rb")) { errno = EACCES; return NULL; }
+  FILE *original = fopen(file, mode);
+  if (!original) return NULL;
+  for (size_t i = 0; i < 128; i++) if (memory_files[i].file == original) return original;
+  struct stat stat;
+  if (fstat(fileno(original), &stat) < 0 || !S_ISREG(stat.st_mode) || stat.st_size < 0 || stat.st_size > MAX_MAPPING) {
+    fclose(original); errno = EACCES; return NULL;
+  }
+  int fd = dup(fileno(original));
+  fclose(original);
+  if (fd < 0) return NULL;
+  FILE *result = memory_stream(target, (size_t)stat.st_size, fd);
+  if (!result) close(fd);
+  return result;
+}
+static int controlled_fclose(FILE *file) {
+  for (size_t i = 0; i < 128; i++) if (memory_files[i].file == file) {
+    void *buffer = memory_files[i].buffer;
+    memory_files[i].file = NULL;
+    int fd = memory_files[i].fd;
+    int result = fclose(file); close(fd); free(buffer); return result;
+  }
+  return fclose(file);
+}
+static int controlled_fileno(FILE *file) {
+  for (size_t i = 0; i < 128; i++) if (memory_files[i].file == file) return memory_files[i].fd;
+  return fileno(file);
+}
+INTERPOSE(controlled_fileno, fileno)
+INTERPOSE(controlled_fdopen, fdopen)
+INTERPOSE(controlled_fopen, fopen)
+INTERPOSE(controlled_fclose, fclose)
+INTERPOSE(controlled_read, read)
+INTERPOSE(controlled_pread, pread)
+INTERPOSE(controlled_mmap, mmap)
+INTERPOSE(controlled_munmap, munmap)
+INTERPOSE(controlled_readlink, readlink)
+
+#ifdef __linux__
+#undef read
+#undef pread
+#undef readlink
+#undef mmap
+#undef munmap
+#undef fopen
+#undef fdopen
+#undef fclose
+#undef fileno
+ssize_t read(int fd, void *buffer, size_t length) { return controlled_read(fd, buffer, length); }
+ssize_t pread(int fd, void *buffer, size_t length, off_t offset) { return controlled_pread(fd, buffer, length, offset); }
+ssize_t pread64(int fd, void *buffer, size_t length, off64_t offset) { return controlled_pread(fd, buffer, length, offset); }
+void *mmap(void *address, size_t length, int protection, int flags, int fd, off_t offset) { return controlled_mmap(address, length, protection, flags, fd, offset); }
+void *mmap64(void *address, size_t length, int protection, int flags, int fd, off64_t offset) { return controlled_mmap(address, length, protection, flags, fd, offset); }
+int munmap(void *address, size_t length) { return controlled_munmap(address, length); }
+ssize_t readlink(const char *file, char *buffer, size_t length) { return controlled_readlink(file, buffer, length); }
+ssize_t readlinkat(int fd, const char *file, char *buffer, size_t length) {
+  if (file[0] == '/' || fd == AT_FDCWD) return controlled_readlink(file, buffer, length);
+  char directory[PATH_MAX], absolute[PATH_MAX];
+  if (!tracked(fd, directory)) return next_readlinkat(fd, file, buffer, length);
+  int n = snprintf(absolute, sizeof(absolute), "%s/%s", directory, file);
+  if (n < 0 || n >= sizeof(absolute)) { errno = EACCES; return -1; }
+  return controlled_readlink(absolute, buffer, length);
+}
+FILE *fopen(const char *file, const char *mode) { return controlled_fopen(file, mode); }
+FILE *fopen64(const char *file, const char *mode) { return controlled_fopen(file, mode); }
+FILE *fdopen(int fd, const char *mode) { return controlled_fdopen(fd, mode); }
+int fclose(FILE *file) { return controlled_fclose(file); }
+int fileno(FILE *file) { return controlled_fileno(file); }
+int fileno_unlocked(FILE *file) { return controlled_fileno(file); }
+ssize_t __read_chk(int fd, void *buffer, size_t length, size_t capacity) {
+  if (length > capacity) { errno = EACCES; return -1; }
+  return controlled_read(fd, buffer, length);
+}
+#endif

package/local-budget-git-native.mjs

@@ -0,0 +1,109 @@
+import { readFixedNativeAttributeChunk, createFixedNativeAttributeRequest } from './local-budget-git-native-attributes.mjs';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { randomBytes, createHash } from 'node:crypto';
+import { fail } from './local-budget-grants.mjs';
+import { gitReadDeadline } from './local-budget-git.mjs';
+import { fixedScratchArguments, assertGitScratchSession, scratchNumstat } from './local-budget-git-scratch-loader.mjs';
+import { fixedGitNativeRuntime, assertFixedGitRuntime, fixedGitEnvironment } from './local-budget-git-native-runtime.mjs';
+import { readFixedNativeGitChunk, createFixedNativeGitRequest, assertFixedNativeGitSources } from './local-budget-git-native-reads.mjs';
+
+const invalid = () => fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed Git content reader handshake or bounded source protocol is invalid');
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+async function canonicalTarget(target) { return path.join(await fs.realpath(path.dirname(target)), path.basename(target)); }
+function request(line, descriptors, progress) {
+  const parts = line.split('\t');
+  if (parts.length !== 8 || parts[0] !== 'R' || !['read', 'pread', 'mmap', 'readlink', 'stdio'].includes(parts[2])) invalid();
+  const [id, offset, count, length, index] = [1, 4, 5, 6, 7].map(i => {
+    if (!/^(?:0|[1-9][0-9]{0,15})$/.test(parts[i])) invalid();
+    const value = Number(parts[i]); if (!Number.isSafeInteger(value)) invalid(); return value;
+  });
+  const descriptor = descriptors.get(parts[3]);
+  if (!descriptor || id < 1 || count < 1 || count > 65536 || length < count || length > 2147483647
+    || (parts[2] === 'readlink' && offset) || (parts[2] === 'mmap' && offset + count > descriptor.bytes)) invalid();
+  let prior = progress.get(id);
+  if (!prior) {
+    if (id !== progress.size + 1 || index !== 0) invalid();
+    if (parts[2] === 'mmap' && offset + length > descriptor.bytes) invalid();
+    prior = { bytes: 0, started: false, offset, length, index: 0, path: parts[3], kind: parts[2] }; progress.set(id, prior);
+  }
+  if (prior.index !== index || prior.path !== parts[3] || prior.kind !== parts[2] || prior.length !== length
+    || offset !== prior.offset + prior.bytes || count !== Math.min(65536, length - prior.bytes)) invalid();
+  return { descriptor, prior, parsed: { id, kind: parts[2], offset, count, length, index } };
+}
+async function respond(pipe, count, bytes) {
+  const header = Buffer.alloc(4); header.writeInt32LE(count);
+  await new Promise((resolve, reject) => pipe.write(bytes ? Buffer.concat([header, bytes]) : header, error => error ? reject(error) : resolve()));
+}
+async function controlBytes(session, target, parsed) {
+  if (target !== await canonicalTarget(session.attributes)) invalid();
+  const stat = await fs.lstat(target);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid() || stat.mode & 0o077) invalid();
+  const bytes = await fs.readFile(target);
+  if (hash(bytes) !== hash(Buffer.from(session.options.attributes))) invalid();
+  return bytes.subarray(parsed.offset, parsed.offset + parsed.count);
+}
+export async function fixedNativeScratchComparison(input, session) {
+  assertGitScratchSession(session);
+  await assertFixedNativeGitSources(input, session);
+  const runtime = await fixedGitNativeRuntime(input), directory = await fs.realpath(session.directory);
+  const descriptors = new Map();
+  for (const descriptor of session.descriptors) descriptors.set(await canonicalTarget(descriptor.target), descriptor);
+  // Derived attributes retain exact original source segments; only fixed conversion flags carry no source bytes.
+  const control = await canonicalTarget(session.attributes);
+  descriptors.set(control, { path: null, bytes: Buffer.byteLength(session.options.attributes), control: true });
+  const state = await assertFixedNativeGitSources(input, session), deadline = gitReadDeadline(state);
+  const nonce = randomBytes(32).toString('hex');
+  const child = spawn(runtime.git, fixedScratchArguments(session), { cwd: directory,
+    env: { ...fixedGitEnvironment(), GIT_CEILING_DIRECTORIES: path.dirname(directory), GIT_DISCOVERY_ACROSS_FILESYSTEM: '0', ...runtime.loaderEnv,
+      ENTROROVE_FIXED_GIT_ROOT: directory, ENTROROVE_FIXED_GIT_NONCE: nonce }, stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'] });
+  let ready = false, buffer = '', output = '', failed = null, finished = false, queue = Promise.resolve();
+  const progress = new Map(); child.stderr.resume(); child.stdio[4].on('error', error => { failed ??= error; });
+  child.stdout.on('data', bytes => { output += bytes.toString('utf8'); if (Buffer.byteLength(output) > 2097152) { failed ??= Object.assign(new Error('fixed Git result exceeded its limit'), { code: 'ENTROROVE_GIT_FAILED' }); child.kill('SIGKILL'); } });
+  const handle = async line => {
+    if (line === `HELLO\tentrorove.fixed-git/1\t${nonce}`) {
+      if (ready) invalid(); ready = true; await assertFixedGitRuntime(runtime); await assertFixedNativeGitSources(input, session);
+      return respond(child.stdio[4], 1);
+    }
+    if (!ready || failed) invalid();
+    const { descriptor, prior, parsed } = request(line, descriptors, progress);
+    let actual;
+    if (descriptor.control && session.attributeDescriptors.length) {
+      const result = await readFixedNativeAttributeChunk(input, session, await createFixedNativeAttributeRequest(input, session, parsed));
+      actual = result.actual; prior.derived = result.derived;
+    } else actual = descriptor.control ? await controlBytes(session, control, parsed)
+      : await readFixedNativeGitChunk(input, descriptor, await createFixedNativeGitRequest(input, session, descriptor, parsed));
+    prior.bytes += actual.length; prior.started = true; prior.index++;
+    await assertFixedNativeGitSources(input, session); await respond(child.stdio[4], actual.length, actual);
+  };
+  child.stdio[3].on('data', bytes => {
+    buffer += bytes.toString('utf8');
+    if (Buffer.byteLength(buffer) > 8192) { failed ??= Object.assign(new Error('fixed Git source protocol exceeded its limit'), { code: 'ENTROROVE_GIT_READER_UNSUPPORTED' }); child.kill('SIGKILL'); return; }
+    let end;
+    while ((end = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+      queue = queue.then(() => handle(line)).catch(async error => {
+        failed ??= error;
+        await respond(child.stdio[4], -1).catch(() => {}); child.kill('SIGKILL');
+      });
+    }
+  });
+  const done = new Promise(resolve => {
+    child.once('error', error => { failed ??= error; finished = true; resolve(null); });
+    child.once('close', code => { finished = true; resolve(code); });
+  });
+  try {
+    while (!finished) {
+      await Promise.race([done, new Promise(resolve => setTimeout(resolve, 25))]);
+      if (Date.now() >= deadline) fail('ENTROROVE_BUDGET_LEASE_EXPIRED', 'fixed Git comparison authorization expired');
+      await assertFixedNativeGitSources(input, session); await assertFixedGitRuntime(runtime);
+    }
+    const code = await done; await queue;
+    if (failed) throw failed;
+    if (!ready) invalid();
+    if (![0, 1].includes(code) || buffer) fail('ENTROROVE_GIT_FAILED', 'fixed Git sealed comparison failed');
+    await assertFixedNativeGitSources(input, session); await assertFixedGitRuntime(runtime);
+    return scratchNumstat(output);
+  } finally { child.kill('SIGKILL'); await done; await queue; }
+}

package/local-budget-git-outcome.mjs

@@ -0,0 +1,33 @@
+import { promises as fs } from 'node:fs';
+import { fail } from './local-budget-grants.mjs';
+import { observeGitFacts } from './local-scope-repository.mjs';
+import { gitReadBinding } from './local-budget-git.mjs';
+import { budgetLocation, loadBudget } from './local-budget-store.mjs';
+const outcomes = new WeakMap();
+const completedDenials = new Set(['ENTROROVE_BUDGET_EXHAUSTED', 'ENTROROVE_BUDGET_LEASE_EXPIRED',
+  'ENTROROVE_BUDGET_SCOPE', 'ENTROROVE_BUDGET_HANDOFF_REVOKED', 'ENTROROVE_BUDGET_COMPLETED']);
+export function getBudgetGitReadOutcome(value) {
+  return value !== null && (typeof value === 'object' || typeof value === 'function') ? outcomes.get(value) ?? null : null;
+}
+async function record(value, binding, initial) {
+  const { state } = await loadBudget(await budgetLocation(binding.input));
+  outcomes.set(value, Object.freeze({ flowId: binding.input.flowId, repositoryRoot: binding.root, budgetHome: binding.input.home,
+    initialSequence: initial.ledger.sequence, initialHead: initial.ledger.head, sequence: state.ledger.sequence, head: state.ledger.head,
+    readCalls: state.readCalls, tokenEstimate: state.tokenEstimate, files: Object.freeze([...state.files]) }));
+}
+/** Fixed scope Git observer only; no callback, command or externally writable receipt store. */
+export async function observeBudgetedGitFacts(root, files, baselineRef, input = { repositoryRoot: root }) {
+  const binding = await gitReadBinding(input);
+  if (await fs.realpath(root) !== binding.root) fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed Git observation cannot change its original repository root');
+  if (!binding.input.flowId) return observeGitFacts(root, files, baselineRef, input);
+  const { state: initial } = await loadBudget(await budgetLocation(binding.input));
+  try {
+    const result = await observeGitFacts(root, files, baselineRef, binding.input);
+    await record(result, binding, initial); return result;
+  } catch (error) {
+    // These fixed-reader denials complete only after every received source byte was committed.
+    // Unknown filesystem/journal failures retain pending accounting without a completion receipt.
+    if (completedDenials.has(error.code)) await record(error, binding, initial);
+    throw error;
+  }
+}

package/local-budget-git-scratch-loader.mjs

@@ -0,0 +1,158 @@
+import { boundGitAttributeSegments, hasSealedBudgetGitAttributes } from './local-budget-git-attributes.mjs';
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { fail, relativePath } from './local-budget-grants.mjs';
+import { verifyFixedGitBlob, verifyGitBlobBytes, gitReadExecution, gitSourceDescriptor } from './local-budget-git-loader.mjs';
+import { gitReadBinding } from './local-budget-git.mjs';
+import { readBudgetedProjectFile, copyBudgetedProjectBuffer, verifyBudgetedProjectBuffer } from './local-budget-reads.mjs';
+
+const sessions = new WeakMap(), descriptorBindings = new WeakMap(), descriptorContents = new WeakMap();
+export function assertGitScratchSession(session) {
+  if (!sessions.has(session)) fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed Git requires an adapter-created sealed source session');
+}
+async function assertOriginalInput(input, original) {
+  if (!input || input.flowId !== original.flowId || await fs.realpath(input.repositoryRoot) !== original.repositoryRoot
+    || original.home && (!input.home || await fs.realpath(input.home) !== original.home)) {
+    fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed Git source cannot change its original home, root or flow');
+  }
+  const actual = (await gitReadBinding(input)).input;
+  if (['home', 'repositoryRoot', 'flowId'].some(key => actual[key] !== original[key])) {
+    fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed Git source requires its original home, root and flow');
+  }
+}
+export async function assertGitScratchSessionInput(input, session) {
+  assertGitScratchSession(session); await assertOriginalInput(input, sessions.get(session));
+}
+export async function assertGitScratchInput(input, descriptor) {
+  if (!descriptorBindings.has(descriptor)) fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed Git requires an adapter-created source descriptor');
+  await assertOriginalInput(input, descriptorBindings.get(descriptor)); await assertGitScratch(descriptor);
+}
+function sealedDescriptor(input, value, content) {
+  Object.freeze(value.stat); const descriptor = Object.freeze(value); descriptorBindings.set(descriptor, input);
+  if (content) descriptorContents.set(descriptor, Buffer.from(content));
+  return descriptor;
+}
+const invalid = message => fail('ENTROROVE_GIT_SOURCE_INVALID', message);
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+function comparisonOptions(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !['attributes', 'attributeBinding', 'binaryDrivers', 'renames', 'algorithm', 'indentHeuristic', 'autocrlf', 'eol', 'renameLimit'].includes(key))
+    || typeof value.attributes !== 'string' || /(?:^|[ \t])filter=/.test(value.attributes) || value.algorithm !== undefined && !['myers', 'minimal', 'patience', 'histogram'].includes(value.algorithm)
+    || value.renames !== undefined && ![false, true, 'copies'].includes(value.renames)
+    || value.autocrlf !== undefined && !['true', 'false', 'input'].includes(value.autocrlf)
+    || value.eol !== undefined && !['lf', 'crlf', 'native'].includes(value.eol)
+    || value.renameLimit !== undefined && (!Number.isSafeInteger(value.renameLimit) || value.renameLimit < 0)
+    || value.indentHeuristic !== undefined && typeof value.indentHeuristic !== 'boolean'
+    || value.binaryDrivers !== undefined && (!Array.isArray(value.binaryDrivers) || value.binaryDrivers.some(driver => !driver
+      || Object.keys(driver).sort().join(',') !== 'binary,name' || !/^[A-Za-z0-9_.-]+$/.test(driver.name) || typeof driver.binary !== 'boolean'))) {
+    fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'Git comparison accepts only fixed captured diff metadata, never commands or callbacks');
+  }
+  const { attributeBinding, ...fields } = value;
+  const options = { ...structuredClone(fields), ...(attributeBinding ? { attributeBinding } : {}) };
+  if (options.binaryDrivers) { options.binaryDrivers.forEach(Object.freeze); Object.freeze(options.binaryDrivers); }
+  return Object.freeze(options);
+}
+async function boundEntry(input, entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry) || !Buffer.isBuffer(entry.content)
+    || !['100644', '100755', '120000'].includes(entry.mode)) invalid('Git scratch needs actual regular-file or symlink source bytes');
+  const relative = relativePath(entry.path), descriptor = { path: relative, bytes: entry.content.length,
+    objectId: entry.objectId ?? null, commitId: entry.commitId ?? null, mode: entry.mode, role: 'git-blob' };
+  if (descriptor.objectId !== null || descriptor.commitId !== null) {
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(descriptor.objectId ?? '')
+      || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(descriptor.commitId ?? '')) invalid('Historical scratch requires its actual commit and blob identity');
+    gitSourceDescriptor(descriptor); verifyGitBlobBytes(descriptor, entry.content); await verifyFixedGitBlob(input.repositoryRoot, descriptor, Date.now() + 10000);
+  } else if (!await verifyBudgetedProjectBuffer(input, path.join(input.repositoryRoot, relative), entry.content)) {
+    const content = await readBudgetedProjectFile(input, path.join(input.repositoryRoot, relative), { sourcePath: relative });
+    if (!content.equals(entry.content)) invalid('Working scratch bytes differ from the original bound source');
+  }
+  return { ...descriptor, role: 'git-comparison', sha256: hash(entry.content) };
+}
+async function writeSide(input, directory, side, entries) {
+  if (!Array.isArray(entries)) invalid('Git scratch sides require arrays of original source entries');
+  const base = path.join(directory, side); await fs.mkdir(base, { mode: 0o700 }); const descriptors = [], seen = new Set();
+  for (const entry of entries) {
+    const descriptor = await boundEntry(input, entry);
+    if ([...seen].some(value => value === descriptor.path || value.startsWith(`${descriptor.path}/`) || descriptor.path.startsWith(`${value}/`))) {
+      invalid('Git scratch source paths repeat or overlap a file or symlink parent');
+    }
+    seen.add(descriptor.path);
+    const target = path.join(base, descriptor.path); await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    if (entry.mode === '120000') {
+      const value = entry.content.toString('utf8');
+      if (!value || value.includes('\0') || !Buffer.from(value).equals(entry.content)) invalid('Git scratch cannot safely represent symlink bytes');
+      await fs.symlink(value, target);
+    } else await fs.writeFile(target, entry.content, { mode: entry.mode === '100755' ? 0o700 : 0o600, flag: 'wx' });
+    descriptors.push(sealedDescriptor(input, { ...descriptor, target, stat: await fs.lstat(target, { bigint: true }) }, entry.content));
+  }
+  return descriptors;
+}
+export async function createGitScratch(input, before, after, value) {
+  input = (await gitReadBinding(input)).input;
+  const copy = entries => {
+    if (!Array.isArray(entries)) invalid('Git scratch sides require arrays');
+    return entries.map(entry => {
+      if (!entry || !Buffer.isBuffer(entry.content)) invalid('Git scratch requires actual source buffers');
+      return { ...entry, content: copyBudgetedProjectBuffer(entry.content) };
+    });
+  };
+  before = copy(before); after = copy(after);
+  const options = comparisonOptions(value), attributeSegments = await boundGitAttributeSegments(input, options), directory = await fs.mkdtemp(path.join(os.tmpdir(), 'entrorove-budget-git-'));
+  try {
+    await fs.chmod(directory, 0o700);
+    const descriptors = [...await writeSide(input, directory, 'before', before), ...await writeSide(input, directory, 'after', after)];
+    const attributes = path.join(directory, 'attributes'); await fs.writeFile(attributes, options.attributes, { mode: 0o600, flag: 'wx' });
+    const attributeStat = Object.freeze(await fs.lstat(attributes, { bigint: true }));
+    const attributeDescriptors = attributeSegments.map(segment => sealedDescriptor(input, { ...segment, target: attributes, stat: attributeStat, bytes: Buffer.byteLength(options.attributes) }));
+    const session = Object.freeze({ directory, attributes, attributeStat, attributeDescriptors, options, descriptors,
+      capturedAttributes: hasSealedBudgetGitAttributes(options) }); Object.freeze(descriptors); Object.freeze(attributeDescriptors); sessions.set(session, input); return session;
+  } catch (error) { await fs.rm(directory, { recursive: true, force: true }); throw error; }
+}
+export async function assertGitScratch(descriptor) {
+  if (!descriptorBindings.has(descriptor)) fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'fixed Git source descriptor is not an opaque adapter identity');
+  const stat = await fs.lstat(descriptor.target, { bigint: true }), original = descriptor.stat;
+  if (stat.dev !== original.dev || stat.ino !== original.ino || stat.size !== original.size || stat.mode !== original.mode
+    || stat.mtimeNs !== original.mtimeNs || stat.ctimeNs !== original.ctimeNs) invalid('Private Git scratch changed during its fixed comparison');
+}
+export function fixedScratchArguments(session) {
+  assertGitScratchSession(session);
+  const args = ['--no-optional-locks', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-c', 'diff.external=', '-c', `core.attributesFile=${session.attributes}`];
+  for (const driver of session.options.binaryDrivers ?? []) args.push('-c', `diff.${driver.name}.binary=${driver.binary}`);
+  if (session.options.autocrlf !== undefined) args.push('-c', `core.autocrlf=${session.options.autocrlf}`);
+  if (session.options.eol !== undefined) args.push('-c', `core.eol=${session.options.eol}`);
+  args.push('diff', '--no-index', '--no-ext-diff', '--no-textconv', '--numstat', '-z',
+    session.options.renames === false ? '--no-renames' : session.options.renames === 'copies' ? '-C' : '-M');
+  if (session.options.algorithm) args.push(`--diff-algorithm=${session.options.algorithm}`);
+  if (session.options.indentHeuristic === false) args.push('--no-indent-heuristic');
+  if (session.options.renameLimit !== undefined) args.push(`-l${session.options.renameLimit}`);
+  args.push('--', 'before', 'after');
+  return args;
+}
+export function fixedScratchComparison(session, deadlineAt) {
+  assertGitScratchSession(session);
+  if (sessions.get(session).flowId) fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'a budget-bound Git session requires the fixed metered native process');
+  const child = spawn('/usr/bin/git', fixedScratchArguments(session), { ...gitReadExecution(session.directory, deadlineAt), stdio: ['ignore', 'pipe', 'pipe'] });
+  child.stderr.resume(); let output = '', oversized = false;
+  child.stdout.on('data', chunk => { output += chunk.toString('utf8'); if (output.length > 2097152) { oversized = true; child.kill('SIGKILL'); } });
+  const done = new Promise(resolve => { child.once('error', () => resolve({ ok: false })); child.once('close', code => resolve({ ok: !oversized && [0, 1].includes(code), output })); });
+  return { done, close: () => child.kill('SIGKILL') };
+}
+export function scratchNumstat(output) {
+  let lines = 0, binary = false, present = false;
+  for (const entry of output.split('\0')) { const match = /^(\d+|-)\t(\d+|-)\t/.exec(entry); if (!match) continue;
+    present = true; if (match[1] === '-' || match[2] === '-') binary = true; else lines += Number(match[1]) + Number(match[2]); }
+  return { lines, binary, present };
+}
+export function verifyScratchBytes(descriptor, content) {
+  if (content.length !== descriptor.bytes || hash(content) !== descriptor.sha256) invalid('Actual private scratch bytes differ from their original source binding');
+}
+
+export function verifyNativeScratchChunk(descriptor, offset, content) {
+  const original = descriptorContents.get(descriptor);
+  if (!original || !Number.isSafeInteger(offset) || offset < 0 || !Buffer.isBuffer(content)
+    || !content.equals(original.subarray(offset, offset + content.length))) {
+    invalid('Actual native scratch bytes differ from their opaque original source binding');
+  }
+}