@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

package/README.md

@@ -2,11 +2,11 @@
 
 The Aventara framework itself: the framework factory (`createFramework`), configuration and its resolution, the
 adapter interfaces an ORM adapter implements, Contract compilation and identity, validation, operation semantics, the
-pipeline runtime, transactions and execution. Its HTTP protocol — passive data and pure functions; it mounts nothing —
-is the separate entry point `@aventara/core/protocol`, which hosts such as `@aventara/nest` serve.
+pipeline runtime, transactions and execution. Its HTTP protocol is the separate entry point `@aventara/core/protocol`,
+which hosts such as `@aventara/nest` serve. The protocol is passive data and pure functions, and it mounts nothing.
 
-Core is ORM- and transport-agnostic: it imports neither Prisma nor NestJS. An application uses it through an adapter
-(`@aventara/prisma7-adapter`) and a host (`@aventara/nest`), and the usual way to set that up is the CLI.
+Core imports neither Prisma nor NestJS. An application uses it through an adapter (`@aventara/prisma7-adapter`) and a
+host (`@aventara/nest`), and the usual way to set that up is the CLI.
 
 ## Install
 
@@ -16,21 +16,21 @@ npx @aventara/cli@rc init           # or: add Aventara to an existing NestJS 12
 npm install @aventara/core@rc       # the package on its own
 ```
 
-Node `^22.18.0 || >=24.2.0`. ES modules, with a CommonJS `default` condition.
+Node `^22.23.4 || >=24.22.1`. ES modules, with a CommonJS `default` condition.
 
 ## Documentation
 
-Start from the `@aventara/cli` README (what `new` and `init` write), then `@aventara/nest` (mounting a `Framework`)
-and `@aventara/prisma7-adapter` (the Prisma 7 adapter and its generate step); each package's README ships in its
+Start from the `@aventara/cli` README (what `new` and `init` write), then `@aventara/nest` (mounting an `AvFramework`)
+and `@aventara/prisma7-adapter` (the Prisma 7 adapter and its generate step). Each package's README ships in its
 tarball and shows on its npm page.
 
 ## Typed Json fields
 
-A `Json` field is any JSON by default. To give it a shape, build one with `AvZ` from `@aventara/core/json` and declare
-it on the field in the configuration:
+A `Json` field is any JSON by default. To give it a shape, build one with `AvZ` from `@aventara/core/avz` and declare
+it as the field's `definition.json` in the configuration's `resources` tree:
 
 ```ts
-import { AvZ } from "@aventara/core/json";
+import { AvZ } from "@aventara/core/avz";
 
 const postMeta = AvZ.object({
   seo: AvZ.object({ title: AvZ.string(), keywords: AvZ.array(AvZ.string()) }),
@@ -42,86 +42,511 @@ const postMeta = AvZ.object({
 export type PostMeta = AvZ.infer<typeof postMeta>;
 
 const framework = await createFramework({
-  entrypoint: "/api",
+  api: "/api",
   adapter,
-  fields: { Post: { meta: { json: postMeta } } },
+  resources: { Post: { fields: { meta: { definition: { json: postMeta } } } } },
 });
 ```
 
-- **Typed.** `framework.application`, `framework.client`, `appTx` and `clientTx` read and write `Post.meta` as
-  `PostMeta`, not as generic JSON, and so does a client generated with `avclient` (it emits the type; it needs no
-  Zod).
-- **Checked on every write.** A create, update, upsert, nested write or transaction step that writes `meta` — a value
-  a transaction step takes from an earlier step included — is checked against the shape before the database is
-  asked. A value out of shape is refused with `A2004`, one issue per problem at its exact path:
+`framework.application`, `framework.client`, `appTx` and `clientTx` read and write `Post.meta` as `PostMeta` instead
+of generic JSON. So does a client generated with `avclient`, which emits the type and needs no Zod.
 
-  ```json
-  { "code": "V1001", "path": ["arguments", "data", "meta", "seo", "title"], "message": "Value must be a string." }
-  ```
+The shape is also one of `meta`'s validators. Every write of `meta` is checked against it before the database is
+asked: a create, update, upsert, nested write or transaction step, including a value a transaction step takes from an
+earlier step. It is checked where validators run, after every pipe and write compute and before any interceptor or hook, and its issues
+come in field order with the other validators'. A value out of shape is refused with `A2004`, one issue per problem at its
+exact path:
+
+```json
+{ "code": "V1001", "path": ["arguments", "data", "meta", "seo", "title"], "message": "Value must be a string." }
+```
 
-  A missing key is `V1000`, a value outside an enum or a literal `V1002`, an integer outside the safe range `V1004`,
-  and a key the shape does not declare `V1005`, once per key. Reads and filters are never checked against a shape, so
-  rows written before the shape existed stay readable.
-- **Types only.** `AvZ` has `string`, `number`, `int`, `boolean`, `null`, `literal`, `enum`, `object`, `array`,
-  `tuple`, `record`, `union`, `discriminatedUnion`, `optional` and `nullable` — no lengths, ranges, patterns,
-  refinements, transforms or defaults. Objects are closed: a key the shape does not declare is refused. `optional`
-  marks an object key that may be left out.
-- **Where it applies.** Only a field the adapter discovered as `Json` takes a shape, and the shape itself cannot admit
-  `null` or absence at its top level — whether the field may be `null` comes from your schema. A shape is built with
-  `AvZ` only: a Zod schema is not accepted, as a type error and when the framework starts.
-- **In the Contract.** The shape is part of the ClientContract, as JSON Schema; adding or changing one changes the
-  ClientContract hash, so regenerate the client.
+A missing key is `V1000`, a value outside an enum or a literal `V1002`, an integer outside the safe range `V1004`,
+and a key the shape does not declare `V1005`, once per key. Reads and filters are never checked against a shape, so
+rows written before the shape existed stay readable.
+
+`AvZ` has `string`, `number`, `int`, `boolean`, `null`, `literal`, `enum`, `object`, `array`, `tuple`, `record`,
+`union`, `discriminatedUnion`, `optional` and `nullable`. A shape node takes checks with `.check(...)`: a string takes
+length, pattern and format checks, a number or an integer takes bounds and `multipleOf`, and an array takes
+`AvZ.minItems`/`AvZ.maxItems`, as in `AvZ.string().check(AvZ.maxLength(80))`. There are no refinements, transforms or
+defaults. Objects are closed: a key the shape does not declare is refused. `optional` marks an object key that may be
+left out.
+
+Only a field the adapter discovered as `Json` takes a shape. The shape cannot admit `null` or absence at its top
+level; whether the field may be `null` comes from your schema. A shape is built with `AvZ` only. A Zod schema is
+refused, both as a type error and when the framework starts.
+
+The shape is part of the ClientContract, as JSON Schema. Adding or changing one changes the ClientContract hash, so
+regenerate the client.
 
 The shape types `AvZShape`, `AvZObject`, `AvZOptional` and `AvZNullable` are exported so a project that emits
 declarations can name the shapes it exports.
 
-`@aventara/core/json` is the only entry that loads Zod (`zod/mini`); an application that declares no shape never loads
+`@aventara/core/avz` is the only entry that loads Zod (`zod/mini`); an application that declares no shape never loads
 it.
 
+## Server-side calls resolve their data and throw their failures
+
+`framework.application`, `framework.client`, `framework.transaction([...])` and a pipeline's `ctx` calls settle the way
+a generated client does: they resolve the data (a row, a list, a count, `null` for a `first` that matched nothing; a
+committed transaction its steps' results in order) and throw every failure as the `AvError` subclass of its code's
+class, exported from `@aventara/core`:
+
+```ts
+import { AvNotFoundError, AvValidationError } from "@aventara/core";
+
+try {
+  const post = await framework.application.Post.update.unique({ where: { id }, data: { title } });
+} catch (error) {
+  if (error instanceof AvNotFoundError) return null;        // A2003
+  if (error instanceof AvValidationError) throw badRequest(error.cause.issues);
+  throw error;
+}
+```
+
+| Class                     | Codes                                       |
+| ------------------------- | ------------------------------------------- |
+| `AvProtocolError`         | A2000, A2001, A2002, A2006, A2010–A2012     |
+| `AvNotFoundError`         | A2003                                       |
+| `AvValidationError`       | A2004, A2007, A2009                         |
+| `AvContractMismatchError` | A2005                                       |
+| `AvConflictError`         | A2008, A2013, A2014                         |
+| `AvInternalError`         | A3000–A3004                                 |
+| `AvAuthError`             | A4000–A4002                                 |
+
+`error.code` and `error.cause` are the envelope's (a transaction's `cause.operation` names the failing step). The
+generated client throws the same classes by the same table. `framework.execute` and `framework.executeTransaction`, the
+entries a transport calls, still answer the envelope.
+
+## The client layer, called with your own values
+
+`framework.client` reads its arguments in the wire forms a decoded request body carries: a `datetime` is its ISO string,
+a `bigint` its base-10 string. That suits a test that should behave like a remote caller. Server code that acts for a
+remote caller, such as a Server Component or a Server Action, holds `Date`s and `bigint`s instead. It calls
+`framework.serverClient`:
+
+```ts
+const recent = await framework.serverClient.Post.find.many({
+  where: { createdAt: { gt: new Date(Date.now() - 86_400_000) } },
+  select: ["id", "title"],
+});
+```
+
+`serverClient` has the client layer's types and rules: what the client layer hides is absent, and the client
+pipelines, validation, exposure and policy run. Its arguments are the application forms (`Date`, `bigint`,
+`AvDecimal`, `Uint8Array`), the same ones `framework.application` takes, and its results are `framework.client`'s.
+Each call copies its arguments, encodes them into the wire forms and runs the request `framework.client` would run.
+`framework.serverClientTx` builds client-layer transaction handles the same way; one `framework.transaction([...])`
+may hold them beside `clientTx` handles, never beside `appTx` ones.
+
+## Every code, explained
+
+`AvErrorCatalog` holds every code this package answers, reports in a validation issue, or refuses to start with: its
+`kind`, `message`, `cause`, `fix` and `docs` URL. The same catalog ships beside `dist` as `ERRORS.md`, and each entry
+of a startup `AvConstructionError`'s `diagnostics` carries its code's `docs` URL.
+
+```ts
+import { AvErrorCatalog } from "@aventara/core";
+
+AvErrorCatalog.A2004.fix; // "Fix the argument each issue's path points at, …"
+AvErrorCatalog.V1000.docs; // "https://aventara-framework.vercel.app/docs/error-codes#v1000"
+```
+
+## Required create fields are typed
+
+Each Resource's Contract states what a create cannot do without (`createRequirements`), as the adapter reads it off
+the database schema: the fields every create must write, and each required relation, which a create writes either as
+the relation or through the fields that hold its reference, never both. The façades, `appTx`/`clientTx`, a stage's
+`ctx` and the generated client type every create payload by it:
+
+```ts
+await framework.application.Post.create.one({ data: { title: "Hi", authorId } });          // ok
+await framework.application.Post.create.one({ data: { title: "Hi", author: { $connect: { id: authorId } } } }); // ok
+// @ts-expect-error neither `author` nor `authorId`
+await framework.application.Post.create.one({ data: { title: "Hi" } });
+// @ts-expect-error `author` and `authorId` both
+await framework.application.Post.create.one({ data: { title: "Hi", authorId, author: { $connect: { id: authorId } } } });
+```
+
+It covers `create.one`'s `data`, every `create.many` record, `upsert`'s `create`, and nested `$create`,
+`$connectOrCreate` and `$upsert` payloads, where the relation the create is nested through is supplied by its parent.
+A `$ref` satisfies a field. Each layer's Contract states only what that layer lets a caller write: hide `authorId` and
+`author` alone is required; hide `author` and `authorId` is. A field a `compute.create` stage fills is not required,
+whether the stage is written inline in `createFramework({...})`, in a `defineResource` block or in a typed config.
+The runtime still refuses what the types refuse (`A2004`, `V1000` or `V1012`).
+
+A `create.many` or `create.count` record cannot write a relation, so there `authorId` is required. A layer that hides
+`authorId` while it keeps those variants fails at startup (`COMPILER_HIDDEN_REQUIRED_FIELD`): expose `authorId`, give
+it a `compute.create`, or exempt `create.many` and `create.count` in that layer
+(`exemptions: { resources: { Post: { fields: { authorId: true }, operations: { create: ["many", "count"] } } } }`).
+
+A field your operation pipe fills server-side is now required of the caller. Give it a `compute.create` stage (or a
+database default) so callers can leave it out, or have them pass it.
+
+Inside the pipeline the requirements hold from write compute on. A variant's guards, pipes and filters run before
+compute, and their typed arguments require no field of a create, since compute may still fill it: `args.data.slug` is
+`string | undefined` in a pipe, and a pipe may return a create without it. The variant's hooks and interceptors run
+after compute and see every required field present.
+
+## Returning a façade from a method
+
+A Nest project emits declarations (`declaration: true`), so a method without a return type has its type written out.
+Every node of the typed façades has a name for that, and so does the Contract view they are typed over, so a method can
+return any of them without an annotation:
+
+```ts
+@Injectable()
+export class PostsService {
+  constructor(@InjectFramework() private readonly framework: AppFramework) {}
+
+  posts() {
+    return this.framework.application.Post;
+  }
+
+  findMany() {
+    return this.framework.application.Post.find.many;
+  }
+}
+```
+
+The declaration file writes a short reference, under half a kilobyte per method at any schema size:
+
+```ts
+posts(): import("@aventara/core").AvApplicationResourceFacade<
+  import("@aventara/core").AvContractView<import("…/discovery.artifact.js").AvModel, never, "omit", never, "omit", never, never>,
+  "Post">;
+findMany(): import("@aventara/core").AvApplicationProjectingCall<
+  import("@aventara/core").AvContractView<import("…/discovery.artifact.js").AvModel, never, "omit", never, "omit", never, never>,
+  "Post", { readonly family: "find"; readonly variant: "many" }>;
+```
+
+The names, one set per surface (`application`, `client`, `serverClient`, `appTx`, `clientTx`, `serverClientTx`):
+
+| Node | `framework.application` | the others |
+| --- | --- | --- |
+| the whole surface | `AvApplicationFacade` | `AvClientFacade`, `AvServerClientFacade`, `AvAppTxFacade`, `AvClientTxFacade`, `AvServerClientTxFacade` |
+| one Resource | `AvApplicationResourceFacade` | `AvClientResourceFacade`, … |
+| one family | `AvApplicationFamilyFacade` | `AvClientFamilyFacade`, … |
+| a variant that takes a `select` or `include` | `AvApplicationProjectingCall` | `AvClientProjectingCall`, `AvServerClientProjectingCall`, `AvAppTxProjectingCall`, `AvClientTxProjectingCall`, `AvServerClientTxProjectingCall` |
+| a variant that does not (the `count` variants: `find.count`, `update.count`, …) | `AvApplicationPlainCall` | `AvClientPlainCall`, `AvServerClientPlainCall`, `AvAppTxPlainCall`, `AvClientTxPlainCall`, `AvServerClientTxPlainCall` |
+
+Each takes the view, `AvContractView`, as its first argument. The view's arguments are your model by its name, the root's
+and the overlay's exposure as written, and the `fields` entries your configuration's `resources` blocks hold. A
+configuration with no `fields` entries writes `never` there. One that has them writes those entries, stages erased, after
+every reference: measured at about 23 KB per method over 50 Resources that each configure a field. Annotate the method
+(`posts(): AppFramework["application"]["Post"]`) if that matters to you; the annotation is written as that reference.
+
+You never need to write these names yourself. They exist so a declaration file can name what a method returns, and a
+project that reads only your declarations types the method exactly as your Framework does. An application that publishes
+no declarations can set `"declaration": false` and skip the question.
+
+The configuration itself costs almost nothing to declare. The Prisma adapter's discovery artifact names the model's
+type (`AvModel`), so the scaffold's `aventaraConfig()`, a `buildFramework` and its `AppFramework` alias write
+`AvAdapter<AvModel>` and `AvFramework<AvModel, …>`: about 0.5 KB at any schema size, where rc.1 wrote
+the model out once per mention (1.2 MB over 50 Resources).
+
+An exported `defineResource(...)` result, and an exported configuration or Framework builder holding typed stages,
+need no annotation: their stages are written by their public types (`readonly AvGuard[]`, `readonly AvPipe[]`, …),
+never with the model the inline stages were typed from.
+
 ## Server-side calls copy their input
 
-`framework.application`, `framework.client`, `framework.execute`, `framework.executeTransaction`, and the `appTx` /
-`clientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
-Everything after that — validation, your guards and pipes, computed values, the adapter — sees only the copy:
-
-- **Changing your object afterwards changes nothing.** An Immer draft revoked after `produce`, or a reactive store that
-  moves on, is safe to pass: the call already has its own copy.
-- **A live Proxy works** (Vue `reactive`, MobX): it is read through its traps once.
-- **`Date`, `Decimal` and `Uint8Array`** (a Node `Buffer` too) are copied as themselves; `bigint` and other primitives are
-  values.
-- **Only plain data.** Arrays and plain objects (`{}` or `Object.create(null)`) are copied with their own enumerable
-  string keys, like JSON: inherited, non-enumerable and symbol keys are dropped. Any other object — a class instance, a
-  `Map` — is refused.
-- **A value that cannot be read** (a revoked Proxy, a getter that throws) is refused too. Both refusals are your
-  request's error, not the server's: `A2004` with one `V1001` at the value's path — `["arguments", …]`, or
-  `["operations", i, "args", …]` with `cause.operation` in a transaction — before any guard, pipe or adapter runs:
+`framework.application`, `framework.client`, `framework.serverClient`, `framework.execute`,
+`framework.executeTransaction`, and the `appTx` / `clientTx` / `serverClientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
+Validation, your guards and pipes, computed values and the adapter all see only the copy, and your stages see it
+frozen: only a pipe changes the arguments, by returning new ones, so what the validators checked is what the adapter
+writes. In practice:
+
+- Changing your object afterwards changes nothing. An Immer draft revoked after `produce`, or a reactive store that
+  moves on, is safe to pass, because the call already has its own copy.
+- A live Proxy (Vue `reactive`, MobX) works: it is read through its traps once.
+- `Date`, `AvDecimal` and `Uint8Array` (a Node `Buffer` too) are copied as themselves; `bigint` and other primitives
+  are values.
+- Arrays and plain objects (`{}` or `Object.create(null)`) are copied with their own enumerable string keys, like JSON:
+  inherited, non-enumerable and symbol keys are dropped. Any other object, such as a class instance or a `Map`, is
+  refused.
+- A value that cannot be read (a revoked Proxy, a getter that throws) is refused too. Both refusals are errors in your
+  request, not the server's: `A2004` with one `V1001` at the value's path (`["arguments", …]`, or
+  `["operations", i, "args", …]` with `cause.operation` in a transaction), before any guard, pipe or adapter runs:
 
   ```json
   { "code": "V1001", "path": ["arguments", "where", "id"], "message": "Value could not be read." }
   ```
 
-  A builder never throws: `appTx`/`clientTx` keep the refusal, and `framework.transaction([...])` answers it.
+  A builder never throws: `appTx`/`clientTx` keep the refusal, and `framework.transaction([...])` throws it as an
+  `AvValidationError`.
 
 To count these refusals, set `misuse` at the root of the configuration, beside `diagnostics`:
 
 ```ts
 const framework = await createFramework({
-  entrypoint: "/api",
+  api: "/api",
   adapter,
   misuse: (event) => metrics.increment("aventara.misuse", { kind: event.kind }),
 });
 ```
 
-It receives one `FrameworkMisuseEvent` per refusal — `kind` (`"unreadable-value"` or `"non-plain-value"`), the `path`
-the caller received, and `origin`, `resource`, `family`, `variant` and the transaction step (`operation`) when they could
-be read — never the value itself. It cannot change the response: an error it throws, or a promise it rejects, is
-ignored. `diagnostics` keeps receiving the server's own unexpected failures, and nothing is reported to both.
+It receives one `AvMisuseEvent` per refusal, never the value itself. The event has `kind` (`"unreadable-value"` or
+`"non-plain-value"`), the `path` the caller received, and `origin`, `resource`, `family`, `variant` and the
+transaction step (`operation`) when they could be read. It cannot change the response: an error it throws, or a
+promise it rejects, is ignored. `diagnostics` keeps receiving the server's own unexpected failures, and nothing is
+reported to both.
+
+HTTP requests are not copied twice. A body that `protocol.handleOperation` / `handleTransaction` parse from raw content
+(as `@aventara/nest` hands it to them) is already plain data. A body your host parsed itself, passed as
+`{ kind: "parsed" }`, is copied like any server-side input.
+
+## Developer SQL in an application transaction
+
+`framework.appTx.$sql` adds a SQL statement to an application transaction. It is written only as a tagged template, and
+every interpolated value is a bound parameter, never part of the SQL text:
 
-HTTP requests cost nothing extra: a body that `protocol.handleOperation` / `handleTransaction` parse from raw content
-(as `@aventara/nest` hands it to them) is already plain data and is not copied again. A body your host parsed itself,
-passed as `{ kind: "parsed" }`, is copied like any server-side input.
+```ts
+const post = framework.appTx.Post.create.one({ data: { title, authorId }, select: ["id"] });
+const job = framework.appTx.$sql<{ msg_id: bigint }>`
+  select pgmq.send('jobs', jsonb_build_object('postId', ${post.$ref("id")}))`;
+
+const [created, rows] = await framework.transaction([post, job]);
+// rows is { msg_id: bigint }[]; without <Row> it is unknown[]
+```
+
+- The statement runs in plan order, in the same database transaction as the other steps. If it fails, or a later step
+  fails, everything rolls back.
+- A value is a string, number, boolean, `bigint`, `null`, `Date`, `AvDecimal`, `Uint8Array`, a JSON value (a plain
+  object or array, bound as JSON text, so cast it: `${value}::jsonb`), or a `$ref` to an earlier step's field, which
+  is read after that step ran and then bound. Values are copied like every other input (see above).
+- The SQL text is static. A table or column name cannot come from a value.
+- A later step cannot `$ref` a SQL step's rows (`A2007`/`V1010`).
+- No guard, pipe, hook, interceptor or filter runs around a SQL step. A SQL error is answered as the adapter
+  classifies it (a uniqueness or reference violation is `A2008`, anything else `A3001`).
+- A stage's `ctx.$sql` runs the same bound template at once. Inside a transaction it joins it; outside one it is a plain
+  statement, with no transaction opened around it.
+- It exists only here. `clientTx` has no `$sql`, the ClientContract carries nothing of it, and `/_transactions` cannot
+  express it. The adapter must support it (`@aventara/prisma7-adapter` does wherever it runs transactions); otherwise a
+  plan holding one is refused with `A2002`.
+
+Aventara itself never writes raw SQL. This tagged template is the only way SQL reaches the database, and the SQL is
+yours.
+
+## The agent layer
+
+`agent` is a layer for calls an AI agent makes, served over MCP. It narrows the view of the layer it `extends`
+(`"client"` when left out, or `"application"`, or `"root"`) and never widens it; its stages run after that layer's, and
+each one sees `ctx.$origin === "agent"`:
+
+```ts
+const framework = await createFramework({
+  api: "/api",
+  mcp: "/mcp",
+  adapter,
+  agent: {
+    exposed: true,
+    exemptions: { resources: { Post: { operations: { delete: true } } } },
+    pipelines: { guards: [(ctx) => ctx.$state.user !== undefined] },
+  },
+});
+```
+
+It compiles to `framework.contracts.agent`, identified by its own hash, and `framework.mcp` is the resolved MCP
+endpoint. A host runs agent calls through `AvProtocol.bind(framework, { origin: "agent" })`, which validates them
+exactly as client calls are validated, against the Agent Contract.
+
+## A policy engine
+
+`policy` hands authorization to an engine Aventara never imports. The engine answers three questions per
+Resource — may the principal run this action (`can`), which rows (`scopeOf`, a `where` fragment), which fields
+(`fieldsOf`) — and core enforces the answers on every client and agent request:
+
+```ts
+const framework = await createFramework({
+  api: "/api",
+  adapter,
+  policy: {
+    engine, // satisfies AvPolicyEngine
+    principal: ({ $state }) => $state.user ?? null,
+  },
+});
+
+await framework.application.Note.find.many({}, { as: user }); // checked as `user`
+await framework.application.Note.find.many({}); // server code: not checked
+```
+
+The read scope is applied at the adapter call, after every developer stage, to the root `where`, every to-many include
+and its `$count`, and every relation filter. A field the engine governs (its `governed` list) is never in a default
+projection; name it to get it, `select: ["$defaults", "email"]`. A refusal answers `403 A4002`.
+
+Writes are checked too. A create asks `can` about each new row, whose rules may look rows up through `exists`. An
+update or delete acts only on rows the caller may change and read; a single-row one that misses answers `A4002` when
+the caller can read the row and `A2003` when it cannot. A field the write sends must be in
+`fieldsOf({ access: "write", action })`, `action` being `"create"` or `"update"` (an upsert's branches and a nested
+record's directive each their own), so a field can be locked on update and still written at create. A rule that
+reaches another Resource through a relation (a note only in a campaign its author plays in) reads which of the
+target's fields the reference names from the Core Contract (`framework.contracts.core`, a relation's `references`
+beside its `referenceFields`); no Contract a caller is served states them. An update that moves a row out of what the caller reads, or fails an `after` condition
+(`can` asked about the row the update returned), is rolled back. For an update the engine lists in `afterChecks`, that
+question also carries `before`, the row as it was before the update; it is present only then. An engine that also
+answers the optional `grantsOf` is asked, before the write, which of its grants cover that row (`exists` then sees
+nothing the request writes), and gets the answer back on the after check as `beforeGrants`. Such an engine refuses
+an after check that carries `before` without `beforeGrants` rather than deciding `before` after the write.
+A typed literal in a fragment the engine answers may be in its application form (`Date`, `AvDecimal`, `bigint`) or its
+wire form (an ISO string, a decimal string, a digit string), as a policy read from JSON states it. Where `transactionsStyle` is `"interactive"`, a
+checked write with a check after it (an update, a nested write) runs in a transaction of its own, and a create or
+delete checked before it runs is one statement; where it is `"none"`, a write that could only be checked after it runs
+is refused (for after conditions, the updates the engine lists in `afterChecks`).
+
+Nested writes (`$create`, `$connect` and the other relation directives) run as one call inside that transaction. Before
+it, every row they link is held to the right scope: a linked row that holds the reference must be one the caller may
+change, one whose parent holds it one the caller may read. Writing a reference field itself (`authorId: "u2"`) links
+the same row, and is held the same way: the row it names must be one the caller may read. Where the adapter can link
+the row in that write, core hands it the reference as a `$connect` carrying the read scope, so the write itself refuses
+a row outside it (`A4002`), with no query of its own; where it cannot (a bulk write on Prisma), one `exists` per target
+Resource asks before the write. Nothing is asked where that Resource is read by everyone, and a `null` reference is not
+asked about. Only a reference to a Resource the Core Contract shows is held; one the root's exemptions hide is not, nor
+one the engine lists in its optional `unheld`: a Resource its rules read in conditions and decide no read of (a
+Resource another service owns, say), so its read scope is `false` for every caller. A reference to one of those, and a
+`$connect` or `$set` that links one by the reference's own values where the writing row holds the reference, is
+decided by the write's own grant
+(`can`, and the after check `afterChecks` lists); reads of it are decided by `scopeOf` as always. An engine that has the
+optional `hosted` is told the held Resources once the Framework is built (`hosted({ held })`), so it can check its own
+rules against them; it answers nothing differently. A to-many `$update` or
+`$delete` acts only on the rows the caller may change or delete, as `update.many` does. After the call, every row they changed is checked as an update is
+(the after check, the move-out re-read), and every row they created is read back as stored and asked `can`; one refusal
+rolls the whole write back. Where `transactionsStyle` is `"none"`, a nested write under a policy is refused.
+
+## An access provider
+
+`access` takes the policy engine and the request state from one object, an `AvAccessProvider`. Aventara Access
+provides one, and you can write your own. It has two members:
+
+- `policy`: the engine, as `policy.engine` takes it.
+- `state({ headers, request })`: seeds each request's `ctx.$state`. Its `me` is the principal the engine is asked
+  about (`null` for an anonymous caller).
+
+The host calls `state` once per request: `@aventara/nest` with the platform request's headers and the request itself,
+`@aventara/next` with the request's headers (and the route's `Request` on a route call). With `access`, leave out
+`policy` and the host's own `state` option; either one beside it is refused at startup, and as a type error where the
+configuration's type shows both. Server code that calls the Framework directly passes the state itself,
+`{ state: await access.state({ headers }) }`.
+
+A point-of-sale till with its own PIN sign-in, written by hand:
+
+```ts
+import type { AvAccessProvider } from "@aventara/core";
+
+type Cashier = { id: string; role: "cashier" | "manager" };
+
+declare module "@aventara/core" {
+  interface AvState {
+    me?: Cashier | null;
+  }
+}
+
+export const tillAccess = {
+  // The till sends the PIN the cashier typed as `x-pos-pin`.
+  state: async ({ headers }) => ({ me: await cashierByPin(headers.get("x-pos-pin")) }),
+  policy: {
+    can: ({ principal, resource, action }) => {
+      const me = principal as Cashier | null;
+      if (me === null) return false; // no PIN, no till
+      if (resource === "Refund" && action !== "read") return me.role === "manager";
+      return true;
+    },
+    scopeOf: () => true,
+    fieldsOf: () => ({ always: "all", perRow: {} }),
+  },
+} satisfies AvAccessProvider;
+
+const framework = await createFramework({ api: "/api", adapter, access: tillAccess });
+```
+
+Every stage reads the cashier as `ctx.$state.me`, typed by the `AvState` declaration above.
+
+### `$access` and the provider's `client`
+
+A provider may also state `client`: where the app mounted Aventara Access (`url`, absolute `http(s)` or root-relative)
+and the verbs it offers (`signIn`, `signUp`, `signOut`, `resetPassword`, `me`, and on Access's `kiosk` profile
+`switchUser`, `lock`, `setPin`, `enrollDevice`, `revokeDevice`; each optional, any other name refused), each with its route
+(`method`, `path`), the JSON Schema of its arguments and result (the subset a `json` field's shape uses), and `call`,
+the verb run in process. Aventara Access fills it in. It is compiled into the Client Contract's `access` section with
+each `call` dropped, so the hash changes only for apps whose provider states it. Every client then carries `$access`:
+
+- `can(questions, options?)`: the batched `POST {api}/_access/can`, one boolean per question. An empty list answers
+  `[]` (`200 A1000`), not a refusal: a page with nothing to ask is no client bug, unlike an empty `/_transactions` plan.
+- `me()`: the token identity `{ sub, claims }`, or `null`; and the sign-in verbs the provider offers. A verb the
+  provider leaves out (a `service` profile has no `signIn`/`signUp`; only a `kiosk` profile has `switchUser`, `lock`,
+  `setPin`, `enrollDevice`, `revokeDevice`) is no member of `$access`. `switchUser` and `enrollDevice` resolve
+  Access's answer, `lock`, `setPin` and `revokeDevice` nothing, as `signIn` and `signOut` do.
+
+`framework.serverClient.$access` answers `can` in process under the call's `state` (or, with `headers` and no
+`state`, the state the provider seeds from them; with neither, anonymously), and runs each verb through its `call` with
+the headers you pass. The section's `url` and each verb's `path` are checked wherever a ClientContract is read: an
+absolute `http(s)` URL or a root-relative path other than `/`, a path starting with one `/`, neither holding a control
+character, a space or a `.`/`..` segment (percent-encoded too). Under Nest, hand the platform request and response too, so Access can read the
+session and set a sign-in's cookie:
+
+```ts
+const me = await framework.serverClient.$access.me({ headers: req.headers });
+await framework.serverClient.$access.signIn(body, { headers: req.headers, request: req, response: res });
+const [canRefund] = await framework.serverClient.$access.can([{ resource: "Refund", action: "create" }], { state });
+```
+
+Without `access`, `serverClient` has no `$access` at all; a provider without `client` offers `can` alone.
+
+On Access's `kiosk` profile, `switchUser`, `lock` and `enrollDevice` rotate the device's credential cookie: under
+Nest, call them with the platform `response` (`{ headers, request, response }`), or the rotated cookie never reaches
+the device and its next switch is refused. Under Next, call them from a Server Action. Never call a verb that changes
+anything inside a cache (Next's `"use cache"`, a memoized helper): a cached answer replays one caller's result to
+another and skips the call. Every verb's answer is projected onto its result schema, so no session token or device
+secret reaches server code either.
+
+## A model managed elsewhere
+
+Some tables belong to another service: Better Auth's `user`, or another service's schema in the same database. Your
+service joins into them and must not write or migrate them. Mark such a model at the root:
+
+```ts
+const framework = await createFramework({
+  api: "/api",
+  adapter,
+  resources: { Account: { managedElsewhere: true } },
+});
+```
+
+- `Account` has no `create`, `update`, `delete` or `upsert` in any layer, and its fields take no write. A call is a
+  type error, and an untyped one is refused with `A2002`.
+- A relation into it keeps only `$connect` and `$disconnect`, and only where your model holds the key (`Post.authorId`
+  for `Post.author`). A nested `$create`, `$update` or `$upsert` into it is a type error and `A2004` (`V1006`).
+- `framework.application` reads `Account` and filters and includes through `Post.author`. The client and agent layers
+  leave out `Account` and every relation into it, so `/_contract`, the generated client and the MCP tools never show
+  it. An overlay can't bring it back.
+- A stage on one of its write families is refused at startup (`COMPILER_UNAVAILABLE_OPERATION`), and
+  `managedElsewhere` in an overlay is `CONFIG_FORBIDDEN_IN_OVERLAY`. So is any `client.resources.Account` or
+  `agent.resources.Account` entry (`COMPILER_UNKNOWN_RESOURCE`): those layers never have it, so nothing there runs.
+- A delete that would write it through a referential action is refused at startup (`CONFIG_INVALID_VALUE` at
+  `resources.Account.managedElsewhere`): if any layer can delete a row whose deletion cascades into `Account` or sets
+  its reference to null or its default, directly or through other cascades. Take those deletes away at the root, or
+  make the reference `onDelete: Restrict`.
+- A create that only the hidden relation could satisfy is refused at startup (`COMPILER_HIDDEN_REQUIRED_FIELD`), naming
+  the reference field to expose instead, so no client advertises a create that can't succeed.
+- `framework.contracts.core` marks it `managedElsewhere: true`, and states every Resource's database `schema` where
+  the adapter knows it (`@@schema("auth")` with `@aventara/prisma7-adapter`). No other Contract carries either.
+
+Two things stay yours. A key update follows the owner's foreign key (`ON UPDATE CASCADE` rewrites `Account`'s rows;
+core has no `onUpdate` facts). And your own code — `ctx.$sql`, an application transaction's SQL step, a stage that
+calls Prisma directly — can still write `Account`.
+
+Aventara doesn't migrate anything, so tell Prisma too: list the table as external in `prisma.config.ts`.
+
+```ts
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  experimental: { externalTables: true },
+  tables: { external: ["auth.Account"] },
+});
+```
 
 ## 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`.

package/dist/adapters/adapter-discovery-diagnostic.d.ts

@@ -1,8 +1,8 @@
-/** Codes of {@link AdapterDiscoveryDiagnostic}. */
-export type AdapterDiscoveryDiagnosticCode = "DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH";
+/** Codes of {@link AvAdapterDiscoveryDiagnostic}. */
+export type AvAdapterDiscoveryDiagnosticCode = "DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH";
 /** A problem found in what the adapter discovered, reported at framework construction. */
-export type AdapterDiscoveryDiagnostic = {
-    readonly code: AdapterDiscoveryDiagnosticCode;
+export type AvAdapterDiscoveryDiagnostic = {
+    readonly code: AvAdapterDiscoveryDiagnosticCode;
     readonly path: "adapter.transactions";
     readonly message: string;
 };

package/dist/adapters/adapter-discovery-diagnostic.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeDescription } from "../runtime/error-guidance.js";
+import type { AvAdapterDiscoveryDiagnosticCode } from "./adapter-discovery-diagnostic.js";
+/** Meaning, cause and fix of every discovery diagnostic code. */
+export declare const ADAPTER_DISCOVERY_DIAGNOSTIC_GUIDANCE: {
+    readonly [C in AvAdapterDiscoveryDiagnosticCode]: ErrorCodeDescription;
+};

package/dist/adapters/adapter-discovery-diagnostic.guidance.js

@@ -0,0 +1,7 @@
+export const ADAPTER_DISCOVERY_DIAGNOSTIC_GUIDANCE = {
+    DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH: {
+        message: "The adapter's transaction capability does not match it.",
+        cause: "The adapter declares interactive transactions but provides no transaction function.",
+        fix: "A defect of the adapter: install the adapter release that matches @aventara/core exactly.",
+    },
+};