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

package/dist/runtime/operation-runtime.js

@@ -3,6 +3,9 @@ import { createComputedFields } from "../config/field-compute.resolver.js";
 import { fieldStagesOf, isForcedOperation, nestedTargetLevels, operationLevels, rawPipelineTree, transactionLevelsOf, } from "../config/pipeline-tree.resolver.js";
 import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
 import { findOperationAvailabilityIssue, validateOperationArguments, } from "../operations/operation-validator.js";
+import { enforceReadPolicy, } from "../policy/policy-read.runtime.js";
+import { admitRequestPolicy, openRequestPolicy, } from "../policy/policy-request.js";
+import { enforceWritePolicy, writeNeedsTransaction, } from "../policy/policy-write.runtime.js";
 import { transactionInfrastructureFailure } from "../transactions/transaction-response.js";
 import { settleTransaction } from "../transactions/transaction-settlement.runtime.js";
 import { TRANSACTION_PIPES, transactionFacts, } from "../transactions/transaction-stage.runtime.js";
@@ -40,6 +43,22 @@ function scopeOf(request, binding) {
 export function withRequestState(request) {
     return { ...request, state: requestStateOf(request.state) };
 }
+export function withRequestPolicy(dependencies, request, caller, report) {
+    const failed = (error) => {
+        report(error, "A3000");
+        return internalFailure();
+    };
+    const withPolicy = (policy) => policy === undefined ? request : { ...request, policy };
+    try {
+        const policy = openRequestPolicy(dependencies.config.policy, dependencies.contracts.core, request, caller, dependencies.adapter);
+        return policy instanceof Promise
+            ? policy.then(withPolicy, failed)
+            : withPolicy(policy);
+    }
+    catch (error) {
+        return failed(error);
+    }
+}
 export function createPipelineDependencies(dependencies, model) {
     const misuse = createMisuseReporter(dependencies.config.misuse);
     const recordWrites = recordWriteFactsOf({
@@ -170,7 +189,7 @@ function outputAccepted(contract, request, projection, data, report) {
 }
 export function createOperationRuntime(dependencies, pipelineDependencies) {
     const misuse = createMisuseReporter(dependencies.config.misuse);
-    return async (request, report, source) => {
+    return async (request, report, source, caller) => {
         let validated;
         try {
             validated = validateOperation(dependencies, request, source, misuse);
@@ -184,7 +203,11 @@ export function createOperationRuntime(dependencies, pipelineDependencies) {
         if (!validated.ok) {
             return validated.response;
         }
-        const stateful = withRequestState(request);
+        const opened = withRequestPolicy(dependencies, withRequestState(request), caller, report);
+        const stateful = opened instanceof Promise ? await opened : opened;
+        if (!("state" in stateful)) {
+            return stateful;
+        }
         const forced = isForcedOperation(activeScopeConfig(dependencies.config, request).pipelines, request);
         const admitted = await admitOperation(pipelineDependencies, stateful, validated.contract, validated.arguments, OPERATION_ARGUMENTS_PATH, report, {
             requestId: request.requestId,
@@ -194,8 +217,20 @@ export function createOperationRuntime(dependencies, pipelineDependencies) {
         if (!admitted.ok) {
             return admitted.response;
         }
-        if (forced) {
-            return executeForcedOperation(pipelineDependencies, dependencies.adapter, stateful, validated.contract, admitted.args, report);
+        let checkedWrite = false;
+        if (stateful.policy !== undefined &&
+            request.family !== "find" &&
+            validated.contract.transactions === "interactive" &&
+            !forced) {
+            try {
+                checkedWrite = await writeNeedsTransaction(stateful.policy, dependencies.contracts.core, stateful, () => planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, validated.contract, activeScopeConfig(dependencies.config, request).compute, stateful, admitted.args), admitted.args);
+            }
+            catch (error) {
+                return sanitizeOperationFailure(error, stateful.policy.execution.boundary.originOf(error), report, { path: OPERATION_ARGUMENTS_PATH, arguments: admitted.args });
+            }
+        }
+        if (forced || checkedWrite) {
+            return executeForcedOperation(pipelineDependencies, dependencies.adapter, stateful, validated.contract, admitted.args, report, forced);
         }
         return executeAdmittedOperation(pipelineDependencies, stateful, validated.contract, admitted.args, OPERATION_ARGUMENTS_PATH, { kind: "standalone", executor: dependencies.adapter }, report);
     };
@@ -346,6 +381,12 @@ export async function admitOperation(dependencies, request, contract, args, argu
     if (absent.length > 0) {
         return { ok: false, response: mapValidationOutcome(absent) };
     }
+    if (request.policy !== undefined) {
+        const refused = await admitRequestPolicy(request.policy, dependencies.contracts.core, contract, request, current, report, { path: argumentsPath, arguments: current });
+        if (refused !== undefined) {
+            return { ok: false, response: refused };
+        }
+    }
     try {
         return await admit();
     }
@@ -441,7 +482,7 @@ export async function prepareStep(dependencies, request, contract, args, argumen
         };
     }
 }
-async function executeForcedOperation(dependencies, adapter, request, contract, args, report) {
+async function executeForcedOperation(dependencies, adapter, request, contract, args, report, forced) {
     const plan = [
         {
             resource: request.resource,
@@ -452,7 +493,9 @@ async function executeForcedOperation(dependencies, adapter, request, contract,
     ];
     const settled = await settleTransaction({
         adapter,
-        levels: transactionLevelsOf(activeScopeConfig(dependencies.config, request).pipelines, request.resource),
+        levels: forced
+            ? transactionLevelsOf(activeScopeConfig(dependencies.config, request).pipelines, request.resource)
+            : [],
         plan,
         contextOf: (current, executor) => dependencies.contexts.transaction({
             requestId: request.requestId,
@@ -544,6 +587,25 @@ export async function executeAdmittedOperation(dependencies, request, contract,
             throw hiddenRefusal;
         }
         args = deepFreeze(computed);
+        let policyWrite;
+        if (request.policy !== undefined && request.family !== "find") {
+            const planned = planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, scopeConfig.compute, request, args);
+            const plannedArguments = await stripVirtualMutationInput(contracts, request, planned.arguments);
+            try {
+                policyWrite = await enforceWritePolicy(request.policy.on({ executor, boundary: adapterBoundary }), dependencies.contracts.core, dependencies.config.adapter.model, request, planned, plannedArguments, binding.kind === "transaction");
+            }
+            catch (error) {
+                return sanitizeOperationFailure(error, adapterBoundary.originOf(error), report, { path: argumentsPath, arguments: args });
+            }
+            if (policyWrite.kind === "refused") {
+                return policyWrite.response;
+            }
+        }
+        let policyFailure;
+        const refuseWrite = (response) => {
+            policyFailure = response;
+            throw thrownFailure(response);
+        };
         let readMaterialized = false;
         let executedReadPlan;
         const materialize = async (data, plan) => {
@@ -552,24 +614,87 @@ export async function executeAdmittedOperation(dependencies, request, contract,
             return materializeReadOperation(contract, scopeConfig.compute, request, plan, data, computeContext);
         };
         const invoke = async () => {
-            const readPlan = planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, scopeConfig.compute, request, args);
-            const adapterArguments = await stripVirtualMutationInput(contracts, request, readPlan.arguments);
-            const identity = request;
-            const adapterData = await adapterBoundary.execute(() => executor.execute({
-                ...identity,
-                resource: request.resource,
-                arguments: adapterArguments,
-            }));
+            let readPlan = planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, scopeConfig.compute, request, args);
+            let adapterArguments = await stripVirtualMutationInput(contracts, request, readPlan.arguments);
+            let operation = request;
+            let settle;
+            let writeMiss;
+            let failedWriteMiss;
+            if (policyWrite !== undefined && policyWrite.kind !== "refused") {
+                writeMiss = policyWrite.miss;
+                failedWriteMiss = policyWrite.failedMiss;
+                if (policyWrite.kind === "empty") {
+                    if (writeMiss !== undefined && policyWrite.data === null) {
+                        refuseWrite(await writeMiss());
+                    }
+                    return materialize(policyWrite.data, readPlan);
+                }
+                operation = policyWrite.identity;
+                adapterArguments = policyWrite.arguments;
+                readPlan = policyWrite.plan;
+                settle = policyWrite.settle;
+            }
+            else if (request.policy !== undefined && request.family === "find") {
+                const read = await enforceReadPolicy(request.policy.on({ executor, boundary: adapterBoundary }), dependencies.contracts.core, dependencies.config.adapter.model, request, readPlan, adapterArguments);
+                if (read.kind === "refused") {
+                    throw thrownFailure(read.response);
+                }
+                if (read.kind === "empty") {
+                    const miss = uniqueMissFailure(request, read.data);
+                    if (miss !== undefined) {
+                        throw thrownFailure(miss);
+                    }
+                    return materialize(read.data, readPlan);
+                }
+                operation = read.identity;
+                adapterArguments = read.arguments;
+                readPlan = read.plan;
+                settle = read.settle;
+            }
+            const { policy: _session, ...identity } = operation;
+            let adapterData;
+            try {
+                adapterData = await adapterBoundary.execute(() => executor.execute({
+                    ...identity,
+                    resource: request.resource,
+                    arguments: adapterArguments,
+                }));
+            }
+            catch (error) {
+                const missed = failedWriteMiss === undefined
+                    ? undefined
+                    : await failedWriteMiss().catch(() => undefined);
+                if (missed !== undefined) {
+                    refuseWrite(missed);
+                }
+                throw error;
+            }
+            if (writeMiss !== undefined && adapterData === null) {
+                refuseWrite(await writeMiss());
+            }
             const miss = uniqueMissFailure(request, adapterData);
             if (miss !== undefined) {
                 throw thrownFailure(miss);
             }
+            if (settle !== undefined) {
+                const settled = await settle(adapterData);
+                if (!settled.ok) {
+                    if (policyWrite !== undefined) {
+                        refuseWrite(settled.response);
+                    }
+                    throw thrownFailure(settled.response);
+                }
+                adapterData = settled.data;
+            }
             return materialize(adapterData, readPlan);
         };
         const materialized = async (data) => readMaterialized
             ? data
             : materialize(data, planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, scopeConfig.compute, request, args));
         const data = await materialized(await runLevelLifecycle(levels, context, invoke, materialized, reuse, () => new AvInterceptorNextError()));
+        if (policyFailure !== undefined) {
+            return policyFailure;
+        }
         if (!outputAccepted(contract, request, executedReadPlan?.projection, data, report)) {
             return internalFailure();
         }

package/dist/runtime/owned-execution.registry.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTransactionRequest, ClientTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvAgentTransactionRequest, AvClientTransactionRequest } from "../transactions/transaction-request.js";
 import type { AvTransactionResponse } from "../transactions/transaction-response.js";
 import type { AvCallerDataError } from "./caller-data.copier.js";
 import type { RemoteOperationRequest } from "./operation-request.js";
@@ -15,7 +15,7 @@ export type OwnedExecution = {
      * at the call, and these steps' arguments could not be copied there: each is
      * answered at its turn as the door answers that failure.
      */
-    readonly executeTransaction: (request: ClientTransactionRequest | AgentTransactionRequest, refused?: ReadonlyMap<number, AvCallerDataError>) => Promise<AvTransactionResponse>;
+    readonly executeTransaction: (request: AvClientTransactionRequest | AvAgentTransactionRequest, refused?: ReadonlyMap<number, AvCallerDataError>) => Promise<AvTransactionResponse>;
 };
 /** Records `framework`'s owned entries; called once, at construction. */
 export declare function recordOwnedExecution(framework: object, execution: OwnedExecution): void;

package/dist/runtime/readonly-value.d.ts

@@ -32,8 +32,12 @@ export declare function deepFreeze<T>(value: T): T;
  * only reads is told — the validated arguments after validation, a result in an
  * after hook — so neither what is written nor the result the caller receives can
  * be changed through it.
+ *
+ * With `snapshot`, a copied container found to hold no `Date` or `Uint8Array`
+ * is remembered as such at once, so a later `frozenCopy` of the copy shares it
+ * without walking it: for a copy that is itself copied again for each stage.
  */
-export declare function frozenCopy<T>(value: T): AvDeepReadonly<T>;
+export declare function frozenCopy<T>(value: T, snapshot?: boolean): AvDeepReadonly<T>;
 /**
  * A read-only view of `value`: reads see the live value, nested plain objects
  * and arrays as views too, and any write, definition or deletion throws a

package/dist/runtime/readonly-value.js

@@ -37,38 +37,79 @@ function scalarCopy(value) {
     return undefined;
 }
 const SCALAR_FREE = new WeakSet();
-export function frozenCopy(value) {
+function scalarFree(value) {
+    return Object.isFrozen(value) && SCALAR_FREE.has(value);
+}
+const WALKING = Symbol("walking");
+function place(target, key, value, enumerable) {
+    if (enumerable && typeof key === "string" && !(key in target)) {
+        target[key] = value;
+        return;
+    }
+    Object.defineProperty(target, key, {
+        value,
+        enumerable,
+        writable: true,
+        configurable: true,
+    });
+}
+export function frozenCopy(value, snapshot = false) {
+    const scalar = scalarCopy(value);
+    if (scalar !== undefined) {
+        return scalar;
+    }
+    if (!isContainer(value) || scalarFree(value)) {
+        return value;
+    }
     const copies = new Map();
-    const walking = new Set();
     let cycled = false;
+    let holdsScalar = false;
     const copy = (current) => {
+        if (current === null || typeof current !== "object") {
+            return current;
+        }
         const scalar = scalarCopy(current);
         if (scalar !== undefined) {
+            holdsScalar = true;
             return scalar;
         }
-        if (!isContainer(current) || SCALAR_FREE.has(current)) {
+        if (!isContainer(current) || scalarFree(current)) {
             return current;
         }
-        if (copies.has(current)) {
-            cycled ||= walking.has(current);
-            return copies.get(current);
+        const known = copies.get(current);
+        if (known === WALKING) {
+            cycled = true;
+            return current;
+        }
+        if (known !== undefined) {
+            holdsScalar ||= !scalarFree(known);
+            return known;
         }
-        copies.set(current, current);
-        walking.add(current);
-        const entries = [];
-        let changed = !DEEP_FROZEN.has(current);
+        copies.set(current, WALKING);
+        const outer = holdsScalar;
+        holdsScalar = false;
+        let changed = !(Object.isFrozen(current) && DEEP_FROZEN.has(current));
+        const array = Array.isArray(current);
+        const prototype = Object.getPrototypeOf(current);
+        const target = array
+            ? new Array(current.length)
+            : prototype === Object.prototype
+                ? {}
+                : Object.create(prototype);
         for (const key of Reflect.ownKeys(current)) {
+            if (array && key === "length") {
+                continue;
+            }
             const descriptor = Object.getOwnPropertyDescriptor(current, key);
-            if (descriptor === undefined ||
-                !("value" in descriptor) ||
-                (Array.isArray(current) && key === "length")) {
+            if (descriptor === undefined || !("value" in descriptor)) {
                 continue;
             }
             const next = copy(descriptor.value);
             changed ||= next !== descriptor.value;
-            entries.push([key, descriptor, next]);
+            place(target, key, next, descriptor.enumerable === true);
         }
-        walking.delete(current);
+        const held = holdsScalar;
+        holdsScalar = outer || held;
         if (!changed) {
             copies.set(current, current);
             if (!cycled) {
@@ -76,20 +117,18 @@ export function frozenCopy(value) {
             }
             return current;
         }
-        const target = Array.isArray(current)
-            ? new Array(current.length)
-            : Object.create(Object.getPrototypeOf(current));
-        for (const [key, descriptor, next] of entries) {
-            Object.defineProperty(target, key, {
-                value: next,
-                enumerable: descriptor.enumerable ?? false,
-                writable: true,
-                configurable: true,
-            });
+        Object.freeze(target);
+        DEEP_FROZEN.add(target);
+        if (cycled) {
+            for (const key of Reflect.ownKeys(target)) {
+                deepFreeze(target[key]);
+            }
+        }
+        if (snapshot && !held && !cycled) {
+            SCALAR_FREE.add(target);
         }
-        const frozen = deepFreeze(target);
-        copies.set(current, frozen);
-        return frozen;
+        copies.set(current, target);
+        return target;
     };
     return copy(value);
 }

package/dist/runtime/referential-action.d.ts

@@ -29,7 +29,7 @@ export type ReferentialEdge = {
      * relation `field` and any of these names the reference twice and is refused;
      * a required relation may be written through all of them instead.
      */
-    readonly references: readonly string[];
+    readonly referenceFields: readonly string[];
     /** What deleting a `target` row does to rows of the ENCLOSING Resource. */
     readonly onDelete: ReferentialDeleteEffect;
 };

package/dist/transactions/sql-statement.d.ts

@@ -10,7 +10,7 @@ import type { AvTransactionReference } from "./transaction-reference.js";
  * `${value}::jsonb`), or a `$ref` to an earlier step's field, resolved when the
  * earlier steps have run and then bound like any other value.
  */
-export type SqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
+export type AvSqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
 /**
  * `framework.appTx.$sql`: a developer SQL step, written only as a tagged template —
  * ``framework.appTx.$sql`select pgmq.send('jobs', jsonb_build_object('id', ${ref}))` ``.
@@ -23,7 +23,7 @@ export type SqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
  * SQL step's rows. No guard, pipe, hook, interceptor or filter runs around it: it
  * has no Resource or operation for one to wrap.
  */
-export type SqlStatementBuilder = <Row = unknown>(strings: TemplateStringsArray, ...values: readonly SqlStatementValue[]) => AvOperation<Row[], "application">;
+export type AvSqlStatementBuilder = <Row = unknown>(strings: TemplateStringsArray, ...values: readonly AvSqlStatementValue[]) => AvOperation<Row[], "application">;
 /** One value of a planned SQL step, as the typed runner bound it. */
 export type PlannedSqlValue = {
     readonly kind: "value";

package/dist/transactions/transaction-plan-assembler.d.ts

@@ -2,7 +2,7 @@ import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import { AvCallerDataError } from "../runtime/caller-data.copier.js";
 import type { MisuseReporter } from "../runtime/misuse-reporter.js";
-import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.js";
 import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
 import type { AvOperation, OperationFingerprint } from "./deferred-operation.js";
 import type { PlannedSqlStatement } from "./sql-statement.js";
@@ -49,5 +49,5 @@ export type TransactionPlanAssembler = {
  * handle, so a handle another instance built — typed against another model,
  * bound to other Contracts — is refused rather than run.
  */
-export declare function createTransactionPlanAssembler(contracts: AvContracts, protocol: ClientProtocolIdentity, misuse: MisuseReporter): TransactionPlanAssembler;
+export declare function createTransactionPlanAssembler(contracts: AvContracts, protocol: AvRequestProtocol, misuse: MisuseReporter): TransactionPlanAssembler;
 export {};

package/dist/transactions/transaction-plan-validator.d.ts

@@ -4,7 +4,7 @@ import type { AvScalarField } from "../contracts/field.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
 import { AvCallerDataError } from "../runtime/caller-data.copier.js";
 import { type ReadProjectionPlan } from "../runtime/computed-read-runtime.js";
-import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
+import type { AvOperationRequest } from "../runtime/operation-request.js";
 import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
 import type { OperationPipelineDependencies } from "../runtime/operation-runtime.js";
 import type { CascadeClosure } from "../runtime/referential-action.js";
@@ -13,7 +13,7 @@ import type { PlannedSqlStatement, ValidatedSqlStatement } from "./sql-statement
 import type { AvTransactionReference } from "./transaction-reference.js";
 import { type TransactionSlotShape } from "./transaction-reference.js";
 import { type TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
-import type { FrameworkTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
+import type { AvTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
 /**
  * Where a plan's step arguments came from, so the validator knows whether to copy
  * them at the door (see `ArgumentsSource`):
@@ -65,7 +65,7 @@ export type TransactionReferenceSlot = {
 };
 export type CandidateTransactionOperation = {
     readonly index: number;
-    readonly request: FrameworkOperationRequest;
+    readonly request: AvOperationRequest;
     readonly arguments: SemanticOperationArguments;
     readonly projection: ReadProjectionPlan | undefined;
     readonly declaredFingerprint: unknown;
@@ -74,7 +74,7 @@ export type CandidateTransactionOperation = {
 export type ValidatedTransactionOperation = {
     readonly kind: "operation";
     readonly index: number;
-    readonly request: FrameworkOperationRequest;
+    readonly request: AvOperationRequest;
     /**
      * The Contract of this operation's origin, which is the plan's: the one it was
      * validated against, the one it runs under, and the one a later `$ref` reads its
@@ -118,4 +118,4 @@ export declare function transactionsUnavailableFailure(): AvOperationFailureResp
 /**
  * Whole-plan Framework Validation Layer for transaction structure and identity.
  */
-export declare function validateTransactionPlan<M extends AvAdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;
+export declare function validateTransactionPlan<M extends AvAdapterModel>(dependencies: TransactionPlanDependencies<M>, request: AvTransactionRequest, origins?: readonly TransactionOperationOrigin[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;

package/dist/transactions/transaction-request.d.ts

@@ -1,4 +1,4 @@
-import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.js";
 import type { AvTransportContext } from "../runtime/pipeline.js";
 import type { AvState } from "../runtime/request-state.js";
 type TransactionRequestBase = {
@@ -11,29 +11,29 @@ type TransactionRequestBase = {
     readonly state?: AvState;
 };
 /** An in-process transaction request, run under the Application Contract. */
-export type ApplicationTransactionRequest = TransactionRequestBase & {
+export type AvApplicationTransactionRequest = TransactionRequestBase & {
     readonly origin: "application";
     readonly protocol?: never;
     readonly transport?: never;
 };
 /** A remote transaction request, run under the Client Contract. */
-export type ClientTransactionRequest = TransactionRequestBase & {
+export type AvClientTransactionRequest = TransactionRequestBase & {
     readonly origin: "client";
-    readonly protocol: ClientProtocolIdentity;
+    readonly protocol: AvRequestProtocol;
     readonly transport?: AvTransportContext;
 };
 /** An AI agent's transaction request, run under the Agent Contract. */
-export type AgentTransactionRequest = TransactionRequestBase & {
+export type AvAgentTransactionRequest = TransactionRequestBase & {
     readonly origin: "agent";
-    readonly protocol: ClientProtocolIdentity;
+    readonly protocol: AvRequestProtocol;
     readonly transport?: AvTransportContext;
 };
 /** One transaction request, as `framework.executeTransaction` takes it. */
-export type FrameworkTransactionRequest = ApplicationTransactionRequest | ClientTransactionRequest | AgentTransactionRequest;
+export type AvTransactionRequest = AvApplicationTransactionRequest | AvClientTransactionRequest | AvAgentTransactionRequest;
 /**
  * The origin one plan operation runs under: its own layer's Contract, its own
  * pipelines, and — for a client or agent step — the protocol identity it is
  * accepted with.
  */
-export type TransactionOperationOrigin = Pick<ApplicationTransactionRequest, "origin"> | Pick<ClientTransactionRequest, "origin" | "protocol" | "transport"> | Pick<AgentTransactionRequest, "origin" | "protocol" | "transport">;
+export type TransactionOperationOrigin = Pick<AvApplicationTransactionRequest, "origin"> | Pick<AvClientTransactionRequest, "origin" | "protocol" | "transport"> | Pick<AvAgentTransactionRequest, "origin" | "protocol" | "transport">;
 export {};

package/dist/transactions/transaction-runtime.d.ts

@@ -1,8 +1,9 @@
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import { type PolicyCaller } from "../policy/policy-request.js";
 import type { TransactionDiagnosticsChannel } from "../runtime/diagnostics-reporter.js";
 import type { OperationPipelineDependencies, OperationRuntimeDependencies } from "../runtime/operation-runtime.js";
 import type { PlanArguments } from "./transaction-plan-validator.js";
-import type { FrameworkTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
+import type { AvTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
 import type { AvTransactionResponse } from "./transaction-response.js";
 /**
  * The transaction executor core. Like the operation executor it owns no
@@ -13,7 +14,9 @@ import type { AvTransactionResponse } from "./transaction-response.js";
  * runner's mixed plans), and `planArguments` whether the steps' arguments are
  * copied at the door; see `validateTransactionPlan`.
  */
-export type FrameworkTransactionExecutor = (request: FrameworkTransactionRequest, diagnostics: TransactionDiagnosticsChannel, origins: readonly TransactionOperationOrigin[] | undefined, planArguments: PlanArguments) => Promise<AvTransactionResponse>;
+export type FrameworkTransactionExecutor = (request: AvTransactionRequest, diagnostics: TransactionDiagnosticsChannel, origins: readonly TransactionOperationOrigin[] | undefined, planArguments: PlanArguments, 
+/** The principal an application run's steps run as (`{ as }`), when it names one. */
+caller?: PolicyCaller) => Promise<AvTransactionResponse>;
 /**
  * Validates a whole plan through the Framework Validation Layer, then runs it inside
  * exactly one Adapter transaction. The touched Resources' transaction stages and

package/dist/transactions/transaction-runtime.js

@@ -1,4 +1,5 @@
 import { transactionLevelsOf } from "../config/pipeline-tree.resolver.js";
+import { openRequestPolicy, } from "../policy/policy-request.js";
 import { AdapterBoundary, planOperationArgumentsPath, planStepPath, sanitizeOperationFailure, } from "../runtime/error-boundary.js";
 import { internalFailure, operationSuccess, } from "../runtime/operation-response.js";
 import { admitOperation, EVERY_FIELD, executeAdmittedOperation, prepareStep, STEP_PIPES, withRequestState, } from "../runtime/operation-runtime.js";
@@ -20,13 +21,13 @@ export function createTransactionRuntime(dependencies, pipelineDependencies) {
         cascades: resolveCascadeClosure(adapter.referentialActions),
         sqlStatements: adapter.sqlStatements === true,
     };
-    return async (seeded, diagnostics, origins, planArguments) => {
+    return async (seeded, diagnostics, origins, planArguments, caller) => {
         const request = withRequestState(seeded);
         const validation = await validateTransactionPlan(planDependencies, request, origins, planArguments);
         if (!validation.ok) {
             return validation.response;
         }
-        return executeTransactionPlan(adapter, pipelineDependencies, request, validation.plan, request.state, diagnostics);
+        return executeTransactionPlan(dependencies, pipelineDependencies, request, validation.plan, request.state, diagnostics, caller);
     };
 }
 function planOrigin(request, plan) {
@@ -79,8 +80,24 @@ function standingReferences(core, operation, args, steps, subject) {
     }
     return { ok: false, ...refused };
 }
-async function executeTransactionPlan(adapter, dependencies, request, plan, state, diagnostics) {
-    const stateful = (operation) => ({ ...operation.request, state });
+async function executeTransactionPlan(runtime, dependencies, request, plan, state, diagnostics, caller) {
+    const { adapter } = runtime;
+    const steps = new Map();
+    const stateful = (operation) => {
+        const known = steps.get(operation);
+        if (known !== undefined) {
+            return known;
+        }
+        const settle = (policy) => {
+            const step = policy === undefined
+                ? { ...operation.request, state }
+                : { ...operation.request, state, policy };
+            steps.set(operation, step);
+            return step;
+        };
+        const policy = openRequestPolicy(runtime.config.policy, runtime.contracts.core, { origin: operation.request.origin, state }, caller, adapter);
+        return policy instanceof Promise ? policy.then(settle) : settle(policy);
+    };
     const admitted = [];
     const standing = [];
     for (const step of plan.operations) {
@@ -90,7 +107,16 @@ async function executeTransactionPlan(adapter, dependencies, request, plan, stat
             continue;
         }
         const report = diagnostics.operation(step.request, step.index);
-        const admission = await admitOperation(dependencies, stateful(step), step.contract, step.arguments, planOperationArgumentsPath(step.index), report, { requestId: request.requestId, transaction: undefined, state }, {
+        let stepRequest;
+        try {
+            const opened = stateful(step);
+            stepRequest = opened instanceof Promise ? await opened : opened;
+        }
+        catch (error) {
+            report(error, "A3000");
+            return transactionOperationFailure(internalFailure(), step.index);
+        }
+        const admission = await admitOperation(dependencies, stepRequest, step.contract, step.arguments, planOperationArgumentsPath(step.index), report, { requestId: request.requestId, transaction: undefined, state }, {
             select: EVERY_FIELD,
             validation: { transactionReferences: true },
             beforeBegin: true,
@@ -118,7 +144,8 @@ async function executeTransactionPlan(adapter, dependencies, request, plan, stat
     const runPlanOperation = async (operation, args, transactionPiped, executor, results, outer) => {
         const report = diagnostics.operation(operation.request, operation.index);
         const argumentsPath = planOperationArgumentsPath(operation.index);
-        const stepRequest = stateful(operation);
+        const opened = stateful(operation);
+        const stepRequest = opened instanceof Promise ? await opened : opened;
         try {
             let live = standing[operation.index] ?? operation.references;
             if (transactionPiped) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/core",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.8",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "node ../../scripts/build/build-output.cleaner.ts dist && tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist && node scripts/errors-markdown.generator.ts",
+    "build": "node ../../scripts/build/build-output.cleaner.ts dist && node scripts/core-version.generator.ts && tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist && node scripts/errors-markdown.generator.ts",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
     "lint": "biome lint src scripts"