@aventara/core 1.0.0-rc.0 → 1.0.0-rc.1

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

@@ -1,20 +1,26 @@
-import type { Adapter } from "../adapters/adapter.interface.js";
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { AdapterOperationExecutor } from "../adapters/adapter-operation-executor.interface.js";
-import type { FrameworkContracts } from "../compiler/contract.compiler.js";
+import type { AvAdapter } from "../adapters/adapter.interface.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterOperationExecutor } from "../adapters/adapter-operation-executor.interface.js";
+import type { AvAdapterTransactionExecutor } from "../adapters/adapter-transaction-executor.interface.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { ResolvedFrameworkConfig } from "../config/config.resolver.js";
-import type { Contract } from "../contracts/contract.js";
+import type { AvRequestOrigin, RemoteRequestOrigin } from "../config/config-layer.js";
+import type { AvContract } from "../contracts/contract.js";
 import type { OperationValidationOptions, SemanticOperationArguments } from "../operations/operation-validator.js";
 import type { FrameworkTransactionRequest } 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 { ClientProtocolIdentity, FrameworkOperationRequest, OperationExecutionRequest } from "./operation-request.js";
-import type { OperationFailureResponse, OperationResponse } from "./operation-response.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 { AvOperationFailureResponse, AvOperationResponse } from "./operation-response.js";
+import type { AvState } from "./request-state.js";
 import { type NormalizationWrite } from "./scalar-runtime.js";
-export type OperationRuntimeDependencies<M extends AdapterModel> = {
-    readonly adapter: Adapter<M>;
-    readonly contracts: FrameworkContracts;
+export type OperationRuntimeDependencies<M extends AvAdapterModel> = {
+    readonly adapter: AvAdapter<M>;
+    readonly contracts: AvContracts;
     readonly config: ResolvedFrameworkConfig<M>;
 };
 /**
@@ -22,13 +28,49 @@ export type OperationRuntimeDependencies<M extends AdapterModel> = {
  * single Adapter call goes through the executor passed beside it, so inside a
  * transaction plan the root Adapter is unreachable by type.
  */
-export type OperationPipelineDependencies<M extends AdapterModel> = Omit<OperationRuntimeDependencies<M>, "adapter"> & {
+export type OperationPipelineDependencies<M extends AvAdapterModel> = Omit<OperationRuntimeDependencies<M>, "adapter"> & {
     /**
      * The Adapter's create requirements and referential edges, read once at
      * construction.
      */
     readonly recordWrites: RecordWriteFacts;
+    /** Builds every stage's ctx: its `$` facts and the executor. */
+    readonly contexts: ContextExecutor<M>;
+    /** Each origin's field-stage dispatch, planned at construction. */
+    readonly fieldStages: {
+        readonly [O in AvRequestOrigin]: FieldStagePlan;
+    };
 };
+/**
+ * Where one operation's Adapter call runs: standalone, through the Adapter, or
+ * inside an open transaction, through its executor.
+ */
+export type OperationBinding<M extends AvAdapterModel> = {
+    readonly kind: "standalone";
+    readonly executor: AvAdapterOperationExecutor<M>;
+} | {
+    readonly kind: "transaction";
+    readonly executor: AvAdapterTransactionExecutor<M>;
+    /**
+     * A plan step's (or a forced call's) Resource transaction filters: the
+     * outer layer an error the step's own filters leave unhandled is handed
+     * to, answered once the transaction interceptors have unwound (the rc.1
+     * follow-up ruling; the independent re-check). Absent for a ctx call.
+     */
+    readonly outer?: OuterFailureLayer;
+};
+/** `request` with its state settled. */
+export declare function withRequestState<Request extends {
+    readonly state?: AvState;
+}>(request: Request): Request & {
+    readonly state: AvState;
+};
+/**
+ * Builds what every operation's pipeline shares, the ctx executor included: its
+ * raw calls run the application's operation path with every developer stage
+ * removed.
+ */
+export declare function createPipelineDependencies<M extends AvAdapterModel>(dependencies: OperationRuntimeDependencies<M>, model: M): OperationPipelineDependencies<M>;
 /**
  * The executor core owns no diagnostics channel: the framework factory owns
  * it and hands in one reporter already bound to this request, so every
@@ -37,33 +79,79 @@ export type OperationPipelineDependencies<M extends AdapterModel> = Omit<Operati
  * 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) => Promise<OperationResponse>;
+export type FrameworkOperationExecutor = (request: FrameworkOperationRequest, report: DiagnosticsReporter, source: ArgumentsSource) => Promise<AvOperationResponse>;
 /** Selects the Contract of the request's origin. */
-export declare function activeContract(contracts: FrameworkContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): Contract;
+export declare function activeContract(contracts: AvContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): AvContract;
 /** Creates the transport-independent operation executor owned by core. */
-export declare function createOperationRuntime<M extends AdapterModel>(dependencies: OperationRuntimeDependencies<M>): FrameworkOperationExecutor;
+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: FrameworkContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): OperationFailureResponse | undefined;
+export declare function validateProtocolIdentity(contracts: AvContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): AvOperationFailureResponse | undefined;
 /**
- * The stale-client check on one client protocol identity: the protocol version first
- * (`A2006`), then the ClientContract hash (`A2005`). Exact match only. The one
+ * 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
+ * for a client, the Agent Contract's for an agent. Exact match only. The one
  * implementation — the protocol's decoders and absence answers
  * (`@aventara/core/protocol`) call it too, so a stale client hears the same envelope
  * whichever layer answers.
  */
-export declare function protocolIdentityFailure(contracts: FrameworkContracts, protocol: ClientProtocolIdentity): OperationFailureResponse | undefined;
+export declare function protocolIdentityFailure(contracts: AvContracts, protocol: ClientProtocolIdentity, origin: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
 export type ValidatedOperationArguments = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
 } | {
     readonly ok: false;
-    readonly response: OperationFailureResponse;
+    readonly response: AvOperationFailureResponse;
 };
 /** Validates one operation's arguments through the Framework Validation Layer. */
-export declare function validateOperationRequest(contract: Contract, request: FrameworkOperationRequest, options?: OperationValidationOptions, write?: NormalizationWrite): ValidatedOperationArguments;
+export declare function validateOperationRequest(contract: AvContract, request: FrameworkOperationRequest, options?: OperationValidationOptions, write?: NormalizationWrite): ValidatedOperationArguments;
+/** Every sent field's path: a single call's arguments hold no `$ref`. */
+export declare const EVERY_FIELD: () => boolean;
+/**
+ * What admission leaves: the deep-frozen arguments every later stage reads, and
+ * whether a pipe or a field pipe changed them; or the answer that refused the
+ * operation.
+ */
+export type AdmittedOperation = {
+    readonly ok: true;
+    readonly args: unknown;
+    readonly piped: boolean;
+} | {
+    readonly ok: false;
+    readonly response: AvOperationFailureResponse;
+};
+/** Which sent values an operation's field stages and validators take, and how its pipe output is checked. */
+export type AdmissionScope = {
+    /**
+     * The sent values the field pipes and validators take: every one for a single
+     * call, a plan step's literal values before BEGIN, its resolved `$ref` values
+     * at the step.
+     */
+    readonly select: (path: readonly (string | number)[]) => boolean;
+    /** Before BEGIN a plan step's `$ref` slots are unresolved: these admit them. */
+    readonly validation?: OperationValidationOptions;
+};
+/**
+ * Runs an operation's admission — its guards, pipes and validators — and answers
+ * the deep-frozen arguments the rest of the operation reads, or the refusal.
+ */
+export declare function admitOperation<M extends AvAdapterModel>(dependencies: OperationPipelineDependencies<M>, request: StatefulOperationRequest, contract: AvContract, args: unknown, argumentsPath: readonly (string | number)[], report: DiagnosticsReporter, scope: ExecutorScope<M>, admission?: AdmissionScope): Promise<AdmittedOperation>;
+/** How a plan step's arguments were changed between their admission and the step. */
+export type StepChanges = {
+    /** The sent `$ref` values written at this step: their field stages run now. */
+    readonly written: (path: readonly (string | number)[]) => boolean;
+    /** A transaction pipe changed the step: every value is judged again. */
+    readonly transactionPiped: boolean;
+    /** An operation pipe ran before BEGIN on a step with `$ref`s: the resolved arguments are checked again. */
+    readonly pipedAroundReferences: boolean;
+};
+/**
+ * A plan step's (or a forced call's) arguments at the step: resolved values
+ * through their field stages, and re-checked when a stage changed them.
+ */
+export declare function prepareStep<M extends AvAdapterModel>(dependencies: OperationPipelineDependencies<M>, request: StatefulOperationRequest, contract: AvContract, args: unknown, argumentsPath: readonly (string | number)[], report: DiagnosticsReporter, executor: AvAdapterTransactionExecutor<M>, changes: StepChanges, outer: OuterFailureLayer): Promise<AdmittedOperation>;
 /**
- * Everything after the Framework Validation Layer: the developer/runtime path
- * wrapped in the post-validation error boundary. Validation failures never
- * reach this function, so developer filters never see them.
+ * Everything after admission: write compute and the lifecycle around the
+ * Adapter call, wrapped in the post-validation error boundary. Validation
+ * failures never reach this function, so developer filters never see them.
  */
-export declare function executeValidatedOperation<M extends AdapterModel>(dependencies: OperationPipelineDependencies<M>, request: OperationExecutionRequest, contract: Contract, validatedArguments: unknown, argumentsPath: readonly (string | number)[], executor: AdapterOperationExecutor<M>, report: DiagnosticsReporter): Promise<OperationResponse>;
+export declare function executeAdmittedOperation<M extends AvAdapterModel>(dependencies: OperationPipelineDependencies<M>, request: StatefulOperationRequest, contract: AvContract, admittedArguments: unknown, argumentsPath: readonly (string | number)[], binding: OperationBinding<M>, report: DiagnosticsReporter): Promise<AvOperationResponse>;