gina 0.4.6 → 0.4.7

package/framework/v0.4.7/lib/ws-session/src/main.js

@@ -0,0 +1,422 @@
+/**
+ * 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.
+ */
+
+/**
+ * @module gina/lib/ws-session
+ *
+ * WebSocket-over-HTTP/2 session bridge (RFC 8441 §5: the extended-CONNECT
+ * stream is used "as if it were the TCP connection" of RFC 6455).
+ *
+ * Responsibilities:
+ *  - `accept(request)`: answer the extended CONNECT with `:status 200` on the
+ *    raw Http2Stream and wrap the stream + a `lib/ws-framing` parser into a
+ *    {@link WsSession} with a send / ping / close API.
+ *  - Protocol housekeeping: auto-pong (§5.5.2), close-handshake echo and a
+ *    timed initiated close (§5.5.1 / §7), protocol violations answered with
+ *    the prescribed status code then torn down.
+ *  - Lifecycle: teardown on stream `close` / `error` / `aborted` (the HTTP/2
+ *    analogs of TCP close/RST per RFC 8441 §5), and registration into the
+ *    framework's graceful-shutdown drain registry
+ *    (`process.gina._sseConnections`) so SIGTERM closes live sessions with a
+ *    `1001 going away` instead of blocking the server drain.
+ *  - Containment: consumer callbacks and transport writes are guarded —
+ *    nothing thrown by a handler or a dying stream escalates to an
+ *    uncaughtException (which would take the whole bundle down).
+ *
+ * Out of scope (by design):
+ *  - Frame parsing/building rules — `lib/ws-framing` owns RFC 6455 §5/§7/§8.
+ *  - The extended-CONNECT detection and refusal table — the Isaac engine owns
+ *    those; this module only ever sees an already-accepted websocket stream.
+ *  - Authentication — the consumer decides from the request it is handed.
+ *
+ * @example
+ *  // from a bundle's onInitialize (app is the raw HTTP/2 server):
+ *  app.onWebSocket('/live', function(session, request) {
+ *      session.onMessage(function(data, isBinary) { session.send('echo: ' + data); });
+ *      session.onClose(function(code, reason) { ... });
+ *  });
+ */
+
+var wsf = require('../../ws-framing/src/main');
+
+/** @private no-op default handler */
+function noop() {}
+
+/**
+ * Session options.
+ *
+ * @typedef {object} WsSessionOptions
+ * @property {number}  [maxPayload] - forwarded to the ws-framing parser (§10.4 cap)
+ * @property {number}  [maxFragments] - forwarded to the ws-framing parser (§10.4 cap)
+ * @property {number}  [closeTimeout=5000] - ms to wait for the peer's Close frame after an initiated close before force-ending the stream
+ * @property {boolean} [autoPong=true] - answer inbound PINGs automatically (§5.5.2)
+ * @property {string}  [protocol] - subprotocol to echo in the `sec-websocket-protocol` response header
+ */
+
+/**
+ * One live WebSocket-over-HTTP/2 session. Construct via
+ * {@link module:gina/lib/ws-session~accept} — never directly.
+ *
+ * Consumer callbacks are registered with the chainable `onMessage` /
+ * `onPing` / `onPong` / `onClose` / `onError` setters. `onClose` is the
+ * single TERMINAL event (normal close, protocol failure, or transport
+ * teardown — exactly once); `onError` is diagnostic and may precede it.
+ *
+ * @class
+ * @constructor
+ * @param {object} stream - the raw Http2Stream of the accepted extended CONNECT
+ * @param {WsSessionOptions} [options]
+ */
+function WsSession(stream, options) {
+    options = options || {};
+    var self = this;
+
+    /** @private */
+    this._stream = stream;
+    /** @private @type {number} */
+    this._closeTimeout = (typeof options.closeTimeout === 'number' && options.closeTimeout > 0)
+        ? options.closeTimeout
+        : 5000;
+    /** @private @type {boolean} */
+    this._autoPong = options.autoPong !== false;
+    /** @private consumer callbacks (chainable setters below) */
+    this._handlers = { message: noop, ping: noop, pong: noop, close: noop, error: noop, drain: noop };
+    /** @private @type {boolean} a Close frame has been written to the wire */
+    this._closeSent = false;
+    /** @private @type {boolean} the terminal onClose has been delivered */
+    this._finished = false;
+    /** @private @type {object|null} */
+    this._closeTimer = null;
+    /** @private graceful-shutdown drain callback registered on process.gina._sseConnections */
+    this._shutdownCloser = function() {
+        try { self.close(1001, 'server shutting down'); } catch (err) { /* already torn down */ }
+    };
+
+    /** @private the per-connection RFC 6455 parser */
+    this._parser = wsf.createParser({
+        maxPayload   : options.maxPayload,
+        maxFragments : options.maxFragments,
+        isServer     : true,
+        onMessage : function(data, isBinary) {
+            self._invoke('message', data, isBinary);
+        },
+        onPing : function(payload) {
+            if (self._autoPong) {
+                self._write(wsf.encodePong(payload));
+            }
+            self._invoke('ping', payload);
+        },
+        onPong : function(payload) {
+            self._invoke('pong', payload);
+        },
+        onClose : function(code, reason) {
+            // §5.5.1 — echo the peer's status code (empty body back when the
+            // peer sent none: 1005 is reserved and never goes on the wire).
+            if (!self._closeSent) {
+                self._closeSent = true;
+                self._write(
+                    (code === 1005)
+                        ? wsf.encodeFrame({ opcode: wsf.OPCODES.CLOSE })
+                        : wsf.encodeClose(code)
+                );
+            }
+            self._endStream();
+            self._finish(code, reason);
+        },
+        onError : function(err) {
+            // Protocol violation: best-effort Close frame with the prescribed
+            // code ("Fail the WebSocket Connection", §7.1.7), then teardown.
+            if (!self._closeSent) {
+                self._closeSent = true;
+                try { self._write(wsf.encodeClose(err.closeCode || 1002)); } catch (encErr) { /* best-effort */ }
+            }
+            self._invoke('error', err);
+            self._endStream();
+            self._finish(err.closeCode || 1002, err.message);
+        }
+    });
+
+    stream.on('data', function(chunk) {
+        self._parser.feed(chunk);
+    });
+    // Transport teardown (HTTP/2 END_STREAM / RST_STREAM / session GOAWAY all
+    // surface here per RFC 8441 §5). 1006 = abnormal closure — reserved on the
+    // wire, legitimate as a LOCAL report (§7.4.1).
+    stream.on('close', function() {
+        self._finish(1006, '');
+    });
+    stream.on('error', function(err) {
+        // Absorb — a dying client stream must never escalate to uncaughtException.
+        self._finish(1006, String((err && err.message) || ''));
+    });
+    stream.on('aborted', function() {
+        self._finish(1006, '');
+    });
+    if (typeof stream.on === 'function') {
+        stream.on('drain', function() {
+            self._invoke('drain');
+        });
+    }
+
+    // Graceful-shutdown drain: proc.js's SIGTERM path iterates this registry
+    // and invokes every closer before _httpServer.close(), so live WebSocket
+    // sessions end with a clean `1001 going away` instead of blocking the
+    // drain until the hard shutdown timeout.
+    if (typeof process !== 'undefined' && process.gina) {
+        if (!process.gina._sseConnections) {
+            process.gina._sseConnections = new Set();
+        }
+        process.gina._sseConnections.add(this._shutdownCloser);
+    }
+}
+
+/**
+ * Registers the message handler — `(data, isBinary)`: text arrives as a
+ * validated UTF-8 string, binary as a Buffer.
+ *
+ * @param {function} fn
+ * @returns {WsSession} this (chainable)
+ * @example
+ *  session.onMessage(function(data, isBinary) { ... });
+ */
+WsSession.prototype.onMessage = function(fn) { this._handlers.message = (typeof fn === 'function') ? fn : noop; return this; };
+
+/**
+ * Registers the ping handler — `(payload Buffer)`. The pong is already sent
+ * automatically unless the session was created with `autoPong: false`.
+ *
+ * @param {function} fn
+ * @returns {WsSession} this (chainable)
+ */
+WsSession.prototype.onPing = function(fn) { this._handlers.ping = (typeof fn === 'function') ? fn : noop; return this; };
+
+/**
+ * Registers the pong handler — `(payload Buffer)`.
+ *
+ * @param {function} fn
+ * @returns {WsSession} this (chainable)
+ */
+WsSession.prototype.onPong = function(fn) { this._handlers.pong = (typeof fn === 'function') ? fn : noop; return this; };
+
+/**
+ * Registers the TERMINAL close handler — `(code, reason)`, delivered exactly
+ * once: peer close (the peer's code; 1005 when its Close body was empty),
+ * protocol failure (the violation's code), initiated-close completion, or
+ * transport teardown (1006).
+ *
+ * @param {function} fn
+ * @returns {WsSession} this (chainable)
+ */
+WsSession.prototype.onClose = function(fn) { this._handlers.close = (typeof fn === 'function') ? fn : noop; return this; };
+
+/**
+ * Registers the diagnostic error handler — `(err)` with `err.closeCode` on
+ * protocol violations. Always followed by the terminal `onClose`.
+ *
+ * @param {function} fn
+ * @returns {WsSession} this (chainable)
+ */
+WsSession.prototype.onError = function(fn) { this._handlers.error = (typeof fn === 'function') ? fn : noop; return this; };
+
+/**
+ * Registers the backpressure-relief handler, forwarded from the underlying
+ * stream's `drain` event. Pair with {@link WsSession#send}'s boolean return.
+ *
+ * @param {function} fn
+ * @returns {WsSession} this (chainable)
+ */
+WsSession.prototype.onDrain = function(fn) { this._handlers.drain = (typeof fn === 'function') ? fn : noop; return this; };
+
+/**
+ * Sends a message: a string goes as a TEXT frame, a Buffer as a BINARY frame.
+ *
+ * @param {string|Buffer} data
+ * @returns {boolean} false when the frame could not be written or the
+ *  underlying stream signalled backpressure (`stream.write` returned false —
+ *  wait for {@link WsSession#onDrain}); true otherwise
+ * @example
+ *  if (!session.send(bigPayload)) { session.onDrain(resumeSending); }
+ */
+WsSession.prototype.send = function(data) {
+    if (this._finished || this._closeSent) {
+        return false;
+    }
+    var frame = (typeof data === 'string') ? wsf.encodeText(data) : wsf.encodeBinary(data);
+    return this._write(frame);
+};
+
+/**
+ * Sends a PING (§5.5.2). Payload must be <= 125 bytes.
+ *
+ * @param {string|Buffer} [payload]
+ * @returns {boolean} as {@link WsSession#send}
+ */
+WsSession.prototype.ping = function(payload) {
+    if (this._finished || this._closeSent) {
+        return false;
+    }
+    return this._write(wsf.encodePing(payload));
+};
+
+/**
+ * Initiates the close handshake (§7): sends a Close frame, then waits up to
+ * `closeTimeout` ms for the peer's echo before force-ending the stream.
+ * Idempotent.
+ *
+ * @param {number} [code] - §7.4 status code; omit for an empty Close body
+ * @param {string} [reason]
+ * @returns {void}
+ * @example
+ *  session.close(1000, 'done');
+ */
+WsSession.prototype.close = function(code, reason) {
+    if (this._finished || this._closeSent) {
+        return;
+    }
+    this._closeSent = true;
+    try {
+        this._write(
+            (typeof code === 'undefined')
+                ? wsf.encodeFrame({ opcode: wsf.OPCODES.CLOSE })
+                : wsf.encodeClose(code, reason)
+        );
+    } catch (err) {
+        // invalid code/reason from the consumer — still proceed with teardown
+    }
+    var self = this;
+    this._closeTimer = setTimeout(function() {
+        self._endStream();
+        self._finish((typeof code === 'undefined') ? 1000 : code, reason || '');
+    }, this._closeTimeout);
+    if (typeof this._closeTimer.unref === 'function') {
+        this._closeTimer.unref();
+    }
+};
+
+/**
+ * Whether the session has delivered its terminal close.
+ *
+ * @returns {boolean}
+ */
+WsSession.prototype.isClosed = function() {
+    return this._finished;
+};
+
+/**
+ * Invokes a consumer callback with containment: a throwing handler is
+ * reported (diagnostic onError, itself guarded) and the session is closed
+ * with `1011 internal error` — never an uncaughtException.
+ *
+ * @private
+ */
+WsSession.prototype._invoke = function(name) {
+    var args = Array.prototype.slice.call(arguments, 1);
+    try {
+        this._handlers[name].apply(null, args);
+    } catch (err) {
+        if (name !== 'error') {
+            try { this._handlers.error(err); } catch (err2) { /* contained */ }
+        }
+        console.warn('[ WS-SESSION ] handler `' + name + '` threw: ' + (err && err.message));
+        if (name !== 'close') {
+            this.close(1011, 'internal error');
+        }
+    }
+};
+
+/**
+ * Guarded write to the underlying stream.
+ *
+ * @private
+ * @param {Buffer} buf
+ * @returns {boolean} stream.write's backpressure boolean; false when the
+ *  stream is gone or the write threw
+ */
+WsSession.prototype._write = function(buf) {
+    var stream = this._stream;
+    if (!stream || stream.destroyed || stream.closed || stream.writableEnded) {
+        return false;
+    }
+    try {
+        return stream.write(buf) !== false;
+    } catch (err) {
+        return false;
+    }
+};
+
+/**
+ * Half-closes the transport (HTTP/2 END_STREAM).
+ *
+ * @private
+ */
+WsSession.prototype._endStream = function() {
+    var stream = this._stream;
+    try {
+        if (stream && !stream.destroyed && !stream.writableEnded) {
+            stream.end();
+        }
+    } catch (err) { /* already gone */ }
+};
+
+/**
+ * Delivers the terminal onClose exactly once and releases session resources
+ * (close timer, shutdown-drain registration).
+ *
+ * @private
+ * @param {number} code
+ * @param {string} reason
+ */
+WsSession.prototype._finish = function(code, reason) {
+    if (this._finished) {
+        return;
+    }
+    this._finished = true;
+    if (this._closeTimer) {
+        clearTimeout(this._closeTimer);
+        this._closeTimer = null;
+    }
+    if (typeof process !== 'undefined' && process.gina && process.gina._sseConnections) {
+        process.gina._sseConnections.delete(this._shutdownCloser);
+    }
+    this._invoke('close', code, reason || '');
+};
+
+/**
+ * Accepts an extended-CONNECT websocket request: answers `:status 200`
+ * (RFC 8441 §5 — the stream then IS the bidirectional WebSocket channel) and
+ * returns the wrapped session.
+ *
+ * @function accept
+ * @param {object} request - the Http2ServerRequest of the extended CONNECT (`request.stream` is the raw Http2Stream)
+ * @param {WsSessionOptions} [options]
+ * @returns {WsSession}
+ * @throws {TypeError} when the request carries no respondable HTTP/2 stream
+ * @throws {Error} when the stream is already closed
+ * @example
+ *  var session = lib.wsSession.accept(request, { maxPayload: 262144 });
+ */
+function accept(request, options) {
+    var stream = request && request.stream;
+    if (!stream || typeof stream.respond !== 'function') {
+        throw new TypeError('accept(request) requires an HTTP/2 extended-CONNECT request carrying a respondable request.stream');
+    }
+    if (stream.destroyed || stream.closed) {
+        throw new Error('accept(request): the stream is already closed');
+    }
+    var headers = { ':status': 200 };
+    if (options && typeof options.protocol === 'string' && options.protocol.length > 0) {
+        headers['sec-websocket-protocol'] = options.protocol;
+    }
+    stream.respond(headers);
+    return new WsSession(stream, options);
+}
+
+module.exports = {
+    accept    : accept,
+    WsSession : WsSession
+};

package/framework/{v0.4.6 → v0.4.7}/package.json

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

package/llms.txt

@@ -369,11 +369,13 @@ var jobId = self.inferAsync([{ role: 'user', content: prompt }], { connector: 'm
     "maxConcurrentStreams": 256,
     "initialWindowSize": 655350,
     "maxSessionRejectedStreams": 100,
-    "maxSessionInvalidFrames": 1000
+    "maxSessionInvalidFrames": 1000,
+    "maxStreamsPerSecond": 200,
+    "enableConnectProtocol": false
   }
 }
 ```
-Security-critical settings that are hardcoded and not user-overridable: `maxHeaderListSize: 65536` (HPACK bomb), `enablePush: false`.
+Security-critical settings that are hardcoded and not user-overridable: `maxHeaderListSize: 65536` (HPACK bomb), `enablePush: false`. All of the above apply to both https and cleartext h2c bundles (the full `http2Options` reaches createSecureServer and createServer alike).
 
 **Session metrics** — exposed at `/_gina/info` under `"http2"` key:
 ```json
@@ -863,7 +865,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 127. **Web Security Headers (`#HDR` plugin family) — 10 lessons consolidated** (replaces individual entries #114, #115, #116, #118, #120, #121, #122, #124, #141, #157):
 - **HTTP security response-header plugins follow the Csrf middleware-return shape, NOT the Session factory-wrap shape** — they emit a header on the response rather than wrapping an upstream module factory. Csrf returns an express middleware directly; each HDR plugin does the same. Settings.json convention stays flat top-level (each plugin gets its own top-level key, sibling of `session.cookie.*` / `csrf.*`). Idempotent-by-default: every header plugin checks `res.getHeader(name)` first and skips writing if a value is already present. No `enabled: false` shortcut — registration IS opt-in; not registering IS opt-out. Throw-on-invalid at factory call time (NOT request time). Multi-field cross-invariant validation in `_resolveOptions` helpers (e.g. #HDR4 `preload=true` requires `includeSubDomains=true` AND `maxAge>=31536000`). Spec-deviation documentation pattern: name the spec section + offsetting receiver behaviour + design tradeoff + operator escape hatch (e.g. #HDR4 RFC 6797 §7.2 vs §8.1). Per-plugin commit shape: 9 touchpoints on gina (src + package.json + README + registry entry + settings template + boilerplate adoption block + ROADMAP row + changie YAML + tests) + 3 on docs-repo (guide + migration + roadmap) in a SEPARATE commit per session.
 - **CSP per-response nonce (#HDR16)** — `gina.plugins.Csp({ useNonce: true })` (opt-in, default off) generates a fresh per-response nonce on the per-request carrier `req._ginaCspNonce` (NOT `res.locals` / `process.gina.*` — the latter would leak across concurrent requests), appends `'nonce-<v>'` to `script-src` (fallback `default-src`; the factory THROWS at call time if neither directive is present), and the swig/nunjucks render delegates stamp it on framework-injected inline scripts and expose `{{ page.cspNonce }}` / `{{ cspNonce }}` so application templates can mark their own inline `<script>`s. The static (no-nonce) path precomputes the header once and writes no `req` slot — byte-identical + zero per-request allocation for non-opt-in bundles.
-- **CSP report-only-inert directive omission (#HDR5)** — in `reportOnly` mode `Csp` omits directives browsers ignore there (`REPORT_ONLY_IGNORED_DIRECTIVES`, currently just `sandbox` — the only directive ignored in report-only by every engine: CSP2 spec text, MDN's Report-Only page, Chromium source, WebKit) and warns once naming what was dropped; `frame-ancestors` is deliberately KEPT — its report-only behaviour is engine-divergent (the CSP3 spec, Gecko and Blink evaluate it and send violation reports; WebKit alone ignores it with a console warning and no report, retaining the CSP2 ignore-when-monitoring rule that CSP3 dropped), so omitting it would lose the Chrome + Firefox observation-phase signal — WebKit-heavy consumers can leave it out of their own report-only set; the configured `directives` keep `sandbox`, so an enforcing factory from the same config still emits it; throws if every directive is report-only-inert.
+- **CSP report-only-inert directive omission (#HDR5)** — in `reportOnly` mode `Csp` omits directives browsers ignore there (`REPORT_ONLY_IGNORED_DIRECTIVES`, currently just `sandbox` — the only directive ignored in report-only by every engine: CSP2 spec text, MDN's Report-Only page, Chromium source, WebKit) and warns once naming what was dropped; `frame-ancestors` is deliberately KEPT — its report-only behaviour is engine-divergent (the CSP3 spec, Gecko and Blink evaluate it and send violation reports; WebKit alone ignores it with a console warning and no report, retaining the CSP2 ignore-when-monitoring rule that CSP3 dropped), so omitting it would lose the Chrome + Firefox observation-phase signal — WebKit-heavy consumers can leave it out of their own report-only set; the configured `directives` keep `sandbox`, so an enforcing factory from the same config still emits it; throws if every directive is report-only-inert. The opt-in `reportOnlyOmit: ['frame-ancestors']` packages the consumer-side omission for engine-divergent directives: named directives are omitted from the report-only header (factory warn with wording distinct from the browser-inert omission — these are NOT browser-ignored; the consumer is forgoing the Gecko/Blink report signal) and emitted again automatically at the enforce flip, so one directive set covers both modes; entries are validated against the same CSP3 whitelist (unknown names throw); silent-inert under reportOnly:false (carrying it there is the expected lifecycle state, never warned); throws if the omissions empty the report-only set or omit the useNonce target directive.
 - **Helmet-parity audit pattern: WebFetch the upstream README before claiming feature parity** — memory of vendor surfaces goes stale fast. When assessing parity, `WebFetch` the canonical README URL before claiming. Triage gaps on 4 axes: (a) modern-and-default-on-in-upstream → strong candidate to add; (b) modern-and-opt-in → moderate; (c) legacy-but-default-on → defense-in-depth-only; (d) legacy-and-opt-in-everywhere → likely skip. Audit cost: 1 WebFetch + ~5 min triage. Cost of skipping: parity-narrative gap a consumer will notice. Precedent: 2026-05-17 #HDR7 (`Origin-Agent-Cluster`) caught via helmet README audit; would have been silently missed otherwise.
 - **Wrapper / orchestrator plugins inherit "batteries-included" default behaviour from sibling wrappers (Session, Csrf, SecurityHeaders), NOT the "register to opt in" rule that single-concern per-feature plugins follow** — `gina.plugins.SecurityHeaders()` with no opts mounts the 7 non-footgun headers (HDR1/2/3/4/7/13/14) with per-plugin defaults. CSP (#HDR5) and COEP (#HDR6) are opt-in-only WITHIN the orchestrator because of known footguns (CSP throws on missing directives; COEP `require-corp` BREAKS embeds without CORP). Default to batteries-included with the "safe" subset of children mounted-by-default; opt-in-only the children with known footguns; preserve the individual-plugin escape hatch via the idempotent first-writer-wins pattern.
 - **gina-bundle plugin adoption ALWAYS uses `myapp.onInitialize(function(event, app){ app.use(<plugin>); event.emit('complete', app); })` — NEVER the standalone-Express idiom** — bundle authors do NOT `require('express')` or call `express()` themselves; gina builds the Express app and passes it via the `onInitialize` callback's `app` parameter. The standalone-Express idiom (`var express = require('express'); var app = express();`) is the recurrence-prone failure mode — universally familiar so it propagates by static-analogy when new docs are added mirroring wrong examples. When adding to an existing docs guide family, cross-check the adoption convention against sibling guides (`csrf.md`, `sessions.md`) AND against the boilerplate (`core/template/boilerplate/bundle/index.js`) BEFORE mirroring an existing example. Sibling sweep needed for Mermaid `participant` declarations: `grep -rn 'participant.*express\|App as express' docs/` — prose-only sweeps miss diagram syntax.
@@ -945,3 +947,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 166. **`project:add`'s gina-symlink step (`linkGina`) no longer shells out to a PATH-resolved `gina` binary, and a failed link now fails the command instead of printing success (`2966a823`, 2026-06-10).** The project's `node_modules/gina` symlink was created by spawning `gina link @<project>` resolved from the PATH; on hosts where no `gina` is on PATH — a repo checkout where `npm install --ignore-scripts` skipped bin linking (CI), or any non-global install — the spawn failed, the failure was routed through the SUCCESS callback (`onSuccess(err)`; the `onError` parameter was dead code), `project:add` printed "Project has been added", and the scaffolded bundle later crashed at boot with `MODULE_NOT_FOUND` on its framework require (the daemonless container-boot integration test was red on CI from its very first run there — never a regression of the commits it first ran against). Three-part fix in `lib/cmd/project/add.js::linkGina`: (a) spawn the running install's OWN CLI — `[process.execPath, <gina root>/bin/cli, 'link', '@<project>']`, the root resolved from the handler's own location (the same self-resolution rationale `framework/link.js` documents for its symlink source; `bin/cli` rewrites a bare `link` task to `framework:link`, which is offline-allowed, so no daemon is needed); the ARRAY form of `Shell.run` matters because the string form is split on spaces with no shell; (b) verify the actual POSTCONDITION (`fs.existsSync` on the project's `node_modules/gina`) instead of trusting the Shell's err channel — the Shell helper reports ANY stderr output as an error even on success, so postcondition-wins is what keeps stderr noise from failing a healthy link; (c) route genuine failures through `onError` so `project:add` exits non-zero. **Two general lessons: never self-invoke your own CLI via a PATH-resolved name (resolve from your own location — PATH may carry no copy or a different version), and when a spawn wrapper's error channel is noisy, assert the operation's postcondition rather than the channel.** Repro recipe for the class: re-run the failing flow with `PATH=/usr/bin:/bin` — a green-locally/red-on-CI integration test whose CI log shows `MODULE_NOT_FOUND` from generated code is the signature. Tests: `test/lib/project-add-link.test.js` (spawn-shape + postcondition + onError source pins, comment-stripped negative on the old PATH form, resolved-CLI-exists check against the real tree, onComplete decision replica); the container-boot integration test is the end-to-end CI guard. Established 2026-06-10.
 
 167. **Two follow-on rules from completing the PATH-resolved self-invocation sweep (`884ee7cd` + `96ca2d03`, 2026-06-10).** (a) **Never guard `execSync` with `instanceof Error`** — `execSync` THROWS on non-zero exit and never returns an Error, so the shape `err = execSync(...); if (err instanceof Error) {...}` is dead code: the "handled" branch can never fire and a real failure escapes as an uncaught throw instead of reaching the command's error path. Wrap in try/catch, and prefer `err.stderr.toString().trim()` for the operator-facing message when present (execSync attaches the child's stderr to the thrown error). Three live instances of this dead shape were removed (framework:link's stale-node_modules repair and CmdHelper's auto-link step). (b) **When self-invoking, pick the entry point that preserves spawn semantics:** plain CLI commands (`link`, `link-node-modules`) are invoked through `bin/cli` directly, but daemon-lifecycle commands (`start`, `stop`, `bundle:restart` inside framework start/restart) must go through the `bin/gina` wrapper — it is the daemonizing "fake daemon" entry point and `start` relies on its detached spawn; `bin/gina` self-locates its cli via its own directory, so an absolute-path invocation stays PATH-independent end-to-end. Deliberate exceptions kept out of the sweep: deriving an npm install PREFIX from `which gina` for project:import registry metadata (semantically "where is gina installed on this machine" — meaningless on a repo checkout, and a wrong self-derived guess would corrupt project metadata; kept with its existing try/catch), and `$(which npm)` (a third-party binary — PATH is the normal resolution). Tests: `test/lib/project-add-link.test.js` §05-07. Established 2026-06-10.
+
+168. **Never hardcode `framework/v<version>` paths in test fixtures, test harnesses, or CI workflows — derive the dir from `package.json` at runtime; enforced by `test/lib/e2e-no-version-pins.test.js`.** The framework directory is renamed at every release cut (the stable rename plus two alpha bumps), so a version-pinned path is green on every CI run between cuts and breaks exactly at the release — polluting the cut's CI signal — and the tag's tree (merged to master, which only moves via tag merges) then carries a deterministic red until the NEXT tag. Incident shape (v0.4.6): an e2e fixture linked the built stylesheet via a literal `framework/v0.4.6-alpha.2/...` href; both post-rename pushes went red with CSS-initial-value failures (`overflow: visible` where the scroll-lock expects `hidden`, `transition-property: all` where the enter transition expects `opacity`) — the diagnostic tell that the page's JS ran but its stylesheet didn't load. Fix: serve fixtures through `test/e2e/runtime-server.js`, which resolves `framework/v<version>` from `package.json` (the same idiom as the CI workflows' `FW_DIR="framework/v${VERSION}"`). The guard test sweeps `test/e2e/**`, `.github/workflows/**`, and `playwright.config.js` for `framework/v<digit>` literals in the gated suite, so a reintroduced pin fails at commit time instead of at the cut; the regex is digit-anchored so `framework/v<version>` prose, `v${VERSION}` interpolation, and `v*` glob pathspecs never match, and it carries per-directory non-empty-sweep pins so a dir move cannot hollow it into a silent always-green no-op. `gna.js` and the root `package.json` `main` field carry the literal BY DESIGN — the release scripts rewrite them atomically with the dir rename (dir name == `package.json` version at every commit), so they are maintained surfaces, deliberately not swept. A post-rename pre-publish Playwright smoke was measured and declined: with zero literals enforced, every committed tree is rename-consistent by construction, and dist staleness (the other tag-tree drift class) is the bundle-freshness gate's job. Established 2026-06-11 (commits `37281177` + `26ff8e83`).
+
+169. **WebSocket over HTTP/2 shipped (develop 2026-06-11, target `0.5.0`; commits `a1bf4d95` transport + `a5f29e5f` codec + `f6ebca90` bridge/API).** Three layers, each with a measured lesson. (1) Transport (Isaac engine): strict `=== true` opt-in `http2Options.enableConnectProtocol` — a boolean settings key must NEVER reuse the `|| default` idiom of its numeric siblings (the string `"true"` or `1` must not flip a SETTINGS advert); the key lives in the `http2Options.settings` literal, which reaches `createSecureServer` (https) and the cleartext `createServer` branches alike since the h2c flood-defense parity fix (2026-06-11 — before it, the cleartext branches passed a bare `{ allowHTTP1 }` literal, dropping the SETTINGS advert AND the session flood caps `maxSessionRejectedStreams`/`maxSessionInvalidFrames`, so h2c bundles ran protocol-default limits — effectively unlimited concurrent streams, server push enabled — and silently ignored their settings.json `http2Options` overrides; passing `http2Options` verbatim is safe because TLS material only merges under `/https/` scheme gates). **Extended-CONNECT streams must be handled on the compat `connect` event, not `session.on('stream')`** — Node's http2 compat layer auto-responds 405 to every CONNECT stream and its internal listener is attached at session setup, before any userland session-level listener, so a stream-handler design loses the race with `ERR_HTTP2_HEADERS_SENT`. Registering a `connect` listener suppresses that auto-405 for ALL CONNECT, so every handler path must terminate the stream (an unanswered CONNECT hangs forever), including the HTTP/1.1 CONNECT signature (`(req, socket, head)`, no `request.stream`) the same event receives under `allowHTTP1`. Refusals are HTTP statuses (405 plain-CONNECT byte-parity — the compat default is just `:status`+`date`; 501 unclaimed; 404 unregistered path), not `close(NGHTTP2_REFUSED_STREAM)`: measured client-side, the RST shape yields an opaque stream error with no loggable status and carries retry semantics. With the flag off, nghttp2 rejects extended CONNECT before any app event — default-off deployments are byte-identical. (2) `lib/ws-framing`: dependency-free RFC 6455 codec (UTF-8 via core `buffer.isUtf8`; maxPayload enforced from the DECLARED frame length before buffering; close-code table mirrors the ws predicate). Write-own was chosen after measuring that ws's `exports` map blocks deep-requiring its internals and that conforming vendoring is whole-tarball-only — which would ship a second copy of a package that is already a framework dependency. The maturity gap is covered by a differential oracle in the tests: ws's root export exposes `Receiver`/`Sender` publicly, so frames are cross-checked in both directions and both parsers must refuse unmasked client frames. (3) `lib/ws-session` + `app.onWebSocket(path, handler)`: `onInitialize`'s `app` IS the raw engine server, so the registration API needs zero routing-layer changes; the dispatcher installs lazily (zero registrations keep the 501-unclaimed refusal); handler exceptions are contained (1011 close, never an uncaughtException); sessions register a closer in the SIGTERM drain registry so shutdown sends `1001 going away` instead of blocking the drain — and since the WS shutdown-drain fix (2026-06-11) the pre-existing engine.io and `/_gina/agent` WS sockets register there too (engine.io with a graceful `socket.close()` — its API takes no status code; the agent WS with `ws.close(1001, 'server shutting down')`), each closer added at socket setup and removed in the socket's own close handler, so no live socket surface blocks SIGTERM until the hard timeout anymore. A routing.json-declared WS surface was measured and deferred: the route matcher's allowed-methods list and exact-method gate sit on the hot path and reject CONNECT, and controller dispatch is render-lifecycle-only — every streaming endpoint bypasses routing, and so does this one. Established 2026-06-11.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -72,7 +72,7 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.4.6/core/gna",
+  "main": "./framework/v0.4.7/core/gna",
   "types": "./types/index.d.ts",
   "typesVersions": {
     "*": {

package/playwright.config.js

@@ -20,8 +20,10 @@ module.exports = defineConfig({
         trace: 'on-first-retry'
     },
     // Starts the runtime harness (test/e2e/runtime-server.js) that serves the REAL
-    // built gina bundle for popin-dialog.runtime.spec.js. The framework-free
-    // popin-dialog.a11y.spec.js drives file:// fixtures and ignores it.
+    // built gina bundle for popin-dialog.runtime.spec.js, plus the framework-free
+    // a11y fixture at /a11y — its stylesheet link resolves through the server's
+    // /css route, which derives framework/v<version> from package.json so the
+    // per-release framework-dir rename can't break it.
     webServer: {
         command: 'node test/e2e/runtime-server.js',
         url: 'http://localhost:' + E2E_PORT + '/',

package/framework/v0.4.6/VERSION

@@ -1 +0,0 @@
-0.4.6