@entrorove/skill 0.1.23 → 0.1.25

package/local-budget-handoff.mjs

@@ -0,0 +1,229 @@
+import { promises as fs } from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import os from 'node:os';
+import { canonical, fail, identifier, normalizeScope, READ_BUDGETS, sha, verifyBudgetGrant } from './local-budget-grants.mjs';
+import { budgetLocation, commitBudget, withBudget } from './local-budget-store.mjs';
+import { budgetView } from './local-budget.mjs';
+import { assertBudgetHandoffCompletionRead, budgetHandoffCompletionValidationState } from './local-budget-handoff-completion.mjs';
+
+const provenanceFields = ['stage', 'handoffId', 'messageRequestId', 'previousOwnerTaskId', 'previousOwnerFlowId',
+  'previousOwnerScopeDigest', 'receiverTaskId', 'epoch', 'receiverEpoch', 'challengeId', 'passDigest',
+  'sourceReleaseReceiptDigest', 'bindingDigest', 'challengeDigest', 'leaseDigest'];
+const candidateLeaseFields = ['schemaVersion', 'purpose', 'leaseId', 'handoffId', 'messageRequestId', 'ownerId', 'taskId',
+  'flowId', 'stepId', 'taskDigest', 'chainDigest', 'challengeId', 'runnerKeyId', 'localRepositoryDigest', 'epoch',
+  'receiverEpoch', 'baselineReceiptDigest', 'paths', 'mutationAllowed', 'issuedAt', 'expiresAt'];
+const restoreContext = new AsyncLocalStorage();
+function denied(message) { fail('ENTROROVE_BUDGET_HANDOFF_REVOKED', message); }
+function snapshotInput(input) {
+  const fields = ['home', 'repositoryRoot', 'flowId', 'mode', 'executionContext', 'grant', 'handoffCandidate',
+    'provisionalLease', 'pass', 'lease', 'challenge', 'authorization'];
+  if (Object.keys(input).some(field => !fields.includes(field))) denied('handoff budget input contains an unsupported field');
+  try { return structuredClone(input); } catch { denied('handoff budget controls must be immutable data'); }
+}
+function validateProvenance(grant) {
+  const h = grant.handoff;
+  if (grant.purpose !== 'handoff-read' || !h || Object.keys(h).sort().join('\0') !== [...provenanceFields].sort().join('\0')
+    || !['released', 'claimed'].includes(h.stage)) denied('handoff budget requires its exact signed phase provenance');
+  for (const field of ['handoffId', 'messageRequestId', 'previousOwnerTaskId', 'previousOwnerFlowId', 'receiverTaskId', 'challengeId']) identifier(h[field], field);
+  for (const field of ['previousOwnerScopeDigest', 'sourceReleaseReceiptDigest', 'bindingDigest', 'challengeDigest', 'leaseDigest']) {
+    if (!/^[0-9a-f]{64}$/.test(h[field] ?? '')) denied('handoff provenance digest is invalid');
+  }
+  if (!Number.isSafeInteger(h.epoch) || h.epoch < 1 || !Number.isSafeInteger(h.receiverEpoch) || h.receiverEpoch < 1
+    || (h.stage === 'released' ? h.passDigest !== null : !/^[0-9a-f]{64}$/.test(h.passDigest ?? ''))
+    || grant.stepId !== `handoff-${h.handoffId}`) denied('handoff provenance epoch, pass or step is invalid');
+  return h;
+}
+function proofFor(input, stage) {
+  return stage === 'released' ? { handoffCandidate: input.handoffCandidate, provisionalLease: input.provisionalLease }
+    : { pass: input.pass, lease: input.lease, challenge: input.challenge };
+}
+function checkCommon(grant, h, challenge, lease) {
+  const pairs = { handoffId: h.handoffId, messageRequestId: h.messageRequestId, ownerId: grant.ownerId,
+    flowId: grant.flowId, localRepositoryDigest: grant.repositoryDigest, epoch: h.epoch, receiverEpoch: h.receiverEpoch,
+    challengeId: h.challengeId };
+  if (Object.entries(pairs).some(([field, value]) => challenge[field] !== value || lease[field] !== value)
+    || challenge.previousOwnerTaskId !== h.previousOwnerTaskId || challenge.previousOwnerFlowId !== h.previousOwnerFlowId
+    || challenge.originalScopeDigest !== h.previousOwnerScopeDigest || challenge.receiverTaskId !== h.receiverTaskId
+    || lease.taskId !== h.receiverTaskId || lease.stepId !== grant.stepId || lease.leaseId !== grant.leaseId
+    || grant.leaseGeneration !== (lease.generation ?? 1) || grant.expiresAt !== lease.expiresAt
+    || challenge.baselineReceiptDigest !== h.sourceReleaseReceiptDigest
+    || canonical([...challenge.paths].sort()) !== canonical(grant.scope.allowedPaths)
+    || canonical(challenge.paths) !== canonical(lease.paths)) denied('handoff budget lost its original receiver, source permission or short lease');
+}
+async function nativeReadState(input, local, grant, h) {
+  const home = await fs.realpath(input.home ?? os.homedir()), root = await fs.realpath(input.repositoryRoot);
+  if (input.flowId !== local.flowId || home !== local.home || root !== local.root) denied('handoff source read cannot replace its original local receiver binding');
+  const native = await import('./local-task-handoff-fence.mjs');
+  let state;
+  try {
+    const authority = await import('./local-task-handoff-read-authority.mjs');
+    const registered = await authority.assertTaskHandoffReadHome({ ...input, taskId: h.receiverTaskId, ownerId: grant.ownerId });
+    state = await native.readTaskHandoffFence(input);
+    if (registered.readHome !== home || registered.taskId !== h.receiverTaskId || registered.ownerId !== grant.ownerId
+      || registered.epoch !== state.epoch || registered.mutationAllowed !== false) denied('native read registration replaced its original receiver binding');
+  } catch (error) {
+    if (error.code === 'ENTROROVE_BUDGET_HANDOFF_REVOKED') throw error;
+    fail('ENTROROVE_BUDGET_HANDOFF_NATIVE_REQUIRED', 'handoff reading requires its completed trusted receiver read-home registration');
+  }
+  return { native, state };
+}
+async function registerReleasedReadHome(input) {
+  const location = await budgetLocation(input, true), grant = verifyBudgetGrant(input.grant, location, input.grant?.kind);
+  const h = validateProvenance(grant);
+  if (h.stage !== 'released') return;
+  try {
+    const wire = await import('./local-task-handoff-overlay-wire.mjs');
+    const challenge = wire.overlayAuthority(input.handoffCandidate, wire.HANDOFF_CANDIDATE_FIELDS, 'entrorove.task-handoff-scope-challenge/1.0');
+    const lease = wire.overlayAuthority(input.provisionalLease, candidateLeaseFields, 'entrorove.task-handoff-provisional-lease/1.0');
+    if (sha(canonical(input.handoffCandidate)) !== h.challengeDigest || sha(canonical(input.provisionalLease)) !== h.leaseDigest
+      || lease.purpose !== 'scope-inspection' || lease.mutationAllowed !== false) denied('released read registration requires its exact signed candidate and lease');
+    checkCommon(grant, h, challenge, lease);
+    const authority = await import('./local-task-handoff-read-authority.mjs');
+    await authority.registerTaskHandoffReadAuthority(input);
+  } catch (error) {
+    if (error.code === 'ENTROROVE_BUDGET_HANDOFF_REVOKED') throw error;
+    fail('ENTROROVE_BUDGET_HANDOFF_NATIVE_REQUIRED', 'released reading could not complete its trusted receiver read-home registration');
+  }
+}
+export function budgetHandoffReadValidationState(state) {
+  const restoration = restoreContext.getStore();
+  if (!restoration || state.grant?.grantId !== restoration.grant.previousGrantId) return budgetHandoffCompletionValidationState(state);
+  return { ...state, grant: { ...state.grant, expiresAt: new Date(Math.min(Date.parse(restoration.authorization.expiresAt),
+    Date.parse(restoration.grant.expiresAt))).toISOString() } };
+}
+export async function assertBudgetHandoffReadAllowed(input, state) {
+  if (state.grant?.purpose !== 'handoff-read') return;
+  const grant = state.grant, h = validateProvenance(grant), retained = state.handoffRead;
+  if (!retained || canonical(retained.handoff) !== canonical(h)) denied('handoff reading requires its retained native proof');
+  try {
+    const { native, state: current } = await nativeReadState(input, retained.local, grant, h);
+    if (assertBudgetHandoffCompletionRead(input, state, current)) return;
+    const restoration = restoreContext.getStore();
+    if (restoration) {
+      if (input.sourceRole?.startsWith('git-') || state.grant.grantId !== restoration.grant.previousGrantId || !current.receiverCompletion
+        || current.status !== 'paused' || current.receiverRestoration || !current.receiverCompletion.receipt.paths.includes(input.path)) denied('finalization cannot read outside its exact paused completion proof');
+      await validateRestoration(state, restoration.grant, restoration.authorization, input, current); return;
+    }
+    const wire = await import('./local-task-handoff-overlay-wire.mjs'); const proof = retained.proof;
+    if (h.stage === 'released') {
+      if (sha(canonical(proof.handoffCandidate)) !== h.challengeDigest || sha(canonical(proof.provisionalLease)) !== h.leaseDigest) denied('candidate controls do not match the signed handoff digests');
+      const challenge = wire.overlayAuthority(proof.handoffCandidate, wire.HANDOFF_CANDIDATE_FIELDS, 'entrorove.task-handoff-scope-challenge/1.0');
+      const lease = wire.overlayAuthority(proof.provisionalLease, candidateLeaseFields, 'entrorove.task-handoff-provisional-lease/1.0');
+      checkCommon(grant, h, challenge, lease);
+      if (lease.purpose !== 'scope-inspection' || lease.mutationAllowed !== false || current.status !== 'active'
+        || current.receiverClaim && !current.receiverRestoration) denied('released handoff candidate is no longer current');
+      const authority = await import('./local-task-handoff-read-authority.mjs');
+      const registered = await authority.readTaskHandoffReadAuthority({ ...input, ...proof });
+      if (registered.candidateDigest !== h.challengeDigest || registered.leaseDigest !== h.leaseDigest
+        || registered.readHome !== retained.local.home) denied('released read lost its exact signed home registration');
+      const observed = await native.readTaskHandoffSnapshotBinding({ ...input, stepId: grant.stepId,
+        paths: grant.scope.allowedPaths, handoffCandidate: proof.handoffCandidate });
+      if (observed.handoffEpoch !== h.receiverEpoch || observed.handoffBaselineReceiptDigest !== h.sourceReleaseReceiptDigest) denied('candidate read lost its real native epoch or baseline');
+    } else {
+      if (current.status !== 'active' || current.epoch !== h.receiverEpoch || current.receiverCompletion || current.receiverRestoration
+        || !current.receiverClaim || canonical(current.receiverClaim) !== canonical(proof)) denied('claimed handoff reading was completed, restored or replaced');
+      const accepted = wire.receiverClaim(current.receiverClaim, { flowId: input.flowId, repo: grant.repositoryDigest });
+      checkCommon(grant, h, accepted.challenge, accepted.lease);
+      if (sha(canonical(proof.pass)) !== h.passDigest || sha(canonical(proof.challenge)) !== h.challengeDigest
+        || sha(canonical(proof.lease)) !== h.leaseDigest || current.revokedPassIds.includes(accepted.pass.passId)
+        || current.revokedLeaseIds.includes(grant.leaseId)
+        || canonical(grant.scope.forbiddenPaths ?? []) !== canonical([...accepted.pass.previousOwnerScopeContract.forbiddenPaths].sort())) denied('claimed read lost its exact native pass, lease or inherited prohibitions');
+    }
+  } catch (error) {
+    if (['ENTROROVE_BUDGET_HANDOFF_REVOKED', 'ENTROROVE_BUDGET_HANDOFF_NATIVE_REQUIRED'].includes(error.code)) throw error;
+    denied('handoff native proof is unavailable, expired or revoked');
+  }
+}
+function unchangedAllowance(state, grant) {
+  if (grant.mode !== state.mode || grant.scope.goal !== state.scope.goal || canonical(grant.limits) !== canonical(state.grant.limits)
+    || grant.additions || grant.policy) denied('handoff reading cannot replace its original goal, mode or quota');
+}
+function initialState(location, input, grant) {
+  if (canonical(input.executionContext) !== canonical({ executionIsolation: 'sandbox', cloudSandboxEnabled: true })
+    || input.mode !== grant.mode || grant.kind !== 'init' || grant.previousGrantId !== null || grant.revision !== 1
+    || canonical(grant.limits) !== canonical(READ_BUDGETS[grant.mode])) denied('initial handoff grant must retain the original fixed mode allowance');
+  return { schemaVersion: 'entrorove.read-budget/2.0', flowId: location.flowId, repositoryDigest: location.repositoryDigest,
+    mode: grant.mode, executionContext: input.executionContext, enforced: true, startedAt: new Date().toISOString(), elapsedMs: 0,
+    ...READ_BUDGETS[grant.mode], files: [], readCalls: 0, tokenEstimate: 0, extensions: [], grant, initialGrant: grant,
+    scope: grant.scope, revision: 1, closedReason: null, autoRenew: null };
+}
+export async function budgetHandoff(input) {
+  input = snapshotInput(input);
+  if (input.grant?.kind === 'handoff-restore') return restoreHandoffBudget(input);
+  if (input.executionContext && (input.executionContext.executionIsolation !== 'sandbox' || input.executionContext.cloudSandboxEnabled !== true)) denied('handoff budget requires a trusted sandbox context');
+  await registerReleasedReadHome(input);
+  return withBudget(input, async (location, loaded) => {
+    const grant = verifyBudgetGrant(input.grant, location, input.grant?.kind), h = validateProvenance(grant);
+    let state = loaded?.state;
+    if (state) {
+      if (!state.enforced || state.closedReason || grant.previousGrantId !== state.grant.grantId || grant.revision !== state.revision + 1
+        || grant.ownerId !== state.grant.ownerId) denied('handoff grant must advance its original live receiver budget exactly once');
+      unchangedAllowance(state, grant);
+      if (grant.kind === 'handoff-read') {
+        if (state.grant.purpose === 'handoff-read' || h.stage !== 'released' || state.autoRenew?.status === 'authorized') denied('handoff entry requires its original receiver budget without active renewal');
+      } else if (grant.kind === 'handoff-claim') {
+        const previous = state.grant.handoff;
+        if (state.grant.purpose !== 'handoff-read' || previous.stage !== 'released' || h.stage !== 'claimed'
+          || provenanceFields.filter(field => !['stage', 'passDigest', 'leaseDigest'].includes(field)).some(field => h[field] !== previous[field])) denied('handoff claim must advance the same original released candidate');
+      } else denied('existing receiver budgets cannot be reinitialized for handoff reading');
+    } else state = initialState(location, input, grant);
+    const local = { home: await fs.realpath(input.home ?? os.homedir()), root: location.root, flowId: location.flowId };
+    const handoffRead = { handoff: h, local, proof: proofFor(input, h.stage),
+      previousBudget: state.handoffRead ? state.handoffRead.previousBudget : (loaded ? { grant: state.grant, scope: state.scope, mode: state.mode } : null) };
+    const updated = { ...state, grant, scope: normalizeScope(grant.scope), revision: grant.revision, handoffRead };
+    await assertBudgetHandoffReadAllowed(input, updated);
+    const committed = await commitBudget(location, loaded, updated, `budget-${grant.kind}`, { grantId: grant.grantId, handoff: h });
+    await assertBudgetHandoffReadAllowed(input, committed); return budgetView(committed);
+  }, true);
+}
+async function validateRestoration(state, grant, authorization, input, current) {
+  const h = state.grant.handoff, r = grant.handoffRestore;
+  const fields = ['handoffId', 'messageRequestId', 'passDigest', 'leaseDigest', 'receiverEpoch', 'restorationDigest'];
+  if (!r || Object.keys(r).sort().join('\0') !== fields.sort().join('\0') || h?.stage !== 'claimed'
+    || fields.filter(field => field !== 'restorationDigest').some(field => r[field] !== h[field])
+    || r.restorationDigest !== sha(canonical(authorization)) || grant.handoff || grant.purpose === 'handoff-read'
+    || grant.flowId !== state.flowId || grant.repositoryDigest !== state.repositoryDigest || grant.ownerId !== state.grant.ownerId
+    || grant.previousGrantId !== state.grant.grantId || grant.revision !== state.revision + 1 || state.closedReason) denied('restoration lost its original handoff grant lineage');
+  unchangedAllowance(state, grant);
+  const wire = await import('./local-task-handoff-overlay-wire.mjs');
+  const restored = wire.receiverRestoration(authorization, current.receiverClaim,
+    { flowId: input.flowId, repo: grant.repositoryDigest });
+  if (!current.receiverCompletion || sha(canonical(current.receiverCompletion.receipt)) !== restored.completionIdleReceiptDigest
+    || restored.baselineReceiptDigest !== restored.completionIdleReceiptDigest
+    || current.epoch !== (current.receiverRestoration ? restored.epoch : restored.previousEpoch)
+    || (current.receiverRestoration ? current.status !== 'active' || canonical(current.receiverRestoration) !== canonical(authorization)
+      : current.status !== 'paused')) denied('restoration requires the actual completed native proof and its exact next receiver epoch');
+  const previous = state.handoffRead.previousBudget;
+  if (previous ? canonical(grant.scope) !== canonical(previous.scope) || grant.mode !== previous.mode
+    || ['stepId', 'leaseId', 'leaseGeneration', 'expiresAt'].some(field => grant[field] !== previous.grant[field])
+    : canonical(grant.scope.allowedPaths) !== canonical([...restored.paths].sort())) denied('restoration cannot expand or replace the original receiver scope or live lease');
+  if (!restored.revokedPassIds.every(id => current.revokedPassIds.includes(id))
+    || !restored.revokedLeaseIds.every(id => current.revokedLeaseIds.includes(id))) denied('native completion has not revoked the original handoff write pass and short lease');
+  return restored;
+}
+async function restoreHandoffBudget(input) {
+  const grant = verifyBudgetGrant(input.grant, input, 'handoff-restore'), authorization = input.authorization;
+  const preparation = await withBudget(input, async (location, loaded) => {
+    const state = loaded.state;
+    if (canonical(state.grant) === canonical(grant)) return { done: budgetView(state) };
+    const native = await nativeReadState(input, state.handoffRead?.local ?? {}, state.grant, state.grant.handoff ?? {});
+    await validateRestoration(state, grant, authorization, input, native.state);
+    return { native: native.native, alreadyRestored: Boolean(native.state.receiverRestoration) };
+  });
+  if (preparation.done) return preparation.done;
+  if (!preparation.alreadyRestored) await restoreContext.run(Object.freeze({ grant, authorization }),
+    () => preparation.native.restoreTaskHandoffReceiverScope({ ...input, authorization }));
+  return withBudget(input, async (location, loaded) => {
+    const state = loaded.state;
+    if (canonical(state.grant) === canonical(grant)) return budgetView(state);
+    const native = await nativeReadState(input, state.handoffRead?.local ?? {}, state.grant, state.grant.handoff ?? {});
+    await validateRestoration(state, grant, authorization, input, native.state);
+    if (!native.state.receiverRestoration) denied('native restoration must finish before original receiver reading resumes');
+    const updated = { ...state, grant, scope: grant.scope, revision: grant.revision, handoffRead: null,
+      handoffHistory: [...(state.handoffHistory ?? []), { handoff: state.grant.handoff, grantId: state.grant.grantId,
+        restoreGrantId: grant.grantId, restorationDigest: grant.handoffRestore.restorationDigest }] };
+    return budgetView(await commitBudget(location, loaded, updated, 'budget-handoff-restore', { grantId: grant.grantId,
+      previousGrantId: grant.previousGrantId, restorationDigest: grant.handoffRestore.restorationDigest }));
+  });
+}
+export const LOCAL_BUDGET_HANDOFF_OPERATIONS = Object.freeze({ 'budget-handoff': budgetHandoff });

package/local-budget-lock.mjs

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { fail } from './local-budget-grants.mjs';
+
+function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+}
+async function owner(lock) {
+  try { return JSON.parse(await fs.readFile(`${lock}/owner.json`, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; fail('ENTROROVE_LOCK_INVALID', 'budget lock owner is unreadable'); }
+}
+async function recoverDead(lock) {
+  let stat;
+  try { stat = await fs.lstat(lock); } catch (error) { if (error.code === 'ENOENT') return true; throw error; }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_LOCK_INVALID', 'budget lock must be a real directory');
+  const previous = await owner(lock);
+  if (previous && alive(previous.pid) || !previous && Date.now() - stat.mtimeMs < 1000) return false;
+  const quarantine = `${lock}.dead-${randomUUID()}`;
+  try { await fs.rename(lock, quarantine); } catch (error) { if (error.code === 'ENOENT') return true; throw error; }
+  const moved = await fs.lstat(quarantine);
+  if (moved.ino !== stat.ino || moved.dev !== stat.dev) {
+    await fs.rename(quarantine, lock).catch(() => undefined);
+    fail('ENTROROVE_LOCK_CHANGED', 'budget lock changed during dead process recovery');
+  }
+  await fs.rm(quarantine, { recursive: true }); return true;
+}
+async function acquire(lock, token) {
+  const staging = `${lock}.pending-${process.pid}-${token}`; const deadline = Date.now() + 10000;
+  await fs.mkdir(staging, { mode: 0o700 });
+  try {
+    await fs.writeFile(`${staging}/owner.json`, `${JSON.stringify({ pid: process.pid, token })}\n`, { flag: 'wx', mode: 0o600 });
+    while (true) {
+      let existing;
+      try { existing = await fs.lstat(lock); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      if (!existing) {
+        try { await fs.rename(staging, lock); return; }
+        catch (error) { if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error; }
+      }
+      if (await recoverDead(lock)) continue;
+      if (Date.now() >= deadline) fail('ENTROROVE_LOCK_BUSY', 'budget is held by an active process');
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+  } finally { await fs.rm(staging, { recursive: true, force: true }); }
+}
+export async function withBudgetLock(file, action) {
+  const lock = `${file}.lock`; const token = randomUUID();
+  await acquire(lock, token);
+  try { return await action(); }
+  finally {
+    const current = await owner(lock);
+    if (!current || current.token !== token || current.pid !== process.pid) fail('ENTROROVE_LOCK_CHANGED', 'budget lock ownership changed during the operation');
+    await fs.rm(lock, { recursive: true });
+  }
+}

package/local-budget-reads.mjs

@@ -0,0 +1,135 @@
+import { constants, promises as fs } from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import os from 'node:os';
+import path from 'node:path';
+import { fail, sha } from './local-budget-grants.mjs';
+import { budgetReadBuffer } from './local-budget.mjs';
+import { budgetLocation, loadBudget, privateDirectory } from './local-budget-store.mjs';
+
+const readContext = new AsyncLocalStorage(), projectBuffers = new WeakMap();
+export async function assertBudgetReadContext(input) {
+  const binding = readContext.getStore(); if (!binding) return;
+  let home; let root;
+  try { home = await fs.realpath(input.home ?? os.homedir()); root = await fs.realpath(input.repositoryRoot); } catch {}
+  if (input.flowId !== binding.flowId || home !== binding.home || root !== binding.root) fail('ENTROROVE_BUDGET_BINDING_REQUIRED', 'source reading cannot replace its active runtime cloud task binding');
+}
+export async function withBudgetReadContext(input, action) {
+  await assertBudgetReadContext(input);
+  if (typeof input.repositoryRoot !== 'string' || typeof input.flowId !== 'string' || !await readHome(input)) return action();
+  const location = await budgetLocation(input); const loaded = await loadBudget(location, true);
+  if (!loaded?.state.enforced) return action();
+  const home = await fs.realpath(input.home ?? os.homedir());
+  return readContext.run(Object.freeze({ flowId: location.flowId, home, root: location.root }), action);
+}
+
+async function readHome(input) {
+  const supplied = input.home ?? os.homedir();
+  if (typeof supplied !== 'string' || !path.isAbsolute(supplied)) fail('ENTROROVE_HOME_INVALID', 'home must be absolute');
+  try {
+    const stat = await fs.lstat(supplied);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_HOME_INVALID', 'home must be a real directory');
+    return await fs.realpath(supplied);
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function enforcedBudgets(input) {
+  const home = await readHome(input); if (!home) return [];
+  const root = await fs.realpath(input.repositoryRoot);
+  const base = path.join(home, '.entrorove', 'budgets', sha(root).slice(0, 32));
+  let entries;
+  try { entries = await fs.readdir(base, { withFileTypes: true }); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  const result = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'budget directory must be a real directory');
+    const location = await budgetLocation({ ...input, flowId: entry.name });
+    const loaded = await loadBudget(location, true);
+    if (loaded?.state.enforced) result.push(entry.name);
+  }
+  return result;
+}
+export async function budgetBindingForRead(input) {
+  await assertBudgetReadContext(input);
+  if (!await readHome(input)) return null;
+  if (typeof input.flowId === 'string') {
+    const selected = await loadBudget(await budgetLocation(input), true);
+    if (selected) return input;
+  }
+  const budgets = await enforcedBudgets(input);
+  if (!budgets.length) return null;
+  if (typeof input.flowId !== 'string' || !budgets.includes(input.flowId)) fail('ENTROROVE_BUDGET_BINDING_REQUIRED', 'an existing sandbox budget requires its original cloud flow binding');
+  return { ...input, flowId: input.flowId };
+}
+export async function assertBudgetRunnerAllowed(input) {
+  const binding = await budgetBindingForRead(input);
+  if (!binding) return;
+  const loaded = await loadBudget(await budgetLocation(binding));
+  if (loaded.state.enforced) fail('ENTROROVE_BUDGET_RUNNER_UNSUPPORTED', 'this process runner cannot enforce source read quotas; use a controlled read adapter');
+}
+export async function assertDependencyReadAllowed(input) {
+  const location = await budgetLocation(input);
+  const file = path.resolve(location.directory, '..', '..', '..', 'coordination', location.repositoryDigest, input.flowId, 'state.json');
+  let state; let handle;
+  try {
+    await privateDirectory(path.dirname(file), false);
+    handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    if (!(await handle.stat()).isFile()) fail('ENTROROVE_LEASE_INVALID', 'coordination state must be a regular file');
+    state = JSON.parse(await handle.readFile({ encoding: 'utf8' }));
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    if (error instanceof SyntaxError || error.code === 'ELOOP') fail('ENTROROVE_LEASE_INVALID', 'coordination state is invalid');
+    throw error;
+  } finally { await handle?.close(); }
+  if (!state || typeof state !== 'object' || Array.isArray(state)
+    || state.workers !== undefined && (!Array.isArray(state.workers) || state.workers.some(worker => !worker || typeof worker !== 'object' || Array.isArray(worker)))
+    || state.events !== undefined && (!Array.isArray(state.events) || state.events.some(event => !event || typeof event !== 'object' || Array.isArray(event)))) {
+    fail('ENTROROVE_LEASE_INVALID', 'coordination state must contain an object and valid worker/event arrays');
+  }
+  if (state.workers?.some(worker => ['waiting', 'dependency-wait'].includes(worker.status) && !Number.isFinite(Date.parse(worker.expiresAt)))) fail('ENTROROVE_LEASE_INVALID', 'dependency worker wait requires a bounded local expiry');
+  if (state.flowId !== input.flowId || state.repositoryDigest !== location.repositoryDigest) fail('ENTROROVE_LEASE_INVALID', 'coordination lease does not match this budget');
+  const waiting = state.workers?.some(worker => ['waiting', 'dependency-wait'].includes(worker.status) && Date.parse(worker.expiresAt) > Date.now());
+  let eventsWaiting = false;
+  for (const event of state.events ?? []) {
+    const expiry = event.expiresAt ? Date.parse(event.expiresAt) : Date.parse(event.at) + 300000;
+    if (event.event === 'dependency-wait' && !Number.isFinite(expiry)) fail('ENTROROVE_LEASE_INVALID', 'dependency wait requires a bounded local expiry');
+    if (event.event === 'dependency-wait' && expiry > Date.now()) eventsWaiting = true;
+    if (['dependency-ready', 'dependency-resumed', 'dependency-complete'].includes(event.event)) eventsWaiting = false;
+  }
+  if (waiting || eventsWaiting) fail('ENTROROVE_DEPENDENCY_WAIT', 'an active local dependency lease blocks source reading');
+}
+export async function readBudgetedProjectFile(input, target, options = {}) {
+  const binding = await budgetBindingForRead(input);
+  if (binding) {
+    const root = await fs.realpath(input.repositoryRoot);
+    const sourcePath = options.sourcePath ?? path.relative(root, target).split(path.sep).join('/');
+    const before = await fs.lstat(target, { bigint: true });
+    const result = await budgetReadBuffer({ ...binding, path: sourcePath }, { target });
+    const after = await fs.lstat(target, { bigint: true });
+    if (!sameSourceStat(before, after)) fail('ENTROROVE_SCOPE_CHANGED', 'budgeted project source changed during its bound observation');
+    projectBuffers.set(result.content, Object.freeze({ home: await fs.realpath(binding.home ?? os.homedir()),
+      root, flowId: binding.flowId, target: await fs.realpath(target), path: sourcePath, stat: Object.freeze(after), digest: sha(result.content) }));
+    return options.encoding ? result.content.toString(options.encoding) : result.content;
+  }
+  const handle = await fs.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try { if (!(await handle.stat()).isFile()) fail('ENTROROVE_FILE_INVALID', 'source must be a regular file'); return await handle.readFile(options.encoding ? { encoding: options.encoding } : undefined); }
+  finally { await handle.close(); }
+}
+
+function sameSourceStat(before, after) {
+  return before.isFile() && after.isFile() && ['dev', 'ino', 'size', 'mode', 'mtimeNs', 'ctimeNs'].every(key => before[key] === after[key]);
+}
+export function copyBudgetedProjectBuffer(content) {
+  const copy = Buffer.from(content), original = projectBuffers.get(content);
+  if (original) projectBuffers.set(copy, original);
+  return copy;
+}
+export async function verifyBudgetedProjectBuffer(input, target, content) {
+  const original = projectBuffers.get(content); if (!original) return false;
+  await assertBudgetReadContext(input);
+  if (input.flowId !== original.flowId || await fs.realpath(input.repositoryRoot) !== original.root
+    || await fs.realpath(input.home ?? os.homedir()) !== original.home || await fs.realpath(target) !== original.target
+    || path.relative(original.root, target).split(path.sep).join('/') !== original.path
+    || sha(content) !== original.digest || !sameSourceStat(original.stat, await fs.lstat(target, { bigint: true }))) {
+    fail('ENTROROVE_GIT_SOURCE_INVALID', 'working Git bytes changed from their private committed project read');
+  }
+  return true;
+}

package/local-budget-renewal.mjs

@@ -1,37 +1,89 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { promises as fs } from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { withStateLock } from './local-state-lock.mjs';
+import { randomUUID } from 'node:crypto';
+import { operationSchemasFor } from './local-contracts.mjs';
+import { canonical, fail, identifier, normalizeScope, requireLiveBudget, sha, validatePolicy, verifyBudgetGrant } from './local-budget-grants.mjs';
+import { withBudget, commitBudget } from './local-budget-store.mjs';
 
-const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
-function digest(value) { return createHash('sha256').update(value).digest('hex'); }
-function canonical(value) { if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`; if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`; return JSON.stringify(value); }
-function rootHome(home = os.homedir()) { if (typeof home !== 'string' || !path.isAbsolute(home)) fail('ENTROROVE_HOME_INVALID', 'home must be absolute'); return path.join(home, '.entrorove'); }
-async function privateDir(directory) { await fs.mkdir(directory, { recursive: true, mode: 0o700 }); const stat = await fs.lstat(directory); if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'state directory must be a real directory'); if (process.platform !== 'win32') await fs.chmod(directory, 0o700); }
-async function repo(value) { if (typeof value !== 'string' || !path.isAbsolute(value)) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute'); const stat = await fs.lstat(value); if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be a real directory'); return fs.realpath(value); }
-function statePath(home, root, flowId) { return path.join(rootHome(home), 'budgets', digest(root).slice(0, 32), flowId, 'budget.json'); }
-async function load(input) { const root = await repo(input.repositoryRoot); if (typeof input.flowId !== 'string' || !ID.test(input.flowId)) fail('ENTROROVE_ID_INVALID', 'flowId must be a safe identifier'); const file = statePath(input.home, root, input.flowId); await privateDir(path.dirname(file)); const stat = await fs.lstat(file); if (!stat.isFile() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'budget state must be a regular file'); const state = JSON.parse(await fs.readFile(file, 'utf8')); if (state.flowId !== input.flowId || state.repositoryDigest !== digest(root).slice(0, 32)) fail('ENTROROVE_BUDGET_SCOPE', 'budget state does not match repository and flow'); return { root, file, state }; }
-async function save(file, state) { await privateDir(path.dirname(file)); const temp = `${file}.${randomUUID()}.tmp`; await fs.writeFile(temp, `${canonical(state)}\n`, { flag: 'wx', mode: 0o600 }); await fs.rename(temp, file); if (process.platform !== 'win32') await fs.chmod(file, 0o600); }
-export async function consumeBudgetRenewal({ file, state, now = Date.now() }) {
-  if (!state.enforced || !state.autoRenew || state.autoRenew.status !== 'authorized') return state;
-  const elapsed = state.elapsedMs + now - Date.parse(state.startedAt); const used = state.autoRenew.renewalsUsed ?? 0;
-  if (elapsed < state.maxDurationMs || used >= state.autoRenew.policy.maxRenewals) return state;
-  const updated = { ...state, startedAt: new Date(now).toISOString(), elapsedMs: 0, autoRenew: { ...state.autoRenew, renewalsUsed: used + 1, lastRenewedAt: new Date(now).toISOString() } };
-  await save(file, updated); return updated;
+const LOCAL_SCHEMA = 'entrorove.local-execution/1.0';
+export function consumeBudgetRenewal({ state, now = Date.now() }) {
+  requireLiveBudget(state, now);
+  const auto = state.autoRenew;
+  if (!state.enforced || state.grant.purpose === 'handoff-read' || auto?.status !== 'authorized') return state;
+  const elapsed = now - Date.parse(state.startedAt);
+  if (elapsed < state.maxDurationMs) return state;
+  const count = Math.floor((elapsed - state.maxDurationMs) / auto.policy.intervalMs) + 1;
+  if (auto.renewalsUsed + count > auto.policy.maxRenewals) return state;
+  const added = count * auto.policy.intervalMs;
+  const intervals = Array.from({ length: count }, (_, index) => ({ count: auto.renewalsUsed + index + 1,
+    reason: 'expired-budgeted-read', at: new Date(now).toISOString(), intervalMs: auto.policy.intervalMs,
+    cumulativeDurationMs: (auto.cumulativeDurationMs ?? 0) + (index + 1) * auto.policy.intervalMs,
+    deadlineAt: new Date(Date.parse(state.startedAt) + state.maxDurationMs + (index + 1) * auto.policy.intervalMs).toISOString() }));
+  return { ...state, maxDurationMs: state.maxDurationMs + added, autoRenew: { ...auto, renewalsUsed: auto.renewalsUsed + count,
+    cumulativeDurationMs: (auto.cumulativeDurationMs ?? 0) + added, lastRenewedAt: new Date(now).toISOString(), lastRenewalReason: 'expired-budgeted-read',
+    lastRenewalIntervals: count, intervals: [...(auto.intervals ?? []), ...intervals] } };
+}
+export async function budgetAutoRenewRequest(input) {
+  return withBudget(input, async (location, loaded) => {
+    const state = loaded.state; requireLiveBudget(state);
+    if (!state.enforced) fail('ENTROROVE_BUDGET_NOT_APPLICABLE', 'automatic renewal applies only to a cloud sandbox');
+    if (state.grant.purpose === 'handoff-read') fail('ENTROROVE_BUDGET_HANDOFF_FORBIDDEN', 'temporary handoff reads cannot authorize automatic renewal');
+    if (state.grant.purpose === 'scope-bootstrap') fail('ENTROROVE_BUDGET_TRANSITION_REQUIRED', 'candidate source reading must accept its scope before automatic renewal');
+    const scope = normalizeScope(input.scope); const policy = validatePolicy(input.policy); const requestId = identifier(input.requestId, 'requestId');
+    if (canonical(scope) !== canonical(state.scope)) fail('ENTROROVE_RENEWAL_SCOPE', 'renewal scope must match the original cloud task');
+    if (state.autoRenew) {
+      if (state.autoRenew.status === 'pending' && state.autoRenew.requestId === requestId && canonical(state.autoRenew.policy) === canonical(policy)) return renewalView(state.autoRenew, state);
+      fail('ENTROROVE_RENEWAL_EXISTS', 'the task already has an immutable renewal request or authorization');
+    }
+    const record = { requestId, scope, scopeDigest: sha(canonical(scope)), policy, status: 'pending', interactionId: `renew-${randomUUID()}`,
+      createdAt: new Date().toISOString(), expiresAt: new Date(Math.min(Date.now() + 300000, Date.parse(state.grant.expiresAt))).toISOString() };
+    await commitBudget(location, loaded, { ...state, autoRenew: record }, 'budget-renew-request', { requestId, policy });
+    return renewalView(record, state);
+  });
+}
+function renewalView(record, state) {
+  return { schemaVersion: LOCAL_SCHEMA, status: 'waiting', requestId: record.requestId, scope: record.scope, policy: record.policy,
+    authority: 'cloud-confirmation-required', interaction: { schemaVersion: 'confirm.interaction/1.0', interactionId: record.interactionId,
+      type: 'confirm', risk: 'high', question: `Authorize read-time renewal for ${record.scope.goal}; scope ${record.scope.allowedPaths.join(', ')}; interval ${record.policy.intervalMs}ms; at most ${record.policy.maxRenewals} intervals?`,
+      options: [{ id: 'approve', label: 'Approve' }, { id: 'reject', label: 'Reject' }], default: null, timeoutAction: 'wait', rememberable: false, batchable: false, expiresAt: record.expiresAt },
+    cloudRequest: { operation: 'budget-auto-renew-request', flowId: state.flowId, requestId: record.requestId,
+      input: { stepId: state.grant.stepId, previousGrantId: state.grant.grantId, revision: state.revision, policy: record.policy } } };
+}
+export async function budgetAutoRenew(input) {
+  return withBudget(input, async (location, loaded) => {
+    const state = loaded.state; requireLiveBudget(state); const pending = state.autoRenew;
+    if (state.grant.purpose === 'handoff-read') fail('ENTROROVE_BUDGET_HANDOFF_FORBIDDEN', 'temporary handoff reads cannot authorize automatic renewal');
+    if (state.grant?.purpose === 'scope-bootstrap') fail('ENTROROVE_BUDGET_TRANSITION_REQUIRED', 'candidate source reading must accept its scope before automatic renewal');
+    let grant;
+    try { grant = verifyBudgetGrant(input.grant?.kind === 'auto-renew' ? input.grant : input.confirmation?.grant, state.grant, 'auto-renew'); }
+    catch (error) { return { schemaVersion: LOCAL_SCHEMA, status: 'blocked', allowed: false, code: error.code ?? 'ENTROROVE_CONFIRMATION_BINDING' }; }
+    const scope = normalizeScope(input.scope); const policy = validatePolicy(input.policy);
+    if (!pending || pending.status !== 'pending' || pending.requestId !== input.requestId || grant.requestId !== input.requestId
+      || Date.parse(pending.expiresAt) <= Date.now() || canonical(scope) !== canonical(pending.scope) || canonical(policy) !== canonical(pending.policy)
+      || canonical(grant.policy) !== canonical(policy) || grant.previousGrantId !== state.grant.grantId || grant.revision !== state.revision + 1
+      || grant.expiresAt !== state.grant.expiresAt || canonical(grant.limits) !== canonical({ maxFiles: state.maxFiles, maxTokenEstimate: state.maxTokenEstimate, maxDurationMs: state.maxDurationMs })) {
+      return { schemaVersion: LOCAL_SCHEMA, status: 'blocked', allowed: false, code: 'ENTROROVE_CONFIRMATION_BINDING' };
+    }
+    const autoRenew = { ...pending, status: 'authorized', approvedAt: grant.issuedAt, grantId: grant.grantId, grant, renewalsUsed: 0, cumulativeDurationMs: 0 };
+    await commitBudget(location, loaded, { ...state, autoRenew, grant, revision: grant.revision }, 'budget-renew-authorized', { grantId: grant.grantId });
+    return { schemaVersion: LOCAL_SCHEMA, status: 'verified', allowed: true, chainId: input.flowId, requestId: input.requestId, scope, policy, renewalsUsed: 0 };
+  });
+}
+export async function budgetAutoRenewStop(input) {
+  return withBudget(input, async (location, loaded) => {
+    if (!['revoked', 'completed'].includes(input.reason)) fail('ENTROROVE_RENEWAL_REASON', 'reason must be revoked or completed');
+    const state = loaded.state;
+    if (state.closedReason === 'completed' || state.autoRenew?.status === 'stopped' && input.reason === 'revoked') return stopView(state, false);
+    const cloudRequest = state.enforced ? { operation: input.reason === 'completed' ? 'budget-read-lease-close' : 'budget-auto-renew-stop', flowId: state.flowId,
+      input: { stepId: state.grant.stepId, leaseId: state.grant.leaseId, leaseGeneration: state.grant.leaseGeneration,
+        ...(input.reason === 'completed' ? { reason: input.reason } : { grantId: state.grant.grantId, scopeDigest: state.grant.scopeDigest, reason: 'revoked' }) } } : null;
+    const autoRenew = { ...(state.autoRenew ?? {}), status: 'stopped', stoppedAt: new Date().toISOString(), stopReason: input.reason, cloudRequest };
+    const committed = await commitBudget(location, loaded, { ...state, autoRenew, closedReason: input.reason === 'completed' ? 'completed' : state.closedReason }, 'budget-renew-stop', { reason: input.reason });
+    return stopView(committed, true);
+  });
+}
+function stopView(state, stopped) {
+  return { schemaVersion: LOCAL_SCHEMA, status: 'verified', stopped, reason: state.autoRenew.stopReason,
+    renewalsUsed: state.autoRenew.renewalsUsed ?? 0,
+    ...(state.autoRenew.cloudRequest ? { cloudClosePending: true, cloudRequest: state.autoRenew.cloudRequest } : {}) };
 }
-function scope(input) { if (!input.scope || typeof input.scope.goal !== 'string' || !Array.isArray(input.scope.allowedPaths) || !input.scope.allowedPaths.length) fail('ENTROROVE_RENEWAL_SCOPE', 'renewal scope must include goal and allowedPaths'); return { goal: input.scope.goal, allowedPaths: [...new Set(input.scope.allowedPaths)].sort() }; }
-function policy(input) { if (!input.policy || !Number.isSafeInteger(input.policy.intervalMs) || input.policy.intervalMs < 1 || !Number.isSafeInteger(input.policy.maxRenewals) || input.policy.maxRenewals < 1 || input.policy.maxRenewals > 100) fail('ENTROROVE_RENEWAL_POLICY', 'renewal policy must have bounded intervalMs and maxRenewals'); return { intervalMs: input.policy.intervalMs, maxRenewals: input.policy.maxRenewals }; }
-async function renewalRequestUnlocked(input) { const current = await load(input); const requested = scope(input); const renewalPolicy = policy(input); if (!input.requestId || typeof input.requestId !== 'string' || !ID.test(input.requestId)) fail('ENTROROVE_REQUEST_ID', 'requestId must be a safe identifier'); if (current.state.autoRenew?.status === 'authorized') fail('ENTROROVE_RENEWAL_EXISTS', 'this budget already has an immutable renewal authorization'); const record = { requestId: input.requestId, chainId: input.flowId, scope: requested, scopeDigest: digest(canonical(requested)), policy: renewalPolicy, status: 'pending', createdAt: new Date().toISOString() }; const state = { ...current.state, autoRenew: record }; await save(current.file, state); return { schemaVersion: 'entrorove.local-execution/1.0', status: 'waiting', interaction: { schemaVersion: 'confirm.interaction/1.0', interactionId: `renew-${randomUUID()}`, risk: 'medium', question: `Allow automatic read-time renewal for chain ${input.flowId}?`, options: [{ id: 'approve', label: 'Approve' }, { id: 'reject', label: 'Reject' }], default: null, expiresAt: new Date(Date.now() + 300_000).toISOString(), callback: { operation: 'budget-auto-renew', requestId: input.requestId } }, requestId: input.requestId, scope: requested, policy: renewalPolicy }; }
-export async function budgetAutoRenewRequest(input) { const current = await load(input); return withStateLock(current.file, () => renewalRequestUnlocked(input)); }
-async function renewalUnlocked(input) { const current = await load(input); const pending = current.state.autoRenew; const requested = scope(input); const renewalPolicy = policy(input); const confirmation = input.confirmation; if (!pending || pending.requestId !== input.requestId || pending.status !== 'pending' || confirmation?.answer !== 'approve' || confirmation.requestId !== input.requestId || pending.scopeDigest !== digest(canonical(requested)) || canonical(pending.policy) !== canonical(renewalPolicy)) return { schemaVersion: 'entrorove.local-execution/1.0', status: 'blocked', allowed: false, code: 'ENTROROVE_CONFIRMATION_BINDING' }; const state = { ...current.state, autoRenew: { ...pending, status: 'authorized', approvedAt: new Date().toISOString(), renewalsUsed: 0 } }; await save(current.file, state); return { schemaVersion: 'entrorove.local-execution/1.0', status: 'verified', allowed: true, chainId: input.flowId, requestId: input.requestId, scope: requested, policy: renewalPolicy, renewalsUsed: 0 }; }
-export async function budgetAutoRenew(input) { const current = await load(input); return withStateLock(current.file, () => renewalUnlocked(input)); }
-async function renewalStopUnlocked(input) { const current = await load(input); const reason = input.reason; if (!['revoked', 'completed'].includes(reason)) fail('ENTROROVE_RENEWAL_REASON', 'reason must be revoked or completed'); if (!current.state.autoRenew || current.state.autoRenew.status !== 'authorized') return { schemaVersion: 'entrorove.local-execution/1.0', status: 'verified', stopped: false, reason }; const state = { ...current.state, autoRenew: { ...current.state.autoRenew, status: 'stopped', stoppedAt: new Date().toISOString(), stopReason: reason } }; await save(current.file, state); return { schemaVersion: 'entrorove.local-execution/1.0', status: 'verified', stopped: true, reason, renewalsUsed: state.autoRenew.renewalsUsed ?? 0 }; }
-export async function budgetAutoRenewStop(input) { const current = await load(input); return withStateLock(current.file, () => renewalStopUnlocked(input)); }
 export const LOCAL_RENEWAL_OPERATIONS = Object.freeze({ 'budget-auto-renew-request': budgetAutoRenewRequest, 'budget-auto-renew': budgetAutoRenew, 'budget-auto-renew-stop': budgetAutoRenewStop });
-export const LOCAL_RENEWAL_SCHEMAS = Object.freeze({
-  'budget-auto-renew-request': { type: 'object', additionalProperties: false, required: ['repositoryRoot', 'flowId', 'requestId', 'scope', 'policy'] },
-  'budget-auto-renew': { type: 'object', additionalProperties: false, required: ['repositoryRoot', 'flowId', 'requestId', 'scope', 'policy', 'confirmation'] },
-  'budget-auto-renew-stop': { type: 'object', additionalProperties: false, required: ['repositoryRoot', 'flowId', 'reason'] },
-});
+export const LOCAL_RENEWAL_SCHEMAS = operationSchemasFor(LOCAL_RENEWAL_OPERATIONS);

package/local-budget-source-bindings.mjs

@@ -0,0 +1,51 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, fail, sha } from './local-budget-grants.mjs';
+
+async function scopeState(file, location) {
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > 8388608 || process.getuid && stat.uid !== process.getuid()
+      || process.platform !== 'win32' && (stat.mode & 0o077)) fail('ENTROROVE_STATE_INVALID', 'scope cache binding must be a private regular state file');
+    let state;
+    try { state = JSON.parse(await handle.readFile('utf8')); } catch { fail('ENTROROVE_BUDGET_SCOPE', 'scope cache binding is invalid JSON'); }
+    if (!state || typeof state !== 'object' || Array.isArray(state) || state.schemaVersion !== 'entrorove.scope-state/1.0' || state.flowId !== location.flowId
+      || state.repositoryDigest !== location.repositoryDigest || !Array.isArray(state.history)
+      || state.revision !== state.history.length || !state.originalSnapshot || !Array.isArray(state.originalFacts?.files)
+      || !state.originalFacts.files.every(file => file && typeof file.path === 'string')) fail('ENTROROVE_BUDGET_SCOPE', 'scope cache state does not match this read flow');
+    for (const [index, record] of state.history.entries()) {
+      if (!record || !Array.isArray(record.facts?.files) || !Array.isArray(record.facts?.importGraph?.nodes)
+        || !Array.isArray(record.facts?.modules) || ![...record.facts.files, ...record.facts.importGraph.nodes].every(file => file && typeof file.path === 'string')
+        || !record.facts.modules.every(module => module && (module.manifestPath === null || typeof module.manifestPath === 'string'))) fail('ENTROROVE_BUDGET_SCOPE', 'scope cache facts are invalid');
+      const core = Object.fromEntries(Object.entries(record).filter(([key]) => key !== 'recordDigest'));
+      if (record.revision !== index + 1 || record.previousDigest !== (state.history[index - 1]?.recordDigest ?? null)
+        || record.recordDigest !== sha(canonical(core))) fail('ENTROROVE_BUDGET_SCOPE', 'scope cache history integrity failed');
+    }
+    return state;
+  } finally { await handle.close(); }
+}
+async function acceptedScopeCache(location, relative, actual, base) {
+  const scope = path.join(base, 'scope', location.repositoryDigest, location.flowId);
+  const parts = path.relative(scope, actual).split(path.sep);
+  if (!/^revision-[1-9][0-9]*-[0-9a-f-]{36}$/.test(parts[0]) || !['original', 'current'].includes(parts[1])
+    || parts.slice(2).join('/') !== relative) return false;
+  const state = await scopeState(path.join(scope, 'state.json'), location);
+  const directory = path.join(scope, parts[0], parts[1]);
+  if (parts[1] === 'original') return state.originalSnapshot.directory === directory && state.originalFacts.files.some(file => file.path === relative && file.exists !== false);
+  const record = state.history.find(item => item.snapshotDirectory === directory);
+  if (!record) return false;
+  return [...record.facts.files, ...record.facts.importGraph.nodes,
+    ...record.facts.modules.map(module => ({ path: module.manifestPath }))].some(file => file.path === relative && file.exists !== false);
+}
+export async function budgetSourceTarget(location, relative, target) {
+  const directory = await fs.realpath(path.dirname(target)); const actual = path.join(directory, path.basename(target));
+  if (actual === path.resolve(location.root, relative)) return actual;
+  const base = path.resolve(location.directory, '..', '..', '..');
+  const snapshot = path.join(base, 'snapshots', location.repositoryDigest, location.flowId);
+  const parts = path.relative(snapshot, actual).split(path.sep);
+  if (/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(parts[0]) && parts.length >= 2 && parts.slice(1).join('/') === relative) return actual;
+  if (actual.startsWith(`${path.join(base, 'scope', location.repositoryDigest, location.flowId)}${path.sep}`)
+    && await acceptedScopeCache(location, relative, actual, base)) return actual;
+  fail('ENTROROVE_BUDGET_SCOPE', 'source does not match its repository path or committed cache binding');
+}