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

package/dist/runtime/unsent-value.normalizer.js

@@ -0,0 +1,128 @@
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { isPlainRecord, WRITE_KEYS } from "./field-stage.runtime.js";
+import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "./mutation-planner.js";
+const REMOVE = Symbol("remove");
+const DEPTH_CEILING = 256;
+function rebuilt(record, changes) {
+    const copy = Object.getPrototypeOf(record) === null ? Object.create(null) : {};
+    for (const key of Object.keys(record)) {
+        const value = changes.has(key) ? changes.get(key) : record[key];
+        if (value === REMOVE) {
+            continue;
+        }
+        Object.defineProperty(copy, key, {
+            value,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return copy;
+}
+function eachEntry(value, strip) {
+    if (!Array.isArray(value)) {
+        return strip(value);
+    }
+    let copy;
+    for (let index = 0; index < value.length; index += 1) {
+        if (!(index in value)) {
+            continue;
+        }
+        const entry = value[index];
+        const stripped = strip(entry);
+        if (stripped !== entry) {
+            copy ??= value.slice();
+            copy[index] = stripped;
+        }
+    }
+    return copy ?? value;
+}
+function stripRecord(walk, resourceName, record, depth) {
+    if (depth > walk.depth || !isPlainRecord(record)) {
+        return record;
+    }
+    const resource = lookupResource(walk.contract, resourceName);
+    let changes;
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+        if (value === undefined) {
+            changes ??= new Map();
+            changes.set(key, REMOVE);
+            continue;
+        }
+        const field = lookupField(resource, key);
+        if (field?.kind !== "relation") {
+            continue;
+        }
+        const stripped = stripRelationWrite(walk, field.target, value, depth + 1);
+        if (stripped !== value) {
+            changes ??= new Map();
+            changes.set(key, stripped);
+        }
+    }
+    return changes === undefined ? record : rebuilt(record, changes);
+}
+function stripRelationWrite(walk, target, value, depth) {
+    if (!isPlainRecord(value)) {
+        return value;
+    }
+    let changes;
+    for (const directive of Object.keys(value)) {
+        if (!isRelationMutationDirective(directive)) {
+            continue;
+        }
+        const sites = RELATION_MUTATION_RECORD_SITES[directive];
+        if (sites.length === 0) {
+            continue;
+        }
+        const operand = value[directive];
+        const next = eachEntry(operand, (entry) => {
+            let stripped = entry;
+            for (const site of sites) {
+                if (site.key === undefined) {
+                    stripped = stripRecord(walk, target, stripped, depth);
+                    continue;
+                }
+                if (!isPlainRecord(stripped) || !Object.hasOwn(stripped, site.key)) {
+                    continue;
+                }
+                const inner = stripped[site.key];
+                const record = stripRecord(walk, target, inner, depth);
+                if (record !== inner) {
+                    stripped = rebuilt(stripped, new Map([[site.key, record]]));
+                }
+            }
+            return stripped;
+        });
+        if (next !== operand) {
+            changes ??= new Map();
+            changes.set(directive, next);
+        }
+    }
+    return changes === undefined ? value : rebuilt(value, changes);
+}
+export function withoutUnsentWriteValues(contract, request, args) {
+    const keys = Object.hasOwn(WRITE_KEYS, request.family)
+        ? WRITE_KEYS[request.family]
+        : undefined;
+    if (keys === undefined || !isPlainRecord(args)) {
+        return args;
+    }
+    const walk = {
+        contract,
+        depth: Math.min(contract.limits.maxNestingDepth, DEPTH_CEILING),
+    };
+    let changes;
+    for (const key of keys) {
+        if (!Object.hasOwn(args, key)) {
+            continue;
+        }
+        const value = args[key];
+        const next = eachEntry(value, (entry) => stripRecord(walk, request.resource, entry, 0));
+        if (next !== value) {
+            changes ??= new Map();
+            changes.set(key, next);
+        }
+    }
+    return changes === undefined ? args : rebuilt(args, changes);
+}

package/dist/transactions/operation-arguments-encoder.js

@@ -1,6 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { encodeBase64 } from "../contracts/wire-scalar-format.js";
-import { AvDecimal } from "../runtime/decimal.js";
+import { isAvDecimal } from "../runtime/decimal.js";
 import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "../runtime/mutation-planner.js";
 import { isTransactionReferenceCandidate } from "./transaction-reference.js";
 function isPlainRecord(value) {
@@ -27,9 +27,11 @@ function encodeScalarAtom(field, value) {
         case "bigint":
             return typeof value === "bigint" ? value.toString(10) : value;
         case "decimal":
-            return value instanceof AvDecimal ? value.toString() : value;
+            return isAvDecimal(value) ? value.toString() : value;
         case "datetime":
-            return value instanceof Date ? value.toISOString() : value;
+            return value instanceof Date && !Number.isNaN(value.getTime())
+                ? value.toISOString()
+                : value;
         case "bytes":
             return value instanceof Uint8Array ? encodeBase64(value) : value;
         default:
@@ -282,6 +284,9 @@ function isUniqueOperation(operation) {
             operation.family === "upsert"));
 }
 export function encodeOperationArgumentsForWire(contract, operation, args) {
+    if (!isPlainRecord(args)) {
+        return args;
+    }
     const encoded = cloneRecord(args);
     if (hasOwnWireProperty(args, "where")) {
         encoded.where = isUniqueOperation(operation)

package/dist/transactions/operation-fingerprint.js

@@ -1,4 +1,4 @@
-import { canonicalizeJson } from "../contracts/contract-canonicalizer.js";
+import { canonicalizeWireJson } from "../contracts/contract-canonicalizer.js";
 const OPERATION_FINGERPRINT_PATTERN = /^fp1:[A-Za-z0-9_-]{22}$/;
 function encodeBase64Url(bytes) {
     let binary = "";
@@ -14,7 +14,7 @@ export function isOperationFingerprint(value) {
     return typeof value === "string" && OPERATION_FINGERPRINT_PATTERN.test(value);
 }
 export async function computeOperationFingerprint(node) {
-    const canonical = canonicalizeJson({
+    const canonical = canonicalizeWireJson({
         resource: node.resource,
         family: node.family,
         variant: node.variant,

package/dist/transactions/sql-statement.d.ts

@@ -10,7 +10,7 @@ import type { AvTransactionReference } from "./transaction-reference.js";
  * `${value}::jsonb`), or a `$ref` to an earlier step's field, resolved when the
  * earlier steps have run and then bound like any other value.
  */
-export type SqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
+export type AvSqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
 /**
  * `framework.appTx.$sql`: a developer SQL step, written only as a tagged template —
  * ``framework.appTx.$sql`select pgmq.send('jobs', jsonb_build_object('id', ${ref}))` ``.
@@ -23,7 +23,7 @@ export type SqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
  * SQL step's rows. No guard, pipe, hook, interceptor or filter runs around it: it
  * has no Resource or operation for one to wrap.
  */
-export type SqlStatementBuilder = <Row = unknown>(strings: TemplateStringsArray, ...values: readonly SqlStatementValue[]) => AvOperation<Row[], "application">;
+export type AvSqlStatementBuilder = <Row = unknown>(strings: TemplateStringsArray, ...values: readonly AvSqlStatementValue[]) => AvOperation<Row[], "application">;
 /** One value of a planned SQL step, as the typed runner bound it. */
 export type PlannedSqlValue = {
     readonly kind: "value";
@@ -35,6 +35,14 @@ export type PlannedSqlValue = {
     readonly operation: number;
     readonly field: string;
 }
+/**
+ * A whole value that is a `$ref` control object the caller wrote, mirrored at
+ * the builder: validated as an operation step's reference is.
+ */
+ | {
+    readonly kind: "candidate";
+    readonly candidate: unknown;
+}
 /** A `$ref` placeholder found inside a value, at `path` within it: refused. */
  | {
     readonly kind: "misplaced-reference";

package/dist/transactions/sql-statement.validator.d.ts

@@ -5,7 +5,7 @@ import type { AvOperationFailureResponse } from "../runtime/operation-response.j
 import type { PlannedSqlStatement, ValidatedSqlStatement } from "./sql-statement.js";
 import type { ValidatedTransactionStep } from "./transaction-plan-validator.js";
 type Path = readonly (string | number)[];
-export type SqlStatementValidation = {
+type SqlStatementValidation = {
     readonly ok: true;
     readonly statement: ValidatedSqlStatement;
 } | {
@@ -13,7 +13,7 @@ export type SqlStatementValidation = {
     readonly response: AvOperationFailureResponse;
 };
 /** What validating a SQL step needs from the plan around it. */
-export type SqlStatementValidationContext = {
+type SqlStatementValidationContext = {
     /** The step's position in the plan. */
     readonly index: number;
     /** The steps validated before it, by position. */

package/dist/transactions/sql-statement.validator.js

@@ -1,11 +1,12 @@
 import { validationIssue } from "../operations/validation-code.js";
+import { AvCallerDataError, locateCallerDataError, } from "../runtime/caller-data.copier.js";
 import { refuseCallerData } from "../runtime/caller-data.door.js";
-import { AvDecimal } from "../runtime/decimal.js";
+import { isAvDecimal } from "../runtime/decimal.js";
 import { planStepPath } from "../runtime/error-boundary.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
 import { isPlainRecord, normalizeJsonValue, } from "../runtime/scalar-runtime.js";
-import { invalidSourceIndexIssue, referenceSourceAt, referenceSourceField, } from "./transaction-reference-validator.js";
+import { inspectReferenceCandidate, invalidSourceIndexIssue, referenceSourceAt, referenceSourceField, } from "./transaction-reference-validator.js";
 import { transactionOperationFailure } from "./transaction-response.js";
 function refused(issue, index) {
     return {
@@ -18,7 +19,7 @@ export function normalizeSqlValue(value, path) {
         typeof value === "string" ||
         typeof value === "boolean" ||
         typeof value === "bigint" ||
-        value instanceof AvDecimal ||
+        isAvDecimal(value) ||
         value instanceof Uint8Array) {
         return { ok: true, value };
     }
@@ -56,7 +57,7 @@ export function normalizeSqlValue(value, path) {
     };
 }
 export function validateSqlStatement(statement, context) {
-    const { index, earlier } = context;
+    const { index } = context;
     if (!context.available) {
         const message = "SQL statements are not available on this Adapter.";
         return {
@@ -73,6 +74,22 @@ export function validateSqlStatement(statement, context) {
     if (statement.refused !== undefined) {
         return refused(refuseCallerData(statement.refused, [...planStepPath(index), "values"], { origin: "application", operation: index }, context.misuse), index);
     }
+    try {
+        return validateSqlValues(statement, statement.strings, context);
+    }
+    catch (error) {
+        if (!(error instanceof AvCallerDataError)) {
+            throw error;
+        }
+        return refused(refuseCallerData(locateCallerDataError(error, statement.values.map((planned) => planned.kind === "value"
+            ? planned.value
+            : planned.kind === "candidate"
+                ? planned.candidate
+                : undefined)), [...planStepPath(index), "values"], { origin: "application", operation: index }, context.misuse), index);
+    }
+}
+function validateSqlValues(statement, strings, context) {
+    const { index, earlier } = context;
     const values = [];
     const issues = [];
     for (const [position, planned] of statement.values.entries()) {
@@ -80,6 +97,22 @@ export function validateSqlStatement(statement, context) {
         switch (planned.kind) {
             case "misplaced-reference":
                 return refused(validationIssue("V1010", [...path, ...planned.path, "$ref"], "A transaction reference in a SQL step must be a whole value."), index);
+            case "candidate": {
+                const inspection = inspectReferenceCandidate(planned.candidate, path, earlier, index);
+                if (!inspection.ok) {
+                    return refused(inspection.issue, index);
+                }
+                if (inspection.field.kind !== "scalar" || inspection.field.list) {
+                    return refused(validationIssue("V1011", inspection.pathPath, "Transaction reference source is not a single scalar field."), index);
+                }
+                values.push({
+                    kind: "reference",
+                    operation: inspection.source.index,
+                    field: inspection.segment,
+                    source: inspection.field,
+                });
+                break;
+            }
             case "reference": {
                 const source = referenceSourceAt(earlier, planned.operation, index);
                 if (source === undefined) {
@@ -127,7 +160,7 @@ export function validateSqlStatement(statement, context) {
         statement: {
             kind: "sql",
             index,
-            strings: statement.strings,
+            strings,
             values,
         },
     };

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

@@ -1,18 +1,18 @@
 import type { AvValidationIssue } from "../operations/validation-code.js";
-export type TransactionEnvelopeSchema = {
+type TransactionEnvelopeSchema = {
     readonly required: readonly string[];
     readonly optional?: readonly string[];
     readonly invalidContainerPath: readonly (string | number)[];
     readonly invalidContainerMessage: string;
 };
-export type TransactionEnvelopeInspection = {
+type TransactionEnvelopeInspection = {
     readonly ok: true;
     readonly values: ReadonlyMap<string, unknown>;
 } | {
     readonly ok: false;
     readonly issue: AvValidationIssue;
 };
-export type TransactionOperationsInspection = {
+type TransactionOperationsInspection = {
     readonly ok: true;
     readonly value: object;
     readonly length: number;
@@ -20,7 +20,7 @@ export type TransactionOperationsInspection = {
     readonly ok: false;
     readonly issue: AvValidationIssue;
 };
-export type TransactionOperationEntryInspection = {
+type TransactionOperationEntryInspection = {
     readonly ok: true;
     readonly value: unknown;
 } | {
@@ -39,3 +39,4 @@ export declare function inspectTransactionOperationEntry(operations: object, ind
  * Proxies are unsupported; reflection failures are contained as envelope issues.
  */
 export declare function inspectTransactionEnvelope(value: unknown, schema: TransactionEnvelopeSchema): TransactionEnvelopeInspection;
+export {};

package/dist/transactions/transaction-integrity-error.js

@@ -1,3 +1,4 @@
+import { brandCoreClass } from "../runtime/core-class.brand.js";
 const TRANSACTION_INTEGRITY_MESSAGES = {
     "transaction-unavailable": "Adapter transaction function is unavailable.",
     "resolved-after-abort": "Adapter transaction resolved after the framework requested rollback.",
@@ -15,3 +16,4 @@ export class AvTransactionIntegrityError extends Error {
         this.violation = violation;
     }
 }
+brandCoreClass(AvTransactionIntegrityError, "AvTransactionIntegrityError");

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,10 +1,13 @@
 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 { 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) {
@@ -46,6 +49,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 +98,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 +139,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 +189,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";
@@ -24,6 +24,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;

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 {};