gina 0.5.6 → 0.5.7

package/llms.txt

@@ -331,7 +331,7 @@ ai.client.chat.completions.create({ ... });
 
 ## Async jobs (#AI6)
 
-Run slow work (e.g. a 1–30s `.infer()`) out-of-band so it doesn't tie up the request pipeline. `lib.job.create(fn, opts)` enqueues a deferred async function on a concurrency-limited worker (default 4) and returns a `jobId` immediately; state moves `pending → running → completed | failed`. Records live in an in-memory store behind a callback-shaped `set/get/remove/list/sweep` seam (connector-backed for multi-pod is a follow-up) with a self-contained unref'd `setInterval` TTL sweep — `lib/cron` is NOT involved.
+Run slow work (e.g. a 1–30s `.infer()`) out-of-band so it doesn't tie up the request pipeline. `lib.job.create(fn, opts)` enqueues a deferred async function on a concurrency-limited worker (default 4) and returns a `jobId` immediately; state moves `pending → running → completed | failed`. Records live behind a callback-shaped `set/get/remove/list/sweep` store seam — in-memory by default, or connector-backed via `app.json`'s `jobs.store` (SQLite for single-host durability, MongoDB or Redis for multi-pod visibility: records survive bundle restarts and are readable cross-process/pod — a job created on one pod is pollable from another — while the deferred function still runs only in the creating process) — with a self-contained unref'd `setInterval` TTL sweep — `lib/cron` is NOT involved.
 
 ```javascript
 // In a controller action — return immediately, work runs out-of-band:
@@ -346,7 +346,10 @@ var jobId = self.inferAsync([{ role: 'user', content: prompt }], { connector: 'm
 
 - Poll the built-in always-on `GET /_gina/jobs/:id` for `{ id, state, createdAt, updatedAt }` — state-only, never the result/error payload, works on both the Isaac and Express engines. Read a completed job's result from your own authenticated route via `self.jobStatus(id, cb)`.
 - Opt-in completion webhook: pass `{ callbackUrl }` to `create` / `startJob` and the framework POSTs `{ id, state, result, error }` on completion — best-effort with retry + exponential backoff (`webhookFailed` recorded after exhaustion, never affecting the job outcome). Set `app.json jobs.webhookSecret` to sign each payload with an `X-Gina-Signature` HMAC-SHA256 header.
-- Always-on with sane defaults; tune via `app.json jobs.*` (`maxConcurrency`, `ttl`, `sweepInterval`, `idSize`, `webhook*`). The deferred function runs after the response, so capture plain values — never `req`/`res`.
+- Always-on with sane defaults; tune via `app.json jobs.*` (`maxConcurrency`, `ttl`, `sweepInterval`, `idSize`, `retryBackoffMs`, `webhook*`). The deferred function runs after the response, so capture plain values — never `req`/`res`.
+- Failed-job retry (opt-in): pass `{ maxAttempts: N }` to `create`/`startJob` — a failed attempt is retried on the CREATING process with exponential backoff (`app.json jobs.retryBackoffMs`, default 1000 ms, doubling per attempt). Between attempts the record returns to `pending` with the last error and an informational `nextRetryAt` visible, and it can never be purged by the TTL sweep (`expiresAt` stays null until terminal); `failed`/`completed` are strictly terminal and the completion webhook fires exactly once, after the final attempt. Only the origin pod retries — the deferred function exists only in the process that created the job; other pods just read the shared record. The default `maxAttempts` of 1 keeps the exact runs-once behavior.
+- Durable (connector-backed) records: set `app.json` `jobs.store` to a `connectors.json` entry name — e.g. `"jobs": { "store": "jobsDb" }` with `"jobsDb": { "connector": "sqlite", "file": "/data/jobs.db" }` (single host), `"jobsDb": { "connector": "mongodb", "host": "127.0.0.1", "port": 27017, "database": "gina_jobs" }` (multi-pod — same `uri`/`host`/`database` keys as the MongoDB session store; the `mongodb` driver is resolved from the consuming project's `node_modules`, so `npm install mongodb` there), or `"jobsRedis": { "connector": "redis", "host": "127.0.0.1", "port": 6379 }` (multi-pod — same `host`/`port`/`db`/`password`/`tls`/`cluster` keys as the Redis session store; driver `ioredis`, resolved like the session store with a project-`node_modules` fallback, so `npm install ioredis` in the project works under every install topology). Each entry follows its OWN connector's config-key conventions: for sqlite use `file` for the path — the model layer also scans every connectors.json entry at boot and treats `database` as a NAME, so a path in `database` fails the boot before the job store is built; for mongodb `database` IS the (required) name; a redis entry needs no database name at all (keys are namespaced under a `prefix`, default `jobs:`). A configured store that cannot be built (bad entry name, missing implementation, unopenable file, missing driver) aborts the boot with a clear error — never a silent fall-back to memory; an absent `jobs.store` keeps the in-memory store, unchanged. Store `get`/`list` deliberately do NOT filter expired records — expiry acts only at sweep time, matching the memory store; the MongoDB store therefore never configures server-side TTL reaping (which would purge outside the seam — and the record's epoch-ms `expiresAt` is a number the Date-indexed TTL monitor would ignore anyway), and the Redis store never sets a per-key TTL for the same reason.
+- Redis job-store design: the record rides as a JSON string at `<prefix><id>`, with per-state id SETs (`<prefix>idx:state:<state>`) and a terminal-only expiry sorted-set (`<prefix>idx:expires`, score = epoch-ms `expiresAt`) maintained atomically with every write in one MULTI — so `list({state})` reads only matching ids, `sweep` reads only already-expired ids, and neither ever SCANs the keyspace. Redis Cluster works via a hash-tagged prefix (default `{jobs}:` in cluster mode; a custom cluster prefix without a `{tag}` fails fast at construction instead of CROSSSLOT errors at runtime). Also fixed alongside: a `"connector": "redis"` connectors.json entry previously aborted the bundle boot at the model scan (the connector shipped no boot connector file) — even the documented Redis session-store configuration could not boot; the connector now includes a no-op boot connector that opens no connection and requires no driver.
 
 ---
 
@@ -900,7 +903,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 163. **`request.rawBody` — the exact unparsed request body is snapshotted before parsing, for inbound-webhook HMAC verification.** The non-multipart end-of-stream handler in `core/server.js` (`request.on('end', onEnd)`) now sets `request.rawBody = (typeof request.body === 'string') ? request.body : ''` immediately BEFORE `processRequestData(request, response, next)` mutates `request.body` into the parsed object. Signed-webhook authentication computes an HMAC over the exact raw request bytes; by the time `app.use(...)` middlewares run the stream is drained and `request.body` is the parsed object, so a consumer middleware could not otherwise capture the raw bytes (consume-then-`next()` hangs the request; a passive `data`/`end` listener sees nothing). The snapshot is a reference assignment (zero-copy) and always-on — no opt-in flag. It is gated to the non-multipart branch only: the `multipart/form-data` path uses Busboy (`request.pipe(busboy)`) and never reaches `onEnd`, so uploads are unaffected. Empty bodies yield `''` (never the `{}` request-init object — `request.body` is initialised to `{}` and only becomes a string once the data handler appends a chunk, so the `typeof === 'string'` guard maps both empty and object cases to `''`). **Engine coverage:** `processRequestData` and this end-of-stream handler live solely in `server.js` and are the shared body pipeline for BOTH engines — `server.isaac.js` has no separate general body accumulation (its only `req.on('data')` is the bounded `/_gina/instrument` control reader), so the isaac engine is covered without an engine-specific mirror. Tests: `test/core/http-methods.test.js` §16 (source pins: snapshot-before-`processRequestData` ordering, the string guard, single-site / after-`request.pipe(busboy)` placement; behavioural replica of multi-chunk accumulation + snapshot; empty-body → `''`; an HMAC round-trip recomputed over `req.rawBody`; a subtract-my-contribution case proving a re-stringified parse breaks verification). Established 2026-06-09.
 
-164. **#B30 — a request with a malformed percent-escape in its URL or query string crashed the bundle (unauthenticated single-request DoS); fixed by crash-safe decode helpers + dropping a redundant double-decode.** Both `decodeURIComponent` AND `decodeURI` throw `URIError: URI malformed` on a malformed escape (a bare `%`, `%zz`, a truncated `%E0%A`); `proc.js`'s `uncaughtException` handler emits an `[ FRAMEWORK ][ uncaughtException ]` emerg and SIGTERM-shuts-down the bundle on a generic uncaught error, so any unguarded decode of attacker-controllable input on the request path was a single-request crash (the production trace: `processRequestData` GET branch → `onEnd` emit → emerg → SIGTERM → forced exit). Two defect classes, two fixes. **(1) Redundant double-decode (GET/HEAD)** — `processRequestData`'s GET/HEAD branches did `formatDataFromString(decodeURIComponent(request.query.inheritedData))` / `(bodyStr)`, but `request.query` is already percent-decoded once by the engine query parser AND `formatDataFromString` self-guards its own internal decode, so the explicit decode was a redundant SECOND decode that crashed on a literal `%` surviving the first decode (e.g. inheritedData `{"x":"50%off"}` → `%of`) and silently double-decoded valid data; DROPPED at all four sites (robust regardless of engine — `formatDataFromString` supplies the single guarded decode; behaviour byte-identical for the no-`%`-in-data case). **(2) Genuine first-decode (cannot drop)** — added `safeDecodeURIComponent` / `safeDecodeURI` DataHelper globals (`try { return decode…(str) } catch { return str }`, mirroring the POST/PUT/PATCH body branches) and routed every first-decode of attacker input through them: `server.isaac.js` query parser (`a[1]` ×2), `server.js` static path (`handleStatics` filename + `getAssetFilenameFromUrl` url), `helpers/data parseBody` (`arr[i]`/`el[0]`/`el[1]`), AND — the class the first pass MISSED (caught by adversarial review) — every `decodeURI` site (a SEPARATE function that throws the same `URIError`, used with a `/// avoid %20` comment on the routing + error paths): `server.js` ×3 (trie lookup, route params, `throwError`), `lib/routing/src/main.js` ×4 (cached params, `request.routing.path` ×2, linear-scan params), `controller.js` ×1 (error path). The `throwError` / `controller.js` error-path sites were worst — a malformed-`%` URL to a missing asset (`GET /assets/%E0%A.css`) reached `throwError` via the 404 path and crashed FROM the error handler (turning a would-be 404 into a crash); the async route-matching `decodeURI` sites instead rejected the dispatch promise → `unhandledRejection` (logged) → a *hung* request, now a clean 404. **NOT done:** no broadening of `proc.js`'s handler into a swallow-everything net (only known-benign TCP/HTTP codes are continued; generic errors still SIGTERM — swallowing arbitrary uncaught exceptions masks state corruption). **Deferred:** `formatDataFromString` still single-decodes an already-decoded value, so a literal `%20` in data still decodes to a space (no crash); fully fixing needs a no-decode variant (own consumer survey). **Lesson:** when sweeping a throwing-decode crash class, sweep BOTH `decodeURIComponent` AND `decodeURI`. Tests: `http-methods.test.js` §17 (GET/HEAD drop + first-decode pins, comment-stripped negatives) + §18 (the 8 `decodeURI` guards across server.js / lib/routing / controller.js), `server.isaac.test.js` §10 (query-parser safe-decode + `?x=%` replica), `format-data-from-string.test.js` (`safeDecodeURIComponent`/`safeDecodeURI` behavioural against the real loaded helper + subtract proving the pre-fix shape throws). Empirical repro (real DataHelper) reproduces the exact production `URIError` pre-fix and the clean result post-fix. Established 2026-06-10.
+164. **#B30 — a request with a malformed percent-escape in its URL or query string crashed the bundle (unauthenticated single-request DoS); fixed by crash-safe decode helpers + dropping a redundant double-decode.** Both `decodeURIComponent` AND `decodeURI` throw `URIError: URI malformed` on a malformed escape (a bare `%`, `%zz`, a truncated `%E0%A`); `proc.js`'s `uncaughtException` handler emits an `[ FRAMEWORK ][ uncaughtException ]` emerg and SIGTERM-shuts-down the bundle on a generic uncaught error, so any unguarded decode of attacker-controllable input on the request path was a single-request crash (the production trace: `processRequestData` GET branch → `onEnd` emit → emerg → SIGTERM → forced exit). Two defect classes, two fixes. **(1) Redundant double-decode (GET/HEAD)** — `processRequestData`'s GET/HEAD branches did `formatDataFromString(decodeURIComponent(request.query.inheritedData))` / `(bodyStr)`, but `request.query` is already percent-decoded once by the engine query parser AND `formatDataFromString` self-guards its own internal decode, so the explicit decode was a redundant SECOND decode that crashed on a literal `%` surviving the first decode (e.g. inheritedData `{"x":"50%off"}` → `%of`) and silently double-decoded valid data; DROPPED at all four sites (robust regardless of engine — `formatDataFromString` supplies the single guarded decode; behaviour byte-identical for the no-`%`-in-data case). **(2) Genuine first-decode (cannot drop)** — added `safeDecodeURIComponent` / `safeDecodeURI` DataHelper globals (`try { return decode…(str) } catch { return str }`, mirroring the POST/PUT/PATCH body branches) and routed every first-decode of attacker input through them: `server.isaac.js` query parser (`a[1]` ×2), `server.js` static path (`handleStatics` filename + `getAssetFilenameFromUrl` url), `helpers/data parseBody` (`arr[i]`/`el[0]`/`el[1]`), AND — the class the first pass MISSED (caught by adversarial review) — every `decodeURI` site (a SEPARATE function that throws the same `URIError`, used with a `/// avoid %20` comment on the routing + error paths): `server.js` ×3 (trie lookup, route params, `throwError`), `lib/routing/src/main.js` ×4 (cached params, `request.routing.path` ×2, linear-scan params), `controller.js` ×1 (error path). The `throwError` / `controller.js` error-path sites were worst — a malformed-`%` URL to a missing asset (`GET /assets/%E0%A.css`) reached `throwError` via the 404 path and crashed FROM the error handler (turning a would-be 404 into a crash); the async route-matching `decodeURI` sites instead rejected the dispatch promise → `unhandledRejection` (logged) → a *hung* request, now a clean 404. **NOT done:** no broadening of `proc.js`'s handler into a swallow-everything net (only known-benign TCP/HTTP codes are continued; generic errors still SIGTERM — swallowing arbitrary uncaught exceptions masks state corruption). **Deferred:** `formatDataFromString` still single-decodes an already-decoded value, so a literal `%20` in data still decodes to a space (no crash); fully fixing needs a no-decode variant (own consumer survey). **Lesson:** when sweeping a throwing-decode crash class, sweep BOTH `decodeURIComponent` AND `decodeURI`. Tests: `http-methods.test.js` §17 (GET/HEAD drop + first-decode pins, comment-stripped negatives) + §18 (the 8 `decodeURI` guards across server.js / lib/routing / controller.js), `server.isaac.test.js` §10 (query-parser safe-decode + `?x=%` replica), `format-data-from-string.test.js` (`safeDecodeURIComponent`/`safeDecodeURI` behavioural against the real loaded helper + subtract proving the pre-fix shape throws). Empirical repro (real DataHelper) reproduces the exact production `URIError` pre-fix and the clean result post-fix. Established 2026-06-10. **Sibling #B64 (path traversal → unauthenticated arbitrary file read, 2026-07-03, shipped 0.5.7):** the SAME two static resolvers built the served filename by raw concatenation — `handleStatics` (prefix-regex branch: `<statics mapping target> + '/' + <url remainder>`, or the `publicPath + pathname` default) and `getAssetFilenameFromUrl` (`content.statics[key] + <remainder>`, or the `publicPath + url` fallback) — guarded ONLY by an existence check, so a `../` (or `%2F` / `%2e%2e`, already settled by the #B30 `safeDecodeURIComponent`) escaped the mapping target to any sibling under the shared root (config/credentials/server-side source). `handleStatics` is the primary path (its `new RegExp('^'+staticResource)` prefix match accepts `/js/vendor/lib/../../../config/secret.json`); `getAssetFilenameFromUrl` also feeds the attacker-controlled HTTP/2-push path (`headers[':path']`). Fixed with a `confineToBase(filename, base)` sibling helper (`path.resolve` on both + separator-aware containment `_resolvedFile === base || _resolvedFile.indexOf(base + path.sep) === 0`, so `/srv/app/lib` can't be bypassed by `/srv/app/lib-secrets`) + a per-branch base capture (`_base`/`_staticBase` = the matched mapping target, else `publicPath`); on escape → notFound/404, identical to a missing file (no distinct signal). Placed right AFTER the #B30 decode so encoded variants are settled. Guards every caller (both engines — `server.js` is engine-agnostic, no `server.isaac.js` copy) and every sink (`fs.readFile`, `fs.createReadStream`, h2-push). Lexical only (no symlink following), mirroring the CVE-2023-25345 Layer-2 idiom in `controller.render-swig.js`. Tests: `server-static-traversal.test.js` (real extracted `confineToBase` + source-pins on both guard sites + real-fs replica of all three encodings on both resolvers + a subtract proving the pre-fix leak); full suite 9727/0.
 
 165. **The dev-mode Inspector statusbar (and its launch link) vanished on content-heavy pages because `String.replace(/re/, str)` expanded dollar-patterns in the replacement STRING (`0ba469d0`, 2026-06-10).** `render-swig.js` splices its inline dev scripts before `</body>` via `layout/htmlContent.replace(/<\/body>/i, content + '...')`. With a STRING replacement, `String.prototype.replace` expands dollar-sequences found in `content`: dollar-backtick = the text BEFORE the match (prematch), dollar-quote = AFTER (postmatch), `$&` = the match, `$1`/`$2` = capture groups (empty when the regex has none). The inlined #TPL2 statusbar body legitimately carries a dollar-backtick (in a regex-explaining comment) and a dollar-quote (in a regex literal), so the prematch spliced the ENTIRE document before `</body>` INTO the statusbar `<script>` → `SyntaxError` → the statusbar IIFE never ran (no statusbar host, no `ginaToolbar` shim, no link). Volume-dependent: a near-empty page (gina-starter) has a tiny prematch and renders fine — the bug only manifests on a real content-heavy render, so a gina-starter smoke is falsely green. The two sibling flow-patch splices (cache-hit + cache-miss) had the same latent exposure via SQL `$1`/`$2` placeholders captured in the flow `detail`. **Fix: function replacers** — `html.replace(/<\/body>/i, function () { return frag + '</body>'; })` inserts the return value verbatim with no dollar-expansion (escaping `$`→`$$` works too, less clear). The popin-XHR splices were already safe — `encodeRFC5987ValueChars` percent-encodes `$`→`%24`. **General rule: any `String.replace(re, X + ...)` where X is dynamic (JSON, user data, an inlined template, captured query/flow text) must use a function replacer or escape `$`** — a string replacement is a latent injection. render-swig.js is server-side (not in the browser bundle) so the fix needs no dist rebuild; it hot-reloads per render in dev/cacheless mode (so a running dev bundle picks it up on the next render). Tests: `render-swig.test.js §18` (3 source pins locking the function replacers + a pure-logic replica proving the old string form duplicates the document while the function replacer does not + a guard that the shipped statusbar actually carries a dollar-sequence). Established 2026-06-10.
 
@@ -951,7 +954,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 188. **The multipart upload handler now honours the configured destination dir and the maxFields / maxFieldsSize limits — three documented settings.json keys were inert (#B49 + #B51, 2026-06-16, commits `0df499a6` + `15ceff06`).** `core/server.js`'s `multipart/form-data` branch carried three dead `upload.*` config keys: (1) **#B49** — it streamed each file via `opt.uploadDir`, a key the shipped `settings.json` never sets (it defines `upload.tmpPath` + per-group `path`, and nothing mapped `tmpPath`→`uploadDir`), so every upload landed in `os.tmpdir()` and the documented dir keys did nothing; (2) **#B51** — `upload.maxFields` (default 1000) was declared but read nowhere, so a group allowing multiple files accepted an UNBOUNDED count (only the binary per-group `isMultipleAllowed` capped anything); (3) **#B51** — `maxFieldsSize` dropped its unit suffix (`parseInt("512K")` → 512, then compared as 512 MB, so `"512K"` silently meant 512 MB). Fixes: (#B49) global dir = `opt.uploadDir || opt.tmpPath || os.tmpdir()`, a per-group `path` override at both write sites, AND an mkdir-if-missing before `createWriteStream` — required because the writeStream `'error'` handler is only attached later, in the busboy `'finish'` loop, so a missing CUSTOM dir would emit an unhandled ENOENT during streaming and crash the bundle (the default `<project>/tmp` is created at boot, but a custom dir is not); (#B51) a global `maxFields` file-count cap (`throwError(400)` once `fileCount > maxFields`, with `0`/unset/NaN disabling it), and a local `parseSize` helper reading B/KB/MB/GB (a bare number = MB for back-compat) into bytes so `content-length` is compared in bytes. The `${tmpPath}` placeholder in `tmpPath`/`path` resolves to an absolute dir at config-load via `whisper` (→ `<project>/tmp`), so the fix reads a real value. Back-compat: the shipped `"2MB"` is unchanged; a non-MB `maxFieldsSize` suffix now means what it says (a tighter limit) — a `Fixed` changie note. `server.js` is server-side (not in the browser bundle) → no dist rebuild. Rule: a documented config key is only real if a code path reads it — grep the consumer before assuming a setting works. Tests: `test/core/upload-config.test.js` (source pins comment-stripped per the negative-pin trap + dir-resolution / parseSize / maxFields replicas + a real-fs throwaway-dir mkdir behavioural test).
 
-189. **An async render delegate must capture per-request inherited refs FUNCTION-scoped, not module-scoped — a module-scoped `self`/`local` races across concurrent renders (#INS10 race fix, 2026-06-17, commit `8674c514`).** `controller.render-swig.js` assigned `self`/`local` at MODULE scope (no `var`), so two concurrent renders shared one binding. Because the Inspector emit (the #INS10 prod-window egress + the dev `inspector#data` emit) reads `self`/`local` AFTER the layout `await`, a render suspended at that await could have its `self`/`local` overwritten by another request and then emit the OTHER request's `_queryLog`/`_timeline`. LOW severity — the channel is authenticated operator-only + time-boxed and the payload is the operator's own bundle (a correctness glitch, not an external leak) — but a real cross-request bleed. Fixed by capturing them function-scoped (`var self = deps.self; var local = deps.local;`) at the render() deps-unpack and dropping them from the module-level inherited-ref chain, matching the #M1 `req`/`res`/`_next` captures and `render-nunjucks.js` (always function-scoped, hence always race-clean). `getData`/`hasViews`/`SwigFilters`/`headersSent` stay module-scoped on purpose: they are read BEFORE the first await, so they are not a race vector (only the measured vector was changed). `render-swig.js` is server-side (not in the browser bundle) → no dist rebuild. Rule: any async (multi-`await`) render delegate that reads a per-request ref AFTER an await must hold it in a function-scoped capture, never a module-scoped binding. Tests: `render-swig.test.js` §12 (a2).
+189. **A render delegate must hold ALL per-request state FUNCTION-scoped — in prod the delegate module is a shared singleton across concurrent requests, and any module-scoped capture races (#INS10 `8674c514` 2026-06-17; sweep completed by #B61/#B62/#B63 `1b3abd97`/`2a838c1b`/`1bd0bcf1`, 2026-07-03).** Module-scoped deps are reassigned by every incoming call, and two overlapping renders BOTH suspend at their first await before either resumes, so the first deterministically resumes with the second's bindings. #INS10 function-scoped `self`/`local` in the swig delegate (the post-await Inspector emit carried the other request's `_queryLog`/`_timeline`) but deliberately left getData/hasViews/setResources/SwigFilters/headersSent/cachePath module-scoped, claiming they are "read before the first await" — MEASURED FALSE: the setResources call and the `merge(data, getData())` restore run AFTER the template-read await, so request A's resume executed request B's closures and gap-filled B's page data (session card included) into A's render context (#B61; the engine ref was also an implicit global). The streaming delegate's fire-and-forget IIFE read module `self`/`local` after its `for await`: a finishing stream nulled the CONCURRENT request's `local.req/res/next` mid-stream (routing its later renders into the released-response guards) while never releasing its own, and reported stream errors through the wrong controller (#B62). The JSON delegate's writeCache resumed from its writeFile await reading module `self`, routing a cache-config error through the concurrent request's controller (#B63 — writeCache now takes `req`/`res`/`cacheIsEnabled`/`throwError` as parameters, the same threaded shape as the swig cache writer, and the write-only module `cachePath` is removed as dead). All live delegates are now free of module-scoped per-request state (nunjucks + the async ALS variants always were; the legacy v1 delegate keeps the old pattern but is dead code — never dispatched); each delegate's test file pins the discipline (module prefix declares no per-request vars) plus an interleaved-replica subtract reproducing the measured asymmetry. All three server-side only — no dist rebuild. Rule: in a shared-singleton delegate, per-request state is function-scoped, PERIOD — never adjudicate per-variable "only read pre-await" inertness (that claim rotted once and measured wrong); module-level helpers take render-scoped values as parameters. Tests: `render-swig.test.js` §21, `render-stream.test.js` §12, `render-json.test.js` §04.
 
 190. **Per-bundle `/_gina/*` Inspector endpoints must derive their base URL with the 3-fallback resolver (`?target=` → opener pathname → strip), not a bare `window.location.pathname` strip — a bare strip misroutes to the proxy's default bundle in reverse-proxy multi-bundle setups (2026-06-17, commit `f04cf52c`).** Where several bundles share a host and differ only by a path prefix (`/a` → bundle A, `/b` → bundle B), the Inspector SPA's `fetchLiveIndexes` (`/_gina/indexes`) and `tryServerLogs` (`/_gina/logs`) built their URL from `window.location.pathname.replace(/\/_gina\/inspector.*$/, '')` — the Inspector's OWN path — so a bare `/_gina/logs` hit the proxy's default bundle, not the monitored one. Fixed by extracting `toggleReveal`'s existing 3-fallback resolver into a shared `resolveBundleBase()` and routing those two through it. `/_gina/agent` is NOT a misroute vector (the architecture note that flagged it overstated): `tryAgent`/`tryAgentWS` are `?target=`-gated and `tryAgentPassive` already uses the opener-pathname fallback (verified). `toggleReveal`/`tryAgentPassive`/refresh-re-reveal keep their inline copies (pinned by `inspector.test.js` §54/§55/§56) — full dedup is a deferred cleanup needing a test-pin update. SPA src edit → prod dist rebuild: `inspector.js` is a verbatim src→dist copy, so only `dist/.../inspector/inspector.js` changes (no `gina.min.*` drift). Rule: any new per-bundle `/_gina/*` consumer in the SPA must call `resolveBundleBase()`, never a bare pathname strip. Tests: `inspector.test.js` §79. **Follow-up (2026-06-17, commit `0066c78e`):** the 3 inline copies (`toggleReveal`, `tryAgentPassive`, refresh re-reveal) were folded into `resolveBundleBase()` — every per-bundle `/_gina/*` consumer now uses the one resolver. `tryAgentPassive` was a 2-fallback (no `?target=`); folding widens it to 3, but the `?target=` branch is inert there (it only runs when `source !== 'agent'`, i.e. no `?target=`). §54/§55/§56 pins re-aimed from inline-text greps to `resolveBundleBase()`-call assertions (the resolver's own 3-fallback/try-catch internals stay pinned in §79). inspector.js is a verbatim src→dist copy → only `dist/.../inspector/inspector.js` rebuilt (no `gina.min.*` drift). No behavior change (no changie).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -73,12 +73,12 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.5.6/core/gna",
+  "main": "./framework/v0.5.7/core/gna",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "import": "./index.mjs",
-      "require": "./framework/v0.5.6/core/gna.js"
+      "require": "./framework/v0.5.7/core/gna.js"
     },
     "./gna": {
       "types": "./types/gna.d.ts",
@@ -122,7 +122,7 @@
     "jsdom": "^29.1.1",
     "nunjucks": "^3.2.4",
     "requirejs": "^2.3.7",
-    "sass": "1.100.0"
+    "sass": "1.101.0"
   },
   "overrides": {
     "ws": "^8.21.0"

package/script/check_no_local_leak.js

@@ -176,8 +176,22 @@ try {
     var pathMatches = [];
     var contentMatches = [];
 
-    for (var i = 0; i < parsed.length; i++) {
-        var files = parsed[i].files || [];
+    // npm <= 11 emits an ARRAY of pack entries; npm 12 emits an OBJECT keyed
+    // by package name (pack/publish JSON output synchronized in npm 12).
+    // Normalize both to an entries array — and fail CLOSED below when zero
+    // files were recognized: an unknown output shape must block the publish,
+    // never vacuously pass (under npm 12 the old array-indexed loop iterated
+    // zero times and reported a clean pack without scanning anything).
+    var entries = Array.isArray(parsed)
+        ? parsed
+        : ( (parsed && typeof parsed === 'object')
+            ? Object.keys(parsed).map(function(k) { return parsed[k]; })
+            : [] );
+    var totalFiles = 0;
+
+    for (var i = 0; i < entries.length; i++) {
+        var files = entries[i].files || [];
+        totalFiles += files.length;
         for (var j = 0; j < files.length; j++) {
             var p = files[j].path;
 
@@ -194,6 +208,12 @@ try {
         }
     }
 
+    if (totalFiles === 0) {
+        console.error('[prepack] ERROR: unrecognized `npm pack --json` output shape — zero files scanned.');
+        console.error('[prepack] Failing closed — the leak scan must never pass without scanning the pack listing.');
+        process.exit(1);
+    }
+
     var failed = false;
 
     if (pathMatches.length > 0) {

package/script/smoke_in_container.js

@@ -233,8 +233,14 @@ async function main() {
         log('bun add -g ' + TARBALL + ' ...');
         inst = spawnSync('bun', ['add', '-g', TARBALL], { stdio: 'inherit', timeout: 600000 });
     } else {
-        log('npm install -g ' + TARBALL + ' (runs pre/post-install) ...');
-        inst = spawnSync('npm', ['install', '-g', TARBALL], { stdio: 'inherit', timeout: 600000 });
+        // npm 12 blocks dependency install scripts by default (allowScripts).
+        // A tarball install resolves to a file: identity, so the name-based
+        // `--allow-scripts=gina` opt-in cannot match it — the all-scripts
+        // escape hatch is the only opt-in that works for a tarball, and this
+        // is a throwaway container. Harmless on npm <= 11: unknown CLI
+        // configs only warn there, and install scripts already run by default.
+        log('npm install -g ' + TARBALL + ' --dangerously-allow-all-scripts (runs pre/post-install) ...');
+        inst = spawnSync('npm', ['install', '-g', TARBALL, '--dangerously-allow-all-scripts'], { stdio: 'inherit', timeout: 600000 });
     }
     if (inst.error) { fail('could not run the ' + RUNTIME + ' installer: ' + inst.error.message); return die(1); }
     if (inst.status !== 0) { fail('global install exited ' + inst.status); return die(1); }

package/script/smoke_test_tarball.js

@@ -146,7 +146,14 @@ function pack(destDir) {
     if (r.status !== 0) throw new Error('npm pack failed:\n' + (r.stderr || r.stdout || '(no output)'));
     var meta;
     try { meta = JSON.parse(r.stdout); } catch (e) { throw new Error('could not parse `npm pack --json` output:\n' + r.stdout); }
-    var filename = meta && meta[0] && meta[0].filename;
+    // npm <= 11 emits an ARRAY of pack entries; npm 12 emits an OBJECT keyed
+    // by package name (pack/publish JSON output synchronized). Accept both.
+    var entries = Array.isArray(meta)
+        ? meta
+        : ( (meta && typeof meta === 'object')
+            ? Object.keys(meta).map(function(k) { return meta[k]; })
+            : [] );
+    var filename = entries[0] && entries[0].filename;
     if (!filename) throw new Error('could not determine packed tarball filename from `npm pack --json`');
     return path.join(destDir, filename);
 }

package/framework/v0.5.6/VERSION

@@ -1 +0,0 @@
-0.5.6

package/framework/v0.5.6/core/connectors/redis/index.js

@@ -1,30 +0,0 @@
-/*
- * 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.
- */
-'use strict';
-
-/**
- * Redis connector — v1: session store only.
- *
- * Entity/ORM wiring is not implemented in v1.
- * Use this connector exclusively as a session store backend via `lib.SessionStore`.
- *
- * To configure:
- *   1. Add a `redis` entry to `config/connectors.json` in your bundle.
- *   2. Install ioredis in your project: `npm install ioredis`
- *   3. Wire the store in `bundle/index.js` — see: core/connectors/redis/lib/session-store.js
- *
- * ORM / entity support is planned for a future release.
- *
- * @class Redis
- * @constructor
- */
-var Redis = function Redis() {
-    // v1: no entity wiring — session store only
-};
-
-module.exports = Redis;