chati-dev 4.5.16 → 4.5.27

package/src/orchestrator/release-runtime.js

@@ -1,14 +1,73 @@
-import { ReleaseLane } from '@chati/release-lane';
-import { resolveRailCompletionReference } from './rail-runtime.js';
+import { join } from 'node:path';
+import {
+  ReleaseLane, ReleaseStateAuthority, ReleaseTransport,
+  SignedHumanAuthorizationVerifier, SignedSmokeEvidenceVerifier,
+} from '@chati/release-lane';
+import { loadRailHandoff, resolveRailCompletionReference } from './rail-runtime.js';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import {
+  signHostAuthorityPayload, verifyHostAuthorityPayload,
+} from '../installer-v2/installation-authority.js';
+
+const RELEASE_STATE_AUTHORITY_DOMAIN = 'chati-release-state-v1';
+
+export {
+  signedHumanAuthorizationPayload,
+  signedSmokeEvidencePayload,
+} from '@chati/release-lane';
 
 /**
- * G3 local release authority. The returned ReleaseLane accepts only its own
- * FakeReleaseTransport capability and resolves completion evidence from the
- * project-local RAIL journal. It has no external deployment adapter.
+ * Project release authority. Completion evidence is resolved from the local
+ * RAIL journal. External I/O remains behind an explicitly injected minted
+ * transport and cannot run before scoped human authorization and smoke proof.
  */
-export function createProjectReleaseLane({ projectDir, handoff_id, clock = () => new Date() } = {}) {
+export function createProjectReleaseLane({
+  projectDir, handoff_id, authorization_issuer_id, authorization_public_key,
+  smoke_issuer_id, smoke_public_key,
+  clock = () => new Date(),
+} = {}) {
+  if (typeof handoff_id !== 'string' || !/^[A-Za-z0-9._-]+$/.test(handoff_id)) {
+    throw new Error('handoff_id must be safe for the project-local release journal');
+  }
+  const artifact = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!artifact) throw new Error('release lane requires an authorized v2 installation');
+  const { handoff } = loadRailHandoff({ projectDir, handoff_id, clock });
+  if (handoff.project_id !== artifact.project_id) {
+    throw new Error('release lane handoff does not belong to the authorized installed project');
+  }
   return new ReleaseLane({
     clock,
     verify_completion: (immutable_ref) => resolveRailCompletionReference({ projectDir, handoff_id, immutable_ref, clock }),
+    authorization_verifier: new SignedHumanAuthorizationVerifier({
+      issuer_id: authorization_issuer_id,
+      public_key: authorization_public_key,
+    }),
+    smoke_verifier: new SignedSmokeEvidenceVerifier({
+      issuer_id: smoke_issuer_id,
+      public_key: smoke_public_key,
+    }),
+    state_authority: new ReleaseStateAuthority({
+      sign: (material) => {
+        const signed = signHostAuthorityPayload(material, { domain: RELEASE_STATE_AUTHORITY_DOMAIN });
+        return { authority_id: signed.authority_id, authority_signature: signed.signature };
+      },
+      verify: (material, receipt) => verifyHostAuthorityPayload(material, {
+        domain: RELEASE_STATE_AUTHORITY_DOMAIN,
+        authorityId: receipt?.authority_id,
+        signature: receipt?.authority_signature,
+      }),
+    }),
+    require_authenticated_state: true,
+    authority_context: {
+      project_id: artifact.project_id,
+      handoff_id,
+    },
+    require_authority_context: true,
+    require_production_transport: true,
+    state_path: join(projectDir, '.chati', 'release-lane', `${handoff_id}.jsonl`),
   });
 }
+
+export function createProjectReleaseTransport({ transport_id, authority_id, public_key, release, rollback, lookup } = {}) {
+  return new ReleaseTransport({ transport_id, authority_id, public_key, release, rollback, lookup });
+}

package/src/orchestrator/review-runtime.js

@@ -1,24 +1,96 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { acceptReview, decideReviewProgress } from '@chati/review-council';
+import { sha256 } from '@chati/core';
 import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
-import { createProjectRailEngine, loadRailHandoff } from './rail-runtime.js';
+import {
+  createProjectRailEngine, loadLatestRailExecutionEvidence, loadRailHandoff, resolveRailAttemptContext,
+} from './rail-runtime.js';
+import { verifyTerminalAuthorityReceipt } from '../terminal/spawner.js';
+import { buildRailReviewPrompt } from '../terminal/rail-prompts.js';
+import { assertRailReadOnlyCommitWorkspaceUnchanged } from '../terminal/rail-readonly-workspace.js';
 
 function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
-function safeId(value, label) {
-  if (typeof value !== 'string' || !/^[A-Za-z0-9._-]+$/.test(value)) fail('INVALID_REVIEW_STORAGE_ID', `${label} must contain only letters, digits, dot, underscore or hyphen`);
-  return value;
+
+function trustedGitEnvironment(source = process.env) {
+  const environment = Object.fromEntries(Object.entries(source).filter(([key]) => !key.startsWith('GIT_')));
+  return {
+    ...environment,
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
+    GIT_TERMINAL_PROMPT: '0',
+  };
+}
+
+function parseAuthorizedReviewPayload(text) {
+  if (typeof text !== 'string') fail('RAIL_REVIEW_OUTPUT_INVALID', 'review output must be a string');
+  const startToken = '<CHATI_RAIL_REVIEW>';
+  const endToken = '</CHATI_RAIL_REVIEW>';
+  const starts = text.split(startToken).length - 1;
+  const ends = text.split(endToken).length - 1;
+  if (starts !== 1 || ends !== 1) fail('RAIL_REVIEW_OUTPUT_INVALID', 'reviewer must return exactly one CHATI_RAIL_REVIEW envelope');
+  const start = text.indexOf(startToken);
+  const end = text.indexOf(endToken, start + startToken.length);
+  try { return JSON.parse(text.slice(start + startToken.length, end).trim()); }
+  catch (error) { return fail('RAIL_REVIEW_OUTPUT_INVALID', `reviewer returned invalid JSON: ${error.message}`); }
 }
-function reviewDir(projectDir, attemptId) { return join(projectDir, '.chati/v2/rail/reviews', safeId(attemptId, 'attempt_id')); }
-function reviewPath(projectDir, attemptId, reviewId) { return join(reviewDir(projectDir, attemptId), `${safeId(reviewId, 'review_id')}.json`); }
 
-function readReviewEvidence(projectDir, attemptId) {
-  const directory = reviewDir(projectDir, attemptId);
-  if (!existsSync(directory)) return [];
-  return readdirSync(directory).filter((name) => name.endsWith('.json')).sort().map((name) => {
-    try { return JSON.parse(readFileSync(join(directory, name), 'utf8')); }
-    catch { return fail('INVALID_STORED_REVIEW', `review evidence cannot be read: ${name}`); }
+export function recordRailReviewDispatch({
+  projectDir, attempt_id, invocation, launch_receipt, prompt, reviewWorkspace, clock,
+} = {}) {
+  const lineage = resolveAttemptLineage(projectDir, attempt_id, clock);
+  const context = resolveRailAttemptContext({ projectDir, handoff_id: lineage.handoff_id, attempt_id, clock });
+  const engine = createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) });
+  const reviewSubject = resolveReviewGitSubject({ projectDir, attempt_id, clock });
+  if (!reviewWorkspace
+    || reviewWorkspace.canonical_project_dir !== realpathSync(resolve(projectDir))
+    || reviewWorkspace.base_commit_ref !== reviewSubject.base_commit_ref
+    || reviewWorkspace.result_commit_ref !== reviewSubject.result_commit_ref) {
+    fail('RAIL_REVIEW_WORKSPACE_MISMATCH', 'review dispatch requires an immutable workspace for the exact result commit');
+  }
+  const workspaceState = assertRailReadOnlyCommitWorkspaceUnchanged({
+    workspace: reviewWorkspace,
+    label: 'RAIL review dispatch',
+  });
+  const canonicalSubject = {
+    ...reviewSubject,
+    workspace_digest: sha256(workspaceState),
+  };
+  const round = engine.reviewEvidenceForAttempt(attempt_id).length + 1;
+  const canonicalPrompt = buildRailReviewPrompt({
+    projectDir: reviewWorkspace.subject_dir,
+    context,
+    invocation,
+    reviewSubject: canonicalSubject,
+    round,
   });
+  if (prompt !== canonicalPrompt || invocation?.prompt_digest !== sha256(canonicalPrompt)) {
+    fail('NONCANONICAL_REVIEW_PROMPT', 'review dispatch must use the exact canonical prompt for this attempt and round');
+  }
+  if (!verifyTerminalAuthorityReceipt(launch_receipt, {
+    purpose: 'terminal_launch', authority_kind: 'rail_review',
+    invocation_id: invocation?.invocation_id, launch_nonce: invocation?.launch_nonce,
+    provider_id: invocation?.provider_id, harness_id: invocation?.harness_id,
+    model_id: invocation?.model_pin?.model_id,
+    reasoning_configuration: invocation?.model_pin?.reasoning_configuration,
+    task_id: context.task.task_id,
+    working_dir: resolve(reviewWorkspace.subject_dir),
+    prompt_digest: invocation.prompt_digest,
+  })) fail('UNTRUSTED_REVIEW_LAUNCH', 'review dispatch requires a terminal-authority launch receipt');
+  const artifact = loadRuntimeInstallationV2(projectDir, { ...(clock === undefined ? {} : { clock }) });
+  if (!artifact) fail('V2_INSTALLATION_REQUIRED', 'RAIL review dispatch requires a v2 installation');
+  return engine.recordReviewDispatch({
+      attempt_id, invocation, launch_receipt,
+      installation: artifact.installation, snapshot: artifact.capability_snapshot,
+      project_dir: projectDir,
+      working_dir: reviewWorkspace.subject_dir,
+    });
+}
+
+export function listRailReviewEvidence({ projectDir, attempt_id, clock } = {}) {
+  return createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) })
+    .reviewEvidenceForAttempt(attempt_id);
 }
 
 function resolveAttemptLineage(projectDir, attemptId, clock) {
@@ -32,43 +104,116 @@ function resolveAttemptLineage(projectDir, attemptId, clock) {
     handoff_id: handoff.handoff_id,
     handoff_manifest_digest: handoff.seal.manifest_digest,
     task_id: attempt.task_id,
+    base_commit_ref: attempt.git_commit_ref,
+  });
+}
+
+export function resolveReviewGitSubject({ projectDir, attempt_id, clock } = {}) {
+  const lineage = resolveAttemptLineage(projectDir, attempt_id, clock);
+  const evidence = loadLatestRailExecutionEvidence({ projectDir, attempt_id, clock });
+  const engine = createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) });
+  const latestControl = engine.records.filter((record) => ['review_decided', 'adjudication_decided'].includes(record.type)
+    && record.payload?.attempt_id === attempt_id).at(-1);
+  const requiredReworkSource = latestControl?.type === 'review_decided'
+    && latestControl.payload.decision?.decision === 'normal-rework'
+    ? latestControl.payload.review_ref
+    : latestControl?.type === 'adjudication_decided'
+      && latestControl.payload.decision?.outcome === 'bounded-correction'
+      ? latestControl.payload.adjudication_ref
+      : null;
+  if (requiredReworkSource && evidence.source_decision_ref !== requiredReworkSource) {
+    fail('RAIL_REWORK_RESULT_REQUIRED', 'latest canonical rework decision has no successful execution result');
+  }
+  if (evidence.attempt_id !== attempt_id || evidence.handoff_id !== lineage.handoff_id || evidence.task_id !== lineage.task_id) {
+    fail('REVIEW_EXECUTION_EVIDENCE_MISMATCH', 'review execution evidence is not bound to the claimed handoff, task and attempt');
+  }
+  const result_commit_ref = evidence.result_commit_ref;
+  if (typeof result_commit_ref !== 'string' || !/^[a-f0-9]{40,64}$/.test(result_commit_ref)) {
+    fail('REVIEW_RESULT_COMMIT_REQUIRED', 'review requires a result commit captured by immutable execution evidence');
+  }
+  try {
+    execFileSync('git', ['-C', projectDir, 'cat-file', '-e', `${result_commit_ref}^{commit}`], {
+      stdio: 'ignore', env: trustedGitEnvironment(),
+    });
+  } catch {
+    return fail('REVIEW_GIT_SUBJECT_UNAVAILABLE', 'the execution evidence result commit is unavailable in local Git');
+  }
+  if (result_commit_ref === lineage.base_commit_ref) {
+    fail('REVIEW_RESULT_COMMIT_REQUIRED', 'review requires a result commit distinct from the sealed base commit');
+  }
+  const ancestry = spawnSync('git', ['-C', projectDir, 'merge-base', '--is-ancestor', lineage.base_commit_ref, result_commit_ref], {
+    env: trustedGitEnvironment(),
   });
+  if (ancestry.status !== 0) fail('REVIEW_RESULT_NOT_DESCENDANT', 'review result commit must descend from the sealed base commit');
+  return Object.freeze({ ...lineage, result_commit_ref, execution_evidence_ref: evidence.evidence_id });
 }
 
-/** Stores a selected-only review record and derives the next rework decision. */
-export function recordRailReview({ projectDir, review, invocation, clock = () => new Date() } = {}) {
+/** Appends selected-only review evidence to the canonical RAIL journal. */
+export function recordRailReview({
+  projectDir, review, review_output, terminal_authority_receipt,
+  invocation, result_commit_ref, clock = () => new Date(),
+} = {}) {
+  const payload = parseAuthorizedReviewPayload(review_output);
+  const outputReview = {
+    findings: payload.findings ?? [], verdict: payload.verdict,
+    impasse: payload.impasse ?? { kind: 'none' },
+    ...(payload.authority_reason ? { authority_reason: payload.authority_reason } : {}),
+    ...(payload.authority_reason_ref ? { authority_reason_ref: payload.authority_reason_ref } : {}),
+  };
+  const suppliedReview = {
+    findings: review?.findings ?? [], verdict: review?.verdict,
+    impasse: review?.impasse ?? { kind: 'none' },
+    ...(review?.authority_reason ? { authority_reason: review.authority_reason } : {}),
+    ...(review?.authority_reason_ref ? { authority_reason_ref: review.authority_reason_ref } : {}),
+  };
+  if (sha256(outputReview) !== sha256(suppliedReview)) {
+    fail('RAIL_REVIEW_PAYLOAD_MISMATCH', 'review material is not the payload returned by the authorized reviewer process');
+  }
+  if (!verifyTerminalAuthorityReceipt(terminal_authority_receipt, {
+    purpose: 'terminal_completion', authority_kind: 'rail_review',
+    invocation_id: invocation?.invocation_id, launch_nonce: invocation?.launch_nonce,
+    provider_id: invocation?.provider_id, harness_id: invocation?.harness_id,
+    model_id: invocation?.model_pin?.model_id,
+    reasoning_configuration: invocation?.model_pin?.reasoning_configuration,
+    exit_status: 0,
+  }) || terminal_authority_receipt.stdout_digest !== sha256(review_output)) {
+    fail('UNTRUSTED_REVIEW_EVIDENCE', 'review requires output bound to a successful terminal authority receipt');
+  }
   const artifact = loadRuntimeInstallationV2(projectDir, { clock });
   if (!artifact) fail('V2_INSTALLATION_REQUIRED', 'RAIL review requires a v2 installation');
   const validated = acceptReview({ review, invocation, installation: artifact.installation, snapshot: artifact.capability_snapshot, clock });
-  const lineage = resolveAttemptLineage(projectDir, validated.attempt_id, clock);
-  const path = reviewPath(projectDir, validated.attempt_id, validated.review_id);
-  const content = `${JSON.stringify({ review: validated, invocation, lineage }, null, 2)}\n`;
-  const stored = readReviewEvidence(projectDir, validated.attempt_id);
-  const matching = stored.find((entry) => entry.review?.review_id === validated.review_id);
-  if (matching && readFileSync(path, 'utf8') !== content) fail('REVIEW_STORAGE_CONFLICT', `review ${validated.review_id} already exists with different material`);
-  const prior = stored.filter((entry) => entry.review?.review_id !== validated.review_id);
+  const baseLineage = resolveAttemptLineage(projectDir, validated.attempt_id, clock);
+  const engine = createProjectRailEngine({ projectDir, clock });
+  const review_ref = `rail-review://${baseLineage.handoff_id}/${validated.attempt_id}/${validated.review_id}`;
+  const existingJournal = engine.records.find((record) => record.type === 'review_decided' && record.payload?.review_ref === review_ref);
+  if (existingJournal) {
+    if (result_commit_ref !== undefined && result_commit_ref !== existingJournal.payload.result_commit_ref) {
+      fail('REVIEW_GIT_SUBJECT_CHANGED', 'Git subject differs from the immutable canonical review');
+    }
+    const lineage = Object.freeze({ ...baseLineage, result_commit_ref: existingJournal.payload.result_commit_ref });
+    const journal = engine.recordReviewDecision({
+      attempt_id: validated.attempt_id, review_ref, decision: existingJournal.payload.decision, review: validated, invocation,
+      terminal_authority_receipt,
+      installation: artifact.installation, snapshot: artifact.capability_snapshot,
+      git_dir: projectDir, result_commit_ref: existingJournal.payload.result_commit_ref,
+    });
+    return Object.freeze({ review_ref, lineage, review: validated, decision: existingJournal.payload.decision, journal, written: false });
+  }
+  const resolvedSubject = resolveReviewGitSubject({ projectDir, attempt_id: validated.attempt_id, clock });
+  if (result_commit_ref !== undefined && result_commit_ref !== resolvedSubject.result_commit_ref) {
+    fail('REVIEW_GIT_SUBJECT_CHANGED', 'Git HEAD changed after the review subject was captured');
+  }
+  const lineage = resolvedSubject;
+  const prior = engine.reviewEvidenceForAttempt(validated.attempt_id);
   const decision = decideReviewProgress({
     prior_review_evidence: prior, current_review: validated, reviewer_invocation: invocation,
     installation: artifact.installation, snapshot: artifact.capability_snapshot, clock,
   });
-  const review_ref = `rail-review://${lineage.handoff_id}/${validated.attempt_id}/${validated.review_id}`;
-  let written = false;
-  if (!matching) {
-    mkdirSync(reviewDir(projectDir, validated.attempt_id), { recursive: true, mode: 0o700 });
-    const temporary = `${path}.${process.pid}.tmp`;
-    writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
-    try {
-      linkSync(temporary, path);
-      written = true;
-    } catch (error) {
-      if (error?.code !== 'EEXIST' || readFileSync(path, 'utf8') !== content) fail('REVIEW_STORAGE_CONFLICT', `review ${validated.review_id} raced with different material`);
-    } finally {
-      if (existsSync(temporary)) unlinkSync(temporary);
-    }
-  }
-  const journal = createProjectRailEngine({ projectDir, clock }).recordReviewDecision({
+  const journal = engine.recordReviewDecision({
     attempt_id: validated.attempt_id, review_ref, decision, review: validated, invocation,
-    prior_review_evidence: prior, installation: artifact.installation, snapshot: artifact.capability_snapshot,
+    terminal_authority_receipt,
+    installation: artifact.installation, snapshot: artifact.capability_snapshot,
+    git_dir: projectDir, result_commit_ref: lineage.result_commit_ref,
   });
-  return Object.freeze({ path, review_ref, lineage, review: validated, decision, journal, written });
+  return Object.freeze({ review_ref, lineage, review: validated, decision, journal, written: !journal.replay });
 }

package/src/orchestrator/runtime-installation-v2.js

@@ -1,13 +1,17 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { INSTALLATION_ARTIFACT_PATH, doctorV2 } from '../installer-v2/index.js';
+import { doctorV2 } from '../installer-v2/index.js';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { assertEligibleInvocation } from '@chati/provider-registry';
+import { selectCanonicalReviewer } from '@chati/review-council';
+import {
+  readInstallationArtifactFile, verifyInstallationCatalogProvenance,
+} from '../installer-v2/catalog-client.js';
+import { verifyInstallationArtifactAuthority } from '../installer-v2/installation-authority.js';
 
 const AGENT_ACTIONS = Object.freeze({
   'greenfield-wu': 'discovery', 'brownfield-wu': 'discovery', brief: 'discovery',
   detail: 'planning', architect: 'planning', ux: 'planning', phases: 'planning', tasks: 'planning',
-  'qa-planning': 'review', dev: 'build', 'qa-implementation': 'review', 'qa-visual': 'review',
-  devops: 'build',
+  'qa-planning': 'review',
 });
 
 export const V2_PLANNING_AGENTS = Object.freeze([
@@ -15,7 +19,78 @@ export const V2_PLANNING_AGENTS = Object.freeze([
   'detail', 'architect', 'ux', 'qa-planning', 'phases', 'tasks',
 ]);
 
+const V2_PLANNING_PREDECESSORS = Object.freeze({
+  brief: Object.freeze(['work-understanding']),
+  detail: Object.freeze(['work-understanding', 'brief']),
+  architect: Object.freeze(['work-understanding', 'brief']),
+  ux: Object.freeze(['work-understanding', 'brief']),
+  'qa-planning': Object.freeze(['work-understanding', 'brief', 'detail', 'architect', 'ux']),
+  phases: Object.freeze(['work-understanding', 'brief', 'detail', 'architect', 'ux', 'qa-planning']),
+  tasks: Object.freeze(['work-understanding', 'brief', 'detail', 'architect', 'ux', 'qa-planning', 'phases']),
+});
+
+export function assertV2PlanningPredecessors(session, agent) {
+  const projectType = session?.project_type || session?.project?.type || 'greenfield';
+  const required = (V2_PLANNING_PREDECESSORS[agent] || []).map((name) =>
+    name === 'work-understanding' ? (projectType === 'brownfield' ? 'brownfield-wu' : 'greenfield-wu') : name
+  );
+  const incomplete = required.filter((name) =>
+    session?.agents?.[name]?.status !== 'completed' || !session?.completed_agents?.includes(name)
+  );
+  if (incomplete.length > 0) {
+    const error = new Error(`Agent ${agent} cannot advance before its canonical predecessors complete: ${incomplete.join(', ')}`);
+    error.code = 'V2_PLANNING_PREDECESSORS_INCOMPLETE';
+    error.incomplete = incomplete;
+    throw error;
+  }
+  return Object.freeze({ valid: true, required: Object.freeze(required) });
+}
+
 const RAIL_ACTIONS = new Set(['build', 'review']);
+const REASONING_CONFIGURATIONS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
+
+function highestCompatibleReasoning(binding, model) {
+  const maximum = model.highest_reasoning_configuration || 'xhigh';
+  const maximumRank = REASONING_CONFIGURATIONS.indexOf(maximum);
+  if (maximumRank < 0) return null;
+  const allowed = new Set(binding.allowed_reasoning_configurations || []);
+  for (let rank = maximumRank; rank >= 0; rank -= 1) {
+    const candidate = REASONING_CONFIGURATIONS[rank];
+    if (allowed.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+function nearestCompatibleReasoning(binding, model, preferred) {
+  const maximum = model.highest_reasoning_configuration || 'xhigh';
+  const maximumRank = REASONING_CONFIGURATIONS.indexOf(maximum);
+  const preferredRank = REASONING_CONFIGURATIONS.indexOf(preferred);
+  if (maximumRank < 0 || preferredRank < 0) return null;
+  const allowed = (binding.allowed_reasoning_configurations || [])
+    .filter((candidate) => {
+      const rank = REASONING_CONFIGURATIONS.indexOf(candidate);
+      return rank >= 0 && rank <= maximumRank;
+    });
+  return allowed.sort((left, right) => {
+    const leftRank = REASONING_CONFIGURATIONS.indexOf(left);
+    const rightRank = REASONING_CONFIGURATIONS.indexOf(right);
+    return Math.abs(leftRank - preferredRank) - Math.abs(rightRank - preferredRank)
+      || leftRank - rightRank;
+  })[0] || null;
+}
+
+function compatibleReasoning(binding, model, requested, preferred) {
+  if (requested === undefined || requested === null) {
+    return nearestCompatibleReasoning(binding, model, preferred);
+  }
+  const requestedRank = REASONING_CONFIGURATIONS.indexOf(requested);
+  const maximumRank = REASONING_CONFIGURATIONS.indexOf(model.highest_reasoning_configuration || 'xhigh');
+  if (requestedRank < 0 || maximumRank < 0 || requestedRank > maximumRank
+    || !binding.allowed_reasoning_configurations?.includes(requested)) {
+    return null;
+  }
+  return requested;
+}
 
 export function describeRuntimeInstallationV2(artifact) {
   const railExecutionPool = artifact.installation.enabled_providers.map((binding) => {
@@ -48,21 +123,54 @@ export function describeRuntimeInstallationV2(artifact) {
   });
 }
 
-export function loadRuntimeInstallationV2(projectDir, { clock = () => new Date() } = {}) {
-  const path = join(projectDir, INSTALLATION_ARTIFACT_PATH);
-  if (!existsSync(path)) return null;
+export function loadRuntimeInstallationV2(projectDir, {
+  clock = () => new Date(), authorityDirectory, source = null,
+} = {}) {
+  const installationSource = source ?? readInstallationArtifactFile(projectDir);
+  if (!installationSource) {
+    if (existsSync(join(resolve(projectDir), '.chati', 'v2'))) {
+      throw Object.assign(new Error('V2 installation artifact is required for a V2 project'), {
+        code: 'INSTALLATION_ARTIFACT_REQUIRED',
+      });
+    }
+    return null;
+  }
   let artifact;
-  try { artifact = JSON.parse(readFileSync(path, 'utf8')); } catch (error) {
+  try { artifact = JSON.parse(installationSource.content); } catch (error) {
     throw Object.assign(new Error('Invalid v2 installation artifact'), { code: 'INVALID_INSTALLATION_ARTIFACT', cause: error });
   }
   const doctor = doctorV2(artifact, { clock });
   if (!doctor.passed) throw Object.assign(new Error('V2 installation artifact failed doctor'), { code: doctor.checks[0]?.code || 'INVALID_INSTALLATION_ARTIFACT' });
+  verifyInstallationArtifactAuthority(projectDir, artifact, { authorityDirectory });
+  verifyInstallationCatalogProvenance(projectDir, artifact.capability_snapshot, { clock });
   return Object.freeze(artifact);
 }
 
-export function resolveRuntimeInvocationV2({ artifact, agent, binding, model_id, reasoning_configuration, clock = () => new Date() }) {
-  const action = AGENT_ACTIONS[agent];
-  if (!action) throw Object.assign(new Error(`No v2 action mapping for agent ${agent}`), { code: 'UNMAPPED_AGENT_ACTION' });
+export function resolveRuntimeExecutableBindingV2({ artifact, provider_id, harness_id } = {}) {
+  const binding = artifact?.installation?.enabled_providers?.find((candidate) =>
+    candidate.provider_id === provider_id && candidate.harness_id === harness_id);
+  if (!binding) {
+    throw Object.assign(new Error('provider executable binding is not part of the selected installation'), { code: 'BINDING_NOT_SELECTED' });
+  }
+  if (typeof binding.executable_path !== 'string' || !binding.executable_path.startsWith('/')
+    || !/^[a-f0-9]{64}$/.test(binding.executable_sha256 || '')) {
+    throw Object.assign(
+      new Error(`installed ${provider_id}/${harness_id} binding does not seal a provider executable`),
+      { code: 'PROVIDER_EXECUTABLE_BINDING_REQUIRED' },
+    );
+  }
+  return Object.freeze({
+    executable_path: binding.executable_path,
+    executable_sha256: binding.executable_sha256,
+    supporting_executables: Object.freeze((binding.supporting_executables || []).map((entry) => Object.freeze({
+      executable_path: entry.executable_path,
+      executable_sha256: entry.executable_sha256,
+    }))),
+  });
+}
+
+function resolveRuntimeActionV2({ artifact, action, routingKey, binding, model_id, reasoning_configuration, clock = () => new Date() }) {
+  let hasEligibleModel = false;
   const candidates = artifact.installation.enabled_providers.flatMap((candidateBinding) => {
     if (binding && (candidateBinding.provider_id !== binding.provider_id || candidateBinding.harness_id !== binding.harness_id)) return [];
     return candidateBinding.allowed_models.flatMap((candidateModelId) => {
@@ -71,10 +179,21 @@ export function resolveRuntimeInvocationV2({ artifact, agent, binding, model_id,
         candidate.provider_id === candidateBinding.provider_id && candidate.model_id === candidateModelId
       );
       if (!catalogModel?.actions.includes(action)) return [];
+      hasEligibleModel = true;
+      const defaultReasoning = catalogModel.tier === 'worker'
+        ? 'low'
+        : catalogModel.tier === 'workhorse'
+          ? 'medium'
+          : 'high';
+      const reasoning = compatibleReasoning(
+        candidateBinding, catalogModel, reasoning_configuration, defaultReasoning,
+      );
+      if (!reasoning) return [];
       return [{
         binding: candidateBinding,
         model: catalogModel,
-        priority: catalogModel.routing_priority?.[agent] ?? catalogModel.routing_priority?.[action] ?? 0,
+        reasoning,
+        priority: catalogModel.routing_priority?.[routingKey] ?? catalogModel.routing_priority?.[action] ?? 0,
       }];
     });
   }).sort((left, right) =>
@@ -83,22 +202,119 @@ export function resolveRuntimeInvocationV2({ artifact, agent, binding, model_id,
     || `${left.binding.harness_id}:${left.model.model_id}`.localeCompare(`${right.binding.harness_id}:${right.model.model_id}`)
   );
   const selectedCandidate = candidates[0];
-  if (!selectedCandidate) throw Object.assign(new Error(`No eligible installed model for ${agent}/${action}`), { code: 'NO_ELIGIBLE_MODEL' });
+  if (!selectedCandidate) {
+    throw Object.assign(
+      new Error(`No eligible installed model and reasoning configuration for ${routingKey}/${action}`),
+      { code: hasEligibleModel ? 'NO_ELIGIBLE_REASONING' : 'NO_ELIGIBLE_MODEL' },
+    );
+  }
   const selected = selectedCandidate.binding;
   const model = selectedCandidate.model.model_id;
-  const defaultReasoning = selectedCandidate.model.tier === 'worker'
-    ? 'low'
-    : selectedCandidate.model.tier === 'workhorse'
-      ? 'medium'
-      : 'high';
   const invocation = {
     provider_id: selected.provider_id, harness_id: selected.harness_id, action,
     model_pin: {
       model_id: model,
       catalog_snapshot_ref: artifact.capability_snapshot.snapshot_id,
-      reasoning_configuration: reasoning_configuration ?? defaultReasoning,
+      reasoning_configuration: selectedCandidate.reasoning,
     },
   };
   assertEligibleInvocation({ installation: artifact.installation, snapshot: artifact.capability_snapshot, invocation, clock });
   return Object.freeze(invocation);
 }
+
+export function resolveRuntimeInvocationV2({ artifact, agent, binding, model_id, reasoning_configuration, clock = () => new Date() }) {
+  if (!V2_PLANNING_AGENTS.includes(agent)) {
+    throw Object.assign(
+      new Error(`Agent ${agent} is not executable through the v2 planning runtime; implementation and release must use RAIL`),
+      { code: 'V2_RAIL_EXECUTION_REQUIRED' },
+    );
+  }
+  const action = AGENT_ACTIONS[agent];
+  if (!action) throw Object.assign(new Error(`No v2 action mapping for agent ${agent}`), { code: 'UNMAPPED_AGENT_ACTION' });
+  return resolveRuntimeActionV2({ artifact, action, routingKey: agent, binding, model_id, reasoning_configuration, clock });
+}
+
+export function resolveRuntimeRailInvocationV2({ artifact, action = 'build', binding, model_id, reasoning_configuration, clock = () => new Date() }) {
+  if (!RAIL_ACTIONS.has(action)) {
+    throw Object.assign(new Error(`Action ${action} is not executable through RAIL`), { code: 'INVALID_RAIL_ACTION' });
+  }
+  return resolveRuntimeActionV2({ artifact, action, routingKey: `rail:${action}`, binding, model_id, reasoning_configuration, clock });
+}
+
+/** Selects the highest-ranked installed reviewer at the strongest available independence level. */
+export function resolveRuntimeRailReviewerV2({ artifact, builder_identity, clock = () => new Date() }) {
+  return selectCanonicalReviewer({
+    installation: artifact.installation,
+    snapshot: artifact.capability_snapshot,
+    builder_identity,
+    clock,
+  });
+}
+
+export function resolveRuntimeAdjudicationV2({ artifact, clock = () => new Date() }) {
+  const candidates = artifact.installation.enabled_providers.flatMap((binding) =>
+    binding.allowed_models.flatMap((modelId) => {
+      const model = artifact.capability_snapshot.models.find((candidate) =>
+        candidate.provider_id === binding.provider_id && candidate.model_id === modelId
+      );
+      if (!model?.actions.includes('adjudication')) return [];
+      const reasoning = highestCompatibleReasoning(binding, model);
+      if (!reasoning) return [];
+      return [{ binding, model, reasoning }];
+    })
+  ).sort((left, right) =>
+    (right.model.adjudication_priority ?? 0) - (left.model.adjudication_priority ?? 0)
+    || (right.model.routing_priority?.adjudication ?? 0) - (left.model.routing_priority?.adjudication ?? 0)
+    || `${left.binding.harness_id}:${left.model.model_id}`.localeCompare(`${right.binding.harness_id}:${right.model.model_id}`)
+  );
+  const selected = candidates[0];
+  if (!selected) throw Object.assign(new Error('No eligible installed model for adjudication'), { code: 'NO_ELIGIBLE_ADJUDICATOR' });
+  const invocation = {
+    provider_id: selected.binding.provider_id,
+    harness_id: selected.binding.harness_id,
+    action: 'adjudication',
+    model_pin: {
+      model_id: selected.model.model_id,
+      catalog_snapshot_ref: artifact.capability_snapshot.snapshot_id,
+      reasoning_configuration: selected.reasoning,
+    },
+  };
+  assertEligibleInvocation({ installation: artifact.installation, snapshot: artifact.capability_snapshot, invocation, clock });
+  return Object.freeze(invocation);
+}
+
+/**
+ * Revalidate a terminal command against the exact route selected from the
+ * integrity-checked installation artifact derived from the signed capability
+ * catalog. Eligibility alone is insufficient because an
+ * installation can permit several models while the router selected one.
+ */
+export function assertRuntimeCommandV2({ artifact, agent, command = {}, reasoning_escalation = false, clock = () => new Date() }) {
+  const expected = reasoning_escalation
+    ? resolveRuntimeAdjudicationV2({ artifact, clock })
+    : resolveRuntimeInvocationV2({ artifact, agent, clock });
+  const actual = {
+    provider_id: command.provider_id || null,
+    harness_id: command.harness_id || null,
+    model_id: command.model_id || null,
+    reasoning_configuration: command.reasoning_configuration || null,
+    catalog_snapshot_ref: command.catalog_snapshot_ref || null,
+    strict_provider: command.strict_provider === true,
+  };
+  const comparisons = [
+    ['provider_id', expected.provider_id, actual.provider_id],
+    ['harness_id', expected.harness_id, actual.harness_id],
+    ['model_id', expected.model_pin.model_id, actual.model_id],
+    ['reasoning_configuration', expected.model_pin.reasoning_configuration, actual.reasoning_configuration],
+    ['catalog_snapshot_ref', expected.model_pin.catalog_snapshot_ref, actual.catalog_snapshot_ref],
+    ['strict_provider', true, actual.strict_provider],
+  ];
+  const mismatches = comparisons.filter(([, expectedValue, actualValue]) => expectedValue !== actualValue);
+  if (mismatches.length > 0) {
+    throw Object.assign(
+      new Error(`Runtime command does not match the integrity-checked v2 route: ${mismatches.map(([field]) => field).join(', ')}`),
+      { code: 'RUNTIME_ROUTE_BINDING_MISMATCH', mismatches: mismatches.map(([field]) => field) },
+    );
+  }
+  return expected;
+}