@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

package/dist/runtime/mutation-planner.js

@@ -1,7 +1,7 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
-import { FrameworkError } from "./framework-error.js";
-import { INTERNAL_FAILURE_MESSAGE } from "./operation-response.js";
-import { normalizeScalarFieldValue } from "./scalar-runtime.js";
+import { AvComputedValueError } from "./computed-value.error.js";
+import { replaceAt, valueAt } from "./field-stage.runtime.js";
+import { jsonShapeIssues, normalizeScalarFieldValue, } from "./scalar-runtime.js";
 function writeScalarField(contracts, resourceName, fieldName) {
     const field = lookupField(lookupResource(contracts.core, resourceName), fieldName) ??
         lookupField(lookupResource(contracts.active, resourceName), fieldName);
@@ -34,13 +34,7 @@ function cloneRecord(value) {
 function relationEntries(value) {
     return Array.isArray(value) ? value : [value];
 }
-function behaviorFailure(issues) {
-    throw new FrameworkError("A3000", {
-        message: INTERNAL_FAILURE_MESSAGE,
-        issues,
-    });
-}
-async function computeRecord(contracts, behaviors, request, resourceName, stage, data, contextFactory) {
+async function computeRecord(contracts, compute, resourceName, stage, data, contextFactory) {
     if (!isRecord(data)) {
         return data;
     }
@@ -49,13 +43,13 @@ async function computeRecord(contracts, behaviors, request, resourceName, stage,
         return data;
     }
     const logicalData = cloneRecord(data);
-    const resourceBehaviors = behaviors[resourceName]?.fields;
-    if (resourceBehaviors !== undefined) {
-        for (const [fieldName, fieldBehavior] of Object.entries(resourceBehaviors)) {
-            if (fieldBehavior === undefined) {
+    const resourceCompute = compute[resourceName];
+    if (resourceCompute !== undefined) {
+        for (const [fieldName, fieldCompute] of Object.entries(resourceCompute)) {
+            if (fieldCompute === undefined) {
                 continue;
             }
-            const callback = fieldBehavior[stage];
+            const callback = fieldCompute[stage];
             if (typeof callback !== "function") {
                 continue;
             }
@@ -63,31 +57,43 @@ async function computeRecord(contracts, behaviors, request, resourceName, stage,
             if (field === undefined) {
                 continue;
             }
+            const snapshot = Object.freeze({ ...logicalData });
             const computed = await callback({
-                scope: request.scope,
-                resource: resourceName,
                 field: fieldName,
-                value: logicalData[fieldName],
-                data: logicalData,
-                operation: contextFactory(logicalData),
+                value: snapshot[fieldName],
+                data: snapshot,
+                ctx: contextFactory(snapshot),
             });
             if (computed === undefined) {
                 continue;
             }
-            const validation = normalizeScalarFieldValue(contracts.core, field, computed, "runtime", ["behaviors", resourceName, fieldName, stage]);
+            const validation = normalizeScalarFieldValue(contracts.core, field, computed, "runtime", [
+                "resources",
+                resourceName,
+                "fields",
+                fieldName,
+                "pipelines",
+                "compute",
+                stage,
+            ]);
             if (!validation.ok) {
-                behaviorFailure(validation.issues);
+                throw new AvComputedValueError(resourceName, fieldName, stage, validation.issues);
+            }
+            const shapeIssues = jsonShapeIssues(field, validation.value, [
+                "resources",
+                resourceName,
+                "fields",
+                fieldName,
+                "pipelines",
+                "compute",
+                stage,
+            ]);
+            if (shapeIssues.length > 0) {
+                throw new AvComputedValueError(resourceName, fieldName, stage, shapeIssues);
             }
             logicalData[fieldName] = validation.value;
         }
     }
-    for (const [fieldName, value] of Object.entries(logicalData)) {
-        const field = lookupField(resource, fieldName);
-        if (field?.kind !== "relation") {
-            continue;
-        }
-        logicalData[fieldName] = await mapRelationMutationRecords(field, value, (targetResource, nestedStage, record) => computeRecord(contracts, behaviors, request, targetResource, nestedStage, record, contextFactory));
-    }
     return logicalData;
 }
 async function mapRelationMutationRecords(relation, value, leaf) {
@@ -123,29 +129,49 @@ async function mapRelationMutationRecords(relation, value, leaf) {
     }
     return normalized;
 }
-export async function applyWriteFieldBehaviors(contracts, behaviors, request, args, contextFactory) {
-    if (behaviors === undefined || !isRecord(args)) {
+export async function applyWriteCompute(contracts, compute, request, args, contextFactory) {
+    if (compute === undefined || !isRecord(args)) {
         return args;
     }
     const logicalArgs = cloneRecord(args);
     if (request.family === "create" && "data" in logicalArgs) {
         logicalArgs.data = Array.isArray(logicalArgs.data)
-            ? await Promise.all(logicalArgs.data.map((entry) => computeRecord(contracts, behaviors, request, request.resource, "create", entry, contextFactory)))
-            : await computeRecord(contracts, behaviors, request, request.resource, "create", logicalArgs.data, contextFactory);
+            ? await Promise.all(logicalArgs.data.map((entry) => computeRecord(contracts, compute, request.resource, "create", entry, contextFactory)))
+            : await computeRecord(contracts, compute, request.resource, "create", logicalArgs.data, contextFactory);
     }
     if (request.family === "update" && "data" in logicalArgs) {
-        logicalArgs.data = await computeRecord(contracts, behaviors, request, request.resource, "update", logicalArgs.data, contextFactory);
+        logicalArgs.data = await computeRecord(contracts, compute, request.resource, "update", logicalArgs.data, contextFactory);
     }
     if (request.family === "upsert") {
         if ("create" in logicalArgs) {
-            logicalArgs.create = await computeRecord(contracts, behaviors, request, request.resource, "create", logicalArgs.create, contextFactory);
+            logicalArgs.create = await computeRecord(contracts, compute, request.resource, "create", logicalArgs.create, contextFactory);
         }
         if ("update" in logicalArgs) {
-            logicalArgs.update = await computeRecord(contracts, behaviors, request, request.resource, "update", logicalArgs.update, contextFactory);
+            logicalArgs.update = await computeRecord(contracts, compute, request.resource, "update", logicalArgs.update, contextFactory);
         }
     }
     return logicalArgs;
 }
+export async function applyNestedWriteCompute(contracts, compute, args, targets, context) {
+    if (compute === undefined) {
+        return args;
+    }
+    let current = args;
+    for (const target of targets) {
+        if (!Object.hasOwn(compute, target.resource)) {
+            continue;
+        }
+        for (const site of target.records) {
+            const record = valueAt(current, site.path);
+            if (!isRecord(record)) {
+                continue;
+            }
+            const computed = await computeRecord(contracts, compute, target.resource, site.stage, record, () => context(target, valueAt(current, target.path)));
+            current = replaceAt(current, site.path, computed);
+        }
+    }
+    return current;
+}
 async function stripVirtualRecord(contracts, resourceName, data) {
     if (!isRecord(data)) {
         return data;

package/dist/runtime/nested-write.walker.d.ts

@@ -0,0 +1,32 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import { type Path } from "./field-stage.runtime.js";
+import type { ReferentialActionTable } from "./referential-action.js";
+/** The family a nested target's stages are told, and its guards are drawn from. */
+export type NestedTargetFamily = "create" | "update" | "delete";
+/** One record of a nested target's data, and the write phase it is. */
+export type NestedRecordSite = {
+    /** Where the record sits in the operation's arguments. */
+    readonly path: Path;
+    /** `create` for a created row (an `$upsert`'s `create` branch too), `update` otherwise. */
+    readonly stage: "create" | "update";
+};
+/** One nested write's target, in data order. */
+export type NestedWriteTarget = {
+    /** The target Resource. */
+    readonly resource: string;
+    readonly family: NestedTargetFamily;
+    /** Where the directive's entry — the nested payload — sits in the arguments. */
+    readonly path: Path;
+    /** The entry's data records the target's field stages run on. */
+    readonly records: readonly NestedRecordSite[];
+};
+/**
+ * Every nested write target in an operation's arguments, depth first in data
+ * order: a target comes before the targets inside its own data, and before the
+ * next directive's. Empty for an operation with no write data. Total over
+ * malformed input.
+ */
+export declare function nestedWriteTargetsOf(contract: AvContract, references: ReferentialActionTable, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown): readonly NestedWriteTarget[];

package/dist/runtime/nested-write.walker.js

@@ -0,0 +1,73 @@
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { isPlainRecord, valueAt, writeRecordPathsOf, } from "./field-stage.runtime.js";
+import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "./mutation-planner.js";
+const DIRECTIVE_FAMILY = {
+    $create: "create",
+    $connectOrCreate: "create",
+    $update: "update",
+    $upsert: "update",
+    $delete: "delete",
+    $connect: "relation",
+    $disconnect: "relation",
+    $set: "relation",
+};
+function holdsReference(references, resource, relation) {
+    const edges = Object.hasOwn(references, resource)
+        ? references[resource]
+        : undefined;
+    return (Array.isArray(edges) &&
+        edges.some((edge) => edge.field === relation));
+}
+function walkRecord(context, resource, path, record) {
+    if (!isPlainRecord(record)) {
+        return;
+    }
+    const owner = lookupResource(context.contract, resource);
+    for (const [key, value] of Object.entries(record)) {
+        const field = lookupField(owner, key);
+        if (field?.kind !== "relation" || !isPlainRecord(value)) {
+            continue;
+        }
+        for (const [directive, operand] of Object.entries(value)) {
+            if (!isRelationMutationDirective(directive)) {
+                continue;
+            }
+            const mapped = DIRECTIVE_FAMILY[directive];
+            if (mapped === "relation" &&
+                field.cardinality === "one" &&
+                holdsReference(context.references, resource, key)) {
+                continue;
+            }
+            const family = mapped === "relation" ? "update" : mapped;
+            const entries = directive !== "$set" && Array.isArray(operand)
+                ? operand.map((_entry, index) => [index])
+                : [[]];
+            for (const at of entries) {
+                const entryPath = [...path, key, directive, ...at];
+                const records = [];
+                for (const site of RELATION_MUTATION_RECORD_SITES[directive]) {
+                    const sitePath = site.key === undefined ? entryPath : [...entryPath, site.key];
+                    if (isPlainRecord(valueAt(record, sitePath.slice(path.length)))) {
+                        records.push({ path: sitePath, stage: site.stage });
+                    }
+                }
+                context.targets.push({
+                    resource: field.target,
+                    family,
+                    path: entryPath,
+                    records,
+                });
+                for (const site of records) {
+                    walkRecord(context, field.target, site.path, valueAt(record, site.path.slice(path.length)));
+                }
+            }
+        }
+    }
+}
+export function nestedWriteTargetsOf(contract, references, request, args) {
+    const context = { contract, references, targets: [] };
+    for (const path of writeRecordPathsOf(request.family, args)) {
+        walkRecord(context, request.resource, path, valueAt(args, path));
+    }
+    return context.targets;
+}

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

@@ -1,25 +1,27 @@
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { PipelineTransportContext } from "./pipeline.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvTransportContext } from "./pipeline.js";
+import type { AvState } from "./request-state.js";
 /**
- * @deprecated Use {@link RequestOrigin}. The set it names is not a property of
- * an operation but the origin layer a request belongs to, derived from
- * `ConfigLayer`; kept as an alias so existing consumers keep compiling.
+ * The protocol version and Contract hash a remote caller says it was built for:
+ * the Client Contract's for a client, the Agent Contract's for an agent.
  */
-export type OperationScope = RequestOrigin;
-/** The protocol version and ClientContract hash a client says it was built for. */
 export type ClientProtocolIdentity = {
     readonly version: number;
     readonly hash: string;
 };
-type RuntimeOperationBase = OperationIdentity & {
+type RuntimeOperationBase = AvOperationIdentity & {
     readonly resource: string;
     readonly arguments: unknown;
     readonly requestId: string;
+    /**
+     * The request's `ctx.$state`: every stage of it, and every ctx call they make,
+     * shares this one object. Omitted, it is a fresh `{}`.
+     */
+    readonly state?: AvState;
 };
 /** An in-process request, run under the Application Contract. */
 export type ApplicationOperationRequest = RuntimeOperationBase & {
-    readonly scope: "application";
+    readonly origin: "application";
     readonly protocol?: never;
     readonly transport?: never;
 };
@@ -28,20 +30,38 @@ export type ApplicationOperationRequest = RuntimeOperationBase & {
  * the client sent.
  */
 export type ClientOperationRequest = RuntimeOperationBase & {
-    readonly scope: "client";
+    readonly origin: "client";
     readonly protocol: ClientProtocolIdentity;
-    readonly transport?: PipelineTransportContext;
+    readonly transport?: AvTransportContext;
 };
+/**
+ * An AI agent's request, run under the Agent Contract; `protocol` is the
+ * identity of the Agent Contract the caller (an MCP server) was built from.
+ */
+export type AgentOperationRequest = RuntimeOperationBase & {
+    readonly origin: "agent";
+    readonly protocol: ClientProtocolIdentity;
+    readonly transport?: AvTransportContext;
+};
+/** A request from outside the server: a client's or an agent's. */
+export type RemoteOperationRequest = ClientOperationRequest | AgentOperationRequest;
 /** One operation request, as `framework.execute` takes it. */
-export type FrameworkOperationRequest = ApplicationOperationRequest | ClientOperationRequest;
+export type FrameworkOperationRequest = ApplicationOperationRequest | ClientOperationRequest | AgentOperationRequest;
 type WithoutArguments<Request> = Request extends unknown ? Omit<Request, "arguments"> : never;
 /**
  * A request as every stage after the Framework Validation Layer sees it:
- * identity, scope, request id and transport, but never `arguments`. Those
+ * identity, origin, request id and transport, but never `arguments`. Those
  * stages act on the validated arguments passed beside it; the unvalidated
  * view — inside a transaction plan still carrying `$ref` placeholders — is
- * unreachable by type. Distributive, so the scope and family/variant
+ * unreachable by type. Distributive, so the origin and family/variant
  * correlations survive the omission.
  */
 export type OperationExecutionRequest = WithoutArguments<FrameworkOperationRequest>;
+/**
+ * A request whose stages run: its `state` settled once, the seed or the `{}`
+ * the runtime made for it, so every stage is told the same object.
+ */
+export type StatefulOperationRequest = OperationExecutionRequest & {
+    readonly state: AvState;
+};
 export {};

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,18 +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 CreateRequirementTable } 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";
-export type OperationRuntimeDependencies<M extends AdapterModel> = {
-    readonly adapter: Adapter<M>;
-    readonly contracts: FrameworkContracts;
+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 { 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 AvAdapterModel> = {
+    readonly adapter: AvAdapter<M>;
+    readonly contracts: AvContracts;
     readonly config: ResolvedFrameworkConfig<M>;
 };
 /**
@@ -20,43 +28,130 @@ 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"> & {
-    /** The Adapter's create requirements, read once at construction. */
-    readonly createRequirements: CreateRequirementTable;
+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
  * boundary — including the outermost totality guard, which runs outside this
- * function — reports through the same channel.
+ * function — reports through the same channel. `source` says whether the
+ * 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) => Promise<OperationResponse>;
-/** Selects the Contract of the request's execution scope. */
-export declare function activeContract(contracts: FrameworkContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): Contract;
+export type FrameworkOperationExecutor = (request: FrameworkOperationRequest, report: DiagnosticsReporter, source: ArgumentsSource) => Promise<AvOperationResponse>;
+/** Selects the Contract of the request's origin. */
+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): 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>;