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

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

@@ -2,7 +2,9 @@ import type { AvContract } from "../contracts/contract.js";
 import type { AvField } from "../contracts/field.js";
 import type { AvValidationIssue } from "../operations/validation-code.js";
 import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { OperationFingerprint } from "./deferred-operation.js";
 import type { CandidateTransactionOperation, TransactionReferenceSlot, ValidatedTransactionStep } from "./transaction-plan-validator.js";
+import type { TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
 type Path = readonly (string | number)[];
 type ReferenceValidationResult = {
     readonly ok: true;
@@ -20,10 +22,8 @@ export declare function invalidSourceIndexIssue(operationPath: Path): AvValidati
  * integer naming a step before the referencing one (`V1016`).
  */
 export declare function referenceSourceAt(earlier: readonly ValidatedTransactionStep[], sourceIndex: unknown, referencingIndex: number): ValidatedTransactionStep | undefined;
-/** The `V1010` refusal of a reference whose source is an `appTx.$sql` step. */
-export declare function sqlSourceIssue(pathPath: Path): AvValidationIssue;
 /** The field a reference reads from its source step, or why it cannot read one. */
-export type ReferenceSourceRead = {
+type ReferenceSourceRead = {
     readonly ok: true;
     readonly field: AvField<AvContract>;
 } | {
@@ -39,6 +39,46 @@ export type ReferenceSourceRead = {
  * the source's to read. Assignability to a destination is the caller's.
  */
 export declare function referenceSourceField(source: ValidatedTransactionStep, segment: string, pathPath: Path): ReferenceSourceRead;
+/** A `$ref` control object read through: its source step, field and fingerprint. */
+type ReferenceCandidateInspection = {
+    readonly ok: true;
+    readonly source: Extract<ValidatedTransactionStep, {
+        kind: "operation";
+    }>;
+    readonly segment: string;
+    readonly fingerprint: OperationFingerprint;
+    readonly field: AvField<AvContract>;
+    /** The candidate's `path` member's own path, where a type refusal stands. */
+    readonly pathPath: Path;
+} | {
+    readonly ok: false;
+    readonly issue: AvValidationIssue;
+};
+/**
+ * Inspects one `$ref` control object standing at `slotPath` of step
+ * `referencingIndex`, through property descriptors only: its shape, its source
+ * step (an earlier one, never a SQL step), the source's fingerprint and the one
+ * field its path reads from the source's projection. Assignability to the
+ * destination is the caller's. Shared by an operation step's slots and an
+ * `appTx.$sql` value, so both refuse a malformed reference alike.
+ */
+export declare function inspectReferenceCandidate(candidate: unknown, slotPath: Path, earlier: readonly ValidatedTransactionStep[], referencingIndex: number): ReferenceCandidateInspection;
+/** The validated slots of a step's candidates, or the first one's refusal. */
+type ReferenceSlotsValidation = {
+    readonly ok: true;
+    readonly references: readonly TransactionReferenceSlot[];
+} | {
+    readonly ok: false;
+    readonly issue: AvValidationIssue;
+};
+/**
+ * Judges every `$ref` candidate of step `index` by the Framework Validation
+ * Layer's reference rules — its shape, an earlier non-SQL source step, that
+ * step's fingerprint, a field of its single-row projection, and type
+ * compatibility with the slot it stands in — and answers the validated slots,
+ * or the first refusal.
+ */
+export declare function validateReferenceSlots(candidates: readonly TransactionReferenceCandidateSlot[], earlier: readonly ValidatedTransactionStep[], index: number): ReferenceSlotsValidation;
 /** Validates every passive reference candidate before operation fingerprinting. */
 export declare function validateTransactionReferences(operation: CandidateTransactionOperation, earlier: readonly ValidatedTransactionStep[]): ReferenceValidationResult;
 export {};

package/dist/transactions/transaction-reference-validator.js

@@ -179,7 +179,7 @@ export function referenceSourceAt(earlier, sourceIndex, referencingIndex) {
         ? source
         : undefined;
 }
-export function sqlSourceIssue(pathPath) {
+function sqlSourceIssue(pathPath) {
     return validationIssue("V1010", pathPath, "Transaction reference source is a SQL step, whose rows cannot be referenced.");
 }
 export function referenceSourceField(source, segment, pathPath) {
@@ -212,66 +212,84 @@ export function referenceSourceField(source, segment, pathPath) {
 }
 const CANDIDATE_KEYS = new Set(["$ref"]);
 const REFERENCE_KEYS = new Set(["operation", "fingerprint", "path"]);
-export function validateTransactionReferences(operation, earlier) {
+export function inspectReferenceCandidate(candidate, slotPath, earlier, referencingIndex) {
+    const refused = (issue) => ({ ok: false, issue });
+    const candidateInspection = inspectControlObject(candidate, CANDIDATE_KEYS, slotPath, validationIssue("V1001", slotPath, "Reference control value must be an object."));
+    if (!candidateInspection.ok) {
+        return refused(candidateInspection.issue);
+    }
+    const refPath = [...slotPath, "$ref"];
+    const refProperty = inspectOwnDataProperty(candidateInspection.value, "$ref", refPath, "V1001", slotPath);
+    if (!refProperty.ok) {
+        return refused(refProperty.issue);
+    }
+    const operationPath = [...refPath, "operation"];
+    const referenceInspection = inspectControlObject(refProperty.value, REFERENCE_KEYS, refPath, validationIssue("V1016", operationPath, "Transaction reference operation index is invalid."));
+    if (!referenceInspection.ok) {
+        return refused(referenceInspection.issue);
+    }
+    const sourceIndexProperty = inspectOwnDataProperty(referenceInspection.value, "operation", operationPath, "V1016", refPath);
+    if (!sourceIndexProperty.ok) {
+        return refused(sourceIndexProperty.issue);
+    }
+    const source = referenceSourceAt(earlier, sourceIndexProperty.value, referencingIndex);
+    if (source === undefined) {
+        return refused(invalidSourceIndexIssue(operationPath));
+    }
+    if (source.kind === "sql") {
+        return refused(sqlSourceIssue([...refPath, "path"]));
+    }
+    const fingerprintPath = [...refPath, "fingerprint"];
+    const fingerprintProperty = inspectOwnDataProperty(referenceInspection.value, "fingerprint", fingerprintPath, "V1000", refPath);
+    if (!fingerprintProperty.ok) {
+        return refused(fingerprintProperty.issue);
+    }
+    const fingerprint = fingerprintProperty.value;
+    if (!isOperationFingerprint(fingerprint) ||
+        fingerprint !== source.fingerprint) {
+        return refused(validationIssue("V1017", fingerprintPath, "Transaction reference fingerprint does not match its source operation."));
+    }
+    const pathPath = [...refPath, "path"];
+    const pathProperty = inspectOwnDataProperty(referenceInspection.value, "path", pathPath, "V1010", refPath);
+    if (!pathProperty.ok) {
+        return refused(pathProperty.issue);
+    }
+    const pathInspection = inspectPathTuple(pathProperty.value, pathPath);
+    if (!pathInspection.ok) {
+        return refused(pathInspection.issue);
+    }
+    const { segment } = pathInspection;
+    if (containsUnpairedSurrogate(segment)) {
+        return refused(validationIssue("V1010", pathPath, "Transaction reference path contains invalid Unicode."));
+    }
+    const sourceRead = referenceSourceField(source, segment, pathPath);
+    if (!sourceRead.ok) {
+        return refused(sourceRead.issue);
+    }
+    return {
+        ok: true,
+        source,
+        segment,
+        fingerprint,
+        field: sourceRead.field,
+        pathPath,
+    };
+}
+export function validateReferenceSlots(candidates, earlier, index) {
     const references = [];
-    for (const slot of operation.candidates) {
-        const candidateInspection = inspectControlObject(slot.candidate, CANDIDATE_KEYS, slot.path, validationIssue("V1001", slot.path, "Reference control value must be an object."));
-        if (!candidateInspection.ok) {
-            return failure(candidateInspection.issue, operation.index);
+    for (const slot of candidates) {
+        const inspection = inspectReferenceCandidate(slot.candidate, slot.path, earlier, index);
+        if (!inspection.ok) {
+            return inspection;
         }
-        const refPath = [...slot.path, "$ref"];
-        const refProperty = inspectOwnDataProperty(candidateInspection.value, "$ref", refPath, "V1001", slot.path);
-        if (!refProperty.ok) {
-            return failure(refProperty.issue, operation.index);
-        }
-        const operationPath = [...refPath, "operation"];
-        const referenceInspection = inspectControlObject(refProperty.value, REFERENCE_KEYS, refPath, validationIssue("V1016", operationPath, "Transaction reference operation index is invalid."));
-        if (!referenceInspection.ok) {
-            return failure(referenceInspection.issue, operation.index);
-        }
-        const sourceIndexProperty = inspectOwnDataProperty(referenceInspection.value, "operation", operationPath, "V1016", refPath);
-        if (!sourceIndexProperty.ok) {
-            return failure(sourceIndexProperty.issue, operation.index);
-        }
-        const sourceIndex = sourceIndexProperty.value;
-        const source = referenceSourceAt(earlier, sourceIndex, operation.index);
-        if (source === undefined) {
-            return failure(invalidSourceIndexIssue(operationPath), operation.index);
-        }
-        if (source.kind === "sql") {
-            return failure(sqlSourceIssue([...refPath, "path"]), operation.index);
-        }
-        const fingerprintPath = [...refPath, "fingerprint"];
-        const fingerprintProperty = inspectOwnDataProperty(referenceInspection.value, "fingerprint", fingerprintPath, "V1000", refPath);
-        if (!fingerprintProperty.ok) {
-            return failure(fingerprintProperty.issue, operation.index);
-        }
-        const fingerprint = fingerprintProperty.value;
-        if (!isOperationFingerprint(fingerprint) ||
-            fingerprint !== source.fingerprint) {
-            return failure(validationIssue("V1017", fingerprintPath, "Transaction reference fingerprint does not match its source operation."), operation.index);
-        }
-        const pathPath = [...refPath, "path"];
-        const pathProperty = inspectOwnDataProperty(referenceInspection.value, "path", pathPath, "V1010", refPath);
-        if (!pathProperty.ok) {
-            return failure(pathProperty.issue, operation.index);
-        }
-        const pathInspection = inspectPathTuple(pathProperty.value, pathPath);
-        if (!pathInspection.ok) {
-            return failure(pathInspection.issue, operation.index);
-        }
-        const { segment } = pathInspection;
-        if (containsUnpairedSurrogate(segment)) {
-            return failure(validationIssue("V1010", pathPath, "Transaction reference path contains invalid Unicode."), operation.index);
-        }
-        const sourceRead = referenceSourceField(source, segment, pathPath);
-        if (!sourceRead.ok) {
-            return failure(sourceRead.issue, operation.index);
-        }
-        const sourceField = sourceRead.field;
+        const { source, segment, fingerprint, pathPath } = inspection;
+        const sourceField = inspection.field;
         if (sourceField.kind !== "scalar" ||
             !isAssignable(sourceField, slot.field, slot.shape)) {
-            return failure(validationIssue("V1011", pathPath, "Transaction reference source type is not assignable to its destination."), operation.index);
+            return {
+                ok: false,
+                issue: validationIssue("V1011", pathPath, "Transaction reference source type is not assignable to its destination."),
+            };
         }
         const reference = Object.freeze({
             $ref: Object.freeze({
@@ -289,6 +307,14 @@ export function validateTransactionReferences(operation, earlier) {
             reference,
         });
     }
+    return { ok: true, references };
+}
+export function validateTransactionReferences(operation, earlier) {
+    const validation = validateReferenceSlots(operation.candidates, earlier, operation.index);
+    if (!validation.ok) {
+        return failure(validation.issue, operation.index);
+    }
+    const { references } = validation;
     const controls = references.map((slot) => ({
         path: slot.path,
         value: slot.reference,

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

@@ -22,7 +22,7 @@ export type AvTransactionReference<Value = unknown> = {
     readonly [REFERENCE_VALUE]?: Value;
 };
 /** Whether a value is an ordinary value or a `$ref` candidate. */
-export type TransactionReferenceCandidateRoute = {
+type TransactionReferenceCandidateRoute = {
     readonly kind: "ordinary";
 } | {
     readonly kind: "candidate";

package/dist/transactions/transaction-reference.js

@@ -14,6 +14,11 @@ export function routeTransactionReferenceCandidate(value) {
         if (!ownKeys.includes("$ref") || referenceDescriptor === undefined) {
             return ORDINARY_ROUTE;
         }
+        if ("value" in referenceDescriptor &&
+            (referenceDescriptor.value === null ||
+                typeof referenceDescriptor.value !== "object")) {
+            return ORDINARY_ROUTE;
+        }
         return {
             kind: "candidate",
             candidate: value,

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,16 +1,19 @@
 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 { isPlainRecord, valueAt } from "../runtime/field-stage.runtime.js";
 import { internalFailure, operationSuccess, } from "../runtime/operation-response.js";
-import { admitOperation, executeAdmittedOperation, prepareStep, withRequestState, } from "../runtime/operation-runtime.js";
+import { admitOperation, EVERY_FIELD, executeAdmittedOperation, prepareStep, STEP_PIPES, withRequestState, } from "../runtime/operation-runtime.js";
 import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
+import { refusedStageOutput, serverContractFor, } from "../runtime/pipe-output.validator.js";
 import { resolveCascadeClosure } from "../runtime/referential-action.js";
 import { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
 import { validateTransactionPlan } from "./transaction-plan-validator.js";
+import { collectTransactionReferenceCandidates } from "./transaction-reference-collector.js";
 import { resolveSqlStatement, resolveTransactionReferences, } from "./transaction-reference-resolver.js";
+import { validateReferenceSlots } from "./transaction-reference-validator.js";
 import { transactionCommitted, transactionInfrastructureFailure, transactionOperationFailure, } from "./transaction-response.js";
 import { settleTransaction } from "./transaction-settlement.runtime.js";
-import { touchedTransactionLevels, transactionFacts, } from "./transaction-stage.runtime.js";
+import { TRANSACTION_PIPES, touchedTransactionLevels, transactionFacts, } from "./transaction-stage.runtime.js";
 export function createTransactionRuntime(dependencies, pipelineDependencies) {
     const { adapter } = dependencies;
     const planDependencies = {
@@ -18,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) {
@@ -59,39 +62,79 @@ function pathKey(path) {
 function relativeSlotPath(operation, path) {
     return path.slice(planOperationArgumentsPath(operation.index).length);
 }
-function standsAt(args, path, slot) {
-    const value = valueAt(args, path);
-    if (value === slot.reference) {
-        return true;
+function standingReferences(core, operation, args, steps, subject) {
+    const candidates = collectTransactionReferenceCandidates(serverContractFor(core, operation.contract), operation.request, operation.index, args);
+    const validation = validateReferenceSlots(candidates, steps, operation.index);
+    if (validation.ok) {
+        return validation;
     }
-    const reference = isPlainRecord(value) ? value.$ref : undefined;
-    if (!isPlainRecord(reference) || !Array.isArray(reference.path)) {
-        return false;
+    const { issue } = validation;
+    const refused = refusedStageOutput(operation.request, [
+        {
+            ...issue,
+            path: ["arguments", ...relativeSlotPath(operation, issue.path ?? [])],
+        },
+    ], subject);
+    if (refused === undefined) {
+        throw new TypeError("A refused reference produced no refusal.");
     }
-    const expected = slot.reference.$ref;
-    return (reference.operation === expected.operation &&
-        reference.path.length === 1 &&
-        reference.path[0] === expected.path[0]);
-}
-function slotKeys(operation) {
-    return new Set(operation.references.map((slot) => pathKey(relativeSlotPath(operation, slot.path))));
+    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) {
         if (step.kind === "sql") {
             admitted.push({ ok: true, args: undefined, piped: false });
+            standing.push([]);
             continue;
         }
-        const references = slotKeys(step);
-        const admission = await admitOperation(dependencies, stateful(step), step.contract, step.arguments, planOperationArgumentsPath(step.index), diagnostics.operation(step.request, step.index), { requestId: request.requestId, transaction: undefined, state }, {
-            select: (path) => !references.has(pathKey(path)),
+        const report = diagnostics.operation(step.request, step.index);
+        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,
         });
         if (!admission.ok) {
             return transactionOperationFailure(admission.response, step.index);
         }
+        if (!admission.piped) {
+            standing.push(step.references);
+        }
+        else {
+            const references = standingReferences(dependencies.contracts.core, step, admission.args, plan.operations, STEP_PIPES);
+            if (!references.ok) {
+                report(references.error, "A3004");
+                return transactionOperationFailure(references.response, step.index);
+            }
+            standing.push(references.references);
+        }
         admitted.push(admission);
     }
     const origin = planOrigin(request, plan);
@@ -101,9 +144,18 @@ 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 {
-            const live = operation.references.filter((slot) => standsAt(args, relativeSlotPath(operation, slot.path), slot));
+            let live = standing[operation.index] ?? operation.references;
+            if (transactionPiped) {
+                const references = standingReferences(dependencies.contracts.core, operation, args, plan.operations, TRANSACTION_PIPES);
+                if (!references.ok) {
+                    report(references.error, "A3004");
+                    return references.response;
+                }
+                live = references.references;
+            }
             const resolved = resolveTransactionReferences({
                 ...operation,
                 arguments: args,
@@ -119,7 +171,7 @@ async function executeTransactionPlan(adapter, dependencies, request, plan, stat
                 written: (path) => written.has(pathKey(path)),
                 transactionPiped,
                 pipedAroundReferences: admitted[operation.index]?.piped === true &&
-                    operation.references.length > 0,
+                    (live.length > 0 || operation.references.length > 0),
             }, outer);
             if (!prepared.ok) {
                 return prepared.response;

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

@@ -14,9 +14,9 @@ import { type TransactionStepView } from "./transaction-stage.runtime.js";
  * the touched Resources' transaction filters answer it once the transaction
  * interceptors have unwound. Its answer is the step's own outcome.
  */
-export type TransactionStepRunner<M extends AvAdapterModel> = (index: number, step: TransactionStepView, piped: boolean, executor: AvAdapterTransactionExecutor<M>, results: readonly unknown[], outer: OuterFailureLayer) => Promise<AvOperationResponse>;
+type TransactionStepRunner<M extends AvAdapterModel> = (index: number, step: TransactionStepView, piped: boolean, executor: AvAdapterTransactionExecutor<M>, results: readonly unknown[], outer: OuterFailureLayer) => Promise<AvOperationResponse>;
 /** How one transaction settled. */
-export type TransactionSettlement = 
+type TransactionSettlement = 
 /** Committed: every step's own outcome, in plan order. */
 {
     readonly kind: "committed";
@@ -34,7 +34,7 @@ export type TransactionSettlement =
     readonly error: unknown;
     readonly operation: number | undefined;
 };
-export type TransactionSettlementInput<M extends AvAdapterModel> = {
+type TransactionSettlementInput<M extends AvAdapterModel> = {
     readonly adapter: AvAdapter<M>;
     /** The touched Resources' transaction levels, outer to inner. */
     readonly levels: readonly ResolvedTransactionPipelineConfig[];
@@ -49,3 +49,4 @@ export type TransactionSettlementInput<M extends AvAdapterModel> = {
 };
 /** Runs `plan` inside one Adapter transaction, its stages around its steps, and settles it. */
 export declare function settleTransaction<M extends AvAdapterModel>(input: TransactionSettlementInput<M>): Promise<TransactionSettlement>;
+export {};

package/dist/transactions/transaction-slot-path-error.js

@@ -1,3 +1,4 @@
+import { brandCoreClass } from "../runtime/core-class.brand.js";
 const TRANSACTION_SLOT_PATH_MESSAGES = {
     "slot-prefix": "Transaction slot path does not name a member below the operation's arguments.",
     "absent-member": "Transaction slot path names an absent member of the operation arguments.",
@@ -11,3 +12,4 @@ export class AvTransactionSlotPathError extends Error {
         this.violation = violation;
     }
 }
+brandCoreClass(AvTransactionSlotPathError, "AvTransactionSlotPathError");

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

@@ -23,11 +23,12 @@ export type TransactionStepView = AvTransactionStep;
 export declare const TRANSACTION_PIPES = "Transaction pipes";
 /**
  * The `$` facts a transaction stage is told: the plan as `$args`, not one
- * operation (`$operation` is absent).
+ * operation (`$operation` is absent). Each ctx holds its own frozen copy of the
+ * plan, a `Date` or a `Uint8Array` in a step's arguments fresh.
  */
 export declare function transactionFacts(contract: AvContract, request: Pick<OperationExecutionRequest, "origin" | "requestId" | "transport">, plan: readonly TransactionStepView[]): ContextFacts;
 /** How the transaction stages around a plan's steps ended. */
-export type TransactionStagesOutcome = 
+type TransactionStagesOutcome = 
 /** Every stage and step ran; the steps' results, as the stages left them. */
 {
     readonly kind: "ran";
@@ -60,7 +61,7 @@ export type TransactionStagesOutcome =
  * changed it, in which case every operation step's arguments are held to the
  * server's rules and its validators again before it runs.
  */
-export type StagedPlan = {
+type StagedPlan = {
     readonly plan: readonly TransactionStepView[];
     readonly piped: boolean;
 };
@@ -79,3 +80,4 @@ export declare function runTransactionStages(levels: readonly ResolvedTransactio
  * exact reverse (the first that handles it wins), then final sanitization.
  */
 export declare function resolveTransactionStageFailure(error: unknown, levels: readonly ResolvedTransactionPipelineConfig[], context: AvTransactionContext, report: DiagnosticsReporter, view: CallerArgumentsView): Promise<AvOperationFailureResponse>;
+export {};

package/dist/transactions/transaction-stage.runtime.js

@@ -2,7 +2,7 @@ import { AdapterBoundary, resolveOperationFailure, } from "../runtime/error-boun
 import { runLevelLifecycle, } from "../runtime/level-lifecycle.runtime.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { AvPipeOutputError, PIPE_OUTPUT_FAILURE_MESSAGE, } from "../runtime/pipe-output.validator.js";
-import { deepFreeze } from "../runtime/readonly-value.js";
+import { deepFreeze, frozenCopy } from "../runtime/readonly-value.js";
 import { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
 export const TRANSACTION_ABORT = Object.freeze({ reason: "aventara-transaction-abort" });
 export const TRANSACTION_PIPES = "Transaction pipes";
@@ -10,7 +10,7 @@ export function transactionFacts(contract, request, plan) {
     return {
         $contract: contract,
         $origin: request.origin,
-        $args: plan,
+        $args: frozenCopy(plan),
         $requestId: request.requestId,
         ...(request.origin !== "application" && request.transport !== undefined
             ? { $transport: request.transport }
@@ -86,8 +86,11 @@ export async function runTransactionStages(levels, plan, contextOf, runSteps) {
         let pipeIndex = 0;
         for (const level of levels) {
             for (const pipe of level.pipes) {
-                const returned = await pipe(current, contextOf(current));
-                if (returned !== undefined && returned !== current) {
+                const told = frozenCopy(current);
+                const returned = await pipe(told, contextOf(current));
+                if (returned !== undefined &&
+                    returned !== told &&
+                    returned !== current) {
                     const accepted = acceptPlan(current, returned, pipeIndex);
                     if (typeof accepted === "string") {
                         return {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@aventara/core",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.10",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",
   "engines": {
-    "node": "^22.18.0 || >=24.2.0"
+    "node": "^22.23.4 || >=24.22.1"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,19 +34,20 @@
   "files": [
     "dist",
     "src/runtime/field-check.evaluator.ts",
+    "ERRORS.md",
     "LICENSE-ADDITIONAL-PERMISSION.md",
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "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",
+    "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"
+    "lint": "biome lint src scripts"
   }
 }

package/src/runtime/field-check.evaluator.ts

@@ -712,7 +712,7 @@ export function entryCheckIssues(
 }
 
 /** Whether a check judges a list's own length (`AvZ.minItems`/`AvZ.maxItems`). */
-export function isListCheck(check: AvFieldCheck): boolean {
+function isListCheck(check: AvFieldCheck): boolean {
 	return (
 		(check.check === "max_length" || check.check === "min_length") &&
 		check.list === true