gina 0.5.1-alpha.1 → 0.5.1-alpha.2

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.2/VERSION

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

package/framework/{v0.5.1-alpha.1 → v0.5.1-alpha.2}/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'
@@ -5266,11 +5281,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 +5409,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.2}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.1-alpha.1",
+  "version": "0.5.1-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.1-alpha.1/core/gna');
+var _gna = require('./framework/v0.5.1-alpha.2/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.2/core/controller');
+var EntitySuper     = require('./framework/v0.5.1-alpha.2/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.2/lib/uuid');
 
 module.exports = {
 

package/package.json

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

package/script/check_roadmap_consistency.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+/*
+ * This file is part of the gina package.
+ * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * @file script/check_roadmap_consistency.js
+ *
+ * Pre-publish guard that asserts ROADMAP.md does not contradict the
+ * stable version being released. Wired into prepare_version.js as
+ * `self.checkRoadmapConsistency`, between `checkReadmeFreshness` and
+ * `checkDefFrameworkConsistency`. Also runnable standalone:
+ *
+ *   node script/check_roadmap_consistency.js
+ *
+ * The check fires on stable publishes only — alpha cuts are intermediate
+ * and never make a roadmap row stale (rows reference stable versions or
+ * `X.Y.x` buckets). The skip is signalled via the `npm_config_tag` env
+ * var or `--tag=alpha` on the argv, mirroring check_readme_freshness.js.
+ *
+ * Three rules, scanned over status rows (lines starting `| 📋 |` or
+ * `| ✅ |`) and exact backtick-wrapped version tokens:
+ *
+ *   1. ABORT — an open (📋) row references the exact version being
+ *      released. The release is about to ship without that item, so the
+ *      row becomes a lie the moment the tag lands. Re-target the row
+ *      (e.g. to the `X.Y.x` bucket) or reword the prose reference.
+ *      Bucket tokens (`0.5.x`) never trip this rule by design — they
+ *      are the sanctioned re-target form.
+ *
+ *   2. ABORT — a done (✅) row references a version NEWER than the one
+ *      being released. A feature cannot have shipped in a version that
+ *      does not exist yet; this catches target-version labels left on
+ *      rows that were flipped to ✅ before the cut. Only tokens sharing
+ *      the released version's MAJOR are compared, so dependency
+ *      versions in prose (e.g. a `2.x` template-engine floor or a
+ *      two-digit uuid major) cannot false-positive.
+ *
+ *   3. WARN — no timeline row marks the released version ✅
+ *      (`` `X.Y.Z` ✅ ``). The timeline is coarse narrative, so this is
+ *      advisory only and never aborts.
+ *
+ * Why this gate exists: a roadmap-accuracy sweep (2026-06-12) found two
+ * recurring drift classes that had survived multiple cuts — ✅ rows
+ * carrying their old TARGET version instead of the actual ship version
+ * (readers were told a feature needed `0.5.0` when `0.4.0` sufficed),
+ * and 📋 rows still targeting versions that had shipped without them
+ * (ten rows across `0.4.0`/`0.5.0`). Both are facts that only become
+ * checkable at cut time, and manual checklist steps decay (see the
+ * README-freshness precedent). This enforces them automatically.
+ *
+ * Failure mode: fail-closed on rules 1-2 (abort the publish with the
+ * offending rows listed). A missing or unreadable ROADMAP.md also
+ * aborts — investigate rather than publish with unverified state.
+ */
+
+'use strict';
+
+var fs = require('fs');
+var nodePath = require('path');
+
+/**
+ * Regex for an exact backtick-wrapped version token: `X.Y.Z` with an
+ * optional `-alpha.N` suffix. Deliberately does NOT match:
+ *   - bucket tokens (`0.5.x`) — the sanctioned open-row re-target form;
+ *   - range-prefixed tokens (`^2.3.0`, `~1.2.0`) — dependency floors;
+ *   - bare (un-backticked) versions in prose — too noisy to police.
+ *
+ * @constant {RegExp}
+ */
+var VERSION_TOKEN_RE = /`(\d+\.\d+\.\d+(?:-alpha\.\d+)?)`/g;
+
+/**
+ * Regex matching a status row of any roadmap table — a markdown table
+ * line whose first cell is the 📋 (open) or ✅ (done) marker.
+ *
+ * @constant {RegExp}
+ */
+var STATUS_ROW_RE = /^\|\s*(📋|✅)\s*\|/;
+
+/**
+ * Extract every exact backtick-wrapped version token from a line.
+ *
+ * @param {string} line  one roadmap line
+ * @returns {string[]} version strings without backticks (may be empty)
+ * @example
+ * extractVersionTokens('| ✅ | x | `0.4.0` | 2026-05-29 |'); // ['0.4.0']
+ * extractVersionTokens('floor `^2.3.0` and bucket `0.5.x`'); // []
+ */
+function extractVersionTokens(line) {
+    var out = [];
+    var m;
+    VERSION_TOKEN_RE.lastIndex = 0;
+    while ((m = VERSION_TOKEN_RE.exec(line || '')) !== null) {
+        out.push(m[1]);
+    }
+    return out;
+}
+
+/**
+ * Compare two version strings of the `X.Y.Z[-alpha.N]` shape.
+ * A prerelease sorts BEFORE its stable (`0.5.0-alpha.2` < `0.5.0`).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} -1 when a < b, 0 when equal, 1 when a > b
+ * @example
+ * compareVersions('0.5.1', '0.5.0');         // 1
+ * compareVersions('0.5.0-alpha.1', '0.5.0'); // -1
+ */
+function compareVersions(a, b) {
+    var pa = String(a).split('-');
+    var pb = String(b).split('-');
+    var na = pa[0].split('.').map(Number);
+    var nb = pb[0].split('.').map(Number);
+    for (var i = 0; i < 3; i++) {
+        if ((na[i] || 0) > (nb[i] || 0)) return 1;
+        if ((na[i] || 0) < (nb[i] || 0)) return -1;
+    }
+    // numeric cores equal — a bare version outranks its prereleases
+    if (!pa[1] && pb[1]) return 1;
+    if (pa[1] && !pb[1]) return -1;
+    if (!pa[1] && !pb[1]) return 0;
+    var aa = Number((pa[1].match(/\d+$/) || [0])[0]);
+    var ab = Number((pb[1].match(/\d+$/) || [0])[0]);
+    if (aa > ab) return 1;
+    if (aa < ab) return -1;
+    return 0;
+}
+
+/**
+ * Parse the roadmap content into status rows.
+ *
+ * @param {string} content  full ROADMAP.md content
+ * @returns {Array<{status: string, lineNo: number, line: string, versions: string[]}>}
+ */
+function parseStatusRows(content) {
+    var rows = [];
+    var lines = String(content || '').split('\n');
+    for (var i = 0; i < lines.length; i++) {
+        var m = lines[i].match(STATUS_ROW_RE);
+        if (!m) continue;
+        rows.push({
+            status: m[1],
+            lineNo: i + 1,
+            line: lines[i],
+            versions: extractVersionTokens(lines[i])
+        });
+    }
+    return rows;
+}
+
+/**
+ * Run the full consistency check over a roadmap content string.
+ * Pure function — callers supply the content and the targeted version,
+ * so tests need no filesystem.
+ *
+ * @param {object} opts
+ * @param {string} opts.roadmapContent   full ROADMAP.md content
+ * @param {string} opts.targetedVersion  stable version being released (e.g. "0.5.0")
+ * @returns {{ok: boolean, failures: Array<{rule: string, lineNo: number, excerpt: string}>, warnings: string[]}}
+ */
+function check(opts) {
+    opts = opts || {};
+    var content = opts.roadmapContent;
+    var version = opts.targetedVersion;
+    var failures = [];
+    var warnings = [];
+    var targetMajor = Number(String(version).split('.')[0]);
+
+    var rows = parseStatusRows(content);
+    for (var i = 0; i < rows.length; i++) {
+        var row = rows[i];
+        for (var v = 0; v < row.versions.length; v++) {
+            var token = row.versions[v];
+            if (row.status === '📋' && token === version) {
+                failures.push({
+                    rule: 'open-row-references-released-version',
+                    lineNo: row.lineNo,
+                    excerpt: row.line.substring(0, 120)
+                });
+                break;
+            }
+            if (row.status === '✅'
+                && Number(token.split('.')[0]) === targetMajor
+                && compareVersions(token, version) > 0
+            ) {
+                failures.push({
+                    rule: 'done-row-references-future-version',
+                    lineNo: row.lineNo,
+                    excerpt: row.line.substring(0, 120)
+                });
+                break;
+            }
+        }
+    }
+
+    // Rule 3 (warn-only): a timeline row should mark the release — `X.Y.Z` ✅
+    var timelineMark = new RegExp('`' + String(version).replace(/\./g, '\\.') + '`\\s*✅');
+    if (!timelineMark.test(String(content || ''))) {
+        warnings.push('no timeline row marks `' + version + '` as released (`' + version + '` ✅) — coarse narrative only, not blocking');
+    }
+
+    return { ok: failures.length === 0, failures: failures, warnings: warnings };
+}
+
+/**
+ * True when this invocation is part of an alpha publish. Mirrors
+ * check_readme_freshness.js — `npm_config_tag` env var with an argv
+ * fallback for direct script invocations.
+ *
+ * @returns {boolean}
+ */
+function isAlphaPublish() {
+    if (process.env.npm_config_tag === 'alpha') return true;
+    var argv = process.argv || [];
+    for (var i = 0; i < argv.length; i++) {
+        if (argv[i] === '--tag=alpha' || argv[i] === '--alpha') return true;
+        if (argv[i] === '--tag' && argv[i + 1] === 'alpha') return true;
+    }
+    return false;
+}
+
+/**
+ * CLI entry. Reads ROADMAP.md and the targeted version from the repo at
+ * cwd (or the path given as the first positional argv). Returns 0 on
+ * success, 1 on failure.
+ *
+ * @returns {number} exit code
+ */
+function main() {
+    if (isAlphaPublish()) {
+        console.log('[roadmap] Alpha publish — skipping roadmap consistency gate.');
+        return 0;
+    }
+
+    var root = process.argv[2] && process.argv[2].indexOf('--') !== 0
+        ? process.argv[2]
+        : process.cwd();
+
+    var content, version;
+    try {
+        content = fs.readFileSync(nodePath.join(root, 'ROADMAP.md'), 'utf8');
+        version = JSON.parse(fs.readFileSync(nodePath.join(root, 'package.json'), 'utf8')).version;
+    } catch (err) {
+        console.error('[roadmap] ERROR: could not read ROADMAP.md / package.json: ' + (err.message || err));
+        return 1;
+    }
+
+    var result = check({ roadmapContent: content, targetedVersion: version });
+
+    for (var w = 0; w < result.warnings.length; w++) {
+        console.warn('[roadmap] WARN: ' + result.warnings[w]);
+    }
+
+    if (result.ok) {
+        console.log('[roadmap] OK: ROADMAP.md is consistent with releasing ' + version + '.');
+        return 0;
+    }
+
+    console.error('[roadmap] ERROR: ROADMAP.md contradicts releasing ' + version + ' — aborting publish.');
+    for (var f = 0; f < result.failures.length; f++) {
+        var fail = result.failures[f];
+        console.error('  [' + fail.rule + '] line ' + fail.lineNo + ': ' + fail.excerpt);
+    }
+    console.error('');
+    console.error('  Fix shape:');
+    console.error('    - open (📋) row naming ' + version + ': re-target it (e.g. to the `X.Y.x` bucket) or reword the reference;');
+    console.error('    - done (✅) row naming a version newer than ' + version + ': stamp the actual ship version.');
+    console.error('  Then commit on develop and re-run npm publish.');
+    return 1;
+}
+
+module.exports = {
+    extractVersionTokens: extractVersionTokens,
+    compareVersions: compareVersions,
+    parseStatusRows: parseStatusRows,
+    check: check,
+    isAlphaPublish: isAlphaPublish,
+    main: main
+};
+
+if (require.main === module) {
+    process.exit(main());
+}

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

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