@aventara/next 0.0.0-stage → 1.0.0-rc.9

package/dist/aventara.factory.js

@@ -0,0 +1,61 @@
+import { createFramework, } from "@aventara/core";
+import { checkedOptions } from "./host-bootstrap.validator.js";
+import { loadMcpBinding } from "./mcp-binding.loader.js";
+import { createRequestState } from "./request-state.cache.js";
+import { bindProtocolHost, createRouteHandlers, } from "./route-handlers.factory.js";
+import { createServerOperations, refuseMemberClashes, } from "./server-operations.factory.js";
+import { frameworkSlot, optionsFingerprint, } from "./shared-framework.registry.js";
+import { registerUniversalPath, universalPath, } from "./universal-path.registry.js";
+export function Aventara(options) {
+    const checked = checkedOptions(options);
+    const { source } = checked;
+    const slot = source.kind === "config"
+        ? frameworkSlot(String(options.api), optionsFingerprint(options))
+        : { fingerprint: "", framework: undefined, built: undefined };
+    const held = (created) => {
+        refuseMemberClashes(created);
+        slot.built = created;
+        return created;
+    };
+    if (source.kind === "framework") {
+        try {
+            slot.framework = Promise.resolve(held(source.framework));
+        }
+        catch (error) {
+            slot.framework = Promise.reject(error);
+            slot.framework.catch(() => undefined);
+        }
+    }
+    const frameworkOf = () => {
+        slot.framework ??=
+            source.kind === "config"
+                ? source
+                    .config()
+                    .then((config) => createFramework(config))
+                    .then(held)
+                : Promise.resolve(held(source.framework));
+        return slot.framework;
+    };
+    let protocol;
+    const protocolOf = () => {
+        protocol ??= frameworkOf().then(async (built) => bindProtocolHost(built, await loadMcpBinding(built)));
+        return protocol;
+    };
+    let readied;
+    const requestState = createRequestState(checked.state);
+    const universalState = checked.state === undefined
+        ? undefined
+        : async () => (await requestState()) ?? {};
+    const { avClient, avApp } = createServerOperations({ built: frameworkOf, current: () => slot.built }, requestState);
+    return {
+        handlers: createRouteHandlers(protocolOf, checked.state),
+        avClient,
+        avApp,
+        ready: () => {
+            readied ??= protocolOf().then(() => {
+                registerUniversalPath(universalPath(protocolOf, universalState));
+            });
+            return readied;
+        },
+    };
+}

package/dist/host-bootstrap.validator.d.ts

@@ -0,0 +1,38 @@
+import type { AvConfigAny, AvFramework } from "@aventara/core";
+import type { HostState } from "./route-handlers.factory.js";
+/**
+ * Refuses an MCP endpoint without `authorization`: on Next.js it could answer
+ * no caller. Checked when the Framework is built, on its resolved `mcp`.
+ */
+export declare function refuseOpenMcp(endpoint: {
+    readonly authorization?: unknown;
+}): void;
+/** The options, split into what the host keeps and where its Framework comes from. */
+export type CheckedOptions = {
+    /**
+     * What seeds each request's state: the developer's `state`, or the
+     * Framework's access provider's (`access`). Core never sees it.
+     */
+    readonly state: HostState | undefined;
+    /** The Framework's source: one built elsewhere, or a configuration this host builds. */
+    readonly source: FrameworkSourceOption;
+};
+/** `{ framework }`: a Framework `createFramework` built; or a configuration for it. */
+export type FrameworkSourceOption = {
+    readonly kind: "framework";
+    readonly framework: AvFramework;
+} | {
+    readonly kind: "config";
+    /**
+     * The configuration without `state`, and with `adapter` resolved: built
+     * on this call when it was given as a function.
+     */
+    readonly config: () => Promise<AvConfigAny>;
+};
+/**
+ * The options as given, split: `state` taken out, and either the given
+ * Framework, or the configuration with a function `adapter` deferred to first
+ * use, since core refuses a root key it does not know and a function in place
+ * of an adapter.
+ */
+export declare function checkedOptions(options: unknown): CheckedOptions;

package/dist/host-bootstrap.validator.js

@@ -0,0 +1,68 @@
+import { accessStateOf } from "@aventara/core/internal";
+const NOT_AN_OBJECT = "Aventara: the options are not an object; pass `{ ...aventaraConfig, adapter, state }`, or `{ framework, state }`.";
+const NOT_A_FRAMEWORK = "Aventara: `framework` is not an Aventara Framework (it has no string `api` and no `contracts.client`); pass what `createFramework` resolved to.";
+function bothForms(keys) {
+    return `Aventara: the options carry both \`framework\` and configuration keys (${keys.map((key) => `\`${key}\``).join(", ")}); pass \`{ framework, state }\` or \`{ ...aventaraConfig, adapter, state }\`, not both.`;
+}
+const STATE_BESIDE_ACCESS = "Aventara: the options carry both `access` and `state`; `access` seeds each request's state, so remove `state`.";
+const STATE_NOT_A_FUNCTION = "Aventara: `state` is not a function; pass `({ headers, request }) => ({ … })`, called once per request.";
+const MCP_WITHOUT_AUTHORIZATION = "Aventara: `mcp` on Next.js needs `authorization` (`mcp: { path, authorization: { servers, verify } }`). Without it the MCP endpoint answers only loopback callers that send no `x-forwarded-for`, and Next.js adds `x-forwarded-for` to every request, so every caller would be refused.";
+export function refuseOpenMcp(endpoint) {
+    if (endpoint.authorization === undefined) {
+        throw new Error(MCP_WITHOUT_AUTHORIZATION);
+    }
+}
+export function checkedOptions(options) {
+    if (typeof options !== "object" || options === null) {
+        throw new Error(NOT_AN_OBJECT);
+    }
+    const { state, ...config } = options;
+    if (state !== undefined && typeof state !== "function") {
+        throw new Error(STATE_NOT_A_FUNCTION);
+    }
+    const boundState = state === undefined
+        ? undefined
+        : state.bind(options);
+    const { framework, ...rest } = config;
+    if (framework !== undefined) {
+        const configured = Object.entries(rest)
+            .filter(([, value]) => value !== undefined)
+            .map(([key]) => key);
+        if (configured.length > 0) {
+            throw new Error(bothForms(configured));
+        }
+        if (!isFramework(framework)) {
+            throw new Error(NOT_A_FRAMEWORK);
+        }
+        return {
+            state: oneStateSeed(boundState, accessStateOf(framework)),
+            source: { kind: "framework", framework },
+        };
+    }
+    const access = config.access;
+    const adapter = config.adapter;
+    return {
+        state: oneStateSeed(boundState, access === undefined ? undefined : (context) => access.state(context)),
+        source: {
+            kind: "config",
+            config: async () => typeof adapter === "function"
+                ? { ...config, adapter: await adapter() }
+                : config,
+        },
+    };
+}
+function oneStateSeed(state, access) {
+    if (state !== undefined && access !== undefined) {
+        throw new Error(STATE_BESIDE_ACCESS);
+    }
+    return state ?? access;
+}
+function isFramework(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.api === "string" &&
+        typeof candidate.contracts?.client === "object" &&
+        candidate.contracts.client !== null);
+}

package/dist/hydration-tag.format.d.ts

@@ -0,0 +1,11 @@
+/** The tagged form a dehydrated value takes: `{ [tagKey]: <tag>, [valueKey]: <wire form> }`. */
+export declare const HYDRATION_FORMAT: {
+    /** The key a tag is under. */
+    readonly tagKey: "$av";
+    /** The key the tagged value's wire form is under. */
+    readonly valueKey: "v";
+    /** The tag of a plain object that holds `tagKey` as data. */
+    readonly objectTag: "object";
+    /** The scalars a value is tagged as: those whose runtime values JSON does not carry. */
+    readonly scalarTags: readonly ["bigint", "bytes", "datetime", "decimal"];
+};

package/dist/hydration-tag.format.js

@@ -0,0 +1,6 @@
+export const HYDRATION_FORMAT = {
+    tagKey: "$av",
+    valueKey: "v",
+    objectTag: "object",
+    scalarTags: ["bigint", "bytes", "datetime", "decimal"],
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import "server-only";
+export { Aventara } from "./aventara.factory.js";
+export type { AvNextHandlers, AvNextStateContext, } from "./route-handlers.factory.js";
+export type { AvNextAppTransaction, AvNextClientTransaction, } from "./server-operations.factory.js";
+export { avDehydrate } from "./value.dehydrator.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+import "server-only";
+export { Aventara } from "./aventara.factory.js";
+export { avDehydrate } from "./value.dehydrator.js";

package/dist/mcp-binding.loader.d.ts

@@ -0,0 +1,33 @@
+import type { AvFramework, AvState } from "@aventara/core";
+import type { AvProtocolResponse } from "@aventara/core/protocol";
+/** One request to the MCP endpoint or its metadata, as `@aventara/mcp` reads it. */
+export type McpRequest = {
+    readonly method: string;
+    /** The request's absolute URL: the OAuth metadata names the endpoint by its origin. */
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: Uint8Array;
+    /** A route handler never sees the socket. */
+    readonly remoteAddress: undefined;
+};
+/** One route the MCP binding lists. */
+export type McpRoute = {
+    readonly kind: "endpoint" | "metadata";
+    readonly path: string;
+    readonly methods: readonly ("GET" | "POST" | "DELETE")[];
+};
+export type McpBinding = {
+    readonly surface: () => readonly McpRoute[];
+    readonly maxRequestBytes: number;
+    readonly handleEndpoint: (request: McpRequest, options?: {
+        readonly state?: () => AvState | Promise<AvState>;
+    }) => Promise<AvProtocolResponse>;
+    readonly encodeMetadata: (request: McpRequest) => AvProtocolResponse;
+};
+/**
+ * The MCP binding for `framework`, or `undefined` when its configuration has no
+ * `mcp`. Called once, when the Framework is built: an `mcp` without
+ * `authorization`, or a missing `@aventara/mcp`, rejects that build with a
+ * fixed sentence.
+ */
+export declare function loadMcpBinding(framework: AvFramework, specifier?: string): Promise<McpBinding | undefined>;

package/dist/mcp-binding.loader.js

@@ -0,0 +1,39 @@
+import { refuseOpenMcp } from "./host-bootstrap.validator.js";
+const MCP_PACKAGE = "@aventara/mcp";
+const missing = (specifier, coreVersion) => `Aventara: the configuration has \`mcp\`, and the package that serves it, ${specifier}, is not installed. Install it at @aventara/core's exact version (npm install --save-exact ${specifier}@${coreVersion ?? "<your @aventara/core version>"}), or remove \`mcp\` from the configuration.`;
+async function installedCoreVersion() {
+    try {
+        const manifest = new URL("../package.json", import.meta.resolve("@aventara/core"));
+        const { default: read } = (await import(manifest.href, { with: { type: "json" } }));
+        return read.name === "@aventara/core" && typeof read.version === "string"
+            ? read.version
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isMissing(error, specifier) {
+    const { code, message } = (error ?? {});
+    return ((code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") &&
+        typeof message === "string" &&
+        message.includes(`'${specifier}'`));
+}
+export async function loadMcpBinding(framework, specifier = MCP_PACKAGE) {
+    if (framework.mcp === undefined) {
+        return undefined;
+    }
+    refuseOpenMcp(framework.mcp);
+    let loaded;
+    try {
+        loaded = await import(specifier);
+    }
+    catch (error) {
+        if (isMissing(error, specifier)) {
+            throw new Error(missing(specifier, await installedCoreVersion()));
+        }
+        throw error;
+    }
+    const { AvMcp } = loaded;
+    return AvMcp.bind(framework);
+}

package/dist/protocol-route.table.d.ts

@@ -0,0 +1,20 @@
+import type { AvState } from "@aventara/core";
+import type { AvProtocolBinding, AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
+import type { McpBinding, McpRequest, McpRoute } from "./mcp-binding.loader.js";
+/** One route `protocol.surface()` lists. */
+export type SurfaceRoute = ReturnType<AvProtocolBinding["surface"]>[number];
+/** The developer's `state` option over one route request: seeds its `ctx.$state`. */
+export type StateSeed = () => AvState | Promise<AvState>;
+/** What a route answers its request with: a bound protocol member. */
+export type RouteAnswer = (request: AvProtocolRequest, state: StateSeed | undefined) => AvProtocolResponse | Promise<AvProtocolResponse>;
+/** The bound member each kind of surface route is answered by. */
+export type ProtocolRouteTable = {
+    readonly [K in SurfaceRoute["kind"]]: (binding: AvProtocolBinding) => RouteAnswer;
+};
+export declare const PROTOCOL_ROUTES: ProtocolRouteTable;
+/** What an MCP route answers its request with: a bound `@aventara/mcp` member. */
+export type McpRouteAnswer = (request: McpRequest, state: StateSeed | undefined) => AvProtocolResponse | Promise<AvProtocolResponse>;
+/** The bound `@aventara/mcp` member each kind of MCP route is answered by. */
+export declare const MCP_ROUTES: {
+    readonly [K in McpRoute["kind"]]: (binding: McpBinding) => McpRouteAnswer;
+};

package/dist/protocol-route.table.js

@@ -0,0 +1,9 @@
+export const PROTOCOL_ROUTES = {
+    operation: (binding) => (request, state) => binding.handleOperation(request, state === undefined ? {} : { state }),
+    contract: (binding) => (request) => binding.encodeContract(request),
+    transactions: (binding) => (request, state) => binding.handleTransaction(request, state === undefined ? {} : { state }),
+};
+export const MCP_ROUTES = {
+    endpoint: (binding) => (request, state) => binding.handleEndpoint(request, state === undefined ? {} : { state }),
+    metadata: (binding) => (request) => binding.encodeMetadata(request),
+};

package/dist/request-body.reader.d.ts

@@ -0,0 +1,34 @@
+import type { AvProtocolBinding, AvProtocolResponse } from "@aventara/core/protocol";
+/**
+ * What the body reader hands on: the stored bytes, an unsupported coding, or a
+ * body that does not decode in the coding it names.
+ */
+export type RequestBodyRead = {
+    readonly kind: "read";
+    readonly content: Uint8Array;
+} | {
+    readonly kind: "unsupported-coding";
+} | {
+    readonly kind: "undecodable";
+};
+/**
+ * The answer to a body the reader could not hand on, through the bound
+ * `failure` member: an unsupported coding is the protocol's `A2011`; a body
+ * that does not decode in its coding is malformed, `A2000`.
+ */
+export declare function unreadBodyAnswer(binding: AvProtocolBinding, read: Exclude<RequestBodyRead, {
+    readonly kind: "read";
+}>): AvProtocolResponse;
+/**
+ * Reads `request`'s body to its end. Its `Content-Encoding` absent, empty or
+ * `identity` is no coding; one of `gzip`, `deflate`, `br` (any case) is
+ * inflated; anything else, a stacked coding included, is unsupported. A body
+ * that does not decode in the coding it names is undecodable. Either way the
+ * stream is still read to its end.
+ */
+export declare function readRequestBody(request: Request, cap: number): Promise<RequestBodyRead>;
+/** Reads `request`'s body to its end, storing its bytes as sent, up to `cap + 1`. */
+export declare function readRawBody(request: Request, cap: number): Promise<{
+    readonly kind: "read";
+    readonly content: Uint8Array;
+}>;

package/dist/request-body.reader.js

@@ -0,0 +1,130 @@
+export function unreadBodyAnswer(binding, read) {
+    return read.kind === "unsupported-coding"
+        ? binding.failure("A2011")
+        : binding.failure("A2000");
+}
+const INFLATERS = {
+    gzip: (zlib) => zlib.createGunzip(),
+    deflate: (zlib) => zlib.createInflate(),
+    br: (zlib) => zlib.createBrotliDecompress(),
+};
+let zlibModule;
+const zlib = () => {
+    const specifier = "node:zlib";
+    zlibModule ??= import(specifier);
+    return zlibModule;
+};
+async function* chunksOf(body) {
+    if (body === null) {
+        return;
+    }
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                return;
+            }
+            yield value;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+export async function readRequestBody(request, cap) {
+    const source = chunksOf(request.body);
+    const coding = codingOf(request.headers.get("content-encoding"));
+    if (coding === undefined) {
+        for await (const _ of source) {
+        }
+        return { kind: "unsupported-coding" };
+    }
+    if (coding === "identity") {
+        return storedUpTo(source, cap);
+    }
+    const stored = boundedStore(cap + 1);
+    const inflater = INFLATERS[coding](await zlib());
+    const inflated = (async () => {
+        for await (const chunk of inflater) {
+            if (!stored.add(chunk)) {
+                inflater.destroy();
+                return;
+            }
+        }
+    })();
+    const stopped = inflated.then(() => undefined, () => undefined);
+    for await (const chunk of source) {
+        if (!inflater.destroyed) {
+            await Promise.race([
+                new Promise((written) => {
+                    inflater.write(chunk, () => written());
+                }),
+                stopped,
+            ]);
+        }
+    }
+    if (!inflater.destroyed) {
+        inflater.end();
+    }
+    try {
+        await inflated;
+    }
+    catch {
+        return { kind: "undecodable" };
+    }
+    return { kind: "read", content: stored.content() };
+}
+export function readRawBody(request, cap) {
+    return storedUpTo(chunksOf(request.body), cap);
+}
+async function storedUpTo(source, cap) {
+    const stored = boundedStore(cap + 1);
+    for await (const chunk of source) {
+        stored.add(chunk);
+    }
+    return { kind: "read", content: stored.content() };
+}
+function codingOf(contentEncoding) {
+    const named = (contentEncoding ?? "")
+        .split(",")
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token !== "");
+    if (named.length === 0) {
+        return "identity";
+    }
+    if (named.length > 1) {
+        return undefined;
+    }
+    const [only] = named;
+    return only === "identity" ||
+        only === "gzip" ||
+        only === "deflate" ||
+        only === "br"
+        ? only
+        : undefined;
+}
+function boundedStore(limit) {
+    const chunks = [];
+    let size = 0;
+    return {
+        add(chunk) {
+            const room = limit - size;
+            if (room > 0) {
+                const kept = chunk.byteLength <= room ? chunk : chunk.subarray(0, room);
+                chunks.push(kept);
+                size += kept.byteLength;
+            }
+            return size < limit;
+        },
+        content() {
+            const bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            return bytes;
+        },
+    };
+}

package/dist/request-state.cache.d.ts

@@ -0,0 +1,9 @@
+import type { AvState } from "@aventara/core";
+import type { HostState } from "./route-handlers.factory.js";
+/**
+ * The request's state for `avClient`: the developer's `state`, handed the
+ * headers `next/headers` reads, run once per request. `undefined` without a
+ * `state` option, so the call starts from `{}` as on a route, and reads no
+ * headers.
+ */
+export declare function createRequestState(state: HostState | undefined): () => Promise<AvState | undefined>;

package/dist/request-state.cache.js

@@ -0,0 +1,8 @@
+import { headers } from "next/headers.js";
+import { cache } from "react";
+export function createRequestState(state) {
+    if (state === undefined) {
+        return async () => undefined;
+    }
+    return cache(async () => state({ headers: await headers() }));
+}

package/dist/route-handlers.factory.d.ts

@@ -0,0 +1,60 @@
+import type { AvFramework, AvState } from "@aventara/core";
+import { type AvProtocolBinding } from "@aventara/core/protocol";
+import type { McpBinding } from "./mcp-binding.loader.js";
+import { type McpRouteAnswer, type RouteAnswer } from "./protocol-route.table.js";
+/** What `Aventara()`'s `state` option is handed for one request: `{ headers, request? }`. */
+export type AvNextStateContext = {
+    /** The request's headers. */
+    readonly headers: Headers;
+    /** The route handler's request: present on every call through `handlers`. */
+    readonly request?: Request;
+};
+/** The developer's `state` option: seeds a request's `ctx.$state`. */
+export type HostState = (context: AvNextStateContext) => AvState | Promise<AvState>;
+/** A Next.js App Router route handler. */
+export type RouteHandler = (request: Request) => Promise<Response>;
+/**
+ * `handlers`, from `Aventara()`: the route handlers the catch-all route file
+ * under the configured `api` path exports,
+ * `export const { GET, POST, PUT, PATCH, DELETE } = handlers;`.
+ */
+export type AvNextHandlers = {
+    readonly GET: RouteHandler;
+    readonly POST: RouteHandler;
+    readonly PUT: RouteHandler;
+    readonly PATCH: RouteHandler;
+    readonly DELETE: RouteHandler;
+};
+/** The protocol bound to one Framework, with its routes keyed for dispatch. */
+export type ProtocolHost = {
+    readonly binding: AvProtocolBinding;
+    /** The Framework's normalized mount path (`""` or `/seg(/seg)*`). */
+    readonly api: string;
+    readonly maxRequestBytes: number;
+    /** Each `surface()` route's answer, keyed by `METHOD path`. */
+    readonly routes: ReadonlyMap<string, RouteAnswer>;
+    /** The MCP binding's routes when the configuration has `mcp`. */
+    readonly mcp: McpHost | undefined;
+};
+/** The MCP binding's routes, keyed for dispatch. */
+type McpHost = {
+    readonly maxRequestBytes: number;
+    /** Each MCP route's answer, keyed by its absolute path. */
+    readonly routes: ReadonlyMap<string, McpRouteAnswer>;
+};
+/**
+ * Binds `framework`'s protocol once: every route `surface()` lists, keyed by
+ * method and path, and the MCP binding's routes, when there is one, by path.
+ */
+export declare function bindProtocolHost(framework: AvFramework, mcp: McpBinding | undefined): ProtocolHost;
+/** A route's dispatch key: its method and its path under the mount path. */
+export declare const routeKey: (method: string, path: string) => string;
+/**
+ * The route handlers over the protocol `host` resolves to. A request for one of
+ * the MCP binding's paths is answered by that binding; a request whose method
+ * and path are a route of `surface()` by its bound member; any other is the
+ * protocol's absence answer, or, for a path outside the protocol's namespace,
+ * Next's `notFound()`. Nothing is built until the first request.
+ */
+export declare function createRouteHandlers(host: () => Promise<ProtocolHost>, state: HostState | undefined): AvNextHandlers;
+export {};

package/dist/route-handlers.factory.js

@@ -0,0 +1,69 @@
+import { AvProtocol } from "@aventara/core/protocol";
+import { notFound } from "next/navigation";
+import { MCP_ROUTES, PROTOCOL_ROUTES, } from "./protocol-route.table.js";
+import { readRawBody, readRequestBody, unreadBodyAnswer, } from "./request-body.reader.js";
+import { mcpRequest, NO_BYTES, pathnameOf, protocolRequest, webResponse, } from "./web-exchange.translator.js";
+export function bindProtocolHost(framework, mcp) {
+    const binding = AvProtocol.bind(framework);
+    return {
+        mcp: mcp === undefined
+            ? undefined
+            : {
+                maxRequestBytes: mcp.maxRequestBytes,
+                routes: new Map(mcp
+                    .surface()
+                    .map((route) => [route.path, MCP_ROUTES[route.kind](mcp)])),
+            },
+        binding,
+        api: framework.api,
+        maxRequestBytes: framework.contracts.client.limits.maxRequestBytes,
+        routes: new Map(binding
+            .surface()
+            .map((route) => [
+            routeKey(route.method, route.path),
+            PROTOCOL_ROUTES[route.kind](binding),
+        ])),
+    };
+}
+export const routeKey = (method, path) => `${method} ${path}`;
+function outsideApi(pathname, api) {
+    return `Aventara: a request for ${pathname} reached handlers, which serve the configured \`api\` path ${api === "" ? "/" : api}; put the route file at app${api}/[...aventara]/route.ts.`;
+}
+export function createRouteHandlers(host, state) {
+    const handle = async (request) => {
+        const pathname = pathnameOf(request);
+        const { binding, api, maxRequestBytes, routes, mcp } = await host();
+        const seed = state === undefined
+            ? undefined
+            : () => state({ headers: request.headers, request });
+        const mcpAnswer = mcp?.routes.get(pathname);
+        if (mcp !== undefined && mcpAnswer !== undefined) {
+            const body = await readRawBody(request, mcp.maxRequestBytes);
+            return webResponse(await mcpAnswer(mcpRequest(request, body.content), seed));
+        }
+        if (pathname !== api && !pathname.startsWith(`${api}/`)) {
+            throw new Error(outsideApi(pathname, api));
+        }
+        const path = pathname.slice(api.length);
+        const answer = routes.get(routeKey(request.method, path));
+        if (answer === undefined) {
+            const absent = binding.answerAbsent(protocolRequest(request, path, NO_BYTES));
+            if (absent === undefined) {
+                notFound();
+            }
+            return webResponse(absent);
+        }
+        const body = await readRequestBody(request, maxRequestBytes);
+        if (body.kind !== "read") {
+            return webResponse(unreadBodyAnswer(binding, body));
+        }
+        return webResponse(await answer(protocolRequest(request, path, body.content), seed));
+    };
+    return Object.freeze({
+        GET: handle,
+        POST: handle,
+        PUT: handle,
+        PATCH: handle,
+        DELETE: handle,
+    });
+}

package/dist/server-operations.factory.d.ts

@@ -0,0 +1,38 @@
+import { type AvExecutionOptions, type AvFramework, type AvOperation, type AvState, type AvTransactionResults } from "@aventara/core";
+/**
+ * `avClient.transaction`: runs `avClient.tx` handles as one transaction, with
+ * this request's state. Client-layer handles only: an `avApp.appTx` handle in
+ * the list is a type error, and refused at runtime (`A2004`/`V1020`).
+ */
+export type AvNextClientTransaction = <const Ops extends readonly AvOperation<unknown, "client">[]>(operations: Ops, options?: AvExecutionOptions) => Promise<AvTransactionResults<Ops>>;
+/**
+ * `avApp.transaction`: runs `avApp.appTx` handles as one transaction.
+ * Application handles only: an `avClient.tx` handle in the list is a type
+ * error, and refused at runtime (`A2004`/`V1020`).
+ */
+export type AvNextAppTransaction = <const Ops extends readonly AvOperation<unknown, "application">[]>(operations: Ops, options?: AvExecutionOptions) => Promise<AvTransactionResults<Ops>>;
+/** Where the members find their Framework: built on first use, once. */
+export type FrameworkSource = {
+    /** The Framework, built on the first call; a construction error is kept. */
+    readonly built: () => Promise<AvFramework>;
+    /** The Framework when it is already built, else `undefined`. */
+    readonly current: () => AvFramework | undefined;
+};
+/**
+ * Refuses a Framework one of whose Resources, in the Contract of the layer
+ * `avClient` or `avApp` serves (client, application), is named like that
+ * tree's own member (`tx`, `transaction`, `appTx`).
+ *
+ * @throws {@link AvConstructionError} naming each clash.
+ */
+export declare function refuseMemberClashes(framework: AvFramework): void;
+/**
+ * `avClient` and `avApp` over the Framework `source` builds. Each call awaits
+ * the Framework, then runs the Framework's own member: `avClient`'s with the
+ * request's state from `requestState` (a `state` the call names wins),
+ * `avApp`'s as given.
+ */
+export declare function createServerOperations(source: FrameworkSource, requestState: () => Promise<AvState | undefined>): {
+    readonly avClient: object;
+    readonly avApp: object;
+};