@entrorove/skill 0.1.22 → 0.1.24

package/local-budget-store.mjs

@@ -0,0 +1,131 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { constants, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { withBudgetLock } from './local-budget-lock.mjs';
+import { BUDGET_SCHEMA, canonical, fail, identifier, sha, verifyBudgetGrant } from './local-budget-grants.mjs';
+
+export async function privateDirectory(directory, create = true) {
+  const absolute = path.resolve(directory);
+  let current = path.parse(absolute).root;
+  for (const part of absolute.slice(current.length).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    if (create) { try { await fs.mkdir(current, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; } }
+    const stat = await fs.lstat(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'budget state directory must be a real directory');
+  }
+  if (create && process.platform !== 'win32') await fs.chmod(absolute, 0o700);
+}
+export async function budgetLocation(input, createHome = false) {
+  if (typeof input.repositoryRoot !== 'string' || !path.isAbsolute(input.repositoryRoot)) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute');
+  const stat = await fs.lstat(input.repositoryRoot);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be a real directory');
+  const root = await fs.realpath(input.repositoryRoot); const repositoryDigest = sha(root).slice(0, 32);
+  const flowId = identifier(input.flowId, 'flowId'); const suppliedHome = input.home ?? os.homedir();
+  if (typeof suppliedHome !== 'string' || !path.isAbsolute(suppliedHome)) fail('ENTROROVE_HOME_INVALID', 'home must be absolute');
+  if (createHome) await fs.mkdir(suppliedHome, { recursive: true, mode: 0o700 });
+  const home = await fs.realpath(suppliedHome);
+  const directory = path.join(home, '.entrorove', 'budgets', repositoryDigest, flowId);
+  const authorityDirectory = path.join(home, '.entrorove', 'budget-integrity', repositoryDigest, flowId);
+  return { root, home, repositoryDigest, flowId, directory, authorityDirectory, authorityFile: path.join(authorityDirectory, 'head.json'),
+    file: path.join(directory, 'budget.json'), journal: path.join(directory, 'journal'), keyFile: path.join(authorityDirectory, 'integrity.key') };
+}
+async function regularBytes(file) {
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try { if (!(await handle.stat()).isFile()) fail('ENTROROVE_STATE_INVALID', 'budget state must be a regular file'); return await handle.readFile(); } finally { await handle.close(); }
+}
+async function json(file) {
+  try {
+    const value = JSON.parse((await regularBytes(file)).toString('utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget controls must contain JSON objects');
+    return value;
+  } catch (error) { if (error instanceof SyntaxError) fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget journal contains invalid JSON'); throw error; }
+}
+async function durableWrite(file, bytes, mode = 0o600) {
+  const handle = await fs.open(file, 'wx', mode);
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+}
+async function syncDirectory(directory) {
+  const handle = await fs.open(directory, 'r');
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+function mac(key, unsigned) { return createHmac('sha256', key).update(canonical(unsigned)).digest('hex'); }
+function verifyRecord(record, key, sequence, previousDigest, location) {
+  if (!record.state || typeof record.state !== 'object' || Array.isArray(record.state)) fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget journal state must be an object');
+  const { digest, signature, ...unsigned } = record;
+  const expected = mac(key, unsigned);
+  if (record.sequence !== sequence || record.previousDigest !== previousDigest || digest !== sha(canonical(unsigned)) || !/^[0-9a-f]{64}$/.test(signature ?? '')
+    || !timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex')) || record.state.schemaVersion !== BUDGET_SCHEMA
+    || record.state.flowId !== location.flowId || record.state.repositoryDigest !== location.repositoryDigest) fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget journal hash, signature, or task binding is invalid');
+}
+export async function loadBudget(location, optional = false) {
+  let names;
+  try { names = (await fs.readdir(location.journal)).filter(name => /^\d{12}\.json$/.test(name)).sort(); } catch (error) {
+    if (optional && error.code === 'ENOENT') {
+      for (const file of [location.file, location.keyFile, location.authorityFile]) { try { await fs.lstat(file); fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget journal is missing for an existing budget'); } catch (cause) { if (cause.code !== 'ENOENT') throw cause; } }
+      return null;
+    }
+    throw error;
+  }
+  if (!names.length) fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget journal is empty');
+  await privateDirectory(location.journal, false); await privateDirectory(location.authorityDirectory, false);
+  const key = await regularBytes(location.keyFile); let previousDigest = null; let latest;
+  let anchor;
+  try { anchor = await json(location.authorityFile); } catch { fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget integrity head is missing or unreadable'); }
+  const { signature: anchorSignature, ...anchorUnsigned } = anchor;
+  if (anchor.flowId !== location.flowId || anchor.repositoryDigest !== location.repositoryDigest || anchorSignature !== mac(key, anchorUnsigned)
+    || !Number.isSafeInteger(anchor.sequence) || anchor.sequence < 0) fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget integrity head is invalid');
+  let anchorMatched = anchor.sequence === 0 && anchor.head === null;
+  for (const [index, name] of names.entries()) {
+    const record = await json(path.join(location.journal, name)); verifyRecord(record, key, index + 1, previousDigest, location);
+    if (latest && record.atMs < latest.atMs) fail('ENTROROVE_BUDGET_CLOCK', 'budget wall clock moved backwards');
+    previousDigest = record.digest; latest = record;
+    if (record.sequence === anchor.sequence && record.digest === anchor.head) anchorMatched = true;
+  }
+  if (!anchorMatched || latest.sequence < anchor.sequence || latest.sequence > anchor.sequence + 1) fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget journal was truncated or diverged from its independent integrity head');
+  let cache;
+  try { cache = await json(location.file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (cache) {
+    const record = await json(path.join(location.journal, `${String(cache.ledger?.sequence).padStart(12, '0')}.json`)).catch(() => null);
+    if (!record || canonical(cache) !== canonical({ ...record.state, ledger: { sequence: record.sequence, head: record.digest } })) fail('ENTROROVE_BUDGET_CHAIN_INVALID', 'budget cache does not match a committed journal record');
+  }
+  const state = { ...latest.state, ledger: { sequence: latest.sequence, head: latest.digest } };
+  if (state.enforced) verifyBudgetGrant(state.grant, location, state.grant.kind, false);
+  return { state, key, latest, anchor };
+}
+async function writeAnchor(location, key, sequence, head) {
+  await privateDirectory(location.authorityDirectory);
+  const unsigned = { schemaVersion: 'entrorove.budget-authority/1.0', flowId: location.flowId, repositoryDigest: location.repositoryDigest, sequence, head };
+  const temporary = `${location.authorityFile}.${randomUUID()}.tmp`;
+  await durableWrite(temporary, `${canonical({ ...unsigned, signature: mac(key, unsigned) })}\n`);
+  await fs.rename(temporary, location.authorityFile); await syncDirectory(location.authorityDirectory);
+}
+export async function commitBudget(location, loaded, state, event, data = {}) {
+  await privateDirectory(location.journal);
+  const key = loaded?.key ?? randomBytes(32);
+  if (!loaded) {
+    await privateDirectory(location.authorityDirectory); await durableWrite(location.keyFile, key);
+    await writeAnchor(location, key, 0, null);
+  } else if (loaded.anchor.sequence < loaded.latest.sequence) {
+    await writeAnchor(location, key, loaded.latest.sequence, loaded.latest.digest);
+  }
+  const { ledger, ...plain } = state;
+  const atMs = Date.now();
+  if (loaded && atMs < loaded.latest.atMs) fail('ENTROROVE_BUDGET_CLOCK', 'budget wall clock moved backwards');
+  const unsigned = { sequence: (loaded?.state.ledger.sequence ?? 0) + 1, previousDigest: loaded?.state.ledger.head ?? null, event, atMs, data, state: plain };
+  const record = { ...unsigned, digest: sha(canonical(unsigned)), signature: mac(key, unsigned) };
+  const destination = path.join(location.journal, `${String(record.sequence).padStart(12, '0')}.json`);
+  const temporaryRecord = `${destination}.${randomUUID()}.tmp`;
+  await durableWrite(temporaryRecord, `${canonical(record)}\n`);
+  try { await fs.link(temporaryRecord, destination); await syncDirectory(location.journal); } finally { await fs.unlink(temporaryRecord).catch(() => undefined); }
+  await writeAnchor(location, key, record.sequence, record.digest);
+  const updated = { ...plain, ledger: { sequence: record.sequence, head: record.digest } };
+  const temporaryCache = `${location.file}.${randomUUID()}.tmp`;
+  await durableWrite(temporaryCache, `${canonical(updated)}\n`);
+  await fs.rename(temporaryCache, location.file); await syncDirectory(location.directory);
+  return updated;
+}
+export async function withBudget(input, action, optional = false) {
+  const location = await budgetLocation(input, optional); await privateDirectory(location.directory);
+  return withBudgetLock(location.file, async () => action(location, await loadBudget(location, optional)));
+}

package/local-budget-transition.mjs

@@ -0,0 +1,46 @@
+import { canonical, fail, requireLiveBudget, READ_BUDGETS, verifyBudgetGrant } from './local-budget-grants.mjs';
+import { withBudget, commitBudget } from './local-budget-store.mjs';
+import { budgetView } from './local-budget.mjs';
+
+function retainedLimits(state, mode) {
+  const total = { ...READ_BUDGETS[mode] };
+  for (const extension of state.extensions) {
+    total.maxFiles += extension.additions.files;
+    total.maxTokenEstimate += extension.additions.tokenEstimate;
+    total.maxDurationMs += extension.additions.durationMs;
+  }
+  if (Object.values(total).some(value => !Number.isSafeInteger(value))) fail('ENTROROVE_EXTENSION_INVALID', 'retained budget additions overflow safe integer limits');
+  return total;
+}
+function validateTransition(state, grant) {
+  const original = state.initialGrant; const transition = grant.transition;
+  if (state.grant.purpose !== 'scope-bootstrap' || original.purpose !== 'scope-bootstrap'
+    || !original.bootstrap || original.bootstrap.candidateRevision !== 1 || grant.purpose !== 'accepted-scope'
+    || grant.previousGrantId !== state.grant.grantId || grant.revision !== state.revision + 1
+    || grant.expiresAt !== original.expiresAt || grant.scope.goal !== original.scope.goal
+    || !transition || transition.candidateScopeDigest !== original.scopeDigest
+    || transition.acceptedScopeDigest !== grant.scopeDigest
+    || transition.candidateRequestId !== original.bootstrap.candidateRequestId || transition.candidateRevision !== 1
+    || canonical(grant.bootstrap) !== canonical(original.bootstrap)
+    || canonical(grant.limits) !== canonical(retainedLimits(state, grant.mode)) || grant.additions || grant.policy
+    || (original.scope.forbiddenPaths ?? []).some(forbidden => !grant.scope.forbiddenPaths?.some(path => forbidden === path || forbidden.startsWith(`${path}/`)))) {
+    fail('ENTROROVE_CONFIRMATION_BINDING', 'scope transition must retain its original candidate lease, goal, prohibitions, additions and cumulative allowance');
+  }
+}
+export async function budgetTransition(input) {
+  return withBudget(input, async (location, loaded) => {
+    const state = loaded.state; requireLiveBudget(state);
+    if (!state.enforced) fail('ENTROROVE_BUDGET_NOT_APPLICABLE', 'scope transition applies only to a cloud sandbox');
+    if (state.transitions?.some(item => item.grantId === input.grant?.grantId)) fail('ENTROROVE_CONFIRMATION_REPLAYED', 'scope transition grant was already consumed');
+    const binding = { ...state.grant, mode: undefined, scopeDigest: undefined };
+    const grant = verifyBudgetGrant(input.grant, binding, 'transition');
+    validateTransition(state, grant);
+    if (state.autoRenew?.status === 'authorized' || state.autoRenew?.status === 'pending') fail('ENTROROVE_BUDGET_TRANSITION_REQUIRED', 'candidate reading cannot have an automatic renewal authorization');
+    const updated = { ...state, ...grant.limits, scope: grant.scope, mode: grant.mode, grant, revision: grant.revision,
+      transitions: [...(state.transitions ?? []), { grantId: grant.grantId, requestId: grant.requestId, transition: grant.transition,
+        priorScopeDigest: state.grant.scopeDigest, scopeDigest: grant.scopeDigest, at: new Date().toISOString() }] };
+    return budgetView(await commitBudget(location, loaded, updated, 'budget-scope-transition', { grantId: grant.grantId,
+      previousGrantId: grant.previousGrantId, transition: grant.transition }));
+  });
+}
+export const LOCAL_BUDGET_TRANSITION_OPERATIONS = Object.freeze({ 'budget-transition': budgetTransition });

package/local-budget.mjs

@@ -0,0 +1,185 @@
+import { constants, promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { BUDGET_SCHEMA, READ_BUDGETS, canonical, fail, relativePath, requireLiveBudget, validateAdditions, verifyBudgetGrant } from './local-budget-grants.mjs';
+import { budgetLocation, loadBudget, withBudget, commitBudget } from './local-budget-store.mjs';
+import { consumeBudgetRenewal } from './local-budget-renewal.mjs';
+import { assertDependencyReadAllowed, assertBudgetReadContext } from './local-budget-reads.mjs';
+import { assertBudgetHandoffReadAllowed, budgetHandoffReadValidationState } from './local-budget-handoff.mjs';
+import { budgetSourceTarget } from './local-budget-source-bindings.mjs';
+
+export { BUDGET_SCHEMA, READ_BUDGETS };
+export { assertReadAllowed as assertBudgetSourceReadAllowed };
+const readOutcomes = new WeakMap();
+/** Private receipts exist only for the exact returned result or thrown error of an accounted read. */
+export function getBudgetReadOutcome(value) { return readOutcomes.get(value); }
+function retainReadOutcome(location, initial, current, relative, readId, received, value) {
+  if (!value || typeof value !== 'object') return;
+  const observed = received.bytes > 0 || received.complete;
+  if (observed && (current.latest.data.readId !== readId || current.state.readCalls !== initial.state.readCalls + 1
+    || current.state.tokenEstimate !== initial.state.tokenEstimate + Math.ceil(received.bytes / 4))) return;
+  const state = current.state;
+  readOutcomes.set(value, Object.freeze({ flowId: location.flowId, repositoryRoot: location.root, budgetHome: location.home,
+    path: relative, readId, initialSequence: initial.latest.sequence, initialHead: initial.latest.digest,
+    sequence: current.latest.sequence, head: current.latest.digest, readCalls: state.readCalls,
+    tokenEstimate: state.tokenEstimate, files: Object.freeze([...state.files]), bytes: received.bytes, complete: received.complete }));
+}
+function enforced(context) {
+  if (!context || typeof context !== 'object' || Array.isArray(context)) fail('ENTROROVE_CONTEXT_REQUIRED', 'executionContext is required');
+  if (Object.keys(context).length === 1 && context.executionIsolation === 'local') return false;
+  if (Object.keys(context).length !== 2 || !['direct', 'sandbox'].includes(context.executionIsolation) || typeof context.cloudSandboxEnabled !== 'boolean'
+    || context.executionIsolation === 'sandbox' && !context.cloudSandboxEnabled) fail('ENTROROVE_CONTEXT_INVALID', 'executionContext is invalid');
+  return context.executionIsolation === 'sandbox';
+}
+export function budgetView(state, now = Date.now()) {
+  const elapsedMs = Math.max(0, now - Date.parse(state.startedAt));
+  const auto = state.autoRenew;
+  const intervals = state.enforced && elapsedMs >= state.maxDurationMs && auto?.status === 'authorized'
+    ? Math.floor((elapsedMs - state.maxDurationMs) / auto.policy.intervalMs) + 1 : 0;
+  const autoRenewEligible = Boolean(intervals && !state.closedReason && now < Date.parse(state.grant.expiresAt)
+    && auto.renewalsUsed + intervals <= auto.policy.maxRenewals);
+  return { ...state, elapsedMs, remainingFiles: state.enforced ? Math.max(0, state.maxFiles - state.files.length) : null,
+    remainingTokenEstimate: state.enforced ? Math.max(0, state.maxTokenEstimate - state.tokenEstimate) : null,
+    remainingDurationMs: state.enforced ? Math.max(0, state.maxDurationMs - elapsedMs) : null,
+    enforcement: state.enforced ? 'cloud-sandbox' : 'continuous', autoRenewEligible,
+    decisionRequired: state.enforced && elapsedMs >= state.maxDurationMs && !autoRenewEligible,
+    nextActions: state.closedReason ? [] : autoRenewEligible ? ['budget-read'] : [] };
+}
+export async function budgetInit(input) {
+  if (input.grant?.purpose === 'handoff-read' || input.grant?.kind === 'handoff-restore') return (await import('./local-budget-handoff.mjs')).budgetHandoff(input);
+  if (!READ_BUDGETS[input.mode]) fail('ENTROROVE_MODE_INVALID', 'mode must be lock, probe, or swarm');
+  const isEnforced = enforced(input.executionContext);
+  return withBudget(input, async (location, loaded) => {
+    if (loaded) {
+      if (loaded.state.mode !== input.mode || canonical(loaded.state.executionContext) !== canonical(input.executionContext)) fail('ENTROROVE_BUDGET_REINITIALIZE', 'budget is already initialized with a different scope');
+      if (isEnforced && canonical(input.grant) !== canonical(loaded.state.initialGrant)) fail('ENTROROVE_BUDGET_REINITIALIZE', 'budget original cloud grant cannot be replaced');
+      requireLiveBudget(loaded.state); return budgetView(loaded.state);
+    }
+    const grant = isEnforced ? verifyBudgetGrant(input.grant, location, 'init') : null;
+    if (grant && (grant.revision !== 1 || grant.previousGrantId !== null || grant.mode !== input.mode
+      || canonical(grant.limits) !== canonical(READ_BUDGETS[input.mode]))) fail('ENTROROVE_BUDGET_GRANT_INVALID', 'initial grant must use the original mode limits and revision');
+    if (grant?.purpose === 'scope-bootstrap' && (!grant.bootstrap || grant.bootstrap.candidateRevision !== 1
+      || typeof grant.bootstrap.candidateRequestId !== 'string')) fail('ENTROROVE_BUDGET_GRANT_INVALID', 'candidate budget must retain its original exact cloud scope confirmation');
+    const state = { schemaVersion: BUDGET_SCHEMA, flowId: location.flowId, repositoryDigest: location.repositoryDigest, mode: input.mode,
+      executionContext: input.executionContext, enforced: isEnforced,
+      startedAt: grant?.purpose === 'scope-bootstrap' ? new Date(grant.issuedAt).toISOString() : new Date().toISOString(), elapsedMs: 0,
+      ...READ_BUDGETS[input.mode], files: [], readCalls: 0, tokenEstimate: 0, extensions: [], grant, initialGrant: grant,
+      scope: grant?.scope ?? null, revision: grant?.revision ?? 1, closedReason: null, autoRenew: null };
+    return budgetView(await commitBudget(location, null, state, 'budget-init', { grantId: grant?.grantId ?? null }));
+  }, true);
+}
+export async function budgetContext(input) {
+  return withBudget(input, async (location, loaded) => {
+    const state = loaded.state; const isEnforced = enforced(input.executionContext);
+    if (state.enforced && !isEnforced) fail('ENTROROVE_BUDGET_DOWNGRADE', 'an enforced sandbox budget cannot be downgraded');
+    if (isEnforced && !state.enforced) fail('ENTROROVE_BUDGET_GRANT_REQUIRED', 'sandbox entry needs a new cloud-bound budget task');
+    requireLiveBudget(state);
+    if (canonical(state.executionContext) === canonical(input.executionContext)) return budgetView(state);
+    return budgetView(await commitBudget(location, loaded, { ...state, executionContext: input.executionContext }, 'budget-context'));
+  });
+}
+export async function budgetStatus(input) {
+  return withBudget(input, async (location, loaded) => budgetView(loaded.state));
+}
+function assertReadAllowed(state, relative, tokens, now = Date.now()) {
+  requireLiveBudget(budgetHandoffReadValidationState(state), now);
+  if (!state.enforced) return;
+  if (state.scope.forbiddenPaths?.some(scope => relative === scope || relative.startsWith(`${scope}/`))) fail('ENTROROVE_BUDGET_SCOPE', 'source read is forbidden by the accepted cloud task scope');
+  if (!state.scope.allowedPaths.some(scope => relative === scope || relative.startsWith(`${scope}/`))) fail('ENTROROVE_BUDGET_SCOPE', 'source read is outside the original cloud task scope');
+  if (!state.files.includes(relative) && state.files.length >= state.maxFiles) fail('ENTROROVE_BUDGET_EXHAUSTED', 'read file budget exhausted');
+  if (tokens > state.maxTokenEstimate - state.tokenEstimate) fail('ENTROROVE_BUDGET_EXHAUSTED', 'read token budget exhausted');
+  if (now - Date.parse(state.startedAt) >= state.maxDurationMs) fail('ENTROROVE_BUDGET_EXHAUSTED', 'read duration budget exhausted');
+}
+async function readSource(location, state, relative, target, received) {
+  const binding = { home: location.home, repositoryRoot: location.root, flowId: location.flowId, path: relative };
+  await assertBudgetHandoffReadAllowed(binding, state);
+  const actualTarget = await budgetSourceTarget(location, relative, target);
+  let handle;
+  try { handle = await fs.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)); }
+  catch (error) { if (error.code === 'ELOOP') fail('ENTROROVE_FILE_INVALID', 'budget source must be a regular file'); throw error; }
+  try {
+    const stat = await handle.stat(); if (!stat.isFile()) fail('ENTROROVE_FILE_INVALID', 'budget source must be a regular file');
+    await assertDescriptorTarget(target, actualTarget, stat);
+    assertReadAllowed(state, relative, Math.ceil(stat.size / 4));
+    const cap = state.enforced ? Math.max(0, (state.maxTokenEstimate - state.tokenEstimate) * 4) : Number.MAX_SAFE_INTEGER;
+    const chunks = []; let size = 0;
+    for await (const chunk of handle.createReadStream({ autoClose: false })) {
+      size += chunk.length; received.bytes = size;
+      if (size > cap) fail('ENTROROVE_BUDGET_EXHAUSTED', 'read token budget exhausted');
+      assertReadAllowed(state, relative, Math.ceil(size / 4));
+      await assertBudgetHandoffReadAllowed(binding, state); chunks.push(chunk);
+    }
+    received.complete = true;
+    await assertDescriptorTarget(target, actualTarget, stat);
+    assertReadAllowed(state, relative, Math.ceil(size / 4));
+    await assertBudgetHandoffReadAllowed(binding, state); return Buffer.concat(chunks, size);
+  } finally { await handle.close(); }
+}
+async function assertDescriptorTarget(target, expected, descriptorStat) {
+  const current = await fs.realpath(target); const stat = await fs.stat(current);
+  if (current !== expected || stat.dev !== descriptorStat.dev || stat.ino !== descriptorStat.ino) fail('ENTROROVE_PATH_ESCAPE', 'source path changed while its budgeted descriptor was open');
+}
+export async function budgetReadBuffer(input, options = {}) {
+  await assertBudgetReadContext(input);
+  const relative = relativePath(input.path);
+  return withBudget(input, async (location, loaded) => {
+    const received = { bytes: 0, complete: false }, readId = randomUUID();
+    let state = loaded.state, charged = false;
+    try {
+      await assertDependencyReadAllowed(input);
+      if (state.grant?.purpose === 'handoff-read') requireLiveBudget(budgetHandoffReadValidationState(state));
+      else state = consumeBudgetRenewal({ state });
+      const target = options.target ?? path.join(location.root, relative);
+      const content = await readSource(location, state, relative, target, received); const tokens = Math.ceil(content.length / 4);
+      const updated = { ...state, files: state.files.includes(relative) ? state.files : [...state.files, relative], readCalls: state.readCalls + 1, tokenEstimate: state.tokenEstimate + tokens };
+      const committed = await commitBudget(location, loaded, updated, 'budget-read', { path: relative, tokens, bytes: content.length,
+        readId, renewedIntervals: (state.autoRenew?.renewalsUsed ?? 0) - (loaded.state.autoRenew?.renewalsUsed ?? 0), reason: state.autoRenew?.lastRenewalReason ?? null });
+      charged = true;
+      assertReadAllowed(committed, relative, 0);
+      await assertBudgetHandoffReadAllowed(input, committed);
+      const result = { content, budget: budgetView(committed), path: relative };
+      retainReadOutcome(location, loaded, await loadBudget(location), relative, readId, received, result);
+      return result;
+    } catch (error) {
+      readOutcomes.delete(error);
+      const retained = await loadBudget(location);
+      if (!charged && retained.latest.data.readId !== readId && (received.bytes || received.complete)) {
+        const tokens = Math.ceil(received.bytes / 4);
+        await commitBudget(location, retained, { ...state, files: state.files.includes(relative) ? state.files : [...state.files, relative],
+          readCalls: state.readCalls + 1, tokenEstimate: state.tokenEstimate + tokens }, 'budget-read',
+        { path: relative, tokens, bytes: received.bytes, readId, readIncomplete: true,
+          renewedIntervals: (state.autoRenew?.renewalsUsed ?? 0) - (loaded.state.autoRenew?.renewalsUsed ?? 0), reason: state.autoRenew?.lastRenewalReason ?? null });
+      }
+      if (error.code?.startsWith('ENTROROVE_') && error.code !== 'ENTROROVE_BUDGET_CHAIN_INVALID') {
+        const current = await loadBudget(location);
+        await commitBudget(location, current, current.state, 'budget-read-denied', { path: relative, code: error.code, readId });
+      }
+      retainReadOutcome(location, loaded, await loadBudget(location), relative, readId, received, error);
+      throw error;
+    }
+  });
+}
+export async function budgetRead(input) {
+  const read = await budgetReadBuffer(input);
+  return { schemaVersion: 'entrorove.local-execution/1.0', path: read.path, content: read.content.toString('utf8'), budget: read.budget };
+}
+export async function budgetExtend(input) {
+  return withBudget(input, async (location, loaded) => {
+    const state = loaded.state;
+    if (!state.enforced) fail('ENTROROVE_BUDGET_NOT_APPLICABLE', 'budget extension applies only to a cloud sandbox');
+    if (state.grant.purpose === 'handoff-read') fail('ENTROROVE_BUDGET_HANDOFF_FORBIDDEN', 'temporary handoff reads cannot extend their source authority');
+    requireLiveBudget(state);
+    const grant = verifyBudgetGrant(input.grant?.kind === 'extend' ? input.grant : input.confirmation?.grant, state.grant, 'extend');
+    const additions = validateAdditions(input.additions);
+    if (state.extensions.some(item => item.grantId === grant.grantId)) fail('ENTROROVE_CONFIRMATION_REPLAYED', 'budget grant was already applied');
+    if (grant.previousGrantId !== state.grant.grantId || grant.revision !== state.revision + 1 || canonical(grant.additions) !== canonical(additions)
+      || canonical(grant.limits) !== canonical({ maxFiles: state.maxFiles + additions.files, maxTokenEstimate: state.maxTokenEstimate + additions.tokenEstimate,
+        maxDurationMs: state.maxDurationMs - (state.autoRenew?.cumulativeDurationMs ?? 0) + additions.durationMs })
+      || grant.expiresAt !== state.grant.expiresAt) fail('ENTROROVE_CONFIRMATION_BINDING', 'extension does not match the original budget revision, quota, and lease');
+    const updated = { ...state, maxFiles: state.maxFiles + additions.files, maxTokenEstimate: state.maxTokenEstimate + additions.tokenEstimate,
+      maxDurationMs: state.maxDurationMs + additions.durationMs, revision: grant.revision, grant,
+      extensions: [...state.extensions, { grantId: grant.grantId, requestId: grant.requestId, additions, at: new Date().toISOString() }] };
+    if (['maxFiles', 'maxTokenEstimate', 'maxDurationMs'].some(field => !Number.isSafeInteger(updated[field]))) fail('ENTROROVE_EXTENSION_INVALID', 'budget extension overflows safe integer limits');
+    return budgetView(await commitBudget(location, loaded, updated, 'budget-extend', { grantId: grant.grantId, additions }));
+  });
+}

package/local-calctool-cli.mjs

@@ -0,0 +1,22 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runCalctoolLocal } from './local-calctool.mjs';
+import { CALCTOOL_LOCAL_OPERATION_SCHEMAS } from './local-calctool-contracts.mjs';
+
+export async function runCalctoolCli(args = process.argv.slice(2)) {
+  let source = ''; for await (const chunk of process.stdin) source += chunk;
+  let input;
+  try { input = source.trim() ? JSON.parse(source) : {}; }
+  catch { throw Object.assign(new Error('Calctool stdin must be valid JSON'), { code: 'CALCTOOL_JSON_INVALID' }); }
+  if (args[0] === 'capabilities') return { schemaVersion: 'entrorove.local-execution/1.0', operationSchemas: CALCTOOL_LOCAL_OPERATION_SCHEMAS, operations: Object.keys(CALCTOOL_LOCAL_OPERATION_SCHEMAS) };
+  if (args[1] && input.repositoryRoot === undefined) input.repositoryRoot = args[1];
+  return runCalctoolLocal(args[0] ?? '', input);
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = await runCalctoolCli(); process.stdout.write(JSON.stringify(result) + '\n');
+    if (['blocked', 'failed', 'incomplete'].includes(result.status)) process.exitCode = 2;
+  } catch (cause) {
+    process.stderr.write(JSON.stringify({ status: 'blocked', code: cause.code ?? 'CALCTOOL_INPUT_INVALID', message: cause.message }) + '\n'); process.exitCode = 2;
+  }
+}

package/local-calctool-contracts.mjs

@@ -0,0 +1,42 @@
+import { FINAL_GATE16_INPUT_SCHEMA, FINAL_GATE16_READ_INPUT_SCHEMA } from './local-final-gate16-contract.mjs';
+import { array, identifier, integer, object, record, relativePath, sha256, text } from './local-contract-types.mjs';
+
+export const CALCTOOL_LOCAL_NAMES = Object.freeze(['run', 'compile', 'generate', 'verify', 'estimate', 'impact', 'status', 'inventory', 'purge',
+  'brain-handshake', 'brain-invoke', 'brain-events', 'brain-cancel', 'brain-complete', 'brain-resume', 'brain-status',
+  'probe-env', 'adapt-config', 'intake-round', 'compile-tool', 'blueprint-orchestrate', 'auto-pipeline', 'final-gate', 'swarm-orchestrate']);
+const base = { repositoryRoot: text, home: text, flowId: identifier, stepId: identifier };
+const engineSource = { ...base, engine: record, enginePath: relativePath, requirements: record, program: record,
+  engineId: text, engineVersion: text, engineDigest: sha256, programDigest: sha256 };
+const sources = ['engine', 'enginePath', 'requirements', 'program', 'engineId'];
+function sourceSchema(properties = {}, required = []) {
+  return { ...object({ ...engineSource, ...properties }, required), oneOf: sources.map(field => ({ type: 'object', required: [field] })),
+    allOf: [{ if: { type: 'object', required: ['enginePath'] }, then: { type: 'object', required: ['repositoryRoot'] } },
+      { if: { type: 'object', required: ['engineId'] }, then: { type: 'object', required: ['repositoryRoot', 'engineVersion'] } }] };
+}
+const schemas = {};
+function add(name, schema) { schemas[`calctool-${name}`] = schema; }
+add('run', sourceSchema({ inputs: { type: 'object', additionalProperties: { anyOf: [{ type: 'string' }, { type: 'number' }] } } }, ['inputs']));
+add('compile', sourceSchema({}, ['repositoryRoot']));
+add('generate', sourceSchema({}, ['repositoryRoot']));
+add('compile-tool', sourceSchema({}, ['repositoryRoot']));
+add('verify', sourceSchema());
+add('final-gate', { oneOf: [sourceSchema(), FINAL_GATE16_INPUT_SCHEMA, FINAL_GATE16_READ_INPUT_SCHEMA] });
+add('estimate', sourceSchema());
+add('impact', sourceSchema({ changedKeys: array(text, 1) }, ['changedKeys']));
+add('status', object({ ...base, engineId: text, engineVersion: text, programDigest: sha256 }, ['repositoryRoot', 'engineId', 'engineVersion']));
+add('inventory', object(base, ['repositoryRoot']));
+add('purge', object({ ...base, engineId: text, engineVersion: text, programDigest: sha256 }, ['repositoryRoot', 'engineId', 'engineVersion', 'programDigest']));
+add('probe-env', object({}));
+add('adapt-config', object({ probe: record }));
+add('intake-round', object({ domainReference: record, message: { type: 'string' }, round: integer(0), confirmed: record }));
+add('brain-handshake', object({ brainMode: { enum: ['ide', 'hermes_local'] }, swarmEnabled: { type: 'boolean' }, blueprintEnabled: { type: 'boolean' } }));
+for (const name of ['brain-invoke', 'swarm-orchestrate']) add(name, object({ requirements: record }, ['requirements']));
+add('auto-pipeline', object({ requirements: record, authorized: { type: 'boolean' }, skipDialogue: { type: 'boolean' }, domainReference: record }, ['requirements', 'authorized']));
+const coordination = { runPlan: record, completedWorkItemIds: array(text), artifacts: record };
+add('brain-status', object({ runPlan: record, completedWorkItemIds: array(text) }, ['runPlan']));
+add('brain-resume', object({ runPlan: record, completedWorkItemIds: array(text), inFlightWorkItemIds: array(text), uncertainWorkItemIds: array(text) }, ['runPlan']));
+add('brain-complete', object(coordination, ['runPlan', 'artifacts']));
+add('brain-events', object({ events: { ...array(record), maxItems: 256 } }, ['events']));
+add('brain-cancel', object({ workItemIds: array(text), reason: { type: 'string' } }, ['workItemIds']));
+add('blueprint-orchestrate', sourceSchema({ goal: text }));
+export const CALCTOOL_LOCAL_OPERATION_SCHEMAS = Object.freeze(schemas);

package/local-calctool-runtime.mjs

@@ -0,0 +1,10 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+const runtimeUrl = new URL('./runtime/calctool-runtime-v7.0.43.mjs', import.meta.url);
+const expectedSha256 = '5d3506320d6baba4a8ca42cf55d062ae2b10f186741896c8cc93e536734f961f';
+export async function calctoolRuntimeBytes() {
+  const bytes = await readFile(runtimeUrl);
+  if (createHash('sha256').update(bytes).digest('hex') !== expectedSha256) throw Object.assign(new Error('Calctool packaged runtime digest mismatch'), { code: 'FORMULA_RUNTIME_INTEGRITY' });
+  return bytes;
+}
+export async function loadCalctoolRuntime() { await calctoolRuntimeBytes(); return import(runtimeUrl.href); }

package/local-calctool-storage.mjs

@@ -0,0 +1,101 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { withStateLock } from './local-state-lock.mjs';
+import { formulaDigest, formulaCanonical, verifyFormulaProgram } from './local-formula-engine.mjs';
+import { formulaError } from './local-decimal.mjs';
+
+const ID = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+const VERSION = /^\d+\.\d+\.\d+$/;
+async function realDirectory(directory, create) {
+  if (create) await fs.mkdir(directory, { mode: 0o700 }).catch(cause => { if (cause.code !== 'EEXIST') throw cause; });
+  const stat = await fs.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || await fs.realpath(directory) !== directory) throw formulaError('FORMULA_STATE_PATH', 'formula state directory must not contain symlinks');
+}
+export async function formulaStoreRoot(input, create = false) {
+  if (typeof input.repositoryRoot !== 'string' || !path.isAbsolute(input.repositoryRoot)) throw formulaError('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute');
+  const repositoryRoot = await fs.realpath(input.repositoryRoot);
+  const home = input.home ?? os.homedir();
+  if (typeof home !== 'string' || !path.isAbsolute(home)) throw formulaError('FORMULA_STATE_PATH', 'home must be absolute');
+  const normalized = await fs.realpath(home); let directory = normalized;
+  for (const component of ['.entrorove', 'calctool', formulaDigest(repositoryRoot)]) { directory = path.join(directory, component); await realDirectory(directory, create); }
+  return directory;
+}
+function identity(engineId, engineVersion) {
+  if (typeof engineId !== 'string' || !ID.test(engineId) || typeof engineVersion !== 'string' || !VERSION.test(engineVersion)) throw formulaError('FORMULA_ENGINE_IDENTITY', 'an explicit engineId and semantic engineVersion are required');
+}
+export async function readOwnedFormulaFile(file) {
+  const stat = await fs.lstat(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || await fs.realpath(file) !== file) throw formulaError('FORMULA_STATE_PATH', 'formula artifact must be a regular file without symlinked ancestors');
+  return fs.readFile(file);
+}
+async function atomic(file, bytes) {
+  const temporary = `${file}.tmp-${randomUUID()}`;
+  try { await fs.writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 }); await fs.rename(temporary, file); }
+  finally { await fs.rm(temporary, { force: true }); }
+}
+async function parsed(file) {
+  try { return JSON.parse(await readOwnedFormulaFile(file)); }
+  catch (cause) { if (cause instanceof SyntaxError) throw formulaError('FORMULA_STATE_CORRUPT', 'formula cache JSON is invalid'); throw cause; }
+}
+async function checkedDirectory(input, create = false) {
+  identity(input.engineId, input.engineVersion); const root = await formulaStoreRoot(input, create);
+  const engineRoot = path.join(root, input.engineId); await realDirectory(engineRoot, create);
+  const directory = path.join(engineRoot, input.engineVersion); await realDirectory(directory, create);
+  return directory;
+}
+export async function loadStoredFormula(input) {
+  const directory = await checkedDirectory(input); const program = verifyFormulaProgram(await parsed(path.join(directory, 'program.json')), input);
+  const manifest = await parsed(path.join(directory, 'manifest.json'));
+  if (manifest.schemaVersion !== 'entrorove.formula-cache/1.0' || manifest.programDigest !== program.programDigest || manifest.engineDigest !== program.engineDigest
+    || manifest.engineId !== program.engineId || manifest.engineVersion !== program.engineVersion || manifest.runtimeVersion !== program.runtimeVersion || !Array.isArray(manifest.files)) throw formulaError('FORMULA_STATE_CORRUPT', 'formula cache manifest binding is invalid');
+  const names = manifest.files.map(entry => entry.path).sort().join('|');
+  if (!['program.json', 'program.json|runtime.mjs|tool.mjs'].includes(names)) throw formulaError('FORMULA_STATE_CORRUPT', 'formula cache manifest must bind every generated file exactly once');
+  for (const entry of manifest.files) {
+    if (!['program.json', 'runtime.mjs', 'tool.mjs'].includes(entry.path) || formulaDigest(await readOwnedFormulaFile(path.join(directory, entry.path))) !== entry.sha256) throw formulaError('FORMULA_STATE_CORRUPT', 'formula cache file digest mismatch');
+  }
+  return { program, directory, manifest };
+}
+export async function storeFormula(input, program, toolFiles) {
+  verifyFormulaProgram(program);
+  const context = { ...input, engineId: program.engineId, engineVersion: program.engineVersion };
+  const root = await formulaStoreRoot(context, true);
+  return withStateLock(path.join(root, `${program.engineId}.state`), async () => {
+    const directory = await checkedDirectory(context, true); const file = path.join(directory, 'program.json');
+    try {
+      const existing = await loadStoredFormula(context);
+      if (existing.program.programDigest !== program.programDigest) throw formulaError('FORMULA_VERSION_CONFLICT', 'an engine version cannot be replaced by different formulas; increment semanticVersion');
+      if (!toolFiles || existing.manifest.files.length > 1) return { ...existing, reused: true };
+    } catch (cause) { if (cause.code !== 'ENOENT') throw cause; }
+    const entries = [{ path: 'program.json', bytes: Buffer.from(`${formulaCanonical(program)}\n`) }, ...(toolFiles ?? [])];
+    for (const entry of entries) await atomic(path.join(directory, entry.path), entry.bytes);
+    const manifest = { schemaVersion: 'entrorove.formula-cache/1.0', engineId: program.engineId, engineVersion: program.engineVersion,
+      engineDigest: program.engineDigest, programDigest: program.programDigest, runtimeVersion: program.runtimeVersion,
+      files: entries.map(entry => ({ path: entry.path, sha256: formulaDigest(entry.bytes) })) };
+    await atomic(path.join(directory, 'manifest.json'), Buffer.from(`${formulaCanonical(manifest)}\n`));
+    return { program, directory, manifest, reused: false };
+  });
+}
+export async function formulaInventory(input) {
+  let root;
+  try { root = await formulaStoreRoot(input); } catch (cause) { if (cause.code === 'ENOENT') return []; throw cause; }
+  const entries = [];
+  for (const engine of await fs.readdir(root, { withFileTypes: true })) {
+    if (!ID.test(engine.name) || engine.name.endsWith('.lock') || engine.name.endsWith('.state')) continue;
+    if (!engine.isDirectory() || engine.isSymbolicLink()) throw formulaError('FORMULA_STATE_PATH', 'formula cache engine directory is invalid');
+    for (const version of await fs.readdir(path.join(root, engine.name), { withFileTypes: true })) {
+      if (!VERSION.test(version.name) || !version.isDirectory() || version.isSymbolicLink()) throw formulaError('FORMULA_STATE_PATH', 'formula cache version directory is invalid');
+      const loaded = await loadStoredFormula({ ...input, engineId: engine.name, engineVersion: version.name }); entries.push(loaded.manifest);
+    }
+  }
+  return entries.sort((a, b) => `${a.engineId}/${a.engineVersion}` < `${b.engineId}/${b.engineVersion}` ? -1 : 1);
+}
+export async function purgeStoredFormula(input) {
+  if (!/^[0-9a-f]{64}$/.test(input.programDigest ?? '')) throw formulaError('FORMULA_PURGE_BINDING', 'purge requires the exact compiled program digest');
+  const root = await formulaStoreRoot(input); identity(input.engineId, input.engineVersion);
+  return withStateLock(path.join(root, `${input.engineId}.state`), async () => {
+    const loaded = await loadStoredFormula(input); await fs.rm(loaded.directory, { recursive: true });
+    return { purged: true, engineId: input.engineId, engineVersion: input.engineVersion, programDigest: loaded.program.programDigest };
+  });
+}