gina 0.5.1-alpha.1 → 0.5.1-alpha.3

package/CONVENTIONS.md

@@ -391,6 +391,7 @@ exports.setUp = function(done) {
 - Test names use `[ category ] description` format for grouping
 - Setup guards (`if (initialized) return done()`) prevent re-execution across test suites
 - New unit tests go in `test/core/` with numeric prefix for ordering
+- **Test counts in docs and changelogs are measured, never estimated.** Don't write an "N unit tests" claim before running the test — estimating from section count consistently undercounts (behaviour sections run 10-15 tests, not ~5). The corrective is mechanical: run `node --test test/core/<file>.test.js 2>&1 | tail -10`, copy the `ℹ tests N` line, and write that exact N. Use `TODO_test_count` placeholders in drafts and fill from the actual output before staging.
 
 **Recommendation:**
 Migrate to `node:test` (built-in, Node 18+) for all new test files — `nodeunit` is unmaintained. Do not convert existing tests; add `node:test` tests alongside. The HTTP/2 client mock harness (#UT1) should use `node:test + node:assert` natively.

package/ROADMAP.md

@@ -23,8 +23,8 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q4 2026** | `0.3.8` ✅ | Patch: `npm install -g gina@latest` regression fix — `psl` + `@rhinostone/swig` promoted to top-level deps · install scripts decoupled from framework `lib` registry · helpers preload guarding `lib/logger` ↔ `framework/v*/helpers` circular dep |
 | **Q2 2026** | `0.3.9` ✅ | Consumer-feedback batch (11 framework patches): per-request middleware dispatch isolation · Couchbase 4.x JsonTranscoder · `length` filter null safety · `process.env` mirroring · 6 nunjucks render-pipeline patches (libRef fallback · namespace prefix drop · bundle filter wraps · top-level userData · `data.data` alias · ginaLoader placeholders) · `getAssets` mid-URL `{{ }}` strip-guard anchor |
 | **Q2 2026** | `0.3.10` ✅ | FormValidator HTML5 form-reassociation hardening trilogy (`HTMLFormControlsCollection`-based `bindForm` + `unbindForm` symmetry · radio mutual-exclusion + IDL/attribute reconciliation · `defaultChecked` cache for reset) · `X-Forwarded-Prefix` reverse-proxy path-prefix awareness |
-| **Q4 2026** | `0.4.0` | AI agents (MCP) · ScyllaDB connector · Advanced tutorial · Website redesign · Docs offline ZIP · Bun investigation · Couchbase v2 removal · Trailer support · CLI Tier 2 (bundle/project status, rename, copy, protocol:remove, minions) |
-| **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.3`) |
+| **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`) |
 | **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 |
 
@@ -66,18 +66,18 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | ✅ | **`protocol:remove`** — Revert a bundle to the project's default protocol/scheme by removing its `settings.json` override (no shared `ports*.json` mutation), with `--dry-run` / `--force`. | `0.4.1-alpha.2` | 2026-05-31 |
 | ✅ | **`minion:list`** — List the running bundle child-processes ("minions") of a project, or of every project, grouped by project. `--format=json` supported. | `0.4.1-alpha.2` | 2026-05-31 |
 | ✅ | **`minion:kill`** — Reap a project's running bundle child-processes ("minions") — both pidfile-tracked and `ps`-discovered orphans — with a graceful SIGTERM/SIGKILL escalation and a `--dry-run` preview. | `0.4.1-alpha.2` | 2026-05-31 |
-| 📋 | **`gina --status` / `-t`** — Top-level health check: print whether the framework daemon is running, its version, and active bundle count. Requires adding `--status`/`-t` entries to `aliases.json` and implementing `framework/status.js`. | `0.4.0` | Q4 2026 |
+| 📋 | **`gina --status` / `-t`** — Top-level health check: print whether the framework daemon is running, its version, and active bundle count. Requires adding `--status`/`-t` entries to `aliases.json` and implementing `framework/status.js`. | `0.5.x` | Q4 2026 |
 | ✅ | **`bundle:copy` / `bundle:cp`** — Duplicate a bundle (source files + config) under a new name within the same project, with a word-boundary name rewrite, a fresh full protocol/scheme/env port matrix, and `--dry-run` / `--force`. | `0.4.1-alpha.2` | 2026-05-31 |
 | ✅ | **`project:status`** — Show the running/stopped state of each bundle in a project with PID and port info. | `0.4.1-alpha.2` | 2026-05-30 |
 
-### Tier 3 — `0.5.0`
+### Tier 3 — `0.5.x`
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
-| 📋 | **`project:move`** — Relocate a project's source directory and update all `~/.gina/` registry entries to the new path. Handler is 0 lines. | `0.5.0` | Q1 2027 |
-| 📋 | **`framework:update`** — Self-update the installed Gina framework to the latest (or a specified) version without reinstalling via npm. Handler is 0 lines. | `0.5.0` | Q1 2027 |
-| 📋 | **`project:backup` / `project:restore`** — Archive a project's source, config, and data to a tarball (`backup`), and restore from it (`restore`). Documented in `project/help.txt` as support-only. No handler files exist. | `0.5.0` | Q1 2027 |
-| 📋 | **`framework:man` / `project:man` / `bundle:man`** — Inline CLI manual pages. Mentioned in `framework/help.txt` but no handler files exist for any group. | `0.5.0` | Q1 2027 |
+| 📋 | **`project:move`** — Relocate a project's source directory and update all `~/.gina/` registry entries to the new path. Handler is 0 lines. | `0.5.x` | Q1 2027 |
+| 📋 | **`framework:update`** — Self-update the installed Gina framework to the latest (or a specified) version without reinstalling via npm. Handler is 0 lines. | `0.5.x` | Q1 2027 |
+| 📋 | **`project:backup` / `project:restore`** — Archive a project's source, config, and data to a tarball (`backup`), and restore from it (`restore`). Documented in `project/help.txt` as support-only. No handler files exist. | `0.5.x` | Q1 2027 |
+| 📋 | **`framework:man` / `project:man` / `bundle:man`** — Inline CLI manual pages. Mentioned in `framework/help.txt` but no handler files exist for any group. | `0.5.x` | Q1 2027 |
 
 ---
 
@@ -112,7 +112,7 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | ✅ | **Explicit exports for global helpers** — `getContext`, `setContext`, `_`, `requireJSON` etc. available as explicit `require('gina/gna').getContext` imports alongside the existing global injection. Enables IDE navigation and static analysis. | `0.3.3-alpha.3` | 2026-04-09 |
 | ✅ | **TypeScript declaration files** — `.d.ts` declarations for the public surface: `SuperController`, `EntitySuper`, connector config shapes, `routing.json` schema, `PathObject`, `uuid`, all config file interfaces, `GinaRequest`/`GinaResponse`. No TS migration of internals — just declarations for consumer projects. `package.json` wired with `"types"` and `"typesVersions"`. | `0.3.3-alpha.3` | 2026-04-09 |
 | ✅ | **Auto-generated `types/gna.d.ts` from JSDoc** (#M9) — `script/generate_gna_types.js` reads the `GLOBAL_EXPORTS` inventory from the gna-exports unit test plus the JSDoc on `framework/v*/core/gna.js` and emits `types/gna.d.ts` with one entry per global export. Two npm scripts: `npm run types:gen` regenerates, `npm run types:check` exits non-zero if drifted. A `gna-types-drift.test.js` unit test re-runs the generator in memory on every test pass — the JSDoc on `core/gna.js` is the single source of truth. Closes the #M8 → #M9 loop and removes the hand-written declaration. | `0.3.7-alpha.2` | 2026-04-18 |
-| 📋 | **`gina connector:audit [@project]`** — reads `connectors.json`, maps each declared connector to its npm peer package (`mysql2`, `pg`, `ioredis`, `couchbase`, `openai`, `@anthropic-ai/sdk`, etc.), and runs `npm audit --json` scoped to those packages in the project's `node_modules`. Reports CVEs with severity and fix availability. If `socket` is installed in the project, delegates to it for supply-chain analysis (malware, typosquatting, protestware) instead of `npm audit`. Exit code 1 on any high/critical finding — CI-friendly. Only audits packages actually declared in `connectors.json`, not the full dependency tree. | `0.4.0` | Q4 2026 |
+| 📋 | **`gina connector:audit [@project]`** — reads `connectors.json`, maps each declared connector to its npm peer package (`mysql2`, `pg`, `ioredis`, `couchbase`, `openai`, `@anthropic-ai/sdk`, etc.), and runs `npm audit --json` scoped to those packages in the project's `node_modules`. Reports CVEs with severity and fix availability. If `socket` is installed in the project, delegates to it for supply-chain analysis (malware, typosquatting, protestware) instead of `npm audit`. Exit code 1 on any high/critical finding — CI-friendly. Only audits packages actually declared in `connectors.json`, not the full dependency tree. | `0.5.x` | Q4 2026 |
 
 ### Phase 5 — Future
 
@@ -287,7 +287,7 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | ✅ | **Application-level rapid reset rate limiter** (CVE-2023-44487) — per-session stream creation counter | `0.3.13` | 2026-05-14 | The Isaac HTTP/2 session handler counts new streams in a rolling 1s window per session; over `maxStreamsPerSecond` (default 200) it sends a GOAWAY and closes the session. More targeted than `maxSessionRejectedStreams` (which counts refused streams, not created ones). Configurable via `settings.json` `http2Options.maxStreamsPerSecond`; `/_gina/info` exposes a `rapidResetBlocked` counter. |
 | ✅ | **Trailer support** — `stream.sendTrailers()` + `waitForTrailers: true` | `0.4.0` | 2026-05-22 | Opt-in HTTP/2 response trailers via `self.sendTrailers(fields)`. The render pipeline sets `waitForTrailers` and emits the trailing headers after the body (in the `wantTrailers` event), across all render delegates. Activated only when a controller calls `self.sendTrailers(fields)`; HTTP/1.1 and the no-trailers path are unchanged. For gRPC-style streaming (`grpc-status`) and content-integrity (`Digest`) use cases. |
 | ✅ | **Alt-Svc header** — advertise HTTP/3 availability | `0.4.2` | 2026-06-02 | Set `Alt-Svc: h3=":443"; ma=86400` response header to advertise HTTP/3 (QUIC) availability via a QUIC-capable reverse proxy (nginx, Caddy, Cloudflare). Gina does not need to implement QUIC — just announce it. Opt-in via `settings.server.json`. Native HTTP/3 is out of scope: Node.js has no stable QUIC API, and the standard deployment topology (Gina → proxy → client) already delivers HTTP/3 at the edge. |
-| 📋 | **RFC 9218 Extensible Priorities** — read `Priority: u=N, i` request header | `0.5.0` | Q1 2027 | Use the RFC 9218 priority header to order response writes for multiplexed API clients. Low value for typical HTML page loads; high value for parallel API requests with declared urgency. |
+| 📋 | **RFC 9218 Extensible Priorities** — read `Priority: u=N, i` request header | `0.5.x` | Q1 2027 | Use the RFC 9218 priority header to order response writes for multiplexed API clients. Low value for typical HTML page loads; high value for parallel API requests with declared urgency. |
 | ✅ | **WebSocket over HTTP/2** (RFC 8441 extended CONNECT) — opt-in via `http2Options.enableConnectProtocol` (default off; https and cleartext h2c HTTP/2 bundles). From `onInitialize`, `app.onWebSocket(path, handler)` registers per-path WebSocket handlers; accepted streams arrive as full sessions backed by a built-in dependency-free RFC 6455 codec (auto-pong, timed close handshake, UTF-8 + close-code validation, payload/fragment DoS caps, backpressure passthrough, graceful shutdown drain). Unknown paths are refused with 404, plain CONNECT keeps its 405, and default-off deployments are byte-identical. | `0.4.7` | 2026-06-11 |
 
 ---
@@ -325,7 +325,7 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | --- | --- | --- | --- | --- |
 | ✅ | **`NODE_COMPILE_CACHE` — V8 bytecode startup cache** | `0.2.0` | Q2 2026 | Node.js 22.8+ caches compiled V8 bytecode to disk. Set once at startup — 30–60% faster cold start on subsequent runs with zero code changes to user bundles. No-op on Node < 22.8, so safe to ship unconditionally. |
 | ✅ | **Route radix trie — compile `routing.json` at startup** | `0.3.0-alpha.1` | 2026-04-01 | `lib/routing/src/radix.js` builds a segment-level trie once at startup. O(m) candidate lookup per request (m = segment count). `Set.has()` check skips non-candidates in the `for…in` loop. Internal change — no user-facing API change. |
-| 📋 | **Bun runtime compatibility investigation** | `0.4.0` | Q4 2026 | Prototype Gina under Bun. Two blockers to verify: `require.cache` deletion (dev hot-reload) and `node:http2` completeness. If both pass, Bun gives 3–10x faster startup and meaningful throughput gains. Deliverable: a compatibility report. |
+| 📋 | **Bun runtime compatibility investigation** | `0.5.x` | Q4 2026 | Prototype Gina under Bun. Two blockers to verify: `require.cache` deletion (dev hot-reload) and `node:http2` completeness. If both pass, Bun gives 3–10x faster startup and meaningful throughput gains. Deliverable: a compatibility report. |
 | ✅ | **V8 pointer compression support** | `0.2.0` | Q2 2026 | Node.js built with `--experimental-enable-pointer-compression` (e.g. [node-caged](https://github.com/platformatic/node-caged) or a custom build) delivers ~50% heap memory reduction across all pointer-heavy structures. Gina is pure JS — compatible out of the box. Adds: startup detection + `GINA_V8_POINTER_COMPRESSED` env var, Dockerfile guide with custom build recipe (full-icu + pointer compression), 4 GB ceiling documentation, N-API-only connector policy. |
 
 ---
@@ -370,10 +370,10 @@ Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
-| ✅ | **`services/src/inspector/` standalone bundle** — ~~Rename `services/src/toolbar/` to `services/src/inspector/`~~ (done). **Authenticated WebSocket transport shipped** (`0.4.3-alpha`): the standalone Inspector connects to a bundle's `/_gina/agent` over a WebSocket (`?transport=ws`) as well as SSE — key-authenticated outside dev mode, with an optional `inspector.agent.allowedOrigins` Origin allowlist; it falls back to SSE automatically if the socket can't open. The embedded SPA at `/_gina/inspector/` remains for quick dev-mode access. **Dev auto-start shipped** (`0.4.3-alpha`): a `gina service:start` command plus a dev-only `gna.js server.on('started')` hook auto-start the standalone Inspector via the daemon-free `gina-container` launcher (gated on dev mode + not-already-running; local-only — no-ops in a fresh install since `services/` ships in neither git nor npm). | `0.5.0` | 2026-06-02 |
+| ✅ | **`services/src/inspector/` standalone bundle** — ~~Rename `services/src/toolbar/` to `services/src/inspector/`~~ (done). **Authenticated WebSocket transport shipped** (`0.4.3-alpha`): the standalone Inspector connects to a bundle's `/_gina/agent` over a WebSocket (`?transport=ws`) as well as SSE — key-authenticated outside dev mode, with an optional `inspector.agent.allowedOrigins` Origin allowlist; it falls back to SSE automatically if the socket can't open. The embedded SPA at `/_gina/inspector/` remains for quick dev-mode access. **Dev auto-start shipped** (`0.4.3-alpha`): a `gina service:start` command plus a dev-only `gna.js server.on('started')` hook auto-start the standalone Inspector via the daemon-free `gina-container` launcher (gated on dev mode + not-already-running; local-only — no-ops in a fresh install since `services/` ships in neither git nor npm). | `0.4.3` | 2026-06-02 |
 | ✅ | **Agent endpoint — dev-mode SSE (`/_gina/agent`)** — Combined data + log SSE stream. CORS, server.js + server.isaac.js (HTTP/2), Inspector SPA `tryAgent()` with `?target=` param. Named events (`event: data`, `event: log`). Manual connect form on "No source" overlay. | `0.3.0` | 2026-04-05 |
-| ✅ | **Agent endpoint — production auth** — **Authenticated `/_gina/agent` + production-safe toggle shipped via the existing SSE transport** (opt-in `inspector.agent.enabled` + key in `settings.json`, constant-time compare, `${secret:KEY}`-capable; key via the `x-gina-inspector-key` header or a `?key=` query param; dev stays open + keyless). Authenticates remote server-log streaming outside dev mode. **WebSocket transport completed** (`0.4.3-alpha`): the standalone Inspector now connects over the #INS8 WebSocket by default (`?transport=sse` forces SSE) with automatic SSE fallback; auth + prod-toggle contract unchanged. | `0.5.0` | 2026-06-02 |
-| ✅ | **Toggleable instrumentation** — Runtime toggle for query + flow instrumentation independent of `NODE_ENV_IS_DEV`: a time-boxed, key-authenticated window (`POST /_gina/instrument`) runs capture in production over the authenticated `/_gina/agent` channel, without full dev mode. Opt-in via `inspector.instrumentation`; 3600s hard cap with auto-revert. **v1 shipped 2026-05-26** (JSON/XHR + cross-bundle egress); the server-rendered HTML-page-render egress follow-up also shipped 2026-05-26 (a separate HTML-free emit path wired per render delegate). | `0.5.0` | 2026-05-26 |
+| ✅ | **Agent endpoint — production auth** — **Authenticated `/_gina/agent` + production-safe toggle shipped via the existing SSE transport** (opt-in `inspector.agent.enabled` + key in `settings.json`, constant-time compare, `${secret:KEY}`-capable; key via the `x-gina-inspector-key` header or a `?key=` query param; dev stays open + keyless). Authenticates remote server-log streaming outside dev mode. **WebSocket transport completed** (`0.4.3-alpha`): the standalone Inspector now connects over the #INS8 WebSocket by default (`?transport=sse` forces SSE) with automatic SSE fallback; auth + prod-toggle contract unchanged. | `0.4.0` | 2026-06-02 |
+| ✅ | **Toggleable instrumentation** — Runtime toggle for query + flow instrumentation independent of `NODE_ENV_IS_DEV`: a time-boxed, key-authenticated window (`POST /_gina/instrument`) runs capture in production over the authenticated `/_gina/agent` channel, without full dev mode. Opt-in via `inspector.instrumentation`; 3600s hard cap with auto-revert. **v1 shipped 2026-05-26** (JSON/XHR + cross-bundle egress); the server-rendered HTML-page-render egress follow-up also shipped 2026-05-26 (a separate HTML-free emit path wired per render delegate). | `0.4.0` | 2026-05-26 |
 | 📋 | **Multi-bundle dashboard** — Discover all running bundles via `ports.json`, connect to each agent. Full-stack request tracing across bundle boundaries. | post-1.0.0 | — |
 | 📋 | **Browser extension companion** — Chrome/Firefox DevTools panel. Thin UI shell connecting to the standalone Inspector via WebSocket. Optional — not a replacement. | post-1.0.0 | — |
 
@@ -387,7 +387,7 @@ Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/
 | ✅ | **Beginner — Notes API** — Your first REST API: scaffold a project, define 3 routes in `routing.json`, write synchronous controller actions, read `req.post` / `req.params`, return JSON with `renderJSON()`, handle errors with `throwError()`. In-memory store — no database needed. | ~15 min | `0.3.0` | 2026-04-01 |
 | ✅ | **Tutorial locale detection** — `LocaleSettings` React component detects the reader's locale and timezone via `navigator.language` + `Intl` APIs and pre-fills the `settings.json` scaffold example. Inserted after the scaffold step in both tutorials. Falls back to `en_US`. | — | `0.3.0` | 2026-04-06 |
 | ✅ | **Intermediate — Link Shortener** — SQLite ORM connector, async controller actions, `render()` + `renderJSON()` in same bundle, HTTP 302 redirect, route `requirements` guard. Includes downloadable project ZIP. | ~30 min | `0.3.0` | 2026-04-01 |
-| 📋 | **Advanced** — Full production project: authentication, scoped data isolation, async/await, HTTP/2, structured logging, Docker/K8s deployment. Starts from the intermediate tutorial's finished state. | ~60 min | `0.4.0` | Q4 2026 |
+| 📋 | **Advanced** — Full production project: authentication, scoped data isolation, async/await, HTTP/2, structured logging, Docker/K8s deployment. Starts from the intermediate tutorial's finished state. | ~60 min | `0.5.x` | Q4 2026 |
 
 ---
 
@@ -395,7 +395,7 @@ Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
-| 📋 | **Official website redesign + docs integration** — Refactor gina.io as a proper project homepage (landing page, feature highlights, showcase) with the documentation fully integrated. Single coherent web presence. Prerequisite: tutorials complete. | `0.4.0` | Q4 2026 |
+| 📋 | **Official website redesign + docs integration** — Refactor gina.io as a proper project homepage (landing page, feature highlights, showcase) with the documentation fully integrated. Single coherent web presence. Prerequisite: tutorials complete. | `0.5.x` | Q4 2026 |
 | ✅ | **Docs offline ZIP** — One-click download of the complete gina.io documentation as a static HTML ZIP archive. Generated at deploy time by the Docusaurus build pipeline — no server-side logic required. Targeted at users in regions with limited or expensive internet access (offline-first for the African market). | `0.4.0` | 2026-05-22 |
 | ✅ | **Security & CVE compliance page** — Dedicated docs page listing the HTTP/2 CVEs addressed by Gina and the Node.js version required for each mitigation. Covers CVE-2023-44487 (Rapid Reset), CVE-2024-27316 / CVE-2024-27983 (CONTINUATION flood), CVE-2019-9514 (RST flood), HPACK bomb, and server push abuse. Docs only — no code changes. | `0.3.0-alpha.1` | 2026-04-01 |
 

package/framework/v0.5.1-alpha.3/VERSION

@@ -0,0 +1 @@
+0.5.1-alpha.3

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

@@ -161,12 +161,27 @@ function SuperController(options) {
      * Returns `true` when response headers have already been sent.
      * Checks both HTTP/2 stream and HTTP/1.1 `res.headersSent`.
      *
+     * Also returns `true` when the per-request response refs were already
+     * released by a terminal exit (`local.res` is null) — a released response
+     * can no longer be written to, so callers' `!headersSent()` guards no-op
+     * instead of dereferencing null (#B31).
+     *
      * @inner
      * @param {object} [res] - Defaults to `local.res`
      * @returns {boolean}
      */
     var headersSent = function(res) {
         var _res = ( typeof(res) != 'undefined' ) ? res : local.res;
+        // #B31 — the per-request response refs may already be released (the
+        // terminal-exit triplet: redirect()/renderTEXT()/throwError() and the
+        // render delegates set local.res = null once the response is out). A
+        // released response cannot be written to anymore, so report it as
+        // "sent": callers' existing !headersSent() guards then no-op instead
+        // of throwing `Cannot read properties of null (reading 'stream')` —
+        // an uncaughtException that proc.js escalates to SIGTERM (bundle kill).
+        if ( !_res ) {
+            return true;
+        }
         if (
             typeof(_res.stream) != 'undefined'
             && typeof(_res.stream.headersSent) != 'undefined'
@@ -3303,11 +3318,11 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 		// proxy_set_header X-Ingress-IP $server_addr
 		// proxy_set_header X-Forwarded-For $remote_addr;
 		// # EO - Specific headers for Gina
-        if ( typeof(local.req.headers['x-client-ip']) != 'undefined' && local.req.headers['x-client-ip'] != options.headers['x-client-ip'] ) {
+        if ( local.req != null && typeof(local.req.headers['x-client-ip']) != 'undefined' && local.req.headers['x-client-ip'] != options.headers['x-client-ip'] ) {
             options.headers['x-client-ip'] = local.req.headers['x-client-ip']
         }
 
-        if ( typeof(local.req.headers['x-ingress-ip']) != 'undefined' && local.req.headers['x-ingress-ip'] != options.headers['x-ingress-ip'] ) {
+        if ( local.req != null && typeof(local.req.headers['x-ingress-ip']) != 'undefined' && local.req.headers['x-ingress-ip'] != options.headers['x-ingress-ip'] ) {
             options.headers['x-ingress-ip'] = local.req.headers['x-ingress-ip']
         }
 
@@ -3844,15 +3859,29 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         } = browser.constants;
 
 
-        if ( typeof(local.req.headers['x-requested-with']) != 'undefined' ) {
+        // #B33 — every retry re-entry (setTimeout → handleHTTP2ClientRequest) re-executes
+        // these forwards, and a terminal exit (e.g. redirect-then-continue) may have
+        // released local.req in between: each forward is null-guarded with query()'s own
+        // idiom. Skipping a forward on a released request is a no-op, not a behavior
+        // change — options.headers already carries the attempt-1 values (the same options
+        // object travels through every retry).
+        if ( local.req != null && typeof(local.req.headers['x-requested-with']) != 'undefined' ) {
             options.headers['x-requested-with'] = local.req.headers['x-requested-with']
         }
 
-        if ( typeof(local.req.headers['access-control-allow-credentials']) != 'undefined' ) {
+        if ( local.req != null && typeof(local.req.headers['access-control-allow-credentials']) != 'undefined' ) {
             options.headers['access-control-allow-credentials'] = local.req.headers['access-control-allow-credentials']
         }
 
-        if ( typeof(local.req.headers['content-type']) != 'undefined' && local.req.headers['content-type'] != options.headers['content-type'] ) {
+        // #FORMCT2 — never clobber an `application/json` outbound Content-Type with the
+        // INCOMING request's. query() serializes the inter-bundle body as raw JSON
+        // (queryData = JSON.stringify) and labels it application/json; forwarding the
+        // incoming CT here re-labels that JSON body (e.g. as urlencoded when the browser
+        // request was a plain form POST — canonical case: a haltedRequest resume), and the
+        // receiving bundle's urlencoded parse then corrupts `+`/`%XX` inside JSON string
+        // values (same corruption #FORMCT fixed in the browser validator). The forward is
+        // kept for non-JSON outbound bodies (e.g. the MSIE text/plain override).
+        if ( local.req != null && typeof(local.req.headers['content-type']) != 'undefined' && local.req.headers['content-type'] != options.headers['content-type'] && !/application\/json/i.test(options.headers['content-type']) ) {
             options.headers['content-type'] = local.req.headers['content-type']
         }
 
@@ -3862,11 +3891,11 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 		// proxy_set_header X-Ingress-IP $server_addr
 		// proxy_set_header X-Forwarded-For $remote_addr;
 		// # EO - Specific headers for Gina
-        if ( typeof(local.req.headers['x-client-ip']) != 'undefined' && local.req.headers['x-client-ip'] != options.headers['x-client-ip'] ) {
+        if ( local.req != null && typeof(local.req.headers['x-client-ip']) != 'undefined' && local.req.headers['x-client-ip'] != options.headers['x-client-ip'] ) {
             options.headers['x-client-ip'] = local.req.headers['x-client-ip']
         }
 
-        if ( typeof(local.req.headers['x-ingress-ip']) != 'undefined' && local.req.headers['x-ingress-ip'] != options.headers['x-ingress-ip'] ) {
+        if ( local.req != null && typeof(local.req.headers['x-ingress-ip']) != 'undefined' && local.req.headers['x-ingress-ip'] != options.headers['x-ingress-ip'] ) {
             options.headers['x-ingress-ip'] = local.req.headers['x-ingress-ip']
         }
 
@@ -4183,7 +4212,10 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
                 try {
                     // Intercepting fallback redirect (3xx)
-                    if (data.status && /^3/.test(data.status) && typeof data.headers !== 'undefined') {
+                    // #B33 — local.res may be null when the response lands after a terminal
+                    // exit released the triplet; skip the intercept and fall through to the
+                    // non-2xx handling (whose throwError no-ops on a released response).
+                    if (local.res != null && data.status && /^3/.test(data.status) && typeof data.headers !== 'undefined') {
                         local.res.writeHead(data.status, data.headers);
                         return local.res.end();
                     }
@@ -4255,7 +4287,10 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                     }
                 }
 
-                if (data.status && /^3/.test(data.status) && typeof data.headers !== 'undefined') {
+                // #B33 — same released-response skip as the callback-mode intercept above;
+                // emitter mode falls through to the query#complete emit so listeners
+                // still learn the outcome.
+                if (local.res != null && data.status && /^3/.test(data.status) && typeof data.headers !== 'undefined') {
                     self.removeAllListeners(['query#complete']);
                     local.res.writeHead(data.status, data.headers);
                     return local.res.end();
@@ -4922,6 +4957,12 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
     var getSession = function() {
         var session = null;
+        // #B33 — local.req is null after a terminal exit released the triplet; callers
+        // like isHaltedRequest() run from HTTP/2 response handlers that can fire on a
+        // released request (retry/late-response paths). No session on a released request.
+        if ( local.req == null ) {
+            return null;
+        }
         if ( typeof(local.req.session) != 'undefined') {
             session = local.req.session;
         }
@@ -5266,11 +5307,17 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
      *   - `throwError(code, err)` — 2-arg form: HTTP status + Error|string
      *   - `throwError(res, code, msg)` — internal 3-arg form used by the router
      *
+     * Late calls: when throwError fires after a response terminal exit has
+     * already released the per-request refs (`local.res` is null — e.g. an
+     * entity/query callback resuming after a redirect() sent its 301), the
+     * call is logged and ignored instead of crashing the bundle (#B31).
+     *
      * @param {object} [ res ]
      * @param {number} code
      * @param {string} msg
      *
-     * @returns {void}
+     * @returns {void|boolean} `false` when the call is ignored (nested
+     *          rendering stack, or a late call on a released response)
      * */
     this.throwError = function(res, code, msg) {
 
@@ -5388,6 +5435,32 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         }
 
         var responseHeaders = null;
+        // #B31 — a late throwError (an entity/query callback, timer or catch
+        // handler resuming after the action already responded) can fire AFTER
+        // a terminal exit (redirect()/render*()/a previous throwError) released
+        // local.req/res/next. Every call shape above has normalized `res` to
+        // local.res by this point, so a null `res` means the response is gone:
+        // reading getHeaders off it threw `Cannot read properties of null
+        // (reading 'getHeaders')` — an uncaughtException that proc.js escalates
+        // to SIGTERM, killing the bundle and every in-flight request with it
+        // (same crash class as #B30: fix the throw site, never widen the
+        // uncaughtException net). Log the swallowed error so the late failure
+        // stays observable, then no-op — same return contract as the
+        // renderingStack guard above.
+        if ( !res ) {
+            res = local.res;
+        }
+        if ( !res ) {
+            var _lateError = errorObject || msg || code;
+            var _lateErrorStr = '';
+            try {
+                _lateErrorStr = ( _lateError && typeof(_lateError) == 'object' ) ? JSON.stringify(_lateError) : String(_lateError || '');
+            } catch (_lateJsonErr) {
+                _lateErrorStr = String(_lateError);
+            }
+            console.warn('[ Controller ] throwError() called after the response was released — ignoring late error: '+ _lateErrorStr);
+            return false;
+        }
         if ( typeof(res.getHeaders) == 'undefined' && typeof(res.stream) != 'undefined' ) {
             responseHeaders = res.stream.sentHeader;
         } else {

package/framework/{v0.5.1-alpha.1 → v0.5.1-alpha.3}/core/router.js

@@ -129,9 +129,38 @@ function Router(env, scope) {
         SuperController = require(_(corePath +'/controller/index.js', true));
 
         if (_hotReload) _hotReload.core = false; // #M6 — clear flag after eviction
+
+        pruneDeadModuleChildren();
         corePath = null;
     }
 
+    /**
+     * Prunes stale `Module` references from every cached module's `children`
+     * array after the eviction cycle above. Each cache-miss `require()` pushes
+     * the fresh `Module` onto the requiring module's `children` (Node only
+     * dedupes on cache hits), so without pruning this long-lived router module
+     * accumulates one dead controller `Module` per request, each pinning its
+     * whole evaluated exports graph — the dev-mode per-request memory leak.
+     *
+     * Local copy of the sweep in `core/server.isaac.js` — the engine-agnostic
+     * router cannot depend on an engine module, and the `lib` registry is
+     * itself evicted per request. Keep both copies in sync.
+     *
+     * @inner
+     * @returns {undefined}
+     */
+    var pruneDeadModuleChildren = function() {
+        var cacheIds = Object.keys(require.cache);
+        for (var i = 0, len = cacheIds.length; i < len; i++) {
+            var cached = require.cache[cacheIds[i]];
+            if (cached && cached.children && cached.children.length > 0) {
+                cached.children = cached.children.filter(function onPruneFilter(child) {
+                    return require.cache[child.id] === child;
+                });
+            }
+        }
+    }
+
     this.setServerInstance = function(serverInstance) {
         serverInstance._http2streamEventInitalized = false;
         self.serverInstance = serverInstance;

package/framework/{v0.5.1-alpha.1 → v0.5.1-alpha.3}/core/server.isaac.js

@@ -243,8 +243,48 @@ var refreshCore = function() {
     delete require.cache[require.resolve(pluginsIndexPath)];
     var freshPlugins = require( pluginsIndexPath );
     require.cache[_(corePath + '/gna.js', true)].exports.plugins = freshPlugins;
+
+    pruneDeadModuleChildren();
 }
 
+/**
+ * Prunes stale `Module` references from every cached module's `children` array.
+ *
+ * Each cache-miss `require()` pushes the freshly created `Module` onto the
+ * requiring module's `children` array — Node only dedupes on cache hits — so the
+ * per-request delete-and-re-require cycles in `refreshCore()` (and the router's
+ * `refreshCoreDependencies()`) make long-lived parents accumulate one dead
+ * `Module` per eviction: this engine module, `router.js`, and any module with a
+ * lazy in-function `require()` of an evicted lib. Every dead `Module` pins its
+ * entire evaluated exports graph. Measured on a minimal bundle in dev mode:
+ * ~1.8 MB of post-GC live heap retained per request, ending in a heap-limit
+ * OOM (SIGABRT) at ~2400 requests.
+ *
+ * Keeping only children whose resolved id still maps to that same instance in
+ * `require.cache` releases the dead graphs. `children` is diagnostic metadata
+ * (nothing in Node's resolution reads it), so pruning never unloads a module
+ * still referenced elsewhere.
+ *
+ * A local copy of the same sweep lives in `core/router.js` — the engine-agnostic
+ * router cannot depend on an engine module, and the `lib` registry is itself
+ * evicted per request. Keep both copies in sync.
+ *
+ * @memberof module:gina/core/server.isaac
+ * @inner
+ * @returns {undefined}
+ */
+var pruneDeadModuleChildren = function() {
+    var cacheIds = Object.keys(require.cache);
+    for (var i = 0, len = cacheIds.length; i < len; i++) {
+        var cached = require.cache[cacheIds[i]];
+        if (cached && cached.children && cached.children.length > 0) {
+            cached.children = cached.children.filter(function onPruneFilter(child) {
+                return require.cache[child.id] === child;
+            });
+        }
+    }
+};
+
 // Express compatibility
 const slice = Array.prototype.slice;
 

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

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.1-alpha.1",
+  "version": "0.5.1-alpha.3",
   "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.1-alpha.1/core/gna');
+var _gna = require('./framework/v0.5.1-alpha.3/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.5.1-alpha.1/core/controller');
-var EntitySuper     = require('./framework/v0.5.1-alpha.1/core/model/entity');
+var SuperController = require('./framework/v0.5.1-alpha.3/core/controller');
+var EntitySuper     = require('./framework/v0.5.1-alpha.3/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.5.1-alpha.1/lib/uuid');
+var uuid = require('./framework/v0.5.1-alpha.3/lib/uuid');
 
 module.exports = {