gina 0.3.7-alpha.3 → 0.3.7-alpha.4

package/CHANGELOG.md

@@ -6,6 +6,14 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.3.7-alpha.4 - 2026-04-23 (npm only — no git tag)
+### Added
+* Static HTML cache writes on the nunjucks render path (#NJ3) — bundles running `render.engine: "nunjucks"` now get the same `memory`/`fs` cache behaviour swig has shipped for years. A route declaring `"cache": { "type": "memory", "ttl": 300 }` (or the `"fs"` variant) is served from the shared server store on subsequent hits without re-entering the controller; the same `static:<bundle>:<url>` key-space + visibility/sliding-window/invalidateOnEvents controls apply. Cache writes run after asset + Inspector injection so the bytes on disk/in memory match what the client sees; the miss-path `Cache-Control: private, max-age=N` header is committed on the same response. Opt-in via your routing rule — there is no new setting to toggle.
+* 103 Early Hints auto-send now works for bundles running `render.engine: "nunjucks"` (#NJ4). HTTP/2 non-dev requests to nunjucks bundles get automatic `Link: ...; rel=preload` hints for the bundle's CSS and JS assets, delivered as a 103 Early Hints informational response before the HTML body. Identical behaviour to swig — the firing point in `controller.js this.render()` is engine-agnostic and the data-feed was closed by #NJ2 (`deps.setResources` runs on both delegates, populating `h2Links` via the same `getNodeRes` path). Closes the final item in the four-session nunjucks parity track (#NJ1 filters / #NJ2 setResources & assets / #NJ3 static HTML cache / #NJ4 Early Hints) — nunjucks bundles now have full feature parity with swig.
+### Security
+* Removed three server-side `eval` / `new Function` call sites (#SCS1). `core/server.js` built a static-path regex via `eval('/^…/')` and now uses `new RegExp`. `lib/logger/src/main.js` generated per-level logger methods via `new Function(...)` string concatenation and now uses a closure factory. `lib/math/index.js` `operate()` wrapped `new Function('return '+ expr)()` and is now a shunting-yard evaluator supporting `+ - * / %`, parentheses, decimals, and unary sign; any non-arithmetic character throws. Public contract unchanged — the expressions `math.operate` accepts are the same as before, but it now rejects arbitrary JS beyond pure arithmetic instead of silently executing it.
+* Replaced the four `eval('async function on<Name>...')` async-chain scaffolding sites (#SCS1b) with direct `promisify` + `try`/`await`/`catch` IIFEs. Affected files: `lib/cmd/framework/build.js`, `lib/cmd/framework/init.js`, `script/pre_install.js`, `script/post_install.js`. Semantics unchanged — each step is still promisified, awaited, and error-exits via `console.error` + `process.exit(1)` before recursing to the next step. Old eval lines kept as comments with the `#SCS1b` tag per the replace-don't-delete convention.
+
 ## 0.3.7-alpha.3 - 2026-04-23 (npm only — no git tag)
 ### Added
 * The nunjucks render path now registers Gina's built-in filter registry automatically. Bundles with `render.engine: "nunjucks"` get the same 7 filters as the swig path — `getUrl`, `getWebroot`, `length`, `nl2br`, `addHours`, `addDays`, `addYears` — with no manual `env.addFilter()` calls needed. Templates can use `{{ 'home' | getUrl }}`, `{{ body | nl2br | safe }}`, or date helpers out of the box. User-registered filters on top (`env.addFilter('upper', fn)`) coexist with the built-in registry. Closes the most user-visible gap left by the 0.3.7-alpha.2 nunjucks MVP.

package/framework/v0.3.7-alpha.4/VERSION

@@ -0,0 +1 @@
+0.3.7-alpha.4

package/framework/{v0.3.7-alpha.3 → v0.3.7-alpha.4}/core/controller/controller.render-nunjucks.js

@@ -55,11 +55,28 @@
  *      recursing via `self.throwError` — recursion would re-enter this same
  *      branch and could loop. The defensive `localOptions.isRenderingCustomError
  *      = false` reset after render mirrors render-swig.js lines 804, 1434.
- *   4. **Early Hints 103** auto-send — lives in `controller.js this.render()`
- *      before the delegate runs, so the port is controller-level rather than
- *      render-nunjucks-level.
- *   5. **Static HTML cache writes** — no `writeCache()` equivalent; every
- *      request re-renders even when the route has `cache` configured.
+ *   4. ~~**Early Hints 103** auto-send~~ — **shipped 2026-04-23** (#NJ4).
+ *      The #EH1 firing point in `controller.js this.render()` is already
+ *      engine-agnostic — it reads `local.options.template.h2Links` and calls
+ *      `self.setEarlyHints(_hints)` BEFORE the delegate dispatch, so both
+ *      swig and nunjucks bundles reach it identically. The data-feed was
+ *      closed by #NJ2: `deps.setResources(localTemplateConf)` is called below
+ *      (same function object defined once in `controller.js:782` and passed
+ *      to both delegates via `deps`), and `setResources` → `getNodeRes`
+ *      writes to `local.options.template.h2Links` at `controller.js:901`
+ *      (CSS) / `:930` (JS) on HTTP/2 non-dev requests. No nunjucks-specific
+ *      h2Links logic is needed — a negative-invariant test locks that in.
+ *   5. ~~**Static HTML cache writes**~~ — **shipped 2026-04-23** (#NJ3).
+ *      `writeCache(bundle, opt, htmlContent)` is a direct port of
+ *      `render-swig.js:35-129` (same guards, cache-key shape, memory/fs
+ *      dispatch, sliding-window support, invalidateOnEvents hook). It runs
+ *      after `injectAssets` + `injectInspectorScripts` so the cached bytes
+ *      match what the client sees, and BEFORE `sendHtmlResponse` so the
+ *      miss-path `Cache-Control: private, max-age=N` header is committed
+ *      alongside the response. Reads are engine-agnostic already — the
+ *      server-layer read path at `server.isaac.js:1012-1067` keys on
+ *      `static:${bundle}:${url}` regardless of which engine populated the
+ *      entry, so no read-side port was needed.
  *   6. ~~**Asset cataloguing / `setResources`**~~ — **shipped 2026-04-23** (#NJ2).
  *      `deps.setResources(localTemplateConf)` is now called before `env.render()`
  *      so `data.page.view.stylesheets` and `data.page.view.scripts` are
@@ -111,6 +128,14 @@ var inspectorRedact = require('lib/inspector-redact');
 // the lib registry so the dev-mode hot-reload evictions of `lib/index.js`
 // don't poison the reference across requests.
 var Collection      = require('../../lib').Collection;
+// #NJ3 — static HTML cache writes. Module-scoped `cache` instance mirrors
+// `render-swig.js:6` and `render-json.js:5`. Per-request, the main render
+// function re-points it at the server's shared in-memory store (key:
+// `static:<bundle>:<url>`). The server-layer read path
+// (`server.isaac.js:1012-1067`) is engine-agnostic, so writes from this
+// delegate are served back on subsequent hits without going through the
+// controller at all.
+var cache           = new (require('../../lib').Cache)();
 
 /**
  * Caches a `nunjucks.Environment` per bundle template root so we don't
@@ -568,6 +593,109 @@ function injectAssets(html, data, localOptions) {
     return html;
 }
 
+/**
+ * #NJ3 — write the rendered HTML to the static-HTML cache store (memory or
+ * file system). No-op when caching is disabled server-side or the route has
+ * no `cache` setting. Direct port of `render-swig.js:35-129` — same guards,
+ * cache-key shape, memory/fs dispatch, sliding-window support, and
+ * `invalidateOnEvents` hook.
+ *
+ * The cache-key namespace (`static:<bundle>:<url>`) matches the prefix the
+ * server-layer read path scans in `server.isaac.js:1012-1067`, so writes
+ * from this function are served back on subsequent hits without reaching
+ * the controller at all.
+ *
+ * @inner
+ * @param {object} local       - Per-request closure (`req`, `res`) — captured explicitly because writeCache is declared at module scope
+ * @param {object} self        - SuperController instance (for `self.serverInstance._cacheIsEnabled` / `self.throwError`)
+ * @param {string} bundle      - Bundle name (used as cache-key namespace)
+ * @param {object} opt         - Server cache configuration (`opt.path`, `opt.ttl`)
+ * @param {string} htmlContent - Final HTML string to cache (post injectAssets + injectInspectorScripts)
+ * @returns {Promise<void>}
+ */
+async function writeCache(local, self, bundle, opt, htmlContent) {
+    if (
+        typeof(local.req.routing.cache) == 'undefined'
+        ||
+        ! local.req.routing.cache
+        ||
+        String(self.serverInstance._cacheIsEnabled).toLowerCase() !== 'true'
+    ) {
+        return;
+    }
+    // Bundle namespace prevents silent collisions when two bundles serve the
+    // same URL path — matches render-swig.js:47 and render-json.js:40 (#C3).
+    var cacheKey = "static:" + bundle + ":" + local.req.originalUrl;
+    var responseHeaders = local.res.getHeaders() || {};
+    if ( !cache.has(cacheKey) ) {
+        // Caching kinds are: `memory` & `fs`
+        var cachingOption = ( typeof(local.req.routing.cache) == 'string' ) ? { type: local.req.routing.cache } : JSON.clone(local.req.routing.cache);
+        if ( typeof(cachingOption.ttl) == 'undefined' ) {
+            cachingOption.ttl = opt.ttl
+        }
+        var cacheObject = {
+            responseHeaders : responseHeaders
+        };
+        // Store visibility for Cache-Control header on the hit path.
+        // Default is 'private' — opt in to 'public' explicitly for truly static pages.
+        cacheObject.visibility = ( cachingOption.visibility === 'public' ) ? 'public' : 'private';
+        if ( cachingOption.ttl > 0) {
+            cacheObject.ttl = cachingOption.ttl;
+        }
+        // Sliding window (opt-in, default false).
+        // When true, ttl becomes the idle eviction threshold (seconds since last access)
+        // rather than an absolute duration from creation.
+        if ( cachingOption.sliding === true ) {
+            cacheObject.sliding = true;
+        }
+        // Absolute expiration ceiling — only meaningful when sliding is enabled.
+        // The entry is evicted at createdAt + maxAge regardless of access patterns.
+        if ( cacheObject.sliding && typeof(cachingOption.maxAge) != 'undefined' && cachingOption.maxAge > 0 ) {
+            cacheObject.maxAge = cachingOption.maxAge;
+        }
+        // Caching to `memory`
+        if ( /^memory$/i.test(cachingOption.type) ) {
+            cacheObject.fromMemory = true;
+            cacheObject.content = htmlContent;
+
+            cache.set(cacheKey, cacheObject);
+        }
+
+        // Caching to `fs` (file system)
+        if ( /^fs$/i.test(cachingOption.type) ) {
+            var url = local.req.originalUrl;
+            if ( url.endsWith('/') ) {
+                url += 'index'
+            }
+            var htmlFilename = _(opt.path +'/'+ bundle +'/html'+ url + '.html', true);
+            var htmlDir = htmlFilename.split(/\//g).slice(0, -1).join('/');
+            var htmlDirObj = new _(htmlDir);
+            if ( !htmlDirObj.existsSync() ) {
+                htmlDirObj.mkdirSync()
+            }
+            htmlDirObj = null;
+
+            await fs.promises.writeFile(htmlFilename, htmlContent);
+
+            cacheObject.filename = htmlFilename;
+
+            // cleanupFn: delete the cached file from disk when the entry is evicted
+            cache.set(cacheKey, cacheObject, function() {
+                try { fs.rmSync(cacheObject.filename); } catch(e) {}
+            });
+        }
+
+        // Invalidation
+        if ( typeof(cachingOption.invalidateOnEvents) != 'undefined' ) {
+            if ( !Array.isArray(cachingOption.invalidateOnEvents) ) {
+                return self.throwError(local.res, 500, new Error('cache.invalidateOn must be an array'));
+            }
+            // Placing event listeners
+            cache.setEvents(cacheKey, cachingOption.invalidateOnEvents);
+        }
+    }
+}
+
 module.exports = async function renderNunjucks(userData, displayInspector, errOptions, deps) {
     var self  = deps.self;
     var local = deps.local;
@@ -580,6 +708,12 @@ module.exports = async function renderNunjucks(userData, displayInspector, errOp
     // `localOptions.template.{stylesheets,javascripts}` arrays.
     var setResources = deps.setResources;
 
+    // #NJ3 — point the module-level `cache` at the server's shared in-memory
+    // store for this request. Same pattern as render-swig.js:171 and
+    // render-json.js:149. A guard is unnecessary: `self.serverInstance._cached`
+    // is always present by the time a controller action runs.
+    cache.from(self.serverInstance._cached);
+
     // Fetch the nunjucks module from the process-cache. `get()` throws if
     // the bundle-startup load did not succeed — we surface that cleanly
     // via throwError so the usual error page pipeline handles it.
@@ -799,5 +933,44 @@ module.exports = async function renderNunjucks(userData, displayInspector, errOp
         try { console.warn('[render-nunjucks] inspector injection skipped: ' + injectErr.message); } catch (e) {}
     }
 
+    // #NJ3 — static HTML cache write. Must run BEFORE sendHtmlResponse so
+    // the cached bytes reflect the final output AND the miss-path
+    // Cache-Control header we set next is committed alongside the response.
+    // The guard mirrors render-swig.js:821-830 exactly: cacheless mode
+    // allowed through when `_cacheIsEnabled === 'true'` (dev-mode cache
+    // testing), GETs only, route must declare a `cache` block.
+    if (
+        !self.isCacheless()
+        && typeof(local.req.routing.cache) != 'undefined'
+        && local.req.method.toUpperCase() === 'GET'
+        ||
+        // allowing caching even for dev env
+        String(self.serverInstance._cacheIsEnabled).toLowerCase() === 'true'
+        && typeof(local.req.routing.cache) != 'undefined'
+        && local.req.method.toUpperCase() === 'GET'
+    ) {
+        try {
+            await writeCache(local, self, localOptions.bundle, localOptions.conf.server.cache, html);
+        } catch (cacheErr) {
+            // Cache-write failures must never break the render. The response
+            // still goes out; subsequent requests will retry the write on the
+            // next miss. Mirrors the fire-and-forget treatment in render-json.js.
+            try { console.error('[render-nunjucks] writeCache failed: ' + (cacheErr.message || cacheErr)); } catch (e) {}
+        }
+    }
+
+    // Cache-Control: miss path — inform browsers/CDNs of the response lifetime (#C6).
+    // Mirror of render-swig.js:834-841. The hit path in server.isaac.js
+    // re-computes its own Cache-Control header from `cachedContentObj.ttl`
+    // so this header is only meaningful when a client receives the
+    // freshly-rendered bytes.
+    if ( typeof(local.req.routing.cache) != 'undefined' && local.req.routing.cache ) {
+        var _ccCfg = ( typeof(local.req.routing.cache) == 'string' ) ? { type: local.req.routing.cache } : local.req.routing.cache;
+        var _ccTtl = ( typeof(_ccCfg.ttl) != 'undefined' && _ccCfg.ttl > 0 ) ? _ccCfg.ttl : localOptions.conf.server.cache.ttl;
+        if ( _ccTtl > 0 ) {
+            local.res.setHeader('Cache-Control', ( _ccCfg.visibility === 'public' ? 'public' : 'private' ) + ', max-age=' + ~~(_ccTtl));
+        }
+    }
+
     sendHtmlResponse(local, html);
 };

package/framework/{v0.3.7-alpha.3 → v0.3.7-alpha.4}/core/server.js

@@ -1867,7 +1867,12 @@ function Server(options) {
         } else {
             var s = 0, sLen = bundleConf.staticResources.length;
             for ( ; s < sLen; ++s ) {
-                if ( eval('/^' + bundleConf.staticResources[s].replace(/\//g,'\\/') +'/').test(pathname) ) {
+                // #SCS1 (2026-04-23) — swap `eval` for `new RegExp` so Socket no longer flags the
+                //                       server-side `Uses eval` risk here. Semantics unchanged: both
+                //                       forms build the same regex from the (already slash-escaped)
+                //                       `staticResources` path.
+                // if ( eval('/^' + bundleConf.staticResources[s].replace(/\//g,'\\/') +'/').test(pathname) ) {
+                if ( new RegExp('^' + bundleConf.staticResources[s].replace(/\//g,'\\/')).test(pathname) ) {
                     filename = bundleConf.content.statics[ bundleConf.staticResources[s] ] +'/'+ pathname.replace(bundleConf.staticResources[s], '');
                     break;
                 }

package/framework/{v0.3.7-alpha.3 → v0.3.7-alpha.4}/lib/cmd/framework/build.js

@@ -56,11 +56,11 @@ function Build(opt, cmd){
         for (let t in self) {
             if ( typeof(self[t]) == 'function') {
                 if (n == i){
-                    //let func = 'self.' + t + '()';
-                    let func = 'self.' + t;
-                    console.debug('Running [ ' + func + '() ]');
-                    funct       = func;
-                    functName   = t;
+                    // #SCS1b (2026-04-23) — hold the function reference directly instead
+                    //                        of building a `'self.' + t` string for eval.
+                    functName = t;
+                    funct     = self[t];
+                    console.debug('Running [ self.' + functName + '() ]');
                     break;
                 }
                 n++;
@@ -69,7 +69,24 @@ function Build(opt, cmd){
 
         // to handle sync vs async to allow execution in order of declaration
         if (funct) {
-            eval('async function on'+functName+'(){ await promisify('+ funct + ')().catch(function(e){ console.error(e.toString()); process.exit(1);}).then(function(){ begin('+(i+1)+')});}; on'+functName+'();');// jshint ignore:line
+            // #SCS1b (2026-04-23) — replaced `eval('async function on<Name>...')` chain
+            //                        scaffolding with a direct promisify + try/await/catch
+            //                        so Socket no longer flags `Uses eval`. Semantics
+            //                        unchanged: promisify → await → error ⇒ console.error
+            //                        + process.exit(1) → recurse to begin(i+1). The
+            //                        per-function `on<Name>` stack-label is lost; functName
+            //                        is logged above instead.
+            // eval('async function on'+functName+'(){ await promisify('+ funct + ')().catch(function(e){ console.error(e.toString()); process.exit(1);}).then(function(){ begin('+(i+1)+')});}; on'+functName+'();');// jshint ignore:line
+            (async function() {
+                try {
+                    await promisify(funct)();
+                } catch (e) {
+                    console.error(e.toString());
+                    process.exit(1);
+                    return;
+                }
+                begin(i + 1);
+            })();
         } else {
             end();
         }

package/framework/{v0.3.7-alpha.3 → v0.3.7-alpha.4}/lib/cmd/framework/init.js

@@ -84,11 +84,11 @@ function Initialize(opt) {
         for (let t in self) {
             if ( typeof(self[t]) == 'function') {
                 if (n == i) {
-                    //let func = 'self.' + t + '()';
-                    let func = 'self.' + t;
-                    console.debug('Running [ ' + func + '() ]');
-                    funct       = func;
-                    functName   = t;
+                    // #SCS1b (2026-04-23) — hold the function reference directly instead
+                    //                        of building a `'self.' + t` string for eval.
+                    functName = t;
+                    funct     = self[t];
+                    console.debug('Running [ self.' + functName + '() ]');
                     break;
                 }
                 n++;
@@ -97,7 +97,24 @@ function Initialize(opt) {
 
         // to handle sync vs async to allow execution in order of declaration
         if (funct) {
-            eval('async function on'+functName+'(){ await promisify('+ funct + ')().catch(function(e){ console.error(e.toString()); process.exit(1);}).then(function(){ begin('+(i+1)+')});}; on'+functName+'();'); // jshint ignore:line
+            // #SCS1b (2026-04-23) — replaced `eval('async function on<Name>...')` chain
+            //                        scaffolding with a direct promisify + try/await/catch
+            //                        so Socket no longer flags `Uses eval`. Semantics
+            //                        unchanged: promisify → await → error ⇒ console.error
+            //                        + process.exit(1) → recurse to begin(i+1). The
+            //                        per-function `on<Name>` stack-label is lost; functName
+            //                        is logged above instead.
+            // eval('async function on'+functName+'(){ await promisify('+ funct + ')().catch(function(e){ console.error(e.toString()); process.exit(1);}).then(function(){ begin('+(i+1)+')});}; on'+functName+'();'); // jshint ignore:line
+            (async function() {
+                try {
+                    await promisify(funct)();
+                } catch (e) {
+                    console.error(e.toString());
+                    process.exit(1);
+                    return;
+                }
+                begin(i + 1);
+            })();
         } else if ( i == self.functionCount() ) {
             e.emit('init#complete', false, run, self.opt);
         }

package/framework/{v0.3.7-alpha.3 → v0.3.7-alpha.4}/lib/logger/src/main.js

@@ -521,8 +521,18 @@ function Logger() {
             }
 
             for (let l in loggerOptions.levels) {
+                // #SCS1 (2026-04-23) — replaced `new Function(...)` dynamic method build with a
+                //                       closure factory so Socket no longer flags `Uses eval` on
+                //                       the server side. `write`, `parse`, `emit` are now captured
+                //                       by reference (they were previously stringified via
+                //                       `toString()` and embedded as literals into the generated
+                //                       function body). `setDefaultLevels` is called fresh on every
+                //                       `setLevel`, so methods still reflect the latest options.
                 // override if existing
-                logger[l] = new Function('return '+ write +'('+ JSON.stringify(loggerOptions) +', '+ parse +', "'+ l +'", arguments, '+  emit +');');// jshint ignore:line
+                // logger[l] = new Function('return '+ write +'('+ JSON.stringify(loggerOptions) +', '+ parse +', "'+ l +'", arguments, '+  emit +');');// jshint ignore:line
+                logger[l] = function() {
+                    return write(loggerOptions, parse, l, arguments, emit);
+                };
             }
 
         } catch (err) {

package/framework/{v0.3.7-alpha.3 → v0.3.7-alpha.4}/lib/math/index.js

@@ -36,7 +36,11 @@ function MathHelper() {
     // }
 
     /**
-     * Operate from a string value
+     * Operate from a string value.
+     *
+     * Evaluates an arithmetic expression without using `eval` or `new Function`:
+     * supported operators are `+`, `-`, `*`, `/`, `%`, parentheses, decimals,
+     * and unary `+` / `-`. Any non-arithmetic character throws.
      *
      * e.g.:
      *
@@ -45,12 +49,92 @@ function MathHelper() {
      *  var result = operate(computation);
      *      => 20
      *
-     *  @param {string} calcultation
+     *  @param {string} computation
      *
      *  @returns {number} result
+     *  @throws {Error} when the expression contains an invalid character or is malformed
      * */
+    // #SCS1 (2026-04-23) — replaced `new Function('return '+ computation)()` with a shunting-yard
+    //                       evaluator so Socket no longer flags `Uses eval` here. Same public
+    //                       contract (string expression → number); now rejects any non-arithmetic
+    //                       character instead of silently running arbitrary JS. Old body kept for
+    //                       reference:
+    //
+    //     self.operate = function(computation) {
+    //         return new Function('return ' + computation)();
+    //     };
     self.operate = function(computation) {
-        return new Function('return ' + computation)();
+        var input  = String(computation);
+        var output = [];
+        var ops    = [];
+        var prec   = { '+': 1, '-': 1, '*': 2, '/': 2, '%': 2, 'u-': 3, 'u+': 3 };
+        var apply  = function(op) {
+            if (op === 'u+') { return; }
+            if (op === 'u-') {
+                if (!output.length) { throw new Error('MathHelper.operate: malformed expression'); }
+                output.push(-output.pop());
+                return;
+            }
+            var b = output.pop();
+            var a = output.pop();
+            if (typeof a === 'undefined' || typeof b === 'undefined') {
+                throw new Error('MathHelper.operate: malformed expression');
+            }
+            if (op === '+') { output.push(a + b); }
+            else if (op === '-') { output.push(a - b); }
+            else if (op === '*') { output.push(a * b); }
+            else if (op === '/') { output.push(a / b); }
+            else if (op === '%') { output.push(a % b); }
+        };
+
+        var prev = 'op';
+        var i = 0;
+        while (i < input.length) {
+            var c = input[i];
+            if (/\s/.test(c)) { ++i; continue; }
+            if (/\d/.test(c) || (c === '.' && /\d/.test(input[i + 1]))) {
+                var num = '';
+                var hasDot = false;
+                while (i < input.length && /[\d.]/.test(input[i])) {
+                    if (input[i] === '.') {
+                        if (hasDot) { throw new Error('MathHelper.operate: invalid number literal'); }
+                        hasDot = true;
+                    }
+                    num += input[i++];
+                }
+                output.push(parseFloat(num));
+                prev = 'num';
+                continue;
+            }
+            if (c === '(') { ops.push(c); prev = 'op'; ++i; continue; }
+            if (c === ')') {
+                while (ops.length && ops[ops.length - 1] !== '(') { apply(ops.pop()); }
+                if (!ops.length) { throw new Error('MathHelper.operate: mismatched parenthesis'); }
+                ops.pop();
+                prev = 'num';
+                ++i;
+                continue;
+            }
+            if (/[+\-*/%]/.test(c)) {
+                var op = c;
+                if ((op === '-' || op === '+') && prev === 'op') { op = 'u' + op; }
+                while (ops.length && ops[ops.length - 1] !== '(' && prec[ops[ops.length - 1]] >= prec[op]) {
+                    apply(ops.pop());
+                }
+                ops.push(op);
+                prev = 'op';
+                ++i;
+                continue;
+            }
+            throw new Error('MathHelper.operate: invalid character `' + c + '`');
+        }
+        while (ops.length) {
+            var tail = ops.pop();
+            if (tail === '(') { throw new Error('MathHelper.operate: mismatched parenthesis'); }
+            apply(tail);
+        }
+        if (output.length !== 1) { throw new Error('MathHelper.operate: malformed expression'); }
+        return output[0];
     };
 
     /**

package/framework/{v0.3.7-alpha.3 → v0.3.7-alpha.4}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.3.7-alpha.3",
+  "version": "0.3.7-alpha.4",
   "dependencies": {
     "@rhinostone/swig": "^1.6.0",
     "psl": "^1.15.0"

package/gna.js

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

package/llms.txt

@@ -817,7 +817,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 66. **changie body strings — single-quote by default and escape `'` as `''`** — six `.changes/unreleased/*.yaml` files written across four separate sessions in April 2026 broke YAML parsing in two distinct ways, one loud and one silent. Loud: a quoted body without a closing `'` before the newline fails with `unexpected end of stream`; an unescaped literal `'` inside a quoted body closes the scalar early and the rest of the file parses as garbage (`did not find expected key`, `mapping values are not allowed`). Silent and worse: an unquoted body containing ` #` (space + hash) — YAML treats that as a comment marker, so `(#M8 / #AI3)` was stored as just `(#M8 /` and the rest of the sentence disappeared from the rendered changelog entirely; likewise an unquoted body with `:` at any depth breaks as a mapping. Cleaned up in commit `ca64f0735` (2026-04-22) — `Added-20260417-200100.yaml`, `Added-20260417-203000.yaml`, `Fixed-20260416-183051.yaml`, `Added-20260422-022257.yaml`, `Added-20260422-023136.yaml`, `Added-20260422-024132.yaml`. Author rule: every new changie entry uses `body: '...'` (single-quoted) even when the text looks "clean"; every literal `'` inside becomes `''`; never leave a body unquoted. Verification is now automatic: `.githooks/pre-commit` runs `script/check_changie_entries.js` against every staged `.changes/unreleased/*.yaml` file and refuses the commit when any body is unquoted, uses an unescaped literal `''` inside a single-quoted scalar, or fails to terminate before the `time:` key (commit `acbf91dd0`, 2026-04-22). The script is also callable standalone (`node script/check_changie_entries.js .changes/unreleased/*.yaml`) for CI use or on-demand audits. Pre-existing unquoted entries on disk are grandfathered until someone edits them — the hook only runs on staged AM files. The on-demand `changie batch --dry-run patch` still works for a visual sanity check of the rendered markdown.
 
-67. **`lib/nunjucks-resolver` + `settings.render.engine` — opt-in nunjucks without a framework dep** — nunjucks is **never** declared in `framework/v*/package.json`; the resolver only looks in `<projectPath>/node_modules/nunjucks/`. Three-layer dispatch: (a) `schema/settings.json > render.engine` defaults to `"swig"`; set to `"nunjucks"` to opt in. (b) `server.js` `initNunjucksEngine(conf)` runs alongside `initSwigEngine` during bundle init when `hasViews()` is true — if `render.engine === 'nunjucks'`, it calls `nunjucksResolver.load(self.executionPath, settings.nunjucks)` which throws `NUNJUCKS_NOT_INSTALLED` when the project has not `npm install`ed the package (bundle startup fails loud, not mid-render). (c) `controller.js` `this.render()` reads `local.options.conf.content.settings.render.engine` and dispatches to either `controller.render-swig.js` (default) or `controller.render-nunjucks.js`; both delegates receive the same `deps` object (`self`, `local`, `getData`, `hasViews`, `headersSent`, etc.), `render-nunjucks.js` fetches the engine via `lib.nunjucksResolver.get()` so the `swig`/`SwigFilters` deps are harmless when unused. Environment caching: `new nunjucks.Environment(loader, ...)` is cached per template root on `process.gina._nunjucksEnvs` and invalidated via `process.gina._nunjucksEnvsOwner` whenever the underlying nunjucks module itself is hot-swapped (dev-mode mtime drift on the project''s `package.json`). Dev-mode also sets `FileSystemLoader({ noCache: true })` so `.njk` template edits take effect on the next request. **Deferred relative to render-swig.js** — documented inline so nothing is hidden: (1) ~~Inspector `__gdPayload`~~ **shipped 2026-04-22** (commit `7aef191ac`) — `<script>window.__ginaData</script>` + `<script>window.__ginaLogs</script>` injected before `</body>` in dev mode via `injectInspectorScripts`, redacted through `lib/inspector-redact`, stashed on `serverInstance._lastGinaData` (+ `_lastGinaDataUnredacted` on local scope), emitted via `process.emit('inspector#data')`, wrapped in try/catch so Inspector bugs never break the page render. Within the Inspector port, three sub-items remain deferred: `statusbar.html` include (swig-templated), `data.page.flow` pipeline from `local._timeline`, `data.page.queries` from `local._queryLog`. (2) ~~HTTP/2 `stream.respond()` direct path~~ **shipped 2026-04-22** (commit `6b11fc6dc`) — `sendHtmlResponse` implements the four-way branch from `class.controller.md §7b` (HEAD×stream, HEAD×HTTP1.1, body×stream, body×HTTP1.1) with the `stream.destroyed || stream.closed` disconnect guard, pipeline-header merge via `local.res.getHeaders()`, and `local.res.headersSent = true` flag. (3) ~~Error-page template routing~~ **shipped 2026-04-22** — when `controller.js renderCustomError()` injects `errOptions.file = <absolute path>` from `bundleConf.content.templates._common.errorFiles[code]`, `render-nunjucks.js` now detects `localOptions.isRenderingCustomError === true`, reads the file via `fs.readFileSync`, and renders it with `env.renderString(source, data)`. `env.renderString` bypasses the `FileSystemLoader` (which rejects absolute paths and cannot reach shared-path error templates outside the bundle root). **Never recurses via `self.throwError`** — every failure mode (missing file, read error, render error) falls back to a minimal inline HTML body served through `sendHtmlResponse`, because a `throwError` call would re-enter this same branch and could loop infinitely. Defensive `localOptions.isRenderingCustomError = false` reset after render mirrors `render-swig.js` lines 804 and 1434. +14 source-inspection tests in `test/lib/render-engine-dispatch.test.js` (78 total in the dispatch suite, 116 total across the nunjucks track, full suite 3326 → 3340 green). (4) Early Hints 103 auto-send — still deferred (lives in `controller.js this.render()` before the delegate is called). (5) static HTML cache writes, (6) `setResources` asset injection / `<gina>` layout placeholders, (7) Gina `SwigFilters` equivalents — users register their own filters via `env.addFilter()`. Negative invariants locked by source-inspection tests in `test/lib/render-engine-dispatch.test.js`: framework `package.json` must never declare nunjucks; `render-nunjucks.js` must never `require("nunjucks")` directly (always through the resolver); dispatch default must stay `"swig"`; the `isRenderingCustomError` branch must never call `self.throwError` (would loop). Nunjucks contrast vs swig-resolver: no framework fallback (different contract — `get()` throws instead of returning a framework copy), no version floor (any installed version accepted), same mtime hot-swap mechanism. Precedent: `63e7e569f` (N1 resolver primitive), `0980a00b7` (N2 dispatch + render-nunjucks.js MVP), `7aef191ac` (Inspector `__gdPayload` port), `6b11fc6dc` (HTTP/2 stream.respond four-way branch), and the error-page template-routing port (this commit), 2026-04-22.
+67. **`lib/nunjucks-resolver` + `settings.render.engine` — opt-in nunjucks without a framework dep** — nunjucks is **never** declared in `framework/v*/package.json`; the resolver only looks in `<projectPath>/node_modules/nunjucks/`. Three-layer dispatch: (a) `schema/settings.json > render.engine` defaults to `"swig"`; set to `"nunjucks"` to opt in. (b) `server.js` `initNunjucksEngine(conf)` runs alongside `initSwigEngine` during bundle init when `hasViews()` is true — if `render.engine === 'nunjucks'`, it calls `nunjucksResolver.load(self.executionPath, settings.nunjucks)` which throws `NUNJUCKS_NOT_INSTALLED` when the project has not `npm install`ed the package (bundle startup fails loud, not mid-render). (c) `controller.js` `this.render()` reads `local.options.conf.content.settings.render.engine` and dispatches to either `controller.render-swig.js` (default) or `controller.render-nunjucks.js`; both delegates receive the same `deps` object (`self`, `local`, `getData`, `hasViews`, `headersSent`, etc.), `render-nunjucks.js` fetches the engine via `lib.nunjucksResolver.get()` so the `swig`/`SwigFilters` deps are harmless when unused. Environment caching: `new nunjucks.Environment(loader, ...)` is cached per template root on `process.gina._nunjucksEnvs` and invalidated via `process.gina._nunjucksEnvsOwner` whenever the underlying nunjucks module itself is hot-swapped (dev-mode mtime drift on the project''s `package.json`). Dev-mode also sets `FileSystemLoader({ noCache: true })` so `.njk` template edits take effect on the next request. **Deferred relative to render-swig.js** — documented inline so nothing is hidden: (1) ~~Inspector `__gdPayload`~~ **shipped 2026-04-22** (commit `7aef191ac`) — `<script>window.__ginaData</script>` + `<script>window.__ginaLogs</script>` injected before `</body>` in dev mode via `injectInspectorScripts`, redacted through `lib/inspector-redact`, stashed on `serverInstance._lastGinaData` (+ `_lastGinaDataUnredacted` on local scope), emitted via `process.emit('inspector#data')`, wrapped in try/catch so Inspector bugs never break the page render. Within the Inspector port, three sub-items remain deferred: `statusbar.html` include (swig-templated), `data.page.flow` pipeline from `local._timeline`, `data.page.queries` from `local._queryLog`. (2) ~~HTTP/2 `stream.respond()` direct path~~ **shipped 2026-04-22** (commit `6b11fc6dc`) — `sendHtmlResponse` implements the four-way branch from `class.controller.md §7b` (HEAD×stream, HEAD×HTTP1.1, body×stream, body×HTTP1.1) with the `stream.destroyed || stream.closed` disconnect guard, pipeline-header merge via `local.res.getHeaders()`, and `local.res.headersSent = true` flag. (3) ~~Error-page template routing~~ **shipped 2026-04-22** — when `controller.js renderCustomError()` injects `errOptions.file = <absolute path>` from `bundleConf.content.templates._common.errorFiles[code]`, `render-nunjucks.js` now detects `localOptions.isRenderingCustomError === true`, reads the file via `fs.readFileSync`, and renders it with `env.renderString(source, data)`. `env.renderString` bypasses the `FileSystemLoader` (which rejects absolute paths and cannot reach shared-path error templates outside the bundle root). **Never recurses via `self.throwError`** — every failure mode (missing file, read error, render error) falls back to a minimal inline HTML body served through `sendHtmlResponse`, because a `throwError` call would re-enter this same branch and could loop infinitely. Defensive `localOptions.isRenderingCustomError = false` reset after render mirrors `render-swig.js` lines 804 and 1434. +14 source-inspection tests in `test/lib/render-engine-dispatch.test.js` (78 total in the dispatch suite, 116 total across the nunjucks track, full suite 3326 → 3340 green). (4) ~~Early Hints 103 auto-send~~ **shipped 2026-04-23** (#NJ4) — feature-complete confirmation only, no code change needed. The `#EH1` firing point at `controller.js:1034-1044` is engine-agnostic (reads `local.options.template.h2Links` and calls `self.setEarlyHints(_hints)` BEFORE the delegate dispatch); the data-feed was closed by #NJ2 because `deps.setResources` is the same function object (defined once in `controller.js:782`) passed to both delegates, and `setResources` → `getNodeRes` writes to `local.options.template.h2Links` at `controller.js:901` (CSS) / `:930` (JS) on HTTP/2 non-dev requests regardless of which delegate invoked it. Negative invariants in `test/lib/render-engine-dispatch.test.js §05f` lock in the single-source rule (no `h2Links` reads or writes anywhere in `render-nunjucks.js` module code; `#EH1` marker present only in `controller.js`). +22 source-inspection + behavioural tests (160 total in the dispatch suite, 198 across the nunjucks track; full suite 3452 → 3474). **Closes the four-session ASAP nunjucks parity track** (#NJ1 filters / #NJ2 setResources & assets / #NJ3 static HTML cache / #NJ4 Early Hints) — nunjucks bundles now have full feature parity with swig. (5) ~~static HTML cache writes~~ **shipped 2026-04-23** (#NJ3) — `writeCache(local, self, bundle, opt, htmlContent)` ported verbatim from `render-swig.js:35-129` (same guards, `static:<bundle>:<url>` key shape, memory/fs dispatch, sliding-window, `invalidateOnEvents`). Helper takes `local`/`self` explicitly because render-nunjucks.js does not hoist those into module scope the way render-swig.js does. Module-level `cache = new lib.Cache()` re-pointed per-request via `cache.from(self.serverInstance._cached)`. Call site runs AFTER `injectAssets` + `injectInspectorScripts` and BEFORE `sendHtmlResponse`; wrapped in try/catch so a cache-write failure never breaks the render. Miss-path `Cache-Control: <visibility>, max-age=N` header set in the same block. READ path is engine-agnostic already — `server.isaac.js:1012-1067` reads from `static:<bundle>:<url>` regardless of which engine populated the entry, so no read-side port was needed. +33 source-inspection + behavioural tests in `test/lib/render-engine-dispatch.test.js` §05e (138 total in the dispatch suite, 176 across the nunjucks track; full suite 3419 → 3452). Third of the four-session ASAP nunjucks parity track. (6) ~~`setResources` asset injection / `<gina>` layout placeholders~~ **shipped 2026-04-23** (#NJ2). (7) ~~Gina `SwigFilters` equivalents~~ **shipped 2026-04-23** (#NJ1) — `lib/nunjucks-filters` factory mirrors the 7 public `lib/swig-filters`, registered per-request via `env.addFilter`. Negative invariants locked by source-inspection tests in `test/lib/render-engine-dispatch.test.js`: framework `package.json` must never declare nunjucks; `render-nunjucks.js` must never `require("nunjucks")` directly (always through the resolver); dispatch default must stay `"swig"`; the `isRenderingCustomError` branch must never call `self.throwError` (would loop). Nunjucks contrast vs swig-resolver: no framework fallback (different contract — `get()` throws instead of returning a framework copy), no version floor (any installed version accepted), same mtime hot-swap mechanism. Precedent: `63e7e569f` (N1 resolver primitive), `0980a00b7` (N2 dispatch + render-nunjucks.js MVP), `7aef191ac` (Inspector `__gdPayload` port), `6b11fc6dc` (HTTP/2 stream.respond four-way branch), error-page template routing (commit `07b1ea087`), `6d5ab382` (#NJ1 filters), `b2466398` (#NJ2 setResources/injectAssets), `680c2637` (#NJ3 static HTML cache), and this commit (#NJ4 Early Hints 103 — closes the four-session nunjucks parity track), 2026-04-22 / 2026-04-23.
 
 68. **Local-tool path leaks have three surfaces — commit messages, changie YAML bodies, JSDoc comments in shipped source — and their cost scales with unpushed-commit backlog** — the CLAUDE.md HARD RULE on no-local-tool-paths-on-public-surfaces names the categories (filenames, directory names, feature-description mentions) but today's pre-flight scan before pushing 23 unpushed commits surfaced three distinct contamination surfaces that each need their own scanner. Notation: `<tool-dir>` = the ignored local-tool config tree named by the existing `.githooks/pre-commit` regex `(^|/)(CLAUDE\.md|\.claude[a-z]*)`; sub-paths below use `<tool-dir>/todo/<plan>.md`, `<tool-dir>/architecture/<file>.md`, etc. (1) **commit messages / bodies** — run `git log origin/<branch>..<branch> --format='%H%n%s%n%b%n==='` then pipe through the same regex the hook uses plus `anthropic|generated by|co-[aa]uthored-[bb]y|opus [0-9]`; today caught a `Plan: <tool-dir>/todo/<plan>.md` footer in three `#AI8 Phase 2b` commits (`79ed1fec5` / `13f767cff` / `1c6d39de3`). (2) **changie YAML bodies that ship as `CHANGELOG.md` content** — `.changes/unreleased/*.yaml` `body:` strings become the published changelog on npm + GitHub + the docs site. Today caught two entries (`Changed-20260422-141823.yaml`, `Changed-20260422-161419.yaml`) referencing `<tool-dir>/architecture/<file>.md §N` anchors. Scan with the leak-scan regex against `.changes/unreleased/*.yaml` before every `changie batch`. (3) **JSDoc comments in shipped source files** — `framework/v*/**/*.js` JSDoc headers travel inside the npm-packed tarball and are publicly visible via `npm view gina@<version>` + unpacked `node_modules/gina/`. Today caught a `sendHtmlResponse` JSDoc block in `controller.render-nunjucks.js` cross-referencing an internal architecture doc. Scan the full diff (`git diff origin/<branch>...<branch> -- | grep '^+' | grep -v '^+++'` piped through the leak-scan regex) not just the latest commit. **Neutral-replacement pattern**: `<tool-dir>/todo/<plan>.md` → "the internal plan doc"; `<tool-dir>/architecture/<file>.md §N` → "the internal architecture docs" (drop the `§N` anchor — it's meaningful only to a reader with access to the file). **Allowed exceptions** (do NOT rewrite): `.githooks/pre-commit`, `script/check_no_local_leak.js`, `.gitignore`, `.npmignore`, and the `CLAUDE.md` global rule itself — these ARE the leak-scan product functionality and must name the pattern they match. **Accumulation-tax observation**: skipping `git push` after each small-batch commit turns a one-commit remediation into a 5-of-23-commit rewrite pass at release time. The "Ship more in small batches" rule's "one commit per push when feasible" half is where the tax is paid — delay one week of pushes, pay a `git filter-repo --replace-text` + force-push + CI-wait round instead of a trivial `git push`. **Remediation commands** for an unreleased feature branch with mixed leaks: `git tag backup/<branch>-<date> <branch>` → write expressions file with `literal:<path>==><neutral>` lines → `git filter-repo --replace-text <file> --refs origin/<branch>..<branch> --force` (scoped to exclusive commits so origin's published history is untouched) → re-scan → `git push --force-with-lease origin <branch>`. Alternative for small commit counts with mixed message + content changes: cherry-pick-replay onto a temp branch from the origin baseline, `git commit --amend -m '<new msg>'` or edit + `git add <file>` + `git commit --amend --no-edit` for the problematic ones, then `git branch -f <branch> temp` and force-push. Precedent: this session's docs-repo PR `gina-io/docs#8` (3 commits rewritten via cherry-pick-replay for a shared-path filename + 2 msg mentions) and the deferred gina alpha release (5 commits queued for `git filter-repo --replace-text` per the internal release plan doc), 2026-04-22.
 
@@ -846,3 +846,5 @@ YAML indent trap: the heredoc body and the `EOF` terminator must land at column
 70. **Per-request mutation of a cached `nunjucks.Environment` is safe under Node's single-threaded event loop — as long as `env.render()` stays synchronous** — when porting `lib/swig-filters` → `lib/nunjucks-filters` for the nunjucks render path (#NJ1, 2026-04-23), two of the 7 filters (`getUrl`, `getWebroot`) need per-request context (`req`, `options`, `isProxyHost`). The obvious design is: build the env once per template root (cached on `process.gina._nunjucksEnvs`), register Gina's filters on it once at startup. That fails because filters would close over stale request context. The less-obvious safe design is: **register filters on the cached env on every request, immediately before `env.render()`** — `registerGinaFilters(env, self, local, localOptions)` after env construction and before `env.render(templateRel, data)`. The singleton factory (`NunjucksFilters.instance._options`) refreshes on every call, and filter functions read from the singleton during the render pass that follows synchronously. Why it's safe: (a) `env.render()` is synchronous (no `await`, no yield); (b) Node's event loop cannot interleave request A's `addFilter → render` sequence with request B — one completes before the other can touch the env; (c) nunjucks' `addFilter` silently replaces an existing filter of the same name, which is the desired behaviour (Gina's registry is authoritative for the 7 public names). Two hard invariants preserve the safety: (1) **`env.render()` MUST remain synchronous** — if a future session adopts `env.renderAsync()` or a custom async loader that yields between addFilter and the actual template execution, another request can race in and stomp the filter table. Any async-render port MUST switch to a per-request env (no cache), not keep this pattern. (2) **User-side `env.addFilter()` calls coexist** — user filters whose names DON'T collide with Gina's 7 are preserved across the loop because Gina only iterates its own `filters` object. A user-registered filter with the same name as one of Gina's 7 loses on every request (Gina wins last). Locked by source-inspection tests in `test/lib/nunjucks-filters.test.js` — §06 "registers filters AFTER env construction but BEFORE template render" enforces the ordering via a single regex with three landmarks; §07 negative invariants guard against copy-paste mistakes (no `swig.setFilter` in runtime code, the lib itself doesn't call `env.addFilter` — that's caller-side only, which keeps the lib portable to any future template engine). Precedent: `#NJ1` (2026-04-23) — first of four sessions in the nunjucks parity ASAP track (#NJ1–#NJ4, `0.3.7` roadmap). The same design works for any sync-render template engine (eta, liquid-sync); an async-render engine would need a different caching strategy.
 
 71. **The nunjucks render path needs BOTH a pre-render `setResources()` call AND a post-render `injectAssets()` pass — the two cooperate via exact-substring user-placement detection** — when porting the swig path's asset cataloguing + `<gina>` layout placeholder system (#NJ2, 2026-04-23), the obvious design is "do it one way or the other". Both fail. Pre-render-only: `data.page.view.stylesheets` / `.scripts` are populated, but only templates that explicitly reference `{{ page.view.stylesheets | safe }}` / `{{ page.view.scripts | safe }}` get any assets — existing bundles that relied on swig's auto-injection would silently ship no stylesheets. Post-render-only: assets are injected everywhere, but templates that DO reference `{{ page.view.stylesheets | safe }}` end up with the tags twice. The working design is: (1) `setResources(localTemplateConf)` runs before `env.render()` so `data.page.view.*` are populated for opt-in templates, (2) `injectAssets(html, data, localOptions)` runs after `env.render()` and auto-injects only when the rendered HTML does NOT already contain the exact stylesheet/script string. User-placement detection is exact-substring match on the final HTML — because `getNodeRes()` emits bundle-specific URLs (hostname + port + webroot), false-positive collisions with unrelated template content are essentially zero. Four additional invariants lock the port: (1) **`injectAssets` runs BEFORE `injectInspectorScripts`** — the Inspector payload (`__ginaData` / `__ginaLogs`) must remain the last `<script>` before `</body>` for dev-mode consumers; reversing the order scatters the payload above user scripts and breaks the flow panel's tail-reading heuristic. (2) **Both `setResources` and `injectAssets` wrap their bodies in try/catch and pass the un-mutated HTML through on any error** — a mis-shaped `localTemplateConf` (common during template migration) must NOT 500 the page. Swig's equivalent mutation runs at compile-time where failures have a separate error channel; the nunjucks pass inspects the production HTML and can't afford to fail. (3) **`isWithoutLayout` filters via `Collection.find({isCommon: false}, {isCommon: true, name: 'gina'})` after `JSON.clone(localTemplateConf)`** — mirrors `render-swig.js:494-498` exactly. The OR-clause keeps private user assets AND common-gina assets, drops common-other; cloning first prevents poisoning the bundle's cached template config object across requests. (4) **HEAD / partial / bodyless templates pass through unchanged** — `injectAssets` only inserts when `</head>` / `</body>` anchors exist in the HTML; it never grows truncated markup. `javascriptsDeferEnabled` controls whether scripts go before `</head>` or before `</body>`; `javascriptsExcluded === '**'` or an already-present `window.onGinaLoaded` suppresses the ginaLoader injection — both mirror swig-side semantics. Locked by +27 source-inspection + behavioural tests in `test/lib/render-engine-dispatch.test.js` §05d (78 → 105 in file, 3419/3419 suite-wide). Precedent: `#NJ2` (2026-04-23) — second of four sessions in the nunjucks parity ASAP track (#NJ1–#NJ4, `0.3.7` roadmap).
+
+72. **Socket's category flags (`Uses eval`, `Network access`, `Shell access`, `Install scripts`, `Obfuscated code`) are boolean per package — one site fires the flag for the whole tarball.** Before promising to "clear" a flag in a session, enumerate ALL sites in the published tarball — not just the ones visible while reading a single file. The enumeration path: `npm view <pkg>@<ver> dist.tarball` → `curl -sSL <url> -o pkg.tgz` → `tar tzf pkg.tgz` (**never** `npm pack --dry-run` without flagging the cost first — in gina it runs `prepare_version.js` which creates a "Prerelease update" commit). Then grep the extracted file list for the offending pattern, because `.npmignore` + `files:` in `package.json` exclude/include things that greps against the working tree miss. For `Uses eval`: both `\beval\s*\(` and `new\s+Function\s*\(` surface under the same Socket category. Hiding spots in gina: (1) **load-bearing** circular-require workarounds that LOOK like dead test-time fallbacks — `merge = eval(fs.readFileSync('.../merge/src/main.js'))` in `lib/logger/src/main.js:69` + the two logger containers (`file/index.js:16`, `mq/index.js:10`) fires when `require('../../merge')` returns a partial `{}` during the circular chain `merge → helpers → logger → merge-partial`. Eval is load-bearing here because it bypasses the require cache AND relies on `JSON.clone` being defined by the time it executes (so merge's own `typeof(JSON.clone) == 'undefined'` → `require('../../../helpers')` branch is skipped, breaking the circular). Removing the fallback without a runtime probe crashes every logger-consuming test with `TypeError: merge is not a function at init (logger/src/main.js:350)` — hand-on confirmation during the #SCS1c attempt (reverted 2026-04-23). Takeaway: any `eval`/`new Function` site wearing a `// if needed for unit tests` or `// publishing hack` comment is the FIRST suspect for load-bearing status; run the suite with the site commented out before writing a removal commit. (2) install-time scripts that ship via npm lifecycle (`script/pre_install.js`, `script/post_install.js`); (3) vendored client-side code shipped as-is (`core/plugins/lib/validator/src/*`); (4) CLI helpers that chain async work via generated function bodies (`lib/cmd/framework/build.js`, `lib/cmd/framework/init.js`) — same pattern, 4 call sites (CLEARED in #SCS1b, commit `04cd05b2`, 2026-04-23 — direct `promisify` + `try/await/catch` IIFE replaces the eval'd `async function on<Name>()` chain). Count BEFORE claiming a fix will clear a flag; the inverse (claim three, find twenty-one) is a credibility cost you can't redeem mid-session. The **replace-don't-delete convention** (`// #SCS1 (YYYY-MM-DD) — <why>` + commented-out old body on the preceding lines) serves as the navigation aid for future passes: `git grep '#SCS1' framework/v*/ | grep -v '^\s*//'` returns zero hits when every in-file tag has been properly paired with a comment block. Precedent: `#SCS1` (2026-04-23, commit `03eec441`) — three server-side sites replaced (`core/server.js:1870` eval→`new RegExp`; `lib/logger/src/main.js:525` `new Function`→closure factory; `lib/math/index.js:53` `new Function`→shunting-yard evaluator with `+ - * / %`, parens, decimals, unary sign, hard-fails on any non-arithmetic character). Socket's `Uses eval` flag still fires because the 21 remaining sites did not all prove removable: #SCS1b (`04cd05b2`) cleared the 4 async-chain sites cleanly; the 3 logger-container `merge = eval(...)` sites turned out to be load-bearing circular-require workarounds (#SCS1c reverted). The remaining real-work buckets are (a) structural refactor of the `merge → helpers → logger` circular chain so the eval fallback can be deleted without breaking init-time loads, (b) a safe expression parser for `lib/collection/src/main.js:90,383` (currently eval'ing user-supplied query strings — real attack surface), and (c) a separate session for the 12 client-side `core/plugins/lib/validator/src/*` evals. Three spot fixes + one pattern refactor cleared 7 of 24 eval sites; the rest are structural.

package/package.json

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