gina 0.6.24 → 0.6.25

package/CHANGELOG.md

@@ -6,6 +6,20 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.6.25 - 2026-09-03
+### Added
+* Exact-money primitive (#FIN5): lib.money server-side and gina.money in the browser bundle — ISO 4217 minor-unit integer arithmetic on BigInt, with an in-lib exponent table (JPY 0, BHD 3, CLF 4, default 2). Strict wire-string parse() rejects float inputs and excess fractional precision (rounding stays the application's decision); add/subtract/compare/multiply throw on currency mismatch and integer-factor violations; format() renders the canonical wire string with exactly the currency's fraction digits; toMinor()/fromMinor() round-trip JSON-safe minor-unit counts. Amounts stay exact beyond Number.MAX_SAFE_INTEGER minor units. Display formatting deliberately stays with the i18n layer (Intl.NumberFormat). The module is dependency-free and dual-published; changes to it ride the browser bundle (pickup: restart and re-bake).
+* isIban and isBic FormValidator rules (#FIN4): IBAN validation per ISO 13616 - shape, official per-country length for 87 registered countries, and the ISO 7064 MOD 97-10 checksum - with a tolerant read (case and space/hyphen separators are normalized for validation only; the stored value is never mutated, and unknown country codes pass on shape + checksum), plus BIC validation per ISO 9362 (8- or 11-character shape, case-insensitive). Shared client + server like every FormValidator rule; empty values stay adjudicated by isRequired alone.
+* Idempotency keys (#FIN6): opt-in Idempotency-Key request deduplication at the router band, per the IETF draft. Arm it with settings.json server.idempotency (a declared kv namespace + keyField) and opt routes in with routing.json top-level idempotency true (or required true to answer 400 when the header is missing). The first request bearing a key reserves the operation and executes; its rendered JSON response is recorded, and a retry with the same key and payload is answered with the recorded response plus Idempotency-Replayed true. A duplicate while the original is in flight gets 409 + Retry-After; the same key with a different payload gets 422. Anonymous callers are skipped (a stored response never crosses principals), 5xx and oversize responses release the reservation so retries re-execute, and the dedup scope follows the kv namespace backend (memory per process, redis/sqlite replica-shared).
+* XML request handling (#FIN1): application/xml, text/xml and application/*+xml request bodies now reach the application verbatim on POST, PUT and PATCH instead of being run through the form-encoded decode path. request.body keeps the exact document the client sent (the same string request.rawBody carries) and the application parses it with the XML library of its choice — the framework never parses XML itself, so it takes on no XML parser surface. Previously such a body was silently destroyed rather than rejected: the form decoder splits on & and then on =, keeping only the first pair, so the XML declaration alone collapsed a whole document to one bogus key, and that object then replaced request.body. The matched set follows the convention ASP.NET Core, Spring and type-is share — the +xml structured-suffix wildcard is scoped to application/, so image/svg+xml is not matched, and the RFC 7303 types that are not XML documents (application/xml-dtd and both xml-external-parsed-entity forms) are excluded. urlencoded, JSON and multipart bodies are unaffected, and the same single chokepoint serves both engines.
+* renderXML delegate (#FIN2): first-class XML responses, the outbound counterpart to verbatim XML request handling. Call self.renderXML(xmlContent) from a controller action to send a pre-serialised document — gina does not build XML any more than it parses it, so you serialise with the library of your choice and the delegate owns the wire concerns. The content type defaults to application/xml (RFC 7303 recommends it over text/xml) with the charset taken from the bundle encoding, and an optional second argument covers the suffix family: self.renderXML(doc, "application/soap+xml"), atom+xml for a feed, or a vendor tree. The status code comes from response.statusCode rather than the payload — an XML string has no envelope for the renderJSON status convention — so set it upstream or answer errors with self.throwError(). HEAD requests get the headers including a byte-accurate content-length with no body, HTTP/2 responses carry the status as a pseudo-header with upstream headers folded into the frame, and opt-in HTTP/2 trailers work as they do for every other delegate. A route using idempotency keys records its response envelope here too, so a retried XML mutation replays rather than re-executing.
+* Message-schema validation seam (#FIN3): routes can now run the raw request body through an application-supplied validator before the controller action. Declare param.messageValidator: "<name>" on a route and ship a factory module at message-validators/<name>.js — the factory runs once at bundle boot (compile your XSD or open your sidecar pool there; a broken module refuses the boot instead of silently skipping validation), and the returned validate(document, req) function — sync or async — receives the verbatim body string on every matching request. Return { valid: true } to proceed, or { valid: false, status, errors } to refuse: 422 by default (schema-invalid, with your errors array forwarded on the response body), 400 for a document that does not parse at all, or 503 with an optional retryAfter when the checker itself is unavailable. A thrown error fails closed as a 500 — a request never proceeds unvalidated. The framework ships no schema engine and takes on no XML or JSON-Schema parser surface: the validator is yours (an XSD library, a Schematron sidecar, a JSON-Schema engine), the hook, ordering and refusal shape are gina's. The gate runs after authorization, rate limiting and idempotency, and before DTO field validation; routes without the declaration are byte-identical.
+### Fixed
+* Client-side routing helper no longer swallows its own "route not found inside your view" diagnostic: when a rendered 404 marker or an alternate-route lookup identifies a route missing from the running table, the composed message is now emitted via console.warn on the first sighting of each route (the gina.notFound registry still dedups repeats), and the alternate-route arm now records its registry entry so repeat counts accumulate instead of resetting. Server-side miss logging is unchanged. (#B462)
+* The query() basic-auth option is now honoured on HTTP/2 — and can no longer leak. `options.auth` ("user:password") was consumed by node's own request() on HTTP/1.x only; on the HTTP/2 path the option-copy loop forwarded it into the outgoing header block as a literal `auth:` header (the strip set did not list it) and no `Authorization` header was ever minted, so the credential travelled in a nonstandard header while authentication silently never happened. The option is now minted into `Authorization: Basic <base64>` before dispatch on BOTH transports through one code path — a caller-supplied authorization header always wins, matching node's HTTP/1.x behaviour — and the option itself is deleted pre-dispatch (and listed in the HTTP/2 strip set as a belt), so an empty or malformed credential cannot travel as a header either. If anything downstream relied on receiving the literal `auth:` header on HTTP/2, that was the defect, not a contract. (#B465)
+### Security
+* Server-side data serialised into the Inspector's inline `<script>` blocks can no longer be read as template source by the swig renderer. The `__ginaData` and `__ginaLogs` scripts are spliced into the layout before it is compiled (their per-request nonce is a swig conditional), which left every swig delimiter live inside the serialised page data: a stored value such as `A{{ 7*7 }}B` rendered as `A49B`, and a `{% %}` tag inside a value executed with the page's locals in scope. The shared inline-script helper now also escapes `{` and `}` inside JSON string literals (`\u007b` / `\u007d` are valid JSON escapes, so every value still parses back identical); structural braces are untouched. Same reachability as the 0.6.23 hardening: only pages that emit the Inspector block (development by default, production only when `displayInspector` is enabled). The nunjucks renderer injects after rendering and was not affected. Server-side only: pick it up with a bundle restart, no rebuild needed. Internal reference #B463.
+
 ## 0.6.24 - 2026-09-02
 ### Fixed
 * Couchbase `bulkInsert` no longer returns `undefined` when its own prologue throws. Its outer `try` wraps the method body, so a synchronous failure — a connection that cannot be resolved, or either of the two deliberate `rec` validations — was caught, logged to `console.error` and then swallowed, and the method fell off the end. Both documented call shapes broke on that path: the `await` form (the first `@example` in its own docblock) resolved with `undefined`, so a caller treating "did not throw" as success recorded an insert that never happened, and the `.onComplete(cb)` form threw a TypeError on `undefined`. In both, the error existed only in the log and was unreachable to the caller. The promise, its one-shot resolver and the `.onComplete` shim are now built before the `try`, so the outer catch settles this call instead: `.onComplete(cb)` receives `(err)` and the promise rejects. The `_settled` latch means a late throw cannot double-settle, and the happy path is unchanged. Note that a fire-and-forget call that ignores the return will now surface an unhandled rejection where it previously failed silently. **Scope, and it matters if you documented the old behaviour:** this changes what `bulkInsert` RETURNS, not what its promise RESOLVES WITH. A rows-less success still settles as `null`, so a non-rejection is still not proof that rows were inserted — keep any rows-based success check you have, and re-read any comment or guard whose premise was the old return-`undefined` behaviour: the premise goes stale while the conclusion usually stays correct. (#B460)

package/README.md

@@ -40,6 +40,10 @@ MVC framework for Node.js and Bun with built-in HTTP/2, multi-bundle architectur
 | Security headers | CSP with per-response nonces, HSTS, COOP / COEP / CORP, Referrer-Policy and the X-* family — per-header plugins or one `SecurityHeaders` wrapper |
 | Secrets | `${secret:KEY}` placeholders in bundle config — fail-closed, env-backed, with opt-in file and exec-bridge tiers beneath the environment; `secrets:scan` / `secrets:check` CLI |
 | Internationalisation | Per-bundle JSON catalogs, `t()` helper, swig + nunjucks `t` filter, CLDR plurals, ICU MessageFormat opt-in via `t.icu()` |
+| Exact money | `lib.money` / `gina.money` — ISO 4217 minor-unit integer arithmetic (BigInt-safe), strict wire-string parsing, same-currency guards; display via `Intl.NumberFormat` |
+| Idempotency keys | Opt-in `Idempotency-Key` dedup at the router band (IETF draft): retried mutations replay the recorded first response — 409 while in flight, 422 on payload reuse, principal-scoped over the kv primitive |
+| Message validation | `param.messageValidator` — a route-level seam running the raw request body through an application-supplied validator (XSD sidecar, JSON Schema, anything) before the action: boot-compiled factory, sync or async, fail-closed 400/422/503 refusals with `Retry-After` on checker outage |
+| XML in and out | `application/xml`, `text/xml` and `application/*+xml` request bodies reach the action verbatim on `req.body`; `self.renderXML()` sends pre-serialised responses with the right content type and charset. The application brings its own XML library — the framework parses none and builds none |
 | Observability | Built-in `/_gina/metrics` Prometheus endpoint (opt-in, IP-allowlisted) — process metrics + HTTP counter / duration histogram with cardinality-safe route labels; structured JSON logs with request ids (`GINA_LOG_FORMAT=json`) |
 | Dev Inspector | Embedded dev SPA at `/_gina/inspector` — request data, live logs, SQL with index-coverage badges, flow timings, app events, AI token stream |
 | OpenAPI & MCP | `bundle:openapi` emits OpenAPI 3.1 from `routing.json`; `bundle:mcp` emits an MCP tool manifest; built-in MCP runtime server (stdio + Streamable HTTP) |
@@ -62,23 +66,29 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.6.24
+## What's in 0.6.25
 
-> **Restart your bundles — no rebuild needed.** This release does not change the
-> browser bundle: all three fixes are server-side, inside the Couchbase
-> connector. A `gina bundle:restart` is enough, and `gina bundle:build` is not
-> required. Projects on other connectors are unaffected.
+> **Restart AND rebuild your bundles.** This release changes the browser bundle:
+> the exact-money primitive (`gina.money`), the `isIban`/`isBic` validation
+> rules and the routing-helper diagnostic all ride `gina.min.js`. Run
+> `gina bundle:build` after upgrading, then `gina bundle:restart`.
 
-> **No settings reset.** `0.6.24` is a patch — the `shortVersion` stays `0.6`,
+> **No settings reset.** `0.6.25` is a patch — the `shortVersion` stays `0.6`,
 > so your `~/.gina/0.6/settings.json` is untouched. (`0.6.0` was the reset.)
 
-**A Couchbase connector reliability release.** Three failure paths that reported
-nothing usable to the caller — one of them silently — now surface the real
-error. Full detail in [CHANGELOG.md](./CHANGELOG.md).
-
-- **Fixed — `bulkInsert` reports a failed prologue instead of returning `undefined` (#B460).** Its outer `try` wraps the method's own body, so a synchronous failure raised before the insert was dispatched — a connection that cannot be resolved, or either of the two `rec` validations — was caught, written to `console.error` and then swallowed, and the method fell off the end. Both documented call shapes broke on that path in opposite ways: the `await` form resolved with `undefined`, so a caller treating "did not throw" as success recorded an insert that never happened, and `.onComplete(cb)` threw a `TypeError` at the call site. In both, the error existed only in the log. The promise, its one-shot resolver and the `.onComplete` shim are now built before the `try`, so the outer catch settles the call. **Behaviour change:** a fire-and-forget call that ignores the return now surfaces an `unhandledRejection` where it previously failed silently. **Scope:** this changes what `bulkInsert` RETURNS, not what its promise RESOLVES WITH — a rows-less success still resolves `null`, so keep any rows-based success check you have.
-- **Fixed — a Couchbase entity that fails to register now names itself (#B461).** The catch guarding entity-class construction and `.sql`-derived method attachment emitted only a bare stack, and none of its three call sites captures a result or takes an error argument — so a throw left the entity partially built, or absent, with nothing in the log identifying which entity or which `.sql` file was responsible. The first symptom was a missing method at request time, arbitrarily far from the cause. The diagnostic now carries the entity, the source file, the method being attached and the underlying cause. Boot behaviour is deliberately unchanged: registration failures remain non-fatal.
-- **Fixed — the reconnect classifier no longer throws under every supported SDK (#B204).** `gina.onError`'s handler tested `err instanceof couchbase.Error`, but no supported couchnode exports a bare `Error` class, so the check raised `TypeError: Right-hand side of 'instanceof' is not an object` the moment the handler ran — and because that operand is evaluated first, the shutdown-bucket message arm was unreachable too. On the Express engine this replaced the real error with the `TypeError`; on the default `isaac` engine the listener is never dispatched at all, so there is no behaviour change there. Each `instanceof` is now guarded on the class existing. Deliberately a guard, not an activation: the arms it protects stay inert on modern SDKs, and the real error now reaches the handler's designed terminal path.
+**The financial-messaging foundations release** — five additive building blocks
+for ISO 20022-class and payments-grade applications, plus one hardening fix and
+two bug fixes. Full detail in [CHANGELOG.md](./CHANGELOG.md).
+
+- **Added — verbatim XML request bodies (#FIN1).** A POST, PUT or PATCH whose `Content-Type` is `application/xml`, `text/xml` or any `application/*+xml` type reaches your action verbatim: `req.body` is the exact document as a string, and you parse it with the library of your choice — gina never parses XML itself. Previously such a body was silently destroyed by the form-encoded decode path.
+- **Added — `self.renderXML(xmlContent, contentType)` (#FIN2).** First-class XML responses: send a pre-serialised document and the delegate owns the wire concerns — `application/xml` by default with your bundle's charset (RFC 7303), an optional `+xml`-suffix content type (`application/soap+xml`, `atom+xml`, vendor trees), HEAD suppression with byte-accurate `content-length`, the HTTP/2 pseudo-header status, opt-in trailers.
+- **Added — message-schema validation seam (#FIN3).** Declare `"messageValidator": "<name>"` in a route's `param` block and ship a factory at `message-validators/<name>.js` — boot-compiled (a broken module refuses the boot instead of silently skipping validation), sync or async, fed the verbatim body string. Refusals are fail-closed: 422 with your `errors` array, 400 for an unparseable document, 503 + `Retry-After` when your checker is down. Gina ships no schema engine — the validator is yours; the hook, the ordering and the refusal shape are the framework's.
+- **Added — `isIban` / `isBic` FormValidator rules (#FIN4).** IBAN per ISO 13616 — shape, official per-country length for 87 registered countries, and the ISO 7064 MOD 97-10 checksum — with a tolerant read (case and separators normalized for validation only; the stored value is never mutated), plus BIC per ISO 9362. Client + server, like every built-in rule.
+- **Added — exact-money primitive (#FIN5).** `lib.money` server-side and `gina.money` in the browser bundle: ISO 4217 minor-unit integer arithmetic on BigInt, strict wire-string `parse()` that rejects float inputs, `add`/`subtract`/`multiply`/`compare` with same-currency guards, canonical `format()`. Display formatting stays with `Intl.NumberFormat`.
+- **Added — idempotency keys (#FIN6).** Opt-in `Idempotency-Key` request deduplication at the router band, per the IETF draft: the recorded first response replays with `Idempotency-Replayed: true`, a duplicate in flight gets 409 + `Retry-After`, key reuse with a different payload gets 422. Principal-scoped, over a kv namespace you declare; dormant unless enabled.
+- **Security — Inspector inline-script data can no longer be read as template source.** The shared inline-script helper now escapes `{` and `}` inside JSON string literals as well as `<`, so a stored value like `{{ 7*7 }}` renders literally instead of executing with the page's locals in scope. Values parse back identical; only pages emitting the Inspector block were reachable.
+- **Fixed — the `query()` basic-auth option is honoured on HTTP/2 and can no longer leak (#B465).** `options.auth` is minted into `Authorization: Basic` before dispatch on BOTH transports and the option is deleted pre-dispatch. Previously node consumed it on HTTP/1.x only, while the HTTP/2 path forwarded it as a literal `auth:` header with authentication silently unperformed. A caller-supplied authorization header always wins.
+- **Fixed — the client-side routing helper no longer swallows its own diagnostic (#B462).** A route missing from the running table now surfaces as a `console.warn` on the first sighting (the `gina.notFound` registry still dedups repeats), and the alternate-route arm records its registry entry so repeat counts accumulate.
 
 ## Documentation
 

package/ROADMAP.md

@@ -75,10 +75,11 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q4 2026** | `0.6.21` ✅ | **Fixed**: an outbound `route.request()` now settles its callback on every outcome — the request object was discarded, so nothing could attach an `error` listener, and a dial failure either never invoked the callback at all (a permanent stall for anything serialized, with nothing logged) or reached `uncaughtException` and terminated the bundle; a response stream dying mid-body waited on an `end` event it would never emit. `options.timeout` was accepted but inert — Node only emits a `timeout` event and never destroys the socket — and is now honoured, so a value set in the belief that it capped the call will begin aborting requests at that budget. **Fixed**: `merge()` no longer throws `TypeError: Cannot read properties of null` on an id-keyed array carrying a `null` element, on either operand at any index — the read-side counterpart of the write-side fix that shipped in `0.6.20`. **Fixed**: on Safari, modifier chords (paste, select-all, copy, cut, undo) work again in live-checked fields carrying `autocomplete="off"` — the form-level keydown proxy cancelled the native keydown before the typing interception could decide anything, and `preventDefault` on a native keydown suppresses the browser's editing command itself, so no `paste` event was dispatched anywhere; Chromium-family browsers were never affected. Restart **and** rebuild your bundles (the browser bundle changed — all three fixes ship in `gina.min.js`). |
 | **Q4 2026** | `0.6.22` ✅ | **Security**: prototype pollution on the request path — client-supplied bracket-notation field names (`__proto__[x]`, `constructor[prototype][x]`, and their percent-encoded forms) reached an unguarded property assignment in the data helper's key-path nesting and wrote to `Object.prototype` silently (the parsed body came back empty, so nothing in the request looked wrong), and `merge()` copied an **own** `__proto__` key — the shape `JSON.parse` produces — through its `for...in` loops. Reachable from query strings, urlencoded and JSON request bodies, `request.query.inheritedData` and multipart text-field names; a polluted prototype could then influence code reading a property it expects to be absent — outbound request options (host, port, auth, the TLS certificate check) and the safe-method and exemption checks. Both sources now reject the same three key names — rejecting the key name is what closes this, since an own `__proto__` (the shape `JSON.parse` produces) satisfies an own-property check. **Fixed**: a form submit that fails at the TRANSPORT layer (network down, connection refused, server restarting) settled with no HTTP status and dispatched neither `error.<formId>` nor `error.<formId>.hform`, so a handler declared with `data-gina-form-event-on-submit-error` never ran while the form released its submit trigger and reported nothing to the visitor; both events now fire with `status: 408` and `transportError: true`, the latter distinguishing it from a genuine request timeout, and handlers matching on `status >= 400` keep working unchanged. Restart **and** rebuild your bundles (the browser bundle changed — both fixes ship in `gina.min.js`). |
 | **Q4 2026** | `0.6.23` ✅ | **Security**: hardened inline-script escaping — the previous guard matched only the literal `</script>` and `<!--`, but the HTML5 script-data end tag also accepts a tab, newline, form feed, space or `/` after the tag name, so `</script >` closed the block and the remainder of a stored value parsed as HTML; serialised values now neutralise `<` itself at every site, with U+2028/U+2029 escaped too, and escaped output parses back to an identical value. **Added**: the framework itself now emits seven security headers by default on both engines (`server.securityHeaders`; four more opt-in — `xFrameOptions` / `coop` / `corp` / `hsts`), first-writer-wins so mounted plugins, `env.json` headers and proxies keep winning, with `/_gina/*` exempt from the cross-origin-isolating pair; `server.hidePoweredBy` now defaults to `true`. **Added**: `server.maxBodySize` (default 64MB, 413 + stream destroyed) bounds non-multipart request bodies, with warn-only `server.maxBodySizeWarn` (2MB) and a configurable `server.timeout` that stays `0` on purpose (SSE/WebSocket). **Added**: opt-in Subresource Integrity — `templates.json > "sriEnabled": true` adds `integrity` + `crossorigin` to same-origin script and stylesheet tags that resolve on disk; fail-open, hashes stat-validated per render. **Fixed**: a JSON body whose nested object shadows `constructor` with a primitive, null, array or plain object no longer crashes the merge on the PUT path. Restart **and** rebuild your bundles (the browser bundle changed — the merge fix ships in `gina.min.js`). |
+| **Q4 2026** | `0.6.25` ✅ | **Added**: the financial-messaging foundations — verbatim XML request bodies on POST/PUT/PATCH (`req.body` keeps the exact document the client sent; the form-encoded decode path previously destroyed it silently) with `self.renderXML()` as the outbound counterpart (`application/xml` by default per RFC 7303, an optional `+xml`-suffix content type, HEAD suppression with byte-accurate `content-length`, HTTP/2 pseudo-header status, opt-in trailers — gina parses no XML and builds none); a pluggable message-schema validation seam (declare `param.messageValidator: "<name>"` on a route and ship a factory at `message-validators/<name>.js` — boot-compiled, fail-closed refusals: 422 with your `errors` array, 400 unparseable, 503 + `Retry-After` when the checker is down — ordered after auth/rate-limit/idempotency and before DTO field validation); `isIban` / `isBic` FormValidator rules (ISO 13616 shape + official per-country length for 87 countries + ISO 7064 MOD 97-10, and ISO 9362 — tolerant read, the stored value is never mutated; client + server like every built-in rule); an exact-money primitive (`lib.money` server-side and `gina.money` in the browser bundle — ISO 4217 minor-unit integer arithmetic on BigInt with strict wire-string `parse()`, same-currency guards and canonical `format()`; display stays with `Intl.NumberFormat`); and opt-in `Idempotency-Key` request deduplication at the router band per the IETF draft (the recorded first response replays with `Idempotency-Replayed: true`; 409 + `Retry-After` while the original is in flight; 422 on key reuse with a different payload; principal-scoped over a declared kv namespace). **Security**: server data serialised into the Inspector's inline script blocks can no longer be read as template source — the shared inline-script helper now escapes `{` and `}` inside JSON string literals as well as `<`, so a stored `{{ 7*7 }}` renders literally instead of executing with the page's locals in scope (values parse back identical; only pages emitting the Inspector block were reachable). **Fixed**: the query() basic-auth option is honoured on HTTP/2 and can no longer leak — `options.auth` is minted into `Authorization: Basic` before dispatch on BOTH transports and the option is deleted pre-dispatch (previously node consumed it on HTTP/1.x only, while the HTTP/2 path forwarded it as a literal `auth:` header with authentication silently unperformed; a caller-supplied authorization header always wins); and the client-side routing helper no longer swallows its "route not found inside your view" diagnostic — `console.warn` on the first sighting of each missing route, with repeats counted on `gina.notFound`. Restart **and** rebuild your bundles — the browser bundle changed (the money primitive, the IBAN/BIC rules and the routing-helper diagnostic ride `gina.min.js`). |
 | **Q4 2026** | `0.6.24` ✅ | **Fixed**: Couchbase `bulkInsert` no longer returns `undefined` when its own prologue throws — the outer `try` wraps the method body, so a synchronous failure (an unresolvable connection, or either `rec` validation) was caught, logged and swallowed, and the method fell off the end: the `await` form resolved with `undefined`, so a caller treating "did not throw" as success recorded an insert that never happened, and `.onComplete(cb)` threw a `TypeError` at the call site. The promise, its one-shot resolver and the `.onComplete` shim are now built before the `try`, so the outer catch settles the call. A fire-and-forget call now surfaces an `unhandledRejection` where it previously failed silently, and the fix moves what `bulkInsert` RETURNS, not what its promise RESOLVES WITH — a rows-less success still resolves `null`. **Fixed**: a Couchbase entity that fails to register now names itself, its source file, the method being attached and the underlying cause, instead of emitting a bare stack that left a partially-built entity and a missing method surfacing arbitrarily far from the cause; registration stays non-fatal. **Fixed**: the reconnect classifier no longer throws under every supported SDK — `err instanceof couchbase.Error` raised a `TypeError` because no supported couchnode exports a bare `Error` class, and since that operand is evaluated first the message arm was unreachable too, so the classifier could not classify by any route; each `instanceof` is now guarded on the class existing (deliberately a guard, not an activation — on the default `isaac` engine the listener is never dispatched at all). Restart your bundles — the browser bundle is unchanged, so no rebuild is needed. |
 | **Q1 2027** | `0.6.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **2027** | `0.7.0` | Performance — remaining measure-gated candidates: multipart & WebSocket fast paths, render/log cleanups, SIMD scanner (the render-path deep-clone & id-mint reduction shipped early in `0.6.2` with a measured 4.4× render-throughput gain; the profiling baseline itself also shipped in `0.6.2`) |
-| **2027** | `0.8.0` | Financial-messaging foundations — XML request/response handling · pluggable message-schema validation · IBAN/BIC validation rules · money & ISO 4217 minor-unit utilities · idempotency keys · sequence primitive · OAuth2 client-credentials egress |
+| **2027** | `0.8.0` | Financial-messaging foundations — XML request/response handling · pluggable message-schema validation · IBAN/BIC validation rules · money & ISO 4217 minor-unit utilities · idempotency keys |
 | **2027** | `0.9.0` | Financial-integration heavyweights — entity-layer datastore transaction seam · message-queue connector family (AMQP / Kafka / IBM MQ) |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
 
@@ -324,15 +325,15 @@ Plumbing for financial-messaging (ISO 20022-class XML flows) and ledger-grade ap
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
-| 📋 | **XML request handling** — `application/xml` / `text/xml` request bodies reach the application verbatim (alongside `req.rawBody`) instead of being run through the form-encoded decode path; the application parses with the XML library of its choice. | `0.8.x` | 2027 |
-| 📋 | **`renderXML` delegate** — first-class XML responses (content type + charset), mirroring `renderJSON`. | `0.8.x` | 2027 |
-| 📋 | **Pluggable message-schema validation** — a seam for validating inbound/outbound messages against the XSDs or usage-guideline validators the application supplies, with a fail-closed 400/422 shape — kept pluggable so the framework never takes on a native-addon dependency. | `0.8.x` | 2027 |
-| 📋 | **IBAN / BIC validation rules** — ISO 13616 (MOD-97) and ISO 9362 shape checks as built-in FormValidator rules, client and server. | `0.8.x` | 2027 |
-| 📋 | **Money & minor-unit utilities** — an ISO 4217 minor-unit exponent table plus a documented exact-money pattern (amounts as strings on the wire, integer minor units internally) and helpers, so monetary values never ride IEEE-754 float arithmetic. | `0.8.x` | 2027 |
-| 📋 | **Idempotency keys** — store-backed request deduplication: a client-supplied idempotency key makes a retried mutation return the recorded first response instead of executing twice. | `0.8.x` | 2027 |
-| 📋 | **Sequence primitive** — monotonic (optionally gapless) reference-number allocation backed by a durable store. | `0.8.x` | 2027 |
+| ✅ | **XML request handling** — `application/xml`, `text/xml` and the `application/*+xml` suffix family (SOAP, Atom, RSS, vendor trees) reach the application verbatim on POST, PUT and PATCH — alongside `req.rawBody` — instead of being run through the form-encoded decode path, which previously split the document on `&` and `=` and kept only the first pair, silently collapsing it to a single bogus key. The framework never parses XML itself, so it takes on no XML-parser surface; the application parses with the library of its choice. The matched set follows the convention ASP.NET Core, Spring and type-is share, with the `+xml` wildcard scoped to `application/` — so `image/svg+xml` is not matched, and the RFC 7303 types that are not XML documents are excluded. urlencoded, JSON and multipart bodies are unaffected. | `0.6.x` | 2026-09-03 |
+| ✅ | **`renderXML` delegate** — first-class XML responses: `self.renderXML(doc)` sends a pre-serialised document with `application/xml` and the bundle charset, and an optional second argument covers the suffix family (`application/soap+xml`, `application/atom+xml`, a vendor tree). The status comes from the response, not the payload; HEAD, HTTP/2 pseudo-header status, upstream header folding and opt-in trailers all behave as they do for `renderJSON`, and an idempotency-keyed route records its envelope here too. The application serialises with the library of its choice — the framework builds no XML. | `0.6.x` | 2026-09-03 |
+| ✅ | **Pluggable message-schema validation** — routes opt in with `param.messageValidator`, naming a factory module the bundle ships (`message-validators/<name>.js`): the factory runs once at boot (compile schemas or open a sidecar pool there — a broken module refuses the boot rather than silently skipping validation) and the returned `validate(document, req)` function — sync or async — receives the verbatim request body ahead of the controller action, after authorization, rate limiting and idempotency and before DTO field validation. Refusals are fail-closed: 422 by default with the validator's `errors` array on the response body, 400 for a document that does not parse, 503 + `Retry-After` when the checker itself is unavailable, and 500 on a thrown error — a request never proceeds unvalidated. The framework ships no schema engine (no native-addon XSD dependency, no new parser surface): the validator is the application's. | `0.6.x` | 2026-09-03 |
+| ✅ | **IBAN / BIC validation rules** — `isIban` and `isBic` built-in FormValidator rules, client and server: `isIban` validates the ISO 13616 shape, the official per-country length (87 registered countries — unknown country codes pass on shape + checksum) and the ISO 7064 MOD 97-10 checksum, with a tolerant read (case and space/hyphen separators are normalized for validation only; the stored value is never mutated); `isBic` validates the 8/11-character ISO 9362 shape case-insensitively. | `0.6.x` | 2026-09-03 |
+| ✅ | **Money & minor-unit utilities** — Exact-money primitive: `lib.money` server-side and `gina.money` in the browser bundle, with an ISO 4217 minor-unit exponent table (JPY 0, BHD 3, …) and the documented pattern — amounts as strings on the wire, integer minor units (BigInt) internally, so monetary values never ride IEEE-754 float arithmetic. Strict parse rejects floats and excess precision (rounding stays the application's); same-currency arithmetic throws on mismatch; display formatting stays with `Intl.NumberFormat`. | `0.6.x` | 2026-09-03 |
+| ✅ | **Idempotency keys** — `Idempotency-Key` request deduplication at the router band, per the IETF draft: a route opts in via routing.json (`idempotency: true` / `{ "required": true }`), the first request reserves the operation over the kv primitive and executes, and a retried mutation returns the RECORDED first response (`Idempotency-Replayed: true`) instead of executing twice — 409 + Retry-After while the original is in flight, 422 when the key is reused with a different payload, principal-scoped so a stored response never crosses callers; anonymous requests are skipped. | `0.6.x` | 2026-09-03 |
+| ⏸ | **Sequence primitive** — monotonic (optionally gapless) reference-number allocation. **Deferred — sequenced after the entity-layer transaction seam.** Monotonic counters already ship: the key-value primitive's `incr` is atomic and durable (TTL-on-create counters over the redis and SQLite backends), with `setnx` to seed a starting value. The gapless variant is deliberately not a standalone feature: gapless means *every allocated value lands on a committed record*, which requires the increment to commit atomically **with** the caller's own write — an allocator in a separate failure domain burns a number whenever the caller's write fails, and no return path closes that honestly. That capability belongs to the transaction seam and will be designed with it. *Interim:* use `gina.kv('<namespace>').incr(key)` for durable monotonic references; for gapless numbering, allocate at issuance time inside your own store's transaction (draft records stay unnumbered; stamp the reference and advance the counter in one atomic unit) — the documented per-connector transaction escape hatches carry this today. | — | on demand |
 | 📋 | **Datastore transaction seam** — a uniform entity-layer transaction surface with per-connector capability flags; until it ships, the documented per-connector native escape hatches remain the supported answer. | `0.9.x` | 2027 |
-| 📋 | **OAuth2 client-credentials egress** — token acquisition and refresh (including signed-JWT client assertions) for outbound `self.query()` calls to OAuth2-protected APIs. | `0.8.x` | 2027 |
+| ⏸ | **OAuth2 client-credentials egress** — token acquisition and refresh for outbound `self.query()` calls. **Deferred — built on request.** Measured at deferral time: no consumer integration currently exercises OAuth2 client-credentials on the request path, no consumer needs signed-JWT client assertions, and the one real-world token lifecycle measured is protocol-specific rather than OAuth2 — so the shape that gets built, when a consumer integration needs it, is a protocol-agnostic bearer-token helper (named token profiles, cached in a key-value namespace with single-flight acquisition, reactive refresh on 401) with OAuth2 client-credentials as a preset. *Interim:* attach the header yourself via `options.headers.authorization` (honoured on both HTTP/1.x and HTTP/2 — the framework adds its own headers but never overwrites yours), own token acquisition in application code, and cache tokens with `gina.kv('<namespace>').getOrSet(...)` for TTL + per-process single-flight. | — | on demand |
 | 📋 | **Message-queue connector family** — first-class messaging connectors (AMQP / Kafka / IBM MQ) in the `connectors.json` model, for integration with message-based platforms. | `0.9.x` | 2027 |
 
 ---

package/framework/v0.6.25/VERSION

@@ -0,0 +1 @@
+0.6.25