oficina-opencode 2.0.1 → 2.1.1

package/README.md

@@ -11,12 +11,26 @@
 [![coverage](https://img.shields.io/badge/coverage-87.3%25-7c3aed.svg)](https://vitest.dev)
 [![types](https://img.shields.io/badge/typescript-strict-3178c6.svg)](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/tsconfig.json)
 
-**4 hooks · 13 tools · 7 agentes · 6 gates · 6 invariantes duros · 306 roles de catálogo**
+**Una malla de coordinadores + peer mesh sobre un roster de roles.**
+
+<!-- BEGIN GENERATED: facts -->
+| | |
+|---|---|
+| **Paquete** | `oficina-opencode` v2.1.1 |
+| **Tools** | 16 |
+| **Hooks** | 7 |
+| **API de plugin** | `@opencode-ai/plugin@1.15.11` |
+| **Node** | >=20 |
+| **Catálogo** | 258 agentes resolubles en 18 divisiones |
+| **Divisiones** | academic, design, engineering, finance, game-development, gis, healthcare, marketing, paid-media, product, project-management, research, sales, spatial-computing, specialized, strategy, support, testing |
+| **Límites** | 20 cards · 40 llamadas · 20 spawns · 10 agentes |
+| **Cobertura mínima** | 60% |
+<!-- END GENERATED: facts -->
 
 > **¿Preferís la versión en humano?** → [`docs/QUE-ES.md`](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/QUE-ES.md) — qué es, qué hace y por qué, sin jerga.
 > **¿Preferís el porqué técnico?** → [`docs/ARCHITECTURE.md`](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/ARCHITECTURE.md)
 
-[Documentación](#arquitectura) · [Instalación](#instalación) · [Uso](#uso) · [CLI](#cli-operación)
+[Documentación](#arquitectura) · [Garantías](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/GARANTIAS.md) · [Compatibilidad](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/COMPATIBILITY.md) · [Instalación](#instalación) · [Uso](#uso) · [CLI](#cli-operación)
 
 </div>
 
@@ -141,6 +155,24 @@ Resolución real contra el catálogo:
 
 Reproducible: `npx tsx scripts/demo-roles.ts`
 
+### El benchmark: ¿la complejidad se justifica?
+
+Un matching textual puede elegir bien al rol y aun así no ser el mejor para la tarea. La pregunta no es *"¿funciona?"* sino **"¿vale la pena?"**. El benchmark compara tres estrategias sobre 21 tareas con resultados de referencia:
+
+| Estrategia | hit@1 | hit@3 | MRR |
+|---|---|---|---|
+| **El matcher de la oficina** | **71%** | 86% | **0.778** |
+| Keywords (los pesos de la v1) | 48% | 81% | 0.623 |
+| Solo el nombre del rol | 52% | 76% | 0.639 |
+
+El matcher completo le gana por **23 puntos** de hit@1 a la versión anterior. La complejidad se justifica, y ahora está dicho con números en vez de con adjetivos.
+
+También se probó una ponderación por **IDF** (los tokens raros pesan más) y **no se quedó**: bajaba el hit@1 a 67%. El código lo documenta y el benchmark lo demuestra. La complejidad que no se justifica hay que sacarla, no dejarla dormida en el repo.
+
+```bash
+npm run bench:selection
+```
+
 ### El panel: primario + complementos
 
 Un objetivo casi nunca es de un solo dominio. *"Formulario de login en React con validación y accesibilidad"* necesita un frontend (que no sabe de ARIA) **y** un especialista en accesibilidad (que no sabe de React).
@@ -266,6 +298,67 @@ El que recibe un pedido de ayuda **hace su propio triage** — no acepta por cor
 
 ---
 
+## El scope es una restricción, no una instrucción
+
+La versión anterior del guard comparaba strings: `"...".match(/^src\//)`. Eso se eludía por tres vías, y las tres eran reales.
+
+```
+// El bug: la ruta se comparaba sin resolver.
+const relative = path.relative(projectRoot, absolute)
+if (!matchesScope(relative, mayTouch)) throw ...
+```
+
+| Escape | Antes | Ahora |
+|---|---|---|
+| Symlink a fuera del proyecto | `src/link.ts` matcheaba `src/**` | Se resuelve el symlink y **se revalida** la contención |
+| `..` con `mayTouch: ["**"]` | `**` matcheaba cualquier string | `**` significa *el proyecto*, nunca el filesystem |
+| Path absoluto | `relative` empezaba en `..` y con `**` pasaba | La contención se verifica antes de cualquier glob |
+
+Ahora la ruta se **resuelve** (absoluta → normalizada → symlinks resueltos → `realpath`) y recién ahí se decide, con `fail-closed`.
+
+Además:
+
+- **Todas las tools que escriben**, no solo `edit`/`write`. Los patches multi-archivo se chequean **todos**, no solo el primero.
+- **Los comandos de shell** se analizan antes de ejecutarse: redirecciones, `cp`, `mv`, `rm`, `sed -i`, `dd`, `curl -o`, `git checkout`, interpreters embebidos.
+- **Los subagentes heredan el scope** por la cadena de padres de sesión. Delegar no es un escalón para salirse.
+- **Los archivos sensibles** (`.env`, `.npmrc`, `.git/**`, claves privadas) nunca son escribibles, pase lo que pase el scope de la card.
+- **El tripwire** fotografía el árbol antes de un comando y compara después: detecta lo que el guard no pudo ver.
+
+> Lo que **no** se promete está en [`docs/GARANTIAS.md`](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/GARANTIAS.md). Un shell con interpreter embebido puede escribir afuera; el tripwire lo detecta después, pero no lo revierte. Preferimos decirlo a vender un aislamiento que no existe.
+
+---
+
+## Una caída no destruye la corrida
+
+La oficina escribe en disco, en varios archivos, sin transacción. Un proceso que muere en el momento equivocado deja el estado incoherente. `reconcile()` compara **estado vs artefactos vs filesystem**:
+
+| Situación | Qué hace |
+|---|---|
+| Card en `review` sin `handoff.md` | El agente murió entregando. Se avisa. |
+| Card en `done` sin `gates.md` | Se cerró sin gate. **Crítico.** |
+| Card en progreso sin owner | Nadie la va a terminar. **Crítico.** |
+| Lease de una card que no existe | Se libera. |
+| Lease de una card terminada | Se libera. |
+| Agente `working` sobre una card `done` | Se libera el agente. |
+| Card bloqueada por dependencia irresoluble | Se reporta. |
+
+Lo que **no** hace: completar cards ni inventar evidencia. Un sistema que se auto-repara inventando pruebas es peor que uno que dice *"esto está roto"*.
+
+---
+
+## El costo se controla, no solo la cantidad de agentes
+
+Limitar el número de agentes **no** es controlar el costo: un agente que relee el mismo contexto veinte veces cuesta diez veces lo que uno que lo hace bien.
+
+- El costo real viene del motor (`AssistantMessage.cost`), no se estima.
+- Se contabiliza por **card**, por **agente** y por **fase** (implementación, review, reparación).
+- Presupuestos por corrida, por card y por fase.
+- Estimación previa a una corrida grande.
+- Detección de **trabajo redundante**: releer el mismo path, repetir el mismo comando.
+- **Freno de emergencia**: `oficina_stop` detiene la corrida; el auto-continuación y el despacho se niegan mientras esté detenida.
+
+---
+
 ## Capa 1 — El briefing: qué sabe cada agente antes de arrancar
 
 Un subagente arranca con el contexto vacío. Si el Commander le pasa un prompt suelta (*"implementá el login"*), el agente tiene que adivinar: qué sabe del proyecto, qué espera de él, qué puede tocar, a quién preguntarle si se traba, y qué tiene que entregar. Adivinar es la fuente de todo el trabajo que se repite y de los agentes que se salen del scope.
@@ -363,7 +456,7 @@ No acepta por cortesía. Seis preguntas, en orden:
 
 ---
 
-## Los 4 hooks
+## Los 7 hooks
 
 Acá es donde el protocolo deja de ser una intención.
 
@@ -373,14 +466,18 @@ Acá es donde el protocolo deja de ser una intención.
 | `tool.execute.before` | Bloquea escrituras fuera del scope de la card | «No toques eso» pasa de instrucción a restricción |
 | `experimental.chat.system.transform` | Inyecta el estado de la oficina en cada llamada | El agente no repregunta lo que ya sabe ni repite trabajo |
 | `experimental.session.compacting` | Reinyecta el estado **leído del disco** al compactar | Sin esto, la oficina se olvida a mitad de camino |
+| `tool.execute.after` | Tripwire: fotografía el árbol antes de un comando y compara después | Detecta lo que el guard no pudo ver |
+| `permission.ask` | Segunda capa de enforcement, a nivel del framework | Deniega en el motor, no solo en el hook propio |
+| `event` → `message.updated` | Contabilidad de costo con el número real del motor | El costo no se estima: el motor ya lo sabe |
+| `experimental.compaction.autocontinue` | Freno de emergencia sobre la auto-continuación | Sin esto, una corrida se quema sola en tokens |
 
 El hook de auto-continuación tiene guardas duras: solo reanuda si queda trabajo real, tope de 25 auto-reanudaciones por sesión, cooldown de 1,5 s entre reanudaciones, y nunca reanuda una corrida `paused`, `blocked` o `delivered`.
 
 ---
 
-## Los 6 gates
+## Los 7 gates
 
-De la skill `verification-loop`. Se ejecutan de verdad; el motor interpreta los exit codes.
+Se ejecutan de verdad; el motor interpreta los exit codes.
 
 | # | Fase | Node | Python | Go | Rust |
 |---|---|---|---|---|---|
@@ -390,6 +487,33 @@ De la skill `verification-loop`. Se ejecutan de verdad; el motor interpreta los
 | 4 | Tests | `npm run test` | `pytest` | `go test` | `cargo test` |
 | 5 | Secretos | escaneo en código | ← | ← | ← |
 | 6 | Diff review | `git diff --stat` | ← | ← | ← |
+| 7 | Requisitos | cada criterio de aceptación con su evidencia | ← | ← | ← |
+
+### La pirámide de verificación
+
+Los seis gates técnicos dicen que **el código está sano**. Dicen nada de si el **objetivo del usuario está cumplido**: un proyecto puede compilar, pasar todos sus tests y tener la autenticación mal porque ningún test contemplaba ese escenario.
+
+| Nivel | Qué comprueba |
+|---|---|
+| 1 — Estático | Tipos, lint, secretos, dependencias |
+| 2 — Comportamiento | Unitarias, integración, regresión, casos límite |
+| 3 — Requisitos | Cada criterio de aceptación enlazado a su evidencia |
+| 4 — Auditoría | Revisión independiente, riesgos, coherencia de la evidencia |
+
+El gate 7 es el que cierra el círculo: **una card no se cierra si falta evidencia de un requisito obligatorio**, aunque los otros seis estén en verde.
+
+### El grafo requisito → evidencia
+
+Cada criterio de aceptación es un requisito. Cada evidencia —un artefacto, un test, un gate, una inspección, una auditoría— se vincula a un requisito con un nivel. El grafo responde *qué falta para poder cerrar*:
+
+```
+T-00 · Implementar login
+  [✓] endpoint de login                     nivel 2   artefacto
+  [ ] sin errores de validación            nivel 0   — FALTA
+  [!] cubierto por revisión independiente   nivel 4   auditoría
+```
+
+Un artefacto llega a nivel 2; un test, a 2; un gate, a 1 (o 2 si es la fase `test`); una inspección, a 3; una auditoría —con revisor distinto del owner—, a 4. Una auto-revisión con cara de auditoría se **rechaza**: es peor que no tener auditoría.
 
 **Reglas de honestidad** — no negociables:
 
@@ -405,9 +529,12 @@ De la skill `verification-loop`. Se ejecutan de verdad; el motor interpreta los
 
 Los implementa el código. Un prompt puede pedirle al modelo que sea cuidadoso; el motor no puede romperlos.
 
+> **Ocho invariantes duros**, y se evalúan **donde corresponde**: el de cierre en el cierre, el de presupuesto al gastar, el de ayuda al enrutar. Evaluar un invariante de `DONE` con la card todavía en `review` lo deja vacío — y así estaba antes: el invariante `gate_required_before_done` no disparaba nunca. Ahora se valida contra el estado al que la card llegaría.
+
 | Invariante | Valor |
 |---|---|
 | `gate_required_before_done` | `true` — sin gates en `PASS` no hay `DONE` |
+| `evidence_required_before_done` | `true` — sin evidencia de los requisitos obligatorios no hay `DONE`. *Fail-closed*: si la evidencia no se evaluó, no se cierra |
 | `reviewer_neq_owner` | `true` — no hay auto-aprobación |
 | `max_concurrent_agents` | 10 base · 14 hard cap |
 | `max_spawn_depth` | 2 niveles bajo el coordinador |
@@ -439,9 +566,9 @@ Las preguntas de un especialista al coordinador **van por el bus**, no interrump
 
 ---
 
-## Los 13 tools
+## Los 16 tools
 
-Trece, no treinta. Cada tool que se suma es ruido en el contexto de todos los agentes.
+Dieciséis, no treinta. Cada tool que se suma es ruido en el contexto de todos los agentes.
 
 | Tool | Qué hace |
 |---|---|
@@ -458,6 +585,9 @@ Trece, no treinta. Cada tool que se suma es ruido en el contexto de todos los ag
 | `oficina_escalate` | Escala al usuario con 2-3 opciones concretas y recomendación |
 | `oficina_ficha` | Resuelve un rol a ficha y **despliega** el agente con su briefing |
 | `oficina_brief` | Muestra el briefing y el **panel de roles** sin desplegar: decisión del Comandante |
+| `oficina_evidence` | El grafo de requisitos a evidencia: qué falta para poder cerrar |
+| `oficina_cost` | Tokens y USD por card, agente y fase, con los presupuestos |
+| `oficina_stop` | Freno de emergencia: detiene o reanuda la corrida |
 
 ---
 
@@ -601,7 +731,7 @@ El formato de artefactos es compatible con OFICINA v1 (la skill). El plugin **mi
 
 ## Código
 
-24 archivos TypeScript · 14 módulos en `core/` · 1 toolset · 4 hooks.
+31 archivos TypeScript · 18 módulos en `core/` · 1 toolset · 7 hooks.
 
 ```
 src/
@@ -617,13 +747,22 @@ src/
 │   ├── factory.ts        # generación de roles con briefing de 10 secciones
 │   ├── briefing.ts       # el contrato de información del agente
 │   ├── router.ts         # enrutado + rotación anti-monotonía
-│   ├── gates.ts          # runner de los 6 gates + escaneo de secretos
+│   ├── gates.ts          # runner de los 7 gates + escaneo de secretos
+│   ├── sandbox.ts        # resolucion real de rutas + scope + sensibles
+│   ├── atomic.ts         # primitivas atomicas: O_EXCL, locks, seq
+│   ├── evidence.ts       # grafo requisito -> evidencia
+│   ├── cost.ts           # ledger de tokens y USD
+│   ├── recovery.ts       # reconciliacion estado vs artefactos
+│   ├── tripwire.ts       # deteccion de escrituras coladas
+│   ├── stores.ts         # persistencia de evidencia y costo
+│   ├── docsync.ts        # fuente unica de verdad de las cifras
 │   ├── retry.ts          # política de 3 golpes
 │   ├── office.ts         # la fachada que amarra todo
 │   ├── paths.ts          # resolución de project root
 │   ├── fsx.ts            # IO atómico
+│   ├── ids.ts            # ids seguros para usar como nombre de archivo
 │   └── log.ts            # logging estructurado
-├── tools/index.ts        # las 11 tools
+├── tools/index.ts        # las 16 tools
 └── hooks/
     ├── sessionIdle.ts    # auto-continuación
     ├── scopeGuard.ts     # enforcement de scope
@@ -640,8 +779,10 @@ Una sola, y es peer del host: `@opencode-ai/plugin`. Zod entra por `tool.schema`
 ## Testing
 
 ```bash
-npm test           # 213 tests, 14 archivos
-npm run coverage   # 90.2% stmts · 82.8% branches
+npm test           # 385 tests, 21 archivos
+npm run coverage   # cobertura por línea
+npm run docs:check # la documentación coincide con el código
+npm run bench:selection  # el matcher le gana a las alternativas simples
 npm run typecheck  # tsc --noEmit, strict
 npm run build      # tsc → dist/
 ```
@@ -650,14 +791,21 @@ npm run build      # tsc → dist/
 |---|---|
 | `bus.test.ts` | Append-only, ack, TTL, idempotencia, broadcast, prioridad, atomicidad |
 | `state.test.ts` | Transiciones, invariantes duros, selección de card, ciclo de corrida |
-| `gates.test.ts` | Detección de tooling, las 6 fases, N/A con motivo, consolidación, redacción |
+| `gates.test.ts` | Detección de tooling, las 7 fases, N/A con motivo, consolidación, redacción |
 | `router.test.ts` | Enrutado, rotación, reviewer ≠ owner, política de 3 golpes, presupuesto |
 | `leases.test.ts` | Adquisición, heartbeat, expiración, double-claim, reasignación |
 | `catalog.test.ts` | Frontmatter, secciones, extracción, matching ponderado, panel, factory |
-| `catalogReal.test.ts` | El catálogo real de 306 agentes: estructuras, matching, división |
+| `catalogReal.test.ts` | El catálogo real de agency-agents: estructuras, matching, división |
 | `briefing.test.ts` | Orden, mínimo, las 10 secciones, los 4 artefactos, INCOMPLETO |
 | `office.test.ts` | Ciclo completo end-to-end, invariantes, artefactos en disco |
 | `scopeGuard.test.ts` | Globs, extracción de path, enforcement de scope |
+| `sandbox.test.ts` | **Adversarial**: symlinks, traversal, absolutos, sensibles, shell |
+| `concurrency.test.ts` | Doble claim simultáneo, seq único, idempotencia atómica |
+| `recovery.test.ts` | Entregas perdidas, invariantes vulnerados, huérfanos, reinicio |
+| `evidence.test.ts` | El grafo requisito → evidencia y los 4 niveles |
+| `cost.test.ts` | Ledger, presupuestos por fase, trabajo redundante |
+| `tripwire.test.ts` | Detección de escrituras coladas por shell |
+| `docsync.test.ts` | La documentación coincide con el código |
 | `plugin.test.ts` | El plugin contra un host mockeado: tools, hooks, auto-resume |
 | `migration.test.ts` | Migración v1 → v2 sin pérdida de datos |
 | `cli.test.ts` | init, status, board, install, audit, reset, idempotencia |
@@ -669,3 +817,5 @@ npm run build      # tsc → dist/
 MIT — ver [LICENSE](https://github.com/SOCRAMbt/AI-OFFICE/tree/main/LICENSE).
 
 El diseño se apoya en los patrones de `durable-execution` y `workflow-engine-design`: estado durable antes de los efectos, leases con TTL, transiciones nombradas explícitamente y at-least-once con reconciliación por idempotency key.
+
+Lo que **no** se promete está escrito en [`docs/GARANTIAS.md`](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/GARANTIAS.md): un plugin de aplicación no es un sandbox, y un README que vende más de lo que el código hace es peor que uno modesto.

package/commands/oficina.md

@@ -1,34 +1,47 @@
 ---
-description: Abrir la Oficina de Agents para trabajar un objetivo de punta a punta con delegation, auto-revisión y gates de calidad
+description: Abrir la Oficina de Agents para trabajar un objetivo de punta a punta con dispatch, auto-revisión, gates de calidad y evidencia por requisito
 subtask: false
 ---
 
-Cargá la skill `oficina` y seguí su protocolo exactamente. Si sus instrucciones no están ya en contexto, cargála primero.
-
-**Vos sos el Director.** Leé el agente `oficina-director` en `~/.config/opencode/agents/oficina-director.md` y adoptá su rol: planificás, delegás, decidís, escalás. **No escribas código de producción vos** — eso lo hacen los especialistas que delegás.
+Cargá la skill `oficina` y seguí su protocolo exactamente. Si sus instrucciones no están ya en contexto, cargala primero.
 
 **Objetivo de la corrida:** $ARGUMENTS
 
 Si el objetivo está vacío, tomá el pedido más reciente del usuario en esta conversación como objetivo.
 
+## Paso 0 — ¿Plugin o fallback?
+
+**[plugin]** Si tenés las tools `oficina_*` disponibles, usá el **motor duro**. Es lo que hace que los invariantes dejen de ser sugerencias: el guard de scope rechaza escrituras fuera del scope, el gate corre comandos de verdad, y una card no se cierra sin evidencia.
+
+Comprobá si existe `oficina_plan`. Si existe:
+
+1. `oficina_plan` con el objetivo descompuesto en cards (ver abajo).
+2. `oficina_dispatch` → **arma el equipo**: resuelve los roles en el catálogo de agency-agents, materializa los agentes y los arranca en paralelo.
+3. `oficina_mesa` (view) → mirá quién trabaja en qué.
+4. Corré el ciclo con las tools: `oficina_assign` → trabajo → `oficina_submit` → `oficina_review` → `oficina_evidence` → `oficina_gate`.
+5. `oficina_cost` para el costo; `oficina_stop` si la corrida se descontrola.
+
+**Si NO hay plugin**, seguí el flujo de artefactos en markdown de `reference/protocol.md`. Mismo protocolo, sin enforcement.
+
 ## Arrancá así — sin preguntar permiso
 
 1. Leé `reference/protocol.md` y `reference/roles.md` de la skill `oficina`.
 2. **Resolvé PROJECT_ROOT** siguiendo el Paso 0 del protocolo (buscá markers de proyecto; no asumas que el cwd es el proyecto). `OFFICE_DIR = PROJECT_ROOT/.oficina/`. Usá paths ABSOLUTOS en todo lo que escribas y en todos los prompts de delegación.
-3. Creá `OFFICE_DIR/` con `board.md`, `state.json` y `context.md` (templates en `reference/templates.md`).
-4. Descomponé el objetivo en cards con acceptance criteria **verificables** y gate explícito. Si el objetivo es vago, hacé las inferencias razonables y anotá cuáles son — no frenes por ambigüedad menor. Ordená las cards por **causa**: si el fix de B rompe el gate de A, B va primero.
+3. Descomponé el objetivo en cards con acceptance criteria **verificables** y gate explícito. Si el objetivo es vago, hacé las inferencias razonables y anotá cuáles son — no frenes por ambigüedad menor. Ordená las cards por **causa**: si el fix de B rompe el gate de A, B va primero.
+4. Cada card necesita: `scope` (qué archivos puede tocar), `acceptance` (criterios verificables) y `gate` (el comando que lo demuestra).
 5. Delegá por la **tabla de enrutado** de `reference/roles.md`. El Crítico nunca es el owner. El Verificador nunca es el Implementador. Cada subagente es stateless: el prompt lleva TODO el contexto, y los paths absolutos del PROJECT_ROOT.
-6. Corré el ciclo: TRABAJO → AUTO-REVIEW → GATES → DONE, o REWORK/REPLAN/ESCALADA.
-7. Checkpoint al usuario cada 3 cards — **informa y seguí**, no pidas permiso.
+6. Corré el ciclo: TRABAJO → AUTO-REVIEW → GATES + EVIDENCIA → DONE, o REWORK/REPLAN/ESCALADA.
+7. Checkpoint al usuario cada 3 cards — **informá y seguí**, no pidás permiso.
 8. Escalá solo con el formato de 2-3 opciones concretas + recomendación.
 
 ## Presupuesto
 
-20 cards, 40 invocaciones de subagente por corrida. Si se agota, entregá informe parcial con lo alcanzado y preguntá.
+20 cards, 40 invocaciones de subagente, 20 spawns por corrida. **[plugin]** El costo real (tokens y USD) se ve con `oficina_cost`; si se dispara, `oficina_stop` frena la corrida.
 
 ## Lo que esta oficina garantiza
 
 - Ninguna card se marca DONE sin `gates.md` en PASS
+- **[plugin]** Ninguna card se marca DONE sin evidencia para cada criterio de aceptación obligatorio
 - Ningún trabajo se auto-aprueba
 - Nada se pierde: todo está en `.oficina/artifacts/`
 - El objetivo se trabaja hasta cumplirlo o hasta un bloqueo real

package/dist/core/atomic.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Primitivas atómicas sobre disco.
+ *
+ * ## Por qué existe
+ *
+ * `writeAtomic` (tmp + rename) garantiza que un lector nunca vea un JSON a
+ * medio escribir. No garantiza que **dos escritores no se pisen**. El
+ * patron "leo, evaluo, escribo" — un TOCTOU — es la raiz de las carreras
+ * que existian:
+ *
+ * - El lease: dos agentes leian "no hay lease", los dos pasaban el chequeo,
+ *   los dos escribian, y el segundo gano. El primero creia que tenia la
+ *   card y el trabajo se hacia dos veces.
+ * - El `seq` del bus: dos emisores concurrentes calculaban el mismo
+ *   `max + 1` y dejaban dos mensajes con el mismo seq.
+ * - La idempotencia: el "existe ya?" se hacia antes de escribir, asi que
+ *   dos envios concurrentes con la misma clave creaban dos mensajes.
+ *
+ * ## Las tres primitivas
+ *
+ * - `writeExclusive`: crea el archivo con `O_EXCL`. Si ya existe, **no**
+ *   lo pisa: devuelve el contenido que hay. Es la primitiva de "reclamar".
+ * - `withLock`: mutex por directorio. `mkdir` es atomico en POSIX y en
+ *   Windows, asi que solo un proceso puede tomar el lock. Tiene un
+ *   breaker de locks vencidos, porque un proceso muerto no suelta el lock.
+ * - `allocateSeq`: numero de secuencia unico, con la asignacion y la
+ *   escritura del mensaje bajo el mismo lock.
+ *
+ * ## Lo que NO resuelve
+ *
+ * Nada de esto es un sistema de transacciones. No hay rollback, ni
+ * commit en dos fases, ni journal. Es lo que hace falta para que las
+ * invariantes que el sistema ya declara (un lease, un seq, una clave de
+ * idempotencia) sean verdad en vez de una intencion.
+ */
+export interface ExclusiveWriteResult {
+    /** true si este proceso creo el archivo. */
+    created: boolean;
+    /** Contenido final del archivo (el propio, o el que ya estaba). */
+    contents: string;
+}
+/**
+ * Escribe un archivo de forma exclusiva.
+ *
+ * Con `O_EXCL`, el kernel garantiza que solo un proceso puede crearlo:
+ * los demas reciben `EEXIST` en vez de pisar. Es la primitiva atomica de
+ * "reclamar un recurso con nombre".
+ */
+export declare function writeExclusive(filePath: string, contents: string): Promise<ExclusiveWriteResult>;
+/** ¿Existe un archivo? */
+export declare function fileExists(filePath: string): Promise<boolean>;
+export interface LockOptions {
+    /** Cuanto esperar por el lock antes de rendirse. */
+    timeoutMs?: number;
+    /** A partir de cuando un lock se considera muerto y se puede romper. */
+    staleMs?: number;
+}
+/**
+ * Mutex por directorio.
+ *
+ * `mkdir` es atomico: de miles de procesos, uno solo recibe exito. Los
+ * demas ven `EEXIST` y esperan.
+ *
+ * ## Locks vencidos
+ *
+ * Si el proceso que tomo el lock muere, el directorio queda ahi para
+ * siempre. Por eso un lock mas viejo que `staleMs` se rompe: se asume que
+ * su dueno murio. Sin eso, un crash deja la oficina trabada para siempre,
+ * que es peor que el riesgo de romper un lock de otro proceso vivo (y ese
+ * proceso, si sigue vivo, esta haciendo su trabajo y no necesita el lock
+ * para otra cosa).
+ */
+export declare function withLock<T>(lockPath: string, fn: () => Promise<T>, options?: LockOptions): Promise<T>;
+/**
+ * Asigna un numero de secuencia unico dentro de un directorio.
+ *
+ * La asignacion y la escritura tienen que ocurrir **bajo el mismo lock**.
+ * Si el numero se reservara y el lock se soltara antes de escribir, el
+ * siguiente emisor no veria el archivo todavia no escrito y calcularia el
+ * mismo numero.
+ */
+export declare function allocateSeq(channelDir: string, write: (seq: number) => Promise<void>, options?: LockOptions): Promise<number>;
+/** Path del lock de un canal. */
+export declare function seqLockPath(channelDir: string): string;
+//# sourceMappingURL=atomic.d.ts.map

package/dist/core/atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../../src/core/atomic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAKH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAA;IAChB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CActG;AAED,0BAA0B;AAC1B,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,CAAC,CAAC,CAgEZ;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EACrC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,iCAAiC;AACjC,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/core/atomic.js

@@ -0,0 +1,186 @@
+/**
+ * Primitivas atómicas sobre disco.
+ *
+ * ## Por qué existe
+ *
+ * `writeAtomic` (tmp + rename) garantiza que un lector nunca vea un JSON a
+ * medio escribir. No garantiza que **dos escritores no se pisen**. El
+ * patron "leo, evaluo, escribo" — un TOCTOU — es la raiz de las carreras
+ * que existian:
+ *
+ * - El lease: dos agentes leian "no hay lease", los dos pasaban el chequeo,
+ *   los dos escribian, y el segundo gano. El primero creia que tenia la
+ *   card y el trabajo se hacia dos veces.
+ * - El `seq` del bus: dos emisores concurrentes calculaban el mismo
+ *   `max + 1` y dejaban dos mensajes con el mismo seq.
+ * - La idempotencia: el "existe ya?" se hacia antes de escribir, asi que
+ *   dos envios concurrentes con la misma clave creaban dos mensajes.
+ *
+ * ## Las tres primitivas
+ *
+ * - `writeExclusive`: crea el archivo con `O_EXCL`. Si ya existe, **no**
+ *   lo pisa: devuelve el contenido que hay. Es la primitiva de "reclamar".
+ * - `withLock`: mutex por directorio. `mkdir` es atomico en POSIX y en
+ *   Windows, asi que solo un proceso puede tomar el lock. Tiene un
+ *   breaker de locks vencidos, porque un proceso muerto no suelta el lock.
+ * - `allocateSeq`: numero de secuencia unico, con la asignacion y la
+ *   escritura del mensaje bajo el mismo lock.
+ *
+ * ## Lo que NO resuelve
+ *
+ * Nada de esto es un sistema de transacciones. No hay rollback, ni
+ * commit en dos fases, ni journal. Es lo que hace falta para que las
+ * invariantes que el sistema ya declara (un lease, un seq, una clave de
+ * idempotencia) sean verdad en vez de una intencion.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Escribe un archivo de forma exclusiva.
+ *
+ * Con `O_EXCL`, el kernel garantiza que solo un proceso puede crearlo:
+ * los demas reciben `EEXIST` en vez de pisar. Es la primitiva atomica de
+ * "reclamar un recurso con nombre".
+ */
+export async function writeExclusive(filePath, contents) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    let handle;
+    try {
+        handle = await fs.open(filePath, "wx");
+        await handle.writeFile(contents, "utf8");
+        return { created: true, contents };
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+        const existing = await fs.readFile(filePath, "utf8").catch(() => "");
+        return { created: false, contents: existing };
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+/** ¿Existe un archivo? */
+export async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Espera un poco. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Mutex por directorio.
+ *
+ * `mkdir` es atomico: de miles de procesos, uno solo recibe exito. Los
+ * demas ven `EEXIST` y esperan.
+ *
+ * ## Locks vencidos
+ *
+ * Si el proceso que tomo el lock muere, el directorio queda ahi para
+ * siempre. Por eso un lock mas viejo que `staleMs` se rompe: se asume que
+ * su dueno murio. Sin eso, un crash deja la oficina trabada para siempre,
+ * que es peor que el riesgo de romper un lock de otro proceso vivo (y ese
+ * proceso, si sigue vivo, esta haciendo su trabajo y no necesita el lock
+ * para otra cosa).
+ */
+export async function withLock(lockPath, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const staleMs = options.staleMs ?? 30_000;
+    const deadline = Date.now() + timeoutMs;
+    // El lock vive como directorio. Su padre puede no existir todavia (el
+    // canal del bus se crea con el primer mensaje), y `mkdir` sin `recursive`
+    // falla con ENOENT si el padre falta.
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    let acquired = false;
+    while (Date.now() < deadline) {
+        try {
+            await fs.mkdir(lockPath);
+            acquired = true;
+            break;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "EEXIST") {
+                // Alguien mas tiene el lock. Normal.
+            }
+            else if (code === "EPERM") {
+                // ── Trampa de Windows ──
+                //
+                // Cuando el dueno anterior esta borrando el lock, un `mkdir`
+                // concurrente no da EEXIST: da EPERM, porque el path existe pero
+                // esta en un estado invalido. Es una carrera transitoria, no un
+                // error de permisos: se reintenta.
+                //
+                // Sin este caso, en Windows dos emisores concurrentes del bus se
+                // rompian con EPERM en vez de serializarse.
+            }
+            else {
+                throw err;
+            }
+            // ¿El lock esta vencido?
+            try {
+                const stat = await fs.stat(lockPath);
+                if (Date.now() - stat.mtimeMs > staleMs) {
+                    await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                    continue;
+                }
+            }
+            catch {
+                // El lock desaparecio entre el mkdir y el stat: reintentar.
+                continue;
+            }
+            // Espera con jitter: evita que los procesos se alineen en la carrera.
+            await sleep(15 + Math.floor(Math.random() * 35));
+        }
+    }
+    if (!acquired) {
+        throw new Error(`[oficina] no se pudo tomar el lock ${lockPath} en ${timeoutMs}ms`);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        // `rmdir` en vez de `rm -r`: el lock esta siempre vacio, y una sola
+        // llamada al sistema deja menos ventana para la carrera de Windows.
+        await fs.rmdir(lockPath).catch(async () => {
+            await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+        });
+    }
+}
+/**
+ * Asigna un numero de secuencia unico dentro de un directorio.
+ *
+ * La asignacion y la escritura tienen que ocurrir **bajo el mismo lock**.
+ * Si el numero se reservara y el lock se soltara antes de escribir, el
+ * siguiente emisor no veria el archivo todavia no escrito y calcularia el
+ * mismo numero.
+ */
+export async function allocateSeq(channelDir, write, options = {}) {
+    const lockPath = path.join(channelDir, ".seq.lock");
+    return withLock(lockPath, async () => {
+        const entries = await fs.readdir(channelDir).catch(() => []);
+        let max = 0;
+        for (const entry of entries) {
+            const m = /^(\d{4,})-/.exec(entry);
+            if (!m)
+                continue;
+            const n = Number.parseInt(m[1], 10);
+            if (Number.isFinite(n) && n > max)
+                max = n;
+        }
+        const seq = max + 1;
+        await write(seq);
+        return seq;
+    }, options);
+}
+/** Path del lock de un canal. */
+export function seqLockPath(channelDir) {
+    return path.join(channelDir, ".seq.lock");
+}
+//# sourceMappingURL=atomic.js.map

package/dist/core/atomic.js.map

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