gina 0.6.12 → 0.6.13

package/llms.txt

@@ -132,6 +132,7 @@ module.exports = ApiContentController;
 - Auth is at `req.session.user` (NOT `req.user`).
 - Request data: `req.get` (GET query), `req.post` (POST body), `req.put` (PUT body), `req.patch` (PATCH body — partial update), `req.delete` (DELETE query), `req.head` (HEAD query — body suppressed). `req.body` aliases `req.post`/`req.put`/`req.patch`. Routes declared as GET automatically accept HEAD. PATCH vs PUT: PATCH sends only changed fields; PUT replaces the full resource. OPTIONS is CORS-only, never dispatched to a controller.
 - Routes declared in `routing.json`, not in code.
+- **No built-in API versioning, and no DB schema/data migration tool — both are deliberately the application's to own** (microservices audit #MS8-adjacent, docs 2026-08-21). There is no `version` route field and no version-aware dispatch: version with a URL prefix + a per-version `namespace` (each loads its own `controller.<ns>.js`), or with separate bundles when versions need their own deps/config/cadence. ⚠️ **`gina connector:migrate` is NOT a data migration** — it lints `connectors.json` (connection CONFIG) and `--fix` rewrites that JSON; it issues no SQL and has no `up`/`down`. Use your database's own tool (Flyway/Liquibase/Sqitch/Knex/`node-pg-migrate`), and run it as a discrete pre-start step (CI job, k8s `Job`/init container), never at bundle boot — a boot-time migration races itself across replicas and turns a schema error into a crash-loop. SQL files are validated at CALL time, not boot, so make changes additive during a rolling deploy.
 - Always null `local.req/res/next` at response exit (done automatically in render path).
 - `createTestInstance(deps)` creates an isolated instance for unit tests without touching production state.
 - `async` controller actions are fully supported — the router attaches `.catch()` to any thenable returned by an action and routes rejections to `throwError(response, 500, ...)`. Use `await entity.method()` directly. For PathObject ops and Shell use `await onCompleteCall(_(path).mkdir())`.
@@ -276,7 +277,7 @@ SELECT * FROM users WHERE id = $1 AND t._scope = $scope
 }
 ```
 
-Connectors supported: `couchbase` (v3/v4), `mysql` (mysql2), `postgresql` (pg), `redis`, `sqlite` (v2 ORM + session store), `scylladb` (cassandra-driver, ORM + session store), `mongodb` (official driver, ORM via `pipelines/<Entity>/*.json` + session store via TTL index), `ai` (LLM providers).
+Connectors supported: `couchbase` (v3/v4), `mysql` (mysql2), `postgresql` (pg), `redis` (store backend only: sessions, jobs, render-cache L2 — no ORM), `sqlite` (v2 ORM + session store), `scylladb` (cassandra-driver, ORM + session store), `mongodb` (official driver, ORM via `pipelines/<Entity>/*.json` + session store via TTL index), `ai` (LLM providers).
 All connector clients (`mysql2`, `pg`, `ioredis`, `couchbase`, `mongodb`, `cassandra-driver`, `openai`, `@anthropic-ai/sdk`) are loaded from the project's `node_modules` — zero framework runtime dependency. The driver-name → npm-package mapping lives in `lib/connector-registry/src/main.js` (single source of truth for `connector:add` / `connector:list` install hints).
 
 ## AI connector
@@ -428,6 +429,8 @@ Counters are live — no restart required. `activeSessions` is bounded by ≥ 0.
 
 **Settled streams are released at EVERY non-retry terminal (#B52, folds former #193).** The stream listeners capture the caller's callback → the per-request controller → its per-request config clone; on a non-retry terminal an idempotent finalize helper (cancel the stream timeout, remove the listeners, close the stream — each op try/catch'd so cleanup never breaks the response path) runs at all five terminals BEFORE the error-swallow check. Without it the settled stream — pinned by the cached, TTL-less HTTP/2 session — stranded the controller + its config clone until the session died: in dev mode (a distinct controller per request) sustained bursts piled clones toward the heap limit (~512 MB live heap from 300 requests in 7 s; ~95% removed by the fix; query-driven and render-agnostic). Retry branches destroy the whole session instead (which tears the stream down), and the pre-flight PING swallow sites have no request stream yet. Any new non-retry terminal in an HTTP/2 client handler must finalize AT the terminal, not on eventual socket death.
 
+**Per-authority circuit breaker (#MS5, opt-in — settings.json `server.query.circuitBreaker`).** After N consecutive transport-class failures to one authority (default `failureThreshold: 5` — each failure already representing a call whose own retries were exhausted), the circuit OPENS and every further `self.query()` to that authority fails fast with a `GinaCircuitOpenError` (`code: 'CIRCUIT_OPEN'`, `status: 503`, `retryable: false`, plus `authority` and `retryAfterMs`) instead of hammering a dead upstream. After `cooldown` (default `"30s"`, `parseTimeout` format) exactly ONE critical request is admitted as the half-open probe — success closes the circuit, a transport failure re-opens it with a fresh cooldown. The gate sits ABOVE the HTTP/1.x / HTTP/2 protocol dispatch, so an open circuit rejects before any connection, retry or pre-flight machinery runs (the #B34/#B52/#B53 invariants are untouched, and retries can never hammer an open circuit). Only transport-class errors count: every `GinaHttp2Error` plus the socket-level `ECONN*` family on `err.code`/`err.cause.code` — an application response, whatever its status, flows through the success terminus as data, and a caller bug is NEUTRAL (neither trips nor resets). Only a CRITICAL request may probe: a non-critical failure is swallowed by the H3 contract (its callback never fires), so a non-critical probe would wedge the half-open state. Non-critical calls rejected while open are swallowed log-only, mirroring H3. Breaker state is per `hostname:port` on the engine instance (the `_http2Sessions` home — dev mode re-requires the controller per request, so anywhere else would reset on hot-reload); it resets on bundle restart. Dormant unless `enabled` is strictly `true`; structurally invalid values on an enabled block REFUSE the boot. Policy is resolved once at engine start (settings.json's `server.query` folds with env.json keys winning, #B114 semantics) — config changes need a bundle restart. Tests: `query-circuit-breaker.test.js`.
+
 **GOAWAY logging** — when a cached HTTP/2 session receives a GOAWAY frame, the handler logs `console.warn('[http2] GOAWAY received — errorCode: X, lastStreamID: Y, session: Z')`. `errorCode` distinguishes clean server restarts (0 = NO_ERROR) from protocol errors (e.g. 1 = PROTOCOL_ERROR, 11 = ENHANCE_YOUR_CALM). `lastStreamID` indicates which streams were processed before the GOAWAY.
 
 ---
@@ -590,7 +593,7 @@ gina bundle:list @<project> --format=json  # JSON payload with ports, running, p
 gina bundle:status <bundle> @<project>   # Status of one bundle (running/stopped, pid, port, env)
 gina project:status @<project>           # Status of every bundle in a project (all projects if omitted)
 gina project:status --format=json        # JSON payload: per-project array of bundle status objects
-gina service:list                       # List framework-internal services (@gina-only)
+gina service:list                       # List framework-internal services (@gina-only; the services/ tree is CLI-generated, gitignored AND npmignored, so a released install lists nothing until it exists locally — `inspector` is the one maintained service. gina ships NO edge/reverse proxy by design (#MS8): front bundles with nginx/Traefik/ingress, the topology the auth, rate-limiting and K8s guidance already assume)
 gina service:list --format=json         # JSON payload with ports, running, pid per service
 gina connector:list                     # List connectors across every registered project (read-only)
 gina connector:list @<project>          # List one project (shared + all bundles)
@@ -1020,4 +1023,11 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 311. **Concurrent `promisify(entity.method)` calls are FIFO-paired, never scalar-overwritten (#B394, shipped in 0.6.11) — `core/model/entity.js`.** The `util.promisify` fast-path (taken when a method is called detached — `this[m]` undefined + trailing function arg) used to back its pending callback into a SCALAR slot (`entity._callbacks[shortName] = cb`) plus a per-call `.once` guarded on that slot. Two concurrent calls on the SAME method raced on the one slot: the second overwrote the first, the first-arriving result was flushed to the LAST-registered callback (cross-delivery — caller B receives caller A's record), and the displaced caller's `.once` found its guard false so its promise NEVER settled (starvation — a hung request, nothing logged; the write-path variant silently persists A's document under B's key). Option B (entity-context calls) had already been given a FIFO queue + one persistent `.on` dispatcher (#M2); the fast-path kept the scalar because its own comment claimed it "bypasses queue". Now it uses the same shape: push each invocation's callback onto `entity._callbacks[shortName]` (an array), register ONE persistent `_onFpQueueEmit` dispatcher (guarded on `listenerCount === 0`) that shifts the OLDEST callback per emit and removes itself when the queue drains. The custom `emit`'s third guard already routes an ARRAY slot straight to native emit (skips `setListener` when `!Array.isArray`), so the `.on` listener receives the emit args directly. Guarantees: **starvation ELIMINATED** (no callback is ever orphaned); **cross-delivery CLOSED for in-order completion** (arrival order == call order → each caller its own result). **Residual, identical to Option B: OUT-OF-ORDER completion swaps results** (FIFO pairs by arrival order). The documented way to get true per-call identity is to have the method RETURN a Promise (resolved via `_innerResult.then()`) instead of emitting — see the Models guide's concurrency note. Framework-internal `promisify` sites (`controller.js` `self.query`, `form-validator.js`) promisify a CONTROLLER method, not an entity trigger, so they never enter this branch (gated on `entity._triggers`). Server-side only — NOT browser-bundled, so pickup is a bundle RESTART, no re-bake. Test `test/core/entity-promisify-concurrency.test.js` (4 arms, bounded-settle so a regression fails rather than hangs; red-first validated against pre-fix bytes — serial control green, the three concurrency arms red).
 
-312. **`Collection.find()`/`findOne()`/`or()`/`update()` refuse undefined-valued filter keys — the silent match-all is closed (#B396, gh issue #65, shipped in 0.6.12).** `find()` round-trips its filter objects through `JSON.stringify(arguments)`/`JSON.parse`, and stringify silently DROPS keys whose value is `undefined` — so `findOne({ id: source.missingId })` degraded to the match-everything `{}` filter and returned the collection's FIRST row (an arbitrary, plausible-looking wrong record), a mixed filter silently lost its undefined constraint, and `update({ id: undefined }, set)` wrote `set` onto EVERY record. The in-loop guard deeper in the matcher (message: ``filter `<key>` cannot be left undefined``) was written to refuse exactly this input but was DEAD CODE — the serialization stripped the keys before the loop could see them (JSON.parse can never produce an `undefined` value). The fix hoists the refusal to `find()`'s entry, BEFORE the round-trip; `findOne`, `or` and `update` all delegate to `find`, so the one gate covers the family. Deliberately unchanged: an explicitly EMPTY `{}` filter still means "no constraint" (match-all), `null` stays a legal needle comparing strictly against stored values (matches stored `null`), array arguments are skipped (record sets, not needles), and `notIn`/`delete` never had the defect (no JSON strip on that path). By-catch hardening: the FormValidator's conditional-case rules lookup (`findOne({ case: fields[caseName] })`) could silently merge the FIRST condition's rules when the case field was absent from the form — the refusal now routes that state into the lookup's own designed catch-and-skip (its warn already said "undeclared or misconfigured case"). Behaviour change for consumers relying on undefined-key-means-no-constraint: build filters conditionally (add a key only when its value is defined). **`lib/collection` IS in the browser `build.json`, so pickup is a bundle RESTART **and** a re-bake.**
+312. **Every `Collection` method that accepts a filter object refuses undefined-valued filter keys — the silent match-all is closed (#B396, gh issue #65, shipped in 0.6.12).** `find()` round-trips its filter objects through `JSON.stringify(arguments)`/`JSON.parse`, and stringify silently DROPS keys whose value is `undefined` — so `findOne({ id: source.missingId })` degraded to the match-everything `{}` filter and returned the collection's FIRST row (an arbitrary, plausible-looking wrong record), a mixed filter silently lost its undefined constraint, and `update({ id: undefined }, set)` wrote `set` onto EVERY record. The in-loop guard deeper in the matcher (message: ``filter `<key>` cannot be left undefined``) was written to refuse exactly this input but was DEAD CODE — the serialization stripped the keys before the loop could see them (JSON.parse can never produce an `undefined` value). The fix hoists the refusal to `find()`'s entry, BEFORE the round-trip; `findOne`, `or` and `update` all delegate to `find`, so the one gate covers the family. Deliberately unchanged: an explicitly EMPTY `{}` filter still means "no constraint" (match-all), `null` stays a legal needle comparing strictly against stored values (matches stored `null`), array arguments are skipped (record sets, not needles), and `notIn`'s ARRAY form (`notIn(rows, key)`) is unaffected because it skips `find()` entirely. ⚠️ Every OTHER filter-object entry point IS covered, including four this entry originally excluded by mistake: `notIn({…})` routes a filter-object argument straight into `find()` (`main.js:869`), `delete()` is a pure delegation to `notIn()` (`:1297`), and `replace()` (`:1199`) and `max()` (`:1373`) call `find()` too — so the covered family is EIGHT entry points, not four. Pre-fix consequences on the four that went undocumented were the worst of the set: `delete({ id: undefined })` returned an EMPTY collection (every record removed — it returns a filtered COPY, so the loss lands in the returned value, not in-place) and `max({ k: undefined })` aggregated over the whole collection instead of the filtered subset. Measured on the published `v0.6.11` vs `v0.6.12` trees with controls; no internal framework caller can pass undefined (two independent sweeps: zero live `notIn`/`replace`/`max` sites, and the two `delete` sites — `lib/proc.js:614`, `core/config.js:2887` — are each structurally string-valued or dominated by an identical-filter `findOne` that throws first). By-catch hardening: the FormValidator's conditional-case rules lookup (`findOne({ case: fields[caseName] })`) could silently merge the FIRST condition's rules when the case field was absent from the form — the refusal now routes that state into the lookup's own designed catch-and-skip (its warn already said "undeclared or misconfigured case"). Behaviour change for consumers relying on undefined-key-means-no-constraint: build filters conditionally (add a key only when its value is defined). ⚠️ That recipe is ONLY for the no-constraint intent — for a LOOKUP BY A POSSIBLY-ABSENT KEY (`if (!col.findOne({id: maybeAbsent}))`, `col.findOne({id: maybeAbsent}) || fallback`) it is the WRONG migration: an empty filter matches everything and returns the FIRST row, so the guard reads "found" and the fallback never runs — measured. Guard the CALL instead: `var row = (id != null) ? col.findOne({id: id}) : null;`. **`lib/collection` IS in the browser `build.json`, so pickup is a bundle RESTART **and** a re-bake.**
+
+313. **Redis is a store backend only — no entity/ORM wiring, by design.** The redis connector class is deliberately empty: it backs FOUR purpose-bound subsystems, each minting its OWN client — the session store (`lib.SessionStore`), the async-job store (`app.json` `jobs.store`), the render-cache L2 (`settings.json` `server.cache` `type: "redis"`), and — since #KV1 slice 1 — a KV namespace backend (`settings.json` `kv.namespaces.<name>.store`; entry 314), one client PER NAMESPACE. Client failure policy diverges per subsystem by design — the render-cache L2 sets `enableOfflineQueue: false` plus a `commandTimeout` so an outage fails page-serving open instead of hanging every request, while the job store keeps ioredis's default offline queue on, and the KV store imposes NEITHER: it passes those knobs through from the `connectors.json` entry so the operator tunes per namespace (a `failMode: "open"` namespace wants the fail-fast trio; a `closed` one usually wants the queue). NON-KV redis use — data structures, pub/sub, third-party queue libraries — stays app-owned by design: it is outside the KV contract, so an app needing it reads its `connectors.json` entry via `getConfig()` and mints its own ioredis client. Redis operations do NOT appear in the Inspector's query log: `_devQueryLog` capture hangs off the entity query path, which this connector deliberately does not implement; a render-cache L2 hit is instead observable per response via the RFC 9211 `Cache-Status` header. Per-operation Inspector capture of redis store traffic was evaluated 2026-08-21 and demand-gated (measured consumer demand: zero); if demand arrives, the evidenced shape is a store-reachability/lifecycle signal on the events channel (with app-registered clients joining the same signal), not query-log wiring.
+
+314. **General-purpose KV primitive (#KV1) — `gina.kv('<namespace>')`, strict-declared namespaces over pluggable per-namespace backends (`settings.json > kv`).** Declare namespaces under `kv.namespaces` (`{ "kv": { "default": "cache", "namespaces": { "cache": { "failMode": "open" }, "tokens": {} } } }`); `gina.kv(name)` THROWS on an unconfigured block or unknown name (the throw is what surfaces a typo — the `gina.storage()` stance), and the whole feature is dormant when the block is absent. Namespaces are process-global, read once at boot from the STARTING bundle's settings. The handle is promise-native with 13 ops: `get` / `set(k, v, {ttl})` / `del` / `has` / `ttl(k)` (null=miss, -1=no expiry, else remaining ms) / `expire(k, ttlMs)` / `setnx` (set-if-absent) / `consume` (atomic read-AND-delete — the one-shot-token op; the second reader gets null) / `incr` / `decr` (integer counters; `{ttl}` applies on CREATE only; non-integer values and safe-range overflow reject) / `delIfEquals` (compare-and-delete — the safe lock-release primitive; compose with `setnx` for lock recipes) / `clear()` / `getOrSet(k, {ttl}, loader)` (fetch-or-compute with per-process single-flight; no negative caching). Value model: JSON-serialized; `undefined` AND `null` are REFUSED on every write (a stored null would be indistinguishable from a miss — store a wrapper or use `del()`); TTLs are MILLISECONDS, positive integers only — `ttl: 0` refuses rather than meaning no-expiry. Per-namespace `failMode`: `closed` (default) rejects on backend errors; `open` degrades every op to its miss-shaped result with a warning (cache-like namespaces) — consulted on backend errors only, so it becomes operative with connector-backed stores. THREE backends ship, differing by SHARING SCOPE. **In-memory** per namespace (zero config; lazy expiry plus an unref'd sweep, `sweepInterval` ms, default 30000) — SINGLE-PROCESS, lost on restart. **SQLite** (`core/connectors/sqlite/lib/kv-store.js`, #KV1 slice 2) — zero npm deps via the `lib/sqlite-driver` seam (node:sqlite, `bun:sqlite` adapter under Bun), DURABLE across restarts and shared across PROCESSES on ONE HOST; namespaces sharing a file are isolated by a composite `(ns, key)` primary key rather than a prefix, `clear()` is one namespace-scoped DELETE, and every read-modify-write verb runs inside `BEGIN IMMEDIATE`/`COMMIT` — the synchronous driver makes a verb indivisible only WITHIN a process, which is precisely the guarantee that fails once a second process opens the file, i.e. the reason to pick this backend at all. **Redis** — shared across HOSTS. **Redis** (`core/connectors/redis/lib/kv-store.js`, #KV1 slice 1): point a namespace's `store` at a `connectors.json` entry and the `lib/kv-store` dispatcher resolves `core/connectors/<connector>/lib/kv-store.js`; naming a connector that has none still REFUSES the boot rather than degrading silently to memory (the others arrive demand-first, the audit-store shipping order). The redis backend keeps every guarantee server-side: `SET .. PX .. NX` for setnx, `GETDEL` for consume when the server has it (>= 6.2) with a **Lua fallback below that — never a GET+DEL pair**, which would let two concurrent readers both redeem; Lua also for compare-and-delete and for TTL-on-CREATE-only counters (`n === by` is a racy proxy for "was created", so existence is checked inside the script). Keys are prefixed `kv:<namespace>:` by default, so two namespaces may share one entry; cluster prefixes are deliberately NOT hash-tagged (every KV op is single-key, and tagging would pin a namespace to one slot — the opposite of the job store, whose MULTI/SUNION/MGET require the tag), so `clear()` scans each master node and deletes per key rather than assuming one slot. Connection policy (`commandTimeout`/`maxRetriesPerRequest`/`enableOfflineQueue`) is passed through from the entry and otherwise left at ioredis's defaults — deliberately NOT the render-cache's fail-fast tuning, because the right policy depends on the namespace's `failMode`. Deliberate boundary — NOT a redis client: no data structures (lists/hashes/sets/streams/pub-sub), no batch `mget`/`mset`, no key scanning (use `clear()` or track your own keys), no binary values (the storage layer owns bytes), no first-class distributed locks (compose `setnx` + `delIfEquals`; a lock API done right needs fencing/renewal policy no half-primitive should imply). `lib/kv` is framework-independent (config, connector stores and the warn sink are injected by gna.js at boot; `test/lib/kv-import-boundary.test.js` enforces the boundary) and plain-require'd (its namespace registry and sweep timers survive dev-mode refreshCore). Server-side only — NOT browser-bundled, so pickup is a bundle RESTART, no re-bake.
+315. **Rate limiting (#MS6) — identified-caller quotas at the router band.** Opt-in via settings.json `server.rateLimit` (`enabled` strictly true, `namespace`, `keyField`, `limit`, `window`; folded into the runtime server block with env.json keys winning, resolved once at engine start onto the instance, so changes need a bundle restart; structurally invalid values on an enabled block refuse the boot). QUOTA semantics, not flood control: the gate runs AFTER route authorization (`authorizeRequest` is the principal resolver — the only writer of `req.machineCaller`, and session identity is its predicate) and BEFORE DTO validation, so the order is 401 -> 429 -> 422 and a throttled caller never receives a 422 field map. A request with NO resolvable principal is SKIPPED, never bucketed — anonymous flood control belongs to the edge proxy and the #H9 HTTP/2 rapid-reset guard, and IP-keying is dishonest behind a proxy (every socket.remoteAddress is the proxy's). Keys: `u:<session.user[keyField]>` for signed-in callers (the field is operator-named because session.user is app-owned shape; an absent/empty value means unidentified => skipped) and `m:<machineCaller.name>` for #MS3 machine callers; session wins, mirroring the authz gate; values over 180 chars are sha256-hexed under the kv 512-char key cap. Counters are FIXED WINDOWS over the #KV1 primitive — `incr(key, 1, {ttl: windowMs})`, TTL-on-create-only, race-free in all three backends — so choosing the namespace's backend chooses the quota's SCOPE: in-memory counts PER PROCESS (each replica grants the quota again; the resolver warns), redis/sqlite share across replicas/processes. For a redis-backed namespace set `enableOfflineQueue: false` + `commandTimeout` on the connectors entry (the render-cache L2 fail-fast trio; with ioredis defaults an outage QUEUES every gated request so neither failMode ever fires — the resolver warns about this too). Outage policy IS the namespace's `failMode`: `open` => incr degrades to null and the gate ALLOWS without headers (the explicit `count === null` check is load-bearing — `null <= limit` is true by coercion); `closed` => the rejection is owned and answers 503 + Retry-After (the caller is NOT over quota). Denials answer 429 via `controller.throwError` with Retry-After (from the store's own ttl — one extra read on the throttled path only) plus the draft-ietf-httpapi-ratelimit-headers-11 structured fields (`RateLimit: "<policy>";r=<remaining>[;t=<sec>]`, `RateLimit-Policy: "<policy>";q=<limit>;w=<windowSec>`); allowed limited requests carry both without `t` (reporting it honestly would cost a second read per request and the parameter is optional). Per-route overrides are TOP-LEVEL routing.json keys (never under `param` — the #CSRF2 trap), propagated by BOTH route builders (cold typeof-guarded — `false` is meaningful — and the warm cached-route opt-in copy): `"rateLimit": false` exempts the route; `{limit, window}` REPLACES the default for that route in its OWN bucket (`<principal>:<rule>`), partial objects inherit the missing key; shapes are linted at boot (a malformed value refuses the boot — the DTO registrar doctrine). Dormant => the dispatch band runs today's exact synchronous path with ZERO promises minted; armed, every terminal of the verdict promise is owned (allow -> band, deny/outage -> answered inside the gate) so a store failure can never strand a request. Implementation: `lib/rate-limit` (plain-required, router-bound), wired in `core/router.js` at both dispatch sites; server-side only, but the route-flag propagation lives in browser-bundled `lib/routing`, so the release carries a dist rebuild (dead code client-side). Tests: `test/core/rate-limit.test.js` (45 — source pins on every seam, resolver refusal/warn matrix, gate behaviour over a scripted namespace, 5 mutation controls fired red-first).
+316. **Reserved-action controller hooks (`onReady`, `setup`) — dispatch semantics + the #B399 ownership guard** — Before the main action, `core/router.js` dispatches the two reserved hooks at BOTH dispatch sites (with- and without-middleware), in order, synchronously, without awaiting: an app defines `this.onReady = function(req, res, next){...}` on the controller, and `setup` resolves through a framework-synthesized wrapper that requires the bundle's `controllers/setup.js` once per controller instance (the wrapper returns the app call's own result). Since #B399, both hook loops run INSIDE the dispatch try and each hook's return value is captured — a thenable gets a `.catch` routing to `throwError(response, 500, ...)` naming the failing hook, the same guard shape the main action dispatch carries. Consequences: a SYNC hook throw answers 500 (previously it escaped to process level — on the built-in engine that was uncaughtException → emerg + SIGTERM, killing the whole bundle; Express's layer-catch answered its own 500 — engine-asymmetric); an ASYNC hook rejection answers 500 when it lands before the response is released, and degrades to the #ERRREF pairing log line when the action already responded (`throwError` is `!headersSent`-guarded). Ordering caveat: hooks are dispatched in the same synchronous frame as the action (never awaited), so a rejecting async hook does NOT prevent the action from running — its side effects still execute even when the wire answers 500; hooks are not a gating mechanism (use route middleware, route authorization, or DTO validation to refuse a request before the action). Sync or absent hooks mint zero promises — dispatch timing is unchanged for every controller that does not return a thenable from a hook.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "description": "MVC framework for Node.js and Bun with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -76,12 +76,12 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.6.12/core/gna",
+  "main": "./framework/v0.6.13/core/gna",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "import": "./index.mjs",
-      "require": "./framework/v0.6.12/core/gna.js"
+      "require": "./framework/v0.6.13/core/gna.js"
     },
     "./gna": {
       "types": "./types/gna.d.ts",

package/schema/routing.json

@@ -126,6 +126,36 @@
             "enum": ["local", "beta", "production", "testing"]
           }
         },
+        "csrfExempt": {
+          "type": "boolean",
+          "default": false,
+          "description": "Per-route opt-out for the Csrf middleware (#CSRF2) -- webhook receivers and other endpoints that legitimately arrive without the double-submit token. Propagated to `req.routing.csrfExempt` (top-level, not under `param`)."
+        },
+        "rateLimit": {
+          "description": "Per-route override for the #MS6 identified-caller quota gate (active only when settings.json `server.rateLimit.enabled` is true). `false` exempts the route entirely. An object REPLACES the default policy for this route -- its requests count in their OWN bucket, not against the global one; a partial object inherits the missing key from the default. Shapes are linted at boot: a malformed value refuses the boot, a typo surfaces at deploy rather than at first request. Top-level on the route, not under `param`.",
+          "oneOf": [
+            {
+              "type": "boolean",
+              "enum": [false],
+              "description": "Exempt this route from quota enforcement."
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "limit": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Requests allowed per principal per window on this route."
+                },
+                "window": {
+                  "type": ["string", "integer"],
+                  "description": "Window length for this route (\"30s\", \"1m\", or milliseconds)."
+                }
+              }
+            }
+          ]
+        },
         "negotiate": {
           "type": "boolean",
           "default": false,

package/schema/settings.json

@@ -336,6 +336,67 @@
               "description": "How a rebuild restarts the process. daemon (default): drain, then spawn `gina bundle:restart` (needs the framework daemon). supervisor: drain, then exit(0) for a container/orchestrator to respawn — the daemonless `gina-container` launch path; requires a restart-on-clean-exit policy (a k8s Deployment or `docker run --restart=always` qualifies; `--restart=on-failure` does not)."
             }
           }
+        },
+        "rateLimit": {
+          "type": "object",
+          "description": "Identified-caller quota enforcement at the router band (#MS6). Opt-in: dormant unless `enabled` is strictly true. Runs AFTER route authorization (the principal resolver) and BEFORE DTO validation, so the order is 401 -> 429 -> 422; a request with NO resolvable principal (no session user, no machine caller) is SKIPPED, never bucketed -- anonymous flood control belongs to the edge proxy and the HTTP/2 rapid-reset guard, not here. Fixed-window counters live in the kv namespace this block names, so choosing the namespace's backend chooses the quota's SCOPE: in-memory counts per process; replica-shared quotas need a redis- or sqlite-backed namespace (the resolver warns about a memory backend, and about a redis entry missing `enableOfflineQueue: false` + `commandTimeout` -- with ioredis defaults an outage QUEUES gated requests instead of degrading). Outage policy is the namespace's own `failMode`: `open` allows without headers, `closed` answers 503 + Retry-After. Denials answer 429 + Retry-After plus the draft-ietf-httpapi-ratelimit-headers-11 structured fields (`RateLimit`, `RateLimit-Policy`); allowed limited requests carry them too (without `t`). Per-route overrides ride routing.json's top-level `rateLimit` key (`false` = exempt; `{limit, window}` REPLACES the default for that route in its own bucket). Folded from settings.json into the runtime server block (env.json keys win); resolved once at engine start, so changes need a bundle restart. Structurally invalid values on an enabled block refuse the boot.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Arm the quota gate. Must be strictly true; any other value (including the string \"true\") leaves it dormant."
+            },
+            "namespace": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The kv namespace holding the counters. Must be DECLARED under `kv.namespaces` -- an undeclared name refuses the boot. Give the limiter its OWN namespace: its `failMode` is then unambiguously the limiter's outage policy."
+            },
+            "keyField": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The `session.user` property that identifies a signed-in caller (e.g. \"id\"). Required because the session user is app-owned shape -- a guessed default would mis-key silently. Machine callers (#MS3) key on their registered name automatically; a user record where this field is absent/empty is unidentified and SKIPPED."
+            },
+            "limit": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Requests allowed per principal per window (the default policy). A structurally invalid value on an enabled block refuses the boot."
+            },
+            "window": {
+              "type": ["string", "integer"],
+              "description": "Window length. Accepts \"1m\", \"30s\", \"500ms\" or a number of milliseconds; must be positive. An unparseable value on an enabled block refuses the boot."
+            }
+          }
+        },
+        "query": {
+          "type": "object",
+          "description": "Outbound client policy for Controller::query(). Folded from settings.json into the runtime server block (env.json keys win, settings.json fills what env.json lacks).",
+          "additionalProperties": false,
+          "properties": {
+            "circuitBreaker": {
+              "type": "object",
+              "description": "Per-authority circuit breaker for query() (#MS5). Opt-in: dormant unless `enabled` is strictly true. Gates BOTH client paths (HTTP/1.x and HTTP/2) above the protocol dispatch, so an open circuit rejects with a machine-readable CIRCUIT_OPEN error (status 503, retryable false) before any connection, retry or pre-flight attempt. State is per `hostname:port`, lives on the engine instance (resets on bundle restart) and transitions closed -> open -> half-open lazily, with a single critical-request probe per cooldown. Config changes need a bundle restart (resolved once at engine start).",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Arm the breaker. Must be strictly true; any other value (including the string \"true\") leaves it dormant.",
+                  "default": false
+                },
+                "failureThreshold": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Consecutive transport-class failures (per authority, after each call's own retries are exhausted) that open the circuit. A structurally invalid value on an enabled block refuses the boot.",
+                  "default": 5
+                },
+                "cooldown": {
+                  "type": ["string", "integer"],
+                  "description": "How long an open circuit rejects before admitting one half-open probe. Accepts \"30s\", \"500ms\", \"1m\" or a number of milliseconds; an unparseable value on an enabled block refuses the boot.",
+                  "default": "30s"
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -492,6 +553,46 @@
         }
       }
     },
+    "kv": {
+      "type": "object",
+      "description": "General-purpose key-value primitive (#KV1) — strict-declared NAMESPACES reached from application code as gina.kv('<name>') / gina.kv(). Values are JSON-serialized; null and undefined are refused on every write (a stored null would be indistinguishable from a miss). TTLs are MILLISECONDS and must be positive — ttl: 0 refuses rather than meaning no-expiry. Namespaces are process-global, read once at boot from the STARTING bundle's settings; the whole feature is dormant when this block is absent, and gina.kv() then throws a named error. Deliberately NOT a redis client: no data structures, no batch ops, no key scanning, no binary values.",
+      "additionalProperties": false,
+      "properties": {
+        "default": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Namespace returned by a no-argument gina.kv(). Must name an entry in `namespaces` — a default pointing at an undeclared namespace refuses the boot. Omit it and every call must name its namespace explicitly."
+        },
+        "namespaces": {
+          "type": "object",
+          "description": "KV namespaces, keyed by name (^[A-Za-z][A-Za-z0-9._-]*$). Each namespace owns its backend and failure policy; {} declares a plain in-memory namespace. Unknown per-namespace keys are ignored with a boot warning naming them, because a silently-dropped key reads as configured behaviour that never happens.",
+          "additionalProperties": false,
+          "patternProperties": {
+            "^[A-Za-z][A-Za-z0-9._-]*$": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "store": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "connectors.json entry name backing this namespace. The entry's `connector` field selects the implementation (core/connectors/<connector>/lib/kv-store.js); a connector without one refuses the boot rather than degrading silently to memory. Omit for the in-memory backend. The redis connector (shared across hosts) and the sqlite connector (zero-dependency, durable, shared across processes on one host) both implement one; the others arrive demand-first."
+                },
+                "failMode": {
+                  "type": "string",
+                  "enum": ["closed", "open"],
+                  "description": "Backend-error policy. closed (default): a backend error rejects the call. open: every op degrades to its miss-shaped result with a warning — for cache-like namespaces where availability beats consistency. Consulted on backend errors only (validation errors always reject); the in-memory backend does not error, so the knob becomes operative with connector-backed stores."
+                },
+                "sweepInterval": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Milliseconds between expired-entry sweeps for the in-memory backend (default 30000). Expired entries are also dropped lazily on read, so the sweep bounds memory, not correctness."
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "storage": {
       "type": "object",
       "description": "Pluggable object storage (#STO1) — an adapter (where bytes live) crossed with a strategy (how keys are laid out), behind one callback-shaped contract. Reached from application code as gina.storage() / gina.storage('<name>'). Keys are OPAQUE: store the key a put() returns, never parse or compose one. Boot config — changes need a bundle restart, and every shape here is linted UNCONDITIONALLY, because unlike a cache a storage layer has no safe degraded mode: a driver that cannot build would leave put() writing nowhere. Since slice 1 an upload group may route its self.store() step through a driver (upload.groups.<name>.driver); the multipart parse/staging path is otherwise untouched.",

package/types/index.d.ts

@@ -796,6 +796,8 @@ declare namespace gina {
         Domain: any;
         /** Job persistence dispatcher (`app.json > jobs.store`). */
         JobStore: any;
+        /** Connector-backed KV namespace-store dispatcher (`settings.json > kv.namespaces.<name>.store`) (#KV1). */
+        KvStore: any;
         Model: any;
         Proc: any;
         /**
@@ -862,6 +864,8 @@ declare namespace gina {
         instrument: any;
         /** Async-job primitive behind `self.startJob()` / `/_gina/jobs/:id`. */
         job: any;
+        /** General-purpose KV primitive — strict-declared namespaces behind gina.kv() (`settings.json > kv`) (#KV1). */
+        kv: any;
         jsonConfigHeader: any;
         logger: any;
         /**
@@ -884,6 +888,8 @@ declare namespace gina {
         netLocality: any;
         nunjucksFilters: any;
         nunjucksResolver: any;
+        /** Identified-caller quota gate — fixed-window counters over the kv primitive, run by the router between authz and the DTO pipe (#MS6). */
+        rateLimit: any;
         /** Stale built-release watch primitives — source-tree fingerprints, change classification, busy probes and the in-flight request gauge (#RWATCH). */
         releaseWatch: any;
         routing: {
@@ -1031,6 +1037,9 @@ declare namespace gina {
     /** Get a configured object-storage driver; omit `name` for `storage.default`. Throws when storage is unconfigured or the name is unknown (#STO1). */
     function storage(name?: string): any;
 
+    /** Get a configured KV namespace; omit `name` for `kv.default`. Throws when kv is unconfigured or the name is unknown (#KV1). */
+    function kv(name?: string): any;
+
     /**
      * Push a payload to ONE named session from outside a request (#B366) — for
      * code with no live controller (job handlers, cron, boot hooks).

package/framework/v0.6.12/VERSION

@@ -1 +0,0 @@
-0.6.12

package/framework/v0.6.12/core/connectors/redis/index.js

@@ -1,36 +0,0 @@
-/*
- * This file is part of the gina package.
- * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-'use strict';
-
-/**
- * Redis connector — v1: session store + job store (no entity/ORM wiring).
- *
- * Entity/ORM wiring is not implemented in v1. Use this connector as:
- *   - a session store backend via `lib.SessionStore`
- *     (see: core/connectors/redis/lib/session-store.js), or
- *   - an async-job store backend via `app.json`'s `jobs.store`
- *     (see: core/connectors/redis/lib/job-store.js).
- *
- * To configure:
- *   1. Add a `redis` entry to `config/connectors.json` in your bundle.
- *   2. Install ioredis in your project: `npm install ioredis`
- *   3. Wire the store: session store in `bundle/index.js`, job store via
- *      `app.json` `{ "jobs": { "store": "<entry name>" } }`.
- *
- * The boot-time model scan is satisfied by the no-op `lib/connector.js`
- * (no connection is opened at boot — each store owns its client).
- * ORM / entity support is planned for a future release.
- *
- * @class Redis
- * @constructor
- */
-var Redis = function Redis() {
-    // v1: no entity wiring — session store + job store only
-};
-
-module.exports = Redis;