@entrorove/skill 0.1.23 → 0.1.24

package/local-archguard-mutation-fence.mjs

@@ -0,0 +1,28 @@
+import { promises as fs } from 'node:fs';
+import { context as handoffContext, readRegistry } from './local-task-handoff-storage.mjs';
+import { readTaskHandoffFence, assertTaskHandoffActive } from './local-task-handoff-fence.mjs';
+import { withExclusiveLock, fail } from './local-archguard-state.mjs';
+
+// This is the same physical directory used by 05's withStateLock(ctx.file).
+// Publish pid/token atomically and recover dead owners immediately, including SIGKILL.
+export async function withArchguardMutationFence(input, action, options = {}) {
+  const ctx = await handoffContext(input, true);
+  const ordinary = { repositoryRoot: ctx.root, home: ctx.home, flowId: ctx.flowId };
+  return withExclusiveLock(`${ctx.file}.lock`, async () => {
+    const registry = await readRegistry(ctx.registry);
+    if (!registry.bindings[ctx.registryKey]) {
+      try {
+        await fs.lstat(ctx.file);
+        fail('ENTROROVE_HANDOFF_FENCE', 'unregistered flow has existing handoff history; cloud recovery is required');
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      if (!options.bootstrap) fail('ENTROROVE_HANDOFF_FENCE', 'ordinary mutation requires an actually registered flow');
+      if (typeof options.bootstrap === 'function') await options.bootstrap();
+      return action(async () => {});
+    }
+    const state = await readTaskHandoffFence(ordinary);
+    const assertPaths = paths => assertTaskHandoffActive({ ...ordinary, epoch: state.epoch, ...(paths ? { paths } : {}) });
+    // Caller handoff/pass/lease fields never authorize an ordinary Archguard mutation.
+    await assertPaths(options.paths);
+    return action(assertPaths);
+  });
+}

package/local-archguard-operations.mjs

@@ -0,0 +1,25 @@
+import * as archguard from './local-archguard.mjs';
+import { runPureArchguardOperation } from './local-archguard-evaluate.mjs';
+import { ARCHGUARD_LOCAL_OPERATION_SCHEMAS } from './local-archguard-contracts.mjs';
+
+const capabilities = async () => ({ ...(await runPureArchguardOperation('capabilities', {})).output,
+  operations: Object.keys(ARCHGUARD_LOCAL_OPERATION_SCHEMAS), operationSchemas: ARCHGUARD_LOCAL_OPERATION_SCHEMAS,
+  stateDirectory: '~/.entrorove/archguard', executionBoundary: 'Only a real snapshot, Ed25519 pass and pinned cloud scope authorization permit a local checkpoint. Signed local receipts require separate cloud verification.' });
+export const ARCHGUARD_LOCAL_OPERATIONS = Object.freeze({
+  'archguard-capabilities': capabilities, 'archguard-help': capabilities,
+  'archguard-intake': input => runPureArchguardOperation('intake', input),
+  'archguard-template-list': input => runPureArchguardOperation('template-list', input),
+  'archguard-contract-create': archguard.archguardContractCreate,
+  'archguard-contract-get': archguard.archguardContractGet,
+  'archguard-contract-update': archguard.archguardContractUpdate,
+  'archguard-snapshot': archguard.archguardSnapshot,
+  'archguard-checkpoint': archguard.archguardCheckpoint,
+  'archguard-scope-request': archguard.archguardScopeRequest,
+  'archguard-rules-scan': archguard.archguardRulesScan,
+  'archguard-complexity-report': archguard.archguardComplexityReport,
+  'archguard-drift-status': archguard.archguardDriftStatus,
+  'archguard-ledger-init': archguard.archguardLedgerInit,
+  'archguard-ledger-query': archguard.archguardLedgerQuery,
+  'archguard-human-resume': archguard.archguardHumanResume,
+  'archguard-human-direction-request': archguard.archguardHumanDirectionRequest,
+});

package/local-archguard-scope.mjs

@@ -0,0 +1,64 @@
+import { withArchguardMutationFence } from './local-archguard-mutation-fence.mjs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { snapshotVerify, verifyMutationPass } from './local-execution.mjs';
+import { context, withExclusiveLock, readLedger, readBytes, readJson, canonical, sha256, fail } from './local-archguard-state.mjs';
+import { freezeContract } from './local-archguard-contract.mjs';
+import { loadSnapshot, drift, MISSING_SHA256, history } from './local-archguard-snapshot.mjs';
+import { signRunnerReceipt, verifyAcceptedWorkflow } from './local-archguard-signing.mjs';
+
+export async function archguardScopeRequest(input) {
+  return withArchguardMutationFence(input, async () => {
+    const ctx = await context(input);
+    return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), async () => {
+    const ledger = await readLedger(ctx); const snapshot = await loadSnapshot(ctx, input.snapshotId);
+    if (drift(ledger).interrupted) fail('ARCH_RED_INTERRUPT', 'scope request is interrupted by the red architecture checkpoint history');
+    if (snapshot.stepId !== input.stepId || ledger.entries.some(item => item.event === 'checkpoint' && item.data.snapshotId === input.snapshotId)) fail('ARCH_SCOPE_REQUEST_REPLAY', 'scope request snapshot belongs to another step or was already consumed');
+    const workflow = await verifyAcceptedWorkflow(ctx, input); const plan = workflow.step.executionPlan;
+    const locked = await freezeContract(ctx);
+    if (locked.contractDigest !== snapshot.contractDigest || plan.contracts.archguard?.contractSha256 !== snapshot.contractDigest
+      || typeof plan.contracts.aimlock?.snapshotSha256 !== 'string' || !/^[0-9a-f]{64}$/.test(input.scopeArtifactDigest)
+      || snapshot.paths.some(relative => !plan.files.some(file => file.path === relative))) fail('ARCH_SCOPE_REQUEST_BINDING', 'scope request must preserve the exact accepted architecture contract, original snapshot, scope artifact, and frozen files');
+    for (const expected of snapshot.files) {
+      const actual = await readBytes(path.join(ctx.root, expected.path), true, ctx);
+      if ((actual.exists ? sha256(actual.content) : MISSING_SHA256) !== expected.sha256) fail('ARCH_SCOPE_REQUEST_CHANGED', 'scope request must be issued before writing the snapshotted block');
+    }
+    const savedPass = await readJson(input.gatePassPath);
+    const verified = await verifyMutationPass({ ...input, repositoryRoot: ctx.root, targetPath: snapshot.paths[0] });
+    const pass = verified.pass;
+    if (canonical(pass) !== canonical(savedPass) || pass.snapshotId !== snapshot.snapshotId
+      || pass.snapshotReceipt.snapshotDigest !== snapshot.snapshotDigest || pass.stepId !== snapshot.stepId
+      || canonical(pass.paths) !== canonical([...snapshot.paths, 'arch.contract.yaml'].sort())) fail('ARCH_SCOPE_REQUEST_PASS', 'scope request must bind the exact real mutation pass and snapshot path set');
+    await snapshotVerify({ ...input, repositoryRoot: ctx.root, snapshotId: snapshot.snapshotId });
+    const expires = Math.min(Date.now() + 90_000, Date.parse(pass.expiresAt), Date.parse(workflow.lease.expiresAt), Date.parse(workflow.plan.expiresAt));
+    const receipt = await signRunnerReceipt(ctx, { schemaVersion: 'entrorove.archguard-snapshot-receipt/1.0', repositoryDigest: ctx.repositoryDigest,
+      flowId: ctx.flowId, ownerId: workflow.plan.ownerId, taskDigest: workflow.plan.taskDigest, chainDigest: workflow.plan.chainDigest,
+      scopeArtifactDigest: input.scopeArtifactDigest, contractDigest: snapshot.contractDigest, stepId: input.stepId,
+      leaseId: workflow.lease.leaseId, generation: workflow.lease.generation, originalSnapshotDigest: plan.contracts.aimlock.snapshotSha256,
+      snapshotDigest: snapshot.snapshotDigest, passDigest: sha256(canonical(pass)), paths: snapshot.paths,
+      issuedAt: new Date().toISOString(), expiresAt: new Date(expires).toISOString(), nonce: randomUUID() }, true);
+    return { snapshotReceipt: receipt, authorizesWrite: false, nextOperation: 'archguard-scope-authorize' };
+    });
+  });
+}
+export async function archguardHumanDirectionRequest(input) {
+  return withArchguardMutationFence(input, async () => {
+    const ctx = await context(input);
+    return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), async () => {
+    const ledger = await readLedger(ctx);
+    if (!drift(ledger).interrupted) fail('ARCH_HUMAN_REQUEST_NOT_RED', 'human direction request requires the real interrupted local checkpoint ledger');
+    const workflow = await verifyAcceptedWorkflow(ctx, input); const locked = await freezeContract(ctx);
+    if (workflow.step.executionPlan.contracts.archguard?.contractSha256 !== locked.contractDigest
+      || !/^[0-9a-f]{64}$/.test(input.scopeArtifactDigest)) fail('ARCH_HUMAN_REQUEST_BINDING', 'human direction request must preserve the original accepted architecture and scope authority');
+    const last = history(ledger).at(-1);
+    if (!last || last.status !== 'blocked') fail('ARCH_HUMAN_REQUEST_INCOMPLETE', 'human direction request lacks a real blocked checkpoint');
+    const expires = Math.min(Date.now() + 90_000, Date.parse(workflow.lease.expiresAt), Date.parse(workflow.plan.expiresAt));
+    const receipt = await signRunnerReceipt(ctx, { schemaVersion: 'entrorove.archguard-ledger-head-receipt/1.0', repositoryDigest: ctx.repositoryDigest,
+      flowId: ctx.flowId, ownerId: workflow.plan.ownerId, taskDigest: workflow.plan.taskDigest, chainDigest: workflow.plan.chainDigest,
+      scopeArtifactDigest: input.scopeArtifactDigest, contractDigest: locked.contractDigest, stepId: input.stepId,
+      leaseId: workflow.lease.leaseId, generation: workflow.lease.generation, ledgerHeadDigest: ledger.headDigest,
+      lastCheckpointId: last.checkpointId, issuedAt: new Date().toISOString(), expiresAt: new Date(expires).toISOString(), nonce: randomUUID() }, true);
+    return { ledgerHeadReceipt: receipt, authorizesWrite: false, nextOperation: 'archguard-human-direction-authorize' };
+    });
+  });
+}

package/local-archguard-signing.mjs

@@ -0,0 +1,52 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { createPublicKey, sign, verify } from 'node:crypto';
+import Ajv from 'ajv';
+import { WORKFLOW_ACCEPTED_PLAN_SCHEMA, WORKFLOW_LOCAL_LEASE_SCHEMA } from './workflow-local-contracts.mjs';
+import { authority, canonical, sha256, readBytes, fail } from './local-archguard-state.mjs';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+const planValid = ajv.compile(WORKFLOW_ACCEPTED_PLAN_SCHEMA);
+const leaseValid = ajv.compile(WORKFLOW_LOCAL_LEASE_SCHEMA);
+
+export async function signRunnerReceipt(ctx, payload, required = false) {
+  const config = await authority(ctx);
+  if (!config.runnerSignerFile && !config.runnerPublicKey) {
+    if (required) fail('ARCH_RUNNER_SIGNER_REQUIRED', 'a pinned trusted runner signer is required for this receipt');
+    return null;
+  }
+  if (typeof config.runnerSignerFile !== 'string' || typeof config.runnerPublicKey !== 'string') fail('ARCH_RUNNER_CONFIG_INVALID', 'trusted runner signer configuration is incomplete');
+  const relative = path.relative(ctx.stateRoot, config.runnerSignerFile);
+  if (!path.isAbsolute(config.runnerSignerFile) || relative.startsWith('..') || path.isAbsolute(relative)) fail('ARCH_RUNNER_CONFIG_INVALID', 'runner signer must remain in Entrorove private state');
+  const bytes = await readBytes(config.runnerSignerFile); const stat = await fs.lstat(config.runnerSignerFile);
+  if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) fail('ARCH_RUNNER_PERMISSIONS', 'runner signer must have private permissions');
+  const privateKey = bytes.content.toString('utf8'); const key = createPublicKey(privateKey); const der = key.export({ type: 'spki', format: 'der' });
+  if (key.asymmetricKeyType !== 'ed25519' || der.toString('base64') !== config.runnerPublicKey) fail('ARCH_RUNNER_IDENTITY', 'Ed25519 runner signer does not match its pinned public key');
+  const value = { ...payload, keyId: sha256(der) };
+  return { ...value, signature: sign(null, Buffer.from(canonical(value)), privateKey).toString('base64url') };
+}
+export async function verifyAcceptedWorkflow(ctx, input) {
+  if (!planValid(input.acceptedPlan) || !leaseValid(input.lease)) fail('ARCH_WORKFLOW_SCHEMA', 'the accepted plan and lease must satisfy their exact workflow contracts');
+  const config = await authority(ctx); const der = Buffer.from(config.publicKey, 'base64');
+  const key = createPublicKey({ key: der, type: 'spki', format: 'der' });
+  const unsigned = value => {
+    const { authorityReceipt: receipt, ...payload } = value; const bytes = Buffer.from(canonical(payload));
+    if (bytes.length > 1024 * 1024 || receipt.schemaVersion !== 'entrorove.workflow-authority-receipt/1.0'
+      || receipt.keyId !== sha256(der) || receipt.payloadDigest !== sha256(bytes)
+      || !verify(null, bytes, key, Buffer.from(receipt.signature, 'base64url'))) fail('ARCH_WORKFLOW_AUTHORITY', 'workflow plan or lease signature is invalid');
+    return payload;
+  };
+  const plan = unsigned(input.acceptedPlan); const lease = unsigned(input.lease); const now = Date.now();
+  const step = plan.steps.find(value => value.stepId === input.stepId);
+  if (!step || plan.flowId !== ctx.flowId || lease.stepId !== input.stepId || !config.actors.includes(plan.ownerId)
+    || ['planId', 'flowId', 'ownerId', 'taskDigest', 'chainDigest', 'chainRevision'].some(key => lease[key] !== plan[key])
+    || lease.planDigest !== sha256(canonical(plan)) || lease.sequence !== step.sequence
+    || step.executionPlanSha256 !== sha256(canonical(step.executionPlan) + '\n')
+    || plan.runnerKeyId !== sha256(Buffer.from(config.runnerPublicKey ?? '', 'base64'))
+    || Date.parse(plan.acceptedAt) > now || Date.parse(plan.expiresAt) <= now
+    || Date.parse(lease.issuedAt) > now || Date.parse(lease.expiresAt) <= now
+    || Date.parse(lease.expiresAt) <= Date.parse(lease.issuedAt)) fail('ARCH_WORKFLOW_BINDING', 'original accepted plan, runner, flow, owner, task, chain, step, or live lease does not match');
+  const dependencyIds = lease.verifiedDependencies.map(value => value.stepId);
+  if (new Set(dependencyIds).size !== dependencyIds.length || canonical([...dependencyIds].sort()) !== canonical([...step.dependsOn].sort())) fail('ARCH_WORKFLOW_DEPENDENCIES', 'the signed lease does not verify every frozen step dependency');
+  return { plan, lease, step };
+}

package/local-archguard-snapshot.mjs

@@ -0,0 +1,126 @@
+import { withArchguardMutationFence } from './local-archguard-mutation-fence.mjs';
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { snapshotPlan, snapshotVerify } from './local-execution.mjs';
+import { context, safeId, safePath, noLinks, canonical, sha256, readBytes, readJson,
+  atomicJson, seal, unseal, withExclusiveLock, appendLedger, readLedger, fail } from './local-archguard-state.mjs';
+import { freezeContract, loadContractLock } from './local-archguard-contract.mjs';
+import { readBudgetedProjectFile } from './local-budget-reads.mjs';
+
+export const MISSING_SHA256 = sha256('entrorove.missing-file/1.0');
+export function sourcePaths(paths) {
+  if (!Array.isArray(paths) || !paths.length) fail('ARCH_SCOPE_EMPTY', 'snapshot paths must not be empty');
+  const normalized = paths.map(safePath).sort();
+  if (new Set(normalized).size !== normalized.length || normalized.includes('arch.contract.yaml')) fail('ARCH_SCOPE_INVALID', 'source paths must be unique and cannot include the locked contract file');
+  return normalized;
+}
+export function history(ledger) {
+  const lastDirection = ledger.entries.findLastIndex(item => item.event === 'human-resume');
+  return ledger.entries.slice(lastDirection + 1).filter(item => item.event === 'checkpoint').map(item => item.data.ledgerEntry);
+}
+export function drift(ledger) {
+  const checkpoints = history(ledger); const last = checkpoints.slice(-3);
+  const shared = last.length === 3 && last.every(entry => entry.status === 'blocked')
+    ? last[0].blockingRuleIds.filter(rule => last.every(entry => entry.blockingRuleIds.includes(rule))) : [];
+  return { light: shared.length ? 'red' : checkpoints.at(-1)?.status === 'blocked' ? 'yellow' : 'green',
+    interrupted: shared.length > 0, ruleIds: shared, consecutiveBlocks: shared.length ? 3 : 0 };
+}
+function snapshotFile(ctx, snapshotId) { return path.join(ctx.directory, 'snapshots', `${safeId(snapshotId, 'snapshotId')}.json`); }
+async function cachedSource(ctx, snapshotId, file) {
+  const target = path.join(ctx.home, '.entrorove', 'snapshots', ctx.repositoryDigest, ctx.flowId, safeId(snapshotId, 'snapshotId'), safePath(file.path));
+  await noLinks(target, !file.exists);
+  if (!file.exists) {
+    try { await fs.lstat(target); fail('ARCH_SNAPSHOT_TAMPERED', 'a missing-file snapshot acquired source bytes'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    return null;
+  }
+  const bytes = await readBudgetedProjectFile({ home: ctx.home, repositoryRoot: ctx.root, flowId: ctx.flowId }, target, { sourcePath: file.path });
+  await noLinks(target);
+  if (sha256(bytes) !== file.sha256) fail('ARCH_SNAPSHOT_TAMPERED', 'native snapshot source digest changed');
+  return bytes;
+}
+export async function loadSnapshot(ctx, snapshotId) {
+  const snapshot = await unseal(ctx, await readJson(snapshotFile(ctx, snapshotId)));
+  if (snapshot.schemaVersion !== 'entrorove.archguard-snapshot/2.0' || snapshot.files.some(file => Object.hasOwn(file, 'content'))) fail('ARCH_SNAPSHOT_FORMAT', 'use a metadata-only snapshot with bound native source copies');
+  if (snapshot.repositoryDigest !== ctx.repositoryDigest || snapshot.flowId !== ctx.flowId || snapshot.snapshotId !== snapshotId
+    || snapshot.contentDigest !== sha256(canonical(snapshot.files))) fail('ARCH_SNAPSHOT_TAMPERED', 'snapshot is not bound to the repository or content');
+  const files = [];
+  for (const file of snapshot.files) { const bytes = await cachedSource(ctx, snapshotId, file); files.push({ ...file, content: bytes?.toString('base64') ?? null }); }
+  return { ...snapshot, files };
+}
+export async function archguardSnapshot(input) {
+  const paths = sourcePaths(input.paths); const snapshotId = safeId(input.snapshotId ?? `snap-${randomUUID()}`, 'snapshotId');
+  return withArchguardMutationFence(input, async () => {
+    const ctx = await context(input);
+    return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), async () => withExclusiveLock(path.join(ctx.directory, 'mutation.lock'), async () => {
+    const ledger = await readLedger(ctx);
+    if (drift(ledger).interrupted) fail('ARCH_RED_INTERRUPT', 'three consecutive blocks triggered a red interrupt; human direction is required');
+    const current = await freezeContract(ctx); const stepId = safeId(input.stepId, 'stepId'); const files = [];
+    for (const relative of [...paths, 'arch.contract.yaml'].sort()) {
+      const value = await readBytes(path.join(ctx.root, relative), true, ctx);
+      files.push({ path: relative, exists: value.exists, content: value.exists ? value.content.toString('base64') : null,
+        sha256: value.exists ? sha256(value.content) : MISSING_SHA256, mode: value.mode });
+    }
+    const native = await snapshotPlan({ ...input, repositoryRoot: ctx.root, paths: files.map(file => file.path), snapshotId,
+      contractDigest: current.contractDigest });
+    const verified = await snapshotVerify({ ...input, repositoryRoot: ctx.root, snapshotId });
+    for (const file of files) {
+      const actual = await readBytes(path.join(ctx.root, file.path), true, ctx);
+      if ((actual.exists ? sha256(actual.content) : MISSING_SHA256) !== file.sha256) fail('ARCH_SNAPSHOT_RACE', 'source changed while creating its snapshot');
+    }
+    const metadata = files.map(({ content, ...file }) => file);
+    const snapshot = { schemaVersion: 'entrorove.archguard-snapshot/2.0', snapshotId, stepId, flowId: ctx.flowId,
+      repositoryDigest: ctx.repositoryDigest, paths, files: metadata, contentDigest: sha256(canonical(metadata)),
+      snapshotDigest: native.snapshotDigest, contractDigest: current.contractDigest, contractRawDigest: current.rawDigest,
+      receipt: verified.receipt };
+    await atomicJson(snapshotFile(ctx, snapshotId), await seal(ctx, snapshot), true);
+    await appendLedger(ctx, 'snapshot', { snapshotId, stepId, snapshotDigest: snapshot.snapshotDigest, contractDigest: current.contractDigest, paths });
+    return { schemaVersion: snapshot.schemaVersion, snapshotId, paths, snapshotDigest: snapshot.snapshotDigest,
+      contractDigest: current.contractDigest, receipt: snapshot.receipt };
+  }));
+  }, { paths, bootstrap: async () => {
+    const lock = await loadContractLock(await context(input), false);
+    if (!lock?.usedConfirmations?.length) fail('ENTROROVE_HANDOFF_FENCE', 'bootstrap snapshot requires an explicitly confirmed architecture contract');
+  } });
+}
+export async function restoreSnapshot(ctx, snapshot) {
+  const prepared = []; const completed = []; const lock = await loadContractLock(ctx);
+  const contractIsCurrent = lock.contractDigest === snapshot.contractDigest && lock.rawDigest === snapshot.contractRawDigest;
+  const files = contractIsCurrent ? snapshot.files : snapshot.files.filter(file => file.path !== 'arch.contract.yaml');
+  try {
+    for (const file of files) {
+      const target = path.join(ctx.root, safePath(file.path)); await noLinks(path.dirname(target), true);
+      await fs.mkdir(path.dirname(target), { recursive: true }); await noLinks(path.dirname(target));
+      let old; try { old = await readBytes(target, true, ctx); } catch (error) {
+        if (error.code !== 'ARCH_SYMLINK_REJECTED') throw error;
+        const stat = await fs.lstat(target); if (!stat.isSymbolicLink()) throw error;
+        old = { symlink: await fs.readlink(target), exists: true };
+      }
+      const temporary = `${target}.${randomUUID()}.rollback`;
+      if (file.exists) {
+        const bytes = await cachedSource(ctx, snapshot.snapshotId, file);
+        if (file.content !== bytes.toString('base64')) fail('ARCH_SNAPSHOT_TAMPERED', 'snapshot content does not match its budgeted native copy');
+        await fs.writeFile(temporary, bytes, { flag: 'wx', mode: file.mode });
+      }
+      prepared.push({ file, target, temporary, old });
+    }
+    for (const item of prepared) {
+      await noLinks(path.dirname(item.target));
+      if (item.file.exists) await fs.rename(item.temporary, item.target);
+      else await fs.rm(item.target, { force: true });
+      completed.push(item);
+    }
+    return { restored: true, paths: files.map(file => file.path), contractRestored: contractIsCurrent,
+      reason: contractIsCurrent ? 'snapshot restored' : 'new explicitly authorized contract revision preserved' };
+  } catch (error) {
+    for (const item of completed.reverse()) {
+      try {
+        if (!item.old.exists) await fs.rm(item.target, { force: true });
+        else if (item.old.symlink) { await fs.rm(item.target, { force: true }); await fs.symlink(item.old.symlink, item.target); }
+        else await fs.writeFile(item.target, item.old.content, { mode: item.old.mode, flag: 'w' });
+      } catch { fail('ARCH_ROLLBACK_FAILED', 'rollback recovery failed; repository requires explicit repair'); }
+    }
+    fail('ARCH_ROLLBACK_FAILED', `snapshot restore failed: ${error.code ?? 'filesystem error'}`);
+  } finally { for (const item of prepared) await fs.rm(item.temporary, { force: true }); }
+}

package/local-archguard-state.mjs

@@ -0,0 +1,200 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { generateKeyPairSync, createPublicKey, sign, verify, randomUUID } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { readBudgetedProjectFile } from './local-budget-reads.mjs';
+
+export { canonical, sha256 };
+export function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
+export function safeId(value, field) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) fail('ARCH_ID_INVALID', `${field} is invalid`);
+  return value;
+}
+export function safePath(value) {
+  if (typeof value !== 'string' || value !== value.normalize('NFC') || path.isAbsolute(value) || /^[A-Za-z]:/.test(value)
+    || /[\\\u0000-\u001f\u007f]/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..')) fail('ARCH_PATH_UNSAFE', 'path is unsafe');
+  return value;
+}
+export async function noLinks(target, missing = false) {
+  const absolute = path.resolve(target); const parts = absolute.split(path.sep).filter(Boolean); let current = path.parse(absolute).root;
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part);
+    try {
+      const stat = await fs.lstat(current);
+      if (stat.isSymbolicLink()) fail('ARCH_SYMLINK_REJECTED', 'symbolic links are forbidden in an Archguard path');
+      if (index < parts.length - 1 && !stat.isDirectory()) fail('ARCH_PATH_INVALID', 'path ancestor must be a directory');
+    } catch (error) { if (error.code === 'ENOENT' && missing) return absolute; throw error; }
+  }
+  return absolute;
+}
+export async function readBytes(file, missing = false, sourceContext = null) {
+  await noLinks(file, missing); let handle;
+  try {
+    handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = await handle.stat();
+    if (!stat.isFile()) fail('ARCH_FILE_INVALID', 'Archguard input must be a regular file');
+    const content = sourceContext
+      ? await readBudgetedProjectFile({ home: sourceContext.home, repositoryRoot: sourceContext.root, flowId: sourceContext.flowId }, file,
+        { sourcePath: path.relative(sourceContext.root, file).split(path.sep).join('/') })
+      : await handle.readFile();
+    const after = await handle.stat();
+    const nameStat = await fs.lstat(file);
+    if (stat.ino !== after.ino || stat.size !== after.size || stat.mtimeMs !== after.mtimeMs
+      || nameStat.ino !== stat.ino || nameStat.dev !== stat.dev || nameStat.isSymbolicLink()) fail('ARCH_READ_RACE', 'file changed during safe read');
+    return { content, mode: stat.mode & 0o777, exists: true };
+  } catch (error) { if (missing && error.code === 'ENOENT') return { content: null, mode: null, exists: false }; throw error; }
+  finally { if (handle) await handle.close(); }
+}
+export async function privateDirectory(directory) {
+  await noLinks(directory, true); await fs.mkdir(directory, { recursive: true, mode: 0o700 }); await noLinks(directory);
+  if (!(await fs.lstat(directory)).isDirectory()) fail('ARCH_STATE_INVALID', 'state directory must be a real directory');
+  if (process.platform !== 'win32') await fs.chmod(directory, 0o700);
+  return directory;
+}
+export async function atomicJson(file, value, exclusive = false) {
+  await privateDirectory(path.dirname(file)); await noLinks(file, true);
+  if (exclusive) { await fs.writeFile(file, canonical(value) + '\n', { mode: 0o600, flag: 'wx' }); return; }
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try { await fs.writeFile(temporary, canonical(value) + '\n', { mode: 0o600, flag: 'wx' }); await fs.rename(temporary, file); }
+  finally { await fs.rm(temporary, { force: true }); }
+}
+export async function atomicBytes(file, bytes, mode = 0o600) {
+  await privateDirectory(path.dirname(file)); await noLinks(file, true);
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try { await fs.writeFile(temporary, bytes, { mode, flag: 'wx' }); await fs.rename(temporary, file); }
+  finally { await fs.rm(temporary, { force: true }); }
+}
+export async function readJson(file) { return JSON.parse((await readBytes(file)).content.toString('utf8')); }
+export async function context(input) {
+  if (typeof input.repositoryRoot !== 'string') fail('ARCH_ROOT_REQUIRED', 'repositoryRoot is required');
+  const root = await noLinks(path.resolve(input.repositoryRoot));
+  if (!(await fs.lstat(root)).isDirectory()) fail('ARCH_ROOT_INVALID', 'repositoryRoot must be a directory');
+  const home = input.home ?? os.homedir();
+  if (typeof home !== 'string' || !path.isAbsolute(home)) fail('ARCH_HOME_INVALID', 'home must be an absolute path');
+  const stateRoot = path.join(home, '.entrorove', 'archguard'); await privateDirectory(stateRoot);
+  const repositoryDigest = sha256(root).slice(0, 32); const flowId = safeId(input.flowId, 'flowId');
+  return { root, home, flowId, repositoryDigest, stateRoot,
+    repositoryState: path.join(stateRoot, 'repositories', repositoryDigest),
+    directory: path.join(stateRoot, 'flows', repositoryDigest, flowId) };
+}
+export async function withExclusiveLock(file, action) {
+  await privateDirectory(path.dirname(file)); await noLinks(file, true);
+  const token = randomUUID();
+  try { await fs.mkdir(file, { mode: 0o700 }); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    if (!await recoverDeadLock(file)) fail('ARCH_CONCURRENT_REJECTED', 'concurrent Archguard mutation rejected');
+    try { await fs.mkdir(file, { mode: 0o700 }); }
+    catch (cause) { if (cause.code === 'EEXIST') fail('ARCH_CONCURRENT_REJECTED', 'concurrent Archguard mutation rejected'); throw cause; }
+  }
+  const ownerFile = path.join(file, 'owner.json');
+  await publishLockOwner(ownerFile, { pid: process.pid, token });
+  try { return await action(); }
+  finally {
+    const owner = await readJson(ownerFile);
+    if (owner.token !== token || owner.pid !== process.pid) fail('ARCH_LOCK_OWNERSHIP', 'Archguard mutation lock ownership changed');
+    await fs.unlink(ownerFile); await fs.rmdir(file);
+  }
+}
+async function publishLockOwner(file, owner) {
+  const staged = `${file}.${owner.token}.tmp`;
+  try {
+    await fs.writeFile(staged, canonical(owner) + '\n', { flag: 'wx', mode: 0o600 });
+    await fs.link(staged, file);
+  } finally { await fs.rm(staged, { force: true }); }
+}
+async function recoverDeadLock(file) {
+  let stat; let owner;
+  try { stat = await fs.lstat(file); }
+  catch (error) { if (error.code === 'ENOENT') return true; throw error; }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ARCH_LOCK_INVALID', 'Archguard mutation lock must be a real directory');
+  try { owner = await readJson(path.join(file, 'owner.json')); }
+  catch (error) { if (['ENOENT', 'ARCH_READ_RACE'].includes(error.code) || error instanceof SyntaxError) return false; throw error; }
+  if (!owner || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 || typeof owner.token !== 'string') fail('ARCH_LOCK_INVALID', 'Archguard mutation lock has no valid process owner');
+  try { process.kill(owner.pid, 0); return false; } catch (error) { if (error.code !== 'ESRCH') return false; }
+  const moved = `${file}.dead-${randomUUID()}`;
+  try { await fs.rename(file, moved); } catch (error) { if (error.code === 'ENOENT') return true; throw error; }
+  const after = await fs.lstat(moved);
+  if (stat.ino !== after.ino || stat.dev !== after.dev) {
+    await fs.rename(moved, file); fail('ARCH_LOCK_RACE', 'Archguard mutation lock changed during dead process recovery');
+  }
+  await fs.unlink(path.join(moved, 'owner.json')); await fs.rmdir(moved); return true;
+}
+async function signingKey(ctx) {
+  const file = path.join(ctx.repositoryState, 'state-signer.json'); await privateDirectory(ctx.repositoryState);
+  try {
+    const stat = await fs.lstat(file);
+    if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) fail('ARCH_KEY_PERMISSIONS', 'state signer must have private permissions');
+    const key = await readJson(file); const derived = createPublicKey(key.privateKey).export({ type: 'spki', format: 'der' }).toString('base64');
+    if (key.publicKey !== derived) fail('ARCH_STATE_KEY_INVALID', 'state signer identity changed');
+    return key;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const pair = generateKeyPairSync('ed25519');
+    const key = { privateKey: pair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+      publicKey: pair.publicKey.export({ type: 'spki', format: 'der' }).toString('base64') };
+    try { await atomicJson(file, key, true); return key; } catch (cause) { if (cause.code === 'EEXIST') return signingKey(ctx); throw cause; }
+  }
+}
+export async function seal(ctx, value) {
+  const key = await signingKey(ctx);
+  return { ...value, stateSignature: sign(null, Buffer.from(canonical(value)), key.privateKey).toString('base64url') };
+}
+export async function unseal(ctx, signed) {
+  const key = await signingKey(ctx); const { stateSignature, ...value } = signed;
+  const publicKey = createPublicKey({ key: Buffer.from(key.publicKey, 'base64'), type: 'spki', format: 'der' });
+  if (typeof stateSignature !== 'string' || !verify(null, Buffer.from(canonical(value)), publicKey, Buffer.from(stateSignature, 'base64url'))) fail('ARCH_STATE_TAMPERED', 'signed Archguard state was tampered');
+  return value;
+}
+export async function readLedger(ctx) {
+  const ledgerPath = path.join(ctx.directory, 'ledger.jsonl'); const headPath = path.join(ctx.directory, 'head.json');
+  const bytes = await readBytes(ledgerPath, true); const headBytes = await readBytes(headPath, true);
+  if (!bytes.exists && !headBytes.exists) return { entries: [], headDigest: null, ledgerPath };
+  if (!bytes.exists || !headBytes.exists) fail('ARCH_LEDGER_UNMANAGED', 'ledger has no managed signed head');
+  const entries = bytes.content.toString('utf8').trim().split('\n').map(line => JSON.parse(line)); let previousDigest = null;
+  for (const [index, signed] of entries.entries()) {
+    const value = await unseal(ctx, signed); const { digest, ...core } = value;
+    if (value.sequence !== index + 1 || value.previousDigest !== previousDigest || sha256(canonical(core)) !== digest
+      || value.flowId !== ctx.flowId || value.repositoryDigest !== ctx.repositoryDigest) fail('ARCH_LEDGER_TAMPERED', 'ledger hash chain is invalid');
+    previousDigest = digest;
+  }
+  const head = await unseal(ctx, JSON.parse(headBytes.content.toString('utf8')));
+  if (head.sequence !== entries.length || head.digest !== previousDigest || head.flowId !== ctx.flowId
+    || head.repositoryDigest !== ctx.repositoryDigest) fail('ARCH_LEDGER_TAMPERED', 'ledger signed head rejects truncation or reordering');
+  return { entries, headDigest: previousDigest, ledgerPath };
+}
+export async function appendLedger(ctx, event, data) {
+  const previous = await readLedger(ctx); const core = { schemaVersion: 'entrorove.archguard-ledger/1.0',
+    sequence: previous.entries.length + 1, previousDigest: previous.headDigest, repositoryDigest: ctx.repositoryDigest,
+    flowId: ctx.flowId, event, data, at: new Date().toISOString() };
+  const record = await seal(ctx, { ...core, digest: sha256(canonical(core)) });
+  await privateDirectory(ctx.directory);
+  const handle = await fs.open(previous.ledgerPath, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1) fail('ARCH_LEDGER_UNSAFE', 'append-only ledger must be an unshared regular managed file');
+    await handle.writeFile(canonical(record) + '\n'); await handle.sync();
+  } finally { await handle.close(); }
+  await atomicJson(path.join(ctx.directory, 'head.json'), await seal(ctx, {
+    sequence: record.sequence, digest: record.digest, flowId: ctx.flowId, repositoryDigest: ctx.repositoryDigest }));
+  return record;
+}
+export async function authority(ctx) {
+  const file = path.join(ctx.stateRoot, 'authorities', `${ctx.repositoryDigest}.json`); const stat = await fs.lstat(file);
+  if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) fail('ARCH_AUTHORITY_PERMISSIONS', 'authority configuration must have private permissions');
+  const value = await readJson(file);
+  if (value.schemaVersion !== 'entrorove.archguard-authority/1.0' || !Array.isArray(value.actors) || !value.actors.length || typeof value.publicKey !== 'string') fail('ARCH_AUTHORITY_INVALID', 'pinned architecture authority is not configured');
+  const der = Buffer.from(value.publicKey, 'base64'); const key = createPublicKey({ key: der, type: 'spki', format: 'der' });
+  if (key.asymmetricKeyType !== 'ed25519' || key.export({ type: 'spki', format: 'der' }).toString('base64') !== value.publicKey) fail('ARCH_AUTHORITY_INVALID', 'pinned architecture authority must be canonical Ed25519 SPKI');
+  return value;
+}
+export async function verifyAuthority(ctx, signed, schemaVersion) {
+  if (!signed || typeof signed.signature !== 'string') fail('ARCH_CONFIRMATION_REQUIRED', 'signed authority confirmation is required');
+  const key = await authority(ctx); const { signature, ...value } = signed; const der = Buffer.from(key.publicKey, 'base64');
+  const now = Date.now(); const issued = Date.parse(value.issuedAt); const expires = Date.parse(value.expiresAt);
+  if (value.schemaVersion !== schemaVersion || value.repositoryDigest !== ctx.repositoryDigest || value.flowId !== ctx.flowId
+    || !Number.isFinite(issued) || !Number.isFinite(expires) || issued > now || expires <= now || expires <= issued || expires - issued > 300_000
+    || value.keyId !== sha256(der) || !verify(null, Buffer.from(canonical(value)), createPublicKey({ key: der, type: 'spki', format: 'der' }), Buffer.from(signature, 'base64url'))) fail('ARCH_AUTHORIZATION_INVALID', 'authority signature, repository, flow, or lifetime is invalid');
+  safeId(value.nonce, 'authority nonce'); return { value, authority: key };
+}

package/local-archguard.mjs

@@ -0,0 +1,74 @@
+import { withArchguardMutationFence } from './local-archguard-mutation-fence.mjs';
+export { archguardContractGet, archguardContractCreate, archguardContractUpdate } from './local-archguard-contract.mjs';
+export { archguardSnapshot } from './local-archguard-snapshot.mjs';
+export { archguardCheckpoint } from './local-archguard-checkpoint.mjs';
+export { archguardScopeRequest, archguardHumanDirectionRequest } from './local-archguard-scope.mjs';
+
+import path from 'node:path';
+import { context, safePath, readBytes, readLedger, withExclusiveLock, fail, verifyAuthority, appendLedger, sha256, canonical } from './local-archguard-state.mjs';
+import { freezeContract, archguardContractGet } from './local-archguard-contract.mjs';
+import { sourcePaths, history, drift } from './local-archguard-snapshot.mjs';
+import { evaluateArchguardFiles, evaluateArchguardDrift } from './local-archguard-evaluate.mjs';
+
+async function scan(input) {
+  const ctx = await context(input);
+  return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), async () => {
+    await readLedger(ctx); const locked = await archguardContractGet(input); const files = [];
+    for (const relative of sourcePaths(input.paths)) {
+      const bytes = await readBytes(path.join(ctx.root, safePath(relative)), false, ctx);
+      files.push({ path: relative, content: bytes.content.toString('utf8') });
+    }
+    return { ...evaluateArchguardFiles(locked.contract, files), contractDigest: locked.contractDigest };
+  });
+}
+export async function archguardRulesScan(input) {
+  const result = await scan(input);
+  return { findings: result.findings, summary: { total: result.findings.length,
+    blocking: result.findings.filter(item => item.blocking).length }, contractDigest: result.contractDigest };
+}
+export async function archguardComplexityReport(input) {
+  const result = await scan(input);
+  return { metrics: result.metrics, findings: result.findings.filter(item => item.category === 'complexity'), contractDigest: result.contractDigest };
+}
+export async function archguardDriftStatus(input) {
+  const ctx = await context(input); const ledger = await readLedger(ctx);
+  return { ...await evaluateArchguardDrift(history(ledger)), ...drift(ledger), processLedgerDigest: ledger.headDigest };
+}
+export async function archguardLedgerQuery(input) {
+  const ctx = await context(input); const ledger = await readLedger(ctx);
+  const entries = ledger.entries.filter(entry => (!input.event || entry.event === input.event)
+    && (!input.status || entry.data.status === input.status)
+    && (!input.ruleId || entry.data.ledgerEntry?.ruleIds.includes(input.ruleId)));
+  return { schemaVersion: 'entrorove.archguard-ledger/1.0', entries, total: entries.length,
+    headDigest: ledger.headDigest, ledgerPath: ledger.ledgerPath, verifiedIntegrity: true };
+}
+export async function archguardLedgerInit(input) {
+  return withArchguardMutationFence(input, async () => {
+    const ctx = await context(input);
+    return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), async () => {
+    const ledger = await readLedger(ctx);
+    if (ledger.entries.length) return { initialized: false, alreadyManaged: true, total: ledger.entries.length, headDigest: ledger.headDigest };
+    const record = await appendLedger(ctx, 'ledger-init', { repositoryDigest: ctx.repositoryDigest, flowId: ctx.flowId });
+    return { initialized: true, alreadyManaged: false, total: 1, headDigest: record.digest };
+    });
+  });
+}
+export async function archguardHumanResume(input) {
+  return withArchguardMutationFence(input, async () => {
+    const ctx = await context(input);
+    return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), async () => {
+    const ledger = await readLedger(ctx);
+    const permit = await verifyAuthority(ctx, input.confirmation, 'entrorove.archguard-human-direction/1.0');
+    if (!drift(ledger).interrupted) fail('ARCH_RESUME_NOT_RED', 'human direction applies only to a red interrupted flow');
+    const value = permit.value;
+    if (value.action !== 'resume-correction' || value.ledgerHeadDigest !== ledger.headDigest
+      || !permit.authority.actors.includes(value.actor) || typeof value.reason !== 'string' || !value.reason.trim()) fail('ARCH_HUMAN_DIRECTION_INVALID', 'human direction must bind the exact red ledger head, actor, and reason');
+    if (ledger.entries.some(item => item.event === 'human-resume' && item.data.nonce === value.nonce)) fail('ARCH_HUMAN_DIRECTION_REPLAY', 'human direction was already consumed');
+    const locked = await freezeContract(ctx);
+    if (value.contractDigest !== locked.contractDigest) fail('ARCH_HUMAN_DIRECTION_BINDING', 'human direction must preserve the exact architecture contract digest');
+    const record = await appendLedger(ctx, 'human-resume', { nonce: value.nonce, actor: value.actor, reason: value.reason,
+      previousHeadDigest: ledger.headDigest, confirmationDigest: sha256(canonical(input.confirmation)) });
+    return { resumed: true, action: 'resume-correction', contractUnchanged: true, headDigest: record.digest };
+    });
+  });
+}

package/local-budget-git-attributes.mjs

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { canonical, relativePath, fail } from './local-budget-grants.mjs';
+import { readBudgetedProjectFile } from './local-budget-reads.mjs';
+import { gitReadBinding, readBudgetedGitBlob } from './local-budget-git.mjs';
+import { deriveBudgetGitAttributeSource } from './local-scope-git-attributes.mjs';
+const bindings = new WeakMap(), hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const control = side => `${side}/** -text -working-tree-encoding -filter -ident\n`;
+const invalid = () => fail('ENTROROVE_GIT_ATTRIBUTES_UNSUPPORTED', 'derived Git attributes require their fixed original source binding');
+function identity(input) { return canonical({ home: input.home, repositoryRoot: input.repositoryRoot, flowId: input.flowId }); }
+export async function sealBudgetedGitAttributes(input, sources) {
+  const binding = await gitReadBinding(input), segments = [], drivers = new Set(); let text = '';
+  if (!binding.input.flowId || !Array.isArray(sources)) invalid();
+  for (const source of sources) {
+    if (!source || !Buffer.isBuffer(source.content) || !source.evidence || !/^[0-9a-f]{64}$/.test(source.evidence.sha256)) invalid();
+    const relative = relativePath(source.evidence.path);
+    const directory = path.basename(relative) === '.gitattributes' ? path.dirname(relative).replace(/^\.$/, '') : '';
+    if (source.directory !== directory) invalid();
+    let actual;
+    if (source.evidence.sourceKind === 'index') {
+      actual = await readBudgetedGitBlob(binding.input, { path: relative, mode: source.evidence.mode, objectId: source.evidence.objectId,
+        sourceKind: 'index', commitId: null, role: 'git-blob', bytes: source.content.length });
+    } else actual = await readBudgetedProjectFile(binding.input, path.join(binding.root, relative), { sourcePath: relative });
+    if (hash(actual) !== source.evidence.sha256 || !actual.equals(source.content)) invalid();
+    const lines = deriveBudgetGitAttributeSource(actual, source.directory, drivers, source.evidence.sourceKind);
+    const derived = lines.length ? `${lines.join('\n')}\n` : '', start = Buffer.byteLength(text);
+    text += derived;
+    if (derived) segments.push(Object.freeze({ ...source.evidence, path: relative, start, end: Buffer.byteLength(text), role: 'git-process-derived' }));
+  }
+  const token = Object.freeze({ kind: 'fixed-git-attribute-binding', digest: hash(canonical({ binding: identity(binding.input), segments, text })) });
+  bindings.set(token, Object.freeze({ binding: identity(binding.input), text, segments: Object.freeze(segments) })); return token;
+}
+export async function boundGitAttributeSegments(input, options) {
+  const text = options.attributes;
+  if (text === '' && !options.attributeBinding) return [];
+  const trusted = bindings.get(options.attributeBinding);
+  if (!trusted) {
+    if ([control('before'), control('before') + control('after')].includes(text)) return [];
+    invalid();
+  }
+  const binding = await gitReadBinding(input);
+  if (trusted.binding !== identity(binding.input)
+    || ![trusted.text, trusted.text + control('before'), trusted.text + control('before') + control('after')].includes(text)) invalid();
+  return trusted.segments;
+}
+
+export function hasSealedBudgetGitAttributes(options) {
+  return bindings.has(options?.attributeBinding);
+}