chati-dev 4.4.1 → 4.5.1

package/node_modules/@chati/provider-registry/src/index.js

@@ -0,0 +1,132 @@
+import { ContractError, canonicalize } from '@chati/core';
+
+const DEFAULT_BINDINGS = Object.freeze({ claude: 'anthropic', codex: 'openai', grok: 'xai' });
+const ACTIONS = new Set(['discovery', 'planning', 'build', 'review', 'adjudication']);
+
+function assertObject(value, code, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new ContractError(code, `${label} must be an object`);
+}
+
+function assertString(value, code, label) {
+  if (typeof value !== 'string' || value.trim() === '') throw new ContractError(code, `${label} must be a non-empty string`);
+}
+
+function parseTime(value, code, label) {
+  assertString(value, code, label);
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) throw new ContractError(code, `${label} must be a valid timestamp`);
+  return parsed;
+}
+
+function readClock(clock) {
+  if (typeof clock !== 'function') throw new ContractError('MISSING_CLOCK', 'a deterministic clock function is required');
+  const value = clock();
+  const millis = value instanceof Date ? value.getTime() : Date.parse(value);
+  if (Number.isNaN(millis)) throw new ContractError('INVALID_CLOCK', 'clock must return a valid Date or RFC3339 timestamp');
+  return millis;
+}
+
+/** Validates the immutable model catalog used by a single installation. */
+export function validateCapabilitySnapshot(snapshot, { clock } = {}) {
+  assertObject(snapshot, 'INVALID_CATALOG', 'snapshot');
+  assertString(snapshot.snapshot_id, 'INVALID_CATALOG', 'snapshot_id');
+  const expiresAt = parseTime(snapshot.expires_at, 'INVALID_CATALOG', 'expires_at');
+  if (expiresAt <= readClock(clock)) throw new ContractError('CATALOG_SNAPSHOT_EXPIRED', 'capability snapshot is expired', { snapshot_id: snapshot.snapshot_id });
+  if (!Array.isArray(snapshot.models) || snapshot.models.length === 0) throw new ContractError('INVALID_CATALOG', 'models must be a non-empty array');
+  const ids = new Set();
+  for (const model of snapshot.models) {
+    assertObject(model, 'INVALID_CATALOG', 'model');
+    assertString(model.provider_id, 'INVALID_CATALOG', 'model.provider_id');
+    assertString(model.model_id, 'INVALID_CATALOG', 'model.model_id');
+    const key = `${model.provider_id}:${model.model_id}`;
+    if (ids.has(key)) throw new ContractError('INVALID_CATALOG', `duplicate model ${key}`);
+    ids.add(key);
+    if (!Array.isArray(model.actions) || model.actions.length === 0 || !model.actions.every((action) => ACTIONS.has(action))) {
+      throw new ContractError('INVALID_CATALOG', 'model.actions contains an unsupported action');
+    }
+    if (model.actions.includes('adjudication')) {
+      assertString(model.highest_reasoning_configuration, 'INVALID_CATALOG', 'model.highest_reasoning_configuration');
+    } else if (model.highest_reasoning_configuration !== undefined) {
+      assertString(model.highest_reasoning_configuration, 'INVALID_CATALOG', 'model.highest_reasoning_configuration');
+    }
+  }
+  return Object.freeze(canonicalize(snapshot));
+}
+
+/** C-01. The installed binding set is an absolute allowlist. */
+export function validateInstallation(installation, snapshot, { bindingMap = DEFAULT_BINDINGS, clock } = {}) {
+  assertObject(installation, 'INVALID_INSTALLATION', 'installation');
+  for (const field of ['installation_id', 'profile', 'capability_snapshot_ref', 'policy_ref']) assertString(installation[field], 'INVALID_INSTALLATION', field);
+  const catalog = validateCapabilitySnapshot(snapshot, { clock });
+  if (installation.capability_snapshot_ref !== catalog.snapshot_id) {
+    throw new ContractError('CATALOG_SNAPSHOT_MISMATCH', 'installation does not reference the supplied catalog');
+  }
+  if (!Array.isArray(installation.enabled_providers) || installation.enabled_providers.length === 0) {
+    throw new ContractError('INVALID_INSTALLATION', 'enabled_providers must be a non-empty array');
+  }
+  const selectedHarnesses = new Set();
+  const selectedBindings = new Map();
+  for (const binding of installation.enabled_providers) {
+    assertObject(binding, 'INVALID_INSTALLATION', 'enabled provider binding');
+    assertString(binding.provider_id, 'INVALID_INSTALLATION', 'provider_id');
+    assertString(binding.harness_id, 'INVALID_INSTALLATION', 'harness_id');
+    if (selectedHarnesses.has(binding.harness_id)) throw new ContractError('DUPLICATE_HARNESS_BINDING', `harness ${binding.harness_id} has more than one selected provider`);
+    if (bindingMap[binding.harness_id] !== binding.provider_id) {
+      throw new ContractError('PROVIDER_HARNESS_MISMATCH', `${binding.provider_id}/${binding.harness_id} is not an allowed binding`);
+    }
+    if (!Array.isArray(binding.allowed_models) || binding.allowed_models.length === 0 || !binding.allowed_models.every((model) => typeof model === 'string' && model)) {
+      throw new ContractError('INVALID_INSTALLATION', 'allowed_models must be a non-empty array');
+    }
+    for (const modelId of binding.allowed_models) {
+      const catalogModel = catalog.models.find((model) => model.provider_id === binding.provider_id && model.model_id === modelId);
+      if (!catalogModel) {
+        throw new ContractError('MODEL_NOT_IN_CATALOG', `${modelId} is not available for ${binding.provider_id}`);
+      }
+    }
+    if (binding.allowed_reasoning_configurations !== undefined) {
+      if (!Array.isArray(binding.allowed_reasoning_configurations) || !binding.allowed_reasoning_configurations.every((reasoning) => typeof reasoning === 'string' && reasoning)) {
+        throw new ContractError('INVALID_INSTALLATION', 'allowed_reasoning_configurations must be an array of non-empty strings');
+      }
+    }
+    selectedHarnesses.add(binding.harness_id);
+    selectedBindings.set(`${binding.provider_id}:${binding.harness_id}`, binding);
+  }
+  assertObject(installation.primary_binding, 'INVALID_INSTALLATION', 'primary_binding');
+  const primaryKey = `${installation.primary_binding.provider_id}:${installation.primary_binding.harness_id}`;
+  if (!selectedBindings.has(primaryKey)) throw new ContractError('PRIMARY_BINDING_NOT_SELECTED', 'primary_binding must be selected');
+  if (installation.primary_harness !== undefined && installation.primary_harness !== installation.primary_binding.harness_id) {
+    throw new ContractError('PRIMARY_HARNESS_MISMATCH', 'primary_harness must match primary_binding.harness_id');
+  }
+  if (installation.profile === 'focus-ai-internal' && installation.external_integrations?.clickup !== 'required') {
+    throw new ContractError('PROFILE_DEPENDENCY_MISSING', 'focus-ai-internal requires ClickUp');
+  }
+  return Object.freeze(canonicalize(installation));
+}
+
+/** C-02. Returns only an explicitly selected and catalog-eligible binding. */
+export function assertEligibleInvocation({ installation, snapshot, invocation, clock, bindingMap = DEFAULT_BINDINGS }) {
+  const selected = validateInstallation(installation, snapshot, { bindingMap, clock });
+  assertObject(invocation, 'INVALID_INVOCATION', 'invocation');
+  assertString(invocation.provider_id, 'INVALID_INVOCATION', 'provider_id');
+  assertString(invocation.harness_id, 'INVALID_INVOCATION', 'harness_id');
+  assertString(invocation.action, 'INVALID_INVOCATION', 'action');
+  assertString(invocation.model_pin?.model_id, 'INVALID_INVOCATION', 'model_pin.model_id');
+  if (invocation.model_pin?.catalog_snapshot_ref !== selected.capability_snapshot_ref) {
+    throw new ContractError('CATALOG_SNAPSHOT_MISMATCH', 'invocation pin does not match installation snapshot');
+  }
+  if (!snapshot.models.some((candidate) => candidate.provider_id === invocation.provider_id)) {
+    throw new ContractError('UNKNOWN_PROVIDER', 'provider is absent from the selected capability snapshot');
+  }
+  const binding = selected.enabled_providers.find((candidate) => candidate.provider_id === invocation.provider_id && candidate.harness_id === invocation.harness_id);
+  if (!binding) throw new ContractError('BINDING_NOT_SELECTED', 'provider/harness binding was not selected');
+  if (!binding.allowed_models.includes(invocation.model_pin.model_id)) throw new ContractError('MODEL_NOT_SELECTED', 'model was not selected for this binding');
+  const reasoning = invocation.model_pin.reasoning_configuration;
+  if (reasoning !== undefined && reasoning !== null && !binding.allowed_reasoning_configurations?.includes(reasoning)) {
+    throw new ContractError('REASONING_NOT_SELECTED', 'reasoning configuration was not selected for this binding');
+  }
+  const model = snapshot.models.find((candidate) => candidate.provider_id === invocation.provider_id && candidate.model_id === invocation.model_pin.model_id);
+  if (!model || !model.actions.includes(invocation.action)) throw new ContractError('MODEL_NOT_ELIGIBLE', 'model is not eligible for this action');
+  return Object.freeze({ binding: canonicalize(binding), model: canonicalize(model) });
+}
+
+export const knownProviderHarnessBindings = DEFAULT_BINDINGS;

package/node_modules/@chati/rail/README.md

@@ -0,0 +1,24 @@
+# @chati/rail
+
+Local, deterministic implementation of G3 contracts C-04 and C-06.
+
+It accepts only sealed handoffs from `@chati/planning`, writes an append-only
+JSONL journal, a local exclusive journal lock, and a single task-claim state
+machine for normal dispatch and recovery. Every record is hash-chained and a
+sidecar checkpoint detects tail truncation. Completion is based only on local
+Git and injected fake-CI evidence. It has no provider invocation, remote Git,
+ClickUp, Brain, browser, release, timer, or network integration.
+
+## Contract limits
+
+- A lease expiry never authorizes blind takeover. Recovery requires structured
+  process, heartbeat, Git, CI, and every-effect reconciliation.
+- Side effects require an idempotency key persisted in the journal before a
+  receipt may be recorded, and require a live lease.
+- `ready_to_merge` and its explicit `merged` transition require independent
+  review references, acceptance evidence, local Git commit verification, and
+  passed CI evidence.
+- Completion records are immutable. A later `merged` record is a new event,
+  not an edit of `ready_to_merge`, and cannot skip it. Completion requires a
+  live lease. ClickUp and any external projection are
+  intentionally outside this package.

package/node_modules/@chati/rail/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@chati/rail",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Local contract engine for sealed CHATI task execution",
+  "type": "module",
+  "exports": "./src/index.js",
+  "dependencies": {
+    "@chati/core": "0.1.0",
+    "@chati/planning": "0.1.0",
+    "@chati/review-council": "0.1.0"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/node_modules/@chati/rail/src/index.js

@@ -0,0 +1,437 @@
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ContractError, canonicalize, sha256 } from '@chati/core';
+import { createAttemptBinding, validateAttemptBinding, verifyLocalGitCommit } from '@chati/planning';
+import { acceptReview, decideReviewProgress } from '@chati/review-council';
+
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const TASK_CLOSED_STATES = new Set(['merged', 'blocked', 'cancelled']);
+const EXECUTABLE_ATTEMPT_STATE = 'active';
+const REVIEW_DECISIONS = new Set(['accept', 'normal-rework', 'AI_ADJUDICATION', 'blocked', 'required-human-decision']);
+const LOCK_RETRIES = 50;
+const LOCK_WAIT = new Int32Array(new SharedArrayBuffer(4));
+
+function fail(code, message, details = {}) {
+  throw new ContractError(code, message, details);
+}
+
+function assertObject(value, code, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(code, `${label} must be an object`);
+}
+
+function assertString(value, code, label) {
+  if (typeof value !== 'string' || value.trim() === '') fail(code, `${label} must be a non-empty string`);
+}
+
+function assertStringArray(value, code, label, { allowEmpty = true } = {}) {
+  if (!Array.isArray(value) || (!allowEmpty && value.length === 0) || !value.every((item) => typeof item === 'string' && item.trim() !== '')) {
+    fail(code, `${label} must be an array of non-empty strings`);
+  }
+}
+
+function timestamp(clock) {
+  if (typeof clock !== 'function') fail('MISSING_CLOCK', 'a deterministic clock function is required');
+  const value = clock();
+  const iso = value instanceof Date ? value.toISOString() : value;
+  if (typeof iso !== 'string' || !RFC3339.test(iso) || Number.isNaN(Date.parse(iso))) fail('INVALID_CLOCK', 'clock must return a valid RFC3339 timestamp or Date');
+  return iso;
+}
+
+function plusMs(iso, milliseconds) {
+  if (!Number.isInteger(milliseconds) || milliseconds <= 0) fail('INVALID_LEASE_TTL', 'lease_ttl_ms must be a positive integer');
+  return new Date(Date.parse(iso) + milliseconds).toISOString();
+}
+
+function stableEventId(sequence, event) {
+  const material = event.causation_id === undefined
+    ? { sequence, event: { type: event.type, payload: event.payload } }
+    : { sequence, event };
+  return `rail-${String(sequence).padStart(8, '0')}-${sha256(material).slice(0, 16)}`;
+}
+
+function checkpointPath(journalPath) { return `${journalPath}.checkpoint`; }
+function lockPath(journalPath) { return `${journalPath}.lock`; }
+
+function parseJournal(journalPath) {
+  if (!existsSync(journalPath)) return [];
+  const lines = readFileSync(journalPath, 'utf8').split('\n').filter(Boolean);
+  const records = [];
+  let previous_hash = 'GENESIS';
+  for (const [index, line] of lines.entries()) {
+    let record;
+    try { record = JSON.parse(line); } catch { fail('JOURNAL_CORRUPT', 'journal contains malformed JSONL', { line: index + 1 }); }
+    assertObject(record, 'JOURNAL_CORRUPT', 'journal record');
+    const { record_hash, chain_hash, previous_hash: record_previous_hash, ...material } = record;
+    assertString(record_hash, 'JOURNAL_CORRUPT', 'record_hash');
+    assertString(chain_hash, 'JOURNAL_CORRUPT', 'chain_hash');
+    if (record_previous_hash !== previous_hash) fail('JOURNAL_CHAIN_MISMATCH', 'journal previous hash does not match prior record', { event_id: record.event_id });
+    if (sha256(material) !== record_hash) fail('JOURNAL_INTEGRITY_MISMATCH', 'journal record hash does not match material', { event_id: record.event_id });
+    if (sha256({ previous_hash, record_hash }) !== chain_hash) fail('JOURNAL_CHAIN_MISMATCH', 'journal chain hash does not match record', { event_id: record.event_id });
+    previous_hash = chain_hash;
+    records.push(Object.freeze(canonicalize(record)));
+  }
+  const checkpointFile = checkpointPath(journalPath);
+  if (existsSync(checkpointFile)) {
+    let checkpoint;
+    try { checkpoint = JSON.parse(readFileSync(checkpointFile, 'utf8')); } catch { fail('JOURNAL_CHECKPOINT_CORRUPT', 'journal checkpoint is malformed'); }
+    assertObject(checkpoint, 'JOURNAL_CHECKPOINT_CORRUPT', 'journal checkpoint');
+    if (checkpoint.schema_version !== 1 || checkpoint.record_count !== records.length || checkpoint.chain_hash !== previous_hash || checkpoint.last_event_id !== records.at(-1)?.event_id) {
+      fail('JOURNAL_TRUNCATION_DETECTED', 'journal does not match its persisted checkpoint');
+    }
+  }
+  return records;
+}
+
+function isExpired(claim, now) {
+  return Date.parse(claim.lease.expires_at) <= Date.parse(now);
+}
+
+function validateRecoveryReconciliation(reconciliation, attempt, effects, gitDir) {
+  assertObject(reconciliation, 'INVALID_RECOVERY', 'reconciliation');
+  if (reconciliation.status !== 'safe_to_resume') fail('RECOVERY_RECONCILIATION_REQUIRED', 'recovery requires safe_to_resume reconciliation');
+  for (const field of ['process', 'heartbeat', 'git', 'ci']) assertObject(reconciliation[field], 'RECOVERY_RECONCILIATION_REQUIRED', `reconciliation.${field}`);
+  if (reconciliation.process.status !== 'not_running') fail('RECOVERY_PROCESS_UNRESOLVED', 'recovery requires an observed non-running prior process');
+  assertStringArray(reconciliation.process.evidence_refs, 'RECOVERY_PROCESS_UNRESOLVED', 'reconciliation.process.evidence_refs', { allowEmpty: false });
+  if (reconciliation.heartbeat.status !== 'expired') fail('RECOVERY_HEARTBEAT_UNRESOLVED', 'recovery requires an expired heartbeat observation');
+  assertString(reconciliation.heartbeat.observed_at, 'RECOVERY_HEARTBEAT_UNRESOLVED', 'reconciliation.heartbeat.observed_at');
+  assertStringArray(reconciliation.heartbeat.evidence_refs, 'RECOVERY_HEARTBEAT_UNRESOLVED', 'reconciliation.heartbeat.evidence_refs', { allowEmpty: false });
+  if (reconciliation.git.status !== 'matched' || reconciliation.git.commit_ref !== attempt.git_commit_ref) fail('RECOVERY_GIT_UNRESOLVED', 'recovery Git reconciliation must match the bound commit');
+  assertStringArray(reconciliation.git.evidence_refs, 'RECOVERY_GIT_UNRESOLVED', 'reconciliation.git.evidence_refs', { allowEmpty: false });
+  verifyLocalGitCommit({ git_dir: gitDir, git_commit_ref: attempt.git_commit_ref });
+  if (!['not_started', 'passed', 'failed'].includes(reconciliation.ci.status)) fail('RECOVERY_CI_UNRESOLVED', 'recovery CI status must be explicit');
+  assertStringArray(reconciliation.ci.evidence_refs, 'RECOVERY_CI_UNRESOLVED', 'reconciliation.ci.evidence_refs', { allowEmpty: false });
+  if (!Array.isArray(reconciliation.effects)) fail('RECOVERY_EFFECTS_UNRESOLVED', 'recovery requires an effect reconciliation array');
+  const provided = new Map(reconciliation.effects.map((effect) => [effect?.idempotency_key, effect]));
+  for (const effect of effects) {
+    const item = provided.get(effect.idempotency_key);
+    if (!item || !['receipted', 'not_sent'].includes(item.status)) fail('RECOVERY_EFFECTS_UNRESOLVED', 'every prepared effect requires a resolved outcome', { idempotency_key: effect.idempotency_key });
+    if (effect.receipt_ref && (item.status !== 'receipted' || item.receipt_ref !== effect.receipt_ref)) fail('RECOVERY_EFFECTS_UNRESOLVED', 'receipt reconciliation does not match journal', { idempotency_key: effect.idempotency_key });
+  }
+}
+
+/**
+ * C-04/C-06 local engine. Every mutable operational fact is represented by a
+ * new journal event. The journal itself is canonical for this package.
+ */
+export class RailEngine {
+  #journalPath;
+  #clock;
+  #records;
+
+  constructor({ journal_path, clock } = {}) {
+    assertString(journal_path, 'INVALID_JOURNAL_PATH', 'journal_path');
+    this.#journalPath = journal_path;
+    this.#clock = clock;
+    this.#records = parseJournal(journal_path);
+  }
+
+  get journalPath() { return this.#journalPath; }
+  get records() { return Object.freeze([...this.#records]); }
+
+  #exclusive(action) {
+    mkdirSync(dirname(this.#journalPath), { recursive: true });
+    const path = lockPath(this.#journalPath);
+    let descriptor;
+    for (let retry = 0; retry < LOCK_RETRIES; retry += 1) {
+      try { descriptor = openSync(path, 'wx', 0o600); break; } catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+        // Wait briefly for the other local transaction, never steal its lock.
+        Atomics.wait(LOCK_WAIT, 0, 0, 2);
+      }
+    }
+    if (descriptor === undefined) fail('JOURNAL_LOCK_BUSY', 'journal mutation lock is already held');
+    try {
+      this.#records = parseJournal(this.#journalPath);
+      return action();
+    } finally {
+      closeSync(descriptor);
+      unlinkSync(path);
+    }
+  }
+
+  #assertLiveLease(attempt, now, code = 'LEASE_EXPIRED') {
+    if (isExpired(attempt.claim, now)) fail(code, 'operation requires a live claim lease', { attempt_id: attempt.attempt_id });
+  }
+
+  #writeCheckpoint(record) {
+    const checkpoint = canonicalize({ schema_version: 1, record_count: this.#records.length, last_event_id: record.event_id, chain_hash: record.chain_hash });
+    const target = checkpointPath(this.#journalPath);
+    const temporary = `${target}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify(checkpoint), { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporary, target);
+  }
+
+  #append(type, payload, causation_id) {
+    const occurred_at = timestamp(this.#clock);
+    const material = canonicalize({
+      schema_version: 1,
+      event_id: stableEventId(this.#records.length + 1, { type, payload, causation_id }),
+      type,
+      occurred_at,
+      ...(causation_id ? { causation_id } : {}),
+      payload,
+    });
+    const record_hash = sha256(material);
+    const previous_hash = this.#records.at(-1)?.chain_hash ?? 'GENESIS';
+    const record = Object.freeze(canonicalize({ ...material, record_hash, previous_hash, chain_hash: sha256({ previous_hash, record_hash }) }));
+    mkdirSync(dirname(this.#journalPath), { recursive: true });
+    appendFileSync(this.#journalPath, `${JSON.stringify(record)}\n`, { encoding: 'utf8', flag: 'a' });
+    this.#records.push(record);
+    this.#writeCheckpoint(record);
+    return record;
+  }
+
+  #attempts() {
+    const attempts = new Map();
+    for (const record of this.#records) {
+      const { type, payload } = record;
+      if (type === 'attempt_claimed') attempts.set(payload.attempt.attempt_id, { ...payload.attempt, claim: payload.claim, state: 'active', claim_event_id: record.event_id });
+      if (type === 'attempt_heartbeat') {
+        const current = attempts.get(payload.attempt_id);
+        if (current) current.claim = { ...current.claim, lease: payload.lease };
+      }
+      if (type === 'attempt_recovered') {
+        const current = attempts.get(payload.attempt_id);
+        if (current) { current.claim = payload.claim; current.state = payload.resume_state ?? 'active'; current.recovery_event_id = record.event_id; }
+      }
+      if (type === 'attempt_completed') {
+        const current = attempts.get(payload.completion.attempt_id);
+        if (current) current.state = payload.completion.state;
+      }
+      if (type === 'attempt_blocked' || type === 'attempt_cancelled') {
+        const current = attempts.get(payload.attempt_id);
+        if (current) current.state = type === 'attempt_blocked' ? 'blocked' : 'cancelled';
+      }
+    }
+    return attempts;
+  }
+
+  #effects() {
+    const effects = new Map();
+    for (const record of this.#records) {
+      if (record.type === 'effect_prepared') effects.set(record.payload.idempotency_key, { ...record.payload, prepared_event_id: record.event_id });
+      if (record.type === 'effect_receipted') {
+        const effect = effects.get(record.payload.idempotency_key);
+        if (effect) effect.receipt_ref = record.payload.receipt_ref;
+      }
+    }
+    return effects;
+  }
+
+  #currentClaimForTask(taskId) {
+    const now = timestamp(this.#clock);
+    for (const attempt of this.#attempts().values()) {
+      if (attempt.task_id === taskId && !TASK_CLOSED_STATES.has(attempt.state)) return { attempt, expired: isExpired(attempt.claim, now) };
+    }
+    return undefined;
+  }
+
+  #mergedTaskIdsForHandoff(handoffId) {
+    return [...this.#attempts().values()]
+      .filter((attempt) => attempt.handoff_id === handoffId && attempt.state === 'merged')
+      .map((attempt) => attempt.task_id);
+  }
+
+  #assertAcceptedReviews(attemptId, reviews) {
+    const decisions = this.#records.filter((record) => record.type === 'review_decided'
+      && record.payload?.attempt_id === attemptId);
+    const byReference = new Map(decisions.map((record) => [record.payload.review_ref, record]));
+    const uniqueReviews = new Set(reviews);
+    if (uniqueReviews.size !== reviews.length || reviews.some((reviewRef) => !byReference.has(reviewRef))) {
+      fail('UNVERIFIED_REVIEW_EVIDENCE', 'every completion review must reference a canonical journal decision', { attempt_id: attemptId });
+    }
+    const latest = decisions.at(-1);
+    if (!latest || latest.payload.decision?.decision !== 'accept' || !uniqueReviews.has(latest.payload.review_ref)) {
+      fail('REVIEW_NOT_ACCEPTED', 'completion requires the latest canonical review decision to accept the attempt', { attempt_id: attemptId });
+    }
+  }
+
+  claimTask({ handoff, task_id, attempt_id, operator_id, harness_process_id, git_dir, lease_ttl_ms = 300000 } = {}) {
+    return this.#exclusive(() => {
+    assertString(operator_id, 'INVALID_CLAIM', 'operator_id');
+    assertString(harness_process_id, 'INVALID_CLAIM', 'harness_process_id');
+    const incumbent = this.#currentClaimForTask(task_id);
+    if (incumbent) {
+      const code = incumbent.expired ? 'CLAIM_RECOVERY_REQUIRED' : 'TASK_ALREADY_CLAIMED';
+      fail(code, 'task has an existing claim and cannot be taken over without recovery', { task_id, attempt_id: incumbent.attempt.attempt_id });
+    }
+    if (this.#attempts().has(attempt_id)) fail('ATTEMPT_ALREADY_EXISTS', 'attempt_id already exists in journal', { attempt_id });
+    const completed_task_ids = this.#mergedTaskIdsForHandoff(handoff.handoff_id);
+    const attempt = createAttemptBinding({ handoff, task_id, attempt_id, completed_task_ids, git_dir });
+    const acquired_at = timestamp(this.#clock);
+    const claim = canonicalize({
+      claim_id: `claim-${sha256({ attempt_id, acquired_at, operator_id, harness_process_id }).slice(0, 24)}`,
+      task_id,
+      handoff_id: attempt.handoff_id,
+      attempt_id,
+      operator_id,
+      harness_process_id,
+      lease: { acquired_at, expires_at: plusMs(acquired_at, lease_ttl_ms), heartbeat_at: acquired_at },
+      idempotency_scope: `task:${task_id}:attempt:${attempt_id}`,
+    });
+    const record = this.#append('attempt_claimed', { attempt, claim });
+    return Object.freeze(canonicalize({ attempt, claim, event_id: record.event_id }));
+    });
+  }
+
+  heartbeat({ attempt_id, claim_id, operator_id, lease_ttl_ms = 300000 } = {}) {
+    return this.#exclusive(() => {
+    assertString(attempt_id, 'INVALID_HEARTBEAT', 'attempt_id');
+    assertString(claim_id, 'INVALID_HEARTBEAT', 'claim_id');
+    assertString(operator_id, 'INVALID_HEARTBEAT', 'operator_id');
+    const attempt = this.#attempts().get(attempt_id);
+    if (!attempt || ![EXECUTABLE_ATTEMPT_STATE, 'ready_to_merge'].includes(attempt.state)) fail('ATTEMPT_NOT_ACTIVE', 'attempt is not active', { attempt_id });
+    if (attempt.claim.claim_id !== claim_id || attempt.claim.operator_id !== operator_id) fail('CLAIM_OWNER_MISMATCH', 'only the active claim owner may heartbeat', { attempt_id });
+    const heartbeat_at = timestamp(this.#clock);
+    this.#assertLiveLease(attempt, heartbeat_at);
+    const lease = { ...attempt.claim.lease, heartbeat_at, expires_at: plusMs(heartbeat_at, lease_ttl_ms) };
+    const record = this.#append('attempt_heartbeat', { attempt_id, claim_id, lease }, attempt.claim_event_id);
+    return Object.freeze(canonicalize({ attempt_id, claim_id, lease, event_id: record.event_id }));
+    });
+  }
+
+  prepareEffect({ attempt_id, claim_id, side_effect_class, idempotency_key, effect_ref } = {}) {
+    return this.#exclusive(() => {
+    for (const [field, value] of Object.entries({ attempt_id, claim_id, side_effect_class, idempotency_key, effect_ref })) assertString(value, 'INVALID_EFFECT', field);
+    const attempt = this.#attempts().get(attempt_id);
+    if (!attempt || attempt.state !== EXECUTABLE_ATTEMPT_STATE) fail('ATTEMPT_NOT_ACTIVE', 'effect requires an active attempt', { attempt_id });
+    if (attempt.claim.claim_id !== claim_id) fail('CLAIM_OWNER_MISMATCH', 'effect does not belong to active claim', { attempt_id });
+    this.#assertLiveLease(attempt, timestamp(this.#clock));
+    const existing = this.#effects().get(idempotency_key);
+    if (existing) {
+      if (existing.attempt_id !== attempt_id || existing.side_effect_class !== side_effect_class || existing.effect_ref !== effect_ref) {
+        fail('IDEMPOTENCY_KEY_CONFLICT', 'idempotency key is already bound to different effect material', { idempotency_key });
+      }
+      return Object.freeze(canonicalize({ ...existing, replay: true }));
+    }
+    const record = this.#append('effect_prepared', { attempt_id, claim_id, side_effect_class, idempotency_key, effect_ref });
+    return Object.freeze(canonicalize({ attempt_id, claim_id, side_effect_class, idempotency_key, effect_ref, prepared_event_id: record.event_id, replay: false }));
+    });
+  }
+
+  recordEffectReceipt({ idempotency_key, receipt_ref } = {}) {
+    return this.#exclusive(() => {
+    assertString(idempotency_key, 'INVALID_EFFECT_RECEIPT', 'idempotency_key');
+    assertString(receipt_ref, 'INVALID_EFFECT_RECEIPT', 'receipt_ref');
+    const effect = this.#effects().get(idempotency_key);
+    if (!effect) fail('EFFECT_NOT_PREPARED', 'receipt requires a persisted prepared effect', { idempotency_key });
+    if (effect.receipt_ref) {
+      if (effect.receipt_ref !== receipt_ref) fail('EFFECT_RECEIPT_CONFLICT', 'effect receipt cannot be changed', { idempotency_key });
+      return Object.freeze(canonicalize({ ...effect, replay: true }));
+    }
+    const record = this.#append('effect_receipted', { idempotency_key, receipt_ref }, effect.prepared_event_id);
+    return Object.freeze(canonicalize({ ...effect, receipt_ref, receipt_event_id: record.event_id, replay: false }));
+    });
+  }
+
+  /**
+   * Persists the Review Council transition that controls the next RAIL step.
+   * Review evidence itself remains external to this package, but the immutable
+   * reference and its selected decision become part of the canonical journal.
+   */
+  recordReviewDecision({ attempt_id, review_ref, decision, review, invocation, prior_review_evidence = [], installation, snapshot } = {}) {
+    return this.#exclusive(() => {
+      assertString(attempt_id, 'INVALID_REVIEW_DECISION', 'attempt_id');
+      assertString(review_ref, 'INVALID_REVIEW_DECISION', 'review_ref');
+      assertObject(decision, 'INVALID_REVIEW_DECISION', 'decision');
+      if (!REVIEW_DECISIONS.has(decision.decision)) fail('INVALID_REVIEW_DECISION', 'decision is not a Review Council outcome');
+      const attempt = this.#attempts().get(attempt_id);
+      if (!attempt || attempt.state !== EXECUTABLE_ATTEMPT_STATE) fail('ATTEMPT_NOT_ACTIVE', 'review decision requires an active attempt', { attempt_id });
+      this.#assertLiveLease(attempt, timestamp(this.#clock));
+      const validated = acceptReview({ review, invocation, installation, snapshot, clock: this.#clock });
+      if (validated.attempt_id !== attempt_id) fail('REVIEW_ATTEMPT_MISMATCH', 'review is not bound to this RAIL attempt');
+      const expectedRef = `rail-review://${attempt.handoff_id}/${attempt_id}/${validated.review_id}`;
+      if (review_ref !== expectedRef) fail('REVIEW_REFERENCE_MISMATCH', 'review reference is not bound to the claimed handoff and attempt');
+      const expected = decideReviewProgress({ prior_review_evidence, current_review: validated, reviewer_invocation: invocation, installation, snapshot, clock: this.#clock });
+      if (sha256(expected) !== sha256(decision)) fail('REVIEW_DECISION_MISMATCH', 'journal decision does not match validated Review Council evidence');
+      const existing = this.#records.find((record) => record.type === 'review_decided' && record.payload?.review_ref === review_ref);
+      if (existing) {
+        if (existing.payload.attempt_id !== attempt_id || sha256(existing.payload.decision) !== sha256(decision)) {
+          fail('REVIEW_DECISION_CONFLICT', 'review reference is already bound to different decision material', { review_ref });
+        }
+        return Object.freeze(canonicalize({ ...existing.payload, event_id: existing.event_id, replay: true }));
+      }
+      const record = this.#append('review_decided', { attempt_id, task_id: attempt.task_id, review_ref, decision: canonicalize(decision) });
+      return Object.freeze(canonicalize({ attempt_id, task_id: attempt.task_id, review_ref, decision, event_id: record.event_id, replay: false }));
+    });
+  }
+
+  recoverAttempt({ attempt_id, operator_id, harness_process_id, reconciliation, git_dir, lease_ttl_ms = 300000 } = {}) {
+    return this.#exclusive(() => {
+    for (const [field, value] of Object.entries({ attempt_id, operator_id, harness_process_id })) assertString(value, 'INVALID_RECOVERY', field);
+    assertString(git_dir, 'INVALID_RECOVERY', 'git_dir');
+    const attempt = this.#attempts().get(attempt_id);
+    if (!attempt || ![EXECUTABLE_ATTEMPT_STATE, 'ready_to_merge'].includes(attempt.state)) fail('ATTEMPT_NOT_RECOVERABLE', 'attempt is not recoverable', { attempt_id });
+    const now = timestamp(this.#clock);
+    if (!isExpired(attempt.claim, now)) fail('LEASE_STILL_ACTIVE', 'active lease cannot be recovered', { attempt_id });
+    validateRecoveryReconciliation(reconciliation, attempt, [...this.#effects().values()].filter((effect) => effect.attempt_id === attempt_id), git_dir);
+    const claim = canonicalize({
+      ...attempt.claim,
+      operator_id,
+      harness_process_id,
+      lease: { acquired_at: now, heartbeat_at: now, expires_at: plusMs(now, lease_ttl_ms) },
+    });
+    const resume_state = attempt.state;
+    const record = this.#append('attempt_recovered', { attempt_id, claim, reconciliation, resume_state }, attempt.claim_event_id);
+    return Object.freeze(canonicalize({ attempt_id, claim, resume_state, event_id: record.event_id }));
+    });
+  }
+
+  completeAttempt({ completion_id, attempt_id, claim_id, operator_id, state, git, ci, reviews, acceptance_evidence_refs, completed_at, metrics, handoff } = {}) {
+    return this.#exclusive(() => {
+    assertString(completion_id, 'INVALID_COMPLETION', 'completion_id');
+    assertString(attempt_id, 'INVALID_COMPLETION', 'attempt_id');
+    assertString(claim_id, 'INVALID_COMPLETION', 'claim_id');
+    assertString(operator_id, 'INVALID_COMPLETION', 'operator_id');
+    if (!['ready_to_merge', 'merged'].includes(state)) fail('INVALID_COMPLETION_STATE', 'state must be ready_to_merge or merged');
+    assertObject(git, 'INVALID_COMPLETION', 'git');
+    assertString(git.git_dir, 'INVALID_COMPLETION', 'git.git_dir');
+    assertStringArray(git.commit_refs, 'INVALID_COMPLETION', 'git.commit_refs', { allowEmpty: false });
+    assertObject(ci, 'INVALID_COMPLETION', 'ci');
+    if (ci.verdict !== 'passed') fail('CI_NOT_PASSED', 'completion requires passed CI evidence');
+    assertStringArray(ci.evidence_refs, 'INVALID_COMPLETION', 'ci.evidence_refs', { allowEmpty: false });
+    assertStringArray(reviews, 'MISSING_REVIEW_EVIDENCE', 'reviews', { allowEmpty: false });
+    assertStringArray(acceptance_evidence_refs, 'MISSING_ACCEPTANCE_EVIDENCE', 'acceptance_evidence_refs', { allowEmpty: false });
+    if (metrics !== undefined) {
+      assertObject(metrics, 'INVALID_COMPLETION_METRICS', 'metrics');
+      for (const field of ['actual_human_effort', 'actual_ai_processing']) {
+        assertObject(metrics[field], 'INVALID_COMPLETION_METRICS', `metrics.${field}`);
+        assertString(metrics[field].unit, 'INVALID_COMPLETION_METRICS', `metrics.${field}.unit`);
+        assertString(metrics[field].evidence_ref, 'INVALID_COMPLETION_METRICS', `metrics.${field}.evidence_ref`);
+        if (typeof metrics[field].value !== 'number' || !Number.isFinite(metrics[field].value) || metrics[field].value < 0) fail('INVALID_COMPLETION_METRICS', `metrics.${field}.value must be a non-negative finite number`);
+      }
+      if (!Number.isInteger(metrics.rework_cycles) || metrics.rework_cycles < 0) fail('INVALID_COMPLETION_METRICS', 'metrics.rework_cycles must be a non-negative integer');
+      assertStringArray(metrics.rework_review_refs, 'INVALID_COMPLETION_METRICS', 'metrics.rework_review_refs');
+      if (metrics.rework_review_refs.length !== metrics.rework_cycles) fail('INVALID_COMPLETION_METRICS', 'each rework cycle requires one review reference');
+    }
+    const existing = this.#records.find((record) => record.type === 'attempt_completed' && record.payload.completion.completion_id === completion_id);
+    if (existing) fail('COMPLETION_ALREADY_EXISTS', 'completion_id is immutable', { completion_id });
+    const attempt = this.#attempts().get(attempt_id);
+    const allowedTransition = (attempt?.state === EXECUTABLE_ATTEMPT_STATE && state === 'ready_to_merge') || (attempt?.state === 'ready_to_merge' && state === 'merged');
+    if (!allowedTransition) fail('INVALID_COMPLETION_TRANSITION', 'completion transition is not allowed for attempt state', { attempt_id, state, current_state: attempt?.state });
+    validateAttemptBinding({ attempt, handoff });
+    if (attempt.claim.claim_id !== claim_id || attempt.claim.operator_id !== operator_id) fail('CLAIM_OWNER_MISMATCH', 'only the active claim owner may complete an attempt', { attempt_id });
+    this.#assertLiveLease(attempt, timestamp(this.#clock));
+    this.#assertAcceptedReviews(attempt_id, reviews);
+    if (!git.commit_refs.includes(attempt.git_commit_ref)) fail('GIT_COMMIT_MISMATCH', 'completion must include the sealed attempt commit', { attempt_id });
+    for (const commit of git.commit_refs) verifyLocalGitCommit({ git_dir: git.git_dir, git_commit_ref: commit });
+    if (ci.commit_ref !== undefined && ci.commit_ref !== attempt.git_commit_ref) fail('CI_SHA_MISMATCH', 'CI evidence must be bound to sealed attempt commit', { attempt_id });
+    const now = timestamp(this.#clock);
+    const completion = canonicalize({
+      completion_id,
+      attempt_id,
+      task_id: attempt.task_id,
+      state,
+      git: { ...(git.base_ref ? { base_ref: git.base_ref } : {}), commit_refs: git.commit_refs, ...(git.pr_ref ? { pr_ref: git.pr_ref } : {}) },
+      ci: { evidence_refs: ci.evidence_refs, verdict: ci.verdict, ...(ci.commit_ref ? { commit_ref: ci.commit_ref } : {}) },
+      reviews,
+      acceptance_evidence_refs,
+      ...(metrics === undefined ? {} : { metrics }),
+      completed_at: completed_at ?? now,
+    });
+    if (!RFC3339.test(completion.completed_at)) fail('INVALID_COMPLETION', 'completed_at must be RFC3339');
+    const record = this.#append('attempt_completed', { completion });
+    return Object.freeze(canonicalize({ ...completion, event_id: record.event_id }));
+    });
+  }
+}

package/node_modules/@chati/release-lane/README.md

@@ -0,0 +1,24 @@
+# CHATI Release Lane
+
+Fixture-only C-11 contract. This package accepts only `FakeReleaseTransport` and has no network client, credential loader, Git command, deployment command or timer.
+
+`ReleaseLane` creates immutable hash-chained records. A release needs non-empty source completion references verified by an injected C-06 completion verifier as `merged` and bound to the same immutable reference, an immutable plan reference, passed fake smoke evidence and a human authorization whose `scope_hash` matches the exact release scope. Rollback is a separate attempt with a separate human authorization and scope hash. The package rejects accessors and non-plain nested inputs before it canonicalizes or records them.
+
+## Legacy removal readiness
+
+| Legacy surface | Replacement in G3 | Parity and migration evidence | Rollback | Responsibility | Status |
+| --- | --- | --- | --- | --- | --- |
+| BUILD agent | `chati-rail` execution attempt | G3-4 fixtures, G3-9 pending | legacy remains intact | Gabriel, technical policy | not-ready |
+| QA Implementation | `chati-review-council` plus RAIL completion | G3-5 fixtures, G3-9 pending | legacy remains intact | Gabriel, technical policy | ready-for-shadow |
+| QA Visual | browser capability contract | G3-7B fixtures, real visual parity pending | legacy remains intact | Gabriel, browser policy | not-ready |
+| DevOps / release | this fake-only release lane | C-11 tests below, real release deliberately absent | legacy remains intact | Gabriel, release policy | ready-for-shadow |
+| Legacy hooks | provider-neutral policy and adapters | G3-9 migration fixture pending | legacy remains intact | Gabriel, CHATI core | not-ready |
+| Provider maps | provider registry and harness adapters | G3-1 to G3-3 tests, parity pending | legacy remains intact | Gabriel, CHATI core | ready-for-shadow |
+
+No row is `ready-for-removal`. This matrix is not authorization to delete or deploy.
+
+## Verification
+
+```sh
+npm -w @chati/release-lane test
+```