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

package/CHANGELOG.md

@@ -0,0 +1,159 @@
+# @aventara/testing
+
+## 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: The protocol fixtures gain two transaction rows: a committed plan whose unique `where` and filter reference an earlier
+  step's result (`200 A1009`), and a reference in a `where` to a step that does not exist (`422 A2007` / `V1016`).
+
+### Patch Changes
+
+- 24ffbab: `@aventara/testing` loads from CommonJS: `require("@aventara/testing")` returns the same module `import` does (its
+  export gains a `default` condition, as core's and nest's have). The package stays ESM; Node's `require()` of an ES
+  module needs Node 22.18 or later, which the package already requires.
+- 24ffbab: Each package ships its `CHANGELOG.md`, so the release notes are in the installed package beside the README.
+- 24ffbab: New export `AvProtocolCorpus`: the protocol corpus's server side, for serving it through a client or host you are
+  writing. `await AvProtocolCorpus.framework()` gives a fresh corpus `Framework` (pass a row's `Aventara-Contract-Hash`
+  to get the contract that row targets), `AvProtocolCorpus.entrypoint` is where to mount it (`"/api"`, every row's path is
+  relative to it), and `AvProtocolCorpus.clientContractHash` is the hash a client generated against it sends. The README
+  has a section on serving the corpus through your own stack.
+- 24ffbab: The protocol corpus now ships as plain JSON at `@aventara/testing/fixtures/protocol-v1.json`, for clients and hosts
+  written in any language: the protocol version, the entrypoint, each ClientContract the rows target (its hash and exact
+  `GET /_contract` bytes) and every row of `AvProtocolFixtures`. It is generated from the TypeScript corpus when the
+  package is built. The one body too large to write out (1 MiB + 1 byte) is a recipe: `prefix` + `repeat` × `times` +
+  `suffix`. The README describes the format.
+- 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.
+- 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.
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [a973e89]
+- Updated dependencies [1e65e9a]
+- Updated dependencies
+- Updated dependencies [a973e89]
+- Updated dependencies [a973e89]
+- Updated dependencies [1e65e9a]
+- Updated dependencies [1e65e9a]
+- Updated dependencies [24ffbab]
+- Updated dependencies [2d00ad7]
+- Updated dependencies [384a50c]
+- Updated dependencies [d43d1cc]
+- Updated dependencies [3f98749]
+- Updated dependencies [032f792]
+- Updated dependencies [dbe6961]
+  - @aventara/core@1.0.0-rc.0
+
+## 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.
+- Updated dependencies [f37dcd6]
+  - @aventara/core@0.1.0-pilot.4
+
+## 0.1.0-pilot.3
+
+### Patch Changes
+
+- @aventara/core@0.1.0-pilot.3
+
+## 0.1.0-pilot.2
+
+### Patch Changes
+
+- 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.
+- Updated dependencies [c2a3b7c]
+- Updated dependencies [e69e88d]
+- Updated dependencies [ab58424]
+- Updated dependencies [23937f8]
+  - @aventara/core@0.1.0-pilot.2
+
+## 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.
+- Updated dependencies [a45f8a8]
+- Updated dependencies [799346e]
+  - @aventara/core@0.1.0-pilot.1
+
+## 0.1.0-pilot.0
+
+### Minor Changes
+
+- First pilot release of `@aventara/testing`: tools for testing an Aventara application, an adapter or a host.
+
+  - `createFakeAdapter` — an in-memory adapter, so a Framework can be built and exercised without a database. Its
+    discovered model is `FakeAdapter.model`.
+  - `AvProtocolFixtures` (each one an `AvProtocolFixture`) — the HTTP protocol's conformance fixtures: every outcome
+    code and success status, contract discovery (`GET /_contract`), missing routes and a stale client, argument
+    validation, body, media-type and method refusals, transactions (including client-scope rules on `/_transactions`),
+    wire scalars and request ids.
+  - `AvProtocolDriver` and `runAvProtocolConformance(driver)` — run the fixtures against your own host: the driver
+    mounts the protocol for a Framework and answers requests, and each fixture's mismatches are reported.
+
+### Patch Changes
+
+- Updated dependencies
+  - @aventara/core@0.1.0-pilot.0

package/README.md

@@ -8,6 +8,9 @@ from outside.
 - `runAvProtocolConformance(driver)` — drives the protocol corpus (`AvProtocolFixtures`) through one host and reports,
   per row, every mismatch with the expected status, code, cause, headers and body. A host supplies an
   `AvProtocolDriver`: given a `Framework`, a session that sends one protocol request and returns the answer, and closes.
+- `AvProtocolCorpus` — the corpus's server side, for serving it through your own client or host (below).
+- `@aventara/testing/fixtures/protocol-v1.json` — the same corpus as plain JSON, for a client or host written in any
+  language (below).
 
 It depends on `@aventara/core` only.
 
@@ -19,6 +22,54 @@ npm install --save-dev @aventara/testing
 
 Node `^22.18.0 || >=24.2.0`. ES modules.
 
+## Serving the corpus through your own stack
+
+`runAvProtocolConformance` builds the corpus `Framework` itself. To serve it from a host or test bench of your own — to
+point a client you are writing at it, say — take it from `AvProtocolCorpus`:
+
+```ts
+import { AvProtocolCorpus, AvProtocolFixtures } from "@aventara/testing";
+
+const framework = await AvProtocolCorpus.framework();
+// Mount `framework` under AvProtocolCorpus.entrypoint ("/api") with your host,
+// then send each row's `request` and compare the answer with the row's `server`.
+```
+
+- `framework(contractHash?)` — a fresh corpus `Framework`, backed by an in-memory adapter whose answers every row
+  states. Pass a row's `Aventara-Contract-Hash` to get the contract that row targets: a few rows target a second
+  contract without transactions, and every other hash (a stale one included) gets the main contract.
+- `entrypoint` — where the corpus is mounted; every row's `path` is relative to it.
+- `clientContractHash` — the main ClientContract's hash: what a client generated against it sends, and what
+  `GET /_contract` names.
+
+A row whose `client.outcome` is `"transport-error"` describes an answer no host produces (a proxy's HTML page, a
+dropped connection); skip it when serving, as the conformance run does. A row's `adapterCalls` counts the operations
+the corpus adapter was handed, which only the conformance run can observe.
+
+## The corpus as JSON
+
+`@aventara/testing/fixtures/protocol-v1.json` holds the whole corpus for protocol version 1, generated from
+`AvProtocolFixtures` when the package is built — every row, in the same order and with the same fields — so a client or
+host written in another language can be held to the same answers:
+
+```json
+{
+  "protocolVersion": 1,
+  "entrypoint": "/api",
+  "clientContractHash": "sha256:…",
+  "contracts": [{ "hash": "sha256:…", "document": "{\"enums\":{},…}" }, …],
+  "rows": [{ "label": "…", "request": { … }, "server": { … }, "client": { … } }, …]
+}
+```
+
+- `contracts` — each ClientContract a row targets: its hash and its exact `GET /_contract` bytes (`document`, a
+  string). The first is the main contract, `clientContractHash`; a row targets the other by sending its hash.
+- `rows` — as `AvProtocolFixture` describes them. One body is too large to write out (one byte over the 1 MiB request
+  limit): its `request.body.content` is a recipe, `{ "prefix": "…", "repeat": "x", "times": 1048567, "suffix": "…" }`,
+  standing for `prefix` + `repeat` repeated `times` times + `suffix`. Every other `content` is the body's text.
+
+From JavaScript: `require("@aventara/testing/fixtures/protocol-v1.json")`, or `import` it `with { type: "json" }`.
+
 ## Documentation
 
 `@aventara/core`'s README is where to start (the framework, its adapters and hosts). `@aventara/nest` is held to this

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

@@ -1,3 +1,3 @@
 import type { Adapter, AdapterModel } from "@aventara/core";
-/** Stable construction seam consumed by reusable adapter conformance suites. */
+/** Builds the Adapter under test; reusable adapter conformance suites take one. */
 export type AdapterFactory<M extends AdapterModel = AdapterModel> = () => Adapter<M> | Promise<Adapter<M>>;

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

@@ -1,28 +1,43 @@
-import type { Adapter, AdapterModel, AdapterOperation } from "@aventara/core";
+import type { Adapter, AdapterModel } from "@aventara/core";
+import type { AdapterOperation } from "@aventara/core/internal";
+/** Answers one operation the fake Adapter is handed. */
 export type FakeAdapterExecute<M extends AdapterModel> = (operation: AdapterOperation<M>) => unknown | Promise<unknown>;
+/** How a transaction ended: `"committed"` or `"rolled-back"`. */
 export type FakeTransactionOutcome = "committed" | "rolled-back";
 /** One settled transaction boundary: what ran inside it, and how it ended. */
 export type FakeTransactionTrace<M extends AdapterModel> = {
+    /** The operations run inside the transaction, in order. */
     readonly operations: readonly AdapterOperation<M>[];
+    /** How the transaction ended. */
     readonly outcome: FakeTransactionOutcome;
 };
 /**
- * Real rollback for caller-owned state: snapshot on begin, restore when the
- * work rejects. Without it the fake Adapter records boundaries but persists
- * whatever the work wrote, so a rollback assertion would prove nothing.
+ * Rollback for state the test owns: `snapshot` when a transaction begins,
+ * `restore` when its work rejects. Without it, the fake Adapter records
+ * transaction boundaries but keeps whatever the work wrote.
  */
 export type FakeAdapterRollback<S> = {
+    /** Captures the state before a transaction's work runs. */
     readonly snapshot: () => S;
+    /** Puts the captured state back after the work rejects. */
     readonly restore: (snapshot: S) => void;
 };
+/** Options for {@link createFakeAdapter}. */
 export type FakeAdapterOptions<M extends AdapterModel, S = unknown> = {
+    /** The adapter model the fake Adapter reports. */
     readonly model: M;
+    /** Answers each operation; without it, every operation resolves `undefined`. */
     readonly execute?: FakeAdapterExecute<M>;
+    /** Makes transactions roll back the test's own state; see {@link FakeAdapterRollback}. */
     readonly rollback?: FakeAdapterRollback<S>;
 };
+/**
+ * The Adapter {@link createFakeAdapter} returns, with a record of every
+ * operation and transaction it ran.
+ */
 export type FakeAdapter<M extends AdapterModel = AdapterModel> = Adapter<M> & {
     readonly operations: readonly AdapterOperation<M>[];
     readonly transactions: readonly FakeTransactionTrace<M>[];
 };
-/** Reusable provider-free Adapter implementation for framework/conformance tests. */
+/** A provider-free, in-memory Adapter for framework and conformance tests. */
 export declare function createFakeAdapter<M extends AdapterModel, S = unknown>(options: FakeAdapterOptions<M, S>): FakeAdapter<M>;

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export type { AdapterFactory } from "./adapters/adapter-factory.js";
 export type { FakeAdapter, FakeAdapterExecute, FakeAdapterOptions, FakeAdapterRollback, FakeTransactionOutcome, FakeTransactionTrace, } from "./adapters/fake-adapter.js";
 export { createFakeAdapter } from "./adapters/fake-adapter.js";
 export { runAvProtocolConformance } from "./protocol/protocol-conformance.js";
+export { AvProtocolCorpus } from "./protocol/protocol-corpus.js";
 export type { AvProtocolDriver } from "./protocol/protocol-driver.js";
 export type { AvProtocolFixture } from "./protocol/protocol-fixture.js";
 export { AvProtocolFixtures } from "./protocol/protocol-fixtures.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { createFakeAdapter } from "./adapters/fake-adapter.js";
 export { runAvProtocolConformance } from "./protocol/protocol-conformance.js";
+export { AvProtocolCorpus } from "./protocol/protocol-corpus.js";
 export { AvProtocolFixtures } from "./protocol/protocol-fixtures.js";

package/dist/protocol/corpus-contract.fixture.d.ts

@@ -3,14 +3,15 @@ import { Decimal } from "@aventara/core";
 /**
  * The corpus's adapter model:
  *
- * - `authors` — every standard operation (family 2); its `secret` field is hidden
- *   at client scope;
- * - `books` — references `authors`, and deleting an author cascades into it
- *   ({@link CORPUS_REFERENTIAL_ACTIONS}; a plan's `V1019`); the client scope adds
- *   a computed `label` to it;
- * - `secrets` — its one operation restricted away at client scope;
- * - `hiddenRes` — hidden at client scope;
- * - `samples` — one field of each scalar whose wire form is not its runtime form.
+ * - `authors`: every standard operation; its `secret` field is hidden at
+ *   client scope;
+ * - `books`: references `authors`, and deleting an author cascades into it
+ *   ({@link CORPUS_REFERENTIAL_ACTIONS}; a plan's `V1019`); the client scope
+ *   adds a computed `label` to it ({@link CORPUS_CLIENT_CONFIG});
+ * - `secrets`: its one operation restricted away at client scope;
+ * - `hiddenRes`: hidden at client scope;
+ * - `samples`: one field of each scalar whose wire form is not its runtime
+ *   form (`bigint`, `datetime`, `decimal`, `bytes`).
  */
 export declare const CORPUS_MODEL: {
     readonly transactions: "interactive";
@@ -274,12 +275,12 @@ export declare const CORPUS_REFERENTIAL_ACTIONS: {
     readonly books: readonly [{
         readonly field: "author";
         readonly target: "authors";
+        readonly references: readonly ["authorId"];
         readonly onDelete: "cascade";
     }];
 };
 /**
- * The `where.id` a row sends to make the corpus Framework fail one way
- * (families 10 and 12, "a fake adapter returning the code, labelled so"):
+ * The `where.id` a row sends to make the corpus Framework fail one way:
  *
  * - `A4000`, `A4001`, `A4002`, `A3000` — the client guard throws
  *   `FrameworkError("A4000")`, denies (`false`), throws
@@ -314,7 +315,7 @@ declare function corpusGuard(context: PipelineContext): boolean;
 declare function corpusPipe(args: unknown): unknown;
 /**
  * The corpus's client-scope configuration: what the ClientContract hides or
- * restricts, and `books.label` — a VIRTUAL field added at client scope and
+ * restricts, and `books.label`, a VIRTUAL field added at client scope and
  * computed on read from `id`.
  */
 export declare const CORPUS_CLIENT_CONFIG: {
@@ -372,24 +373,20 @@ export declare const CORPUS_CLIENT_CONFIG: {
 export declare const CORPUS_ENTRYPOINT = "/api";
 /**
  * The corpus ClientContract's hash: what a generated client for it sends as
- * `Aventara-Contract-Hash`. A literal, as a generated client holds it;
- * `corpus-contract.spec.ts` fails, naming this constant, when the compiled
- * contract moves.
+ * `Aventara-Contract-Hash`. A literal, as a generated client holds it.
  */
 export declare const CORPUS_CLIENT_CONTRACT_HASH = "sha256:07b1a75a6e8e88e30115ae81bcf7e3a12fa493bddce995a01867e2381bd158d0";
 /**
  * The corpus ClientContract as `GET /_contract` serves it: its JCS-canonical
  * bytes, `protocol.hash` included. A literal, as a host must serve it byte for
- * byte; `corpus-contract.spec.ts` fails, naming this constant, when the compiled
- * contract moves.
+ * byte.
  */
 export declare const CORPUS_CLIENT_CONTRACT_DOCUMENT = "{\"enums\":{},\"limits\":{\"maxBooleanNodes\":50,\"maxListLimit\":250,\"maxNestingDepth\":12,\"maxRequestBytes\":1048576,\"maxTransactionOperations\":20},\"protocol\":{\"hash\":\"sha256:07b1a75a6e8e88e30115ae81bcf7e3a12fa493bddce995a01867e2381bd158d0\",\"version\":1},\"resources\":{\"authors\":{\"fields\":{\"id\":{\"capabilities\":{\"filter\":[\"equals\"],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"string\"}},\"name\":{\"capabilities\":{\"create\":[],\"filter\":[\"equals\"],\"select\":true,\"update\":[]},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"string\"}}},\"identifiers\":[[\"id\"]],\"operations\":{\"create\":{\"count\":true,\"many\":true,\"one\":true},\"delete\":{\"count\":true,\"first\":true,\"many\":true,\"unique\":true},\"find\":{\"count\":true,\"first\":true,\"many\":true,\"unique\":true},\"update\":{\"count\":true,\"first\":true,\"many\":true,\"unique\":true},\"upsert\":{\"unique\":true}}},\"books\":{\"fields\":{\"authorId\":{\"capabilities\":{\"filter\":[\"equals\"],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"string\"}},\"id\":{\"capabilities\":{\"filter\":[\"equals\"],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"string\"}},\"label\":{\"capabilities\":{\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[\"COMPUTED_ON_READ\",\"VIRTUAL\"],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"string\"}}},\"identifiers\":[[\"id\"]],\"operations\":{\"find\":{\"many\":true}}},\"samples\":{\"fields\":{\"amount\":{\"capabilities\":{\"create\":[],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"decimal\"}},\"at\":{\"capabilities\":{\"create\":[],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"datetime\"}},\"blob\":{\"capabilities\":{\"create\":[],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"bytes\"}},\"count\":{\"capabilities\":{\"create\":[],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"bigint\"}},\"id\":{\"capabilities\":{\"filter\":[\"equals\"],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"string\"}}},\"identifiers\":[[\"id\"]],\"operations\":{\"create\":{\"one\":true},\"find\":{\"unique\":true}}},\"secrets\":{\"fields\":{\"id\":{\"capabilities\":{\"filter\":[\"equals\"],\"select\":true},\"kind\":\"scalar\",\"lifecycle\":[],\"list\":false,\"nullable\":false,\"type\":{\"scalar\":\"string\"}}},\"identifiers\":[[\"id\"]],\"operations\":{}}},\"scalars\":{\"bigint\":{\"builtin\":true},\"bytes\":{\"builtin\":true},\"datetime\":{\"builtin\":true},\"decimal\":{\"builtin\":true},\"string\":{\"builtin\":true}},\"transactions\":\"interactive\"}";
 /**
- * The hash of the corpus's SECOND ClientContract — the same model and
- * configuration with `transactions: "none"` (family 6's `/_transactions` absence).
- * A row targets it by sending this hash, exactly as a client generated against it
- * would; the runner gives the row the Framework whose ClientContract it names. A
- * literal, held to the compiled value by `corpus-contract.spec.ts`.
+ * The hash of the corpus's second ClientContract: the same model and
+ * configuration with `transactions: "none"` (the `/_transactions` absence
+ * rows). A row targets it by sending this hash, exactly as a client generated
+ * against it would.
  */
 export declare const CORPUS_NONE_CLIENT_CONTRACT_HASH = "sha256:d333e8396b9bf9127e0859ed69b9874f230058a597e2129e6b9e9b380daef618";
 /** The one record the corpus Adapter knows. */

package/dist/protocol/corpus-contract.fixture.js

@@ -81,7 +81,14 @@ export const CORPUS_MODEL = {
     },
 };
 export const CORPUS_REFERENTIAL_ACTIONS = {
-    books: [{ field: "author", target: "authors", onDelete: "cascade" }],
+    books: [
+        {
+            field: "author",
+            target: "authors",
+            references: ["authorId"],
+            onDelete: "cascade",
+        },
+    ],
 };
 export const CORPUS_TRIGGER = {
     unauthenticated: "A4000",

package/dist/protocol/in-process.driver.d.ts

@@ -1,10 +1,8 @@
 import type { AvProtocolDriver } from "./protocol-driver.js";
 /**
- * Driver 1: the protocol hosted in process, with no HTTP stack — a catch-all host
- * that hands `/_contract` to `protocol.encodeContract`, `/_transactions` to the
- * bound shortcut `protocol.handleTransaction`, every other request to
- * `protocol.handleOperation`, and writes back exactly what they answer. What it
- * proves is the framework's own answer, host-free; driver 2 must answer every row
- * identically through a real server.
+ * The protocol hosted in process, with no HTTP stack: `/_contract` goes to
+ * `protocol.encodeContract`, `/_transactions` to `protocol.handleTransaction`,
+ * every other request to `protocol.handleOperation`, and the answer is written
+ * back as it is.
  */
 export declare const inProcessDriver: AvProtocolDriver;

package/dist/protocol/per-route.driver.d.ts

@@ -1,11 +1,10 @@
 import type { AvProtocolDriver } from "./protocol-driver.js";
 /**
- * The per-route driver: the protocol hosted in process as a host that mounts ONE
- * route per `protocol.surface()` entry — each operation on `handleOperation`,
+ * The protocol hosted in process as a host that mounts one route per
+ * `protocol.surface()` entry (each operation on `handleOperation`,
  * `/_transactions` on `handleTransaction`, `/_contract` on `encodeContract`,
- * matched by method and path — and `protocol.answerAbsent` as the fallback for
- * everything it did not mount. `undefined` from the fallback is a path outside the
- * protocol, which this host answers with its own bodiless 404. Every corpus row
- * must answer here exactly as through driver 1's catch-all.
+ * matched by method and path) and uses `protocol.answerAbsent` as the fallback
+ * for everything it did not mount. `undefined` from the fallback is a path
+ * outside the protocol, which this host answers with its own bodiless 404.
  */
 export declare const perRouteDriver: AvProtocolDriver;

package/dist/protocol/protocol-conformance.d.ts

@@ -1,29 +1,30 @@
 import type { AvProtocolDriver } from "./protocol-driver.js";
 /**
- * `runAvProtocolConformance(driver)` — the corpus, driven through one host.
+ * `runAvProtocolConformance(driver)` — drives the protocol fixture corpus
+ * through one host.
  *
- * Every row a host answers is driven — the rows whose `client.outcome` is
+ * Every row a host answers is driven; rows whose `client.outcome` is
  * `"transport-error"` describe what a client receives instead of a framework
  * answer, so they are skipped. Each driven row runs against a fresh corpus
- * Framework, through a fresh driver session, with one request — the corpus
- * Framework whose ClientContract hash the row's `Aventara-Contract-Hash` names, as
- * a generated client names it — and its answer is held to the row's `server`
- * block:
+ * Framework, through a fresh driver session, with one request (the corpus
+ * Framework whose ClientContract hash the row's `Aventara-Contract-Hash`
+ * names; the main corpus contract for any other hash), and its answer is
+ * held to the row's `server` block:
  *
  * - `status`, exactly;
- * - `code`: the body is a framework envelope (`AvProtocol.isOperationResponse`,
- *   the one envelope test) carrying that code — or, for `null`, is none;
+ * - `code`: the body is a framework envelope carrying that code — or, for
+ *   `null`, is none;
  * - `causeKeys`: the exact sorted key set of `cause`;
  * - `issues`: each issue's `code` and `path`, in order;
  * - `adapterCalls`: the operations the corpus Adapter was handed, exactly;
- * - `responseHeaders`: each named header present (names matched without regard to
- *   case) with exactly that value — a host may add its own;
+ * - `responseHeaders`: each named header present (names matched without
+ *   regard to case) with exactly that value — a host may add its own;
  * - `bodyBytes`: the body text, exactly.
  *
- * Resolves one result per driven row, in corpus order, each with the mismatches
- * found — none when the host conforms. A driver that throws is a mismatch of its
- * row, not a rejection of the run. Test-runner free: a caller asserts on the
- * results with whatever runner it uses.
+ * Resolves one result per driven row, in corpus order, each with the
+ * mismatches found — none when the host conforms. A driver that throws is a
+ * mismatch of its row, not a rejection of the run. Works with any test
+ * runner: assert on the results with whatever runner you use.
  */
 export declare function runAvProtocolConformance(driver: AvProtocolDriver): Promise<readonly {
     readonly label: string;

package/dist/protocol/protocol-corpus.d.ts

@@ -0,0 +1,30 @@
+import type { Framework } from "@aventara/core";
+/**
+ * The server side of the protocol fixture corpus (`AvProtocolFixtures`), for
+ * a client or host author who serves it through their own stack: a Framework
+ * whose answers every corpus row states, the entrypoint its rows' paths are
+ * relative to, and the hash of the ClientContract it serves.
+ *
+ * ```ts
+ * const framework = await AvProtocolCorpus.framework();
+ * // mount it under AvProtocolCorpus.entrypoint with your host, then send the
+ * // rows of AvProtocolFixtures and compare each answer with the row's `server`
+ * ```
+ */
+export declare const AvProtocolCorpus: {
+    /**
+     * A fresh corpus Framework, backed by an in-memory Adapter whose answer is a
+     * pure function of the operation it is handed. `contractHash` picks which
+     * corpus ClientContract it serves, as a row's `Aventara-Contract-Hash` does:
+     * the corpus's `transactions: "none"` contract for that contract's hash (the
+     * `/_transactions` absence rows send it), the main one for anything else.
+     */
+    readonly framework: (contractHash?: string) => Promise<Framework>;
+    /** Where the corpus Framework is mounted; every row's `path` is relative to it. */
+    readonly entrypoint: string;
+    /**
+     * The hash of the main corpus ClientContract — what a client generated against
+     * it sends as `Aventara-Contract-Hash`, and what `GET /_contract` names.
+     */
+    readonly clientContractHash: string;
+};

package/dist/protocol/protocol-corpus.js

@@ -0,0 +1,6 @@
+import { CORPUS_CLIENT_CONTRACT_HASH, CORPUS_ENTRYPOINT, createCorpusFramework, } from "./corpus-contract.fixture.js";
+export const AvProtocolCorpus = Object.freeze({
+    framework: async (contractHash) => (await createCorpusFramework(contractHash)).framework,
+    entrypoint: CORPUS_ENTRYPOINT,
+    clientContractHash: CORPUS_CLIENT_CONTRACT_HASH,
+});

package/dist/protocol/protocol-driver.d.ts

@@ -1,14 +1,11 @@
 import type { Framework } from "@aventara/core";
 import type { AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
 /**
- * One host under test, as the protocol conformance run drives it
- * (`runAvProtocolConformance`): given the corpus's Framework, mount the protocol
- * the way that host does, then answer each corpus request as that host would
- * answer it over HTTP — status, headers and body text, as an `AvProtocolResponse`.
- *
- * Driver 1 (`in-process.driver.ts`) calls the bound protocol's shortcuts directly;
- * a real host sends the request over its own stack and reads back what arrived.
- * The run calls `close` once per row, after its one request.
+ * One host under test, as `runAvProtocolConformance` drives it: given the
+ * corpus's Framework, mount the protocol the way that host does, then answer
+ * each corpus request as that host would answer it over HTTP (status, headers
+ * and body text, as an `AvProtocolResponse`). The run calls `close` once per
+ * row, after its one request.
  */
 export type AvProtocolDriver = (framework: Framework) => Promise<{
     readonly send: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;

package/dist/protocol/protocol-fixture.d.ts

@@ -1,25 +1,27 @@
 import type { OperationCode, ValidationCode } from "@aventara/core";
 import type { AvProtocolRequest } from "@aventara/core/protocol";
 /**
- * Types only; the rows live in `protocol-fixtures.ts`.
+ * One row of the protocol fixture corpus: the HTTP request a host receives
+ * (`request`), what the host must answer (`server`), and what a generated
+ * client must do with that answer (`client`).
  *
- * `request` is core's own request value, `AvProtocolRequest` from
- * `@aventara/core/protocol`, so a row is exactly what a host hands the bound
- * protocol: no second request shape exists for the corpus to drift from.
+ * `request` is an `AvProtocolRequest` from `@aventara/core/protocol`, exactly
+ * what a host hands the bound protocol.
  */
 export type AvProtocolFixture = {
     /**
-     * A row that covers one of the specification's success rows begins with that row's
-     * operation name (`find.many …`, `create.one …`) or with `transaction` for the
-     * committed-plan row.
+     * The row's name. A row for a standard operation's success begins with that
+     * operation's name (`find.many …`, `create.one …`), or with `transaction` for
+     * the committed-plan row.
      */
     readonly label: string;
     /** Method, entrypoint-relative path, headers, and a raw or parsed body. */
     readonly request: AvProtocolRequest;
+    /** What the host must answer. */
     readonly server: {
         /**
-         * The HTTP status. `0` only on a transport-error row (family 11) where no
-         * HTTP response arrived at all — the Fetch API's network-error status.
+         * The HTTP status. `0` only on a transport-error row, where no HTTP
+         * response arrived at all (the Fetch API's network-error status).
          */
         readonly status: number;
         /** `null`: the host produces no framework envelope at all. */
@@ -36,11 +38,12 @@ export type AvProtocolFixture = {
         /** The exact body, where bytes matter. */
         readonly bodyBytes?: string;
     };
+    /** What a generated client must do with the answer. */
     readonly client: {
         /**
          * What a generated client does with the answer. `"transport-error"`
-         * also marks a row no host produces (family 11): a host driver filters
-         * on `client.outcome === "transport-error"` and does not drive those rows.
+         * also marks a row no host produces: a host driver filters on
+         * `client.outcome === "transport-error"` and does not drive those rows.
          */
         readonly outcome: "resolve" | "framework-error" | "transport-error";
         /** Present iff `outcome` is `"framework-error"`. */

package/dist/protocol/protocol-fixtures.d.ts

@@ -1,2 +1,7 @@
 import type { AvProtocolFixture } from "./protocol-fixture.js";
+/**
+ * The protocol fixture corpus: passive data rows, each an HTTP request, the
+ * answer a host must give and what a generated client must do with it. Drive
+ * them through a host with `runAvProtocolConformance`.
+ */
 export declare const AvProtocolFixtures: readonly AvProtocolFixture[];