@nac3/forge-cli 1.15.0 → 1.16.1

package/dist/commands/audit-persistence.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `yf audit persistence [path]` -- la interfaz de persistencia es ASINCRONICA.
+ *
+ * El candado que le faltaba a Forge, y la razon esta en ADIP-Kikan (Pablo,
+ * 13-oct-2026): el brain construyo la capa de repositorio bien y persiste en
+ * MariaDB desde el primer commit, pero definio la interfaz SINCRONICA. Eso
+ * obligo al store de MariaDB a mantener el working set en RAM para servir
+ * lecturas sincronas, y de ahi el esquema degenero en una tabla generica de
+ * JSON. Una firma de funcion, 1.543 puntos de deuda y nueve slices de
+ * conversion.
+ *
+ * El analisis vive en `src/audit/persistence_async.ts`, puro y con bateria.
+ * Este archivo es solo el recorrido del arbol y el reporte.
+ *
+ * Corre sobre CUALQUIER proyecto -- recien nacido o heredado -- y no necesita
+ * configuracion: el detector reconoce un store por su nombre, por su carpeta o
+ * por su forma.
+ *
+ * ASCII-only.
+ */
+import type { Command } from 'commander';
+export interface AuditPersistenceOptions {
+    json?: boolean;
+}
+export interface Recolectado {
+    fuentes: Array<[string, string]>;
+    /** Salteados por generados/minificados. Se REPORTAN: un salteo invisible es
+     *  un agujero del mismo tipo que un ilegible que cuenta cero. */
+    generados: string[];
+}
+export declare function recolectarFuentes(raiz: string): Recolectado;
+export declare function registerAuditPersistenceCommand(program: Command): void;
+//# sourceMappingURL=audit-persistence.d.ts.map

package/dist/commands/audit-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-persistence.d.ts","sourceRoot":"","sources":["../../src/commands/audit-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwCzC,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjC;qEACiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA4B3D;AAoED,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyBtE"}

package/dist/commands/audit-persistence.js

@@ -0,0 +1,173 @@
+import path from 'node:path';
+import { readdirSync, statSync, readFileSync } from 'node:fs';
+import { c, header } from '../ui/colors.js';
+import { analizar, aprueba } from '../audit/persistence_async.js';
+const OMITIR = new Set([
+    'node_modules', 'dist', 'coverage', '.git', '.next', 'build', '.expo',
+    '.turbo', 'out', 'vendor', 'third_party', '__pycache__', 'site-packages',
+    'bower_components', '.cache', '.tox', 'target', '.gradle', '.idea',
+]);
+/* Los entornos virtuales de Python se llaman `.venv`, `venv`, `.venv_test`,
+ * `env`... y adentro traen el chromium de Playwright con sus bundles. */
+const OMITIR_PREFIJO = ['.venv', 'venv', '.env-', 'env-'];
+const EXT = /\.(js|mjs|cjs|ts|tsx)$/;
+/* Las baterias quedan afuera: un doble de test SINCRONICO es legitimo -- lo que
+ * no puede ser sincronico es el store del que depende el producto. */
+const ES_TEST = /\.(test|spec)\.[jt]sx?$/;
+const ES_MINIFICADO = /\.(min|bundle|chunk)\.[jt]s$/;
+/* Una linea de mas de 1000 caracteres no la escribio una persona: es un bundle,
+ * un minificado o un blob generado. Nunca es la capa de persistencia de nadie,
+ * y ademas no se puede analizar con sentido.
+ *
+ * Calibrado contra ADIP-Kikan (13-oct-2026): la primera corrida reporto 26
+ * hallazgos dentro de `xtermModule-COQkjINf.js`, un bundle de Playwright
+ * metido en un `.venv_harness`. Ese ruido es exactamente lo que hace que un
+ * equipo apague un control, y un control apagado no vigila nada. */
+const LARGO_DE_LINEA_GENERADO = 1000;
+function pareceGenerado(texto) {
+    let largo = 0;
+    for (let i = 0; i < texto.length; i++) {
+        if (texto[i] === '\n') {
+            largo = 0;
+            continue;
+        }
+        if (++largo > LARGO_DE_LINEA_GENERADO)
+            return true;
+    }
+    return false;
+}
+export function recolectarFuentes(raiz) {
+    const fuentes = [];
+    const generados = [];
+    const omitirDir = (n) => OMITIR.has(n) || OMITIR_PREFIJO.some((p) => n.startsWith(p));
+    const rec = (dir) => {
+        let items;
+        try {
+            items = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const nombre of items.sort()) {
+            const p = path.join(dir, nombre);
+            let st;
+            try {
+                st = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (!omitirDir(nombre))
+                    rec(p);
+                continue;
+            }
+            if (!EXT.test(nombre) || ES_TEST.test(nombre))
+                continue;
+            const rel = path.relative(raiz, p).split(path.sep).join('/');
+            if (ES_MINIFICADO.test(nombre)) {
+                generados.push(rel);
+                continue;
+            }
+            let texto;
+            try {
+                texto = readFileSync(p, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            if (pareceGenerado(texto)) {
+                generados.push(rel);
+                continue;
+            }
+            fuentes.push([rel, texto]);
+        }
+    };
+    rec(raiz);
+    return { fuentes, generados };
+}
+function imprimir(raiz, r, archivos, generados) {
+    header('Yujin Forge -- audit persistence');
+    console.log('');
+    console.log('  Proyecto: ' + c.dim(raiz));
+    console.log('  ' + c.dim(archivos + ' archivos leidos, ' + r.modulos.length + ' modulo(s) de persistencia'
+        + (generados ? ', ' + generados + ' generado(s)/minificado(s) salteado(s)' : '')));
+    console.log('');
+    if (r.modulos.length === 0) {
+        console.log(c.dim('  No se detecto ninguna capa de persistencia.'));
+        console.log('');
+        console.log(c.success('  OK') + c.dim(' -- nada que vigilar todavia.'));
+        return;
+    }
+    console.log('  Metodos de acceso a datos: ' + r.vistos
+        + c.dim('  (async ' + r.asincronicos + ' / sincronicos ' + r.hallazgos.length + ')'));
+    console.log('');
+    if (r.hallazgos.length > 0) {
+        console.log(c.error('  SINCRONICOS -- cada uno es una interfaz que no puede envolver una base real:'));
+        const porArchivo = new Map();
+        for (const h of r.hallazgos) {
+            const lista = porArchivo.get(h.archivo) ?? [];
+            lista.push(h);
+            porArchivo.set(h.archivo, lista);
+        }
+        for (const [archivo, lista] of porArchivo) {
+            console.log('    ' + c.dim(archivo));
+            for (const h of lista) {
+                console.log('      ' + c.error('x') + ' linea ' + String(h.linea).padStart(4)
+                    + '  ' + h.metodo + '()' + c.dim('  [' + h.forma + ']'));
+            }
+        }
+        console.log('');
+    }
+    if (r.exentos.length > 0) {
+        console.log(c.warn('  Eximidos a mano (' + r.exentos.length + '):'));
+        for (const e of r.exentos) {
+            console.log('    ' + c.dim(e.archivo + ':' + e.linea) + '  ' + e.metodo + '()  -- ' + e.motivo);
+        }
+        console.log('');
+    }
+    if (r.ilegibles.length > 0) {
+        console.log(c.error('  NO SE PUDIERON ANALIZAR (' + r.ilegibles.length + '):'));
+        for (const f of r.ilegibles)
+            console.log('    ' + c.error('?') + ' ' + f);
+        console.log(c.dim('    Un archivo que no se puede afirmar NO cuenta como cero: el control falla.'));
+        console.log('');
+    }
+    if (aprueba(r)) {
+        console.log(c.success('  OK') + ' -- toda la interfaz de persistencia es asincronica.');
+        return;
+    }
+    console.log(c.error('  FALLA'));
+    console.log('');
+    console.log(c.dim('  Por que esto importa, y por que se arregla AHORA y no despues:'));
+    console.log(c.dim('    `await` sobre un valor que no es Promise no hace nada, asi que declarar'));
+    console.log(c.dim('    el store async hoy cuesta CERO -- incluso con el store en memoria. El'));
+    console.log(c.dim('    camino inverso es cada punto de llamada del sistema: en ADIP-Kikan'));
+    console.log(c.dim('    fueron 1.543, en nueve slices. Las dos opciones no son simetricas.'));
+}
+export function registerAuditPersistenceCommand(program) {
+    const audit = program.commands.find((cmd) => cmd.name() === 'audit')
+        ?? program.command('audit').description('Controles estaticos sobre un proyecto.');
+    audit
+        .command('persistence [path]')
+        .description('Exige que todo metodo de un store/repositorio este declarado async.')
+        .option('--json', 'emitir JSON en vez del reporte legible')
+        .action(async (where, opts) => {
+        const raiz = path.resolve(process.cwd(), where ?? '.');
+        const { fuentes, generados } = recolectarFuentes(raiz);
+        const r = analizar(fuentes);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({
+                root: raiz, files: fuentes.length, skipped_generated: generados,
+                ok: aprueba(r), ...r,
+            }, null, 2) + '\n');
+            if (!aprueba(r))
+                process.exitCode = 1;
+            return;
+        }
+        imprimir(raiz, r, fuentes.length, generados.length);
+        if (!aprueba(r))
+            process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=audit-persistence.js.map

package/dist/commands/audit-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-persistence.js","sourceRoot":"","sources":["../../src/commands/audit-persistence.ts"],"names":[],"mappings":"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"}

package/dist/docs/doctrine/persistence-interface.md

@@ -0,0 +1,113 @@
+# The persistence interface is async from line one
+
+A rule with no sizing round, no questions to the owner, and no exceptions
+worth arguing about. It is free to obey and it is the most expensive thing
+in this repo to disobey.
+
+## The rule
+
+**Every method of every store, repository or DAO is declared `async`, from
+the first commit, whatever is behind it.** In memory, on disk, over a
+network, a stub that returns `null` -- all of them.
+
+Mechanically enforced by `yf audit persistence`. New projects carry it in
+their own CI. The check fails on a synchronous method and it also fails on a
+file it cannot analyse: a store whose signature cannot be asserted is not a
+store that passed.
+
+## Why it needs no information to decide
+
+The two directions are not symmetric:
+
+| Direction | Cost |
+|---|---|
+| async interface, synchronous implementation behind it | **zero.** `await` on a non-Promise is a no-op |
+| synchronous interface, later made async | **every call site in the system** |
+
+An asymmetric decision is always taken on the recoverable side. There is no
+volumetry that makes the sync interface the better bet, because the sync
+interface's only advantage is that it is marginally shorter to type.
+
+So this rule does not wait for G9, does not wait for the owner to answer how
+many rows per year, and does not appear in the options catalogue. It is not a
+choice.
+
+## What it actually prevents: ADIP-Kikan
+
+Measured, 13-oct-2026. Kikan's first commit reads *"nucleo kawa/sazanami +
+persistencia MariaDB"*. The brain built the repository layer, built two
+implementations, and wired production to MariaDB with write-through and
+boot-time hydration. The data was durable and always had been.
+
+One decision was wrong, and it was a **signature**: the repository interface
+was synchronous. Everything else followed mechanically.
+
+1. A real SQL driver is asynchronous, and a synchronous interface cannot
+   wrap one.
+2. So the "MariaDB store" had to keep the working set in RAM to serve reads
+   synchronously. Its own header says so: *"lecturas sincronas, interfaz
+   IDENTICA a createMemoryStore -> no reescribe el motor"*.
+3. And because an in-memory working set needs no columns, the schema
+   degenerated into **one generic table of JSON rows** (`engine_rows`), with
+   the 57 normalised tables demoted to a derived read-model instead of being
+   the system of record.
+
+The bill: **1.543 call sites**, nine conversion slices, a static ratchet
+built to hold the line, and a reengineering plan of its own.
+
+## Why a brain walks into it
+
+Not from ignorance. Every step is locally correct:
+
+- When the engine is being written there is **no database yet**. The first
+  store you write so the engine is testable is the in-memory one, and its
+  natural signature is synchronous -- correct, at that moment.
+- The engine is written against that signature. Now every future store must
+  match it or the engine breaks.
+- When the real SQL store finally gets written, that signature is
+  load-bearing for hundreds of call sites. Making it async is a repo-wide
+  change no single turn can justify and nobody asked for. So the SQL store
+  contorts to fit the signature instead.
+
+Each step is reasonable. The aggregate is wrong. That is the failure mode of
+incremental construction without an invariant that is checked, and it is why
+this one is a mechanical gate and not a paragraph of advice.
+
+Note also what the model never wrote: it never wrote "in-memory
+persistence". It wrote "a repository with a synchronous interface", and that
+shape is everywhere in any training corpus -- every test double, every
+in-process repo, every small app without an ORM. The dangerous default is
+the *common* one, not an exotic one.
+
+## The decision that was never taken
+
+There was no turn whose subject was "choose the persistence architecture".
+It accumulated. `docs/doctrine/sizing.md` carries the same finding for
+volumetry; this file carries it for the interface, because the interface is
+the half that costs nothing to get right and everything to get wrong.
+
+## Exemptions
+
+A genuinely synchronous accessor that will never cross a process boundary
+can be marked in place:
+
+```js
+// persistence-async-ok: in-RAM index, never touches disk or network
+get(key) { return this.index.get(key); }
+```
+
+The checker **counts and reports** exemptions. An invisible exemption is a
+hole; a counted one is a decision someone can review. Blanket-disabling the
+check is not an exemption, it is the defect.
+
+## What this rule does NOT say
+
+- It does not say the store must be SQL. A memory store is fine for a
+  prototype; the sizing gate decides that. This rule is only about the
+  **signature**.
+- It does not require returning a real Promise. `async` on something that
+  already returns one changes nothing; the rule is "declared `async`"
+  because that is trivial to satisfy and trivial to verify, and a strict
+  simple rule beats a clever one that needs interpreting.
+- It does not apply to test doubles. A synchronous fake inside a battery is
+  legitimate; the checker skips `*.test.*` and `*.spec.*` for that reason.

package/dist/relay/in_flight_turn.d.ts

@@ -33,23 +33,56 @@ export interface InFlightTurn {
     started_at: string;
 }
 /**
- * Tope de edad. Un turno mas viejo que esto se considera muerto y deja de
- * anunciarse, aunque nadie lo haya limpiado.
+ * Cada cuanto el turno da senal de vida. Es el periodo del latido de actividad
+ * del servidor (`startRelayHeartbeat`), que corre SOLO entre el arranque y el
+ * cierre del turno.
  *
- * No es decoracion: `clearInFlightTurn` corre al final del handler, y un
- * proceso que muere a mitad de turno (o una excepcion por un camino que no
- * pasa por ahi) dejaria al telefono con una burbuja "pensando" para siempre.
- * Mentir sobre lo que el sistema esta haciendo es peor que no decir nada.
+ * Vive aca y no en server.ts a proposito: es la mitad de un par acoplado, y la
+ * otra mitad es `SILENCIO_MAX_MS`. El bug anterior nacio de tener dos numeros
+ * acoplados en dos archivos distintos sin nada que los ligara.
  */
-export declare const IN_FLIGHT_MAX_AGE_MS: number;
-export declare function setInFlightTurn(t: InFlightTurn): void;
+export declare const PULSO_DE_PROGRESO_MS: number;
+/**
+ * Tope de SILENCIO. Un turno que no da senal de vida por mas que esto se
+ * considera muerto y deja de anunciarse, aunque nadie lo haya limpiado.
+ *
+ * ANTES ERA UN TOPE DE EDAD, y eso estaba mal (Pablo, 13-oct-2026: "hay turnos
+ * de mas de 3 horas en un desarrollo"). La proteccion que se queria es contra
+ * un turno COLGADO -- un proceso que muere a mitad de camino, o una excepcion
+ * por un camino que no pasa por `clearInFlightTurn` -- porque mentir sobre lo
+ * que el sistema esta haciendo es peor que no decir nada. Pero "colgado" no es
+ * "viejo": es "sin progreso". Un tope de edad confunde las dos cosas y castiga
+ * justo al turno largo, que es el que mas necesita anunciarse.
+ *
+ * Medido: un turno de 29 minutos en ADIP-Kikan dejaba al telefono diciendo que
+ * no habia nada corriendo durante sus ultimos 19 minutos. Con turnos de 3 horas
+ * el anuncio serviria para el 5% del turno.
+ *
+ * Diez pulsos de margen: tolera que se pierdan nueve latidos seguidos antes de
+ * dar por muerto un turno que esta vivo.
+ */
+export declare const SILENCIO_MAX_MS: number;
+export declare function setInFlightTurn(t: InFlightTurn, now?: number): void;
+/**
+ * Senal de vida del turno en curso. La llama el latido de actividad del
+ * servidor, que corre solo mientras hay turno.
+ *
+ * No crea nada: si no hay turno registrado, no hace nada. Asi un latido
+ * rezagado no puede resucitar un turno ya cerrado.
+ */
+export declare function touchInFlightTurn(now?: number): void;
 /**
  * Limpia el turno en vuelo. Con `id`, SOLO si coincide: dos turnos encadenados
  * pueden cerrar fuera de orden, y un cierre tardio del viejo no tiene que
  * borrar el anuncio del que recien arranco.
  */
 export declare function clearInFlightTurn(id?: string): void;
-/** El turno en vuelo, o null si no hay o si ya es demasiado viejo. */
+/**
+ * El turno en vuelo, o null si no hay o si se quedo CALLADO.
+ *
+ * La edad del turno no entra en la decision: un turno de tres horas que sigue
+ * latiendo es un turno vivo y se anuncia. Lo que lo saca es el silencio.
+ */
 export declare function inFlightTurn(now?: number): InFlightTurn | null;
 /** Solo para tests. */
 export declare function _resetInFlightTurn(): void;

package/dist/relay/in_flight_turn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"in_flight_turn.d.ts","sourceRoot":"","sources":["../../src/relay/in_flight_turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,QAAiB,CAAC;AAInD,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAGrD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAInD;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAmB,GAAG,YAAY,GAAG,IAAI,CAQ1E;AAED,uBAAuB;AACvB,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"in_flight_turn.d.ts","sourceRoot":"","sources":["../../src/relay/in_flight_turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,QAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,QAA4B,CAAC;AASzD,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,GAAE,MAAmB,GAAG,IAAI,CAQ/E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI,CAGhE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAInD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAmB,GAAG,YAAY,GAAG,IAAI,CAU1E;AAED,uBAAuB;AACvB,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/relay/in_flight_turn.js

@@ -27,20 +27,57 @@
  * ASCII puro.
  */
 /**
- * Tope de edad. Un turno mas viejo que esto se considera muerto y deja de
- * anunciarse, aunque nadie lo haya limpiado.
+ * Cada cuanto el turno da senal de vida. Es el periodo del latido de actividad
+ * del servidor (`startRelayHeartbeat`), que corre SOLO entre el arranque y el
+ * cierre del turno.
  *
- * No es decoracion: `clearInFlightTurn` corre al final del handler, y un
- * proceso que muere a mitad de turno (o una excepcion por un camino que no
- * pasa por ahi) dejaria al telefono con una burbuja "pensando" para siempre.
- * Mentir sobre lo que el sistema esta haciendo es peor que no decir nada.
+ * Vive aca y no en server.ts a proposito: es la mitad de un par acoplado, y la
+ * otra mitad es `SILENCIO_MAX_MS`. El bug anterior nacio de tener dos numeros
+ * acoplados en dos archivos distintos sin nada que los ligara.
  */
-export const IN_FLIGHT_MAX_AGE_MS = 10 * 60 * 1000;
+export const PULSO_DE_PROGRESO_MS = 60 * 1000;
+/**
+ * Tope de SILENCIO. Un turno que no da senal de vida por mas que esto se
+ * considera muerto y deja de anunciarse, aunque nadie lo haya limpiado.
+ *
+ * ANTES ERA UN TOPE DE EDAD, y eso estaba mal (Pablo, 13-oct-2026: "hay turnos
+ * de mas de 3 horas en un desarrollo"). La proteccion que se queria es contra
+ * un turno COLGADO -- un proceso que muere a mitad de camino, o una excepcion
+ * por un camino que no pasa por `clearInFlightTurn` -- porque mentir sobre lo
+ * que el sistema esta haciendo es peor que no decir nada. Pero "colgado" no es
+ * "viejo": es "sin progreso". Un tope de edad confunde las dos cosas y castiga
+ * justo al turno largo, que es el que mas necesita anunciarse.
+ *
+ * Medido: un turno de 29 minutos en ADIP-Kikan dejaba al telefono diciendo que
+ * no habia nada corriendo durante sus ultimos 19 minutos. Con turnos de 3 horas
+ * el anuncio serviria para el 5% del turno.
+ *
+ * Diez pulsos de margen: tolera que se pierdan nueve latidos seguidos antes de
+ * dar por muerto un turno que esta vivo.
+ */
+export const SILENCIO_MAX_MS = PULSO_DE_PROGRESO_MS * 10;
 let current = null;
-export function setInFlightTurn(t) {
+export function setInFlightTurn(t, now = Date.now()) {
     if (!t || !t.id)
         return;
-    current = { id: String(t.id), user: String(t.user || ''), started_at: String(t.started_at || new Date().toISOString()) };
+    current = {
+        id: String(t.id),
+        user: String(t.user || ''),
+        started_at: String(t.started_at || new Date(now).toISOString()),
+        visto: now,
+    };
+}
+/**
+ * Senal de vida del turno en curso. La llama el latido de actividad del
+ * servidor, que corre solo mientras hay turno.
+ *
+ * No crea nada: si no hay turno registrado, no hace nada. Asi un latido
+ * rezagado no puede resucitar un turno ya cerrado.
+ */
+export function touchInFlightTurn(now = Date.now()) {
+    if (!current)
+        return;
+    current.visto = now;
 }
 /**
  * Limpia el turno en vuelo. Con `id`, SOLO si coincide: dos turnos encadenados
@@ -54,16 +91,23 @@ export function clearInFlightTurn(id) {
         return;
     current = null;
 }
-/** El turno en vuelo, o null si no hay o si ya es demasiado viejo. */
+/**
+ * El turno en vuelo, o null si no hay o si se quedo CALLADO.
+ *
+ * La edad del turno no entra en la decision: un turno de tres horas que sigue
+ * latiendo es un turno vivo y se anuncia. Lo que lo saca es el silencio.
+ */
 export function inFlightTurn(now = Date.now()) {
     if (!current)
         return null;
-    const started = Date.parse(current.started_at);
-    if (Number.isFinite(started) && now - started > IN_FLIGHT_MAX_AGE_MS) {
+    /* Un reloj que salta hacia atras da silencio negativo: no vence. Preferible
+     * anunciar un turno de mas que descartar uno vivo por un salto de NTP. */
+    if (now - current.visto > SILENCIO_MAX_MS) {
         current = null;
         return null;
     }
-    return current;
+    const { id, user, started_at } = current;
+    return { id, user, started_at };
 }
 /** Solo para tests. */
 export function _resetInFlightTurn() {

package/dist/relay/in_flight_turn.js.map

@@ -1 +1 @@
-{"version":3,"file":"in_flight_turn.js","sourceRoot":"","sources":["../../src/relay/in_flight_turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AASH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnD,IAAI,OAAO,GAAwB,IAAI,CAAC;AAExC,MAAM,UAAU,eAAe,CAAC,CAAe;IAC7C,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QAAE,OAAO;IACxB,OAAO,GAAG,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;AAC3H,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAW;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,IAAI,EAAE,IAAI,OAAO,CAAC,EAAE,KAAK,EAAE;QAAE,OAAO;IACpC,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,YAAY,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IACnD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,GAAG,GAAG,OAAO,GAAG,oBAAoB,EAAE,CAAC;QACrE,OAAO,GAAG,IAAI,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uBAAuB;AACvB,MAAM,UAAU,kBAAkB;IAChC,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC"}
+{"version":3,"file":"in_flight_turn.js","sourceRoot":"","sources":["../../src/relay/in_flight_turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AASH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,IAAI,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,GAAG,EAAE,CAAC;AAOzD,IAAI,OAAO,GAAoB,IAAI,CAAC;AAEpC,MAAM,UAAU,eAAe,CAAC,CAAe,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IACvE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QAAE,OAAO;IACxB,OAAO,GAAG;QACR,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QAC/D,KAAK,EAAE,GAAG;KACX,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IACxD,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,OAAO,CAAC,KAAK,GAAG,GAAG,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAW;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,IAAI,EAAE,IAAI,OAAO,CAAC,EAAE,KAAK,EAAE;QAAE,OAAO;IACpC,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IACnD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B;8EAC0E;IAC1E,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,GAAG,eAAe,EAAE,CAAC;QAC1C,OAAO,GAAG,IAAI,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACzC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAClC,CAAC;AAED,uBAAuB;AACvB,MAAM,UAAU,kBAAkB;IAChC,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC"}

package/dist/version.d.ts

@@ -2,5 +2,5 @@
  * Yujin Forge CLI version. Kept in sync with package.json by the npm
  * "version" lifecycle (scripts/sync_version.mjs) so the two never drift.
  */
-export declare const VERSION = "1.15.0";
+export declare const VERSION = "1.16.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -2,5 +2,5 @@
  * Yujin Forge CLI version. Kept in sync with package.json by the npm
  * "version" lifecycle (scripts/sync_version.mjs) so the two never drift.
  */
-export const VERSION = '1.15.0';
+export const VERSION = '1.16.1';
 //# sourceMappingURL=version.js.map

package/docs/doctrine/persistence-interface.md

@@ -0,0 +1,113 @@
+# The persistence interface is async from line one
+
+A rule with no sizing round, no questions to the owner, and no exceptions
+worth arguing about. It is free to obey and it is the most expensive thing
+in this repo to disobey.
+
+## The rule
+
+**Every method of every store, repository or DAO is declared `async`, from
+the first commit, whatever is behind it.** In memory, on disk, over a
+network, a stub that returns `null` -- all of them.
+
+Mechanically enforced by `yf audit persistence`. New projects carry it in
+their own CI. The check fails on a synchronous method and it also fails on a
+file it cannot analyse: a store whose signature cannot be asserted is not a
+store that passed.
+
+## Why it needs no information to decide
+
+The two directions are not symmetric:
+
+| Direction | Cost |
+|---|---|
+| async interface, synchronous implementation behind it | **zero.** `await` on a non-Promise is a no-op |
+| synchronous interface, later made async | **every call site in the system** |
+
+An asymmetric decision is always taken on the recoverable side. There is no
+volumetry that makes the sync interface the better bet, because the sync
+interface's only advantage is that it is marginally shorter to type.
+
+So this rule does not wait for G9, does not wait for the owner to answer how
+many rows per year, and does not appear in the options catalogue. It is not a
+choice.
+
+## What it actually prevents: ADIP-Kikan
+
+Measured, 13-oct-2026. Kikan's first commit reads *"nucleo kawa/sazanami +
+persistencia MariaDB"*. The brain built the repository layer, built two
+implementations, and wired production to MariaDB with write-through and
+boot-time hydration. The data was durable and always had been.
+
+One decision was wrong, and it was a **signature**: the repository interface
+was synchronous. Everything else followed mechanically.
+
+1. A real SQL driver is asynchronous, and a synchronous interface cannot
+   wrap one.
+2. So the "MariaDB store" had to keep the working set in RAM to serve reads
+   synchronously. Its own header says so: *"lecturas sincronas, interfaz
+   IDENTICA a createMemoryStore -> no reescribe el motor"*.
+3. And because an in-memory working set needs no columns, the schema
+   degenerated into **one generic table of JSON rows** (`engine_rows`), with
+   the 57 normalised tables demoted to a derived read-model instead of being
+   the system of record.
+
+The bill: **1.543 call sites**, nine conversion slices, a static ratchet
+built to hold the line, and a reengineering plan of its own.
+
+## Why a brain walks into it
+
+Not from ignorance. Every step is locally correct:
+
+- When the engine is being written there is **no database yet**. The first
+  store you write so the engine is testable is the in-memory one, and its
+  natural signature is synchronous -- correct, at that moment.
+- The engine is written against that signature. Now every future store must
+  match it or the engine breaks.
+- When the real SQL store finally gets written, that signature is
+  load-bearing for hundreds of call sites. Making it async is a repo-wide
+  change no single turn can justify and nobody asked for. So the SQL store
+  contorts to fit the signature instead.
+
+Each step is reasonable. The aggregate is wrong. That is the failure mode of
+incremental construction without an invariant that is checked, and it is why
+this one is a mechanical gate and not a paragraph of advice.
+
+Note also what the model never wrote: it never wrote "in-memory
+persistence". It wrote "a repository with a synchronous interface", and that
+shape is everywhere in any training corpus -- every test double, every
+in-process repo, every small app without an ORM. The dangerous default is
+the *common* one, not an exotic one.
+
+## The decision that was never taken
+
+There was no turn whose subject was "choose the persistence architecture".
+It accumulated. `docs/doctrine/sizing.md` carries the same finding for
+volumetry; this file carries it for the interface, because the interface is
+the half that costs nothing to get right and everything to get wrong.
+
+## Exemptions
+
+A genuinely synchronous accessor that will never cross a process boundary
+can be marked in place:
+
+```js
+// persistence-async-ok: in-RAM index, never touches disk or network
+get(key) { return this.index.get(key); }
+```
+
+The checker **counts and reports** exemptions. An invisible exemption is a
+hole; a counted one is a decision someone can review. Blanket-disabling the
+check is not an exemption, it is the defect.
+
+## What this rule does NOT say
+
+- It does not say the store must be SQL. A memory store is fine for a
+  prototype; the sizing gate decides that. This rule is only about the
+  **signature**.
+- It does not require returning a real Promise. `async` on something that
+  already returns one changes nothing; the rule is "declared `async`"
+  because that is trivial to satisfy and trivial to verify, and a strict
+  simple rule beats a clever one that needs interpreting.
+- It does not apply to test doubles. A synchronous fake inside a battery is
+  legitimate; the checker skips `*.test.*` and `*.spec.*` for that reason.