gina 0.6.1 → 0.6.2

package/framework/{v0.6.1 → v0.6.2}/lib/swig-filters/src/main.js

@@ -94,7 +94,18 @@ function SwigFilters(conf) {
 
     var getInstance = function() {
         if (conf) {
-            self.options = SwigFilters.instance._options = JSON.clone(conf);
+            // #P39 — stash by REFERENCE. The former per-call deep copy of the
+            // whole wrapper (whose `.options` is the render's `local.options`,
+            // itself already private per request — #M1) doubled the single
+            // heaviest clone in the render profile for zero isolation gain:
+            // `_options` is never written outside this assignment (the merge in
+            // getUrl/getWebroot fills a fresh `{}` target and only READS this),
+            // and `req`/`res` always passed by reference anyway (the cloner
+            // bails on non-plain constructors). `self.options` is kept in the
+            // chain for the boot-branch shape parity, but note `self` here is a
+            // throwaway per-call object — `SwigFilters.instance` is what every
+            // consumer reads.
+            self.options = SwigFilters.instance._options = conf;
         }
 
         return SwigFilters.instance

package/framework/{v0.6.1 → v0.6.2}/lib/uuid/src/main.js

@@ -25,7 +25,7 @@
 
 var _alphabet = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
 var _mask = 63;  // smallest (2^n - 1) >= 62 — rejects 62,63 (~3% waste, no bias)
-var _step = 7;   // ceil(1.6 * 63 * 4 / 62) — enough random bytes per iteration
+var _step = 7;   // ceil(1.6 * 63 * 4 / 62) — random bytes per iteration for the DEFAULT size 4 (#P39: larger sizes compute their own)
 
 /**
  * Generate a cryptographically secure random ID.
@@ -35,10 +35,19 @@ var _step = 7;   // ceil(1.6 * 63 * 4 / 62) — enough random bytes per iteratio
  */
 function uuid(size) {
     size = size || 4;
+    // #P39 — size the random-byte batch to the REQUESTED length, the same
+    // formula customAlphabet() below already uses for its default size. The
+    // fixed 7-byte batch was sized for the 4-char default, so uuid(16) — the
+    // form lib/collection mints per item — needed ~3 webcrypto calls per id;
+    // one right-sized call replaces them. Each getRandomValues call pays a
+    // full randomFillSync regardless of byte count, so the cost is the call
+    // count, not the bytes. Output distribution is untouched: the bitmask
+    // rejection below is applied per byte exactly as before.
+    var step = (size <= 4) ? _step : Math.ceil(1.6 * (_mask + 1) * size / _alphabet.length);
     var id = '';
     while (true) {
-        var bytes = crypto.getRandomValues(new Uint8Array(_step));
-        for (var j = 0; j < _step; j++) {
+        var bytes = crypto.getRandomValues(new Uint8Array(step));
+        for (var j = 0; j < step; j++) {
             var idx = bytes[j] & _mask;
             if (idx < 62) {
                 id += _alphabet[idx];

package/framework/{v0.6.1 → v0.6.2}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "dependencies": {
     "@rhinostone/busboy": "^1.6.1",
     "@rhinostone/swig": "^2.7.2",

package/gna.js

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

package/llms.txt

@@ -816,7 +816,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 - **Two-guard `@<project>` requirement asymmetry in `lib/cmd/helper.js`** — a `project:*` command that should run without `@<project>` must be exempted in BOTH guards: the early task-shape guard (`!/^project\:(list|help|status)/`) AND the later projectName-resolution guard (`!/\:list$/.test(cmd.task)` → widened to also allow `^project:status$`). Exempting only the first leaves the second falling through to cwd-project-inference and a "No project name found" error before the handler runs. `project:list` is the working precedent that null `projectName` survives `loadAssets()`.
 - **Single-bundle CLI handlers read `cmd.name` / `self.name`, NOT `self.bundle`** — CmdHelper sets `cmd.name = cmd.bundles[0]` only when exactly one bundle positional is present (`lib/cmd/helper.js`, the `cmd.bundles.length == 1` branch); `cmd.bundles` is the array for bulk operations. There is no `self.bundle` property. Precedent: `bundle:stop` / `bundle:start` / `bundle:status` all read `self.name`. (Worked example: a sub-agent investigation reported the slot as `self.bundle`; a single read of `helper.js` refuted it before the handler shipped — verify agent-relayed property names against source.)
 - **`gina start` does not need sudo with a user-prefix install** — `npm install -g --prefix ~/.npm-global` (standard Gina setup) runs as the current user and doesn't touch `/var/run/`. The "Needs to be launched as [sudo]" comment in `lib/cmd/framework/start.js` only applies to system-wide installs.
-- **`gina start` exits with code 1 even on success** — the startup script detaches the daemon; the shell child exits 1 as part of detachment. Always use `gina status` to confirm rather than the exit code. Sibling: a `gina start` framework server left running can hang the full test suite AND bundle boot via stale `~/.gina/procs.json` forcing the server onto a non-canonical port (see `cli-handlers.md § 11`).
+- **`gina start` exits with code 1 even on success** — the startup script detaches the daemon; the shell child exits 1 as part of detachment. Always use `gina status` to confirm rather than the exit code. Sibling: a `gina start` framework server left running can hang the full test suite AND bundle boot — the hang is the MQ log-listener connect left pending forever against a degraded daemon; a daemon on a non-canonical port traces to a corrupted persisted `port` in `~/.gina/<shortVersion>/settings.json`, not to `~/.gina/procs.json`, which no boot path reads (its only consumers are `gina stop`'s kill targeting and an address-in-use diagnostic). #B180 (fixed): `removeRunningProc()` deleted the registry entry under the constructing bundle's key instead of the key matched by pid, so dead `gina-*` records were rewritten back instead of removed (and a live record could be destroyed when the keys differed) — a `procs.json` written by an older framework may still carry stale dead entries; with the daemon stopped, clearing the file once is safe.
 - **CLI reserved flags — `--port` and `--version` must be renamed in subcommands** — both consumed by the framework's global CLI parser (`utils/helper.js::filterArgs` + `bin/cli:301`) before the subcommand sees argv. Use domain-prefixed forms: `--connector-port=`, `--driver-version=`. Un-prefixed forms are silently swallowed.
 - **CLI scope grammar — positional-absence, not flags** — for commands that apply to either a single bundle or the whole project, use `[<bundle>] @<project>` and signal project-wide by omitting `<bundle>`. Never reintroduce `--scope=bundle` (`scope` is reserved for data isolation: local/beta/production/testing) or `--shared`.
 - **`connector:rm` never runs `npm uninstall`** — a driver removed from one bundle's `connectors.json` may still be needed by another bundle in the same project (npm resolves `node_modules/<driver>/` once per project). Handler prints a driver-retention hint naming siblings (shared + other bundles) that still reference the same driver; sqlite exempt. Project-level `connector:rm` consults a usage guard — pass `--force` to bypass.
@@ -959,7 +959,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 259. **Server-side error responses strip stack traces outside local scope — the engine-level throwError sanitizes centrally; the full stack goes to the server log (2026-07-20, rides the next cut).** Two throwError implementations exist: the controller-side one (scope-gated since 0.5.x — it strips the `stack` FIELD outside local scope) and the SERVER-side engine-attached one, whose feeders (router action/middleware catches, server internals) flatten `err.stack` INTO the message string — so non-local 500 bodies used to carry absolute framework paths + stack frames in the JSON `error` field, the inline HTML error fallback, and custom-error page data. The server-side throwError now detects a stack-bearing message (`/\n\s+at\s/`, the V8 frame format) outside local scope, logs the FULL text server-side, and ships only the message line; an object msg has `.stack` logged then stripped off a clone (the caller's object is untouched). Local scope is byte-identical — the dev toolbar reads the stack off the wire. The gate reads the same NODE_SCOPE_IS_LOCAL env var as the controller-side gate (set once at bootstrap), deliberately NOT the config-derived per-bundle scope flag: that flag derives from the project's DEFAULT scope and can lag a boot started with an explicit NODE_SCOPE/--scope. Siblings fixed with it: the JSON render delegate's HTTP/1.1 reason-phrase catch ships `err.message` (a multi-line reason phrase is invalid on the HTTP/1.1 status line — Node rejects the write), and the cached-file stream error path ships message-only. Consumers who relied on wire stacks for service-to-service debugging keep them on LOCAL scope only; everywhere else the server log carries the diagnostic.
 
-260. **A bundle with a missing or unreadable config/routing.json REFUSES to boot (matching the malformed-JSON path), and the route-lookup not-found error names the bundle + its rule count (2026-07-20, rides the next cut).** Bundle config hydration is readdir-driven: a routing.json absent at boot readdir time was never iterated, so the bundle silently booted with only the framework-synthetic routes (bundle-status, custom-error-page, webroot + the upload endpoints) — every app route 404'd and a sibling bundle's cross-bundle route lookup threw hours later with a message indistinguishable from a mistyped rule; there is no prod re-hydration. The config loader now tracks whether the config-file loop resolved a REAL routing config (bundle dir or shared-config complement; env-versioned `routing.<env>.json` variants ride their base file's iteration, so an env-only file still refuses — it never loaded anyway) and otherwise fails the boot with an error naming the bundle + environment; an EXTERNAL supervisor restart (an orchestrator liveness/restart, a container restart policy such as restart=always, an init system) then retries until the release tree settles, so a mid-deploy race self-heals — gina's own daemon does NOT retry a startup crash: it reports `crashed during startup` once and stops, so a bare `gina bundle:start` deployment is fail-stop until a manual restart. BEHAVIOR CHANGE: a deployment that relied on the silent half-boot must fix its release artifact. The `RoutingHelper::getRouting` not-found throw keeps its historical prefix and appends `(bundle <name> holds N rules)`, so a degraded or near-empty table is tellable from a plain mistyped rule — browser bundle included (dist rebuilt).
+260. **A bundle with a missing or unreadable config/routing.json REFUSES to boot (matching the malformed-JSON path), and the route-lookup not-found error names the bundle + its rule count (2026-07-20, rides the next cut).** Bundle config hydration is readdir-driven: a routing.json absent at boot readdir time was never iterated, so the bundle silently booted with only the framework-synthetic routes (bundle-status, custom-error-page, webroot + the upload endpoints) — every app route 404'd and a sibling bundle's cross-bundle route lookup threw hours later with a message indistinguishable from a mistyped rule; there is no prod re-hydration. The config loader now tracks whether the config-file loop resolved a REAL routing config (bundle dir or shared-config complement; env-versioned `routing.<env>.json` variants ride their base file's iteration, so an env-only file still refuses — it never loaded anyway) and otherwise fails the boot with an error naming the bundle + environment; an EXTERNAL supervisor restart (an orchestrator liveness/restart, a container restart policy such as restart=always, an init system) then retries until the release tree settles, so a mid-deploy race self-heals — gina's own daemon does NOT retry a startup crash: it reports `crashed during startup` once and stops, so a bare `gina bundle:start` deployment is fail-stop until a manual restart. BEHAVIOR CHANGE: a deployment that relied on the silent half-boot must fix its release artifact. The `RoutingHelper::getRouting` not-found throw keeps its historical prefix and appends `(bundle <name> holds N rules)`, so a degraded or near-empty table is tellable from a plain mistyped rule — browser bundle included (dist rebuilt). **SIBLING REFUSAL — the project `env.json` block (#B181(b), 2026-07-31, unreleased).** The same function refuses one step earlier when `envConf[bundle][env]` is absent: the bundle list is built inside the env.json template-merge loop, so an env.json that is ABSENT (`userConf` stays `false`), empty, or that declares only bundles the manifest does not list yields an EMPTY list — `bundles[b]` is then undefined, `bundle` falls back to `startingApp`, and `setServerCoreConf` dereferenced a block that was never populated, dying as an uncaughtException (`Cannot read properties of undefined (reading '<env>')`, exit 143) that named neither env.json nor the bundle. It now refuses through the same `callback(new Error())` path (exit 1), naming the bundle, the env, the resolved env.json path, and whether the file was found at all — so a MISSING file and a present-but-incomplete one give different remedies; `setServerCoreConf` also throws a named error for any direct caller. Measured on fresh isolated scenes: the scaffolded-env.json baseline still boots and serves, and all three degenerate shapes refuse cleanly — the predicate can only fire where the boot ALREADY crashed, so it cannot refuse a working configuration. **SIBLING — the missing `host` default (#B181(a), 2026-07-31, unreleased).** `host` was the ONLY key the per-bundle configuration reads that carried no framework-side default — absent from both the env and settings templates, and written solely by the CLI into the project's own env.json — so a hand-written or PARTIAL block (one setting, say, only `server.cache`) left it undefined. Unknown `${...}` tokens are preserved verbatim and silently by design, so the `server.credentials` paths rendered as `.../certificates/scopes/<scope>/${host}/private.key`, the https/HTTP-2 read ENOENT'd, and the boot exited pointing at the server settings rather than at the missing key. The env template now carries the same `localhost` default the CLI already writes, so the existing deep-fill merge supplies it; an omitted declaration is warned (naming bundle + env) instead of defaulting silently, and a project that declares `host` is untouched because the merges are target-wins. NOTE the merge was EXONERATED as the cause: every env.json merge is override-off, i.e. a deep target-wins FILL — the shallow `override=true` wholesale-replace exists only on the dev-mode `env.local.json` path, a different surface. **SIBLING — the declared-but-not-for-this-env shape (#B183, 2026-08-01, unreleased).** `newContent[app][env].bundlesPath` was assigned one line BEFORE the `typeof(content[app][env])` guard that exists to protect exactly that dereference; since `newContent` is a deep clone of `content`, that property is undefined for precisely the apps the guard rejects. Booting an env a declared bundle carries no block for therefore threw `Cannot set properties of undefined (setting 'bundlesPath')` at exit 143, ~750 lines before (b)'s refusal could fire — (b)'s coverage of this fourth shape was replica-only and never live-verified, which is why it read as covered. The assignment now sits INSIDE the guard: the STARTING bundle reaches (b)'s named refusal (exit 1, naming bundle + env + env.json path), and a NON-starting bundle skipped for the booting env is WARNED (naming bundle + env) rather than vanishing from the boot silently — the guard's else branch was previously empty, so a skipped sibling left no trace. Live A/B in both directions on fresh isolated scenes (control boots; mutated scene died at `config.js:786` before, refuses cleanly after). **And a DELETED env.json does not stay deleted:** the CLI recreates it as `{}` on the next command of any kind, and `{}` is precisely the (b) shape — so the historical "the crash persists across rebuilds" reading was that resurrection, NOT a stale env bake in the release tree; `bundle:build` writes no env config there at all (measured).
 
 261. **FormValidator autocomplete interception + live-check stale-error clear (#B134/#B135/#B136).** The Safari-autocomplete keydown interception (fields with autocomplete="off" on a live-check form: preventDefault + programmatic value rebuild behind a transient readonly) now (a) bails on modifier chords — e.metaKey/e.ctrlKey returns BEFORE preventDefault so the native select-all/copy/paste/cut/undo defaults run; pre-fix Cmd+A typed the chord letter into the field and keyboard paste was dead (execCommand("paste") is inert in unprivileged web content; the whole chord-case block is commented out, incl. the undo case that wiped input back to defaultValue) — and (b) gates on REAL Safari only (/safari/i && !/chrom(e|ium)/i): every Chromium UA carries the Safari/537.36 token, so the workaround ran on Chrome/Edge/Brave where it was never intended; WebKit-on-iOS browsers (CriOS/FxiOS) stay matched by design. And (c) the live-check whole-form pass, when it turns VALID, now clears every previously-errored field' rendered error in BOTH copies (the input/checkbox/radio processEvent pass and updateSelect') instead of leaving a stale blocking-error paragraph beside the re-enabled submit trigger — the old clear branch was gated on the stored errors map being ALREADY empty and cleared only the touched field; the pass still never renders NEW errors on untouched fields. All three are browser-bundled (dist rebuilt). Tests: validator-autocomplete-interception.test.js + validator-livecheck-stale-error-clear.test.js — extracted-real-bytes execution (brace-walked handler + branch blocks, a real-UA matrix) with red-first dist pins (Closure De-Morgans the chord bail and folds the clear loop into a brace-less for-in, so minified pins target property-name shapes, never var names).
 
@@ -996,7 +996,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 278. **A cache key is opaque DATA — never route it through an expression/condition evaluator.** An output-cache key embeds the request URL, so a querystring's `?`/`=` parse as OPERATOR tokens in any condition-DSL lookup — the render cache's event registry originally lived in a collection whose dedup ran keys through the condition evaluator, and the SECOND cache-miss render of any cached GET route with `invalidateOnEvents` + a querystring THREW (in the swig path that rejection unwound to the function-level try, whose catch answered 500 — discarding an already-rendered page). The registry became a plain array matched with `===`. Generalizes beyond caching: never let a value carrying user-controlled characters reach a query/condition DSL as an expression — match registry rows with `===` on plain structures, and treat every composite key as an opaque string.
 
-279. **Transient-vs-permanent connector-error classification (#CE1, `26d803bd`+`d9231eff`, 0.5.25).** `lib/connector-error` (`classify(err) → {isTransient, reason}` + in-place `stamp(err)`) stamps `err.isTransient` (boolean; explicit `false` = classified-permanent, not merely absent) + `err.transientReason` (normalized token, `null` when permanent) on every datastore query error reaching the controller, so an app renders an honest retryable response by branching on the CONDITION instead of string-matching vendor text. Wired at 2 error sites per connector (Promise reject + direct-callback) across couchbase/mongodb/mysql/postgresql/scylladb/sqlite; `stamp()` RETURNS err so the call FOLDS into the terminal (`_reject(lib.connectorError.stamp(err))`) — the two-line form pushes `_queryEntry.resultSize` past inspector.test.js's fixed-width QI `substring(idx,idx+1800/900)` windows (thin post-fix margins 12/22 — RE-MEASURE on any connector error-branch edit; same fragility class as the #B152 260-char window). Taxonomy, first-match-wins IN ORDER: socket errno (ECONNREFUSED/ECONNRESET/ETIMEDOUT/EPIPE/EHOSTUNREACH/ENETUNREACH/ENETDOWN/EAI_AGAIN transient; **ENOTFOUND EXCLUDED** = DNS misconfig, not a blip) → mysql/sqlite string codes → **node:sqlite NUMERIC `errcode` primary byte** (MEASURED: a busy error is `code:'ERR_SQLITE_ERROR'`+`errcode:5`, NEVER `code:'SQLITE_BUSY'`; `errcode & 0xff` → 5 busy / 6 locked, so extended 261 SQLITE_BUSY_RECOVERY→5; dup-key 1555→19 stays permanent) → pg SQLSTATE (exact set + whole `08` connection class, 5-char-gated) → driver class NAMES (cassandra `NoHostAvailableError`/`OperationTimedOutError`, couchbase `*TimeoutError`/`RequestCanceledError`/`ServiceNotAvailableError`, mongo `MongoNetworkError`/`*SelectionError`) → mongo error LABELS (`TransientTransactionError`/`RetryableWriteError`) → mongo numeric codes (**7 HostNotFound EXCLUDED** = server-side ENOTFOUND; 6 HostUnreachable kept) → couchbase N1QL `cause.first_error_code` 1080 + 12008 bulk-get-retry-exhaustion + `cause.retry===true` (**12009 generic-DML EXCLUDED** = also covers dup-key; the SDK buckets every un-cased 12xxx — permanent 12003 included — into one IndexFailureError grab-bag, so the cause CODE is the signal and that class name must never join the name table; the #B153 envelope-forward reaches classify as a synthesized name-`Error` wrapper WHENEVER THE ENVELOPE CARRIES TEXT, making the code table the SOLE classifier on that path — the 1080 entry is live there, dead only on the raw-SDK shape where the typed timeout name fires first). **#B153 RESIDUAL (fixed 0.5.26)** — the synthesize branch was gated on `typeof(cause.first_error_message) != 'undefined'`, but the node binding marshals `first_error_code`/`first_error_message` onto EVERY query error (the C++ `query_error_context` value-initializes them), so a CLIENT-side SDK timeout — `cause` present, code `0`, message `''` — took the synthesize branch and became `new Error('')`, destroying the typed `Un/AmbiguousTimeoutError` name `classify` matches on, and a retryable timeout was stamped PERMANENT with message `''`. Guard gains `&& cause.first_error_message !== ''` at all three couchbase N1QL `onError` sites, so an empty envelope raw-forwards instead: raw-forwarding is classification-LOSSLESS (the raw error keeps `.cause`, so even a pathological empty-message SERVER envelope still classifies off the code table — the synthesize branch only ever existed to surface envelope text). Named residual: a NON-Error rejection carrying an empty message still loses `.cause` on the `new Error(String(err))` wrap — no known producer (the SDK rejects with typed Errors, and the empty-message case IS the typed timeout). Server-side — NO dist rebuild; restart to pick up. Tests: `couchbase-connector.test.js §08` (14 — source pins on the new clause + client-timeout end-to-end replicas asserting the typed name survives and `classify().isTransient === true`, plus a pre-residual subtract control reproducing the false negative). `classify` is TOTAL — never throws (invoked on the error path; hostile shapes → permanent); `stamp` is frozen-safe. Registered PLAIN `require` (gen-0-captured by the load-once connectors + invoked per-request → a `_require` copy would be a #B32-residual leak candidate). Couchbase is classifiable ONLY because #B153 (`3ac5ea4a`) forwards the RAW driver error its old `.catch` used to discard (and used to HANG on when there was no `cause`). Declared on `GinaLib` in `types/index.d.ts` (the types-runtime-parity two-way gate). Deferred: slice 2 (opt-in 503 + `Retry-After`), slice 3 (opt-in single auto-retry keyed on the entity OPERATION, not the serving request's HTTP verb — a GET can issue mutating queries). Server-side — NO dist rebuild; restart to pick up. Tests: `test/core/couchbase-connector.test.js §08` (#B153) + `test/lib/connector-error.test.js` (71).
+279. **Transient-vs-permanent connector-error classification (#CE1, `26d803bd`+`d9231eff`, 0.5.25).** `lib/connector-error` (`classify(err) → {isTransient, reason}` + in-place `stamp(err)`) stamps `err.isTransient` (boolean; explicit `false` = classified-permanent, not merely absent) + `err.transientReason` (normalized token, `null` when permanent) on every datastore query error reaching the controller, so an app renders an honest retryable response by branching on the CONDITION instead of string-matching vendor text. Wired at 2 error sites per connector (Promise reject + direct-callback) across couchbase/mongodb/mysql/postgresql/scylladb/sqlite; `stamp()` RETURNS err so the call FOLDS into the terminal (`_reject(lib.connectorError.stamp(err))`) — the two-line form pushes `_queryEntry.resultSize` past inspector.test.js's fixed-width QI `substring(idx,idx+1800/900)` windows (thin post-fix margins 12/22 — RE-MEASURE on any connector error-branch edit; same fragility class as the #B152 260-char window). Taxonomy, first-match-wins IN ORDER: socket errno (ECONNREFUSED/ECONNRESET/ETIMEDOUT/EPIPE/EHOSTUNREACH/ENETUNREACH/ENETDOWN/EAI_AGAIN transient; **ENOTFOUND EXCLUDED** = DNS misconfig, not a blip) → mysql/sqlite string codes → **node:sqlite NUMERIC `errcode` primary byte** (MEASURED: a busy error is `code:'ERR_SQLITE_ERROR'`+`errcode:5`, NEVER `code:'SQLITE_BUSY'`; `errcode & 0xff` → 5 busy / 6 locked, so extended 261 SQLITE_BUSY_RECOVERY→5; dup-key 1555→19 stays permanent) → pg SQLSTATE (exact set + whole `08` connection class, 5-char-gated) → driver class NAMES (cassandra `NoHostAvailableError`/`OperationTimedOutError`, couchbase `*TimeoutError`/`RequestCanceledError`/`ServiceNotAvailableError`, mongo `MongoNetworkError`/`*SelectionError`) → mongo error LABELS (`TransientTransactionError`/`RetryableWriteError`) → mongo numeric codes (**7 HostNotFound EXCLUDED** = server-side ENOTFOUND; 6 HostUnreachable kept) → couchbase N1QL `cause.first_error_code` 1080 + 12008 bulk-get-retry-exhaustion + `cause.retry===true` (**12009 generic-DML EXCLUDED** = also covers dup-key; the SDK buckets every un-cased 12xxx — permanent 12003 included — into one IndexFailureError grab-bag, so the cause CODE is the signal and that class name must never join the name table; the #B153 envelope-forward reaches classify as a synthesized name-`Error` wrapper WHENEVER THE ENVELOPE CARRIES TEXT, making the code table the SOLE classifier on that path — the 1080 entry is live there, dead only on the raw-SDK shape where the typed timeout name fires first). **#B153 RESIDUAL (fixed 0.5.26)** — the synthesize branch was gated on `typeof(cause.first_error_message) != 'undefined'`, but the node binding marshals `first_error_code`/`first_error_message` onto EVERY query error (the C++ `query_error_context` value-initializes them), so a CLIENT-side SDK timeout — `cause` present, code `0`, message `''` — took the synthesize branch and became `new Error('')`, destroying the typed `Un/AmbiguousTimeoutError` name `classify` matches on, and a retryable timeout was stamped PERMANENT with message `''`. Guard gains `&& cause.first_error_message !== ''` at all three couchbase N1QL `onError` sites, so an empty envelope raw-forwards instead: raw-forwarding is classification-LOSSLESS (the raw error keeps `.cause`, so even a pathological empty-message SERVER envelope still classifies off the code table — the synthesize branch only ever existed to surface envelope text). Named residual: a NON-Error rejection carrying an empty message still loses `.cause` on the `new Error(String(err))` wrap — no known producer (the SDK rejects with typed Errors, and the empty-message case IS the typed timeout). Server-side — NO dist rebuild; restart to pick up. Tests: `couchbase-connector.test.js §08` (14 — source pins on the new clause + client-timeout end-to-end replicas asserting the typed name survives and `classify().isTransient === true`, plus a pre-residual subtract control reproducing the false negative). `classify` is TOTAL — never throws (invoked on the error path; hostile shapes → permanent); `stamp` is frozen-safe. Registered PLAIN `require` (gen-0-captured by the load-once connectors + invoked per-request → a `_require` copy would be a #B32-residual leak candidate). Couchbase is classifiable ONLY because #B153 (`3ac5ea4a`) forwards the RAW driver error its old `.catch` used to discard (and used to HANG on when there was no `cause`). Declared on `GinaLib` in `types/index.d.ts` (the types-runtime-parity two-way gate). **Slice 2 SHIPPED (0.6.2+): opt-in 503 + `Retry-After`.** Per-bundle `server.transientErrors` block — `enabled` (strict boolean true, default false), `retryAfter` (integer seconds 1..86400, default 30), `message` (non-empty string, default = the standard 503 status text). With the opt-in ON, a stamped-transient error resolving to 500 through controller `throwError` renders 503 + `Retry-After: <retryAfter>` (one early guarded `setHeader` rides every egress: the JSON writeHead trio, the HTML fallback page, and the renderCustomError → render pipeline, which forwards `res.getHeaders()` into the HTTP/2 frame), with the user-facing `error` field swapped to `message`; `message`/`stack` body fields keep their existing scope semantics and the incident-ref pairing line keeps full pre-strip detail server-side. Explicit non-500 statuses and permanent errors never upgrade; upgrade applies at BOTH throwError status-resolution sites (the Error/1-arg path and the 2-arg errorObj path). Boot-time shape check warns per malformed key and NEVER refuses boot (a rendering nicety must not gate a boot); the controller-side reader independently normalizes to the same defaults, total (hostile getters → defaults). Deliberately NOT mirrored in the server-side throwError twin — stamped connector errors surface through controller actions only. Wire-verified live on BOTH protocols (isaac engine): h1 503+header, h2 `:status` 503 + `retry-after` (the renderJSON h2-inert-status class does not apply — throwError writes via writeHead; express shares the same engine-agnostic controller path, mechanism-verified only). Deferred: slice 3 (opt-in single auto-retry keyed on the entity OPERATION, not the serving request's HTTP verb — a GET can issue mutating queries). Server-side — NO dist rebuild; restart to pick up. Tests: `test/core/couchbase-connector.test.js §08` (#B153) + `test/lib/connector-error.test.js` (71) + `test/core/transient-errors.test.js` (26: source/order pins both files, real-throwError behaviorals via createTestInstance, extracted-bytes config-normalization matrix, server-twin divergence invariant).
 280. **Framework control-plane bind host + command-name namespace (0.5.26).** The two control-plane listeners — the command socket (default `8124`, `bin/cmd`, which executes a CLI command per connection) and the MQ listener (default `8125`, `lib/logger/src/containers/mq/listener.js`) — bind an explicit host that defaults to loopback. The `bind_host` setting governs it (env `GINA_BIND_HOST`, flag `gina framework:set --bind-host=`, seeded into `~/.gina/<shortVersion>/settings.json` and carried across shortVersion bumps by the `checkIfSettings` migration map); it is deliberately SEPARATE from `host_v4`, which is the address clients CONNECT to — reusing one key for both would make a workstation whose `host_v4` points at another machine fail to bind its own daemon (EADDRNOTAVAIL). Node binds every interface when `listen()` gets no host argument, and the MQ listener reads `opt.hostV4` specifically, so a caller passing a `host` key leaves it undefined and binds everything — both now default to `127.0.0.1` at the listener itself as well as at the resolution site. Exposing the control plane beyond the local host is a deliberate opt-in, mirroring a bundle's `--http-host`. Separately, `lib/cmd/framework/init.js` `run()` constrains a caller-supplied `topic:action` pair to `/^[A-Za-z0-9_-]+$/` before it becomes a `require()` path (an out-of-namespace segment resolves to `''`, which never exists, so it takes the same "not a valid command" branch); every shipped command group and action matches, including the synthetic `framework:-V` / `framework:--version` forms. An unresolvable name reaching the daemon over the socket ends that client's connection instead of calling `process.exit(1)`, which would stop the daemon serving every other client — an offline one-shot CLI run still exits non-zero. NOTE most command handlers call `process.exit()` themselves, so only `bundle:start` (the sole command `bin/cli` routes online) is designed to run inside the daemon. ⚠️ 0.5.26 shipped a DIAL-side regression with this: CLI-side clients — the command socket dial (`bin/cli`), the MQ speaker and file log containers, and `gina tail` — dialled `host_v4` while the daemon binds `bind_host`, so a co-located CLI could not reach its own daemon whenever `host_v4` was a non-loopback address of the same machine (the common containerized shape: `bundle:start` aborted before the HTTP server ever bound, and `gina tail` printed `[MQTail] ECONNREFUSED <host_v4>:8125`). Fixed post-0.5.26: all four dial sites resolve through `lib/net-locality` — `resolveDialHost(hostV4, bindHost)` dials the bind address (loopback by default, or `bind_host` when it is a concrete non-wildcard address) whenever `host_v4` names one of the machine's own interfaces per `os.networkInterfaces()`, while hostnames, genuinely remote addresses, and enumeration failures dial unchanged (fail-safe) — and the refused-connection error now names the dial target plus the `bind_host` knob. Also fixed in the same change: a `gina framework:set --bind-host=` write now PERSISTS — `bind_host` was the only connection key without a disk-to-env read-back in the settings regeneration (every CLI invocation rewrote it back to env-or-default), and the container bootstrap (`gina-init`) overwrote it unconditionally; both paths now preserve the persisted value, with `GINA_BIND_HOST` still taking precedence and unresolved `${}` template placeholders skipped.
 
 281. **Production transport posture — `server.requireHttps` / `server.allowInsecure` (#COMPLY9, 0.5.26).** Outside the `local` scope a bundle resolving a cleartext scheme (anything but https — both engines' scheme switches default to the plain server) warns ONCE at boot, naming bundle/scheme/scope and both remediations; `server.requireHttps: true` refuses to boot it instead (the throw lands in init()'s central catch — pre-listen, the cleartext port never binds), and `server.allowInsecure: true` asserts TLS terminates upstream (mesh/ingress/reverse proxy — the documented h2c topology), turning the warn into one info line (same vocabulary as `mcp.json > server > allowInsecure`). Both strict booleans resolved like `scheme` itself (bundle settings win, env.json's `server` block fills via the serverOpt picked-keys merge); a non-boolean-when-present and the both-true contradiction refuse the boot in EVERY scope (the quietly-OFF class). The gate is NOT-local, never is-production — a custom scope (e.g. `beta`) is neither, and a production-keyed gate would silently skip it; `conf.server.scopeIsLocal` derives from def_scope, not the live scope, so it is never consulted. An https:// proxy.json upstream hostname is NAMED in the warn (advisory) but never silences it. Server-side only — no dist rebuild; pickup = restart.
@@ -1030,3 +1030,5 @@ Dev-mode query instrumentation captures every database query tied to the current
 296. **FormValidator submits: one XHR per send + a fail-safe lock release (#B175/#B176, 0.6.1).** `send()` used to reuse ONE module-scope `XMLHttpRequest` (created once at validator init): re-`open()`ing the completed instance synchronously replayed the PREVIOUS submit's still-assigned `onreadystatechange` at readyState 1, re-disabling that form's submit trigger and re-stamping its `data-gina-form-loading` with no release path (the lock was armed at four sites and released only inside readyState 4) — so submitting form B after form A had completed stranded A's trigger natively-disabled until something else happened to re-enable it. Since 0.6.1 every send builds its own LOCAL XHR (per-submit handler/state/lifecycle; the reuse's implicit cross-form abort is gone — each form settles its own request) and registers a `loadend` release — fires on success, error, timeout and abort alike — that removes `disabled`/`aria-disabled` + `data-gina-form-loading` and clears `$form.isSending`/`$form.sent`; `$form.isSending` now genuinely spans send→settled (it used to be cleared at the first readyState transition, i.e. almost immediately — `$form.sent` was the only flag that spanned the request); the timeout path removes `data-gina-form-loading` instead of writing the truthy string `"false"`. Same release, #B176: the live-check opt-out is honored CONSISTENTLY — two validation gates (the select-change handler and the bind-time silent-validation pass) evaluated the rules-count boolean INSIDE `/^(true)$/i.test(…)`, so an explicit `data-gina-form-live-check-enabled="false"` (a truthy string) short-circuited to the count boolean and matched, leaving those two running on a form that had opted out; the gates now test the attribute alone, then check the count. Scope worth knowing before auditing a form's pre-0.6.1 behaviour: the opt-out was NOT ignored outright — the three `registerForLiveChecking` sites (textarea / form-associated custom element / input) already tested the attribute alone, so text as-you-type never ran on an opted-out form, and the submit trigger ended enabled either way because the trigger's show branch is forced whenever live-check is off. The pre-fix behaviour was an inconsistent middle; only bind-time and select-change validation change at pickup. Browser-bundled — consumers re-bake at pickup. Caution that stays by design: `setOptions()` is a MODULE-wide default setter, not per-call — e.g. `setOptions({withRateLimit: false})` turns rate limiting off for every form for the rest of the page lifetime (per-form options are a demand-gated follow-up).
 
 297. **Validator error labels & rendering — observable keys now translatable, announcements separator-joined, identical messages deduped (#B178 family, 0.6.1).** The key an app can OBSERVE in a field's `errors` object was not always the key the label catalog is consulted under: four rule families write the error under a generic key while consulting a SPECIFIC label key — the float coercion's NaN branch renders `errorLabels['toFloatNAN']` into `errors['toFloat']`, and the number/integer/string Length families render the `Min`/`Max` label variants into the generic `is<X>Length` errors key — so translating the observable key (bundle catalog `_validator` node or `setErrorLabels()`) was a silent no-op and a partial catalog rendered one localized message beside one English default. Fixed with an alias fill applied to every app-supplied label layer (server catalog node, client catalog whisper, per-culture registrations, `setErrorLabels()`): a supplied generic fills the specific keys the app did not supply itself; a supplied specific still wins; English defaults are untouched. Same release: numbered `is` aliases (`is1`, `is2`, …) had no per-alias default label, so a failing alias with no rule-supplied text rendered an EMPTY message — they now fall back to the shared `is` label (translate catalog key `is` once to cover every alias); and the user-validator setup loop unconditionally reset every user-defined validator's label to the English default, clobbering catalog translations — it now fills only when the app supplied none. Two render-side fixes ride along: the error container renders one `<p>` per error key and the aria-live announcement passed the container's raw `textContent`, which concatenates with NO separator — a screen reader received multiple messages as one run-on string (visually the messages stack as blocks; only the announcement channel ran them together); announcements now join the per-message texts with a sentence separator. And two rules resolving to byte-identical message text (canonically a coercion paired with its validator, both failing on the same non-numeric input) rendered the same sentence twice — each distinct text now renders once, while the dev inspector still records every error key. Browser-bundled — consumers re-bake at pickup; apps that translated only observable keys will see those messages switch from English to their language.
+
+298. **Render/request-path deep-clone & id-mint reduction (#P39 slice 1, 0.6.x) — the filter-factory options travel by REFERENCE, locale lookups are memoized, `conf.locales` is a lazy per-request accessor, and `lib/uuid` right-sizes its entropy batch.** The CPU-profiling baseline convicted per-request copy/id overhead as ~60% of render-arm CPU, 98.7% of the clone time in three caller-attributed paths; all three are gone. (1) `controller.render-swig.js` / `controller.render-nunjucks.js` hand `local.options` to the filter factory UN-cloned, and `lib/swig-filters` / `lib/nunjucks-filters` `getInstance()` stashes that wrapper by reference — the singleton's `_options` has no writer beyond the stash itself (every filter only reads it; the `getUrl`/`getWebroot` merge fills a fresh `{}` target), the request path already shares `conf.routing`/`conf.reverseRouting`/`conf.forms` by reference, and `req`/`res` always passed by reference anyway (the cloner bails on non-plain constructors) — so reference-passing adds no new mutation-visibility class and the stash-then-await interleave window is byte-identical to the cloned era. Anything that MUTATES what it reads from the filter context must clone its own copy first (the pre-existing contract; `getRoute()` already does). (2) `setOptions` no longer builds two Collections per request over the boot-static region sets (each was a deep copy of ~500 nested records plus one 16-char id minted per record ≈ 750 webcrypto calls, paid by EVERY request in a views-bearing bundle, render or not): a module-level per-culture memo answers the language → region-set and country → row lookups; `conf.locale` is a per-request deep copy of the ONE resolved row (isolating the `.date` write and template mutations); `conf.locales` is a LAZY self-replacing accessor — the request's own deep copy materializes on first read (sole framework reader: `self.getLocales()`), so the common request pays nothing while whole-conf clones and serializers materialize it transparently, and assignment writes through. (3) `lib/uuid` sizes its `getRandomValues` batch to the REQUESTED id length (the fixed 7-byte batch was sized for the 4-char default, so `uuid(16)` — the form `lib/collection` mints per item — needed ~3 webcrypto calls; now 1; each call pays a full randomFillSync regardless of byte count, so call count is the cost). (4) The cloner's dead per-recursion `Object.keys` allocation is removed. Measured A/B on the profiling harness (fresh runs both sides, same knobs): render wall 32,186 → 7,268 ms for 3000 requests = 4.4× throughput (10.7 → 2.4 ms/render), deep-clone share 50.31% → 1.81%, GC 2,522 → 137 ms, randomFillSync out of the top-15 frames on both arms, upload-arm clone floor 253 → 11 ms — the pre-stated ≈2× ceiling was beaten because allocation-pressure knock-on (GC, locality) fell with the clones. `lib/uuid` is AMD-bundled, so the browser bundle changed: consumer pickup = restart AND per-bundle re-bake. `Collection`'s own eager per-item `_uuid` minting is UNCHANGED (its only consumers are collection-internal; `toRaw()` strips). Remaining clone sites (hot route-matching-loop clones, `getRoute`-per-`getUrl` filter call, `getParams`/`getConfig` per-call clones, cssColl/jsColl construction, async-delegate store clones) stay measure-gated for a future profile.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "MVC framework for Node.js and Bun with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -76,12 +76,12 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.6.1/core/gna",
+  "main": "./framework/v0.6.2/core/gna",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "import": "./index.mjs",
-      "require": "./framework/v0.6.1/core/gna.js"
+      "require": "./framework/v0.6.2/core/gna.js"
     },
     "./gna": {
       "types": "./types/gna.d.ts",

package/schema/settings.json

@@ -215,6 +215,28 @@
           "type": "boolean",
           "description": "When true, the HTTP/2 server also accepts HTTP/1.1 connections (ALPN negotiation). Defaults to true."
         },
+        "transientErrors": {
+          "type": "object",
+          "description": "Opt-in rendering of transient datastore failures as 503 + Retry-After. When enabled, a connector error stamped isTransient that would render as HTTP 500 through throwError renders as 503 with a Retry-After header and a clean user-facing error message instead. Explicit non-500 statuses and permanent errors are never upgraded. A malformed block warns at boot and leaves the feature off — it never refuses a boot.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Master switch. Must be strictly boolean true to turn the upgrade on — any other type or value leaves it off. Defaults to false."
+            },
+            "retryAfter": {
+              "type": "integer",
+              "description": "Delta-seconds value emitted as the Retry-After header on upgraded 503 responses. Integer between 1 and 86400; out-of-range or non-integer values are ignored with a boot warning. Defaults to 30.",
+              "minimum": 1,
+              "maximum": 86400
+            },
+            "message": {
+              "type": "string",
+              "description": "User-facing text placed in the error field of upgraded 503 responses. Non-empty string; empty or non-string values are ignored with a boot warning. Defaults to the standard 503 status text (Service Unavailable).",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        },
         "warmup": {
           "type": "array",
           "description": "List of upstream URLs to pre-establish HTTP/2 sessions at bundle startup. Reduces latency on the first real request.",

package/script/perf/analyze-cpuprofile.js

@@ -0,0 +1,187 @@
+'use strict';
+/**
+ * analyze-cpuprofile.js — self-time aggregation of a V8 `.cpuprofile` by
+ * acceleration-candidate bucket (#P34, the native-acceleration arc's gate).
+ *
+ * Reads one or more `.cpuprofile` files (as written by `node --cpu-prof`) and
+ * reports, per file: total sampled time, self-time per candidate bucket
+ * (multipart scan, ws-framing codec, getAssets, render delegates, swig engine,
+ * logger, router/server/controller layers, GC, node internals, idle), and the
+ * top individual frames by self-time. This is the conviction surface for
+ * #P35-#P38: a candidate whose bucket stays flat under its own arm's load is
+ * acquitted.
+ *
+ * Attribution model: `selfTime[node] = sum(timeDeltas[i] where samples[i] is
+ * that node)` — the standard sampling approximation (each inter-sample delta
+ * is attributed to the sample that ends it; negative deltas are clamped to 0).
+ * A whole-process profile includes boot: module compile/require frames land in
+ * their own visible buckets, so request-path buckets stay attributable.
+ *
+ * Usage:
+ *   node script/perf/analyze-cpuprofile.js <file.cpuprofile> [...more]
+ *   node script/perf/analyze-cpuprofile.js --json <file.cpuprofile>
+ *
+ * Standalone by design — no framework globals, require()-able by the
+ * profile-baseline orchestrator (module.exports.analyze).
+ */
+
+var fs   = require('fs');
+var path = require('path');
+
+/**
+ * Candidate buckets, first-match ordering. Frame-name tests (GC/program/idle)
+ * come before URL tests because those frames carry empty urls; specific
+ * framework surfaces come before the generic framework catch-all.
+ *
+ * @constant {Array<{key: string, test: function}>}
+ */
+var BUCKETS = [
+    { key: 'GC',                            test: function (fn, url) { return fn === '(garbage collector)'; } },
+    { key: 'idle',                          test: function (fn, url) { return fn === '(idle)'; } },
+    { key: 'program (V8/native)',           test: function (fn, url) { return fn === '(program)'; } },
+    { key: 'multipart scan (streamsearch/busboy)', test: function (fn, url) { return /streamsearch|@rhinostone\/busboy/.test(url); } },
+    { key: 'ws codec (lib/ws-framing)',     test: function (fn, url) { return /lib\/ws-framing/.test(url); } },
+    { key: 'ws session (lib/ws-session)',   test: function (fn, url) { return /lib\/ws-session/.test(url); } },
+    { key: 'getAssets (core/server.js)',    test: function (fn, url) { return fn === 'getAssets'; } },
+    { key: 'render delegates (controller.render-*)', test: function (fn, url) { return /controller\/controller\.render-/.test(url); } },
+    { key: 'swig engine (@rhinostone/swig)', test: function (fn, url) { return /@rhinostone\/swig/.test(url); } },
+    { key: 'logger (lib/logger)',           test: function (fn, url) { return /lib\/logger/.test(url); } },
+    { key: 'deep clone (utils/prototypes JSONClone)', test: function (fn, url) { return /utils\/prototypes\.json_clone/.test(url); } },
+    { key: 'framework utils (utils/)',      test: function (fn, url) { return /gina[^/]*\/utils\//.test(url); } },
+    { key: 'merge/collection (lib)',        test: function (fn, url) { return /\/(merge|collection)\/src\//.test(url); } },
+    { key: 'router (core/router.js)',       test: function (fn, url) { return /core\/router\.js/.test(url); } },
+    { key: 'server core (core/server*.js)', test: function (fn, url) { return /core\/server/.test(url); } },
+    { key: 'controller core (core/controller)', test: function (fn, url) { return /core\/controller/.test(url); } },
+    { key: 'framework other',               test: function (fn, url) { return /framework\/v[0-9]|node_modules\/gina\//.test(url); } },
+    { key: 'bundle app code',               test: function (fn, url) { return /\/releases\/|\/src\/[^/]+\/(controllers|templates|index\.js)/.test(url); } },
+    { key: 'node internals',                test: function (fn, url) { return url.indexOf('node:') === 0; } },
+    { key: 'other JS',                      test: function ()        { return true; } }
+];
+
+/**
+ * Aggregate one parsed profile into bucket self-times.
+ *
+ * @param   {object} profile - parsed `.cpuprofile` JSON ({nodes, samples, timeDeltas})
+ * @returns {{totalUs: number, buckets: object, frames: Array}} totals in microseconds
+ */
+function analyze(profile) {
+    var byId = {};
+    var i;
+    for (i = 0; i < profile.nodes.length; i++) {
+        byId[profile.nodes[i].id] = profile.nodes[i];
+    }
+
+    var selfUs = {};
+    var samples = profile.samples || [];
+    var deltas  = profile.timeDeltas || [];
+    for (i = 0; i < samples.length; i++) {
+        var d = deltas[i] > 0 ? deltas[i] : 0;
+        selfUs[samples[i]] = (selfUs[samples[i]] || 0) + d;
+    }
+
+    var buckets = {};
+    var frames  = [];
+    var totalUs = 0;
+    for (i = 0; i < BUCKETS.length; i++) {
+        buckets[BUCKETS[i].key] = 0;
+    }
+
+    Object.keys(selfUs).forEach(function (id) {
+        var node = byId[id];
+        if (!node) { return; }
+        var cf  = node.callFrame || {};
+        var fn  = cf.functionName || '';
+        var url = cf.url || '';
+        var us  = selfUs[id];
+        totalUs += us;
+
+        for (var b = 0; b < BUCKETS.length; b++) {
+            if (BUCKETS[b].test(fn, url)) {
+                buckets[BUCKETS[b].key] += us;
+                break;
+            }
+        }
+        frames.push({
+            us   : us,
+            fn   : fn || '(anonymous)',
+            url  : url,
+            line : (typeof cf.lineNumber === 'number') ? cf.lineNumber + 1 : null
+        });
+    });
+
+    frames.sort(function (a, b) { return b.us - a.us; });
+    return { totalUs: totalUs, buckets: buckets, frames: frames };
+}
+
+/**
+ * Render one analysis as a human-readable table.
+ *
+ * @param   {string} label
+ * @param   {{totalUs: number, buckets: object, frames: Array}} result
+ * @param   {number} [topN=15]
+ * @returns {string}
+ */
+function format(label, result, topN) {
+    topN = topN || 15;
+    var out = [];
+    out.push('══ ' + label + ' — total sampled self-time: ' + (result.totalUs / 1000).toFixed(1) + ' ms');
+    Object.keys(result.buckets)
+        .map(function (k) { return { k: k, us: result.buckets[k] }; })
+        .sort(function (a, b) { return b.us - a.us; })
+        .forEach(function (row) {
+            if (row.us === 0) { return; }
+            var pct = (100 * row.us / result.totalUs).toFixed(2);
+            out.push('  ' + pad(pct + '%', 8) + pad((row.us / 1000).toFixed(1) + ' ms', 12) + row.k);
+        });
+    out.push('  ── top ' + topN + ' frames by self-time:');
+    result.frames.slice(0, topN).forEach(function (f) {
+        var loc = f.url ? (shorten(f.url) + (f.line ? ':' + f.line : '')) : '';
+        out.push('  ' + pad((f.us / 1000).toFixed(1) + ' ms', 12) + f.fn + (loc ? '  @ ' + loc : ''));
+    });
+    return out.join('\n');
+}
+
+/**
+ * @param   {string} s
+ * @param   {number} n
+ * @returns {string} left-padded to n + two trailing spaces
+ * @inner
+ */
+function pad(s, n) {
+    while (s.length < n) { s = ' ' + s; }
+    return s + '  ';
+}
+
+/**
+ * @param   {string} url
+ * @returns {string} the last 3 path segments — enough to identify a frame
+ * @inner
+ */
+function shorten(url) {
+    var parts = url.split('/');
+    return parts.slice(Math.max(0, parts.length - 3)).join('/');
+}
+
+module.exports = { analyze: analyze, format: format, BUCKETS: BUCKETS };
+
+if (require.main === module) {
+    var args   = process.argv.slice(2);
+    var asJson = args.indexOf('--json') > -1;
+    var files  = args.filter(function (a) { return a.indexOf('--') !== 0; });
+    if (!files.length) {
+        process.stderr.write('usage: node script/perf/analyze-cpuprofile.js [--json] <file.cpuprofile> [...]\n');
+        process.exit(2);
+    }
+    var all = {};
+    files.forEach(function (f) {
+        var result = analyze(JSON.parse(fs.readFileSync(f, 'utf8')));
+        if (asJson) {
+            all[path.basename(f)] = { totalUs: result.totalUs, buckets: result.buckets, top: result.frames.slice(0, 20) };
+        } else {
+            process.stdout.write(format(path.basename(f), result) + '\n\n');
+        }
+    });
+    if (asJson) {
+        process.stdout.write(JSON.stringify(all, null, 2) + '\n');
+    }
+}