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

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";
@@ -90,12 +91,24 @@ export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAn
      */
     readonly policy?: {
         readonly engine: AvPolicyEngine;
-        /** The request's principal, from its `ctx.$state` and its layer; `null` for an anonymous caller. */
+        /**
+         * The request's principal, from its `ctx.$state` and its layer; `null` for
+         * an anonymous caller. It may answer with a promise (rc.5), which is
+         * awaited; a throw or a rejection answers `A3000`.
+         */
         readonly principal: (facts: {
             readonly $state: AvState;
             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/contracts/contract.d.ts

@@ -1,6 +1,7 @@
 import type { AvContractLimits } from "./contract-limits.js";
 import type { AvContractClientProtocol } from "./contract-protocol.js";
 import type { AvEnumDefinition } from "./enum-definition.js";
+import type { AvCoreField } from "./field.js";
 import type { ReferenceWriteLimit } from "./reference-write-limit.js";
 import type { AvResource } from "./resource.js";
 import type { AvScalarRegistry } from "./scalar.js";
@@ -24,8 +25,21 @@ export interface AvContract {
      */
     readonly referenceWrites?: ReferenceWriteLimit;
 }
-/** The Contract compiled from the root configuration. */
+/**
+ * The Contract compiled from the root configuration. Its relation fields also
+ * state the target's fields their reference names (`references`), which no
+ * other Contract carries.
+ */
 export interface AvContractCore extends AvContract {
+    /** The Resources, by name. */
+    readonly resources: Readonly<Record<string, AvCoreResource>>;
+}
+/**
+ * A Resource as the Core Contract states it: its fields are
+ * {@link AvCoreField}s, so its relation fields carry `references`.
+ */
+export interface AvCoreResource extends AvResource<AvContractCore> {
+    readonly fields: Readonly<Record<string, AvCoreField<AvContractCore>>>;
 }
 /** The Contract in-process calls run under (`framework.application`). */
 export interface AvContractApplication extends AvContract {

package/dist/contracts/field.d.ts

@@ -176,3 +176,20 @@ export type AvRelationField<C extends AvContract> = {
 };
 /** One field of a Resource: a scalar or a relation. */
 export type AvField<C extends AvContract> = AvScalarField<C> | AvRelationField<C>;
+/**
+ * A relation field as the Core Contract states it: an {@link AvRelationField}
+ * and, on the end that holds the reference, the target's fields it names.
+ */
+export type AvCoreRelationField<C extends AvContract> = AvRelationField<C> & {
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in the
+     * same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`). Present only beside a `referenceFields` the
+     * Contract states whole, and only when every one of them is a scalar field
+     * the Core Contract shows on the target; absent on the end that holds no
+     * reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
+};
+/** One field of a Resource as the Core Contract states it. */
+export type AvCoreField<C extends AvContract> = AvScalarField<C> | AvCoreRelationField<C>;

package/dist/contracts/scalar-value-type.d.ts

@@ -78,5 +78,7 @@ type ListValue<List, Atom> = [List] extends [false] ? Atom : [List] extends [tru
  * - `list: true` → `readonly T[]`, whose entries are never `null`;
  * - `nullable: true` → `| null`, on the whole value, list or not.
  */
-export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never);
+export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = [
+    ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never)
+] extends [infer Value] ? Value : never;
 export {};

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.d.ts

@@ -15,7 +15,8 @@ export type AvConstructionDiagnostic = ConstructionProblem & {
 };
 /**
  * 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;

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

@@ -1,14 +1,25 @@
+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.map((diagnostic) => ({
@@ -17,3 +28,4 @@ export class AvConstructionError extends Error {
         }));
     }
 }
+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.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 {

package/dist/framework/operation-facade.d.ts

@@ -6,10 +6,10 @@ import type { AvOperationCall, AvOperationGrammar, DeferredArguments, DeferredPl
 import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import { type PolicyCaller } from "../policy/policy-request.js";
 import type { AvExecutionOptions } from "../runtime/execution-options.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 { AvState } from "../runtime/request-state.js";
-import type { SqlStatementBuilder } from "../transactions/sql-statement.js";
+import type { AvSqlStatementBuilder } from "../transactions/sql-statement.js";
 import type { AvTransactionResponse } from "../transactions/transaction-response.js";
 import type { AvContractApplicationView, ClientContractView } from "./contract-view.js";
 /**
@@ -20,8 +20,8 @@ import type { AvContractApplicationView, ClientContractView } from "./contract-v
 type OpaqueSurface = {
     readonly [resource: string]: unknown;
 };
-/** The four typed surfaces of an `AvFramework`, named by the member that holds each. */
-type FacadeSurface = "application" | "client" | "appTx" | "clientTx";
+/** The typed surfaces of an `AvFramework`, named by the member that holds each. */
+type FacadeSurface = "application" | "client" | "serverClient" | "appTx" | "clientTx" | "serverClientTx";
 /** `framework.application.<Resource>.<family>.<variant>` when the variant takes a `select` or `include`. */
 export type AvApplicationProjectingCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = ProjectingCall<C, R, I, AvOperationArgumentsFor<C, R, I, AvApplicationScalarForms>, AvApplicationScalarForms, AvExecutionOptions>;
 /** `framework.application.<Resource>.<family>.<variant>` when it does not (the `count` variants). */
@@ -38,13 +38,28 @@ export type AvAppTxPlainCall<in out C extends AvContract, in out R extends AvRes
 export type AvClientTxProjectingCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = DeferredProjectingCall<C, R, I, DeferredArguments<C, R, I, AvWireScalarForms, AvApplicationScalarForms>, AvApplicationScalarForms, "client">;
 /** `framework.clientTx.<Resource>.<family>.<variant>` when it does not. */
 export type AvClientTxPlainCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = DeferredPlainCall<C, R, I, DeferredArguments<C, R, I, AvWireScalarForms, AvApplicationScalarForms>, AvApplicationScalarForms, "client">;
+/**
+ * `framework.serverClient.<Resource>.<family>.<variant>` when the variant takes a `select` or `include`:
+ * the Client Contract's view, application forms in.
+ */
+export type AvServerClientProjectingCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = ProjectingCall<C, R, I, AvOperationArgumentsFor<C, R, I, AvApplicationScalarForms>, AvApplicationScalarForms, AvExecutionOptions>;
+/** `framework.serverClient.<Resource>.<family>.<variant>` when it does not. */
+export type AvServerClientPlainCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = PlainCall<C, R, I, AvOperationArgumentsFor<C, R, I, AvApplicationScalarForms>, AvApplicationScalarForms, AvExecutionOptions>;
+/**
+ * `framework.serverClientTx.<Resource>.<family>.<variant>` when the variant takes a `select` or `include`:
+ * the Client Contract's view, application forms in, a client-origin handle out.
+ */
+export type AvServerClientTxProjectingCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = DeferredProjectingCall<C, R, I, DeferredArguments<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms>, AvApplicationScalarForms, "client">;
+/** `framework.serverClientTx.<Resource>.<family>.<variant>` when it does not. */
+export type AvServerClientTxPlainCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = DeferredPlainCall<C, R, I, DeferredArguments<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms>, AvApplicationScalarForms, "client">;
 /**
  * One variant on a surface: a direct call (application or wire forms), or a
- * deferred one for a transaction (`appTx`, `clientTx`), projecting when its
- * arguments carry a `select` (as `AvOperationCall` and `AvDeferredOperationCall`
- * decide it).
+ * deferred one for a transaction (`appTx`, `clientTx`, `serverClientTx`),
+ * projecting when its arguments carry a `select` (as `AvOperationCall` and
+ * `AvDeferredOperationCall` decide it). `serverClient` and `serverClientTx` take
+ * the application forms over the Client Contract's view.
  */
-type SurfaceCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, S extends FacadeSurface> = S extends "application" ? "select" extends keyof AvOperationArgumentsFor<C, R, I, AvApplicationScalarForms> ? AvApplicationProjectingCall<C, R, I> : AvApplicationPlainCall<C, R, I> : S extends "client" ? "select" extends keyof AvOperationArgumentsFor<C, R, I, AvWireScalarForms> ? AvClientProjectingCall<C, R, I> : AvClientPlainCall<C, R, I> : S extends "appTx" ? "select" extends keyof DeferredArguments<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms> ? AvAppTxProjectingCall<C, R, I> : AvAppTxPlainCall<C, R, I> : "select" extends keyof DeferredArguments<C, R, I, AvWireScalarForms, AvApplicationScalarForms> ? AvClientTxProjectingCall<C, R, I> : AvClientTxPlainCall<C, R, I>;
+type SurfaceCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, S extends FacadeSurface> = S extends "application" ? "select" extends keyof AvOperationArgumentsFor<C, R, I, AvApplicationScalarForms> ? AvApplicationProjectingCall<C, R, I> : AvApplicationPlainCall<C, R, I> : S extends "client" ? "select" extends keyof AvOperationArgumentsFor<C, R, I, AvWireScalarForms> ? AvClientProjectingCall<C, R, I> : AvClientPlainCall<C, R, I> : S extends "serverClient" ? "select" extends keyof AvOperationArgumentsFor<C, R, I, AvApplicationScalarForms> ? AvServerClientProjectingCall<C, R, I> : AvServerClientPlainCall<C, R, I> : S extends "appTx" ? "select" extends keyof DeferredArguments<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms> ? AvAppTxProjectingCall<C, R, I> : AvAppTxPlainCall<C, R, I> : S extends "clientTx" ? "select" extends keyof DeferredArguments<C, R, I, AvWireScalarForms, AvApplicationScalarForms> ? AvClientTxProjectingCall<C, R, I> : AvClientTxPlainCall<C, R, I> : "select" extends keyof DeferredArguments<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms> ? AvServerClientTxProjectingCall<C, R, I> : AvServerClientTxPlainCall<C, R, I>;
 /** The families view `C` advertises on Resource `R`. */
 type FamilyKey<C extends AvContract, R extends AvResourceKey<C>> = keyof AvOperationGrammar<C>[R];
 /** One family node of surface `S`; the public names below are its four instances. */
@@ -55,10 +70,14 @@ type FamilyNode<C extends AvContract, S extends FacadeSurface, R extends AvResou
 export type AvApplicationFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "application", R, F>;
 /** `framework.client.<Resource>.<family>`: one direct call per variant, wire forms. */
 export type AvClientFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "client", R, F>;
+/** `framework.serverClient.<Resource>.<family>`: one direct call per variant, application forms. */
+export type AvServerClientFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "serverClient", R, F>;
 /** `framework.appTx.<Resource>.<family>`: one deferred operation per variant. */
 export type AvAppTxFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "appTx", R, F>;
 /** `framework.clientTx.<Resource>.<family>`: one deferred operation per variant. */
 export type AvClientTxFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "clientTx", R, F>;
+/** `framework.serverClientTx.<Resource>.<family>`: one deferred operation per variant, application forms. */
+export type AvServerClientTxFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "serverClientTx", R, F>;
 /** `framework.application.<Resource>`: one {@link AvApplicationFamilyFacade} per family. */
 export type AvApplicationResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
     readonly [F in FamilyKey<C, R>]: AvApplicationFamilyFacade<C, R, F>;
@@ -67,6 +86,10 @@ export type AvApplicationResourceFacade<in out C extends AvContract, in out R ex
 export type AvClientResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
     readonly [F in FamilyKey<C, R>]: AvClientFamilyFacade<C, R, F>;
 };
+/** `framework.serverClient.<Resource>`: one {@link AvServerClientFamilyFacade} per family. */
+export type AvServerClientResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
+    readonly [F in FamilyKey<C, R>]: AvServerClientFamilyFacade<C, R, F>;
+};
 /** `framework.appTx.<Resource>`: one {@link AvAppTxFamilyFacade} per family. */
 export type AvAppTxResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
     readonly [F in FamilyKey<C, R>]: AvAppTxFamilyFacade<C, R, F>;
@@ -75,6 +98,10 @@ export type AvAppTxResourceFacade<in out C extends AvContract, in out R extends
 export type AvClientTxResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
     readonly [F in FamilyKey<C, R>]: AvClientTxFamilyFacade<C, R, F>;
 };
+/** `framework.serverClientTx.<Resource>`: one {@link AvServerClientTxFamilyFacade} per family. */
+export type AvServerClientTxResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
+    readonly [F in FamilyKey<C, R>]: AvServerClientTxFamilyFacade<C, R, F>;
+};
 /**
  * `framework.application`: one {@link AvApplicationResourceFacade} per Resource
  * of `C`, the Application Contract's view.
@@ -89,14 +116,21 @@ export type AvApplicationFacade<C extends AvContract> = {
 export type AvClientFacade<C extends AvContract> = {
     readonly [R in AvResourceKey<C>]: AvClientResourceFacade<C, R>;
 };
+/**
+ * `framework.serverClient`: one {@link AvServerClientResourceFacade} per Resource
+ * of `C`, the Client Contract's view, taking application forms.
+ */
+export type AvServerClientFacade<C extends AvContract> = {
+    readonly [R in AvResourceKey<C>]: AvServerClientResourceFacade<C, R>;
+};
 /** `framework.appTx.$sql`: the developer SQL step only an application transaction has. */
 type ApplicationSqlStep = {
     /**
      * A developer SQL step, written only as a tagged template:
      * ``framework.appTx.$sql<Row>`select … ${value}` ``. Every interpolated value
-     * is bound as a parameter. See {@link SqlStatementBuilder}.
+     * is bound as a parameter. See {@link AvSqlStatementBuilder}.
      */
-    readonly $sql: SqlStatementBuilder;
+    readonly $sql: AvSqlStatementBuilder;
 };
 /**
  * `framework.appTx`: one {@link AvAppTxResourceFacade} per Resource of `C`, the
@@ -112,18 +146,31 @@ export type AvAppTxFacade<C extends AvContract> = {
 export type AvClientTxFacade<C extends AvContract> = {
     readonly [R in AvResourceKey<C>]: AvClientTxResourceFacade<C, R>;
 };
+/**
+ * `framework.serverClientTx`: one {@link AvServerClientTxResourceFacade} per
+ * Resource of `C`, the Client Contract's view, taking application forms.
+ */
+export type AvServerClientTxFacade<C extends AvContract> = {
+    readonly [R in AvResourceKey<C>]: AvServerClientTxResourceFacade<C, R>;
+};
 type ApplicationSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface : AvApplicationFacade<C> : never;
 type ClientSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface : AvClientFacade<C> : never;
+type ServerClientSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface : AvServerClientFacade<C> : never;
 type ApplicationDeferredSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface & ApplicationSqlStep : AvAppTxFacade<C> : never;
 type ClientDeferredSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface : AvClientTxFacade<C> : never;
+type ServerClientDeferredSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface : AvServerClientTxFacade<C> : never;
 /** `framework.application`'s type: {@link AvApplicationFacade}, or opaque. */
 export type ApplicationOperations<M extends AvAdapterModel, Cfg> = ApplicationSurface<AvContractApplicationView<M, Cfg>>;
 /** `framework.client`'s type: {@link AvClientFacade}, or opaque. */
 export type ClientOperations<M extends AvAdapterModel, Cfg> = ClientSurface<ClientContractView<M, Cfg>>;
+/** `framework.serverClient`'s type: {@link AvServerClientFacade}, or opaque. */
+export type ServerClientOperations<M extends AvAdapterModel, Cfg> = ServerClientSurface<ClientContractView<M, Cfg>>;
 /** `framework.appTx`'s type: {@link AvAppTxFacade}, or opaque with `$sql`. */
 export type ApplicationTransactionBuilders<M extends AvAdapterModel, Cfg> = ApplicationDeferredSurface<AvContractApplicationView<M, Cfg>>;
 /** `framework.clientTx`'s type: {@link AvClientTxFacade}, or opaque. */
 export type ClientTransactionBuilders<M extends AvAdapterModel, Cfg> = ClientDeferredSurface<ClientContractView<M, Cfg>>;
+/** `framework.serverClientTx`'s type: {@link AvServerClientTxFacade}, or opaque. */
+export type ServerClientTransactionBuilders<M extends AvAdapterModel, Cfg> = ServerClientDeferredSurface<ClientContractView<M, Cfg>>;
 /**
  * The Resources of a pipeline ctx: `ctx.<Resource>.<family>.<variant>(args)`,
  * application-origin, resolving the operation's data.
@@ -149,8 +196,8 @@ type ComputeReadFacade<C> = C extends AvContract ? string extends AvResourceKey<
     };
 } : never;
 /** Builds the request one façade call hands to `execute`, under its request id and state. */
-export type FacadeRequest = (resource: string, identity: AvOperationIdentity, args: unknown, requestId: string, state: AvState | undefined) => FrameworkOperationRequest;
-type FacadeExecutor = (request: FrameworkOperationRequest, caller: PolicyCaller | undefined) => Promise<AvOperationResponse>;
+export type FacadeRequest = (resource: string, identity: AvOperationIdentity, args: unknown, requestId: string, state: AvState | undefined) => AvOperationRequest;
+type FacadeExecutor = (request: AvOperationRequest, caller: PolicyCaller | undefined) => Promise<AvOperationResponse>;
 /**
  * Builds a façade over `model`, the same object its types are read from, so a
  * call that type-checks always reaches `execute`: a Resource, variant or field

package/dist/index.d.ts

@@ -13,12 +13,12 @@ export type { AvConfigExact } from "./config/exact-framework-config.js";
 export type { AvConfig, AvConfigAddedFieldDefinition, AvConfigAgentLayer, AvConfigAny, AvConfigExemptions, AvConfigFamily, AvConfigFieldDefinition, AvConfigFieldLifecycleTrait, AvConfigKnownFieldDefinition, AvConfigLayer, AvConfigLayerAny, AvConfigLayerKind, AvConfigLimits, AvConfigMcp, AvConfigOperations, AvConfigOperationsExemption, AvConfigOverlayField, AvConfigRelationFieldExemption, AvConfigResource, AvConfigResourceExemption, AvConfigResourceFields, AvConfigResourceKey, AvConfigResources, AvConfigResourcesAny, AvConfigResourceTransactions, AvConfigRootField, AvConfigScalarFieldExemption, AvConfigScalarTypeRef, AvConfigVariant, AvFieldCompute, AvRelationFieldCapabilityName, AvRelationFieldPipeline, AvScalarFieldCapabilityName, AvScalarFieldPipeline, AvZCheck, AvZFormat, } from "./config/framework-config.js";
 export type { AvPipeline, AvTransactionPipeline, } from "./config/pipeline-config.js";
 export type { AvPaginationCapability, AvProjectionScope, AvRelationFilterCapability, AvRelationMutationDirective, AvRelationReducer, AvScalarFilterOperator, AvScalarMutationDirective, AvWriteScope, } from "./contracts/capability.js";
-export type { AvContract, AvContractAgent, AvContractApplication, AvContractClient, AvContractCore, } from "./contracts/contract.js";
+export type { AvContract, AvContractAgent, AvContractApplication, AvContractClient, AvContractCore, AvCoreResource, } from "./contracts/contract.js";
 export type { AvContractLimits } from "./contracts/contract-limits.js";
 export type { AvContractClientProtocol, AvContractHash, AvContractProtocol, } from "./contracts/contract-protocol.js";
 export type { AvCreateRequirementGroup, AvCreateRequirements, } from "./contracts/create-requirements.js";
 export type { AvEnumDefinition } from "./contracts/enum-definition.js";
-export type { AvField, AvProjectionScopes, AvRelationField, AvRelationFieldCapabilities, AvRelationMutationCapability, AvRelationProjectionCapability, AvRelationReducerCapability, AvScalarField, AvScalarFieldCapabilities, AvScalarFormat, AvScopedRelationMutations, AvScopedRelationReducers, AvWriteScopes, } from "./contracts/field.js";
+export type { AvCoreField, AvCoreRelationField, AvField, AvProjectionScopes, AvRelationField, AvRelationFieldCapabilities, AvRelationMutationCapability, AvRelationProjectionCapability, AvRelationReducerCapability, AvScalarField, AvScalarFieldCapabilities, AvScalarFormat, AvScopedRelationMutations, AvScopedRelationReducers, AvWriteScopes, } from "./contracts/field.js";
 export type { AvFieldCheck } from "./contracts/field-check.js";
 export type { AvIdentifier, AvScalarFieldKey } from "./contracts/identifier.js";
 export type { AvLifecycleTrait } from "./contracts/lifecycle-trait.js";
@@ -32,12 +32,13 @@ export { createFramework } from "./framework/framework.factory.js";
 export type { AvFramework } from "./framework/framework.js";
 export type { AvConstructionDiagnostic, AvConstructionStage, } from "./framework/framework-construction.error.js";
 export { AvConstructionError } from "./framework/framework-construction.error.js";
-export type { AvApplicationFacade, AvApplicationFamilyFacade, AvApplicationPlainCall, AvApplicationProjectingCall, AvApplicationResourceFacade, AvAppTxFacade, AvAppTxFamilyFacade, AvAppTxPlainCall, AvAppTxProjectingCall, AvAppTxResourceFacade, AvClientFacade, AvClientFamilyFacade, AvClientPlainCall, AvClientProjectingCall, AvClientResourceFacade, AvClientTxFacade, AvClientTxFamilyFacade, AvClientTxPlainCall, AvClientTxProjectingCall, AvClientTxResourceFacade, } from "./framework/operation-facade.js";
-export type { AvCreateDataInput, AvCursorInput, AvFieldKey, AvIncludeInput, AvNullsOrder, AvOperationArgumentMap, AvOperationArgumentsFor, AvOrderByEntry, AvOrderByInput, AvProjectionEntry, AvRelationProjectionInput, AvResourceKey, AvScalarOrderInput, AvSelectInput, AvSortDirection, AvUniqueWhereInput, AvUpdateDataInput, AvWhereInput, } from "./operations/operation-arguments.js";
+export type { AvApplicationFacade, AvApplicationFamilyFacade, AvApplicationPlainCall, AvApplicationProjectingCall, AvApplicationResourceFacade, AvAppTxFacade, AvAppTxFamilyFacade, AvAppTxPlainCall, AvAppTxProjectingCall, AvAppTxResourceFacade, AvClientFacade, AvClientFamilyFacade, AvClientPlainCall, AvClientProjectingCall, AvClientResourceFacade, AvClientTxFacade, AvClientTxFamilyFacade, AvClientTxPlainCall, AvClientTxProjectingCall, AvClientTxResourceFacade, AvServerClientFacade, AvServerClientFamilyFacade, AvServerClientPlainCall, AvServerClientProjectingCall, AvServerClientResourceFacade, AvServerClientTxFacade, AvServerClientTxFamilyFacade, AvServerClientTxPlainCall, AvServerClientTxProjectingCall, AvServerClientTxResourceFacade, } from "./framework/operation-facade.js";
+export type { AvCreateDataInput, AvCursorInput, AvFieldKey, AvIncludeInput, AvNoAdvertisedMember, AvNullsOrder, AvOperationArgumentMap, AvOperationArgumentsFor, AvOrderByEntry, AvOrderByInput, AvProjectionEntry, AvRelationProjectionInput, AvResourceKey, AvScalarFilterOperands, AvScalarOrderInput, AvScalarWhereInput, AvSelectInput, AvSortDirection, AvUniqueWhereInput, AvUpdateDataInput, AvWhereInput, } from "./operations/operation-arguments.js";
 export type { AvDeferredOperationCall, AvOperationCall, AvOperationGrammar, AvOperationSlot, } from "./operations/operation-call.js";
 export type { AvOperationFamily, AvOperationIdentity, AvOperationVariant, } from "./operations/operation-identity.js";
 export type { AvOperationResultFor } from "./operations/operation-result.js";
 export type { AvValidationCode, AvValidationIssue, } from "./operations/validation-code.js";
+export type { AvAccessProvider } from "./policy/access-provider.interface.js";
 export type { AvPolicyEngine, AvPolicyWhere, } from "./policy/policy-engine.js";
 export type { AvPrebuiltContracts } from "./prebuilt/prebuilt-contracts.js";
 export { AvDecimal } from "./runtime/decimal.js";
@@ -48,14 +49,17 @@ export type { AvComputeContext, AvComputeCreate, AvComputeRead, AvComputeUpdate,
 export { AvAuthError, AvConflictError, AvContractMismatchError, AvError, AvInternalError, AvNotFoundError, AvProtocolError, AvValidationError, } from "./runtime/framework-error.js";
 export type { AvJsonValue } from "./runtime/json-value.js";
 export type { AvMisuseEvent, AvMisuseSink, } from "./runtime/misuse-reporter.js";
+export type { AvAgentOperationRequest, AvApplicationOperationRequest, AvClientOperationRequest, AvOperationRequest, AvRequestProtocol, } from "./runtime/operation-request.js";
 export type { AvCause, AvOperationCode, AvOperationErrorCode, AvOperationFailureResponse, AvOperationNoMatchResponse, AvOperationResponse, AvOperationSuccessCode, AvOperationSuccessDataCode, AvOperationSuccessResponse, } from "./runtime/operation-response.js";
 export type { AvAfterHook, AvBeforeHook, AvContext, AvFieldGuard, AvFieldPipe, AvFilter, AvGuard, AvInterceptor, AvPipe, AvTransactionAfterHook, AvTransactionBeforeHook, AvTransactionContext, AvTransactionFilter, AvTransactionGuard, AvTransactionInterceptor, AvTransactionPipe, AvTransactionStep, AvTransportContext, } from "./runtime/pipeline.js";
 export type { AvDeepReadonly } from "./runtime/readonly-value.js";
 export type { AvState } from "./runtime/request-state.js";
 export type { AvOperation, AvOperationHandle, AvOperationReferenceSurface, AvReferenceableField, AvReferenceBuilder, AvSingleRowResult, AvTransactionResults, AvTransactionRunner, } from "./transactions/deferred-operation.js";
+export type { AvSqlStatementBuilder, AvSqlStatementValue, } from "./transactions/sql-statement.js";
 export type { AvTransactionIntegrityViolation } from "./transactions/transaction-integrity-error.js";
 export { AvTransactionIntegrityError } from "./transactions/transaction-integrity-error.js";
 export type { AvTransactionReference } from "./transactions/transaction-reference.js";
+export type { AvAgentTransactionRequest, AvApplicationTransactionRequest, AvClientTransactionRequest, AvTransactionRequest, } from "./transactions/transaction-request.js";
 export type { AvTransactionCommittedResponse, AvTransactionResponse, } from "./transactions/transaction-response.js";
 export type { AvTransactionSlotPathViolation } from "./transactions/transaction-slot-path-error.js";
 export { AvTransactionSlotPathError } from "./transactions/transaction-slot-path-error.js";

package/dist/internal.d.ts

@@ -32,12 +32,12 @@ export type { AvDatabaseRefusal } from "./operations/database-refusal.js";
 export { DATABASE_REFUSALS } from "./operations/database-refusal.js";
 export type { SemanticOperationArguments } from "./operations/operation-validator.js";
 export { VALIDATION_CODES } from "./operations/validation-code.js";
+export { accessStateOf } from "./policy/access-provider.registry.js";
+export { prebuiltFileChanges } from "./prebuilt/prebuilt-changes.js";
 export { emitPrebuiltContracts, prebuiltContractsOf, } from "./prebuilt/prebuilt-contracts.emitter.js";
 export { mcpFailureReporterOf } from "./runtime/diagnostics-reporter.js";
 export type { AvErrorClassName } from "./runtime/framework-error-class.table.js";
 export { FRAMEWORK_ERROR_CLASS_OF } from "./runtime/framework-error-class.table.js";
-export type { AgentOperationRequest, ApplicationOperationRequest, ClientOperationRequest, ClientProtocolIdentity, FrameworkOperationRequest, } from "./runtime/operation-request.js";
 export { OPERATION_CODES } from "./runtime/operation-response.js";
 export type { BuiltinNonRow, OperationFingerprint, } from "./transactions/deferred-operation.js";
 export { computeOperationFingerprint } from "./transactions/operation-fingerprint.js";
-export type { AgentTransactionRequest, ApplicationTransactionRequest, ClientTransactionRequest, FrameworkTransactionRequest, } from "./transactions/transaction-request.js";

package/dist/internal.js

@@ -13,6 +13,8 @@ export { BUILT_IN_SCALARS } from "./contracts/scalar.js";
 export { TRANSACTION_CAPABILITIES } from "./contracts/transaction-capability.js";
 export { DATABASE_REFUSALS } from "./operations/database-refusal.js";
 export { VALIDATION_CODES } from "./operations/validation-code.js";
+export { accessStateOf } from "./policy/access-provider.registry.js";
+export { prebuiltFileChanges } from "./prebuilt/prebuilt-changes.js";
 export { emitPrebuiltContracts, prebuiltContractsOf, } from "./prebuilt/prebuilt-contracts.emitter.js";
 export { mcpFailureReporterOf } from "./runtime/diagnostics-reporter.js";
 export { FRAMEWORK_ERROR_CLASS_OF } from "./runtime/framework-error-class.table.js";