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

package/dist/runtime/operation-runtime.d.ts

@@ -8,14 +8,14 @@ import type { AvRequestOrigin, RemoteRequestOrigin } from "../config/config-laye
 import type { AvContract } from "../contracts/contract.js";
 import type { OperationValidationOptions, SemanticOperationArguments } from "../operations/operation-validator.js";
 import { type PolicyCaller } from "../policy/policy-request.js";
-import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvTransactionRequest } from "../transactions/transaction-request.js";
 import { type ArgumentsSource } from "./caller-data.door.js";
 import { type ContextExecutor, type ExecutorScope } from "./context-executor.runtime.js";
 import { type RecordWriteFacts } from "./create-requirement.js";
 import { type DiagnosticsReporter } from "./diagnostics-reporter.js";
 import { type OuterFailureLayer } from "./error-boundary.js";
 import { type FieldStagePlan } from "./field-stage.plan.js";
-import type { ClientProtocolIdentity, FrameworkOperationRequest, StatefulOperationRequest } from "./operation-request.js";
+import type { AvOperationRequest, AvRequestProtocol, StatefulOperationRequest } from "./operation-request.js";
 import type { AvOperationFailureResponse, AvOperationResponse } from "./operation-response.js";
 import type { AvState } from "./request-state.js";
 import { type NormalizationWrite } from "./scalar-runtime.js";
@@ -70,7 +70,7 @@ export declare function withRequestState<Request extends {
  * `request` with its policy session when the policy checks it, or the failure
  * deriving its principal answered.
  */
-export declare function withRequestPolicy<M extends AvAdapterModel>(dependencies: Pick<OperationRuntimeDependencies<M>, "adapter" | "config" | "contracts">, request: StatefulOperationRequest, caller: PolicyCaller | undefined, report: DiagnosticsReporter): StatefulOperationRequest | AvOperationFailureResponse;
+export declare function withRequestPolicy<M extends AvAdapterModel>(dependencies: Pick<OperationRuntimeDependencies<M>, "adapter" | "config" | "contracts">, request: StatefulOperationRequest, caller: PolicyCaller | undefined, report: DiagnosticsReporter): StatefulOperationRequest | AvOperationFailureResponse | Promise<StatefulOperationRequest | AvOperationFailureResponse>;
 /**
  * Builds what every operation's pipeline shares, the ctx executor included: its
  * raw calls run the application's operation path with every developer stage
@@ -85,15 +85,15 @@ export declare function createPipelineDependencies<M extends AvAdapterModel>(dep
  * request's arguments are the caller's own objects, copied at the door, or data
  * no caller holds (see {@link ArgumentsSource}).
  */
-export type FrameworkOperationExecutor = (request: FrameworkOperationRequest, report: DiagnosticsReporter, source: ArgumentsSource, 
+export type FrameworkOperationExecutor = (request: AvOperationRequest, report: DiagnosticsReporter, source: ArgumentsSource, 
 /** The principal an application call runs as (`{ as }`), when it names one. */
 caller?: PolicyCaller) => Promise<AvOperationResponse>;
 /** Selects the Contract of the request's origin. */
-export declare function activeContract(contracts: AvContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): AvContract;
+export declare function activeContract(contracts: AvContracts, request: AvOperationRequest | AvTransactionRequest): AvContract;
 /** Creates the transport-independent operation executor owned by core. */
 export declare function createOperationRuntime<M extends AvAdapterModel>(dependencies: OperationRuntimeDependencies<M>, pipelineDependencies: OperationPipelineDependencies<M>): FrameworkOperationExecutor;
 /** Validates the request-level protocol identity. */
-export declare function validateProtocolIdentity(contracts: AvContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): AvOperationFailureResponse | undefined;
+export declare function validateProtocolIdentity(contracts: AvContracts, request: AvOperationRequest | AvTransactionRequest): AvOperationFailureResponse | undefined;
 /**
  * The stale-client check on one remote protocol identity: the protocol version first
  * (`A2006`), then the hash of the origin's Contract (`A2005`): the ClientContract's
@@ -102,7 +102,7 @@ export declare function validateProtocolIdentity(contracts: AvContracts, request
  * (`@aventara/core/protocol`) call it too, so a stale client hears the same envelope
  * whichever layer answers.
  */
-export declare function protocolIdentityFailure(contracts: AvContracts, protocol: ClientProtocolIdentity, origin: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
+export declare function protocolIdentityFailure(contracts: AvContracts, protocol: AvRequestProtocol, origin: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
 export type ValidatedOperationArguments = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
@@ -111,7 +111,7 @@ export type ValidatedOperationArguments = {
     readonly response: AvOperationFailureResponse;
 };
 /** Validates one operation's arguments through the Framework Validation Layer. */
-export declare function validateOperationRequest(contract: AvContract, request: FrameworkOperationRequest, options?: OperationValidationOptions, write?: NormalizationWrite): ValidatedOperationArguments;
+export declare function validateOperationRequest(contract: AvContract, request: AvOperationRequest, options?: OperationValidationOptions, write?: NormalizationWrite): ValidatedOperationArguments;
 /** The subject a refused output of an operation's pipes is reported under at a plan step. */
 export declare const STEP_PIPES = "Pipes";
 /**

package/dist/runtime/operation-runtime.js

@@ -44,13 +44,19 @@ 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 === undefined ? request : { ...request, policy };
+        return policy instanceof Promise
+            ? policy.then(withPolicy, failed)
+            : withPolicy(policy);
     }
     catch (error) {
-        report(error, "A3000");
-        return internalFailure();
+        return failed(error);
     }
 }
 export function createPipelineDependencies(dependencies, model) {
@@ -197,7 +203,8 @@ export function createOperationRuntime(dependencies, pipelineDependencies) {
         if (!validated.ok) {
             return validated.response;
         }
-        const stateful = withRequestPolicy(dependencies, withRequestState(request), caller, report);
+        const opened = withRequestPolicy(dependencies, withRequestState(request), caller, report);
+        const stateful = opened instanceof Promise ? await opened : opened;
         if (!("state" in stateful)) {
             return stateful;
         }
@@ -612,8 +619,10 @@ export async function executeAdmittedOperation(dependencies, request, contract,
             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());
@@ -643,11 +652,23 @@ export async function executeAdmittedOperation(dependencies, request, contract,
                 settle = read.settle;
             }
             const { policy: _session, ...identity } = operation;
-            let adapterData = await adapterBoundary.execute(() => executor.execute({
-                ...identity,
-                resource: request.resource,
-                arguments: adapterArguments,
-            }));
+            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());
             }

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/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

@@ -3,7 +3,7 @@ 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
@@ -14,7 +14,7 @@ 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, 
+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>;
 /**

package/dist/transactions/transaction-runtime.js

@@ -88,12 +88,15 @@ async function executeTransactionPlan(runtime, dependencies, request, plan, stat
         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);
-        const step = policy === undefined
-            ? { ...operation.request, state }
-            : { ...operation.request, state, policy };
-        steps.set(operation, step);
-        return step;
+        return policy instanceof Promise ? policy.then(settle) : settle(policy);
     };
     const admitted = [];
     const standing = [];
@@ -106,7 +109,8 @@ async function executeTransactionPlan(runtime, dependencies, request, plan, stat
         const report = diagnostics.operation(step.request, step.index);
         let stepRequest;
         try {
-            stepRequest = stateful(step);
+            const opened = stateful(step);
+            stepRequest = opened instanceof Promise ? await opened : opened;
         }
         catch (error) {
             report(error, "A3000");
@@ -140,7 +144,8 @@ async function executeTransactionPlan(runtime, 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.4",
+  "version": "1.0.0-rc.8",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",