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

package/dist/config/config.validator.js

@@ -5,6 +5,8 @@ const ROOT_ONLY_PROPERTIES = new Set([
     "api",
     "mcp",
     "adapter",
+    "prebuilt",
+    "policy",
     "diagnostics",
     "misuse",
     "application",
@@ -618,6 +620,14 @@ export function validateFrameworkConfig(value) {
     else {
         validateAdapter(value.adapter, diagnostics);
     }
+    if (Object.hasOwn(value, "prebuilt") &&
+        value.prebuilt !== undefined &&
+        (value.prebuilt === null || typeof value.prebuilt !== "object")) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "prebuilt", "prebuilt must be the generated prebuilt Contracts object when provided"));
+    }
+    if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
+        validatePolicy(value.policy, diagnostics);
+    }
     if (Object.hasOwn(value, "diagnostics") &&
         value.diagnostics !== undefined &&
         typeof value.diagnostics !== "function") {
@@ -639,6 +649,78 @@ export function validateFrameworkConfig(value) {
     }
     return diagnostics;
 }
+const POLICY_PROPERTIES = new Set(["engine", "principal"]);
+function validatePolicy(value, diagnostics) {
+    if (!isPlainRecord(value)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy", "policy must be { engine, principal }"));
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (!POLICY_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `policy.${key}`, `unknown policy property: ${key}`));
+        }
+    }
+    if (!Object.hasOwn(value, "principal")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "policy.principal", "policy.principal is required"));
+    }
+    else if (typeof value.principal !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy.principal", "policy.principal must be a function"));
+    }
+    if (!Object.hasOwn(value, "engine")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "policy.engine", "policy.engine is required"));
+        return;
+    }
+    const engine = value.engine;
+    if (engine === null || typeof engine !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy.engine", "policy.engine 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`));
+        }
+    }
+    validatePolicyLists(members.governed, "governed", { all: "string lists", one: "a list of strings" }, isStringList, diagnostics);
+    validatePolicyLists(members.paths, "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);
+}
+function validateAfterCheckActions(lists, diagnostics) {
+    if (!isPlainRecord(lists)) {
+        return;
+    }
+    for (const [resource, actions] of Object.entries(lists)) {
+        if (!isStringList(actions)) {
+            continue;
+        }
+        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`));
+            }
+        }
+    }
+}
+function isStringList(value) {
+    return (Array.isArray(value) && value.every((name) => typeof name === "string"));
+}
+function validatePolicyLists(lists, 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`));
+        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}`));
+        }
+    }
+}
 function validateMcp(value, api, diagnostics) {
     if (typeof value === "string") {
         validateMcpPath(value, "mcp", api, diagnostics);

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

@@ -238,6 +238,11 @@ type RootSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
     readonly api: Leaf;
     readonly mcp: McpSchema;
     readonly adapter: Leaf;
+    readonly prebuilt: Leaf;
+    readonly policy: {
+        readonly engine: Leaf;
+        readonly principal: Leaf;
+    };
     readonly diagnostics: Leaf;
     readonly misuse: Leaf;
     readonly resources: RootResourcesSchema<M>;

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

@@ -2,10 +2,13 @@ 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 { AvPolicyEngine } from "../policy/policy-engine.js";
+import type { AvPrebuiltContracts } from "../prebuilt/prebuilt-contracts.js";
 import type { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
 import type { AvMisuseSink } from "../runtime/misuse-reporter.js";
+import type { AvState } from "../runtime/request-state.js";
 import type { AvConfigAny } from "./any-framework-config.js";
-import type { AvConfigLayerName } from "./config-layer.js";
+import type { AvConfigLayerName, AvRequestOrigin } from "./config-layer.js";
 import type { AvConfigExemptions } from "./framework-exemptions-config.js";
 import type { AvConfigLayerKind, AvConfigResources, LayerOfKind } from "./framework-resources-config.js";
 import type { AvPipeline } from "./pipeline-config.js";
@@ -71,6 +74,28 @@ export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAn
      */
     readonly mcp?: AvConfigMcp;
     readonly adapter: AvAdapter<M>;
+    /**
+     * Contracts compiled ahead of time (the generated `aventaraContracts`), for a
+     * fast cold start on serverless and edge platforms. Used only when they were
+     * compiled from this configuration and the adapter's model by this core;
+     * otherwise the Contracts are compiled at startup, as without it, and a
+     * `AVENTARA_PREBUILT_STALE` warning says why.
+     */
+    readonly prebuilt?: AvPrebuiltContracts;
+    /**
+     * The policy engine every client and agent request is checked against, and
+     * how a request's principal is derived from its `ctx.$state`. Application
+     * calls bypass it unless they name a principal (`{ as }`); calls a stage
+     * makes through `ctx` always do.
+     */
+    readonly policy?: {
+        readonly engine: AvPolicyEngine;
+        /** The request's principal, from its `ctx.$state` and its layer; `null` for an anonymous caller. */
+        readonly principal: (facts: {
+            readonly $state: AvState;
+            readonly $origin: AvRequestOrigin;
+        }) => unknown;
+    };
     readonly diagnostics?: AvDiagnosticsSink;
     /** Told about every caller value refused as unreadable or not plain data. */
     readonly misuse?: AvMisuseSink;

package/dist/contracts/client-contract-structure.validator.d.ts

@@ -498,6 +498,10 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly minimum: 0;
                                             readonly unique: false;
                                         };
+                                        readonly governed: {
+                                            readonly is: "literal";
+                                            readonly values: readonly [true];
+                                        };
                                     };
                                 };
                                 readonly relation: {
@@ -694,6 +698,10 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly minimum: 1;
                                             readonly unique: false;
                                         };
+                                        readonly governed: {
+                                            readonly is: "literal";
+                                            readonly values: readonly [true];
+                                        };
                                     };
                                 };
                             };

package/dist/contracts/client-contract-structure.validator.js

@@ -237,6 +237,7 @@ const SCALAR_FIELD = object({
     format: STRING,
     json: { is: "jsonSchema" },
     validators: list(FIELD_CHECK),
+    governed: literal([true]),
 });
 const RELATION_FIELD = object({
     kind: literal(["relation"]),
@@ -257,7 +258,11 @@ const RELATION_FIELD = object({
         update: RELATION_MUTATION,
         nestedWriteFilter: literal(["scalar"]),
     }),
-}, { inverse: STRING, referenceFields: nonEmptyList(STRING) });
+}, {
+    inverse: STRING,
+    referenceFields: nonEmptyList(STRING),
+    governed: literal([true]),
+});
 const OPERATION_AVAILABILITY = union(literal([true]), object({ projection: literal(PROJECTION_SCOPES) }, { write: literal(WRITE_SCOPES) }), object({ write: literal(WRITE_SCOPES) }, { projection: literal(PROJECTION_SCOPES) }));
 const RESOURCE = object({
     fields: registry({

package/dist/contracts/field.d.ts

@@ -138,6 +138,12 @@ export type AvScalarField<C extends AvContract> = {
      * `list: true` length check, which applies to the list.
      */
     readonly validators?: readonly AvFieldCheck[];
+    /**
+     * `true` when the policy governs the field: it is left out of every default
+     * projection, and a caller that wants it names it (`select: ["$defaults",
+     * "email"]`).
+     */
+    readonly governed?: true;
 };
 /** A relation field; the `target` Resource describes the related row. */
 export type AvRelationField<C extends AvContract> = {
@@ -162,6 +168,11 @@ export type AvRelationField<C extends AvContract> = {
      * holds no reference, and where the layer shows none of them.
      */
     readonly referenceFields?: readonly [string, ...string[]];
+    /**
+     * `true` when the policy engine's `governed` set names the relation: including
+     * it on rows the caller may not read it on refuses the request.
+     */
+    readonly governed?: true;
 };
 /** One field of a Resource: a scalar or a relation. */
 export type AvField<C extends AvContract> = AvScalarField<C> | AvRelationField<C>;

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.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,9 +1,10 @@
 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 { AvOperationResponse } from "../runtime/operation-response.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. */
@@ -131,7 +150,7 @@ 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>;
+type FacadeExecutor = (request: FrameworkOperationRequest, 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

@@ -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 { 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 { 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";

package/dist/internal.d.ts

@@ -32,6 +32,7 @@ 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 { 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";

package/dist/internal.js

@@ -13,6 +13,7 @@ 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 { 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";

package/dist/operations/operation-arguments.d.ts

@@ -335,7 +335,7 @@ type IncludeRelationProjectionEntry<C extends AvContract, K extends AvResourceKe
  * One entry of a `select` argument, at one projection position. The default is
  * the unrestricted position.
  */
-export type AvProjectionEntry<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = SelectableScalarKey<C, K, Scope> | SelectableRelationKey<C, K, Scope> | SelectRelationProjectionEntry<C, K, Scope, Forms> | (AllowCount extends true ? "$count" : never);
+export type AvProjectionEntry<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = SelectableScalarKey<C, K, Scope> | SelectableRelationKey<C, K, Scope> | SelectRelationProjectionEntry<C, K, Scope, Forms> | "$defaults" | (AllowCount extends true ? "$count" : never);
 /** A `select` argument: the fields to return. */
 export type AvSelectInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = readonly AvProjectionEntry<C, K, Scope, AllowCount, Forms>[];
 /** An `include` argument: the relations to return with each row. */

package/dist/operations/operation-call.d.ts

@@ -55,8 +55,10 @@ export type AvOperationGrammar<C extends AvContract> = {
 export type AvOperationSlot<I extends AvOperationIdentity, Result> = I["variant"] extends "first" ? Result | null : Result;
 /** What a direct call resolves: the slot, every failure thrown. */
 type Settled<I extends AvOperationIdentity, Result> = AvOperationSlot<I, Result>;
-type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
-type PlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
+/** A direct call that projects: generic in its `select`/`include` literal. */
+export type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
+/** A direct call that does not project. */
+export type PlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
 /**
  * One direct call: its arguments in `Forms`, its result in `ResultForms`,
  * resolving the slot and throwing every failure, taking `Options` per call. It is generic in its
@@ -68,9 +70,11 @@ export type AvOperationCall<C extends AvContract, R extends AvResourceKey<C>, I
  * `$ref` typed in `ResultForms` — the forms the source's final data is read in, so a
  * reference carries what its source resolves.
  */
-type DeferredArguments<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
-type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
-type DeferredPlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = (...args: ArgumentList<Args, Args>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>, Origin>;
+export type DeferredArguments<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
+/** A deferred operation that projects: generic in its `select`/`include` literal. */
+export type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
+/** A deferred operation that does not project. */
+export type DeferredPlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = (...args: ArgumentList<Args, Args>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>, Origin>;
 /**
  * One deferred operation: a handle typed `AvOperation<AvOperationSlot<…>, Origin>`,
  * with `$ref` present exactly where the result is one row. A handle is not a