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

package/CHANGELOG.md

@@ -1,5 +1,162 @@
 # @aventara/core
 
+## 1.0.0-rc.13
+
+### Minor Changes
+
+- f3b291f: `AvProtocol.fingerprint({ resource, family, variant, args })` on `@aventara/core/protocol` computes a transaction
+  plan step's `fingerprint`, so a client written by hand can send a raw `POST /_transactions` plan: the RFC 8785
+  canonical JSON of the four members over the step's wire-form arguments, hashed with SHA-256, the first 16 bytes in
+  base64url without padding, after `fp1:`. It is the function the server checks a step with, and rejects arguments
+  that are not JSON (a lone surrogate, a non-finite number, a `bigint`, a non-plain object).
+- f3b291f: A new limit, `maxTransactionWrites` (default `20`), counts the write steps of one transaction plan: each `create`,
+  `update`, `upsert` and `delete` step, and each `appTx.$sql` step, since a statement cannot be classed as a read. A
+  plan with more is refused before anything runs (`422 A2009`, one `V1014` at `["operations"]`). It is set like every
+  other limit (`limits` at the root, overridden per limit by a layer) and is part of each Contract's `limits`, so every
+  Contract hash moves with this release. `maxTransactionOperations` still counts every step, reads and `$sql` steps
+  included. The two limits are separate: `maxTransactionWrites` defaults to `20` whatever `maxTransactionOperations` is
+  set to, so raising only the step limit still caps a plan at 20 writes; raise both. The limit counts steps, not rows: a
+  `create` step with nested `$create`s is one write. `POST /_all` is bounded by `maxAll`, not by either plan limit, and its writes do not roll back together.
+  The MCP `transaction` tool's description states the write limit when it is lower than the step limit.
+- f3b291f: `transactionsStyle` takes a third value, `"server"`: the server still opens transactions, and callers send no plans.
+  A forced call (`forceTransaction`), a write the policy checks after it runs and `ctx.$transaction` run in a
+  transaction as under `"interactive"`, while the layer has no `POST /_transactions` route, a plan sent to it answers as
+  that absent route (`404 A2002`, one `V1006` at `["operations"]`), `framework.transaction` refuses a plan of that
+  origin the same way, the generated client has no `tx` or `transaction`, and an MCP agent layer under it has no
+  `transaction` tool. `client: { transactionsStyle: "server" }` keeps forced writes atomic without letting remote
+  callers send multi-step plans. `forceTransaction` under `"none"` is still a startup error; under `"server"` it is
+  allowed. Like `"interactive"`, `"server"` needs an adapter with transactions (`COMPILER_UNAVAILABLE_CAPABILITY`
+  otherwise). The Contract's `transactions` carries the value, so a layer that states it gets a new Contract hash.
+
+### Patch Changes
+
+- 6c3e25c: `AvZ.oneOf(["USD", "EUR"])` is a string field validator for a closed set of values. It builds an anchored pattern of
+  the values, each one's pattern syntax escaped (`"C++"` and `"a.b"` match only themselves), so the Contract gains no
+  new check: the generated client runs it like any `AvZ.regex`, and the field's type stays `string`. A refused value
+  answers `V1003` with the message `Value must be one of "USD", "EUR".` rather than the pattern. An empty list, or a
+  value that is not a string, is refused when the check is built, and the types refuse both. When the types should name
+  the set as a union, use a Prisma `enum`: Aventara carries it into the Contract and the generated client as a literal
+  union.
+- 2aaa27d: A stage's `ctx` create no longer has to write a field that the root's or the `application` overlay's `compute.create`
+  fills. A `ctx` call runs that compute, and the generated types already state which fields it fills (the
+  `computed-fields.generated.ts` file `aventara-build` writes), so `ctx.Payment.create.one({ data })` type-checks without
+  the computed `employeeId`. A field that only the `client` or `agent` overlay computes is still required, because that
+  compute does not run for a `ctx` call. A model whose types state no computed fields keeps every requirement. The agent
+  skill says so.
+- 2aaa27d: Exemptions take one more value, `"read"`, on a field and on a Resource's `fields`. It names every read capability of
+  the field that the layer above offers: a scalar's `select`, `filter`, `order` and `orderNulls`, a relation's `select`,
+  `include`, `filter`, `order`, `pagination` and `reducers`. On `fields` it applies to every field of the Resource.
+
+  - Under `exposed: false` it exposes reading and no write, so a read-only Resource no longer needs every field listed:
+    `Category: { operations: { find: true }, fields: "read" }`.
+  - Under `exposed: true` it hides reading and keeps the writes, which is the write-only field:
+    `passwordHash: "read"`.
+
+  It compiles to the same Contracts as the capability lists it stands for, hash included. Like every exemption it only
+  narrows: it never brings back a capability the layer above hid, and naming a field the layer above hid is refused as
+  before. `fields: "read"` names relations too, so a relation into a Resource the layer leaves out still fails with
+  `COMPILER_DANGLING_RELATION`. The agent skill documents it.
+
+  Read-only now means no nested write either. A relation does not write rows of a Resource its layer cannot write: one
+  that creates nothing (no create or upsert operation, and no field writable on create) takes no `$create`,
+  `$connectOrCreate` or `$upsert`; one that updates nothing (no update or upsert operation, and no field writable on
+  update) takes no `$update` or `$upsert`; one with no delete operation takes no `$delete`. The fields count with the
+  operations for creates and updates, so a Resource whose create operation is hidden but whose fields stay writable on
+  create is still created through its parent. Relation fields count too, even link-only (`$connect`): if a Resource must
+  create nothing, hide its relations' `create` as well. This holds however the Resource was made read-only, `"read"` or listed
+  capabilities, and also when it has no required field, where a nested `$create: {}` was accepted before. `$connect`,
+  `$disconnect` and `$set` stay.
+
+  What happens follows the layer's `exposed`. Under `exposed: false` the relation's directives are the ones the layer
+  grants (by `true` on the Resource or the field, by the relation's `create` or `update`, or by naming the directive), so
+  such a grant is refused at startup with `COMPILER_READ_ONLY_NESTED_WRITE`: let the relation only link,
+  `author: { select: true, create: ["$connect"] }`. Under `exposed: true` the relation inherits its directives, so they
+  are dropped from it and startup succeeds; a call that sends one gets `V1006`, or "Relation … is not writable during
+  update." when the relation's update had nothing else. Dropping one can leave another Resource with nothing writable, and
+  the nested writes into it go the same way. A layer with `exposed: false` below that names a dropped directive, or grants
+  a member that was removed, is refused with `COMPILER_READ_ONLY_NESTED_WRITE`.
+
+  A configuration under `exposed: true` that hides a Resource's deletes, or every way to create or update it, therefore
+  serves Contracts with fewer directives on the relations into it, and its ClientContract hash changes: regenerate the
+  frontend client. Such a configuration was refused at startup before when a hidden field was required, and otherwise
+  accepted nested creates.
+
+- e4e8abd: The same rule now holds for in-process calls. When `state` rejects with an object whose `status` or `statusCode` is
+  the number 401 or 403, an `avClient` call in a Next.js Server Component or Server Action rejects with an `AvAuthError`
+  of code `A4000` or `A4001`, and so does `framework.serverClient.$access.can` given `headers`. Its message is core's own
+  (`"Unauthenticated."` or `"Forbidden."`) and nothing of the rejection reaches the caller. Before, the call rejected
+  with the library's own error. A thrown `AvError` and any other rejection still reject the call unchanged.
+
+  An object whose `status` and `statusCode` are both numbers that disagree, such as `status: 500` beside
+  `statusCode: 401`, is no longer read as a refusal: a route answers it `500 A3000`. A number beside a non-number, such
+  as Better Auth's `status: "UNAUTHORIZED"` beside `statusCode: 401`, is still read by the number.
+
+- e662048: A request whose `state` (the host's `state` option, or the `access` provider's `state`) rejects with an object whose
+  `status` or `statusCode` is the number 401 or 403 is now answered `401 A4000` or `403 A4001`, not `500 A3000`. This is
+  how authentication libraries refuse a bad credential: Better Auth's `APIError` for a wrong API key carries
+  `statusCode: 401`. The answer is core's own envelope (`"Unauthenticated."` or `"Forbidden."`); nothing of the
+  rejection, neither its message nor its code, reaches the caller, and it is not reported to `diagnostics`, as a thrown
+  `AvError("A4000", …)` is not. It applies on every protocol route that seeds state: operations, cached reads,
+  `/_transactions`, `/_all`, `/_access/can`, and MCP tool calls. A thrown `AvError` is still its own outcome, and any
+  other rejection, a 401 beside a 403 included, is still `500 A3000`.
+- 6c3e25c: Field validators now judge every value the caller sent before write compute, and each value once. A value the caller
+  sent is judged after the guards, the pipes and its field pipes, before any compute stage runs, and that includes a
+  field that has a `compute.create` or `compute.update` stage of its own. After compute, only a value compute set or
+  changed is judged: a field the caller left out that compute filled, or a caller's value compute replaced. A compute
+  stage that returns `undefined` or the caller's own value changes nothing, so that value is not judged again. The order
+  is now guards → pipes → validators of the caller's values → write compute → validators of what compute set or changed
+  → hooks.
+
+  A compute stage never sees a value its own validators refuse. A caller value that also breaks a compute stage (a
+  quantity that overflows a total, an unknown currency code handed to `Intl.NumberFormat`) answered `500 A3000` before
+  this release; it now answers `422 A2004` with the issue at the field, and no compute stage runs. A bad caller value is
+  refused even when compute would have replaced it: before this release that value was dropped silently. Codes and
+  issue shapes are unchanged. One answer no longer mixes the two kinds: when a caller value is refused, the computed
+  values are not judged yet. In a transaction plan or a forced call, every literal value is judged before the
+  transaction opens; a resolved `$ref` value and a value a Resource transaction pipe changed are judged at their step,
+  before write compute. The agent skill's stage order says so.
+
+- 6c3e25c: A field the configuration adds (`lifecycle: ["VIRTUAL"]`) with `nullable: false` is now a create requirement, like the
+  adapter's own non-null columns: in each layer that lets a caller write it at create, and where no `compute.create` (the
+  root's or that layer's) fills it, it joins the Contract's `createRequirements.required`. A create without it answers
+  `422 A2004` with `V1000` at the field, before any guard runs, and `framework.application`, `framework.client` and the
+  generated client type it as required. A layer that hides the field creates without it, and an update is unchanged. A
+  nullable added field stays optional. A `compute.create` stage that fills such a field and returns `undefined` answers
+  `500 A3000` with an `AvComputedValueError` in the `diagnostics` sink, as it does for a required database column, and
+  nothing is written.
+
+  This changes the Client Contract, and so its hash, for every configuration with such a field: regenerate the frontend
+  client. A configuration that sent a `nullable: false` virtual input only sometimes must now send it on every create, or
+  state it `nullable: true`.
+
+- a708188: A validator on a field whose type takes no check now names why in the type error, in place of `… is not assignable to
+type 'readonly never[]'`. `AvZ.oneOf([...])` on an enum field reads `Type 'AvZCheck<"string">' is not assignable to
+type '"Error: an enum field takes no check: its enum already is the closed set of values it admits"'`. An enum list
+  says it takes only a list length (`AvZ.minItems`, `AvZ.maxItems`), and a boolean field or list says the same in its
+  own words.
+
+- a9260d2: The agent skills cover what an agent needs without opening `node_modules`:
+
+  - The frontend skill (`avclient skill`) now explains what a call returns (`Date`, `bigint`, `AvDecimal`, `Uint8Array`), which error class each code throws (`AvTransportError` included), `error.cause.issues` for form errors, transactions with `$ref`, and a new `reference/client-setup.md`: `framework.client.ts` (`defineClientConfig`, `env`, `AVENTARA_API_URL`, `generateAt`), regenerating after the server changed, `avclient generate --yes` in CI, and the stale-client error (`A2005`, `AvContractMismatchError`). It also links the docs for agents.
+  - The server skill (`aventara skill`) adds `reference/avz.md` (every `AvZ` check and Json shape builder, `AvZ.infer`) and covers the `policy` and `access` keys, MCP token claims in `ctx.$state.mcp.claims`, the Next.js `state` example, `avDehydrate`/`avHydrate` and server transactions in Next.js, testing with `createFakeAdapter` (what `execute` receives and returns), switching the database or driver, `ctx.$sql`, `ctx.$transaction` and `ctx.$transport`, the compute stage types, and the `AVENTARA_PREBUILT_STALE` fallback.
+  - With `@aventara/access` installed, the skill now says to write Access's own skill with `avaccess skill` (`npx avaccess skill`, or `pnpm exec avaccess skill`).
+  - Corrected: a write-only field is written `"read"` everywhere; a field pipe or compute stage that returns `undefined` keeps the value; a read compute may be a plain function and gets `field`, `value`, `record` and `ctx`.
+  - `CONFIG_FORBIDDEN_IN_OVERLAY` in the error catalog now names `managedElsewhere` as well as a field `definition`.
+
+## 1.0.0-rc.12
+
+### Patch Changes
+
+- fdeee8a: A unique field a layer may not filter on is no longer an identifier of that layer. Exempting its `filter` (a write-only
+  `apiKey: ["select", "filter", "order"]`, an unsearchable `email: ["filter"]`, or a Pick that leaves `filter` out) used
+  to keep the field in the Contract's `identifiers`, so `find.unique`, `update.unique`, `upsert.unique`, `delete.unique`
+  and a nested `$connect`/`$connectOrCreate` still looked a record up by it and answered the row or `A2003`, over every
+  route including `/_all` and `/_transactions`. Such a selector is now refused `V1007` before the Adapter is called, a
+  compound identifier goes with any one of its fields, and the generated client and the server façades no longer offer
+  it. A layer that keeps a unique variant with no filterable identifier left fails at startup with
+  `COMPILER_MISSING_IDENTIFIER`, as hiding the identifier already did: under `exposed: false`, pick `id: ["select",
+"filter"]`, not `id: ["select"]`, to keep `find.unique`. The agent skill's Pick example says so.
+
 ## 1.0.0-rc.11
 
 ### Patch Changes

package/ERRORS.md

@@ -1,6 +1,6 @@
 # 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.
+Every code `@aventara/core` 1.0.0-rc.13 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 }`.
 
@@ -31,7 +31,7 @@ The caller can fix these. The generated client and server-side calls throw the c
 | [`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. |
+| [`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 every value the caller sent after its pipes and before write compute, a field with a compute stage included, so a bad value is refused even when compute would replace it; then a value write compute set or changed, 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. |
@@ -61,8 +61,8 @@ 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. |
+| [`A4000`](https://aventara.razor34.dev/framework/docs/error-codes#a4000) | Unauthenticated. | A guard threw new AvError("A4000", ...), or the host's or access provider's state rejected with an object whose status or statusCode is 401 (an authentication library's refusal, answered with this message only): 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, a stage threw A4001, or the host's or access provider's state rejected with an object whose status or statusCode is 403 (answered with this message only). | 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)
@@ -85,7 +85,7 @@ Each entry of `cause.issues[]` under `A2001`, `A2002`, `A2004`, `A2007` or `A200
 | [`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. |
+| [`V1014`](https://aventara.razor34.dev/framework/docs/error-codes#v1014) | Configured limit exceeded. | A limit above maxListLimit, more steps than maxTransactionOperations, or more write steps than maxTransactionWrites. | 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. |
@@ -105,7 +105,7 @@ Each entry of `cause.issues[]` under `A2001`, `A2002`, `A2004`, `A2007` or `A200
 | [`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. |
+| [`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, or a Resource's managedElsewhere, in application, client or agent. | State it once at the root (`resources.<R>.fields.<f>.definition`, `resources.<R>.managedElsewhere`); an overlay only chooses visibility. |
 
 ## Startup: discovery
 
@@ -135,8 +135,9 @@ Each entry of `cause.issues[]` under `A2001`, `A2002`, `A2004`, `A2007` or `A200
 | [`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_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 it may filter on: a Pick that did not pick one with its filter, or an Omit that hid every one or its filter. | Expose an identifier field with its filter (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_READ_ONLY_NESTED_WRITE`](https://aventara.razor34.dev/framework/docs/error-codes#compiler_read_only_nested_write) | A relation writes rows of a read-only Resource. | A layer with exposed: false grants a relation a write into a Resource it cannot write: $create, $connectOrCreate or $upsert into a Resource with no create or upsert operation and no field writable on create, $update or $upsert into one with no update or upsert operation and no field writable on update, or $delete into one with no delete operation. Read-only, by fields: "read" or by hand-listed capabilities, means no nested write either. Under exposed: true those directives are dropped from the relation instead, and startup succeeds. | Narrow the relation to the directives it may use (author: { select: true, create: ["$connect"] }), or give the target Resource the create, update or delete operation, or a field writable there. |
 | [`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

@@ -53,7 +53,8 @@ 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 write compute and before any interceptor or hook, and its issues
+earlier step. It is checked where validators run (a value you send after every pipe and before write compute, a
+value write compute sets or changes after it) 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:
 
@@ -396,7 +397,7 @@ answers the optional `grantsOf` is asked, before the write, which of its grants
 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
+wire form (an ISO string, a decimal string, a digit string), as a policy read from JSON states it. Where `transactionsStyle` is `"interactive"` or `"server"`, 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`).

package/dist/avz/avz-check.factory.d.ts

@@ -37,6 +37,8 @@ export declare const minSize: (minimum: number) => AvZCheck<"bytes">;
 export declare const size: (exact: number) => AvZCheck<"bytes">;
 /** A string `pattern` matches (a JavaScript regular expression; its flags count). */
 export declare const regex: (pattern: RegExp) => AvZCheck<"string">;
+/** A string equal to one of `values`, compared exactly. */
+export declare const oneOf: <const Values extends readonly string[]>(values: Values & (Values extends readonly [] ? never : unknown)) => AvZCheck<"string">;
 /** A string containing `value`. */
 export declare const includes: (value: string) => AvZCheck<"string">;
 /** A string starting with `prefix`. */

package/dist/avz/avz-check.factory.js

@@ -68,6 +68,18 @@ export const regex = (pattern) => {
         pattern: { source: pattern.source, flags: pattern.flags },
     });
 };
+const PATTERN_SYNTAX = /[\\^$.*+?()[\]{}|/]/g;
+export const oneOf = (values) => {
+    if (!Array.isArray(values) || values.length === 0) {
+        throw new TypeError("AvZ.oneOf: give at least one value.");
+    }
+    const escaped = values.map((value) => text("oneOf", value).replace(PATTERN_SYNTAX, "\\$&"));
+    return build({
+        check: "string_format",
+        format: "regex",
+        pattern: { source: `^(?:${escaped.join("|")})$`, flags: "" },
+    });
+};
 export const includes = (value) => build({
     check: "string_format",
     format: "includes",

package/dist/avz/avz.d.ts

@@ -134,6 +134,12 @@ export declare class AvZ {
     static readonly size: (exact: number) => AvZCheck<"bytes">;
     /** A string the pattern matches: a JavaScript regular expression, flags included. */
     static readonly regex: (pattern: RegExp) => AvZCheck<"string">;
+    /**
+     * A string equal to one of `values`: an anchored pattern of them, each
+     * escaped, whose issue lists the values. The field's type stays `string`;
+     * for a closed set the types should name, use a database enum.
+     */
+    static readonly oneOf: <const Values extends readonly string[]>(values: Values & (Values extends readonly [] ? never : unknown)) => AvZCheck<"string">;
     /** A string containing `value`. */
     static readonly includes: (value: string) => AvZCheck<"string">;
     /** A string starting with `prefix`. */

package/dist/avz/avz.js

@@ -323,6 +323,7 @@ export class AvZ {
     static minSize = checks.minSize;
     static size = checks.size;
     static regex = checks.regex;
+    static oneOf = checks.oneOf;
     static includes = checks.includes;
     static startsWith = checks.startsWith;
     static endsWith = checks.endsWith;

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

@@ -7,8 +7,9 @@ export type AvContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "CO
  | "COMPILER_RESERVED_RESOURCE_NAME"
 /**
  * A layer exposes a unique operation variant (`find.unique`, `update.unique`,
- * `delete.unique`, `upsert.unique`) and no complete identifier of its Resource:
- * a Pick that did not pick one, or an Omit that hid every one.
+ * `delete.unique`, `upsert.unique`) and no complete identifier of its Resource
+ * it may filter on: a Pick that did not pick one with its filter, or an Omit
+ * that hid every one or its filter.
  */
  | "COMPILER_MISSING_IDENTIFIER"
 /**
@@ -19,6 +20,16 @@ export type AvContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "CO
  * not writable on create with a reference field neither writable nor computed.
  */
  | "COMPILER_HIDDEN_REQUIRED_FIELD"
+/**
+ * A Pick layer lets a relation write rows of a Resource it cannot write: a
+ * nested `$create`, `$connectOrCreate` or `$upsert` into a Resource with no
+ * create or upsert variant and no field writable on create, a nested
+ * `$update` or `$upsert` into one with no update or upsert variant and no
+ * field writable on update, or a nested `$delete` into one with no delete
+ * variant (an Omit layer drops those directives instead). `path` is the
+ * relation's exemption.
+ */
+ | "COMPILER_READ_ONLY_NESTED_WRITE"
 /**
  * A field validator cannot apply: it is not a check built with `AvZ`, it does
  * not fit the field's type (`AvZ.maxLength` on an `int` field, `AvZ.maxItems`

package/dist/compiler/contract-compiler-diagnostic.guidance.js

@@ -71,14 +71,19 @@ export const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE = {
     },
     COMPILER_MISSING_IDENTIFIER: {
         message: "A unique operation has no identifier.",
-        cause: "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.",
-        fix: "Expose an identifier field (id, or every field of one unique), or exempt the unique variants.",
+        cause: "A layer exposes a unique variant (find.unique, update.unique, delete.unique, upsert.unique) and no complete identifier of the Resource it may filter on: a Pick that did not pick one with its filter, or an Omit that hid every one or its filter.",
+        fix: "Expose an identifier field with its filter (id, or every field of one unique), or exempt the unique variants.",
     },
     COMPILER_HIDDEN_REQUIRED_FIELD: {
         message: "A layer that creates a Resource hides a required field.",
         cause: "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.",
         fix: "Expose the field, give it a compute.create stage, or exempt the layer's create operations.",
     },
+    COMPILER_READ_ONLY_NESTED_WRITE: {
+        message: "A relation writes rows of a read-only Resource.",
+        cause: 'A layer with exposed: false grants a relation a write into a Resource it cannot write: $create, $connectOrCreate or $upsert into a Resource with no create or upsert operation and no field writable on create, $update or $upsert into one with no update or upsert operation and no field writable on update, or $delete into one with no delete operation. Read-only, by fields: "read" or by hand-listed capabilities, means no nested write either. Under exposed: true those directives are dropped from the relation instead, and startup succeeds.',
+        fix: 'Narrow the relation to the directives it may use (author: { select: true, create: ["$connect"] }), or give the target Resource the create, update or delete operation, or a field writable there.',
+    },
     COMPILER_INVALID_VALIDATOR: {
         message: "A field validator cannot apply.",
         cause: "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.",