@aventara/testing 0.0.0-stage → 0.1.0-pilot.0

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

@@ -0,0 +1,334 @@
+import { createFramework, Decimal, FrameworkError } from "@aventara/core";
+import { createFakeAdapter } from "../adapters/fake-adapter.js";
+/**
+ * The Framework every driven corpus row runs against: one model, one
+ * configuration, and an in-memory Adapter whose answer is a pure function of
+ * the operation it is handed — so a row's expected bytes are fixed facts, and
+ * no row needs a provider (plan §13).
+ *
+ * Grows with the corpus (plan §6): each slice adds the resources its rows
+ * need, and moves {@link CORPUS_CLIENT_CONTRACT_HASH} with them.
+ */
+const identityString = {
+    kind: "scalar",
+    type: { scalar: "string" },
+    nullable: false,
+    list: false,
+    lifecycle: [],
+    capabilities: { select: true, filter: ["equals"] },
+};
+const writableString = {
+    ...identityString,
+    capabilities: {
+        select: true,
+        filter: ["equals"],
+        create: [],
+        update: [],
+    },
+};
+/** A non-JSON-native scalar the corpus reads (family 13): selectable, never filtered. */
+const wired = (scalar) => ({
+    kind: "scalar",
+    type: { scalar },
+    nullable: false,
+    list: false,
+    lifecycle: [],
+    capabilities: { select: true, create: [] },
+});
+/** One `find.many`: what the corpus's supporting Resources advertise. */
+const findMany = { find: { many: true } };
+/**
+ * The corpus's adapter model:
+ *
+ * - `authors` — every standard operation (family 2); its `secret` field is
+ *   hidden at client scope (R1's client-hidden field);
+ * - `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}, F-828);
+ * - `secrets` — its one operation restricted away at client scope (R1's
+ *   client-restricted variant; M6's `operations: {}`);
+ * - `hiddenRes` — hidden at client scope (R1's client-hidden Resource, M7);
+ * - `samples` — one field of each scalar whose wire form is not its runtime
+ *   form (`bigint`, `datetime`, `decimal`, `bytes`; family 13, P1, C1).
+ */
+export const CORPUS_MODEL = {
+    transactions: "interactive",
+    scalars: {
+        string: { builtin: true },
+        bigint: { builtin: true },
+        datetime: { builtin: true },
+        decimal: { builtin: true },
+        bytes: { builtin: true },
+    },
+    enums: {},
+    resources: {
+        authors: {
+            fields: {
+                id: identityString,
+                name: writableString,
+                secret: identityString,
+            },
+            identifiers: [["id"]],
+            operations: {
+                find: { first: true, unique: true, many: true, count: true },
+                create: { one: true, many: true, count: true },
+                update: { first: true, unique: true, many: true, count: true },
+                delete: { first: true, unique: true, many: true, count: true },
+                upsert: { unique: true },
+            },
+        },
+        books: {
+            fields: { id: identityString, authorId: identityString },
+            identifiers: [["id"]],
+            operations: findMany,
+        },
+        secrets: {
+            fields: { id: identityString },
+            identifiers: [["id"]],
+            operations: findMany,
+        },
+        hiddenRes: {
+            fields: { id: identityString },
+            identifiers: [["id"]],
+            operations: findMany,
+        },
+        samples: {
+            fields: {
+                id: identityString,
+                count: wired("bigint"),
+                at: wired("datetime"),
+                amount: wired("decimal"),
+                blob: wired("bytes"),
+            },
+            identifiers: [["id"]],
+            operations: { find: { unique: true }, create: { one: true } },
+        },
+    },
+};
+/** Deleting an author cascades into its books (an edge under `books`). */
+export const CORPUS_REFERENTIAL_ACTIONS = {
+    books: [{ field: "author", target: "authors", 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"):
+ *
+ * - `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
+ *   conflict code; `A3001` — it throws a plain `Error`;
+ * - `A3002` — a plan step carrying it runs, and the Adapter's transaction then
+ *   fails to commit;
+ * - `A3003` — `samples.find.unique` answers a datetime the wire cannot spell.
+ */
+export const CORPUS_TRIGGER = {
+    unauthenticated: "A4000",
+    guardDenies: "A4001",
+    policyDenies: "A4002",
+    guardThrows: "A3000",
+    conflict: "A2008",
+    concurrentModification: "A2013",
+    staleSelection: "A2014",
+    adapterThrows: "A3001",
+    commitFails: "A3002",
+    unencodable: "A3003",
+};
+/** The `where.id` an operation's arguments name, when it names one as a string. */
+function whereIdOf(args) {
+    const where = typeof args === "object" && args !== null
+        ? args.where
+        : undefined;
+    const id = typeof where === "object" && where !== null
+        ? where.id
+        : undefined;
+    return typeof id === "string" ? id : undefined;
+}
+/** The corpus's one client guard: it decides nothing unless a row names a trigger. */
+function corpusGuard(context) {
+    switch (whereIdOf(context.args)) {
+        case CORPUS_TRIGGER.unauthenticated:
+            throw new FrameworkError("A4000", "Authentication is required.");
+        case CORPUS_TRIGGER.guardDenies:
+            return false;
+        case CORPUS_TRIGGER.policyDenies:
+            throw new FrameworkError("A4002", "Denied by the corpus policy.");
+        case CORPUS_TRIGGER.guardThrows:
+            throw new Error("the corpus guard failed");
+        default:
+            return true;
+    }
+}
+/**
+ * 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` (F-828, plan S12).
+ */
+export const CORPUS_CLIENT_CONFIG = {
+    fields: {
+        books: {
+            label: {
+                type: { scalar: "string" },
+                nullable: false,
+                list: false,
+                lifecycle: ["VIRTUAL"],
+            },
+        },
+    },
+    behaviors: {
+        books: {
+            fields: {
+                label: {
+                    read: {
+                        dependsOn: ["id"],
+                        compute: ({ record, }) => `book:${String(record.id)}`,
+                    },
+                },
+            },
+        },
+    },
+    pipelines: { guards: [corpusGuard] },
+    restrictions: {
+        authors: { fields: { secret: { hidden: true } } },
+        secrets: { operations: { find: { many: false } } },
+        hiddenRes: { hidden: true },
+    },
+};
+/** The corpus Framework's mount point; every row's path is relative to it. */
+export 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.
+ */
+export const CORPUS_CLIENT_CONTRACT_HASH = "sha256:07b1a75a6e8e88e30115ae81bcf7e3a12fa493bddce995a01867e2381bd158d0";
+/**
+ * The corpus ClientContract as `GET /_contract` serves it: its JCS-canonical
+ * bytes (Q8), `protocol.hash` included (M22). A literal, as a host must
+ * serve it byte for byte; `corpus-contract.spec.ts` fails, naming this
+ * constant, when the compiled contract moves.
+ */
+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"}';
+/**
+ * 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 (the director, 2026-10-05). A literal, held to the
+ * compiled value by `corpus-contract.spec.ts`.
+ */
+export const CORPUS_NONE_CLIENT_CONTRACT_HASH = "sha256:d333e8396b9bf9127e0859ed69b9874f230058a597e2129e6b9e9b380daef618";
+/** The one record the corpus Adapter knows. */
+export const CORPUS_AUTHOR = { id: "a1", name: "Ada" };
+/** The `where.id` that matches nothing. */
+export const CORPUS_NOBODY = "nobody";
+/**
+ * The one `samples` record, in runtime forms — what an Adapter hands core,
+ * and what the HTTP encoders must spell in wire forms (P1).
+ */
+export const CORPUS_SAMPLE = {
+    id: "s1",
+    count: 9007199254740993n,
+    at: new Date("2026-10-05T12:34:56.789Z"),
+    amount: new Decimal("12.50"),
+    blob: new Uint8Array([255, 0, 16]),
+};
+/** The conflict codes the corpus Adapter raises, and the text it raises them with. */
+const CONFLICTS = {
+    [CORPUS_TRIGGER.conflict]: "A2008",
+    [CORPUS_TRIGGER.concurrentModification]: "A2013",
+    [CORPUS_TRIGGER.staleSelection]: "A2014",
+};
+/** The one record of each supporting Resource. */
+const SUPPORTING_RECORDS = {
+    books: { id: "b1", authorId: CORPUS_AUTHOR.id },
+    secrets: { id: "s1" },
+    hiddenRes: { id: "h1" },
+};
+/**
+ * What the corpus Adapter answers an operation. A trigger `where.id` fails it
+ * ({@link CORPUS_TRIGGER}). Otherwise: for {@link CORPUS_NOBODY}, nothing — `0`
+ * for a count, `[]` for a many, `null` for a single record; else `2` for a
+ * count, the Resource's one record in a list for a many, and the one record
+ * for a single-record operation (`samples`: {@link CORPUS_SAMPLE}).
+ */
+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}.`);
+    }
+    if (id === CORPUS_TRIGGER.adapterThrows) {
+        throw new Error("the corpus Adapter failed");
+    }
+    const nothing = id === CORPUS_NOBODY;
+    if (operation.variant === "count") {
+        return nothing ? 0 : 2;
+    }
+    if (operation.variant === "many") {
+        return nothing
+            ? []
+            : [SUPPORTING_RECORDS[operation.resource] ?? CORPUS_AUTHOR];
+    }
+    if (nothing) {
+        return null;
+    }
+    if (operation.resource === "samples") {
+        return id === CORPUS_TRIGGER.unencodable
+            ? { ...CORPUS_SAMPLE, at: new Date("+010000-01-01T00:00:00.000Z") }
+            : CORPUS_SAMPLE;
+    }
+    return CORPUS_AUTHOR;
+}
+/**
+ * The fake Adapter's transaction, made to fail its commit when a step of the
+ * plan named {@link CORPUS_TRIGGER.commitFails} — an infrastructure failure
+ * after the work ran (`A3002`).
+ */
+function failingCommit(transaction) {
+    return async (work) => {
+        let doomed = false;
+        const result = await transaction((scoped) => work({
+            execute: (operation) => {
+                if (whereIdOf(operation.arguments) === CORPUS_TRIGGER.commitFails) {
+                    doomed = true;
+                }
+                return scoped.execute(operation);
+            },
+        }));
+        if (doomed) {
+            throw new Error("the corpus Adapter failed to commit");
+        }
+        return result;
+    };
+}
+/**
+ * A fresh corpus Framework, and the count of operations its Adapter has been
+ * handed so far — a row's `adapterCalls` is read from it. `contractHash`
+ * selects which corpus ClientContract it serves: the `transactions: "none"`
+ * one when it is {@link CORPUS_NONE_CLIENT_CONTRACT_HASH}, the main one
+ * otherwise (a stale or absent hash included).
+ */
+export async function createCorpusFramework(contractHash) {
+    // Over the widened model type: which model is discovered is a runtime fact,
+    // and a literal-typed Framework costs type-checking the corpus never uses.
+    const fake = createFakeAdapter({
+        model: contractHash === CORPUS_NONE_CLIENT_CONTRACT_HASH
+            ? { ...CORPUS_MODEL, transactions: "none" }
+            : CORPUS_MODEL,
+        execute: corpusAnswer,
+    });
+    const adapter = Object.assign(fake, {
+        referentialActions: CORPUS_REFERENTIAL_ACTIONS,
+        ...(fake.transaction === undefined
+            ? {}
+            : { transaction: failingCommit(fake.transaction) }),
+    });
+    const framework = await createFramework({
+        entrypoint: CORPUS_ENTRYPOINT,
+        adapter,
+        client: CORPUS_CLIENT_CONFIG,
+    });
+    return { framework, adapterCalls: () => adapter.operations.length };
+}

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

@@ -0,0 +1,11 @@
+import type { AvProtocolDriver } from "./protocol-driver.js";
+/**
+ * Driver 1 (plan S8, S9): the protocol hosted in process, with no HTTP stack —
+ * a catch-all host (Q12) 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 (S13) must
+ * answer every row identically through a real server.
+ */
+export declare const inProcessDriver: AvProtocolDriver;

package/dist/protocol/in-process.driver.js

@@ -0,0 +1,26 @@
+import { AvProtocol } from "@aventara/core/protocol";
+/**
+ * Driver 1 (plan S8, S9): the protocol hosted in process, with no HTTP stack —
+ * a catch-all host (Q12) 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 (S13) must
+ * answer every row identically through a real server.
+ */
+export const inProcessDriver = async (framework) => {
+    const protocol = AvProtocol.bind(framework);
+    return {
+        send: async (request) => {
+            switch (request.path) {
+                case "/_contract":
+                    return protocol.encodeContract(request);
+                case "/_transactions":
+                    return protocol.handleTransaction(request);
+                default:
+                    return protocol.handleOperation(request);
+            }
+        },
+        close: async () => undefined,
+    };
+};

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

@@ -0,0 +1,12 @@
+import type { AvProtocolDriver } from "./protocol-driver.js";
+/**
+ * The per-route driver (plan S10): 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 (Q12's first style).
+ * `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.
+ */
+export declare const perRouteDriver: AvProtocolDriver;

package/dist/protocol/per-route.driver.js

@@ -0,0 +1,36 @@
+import { AvProtocol } from "@aventara/core/protocol";
+/** What this host answers a path the protocol says is the host's: its own bodiless 404. */
+const HOST_NOT_FOUND = Object.freeze({
+    status: 404,
+    headers: Object.freeze({}),
+    body: "",
+});
+/**
+ * The per-route driver (plan S10): 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 (Q12's first style).
+ * `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.
+ */
+export const perRouteDriver = async (framework) => {
+    const protocol = AvProtocol.bind(framework);
+    const mounted = new Map(protocol.surface().map((route) => [`${route.method} ${route.path}`, route]));
+    return {
+        send: async (request) => {
+            switch (mounted.get(`${request.method} ${request.path}`)?.kind) {
+                case "operation":
+                    return protocol.handleOperation(request);
+                case "transactions":
+                    return protocol.handleTransaction(request);
+                case "contract":
+                    return protocol.encodeContract(request);
+                default:
+                    return protocol.answerAbsent(request) ?? HOST_NOT_FOUND;
+            }
+        },
+        close: async () => undefined,
+    };
+};

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

@@ -0,0 +1,32 @@
+import type { AvProtocolDriver } from "./protocol-driver.js";
+/**
+ * `runAvProtocolConformance(driver)` — the corpus, driven through one host.
+ *
+ * Every row a host answers is driven — the rows whose `client.outcome` is
+ * `"transport-error"` describe what a client receives instead of a framework
+ * answer, so they are skipped (the director, 2026-10-05). 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 (the main
+ * corpus contract for any other hash; the director, 2026-10-05) — 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;
+ * - `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;
+ * - `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.
+ */
+export declare function runAvProtocolConformance(driver: AvProtocolDriver): Promise<readonly {
+    readonly label: string;
+    readonly mismatches: readonly string[];
+}[]>;

package/dist/protocol/protocol-conformance.js

@@ -0,0 +1,112 @@
+import { AvProtocol } from "@aventara/core/protocol";
+import { createCorpusFramework } from "./corpus-contract.fixture.js";
+import { AvProtocolFixtures } from "./protocol-fixtures.js";
+/**
+ * `runAvProtocolConformance(driver)` — the corpus, driven through one host.
+ *
+ * Every row a host answers is driven — the rows whose `client.outcome` is
+ * `"transport-error"` describe what a client receives instead of a framework
+ * answer, so they are skipped (the director, 2026-10-05). 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 (the main
+ * corpus contract for any other hash; the director, 2026-10-05) — 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;
+ * - `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;
+ * - `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.
+ */
+export async function runAvProtocolConformance(driver) {
+    const results = [];
+    for (const row of AvProtocolFixtures) {
+        if (row.client.outcome === "transport-error") {
+            continue;
+        }
+        const corpus = await createCorpusFramework(contractHashOf(row.request));
+        let response;
+        try {
+            const session = await driver(corpus.framework);
+            try {
+                response = await session.send(row.request);
+            }
+            finally {
+                await session.close();
+            }
+        }
+        catch (error) {
+            results.push({
+                label: row.label,
+                mismatches: [`driver threw: ${error}`],
+            });
+            continue;
+        }
+        results.push({
+            label: row.label,
+            mismatches: mismatchesOf(row.server, response, corpus.adapterCalls()),
+        });
+    }
+    return results;
+}
+/** Every way `response` departs from what the row's server block states. */
+function mismatchesOf(server, response, adapterCalls) {
+    const mismatches = [];
+    const expect = (what, actual, expected) => {
+        const [a, e] = [JSON.stringify(actual), JSON.stringify(expected)];
+        if (a !== e) {
+            mismatches.push(`${what}: expected ${e}, received ${a}`);
+        }
+    };
+    expect("status", response.status, server.status);
+    expect("adapter calls", adapterCalls, server.adapterCalls);
+    const body = parsedBody(response.body);
+    if (server.code === null) {
+        expect("a framework envelope", AvProtocol.isOperationResponse(body), false);
+    }
+    else if (AvProtocol.isOperationResponse(body)) {
+        expect("code", body.code, server.code);
+        const cause = body.cause;
+        if (server.causeKeys !== undefined) {
+            expect("cause keys", Object.keys(cause ?? {}).sort(), [...server.causeKeys].sort());
+        }
+        if (server.issues !== undefined) {
+            expect("issues", (cause?.issues ?? []).map(({ code, path }) => path === undefined ? { code } : { code, path }), server.issues);
+        }
+    }
+    else {
+        mismatches.push(`a framework envelope carrying ${server.code}: none`);
+    }
+    for (const [name, value] of Object.entries(server.responseHeaders ?? {})) {
+        const received = Object.entries(response.headers).find(([candidate]) => candidate.toLowerCase() === name.toLowerCase());
+        expect(`header ${name}`, received?.[1], value);
+    }
+    if (server.bodyBytes !== undefined) {
+        expect("body", response.body, server.bodyBytes);
+    }
+    return mismatches;
+}
+/** The row's `Aventara-Contract-Hash`, its name matched without regard to case. */
+function contractHashOf(request) {
+    const value = Object.entries(request.headers).find(([name]) => name.toLowerCase() === "aventara-contract-hash")?.[1];
+    return typeof value === "string" ? value : undefined;
+}
+/** The parsed body, or `undefined` — which no envelope is — for text that is not JSON. */
+function parsedBody(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,18 @@
+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 (a `node:http` server, Phase 11's Nest module) sends
+ * the request over its own stack and reads back what arrived. The run calls
+ * `close` once per row, after its one request.
+ */
+export type AvProtocolDriver = (framework: Framework) => Promise<{
+    readonly send: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
+    readonly close: () => Promise<void>;
+}>;

package/dist/protocol/protocol-driver.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,53 @@
+import type { OperationCode, ValidationCode } from "@aventara/core";
+import type { AvProtocolRequest } from "@aventara/core/protocol";
+/**
+ * One row of the Phase 10 protocol fixture corpus: the HTTP request a host
+ * receives (`request`), what the host must answer for it (`server`), and what
+ * a generated client must do with that answer (`client`). Types only; the
+ * rows live in `protocol-fixtures.ts`.
+ *
+ * `request` is core's own request value, `AvProtocolRequest` from
+ * `@aventara/core/protocol` (Q9), so a row is exactly what a host hands the
+ * bound protocol: no second request shape exists for the corpus to drift from.
+ */
+export type AvProtocolFixture = {
+    /**
+     * Stable across slices; the coverage gate reads it. 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.
+     */
+    readonly label: string;
+    /** Method, entrypoint-relative path, headers, and a raw or parsed body (Q11). */
+    readonly request: AvProtocolRequest;
+    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.
+         */
+        readonly status: number;
+        /** `null`: the host produces no framework envelope at all. */
+        readonly code: OperationCode | null;
+        /** The exact, sorted key set of `cause`. */
+        readonly causeKeys?: readonly string[];
+        readonly issues?: readonly {
+            readonly code: ValidationCode;
+            readonly path?: readonly (string | number)[];
+        }[];
+        /** Always stated: `0` is an assertion, not a default. */
+        readonly adapterCalls: number;
+        readonly responseHeaders?: Readonly<Record<string, string>>;
+        /** The exact body, where bytes matter. */
+        readonly bodyBytes?: string;
+    };
+    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.
+         */
+        readonly outcome: "resolve" | "framework-error" | "transport-error";
+        /** Present iff `outcome` is `"framework-error"`. */
+        readonly code?: OperationCode;
+    };
+};

package/dist/protocol/protocol-fixture.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+import type { AvProtocolFixture } from "./protocol-fixture.js";
+export declare const AvProtocolFixtures: readonly AvProtocolFixture[];