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

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

@@ -1,50 +1,50 @@
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 /** Every outcome code, as a runtime list. */
 export declare const OPERATION_CODES: readonly ["A1000", "A1001", "A1002", "A1003", "A1004", "A1005", "A1006", "A1007", "A1008", "A1009", "A2000", "A2001", "A2002", "A2003", "A2004", "A2005", "A2006", "A2007", "A2008", "A2009", "A2010", "A2011", "A2012", "A2013", "A2014", "A3000", "A3001", "A3002", "A3003", "A3004", "A4000", "A4001", "A4002"];
 /**
  * Every outcome code: `A1xxx` success, `A2xxx` caller error, `A3xxx` internal
  * failure, `A4xxx` authentication or permission denial.
  */
-export type OperationCode = (typeof OPERATION_CODES)[number];
+export type AvOperationCode = (typeof OPERATION_CODES)[number];
 /** The success codes, `A1xxx`. */
-export type OperationSuccessCode = Extract<OperationCode, `A1${string}`>;
+export type AvOperationSuccessCode = Extract<AvOperationCode, `A1${string}`>;
 /** Every outcome code that is not a success. */
-export type OperationErrorCode = Exclude<OperationCode, OperationSuccessCode>;
+export type AvOperationErrorCode = Exclude<AvOperationCode, AvOperationSuccessCode>;
 /** Internal-failure family: nothing in the cause is caller-actionable. */
-export type OperationInternalErrorCode = Extract<OperationErrorCode, `A3${string}`>;
+export type OperationInternalErrorCode = Extract<AvOperationErrorCode, `A3${string}`>;
 /** Why a request failed: a message, and the validation issues when there are any. */
-export type Cause = {
+export type AvCause = {
     readonly message: string;
-    readonly issues?: readonly ValidationIssue[];
+    readonly issues?: readonly AvValidationIssue[];
     readonly operation?: number;
 };
 /** The response envelope: `{ data, code, cause }`. */
-type OperationResponseEnvelope<TData, TCode extends OperationCode, TCause extends Cause | null> = {
+type OperationResponseEnvelope<TData, TCode extends AvOperationCode, TCause extends AvCause | null> = {
     readonly data: TData;
     readonly code: TCode;
     readonly cause: TCause;
 };
 /** Success codes that carry response data (every success code but A1001). */
-export type OperationSuccessDataCode = Exclude<OperationSuccessCode, "A1001">;
+export type AvOperationSuccessDataCode = Exclude<AvOperationSuccessCode, "A1001">;
 /** A success with data: `cause` is `null`. */
-export type OperationSuccessResponse<T> = OperationResponseEnvelope<T, OperationSuccessDataCode, null>;
+export type AvOperationSuccessResponse<T> = OperationResponseEnvelope<T, AvOperationSuccessDataCode, null>;
 /** A success with no matching row (`A1001`): `data` and `cause` are `null`. */
-export type OperationNoMatchResponse = OperationResponseEnvelope<null, "A1001", null>;
+export type AvOperationNoMatchResponse = OperationResponseEnvelope<null, "A1001", null>;
 /** A failure: `data` is `null` and `cause` says why. */
-export type OperationFailureResponse = OperationResponseEnvelope<null, OperationErrorCode, Cause>;
+export type AvOperationFailureResponse = OperationResponseEnvelope<null, AvOperationErrorCode, AvCause>;
 /**
  * What an operation answers: success with data, a no-match success (`A1001`),
  * or a failure with a cause.
  */
-export type OperationResponse<T = unknown> = OperationSuccessResponse<T> | OperationNoMatchResponse | OperationFailureResponse;
+export type AvOperationResponse<T = unknown> = AvOperationSuccessResponse<T> | AvOperationNoMatchResponse | AvOperationFailureResponse;
 /** Builds a success response with data. */
-export declare function operationSuccess<T>(data: T, code: OperationSuccessDataCode): OperationSuccessResponse<T>;
+export declare function operationSuccess<T>(data: T, code: AvOperationSuccessDataCode): AvOperationSuccessResponse<T>;
 /** Builds the no-match success arm (A1001). */
-export declare function operationNoMatch(): OperationNoMatchResponse;
+export declare function operationNoMatch(): AvOperationNoMatchResponse;
 /** Builds a failure response. */
-export declare function operationFailure(code: OperationErrorCode, cause: Cause): OperationFailureResponse;
+export declare function operationFailure(code: AvOperationErrorCode, cause: AvCause): AvOperationFailureResponse;
 /** The one generic internal-failure text; every A3000 carries it. */
 export declare const INTERNAL_FAILURE_MESSAGE = "Internal framework error.";
 /** The response every internal failure (`A3000`) answers with. */
-export declare function internalFailure(): OperationFailureResponse;
+export declare function internalFailure(): AvOperationFailureResponse;
 export {};

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

@@ -1,20 +1,27 @@
-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 PolicyCaller } from "../policy/policy-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 { 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 { 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";
-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 +29,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.
+ */
+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 +80,96 @@ 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: 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: FrameworkContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): Contract;
+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 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: AvOperationRequest | AvTransactionRequest): 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 type ValidatedOperationArguments = {
+export declare function protocolIdentityFailure(contracts: AvContracts, protocol: AvRequestProtocol, origin: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
+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: 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";
+/**
+ * Every sent field's path. A `$ref` is an object of `$`-keys, which no field
+ * pipe or validator takes, so a plan step's literal values before BEGIN are
+ * every field too, wherever a pipe left a reference or a literal.
+ */
+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. */
+type AdmissionScope = {
+    /**
+     * The sent values the field pipes and validators take: every one for a single
+     * call and for a plan step before BEGIN (an unresolved `$ref` is an object of
+     * `$`-keys, which they never take), 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;
+    /**
+     * A plan step or a forced call, admitted before BEGIN: the validators judge
+     * there the sent values no later stage can change (a field with no write
+     * compute stage of its record's phase), so a caller's refusal opens no
+     * transaction. Everything is judged again after write compute.
+     */
+    readonly beforeBegin?: boolean;
+};
+/**
+ * Runs an operation's admission — its guards and pipes, and before BEGIN the
+ * validators of the values nothing after it changes — 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. */
+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 pipes, 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>;
+export {};