@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/protocol/protocol.binder.d.ts

@@ -1,6 +1,7 @@
-import type { Framework } from "../framework/framework.js";
-import type { OperationResponse } from "../runtime/operation-response.js";
-import type { TransactionResponse } from "../transactions/transaction-response.js";
+import type { AvFramework } from "../framework/framework.js";
+import type { AvOperationResponse } from "../runtime/operation-response.js";
+import type { AvState } from "../runtime/request-state.js";
+import type { AvTransactionResponse } from "../transactions/transaction-response.js";
 import { type AvProtocolRequest, type DecodedOperation, type DecodedOperationRequest, type DecodedTransaction } from "./http-request.decoder.js";
 import { type AvProtocolResponse } from "./http-response.encoder.js";
 import { transportFailure } from "./protocol-failure.js";
@@ -11,49 +12,52 @@ import { type SurfaceRoute } from "./protocol-surface.js";
  */
 export type AvProtocolBinding = {
     /**
-     * Every route a host mounts for the bound ClientContract, from one list, each
+     * Every route a host mounts for the bound Contract (the Client Contract, or the
+     * Agent Contract under `{ origin: "agent" }`), from one list, each
      * tagged by `kind`: one `POST` `operation` route per `(resource, family, variant)`
-     * it advertises — nothing it does not — then the `contract` route `GET /_contract`
+     * it advertises and no other, then the `contract` route `GET /_contract`
      * (always), then the `transactions` route `POST /_transactions` exactly when its
-     * `transactions` is `"interactive"`. Each path is relative to
-     * `framework.entrypoint`. Read once at bind time: every call answers the same
+     * `transactions` is `"interactive"`, then the `can` route `POST /_access/can`
+     * exactly when it has its `access` section. Each path is relative to
+     * `framework.api`. Read once at bind time: every call answers the same
      * deep-frozen list, which is passive data a host may serialize.
      */
     readonly surface: () => readonly SurfaceRoute[];
     /**
-     * An operation route's HTTP request → the client-origin request
+     * An operation route's HTTP request → the client-origin (or the binding's
+     * agent-origin) request
      * `framework.execute` takes, or the framework response that answers it instead,
      * with the request id either way. Answers absence for an unadvertised triple
      * without executing it, so a catch-all host is safe. Raw body: size, content type,
-     * JSON and shape enforced; parsed body: shape only — the rest was the host's
-     * parser's.
+     * JSON and shape enforced; parsed body: shape only, since the rest was the
+     * host's parser's job.
      */
     readonly decodeOperation: (request: AvProtocolRequest) => DecodedOperation;
     /**
-     * The same for `/_transactions` → the client-origin plan request
-     * `framework.executeTransaction` takes; absent unless the ClientContract's
+     * The same for `/_transactions` → the binding's origin's plan request
+     * `framework.executeTransaction` takes; absent unless the bound Contract's
      * transactions are `"interactive"`.
      */
     readonly decodeTransaction: (request: AvProtocolRequest) => DecodedTransaction;
     /**
-     * One operation's framework response — what `framework.execute` answered — as the
+     * One operation's framework response (what `framework.execute` answered) as the
      * HTTP response a host writes: the code's status, `data` in wire forms, `Aventara-
      * Request-Id` echoed. A result with no wire form answers `A3003` → 500. A
      * diagnostic of one operation names it (`resource`, `family`, `variant`), so the
-     * `A3003` reaches the diagnostics sink only when the host passes `decoded` —
-     * `decodeOperation`'s success value — as `handleOperation` does; without it the
+     * `A3003` reaches the diagnostics sink only when the host passes `decoded`
+     * (`decodeOperation`'s success value), as `handleOperation` does; without it the
      * answer is the same and nothing is reported.
      */
-    readonly encodeOperation: (response: OperationResponse, requestId: string, decoded?: DecodedOperationRequest) => AvProtocolResponse;
+    readonly encodeOperation: (response: AvOperationResponse, requestId: string, decoded?: DecodedOperationRequest) => AvProtocolResponse;
     /**
-     * The same for `/_transactions` — what `framework.executeTransaction` answered. An
+     * The same for `/_transactions`: what `framework.executeTransaction` answered. An
      * `A3003` is reported to the Framework's diagnostics sink as a `"transaction"`
-     * diagnostic — client origin, this `requestId`, the step it blames as `operation` —
+     * diagnostic (client origin, this `requestId`, the step it blames as `operation`)
      * with the value that had no wire form (or what its getter threw) as `error`.
      */
-    readonly encodeTransaction: (response: TransactionResponse, requestId: string) => AvProtocolResponse;
+    readonly encodeTransaction: (response: AvTransactionResponse, requestId: string) => AvProtocolResponse;
     /**
-     * A transport code — `A2000`, `A2010`, `A2011` or `A2012` — as the complete
+     * A transport code (`A2000`, `A2010`, `A2011` or `A2012`) as the complete
      * framework response. For a host that parses the body itself and must answer
      * its parser's failure. `A2012` requires the methods its route allows, so
      * every 405 carries `Allow`.
@@ -67,20 +71,44 @@ export type AvProtocolBinding = {
      * host hands it: one that is not an `AvProtocolRequest` answers `400 A2000`; it
      * never rejects.
      */
-    readonly handleOperation: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
+    readonly handleOperation: (request: AvProtocolRequest, options?: {
+        /**
+         * Seeds the request's `ctx.$state` (a host reads its platform request
+         * here, Passport's `req.user`, say). Called once, after decoding; a
+         * throw is answered like any developer failure. Omitted, the state is `{}`.
+         */
+        readonly state?: () => AvState | Promise<AvState>;
+    }) => Promise<AvProtocolResponse>;
     /**
      * The same for `/_transactions`: `decodeTransaction` →
      * `framework.executeTransaction` → `encodeTransaction`. Every step runs under
      * ClientContract rules; a committed plan is `200 A1009`, a rolled-back one its
      * failing step's own status.
      */
-    readonly handleTransaction: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
+    readonly handleTransaction: (request: AvProtocolRequest, options?: {
+        /** Seeds the plan's one `ctx.$state`, as for `handleOperation`. */
+        readonly state?: () => AvState | Promise<AvState>;
+    }) => Promise<AvProtocolResponse>;
+    /**
+     * The `POST /_access/can` shortcut: the request decoded, its `ctx.$state`
+     * seeded through `options.state`, its `{ questions }` answered by the bound
+     * Framework's policy engine under the principal `ctx.$state.me`, and the answer
+     * encoded: `200 A1000` with one boolean per question, in order. It only shapes
+     * a UI, so it refuses malformed input only, never `403`. Absent (`404 A2002`)
+     * unless the bound Contract has its `access` section, which it has exactly when
+     * the framework's `access` option is configured. Total over any value, as
+     * `handleOperation` is.
+     */
+    readonly handleCan: (request: AvProtocolRequest, options?: {
+        /** Seeds the request's `ctx.$state`, as for `handleOperation`. */
+        readonly state?: () => AvState | Promise<AvState>;
+    }) => Promise<AvProtocolResponse>;
     /**
      * The `GET /_contract` responder: the bound ClientContract's JCS-canonical bytes,
      * `ETag` its quoted hash, `Cache-Control: no-cache`, and `304` with no body when
      * `If-None-Match` matches (weak comparison, a list, `*`). Requires no identity
-     * header; any other method is `405 A2012` with `Allow: GET`. The bytes are written
-     * once, at bind time.
+     * header; any other method is `405 A2012` with `Allow: GET`. The bytes are the ones
+     * the Contract's hash was taken over, written once, at construction.
      */
     readonly encodeContract: (request: AvProtocolRequest) => AvProtocolResponse;
     /**
@@ -91,12 +119,22 @@ export type AvProtocolBinding = {
      * `undefined` for a path outside the protocol's namespace, which the host
      * answers itself. An operation or `/_transactions` route answered `500 A3000`
      * is also reported once to the Framework's diagnostics sink, as an
-     * `UnmountedRouteError` naming the route the host did not mount.
+     * `AvUnmountedRouteError` naming the route the host did not mount.
      */
     readonly answerAbsent: (request: AvProtocolRequest) => AvProtocolResponse | undefined;
 };
 /**
- * `AvProtocol.bind(framework)`: reads the instance's compiled ClientContract
- * once and returns the bound members, frozen.
+ * `AvProtocol.bind(framework, options?)`: reads the instance's compiled Client
+ * Contract (or, with `{ origin: "agent" }`, its Agent Contract) once and returns
+ * the bound members, frozen. Every request decoded through it runs under that
+ * origin.
  */
-export declare function bind(framework: Framework): AvProtocolBinding;
+export declare function bind(framework: AvFramework, options?: {
+    /**
+     * The origin every request through this binding runs under: `"client"`
+     * (the default: the Client Contract, `/_contract`'s document) or `"agent"`
+     * (the Agent Contract, its hash and its layer's pipelines), for a host
+     * that serves an AI agent — an MCP server.
+     */
+    readonly origin?: "client" | "agent";
+}): AvProtocolBinding;

package/dist/protocol/protocol.binder.js

@@ -1,36 +1,42 @@
+import { accessQuestionsOf } from "../policy/access-question.registry.js";
 import { diagnosticsSinkOf } from "../runtime/diagnostics-reporter.js";
 import { ownedExecutionOf } from "../runtime/owned-execution.registry.js";
 import { answerAbsentRequest } from "./absent-route.responder.js";
 import { contractDocumentOf, encodeContractRequest, } from "./contract-document.responder.js";
 import { decodeOperationRequest, decodeTransactionRequest, } from "./http-request.decoder.js";
 import { encodeOperationResponse, encodeTransactionResponse, } from "./http-response.encoder.js";
-import { handleOperationRequest, handleTransactionRequest, operationUnencodableReport, planUnencodableReport, } from "./protocol.handler.js";
+import { handleCanRequest, handleOperationRequest, handleTransactionRequest, operationUnencodableReport, planUnencodableReport, } from "./protocol.handler.js";
 import { transportFailure } from "./protocol-failure.js";
 import { surfaceOf } from "./protocol-surface.js";
-export function bind(framework) {
+export function bind(framework, options) {
     const { contracts } = framework;
-    const surface = surfaceOf(contracts.client);
-    const document = contractDocumentOf(contracts.client);
+    const origin = options?.origin === "agent" ? "agent" : "client";
+    const contract = contracts[origin];
+    const surface = surfaceOf(contract);
+    const document = contractDocumentOf(contract);
     const sink = diagnosticsSinkOf(framework);
     const handler = {
         contracts,
+        origin,
         execute: (request) => framework.execute(request),
         executeTransaction: (request) => framework.executeTransaction(request),
         owned: ownedExecutionOf(framework),
         sink,
+        can: accessQuestionsOf(framework),
     };
     return Object.freeze({
         surface: () => surface,
-        decodeOperation: (request) => decodeOperationRequest(contracts, request),
-        decodeTransaction: (request) => decodeTransactionRequest(contracts, request),
+        decodeOperation: (request) => decodeOperationRequest(contracts, request, origin),
+        decodeTransaction: (request) => decodeTransactionRequest(contracts, request, origin),
         encodeOperation: (response, requestId, decoded) => encodeOperationResponse(response, requestId, decoded === undefined
             ? undefined
             : operationUnencodableReport(sink, decoded.request)),
-        encodeTransaction: (response, requestId) => encodeTransactionResponse(response, requestId, planUnencodableReport(sink, requestId)),
+        encodeTransaction: (response, requestId) => encodeTransactionResponse(response, requestId, planUnencodableReport(sink, requestId, origin)),
         failure: transportFailure,
-        handleOperation: (request) => handleOperationRequest(handler, request),
-        handleTransaction: (request) => handleTransactionRequest(handler, request),
+        handleOperation: (request, options) => handleOperationRequest(handler, request, options),
+        handleTransaction: (request, options) => handleTransactionRequest(handler, request, options),
+        handleCan: (request, options) => handleCanRequest(handler, request, options),
         encodeContract: (request) => encodeContractRequest(document, request),
-        answerAbsent: (request) => answerAbsentRequest(contracts, request, sink),
+        answerAbsent: (request) => answerAbsentRequest(contracts, request, sink, origin),
     });
 }

package/dist/protocol/protocol.handler.d.ts

@@ -1,8 +1,11 @@
-import type { FrameworkContracts } from "../compiler/contract.compiler.js";
-import type { Framework } from "../framework/framework.js";
-import { type FrameworkDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
-import type { ClientOperationRequest } from "../runtime/operation-request.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { RemoteRequestOrigin } from "../config/config-layer.js";
+import type { AvFramework } from "../framework/framework.js";
+import type { AccessQuestionsAnswerer } from "../policy/access-question.runtime.js";
+import { type AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
+import type { RemoteOperationRequest } from "../runtime/operation-request.js";
 import type { OwnedExecution } from "../runtime/owned-execution.registry.js";
+import type { AvState } from "../runtime/request-state.js";
 import { type AvProtocolRequest } from "./http-request.decoder.js";
 import { type AvProtocolResponse, type UnencodableReport } from "./http-response.encoder.js";
 /**
@@ -11,12 +14,21 @@ import { type AvProtocolResponse, type UnencodableReport } from "./http-response
  * decoder parsed without copying it again (absent for anything but a
  * constructed Framework) — and its configured diagnostics sink.
  */
-export type HandlerContext = {
-    readonly contracts: FrameworkContracts;
-    readonly execute: Framework["execute"];
-    readonly executeTransaction: Framework["executeTransaction"];
+type HandlerContext = {
+    readonly contracts: AvContracts;
+    /** The origin every request the binding decodes runs under. */
+    readonly origin: RemoteRequestOrigin;
+    readonly execute: AvFramework["execute"];
+    readonly executeTransaction: AvFramework["executeTransaction"];
     readonly owned: OwnedExecution | undefined;
-    readonly sink: FrameworkDiagnosticsSink | undefined;
+    readonly sink: AvDiagnosticsSink | undefined;
+    /** The Framework's `can` answerer: absent for one without `access`, or anything `createFramework` did not return. */
+    readonly can: AccessQuestionsAnswerer | undefined;
+};
+/** What a host passes beside one protocol request. */
+export type ProtocolCallOptions = {
+    /** Seeds the request's `ctx.$state`; called once, after decoding. Omitted, the state is `{}`. */
+    readonly state?: () => AvState | Promise<AvState>;
 };
 /**
  * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a `"transaction"`
@@ -24,15 +36,15 @@ export type HandlerContext = {
  * encoder blames as `operation` when it blames one. One spelling for both
  * `protocol.encodeTransaction` and `protocol.handleTransaction`.
  */
-export declare function planUnencodableReport(sink: FrameworkDiagnosticsSink | undefined, requestId: string): UnencodableReport;
+export declare function planUnencodableReport(sink: AvDiagnosticsSink | undefined, requestId: string, origin?: RemoteRequestOrigin): UnencodableReport;
 /**
  * Where one operation's `A3003` goes: the Framework's diagnostics sink, as an
  * `"operation"` diagnostic carrying the decoded request's identity and id — the shape
- * the public `OperationDiagnostic` already has. One spelling for
+ * the public `AvOperationDiagnostic` already has. One spelling for
  * `protocol.handleOperation` and for `protocol.encodeOperation` given the decoded
  * request.
  */
-export declare function operationUnencodableReport(sink: FrameworkDiagnosticsSink | undefined, request: ClientOperationRequest): UnencodableReport;
+export declare function operationUnencodableReport(sink: AvDiagnosticsSink | undefined, request: RemoteOperationRequest): UnencodableReport;
 /**
  * `protocol.handleOperation(request)`: the three steps a host would otherwise spell
  * out — `decodeOperation` → `framework.execute` → `encodeOperation` — in one call,
@@ -40,7 +52,7 @@ export declare function operationUnencodableReport(sink: FrameworkDiagnosticsSin
  * itself (a transport failure, an identity mismatch, an unadvertised route) is
  * answered without executing.
  */
-export declare function handleOperationRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;
+export declare function handleOperationRequest(context: HandlerContext, request: AvProtocolRequest, options?: ProtocolCallOptions): Promise<AvProtocolResponse>;
 /**
  * `protocol.handleTransaction(request)`: the same shortcut for `/_transactions` —
  * `decodeTransaction` → `framework.executeTransaction` → `encodeTransaction`. The
@@ -52,4 +64,12 @@ export declare function handleOperationRequest(context: HandlerContext, request:
  * handleOperationRequest} is; an `A3003` is reported through {@link
  * planUnencodableReport}.
  */
-export declare function handleTransactionRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;
+export declare function handleTransactionRequest(context: HandlerContext, request: AvProtocolRequest, options?: ProtocolCallOptions): Promise<AvProtocolResponse>;
+/**
+ * `protocol.handleCan(request)`: the `/_access/can` request decoded, its state
+ * seeded, its questions answered by the bound Framework, and the answer encoded —
+ * `200 A1000` with one boolean per question, in order, or the refusal. Total over
+ * any value, as {@link handleOperationRequest} is.
+ */
+export declare function handleCanRequest(context: HandlerContext, request: AvProtocolRequest, options?: ProtocolCallOptions): Promise<AvProtocolResponse>;
+export {};

package/dist/protocol/protocol.handler.js

@@ -1,20 +1,79 @@
+import { copyAtDoor } from "../runtime/caller-data.door.js";
 import { createDiagnosticsReporter, createReporter, } from "../runtime/diagnostics-reporter.js";
-import { decodeOperationRequest, decodeTransactionRequest, isParsedByDecoder, } from "./http-request.decoder.js";
+import { sanitizeOperationFailure } from "../runtime/error-boundary.js";
+import { internalFailure, } from "../runtime/operation-response.js";
+import { capturePlanAtCall } from "../transactions/transaction-plan-validator.js";
+import { decodeCanRequest, decodeOperationRequest, decodeTransactionRequest, isParsedByDecoder, } from "./http-request.decoder.js";
 import { encodeOperationResponse, encodeTransactionResponse, } from "./http-response.encoder.js";
-function operationEntry(context, request) {
-    return context.owned !== undefined && isParsedByDecoder(request.arguments)
-        ? context.owned.execute
-        : context.execute;
+function admitOperation(context, request) {
+    const owned = context.owned;
+    if (isParsedByDecoder(request.arguments)) {
+        return { request, run: owned?.execute ?? context.execute };
+    }
+    const copy = copyAtDoor(request.arguments);
+    if (owned === undefined) {
+        return {
+            request: copy.ok ? { ...request, arguments: copy.value } : request,
+            run: context.execute,
+        };
+    }
+    if (copy.ok) {
+        return {
+            request: { ...request, arguments: copy.value },
+            run: (admitted) => owned.execute(admitted),
+        };
+    }
+    return {
+        request: { ...request, arguments: {} },
+        run: (admitted) => owned.execute(admitted, copy.error),
+    };
 }
-function transactionEntry(context, request) {
-    return context.owned !== undefined && isParsedByDecoder(request.plan)
-        ? context.owned.executeTransaction
-        : context.executeTransaction;
+function admitTransaction(context, request) {
+    const owned = context.owned;
+    if (isParsedByDecoder(request.plan)) {
+        return {
+            request,
+            run: owned?.executeTransaction ?? context.executeTransaction,
+        };
+    }
+    const captured = capturePlanAtCall(request.plan);
+    if (owned === undefined) {
+        return {
+            request: captured.refused.size === 0
+                ? { ...request, plan: captured.plan }
+                : request,
+            run: context.executeTransaction,
+        };
+    }
+    return {
+        request: { ...request, plan: captured.plan },
+        run: (admitted) => owned.executeTransaction(admitted, captured.refused.size === 0 ? undefined : captured.refused),
+    };
+}
+async function seededState(options, report, view) {
+    if (options?.state === undefined) {
+        return { ok: true, state: undefined };
+    }
+    try {
+        const state = await options.state();
+        return {
+            ok: true,
+            state: typeof state === "object" && state !== null && !Array.isArray(state)
+                ? state
+                : undefined,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            response: sanitizeOperationFailure(error, "runtime", report, view),
+        };
+    }
 }
-export function planUnencodableReport(sink, requestId) {
+export function planUnencodableReport(sink, requestId, origin = "client") {
     return (error, operation) => createReporter(sink, {
         kind: "transaction",
-        origin: "client",
+        origin,
         requestId,
         ...(operation === undefined ? {} : { operation }),
     })(error, "A3003");
@@ -22,19 +81,64 @@ export function planUnencodableReport(sink, requestId) {
 export function operationUnencodableReport(sink, request) {
     return (error) => createDiagnosticsReporter(sink, request)(error, "A3003");
 }
-export async function handleOperationRequest(context, request) {
-    const decoded = decodeOperationRequest(context.contracts, request);
+export async function handleOperationRequest(context, request, options) {
+    const decoded = decodeOperationRequest(context.contracts, request, context.origin);
     if (!decoded.ok) {
         return decoded.response;
     }
-    const response = await operationEntry(context, decoded.request)(decoded.request);
+    const admitted = admitOperation(context, decoded.request);
+    const seeded = await seededState(options, createDiagnosticsReporter(context.sink, admitted.request), { path: ["arguments"], arguments: admitted.request.arguments });
+    const response = seeded.ok
+        ? await admitted.run(seeded.state === undefined
+            ? admitted.request
+            : { ...admitted.request, state: seeded.state })
+        : seeded.response;
     return encodeOperationResponse(response, decoded.requestId, operationUnencodableReport(context.sink, decoded.request));
 }
-export async function handleTransactionRequest(context, request) {
-    const decoded = decodeTransactionRequest(context.contracts, request);
+export async function handleTransactionRequest(context, request, options) {
+    const decoded = decodeTransactionRequest(context.contracts, request, context.origin);
     if (!decoded.ok) {
         return decoded.response;
     }
-    const response = await transactionEntry(context, decoded.request)(decoded.request);
-    return encodeTransactionResponse(response, decoded.requestId, planUnencodableReport(context.sink, decoded.requestId));
+    const admitted = admitTransaction(context, decoded.request);
+    const seeded = await seededState(options, createReporter(context.sink, {
+        kind: "transaction",
+        origin: context.origin,
+        requestId: decoded.requestId,
+    }), { path: ["plan"], arguments: admitted.request.plan });
+    const response = seeded.ok
+        ? await admitted.run(seeded.state === undefined
+            ? admitted.request
+            : { ...admitted.request, state: seeded.state })
+        : seeded.response;
+    return encodeTransactionResponse(response, decoded.requestId, planUnencodableReport(context.sink, decoded.requestId, context.origin));
+}
+export async function handleCanRequest(context, request, options) {
+    const decoded = decodeCanRequest(context.contracts, request, context.origin);
+    if (!decoded.ok) {
+        return decoded.response;
+    }
+    const { requestId, body } = decoded.request;
+    const report = createReporter(context.sink, {
+        kind: "can",
+        origin: "client",
+        requestId,
+    });
+    if (context.can === undefined) {
+        report(new Error("The bound Framework has no answerer for /_access/can."), "A3000");
+        return encodeOperationResponse(internalFailure(), requestId);
+    }
+    const seeded = await seededState(options, report, {
+        path: ["questions"],
+        arguments: body,
+    });
+    const response = seeded.ok
+        ? await context.can({
+            origin: context.origin,
+            requestId,
+            ...(seeded.state === undefined ? {} : { state: seeded.state }),
+            body,
+        })
+        : seeded.response;
+    return encodeOperationResponse(response, requestId);
 }

package/dist/protocol/unmounted-route.error.d.ts

@@ -5,15 +5,15 @@
  * `500 A3000` is unchanged; this error names the route the host left out, so the
  * server's diagnostics show it too. It is never sent to the caller.
  */
-export declare class UnmountedRouteError extends Error {
+export declare class AvUnmountedRouteError extends Error {
     /** What the ClientContract advertises: `resource.family.variant`, or `transactions`. */
     readonly advertised: string;
-    /** The route as the request reached it: method and entrypoint-relative path. */
+    /** The route as the request reached it: method and api-relative path. */
     readonly route: string;
-    readonly name = "UnmountedRouteError";
+    readonly name = "AvUnmountedRouteError";
     constructor(
     /** What the ClientContract advertises: `resource.family.variant`, or `transactions`. */
     advertised: string, 
-    /** The route as the request reached it: method and entrypoint-relative path. */
+    /** The route as the request reached it: method and api-relative path. */
     route: string);
 }

package/dist/protocol/unmounted-route.error.js

@@ -1,7 +1,7 @@
-export class UnmountedRouteError extends Error {
+export class AvUnmountedRouteError extends Error {
     advertised;
     route;
-    name = "UnmountedRouteError";
+    name = "AvUnmountedRouteError";
     constructor(advertised, route) {
         super(`The ClientContract advertises ${advertised}, but the host mounted no route for ${route}, so protocol.answerAbsent answered it 500 A3000. Mount every protocol.surface() entry.`);
         this.advertised = advertised;

package/dist/runtime/caller-data.copier.d.ts

@@ -1,5 +1,5 @@
 /** Why a caller value could not be copied. */
-export type CallerDataFailureKind = "unreadable-value" | "non-plain-value";
+type CallerDataFailureKind = "unreadable-value" | "non-plain-value";
 /** A data location inside the copied value, from its root. */
 export type CallerDataPath = readonly (string | number)[];
 /**
@@ -7,7 +7,7 @@ export type CallerDataPath = readonly (string | number)[];
  * root. Thrown by {@link copyCallerData} and caught by every door, which answers it as
  * the caller's `A2004`/`V1001` at its own address. It never carries the value.
  */
-export declare class CallerDataError extends Error {
+export declare class AvCallerDataError extends Error {
     readonly kind: CallerDataFailureKind;
     readonly path: CallerDataPath;
     /**
@@ -15,7 +15,7 @@ export declare class CallerDataError extends Error {
      * tripwire read after the door; {@link locateCallerDataError} resolves it.
      */
     readonly within?: object | undefined;
-    readonly name = "CallerDataError";
+    readonly name = "AvCallerDataError";
     constructor(kind: CallerDataFailureKind, path: CallerDataPath, 
     /**
      * The control mirror `path` starts from, when the failure is a mirror's
@@ -41,19 +41,34 @@ export type CallerDataPolicy = {
     readonly keep?: CallerDataKeep;
     readonly mirror?: CallerDataMirror;
 };
+/** The members a structural mirror copies by value rather than mirroring. */
+type MirrorMembers = {
+    /** The policy a member at `path` (from the mirror's root) is copied by, or `undefined`. */
+    readonly copyAt: (path: CallerDataPath) => CallerDataPolicy | undefined;
+    /** Receives a member whose copy failed; the mirror holds `undefined` for it. */
+    readonly refused: (path: CallerDataPath, error: AvCallerDataError) => void;
+};
+/**
+ * Mirrors `value` by its descriptors, as a `$ref` control object is mirrored (no
+ * getter runs, an accessor stays a tripwire), except the members `members.copyAt`
+ * names by their path: each is copied by value under the policy it returns, and one
+ * whose copy fails is reported to `members.refused` and held as `undefined`.
+ *
+ * @throws {@link AvCallerDataError} at `[]` when `value` itself cannot be reflected.
+ */
+export declare function mirrorCallerData(value: object, members: MirrorMembers): unknown;
 /**
  * Places a mirror tripwire's failure in the value the door copied: its path from the
  * copy's root, where `error.path` started from the mirror. A failure that is not a
  * tripwire's, or a mirror the copy does not hold, is returned as it is.
  */
-export declare function locateCallerDataError(error: CallerDataError, copy: unknown): CallerDataError;
+export declare function locateCallerDataError(error: AvCallerDataError, copy: unknown): AvCallerDataError;
 /**
  * Copies a caller's value into fresh plain data (see the module note), reading the
  * caller's objects exactly once.
  *
- * @throws {@link CallerDataError} when a value cannot be read or is not plain data,
+ * @throws {@link AvCallerDataError} when a value cannot be read or is not plain data,
  *   naming its path from `value`.
  */
 export declare function copyCallerData(value: unknown, policy?: CallerDataPolicy): unknown;
-/** The `V1001` message a door answers a {@link CallerDataError} with. */
-export declare function callerDataFailureMessage(kind: CallerDataFailureKind): string;
+export {};