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

package/dist/runtime/scalar-runtime.js

@@ -1,13 +1,20 @@
+import { shapeOfField } from "../avz/json-shape.registry.js";
+import { AVZ_FORMATS } from "../config/framework-field-definition.js";
+import { FILTER_MODES, } from "../contracts/capability.js";
 import { lookupField, lookupOwn, lookupResource, } from "../contracts/contract-lookup.js";
 import { decodeBase64, WIRE_SCALAR_PATTERNS, } from "../contracts/wire-scalar-format.js";
-import { shapeOfField } from "../json/json-shape.registry.js";
 import { routeTransactionReferenceCandidate, } from "../transactions/transaction-reference.js";
-import { Decimal } from "./decimal.js";
+import { AvDecimal, isAvDecimal } from "./decimal.js";
+import { fieldCheckIssues } from "./field-check.evaluator.js";
 const INT_MIN = -(2 ** 31);
 const INT_MAX = 2 ** 31 - 1;
 const BIGINT_MIN = -(2n ** 63n);
 const BIGINT_MAX = 2n ** 63n - 1n;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const NAMED_FORMATS = new Set(AVZ_FORMATS);
+function isNamedFormat(format) {
+    return NAMED_FORMATS.has(format);
+}
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -24,6 +31,10 @@ function issue(code, path, message) {
 function typeIssue(path, expected) {
     return issue("V1001", path, `Value must be ${expected}.`);
 }
+const UNSENT_READ_VALUE_MESSAGE = "Value must not be undefined: it would be left out, and the request would reach more rows.";
+export function unsentReadValueIssue(path) {
+    return issue("V1001", path, UNSENT_READ_VALUE_MESSAGE);
+}
 function formatIssue(path, expected) {
     return issue("V1003", path, `Value must use ${expected}.`);
 }
@@ -39,7 +50,7 @@ function materializeJsonPath(root, link) {
     segments.reverse();
     return [...root, ...segments];
 }
-function normalizeJsonValue(value, path, seen) {
+export function normalizeJsonValue(value, path, seen) {
     const issues = [];
     let root;
     const stack = [
@@ -83,18 +94,14 @@ function normalizeJsonValue(value, path, seen) {
             const normalized = [];
             task.emit(normalized);
             stack.push({ kind: "leave", container: current });
-            const entries = [];
-            current.forEach((entry, index) => {
-                entries.push([index, entry]);
-            });
-            for (let cursor = entries.length - 1; cursor >= 0; cursor -= 1) {
-                const entry = entries[cursor];
+            for (let index = current.length - 1; index >= 0; index -= 1) {
+                const entry = current[index];
                 stack.push({
                     kind: "visit",
-                    value: entry[1],
-                    link: { parent: task.link, segment: entry[0] },
+                    value: entry === undefined ? null : entry,
+                    link: { parent: task.link, segment: index },
                     emit: (child) => {
-                        normalized.push(child);
+                        normalized[index] = child;
                     },
                 });
             }
@@ -112,7 +119,7 @@ function normalizeJsonValue(value, path, seen) {
         const normalized = {};
         task.emit(normalized);
         stack.push({ kind: "leave", container: current });
-        const entries = Object.entries(current);
+        const entries = Object.entries(current).filter((entry) => entry[1] !== undefined);
         for (let cursor = entries.length - 1; cursor >= 0; cursor -= 1) {
             const entry = entries[cursor];
             stack.push({
@@ -231,10 +238,9 @@ function normalizeScalarAtom(contract, field, value, origin, path, allowNull) {
             break;
         case "decimal":
             if (origin === "application") {
-                normalized =
-                    value instanceof Decimal
-                        ? { ok: true, value }
-                        : { ok: false, issues: [typeIssue(path, "an Aventara Decimal")] };
+                normalized = isAvDecimal(value)
+                    ? { ok: true, value }
+                    : { ok: false, issues: [typeIssue(path, "an Aventara Decimal")] };
             }
             else if (typeof value !== "string") {
                 normalized = {
@@ -244,7 +250,7 @@ function normalizeScalarAtom(contract, field, value, origin, path, allowNull) {
             }
             else {
                 try {
-                    normalized = { ok: true, value: new Decimal(value) };
+                    normalized = { ok: true, value: new AvDecimal(value) };
                 }
                 catch {
                     normalized = {
@@ -359,9 +365,21 @@ export function normalizeScalarFieldValue(contract, field, value, origin, path)
         });
         return issues.length > 0
             ? { ok: false, issues }
-            : { ok: true, value: normalized };
+            : heldToFormat(field, { ok: true, value: normalized }, origin, path);
     }
-    return normalizeScalarAtom(contract, field, value, origin === "runtime" ? "application" : origin, path, field.nullable);
+    return heldToFormat(field, normalizeScalarAtom(contract, field, value, origin === "runtime" ? "application" : origin, path, field.nullable), origin, path);
+}
+function heldToFormat(field, normalized, origin, path) {
+    const format = field.format;
+    if (origin !== "runtime" ||
+        !normalized.ok ||
+        format === undefined ||
+        format === "uuid" ||
+        !isNamedFormat(format)) {
+        return normalized;
+    }
+    const issues = fieldCheckIssues([{ check: "string_format", format }], normalized.value, "string", path, field.list);
+    return issues.length === 0 ? normalized : { ok: false, issues };
 }
 export function jsonShapeIssues(field, value, path, position = "value") {
     if (field.json === undefined || value === null || value === undefined) {
@@ -385,7 +403,6 @@ function normalizeWrittenValue(contract, field, value, origin, path, issues) {
         issues.push(...result.issues);
         return undefined;
     }
-    issues.push(...jsonShapeIssues(field, result.value, path));
     return result.value;
 }
 function normalizeWrittenElement(contract, field, value, origin, path, issues) {
@@ -394,7 +411,6 @@ function normalizeWrittenElement(contract, field, value, origin, path, issues) {
         issues.push(...result.issues);
         return undefined;
     }
-    issues.push(...jsonShapeIssues(field, result.value, path, "entry"));
     return result.value;
 }
 const SCALAR_ATOM_COPIERS = {
@@ -429,6 +445,11 @@ export function copyScalarFieldValue(field, value) {
 function normalizeListElement(contract, field, value, origin, path) {
     return normalizeScalarAtom(contract, field, value, origin, path, false);
 }
+function normalizeFilterEntry(contract, field, value, origin, path) {
+    return value === undefined
+        ? { ok: false, issues: [unsentReadValueIssue(path)] }
+        : normalizeListElement(contract, field, value, origin, path);
+}
 function mergeResult(result, issues) {
     if (result.ok) {
         return result.value;
@@ -436,7 +457,7 @@ function mergeResult(result, issues) {
     issues.push(...result.issues);
     return undefined;
 }
-export const REFERENCE_OPERANDS = Object.freeze({
+const REFERENCE_OPERANDS = Object.freeze({
     equals: "value",
     not: "value",
     lt: "nonNullValue",
@@ -465,10 +486,40 @@ const NULL_OPERAND_OPERATORS = new Set([
     "arrayStartsWith",
     "arrayEndsWith",
 ]);
+const KEYWORD_OPERANDS = Object.freeze({
+    mode: (operand, path, issues) => {
+        if (!FILTER_MODES.includes(operand)) {
+            issues.push(typeIssue(path, '"default", "sensitive" or "insensitive"'));
+        }
+    },
+    isEmpty: (operand, path, issues) => {
+        if (typeof operand !== "boolean") {
+            issues.push(typeIssue(path, "a boolean"));
+        }
+    },
+    path: (operand, path, issues) => {
+        if (!Array.isArray(operand)) {
+            issues.push(typeIssue(path, "an array of strings"));
+            return;
+        }
+        for (let index = 0; index < operand.length; index += 1) {
+            if (operand[index] === undefined) {
+                issues.push(unsentReadValueIssue([...path, index]));
+            }
+            else if (typeof operand[index] !== "string") {
+                issues.push(typeIssue([...path, index], "a string"));
+            }
+        }
+    },
+});
 function normalizeScalarFilter(contract, field, value, origin, path, issues, references = false) {
     if (isKeptReference(references, value)) {
         return value;
     }
+    if (value === undefined) {
+        issues.push(unsentReadValueIssue(path));
+        return value;
+    }
     if (!isPlainRecord(value)) {
         return mergeResult(normalizeScalarFieldValue(contract, field, value, origin, path), issues);
     }
@@ -479,11 +530,17 @@ function normalizeScalarFilter(contract, field, value, origin, path, issues, ref
     const normalized = cloneRecord(value);
     for (const [operator, operand] of Object.entries(value)) {
         const operandPath = [...path, operator];
+        if (operand === undefined) {
+            issues.push(unsentReadValueIssue(operandPath));
+            continue;
+        }
         if (operand === null && !acceptsNullOperand(operator)) {
             issues.push(typeIssue(operandPath, "non-null"));
             continue;
         }
-        if (operator === "mode" || operator === "isEmpty" || operator === "path") {
+        const keyword = lookupOwn(KEYWORD_OPERANDS, operator);
+        if (keyword !== undefined) {
+            keyword(operand, operandPath, issues);
             continue;
         }
         if (referenceOperandShape(operator) !== undefined &&
@@ -499,14 +556,14 @@ function normalizeScalarFilter(contract, field, value, origin, path, issues, ref
                 issues.push(typeIssue(operandPath, "an array"));
                 continue;
             }
-            normalized[operator] = operand.map((entry, index) => mergeResult(normalizeListElement(contract, field, entry, origin, [
+            normalized[operator] = operand.map((entry, index) => mergeResult(normalizeFilterEntry(contract, field, entry, origin, [
                 ...operandPath,
                 index,
             ]), issues));
             continue;
         }
         if (operator === "has") {
-            normalized[operator] = mergeResult(normalizeListElement(contract, field, operand, origin, operandPath), issues);
+            normalized[operator] = mergeResult(normalizeFilterEntry(contract, field, operand, origin, operandPath), issues);
             continue;
         }
         if (operator === "hasEvery" || operator === "hasSome") {
@@ -514,7 +571,7 @@ function normalizeScalarFilter(contract, field, value, origin, path, issues, ref
                 issues.push(typeIssue(operandPath, "an array"));
                 continue;
             }
-            normalized[operator] = operand.map((entry, index) => mergeResult(normalizeListElement(contract, field, entry, origin, [
+            normalized[operator] = operand.map((entry, index) => mergeResult(normalizeFilterEntry(contract, field, entry, origin, [
                 ...operandPath,
                 index,
             ]), issues));
@@ -523,6 +580,12 @@ function normalizeScalarFilter(contract, field, value, origin, path, issues, ref
         if ("scalar" in field.type &&
             field.type.scalar === "json" &&
             (operator.startsWith("string") || operator.startsWith("array"))) {
+            if (operator.startsWith("string")) {
+                if (typeof operand !== "string") {
+                    issues.push(typeIssue(operandPath, "a string"));
+                }
+                continue;
+            }
             const jsonResult = normalizeJsonValue(operand, operandPath, new Set());
             normalized[operator] = mergeResult(jsonResult, issues);
             continue;
@@ -587,6 +650,10 @@ function normalizeUniqueSelector(contract, resourceName, selector, origin, path,
     const normalized = cloneRecord(selector);
     for (const [fieldName, value] of Object.entries(selector)) {
         const field = lookupField(resource, fieldName);
+        if (field?.kind === "scalar" && value === undefined) {
+            issues.push(unsentReadValueIssue([...path, fieldName]));
+            continue;
+        }
         if (field?.kind === "scalar" && !isKeptReference(references, value)) {
             normalized[fieldName] = mergeResult(normalizeScalarFieldValue(contract, field, value, origin, [
                 ...path,
@@ -679,9 +746,9 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
     const normalized = cloneRecord(value);
     for (const [directive, operand] of Object.entries(value)) {
         const directivePath = [...path, directive];
-        const entries = edge.cardinality === "many" && Array.isArray(operand)
-            ? operand
-            : [operand];
+        const listed = edge.cardinality === "many" && Array.isArray(operand);
+        const entries = listed ? operand : [operand];
+        const entryPath = (index) => listed ? [...directivePath, index] : directivePath;
         if (directive === "$create") {
             normalized[directive] =
                 edge.cardinality === "many" && Array.isArray(operand)
@@ -714,8 +781,8 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
                 }
                 return {
                     ...entry,
-                    where: normalizeUniqueSelector(contract, edge.target, entry.where, origin, [...directivePath, index, "where"], issues, references),
-                    create: normalizeMutationData(contract, edge.target, entry.create, origin, [...directivePath, index, "create"], issues, references),
+                    where: normalizeUniqueSelector(contract, edge.target, entry.where, origin, [...entryPath(index), "where"], issues, references),
+                    create: normalizeMutationData(contract, edge.target, entry.create, origin, [...entryPath(index), "create"], issues, references),
                 };
             });
             normalized[directive] =
@@ -733,10 +800,10 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
                     ...entry,
                     ...(entry.where !== undefined
                         ? {
-                            where: normalizeWhere(contract, edge.target, entry.where, origin, [...directivePath, index, "where"], issues, references),
+                            where: normalizeWhere(contract, edge.target, entry.where, origin, [...entryPath(index), "where"], issues, references),
                         }
                         : {}),
-                    data: normalizeMutationData(contract, edge.target, entry.data, origin, [...directivePath, index, "data"], issues, references),
+                    data: normalizeMutationData(contract, edge.target, entry.data, origin, [...entryPath(index), "data"], issues, references),
                 };
             });
             normalized[directive] =
@@ -752,7 +819,7 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
                 }
                 return {
                     ...entry,
-                    where: normalizeWhere(contract, edge.target, entry.where, origin, [...directivePath, index, "where"], issues, references),
+                    where: normalizeWhere(contract, edge.target, entry.where, origin, [...entryPath(index), "where"], issues, references),
                 };
             });
             normalized[directive] =
@@ -770,11 +837,11 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
                     ...entry,
                     ...(entry.where !== undefined
                         ? {
-                            where: normalizeUniqueSelector(contract, edge.target, entry.where, origin, [...directivePath, index, "where"], issues, references),
+                            where: normalizeUniqueSelector(contract, edge.target, entry.where, origin, [...entryPath(index), "where"], issues, references),
                         }
                         : {}),
-                    create: normalizeMutationData(contract, edge.target, entry.create, origin, [...directivePath, index, "create"], issues, references),
-                    update: normalizeMutationData(contract, edge.target, entry.update, origin, [...directivePath, index, "update"], issues, references),
+                    create: normalizeMutationData(contract, edge.target, entry.create, origin, [...entryPath(index), "create"], issues, references),
+                    update: normalizeMutationData(contract, edge.target, entry.update, origin, [...entryPath(index), "update"], issues, references),
                 };
             });
             normalized[directive] =

package/dist/runtime/unsent-value.normalizer.d.ts

@@ -0,0 +1,15 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationFamily } from "../operations/operation-identity.js";
+/**
+ * One operation's arguments with every write record's unsent fields removed — a
+ * field whose value is `undefined`, at any depth of nested write data the
+ * Contract's `maxNestingDepth` admits — and
+ * nothing else changed (see the module note): `where`, selectors and every other
+ * member are left as they are. The same object when nothing was unsent; otherwise
+ * a copy of each container on the way, never a write into `args`. Total over
+ * malformed input.
+ */
+export declare function withoutUnsentWriteValues(contract: AvContract, request: {
+    readonly resource: string;
+    readonly family: AvOperationFamily;
+}, args: unknown): unknown;

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/deferred-operation.d.ts

@@ -1,12 +1,10 @@
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { ExecutionOptions } from "../runtime/execution-options.js";
-import type { OperationFailureResponse } from "../runtime/operation-response.js";
-import type { TransactionReference } from "./transaction-reference.js";
-import type { TransactionCommittedResponse } from "./transaction-response.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvExecutionOptions } from "../runtime/execution-options.js";
+import type { AvTransactionReference } from "./transaction-reference.js";
 /** An operation fingerprint: `fp1:` and a hash of the operation and its arguments. */
 export type OperationFingerprint = `fp1:${string}`;
 /** One serializable transaction-plan operation node. */
-export type DeferredOperation = OperationIdentity & {
+export type DeferredOperation = AvOperationIdentity & {
     readonly resource: string;
     readonly args: unknown;
     readonly fingerprint: OperationFingerprint;
@@ -17,34 +15,51 @@ export type TransactionPlan = {
 };
 declare const OPERATION_RESULT: unique symbol;
 declare const OPERATION_HANDLE: unique symbol;
+/** The origin a handle's builder gives it: `appTx`'s or `clientTx`'s. */
+type HandleOrigin = "application" | "client";
+type AnyOrigin = any;
 /** Standard-library shapes that are objects but never a projected result row. */
 export type BuiltinNonRow = Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | PromiseLike<unknown> | ArrayBufferView;
 /**
  * The single row behind a result type, or `never` when the result is not one
  * referenceable row.
  */
-export type SingleRowResult<T> = NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends (...args: never[]) => unknown ? never : NonNullable<T> extends BuiltinNonRow ? never : NonNullable<T> extends object ? Extract<keyof NonNullable<T>, string> extends never ? never : NonNullable<T> : never;
+export type AvSingleRowResult<T> = NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends (...args: never[]) => unknown ? never : NonNullable<T> extends BuiltinNonRow ? never : NonNullable<T> extends object ? Extract<keyof NonNullable<T>, string> extends never ? never : NonNullable<T> : never;
 /** The field names a result row can be referenced by. */
-export type ReferenceableField<T> = Extract<keyof SingleRowResult<T>, string>;
+export type AvReferenceableField<T> = Extract<keyof AvSingleRowResult<T>, string>;
 /** Builds a `$ref` to one field of this handle's row, typed as that field. */
-export type ReferenceBuilder<T> = <F extends ReferenceableField<T>>(field: F) => TransactionReference<SingleRowResult<T>[F]>;
+export type AvReferenceBuilder<T> = <F extends AvReferenceableField<T>>(field: F) => AvTransactionReference<AvSingleRowResult<T>[F]>;
 /** Contributes `$ref` only where the result is a referenceable single row. */
-export type OperationReferenceSurface<T> = [SingleRowResult<T>] extends [never] ? {} : {
-    readonly $ref: ReferenceBuilder<T>;
+export type AvOperationReferenceSurface<T> = [AvSingleRowResult<T>] extends [
+    never
+] ? {} : {
+    readonly $ref: AvReferenceBuilder<T>;
 };
-/** An opaque deferred-operation handle. */
-export type Operation<T> = {
-    readonly [OPERATION_HANDLE]: true;
+/**
+ * The opaque part of every deferred-operation handle: the result type `T` its
+ * transaction slot resolves to, and the origin of the builder that made it
+ * (`appTx` is `"application"`, `clientTx` is `"client"`; left out, either).
+ * Type-level only: a handle holds neither at runtime.
+ */
+export interface AvOperationHandle<T, Origin extends HandleOrigin = AnyOrigin> {
+    readonly [OPERATION_HANDLE]: Origin;
     readonly [OPERATION_RESULT]?: T;
-} & OperationReferenceSurface<T>;
+}
+/**
+ * An opaque deferred-operation handle: its result type and origin
+ * ({@link AvOperationHandle}), and `$ref` where the result is one row.
+ */
+export type AvOperation<T, Origin extends HandleOrigin = AnyOrigin> = AvOperationHandle<T, Origin> & AvOperationReferenceSurface<T>;
 /** Ordered results of a tuple of handles, positionally typed. */
-export type TransactionResults<Ops extends readonly Operation<unknown>[]> = {
-    readonly [I in keyof Ops]: Ops[I] extends Operation<infer R> ? R : never;
+export type AvTransactionResults<Ops extends readonly AvOperation<unknown>[]> = {
+    readonly [I in keyof Ops]: Ops[I] extends AvOperation<infer R> ? R : never;
 };
 /**
  * `framework.transaction`'s type. It infers the handle tuple without `as const`
- * and resolves the committed response (`A1009`) with each handle's result in
- * plan order, or the failure response.
+ * and resolves each handle's result in plan order once the transaction
+ * committed, or throws its failure as the `AvError` subclass of the code's class
+ * (`cause.operation` names the failing step). The handles are all `appTx`
+ * handles or all `clientTx` handles: a list that mixes them is a type error.
  */
-export type TransactionRunner = <const Ops extends readonly Operation<unknown>[]>(operations: Ops, options?: ExecutionOptions) => Promise<TransactionCommittedResponse<TransactionResults<Ops>> | OperationFailureResponse>;
+export type AvTransactionRunner = <const Ops extends readonly AvOperation<unknown, "application">[] | readonly AvOperation<unknown, "client">[]>(operations: Ops, options?: AvExecutionOptions) => Promise<AvTransactionResults<Ops>>;
 export {};

package/dist/transactions/operation-arguments-encoder.d.ts

@@ -1,7 +1,7 @@
-import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
 /** Encodes validated application arguments into the wire scalar form. */
-export declare function encodeOperationArgumentsForWire(contract: Contract, operation: OperationIdentity & {
+export declare function encodeOperationArgumentsForWire(contract: AvContract, operation: AvOperationIdentity & {
     readonly resource: string;
 }, args: SemanticOperationArguments): unknown;

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 { Decimal } 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 Decimal ? 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,