@aventara/testing 0.1.0-pilot.2 → 0.1.0-pilot.4

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,42 @@
 import type { Adapter, AdapterModel, AdapterOperation } from "@aventara/core";
+/** 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/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";
@@ -278,8 +279,7 @@ export declare const CORPUS_REFERENTIAL_ACTIONS: {
     }];
 };
 /**
- * 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 +314,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 +372,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/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-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[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/testing",
-  "version": "0.1.0-pilot.2",
+  "version": "0.1.0-pilot.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Conformance and extension testing utilities for Aventara.",
   "type": "module",
@@ -20,7 +20,7 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.2"
+    "@aventara/core": "0.1.0-pilot.4"
   },
   "publishConfig": {
     "access": "public"