@aventara/nest 0.1.0-pilot.4 → 1.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,314 @@
+# @aventara/nest
+
+## 1.0.0-rc.1
+
+### Patch Changes
+
+- 7e3d06f: Breaking: the configuration has a new shape. Every layer (the root, `application` and `client`) now holds the
+  same six keys: `exposed`, `transactionsStyle`, `limits`, `pipelines`, `resources` and `exemptions`. Everything about
+  one Resource lives under `resources.<Resource>`: its fields, and each field's `definition` and `pipelines`. The old
+  keys are refused when the framework starts, with a message that names where each one moved:
+
+  | Before (rc.0)                                           | Now (rc.1)                                                                          |
+  | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+  | `fields: { Post: { url: { type, nullable, … } } }`      | `resources: { Post: { fields: { url: { definition: { type, nullable, … } } } } }`   |
+  | `behaviors: { Post: { fields: { slug: { create } } } }` | `resources: { Post: { fields: { slug: { pipelines: { compute: { create } } } } } }` |
+  | `transactions: "none"`                                  | `transactionsStyle: "none"`                                                         |
+  | `restrictions`                                          | `exposed` + `exemptions` (see below)                                                |
+  | `@aventara/core/json`                                   | `@aventara/core/avz`                                                                |
+
+  Before:
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    transactions: "interactive",
+    fields: {
+      Post: {
+        url: {
+          type: { scalar: "string" },
+          nullable: false,
+          list: false,
+          lifecycle: ["VIRTUAL"],
+        },
+      },
+    },
+    behaviors: {
+      Post: {
+        fields: {
+          url: {
+            read: {
+              dependsOn: ["slug"],
+              compute: ({ record }) => `/p/${record.slug}`,
+            },
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  After:
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    transactionsStyle: "interactive",
+    resources: {
+      Post: {
+        fields: {
+          url: {
+            definition: {
+              type: { scalar: "string" },
+              nullable: false,
+              list: false,
+              lifecycle: ["VIRTUAL"],
+              format: "url",
+            },
+            pipelines: {
+              compute: {
+                read: {
+                  dependsOn: ["slug"],
+                  compute: ({ record }) => `/p/${record.slug}`,
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  What else changed:
+
+  - A field is defined at the root only. A `definition` in `application` or `client` is refused
+    (`CONFIG_FORBIDDEN_IN_OVERLAY`). Define the field
+    at the root; `application` and `client` can still add compute stages to it.
+  - Computed values chain. When the root and an overlay both compute a field, the root's stage runs first and the
+    overlay's receives its result as `value`. A stage can no longer be turned off with `false`. Returning `undefined`
+    keeps the current value. An upsert computes its create branch with `compute.create` and its update branch with
+    `compute.update`.
+  - A discovered field keeps the adapter's facts. On a field the adapter discovered you may restate its own `type`,
+    `nullable` and `list`, and give a Json field its shape (`definition.json`). Setting a different type, any `format`
+    or any `capabilities` on it is refused. `format` is for fields you add, and it must be one of zod's named string
+    formats (`"email"`, `"url"`, `"uuid"`, …); any other name is a type error and refused at startup.
+  - A misplaced key is a type error. In a configuration written inline in `createFramework({ ... })` or
+    `AventaraModule.forRoot`, a key that has no place there (a typo, an old key, `compute` on a relation field, a field
+    name neither your schema nor the root has) is now a type error at that key, and still refused at startup.
+  - A Resource whose name starts with `$` is refused at startup (`$` names are the framework's).
+  - The Json shape builder moved from `@aventara/core/json` to `@aventara/core/avz`. Change the import; `AvZ` is
+    the same.
+
+  `exposed` and `exemptions`, which replace `restrictions`, have their own entry.
+
+- 4907afc: New: `AventaraModule.forRoot` and `forRootAsync` take a `state` option that seeds each protocol request's
+  `ctx.$state` (see `@aventara/core`'s changelog). It is called once per request with the platform's own request, so
+  what your middleware set there reaches every guard, pipe, hook and interceptor of the request:
+
+  ```ts
+  AventaraModule.forRoot({
+    config,
+    state: (req: Request) => ({ user: req.user }), // Passport's req.user, on Express
+  });
+  ```
+
+  On Express the request is Express's `req`. On Fastify it is Fastify's `request`; middleware added with `app.use`
+  writes to its Node request, `request.raw`, so read `request.raw.user` there. Fastify answers a protocol route in its
+  `onRequest` hook, so only what runs before that (`app.use` middleware, an earlier `onRequest` hook) can be read. A
+  `state` function that throws an `AvError` answers that error (`AvError("A4001", …)` is a `403`); any other throw is
+  `500 A3000`. A request the protocol refuses before running (a stale client, an unknown route) never calls it. A
+  `state` that is not a function is refused while Nest builds the application.
+
+- Breaking: the configuration's mount path is `api` (it was `entrypoint`), and the module reads `framework.api`.
+  `forRoot({ config: { api: "/api", adapter } })`. The Fastify refusal of a path with `*` now says "Change `api`, or
+  host on Express."
+
+- New: with `mcp` in the configuration, the module mounts the MCP endpoint of `@aventara/mcp` at that path (and, with
+  `mcp.authorization`, its OAuth metadata at `/.well-known/oauth-protected-resource` plus the path), on Express and on
+  Fastify, as it mounts the protocol's routes: the body read raw, the request's URL and peer address handed over, the
+  answer written as it is. The `state` option seeds each tool call's `ctx.$state`. `@aventara/mcp` is an optional peer
+  dependency, loaded only when `mcp` is configured; with `mcp` set and the package missing, the application refuses to
+  start and names it.
+
+- Fixed on Express: a request whose path matched a mounted route only because Express ignores case reached the route
+  without its body, and was answered as if it had sent none. Express matches routes case-insensitively by default,
+  while the body reader compared the path exactly. The MCP routes now answer their own path only, exactly as written,
+  so `/MCP` or `/mcp/` goes on to Nest's `404`, as on Fastify. The protocol's routes keep Express's matching (it also
+  answers the protocol under `/API` for `api: "/api"`), and the body reader now matches the `api` path the same way, so
+  `POST /API/_resources/…` gets its body.
+
+- The host's log line for an internal failure names the MCP endpoint when the endpoint itself failed
+  (`A3000 on the MCP endpoint (agent origin, request …)`).
+
+- Updated dependencies [800123b]
+- Updated dependencies [8bb1d6a]
+- Updated dependencies [68d4395]
+- Updated dependencies [7e3d06f]
+- Updated dependencies [1b5d3c0]
+- Updated dependencies [6317811]
+- Updated dependencies [6d0e5d6]
+- Updated dependencies [7a0cab9]
+- Updated dependencies [eb2a718]
+- Updated dependencies [03312c5]
+- Updated dependencies [123f6dc]
+- Updated dependencies [b65df2e]
+- Updated dependencies [c6e5010]
+- Updated dependencies [c1f9389]
+- Updated dependencies [9c52482]
+- Updated dependencies [8396148]
+- Updated dependencies [e8fbb02]
+- Updated dependencies [916e5f6]
+- Updated dependencies [6cbd158]
+  - @aventara/core@1.0.0-rc.1
+
+## 1.0.0-rc.0
+
+### Major Changes
+
+- First release candidate of Aventara 1.0. The public API is now considered stable; changes before 1.0.0 are possible
+  based on feedback.
+
+### Patch Changes
+
+- 24ffbab: Each package ships its `CHANGELOG.md`, so the release notes are in the installed package beside the README.
+- 24ffbab: **Behaviour changes:** Pipelines and guards read where a request came from as `request.origin` (was `request.scope`).
+  The same property is renamed everywhere it means `"application"` or `"client"`: the pipeline context
+  (`context.origin`), the request objects `framework.execute` and `framework.executeTransaction` take
+  (`{ origin: "client", … }`), the context a computed field's behaviour receives, and every diagnostic the diagnostics
+  sink receives. There is no `scope` alias: replace `scope` with `origin` in those places. Nothing sent over HTTP
+  changes.
+
+  The Nest host's log line for an internal failure now reads `(client origin, request …)` instead of
+  `(client scope, request …)`.
+
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [a973e89]
+- Updated dependencies [1e65e9a]
+- Updated dependencies
+- Updated dependencies [a973e89]
+- Updated dependencies [a973e89]
+- Updated dependencies [1e65e9a]
+- Updated dependencies [1e65e9a]
+- Updated dependencies [24ffbab]
+- Updated dependencies [2d00ad7]
+- Updated dependencies [384a50c]
+- Updated dependencies [d43d1cc]
+- Updated dependencies [3f98749]
+- Updated dependencies [032f792]
+- Updated dependencies [dbe6961]
+  - @aventara/core@1.0.0-rc.0
+
+## 0.1.0-pilot.4
+
+### Patch Changes
+
+- f37dcd6: The documentation shipped with the package — the comments an editor shows on hover, and the README — now describes
+  what each export does, how to use it, what it returns and what it throws. Notes about how the package was built and
+  why are no longer part of what is published.
+- Updated dependencies [f37dcd6]
+  - @aventara/core@0.1.0-pilot.4
+
+## 0.1.0-pilot.3
+
+### Patch Changes
+
+- @aventara/core@0.1.0-pilot.3
+
+## 0.1.0-pilot.2
+
+### Patch Changes
+
+- 5535994: Internal failures are visible in the host's log: when `AventaraModule` builds the framework from `config`, every
+  `A3000`–`A3003` writes one error line through Nest's `Logger` (context `Aventara`) with the code, the operation, the
+  scope, the request id and the thrown value's class name — never the error's message. A configured `diagnostics` sink
+  still receives the raw error.
+- e69e88d: The published packages are written for the people who use them. The JavaScript ships without comments; the type
+  declarations keep their documentation, and it, the error messages, the protocol fixtures' labels and the comments in a
+  generated client no longer carry the project's internal development notes.
+- ab58424: A pipe's output is checked against the server's own rules before it reaches the adapter. The request is validated
+  against the caller's Contract; after each pipe, the arguments are validated against the Core Contract (plus fields the
+  caller's scope adds), so a pipe may still write what the caller cannot — a field the client Contract hides, such as a
+  password hash — but not what the server cannot store. A refusal is the new internal code `A3004 PIPE_OUTPUT_INVALID` (HTTP
+  500). The caller receives only the generic `A server pipeline produced invalid arguments.`, like every internal
+  failure; the pipe (`pipes[i]` and its function name), the operation, the offending field and its V-code go to the
+  diagnostics sink as a `PipeOutputError`, and `@aventara/nest` writes them into its error log line. Nothing reaches the
+  adapter. This holds for operations and transaction steps alike (a plan answers with `cause.operation`). Generated
+  clients map `A3004` to `InternalError`; the protocol fixtures in `@aventara/testing` include an `A3004` row.
+- Updated dependencies [c2a3b7c]
+- Updated dependencies [e69e88d]
+- Updated dependencies [ab58424]
+- Updated dependencies [23937f8]
+  - @aventara/core@0.1.0-pilot.2
+
+## 0.1.0-pilot.1
+
+### Patch Changes
+
+- 1c45eb7: Startup says what Aventara mounted. Its routes are platform routes, which Nest's `RouterExplorer` never lists, so a
+  started server showed no sign of them. On mount, the module now logs one line through Nest's `Logger` (context
+  `AventaraModule`), read off `protocol.surface()`: `Aventara mounted 10 operations at /api (+ GET /api/_contract, POST
+/api/_transactions)`. The application's logger settings govern it.
+- 799346e: The package READMEs (each package's npm page) are rewritten for the people who use the packages. The Prisma 7
+  adapter's README now states the actual behaviour of a to-many relation or `$count` projected on
+  `update.many`/`create.many`: a validation refusal, `A2004` with `V1008`, before any statement runs (it said `A3001`).
+  Every install or run command names the `@pilot` dist-tag.
+- e58aebf: The READMEs show how to call the API by hand: a copy-pasteable `curl` that fetches `/api/_contract` and sends a
+  `find.many` with both identity headers, and runs as printed against a scaffolded server. They also say that
+  Resource keys are the model names as written (`/_resources/User/…`, `avClient.User.find.many`), and that list results are
+  `readonly` arrays (`readonly User[]`).
+- Updated dependencies [a45f8a8]
+- Updated dependencies [799346e]
+  - @aventara/core@0.1.0-pilot.1
+
+## 0.1.0-pilot.0
+
+### Minor Changes
+
+- First pilot release of `@aventara/nest`: it hosts an Aventara Framework in a NestJS 12 application (peers
+  `@nestjs/common` and `@nestjs/core` `^12.0.0`). It exports `AventaraModule`, `AVENTARA_FRAMEWORK`, `InjectFramework`
+  and the types `AventaraModuleOptions` / `AventaraModuleAsyncOptions`.
+
+  - **Mounting.** `AventaraModule.forRoot({ framework })` uses your own instance; `forRoot({ config })` calls
+    `createFramework(config)` itself; `forRootAsync({ imports, inject, useFactory })` resolves either. Both forms are
+    generic like `createFramework`, so a configuration is checked against its adapter's model. The module is global;
+    inject the Framework with `@InjectFramework()`. A configuration error rejects `NestFactory.create` before the
+    application listens, and passing both `framework` and `config`, neither, a value that is not a Framework, or
+    mounting the module twice is refused with a fixed message.
+  - **Routes.** One platform route per route the protocol advertises — every operation, `GET /_contract`, and
+    `POST /_transactions` when transactions are interactive — at its literal path under `FrameworkConfig.entrypoint`
+    (a Nest global prefix does not move it), on Express and on Fastify. Any other path under the entrypoint's `/_`
+    namespace gets the protocol's own answer; every other path goes on to Nest.
+  - **What runs on them.** Nest's guards, interceptors and pipes do not; `app.use` middleware and `enableCors()` do.
+    `MiddlewareConsumer` middleware does not run on them on Express, and does on Fastify — exclude `<entrypoint>/_*`
+    (for example `.exclude("api/_*path")`) to keep it off. A throw while translating a request reaches your exception
+    filter.
+  - **Request bodies.** Read raw and bounded by the contract's `limits.maxRequestBytes`; `gzip`, `deflate` and `br` are
+    decoded and the limit counts decoded bytes (`413 A2010`); any other coding answers `415 A2011`, and a body that does
+    not decode in the coding it names answers `400 A2000`. Nothing is executed in either case. Your own routes keep Nest's
+    parsed `req.body`.
+  - **Platform differences.** On Fastify, Resource keys or an entrypoint holding `*` or a reserved character
+    (`: + # $ & , / ; = ? @`) are refused at startup, naming them — rename them, or host on Express. Express answers a
+    non-canonical percent-encoding of a protocol route with `500 A3000`, and matches the entrypoint in any case by
+    default.
+  - Works under Nest's testing module (`Test.createTestingModule(…).compile()` then `createNestApplication()`), and every
+    export has a `default` condition, so a CommonJS NestJS project can `require()` it. The README covers the ways to
+    mount the module, typed injection, what fails before listen, and the platform differences.
+
+### Patch Changes
+
+- Updated dependencies
+  - @aventara/core@0.1.0-pilot.0

package/README.md

@@ -1,16 +1,16 @@
 # `@aventara/nest`
 
-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
+Hosts an Aventara `AvFramework` in a NestJS application. It mounts the framework's HTTP protocol
+(`AvProtocol.bind(framework)` from `@aventara/core/protocol`) on Nest's HTTP platform, and puts the `AvFramework` 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.
+It runs on 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.
+`AventaraModule` is a global module, imported once in your root module. It takes the `AvFramework` in one of four forms.
 
 ```ts
 // src/app.module.ts — the shape `aventara init` writes (`@aventara/cli`)
@@ -33,14 +33,27 @@ import { PrismaModule, PrismaService } from "./prisma.service.js";
 })
 export class AppModule {}
 
-// src/aventara.config.ts — the framework's configuration: entrypoint, restrictions, pipelines
+// src/aventara.config.ts — the framework's configuration: api, exposure, pipelines, resources
+import type { AvDiagnostic } from "@aventara/core";
 import { createPrismaAdapter } from "@aventara/prisma7-adapter";
+import { Logger } from "@nestjs/common";
 import { discovery } from "./generated/aventara/discovery.artifact.js";
 import type { PrismaService } from "./prisma.service.js";
 
+const logger = new Logger("Aventara");
+
 export async function aventaraConfig(prisma: PrismaService) {
 	return {
-		entrypoint: "/api",
+		api: "/api",
+		exposed: true,
+		// The raw error of a server failure, with its stack, in Nest's log.
+		diagnostics: (diagnostic: AvDiagnostic) => {
+			const { error } = diagnostic;
+			logger.error(
+				`${diagnostic.code} (request ${diagnostic.requestId}): raw error`,
+				error instanceof Error ? error.stack : String(error),
+			);
+		},
 		adapter: await createPrismaAdapter({
 			client: prisma,
 			discovery,
@@ -53,15 +66,18 @@ export async function aventaraConfig(prisma: PrismaService) {
 
 | Form | When |
 |---|---|
-| `AventaraModule.forRoot({ framework })` | You called `createFramework(config)` yourself and want your own typed `Framework<M, Cfg>` in code. |
+| `AventaraModule.forRoot({ framework })` | You called `createFramework(config)` yourself and want your own typed `AvFramework<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
+Each form also takes `state`, which seeds every protocol request's `ctx.$state` from the platform request (see
+*Request state*).
+
+The `config` form is typed exactly like `createFramework`'s parameter: an annotated `AvConfig<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:
+`@InjectFramework()` (or `@Inject(AVENTARA_FRAMEWORK)`) injects the `AvFramework`. DI carries no type argument, so type
+the parameter with your own alias:
 
 ```ts
 export type AppFramework = Awaited<ReturnType<typeof buildFramework>>;
@@ -72,23 +88,23 @@ export class ReportsService {
 }
 ```
 
-**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.
+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; a `state` option that is not a function; the module mounted twice in one application; a platform other than Express
+or Fastify (or none, as in `createApplicationContext`); an `AvConstructionError`, 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. A testing module initialized with no
-application at all is refused at `init()`, as a platform of `none`.
+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. 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
+The module owns no resource, so there is nothing to shut down. Your Prisma provider closes its own client in its
 `onModuleDestroy`, with `app.enableShutdownHooks()` for signals.
 
 ## Calling it by hand
 
-Against the shape `aventara init` writes — the entrypoint `/api`, a Prisma `User` model:
+Against the shape `aventara init` writes (the `api` mount path `/api`, a Prisma `User` model):
 
 <!-- pilot-gate:curl -->
 ```bash
@@ -108,18 +124,19 @@ curl -s -X POST http://localhost:3000/api/_resources/User/find/many \
 Leave out an identity header and the answer is `400 A2000`, naming the header that is missing. The hash changes
 whenever the schema or the configuration does: fetch it again, and regenerate the client.
 
-- **Resource keys are the model names, as written.** `model User` is `User` everywhere: on the wire
-  (`/_resources/User/find/many`) and in the generated client (`avClient.User.find.many({})`). Nothing is renamed,
-  lower-cased or pluralized.
-- **Results are read-only.** A list result is a `readonly` array: type it `readonly User[]`, not `User[]` —
-  `const users: readonly User[] = await avClient.User.find.many({});`.
+Resource keys are the model names, as written. `model User` is `User` everywhere: on the wire
+(`/_resources/User/find/many`) and in the generated client (`avClient.User.find.many({})`). Nothing is renamed,
+lower-cased or pluralized.
+
+Results are read-only. A list result is a `readonly` array, so type it `readonly User[]`:
+`const users: readonly User[] = await avClient.User.find.many({});`.
 
 ## 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>/_*`. Nest's `RouterExplorer` does not list platform routes, so the module logs one line of its
+The protocol's routes are platform routes, registered from the module's `configure()`. There is one per
+`protocol.surface()` entry (every advertised operation, `GET <api>/_contract`, and `POST
+<api>/_transactions` only when the ClientContract advertises `interactive`), plus the absence handler for the
+rest of `<api>/_*`. Nest's `RouterExplorer` does not list platform routes, so the module logs one line of its
 own when it mounts them, through Nest's `Logger` (context `AventaraModule`; `logger: false` silences it like any other):
 
 ```text
@@ -127,16 +144,19 @@ own when it mounts them, through Nest's `Logger` (context `AventaraModule`; `log
 ```
 
 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:
+(context `Aventara`): the code, the operation, the origin and the request id, and the thrown value's class name. It
+never logs the message, which can hold SQL or a connection string. The raw error still goes to your `diagnostics` sink, when you
+configure one. The `aventara.config.ts` that `aventara new` and `aventara init` write has one: it logs the raw error with its
+stack through the same `Logger`, at error level, right after this line.
 
 ```text
-[Nest] ERROR [Aventara] A3001 on Post.create.one (client scope, request 3f1c…): PrismaClientValidationError. The raw error goes to the framework's diagnostics sink.
+[Nest] ERROR [Aventara] A3001 on Post.create.one (client origin, request 3f1c…): PrismaClientValidationError. The raw error goes to the framework's diagnostics sink.
+[Nest] ERROR [Aventara] A3001 (request 3f1c…): raw error
+PrismaClientValidationError: …
 ```
 
-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.
+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.
@@ -146,42 +166,97 @@ 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 |
+| Nest guards, interceptors, pipes (global or not) | never | never |
+| `MiddlewareConsumer` middleware | never | runs, because Fastify runs Nest middleware before routing; add `.exclude("api/_*path")` (your `api` path) to keep it off |
+| Your controller at `<api>/_contract` (or any `_` path) | never reached | the application does not start |
+| Your controller at `<api>/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.
+Authorization therefore belongs in Aventara pipelines (guards). A guard reads the request's headers as
+`ctx.$transport.headers` (lower-cased names, repeats joined), and whatever your middleware found as `ctx.$state`,
+through the module's `state` option (next section).
 
-**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.
+## Request state
+
+`state` seeds each protocol request's `ctx.$state`, the one object every stage of that request reads and writes. It is
+called once per request, with the platform's own request, after the protocol has accepted it (a stale client or an
+unknown route never calls it):
+
+```ts
+declare module "@aventara/core" {
+	interface AvState {
+		user?: { id: string; roles: string[] };
+	}
+}
+
+AventaraModule.forRoot({
+	config,
+	state: (req: Request) => ({ user: req.user }), // what your auth middleware set
+});
+
+// In the configuration: a guard reads it.
+const signedIn: AvGuard = (ctx) => ctx.$state.user !== undefined;
+```
+
+- `forRootAsync`'s `useFactory` returns `state` beside `framework` or `config`.
+- On Express, `req` is Express's request. On Fastify it is Fastify's `request`; `app.use` middleware writes to its
+  Node request, so read `request.raw.user`. Fastify answers a protocol route from its `onRequest` hook, so only what
+  runs before it (`app.use` middleware, an earlier `onRequest` hook) has run.
+- Use `app.use(...)` for the middleware that finds the user (a Passport `authenticate` call, a session or JWT check).
+  Nest guards never run on protocol routes, and `MiddlewareConsumer` middleware does not on Express (the table above).
+- Throw `new AvError("A4001", "…")` from `state` to refuse the request (`403`); any other throw is `500 A3000`, with the
+  error in your `diagnostics` sink.
+- A plan sent to `/_transactions` gets one state for all its steps and transaction stages. A ctx call a stage makes
+  inherits it. Compute reads it but cannot write it.
+- Server code that calls the framework in process seeds it per call:
+  `framework.application.Post.create.one(args, { state: { user } })`.
+
+`AvConfig.api` alone decides where the protocol is mounted. `app.setGlobalPrefix(...)` does not move it; set
+`api` 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
+- 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
+- For `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.
+- 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, so set `Aventara-Request-Id` at your
+  proxy.
+- A query string is not part of the protocol path; it is ignored.
+
+## The MCP endpoint
+
+With `mcp` in the configuration, the module also mounts the MCP server of `@aventara/mcp` at that path, on Express and
+Fastify alike, and logs `Aventara mounted the MCP endpoint at /mcp (…)`. Install it beside this package, at the same
+version:
+
+```bash
+npm install @aventara/mcp@rc
+```
+
+It is an optional peer dependency: an application without `mcp` does not need it, and one with `mcp` and without the
+package refuses to start, naming it. As for the protocol's routes, the module only mounts: the endpoint's body is read
+raw, the request's URL comes from the platform's `protocol` and `host` (set `trust proxy` on Express or `trustProxy` on
+Fastify behind a proxy), and every answer is `@aventara/mcp`'s. The `state` option seeds each tool call's `ctx.$state`.
+See `@aventara/mcp`'s README for the tools, the contract resource and authorization.
 
 ## 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
+- Fastify cannot mount some Resource keys or `api` paths as literal routes. A Resource key that needs `*` or a
+  reserved character (`: + # $ & , / ; = ? @`) in its route path, or an `api` path 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.
+- 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. The
+  MCP endpoint is the exception: on both platforms it answers its own path only, exactly as written (`/mcp`, not
+  `/MCP` or `/mcp/`).
+- 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. This is a known divergence.
 - 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`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.