@agilno-tech/rivet 0.1.0-alpha.0

package/src/feature/host-lock-recovery.js

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { join } from 'node:path';
+
+import { loadProjectConfig } from '../config/load.js';
+import { createFeaturePlan } from './plan-contract.js';
+import { createFeatureRuntimeState } from './runtime-bridge.js';
+import { immutableJson } from '../clients/contract.js';
+import { validateRuntimeSnapshot } from '../runtime/orchestrator.js';
+import { acquireLock, recoverAbandonedLock } from '../state/lock.js';
+import { resolveExistingFeatureRunPaths, resolveExistingStatePaths, verifyResolvedStatePaths } from '../state/paths.js';
+import { readSnapshotWithoutLock } from '../state/snapshot-store.js';
+import { createFeatureRunStore } from './run-store.js';
+
+function invalid() {
+  const error = new Error('Lock recovery requires valid saved host state or a finished spawned task awaiting local acceptance.');
+  error.code = 'ERR_HOST_RUN_RECOVERY_STATE';
+  error.safeMessage = error.message;
+  throw error;
+}
+
+/** Recover lock ownership only. Never construct a runtime or change a saved run. */
+export async function recoverHostRunLocks(project, runId) {
+  const paths = await resolveExistingFeatureRunPaths(project, runId);
+  if (paths === null) invalid();
+  const runtimePaths = await resolveExistingStatePaths(project, runId);
+  const config = await loadProjectConfig(project);
+  async function validate() {
+    await verifyResolvedStatePaths(paths);
+    const run = await createFeatureRunStore(paths).readOnly();
+    if (!run) invalid();
+    const spawned = run.featurePlan.client !== 'host';
+    if (spawned && !['awaiting-final-approval', 'completed'].includes(run.status)) invalid();
+    createFeaturePlan({ proposal: run.featurePlan, config, workRequest: run.workRequest, baselineCommit: run.featurePlan.baselineCommit, client: run.featurePlan.client });
+    let runtime = null;
+    let savedSnapshot = null;
+    if (runtimePaths !== null) {
+      await verifyResolvedStatePaths(runtimePaths);
+      savedSnapshot = await readSnapshotWithoutLock(runtimePaths);
+      if (savedSnapshot === null) {
+        if (run.status !== 'approved' || run.runtimeRefs.length !== 0) invalid();
+      } else {
+        runtime = validateRuntimeSnapshot(savedSnapshot.data, runId);
+        const expected = createFeatureRuntimeState({ config, run }).graph;
+        const fixedGraph = graph => ({ ...graph, status: undefined, nodes: graph.nodes.map(node => ({ ...node, status: undefined, evidenceRefs: undefined })) });
+        if (!isDeepStrictEqual(fixedGraph(runtime.graph), fixedGraph(expected))) invalid();
+      }
+    } else if (!['proposed', 'approved'].includes(run.status) || run.runtimeRefs.length !== 0) invalid();
+    // A finished spawned task may have crashed while holding this lock during
+    // local confirmation/application. Recover ownership only: this does not
+    // authorize a Git update, restart a Worker, or change acceptance evidence.
+    if (spawned && (!runtime
+      || runtime.graph.nodes.find(node => node.id === 'final-delivery')?.status !== 'ready'
+      || runtime.graph.nodes.some(node => node.owner.role === 'worker'
+        && !['completed', 'archived'].includes(node.status)))) invalid();
+    return { spawned, runVersion: run.version, runtimeVersion: runtime?.version ?? null,
+      fingerprint: createHash('sha256').update(JSON.stringify({ run, savedSnapshot })).digest('hex') };
+  }
+  const initial = await validate();
+  const recoveredLocks = [];
+  const held = [];
+  let blockedLock = 'host-operation';
+  let failure = false;
+  const lockPaths = [
+    ['host-operation', join(paths.runDir, 'host-operation.lock'), paths],
+    ['run', paths.lockPath, paths],
+    ...(runtimePaths ? [['runtime', runtimePaths.runtimeLockPath, runtimePaths], ['state', runtimePaths.lockPath, runtimePaths]] : []),
+  ];
+  try {
+    for (const [label, path, ownerPaths] of lockPaths) {
+      blockedLock = label;
+      await verifyResolvedStatePaths(ownerPaths);
+      const current = await validate();
+      if (current.fingerprint !== initial.fingerprint) invalid();
+      if (await recoverAbandonedLock(path)) recoveredLocks.push(label);
+      held.push({ label, lock: await acquireLock(path) });
+    }
+    if ((await validate()).fingerprint !== initial.fingerprint) invalid();
+  } catch {
+    failure = true;
+  } finally {
+    for (const { label, lock } of held.reverse()) {
+      try { await lock.release(); }
+      catch { if (!failure) blockedLock = label; failure = true; }
+    }
+  }
+  return immutableJson({
+    status: failure ? 'blocked' : 'recovered', runId, runVersion: initial.runVersion, runtimeVersion: initial.runtimeVersion, recoveredLocks,
+    ...(failure ? { blockedLock } : {}),
+    nextAction: failure
+      ? 'Recovery stopped safely. Inspect the remaining lock owner and private state before retrying; recovered locks are listed above.'
+      : initial.spawned
+        ? 'Read rivet task status, then rivet task approve to inspect local acceptance. Recovery did not resume workers, apply changes, or change task state.'
+        : 'Read task status and continue in the owning harness. Recovery did not resume workers or change task state.',
+  });
+}

package/src/feature/host-run-lock.js

@@ -0,0 +1,32 @@
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { acquireLock, LockBusyError, StaleLockError } from '../state/lock.js';
+import { assertResolvedStatePaths, verifyResolvedStatePaths } from '../state/paths.js';
+
+export class HostRunLockError extends Error {
+  constructor(stale = false) {
+    super(stale
+      ? 'Host run lock needs inspection after an interrupted operation; no lock was removed automatically.'
+      : 'Host run is busy. Read work status and retry with the current versions.');
+    this.name = 'HostRunLockError';
+    this.code = stale ? 'ERR_HOST_RUN_STALE_LOCK' : 'ERR_HOST_RUN_BUSY';
+    this.safeMessage = this.message;
+  }
+}
+
+export async function acquireHostRunLock(paths) {
+  assertResolvedStatePaths(paths);
+  if (paths.runDir !== paths.instanceDir) throw new TypeError('Host run paths are invalid');
+  const deadline = Date.now() + 2_000;
+  while (true) {
+    await verifyResolvedStatePaths(paths);
+    try { return await acquireLock(join(paths.runDir, 'host-operation.lock')); }
+    catch (error) {
+      if (error instanceof StaleLockError) throw new HostRunLockError(true);
+      if (!(error instanceof LockBusyError)) throw error;
+      if (Date.now() >= deadline) throw new HostRunLockError();
+      await delay(10);
+    }
+  }
+}

package/src/feature/local-approval.js

@@ -0,0 +1,183 @@
+import {createHash} from 'node:crypto';
+import {constants} from 'node:fs';
+import {lstat, open} from 'node:fs/promises';
+import {join, resolve} from 'node:path';
+import {immutableJson} from '../clients/contract.js';
+import {loadProjectConfig} from '../config/load.js';
+import {CONFIG_FILES, MAX_CONFIG_FILE_BYTES} from '../config/defaults.js';
+import {assertGitClient} from '../git/client.js';
+import {assertSelectedProtocolRefs} from '../protocols/project.js';
+import {resolveExistingFeatureRunPaths, verifyResolvedStatePaths} from '../state/paths.js';
+import {createHostExecution} from './host-execution.js';
+import {acquireHostRunLock} from './host-run-lock.js';
+import {createFeatureRunStore} from './run-store.js';
+import {createFeatureRuntimeState} from './runtime-bridge.js';
+
+export class LocalApprovalError extends Error {
+  constructor(reason = 'conflict') {
+    const messages = {
+      conflict: 'Local application requires unchanged verified evidence, configuration, and clean checkouts. Inspect task status before retrying.',
+      interrupted: 'A local application was interrupted. Work is preserved. Inspect the source branch and private approval record; no merge was retried.',
+      cancelled: 'Local application was cancelled before the Git update.',
+      invalid: 'Local approval input is invalid.',
+      configuration: 'Local application requires the four Rivet configuration files committed in the approved baseline and unchanged in both checkouts. Commit intended configuration changes, then create and verify a new reviewed task.',
+    };
+    super(messages[reason] ?? messages.conflict);
+    this.name = 'LocalApprovalError';
+    this.code = `ERR_LOCAL_APPROVAL_${reason.toUpperCase()}`;
+    this.safeMessage = this.message;
+  }
+}
+function fail(reason) { throw new LocalApprovalError(reason); }
+function hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function same(a,b) { return a.dev===b.dev && a.ino===b.ino; }
+const MAX_RECORD = 64 * 1024;
+async function readBounded(path, maximum, privateFile = false) {
+  let handle;
+  try {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink!==1 || before.size>maximum
+      || (privateFile && (before.mode & 0o777)!==0o600)) fail();
+    handle=await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const opened=await handle.stat();
+    if(!same(before,opened))fail();
+    const bytes=Buffer.alloc(maximum+1); let count=0;
+    while(count<bytes.length){const result=await handle.read(bytes,count,bytes.length-count,null);if(!result.bytesRead)break;count+=result.bytesRead;}
+    const after=await handle.stat();
+    if(count>maximum||!same(after,await lstat(path))||after.size!==opened.size||after.mtimeMs!==opened.mtimeMs)fail();
+    return bytes.subarray(0,count);
+  } finally {await handle?.close();}
+}
+async function record(paths,name) {
+  await verifyResolvedStatePaths(paths);
+  try {return JSON.parse((await readBounded(join(paths.runDir,name),MAX_RECORD,true)).toString('utf8'));}
+  catch(error){if(error.code==='ENOENT')return null;fail();}
+}
+// Create once, fsync both file and directory. An interrupted partial write is
+// intentionally an inspection boundary; neither a stale lock nor an intent is
+// permission to execute a second merge. Private state is a trusted local boundary.
+async function writeRecord(paths,name,value) {
+  await verifyResolvedStatePaths(paths);
+  const data=JSON.stringify(value);
+  if(Buffer.byteLength(data)>MAX_RECORD)fail();
+  const handle=await open(join(paths.runDir,name),constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600);
+  try{await handle.writeFile(data);await handle.sync();}finally{await handle.close();}
+  await verifyResolvedStatePaths(paths);
+  const directory=await open(paths.runDir,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);
+  try{await directory.sync();}finally{await directory.close();}
+}
+
+export async function applyVerifiedTask(input) {
+  let lock;
+  let selectedRunId;
+  try {
+    if(!input || typeof input!=='object' || Array.isArray(input) || ![Object.prototype,null].includes(Object.getPrototypeOf(input))
+      || Reflect.ownKeys(input).some(key=>typeof key!=='string'))fail('invalid');
+    const descriptors=Object.getOwnPropertyDescriptors(input);
+    if(Object.keys(descriptors).some(key=>!['project','runId','gitClient','confirm','signal'].includes(key)
+      || !Object.hasOwn(descriptors[key],'value')))fail('invalid');
+    const values=Object.fromEntries(Object.entries(descriptors).map(([key,descriptor])=>[key,descriptor.value]));
+    const {project,runId,gitClient,confirm,signal}=values;
+    if(typeof project!=='string'||resolve(project)!==project||typeof runId!=='string'
+      ||! /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(runId)||runId.length>64||typeof confirm!=='function')fail('invalid');
+    selectedRunId=runId;
+    assertGitClient(gitClient);
+    const cancelled=()=>{if(signal?.aborted)fail('cancelled');};
+    cancelled();
+    const paths=await resolveExistingFeatureRunPaths(project,runId);if(!paths)fail();
+    lock=await acquireHostRunLock(paths);
+    const store=createFeatureRunStore(paths);
+    const host=createHostExecution({gitClient});
+    async function observe() {
+      await verifyResolvedStatePaths(paths);
+      const status=await host.status({project,runId});
+      const {run,verification,checkout,runtime}=status;
+      const config=await loadProjectConfig(project);
+      createFeatureRuntimeState({config,run});
+      assertSelectedProtocolRefs(project,run.workRequest.contextRefs);
+      if(!verification||!checkout||!runtime||checkout.status!=='clean'||verification.status!=='pass')fail();
+      const source=await gitClient.inspectRepository(project);
+      if(source.root!==project||source.dirty||source.detached||source.branch!==config.project.repository.defaultBranch)fail();
+      // Require exact baseline configuration bytes, including files hidden from
+      // ordinary Git status with assume-unchanged. Policy-changing work needs a
+      // separate reviewed delivery flow, not reuse of this local approval.
+      const configHashes=[];
+      try {
+      for(const name of Object.values(CONFIG_FILES)){
+        const relative=`.rivet/${name}`;
+        const tracked=await gitClient.inspectTrackedFile(project,run.featurePlan.baselineCommit,relative);
+        const bytes=await readBounded(join(project,relative),MAX_CONFIG_FILE_BYTES);
+        const blob=createHash(tracked.blob.length===40?'sha1':'sha256').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+        if(blob!==tracked.blob)fail();
+        const integrationBytes=await readBounded(join(checkout.path,relative),MAX_CONFIG_FILE_BYTES);
+        if(!bytes.equals(integrationBytes))fail();
+        configHashes.push(blob);
+      }
+      } catch { fail('configuration'); }
+      const changed=await gitClient.changedPaths(project,run.featurePlan.baselineCommit,verification.commitSha);
+      const selectedPaths=new Set(run.workRequest.contextRefs.filter(ref=>ref.startsWith('protocol:'))
+        .map(ref=>`.rivet/protocols/${ref.split(':')[1]}.md`));
+      if(changed.some(path=>selectedPaths.has(path)))fail();
+      if(changed.length!==verification.changedPathCount||hash(changed)!==hash(verification.changedPaths))fail();
+      const evidenceDigest=hash({configHashes,config,proposalDigest:run.proposalDigest,activation:run.activation,
+        workRequest:run.workRequest,featurePlan:run.featurePlan,verification,runtime,checkout});
+      return {status,source,evidenceDigest};
+    }
+    let current=await observe();
+    const intent=await record(paths,'local-approval-intent.json');
+    let receipt=await record(paths,'local-approval-receipt.json');
+    const {run}=current.status;
+    const preview=immutableJson({runId,targetBranch:current.source.branch,baselineCommit:run.featurePlan.baselineCommit,
+      commitSha:current.status.verification.commitSha,integrationPath:current.status.checkout.path,
+      changedPaths:current.status.verification.changedPaths,
+      checks:current.status.verification.checks.map(({id,status,required,exitCode})=>({id,status,required,exitCode}))});
+    const binding={schemaVersion:1,kind:'local-acceptance',runId,runVersion:run.status==='completed'?run.version-1:run.version,
+      evidenceDigest:current.evidenceDigest,source:{root:current.source.root,rootIdentity:current.source.rootIdentity,
+        gitCommonDir:current.source.gitCommonDir,repositoryId:current.source.repositoryId},preview};
+    const identity=hash(binding);
+    const reference=`local-acceptance:${identity}`;
+    if(intent!==null){
+      if(hash(intent)!==hash({...binding,digest:identity}))fail();
+      if(current.source.headSha!==preview.commitSha)fail('interrupted');
+      if(receipt!==null&&hash(receipt)!==hash({schemaVersion:1,kind:'local-acceptance',intentDigest:identity,commitSha:preview.commitSha}))fail();
+      if(run.status==='completed'){
+        if(receipt===null||!run.evidenceRefs.includes(reference))fail();
+        return immutableJson({status:'completed',commitSha:preview.commitSha,nextAction:'Verified changes are in your local default branch. No push or deployment was performed.'});
+      }
+      if(!current.status.deliveryReady)fail();
+      // Exact durable intent plus the already-observed target permits receipt-only
+      // reconciliation. It never authorizes another Git mutation.
+    }else{
+      if(receipt!==null||run.status!=='awaiting-final-approval'||!current.status.deliveryReady
+        ||current.source.headSha!==preview.baselineCommit)fail();
+      if(await confirm(preview)!==true)return Object.freeze({status:'declined'});
+      cancelled();
+      const fresh=await observe();
+      if(fresh.status.run.version!==run.version||fresh.evidenceDigest!==current.evidenceDigest
+        ||hash(fresh.source)!==hash(current.source)||!fresh.status.deliveryReady)fail();
+      await writeRecord(paths,'local-approval-intent.json',{...binding,digest:identity});
+      cancelled();
+      await gitClient.fastForward(project,{branch:preview.targetBranch,expectedTip:preview.baselineCommit,newTip:preview.commitSha});
+      current=await observe();
+      if(current.evidenceDigest!==binding.evidenceDigest||current.status.run.version!==run.version
+        ||current.source.headSha!==preview.commitSha||!current.status.deliveryReady)fail('interrupted');
+    }
+    if(receipt===null){
+      receipt={schemaVersion:1,kind:'local-acceptance',intentDigest:identity,commitSha:preview.commitSha};
+      await writeRecord(paths,'local-approval-receipt.json',receipt);
+    }
+    await store.update({status:'completed',updatedAt:new Date(Math.max(Date.now(),Date.parse(run.updatedAt))).toISOString(),
+      runtimeRefs:run.runtimeRefs,evidenceRefs:[...run.evidenceRefs,reference]}, {expectedVersion:run.version});
+    return immutableJson({status:'completed',commitSha:preview.commitSha,nextAction:'Verified changes are in your local default branch. No push or deployment was performed.'});
+  }catch(error){
+    if(error instanceof LocalApprovalError)throw error;
+    if(error?.code==='ERR_HOST_RUN_STALE_LOCK' && selectedRunId){
+      const recovery=new LocalApprovalError('interrupted');
+      recovery.message=`A prior local operation was interrupted. From this project, run rivet task recover --run=${selectedRunId}, then inspect task status before approving. No lock was removed automatically.`;
+      recovery.safeMessage=recovery.message;
+      throw recovery;
+    }
+    throw new LocalApprovalError();
+  }
+  finally{await lock?.release();}
+}

package/src/feature/plan-contract.js

@@ -0,0 +1,215 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+import Ajv from 'ajv';
+
+import { immutableJson } from '../clients/contract.js';
+import { validateProjectConfiguration } from '../config/validate.js';
+import { validateWorkRequest } from '../work-request/contract.js';
+import { matchesClientProfile, matchesWorkerExecution } from './client-profile.js';
+
+const schema = JSON.parse(readFileSync(new URL('../../schemas/feature-plan.schema.json', import.meta.url), 'utf8'));
+const validateSchema = new Ajv({ allErrors: true, strict: true }).compile(schema);
+const plans = new WeakSet();
+const GIT_OBJECT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const CLIENTS = new Set(['claude', 'codex', 'host']);
+const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+
+const VIOLATIONS = Object.freeze({
+  'owned-path-invalid': 'An owned path contains a reserved or non-normalized component.',
+  'owned-path-protected': 'An owned path targets repository metadata or a protected project path.',
+  'owned-path-duplicate': 'A work item contains owned paths that collide after case normalization.',
+  'plan-schema-invalid': 'The compiled plan does not match the governed plan schema.',
+  'plan-policy-invalid': 'The compiled plan violates the configured governance policy.',
+});
+
+export class FeaturePlanError extends Error {
+  constructor(reason = 'invalid-plan', violation) {
+    const messages = {
+      'invalid-plan': 'Feature plan is invalid.',
+      'decomposition-invalid': 'Planning provider returned an invalid feature decomposition.',
+      'compiled-plan-invalid': 'Feature decomposition could not be compiled into a valid governed plan.',
+    };
+    const detail = Object.hasOwn(VIOLATIONS, violation) ? violation : undefined;
+    super(`${messages[reason] ?? messages['invalid-plan']}${detail ? ` ${VIOLATIONS[detail]}` : ''}`);
+    this.name = 'FeaturePlanError';
+    this.code = 'ERR_INVALID_FEATURE_PLAN';
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason, ...(detail ? { violation: detail } : {}) });
+  }
+}
+
+function fail(violation = 'plan-policy-invalid') { throw new FeaturePlanError('invalid-plan', violation); }
+
+function canonical(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+}
+
+function safeSnapshot(value) {
+  try { return immutableJson(value); } catch { fail(); }
+}
+
+function validateBindings(bindings) {
+  try {
+    if (!bindings || typeof bindings !== 'object' || Array.isArray(bindings)) fail();
+    const keys = Reflect.ownKeys(bindings);
+    if (keys.length !== 5 || keys.some(key => typeof key !== 'string'
+      || !['proposal', 'config', 'workRequest', 'baselineCommit', 'client'].includes(key))) fail();
+    validateProjectConfiguration(bindings.config);
+    validateWorkRequest(bindings.workRequest);
+    if (typeof bindings.baselineCommit !== 'string' || !GIT_OBJECT.test(bindings.baselineCommit)
+      || !CLIENTS.has(bindings.client)) fail();
+    return bindings;
+  } catch (error) {
+    if (error instanceof FeaturePlanError) throw error;
+    fail();
+  }
+}
+
+function safeOwnedPath(path, sensitivePaths) {
+  const parts = path.replaceAll('\\', '/').split('/');
+  if (parts.some(part => !part || part === '.' || part === '..' || part.endsWith('.') || part.endsWith(' ')
+    || WINDOWS_RESERVED.test(part))) fail('owned-path-invalid');
+  const folded = parts.map(part => part.toLowerCase()).join('/');
+  if (folded === '.git' || folded.startsWith('.git/') || folded === '.rivet' || folded.startsWith('.rivet/')
+    || folded === '.rivet.cjs' || folded.startsWith('.rivet.cjs/')) fail('owned-path-protected');
+  for (const pattern of sensitivePaths) {
+    const prefix = pattern.replaceAll('\\', '/').split('*', 1)[0].replace(/\/$/, '').toLowerCase();
+    if (folded === prefix || folded.startsWith(`${prefix}/`)) fail('owned-path-protected');
+  }
+  return folded;
+}
+
+function pathOverlap(left, right) {
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function visit(id, nodeMap, visiting, visited) {
+  if (visited.has(id)) return;
+  if (visiting.has(id)) fail();
+  visiting.add(id);
+  const node = nodeMap.get(id);
+  for (const dependency of node.dependencies) visit(dependency, nodeMap, visiting, visited);
+  visiting.delete(id);
+  visited.add(id);
+}
+
+function dependsOn(node, targetId, nodeMap) {
+  const pending = [...node.dependencies];
+  const seen = new Set();
+  while (pending.length > 0) {
+    const id = pending.pop();
+    if (id === targetId) return true;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    pending.push(...nodeMap.get(id).dependencies);
+  }
+  return false;
+}
+
+function validatePlanSemantics(plan, { config, workRequest, baselineCommit, client }) {
+  if (plan.baselineCommit !== baselineCommit || plan.workRequestDigest !== workRequest.digest || plan.client !== client
+    || !matchesClientProfile(client, plan.clientProfile)) fail();
+  if (client === 'host' && config.orchestration.roles.some(role => role.harness !== undefined)) fail();
+  const configuredProviders = new Set(config.providers.providers.map(provider => provider.id));
+  if (plan.providerRefs.some(provider => !configuredProviders.has(provider))) fail();
+  const roles = new Map(config.orchestration.roles.map(role => [role.id, role]));
+  const profiles = new Map(config.orchestration.completionProfiles.map(profile => [profile.id, profile]));
+  const commands = new Set(Object.keys(config.project.commands));
+  const qualityEvidence = new Set(config.quality.evidence.requiredTypes);
+  const nodeMap = new Map();
+  for (const node of plan.nodes) {
+    if (nodeMap.has(node.id)) fail();
+    nodeMap.set(node.id, node);
+  }
+  const roots = plan.nodes.filter(node => node.parentId === undefined);
+  const activation = plan.nodes.filter(node => node.approvalGate === 'activation');
+  const final = plan.nodes.filter(node => node.approvalGate === 'final-delivery');
+  if (roots.length !== 1 || activation.length !== 1 || final.length !== 1 || roots[0] !== activation[0]
+    || activation[0].role !== 'boss' || final[0].role !== 'boss' || final[0].parentId !== activation[0].id) fail();
+  if (!['boss', 'manager', 'worker'].every(kind => plan.nodes.some(node => node.role === kind))) fail();
+
+  const criteria = new Set(workRequest.acceptanceCriteria);
+  const covered = new Set();
+  const pathSets = new Map();
+  for (const node of plan.nodes) {
+    const role = roles.get(node.roleId);
+    if (!role || role.kind !== node.role || node.dependencies.includes(node.id)) fail();
+    if (!matchesWorkerExecution(role, node.execution)) fail();
+    if (node !== roots[0] && (node.dependencies.length === 0 || !node.parentId)) fail();
+    if (node.parentId && !nodeMap.has(node.parentId)) fail();
+    if (node.dependencies.some(id => !nodeMap.has(id))) fail();
+    if (node.authorityScopes.some(scope => !role.authorityScopes.includes(scope))) fail();
+    if (node.commandIds.some(command => !commands.has(command))) fail();
+    for (const name of ['timeMinutes', 'tokenLimit', 'costUsd', 'taskLimit']) {
+      if (node.budget[name] > role.budget[name]) fail();
+    }
+    const profile = profiles.get(role.completionProfile);
+    if (!profile || profile.requiredEvidence.some(type => !node.requiredEvidenceTypes.includes(type))
+      || node.requiredEvidenceTypes.some(type => !qualityEvidence.has(type))) fail();
+    if (node.approvalGate && !config.orchestration.approvalGates.includes(node.approvalGate)) fail();
+    if ((node.approvalGate === 'activation' || node.approvalGate === 'final-delivery')
+      && !node.requiredEvidenceTypes.includes('human-approval')) fail();
+    if (node.authorityScopes.includes('external-write') && !role.permissions.externalWrites) fail();
+    if (node.authorityScopes.includes('merge') && !role.permissions.merge) fail();
+    if (node.authorityScopes.includes('deploy') && !role.permissions.deploy) fail();
+    if (node.role === 'worker' && node.ownedPaths.length === 0) fail();
+    if (node.role !== 'worker' && node.ownedPaths.length > 0) fail();
+    const foldedPaths = node.ownedPaths.map(path => safeOwnedPath(path, config.project.repository.sensitivePaths ?? []));
+    if (new Set(foldedPaths).size !== foldedPaths.length) fail('owned-path-duplicate');
+    pathSets.set(node.id, foldedPaths);
+    for (const criterion of node.acceptanceCriteria) {
+      if (!criteria.has(criterion)) fail();
+      if (node.role === 'worker') covered.add(criterion);
+    }
+    if (node.role === 'worker' && node.acceptanceCriteria.length === 0) fail();
+  }
+  if (covered.size !== criteria.size) fail();
+
+  for (const node of plan.nodes) {
+    if (!node.parentId) continue;
+    const parent = nodeMap.get(node.parentId);
+    const parentRole = roles.get(parent.roleId);
+    const finalBoss = node === final[0] && parent === activation[0];
+    if (!finalBoss && (!parentRole.canDelegate || !parentRole.delegatesTo.includes(node.role))) fail();
+    if (node.authorityScopes.some(scope => !parent.authorityScopes.includes(scope))) fail();
+    for (const name of ['timeMinutes', 'tokenLimit', 'costUsd', 'taskLimit']) {
+      if (node.budget[name] > parent.budget[name]) fail();
+    }
+  }
+  const visited = new Set();
+  for (const node of plan.nodes) visit(node.id, nodeMap, new Set(), visited);
+
+  const workers = plan.nodes.filter(node => node.role === 'worker');
+  for (let leftIndex = 0; leftIndex < workers.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < workers.length; rightIndex += 1) {
+      const left = workers[leftIndex];
+      const right = workers[rightIndex];
+      if (dependsOn(left, right.id, nodeMap) || dependsOn(right, left.id, nodeMap)) continue;
+      if (pathSets.get(left.id).some(a => pathSets.get(right.id).some(b => pathOverlap(a, b)))) fail();
+    }
+  }
+  const requiredCommands = config.quality.commandGates.filter(gate => gate.required).map(gate => gate.command);
+  if (requiredCommands.some(command => !final[0].commandIds.includes(command))) fail();
+}
+
+export function createFeaturePlan(bindingsInput) {
+  const bindings = validateBindings(bindingsInput);
+  const proposal = safeSnapshot(bindings.proposal);
+  if (!validateSchema(proposal)) fail('plan-schema-invalid');
+  validatePlanSemantics(proposal, bindings);
+  plans.add(proposal);
+  return proposal;
+}
+
+export function validateFeaturePlan(value) {
+  if (!plans.has(value)) fail();
+  return value;
+}
+
+export function featurePlanDigest(value) {
+  validateFeaturePlan(value);
+  return createHash('sha256').update(canonical(value)).digest('hex');
+}