@nac3/forge-cli 1.14.0 → 1.16.0

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nac3/forge-cli",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Yujin Forge -- voice-first NAC-3 React development framework. CLI + chat panel + spec ingest + 10-format document reader + voice loop.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Pablo Kuschnirof <pablo@rpaforce.com>",

package/templates/nextjs-app/package.json

@@ -11,7 +11,8 @@
     "test:watch": "vitest",
     "test:e2e": "playwright test",
     "lint": "next lint",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && yf audit persistence",
+    "audit:persistence": "yf audit persistence",
     "yf": "yf"
   },
   "dependencies": {

package/templates/react-app/package.json

@@ -11,7 +11,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
-    "lint": "tsc --noEmit",
+    "lint": "tsc --noEmit && yf audit persistence",
+    "audit:persistence": "yf audit persistence",
     "yf": "yf"
   },
   "dependencies": {