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

package/ERRORS.md

@@ -0,0 +1,142 @@
+# 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.
+
+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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/docs/error-codes#a1002) | Created. | create.one created a row. | Nothing: the call succeeded. |
+| [`A1003`](https://aventara-framework.vercel.app/docs/error-codes#a1003) | Created many. | create.many or create.count created rows. | Nothing: the call succeeded. |
+| [`A1004`](https://aventara-framework.vercel.app/docs/error-codes#a1004) | Updated. | update.first or update.unique updated a row. | Nothing: the call succeeded. |
+| [`A1005`](https://aventara-framework.vercel.app/docs/error-codes#a1005) | Updated many. | update.many or update.count updated rows. | Nothing: the call succeeded. |
+| [`A1006`](https://aventara-framework.vercel.app/docs/error-codes#a1006) | Deleted. | delete.first or delete.unique deleted a row. | Nothing: the call succeeded. |
+| [`A1007`](https://aventara-framework.vercel.app/docs/error-codes#a1007) | Deleted many. | delete.count deleted rows. | Nothing: the call succeeded. |
+| [`A1008`](https://aventara-framework.vercel.app/docs/error-codes#a1008) | Upserted. | upsert.unique created or updated a row. | Nothing: the call succeeded. |
+| [`A1009`](https://aventara-framework.vercel.app/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-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. |
+| [`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. |
+| [`A2008`](https://aventara-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/docs/error-codes#a2010) | Payload too large. | The decoded request body exceeds maxRequestBytes (default 1048576). | Send less, or raise limits.maxRequestBytes. |
+| [`A2011`](https://aventara-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/docs/error-codes#a2013) | Concurrent modification. | A competing writer reached the state first; nothing was written. | Retry. No retry is automatic. |
+| [`A2014`](https://aventara-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-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. |
+
+## 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-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). |
+| [`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. |
+| [`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. |
+| [`V1008`](https://aventara-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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. | Write either the relation or its reference field, in the relation's cardinality. |
+| [`V1013`](https://aventara-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-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_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_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. |
+
+## Startup: discovery
+
+`AvConstructionError` with `stage: "discovery"`: what the adapter reported does not hold together.
+
+| Code | Meaning | Cause | Fix |
+|---|---|---|---|
+| [`DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH`](https://aventara-framework.vercel.app/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-framework.vercel.app/docs/error-codes#compiler_unknown_resource) | Unknown Resource. | A Resource name the adapter's model does not have, in resources or in exemptions. | Use the model's exact name. After a schema change run `npm run aventara:prepare`. |
+| [`COMPILER_UNKNOWN_FIELD`](https://aventara-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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). | Rename the model; the table it maps to can keep its name. |
+| [`COMPILER_MISSING_IDENTIFIER`](https://aventara-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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-framework.vercel.app/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

@@ -2,11 +2,11 @@
 
 The Aventara framework itself: the framework factory (`createFramework`), configuration and its resolution, the
 adapter interfaces an ORM adapter implements, Contract compilation and identity, validation, operation semantics, the
-pipeline runtime, transactions and execution. Its HTTP protocol — passive data and pure functions; it mounts nothing —
-is the separate entry point `@aventara/core/protocol`, which hosts such as `@aventara/nest` serve.
+pipeline runtime, transactions and execution. Its HTTP protocol is the separate entry point `@aventara/core/protocol`,
+which hosts such as `@aventara/nest` serve. The protocol is passive data and pure functions, and it mounts nothing.
 
-Core is ORM- and transport-agnostic: it imports neither Prisma nor NestJS. An application uses it through an adapter
-(`@aventara/prisma7-adapter`) and a host (`@aventara/nest`), and the usual way to set that up is the CLI.
+Core imports neither Prisma nor NestJS. An application uses it through an adapter (`@aventara/prisma7-adapter`) and a
+host (`@aventara/nest`), and the usual way to set that up is the CLI.
 
 ## Install
 
@@ -20,17 +20,17 @@ Node `^22.18.0 || >=24.2.0`. ES modules, with a CommonJS `default` condition.
 
 ## Documentation
 
-Start from the `@aventara/cli` README (what `new` and `init` write), then `@aventara/nest` (mounting a `Framework`)
-and `@aventara/prisma7-adapter` (the Prisma 7 adapter and its generate step); each package's README ships in its
+Start from the `@aventara/cli` README (what `new` and `init` write), then `@aventara/nest` (mounting an `AvFramework`)
+and `@aventara/prisma7-adapter` (the Prisma 7 adapter and its generate step). Each package's README ships in its
 tarball and shows on its npm page.
 
 ## Typed Json fields
 
-A `Json` field is any JSON by default. To give it a shape, build one with `AvZ` from `@aventara/core/json` and declare
-it on the field in the configuration:
+A `Json` field is any JSON by default. To give it a shape, build one with `AvZ` from `@aventara/core/avz` and declare
+it as the field's `definition.json` in the configuration's `resources` tree:
 
 ```ts
-import { AvZ } from "@aventara/core/json";
+import { AvZ } from "@aventara/core/avz";
 
 const postMeta = AvZ.object({
   seo: AvZ.object({ title: AvZ.string(), keywords: AvZ.array(AvZ.string()) }),
@@ -42,86 +42,276 @@ const postMeta = AvZ.object({
 export type PostMeta = AvZ.infer<typeof postMeta>;
 
 const framework = await createFramework({
-  entrypoint: "/api",
+  api: "/api",
   adapter,
-  fields: { Post: { meta: { json: postMeta } } },
+  resources: { Post: { fields: { meta: { definition: { json: postMeta } } } } },
 });
 ```
 
-- **Typed.** `framework.application`, `framework.client`, `appTx` and `clientTx` read and write `Post.meta` as
-  `PostMeta`, not as generic JSON, and so does a client generated with `avclient` (it emits the type; it needs no
-  Zod).
-- **Checked on every write.** A create, update, upsert, nested write or transaction step that writes `meta` — a value
-  a transaction step takes from an earlier step included — is checked against the shape before the database is
-  asked. A value out of shape is refused with `A2004`, one issue per problem at its exact path:
+`framework.application`, `framework.client`, `appTx` and `clientTx` read and write `Post.meta` as `PostMeta` instead
+of generic JSON. So does a client generated with `avclient`, which emits the type and needs no Zod.
 
-  ```json
-  { "code": "V1001", "path": ["arguments", "data", "meta", "seo", "title"], "message": "Value must be a string." }
-  ```
+The shape is also one of `meta`'s validators. Every write of `meta` is checked against it before the database is
+asked: a create, update, upsert, nested write or transaction step, including a value a transaction step takes from an
+earlier step. It is checked where validators run, after every pipe and write compute and before any interceptor or hook, and its issues
+come in field order with the other validators'. A value out of shape is refused with `A2004`, one issue per problem at its
+exact path:
+
+```json
+{ "code": "V1001", "path": ["arguments", "data", "meta", "seo", "title"], "message": "Value must be a string." }
+```
 
-  A missing key is `V1000`, a value outside an enum or a literal `V1002`, an integer outside the safe range `V1004`,
-  and a key the shape does not declare `V1005`, once per key. Reads and filters are never checked against a shape, so
-  rows written before the shape existed stay readable.
-- **Types only.** `AvZ` has `string`, `number`, `int`, `boolean`, `null`, `literal`, `enum`, `object`, `array`,
-  `tuple`, `record`, `union`, `discriminatedUnion`, `optional` and `nullable` — no lengths, ranges, patterns,
-  refinements, transforms or defaults. Objects are closed: a key the shape does not declare is refused. `optional`
-  marks an object key that may be left out.
-- **Where it applies.** Only a field the adapter discovered as `Json` takes a shape, and the shape itself cannot admit
-  `null` or absence at its top level — whether the field may be `null` comes from your schema. A shape is built with
-  `AvZ` only: a Zod schema is not accepted, as a type error and when the framework starts.
-- **In the Contract.** The shape is part of the ClientContract, as JSON Schema; adding or changing one changes the
-  ClientContract hash, so regenerate the client.
+A missing key is `V1000`, a value outside an enum or a literal `V1002`, an integer outside the safe range `V1004`,
+and a key the shape does not declare `V1005`, once per key. Reads and filters are never checked against a shape, so
+rows written before the shape existed stay readable.
+
+`AvZ` has `string`, `number`, `int`, `boolean`, `null`, `literal`, `enum`, `object`, `array`, `tuple`, `record`,
+`union`, `discriminatedUnion`, `optional` and `nullable`. A shape node takes checks with `.check(...)`: a string takes
+length, pattern and format checks, a number or an integer takes bounds and `multipleOf`, and an array takes
+`AvZ.minItems`/`AvZ.maxItems`, as in `AvZ.string().check(AvZ.maxLength(80))`. There are no refinements, transforms or
+defaults. Objects are closed: a key the shape does not declare is refused. `optional` marks an object key that may be
+left out.
+
+Only a field the adapter discovered as `Json` takes a shape. The shape cannot admit `null` or absence at its top
+level; whether the field may be `null` comes from your schema. A shape is built with `AvZ` only. A Zod schema is
+refused, both as a type error and when the framework starts.
+
+The shape is part of the ClientContract, as JSON Schema. Adding or changing one changes the ClientContract hash, so
+regenerate the client.
 
 The shape types `AvZShape`, `AvZObject`, `AvZOptional` and `AvZNullable` are exported so a project that emits
 declarations can name the shapes it exports.
 
-`@aventara/core/json` is the only entry that loads Zod (`zod/mini`); an application that declares no shape never loads
+`@aventara/core/avz` is the only entry that loads Zod (`zod/mini`); an application that declares no shape never loads
 it.
 
+## Server-side calls resolve their data and throw their failures
+
+`framework.application`, `framework.client`, `framework.transaction([...])` and a pipeline's `ctx` calls settle the way
+a generated client does: they resolve the data (a row, a list, a count, `null` for a `first` that matched nothing; a
+committed transaction its steps' results in order) and throw every failure as the `AvError` subclass of its code's
+class, exported from `@aventara/core`:
+
+```ts
+import { AvNotFoundError, AvValidationError } from "@aventara/core";
+
+try {
+  const post = await framework.application.Post.update.unique({ where: { id }, data: { title } });
+} catch (error) {
+  if (error instanceof AvNotFoundError) return null;        // A2003
+  if (error instanceof AvValidationError) throw badRequest(error.cause.issues);
+  throw error;
+}
+```
+
+| Class                     | Codes                                       |
+| ------------------------- | ------------------------------------------- |
+| `AvProtocolError`         | A2000, A2001, A2002, A2006, A2010–A2012     |
+| `AvNotFoundError`         | A2003                                       |
+| `AvValidationError`       | A2004, A2007, A2009                         |
+| `AvContractMismatchError` | A2005                                       |
+| `AvConflictError`         | A2008, A2013, A2014                         |
+| `AvInternalError`         | A3000–A3004                                 |
+| `AvAuthError`             | A4000–A4002                                 |
+
+`error.code` and `error.cause` are the envelope's (a transaction's `cause.operation` names the failing step). The
+generated client throws the same classes by the same table. `framework.execute` and `framework.executeTransaction`, the
+entries a transport calls, still answer the envelope.
+
+## Every code, explained
+
+`AvErrorCatalog` holds every code this package answers, reports in a validation issue, or refuses to start with: its
+`kind`, `message`, `cause`, `fix` and `docs` URL. The same catalog ships beside `dist` as `ERRORS.md`, and each entry
+of a startup `AvConstructionError`'s `diagnostics` carries its code's `docs` URL.
+
+```ts
+import { AvErrorCatalog } from "@aventara/core";
+
+AvErrorCatalog.A2004.fix; // "Fix the argument each issue's path points at, …"
+AvErrorCatalog.V1000.docs; // "https://aventara-framework.vercel.app/docs/error-codes#v1000"
+```
+
+## Required create fields are typed
+
+Each Resource's Contract states what a create cannot do without (`createRequirements`), as the adapter reads it off
+the database schema: the fields every create must write, and each required relation, which a create writes either as
+the relation or through the fields that hold its reference, never both. The façades, `appTx`/`clientTx`, a stage's
+`ctx` and the generated client type every create payload by it:
+
+```ts
+await framework.application.Post.create.one({ data: { title: "Hi", authorId } });          // ok
+await framework.application.Post.create.one({ data: { title: "Hi", author: { $connect: { id: authorId } } } }); // ok
+// @ts-expect-error neither `author` nor `authorId`
+await framework.application.Post.create.one({ data: { title: "Hi" } });
+// @ts-expect-error `author` and `authorId` both
+await framework.application.Post.create.one({ data: { title: "Hi", authorId, author: { $connect: { id: authorId } } } });
+```
+
+It covers `create.one`'s `data`, every `create.many` record, `upsert`'s `create`, and nested `$create`,
+`$connectOrCreate` and `$upsert` payloads, where the relation the create is nested through is supplied by its parent.
+A `$ref` satisfies a field. Each layer's Contract states only what that layer lets a caller write: hide `authorId` and
+`author` alone is required; hide `author` and `authorId` is. A field a `compute.create` stage fills is not required,
+whether the stage is written inline in `createFramework({...})`, in a `defineResource` block or in a typed config.
+The runtime still refuses what the types refuse (`A2004`, `V1000` or `V1012`).
+
+A `create.many` or `create.count` record cannot write a relation, so there `authorId` is required. A layer that hides
+`authorId` while it keeps those variants fails at startup (`COMPILER_HIDDEN_REQUIRED_FIELD`): expose `authorId`, give
+it a `compute.create`, or exempt `create.many` and `create.count` in that layer
+(`exemptions: { resources: { Post: { fields: { authorId: true }, operations: { create: ["many", "count"] } } } }`).
+
+A field your operation pipe fills server-side is now required of the caller. Give it a `compute.create` stage (or a
+database default) so callers can leave it out, or have them pass it.
+
+Inside the pipeline the requirements hold from write compute on. A variant's guards, pipes and filters run before
+compute, and their typed arguments require no field of a create, since compute may still fill it: `args.data.slug` is
+`string | undefined` in a pipe, and a pipe may return a create without it. The variant's hooks and interceptors run
+after compute and see every required field present.
+
+## Returning a façade from a method
+
+A Nest project emits declarations (`declaration: true`), so a method without a return type has its type written out.
+Every node of the typed façades has a name for that: 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:
+
+```ts
+@Injectable()
+export class PostsService {
+  constructor(@InjectFramework() private readonly framework: AppFramework) {}
+
+  posts() {
+    return this.framework.application.Post;
+  }
+}
+```
+
+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.
+
+```ts
+posts(): AppFramework["application"]["Post"] {
+  return this.framework.application.Post;
+}
+```
+
+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 configuration itself costs almost nothing to declare. The Prisma adapter's discovery artifact names the model's
+type (`AvModel`), so the scaffold's `aventaraConfig()`, a `buildFramework` and its `AppFramework` alias write
+`AvAdapter<AvModel>` and `AvFramework<AvModel, …>`: about 0.5 KB at any schema size, where rc.1 wrote
+the model out once per mention (1.2 MB over 50 Resources).
+
+An exported `defineResource(...)` result, and an exported configuration or Framework builder holding typed stages,
+need no annotation: their stages are written by their public types (`readonly AvGuard[]`, `readonly AvPipe[]`, …),
+never with the model the inline stages were typed from.
+
 ## Server-side calls copy their input
 
 `framework.application`, `framework.client`, `framework.execute`, `framework.executeTransaction`, and the `appTx` /
 `clientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
-Everything after that — validation, your guards and pipes, computed values, the adapter — sees only the copy:
-
-- **Changing your object afterwards changes nothing.** An Immer draft revoked after `produce`, or a reactive store that
-  moves on, is safe to pass: the call already has its own copy.
-- **A live Proxy works** (Vue `reactive`, MobX): it is read through its traps once.
-- **`Date`, `Decimal` and `Uint8Array`** (a Node `Buffer` too) are copied as themselves; `bigint` and other primitives are
-  values.
-- **Only plain data.** Arrays and plain objects (`{}` or `Object.create(null)`) are copied with their own enumerable
-  string keys, like JSON: inherited, non-enumerable and symbol keys are dropped. Any other object — a class instance, a
-  `Map` — is refused.
-- **A value that cannot be read** (a revoked Proxy, a getter that throws) is refused too. Both refusals are your
-  request's error, not the server's: `A2004` with one `V1001` at the value's path — `["arguments", …]`, or
-  `["operations", i, "args", …]` with `cause.operation` in a transaction — before any guard, pipe or adapter runs:
+Validation, your guards and pipes, computed values and the adapter all see only the copy, and your stages see it
+frozen: only a pipe changes the arguments, by returning new ones, so what the validators checked is what the adapter
+writes. In practice:
+
+- Changing your object afterwards changes nothing. An Immer draft revoked after `produce`, or a reactive store that
+  moves on, is safe to pass, because the call already has its own copy.
+- A live Proxy (Vue `reactive`, MobX) works: it is read through its traps once.
+- `Date`, `AvDecimal` and `Uint8Array` (a Node `Buffer` too) are copied as themselves; `bigint` and other primitives
+  are values.
+- Arrays and plain objects (`{}` or `Object.create(null)`) are copied with their own enumerable string keys, like JSON:
+  inherited, non-enumerable and symbol keys are dropped. Any other object, such as a class instance or a `Map`, is
+  refused.
+- A value that cannot be read (a revoked Proxy, a getter that throws) is refused too. Both refusals are errors in your
+  request, not the server's: `A2004` with one `V1001` at the value's path (`["arguments", …]`, or
+  `["operations", i, "args", …]` with `cause.operation` in a transaction), before any guard, pipe or adapter runs:
 
   ```json
   { "code": "V1001", "path": ["arguments", "where", "id"], "message": "Value could not be read." }
   ```
 
-  A builder never throws: `appTx`/`clientTx` keep the refusal, and `framework.transaction([...])` answers it.
+  A builder never throws: `appTx`/`clientTx` keep the refusal, and `framework.transaction([...])` throws it as an
+  `AvValidationError`.
 
 To count these refusals, set `misuse` at the root of the configuration, beside `diagnostics`:
 
 ```ts
 const framework = await createFramework({
-  entrypoint: "/api",
+  api: "/api",
   adapter,
   misuse: (event) => metrics.increment("aventara.misuse", { kind: event.kind }),
 });
 ```
 
-It receives one `FrameworkMisuseEvent` per refusal — `kind` (`"unreadable-value"` or `"non-plain-value"`), the `path`
-the caller received, and `origin`, `resource`, `family`, `variant` and the transaction step (`operation`) when they could
-be read — never the value itself. It cannot change the response: an error it throws, or a promise it rejects, is
-ignored. `diagnostics` keeps receiving the server's own unexpected failures, and nothing is reported to both.
+It receives one `AvMisuseEvent` per refusal, never the value itself. The event has `kind` (`"unreadable-value"` or
+`"non-plain-value"`), the `path` the caller received, and `origin`, `resource`, `family`, `variant` and the
+transaction step (`operation`) when they could be read. It cannot change the response: an error it throws, or a
+promise it rejects, is ignored. `diagnostics` keeps receiving the server's own unexpected failures, and nothing is
+reported to both.
+
+HTTP requests are not copied twice. A body that `protocol.handleOperation` / `handleTransaction` parse from raw content
+(as `@aventara/nest` hands it to them) is already plain data. A body your host parsed itself, passed as
+`{ kind: "parsed" }`, is copied like any server-side input.
+
+## Developer SQL in an application transaction
+
+`framework.appTx.$sql` adds a SQL statement to an application transaction. It is written only as a tagged template, and
+every interpolated value is a bound parameter, never part of the SQL text:
+
+```ts
+const post = framework.appTx.Post.create.one({ data: { title, authorId }, select: ["id"] });
+const job = framework.appTx.$sql<{ msg_id: bigint }>`
+  select pgmq.send('jobs', jsonb_build_object('postId', ${post.$ref("id")}))`;
+
+const [created, rows] = await framework.transaction([post, job]);
+// rows is { msg_id: bigint }[]; without <Row> it is unknown[]
+```
+
+- The statement runs in plan order, in the same database transaction as the other steps. If it fails, or a later step
+  fails, everything rolls back.
+- A value is a string, number, boolean, `bigint`, `null`, `Date`, `AvDecimal`, `Uint8Array`, a JSON value (a plain
+  object or array, bound as JSON text, so cast it: `${value}::jsonb`), or a `$ref` to an earlier step's field, which
+  is read after that step ran and then bound. Values are copied like every other input (see above).
+- The SQL text is static. A table or column name cannot come from a value.
+- A later step cannot `$ref` a SQL step's rows (`A2007`/`V1010`).
+- No guard, pipe, hook, interceptor or filter runs around a SQL step. A SQL error is answered as the adapter
+  classifies it (a uniqueness or reference violation is `A2008`, anything else `A3001`).
+- A stage's `ctx.$sql` runs the same bound template at once. Inside a transaction it joins it; outside one it is a plain
+  statement, with no transaction opened around it.
+- It exists only here. `clientTx` has no `$sql`, the ClientContract carries nothing of it, and `/_transactions` cannot
+  express it. The adapter must support it (`@aventara/prisma7-adapter` does wherever it runs transactions); otherwise a
+  plan holding one is refused with `A2002`.
+
+Aventara itself never writes raw SQL. This tagged template is the only way SQL reaches the database, and the SQL is
+yours.
+
+## The agent layer
+
+`agent` is a layer for calls an AI agent makes, served over MCP. It narrows the view of the layer it `extends`
+(`"client"` when left out, or `"application"`, or `"root"`) and never widens it; its stages run after that layer's, and
+each one sees `ctx.$origin === "agent"`:
+
+```ts
+const framework = await createFramework({
+  api: "/api",
+  mcp: "/mcp",
+  adapter,
+  agent: {
+    exposed: true,
+    exemptions: { resources: { Post: { operations: { delete: true } } } },
+    pipelines: { guards: [(ctx) => ctx.$state.user !== undefined] },
+  },
+});
+```
 
-HTTP requests cost nothing extra: a body that `protocol.handleOperation` / `handleTransaction` parse from raw content
-(as `@aventara/nest` hands it to them) is already plain data and is not copied again. A body your host parsed itself,
-passed as `{ kind: "parsed" }`, is copied like any server-side input.
+It compiles to `framework.contracts.agent`, identified by its own hash, and `framework.mcp` is the resolved MCP
+endpoint. A host runs agent calls through `AvProtocol.bind(framework, { origin: "agent" })`, which validates them
+exactly as client calls are validated, against the Agent Contract.
 
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.

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

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

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

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

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

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