gina 0.6.13 → 0.6.14

package/CHANGELOG.md

@@ -6,6 +6,36 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.6.14 - 2026-08-23
+### Added
+* Secrets exec bridge (#SECRETS3): a bundle may declare `settings.secrets.exec` — one operator-declared command (`{"command": ["sops", "decrypt", "--output-type", "json", "${project}/secrets.enc.json"], "timeout": 10000}`, argv form, no shell) whose stdout must be a single flat JSON object of string values, layered UNDERNEATH the environment exactly like the `file` tier and mutually exclusive with it (a bundle inheriting a project-wide `file` chain opts out with `"file": null` beside its `exec` block). The command runs once per bundle per config-load cycle, at boot only, and failure is always a per-bundle boot REFUSAL, never a hang: the child is bounded by `timeout` (default 10000ms) and killed with SIGKILL on expiry, so a wedged secrets endpoint becomes a fast, named boot failure. The fetched output is never echoed into any error, log or report. A non-empty environment value still beats the fetched map — decrypting at the container entrypoint remains the better pattern wherever the entrypoint can be controlled; this tier exists for environments where it cannot. `gina secrets:check` validates and RUNS the same command through the same code, so the CI gate's verdict matches the boot's. Also stricter, deliberately: `settings.secrets` now refuses unknown keys and non-object values at boot instead of silently ignoring them — a typo'd tier name used to degrade to environment-only resolution without a word.
+### Changed
+* The config-source walk behind `secrets:scan` and `secrets:check` now lives in `lib.secrets` as `getProjectRequiredKeys(projectPath, {scope, bundle})` (with `loadManifest`, `readJsonSafe` and `resolveBundleSrc` exported alongside for single-file reads). The two CLI handlers previously each carried their own near-identical copy of the walk and now delegate to the one shared implementation, so the two commands - and any future boot-time consumer - enumerate the same config sources by construction and cannot drift apart. CLI behaviour and report output are unchanged by this relocation.
+### Fixed
+* Fixed #B399 (query delivery seams) — an exception in an `async` query callback could vanish without a response: every app-callback delivery in a controller's `self.query()` (the Node-style callback form and the `{onComplete}` facade, on both HTTP/1.1 and HTTP/2 transports, success and transport-error deliveries alike) invoked the callback bare, so while a synchronous throw was caught by the success-delivery guards, an asynchronous rejection was unowned — the request hung to client/proxy timeout and the only trace floated to the process-level rejection handler. Every delivery now routes a rejected callback promise to the same `throwError` shape the sync guards build. Behaviour change: an `async` query callback whose promise rejects now answers 500 (with the #ERRREF correlation ref) where it previously hung; a callback that already responded before rejecting is absorbed by the released-response guard (logged server-side, never a double response). Synchronous behaviour at every delivery site is byte-unchanged and plain callbacks mint no promises. The adjacent synchronous gap — a throw inside a callback invoked on a transport-error delivery, which was never guarded — is owned by its own fix in this same release (see the dedicated entry).
+* Fixed #B401 (docs accuracy) — `self.query()`'s JSDoc claimed the no-callback form returns a Promise; it returns a handle exposing `.onComplete(cb)`, which is not a thenable, so `await self.query({...})` resolved immediately with the handle and silently dropped the result. The JSDoc (and the online guide) now document the real contract and the supported `await` idiom — `await require('util').promisify(self.query)(options, {})` — including the rejection shapes (a non-2xx status rejects with the plain `{status, error, message}` object, a connection failure with a native `Error`), each verified against the runtime.
+* Fixed #B402 — a synchronous throw inside a `self.query()` callback invoked on a TRANSPORT-ERROR delivery is now owned at the delivery site. All 14 formerly-bare error-path deliveries (host-missing, circuit refusal, the query-scope outer catch, both ca-read catches, HTTP/1.1 ALPN and request-error, the HTTP/2 typed terminals and both pre-flight PING failures) wrap the callback so a throw routes to a shared guard answering a flat 500 (with the #ERRREF correlation ref, marker `Controller Query Exception on transport-error callback throw.`). Previously, on the event/timer-frame sites the throw escaped to the process handler — emerg + SIGTERM, a whole-bundle kill on BOTH engines for consumer bundles — and on the caller-frame sites the query-scope catch re-invoked the app callback a second time with its own exception as the error argument. Behaviour change: a throwing callback on an error-path delivery now answers 500 instead of killing the bundle or double-invoking; the callback still receives the original transport error first, and callbacks that do not throw are untouched.
+* Fixed #B403 — an HTTP/2 transport failure could be answered twice: the app callback received the typed error from the stream-level delivery while the SESSION error handler independently answered the same request through `throwError`, racing graceful degraded-mode handling (the framework 500 could reach the wire before the app response) — and on a reused session the handler could answer with the CREATING request context, since session listeners bind once at connect. The session-level answer is retired: session cleanup and logging stay, and request notification is owned solely by the stream-level deliveries (request error/close/end typed terminals), which fire for every live stream when a session fails. With a Node-style callback, a connection failure now notifies exactly once; HTTP/1.1, which has no session layer, already behaved this way.
+* Handle-mode query error deliveries now reach the app's `onComplete` listener (#B404): every error-path `query#complete` emit is single-argument — mirroring the callback form's `callback(err)` contract — while both facades' `(err, data)` dispatch dereferenced `data.status` unconditionally, so a transport error or non-2xx outcome crashed the facade and answered 500 with a marker misattributing the failure to the app callback; the listener never fired. A guard in both facades (HTTP/1.1 and HTTP/2) now delivers the single-argument payload as the error: 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)`. The host-missing emitter branch also gained the `return` its callback twin always had. Action required if a handle-mode query could fail: the listener is NOW INVOKED with the error (previously the framework answered 500 before it could run) — the app owns the outcome, like the callback form.
+* A crash during bundle bootstrap now aborts the process loudly instead of leaving it hung and silent. The boot callback in core/gna.js is declared async, so a synchronous throw anywhere in its frame became a promise rejection: the process-level net only logged it at error level - no `[ emerg` marker for the daemon startup watchdog, no exit - so `gina bundle:start` sat on its 60-second startup timer and reported a timeout with no cause attached. The whole frame is now owned by a try/catch that routes every failure - including a non-Error rejection like `throw null`, coerced first because the terminal reads `.stack` - into abort(), the existing boot terminal: an emerg-level line the daemon watchdog matches on (it then kills the child and prints the cause immediately), a synchronous stderr flush that survives the exit, and exit code 1. Behaviour change worth knowing: a throw late in the boot frame that previously left a half-initialised process limping along now refuses the boot cleanly - if a bundle that used to "start" begins aborting after this release, the printed cause was always there, previously invisible. Server-side only: pickup is a bundle restart, no re-bake.
+* Fixed #B405 — an HTTP/2 query in callback mode never delivered a non-5xx error status to the app callback: the dispatch split 5xx → `callback(data)` / every other deliverable non-2xx → the framework's own error answer, so graceful degradation was impossible for e.g. a 404 from an HTTP/2 upstream, and — measured — the documented `util.promisify(self.query)` idiom NEVER SETTLED on any non-5xx status (the `await` hung and its continuation was silently abandoned), while HTTP/1.1 has delivered every non-2xx to the callback since its own earlier change. The split is retired: every body-announced non-2xx with a known status code now invokes `callback(data)` on both transports, matching the documented contract. Behaviour change: an HTTP/2 callback-mode query that previously auto-answered the original request with the upstream's non-5xx status now invokes your callback instead — decide there whether to degrade or surface; the 3xx-with-headers redirect replay is unchanged.
+* GET and HEAD query parameters no longer lose backslash-escaped characters (#B407, consumer-reported). The query pipeline serialized `request.query` and then stripped every backslash from the whole document to support nested-JSON value unwrapping - so a newline (`%0A`) in a value degraded to the letter `n`, a tab to `t`, a backslash vanished, and a double quote or a JSON-array value produced invalid JSON that silently dropped EVERY query parameter on the request. Nested-JSON string values (`?filter={"a":1}`) are now unwrapped by parsing them individually - the same unwrap intent, validated, and correct even when the nested content itself carries escapes, which the old unwrap also corrupted - and the query then serializes cleanly. Whole-value `true`/`false`/`on`/`null` coercion and plain values are unchanged; JSON-array parameters and unparsable `{`-leading values now arrive intact where they previously killed the whole query.
+* Aligned `gina secrets:check` with the runtime's `settings.secrets.file` declaration guards by moving the validation to one shared implementation, exposed as `lib.secrets.validateFilePaths` (#B408): the checker's hand-kept mirror had missed the whitespace-only-entry refusal and the empty-path-segment (`//`) refusal, so it reported GREEN configs the bundle refuses to boot — a whitespace-only entry, or a path whose `${…}` token collapsed to a double separator, now fail the check exactly as they fail the boot. The check also validates the declaration before reading any declared layer, as the boot does, so an invalid chain reports with no layers listed.
+* `gina secrets:check` now exits non-zero when a bundle's secrets declaration itself is invalid or unreachable (#B409) — an unreadable declared file, a malformed entry, a failing exec fetch — not only when a required key is unset. Previously such errors were printed but the exit code stayed 0 whenever the environment happened to carry the keys, so the CI gate green-lit configs the runtime refuses to boot.
+
+## 0.6.13 - 2026-08-22
+### Added
+* New: a general-purpose key-value primitive (#KV1) — declare namespaces under `settings.json > kv.namespaces` and reach them as `gina.kv('<namespace>')` (or `gina.kv()` for `kv.default`). The handle is promise-native with 13 operations: `get` / `set` / `del` / `has` / `ttl` / `expire` / `setnx` (set-if-absent) / `consume` (atomic read-and-delete — one-shot tokens: the second reader gets null) / `incr` / `decr` (integer counters, TTL on create only) / `delIfEquals` (compare-and-delete, the safe lock-release primitive) / `clear` / `getOrSet` (fetch-or-compute with per-process single-flight). Values are JSON-serialized — null and undefined are refused on every write, a stored null being indistinguishable from a miss; TTLs are milliseconds and must be positive (`ttl: 0` refuses rather than meaning no-expiry). Namespaces are strict-declared: an unknown name throws at the call site instead of silently minting an empty store, and the whole feature is dormant with no `kv` block. Each namespace owns its failure policy (`failMode` `closed`, the default, rejects on backend errors; `open` degrades every operation to its miss-shaped result with a warning). Ships with three backends: in-memory (zero config), redis and SQLite, the latter two selected by pointing a namespace's `store` at a `connectors.json` entry — atomic set-if-absent, consume, compare-and-delete and TTL-on-create-only counters are all server-side, and `GETDEL` is used when the server supports it with a Lua fallback below redis 6.2. Naming a connector that has no kv-store implementation still refuses the boot rather than degrading silently to memory. Deliberately NOT a redis client: no data structures, batch operations, key scanning, binary values, or first-class locks.
+* The general-purpose KV primitive (#KV1) gains a redis backend for namespaces shared across hosts: point a namespace's `store` at a `connectors.json` redis entry (`{ "kv": { "namespaces": { "tokens": { "store": "kvRedis" } } } }`) and the namespace is served by redis instead of process memory — so several bundles or replicas can share one namespace, which the in-memory backend cannot do. Every guarantee stays server-side: set-if-absent is a single `SET .. PX .. NX`, consume is `GETDEL` where the server supports it (redis 6.2 and above) and a Lua script below that rather than a `GET` plus `DEL` pair, and compare-and-delete and TTL-on-create-only counters are Lua as well. Keys are prefixed per namespace, so two namespaces may share one connectors entry; cluster keys are deliberately left un-tagged so a namespace spreads across slots, and `clear()` scans each master node. Connection policy — `commandTimeout`, `maxRetriesPerRequest`, `enableOfflineQueue` — is read from the connectors entry and otherwise left at the driver's defaults, so a cache-like namespace can be tuned to fail fast while a token namespace keeps the offline queue. Requires `ioredis` in your project. Naming a connector that has no kv-store implementation still refuses the boot.
+* The general-purpose KV primitive (#KV1) gains a SQLite backend — the zero-dependency durable option between in-memory and redis: point a namespace's `store` at a `connectors.json` sqlite entry (`{ "kvDb": { "connector": "sqlite", "file": "/data/kv.db" } }`) and the namespace survives a bundle restart and is visible to any process opening the same file, with no server to run. Namespaces sharing one file are isolated by a composite key rather than a prefix, so `clear()` touches only its own namespace. Every read-modify-write operation — set-if-absent, consume, compare-and-delete, counters — runs inside an IMMEDIATE transaction, so it stays atomic when a SECOND PROCESS shares the file, which is the case the backend exists for. Expiry is filtered on every read and swept periodically, so an expired entry is never observable. Uses `node:sqlite` (built in on Node, a `bun:sqlite` adapter under Bun), so nothing to install. All three backends are now verified against ONE shared contract spec rather than three separate suites.
+* Adding an opt-in per-authority circuit breaker to Controller::query() (#MS5, settings.json > server.query.circuitBreaker): after N consecutive transport-class failures to one authority (default 5, each already representing a call whose own retries were exhausted), the circuit opens and every further call fails fast with a machine-readable CIRCUIT_OPEN error (status 503, retryable false, plus the authority and retryAfterMs) instead of hammering a dead upstream; after the cooldown (default 30s) exactly one critical request is admitted as the half-open probe, closing the circuit on success and re-arming it on failure. The gate sits above the HTTP/1.x / HTTP/2 protocol dispatch, so an open circuit rejects before any connection, retry or pre-flight machinery runs and the existing retry invariants are untouched - retries can never hammer an open circuit by construction. Three decisions are load-bearing and documented in-source. Only transport-class errors count: every GinaHttp2Error plus the socket-level ECONN family, checked on err.code and err.cause.code - an application response, whatever its status, flows through the success terminus as data, and a caller bug is neutral, so neither can trip the breaker on a healthy upstream. Only a CRITICAL request may serve as the half-open probe, because a non-critical failure is swallowed by the H3 contract - its callback never fires - so a non-critical probe could never report back and would wedge the half-open state forever. And breaker state lives on the engine instance, the same home as the HTTP/2 session registry, because dev mode re-requires the controller per request: anywhere else the state would reset on every hot-reload, while instance state survives reloads and dies on restart, which is exactly the lifetime circuit state wants. Dormant unless enabled is strictly true; a structurally invalid enabled block refuses the boot rather than warn-and-disable, since silently running without the protection the operator asked for is the fail-open shape the other boot bands refuse. Policy is resolved once at engine start and stamped on the instance, so config changes need a bundle restart. Server-side only, so pickup is a bundle restart with no re-bake
+* Documenting two boundaries the framework deliberately does not cross: API versioning and database migrations. Both were absences a reader could only discover by searching for something that was not there, and an absence with no statement behind it reads as an oversight rather than a decision. Neither is a new capability - the point is that neither will be one. Versioning gets a routing-guide section stating plainly that there is no version route field and no version-aware dispatch, because when to cut a version and how long to support the old one are product decisions a framework would be wrong to make for you; it then shows the three shapes the existing primitives already cover, a URL prefix with a per-version namespace so each version loads its own controller file, separate bundles when versions need their own dependencies or release cadence, and header negotiation - with the note that the question deciding between them is not URL versus header but what changes together. Migrations get a models-guide section naming the per-database tools to use instead, plus the two things that actually go wrong in practice: run them as a discrete step before the new version serves, never at bundle boot, where they race themselves the moment there is more than one replica and turn a schema error into a crash-loop instead of a failed deploy step; and keep changes additive during a rolling deploy, because SQL files are validated at call time rather than at boot, so a renamed column and a query still selecting it fail on the first request rather than at startup. The connector CLI page gains an explicit warning that connector:migrate is not a database migration - it lints the connection configuration and with --fix rewrites that JSON, issuing no SQL and holding no up or down concept - since the name is the whole source of the confusion. Verified against the source before writing rather than from memory: no version field exists anywhere in the router or the routing library, and the migrate command help confirms it scans connectors.json only. Docs only, no behaviour change; pickup is a bundle restart with no re-bake
+* Identified-caller rate limiting (#MS6): opt-in quota enforcement at the router, keyed on the authenticated principal — the session user (via the operator-named server.rateLimit.keyField) or a machine caller — with fixed-window counters stored in a kv namespace you declare, so a redis- or sqlite-backed namespace shares one quota across replicas while an in-memory one counts per process (the boot resolver warns about the difference, and about a redis connectors entry missing the fail-fast tuning that would otherwise queue requests through an outage). The gate runs after route authorization and before DTO validation (401 -> 429 -> 422), and it throttles identified callers only: anonymous flood control stays with your edge proxy and the HTTP/2 rapid-reset guard, and a request with no resolvable principal is skipped, never bucketed by IP. Denials answer 429 with Retry-After plus the RateLimit / RateLimit-Policy structured fields from draft-ietf-httpapi-ratelimit-headers-11; allowed limited requests carry them too. Per-route overrides ride routing.json's top-level rateLimit key: false exempts a route, an object with limit / window replaces the default policy for that route in its own bucket (partial objects inherit the missing key). Configure under settings.json server.rateLimit (enabled, namespace, keyField, limit, window; env.json keys win at the fold, changes need a bundle restart). Dormant unless enabled is strictly true; structurally invalid values on an enabled block refuse the boot; store outages follow the namespace's own failMode — open admits requests with a warning, closed answers 503 with Retry-After. Server-side only: pickup is a bundle restart (the dist rebuild in this release carries only the route-flag propagation, dead code in the browser).
+### Fixed
+* Retiring the published claim that gina ships a companion reverse-proxy service (#MS8). The service help text, its JSDoc and the docs-site CLI pages all named `proxy` as one of two framework-internal services you could start, and `gina service:list` reported it with status ok - for a bundle that cannot serve a single proxied request. Measured rather than assumed: the bundle does carry forwarding logic (it reads a Target-URL request header, handles the OPTIONS preflight and pipes an upstream response back), but the HTTP client it calls is never imported and is not a framework global, so any request carrying that header throws a ReferenceError. The internal note claiming the bundle had no proxy logic at all was therefore wrong in its reason while right in its conclusion, and is corrected at source so a later session does not re-derive it. Nothing is being taken away from anyone: the services directory is CLI-generated, gitignored and npmignored, and the published tarball was checked to contain zero entries for it against a firing control, so no release ever carried the bundle the text advertised. The same wording was inaccurate about the other service too - it said these bundles ship alongside gina, which is true of neither - so the sentence now states plainly that services live in a maintainer-side tree outside the published package and that a released install has nothing to list until that tree exists locally. In its place each surface carries the stance: gina ships no edge or reverse proxy by design, run nginx, Traefik or an ingress controller in front of your bundles. That is not a new position, it is the one the rest of the documentation already assumed - the authentication guidance sends OAuth deployments behind a reverse proxy, the rate-limiting roadmap row names your reverse proxy or ingress as the interim answer, and the Kubernetes guide is ingress-fronted throughout - so this aligns four surfaces with one that disagreed. No roadmap row ever promised a built-in proxy, so nothing planned is being cancelled. The dormant bundle is deliberately left on disk: nothing reads it, and deleting generated local state is the operator call. Docs and help text only, no runtime behaviour change; pickup is a bundle restart with no re-bake
+* Making the entity dispatch diagnostics readable (#B395). The five DISPATCH markers in the entity callback machinery were raw console.log calls, and in gina that is the logger raw-stdout branch: it bypasses the container dispatch and the level gate alike, so the lines never reached a bundle log file or gina tail, while a daemon-spawned bundle also has its child stdout filtered, so they never reached container logs either. They were diagnostics that could only be seen by running a bundle in the foreground and reading the terminal - which is how a consumer came to report seeing the neighbouring levelled output while these were absent. They now go through console.debug, so they are off by default and appear when the log hierarchy is raised to debug, which was the original intent. The leading newline each line carried is dropped, because it was a formatting hack for the raw stdout path and would otherwise be embedded in the message field under JSON log format, and the prefix now matches the convention already used elsewhere in the same file. The alternative considered was deleting them as spent scaffolding, and it was rejected on measurement rather than on taste: the case for deleting rested on the sites being hot enough that making them visible would flood a debug log, and the full test suite emits fifteen of these lines in total, with two of the four markers never firing at all. Reasoning from the shape of the enclosing handlers is not the same as measuring how often they run. A comment at the first site now records why the method choice is load-bearing, so a later edit does not quietly restore console.log and re-break the visibility. Server-side only, so pickup is a bundle restart with no re-bake
+* Fixed #B399 — an exception in a controller's reserved-action hooks (`onReady`, the `setup` controller) could vanish without a response or a visible log line: both dispatch sites invoked the hooks outside the guarded band, so a synchronous throw escaped to the process level (on the built-in engine: uncaughtException killing the whole bundle process; Express answered its own 500 — engine-asymmetric) and an asynchronous rejection was unowned (the request could hang to client/proxy timeout while work after the throw silently never happened). Both hook loops now run inside the dispatch try and every hook's returned promise is owned with the same `.catch` → 500 guard the main action carries, naming the failing hook in the error detail; the synthesized `setup` wrapper now returns the app call's own result so an async `setup.js` rejection reaches the guard. Behaviour change: a rejecting or throwing hook now answers 500 (with the #ERRREF correlation ref) where it previously crashed the process, hung, or let the action's own response mask the failure. The hooks are still dispatched without awaiting, in the same synchronous frame as the action — a hook rejection does not prevent the action from running, so its side effects may already have executed when the 500 reaches the client; treat retries of non-idempotent actions accordingly.
+
 ## 0.6.12 - 2026-08-20
 ### Fixed
 * Refreshed the external references carried by the framework READMEs. The country-codes locale README pointed at a Simple Data Format specification URL that no longer exists (404); it now names the Tabular Data Package specification that superseded it, matching the upstream dataset the file mirrors. Every remaining plain-HTTP reference in the locales and frontend-asset READMEs is now HTTPS, with the geonames.org link resolved to the www host because the bare domain redirects back down to HTTP. Documentation only; no runtime or API change.

package/README.md

@@ -38,7 +38,7 @@ MVC framework for Node.js and Bun with built-in HTTP/2, multi-bundle architectur
 | Audit trail | Opt-in append-only JSONL audit log (`self.audit()`), authorization denials auto-recorded, always-on request ids; opt-in HMAC hash chain verified offline by `gina audit:verify` |
 | CSRF protection | Signed double-submit token middleware + Origin/Referer pre-filter + hardened session cookie |
 | Security headers | CSP with per-response nonces, HSTS, COOP / COEP / CORP, Referrer-Policy and the X-* family — per-header plugins or one `SecurityHeaders` wrapper |
-| Secrets | `${secret:KEY}` placeholders in bundle config — fail-closed, env-backed; `secrets:scan` / `secrets:check` CLI |
+| Secrets | `${secret:KEY}` placeholders in bundle config — fail-closed, env-backed, with opt-in file and exec-bridge tiers beneath the environment; `secrets:scan` / `secrets:check` CLI |
 | Internationalisation | Per-bundle JSON catalogs, `t()` helper, swig + nunjucks `t` filter, CLDR plurals, ICU MessageFormat opt-in via `t.icu()` |
 | Observability | Built-in `/_gina/metrics` Prometheus endpoint (opt-in, IP-allowlisted) — process metrics + HTTP counter / duration histogram with cardinality-safe route labels; structured JSON logs with request ids (`GINA_LOG_FORMAT=json`) |
 | Dev Inspector | Embedded dev SPA at `/_gina/inspector` — request data, live logs, SQL with index-coverage badges, flow timings, app events, AI token stream |
@@ -62,33 +62,39 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.6.13
+## What's in 0.6.14
 
-> **Restart your bundles AND rebuild them.** The browser bundle changed in this
-> release. The client-side delta is inert — it is the per-route flag propagation
-> the new rate limiter needs on the server, which is dead code in the browser —
-> but the baked copy each bundle serves is no longer byte-identical to the
-> shipped one, so run `gina bundle:build` for each bundle as well as
-> `gina bundle:restart`. Every behaviour change below is server-side.
+> **Restart your bundles — no rebuild needed.** Every change in this release is
+> server-side. The browser bundle's executable content is byte-identical to
+> `0.6.13` (the only `dist/` delta is a documentation comment, which
+> minification strips), so `gina bundle:restart` is enough and you do not need
+> to re-run `gina bundle:build`.
 
-> **No settings reset.** `0.6.13` is a patch — the `shortVersion` stays `0.6`, so
+> **No settings reset.** `0.6.14` is a patch — the `shortVersion` stays `0.6`, so
 > your `~/.gina/0.6/settings.json` is untouched. (`0.6.0` was the reset.)
 
-**Three new opt-in capabilities and three fixes.** The headline is a
-general-purpose key-value primitive with three backends, which the new
-identified-caller rate limiter is built on top of. **One behaviour change to
-check before you upgrade** — an exception thrown by a controller's `onReady` or
-`setup` hook now answers a 500 where it previously crashed the bundle process or
-left the request hanging. Details are in the
+**One new opt-in capability, and a correctness pass over how `self.query()` hands
+results back to your code.** The headline is a secrets bridge that reads from a
+network-backed store without a vendor SDK and without risking a hung boot.
+Alongside it, six fixes close the seams where a query's outcome could be lost:
+a rejected `async` callback that hung the request, a throw that killed the whole
+bundle process, an HTTP/2 failure answered twice, a handle-mode listener that
+never fired, and non-5xx statuses that never reached the callback at all.
+**Several behaviour changes are worth checking before you upgrade** — each is
+called out in its bullet below, with the details in the
 [migration guide](https://gina.io/docs/migration).
 
-- **New — a general-purpose key-value primitive with in-memory, redis and SQLite backends (#KV1).** Declare namespaces under `settings.json > kv.namespaces` and reach them as `gina.kv('<namespace>')`. The handle is promise-native with 13 operations, including the ones that are hard to get right by hand: `setnx` (set-if-absent), `consume` (atomic read-and-delete, so a one-shot token's second reader gets `null`), `delIfEquals` (compare-and-delete — the safe lock-release primitive), `incr`/`decr` with TTL-on-create-only, and `getOrSet` with per-process single-flight. **Redis** serves namespaces shared across hosts and replicas, keeping every guarantee server-side (`SET .. PX .. NX`, `GETDEL` with a Lua fallback below redis 6.2, Lua for compare-and-delete and counters). **SQLite** is the zero-dependency durable option — it survives a restart and is visible to any process opening the same file, with every read-modify-write inside an `IMMEDIATE` transaction so it stays atomic across processes; it uses `node:sqlite` (a `bun:sqlite` adapter under Bun), so there is nothing to install. Namespaces are strict-declared — an unknown name throws at the call site rather than silently minting an empty store — and each owns its `failMode`. All three backends are verified against one shared contract spec. Dormant with no `kv` block. Deliberately **not** a redis client: no data structures, batch operations, key scanning, binary values or first-class locks.
-- **New — identified-caller rate limiting (#MS6).** Opt-in quota enforcement at the router, keyed on the **authenticated principal** — the session user (via the operator-named `server.rateLimit.keyField`) or a machine caller — with fixed-window counters in a kv namespace you declare. That makes the scope your choice: a redis- or SQLite-backed namespace shares one quota across replicas, while an in-memory one counts per process (the boot resolver says so, and also warns about a redis connectors entry missing the fail-fast tuning that would otherwise queue every gated request through an outage). The gate runs **after** route authorization and **before** DTO validation, so the refusal order is `401 → 429 → 422` and a throttled caller never receives a field map. It throttles identified callers **only** — a request with no resolvable principal is skipped, never bucketed by IP, because behind a reverse proxy that would be one bucket for the whole internet; anonymous flood control stays with your edge proxy and the HTTP/2 rapid-reset guard. Denials answer 429 with `Retry-After` plus the `RateLimit` / `RateLimit-Policy` structured fields from `draft-ietf-httpapi-ratelimit-headers-11`, which allowed limited requests carry too. Per-route overrides ride `routing.json`'s top-level `rateLimit` key (`false` exempts a route; an object replaces the policy for it). Store outages follow the namespace's own `failMode`.
-- **New — an opt-in per-authority circuit breaker for `Controller::query()` (#MS5).** After N consecutive **transport-class** failures to one authority (default 5, each already a call whose own retries were exhausted), the circuit opens and further calls fail fast with a machine-readable `CIRCUIT_OPEN` error (status 503, `retryable: false`, plus the authority and `retryAfterMs`) instead of hammering a dead upstream. After the cooldown (default 30s) exactly one **critical** request is admitted as the half-open probe, closing the circuit on success and re-arming it on failure. The gate sits above the HTTP/1.x / HTTP/2 dispatch, so an open circuit rejects before any connection, retry or pre-flight machinery runs — retries can never hammer an open circuit by construction. Only transport-class errors count: an application response, whatever its status, flows through the success terminus as data, so a 500 from a healthy upstream cannot trip the breaker. Configure under `settings.json > server.query.circuitBreaker`.
-- **Fixed — an exception in a controller's `onReady` or `setup` hook can no longer vanish (#B399).** Both router dispatch sites invoked the reserved-action hooks outside the guarded band, so a **synchronous** throw escaped to the process level — on the built-in engine that was an uncaught exception killing the whole bundle process, while Express answered its own 500, an engine asymmetry — and an **asynchronous** rejection was unowned, leaving the request to hang to client or proxy timeout while work after the throw silently never happened. Both hook loops now run inside the dispatch `try`, and every hook's returned promise is owned by the same `.catch` → 500 guard the main action already carried, naming the failing hook in the error detail; the synthesized `setup` wrapper now returns the app call's own result, so an async `setup.js` rejection actually reaches the guard. **ACTION REQUIRED if a hook of yours can throw:** it now answers 500 (with the `#ERRREF` correlation ref) where it previously crashed the process, hung, or let the action's own response mask the failure. Note the hooks are still dispatched without awaiting, in the same synchronous frame as the action — a hook rejection does not prevent the action from running, so its side effects may already have executed when the 500 reaches the client; treat retries of non-idempotent actions accordingly.
-- **Fixed — the entity dispatch diagnostics are readable again (#B395).** The five `DISPATCH` markers in the entity callback machinery were raw `console.log` calls, which in gina is the logger's raw-stdout branch: it bypasses both the container dispatch and the level gate, so the lines never reached a bundle log file or `gina tail`, and a daemon-spawned bundle has its child stdout filtered as well, so they never reached container logs either. They were diagnostics visible only by running a bundle in the foreground. They now go through `console.debug` — off by default, appearing when the log hierarchy is raised to `debug`, which was the original intent.
-- **Fixed — the published claim that gina ships a companion reverse-proxy service is retired (#MS8).** The service help text, its JSDoc and the docs-site CLI pages all named `proxy` as a framework-internal service you could start, and `gina service:list` reported it with status `ok` — for a bundle that cannot serve a single proxied request. Nothing is being taken away: the services directory is CLI-generated, gitignored and npmignored, and the published tarball carries zero entries for it, so no release ever shipped the bundle the text advertised. Each surface now carries the stance instead: **gina ships no edge or reverse proxy by design** — run nginx, Traefik or an ingress controller in front of your bundles. That is the position the rest of the documentation already assumed.
-- **Documentation — two boundaries the framework deliberately does not cross.** API versioning and database migrations were both absences you could only discover by searching for something that was not there, and an absence with no statement behind it reads as an oversight rather than a decision. The routing guide now states plainly that there is no version route field and no version-aware dispatch — when to cut a version and how long to support the old one are product decisions — and shows the three shapes the existing primitives already cover. The models guide names the per-database migration tools to use instead, plus the two things that actually go wrong: run migrations as a discrete step **before** the new version serves (never at bundle boot, where they race themselves the moment there is more than one replica), and keep changes additive during a rolling deploy. The connector CLI page gains an explicit warning that `connector:migrate` is **not** a database migration — it lints connection configuration and issues no SQL.
+- **New — network-backed secrets without a vendor SDK or a hung boot (#SECRETS3).** A bundle may declare one operator-supplied fetch command under `settings.secrets.exec` — argv form, no shell (`{"command": ["sops", "decrypt", "--output-type", "json", "${project}/secrets.enc.json"], "timeout": 10000}`) — whose stdout must be a single flat JSON object of string values. It runs once per bundle per config-load cycle, at boot only, and is layered *underneath* the environment exactly like the existing `file` tier: a non-empty environment value still wins. The two declared tiers are mutually exclusive, and a bundle inheriting a project-wide `file` chain opts out with `"file": null` beside its own `exec` block. **A failing fetch is always a fast, named per-bundle boot refusal, never a hang** — the child is bounded by `timeout` (default 10000ms) and killed with `SIGKILL` on expiry, so a wedged secrets endpoint costs you a failed boot rather than a process that never comes up. The fetched output is never echoed into any error, log or report, and `gina secrets:check` validates *and runs* the same command through the same code, so the CI gate's verdict matches the boot's by construction. Recipes for `vault`, `kubectl` and `sops` are in the guide. Decrypting at the container entrypoint remains the better pattern wherever you control the entrypoint; this tier exists for the environments where you do not. **Also stricter, deliberately:** `settings.secrets` now refuses unknown keys and non-object values at boot instead of silently ignoring them — a typo'd tier name used to degrade to environment-only resolution without a word.
+- **Fixed — an exception in an `async` query callback can no longer vanish (#B399).** Every app-callback delivery in a controller's `self.query()` — the Node-style callback form and the `{onComplete}` facade, on both HTTP/1.1 and HTTP/2 — invoked your callback bare. A synchronous throw was caught by the success-delivery guards, but an asynchronous *rejection* was unowned: the request hung to client or proxy timeout and the only trace floated up to the process-level rejection handler. Every delivery now routes a rejected callback promise to the same `throwError` shape the synchronous guards build. **Behaviour change:** an `async` query callback whose promise rejects now answers 500 (with the `#ERRREF` correlation ref) where it previously hung. A callback that already responded before rejecting is absorbed by the released-response guard — logged server-side, never a double response. Synchronous behaviour at every delivery site is byte-unchanged, and plain callbacks mint no promises.
+- **Fixed — a throw inside a query callback on a transport-error delivery no longer kills the bundle (#B402).** All 14 formerly-bare error-path deliveries — host-missing, circuit refusal, the query-scope outer catch, both certificate-read catches, HTTP/1.1 ALPN and request-error, the HTTP/2 typed terminals and both pre-flight PING failures — now wrap the callback. Previously, on the event- and timer-frame sites a throw escaped to the process handler as an emergency-level exit, **killing the whole bundle on both engines**; on the caller-frame sites the query-scope catch re-invoked your callback a second time, passing its own exception as the error argument. **Behaviour change:** a throwing callback on an error-path delivery now answers a flat 500 instead of killing the bundle or double-invoking. Your callback still receives the original transport error first, and callbacks that do not throw are untouched.
+- **Fixed — an HTTP/2 transport failure is now answered exactly once (#B403).** The app callback received the typed error from the stream-level delivery while the *session* error handler independently answered the same request through `throwError` — racing graceful degraded-mode handling, so the framework's 500 could reach the wire before your own response. On a reused session it was worse: session listeners bind once at connect, so the handler could answer using the *creating* request's context. The session-level answer is retired; session cleanup and logging stay, and request notification is owned solely by the stream-level deliveries, which fire for every live stream when a session fails. HTTP/1.1, which has no session layer, already behaved this way.
+- **Fixed — handle-mode query errors now reach your `onComplete` listener (#B404).** Every error-path `query#complete` emit is single-argument, mirroring the callback form's `callback(err)` contract, but both facades' `(err, data)` dispatch dereferenced `data.status` unconditionally — so a transport error or a non-2xx outcome crashed the facade and answered 500 with a marker that misattributed the failure to your callback, which never ran. Both facades now deliver the single-argument payload as the error: 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 such as a missing host, an unreadable certificate or an open circuit), and on success `cb(false, data)`. **Action required if a handle-mode query of yours can fail:** your listener is now *invoked* with the error, where the framework previously answered 500 before it could run — the outcome is yours to own, exactly as in the callback form.
+- **Fixed — HTTP/2 queries in callback mode now deliver every non-2xx status (#B405).** The dispatch split 5xx to your callback and every *other* deliverable non-2xx to the framework's own error answer, so graceful degradation was impossible for something as ordinary as a 404 from an HTTP/2 upstream — and, measured, the documented `util.promisify(self.query)` idiom **never settled** on any non-5xx status: the `await` hung and its continuation was silently abandoned. HTTP/1.1 has delivered every non-2xx to the callback since its own earlier change. The split is retired: every body-announced non-2xx with a known status code now invokes your callback on both transports. **Behaviour change:** an HTTP/2 callback-mode query that previously auto-answered the original request with the upstream's non-5xx status now invokes your callback instead — decide there whether to degrade or surface. The 3xx-with-headers redirect replay is unchanged.
+- **Fixed — `self.query()`'s documented return contract (#B401).** The JSDoc claimed the no-callback form returns a Promise. It returns a handle exposing `.onComplete(cb)`, which is not a thenable — so `await self.query({...})` resolved immediately with the handle and silently dropped the result. The JSDoc and the online guide now document the real contract and the supported `await` idiom, `await require('util').promisify(self.query)(options, {})`, including its rejection shapes: a non-2xx status rejects with the plain `{status, error, message}` object, a connection failure with a native `Error`. Both were verified against the runtime.
+- **Fixed — a crash during bundle bootstrap now aborts loudly instead of hanging silently (#B406).** The boot callback in `core/gna.js` is declared `async`, so a synchronous throw anywhere in its frame became a promise rejection: the process-level net logged it at error level and stopped there — no emergency marker for the daemon's startup watchdog, no exit — so `gina bundle:start` sat on its 60-second startup timer and reported a timeout with no cause attached. The whole frame is now owned by a `try`/`catch` routing every failure (including a non-`Error` rejection like `throw null`) into the existing boot terminal: an emergency-level line the watchdog matches on, a synchronous stderr flush that survives the exit, and exit code 1. **Behaviour change worth knowing:** a throw late in the boot frame that previously left a half-initialised process limping along now refuses the boot cleanly. If a bundle that used to "start" begins aborting after this release, the printed cause was always there — it was simply invisible.
+- **Fixed — GET and HEAD query parameters no longer lose backslash-escaped characters (#B407, consumer-reported).** The query pipeline serialized `request.query` and then stripped every backslash from the whole document in order to support nested-JSON value unwrapping. A newline (`%0A`) in a value degraded to the letter `n`, a tab to `t`, a backslash vanished outright, and a double quote or a JSON-array value produced invalid JSON that silently dropped **every** query parameter on the request. Nested-JSON string values (`?filter={"a":1}`) are now unwrapped by parsing them individually — the same intent, validated, and correct even when the nested content itself carries escapes, which the old unwrap also corrupted — and the query then serializes cleanly. Whole-value `true`/`false`/`on`/`null` coercion and plain values are unchanged; JSON-array parameters and unparsable `{`-leading values now arrive intact where they previously killed the whole query.
+- **Fixed — `gina secrets:check` now agrees with the boot (#B408, #B409).** The checker kept its own hand-written mirror of the runtime's `settings.secrets.file` declaration guards, and it had drifted — twice, both times permissively: a whitespace-only entry and a path whose `${…}` token collapsed to a double separator both reported **green** while the bundle refused to boot on them. The validation now lives in one shared implementation (`lib.secrets.validateFilePaths`) that boot and check both consume, and the check validates the declaration *before* reading any declared layer, exactly as the boot does — so an invalid chain now reports with no layers listed. **Behaviour change for CI:** the command now exits non-zero when a bundle's declaration is itself invalid or unreachable — an unreadable declared file, a malformed entry, a failing exec fetch — not only when a required key is unset. Previously such errors were printed while the exit code stayed 0 whenever the environment happened to carry the keys, so the gate green-lit configurations the runtime refuses to boot.
+- **Changed — one shared config-source walk behind `secrets:scan` and `secrets:check`.** The walk now lives in `lib.secrets` as `getProjectRequiredKeys(projectPath, {scope, bundle})`, with `loadManifest`, `readJsonSafe` and `resolveBundleSrc` exported alongside it for single-file reads. The two CLI handlers each carried a near-identical private copy and now delegate to the one implementation, so they enumerate the same config sources by construction and cannot drift apart. CLI behaviour and report output are unchanged by the relocation.
 
 ## Documentation
 

package/ROADMAP.md

@@ -65,6 +65,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q4 2026** | `0.6.11` ✅ | **Fixed**: `Collection.replace()` no longer silently discards the write when the stored entry carries an internal `_uuid` and the caller's `set` does not — the comparison key is now resolved from both sides (falling back to `id` when both carry one) and the call throws instead of returning quietly when the two sides share no usable key; an explicitly supplied key is honoured exactly as before (issue #64). Concurrent `util.promisify(entity.method)` calls on the same method no longer cross-deliver results or leave a caller hanging — the promisify fast-path now uses the same FIFO queue and single persistent dispatcher as the entity-context path, so every caller settles and in-order completion gives each its own result; out-of-order completion still pairs by arrival order, for which the per-call-identity path is a Promise-returning method. FormValidator: fast typing into a Safari `autocomplete="off"` field no longer scrambles the text (the caret is committed synchronously on every rebuild and the deferred restore re-asserts the latest committed position; issue #63), with three position-0 edge cases in the same interception corrected to native behaviour (Backspace, Delete with a selection, ArrowLeft); a refused submit's answer on an async-`query` form stays visible and focused instead of being re-hidden by a late completion (answer-placed focus is told from user-placed focus until the first genuine interaction); and a stale not-ready submit marker can no longer refuse every click until reload on a form whose async `query` field is not declared last (the reveal pass now carries its own completion identity and always completes). Inspector (development mode): the View tab's page-weight badge and the Flow tab's late timeline bars no longer go missing until a refresh — both data channels are refreshed at the end of the late-bind patch, keyed per tab. Pickup: restart **and** rebuild your bundles (the browser bundle changed). |
 | **Q4 2026** | `0.6.12` ✅ | **Fixed**: an undefined-valued filter key no longer makes a `Collection` query match every record — every `Collection` method that accepts a filter object round-tripped it through `JSON.stringify`, which silently drops keys whose value is `undefined`, so a filter built from a possibly-absent field degraded to the match-everything `{}` filter: `findOne()` returned the collection's first row instead of the `null` the calling guard expected, `update()` wrote its `set` onto every record, and `delete()` returned an empty collection with every record removed. All eight filter-object methods now throw a descriptive error naming the offending key — `find()`, `findOne()`, `or()`, `update()`, `replace()`, `max()`, `notIn()` and `delete()`, the last two because `notIn()` routes a filter-object argument through `find()`; only `notIn()`'s array form, `notIn(rows, key)`, is exempt (ACTION REQUIRED if you relied on an undefined value meaning "no constraint" — build the filter conditionally; an explicitly empty `{}` still means no constraint, and `null` remains a legal needle). A non-string field value no longer aborts the whole form validation pass — `isEmail`, `isJsonWebToken` and `trim` called a string method on the value without a type check, so a `123`, `true` or `[]` arriving from a JSON body or a checkbox threw and the rule driver re-threw, killing every remaining field: the request went unvalidated server-side, and client-side the boot-time binding loop died so forms bound after it silently lost both validation and CSRF token injection. All three now leave a non-string untouched — the two checks record their normal rule error and `trim` passes it through untransformed, matching how `isFloat` already behaved (no action required; a defensive upstream coercion added to work around the crash can be removed). Documentation: the external references carried by the framework READMEs are current again, the retired Simple Data Format specification link replaced by the Tabular Data Package specification that superseded it, and every remaining plain-HTTP reference moved to HTTPS. Pickup: restart **and** rebuild your bundles (the browser bundle changed). |
 | **Q4 2026** | `0.6.13` ✅ | **Added**: a general-purpose key-value primitive — declare namespaces under `settings.json > kv.namespaces` and reach them as `gina.kv('<namespace>')`, a promise-native handle with 13 operations including the ones that are hard to get right by hand: set-if-absent, atomic read-and-delete (a one-shot token's second reader gets `null`), compare-and-delete as the safe lock-release primitive, TTL-on-create-only counters, and fetch-or-compute with per-process single-flight. Three backends: in-memory with zero config, redis for namespaces shared across hosts and replicas (every guarantee server-side — `SET .. PX .. NX`, `GETDEL` with a Lua fallback below redis 6.2), and SQLite as the zero-dependency durable option that survives a restart and stays atomic across processes via `IMMEDIATE` transactions, using `node:sqlite` so there is nothing to install. Namespaces are strict-declared — an unknown name throws at the call site rather than silently minting an empty store — and each owns its failure policy; all three backends are verified against one shared contract spec. Deliberately not a redis client: no data structures, batch operations, key scanning, binary values or first-class locks. Identified-caller rate limiting — opt-in quota enforcement at the router keyed on the authenticated principal (a session user via an operator-named field, or a machine caller), with fixed-window counters in a kv namespace you declare, so choosing that namespace's backend chooses the quota's scope: redis or SQLite share one quota across replicas, in-memory counts per process. The gate runs after route authorization and before payload validation, so the refusal order is 401 → 429 → 422 and a throttled caller never receives a field map; it throttles identified callers only, and a request with no resolvable principal is skipped rather than bucketed by IP, since behind a reverse proxy that would be one bucket for the whole internet — anonymous flood control stays with your edge proxy. Denials answer 429 with `Retry-After` plus the `RateLimit` / `RateLimit-Policy` structured fields, which allowed limited requests carry too, and per-route overrides ride a top-level `rateLimit` key in `routing.json`. An opt-in per-authority circuit breaker for `Controller::query()` — after N consecutive transport-class failures to one authority the circuit opens and further calls fail fast with a machine-readable `CIRCUIT_OPEN` error instead of hammering a dead upstream, admitting exactly one critical request as the half-open probe after the cooldown; the gate sits above the HTTP/1.x / HTTP/2 dispatch so retries can never hammer an open circuit by construction, and only transport-class errors count, so an application response of any status cannot trip it. **Fixed**: an exception in a controller's `onReady` or `setup` hook can no longer vanish — both dispatch sites invoked the reserved-action hooks outside the guarded band, so a synchronous throw escaped to the process level (on the built-in engine an uncaught exception killing the whole bundle process, while Express answered its own 500 — an engine asymmetry) and an asynchronous rejection was unowned, leaving the request to hang to client or proxy timeout while work after the throw silently never happened; both loops now run inside the dispatch `try` and every hook's promise is owned by the same guard the main action carried, with the synthesized `setup` wrapper returning the app call's own result so an async `setup.js` rejection actually reaches it (ACTION REQUIRED if a hook of yours can throw: it now answers 500 where it previously crashed, hung, or was masked — and since hooks are still dispatched without awaiting, a hook rejection does not stop the action, so its side effects may already have run when the 500 lands). The entity dispatch diagnostics are readable again — five markers were raw `console.log` calls, which in gina bypasses both the container dispatch and the level gate, so they reached neither a bundle log file nor container logs and were visible only by running a bundle in the foreground; they now go through `console.debug`, off by default and appearing at the `debug` hierarchy as originally intended. **Documentation**: the published claim that gina ships a companion reverse-proxy service is retired — no release ever carried the bundle the help text advertised, and each surface now states the position the rest of the documentation already assumed, that gina ships no edge or reverse proxy by design; run nginx, Traefik or an ingress controller in front of your bundles. Two deliberate boundaries are now stated rather than left as absences: API versioning (no version route field, no version-aware dispatch — with the three shapes the existing primitives already cover) and database migrations (the per-database tools to use, plus running them as a discrete step before the new version serves rather than at bundle boot where replicas race each other, and keeping changes additive during a rolling deploy), and `connector:migrate` is explicitly flagged as not a database migration. Pickup: restart **and** rebuild your bundles — the browser bundle changed, though its client-side delta is inert. |
+| **Q4 2026** | `0.6.14` ✅ | **Added**: network-backed secrets without a vendor SDK or a hung boot — a bundle may declare one operator-supplied fetch command under `settings.secrets.exec` (argv form, no shell) whose stdout must be a single flat JSON object of string values, layered underneath the environment exactly like the existing file tier and mutually exclusive with it, a bundle inheriting a project-wide file chain opting out with `"file": null` beside its own block. It runs once per bundle per config-load cycle, at boot only, and a failing fetch is always a fast, named per-bundle boot refusal rather than a hang: the child is bounded by its own timeout and killed with SIGKILL on expiry, so a wedged secrets endpoint costs a failed boot instead of a process that never comes up. The fetched output is never echoed into any error, log or report, and `gina secrets:check` validates *and runs* the same command through the same code, so the CI gate's verdict matches the boot's by construction; recipes for vault, kubectl and sops ship with the guide, and decrypting at the container entrypoint remains the better pattern wherever the entrypoint can be controlled. `settings.secrets` is also stricter, deliberately: unknown keys and non-object values now refuse the boot instead of silently degrading to environment-only resolution. **Fixed**: a correctness pass over how `self.query()` hands results back to application code. An exception in an `async` query callback could vanish — every app-callback delivery (the Node-style callback form and the `{onComplete}` facade, on both transports) invoked the callback bare, so an asynchronous rejection was unowned and the request hung to client or proxy timeout; rejections now answer 500 with the correlation ref. A synchronous throw inside a callback invoked on a transport-error delivery escaped to the process handler on the event- and timer-frame sites, killing the whole bundle on both engines, and re-invoked the callback with its own exception on the caller-frame sites; all fourteen error-path deliveries are now guarded. An HTTP/2 transport failure was answered twice, the session-level error handler racing the stream-level delivery — and on a reused session answering with the *creating* request's context, since session listeners bind once at connect; notification is now owned solely by the stream-level terminals. Handle-mode error deliveries never reached the app's `onComplete` listener, because both facades dereferenced `data.status` on a single-argument error emit and crashed into a 500 that misattributed the failure to the app callback; the listener is now invoked with the error, and owns the outcome as the callback form does. And HTTP/2 callback mode never delivered a non-5xx error status at all, so graceful degradation was impossible for something as ordinary as a 404 from an HTTP/2 upstream and the documented promisify idiom never settled on one — every body-announced non-2xx now reaches the callback on both transports. `self.query()`'s JSDoc no longer claims the no-callback form returns a Promise: it returns a handle exposing `.onComplete(cb)`, which is not a thenable, so `await self.query({...})` resolved immediately with the handle and silently dropped the result — the real contract and the supported `await` idiom are documented with their rejection shapes, each verified against the runtime. A crash during bundle bootstrap now aborts loudly instead of hanging silently — the async boot frame turned a synchronous throw into a rejection logged at error level with no emergency marker and no exit, so `gina bundle:start` sat on its startup timer and reported a timeout with no cause attached. GET and HEAD query parameters keep their backslash-escaped characters: the pipeline stripped every backslash from the whole serialized document, so a newline degraded to the letter `n`, a backslash vanished, and a double quote or JSON-array value produced invalid JSON that silently dropped every parameter on the request. And `gina secrets:check` now agrees with the boot — its hand-kept mirror of the `settings.secrets.file` declaration guards had drifted permissively twice, reporting green on configurations the bundle refuses to start on, and the command now exits non-zero when a declaration is itself invalid or unreachable rather than only when a required key is unset. **Changed**: the config-source walk behind `secrets:scan` and `secrets:check` now lives in `lib.secrets`, so the two commands enumerate the same config sources by construction and cannot drift apart; CLI behaviour and report output are unchanged. Pickup: restart your bundles — no rebuild needed, the browser bundle's executable content is byte-identical to `0.6.13`. |
 | **Q1 2027** | `0.6.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **2027** | `0.7.0` | Performance — remaining measure-gated candidates: multipart & WebSocket fast paths, render/log cleanups, SIMD scanner (the render-path deep-clone & id-mint reduction shipped early in `0.6.2` with a measured 4.4× render-throughput gain; the profiling baseline itself also shipped in `0.6.2`) |
 | **2027** | `0.8.0` | Financial-messaging foundations — XML request/response handling · pluggable message-schema validation · IBAN/BIC validation rules · money & ISO 4217 minor-unit utilities · idempotency keys · sequence primitive · OAuth2 client-credentials egress |
@@ -266,12 +267,12 @@ Client-side form-validation accessibility — keeping `FormValidator`'s ARIA sta
 
 ## Secrets & Configuration
 
-Secrets handling for bundle JSON configs without baking plaintext values into source. Pluggable-backend design with the environment as the default, plus an opt-in file tier beneath it (`settings.secrets.file`). The backend seam is real — the file tier ships on it, without changing call sites or the placeholder syntax — but a **network-backed** backend (Vault, SOPS with a cloud KMS) is structurally blocked today, not merely unwritten; decrypt at the container entrypoint instead.
+Secrets handling for bundle JSON configs without baking plaintext values into source. Pluggable-backend design with the environment as the default, an opt-in file tier beneath it (`settings.secrets.file`), and an opt-in exec bridge beside that (`settings.secrets.exec`) which runs the operator's own secrets CLI at boot — SOPS, Vault, kubectl — with no vendor SDK in the framework and a hard fail-fast bound. Decrypting at the container entrypoint remains the recommended pattern wherever the entrypoint can be controlled.
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | ✅ | **`${secret:KEY}` placeholder substitution** — `lib/secrets` resolves `${secret:KEY}` placeholders embedded in bundle JSON configs (`settings.json`, `app.json`, `connectors.json`, `mcp.json`, etc.) at config-load time. Anchored regex matches the entire string value only — mixed strings (`"prefix-${secret:K}-suffix"`) pass through unchanged. Default backend reads `process.env[KEY]`; pluggable-backend interface reserved for a future iteration. Fails closed (throws `Error('Secret resolution failed')`) when an env var is unset or empty; the error message intentionally omits the key name. Resolution is once per config-load cycle (in-place mutation). `WeakMap`-backed path tracking enables a future log-redaction wrapper at merged-conf print sites. Hooked inside `core/config.js::loadBundleConfig`, so downstream readers (`getConfig()`, plugin factories) see resolved values transparently. **Consumers shipped**: `gina.plugins.Csrf()` reads `settings.csrf.secret` (precedence `opts.secret` > `settings.csrf.secret` > `process.env.GINA_CSRF_SECRET` for back-compat); `gina bundle:mcp-start` re-runs the resolver on the parsed `mcp.json` immediately after `requireJSON()` so `server.authToken` and any future placeholder field gets filled before downstream readers; bundle scaffolding (`project:add` / `bundle:add`) recommends the placeholder shape in `core/template/conf/settings.json` and `core/template/boilerplate/bundle/index.js`. 33 tests in `test/core/config-secrets-resolver.test.js`. | `0.3.13-alpha` | 2026-05-13 |
-| ⏸ | **Network-backed secret backends** — Vault, SOPS with a cloud KMS, or a Kubernetes Secrets API client resolving `${secret:KEY}` directly at bundle start. **Blocked, not merely unwritten.** The backend seam (`resolve(config, backend?)`) is real and the opt-in file tier (`settings.secrets.file`) ships on it, but `lib/secrets` is fully synchronous and the config loader holds a synchronous initialisation contract — so a network-backed backend would put a round-trip inside a synchronous boot path, where a KMS hiccup becomes a *hung* boot rather than a failed one. Delivering this requires making config-init asynchronous first, a far larger change. *Interim (and the recommended answer regardless):* decrypt at the container entrypoint so values land in the environment, which the resolver already reads first — this is what keeps a KMS call off the boot path. | — | blocked |
+| ✅ | **Secrets exec bridge** — `${secret:KEY}` resolution from Vault, SOPS+KMS or Kubernetes Secrets through ONE operator-declared command (`settings.secrets.exec`: an argv array, no shell, whose stdout must be a single flat JSON object of string values), layered beneath the environment exactly like the file tier and mutually exclusive with it. Fail fast, never hang: the fetch is timeout-bounded (default 10s) and SIGKILLed on expiry, so a wedged secrets endpoint is a fast, named boot refusal — never a hung boot — and the fetched output never appears in any error, log or report. `gina secrets:check` validates and RUNS the same command through the same code, and now exits non-zero on any declaration the runtime would refuse to boot on. Per-vendor SDK backends remain a deliberate non-goal: the vendor CLIs already own auth and endpoints, and a direct in-process network client would require the async config-init question first. *Decrypting at the container entrypoint remains the better pattern wherever the entrypoint can be controlled* (`sops exec-env`, Kubernetes `envFrom` secretRef, Vault agent-injector — values land in the environment, which every tier already prefers); the exec bridge exists for environments where it cannot. | `0.6.x` | 2026-08-23 |
 
 ---
 

package/framework/v0.6.14/VERSION

@@ -0,0 +1 @@
+0.6.14

package/framework/{v0.6.13 → v0.6.14}/core/asset/plugin/dist/vendor/gina/js/gina.js

@@ -26895,12 +26895,15 @@ if ( ( typeof(module) !== 'undefined' ) && module.exports ) {
 /**
  * In-memory document collection with query and mutation methods.
  *
- * Filter values must be defined: `find`/`findOne`/`or`/`update` throw an
- * `Error` naming the offending key when a filter object carries an
- * `undefined` value — build such filters conditionally (add a key only when
- * its value is defined). An explicitly empty `{}` filter is legal and
- * matches every record; `null` is a legal needle comparing strictly
- * against stored values.
+ * Filter values must be defined. Every method that accepts a filter object
+ * throws an `Error` naming the offending key when that object carries an
+ * `undefined` value: `find`, `findOne`, `or`, `update`, `replace`, `max`,
+ * `notIn` and `delete`. The last two are covered transitively — `notIn`
+ * routes a filter-object argument through `find`, and `delete` delegates to
+ * `notIn` — so only `notIn`'s array form, `notIn(rows, key)`, is exempt.
+ * Build such filters conditionally (add a key only when its value is
+ * defined). An explicitly empty `{}` filter is legal and matches every
+ * record; `null` is a legal needle comparing strictly against stored values.
  *
  * @class Collection
  * @constructor

package/framework/{v0.6.13 → v0.6.14}/core/config.js

@@ -3128,10 +3128,15 @@ function Config(opt, contextResetNeeded) {
         // values. Fail-closed: backend throws on unset/empty values.
         //
         // The backend is the env-only default unless the bundle declares
-        // `settings.secrets.file`, in which case files are layered UNDER the
-        // environment (see lib/secrets/backends/file.js for why that way
-        // round). Selection is its own step so that an invalid `secrets`
-        // block reports as a config error rather than as a missing secret.
+        // `settings.secrets.file` (files layered UNDER the environment — see
+        // lib/secrets/backends/file.js for why that way round) or
+        // `settings.secrets.exec` (one operator-declared command whose JSON
+        // stdout layers under the environment the same way; its eager,
+        // SIGKILL-bounded fetch throws here on timeout/failure, so a wedged
+        // fetch is a FAILED boot, never a hung one). The two tiers are
+        // mutually exclusive by validation. Selection is its own step so
+        // that an invalid `secrets` block reports as a config error rather
+        // than as a missing secret.
         var secretsBackend;
         try {
             secretsBackend = secrets.selectBackend(self.envConf[bundle][env]);