@nac3/forge-cli 1.0.89 → 1.0.90

package/dist/chat/doctrine_digest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctrine_digest.d.ts","sourceRoot":"","sources":["../../src/chat/doctrine_digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,eAAe,EAAE,mBAAmB,EAyHhD,CAAC;AAEF,6DAA6D;AAC7D,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC;AAED,MAAM,WAAW,qBAAqB;IACpC;4EACwE;IACxE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;uEACuE;AACvE,wBAAgB,wBAAwB,CAAC,IAAI,GAAE,qBAA0B,GAAG,MAAM,EAAE,CAiBnF"}
+{"version":3,"file":"doctrine_digest.d.ts","sourceRoot":"","sources":["../../src/chat/doctrine_digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,eAAe,EAAE,mBAAmB,EA2IhD,CAAC;AAEF,6DAA6D;AAC7D,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC;AAED,MAAM,WAAW,qBAAqB;IACpC;4EACwE;IACxE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;uEACuE;AACvE,wBAAgB,wBAAwB,CAAC,IAAI,GAAE,qBAA0B,GAAG,MAAM,EAAE,CAiBnF"}

package/dist/chat/doctrine_digest.js

@@ -105,6 +105,23 @@ export const DOCTRINE_DIGEST = [
             + 'number (a 20-user tool stays single-tier; neither a bottleneck nor '
             + 'gold-plating).',
     },
+    {
+        slugs: ['performance-hardening'],
+        rule: 'harden every load-bearing component for its load in v1 -- match the '
+            + 'trigger (full patterns via discover): DB batch = COMMIT PER CHUNK, '
+            + 'never a tx open across a network call, deadlock retry w/ backoff but '
+            + 'never an external call inside a retry; third parties NON-idempotent -- '
+            + 'dedupe by id ON WRITE (UNIQUE), ACK-first + background, pace outbound, '
+            + 'firm reject -> dead-end not retry-burst; background loops = '
+            + 'backpressure cap per pass + TTL-keyed locks + start-once singletons; '
+            + 'lists PAGINATE server-side; growing tables INDEX filtered/sorted cols, '
+            + 'no fn on an indexed col, no LIKE %q%, VARCHAR(191) not TEXT; long work '
+            + '-> job+poll not a 504; TTL-clean growth; heartbeat+watchdog+'
+            + 'alert-dedupe. LAWS: cero hardcode (thresholds in config, default '
+            + 'preserves behavior, dangerous features born inert), producer/consumer '
+            + 'symmetry, fail-closed, MEASURE before a fan-out switch, PROPORTIONAL '
+            + '(pairs with concurrency-scale).',
+    },
     {
         slugs: ['verb-composition'],
         rule: 'compose native verbs in dependency order; prefer a yujin.* verb over shell. Long-running commands (dev server/watcher/tunnel) MUST use yujin.task.run, never shell.exec (which refuses them).',

package/dist/chat/doctrine_digest.js.map

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

package/dist/docs/doctrine/concurrency-scale.md

@@ -52,3 +52,14 @@ the stated concurrency.
 
 Record the target concurrency and the tier decisions in the spec so
 they are traceable and can be revisited when the number changes.
+
+## 4. Then harden each component (see `performance-hardening`)
+
+This doctrine sizes the ARCHITECTURE. Sizing the tiers right does not
+save a component that holds a transaction open across a network call,
+runs a batch in one monolithic commit, hammers a non-idempotent third
+party, or grids a table with `LIKE '%q%'`. The construction-time
+pattern library -- commit-per-chunk, send-outside-transaction, deadlock
+retry, backpressure caps, server-side pagination, idempotency at the
+boundary, TTL cleanup, heartbeat/watchdog -- lives in
+`performance-hardening`. Size here; harden there.

package/dist/docs/doctrine/performance-hardening.md

@@ -0,0 +1,213 @@
+# Performance & scale hardening doctrine
+
+Every load-bearing component MUST be built for its load in its FIRST
+version -- not hardened after it falls over in production. The brain
+defaults to the happy path: it writes the loop, calls the API, renders
+the grid, and stops. That is exactly how a component ships that
+saturates the DB, hammers a third party, or deadlocks under
+concurrency. This doctrine is the pattern library that closes that gap.
+
+Apply the patterns that the component's SHAPE triggers (below). This is
+the RUNTIME / construction complement to `concurrency-scale` (which
+sizes the ARCHITECTURE during relevamiento). Size the tiers there;
+harden each component here. Every rule below is battle-tested in a
+production HITL system, not theory.
+
+## How to use this: match the trigger, apply the pattern
+
+### Trigger 1 -- a component that WRITES to a DB in a loop or batch
+
+- **Commit per chunk, never one monolithic transaction.** A single
+  final commit over the whole run holds row/gap locks on every touched
+  table until the end, grows the undo log unbounded, and lets ONE
+  deadlock roll back the ENTIRE run. Commit per item (or per small
+  chunk): locks release continuously, a failure isolates to one item,
+  and the run becomes resumable.
+- **Never hold a transaction open across a slow side-effect (network /
+  external call).** Use the TWO-TRANSACTION pattern: TX1 = change state
+  + set an "in-flight" marker -> COMMIT (release locks) -> perform the
+  external call with NO transaction open -> TX2 = record the result +
+  clear the marker -> COMMIT. A crash between the COMMIT and the call
+  must be recoverable: build a sweeper that finds rows with the marker
+  set but no result, past a TTL, and re-queues them.
+- **Deadlock retry with backoff + jitter.** Classify transient errors
+  (MariaDB 1213 deadlock / 1205 lock-wait-timeout; SQLite "database is
+  locked") and retry the transaction with exponential backoff + jitter
+  (~6 attempts is a good default). Two variants: retry on a FRESH
+  connection (top-level request) vs retry a pure-DB sub-transaction on
+  the ALREADY-OPEN connection. **INVARIANT: never put an external call
+  inside a retry body** -- a redo would double-send / double-charge.
+- **Reserve -> confirm -> return for consumable resources.** Do not
+  decrement-then-hope-to-refund. Reserve at arming, confirm on success,
+  return on reject. The decrement MUST be a single atomic UPDATE guarded
+  so the balance never goes negative (multiple workers touch the same
+  row).
+- **Atomic counter / compare-and-swap, not read-modify-write, across
+  threads or workers.** `UPDATE ... SET flag=1 WHERE id=? AND flag=0`;
+  if rowcount=0 you lost the race, back off. Guard in-process shared
+  state with a lock (a multi-thread WSGI server runs N handlers).
+
+### Trigger 2 -- a component that CALLS a third party (API / provider / webhook)
+
+- **Assume NOT idempotent until proven.** Never auto-retry a
+  non-idempotent write. A firm reject goes to a dead-end + manual path,
+  NOT a burst of retries at a real person or resource. Gate any
+  auto-refire behind provider-confirmed idempotency OR a read-back that
+  proves the prior call did not land.
+- **Idempotency at the boundary = a UNIQUE constraint.** Dedupe by the
+  provider's real message/transaction id ON WRITE, not just on read.
+  Webhooks arrive "at least once" and may re-deliver even after your
+  ACK; an unconditional insert turns one event into six rows.
+- **ACK first, work after.** Answer the webhook immediately (202) and do
+  the slow work (notices, downstream calls) in a background thread /
+  queue. A slow response makes the provider time out and re-send ->
+  amplification (one real incident: 62 inbound images -> 36 real).
+- **Pace outbound explicitly.** Per-recipient minimum interval; a
+  time-window gate (do not contact outside allowed hours; exempt urgent
+  paths); a per-run quota + an inter-item sleep placed OUTSIDE any open
+  transaction. Respect the provider's rate limits as first-class config.
+- **Timeout-then-escalate; never wait forever.** After a bounded wait,
+  escalate or advance so nothing stays stuck. Advance on the FIRST of
+  several signals (read / reply / timeout), idempotently.
+- **The external latency and the human ARE the dominant time cost** --
+  far above the DB. Do not block the main thread on them; optimizing a
+  query that was never the bottleneck buys nothing.
+
+### Trigger 3 -- a background loop / scheduler / sweeper
+
+- **Backpressure: cap dispatches per pass.** A mass dump ("run it all
+  now") without a cap is a stampede that collides into deadlocks. A
+  configurable cap per pass drains the backlog in controlled batches and
+  keeps each pass under the watchdog threshold.
+- **One unit per key per pass** when exclusivity/order matters (e.g. one
+  message per recipient per sweep) so the loop never fires two at the
+  same target.
+- **Isolate each sweep in its own transaction + its own retry.** Do not
+  bundle several sweeps under one commit -- one deadlock then starves all
+  of them for the whole interval.
+- **Locks with a configurable TTL, keyed CORRECTLY.** An eternal lock is
+  a bug (a silent responder blocks the target forever). Key the lock by
+  the thing that must serialize (per type / per recipient / per delivery
+  target). Stamp each run with the SERVER-INSTANCE token so a recycled
+  PID after a restart does not leave the lock hung.
+- **Singletons start EXACTLY once**, guarded against double-start (a dev
+  reloader or two threads can otherwise launch two schedulers -> doubled
+  cron and doubled sends).
+
+### Trigger 4 -- a list / grid / export endpoint
+
+- **Server-side pagination**: LIMIT/OFFSET with an envelope
+  `{items, total, page, pages}` and a page_size cap. Filter the WHOLE set
+  server-side, THEN paginate -- never filter only the visible page.
+- **Export fetches the complete filtered/ordered set** via an explicit
+  flag (e.g. `?todo=1`), never by scraping the visible DOM page. The
+  page_size cap still protects the screen.
+- Never load the whole world into the client to render a view.
+
+### Trigger 5 -- a query on a table that GROWS
+
+- **Index every column that grows and is filtered / joined / sorted.** A
+  UNIQUE constraint IS an index -- do not double-index its leading
+  column, and do not "fix" a scan that already rides a UNIQUE.
+- **Never wrap an indexed column in a function inside WHERE / GROUP BY /
+  ORDER BY** (`substr(ts,1,10)=today`, `TRIM(col)=''`, `ORDER BY CASE`).
+  It disables the index. Rewrite to a RANGE (`ts >= day AND ts < next`),
+  normalize on write, or persist the sort key in its own indexed column.
+- **`LIKE '%q%'` (leading wildcard) is unindexable by a B-tree.** Use an
+  anchored prefix `q%` (indexable, "starts with") or a real full-text
+  index (MariaDB FULLTEXT / SQLite FTS). Free-text search at scale wants
+  an inverted index, not SQL LIKE.
+- **Engine portability: short indexed columns are VARCHAR(191), not
+  TEXT.** SQLite indexes TEXT happily and hides the bug; MariaDB errors
+  1071 "key too long" (and FK-on-TEXT errno 150). Test against the REAL
+  engine before prod (a pre-push barrier catches "key too long" before
+  the VM does).
+
+### Trigger 6 -- memory / large payloads / long work
+
+- **Do not load a whole file / dataset into memory** when you can stream
+  in chunks. Know the memory peak of each heavy operation and do not let
+  two heavy runs (import + browser bot + batch) overlap on one machine.
+- **Compress large payloads (gzip)** and raise size caps ONLY on the
+  specific admin endpoint, not globally.
+- **Long-running work -> background job + poll**, never inside the HTTP
+  request (that is a structural 504). Return `202 + id`; the client polls
+  a status endpoint. Guard it idempotently: a second start while one is
+  alive returns the SAME run.
+
+### Trigger 7 -- anything that accumulates (tables, files, logs)
+
+- **Every fast-growing table and disk accumulation needs a TTL cleanup**,
+  configurable, default OFF (never silent data loss). Bounded size keeps
+  queries fast and disk healthy. Beware: cleanup that deletes DB rows
+  often forgets the files they point to -- purge both.
+
+### Trigger 8 -- observability of the hardening itself
+
+- **Instrument retries.** Leave a trace when a retry saved a transaction,
+  so residual deadlocks are countable ("the retry doing its job, not an
+  error"), not invisible.
+- **Heartbeat per service + heartbeat MID-PASS.** A long pass over a big
+  backlog exceeds the liveness threshold and trips a FALSE "hung" alarm;
+  refresh the heartbeat every N items inside the loop (zero DB, safe
+  mid-transaction).
+- **A watchdog that RELAUNCHES the hung thread, not just logs** -- and
+  reports honestly whether it revived a dead thread or the thread is
+  alive-but-stuck (which needs a restart it cannot do from inside).
+- **Dedupe repeated alerts within a window** (one incident emitted 891
+  identical alerts, one per pass). Exclude genuinely unique events from
+  dedupe.
+- **Load-test as an acceptance gate.** Re-run the realistic peak and
+  compare deadlocks / orphaned handoffs / false-watchdogs / throughput
+  p50/p95 against a baseline; a hardening change does not "close" until
+  the numbers hold. You cannot tune what you do not measure -- and the
+  volumetry you assume is not the volumetry you have until measured.
+
+## The cross-cutting laws (apply to EVERY threshold you add)
+
+1. **Cero hardcode.** Every threshold -- cap, retry count, backoff, TTL,
+   timeout, poll interval, quota, sleep -- lives in config with a sane
+   clamp/floor. The DEFAULT preserves current behavior; a dangerous
+   feature is born INERT (0 / off) and hot-applied. A garbage value
+   collapses to the safe behavior, never to the risky one.
+2. **Producer/consumer symmetry.** When you change a producer, audit ALL
+   its consumers BEFORE the commit. Clamp the same value identically on
+   save (producer) and on read (consumer). Preview (dry-run) must walk
+   the EXACT same set and same locks as real execution -- the count shown
+   equals the count processed.
+3. **Never an external / network call inside an open transaction or a
+   retry.** This single rule prevents most lock storms AND all
+   double-sends / double-charges.
+4. **Fail-closed (cero dano silencioso).** On ambiguous or corrupt input,
+   collapse to the safe branch (manual review, no-op), never the
+   irreversible one. Lists are born empty, switches born off.
+5. **Measure first.** Before flipping a switch that fans out to real
+   users / resources, COUNT the burst it will release (how many are
+   queued right now). Benchmark before and after.
+6. **Proportionality.** Apply the pattern the component's real load
+   needs. A 20-user internal tool does not get a broker and sharding --
+   that is a defect too. Neither a bottleneck nor gold-plating. Size to
+   the number in the spec (see `concurrency-scale`).
+
+## When the numbers actually grow (the escalation ladder)
+
+Cheapest-first; each step only when volume demands it (details +
+sizing in `concurrency-scale`):
+
+1. Production WSGI server with a thread pool (removes the single-thread
+   web bottleneck -- highest return for lowest effort).
+2. Connection pool (stop opening/closing a connection per operation).
+3. **Queue-in-the-DB**: a "pending jobs" table on the DB you already run
+   -- gives enqueue, retry-with-wait, restart-survival, and models the
+   per-key lock as a ROW you lock, with zero new services (~80% of a
+   broker's benefit at ~20% of the operational cost).
+4. Split API vs Worker; move the in-process lock to a distributed lock
+   (DB `GET_LOCK()` / Redis) with a single active consumer per key.
+5. A real broker (RabbitMQ / Pub-Sub) with a dead-letter queue and
+   partitioning by the lock key; a circuit breaker so one failing
+   dependency does not take the rest down.
+
+The expensive part of distributing is NOT the broker -- it is preserving
+the per-key serialization/order invariant once the lock leaves the
+process. Do not reach for a broker to solve a problem a per-run cap and a
+queue-in-the-DB already solve.

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.0.89";
+export declare const VERSION = "1.0.90";
 //# 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.0.89';
+export const VERSION = '1.0.90';
 //# sourceMappingURL=version.js.map

package/docs/doctrine/concurrency-scale.md

@@ -52,3 +52,14 @@ the stated concurrency.
 
 Record the target concurrency and the tier decisions in the spec so
 they are traceable and can be revisited when the number changes.
+
+## 4. Then harden each component (see `performance-hardening`)
+
+This doctrine sizes the ARCHITECTURE. Sizing the tiers right does not
+save a component that holds a transaction open across a network call,
+runs a batch in one monolithic commit, hammers a non-idempotent third
+party, or grids a table with `LIKE '%q%'`. The construction-time
+pattern library -- commit-per-chunk, send-outside-transaction, deadlock
+retry, backpressure caps, server-side pagination, idempotency at the
+boundary, TTL cleanup, heartbeat/watchdog -- lives in
+`performance-hardening`. Size here; harden there.

package/docs/doctrine/performance-hardening.md

@@ -0,0 +1,213 @@
+# Performance & scale hardening doctrine
+
+Every load-bearing component MUST be built for its load in its FIRST
+version -- not hardened after it falls over in production. The brain
+defaults to the happy path: it writes the loop, calls the API, renders
+the grid, and stops. That is exactly how a component ships that
+saturates the DB, hammers a third party, or deadlocks under
+concurrency. This doctrine is the pattern library that closes that gap.
+
+Apply the patterns that the component's SHAPE triggers (below). This is
+the RUNTIME / construction complement to `concurrency-scale` (which
+sizes the ARCHITECTURE during relevamiento). Size the tiers there;
+harden each component here. Every rule below is battle-tested in a
+production HITL system, not theory.
+
+## How to use this: match the trigger, apply the pattern
+
+### Trigger 1 -- a component that WRITES to a DB in a loop or batch
+
+- **Commit per chunk, never one monolithic transaction.** A single
+  final commit over the whole run holds row/gap locks on every touched
+  table until the end, grows the undo log unbounded, and lets ONE
+  deadlock roll back the ENTIRE run. Commit per item (or per small
+  chunk): locks release continuously, a failure isolates to one item,
+  and the run becomes resumable.
+- **Never hold a transaction open across a slow side-effect (network /
+  external call).** Use the TWO-TRANSACTION pattern: TX1 = change state
+  + set an "in-flight" marker -> COMMIT (release locks) -> perform the
+  external call with NO transaction open -> TX2 = record the result +
+  clear the marker -> COMMIT. A crash between the COMMIT and the call
+  must be recoverable: build a sweeper that finds rows with the marker
+  set but no result, past a TTL, and re-queues them.
+- **Deadlock retry with backoff + jitter.** Classify transient errors
+  (MariaDB 1213 deadlock / 1205 lock-wait-timeout; SQLite "database is
+  locked") and retry the transaction with exponential backoff + jitter
+  (~6 attempts is a good default). Two variants: retry on a FRESH
+  connection (top-level request) vs retry a pure-DB sub-transaction on
+  the ALREADY-OPEN connection. **INVARIANT: never put an external call
+  inside a retry body** -- a redo would double-send / double-charge.
+- **Reserve -> confirm -> return for consumable resources.** Do not
+  decrement-then-hope-to-refund. Reserve at arming, confirm on success,
+  return on reject. The decrement MUST be a single atomic UPDATE guarded
+  so the balance never goes negative (multiple workers touch the same
+  row).
+- **Atomic counter / compare-and-swap, not read-modify-write, across
+  threads or workers.** `UPDATE ... SET flag=1 WHERE id=? AND flag=0`;
+  if rowcount=0 you lost the race, back off. Guard in-process shared
+  state with a lock (a multi-thread WSGI server runs N handlers).
+
+### Trigger 2 -- a component that CALLS a third party (API / provider / webhook)
+
+- **Assume NOT idempotent until proven.** Never auto-retry a
+  non-idempotent write. A firm reject goes to a dead-end + manual path,
+  NOT a burst of retries at a real person or resource. Gate any
+  auto-refire behind provider-confirmed idempotency OR a read-back that
+  proves the prior call did not land.
+- **Idempotency at the boundary = a UNIQUE constraint.** Dedupe by the
+  provider's real message/transaction id ON WRITE, not just on read.
+  Webhooks arrive "at least once" and may re-deliver even after your
+  ACK; an unconditional insert turns one event into six rows.
+- **ACK first, work after.** Answer the webhook immediately (202) and do
+  the slow work (notices, downstream calls) in a background thread /
+  queue. A slow response makes the provider time out and re-send ->
+  amplification (one real incident: 62 inbound images -> 36 real).
+- **Pace outbound explicitly.** Per-recipient minimum interval; a
+  time-window gate (do not contact outside allowed hours; exempt urgent
+  paths); a per-run quota + an inter-item sleep placed OUTSIDE any open
+  transaction. Respect the provider's rate limits as first-class config.
+- **Timeout-then-escalate; never wait forever.** After a bounded wait,
+  escalate or advance so nothing stays stuck. Advance on the FIRST of
+  several signals (read / reply / timeout), idempotently.
+- **The external latency and the human ARE the dominant time cost** --
+  far above the DB. Do not block the main thread on them; optimizing a
+  query that was never the bottleneck buys nothing.
+
+### Trigger 3 -- a background loop / scheduler / sweeper
+
+- **Backpressure: cap dispatches per pass.** A mass dump ("run it all
+  now") without a cap is a stampede that collides into deadlocks. A
+  configurable cap per pass drains the backlog in controlled batches and
+  keeps each pass under the watchdog threshold.
+- **One unit per key per pass** when exclusivity/order matters (e.g. one
+  message per recipient per sweep) so the loop never fires two at the
+  same target.
+- **Isolate each sweep in its own transaction + its own retry.** Do not
+  bundle several sweeps under one commit -- one deadlock then starves all
+  of them for the whole interval.
+- **Locks with a configurable TTL, keyed CORRECTLY.** An eternal lock is
+  a bug (a silent responder blocks the target forever). Key the lock by
+  the thing that must serialize (per type / per recipient / per delivery
+  target). Stamp each run with the SERVER-INSTANCE token so a recycled
+  PID after a restart does not leave the lock hung.
+- **Singletons start EXACTLY once**, guarded against double-start (a dev
+  reloader or two threads can otherwise launch two schedulers -> doubled
+  cron and doubled sends).
+
+### Trigger 4 -- a list / grid / export endpoint
+
+- **Server-side pagination**: LIMIT/OFFSET with an envelope
+  `{items, total, page, pages}` and a page_size cap. Filter the WHOLE set
+  server-side, THEN paginate -- never filter only the visible page.
+- **Export fetches the complete filtered/ordered set** via an explicit
+  flag (e.g. `?todo=1`), never by scraping the visible DOM page. The
+  page_size cap still protects the screen.
+- Never load the whole world into the client to render a view.
+
+### Trigger 5 -- a query on a table that GROWS
+
+- **Index every column that grows and is filtered / joined / sorted.** A
+  UNIQUE constraint IS an index -- do not double-index its leading
+  column, and do not "fix" a scan that already rides a UNIQUE.
+- **Never wrap an indexed column in a function inside WHERE / GROUP BY /
+  ORDER BY** (`substr(ts,1,10)=today`, `TRIM(col)=''`, `ORDER BY CASE`).
+  It disables the index. Rewrite to a RANGE (`ts >= day AND ts < next`),
+  normalize on write, or persist the sort key in its own indexed column.
+- **`LIKE '%q%'` (leading wildcard) is unindexable by a B-tree.** Use an
+  anchored prefix `q%` (indexable, "starts with") or a real full-text
+  index (MariaDB FULLTEXT / SQLite FTS). Free-text search at scale wants
+  an inverted index, not SQL LIKE.
+- **Engine portability: short indexed columns are VARCHAR(191), not
+  TEXT.** SQLite indexes TEXT happily and hides the bug; MariaDB errors
+  1071 "key too long" (and FK-on-TEXT errno 150). Test against the REAL
+  engine before prod (a pre-push barrier catches "key too long" before
+  the VM does).
+
+### Trigger 6 -- memory / large payloads / long work
+
+- **Do not load a whole file / dataset into memory** when you can stream
+  in chunks. Know the memory peak of each heavy operation and do not let
+  two heavy runs (import + browser bot + batch) overlap on one machine.
+- **Compress large payloads (gzip)** and raise size caps ONLY on the
+  specific admin endpoint, not globally.
+- **Long-running work -> background job + poll**, never inside the HTTP
+  request (that is a structural 504). Return `202 + id`; the client polls
+  a status endpoint. Guard it idempotently: a second start while one is
+  alive returns the SAME run.
+
+### Trigger 7 -- anything that accumulates (tables, files, logs)
+
+- **Every fast-growing table and disk accumulation needs a TTL cleanup**,
+  configurable, default OFF (never silent data loss). Bounded size keeps
+  queries fast and disk healthy. Beware: cleanup that deletes DB rows
+  often forgets the files they point to -- purge both.
+
+### Trigger 8 -- observability of the hardening itself
+
+- **Instrument retries.** Leave a trace when a retry saved a transaction,
+  so residual deadlocks are countable ("the retry doing its job, not an
+  error"), not invisible.
+- **Heartbeat per service + heartbeat MID-PASS.** A long pass over a big
+  backlog exceeds the liveness threshold and trips a FALSE "hung" alarm;
+  refresh the heartbeat every N items inside the loop (zero DB, safe
+  mid-transaction).
+- **A watchdog that RELAUNCHES the hung thread, not just logs** -- and
+  reports honestly whether it revived a dead thread or the thread is
+  alive-but-stuck (which needs a restart it cannot do from inside).
+- **Dedupe repeated alerts within a window** (one incident emitted 891
+  identical alerts, one per pass). Exclude genuinely unique events from
+  dedupe.
+- **Load-test as an acceptance gate.** Re-run the realistic peak and
+  compare deadlocks / orphaned handoffs / false-watchdogs / throughput
+  p50/p95 against a baseline; a hardening change does not "close" until
+  the numbers hold. You cannot tune what you do not measure -- and the
+  volumetry you assume is not the volumetry you have until measured.
+
+## The cross-cutting laws (apply to EVERY threshold you add)
+
+1. **Cero hardcode.** Every threshold -- cap, retry count, backoff, TTL,
+   timeout, poll interval, quota, sleep -- lives in config with a sane
+   clamp/floor. The DEFAULT preserves current behavior; a dangerous
+   feature is born INERT (0 / off) and hot-applied. A garbage value
+   collapses to the safe behavior, never to the risky one.
+2. **Producer/consumer symmetry.** When you change a producer, audit ALL
+   its consumers BEFORE the commit. Clamp the same value identically on
+   save (producer) and on read (consumer). Preview (dry-run) must walk
+   the EXACT same set and same locks as real execution -- the count shown
+   equals the count processed.
+3. **Never an external / network call inside an open transaction or a
+   retry.** This single rule prevents most lock storms AND all
+   double-sends / double-charges.
+4. **Fail-closed (cero dano silencioso).** On ambiguous or corrupt input,
+   collapse to the safe branch (manual review, no-op), never the
+   irreversible one. Lists are born empty, switches born off.
+5. **Measure first.** Before flipping a switch that fans out to real
+   users / resources, COUNT the burst it will release (how many are
+   queued right now). Benchmark before and after.
+6. **Proportionality.** Apply the pattern the component's real load
+   needs. A 20-user internal tool does not get a broker and sharding --
+   that is a defect too. Neither a bottleneck nor gold-plating. Size to
+   the number in the spec (see `concurrency-scale`).
+
+## When the numbers actually grow (the escalation ladder)
+
+Cheapest-first; each step only when volume demands it (details +
+sizing in `concurrency-scale`):
+
+1. Production WSGI server with a thread pool (removes the single-thread
+   web bottleneck -- highest return for lowest effort).
+2. Connection pool (stop opening/closing a connection per operation).
+3. **Queue-in-the-DB**: a "pending jobs" table on the DB you already run
+   -- gives enqueue, retry-with-wait, restart-survival, and models the
+   per-key lock as a ROW you lock, with zero new services (~80% of a
+   broker's benefit at ~20% of the operational cost).
+4. Split API vs Worker; move the in-process lock to a distributed lock
+   (DB `GET_LOCK()` / Redis) with a single active consumer per key.
+5. A real broker (RabbitMQ / Pub-Sub) with a dead-letter queue and
+   partitioning by the lock key; a circuit breaker so one failing
+   dependency does not take the rest down.
+
+The expensive part of distributing is NOT the broker -- it is preserving
+the per-key serialization/order invariant once the lock leaves the
+process. Do not reach for a broker to solve a problem a per-run cap and a
+queue-in-the-DB already solve.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nac3/forge-cli",
-  "version": "1.0.89",
+  "version": "1.0.90",
   "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>",