@aventara/nest 0.0.0-stage → 0.1.0-pilot.0

package/LICENSE

@@ -0,0 +1,91 @@
+Required Notice: Copyright 2026 Mohamed Ragheb
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/LICENSE-ADDITIONAL-PERMISSION.md

@@ -0,0 +1,9 @@
+# Additional Permission — Aventara
+
+Copyright 2026 Mohamed Ragheb
+
+In addition to the permissions of the PolyForm Shield License 1.0.0 in `LICENSE`, the licensor grants the following additional permission:
+
+The Noncompete section applies only to providing a product that competes with the software itself — the Aventara framework, its packages and its tooling. Providing a product that competes with any other product the licensor or its affiliates provide using the software is a permitted purpose.
+
+This additional permission only adds to your permissions; it does not restrict or replace any term of `LICENSE`.

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# `@aventara/nest`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hosts an Aventara `Framework` in a NestJS application. It does one thing: it mounts the framework's HTTP protocol —
+`AvProtocol.bind(framework)` from `@aventara/core/protocol` — on Nest's HTTP platform, and puts the `Framework` into
+Nest's dependency injection. Every rule of the protocol (routes, decoding, statuses, envelopes, headers, absence) is
+core's; this package only translates a Nest request into the protocol's request and writes the protocol's answer back.
+
+- **Nest 12** (`@nestjs/common` and `@nestjs/core` `^12.0.0`), on **Express** (Nest's default) or **Fastify**.
+- `@aventara/core` is its one dependency.
+
+## Mounting it
+
+`AventaraModule` is a global module, imported once in your root module. It takes the `Framework` in one of four forms.
+
+```ts
+// src/app.module.ts — the shape `aventara init` writes (`@aventara/cli`)
+import { Module } from "@nestjs/common";
+import { AventaraModule } from "@aventara/nest";
+import { aventaraConfig } from "./aventara.config.js";
+import { PrismaModule, PrismaService } from "./prisma.service.js";
+
+@Module({
+	imports: [
+		PrismaModule,
+		AventaraModule.forRootAsync({
+			imports: [PrismaModule],
+			inject: [PrismaService],
+			useFactory: async (prisma: PrismaService) => ({
+				config: await aventaraConfig(prisma),
+			}),
+		}),
+	],
+})
+export class AppModule {}
+
+// src/aventara.config.ts — the framework's configuration: entrypoint, restrictions, pipelines
+import { createPrismaAdapter } from "@aventara/prisma7-adapter";
+import { discovery } from "./generated/aventara/discovery.artifact.js";
+import type { PrismaService } from "./prisma.service.js";
+
+export async function aventaraConfig(prisma: PrismaService) {
+	return {
+		entrypoint: "/api",
+		adapter: await createPrismaAdapter({
+			client: prisma,
+			discovery,
+			provider: "postgresql",
+			driver: "@prisma/adapter-pg",
+		}),
+	} as const;
+}
+```
+
+| Form | When |
+|---|---|
+| `AventaraModule.forRoot({ framework })` | You called `createFramework(config)` yourself and want your own typed `Framework<M, Cfg>` in code. |
+| `AventaraModule.forRoot({ config })` | The module calls `createFramework(config)` for you. |
+| `AventaraModule.forRootAsync({ imports, inject, useFactory })` resolving `{ framework }` or `{ config }` | What builds the Framework (a Prisma client, a configuration service) is itself a provider. |
+
+The `config` form is typed exactly like `createFramework`'s parameter: an annotated `FrameworkConfig<M>`, an inline
+literal, an inferred constant and a `satisfies` check are all accepted, and checked against your Adapter's model.
+
+**Injecting it.** `@InjectFramework()` (or `@Inject(AVENTARA_FRAMEWORK)`) injects the `Framework`. DI carries no type
+argument, so type the parameter with your own alias:
+
+```ts
+export type AppFramework = Awaited<ReturnType<typeof buildFramework>>;
+
+@Injectable()
+export class ReportsService {
+	constructor(@InjectFramework() private readonly framework: AppFramework) {}
+}
+```
+
+**Fails before listen.** These reject while Nest builds the application, before it listens: both or neither of
+`framework` and `config`; a `framework` value that is not a Framework; the module mounted twice in one application; a
+platform other than Express or Fastify (or none, as in `createApplicationContext`); a `FrameworkConstructionError`,
+yours or the module's own, which propagates unchanged. Nest's default `abortOnError: true` **exits the process** on a
+bootstrap error instead of rejecting; pass `abortOnError: false` to `NestFactory.create` to catch it.
+
+**Nest's testing module works.** `Test.createTestingModule({ imports: [AppModule] }).compile()` builds the providers
+before any HTTP platform exists; the module waits for the one `createNestApplication()` supplies, and still refuses an
+unsupported platform before the application listens (ADR 0011's amendment). A testing module initialized with no
+application at all is refused at `init()`, as a platform of `none`.
+
+**Nothing to shut down.** The module owns no resource. Your Prisma provider closes its own client — in its
+`onModuleDestroy`, with `app.enableShutdownHooks()` for signals.
+
+## What runs on a protocol route
+
+The protocol's routes are platform routes, registered from the module's `configure()`, one per
+`protocol.surface()` entry — every advertised operation, `GET <entrypoint>/_contract`, and `POST
+<entrypoint>/_transactions` only when the ClientContract advertises `interactive` — plus the absence handler for the
+rest of `<entrypoint>/_*`. The framework's validation is outermost:
+
+| | Express | Fastify |
+|---|---|---|
+| Your `app.use(...)` middleware, `app.enableCors()`, helmet | runs | runs |
+| Nest guards, interceptors, pipes (global or not) | **never** | **never** |
+| `MiddlewareConsumer` middleware | **never** | **runs** — Fastify runs Nest middleware before routing; add `.exclude("api/_*path")` (your entrypoint) to keep it off |
+| Your controller at `<entrypoint>/_contract` (or any `_` path) | never reached | the application does not start |
+| Your controller at `<entrypoint>/health` (outside `_`) | reached | reached |
+
+Authentication and authorization therefore belong in Aventara **pipelines** (guards), which read
+`transport.headers` — lower-cased names, repeats joined. A Passport strategy run as Nest middleware sets `req.user`,
+which a pipeline cannot see: verify the bearer token or cookie in the Aventara guard instead.
+
+**Where it is mounted.** `FrameworkConfig.entrypoint` alone decides it. `app.setGlobalPrefix(...)` does not move the
+protocol; set the entrypoint to where you want it, and point the generated client at the same URL.
+
+## Requests
+
+- **Bodies** on protocol routes are read raw — never through Nest's body parser — up to `limits.maxRequestBytes`; the
+  protocol's decoder answers an oversized body (`413 A2010`), another content type (`415 A2011`) and malformed JSON
+  (`400 A2000`). Your own routes keep Nest's parsed `req.body`. No `NestFactory.create` option is needed.
+- **`Content-Encoding`:** `gzip`, `deflate` and `br` are inflated, and the limit counts decoded bytes. Any other coding
+  answers `415 A2011`; a body that does not decode in the coding it names answers `400 A2000`. These two answers carry a
+  newly minted `Aventara-Request-Id`, not the client's.
+- **The request id** is the client's `Aventara-Request-Id` as it arrived, or one core mints. A middleware that rewrites
+  `req.headers` cannot change it, and `X-Request-Id` is never copied into it — set `Aventara-Request-Id` at your proxy.
+- **A query string** is not part of the protocol path; it is ignored.
+
+## Platform differences
+
+- **Fastify cannot mount some Resource keys or entrypoints as literal routes.** A Resource key that needs `*` or a
+  reserved character (`: + # $ & , / ; = ? @`) in its route path, or an entrypoint containing `*`, is refused at startup
+  with a message naming it. Rename it, or host on Express, which mounts every key.
+- **Express routing is case-insensitive** by default, so it also answers the protocol under, say, `/API/_contract`;
+  Fastify's is not. That is Express's own `case sensitive routing` setting, off by default, and yours to change.
+- **Express answers `500 A3000`** to a protocol route requested with a percent-encoding a generated client never sends
+  (for example `%6Eotes` for `notes`); Fastify and the in-process protocol execute it. A known divergence (register
+  F-843).
+- On Express the response carries Express's `X-Powered-By` header; `app.disable("x-powered-by")` removes it.
+
+## License
+
+PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
+use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.

package/dist/aventara.module.d.ts

@@ -0,0 +1,49 @@
+import { type AdapterModel, type AnyFrameworkConfig, type Framework, type FrameworkConfig } from "@aventara/core";
+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.
+ *
+ * The `config` arm is typed exactly as `createFramework`'s parameter
+ * (`Cfg & FrameworkConfig<M, Cfg>`; U12, architect 2026-10-05), 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.
+ */
+export type AventaraModuleOptions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
+    readonly framework: Framework;
+    readonly config?: never;
+} | {
+    readonly config: Cfg & FrameworkConfig<M, Cfg>;
+    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).
+ */
+export type AventaraModuleAsyncOptions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
+    readonly imports?: ModuleMetadata["imports"];
+    readonly inject?: FactoryProvider["inject"];
+    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.
+ */
+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). */
+    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;
+    private static mount;
+}

package/dist/aventara.module.js

@@ -0,0 +1,77 @@
+import { createFramework, } from "@aventara/core";
+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 { 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);
+}
+/**
+ * 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) {
+        this.host = host;
+    }
+    configure() {
+        this.host.mount();
+    }
+    /** An application context never receives a platform: refused here, at its init (N1). */
+    onModuleInit() {
+        this.host.assertReady();
+    }
+    static forRoot(options) {
+        return AventaraModule.mount([], [], () => options);
+    }
+    static forRootAsync(options) {
+        return AventaraModule.mount(options.imports ?? [], options.inject ?? [], options.useFactory);
+    }
+    static mount(imports, inject, resolve) {
+        mounts += 1;
+        return {
+            module: AventaraModule,
+            global: true,
+            imports,
+            providers: [
+                { provide: MOUNT, useValue: mounts },
+                {
+                    provide: AVENTARA_FRAMEWORK,
+                    inject: [HttpAdapterHost, ...inject],
+                    useFactory: async (application, ...deps) => {
+                        recordMount(application);
+                        return frameworkOf(await resolve(...deps));
+                    },
+                },
+                {
+                    provide: PROTOCOL_HOST,
+                    inject: [HttpAdapterHost, AVENTARA_FRAMEWORK],
+                    useFactory: (application, framework) => createPendingProtocolHost(application, framework),
+                },
+            ],
+            exports: [AVENTARA_FRAMEWORK],
+        };
+    }
+}
+Inject(PROTOCOL_HOST)(AventaraModule, undefined, 0);
+Module({})(AventaraModule);

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

@@ -0,0 +1,42 @@
+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 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.
+ *
+ * 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`).
+ */
+/** 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`). */
+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;
+    use(handler: ExpressHandler): unknown;
+};
+/**
+ * Installs the pre-parser on `platform` now, and returns the host whose
+ * `mount` registers the routes and the absence fallback under `entrypoint`.
+ */
+export declare function createExpressProtocolHost(platform: ExpressPlatform, binding: AvProtocolBinding, entrypoint: string, maxRequestBytes: number): ProtocolHost;
+export {};

package/dist/express-protocol.mounter.js

@@ -0,0 +1,65 @@
+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;
+    platform.use(async (request, _response, next) => {
+        if (pathnameOf(request.originalUrl).startsWith(`${entrypoint}/_`)) {
+            bodies.set(request, await readRequestBody(request, request.headersDistinct["content-encoding"], maxRequestBytes));
+        }
+        handOn(next);
+    });
+    return {
+        mount: () => {
+            for (const route of binding.surface()) {
+                const answer = PROTOCOL_ROUTES[route.kind](binding);
+                platform[REGISTER[route.method]](literalPath(`${entrypoint}${route.path}`), async (request, response) => {
+                    const body = bodyOf(request);
+                    writeAnswer(response, body.kind === "read"
+                        ? await answer(translated(request, entrypoint, body.content))
+                        : unreadBodyAnswer(binding, body));
+                });
+            }
+            platform.use((request, response, next) => {
+                if (!pathnameOf(request.originalUrl).startsWith(`${entrypoint}/`)) {
+                    handOn(next);
+                    return;
+                }
+                const body = bodyOf(request);
+                const absent = binding.answerAbsent(translated(request, entrypoint, body.kind === "read" ? body.content : NO_BYTES));
+                if (absent === undefined) {
+                    handOn(next);
+                    return;
+                }
+                writeAnswer(response, absent);
+            });
+        },
+    };
+}
+/** 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

@@ -0,0 +1,68 @@
+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:
+ *
+ * - **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).
+ * - **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).
+ */
+/** Fastify's request: Node's own under `raw`, and whether a route matched. */
+type FastifyRequest = {
+    readonly raw: NodeIncoming & {
+        readonly method: string;
+        readonly url: string;
+    };
+    readonly is404: boolean;
+};
+/** Fastify's reply: hijacked, then written through Node's response under `raw`. */
+type FastifyReply = {
+    hijack(): unknown;
+    getHeaders(): PlatformHeaders;
+    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;
+        readonly url: string;
+        readonly exposeHeadRoute: false;
+        readonly onRequest: OnRequestHook;
+        readonly handler: () => never;
+    }): unknown;
+    addHook(name: "onRequest", hook: OnRequestHook): unknown;
+};
+/**
+ * The host whose `mount` registers the routes and the absence hook under
+ * `entrypoint` — after refusing, now, a surface it cannot mount literally.
+ */
+export declare function createFastifyProtocolHost(platform: FastifyPlatform, binding: AvProtocolBinding, entrypoint: string, maxRequestBytes: number): ProtocolHost;
+export {};

package/dist/fastify-protocol.mounter.js

@@ -0,0 +1,83 @@
+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.`);
+    }
+    const refused = binding
+        .surface()
+        .flatMap((route) => route.kind === "operation" && UNMATCHABLE.test(route.path)
+        ? [route.resource]
+        : [])
+        .filter((key, index, keys) => keys.indexOf(key) === index);
+    if (refused.length > 0) {
+        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);
+    return {
+        mount: () => {
+            for (const route of binding.surface()) {
+                const answer = PROTOCOL_ROUTES[route.kind](binding);
+                platform.route({
+                    method: route.method,
+                    url: literalPath(`${entrypoint}${route.path}`),
+                    exposeHeadRoute: false,
+                    onRequest: async (request, reply) => {
+                        const body = await readRequestBody(request.raw, request.raw.headersDistinct["content-encoding"], maxRequestBytes);
+                        write(reply, body.kind === "read"
+                            ? await answer(translated(request, body.content))
+                            : unreadBodyAnswer(binding, body));
+                        return reply;
+                    },
+                    handler: () => {
+                        throw new Error("AventaraModule: a protocol route's onRequest hook answers every request; its handler is unreachable.");
+                    },
+                });
+            }
+            platform.addHook("onRequest", async (request, reply) => {
+                if (!request.is404 ||
+                    !pathnameOf(request.raw.url).startsWith(`${entrypoint}/`)) {
+                    return undefined;
+                }
+                const absent = binding.answerAbsent(translated(request, NO_BYTES));
+                if (absent === undefined) {
+                    return undefined;
+                }
+                write(reply, absent);
+                return reply;
+            });
+        },
+    };
+}
+/**
+ * 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

@@ -0,0 +1,10 @@
+/**
+ * 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 declare const AVENTARA_FRAMEWORK: unique symbol;
+/** `@InjectFramework()` — `@Inject(AVENTARA_FRAMEWORK)` in one call (Q2). */
+export declare function InjectFramework(): ParameterDecorator;

package/dist/framework.token.js

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,9 @@
+import type { AventaraModuleOptions } from "./aventara.module.js";
+/** The options as given — `forRootAsync`'s factory may resolve anything at runtime. */
+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). */
+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

@@ -0,0 +1,60 @@
+/**
+ * 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
+        : {};
+    const hasFramework = record.framework !== undefined;
+    const hasConfig = record.config !== undefined;
+    if (hasFramework && hasConfig) {
+        throw new Error(BOTH_ARMS);
+    }
+    if (!hasFramework && !hasConfig) {
+        throw new Error(NEITHER_ARM);
+    }
+    if (hasFramework && !isFramework(record.framework)) {
+        throw new Error(NOT_A_FRAMEWORK);
+    }
+    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;
+    }
+    const candidate = value;
+    return (typeof candidate.entrypoint === "string" &&
+        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);
+    }
+    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) {
+        throw new Error(`AventaraModule mounts the protocol on Nest's Express or Fastify platform; this application's platform is \`${type ?? "none"}\`.`);
+    }
+    return platform;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { AventaraModuleAsyncOptions, AventaraModuleOptions, } from "./aventara.module.js";
+export { AventaraModule } from "./aventara.module.js";
+export { AVENTARA_FRAMEWORK, InjectFramework } from "./framework.token.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { AventaraModule } from "./aventara.module.js";
+export { AVENTARA_FRAMEWORK, InjectFramework } from "./framework.token.js";

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

@@ -0,0 +1,30 @@
+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;
+};
+/** Headers a platform's own hooks set on the reply before the protocol answered. */
+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). */
+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). */
+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.
+ */
+export declare function writeAnswer(response: NodeOutgoing, answer: AvProtocolResponse, beneath?: PlatformHeaders): void;

package/dist/node-exchange.translator.js

@@ -0,0 +1,33 @@
+/** 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,
+        path: pathnameOf(url).slice(entrypoint.length),
+        headers: incoming.headersDistinct,
+        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 = {};
+    for (const [name, value] of Object.entries(beneath)) {
+        if (value !== undefined && !own.has(name.toLowerCase())) {
+            headers[name] = value;
+        }
+    }
+    response.writeHead(answer.status, { ...headers, ...answer.headers });
+    response.end(answer.body);
+}

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

@@ -0,0 +1,40 @@
+import type { Framework } from "@aventara/core";
+import type { AbstractHttpAdapter } from "@nestjs/core";
+/** The protocol, bound once at startup, and the one call that mounts it. */
+export type ProtocolHost = {
+    readonly mount: () => void;
+};
+/**
+ * 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 declare function createProtocolHost(adapter: AbstractHttpAdapter | undefined, framework: Framework): ProtocolHost;
+/** What `AventaraModule` holds: a host, perhaps waiting for its platform, and the check that it has one. */
+export type PendingProtocolHost = ProtocolHost & {
+    /** Throws when no platform arrived, or the one that did is refused. */
+    readonly assertReady: () => void;
+};
+/** The parts of Nest's `HttpAdapterHost` the module reads. */
+export type AdapterHostView = {
+    readonly httpAdapter: AbstractHttpAdapter | undefined;
+    readonly init$: {
+        subscribe(next: () => void): unknown;
+    };
+};
+/**
+ * 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 declare function createPendingProtocolHost(application: AdapterHostView, framework: Framework): PendingProtocolHost;

package/dist/protocol-host.factory.js

@@ -0,0 +1,65 @@
+import { AvProtocol } from "@aventara/core/protocol";
+import { createExpressProtocolHost } from "./express-protocol.mounter.js";
+import { createFastifyProtocolHost, } from "./fastify-protocol.mounter.js";
+import { checkedPlatform, } from "./host-bootstrap.validator.js";
+const PLATFORM_MOUNTERS = {
+    express: (adapter, binding, entrypoint, maxRequestBytes) => createExpressProtocolHost({
+        get: (path, handler) => adapter.get(path, handler),
+        post: (path, handler) => adapter.post(path, handler),
+        use: (handler) => adapter.use(handler),
+    }, 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());
+    return PLATFORM_MOUNTERS[platform](adapter, AvProtocol.bind(framework), framework.entrypoint, framework.contracts.client.limits.maxRequestBytes);
+}
+/**
+ * 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);
+        return { mount: host.mount, assertReady: () => undefined };
+    }
+    let host;
+    let refusal;
+    application.init$.subscribe(() => {
+        try {
+            host = createProtocolHost(application.httpAdapter, framework);
+        }
+        catch (error) {
+            refusal = error;
+        }
+    });
+    const ready = () => {
+        if (refusal !== undefined) {
+            throw refusal;
+        }
+        // No adapter ever arrived: refused with the same sentence as at creation.
+        return host ?? createProtocolHost(undefined, framework);
+    };
+    return {
+        mount: () => ready().mount(),
+        assertReady: () => {
+            ready();
+        },
+    };
+}

package/dist/protocol-route.table.d.ts

@@ -0,0 +1,18 @@
+import type { AvProtocolBinding, AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
+/**
+ * One route `protocol.surface()` lists. Core keeps `SurfaceRoute` a module
+ * type, so the host derives it from the binding — no new core export.
+ */
+export type SurfaceRoute = ReturnType<AvProtocolBinding["surface"]>[number];
+/** What a mounted route answers its request with: a bound protocol member. */
+export type RouteAnswer = (request: AvProtocolRequest) => AvProtocolResponse | Promise<AvProtocolResponse>;
+/**
+ * The bound member each kind of surface route is answered by — total over
+ * `SurfaceRoute["kind"]`, so a route kind core adds fails to compile here
+ * rather than mounting a route nothing answers. Every platform's mounter
+ * reads this one table; none decides an answer of its own.
+ */
+export type ProtocolRouteTable = {
+    readonly [K in SurfaceRoute["kind"]]: (binding: AvProtocolBinding) => RouteAnswer;
+};
+export declare const PROTOCOL_ROUTES: ProtocolRouteTable;

package/dist/protocol-route.table.js

@@ -0,0 +1,5 @@
+export const PROTOCOL_ROUTES = {
+    operation: (binding) => (request) => binding.handleOperation(request),
+    contract: (binding) => (request) => binding.encodeContract(request),
+    transactions: (binding) => (request) => binding.handleTransaction(request),
+};

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

@@ -0,0 +1,45 @@
+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.
+ *
+ * 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`).
+ */
+/**
+ * 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`).
+ */
+export type RequestBodyRead = {
+    readonly kind: "read";
+    readonly content: Uint8Array;
+} | {
+    readonly kind: "unsupported-coding";
+} | {
+    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).
+ */
+export declare function unreadBodyAnswer(binding: AvProtocolBinding, read: Exclude<RequestBodyRead, {
+    readonly kind: "read";
+}>): AvProtocolResponse;
+/**
+ * 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 declare function readRequestBody(source: AsyncIterable<Uint8Array>, contentEncoding: readonly string[] | undefined, cap: number): Promise<RequestBodyRead>;

package/dist/request-body.reader.js

@@ -0,0 +1,130 @@
+/**
+ * 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")
+        : binding.failure("A2000");
+}
+const INFLATERS = {
+    gzip: (zlib) => zlib.createGunzip(),
+    deflate: (zlib) => zlib.createInflate(),
+    br: (zlib) => zlib.createBrotliDecompress(),
+};
+let zlibModule;
+const zlib = () => {
+    const specifier = "node: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" };
+    }
+    const stored = boundedStore(cap + 1);
+    if (coding === "identity") {
+        for await (const chunk of source) {
+            stored.add(chunk);
+        }
+        return { kind: "read", content: stored.content() };
+    }
+    const inflater = INFLATERS[coding](await zlib());
+    const inflated = (async () => {
+        for await (const chunk of inflater) {
+            if (!stored.add(chunk)) {
+                inflater.destroy();
+                return;
+            }
+        }
+    })();
+    // 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) {
+            await Promise.race([
+                new Promise((written) => {
+                    inflater.write(chunk, () => written());
+                }),
+                stopped,
+            ]);
+        }
+    }
+    if (!inflater.destroyed) {
+        inflater.end();
+    }
+    try {
+        await inflated;
+    }
+    catch {
+        return { kind: "undecodable" };
+    }
+    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(",")
+        .split(",")
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token !== "");
+    if (named.length === 0) {
+        return "identity";
+    }
+    if (named.length > 1) {
+        return undefined;
+    }
+    const [only] = named;
+    return only === "identity" ||
+        only === "gzip" ||
+        only === "deflate" ||
+        only === "br"
+        ? only
+        : undefined;
+}
+/** Stores bytes up to `limit`; `add` answers whether there is room for more. */
+function boundedStore(limit) {
+    const chunks = [];
+    let size = 0;
+    return {
+        add(chunk) {
+            const room = limit - size;
+            if (room > 0) {
+                const kept = chunk.byteLength <= room ? chunk : chunk.subarray(0, room);
+                chunks.push(kept);
+                size += kept.byteLength;
+            }
+            return size < limit;
+        },
+        content() {
+            const bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            return bytes;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@aventara/nest",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-pilot.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "NestJS host integration for Aventara.",
+  "type": "module",
+  "engines": {
+    "node": "^22.18.0 || >=24.2.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE-ADDITIONAL-PERMISSION.md"
+  ],
+  "dependencies": {
+    "@aventara/core": "0.1.0-pilot.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^12.0.0",
+    "@nestjs/core": "^12.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@aventara/prisma7-adapter": "0.1.0-pilot.0",
+    "@aventara/testing": "0.1.0-pilot.0",
+    "@nestjs/common": "^12.1.2",
+    "@nestjs/core": "^12.1.2",
+    "@nestjs/platform-express": "^12.1.2",
+    "@nestjs/platform-fastify": "^12.1.2",
+    "@nestjs/testing": "^12.1.2",
+    "@prisma/adapter-better-sqlite3": "7.10.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
+    "lint": "biome lint src"
+  }
 }