@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/migrar-fase-dominio.js

@@ -1,200 +1,200 @@
-#!/usr/bin/env node
-/**
- * Migración Sprint 2B — añade campos `fase` y `dominio` al frontmatter de los
- * 59 agentes de SWL. Skip si ya los tiene. Inserta antes de `exclusiones:` o
- * al final del frontmatter.
- *
- * Idempotente: corre dos veces sin efectos.
- *
- * Uso:
- *   node scripts/migrar-fase-dominio.js [--dry-run]
- *
- * Origen: análisis de temp/ + propuesta consolidada (mayo 2026).
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-const AGENTES_DIR = path.join(__dirname, '..', 'agentes');
-const DRY_RUN = process.argv.includes('--dry-run');
-
-// Mapeo agente → (fase, dominio). Vocabulario controlado del schema.
-const MAPEO = {
-  'accesibilidad-wcag-swl': ['verify', 'ux'],
-  'arquitecto-swl': ['plan', 'general'],
-  'auto-evolucion-swl': ['learn', 'meta'],
-  'backend-api-swl': ['implement', 'backend'],
-  'backend-csharp-swl': ['implement', 'backend'],
-  'backend-go-swl': ['implement', 'backend'],
-  'backend-java-swl': ['implement', 'backend'],
-  'backend-node-swl': ['implement', 'backend'],
-  'backend-python-swl': ['implement', 'backend'],
-  'backend-rust-swl': ['implement', 'backend'],
-  'backend-workers-swl': ['implement', 'backend'],
-  'cloud-infra-swl': ['release', 'infra'],
-  'consolidador-swl': ['learn', 'meta'],
-  'datos-swl': ['implement', 'data'],
-  'depurador-swl': ['implement', 'general'],
-  'devops-ci-swl': ['release', 'infra'],
-  'disenador-ui-swl': ['plan', 'ux'],
-  'documentador-swl': ['meta', 'docs'],
-  'frontend-angular-swl': ['implement', 'frontend'],
-  'frontend-css-swl': ['implement', 'frontend'],
-  'frontend-react-swl': ['implement', 'frontend'],
-  'frontend-swl': ['implement', 'frontend'],
-  'frontend-tailwind-swl': ['implement', 'frontend'],
-  'implementador-swl': ['implement', 'general'],
-  'investigador-swl': ['discover', 'general'],
-  'investigador-ux-swl': ['discover', 'ux'],
-  'llm-apps-swl': ['implement', 'backend'],
-  'migrador-swl': ['implement', 'data'],
-  'mobile-android-swl': ['implement', 'mobile'],
-  'mobile-cross-swl': ['implement', 'mobile'],
-  'mobile-ios-swl': ['implement', 'mobile'],
-  'mobile-testing-swl': ['verify', 'quality'],
-  'notificador-swl': ['meta', 'meta'],
-  'observabilidad-swl': ['release', 'infra'],
-  'orquestador-swl': ['meta', 'process'],
-  'pagos-swl': ['implement', 'backend'],
-  'perfilador-usuario-swl': ['meta', 'meta'],
-  'planificador-swl': ['plan', 'process'],
-  'producto-prd-swl': ['discover', 'process'],
-  'red-team-swl': ['verify', 'security'],
-  'release-manager-swl': ['release', 'process'],
-  'rendimiento-swl': ['verify', 'quality'],
-  'resolutor-build-swl': ['implement', 'general'],
-  'revisor-angular-swl': ['verify', 'quality'],
-  'revisor-codigo-swl': ['verify', 'quality'],
-  'revisor-csharp-swl': ['verify', 'quality'],
-  'revisor-go-swl': ['verify', 'quality'],
-  'revisor-java-swl': ['verify', 'quality'],
-  'revisor-kotlin-swl': ['verify', 'quality'],
-  'revisor-nextjs-swl': ['verify', 'quality'],
-  'revisor-php-swl': ['verify', 'quality'],
-  'revisor-react-swl': ['verify', 'quality'],
-  'revisor-rust-swl': ['verify', 'quality'],
-  'revisor-seguridad-swl': ['verify', 'security'],
-  'revisor-swift-swl': ['verify', 'quality'],
-  'revisor-typescript-swl': ['verify', 'quality'],
-  'sre-swl': ['release', 'infra'],
-  'tdd-qa-swl': ['verify', 'quality'],
-};
-
-function migrarAgente(nombre) {
-  const archivo = path.join(AGENTES_DIR, `${nombre}.md`);
-  if (!fs.existsSync(archivo)) {
-    return { nombre, status: 'no-existe' };
-  }
-
-  const par = MAPEO[nombre];
-  if (!par) {
-    return { nombre, status: 'sin-mapeo' };
-  }
-  const [fase, dominio] = par;
-
-  const contenido = fs.readFileSync(archivo, 'utf-8');
-
-  // Detectar el frontmatter delimitado por `---` (acepta CRLF y LF)
-  const match = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
-  if (!match) {
-    return { nombre, status: 'sin-frontmatter' };
-  }
-
-  const frontmatter = match[1];
-
-  // Idempotencia: skip si ya tiene fase y dominio
-  const tieneFase = /^fase:\s*\S+/m.test(frontmatter);
-  const tieneDominio = /^dominio:\s*\S+/m.test(frontmatter);
-  if (tieneFase && tieneDominio) {
-    return { nombre, status: 'ya-migrado', fase, dominio };
-  }
-
-  // Insertar antes de `exclusiones:` o al final del frontmatter
-  let nuevoFrontmatter;
-  if (/^exclusiones:/m.test(frontmatter)) {
-    nuevoFrontmatter = frontmatter.replace(
-      /^(exclusiones:)/m,
-      `fase: ${fase}\ndominio: ${dominio}\n$1`
-    );
-  } else {
-    // Sin exclusiones: agregar al final del frontmatter
-    nuevoFrontmatter = frontmatter.trimEnd() + `\nfase: ${fase}\ndominio: ${dominio}\n`;
-  }
-
-  // Preservar el line ending detectado
-  const eol = match[0].includes('\r\n') ? '\r\n' : '\n';
-  const fm = nuevoFrontmatter.replace(/\r\n/g, '\n').replace(/\n/g, eol);
-  const nuevoContenido = contenido.replace(match[0], `---${eol}${fm}${eol}---${eol}`);
-
-  if (DRY_RUN) {
-    return { nombre, status: 'dry-run-ok', fase, dominio };
-  }
-
-  fs.writeFileSync(archivo, nuevoContenido, 'utf-8');
-  return { nombre, status: 'migrado', fase, dominio };
-}
-
-function main() {
-  console.log(`Migrando fase/dominio en agentes${DRY_RUN ? ' (dry-run)' : ''}...\n`);
-
-  const archivosEnDisco = fs
-    .readdirSync(AGENTES_DIR)
-    .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
-    .map((f) => f.replace(/\.md$/, ''));
-
-  const resultados = archivosEnDisco.map(migrarAgente);
-
-  const stats = {
-    migrado: 0,
-    'ya-migrado': 0,
-    'dry-run-ok': 0,
-    'sin-mapeo': [],
-    'sin-frontmatter': [],
-    'no-existe': [],
-  };
-
-  for (const r of resultados) {
-    if (typeof stats[r.status] === 'number') {
-      stats[r.status]++;
-    } else if (Array.isArray(stats[r.status])) {
-      stats[r.status].push(r.nombre);
-    }
-  }
-
-  console.log(`Migrados: ${stats.migrado}`);
-  console.log(`Ya migrados (skip): ${stats['ya-migrado']}`);
-  console.log(`Dry-run OK: ${stats['dry-run-ok']}`);
-  if (stats['sin-mapeo'].length) {
-    console.log(`\n⚠️  Sin mapeo en MAPEO (${stats['sin-mapeo'].length}):`);
-    stats['sin-mapeo'].forEach((n) => console.log(`  - ${n}`));
-  }
-  if (stats['sin-frontmatter'].length) {
-    console.log(`\n❌ Sin frontmatter detectable:`);
-    stats['sin-frontmatter'].forEach((n) => console.log(`  - ${n}`));
-  }
-
-  // Validación: el mapeo debe cubrir todos los agentes en disco
-  const enMapeo = new Set(Object.keys(MAPEO));
-  const enDisco = new Set(archivosEnDisco);
-  const faltanEnMapeo = [...enDisco].filter((n) => !enMapeo.has(n));
-  const sobranEnMapeo = [...enMapeo].filter((n) => !enDisco.has(n));
-
-  if (faltanEnMapeo.length) {
-    console.log(`\n⚠️  Agentes en disco sin entrada en MAPEO:`);
-    faltanEnMapeo.forEach((n) => console.log(`  - ${n}`));
-  }
-  if (sobranEnMapeo.length) {
-    console.log(`\nℹ️  Entradas en MAPEO sin archivo en disco (probablemente renombrados):`);
-    sobranEnMapeo.forEach((n) => console.log(`  - ${n}`));
-  }
-
-  process.exit(stats['sin-frontmatter'].length || faltanEnMapeo.length ? 1 : 0);
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = { MAPEO, migrarAgente };
+#!/usr/bin/env node
+/**
+ * Migración Sprint 2B — añade campos `fase` y `dominio` al frontmatter de los
+ * 59 agentes de SWL. Skip si ya los tiene. Inserta antes de `exclusiones:` o
+ * al final del frontmatter.
+ *
+ * Idempotente: corre dos veces sin efectos.
+ *
+ * Uso:
+ *   node scripts/migrar-fase-dominio.js [--dry-run]
+ *
+ * Origen: análisis de temp/ + propuesta consolidada (mayo 2026).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTES_DIR = path.join(__dirname, '..', 'agentes');
+const DRY_RUN = process.argv.includes('--dry-run');
+
+// Mapeo agente → (fase, dominio). Vocabulario controlado del schema.
+const MAPEO = {
+  'accesibilidad-wcag-swl': ['verify', 'ux'],
+  'arquitecto-swl': ['plan', 'general'],
+  'auto-evolucion-swl': ['learn', 'meta'],
+  'backend-api-swl': ['implement', 'backend'],
+  'backend-csharp-swl': ['implement', 'backend'],
+  'backend-go-swl': ['implement', 'backend'],
+  'backend-java-swl': ['implement', 'backend'],
+  'backend-node-swl': ['implement', 'backend'],
+  'backend-python-swl': ['implement', 'backend'],
+  'backend-rust-swl': ['implement', 'backend'],
+  'backend-workers-swl': ['implement', 'backend'],
+  'cloud-infra-swl': ['release', 'infra'],
+  'consolidador-swl': ['learn', 'meta'],
+  'datos-swl': ['implement', 'data'],
+  'depurador-swl': ['implement', 'general'],
+  'devops-ci-swl': ['release', 'infra'],
+  'disenador-ui-swl': ['plan', 'ux'],
+  'documentador-swl': ['meta', 'docs'],
+  'frontend-angular-swl': ['implement', 'frontend'],
+  'frontend-css-swl': ['implement', 'frontend'],
+  'frontend-react-swl': ['implement', 'frontend'],
+  'frontend-swl': ['implement', 'frontend'],
+  'frontend-tailwind-swl': ['implement', 'frontend'],
+  'implementador-swl': ['implement', 'general'],
+  'investigador-swl': ['discover', 'general'],
+  'investigador-ux-swl': ['discover', 'ux'],
+  'llm-apps-swl': ['implement', 'backend'],
+  'migrador-swl': ['implement', 'data'],
+  'mobile-android-swl': ['implement', 'mobile'],
+  'mobile-cross-swl': ['implement', 'mobile'],
+  'mobile-ios-swl': ['implement', 'mobile'],
+  'mobile-testing-swl': ['verify', 'quality'],
+  'notificador-swl': ['meta', 'meta'],
+  'observabilidad-swl': ['release', 'infra'],
+  'orquestador-swl': ['meta', 'process'],
+  'pagos-swl': ['implement', 'backend'],
+  'perfilador-usuario-swl': ['meta', 'meta'],
+  'planificador-swl': ['plan', 'process'],
+  'producto-prd-swl': ['discover', 'process'],
+  'red-team-swl': ['verify', 'security'],
+  'release-manager-swl': ['release', 'process'],
+  'rendimiento-swl': ['verify', 'quality'],
+  'resolutor-build-swl': ['implement', 'general'],
+  'revisor-angular-swl': ['verify', 'quality'],
+  'revisor-codigo-swl': ['verify', 'quality'],
+  'revisor-csharp-swl': ['verify', 'quality'],
+  'revisor-go-swl': ['verify', 'quality'],
+  'revisor-java-swl': ['verify', 'quality'],
+  'revisor-kotlin-swl': ['verify', 'quality'],
+  'revisor-nextjs-swl': ['verify', 'quality'],
+  'revisor-php-swl': ['verify', 'quality'],
+  'revisor-react-swl': ['verify', 'quality'],
+  'revisor-rust-swl': ['verify', 'quality'],
+  'revisor-seguridad-swl': ['verify', 'security'],
+  'revisor-swift-swl': ['verify', 'quality'],
+  'revisor-typescript-swl': ['verify', 'quality'],
+  'sre-swl': ['release', 'infra'],
+  'tdd-qa-swl': ['verify', 'quality'],
+};
+
+function migrarAgente(nombre) {
+  const archivo = path.join(AGENTES_DIR, `${nombre}.md`);
+  if (!fs.existsSync(archivo)) {
+    return { nombre, status: 'no-existe' };
+  }
+
+  const par = MAPEO[nombre];
+  if (!par) {
+    return { nombre, status: 'sin-mapeo' };
+  }
+  const [fase, dominio] = par;
+
+  const contenido = fs.readFileSync(archivo, 'utf-8');
+
+  // Detectar el frontmatter delimitado por `---` (acepta CRLF y LF)
+  const match = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!match) {
+    return { nombre, status: 'sin-frontmatter' };
+  }
+
+  const frontmatter = match[1];
+
+  // Idempotencia: skip si ya tiene fase y dominio
+  const tieneFase = /^fase:\s*\S+/m.test(frontmatter);
+  const tieneDominio = /^dominio:\s*\S+/m.test(frontmatter);
+  if (tieneFase && tieneDominio) {
+    return { nombre, status: 'ya-migrado', fase, dominio };
+  }
+
+  // Insertar antes de `exclusiones:` o al final del frontmatter
+  let nuevoFrontmatter;
+  if (/^exclusiones:/m.test(frontmatter)) {
+    nuevoFrontmatter = frontmatter.replace(
+      /^(exclusiones:)/m,
+      `fase: ${fase}\ndominio: ${dominio}\n$1`
+    );
+  } else {
+    // Sin exclusiones: agregar al final del frontmatter
+    nuevoFrontmatter = frontmatter.trimEnd() + `\nfase: ${fase}\ndominio: ${dominio}\n`;
+  }
+
+  // Preservar el line ending detectado
+  const eol = match[0].includes('\r\n') ? '\r\n' : '\n';
+  const fm = nuevoFrontmatter.replace(/\r\n/g, '\n').replace(/\n/g, eol);
+  const nuevoContenido = contenido.replace(match[0], `---${eol}${fm}${eol}---${eol}`);
+
+  if (DRY_RUN) {
+    return { nombre, status: 'dry-run-ok', fase, dominio };
+  }
+
+  fs.writeFileSync(archivo, nuevoContenido, 'utf-8');
+  return { nombre, status: 'migrado', fase, dominio };
+}
+
+function main() {
+  console.log(`Migrando fase/dominio en agentes${DRY_RUN ? ' (dry-run)' : ''}...\n`);
+
+  const archivosEnDisco = fs
+    .readdirSync(AGENTES_DIR)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
+    .map((f) => f.replace(/\.md$/, ''));
+
+  const resultados = archivosEnDisco.map(migrarAgente);
+
+  const stats = {
+    migrado: 0,
+    'ya-migrado': 0,
+    'dry-run-ok': 0,
+    'sin-mapeo': [],
+    'sin-frontmatter': [],
+    'no-existe': [],
+  };
+
+  for (const r of resultados) {
+    if (typeof stats[r.status] === 'number') {
+      stats[r.status]++;
+    } else if (Array.isArray(stats[r.status])) {
+      stats[r.status].push(r.nombre);
+    }
+  }
+
+  console.log(`Migrados: ${stats.migrado}`);
+  console.log(`Ya migrados (skip): ${stats['ya-migrado']}`);
+  console.log(`Dry-run OK: ${stats['dry-run-ok']}`);
+  if (stats['sin-mapeo'].length) {
+    console.log(`\n⚠️  Sin mapeo en MAPEO (${stats['sin-mapeo'].length}):`);
+    stats['sin-mapeo'].forEach((n) => console.log(`  - ${n}`));
+  }
+  if (stats['sin-frontmatter'].length) {
+    console.log(`\n❌ Sin frontmatter detectable:`);
+    stats['sin-frontmatter'].forEach((n) => console.log(`  - ${n}`));
+  }
+
+  // Validación: el mapeo debe cubrir todos los agentes en disco
+  const enMapeo = new Set(Object.keys(MAPEO));
+  const enDisco = new Set(archivosEnDisco);
+  const faltanEnMapeo = [...enDisco].filter((n) => !enMapeo.has(n));
+  const sobranEnMapeo = [...enMapeo].filter((n) => !enDisco.has(n));
+
+  if (faltanEnMapeo.length) {
+    console.log(`\n⚠️  Agentes en disco sin entrada en MAPEO:`);
+    faltanEnMapeo.forEach((n) => console.log(`  - ${n}`));
+  }
+  if (sobranEnMapeo.length) {
+    console.log(`\nℹ️  Entradas en MAPEO sin archivo en disco (probablemente renombrados):`);
+    sobranEnMapeo.forEach((n) => console.log(`  - ${n}`));
+  }
+
+  process.exit(stats['sin-frontmatter'].length || faltanEnMapeo.length ? 1 : 0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { MAPEO, migrarAgente };

package/scripts/migrar-gates-legacy.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+/** CLI estricta para migrar un PLAN legacy con autoridad W2 verificable. */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const contract = require('./lib/policy-contract');
+const signed = require('./lib/signed-envelope');
+const { migrateLegacyGate } = require('./lib/legacy-gate-migration');
+
+const REQUIRED = [
+  'fase', 'approval', 'trust-bootstrap', 'kernel-bootstrap',
+  'root-public-key', 'root-key-digest', 'root-key-id',
+];
+const ALLOWED = new Set([
+  ...REQUIRED,
+  ...REQUIRED.map((name) => name.replace(/-/gu, '_')),
+  '_args', 'json', 'verbose',
+]);
+
+function usage() {
+  return 'Uso: swl-ses migrar-gates-legacy --fase=N --approval=<archivo> ' +
+    '--trust-bootstrap=<archivo> --kernel-bootstrap=<archivo> ' +
+    '--root-public-key=<archivo> --root-key-digest=<sha256> --root-key-id=<id>';
+}
+
+function option(options, name) {
+  const value = options[name];
+  return value === true ? null : value;
+}
+
+function validateCliOptions(options) {
+  const unknown = Object.keys(options).filter((key) => !ALLOWED.has(key));
+  const missing = REQUIRED.filter((key) => !option(options, key));
+  if (unknown.length > 0 || missing.length > 0 || !/^0?[1-8]$/u.test(String(options.fase))) {
+    const error = new Error(usage());
+    error.code = 'CLI_USAGE';
+    throw error;
+  }
+}
+
+function readFile(filePath, label) {
+  const resolved = path.resolve(String(filePath));
+  const stat = fs.lstatSync(resolved);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) {
+    throw new Error(`${label} debe ser un archivo regular de máximo 1 MiB`);
+  }
+  return fs.readFileSync(resolved);
+}
+
+function createDependencies(options, workspaceRoot, now) {
+  const rootPublicKey = readFile(options['root-public-key'], 'root-public-key').toString('utf8');
+  const rootVerifier = signed.crearRootVerifier({
+    rootPublicKey,
+    rootKeyDigest: options['root-key-digest'],
+    expectedRootKeyId: options['root-key-id'],
+  });
+  const trustContext = signed.verificarBootstrapReceipt(
+    readFile(options['trust-bootstrap'], 'trust-bootstrap'),
+    { rootVerifier, previousTrustContext: null }
+  );
+  const kernelEnvelope = signed.verificarEnvelope(
+    readFile(options['kernel-bootstrap'], 'kernel-bootstrap'),
+    { trustContext, expectedType: 'integrity', requiredScope: 'kernel:bootstrap', now }
+  );
+  const receipt = contract.verifyKernelBootstrapReceipt(
+    kernelEnvelope, { workspaceRoot, now }
+  );
+  return { dependencies: contract.createKernelDependencies(receipt), trustContext };
+}
+
+function execute(options) {
+  validateCliOptions(options);
+  const workspaceRoot = process.cwd();
+  const now = new Date().toISOString();
+  const authority = createDependencies(options, workspaceRoot, now);
+  return migrateLegacyGate({
+    approvalRaw: readFile(options.approval, 'approval'),
+    dependencies: authority.dependencies,
+    expectedPhaseId: String(options.fase).padStart(2, '0'),
+    trustContext: authority.trustContext,
+    workspaceRoot,
+  });
+}
+
+function migrarGatesLegacyCli(options = {}) {
+  try {
+    const result = execute(options || {});
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  } catch (error) {
+    if (error.code === 'CLI_USAGE') {
+      console.error(error.message);
+      process.exit(2);
+    }
+    throw error;
+  }
+}
+
+if (require.main === module) {
+  const { parsearOpciones } = require('./lib/parsear-opciones');
+  migrarGatesLegacyCli(parsearOpciones(process.argv.slice(2)));
+}
+
+module.exports = migrarGatesLegacyCli;
+module.exports.execute = execute;

package/scripts/publicar-certification-request.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * CLI (wrapper de EFECTO) que publica el `CertificationRequest` de swl-ses:
+ * deriva el commit real (git HEAD) y el `tarballDigest` real (sha256 del tgz de
+ * `npm pack`), arma la matriz Core-3 y escribe el request canónico a disco. La
+ * lógica pura vive en `scripts/lib/w4-publicar-request.js`. T-09, ADR-0053.
+ *
+ * NO se registra como `/swl:*` ni en `modulos.json` (superficie interna w4,
+ * misma excepción documentada que los schemas/scripts w4). Sin efectos al
+ * require: `main(opciones)` sólo actúa al invocarse; `deps` son inyectables.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+
+const { construirRequest } = require('./lib/w4-publicar-request');
+const { canonicalizarIJson } = require('./lib/signed-envelope');
+const { RUNTIMES_CORE3, OS_CORE3 } = require('./lib/w4-runtimes-core3');
+
+/** Producto cartesiano runtime × os con el `model` provisto por runtime. */
+function matrizCore3(modelPorRuntime, osList = OS_CORE3) {
+  if (!modelPorRuntime || typeof modelPorRuntime !== 'object') {
+    throw new Error('modelPorRuntime requerido: { runtime: modelId } por cada runtime Core-3');
+  }
+  const matriz = [];
+  for (const runtime of RUNTIMES_CORE3) {
+    const model = modelPorRuntime[runtime];
+    if (!model) throw new Error(`falta model para el runtime ${runtime}`);
+    for (const os of osList) matriz.push({ runtime, os, model });
+  }
+  return matriz;
+}
+
+function crearError(codigo, mensaje) {
+  const error = new Error(mensaje);
+  error.codigo = codigo;
+  return error;
+}
+
+/**
+ * Asegura el binding commit↔tarballDigest en el origen (C-3): `npm pack`
+ * empaqueta el árbol de TRABAJO, no el objeto git del commit, así que un árbol
+ * sucio produciría un `tarballDigest` que no corresponde al `commit` certificado.
+ * Fail-closed: si hay cambios sin commitear, aborta antes de derivar el par.
+ */
+function asegurarArbolLimpio(deps) {
+  const estado = deps.execFileSync('git', ['status', '--porcelain'], { encoding: 'utf8' }).trim();
+  if (estado !== '') {
+    throw crearError(
+      'TARBALL_COMMIT_BINDING_DIRTY_TREE',
+      'árbol de trabajo sucio: el tarball no correspondería al commit certificado (C-3). '
+        + 'Committea o descarta los cambios antes de publicar el request.'
+    );
+  }
+}
+
+function derivarCommit(deps) {
+  return deps.execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+}
+
+/** sha256 del tarball REAL de `npm pack` (el artefacto que se certifica). */
+function derivarTarballDigest(deps) {
+  const meta = JSON.parse(deps.execFileSync('npm', ['pack', '--json'], { encoding: 'utf8' }));
+  const nombre = Array.isArray(meta) ? meta[0].filename : meta.filename;
+  const bytes = deps.fs.readFileSync(nombre);
+  const digest = crypto.createHash('sha256').update(bytes).digest('hex');
+  deps.fs.rmSync(nombre, { force: true });
+  return digest;
+}
+
+function main(opciones = {}) {
+  const deps = opciones.deps || { execFileSync, fs };
+  // El par {commit, tarballDigest} debe estar bindeado: o se derivan AMBOS del
+  // repo vivo (con árbol limpio), o el llamador provee AMBOS y asume la
+  // responsabilidad del binding. Proveer sólo uno rompe C-3 — el otro se
+  // derivaría de HEAD y podría no corresponder al provisto (Hueco A).
+  const commitProvisto = Boolean(opciones.commit);
+  const digestProvisto = Boolean(opciones.tarballDigest);
+  if (commitProvisto !== digestProvisto) {
+    throw crearError(
+      'TARBALL_COMMIT_BINDING_PARTIAL_OVERRIDE',
+      'commit y tarballDigest deben proveerse juntos o ninguno — la provisión parcial rompe el binding C-3'
+    );
+  }
+  if (!commitProvisto && !digestProvisto) {
+    asegurarArbolLimpio(deps);
+  }
+  const commit = opciones.commit || derivarCommit(deps);
+  const tarballDigest = opciones.tarballDigest || derivarTarballDigest(deps);
+  const matrix = opciones.matrix || matrizCore3(opciones.modelPorRuntime, opciones.osList);
+  const request = construirRequest({ commit, tarballDigest, matrix, entryPoint: opciones.entryPoint });
+  const contenido = canonicalizarIJson(request);
+  const salida = opciones.salida || 'certification-request.json';
+  deps.fs.writeFileSync(salida, contenido, 'utf8');
+  return { request, salida, bytes: contenido };
+}
+
+module.exports = { main, matrizCore3, derivarCommit, derivarTarballDigest, asegurarArbolLimpio, OS_CORE3 };
+
+if (require.main === module) {
+  const modelPorRuntime = {
+    'claude-code': process.env.SWL_MODEL_CLAUDE_CODE || null,
+    'codex-cli': process.env.SWL_MODEL_CODEX_CLI || null,
+    'gemini-cli': process.env.SWL_MODEL_GEMINI_CLI || null,
+  };
+  const faltantes = Object.entries(modelPorRuntime).filter(([, v]) => !v).map(([k]) => k);
+  if (faltantes.length > 0) {
+    process.stderr.write(`Falta el modelo por runtime: define SWL_MODEL_CLAUDE_CODE / SWL_MODEL_CODEX_CLI / SWL_MODEL_GEMINI_CLI (faltan: ${faltantes.join(', ')})\n`);
+    process.exit(2);
+  }
+  const { salida, request } = main({ modelPorRuntime });
+  process.stdout.write(`CertificationRequest escrito en ${salida} (commit ${request.candidate.commit.slice(0, 12)}, ${request.matrix.length} combos)\n`);
+}