@aventara/core 0.1.0-pilot.3 → 1.0.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,338 @@
+# @aventara/core
+
+## 1.0.0-rc.0
+
+### Major Changes
+
+- First release candidate of Aventara 1.0. The public API is now considered stable; changes before 1.0.0 are possible
+  based on feedback.
+
+### Minor Changes
+
+- 24ffbab: A `Json` field can now have a type. Build its shape with `AvZ` from the new entry `@aventara/core/json` and declare it
+  on the field: `fields: { Post: { meta: { json: AvZ.object({ title: AvZ.string() }) } } }`. `framework.application`,
+  `framework.client`, `appTx`/`clientTx` and the generated client then read and write the field as that type instead of
+  generic JSON, and every write to it — create, update, upsert, nested writes and transaction steps, a value taken from
+  an earlier step included — is checked before the database is asked: a value out of shape is refused with `A2004` and
+  one issue per problem at its exact path (`V1000` missing key, `V1001` wrong type, `V1002` outside an enum or literal,
+  `V1004` integer out of range, `V1005` unknown key). Shapes are types only and their objects are closed; reads and
+  filters are never checked. Only a field the adapter discovered as `Json` takes a shape, and a Zod schema is not
+  accepted. The shape is part of the ClientContract (as JSON Schema), so declaring or changing one changes its hash:
+  regenerate the client. `@aventara/core` now depends on `zod` (`^4.6.5`), which only `@aventara/core/json` loads. The
+  shape types `AvZShape`, `AvZObject`, `AvZOptional` and `AvZNullable` are exported too, so a project that emits
+  declarations can export a shape or a configuration holding one.
+- 24ffbab: Transaction steps can now reference earlier results in `$connect`, `$disconnect`, `$set`, `$connectOrCreate`'s `where`,
+  a `cursor`, a unique `where`, and anywhere in a filter — `AND`/`OR`/`NOT` and relation filters included, with every
+  scalar operator. `framework.appTx` and `framework.clientTx` type each position by what it holds: a filter's value,
+  `equals` and `not` take a source of the field's own type (nullable only where the field is, and a `null` then matches
+  the rows where the field is unset, as a literal `null` does); a unique key, a `cursor`, a comparison or a text operator a
+  non-null source; `in`, `notIn`, `hasEvery` and `hasSome` a list field; `has` one value. The server checks the same rule
+  before anything runs and refuses a mismatch with `A2007`/`V1011`. Nested relation writes take references at any depth
+  too: the values and keys of nested `$create`, `$update` and `$upsert` data, and the `where` of a nested `$update`,
+  `$delete` or `$upsert`. A reference in an ordering or a projection's nested `where` is still refused.
+- 24ffbab: **Behaviour changes:** server-side calls now copy what you pass them. `framework.application`, `framework.client`,
+  `framework.execute`, `framework.executeTransaction` and the `appTx`/`clientTx` builders read your arguments once, when
+  you call them, into plain data the framework owns; validation, guards, pipes, computed values and the adapter see only
+  that copy, so changing or revoking your object afterwards (an Immer draft after `produce`) no longer affects the
+  operation. A live Proxy (Vue `reactive`, MobX) still works.
+
+  A value that cannot be read — a revoked Proxy, a getter that throws — or that is not plain data — a class instance or a
+  `Map`; `Date`, `Decimal` and `Uint8Array` are fine — is now refused as your request's error: `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. Before, it was `A3000` (an internal error) or, from `appTx`/`clientTx`, a `TypeError`
+  thrown at the builder call; a builder now never throws, and `framework.transaction([...])` answers the refusal. The same
+  holds for a `framework.execute` / `executeTransaction` request object that cannot be read. Two answers change for
+  inputs that were never supported: a class instance where an object of arguments belongs (`where`, `data`, …) was
+  accepted or failed as `A3000`, and is now refused; inherited, non-enumerable and symbol keys are dropped, as JSON drops
+  them.
+
+  New optional root setting `misuse` (types `FrameworkMisuseSink`, `FrameworkMisuseEvent`), beside `diagnostics`: it
+  receives one event per refused value — its `kind` (`"unreadable-value"` or `"non-plain-value"`), the `path` the caller
+  received, and the operation's `origin`, `resource`, `family`, `variant` and transaction step (`operation`) when they
+  could be read — never the value itself. It cannot change a response; an error it throws or a promise it rejects is
+  ignored. `diagnostics` keeps receiving only unexpected failures.
+
+  HTTP requests are not copied again: a body the protocol parses from raw content is already plain data.
+
+  The generated client reads your arguments through one guard too: a value that cannot be read is refused with a
+  `TypeError` naming where (`… the value at /where/id could not be read.`) before anything is sent, and a `tx` builder
+  never throws — `transaction([...])` rejects with that error instead. Regenerate the client to pick this up.
+
+- 24ffbab: A nested `$update` or `$delete` through a to-many relation filters plain fields only on Prisma 7, and Aventara now says
+  so up front: a relation filter in its `where` — `{ posts: { $update: { where: { category: { name: "x" } }, … } } }`, at
+  any depth, under `AND`/`OR`/`NOT` too — is refused with `A2004` / `V1006` before the database is asked, and is a type
+  error in `framework.application`, `framework.client`, `appTx`/`clientTx` and the generated client. Before, it reached
+  Prisma and fail as `A3001`. A to-one relation's nested filter keeps relation filters. The limit is stated by the adapter
+  in the Contract (`nestedWriteFilter: "scalar"`), so the ClientContract hash changes: regenerate the client.
+
+### Patch Changes
+
+- 24ffbab: **Behaviour changes:** `@aventara/core` exports fewer names. Every name it no longer exports was undocumented; every
+  documented name (`createFramework`, `FrameworkConfig`, `defineFields`, `Decimal`, `FrameworkError`, the pipeline types and
+  the rest) is still exported. Types shown in a hover or an error message still resolve; what changes is only which names
+  your own code can import. `OperationScope` was a deprecated alias: use `RequestOrigin`.
+
+  What Aventara's own packages need from core moved to `@aventara/core/internal`. It is not public API: it carries no
+  stability promise, and any of its exports may change or disappear in any release. Applications import from
+  `@aventara/core`.
+
+  Moved to `@aventara/core/internal`: `AdapterField`, `AdapterFieldKey`, `AdapterFieldMap`, `AdapterIdentifier`, `AdapterLifecycleTrait`, `AdapterOperation`, `AdapterOperationExecutor`, `AdapterRelationField`, `AdapterResource`, `AdapterScalarField`, `AdapterScalarFieldKey`, `advertisedDirectives`, `advertisedReducers`, `ApplicationContractView`, `ApplicationOperationRequest`, `ApplicationTransactionRequest`, `AVENTARA_PROTOCOL_VERSION`, `BUILT_IN_SCALARS`, `BuiltinNonRow`, `canonicalizeContract`, `canonicalizeJson`, `CanonicalJsonError`, `ClientContractHashInput`, `ClientOperationRequest`, `ClientProtocolIdentity`, `ClientTransactionRequest`, `compileContracts`, `computeClientContractHash`, `computeOperationFingerprint`, `DEFAULT_CONTRACT_LIMITS`, `FrameworkOperationRequest`, `FrameworkTransactionRequest`, `isOperationVariantAvailable`, `LIFECYCLE_TRAITS`, `OPERATION_CODES`, `OperationFingerprint`, `PROJECTION_SCOPES`, `projectionScopeOf`, `resolveFrameworkConfig`, `SemanticOperationArguments`, `TRANSACTION_CAPABILITIES`, `validateClientContractStructure`, `VALIDATION_CODES`, `verifyClientContractHash`, `WRITE_SCOPES`, `writeScopeOf`.
+
+  No longer exported from any entry: `advertisedDirectivesAt`, `advertisedReducersAt`, `ClientContractStructureVerdict`, `ContractCompilationResult`, `DeferredOperation`, `EffectiveFieldKeyAt`, `holdsAt`, `holdsInAnyScope`, `isOperationFingerprint`, `isTransactionReferenceCandidate`, `isTransactionReferenceObject`, `operationFailure`, `OperationFingerprintNode`, `OperationInternalErrorCode`, `operationNoMatch`, `OperationScope`, `operationSuccess`, `OperationValidationResult`, `RelationMutationAction`, `ResolvedFrameworkConfig`, `ResolvedFrameworkScopeConfig`, `ResolvedPipelineConfig`, `ScalarFilterInput`, `ScalarMutationAction`, `transactionCommitted`, `TransactionCreateDataInput`, `transactionInfrastructureFailure`, `TransactionOperationArgumentsFor`, `transactionOperationFailure`, `TransactionPlan`, `TransactionReferenceCandidate`, `TransactionScalarValue`, `TransactionUpdateDataInput`, `validateFrameworkConfig`, `validateOperationArguments`, `VALIDATION_CODE_MESSAGES`.
+
+- 24ffbab: Each package ships its `CHANGELOG.md`, so the release notes are in the installed package beside the README.
+- 24ffbab: A `null` given to a filter operator that has no `null` meaning — `gt`, `contains`, `in`, `has`, `mode`, `isEmpty`,
+  `path`, a JSON `string*` operator and the rest — is now refused as `A2004` / `V1001` at that operator, before the
+  database is asked, and is a type error. Before, it reached the database and failed as `A3001`. `equals: null` and
+  `not: null` still match the rows where a nullable field is unset or set.
+- 24ffbab: **Diagnostics:** if your own HTTP host mounts only some of `protocol.surface()` and a request for a route it left out
+  reaches `protocol.answerAbsent`, your `diagnostics` sink now receives one `A3000` diagnostic naming the route: an
+  `"operation"` diagnostic with the Resource, family and variant (a `"transaction"` one for `/_transactions`), whose
+  `error` is named `"UnmountedRouteError"` and says which `surface()` entry to mount. The caller's `500 A3000` answer is
+  unchanged, and a route your ClientContract does not offer is still answered without a report. `@aventara/nest` mounts
+  every route, so its applications are not affected.
+- 24ffbab: **Diagnostics:** a `FrameworkError` you throw on purpose with an `A3xxx` code — from a guard, pipe, hook, interceptor,
+  computed field or adapter, or returned by a filter — now reaches your `diagnostics` sink once, as the error you threw,
+  under its code, with `deliberate: true` on the diagnostic. Before, the caller received the generic `A3000`/`A3001` and
+  your message and issues were reported nowhere. A failure Aventara did not expect carries no `deliberate` field, so a sink
+  can tell the two apart. What the caller receives is unchanged, and `A2xxx`/`A4xxx` outcomes are still not reported.
+- 24ffbab: **Diagnostics:** a result that does not match its Contract — an adapter row with a wrong value, a missing field, a
+  result of the wrong shape — now reaches your `diagnostics` sink as one `A3000` diagnostic whose `error` (`name`
+  `"OutputValidationError"`) names the operation and lists the problems (`error.issues`). Before, the caller got `A3000`
+  and the sink got nothing unless reading the result threw. The same now holds for a computed field: a read or write
+  behavior that returns a value its field refuses is reported as an error named `"ComputedValueError"` with the issues
+  (before, the sink received only the field's location). What the caller receives is unchanged. A filter that inspects
+  the error now sees that error instead of a `FrameworkError` with code `A3000`.
+
+  The `FrameworkError` documentation now states the message rule: for any code outside `A3xxx`, the message is sent to
+  the caller exactly as written, so it must not carry database text, SQL, a stack, a path or a secret.
+
+- 24ffbab: **Behaviour changes:** Pipelines and guards read where a request came from as `request.origin` (was `request.scope`).
+  The same property is renamed everywhere it means `"application"` or `"client"`: the pipeline context
+  (`context.origin`), the request objects `framework.execute` and `framework.executeTransaction` take
+  (`{ origin: "client", … }`), the context a computed field's behaviour receives, and every diagnostic the diagnostics
+  sink receives. There is no `scope` alias: replace `scope` with `origin` in those places. Nothing sent over HTTP
+  changes.
+
+  The Nest host's log line for an internal failure now reads `(client origin, request …)` instead of
+  `(client scope, request …)`.
+
+- 24ffbab: **Types:** a guard, pipe, hook, interceptor or filter typed with `Guard`, `Pipe`, `BeforeHook`, `AfterHook`,
+  `Interceptor` or `Filter` without a model type now type-checks wherever one typed for your model is expected, so you
+  can put it in an `as const` configuration (the shape `aventara init` writes), in `client.pipelines` or
+  `application.pipelines`, and mix it with model-typed callbacks in one list. Before, TypeScript refused it there, and
+  the way around it was a structural parameter type such as `Pick<PipelineContext, "family" | "transport">`, which you no
+  longer need (it keeps working). A callback typed for a different model is still refused.
+- a973e89: An issue your own code throws now reaches the caller with the message you wrote. When a pipe, guard, hook, interceptor,
+  filter or computed behavior throws `new FrameworkError("A2004", { message, issues: [{ path, code, message }] })`, each
+  issue's `message` is sent as written instead of the generic text for its code — standalone, inside a transaction plan,
+  and over HTTP. The message must have a visible character and be at most 1,000 characters; otherwise the caller receives
+  the generic text for the code and your message goes to the `diagnostics` sink. The rest is unchanged: an issue whose
+  `code` is not a validation code (`V1000` and up) is dropped, a `path` that does not name a member of the request's own
+  arguments is dropped, an `A3xxx` outcome still carries no issues, and an issue an Adapter throws still carries the
+  generic text for its code.
+- 1e65e9a: `framework.execute(request)` and `framework.executeTransaction(request)` now check the request object itself before
+  running it. A wrong one — not an object, a missing or empty `requestId`, an `origin` other than `"application"` or
+  `"client"`, a client request without a `protocol` of `{ version, hash }`, malformed `transport`, `protocol` or
+  `transport` on an application request, or a missing or non-string `resource`, `family` or `variant` — is answered
+  `A2004` with one issue per wrong member at its own path (`["requestId"]`, `["protocol", "hash"]`, …), and nothing
+  runs: no guard, pipe or hook, no adapter call. Before, most of these answered `A3000` (an internal error) or ran as
+  though the request were well formed. A well-formed request is unchanged, including `A2005`/`A2006` for a stale
+  `protocol` and `A2001` for an unknown Resource.
+- a973e89: A write that sets an optional relation both ways — its reference field and the relation itself, such as `categoryId`
+  and `category: { $connect: … }` in the same record — is now refused before it reaches the database, exactly like a
+  required relation: `A2004` with a `V1012` issue at the relation, message `Set "categoryId" or "category", not both.`
+  Before, the database refused it and the caller received `A3001`. It applies to `create`, `update` and `upsert`, to
+  nested writes at any depth, and to each step of a transaction.
+
+  The discovery artifact now records, for each relation, the fields that hold its reference (`references` on each edge
+  of `referentialActions`), and a create requirement no longer repeats them. Regenerate your artifact with
+  `npm run aventara:prepare` (or `aventara-prisma7-generate`); an artifact from an earlier version is refused with a
+  message that says so. An adapter's `referentialActions` edges carry the same `references` member.
+
+- a973e89: With the Prisma adapter, a record that writes one relation through its reference field and another relation directly —
+  such as `authorId` beside `category: { $connect: … }` — is now refused before it reaches the database: `A2004` with a
+  `V1012` issue at the relation write, message
+  `Use relation fields only, or reference fields only, in one record: "authorId" is a reference field and "category" is a relation.`
+  Before, Prisma refused it and the caller received `A3001`. Write the record's relations all as relations
+  (`author: { $connect: … }, category: { $connect: … }`) or all through their fields (`authorId`, `categoryId`). A
+  reference field beside a relation that holds no reference on that side — `mentorId` beside `posts: { $create: … }` on
+  an author — is unchanged and still accepted. It applies to `create`, `update` and `upsert`, to nested writes at any
+  depth, and to each step of a transaction.
+
+  The limit is part of the Contract: a Contract whose data source has it carries `referenceWrites: "uniform"`, so the
+  Contract hash of every Prisma-backed application changes. Regenerate your discovery artifact
+  (`npm run aventara:prepare`) and your generated client (`avclient generate`). An adapter states the limit with
+  `referenceWrites: "uniform"` in its model; without it, nothing changes.
+
+- 1e65e9a: A write that sets a required relation both ways — its reference field and the relation itself, such as `authorId` and
+  `author: { $connect: … }` in the same `data` — is now refused before it reaches the database: `A2004` with a `V1012`
+  issue at the relation (`["arguments", "data", "author"]`), message `Set "authorId" or "author", not both.` It applies to
+  `create`, `update` and `upsert`, to nested writes at any depth, and to each step of a transaction, and nothing is
+  written. Before, the database refused it and the caller received `A3001`. Writing either one alone is unchanged.
+- 1e65e9a: A guard, pipe, hook, interceptor or filter typed for any Resource — `Guard`, `Pipe`, `BeforeHook` and the rest without a
+  model argument, or a callback whose context is a `Pick<PipelineContext, …>` — in the root `pipelines` no longer erases
+  `framework.application`, `framework.client`, `framework.appTx` and `framework.clientTx` to an untyped object. They stay
+  typed from your adapter's model with any mix of stage types, at the root and in the `application` and `client`
+  overlays, with or without `as const`, and a callback written inline is still told your Resource names.
+- 24ffbab: **Behaviour changes, transactions:** an object carrying `$ref` in a step's `args` is now copied when you call
+  `framework.executeTransaction`, like the rest of your arguments. Where a `$ref` belongs (a field value, a filter
+  value, a `$connect` key) it is answered exactly as before; changing it after the call no longer affects the plan.
+  Placed anywhere else — the whole `where`, a whole relation value, the whole `data` — a member of it that cannot be
+  read (a getter that throws, a revoked Proxy) is now your request's error, `A2004` with one `V1001` at that member's
+  path and `cause.operation`, reported to `misuse`; before, it was `A3000`. The framework never runs a getter inside an
+  object that carries `$ref`, wherever it stands, so such a getter is refused unread.
+
+  A value whose first read throws is now refused even if reading it again would succeed: `A2004`/`V1001` at the object
+  or array whose read failed. Before, it was copied from the second read.
+- 2d00ad7: An issue your own code throws from a transaction step now keeps its `path`. A pipe, guard, hook, interceptor,
+  filter or computed behavior does not know where its operation stands in a plan, so it writes the path as it would for
+  a single call — `["arguments", "data", "name"]`. Inside `framework.transaction`, `framework.executeTransaction` and
+  `POST /_transactions` that path is now checked against that step's own arguments and sent as
+  `["operations", i, "args", "data", "name"]` beside `cause.operation`; before, it was dropped and the issue reached the
+  caller without a path. A path written as `["operations", i, "args", …]` with the step's own index is accepted as
+  before, and a path that does not name a member of the step's arguments is still dropped.
+- 384a50c: **Behaviour changes, transactions:** every issue about a transaction step's arguments now names where it is
+  in the plan, `["operations", i, "args", …]`, beside `cause.operation: i`. Before, the framework's own checks — a wrong
+  type, an unknown field or operator, a structural limit, a Json value out of its `AvZ` shape, a value that is not valid
+  JSON — answered `["arguments", …]` inside a plan while a bad `$ref`, a refused value and a step that depends on a
+  cascaded delete already answered `["operations", i, "args", …]`; now one plan uses one spelling, through
+  `framework.transaction`, `framework.executeTransaction` and `POST /_transactions` alike. A single call is unchanged
+  (`["arguments", …]`). If your code reads `issue.path` from a transaction's answer, drop the `"operations", i, "args"`
+  prefix to get the path inside that step's arguments. `@aventara/testing`'s protocol corpus row "a client-hidden
+  field — /_transactions" and `fixtures/protocol-v1.json` carry the new path.
+- d43d1cc: **Types:** `diagnostic.deliberate` now type-checks on any `FrameworkDiagnostic`, without checking
+  `diagnostic.kind` first, so a `diagnostics` sink can log it for every report. It is `true` only on an `"operation"`
+  diagnostic for a `FrameworkError` you threw on purpose with an `A3xxx` code, and always absent on a `"transaction"`
+  diagnostic, which reports the transaction's own failure (`A3002`). Before, reading it on the union was a TypeScript
+  error (`TS2339`).
+- 3f98749: **Types:** `framework.application`, `framework.client`, `framework.appTx` and `framework.clientTx` now follow
+  your `restrictions` the way the generated client does. A field whose capability you turn off — `select`, `filter`,
+  `order`, `create` or `update` — is refused in that position and left out of the result types; an operation you turn
+  off (`operations: { delete: { unique: false } }`) is not on the façade; and a unique operation disappears when its
+  only identifier is hidden. Each façade reads its own layer: `framework.client` the root restrictions with
+  `client.restrictions` over them, `framework.application` the root restrictions with `application.restrictions` over
+  them — so `hidden` now applies to `framework.application` too. Before, only `client`'s `hidden` was reflected, so with
+  `passwordHash: { capabilities: { select: false, … } }` a call such as
+  `framework.client.User.find.many({ select: ["passwordHash"] })` compiled and every result type carried `passwordHash`.
+  Nothing changes at runtime: the server refused those calls before and still does. A restriction value typed as a plain
+  `boolean` rather than `true`/`false` still leaves the field as it was.
+- 032f792: **Behaviour changes, transactions:** an error about a transaction step itself — rather than its arguments — now
+  names the step too, so every path in a transaction's answer is a path through the request you sent: an unknown or
+  hidden Resource is at `["operations", i, "resource"]`, a fingerprint that does not match at
+  `["operations", i, "fingerprint"]`, a missing or unknown key on the step at `["operations", i, "<key>"]`, and a step
+  that is not an object at `["operations", i]`. An operation the step cannot run points at the key that is wrong:
+  `["operations", i, "family"]` when the family is not a string, not a standard family, or one the Resource offers no
+  variant of; `["operations", i, "variant"]` when the family is right and the variant is not (unknown, not offered or
+  restricted for it). Before, these answered `["resource"]`, `["operation"]`, `["fingerprint"]` and `["<key>"]`.
+  `cause.operation` and the outcome code are unchanged: an unknown Resource is still `A2001`, an unavailable operation
+  `A2002`. `framework.transaction([...])` refuses an entry that is not a handle, or one handle placed twice, at
+  `["operations", i]`. A single call is unchanged. `@aventara/testing`'s protocol corpus and `fixtures/protocol-v1.json`
+  carry the new paths.
+- dbe6961: **Behaviour changes:** a single call to an operation a Resource does not offer now names the key of the
+  request that is wrong instead of `["operation"]`, which no request has: `["family"]` when the family is not a standard
+  one or the Resource offers none of its operations, `["variant"]` when the family is right and the variant is not. This
+  holds for `framework.execute` and for an HTTP route, whose `/_resources/:resource/:family/:variant` segments are named
+  by those same keys. The code is unchanged (`A2002` / `V1006`), and so is `["resource"]` for an unknown Resource.
+  `@aventara/testing`'s protocol corpus and `fixtures/protocol-v1.json` carry the new paths.
+
+## 0.1.0-pilot.4
+
+### Patch Changes
+
+- f37dcd6: The documentation shipped with the package — the comments an editor shows on hover, and the README — now describes
+  what each export does, how to use it, what it returns and what it throws. Notes about how the package was built and
+  why are no longer part of what is published.
+
+  The declarations a generated client copies from `@aventara/core` carry the same documentation.
+
+## 0.1.0-pilot.3
+
+## 0.1.0-pilot.2
+
+### Patch Changes
+
+- c2a3b7c: A `bigint` value outside the signed 64-bit range is refused as `A2004` with a `V1004` issue at its path, from the wire
+  and from the application alike, before any pipeline or adapter runs. Before this release it reached the database and
+  answered `A3001`.
+- e69e88d: The published packages are written for the people who use them. The JavaScript ships without comments; the type
+  declarations keep their documentation, and it, the error messages, the protocol fixtures' labels and the comments in a
+  generated client no longer carry the project's internal development notes.
+- ab58424: A pipe's output is checked against the server's own rules before it reaches the adapter. The request is validated
+  against the caller's Contract; after each pipe, the arguments are validated against the Core Contract (plus fields the
+  caller's scope adds), so a pipe may still write what the caller cannot — a field the client Contract hides, such as a
+  password hash — but not what the server cannot store. A refusal is the new internal code `A3004 PIPE_OUTPUT_INVALID` (HTTP
+  500). The caller receives only the generic `A server pipeline produced invalid arguments.`, like every internal
+  failure; the pipe (`pipes[i]` and its function name), the operation, the offending field and its V-code go to the
+  diagnostics sink as a `PipeOutputError`, and `@aventara/nest` writes them into its error log line. Nothing reaches the
+  adapter. This holds for operations and transaction steps alike (a plan answers with `cause.operation`). Generated
+  clients map `A3004` to `InternalError`; the protocol fixtures in `@aventara/testing` include an `A3004` row.
+- 23937f8: A create that lacks a value the database requires is refused as `A2004` with a `V1000` issue at the value's path,
+  instead of reaching the database and answering `A3001`. It covers `create.one`, every row of `create.many`, `upsert`'s
+  `create` branch, nested `$create` (and `$connectOrCreate`/`$upsert` creates) at any depth, and transaction steps
+  (`["operations", i, "args", …]`). A required relation is satisfied by writing it or every scalar that holds its
+  reference; a nested create never needs the relation it is created through. Defaults, `@updatedAt`, autoincrement,
+  optional and list columns are never required. The check runs after pipes and computed behaviours, so a value they
+  supply counts.
+
+  An adapter states the requirements through the new optional `Adapter.createRequirements`; the Prisma 7 adapter reads
+  them from the generated client's create inputs at generate time and records them in the discovery artifact, so the
+  artifact must be regenerated (`aventara:prepare`).
+
+## 0.1.0-pilot.1
+
+### Patch Changes
+
+- a45f8a8: The `400 A2000` for a request without its identity headers now says which one: `cause.message` is "The
+  Aventara-Contract-Hash header is missing." (or "The Aventara-Protocol-Version header is missing.", or both, naming both),
+  instead of the generic "The request is malformed and cannot be interpreted." It names headers only and echoes no value.
+  The code, status and every other `A2000` are unchanged. The protocol fixtures in `@aventara/testing` check the new messages, with a row
+  for a request with neither header.
+- 799346e: The package READMEs (each package's npm page) are rewritten for the people who use the packages. The Prisma 7
+  adapter's README now states the actual behaviour of a to-many relation or `$count` projected on
+  `update.many`/`create.many`: a validation refusal, `A2004` with `V1008`, before any statement runs (it said `A3001`).
+  Every install or run command names the `@pilot` dist-tag.
+
+## 0.1.0-pilot.0
+
+### Minor Changes
+
+- First pilot release of `@aventara/core`: the framework itself — configuration, Contracts, validation, operations,
+  pipelines and transactions — independent of any HTTP server or ORM.
+
+  - **`createFramework(config)`** builds a Framework from an adapter and a configuration. The configuration is typed
+    against the adapter's model, so restriction keys, behaviors, `dependsOn` and pipeline `resource` guards are checked
+    against the Resources and fields that exist; `defineFields` declares the fields a configuration adds so the rest of
+    it can name them.
+  - **Contracts.** The adapter's capabilities and your configuration compile into the Core, Application and Client
+    Contracts at startup. The ClientContract is what clients are generated from, and its hash identifies it. A scoped
+    configuration (`application`, `client`) only narrows what the root allows, and a configuration asking for a
+    capability the root or the adapter does not offer fails at startup with `COMPILER_UNAVAILABLE_CAPABILITY` at its
+    path. A value the Contract cannot represent, or an invalid ClientContract (`COMPILER_INVALID_CLIENT_CONTRACT`), also
+    fails at startup.
+  - **Capabilities by argument position.** A relation the database projects or writes only in some operations is
+    advertised only there; asking for it elsewhere is refused with `A2004` (`V1008` for a projection, `V1006` for a
+    write) before any query, and is a type error.
+  - **Typed calls.** `framework.application.<resource>.<family>.<variant>(args)` and `framework.client.…` take arguments
+    and return results typed from the Contract (`OperationResultFor`); an optional second argument, `ExecutionOptions`
+    (`{ requestId }`), sets the request id every pipeline context, adapter call and diagnostic of the call carries.
+  - **Transactions.** `framework.appTx` and `framework.clientTx` build typed plans whose steps can use earlier steps'
+    results through `$ref`; `framework.transaction(steps, options)` runs them. A step that depends on rows an earlier
+    step's cascading delete removed is refused before the plan runs (`A2004`/`V1019`).
+  - **Fields and pipelines.** Computed and virtual fields under `application.fields` and `client.fields`; guards, pipes,
+    before and after hooks, interceptors and filters.
+  - **Scalars.** `Decimal` (string-backed; `toJSON()` writes its digits; a non-string argument throws a `TypeError`),
+    `JsonValue`, and the `ApplicationScalarForms` / `WireScalarForms` maps. A `Date`, `Decimal` or `Uint8Array` at a
+    filter position is shorthand for equality.
+  - **`@aventara/core/protocol`**, a second entry point: the HTTP protocol as data and pure functions a host mounts —
+    `AvProtocol.headers`, `httpStatus`, `scalarFormats`, `normalizeEntrypoint` and `isOperationResponse`, and
+    `AvProtocol.bind(framework)` with `surface()` (the routes to mount), `handleOperation`, `handleTransaction`,
+    `encodeContract` (`GET /_contract`, with `ETag` and `304`), `answerAbsent`, `failure`, and the decoders and encoders
+    under them. A request without an identity header answers `400 A2000`, a wrong protocol version `A2006`, a stale
+    contract hash `A2005`; a body larger than `limits.maxRequestBytes` `413 A2010`, a content type other than
+    `application/json` `415 A2011`; every `405 A2012` carries `Allow`. A malformed request never throws: it answers
+    `400 A2000`.
+  - **The entrypoint** is normalized once: `"api"`, `"/api/"` and `"//api//"` become `"/api"`, `"/"` becomes `""`, and an
+    entrypoint that is not a plain path (whitespace, a scheme, a query, a `..` segment, a `%` and the like) fails at
+    startup with `CONFIG_INVALID_VALUE`.
+  - Every export has a `default` condition, so a CommonJS project can `require()` the package.

package/README.md

@@ -11,9 +11,9 @@ Core is ORM- and transport-agnostic: it imports neither Prisma nor NestJS. An ap
 ## Install
 
 ```bash
-npx @aventara/cli@pilot new my-api     # a new NestJS project with Prisma and Aventara
-npx @aventara/cli@pilot init           # or: add Aventara to an existing NestJS 12 project
-npm install @aventara/core@pilot       # the package on its own
+npx @aventara/cli@rc new my-api     # a new NestJS project with Prisma and Aventara
+npx @aventara/cli@rc init           # or: add Aventara to an existing NestJS 12 project
+npm install @aventara/core@rc       # the package on its own
 ```
 
 Node `^22.18.0 || >=24.2.0`. ES modules, with a CommonJS `default` condition.
@@ -24,6 +24,103 @@ Start from the `@aventara/cli` README (what `new` and `init` write), then `@aven
 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:
+
+```ts
+import { AvZ } from "@aventara/core/json";
+
+const postMeta = AvZ.object({
+  seo: AvZ.object({ title: AvZ.string(), keywords: AvZ.array(AvZ.string()) }),
+  status: AvZ.enum(["draft", "published"]),
+  rating: AvZ.optional(AvZ.int()),
+  cover: AvZ.nullable(AvZ.string()),
+});
+
+export type PostMeta = AvZ.infer<typeof postMeta>;
+
+const framework = await createFramework({
+  entrypoint: "/api",
+  adapter,
+  fields: { Post: { meta: { 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:
+
+  ```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.
+
+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
+it.
+
+## 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:
+
+  ```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.
+
+To count these refusals, set `misuse` at the root of the configuration, beside `diagnostics`:
+
+```ts
+const framework = await createFramework({
+  entrypoint: "/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.
+
+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.
+
 ## License
 
 PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not

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

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

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

@@ -3,13 +3,7 @@ import type { LifecycleTrait } from "../contracts/lifecycle-trait.js";
 import type { AdapterModel } from "./adapter-model.js";
 /** Provider-observable lifecycle facts available during adapter discovery. */
 export type AdapterLifecycleTrait = Extract<LifecycleTrait, "DEFAULTED" | "GENERATED_ON_CREATE" | "GENERATED_ON_UPDATE">;
-/**
- * Scalar-shaped provider field expressed only in Aventara vocabulary.
- *
- * Scalar capabilities carry no scope qualifier, measured and not assumed: all six
- * members are uniform across every operation variant on both pilot engines, so a
- * discoverer has nothing per-position to answer here.
- */
+/** Scalar-shaped provider field expressed only in Aventara vocabulary. */
 export type AdapterScalarField<M extends AdapterModel> = {
     readonly kind: "scalar";
     readonly type: {
@@ -23,25 +17,7 @@ export type AdapterScalarField<M extends AdapterModel> = {
     readonly lifecycle: readonly AdapterLifecycleTrait[];
     readonly capabilities: ScalarFieldCapabilities;
 };
-/**
- * Provider relation edge; the target AdapterResource owns object shape.
- *
- * The capabilities are the Contract's own {@link RelationFieldCapabilities}, scope
- * qualifier included, and that sharing is the point: the ADAPTER is the only party
- * that can measure which argument positions a relation is reachable in, because
- * the answer depends on which provider call each operation variant is routed to.
- * Core tabulating it would be a tabulated provider fact and would be wrong for the
- * next adapter.
- *
- * The qualifier is OPTIONAL at this boundary, as it is in the Contract: an adapter
- * that has not measured the axis states the unqualified answer and is believed,
- * which is what keeps a surface that predates the measurement meaningful rather
- * than silently narrowed.
- *
- * **A scope qualifies the TOP LEVEL of an argument only** — the measurement and
- * the reason are recorded on `ProjectionScope`, and a discoverer that narrows
- * recursively would advertise less than the provider accepts.
- */
+/** A discovered relation field; the `target` Resource describes the related row. */
 export type AdapterRelationField<M extends AdapterModel> = {
     readonly kind: "relation";
     readonly target: Extract<keyof M["resources"], string>;
@@ -49,4 +25,5 @@ export type AdapterRelationField<M extends AdapterModel> = {
     readonly nullable: boolean;
     readonly capabilities: RelationFieldCapabilities;
 };
+/** One field the adapter discovered: a scalar or a relation. */
 export type AdapterField<M extends AdapterModel> = AdapterScalarField<M> | AdapterRelationField<M>;

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

@@ -1,16 +1,6 @@
 import type { AdapterField } from "./adapter-field.js";
 import type { AdapterModel } from "./adapter-model.js";
-/**
- * Keys of `TFields` whose discovered field can be scalar-shaped.
- *
- * `TFields[K]` is an indexed access, not a naked type parameter, so a bare
- * conditional would not distribute over a union-valued field. With the
- * abstract `AdapterFieldMap` default every key maps to the whole
- * `AdapterField` union, which is not a subtype of the scalar branch, so the
- * bare form collapses to `never` and makes `AdapterIdentifier` uninhabitable.
- * `Extract` selects the scalar branch out of the union instead, so a key is
- * kept unless it is provably relation-only.
- */
+/** Keys of `TFields` whose discovered field can be scalar-shaped. */
 export type AdapterScalarFieldKey<TFields extends Readonly<Record<string, AdapterField<AdapterModel>>>> = Extract<{
     [K in keyof TFields]: [
         Extract<TFields[K], {

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

@@ -1,4 +1,5 @@
 import type { EnumDefinition } from "../contracts/enum-definition.js";
+import type { ReferenceWriteLimit } from "../contracts/reference-write-limit.js";
 import type { ScalarRegistry } from "../contracts/scalar.js";
 import type { TransactionCapability } from "../contracts/transaction-capability.js";
 import type { AdapterResource } from "./adapter-resource.js";
@@ -7,8 +8,19 @@ import type { AdapterResource } from "./adapter-resource.js";
  * Contract compilation is applied.
  */
 export interface AdapterModel {
+    /** The scalar types the data source supports. */
     readonly scalars: ScalarRegistry;
+    /** The enums the data source declares, by name. */
     readonly enums: Readonly<Record<string, EnumDefinition>>;
+    /** The discovered Resources, by name. */
     readonly resources: Readonly<Record<string, AdapterResource<this>>>;
+    /** Whether the adapter can run interactive transactions. */
     readonly transactions: TransactionCapability;
+    /**
+     * `"uniform"` when the data source takes one record's references only one
+     * way at a time: every relation that holds a reference written as a
+     * relation, or every one through its reference fields. Absent: each relation
+     * either way. Compiled into every Contract.
+     */
+    readonly referenceWrites?: ReferenceWriteLimit;
 }

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

@@ -1,6 +1,10 @@
 import type { AdapterModel } from "./adapter-model.js";
 import type { AdapterOperation } from "./adapter-operation.js";
-/** Small execution seam usable both directly and inside provider transactions. */
+/**
+ * Executes one operation against the provider, directly or inside a provider
+ * transaction.
+ */
 export interface AdapterOperationExecutor<M extends AdapterModel = AdapterModel> {
+    /** Runs one validated operation and resolves its raw result. */
     execute(operation: AdapterOperation<M>): Promise<unknown>;
 }

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

@@ -2,40 +2,19 @@ import type { ResourceOperations } from "../contracts/resource-operations.js";
 import type { AdapterField } from "./adapter-field.js";
 import type { AdapterIdentifier } from "./adapter-identifier.js";
 import type { AdapterModel } from "./adapter-model.js";
+/** A discovered Resource's fields, by name. */
 export type AdapterFieldMap<M extends AdapterModel> = Readonly<Record<string, AdapterField<M>>>;
 /**
- * The field names the adapter discovered for `R`.
- *
- * This is the lower layer of `EffectiveFieldKey`, in
- * `config/effective-fields.ts`: everything the provider already knows about,
- * before any configuration is applied. Named in prose rather than with a
- * `{@link}` because a resolvable link would need an import, and `adapters/`
- * must not reach into `config/`.
- *
- * `R`'s constraint is written out rather than imported as
- * `FrameworkResourceKey<M>` — the identical type — because `adapters/` owns
- * the Base layer and must not depend on `config/`.
+ * The field names the adapter discovered for Resource `R`, before any
+ * configuration adds to them.
  */
 export type AdapterFieldKey<M extends AdapterModel, R extends Extract<keyof M["resources"], string>> = Extract<keyof M["resources"][R]["fields"], string>;
-/**
- * Provider-discovered facts for one Aventara Resource candidate.
- *
- * `TFields` is never supplied by a caller — every in-repo site writes
- * `AdapterResource<M>` — but it is **load-bearing and must not be inlined**. It is
- * the indirection that keeps `M` out of this type's body.
- *
- * `AdapterField<M>` is invariant in `M` (it reads `keyof M["scalars"]` and `keyof
- * M["resources"]`). If `M` reached the body, `AdapterResource` would acquire an
- * invariant variance marker, and every concrete model would stop satisfying the
- * self-typed `AdapterModel.resources: Readonly<Record<string,
- * AdapterResource<this>>>` constraint. Measured: 43 type errors across the adapter
- * and index type tests, and identically 43 whether the parameter is deleted or
- * merely bypassed — so it is the body occurrence that matters, not the arity.
- *
- * Deleting it is not a cleanup.
- */
+/** Provider-discovered facts for one Aventara Resource candidate. */
 export type AdapterResource<M extends AdapterModel, TFields extends AdapterFieldMap<M> = AdapterFieldMap<M>> = {
+    /** The Resource's fields, by name. */
     readonly fields: TFields;
+    /** The field tuples that identify at most one row. */
     readonly identifiers: readonly AdapterIdentifier<TFields>[];
+    /** The standard operations the data source can run for this Resource. */
     readonly operations: ResourceOperations;
 };