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

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,33 @@ 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 policy engine's `governed` set, when its type states one. */
+type GovernedBlock<Cfg> = LiteralRecord<(NonNullable<PolicyEngineOf<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];
+};
 /**
  * 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 : {
@@ -132,8 +161,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
@@ -289,13 +318,15 @@ export type RootViewResources<M extends AvAdapterModel, Cfg> = ExposedResources<
 /** 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>>>;
 /**
- * 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.
  */
-type DerivedContractView<M extends AvAdapterModel, FieldsBlock, RootStyle, RootExemptions, OverlayStyle, OverlayExemptions, OverlayBlock> = {
+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"], FieldsBlock, OverlayBlock>, RootStyle, RootExemptions>, OverlayStyle, OverlayExemptions>;
+    readonly resources: ExposedResources<ExposedResources<LayeredResources<M["resources"], RootFields, OverlayFields, Governed>, RootStyle, RootExemptions>, OverlayStyle, OverlayExemptions>;
     readonly limits: AvContractLimits;
     readonly transactions: M["transactions"];
 };
@@ -303,7 +334,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] ? 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>> : 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 +342,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] ? 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>> : never;
 export {};

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

@@ -4,11 +4,21 @@ const FRAMEWORK_CONSTRUCTION_MESSAGES = {
     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) => ({

package/dist/framework/framework.d.ts

@@ -2,10 +2,10 @@ 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";
 /**
@@ -72,7 +72,7 @@ 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>;
+    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 +83,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

@@ -1,9 +1,12 @@
-import { compileContracts } from "../compiler/contract.compiler.js";
+import { compileContracts, } from "../compiler/contract.compiler.js";
 import { computedFieldsOf, warnOnStaleComputedFields, } from "../config/computed-fields.js";
-import { resolveFrameworkConfig } from "../config/config.resolver.js";
+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 { 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 { createDiagnosticsReporter, createTransactionDiagnosticsChannel, recordDiagnosticsSink, } from "../runtime/diagnostics-reporter.js";
 import { createMisuseReporter, } from "../runtime/misuse-reporter.js";
@@ -39,7 +42,9 @@ export async function createFramework(config) {
         trees: resolvedConfig.trees,
         agentExtends: resolvedConfig.agent.parent,
     }));
-    const compilation = await compileContracts(model, resolvedConfig);
+    const compilation = (config.prebuilt === undefined
+        ? undefined
+        : await prebuiltCompilation(config.prebuilt, model, config, resolvedConfig)) ?? (await compileContracts(model, resolvedConfig));
     if (!compilation.ok) {
         throw new AvConstructionError("contract-compilation", compilation.diagnostics);
     }
@@ -47,6 +52,12 @@ export async function createFramework(config) {
     if (forcing.length > 0) {
         throw new AvConstructionError("configuration", forcing);
     }
+    if (resolvedConfig.policy !== undefined) {
+        const policy = policyStartupDiagnostics(compilation.contracts.core, resolvedConfig.policy);
+        if (policy.length > 0) {
+            throw new AvConstructionError("configuration", policy);
+        }
+    }
     const runtimeDependencies = {
         adapter: config.adapter,
         contracts: compilation.contracts,
@@ -56,7 +67,7 @@ export async function createFramework(config) {
     const execute = createOperationRuntime(runtimeDependencies, pipelineDependencies);
     const executeTransaction = createTransactionRuntime(runtimeDependencies, pipelineDependencies);
     const misuse = createMisuseReporter(resolvedConfig.misuse);
-    const executeOperation = (request) => executeTotally(execute, request, resolvedConfig.diagnostics, "caller");
+    const executeOperation = (request, caller) => executeTotally(execute, request, resolvedConfig.diagnostics, "caller", caller);
     const protocol = {
         version: AVENTARA_PROTOCOL_VERSION,
         hash: compilation.contracts.client.protocol.hash,
@@ -90,7 +101,7 @@ export async function createFramework(config) {
         clientTx: createOperationTree(model, (resource, identity) => (args) => assembler.defer("client", resource, identity, args === undefined ? {} : args)),
         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))),
+        transaction: (async (operations, options) => settleOperation(await runTransactionTotally(executeTransaction, assembler, operations, requestIdOf(options), stateOptionOf(options), resolvedConfig.diagnostics, callerOf(options)))),
     };
     recordDiagnosticsSink(framework, resolvedConfig.diagnostics);
     recordOwnedExecution(framework, {
@@ -101,10 +112,27 @@ export async function createFramework(config) {
     });
     return framework;
 }
-async function executeTotally(execute, request, diagnostics, source) {
+async function prebuiltCompilation(prebuilt, model, config, resolved) {
+    let loaded;
+    try {
+        loaded = await loadPrebuiltContracts(prebuilt, model, config, resolved);
+    }
+    catch (error) {
+        loaded = {
+            ok: false,
+            reason: `it could not be read (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    if (!loaded.ok) {
+        warnStalePrebuilt(loaded.reason);
+        return undefined;
+    }
+    return { ok: true, contracts: loaded.contracts };
+}
+async function executeTotally(execute, request, diagnostics, source, caller) {
     const report = createDiagnosticsReporter(diagnostics, request);
     try {
-        return await execute(request, report, source);
+        return await execute(request, report, source, caller);
     }
     catch (error) {
         report(error, "A3000");
@@ -145,18 +173,18 @@ function executeTransactionRequestTotally(execute, request, diagnostics, misuse)
     }
     return executeTransactionTotally(execute, envelope.value, diagnostics, undefined, { source: "caller" });
 }
-async function executeTransactionTotally(execute, request, diagnostics, origins, planArguments) {
+async function executeTransactionTotally(execute, request, diagnostics, origins, planArguments, caller) {
     const channel = createTransactionDiagnosticsChannel(diagnostics, request);
     const report = channel.transaction();
     try {
-        return await execute(request, channel, origins, planArguments);
+        return await execute(request, channel, origins, planArguments, caller);
     }
     catch (error) {
         report(error, "A3000");
         return internalFailure();
     }
 }
-async function runTransactionTotally(execute, assembler, operations, requestId, state, diagnostics) {
+async function runTransactionTotally(execute, assembler, operations, requestId, state, diagnostics, caller) {
     let assembled;
     try {
         assembled = await assembler.assemble(operations);
@@ -181,5 +209,5 @@ async function runTransactionTotally(execute, assembler, operations, requestId,
         source: "owned",
         refused: assembled.refused,
         statements: assembled.statements,
-    });
+    }, caller);
 }

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

@@ -1,14 +1,15 @@
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvContract } from "../contracts/contract.js";
 import type { AvApplicationScalarForms, AvWireScalarForms } from "../contracts/scalar-value-type.js";
-import type { AvResourceKey } from "../operations/operation-arguments.js";
-import type { AvDeferredOperationCall, AvOperationCall, AvOperationGrammar } from "../operations/operation-call.js";
+import type { AvOperationArgumentsFor, AvResourceKey } from "../operations/operation-arguments.js";
+import type { AvOperationCall, AvOperationGrammar, DeferredArguments, DeferredPlainCall, DeferredProjectingCall, PlainCall, ProjectingCall } from "../operations/operation-call.js";
 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";
 /**
@@ -21,11 +22,29 @@ type OpaqueSurface = {
 };
 /** The four typed surfaces of an `AvFramework`, named by the member that holds each. */
 type FacadeSurface = "application" | "client" | "appTx" | "clientTx";
+/** `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). */
+export type AvApplicationPlainCall<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.client.<Resource>.<family>.<variant>` when the variant takes a `select` or `include`: wire forms in. */
+export type AvClientProjectingCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = ProjectingCall<C, R, I, AvOperationArgumentsFor<C, R, I, AvWireScalarForms>, AvApplicationScalarForms, AvExecutionOptions>;
+/** `framework.client.<Resource>.<family>.<variant>` when it does not. */
+export type AvClientPlainCall<in out C extends AvContract, in out R extends AvResourceKey<C>, in out I extends AvOperationIdentity> = PlainCall<C, R, I, AvOperationArgumentsFor<C, R, I, AvWireScalarForms>, AvApplicationScalarForms, AvExecutionOptions>;
+/** `framework.appTx.<Resource>.<family>.<variant>` when the variant takes a `select` or `include`. */
+export type AvAppTxProjectingCall<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, "application">;
+/** `framework.appTx.<Resource>.<family>.<variant>` when it does not. */
+export type AvAppTxPlainCall<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, "application">;
+/** `framework.clientTx.<Resource>.<family>.<variant>` when the variant takes a `select` or `include`: wire forms in. */
+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">;
 /**
  * One variant on a surface: a direct call (application or wire forms), or a
- * deferred one for a transaction (`appTx`, `clientTx`).
+ * deferred one for a transaction (`appTx`, `clientTx`), projecting when its
+ * arguments carry a `select` (as `AvOperationCall` and `AvDeferredOperationCall`
+ * decide it).
  */
-type SurfaceCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, S extends FacadeSurface> = S extends "application" ? AvOperationCall<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms, AvExecutionOptions> : S extends "client" ? AvOperationCall<C, R, I, AvWireScalarForms, AvApplicationScalarForms, AvExecutionOptions> : S extends "appTx" ? AvDeferredOperationCall<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms, "application"> : AvDeferredOperationCall<C, R, I, AvWireScalarForms, AvApplicationScalarForms, "client">;
+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>;
 /** 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. */
@@ -75,9 +94,9 @@ 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
@@ -130,8 +149,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) => 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/framework/operation-facade.js

@@ -1,10 +1,11 @@
 import { isOperationVariantAvailable } from "../contracts/resource-operations.js";
 import { parseOperationIdentity } from "../operations/operation-identity.js";
+import { callerOf } from "../policy/policy-request.js";
 import { thrownFailure } from "../runtime/framework-error.factory.js";
 import { requestIdOf } from "../runtime/request-id.js";
 import { stateOptionOf } from "../runtime/request-state.resolver.js";
 export function createOperationFacade(model, request, execute) {
-    return createOperationTree(model, (resource, identity) => async (args, options) => settleOperation(await execute(request(resource, identity, args === undefined ? {} : args, requestIdOf(options), stateOptionOf(options)))));
+    return createOperationTree(model, (resource, identity) => async (args, options) => settleOperation(await execute(request(resource, identity, args === undefined ? {} : args, requestIdOf(options), stateOptionOf(options)), callerOf(options))));
 }
 export function settleOperation(response) {
     if (response.cause !== null) {

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";
@@ -27,16 +27,19 @@ export type { AvOperationAvailability, AvOperationVariantScopes, AvResourceOpera
 export type { AvBuiltInScalar, AvScalarDefinition, AvScalarRegistry, } from "./contracts/scalar.js";
 export type { AvApplicationScalarForms, AvScalarValueType, AvWireScalarForms, } from "./contracts/scalar-value-type.js";
 export type { AvTransactionCapability } from "./contracts/transaction-capability.js";
+export type { AvContractView } from "./framework/contract-view.js";
 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, AvApplicationResourceFacade, AvAppTxFacade, AvAppTxFamilyFacade, AvAppTxResourceFacade, AvClientFacade, AvClientFamilyFacade, AvClientResourceFacade, AvClientTxFacade, AvClientTxFamilyFacade, 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, } 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 { AvPolicyEngine, AvPolicyWhere, } from "./policy/policy-engine.js";
+export type { AvPrebuiltContracts } from "./prebuilt/prebuilt-contracts.js";
 export { AvDecimal } from "./runtime/decimal.js";
 export type { AvDiagnostic, AvDiagnosticsSink, AvMcpDiagnostic, AvOperationDiagnostic, AvTransactionDiagnostic, } from "./runtime/diagnostics-reporter.js";
 export { AvErrorCatalog, type AvErrorCatalogCode, type AvErrorCatalogEntry, type AvErrorKind, } from "./runtime/error.catalog.js";
@@ -45,14 +48,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,11 +32,11 @@ 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 { 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 { 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";
 export { OPERATION_CODES } from "./runtime/operation-response.js";