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

package/dist/framework/access-facade.js

@@ -0,0 +1,120 @@
+import { projectJsonValue } from "../contracts/json-schema.projector.js";
+import { ACCESS_VERB_NAMES, ACCESS_VERBS, providerVerb, } from "../policy/access-verb.table.js";
+import { copyAtDoor } from "../runtime/caller-data.door.js";
+import { requestIdOf } from "../runtime/request-id.js";
+import { stateOptionOf } from "../runtime/request-state.resolver.js";
+import { encodeOperationArgumentsForWire } from "../transactions/operation-arguments-encoder.js";
+import { settleOperation } from "./operation-facade.js";
+export function createServerClientAccess(dependencies) {
+    const { contract, answer, client } = dependencies;
+    const stateFor = async (options) => {
+        if (options?.state !== undefined || options?.headers === undefined) {
+            return stateOf(options);
+        }
+        return {
+            state: await dependencies.state({
+                headers: requestHeadersOf(options.headers),
+                ...(options.request === undefined ? {} : { request: options.request }),
+            }),
+        };
+    };
+    const can = async (questions, options) => settleOperation(await answer({
+        origin: "client",
+        requestId: requestIdOf(options),
+        ...(await stateFor(options)),
+        body: wireQuestions(contract, questions),
+    }));
+    if (client === undefined) {
+        return Object.freeze({ can });
+    }
+    const verbs = { can };
+    for (const name of ACCESS_VERB_NAMES) {
+        const verb = providerVerb(client.verbs, name);
+        if (verb !== undefined) {
+            verbs[name] = serverVerb(verb, ACCESS_VERBS[name]);
+        }
+    }
+    return Object.freeze(verbs);
+}
+function serverVerb(verb, shape) {
+    const run = async (args, options) => {
+        const answer = await verb.call({
+            args,
+            headers: requestHeadersOf(options?.headers),
+            ...(options?.request === undefined ? {} : { request: options.request }),
+            ...(options?.response === undefined
+                ? {}
+                : { response: options.response }),
+        });
+        switch (shape.resolves) {
+            case "nothing":
+                return undefined;
+            default:
+                return answer === null || answer === undefined
+                    ? null
+                    : projectJsonValue(answer, verb.result);
+        }
+    };
+    return shape.args
+        ? (args, options) => run(args, options)
+        : (options) => run(undefined, options);
+}
+function stateOf(options) {
+    const state = stateOptionOf(options);
+    return state === undefined ? {} : { state };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function wireQuestions(contract, questions) {
+    const copy = copyAtDoor({ questions });
+    if (!copy.ok) {
+        return { questions };
+    }
+    const body = copy.value;
+    if (!Array.isArray(body.questions)) {
+        return body;
+    }
+    return {
+        questions: body.questions.map((question) => {
+            if (!isRecord(question) ||
+                !Object.hasOwn(question, "where") ||
+                typeof question.resource !== "string" ||
+                !Object.hasOwn(contract.resources, question.resource)) {
+                return question;
+            }
+            const encoded = encodeOperationArgumentsForWire(contract, { family: "find", variant: "unique", resource: question.resource }, { where: question.where });
+            return { ...question, where: encoded.where };
+        }),
+    };
+}
+function requestHeadersOf(headers) {
+    if (headers !== undefined &&
+        typeof headers.get === "function") {
+        return headers;
+    }
+    const lowered = new Map();
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        const values = typeof value === "string"
+            ? [value]
+            : Array.isArray(value)
+                ? value
+                : [];
+        if (values.length > 0) {
+            const key = name.toLowerCase();
+            const before = lowered.get(key);
+            lowered.set(key, before === undefined
+                ? values.join(", ")
+                : `${before}, ${values.join(", ")}`);
+        }
+    }
+    return Object.freeze({
+        get: (name) => lowered.get(name.toLowerCase()) ?? null,
+        has: (name) => lowered.has(name.toLowerCase()),
+        forEach: (callback) => {
+            for (const [name, value] of lowered) {
+                callback(value, name);
+            }
+        },
+    });
+}

package/dist/framework/contract-view.d.ts

@@ -17,6 +17,14 @@ type RootBlock<Cfg, Key extends PropertyKey> = LiteralRecord<(Cfg & {
 })[Key]>;
 /** The root's `resources` block, its stages erased. */
 type ResourcesBlock<Cfg> = ErasedResources<RootBlock<Cfg, "resources">>;
+/** A `resources` block reduced to the `fields` entries the view reads. */
+type ViewBlock<Block> = [Block] extends [never] ? never : {
+    readonly [R in keyof Block as "fields" extends keyof NonNullable<Block[R]> ? R : never]: {
+        readonly fields: (NonNullable<Block[R]> & {
+            readonly fields?: unknown;
+        })["fields"];
+    };
+};
 /** An overlay's `resources` block, its stages erased (see {@link ResourcesBlock}). */
 type OverlayResourcesBlock<Cfg, Layer extends AvRequestOrigin> = ErasedResources<LiteralRecord<(LiteralRecord<OverlayOf<Cfg, Layer>> & {
     readonly resources?: unknown;
@@ -90,12 +98,93 @@ type DefinitionOf<FieldEntry> = EntryOf<FieldEntry, "definition">;
 type LayeredFields<ModelFields, ResourceConfig> = {
     readonly [F in keyof ModelFields | AddedFieldKey<ModelFields, ResourceConfig>]: F extends keyof ModelFields ? LayeredModelField<ModelFields[F], DefinitionOf<EntryOf<ResourceConfig, F>>> : AddedField<DefinitionOf<EntryOf<ResourceConfig, F>>>;
 };
+/** The configuration's `policy.engine`, read by indexed access (see {@link RootBlock}). */
+type PolicyEngineOf<Cfg> = (NonNullable<(Cfg & {
+    readonly policy?: unknown;
+})["policy"]> & {
+    readonly engine?: unknown;
+})["engine"];
+/** The configuration's `access.policy`, read by indexed access. */
+type AccessEngineOf<Cfg> = ((Cfg & {
+    readonly access?: {
+        readonly policy?: unknown;
+    };
+})["access"] & {
+    readonly policy?: unknown;
+})["policy"];
+/** The configuration's policy engine's `governed` set, when its type states one. */
+type GovernedBlock<Cfg> = LiteralRecord<(NonNullable<PolicyEngineOf<Cfg>> & AccessEngineOf<Cfg> & {
+    readonly governed?: unknown;
+})["governed"]>;
+/** The names `Governed` lists for Resource `R`, or `never`. */
+type GovernedNames<Governed, R> = [Governed] extends [never] ? never : R extends keyof Governed ? Governed[R] extends readonly (infer Name)[] ? Name : never : never;
+/** The `governed: true` mark, added to a field: a key the field does not have. */
+type GovernedMark = {
+    readonly governed: true;
+};
+/** A Resource's fields with each governed one marked. */
+type GovernedFields<Fields, Governed> = [Governed] extends [never] ? Fields : {
+    readonly [F in keyof Fields]: F extends Governed ? Fields[F] & GovernedMark : Fields[F];
+};
+/** The root's `resources` block's Resources marked `managedElsewhere: true`. */
+type ManagedBlock<Block> = [Block] extends [never] ? never : {
+    [R in keyof Block]-?: NonNullable<Block[R]> extends {
+        readonly managedElsewhere: true;
+    } ? R : never;
+}[keyof Block];
+/** The write families a managed Resource never offers. */
+type WriteFamily = "create" | "update" | "delete" | "upsert";
+/** The two write capabilities a field may have. */
+type WriteStage = "create" | "update";
+/** A managed Resource's operations: its reads alone. */
+type ReadOperations<Operations> = {
+    readonly [F in keyof Operations as F extends WriteFamily ? never : F]: Operations[F];
+};
+/** Capabilities with each write member narrowed to `Kept` tokens, dropped when none is left. */
+type KeptWrites<Caps, Kept> = {
+    readonly [K in keyof Caps as K extends WriteStage ? [Extract<MemberTokens<NonNullable<Caps[K]>>, Kept>] extends [never] ? never : K : K]: K extends WriteStage ? WithTokens<NonNullable<Caps[K]>, Extract<MemberTokens<NonNullable<Caps[K]>>, Kept>> : Caps[K];
+};
+/** A field whose writes keep only `Kept` directives. */
+type WritesKept<Field, Kept> = {
+    readonly [P in keyof Field]: P extends "capabilities" ? KeptWrites<Field[P], Kept> : Field[P];
+};
+/** The directives a relation into a managed Resource keeps: the source row's own, where it holds the key. */
+type SourceRowDirectives<Field> = Field extends {
+    readonly referenceFields: readonly [unknown, ...unknown[]];
+} ? "$connect" | "$disconnect" : never;
+/** A Resource's fields, written as a managed Resource's or as relations into one. */
+type ManagedFields<Fields, Managed, IsManaged> = [Managed] extends [never] ? Fields : IsManaged extends true ? {
+    readonly [F in keyof Fields]: WritesKept<Fields[F], never>;
+} : {
+    readonly [F in keyof Fields]: Fields[F] extends {
+        readonly kind: "relation";
+        readonly target: Managed;
+    } ? WritesKept<Fields[F], SourceRowDirectives<Fields[F]>> : Fields[F];
+};
+/**
+ * The root's view with what is managed elsewhere applied: each managed
+ * Resource's writes withheld, and each relation's into one; under `Hidden` (the
+ * client's view) the managed Resources and every relation into them left out.
+ */
+type ManagedView<Resources, Managed, Hidden> = [Managed] extends [never] ? Resources : ManagedResources<Resources, Managed, Hidden>;
+/** {@link ManagedView}'s Resources when something is managed elsewhere. */
+type ManagedResources<in out Resources, in out Managed, in out Hidden> = {
+    readonly [R in Exclude<keyof Resources, Hidden>]: {
+        readonly [P in keyof Resources[R]]: P extends "fields" ? [Hidden] extends [never] ? ManagedFields<Resources[R][P], Managed, R extends Managed ? true : false> : {
+            readonly [F in keyof Resources[R][P] as Resources[R][P][F] extends {
+                readonly kind: "relation";
+                readonly target: Hidden;
+            } ? never : F]: Resources[R][P][F];
+        } : P extends "operations" ? R extends Managed ? ReadOperations<Resources[R][P]> : Resources[R][P] : Resources[R][P];
+    };
+};
 /**
  * One Resource before exposure: the model's own, with its fields layered and
- * its create requirements less what the layers' compute stages fill.
+ * marked where governed, and its create requirements less what the layers'
+ * compute stages fill.
  */
-type LayeredResource<in out Resource, in out ResourceConfig, in out OverlayConfig> = {
-    readonly [P in keyof Resource]: P extends "fields" ? LayeredFields<Resource[P], EntryOf<ResourceConfig, "fields">> : P extends "createRequirements" ? RequirementsLessComputed<Exclude<Resource[P], undefined>, ComputedOnCreateKey<EntryOf<ResourceConfig, "fields">> | ComputedOnCreateKey<EntryOf<OverlayConfig, "fields">>> : Resource[P];
+type LayeredResource<in out Resource, in out ResourceConfig, in out OverlayConfig, in out Governed = never> = {
+    readonly [P in keyof Resource]: P extends "fields" ? GovernedFields<LayeredFields<Resource[P], EntryOf<ResourceConfig, "fields">>, Governed> : P extends "createRequirements" ? RequirementsLessComputed<Exclude<Resource[P], undefined>, ComputedOnCreateKey<EntryOf<ResourceConfig, "fields">> | ComputedOnCreateKey<EntryOf<OverlayConfig, "fields">>> : Resource[P];
 };
 /** The fields of a `fields` block with a `compute.create` stage. */
 type ComputedOnCreateKey<FieldsBlock> = [FieldsBlock] extends [never] ? never : {
@@ -111,9 +200,9 @@ type ComputedOnCreateKey<FieldsBlock> = [FieldsBlock] extends [never] ? never :
  * none is satisfied and leaves `oneOf`. A member left empty is absent, as the
  * compiler leaves it (`projectCreateRequirements`).
  */
-type RequirementsLessComputed<Requirements, Computed> = [Computed] extends [
-    never
-] ? Requirements : {
+export type RequirementsLessComputed<Requirements, Computed> = [
+    Computed
+] extends [never] ? Requirements : {
     readonly [P in keyof Requirements as P extends "required" | "oneOf" ? LessComputed<P, Requirements[P], Computed> extends readonly [] ? never : P : P]: P extends "required" | "oneOf" ? LessComputed<P, Requirements[P], Computed> : Requirements[P];
 };
 /** One member of a statement less `Computed`: its names, or its groups. */
@@ -132,8 +221,8 @@ type GroupsLessComputed<Groups, Computed> = Groups extends readonly [
     ...GroupsLessComputed<Rest, Computed>
 ] : GroupsLessComputed<Rest, Computed> : readonly [];
 /** The Resources before exposure: the model, with the root's definitions applied. */
-type LayeredResources<Resources, Block, OverlayBlock> = {
-    readonly [R in keyof Resources]: LayeredResource<Resources[R], EntryOf<Block, R>, EntryOf<OverlayBlock, R>>;
+type LayeredResources<Resources, Block, OverlayBlock, Governed = never> = {
+    readonly [R in keyof Resources]: LayeredResource<Resources[R], EntryOf<Block, R>, EntryOf<OverlayBlock, R>, GovernedNames<Governed, R>>;
 };
 /**
  * The style a layer's `exposed` sets: `false` picks, `true` or absent omits, a
@@ -207,7 +296,7 @@ type OmittedMember<Member, Entry> = Entry extends readonly unknown[] ? WithToken
 /** One capability member under a Pick object entry: a token list keeps only those tokens. */
 type PickedMember<Member, Entry> = Entry extends readonly unknown[] ? WithTokens<Member, Extract<MemberTokens<Member>, Listed<Entry>>> : Member;
 /** The capability members no exemption names and a Pick still keeps. */
-type AdapterLimit = "nestedWriteFilter";
+type AdapterLimit = "nestedWriteFilter" | "filterModes" | "pathFilterModes";
 /** A field's capabilities under its exemption, a list of names or an object. */
 type ExemptedCapabilities<Caps, Entry, Style> = Style extends "omit" ? Entry extends readonly unknown[] ? {
     readonly [P in keyof Caps as P extends Listed<Entry> ? never : P]: Caps[P];
@@ -285,17 +374,32 @@ type ExposedResources<Resources, Style, Block> = Style extends "omit" ? [Block]
     readonly [R in Extract<keyof Resources, GrantedResourceKey<Block>>]: ExemptedResource<Resources[R], RawEntry<Block, R>, "pick">;
 } : Resources;
 /** The Resources of the root's final view: what every overlay starts from. */
-export type RootViewResources<M extends AvAdapterModel, Cfg> = ExposedResources<LayeredResources<M["resources"], ResourcesBlock<Cfg>, never>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>>;
+export type RootViewResources<M extends AvAdapterModel, Cfg> = ManagedView<ExposedResources<LayeredResources<M["resources"], ResourcesBlock<Cfg>, never>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>>, ManagedBlock<RootBlock<Cfg, "resources">>, never>;
 /** The Resources of an overlay's final view: the root's view, narrowed by it. */
-export type OverlayViewResources<M extends AvAdapterModel, Cfg, Layer extends "application" | "client"> = ExposedResources<ExposedResources<LayeredResources<M["resources"], ResourcesBlock<Cfg>, OverlayResourcesBlock<Cfg, Layer>>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>>, ExposureStyleOf<ExposedOf<OverlayOf<Cfg, Layer>>>, ExemptionsOf<OverlayOf<Cfg, Layer>>>;
+export type OverlayViewResources<M extends AvAdapterModel, Cfg, Layer extends "application" | "client"> = ExposedResources<ManagedView<ExposedResources<LayeredResources<M["resources"], ResourcesBlock<Cfg>, OverlayResourcesBlock<Cfg, Layer>>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>>, ManagedBlock<RootBlock<Cfg, "resources">>, Layer extends "client" ? ManagedBlock<RootBlock<Cfg, "resources">> : never>, ExposureStyleOf<ExposedOf<OverlayOf<Cfg, Layer>>>, ExemptionsOf<OverlayOf<Cfg, Layer>>>;
 /**
- * One derived Contract's type: the model, with the root's `resources` block
+ * One derived Contract's type: the model, with the root's `fields` entries
  * applied, then the root's exposure, then the overlay's over the root's view.
+ * `framework.application`, `client`, `appTx` and `clientTx` are typed over it,
+ * and a declaration file names it when it writes one of their nodes.
+ */
+export type AvContractView<M extends AvAdapterModel, RootFields, RootStyle, RootExemptions, OverlayStyle, OverlayExemptions, OverlayFields, Governed = never> = {
+    readonly scalars: M["scalars"];
+    readonly enums: M["enums"];
+    readonly resources: ExposedResources<ExposedResources<LayeredResources<M["resources"], RootFields, OverlayFields, Governed>, RootStyle, RootExemptions>, OverlayStyle, OverlayExemptions>;
+    readonly limits: AvContractLimits;
+    readonly transactions: M["transactions"];
+};
+/**
+ * {@link AvContractView} for a configuration that marks Resources managed
+ * elsewhere (`Managed`): their writes, and the writes of relations into them,
+ * withheld after the root's exposure; under `Hidden` (the client's view) they
+ * and every relation into them left out.
  */
-type DerivedContractView<M extends AvAdapterModel, FieldsBlock, RootStyle, RootExemptions, OverlayStyle, OverlayExemptions, OverlayBlock> = {
+export type AvManagedContractView<M extends AvAdapterModel, RootFields, RootStyle, RootExemptions, OverlayStyle, OverlayExemptions, OverlayFields, Governed, in out Managed, in out Hidden> = {
     readonly scalars: M["scalars"];
     readonly enums: M["enums"];
-    readonly resources: ExposedResources<ExposedResources<LayeredResources<M["resources"], FieldsBlock, OverlayBlock>, RootStyle, RootExemptions>, OverlayStyle, OverlayExemptions>;
+    readonly resources: ExposedResources<ManagedView<ExposedResources<LayeredResources<M["resources"], RootFields, OverlayFields, Governed>, RootStyle, RootExemptions>, Managed, Hidden>, OverlayStyle, OverlayExemptions>;
     readonly limits: AvContractLimits;
     readonly transactions: M["transactions"];
 };
@@ -303,7 +407,7 @@ type DerivedContractView<M extends AvAdapterModel, FieldsBlock, RootStyle, RootE
  * The Application Contract's type, derived from the adapter model and the
  * configuration.
  */
-export type AvContractApplicationView<M extends AvAdapterModel, Cfg = AvConfigAny> = [Cfg] extends [unknown] ? DerivedContractView<M, ResourcesBlock<Cfg>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>, ExposureStyleOf<ExposedOf<OverlayOf<Cfg, "application">>>, ExemptionsOf<OverlayOf<Cfg, "application">>, OverlayResourcesBlock<Cfg, "application">> : never;
+export type AvContractApplicationView<M extends AvAdapterModel, Cfg = AvConfigAny> = [Cfg] extends [unknown] ? [ManagedBlock<RootBlock<Cfg, "resources">>] extends [never] ? AvContractView<M, ViewBlock<ResourcesBlock<Cfg>>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>, ExposureStyleOf<ExposedOf<OverlayOf<Cfg, "application">>>, ExemptionsOf<OverlayOf<Cfg, "application">>, ViewBlock<OverlayResourcesBlock<Cfg, "application">>, GovernedBlock<Cfg>> : AvManagedContractView<M, ViewBlock<ResourcesBlock<Cfg>>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>, ExposureStyleOf<ExposedOf<OverlayOf<Cfg, "application">>>, ExemptionsOf<OverlayOf<Cfg, "application">>, ViewBlock<OverlayResourcesBlock<Cfg, "application">>, GovernedBlock<Cfg>, ManagedBlock<RootBlock<Cfg, "resources">>, never> : never;
 /**
  * The Client Contract's type, derived from the adapter model and the
  * configuration: what the client layer hides is absent. It types
@@ -311,5 +415,5 @@ export type AvContractApplicationView<M extends AvAdapterModel, Cfg = AvConfigAn
  */
 export type ClientContractView<M extends AvAdapterModel, Cfg = AvConfigAny> = [
     Cfg
-] extends [unknown] ? DerivedContractView<M, ResourcesBlock<Cfg>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>, ExposureStyleOf<ExposedOf<OverlayOf<Cfg, "client">>>, ExemptionsOf<OverlayOf<Cfg, "client">>, OverlayResourcesBlock<Cfg, "client">> : never;
+] extends [unknown] ? [ManagedBlock<RootBlock<Cfg, "resources">>] extends [never] ? AvContractView<M, ViewBlock<ResourcesBlock<Cfg>>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>, ExposureStyleOf<ExposedOf<OverlayOf<Cfg, "client">>>, ExemptionsOf<OverlayOf<Cfg, "client">>, ViewBlock<OverlayResourcesBlock<Cfg, "client">>, GovernedBlock<Cfg>> : AvManagedContractView<M, ViewBlock<ResourcesBlock<Cfg>>, ExposureStyleOf<ExposedOf<Cfg>>, ExemptionsOf<Cfg>, ExposureStyleOf<ExposedOf<OverlayOf<Cfg, "client">>>, ExemptionsOf<OverlayOf<Cfg, "client">>, ViewBlock<OverlayResourcesBlock<Cfg, "client">>, GovernedBlock<Cfg>, ManagedBlock<RootBlock<Cfg, "resources">>, ManagedBlock<RootBlock<Cfg, "resources">>> : never;
 export {};

package/dist/framework/framework-construction.error.d.ts

@@ -3,14 +3,24 @@ import type { AvContractCompilerDiagnostic } from "../compiler/contract-compiler
 import type { AvConfigDiagnostic } from "../config/config-diagnostic.js";
 /** The construction step that failed. */
 export type AvConstructionStage = "configuration" | "discovery" | "contract-compilation";
-/** One problem reported by {@link AvConstructionError}. */
-export type AvConstructionDiagnostic = AvConfigDiagnostic | AvAdapterDiscoveryDiagnostic | AvContractCompilerDiagnostic;
+/** One problem found while constructing, before its documentation link is added. */
+type ConstructionProblem = AvConfigDiagnostic | AvAdapterDiscoveryDiagnostic | AvContractCompilerDiagnostic;
+/**
+ * One problem reported by {@link AvConstructionError}: its `code`, `path` and
+ * `message`, and `docs`, the URL of the code's entry on the error-codes page
+ * (the same as `AvErrorCatalog[code].docs`).
+ */
+export type AvConstructionDiagnostic = ConstructionProblem & {
+    readonly docs: string;
+};
 /**
  * Thrown by {@link createFramework} when construction fails: `stage` says
- * where, and `diagnostics` lists every problem found there.
+ * where, and `diagnostics` lists every problem found there. The message names
+ * the first of them and how many more there are.
  */
 export declare class AvConstructionError extends Error {
     readonly stage: AvConstructionStage;
     readonly diagnostics: readonly AvConstructionDiagnostic[];
-    constructor(stage: AvConstructionStage, diagnostics: readonly AvConstructionDiagnostic[]);
+    constructor(stage: AvConstructionStage, diagnostics: readonly ConstructionProblem[]);
 }
+export {};

package/dist/framework/framework-construction.error.js

@@ -1,15 +1,31 @@
+import { brandCoreClass } from "../runtime/core-class.brand.js";
+import { errorDocsUrl } from "../runtime/error.catalog.js";
 const FRAMEWORK_CONSTRUCTION_MESSAGES = {
     configuration: "Aventara framework configuration validation failed",
     discovery: "Aventara adapter discovery validation failed",
     "contract-compilation": "Aventara contract compilation failed",
 };
+function constructionMessage(stage, diagnostics) {
+    const base = FRAMEWORK_CONSTRUCTION_MESSAGES[stage];
+    const [first] = diagnostics;
+    if (first === undefined) {
+        return base;
+    }
+    const where = first.path === "" ? "" : ` at ${first.path}`;
+    const more = diagnostics.length > 1 ? ` (+${diagnostics.length - 1} more)` : "";
+    return `${base}: ${first.code}${where}: ${first.message}${more}`;
+}
 export class AvConstructionError extends Error {
     stage;
     diagnostics;
     constructor(stage, diagnostics) {
-        super(FRAMEWORK_CONSTRUCTION_MESSAGES[stage]);
+        super(constructionMessage(stage, diagnostics));
         this.name = "AvConstructionError";
         this.stage = stage;
-        this.diagnostics = [...diagnostics];
+        this.diagnostics = diagnostics.map((diagnostic) => ({
+            ...diagnostic,
+            docs: errorDocsUrl(diagnostic.code),
+        }));
     }
 }
+brandCoreClass(AvConstructionError, "AvConstructionError");

package/dist/framework/framework.d.ts

@@ -2,12 +2,12 @@ import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { AvConfigAny } from "../config/any-framework-config.js";
 import type { AvMcpEndpoint } from "../config/config.resolver.js";
-import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
+import type { AvOperationRequest } from "../runtime/operation-request.js";
 import type { AvOperationResponse } from "../runtime/operation-response.js";
 import type { AvTransactionRunner } from "../transactions/deferred-operation.js";
-import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvTransactionRequest } from "../transactions/transaction-request.js";
 import type { AvTransactionResponse } from "../transactions/transaction-response.js";
-import type { ApplicationOperations, ApplicationTransactionBuilders, ClientOperations, ClientTransactionBuilders } from "./operation-facade.js";
+import type { ApplicationOperations, ApplicationTransactionBuilders, ClientOperations, ClientTransactionBuilders, ServerClientOperations, ServerClientTransactionBuilders } from "./operation-facade.js";
 /**
  * One Aventara instance, as returned by {@link createFramework}: its compiled
  * Contracts, typed in-process operations, transaction builders and the
@@ -50,6 +50,19 @@ export type AvFramework<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfi
      * failure thrown.
      */
     readonly client: ClientOperations<M, Cfg>;
+    /**
+     * The client layer for server code, taking application values:
+     * `framework.serverClient.<resource>.<family>.<variant>(args, options?)`.
+     *
+     * Typed and run exactly as {@link client} (the Client Contract's view, the
+     * client pipelines, validation, exposure and policy), but its arguments are
+     * the application forms: a `datetime` is a `Date`, a `bigint` a `bigint`, a
+     * `decimal` an `AvDecimal`, `bytes` a `Uint8Array`. Each call copies its
+     * arguments, encodes them into the wire forms `client` reads, and hands the
+     * same client-origin request to {@link execute}. Results are the same as
+     * `client`'s; the optional second argument is {@link AvExecutionOptions}.
+     */
+    readonly serverClient: ServerClientOperations<M, Cfg>;
     /**
      * Transaction builders under application rules:
      * `framework.appTx.<resource>.<family>.<variant>(args)` defers one operation
@@ -72,7 +85,15 @@ export type AvFramework<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfi
      * share one (`A2004`/`V1020` at the first step of the other origin).
      */
     readonly clientTx: ClientTransactionBuilders<M, Cfg>;
-    execute(request: FrameworkOperationRequest): Promise<AvOperationResponse>;
+    /**
+     * The {@link clientTx} builders taking application values, as
+     * {@link serverClient} takes them: each handle's arguments are copied and
+     * encoded into the wire forms when it is built. Its handles are client-origin,
+     * so one {@link transaction} may hold them beside `clientTx` handles, never
+     * beside `appTx` ones.
+     */
+    readonly serverClientTx: ServerClientTransactionBuilders<M, Cfg>;
+    execute(request: AvOperationRequest): Promise<AvOperationResponse>;
     /**
      * Validates a whole transaction plan, then runs its operations one after
      * another inside one Adapter transaction. Answers `A1009` with each
@@ -83,7 +104,7 @@ export type AvFramework<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfi
      * Guards, pipes, hooks and interceptors run while the transaction is open, so
      * they should not perform network I/O or other slow work.
      */
-    executeTransaction(request: FrameworkTransactionRequest): Promise<AvTransactionResponse>;
+    executeTransaction(request: AvTransactionRequest): Promise<AvTransactionResponse>;
     /**
      * Runs handles from `appTx`/`clientTx` as one transaction:
      * `framework.transaction([h1, h2, …], options?)`. Resolves each handle's

package/dist/framework/framework.factory.d.ts

@@ -10,4 +10,4 @@ import type { AvFramework } from "./framework.js";
  *
  * @throws {@link AvConstructionError} when any of those steps fails.
  */
-export declare function createFramework<M extends AvAdapterModel, const Cfg = AvConfigAny>(config: Cfg & AvConfig<M, Cfg> & AvConfigExact<M, Cfg>): Promise<AvFramework<M, ErasedConfig<Cfg>>>;
+export declare function createFramework<M extends AvAdapterModel, const Cfg = AvConfigAny>(config: Cfg & AvConfigExact<M, Cfg> & AvConfig<M, Cfg>): Promise<AvFramework<M, ErasedConfig<Cfg>>>;