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

package/dist/internal.js

@@ -11,6 +11,7 @@ export { LIFECYCLE_TRAITS } from "./contracts/lifecycle-trait.js";
 export { isOperationVariantAvailable, projectionScopeOf, writeScopeOf, } from "./contracts/resource-operations.js";
 export { BUILT_IN_SCALARS } from "./contracts/scalar.js";
 export { TRANSACTION_CAPABILITIES } from "./contracts/transaction-capability.js";
+export { DATABASE_REFUSALS } from "./operations/database-refusal.js";
 export { VALIDATION_CODES } from "./operations/validation-code.js";
 export { mcpFailureReporterOf } from "./runtime/diagnostics-reporter.js";
 export { FRAMEWORK_ERROR_CLASS_OF } from "./runtime/framework-error-class.table.js";

package/dist/operations/database-refusal.d.ts

@@ -0,0 +1,51 @@
+import type { AvValidationCode } from "./validation-code.js";
+/**
+ * Why the database refused a caller's value, each with the validation code and the
+ * issue message an adapter answers it with.
+ */
+export declare const DATABASE_REFUSALS: {
+    readonly tooLong: {
+        readonly code: "V1004";
+        readonly message: "The database refused this value: it is longer than the database can hold for its column.";
+    };
+    readonly outOfRange: {
+        readonly code: "V1004";
+        readonly message: "The database refused this value: it is outside the range its column can hold.";
+    };
+    readonly datetimeOutOfRange: {
+        readonly code: "V1004";
+        readonly message: "The database refused this value: the date and time is outside the range the database can hold.";
+    };
+    readonly divisionByZero: {
+        readonly code: "V1004";
+        readonly message: "The database refused this value: it divides by zero.";
+    };
+    readonly computedNull: {
+        readonly code: "V1004";
+        readonly message: "The database refused this value: the write computes no value for a column that requires one, as a division by zero does.";
+    };
+    readonly invalidInput: {
+        readonly code: "V1001";
+        readonly message: "The database refused this value: it is not valid input for its column's type.";
+    };
+    readonly nulInText: {
+        readonly code: "V1001";
+        readonly message: "The database refused this value: its text cannot contain the NUL character (U+0000).";
+    };
+    readonly nulInJson: {
+        readonly code: "V1001";
+        readonly message: "The database refused this value: its JSON cannot contain the NUL character (U+0000).";
+    };
+    readonly trailingEscape: {
+        readonly code: "V1001";
+        readonly message: "The database refused this value: a text match cannot end with the escape character \\.";
+    };
+    readonly backReference: {
+        readonly code: "V1012";
+        readonly message: "The data source refused this nested write: a record written through a relation cannot write that relation or its reference fields back.";
+    };
+};
+/** A reason the database refused a caller's value: a key of {@link DATABASE_REFUSALS}. */
+export type AvDatabaseRefusal = keyof typeof DATABASE_REFUSALS;
+/** Whether `message` is the message of a database refusal answered under `code`. */
+export declare function isDatabaseRefusalMessage(code: AvValidationCode, message: string): boolean;

package/dist/operations/database-refusal.js

@@ -0,0 +1,45 @@
+export const DATABASE_REFUSALS = {
+    tooLong: {
+        code: "V1004",
+        message: "The database refused this value: it is longer than the database can hold for its column.",
+    },
+    outOfRange: {
+        code: "V1004",
+        message: "The database refused this value: it is outside the range its column can hold.",
+    },
+    datetimeOutOfRange: {
+        code: "V1004",
+        message: "The database refused this value: the date and time is outside the range the database can hold.",
+    },
+    divisionByZero: {
+        code: "V1004",
+        message: "The database refused this value: it divides by zero.",
+    },
+    computedNull: {
+        code: "V1004",
+        message: "The database refused this value: the write computes no value for a column that requires one, as a division by zero does.",
+    },
+    invalidInput: {
+        code: "V1001",
+        message: "The database refused this value: it is not valid input for its column's type.",
+    },
+    nulInText: {
+        code: "V1001",
+        message: "The database refused this value: its text cannot contain the NUL character (U+0000).",
+    },
+    nulInJson: {
+        code: "V1001",
+        message: "The database refused this value: its JSON cannot contain the NUL character (U+0000).",
+    },
+    trailingEscape: {
+        code: "V1001",
+        message: "The database refused this value: a text match cannot end with the escape character \\.",
+    },
+    backReference: {
+        code: "V1012",
+        message: "The data source refused this nested write: a record written through a relation cannot write that relation or its reference fields back.",
+    },
+};
+export function isDatabaseRefusalMessage(code, message) {
+    return Object.values(DATABASE_REFUSALS).some((refusal) => refusal.code === code && refusal.message === message);
+}

package/dist/operations/operation-arguments.d.ts

@@ -1,4 +1,4 @@
-import type { AvProjectionScope, AvRelationMutationDirective, AvScalarFilterOperator, AvScalarMutationDirective, AvWriteScope } from "../contracts/capability.js";
+import type { AvProjectionScope, AvRelationMutationDirective, AvScalarFilterOperator, AvScalarMutationDirective, AvWriteScope, ScalarFilterMode } from "../contracts/capability.js";
 import type { AvContract } from "../contracts/contract.js";
 import type { AvProjectionScopes, AvScalarField } from "../contracts/field.js";
 import type { AvScalarValueType, FieldAtom, ScalarForms } from "../contracts/scalar-value-type.js";
@@ -82,7 +82,7 @@ type SlotReference<C extends AvContract, K extends AvResourceKey<C>, F extends A
  * read a JSON object as the operators, so their value forms leave it out.
  */
 type JsonObject = Extract<AvJsonValue, {
-    readonly [key: string]: AvJsonValue;
+    readonly [key: string]: AvJsonValue | undefined;
 }>;
 /**
  * The field-independent shape of one scalar filter: any value, or an object of the
@@ -106,14 +106,17 @@ type FieldSlotReferences<C extends AvContract, K extends AvResourceKey<C>, F ext
  * whole value; `in`, `notIn`, `hasEvery` and `hasSome` take a list of entries;
  * `has` one entry; a `json` field's `string*`/`array*` operand a
  * {@link AvJsonValue}; `not` a nested operator object of the same operators, or
- * a value where `equals` is one of them. `mode`, `isEmpty` and `path` are passed to the adapter as given.
- * Only `equals`, `not` and the `json` `array*` operands take `null`. Inside a
- * transaction plan every operand but `mode`, `isEmpty`, `path` and the `json`
- * ones may be a `$ref` of the shape it holds (`References`).
+ * a value where `equals` is one of them. `mode` takes one of the modes the
+ * field offers at this level (`LevelMode`), `isEmpty` a boolean, `path` a list of
+ * JSON keys and a `json` field's `string*` operand a string: none of these is a
+ * value of the field. Only `equals`, `not` and the `json` `array*` operands take
+ * `null`. Inside a transaction plan every
+ * operand but `mode`, `isEmpty`, `path` and the `json` ones may be a `$ref` of
+ * the shape it holds (`References`).
  */
-type ScalarFilterOperands<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator> = {
+type ScalarFilterOperands<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, PathMode extends ScalarFilterMode, LevelMode extends ScalarFilterMode> = {
     equals: Value | References["value"];
-    not: ("equals" extends Operator ? Exclude<Value, JsonObject> | References["value"] : never) | ScalarFilterOperators<Value, Atom, Json, References, Operator>;
+    not: NegatedValue<Value, References, Operator> | ScalarFilterOperators<Value, Atom, Json, References, Operator, Mode, PathMode>;
     in: readonly Atom[] | References["entries"];
     notIn: readonly Atom[] | References["entries"];
     lt: Exclude<Value, null> | References["nonNullValue"];
@@ -123,26 +126,67 @@ type ScalarFilterOperands<Value, Atom, Json, References extends Readonly<Record<
     contains: Exclude<Value, null> | References["nonNullValue"];
     startsWith: Exclude<Value, null> | References["nonNullValue"];
     endsWith: Exclude<Value, null> | References["nonNullValue"];
-    mode: unknown;
+    mode: LevelMode;
     has: Atom | References["entry"];
     hasEvery: readonly Atom[] | References["entries"];
     hasSome: readonly Atom[] | References["entries"];
-    isEmpty: unknown;
-    path: unknown;
-    stringContains: Exclude<Json, null>;
-    stringStartsWith: Exclude<Json, null>;
-    stringEndsWith: Exclude<Json, null>;
+    isEmpty: boolean;
+    path: readonly string[];
+    stringContains: string;
+    stringStartsWith: string;
+    stringEndsWith: string;
     arrayContains: Json;
     arrayStartsWith: Json;
     arrayEndsWith: Json;
 };
 /**
  * A scalar filter's operator object: the operators `Operator` names — the ones
- * the field's `filter` member advertises — each with its operand.
+ * the field's `filter` member advertises — each with its operand. Where `path`
+ * is one of them, an object that names it takes `PathMode`, and one that does
+ * not takes `Mode`. An object that names `mode` or `path` names a comparing
+ * operator beside it.
  */
-type ScalarFilterOperators<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator> = Readonly<Partial<Pick<ScalarFilterOperands<Value, Atom, Json, References, Operator>, Operator>>>;
+type ScalarFilterOperators<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, PathMode extends ScalarFilterMode> = ScalarFilterLevel<ReadonlyOperands<Value, Atom, Json, References, Operator, Mode, PathMode, Mode>, Operator, Mode, NegatedValue<Value, References, Operator>, "path" extends Operator ? {
+    readonly path?: never;
+} : unknown> | ("path" extends Operator ? ScalarFilterOperatorsAtPath<ReadonlyOperands<Value, Atom, Json, References, Operator, Mode, PathMode, PathMode>, Operator, PathMode, NegatedValue<Value, References, Operator>> : never);
+/** {@link ScalarFilterOperands}, each operand read-only. */
+type ReadonlyOperands<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, PathMode extends ScalarFilterMode, LevelMode extends ScalarFilterMode> = Readonly<ScalarFilterOperands<Value, Atom, Json, References, Operator, Mode, PathMode, LevelMode>>;
+/** The operators of a level that compare something: all but `mode` and `path`. */
+type ComparingOperator<Operator extends AvScalarFilterOperator> = Exclude<Operator, "mode" | "path">;
+/** `not`'s value arm: equality negated, offered only where `equals` is. */
+type NegatedValue<Value, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator> = "equals" extends Operator ? Exclude<Value, JsonObject> | References["value"] : never;
+/** A level's comparing operators, each optional. */
+type ComparingOperators<Operands extends Readonly<Record<AvScalarFilterOperator, unknown>>, Operator extends AvScalarFilterOperator> = Partial<Pick<Operands, ComparingOperator<Operator>>>;
+/**
+ * A level's comparing operators with at least one of them present; `not` is
+ * one only with a value (an object under `not` compares at its own level).
+ */
+type SomeComparingOperator<Operands extends Readonly<Record<AvScalarFilterOperator, unknown>>, Operator extends AvScalarFilterOperator, Negated> = ({
+    [Key in Exclude<ComparingOperator<Operator>, "not">]-?: Pick<Operands, Key>;
+}[Exclude<ComparingOperator<Operator>, "not">] & ComparingOperators<Operands, Operator>) | ("not" extends Operator ? {
+    readonly not: Negated;
+} & Partial<Pick<Operands, Exclude<ComparingOperator<Operator>, "not">>> : never);
+/**
+ * One operator object that names no `path`: without `mode`, any of its comparing
+ * operators; with `mode` (one of `Mode`), at least one of them.
+ */
+type ScalarFilterLevel<Operands extends Readonly<Record<AvScalarFilterOperator, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, Negated, PathKey> = ("mode" extends Operator ? (ComparingOperators<Operands, Operator> & {
+    readonly mode?: never;
+}) | (SomeComparingOperator<Operands, Operator, Negated> & {
+    readonly mode?: Mode;
+}) : ComparingOperators<Operands, Operator>) & PathKey;
+/** An operator object that names `path`: `PathMode`, and a comparing operator. */
+type ScalarFilterOperatorsAtPath<Operands extends Readonly<Record<AvScalarFilterOperator, unknown>>, Operator extends AvScalarFilterOperator, PathMode extends ScalarFilterMode, Negated> = SomeComparingOperator<Operands, Operator, Negated> & {
+    readonly path: readonly string[];
+} & ("mode" extends Operator ? {
+    readonly mode?: PathMode;
+} : unknown);
 /** The filter operators field `F` advertises: `never` when it advertises none. */
 type ScalarFilterOperatorAt<C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>> = Extract<CapabilityTokens<C, K, F, "filter", UnrestrictedProjection>, AvScalarFilterOperator>;
+/** The `mode` operands field `F` takes in an operator object without `path`. */
+type ScalarFilterModeAt<C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>> = "default" | Extract<CapabilityTokens<C, K, F, "filterModes", UnrestrictedProjection>, ScalarFilterMode>;
+/** The `mode` operands field `F` takes in an operator object that names `path`. */
+type ScalarPathFilterModeAt<C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>> = "pathFilterModes" extends keyof CapabilitiesOf<C, K, F> ? "default" | Extract<CapabilityTokens<C, K, F, "pathFilterModes", UnrestrictedProjection>, ScalarFilterMode> : ScalarFilterModeAt<C, K, F>;
 /**
  * One scalar field's filter under `Forms`: a shorthand value where the field
  * advertises `equals`, or an object of the operators it advertises. Inside a
@@ -153,7 +197,7 @@ type ScalarFilterOperatorAt<C extends AvContract, K extends AvResourceKey<C>, F
  */
 type ScalarFilterFor<C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = ("equals" extends ScalarFilterOperatorAt<C, K, F> ? ScalarFilterShorthand<ScalarValueAt<C, K, F, Forms>> | SlotReference<C, K, F, ReferenceForms, "value"> : never) | ScalarFilterOperators<ScalarValueAt<C, K, F, Forms>, ScalarAtomAt<C, K, F, Forms>, ScalarFieldAt<C, K, F>["type"] extends {
     readonly scalar: "json";
-} ? AvJsonValue : ScalarValueAt<C, K, F, Forms>, FieldSlotReferences<C, K, F, ReferenceForms>, ScalarFilterOperatorAt<C, K, F>>;
+} ? AvJsonValue : ScalarValueAt<C, K, F, Forms>, FieldSlotReferences<C, K, F, ReferenceForms>, ScalarFilterOperatorAt<C, K, F>, ScalarFilterModeAt<C, K, F>, ScalarPathFilterModeAt<C, K, F>>;
 /** The scalar fields of `K` a `where` can name: those advertising an operator. */
 type ScalarFilterableKey<C extends AvContract, K extends AvResourceKey<C>> = {
     [F in ScalarFieldKeyOf<C, K>]: [ScalarFilterOperatorAt<C, K, F>] extends [
@@ -330,11 +374,11 @@ type ConnectOrCreateEntry<C extends AvContract, K extends AvResourceKey<C>, F ex
 }>;
 type ToOneUpdateEntry<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     where?: NestedWriteWhereInput<C, K, F, Forms, ReferenceForms>;
-    data: AvUpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
+    data: AvUpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>;
 }>;
 type ToManyUpdateEntry<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     where: NestedWriteWhereInput<C, K, F, Forms, ReferenceForms>;
-    data: AvUpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
+    data: AvUpdateDataInput<C, RelationTarget<C, K, F>, "bulkWrite", Forms, ReferenceForms, readonly [K, F]>;
 }>;
 type ToOneDeleteEntry<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = true | Readonly<{
     where?: NestedWriteWhereInput<C, K, F, Forms, ReferenceForms>;
@@ -345,12 +389,12 @@ type ToManyDeleteEntry<C extends AvContract, K extends AvResourceKey<C>, F exten
 type ToOneUpsertEntry<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     where?: AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
     create: AvCreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>;
-    update: AvUpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
+    update: AvUpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>;
 }>;
 type ToManyUpsertEntry<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     where: AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
     create: AvCreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>;
-    update: AvUpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
+    update: AvUpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>;
 }>;
 type RelationDirectiveValue<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Directive extends AvRelationMutationDirective, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Directive extends "$create" ? ManyOrOne<C, K, F, AvCreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>> : Directive extends "$connect" ? ManyOrOne<C, K, F, AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>> : Directive extends "$connectOrCreate" ? ManyOrOne<C, K, F, ConnectOrCreateEntry<C, K, F, Forms, ReferenceForms>> : Directive extends "$disconnect" ? RelationCardinality<C, K, F> extends "one" ? true : AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> | readonly AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>[] : Directive extends "$set" ? RelationCardinality<C, K, F> extends "one" ? AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> | null : readonly AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>[] : Directive extends "$update" ? RelationCardinality<C, K, F> extends "one" ? ToOneUpdateEntry<C, K, F, Forms, ReferenceForms> : ManyOrOne<C, K, F, ToManyUpdateEntry<C, K, F, Forms, ReferenceForms>> : Directive extends "$delete" ? RelationCardinality<C, K, F> extends "one" ? ToOneDeleteEntry<C, K, F, Forms, ReferenceForms> : ManyOrOne<C, K, F, ToManyDeleteEntry<C, K, F, Forms, ReferenceForms>> : Directive extends "$upsert" ? RelationCardinality<C, K, F> extends "one" ? ToOneUpsertEntry<C, K, F, Forms, ReferenceForms> : ManyOrOne<C, K, F, ToManyUpsertEntry<C, K, F, Forms, ReferenceForms>> : never;
 declare const NO_ADVERTISED_MEMBER: unique symbol;
@@ -377,22 +421,46 @@ type ScalarDirectiveOperand<C extends AvContract, K extends AvResourceKey<C>, F
  */
 type ScalarMutationActionFor<C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms> = [
     Extract<CapabilityTokens<C, K, F, Stage, Scope>, AvScalarMutationDirective>
-] extends [never] ? never : Readonly<{
-    [Directive in Extract<CapabilityTokens<C, K, F, Stage, Scope>, AvScalarMutationDirective>]?: ScalarDirectiveOperand<C, K, F, Directive, Forms>;
-}>;
+] extends [never] ? never : OneDirective<Extract<CapabilityTokens<C, K, F, Stage, Scope>, AvScalarMutationDirective>, C, K, F, Forms>;
+type OneDirective<Tokens extends AvScalarMutationDirective, C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>, Forms extends ScalarForms> = {
+    [Directive in Tokens]: Readonly<{
+        [Key in Directive]: ScalarDirectiveOperand<C, K, F, Key, Forms>;
+    } & {
+        [Other in Exclude<Tokens, Directive>]?: never;
+    }>;
+}[Tokens];
 /**
  * Each writable scalar takes its value under `Forms`, or a directive object of
  * the directives it advertises at this stage — or, in a transaction plan's
  * top-level data, a `$ref` to a source of the same type.
  */
-type ScalarMutationFields<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
-    [F in WritableScalarKey<C, K, Stage, Scope>]?: ScalarValueAt<C, K, F, Forms> | ScalarMutationActionFor<C, K, F, Stage, Scope, Forms> | SlotReference<C, K, F, ReferenceForms, "value">;
+type ScalarMutationFields<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms, Via extends ParentEdge = never> = Readonly<{
+    [F in Exclude<WritableScalarKey<C, K, Stage, Scope>, LoopbackRefused<C, K, Stage, Via>>]?: ScalarValueAt<C, K, F, Forms> | ScalarMutationActionFor<C, K, F, Stage, Scope, Forms> | SlotReference<C, K, F, ReferenceForms, "value">;
 }>;
-type RelationMutationFields<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
-    [F in WritableRelationKey<C, K, Stage, Scope>]?: RelationMutationActionFor<C, K, F & RelationFieldKeyOf<C, K>, Stage, Scope, Forms, ReferenceForms>;
+type RelationMutationFields<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms, Via extends ParentEdge = never> = Readonly<{
+    [F in Exclude<WritableRelationKey<C, K, Stage, Scope>, LoopbackRefused<C, K, Stage, Via>>]?: RelationMutationActionFor<C, K, F & RelationFieldKeyOf<C, K>, Stage, Scope, Forms, ReferenceForms>;
 }>;
 /** A relation edge a nested create is reached through: `[parent, relation]`. */
 type ParentEdge = readonly [string, string];
+/** The other end of `Via`'s relation, as the Contract pairs it; `never` when it does not. */
+type LoopbackOf<C extends AvContract, Via> = Via extends readonly [
+    infer Parent,
+    infer Relation
+] ? Parent extends AvResourceKey<C> ? Relation extends keyof C["resources"][Parent]["fields"] ? C["resources"][Parent]["fields"][Relation] extends {
+    readonly inverse: infer Inverse extends string;
+} ? Inverse : never : never : never : never;
+/** The fields `K`'s relation `Relation` states hold its reference; `never` when it states none. */
+type ReferenceFieldsOf<C extends AvContract, K extends AvResourceKey<C>, Relation extends string> = Relation extends keyof C["resources"][K]["fields"] ? C["resources"][K]["fields"][Relation] extends {
+    readonly referenceFields: readonly (infer Field extends string)[];
+} ? Field : never : never;
+/**
+ * The members a record of `K` reached through `Via` cannot write at `Stage`:
+ * the other end of `Via`'s relation and the fields that hold its reference,
+ * unless the Contract admits that relation at the `"loopback"` position.
+ */
+type LoopbackRefused<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Via> = [Via] extends [never] ? never : LoopbackOf<C, Via> extends infer Loopback extends string ? [
+    Extract<Loopback, WritableRelationKey<C, K, Stage, "loopback">>
+] extends [never] ? Loopback | ReferenceFieldsOf<C, K, Loopback> : never : never;
 /** The names a requirement list holds; `never` when the member is absent. */
 type RequirementNames<Requirements, Member extends PropertyKey> = Requirements extends {
     readonly [P in Member]?: infer List;
@@ -450,9 +518,12 @@ type CreateRequirementPresence<C extends AvContract, K extends AvResourceKey<C>,
  * reference fields — never both. `Via` is the `[parent, relation]` a nested
  * create is reached through: what that parent supplies is not required.
  */
-export type AvCreateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never, Via extends ParentEdge = never> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "create", Scope, Forms, ReferenceForms> & RelationMutationFields<C, K, "create", Scope, Forms, ReferenceForms>>> & CreateRequirementPresence<C, K, Scope, Via>;
-/** An `update` data argument, at one write position. See {@link AvCreateDataInput}. */
-export type AvUpdateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "update", Scope, Forms, ReferenceForms> & RelationMutationFields<C, K, "update", Scope, Forms, ReferenceForms>>>;
+export type AvCreateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never, Via extends ParentEdge = never> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "create", Scope, Forms, ReferenceForms, Via> & RelationMutationFields<C, K, "create", Scope, Forms, ReferenceForms, Via>>> & CreateRequirementPresence<C, K, Scope, Via>;
+/**
+ * An `update` data argument, at one write position. See {@link AvCreateDataInput};
+ * `Via` is the `[parent, relation]` a nested update is reached through.
+ */
+export type AvUpdateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never, Via extends ParentEdge = never> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "update", Scope, Forms, ReferenceForms, Via> & RelationMutationFields<C, K, "update", Scope, Forms, ReferenceForms, Via>>>;
 type QueryProjectionArgs<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope, Forms extends ScalarForms> = ProjectionChoice<C, K, Scope, false, Forms>;
 /**
  * Every standard operation's argument object, with each argument at its