gina 0.6.14 → 0.6.15

package/CHANGELOG.md

@@ -6,6 +6,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.6.15 - 2026-08-24
+### Changed
+* The changie pre-commit guard now also requires that a fragment whose FILENAME names a tracker id cites that id in its body (#B410). Only the body is rendered into CHANGELOG.md and the published tarball, so an id carried by the filename and the commit message but missing from the body ships an UNNUMBERED changelog entry, and anyone triaging by id gets a false zero. Measured across all 937 historical fragments, roughly 60 shipped entries are unnumbered this way; the guard stops the next one at commit time rather than at cut time. Recognised id families are an explicit allowlist rather than a generic letters-then-digits pattern, because the generic form false-positives on real filenames (express5, npm12, s3) and a false positive would block a commit; a filename encoding no recognised id is skipped, never failed.
+### Fixed
+* The couchbase connector no longer hangs a request when a `@return {number}` COUNT query does not match its alias parser (#B412, consumer-reported). The branch parsed the COUNT alias out of the query text and dereferenced the match without a guard, so `SELECT COUNT(DISTINCT a.b) AS n` (the pattern could not span the space inside the parentheses) and an unaliased `SELECT COUNT(*)` both produced a null match and threw. Because the throw happened inside the connector's own result callback, the failure did not surface as a 5xx: a promisified caller never settled and the request hung until the client or proxy timed out, leaving only an uncorrelated log line, and behind an HTTP/2 inter-bundle client the stall was then retried. It was also invisible in development, where only the first comment block is stripped from the query text, so a commented-out parsable COUNT elsewhere in the file kept the parser satisfied locally while production - which strips every comment - threw on the identical file. The branch now derives the count from the first projected column with no regex at all, guarded against empty result sets, empty rows and null payloads, exactly as the mysql, postgresql, scylladb and sqlite connectors already did and as the documented contract (first key of first row) already stated. Also fixed on the same path: the `@return` annotation parser was greedy, so a second brace pair later on the same line over-captured (`@return {object} note {x}` yielded `object} note {x`) and the resulting unknown return type fell through every branch silently, handing the caller the raw row array instead of the declared shape; it is now bounded to the first brace pair like the sibling connectors. Behaviour change worth knowing: for a multi-column projection whose COUNT is not the first column, the returned value is now the first column rather than the aliased one - consistent with every other connector.
+* The couchbase connector now normalises the types it reads from `@return` and `@param` annotations, and bounds both captures to the first brace pair (#B413). Both extracted types feed exact-match comparisons whose arms are all lowercase - the return type against the branch chain that dispatches the declared shape, and each param type against the switch in the parameter cast - so a capitalised or space-padded type such as `{Number}` or `{ number }` matched nothing and was SILENTLY skipped: the caller received the raw row array instead of the declared shape, and the parameter was left uncast. Both are now trimmed and lowercased at extraction, exactly as the mysql, postgresql, scylladb and sqlite connectors already did. The two captures were also greedy, so a second brace pair on the same line bled into the extracted type (`@param {a} and {b}` yielded `a} and {b`), which then matched no cast arm either; both are bounded to the first brace pair. Behaviour change worth knowing: annotations that previously fell through silently now reach their branch, so a query declaring `@return {Number}` begins returning the declared shape rather than the raw row array. The `@options` annotation deliberately keeps its greedy capture and is pinned as such - it holds a nestable object literal rather than a single type token, so bounding it would truncate a nested object and break the parse.
+* Client-side handler release now awaits the routing table (#B414, consumer-reported with a two-way browser reproduction). The client routing table arrives only by async fetch (the page whispers an empty stub), yet `gina.ready` handlers and the auto-boot validator released at DOMContentLoaded - so any `getRoute()`/`toUrl()` during handler or form-bind initialisation ran against an empty table. Loopback wins that race by single-digit milliseconds, which is why development never sees it; a real deployment loses it by 150ms or more on every load, deterministically - a validator form rule naming a route then threw inside the init listener, the throw was swallowed by the event dispatch, and the instance's `ready` never fired, silently. All three release paths now gate on the dependency SETTLING: the ready-list scheduler, the validator auto-boot poll, and the late-registration path (a handler registered after DOMContentLoaded previously bypassed the scheduler entirely and fired immediately). Settled deliberately means loaded OR failed - a broken endpoint still releases handlers rather than hanging the page - and a parse-time 5-second fallback force-settles with a console error in degenerate shapes where the fetch is never issued. Behaviour change worth knowing: on deployed tiers, `gina.ready` handlers now fire when routing is actually available (typically 150ms-1.3s later than before, per the consumer's measurements); on loopback and in development the difference is single-digit milliseconds. Pages that do not use client routing are unaffected in every case but the timing.
+* Client-side `getRoute()` no longer crashes with a context-free TypeError when a bundle's routing table is absent (#B415). The client `getRouting()` returns null by design when nothing matches - an empty table before the routing fetch lands, or a bundle with no rules - and the bare dereference of that null sat one line above the very diagnostic built for the degraded-table case, so the case it existed for was exactly the one it could never report. A named guard now throws `bundle X has no routing table for rule Y (client: routing config not loaded yet, or empty)`, restoring the diagnostic's intent on both the client and the server.
+* A failed client routing fetch now leaves console evidence (#B416). The dependency bus event fires on fetch failure as well as success - that is what keeps the page booting - but the listener discarded the error it carried, so a genuinely failed fetch (a non-OK status caught by the response guard) booted the framework permanently degraded, with an empty routing table and zero console output. The listener now reads and reports the carried error, naming the consequence: client `getRoute()`/`toUrl()` degraded until reload.
+* Fixed #B328 — calling the public link API with a url no link is registered for (gina.link.request(url), or a registered link's .request(url) with a foreign url) threw a bare TypeError. It now throws a named error identifying the url and the likely cause — never bound, or bound by a later construction the published instance cannot see. The miss is also detected before the supersede step, so a mistyped url no longer aborts a legitimate request still in flight. Click-driven links are unaffected: both click paths always resolve a real registration.
+* Fixed #B329 — the popin stylesheet no longer restyles every dialog on the page: its ::backdrop rule (dark overlay + blur) is now scoped to gina's own popin dialogs (dialog.gina-popin-container::backdrop), matching the reduced-motion rules that were already scoped. Consumer-visible: a page that relied on the unscoped rule to style its own dialogs must now style them itself, and a popin dialog element supplied by the page's own markup needs the gina-popin-container class to keep gina's backdrop.
+
 ## 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.

package/README.md

@@ -62,39 +62,36 @@ 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.14
+## What's in 0.6.15
 
-> **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`.
+> **Restart your bundles AND rebuild them.** This release changes the browser
+> bundle: both `gina.min.js` and `gina.min.css` differ from `0.6.14`. A restart
+> alone updates the server half only — each bundle bakes its own copy of the
+> client assets, so `gina bundle:build` is required for the client-boot,
+> link and popin fixes below to reach a browser at all.
 
-> **No settings reset.** `0.6.14` is a patch — the `shortVersion` stays `0.6`, so
+> **No settings reset.** `0.6.15` is a patch — the `shortVersion` stays `0.6`, so
 > your `~/.gina/0.6/settings.json` is untouched. (`0.6.0` was the reset.)
 
-**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.
+**A correctness pass over client boot, and two connector defects that could hang
+a request.** The headline is a race that only a real deployment can lose: the
+client routing table arrives by async fetch, but handlers were released before it
+landed — so anything resolving a route during initialisation ran against an empty
+table, deterministically, on every page load away from loopback. Alongside it,
+the couchbase connector no longer hangs a request on an unparsed `COUNT`, and two
+client plugins stop leaking their behaviour onto pages that never asked for it.
 **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 — 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.
+- **Fixed — client handlers now wait for the routing table (#B414, consumer-reported).** The client routing table arrives only by async fetch — the page deliberately whispers an empty stub rather than inlining it — yet `gina.ready` handlers and the auto-boot validator released at `DOMContentLoaded`. Anything calling `getRoute()`/`toUrl()` during handler or form-bind initialisation therefore ran against an empty table. Loopback wins that race by single-digit milliseconds, which is why development and local suites never see it; a real deployment loses it by 150ms or more on *every* load. A validator form rule naming a route then threw inside the init listener, the event dispatch swallowed the throw, and the instance's `ready` never fired — silently, with one uncorrelated console error as the only artefact. All three release paths now gate on the dependency *settling*: the ready-list scheduler, the validator auto-boot poll, and the late-registration path (a handler registered after `DOMContentLoaded` previously bypassed the scheduler and fired immediately). Settled deliberately means loaded **or** failed, so a broken endpoint still releases handlers rather than hanging the page, and a parse-time 5-second fallback force-settles with a console error in degenerate shapes where no fetch is ever issued. **Behaviour change:** on deployed tiers `gina.ready` handlers now fire when routing is actually available — typically 150ms–1.3s later than before; on loopback and in development the difference is single-digit milliseconds. Pages that do not use client routing are unaffected but for the timing.
+- **Fixed — `getRoute()` reports a missing routing table instead of crashing (#B415).** The client `getRouting()` returns `null` by design when nothing matches — an empty table before the fetch lands, or a bundle with no rules — and the bare dereference of that `null` sat one line *above* the very diagnostic built for the degraded-table case, so the case it existed for was exactly the one it could never report. A named guard now throws `bundle X has no routing table for rule Y (client: routing config not loaded yet, or empty)`, on both the client and the server.
+- **Fixed — a failed routing fetch now leaves console evidence (#B416).** The dependency bus fires on fetch failure as well as success — that is what keeps the page booting — but the listener discarded the error it carried. A genuinely failed fetch booted the framework permanently degraded, with an empty routing table and *zero* console output. The listener now reports the carried error and names the consequence: client `getRoute()`/`toUrl()` degraded until reload.
+- **Fixed — a couchbase `COUNT` query can no longer hang the request (#B412, consumer-reported).** The `@return {number}` branch parsed the COUNT alias out of the query text and dereferenced the match unguarded, so `SELECT COUNT(DISTINCT a.b) AS n` — the pattern cannot span the space inside the parentheses — and an unaliased `SELECT COUNT(*)` both produced a null match and threw. The severity was not the throw but where it landed: inside the connector's own result callback, so no 5xx was ever produced, a promisified caller never settled, and the request hung until the client or proxy timed out — leaving one uncorrelated log line, and behind an HTTP/2 inter-bundle client the stall was then retried. It was dev-invisible too: the dev path strips only the first comment block, so a commented-out parsable COUNT elsewhere in the file kept the regex satisfied locally while production, which strips every comment, threw on the identical file. The branch now derives the count from the first projected column with no regex at all, guarded against empty result sets, empty rows and null payloads — exactly as mysql, postgresql, scylladb and sqlite already did, and as the documented contract already stated. **Behaviour change:** for a multi-column projection whose COUNT is not the first column, the returned value is now the first column rather than the aliased one — consistent with every other connector.
+- **Fixed — couchbase annotation types are normalised and bounded (#B413).** Both the `@return` type and each `@param` type feed exact-match comparisons whose arms are all lowercase, so a capitalised or space-padded type such as `{Number}` or `{ number }` matched nothing and was silently skipped — handing the caller the raw row array instead of the declared shape, and leaving the parameter uncast. Both are now trimmed and lowercased at extraction, as the sibling connectors already did. Both captures were also greedy, so a second brace pair on the same line bled into the extracted type (`@param {a} and {b}` yielded `a} and {b`), matching no cast arm either; both are bounded to the first brace pair. **Behaviour change:** annotations that previously fell through silently now reach their branch, so a query declaring `@return {Number}` begins returning the declared shape rather than the raw row array. `@options` deliberately keeps its greedy capture — it holds a nestable object literal, not a single type token.
+- **Fixed — the public link API names its error instead of throwing a bare TypeError (#B328).** Calling `gina.link.request(url)` — or a registered link's `.request(url)` with a foreign url — for a url no link is registered for dereferenced the null resolution. It now throws a named error identifying the url and the likely cause: never bound, or bound by a later construction the published instance cannot see. The miss is also detected *before* the supersede step, so a mistyped url no longer aborts a legitimate request still in flight. Click-driven links are unaffected — both click paths always resolve a real registration.
+- **Fixed — the popin stylesheet no longer restyles every dialog on the page (#B329).** Its `::backdrop` rule (dark overlay + blur) shipped unscoped on the bare `dialog` element, so gina painted its backdrop on any `<dialog>` a page opened. It is now scoped to `dialog.gina-popin-container::backdrop`, matching the reduced-motion rules that were already scoped. **Consumer-visible:** a page that relied on the unscoped rule to style its own dialogs must style them itself now, and a popin dialog element supplied by the page's own markup needs the `gina-popin-container` class to keep gina's backdrop.
+- **Changed — a changelog fragment must cite the tracker id its filename names (#B410).** Only the body is rendered into `CHANGELOG.md` and the published tarball, so an id carried by the filename and the commit message but missing from the body ships an unnumbered changelog entry — and anyone triaging by id gets a false zero. Measured across all 937 historical fragments, roughly 60 shipped entries are unnumbered this way; the guard stops the next one at commit time rather than at cut time. Recognised id families are an explicit allowlist rather than a generic letters-then-digits pattern, because the generic form false-positives on real filenames (`express5`, `npm12`, `s3`) and a false positive would block a commit; a filename encoding no recognised id is skipped, never failed.
 
 ## Documentation
 

package/ROADMAP.md

@@ -66,6 +66,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **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`. |
+| **Q4 2026** | `0.6.15` ✅ | **Fixed**: client-side handler release now awaits the routing table — the table arrives only by async fetch (the page deliberately whispers an empty stub rather than inlining it) yet `gina.ready` handlers and the auto-boot validator released at `DOMContentLoaded`, so anything calling `getRoute()`/`toUrl()` during handler or form-bind initialisation ran against an empty table; loopback wins that race by single-digit milliseconds, which is why development and the local suites never see it, while a real deployment loses it by 150ms or more on every load, deterministically — a validator form rule naming a route then threw inside the init listener, the event dispatch swallowed the throw, and the instance's `ready` never fired, silently. All three release paths now gate on the dependency settling (the ready-list scheduler, the validator auto-boot poll, and the late-registration path that previously bypassed the scheduler entirely and fired immediately), settled deliberately meaning loaded **or** failed so a broken endpoint still releases handlers rather than hanging the page, with a parse-time 5-second fallback force-settling in degenerate shapes where no fetch is ever issued (ACTION REQUIRED only in the sense of timing: on deployed tiers handlers now fire 150ms–1.3s later than before, when routing is actually available). Alongside it, client `getRoute()` no longer crashes with a context-free TypeError when a bundle's routing table is absent — the client `getRouting()` returns null by design, and the bare dereference of that null sat one line above the very diagnostic built for the degraded-table case, so the case it existed for was exactly the one it could never report — and a failed routing fetch now leaves console evidence instead of booting the framework permanently degraded in silence. The couchbase connector no longer hangs a request when a `@return {number}` COUNT query does not match its alias parser: the branch dereferenced an unguarded regex match, so `SELECT COUNT(DISTINCT a.b) AS n` and an unaliased `SELECT COUNT(*)` both threw inside the connector's own result callback — no 5xx was ever produced, a promisified caller never settled, and the request hung until the client or proxy timed out, a stall then retried behind an HTTP/2 inter-bundle client; it was dev-invisible too, since the dev path strips only the first comment block, so a commented-out parsable COUNT elsewhere in the file kept the regex satisfied locally while production threw on the identical file. The branch now derives the count from the first projected column with no regex at all, guarded against empty result sets, empty rows and null payloads, exactly as mysql, postgresql, scylladb and sqlite already did (ACTION REQUIRED if a multi-column projection puts its COUNT anywhere but first: the returned value is now the first column rather than the aliased one, consistent with every other connector). The same connector now trims and lowercases the types it reads from `@return` and `@param`, and bounds both captures to the first brace pair — the extracted types feed exact-match comparisons whose arms are all lowercase, so `{Number}` or `{ number }` matched nothing and was silently skipped, handing back the raw row array instead of the declared shape and leaving the parameter uncast, while a second brace pair on the same line bled into the greedy capture (ACTION REQUIRED: annotations that previously fell through silently now reach their branch, so a query declaring `@return {Number}` begins returning the declared shape; `@options` deliberately keeps its greedy capture, holding a nestable object literal rather than a single type token). Two client plugins stop leaking behaviour onto pages that never asked for it: the public link API throws a named error identifying the url and the likely cause instead of a bare TypeError, and detects the miss before the supersede step so a mistyped url no longer aborts a legitimate request still in flight; and the popin stylesheet's `::backdrop` rule is scoped to gina's own popin dialogs rather than every `<dialog>` on the page (ACTION REQUIRED if a page relied on the unscoped rule to style its own dialogs, or supplies a popin dialog element from its own markup — that element needs the `gina-popin-container` class to keep gina's backdrop). **Changed**: a changelog fragment whose filename names a tracker id must now cite that id in its body, since only the body renders into `CHANGELOG.md` and the published tarball — an id carried by filename and commit message alone ships an unnumbered entry and anyone triaging by id gets a false zero (roughly 60 of 937 historical fragments shipped that way); recognised id families are an explicit allowlist rather than a generic pattern, because the generic form false-positives on real filenames and a false positive would block a commit. Pickup: restart **and** rebuild your bundles (the browser bundle changed — both `gina.min.js` and `gina.min.css` differ from `0.6.14`). |
 | **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 |

package/framework/v0.6.15/VERSION

@@ -0,0 +1 @@
+0.6.15

package/framework/{v0.6.14 → v0.6.15}/core/asset/plugin/dist/vendor/gina/css/gina.min.css

@@ -1 +1 @@
-@charset "UTF-8";@keyframes gina-popin-skeleton-shimmer{0%{background-position:200%0}to{background-position:-200%0}}@layer gina{[data-gina-loading=true]{cursor:progress}@keyframes gina-loading-pulse{0%{opacity:1}to{opacity:.55}}@media (prefers-reduced-motion:no-preference){[data-gina-loading=true]{animation:gina-loading-pulse .9s ease-in-out infinite alternate}}@media (prefers-reduced-motion:reduce){[data-gina-loading=true]{opacity:.7}}[data-gina-form-submit-gated=true]{cursor:not-allowed;opacity:.7}}@font-face{font-family:"have_heart_oneregular";src:url(fonts/have_heart_one-webfont.woff2)format("woff2"),url(fonts/have_heart_one-webfont.woff)format("woff");font-weight:400;font-style:normal}.gina-popin-container{background:#fff}.gina-popins-overlay,div.gina-popin-container{visibility:hidden;opacity:0;z-index:1;transition:opacity .3s,visibility 0 .3s}.gina-popins-overlay.gina-popin-is-active,div.gina-popin-container.gina-popin-is-active{opacity:1;visibility:visible;transition-delay:0}dialog.gina-popin-container{padding:0;border:0;z-index:1}@media (prefers-reduced-motion:no-preference){dialog.gina-popin-container{opacity:0;transform:translateY(-.5rem);transition:opacity .2s ease,transform .2s ease,overlay .2s ease allow-discrete,display .2s ease allow-discrete}dialog.gina-popin-container[open]{opacity:1;transform:translateY(0)}@starting-style{dialog.gina-popin-container[open]{opacity:0;transform:translateY(-.5rem)}}dialog.gina-popin-container::backdrop{opacity:0;transition:opacity .2s ease,overlay .2s ease allow-discrete,display .2s ease allow-discrete}dialog.gina-popin-container[open]::backdrop{opacity:1}@starting-style{dialog.gina-popin-container[open]::backdrop{opacity:0}}}body[data-gina-popin-scroll-lock]{overflow:hidden}.gina-popins-overlay{position:fixed;left:0;top:0;display:grid;place-items:center;width:100%;height:100%;transition:opacity .3s,visibility .3s;overflow:auto;background:rgba(0,0,0,.75)}.gina-popins-overlay.gina-popin-is-active{backdrop-filter:blur(6px)}dialog::backdrop{background-color:rgba(0,0,0,.75);backdrop-filter:blur(6px)}.gina-popin-skeleton{padding:1.5rem;min-width:18rem;max-width:90vw}.gina-popin-skeleton .gina-popin-skeleton-line{height:.85rem;margin-bottom:.75rem;border-radius:4px;background:linear-gradient(90deg,#ededed 25%,#f7f7f7 50%,#ededed 75%);background-size:200% 100%;animation:gina-popin-skeleton-shimmer 1.4s ease-in-out infinite}.gina-popin-skeleton .gina-popin-skeleton-line:last-child{margin-bottom:0}.gina-popin-skeleton .gina-popin-skeleton-title{height:1.4rem;width:60%;margin-bottom:1.25rem}.gina-popin-skeleton .gina-popin-skeleton-line--short{width:40%}@media (prefers-reduced-motion:reduce){.gina-popin-skeleton .gina-popin-skeleton-line{animation:none}}
+@charset "UTF-8";@keyframes gina-popin-skeleton-shimmer{0%{background-position:200%0}to{background-position:-200%0}}@layer gina{[data-gina-loading=true]{cursor:progress}@keyframes gina-loading-pulse{0%{opacity:1}to{opacity:.55}}@media (prefers-reduced-motion:no-preference){[data-gina-loading=true]{animation:gina-loading-pulse .9s ease-in-out infinite alternate}}@media (prefers-reduced-motion:reduce){[data-gina-loading=true]{opacity:.7}}[data-gina-form-submit-gated=true]{cursor:not-allowed;opacity:.7}}@font-face{font-family:"have_heart_oneregular";src:url(fonts/have_heart_one-webfont.woff2)format("woff2"),url(fonts/have_heart_one-webfont.woff)format("woff");font-weight:400;font-style:normal}.gina-popin-container{background:#fff}.gina-popins-overlay,div.gina-popin-container{visibility:hidden;opacity:0;z-index:1;transition:opacity .3s,visibility 0 .3s}.gina-popins-overlay.gina-popin-is-active,div.gina-popin-container.gina-popin-is-active{opacity:1;visibility:visible;transition-delay:0}dialog.gina-popin-container{padding:0;border:0;z-index:1}@media (prefers-reduced-motion:no-preference){dialog.gina-popin-container{opacity:0;transform:translateY(-.5rem);transition:opacity .2s ease,transform .2s ease,overlay .2s ease allow-discrete,display .2s ease allow-discrete}dialog.gina-popin-container[open]{opacity:1;transform:translateY(0)}@starting-style{dialog.gina-popin-container[open]{opacity:0;transform:translateY(-.5rem)}}dialog.gina-popin-container::backdrop{opacity:0;transition:opacity .2s ease,overlay .2s ease allow-discrete,display .2s ease allow-discrete}dialog.gina-popin-container[open]::backdrop{opacity:1}@starting-style{dialog.gina-popin-container[open]::backdrop{opacity:0}}}body[data-gina-popin-scroll-lock]{overflow:hidden}.gina-popins-overlay{position:fixed;left:0;top:0;display:grid;place-items:center;width:100%;height:100%;transition:opacity .3s,visibility .3s;overflow:auto;background:rgba(0,0,0,.75)}.gina-popins-overlay.gina-popin-is-active{backdrop-filter:blur(6px)}dialog.gina-popin-container::backdrop{background-color:rgba(0,0,0,.75);backdrop-filter:blur(6px)}.gina-popin-skeleton{padding:1.5rem;min-width:18rem;max-width:90vw}.gina-popin-skeleton .gina-popin-skeleton-line{height:.85rem;margin-bottom:.75rem;border-radius:4px;background:linear-gradient(90deg,#ededed 25%,#f7f7f7 50%,#ededed 75%);background-size:200% 100%;animation:gina-popin-skeleton-shimmer 1.4s ease-in-out infinite}.gina-popin-skeleton .gina-popin-skeleton-line:last-child{margin-bottom:0}.gina-popin-skeleton .gina-popin-skeleton-title{height:1.4rem;width:60%;margin-bottom:1.25rem}.gina-popin-skeleton .gina-popin-skeleton-line--short{width:40%}@media (prefers-reduced-motion:reduce){.gina-popin-skeleton .gina-popin-skeleton-line{animation:none}}

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

@@ -6675,6 +6675,15 @@ function Routing() {
         // }
 
 
+        // #B415 — client-side getRouting returns null BY DESIGN when nothing
+        // matches (a {} table before the routing fetch lands, or a bundle with
+        // no rules). The bare `routing[rule]` deref below then threw a context-
+        // free TypeError ONE LINE ABOVE the #B132 diagnostic — so the degraded-
+        // table case #B132 was built for was exactly the one it could never
+        // report. Name the bundle and the likely cause instead.
+        if ( !routing ) {
+            throw new Error('[ RoutingHelper::getRoute(rule, params) ] : bundle `'+ bundle +'` has no routing table for rule `'+ rule +'` (client: routing config not loaded yet, or empty)')
+        }
         if ( typeof(routing[rule]) == 'undefined' ) {
             // #B132 — name the bundle + its table size so a degraded/near-empty
             // table (e.g. a bundle whose routing config never loaded) is
@@ -10075,6 +10084,10 @@ define('gina/link', [ 'require', 'lib/domain', 'lib/loading-state', 'lib/merge',
          * url lookup run. Before this order existed, two anchors sharing one url
          * collapsed onto whichever registered first, whichever was clicked.
          *
+         * A url that resolves to no registration throws a named error BEFORE the
+         * supersede step (#B328) — a miss can never abort a request already in
+         * flight, and the message names the url plus the likely cause.
+         *
          * Side effects: supersedes any request still in flight, arms `data-gina-loading`
          * on the anchor for the duration of this one, and releases it from a `loadend`
          * listener. An indefinite hang is the single outcome that never releases, because
@@ -10083,6 +10096,8 @@ define('gina/link', [ 'require', 'lib/domain', 'lib/loading-state', 'lib/merge',
          * @param {string} url - URL to request
          * @param {object} [options] - XHR options, merged over the link's own
          *
+         * @throws {Error} when `url` matches no registration (the public-path miss)
+         *
          * @returns {void}
          *
          * @example
@@ -10097,6 +10112,20 @@ define('gina/link', [ 'require', 'lib/domain', 'lib/loading-state', 'lib/merge',
             var $operated = _operatedLink;
             _operatedLink = null;
 
+            // link object — #B287: the operated registration wins; the first-match
+            // url lookup remains only for the public `gina.link.request(url)` path.
+            // #B328 — resolved (and guarded) BEFORE the transport block below:
+            // resolving after it meant a mistyped public url had already aborted a
+            // legitimate in-flight request before throwing a bare TypeError on
+            // `$link.id`. A miss now leaves transport state untouched.
+            var $link      = $operated || getLinkByUrl(url);
+            if ( !$link ) {
+                // Named like #B415's null-table guard: tell a mistyped url from the
+                // real second shape — a registration added by a later construction,
+                // which the published instance's walk cannot see (#B326).
+                throw new Error('[ LinkHandler::request(url, options) ] : no link is registered for url `'+ url +'` (never bound, or bound by a later construction — the published instance walks only its own registrations)');
+            }
+
             // One transport per request, and a sequence taken BEFORE the abort so a
             // supersede-abort is stale by construction — its handler sees
             // `seq !== _linkSeq` and drops out, which is what keeps the abort from
@@ -10110,9 +10139,6 @@ define('gina/link', [ 'require', 'lib/domain', 'lib/loading-state', 'lib/merge',
             var xhr = createXhr();
             _linkXhr = xhr;
 
-            // link object — #B287: the operated registration wins; the first-match
-            // url lookup remains only for the public `gina.link.request(url)` path.
-            var $link      = $operated || getLinkByUrl(url);
             var id         = $link.id;
 
 
@@ -28625,6 +28651,55 @@ var readyList = [
 var readyFired = false;
 var readyEventHandlersInstalled = false;
 
+// #B414 — the framework's ONE mandatory client dependency (the routing table,
+// fetched by getDependencies from `<webroot>_gina/assets/routing.json`) must be
+// SETTLED before any consumer handler runs: the server whispers
+// `page.environment.routing` as a hardcoded '{}' (the real export is commented
+// out — "Adding 289 KB"), so between DOMContentLoaded and the fetch landing,
+// `gina.config.routing` is {} and any getRoute()/toUrl() in handler init throws
+// or misroutes. Loopback wins that race by single-digit ms; a real deployment
+// LOSES it by 150ms+ on every load — deterministic breakage that local dev can
+// never see. "Settled" deliberately means loaded OR failed: loadRoutingConf
+// dispatches `deps.loaded` on both paths, so a broken endpoint still releases
+// handlers (with console evidence via the listener) instead of hanging the page.
+var _ginaDepsSettled = false;
+var _ginaDepsQueue   = [];
+/**
+ * Marks the mandatory client deps settled and drains every queued callback.
+ * Idempotent — the forced (timeout) and real (deps.loaded) paths can both fire.
+ * @param {boolean} [forced] - true when the 5s fallback fired before the deps
+ * @inner
+ */
+function _settleDeps(forced) {
+    if (_ginaDepsSettled) return;
+    _ginaDepsSettled = true;
+    if (forced && typeof(console) != 'undefined' && console.error) {
+        console.error('[gina] routing dependency still pending after 5s — releasing handlers with a degraded routing table');
+    }
+    while (_ginaDepsQueue.length) {
+        try { _ginaDepsQueue.shift()(); } catch (depsCbErr) {
+            if ( typeof(console) != 'undefined' && console.error ) {
+                console.error(depsCbErr.stack || depsCbErr.message || depsCbErr);
+            }
+        }
+    }
+}
+/**
+ * Runs `fn` now if the mandatory deps have settled, else queues it for the
+ * settle drain (real or forced).
+ * @param {function} fn
+ * @inner
+ */
+function _whenDepsSettled(fn) {
+    if (_ginaDepsSettled) { fn(); return; }
+    _ginaDepsQueue.push(fn);
+}
+// Armed at PARSE TIME on purpose — NOT inside getDependencies: on a page where
+// the script-tag scan matches nothing (renamed src, static harness) the fetch
+// is never issued, so a timer armed there would never start and the gate would
+// hang handlers forever in exactly the degenerate case it exists to protect.
+setTimeout(function () { _settleDeps(true); }, 5000);
+
 // call this when the document is ready
 // this function protects itself against being called more than once
 function ready() {
@@ -28651,7 +28726,13 @@ function ready() {
                             result = readyList[i].fn.call(window, readyList[i].ctx, window.require);
 
                             // clear
-                            if (result) {
+                            // #B414 — advance past the gina entry only once the
+                            // routing dependency has settled too: a truthy
+                            // onGinaLoaded means only that the LOADER's whispers
+                            // ran (isFrameworkLoaded), never that the async
+                            // routing fetch landed. Releasing here without it
+                            // ran consumer handlers against a {} table.
+                            if (result && _ginaDepsSettled) {
                                 window.clearInterval(scheduler);
                                 ++i;
                                 handleEvent(i, readyList);
@@ -28742,7 +28823,12 @@ if ( typeof(window['gina']) == 'undefined' ) { // could have be defined by loade
         /**
          * ready
          * This is the one public interface use to wrap `handlers`
-         * It is an equivalent of document.addEventListener('DOMContentLoaded', cb)
+         * It fires once BOTH document readiness (DOMContentLoaded-equivalent)
+         * AND the framework's mandatory routing dependency have settled — the
+         * routing table arrives by async fetch, so DOMContentLoaded alone was
+         * too early on deployed tiers (#B414). If the fetch fails or never
+         * starts, handlers still release (settle-on-error / 5s fallback), with
+         * console evidence.
          *
          * No need to use it for `handlers`, it is automatically applied for each `handler`
          *
@@ -28756,7 +28842,14 @@ if ( typeof(window['gina']) == 'undefined' ) { // could have be defined by loade
             // if ready has already beenfired, then just schedule the callback
             // to fire asynchronously, but right away
             if (readyFired) {
-                setTimeout(function() {callback(context);}, 1);
+                // #B414 — the late-registration path must gate on the routing
+                // dependency too: this branch bypasses the readyList scheduler
+                // entirely, so without the gate a handler registered after
+                // DOMContentLoaded (a deferred script, a handler registered
+                // from another handler) still ran against a {} table.
+                _whenDepsSettled(function () {
+                    setTimeout(function() {callback(context);}, 1);
+                });
                 return;
             } else {
                 // add the function and context to the list
@@ -28882,7 +28975,14 @@ require([
     var _validatorBootTries = 0;
     var bootValidator = function () {
         try {
-            if ( !window['gina'] || !window['gina']['isFrameworkLoaded'] ) {
+            // #B414 — `_ginaDepsSettled` joins the gate: `isFrameworkLoaded`
+            // guarantees the whispers (incl. gina.forms) ran, but NOT that the
+            // async routing fetch landed — and a form rule may name a route
+            // (the `query` rule), which evaluates at bind. Constructing before
+            // the deps settle bound forms against a {} table and died inside
+            // the init listener. Settle-on-error + the 5s fallback keep this
+            // poll terminating in every degenerate shape.
+            if ( !window['gina'] || !window['gina']['isFrameworkLoaded'] || !_ginaDepsSettled ) {
                 if ( _validatorBootTries++ < 100 ) {
                     (window['setTimeout'] || function (fn) { fn(); })(bootValidator, 50);
                 }
@@ -29046,9 +29146,21 @@ function getDependencies(gina, cb) {
         // }
     ];
     depsEventBus.addEventListener('deps.loaded', (event) => {
+        // #B416 — surface the failure the event carries: loadRoutingConf
+        // dispatches this on ERROR too (that is what keeps the boot alive),
+        // but the detail was discarded — a failed fetch (#B213's guard
+        // throwing on a non-OK status) booted the framework permanently
+        // degraded (routing {}) with ZERO console evidence.
+        if ( event && event.detail && event.detail.error ) {
+            if ( typeof(console) != 'undefined' && console.error ) {
+                console.error('[gina] routing dependency failed to load — client getRoute()/toUrl() will be degraded until reload:', event.detail.error.stack || event.detail.error.message || event.detail.error);
+            }
+        }
         arr.splice(0,1);
         if (!arr.length) {
-            // Deps ready
+            // Deps settled (loaded or failed) — release the #B414 gate, then
+            // run the script-onload continuation (the ginaloaded attach).
+            _settleDeps();
             cb()
         }
     });