@aventara/core 1.0.0-rc.1 → 1.0.0-rc.11

package/ERRORS.md

@@ -0,0 +1,142 @@
+# Aventara error codes
+
+Every code `@aventara/core` 1.0.0-rc.11 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 }`.
+
+## Success codes (A1xxx)
+
+An operation's `code` when it succeeded. The generated client resolves for these.
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`A1000`](https://aventara.razor34.dev/framework/docs/error-codes#a1000) | Success. | A read, a count or another operation without a more specific success code succeeded. | Nothing: the call succeeded. |
+| [`A1001`](https://aventara.razor34.dev/framework/docs/error-codes#a1001) | No match. | A first-style operation (find.first, update.first, delete.first) matched no row; data is null and the generated client resolves null. | Nothing: handle the null result. A unique operation answers A2003 instead. |
+| [`A1002`](https://aventara.razor34.dev/framework/docs/error-codes#a1002) | Created. | create.one created a row. | Nothing: the call succeeded. |
+| [`A1003`](https://aventara.razor34.dev/framework/docs/error-codes#a1003) | Created many. | create.many or create.count created rows. | Nothing: the call succeeded. |
+| [`A1004`](https://aventara.razor34.dev/framework/docs/error-codes#a1004) | Updated. | update.first or update.unique updated a row. | Nothing: the call succeeded. |
+| [`A1005`](https://aventara.razor34.dev/framework/docs/error-codes#a1005) | Updated many. | update.many or update.count updated rows. | Nothing: the call succeeded. |
+| [`A1006`](https://aventara.razor34.dev/framework/docs/error-codes#a1006) | Deleted. | delete.first or delete.unique deleted a row. | Nothing: the call succeeded. |
+| [`A1007`](https://aventara.razor34.dev/framework/docs/error-codes#a1007) | Deleted many. | delete.count deleted rows. | Nothing: the call succeeded. |
+| [`A1008`](https://aventara.razor34.dev/framework/docs/error-codes#a1008) | Upserted. | upsert.unique created or updated a row. | Nothing: the call succeeded. |
+| [`A1009`](https://aventara.razor34.dev/framework/docs/error-codes#a1009) | Transaction committed. | A whole transaction plan committed; data holds one result per step. | Nothing: the plan committed. |
+
+## Request errors (A2xxx)
+
+The caller can fix these. The generated client and server-side calls throw the code's `AvError` subclass.
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`A2000`](https://aventara.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/docs/error-codes#a2006) | Protocol mismatch. | Aventara-Protocol-Version is not 1. | Send `Aventara-Protocol-Version: 1`, or upgrade the client. |
+| [`A2007`](https://aventara.razor34.dev/framework/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. |
+| [`A2008`](https://aventara.razor34.dev/framework/docs/error-codes#a2008) | Conflict. | A uniqueness or reference constraint failed: a duplicate value, a missing parent, or a $disconnect or $set that would orphan a required child (also through update.first or a developer SQL statement). Sending it again unchanged fails the same way. | Change the data. For a duplicate, update the existing row or use upsert.unique. |
+| [`A2009`](https://aventara.razor34.dev/framework/docs/error-codes#a2009) | Limit exceeded. | A contract limit was crossed: nesting depth (V1013), list or plan size (V1014), boolean nodes (V1015) or Json value depth (V1021). | Ask for less (paginate, split the plan), or raise the limit under `limits`. |
+| [`A2010`](https://aventara.razor34.dev/framework/docs/error-codes#a2010) | Payload too large. | The decoded request body exceeds maxRequestBytes (default 1048576). | Send less, or raise limits.maxRequestBytes. |
+| [`A2011`](https://aventara.razor34.dev/framework/docs/error-codes#a2011) | Unsupported media type. | The body is not application/json, or its Content-Encoding is not gzip, deflate or br. | Send `Content-Type: application/json`. |
+| [`A2012`](https://aventara.razor34.dev/framework/docs/error-codes#a2012) | Method not allowed. | The HTTP method does not fit the route; the Allow header names the right one (`POST` on operations and `/_transactions`, `GET` on `/_contract`). | Use the method the Allow header names. |
+| [`A2013`](https://aventara.razor34.dev/framework/docs/error-codes#a2013) | Concurrent modification. | A competing writer reached the state first; nothing was written. | Retry. No retry is automatic. |
+| [`A2014`](https://aventara.razor34.dev/framework/docs/error-codes#a2014) | Stale selection. | The selected state changed before the write; nothing was written. | Read again, then retry. |
+
+## Server errors (A3xxx)
+
+Not caller-actionable: `cause.message` is generic, and the real error goes to the root `diagnostics` sink.
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`A3000`](https://aventara.razor34.dev/framework/docs/error-codes#a3000) | Internal error. | An unexpected failure on the server: a stage threw an error that is not an AvError, an interceptor called next() twice, a compute stage reached a write through its read-only ctx, a compute stage returned a value of the wrong type, or a compute.create returned undefined for a required field. cause.message is always "Internal framework error." | Read the real error in the diagnostics sink (the root `diagnostics` key) or the server log line for the request id, and fix that stage. To answer with a code of your choice, throw an AvError. |
+| [`A3001`](https://aventara.razor34.dev/framework/docs/error-codes#a3001) | Adapter error. | A database or ORM failure that is not something the caller can fix. cause.message is always "Adapter execution failed." | Read the raw error in the diagnostics sink; check the database, its connection and the migration state. |
+| [`A3002`](https://aventara.razor34.dev/framework/docs/error-codes#a3002) | Transaction error. | Transaction infrastructure failed (commit or rollback, or the transaction expired or was closed under a step), or a Resource transaction interceptor called next() twice or resolved without calling it. | Read the diagnostics sink. Call next() exactly once in a transaction interceptor; retry an infrastructure failure. |
+| [`A3003`](https://aventara.razor34.dev/framework/docs/error-codes#a3003) | Serialization error. | A result could not be encoded for transport. | Read the diagnostics sink; make compute.read stages and Json values return plain data of the field's type. |
+| [`A3004`](https://aventara.razor34.dev/framework/docs/error-codes#a3004) | Pipe output invalid. | A server pipe, field pipe or transaction pipe (or write compute) returned arguments the server's own contract refuses: a field the Resource does not have, a wrong type, a dropped required field, a reference written together with its relation (V1012), or a changed plan. cause.message is always "A server pipeline produced invalid arguments." | Read the server log line, which names the pipe, the operation and the path, and fix the pipe. A pipe returns a new object of the same shape, or undefined to keep the arguments. |
+
+## Authentication and authorization (A4xxx)
+
+Produced by your guards; the framework never authenticates by itself.
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`A4000`](https://aventara.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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)
+
+Each entry of `cause.issues[]` under `A2001`, `A2002`, `A2004`, `A2007` or `A2009`: `{ code, path, message }`, plus `check` and `params` for a failed field validator.
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`V1000`](https://aventara.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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. |
+| [`V1008`](https://aventara.razor34.dev/framework/docs/error-codes#v1008) | Invalid select/include/reducer projection. | Both select and include, a write-only field selected, or a relation that is not selectable there. | Use select or include, not both, and select only readable fields. |
+| [`V1009`](https://aventara.razor34.dev/framework/docs/error-codes#v1009) | Invalid or non-deterministic cursor. | A cursor without an explicit orderBy, or cursor keys that do not match the ordered fields. | Give an orderBy and a cursor holding exactly its ordered fields. |
+| [`V1010`](https://aventara.razor34.dev/framework/docs/error-codes#v1010) | Invalid transaction reference path. | A $ref path the earlier step does not return, a $ref to a step that is not in the transaction, or to a step with no single row (a many or count step). | Select the referenced field in the earlier step, and reference a single-row step. |
+| [`V1011`](https://aventara.razor34.dev/framework/docs/error-codes#v1011) | Transaction reference type mismatch. | The referenced value's type does not fit its target, a nullable source where only a non-null value is accepted included. | Reference a field of the target's type, non-null where the target needs it. |
+| [`V1012`](https://aventara.razor34.dev/framework/docs/error-codes#v1012) | Invalid relation action/cardinality. | A nested write that does not fit the relation (a list where one record is expected), a reference field set together with its own relation, one record mixing reference fields and relation writes where the adapter cannot run both, or a record written through a relation that writes that relation (or a field holding its reference) back, where the adapter admits no such write. Also a to-one $update or $upsert beside $connect, $connectOrCreate, $create, $set or $disconnect on the same relation: the row it would update is the newly linked one. | Write either the relation or its reference field, in the relation's cardinality. Relink a to-one relation in one write and update the linked row in another. |
+| [`V1013`](https://aventara.razor34.dev/framework/docs/error-codes#v1013) | Maximum nesting depth exceeded. | Nested projections, filters or writes deeper than maxNestingDepth. | Nest less, or raise limits.maxNestingDepth. |
+| [`V1014`](https://aventara.razor34.dev/framework/docs/error-codes#v1014) | Configured limit exceeded. | A limit above maxListLimit, or more steps than maxTransactionOperations. | Paginate or split the plan, or raise the limit. |
+| [`V1015`](https://aventara.razor34.dev/framework/docs/error-codes#v1015) | Boolean/filter node limit exceeded. | A where tree with more nodes than maxBooleanNodes. | Simplify the filter (in instead of many OR clauses), or raise limits.maxBooleanNodes. |
+| [`V1016`](https://aventara.razor34.dev/framework/docs/error-codes#v1016) | Invalid transaction reference index. | A $ref to the referencing step itself or a later one, or to an index no step has. | Reference an earlier step only. |
+| [`V1017`](https://aventara.razor34.dev/framework/docs/error-codes#v1017) | Transaction fingerprint mismatch. | A hand-written plan whose fingerprint does not match its step. | Let the generated client, framework.appTx or framework.clientTx build the plan. |
+| [`V1018`](https://aventara.razor34.dev/framework/docs/error-codes#v1018) | Transaction reference resolved to no value. | The referenced step returned no value at that path, such as a first step that matched no row. | Make sure the earlier step returns a row, or use a unique step, which fails with A2003. |
+| [`V1019`](https://aventara.razor34.dev/framework/docs/error-codes#v1019) | Transaction step depends on a row removed by an earlier step's cascade | A later step uses a row that an earlier step's delete removed through a database cascade. | Reorder or drop the dependent step. |
+| [`V1020`](https://aventara.razor34.dev/framework/docs/error-codes#v1020) | Transaction mixes application and client steps. | One framework.transaction([...]) list mixes appTx and clientTx steps. | Build every step of a plan from one origin. |
+| [`V1021`](https://aventara.razor34.dev/framework/docs/error-codes#v1021) | Json value depth limit exceeded. | A Json field's value nests deeper than maxJsonDepth. | Flatten the value, or raise limits.maxJsonDepth. |
+
+## Startup: configuration
+
+`createFramework` (and `AventaraModule`) throws one `AvConstructionError` with `stage: "configuration"`; each diagnostic is `{ code, path, message, docs }`.
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`CONFIG_REQUIRED`](https://aventara.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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.razor34.dev/framework/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, or its unheld naming a Resource the data source's model does not have (the message names the Resource or the rule). | Use a value the message allows. |
+| [`CONFIG_MOVED_PROPERTY`](https://aventara.razor34.dev/framework/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.razor34.dev/framework/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. |
+
+## Startup: discovery
+
+`AvConstructionError` with `stage: "discovery"`: what the adapter reported does not hold together.
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH`](https://aventara.razor34.dev/framework/docs/error-codes#discovery_transaction_capability_mismatch) | The adapter's transaction capability does not match it. | The adapter declares interactive transactions but provides no transaction function. | A defect of the adapter: install the adapter release that matches @aventara/core exactly. |
+
+## Startup: contract compilation
+
+`AvConstructionError` with `stage: "contract-compilation"`; a diagnostic's `path` starts with its layer (`root.`, `application.`, `client.`, `agent.`).
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`COMPILER_UNKNOWN_RESOURCE`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_unknown_resource) | Unknown Resource. | A Resource name the adapter's model does not have, in resources or in exemptions; or a client or agent entry for a Resource managed elsewhere, which those layers never have. | Use the model's exact name. After a schema change run `npm run aventara:prepare`. Configure a Resource managed elsewhere at the root or in application only. |
+| [`COMPILER_UNKNOWN_FIELD`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_unknown_field) | Unknown field. | A field that is neither in the schema nor defined at the root. | Fix the name, run aventara:prepare after a schema change, or add the field with a root definition. |
+| [`COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_relation_field_config_unsupported) | A relation field takes write guards only. | Field pipes or compute on a relation field. | Put the stage on the relation's reference field, or use an operation pipe. |
+| [`COMPILER_INCOMPLETE_FIELD`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_incomplete_field) | An added field is incomplete. | A definition that adds a field leaves out type, nullable or list. | Spell out type, nullable and list, with lifecycle: ["VIRTUAL"] for a field that has no column. |
+| [`COMPILER_STRUCTURAL_FIELD_OVERRIDE`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_structural_field_override) | A discovered field's structure was redefined. | A definition on a field the adapter discovered changes its type, format or capabilities. | Restate only its type, nullable and list. Change capabilities through exemptions and the column through the schema. |
+| [`COMPILER_MISSING_SCALAR`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_missing_scalar) | Unknown scalar type. | A definition names a scalar type that does not exist. | Use a built-in scalar: string, boolean, int, float, bigint, decimal, datetime, bytes or json. |
+| [`COMPILER_MISSING_ENUM`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_missing_enum) | Unknown enum. | A definition names an enum the model does not have. | Use an enum of the schema, and run aventara:prepare after adding one. |
+| [`COMPILER_DANGLING_RELATION`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_dangling_relation) | A visible relation points at a hidden Resource. | A layer hides a Resource but still exposes a relation field that targets it. | Hide the relation field too (`exemptions.resources.<R>.fields.<relation>: true`), or expose the target. |
+| [`COMPILER_UNAVAILABLE_OPERATION`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_unavailable_operation) | Operation not available. | An operation the adapter does not offer (such as delete.many), or an overlay granting one that its parent hid. | Remove it. To reach an operation from one overlay only, expose it at the root and hide it in the other overlay. |
+| [`COMPILER_UNAVAILABLE_CAPABILITY`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_unavailable_capability) | Capability not available. | A capability or token the field does not offer, or an overlay (or the agent layer) granting one its parent hid. Overlays only narrow. | Remove it, or expose it in the parent layer and hide it in the layer it must not reach. |
+| [`COMPILER_INVALID_LIFECYCLE`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_invalid_lifecycle) | Invalid field lifecycle. | An added field declares a lifecycle other than VIRTUAL, a VIRTUAL field claims a database-generated lifecycle or a provider-side capability, or a definition redefines a discovered field's lifecycle. | Give an added field lifecycle: ["VIRTUAL"] and only the capabilities it can serve; computed lifecycles come from compute stages. |
+| [`COMPILER_MISSING_READ_COMPUTE`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_missing_read_compute) | A selectable virtual field has no compute.read. | A VIRTUAL field that can be selected has no pipelines.compute.read stage. | Add a compute.read stage, or make the field write-only with capabilities.select: false. |
+| [`COMPILER_INVALID_COMPUTE_DEPENDENCY`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_invalid_compute_dependency) | Invalid compute.read dependency. | A dependsOn entry that is not a stored scalar field of the same Resource. | List only stored scalar fields of the Resource in dependsOn. |
+| [`COMPILER_RESERVED_RESOURCE_NAME`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_reserved_resource_name) | Reserved Resource name. | A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref), or is the name of a member beside the Resources: all on serverClient (and so on Next.js's avClient), and on a host that adds its own, one of those (on Next.js: tx and transaction on avClient, appTx and transaction on avApp). | Rename the model; the table it maps to can keep its name. A host member's name is also left free when the layer it belongs to hides the Resource. |
+| [`COMPILER_MISSING_IDENTIFIER`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_missing_identifier) | A unique operation has no identifier. | A layer exposes a unique variant (find.unique, update.unique, delete.unique, upsert.unique) and no complete identifier of the Resource: a Pick that did not pick one, or an Omit that hid every one. | Expose an identifier field (id, or every field of one unique), or exempt the unique variants. |
+| [`COMPILER_HIDDEN_REQUIRED_FIELD`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_hidden_required_field) | A layer that creates a Resource hides a required field. | A layer still creates the Resource (a create or upsert variant, or a nested create) while a required field, or a required relation's reference field, is hidden or has its create capability exempted, and no compute.create fills it. | Expose the field, give it a compute.create stage, or exempt the layer's create operations. |
+| [`COMPILER_INVALID_VALIDATOR`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_invalid_validator) | A field validator cannot apply. | A validator that is not built with AvZ, does not fit the field's type (AvZ.maxLength on an int, AvZ.maxItems on a field that is not a list), or sits on a relation or Json field. | Use an AvZ check that fits the field's type; a Json field's checks go in its json shape. |
+| [`COMPILER_INVALID_JSON_SHAPE`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_invalid_json_shape) | A Json shape cannot apply. | A json shape on a field that is not a discovered Json field, a shape not built with AvZ, or one that admits null or absence at its top level. | Put the shape on a Json field, build it with AvZ, and keep its top level non-null (the column's nullability decides null). |
+| [`COMPILER_INVALID_CLIENT_CONTRACT`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_invalid_client_contract) | The compiled client contract is invalid. | The finished client contract failed its own structural check: a framework defect. | Report it with the diagnostic's path and message. |

package/README.md

@@ -16,7 +16,7 @@ npx @aventara/cli@rc init           # or: add Aventara to an existing NestJS 12
 npm install @aventara/core@rc       # the package on its own
 ```
 
-Node `^22.18.0 || >=24.2.0`. ES modules, with a CommonJS `default` condition.
+Node `^22.23.4 || >=24.22.1`. ES modules, with a CommonJS `default` condition.
 
 ## Documentation
 
@@ -53,7 +53,7 @@ of generic JSON. So does a client generated with `avclient`, which emits the typ
 
 The shape is also one of `meta`'s validators. Every write of `meta` is checked against it before the database is
 asked: a create, update, upsert, nested write or transaction step, including a value a transaction step takes from an
-earlier step. It is checked where validators run, after every pipe and before any interceptor or hook, and its issues
+earlier step. It is checked where validators run, after every pipe and write compute and before any interceptor or hook, and its issues
 come in field order with the other validators'. A value out of shape is refused with `A2004`, one issue per problem at its
 exact path:
 
@@ -118,6 +118,47 @@ try {
 generated client throws the same classes by the same table. `framework.execute` and `framework.executeTransaction`, the
 entries a transport calls, still answer the envelope.
 
+## The client layer, called with your own values
+
+`framework.client` reads its arguments in the wire forms a decoded request body carries: a `datetime` is its ISO string,
+a `bigint` its base-10 string. That suits a test that should behave like a remote caller. Server code that acts for a
+remote caller, such as a Server Component or a Server Action, holds `Date`s and `bigint`s instead. It calls
+`framework.serverClient`:
+
+```ts
+const recent = await framework.serverClient.Post.find.many({
+  where: { createdAt: { gt: new Date(Date.now() - 86_400_000) } },
+  select: ["id", "title"],
+});
+```
+
+`serverClient` has the client layer's types and rules: what the client layer hides is absent, and the client
+pipelines, validation, exposure and policy run. Its arguments are the application forms (`Date`, `bigint`,
+`AvDecimal`, `Uint8Array`), the same ones `framework.application` takes, and its results are `framework.client`'s.
+Each call copies its arguments, encodes them into the wire forms and runs the request `framework.client` would run.
+`framework.serverClientTx` builds client-layer transaction handles the same way; one `framework.transaction([...])`
+may hold them beside `clientTx` handles, never beside `appTx` ones.
+
+`framework.serverClient.all({ key: call, … }, { settle?, signal? })` awaits an object of calls together, in process,
+as the generated client's `avClient.all` does in the browser. A call runs when it is made; wrap it in
+`avLazy(() => call)` for `all` to start it, at most `limits.maxAllConcurrency` at once. It takes any number of
+entries: `limits.maxAll` bounds `POST /_all` only. Strict by default (the first
+failure rejects it and its `avLazy` entries not yet started never start); `settle: true` settles every key as
+`{ status, value }` or `{ status, reason }`. Its `signal` aborts each entry; a call takes its own `signal` too.
+
+## Every code, explained
+
+`AvErrorCatalog` holds every code this package answers, reports in a validation issue, or refuses to start with: its
+`kind`, `message`, `cause`, `fix` and `docs` URL. The same catalog ships beside `dist` as `ERRORS.md`, and each entry
+of a startup `AvConstructionError`'s `diagnostics` carries its code's `docs` URL.
+
+```ts
+import { AvErrorCatalog } from "@aventara/core";
+
+AvErrorCatalog.A2004.fix; // "Fix the argument each issue's path points at, …"
+AvErrorCatalog.V1000.docs; // "https://aventara.razor34.dev/framework/docs/error-codes#v1000"
+```
+
 ## Required create fields are typed
 
 Each Resource's Contract states what a create cannot do without (`createRequirements`), as the adapter reads it off
@@ -149,13 +190,16 @@ it a `compute.create`, or exempt `create.many` and `create.count` in that layer
 A field your operation pipe fills server-side is now required of the caller. Give it a `compute.create` stage (or a
 database default) so callers can leave it out, or have them pass it.
 
+Inside the pipeline the requirements hold from write compute on. A variant's guards, pipes and filters run before
+compute, and their typed arguments require no field of a create, since compute may still fill it: `args.data.slug` is
+`string | undefined` in a pipe, and a pipe may return a create without it. The variant's hooks and interceptors run
+after compute and see every required field present.
+
 ## Returning a façade from a method
 
 A Nest project emits declarations (`declaration: true`), so a method without a return type has its type written out.
-Every node of the typed façades has a name for that: 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()
@@ -165,21 +209,48 @@ 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`, `serverClient`, `appTx`, `clientTx`, `serverClientTx`):
+
+| Node | `framework.application` | the others |
+| --- | --- | --- |
+| the whole surface | `AvApplicationFacade` | `AvClientFacade`, `AvServerClientFacade`, `AvAppTxFacade`, `AvClientTxFacade`, `AvServerClientTxFacade` |
+| one Resource | `AvApplicationResourceFacade` | `AvClientResourceFacade`, … |
+| one family | `AvApplicationFamilyFacade` | `AvClientFamilyFacade`, … |
+| a variant that takes a `select` or `include` | `AvApplicationProjectingCall` | `AvClientProjectingCall`, `AvServerClientProjectingCall`, `AvAppTxProjectingCall`, `AvClientTxProjectingCall`, `AvServerClientTxProjectingCall` |
+| a variant that does not (the `count` variants: `find.count`, `update.count`, …) | `AvApplicationPlainCall` | `AvClientPlainCall`, `AvServerClientPlainCall`, `AvAppTxPlainCall`, `AvClientTxPlainCall`, `AvServerClientTxPlainCall` |
+
+Each takes the view, `AvContractView`, as its first argument. The view's arguments are your model by its name, the root's
+and the overlay's exposure as written, and the `fields` entries your configuration's `resources` blocks hold. A
+configuration with no `fields` entries writes `never` there. One that has them writes those entries, stages erased, after
+every reference: measured at about 23 KB per method over 50 Resources that each configure a field. Annotate the method
+(`posts(): AppFramework["application"]["Post"]`) if that matters to you; the annotation is written as that reference.
+
+You never need to write these names yourself. They exist so a declaration file can name what a method returns, and a
+project that reads only your declarations types the method exactly as your Framework does. An application that publishes
+no declarations can set `"declaration": false` and skip the question.
+
+The configuration itself costs almost nothing to declare. The Prisma adapter's discovery artifact names the model's
+type (`AvModel`), so the scaffold's `aventaraConfig()`, a `buildFramework` and its `AppFramework` alias write
+`AvAdapter<AvModel>` and `AvFramework<AvModel, …>`: about 0.5 KB at any schema size, where rc.1 wrote
+the model out once per mention (1.2 MB over 50 Resources).
 
 An exported `defineResource(...)` result, and an exported configuration or Framework builder holding typed stages,
 need no annotation: their stages are written by their public types (`readonly AvGuard[]`, `readonly AvPipe[]`, …),
@@ -187,8 +258,8 @@ never with the model the inline stages were typed from.
 
 ## Server-side calls copy their input
 
-`framework.application`, `framework.client`, `framework.execute`, `framework.executeTransaction`, and the `appTx` /
-`clientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
+`framework.application`, `framework.client`, `framework.serverClient`, `framework.execute`,
+`framework.executeTransaction`, and the `appTx` / `clientTx` / `serverClientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
 Validation, your guards and pipes, computed values and the adapter all see only the copy, and your stages see it
 frozen: only a pipe changes the arguments, by returning new ones, so what the validators checked is what the adapter
 writes. In practice:
@@ -287,6 +358,249 @@ 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. For an update the engine lists in `afterChecks`, that
+question also carries `before`, the row as it was before the update; it is present only then. An engine that also
+answers the optional `grantsOf` is asked, before the write, which of its grants cover that row (`exists` then sees
+nothing the request writes), and gets the answer back on the after check as `beforeGrants`. Such an engine refuses
+an after check that carries `before` without `beforeGrants` rather than deciding `before` after the write.
+A typed literal in a fragment the engine answers may be in its application form (`Date`, `AvDecimal`, `bigint`) or its
+wire form (an ISO string, a decimal string, a digit string), as a policy read from JSON states it. Where `transactionsStyle` is `"interactive"`, a
+checked write with a check after it (an update, a nested write) runs in a transaction of its own, and a create or
+delete checked before it runs is one statement; where it is `"none"`, a write that could only be checked after it runs
+is refused (for after conditions, the updates the engine lists in `afterChecks`).
+
+Nested writes (`$create`, `$connect` and the other relation directives) run as one call inside that transaction. Before
+it, every row they link is held to the right scope: a linked row that holds the reference must be one the caller may
+change, one whose parent holds it one the caller may read. Writing a reference field itself (`authorId: "u2"`) links
+the same row, and is held the same way: the row it names must be one the caller may read. Where the adapter can link
+the row in that write, core hands it the reference as a `$connect` carrying the read scope, so the write itself refuses
+a row outside it (`A4002`), with no query of its own; where it cannot (a bulk write on Prisma), one `exists` per target
+Resource asks before the write. Nothing is asked where that Resource is read by everyone, and a `null` reference is not
+asked about. Only a reference to a Resource the Core Contract shows is held; one the root's exemptions hide is not, nor
+one the engine lists in its optional `unheld`: a Resource its rules read in conditions and decide no read of (a
+Resource another service owns, say), so its read scope is `false` for every caller. A reference to one of those, and a
+`$connect` or `$set` that links one by the reference's own values where the writing row holds the reference, is
+decided by the write's own grant
+(`can`, and the after check `afterChecks` lists); reads of it are decided by `scopeOf` as always. An engine that has the
+optional `hosted` is told the held Resources once the Framework is built (`hosted({ held })`), so it can check its own
+rules against them; it answers nothing differently. A to-many `$update` or
+`$delete` acts only on the rows the caller may change or delete, as `update.many` does. After the call, every row they changed is checked as an update is
+(the after check, the move-out re-read), and every row they created is read back as stored and asked `can`; one refusal
+rolls the whole write back. Where `transactionsStyle` is `"none"`, a nested write under a policy is refused.
+
+## An access provider
+
+`access` takes the policy engine and the request state from one object, an `AvAccessProvider`. Aventara Access
+provides one, and you can write your own. It has two members:
+
+- `policy`: the engine, as `policy.engine` takes it.
+- `state({ headers, request })`: seeds each request's `ctx.$state`. Its `me` is the principal the engine is asked
+  about (`null` for an anonymous caller).
+
+The host calls `state` once per request: `@aventara/nest` with the platform request's headers and the request itself,
+`@aventara/next` with the request's headers (and the route's `Request` on a route call). With `access`, leave out
+`policy` and the host's own `state` option; either one beside it is refused at startup, and as a type error where the
+configuration's type shows both. Server code that calls the Framework directly passes the state itself,
+`{ state: await access.state({ headers }) }`.
+
+A point-of-sale till with its own PIN sign-in, written by hand:
+
+```ts
+import type { AvAccessProvider } from "@aventara/core";
+
+type Cashier = { id: string; role: "cashier" | "manager" };
+
+declare module "@aventara/core" {
+  interface AvState {
+    me?: Cashier | null;
+  }
+}
+
+export const tillAccess = {
+  // The till sends the PIN the cashier typed as `x-pos-pin`.
+  state: async ({ headers }) => ({ me: await cashierByPin(headers.get("x-pos-pin")) }),
+  policy: {
+    can: ({ principal, resource, action }) => {
+      const me = principal as Cashier | null;
+      if (me === null) return false; // no PIN, no till
+      if (resource === "Refund" && action !== "read") return me.role === "manager";
+      return true;
+    },
+    scopeOf: () => true,
+    fieldsOf: () => ({ always: "all", perRow: {} }),
+  },
+} satisfies AvAccessProvider;
+
+const framework = await createFramework({ api: "/api", adapter, access: tillAccess });
+```
+
+Every stage reads the cashier as `ctx.$state.me`, typed by the `AvState` declaration above.
+
+### `$access` and the provider's `client`
+
+A provider may also state `client`: where the app mounted Aventara Access (`url`, absolute `http(s)` or root-relative)
+and the verbs it offers (`signIn`, `signUp`, `signOut`, `resetPassword`, `me`, and on Access's `kiosk` profile
+`switchUser`, `lock`, `setPin`, `enrollDevice`, `revokeDevice`; each optional, any other name refused), each with its route
+(`method`, `path`), the JSON Schema of its arguments and result (the subset a `json` field's shape uses), and `call`,
+the verb run in process. Aventara Access fills it in. It is compiled into the Client Contract's `access` section with
+each `call` dropped, so the hash changes only for apps whose provider states it. Every client then carries `$access`:
+
+- `can(questions, options?)`: the batched `POST {api}/_access/can`, one boolean per question. An empty list answers
+  `[]` (`200 A1000`), not a refusal: a page with nothing to ask is no client bug, unlike an empty `/_transactions` plan.
+- `me()`: the token identity `{ sub, claims }`, or `null`; and the sign-in verbs the provider offers. A verb the
+  provider leaves out (a `service` profile has no `signIn`/`signUp`; only a `kiosk` profile has `switchUser`, `lock`,
+  `setPin`, `enrollDevice`, `revokeDevice`) is no member of `$access`. `switchUser` and `enrollDevice` resolve
+  Access's answer, `lock`, `setPin` and `revokeDevice` nothing, as `signIn` and `signOut` do.
+
+`framework.serverClient.$access` answers `can` in process under the call's `state` (or, with `headers` and no
+`state`, the state the provider seeds from them; with neither, anonymously), and runs each verb through its `call` with
+the headers you pass. The section's `url` and each verb's `path` are checked wherever a ClientContract is read: an
+absolute `http(s)` URL or a root-relative path other than `/`, a path starting with one `/`, neither holding a control
+character, a space or a `.`/`..` segment (percent-encoded too). Under Nest, hand the platform request and response too, so Access can read the
+session and set a sign-in's cookie:
+
+```ts
+const me = await framework.serverClient.$access.me({ headers: req.headers });
+await framework.serverClient.$access.signIn(body, { headers: req.headers, request: req, response: res });
+const [canRefund] = await framework.serverClient.$access.can([{ resource: "Refund", action: "create" }], { state });
+```
+
+Without `access`, `serverClient` has no `$access` at all; a provider without `client` offers `can` alone.
+
+On Access's `kiosk` profile, `switchUser`, `lock` and `enrollDevice` rotate the device's credential cookie: under
+Nest, call them with the platform `response` (`{ headers, request, response }`), or the rotated cookie never reaches
+the device and its next switch is refused. Under Next, call them from a Server Action. Never call a verb that changes
+anything inside a cache (Next's `"use cache"`, a memoized helper): a cached answer replays one caller's result to
+another and skips the call. Every verb's answer is projected onto its result schema, so no session token or device
+secret reaches server code either.
+
+## A model managed elsewhere
+
+Some tables belong to another service: Better Auth's `user`, or another service's schema in the same database. Your
+service joins into them and must not write or migrate them. Mark such a model at the root:
+
+```ts
+const framework = await createFramework({
+  api: "/api",
+  adapter,
+  resources: { Account: { managedElsewhere: true } },
+});
+```
+
+- `Account` has no `create`, `update`, `delete` or `upsert` in any layer, and its fields take no write. A call is a
+  type error, and an untyped one is refused with `A2002`.
+- A relation into it keeps only `$connect` and `$disconnect`, and only where your model holds the key (`Post.authorId`
+  for `Post.author`). A nested `$create`, `$update` or `$upsert` into it is a type error and `A2004` (`V1006`).
+- `framework.application` reads `Account` and filters and includes through `Post.author`. The client and agent layers
+  leave out `Account` and every relation into it, so `/_contract`, the generated client and the MCP tools never show
+  it. An overlay can't bring it back.
+- A stage on one of its write families is refused at startup (`COMPILER_UNAVAILABLE_OPERATION`), and
+  `managedElsewhere` in an overlay is `CONFIG_FORBIDDEN_IN_OVERLAY`. So is any `client.resources.Account` or
+  `agent.resources.Account` entry (`COMPILER_UNKNOWN_RESOURCE`): those layers never have it, so nothing there runs.
+- A delete that would write it through a referential action is refused at startup (`CONFIG_INVALID_VALUE` at
+  `resources.Account.managedElsewhere`): if any layer can delete a row whose deletion cascades into `Account` or sets
+  its reference to null or its default, directly or through other cascades. Take those deletes away at the root, or
+  make the reference `onDelete: Restrict`.
+- A create that only the hidden relation could satisfy is refused at startup (`COMPILER_HIDDEN_REQUIRED_FIELD`), naming
+  the reference field to expose instead, so no client advertises a create that can't succeed.
+- `framework.contracts.core` marks it `managedElsewhere: true`, and states every Resource's database `schema` where
+  the adapter knows it (`@@schema("auth")` with `@aventara/prisma7-adapter`). No other Contract carries either.
+
+Two things stay yours. A key update follows the owner's foreign key (`ON UPDATE CASCADE` rewrites `Account`'s rows;
+core has no `onUpdate` facts). And your own code — `ctx.$sql`, an application transaction's SQL step, a stage that
+calls Prisma directly — can still write `Account`.
+
+Aventara doesn't migrate anything, so tell Prisma too: list the table as external in `prisma.config.ts`.
+
+```ts
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  experimental: { externalTables: true },
+  tables: { external: ["auth.Account"] },
+});
+```
+
+## Caching reads
+
+Reads are POST by default, which no browser or CDN caches. To let one keep a read, give it a `cache` stage:
+
+```ts
+import { cache, createFramework } from "@aventara/core";
+
+const framework = await createFramework({
+  api: "/api",
+  adapter,
+  resources: {
+    Product: { pipelines: { cache: cache({ for: "everyone", maxAge: 300 }) } },
+    Post: {
+      operations: {
+        find: { many: { pipelines: { cache: cache({ for: "anonymous", maxAge: 60 }) } } },
+      },
+    },
+    Order: { pipelines: { cache: cache({ for: "user", maxAge: 30 }) } },
+  },
+});
+```
+
+`for` says who may share one answer:
+
+- `for: "user"`: the answer is the caller's own. `Cache-Control: private, max-age=<maxAge>`, `Vary: Authorization,
+  Cookie`: only the caller's browser keeps it.
+- `for: "anonymous"`: every anonymous caller gets the same answer, which a CDN may keep (`public`); a signed-in caller's
+  stays `private`.
+- `for: "everyone"`: every caller gets the same answer, and a CDN may hand it to anyone (`public`). Use it only where
+  nothing makes the answer differ by caller: no stage that reads the caller, no read compute that does, no policy that
+  scopes the rows or fields.
+
+Always write `for`, even for the default `"user"`: the audience is the promise this read makes, and it should be visible
+in the code. Aventara doesn't check the promise; it serves the headers you asked for.
+
+- Put the stage at the root or `client` layer, a Resource, the `find` family or one `find` variant. The most specific one
+  wins; at one level, `client`'s replaces the root's. A write, a transaction, `application` or `agent` refuses it at
+  startup (`CONFIG_INVALID_VALUE`).
+- A cached read is also served as `GET /api/_resources/<Resource>/find/<variant>?q=<arguments>&v=<contract hash>`. The
+  Client Contract marks it, so the generated client sends it that way.
+- "Anonymous" means: with a policy (or `access`), the principal derived from the request's state is `null`; without one,
+  the request sends no `Cookie` and no `Authorization` header. If your callers sign in with a custom header, configure a
+  policy, or don't use `"anonymous"` or `"everyone"`.
+- Every answer to a GET carries `Referrer-Policy: no-referrer`, `X-Content-Type-Options: nosniff` and an `ETag`; a matching
+  `If-None-Match` is `304`; anything but a `200` is `no-store`. A public answer echoes no `Aventara-Request-Id`.
+- A new deploy changes the contract hash in the URL, so nothing cached before it is served after it.
+- The URL holds the read's arguments: it shows up in server logs and browser history. A browser's prefetch is a GET
+  too, and runs your pipelines; they see `ctx.$transport.method === "GET"`.
+
 ## 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-discovery-diagnostic.guidance.d.ts

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

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

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