gemstack-ai 1.0.1 → 1.1.2

package/src/commands/verify.js

@@ -0,0 +1,311 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+const manifestLib = require('../lib/manifest');
+
+module.exports = async (flags) => {
+    const targetDir = flags.target || process.cwd();
+    logger.info(`Ejecutando verificación integral de Gemstack en: ${targetDir}`);
+
+    let totalErrors = 0;
+    let totalWarnings = 0;
+
+    // 1. Verificación Estructural y Manifest
+    logger.info('--- 1/5 Verificación Estructural (Archivos Base) ---');
+    const manifestPath = fssafe.resolveSafe(targetDir, '.gemstack/manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+        logger.warn('Manifest no encontrado (.gemstack/manifest.json). Es posible que Gemstack no esté inicializado en este directorio.');
+        totalWarnings++;
+    } else {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+            let missing = 0;
+            let modified = 0;
+            (manifest.files || []).forEach(f => {
+                const p = fssafe.resolveSafe(targetDir, f.path);
+                if (!fs.existsSync(p)) {
+                    logger.error(`Archivo requerido faltante: ${f.path}`);
+                    missing++;
+                } else {
+                    const destContent = fs.readFileSync(p);
+                    if (manifestLib.getChecksum(destContent) !== f.checksum) {
+                        modified++;
+                    }
+                }
+            });
+            if (missing === 0 && modified === 0) {
+                logger.ok('Todos los archivos base de Gemstack están presentes e íntegros.');
+            } else {
+                if (missing > 0) totalErrors += missing;
+                if (modified > 0) {
+                    logger.info(`${modified} archivos base modificados localmente (personalización permitida).`);
+                }
+            }
+        } catch (e) {
+            logger.error(`Error leyendo manifest.json: ${e.message}`);
+            totalErrors++;
+        }
+    }
+
+    const giPath = fssafe.resolveSafe(targetDir, '.gitignore');
+    if (fs.existsSync(giPath) && fs.readFileSync(giPath, 'utf8').includes('# Gemstack')) {
+        logger.ok('.gitignore contiene el bloque de Gemstack.');
+    } else {
+        logger.warn('.gitignore no está configurado con las exclusiones de Gemstack.');
+        totalWarnings++;
+    }
+
+    // 2. Verificación de Memoria (handoff.md)
+    logger.info('--- 2/5 Verificación de Memoria e Integridad de Handoff ---');
+    const handoffPath = fssafe.resolveSafe(targetDir, 'handoff.md');
+    if (!fs.existsSync(handoffPath)) {
+        logger.error('handoff.md no existe en la raíz. La memoria de sesión es obligatoria.');
+        totalErrors++;
+    } else {
+        const handoffContent = fs.readFileSync(handoffPath, 'utf8');
+        const requiredSections = [
+            '1. Objetivo',
+            '2. Estado actual',
+            '3. Archivos y cambios',
+            '4. Intentos fallidos',
+            '5. Próximos pasos'
+        ];
+        const missingSections = requiredSections.filter(s => !handoffContent.includes(s));
+        if (missingSections.length > 0) {
+            logger.error(`handoff.md está incompleto. Faltan secciones obligatorias: ${missingSections.join(', ')}`);
+            totalErrors++;
+        } else {
+            logger.ok('handoff.md contiene las 5 secciones obligatorias.');
+        }
+
+        // Regla inmutable: '4. Intentos fallidos' no debe estar eliminada
+        if (!handoffContent.includes('4. Intentos fallidos')) {
+            logger.error('Violación de la Constitución: La sección "4. Intentos fallidos" fue eliminada.');
+            totalErrors++;
+        } else {
+            logger.ok('Sección inmutable "4. Intentos fallidos" preservada.');
+        }
+    }
+
+    // 3. Consistencia de Estado Local (.gemstack/state.json)
+    logger.info('--- 3/5 Verificación de Estado Local (.gemstack/state.json) ---');
+    const statePath = fssafe.resolveSafe(targetDir, '.gemstack/state.json');
+    let loadedState = null;
+    if (!fs.existsSync(statePath)) {
+        logger.warn('.gemstack/state.json no encontrado.');
+        totalWarnings++;
+    } else {
+        try {
+            const { readState } = require('../lib/state');
+            loadedState = readState(targetDir);
+            logger.ok(`Estado local cargado. Fase actual: ${loadedState.current_phase || 'no definida'}`);
+            if (loadedState.active_spec) {
+                const specFile = fssafe.resolveSafe(targetDir, path.join(loadedState.active_spec, 'spec.md'));
+                if (!fs.existsSync(specFile)) {
+                    logger.warn(`Desfase de estado: active_spec apunta a "${loadedState.active_spec}", pero "${specFile}" no existe.`);
+                    totalWarnings++;
+                } else {
+                    logger.ok(`active_spec confirmado: ${loadedState.active_spec}`);
+                }
+            } else {
+                logger.ok('Sin spec activa pendiente (estado limpio o cerrado).');
+            }
+        } catch (e) {
+            logger.error(`.gemstack/state.json tiene formato JSON inválido: ${e.message}`);
+            totalErrors++;
+        }
+    }
+
+    // 4. Consistencia de Arquitectura y Hashes de Fase (Upgrade A)
+    logger.info('--- 4/5 Verificación de Consistencia de Arquitectura y Hashes de Fase ---');
+    if (loadedState && loadedState.active_spec) {
+        try {
+            const { hashFile } = require('../lib/hasher');
+            const {
+                extractContractsBlock,
+                validateContractSchemas,
+                comparePhaseContracts,
+                resolvePhaseInheritance
+            } = require('../lib/contracts');
+            const {
+                reconcileFindings,
+                evaluateAcceptedExceptions,
+                formatDisplayFingerprint
+            } = require('../lib/findings');
+
+            const specFile = fssafe.resolveSafe(targetDir, path.join(loadedState.active_spec, 'spec.md'));
+            const planFile = fssafe.resolveSafe(targetDir, path.join(loadedState.active_spec, 'plan.md'));
+            const tasksFile = fssafe.resolveSafe(targetDir, path.join(loadedState.active_spec, 'tasks.md'));
+
+            if (fs.existsSync(specFile)) {
+                const specRaw = fs.readFileSync(specFile, 'utf8');
+                const specBlock = extractContractsBlock(specRaw);
+
+                if (specBlock.isLegacy) {
+                    logger.ok(`[LEGACY] Feature "${loadedState.active_spec}" opera en modo legacy (sin bloques de contratos).`);
+                } else {
+                    const specContracts = validateContractSchemas(specBlock.contracts);
+                    logger.ok(`[STRUCTURED] ${specContracts.length} contrato(s) base declarados en spec.md.`);
+
+                    // Detección de mutación de spec congelada (VERIFY != FREEZE)
+                    if (loadedState.phase_hashes && loadedState.phase_hashes.spec) {
+                        const currentSpecHash = hashFile(specFile);
+                        if (currentSpecHash !== loadedState.phase_hashes.spec) {
+                            logger.error(`[FROZEN_ARTIFACT_CHANGED] El artefacto congelado spec.md fue mutado sin autorización. Hash esperado: ${loadedState.phase_hashes.spec}, actual: ${currentSpecHash}`);
+                            totalErrors++;
+                        } else {
+                            logger.ok(`Hash congelado de spec.md verificado: ${loadedState.phase_hashes.spec.slice(0, 12)}...`);
+                        }
+                    }
+
+                    // Validación de PLAN si existe
+                    let effectiveUpstream = specContracts;
+                    let planContracts = [];
+                    let violations = [];
+
+                    if (fs.existsSync(planFile)) {
+                        const planRaw = fs.readFileSync(planFile, 'utf8');
+                        const planBlock = extractContractsBlock(planRaw);
+                        if (!planBlock.isLegacy) {
+                            planContracts = validateContractSchemas(planBlock.contracts);
+                            const planViolations = comparePhaseContracts(effectiveUpstream, planContracts, 'plan');
+                            violations.push(...planViolations.map(v => ({ ...v, location: path.join(loadedState.active_spec, 'plan.md') })));
+                            effectiveUpstream = resolvePhaseInheritance(effectiveUpstream, planContracts);
+                        }
+
+                        if (loadedState.phase_hashes && loadedState.phase_hashes.plan) {
+                            const currentPlanHash = hashFile(planFile);
+                            if (currentPlanHash !== loadedState.phase_hashes.plan) {
+                                logger.error(`[FROZEN_ARTIFACT_CHANGED] El artefacto congelado plan.md fue mutado sin autorización. Hash esperado: ${loadedState.phase_hashes.plan}, actual: ${currentPlanHash}`);
+                                totalErrors++;
+                            } else {
+                                logger.ok(`Hash congelado de plan.md verificado: ${loadedState.phase_hashes.plan.slice(0, 12)}...`);
+                            }
+                        }
+                    }
+
+                    // Validación de TASKS si existe
+                    if (fs.existsSync(tasksFile)) {
+                        const tasksRaw = fs.readFileSync(tasksFile, 'utf8');
+                        const tasksBlock = extractContractsBlock(tasksRaw);
+                        if (!tasksBlock.isLegacy) {
+                            const tasksContracts = validateContractSchemas(tasksBlock.contracts);
+                            const tasksViolations = comparePhaseContracts(effectiveUpstream, tasksContracts, 'tasks');
+                            violations.push(...tasksViolations.map(v => ({ ...v, location: path.join(loadedState.active_spec, 'tasks.md') })));
+                        }
+
+                        if (loadedState.phase_hashes && loadedState.phase_hashes.tasks) {
+                            const currentTasksHash = hashFile(tasksFile);
+                            if (currentTasksHash !== loadedState.phase_hashes.tasks) {
+                                logger.error(`[FROZEN_ARTIFACT_CHANGED] El artefacto congelado tasks.md fue mutado sin autorización. Hash esperado: ${loadedState.phase_hashes.tasks}, actual: ${currentTasksHash}`);
+                                totalErrors++;
+                            } else {
+                                logger.ok(`Hash congelado de tasks.md verificado: ${loadedState.phase_hashes.tasks.slice(0, 12)}...`);
+                            }
+                        }
+                    }
+
+                    // Reconciliación de hallazgos y evaluación de excepciones aceptadas vía sidecar de feature
+                    const featureDir = fssafe.resolveSafe(targetDir, loadedState.active_spec);
+                    const { readSidecar, writeSidecarAtomic } = require('../lib/state');
+                    const sidecar = readSidecar(featureDir);
+
+                    // Migración retrocompatible: si state tenía findings o accepted_exceptions, migrarlos al sidecar
+                    const existingFindings = sidecar.historical_findings && sidecar.historical_findings.length > 0
+                        ? sidecar.historical_findings
+                        : (loadedState.findings || []);
+                    const acceptedExceptions = sidecar.accepted_exceptions && sidecar.accepted_exceptions.length > 0
+                        ? sidecar.accepted_exceptions
+                        : (loadedState.accepted_exceptions || []);
+
+                    const reconciled = reconcileFindings(existingFindings, violations);
+                    const currentContext = {
+                        upstreamAcceptedPhaseHash: (loadedState.phase_hashes && loadedState.phase_hashes.spec) || '',
+                        currentComparedPhaseHash: (loadedState.phase_hashes && loadedState.phase_hashes.plan) || '',
+                        normalizedContractRepresentation: JSON.stringify(effectiveUpstream)
+                    };
+                    const evaluated = evaluateAcceptedExceptions(reconciled, acceptedExceptions, currentContext);
+
+                    // Persistir el historial detallado de hallazgos exclusivamente en el sidecar
+                    sidecar.historical_findings = evaluated;
+                    sidecar.accepted_exceptions = acceptedExceptions;
+                    writeSidecarAtomic(featureDir, sidecar);
+
+                    const blockers = evaluated.filter(f => f.is_blocking);
+                    if (blockers.length > 0) {
+                        for (const b of blockers) {
+                            logger.error(`[CONSISTENCY_BLOCKER] Contrato "${b.contractId}" en fase "${b.phase}" (${formatDisplayFingerprint(b.fingerprint)}): ${JSON.stringify(b.delta)}`);
+                        }
+                        totalErrors += blockers.length;
+                    } else {
+                        logger.ok('Verificación de consistencia arquitectónica aprobada (0 bloqueadores).');
+                    }
+                }
+            } else {
+                logger.ok(`Modo legacy: no existe spec.md en ${loadedState.active_spec}`);
+            }
+        } catch (cErr) {
+            logger.error(`Error en verificación de consistencia: ${cErr.message}`);
+            totalErrors++;
+        }
+    } else {
+        logger.ok('Sin spec activa configurada para verificación de contratos.');
+    }
+
+    // 5. Seguridad Local y Anti-Silent Failures en Tests
+    logger.info('--- 5/5 Verificación de Seguridad y Test Runners ---');
+    const envPath = fssafe.resolveSafe(targetDir, '.env');
+    if (fs.existsSync(envPath)) {
+        logger.warn('Archivo .env detectado en el directorio de trabajo. Verifica que esté en .gitignore.');
+        totalWarnings++;
+    }
+
+    const pkgPath = fssafe.resolveSafe(targetDir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            const scripts = pkg.scripts || {};
+            for (const [scriptName, scriptCmd] of Object.entries(scripts)) {
+                if (typeof scriptCmd === 'string') {
+                    // Detección de supresores de error peligrosos en scripts
+                    if (scriptCmd.includes('2>nul') || scriptCmd.includes('2> nul')) {
+                        logger.error(`Falso positivo silencioso detectado en script "${scriptName}": contiene "2>nul", incompatible con PowerShell/Bash y enmascara fallos.`);
+                        logger.info(`Solución: Estandariza el runner multiplataforma usando: "tsx --test <paths>" o "node --test <paths>"`);
+                        totalErrors++;
+                    } else if (scriptCmd.includes('|| true') && scriptName.includes('test')) {
+                        logger.warn(`Script de prueba "${scriptName}" contiene "|| true", lo que ignora fallos de testing.`);
+                        totalWarnings++;
+                    }
+                }
+            }
+            logger.ok('Revisión de scripts de package.json completada.');
+        } catch (e) {
+            logger.warn(`No se pudo parsear package.json: ${e.message}`);
+        }
+    }
+
+    // Ejecución de pruebas si se solicita explícitamente (--run-tests)
+    if (flags.runTests) {
+        logger.info('Ejecutando suite de pruebas (--run-tests activado)...');
+        try {
+            execSync('npm test', { cwd: targetDir, stdio: 'inherit' });
+            logger.ok('Suite de pruebas ejecutada con éxito.');
+        } catch (err) {
+            logger.error('La suite de pruebas falló.');
+            totalErrors++;
+        }
+    }
+
+    // Resumen Final
+    console.log('\n--- Resumen de Auditoría Gemstack ---');
+    if (totalErrors === 0 && totalWarnings === 0) {
+        logger.ok('Auditoría completada sin errores ni advertencias. Todo el sistema está saludable.');
+    } else if (totalErrors === 0) {
+        logger.ok(`Auditoría completada con éxito (${totalWarnings} advertencia(s) menores).`);
+    } else {
+        logger.error(`Auditoría finalizada con ${totalErrors} error(es) y ${totalWarnings} advertencia(s).`);
+        process.exit(1);
+    }
+};

package/src/lib/contracts.js

@@ -0,0 +1,388 @@
+const { normalizeContent } = require('./hasher');
+
+const CANONICAL_CONTRACT_TYPES = [
+  'ENUM_SET',
+  'IDENTITY_TUPLE',
+  'PROVENANCE_RULE',
+  'BOOLEAN_INVARIANT',
+  'BOUNDARY',
+  'ROADMAP_LIMIT'
+];
+
+/**
+ * Extracts and parses the single canonical gemstack-contracts block from markdown.
+ *
+ * @param {string} markdownContent
+ * @returns {{ contracts: Array<object>, isLegacy: boolean }}
+ */
+function extractContractsBlock(markdownContent) {
+  // Check BOM and normalize newlines via hasher
+  const normalized = normalizeContent(markdownContent);
+
+  const lines = normalized.split('\n');
+  const fence = '```';
+  const header = '```gemstack-contracts';
+
+  const blocks = [];
+  let inBlock = false;
+  let blockLines = [];
+
+  for (const line of lines) {
+    if (!inBlock) {
+      if (line.trimEnd() === header) {
+        inBlock = true;
+        blockLines = [];
+      }
+    } else {
+      if (line.trimEnd() === fence) {
+        inBlock = false;
+        blocks.push(blockLines.join('\n'));
+      } else {
+        blockLines.push(line);
+      }
+    }
+  }
+
+  if (blocks.length === 0) {
+    return { contracts: [], isLegacy: true };
+  }
+
+  if (blocks.length > 1) {
+    const err = new Error(`Multiple gemstack-contracts blocks detected (${blocks.length}). Exactly one is permitted.`);
+    err.code = 'CONTRACT_PARSE_ERROR';
+    throw err;
+  }
+
+  const jsonRaw = blocks[0].trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonRaw);
+  } catch (parseErr) {
+    const err = new Error(`Malformed JSON in gemstack-contracts block: ${parseErr.message}`);
+    err.code = 'CONTRACT_PARSE_ERROR';
+    throw err;
+  }
+
+  if (!Array.isArray(parsed)) {
+    const err = new Error('gemstack-contracts content must be a JSON array of contract objects');
+    err.code = 'CONTRACT_INVALID_SHAPE';
+    throw err;
+  }
+
+  return { contracts: parsed, isLegacy: false };
+}
+
+/**
+ * Validates the schema of an array of contract objects and checks for duplicate IDs.
+ *
+ * @param {Array<object>} contractsArray
+ * @returns {Array<object>} Validated contracts
+ */
+function validateContractSchemas(contractsArray) {
+  if (!Array.isArray(contractsArray)) {
+    const err = new Error('Contracts must be an array');
+    err.code = 'CONTRACT_INVALID_SHAPE';
+    throw err;
+  }
+
+  const seenIds = new Set();
+
+  for (const c of contractsArray) {
+    if (!c || typeof c !== 'object') {
+      const err = new Error('Each contract must be a non-null object');
+      err.code = 'CONTRACT_INVALID_SHAPE';
+      throw err;
+    }
+
+    if (typeof c.id !== 'string' || !c.id.trim()) {
+      const err = new Error('Contract missing valid string id');
+      err.code = 'CONTRACT_INVALID_SHAPE';
+      throw err;
+    }
+
+    if (seenIds.has(c.id)) {
+      const err = new Error(`Duplicate contract ID detected: "${c.id}"`);
+      err.code = 'CONTRACT_DUPLICATE_ID';
+      throw err;
+    }
+    seenIds.add(c.id);
+
+    if (!CANONICAL_CONTRACT_TYPES.includes(c.type)) {
+      const err = new Error(`Unknown contract type: "${c.type}" on contract "${c.id}"`);
+      err.code = 'CONTRACT_UNKNOWN_TYPE';
+      throw err;
+    }
+
+    // Type specific validations
+    if (c.type === 'ENUM_SET') {
+      if (!Array.isArray(c.values)) {
+        const err = new Error(`ENUM_SET "${c.id}" requires a values array`);
+        err.code = 'CONTRACT_INVALID_SHAPE';
+        throw err;
+      }
+      const seenVals = new Set();
+      for (const v of c.values) {
+        if (typeof v !== 'string' || !v.trim()) {
+          const err = new Error(`ENUM_SET "${c.id}" contains empty or non-string member`);
+          err.code = 'CONTRACT_INVALID_SHAPE';
+          throw err;
+        }
+        if (seenVals.has(v.trim())) {
+          const err = new Error(`ENUM_SET "${c.id}" contains duplicate value "${v}"`);
+          err.code = 'CONTRACT_INVALID_SHAPE';
+          throw err;
+        }
+        seenVals.add(v.trim());
+      }
+    } else if (c.type === 'IDENTITY_TUPLE') {
+      if (!Array.isArray(c.values)) {
+        const err = new Error(`IDENTITY_TUPLE "${c.id}" requires a values array of dimensions`);
+        err.code = 'CONTRACT_INVALID_SHAPE';
+        throw err;
+      }
+      const seenDims = new Set();
+      for (const d of c.values) {
+        if (typeof d !== 'string' || !d.trim()) {
+          const err = new Error(`IDENTITY_TUPLE "${c.id}" contains invalid dimension string`);
+          err.code = 'CONTRACT_INVALID_SHAPE';
+          throw err;
+        }
+        if (seenDims.has(d.trim())) {
+          const err = new Error(`IDENTITY_TUPLE "${c.id}" contains duplicate dimension "${d}"`);
+          err.code = 'CONTRACT_INVALID_SHAPE';
+          throw err;
+        }
+        seenDims.add(d.trim());
+      }
+    } else if (c.type === 'PROVENANCE_RULE') {
+      if (typeof c.entity !== 'string' || !c.entity.trim()) {
+        const err = new Error(`PROVENANCE_RULE "${c.id}" requires an entity string`);
+        err.code = 'CONTRACT_INVALID_SHAPE';
+        throw err;
+      }
+      if (!Array.isArray(c.values)) {
+        const err = new Error(`PROVENANCE_RULE "${c.id}" requires a values array of provenance fields`);
+        err.code = 'CONTRACT_INVALID_SHAPE';
+        throw err;
+      }
+      for (const f of c.values) {
+        if (typeof f !== 'string' || !f.trim()) {
+          const err = new Error(`PROVENANCE_RULE "${c.id}" contains invalid field string`);
+          err.code = 'CONTRACT_INVALID_SHAPE';
+          throw err;
+        }
+      }
+    } else if (c.type === 'BOOLEAN_INVARIANT') {
+      if (typeof c.value !== 'boolean') {
+        const err = new Error(`BOOLEAN_INVARIANT "${c.id}" requires native boolean value, got ${typeof c.value}`);
+        err.code = 'CONTRACT_INVALID_SHAPE';
+        throw err;
+      }
+    } else if (c.type === 'BOUNDARY') {
+      if (c.value !== 'FORBIDDEN' && c.value !== 'REQUIRED') {
+        const err = new Error(`BOUNDARY "${c.id}" value must be strictly "FORBIDDEN" or "REQUIRED", got "${c.value}"`);
+        err.code = 'CONTRACT_INVALID_SHAPE';
+        throw err;
+      }
+    } else if (c.type === 'ROADMAP_LIMIT') {
+      if (typeof c.value !== 'number' && typeof c.value !== 'string') {
+        const err = new Error(`ROADMAP_LIMIT "${c.id}" value must be a number or string`);
+        err.code = 'CONTRACT_INVALID_SHAPE';
+        throw err;
+      }
+    }
+  }
+
+  return contractsArray;
+}
+
+/**
+ * Normalizes contract representation deterministically.
+ * Arrays of set-like members are trimmed and sorted alphabetically.
+ *
+ * @param {object} contract
+ * @returns {object} Normalized copy
+ */
+function normalizeContract(contract) {
+  const norm = { ...contract };
+  if (norm.type === 'ENUM_SET' || norm.type === 'IDENTITY_TUPLE' || norm.type === 'PROVENANCE_RULE') {
+    if (Array.isArray(norm.values)) {
+      norm.values = norm.values.map(v => typeof v === 'string' ? v.trim() : v).slice().sort();
+    }
+  }
+  return norm;
+}
+
+/**
+ * Resolves cumulative phase inheritance.
+ * Upstream contracts are inherited; downstream additions are merged if not contradicting.
+ *
+ * @param {Array<object>} upstreamContracts
+ * @param {Array<object>} currentContracts
+ * @returns {Array<object>} Consolidated effective contract registry
+ */
+function resolvePhaseInheritance(upstreamContracts = [], currentContracts = []) {
+  const effective = new Map();
+
+  for (const c of upstreamContracts) {
+    effective.set(c.id, normalizeContract(c));
+  }
+
+  for (const c of currentContracts) {
+    // If it's an additive contract not present in upstream
+    if (!effective.has(c.id)) {
+      effective.set(c.id, normalizeContract(c));
+    }
+  }
+
+  return Array.from(effective.values());
+}
+
+/**
+ * Compares current phase contracts against upstream accepted contracts.
+ * Emits one consolidated violation finding per (contractId, phase, violationType).
+ *
+ * @param {Array<object>} upstreamContracts
+ * @param {Array<object>} currentContracts
+ * @param {string} currentPhase - e.g. 'plan' or 'tasks'
+ * @returns {Array<object>} List of violations
+ */
+function comparePhaseContracts(upstreamContracts = [], currentContracts = [], currentPhase = 'plan') {
+  const violations = [];
+  const currentMap = new Map();
+  for (const c of currentContracts) {
+    currentMap.set(c.id, normalizeContract(c));
+  }
+
+  for (const up of upstreamContracts) {
+    const normUp = normalizeContract(up);
+    // If downstream does not redeclare an inherited contract, that is PASS (implicit inheritance)
+    if (!currentMap.has(normUp.id)) {
+      continue;
+    }
+
+    const normCurr = currentMap.get(normUp.id);
+
+    // If contract types differ
+    if (normCurr.type !== normUp.type) {
+      violations.push({
+        code: 'FROZEN_CONTRACT_VIOLATION',
+        contractId: normUp.id,
+        phase: currentPhase,
+        violationType: 'TYPE_MUTATION',
+        delta: {
+          expectedType: normUp.type,
+          observedType: normCurr.type
+        }
+      });
+      continue;
+    }
+
+    // Comparison by type
+    if (normUp.type === 'ENUM_SET') {
+      const upSet = new Set(normUp.values);
+      const currSet = new Set(normCurr.values);
+
+      const added = normCurr.values.filter(v => !upSet.has(v)).sort();
+      const missing = normUp.values.filter(v => !currSet.has(v)).sort();
+
+      if (added.length > 0 || missing.length > 0) {
+        violations.push({
+          code: 'FROZEN_CONTRACT_VIOLATION',
+          contractId: normUp.id,
+          phase: currentPhase,
+          violationType: 'ENUM_SET_MISMATCH',
+          delta: { added, missing }
+        });
+      }
+    } else if (normUp.type === 'IDENTITY_TUPLE') {
+      const upSet = new Set(normUp.values);
+      const currSet = new Set(normCurr.values);
+
+      const added = normCurr.values.filter(d => !upSet.has(d)).sort();
+      const missing = normUp.values.filter(d => !currSet.has(d)).sort();
+
+      if (added.length > 0 || missing.length > 0 || normUp.values.length !== normCurr.values.length) {
+        violations.push({
+          code: 'FROZEN_CONTRACT_VIOLATION',
+          contractId: normUp.id,
+          phase: currentPhase,
+          violationType: 'IDENTITY_TUPLE_MISMATCH',
+          delta: { added, missing }
+        });
+      }
+    } else if (normUp.type === 'PROVENANCE_RULE') {
+      let entityMismatch = normUp.entity !== normCurr.entity;
+      const upSet = new Set(normUp.values);
+      const currSet = new Set(normCurr.values);
+
+      const added = normCurr.values.filter(f => !upSet.has(f)).sort();
+      const missing = normUp.values.filter(f => !currSet.has(f)).sort();
+
+      if (entityMismatch || added.length > 0 || missing.length > 0) {
+        violations.push({
+          code: 'FROZEN_CONTRACT_VIOLATION',
+          contractId: normUp.id,
+          phase: currentPhase,
+          violationType: 'PROVENANCE_MISMATCH',
+          delta: {
+            entityExpected: normUp.entity,
+            entityObserved: normCurr.entity,
+            added,
+            missing
+          }
+        });
+      }
+    } else if (normUp.type === 'BOOLEAN_INVARIANT') {
+      if (normUp.value !== normCurr.value) {
+        violations.push({
+          code: 'FROZEN_CONTRACT_VIOLATION',
+          contractId: normUp.id,
+          phase: currentPhase,
+          violationType: 'BOOLEAN_CONTRADICTION',
+          delta: {
+            expected: normUp.value,
+            observed: normCurr.value
+          }
+        });
+      }
+    } else if (normUp.type === 'BOUNDARY') {
+      if (normUp.value !== normCurr.value) {
+        violations.push({
+          code: 'FROZEN_CONTRACT_VIOLATION',
+          contractId: normUp.id,
+          phase: currentPhase,
+          violationType: 'BOUNDARY_CONTRADICTION',
+          delta: {
+            expected: normUp.value,
+            observed: normCurr.value
+          }
+        });
+      }
+    } else if (normUp.type === 'ROADMAP_LIMIT') {
+      if (normUp.value !== normCurr.value) {
+        violations.push({
+          code: 'FROZEN_CONTRACT_VIOLATION',
+          contractId: normUp.id,
+          phase: currentPhase,
+          violationType: 'ROADMAP_LIMIT_MISMATCH',
+          delta: {
+            expected: normUp.value,
+            observed: normCurr.value
+          }
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+module.exports = {
+  CANONICAL_CONTRACT_TYPES,
+  extractContractsBlock,
+  validateContractSchemas,
+  normalizeContract,
+  resolvePhaseInheritance,
+  comparePhaseContracts
+};