@aventara/core 1.0.0-rc.11 → 1.0.0-rc.13

package/dist/runtime/mutation-planner.js

@@ -42,6 +42,7 @@ async function computeRecord(contracts, compute, resourceName, stage, data, cont
         return data;
     }
     const logicalData = cloneRecord(data);
+    let changed = false;
     const resourceCompute = compute[resourceName];
     if (resourceCompute !== undefined) {
         for (const [fieldName, fieldCompute] of Object.entries(resourceCompute)) {
@@ -79,9 +80,10 @@ async function computeRecord(contracts, compute, resourceName, stage, data, cont
                 throw new AvComputedValueError(resourceName, fieldName, stage, validation.issues);
             }
             logicalData[fieldName] = validation.value;
+            changed = true;
         }
     }
-    return logicalData;
+    return changed ? logicalData : data;
 }
 async function mapRelationMutationRecords(relation, value, leaf) {
     if (!isRecord(value)) {
@@ -121,23 +123,36 @@ export async function applyWriteCompute(contracts, compute, request, args, conte
         return args;
     }
     const logicalArgs = cloneRecord(args);
+    let changed = false;
+    const computeList = async (records, stage) => {
+        const computed = await Promise.all(records.map((entry) => computeRecord(contracts, compute, request.resource, stage, entry, contextFactory)));
+        return computed.every((entry, index) => entry === records[index])
+            ? records
+            : computed;
+    };
+    const computeAt = async (key, stage) => {
+        const record = logicalArgs[key];
+        const computed = Array.isArray(record) && request.family === "create"
+            ? await computeList(record, stage)
+            : await computeRecord(contracts, compute, request.resource, stage, record, contextFactory);
+        changed ||= computed !== record;
+        logicalArgs[key] = computed;
+    };
     if (request.family === "create" && "data" in logicalArgs) {
-        logicalArgs.data = Array.isArray(logicalArgs.data)
-            ? 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);
+        await computeAt("data", "create");
     }
     if (request.family === "update" && "data" in logicalArgs) {
-        logicalArgs.data = await computeRecord(contracts, compute, request.resource, "update", logicalArgs.data, contextFactory);
+        await computeAt("data", "update");
     }
     if (request.family === "upsert") {
         if ("create" in logicalArgs) {
-            logicalArgs.create = await computeRecord(contracts, compute, request.resource, "create", logicalArgs.create, contextFactory);
+            await computeAt("create", "create");
         }
         if ("update" in logicalArgs) {
-            logicalArgs.update = await computeRecord(contracts, compute, request.resource, "update", logicalArgs.update, contextFactory);
+            await computeAt("update", "update");
         }
     }
-    return logicalArgs;
+    return changed ? logicalArgs : args;
 }
 export async function applyNestedWriteCompute(contracts, compute, args, targets, context) {
     if (compute === undefined) {
@@ -154,7 +169,9 @@ export async function applyNestedWriteCompute(contracts, compute, args, targets,
                 continue;
             }
             const computed = await computeRecord(contracts, compute, target.resource, site.stage, record, () => context(target, valueAt(current, target.path)));
-            current = replaceAt(current, site.path, computed);
+            if (computed !== record) {
+                current = replaceAt(current, site.path, computed);
+            }
         }
     }
     return current;

package/dist/runtime/operation-code.guidance.js

@@ -71,7 +71,7 @@ export const OPERATION_CODE_GUIDANCE = {
     },
     A2004: {
         message: "Validation failed.",
-        cause: 'The arguments break a contract rule or a field validator. cause.issues lists each problem by V-code and path; a validator\'s issue also has check and params. The validators judge the values after the pipes and write compute, so a computed value they refuse is here too, at its field. A required create field left out is here (V1000). So is a value the database itself refused: too long for its column or its index, or out of its range (V1004), or holding a character it cannot store or a pattern it cannot read (V1001), with the issue at `["arguments"]`, or at the value where the adapter can place it (a bigint its driver cannot bind), and its message saying what the database refused. So is a record written through a relation that writes that relation, or a field holding its reference, back (V1012, at that field), where the adapter admits no such write.',
+        cause: 'The arguments break a contract rule or a field validator. cause.issues lists each problem by V-code and path; a validator\'s issue also has check and params. The validators judge every value the caller sent after its pipes and before write compute, a field with a compute stage included, so a bad value is refused even when compute would replace it; then a value write compute set or changed, so a computed value they refuse is here too, at its field. A required create field left out is here (V1000). So is a value the database itself refused: too long for its column or its index, or out of its range (V1004), or holding a character it cannot store or a pattern it cannot read (V1001), with the issue at `["arguments"]`, or at the value where the adapter can place it (a bigint its driver cannot bind), and its message saying what the database refused. So is a record written through a relation that writes that relation, or a field holding its reference, back (V1012, at that field), where the adapter admits no such write.',
         fix: "Fix the argument each issue's path points at, as its V-code says. A field the server must fill takes a compute.create stage. For a value the database refused, send one its column holds. For a nested write that writes its relation back, leave that field out: the parent supplies it.",
     },
     A2005: {
@@ -151,12 +151,12 @@ export const OPERATION_CODE_GUIDANCE = {
     },
     A4000: {
         message: "Unauthenticated.",
-        cause: 'A guard threw new AvError("A4000", ...): authentication is required or failed. The framework never authenticates by itself.',
+        cause: "A guard threw new AvError(\"A4000\", ...), or the host's or access provider's state rejected with an object whose status or statusCode is 401 (an authentication library's refusal, answered with this message only): authentication is required or failed. The framework never authenticates by itself.",
         fix: "Send the credentials your guards expect, such as the Authorization header.",
     },
     A4001: {
         message: "Forbidden.",
-        cause: 'A guard returned false ("Operation denied by a framework guard."), a field write guard or a nested write\'s target guard included, or a stage threw A4001.',
+        cause: "A guard returned false (\"Operation denied by a framework guard.\"), a field write guard or a nested write's target guard included, a stage threw A4001, or the host's or access provider's state rejected with an object whose status or statusCode is 403 (answered with this message only).",
         fix: "Call as a caller the guard admits, or stop sending the guarded field. To answer another code, throw an AvError from the guard.",
     },
     A4002: {

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

@@ -139,25 +139,26 @@ type AdmissionScope = {
     /** 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.
+     * The sent values the validators judge, when not the ones `select` admits: at
+     * a step a transaction pipe changed, its resolved `$ref` values and every value
+     * the pipe changed since the step's admission.
      */
-    readonly beforeBegin?: boolean;
+    readonly judge?: (path: readonly (string | number)[]) => 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.
+ * Runs an operation's admission — its guards, pipes and field pipes, then the
+ * validators of the values the caller sent — 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. */
+    /** A transaction pipe changed the step: what it changed is judged again. */
     readonly transactionPiped: boolean;
+    /** The step's arguments as admitted before BEGIN, what a transaction pipe's change is told apart from. */
+    readonly admitted: unknown;
     /** An operation pipe ran before BEGIN on a step with `$ref`s: the resolved arguments are checked again. */
     readonly pipedAroundReferences: boolean;
 };

package/dist/runtime/operation-runtime.js

@@ -2,6 +2,7 @@ import { hasFieldValidators } from "../compiler/field-validator.compiler.js";
 import { createComputedFields } from "../config/field-compute.resolver.js";
 import { fieldStagesOf, isForcedOperation, nestedTargetLevels, operationLevels, rawPipelineTree, transactionLevelsOf, } from "../config/pipeline-tree.resolver.js";
 import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
+import { opensServerTransactions } from "../contracts/transaction-capability.js";
 import { findOperationAvailabilityIssue, validateOperationArguments, } from "../operations/operation-validator.js";
 import { enforceReadPolicy, } from "../policy/policy-read.runtime.js";
 import { admitRequestPolicy, openRequestPolicy, } from "../policy/policy-request.js";
@@ -18,7 +19,7 @@ import { createDiagnosticsReporter, } from "./diagnostics-reporter.js";
 import { AdapterBoundary, OPERATION_ARGUMENTS_PATH, resolveOperationFailure, sanitizeOperationFailure, } from "./error-boundary.js";
 import { planFieldStages } from "./field-stage.plan.js";
 import { guardSentFields, pipeSentFields, valueAt, writeRecordPathsOf, } from "./field-stage.runtime.js";
-import { fieldValidatorIssues, hiddenFieldRefusal, } from "./field-validator.runtime.js";
+import { fieldValidatorIssues, hiddenFieldRefusal, valuesChangedBetween, } from "./field-validator.runtime.js";
 import { thrownFailure } from "./framework-error.factory.js";
 import { AvInterceptorNextError } from "./interceptor-next.error.js";
 import { runLevelLifecycle, } from "./level-lifecycle.runtime.js";
@@ -66,6 +67,7 @@ export function createPipelineDependencies(dependencies, model) {
             ? {}
             : { referentialActions: dependencies.adapter.referentialActions }),
         model,
+        core: dependencies.contracts.core,
     });
     const contexts = createContextExecutor({
         model,
@@ -213,14 +215,14 @@ export function createOperationRuntime(dependencies, pipelineDependencies) {
             requestId: request.requestId,
             transaction: undefined,
             state: stateful.state,
-        }, forced ? FORCED_CALL : SINGLE_CALL);
+        });
         if (!admitted.ok) {
             return admitted.response;
         }
         let checkedWrite = false;
         if (stateful.policy !== undefined &&
             request.family !== "find" &&
-            validated.contract.transactions === "interactive" &&
+            opensServerTransactions(validated.contract.transactions) &&
             !forced) {
             try {
                 checkedWrite = await writeNeedsTransaction(stateful.policy, dependencies.contracts.core, stateful, () => planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, validated.contract, activeScopeConfig(dependencies.config, request).compute, stateful, admitted.args), admitted.args);
@@ -309,7 +311,6 @@ function filtersOf(levels) {
     return levels.flatMap((level) => level.filters);
 }
 const SINGLE_CALL = { select: EVERY_FIELD };
-const FORCED_CALL = { select: EVERY_FIELD, beforeBegin: true };
 export async function admitOperation(dependencies, request, contract, args, argumentsPath, report, scope, admission = SINGLE_CALL) {
     const contexts = dependencies.contexts;
     const tree = activeScopeConfig(dependencies.config, request).pipelines;
@@ -402,7 +403,7 @@ async function runFieldInputStages(dependencies, request, contract, args, argume
     const tree = scopeConfig.pipelines;
     const planned = dependencies.fieldStages[request.origin];
     const pipes = planned.anyPipes;
-    const judge = admission.beforeBegin === true && hasFieldValidators(contract);
+    const judge = hasFieldValidators(contract);
     if (!pipes && !judge) {
         return { ok: true, args, piped: false };
     }
@@ -432,22 +433,17 @@ async function runFieldInputStages(dependencies, request, contract, args, argume
         }
     }
     if (judge) {
-        const compute = scopeConfig.compute;
-        const broken = fieldValidatorIssues(contract, dependencies.recordWrites.references, request, current, argumentsPath, admission.select, (resource, stage, field) => {
-            const fields = compute !== undefined && Object.hasOwn(compute, resource)
-                ? compute[resource]
-                : undefined;
-            const phases = fields !== undefined && Object.hasOwn(fields, field)
-                ? fields[field]
-                : undefined;
-            return phases?.[stage] !== undefined;
-        });
+        const broken = fieldValidatorIssues(contract, dependencies.recordWrites.references, request, current, argumentsPath, admission.judge ?? admission.select);
         if (broken.length > 0) {
             return { ok: false, response: mapValidationOutcome(broken) };
         }
     }
     return { ok: true, args: current, piped: changed };
 }
+function transactionPipeChanges(changes, current) {
+    const changed = valuesChangedBetween(changes.admitted, current);
+    return (path) => changes.written(path) || changed(path);
+}
 export async function prepareStep(dependencies, request, contract, args, argumentsPath, report, executor, changes, outer) {
     let current = deepFreeze(withoutUnsentWriteValues(dependencies.contracts.core, request, args));
     const scope = {
@@ -456,7 +452,12 @@ export async function prepareStep(dependencies, request, contract, args, argumen
         state: request.state,
     };
     try {
-        const resolved = await runFieldInputStages(dependencies, request, contract, current, argumentsPath, report, { select: changes.written });
+        const resolved = await runFieldInputStages(dependencies, request, contract, current, argumentsPath, report, changes.transactionPiped
+            ? {
+                select: changes.written,
+                judge: transactionPipeChanges(changes, current),
+            }
+            : { select: changes.written });
         if (!resolved.ok) {
             return resolved;
         }
@@ -510,6 +511,7 @@ async function executeForcedOperation(dependencies, adapter, request, contract,
                 const prepared = await prepareStep(dependencies, request, contract, stepArguments, OPERATION_ARGUMENTS_PATH, report, executor, {
                     written: () => false,
                     transactionPiped: true,
+                    admitted: args,
                     pipedAroundReferences: false,
                 }, outer);
                 if (!prepared.ok) {
@@ -576,8 +578,8 @@ export async function executeAdmittedOperation(dependencies, request, contract,
         if (firstUnfilled !== undefined) {
             throw new AvComputedValueError(firstUnfilled.resource, firstUnfilled.field, "create", unfilled.map((gap) => gap.issue), `compute.create on ${firstUnfilled.resource}.${firstUnfilled.field} returned undefined for a required field`);
         }
-        if (hasFieldValidators(contract)) {
-            const refused = fieldValidatorIssues(contract, dependencies.recordWrites.references, request, computed, argumentsPath, EVERY_FIELD);
+        if (computed !== args && hasFieldValidators(contract)) {
+            const refused = fieldValidatorIssues(contract, dependencies.recordWrites.references, request, computed, argumentsPath, valuesChangedBetween(args, computed));
             if (refused.length > 0) {
                 return mapValidationOutcome(refused);
             }

package/dist/runtime/pipeline.d.ts

@@ -5,7 +5,7 @@ import type { AvRequestOrigin } from "../config/config-layer.js";
 import type { AvConfigResourceKey } from "../config/framework-field-definition.js";
 import type { AvContract } from "../contracts/contract.js";
 import type { AvApplicationScalarForms } from "../contracts/scalar-value-type.js";
-import type { AvContractApplicationView, RequirementsLessComputed } from "../framework/contract-view.js";
+import type { AvContractApplicationView, PreComputeView } from "../framework/contract-view.js";
 import type { AvContextOperations } from "../framework/operation-facade.js";
 import type { AvOperationArgumentsFor, AvResourceKey } from "../operations/operation-arguments.js";
 import type { AvOperationFamily, AvOperationIdentity } from "../operations/operation-identity.js";
@@ -59,20 +59,6 @@ type StageArgumentsOf<C extends AvContract, R extends string, F extends AvOperat
  * `compute.create` fills (`Lift`, as `"<Resource>.<field>"`; `string`: any).
  */
 export type AvPreComputeStageArguments<M extends AvAdapterModel, R extends string, F extends AvOperationFamily, V extends string, Lift extends string = AvPreComputeLift<M, "root">> = F extends "find" | "delete" ? AvStageArguments<M, R, F, V> : [Lift] extends [never] ? AvStageArguments<M, R, F, V> : StageArgumentsOf<PreComputeView<AvContractApplicationView<M>, Lift>, R, F, V>;
-/** A Contract view with the create requirements `Lift` names lifted. */
-type PreComputeView<C, Lift extends string> = Extract<{
-    readonly [P in keyof C]: P extends "resources" ? string extends Lift ? {
-        readonly [R in keyof C[P]]: Omit<C[P][R], "createRequirements">;
-    } : {
-        readonly [R in keyof C[P]]: LiftedResource<C[P][R], LiftedFieldOf<Lift, R>>;
-    } : C[P];
-}, AvContract>;
-/** The fields of Resource `R` that `Lift` names. */
-type LiftedFieldOf<Lift extends string, R> = Lift extends `${R & string}.${infer Field}` ? Field : never;
-/** One Resource with the create requirements on `Fields` lifted; itself when none. */
-type LiftedResource<Resource, Fields> = [Fields] extends [never] ? Resource : {
-    readonly [P in keyof Resource]: P extends "createRequirements" ? RequirementsLessComputed<Exclude<Resource[P], undefined>, Fields> : Resource[P];
-};
 /**
  * What a pipeline callback is told about the operation it is wrapping, and the
  * framework's executor: `ctx.<Resource>.<family>.<variant>(args)`, `ctx.$sql` and

package/dist/runtime/state-refusal.mapper.d.ts

@@ -0,0 +1,16 @@
+import { type AvOperationFailureResponse } from "./operation-response.js";
+/**
+ * The outcome a seed's rejection carries by its shape: `A4000` for an object
+ * whose `status` or `statusCode` is `401`, `A4001` for `403`, each with core's
+ * own cause. `undefined` for anything else: an `AvError` (it is its own
+ * outcome), two numeric fields that disagree, and a value whose fields cannot
+ * be read. Total: it never throws.
+ */
+export declare function stateRefusalOf(error: unknown): AvOperationFailureResponse | undefined;
+/**
+ * What an in-process call rejects with when the `state` seeding it rejected
+ * with `error`: the `AvAuthError` of `A4000` or `A4001`, with core's own cause,
+ * for a rejection {@link stateRefusalOf} reads as a refusal; `error` itself
+ * otherwise, an `AvError` included. Total: it never throws.
+ */
+export declare function inProcessStateRejection(error: unknown): unknown;

package/dist/runtime/state-refusal.mapper.js

@@ -0,0 +1,40 @@
+import { thrownFailure } from "./framework-error.factory.js";
+import { AvError } from "./framework-error.js";
+import { OPERATION_CODE_GUIDANCE } from "./operation-code.guidance.js";
+import { operationFailure, } from "./operation-response.js";
+const REFUSALS = {
+    401: "A4000",
+    403: "A4001",
+};
+const isRefusalStatus = (value) => value === 401 || value === 403;
+export function stateRefusalOf(error) {
+    try {
+        if (typeof error !== "object" ||
+            error === null ||
+            error instanceof AvError) {
+            return undefined;
+        }
+        const { status, statusCode } = error;
+        if (typeof status === "number" &&
+            typeof statusCode === "number" &&
+            status !== statusCode) {
+            return undefined;
+        }
+        const statuses = new Set([status, statusCode].filter(isRefusalStatus));
+        const [only] = statuses;
+        if (statuses.size !== 1 || only === undefined) {
+            return undefined;
+        }
+        const code = REFUSALS[only];
+        return operationFailure(code, {
+            message: OPERATION_CODE_GUIDANCE[code].message,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+export function inProcessStateRejection(error) {
+    const refusal = stateRefusalOf(error);
+    return refusal === undefined ? error : thrownFailure(refusal);
+}

package/dist/transactions/operation-fingerprint.d.ts

@@ -8,5 +8,18 @@ export type OperationFingerprintNode = {
 };
 /** Whether `value` is an operation fingerprint (`fp1:…`). */
 export declare function isOperationFingerprint(value: unknown): value is OperationFingerprint;
-/** Computes an operation's fingerprint from its wire-form arguments. */
-export declare function computeOperationFingerprint(node: OperationFingerprintNode): Promise<OperationFingerprint>;
+/**
+ * The fingerprint of one transaction plan step, `fp1:` and 22 base64url
+ * characters: the RFC 8785 canonical JSON of `{ resource, family, variant, args }`
+ * over the step's wire-form arguments (a key holding `undefined` left out, an
+ * array element holding it written `null`), its UTF-8 bytes hashed with SHA-256,
+ * the first 16 bytes of the digest in base64url without padding. Rejects when the
+ * arguments are not JSON: a lone surrogate, a non-finite number, a `bigint`, a
+ * function, a symbol, or an object that is not a plain object or array.
+ */
+export declare function computeOperationFingerprint(node: {
+    readonly resource: string;
+    readonly family: string;
+    readonly variant: string;
+    readonly args: unknown;
+}): Promise<`fp1:${string}`>;

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

@@ -1,5 +1,6 @@
 import { AvCanonicalJsonError } from "../contracts/contract-canonicalizer.js";
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { takesTransactionPlans } from "../contracts/transaction-capability.js";
 import { parseOperationIdentity } from "../operations/operation-identity.js";
 import { findOperationAvailabilityIssue, operationUnavailableIssue, unavailableOperationKey, } from "../operations/operation-validator.js";
 import { resourceUnavailableIssue } from "../operations/operation-validator-core.js";
@@ -51,6 +52,31 @@ export function capturePlanAtCall(plan) {
         throw error;
     }
 }
+const WRITE_FAMILIES = new Set([
+    "create",
+    "update",
+    "upsert",
+    "delete",
+]);
+function writeLimitFailure(steps, planContracts) {
+    const maxTransactionWrites = Math.min(...planContracts.map((contract) => contract.limits.maxTransactionWrites));
+    let writes = 0;
+    for (const step of steps) {
+        if (step.ok &&
+            (step.kind === "sql" || WRITE_FAMILIES.has(step.node.get("family")))) {
+            writes += 1;
+        }
+    }
+    if (writes <= maxTransactionWrites) {
+        return undefined;
+    }
+    return operationFailure("A2009", {
+        message: "Transaction write count exceeds the active Contract limit.",
+        issues: [
+            validationIssue("V1014", ["operations"], `Transaction write count exceeds maxTransactionWrites (${maxTransactionWrites}).`),
+        ],
+    });
+}
 function captureSteps(operations, operationCount, planArguments) {
     const steps = [];
     const statements = planArguments.source === "owned" ? planArguments.statements : undefined;
@@ -269,7 +295,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
     const planContracts = origins === undefined || origins.length === 0
         ? [activeContract(dependencies.contracts, request)]
         : originContracts(dependencies.contracts, origins);
-    if (planContracts.some((contract) => contract.transactions === "none")) {
+    if (planContracts.some((contract) => !takesTransactionPlans(contract.transactions))) {
         return { ok: false, response: transactionsUnavailableFailure() };
     }
     const planEnvelope = inspectTransactionEnvelope(request.plan, {
@@ -307,6 +333,10 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
         };
     }
     const steps = captureSteps(operations, operationCount, planArguments);
+    const writes = writeLimitFailure(steps, planContracts);
+    if (writes !== undefined) {
+        return { ok: false, response: writes };
+    }
     const misuse = createMisuseReporter(dependencies.config.misuse);
     const validated = [];
     const cascaded = new Set();

package/dist/transactions/transaction-runtime.js

@@ -148,7 +148,6 @@ async function executeTransactionPlan(runtime, dependencies, request, plan, stat
         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);
@@ -199,6 +198,7 @@ async function executeTransactionPlan(runtime, dependencies, request, plan, stat
             const prepared = await prepareStep(dependencies, stepRequest, operation.contract, resolved.arguments, argumentsPath, report, executor, {
                 written: (path) => written.has(pathKey(path)),
                 transactionPiped,
+                admitted: admitted[operation.index]?.args,
                 pipedAroundReferences: admitted[operation.index]?.piped === true &&
                     (live.length > 0 || operation.references.length > 0),
             }, outer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/core",
-  "version": "1.0.0-rc.11",
+  "version": "1.0.0-rc.13",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",

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

@@ -579,10 +579,54 @@ function plural(count: number, one: string, many: string): string {
 	return `${count} ${count === 1 ? one : many}`;
 }
 
+/** The characters a pattern reads as syntax: `AvZ.oneOf` escapes each in a value. */
+const PATTERN_SYNTAX = "\\^$.*+?()[]{}|/";
+
+// Source: rc.13 (CORE-08). `AvZ.oneOf` writes its values as `^(?:a|b)$`, each
+// syntax character escaped, no flags: read back exactly, that form lists them.
+// Any other pattern (an unescaped syntax character, a flag) lists nothing.
+/** The values an `AvZ.oneOf` pattern lists, or `undefined` for any other pattern. */
+function listedValues(pattern: {
+	readonly source: string;
+	readonly flags: string;
+}): readonly string[] | undefined {
+	const { source, flags } = pattern;
+	if (flags !== "" || !source.startsWith("^(?:") || !source.endsWith(")$")) {
+		return undefined;
+	}
+	const body = source.slice(4, -2);
+	const values: string[] = [];
+	let value = "";
+	for (let index = 0; index < body.length; index += 1) {
+		const character = body.charAt(index);
+		if (character === "\\") {
+			const escaped = body.charAt(index + 1);
+			if (escaped === "" || !PATTERN_SYNTAX.includes(escaped)) {
+				return undefined;
+			}
+			value += escaped;
+			index += 1;
+		} else if (character === "|") {
+			values.push(value);
+			value = "";
+		} else if (PATTERN_SYNTAX.includes(character)) {
+			return undefined;
+		} else {
+			value += character;
+		}
+	}
+	values.push(value);
+	return values;
+}
+
 function formatMessage(check: AvFieldFormatCheck): string {
 	switch (check.format) {
-		case "regex":
-			return `Value must match the pattern /${check.pattern.source}/${check.pattern.flags}.`;
+		case "regex": {
+			const listed = listedValues(check.pattern);
+			return listed === undefined
+				? `Value must match the pattern /${check.pattern.source}/${check.pattern.flags}.`
+				: `Value must be one of ${listed.map((value) => JSON.stringify(value)).join(", ")}.`;
+		}
 		case "includes":
 			return `Value must include ${JSON.stringify(check.includes)}.`;
 		case "starts_with":