@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/gate-engine.js

@@ -0,0 +1,871 @@
+'use strict';
+
+/** Máquina de estados G0-G4 compuesta sobre el writer privado del kernel. */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { assertEvidenceCurrent, isVerifiedEvidence } = require('./evidence-verifier');
+const { assertPrincipalCurrent, isVerifiedPrincipal } = require('./principal-verifier');
+const {
+  exactKeys, fail, freezeDeep, getContractValidators, plainObject,
+} = require('./policy-verifier-utils');
+const { canonicalizarIJson, validarTimestampIso } = require('./signed-envelope');
+
+const STATES = new WeakMap();
+const RECEIPTS = new WeakMap();
+const SHA256 = /^[a-f0-9]{64}$/u;
+const GIT_HASH = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const TASK = /^T-[0-9]{2}$/u;
+const REQUIREMENT = /^REQ-[0-9]{2}-[0-9]{2}$/u;
+const TASK_EVENTS = Object.freeze([
+  'red_recorded', 'tdd_exempted', 'implementation_started', 'tests_passed',
+]);
+const G4_EVENTS = Object.freeze(['trace_verified', 'phase_closed']);
+const PHASE_STATES = Object.freeze([
+  'sin_spec', 'spec_validada', 'plan_aprobado', 'red_evidenciado', 'tdd_exento',
+  'implementacion_activa', 'tests_verdes', 'trazabilidad_verificada', 'cerrada',
+]);
+const ROLES = Object.freeze([
+  'evidence_verifier', 'executor', 'human_approver',
+  'independent_verifier', 'spec_validator',
+]);
+const CONFIG_KEYS = [
+  'phaseId', 'planDigest', 'planVersion', 'planPath', 'contextDigest',
+  'contextPath', 'coverageThreshold', 'taskIds', 'requirementsByTask', 'actorBindings',
+];
+const TRANSITION_KEYS = [
+  'event', 'expectedVersion', 'taskId', 'principal', 'evidence', 'grantClaimReceipt',
+];
+const PAYLOAD_KEYS = [
+  'schemaVersion', 'configurationDigest', 'event', 'expectedVersion', 'phaseId',
+  'taskId', 'actorRole', 'principalDigest', 'evidenceDigests', 'grantDigest',
+  'evidenceBaseHead', 'fromState', 'toState', 'planDigest', 'observedPlanDigest',
+  'planVersion', 'approvalDigest', 'operationDigest',
+  'g1Approval',
+];
+const G1_KEYS = [
+  'kind', 'approvalDigest', 'evidenceDigest', 'approverDigest', 'phaseId',
+  'planDigest', 'planBindingDigest', 'issuedAt', 'expiresAt',
+];
+const EVENT_ACTORS = Object.freeze({
+  spec_validated: 'spec_validator',
+  plan_approved: 'human_approver',
+  red_recorded: 'evidence_verifier',
+  tdd_exempted: 'human_approver',
+  implementation_started: 'executor',
+  tests_passed: 'evidence_verifier',
+  trace_verified: 'evidence_verifier',
+  phase_closed: 'independent_verifier',
+  plan_invalidated: 'gate_engine',
+});
+
+function cloneConfig(config) {
+  return freezeDeep(structuredClone(config));
+}
+
+function validateSortedTasks(taskIds) {
+  if (!Array.isArray(taskIds) || taskIds.length === 0 || taskIds.length > 99
+      || taskIds.some((taskId) => !TASK.test(taskId))
+      || taskIds.some((taskId, index) => index > 0 && taskIds[index - 1] >= taskId)) {
+    fail('GATE_CONFIG_INVALID', 'taskIds inválidos o no canónicos');
+  }
+}
+
+function validateActorBindings(bindings) {
+  plainObject(bindings, 'GATE_CONFIG_INVALID', 'actorBindings');
+  exactKeys(bindings, ROLES, 'GATE_CONFIG_INVALID', 'actorBindings');
+  if (Object.values(bindings).some((digest) => !SHA256.test(digest))) {
+    fail('GATE_CONFIG_INVALID', 'actorBindings inválidos');
+  }
+}
+
+function validateRequirementsByTask(requirementsByTask, taskIds) {
+  plainObject(requirementsByTask, 'GATE_CONFIG_INVALID', 'requirementsByTask');
+  exactKeys(requirementsByTask, taskIds, 'GATE_CONFIG_INVALID', 'requirementsByTask');
+  for (const taskId of taskIds) {
+    const requirements = requirementsByTask[taskId];
+    if (!Array.isArray(requirements) || requirements.length === 0
+        || requirements.some((requirement) => !REQUIREMENT.test(requirement))
+        || requirements.some((requirement, index) => (
+          index > 0 && requirements[index - 1] >= requirement
+        ))) {
+      fail('GATE_CONFIG_INVALID', `requisitos inválidos para ${taskId}`);
+    }
+  }
+}
+
+function resolveTrackedPath(workspaceRoot, relativePath, label) {
+  if (typeof relativePath !== 'string' || path.isAbsolute(relativePath)
+      || relativePath.includes('\0')) fail('GATE_CONFIG_INVALID', `${label} inválido`);
+  const root = fs.realpathSync(workspaceRoot);
+  const target = path.resolve(root, relativePath);
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    fail('GATE_CONFIG_INVALID', `${label} fuera del workspace`);
+  }
+  const realTarget = fs.realpathSync(target);
+  if (realTarget !== target || !fs.statSync(realTarget).isFile()) {
+    fail('GATE_CONFIG_INVALID', `${label} ambiguo`);
+  }
+  return realTarget;
+}
+
+function hashStableFile(filePath) {
+  const before = fs.statSync(filePath);
+  const bytes = fs.readFileSync(filePath);
+  const after = fs.statSync(filePath);
+  if (before.dev !== after.dev || before.ino !== after.ino
+      || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+    fail('GATE_ARTIFACT_CHANGED', 'artefacto cambió durante lectura');
+  }
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function validateConfig(rawConfig, workspaceRoot) {
+  plainObject(rawConfig, 'GATE_CONFIG_INVALID', 'configuración gate');
+  exactKeys(rawConfig, CONFIG_KEYS, 'GATE_CONFIG_INVALID', 'configuración gate');
+  if (!IDENTIFIER.test(rawConfig.phaseId) || !IDENTIFIER.test(rawConfig.planVersion)
+      || !SHA256.test(rawConfig.planDigest) || !SHA256.test(rawConfig.contextDigest)
+      || !Number.isInteger(rawConfig.coverageThreshold)
+      || rawConfig.coverageThreshold < 0 || rawConfig.coverageThreshold > 100) {
+    fail('GATE_CONFIG_INVALID', 'bindings de configuración inválidos');
+  }
+  validateSortedTasks(rawConfig.taskIds);
+  validateRequirementsByTask(rawConfig.requirementsByTask, rawConfig.taskIds);
+  validateActorBindings(rawConfig.actorBindings);
+  const config = cloneConfig(rawConfig);
+  return {
+    config,
+    contextPath: resolveTrackedPath(workspaceRoot, config.contextPath, 'contextPath'),
+    planPath: resolveTrackedPath(workspaceRoot, config.planPath, 'planPath'),
+  };
+}
+
+function calculateConfigurationDigest(config) {
+  const invariant = { ...config };
+  delete invariant.planDigest;
+  delete invariant.planVersion;
+  return crypto.createHash('sha256')
+    .update(canonicalizarIJson(invariant), 'utf8').digest('hex');
+}
+
+function calculateApprovalDigest(configurationDigest, phaseId, planDigest, planVersion) {
+  return crypto.createHash('sha256').update(canonicalizarIJson({
+    configurationDigest, phaseId, planDigest, planVersion,
+  }), 'utf8').digest('hex');
+}
+
+function createTaskStates(taskIds) {
+  return Object.fromEntries(taskIds.map((taskId) => [taskId, {
+    state: 'pendiente', g2EvidenceDigest: null, g3EvidenceDigest: null, baseHead: null,
+  }]));
+}
+
+function initialState(config, configurationDigest, revision = config) {
+  return {
+    kind: 'verified-gate-state', schemaVersion: '1.0.0',
+    phaseId: config.phaseId, configurationDigest,
+    planDigest: revision.planDigest, planVersion: revision.planVersion,
+    activeApprovalDigest: revision.approvalDigest || calculateApprovalDigest(
+      configurationDigest, config.phaseId, revision.planDigest, revision.planVersion
+    ),
+    activeG1: null,
+    phaseState: 'sin_spec', version: 0, taskStates: createTaskStates(config.taskIds),
+    planInvalidated: false, observedPlanDigest: null, lastEvent: null,
+  };
+}
+
+function requireTask(state, taskId, expectedState) {
+  const task = state.taskStates[taskId];
+  if (!task || (expectedState && task.state !== expectedState)) {
+    fail('GATE_TRANSITION_INVALID', 'tarea ausente o en estado inválido');
+  }
+  return task;
+}
+
+function applyTaskStart(state, taskId, target) {
+  if (!['plan_aprobado', 'implementacion_activa'].includes(state.phaseState)) {
+    fail('GATE_TRANSITION_INVALID', 'origen de G2 inválido');
+  }
+  requireTask(state, taskId, 'pendiente').state = target;
+  state.phaseState = target;
+}
+
+function applyImplementation(state, taskId) {
+  const task = requireTask(state, taskId);
+  if (!['red_evidenciado', 'tdd_exento'].includes(state.phaseState)
+      || task.state !== state.phaseState) {
+    fail('GATE_TRANSITION_INVALID', 'G2 no precede implementación');
+  }
+  task.state = 'implementacion_activa';
+  state.phaseState = 'implementacion_activa';
+}
+
+function applyTests(state, taskId) {
+  const task = requireTask(state, taskId, 'implementacion_activa');
+  if (state.phaseState !== 'implementacion_activa') {
+    fail('GATE_TRANSITION_INVALID', 'implementación no activa');
+  }
+  task.state = 'tests_verdes';
+  const allGreen = Object.values(state.taskStates).every(({ state: value }) => (
+    value === 'tests_verdes'
+  ));
+  state.phaseState = allGreen ? 'tests_verdes' : 'implementacion_activa';
+}
+
+function applyPhaseTransition(state, payload) {
+  const { event } = payload;
+  const matrix = {
+    spec_validated: ['sin_spec', 'spec_validada'],
+    plan_approved: ['spec_validada', 'plan_aprobado'],
+    trace_verified: ['tests_verdes', 'trazabilidad_verificada'],
+    phase_closed: ['trazabilidad_verificada', 'cerrada'],
+  };
+  const transition = matrix[event];
+  if (!transition || state.phaseState !== transition[0]) {
+    fail('GATE_TRANSITION_INVALID', 'transición de fase inválida');
+  }
+  state.phaseState = transition[1];
+  if (event === 'plan_approved') {
+    state.planDigest = payload.planDigest;
+    state.planVersion = payload.planVersion;
+    state.activeApprovalDigest = payload.approvalDigest;
+    state.activeG1 = structuredClone(payload.g1Approval);
+    state.planInvalidated = false;
+    state.observedPlanDigest = null;
+  }
+}
+
+function applyInvalidation(state, observedPlanDigest) {
+  if (['sin_spec', 'spec_validada'].includes(state.phaseState)) {
+    fail('GATE_TRANSITION_INVALID', 'plan no aprobado para invalidar');
+  }
+  state.phaseState = 'spec_validada';
+  state.taskStates = createTaskStates(Object.keys(state.taskStates));
+  state.planInvalidated = true;
+  state.observedPlanDigest = observedPlanDigest;
+  state.activeG1 = null;
+}
+
+function canPersistInvalidation(state) {
+  return !['sin_spec', 'spec_validada'].includes(state.phaseState);
+}
+
+function applyEvent(previous, payload) {
+  const state = structuredClone(previous);
+  if (payload.event === 'red_recorded') applyTaskStart(state, payload.taskId, 'red_evidenciado');
+  else if (payload.event === 'tdd_exempted') applyTaskStart(state, payload.taskId, 'tdd_exento');
+  else if (payload.event === 'implementation_started') applyImplementation(state, payload.taskId);
+  else if (payload.event === 'tests_passed') applyTests(state, payload.taskId);
+  else if (payload.event === 'plan_invalidated') {
+    applyInvalidation(state, payload.observedPlanDigest);
+  } else applyPhaseTransition(state, payload);
+  state.version += 1;
+  state.lastEvent = payload.event;
+  return state;
+}
+
+function validatePayloadShape(payload) {
+  plainObject(payload, 'GATE_STATE_INVALID', 'evento gate');
+  exactKeys(payload, PAYLOAD_KEYS, 'GATE_STATE_INVALID', 'evento gate');
+  if (payload.schemaVersion !== '1.0.0' || !Object.hasOwn(EVENT_ACTORS, payload.event)
+      || !Number.isInteger(payload.expectedVersion) || payload.expectedVersion < 0
+      || !IDENTIFIER.test(payload.phaseId) || payload.actorRole !== EVENT_ACTORS[payload.event]
+      || !PHASE_STATES.includes(payload.fromState) || !PHASE_STATES.includes(payload.toState)
+      || (payload.taskId !== null && !TASK.test(payload.taskId))
+      || !SHA256.test(payload.configurationDigest) || !SHA256.test(payload.planDigest)
+      || !IDENTIFIER.test(payload.planVersion) || !SHA256.test(payload.approvalDigest)
+      || (payload.operationDigest !== null && !SHA256.test(payload.operationDigest))
+      || !Array.isArray(payload.evidenceDigests)
+      || payload.evidenceDigests.some((digest) => !SHA256.test(digest))
+      || (payload.evidenceBaseHead !== null && !GIT_HASH.test(payload.evidenceBaseHead))) {
+    fail('GATE_STATE_INVALID', 'evento gate futuro o inválido');
+  }
+  validateG1ApprovalShape(payload.g1Approval);
+}
+
+function calculateG1ApprovalDigest(approval) {
+  const unsigned = { ...approval };
+  delete unsigned.approvalDigest;
+  return crypto.createHash('sha256')
+    .update(canonicalizarIJson(unsigned), 'utf8').digest('hex');
+}
+
+function validateG1ApprovalShape(approval) {
+  if (approval === null) return;
+  plainObject(approval, 'GATE_STATE_INVALID', 'approval G1');
+  exactKeys(approval, G1_KEYS, 'GATE_STATE_INVALID', 'approval G1');
+  validarTimestampIso(approval.issuedAt, 'G1 issuedAt');
+  validarTimestampIso(approval.expiresAt, 'G1 expiresAt');
+  if (approval.kind !== 'g1-approval-receipt'
+      || !SHA256.test(approval.approvalDigest)
+      || approval.approvalDigest !== calculateG1ApprovalDigest(approval)
+      || !SHA256.test(approval.evidenceDigest) || !SHA256.test(approval.approverDigest)
+      || !IDENTIFIER.test(approval.phaseId) || !SHA256.test(approval.planDigest)
+      || !SHA256.test(approval.planBindingDigest)
+      || approval.issuedAt >= approval.expiresAt) {
+    fail('GATE_STATE_INVALID', 'approval G1 durable inválida');
+  }
+}
+
+function validateDurableCardinality(payload, config) {
+  const expectedEvidence = payload.event === 'plan_invalidated'
+    ? 0 : (G4_EVENTS.includes(payload.event) ? config.taskIds.length : 1);
+  const taskExpected = TASK_EVENTS.includes(payload.event);
+  if (payload.evidenceDigests.length !== expectedEvidence
+      || taskExpected !== (payload.taskId !== null)
+      || (payload.taskId !== null && !config.taskIds.includes(payload.taskId))) {
+    fail('GATE_STATE_INVALID', 'cardinalidad durable de gate inválida');
+  }
+}
+
+function validateDurableAuthority(payload, config) {
+  const isInvalidation = payload.event === 'plan_invalidated';
+  const expectedPrincipal = isInvalidation ? null : config.actorBindings[payload.actorRole];
+  const expectedGrant = payload.event === 'implementation_started';
+  if (payload.principalDigest !== expectedPrincipal
+      || expectedGrant !== (payload.grantDigest !== null)
+      || expectedGrant !== (payload.operationDigest !== null)
+      || (payload.grantDigest !== null && !SHA256.test(payload.grantDigest))
+      || isInvalidation !== (payload.observedPlanDigest !== null)
+      || (payload.observedPlanDigest !== null && !SHA256.test(payload.observedPlanDigest))) {
+    fail('GATE_STATE_INVALID', 'autoridad durable de gate inválida');
+  }
+  const expectsG1 = payload.event === 'plan_approved';
+  if (expectsG1 !== (payload.g1Approval !== null)) {
+    fail('GATE_STATE_INVALID', 'receipt G1 durable ausente o inesperado');
+  }
+  if (expectsG1 && (payload.g1Approval.evidenceDigest !== payload.evidenceDigests[0]
+      || payload.g1Approval.approverDigest !== payload.principalDigest
+      || payload.g1Approval.phaseId !== payload.phaseId
+      || payload.g1Approval.planDigest !== payload.planDigest
+      || payload.g1Approval.planBindingDigest !== payload.approvalDigest)) {
+    fail('GATE_STATE_INVALID', 'receipt G1 durable no coincide con transición');
+  }
+}
+
+function validateDurableTaskEvidence(payload, state) {
+  const task = payload.taskId === null ? null : state.taskStates[payload.taskId];
+  const expectsBase = TASK_EVENTS.includes(payload.event);
+  if (expectsBase !== (payload.evidenceBaseHead !== null)) {
+    fail('GATE_STATE_INVALID', 'base durable de gate inválida');
+  }
+  if (['implementation_started', 'tests_passed'].includes(payload.event)
+      && (!task || payload.evidenceBaseHead !== task.baseHead)) {
+    fail('GATE_STATE_INVALID', 'base durable no conserva G2');
+  }
+  if (payload.event === 'implementation_started'
+      && payload.evidenceDigests[0] !== task.g2EvidenceDigest) {
+    fail('GATE_STATE_INVALID', 'evidencia durable no conserva G2');
+  }
+}
+
+function validateDurableSemantics(payload, state, config) {
+  validateDurableCardinality(payload, config);
+  validateDurableAuthority(payload, config);
+  validateDurableTaskEvidence(payload, state);
+}
+
+function validateDurableGrant(payload, ledgerState, state) {
+  if (payload.event !== 'implementation_started') return;
+  const claims = ledgerState.events.filter(({ eventType, payload: claim }) => (
+    eventType === 'grant.claimed' && claim.grantDigest === payload.grantDigest
+    && claim.principalDigest === payload.principalDigest
+    && claim.operationDigest === payload.operationDigest
+    && claim.planDigest === payload.planDigest
+    && claim.g1ApprovalDigest === state.activeG1?.approvalDigest
+    && claim.phaseId === payload.phaseId && claim.taskId === payload.taskId
+  ));
+  const consumers = ledgerState.events.filter(({ eventType, payload: event }) => (
+    eventType === 'gate.transition' && event.event === 'implementation_started'
+    && event.grantDigest === payload.grantDigest
+  ));
+  if (claims.length !== 1 || consumers.length !== 1) {
+    fail('GATE_STATE_INVALID', 'grant durable ausente o reutilizada');
+  }
+}
+
+function applyDurableEvidence(state, payload) {
+  if (!payload.taskId) return;
+  const task = state.taskStates[payload.taskId];
+  if (['red_recorded', 'tdd_exempted'].includes(payload.event)) {
+    task.g2EvidenceDigest = payload.evidenceDigests[0];
+    task.baseHead = payload.evidenceBaseHead;
+  }
+  if (payload.event === 'tests_passed') task.g3EvidenceDigest = payload.evidenceDigests[0];
+}
+
+function validateReplayBindings(payload, state, config, configurationDigest) {
+  const revisionMayChange = payload.event === 'plan_approved' && state.planInvalidated;
+  const expectedApprovalDigest = calculateApprovalDigest(
+    configurationDigest, config.phaseId, payload.planDigest, payload.planVersion
+  );
+  if (payload.configurationDigest !== configurationDigest || payload.phaseId !== config.phaseId
+      || (!revisionMayChange && (payload.planDigest !== state.planDigest
+        || payload.planVersion !== state.planVersion))
+      || payload.approvalDigest !== expectedApprovalDigest
+      || payload.expectedVersion !== state.version
+      || payload.actorRole !== EVENT_ACTORS[payload.event]
+      || payload.fromState !== state.phaseState) {
+    fail('GATE_STATE_INVALID', 'binding durable de gate inválido');
+  }
+  validateDurableSemantics(payload, state, config);
+}
+
+function replayState(ledgerState, config, configurationDigest) {
+  const events = ledgerState.events.filter(({ eventType }) => eventType === 'gate.transition');
+  const phaseEvents = [];
+  for (const { payload } of events) {
+    validatePayloadShape(payload);
+    if (payload.phaseId === config.phaseId) phaseEvents.push(payload);
+  }
+  const initialRevision = phaseEvents[0] || config;
+  let state = initialState(config, configurationDigest, initialRevision);
+  for (const payload of phaseEvents) {
+    validateReplayBindings(payload, state, config, configurationDigest);
+    validateDurableGrant(payload, ledgerState, state);
+    const next = applyEvent(state, payload);
+    applyDurableEvidence(next, payload);
+    if (payload.toState !== next.phaseState) {
+      fail('GATE_STATE_INVALID', 'destino durable de gate inválido');
+    }
+    state = next;
+  }
+  const matchesCurrent = state.planDigest === config.planDigest
+    && state.planVersion === config.planVersion;
+  const matchesObservedRevision = state.planInvalidated
+    && state.observedPlanDigest === config.planDigest;
+  if (!matchesCurrent && !matchesObservedRevision) {
+    fail('GATE_STATE_INVALID', 'revisión de PLAN incompatible con proyección');
+  }
+  return state;
+}
+
+function asEvidenceArray(evidence) {
+  return Array.isArray(evidence) ? evidence : [evidence];
+}
+
+function assertEvidenceBindings(evidence, event, taskId, principal, config, authority) {
+  if (!isVerifiedEvidence(evidence)) fail('GATE_EVIDENCE_INVALID', 'evidence no verificada');
+  assertEvidenceCurrent(evidence, authority);
+  const expectedKind = {
+    spec_validated: 'g0', plan_approved: 'g1', red_recorded: 'g2',
+    tdd_exempted: 'g2', implementation_started: 'g2', tests_passed: 'g3',
+    trace_verified: 'g4', phase_closed: 'g4',
+  }[event];
+  const expectedTask = taskId || config.phaseId;
+  const principalMismatch = event !== 'implementation_started'
+    && evidence.principalDigest !== principal.principalDigest;
+  if (evidence.evidenceKind !== expectedKind || principalMismatch
+      || evidence.phaseId !== config.phaseId || evidence.planDigest !== config.planDigest
+      || evidence.taskId !== expectedTask) {
+    fail('GATE_EVIDENCE_INVALID', 'evidence ligada a otra transición');
+  }
+}
+
+function assertEventEvidence(evidence, event, config, configurationDigest, approvalDigest) {
+  const expectedG0 = [config.contextDigest, configurationDigest].sort();
+  const expectedG1 = [config.planDigest, approvalDigest].sort();
+  if (event === 'spec_validated'
+      && JSON.stringify(evidence.sourceHashes) !== JSON.stringify(expectedG0)) {
+    fail('GATE_EVIDENCE_INVALID', 'G0 no liga contexto y configuración');
+  }
+  if (event === 'plan_approved'
+      && JSON.stringify(evidence.sourceHashes) !== JSON.stringify(expectedG1)) {
+    fail('GATE_EVIDENCE_INVALID', 'G1 no liga PLAN, versión y alcance');
+  }
+  if (event === 'red_recorded' && evidence.exitCode === 0) {
+    fail('GATE_EVIDENCE_INVALID', 'G2 RED requiere fallo causal');
+  }
+  const exemptionClaims = [
+    'tdd-exemption', `scope:${evidence.taskId}`,
+  ];
+  const hasReason = evidence.testIds.filter((value) => /^reason:[A-Za-z0-9._:-]+$/u.test(value));
+  const hasRisk = evidence.testIds.filter((value) => /^risk:(?:low|medium|high)$/u.test(value));
+  const exemptionValid = exemptionClaims.every((claim) => evidence.testIds.includes(claim))
+    && hasReason.length === 1 && hasRisk.length === 1 && evidence.testIds.length === 4;
+  if (event === 'tdd_exempted' && (evidence.exitCode !== 0 || !exemptionValid)) {
+    fail('GATE_EVIDENCE_INVALID', 'exención TDD inválida');
+  }
+}
+
+function assertGreenEvidence(evidence, state, taskId, config) {
+  const task = requireTask(state, taskId, 'implementacion_activa');
+  if (evidence.exitCode !== 0 || evidence.baseHead !== task.baseHead
+      || Object.values(evidence.coverage).some((value) => value < config.coverageThreshold)) {
+    fail('GATE_EVIDENCE_INVALID', 'G3 no demuestra tests y cobertura');
+  }
+}
+
+function assertG4Evidence(evidences, config) {
+  const actualTasks = evidences.map(({ taskId }) => taskId).sort();
+  if (JSON.stringify(actualTasks) !== JSON.stringify(config.taskIds)) {
+    fail('GATE_EVIDENCE_INVALID', 'G4 no cubre tareas exactas');
+  }
+  for (const evidence of evidences) {
+    const actualRequirements = evidence.traceability
+      .filter(({ taskId }) => taskId === evidence.taskId)
+      .map(({ requirementId }) => requirementId).sort();
+    const expectedRequirements = config.requirementsByTask[evidence.taskId];
+    if (evidence.exitCode !== 0 || evidence.traceability.length !== expectedRequirements.length
+        || JSON.stringify(actualRequirements) !== JSON.stringify(expectedRequirements)) {
+      fail('GATE_EVIDENCE_INVALID', 'G4 sin trazabilidad exacta REQ×T');
+    }
+  }
+}
+
+function validateEvidenceSet(options, state, config, configurationDigest, authority) {
+  const evidences = asEvidenceArray(options.evidence);
+  const expectedCount = G4_EVENTS.includes(options.event) ? config.taskIds.length : 1;
+  if (evidences.length !== expectedCount) {
+    fail('GATE_EVIDENCE_INVALID', 'cardinalidad de evidence inválida');
+  }
+  for (const evidence of evidences) {
+    assertEvidenceBindings(
+      evidence, options.event,
+      G4_EVENTS.includes(options.event) ? evidence.taskId : options.taskId,
+      options.principal, config, authority
+    );
+  }
+  if (G4_EVENTS.includes(options.event)) assertG4Evidence(evidences, config);
+  else assertEventEvidence(
+    evidences[0], options.event, config, configurationDigest,
+    calculateApprovalDigest(
+      configurationDigest, config.phaseId, config.planDigest, config.planVersion
+    )
+  );
+  if (options.event === 'tests_passed') {
+    assertGreenEvidence(evidences[0], state, options.taskId, config);
+  }
+  return evidences;
+}
+
+function validateTransitionOptions(options) {
+  plainObject(options, 'GATE_OPTIONS_INVALID', 'opciones transición');
+  exactKeys(options, TRANSITION_KEYS, 'GATE_OPTIONS_INVALID', 'opciones transición');
+  if (!Object.hasOwn(EVENT_ACTORS, options.event) || options.event === 'plan_invalidated'
+      || !Number.isInteger(options.expectedVersion) || options.expectedVersion < 0
+      || (options.taskId !== null && !TASK.test(options.taskId))) {
+    fail('GATE_OPTIONS_INVALID', 'transición desconocida');
+  }
+  if (!isVerifiedPrincipal(options.principal)) {
+    fail('GATE_PRINCIPAL_INVALID', 'actor no verificado');
+  }
+}
+
+function validateActor(options, config, authority) {
+  assertPrincipalCurrent(options.principal, authority);
+  const role = EVENT_ACTORS[options.event];
+  if (config.actorBindings[role] !== options.principal.principalDigest) {
+    fail('GATE_ACTOR_INVALID', 'actor no autorizado para transición');
+  }
+  return role;
+}
+
+function validateActiveG1(state, authority, context, event) {
+  if (['spec_validated', 'plan_approved'].includes(event)) return;
+  const approval = state.activeG1;
+  if (!approval || approval.phaseId !== context.config.phaseId
+      || approval.planDigest !== state.planDigest
+      || approval.planBindingDigest !== state.activeApprovalDigest
+      || approval.approverDigest !== context.config.actorBindings.human_approver
+      || approval.issuedAt > authority.observedAt
+      || approval.expiresAt < authority.observedAt) {
+    fail('G1_EXPIRED', 'G1 ausente, fuera de alcance o expirado');
+  }
+}
+
+function validateTaskPresence(event, taskId) {
+  if (TASK_EVENTS.includes(event) !== (taskId !== null)) {
+    fail('GATE_OPTIONS_INVALID', 'taskId incompatible con transición');
+  }
+}
+
+function validateGrant(ledgerState, state, options, singleUseStore, context) {
+  if (options.event !== 'implementation_started') {
+    if (options.grantClaimReceipt !== null) fail('GATE_OPTIONS_INVALID', 'grant inesperada');
+    return null;
+  }
+  const receipt = options.grantClaimReceipt;
+  if (!singleUseStore.isGrantClaimReceipt(receipt)) {
+    fail('GATE_GRANT_INVALID', 'grant claim no verificada');
+  }
+  if (receipt.phaseId !== context.config.phaseId || receipt.taskId !== options.taskId) {
+    fail('GATE_GRANT_INVALID', 'grant claim ligada a otra fase o tarea');
+  }
+  const priorConsumers = ledgerState.events.filter(({ eventType, payload }) => (
+    eventType === 'gate.transition' && payload.event === 'implementation_started'
+    && payload.grantDigest === receipt.grantDigest
+  ));
+  if (priorConsumers.length !== 0) {
+    fail('GATE_GRANT_INVALID', 'grant ya consumida por otra transición');
+  }
+  if (receipt.g1ApprovalDigest !== state.activeG1?.approvalDigest) {
+    fail('GATE_GRANT_INVALID', 'grant claim ligada a otra época G1');
+  }
+  const matches = ledgerState.events.filter(({ eventType, sequence, payload }) => (
+    eventType === 'grant.claimed' && sequence === receipt.sequence
+    && payload.grantDigest === receipt.grantDigest
+    && payload.principalDigest === options.principal.principalDigest
+    && payload.operationDigest === options.principal.operationDigest
+    && payload.planDigest === context.config.planDigest
+    && payload.g1ApprovalDigest === state.activeG1.approvalDigest
+    && payload.phaseId === context.config.phaseId && payload.taskId === options.taskId
+  ));
+  if (matches.length !== 1) fail('GATE_GRANT_INVALID', 'grant claim no durable');
+  return receipt.grantDigest;
+}
+
+function enrichTaskEvidence(next, options, evidences) {
+  if (!options.taskId) return;
+  const task = next.taskStates[options.taskId];
+  if (['red_recorded', 'tdd_exempted'].includes(options.event)) {
+    task.g2EvidenceDigest = evidences[0].evidenceDigest;
+    task.baseHead = evidences[0].baseHead;
+  }
+  if (options.event === 'implementation_started'
+      && task.g2EvidenceDigest !== evidences[0].evidenceDigest) {
+    fail('GATE_EVIDENCE_INVALID', 'implementación no reutiliza G2 vigente');
+  }
+  if (options.event === 'tests_passed') task.g3EvidenceDigest = evidences[0].evidenceDigest;
+}
+
+function createG1Approval(evidence, context) {
+  const base = {
+    kind: 'g1-approval-receipt', evidenceDigest: evidence.evidenceDigest,
+    approverDigest: evidence.principalDigest, phaseId: context.config.phaseId,
+    planDigest: context.config.planDigest, planBindingDigest: context.approvalDigest,
+    issuedAt: evidence.timestamp, expiresAt: evidence.expiresAt,
+  };
+  return {
+    ...base, approvalDigest: crypto.createHash('sha256')
+      .update(canonicalizarIJson(base), 'utf8').digest('hex'),
+  };
+}
+
+function createPayload(state, next, options, role, evidences, grantDigest, context) {
+  return {
+    schemaVersion: '1.0.0', configurationDigest: context.configurationDigest,
+    event: options.event, expectedVersion: state.version, phaseId: context.config.phaseId,
+    taskId: options.taskId, actorRole: role,
+    principalDigest: options.principal.principalDigest,
+    evidenceDigests: evidences.map(({ evidenceDigest }) => evidenceDigest),
+    grantDigest, evidenceBaseHead: options.taskId ? evidences[0].baseHead : null,
+    fromState: state.phaseState, toState: next.phaseState,
+    planDigest: context.config.planDigest, observedPlanDigest: null,
+    planVersion: context.config.planVersion, approvalDigest: context.approvalDigest,
+    operationDigest: options.event === 'implementation_started'
+      ? options.principal.operationDigest : null,
+    g1Approval: options.event === 'plan_approved'
+      ? createG1Approval(evidences[0], context) : null,
+  };
+}
+
+function createInvalidationPayload(state, context, observedPlanDigest) {
+  const options = { event: 'plan_invalidated', taskId: null };
+  const next = applyEvent(state, { ...options, observedPlanDigest });
+  return {
+    schemaVersion: '1.0.0', configurationDigest: context.configurationDigest,
+    event: 'plan_invalidated', expectedVersion: state.version,
+    phaseId: context.config.phaseId, taskId: null, actorRole: 'gate_engine',
+    principalDigest: null, evidenceDigests: [], grantDigest: null,
+    evidenceBaseHead: null,
+    fromState: state.phaseState, toState: next.phaseState,
+    planDigest: state.planDigest, observedPlanDigest,
+    planVersion: state.planVersion, approvalDigest: state.activeApprovalDigest,
+    operationDigest: null,
+    g1Approval: null,
+  };
+}
+
+function appendEntry(ledgerState, payload) {
+  return {
+    expectedSequence: ledgerState.sequence, expectedHeadHash: ledgerState.headHash,
+    eventType: 'gate.transition', payload,
+  };
+}
+
+function createBrandedState(state, owner) {
+  const branded = freezeDeep(structuredClone(state));
+  STATES.set(branded, owner);
+  return branded;
+}
+
+function createReceipt(payload, appendReceipt, owner) {
+  const receipt = freezeDeep({
+    kind: 'gate-transition-receipt', phaseId: payload.phaseId, event: payload.event,
+    taskId: payload.taskId, version: payload.expectedVersion + 1,
+    phaseState: payload.toState, evidenceDigests: payload.evidenceDigests,
+    sequence: appendReceipt.sequence, headHash: appendReceipt.headHash,
+  });
+  RECEIPTS.set(receipt, owner);
+  return receipt;
+}
+
+function buildTransitionAction(options, context, singleUseStore) {
+  let payload;
+  let invalidated = false;
+  const action = (ledgerState, authority) => {
+    const state = replayState(ledgerState, context.config, context.configurationDigest);
+    const observedPlanDigest = hashStableFile(context.planPath);
+    if (observedPlanDigest !== context.config.planDigest) {
+      if (state.planInvalidated || !canPersistInvalidation(state)) {
+        fail('PLAN_DRIFT', 'PLAN cambió sin aprobación vigente');
+      }
+      payload = createInvalidationPayload(state, context, observedPlanDigest);
+      invalidated = true;
+      return appendEntry(ledgerState, payload);
+    }
+    if (options.expectedVersion !== state.version) fail('GATE_CAS_CONFLICT', 'versión cambió');
+    const role = validateActor(options, context.config, authority);
+    validateActiveG1(state, authority, context, options.event);
+    const evidences = validateEvidenceSet(
+      options, state, context.config, context.configurationDigest, authority
+    );
+    const grantDigest = validateGrant(
+      ledgerState, state, options, singleUseStore, context
+    );
+    const next = applyEvent(state, {
+      event: options.event, taskId: options.taskId,
+      planDigest: context.config.planDigest, planVersion: context.config.planVersion,
+      approvalDigest: context.approvalDigest,
+    });
+    enrichTaskEvidence(next, options, evidences);
+    payload = createPayload(state, next, options, role, evidences, grantDigest, context);
+    return appendEntry(ledgerState, payload);
+  };
+  return { action, getPayload: () => payload, wasInvalidated: () => invalidated };
+}
+
+function transition(writer, singleUseStore, owner, context, options) {
+  validateTransitionOptions(options);
+  validateTaskPresence(options.event, options.taskId);
+  const built = buildTransitionAction(options, context, singleUseStore);
+  const appendReceipt = writer.transact(built.action);
+  if (built.wasInvalidated()) fail('PLAN_DRIFT', 'PLAN cambió; estado invalidado');
+  return createReceipt(built.getPayload(), appendReceipt, owner);
+}
+
+function persistInvalidation(writer, context) {
+  writer.transact((ledgerState) => {
+    const state = replayState(ledgerState, context.config, context.configurationDigest);
+    const currentDigest = hashStableFile(context.planPath);
+    if (currentDigest === context.config.planDigest) {
+      fail('GATE_ARTIFACT_CHANGED', 'PLAN cambió durante invalidación');
+    }
+    const payload = createInvalidationPayload(state, context, currentDigest);
+    return appendEntry(ledgerState, payload);
+  });
+}
+
+function readVerifiedState(writer, owner, context) {
+  const inspected = writer.inspect((ledgerState) => ({
+    state: replayState(ledgerState, context.config, context.configurationDigest),
+    observedPlanDigest: hashStableFile(context.planPath),
+  }));
+  if (inspected.observedPlanDigest === context.config.planDigest) {
+    return createBrandedState(inspected.state, owner);
+  }
+  if (inspected.state.planInvalidated) {
+    if (inspected.observedPlanDigest !== inspected.state.observedPlanDigest) {
+      fail('PLAN_DRIFT', 'PLAN volvió a cambiar después de invalidarse');
+    }
+    return createBrandedState(inspected.state, owner);
+  }
+  if (!canPersistInvalidation(inspected.state)) {
+    fail('PLAN_DRIFT', 'PLAN cambió antes de su aprobación');
+  }
+  persistInvalidation(writer, context);
+  return writer.inspect((ledgerState) => createBrandedState(
+    replayState(ledgerState, context.config, context.configurationDigest), owner
+  ));
+}
+
+function createPhaseEngine(writer, singleUseStore, owner, rawConfig, workspaceRoot) {
+  const paths = validateConfig(rawConfig, workspaceRoot);
+  if (hashStableFile(paths.planPath) !== paths.config.planDigest
+      || hashStableFile(paths.contextPath) !== paths.config.contextDigest) {
+    fail('GATE_CONFIG_INVALID', 'artefactos no coinciden con configuración');
+  }
+  const context = Object.freeze({
+    ...paths, configurationDigest: calculateConfigurationDigest(paths.config),
+  });
+  const approvalDigest = calculateApprovalDigest(
+    context.configurationDigest, context.config.phaseId,
+    context.config.planDigest, context.config.planVersion
+  );
+  const boundContext = Object.freeze({ ...context, approvalDigest });
+  const publicPhase = Object.freeze({
+    approvalDigest, configurationDigest: context.configurationDigest,
+    readVerifiedState: () => readVerifiedState(writer, owner, boundContext),
+    transition: (options) => transition(writer, singleUseStore, owner, boundContext, options),
+  });
+  return Object.freeze({ boundContext, publicPhase });
+}
+
+function readAuthorizationGate(phases, ledgerState, authority, operation) {
+  if (!getContractValidators().isVerifiedOperation(operation)
+      || operation.schemaVersion !== '1.1.0') {
+    fail('GATE_OPERATION_INVALID', 'operación de gate inválida');
+  }
+  const context = phases.get(operation.phaseId);
+  if (!context) fail('GATE_PHASE_UNKNOWN', 'fase no registrada');
+  if (hashStableFile(context.planPath) !== context.config.planDigest) {
+    fail('PLAN_DRIFT', 'PLAN cambió durante autorización');
+  }
+  const state = replayState(ledgerState, context.config, context.configurationDigest);
+  if (state.planInvalidated || state.version !== operation.fsmVersion) {
+    fail('GATE_VERSION_MISMATCH', 'estado gate stale o invalidado');
+  }
+  const task = state.taskStates[operation.taskId];
+  if (!task) fail('GATE_TASK_UNKNOWN', 'tarea no registrada');
+  const esLectura = ['filesystem.read', 'memory.read'].includes(operation.capability);
+  if (!esLectura && (task.state !== 'implementacion_activa' || !state.activeG1)) {
+    fail('GATE_NOT_SATISFIED', 'G1/G2 no habilita la operación');
+  }
+  if (state.activeG1 && state.activeG1.expiresAt < authority.observedAt) {
+    fail('GATE_G1_EXPIRED', 'G1 expiró');
+  }
+  const evidence = {
+    configurationDigest: context.configurationDigest,
+    gateVersion: state.version, g1ApprovalDigest: state.activeG1?.approvalDigest || null,
+    g1ExpiresAt: state.activeG1?.expiresAt || null,
+    phaseId: operation.phaseId, planDigest: state.planDigest,
+    planVersion: state.planVersion, taskId: operation.taskId, taskState: task.state,
+  };
+  return freezeDeep({
+    ...evidence,
+    gateAuthorizationDigest: crypto.createHash('sha256')
+      .update(canonicalizarIJson(evidence), 'utf8').digest('hex'),
+  });
+}
+
+function createGateEngine(writer, singleUseStore, workspaceRoot) {
+  const owner = Object.freeze({});
+  const phases = new Map();
+  const publicGateEngine = Object.freeze({
+    isGateReceipt: (value) => RECEIPTS.get(value) === owner,
+    isVerifiedGateState: (value) => STATES.get(value) === owner,
+    openPhase: (config) => {
+      const created = createPhaseEngine(writer, singleUseStore, owner, config, workspaceRoot);
+      const previous = phases.get(created.boundContext.config.phaseId);
+      if (previous
+          && previous.configurationDigest !== created.boundContext.configurationDigest) {
+        fail('GATE_CONFIG_CONFLICT', 'fase registrada con otra configuración');
+      }
+      phases.set(created.boundContext.config.phaseId, created.boundContext);
+      return created.publicPhase;
+    },
+  });
+  const authorizationGateReader = Object.freeze({
+    read: (ledgerState, authority, operation) => (
+      readAuthorizationGate(phases, ledgerState, authority, operation)
+    ),
+  });
+  return Object.freeze({ authorizationGateReader, publicGateEngine });
+}
+
+module.exports = { createGateEngine };