@aventara/testing 0.1.0-pilot.4 → 1.0.0-rc.1

package/README.md

@@ -1,24 +1,75 @@
 # `@aventara/testing`
 
-Conformance fixtures and testing utilities for Aventara extensions: what an adapter or a transport host is held to,
-from outside.
+Conformance fixtures and testing utilities for Aventara extensions. They test an adapter or a transport host from
+outside.
 
-- `createFakeAdapter` — an in-memory adapter, with transaction tracing, for testing code that runs a `Framework`
+- `createFakeAdapter`: an in-memory adapter, with transaction tracing, for testing code that runs an `AvFramework`
   without a database.
-- `runAvProtocolConformance(driver)` — drives the protocol corpus (`AvProtocolFixtures`) through one host and reports,
+- `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.
+  `AvProtocolDriver`: given an `AvFramework`, 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.
 
 ## Install
 
 ```bash
-npm install --save-dev @aventara/testing
+npm install --save-dev @aventara/testing@rc
 ```
 
 Node `^22.18.0 || >=24.2.0`. ES modules.
 
+## Serving the corpus through your own stack
+
+`runAvProtocolConformance` builds the corpus `AvFramework` itself. To serve it from a host or test bench of your own,
+for example to point a client you are writing at it, 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 `AvFramework`, 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. A client generated against it sends this hash, and
+  `GET /_contract` names it.
+
+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. It is generated from
+`AvProtocolFixtures` when the package is built, with 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
@@ -26,5 +77,6 @@ corpus on Express and Fastify in its own tests. Each package's README ships in i
 
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.

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

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

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

@@ -1,42 +1,43 @@
-import type { Adapter, AdapterModel, AdapterOperation } from "@aventara/core";
+import type { AvAdapter, AvAdapterModel } from "@aventara/core";
+import type { AvAdapterOperation } from "@aventara/core/internal";
 /** Answers one operation the fake Adapter is handed. */
-export type FakeAdapterExecute<M extends AdapterModel> = (operation: AdapterOperation<M>) => unknown | Promise<unknown>;
+export type AvFakeAdapterExecute<M extends AvAdapterModel> = (operation: AvAdapterOperation<M>) => unknown | Promise<unknown>;
 /** How a transaction ended: `"committed"` or `"rolled-back"`. */
-export type FakeTransactionOutcome = "committed" | "rolled-back";
+export type AvFakeTransactionOutcome = "committed" | "rolled-back";
 /** One settled transaction boundary: what ran inside it, and how it ended. */
-export type FakeTransactionTrace<M extends AdapterModel> = {
+export type AvFakeTransactionTrace<M extends AvAdapterModel> = {
     /** The operations run inside the transaction, in order. */
-    readonly operations: readonly AdapterOperation<M>[];
+    readonly operations: readonly AvAdapterOperation<M>[];
     /** How the transaction ended. */
-    readonly outcome: FakeTransactionOutcome;
+    readonly outcome: AvFakeTransactionOutcome;
 };
 /**
  * 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> = {
+export type AvFakeAdapterRollback<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> = {
+export type AvFakeAdapterOptions<M extends AvAdapterModel, 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>;
+    readonly execute?: AvFakeAdapterExecute<M>;
+    /** Makes transactions roll back the test's own state; see {@link AvFakeAdapterRollback}. */
+    readonly rollback?: AvFakeAdapterRollback<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>[];
+export type AvFakeAdapter<M extends AvAdapterModel = AvAdapterModel> = AvAdapter<M> & {
+    readonly operations: readonly AvAdapterOperation<M>[];
+    readonly transactions: readonly AvFakeTransactionTrace<M>[];
 };
 /** 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>;
+export declare function createFakeAdapter<M extends AvAdapterModel, S = unknown>(options: AvFakeAdapterOptions<M, S>): AvFakeAdapter<M>;

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export type { AdapterFactory } from "./adapters/adapter-factory.js";
-export type { FakeAdapter, FakeAdapterExecute, FakeAdapterOptions, FakeAdapterRollback, FakeTransactionOutcome, FakeTransactionTrace, } from "./adapters/fake-adapter.js";
+export type { AvAdapterFactory } from "./adapters/adapter-factory.js";
+export type { AvFakeAdapter, AvFakeAdapterExecute, AvFakeAdapterOptions, AvFakeAdapterRollback, AvFakeTransactionOutcome, AvFakeTransactionTrace, } 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

@@ -1,5 +1,5 @@
-import type { Framework, PipelineContext } from "@aventara/core";
-import { Decimal } from "@aventara/core";
+import type { AvContext, AvFramework } from "@aventara/core";
+import { AvDecimal } from "@aventara/core";
 /**
  * The corpus's adapter model:
  *
@@ -7,7 +7,7 @@ import { Decimal } from "@aventara/core";
  *   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});
+ *   defines a computed `label` the client alone sees ({@link CORPUS_RESOURCES});
  * - `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
@@ -275,6 +275,7 @@ export declare const CORPUS_REFERENTIAL_ACTIONS: {
     readonly books: readonly [{
         readonly field: "author";
         readonly target: "authors";
+        readonly references: readonly ["authorId"];
         readonly onDelete: "cascade";
     }];
 };
@@ -282,9 +283,9 @@ export declare const CORPUS_REFERENTIAL_ACTIONS: {
  * 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
- *   `FrameworkError("A4002")`, or throws a plain `Error`;
- * - `A2008`, `A2013`, `A2014` — the Adapter throws `FrameworkError` with that
+ *   `AvError("A4000")`, denies (`false`), throws
+ *   `AvError("A4002")`, or throws a plain `Error`;
+ * - `A2008`, `A2013`, `A2014` — the Adapter throws `AvError` with that
  *   conflict code; `A3001` — it throws a plain `Error`;
  * - `A3002` — a plan step carrying it runs, and the Adapter's transaction then
  *   fails to commit;
@@ -306,65 +307,78 @@ export declare const CORPUS_TRIGGER: {
     readonly pipeOutputInvalid: "A3004";
 };
 /** The corpus's one client guard: it decides nothing unless a row names a trigger. */
-declare function corpusGuard(context: PipelineContext): boolean;
+declare function corpusGuard(context: AvContext): boolean;
 /**
  * The corpus's one client pipe: it rewrites nothing unless a row names the
  * `A3004` trigger, and then adds a filter on a field the server does not have.
  */
 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
- * computed on read from `id`.
+ * The corpus's root `resources` tree: `books.label`, a VIRTUAL field computed on
+ * read from `id`.
  */
-export declare const CORPUS_CLIENT_CONFIG: {
-    readonly fields: {
-        readonly books: {
+export declare const CORPUS_RESOURCES: {
+    readonly books: {
+        readonly fields: {
             readonly label: {
-                readonly type: {
-                    readonly scalar: "string";
+                readonly definition: {
+                    readonly type: {
+                        readonly scalar: "string";
+                    };
+                    readonly nullable: false;
+                    readonly list: false;
+                    readonly lifecycle: readonly ["VIRTUAL"];
+                };
+                readonly pipelines: {
+                    readonly compute: {
+                        readonly read: {
+                            readonly dependsOn: readonly ["id"];
+                            readonly compute: ({ record, }: {
+                                readonly record: Readonly<Record<string, unknown>>;
+                            }) => string;
+                        };
+                    };
                 };
-                readonly nullable: false;
-                readonly list: false;
-                readonly lifecycle: readonly ["VIRTUAL"];
             };
         };
     };
-    readonly behaviors: {
-        readonly books: {
-            readonly fields: {
-                readonly label: {
-                    readonly read: {
-                        readonly dependsOn: readonly ["id"];
-                        readonly compute: ({ record, }: {
-                            readonly record: Readonly<Record<string, unknown>>;
-                        }) => string;
-                    };
+};
+/** The corpus's application layer: `books.label` is the client's only. */
+export declare const CORPUS_APPLICATION_CONFIG: {
+    readonly exposed: true;
+    readonly exemptions: {
+        readonly resources: {
+            readonly books: {
+                readonly fields: {
+                    readonly label: true;
                 };
             };
         };
     };
+};
+/**
+ * The corpus's client layer: what the ClientContract hides or restricts, and
+ * the client's own guard and pipe.
+ */
+export declare const CORPUS_CLIENT_CONFIG: {
     readonly pipelines: {
         readonly guards: readonly [typeof corpusGuard];
         readonly pipes: readonly [typeof corpusPipe];
     };
-    readonly restrictions: {
-        readonly authors: {
-            readonly fields: {
-                readonly secret: {
-                    readonly hidden: true;
+    readonly exposed: true;
+    readonly exemptions: {
+        readonly resources: {
+            readonly authors: {
+                readonly fields: {
+                    readonly secret: true;
                 };
             };
-        };
-        readonly secrets: {
-            readonly operations: {
-                readonly find: {
-                    readonly many: false;
+            readonly secrets: {
+                readonly operations: {
+                    readonly find: readonly ["many"];
                 };
             };
-        };
-        readonly hiddenRes: {
-            readonly hidden: true;
+            readonly hiddenRes: true;
         };
     };
 };
@@ -374,20 +388,20 @@ 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.
  */
-export declare const CORPUS_CLIENT_CONTRACT_HASH = "sha256:07b1a75a6e8e88e30115ae81bcf7e3a12fa493bddce995a01867e2381bd158d0";
+export declare const CORPUS_CLIENT_CONTRACT_HASH = "sha256:502530d5b918266c61f45e70035acd7d9637bbf7305c5572106185d5e63ec307";
 /**
  * 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.
  */
-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\"}";
+export declare const CORPUS_CLIENT_CONTRACT_DOCUMENT = "{\"enums\":{},\"limits\":{\"maxBooleanNodes\":50,\"maxJsonDepth\":64,\"maxListLimit\":250,\"maxNestingDepth\":12,\"maxRequestBytes\":1048576,\"maxTransactionOperations\":20},\"protocol\":{\"hash\":\"sha256:502530d5b918266c61f45e70035acd7d9637bbf7305c5572106185d5e63ec307\",\"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"` (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";
+export declare const CORPUS_NONE_CLIENT_CONTRACT_HASH = "sha256:5e99809294a2aae922b635e9a44b464b1b6e03359a54d30420292c62676a7ce5";
 /** The one record the corpus Adapter knows. */
 export declare const CORPUS_AUTHOR: {
     readonly id: "a1";
@@ -403,7 +417,7 @@ export declare const CORPUS_SAMPLE: {
     readonly id: "s1";
     readonly count: 9007199254740993n;
     readonly at: Date;
-    readonly amount: Decimal;
+    readonly amount: AvDecimal;
     readonly blob: Uint8Array<ArrayBuffer>;
 };
 /**
@@ -414,7 +428,7 @@ export declare const CORPUS_SAMPLE: {
  * otherwise (a stale or absent hash included).
  */
 export declare function createCorpusFramework(contractHash?: string): Promise<{
-    readonly framework: Framework;
+    readonly framework: AvFramework;
     readonly adapterCalls: () => number;
 }>;
 export {};

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

@@ -1,4 +1,4 @@
-import { createFramework, Decimal, FrameworkError } from "@aventara/core";
+import { AvDecimal, AvError, createFramework } from "@aventara/core";
 import { createFakeAdapter } from "../adapters/fake-adapter.js";
 const identityString = {
     kind: "scalar",
@@ -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",
@@ -106,13 +113,13 @@ function whereIdOf(args) {
     return typeof id === "string" ? id : undefined;
 }
 function corpusGuard(context) {
-    switch (whereIdOf(context.args)) {
+    switch (whereIdOf(context.$args)) {
         case CORPUS_TRIGGER.unauthenticated:
-            throw new FrameworkError("A4000", "Authentication is required.");
+            throw new AvError("A4000", "Authentication is required.");
         case CORPUS_TRIGGER.guardDenies:
             return false;
         case CORPUS_TRIGGER.policyDenies:
-            throw new FrameworkError("A4002", "Denied by the corpus policy.");
+            throw new AvError("A4002", "Denied by the corpus policy.");
         case CORPUS_TRIGGER.guardThrows:
             throw new Error("the corpus guard failed");
         default:
@@ -126,47 +133,54 @@ function corpusPipe(args) {
     const record = args;
     return { ...record, where: { ...record.where, nope: "x" } };
 }
-export const CORPUS_CLIENT_CONFIG = {
-    fields: {
-        books: {
+export const CORPUS_RESOURCES = {
+    books: {
+        fields: {
             label: {
-                type: { scalar: "string" },
-                nullable: false,
-                list: false,
-                lifecycle: ["VIRTUAL"],
-            },
-        },
-    },
-    behaviors: {
-        books: {
-            fields: {
-                label: {
-                    read: {
-                        dependsOn: ["id"],
-                        compute: ({ record, }) => `book:${String(record.id)}`,
+                definition: {
+                    type: { scalar: "string" },
+                    nullable: false,
+                    list: false,
+                    lifecycle: ["VIRTUAL"],
+                },
+                pipelines: {
+                    compute: {
+                        read: {
+                            dependsOn: ["id"],
+                            compute: ({ record, }) => `book:${String(record.id)}`,
+                        },
                     },
                 },
             },
         },
     },
+};
+export const CORPUS_APPLICATION_CONFIG = {
+    exposed: true,
+    exemptions: { resources: { books: { fields: { label: true } } } },
+};
+export const CORPUS_CLIENT_CONFIG = {
     pipelines: { guards: [corpusGuard], pipes: [corpusPipe] },
-    restrictions: {
-        authors: { fields: { secret: { hidden: true } } },
-        secrets: { operations: { find: { many: false } } },
-        hiddenRes: { hidden: true },
+    exposed: true,
+    exemptions: {
+        resources: {
+            authors: { fields: { secret: true } },
+            secrets: { operations: { find: ["many"] } },
+            hiddenRes: true,
+        },
     },
 };
 export const CORPUS_ENTRYPOINT = "/api";
-export const CORPUS_CLIENT_CONTRACT_HASH = "sha256:07b1a75a6e8e88e30115ae81bcf7e3a12fa493bddce995a01867e2381bd158d0";
-export 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"}';
-export const CORPUS_NONE_CLIENT_CONTRACT_HASH = "sha256:d333e8396b9bf9127e0859ed69b9874f230058a597e2129e6b9e9b380daef618";
+export const CORPUS_CLIENT_CONTRACT_HASH = "sha256:502530d5b918266c61f45e70035acd7d9637bbf7305c5572106185d5e63ec307";
+export const CORPUS_CLIENT_CONTRACT_DOCUMENT = '{"enums":{},"limits":{"maxBooleanNodes":50,"maxJsonDepth":64,"maxListLimit":250,"maxNestingDepth":12,"maxRequestBytes":1048576,"maxTransactionOperations":20},"protocol":{"hash":"sha256:502530d5b918266c61f45e70035acd7d9637bbf7305c5572106185d5e63ec307","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"}';
+export const CORPUS_NONE_CLIENT_CONTRACT_HASH = "sha256:5e99809294a2aae922b635e9a44b464b1b6e03359a54d30420292c62676a7ce5";
 export const CORPUS_AUTHOR = { id: "a1", name: "Ada" };
 export const CORPUS_NOBODY = "nobody";
 export const CORPUS_SAMPLE = {
     id: "s1",
     count: 9007199254740993n,
     at: new Date("2026-10-05T12:34:56.789Z"),
-    amount: new Decimal("12.50"),
+    amount: new AvDecimal("12.50"),
     blob: new Uint8Array([255, 0, 16]),
 };
 const CONFLICTS = {
@@ -183,7 +197,7 @@ function corpusAnswer(operation) {
     const id = whereIdOf(operation.arguments);
     const conflict = id === undefined ? undefined : CONFLICTS[id];
     if (conflict !== undefined) {
-        throw new FrameworkError(conflict, `The corpus Adapter answered ${conflict}.`);
+        throw new AvError(conflict, `The corpus Adapter answered ${conflict}.`);
     }
     if (id === CORPUS_TRIGGER.adapterThrows) {
         throw new Error("the corpus Adapter failed");
@@ -238,8 +252,10 @@ export async function createCorpusFramework(contractHash) {
             : { transaction: failingCommit(fake.transaction) }),
     });
     const framework = await createFramework({
-        entrypoint: CORPUS_ENTRYPOINT,
+        api: CORPUS_ENTRYPOINT,
         adapter,
+        resources: CORPUS_RESOURCES,
+        application: CORPUS_APPLICATION_CONFIG,
         client: CORPUS_CLIENT_CONFIG,
     });
     return { framework, adapterCalls: () => adapter.operations.length };

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

@@ -1,6 +1,6 @@
 import type { AvProtocolDriver } from "./protocol-driver.js";
 /**
- * `runAvProtocolConformance(driver)` — drives the protocol fixture corpus
+ * `runAvProtocolConformance(driver)` drives the protocol fixture corpus
  * through one host.
  *
  * Every row a host answers is driven; rows whose `client.outcome` is
@@ -12,17 +12,17 @@ import type { AvProtocolDriver } from "./protocol-driver.js";
  * held to the row's `server` block:
  *
  * - `status`, exactly;
- * - `code`: the body is a framework envelope carrying that code — or, for
+ * - `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;
+ *   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
+ * 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.
  */

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

@@ -0,0 +1,30 @@
+import type { AvFramework } 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<AvFramework>;
+    /** 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,4 +1,4 @@
-import type { Framework } from "@aventara/core";
+import type { AvFramework } from "@aventara/core";
 import type { AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
 /**
  * One host under test, as `runAvProtocolConformance` drives it: given the
@@ -7,7 +7,7 @@ import type { AvProtocolRequest, AvProtocolResponse } from "@aventara/core/proto
  * and body text, as an `AvProtocolResponse`). The run calls `close` once per
  * row, after its one request.
  */
-export type AvProtocolDriver = (framework: Framework) => Promise<{
+export type AvProtocolDriver = (framework: AvFramework) => Promise<{
     readonly send: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
     readonly close: () => Promise<void>;
 }>;