@aventara/nest 0.1.0-pilot.1 → 0.1.0-pilot.3

package/README.md

@@ -126,6 +126,21 @@ own when it mounts them, through Nest's `Logger` (context `AventaraModule`; `log
 [Nest] LOG [AventaraModule] Aventara mounted 10 operations at /api (+ GET /api/_contract, POST /api/_transactions)
 ```
 
+An internal failure (`A3000`–`A3004`, answered as a 500) is logged as one error line through Nest's `Logger`
+(context `Aventara`): the code, the operation, the scope and the request id, and the thrown value's class name — never
+its message, which can hold SQL or a connection string. The raw error still goes to your `diagnostics` sink, when you
+configure one:
+
+```text
+[Nest] ERROR [Aventara] A3001 on Post.create.one (client scope, request 3f1c…): PrismaClientValidationError. The raw error goes to the framework's diagnostics sink.
+```
+
+For `A3004` — one of your pipes returned arguments the server contract refuses — the line also names the pipe, the
+operation, the offending field and its V-code; the caller only ever sees the generic message.
+
+The line is added when the module builds the framework from `config`; a framework you build yourself and pass as
+`framework` keeps exactly the `diagnostics` sink you gave it.
+
 The framework's validation is outermost:
 
 | | Express | Fastify |

package/dist/aventara.module.d.ts

@@ -2,17 +2,16 @@ import { type AdapterModel, type AnyFrameworkConfig, type Framework, type Framew
 import { type DynamicModule, type FactoryProvider, type ModuleMetadata, type NestModule, type OnModuleInit } from "@nestjs/common";
 import { type PendingProtocolHost } from "./protocol-host.factory.js";
 /**
- * How the application's Framework enters Nest (Q1, ruled): either the
- * developer's own instance — they called `createFramework` — or the
- * configuration the module hands to `createFramework` itself. Exactly one arm;
- * the `?: never` halves make both a type error.
+ * How the application's Framework enters Nest: either the developer's own instance
+ * — they called `createFramework` — or the configuration the module hands to
+ * `createFramework` itself. Exactly one arm; the `?: never` halves make both a
+ * type error.
  *
- * The `config` arm is typed exactly as `createFramework`'s parameter
- * (`Cfg & FrameworkConfig<M, Cfg>`; U12, architect 2026-10-05), so a
+ * The `config` arm is typed exactly as `createFramework`'s parameter, so a
  * configuration annotated `FrameworkConfig<M>`, written inline, inferred or
- * checked with `satisfies` is accepted — and checked against its own Adapter
- * model — wherever `createFramework` would accept it. The defaults are the
- * untyped forms.
+ * checked with `satisfies` is accepted — and checked against its own Adapter model
+ * — wherever `createFramework` would accept it. The defaults are the untyped
+ * forms.
  */
 export type AventaraModuleOptions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
     readonly framework: Framework;
@@ -22,9 +21,9 @@ export type AventaraModuleOptions<M extends AdapterModel = AdapterModel, Cfg = A
     readonly framework?: never;
 };
 /**
- * `forRootAsync`'s options: the Nest idiom when what builds the Framework
- * (a Prisma client, a configuration service) is itself a provider. The
- * factory resolves to either arm of {@link AventaraModuleOptions} (Q1).
+ * `forRootAsync`'s options: the Nest idiom when what builds the Framework (a
+ * Prisma client, a configuration service) is itself a provider. The factory
+ * resolves to either arm of {@link AventaraModuleOptions}.
  */
 export type AventaraModuleAsyncOptions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
     readonly imports?: ModuleMetadata["imports"];
@@ -32,16 +31,16 @@ export type AventaraModuleAsyncOptions<M extends AdapterModel = AdapterModel, Cf
     readonly useFactory: (...deps: never[]) => AventaraModuleOptions<M, Cfg> | Promise<AventaraModuleOptions<M, Cfg>>;
 };
 /**
- * The global module that hosts one Aventara Framework (Q2, Q3), and mounts its
- * protocol on the application's platform from `configure()` (Q5): after the
- * developer's `app.use` / `enableCors`, before `MiddlewareConsumer` middleware
- * and every controller, so the reserved `_` namespace cannot be shadowed.
+ * The global module that hosts one Aventara Framework, and mounts its protocol on
+ * the application's platform from `configure()`: after the developer's `app.use` /
+ * `enableCors`, before `MiddlewareConsumer` middleware and every controller, so
+ * the reserved `_` namespace cannot be shadowed.
  */
 export declare class AventaraModule implements NestModule, OnModuleInit {
     private readonly host;
     constructor(host: PendingProtocolHost);
     configure(): void;
-    /** An application context never receives a platform: refused here, at its init (N1). */
+    /** An application context never receives a platform: refused here, at its init. */
     onModuleInit(): void;
     static forRoot<M extends AdapterModel, const Cfg = AnyFrameworkConfig>(options: AventaraModuleOptions<M, Cfg>): DynamicModule;
     static forRootAsync<M extends AdapterModel, const Cfg = AnyFrameworkConfig>(options: AventaraModuleAsyncOptions<M, Cfg>): DynamicModule;

package/dist/aventara.module.js

@@ -3,32 +3,21 @@ import { Inject, Module, } from "@nestjs/common";
 import { HttpAdapterHost } from "@nestjs/core";
 import { AVENTARA_FRAMEWORK } from "./framework.token.js";
 import { checkedOptions, recordMount } from "./host-bootstrap.validator.js";
+import { withInternalFailureLog } from "./internal-failure.logger.js";
 import { createPendingProtocolHost, } from "./protocol-host.factory.js";
-/**
- * One value per `forRoot`/`forRootAsync` call, carried in the module's
- * metadata: under Nest's opt-in `deep-hash` module ids, two calls whose
- * metadata serialized alike would collapse into one module and the second
- * mount would vanish instead of being refused (Q18).
- */
 const MOUNT = Symbol("AVENTARA_MOUNT");
 let mounts = 0;
-/** The bound protocol and its mounter for this application's platform. */
 const PROTOCOL_HOST = Symbol("AVENTARA_PROTOCOL_HOST");
-/**
- * The Framework the options name: the developer's instance, or the one
- * `createFramework` builds from the configuration — whose
- * `FrameworkConstructionError` propagates unchanged (Q1).
- */
 async function frameworkOf(options) {
     const checked = checkedOptions(options);
-    return checked.framework ?? createFramework(checked.config);
+    if (checked.framework !== undefined) {
+        return checked.framework;
+    }
+    return createFramework({
+        ...checked.config,
+        diagnostics: withInternalFailureLog(checked.config.diagnostics),
+    });
 }
-/**
- * The global module that hosts one Aventara Framework (Q2, Q3), and mounts its
- * protocol on the application's platform from `configure()` (Q5): after the
- * developer's `app.use` / `enableCors`, before `MiddlewareConsumer` middleware
- * and every controller, so the reserved `_` namespace cannot be shadowed.
- */
 export class AventaraModule {
     host;
     constructor(host) {
@@ -37,7 +26,6 @@ export class AventaraModule {
     configure() {
         this.host.mount();
     }
-    /** An application context never receives a platform: refused here, at its init (N1). */
     onModuleInit() {
         this.host.assertReady();
     }

package/dist/express-protocol.mounter.d.ts

@@ -2,33 +2,31 @@ import type { AvProtocolBinding } from "@aventara/core/protocol";
 import { type NodeIncoming, type NodeOutgoing } from "./node-exchange.translator.js";
 import type { ProtocolHost } from "./protocol-host.factory.js";
 /**
- * The protocol on Nest's Express platform (Q4, Q5, Q8, Q9, Q11, Q12, P1–P3).
+ * The protocol on Nest's Express platform.
  *
- * - **The pre-parser** (Q8), installed while Nest instantiates providers —
- *   before Nest's own body parsers: a request under `<entrypoint>/_` has its
- *   body read raw, bounded and decoded, and kept for its route. Its stream is
- *   then finished, so Nest's parsers skip it; every other request keeps
- *   Nest's parsed body. It reads; it answers nothing.
- * - **The routes**, mounted from the module's `configure()` (Q5): one platform
- *   route per `protocol.surface()` entry, each at its escaped literal path
- *   under the entrypoint, then one fallback — `protocol.answerAbsent`, the
- *   absence handler, not a catch-all: it executes nothing, and a path it does
- *   not own (`undefined`) goes on to Nest.
+ * - **The pre-parser**, installed while Nest instantiates providers — before
+ *   Nest's own body parsers: a request under `<entrypoint>/_` has its body read
+ *   raw, bounded and decoded, and kept for its route. Its stream is then finished,
+ *   so Nest's parsers skip it; every other request keeps Nest's parsed body. It
+ *   reads; it answers nothing.
+ * - **The routes**, mounted from the module's `configure()`: one platform route
+ *   per `protocol.surface()` entry, each at its escaped literal path under the
+ *   entrypoint, then one fallback — `protocol.answerAbsent`, the absence handler,
+ *   not a catch-all: it executes nothing, and a path it does not own (`undefined`)
+ *   goes on to Nest.
  *
- * Its whole job is translation: the Express request into an
- * `AvProtocolRequest`, the `AvProtocolResponse` back onto the wire. Express's
- * types are the slices below (P4: no `@types/node`, no `@types/express`).
+ * Its whole job is translation: the Express request into an `AvProtocolRequest`,
+ * the `AvProtocolResponse` back onto the wire.
  */
 /** Express's request: Node's `IncomingMessage`, plus `originalUrl`. */
 type ExpressRequest = NodeIncoming & {
     readonly method: string;
     readonly originalUrl: string;
 };
-/** Express's response, written through Node's own `writeHead` (P1: never `send`/`json`). */
+/** Express's response, written through Node's own `writeHead`. */
 type ExpressResponse = NodeOutgoing;
 /** Express passes `next`; Nest's handler type declares it as an optional `Function`. */
 type ExpressHandler = (request: ExpressRequest, response: ExpressResponse, next?: unknown) => unknown;
-/** The slice of Nest's `ExpressAdapter` this mounter registers on. */
 export type ExpressPlatform = {
     get(path: string, handler: ExpressHandler): unknown;
     post(path: string, handler: ExpressHandler): unknown;

package/dist/express-protocol.mounter.js

@@ -1,14 +1,8 @@
 import { NO_BYTES, pathnameOf, protocolRequest, writeAnswer, } from "./node-exchange.translator.js";
 import { PROTOCOL_ROUTES } from "./protocol-route.table.js";
 import { readRequestBody, unreadBodyAnswer, } from "./request-body.reader.js";
-/** The platform method that registers a route of each surface method. */
 const REGISTER = { GET: "get", POST: "post" };
-/** A request the pre-parser did not read: zero bytes. */
 const NOTHING_READ = { kind: "read", content: NO_BYTES };
-/**
- * Installs the pre-parser on `platform` now, and returns the host whose
- * `mount` registers the routes and the absence fallback under `entrypoint`.
- */
 export function createExpressProtocolHost(platform, binding, entrypoint, maxRequestBytes) {
     const bodies = new WeakMap();
     const bodyOf = (request) => bodies.get(request) ?? NOTHING_READ;
@@ -45,21 +39,14 @@ export function createExpressProtocolHost(platform, binding, entrypoint, maxRequ
         },
     };
 }
-/** Hands the request on to whatever Express runs next — Nest's own routes. */
 function handOn(next) {
     if (typeof next === "function") {
         next();
     }
 }
-/**
- * The route path as a literal for Express's router (`path-to-regexp` 8):
- * every character it reads as syntax is escaped, so a Resource key never
- * mounts a parameter or a wildcard (H11, DA-13).
- */
 function literalPath(path) {
     return path.replace(/[()[\]{}*+?!:\\]/g, "\\$&");
 }
-/** The Express request as the protocol reads it. */
 function translated(request, entrypoint, content) {
     return protocolRequest(request.method, request.originalUrl, request, entrypoint, content);
 }

package/dist/fastify-protocol.mounter.d.ts

@@ -2,37 +2,33 @@ import type { AvProtocolBinding } from "@aventara/core/protocol";
 import { type NodeIncoming, type NodeOutgoing, type PlatformHeaders } from "./node-exchange.translator.js";
 import type { ProtocolHost } from "./protocol-host.factory.js";
 /**
- * The protocol on Nest's Fastify platform (Q10; Q8, Q9, Q11, Q12, P1–P3 as on
- * Express), mounted from the module's `configure()` (Q5). Measured in S4:
+ * The protocol on Nest's Fastify platform, mounted from the module's
+ * `configure()`.
  *
  * - **One Fastify route per `protocol.surface()` entry**, at its literal path
- *   under the entrypoint, with Fastify's automatic `HEAD` route off (U9), so
- *   `HEAD /_contract` reaches the protocol's `405` as on Express (P3).
+ *   under the entrypoint, with Fastify's automatic `HEAD` route off, so `HEAD
+ *   /_contract` reaches the protocol's `405` as on Express.
  * - **Each route is answered from its own `onRequest` hook** — Fastify's first
- *   step, before its content-type check and body parsing: the body is read raw
- *   off Node's request by the bounded reader, the bound member answers, and the
- *   reply is hijacked. Fastify's parsers, `bodyLimit` and early `415` (on a
- *   `Content-Type` it cannot parse) never run on a protocol route, so every
- *   body failure is the protocol's own answer, as on Express (director,
- *   2026-10-05). The route handler is never reached.
- * - **The absence fallback** is a root `onRequest` hook acting only on a
- *   request Fastify matched to no route (`request.is404`) under
- *   `<entrypoint>/`: `protocol.answerAbsent`, and `undefined` hands the request
- *   on to Nest's own not-found handler (U8, director, 2026-10-05). A not-found
- *   handler of our own could not hand back: inside one, Fastify answers its
- *   plain-text 404, not Nest's.
- * - **Literal paths** (architect, 2026-10-05): each route is registered
- *   `decodeURI`-ed, as find-my-way decodes a request path before matching it
- *   (`café`, `a[b]`). A path find-my-way cannot match as a literal — a `*`
- *   (its wildcard) or a reserved escape (it keeps those encoded, and never
- *   matches them against a static route) — is refused while Nest builds the
- *   application, naming the Resource keys; Express mounts them all.
- * - **Writes** go through Node's response after `reply.hijack()` (P1: no
- *   charset rewrite, no lower-cased names, no added `Content-Type`), with the
- *   headers Fastify hooks already set (CORS) beneath the protocol's own —
- *   what Node's `writeHead` does on Express (director, 2026-10-05).
- *
- * Fastify's types are the slices below (P4).
+ *   step, before its content-type check and body parsing: the body is read raw off
+ *   Node's request by the bounded reader, the bound member answers, and the reply
+ *   is hijacked. Fastify's parsers, `bodyLimit` and early `415` (on a
+ *   `Content-Type` it cannot parse) never run on a protocol route, so every body
+ *   failure is the protocol's own answer, as on Express. The route handler is
+ *   never reached.
+ * - **The absence fallback** is a root `onRequest` hook acting only on a request
+ *   Fastify matched to no route (`request.is404`) under `<entrypoint>/`:
+ *   `protocol.answerAbsent`, and `undefined` hands the request on to Nest's own
+ *   not-found handler. A not-found handler of our own could not hand back: inside
+ *   one, Fastify answers its plain-text 404, not Nest's.
+ * - **Literal paths**: each route is registered `decodeURI`-ed, as find-my-way
+ *   decodes a request path before matching it (`café`, `a[b]`). A path find-my-way
+ *   cannot match as a literal — a `*` (its wildcard) or a reserved escape (it
+ *   keeps those encoded, and never matches them against a static route) — is
+ *   refused while Nest builds the application, naming the Resource keys; Express
+ *   mounts them all.
+ * - **Writes** go through Node's response after `reply.hijack()`, with the headers
+ *   Fastify hooks already set (CORS) beneath the protocol's own — what Node's
+ *   `writeHead` does on Express.
  */
 /** Fastify's request: Node's own under `raw`, and whether a route matched. */
 type FastifyRequest = {
@@ -49,7 +45,6 @@ type FastifyReply = {
     readonly raw: NodeOutgoing;
 };
 type OnRequestHook = (request: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply | undefined>;
-/** The slice of the Fastify instance (`httpAdapter.getInstance()`) this mounter registers on. */
 export type FastifyPlatform = {
     route(options: {
         readonly method: string;

package/dist/fastify-protocol.mounter.js

@@ -1,17 +1,7 @@
 import { NO_BYTES, pathnameOf, protocolRequest, writeAnswer, } from "./node-exchange.translator.js";
 import { PROTOCOL_ROUTES } from "./protocol-route.table.js";
 import { readRequestBody, unreadBodyAnswer } from "./request-body.reader.js";
-/**
- * What find-my-way cannot match in a static route path: its wildcard, and the
- * escapes of the characters `decodeURI` leaves encoded (: + # $ & , / ; = ? @).
- */
 const UNMATCHABLE = /\*|%(?:3A|2B|23|24|26|2C|2F|3B|3D|3F|40)/i;
-/**
- * Refuses an entrypoint find-my-way cannot match literally — a `*`, its
- * wildcard; every other character a canonical entrypoint may carry raw
- * mounts (measured S6; a `:` is doubled) — then, naming them, the Resource
- * keys whose routes it cannot match literally.
- */
 function checkLiteralRoutes(binding, entrypoint) {
     if (entrypoint.includes("*")) {
         throw new Error(`AventaraModule cannot mount the entrypoint \`${entrypoint}\` as a literal path on Nest's Fastify platform: it may not carry \`*\`. Change the entrypoint, or host on Express.`);
@@ -26,10 +16,6 @@ function checkLiteralRoutes(binding, entrypoint) {
         throw new Error(`AventaraModule cannot mount Resource ${refused.map((key) => `\`${key}\``).join(", ")} as literal routes on Nest's Fastify platform: a route path may not carry \`*\` or a reserved character (: + # $ & , / ; = ? @). Rename the Resource, or host on Express.`);
     }
 }
-/**
- * The host whose `mount` registers the routes and the absence hook under
- * `entrypoint` — after refusing, now, a surface it cannot mount literally.
- */
 export function createFastifyProtocolHost(platform, binding, entrypoint, maxRequestBytes) {
     checkLiteralRoutes(binding, entrypoint);
     const translated = (request, content) => protocolRequest(request.raw.method, request.raw.url, request.raw, entrypoint, content);
@@ -68,15 +54,9 @@ export function createFastifyProtocolHost(platform, binding, entrypoint, maxRequ
         },
     };
 }
-/**
- * The route path as find-my-way matches it: `decodeURI`-ed, as it decodes a
- * request path before the lookup, and every `:` (raw only in the entrypoint —
- * the surface encodes it) doubled, find-my-way's escape for a literal colon.
- */
 function literalPath(path) {
     return decodeURI(path).replaceAll(":", "::");
 }
-/** The protocol's answer on the hijacked reply, the hooks' headers beneath it. */
 function write(reply, answer) {
     reply.hijack();
     writeAnswer(reply.raw, answer, reply.getHeaders());

package/dist/framework.token.d.ts

@@ -1,10 +1,9 @@
 /**
  * The DI token under which `AventaraModule` provides the application's
- * `Framework` (Q2). A symbol, so injection is exact: an abstract-class token
- * would type the injected value as an empty class, not the application's own
- * `Framework<M, Cfg>` (Q3 — the application types the injection with its
- * own alias).
+ * `Framework`. A symbol, so injection is exact: an abstract-class token would type
+ * the injected value as an empty class, not the application's own `Framework<M,
+ * Cfg>`.
  */
 export declare const AVENTARA_FRAMEWORK: unique symbol;
-/** `@InjectFramework()` — `@Inject(AVENTARA_FRAMEWORK)` in one call (Q2). */
+/** `@InjectFramework()` — `@Inject(AVENTARA_FRAMEWORK)` in one call. */
 export declare function InjectFramework(): ParameterDecorator;

package/dist/framework.token.js

@@ -1,13 +1,5 @@
 import { Inject } from "@nestjs/common";
-/**
- * The DI token under which `AventaraModule` provides the application's
- * `Framework` (Q2). A symbol, so injection is exact: an abstract-class token
- * would type the injected value as an empty class, not the application's own
- * `Framework<M, Cfg>` (Q3 — the application types the injection with its
- * own alias).
- */
 export const AVENTARA_FRAMEWORK = Symbol("AVENTARA_FRAMEWORK");
-/** `@InjectFramework()` — `@Inject(AVENTARA_FRAMEWORK)` in one call (Q2). */
 export function InjectFramework() {
     return Inject(AVENTARA_FRAMEWORK);
 }

package/dist/host-bootstrap.validator.d.ts

@@ -3,7 +3,7 @@ import type { AventaraModuleOptions } from "./aventara.module.js";
 export declare function checkedOptions(options: unknown): AventaraModuleOptions;
 /** Records one mount in `application`; a second is refused. */
 export declare function recordMount(application: object): void;
-/** The Nest HTTP platforms the module mounts the protocol on (Q10). */
+/** The Nest HTTP platforms the module mounts the protocol on. */
 export type HostPlatform = "express" | "fastify";
 /** The application's platform, as `httpAdapter.getType()` names it — or a refusal. */
 export declare function checkedPlatform(type: string | undefined): HostPlatform;

package/dist/host-bootstrap.validator.js

@@ -1,14 +1,7 @@
-/**
- * Q18's bootstrap checks, all at module setup, so `NestFactory.create`
- * rejects before the application listens: plain `Error`s with fixed messages
- * (no new public name — Q18 a). A `FrameworkConstructionError` is core's and
- * passes through untouched; nothing here wraps it.
- */
 const NEITHER_ARM = "AventaraModule: the options carry neither `framework` nor `config`; pass exactly one.";
 const BOTH_ARMS = "AventaraModule: the options carry both `framework` and `config`; pass exactly one.";
 const NOT_A_FRAMEWORK = "AventaraModule: `framework` is not an Aventara Framework (it has no string `entrypoint` and no `contracts.client`); pass what `createFramework` resolved to.";
 const MOUNTED_TWICE = "AventaraModule is mounted twice in one application; import AventaraModule.forRoot or forRootAsync once.";
-/** The options as given — `forRootAsync`'s factory may resolve anything at runtime. */
 export function checkedOptions(options) {
     const record = typeof options === "object" && options !== null
         ? options
@@ -26,7 +19,6 @@ export function checkedOptions(options) {
     }
     return record;
 }
-/** What the host reads of a Framework: its entrypoint, and its compiled ClientContract. */
 function isFramework(value) {
     if (typeof value !== "object" || value === null) {
         return false;
@@ -36,13 +28,7 @@ function isFramework(value) {
         typeof candidate.contracts?.client === "object" &&
         candidate.contracts.client !== null);
 }
-/**
- * Applications that already mount the module, keyed by an object Nest creates
- * once per application (its `HttpAdapterHost`). Weak, so a closed
- * application's entry goes with it.
- */
 const mounted = new WeakSet();
-/** Records one mount in `application`; a second is refused. */
 export function recordMount(application) {
     if (mounted.has(application)) {
         throw new Error(MOUNTED_TWICE);
@@ -50,7 +36,6 @@ export function recordMount(application) {
     mounted.add(application);
 }
 const HOST_PLATFORMS = ["express", "fastify"];
-/** The application's platform, as `httpAdapter.getType()` names it — or a refusal. */
 export function checkedPlatform(type) {
     const platform = HOST_PLATFORMS.find((supported) => supported === type);
     if (platform === undefined) {

package/dist/internal-failure.logger.d.ts

@@ -0,0 +1,8 @@
+import type { FrameworkDiagnostic, FrameworkDiagnosticsSink } from "@aventara/core";
+/** Wraps the application's sink (if any): log an internal failure, then forward. */
+export declare function withInternalFailureLog(sink: FrameworkDiagnosticsSink | undefined): FrameworkDiagnosticsSink;
+/**
+ * e.g. `A3001 on Post.create.one (client scope, request 7f3c…): Error. The raw
+ * error goes to the framework's diagnostics sink.`
+ */
+export declare function internalFailureLine(diagnostic: FrameworkDiagnostic): string;

package/dist/internal-failure.logger.js

@@ -0,0 +1,46 @@
+import { Logger } from "@nestjs/common";
+const INTERNAL_FAILURE_LOGGER = new Logger("Aventara");
+export function withInternalFailureLog(sink) {
+    return (diagnostic) => {
+        if (diagnostic.code.startsWith("A3")) {
+            try {
+                INTERNAL_FAILURE_LOGGER.error(internalFailureLine(diagnostic));
+            }
+            catch {
+            }
+        }
+        return sink?.(diagnostic);
+    };
+}
+export function internalFailureLine(diagnostic) {
+    const subject = diagnostic.kind === "operation"
+        ? `${diagnostic.resource}.${diagnostic.family}.${diagnostic.variant}`
+        : "a transaction";
+    const step = diagnostic.operation === undefined
+        ? ""
+        : `, plan operation ${diagnostic.operation}`;
+    return `${diagnostic.code} on ${subject} (${diagnostic.scope} scope, request ${diagnostic.requestId}${step}): ${thrownKind(diagnostic.error)}${frameworkDetail(diagnostic.error)}. The raw error goes to the framework's diagnostics sink.`;
+}
+function frameworkDetail(error) {
+    try {
+        if (error instanceof Error &&
+            error.name === "PipeOutputError" &&
+            typeof error.message === "string") {
+            return ` — ${error.message}`;
+        }
+    }
+    catch {
+    }
+    return "";
+}
+function thrownKind(error) {
+    try {
+        const name = error instanceof Error ? error.constructor.name : undefined;
+        return typeof name === "string" && /^[A-Za-z_$][\w$]{0,63}$/.test(name)
+            ? name
+            : "a non-Error value";
+    }
+    catch {
+        return "an unreadable value";
+    }
+}

package/dist/node-exchange.translator.d.ts

@@ -1,14 +1,7 @@
 import type { AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
-/**
- * The translation both platforms share, because both hand the host Node's own
- * request and response (Q10: shared only as measured — S4 ran the corpus on
- * Express and Fastify through it). Node's types are the slices below (P4).
- */
-/** The slice of Node's `IncomingMessage` the host reads. */
 export type NodeIncoming = AsyncIterable<Uint8Array> & {
     readonly headersDistinct: Readonly<Record<string, readonly string[]>>;
 };
-/** The slice of Node's `ServerResponse` the host writes (P1: no platform reply path). */
 export type NodeOutgoing = {
     writeHead(status: number, headers: Readonly<Record<string, string | number | readonly string[]>>): unknown;
     end(body: string): unknown;
@@ -17,14 +10,16 @@ export type NodeOutgoing = {
 export type PlatformHeaders = Readonly<Record<string, string | number | readonly string[] | undefined>>;
 /** Zero bytes: the body of a request whose body the protocol does not read. */
 export declare const NO_BYTES: Uint8Array<ArrayBuffer>;
-/** A request URL's raw pathname — query dropped (Q12), not URL-decoded (P2). */
+/** A request URL's raw pathname — query dropped, not URL-decoded. */
 export declare function pathnameOf(url: string): string;
-/** The request as the protocol reads it: path relative to the entrypoint, `headersDistinct` (Q11), the raw arm (Q8). */
+/**
+ * The request as the protocol reads it: path relative to the entrypoint,
+ * `headersDistinct`, the raw arm.
+ */
 export declare function protocolRequest(method: string, url: string, incoming: NodeIncoming, entrypoint: string, content: Uint8Array): AvProtocolRequest;
 /**
- * The protocol's answer, written as it is (P1). Headers the platform's hooks
- * already set (CORS, say) go beneath it; a protocol header of the same name,
- * in any case, wins — what Node's `writeHead` does with `setHeader`'s on
- * Express.
+ * The protocol's answer, written as it is. Headers the platform's hooks already
+ * set (CORS, say) go beneath it; a protocol header of the same name, in any case,
+ * wins — what Node's `writeHead` does with `setHeader`'s on Express.
  */
 export declare function writeAnswer(response: NodeOutgoing, answer: AvProtocolResponse, beneath?: PlatformHeaders): void;

package/dist/node-exchange.translator.js

@@ -1,11 +1,8 @@
-/** Zero bytes: the body of a request whose body the protocol does not read. */
 export const NO_BYTES = new Uint8Array();
-/** A request URL's raw pathname — query dropped (Q12), not URL-decoded (P2). */
 export function pathnameOf(url) {
     const query = url.indexOf("?");
     return query === -1 ? url : url.slice(0, query);
 }
-/** The request as the protocol reads it: path relative to the entrypoint, `headersDistinct` (Q11), the raw arm (Q8). */
 export function protocolRequest(method, url, incoming, entrypoint, content) {
     return {
         method,
@@ -14,12 +11,6 @@ export function protocolRequest(method, url, incoming, entrypoint, content) {
         body: { kind: "raw", content },
     };
 }
-/**
- * The protocol's answer, written as it is (P1). Headers the platform's hooks
- * already set (CORS, say) go beneath it; a protocol header of the same name,
- * in any case, wins — what Node's `writeHead` does with `setHeader`'s on
- * Express.
- */
 export function writeAnswer(response, answer, beneath = {}) {
     const own = new Set(Object.keys(answer.headers).map((name) => name.toLowerCase()));
     const headers = {};

package/dist/protocol-host.factory.d.ts

@@ -7,9 +7,9 @@ export type ProtocolHost = {
 };
 /**
  * Binds `framework`'s protocol for the application's platform, refusing an
- * unsupported platform while providers are instantiated — so
- * `NestFactory.create` rejects before the application listens (Q18). The
- * routes are mounted later, from the module's `configure()` (Q5).
+ * unsupported platform while providers are instantiated — so `NestFactory.create`
+ * rejects before the application listens. The routes are mounted later, from the
+ * module's `configure()`.
  */
 export declare function createProtocolHost(adapter: AbstractHttpAdapter | undefined, framework: Framework): ProtocolHost;
 /**
@@ -32,17 +32,14 @@ export type AdapterHostView = {
     };
 };
 /**
- * N1 (plan B23) — a host for an application whose HTTP adapter may arrive after
- * the providers are instantiated.
- *
- * `NestFactory.create` sets the adapter first: the host is created at once, and
- * an unsupported platform rejects then, as before (Q18). Nest's testing module
- * compiles first and receives its adapter from `createNestApplication()`, which
- * sets it on the `HttpAdapterHost` — `init$` fires — before `app.init()`
- * registers Nest's body parsers: the host is created at that moment, so a
- * platform's body reader is still installed ahead of them (Q8). A refusal there
- * is kept and raised by `mount()` or `assertReady()`, from `app.init()` — still
- * before the application listens. With no adapter at all
- * (`createApplicationContext`), `assertReady()` refuses from `onModuleInit`.
+ * `NestFactory.create` sets the adapter first: the host is created at once, and an
+ * unsupported platform rejects then, as before. Nest's testing module compiles
+ * first and receives its adapter from `createNestApplication()`, which sets it on
+ * the `HttpAdapterHost` — `init$` fires — before `app.init()` registers Nest's
+ * body parsers: the host is created at that moment, so a platform's body reader is
+ * still installed ahead of them. A refusal there is kept and raised by `mount()`
+ * or `assertReady()`, from `app.init()` — still before the application listens.
+ * With no adapter at all (`createApplicationContext`), `assertReady()` refuses
+ * from `onModuleInit`.
  */
 export declare function createPendingProtocolHost(application: AdapterHostView, framework: Framework): PendingProtocolHost;

package/dist/protocol-host.factory.js

@@ -11,12 +11,6 @@ const PLATFORM_MOUNTERS = {
     }, binding, entrypoint, maxRequestBytes),
     fastify: (adapter, binding, entrypoint, maxRequestBytes) => createFastifyProtocolHost(adapter.getInstance(), binding, entrypoint, maxRequestBytes),
 };
-/**
- * Binds `framework`'s protocol for the application's platform, refusing an
- * unsupported platform while providers are instantiated — so
- * `NestFactory.create` rejects before the application listens (Q18). The
- * routes are mounted later, from the module's `configure()` (Q5).
- */
 export function createProtocolHost(adapter, framework) {
     const platform = checkedPlatform(adapter?.getType());
     const binding = AvProtocol.bind(framework);
@@ -28,18 +22,7 @@ export function createProtocolHost(adapter, framework) {
         },
     };
 }
-/**
- * pilot.1 — the protocol's routes are platform routes, which Nest's
- * `RouterExplorer` never logs; this is the one line that says they exist.
- * Through Nest's `Logger`, so the application's logger settings govern it.
- */
 const MOUNT_LOGGER = new Logger("AventaraModule");
-/**
- * What one mount registered, read off `protocol.surface()`: the operation
- * count under the entrypoint, then each framework route by method and path —
- * e.g. `Aventara mounted 5 operations at /api (+ GET /api/_contract, POST
- * /api/_transactions)`.
- */
 export function mountedLine(routes, entrypoint) {
     const operations = routes.filter((route) => route.kind === "operation");
     const framework = routes
@@ -47,20 +30,6 @@ export function mountedLine(routes, entrypoint) {
         .map((route) => `${route.method} ${entrypoint}${route.path}`);
     return `Aventara mounted ${operations.length} ${operations.length === 1 ? "operation" : "operations"} at ${entrypoint === "" ? "/" : entrypoint} (+ ${framework.join(", ")})`;
 }
-/**
- * N1 (plan B23) — a host for an application whose HTTP adapter may arrive after
- * the providers are instantiated.
- *
- * `NestFactory.create` sets the adapter first: the host is created at once, and
- * an unsupported platform rejects then, as before (Q18). Nest's testing module
- * compiles first and receives its adapter from `createNestApplication()`, which
- * sets it on the `HttpAdapterHost` — `init$` fires — before `app.init()`
- * registers Nest's body parsers: the host is created at that moment, so a
- * platform's body reader is still installed ahead of them (Q8). A refusal there
- * is kept and raised by `mount()` or `assertReady()`, from `app.init()` — still
- * before the application listens. With no adapter at all
- * (`createApplicationContext`), `assertReady()` refuses from `onModuleInit`.
- */
 export function createPendingProtocolHost(application, framework) {
     if (application.httpAdapter !== undefined) {
         const host = createProtocolHost(application.httpAdapter, framework);
@@ -80,7 +49,6 @@ export function createPendingProtocolHost(application, framework) {
         if (refusal !== undefined) {
             throw refusal;
         }
-        // No adapter ever arrived: refused with the same sentence as at creation.
         return host ?? createProtocolHost(undefined, framework);
     };
     return {

package/dist/request-body.reader.d.ts

@@ -1,20 +1,18 @@
 import type { AvProtocolBinding, AvProtocolResponse } from "@aventara/core/protocol";
 /**
- * The raw arm's body reader (Q8, Q9): a request body read off a Node stream,
- * decoded per its `Content-Encoding`, and stored up to `maxRequestBytes + 1`
- * DECODED bytes — one more than the limit is all the decoder needs to answer
- * `A2010`, and counting decoded bytes is also the decompression-bomb bound
- * (§12.3, §20.1). Past the bound the stream is still read to its end and
- * discarded, so the connection stays usable (U1); nothing more is inflated.
+ * The raw arm's body reader: a request body read off a Node stream, decoded per
+ * its `Content-Encoding`, and stored up to `maxRequestBytes + 1` DECODED bytes —
+ * one more than the limit is all the decoder needs to answer `A2010`, and counting
+ * decoded bytes is also the decompression-bomb bound. Past the bound the stream is
+ * still read to its end and discarded, so the connection stays usable; nothing
+ * more is inflated.
  *
- * Platform-free: it reads an async iterable of bytes, as Node's
- * `IncomingMessage` is. `node:zlib` is loaded by a specifier the compiler does
- * not resolve, typed by the slice below (P4: no `@types/node`).
+ * Platform-free: it reads an async iterable of bytes, as Node's `IncomingMessage`
+ * is.
  */
 /**
- * What the reader hands on: the stored bytes; an unsupported coding (Q9,
- * answered `A2011`); or a body that does not decode in the coding it names —
- * a malformed request (director, 2026-10-05: answered `A2000`).
+ * What the reader hands on: the stored bytes; an unsupported coding; or a body
+ * that does not decode in the coding it names — a malformed request.
  */
 export type RequestBodyRead = {
     readonly kind: "read";
@@ -25,12 +23,11 @@ export type RequestBodyRead = {
     readonly kind: "undecodable";
 };
 /**
- * The answer to a body the reader could not hand on, through the bound
- * `failure` member — the one place the host names an A-code (Q9): an
- * unsupported coding is `415 A2011`; a body that does not decode in its
- * coding is malformed, `400 A2000` (director, 2026-10-05). The request id is
- * minted by core: it exposes no adoption of the client's id to a host
- * (register row, S8).
+ * The answer to a body the reader could not hand on, through the bound `failure`
+ * member — the one place the host names an A-code: an unsupported coding is `415
+ * A2011`; a body that does not decode in its coding is malformed, `400 A2000`. The
+ * request id is minted by core: it exposes no adoption of the client's id to a
+ * host.
  */
 export declare function unreadBodyAnswer(binding: AvProtocolBinding, read: Exclude<RequestBodyRead, {
     readonly kind: "read";

package/dist/request-body.reader.js

@@ -1,11 +1,3 @@
-/**
- * The answer to a body the reader could not hand on, through the bound
- * `failure` member — the one place the host names an A-code (Q9): an
- * unsupported coding is `415 A2011`; a body that does not decode in its
- * coding is malformed, `400 A2000` (director, 2026-10-05). The request id is
- * minted by core: it exposes no adoption of the client's id to a host
- * (register row, S8).
- */
 export function unreadBodyAnswer(binding, read) {
     return read.kind === "unsupported-coding"
         ? binding.failure("A2011")
@@ -22,19 +14,9 @@ const zlib = () => {
     zlibModule ??= import(specifier);
     return zlibModule;
 };
-/**
- * Reads `source` to its end. `contentEncoding` is the header's values as
- * received; absent, empty or `identity` is no coding; one of `gzip`,
- * `deflate`, `br` (any case) is inflated; anything else — a stacked coding
- * included — is unsupported. A body that does not decode in the coding it
- * names is undecodable. Either way the stream is still read to its end.
- */
 export async function readRequestBody(source, contentEncoding, cap) {
     const coding = codingOf(contentEncoding);
     if (coding === undefined) {
-        // Read to the end and discarded all the same: the stream finished is
-        // what keeps the platform's own parsers off it (Q8), and the
-        // connection usable.
         for await (const _ of source) {
         }
         return { kind: "unsupported-coding" };
@@ -55,11 +37,6 @@ export async function readRequestBody(source, contentEncoding, cap) {
             }
         }
     })();
-    // Settles when the inflater stops — at its end, at the bound (destroyed),
-    // or at a decoding error. Node calls no write callback once an inflater
-    // has failed, so each write also waits on this, never on the callback
-    // alone. Marking it handled here keeps an early decoding error from being
-    // reported as unhandled before it is awaited below.
     const stopped = inflated.then(() => undefined, () => undefined);
     for await (const chunk of source) {
         if (!inflater.destroyed) {
@@ -82,7 +59,6 @@ export async function readRequestBody(source, contentEncoding, cap) {
     }
     return { kind: "read", content: stored.content() };
 }
-/** The coding the header names, `identity` for none, `undefined` for an unsupported one. */
 function codingOf(contentEncoding) {
     const named = (contentEncoding ?? [])
         .join(",")
@@ -103,7 +79,6 @@ function codingOf(contentEncoding) {
         ? only
         : undefined;
 }
-/** Stores bytes up to `limit`; `add` answers whether there is room for more. */
 function boundedStore(limit) {
     const chunks = [];
     let size = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/nest",
-  "version": "0.1.0-pilot.1",
+  "version": "0.1.0-pilot.3",
   "license": "SEE LICENSE IN LICENSE",
   "description": "NestJS host integration for Aventara.",
   "type": "module",
@@ -21,7 +21,7 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.1"
+    "@aventara/core": "0.1.0-pilot.3"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",
@@ -31,8 +31,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/prisma7-adapter": "0.1.0-pilot.1",
-    "@aventara/testing": "0.1.0-pilot.1",
+    "@aventara/prisma7-adapter": "0.1.0-pilot.3",
+    "@aventara/testing": "0.1.0-pilot.3",
     "@nestjs/common": "^12.1.2",
     "@nestjs/core": "^12.1.2",
     "@nestjs/platform-express": "^12.1.2",
@@ -43,7 +43,7 @@
     "rxjs": "^7.8.2"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
     "lint": "biome lint src"