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

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, ToOneRelinkDirective, ToOneRewriteDirective } 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,13 +82,8 @@ 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
- * operator vocabulary.
- */
-export type ScalarFilterInput = unknown | Readonly<Partial<Record<AvScalarFilterOperator, unknown>>>;
 /**
  * A scalar filter's shorthand equality value: the field's value, minus a JSON
  * object.
@@ -106,14 +101,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> = {
+export type AvScalarFilterOperands<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 +121,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, 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 AvScalarFilterOperands}, 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<AvScalarFilterOperands<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 ScalarFilterOperators<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator> = Readonly<Partial<Pick<ScalarFilterOperands<Value, Atom, Json, References, Operator>, Operator>>>;
+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 +192,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 [
@@ -180,7 +219,7 @@ export type AvWhereInput<C extends AvContract, K extends AvResourceKey<C>, Forms
     AND?: readonly AvWhereInput<C, K, Forms, ReferenceForms>[];
     OR?: readonly AvWhereInput<C, K, Forms, ReferenceForms>[];
     NOT?: AvWhereInput<C, K, Forms, ReferenceForms>;
-} & ScalarWhereFields<C, K, Forms, ReferenceForms> & RelationWhereFields<C, K, Forms, ReferenceForms>>;
+}> & ScalarWhereFields<C, K, Forms, ReferenceForms> & RelationWhereFields<C, K, Forms, ReferenceForms>;
 type ActiveIdentifier<C extends AvContract, K extends AvResourceKey<C>> = C["resources"][K]["identifiers"][number];
 type IdentifierObject<C extends AvContract, K extends AvResourceKey<C>, I extends readonly string[], Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     [F in Extract<I[number], AvFieldKey<C, K>>]: ScalarValueAt<C, K, F, Forms> | SlotReference<C, K, F, ReferenceForms, "nonNullValue">;
@@ -291,15 +330,11 @@ type IncludeRelationProjectionEntry<C extends AvContract, K extends AvResourceKe
  * One entry of a `select` argument, at one projection position. The default is
  * the unrestricted position.
  */
-export type AvProjectionEntry<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = SelectableScalarKey<C, K, Scope> | SelectableRelationKey<C, K, Scope> | SelectRelationProjectionEntry<C, K, Scope, Forms> | (AllowCount extends true ? "$count" : never);
+export type AvProjectionEntry<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = SelectableScalarKey<C, K, Scope> | SelectableRelationKey<C, K, Scope> | SelectRelationProjectionEntry<C, K, Scope, Forms> | "$defaults" | (AllowCount extends true ? "$count" : never);
 /** A `select` argument: the fields to return. */
 export type AvSelectInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = readonly AvProjectionEntry<C, K, Scope, AllowCount, Forms>[];
 /** An `include` argument: the relations to return with each row. */
 export type AvIncludeInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, Forms extends ScalarForms = UnstatedForms> = readonly (IncludeRelationKey<C, K, Scope> | IncludeRelationProjectionEntry<C, K, Scope, Forms>)[];
-/** A scalar update directive and its operand, such as `{ $increment: 1 }`. */
-export type ScalarMutationAction = Readonly<Partial<Record<AvScalarMutationDirective, unknown>>>;
-/** A relation write: one or more relation directives and their payloads. */
-export type RelationMutationAction = Readonly<Partial<Record<AvRelationMutationDirective, unknown>>>;
 /** The scalar fields writable at one stage and write position. */
 type WritableScalarKey<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope> = KeysWithCapability<C, K, ScalarFieldKeyOf<C, K>, Stage, Scope>;
 /**
@@ -312,29 +347,29 @@ type ManyOrOne<C extends AvContract, K extends AvResourceKey<C>, F extends Relat
  * A `where` of plain fields: each scalar field's filter, combined with
  * `AND`/`OR`/`NOT`, and no relation filter at any depth.
  */
-type ScalarOnlyWhereInput<C extends AvContract, K extends AvResourceKey<C>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
-    AND?: readonly ScalarOnlyWhereInput<C, K, Forms, ReferenceForms>[];
-    OR?: readonly ScalarOnlyWhereInput<C, K, Forms, ReferenceForms>[];
-    NOT?: ScalarOnlyWhereInput<C, K, Forms, ReferenceForms>;
-} & ScalarWhereFields<C, K, Forms, ReferenceForms>>;
+export type AvScalarWhereInput<C extends AvContract, K extends AvResourceKey<C>, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = Readonly<{
+    AND?: readonly AvScalarWhereInput<C, K, Forms, ReferenceForms>[];
+    OR?: readonly AvScalarWhereInput<C, K, Forms, ReferenceForms>[];
+    NOT?: AvScalarWhereInput<C, K, Forms, ReferenceForms>;
+}> & ScalarWhereFields<C, K, Forms, ReferenceForms>;
 /**
  * The `where` of a nested `$update` or `$delete` through relation `F`: plain fields
  * only where the relation states `nestedWriteFilter: "scalar"`, any filter otherwise.
  */
 type NestedWriteWhereInput<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = CapabilitiesOf<C, K, F> extends {
     readonly nestedWriteFilter: "scalar";
-} ? ScalarOnlyWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> : AvWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
+} ? AvScalarWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> : AvWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
 type ConnectOrCreateEntry<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]>;
 }>;
 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,26 +380,35 @@ 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;
 /**
  * A write member that advertises nothing: it accepts `{}` and refuses every key.
  */
-type NoAdvertisedMember = {
-    readonly [NO_ADVERTISED_MEMBER]?: never;
-};
-/** `Write`, or {@link NoAdvertisedMember} when `Write` has no keys at all. */
-type RefuseEveryKeyWhenEmpty<Write> = [keyof Write] extends [never] ? NoAdvertisedMember : Write;
-type RelationMutationActionFor<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = RefuseEveryKeyWhenEmpty<Readonly<Partial<{
+export interface AvNoAdvertisedMember {
+    readonly [Symbol.unscopables]?: never;
+}
+/** `Write`, or {@link AvNoAdvertisedMember} when `Write` has no keys at all. */
+type RefuseEveryKeyWhenEmpty<Write> = [keyof Write] extends [never] ? AvNoAdvertisedMember : Write;
+type RelationMutationActionFor<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = RefuseEveryKeyWhenEmpty<RelinkOrRewrite<RelationCardinality<C, K, F>, Readonly<Partial<{
     [Directive in Extract<CapabilityTokens<C, K, F, Stage, Scope>, AvRelationMutationDirective>]: RelationDirectiveValue<C, K, F, Directive, Forms, ReferenceForms>;
-}>>>;
+}>>>>;
+/**
+ * A to-one relation's directive object, which either relinks the relation
+ * (`$connect`, `$create`, …) or writes the linked row (`$update`, `$upsert`),
+ * never both: the ORM would write the newly linked row.
+ */
+type RelinkOrRewrite<Cardinality, Directives> = [Cardinality] extends ["one"] ? [Extract<keyof Directives, ToOneRewriteDirective>] extends [never] ? Directives : [Extract<keyof Directives, ToOneRelinkDirective>] extends [never] ? Directives : (Directives & {
+    readonly [D in Extract<keyof Directives, ToOneRewriteDirective>]?: never;
+}) | (Directives & {
+    readonly [D in Extract<keyof Directives, ToOneRelinkDirective>]?: never;
+}) : Directives;
 /**
  * One scalar mutation directive's operand: one entry of the field (`$push` on a
  * list also takes a list of them). `$unset`'s operand is passed to the adapter as
@@ -377,22 +421,55 @@ 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.
+ * top-level data, a `$ref` to a source of the same type. A field a create must
+ * write (`RequiredWriteKey`) is required.
  */
-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 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 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, Keys extends AvFieldKey<C, K> = Exclude<WritableScalarKey<C, K, Stage, Scope>, LoopbackRefused<C, K, Stage, Via>>, Required extends Keys = Extract<Keys, RequiredWriteKey<C, K, Stage, Scope, Via>>> = Readonly<([Required] extends [never] ? unknown : {
+    [F in Required]: ScalarValueAt<C, K, F, Forms> | ScalarMutationActionFor<C, K, F, Stage, Scope, Forms> | SlotReference<C, K, F, ReferenceForms, "value">;
+}) & ([Exclude<Keys, Required>] extends [never] ? unknown : {
+    [F in Exclude<Keys, Required>]?: ScalarValueAt<C, K, F, Forms> | ScalarMutationActionFor<C, K, F, Stage, Scope, Forms> | SlotReference<C, K, F, ReferenceForms, "value">;
+})>;
+/**
+ * Each writable relation takes the directive object it advertises at this
+ * stage. A relation a create must write (`RequiredWriteKey`) is required.
+ */
+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, Keys extends AvFieldKey<C, K> = Exclude<WritableRelationKey<C, K, Stage, Scope>, LoopbackRefused<C, K, Stage, Via>>, Required extends Keys = Extract<Keys, RequiredWriteKey<C, K, Stage, Scope, Via>>> = Readonly<([Required] extends [never] ? unknown : {
+    [F in Required]: RelationMutationActionFor<C, K, F & RelationFieldKeyOf<C, K>, Stage, Scope, Forms, ReferenceForms>;
+}) & ([Exclude<Keys, Required>] extends [never] ? unknown : {
+    [F in Exclude<Keys, Required>]?: 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;
@@ -429,13 +506,21 @@ type GroupPresence<Group, Scalars, Relations, Supplied> = Group extends readonly
 }) : Present<Relation> : Present<References[number]> : unknown : unknown;
 /** Every group of a `oneOf` tuple, each one's presence intersected. */
 type GroupsPresence<Groups, Scalars, Relations, Supplied> = Groups extends readonly [infer Group, ...infer Rest] ? GroupPresence<Group, Scalars, Relations, Supplied> & GroupsPresence<Rest, Scalars, Relations, Supplied> : unknown;
+/**
+ * The names a create of `K` at `Scope` must write: every `required` name it can
+ * write there, less what the parent supplies through `Via`. `never` for an
+ * update, and where the Contract states nothing.
+ */
+type RequiredWriteKey<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Via> = Stage extends "create" ? [CreateRequirementsAt<C, K>] extends [never] ? never : CreateRequirementsAt<C, K> extends infer Requirements ? string extends RequirementNames<Requirements, "required"> ? never : Exclude<Extract<RequirementNames<Requirements, "required">, WritableScalarKey<C, K, "create", Scope> | WritableRelationKey<C, K, "create", Scope>>, SuppliedThrough<Requirements, Via>> : never : never;
+/** The members a create's two halves hold at `Scope`, reached through `Via`. */
+type HeldCreateKey<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope, Via> = Exclude<WritableScalarKey<C, K, "create", Scope> | WritableRelationKey<C, K, "create", Scope>, LoopbackRefused<C, K, "create", Via>>;
 /**
  * What a create of Resource `K` at write position `Scope` must and must not
  * write: every `required` name it can write, and one side of every `oneOf`
  * group — less what the parent supplies when the create is nested through
  * `Via`. `unknown` (no constraint) when the Contract states nothing.
  */
-type CreateRequirementPresence<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope, Via> = [CreateRequirementsAt<C, K>] extends [never] ? unknown : CreateRequirementsAt<C, K> extends infer Requirements ? string extends RequirementNames<Requirements, "required"> ? unknown : Present<Exclude<Extract<RequirementNames<Requirements, "required">, WritableScalarKey<C, K, "create", Scope> | WritableRelationKey<C, K, "create", Scope>>, SuppliedThrough<Requirements, Via>>> & (Requirements extends {
+type CreateRequirementPresence<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope, Via> = [CreateRequirementsAt<C, K>] extends [never] ? unknown : CreateRequirementsAt<C, K> extends infer Requirements ? string extends RequirementNames<Requirements, "required"> ? unknown : Present<Exclude<RequiredWriteKey<C, K, "create", Scope, Via>, HeldCreateKey<C, K, Scope, Via>>> & (Requirements extends {
     readonly oneOf?: infer Groups;
 } ? GroupsPresence<Groups, WritableScalarKey<C, K, "create", Scope>, WritableRelationKey<C, K, "create", Scope>, SuppliedThrough<Requirements, Via>> : unknown) : unknown;
 /**
@@ -450,9 +535,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<ScalarMutationFields<C, K, "create", Scope, Forms, ReferenceForms, Via>> & RefuseEveryKeyWhenEmpty<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<ScalarMutationFields<C, K, "update", Scope, Forms, ReferenceForms, Via>> & RefuseEveryKeyWhenEmpty<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

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

@@ -55,8 +55,10 @@ export type AvOperationGrammar<C extends AvContract> = {
 export type AvOperationSlot<I extends AvOperationIdentity, Result> = I["variant"] extends "first" ? Result | null : Result;
 /** What a direct call resolves: the slot, every failure thrown. */
 type Settled<I extends AvOperationIdentity, Result> = AvOperationSlot<I, Result>;
-type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
-type PlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
+/** A direct call that projects: generic in its `select`/`include` literal. */
+export type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, NoInfer<Omit<Args, ProjectionKey>> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
+/** A direct call that does not project. */
+export type PlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
 /**
  * One direct call: its arguments in `Forms`, its result in `ResultForms`,
  * resolving the slot and throwing every failure, taking `Options` per call. It is generic in its
@@ -68,9 +70,11 @@ export type AvOperationCall<C extends AvContract, R extends AvResourceKey<C>, I
  * `$ref` typed in `ResultForms` — the forms the source's final data is read in, so a
  * reference carries what its source resolves.
  */
-type DeferredArguments<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
-type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
-type DeferredPlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = (...args: ArgumentList<Args, Args>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>, Origin>;
+export type DeferredArguments<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
+/** A deferred operation that projects: generic in its `select`/`include` literal. */
+export type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, NoInfer<Omit<Args, ProjectionKey>> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
+/** A deferred operation that does not project. */
+export type DeferredPlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = (...args: ArgumentList<Args, Args>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>, Origin>;
 /**
  * One deferred operation: a handle typed `AvOperation<AvOperationSlot<…>, Origin>`,
  * with `$ref` present exactly where the result is one row. A handle is not a

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

@@ -6,7 +6,8 @@ import type { AvOperationIdentity } from "./operation-identity.js";
 type FieldOf<C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>> = C["resources"][K]["fields"][F];
 /**
  * The fields returned when no projection is given: the scalars whose `select`
- * is exactly `true`. A write-only field never appears.
+ * is exactly `true` and that the policy does not govern. A write-only field never
+ * appears, and a governed one appears only where a projection names it.
  */
 type DefaultKey<C extends AvContract, K extends AvResourceKey<C>> = {
     [F in AvFieldKey<C, K>]: FieldOf<C, K, F> extends {
@@ -14,6 +15,7 @@ type DefaultKey<C extends AvContract, K extends AvResourceKey<C>> = {
         readonly capabilities: {
             readonly select: true;
         };
+        readonly governed?: never;
     } ? F : never;
 }[AvFieldKey<C, K>];
 /** The field one projection entry names: a bare key, or a relation entry's key. */
@@ -33,14 +35,14 @@ type EntryArguments<Entry, F extends string> = Entry extends object ? Entry exte
  */
 type ProjectedFields<C extends AvContract, K extends AvResourceKey<C>, Keys extends AvFieldKey<C, K>, Entries, Forms extends ScalarForms> = {
     readonly [F in Keys]: FieldOf<C, K, F> extends AvScalarField<C> ? AvScalarValueType<C, FieldOf<C, K, F>, Forms> : FieldOf<C, K, F> extends AvRelationField<C> ? RelationResult<C, Extract<FieldOf<C, K, F>["target"], AvResourceKey<C>>, FieldOf<C, K, F>, EntryArguments<Entries, F>, Forms> : never;
-};
+} extends infer Fields ? Fields : never;
 /**
  * One projection level: `select` returns exactly its entries, `include` the
  * default fields plus the named relations, and no projection the default fields.
  */
 type ProjectedRecord<C extends AvContract, K extends AvResourceKey<C>, Arguments, Forms extends ScalarForms> = [Arguments] extends [never] ? ProjectedFields<C, K, DefaultKey<C, K>, never, Forms> : [Arguments] extends [{
     readonly select: readonly (infer Entry)[];
-}] ? ProjectedFields<C, K, Extract<EntryKey<Entry>, AvFieldKey<C, K>>, Entry, Forms> : [Arguments] extends [{
+}] ? ProjectedFields<C, K, Extract<EntryKey<Entry>, AvFieldKey<C, K>> | (Entry extends "$defaults" ? DefaultKey<C, K> : never), Entry, Forms> : [Arguments] extends [{
     readonly include: readonly (infer Entry)[];
 }] ? ProjectedFields<C, K, DefaultKey<C, K> | Extract<EntryKey<Entry>, AvFieldKey<C, K>>, Entry, Forms> : ProjectedFields<C, K, DefaultKey<C, K>, never, Forms>;
 /**
@@ -50,7 +52,7 @@ type ProjectedRecord<C extends AvContract, K extends AvResourceKey<C>, Arguments
 type CountEnvelope<C extends AvContract, Target extends AvResourceKey<C>, Entry, Forms extends ScalarForms> = [Exclude<Entry, "$count">] extends [never] ? {
     readonly count: number;
 } : {
-    readonly data: readonly ProjectedFields<C, Target, Extract<EntryKey<Entry>, AvFieldKey<C, Target>>, Exclude<Entry, "$count">, Forms>[];
+    readonly data: readonly ProjectedFields<C, Target, Extract<EntryKey<Entry>, AvFieldKey<C, Target>> | (Entry extends "$defaults" ? DefaultKey<C, Target> : never), Exclude<Entry, "$count">, Forms>[];
     readonly count: number;
 };
 /** The entries of an argument's own `select`, or `never` when it has none. */