@aventara/core 1.0.0-rc.3 → 1.0.0-rc.8

package/CHANGELOG.md

@@ -1,5 +1,235 @@
 # @aventara/core
 
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- 1c8e4ee: Helpers typed off the façades compile again in projects that emit declarations. In 1.0.0-rc.7 a function that took
+  `Parameters<AppFramework["application"]["Post"]["find"]["many"]>[0]` and returned its `where` (or built a new one
+  from it, `{ AND: [args.where ?? {}, { published: { equals: true } }] }`) without a return type failed `nest build`
+  (and `tsc` with `"declaration": true`) with `TS4023: ... has or is using name 'ScalarFilterOperands' ... but cannot be
+  named`, usually beside `TS7056`. A nested write's data could fail the same way, or name `NO_ADVERTISED_MEMBER`, and a
+  nested `$update`'s `where` was written into the `.d.ts` as `any`. The declaration now names the argument types
+  `@aventara/core` exports (`AvWhereInput`, `AvUpdateDataInput`, `AvCreateDataInput`, ...), and these new exports cover
+  the rest:
+
+  - `AvScalarFilterOperands`: one field's filter operators, which a filter's `not` holds again.
+  - `AvScalarWhereInput`: the `where` of a nested `$update` or `$delete` that only takes plain fields.
+  - `AvNoAdvertisedMember`: a write member that advertises nothing; it takes `{}` and refuses every key.
+  - `AvSqlStatementBuilder` and `AvSqlStatementValue`: the type of `framework.appTx.$sql` and the values it binds.
+    A method returning `framework.appTx.$sql` failed with `TS2883`/`TS2742` before.
+
+  `framework.execute` and `framework.executeTransaction` take request types that `@aventara/core` exports:
+  `AvOperationRequest` (`AvApplicationOperationRequest`, `AvClientOperationRequest`, `AvAgentOperationRequest`),
+  `AvTransactionRequest` (`AvApplicationTransactionRequest`, `AvClientTransactionRequest`,
+  `AvAgentTransactionRequest`) and `AvRequestProtocol` (a remote request's `protocol`). They were named from
+  `@aventara/core/internal` (`FrameworkOperationRequest`, `FrameworkTransactionRequest`, ...), so a declaration that
+  spelled them reached into the package's internal entry. Those names are gone from `@aventara/core/internal`.
+
+  An adapter's `referentialActions` edges name the fields that hold the reference `referenceFields`, as a relation of
+  the Core Contract does. They were called `references`, which the Core Contract uses for the target's fields.
+
+  Reading a projecting variant's argument type (`Parameters<…["find"]["many"]>[0]`) also type-checks faster: about
+  6,000 type instantiations over a three-field model, where rc.7 took about 29,000. The part of the argument other than
+  `select`/`include` is now marked `NoInfer` in the call's parameter, so an editor shows that parameter as
+  `NoInfer<Omit<…>> & …`. What it accepts is unchanged.
+
+  A create's `data` type now states each required field once, as a required member (`Readonly<{ title: string; } & {
+  body?: ... }>` in an editor's expanded hover). Before, a required field appeared as an optional member beside a
+  separate `{ readonly title: WrittenValue }`, and a declaration file wrote both. What a create accepts and refuses is
+  unchanged.
+
+- Operation results read as their value types in an editor and in emitted declarations. A result field that is nullable,
+  an enum or a `boolean` (such as a `Boolean @default(false)` column) was shown as `AvScalarValueType<…>`, with the
+  whole Contract view as its argument, and a project with `"declaration": true` wrote that view into its `.d.ts` once
+  per such field: a Nest service of five methods with no return types came out at 524 lines. Those fields now read
+  `body: string | null`, `published: boolean`, `publishedAt: Date | null`, and that service's declaration is 44 lines.
+  A result, and a relation included in it, is shown as its fields rather than as `ProjectedFields<…>`. This covers
+  `framework.application` and `framework.client` results, the same fields in a write's `data`, and clients generated
+  by `avclient`. What each type accepts is unchanged.
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- f917c1c: A helper that reads `framework.contracts.core` compiles again in projects that emit declarations. In 1.0.0-rc.6 a
+  function returning a Resource or a field of the Core Contract without a return type, such as
+  `core.resources[resource]?.fields[relation]`, failed `nest build` (and `tsc` with `"declaration": true`, which Nest's
+  `tsconfig.json` sets) with `TS2883: The inferred type of 'relationOf' cannot be named without a reference to
+  'AvCoreField'` under TypeScript 6 (`TS2742` under 5.9), or with `TS4058`/`TS4023` naming `AvCoreResource`.
+  `@aventara/core` now exports the three types the Core Contract is written with: `AvCoreResource` (a Resource),
+  `AvCoreField` (one of its fields) and `AvCoreRelationField` (a relation field, with the target fields its reference
+  names in `references`).
+
+  A policy's startup check states the path once: `CONFIG_INVALID_VALUE at policy.engine.governed.Nope: "Nope" is no
+  Resource of the Core Contract`, where rc.6 repeated `policy.engine.governed.Nope:` inside the message. Each
+  diagnostic's `message` no longer starts with its `path`; read the path from `path`.
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+### Patch Changes
+
+- 1cf72e0: Typed policy engines compile again in projects that emit declarations. In 1.0.0-rc.5 an engine written
+  `as const satisfies AvPolicyEngine` failed `nest build` (and `tsc` with `"declaration": true`, which Nest's
+  `tsconfig.json` sets) with `TS2883: The inferred type of 'policyEngine' cannot be named without a reference to
+  'PolicyFieldsAccess'` under TypeScript 6, or `TS2742` under 5.9, and so did the configuration and the framework holding
+  it. `fieldsOf`'s question is now written out in full in `AvPolicyEngine`, so a declaration can spell it.
+
+  A read question's `action` is now typed `undefined`, so an engine can destructure it from either question:
+  `fieldsOf({ resource, access, action })`. A write question's `action` is `"create"` or `"update"`, as before.
+
+## 1.0.0-rc.5
+
+### Patch Changes
+
+- 4795ff1: Two additions for policy engines. A Framework without a policy, and every Contract a caller is served, are unchanged.
+
+  - A policy engine can check a create whose row reaches another Resource through a relation. Discovery now states, on the end of a relation that holds the reference, which of the target's fields its reference fields name, pair by pair (`Note.campaign`: `referenceFields: ["campaignId"]`, `references: ["id"]`). An engine reads them from the model it is built from (a Prisma discovery artifact's `model`) or from `framework.contracts.core`, and asks one `exists` about the row they name: "a player creates a note only in a campaign they play in". Only the adapter's model and the Core Contract carry them. The Application, Client and Agent Contracts, `/_contract`, the MCP tools and every ClientContract hash are unchanged. The discovery artifact's model hash, and so a prebuilt Contracts file's fingerprint, change: regenerate the artifact and rebuild the prebuilt file.
+  - `fieldsOf({ access: "write" })` also names the action that writes the record, `action: "create" | "update"` (an upsert's branches each their own, a nested record its directive's), so an engine can lock a field on update and still let a create write it. A read question names none. An engine that ignores it keeps working.
+
+- 9e178ca: Fixes for applications that check requests with a policy engine. A Framework without a policy behaves as before.
+
+  - A cursor on a row the caller cannot read is answered exactly as a cursor on a row that does not exist, at the root and in a to-many relation, whatever values the caller sends beside the identifier. Before, the page started at the hidden row, so it told that the row exists and where its values sort. The Prisma adapter reads the cursor's row under the read scope first: one statement more for a cursor on a readable row, and only that read for one on a row the caller cannot read.
+  - A unique update with a nested write (`$create`, `$connect`, …) on a row the caller can read but not change answers `A4002`, as the same update without one does. It answered `A2003`. A row the caller cannot read still answers `A2003`.
+  - The `exists` questions a policy asks select the Resource's primary identifier, never another unique field such as a governed `email`.
+  - `policy.principal` may answer with a promise. A synchronous principal works as before; a rejection answers `A3000`, as a throw does.
+  - `AvConstructionError.message` names the first problem and how many more there are, for example `Aventara framework configuration validation failed: CONFIG_INVALID_TYPE at adapter.execute: adapter.execute must be a function (+2 more)`. `stage` and `diagnostics` are unchanged.
+
+## 1.0.0-rc.4
+
+### Patch Changes
+
+- e3d03a7: The error catalog says more about policies. `A2003` now names the cases a policy adds: a unique read of a row outside the
+  caller's read scope, and a single-row update or delete of a row the caller cannot read, are misses, while a row the
+  caller can read but not change answers `A4002`. `CONFIG_REQUIRED`, `CONFIG_UNKNOWN_PROPERTY` and `CONFIG_INVALID_VALUE`
+  name the `policy` key's rules: `policy.engine` and `policy.principal` are required, `policy` and `prebuilt` are root-only,
+  and the engine's `governed`, `paths` and `afterChecks` lists must name what the Core Contract has. Wording only; no
+  behaviour changes.
+- d10639a: Faster reads. The read-only copies stages are told cost about half what they did: a read with a computed field
+  copies each row in one pass, a row with several computed fields shares its nested objects between the stages'
+  copies, and after hooks share one frozen copy of the result. A row whose computed field returns a value at once no
+  longer waits a turn per row. The MCP endpoint builds its JSON Schema validator once instead of on every request.
+  What stages are told, the order they run in and what a request answers are unchanged.
+- f67e68c: A service method can return any façade node or variant without a return type. Under `declaration: true` (a Nest
+  build) the declaration file now writes a short reference, under half a kilobyte per method at any schema size, where it
+  wrote the whole Contract view (about 440 KB per method over 50 Resources). A method returning a variant
+  (`this.framework.application.Post.find.many`) no longer needs an annotation to compile, and one returning a transaction
+  variant (`this.framework.appTx.Post.create.one`) no longer runs the compiler out of memory.
+
+  New type names, exported from `@aventara/core` so a declaration can write them (you never need to write them yourself):
+
+  - `AvContractView`, the Contract view the façades are typed over;
+  - one call type per surface and shape: `AvApplicationProjectingCall`, `AvApplicationPlainCall`,
+    `AvClientProjectingCall`, `AvClientPlainCall`, `AvAppTxProjectingCall`, `AvAppTxPlainCall`,
+    `AvClientTxProjectingCall`, `AvClientTxPlainCall`.
+
+  A configuration with `fields` entries still writes those entries after each reference; annotate the method if that
+  matters (see the README's "Returning a façade from a method").
+
+- 708556c: Policy engines check nested writes. A create, update or upsert whose data writes a relation through a directive
+  (`$create`, `$connect`, `$connectOrCreate`, `$update`, `$upsert`, `$delete`, `$disconnect`, `$set`) now runs under a
+  policy, where before it was refused. It runs as one adapter call inside the write's interactive transaction, and one
+  failed check rolls the whole write back with `403 A4002`.
+
+  - Every row the nested write creates is read back as stored (its parent's reference filled, database defaults
+    present) and asked `can({ action: "create", row })`, its `exists` lookups seeing the rows the same call wrote. A
+    create whose own data holds a nested write is asked about its row the same way, after the insert.
+  - A row a directive links or unlinks is held to the scope of the row that changes: a linked row that holds the
+    reference (a to-many relation's rows, the back end of a one-to-one, a many-to-many relation's rows) must be in its
+    update scope, one whose parent holds the reference (a to-one relation's target) in its read scope. One `exists`
+    per Resource answers it, inside the transaction. A linked row that changes is an update: after the call it gets
+    the after check (`can({ action: "update", row })`) and the move-out re-read. Linking a new row to a one-to-one's
+    back end unlinks the old one, which is held the same way.
+  - A to-many nested `$update` or `$delete` acts only on the rows within the update (or delete) scope, as
+    `update.many` and `delete.many` do: core reads those rows' identifiers inside the transaction and hands the
+    adapter `where: { id: { in: [...] } }`. A to-one one refuses the write when its row is outside the scope. A nested
+    `$update`'s changed rows get the after check and the move-out re-read after the call.
+  - The fields a nested record sends are held to its Resource's `fieldsOf({ access: "write" })`, and a relation written
+    through a directive to the parent's grant, its reference fields with it.
+  - Where the operation's `transactionsStyle` is `"none"`, a nested write under a policy is refused before it runs.
+
+- 3a0dfca: A write the policy checks costs fewer database round trips. What each check decides and refuses is unchanged.
+
+  - A single-row update or delete carries the caller's scopes inside its own `where` and runs as one statement, with no
+    read of its row before it. One that matches nothing still answers `A4002` when the caller can read the row and
+    `A2003` when it cannot, with one lookup on that miss only. The Prisma adapter sends it as
+    `update({ where: { id, AND: [scope] } })`.
+  - A create asks `can({ action: "create", row })` and its `exists` lookups before the insert, without a transaction. A
+    transaction around them never closed the race between the lookup and the insert at the database's default
+    isolation, and cost a BEGIN and a COMMIT.
+  - A transaction opens only when a check after the write may roll it back: an update's after check or move-out, a
+    created row held to a write grant, a nested write, or returned rows checked by `exists`. A plain checked create or
+    delete is one statement, its interceptors and hooks outside any transaction.
+  - The after check asks `can` about the row the update returned, so it reads nothing again. Only a move-out reads the
+    changed rows again. An `update.count` runs as the returning `update.many` when the Contract offers it.
+
+  Round trips per request on PostgreSQL: `create.one` 3 → 1, `delete.unique` 4 → 1, `update.unique` 5 → 3,
+  `update.many` 4 → 3, `update.count` 5 → 3. Reads, and a Framework without a policy, are unchanged.
+
+- 99169d2: Policy engines, reads first. `createFramework` takes an optional root `policy: { engine, principal }`: an engine that
+  answers three questions (`can`, `scopeOf`, `fieldsOf`, each now or as a promise), and a function that derives a
+  request's principal from its `ctx.$state`. Core never imports an engine; one satisfies `AvPolicyEngine` by its shape,
+  and a scope or grant is a fragment of Aventara's own `where` (`AvPolicyWhere`).
+
+  - Client and agent requests are checked (an MCP tool call is an agent request). An application call is checked only
+    when it names a principal: `framework.application.Note.find.many(args, { as: user })`. A call a stage makes through
+    `ctx` never is.
+  - Before any guard, `can` and the fields the request names or receives (`fieldsOf`); a refusal is `403 A4002`. At the
+    adapter call, after every developer stage, the read scope is ANDed into the root `where`, every to-many include and
+    its `$count`, and every relation filter, at every level. A to-one include of a row out of scope refuses the request;
+    it is never nulled.
+  - Governed fields (the engine's `governed` list) are left out of every default projection and carry `governed: true`
+    in the Contracts. Name one to get it: `select: ["$defaults", "email"]`, where `$defaults` is the level's default
+    projection. It is refused where a returned row does not grant it, and a filter or sort by it is checked before the
+    query runs, so it cannot reveal values the caller may not read.
+  - The engine's `governed` and `paths` lists are checked against the Core Contract at startup. A rule's paths are lists
+    of segments, as other paths in core are: `["Note", "campaign", "members", "some", "userId", "equals"]`.
+  - Writes are checked as well; see the policy writes entry.
+
+  Without `policy`, nothing changes: the Contracts and their hashes are the same bytes.
+
+- 0fd2608: A write the policy checks costs less CPU after the round-trip changes. The operation core hands its adapter no longer
+  carries the request's policy session, so an adapter that keeps its operations no longer keeps each request's session
+  with them. The fields a write returns only for the after check are dropped as soon as the check has read them, so a
+  read compute stage is told the row the request asked for, not every scalar field. What each check decides, the
+  fields `can` is asked about, and the database round trips are unchanged.
+- 154e440: Policy engines check writes. Every create, update, delete and upsert a client or agent makes (or an application call
+  made `{ as }` a principal) is now checked by the configuration's `policy`, where before it was refused.
+
+  - The fields a write sends are held to `fieldsOf({ access: "write" })` before any guard; a field outside it answers
+    `403 A4002`. A field writable on some rows only is checked against every row an update reaches, and against the
+    row a create inserts, after the insert and inside its transaction.
+  - A create asks `can({ action: "create", row })` about each new row on its final data. Its rules can look rows up
+    through `exists`, which runs inside the write's transaction, so a plan that creates a campaign and then its first
+    note sees the campaign.
+  - An update or delete acts only on rows the caller may both change (`scopeOf` for the action) and read. A single-row
+    one that matches nothing answers `A4002` when the caller can read the row, and `A2003` when it cannot, so the
+    answer does not reveal that the row exists. A `many` or `count` one answers for the caller's rows only.
+  - An update that moves a row out of what the caller reads is rolled back with `A4002`. So is one that fails an `after`
+    condition: inside the transaction core asks `can({ action: "update", row })` about each changed row of every
+    checked update. The engine's new `afterChecks` member (`{ Note: ["update"] }`) names the updates whose grants carry
+    such a condition, which are the ones refused where there is no interactive transaction.
+  - Where the operation's `transactionsStyle` is `"interactive"`, a checked write runs in a transaction of its own. Where
+    it is `"none"` (Cloudflare D1), a write that can only be checked after it runs is refused before it runs; every other
+    write runs, a create looking up before it inserts, and an unlisted update without the after check.
+  - Nested writes (a relation directive in a write's data) are refused under a policy for now.
+
+  `afterChecks` is checked against the Core Contract at startup and changes no Contract and no prebuilt fingerprint.
+
+- 2fcffdb: Prebuilt Contracts. `createFramework` takes an optional `prebuilt` key: the four Contracts compiled ahead of time (type
+  `AvPrebuiltContracts`), so a serverless or edge cold start loads them instead of compiling them. A file is used only
+  when this core compiled it, for this protocol, from the same configuration and adapter model; its Contracts, hashes
+  and `/_contract` bytes are then the ones compiling would give. Any other file is ignored whole: the framework compiles
+  at startup exactly as without one and warns once (`AVENTARA_PREBUILT_STALE`), naming the Resources whose configuration
+  or model changed, or the version that differs. Without `prebuilt`, nothing changes. The build step that writes the
+  file arrives with `@aventara/build`.
+
 ## 1.0.0-rc.3
 
 ### Patch Changes
@@ -27,7 +257,7 @@
   on an `AvComputedValueError`, with nothing of the hidden field in the answer. Before, a shaped Json field hidden from
   the layer was not judged at all, and a hidden field's own validators answered the caller `A2004` with an issue at the
   hidden field's path. A layer that shows the field still answers `A2004` at it.
-- b38034d: On PostgreSQL, a `@unique` value too long for its index (an index row past the B-tree's 8191 bytes, SQLSTATE
+- b38034d: On PostgreSQL, a `@unique` value too long for its index (an index row past the B-tree's limit of about 2704 bytes, SQLSTATE
   `54000`) is answered `422 A2004`, not `500 A3001`: one `V1004` issue at `["arguments"]`, as a value too long for its
   column already was. The adapter reads the SQLSTATE, never the message. The issue's message for a value too long now
   reads `The database refused this value: it is longer than the database can hold for its column.`

package/ERRORS.md

@@ -1,6 +1,6 @@
 # Aventara error codes
 
-Every code `@aventara/core` 1.0.0-rc.3 answers, reports in a validation issue, or refuses to start with. Generated from `AvErrorCatalog` (exported by `@aventara/core`); do not edit.
+Every code `@aventara/core` 1.0.0-rc.8 answers, reports in a validation issue, or refuses to start with. Generated from `AvErrorCatalog` (exported by `@aventara/core`); do not edit.
 
 Branch on the code, never on the message. In code, `AvErrorCatalog[code]` gives the same entry: `{ code, kind, message, cause, fix, docs }`.
 
@@ -30,7 +30,7 @@ The caller can fix these. The generated client and server-side calls throw the c
 | [`A2000`](https://aventara-framework.vercel.app/docs/error-codes#a2000) | Invalid request. | The HTTP request cannot be interpreted: malformed JSON, a body that is not a JSON object, an unknown `/_*` path, a body that does not decode in its Content-Encoding, or a missing Aventara-Protocol-Version or Aventara-Contract-Hash header (the message names it). | Send a JSON object with both identity headers. The generated client does this for you. |
 | [`A2001`](https://aventara-framework.vercel.app/docs/error-codes#a2001) | Unknown Resource. | The Resource is not in the caller's contract: misspelt, hidden by exposure, or added to the schema after aventara:prepare last ran. cause.message is "The requested Resource is not available." and the issue is V1005 at `["resource"]`. | Use the model's exact name. After a schema change run the adapter's generate step (`npm run aventara:prepare` in a scaffolded project), restart, and regenerate the client. A Resource hidden on purpose is reached from server code (framework.application). |
 | [`A2002`](https://aventara-framework.vercel.app/docs/error-codes#a2002) | Unknown operation. | The operation is not available on that Resource: a typo, removed by exposure, an operation the adapter does not offer (such as delete.many), or a ctx.$sql, appTx.$sql or ctx.$transaction the adapter or the layer cannot run. The issue is V1006 at `["family"]` or `["variant"]`. | Call an operation the contract lists (`GET <api>/_contract`), regenerate a stale client, and check the layer's exemptions and transactionsStyle. |
-| [`A2003`](https://aventara-framework.vercel.app/docs/error-codes#a2003) | Not found. | A unique operation (find.unique, update.unique, delete.unique) matched no row, or a $connect names a record that does not exist. The operation fails, so no after hook runs. | Catch AvNotFoundError, or use a first-style operation, which answers A1001 with null. Check the $connect identifier. |
+| [`A2003`](https://aventara-framework.vercel.app/docs/error-codes#a2003) | Not found. | A unique operation (find.unique, update.unique, delete.unique) matched no row, or a $connect names a record that does not exist. The operation fails, so no after hook runs. Under a policy, a row outside the caller's read scope is a miss too, and so is a single-row update or delete of a row the caller cannot read, so the answer does not reveal that the row exists. A row the caller can read but not change answers A4002. | Catch AvNotFoundError, or use a first-style operation, which answers A1001 with null. Check the $connect identifier. |
 | [`A2004`](https://aventara-framework.vercel.app/docs/error-codes#a2004) | Validation failed. | The arguments break a contract rule or a field validator. cause.issues lists each problem by V-code and path; a validator's issue also has check and params. The validators judge the values after the pipes and write compute, so a computed value they refuse is here too, at its field. A required create field left out is here (V1000). So is a value the database itself refused: too long for its column or its index, or out of its range (V1004), or holding a character it cannot store or a pattern it cannot read (V1001), with the issue at `["arguments"]`, or at the value where the adapter can place it (a bigint its driver cannot bind), and its message saying what the database refused. So is a record written through a relation that writes that relation, or a field holding its reference, back (V1012, at that field), where the adapter admits no such write. | Fix the argument each issue's path points at, as its V-code says. A field the server must fill takes a compute.create stage. For a value the database refused, send one its column holds. For a nested write that writes its relation back, leave that field out: the parent supplies it. |
 | [`A2005`](https://aventara-framework.vercel.app/docs/error-codes#a2005) | Contract mismatch. | The caller's Aventara-Contract-Hash is not the server's current one: the schema, the configuration, the limits or the exposure changed, or the client targets another deployment. | Regenerate the client against the running server: `npm run avclient:generate`. |
 | [`A2006`](https://aventara-framework.vercel.app/docs/error-codes#a2006) | Protocol mismatch. | Aventara-Protocol-Version is not 1. | Send `Aventara-Protocol-Version: 1`, or upgrade the client. |
@@ -63,7 +63,7 @@ Produced by your guards; the framework never authenticates by itself.
 |---|---|---|---|
 | [`A4000`](https://aventara-framework.vercel.app/docs/error-codes#a4000) | Unauthenticated. | A guard threw new AvError("A4000", ...): authentication is required or failed. The framework never authenticates by itself. | Send the credentials your guards expect, such as the Authorization header. |
 | [`A4001`](https://aventara-framework.vercel.app/docs/error-codes#a4001) | Forbidden. | A guard returned false ("Operation denied by a framework guard."), a field write guard or a nested write's target guard included, or a stage threw A4001. | Call as a caller the guard admits, or stop sending the guarded field. To answer another code, throw an AvError from the guard. |
-| [`A4002`](https://aventara-framework.vercel.app/docs/error-codes#a4002) | Policy denied. | A guard or hook threw new AvError("A4002", ...) with a policy reason of your own. | Read cause.message for the policy's reason. |
+| [`A4002`](https://aventara-framework.vercel.app/docs/error-codes#a4002) | Policy denied. | The configuration's policy refused the request: its engine does not allow the operation, a field the request names, writes or returns, a row it reaches, a row it creates, or the row a change leaves (moved out of what the caller reads, or failing its grant's after condition, which rolls the write back); on a database without interactive transactions, a write the policy can only check after it runs; or a stage threw new AvError("A4002", ...). | Read cause.message, which names what the policy refused. Call as a principal the policy allows, leave the refused field or relation out (a governed one is named only where every row grants it), or change only rows the caller may change and still read afterwards. |
 
 ## Validation issues (V1xxx)
 
@@ -100,10 +100,10 @@ Each entry of `cause.issues[]` under `A2001`, `A2002`, `A2004`, `A2007` or `A200
 
 | Code | Meaning | Cause | Fix |
 |---|---|---|---|
-| [`CONFIG_REQUIRED`](https://aventara-framework.vercel.app/docs/error-codes#config_required) | A required configuration key is missing. | A key that must be present is absent: api, adapter, or an overlay's exposed when the overlay sets exemptions. | Add the key at the diagnostic's path. |
-| [`CONFIG_UNKNOWN_PROPERTY`](https://aventara-framework.vercel.app/docs/error-codes#config_unknown_property) | Unknown configuration key. | A key the configuration does not define at that place: a typo, or a key written at the wrong level of the tree. | Remove it, or move it where it belongs (the configuration reference's "Where a key can go"). |
+| [`CONFIG_REQUIRED`](https://aventara-framework.vercel.app/docs/error-codes#config_required) | A required configuration key is missing. | A key that must be present is absent: api, adapter, or an overlay's exposed when the overlay sets exemptions, or policy.engine or policy.principal when policy is set. | Add the key at the diagnostic's path. |
+| [`CONFIG_UNKNOWN_PROPERTY`](https://aventara-framework.vercel.app/docs/error-codes#config_unknown_property) | Unknown configuration key. | A key the configuration does not define at that place: a typo, or a key written at the wrong level of the tree. `policy` and `prebuilt` are root-only keys; in an overlay they read as unknown. | Remove it, or move it where it belongs (the configuration reference's "Where a key can go"). |
 | [`CONFIG_INVALID_TYPE`](https://aventara-framework.vercel.app/docs/error-codes#config_invalid_type) | A configuration key has the wrong type. | A value of the wrong type, or a key set to an explicit undefined. | Give the value the type the reference states; leave a key out rather than setting it to undefined. |
-| [`CONFIG_INVALID_VALUE`](https://aventara-framework.vercel.app/docs/error-codes#config_invalid_value) | A configuration value is not allowed. | A malformed api or mcp path, a negative limit, an unknown transactionsStyle, a format that is not a named zod format, or forceTransaction under an effective transactionsStyle "none". | Use a value the message allows. |
+| [`CONFIG_INVALID_VALUE`](https://aventara-framework.vercel.app/docs/error-codes#config_invalid_value) | A configuration value is not allowed. | A malformed api or mcp path, a negative limit, an unknown transactionsStyle, a format that is not a named zod format, forceTransaction under an effective transactionsStyle "none", an after check on any action but update, or a policy engine's governed, paths or afterChecks naming a Resource, field or path the Core Contract does not have (the message names the Resource or the rule). | Use a value the message allows. |
 | [`CONFIG_MOVED_PROPERTY`](https://aventara-framework.vercel.app/docs/error-codes#config_moved_property) | A configuration key moved in rc.1. | Configuration written for 1.0.0-rc.0: restrictions, entrypoint, fields, behaviors, transactions or pipelines.before/after. | Move it where the message says: restrictions to exposed + exemptions, entrypoint to api, fields to `resources.<R>.fields.<f>.definition`, transactions to transactionsStyle, before/after to pipelines.hooks. |
 | [`CONFIG_FORBIDDEN_IN_OVERLAY`](https://aventara-framework.vercel.app/docs/error-codes#config_forbidden_in_overlay) | A root-only key is written in an overlay. | A field definition in application, client or agent. | Define the field once at the root (`resources.<R>.fields.<f>.definition`); an overlay only chooses its visibility. |
 

package/README.md

@@ -170,10 +170,8 @@ 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: a whole surface (`AvApplicationFacade`), one Resource
-(`AvApplicationResourceFacade`), one family (`AvApplicationFamilyFacade`), and the same three for `client`, `appTx` and
-`clientTx` (`AvClientFacade`, `AvAppTxResourceFacade`, …). The declaration writes the name, with the Contract view as
-its argument, so this compiles:
+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()
@@ -183,21 +181,43 @@ export class PostsService {
   posts() {
     return this.framework.application.Post;
   }
+
+  findMany() {
+    return this.framework.application.Post.find.many;
+  }
 }
 ```
 
-The view is written out in full, about 400 KB of declaration per such method over 50 Resources. Give the method a
-return type to keep it small: `AppFramework["application"]["Post"]` is written as that reference, about 0.2 KB.
+The declaration file writes a short reference, under half a kilobyte per method at any schema size:
 
 ```ts
-posts(): AppFramework["application"]["Post"] {
-  return this.framework.application.Post;
-}
+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" }>;
 ```
 
-A variant (`this.framework.application.Post.find.many`) is a call type the declaration cannot name: give that method a
-return type, or return the call's result, whose row type is small. An application that publishes no declarations can
-set `"declaration": false` and skip the question.
+The names, one set per surface (`application`, `client`, `appTx`, `clientTx`):
+
+| Node | `framework.application` | the others |
+| --- | --- | --- |
+| the whole surface | `AvApplicationFacade` | `AvClientFacade`, `AvAppTxFacade`, `AvClientTxFacade` |
+| one Resource | `AvApplicationResourceFacade` | `AvClientResourceFacade`, … |
+| one family | `AvApplicationFamilyFacade` | `AvClientFamilyFacade`, … |
+| a variant that takes a `select` or `include` | `AvApplicationProjectingCall` | `AvClientProjectingCall`, `AvAppTxProjectingCall`, `AvClientTxProjectingCall` |
+| a variant that does not (the `count` variants: `find.count`, `update.count`, …) | `AvApplicationPlainCall` | `AvClientPlainCall`, `AvAppTxPlainCall`, `AvClientTxPlainCall` |
+
+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
@@ -310,6 +330,50 @@ It compiles to `framework.contracts.agent`, identified by its own hash, and `fra
 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. 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. 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.
+
 ## License
 
 PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you

package/dist/adapters/adapter-field.d.ts

@@ -38,6 +38,14 @@ export type AvAdapterRelationField<M extends AvAdapterModel> = {
      * one. Absent on the end that holds no reference (`User.posts`); never empty.
      */
     readonly referenceFields?: readonly [string, ...string[]];
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in
+     * the same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`, so `Post.authorId` holds `User.id`). Stated only
+     * beside `referenceFields`, with as many entries; absent on the end that
+     * holds no reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
 };
 /** One field the adapter discovered: a scalar or a relation. */
 export type AvAdapterField<M extends AvAdapterModel> = AvAdapterScalarField<M> | AvAdapterRelationField<M>;

package/dist/adapters/adapter-identifier.d.ts

@@ -13,3 +13,12 @@ export type AvAdapterIdentifier<TFields extends Readonly<Record<string, AvAdapte
     AvAdapterScalarFieldKey<TFields>,
     ...AvAdapterScalarFieldKey<TFields>[]
 ];
+/**
+ * The Resource's identifier as the Adapter states it first: in the Adapter's
+ * own order (an ORM adapter's is its schema's, so the primary key). The Core
+ * Contract sorts identifiers for its hash, so its first one is the
+ * alphabetically first (`email` before `id`) and says nothing about which is
+ * the primary key; the model keeps the order it declared. Empty for a Resource
+ * the model does not hold or that has no identifier.
+ */
+export declare function adapterPrimaryIdentifier(model: AvAdapterModel, resource: string): readonly string[];

package/dist/adapters/adapter-identifier.js

@@ -1 +1,6 @@
-export {};
+export function adapterPrimaryIdentifier(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : undefined) ?? []);
+}

package/dist/adapters/adapter-operation.d.ts

@@ -5,6 +5,19 @@ import type { AvAdapterModel } from "./adapter-model.js";
  * Provider execution request after framework semantic validation.
  * Operation identity and arguments remain provider-neutral; adapters receive
  * only validated semantic argument objects, never raw transport input.
+ *
+ * Two shapes exist here only, both an `AND`: a list of conditions in the
+ * general `where` grammar the addressed row must also meet.
+ *
+ * - The flat unique selector of an `update.unique` or a `delete.unique` may
+ *   carry it. A row the selector names that misses them is a miss (the same
+ *   `null` as a row that is not there).
+ * - A `cursor` may carry it, at the root of a `find.many` and in a to-many
+ *   relation's arguments. A row the cursor names that misses them is a cursor
+ *   that names no row: the same answer as a cursor on a row that is not there.
+ *
+ * An adapter must honour it or refuse the operation, never drop it: dropping it
+ * would write a row the conditions exclude, or position a page at one.
  */
 export type AvAdapterOperation<M extends AvAdapterModel = AvAdapterModel> = AvOperationIdentity & {
     readonly resource: Extract<keyof M["resources"], string>;

package/dist/compiler/contract.compiler.d.ts

@@ -30,3 +30,9 @@ export type ContractCompilationResult = {
  * Agent Contract from the view of the layer it extends.
  */
 export declare function compileContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;
+/**
+ * Binds Contracts loaded from a prebuilt file to the runtime pieces
+ * {@link compileContracts} binds to the ones it compiles, from the live
+ * `config` and `model` they were compiled from.
+ */
+export declare function bindPrebuiltContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>, contracts: AvContracts): void;