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

package/dist/transactions/transaction-plan-assembler.d.ts

@@ -1,14 +1,16 @@
 import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { AvOperationIdentity } from "../operations/operation-identity.js";
-import type { AvCallerDataError } from "../runtime/caller-data.copier.js";
+import { AvCallerDataError } from "../runtime/caller-data.copier.js";
 import type { MisuseReporter } from "../runtime/misuse-reporter.js";
-import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.js";
 import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
 import type { AvOperation, OperationFingerprint } from "./deferred-operation.js";
 import type { PlannedSqlStatement } from "./sql-statement.js";
 import type { TransactionOperationOrigin } from "./transaction-request.js";
 /** The origin a handle's builder gives it. */
 type HandleOrigin = "application" | "client";
+/** The scalar forms a builder takes its arguments in. */
+type ArgumentForms = "wire" | "application";
 /** One wire node, exactly as the transaction runtime receives it. */
 type WireOperationNode = {
     readonly resource: string;
@@ -37,8 +39,13 @@ export type AssembledTransactionPlan = {
     readonly response: AvOperationFailureResponse;
 };
 export type TransactionPlanAssembler = {
-    /** Defers one operation into a handle; nothing runs. */
-    defer(origin: HandleOrigin, resource: string, identity: AvOperationIdentity, args: unknown): AvOperation<unknown>;
+    /**
+     * Defers one operation into a handle; nothing runs. `forms` says which scalar
+     * forms a client-origin handle's arguments are in: `"wire"` (`clientTx`, the
+     * default) or `"application"` (`serverClientTx`), encoded into the wire forms
+     * from the builder's copy.
+     */
+    defer(origin: HandleOrigin, resource: string, identity: AvOperationIdentity, args: unknown, forms?: ArgumentForms): AvOperation<unknown>;
     /** Defers one `appTx.$sql` statement into a handle; nothing runs. */
     deferSql(strings: unknown, values: readonly unknown[]): AvOperation<unknown>;
     /** Binds a list of handles into the passive plan, or refuses it. */
@@ -49,5 +56,5 @@ export type TransactionPlanAssembler = {
  * handle, so a handle another instance built — typed against another model,
  * bound to other Contracts — is refused rather than run.
  */
-export declare function createTransactionPlanAssembler(contracts: AvContracts, protocol: ClientProtocolIdentity, misuse: MisuseReporter): TransactionPlanAssembler;
+export declare function createTransactionPlanAssembler(contracts: AvContracts, protocol: AvRequestProtocol, misuse: MisuseReporter): TransactionPlanAssembler;
 export {};

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

@@ -1,19 +1,16 @@
 import { VALIDATION_CODE_MESSAGES, validationIssue, } from "../operations/validation-code.js";
+import { AvCallerDataError, } from "../runtime/caller-data.copier.js";
 import { copyAtDoor, refuseCallerData } from "../runtime/caller-data.door.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
+import { isPlainRecord } from "../runtime/record.guard.js";
+import { withoutUnsentWriteValues } from "../runtime/unsent-value.normalizer.js";
 import { encodeOperationArgumentsForWire } from "./operation-arguments-encoder.js";
 import { computeOperationFingerprint } from "./operation-fingerprint.js";
 import { readSqlTemplate } from "./sql-statement.js";
+import { routeTransactionReferenceCandidate } from "./transaction-reference.js";
 import { transactionOperationFailure } from "./transaction-response.js";
 const SQL_STEP_NODE = Object.freeze({ fingerprint: null });
-function isPlainRecord(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
 const KEEP = Symbol("keep");
 function rebuildArguments(root, leaf) {
     const pathOf = (parent, key) => () => {
@@ -46,6 +43,9 @@ function rebuildArguments(root, leaf) {
         if (!Array.isArray(value) && !isPlainRecord(value)) {
             return { value };
         }
+        if (Object.hasOwn(value, "$ref")) {
+            return { value };
+        }
         if (ancestors.has(value)) {
             return { value };
         }
@@ -92,15 +92,17 @@ function operationEntryFailure(operation, message) {
 function referenceFailure(issue, operation) {
     return transactionOperationFailure(mapValidationOutcome([issue]), operation);
 }
+const STEP_REFERENCE_MIRROR = (value) => Object.hasOwn(value, "$ref");
 export function createTransactionPlanAssembler(contracts, protocol, misuse) {
     const handles = new WeakMap();
     const placeholders = new WeakMap();
     const originOf = (origin) => origin === "application"
         ? { origin: "application" }
         : { origin: "client", protocol };
-    const snapshot = (args) => {
+    const snapshot = (args, mirror) => {
         const copy = copyAtDoor(args, {
             keep: (value) => placeholders.has(value),
+            ...(mirror === undefined ? {} : { mirror }),
         });
         return copy.ok ? { args: copy.value } : { args: {}, refused: copy.error };
     };
@@ -131,15 +133,43 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
         handles.set(handle, record);
         return handle;
     };
-    const defer = (origin, resource, identity, args) => createHandle({
-        kind: "operation",
-        origin,
-        resource,
-        identity,
-        ...snapshot(args),
-    });
+    const defer = (origin, resource, identity, args, forms = "wire") => {
+        const snapped = snapshot(args, STEP_REFERENCE_MIRROR);
+        let copy = snapped;
+        if (origin === "client" &&
+            forms === "application" &&
+            snapped.refused === undefined) {
+            try {
+                copy = {
+                    args: encodeOperationArgumentsForWire(contracts.client, { resource, ...identity }, snapped.args),
+                };
+            }
+            catch (error) {
+                if (!(error instanceof AvCallerDataError)) {
+                    throw error;
+                }
+            }
+        }
+        let sent = copy.args;
+        try {
+            sent = withoutUnsentWriteValues(origin === "application" ? contracts.application : contracts.client, { resource, family: identity.family }, copy.args);
+        }
+        catch (error) {
+            if (!(error instanceof AvCallerDataError)) {
+                throw error;
+            }
+        }
+        return createHandle({
+            kind: "operation",
+            origin,
+            resource,
+            identity,
+            ...copy,
+            args: sent,
+        });
+    };
     const deferSql = (strings, values) => {
-        const copy = snapshot(values);
+        const copy = snapshot(values, STEP_REFERENCE_MIRROR);
         return createHandle({
             kind: "sql",
             strings: readSqlTemplate(strings, values.length),
@@ -153,7 +183,9 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
             const sites = placeholderSites(value);
             const [site] = sites;
             if (site === undefined) {
-                return { kind: "value", value };
+                return routeTransactionReferenceCandidate(value).kind === "ordinary"
+                    ? { kind: "value", value }
+                    : { kind: "candidate", candidate: value };
             }
             if (site.path.length > 0) {
                 return { kind: "misplaced-reference", path: site.path };

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

@@ -4,7 +4,7 @@ import type { AvScalarField } from "../contracts/field.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
 import { AvCallerDataError } from "../runtime/caller-data.copier.js";
 import { type ReadProjectionPlan } from "../runtime/computed-read-runtime.js";
-import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
+import type { AvOperationRequest } from "../runtime/operation-request.js";
 import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
 import type { OperationPipelineDependencies } from "../runtime/operation-runtime.js";
 import type { CascadeClosure } from "../runtime/referential-action.js";
@@ -13,7 +13,7 @@ import type { PlannedSqlStatement, ValidatedSqlStatement } from "./sql-statement
 import type { AvTransactionReference } from "./transaction-reference.js";
 import { type TransactionSlotShape } from "./transaction-reference.js";
 import { type TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
-import type { FrameworkTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
+import type { AvTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
 /**
  * Where a plan's step arguments came from, so the validator knows whether to copy
  * them at the door (see `ArgumentsSource`):
@@ -34,6 +34,22 @@ export type PlanArguments = {
     readonly refused?: ReadonlyMap<number, AvCallerDataError>;
     readonly statements?: ReadonlyMap<number, PlannedSqlStatement>;
 };
+/** A plan taken at a call, and the steps whose arguments could not be copied. */
+type CapturedPlan = {
+    readonly plan: unknown;
+    readonly refused: ReadonlyMap<number, AvCallerDataError>;
+};
+/**
+ * A host's parsed plan taken at `protocol.handleTransaction`'s call, before its first
+ * await (rc.2, e2e batch 2): its structure mirrored by descriptors, which is how this
+ * validator inspects it — so no getter it refuses runs, and every accessor stays one
+ * for it to refuse — and each step's `args` copied as {@link captureSteps} copies a
+ * caller's, its `$ref` control objects mirrored. Run as an `"owned"` plan with
+ * `refused`, it is answered exactly as the plan the host held at the call. A plan
+ * that is no object, or cannot be reflected, is returned as it is: nothing in it can
+ * change.
+ */
+export declare function capturePlanAtCall(plan: unknown): CapturedPlan;
 export type { TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
 /** One validated Transaction Slot: where it is, what it holds, and its reference. */
 export type TransactionReferenceSlot = {
@@ -49,7 +65,7 @@ export type TransactionReferenceSlot = {
 };
 export type CandidateTransactionOperation = {
     readonly index: number;
-    readonly request: FrameworkOperationRequest;
+    readonly request: AvOperationRequest;
     readonly arguments: SemanticOperationArguments;
     readonly projection: ReadProjectionPlan | undefined;
     readonly declaredFingerprint: unknown;
@@ -58,7 +74,7 @@ export type CandidateTransactionOperation = {
 export type ValidatedTransactionOperation = {
     readonly kind: "operation";
     readonly index: number;
-    readonly request: FrameworkOperationRequest;
+    readonly request: AvOperationRequest;
     /**
      * The Contract of this operation's origin, which is the plan's: the one it was
      * validated against, the one it runs under, and the one a later `$ref` reads its
@@ -81,12 +97,12 @@ export type ValidatedTransactionPlan = {
  * Framework is constructed. The record-write facts are not among them: they
  * are checked when each operation runs, after its pipes.
  */
-export type TransactionPlanDependencies<M extends AvAdapterModel> = Omit<OperationPipelineDependencies<M>, "recordWrites" | "contexts" | "fieldStages"> & {
+type TransactionPlanDependencies<M extends AvAdapterModel> = Omit<OperationPipelineDependencies<M>, "recordWrites" | "contexts" | "fieldStages"> & {
     readonly cascades: CascadeClosure;
     /** Whether the Adapter declares `sqlStatements`: read once, at construction. */
     readonly sqlStatements: boolean;
 };
-export type TransactionPlanValidationResult = {
+type TransactionPlanValidationResult = {
     readonly ok: true;
     readonly plan: ValidatedTransactionPlan;
 } | {
@@ -102,4 +118,4 @@ export declare function transactionsUnavailableFailure(): AvOperationFailureResp
 /**
  * Whole-plan Framework Validation Layer for transaction structure and identity.
  */
-export declare function validateTransactionPlan<M extends AvAdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;
+export declare function validateTransactionPlan<M extends AvAdapterModel>(dependencies: TransactionPlanDependencies<M>, request: AvTransactionRequest, origins?: readonly TransactionOperationOrigin[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;

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

@@ -4,7 +4,7 @@ import { parseOperationIdentity } from "../operations/operation-identity.js";
 import { findOperationAvailabilityIssue, operationUnavailableIssue, unavailableOperationKey, } from "../operations/operation-validator.js";
 import { resourceUnavailableIssue } from "../operations/operation-validator-core.js";
 import { VALIDATION_CODE_MESSAGES, validationIssue, } from "../operations/validation-code.js";
-import { AvCallerDataError, locateCallerDataError, } from "../runtime/caller-data.copier.js";
+import { AvCallerDataError, locateCallerDataError, mirrorCallerData, } from "../runtime/caller-data.copier.js";
 import { copyAtDoor, misuseIdentityOf, refuseCallerData, } from "../runtime/caller-data.door.js";
 import { planReadOperation, } from "../runtime/computed-read-runtime.js";
 import { planOperationArgumentsPath, planStepPath, } from "../runtime/error-boundary.js";
@@ -12,6 +12,7 @@ import { createMisuseReporter } from "../runtime/misuse-reporter.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { activeContract, validateOperationRequest, validateProtocolIdentity, } from "../runtime/operation-runtime.js";
 import { mapValidationOutcome, VALIDATION_OUTCOME_MESSAGES, } from "../runtime/outcome-mapper.js";
+import { isRecord } from "../runtime/record.guard.js";
 import { encodeOperationArgumentsForWire } from "./operation-arguments-encoder.js";
 import { computeOperationFingerprint, isOperationFingerprint, } from "./operation-fingerprint.js";
 import { validateSqlStatement } from "./sql-statement.validator.js";
@@ -24,6 +25,32 @@ const CALLER_PLAN = { source: "caller" };
 const STEP_ARGUMENTS_POLICY = {
     mirror: (value) => Object.hasOwn(value, "$ref"),
 };
+export function capturePlanAtCall(plan) {
+    const refused = new Map();
+    if (typeof plan !== "object" || plan === null) {
+        return { plan, refused };
+    }
+    try {
+        const mirrored = mirrorCallerData(plan, {
+            copyAt: (path) => path.length === 3 &&
+                path[0] === "operations" &&
+                typeof path[1] === "number" &&
+                path[2] === "args"
+                ? STEP_ARGUMENTS_POLICY
+                : undefined,
+            refused: (path, error) => {
+                refused.set(path[1], error);
+            },
+        });
+        return { plan: mirrored, refused };
+    }
+    catch (error) {
+        if (error instanceof AvCallerDataError) {
+            return { plan, refused };
+        }
+        throw error;
+    }
+}
 function captureSteps(operations, operationCount, planArguments) {
     const steps = [];
     const statements = planArguments.source === "owned" ? planArguments.statements : undefined;
@@ -78,9 +105,6 @@ const OPERATION_KEYS = [
     "args",
     "fingerprint",
 ];
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function operationKeyFailure(contract, step, operation) {
     const { resource, family, variant } = step;
     const issue = typeof family === "string" && typeof variant === "string"
@@ -173,7 +197,7 @@ function* relationTraversals(contract, resourceName, value, path) {
         }
         return;
     }
-    if (!isObject(value)) {
+    if (!isRecord(value)) {
         return;
     }
     for (const [key, entry] of Object.entries(value)) {
@@ -189,7 +213,7 @@ function* relationTraversals(contract, resourceName, value, path) {
     }
 }
 function* operationTraversals(contract, request, index) {
-    if (!isObject(request.arguments)) {
+    if (!isRecord(request.arguments)) {
         return;
     }
     const root = planOperationArgumentsPath(index);
@@ -203,7 +227,7 @@ function* operationTraversals(contract, request, index) {
 function deletedResources(contract, request, index) {
     const deleted = request.family === "delete" ? [request.resource] : [];
     for (const traversal of operationTraversals(contract, request, index)) {
-        if (isObject(traversal.value) &&
+        if (isRecord(traversal.value) &&
             Object.hasOwn(traversal.value, "$delete")) {
             deleted.push(traversal.field.target);
         }

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

@@ -1,10 +1,8 @@
 import { lookupField, lookupOwn, lookupResource, } from "../contracts/contract-lookup.js";
 import { planOperationArgumentsPath } from "../runtime/error-boundary.js";
-import { isPlainRecord, referenceOperandShape, } from "../runtime/scalar-runtime.js";
+import { isPlainRecord, isRecord } from "../runtime/record.guard.js";
+import { referenceOperandShape } from "../runtime/scalar-runtime.js";
 import { routeTransactionReferenceCandidate, } from "./transaction-reference.js";
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function at(position, ...segments) {
     return { ...position, path: [...position.path, ...segments] };
 }
@@ -23,7 +21,7 @@ function collectValue(field, shape, value, path, candidates, written = false) {
     return true;
 }
 function collectKey(position, selector, candidates) {
-    if (!isObject(selector)) {
+    if (!isRecord(selector)) {
         return;
     }
     const resource = lookupResource(position.contract, position.resource);
@@ -61,7 +59,7 @@ function collectScalarFilter(field, filter, path, candidates) {
     }
 }
 function collectWhere(position, where, candidates) {
-    if (!isObject(where)) {
+    if (!isRecord(where)) {
         return;
     }
     const resource = lookupResource(position.contract, position.resource);
@@ -87,7 +85,7 @@ function collectWhere(position, where, candidates) {
             if (field.cardinality === "one") {
                 collectWhere(target, value, candidates);
             }
-            else if (isObject(value)) {
+            else if (isRecord(value)) {
                 for (const operator of ["some", "every", "none"]) {
                     if (Object.hasOwn(value, operator)) {
                         collectWhere(at(target, operator), value[operator], candidates);
@@ -107,7 +105,7 @@ function eachEntry(position, operand, visit) {
     visit(position, operand);
 }
 function collectRelationDirectives(position, edge, value, candidates) {
-    if (!isObject(value)) {
+    if (!isRecord(value)) {
         return;
     }
     const target = { ...position, resource: edge.target };
@@ -129,7 +127,7 @@ function collectRelationDirectives(position, edge, value, candidates) {
             case "$delete":
             case "$upsert":
                 eachEntry(directivePosition, operand, (entryPosition, entry) => {
-                    if (!isObject(entry)) {
+                    if (!isRecord(entry)) {
                         return;
                     }
                     const where = at(entryPosition, "where");
@@ -150,7 +148,7 @@ function collectRelationDirectives(position, edge, value, candidates) {
     }
 }
 function collectData(position, data, candidates) {
-    if (!isObject(data)) {
+    if (!isRecord(data)) {
         return;
     }
     const resource = lookupResource(position.contract, position.resource);

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

@@ -3,14 +3,14 @@ import type { SemanticOperationArguments } from "../operations/operation-validat
 import type { AvValidationIssue } from "../operations/validation-code.js";
 import type { ValidatedSqlStatement } from "./sql-statement.js";
 import type { ValidatedTransactionOperation } from "./transaction-plan-validator.js";
-export type ResolvedTransactionArguments = {
+type ResolvedTransactionArguments = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
 } | {
     readonly ok: false;
     readonly issues: readonly AvValidationIssue[];
 };
-export type ResolvedSqlStatement = {
+type ResolvedSqlStatement = {
     readonly ok: true;
     readonly statement: AvAdapterSqlStatement;
 } | {
@@ -38,3 +38,4 @@ export declare function resolveSqlStatement(statement: ValidatedSqlStatement, re
  * alter the source's committed result.
  */
 export declare function resolveTransactionReferences(operation: ValidatedTransactionOperation, results: readonly unknown[]): ResolvedTransactionArguments;
+export {};

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

@@ -1,9 +1,7 @@
 import { validationIssue } from "../operations/validation-code.js";
+import { isRecord } from "../runtime/record.guard.js";
 import { copyScalarFieldValue } from "../runtime/scalar-runtime.js";
 import { replaceTransactionSlotValues } from "./transaction-slot-writer.js";
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function unresolvedIssue(path) {
     return validationIssue("V1018", [...path, "$ref", "path"], "Transaction reference resolved to no value.");
 }

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,