@aventara/core 1.0.0-rc.2 → 1.0.0-rc.4

package/CHANGELOG.md

@@ -1,5 +1,180 @@
 # @aventara/core
 
+## 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
+
+- b38034d: An issue inside one entry of a to-many relation directive's array names that entry's index:
+  `["arguments", "data", "posts", "$update", 1, "data", "category"]`, where it read `[…, "$update", "data", "category"]`.
+  This holds for `$create`, `$connect`, `$connectOrCreate`, `$update`, `$delete`, `$upsert`, `$set` and `$disconnect`,
+  as the runtime's own nested-write paths already did. A directive given one object, not an array, keeps its issue at the
+  directive.
+- b38034d: An empty boolean node in the `where` of a write is refused, as an `undefined` there is, and nothing runs. In
+  `update.many`, `update.count`, `update.first`, `delete.many`, `delete.count`, `delete.first` and a to-many `$update`
+  or `$delete`, an empty `NOT: {}`, `AND: {}` or `[]`, `OR: []` or `AND`/`OR` entry `{}`, at any depth, answers
+  `422 A2004` with a `V1001` issue at the node:
+  `A boolean node must hold a condition here: an empty one matches every row, and the write would reach more rows.`
+  The ORM reads these as no condition, so `delete.count({ where: { NOT: {} } })` deleted every row, and `delete.first`
+  with one deleted an arbitrary row. A `where` that is `{}` itself still means every row, and reads pass empty nodes through as before. Field filters are unchanged: a scalar's `{}` and a
+  to-many relation's `{}` were already refused, and a to-one relation's `{}` matches the rows that have a related row.
+- b38034d: The error catalog (`AvErrorCatalog`, `ERRORS.md`) catches up with the code: `A2004` says a value the database refused
+  may stand at the value itself where the adapter can place it (a bigint its driver cannot bind) and may be too long for
+  its index; `V1001` lists an `undefined` in a filter, selector or cursor and an empty boolean node in a bulk write's
+  `where`; `V1004` lists a value the database refused as too long or out of range, a bigint a driver cannot bind among
+  them.
+- b38034d: A value write compute writes to a field the caller's layer hides is judged by that field's validators and Json shape
+  (the Core Contract's), and a value they refuse is the server's error: `500 A3000`, the issues to the `diagnostics` sink
+  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 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.`
+  (it said `longer than its column can hold`, which an index refusal is not).
+- b38034d: A Pick layer's list entry that names what its parent hid is refused with the sentence written inline too. Inline in
+  `createFramework` or `AventaraModule.forRoot`, the error is at the key and reads:
+
+  ```text
+  Type '["select"]' is not assignable to type '…'.
+    …
+      Property '"Error: client cannot expose 'Post.internalNote': hidden by root"' is missing in type '["select"]' but required in type '{ readonly "Error: client cannot expose 'Post.internalNote': hidden by root": true; }'.
+  ```
+
+  where it ended at `Type 'string' is not assignable to type 'never'.` at the list's element. A list entry is now typed as
+  an object keyed by the sentence, which no list has, so a configuration that is not inline (an `aventaraConfig()` handed
+  to `AventaraModule.forRootAsync`) ends at the same `Property '"Error: …"' is missing` line, where it ended at
+  `Type '"select"' is not assignable to type '"Error: …"'`. An entry written `true` or as an object is unchanged.
+
 ## 1.0.0-rc.2
 
 ### Patch Changes

package/ERRORS.md

@@ -1,6 +1,6 @@
 # Aventara error codes
 
-Every code `@aventara/core` 1.0.0-rc.2 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.4 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,8 +30,8 @@ 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. |
-| [`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 out of its range (V1004), or holding a character it cannot store or a pattern it cannot read (V1001), with the issue at `["arguments"]` 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. |
+| [`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. |
 | [`A2007`](https://aventara-framework.vercel.app/docs/error-codes#a2007) | Invalid transaction reference. | A transaction $ref or fingerprint is invalid: the issues are V1010, V1011, V1016, V1017 or V1018, and cause.operation is the step. A $ref with no fingerprint is A2004 / V1000. | Let the generated client or framework.appTx build plans; check the $ref path and that the referenced step comes earlier. |
@@ -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)
 
@@ -72,10 +72,10 @@ Each entry of `cause.issues[]` under `A2001`, `A2002`, `A2004`, `A2007` or `A200
 | Code | Meaning | Cause | Fix |
 |---|---|---|---|
 | [`V1000`](https://aventara-framework.vercel.app/docs/error-codes#v1000) | Required value missing. | A required value is absent: a create leaves out a required field that has no database default and no compute.create (the path names the field), a required relation and its reference field are both missing, a typed Json field lacks a required key, or a $ref has no fingerprint. | Send the value at the issue's path. When the server must fill it, give the field a compute.create stage or a database default; a pipe cannot fill it. |
-| [`V1001`](https://aventara-framework.vercel.app/docs/error-codes#v1001) | Invalid runtime/wire type. | A value of the wrong type: a string where a number is expected, a negative limit, a non-integer id, null given to an operator with no null meaning (gt, contains, in), two directives in one scalar action object (`{ $increment: 1, $decrement: 2 }`), or a server-side value that is not plain data. | Send the type the contract states at that path (the generated client's types say it). |
+| [`V1001`](https://aventara-framework.vercel.app/docs/error-codes#v1001) | Invalid runtime/wire type. | A value of the wrong type: a string where a number is expected, a negative limit, a non-integer id, null given to an operator with no null meaning (gt, contains, in), two directives in one scalar action object (`{ $increment: 1, $decrement: 2 }`), or a server-side value that is not plain data. Also a value that would make the call reach more rows: `undefined` in a filter, a unique selector or a cursor, an empty boolean node (`NOT: {}`, `AND: []`, `OR: []`) in the where of a write (update or delete many, count or first, a to-many $update or $delete). | Send the type the contract states at that path (the generated client's types say it). |
 | [`V1002`](https://aventara-framework.vercel.app/docs/error-codes#v1002) | Invalid enum value. | A value that is not a member of the enum, or outside a typed Json field's AvZ.enum or AvZ.literal. | Send one of the enum's members. |
 | [`V1003`](https://aventara-framework.vercel.app/docs/error-codes#v1003) | Invalid format (for example UUID/DateTime/base64). | A malformed datetime, decimal, base64 or UUID string, or a failed pattern or format validator (`check: "string_format"`). | Send the canonical encoding (ISO-8601 UTC datetime, decimal string, base64 bytes) and satisfy the validator that check and params name. |
-| [`V1004`](https://aventara-framework.vercel.app/docs/error-codes#v1004) | Value outside accepted range. | A number, length or size outside its range: a failed bound, length or size validator, a BigInt outside signed 64 bits, an AvZ.int() outside the safe integer range, or a transaction with no operations. | Send a value inside the range; check and params name the validator that failed. |
+| [`V1004`](https://aventara-framework.vercel.app/docs/error-codes#v1004) | Value outside accepted range. | A number, length or size outside its range: a failed bound, length or size validator, a BigInt outside signed 64 bits, an AvZ.int() outside the safe integer range, or a transaction with no operations. Under A2004 it is also a value the database refused as too long or out of its range, a BigInt beyond what the data source's driver can bind among them (some bind at most ±(2^53 − 1)). | Send a value inside the range; check and params name the validator that failed. |
 | [`V1005`](https://aventara-framework.vercel.app/docs/error-codes#v1005) | Unknown or inaccessible field. | A field that does not exist or is hidden in the caller's layer, an unknown Resource (under A2001), or a key a typed Json field's shape does not declare. | Use a field the caller's contract exposes, expose it through exemptions, or make the call from server code. |
 | [`V1006`](https://aventara-framework.vercel.app/docs/error-codes#v1006) | Unsupported filter/order/mutation directive. | An operator, directive or nested write the field does not offer (at any depth, inside not too; a to-many $update's data takes only what a bulk write takes), a mode it does not offer, or an operation that is not available (under A2002). | Use what the contract lists for that field or Resource, or expose it through exemptions. |
 | [`V1007`](https://aventara-framework.vercel.app/docs/error-codes#v1007) | Invalid unique identifier shape. | The where of a unique operation is not exactly one complete identifier. | Pass exactly one identifier: the id, or every field of one @unique or @@unique. |
@@ -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,46 @@ 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" })`. 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-operation.d.ts

@@ -5,6 +5,13 @@ 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.
+ *
+ * One shape exists here only: the flat unique selector of an `update.unique` or
+ * a `delete.unique` may carry `AND`, a list of conditions in the general
+ * `where` grammar the selected row must also meet. A row the selector names
+ * that misses them is a miss (the same `null` as 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.
  */
 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;

package/dist/compiler/contract.compiler.js

@@ -1002,6 +1002,7 @@ function projectCore(model, config, diagnostics) {
     baseline.transactions = resolveTransactions(model, "root", scope, diagnostics);
     checkResourceTree(model, baseline, "root", config.trees.root, config.definitions, diagnostics);
     applyFieldDefinitions(model, baseline, config.definitions, diagnostics);
+    markGovernedFields(baseline, config.policy?.governed);
     applyCompute(baseline, scope.compute);
     checkLayerValidators(baseline.resources, "root", config.trees.root, diagnostics);
     const validators = compileValidatorTable(baseline.resources, scope.pipelines);
@@ -1014,6 +1015,27 @@ function projectCore(model, config, diagnostics) {
     validateProjection(projection, "root", diagnostics);
     return { baseline, projection, validators };
 }
+function markGovernedFields(baseline, governed) {
+    if (governed === undefined) {
+        return;
+    }
+    for (const [resourceName, names] of Object.entries(governed)) {
+        const resource = Object.hasOwn(baseline.resources, resourceName)
+            ? baseline.resources[resourceName]
+            : undefined;
+        if (resource === undefined) {
+            continue;
+        }
+        for (const name of names) {
+            const field = Object.hasOwn(resource.fields, name)
+                ? resource.fields[name]
+                : undefined;
+            if (field !== undefined) {
+                field.governed = true;
+            }
+        }
+    }
+}
 function projectDerivedScope(model, scopeName, core, parentView, config, diagnostics) {
     const scope = config[scopeName];
     const baseline = cloneValue(core.baseline);
@@ -1095,18 +1117,57 @@ export async function compileContracts(model, config) {
             };
         }
     }
-    bindShapedFields(core, compilerConfig.definitions);
-    bindShapedFields(application, compilerConfig.definitions);
-    bindShapedFields(client, compilerConfig.definitions);
-    bindShapedFields(agent, compilerConfig.definitions);
-    bindFieldValidators(core, coreCompilation.validators);
-    bindFieldValidators(application, applicationProjection.validators);
-    bindFieldValidators(client, clientProjection.validators);
-    bindFieldValidators(agent, agentProjection.validators);
-    return {
-        ok: true,
-        contracts: { core, application, client, agent },
-    };
+    const contracts = { core, application, client, agent };
+    bindRuntimePieces(contracts, compilerConfig.definitions, {
+        core: coreCompilation.validators,
+        application: applicationProjection.validators,
+        client: clientProjection.validators,
+        agent: agentProjection.validators,
+    });
+    return { ok: true, contracts };
+}
+function bindRuntimePieces(contracts, definitions, validators) {
+    for (const origin of ["core", "application", "client", "agent"]) {
+        bindShapedFields(contracts[origin], definitions);
+        bindFieldValidators(contracts[origin], validators[origin]);
+    }
+}
+export function bindPrebuiltContracts(model, config, contracts) {
+    const compilerConfig = config;
+    const fields = validatedFieldsView(model, compilerConfig.definitions);
+    bindRuntimePieces(contracts, compilerConfig.definitions, {
+        core: compileValidatorTable(fields, compilerConfig.root.pipelines),
+        application: compileValidatorTable(fields, compilerConfig.application.pipelines),
+        client: compileValidatorTable(fields, compilerConfig.client.pipelines),
+        agent: compileValidatorTable(fields, compilerConfig.agent.pipelines),
+    });
+}
+function validatedFieldsView(model, definitions) {
+    const resources = { ...model.resources };
+    for (const [resourceName, resourceDefinitions] of Object.entries(definitions)) {
+        const resource = Object.hasOwn(model.resources, resourceName)
+            ? model.resources[resourceName]
+            : undefined;
+        if (resource === undefined) {
+            continue;
+        }
+        let added;
+        for (const [fieldName, definition] of Object.entries(resourceDefinitions)) {
+            if (Object.hasOwn(resource.fields, fieldName)) {
+                continue;
+            }
+            added ??= {};
+            added[fieldName] = {
+                kind: "scalar",
+                type: definition.type,
+                list: definition.list,
+            };
+        }
+        if (added !== undefined) {
+            resources[resourceName] = { fields: { ...resource.fields, ...added } };
+        }
+    }
+    return resources;
 }
 async function identifiedContract(projection) {
     const members = canonicalizeContractMembers({

package/dist/config/computed-fields.js

@@ -1,3 +1,4 @@
+import { emitFrameworkWarning } from "../runtime/framework-warning.emitter.js";
 import { computeOfLayer } from "./field-compute.resolver.js";
 function layerComputedFields(resources) {
     const result = {};
@@ -68,13 +69,5 @@ export function warnOnStaleComputedFields(generated, configured) {
     const message = `generated types are stale: run aventara:prepare. The computed fields the pre-compute stages are typed with differ from the configuration's:\n${drift
         .map((line) => `  - ${line}`)
         .join("\n")}`;
-    const emitWarning = globalThis.process?.emitWarning;
-    if (typeof emitWarning === "function") {
-        emitWarning(message, {
-            type: "AventaraWarning",
-            code: STALE_GENERATED_TYPES_WARNING,
-        });
-        return;
-    }
-    globalThis.console?.warn(`AventaraWarning: ${message}`);
+    emitFrameworkWarning(message, STALE_GENERATED_TYPES_WARNING);
 }

package/dist/config/config-diagnostic.guidance.js

@@ -1,12 +1,12 @@
 export const CONFIG_DIAGNOSTIC_GUIDANCE = {
     CONFIG_REQUIRED: {
         message: "A required configuration key is missing.",
-        cause: "A key that must be present is absent: api, adapter, or an overlay's exposed when the overlay sets exemptions.",
+        cause: "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.",
         fix: "Add the key at the diagnostic's path.",
     },
     CONFIG_UNKNOWN_PROPERTY: {
         message: "Unknown configuration key.",
-        cause: "A key the configuration does not define at that place: a typo, or a key written at the wrong level of the tree.",
+        cause: "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.",
         fix: 'Remove it, or move it where it belongs (the configuration reference\'s "Where a key can go").',
     },
     CONFIG_INVALID_TYPE: {
@@ -16,7 +16,7 @@ export const CONFIG_DIAGNOSTIC_GUIDANCE = {
     },
     CONFIG_INVALID_VALUE: {
         message: "A configuration value is not allowed.",
-        cause: '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".',
+        cause: '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).',
         fix: "Use a value the message allows.",
     },
     CONFIG_MOVED_PROPERTY: {

package/dist/config/config.resolver.d.ts

@@ -1,6 +1,7 @@
 import type { AvAdapter } from "../adapters/adapter.interface.js";
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvTransactionCapability } from "../contracts/transaction-capability.js";
+import type { AvPolicyEngine } from "../policy/policy-engine.js";
 import type { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
 import type { AvMisuseSink } from "../runtime/misuse-reporter.js";
 import type { AvConfigAgentParent } from "./config-layer.js";
@@ -8,6 +9,17 @@ import { type ResolvedComputeConfig } from "./field-compute.resolver.js";
 import type { AvConfig, AvConfigLimits } from "./framework-config.js";
 import type { AvConfigFieldDefinition } from "./framework-field-definition.js";
 import { type ResolvedPipelineTree } from "./pipeline-tree.resolver.js";
+/** The root's `policy`, its engine's passive lists read once. */
+export type ResolvedPolicyConfig = {
+    readonly engine: AvPolicyEngine;
+    readonly principal: NonNullable<AvConfig["policy"]>["principal"];
+    /** The governed fields and relations, by Resource. */
+    readonly governed: Readonly<Record<string, readonly string[]>>;
+    /** The rule paths, by rule name, each a list of segments. */
+    readonly paths: Readonly<Record<string, readonly (readonly string[])[]>>;
+    /** The writes whose grants carry an `after` condition, by Resource. */
+    readonly afterChecks: Readonly<Record<string, readonly string[]>>;
+};
 /** The root's field definitions, by Resource and field name. */
 export type ResolvedFieldDefinitions = Readonly<Record<string, Readonly<Record<string, AvConfigFieldDefinition>>>>;
 /** One resolved layer of the configuration: root, application, client or agent. */
@@ -63,6 +75,8 @@ export type ResolvedFrameworkConfig<M extends AvAdapterModel = AvAdapterModel> =
     readonly diagnostics: AvDiagnosticsSink | undefined;
     /** The misuse sink, from the root configuration only. */
     readonly misuse: AvMisuseSink | undefined;
+    /** The policy, from the root configuration only; absent, nothing is checked. */
+    readonly policy: ResolvedPolicyConfig | undefined;
     /** Every field definition, from the root only; the same for all three layers. */
     readonly definitions: ResolvedFieldDefinitions;
     /** Each layer's `resources` tree as authored: the compiler checks its names. */