@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

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

@@ -0,0 +1,204 @@
+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 { 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] };
+}
+function collectValue(field, shape, value, path, candidates, written = false) {
+    const route = routeTransactionReferenceCandidate(value);
+    if (route.kind === "ordinary") {
+        return false;
+    }
+    candidates.push({
+        path,
+        field,
+        shape,
+        written,
+        candidate: route.candidate,
+    });
+    return true;
+}
+function collectKey(position, selector, candidates) {
+    if (!isObject(selector)) {
+        return;
+    }
+    const resource = lookupResource(position.contract, position.resource);
+    for (const [fieldName, value] of Object.entries(selector)) {
+        const field = lookupField(resource, fieldName);
+        if (field?.kind === "scalar") {
+            collectValue(field, "nonNullValue", value, [...position.path, fieldName], candidates);
+        }
+    }
+}
+function collectKeys(position, selectors, candidates) {
+    if (Array.isArray(selectors)) {
+        selectors.forEach((selector, index) => {
+            collectKey(at(position, index), selector, candidates);
+        });
+        return;
+    }
+    collectKey(position, selectors, candidates);
+}
+function collectScalarFilter(field, filter, path, candidates) {
+    if (collectValue(field, "value", filter, path, candidates) ||
+        !isPlainRecord(filter)) {
+        return;
+    }
+    for (const [operator, operand] of Object.entries(filter)) {
+        const operandPath = [...path, operator];
+        if (operator === "not") {
+            collectScalarFilter(field, operand, operandPath, candidates);
+            continue;
+        }
+        const shape = referenceOperandShape(operator);
+        if (shape !== undefined) {
+            collectValue(field, shape, operand, operandPath, candidates);
+        }
+    }
+}
+function collectWhere(position, where, candidates) {
+    if (!isObject(where)) {
+        return;
+    }
+    const resource = lookupResource(position.contract, position.resource);
+    for (const [key, value] of Object.entries(where)) {
+        if (key === "AND" || key === "OR") {
+            if (Array.isArray(value)) {
+                value.forEach((entry, index) => {
+                    collectWhere(at(position, key, index), entry, candidates);
+                });
+            }
+            continue;
+        }
+        if (key === "NOT") {
+            collectWhere(at(position, key), value, candidates);
+            continue;
+        }
+        const field = lookupField(resource, key);
+        if (field?.kind === "scalar") {
+            collectScalarFilter(field, value, [...position.path, key], candidates);
+        }
+        else if (field?.kind === "relation") {
+            const target = { ...at(position, key), resource: field.target };
+            if (field.cardinality === "one") {
+                collectWhere(target, value, candidates);
+            }
+            else if (isObject(value)) {
+                for (const operator of ["some", "every", "none"]) {
+                    if (Object.hasOwn(value, operator)) {
+                        collectWhere(at(target, operator), value[operator], candidates);
+                    }
+                }
+            }
+        }
+    }
+}
+function eachEntry(position, operand, visit) {
+    if (Array.isArray(operand)) {
+        operand.forEach((entry, index) => {
+            visit(at(position, index), entry);
+        });
+        return;
+    }
+    visit(position, operand);
+}
+function collectRelationDirectives(position, edge, value, candidates) {
+    if (!isObject(value)) {
+        return;
+    }
+    const target = { ...position, resource: edge.target };
+    for (const [directive, operand] of Object.entries(value)) {
+        const directivePosition = at(target, directive);
+        switch (directive) {
+            case "$connect":
+            case "$disconnect":
+            case "$set":
+                collectKeys(directivePosition, operand, candidates);
+                break;
+            case "$create":
+                eachEntry(directivePosition, operand, (entryPosition, entry) => {
+                    collectData(entryPosition, entry, candidates);
+                });
+                break;
+            case "$connectOrCreate":
+            case "$update":
+            case "$delete":
+            case "$upsert":
+                eachEntry(directivePosition, operand, (entryPosition, entry) => {
+                    if (!isObject(entry)) {
+                        return;
+                    }
+                    const where = at(entryPosition, "where");
+                    if (directive === "$update" || directive === "$delete") {
+                        collectWhere(where, entry.where, candidates);
+                    }
+                    else {
+                        collectKey(where, entry.where, candidates);
+                    }
+                    for (const branch of ["create", "update", "data"]) {
+                        if (Object.hasOwn(entry, branch)) {
+                            collectData(at(entryPosition, branch), entry[branch], candidates);
+                        }
+                    }
+                });
+                break;
+        }
+    }
+}
+function collectData(position, data, candidates) {
+    if (!isObject(data)) {
+        return;
+    }
+    const resource = lookupResource(position.contract, position.resource);
+    for (const [fieldName, value] of Object.entries(data)) {
+        const field = lookupField(resource, fieldName);
+        if (field?.kind === "scalar") {
+            collectValue(field, "value", value, [...position.path, fieldName], candidates, true);
+        }
+        else if (field?.kind === "relation") {
+            collectRelationDirectives(at(position, fieldName), field, value, candidates);
+        }
+    }
+}
+export function collectTransactionReferenceCandidates(contract, request, index, args) {
+    const candidates = [];
+    const root = {
+        contract,
+        resource: request.resource,
+        path: planOperationArgumentsPath(index),
+    };
+    const where = lookupOwn(args, "where");
+    if (request.variant === "unique") {
+        collectKey(at(root, "where"), where, candidates);
+    }
+    else {
+        collectWhere(at(root, "where"), where, candidates);
+    }
+    collectKey(at(root, "cursor"), lookupOwn(args, "cursor"), candidates);
+    if (request.family === "create") {
+        const data = lookupOwn(args, "data");
+        if (request.variant === "many" || request.variant === "count") {
+            if (Array.isArray(data)) {
+                data.forEach((entry, dataIndex) => {
+                    collectData(at(root, "data", dataIndex), entry, candidates);
+                });
+            }
+        }
+        else {
+            collectData(at(root, "data"), data, candidates);
+        }
+    }
+    else if (request.family === "update") {
+        collectData(at(root, "data"), lookupOwn(args, "data"), candidates);
+    }
+    else if (request.family === "upsert") {
+        for (const stage of ["create", "update"]) {
+            collectData(at(root, stage), lookupOwn(args, stage), candidates);
+        }
+    }
+    return candidates;
+}

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

@@ -1,13 +1,30 @@
+import type { AvAdapterSqlStatement } from "../adapters/adapter-sql-statement.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+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 = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
+export type ResolvedSqlStatement = {
+    readonly ok: true;
+    readonly statement: AvAdapterSqlStatement;
+} | {
+    readonly ok: false;
+    readonly issues: readonly AvValidationIssue[];
+};
+/**
+ * The statement a validated SQL step hands the Adapter: every `$ref` value read from
+ * the results ledger, exactly as an operation's slot is — the source's final data,
+ * copied by the source field's own codec — and then bound like any other value. A
+ * source row lacking the field is `V1018` at the value, before the statement runs.
+ * Issue paths are relative to the step (`["values", k, "$ref", "path"]`).
+ */
+export declare function resolveSqlStatement(statement: ValidatedSqlStatement, results: readonly unknown[]): ResolvedSqlStatement;
 /**
  * Substitutes every validated `$ref` placeholder of one operation from the results
  * ledger: each earlier operation's final `data`, exactly the value at its index in the

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

@@ -4,23 +4,40 @@ 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.");
+}
+export function resolveSqlStatement(statement, results) {
+    const values = [];
+    for (const [position, value] of statement.values.entries()) {
+        if (value.kind === "value") {
+            values.push(value.value);
+            continue;
+        }
+        const row = results[value.operation];
+        if (!isRecord(row) || !Object.hasOwn(row, value.field)) {
+            return { ok: false, issues: [unresolvedIssue(["values", position])] };
+        }
+        values.push(copyScalarFieldValue(value.source, row[value.field]));
+    }
+    return {
+        ok: true,
+        statement: Object.freeze({
+            strings: statement.strings,
+            values: Object.freeze(values),
+        }),
+    };
+}
 export function resolveTransactionReferences(operation, results) {
     const substitutions = [];
     for (const slot of operation.references) {
         const { operation: source, path: [segment], } = slot.reference.$ref;
         const row = results[source];
         if (!isRecord(row) || !Object.hasOwn(row, segment)) {
-            return {
-                ok: false,
-                issues: [
-                    validationIssue("V1018", [...slot.path, "$ref", "path"], "Transaction reference resolved to no value."),
-                ],
-            };
+            return { ok: false, issues: [unresolvedIssue(slot.path)] };
         }
-        substitutions.push({
-            path: slot.path,
-            value: copyScalarFieldValue(slot.field, row[segment]),
-        });
+        const value = copyScalarFieldValue(slot.source, row[segment]);
+        substitutions.push({ path: slot.path, value });
     }
     return {
         ok: true,

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

@@ -1,5 +1,9 @@
-import type { OperationFailureResponse } from "../runtime/operation-response.js";
-import type { CandidateTransactionOperation, TransactionReferenceSlot, ValidatedTransactionOperation } from "./transaction-plan-validator.js";
+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 { CandidateTransactionOperation, TransactionReferenceSlot, ValidatedTransactionStep } from "./transaction-plan-validator.js";
+type Path = readonly (string | number)[];
 type ReferenceValidationResult = {
     readonly ok: true;
     readonly references: readonly TransactionReferenceSlot[];
@@ -7,8 +11,34 @@ type ReferenceValidationResult = {
     readonly requestArguments: unknown;
 } | {
     readonly ok: false;
-    readonly response: OperationFailureResponse;
+    readonly response: AvOperationFailureResponse;
 };
+/** The `V1016` refusal of a reference's source index, at its `operation` member. */
+export declare function invalidSourceIndexIssue(operationPath: Path): AvValidationIssue;
+/**
+ * The validated step a reference names, or `undefined` when its index is no
+ * 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 = {
+    readonly ok: true;
+    readonly field: AvField<AvContract>;
+} | {
+    readonly ok: false;
+    readonly issue: AvValidationIssue;
+};
+/**
+ * Reads the field a reference's one path segment names from its source step,
+ * holding the source to what a reference may read: one row (not a `many` or
+ * `count` result, not a SQL step's rows), and a field in its actual projection,
+ * never a reducer. The field is read under the source's own Contract: in a plan
+ * that mixes origins, a source field the referencing step's layer hides is still
+ * the source's to read. Assignability to a destination is the caller's.
+ */
+export declare function referenceSourceField(source: ValidatedTransactionStep, segment: string, pathPath: Path): ReferenceSourceRead;
 /** Validates every passive reference candidate before operation fingerprinting. */
-export declare function validateTransactionReferences(operation: CandidateTransactionOperation, earlier: readonly ValidatedTransactionOperation[]): ReferenceValidationResult;
+export declare function validateTransactionReferences(operation: CandidateTransactionOperation, earlier: readonly ValidatedTransactionStep[]): ReferenceValidationResult;
 export {};

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

@@ -141,25 +141,74 @@ function containsUnpairedSurrogate(value) {
     }
     return false;
 }
-function sameType(source, destination) {
+function sameScalar(source, destination) {
     if ("scalar" in source.type) {
-        if (!("scalar" in destination.type)) {
-            return false;
-        }
-        if (source.type.scalar !== destination.type.scalar) {
-            return false;
-        }
+        return ("scalar" in destination.type &&
+            source.type.scalar === destination.type.scalar);
     }
-    else {
-        if (!("enum" in destination.type)) {
-            return false;
-        }
-        if (source.type.enum !== destination.type.enum) {
-            return false;
-        }
+    return ("enum" in destination.type && source.type.enum === destination.type.enum);
+}
+function isAssignable(source, destination, shape) {
+    if (!sameScalar(source, destination)) {
+        return false;
+    }
+    switch (shape) {
+        case "value":
+            return (source.list === destination.list &&
+                !(source.nullable && !destination.nullable));
+        case "nonNullValue":
+            return source.list === destination.list && !source.nullable;
+        case "entry":
+            return !source.list && !source.nullable;
+        case "entries":
+            return source.list && !source.nullable;
     }
-    return (source.list === destination.list &&
-        !(source.nullable && !destination.nullable));
+}
+export function invalidSourceIndexIssue(operationPath) {
+    return validationIssue("V1016", operationPath, "Transaction reference operation index is invalid.");
+}
+export function referenceSourceAt(earlier, sourceIndex, referencingIndex) {
+    if (typeof sourceIndex !== "number" ||
+        !Number.isInteger(sourceIndex) ||
+        sourceIndex < 0 ||
+        sourceIndex >= referencingIndex) {
+        return undefined;
+    }
+    const source = earlier[sourceIndex];
+    return source !== undefined && source.index === sourceIndex
+        ? source
+        : undefined;
+}
+export 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) {
+    if (source.kind === "sql") {
+        return { ok: false, issue: sqlSourceIssue(pathPath) };
+    }
+    if (source.request.variant === "many" || source.request.variant === "count") {
+        return {
+            ok: false,
+            issue: validationIssue("V1010", pathPath, "Transaction reference source has no addressable single-row projection."),
+        };
+    }
+    const projection = source.projection;
+    if (projection?.reducers.some((reducer) => reducer === segment)) {
+        return {
+            ok: false,
+            issue: validationIssue("V1011", pathPath, "Transaction reference source is not a scalar field."),
+        };
+    }
+    const field = projection === undefined || !projection.requested.includes(segment)
+        ? undefined
+        : lookupField(lookupResource(source.contract, projection.resource), segment);
+    if (field === undefined) {
+        return {
+            ok: false,
+            issue: validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."),
+        };
+    }
+    return { ok: true, field };
 }
 const CANDIDATE_KEYS = new Set(["$ref"]);
 const REFERENCE_KEYS = new Set(["operation", "fingerprint", "path"]);
@@ -185,19 +234,15 @@ export function validateTransactionReferences(operation, earlier) {
             return failure(sourceIndexProperty.issue, operation.index);
         }
         const sourceIndex = sourceIndexProperty.value;
-        const source = typeof sourceIndex === "number" && Number.isInteger(sourceIndex)
-            ? earlier[sourceIndex]
-            : undefined;
-        if (typeof sourceIndex !== "number" ||
-            !Number.isInteger(sourceIndex) ||
-            sourceIndex < 0 ||
-            sourceIndex >= operation.index ||
-            source === undefined ||
-            source.index !== sourceIndex) {
-            return failure(validationIssue("V1016", operationPath, "Transaction reference operation index is invalid."), operation.index);
+        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, "V1017", refPath);
+        const fingerprintProperty = inspectOwnDataProperty(referenceInspection.value, "fingerprint", fingerprintPath, "V1000", refPath);
         if (!fingerprintProperty.ok) {
             return failure(fingerprintProperty.issue, operation.index);
         }
@@ -219,27 +264,18 @@ export function validateTransactionReferences(operation, earlier) {
         if (containsUnpairedSurrogate(segment)) {
             return failure(validationIssue("V1010", pathPath, "Transaction reference path contains invalid Unicode."), operation.index);
         }
-        if (source.request.variant === "many" ||
-            source.request.variant === "count") {
-            return failure(validationIssue("V1010", pathPath, "Transaction reference source has no addressable single-row projection."), operation.index);
-        }
-        const projection = source.projection;
-        if (projection?.reducers.some((reducer) => reducer === segment)) {
-            return failure(validationIssue("V1011", pathPath, "Transaction reference source is not a scalar field."), operation.index);
-        }
-        if (projection === undefined || !projection.requested.includes(segment)) {
-            return failure(validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."), operation.index);
-        }
-        const sourceField = lookupField(lookupResource(source.contract, projection.resource), segment);
-        if (sourceField === undefined) {
-            return failure(validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."), operation.index);
+        const sourceRead = referenceSourceField(source, segment, pathPath);
+        if (!sourceRead.ok) {
+            return failure(sourceRead.issue, operation.index);
         }
-        if (sourceField.kind !== "scalar" || !sameType(sourceField, slot.field)) {
+        const sourceField = sourceRead.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);
         }
         const reference = Object.freeze({
             $ref: Object.freeze({
-                operation: sourceIndex,
+                operation: source.index,
                 fingerprint,
                 path: Object.freeze([segment]),
             }),
@@ -247,6 +283,9 @@ export function validateTransactionReferences(operation, earlier) {
         references.push({
             path: Object.freeze([...slot.path]),
             field: slot.field,
+            shape: slot.shape,
+            written: slot.written,
+            source: sourceField,
             reference,
         });
     }

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

@@ -1,8 +1,8 @@
-import type { WriteScope } from "../contracts/capability.js";
-import type { Contract } from "../contracts/contract.js";
+import type { AvWriteScope } from "../contracts/capability.js";
+import type { AvContract } from "../contracts/contract.js";
 import type { ScalarForms } from "../contracts/scalar-value-type.js";
-import type { CreateDataInput, OperationArgumentsFor, ResourceKey, UpdateDataInput, WritableRelationKey } from "../operations/operation-arguments.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvCreateDataInput, AvOperationArgumentsFor, AvResourceKey, AvUpdateDataInput } from "../operations/operation-arguments.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { OperationFingerprint } from "./deferred-operation.js";
 declare const REFERENCE_VALUE: unique symbol;
 /** Any object with a `$ref` key, before it is validated as a reference. */
@@ -13,7 +13,7 @@ export type TransactionReferenceCandidate = {
  * A reference to a field of an earlier operation's result in the same
  * transaction plan: `{ $ref: { operation, fingerprint, path } }`.
  */
-export type TransactionReference<Value = unknown> = {
+export type AvTransactionReference<Value = unknown> = {
     readonly $ref: {
         readonly operation: number;
         readonly fingerprint: OperationFingerprint;
@@ -38,68 +38,40 @@ export declare function routeTransactionReferenceCandidate(value: unknown): Tran
 /** Whether `value` is an object with a `$ref` key; it is not validated here. */
 export declare function isTransactionReferenceCandidate(value: unknown): value is TransactionReferenceCandidate;
 /** Whether `value` is a complete `$ref` object. */
-export declare function isTransactionReferenceObject(value: unknown): value is TransactionReference;
+export declare function isTransactionReferenceObject(value: unknown): value is AvTransactionReference;
 /**
  * A scalar mutation value inside a plan: the value itself, or a reference to an
  * earlier operation's field of that same type.
  */
-export type TransactionScalarValue<Value> = Value | TransactionReference<Value>;
+export type TransactionScalarValue<Value> = Value | AvTransactionReference<Value>;
 /**
- * A scalar value inside a plan, or a `$ref` to a field of the same type. A
- * reference is typed by the application form of its source field, because a
- * source's final data is always in application forms.
+ * What a Transaction Slot holds of its destination field, which decides the source
+ * fields a reference there accepts — always the same scalar or enum, no coercion:
+ *
+ * - `"value"` — the field's whole value, where a `null` means something: a mutation
+ *   value, or an equality filter (`null` matches the rows the field is unset on). A
+ *   nullable source only into a nullable field.
+ * - `"nonNullValue"` — the field's whole value, where a `null` identifies or orders
+ *   nothing: a unique key, a `cursor`, an ordering or text comparison. The source is
+ *   never nullable.
+ * - `"entry"` — one entry of a list field (`has`): a non-null, non-list source.
+ * - `"entries"` — a list of entries (`in`, `notIn`, `hasEvery`, `hasSome`): a
+ *   non-null list source.
  */
-type ReferenceableValue<Value, ReferenceValue> = Value | TransactionReference<ReferenceValue>;
-/** `Data`'s member `Key`, or `never` when it has none. */
-type MemberOf<Data, Key> = Key extends keyof Data ? Data[Key] : never;
+export type TransactionSlotShape = "value" | "nonNullValue" | "entry" | "entries";
 /**
- * Create data whose top-level scalar fields may hold a `$ref`, under stated
- * scalar forms.
+ * Create data inside a transaction plan, at one write position: its scalar values
+ * and the unique keys its relation directives name may hold a `$ref`. The default
+ * is the unrestricted position, as on `AvCreateDataInput`.
  */
-export type ReferenceableCreateData<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
-    [F in keyof CreateDataInput<C, K, Scope, Forms>]: F extends WritableRelationKey<C, K, "create", Scope> ? CreateDataInput<C, K, Scope, Forms>[F] : ReferenceableValue<CreateDataInput<C, K, Scope, Forms>[F], MemberOf<CreateDataInput<C, K, Scope, ReferenceForms>, F>>;
-}>;
+export type TransactionCreateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = "nested"> = AvCreateDataInput<C, K, Scope, ScalarForms, ScalarForms>;
+/** Update data inside a transaction plan. See {@link TransactionCreateDataInput}. */
+export type TransactionUpdateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = "nested"> = AvUpdateDataInput<C, K, Scope, ScalarForms, ScalarForms>;
 /**
- * Update data whose top-level scalar fields may hold a `$ref`, under stated
- * scalar forms.
+ * Operation arguments inside a transaction plan, under one value form and one
+ * reference form: `AvOperationArgumentsFor` with its reference positions opened.
  */
-export type ReferenceableUpdateData<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
-    [F in keyof UpdateDataInput<C, K, Scope, Forms>]: F extends WritableRelationKey<C, K, "update", Scope> ? UpdateDataInput<C, K, Scope, Forms>[F] : ReferenceableValue<UpdateDataInput<C, K, Scope, Forms>[F], MemberOf<UpdateDataInput<C, K, Scope, ReferenceForms>, F>>;
-}>;
-/**
- * Only top-level scalar fields accept a `$ref`; a relation field keeps its relation
- * mutation action, where a `$ref` is an ordinary invalid value.
- */
-export type TransactionCreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = ReferenceableCreateData<C, K, Scope, ScalarForms, ScalarForms>;
-/** See {@link TransactionCreateDataInput}. */
-export type TransactionUpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = ReferenceableUpdateData<C, K, Scope, ScalarForms, ScalarForms>;
-/** Operation arguments inside a transaction plan, under stated scalar forms. */
-export type ReferenceableArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = I extends {
-    family: "create";
-    variant: "one";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "data"> & {
-    data: ReferenceableCreateData<C, K, "nested", Forms, ReferenceForms>;
-} : I extends {
-    family: "create";
-    variant: "many" | "count";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "data"> & {
-    data: readonly ReferenceableCreateData<C, K, "bulkWrite", Forms, ReferenceForms>[];
-} : I extends {
-    family: "update";
-    variant: "first" | "unique";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "data"> & {
-    data: ReferenceableUpdateData<C, K, "nested", Forms, ReferenceForms>;
-} : I extends {
-    family: "update";
-    variant: "many" | "count";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "data"> & {
-    data: ReferenceableUpdateData<C, K, "bulkWrite", Forms, ReferenceForms>;
-} : I extends {
-    family: "upsert";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "create" | "update"> & {
-    create: ReferenceableCreateData<C, K, "nested", Forms, ReferenceForms>;
-    update: ReferenceableUpdateData<C, K, "nested", Forms, ReferenceForms>;
-} : OperationArgumentsFor<C, K, I, Forms>;
+export type ReferenceableArgumentsFor<C extends AvContract, K extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = AvOperationArgumentsFor<C, K, I, Forms, ReferenceForms>;
 /** Operation arguments inside a transaction plan, no scalar form stated. */
-export type TransactionOperationArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity> = ReferenceableArgumentsFor<C, K, I, ScalarForms, ScalarForms>;
+export type TransactionOperationArgumentsFor<C extends AvContract, K extends AvResourceKey<C>, I extends AvOperationIdentity> = ReferenceableArgumentsFor<C, K, I, ScalarForms, ScalarForms>;
 export {};