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

package/dist/request-state.cache.js

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

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, request.signal));
+    };
+    return Object.freeze({
+        GET: handle,
+        POST: handle,
+        PUT: handle,
+        PATCH: handle,
+        DELETE: handle,
+    });
+}

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

@@ -0,0 +1,40 @@
+import { type AvExecutionOptions, type AvFramework, type AvOperation, type AvState, type AvTransactionResults } from "@aventara/core";
+import type { AccessClient } from "./host-bootstrap.validator.js";
+/**
+ * `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. */
+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>, access: AccessClient | undefined): {
+    readonly avClient: object;
+    readonly avApp: object;
+};
+export {};

package/dist/server-operations.factory.js

@@ -0,0 +1,191 @@
+import { AvConstructionError, AvProtocolError, } from "@aventara/core";
+import { ACCESS_VERB_NAMES, ACCESS_VERBS, providerVerb, } from "@aventara/core/internal";
+import { io } from "next/cache.js";
+import { headers } from "next/headers.js";
+function ioBeforeCall() {
+    try {
+        return io();
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
+const handlesBeforeBuild = (member) => `Aventara: \`${member}\` builds its handles on the Framework, which is built on first use; \`await ready()\` before building them.`;
+const CLIENT_MEMBERS = ["all", "tx", "transaction", "$access"];
+const APPLICATION_MEMBERS = ["appTx", "transaction"];
+export function refuseMemberClashes(framework) {
+    const clashes = [
+        ...clashesOf("avClient", framework.contracts.client.resources, CLIENT_MEMBERS),
+        ...clashesOf("avApp", framework.contracts.application.resources, APPLICATION_MEMBERS),
+    ];
+    if (clashes.length > 0) {
+        throw new AvConstructionError("contract-compilation", clashes.map(({ tree, member }) => ({
+            code: "COMPILER_RESERVED_RESOURCE_NAME",
+            path: `adapter.model.resources.${member}`,
+            message: `resource "${member}" clashes with ${tree}.${member}; rename the Resource or expose it under another name`,
+        })));
+    }
+}
+function clashesOf(tree, resources, members) {
+    return members
+        .filter((member) => Object.hasOwn(resources, member))
+        .map((member) => ({ tree, member }));
+}
+export function createServerOperations(source, requestState, access) {
+    const withRequestState = async (options) => {
+        if (options?.state !== undefined) {
+            return options;
+        }
+        const state = await requestState();
+        return state === undefined ? options : { ...options, state };
+    };
+    const asGiven = async (options) => options;
+    const clientTransaction = transactionOf(source, withRequestState);
+    const all = allOf(source);
+    const applicationTransaction = transactionOf(source, asGiven);
+    const verbs = accessOf(source, withRequestState, access);
+    return {
+        avClient: operationTree("avClient", source, (framework) => framework.serverClient, withRequestState, {
+            all: () => all,
+            tx: () => builders(source, "avClient.tx").serverClientTx,
+            transaction: () => clientTransaction,
+            $access: () => verbs,
+        }),
+        avApp: operationTree("avApp", source, (framework) => framework.application, asGiven, {
+            appTx: () => builders(source, "avApp.appTx").appTx,
+            transaction: () => applicationTransaction,
+        }),
+    };
+}
+const ACCESS_VERB_OPTIONS = [
+    ["can", 1],
+    ...ACCESS_VERB_NAMES.map((name) => [name, ACCESS_VERBS[name].args ? 1 : 0]),
+];
+function servedVerbs(access) {
+    if (access === undefined) {
+        return new Set();
+    }
+    const verbs = access.client?.verbs ?? {};
+    return new Set([
+        "can",
+        ...ACCESS_VERB_NAMES.filter((name) => providerVerb(verbs, name) !== undefined),
+    ]);
+}
+function unservedVerb(name, access) {
+    const why = access === undefined
+        ? `avClient.$access.${name}: this Framework has no \`access\`, so avClient has no $access.`
+        : `avClient.$access.${name}: the access provider offers no \`${name}\` (its \`client\` states no such verb).`;
+    return async () => {
+        throw new AvProtocolError("A2002", why);
+    };
+}
+function accessOf(source, fill, access) {
+    const served = servedVerbs(access);
+    const verbs = {};
+    const unserved = new Map();
+    for (const [name, at] of ACCESS_VERB_OPTIONS) {
+        if (!served.has(name)) {
+            unserved.set(name, unservedVerb(name, access));
+            continue;
+        }
+        verbs[name] = async (...args) => {
+            await ioBeforeCall();
+            const framework = await source.built();
+            const call = framework.serverClient.$access?.[name];
+            if (call === undefined) {
+                return unservedVerb(name, access)();
+            }
+            const given = args[at];
+            const called = args.slice(0, at);
+            called[at] =
+                name === "can"
+                    ? await fill(given)
+                    : given?.headers !== undefined
+                        ? given
+                        : { ...given, headers: await headers() };
+            return call(...called);
+        };
+    }
+    return new Proxy(Object.freeze(verbs), {
+        get: (target, key, receiver) => typeof key === "string" && unserved.has(key)
+            ? unserved.get(key)
+            : Reflect.get(target, key, receiver),
+    });
+}
+function builders(source, member) {
+    const framework = source.current();
+    if (framework === undefined) {
+        throw new Error(handlesBeforeBuild(member));
+    }
+    return framework;
+}
+function transactionOf(source, fill) {
+    return async (operations, options) => {
+        await ioBeforeCall();
+        const framework = await source.built();
+        return framework.transaction(operations, await fill(options));
+    };
+}
+const NEVER_A_RESOURCE = new Set(["then", "__esModule"]);
+function allOf(source) {
+    return async (entries, options) => {
+        await ioBeforeCall();
+        const framework = await source.built();
+        return framework.serverClient.all(entries, options);
+    };
+}
+function operationTree(name, source, layer, fill, members) {
+    const leaf = (path) => async (args, options) => {
+        await ioBeforeCall();
+        const framework = await source.built();
+        const call = memberAt(layer(framework), path);
+        if (typeof call !== "function") {
+            throw new TypeError(`${name}.${path.join(".")} is not a function`);
+        }
+        return call(args, await fill(options));
+    };
+    const resources = new Map();
+    return new Proxy(Object.freeze(Object.create(null)), {
+        get: (_target, key) => {
+            if (typeof key !== "string" || NEVER_A_RESOURCE.has(key)) {
+                return undefined;
+            }
+            const member = Object.hasOwn(members, key) ? members[key] : undefined;
+            if (member !== undefined) {
+                return member();
+            }
+            let resource = resources.get(key);
+            if (resource === undefined) {
+                resource = keyedNodes((family) => keyedNodes((variant) => leaf([key, family, variant])));
+                resources.set(key, resource);
+            }
+            return resource;
+        },
+    });
+}
+function keyedNodes(child) {
+    const children = new Map();
+    return new Proxy(Object.freeze(Object.create(null)), {
+        get: (_target, key) => {
+            if (typeof key !== "string" || NEVER_A_RESOURCE.has(key)) {
+                return undefined;
+            }
+            if (!children.has(key)) {
+                children.set(key, child(key));
+            }
+            return children.get(key);
+        },
+    });
+}
+function memberAt(root, path) {
+    let node = root;
+    for (const key of path) {
+        if (typeof node !== "object" ||
+            node === null ||
+            !Object.hasOwn(node, key)) {
+            return undefined;
+        }
+        node = node[key];
+    }
+    return node;
+}

package/dist/shared-framework.registry.d.ts

@@ -0,0 +1,25 @@
+import type { AvFramework } from "@aventara/core";
+/** One `api` path's build, shared by every copy of the module that calls `Aventara()` with the same options. */
+export type FrameworkSlot = {
+    readonly fingerprint: string;
+    /** The build: once started, kept, a construction error included. */
+    framework: Promise<AvFramework> | undefined;
+    /** The Framework once built. */
+    built: AvFramework | undefined;
+};
+/**
+ * The slot for `api` in this process: the one a copy of the same module
+ * already holds (the same `fingerprint`), else a new one. A different
+ * fingerprint is refused in production and replaces the slot otherwise.
+ *
+ * @throws Error when another configuration holds `api` in production.
+ */
+export declare function frameworkSlot(api: string, fingerprint: string, source: string): FrameworkSlot;
+/**
+ * The options' fingerprint: their plain data in a stable order; a function or
+ * any other object than plain data and arrays counts only as present, since
+ * bundlers spell them differently in each layer of one app. With `functions`
+ * `"source"`, a function counts by its source text instead: what one layer
+ * compares with its own last call.
+ */
+export declare function optionsFingerprint(options: unknown, functions?: "presence" | "source"): string;

package/dist/shared-framework.registry.js

@@ -0,0 +1,75 @@
+const KEY_PREFIX = "aventara.next.framework:";
+const environment = () => globalThis.process?.env;
+const lastCalls = new Map();
+const frameworkKey = (api) => Symbol.for(`${KEY_PREFIX}${api}`);
+function claimed(api) {
+    return `Aventara: another configuration already serves the \`api\` path ${api === "" ? "/" : api} in this process; give each Aventara() its own \`api\` path.`;
+}
+export function frameworkSlot(api, fingerprint, source) {
+    const key = frameworkKey(api);
+    const global = globalThis;
+    const held = global[key];
+    const production = environment()?.NODE_ENV === "production";
+    const last = lastCalls.get(api);
+    if (held !== undefined) {
+        if (held.fingerprint === fingerprint) {
+            const edited = !production && last?.slot === held && last.source !== source;
+            if (!edited) {
+                lastCalls.set(api, { source, slot: held });
+                return held;
+            }
+        }
+        else if (production) {
+            throw new Error(claimed(api));
+        }
+    }
+    const slot = {
+        fingerprint,
+        framework: undefined,
+        built: undefined,
+    };
+    global[key] = slot;
+    lastCalls.set(api, { source, slot });
+    return slot;
+}
+export function optionsFingerprint(options, functions = "presence") {
+    const seen = new Set();
+    const walk = (value) => {
+        switch (typeof value) {
+            case "function":
+                return functions === "source"
+                    ? `fn${JSON.stringify(Function.prototype.toString.call(value))}`
+                    : "fn";
+            case "bigint":
+                return `${value}n`;
+            case "object":
+                break;
+            default:
+                return String(JSON.stringify(value));
+        }
+        if (value === null) {
+            return "null";
+        }
+        if (seen.has(value)) {
+            return "[cycle]";
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            let text = "[";
+            for (const member of value) {
+                text += `${walk(member)},`;
+            }
+            return `${text}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return "obj";
+        }
+        let text = "{";
+        for (const key of Object.keys(value).sort()) {
+            text += `${JSON.stringify(key)}:${walk(value[key])},`;
+        }
+        return `${text}}`;
+    };
+    return walk(options);
+}

package/dist/universal-path.registry.d.ts

@@ -0,0 +1,28 @@
+import type { StateSeed } from "./protocol-route.table.js";
+import { type ProtocolHost } from "./route-handlers.factory.js";
+/** The `globalThis` key the in-process path is registered under. */
+export declare const UNIVERSAL_PATH_KEY: unique symbol;
+/** The request the generated client's transport hands to its `fetch`: a cached read's GET has no body. */
+export type UniversalRequest = {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string;
+};
+/** What the generated client's transport reads of a `fetch` answer. */
+export type UniversalAnswer = {
+    readonly status: number;
+    text(): Promise<string>;
+};
+/** The in-process path: the generated client's request in, the protocol's answer out. */
+export type UniversalPath = (url: string, init: UniversalRequest) => Promise<UniversalAnswer>;
+/**
+ * The in-process path over the protocol `host` resolves to: each request is
+ * answered by the bound member its route names, with the state `state` seeds,
+ * or by the protocol's absence answer.
+ */
+export declare function universalPath(host: () => Promise<ProtocolHost>, state: StateSeed | undefined): UniversalPath;
+/**
+ * Registers `path` as this server's in-process path for `@/aventara/universal`,
+ * and `access`, `avClient.$access`, as its `$access` verbs on the server.
+ */
+export declare function registerUniversalPath(path: UniversalPath, access?: object): void;

package/dist/universal-path.registry.js

@@ -0,0 +1,55 @@
+import { routeKey } from "./route-handlers.factory.js";
+export const UNIVERSAL_PATH_KEY = Symbol.for("aventara.next.universal");
+const IN_PROCESS = new AbortController().signal;
+function outsideApi(url, api) {
+    return `Aventara: @/aventara/universal called ${url} on the server, which is not under the configured \`api\` path ${api === "" ? "/" : api}; run aventara-build --client again (npm run aventara:prepare).`;
+}
+export function universalPath(host, state) {
+    return async (url, init) => {
+        const { binding, api, routes } = await host();
+        if (url !== api && !url.startsWith(`${api}/`)) {
+            throw new Error(outsideApi(url, api));
+        }
+        const [path = "", query] = splitQuery(url.slice(api.length));
+        const request = {
+            method: init.method,
+            path,
+            ...(query === undefined ? {} : { query }),
+            headers: Object.fromEntries(new Headers(init.headers)),
+            body: { kind: "raw", content: init.body ?? "" },
+        };
+        const answer = routes.get(routeKey(init.method, path));
+        const response = answer === undefined
+            ? binding.answerAbsent(request)
+            : await answer(request, state, IN_PROCESS);
+        if (response === undefined) {
+            throw new Error(outsideApi(url, api));
+        }
+        const { body } = response;
+        return {
+            status: response.status,
+            text: async () => (typeof body === "string" ? body : await joined(body)),
+        };
+    };
+}
+function splitQuery(url) {
+    const mark = url.indexOf("?");
+    return mark === -1
+        ? [url, undefined]
+        : [url.slice(0, mark), url.slice(mark + 1)];
+}
+async function joined(lines) {
+    let text = "";
+    for await (const line of lines) {
+        text += line;
+    }
+    return text;
+}
+const UNIVERSAL_ACCESS_KEY = Symbol.for("aventara.next.universal.access");
+export function registerUniversalPath(path, access) {
+    const holder = globalThis;
+    holder[UNIVERSAL_PATH_KEY] = path;
+    if (access !== undefined) {
+        holder[UNIVERSAL_ACCESS_KEY] = access;
+    }
+}

package/dist/value.dehydrator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Makes data an Aventara client answered safe to pass from the server to the
+ * browser: each `Date`, `bigint`, `Uint8Array` and decimal becomes a tagged
+ * plain object, which `avHydrate` (from `@/aventara/client`) revives in the
+ * browser, a decimal as the browser client's own `AvDecimal`. Arrays and
+ * plain objects are copied with their members dehydrated; any other value is
+ * returned as it is.
+ *
+ * Give it to TanStack Query as `dehydrate(queryClient, { serializeData: avDehydrate })`,
+ * or call it on an SWR `fallback` in a Server Component.
+ *
+ * @throws TypeError for a `Date` with no wire form (invalid, or a year past four digits).
+ */
+export declare function avDehydrate(data: unknown): unknown;

package/dist/value.dehydrator.js

@@ -0,0 +1,72 @@
+import { AvProtocol } from "@aventara/core/protocol";
+import { HYDRATION_FORMAT } from "./hydration-tag.format.js";
+const { tagKey, valueKey, objectTag } = HYDRATION_FORMAT;
+const DECIMAL = new RegExp(AvProtocol.scalarFormats.decimal);
+const DATETIME = new RegExp(AvProtocol.scalarFormats.datetime);
+const tagged = (tag, wire) => ({
+    [tagKey]: tag,
+    [valueKey]: wire,
+});
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function decimalString(value) {
+    const methods = value;
+    if (typeof methods.toString !== "function" ||
+        typeof methods.toJSON !== "function") {
+        return undefined;
+    }
+    const digits = methods.toString.call(value);
+    return typeof digits === "string" &&
+        DECIMAL.test(digits) &&
+        methods.toJSON.call(value) === digits
+        ? digits
+        : undefined;
+}
+function base64Of(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function datetimeOf(date) {
+    const wire = Number.isNaN(date.getTime()) ? "" : date.toISOString();
+    if (!DATETIME.test(wire)) {
+        throw new TypeError("avDehydrate: a Date that is invalid, or whose year is not four digits, has no wire form.");
+    }
+    return wire;
+}
+function dehydratedMembers(record) {
+    return Object.fromEntries(Object.entries(record).map(([key, member]) => [key, avDehydrate(member)]));
+}
+export function avDehydrate(data) {
+    switch (typeof data) {
+        case "bigint":
+            return tagged("bigint", data.toString(10));
+        case "object":
+            break;
+        default:
+            return data;
+    }
+    if (data === null) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.map((member) => avDehydrate(member));
+    }
+    if (data instanceof Date) {
+        return tagged("datetime", datetimeOf(data));
+    }
+    if (data instanceof Uint8Array) {
+        return tagged("bytes", base64Of(data));
+    }
+    if (isPlainObject(data)) {
+        return Object.hasOwn(data, tagKey)
+            ? tagged(objectTag, dehydratedMembers(data))
+            : dehydratedMembers(data);
+    }
+    const decimal = decimalString(data);
+    return decimal === undefined ? data : tagged("decimal", decimal);
+}

package/dist/web-exchange.translator.d.ts

@@ -0,0 +1,23 @@
+import type { AvProtocolRequest } from "@aventara/core/protocol";
+import type { McpRequest } from "./mcp-binding.loader.js";
+import type { RouteResponse } from "./protocol-route.table.js";
+/** Zero bytes: the body of a request whose body the protocol does not read. */
+export declare const NO_BYTES: Uint8Array<ArrayBuffer>;
+/**
+ * A request URL's pathname, as the `Request` carries it: the query dropped and
+ * nothing URL-decoded.
+ */
+export declare function pathnameOf(request: Request): string;
+/**
+ * The request as the protocol reads it: path relative to the mount path, raw
+ * query (rc.11: a cached read's `q` and `v`), its headers, raw body.
+ */
+export declare function protocolRequest(request: Request, path: string, content: Uint8Array): AvProtocolRequest;
+/** The request as `@aventara/mcp` reads it: absolute URL at the origin the caller used, its headers, raw body, no peer address. */
+export declare function mcpRequest(request: Request, content: Uint8Array): McpRequest;
+/**
+ * The protocol's answer as the route handler's `Response`: status, headers and
+ * body as they are. A streamed body (`/_all` under NDJSON) is a
+ * `ReadableStream` that pulls each line as core yields it.
+ */
+export declare function webResponse(answer: RouteResponse): Response;