gina 0.6.12 → 0.6.13

package/framework/v0.6.13/core/connectors/sqlite/lib/kv-store.js

@@ -0,0 +1,316 @@
+/*
+ * 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';
+
+/**
+ * @module gina/core/connectors/sqlite/kv-store
+ * @description SQLite backend for the general-purpose KV primitive (#KV1,
+ * slice 2) — the zero-dependency durable backend, sitting between the
+ * in-memory default (fast, process-local, lost on restart) and redis (shared
+ * across hosts, needs a server).
+ *
+ * Backed by `node:sqlite` through the shared `lib/sqlite-driver` seam (the
+ * built-in on Node, a `bun:sqlite` adapter under Bun), the same substrate as
+ * `lib/state`, the SQLite session/job stores and the storage metadata store.
+ *
+ * **What it buys over memory:** namespace contents survive a bundle restart,
+ * and any process opening the same file sees them — so a single-host
+ * multi-bundle deployment can share a namespace without running redis. **What
+ * it does not buy:** cross-HOST sharing; that is what the redis backend is
+ * for.
+ *
+ * **Namespaces share a file by a composite key**, not a key prefix: the table
+ * is keyed `(ns, key)`, so two namespaces pointing at one `connectors.json`
+ * entry never collide and `clear()` is a single `DELETE ... WHERE ns = ?`.
+ * (The redis backend prefixes instead, because redis has no composite key.)
+ *
+ * **Atomicity comes from IMMEDIATE transactions, not from the driver being
+ * synchronous.** Being synchronous makes each verb indivisible *within this
+ * process*, which is exactly the guarantee that does NOT hold once a second
+ * process opens the same file — and multi-process sharing is the reason to
+ * choose this backend at all. So every read-modify-write verb (`del`,
+ * `setnx`, `consume`, `incrby`, `compareDel`) runs inside
+ * `BEGIN IMMEDIATE` / `COMMIT`, which takes SQLite's write lock up front and
+ * makes the pair atomic against other processes too. Single-statement verbs
+ * need no transaction.
+ *
+ * **Expiry is lazy on read plus a periodic sweep**, mirroring the in-memory
+ * backend: every read filters on `exp`, so an unswept expired row is never
+ * observable; the sweep only bounds file growth. `clear()` deliberately counts
+ * expired-but-unswept rows, because the in-memory backend's `clear()` reports
+ * `map.size` on the same basis.
+ *
+ * `file` is the PATH key by the sqlite DB-connector convention — the model
+ * layer scans every `connectors.json` entry at boot and treats `database` as a
+ * NAME, so a path in `database` fails the boot before this store is built.
+ *
+ * @example
+ *   // connectors.json:  { "kvDb": { "connector": "sqlite", "file": "/data/kv.db" } }
+ *   // settings.json:    { "kv": { "namespaces": { "tokens": { "store": "kvDb" } } } }
+ *   // (wired automatically at boot by gna.js via lib/kv-store)
+ */
+
+/**
+ * Default expired-row sweep cadence, ms.
+ * @constant
+ * @inner
+ * @type {number}
+ */
+var DEFAULT_SWEEP_MS = 30000;
+
+/**
+ * Build the SQLite KV backend for one namespace.
+ *
+ * @class SqliteKvStore
+ * @constructor
+ *
+ * @param {object} connConf                 - Resolved `connectors.json` entry.
+ * @param {string} [connConf.file]          - SQLite file path, or `':memory:'` (volatile —
+ *                                            only useful in tests). Defaults to
+ *                                            `~/.gina/{version}/kv-{bundle}.db`.
+ * @param {number} [connConf.sweepInterval] - Expired-row sweep cadence in ms (default 30000).
+ * @param {string} bundle                   - Bundle name — used for the default file name.
+ * @param {string} namespaceName            - KV namespace this store backs (the `ns` column).
+ * @returns {object}                        - A `KvStoreContract` instance (see `lib/kv`).
+ * @throws {Error}                          - When no SQLite driver is available, or the
+ *                                            database file cannot be opened.
+ */
+module.exports = function SqliteKvStore(connConf, bundle, namespaceName) {
+    connConf = connConf || {};
+
+    var DatabaseSync;
+    try {
+        DatabaseSync = require('./../../../../lib/sqlite-driver').getDatabaseSync();
+    } catch (e) {
+        throw new Error('[SqliteKvStore] ' + e.message);
+    }
+
+    // Resolve the DB path: connectors.json `file` > default per-bundle file.
+    // The default branch is the only place the injected `_` / `getPath`
+    // globals are read, so a test passing an explicit `file` stays standalone.
+    var dbPath = connConf.file
+        || _(getPath('gina').home + '/kv-' + (bundle || 'bundle') + '.db', true);
+
+    var ns = String(namespaceName || 'default');
+    var db = new DatabaseSync(dbPath);
+
+    // WAL + synchronous=NORMAL — the same trade-off as the sibling SQLite
+    // stores: concurrent readers never block the writer; a crash can lose the
+    // last committed transaction but never corrupts the file.
+    db.exec('PRAGMA journal_mode=WAL');
+    db.exec('PRAGMA synchronous=NORMAL');
+
+    // Schema bootstrap — idempotent. `exp` is epoch MILLISECONDS or NULL for
+    // "no expiry"; the composite primary key is what isolates namespaces
+    // sharing one file.
+    db.exec(
+        'CREATE TABLE IF NOT EXISTS kv ('
+        + '  ns    TEXT NOT NULL,'
+        + '  key   TEXT NOT NULL,'
+        + '  value TEXT NOT NULL,'
+        + '  exp   INTEGER,'
+        + '  PRIMARY KEY (ns, key)'
+        + ')'
+    );
+    db.exec('CREATE INDEX IF NOT EXISTS kv_exp ON kv (exp)');
+
+    var stmtGet     = db.prepare('SELECT value, exp FROM kv WHERE ns = ? AND key = ?');
+    var stmtPut     = db.prepare('INSERT OR REPLACE INTO kv (ns, key, value, exp) VALUES (?, ?, ?, ?)');
+    var stmtDel     = db.prepare('DELETE FROM kv WHERE ns = ? AND key = ?');
+    var stmtExpire  = db.prepare('UPDATE kv SET exp = ? WHERE ns = ? AND key = ?');
+    var stmtClear   = db.prepare('DELETE FROM kv WHERE ns = ?');
+    var stmtSweep   = db.prepare('DELETE FROM kv WHERE ns = ? AND exp IS NOT NULL AND exp <= ?');
+
+    /**
+     * The live row for a key, or `null` when absent or expired.
+     * @inner
+     * @param {string} key - Caller key.
+     * @returns {?{value: string, exp: ?number}}
+     */
+    function live(key) {
+        var row = stmtGet.get(ns, key);
+        if (!row) { return null; }
+        if (row.exp !== null && typeof row.exp !== 'undefined' && row.exp <= Date.now()) { return null; }
+        return row;
+    }
+
+    /**
+     * Run `fn` inside `BEGIN IMMEDIATE` / `COMMIT`, rolling back on a throw.
+     * IMMEDIATE takes the write lock up front, so a read-modify-write pair is
+     * atomic against OTHER PROCESSES sharing the file — the guarantee the
+     * synchronous driver alone does not provide.
+     *
+     * @inner
+     * @param {function} fn - Body; its return value is returned.
+     * @returns {*} Whatever `fn` returns.
+     */
+    function tx(fn) {
+        db.exec('BEGIN IMMEDIATE');
+        var out;
+        try {
+            out = fn();
+        } catch (err) {
+            try { db.exec('ROLLBACK'); } catch (rbErr) { /* the throw below is the real error */ }
+            throw err;
+        }
+        db.exec('COMMIT');
+        return out;
+    }
+
+    /**
+     * Lift a synchronous body into the contract's promise shape.
+     * @inner
+     * @param {function} fn - Body.
+     * @returns {Promise<*>}
+     */
+    function P(fn) {
+        try {
+            return Promise.resolve(fn());
+        } catch (err) {
+            return Promise.reject(err);
+        }
+    }
+
+    var sweepMs = (Number.isSafeInteger(connConf.sweepInterval) && connConf.sweepInterval > 0)
+        ? connConf.sweepInterval
+        : DEFAULT_SWEEP_MS;
+
+    // Bounds file growth only — reads already filter on `exp`, so an unswept
+    // row is never observable. Never keeps the process alive.
+    var timer = setInterval(function sweepExpired() {
+        try { stmtSweep.run(ns, Date.now()); } catch (sweepErr) { /* next tick retries */ }
+    }, sweepMs);
+    if (timer.unref) { timer.unref(); }
+
+    return {
+        get: function (key) {
+            return P(function () {
+                var row = live(key);
+                return row ? row.value : null;
+            });
+        },
+
+        set: function (key, s, ttlMs) {
+            return P(function () {
+                stmtPut.run(ns, key, s, ttlMs ? Date.now() + ttlMs : null);
+                return undefined;
+            });
+        },
+
+        del: function (key) {
+            return P(function () {
+                return tx(function () {
+                    var existed = !!live(key);
+                    // Unconditional: an expired row is swept opportunistically
+                    // here too, while `existed` keeps the contract's
+                    // live-only semantics.
+                    stmtDel.run(ns, key);
+                    return existed;
+                });
+            });
+        },
+
+        has: function (key) {
+            return P(function () { return !!live(key); });
+        },
+
+        pttl: function (key) {
+            return P(function () {
+                var row = live(key);
+                if (!row) { return null; }
+                if (row.exp === null || typeof row.exp === 'undefined') { return -1; }
+                return Math.max(0, row.exp - Date.now());
+            });
+        },
+
+        pexpire: function (key, ttlMs) {
+            return P(function () {
+                return tx(function () {
+                    if (!live(key)) { return false; }
+                    stmtExpire.run(Date.now() + ttlMs, ns, key);
+                    return true;
+                });
+            });
+        },
+
+        setnx: function (key, s, ttlMs) {
+            return P(function () {
+                return tx(function () {
+                    // An EXPIRED row must lose, not win: plain INSERT ... ON
+                    // CONFLICT DO NOTHING would see the dead row as a conflict
+                    // and refuse a write that should succeed.
+                    if (live(key)) { return false; }
+                    stmtPut.run(ns, key, s, ttlMs ? Date.now() + ttlMs : null);
+                    return true;
+                });
+            });
+        },
+
+        consume: function (key) {
+            return P(function () {
+                return tx(function () {
+                    var row = live(key);
+                    stmtDel.run(ns, key);
+                    return row ? row.value : null;
+                });
+            });
+        },
+
+        incrby: function (key, by, ttlMs) {
+            return P(function () {
+                return tx(function () {
+                    var row = live(key);
+                    var cur = 0;
+                    if (row) {
+                        cur = Number(row.value);
+                        if (!Number.isSafeInteger(cur)) {
+                            throw new Error('[kv] value at key `' + key + '` is not an integer — incr/decr need an integer value');
+                        }
+                    }
+                    var next = cur + by;
+                    if (!Number.isSafeInteger(next)) {
+                        throw new Error('[kv] increment leaves the safe-integer range at key `' + key + '`');
+                    }
+                    // TTL applies on CREATE only — an existing counter keeps
+                    // whatever expiry it already had.
+                    var exp = row ? ((typeof row.exp === 'undefined') ? null : row.exp)
+                                  : (ttlMs ? Date.now() + ttlMs : null);
+                    stmtPut.run(ns, key, String(next), exp);
+                    return next;
+                });
+            });
+        },
+
+        compareDel: function (key, s) {
+            return P(function () {
+                return tx(function () {
+                    var row = live(key);
+                    if (row && row.value === s) {
+                        stmtDel.run(ns, key);
+                        return true;
+                    }
+                    return false;
+                });
+            });
+        },
+
+        clear: function () {
+            return P(function () {
+                // Counts expired-but-unswept rows, matching the in-memory
+                // backend's `map.size` basis.
+                var res = stmtClear.run(ns);
+                return res.changes;
+            });
+        },
+
+        close: function () {
+            clearInterval(timer);
+            try { db.close(); } catch (closeErr) { /* already closed */ }
+        }
+    };
+};

package/framework/{v0.6.12 → v0.6.13}/core/controller/controller.js

@@ -4514,6 +4514,50 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
             if ( !/http2/.test(httpLib) && /https/.test(options.scheme) ) {
                 httpLib += 's';
             }
+
+            // #MS5 — per-authority circuit breaker (opt-in: settings.json
+            // `server.query.circuitBreaker`, boot-resolved onto the engine
+            // instance by server.js `start()`). Gating happens HERE, above the
+            // protocol dispatch, so an open circuit rejects before any
+            // connection, retry or pre-flight machinery runs: the #B34/#B52/#B53
+            // invariants inside the handlers are untouched, and retries can
+            // never hammer an open circuit.
+            var _cbConf = self.serverInstance && self.serverInstance._queryCircuitBreaker;
+            if ( _cbConf && _cbConf.enabled ) {
+                var _cbAuthority = options.hostname + ':' + options.port;
+                var _cbEntry     = _getCircuitEntry(_cbAuthority);
+                var _cbGate      = _circuitAdmit(_cbEntry, _cbConf, isCritical);
+                if ( !_cbGate.admitted ) {
+                    var _cbErr = new GinaCircuitOpenError(_cbAuthority, _cbGate.retryAfterMs);
+                    if (!isCritical) {
+                        // mirror the H3 `_swallowIfNonCritical` contract: log-only, no callback
+                        console.warn('[QUERY][circuit-open][non-critical] swallowed '+ (options.method || '') +' '+ (options.path || '') +' to '+ _cbAuthority);
+                        return;
+                    }
+                    if (callback) {
+                        return callback(_cbErr);
+                    }
+                    return self.emit('query#complete', _cbErr);
+                }
+                if ( typeof(callback) == 'function' ) {
+                    var _cbOriginalCallback = callback;
+                    var _cbSettled = false;
+                    callback = function onCircuitObservedOutcome(err) {
+                        if (!_cbSettled) { // record once, whatever the terminal
+                            _cbSettled = true;
+                            _circuitRecord(_cbEntry, _cbConf, _cbGate.probe, err);
+                        }
+                        return _cbOriginalCallback.apply(this, arguments);
+                    };
+                } else if (_cbGate.probe) {
+                    // No callback → the outcome is unobservable (the shared
+                    // `query#complete` emitter would misattribute concurrent
+                    // queries) → release the probe slot immediately rather than
+                    // wedge the half-open state.
+                    _cbEntry.probeInFlight = false;
+                }
+            }
+
             browser = require(''+ httpLib);
             // #FI — capture query call start time for Flow timeline
             if (_isDev && local._timeline) {
@@ -4689,6 +4733,164 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
     //     });
     // };
 
+    /**
+     * Error surfaced by `query()` when the target authority's circuit is OPEN (#MS5).
+     *
+     * Minted ABOVE the HTTP/1.x / HTTP/2 dispatch — before any connection attempt,
+     * retry or pre-flight PING runs — so it applies identically to both client
+     * paths. The field shape mirrors `GinaHttp2Error` (`code`, `retryable`,
+     * `status`, `retryCount`) so machine consumers can switch on `code` without
+     * caring which transport would have been used; the name is protocol-neutral
+     * on purpose.
+     *
+     * @constructor
+     * @param {string} authority    - `hostname:port` whose circuit is open
+     * @param {number} retryAfterMs - Milliseconds until the next half-open probe may be admitted (0 = a probe slot is free now)
+     */
+    function GinaCircuitOpenError(authority, retryAfterMs) {
+        Error.call(this);
+        this.name    = 'GinaCircuitOpenError';
+        this.message = 'Controller::query() circuit is OPEN for [ '+ authority +' ] — failing fast'+ ( retryAfterMs > 0 ? ' (next probe allowed in '+ retryAfterMs +'ms)' : '' );
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, GinaCircuitOpenError);
+        } else {
+            this.stack = (new Error(this.message)).stack;
+        }
+        this.code         = 'CIRCUIT_OPEN';
+        this.retryable    = false;
+        this.status       = 503;
+        this.retryCount   = 0;
+        this.authority    = authority;
+        this.retryAfterMs = retryAfterMs;
+    }
+    GinaCircuitOpenError.prototype             = Object.create(Error.prototype);
+    GinaCircuitOpenError.prototype.constructor = GinaCircuitOpenError;
+
+    /**
+     * Transport-failure classifier for the #MS5 circuit breaker.
+     *
+     * Counts ONLY errors that indicate the upstream (or the path to it) is
+     * unhealthy: every `GinaHttp2Error` (all of its codes are transport-class —
+     * post-#B34 an application response, whatever its status, flows through the
+     * SUCCESS terminus as data, never as `err`) plus the HTTP/1.x socket-level
+     * codes, checked on `err.code` and `err.cause.code` (the HTTP/1.x error path
+     * annotates both shapes). Anything else — a caller bug surfacing through the
+     * sync dispatch `catch`, a malformed option, an app-level error — is NEUTRAL:
+     * it neither trips nor resets the circuit, because it says nothing about
+     * upstream health.
+     *
+     * @inner
+     * @param   {*} err - Whatever the client path surfaced to the query callback
+     * @returns {boolean} `true` when the error counts toward opening the circuit
+     */
+    var _CB_TRANSPORT_CODES = /^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|EPIPE|ECONNABORTED|EHOSTUNREACH|ENETUNREACH)$/;
+    var _isCircuitTransportFailure = function(err) {
+        if (!err) return false;
+        if (err.name === 'GinaHttp2Error') return true;
+        var code = err.code || (err.cause && err.cause.code);
+        return _CB_TRANSPORT_CODES.test(String(code || ''));
+    };
+
+    /**
+     * Lazily fetch (or mint) the per-authority breaker entry (#MS5).
+     *
+     * State lives on the SERVER instance — the same home as `_http2Sessions` —
+     * because dev mode re-requires this module per request (see the #B52 note):
+     * module- or controller-level state would reset on every hot-reload, while
+     * instance state survives reloads and dies on restart, which is exactly the
+     * lifetime circuit state wants. Entries are keyed per distinct
+     * `hostname:port`; query targets come from bundle config and app code (a
+     * trusted surface), so cardinality is not attacker-controlled.
+     *
+     * @inner
+     * @param   {string} authority - `hostname:port`
+     * @returns {object} `{ state, consecutiveFailures, openedAt, probeInFlight }`
+     */
+    var _getCircuitEntry = function(authority) {
+        if (!self.serverInstance._queryCircuitBreakers) {
+            self.serverInstance._queryCircuitBreakers = {};
+        }
+        var registry = self.serverInstance._queryCircuitBreakers;
+        if (!registry[authority]) {
+            registry[authority] = { state: 'closed', consecutiveFailures: 0, openedAt: 0, probeInFlight: false };
+        }
+        return registry[authority];
+    };
+
+    /**
+     * Admission decision for one outgoing query under the #MS5 breaker.
+     *
+     * Runs the lazy OPEN → HALF-OPEN transition first (the breaker owns NO
+     * timers: elapsed time is computed on access), then answers:
+     *
+     *  - CLOSED            → admit
+     *  - OPEN, cooling     → reject, reporting the remaining cooldown
+     *  - OPEN, cooled down → become HALF-OPEN and fall through
+     *  - HALF-OPEN         → admit exactly ONE probe, and only for a CRITICAL
+     *    request: a non-critical failure is swallowed by `_swallowIfNonCritical`
+     *    (its callback never fires), so a non-critical probe could never report
+     *    back and would wedge `probeInFlight` forever. Everything else is
+     *    rejected until the probe settles.
+     *
+     * @inner
+     * @param   {object}  entry      - Breaker entry from `_getCircuitEntry()`
+     * @param   {object}  conf       - Resolved policy (`failureThreshold`, `cooldownMs`)
+     * @param   {boolean} isCritical - The query's H3 criticality flag
+     * @returns {object}  `{ admitted, probe, retryAfterMs }`
+     */
+    var _circuitAdmit = function(entry, conf, isCritical) {
+        if (entry.state === 'open') {
+            var elapsed = Date.now() - entry.openedAt;
+            if (elapsed < conf.cooldownMs) {
+                return { admitted: false, probe: false, retryAfterMs: conf.cooldownMs - elapsed };
+            }
+            entry.state = 'half-open';
+            entry.probeInFlight = false;
+        }
+        if (entry.state === 'half-open') {
+            if (entry.probeInFlight || !isCritical) {
+                return { admitted: false, probe: false, retryAfterMs: 0 };
+            }
+            entry.probeInFlight = true;
+            return { admitted: true, probe: true, retryAfterMs: 0 };
+        }
+        return { admitted: true, probe: false, retryAfterMs: 0 };
+    };
+
+    /**
+     * Record one settled query outcome against its authority's circuit (#MS5).
+     *
+     *  - success             → CLOSED, counter reset (a settling probe closes the circuit)
+     *  - transport failure   → counter + 1; reaching `failureThreshold` — or failing
+     *                          the half-open probe — re-opens with a fresh cooldown
+     *  - neutral (non-transport) error → releases a probe slot but otherwise
+     *    changes nothing (see `_isCircuitTransportFailure`)
+     *
+     * @inner
+     * @param {object}  entry   - Breaker entry
+     * @param {object}  conf    - Resolved policy
+     * @param {boolean} isProbe - Whether this outcome settles the half-open probe
+     * @param {*}       err     - The callback's error argument (`false` on success — see §9's sentinel)
+     */
+    var _circuitRecord = function(entry, conf, isProbe, err) {
+        if (isProbe) {
+            entry.probeInFlight = false;
+        }
+        if (!err) {
+            entry.state = 'closed';
+            entry.consecutiveFailures = 0;
+            return;
+        }
+        if ( !_isCircuitTransportFailure(err) ) {
+            return; // neutral — caller bug or app-level error
+        }
+        entry.consecutiveFailures++;
+        if (isProbe || entry.consecutiveFailures >= conf.failureThreshold) {
+            entry.state = 'open';
+            entry.openedAt = Date.now();
+        }
+    };
+
     /**
      * #B53 — Idempotency guard for inter-bundle client retries.
      *

package/framework/{v0.6.12 → v0.6.13}/core/gna.js

@@ -1748,6 +1748,62 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
                                     console.warn('[storage] config validation skipped: ' + (stoErr.message || stoErr));
                                 }
 
+                                // #KV1 — general-purpose KV primitive. Validate the starting
+                                // bundle's `kv` block, build any connector-backed namespace stores,
+                                // then install the namespaces before the first request. FATAL on an
+                                // unbuildable config (the #STO1 shape above): a namespace whose
+                                // declared store cannot build would leave gina.kv() handing out a
+                                // backend the operator did not ask for. Dormant — zero cost — when
+                                // the block is absent.
+                                try {
+                                    var _kvAll      = config.getInstance();
+                                    var _kvSettings = null;
+                                    try {
+                                        _kvSettings = _kvAll[gna.core.startingApp][env].content.settings.kv;
+                                    } catch (kvConfErr) { _kvSettings = null; }
+                                    if ( _kvSettings ) {
+                                        var _kvCheck = lib.kv.validateConfig(_kvSettings);
+                                        for (var _kvW = 0; _kvW < _kvCheck.warnings.length; _kvW++) {
+                                            console.warn('[kv] ' + _kvCheck.warnings[_kvW]);
+                                        }
+                                        if (_kvCheck.fatal) {
+                                            var _kvFatalMsg = '[kv] invalid kv configuration — aborting boot: ' + _kvCheck.fatal;
+                                            console.emerg(_kvFatalMsg);
+                                            // boot-exit-flush: process.exit() truncates async stdio on a pipe.
+                                            try { fs.writeSync(2, _kvFatalMsg + '\n'); } catch (_e) {}
+                                            process.exit(1);
+                                        }
+                                        if (_kvCheck.namespaceCount > 0) {
+                                            var _kvNamespaces = _kvSettings.namespaces;
+                                            var _kvStores     = {};
+                                            for (var _kvN in _kvNamespaces) {
+                                                if ( typeof(_kvNamespaces[_kvN].store) == 'string' && _kvNamespaces[_kvN].store.length > 0 ) {
+                                                    try {
+                                                        // the namespace name is passed so an implementation
+                                                        // prefixes its keys — two namespaces may share one
+                                                        // connectors.json entry without colliding
+                                                        _kvStores[_kvN] = lib.KvStore(_kvNamespaces[_kvN].store, _kvN);
+                                                    } catch (kvStoreErr) {
+                                                        var _kvStoreMsg = '[kv] namespace `' + _kvN + '` names store `' + _kvNamespaces[_kvN].store + '`, which could not be built — aborting boot: ' + (kvStoreErr.message || kvStoreErr);
+                                                        console.emerg(_kvStoreMsg + '\n' + (kvStoreErr.stack || ''));
+                                                        try { fs.writeSync(2, _kvStoreMsg + '\n'); } catch (_e) {}
+                                                        process.exit(1);
+                                                    }
+                                                }
+                                            }
+                                            if ( lib.kv.start(_kvSettings, { stores: _kvStores, warn: function(kvWarnMsg) { console.warn('[kv] ' + kvWarnMsg); } }) ) {
+                                                // console.info, NOT debug — an operator needs to see
+                                                // which namespaces went live (the #STO1 precedent).
+                                                console.info('[kv] ' + _kvCheck.namespaceCount + ' namespace(s) ready' + ( _kvSettings.default ? ' (default: ' + _kvSettings.default + ')' : '' ));
+                                            } else {
+                                                console.warn('[kv] namespaces were already installed — this boot wiring was ignored');
+                                            }
+                                        }
+                                    }
+                                } catch (kvErr) {
+                                    console.warn('[kv] setup skipped: ' + (kvErr.message || kvErr));
+                                }
+
                                 // #CE1 — `server.transientErrors` boot-time shape check
                                 // (warn-only, NEVER fatal: the opt-in governs how a
                                 // transient datastore error RENDERS — a bad value must
@@ -2561,6 +2617,35 @@ gna.storage = function(name) {
     return lib.storage.get(name);
 };
 
+/**
+ * #KV1 — get a configured KV namespace.
+ *
+ * The general-purpose key-value surface (counters, one-shot tokens,
+ * fetch-or-compute caching, lease primitives) — strict-declared: a namespace
+ * must exist under `settings.json > kv.namespaces` or this throws at the
+ * call site, which is what surfaces a typo (the `gna.storage` stance).
+ *
+ * Assigned UNCONDITIONALLY, so a bundle with no `kv` block gets a named
+ * error naming the fix instead of `gna.kv is not a function` — and so the
+ * declaration is a plain function rather than one the caller must narrow.
+ *
+ * @param {string} [name] - Namespace name; omitted returns the `kv.default` namespace.
+ * @returns {object} The namespace handle (`get` / `set` / `del` / `has` / `ttl` /
+ *                   `expire` / `setnx` / `consume` / `incr` / `decr` /
+ *                   `delIfEquals` / `clear` / `getOrSet` — all promise-returning).
+ * @throws {Error} When kv is not configured, when no default is declared and `name`
+ *                 was omitted, or when `name` is not a declared namespace.
+ * @example
+ *   gna.kv('tokens').consume('t:' + hash).then(function (record) {
+ *       if (record === null) { return self.throwError(410, 'link already used'); }
+ *   });
+ * @example
+ *   gina.kv();  // the `kv.default` namespace
+ */
+gna.kv = function(name) {
+    return lib.kv.get(name);
+};
+
 /**
  * #B366 — push a payload to ONE named session from OUTSIDE a request.
  *