gina 0.6.13 → 0.6.14

package/framework/v0.6.14/lib/secrets/src/sources.js

@@ -0,0 +1,325 @@
+'use strict';
+/**
+ * @module lib/secrets/sources
+ * @description The config-source walk: which config files exist for a
+ * project's bundles, and which `${secret:KEY}` placeholders they require.
+ * Shared so that every consumer walks the SAME source set.
+ *
+ * Consumers today are the `gina secrets:scan` and `gina secrets:check` CLI
+ * handlers; the walk is also the enumeration a boot-time consumer (e.g. a
+ * prefetching secrets backend) would need. Before this module existed, the
+ * two CLI handlers each carried a hand-kept copy of the walk — and two
+ * hand-kept copies of "which sources does a bundle read" drifted once
+ * already (#B263: the gate and the runtime consulted different source
+ * sets, producing a false verdict on the exact command that exists to
+ * prevent surprises). One implementation makes that class of disagreement
+ * structurally impossible rather than merely unlikely.
+ *
+ * Config sources walked, matching `core/config.js::loadBundleConfig`:
+ *   - `<bundleSrc>/config/` per bundle, where `bundleSrc` comes from
+ *     `manifest.bundles[<name>].src` (falling back to the bundle name).
+ *   - the project-level `shared/config/`, which the loader merges into
+ *     every bundle — so its keys are attributed to each bundle.
+ * Every `.json` in those dirs is read (the loader globs the dir rather
+ * than using a fixed whitelist); dotfiles and `* copy` files are skipped.
+ *
+ * With a `scope`, the sibling `config_<scope>/` dir of each config dir
+ * (e.g. `shared/config_production/`) is read-only overlaid on top of the
+ * base via deep-merge (scope wins) — mirroring how a deploy applies its
+ * per-scope config — so the report shows the *effective* keys that scope's
+ * deploy will require. This is pure introspection: it does NOT change the
+ * runtime config loader, which stays scope-agnostic (the deploy owns
+ * per-scope selection).
+ *
+ * Caveat: this reports the *authored* placeholders on disk, not the merged
+ * runtime config — correct today because placeholders are always authored
+ * literals.
+ *
+ * Shape: a FACTORY taking the key-enumeration primitive. `main.js` (which
+ * owns `getRequiredKeys`) instantiates it and spreads the result into the
+ * `lib.secrets` surface — the factory form exists so this file never
+ * requires `./main` back (no load cycle) and never touches the `lib`
+ * registry (so a bare `require` of `lib/secrets` stays dependency-free).
+ *
+ * Framework global context: the walk resolves `_()` (path normalisation)
+ * and `requireJSON` (comment-tolerant JSON read) at CALL time — they are
+ * the gna.js / helpers-injected globals every runtime and CLI scope
+ * carries. Module LOAD touches neither, so requiring `lib/secrets` in a
+ * bare test process needs no global setup; only *calling* the walk does
+ * (a test installs them by requiring the framework `helpers/` tree).
+ */
+
+var fs = require('fs');
+// Deep merge for the scope overlay. Required relatively (server-side only;
+// this module is not in the browser bundle) — and its node export path also
+// installs `JSON.clone` when absent (#M22), which the overlay clone needs.
+var merge = require('../../merge');
+
+/**
+ * Builds the config-source walk over the supplied key-enumeration
+ * primitive.
+ *
+ * @function module:lib/secrets/sources
+ * @param {function} getRequiredKeys - `lib/secrets`'s own `getRequiredKeys(config)` — read-only, non-throwing, backend-free
+ * @returns {{getProjectRequiredKeys: function, loadManifest: function, readJsonSafe: function, resolveBundleSrc: function}}
+ */
+module.exports = function sourcesFactory(getRequiredKeys) {
+
+    /**
+     * Config files are JSON. The loader globs every `.json` in a config
+     * dir; this matches that, then drops dotfiles and `* copy` siblings.
+     *
+     * @inner
+     * @constant
+     * @type {RegExp}
+     */
+    var JSON_EXT = /\.json$/;
+
+    /**
+     * Reads a JSON file with comment tolerance via `requireJSON`. Returns
+     * `null` when the file is absent or unreadable so callers can choose
+     * how to surface the failure. A file that exists but does not PARSE
+     * follows `requireJSON`'s own loud-failure contract instead: in a full
+     * framework context (where `console.emerg` exists) it emerg-logs and
+     * exits the process, so the catch below never sees it — stated here
+     * because the previous in-handler copies of this helper documented
+     * "null on any parse error", which that contract makes unreachable.
+     *
+     * Note `requireJSON` caches by path (require-cache semantics), so the
+     * returned object is SHARED — callers that mutate or merge it must
+     * clone first (the scope overlay below does).
+     *
+     * @memberof module:lib/secrets/sources
+     * @function readJsonSafe
+     * @param {string} filePath - Absolute path
+     * @returns {object|null}
+     * @example
+     * var pkg = readJsonSafe('/tmp/some-project/manifest.json');
+     * if (pkg === null) { console.warn('unreadable or absent'); }
+     */
+    var readJsonSafe = function (filePath) {
+        try {
+            if ( !fs.existsSync(filePath) ) return null;
+            return requireJSON(filePath);
+        } catch (e) {
+            return null;
+        }
+    };
+
+    /**
+     * Loads `<projectPath>/manifest.json`. Returns `null` on failure.
+     *
+     * @memberof module:lib/secrets/sources
+     * @function loadManifest
+     * @param {string} projectPath - Absolute project root
+     * @returns {object|null}
+     * @example
+     * var manifest = loadManifest('/tmp/some-project');
+     * var names = manifest ? Object.keys(manifest.bundles) : [];
+     */
+    var loadManifest = function (projectPath) {
+        return readJsonSafe(_(projectPath + '/manifest.json', true));
+    };
+
+    /**
+     * Resolves a bundle's source-dir (relative to the project root) from
+     * the manifest, mirroring `bundle:openapi`. Falls back to the bundle
+     * name when `src` is absent.
+     *
+     * @memberof module:lib/secrets/sources
+     * @function resolveBundleSrc
+     * @param {object|null} manifest
+     * @param {string} bundleName
+     * @returns {string}
+     * @example
+     * resolveBundleSrc({ bundles: { demo: { src: 'src/demo' } } }, 'demo'); // 'src/demo'
+     * resolveBundleSrc(null, 'demo');                                      // 'demo'
+     */
+    var resolveBundleSrc = function (manifest, bundleName) {
+        if ( manifest && manifest.bundles && manifest.bundles[bundleName] && manifest.bundles[bundleName].src ) {
+            return manifest.bundles[bundleName].src;
+        }
+        return bundleName;
+    };
+
+    /**
+     * Lists the `.json` files in `dir`, skipping dotfiles and `* copy`
+     * siblings — the same filtering `loadBundleConfig` applies. Returns a
+     * sorted list of bare filenames. Empty when the dir is absent.
+     *
+     * @inner
+     * @private
+     * @param {string} dir - Absolute config directory
+     * @returns {string[]}
+     */
+    var listJsonFiles = function (dir) {
+        if ( !fs.existsSync(dir) ) return [];
+        var entries;
+        try { entries = fs.readdirSync(dir); } catch (e) { return []; }
+        var out = [];
+        for (var i = 0; i < entries.length; i++) {
+            var name = entries[i];
+            if ( /^\./.test(name) ) continue;
+            if ( /\s+copy/i.test(name) ) continue;
+            if ( !JSON_EXT.test(name) ) continue;
+            out.push(name);
+        }
+        out.sort();
+        return out;
+    };
+
+    /**
+     * Reads every `.json` under `absDir`, enumerates its required secret
+     * keys via the injected `getRequiredKeys`, and records each key
+     * against its originating file (labelled `relBase + '/' + filename`).
+     * Mutates `byKey` in place.
+     *
+     * When `scopeName` is set, the sibling `<absDir>_<scope>/` directory
+     * (e.g. `shared/config_production/`) is read-only overlaid on top of
+     * the base dir per config file, mirroring how a deploy applies its
+     * per-scope config: the scope file deep-merges over the base (scope
+     * wins on collisions, base back-fills) so the keys reported are the
+     * *effective* ones that scope's deploy will require. The scope file is
+     * JSON.clone'd before merge so cached content is not mutated. This is
+     * read-only introspection — it never touches the runtime config
+     * loader.
+     *
+     * @inner
+     * @private
+     * @param {string} absDir  - Absolute base config directory to read
+     * @param {string} relBase - Display prefix for file labels (e.g. `src/demo/config`)
+     * @param {Object<string, string[]>} byKey - Mutable KEY -> [files] map
+     * @param {string|null} scopeName - Scope overlay name, or `null`
+     */
+    var collectFromConfigDir = function (absDir, relBase, byKey, scopeName) {
+        var scopeAbsDir  = scopeName ? (absDir + '_' + scopeName) : null;
+        var scopeRelBase = scopeName ? (relBase + '_' + scopeName) : null;
+
+        var baseNames  = listJsonFiles(absDir);
+        var scopeNames = scopeAbsDir ? listJsonFiles(scopeAbsDir) : [];
+
+        // union of config file names across base + scope-overlay dirs
+        var names = baseNames.slice();
+        for (var s = 0; s < scopeNames.length; s++) {
+            if (names.indexOf(scopeNames[s]) < 0) names.push(scopeNames[s]);
+        }
+
+        for (var f = 0; f < names.length; f++) {
+            var name         = names[f];
+            var baseContent  = (baseNames.indexOf(name) > -1) ? readJsonSafe(_(absDir + '/' + name, true)) : null;
+            var scopeContent = (scopeAbsDir && scopeNames.indexOf(name) > -1) ? readJsonSafe(_(scopeAbsDir + '/' + name, true)) : null;
+
+            // effective config for this scope: scope deep-merges over base (scope wins).
+            // override=false is explicit (not merge's default) so scope precedence stays
+            // correct even if lib/merge's default override ever changes.
+            var effective = scopeContent ? merge(JSON.clone(scopeContent), baseContent || {}, false) : baseContent;
+            if (!effective) continue;
+
+            var keys      = getRequiredKeys(effective);
+            var scopeKeys = scopeContent ? getRequiredKeys(scopeContent) : [];
+            for (var k = 0; k < keys.length; k++) {
+                // attribute the key to the layer that actually provides it in the effective config
+                var label = (scopeKeys.indexOf(keys[k]) > -1) ? (scopeRelBase + '/' + name) : (relBase + '/' + name);
+                if (!byKey[keys[k]]) byKey[keys[k]] = [];
+                if (byKey[keys[k]].indexOf(label) < 0) byKey[keys[k]].push(label);
+            }
+        }
+    };
+
+    /**
+     * Computes the shared-config KEY -> [files] map once per project. The
+     * loader merges `shared/config/` into every bundle, so these keys are
+     * attributed to each bundle.
+     *
+     * @inner
+     * @private
+     * @param {string} projectPath
+     * @param {string|null} scopeName
+     * @returns {Object<string, string[]>}
+     */
+    var computeSharedByKey = function (projectPath, scopeName) {
+        var byKey = Object.create(null);
+        collectFromConfigDir(_(projectPath + '/shared/config', true), 'shared/config', byKey, scopeName);
+        return byKey;
+    };
+
+    /**
+     * Enumerates the `${secret:KEY}` placeholders a project's bundles
+     * require, walking the same config sources `loadBundleConfig` reads
+     * (shared/config folded into every bundle; per-bundle `config/`; the
+     * optional `config_<scope>/` overlay). Read-only and non-throwing —
+     * the introspection family contract `getRequiredKeys` set.
+     *
+     * Provenance is always on: each key maps to the project-relative
+     * config file(s) that require it, insertion-ordered and de-duplicated
+     * (shared labels first, then the bundle's own).
+     *
+     * Semantics, precisely:
+     *   - a non-string or empty `projectPath` returns `null`.
+     *   - with `options.bundle`, the filter is honoured VERBATIM: that one
+     *     bundle is walked even when the manifest is missing or does not
+     *     list it (its src falls back to the bundle name; absent dirs
+     *     simply contribute nothing) — matching the CLI, which validates
+     *     membership itself before calling and, historically, walked a
+     *     manifest-less project on an explicit bundle name.
+     *   - without `options.bundle`, the manifest IS the bundle list: a
+     *     missing/unreadable manifest, or one without a `bundles` object,
+     *     returns `null` (callers decide how to surface it).
+     *
+     * @memberof module:lib/secrets/sources
+     * @function getProjectRequiredKeys
+     * @param {string} projectPath - Absolute project root
+     * @param {object} [options]
+     * @param {string|null} [options.scope=null]  - Scope overlay name (`config_<scope>/` siblings)
+     * @param {string|null} [options.bundle=null] - Restrict the walk to one bundle
+     * @returns {{bundles: Array<{bundle: string, byKey: Object<string, string[]>}>}|null}
+     *          Bundles sorted by name; `byKey` is a null-proto KEY -> [labels] map
+     * @example
+     * // all bundles, production overlay:
+     * var r = getProjectRequiredKeys('/tmp/some-project', { scope: 'production' });
+     * // -> { bundles: [ { bundle: 'demo', byKey: { DB_PASSWORD: ['shared/config/app.json'] } } ] }
+     * @example
+     * // one bundle, no overlay — null projectPath and missing manifests are not thrown:
+     * getProjectRequiredKeys('', {});                                // null
+     * getProjectRequiredKeys('/tmp/some-project', { bundle: 'demo' }); // walks only demo
+     */
+    var getProjectRequiredKeys = function (projectPath, options) {
+        if (typeof projectPath !== 'string' || projectPath === '') {
+            return null;
+        }
+        var opts      = (options && typeof options === 'object') ? options : {};
+        var scopeName = opts.scope || null;
+        var manifest  = loadManifest(projectPath);
+
+        var names;
+        if (opts.bundle) {
+            names = [opts.bundle];
+        } else {
+            if (!manifest || !manifest.bundles || typeof manifest.bundles !== 'object') {
+                return null;
+            }
+            names = Object.keys(manifest.bundles).sort();
+        }
+
+        var sharedByKey = computeSharedByKey(projectPath, scopeName);
+        var bundles     = [];
+        for (var i = 0; i < names.length; i++) {
+            var byKey = Object.create(null);
+            for (var sk in sharedByKey) {
+                byKey[sk] = sharedByKey[sk].slice();
+            }
+            var bundleSrc = resolveBundleSrc(manifest, names[i]);
+            var rel       = bundleSrc + '/config';
+            collectFromConfigDir(_(projectPath + '/' + rel, true), rel, byKey, scopeName);
+            bundles.push({ bundle: names[i], byKey: byKey });
+        }
+        return { bundles: bundles };
+    };
+
+    return {
+        getProjectRequiredKeys : getProjectRequiredKeys,
+        loadManifest           : loadManifest,
+        readJsonSafe           : readJsonSafe,
+        resolveBundleSrc       : resolveBundleSrc
+    };
+};

package/framework/{v0.6.13 → v0.6.14}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.6.13",
+  "version": "0.6.14",
   "dependencies": {
     "@rhinostone/busboy": "^1.6.1",
     "@rhinostone/swig": "^2.7.2",

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.6.13/core/gna');
+var _gna = require('./framework/v0.6.14/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.6.13/core/controller');
-var EntitySuper     = require('./framework/v0.6.13/core/model/entity');
+var SuperController = require('./framework/v0.6.14/core/controller');
+var EntitySuper     = require('./framework/v0.6.14/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.6.13/lib/uuid');
+var uuid = require('./framework/v0.6.14/lib/uuid');
 
 module.exports = {
 

package/llms.txt

@@ -135,7 +135,7 @@ module.exports = ApiContentController;
 - **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())`.
+- `async` controller actions are fully supported — the router attaches `.catch()` to any thenable returned by an action and routes rejections to `throwError(response, 500, ...)`; `self.query()` owns an `async` callback's rejection the same way at every delivery seam (callback form and `{onComplete}` facade, both transports — a rejected callback promise answers 500 instead of hanging; #B399). Use `await entity.method()` directly. For PathObject ops and Shell use `await onCompleteCall(_(path).mkdir())`.
 - `self.setEarlyHints(links)` — send a 103 Early Hints informational response. Call before the terminal method. `links` is a string or array of `Link` header values. HTTP/2: `stream.additionalHeaders({ ':status': 103 })`; HTTP/1.1: `res.writeEarlyHints()` (Node.js 18.11+). Silent no-op when unsupported. Returns `self`. **Also automatic**: `render()` auto-sends 103 for the bundle's CSS/JS preloads (from `h2Links`) before Swig compilation in HTTP/2 production mode — zero config required.
 - `self.renderStream(asyncIterable, contentType)` — stream an `AsyncIterable` as a chunked HTTP response without buffering. `contentType` defaults to `text/event-stream` (SSE). Each yielded string/Buffer becomes `data: {chunk}\n\n` for SSE; raw for other content types. HTTP/2: `stream.respond()` + `stream.write()` + `stream.end()`. HTTP/1.1: automatic chunked transfer-encoding. `x-accel-buffering: no` set automatically for SSE. Fire-and-forget — do not `await`. Required for LLM token streaming via `ai.client` with `stream: true`. **Honours a caller-set `response.statusCode` on BOTH engines (#B351, 0.6.8)** — the h2 frame carries `response.statusCode || 200` and the h1 arm assigns `response.statusCode || 200`, so a controller may pre-set 206/416/404 before calling. Until 0.6.8 both arms were 200-only (the h2 frame hardcoded the pseudo-header literal, the h1 arm clobbered a pre-set code), which made `206 Partial Content` unreachable through renderStream — the reason it blocked Range serving. Same class as #B172: **a hand-built h2 frame must never carry a literal `':status'`**, because `setHeader(':status', …)` throws and no later header merge can repair a pseudo-header; the pending-header merge deliberately does not overwrite `:status`.
 
@@ -812,7 +812,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 80. **CSRF — three-phase protection (`#CSRF1` Session plugin / `#CSRF2` signed double-submit token / `#CSRF3` Origin pre-filter)** — Session plugin hardens `express-session` cookie defaults from `settings.json > session.cookie.{sameSite, httpOnly, secure}` (opt-in, one-line bundle bootstrap swap, never transparent because bundles legitimately set `httpOnly: false`); signed token middleware uses `crypto.timingSafeEqual` HMAC-SHA256 bound to `req.session.id` with per-route `routing.json > "csrfExempt": true` opt-out (see `routing-and-http2.md § "Per-route flags"` for `req.routing.csrfExempt` two-step propagation: `lib/routing` extracts → `core/server.js` hoists, top-level on `req.routing` not under `param.*`); Origin pre-filter folded INSIDE `gina.plugins.Csrf()` BEFORE token verify on mutating methods, allowlist via `settings.json > csrf.allowedOrigins` (empty defaults to `[bundleHostname]` auto-derived). Negative-invariant lock: matching token + mismatching Origin still 403s — token layer ≠ Origin layer. Implementation traps from the trilogy: plan-vs-shipped attribute drift (downstream commits must `grep -n '<attribute>' <upstream-source-file>` before referencing — source on develop wins, not the plan); CI flake-vs-regression triage (same-message-different-SHA pairs need `git diff --stat A..B` first); source-inspection `indexOf` matches the function DEFINITION before the call site (use unique assignment LHS like `requestOrigin = parseRequestOrigin(req)`); `Origin: "null"` is a real browser value (sandboxed iframes / `file://`) and needs an explicit `s === 'null'` guard so the parser falls through to Referer instead of 403'ing for "origin not allowed".
 
-98. **Secrets — `${secret:KEY}` config placeholders + the `secrets:scan`/`secrets:check` introspection CLI (absorbs former #135).** `lib/secrets` substitutes `${secret:KEY}` at config-load (`core/config.js::loadBundleConfig`, post-merge per bundle), resolving each key from the FRAMEWORK environment first (`getEnvVar`) and falling back to `process.env[KEY]`. **That two-tier read is load-bearing, not defensive (0.6.3, #B156):** the CLI MOVES every `GINA_*`/`USER_*`/`VENDOR_*` key OUT of `process.env` into `process.gina` (`filterArgs`, `utils/helper.js`), so a `${secret:GINA_*}` placeholder was previously unresolvable in ANY CLI-loaded config — `mcp.json` (the published example), the connector commands, `audit:verify` — and failed closed with a refusing boot. Non-`GINA_` keys are untouched by the sweep and resolve as before. The same idiom now backs the CSRF `GINA_CSRF_SECRET` tier and the MCP transport's `GINA_BIND_HOST`/`GINA_DIR` reads (#B157). ANCHORED: the regex matches only when the ENTIRE string value is the placeholder — mixed strings (`"prefix-${secret:K}-suffix"`) pass through unchanged; non-string scalars untouched; nested objects/arrays descend. **Fail-closed:** an unset/empty env var throws a GENERIC `Secret resolution failed` — the key name rides only a non-enumerable `_ginaSecretKey`, surfaced at debug level by the config-load catch naming key + `<bundle>/<env>:<scope>` (#B42), so consumer-visible surfaces never carry key names. Secret rotation needs a process restart (the resolver re-runs on `config.refresh()`, but the env is inherited from container init). Pluggable backend interface (`{resolve(key)}` — env-only by default, env-over-file once `secrets.file` is declared). **The two tiers are read INDEPENDENTLY, never joined by `||` (0.6.9, #B270):** `filterArgs` stores swept values as REAL booleans, so a truthy boolean used to satisfy the short-circuit and `process.env` was never consulted — the file tier then beat a SET environment variable, inverting the precedence the file backend exists to enforce. Only a non-empty STRING from the framework tier wins; a boolean, number, `undefined` or `''` falls through. `getResolvedPaths()` gives the dotted paths substituted in a config, but it is **not** a general redaction substrate (0.6.9, #B274): the paths address the config object and the lookup is keyed on its IDENTITY, so a consumer must hold the very object `resolve()` mutated — which rules out the Inspector, whose payload is a structural clone of the controller's VIEW data (`{gina, user}`), a different object in a different coordinate space. A surface holding VALUES rather than the config needs a value-based pass; `core/connectors/param-redact.js` exists for exactly that reason. **`secrets.file` shape guards (0.6.9):** `[]` still disables the tier like `null` but now WARNS rather than doing it silently (#B271 — an operator emptying the array to drop one layer drops the whole tier; boot is not refused, since an empty list genuinely means "no files"); a whitespace-only entry is REFUSED (`minLength: 1` counts a space, so `[" "]` used to build a tier that could never resolve anything); and a path containing an empty segment (`//`) is refused (#B272 — such a path does not name the file it appears to, since POSIX reads `<a>//<b>` as `<a>/<b>`; the DANGEROUS cause is a `${…}` token that resolved to EMPTY, leaving no token for the unresolved-token guard and silently reading the file one directory UP — `${homedir}/${scope}/secrets.env` with an empty scope — while the BENIGN cause is a token with a trailing slash such as an operator's `GINA_HOMEDIR=/opt/gina/`, which nothing in the path chain normalises. The two are indistinguishable once assembled, so boot refuses on both and the error names both causes rather than asserting one it cannot know; the benign case is a one-character fix). The schema gains `minItems: 1` as an editor-facing hint — no runtime validator loads `schema/settings.json`, so `main.js` is the enforcement. **FILE SYNTAX — one parser (`lib/secrets/src/env-file.js::parseEnv`) serves BOTH readers (`secrets:check` + the file backend), so the gate cannot green-light a file the runtime reads differently.** It targets what a POSIX shell `source`s, since the documented entrypoint (`set -a; . secrets.env; set +a`) is a THIRD reader the module cannot unify by construction. **#B269 (0.6.4) — a trailing `#` comment is now stripped** (previously swallowed into the value): the strip fires only when the `#` is preceded by whitespace AND outside quotes, because `abc#def` is a literal hash to a shell and `"abc # def"` is a quoted one — so quoting is a COMPLETE escape hatch, and the strip runs on the RAW pre-trim value (trimming first makes `KEY= # c` and `KEY=#c` indistinguishable while the shell reads them as `''` vs `'#c'`). Unquoting applies AFTER the strip, so `KEY="abc" # note` is `abc`, not `"abc"` — previously the comment defeated the `/^".*"$/` test and the quotes became part of the credential. Consequence to expect: `KEY= # comment` is now EMPTY, and empty counts as unset in both readers (`typeof v === 'string' && v !== ''`), so it fails closed and `secrets:check` reports UNSET where it previously reported a FALSE-GREEN SET. Two divergences REMAIN by decision — `KEY = value` (accepted+trimmed here, a shell errors) and `KEY="a"b"` (`a"b` here, `ab` in a shell) — so do NOT restate the parser as "whatever a POSIX shell does". **`getRequiredKeys(config)`** is the read-only, non-throwing sibling backing the OFFLINE CLI: `gina secrets:scan [<bundle>] [@project]` (which keys each bundle requires, grouped by file — sources derived from the manifest's `src`, never a guessed path) + `gina secrets:check` (marks SET/UNSET, exits non-zero — the CI gate), with `--scope=<s>` overlaying `config_<s>/` dirs READ-ONLY (the runtime loader stays scope-agnostic about config DIRS) and `--env-file` standing in for the ENV TIER. **#B263 (0.6.4) — `check` now reads BOTH runtime tiers, in order:** env, then the bundle's declared `secrets.file` chain resolved through the SAME global `whisper` + the shared `parseEnvFile`, so it can no longer report UNSET (and exit non-zero) for a key the bundle would have booted with — that false RED, not a false green, was the dominant real-world defect, since adding a source can only turn UNSET→SET. Parity is BY CONSTRUCTION: `homedir` comes from the project's own `env.json` (`<bundle>.<env>`) else the template's `~/.<projectName>`, NEVER `projects.json`'s `homedir` (a CLI-level field `config.js` never reads). A reps key is seeded only from a NON-EMPTY string — an absent key leaves its token verbatim and is caught loudly, but an EMPTY one substitutes SILENTLY (measured: `scope:''` → `/h//f.env`, which collapses to the base path on POSIX with no guard firing; whisper's pass 2 `dict[k]||s` leaves it, pass 3 `!==undefined` rescues it). `${scope}`/`${env}` are LAUNCH-time values the CLI cannot read (runtime prefers `NODE_SCOPE`/`NODE_ENV`), so the report NAMES the values it assumed, `--env` was added to pick the env block, and an unresolvable path is reported + its tier skipped rather than statted — under-reading can only make the gate stricter than the runtime, never laxer. **#B266 (`74e52cda`) — the reps dict must carry every token a REAL chain uses, not the ones the examples use.** The first consumer config (`${homedir}/v${projectVersionMajor}/credentials/[${scope}/]secrets.env`) resolved at runtime but NOT in `check`, re-opening the #B263 false-RED through three holes: (a) **version tokens absent** — the runtime does not list them in the bundle-config dict either, it gets them because `core/template/conf/env.json` declares `projectVersion`/`projectVersionMajor` as per-bundle SCALARS which the `:2356` harvest then copies in, so **reading only the `:2296` dict literal shows no version tokens and looks complete**; now seeded from the manifest; (b) **`${scope}` had no default** — now falls back to the project default via a SEPARATE `self.scopeAssumed` slot, because defaulting `self.scopeName` would start applying the `config_<scope>/` overlay to every bare invocation (two axes, one name); (c) **`~/.undefined`** — `buildReps` used `self.projectName`, undefined on the all-projects branch, yielding a real stat-able wrong path; now derived from the project PATH. Declaration resolution is pinned (`5a80b1a1`): bundle `secrets.file` REPLACES shared's (arrays never concatenate), `secrets:{}` INHERITS, `secrets:{file:null}` is the opt-out, and `--env-file` stays TOP tier (it stands in for the environment; demoting it below the files would model something the runtime never does). Each key's report names the tier that satisfied it. ⚠️ The other `secrets.resolve()` callers pass NO backend and stay env-only (`bundle:mcp-start`, `connector:infer`/`test`/`models` — #B264). Design of record: the framework RESOLVES secrets, the deployment layer STORES them. Since 0.6.4 it may additionally READ declared plaintext files as the LOWEST-precedence tier — opt-in `settings.secrets.file` in a bundle's `settings.json`, one path or an array written with the usual config tokens (`["${homedir}/secrets.env", "${homedir}/${scope}/secrets.env"]`), later entries winning. Files layer UNDER the environment (`getEnvVar` → `process.env` → files → throw), which INVERTS the usual `.env` intuition and is deliberate: every production delivery path (K8s `secretRef`, ECS task secrets, `sops exec-env`, a CI export) arrives via the environment, so a file that won could let a stale plaintext copy shadow the real credential. ⚠️ Precisely, it is a NON-EMPTY env value that wins (#B268, `90518bec`): a SET-but-EMPTY variable counts as ABSENT and the file fills it — deliberate and kept, because `environment: ["X=${X}"]` with the outer var unset puts an empty-but-SET var in the container (measured) and refusing would break working setups — but since a failed `export X="$(fetch …)"` produces that same shape, the fall-through WARNS, naming the key and never the value, at `warn` so the default `info` hierarchy keeps it. Undeclared ⇒ byte-identical to env-only; a declared-but-ABSENT file contributes nothing, but one that EXISTS and cannot be READ is FATAL (#B267, `90518bec`) — collapsing both to `null` let a `[base, per-scope]` chain whose per-scope file lost read permission boot silently on the SHARED credential (measured: `production_password` → `shared_dev_password`), announced only by a debug line MISLABELLED `ABSENT` which `info` suppresses; `env-file` now also exports `readEnvFile` (reports the errno — ENOENT vs EACCES/EISDIR; a dangling symlink is ENOENT, correctly absent), the backend refuses on anything non-ENOENT naming path + code, and `secrets:check` reports `UNREADABLE` so the CI gate and the runtime cannot disagree about a file neither can open; resolution stays fail-closed; paths carrying an unresolved `${…}` or a `${secret:…}` are rejected at boot. Selection reads `content.settings`, NOT `settings` — historically the only copy with tokens resolved, because `config.js` bound `.settings` BEFORE the token-substitution pass and `.content` after it, and substitution returns a NEW object rather than rewriting the original. **Since #B257 (0.6.7) the `.settings` alias is re-pointed at the post-substitution copy, so for a config built by `loadBundleConfig` the two are now the SAME object** and either read would serve; `content.settings` stays the canonical one because `selectBackend` accepts any config-shaped object, including ones assembled by other paths. ⚠️ The old rationale was never accurate AS STATED (#B273) and must not be restated: an EARLIER substitution pass already resolved `${homedir}` / `${scope}` in both copies, so what actually diverged was only the tokens pass 2 is the FIRST to know — `${bundlePath}`, `${libPath}`, `${publicPath}`, `${handlersPath}`, `${mountPath}`, `${gina}`, `${project}`, `${root}`, `${source}`, `${<name>Port}`, `${templates}`/`${html}`/`${theme}` and the `:2356` scalar harvest. `${secret:…}` was never affected in either copy, since `secrets.resolve()` walks the config IN PLACE and so reaches both subtrees. Consumer-visible consequence of the fix: a `getConfig().settings.<x>` read that used to hand back a literal `'${libPath}/…'` now returns the resolved path.It does NOT decrypt: for SOPS/Vault/KMS keep decrypting at the container entrypoint — a structural constraint, not a preference, since `lib/secrets` is fully synchronous and `config.js` holds the #P33 sync-init contract, so a network-backed backend would put a KMS round-trip inside a synchronous boot path. (The scope-agnostic note above is about `config_<s>/` DIRS, which the runtime still does not overlay; a secrets FILE path may be scope-varying via `${scope}`.) Consumers: `Csrf` (`settings.csrf.secret`), `bundle:mcp-start` (re-resolves `mcp.json` post-parse), `auth.machine` caller keys.
+98. **Secrets — `${secret:KEY}` config placeholders + the `secrets:scan`/`secrets:check` introspection CLI (absorbs former #135).** `lib/secrets` substitutes `${secret:KEY}` at config-load (`core/config.js::loadBundleConfig`, post-merge per bundle), resolving each key from the FRAMEWORK environment first (`getEnvVar`) and falling back to `process.env[KEY]`. **That two-tier read is load-bearing, not defensive (0.6.3, #B156):** the CLI MOVES every `GINA_*`/`USER_*`/`VENDOR_*` key OUT of `process.env` into `process.gina` (`filterArgs`, `utils/helper.js`), so a `${secret:GINA_*}` placeholder was previously unresolvable in ANY CLI-loaded config — `mcp.json` (the published example), the connector commands, `audit:verify` — and failed closed with a refusing boot. Non-`GINA_` keys are untouched by the sweep and resolve as before. The same idiom now backs the CSRF `GINA_CSRF_SECRET` tier and the MCP transport's `GINA_BIND_HOST`/`GINA_DIR` reads (#B157). ANCHORED: the regex matches only when the ENTIRE string value is the placeholder — mixed strings (`"prefix-${secret:K}-suffix"`) pass through unchanged; non-string scalars untouched; nested objects/arrays descend. **Fail-closed:** an unset/empty env var throws a GENERIC `Secret resolution failed` — the key name rides only a non-enumerable `_ginaSecretKey`, surfaced at debug level by the config-load catch naming key + `<bundle>/<env>:<scope>` (#B42), so consumer-visible surfaces never carry key names. Secret rotation needs a process restart (the resolver re-runs on `config.refresh()`, but the env is inherited from container init). Pluggable backend interface (`{resolve(key)}` — env-only by default, env-over-file once `secrets.file` is declared, env-over-exec once `secrets.exec` is declared; the two declared tiers are mutually exclusive by validation). **The two tiers are read INDEPENDENTLY, never joined by `||` (0.6.9, #B270):** `filterArgs` stores swept values as REAL booleans, so a truthy boolean used to satisfy the short-circuit and `process.env` was never consulted — the file tier then beat a SET environment variable, inverting the precedence the file backend exists to enforce. Only a non-empty STRING from the framework tier wins; a boolean, number, `undefined` or `''` falls through. `getResolvedPaths()` gives the dotted paths substituted in a config, but it is **not** a general redaction substrate (0.6.9, #B274): the paths address the config object and the lookup is keyed on its IDENTITY, so a consumer must hold the very object `resolve()` mutated — which rules out the Inspector, whose payload is a structural clone of the controller's VIEW data (`{gina, user}`), a different object in a different coordinate space. A surface holding VALUES rather than the config needs a value-based pass; `core/connectors/param-redact.js` exists for exactly that reason. **`secrets.file` shape guards (0.6.9):** `[]` still disables the tier like `null` but now WARNS rather than doing it silently (#B271 — an operator emptying the array to drop one layer drops the whole tier; boot is not refused, since an empty list genuinely means "no files"); a whitespace-only entry is REFUSED (`minLength: 1` counts a space, so `[" "]` used to build a tier that could never resolve anything); and a path containing an empty segment (`//`) is refused (#B272 — such a path does not name the file it appears to, since POSIX reads `<a>//<b>` as `<a>/<b>`; the DANGEROUS cause is a `${…}` token that resolved to EMPTY, leaving no token for the unresolved-token guard and silently reading the file one directory UP — `${homedir}/${scope}/secrets.env` with an empty scope — while the BENIGN cause is a token with a trailing slash such as an operator's `GINA_HOMEDIR=/opt/gina/`, which nothing in the path chain normalises. The two are indistinguishable once assembled, so boot refuses on both and the error names both causes rather than asserting one it cannot know; the benign case is a one-character fix). The schema gains `minItems: 1` as an editor-facing hint — no runtime validator loads `schema/settings.json`, so `lib/secrets` is the enforcement. **#B408 (0.6.14) — those declaration guards are ONE shared implementation for the runtime AND the gate:** `selectBackend` and `secrets:check` both consume `secrets.validateFilePaths` (`lib/secrets/src/declaration.js` — pure and require-free, first-error-wins in entry order, with the `${secret:…}` verdict outranking the generic unresolved-token one because the token regex matches a placeholder too), because the checker's hand-kept mirror had drifted twice in the LAX direction: the #B271 trim and #B272 `//` guards never reached it, so `settings.secrets.file: [" "]` and a token-collapsed `//` path passed `gina secrets:check` GREEN while boot REFUSED — the exact checker-vs-runtime disagreement the command exists to prevent, and the second #B263-class drift after the source walk. The gate now also validates BEFORE reading any layer, as boot does (an invalid declaration reports with NO layers read), and keeps its CLI-only `--scope`/`--env` hint by APPENDING to the shared message on the `file-unresolved-token` error code, never by forking the text. **FILE SYNTAX — one parser (`lib/secrets/src/env-file.js::parseEnv`) serves BOTH readers (`secrets:check` + the file backend), so the gate cannot green-light a file the runtime reads differently.** It targets what a POSIX shell `source`s, since the documented entrypoint (`set -a; . secrets.env; set +a`) is a THIRD reader the module cannot unify by construction. **#B269 (0.6.4) — a trailing `#` comment is now stripped** (previously swallowed into the value): the strip fires only when the `#` is preceded by whitespace AND outside quotes, because `abc#def` is a literal hash to a shell and `"abc # def"` is a quoted one — so quoting is a COMPLETE escape hatch, and the strip runs on the RAW pre-trim value (trimming first makes `KEY= # c` and `KEY=#c` indistinguishable while the shell reads them as `''` vs `'#c'`). Unquoting applies AFTER the strip, so `KEY="abc" # note` is `abc`, not `"abc"` — previously the comment defeated the `/^".*"$/` test and the quotes became part of the credential. Consequence to expect: `KEY= # comment` is now EMPTY, and empty counts as unset in both readers (`typeof v === 'string' && v !== ''`), so it fails closed and `secrets:check` reports UNSET where it previously reported a FALSE-GREEN SET. Two divergences REMAIN by decision — `KEY = value` (accepted+trimmed here, a shell errors) and `KEY="a"b"` (`a"b` here, `ab` in a shell) — so do NOT restate the parser as "whatever a POSIX shell does". **`getRequiredKeys(config)`** is the read-only, non-throwing sibling backing the OFFLINE CLI: `gina secrets:scan [<bundle>] [@project]` (which keys each bundle requires, grouped by file — sources derived from the manifest's `src`, never a guessed path) + `gina secrets:check` (marks SET/UNSET, exits non-zero — the CI gate), with `--scope=<s>` overlaying `config_<s>/` dirs READ-ONLY (the runtime loader stays scope-agnostic about config DIRS) and `--env-file` standing in for the ENV TIER. **The config-dir walk behind BOTH commands is ONE implementation in `lib/secrets` (`getProjectRequiredKeys(projectPath, {scope, bundle})` → `{bundles: [{bundle, byKey}]}`, provenance labels always on; the `loadManifest`/`readJsonSafe`/`resolveBundleSrc` leaves ride along for the handlers' own single-file reads):** the two handlers previously each carried a byte-near-identical copy of the walk — copies of exactly the kind #B263's drift came from — and the shared walk is also the enumeration a boot-time prefetch consumer would need. Non-throwing family: `null` for a bad `projectPath` or a missing manifest with no bundle filter; an explicit `bundle` filter is honoured VERBATIM (walks even a manifest-less project, src falling back to the bundle name — the historical CLI shape). It resolves `_()`/`requireJSON` at CALL time only, so module load needs no framework globals; and a config file that exists but does not PARSE follows requireJSON's own loud contract (emerg + exit while `console.emerg` exists) rather than the null-skip the old in-handler helper JSDoc claimed. **#B263 (0.6.4) — `check` now reads BOTH runtime tiers, in order:** env, then the bundle's declared `secrets.file` chain resolved through the SAME global `whisper` + the shared `parseEnvFile`, so it can no longer report UNSET (and exit non-zero) for a key the bundle would have booted with — that false RED, not a false green, was the dominant real-world defect, since adding a source can only turn UNSET→SET. Parity is BY CONSTRUCTION: `homedir` comes from the project's own `env.json` (`<bundle>.<env>`) else the template's `~/.<projectName>`, NEVER `projects.json`'s `homedir` (a CLI-level field `config.js` never reads). A reps key is seeded only from a NON-EMPTY string — an absent key leaves its token verbatim and is caught loudly, but an EMPTY one substitutes SILENTLY (measured: `scope:''` → `/h//f.env`, which collapses to the base path on POSIX with no guard firing; whisper's pass 2 `dict[k]||s` leaves it, pass 3 `!==undefined` rescues it). `${scope}`/`${env}` are LAUNCH-time values the CLI cannot read (runtime prefers `NODE_SCOPE`/`NODE_ENV`), so the report NAMES the values it assumed, `--env` was added to pick the env block, and an unresolvable path is reported + its tier skipped rather than statted — under-reading can only make the gate stricter than the runtime, never laxer. **#B266 (`74e52cda`) — the reps dict must carry every token a REAL chain uses, not the ones the examples use.** The first consumer config (`${homedir}/v${projectVersionMajor}/credentials/[${scope}/]secrets.env`) resolved at runtime but NOT in `check`, re-opening the #B263 false-RED through three holes: (a) **version tokens absent** — the runtime does not list them in the bundle-config dict either, it gets them because `core/template/conf/env.json` declares `projectVersion`/`projectVersionMajor` as per-bundle SCALARS which the `:2356` harvest then copies in, so **reading only the `:2296` dict literal shows no version tokens and looks complete**; now seeded from the manifest; (b) **`${scope}` had no default** — now falls back to the project default via a SEPARATE `self.scopeAssumed` slot, because defaulting `self.scopeName` would start applying the `config_<scope>/` overlay to every bare invocation (two axes, one name); (c) **`~/.undefined`** — `buildReps` used `self.projectName`, undefined on the all-projects branch, yielding a real stat-able wrong path; now derived from the project PATH. Declaration resolution is pinned (`5a80b1a1`): bundle `secrets.file` REPLACES shared's (arrays never concatenate), `secrets:{}` INHERITS, `secrets:{file:null}` is the opt-out, and `--env-file` stays TOP tier (it stands in for the environment; demoting it below the files would model something the runtime never does). Each key's report names the tier that satisfied it. ⚠️ The other `secrets.resolve()` callers pass NO backend and stay env-only (`bundle:mcp-start`, `connector:infer`/`test`/`models` — #B264). Design of record: the framework RESOLVES secrets, the deployment layer STORES them. Since 0.6.4 it may additionally READ declared plaintext files as the LOWEST-precedence tier — opt-in `settings.secrets.file` in a bundle's `settings.json`, one path or an array written with the usual config tokens (`["${homedir}/secrets.env", "${homedir}/${scope}/secrets.env"]`), later entries winning. Files layer UNDER the environment (`getEnvVar` → `process.env` → files → throw), which INVERTS the usual `.env` intuition and is deliberate: every production delivery path (K8s `secretRef`, ECS task secrets, `sops exec-env`, a CI export) arrives via the environment, so a file that won could let a stale plaintext copy shadow the real credential. ⚠️ Precisely, it is a NON-EMPTY env value that wins (#B268, `90518bec`): a SET-but-EMPTY variable counts as ABSENT and the file fills it — deliberate and kept, because `environment: ["X=${X}"]` with the outer var unset puts an empty-but-SET var in the container (measured) and refusing would break working setups — but since a failed `export X="$(fetch …)"` produces that same shape, the fall-through WARNS, naming the key and never the value, at `warn` so the default `info` hierarchy keeps it. Undeclared ⇒ byte-identical to env-only; a declared-but-ABSENT file contributes nothing, but one that EXISTS and cannot be READ is FATAL (#B267, `90518bec`) — collapsing both to `null` let a `[base, per-scope]` chain whose per-scope file lost read permission boot silently on the SHARED credential (measured: `production_password` → `shared_dev_password`), announced only by a debug line MISLABELLED `ABSENT` which `info` suppresses; `env-file` now also exports `readEnvFile` (reports the errno — ENOENT vs EACCES/EISDIR; a dangling symlink is ENOENT, correctly absent), the backend refuses on anything non-ENOENT naming path + code, and `secrets:check` reports `UNREADABLE` so the CI gate and the runtime cannot disagree about a file neither can open; resolution stays fail-closed; paths carrying an unresolved `${…}` or a `${secret:…}` are rejected at boot. Selection reads `content.settings`, NOT `settings` — historically the only copy with tokens resolved, because `config.js` bound `.settings` BEFORE the token-substitution pass and `.content` after it, and substitution returns a NEW object rather than rewriting the original. **Since #B257 (0.6.7) the `.settings` alias is re-pointed at the post-substitution copy, so for a config built by `loadBundleConfig` the two are now the SAME object** and either read would serve; `content.settings` stays the canonical one because `selectBackend` accepts any config-shaped object, including ones assembled by other paths. ⚠️ The old rationale was never accurate AS STATED (#B273) and must not be restated: an EARLIER substitution pass already resolved `${homedir}` / `${scope}` in both copies, so what actually diverged was only the tokens pass 2 is the FIRST to know — `${bundlePath}`, `${libPath}`, `${publicPath}`, `${handlersPath}`, `${mountPath}`, `${gina}`, `${project}`, `${root}`, `${source}`, `${<name>Port}`, `${templates}`/`${html}`/`${theme}` and the `:2356` scalar harvest. `${secret:…}` was never affected in either copy, since `secrets.resolve()` walks the config IN PLACE and so reaches both subtrees. Consumer-visible consequence of the fix: a `getConfig().settings.<x>` read that used to hand back a literal `'${libPath}/…'` now returns the resolved path.The FILE tier does NOT decrypt — pointed at ciphertext it yields ciphertext, silently. **Since 0.6.14, `settings.secrets.exec` is the sanctioned in-process bridge for SOPS/Vault/K8s (#SECRETS3):** ONE operator-declared command — argv array, NO shell — run once per bundle per config-load cycle at boot only, whose stdout must be a single flat JSON object of string values (`sops decrypt --output-type json` on a flat secrets file emits it directly, measured end-to-end; `vault`/`kubectl` need a 2-3 line wrapper script — see the guide's recipes), layered UNDER the environment exactly like the file tier and MUTUALLY EXCLUSIVE with it: a bundle inheriting a shared `file` chain escapes with `"file": null` beside its own `exec` block (the refusal message names it), `"exec": null` symmetrically; unknown `secrets` keys and non-object blocks now REFUSE the boot instead of silently degrading to env-only (runtime parity with the schema's `additionalProperties: false`). The boot STAYS synchronous (#P33 intact): the fetch is `spawnSync` bounded by `timeout` (default 10000ms, 2× the house probe class) and killed with **SIGKILL** on expiry — measured-mandatory, not caution: the default SIGTERM leaves `spawnSync` BLOCKED past its timeout against a signal-ignoring child and then reports `{error: ETIMEDOUT, status: 0}`, which is also why the result check reads `.error` BEFORE `.status` (a status-first read calls that shape a success). So a wedged KMS becomes a FAILED boot, never a hung one — every fetch failure (timeout, missing binary, non-zero exit with stderr tail quoted, malformed output) is the per-bundle boot refusal through `config.js`'s existing catch. stdout is the secrets payload and NEVER appears in any error, log or report (a non-string value's key rides the debug channel only); auth travels via environment variables, never argv (`ps`-visible), and the child inherits `process.env` (the #B156 sweep means `GINA_*` / `VENDOR_*` / `USER_*` keys are invisible to it in CLI/daemon processes). `secrets:check` mirrors the tier by RUNNING the declared command through the runtime's own `fetchExecMap` (same timeout, same SIGKILL bound, same output contract — a validate-only mirror would false-RED every exec-supplied key, the #B263 shape), and **#B409 (0.6.14)**: declaration/fetch errors now fail the gate's EXIT CODE too — both exit sites widened to `anyUnset || anyError`; previously a boot-refusing declaration exited 0 whenever the environment happened to carry the keys. **The entrypoint decrypt remains the BETTER pattern wherever the entrypoint can be controlled** (`sops exec-env`, K8s `envFrom` secretRef, Vault agent-injector — values land in the environment, which every tier already defers to): `exec` supports that pattern for environments that cannot, it does not replace it. (The scope-agnostic note above is about `config_<s>/` DIRS, which the runtime still does not overlay; a secrets FILE path may be scope-varying via `${scope}`.) Consumers: `Csrf` (`settings.csrf.secret`), `bundle:mcp-start` (re-resolves `mcp.json` post-parse), `auth.machine` caller keys.
 
 125. **CLI handler authoring & operations — consolidated** (replaces individual entries #17, #23, #24, #55, #56, #58, #59, #60, #62, #63, #102, #112; plus #161, #166, #167, #181, #182, #183, #185, #199, #201, #202, #203 folded 2026-07-05):
 - **CLI stubs** — `gina --status` / `gina -t` appear in help.txt or docs but have no handler (not in `aliases.json`); tracked in `ROADMAP.md § CLI`; never suggest to users without checking the handler file first. `bundle:status` / `project:status` / `minion:list` / `minion:kill` / `protocol:remove` / `bundle:copy` (+ `cp` alias) / `bundle:rename` shipped 0.4.1-alpha.2; `project:move` / `project:backup` / `project:restore` / `framework:update` / `framework:man` (+ `project:man` / `bundle:man` / `service:man`) — the **CLI Tier 3** finals — shipped 0.5.x (full coverage in the two CLI Tier 3 sub-bullets below). Both minion commands are run-dir-driven process-truth (the "minion" abstraction is half-wired — nothing sets `process.isMinion` or writes `*minion*.pid`, so a minion == any running bundle child-process): `minion:list` lists every live `<bundle>@<project>.pid` grouped by project via `lib.cmdStatusFormat`; `minion:kill @<project>` reaps them (hybrid kill-set = run-dir pidfiles + a `ps -ef | grep 'gina: ...@<project>'` sweep for pidfile-less orphans bundle:stop misses), SIGTERM→grace→SIGKILL escalation, `--dry-run` preview, unlinks stale/killed pidfiles, never touches mount symlinks or its own PID. `protocol:remove <bundle> @<project>` reverts a bundle to the project default protocol by deleting ONLY its `server.protocol/scheme/allowHTTP1` override from the bundle's `settings.json` (config.js `:1014/:1020` auto-defaults an absent protocol to `def_protocol`/`def_scheme`); it deliberately does NOT mutate the shared `ports*.json` — `project:add` pre-allocates the full protocol×scheme×env matrix, so the default-protocol port already exists and pruning the set's port would be wrong; a per-env port-presence guard refuses (unless `--force`) when the default-protocol port is missing; `--dry-run` preview, header-preserving JSON rewrite (connector:rm pattern). `bundle:copy <source> <new> @<project>` (+ `cp`) duplicates a bundle under a new name in the SAME project: copies the `src/<source>` tree, then word-boundary-rewrites the name footprint (PascalCase `<Src>`→`<Dst>` for controller class names + lowercase whole-word `<src>`→`<new>` for the gina require-var / `app.json` name / webroot path, `.js`/`.json` files only — embedded tokens like `apiClient` are untouched; a first-bundle webroot `/` is repointed to `/<new>`), allocates a fresh FULL protocol×scheme×env port matrix via the shared `setPorts` (a single-port insert would later emerg in `config.js`, which expects the complete matrix), and clones+repoints the source's manifest entry (`src`/`link`/`releases` target paths). `--dry-run` previews every rewrite site before writing; `--force` overwrites an existing target (its `removeDest` mirrors `bundle:remove`'s deletions). TWO positionals leave `self.name` null (CmdHelper sets it only for a single positional), so the handler reads `self.bundles[0]`/`[1]` directly — which also slips past the `cmd.name`-gated existence guard so the not-yet-registered new name isn't rejected. `bundle:rename <old> <new> @<project>` is the move-sibling — it renames a bundle IN PLACE in the same project (`fs.renameSync` move, NOT a copy) reusing the same `inc/name-rewrite.js` engine but with `fixWebroot:false` (rename moves the only bundle, so there's no first-bundle/collision case; a name-derived `/<old>` webroot is still rewritten by the lowercase pass). Its ports are REKEYED, not reallocated — port NUMBERS are preserved: `ports.json` rewrites the `<old>@<project>/` owner prefix back into the SAME `[protocol][scheme][portKey]` slot (avoiding the two `project/rename.js` bugs: the wrong `[protocol][portKey]` slot, and a project-wide owner replace), then `ports.reverse.json` is rekeyed (`pr[new]=pr[old]; delete pr[old]`) and flipped LAST as the canonical existence record. It REFUSES a running bundle with NO `--force` bypass (`--force` only overwrites an existing dest); the whole multi-surface mutation (symlink → renameSync dir → rewrite tree → env → manifest → ports → ports.reverse) is snapshot-guarded (the `bundle:add` rollback model) so any post-move failure reverses the dir move and restores env/manifest/ports/ports.reverse from in-memory snapshots. NOTE: the ROADMAP's "fix the help.txt remouve typo" item was stale — no such typo existed.
@@ -899,7 +899,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 210. **Multipart upload config is ENFORCED — groups, destination, limits, text-field capture + caps, terminal states (consolidates former #187/#188/#228/#230's server half; #B49/#B50/#B51/#B92-adjacent/#B93/#B97).** Every uploaded file must map to a CONFIGURED upload group: the resolved group (no/empty → the default `untagged`) must exist in `settings.json upload.groups` or the request is rejected 400 BEFORE the temp file is created, and `untagged` obeys its own config like any named group (pre-#B50 the checks ran only for defined non-`untagged` groups — an allow-list bypass; the shipped `untagged` default is `allowedExtensions: '*'` + `isMultipleAllowed: true`, so configure `untagged` restrictively or a client can route around a named group's allow-list). Destination + limits honoured: files stream to `uploadDir || tmpPath || os.tmpdir()` with a per-group `path` override and mkdir-if-missing before `createWriteStream` (the mkdir itself crash-guarded → 500, #B145); `maxFields` caps the per-request file COUNT (400 past the cap; 0/unset disables); `maxFieldsSize` parses its unit suffix (B/KB/MB/GB; bare number = MB) as the whole-body cap (431). **Multipart TEXT fields are captured** — a real busboy `'field'` listener (busboy silently SKIPS all non-file parts when none is registered) exposes them on `req.body` + `req[method]` (POST/PUT/PATCH only), values VERBATIM (no url-decode, no `"true"/"false"/"on"/"null"` coercion — the JSON body contract, deliberately: otherwise the same client `send(fd)` call would change value TYPES with file presence), bracket-notation names nested through the urlencoded path's own layer, duplicate plain names last-wins; caps `upload.maxTextFields` (default 1000) + `upload.maxTextFieldSize` (default 1MB, unit-aware, explicit 0 = no limit) answer 400 on breach instead of busboy's silent skip/truncation. **A multipart request with no successfully-parsed file part reaches a TERMINAL state:** fields-only → the request resumes; malformed/empty → 400 via `busboy.on('error')` with a double-response guard (busboy terminates in exactly `finish` XOR `error`; pre-#B93/#B97 both were unauthenticated pre-routing DoS holes — an eternal hang, and an uncaughtException → SIGTERM bundle kill). Rules: a per-group restriction is only a control if the UNCONFIGURED/default case is denied or constrained, never waved through; a documented config key is only real if a code path reads it — grep the consumer before assuming a setting works; any stream/parser whose SUCCESS path drives a request's continuation must ALSO handle its error/empty terminals. Since #STO1 slice 1 a group may also carry driver: '<name>', routing its self.store() step through settings.storage (entry #300; the parse/staging path above is unchanged). Server-side only. Tests: `test/core/upload-groups.test.js` + `upload-config.test.js` + `multipart-nonfile-terminal.test.js` + `multipart-field-capture.test.js` (+ the client `send(FormData)` half: `validator-send-formdata-multipart-fields.test.js`). **Server-path integrity + terminal-state hardening (former #263/#267/#268/#270 — #B103/#B142/#B143/#B144/#B145/#B223, 0.5.22-0.5.24):** a multipart body stays RAW end-to-end — `request.isMultipart` is computed ONCE at the request prologue and gates the request-stream `setEncoding` (a multipart stream reaches busboy as raw Buffers, its documented input; the decode remains for the text-body branches), write-pipeline chunks pass through VERBATIM, and `req.files[].size` counts BYTES, never a decoded string's length (#B103 — pure-ASCII surviving both old decode layers is why text uploads always worked while every real binary corrupted on every native multipart client: a PNG's 0x89 magic landed as 0xFD). The per-file `size` is finalized in the liner Transform's `_flush` (#B142 — the source-'end' record ran one pipe hop UPSTREAM of the byte counter with 16-object high-water marks still queued, under-counting ~25% on a 1.5MB file while md5 stayed perfect: the bytes were intact, only the number lied; `_flush` runs after the last `_transform` and strictly before the write stream can emit 'finish', both interleavings measured exact), and BOTH write-stream terminal listeners arm AT STREAM CREATION in the 'file' handler (#B143 — arming inside `busboy.on('finish')` lost the race for any early-finishing small file: Node never replays 'finish' for a late listener, so a throttled two-file upload hung deterministically, ~1 in 13 unthrottled; unauthenticated, both engines). Resume fires on `busboyDone && pending === 0`, whichever event lands last (the zero-pending branch still covers the fields-only #B93 terminal), and a mid-stream write error (missing dir, disk full) gets a guarded 500 instead of the historical unhandled-'error' uncaughtException SIGTERM. Downstream, `Controller.store()`'s mover streams each file to a temp sibling and publishes with an ATOMIC rename (a reader never observes a partial file; a pre-existing destination is replaced only on success), propagates the REAL filesystem Error (previously masked as `No file to upload`), and never settles the callback twice (#B223). Since #B227 the SAME semantics govern the general-purpose byte-writer in `helpers/path.js` behind `_().cp()` / `PathObject.mv()` (which CLI copy/build/rename paths ride): temp sibling in the destination's own directory + atomic rename (a pre-existing destination is no longer unlinked BEFORE the copy — its content survives a failed copy), a source-stream error listener (was an unhandled `error` event → process kill), a settled latch (a destination-side failure previously settled twice, the second time as a success, forking `browseCopy`'s directory recursion), and a real `Error` instead of the former plain string (`Error on Path.cp(...): Not found ...`) — so caller `err.stack` prints stop logging `undefined`. The destination mkdir is crash-guarded (#B145): a group whose custom `path` has a read-only/EACCES/EROFS parent answers a guarded 500 naming group + path — a server CONFIG problem is 500 (the #B50 unconfigured-group 400 stays upstream and unchanged), and pre-fix `fs.mkdirSync` threw SYNCHRONOUSLY inside the parser callback → uncaughtException → SIGTERM, an unauthenticated single-request bundle kill (the multipart parse precedes routing and all middleware, both engines). A per-group `simulateWriteError: true` flag (#B144) lets a consumer deterministically fire the guarded-500 write-error path OUTSIDE production scope only (`!NODE_SCOPE_IS_PRODUCTION`): the 'file' handler creates the REAL write stream, arms the REAL terminal listeners, then synthetically `destroy()`s it — the exact terminal semantics of a real ENOSPC/EIO (an errored stream never emits 'finish', so the request stays terminal at the 500), N destroyed parts collapsing to exactly ONE 500 via throwError's `!res.headersSent` guard; a boot warn scans `upload.groups` for the flag in both scopes (production: "IGNORED — remove before shipping"; else "PROBE active"); nothing ships active. The `group="…"` tag rides a Content-Disposition PARAMETER that `curl -F` / browser FormData cannot emit (the `@rhinostone/busboy` fork parses it into `info.dispositionParams.group`), so a faithful probe HAND-BUILDS the multipart body. **The staged upload client layer (`data-gina-form-upload-*`, lives in the validator plugin — browser-bundled ⇒ consumers RE-BAKE at pickup; former #269/#271/#272/#274 — #R8 slices 1-2, #B146/#B147/#B148/#B149):** the staging POST body is assembled as a `Blob` with each File object embedded RAW (#B148 — the historical `FileReader`/`ab2str` DOMString concatenation UTF-8-inflated every byte >= 0x80 on the wire, ×1.49 measured, a PNG's 0x89 arriving as 0xC2 0x89; the corruption only STARTED at 0.5.22 because the pre-#B103 server's two since-removed decode layers EXACTLY reversed the inflation — two wrongs cancelling — so the #B103 server fix is what exposed the client defect). Multipart FRAMING is byte-identical (same boundary delimiters, same `name=`/`group=`/`filename=` disposition-parameter set, values percent-escaped for CR/LF/double-quote per RFC 7578 §5.1.1); a fixed client must pair with a server >= 0.5.22 (an older server's decode layers would corrupt the now-raw bytes — the #B103 corruption in reverse); files corrupted by the defect are LOSSLESSLY recoverable (the stored bytes are exactly the UTF-8 encoding of the originals: decode utf8 → re-encode latin1). **Upload progress (#R8 slice 1):** `send()` assigns `xhr.upload.onprogress` FRESH on every send (the module-scoped XHR was reused across sends — a stale handler replays the previous send's closure with the wrong id), dispatching the REGISTERED event `uploadProgress.<uploadFormId>` (the events-array registration is required — `on()` validates names against the plugin registry) with `{ status: 100, progress: <int 0-100 | null when lengthComputable is false>, loaded, total, lengthComputable, files: [names] }` — a per-REQUEST aggregate (ONE staging XHR carries every file of a selection; per-file wire progress is not separable). Consumer surfaces: `data-gina-form-upload-on-progress` (bare window identifier, the -on-success convention) + a declarative indicator `data-gina-form-upload-progress="<elId>"` defaulting to `<fieldId>-progress`, opt-in by element presence. The updater feature-detects the target: a native `<progress>` tracks value=loaded/max=total (indeterminate = the value attribute REMOVED for the native animation; error = value 0, NEVER indeterminate — that animation would read as still working); any other element gets percent textContent + `data-gina-upload-progress`/`data-gina-upload-progress-state` styling hooks (preparing|uploading|indeterminate|processing|complete|error) with NO hardcoded wording (i18n-neutral — label via CSS on the state attribute). Lifecycle: `preparing` at selection (covers the FileReader/assembly phase), `uploading` per frame, `processing` at `xhr.upload.onloadend` (the browser finished SENDING — advances the state attribute ONLY, leaving value/percent as the last frame left them so a determinate bar stays visually full), `complete`/`error` finalized in onUpload (one chokepoint covers success and every error/timeout path), reset/delete strips the indicator. The response-side download channel `progress.<id>` is byte-untouched (it also serves attachment downloads). **Drag-and-drop (#R8 slice 2):** a file input carrying `data-gina-form-upload-dropzone="<elementId>"` gets drag listeners bound on the named element at form-bind time; dropped files are assigned to the input (`input.files = dataTransfer.files`) and the input's `change` is re-fired synthetically, so the ENTIRE staging pipeline — group tagging, virtual form, staging POST, previews, hidden metadata fields, reset/delete, upload progress — runs with zero duplicated logic (the change handler reads only `currentTarget`, so a synthetic dispatch is indistinguishable from a trusted one on this path). Contract: EXPLICIT-id-only (deliberately NO `<fieldId>-dropzone` default — auto-binding a coincidentally-named element would attach drag semantics to markup that may carry its own drop handling; absent attribute = inert, missing element = console.warn + inert); the zone is stamped `data-gina-upload-dropzone` (value = owner input id — the first-wins guard: one zone serves one input) and `data-gina-upload-dropzone-state` (`idle` → `over` on a file-drag hover, DEPTH-COUNTED so child-boundary crossings never flicker → `dropped` → back to `idle` at the same onUpload chokepoint that finalizes progress, and at reset/delete) — pure CSS hooks, no hardcoded wording. Only FILE drags react (`dataTransfer.types` must carry `Files`; text/link drags fall through untouched, never preventDefault'd); a multi-file drop on a non-`multiple` input keeps the FIRST file only (console.warn) — configured groups still enforce `isMultipleAllowed` server-side; a bare file input already accepts native browser drops through the same change handler — the attribute exists to delegate a larger/styled element. **Action/preview/bind fixes (#B146/#B147/#B149):** `checkUploadUrlActions`'s default-route fallback writes the attribute ACTUALLY being checked (`setAttribute(action, …)` — it used to hardcode the staging attribute and silently repoint a staging POST at the resolved reset/delete default route, compounding to a SILENT failure when `toUrl()`'s absolute origin tripped a CORS preflight → XHR status-0 → the commented-out status-0 branch); the preview-container guard uses the typeof-null pattern (`&& previewContainer` — `getElementById` returns element|null and `typeof null === 'object'`, so a preview-element MISS used to TypeError the success handler at `.id`); an upload-only input binds QUIETLY — `-delete-action` deliberately has no framework default (it removes an already-saved file, an app-specific endpoint), so a no-default absent action is a single `console.debug` + early return (a WITH-default action that genuinely fails to resolve still errors; the delete requirement stays enforced lazily at `onUploadResetOrDelete`). Tests: `upload-binary-integrity.test.js` / `upload-size-accuracy.test.js` (11) / `multipart-multifile-resume.test.js` (15) / `upload-write-error-probe.test.js` / `upload-config.test.js §07` / `validator-upload-progress.test.js` (46) / `validator-upload-binary-wire.test.js` / `validator-upload-action-guard.test.js` — all red-first-validated with control-gated extractions of the shipped bytes.
 
-211. **Request-body parsing contract — verbatim JSON, `req.rawBody`, and crash-safe decodes (consolidates former #162/#163/#164; #B28/#B30/#B64).** `application/json` bodies (POST/PUT/PATCH) parse VERBATIM first — `JSON.parse(request.body)`, with a `decodeURIComponent` fallback ONLY when that throws — so the client's exact types and string contents survive (no double-decode, no `"true"/"false"/"on"/"null"` coercion, no bracket-key expansion; urlencoded/absent content-types keep the legacy decode+coerce path; error disposition unchanged — POST/PATCH 500 only when both attempts fail, PUT warns). The framework's own server-to-server client (`self.query()`) sends raw `JSON.stringify(data)` for JSON bodies (RFC5987 value-encoding is for header values, not request bodies), and the inter-bundle HTTP/2 proxy no longer copies the INCOMING request's Content-Type onto the outbound JSON body it serialized itself — a urlencoded label re-routed raw JSON through the receiving parser's urlencoded branch and corrupted string values (the only incoming-CT→outbound copy framework-wide; kept for non-JSON bodies). `request.rawBody` snapshots the exact unparsed body (reference assignment, always-on, non-multipart only, `''` for empty) immediately BEFORE parsing mutates `request.body` — inbound-webhook HMAC verification needs the raw bytes, which middleware cannot recover after the stream drains; both engines share this single `core/server.js` pipeline. Malformed percent-escapes (`%`, `%zz`, truncated `%E0%A`) in a URL or query no longer kill the bundle (#B30 — an unauthenticated single-request DoS: any unguarded `decodeURIComponent` OR `decodeURI` on the request path threw `URIError` → uncaughtException → SIGTERM): redundant SECOND decodes on the GET/HEAD branches were DROPPED (the engine query parser + the data helper each already decode once, guarded), and every genuine first decode of attacker-controllable input routes through `safeDecodeURIComponent`/`safeDecodeURI` (try/decode/fallback-to-raw) — including the ERROR paths, where a malformed-% URL to a missing asset previously crashed FROM the error handler, turning a would-be 404 into a bundle kill. Sweep rule: `decodeURIComponent` and `decodeURI` are the same throwing family — sweep BOTH; fix the throw sites, never widen the uncaughtException net. Sibling #B64 (0.5.7): the two static-file resolvers confine the resolved filename to the matched mapping target (`path.resolve` both sides + separator-aware containment), so `../` / `%2F` / `%2e%2e` cannot escape to sibling files — an escape 404s exactly like a missing file. Second site, same guard (#B179, Security/CWE-22): the dev-mode Inspector SPA handler (`/_gina/inspector/*`) built its filename the same way — request target minus the prefix, joined onto the asset root, passed through the `_()` path helper — and `_()` calls `Path.normalize`, which **RESOLVES** `..` rather than rejecting it, so a literal `../` read any absolute path the bundle process could reach (verified live: 200 on `/etc/passwd`; encoded `%2e%2e` unaffected, since this handler never decodes — and decoding was deliberately not added). Node does not normalise the request-target (only clients do), so a raw HTTP client reaches it where a browser cannot. Unlike the static resolvers, this handler is **DUPLICATED per engine** (server.js + server.isaac.js) and `confineToBase` is scoped inside server.js's `Server()` closure — unreachable from isaac, which therefore declares an engine-local twin, pinned against drift by a test asserting both extracted copies agree. **Rule: any handler joining request-derived segments onto a base MUST confine the RESOLVED path; path normalisation is not a traversal defence, it is the mechanism that makes the escape land.** Corollary for endpoint families: check the SIBLING handlers' gating too — the Inspector endpoint carries no IP allowlist while its `/_gina/*` neighbours (`info`, `cache/stats`, `cache/clear`) all gate on `lib.admin.isClientAllowed`.
+211. **Request-body parsing contract — verbatim JSON, `req.rawBody`, and crash-safe decodes (consolidates former #162/#163/#164; #B28/#B30/#B64).** `application/json` bodies (POST/PUT/PATCH) parse VERBATIM first — `JSON.parse(request.body)`, with a `decodeURIComponent` fallback ONLY when that throws — so the client's exact types and string contents survive (no double-decode, no `"true"/"false"/"on"/"null"` coercion, no bracket-key expansion; urlencoded/absent content-types keep the legacy decode+coerce path; error disposition unchanged — POST/PATCH 500 only when both attempts fail, PUT warns). The framework's own server-to-server client (`self.query()`) sends raw `JSON.stringify(data)` for JSON bodies (RFC5987 value-encoding is for header values, not request bodies), and the inter-bundle HTTP/2 proxy no longer copies the INCOMING request's Content-Type onto the outbound JSON body it serialized itself — a urlencoded label re-routed raw JSON through the receiving parser's urlencoded branch and corrupted string values (the only incoming-CT→outbound copy framework-wide; kept for non-JSON bodies). `request.rawBody` snapshots the exact unparsed body (reference assignment, always-on, non-multipart only, `''` for empty) immediately BEFORE parsing mutates `request.body` — inbound-webhook HMAC verification needs the raw bytes, which middleware cannot recover after the stream drains; both engines share this single `core/server.js` pipeline. Malformed percent-escapes (`%`, `%zz`, truncated `%E0%A`) in a URL or query no longer kill the bundle (#B30 — an unauthenticated single-request DoS: any unguarded `decodeURIComponent` OR `decodeURI` on the request path threw `URIError` → uncaughtException → SIGTERM): redundant SECOND decodes on the GET/HEAD branches were DROPPED (the engine query parser + the data helper each already decode once, guarded), and every genuine first decode of attacker-controllable input routes through `safeDecodeURIComponent`/`safeDecodeURI` (try/decode/fallback-to-raw) — including the ERROR paths, where a malformed-% URL to a missing asset previously crashed FROM the error handler, turning a would-be 404 into a bundle kill. Sweep rule: `decodeURIComponent` and `decodeURI` are the same throwing family — sweep BOTH; fix the throw sites, never widen the uncaughtException net. Sibling #B64 (0.5.7): the two static-file resolvers confine the resolved filename to the matched mapping target (`path.resolve` both sides + separator-aware containment), so `../` / `%2F` / `%2e%2e` cannot escape to sibling files — an escape 404s exactly like a missing file. Second site, same guard (#B179, Security/CWE-22): the dev-mode Inspector SPA handler (`/_gina/inspector/*`) built its filename the same way — request target minus the prefix, joined onto the asset root, passed through the `_()` path helper — and `_()` calls `Path.normalize`, which **RESOLVES** `..` rather than rejecting it, so a literal `../` read any absolute path the bundle process could reach (verified live: 200 on `/etc/passwd`; encoded `%2e%2e` unaffected, since this handler never decodes — and decoding was deliberately not added). Node does not normalise the request-target (only clients do), so a raw HTTP client reaches it where a browser cannot. Unlike the static resolvers, this handler is **DUPLICATED per engine** (server.js + server.isaac.js) and `confineToBase` is scoped inside server.js's `Server()` closure — unreachable from isaac, which therefore declares an engine-local twin, pinned against drift by a test asserting both extracted copies agree. **Rule: any handler joining request-derived segments onto a base MUST confine the RESOLVED path; path normalisation is not a traversal defence, it is the mechanism that makes the escape land.** Corollary for endpoint families: check the SIBLING handlers' gating too — the Inspector endpoint carries no IP allowlist while its `/_gina/*` neighbours (`info`, `cache/stats`, `cache/clear`) all gate on `lib.admin.isClientAllowed`. **GET/HEAD query serialization no longer destroys escapes (#B407, consumer-reported):** both branches round-trip `request.query` through JSON.stringify + a re-parse, and the former textual nested-JSON unwrap ended with a blanket backslash strip over the WHOLE serialized document — so `%0A` in a value became the letter `n`, a backslash vanished, and a double quote OR a JSON-ARRAY value produced invalid JSON that silently dropped EVERY query param on the request (`parseBody` logs `[365]` and returns undefined). Both sites now serialize via `serializeQueryForReparse` (a shared inner helper in `processRequestData`): each own STRING value leaning `{`/`[` is unwrapped by PARSING it (kept verbatim when it does not parse — previously that shape also dropped the whole query), then a clean stringify with no post-processing; the whole-value `"true"/"false"/"on"/"null"` coercion is unchanged and, with escapes intact, can no longer match an escaped occurrence embedded inside a longer value. Intended behaviours preserved byte-for-byte (nested-object unwrap — now also correct for nested content carrying escapes, which the textual unwrap corrupted as well — coercion, plain values); array-valued and unparsable-`{`-leading params are delivered instead of killing the query.
 
 212. **Structured (JSON) logging — `GINA_LOG_FORMAT=json` + per-request `requestId`/`durationMs` (consolidates former #152/#155; #M12a/#M12b).** The logger resolves its render format ONCE at init into `opt.format` (precedence `GINA_LOG_FORMAT=json|text` > `GINA_LOG_STDOUT` truthy ⇒ json > `text` default) BEFORE containers are cloned; a JSON line is `{ts, level, bundle, message, group, msg}` — `bundle`/`message` canonical, `group`/`msg` retained as additive back-compat aliases — and the raw `console.log` path honours the format too (otherwise JSON mode would interleave plain lines and break a collector); the `text` default keeps container logs byte-identical. Per-request `requestId` + `durationMs` ride JSON logs via a NARROW `AsyncLocalStorage` (`process.gina._reqALS`, parked on `process.gina` so it survives dev require-cache busting), gated on JSON logging ONLY (text renders no id field, so the ALS would be pure overhead — the text path stays byte-identical/zero-cost): the id resolver honours a SANITISED inbound `X-Request-Id` (`/^[\w.\-]{1,128}$/`, regenerate-on-violation kills log forging) else `crypto.randomUUID()`; the `.run({requestId, startMs})` wrap sits at `handle()` — NOT the request-entry handler — because the `request.on('end')` boundary between them loses async context while `handle()`'s awaits preserve it (the original body became `_handleDispatch`; `handle` is a thin wrapper); HTTP/2 gets per-stream scoping free via Node's per-stream compat `'request'` event, NOT `session.on('stream')`; the JSON-assembly sites read `getStore()` and add `requestId` + per-line `durationMs`, gracefully absent for CLI/boot/off-request logs. `.run()`, never `enterWith()` (enterWith bleeds sideways across siblings). **MS1 (2026-07-24, 0.5.25):** the same id is now PROPAGATED beyond the process — every `self.query()` outbound path (the file-download proxy + both the HTTP/1 and HTTP/2 inter-bundle clients) forwards it as `x-request-id` (sourced from the resolved `req._ginaReqId`, never a raw inbound header; a caller-set value always wins), and `server.js onRequest` ECHOES `X-Request-Id` back on every response — ungated / independent of `GINA_LOG_FORMAT` (the id is always-on even when the JSON-log field isn't) and guarded against an already-sent response — so one logical request stays correlatable as it fans out across bundles and a caller/LB/APM reads the id off the wire. `controller.js`/`server.js` are server-side → no dist rebuild; restart to apply. Tests: `test/core/request-id-propagation.test.js`. **The contextless `require('gina')` boundary + MQ-speaker transport resilience (moved here from the DTO entry that surfaced it; #B276/#B277 0.6.4, #B318 0.6.5, #B323 fixed post-0.6.5 — shipped 0.6.6 with the reconnect).** Importing gina outside a spawned bundle child has ALWAYS been an intended boundary (`index.mjs`'s own docblock states it; both published entries throw alike), but two defects sat on top of it. **(1) The throw was uncatchable and could HANG the process.** The logger is a load-time singleton whose default flows are `['default','mq']`, so `speaker.js` opens a TCP socket BEFORE the boot reaches its throw — and that socket kept the event loop alive (listener-CONTINGENT, measured both ways: nothing bound to the MQ port ⇒ ECONNREFUSED ⇒ exit 0, so the bug is invisible on a quiet machine and hangs with no output on one running bundles or in CI). Fixed by `client.unref()`: a logging transport must never be why a process stays alive. ⚠️ #B318: a THIRD state exists beyond connected/REFUSED — an UNREACHABLE host, where `unref()` covers the socket HANDLE but not the pending `TCPConnectWrap` REQUEST, which holds the loop by itself for the OS connect timeout (~75s on macOS); fixed with an unref'd connect deadline (2s default, `opt.mqConnectTimeout`) that `destroy(err)`s only while `client.connecting`. ⚠️ **That safety claim — "only while connecting" — is MEASURED FALSE and shipped a HIGH regression for one release (#B323):** `client.connecting` does NOT flip when the kernel completes the connect; it flips when the POLL phase runs `afterConnect` — and a timer fires in the TIMERS phase, which precedes poll. On any boot that blocks the event loop past the deadline (a bundle mount off a network filesystem — every Kubernetes-class start) the loop resumes, runs the OVERDUE deadline first, reads `connecting === true` on a connection the kernel established seconds ago, and destroys it; the bundle then logged NOWHERE for the rest of its life (the speaker dialled exactly once, ever). Measured both directions: a kernel-completed dial reads `connecting` TRUE at the timers phase and FALSE at the check phase; a black-holed one reads TRUE at both. The fix defers the verdict one phase — `setImmediate` INSIDE the deadline, so the read happens in the CHECK phase, after poll — a completed connect survives while a genuinely pending one still dies on schedule (#B318's no-hang contract intact). **Generalisable: a state flag written by an event-loop callback cannot be read from an EARLIER phase and treated as current** — `connecting`, `destroyed`, `readyState` and every `pending*` counter share the property, and a blocked loop is precisely what makes the stale read reachable; a timers-phase guard over I/O state wants a `setImmediate` (or the event itself), never a direct read. **The speaker also RECONNECTS (0.6.6):** `startMQSpeaker` returns a stable `{write}` transport FACADE (`mq/index.js` captures the return ONCE for the life of the process — without the indirection a replaced socket is unreachable); each dial builds its OWN `clientOptions` (the listener mints a fresh `sessionId` per connection and the handshake only fires while `clientOptions.sessionId` is unset — a shared object would make every reconnect skip its acknowledgement); `close` on the CURRENT socket (a `current !== client` guard keeps a superseded one from stacking a second connection) arms a capped unref'd backoff (`min(500 * 2^n, 30000)`, reset on connect). Unref'd is load-bearing BOTH ways: a short-lived CLI still exits while a long-lived bundle keeps retrying and HEALS if a listener appears later. The caller callback settles ONCE, the warn fires once per OUTAGE (not per retry), and frames are DROPPED while down — an unbounded queue behind an outage of unknown length is a memory leak, and the `default`/stdout flow carries the same lines regardless. ⚠️ The socket still CONNECTS — `unref` changes only whether it votes on process lifetime (consumer-verified against a live listener: the connected line still logs; "unref'd" is not "suppressed"). ⚠️ The workaround `GINA_LOG_STDOUT=true` does splice `mq` out of the flows but ALSO flips log format to JSON (measured) — a container logging-mode flag pressed into service as a don't-open-a-socket switch. **(2) The boundary's error now names the boundary** — the old message named an internal call (`setPath("gina.home", path): path cannot be empty`) because `getEnvVar` reads `process.gina` ONLY and is empty outside the CLI; it now routes the reader to `SuperController.createTestInstance()`, the supported way to exercise controller code without booting. ⛔ **Do NOT "fix" the boundary by extending the `getEnvVar → process.env` ladder to `gna.js`, nor by skipping the empty `setPath`** — REFUTED BY MEASUREMENT: satisfying that call merely defers the failure 8 lines to a bare-global `ReferenceError` (strictly less legible), and that `setPath` is the SOLE registration site for `gina.home` repo-wide (the SQLite connector and session store read it). Failing fast at the first detectable point is correct. Diagnostic instrument for the hang class: `process._getActiveRequests()` reports `TCPConnectWrap` while `_getActiveHandles()` shows only the unref'd Socket. Tests: `test/lib/logger-mq-speaker-resilience.test.js` (§01 deferral-ordering + reconnect-shape pins; §02 a child that blocks 3s right after the dial and must still deliver — red-first: pre-fix it lost the frame while the connection was ESTABLISHED, the defect's own signature; §03 a listener destroyed and rebound must be heard again; §04 the no-listener child still exits promptly) + `logger-mq-speaker-unref.test.js` (comment-stripped source pin — subtracting the fix left a bare existence pin GREEN against the commented-out line — + a behavioural arm with its own must-be-killed control).
 
@@ -1029,5 +1029,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 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.
+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. **The QUERY-DELIVERY half of the same #B399 arc (shipped separately): every app-callback delivery in `Controller::query()`** — the Node-style callback form and the `{onComplete}` facade, both transports, success/status AND transport-error deliveries — routes an `async` callback's rejected promise through one constructor-scope `_ownAsyncCbRejection` helper to the same throwError(500) shape the sync-delivery catches build (marker: `Controller Query Exception on async callback rejection.`). Pre-fix the rejection floated to the process handler and the request hung; the two success-delivery sync catches are byte-unchanged, plain callbacks mint zero promises, and a callback that responded before rejecting is absorbed by the #B31 released-response guard. The SYNC half of the same error-path surface is owned too (#B402): all 14 formerly-bare transport-error deliveries (host-missing, circuit refusal, the query-scope outer catch, both ca-read catches, h1 ALPN/request-error, the h2 typed terminals and both pre-flight PING failures) wrap the callback in try/catch routing to a shared `_ownSyncCbThrow` guard (marker: `Controller Query Exception on transport-error callback throw.`, flat 500) — previously an event/timer-frame throw escaped to the process handler (lib/proc.js: emerg + SIGTERM, a whole-bundle kill on BOTH engines for consumer bundles, since an app bug's error code matches none of the transport-lifecycle survive branches), and the caller-frame sites re-invoked the app callback a second time through the query-scope catch, handing it its own exception as the query error. The h2 session-error handler no longer answers the request itself (#B403): request notification on a failing session is owned solely by the stream-level typed deliveries (every live stream self-delivers), retiring the session-level throwError that raced the app callback's own response — and that, on a REUSED session, could answer with the CREATING request's context (session listeners bind once at fresh connect; the cache-hit path never re-binds them). Its by-catch #B404 is FIXED in the same pending release: every error-path `query#complete` emit is SINGLE-argument (mirroring the callback form — `callback(err)` on failure), while both `onComplete` facades' `(err, data)` dispatch dereferenced `data.status` unconditionally — so in handle/emitter mode a transport error or non-2xx outcome never reached the app's listener and the request answered 500 through the facade's sync catch with a marker misattributing it to an app callback exception. A `typeof data == 'undefined'` guard opening each facade's sync-guard try now delivers the payload as the error argument (on failure `cb(err)` with `data` undefined — a plain `{status, error}` object for a non-2xx status or a transport failure, a native `Error` for a pre-transport failure (missing host, unreadable certificate, open circuit) — and on success `cb(false, data)`); listener sync throws and async rejections are owned like every other delivery — and the host-missing emitter branch gained the `return` its callback twin always had (the only fall-through of the 20 emit sites). The documented `util.promisify(self.query)` idiom always used the callback form and was never affected by #B404 — but WAS broken by the last divergent cell, retired as #B405 (measured with controls in both directions): the h2 CALLBACK-mode dispatch delivered only 5xx to the callback and answered every other deliverable non-2xx itself via throwError, so h2 graceful degradation was impossible for 4xx and a promisified h2 query NEVER SETTLED on any non-5xx status (the await's continuation silently abandoned). Every body-announced non-2xx with a known status code now invokes `callback(data)` on both transports (h1 has done this since its #Q1 change, whose inline comment states the intent; the 3xx-with-headers replay is untouched; the retired split is preserved as comments at the site), so the promisify rejection contract now holds transport-uniformly.
+317. **Boot-frame failure ownership — a crash during bundle bootstrap aborts loudly instead of hanging (#B406, 2026-08-23).** `core/gna.js`'s boot callback (`onGettingProjectConfig`) is declared `async`, so a synchronous throw anywhere in its ~1470-line direct frame became a promise REJECTION: the caller's try/catch (written for a plain callback) could never see it, and the process-level `unhandledRejection` net only logs at error level — no `[ emerg` marker, no exit. The daemon's startup watchdog (`lib/cmd/bundle/start.js`) reads the child's STDOUT only, during startup only, and matches `/(\[|\[\s+)emerg/` — on a match it SIGKILLs the child, prints the cause, and clears the startup timer; a child that dies WITHOUT the marker gets the immediate exit-code report; a child that neither exits nor emits the marker got the 60-second timeout with no cause. Pre-fix, a boot crash in that frame was the third shape. The whole frame is now owned by one try/catch routing every failure — sync throws today, any awaited rejection added later — into `abort()`, the existing boot terminal (context-aware `console.emerg` + synchronous `fs.writeSync(2)` flush + `process.exit(1)`), with non-Error rejections (`throw null`) coerced to an Error FIRST because `abort()` reads `.stack` through branches that would themselves throw on null — and a throw inside the catch would escape back to the silent net. Measured: the levelled emerg line SURVIVES an immediate `process.exit(1)` on a POSIX pipe (short writes; the 64KB truncation class is large payloads), so the single marker line reaches the watchdog — deliberately ONE marker-bearing line, since the watchdog's emerg branch has no re-entry guard and two lines risk double-firing its bulk-start accounting. Behaviour change: a throw LATE in the frame that previously left a half-initialised process limping now refuses the boot. Extends entry 178's severity-axis rule ("lethality follows the nearest async boundary") with the boot-time tier: at boot there is no request to degrade to a logged rejection — an unowned rejection means the process neither starts nor exits, which is strictly worse than either crash-and-respawn or a 500. Tests: `test/core/gna-boot-frame-ownership.test.js` (source pins red-first vs the pre-fix blob; replica arms incl. an awaited-rejection arm proving the seam is ready for a boot-time `await`, a child-process SUBTRACT reproducing the pre-fix escape at a real process-level net, and a plain-callback CONTROL locking the caller contract). Server-side only: pickup is a bundle restart, no re-bake.
+
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.6.13",
+  "version": "0.6.14",
   "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.13/core/gna",
+  "main": "./framework/v0.6.14/core/gna",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "import": "./index.mjs",
-      "require": "./framework/v0.6.13/core/gna.js"
+      "require": "./framework/v0.6.14/core/gna.js"
     },
     "./gna": {
       "types": "./types/gna.d.ts",