@aventara/core 1.0.0-rc.8 → 1.0.0-rc.9

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @aventara/core
 
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- 205a379: `createFramework` takes `access`, an access provider: the policy engine and the request state from one object.
+  `AvAccessProvider` is the new main-entry type it is written against, with two members:
+
+  - `policy`: the engine every client and agent request is checked against, as `policy.engine` takes it.
+  - `state({ headers, request })`: seeds each request's `ctx.$state`. Its `me` is the principal the engine is asked
+    about, `null` for an anonymous caller.
+
+  Aventara Access provides one, and a hand-written provider works the same way (a till's PIN sign-in, say: see the
+  README). The host calls `state` once per request; server code that calls the Framework directly passes the state
+  itself. A governed field of the provider's engine is left out of the default projection's type, as with `policy`.
+  `access` together with `policy` is refused at startup (`CONFIG_INVALID_VALUE` at `policy`) and is a type error at
+  `policy`. A provider whose `policy` is no engine or whose `state` is no function is refused at startup, member by
+  member, and the engine's `governed`, `paths` and `afterChecks` are checked against the Core Contract under
+  `access.policy`. A prebuilt Contracts file counts the provider by its engine's governed set alone.
+
+- a0bb05e: A Framework's `diagnostics` sink receives every report when the process holds more than one copy of `@aventara/core`
+  (Next.js giving each layer its own copy, a duplicate install, a monorepo). A protocol failure such as a result with no
+  wire form (`500 A3003`), or an MCP endpoint failure, raised through another copy than the one that built the Framework
+  now reaches the sink instead of being silently dropped. Copies of one major version share the sinks; nothing in the
+  public API or its types changed.
+- 86ab319: Values and errors from `@aventara/core` are recognized across duplicate copies of the package in one process. A
+  bundler that gives each layer its own copy (Next.js instrumentation, route handlers and pages), a duplicate install, a
+  monorepo, Vite SSR, per-function bundles and test runners' module isolation all load core more than once.
+
+  - A decimal made by one copy is an `AvDecimal` to every other: `value instanceof AvDecimal` is `true`, the protocol
+    encodes it (a `find.many` selecting a decimal no longer answers `500 A3003` "Result serialization failed"), and a
+    Framework accepts it in arguments, `$sql` values and Adapter results.
+  - `AvError` and its subclasses (`AvValidationError`, `AvNotFoundError`, `AvConflictError`, `AvAuthError`,
+    `AvInternalError`, `AvProtocolError`, `AvContractMismatchError`), `AvConstructionError`,
+    `AvTransactionIntegrityError` and `AvTransactionSlotPathError` pass `instanceof` across copies, with the same
+    subclass rules: every one is an `AvError`, and each is only its own subclass. An `AvError` a pipeline throws with
+    another copy's class is answered as the outcome it names. A subclass you declare yourself is checked as before.
+  - Copies recognize each other within one major version only. Nothing in the public API or its types changed.
+
+- fdf52e6: `framework.serverClient` and `framework.serverClientTx`: the client layer for server code, called with application
+  values, such as a Next.js Server Component's.
+
+  - `framework.serverClient.<Resource>.<family>.<variant>(args, options?)` is typed from the Client Contract's view, as
+    `framework.client` is: what the client layer hides is absent. Its arguments are the application forms (`Date`,
+    `bigint`, `AvDecimal`, `Uint8Array`), the ones `framework.application` takes, and their wire strings are type errors.
+    Its results are `framework.client`'s. At runtime a value already in its wire form is accepted too, as
+    `framework.client` reads it.
+  - Each call copies its arguments, encodes the copy into the wire forms against the Client Contract, and runs the request
+    `framework.client` would run for those wire forms: the same client pipelines, validation, exposure and policy, the
+    same answers and the same `AvError` classes. `framework.client` itself is unchanged and keeps the wire forms.
+  - `framework.serverClientTx` builds client-origin transaction handles from application values. One
+    `framework.transaction([...])` may hold them beside `clientTx` handles, never beside `appTx` ones.
+  - New main-entry type names: `AvServerClientFacade`, `AvServerClientResourceFacade`, `AvServerClientFamilyFacade`,
+    `AvServerClientProjectingCall`, `AvServerClientPlainCall`, `AvServerClientTxFacade`,
+    `AvServerClientTxResourceFacade`, `AvServerClientTxFamilyFacade`, `AvServerClientTxProjectingCall`,
+    `AvServerClientTxPlainCall`.
+
 ## 1.0.0-rc.8
 
 1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.

package/ERRORS.md

@@ -1,6 +1,6 @@
 # Aventara error codes
 
-Every code `@aventara/core` 1.0.0-rc.8 answers, reports in a validation issue, or refuses to start with. Generated from `AvErrorCatalog` (exported by `@aventara/core`); do not edit.
+Every code `@aventara/core` 1.0.0-rc.9 answers, reports in a validation issue, or refuses to start with. Generated from `AvErrorCatalog` (exported by `@aventara/core`); do not edit.
 
 Branch on the code, never on the message. In code, `AvErrorCatalog[code]` gives the same entry: `{ code, kind, message, cause, fix, docs }`.
 
@@ -134,7 +134,7 @@ Each entry of `cause.issues[]` under `A2001`, `A2002`, `A2004`, `A2007` or `A200
 | [`COMPILER_INVALID_LIFECYCLE`](https://aventara-framework.vercel.app/docs/error-codes#compiler_invalid_lifecycle) | Invalid field lifecycle. | An added field declares a lifecycle other than VIRTUAL, a VIRTUAL field claims a database-generated lifecycle or a provider-side capability, or a definition redefines a discovered field's lifecycle. | Give an added field lifecycle: ["VIRTUAL"] and only the capabilities it can serve; computed lifecycles come from compute stages. |
 | [`COMPILER_MISSING_READ_COMPUTE`](https://aventara-framework.vercel.app/docs/error-codes#compiler_missing_read_compute) | A selectable virtual field has no compute.read. | A VIRTUAL field that can be selected has no pipelines.compute.read stage. | Add a compute.read stage, or make the field write-only with capabilities.select: false. |
 | [`COMPILER_INVALID_COMPUTE_DEPENDENCY`](https://aventara-framework.vercel.app/docs/error-codes#compiler_invalid_compute_dependency) | Invalid compute.read dependency. | A dependsOn entry that is not a stored scalar field of the same Resource. | List only stored scalar fields of the Resource in dependsOn. |
-| [`COMPILER_RESERVED_RESOURCE_NAME`](https://aventara-framework.vercel.app/docs/error-codes#compiler_reserved_resource_name) | Reserved Resource name. | A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref). | Rename the model; the table it maps to can keep its name. |
+| [`COMPILER_RESERVED_RESOURCE_NAME`](https://aventara-framework.vercel.app/docs/error-codes#compiler_reserved_resource_name) | Reserved Resource name. | A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref), or, on a host that adds members beside the Resources, is one of those members' names (on Next.js: tx and transaction on avClient, appTx and transaction on avApp). | Rename the model; the table it maps to can keep its name. A host member's name is also left free when the layer it belongs to hides the Resource. |
 | [`COMPILER_MISSING_IDENTIFIER`](https://aventara-framework.vercel.app/docs/error-codes#compiler_missing_identifier) | A unique operation has no identifier. | A layer exposes a unique variant (find.unique, update.unique, delete.unique, upsert.unique) and no complete identifier of the Resource: a Pick that did not pick one, or an Omit that hid every one. | Expose an identifier field (id, or every field of one unique), or exempt the unique variants. |
 | [`COMPILER_HIDDEN_REQUIRED_FIELD`](https://aventara-framework.vercel.app/docs/error-codes#compiler_hidden_required_field) | A layer that creates a Resource hides a required field. | A layer still creates the Resource (a create or upsert variant, or a nested create) while a required field, or a required relation's reference field, is hidden or has its create capability exempted, and no compute.create fills it. | Expose the field, give it a compute.create stage, or exempt the layer's create operations. |
 | [`COMPILER_INVALID_VALIDATOR`](https://aventara-framework.vercel.app/docs/error-codes#compiler_invalid_validator) | A field validator cannot apply. | A validator that is not built with AvZ, does not fit the field's type (AvZ.maxLength on an int, AvZ.maxItems on a field that is not a list), or sits on a relation or Json field. | Use an AvZ check that fits the field's type; a Json field's checks go in its json shape. |

package/README.md

@@ -118,6 +118,27 @@ try {
 generated client throws the same classes by the same table. `framework.execute` and `framework.executeTransaction`, the
 entries a transport calls, still answer the envelope.
 
+## The client layer, called with your own values
+
+`framework.client` reads its arguments in the wire forms a decoded request body carries: a `datetime` is its ISO string,
+a `bigint` its base-10 string. That suits a test that should behave like a remote caller. Server code that acts for a
+remote caller, such as a Server Component or a Server Action, holds `Date`s and `bigint`s instead. It calls
+`framework.serverClient`:
+
+```ts
+const recent = await framework.serverClient.Post.find.many({
+  where: { createdAt: { gt: new Date(Date.now() - 86_400_000) } },
+  select: ["id", "title"],
+});
+```
+
+`serverClient` has the client layer's types and rules: what the client layer hides is absent, and the client
+pipelines, validation, exposure and policy run. Its arguments are the application forms (`Date`, `bigint`,
+`AvDecimal`, `Uint8Array`), the same ones `framework.application` takes, and its results are `framework.client`'s.
+Each call copies its arguments, encodes them into the wire forms and runs the request `framework.client` would run.
+`framework.serverClientTx` builds client-layer transaction handles the same way; one `framework.transaction([...])`
+may hold them beside `clientTx` handles, never beside `appTx` ones.
+
 ## Every code, explained
 
 `AvErrorCatalog` holds every code this package answers, reports in a validation issue, or refuses to start with: its
@@ -199,15 +220,15 @@ findMany(): import("@aventara/core").AvApplicationProjectingCall<
   "Post", { readonly family: "find"; readonly variant: "many" }>;
 ```
 
-The names, one set per surface (`application`, `client`, `appTx`, `clientTx`):
+The names, one set per surface (`application`, `client`, `serverClient`, `appTx`, `clientTx`, `serverClientTx`):
 
 | Node | `framework.application` | the others |
 | --- | --- | --- |
-| the whole surface | `AvApplicationFacade` | `AvClientFacade`, `AvAppTxFacade`, `AvClientTxFacade` |
+| the whole surface | `AvApplicationFacade` | `AvClientFacade`, `AvServerClientFacade`, `AvAppTxFacade`, `AvClientTxFacade`, `AvServerClientTxFacade` |
 | one Resource | `AvApplicationResourceFacade` | `AvClientResourceFacade`, … |
 | one family | `AvApplicationFamilyFacade` | `AvClientFamilyFacade`, … |
-| a variant that takes a `select` or `include` | `AvApplicationProjectingCall` | `AvClientProjectingCall`, `AvAppTxProjectingCall`, `AvClientTxProjectingCall` |
-| a variant that does not (the `count` variants: `find.count`, `update.count`, …) | `AvApplicationPlainCall` | `AvClientPlainCall`, `AvAppTxPlainCall`, `AvClientTxPlainCall` |
+| a variant that takes a `select` or `include` | `AvApplicationProjectingCall` | `AvClientProjectingCall`, `AvServerClientProjectingCall`, `AvAppTxProjectingCall`, `AvClientTxProjectingCall`, `AvServerClientTxProjectingCall` |
+| a variant that does not (the `count` variants: `find.count`, `update.count`, …) | `AvApplicationPlainCall` | `AvClientPlainCall`, `AvServerClientPlainCall`, `AvAppTxPlainCall`, `AvClientTxPlainCall`, `AvServerClientTxPlainCall` |
 
 Each takes the view, `AvContractView`, as its first argument. The view's arguments are your model by its name, the root's
 and the overlay's exposure as written, and the `fields` entries your configuration's `resources` blocks hold. A
@@ -230,8 +251,8 @@ never with the model the inline stages were typed from.
 
 ## Server-side calls copy their input
 
-`framework.application`, `framework.client`, `framework.execute`, `framework.executeTransaction`, and the `appTx` /
-`clientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
+`framework.application`, `framework.client`, `framework.serverClient`, `framework.execute`,
+`framework.executeTransaction`, and the `appTx` / `clientTx` / `serverClientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
 Validation, your guards and pipes, computed values and the adapter all see only the copy, and your stages see it
 frozen: only a pipe changes the arguments, by returning new ones, so what the validators checked is what the adapter
 writes. In practice:
@@ -374,6 +395,54 @@ caller may change or delete, as `update.many` does. After the call, every row th
 (the after check, the move-out re-read), and every row they created is read back as stored and asked `can`; one refusal
 rolls the whole write back. Where `transactionsStyle` is `"none"`, a nested write under a policy is refused.
 
+## An access provider
+
+`access` takes the policy engine and the request state from one object, an `AvAccessProvider`. Aventara Access
+provides one, and you can write your own. It has two members:
+
+- `policy`: the engine, as `policy.engine` takes it.
+- `state({ headers, request })`: seeds each request's `ctx.$state`. Its `me` is the principal the engine is asked
+  about (`null` for an anonymous caller).
+
+The host calls `state` once per request: `@aventara/nest` with the platform request's headers and the request itself,
+`@aventara/next` with the request's headers (and the route's `Request` on a route call). With `access`, leave out
+`policy` and the host's own `state` option; either one beside it is refused at startup, and as a type error where the
+configuration's type shows both. Server code that calls the Framework directly passes the state itself,
+`{ state: await access.state({ headers }) }`.
+
+A point-of-sale till with its own PIN sign-in, written by hand:
+
+```ts
+import type { AvAccessProvider } from "@aventara/core";
+
+type Cashier = { id: string; role: "cashier" | "manager" };
+
+declare module "@aventara/core" {
+  interface AvState {
+    me?: Cashier | null;
+  }
+}
+
+export const tillAccess = {
+  // The till sends the PIN the cashier typed as `x-pos-pin`.
+  state: async ({ headers }) => ({ me: await cashierByPin(headers.get("x-pos-pin")) }),
+  policy: {
+    can: ({ principal, resource, action }) => {
+      const me = principal as Cashier | null;
+      if (me === null) return false; // no PIN, no till
+      if (resource === "Refund" && action !== "read") return me.role === "manager";
+      return true;
+    },
+    scopeOf: () => true,
+    fieldsOf: () => ({ always: "all", perRow: {} }),
+  },
+} satisfies AvAccessProvider;
+
+const framework = await createFramework({ api: "/api", adapter, access: tillAccess });
+```
+
+Every stage reads the cashier as `ctx.$state.me`, typed by the `AvState` declaration above.
+
 ## License
 
 PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you

package/dist/compiler/contract-compiler-diagnostic.guidance.js

@@ -66,8 +66,8 @@ export const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE = {
     },
     COMPILER_RESERVED_RESOURCE_NAME: {
         message: "Reserved Resource name.",
-        cause: "A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref).",
-        fix: "Rename the model; the table it maps to can keep its name.",
+        cause: "A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref), or, on a host that adds members beside the Resources, is one of those members' names (on Next.js: tx and transaction on avClient, appTx and transaction on avApp).",
+        fix: "Rename the model; the table it maps to can keep its name. A host member's name is also left free when the layer it belongs to hides the Resource.",
     },
     COMPILER_MISSING_IDENTIFIER: {
         message: "A unique operation has no identifier.",

package/dist/config/config.resolver.d.ts

@@ -11,6 +11,8 @@ import type { AvConfigFieldDefinition } from "./framework-field-definition.js";
 import { type ResolvedPipelineTree } from "./pipeline-tree.resolver.js";
 /** The root's `policy`, its engine's passive lists read once. */
 export type ResolvedPolicyConfig = {
+    /** Where the engine was configured, for the startup diagnostics' paths. */
+    readonly at: "policy.engine" | "access.policy";
     readonly engine: AvPolicyEngine;
     readonly principal: NonNullable<AvConfig["policy"]>["principal"];
     /** The governed fields and relations, by Resource. */

package/dist/config/config.resolver.js

@@ -158,11 +158,16 @@ function frozenPathLists(value) {
         Object.freeze(paths.map((path) => Object.freeze([...path]))),
     ])));
 }
-function resolvePolicy(policy) {
+const accessPrincipal = ({ $state, }) => $state.me ?? null;
+function resolvePolicy(configured, access) {
+    const policy = access === undefined
+        ? configured
+        : { engine: access.policy, principal: accessPrincipal };
     if (policy === undefined) {
         return undefined;
     }
     return Object.freeze({
+        at: access === undefined ? "policy.engine" : "access.policy",
         engine: policy.engine,
         principal: policy.principal,
         governed: frozenLists(policy.engine.governed),
@@ -188,7 +193,7 @@ export function resolveFrameworkConfig(config) {
         adapter: config.adapter,
         diagnostics: config.diagnostics,
         misuse: config.misuse,
-        policy: resolvePolicy(config.policy),
+        policy: resolvePolicy(config.policy, config.access),
         definitions: definitionsOf(root.resources),
         trees: {
             root: root.resources,

package/dist/config/config.validator.js

@@ -7,6 +7,7 @@ const ROOT_ONLY_PROPERTIES = new Set([
     "adapter",
     "prebuilt",
     "policy",
+    "access",
     "diagnostics",
     "misuse",
     "application",
@@ -628,6 +629,12 @@ export function validateFrameworkConfig(value) {
     if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
         validatePolicy(value.policy, diagnostics);
     }
+    if (Object.hasOwn(value, "access") && value.access !== undefined) {
+        validateAccess(value.access, diagnostics);
+        if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
+            diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", "policy", "policy cannot be configured with access: access.policy is the policy engine, and ctx.$state.me the principal; remove policy"));
+        }
+    }
     if (Object.hasOwn(value, "diagnostics") &&
         value.diagnostics !== undefined &&
         typeof value.diagnostics !== "function") {
@@ -670,26 +677,43 @@ function validatePolicy(value, diagnostics) {
         diagnostics.push(diagnostic("CONFIG_REQUIRED", "policy.engine", "policy.engine is required"));
         return;
     }
-    const engine = value.engine;
+    validatePolicyEngine(value.engine, "policy.engine", diagnostics);
+}
+function validateAccess(value, diagnostics) {
+    if (value === null || typeof value !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "access", "access must be an access provider, { policy, state }"));
+        return;
+    }
+    const provider = value;
+    if (typeof provider.state !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "access.state", "access.state must be a function"));
+    }
+    if (provider.policy === undefined) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "access.policy", "access.policy is required"));
+        return;
+    }
+    validatePolicyEngine(provider.policy, "access.policy", diagnostics);
+}
+function validatePolicyEngine(engine, at, diagnostics) {
     if (engine === null || typeof engine !== "object") {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy.engine", "policy.engine must be an object"));
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", at, `${at} must be an object`));
         return;
     }
     const members = engine;
     for (const question of ["can", "scopeOf", "fieldsOf"]) {
         if (typeof members[question] !== "function") {
-            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `policy.engine.${question}`, `policy.engine.${question} must be a function`));
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${question}`, `${at}.${question} must be a function`));
         }
     }
-    validatePolicyLists(members.governed, "governed", { all: "string lists", one: "a list of strings" }, isStringList, diagnostics);
-    validatePolicyLists(members.paths, "paths", {
+    validatePolicyLists(members.governed, at, "governed", { all: "string lists", one: "a list of strings" }, isStringList, diagnostics);
+    validatePolicyLists(members.paths, at, "paths", {
         all: "path lists",
         one: "a list of paths, each a list of strings",
     }, (paths) => Array.isArray(paths) && paths.every(isStringList), diagnostics);
-    validatePolicyLists(members.afterChecks, "afterChecks", { all: "action lists", one: "a list of actions" }, isStringList, diagnostics);
-    validateAfterCheckActions(members.afterChecks, diagnostics);
+    validatePolicyLists(members.afterChecks, at, "afterChecks", { all: "action lists", one: "a list of actions" }, isStringList, diagnostics);
+    validateAfterCheckActions(members.afterChecks, at, diagnostics);
 }
-function validateAfterCheckActions(lists, diagnostics) {
+function validateAfterCheckActions(lists, at, diagnostics) {
     if (!isPlainRecord(lists)) {
         return;
     }
@@ -699,7 +723,7 @@ function validateAfterCheckActions(lists, diagnostics) {
         }
         for (const action of actions) {
             if (action !== "update") {
-                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `policy.engine.afterChecks.${resource}`, `policy.engine.afterChecks.${resource}: "${action}" is no action an after check runs on; only "update" is`));
+                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `${at}.afterChecks.${resource}`, `${at}.afterChecks.${resource}: "${action}" is no action an after check runs on; only "update" is`));
             }
         }
     }
@@ -707,17 +731,17 @@ function validateAfterCheckActions(lists, diagnostics) {
 function isStringList(value) {
     return (Array.isArray(value) && value.every((name) => typeof name === "string"));
 }
-function validatePolicyLists(lists, list, entry, isEntry, diagnostics) {
+function validatePolicyLists(lists, at, list, entry, isEntry, diagnostics) {
     if (lists === undefined) {
         return;
     }
     if (!isPlainRecord(lists)) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `policy.engine.${list}`, `policy.engine.${list} must be an object of ${entry.all} when provided`));
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${list}`, `${at}.${list} must be an object of ${entry.all} when provided`));
         return;
     }
     for (const [key, value] of Object.entries(lists)) {
         if (!isEntry(value)) {
-            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `policy.engine.${list}.${key}`, `policy.engine.${list}.${key} must be ${entry.one}`));
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${list}.${key}`, `${at}.${list}.${key} must be ${entry.one}`));
         }
     }
 }

package/dist/config/exact-framework-config.d.ts

@@ -243,6 +243,7 @@ type RootSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
         readonly engine: Leaf;
         readonly principal: Leaf;
     };
+    readonly access: Leaf;
     readonly diagnostics: Leaf;
     readonly misuse: Leaf;
     readonly resources: RootResourcesSchema<M>;
@@ -264,7 +265,16 @@ type Exact<S, V> = [S] extends [Leaf] ? unknown : V extends readonly unknown[] ?
  * rc.0 key, a `definition` in an overlay, a stage a relation field does not take,
  * or a name the model and the root do not have.
  */
-export type AvConfigExact<M extends AvAdapterModel, Cfg> = Exact<RootSchema<M, Cfg>, Cfg> & ExposedWithExemptions<Cfg, "application"> & ExposedWithExemptions<Cfg, "client"> & ExposedWithExemptions<Cfg, "agent"> & ForceNeedsTransactions<M, Cfg>;
+export type AvConfigExact<M extends AvAdapterModel, Cfg> = Exact<RootSchema<M, Cfg>, Cfg> & ExposedWithExemptions<Cfg, "application"> & ExposedWithExemptions<Cfg, "client"> & ExposedWithExemptions<Cfg, "agent"> & ForceNeedsTransactions<M, Cfg> & AccessWithoutPolicy<Cfg>;
+/** `policy` refused when the configuration also states `access`. */
+type AccessWithoutPolicy<Cfg> = Cfg extends {
+    readonly access: object;
+    readonly policy: object;
+} ? {
+    readonly policy: readonly [
+        "Error: `access` brings the policy engine; remove `policy`"
+    ];
+} : unknown;
 /** A layer's own literal `transactionsStyle`, `undefined` when it states none. */
 type StyleOf<Layer> = Layer extends {
     readonly transactionsStyle: infer Style;

package/dist/config/framework-config.d.ts

@@ -2,6 +2,7 @@ import type { AvAdapter } from "../adapters/adapter.interface.js";
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvContractLimits } from "../contracts/contract-limits.js";
 import type { AvTransactionCapability } from "../contracts/transaction-capability.js";
+import type { AvAccessProvider } from "../policy/access-provider.interface.js";
 import type { AvPolicyEngine } from "../policy/policy-engine.js";
 import type { AvPrebuiltContracts } from "../prebuilt/prebuilt-contracts.js";
 import type { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
@@ -100,6 +101,14 @@ export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAn
             readonly $origin: AvRequestOrigin;
         }) => unknown;
     };
+    /**
+     * The access provider (Aventara Access, or one written by hand): its
+     * `policy` engine checks every client and agent request, with
+     * `ctx.$state.me` as the principal, and the host seeds each request's
+     * `ctx.$state` with its `state`. Not together with `policy`, nor with a
+     * host's own `state` option.
+     */
+    readonly access?: AvAccessProvider;
     readonly diagnostics?: AvDiagnosticsSink;
     /** Told about every caller value refused as unreadable or not plain data. */
     readonly misuse?: AvMisuseSink;

package/dist/contracts/contract-canonicalizer.js

@@ -1,3 +1,4 @@
+import { brandCoreClass } from "../runtime/core-class.brand.js";
 import { FILTER_MODES, PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
 import { LIFECYCLE_TRAITS } from "./lifecycle-trait.js";
 import { projectionScopeOf, writeScopeOf } from "./resource-operations.js";
@@ -5,6 +6,7 @@ const PAGINATION_ORDER = ["limit", "offset", "cursor"];
 const REDUCER_ORDER = ["$count"];
 export class AvCanonicalJsonError extends TypeError {
 }
+brandCoreClass(AvCanonicalJsonError, "AvCanonicalJsonError");
 function compareCodeUnits(left, right) {
     if (left === right) {
         return 0;

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

@@ -104,8 +104,16 @@ type PolicyEngineOf<Cfg> = (NonNullable<(Cfg & {
 })["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>> & {
+type GovernedBlock<Cfg> = LiteralRecord<(NonNullable<PolicyEngineOf<Cfg>> & AccessEngineOf<Cfg> & {
     readonly governed?: unknown;
 })["governed"]>;
 /** The names `Governed` lists for Resource `R`, or `never`. */

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

@@ -1,3 +1,4 @@
+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",
@@ -27,3 +28,4 @@ export class AvConstructionError extends Error {
         }));
     }
 }
+brandCoreClass(AvConstructionError, "AvConstructionError");

package/dist/framework/framework.d.ts

@@ -7,7 +7,7 @@ import type { AvOperationResponse } from "../runtime/operation-response.js";
 import type { AvTransactionRunner } from "../transactions/deferred-operation.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,6 +85,14 @@ 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>;
+    /**
+     * 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

package/dist/framework/framework.factory.js

@@ -4,10 +4,11 @@ import { resolveFrameworkConfig, } from "../config/config.resolver.js";
 import { validateFrameworkConfig } from "../config/config.validator.js";
 import { validateForcedOperations } from "../config/forced-operation.validator.js";
 import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
+import { recordAccessProvider } from "../policy/access-provider.registry.js";
 import { callerOf } from "../policy/policy-request.js";
 import { policyStartupDiagnostics } from "../policy/policy-startup.validator.js";
 import { loadPrebuiltContracts, warnStalePrebuilt, } from "../prebuilt/prebuilt-contracts.loader.js";
-import { copyEnvelopeAtDoor, refuseCallerData, } from "../runtime/caller-data.door.js";
+import { copyAtDoor, copyEnvelopeAtDoor, refuseCallerData, } from "../runtime/caller-data.door.js";
 import { createDiagnosticsReporter, createTransactionDiagnosticsChannel, recordDiagnosticsSink, } from "../runtime/diagnostics-reporter.js";
 import { createMisuseReporter, } from "../runtime/misuse-reporter.js";
 import { internalFailure, operationFailure, } from "../runtime/operation-response.js";
@@ -16,6 +17,7 @@ import { recordOwnedExecution } from "../runtime/owned-execution.registry.js";
 import { validateOperationEnvelope, validateTransactionEnvelope, } from "../runtime/request-envelope.validator.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 { createTransactionPlanAssembler } from "../transactions/transaction-plan-assembler.js";
 import { createTransactionRuntime } from "../transactions/transaction-runtime.js";
 import { AvConstructionError } from "./framework-construction.error.js";
@@ -68,11 +70,21 @@ export async function createFramework(config) {
     const executeTransaction = createTransactionRuntime(runtimeDependencies, pipelineDependencies);
     const misuse = createMisuseReporter(resolvedConfig.misuse);
     const executeOperation = (request, caller) => executeTotally(execute, request, resolvedConfig.diagnostics, "caller", caller);
+    const executeApplicationValues = (request, caller) => executeTotally(encodingApplicationValues(execute, compilation.contracts.client), request, resolvedConfig.diagnostics, "caller", caller);
     const protocol = {
         version: AVENTARA_PROTOCOL_VERSION,
         hash: compilation.contracts.client.protocol.hash,
     };
     const assembler = createTransactionPlanAssembler(compilation.contracts, protocol, misuse);
+    const clientRequest = (resource, identity, args, requestId, state) => ({
+        ...identity,
+        origin: "client",
+        protocol,
+        requestId,
+        ...(state === undefined ? {} : { state }),
+        resource,
+        arguments: args,
+    });
     const framework = {
         api: resolvedConfig.api,
         mcp: resolvedConfig.mcp,
@@ -85,25 +97,20 @@ export async function createFramework(config) {
             resource,
             arguments: args,
         }), executeOperation),
-        client: createOperationFacade(model, (resource, identity, args, requestId, state) => ({
-            ...identity,
-            origin: "client",
-            protocol,
-            requestId,
-            ...(state === undefined ? {} : { state }),
-            resource,
-            arguments: args,
-        }), executeOperation),
+        client: createOperationFacade(model, clientRequest, executeOperation),
+        serverClient: createOperationFacade(model, clientRequest, executeApplicationValues),
         appTx: Object.freeze({
             ...createOperationTree(model, (resource, identity) => (args) => assembler.defer("application", resource, identity, args === undefined ? {} : args)),
             [APPLICATION_SQL_BUILDER]: (strings, ...values) => assembler.deferSql(strings, values),
         }),
         clientTx: createOperationTree(model, (resource, identity) => (args) => assembler.defer("client", resource, identity, args === undefined ? {} : args)),
+        serverClientTx: createOperationTree(model, (resource, identity) => (args) => assembler.defer("client", resource, identity, args === undefined ? {} : args, "application")),
         execute: (request) => executeRequestTotally(execute, request, resolvedConfig.diagnostics, misuse),
         executeTransaction: (request) => executeTransactionRequestTotally(executeTransaction, request, resolvedConfig.diagnostics, misuse),
         transaction: (async (operations, options) => settleOperation(await runTransactionTotally(executeTransaction, assembler, operations, requestIdOf(options), stateOptionOf(options), resolvedConfig.diagnostics, callerOf(options)))),
     };
     recordDiagnosticsSink(framework, resolvedConfig.diagnostics);
+    recordAccessProvider(framework, config.access);
     recordOwnedExecution(framework, {
         execute: (request, refused) => executeTotally(execute, request, resolvedConfig.diagnostics, refused === undefined ? "owned" : { refused }),
         executeTransaction: (request, refused) => executeTransactionTotally(executeTransaction, request, resolvedConfig.diagnostics, undefined, refused === undefined
@@ -129,6 +136,18 @@ async function prebuiltCompilation(prebuilt, model, config, resolved) {
     }
     return { ok: true, contracts: loaded.contracts };
 }
+function encodingApplicationValues(execute, contract) {
+    return (request, report, _source, caller) => {
+        const copy = copyAtDoor(request.arguments);
+        if (!copy.ok) {
+            return execute(request, report, { refused: copy.error }, caller);
+        }
+        return execute({
+            ...request,
+            arguments: encodeOperationArgumentsForWire(contract, request, copy.value),
+        }, report, "owned", caller);
+    };
+}
 async function executeTotally(execute, request, diagnostics, source, caller) {
     const report = createDiagnosticsReporter(diagnostics, request);
     try {