gina 0.5.2-alpha.1 → 0.5.2

package/CHANGELOG.md

@@ -6,6 +6,14 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.2 - 2026-06-13
+### Fixed
+* Fixed an inter-bundle self.query() over HTTP/2 reporting an upstream 502 as success once its retries were exhausted: the 502 response body was handed to the query callback as if it were valid data (and a JSON-shaped body was even relabelled with status 200), so a caller could silently consume a Bad Gateway error page as a real response. Exhausted 502s now surface a typed error to the caller (status 502, code BAD_GATEWAY), matching how timeout, stream-error, and premature-close exhaustion are already reported; non-critical queries still swallow it. (#B34)
+* Fixed five synchronous controller helpers (isPopinContext, setRequestMethod, setRequestMethodParams, getRequestMethodParams, getFormsRules) crashing the bundle when called after the response was already released. A controller action that keeps running after self.redirect() (which releases the per-request response and lets the middleware chain continue) and then calls one of these helpers dereferenced the released request and threw, escalating to an uncaughtException and a SIGTERM bundle shutdown. Each now returns a safe default (false / null / {}) on a released request, matching the released-response guards already on the query and throwError paths. (#B35)
+* Fixed renderJSON() crashing the bundle when called after the response was already released. A controller action that keeps running after self.redirect() (which releases the per-request response and lets the middleware chain continue) and then calls self.renderJSON() dereferenced the released response and threw synchronously, escalating to an uncaughtException and a SIGTERM bundle shutdown. renderJSON() now no-ops on a released response, matching the released-response guards already on the query, throwError and the other controller helpers. (#B36)
+* Fixed self.redirect() crashing the bundle when called after the response was already released. redirect() is synchronous and reads the request/response throughout, so a controller that hits a terminal exit (a prior redirect, or a render-error path) and then calls self.redirect() again dereferenced the released request and threw synchronously, escalating to an uncaughtException and a SIGTERM bundle shutdown. redirect() now no-ops on a released response, matching the guards already on the query, throwError, renderJSON and the other controller helpers. (#B37)
+* Fixed six more controller methods crashing the bundle when called on a response that a terminal exit had already released. downloadFromLocal, store(target).onComplete(cb), renderStream, push, pauseRequest and resumeRequest each synchronously dereference the per-request request/response, so a controller that hits a terminal exit (for example a redirect that then lets the middleware chain continue) and later calls one of them dereferenced the released refs and threw synchronously, escalating to an uncaughtException and a SIGTERM bundle shutdown. Each now no-ops (or notifies through its existing callback/event channel) on a released response, matching the guards already on redirect, throwError, renderJSON and the other controller helpers; live requests are byte-for-byte unaffected. (#B38)
+
 ## 0.5.1 - 2026-06-12
 ### Added
 * Stable publishes now run a ROADMAP.md consistency gate (script/check_roadmap_consistency.js, wired into the release prepare step alongside the README freshness gate). The publish aborts when an open roadmap row still references the exact version being released (the row would become stale the moment the tag lands) or when a done row is labelled with a version newer than the one shipping; a missing "released" timeline mark is surfaced as a warning only. Alpha publishes skip the gate.

package/README.md

@@ -39,12 +39,10 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
-## What's in 0.5.1
+## What's in 0.5.2
 
-- **Released-response crash family fixed (bundle-killing).** A late `throwError()` after the response was already sent — e.g. an entity or query callback resuming after a `redirect()` had already issued its 301 — dereferenced the released response, escalating to an `uncaughtException` and a SIGTERM bundle shutdown that dropped every in-flight request. Late calls now log the swallowed error and no-op. The same guard family covers the HTTP/2 inter-bundle query paths: retry re-entries, late upstream responses, and both 3xx redirect intercepts no longer crash when the originating request has already terminated.
-- **Dev-mode hot-reload memory leak fixed.** The per-request hot-reload eviction cycles retained ~1.8 MB of live heap per request through dead `module.children` references, killing heavily-loaded dev bundles with a heap-limit OOM. Both cycles now prune stale module references after eviction; production mode was never affected.
-- **Inter-bundle proxy Content-Type fix.** `query()` over HTTP/2 no longer re-labels the raw-JSON body it serializes itself with the incoming request's Content-Type — a urlencoded browser POST proxied between bundles no longer corrupts `+`/`%XX` sequences inside JSON string values.
-- **ROADMAP consistency release gate.** Stable publishes now abort when a roadmap row is stale relative to the version being released, alongside the existing README freshness gate.
+- **Released-response crash family completed across the synchronous controller surface (bundle-killing).** Building on the `throwError()` and HTTP/2 query-path guards in 0.5.1, thirteen more synchronous controller APIs — `renderJSON()`, `redirect()`, `store()`, `push()`, `renderStream()`, `pauseRequest()` / `resumeRequest()`, `downloadFromLocal()`, and the request-method / popin / form-rule helpers — no longer crash the bundle when a controller action keeps running after a terminal exit (typically a `redirect()` that lets the middleware chain continue) and then dereferences the already-released request or response. Each now no-ops or notifies through its existing callback/event channel instead of escalating to an `uncaughtException` and a SIGTERM shutdown; live requests are byte-for-byte unaffected.
+- **Exhausted HTTP/2 502 retries now surface a typed error instead of success.** An inter-bundle `self.query()` over HTTP/2 that exhausted its retries against an upstream returning 502 used to hand the Bad Gateway response body to the caller as if it were valid data (a JSON-shaped body was even relabelled `status: 200`). Exhausted 502s now surface `status: 502`, `code: BAD_GATEWAY` to the caller, matching how timeout, stream-error, and premature-close exhaustion are already reported; non-critical queries still swallow it.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -26,6 +26,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q2 2026** | `0.4.0` ✅ | Couchbase v2 removal (BREAKING — SDK v2 connector + session store dropped) · HTTP/2 response trailers · async-job primitive · CSP per-response nonce · `secrets:scan` / `secrets:check` CLI · SQL column-level index coverage — of the items originally targeted here: AI agents (MCP) shipped `0.3.7`, ScyllaDB `0.3.11`, CLI Tier 2 `0.4.1`, the docs offline ZIP is live on the docs site, and the Advanced tutorial · website redesign · Bun investigation moved to `0.5.x` |
 | **Q2 2026** | `0.5.0` ✅ | ESM entry points (dual CJS/ESM `exports` map) · Mixed template engines per bundle (extension-keyed `.njk` / `.swig` dispatch) · Nunjucks Inspector parity — the other items originally targeted here shipped earlier: structured logging (`0.4.5`), Alt-Svc (`0.4.2`), WebSocket over HTTP/2 (`0.4.7`), Inspector production auth (`0.4.0`) |
 | **Q2 2026** | `0.5.1` ✅ | Patch: released-response crash family — late `throwError()` and the HTTP/2 inter-bundle query retry / late-response / redirect-intercept paths no longer kill the bundle · dev-mode hot-reload `module.children` heap leak fixed (OOM under sustained load) · inter-bundle proxy JSON bodies keep their `application/json` label · ROADMAP consistency release gate |
+| **Q2 2026** | `0.5.2` ✅ | Patch: released-response crash family completed across the remaining synchronous controller surface — `renderJSON()` / `redirect()` / `store()` / `push()` / `renderStream()` / request-method + form-rule helpers no longer kill the bundle when called on an already-released response · exhausted HTTP/2 502 retries surface a typed `BAD_GATEWAY` error instead of being consumed as success |
 | **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · CLI Tier 3 (project:move, framework:update, backup/restore, man pages) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
 

package/framework/v0.5.2/VERSION

@@ -0,0 +1 @@
+0.5.2

package/framework/{v0.5.2-alpha.1 → v0.5.2}/core/asset/plugin/dist/vendor/gina/inspector/inspector.js

@@ -2690,7 +2690,7 @@
                 break;
 
             case 'io':
-                // "query → coreapi" → "→ coreapi"
+                // "query → api" → "→ api"
                 name = label.replace(/^query\s*/, '');
                 break;
 

package/framework/{v0.5.2-alpha.1 → v0.5.2}/core/controller/controller.js

@@ -285,7 +285,7 @@ function SuperController(options) {
         // Activated when the Inspector is open locally (_inspectorActive) OR when
         // the request came from a cross-bundle self.query() call with the Inspector
         // header (x-gina-inspector). This ensures QI captures queries on target
-        // bundles (e.g. coreapi) without always-on overhead.
+        // bundles (e.g. an upstream API bundle) without always-on overhead.
         // #INS10 — also enter capture during a prod instrumentation window. Window-only in prod:
         // the x-gina-inspector header path still requires _isDev, so a spoofed header cannot
         // trigger capture in production (only an explicitly-opened window does).
@@ -1341,6 +1341,13 @@ function SuperController(options) {
      * @returns {boolean}
      */
     this.isPopinContext = function() {
+        // #B35 — released-response guard (see getSession, #B31/#B33): a terminal exit
+        // (e.g. redirect-then-continue) nulls local.req; reading local.req.headers here
+        // would crash the bundle (uncaughtException → SIGTERM). A released request is
+        // not a popin context.
+        if ( local.req == null ) {
+            return false;
+        }
         return (
             typeof(local.req.headers['x-gina-popin-id']) != 'undefined'
             || typeof(local.req.headers['x-gina-popin-name']) != 'undefined'
@@ -1820,6 +1827,11 @@ function SuperController(options) {
      */
     var localRequestMethod = null, localRequestMethodParams = null;
     this.setRequestMethod = function(requestMethod, conf) {
+        // #B35 — released-response guard (see getSession): skip on a released request;
+        // reading the request method / routing here would crash the bundle.
+        if ( local.req == null ) {
+            return null;
+        }
         // http/2 case
         if ( /http\/2/i.test(conf.server.protocolShort) ) {
             local.req.headers[':method'] = local.req.method.toUpperCase()
@@ -1848,6 +1860,10 @@ function SuperController(options) {
      * @returns {void}
      */
     this.setRequestMethodParams = function(params) {
+        // #B35 — released-response guard: skip the local.req write on a released request.
+        if ( local.req == null ) {
+            return;
+        }
         localRequestMethodParams = local.req[local.req.method.toLowerCase()] = localRequestMethodParams = params
     }
 
@@ -1858,6 +1874,10 @@ function SuperController(options) {
      * @returns {object}
      */
     this.getRequestMethodParams = function() {
+        // #B35 — released-response guard: return the cached value without dereferencing local.req.
+        if ( local.req == null ) {
+            return localRequestMethodParams;
+        }
         return (localRequestMethodParams) ? localRequestMethodParams : local.req[local.req.method.toLowerCase()]
     }
 
@@ -1976,6 +1996,14 @@ function SuperController(options) {
      * @callback [ next ]
      * */
     this.redirect = function(req, res, next) {
+        // #B37 — released-response guard (see getSession / #B31/#B35/#B36): redirect is
+        // synchronous and reads local.req/local.res throughout; a terminal exit (a prior
+        // redirect, or a render-error path) nulls the triplet, and a second redirect on
+        // the released instance would crash the bundle (uncaughtException → SIGTERM).
+        // Nothing to redirect once the response was already sent/released.
+        if ( local.req == null ) {
+            return;
+        }
         var conf    = self.getConfig();
         var bundle  = conf.bundle;
         var env     = conf.env;
@@ -2626,7 +2654,7 @@ function SuperController(options) {
 // Override for local scope when switching env
 if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
     var ctx = getContext();
-    var envHostname = ctx.gina.config.envConf['coreapi'][ctx.env].hostname;
+    var envHostname = ctx.gina.config.envConf['api'][ctx.env].hostname;
     var re = new RegExp('^'+ envHostname);
     if (!re.test(file.url) ) {
         var urlHostname = file.url.match(/^[a-z]+:\/\/[^/:]+(?::\d+)?/)[0];
@@ -2661,6 +2689,15 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
      **/
     this.downloadFromLocal = function(filename) {
 
+        // #B38 — released-response guard (see #B31): a terminal exit (redirect()/
+        // renderTEXT()/throwError()/a render-error path) nulled the per-request refs.
+        // downloadFromLocal is terminal — it streams a file as the response — so a
+        // released instance means the response is already out; a no-op return is correct
+        // (a live request is unaffected: the guard is skipped while the refs exist).
+        if ( local.res == null ) {
+            return;
+        }
+
         var file            = filename.split(/\//g).pop();
         var ext             = file.split(/\./g).pop()
             , contentType   = null
@@ -2708,6 +2745,18 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                 var cb = arguments[1];
             }
 
+            // #B38 — released-response guard (see #B31): the documented
+            // `store(target).onComplete(cb)` form calls start() SYNCHRONOUSLY from the
+            // returned wrapper, OUTSIDE the async store() body, so on a released request
+            // (the per-request refs nulled by a terminal exit) this is a SIGTERM bundle
+            // kill — not the non-fatal async class. Notify through the same cb / 'uploaded'
+            // channel the empty-upload path uses, then bail.
+            if ( local.req == null ) {
+                var _releasedErr = new Error('Controller::store — response already released');
+                if (cb) { cb(_releasedErr); } else { self.emit('uploaded', _releasedErr); }
+                return;
+            }
+
             if ( typeof(files) == 'undefined' || typeof(files) == 'function' ) {
                 files = local.req.files
             }
@@ -4162,7 +4211,7 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                 if (req.aborted || req.destroyed) {
                     data = { status: 500, error: new Error('Request aborted by client or server') };
                 } else {
-                    // Might be a 204 No Content, but usually CoreAPI should return {}
+                    // Might be a 204 No Content, but usually the upstream bundle should return {}
                     console.warn('[HTTP2] Empty response received');
                     data = { status: 200, empty: true };
                 }
@@ -4184,6 +4233,28 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                     handleHTTP2ClientRequest(browser, options, callback, _502Next, isCritical);
                 }, 2000);
                 return;
+            } else if (httpStatus === 502) {
+                // #B34 — all retries exhausted on a 502: surface it as an error instead of
+                // falling through to the success path (which silently delivered the 502 body
+                // to the caller as `callback(false, data)` / `query#complete(false, data)`,
+                // and for a JSON-shaped body even logged "switching to 200" and forced
+                // data.status = 200). Mirrors the timeout / stream-error / premature-close
+                // exhaustion branches; status 502 is the truthful upstream status (the
+                // GinaHttp2Error JSDoc already lists code BAD_GATEWAY / status 502).
+                var _badGatewayErr = new GinaHttp2Error('[HTTP2] 502 Bad Gateway from '+ options[':authority'] + options[':path'] +' (exhausted '+ HTTP2_MAX_RETRIES +' retries)', {
+                    code       : 'BAD_GATEWAY',
+                    retryable  : false,
+                    status     : 502,
+                    retryCount : retryCount
+                });
+                // H3: if non-critical, swallow and return
+                if (_swallowIfNonCritical(_badGatewayErr)) return;
+                if (typeof callback !== 'undefined') {
+                    callback(_badGatewayErr);
+                } else {
+                    self.emit('query#complete', { status: 502, error: _badGatewayErr });
+                }
+                return;
             }
 
             // 3. Exception filter for ALPN or protocol mismatches
@@ -4236,7 +4307,7 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                         }
                         // #QI — extract upstream query log from the response and
                         // merge into the current request's log. This surfaces
-                        // coreapi queries in the dashboard Inspector automatically.
+                        // upstream-bundle queries in the calling bundle's Inspector automatically.
                         // #INS10 — extract + strip the upstream query sidecar during a prod window too.
                         if (((process.gina && process.gina._inspectorWindowUntil > Date.now()) || _isDev) && data && data.__ginaQueries && local._queryLog) {
                             for (var _qi = 0; _qi < data.__ginaQueries.length; _qi++) {
@@ -4842,6 +4913,11 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
      *
      * */
     this.getFormsRules = function () {
+        // #B35 — released-response guard: no form rules to resolve on a released request
+        // (reading the request's gina headers would crash the bundle).
+        if ( local.req == null ) {
+            return {};
+        }
         var bundle  = local.options.conf.bundle; // by default
         var form    = null;
         var rule    = null;
@@ -4893,6 +4969,14 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
      */
     this.push = function(payload, option, callback) {
 
+        // #B38 — released-response guard (see #B31): push is a fire-and-forget broadcast
+        // over the SSE/engine.io clients; on a released request (per-request refs nulled by
+        // a terminal exit) a no-op return is correct — the response this request would have
+        // pushed to is already gone. Live requests are unaffected (guard skipped).
+        if ( local.req == null ) {
+            return;
+        }
+
         var req = local.req, res = local.res;
         var method  = req.method.toLowerCase();
         // if no session defined, will push to all active clients
@@ -5018,6 +5102,13 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
      */
     this.pauseRequest = function(data, requestStorage) {
 
+        // #B38 — released-response guard (see #B31): pauseRequest snapshots the current
+        // request before a login redirect; on a released request (per-request refs nulled
+        // by a terminal exit) there is nothing to snapshot — a no-op return is correct.
+        // Live requests are unaffected (guard skipped while the refs exist).
+        if ( local.req == null ) {
+            return;
+        }
 
         // saving halted request
         var req             = local.req
@@ -5081,6 +5172,14 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         if (local.haltedRequestUrlResumed)
             return;
 
+        // #B38 — released-response guard (see #B31): resumeRequest replays a halted
+        // request against the live request/response; on a released request (per-request
+        // refs nulled by a terminal exit) there is nothing to replay onto — a no-op return
+        // is correct. Live requests are unaffected (guard skipped while the refs exist).
+        if ( local.req == null ) {
+            return;
+        }
+
         var haltedRequest   = null
             , req           = local.req
             , res           = local.res
@@ -5568,7 +5667,7 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
                 if ( errorObject && errorObject != 'null' && /object/i.test(typeof(errorObject)) ) {
                     // replaced: (errorObject.stack||errorObject.message) — both may be undefined for plain
-                    // object errors forwarded from query() (e.g. coreapi non-2xx). Fall back to serializing
+                    // object errors forwarded from query() (e.g. an upstream non-2xx). Fall back to serializing
                     // errorObject.error so the log always contains the failure reason. (#Q1)
                     // When no stack is present on the error object, capture the throwError callsite so the
                     // log always shows which controller method caused the error. (#Q1)

package/framework/{v0.5.2-alpha.1 → v0.5.2}/core/controller/controller.render-json.js

@@ -154,6 +154,15 @@ module.exports = function renderJSON(jsonObj, deps) {
         return;
     }
 
+    // #B36 — released-response guard: a terminal exit (e.g. redirect-then-continue,
+    // which nulls local.req/res/next then lets the middleware chain continue) leaves
+    // local.res null; the synchronous `local.res.stream` read below would then crash
+    // the bundle (uncaughtException → SIGTERM, the #B31/#B33/#B35 class). There is
+    // nothing to render to a response that was already sent/released.
+    if ( local.res == null ) {
+        return;
+    }
+
     // Using server cache to cache compiledTemplates
     cache.from(self.serverInstance._cached);
     cachePath       = self.serverInstance._cachePath;
@@ -412,7 +421,7 @@ module.exports = function renderJSON(jsonObj, deps) {
             return response.end(data);
         }
         // normal case
-        // E.g.: Caching result for document-get-all@coreapi
+        // E.g.: Caching result for document-get-all@api
         if (
             !self.isCacheless()
             && typeof(request.routing.cache) != 'undefined'

package/framework/{v0.5.2-alpha.1 → v0.5.2}/core/controller/controller.render-stream.js

@@ -42,6 +42,15 @@ module.exports = function renderStream(asyncIterable, contentType, deps) {
     if (local.options.renderingStack.length > 1) return false;
     if (self.isProcessingError) return;
 
+    // #B38 — released-response guard (see #B31 / #B36): a terminal exit (redirect() /
+    // renderTEXT() / throwError()) nulled the per-request refs before this stream began.
+    // renderStream's wrapper and this delegate are BOTH synchronous, so the read below
+    // would throw synchronously → uncaughtException → SIGTERM. The read happens BEFORE the
+    // headersSent() guard further down, so check here — mirrors render-json.js's #B36
+    // placement (after isProcessingError, before the first local.res deref). Behaviour-
+    // neutral on live requests (guard skipped while the refs exist).
+    if (local.res == null) return;
+
     var response = local.res;
     var stream   = (typeof(response.stream) !== 'undefined') ? response.stream : null;
     // #H10 — opt-in HTTP/2 response trailers (registered via self.sendTrailers()).

package/framework/{v0.5.2-alpha.1 → v0.5.2}/core/controller/controller.render-swig.js

@@ -657,7 +657,7 @@ module.exports = async function render(userData, displayInspector, errOptions, d
             var errorObject = {
                 status  : data.page.data.status,
                 // replaced: statusCodes[data.page.data.status] first — always truthy for known
-                // codes, so actual coreapi error reason was always buried. Prioritize the actual
+                // codes, so the actual upstream error reason was always buried. Prioritize the actual
                 // error/message from the upstream response; fall back to generic status label. (#Q1)
                 // Normalized to string before use — upstream objects would otherwise render as
                 // "[object Object]". (#Q2)

package/framework/{v0.5.2-alpha.1 → v0.5.2}/lib/cmd/inspector/help.txt

@@ -35,7 +35,7 @@
 
     gina inspector:open                                  Open for default bundle on port 3100
     gina inspector:open demo @myproject                  Open for bundle "demo" (uses settings.inspector.url if set)
-    gina inspector:open coreapi @myotherproject          Bundle on a project other than @gina
+    gina inspector:open backend @myotherproject          Bundle on a project other than @gina
     gina inspector:open https://local.example.com/api/
                                                          URL target — Inspector SPA opens with that origin
     gina inspector:open --port=3200                      Open for a specific port (embedded)

package/framework/{v0.5.2-alpha.1 → v0.5.2}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.2-alpha.1",
+  "version": "0.5.2-alpha.2",
   "dependencies": {
     "@rhinostone/swig": "^2.7.2",
     "intl-messageformat": "^11.2.4",

package/gna.js

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

package/llms.txt

@@ -410,7 +410,9 @@ Counters are live — no restart required. `activeSessions` is bounded by ≥ 0.
 | `HTTP2_PREFLIGHT_STALE_MS` | 3000 | Session age threshold before pre-flight PING |
 | `HTTP2_PREFLIGHT_DEADLINE_MS` | 1500 | Pre-flight PING timeout |
 
-`GinaHttp2Error` codes: `TIMEOUT`, `PREMATURE_CLOSE`, `STREAM_ERROR`, `ECONNRESET`, `ECONNREFUSED`, `PREFLIGHT_TIMEOUT`, `PREFLIGHT_FAILED`. `ECONNREFUSED` is never retried. `retryCount` tracks attempts; `retriedOnce` is derived from `retryCount > 0`.
+`GinaHttp2Error` codes: `TIMEOUT`, `PREMATURE_CLOSE`, `STREAM_ERROR`, `ECONNRESET`, `ECONNREFUSED`, `BAD_GATEWAY`, `PREFLIGHT_TIMEOUT`, `PREFLIGHT_FAILED`. `ECONNREFUSED` is never retried. `retryCount` tracks attempts; `retriedOnce` is derived from `retryCount > 0`.
+
+**Exhausted retryable errors must SURFACE, never fall through to the success path (#B34, 2026-06-13).** Every retryable failure (timeout / stream-error / premature-close / preflight) builds a typed `GinaHttp2Error` on exhaustion and reports it via `callback(err)` / `emit('query#complete', {status, error})`. The 502 path was the lone exception: its retry guard (`httpStatus === 502 && retryCount < HTTP2_MAX_RETRIES`) was the ONLY consumer of the captured upstream transport status (`httpStatus`), so once retries were spent the guard simply declined and control fell through to normal response handling — `callback(false, data)` — delivering the 502 body to the caller as SUCCESS (a JSON-shaped 502 body even hit the legitimate "undefined body-status → 200" fallback and was relabelled `status: 200`; an HTML 502 page was passed through as the "data"). The bug is the gap between the TRANSPORT status (`httpStatus`, from the `:status` HEADERS frame) and the BODY status (`data.status`, from the JSON payload) — they were never reconciled. Fix: an `else if (httpStatus === 502)` branch surfaces a `BAD_GATEWAY` / `status: 502` `GinaHttp2Error` (truthful upstream status; `_swallowIfNonCritical` still applies). Measured by driving the real `query()` against an always-502 h2c server (both JSON-body and HTML-body variants → success pre-fix, error post-fix). Tests: `controller.test.js §24`.
 
 **GOAWAY logging** — when a cached HTTP/2 session receives a GOAWAY frame, the handler logs `console.warn('[http2] GOAWAY received — errorCode: X, lastStreamID: Y, session: Z')`. `errorCode` distinguishes clean server restarts (0 = NO_ERROR) from protocol errors (e.g. 1 = PROTOCOL_ERROR, 11 = ENHANCE_YOUR_CALM). `lastStreamID` indicates which streams were processed before the GOAWAY.
 
@@ -842,7 +844,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 - **`req.routing.param.<key>` ≠ URL value — use `req.params.<key>`** — `req.routing.param` holds the raw routing config object from `routing.json`. For URL parameter bindings like `"id": ":id"`, the value stored there is the literal placeholder string `":id"`, not the actual URL segment. The actual captured value is in `req.params.id` (always available) and `req.get.id` / `req.delete.id` etc. (method-specific). Static values declared in `param` (e.g. `"code": 302`) ARE correctly available on `req.routing.param.code`. Rule of thumb: use `req.routing.param` only for static metadata, never for captured URL params.
 - **Routing loop cross-route contamination** — `fitsWithRequirements()` mutates `request.params` and `request[method]` during each route comparison. Leftover values from non-matching routes cause `parseRouting` lines 396–407 to inject phantom URL segments, compounding work exponentially. Fix: `req.params = Object.assign({}, _origParams)` + `delete req[method]` before each `compareUrls()`. Never `delete req.params` — `fitsWithRequirements` gates on `typeof(request.params) != 'undefined'`. Never use `JSON.clone` on request state in the routing loop — `Object.assign` is sufficient and safe.
 - **`server.isaac.js:812` initializes `req.params`** — `request.params = {}` and `request.params[0] = url` are set before `handle()` runs. Any code that deletes `req.params` breaks `fitsWithRequirements` which checks `typeof(request.params) != 'undefined'` before setting param values.
-- **internal-bundle `setting-get-one-design` was a latent crash** — `coreapi` routing has `"url": "/settings/get/design/:designId"` with no `requirements` block. Before the `fitsWithRequirements` fix, every GET to that URL threw a 500 TypeError. The fix makes it work correctly. Worth testing that route after the next ff-only merge.
+- **internal-bundle `setting-get-one-design` was a latent crash** — an internal bundle's routing had `"url": "/settings/get/design/:designId"` with no `requirements` block. Before the `fitsWithRequirements` fix, every GET to that URL threw a 500 TypeError. The fix makes it work correctly. Worth testing that route after the next ff-only merge.
 
 129. **`env.json > response.header` config defaults are asymmetric across engines and can collide with framework `setHeader` calls — always trace the full emit chain before claiming a config default reaches the wire.** `core/server.js` (Express engine) reads `conf.server.response.header` into `resHeaders` at L1391 and loops `response.setHeader(h, headerValue)` over each key at L1481-1534 — so any entry in the env.json `response.header` block IS applied on Express. But `core/server.isaac.js` does NOT read `server.response.header` anywhere (grep `serverResponseHeaders` / `server\.response\.header` against `server.isaac.js` returns zero matches) — Isaac builds its headers from the framework's own primitives (`_setPoweredByHeader()` for X-Powered-By, fixed setHeader calls for cache/CORS at the `/_gina/*` handlers), so any env.json `response.header` default is silently ignored on Isaac bundles. Layered on top: framework code that emits its own canonical value via a later `setHeader` call in the Express request lifecycle OVERWRITES whatever env.json set earlier. The combination means an env.json `response.header` config default can look load-bearing in the template while being functionally dead at runtime — applied-then-overwritten on Express, ignored on Isaac. Operator rule: before claiming a `response.header` config key reaches the wire, (a) grep both engines for reads of `server.response.header` (the Isaac silence is the dead-giveaway), and (b) grep for framework `setHeader('<that-key>', ...)` calls that would overwrite. Precedent: 2026-05-17 — the `X-Powered-By: "Gina I/O - v${version}"` env.json default at `core/template/conf/env.json:91` was structurally dead (overwritten by `server.js:2425` on Express, never read on Isaac); dropped in favour of the canonical `Gina/<version>` shape emitted by `server.js:2425` + `_setPoweredByHeader()` and suppressed by `gina.plugins.HidePoweredBy()` middleware + `settings.json > server.hidePoweredBy: true` gate respectively. The handoff that prompted the cleanup had framed the env.json default as a "third emit path that neither plugin nor gate reaches" — wrong in both directions (Express middleware DID remove the overwritten value cleanly; Isaac never read the env.json key at all). Established 2026-05-17.
 
@@ -919,4 +921,4 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 177. **Couchbase connector — install-derived SDK resolution (v2 removed), `connectors.json` semantics, `getCluster()`, dev-mode index reporting** (replaces individual entries #29, #40, #41, #57, #136, #153) — connectors are keyed in `schema/connectors.json` by LOGICAL name (`primary`, `sessionStore`, `cache`, …) with the driver selected by the `connector` enum field (`couchbase`/`mysql`/`postgresql`/`sqlite`/`redis`/`ai`/…) — never introduce a separate `driver` field; the optional `version` field carries a semver range used by `connector:add --driver-version=…` for the npm-install hint. The Couchbase SDK major is derived from the project's INSTALLED `couchbase` npm version — the leading major of `dependencies.couchbase` selects `connector.v<major>.js`, which stamps `conn.sdk = { version: N }` — never from a config key, so migrating SDK majors is a driver bump (`npm install couchbase@^4`), not a config edit. SDK v2 is REMOVED as of 0.4.0: the resolver now throws a clear "SDK v2 is no longer supported — upgrade couchbase@^3/^4" error when the installed major is ≤ 2 or the connector file is missing (previously a silent fallback that crashed later with an opaque MODULE_NOT_FOUND); the v3-vs-v4 split remains for param shaping. Generalises: when a connector's behavior-version derives from an installed dependency rather than config, fail fast once the installed major drops below the supported floor. Couchbase entities expose a public `getCluster()` (on both the model-entity and N1QL-entity prototypes) returning the underlying SDK `Cluster` handle for features the ORM doesn't wrap — chiefly multi-document ACID transactions (`cluster.transactions().run(...)`, needs SDK 3.2+/4.x) — without touching private `_*` internals; it throws a coded `GINA_COUCHBASE_CLUSTER_UNRESOLVED` error when neither connection shape resolves. Dev-mode index reporting: the SDK v4 C++ binding never populates `meta.profile` despite `profile: 'timings'` being sent (confirmed on v4.6.0), so an async `EXPLAIN <statement>` fallback with a per-process per-statement cache supplies the plan instead (the first request for a new statement may show N/A; subsequent requests hit the cache), and `USE KEYS` plans surface as "KV lookup" via `ExpressionScan`/`KeyScan` operator detection. Two historical traps locked by tests: `conn._cluster.query()` must receive the full `queryOptions` object, not the raw params array (the raw form silently dropped `profile`/`scanConsistency`/`adhoc` from every query), and of the connector's two `register()` dispatch paths, Option B (`!_isRegisteredFromProto`) is the ALWAYS-active one — instrumentation or logging added to Option A never executes.
 
-178. **HTTP/2 query paths must tolerate a released response — retry re-entries and late upstream responses run after terminal exits (#B33, 2026-06-12, commit `9c2d802a`).** Terminal exits release the per-request refs, and `redirect()` releases them and THEN calls next(), so an inter-bundle HTTP/2 query can outlive its own request in three measured ways, each previously an uncaughtException → SIGTERM bundle kill: (1) every retry re-entry (the 502/timeout/stream-error/preflight setTimeout paths) re-executes the header-forward prep block, which read the released request's headers — null deref from a timer callback outside all try/catch; (2) a late upstream response's success path calls isHaltedRequest → getSession, which read the released request's session from the stream end handler; (3) a parsed upstream payload claiming a 3xx status routed into the redirect intercepts, which wrote headers to the released response (the emitter-mode intercept uncaught; the callback-mode one contained only via a fragile catch chain). All sites null-guarded: forwards and intercepts no-op on a released request (the same options object travels through retries, so options.headers already carries the attempt-1 values — nothing is lost), getSession reports no session, and the emitter-mode intercept falls through to the query#complete emit so listeners still learn the outcome. Live-request behaviour is byte-identical. Runtime-verified by driving the REAL query() through a standalone controller harness against local h2c servers (six probe modes, crash reproduced pre-fix and clean post-fix per site). Sibling unguarded request-header reads exist in OTHER lifecycle functions (redirect, popin-context detection, render-path authority composition, bundle-status forwards) — they run on the live request lifecycle, are unmeasured for this failure shape, and are deliberately out of scope; the guard pin in the controller test is block-scoped to the fixed functions for exactly that reason.
+178. **HTTP/2 query paths must tolerate a released response — retry re-entries and late upstream responses run after terminal exits (#B33, 2026-06-12, commit `9c2d802a`).** Terminal exits release the per-request refs, and `redirect()` releases them and THEN calls next(), so an inter-bundle HTTP/2 query can outlive its own request in three measured ways, each previously an uncaughtException → SIGTERM bundle kill: (1) every retry re-entry (the 502/timeout/stream-error/preflight setTimeout paths) re-executes the header-forward prep block, which read the released request's headers — null deref from a timer callback outside all try/catch; (2) a late upstream response's success path calls isHaltedRequest → getSession, which read the released request's session from the stream end handler; (3) a parsed upstream payload claiming a 3xx status routed into the redirect intercepts, which wrote headers to the released response (the emitter-mode intercept uncaught; the callback-mode one contained only via a fragile catch chain). All sites null-guarded: forwards and intercepts no-op on a released request (the same options object travels through retries, so options.headers already carries the attempt-1 values — nothing is lost), getSession reports no session, and the emitter-mode intercept falls through to the query#complete emit so listeners still learn the outcome. Live-request behaviour is byte-identical. Runtime-verified by driving the REAL query() through a standalone controller harness against local h2c servers (six probe modes, crash reproduced pre-fix and clean post-fix per site). Sibling unguarded request-header reads exist in OTHER lifecycle functions; the §23 guard pin is block-scoped to the fixed functions for exactly that reason. **Follow-up #B35 (2026-06-13, `714d816f`+next):** the 5 directly-callable SYNCHRONOUS siblings were MEASURED (standalone harness: createTestInstance → renderTEXT() releases the triplet → call → confirmed `uncaughtException`-class crash) and guarded with top-of-function early-returns — `isPopinContext` → false, `setRequestMethod` → null, `setRequestMethodParams` → (void), `getRequestMethodParams` → the cached value, `getFormsRules` → {} (tests `controller.test.js §25`). **#B36 (`c5eaeeb7`+next):** `renderJSON()` is the same shape — its delegate reads `local.res.stream` synchronously before any `headersSent` guard, measured (standalone harness driving the real `render-json.js` delegate: CONTROL live rendered, RELEASE after `renderTEXT()` threw `reading 'stream'`) to crash a released response → SIGTERM; guarded with a top-of-function `if (local.res == null) return` (tests `render-json.test.js §03`). The render-swig / render-nunjucks delegates share the same read but are the NON-FATAL async class (measured 2026-06-13, NOT guarded): their `render()` is `async` and `this.render` returns the delegate promise un-awaited, so a released-instance read rejects → `unhandledRejection` → `gna.js:726` logs it (no SIGTERM). This is the canonical severity-axis example — a SYNCHRONOUS released read (render-json `#B36`, the `#B35` helpers) is a SIGTERM bundle-kill worth guarding; the same read in an ASYNC delegate is a logged unhandledRejection not worth editing the hot render path for. `redirect` GUARDED too (**#B37**, `a03e6f84`+next): measured synchronous, so a released second-call (redirect-then-redirect, or render-error-then-redirect) crashed `reading 'originalMethod'` → SIGTERM; top-of-function `if (local.req == null) return` (tests `controller.test.js §26`). **#B38 (2026-06-13) — the #B37 "SIGTERM class CLOSED" claim was premature: an exhaustive sweep of EVERY synchronous controller surface found SIX more lethal sync residuals, each measured (CONTROL no-throw / RELEASE positive crash, then no-throw post-guard) and guarded top-of-function with the same `if (local.req|res == null) return <default>` shape:** `downloadFromLocal` (`reading 'setHeader'`), the inner `start` of `store` (`reading 'files'` — reached SYNCHRONOUSLY through the documented `store(target).onComplete(cb)` wrapper, which calls `start` OUTSIDE the async `store` body; the #B35 probe had only tried `store('t')`, which returns the wrapper WITHOUT calling `start`, so `store` was wrongly filed as async-deferred here), `renderStream` (`reading 'stream'` — its controller wrapper AND the delegate are both synchronous, and the read precedes the delegate's headersSent guard, mirroring the #B36 render-json placement), `push` (`reading 'method'`), `pauseRequest` (`reading 'url'`), `resumeRequest` (`reading 'session'`/`'method'`) — tests `controller.test.js §27` + `render-stream.test.js §11`. Genuinely document-skipped (measured NON-FATAL, mirroring the render-swig/nunjucks #B36 decision): `downloadFromURL` (its reads sit inside an `async function`, so any throw is a rejected promise → `unhandledRejection`), and the render-path inner fns `setResources` / `getNodeRes` (sync, but invoked ONLY from the async render delegates, so a throw rejects the delegate promise — and the captured-req fix-shape was declined because the captured req is itself null in the released-response case). **Rule: lethality follows the NEAREST async boundary, not the function's own sync/async keyword — a sync read with no async function between it and the dispatcher is a SIGTERM bundle-kill (guard it); the same read reached only through an async function degrades to a logged unhandledRejection (skip it). Probe-asymmetry corollary: "no throw" is NOT proof of safety — feed inputs that actually REACH the deref (`resumeRequest({})` dodged its `req.session` read via an `&&` short-circuit + an early `throwError` return and looked safe until re-measured with a deref-reaching input).**

package/package.json

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

package/schema/app.json

@@ -97,7 +97,7 @@
         },
         "hostname": {
           "type": "string",
-          "description": "Upstream host. Use \"bundle@project\" notation to reference another Gina bundle (e.g. \"coreapi@myproject\")."
+          "description": "Upstream host. Use \"bundle@project\" notation to reference another Gina bundle (e.g. \"api@myproject\")."
         },
         "port": {
           "type": ["string", "number"],

package/framework/v0.5.2-alpha.1/VERSION

@@ -1 +0,0 @@
-0.5.2-alpha.1