@trycore/spec-build-harness 0.8.4 → 0.10.0

package/commands/build/work.md

@@ -6,7 +6,7 @@ tags: [build-harness, router, classify-and-act, trycore]
 ---
 
 **Router puro.** Decide *qué carril* aplica y **delega** en la skill correspondiente. NO ejecuta el pipeline,
-NO escribe `build-state.json`, NO crea ramas. Codifica como **ruteo** (no política nueva) el *decision gate*
+NO transiciona el estado del slice, NO crea ramas. Codifica como **ruteo** (no política nueva) el *decision gate*
 del micro-change y el default del Release Gate de `METODOLOGIA.md` (§2, §4). Si algo contradice la metodología,
 **gana la metodología**.
 
@@ -28,12 +28,14 @@ Si `NOT_INSTALLED` → ejecuta `trycore-build init` y vuelve.
 
 Aplica las reglas en orden:
 
-0. **¿Greenfield sin caparazón construido?** — si `build-state.json` tiene
-   `project_kind: "greenfield"`, `foundation.required: true` y `foundation.completed_at` sin
-   estampar → **enruta directo a construir la épica caparazón**
-   (`foundation.epic`) por el carril **`building-a-slice`**. Si `foundation.epic` es `null`,
-   enruta a `/build:onboard` (Fase 2c) o a discovery para definirla. Ninguna épica de negocio
-   pasa por delante. Brownfield o `foundation.required` ausente/false → esta regla es N/A.
+0. **¿Greenfield sin caparazón construido?** — consulta los hechos de proyecto con
+   `bash .claude/hooks/build/slice-ops.sh status` (línea `hechos:`): si `project_kind` es
+   `greenfield` y `foundation_done` es `false` → **enruta directo a construir la épica caparazón**
+   por el carril **`building-a-slice`**. `status` no trae **cuál** es esa épica (`foundation.epic`
+   vive hoy en el fichero legacy, leído directo por `dor-dod-gatekeeper`); si no la encuentras o
+   está sin definir, enruta a `/build:onboard` (Fase 2c) o a discovery para definirla. Ninguna épica de
+   negocio pasa por delante. Brownfield, o caparazón no requerida (`foundation_done` ya `true`) →
+   esta regla es N/A.
    Esta regla gatea **aperturas de slice** (épicas): el carril de **mantenimiento**
    (`building-a-micro-change`, regla 1) no se bloquea — un typo/copy/config fix sigue su carril
    normal aun sin caparazón construida.
@@ -70,7 +72,8 @@ modelo/invariantes de datos** → **deja de ser micro-change** y se enruta a **`
 
 ## Guardrails
 
-- **Solo ruteo.** No corres el pipeline, no tocas el estado, no creas ramas: eso es de las skills destino.
+- **Solo ruteo.** No corres el pipeline, no transicionas el estado (ni por `slice-ops.sh` ni por el
+  fichero), no creas ramas: eso es de las skills destino.
 - **Ante la duda, épica.** Nunca degrades un cambio con límite duro a micro-change.
 - **No dupliques gates** ni saltes el orden: las skills destino los gobiernan.
 - **Agnóstico**: vocabulario genérico del arnés; lo específico del dominio entra por `/build:onboard`.

package/config/build-config.template.json

@@ -4,5 +4,9 @@
     "critical_pct": 25,
     "auto_checkpoint": false,
     "stale_seconds": 60
+  },
+  "runtime": {
+    "mode": "legacy",
+    "stale_seconds": 900
   }
 }

package/dist/cli.js

@@ -7,6 +7,7 @@ import { update } from './commands/update.js';
 import { status } from './commands/status.js';
 import { uninstall } from './commands/uninstall.js';
 import { doctor } from './commands/doctor.js';
+import { migrate } from './commands/migrate.js';
 const program = new Command();
 program
     .name('trycore-build')
@@ -24,6 +25,9 @@ program
     .option('--runtime <semver>', 'Semver del runtime (ej. ">=18.18")')
     .option('--prd-path <path>', 'Ruta#ancla del PRD técnico (fuente del allowlist)')
     .option('--yes', 'No interactivo: usa defaults para el stack')
+    .option('--runtime-url <url>', 'URL del Agent Orchestrator Runtime (con --runtime-token, registra el agente)')
+    .option('--runtime-token <token>', 'Token de proyecto emitido por un ADMIN en el hub')
+    .option('--runtime-mode <mode>', 'legacy|dual|runtime tras registrar (default: dual)')
     .action(async (directory, opts) => {
     try {
         await init({
@@ -38,6 +42,9 @@ program
                 prdPath: opts.prdPath,
                 yes: Boolean(opts.yes),
             },
+            runtimeUrl: opts.runtimeUrl,
+            runtimeToken: opts.runtimeToken,
+            runtimeMode: opts.runtimeMode,
         });
     }
     catch (err) {
@@ -99,6 +106,21 @@ program
         process.exit(1);
     }
 });
+program
+    .command('migrate')
+    .description('Prepara el bundle de estado (history/releases/hechos) de build-state.json para que un ADMIN lo importe en el hub. Nunca sube nada.')
+    .argument('[directory]', 'Directorio del proyecto', '.')
+    .option('--out <path>', 'Ruta de salida del bundle (default: .claude/state/migration-bundle.json)')
+    .option('--project-ref <ref>', 'Identificador de proyecto en el hub (default: nombre del directorio)')
+    .action(async (directory, opts) => {
+    try {
+        await migrate({ targetDir: directory, outFile: opts.out, projectRef: opts.projectRef });
+    }
+    catch (err) {
+        console.error('✗ Error:', err.message);
+        process.exit(1);
+    }
+});
 program.parseAsync(process.argv).catch((err) => {
     console.error('✗ Error inesperado:', err);
     process.exit(1);

package/dist/commands/doctor.js

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { targetPaths } from '../lib/paths.js';
+import { runtimeMode, readCredentials, getAgentContext, readLock, outboxStats } from '../lib/runtime-client.js';
 export function hasBinary(bin) {
     if (process.platform === 'win32') {
         return spawnSync('where', [bin], { stdio: 'ignore' }).status === 0;
@@ -87,6 +88,47 @@ export async function doctor(opts) {
     else {
         console.log('Scaffold (Paso 1): — (sin build-state.json; corre `trycore-build init`)');
     }
+    // Runtime [EP-OR-08-D]: conectividad, validez del token, frescura del lock, cola offline.
+    const mode = runtimeMode(targetDir);
+    console.log('');
+    console.log(`Runtime (modo ${mode}):`);
+    if (mode === 'legacy') {
+        console.log('  — legacy: sin conexión al runtime (corre `trycore-build init --runtime-url … --runtime-token …`)');
+    }
+    else {
+        const creds = readCredentials(targetDir);
+        console.log(`  Token:      ${creds.project_token ? '✓ presente' : '✗ falta — corre init con --runtime-token'}`);
+        if (creds.project_token) {
+            const ctx = await getAgentContext(targetDir);
+            if (ctx.status === 200) {
+                console.log('  Conexión:   ✓ el runtime responde');
+            }
+            else if (ctx.status === 401 || ctx.status === 403) {
+                console.log('  Conexión:   ✗ token inválido/revocado — pide uno nuevo al ADMIN');
+            }
+            else if (ctx.status === 0) {
+                console.log('  Conexión:   ⚠ runtime inalcanzable — se trabaja offline con el último lock');
+            }
+            else {
+                console.log(`  Conexión:   ⚠ el runtime respondió ${ctx.status}`);
+            }
+        }
+        const lock = readLock(targetDir);
+        if (lock.manifestHash) {
+            console.log(`  Contexto:   ✓ sincronizado (${lock.fileCount} archivo(s), ${lock.syncedAt ?? 'fecha desconocida'})`);
+        }
+        else {
+            console.log('  Contexto:   ⚠ sin sincronizar aún (se resuelve en la primera sesión Claude)');
+        }
+        const ob = outboxStats(targetDir);
+        if (ob.count > 0) {
+            const ageMin = ob.oldestAgeSeconds !== null ? Math.floor(ob.oldestAgeSeconds / 60) : null;
+            console.log(`  Cola:       ${ob.count} evento(s) pendiente(s) (${(ob.totalBytes / 1024).toFixed(0)} KB${ageMin !== null ? `, el más viejo hace ${ageMin} min` : ''}) — el daemon los despacha`);
+        }
+        else {
+            console.log('  Cola:       vacía');
+        }
+    }
     // Detección de doble canal (CLI settings.json + plugin) [H3]
     const settingsHasHooks = fs.existsSync(t.settingsFile) &&
         /hooks\/build\//.test(fs.readFileSync(t.settingsFile, 'utf8'));

package/dist/commands/init.js

@@ -6,12 +6,14 @@
 // hace el slash command /build:onboard (Claude), NO este binario.
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { ASSETS, readPackageVersion, targetPaths } from '../lib/paths.js';
 import { linkChildren, countChildren, chmodExec } from '../lib/install-engine.js';
 import { upsertMarkedBlock } from '../lib/markers.js';
 import { seedState, seedConfig, seedBuildConfig, stampProjectKind } from '../lib/state-seed.js';
 import { mergeHarnessSettings } from '../lib/settings-merge.js';
 import { captureStack, renderAllowlist } from '../lib/stack-prompt.js';
+import { registerAgent, isPlausibleUrl } from '../lib/runtime-client.js';
 import { checkDeps } from './doctor.js';
 const BEGIN = '<!-- BEGIN trycore-build-harness ';
 const END = '<!-- END trycore-build-harness -->';
@@ -55,6 +57,11 @@ export async function init(opts) {
         chmodExec(t.hooksBuild); // preserva +x [H1] (recorre hooks/build/ incl. lib/)
         chmodExec(t.scriptsLib);
     }
+    // asset-types.json: versionado como schema/README, se refresca en cada init/update.
+    // session-start.sh lo busca en .claude/asset-types.json (protocolo §6; ver su comentario
+    // "la siembra es del sub-slice D").
+    if (fs.existsSync(ASSETS.assetTypes))
+        fs.copyFileSync(ASSETS.assetTypes, t.assetTypesFile);
     // 2) Estado (schema/README versionados; build-state.json vacío solo si falta) [C1]
     const { stateSeeded } = seedState(targetDir);
     const projectKind = stampProjectKind(targetDir);
@@ -75,6 +82,11 @@ export async function init(opts) {
     syncClaudeMdBlock(targetDir, version);
     // 6) .gitignore: lista los assets symlinkeados + estado vivo [H1]
     syncGitignoreBlock(targetDir, linkMode);
+    // 6-bis) Runtime (opcional, [EP-OR-08-D]): con --runtime-url/--runtime-token, registra el
+    // agente (bootstrap, fuera de una sesión Claude) y dispara el primer sync de contexto.
+    // Fail-open: un runtime inalcanzable en init NUNCA aborta la instalación — degrada a
+    // legacy y el registro/sync se reintentan en la primera sesión (session-start.sh).
+    const runtime = await maybeRegisterRuntime(targetDir, t, version, opts);
     // 7) marca de versión
     fs.writeFileSync(t.versionFile, version + '\n', 'utf8');
     // 8) Resumen
@@ -89,10 +101,71 @@ export async function init(opts) {
     console.log(`  Config:    ${configSeeded ? 'stack-allowlist.json sembrado' : 'stack-allowlist.json preservado'}`);
     console.log(`  Config:    ${buildConfigSeeded ? 'build-config.json sembrado' : 'build-config.json preservado'}`);
     console.log(`  Proyecto:  ${projectKind === 'brownfield' ? 'brownfield (épica caparazón N/A)' : projectKind === 'greenfield' ? 'greenfield (épica caparazón requerida — se define en /build:onboard)' : 'indeterminado (se confirma en /build:onboard)'}`);
+    console.log(`  Runtime:   ${runtime}`);
     console.log('');
     console.log('Siguiente paso — abre Claude Code y ejecuta:');
     console.log('  /build:onboard   # parametriza el dominio (PII, capa IA, capa determinista) y escribe memoria');
 }
+/**
+ * Registro del agente CLI + primer sync de contexto, solo si el llamador pasó
+ * --runtime-url/--runtime-token. Fail-open en TODO: nunca lanza, nunca aborta init.
+ * Devuelve una línea de una sola frase para el resumen.
+ */
+async function maybeRegisterRuntime(targetDir, t, version, opts) {
+    if (!opts.runtimeUrl && !opts.runtimeToken) {
+        return 'legacy (sin --runtime-url/--runtime-token; corre `trycore-build init --runtime-url … --runtime-token …` cuando el ADMIN te dé el token)';
+    }
+    if (!opts.runtimeUrl || !opts.runtimeToken) {
+        console.log('  ⚠ runtime: --runtime-url y --runtime-token deben darse juntos — se omite el registro (modo legacy).');
+        return 'legacy (faltó --runtime-url o --runtime-token)';
+    }
+    if (!isPlausibleUrl(opts.runtimeUrl)) {
+        console.log(`  ⚠ runtime: --runtime-url "${opts.runtimeUrl}" no es una URL http(s) válida — se omite el registro (modo legacy).`);
+        return 'legacy (--runtime-url inválida)';
+    }
+    const mode = opts.runtimeMode ?? 'dual';
+    let assetTypes = [];
+    if (fs.existsSync(t.assetTypesFile)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(t.assetTypesFile, 'utf8'));
+            assetTypes = Array.isArray(parsed?.types) ? parsed.types : [];
+        }
+        catch {
+            /* asset-types.json ilegible: se registra con [] — no bloquea */
+        }
+    }
+    const res = await registerAgent(targetDir, { url: opts.runtimeUrl, token: opts.runtimeToken, harnessVersion: version, assetTypes });
+    if (!res.ok) {
+        console.log(`  ⚠ runtime: no se pudo registrar (${res.message ?? 'error desconocido'}). Credenciales guardadas; se reintenta en la primera sesión.`);
+        return `legacy (registro falló: ${res.message ?? 'error desconocido'})`;
+    }
+    // build-config.json ya está sembrado (paso 3) — escribe runtime.mode sin pisar el resto.
+    try {
+        const cfg = JSON.parse(fs.readFileSync(t.buildConfigFile, 'utf8'));
+        cfg.runtime = { ...(cfg.runtime ?? {}), mode };
+        fs.writeFileSync(t.buildConfigFile, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+    }
+    catch {
+        console.log('  ⚠ runtime: no se pudo escribir runtime.mode en build-config.json (queda legacy hasta ajustarlo a mano).');
+        return 'legacy (no se pudo escribir build-config.json)';
+    }
+    console.log(`  ✓ runtime: agente registrado (modo ${mode}).`);
+    // Primer sync de contexto: se delega al script bash ya instalado (mismo protocolo que
+    // usa toda sesión Claude) en vez de reimplementar el algoritmo de sync en TS.
+    const syncScript = path.join(t.hooksBuild, 'context-sync.sh');
+    if (fs.existsSync(syncScript)) {
+        const r = spawnSync('bash', [syncScript], { cwd: targetDir, env: { ...process.env, CLAUDE_PROJECT_DIR: targetDir }, encoding: 'utf8' });
+        if (r.status === 0) {
+            console.log('  ✓ runtime: primer sync de contexto completado.');
+            if (r.stdout?.trim())
+                console.log(r.stdout.trim().split('\n').map((l) => `    ${l}`).join('\n'));
+        }
+        else {
+            console.log('  ⚠ runtime: el primer sync de contexto no terminó limpio — se reintenta en la primera sesión.');
+        }
+    }
+    return `${mode} (agente registrado, primer sync intentado)`;
+}
 function syncClaudeMdBlock(targetDir, version) {
     const t = targetPaths(targetDir);
     if (!fs.existsSync(ASSETS.templateClaudeMd)) {
@@ -142,7 +215,17 @@ function syncGitignoreBlock(targetDir, mode) {
     const isGitRepo = fs.existsSync(path.join(targetDir, '.git'));
     if (!isGitRepo && !fs.existsSync(t.gitignore))
         return;
-    const lines = [GI_BEGIN + ' ───────────────────────', '.claude/state/build-state.json'];
+    const lines = [
+        GI_BEGIN + ' ───────────────────────',
+        '.claude/state/build-state.json',
+        // Credenciales del runtime (token 0600) y sus artefactos derivados [EP-OR-08-D]:
+        // nunca deben poder llegar a un `git add` descuidado, sin importar el modo de link.
+        '.claude/state/runtime.credentials',
+        '.claude/state/context.lock',
+        '.claude/state/runtime-projection.json',
+        '.claude/state/.runtime-http-status',
+        '.claude/state/outbox/',
+    ];
     if (mode === 'symlink') {
         // Los symlinks absolutos a node_modules global se rompen en otra máquina si se commitean.
         lines.push('.claude/agents/build/', '.claude/commands/opsx/', '.claude/commands/build/', '.claude/hooks/build/', '.claude/scripts/lib/');

package/dist/commands/migrate.js

@@ -0,0 +1,48 @@
+// commands/migrate.ts — prepara el bundle normalizado del build-state.json legacy para que
+// un ADMIN lo importe en la consola del hub (docs/superpowers/specs/2026-08-20-cliente-migrate-normalizacion-eventos-design.md).
+// Nunca sube nada: el import es acto de gobierno, igual que el bundle de grafo (Task 13, C).
+import fs from 'node:fs';
+import path from 'node:path';
+import { targetPaths } from '../lib/paths.js';
+import { buildStateBundle } from '../lib/state-bundle.js';
+export async function migrate(opts) {
+    const targetDir = path.resolve(opts.targetDir);
+    const t = targetPaths(targetDir);
+    if (!fs.existsSync(t.stateFile)) {
+        console.error(`✗ No hay build-state.json en ${t.stateFile} — nada que migrar.`);
+        process.exit(1);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(t.stateFile, 'utf8'));
+    }
+    catch (err) {
+        console.error(`✗ build-state.json no parsea como JSON: ${err.message}`);
+        process.exit(1);
+    }
+    const projectRef = opts.projectRef ?? path.basename(targetDir);
+    const bundle = buildStateBundle(raw, projectRef);
+    if (bundle.validation_errors.length > 0) {
+        console.error('✗ El bundle normalizado no pasa la validación local — no se escribe el fichero.');
+        for (const e of bundle.validation_errors)
+            console.error(`    ✗ ${e}`);
+        process.exit(1);
+    }
+    bundle.generated_at = new Date().toISOString();
+    const outFile = opts.outFile ? path.resolve(opts.outFile) : path.join(t.stateDir, 'migration-bundle.json');
+    fs.mkdirSync(path.dirname(outFile), { recursive: true });
+    fs.writeFileSync(outFile, JSON.stringify(bundle, null, 2) + '\n', 'utf8');
+    console.log(`✓ Bundle de estado preparado: ${outFile}`);
+    console.log(`  ${bundle.history.length} slice(s) de historial · ${bundle.releases.length} release(s) · ` +
+        `${bundle.fronts.length} front(s) · ${bundle.facts.length} hecho(s) de proyecto · ${bundle.unmapped.length} entrada(s) no mapeable(s)`);
+    if (bundle.warnings.length > 0) {
+        console.log('');
+        console.log('  Avisos (no bloquean; corrígelos en discovery si aplica):');
+        for (const w of bundle.warnings)
+            console.log(`    ⚠ ${w}`);
+    }
+    console.log('');
+    console.log('Este fichero NO se sube automáticamente: es un acto de gobierno. Entrégalo a un');
+    console.log('ADMIN con esta instrucción literal: «súbelo en la consola del hub, pantalla de');
+    console.log('import histórico del proyecto». El import es idempotente y reanuda si falló a medias.');
+}

package/dist/commands/status.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { readPackageVersion, targetPaths, PACKAGE_ROOT } from '../lib/paths.js';
 import { countChildren } from '../lib/install-engine.js';
 import { hasBinary } from './doctor.js';
+import { runtimeMode, getAgentContext, readProjection, readLock } from '../lib/runtime-client.js';
 export async function status(opts) {
     const targetDir = path.resolve(opts.targetDir);
     const t = targetPaths(targetDir);
@@ -32,6 +33,39 @@ export async function status(opts) {
     console.log('Requisitos externos:');
     console.log(`  openspec:   ${hasBinary('openspec') ? '✓' : '✗ falta (npm i -g @fission-ai/openspec)'}`);
     console.log(`  python3:    ${hasBinary('python3') ? '✓' : '✗ falta'}`);
+    // Runtime [EP-OR-08-D]: en dual/runtime, la fuente preferida es la caché de proyección
+    // (la normaliza agent-context.sh — esta CLI no duplica esa lógica, solo lee y pinguea).
+    const mode = runtimeMode(targetDir);
+    if (mode !== 'legacy') {
+        console.log('');
+        console.log(`Runtime (modo ${mode}):`);
+        const ctx = await getAgentContext(targetDir);
+        console.log(`  Conexión:     ${ctx.status === 200 ? '✓' : ctx.status === 0 ? '⚠ inalcanzable (trabajando offline)' : `⚠ respondió ${ctx.status}`}`);
+        const proj = readProjection(targetDir);
+        if (proj.fetched_at) {
+            const ageS = Math.max(0, Math.floor((Date.now() - Date.parse(String(proj.fetched_at))) / 1000));
+            console.log(`  Proyección:   ✓ v${proj.context?.version ?? '?'} (hace ${ageS}s${ageS > 900 ? ' — ⚠ stale' : ''})`);
+            const slice = proj.active_slice;
+            if (slice) {
+                console.log(`  Slice activo: ${slice.epic_code ?? '?'} (fase ${slice.phase ?? '?'})`);
+            }
+            else {
+                console.log('  Slice activo: ninguno');
+            }
+            const nudges = Array.isArray(proj.nudges) ? proj.nudges : [];
+            if (nudges.length > 0)
+                console.log(`  Nudges:       ${nudges.length} pendiente(s)`);
+        }
+        else {
+            console.log('  Proyección:   — sin caché aún (se resuelve en la primera sesión Claude)');
+        }
+        const lock = readLock(targetDir);
+        console.log(`  Contexto:     ${lock.manifestHash ? `✓ sincronizado (${lock.fileCount} archivo(s))` : '⚠ sin sincronizar'}`);
+        if (mode === 'runtime') {
+            console.log('══════════════════════════════════════════════════════');
+            return;
+        }
+    }
     // Estado del arnés
     if (fs.existsSync(t.stateFile)) {
         try {

package/dist/lib/normalize.js

@@ -0,0 +1,276 @@
+// normalize.ts — normaliza el build-state.json legacy a la forma de eventos
+// del catálogo v2 que exige POST /orchestrator/projects/{id}/import/bundle
+// (docs/superpowers/specs/2026-08-20-cliente-migrate-normalizacion-eventos-design.md).
+//
+// Catálogo v2 embebido desde trycore-ia-hub/backend/app/modules/orchestrator/
+// event_catalog.py (SCHEMAS/TIPOS_POR_AGREGADO), copiado 2026-08-20. Si el
+// catálogo del hub cambia, esta copia se desincroniza — no hay forma de
+// importarlo en build-time entre repos distintos.
+export const PHASE_ORDER = [
+    'dor', 'change', 'red', 'green', 'refactor', 'smoke', 'api', 'data', 'dod', 'pr', 'archived',
+];
+export const EVENT_TYPES_BY_AGGREGATE = {
+    slice: new Set([
+        'slice_opened', 'phase_advanced', 'gate_verdict', 'wiring_checklist_seeded',
+        'wiring_item_updated', 'progress_noted', 'slice_archived', 'slice_parked', 'slice_cancelled',
+    ]),
+    release: new Set(['release_opened', 'release_gate_verdict', 'release_closed']),
+    front: new Set(['front_opened', 'front_member_added', 'front_drained', 'front_closed']),
+};
+const SECOND_MS = 1000;
+const EPOCH_ISO = new Date(0).toISOString();
+function toIso(value, fallback) {
+    if (typeof value === 'string') {
+        const d = new Date(value);
+        if (!Number.isNaN(d.getTime()))
+            return d.toISOString();
+    }
+    return fallback;
+}
+function ensureStrictlyIncreasing(events) {
+    let prevMs = -Infinity;
+    return events.map((ev) => {
+        let ms = new Date(ev.occurred_at).getTime();
+        if (Number.isNaN(ms) || ms <= prevMs)
+            ms = prevMs === -Infinity ? Date.parse(EPOCH_ISO) : prevMs + SECOND_MS;
+        prevMs = ms;
+        return { ...ev, occurred_at: new Date(ms).toISOString() };
+    });
+}
+function openingEvent(entry, epicCode) {
+    return {
+        event_type: 'slice_opened',
+        payload: { epic_code: epicCode },
+        occurred_at: toIso(entry.updated_at, EPOCH_ISO),
+    };
+}
+function phaseAdvancedEvents(entry) {
+    const finalPhase = typeof entry.phase === 'string' ? entry.phase : null;
+    const idx = finalPhase ? PHASE_ORDER.indexOf(finalPhase) : -1;
+    if (idx <= 0)
+        return [];
+    const upTo = finalPhase === 'archived' ? PHASE_ORDER.indexOf('pr') : idx;
+    const anchor = toIso(entry.updated_at, EPOCH_ISO);
+    const events = [];
+    for (let i = 1; i <= upTo; i++) {
+        events.push({ event_type: 'phase_advanced', payload: { to: PHASE_ORDER[i] }, occurred_at: anchor });
+    }
+    return events;
+}
+function gateVerdictEvents(entry) {
+    const gates = entry.gates && typeof entry.gates === 'object' ? entry.gates : {};
+    const anchor = toIso(entry.updated_at, EPOCH_ISO);
+    return Object.entries(gates)
+        .filter(([, v]) => v === true)
+        .map(([gate]) => ({ event_type: 'gate_verdict', payload: { gate, verdict: 'PASS' }, occurred_at: anchor }));
+}
+function wiringEvents(entry) {
+    const checklist = Array.isArray(entry.wiring_checklist) ? entry.wiring_checklist : [];
+    if (checklist.length === 0)
+        return [];
+    const anchor = toIso(entry.updated_at, EPOCH_ISO);
+    const events = [
+        {
+            event_type: 'wiring_checklist_seeded',
+            payload: {
+                items: checklist.map((item) => ({
+                    item_id: String(item.item_id ?? item.id ?? ''),
+                    kind: String(item.kind ?? 'unknown'),
+                    ref: String(item.ref ?? ''),
+                })),
+            },
+            occurred_at: anchor,
+        },
+    ];
+    for (const item of checklist) {
+        if (typeof item.status === 'string') {
+            events.push({
+                event_type: 'wiring_item_updated',
+                payload: { item_id: String(item.item_id ?? item.id ?? ''), status: item.status },
+                occurred_at: anchor,
+            });
+        }
+    }
+    return events;
+}
+function progressNotedEvents(entry) {
+    const log = Array.isArray(entry.progress_log) ? entry.progress_log : [];
+    const fallback = toIso(entry.updated_at, EPOCH_ISO);
+    return log
+        .filter((p) => typeof p === 'object' && p !== null && typeof p.note === 'string')
+        .map((p) => ({ event_type: 'progress_noted', payload: { note: p.note }, occurred_at: toIso(p.at, fallback) }));
+}
+function bodyEvents(entry) {
+    return [...phaseAdvancedEvents(entry), ...gateVerdictEvents(entry), ...wiringEvents(entry), ...progressNotedEvents(entry)];
+}
+function closingEvent(entry) {
+    const anchor = toIso(entry.updated_at, EPOCH_ISO);
+    if (entry.phase === 'archived')
+        return { event_type: 'slice_archived', payload: {}, occurred_at: anchor };
+    if (entry.status === 'parked') {
+        return { event_type: 'slice_parked', payload: { reason: String(entry.reason ?? entry.notes ?? 'sin motivo registrado') }, occurred_at: anchor };
+    }
+    if (entry.status === 'cancelled')
+        return { event_type: 'slice_cancelled', payload: {}, occurred_at: anchor };
+    return null;
+}
+/**
+ * Fusiona todas las entradas de `history[]` de UNA épica en una sola secuencia
+ * continua: un único slice_opened al inicio, un único cierre al final (de la
+ * entrada de MAYOR índice, nunca por updated_at — spec §6.1). El reducer del
+ * servidor prohíbe reabrir un slice tras un cierre, así que las entradas
+ * intermedias solo aportan su cuerpo (fases/gates/wiring/progreso), sin abrir
+ * ni cerrar.
+ */
+export function normalizeHistoryGroup(epicCode, entries) {
+    const objs = entries.filter((e) => typeof e === 'object' && e !== null && !Array.isArray(e));
+    if (objs.length === 0)
+        return null;
+    const events = [openingEvent(objs[0], epicCode)];
+    objs.forEach((entry, i) => {
+        events.push(...bodyEvents(entry));
+        if (i === objs.length - 1) {
+            const closing = closingEvent(entry);
+            if (closing)
+                events.push(closing);
+        }
+    });
+    return { epic_code: epicCode, events: ensureStrictlyIncreasing(events), normalized: true };
+}
+/**
+ * Agrupa history[] por épica preservando el ORDEN DE ÍNDICE de aparición
+ * (nunca por updated_at — spec §6.1) y fusiona cada grupo en una entrada.
+ * Entradas sin `epica` reconocible caen a unmapped, sin bloquear a las demás.
+ */
+export function normalizeHistory(historyRaw) {
+    const groups = new Map();
+    const order = [];
+    const unmapped = [];
+    historyRaw.forEach((raw, i) => {
+        const obj = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw : null;
+        const epicCode = obj && typeof obj.epica === 'string' ? obj.epica : null;
+        if (!epicCode) {
+            unmapped.push({ source_key: `history[${i}]`, original: raw, occurred_at: toIso(obj?.updated_at, EPOCH_ISO) });
+            return;
+        }
+        if (!groups.has(epicCode)) {
+            groups.set(epicCode, []);
+            order.push(epicCode);
+        }
+        groups.get(epicCode).push(obj);
+    });
+    const entries = [];
+    for (const epicCode of order) {
+        const merged = normalizeHistoryGroup(epicCode, groups.get(epicCode));
+        if (merged)
+            entries.push(merged);
+    }
+    return { entries, unmapped };
+}
+function releaseEvents(release, key) {
+    const anchor = toIso(release.created_at, EPOCH_ISO);
+    const epicCodes = Array.isArray(release.epicas) ? release.epicas.map(String) : [];
+    const events = [
+        { event_type: 'release_opened', payload: { release_line: key, epic_codes: epicCodes }, occurred_at: anchor },
+    ];
+    const gates = release.gates && typeof release.gates === 'object' ? release.gates : {};
+    for (const [gate, verdict] of Object.entries(gates)) {
+        events.push({ event_type: 'release_gate_verdict', payload: { gate, verdict: verdict === true ? 'PASS' : 'FAIL' }, occurred_at: anchor });
+    }
+    if (release.status === 'failed' || release.status === 'passed') {
+        events.push({
+            event_type: 'release_closed',
+            payload: { status: release.status === 'failed' ? 'FAILED' : 'PASSED', epic_codes: epicCodes },
+            occurred_at: anchor,
+        });
+    }
+    const notes = Array.isArray(release.notes) ? release.notes : [];
+    const unmapped = notes.map((note, i) => ({
+        source_key: `releases[${key}].notes[${i}]`,
+        original: note,
+        occurred_at: anchor,
+    }));
+    return { events: ensureStrictlyIncreasing(events), unmapped };
+}
+/** `notes[]` de un release no tiene tipo en el catálogo del agregado `release`
+ * (event_catalog.py no declara ninguno) — se preserva en `unmapped[]` en vez
+ * de descartarse (spec §7: "nada se pierde, nada bloquea"). Mismo principio
+ * para una entrada sin `release_id` utilizable como key: cae a unmapped en
+ * vez de descartarse en silencio (consistente con normalizeHistory). */
+export function normalizeReleases(releasesRaw) {
+    const entries = [];
+    const unmapped = [];
+    releasesRaw.forEach((raw, i) => {
+        const obj = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw : null;
+        const key = obj && typeof obj.release_id === 'string' ? obj.release_id : null;
+        if (!obj || !key) {
+            unmapped.push({ source_key: `releases[${i}]`, original: raw, occurred_at: toIso(obj?.created_at, EPOCH_ISO) });
+            return;
+        }
+        const { events, unmapped: relUnmapped } = releaseEvents(obj, key);
+        entries.push({ key, events, normalized: true });
+        unmapped.push(...relUnmapped);
+    });
+    return { entries, unmapped };
+}
+export function normalizeFront(frontRaw) {
+    if (typeof frontRaw !== 'object' || frontRaw === null)
+        return null;
+    const front = frontRaw;
+    const anchor = toIso(front.opened_at, EPOCH_ISO);
+    const members = Array.isArray(front.members) ? front.members : [];
+    const events = [
+        {
+            event_type: 'front_opened',
+            payload: {
+                members: members.map((m) => String(m.epica ?? '')),
+                merge_order: Array.isArray(front.merge_order) ? front.merge_order : [],
+                asignaciones: members.map((m) => ({
+                    epic_code: String(m.epica ?? ''),
+                    worktree: String(m.worktree ?? ''),
+                    assignee: String(m.assignee ?? ''),
+                })),
+            },
+            occurred_at: anchor,
+        },
+    ];
+    if (front.status === 'drained')
+        events.push({ event_type: 'front_drained', payload: {}, occurred_at: anchor });
+    else if (front.status === 'closed')
+        events.push({ event_type: 'front_closed', payload: {}, occurred_at: anchor });
+    return { key: 'parallel_front', events: ensureStrictlyIncreasing(events), normalized: true };
+}
+const FACT_KEYS = ['scaffold', 'design_source', 'project_kind', 'project_kind_source', 'foundation', 'harness_phase'];
+export function normalizeFacts(raw, fallbackAt) {
+    const facts = [];
+    for (const key of FACT_KEYS) {
+        if (!(key in raw))
+            continue;
+        const value = raw[key];
+        const normalizedValue = typeof value === 'boolean' || typeof value === 'string' ? value : value === null || value === undefined ? null : JSON.stringify(value);
+        facts.push({ fact: key, value: normalizedValue, occurred_at: fallbackAt, normalized: true });
+    }
+    return facts;
+}
+function checkSequence(errors, aggregate, key, events) {
+    if (events.length === 0)
+        errors.push(`${key}: sin eventos`);
+    for (const ev of events) {
+        if (!EVENT_TYPES_BY_AGGREGATE[aggregate].has(ev.event_type)) {
+            errors.push(`${key}: event_type "${ev.event_type}" no existe en el catálogo del agregado "${aggregate}"`);
+        }
+        if (Number.isNaN(new Date(ev.occurred_at).getTime())) {
+            errors.push(`${key}: occurred_at inválido: "${ev.occurred_at}"`);
+        }
+    }
+}
+/** Validación local previa al volcado (spec §9): mismo catálogo que valida el
+ * servidor, sin replicar la forma de payload campo a campo (eso lo cubre el
+ * test golden, no una revalidación en runtime). */
+export function validateNormalizedBundle(bundle) {
+    const errors = [];
+    bundle.history.forEach((h) => checkSequence(errors, 'slice', `history[${h.epic_code}]`, h.events));
+    bundle.releases.forEach((r) => checkSequence(errors, 'release', `releases[${r.key}]`, r.events));
+    bundle.fronts.forEach((f) => checkSequence(errors, 'front', `fronts[${f.key}]`, f.events));
+    return errors;
+}