@aventara/core 0.1.0-pilot.3 → 1.0.0-rc.0

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

@@ -1,10 +1,13 @@
 import type { ProjectionScope, RelationMutationDirective, ScalarFilterOperator, ScalarMutationDirective, WriteScope } from "../contracts/capability.js";
 import type { Contract } from "../contracts/contract.js";
 import type { ProjectionScopes, ScalarField } from "../contracts/field.js";
-import type { ScalarAtom, ScalarForms, ScalarValueType } from "../contracts/scalar-value-type.js";
+import type { FieldAtom, ScalarForms, ScalarValueType } from "../contracts/scalar-value-type.js";
 import type { JsonValue } from "../runtime/json-value.js";
+import type { TransactionReference, TransactionSlotShape } from "../transactions/transaction-reference.js";
 import type { OperationIdentity } from "./operation-identity.js";
+/** The Resource names of Contract `C`. */
 export type ResourceKey<C extends Contract> = Extract<keyof C["resources"], string>;
+/** The field names of Resource `K` in Contract `C`. */
 export type FieldKey<C extends Contract, K extends ResourceKey<C>> = Extract<keyof C["resources"][K]["fields"], string>;
 type FieldAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>> = C["resources"][K]["fields"][F];
 type ScalarFieldAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>> = Extract<FieldAt<C, K, F>, {
@@ -22,49 +25,15 @@ type RelationFieldKeyOf<C extends Contract, K extends ResourceKey<C>> = {
 type CapabilitiesOf<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>> = FieldAt<C, K, F> extends {
     readonly capabilities: infer Capabilities;
 } ? Capabilities : never;
-/**
- * The argument scope a reader with no scope to thread reads a projection
- * capability at.
- *
- * `filter`, `order`, `orderNulls` and `pagination` were measured uniform across
- * every operation variant, so their readers have no scope to be given; and every
- * variant that carries a filter, an order, a cursor or a pagination argument
- * carries it in the unrestricted position — the bulk cells carry none of them.
- * Named rather than inlined so that a member which stops being uniform is found
- * by grepping one word instead of auditing `"record"` string literals.
- */
+/** The projection position read when no position applies: `"record"`. */
 type UnrestrictedProjection = "record";
-/**
- * The write mirror of {@link UnrestrictedProjection}, and the default for the
- * public write surfaces: a write argument reached through a relation is the
- * unrestricted position, because a scope qualifies the TOP LEVEL of an argument
- * only and does not narrow recursively (see {@link WriteScope}).
- */
+/** The write position read when no position applies, and the one nested writes use: `"nested"`. */
 type UnrestrictedWrite = "nested";
-/**
- * Whether a capability member's answer holds at one argument scope.
- *
- * The qualified arms state where they hold: a scope list on `select`/`include`,
- * a `scopes` member beside the tokens on `reducers`, `create` and `update`. The
- * unqualified arms state no scope and therefore hold in every one of them —
- * which is what keeps a Contract written before the axis existed meaning exactly
- * what it meant, and what lets an adapter that has not measured the axis say so
- * without losing a capability.
- *
- * Presence is deliberately NOT answered here: `false` and an absent member
- * arrive as unqualified values and would be reported as holding.
- * {@link HasCapability} owns the presence question and asks this one second.
- */
+/** Whether a capability member's answer holds at one argument scope. */
 type HoldsAtScope<Value, Scope extends ProjectionScope | WriteScope> = Value extends {
     readonly scopes: readonly (infer Stated)[];
 } ? Scope extends Stated ? true : false : Value extends ProjectionScopes ? Scope extends Value[number] ? true : false : true;
-/**
- * The tokens a capability member advertises, whichever arm it is written in — the
- * type-level mirror of `advertisedDirectives` and `advertisedReducers`, and
- * scope-blind for the same reason they are: reading the tokens and deciding where
- * they hold are two questions, and a reader handed both in one answer answers the
- * second by forgetting it. {@link CapabilityTokens} asks both.
- */
+/** The tokens a capability member advertises, in any argument position. */
 type AdvertisedTokens<Value> = Value extends {
     readonly scopes: readonly WriteScope[];
     readonly directives: readonly (infer Directive)[];
@@ -93,127 +62,129 @@ type KeysWithCapability<C extends Contract, K extends ResourceKey<C>, Keys exten
     [F in Keys]: HasCapability<C, K, F, Capability, Scope> extends true ? F : never;
 }[Keys];
 /**
- * The scalar-form map an argument surface reads its scalar VALUES through when
- * the caller names no side of a boundary: every built-in form `unknown`.
- *
- * It is `ScalarForms` itself — the constraint every map satisfies — so it tells a
- * reader nothing about a built-in value, which is the surface every caller had
- * before values were typed. An authoring mirror shared by both request origins (a
- * transaction plan, a hand-written request) cannot know whether its `Date`
- * travels as a `Date` or as an ISO string; a caller that does know passes
- * `ApplicationScalarForms` or `WireScalarForms` and is held to it.
- *
- * Enum members are not a form: they are the same strings on both sides, so an
- * enum-backed value is its member union under every map, this one included.
+ * The scalar-form map used when no side of a boundary is named: every built-in
+ * value is `unknown`. Pass `ApplicationScalarForms` or `WireScalarForms` to type
+ * values. Enum values are their member union under every map.
  */
 type UnstatedForms = ScalarForms;
-/**
- * Field `F`'s value under `Forms`: the one derivation a result reads
- * (`ScalarValueType`), read here for arguments, so an argument and a result
- * cannot disagree about what a field's value is.
- */
+/** Field `F`'s value under `Forms`, the same as in results. */
 type ScalarValueAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Forms extends ScalarForms> = ScalarFieldAt<C, K, F> extends infer Field extends ScalarField<C> ? ScalarValueType<C, Field, Forms> : never;
 /** One entry of field `F`'s value — the whole value when `F` is not a list. */
-type ScalarAtomAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Forms extends ScalarForms> = ScalarAtom<C, ScalarFieldAt<C, K, F>["type"], Forms>;
+type ScalarAtomAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Forms extends ScalarForms> = FieldAtom<C, ScalarFieldAt<C, K, F>, Forms>;
+/**
+ * A `$ref` to a source whose value fits slot shape `Shape` of field `F`, typed in
+ * `ReferenceForms` — the forms a source's final data is read in. `never` when
+ * `ReferenceForms` is `never`: no position takes one outside a transaction plan.
+ */
+type SlotReference<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, ReferenceForms extends ScalarForms, Shape extends TransactionSlotShape> = [ReferenceForms] extends [never] ? never : TransactionReference<Shape extends "value" ? ScalarValueAt<C, K, F, ReferenceForms> : Shape extends "nonNullValue" ? Exclude<ScalarValueAt<C, K, F, ReferenceForms>, null> : Shape extends "entry" ? ScalarAtomAt<C, K, F, ReferenceForms> : readonly ScalarAtomAt<C, K, F, ReferenceForms>[]>;
 /**
- * A JSON object: the value the runtime reads as an argument OBJECT rather than as
- * a value wherever a position admits both (`runtime/scalar-runtime.ts`
- * `isPlainRecord`), so those positions' value arms leave it out.
+ * A JSON object. Positions that accept both a value and an object of operators
+ * read a JSON object as the operators, so their value forms leave it out.
  */
 type JsonObject = Extract<JsonValue, {
     readonly [key: string]: JsonValue;
 }>;
 /**
- * The field-independent shape of one scalar filter: any value, or an object of
- * the operator vocabulary. `WhereInput` no longer reads it — it types each
- * field's operands through a scalar-form map (see `ScalarFilterFor`) — and it
- * stays exported as the vocabulary's own shape for a caller that holds no
- * Contract.
+ * The field-independent shape of one scalar filter: any value, or an object of the
+ * operator vocabulary.
  */
 export type ScalarFilterInput = unknown | Readonly<Partial<Record<ScalarFilterOperator, unknown>>>;
 /**
  * A scalar filter's shorthand equality value: the field's value, minus a JSON
  * object.
- *
- * Every reader of a filter position — the validation layer, the scalar runtime and
- * the adapter — reads it through one discriminant (`runtime/scalar-runtime.ts`
- * `isPlainRecord`): a plain record is an operator object, anything else is a
- * value. So a `Date`, a `Decimal` and a `Uint8Array` are shorthand for their
- * field, and a JSON object is an operator object by construction — `{ equals:
- * document }` carries it. The same exclusion as `not`'s value arm below.
  */
 type ScalarFilterShorthand<Value> = Exclude<Value, JsonObject>;
 /**
- * A scalar filter's operator object, each operand read the way
- * `normalizeScalarFilter` reads it: a comparison operand is the field's whole
- * value; `in`, `notIn`, `hasEvery` and `hasSome` a list of entries; `has` one
- * entry; a `json` field's `string*`/`array*` operand a {@link JsonValue}; `not` a
- * value or a nested operator object. `mode`, `isEmpty` and `path` reach the
- * adapter un-normalized, so core states nothing about them.
- *
- * Which operators a field advertises stays the validation layer's question
- * (`V1006`), exactly as before values were typed: this answers only what each
- * operand is.
+ * The `$ref` each slot shape of field `F` takes, by shape: every member `never`
+ * outside a transaction plan.
+ */
+type FieldSlotReferences<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, ReferenceForms extends ScalarForms> = {
+    readonly [Shape in TransactionSlotShape]: SlotReference<C, K, F, ReferenceForms, Shape>;
+};
+/**
+ * A scalar filter's operator object: a comparison operand is the field's whole
+ * value; `in`, `notIn`, `hasEvery` and `hasSome` take a list of entries; `has`
+ * one entry; a `json` field's `string*`/`array*` operand a {@link JsonValue};
+ * `not` a value or a nested operator object. `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`).
  */
-type ScalarFilterOperators<Value, Atom, Json> = Readonly<{
-    equals?: Value;
-    not?: Exclude<Value, JsonObject> | ScalarFilterOperators<Value, Atom, Json>;
-    in?: readonly Atom[];
-    notIn?: readonly Atom[];
-    lt?: Value;
-    lte?: Value;
-    gt?: Value;
-    gte?: Value;
-    contains?: Value;
-    startsWith?: Value;
-    endsWith?: Value;
+type ScalarFilterOperators<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>> = Readonly<{
+    equals?: Value | References["value"];
+    not?: Exclude<Value, JsonObject> | References["value"] | ScalarFilterOperators<Value, Atom, Json, References>;
+    in?: readonly Atom[] | References["entries"];
+    notIn?: readonly Atom[] | References["entries"];
+    lt?: Exclude<Value, null> | References["nonNullValue"];
+    lte?: Exclude<Value, null> | References["nonNullValue"];
+    gt?: Exclude<Value, null> | References["nonNullValue"];
+    gte?: Exclude<Value, null> | References["nonNullValue"];
+    contains?: Exclude<Value, null> | References["nonNullValue"];
+    startsWith?: Exclude<Value, null> | References["nonNullValue"];
+    endsWith?: Exclude<Value, null> | References["nonNullValue"];
     mode?: unknown;
-    has?: Atom;
-    hasEvery?: readonly Atom[];
-    hasSome?: readonly Atom[];
+    has?: Atom | References["entry"];
+    hasEvery?: readonly Atom[] | References["entries"];
+    hasSome?: readonly Atom[] | References["entries"];
     isEmpty?: unknown;
     path?: unknown;
-    stringContains?: Json;
-    stringStartsWith?: Json;
-    stringEndsWith?: Json;
+    stringContains?: Exclude<Json, null>;
+    stringStartsWith?: Exclude<Json, null>;
+    stringEndsWith?: Exclude<Json, null>;
     arrayContains?: Json;
     arrayStartsWith?: Json;
     arrayEndsWith?: Json;
 }>;
-/** One scalar field's filter under `Forms`: a shorthand value or an operator object. */
-type ScalarFilterFor<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Forms extends ScalarForms> = ScalarFilterShorthand<ScalarValueAt<C, K, F, Forms>> | ScalarFilterOperators<ScalarValueAt<C, K, F, Forms>, ScalarAtomAt<C, K, F, Forms>, ScalarFieldAt<C, K, F>["type"] extends {
+/**
+ * One scalar field's filter under `Forms`: a shorthand value or an operator object.
+ * Inside a transaction plan the value and every operand that holds a field value may
+ * be a `$ref` (see {@link TransactionSlotShape}): equality to a source nullable only
+ * where the field is, a comparison to a non-null source, `in` and the list operators
+ * to a list source, `has` to one entry.
+ */
+type ScalarFilterFor<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = ScalarFilterShorthand<ScalarValueAt<C, K, F, Forms>> | SlotReference<C, K, F, ReferenceForms, "value"> | ScalarFilterOperators<ScalarValueAt<C, K, F, Forms>, ScalarAtomAt<C, K, F, Forms>, ScalarFieldAt<C, K, F>["type"] extends {
     readonly scalar: "json";
-} ? JsonValue : ScalarValueAt<C, K, F, Forms>>;
+} ? JsonValue : ScalarValueAt<C, K, F, Forms>, FieldSlotReferences<C, K, F, ReferenceForms>>;
 type ScalarFilterableKey<C extends Contract, K extends ResourceKey<C>> = KeysWithCapability<C, K, ScalarFieldKeyOf<C, K>, "filter", UnrestrictedProjection>;
 type RelationParentFilterKey<C extends Contract, K extends ResourceKey<C>> = {
     [F in RelationFieldKeyOf<C, K>]: RelationCardinality<C, K, F> extends "one" ? HasCapabilityToken<C, K, F, "filter", UnrestrictedProjection, "match"> extends true ? F : HasCapabilityToken<C, K, F, "filter", UnrestrictedProjection, "null"> extends true ? F : never : Extract<CapabilityTokens<C, K, F, "filter", UnrestrictedProjection>, "some" | "every" | "none"> extends never ? never : F;
 }[RelationFieldKeyOf<C, K>];
-type ToManyRelationWhereInput<C extends Contract, K extends ResourceKey<C>, F extends RelationParentFilterKey<C, K> & RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = Readonly<Partial<Record<Extract<CapabilityTokens<C, K, F, "filter", UnrestrictedProjection>, "some" | "every" | "none">, WhereInput<C, RelationTarget<C, K, F>, Forms>>>>;
-type RelationWhereInput<C extends Contract, K extends ResourceKey<C>, F extends RelationParentFilterKey<C, K> & RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = RelationCardinality<C, K, F> extends "one" ? (HasCapabilityToken<C, K, F, "filter", UnrestrictedProjection, "match"> extends true ? WhereInput<C, RelationTarget<C, K, F>, Forms> : never) | (RelationNullable<C, K, F> extends true ? HasCapabilityToken<C, K, F, "filter", UnrestrictedProjection, "null"> extends true ? null : never : never) : ToManyRelationWhereInput<C, K, F, Forms>;
-type ScalarWhereFields<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms> = Readonly<{
-    [F in ScalarFilterableKey<C, K>]?: ScalarFilterFor<C, K, F, Forms>;
+type ToManyRelationWhereInput<C extends Contract, K extends ResourceKey<C>, F extends RelationParentFilterKey<C, K> & RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<Partial<Record<Extract<CapabilityTokens<C, K, F, "filter", UnrestrictedProjection>, "some" | "every" | "none">, WhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>>>>;
+type RelationWhereInput<C extends Contract, K extends ResourceKey<C>, F extends RelationParentFilterKey<C, K> & RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = RelationCardinality<C, K, F> extends "one" ? (HasCapabilityToken<C, K, F, "filter", UnrestrictedProjection, "match"> extends true ? WhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> : never) | (RelationNullable<C, K, F> extends true ? HasCapabilityToken<C, K, F, "filter", UnrestrictedProjection, "null"> extends true ? null : never : never) : ToManyRelationWhereInput<C, K, F, Forms, ReferenceForms>;
+type ScalarWhereFields<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    [F in ScalarFilterableKey<C, K>]?: ScalarFilterFor<C, K, F, Forms, ReferenceForms>;
 }>;
-type RelationWhereFields<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms> = Readonly<{
-    [F in RelationParentFilterKey<C, K>]?: RelationWhereInput<C, K, F & RelationFieldKeyOf<C, K>, Forms>;
+type RelationWhereFields<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    [F in RelationParentFilterKey<C, K>]?: RelationWhereInput<C, K, F & RelationFieldKeyOf<C, K>, Forms, ReferenceForms>;
 }>;
 /**
  * A `where` argument. `Forms` is the scalar-form map its scalar values are read
- * through; see {@link UnstatedForms} for the default.
+ * through; see {@link UnstatedForms} for the default. `ReferenceForms` opens a
+ * transaction step's own `where` to `$ref`s, at every depth of it.
  */
-export type WhereInput<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms> = Readonly<{
-    AND?: readonly WhereInput<C, K, Forms>[];
-    OR?: readonly WhereInput<C, K, Forms>[];
-    NOT?: WhereInput<C, K, Forms>;
-} & ScalarWhereFields<C, K, Forms> & RelationWhereFields<C, K, Forms>>;
+export type WhereInput<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = Readonly<{
+    AND?: readonly WhereInput<C, K, Forms, ReferenceForms>[];
+    OR?: readonly WhereInput<C, K, Forms, ReferenceForms>[];
+    NOT?: WhereInput<C, K, Forms, ReferenceForms>;
+} & ScalarWhereFields<C, K, Forms, ReferenceForms> & RelationWhereFields<C, K, Forms, ReferenceForms>>;
 type ActiveIdentifier<C extends Contract, K extends ResourceKey<C>> = C["resources"][K]["identifiers"][number];
-type IdentifierObject<C extends Contract, K extends ResourceKey<C>, I extends readonly string[], Forms extends ScalarForms> = Readonly<{
-    [F in Extract<I[number], FieldKey<C, K>>]: ScalarValueAt<C, K, F, Forms>;
+type IdentifierObject<C extends Contract, K extends ResourceKey<C>, I extends readonly string[], Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    [F in Extract<I[number], FieldKey<C, K>>]: ScalarValueAt<C, K, F, Forms> | SlotReference<C, K, F, ReferenceForms, "nonNullValue">;
 } & {
     [F in Exclude<FieldKey<C, K>, I[number]>]?: never;
 }>;
-export type UniqueWhereInput<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms> = ActiveIdentifier<C, K> extends infer I ? I extends readonly string[] ? IdentifierObject<C, K, I, Forms> : never : never;
+/**
+ * A `where` argument for a unique operation: the values of one identifier. Inside a
+ * transaction plan (`ReferenceForms` stated) each value may be a `$ref` to a non-null
+ * source of the same type.
+ */
+export type UniqueWhereInput<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = ActiveIdentifier<C, K> extends infer I ? I extends readonly string[] ? IdentifierObject<C, K, I, Forms, ReferenceForms> : never : never;
+/** `"asc"` or `"desc"`. */
 export type SortDirection = "asc" | "desc";
+/** Where `null`s sort: `"first"` or `"last"`. */
 export type NullsOrder = "first" | "last";
+/** How one scalar field sorts: a direction, or a direction and a `nulls` order. */
 export type ScalarOrderInput = SortDirection | Readonly<{
     sort: SortDirection;
     nulls: NullsOrder;
@@ -223,40 +194,15 @@ type OrderableRelationKey<C extends Contract, K extends ResourceKey<C>> = KeysWi
 type OrderableFieldKey<C extends Contract, K extends ResourceKey<C>> = OrderableScalarKey<C, K> | OrderableRelationKey<C, K>;
 type ScalarOrderForField<C extends Contract, K extends ResourceKey<C>, F extends OrderableScalarKey<C, K>> = ScalarFieldAt<C, K, F>["nullable"] extends true ? HasCapability<C, K, F, "orderNulls", UnrestrictedProjection> extends true ? ScalarOrderInput : SortDirection : SortDirection;
 /**
- * An `orderBy` reducer is not a PROJECTION position, so the projection scopes
- * beside the reducer list do not qualify it; and every variant that carries an
- * `orderBy` argument carries it in the unrestricted position, which is why this
- * reader does not thread a scope.
- *
- * A to-one value is **one** target entry, not an {@link OrderByInput}: the
- * runtime refuses a precedence list there (`validateOrderBy` requires a record
- * at a relation position, V1001), so admitting one would advertise what the
- * validation layer refuses.
+ * The `orderBy` value of a relation field: a to-many relation orders by
+ * `$count`; a to-one relation takes one entry of the related Resource's
+ * `orderBy`, not a list.
  */
 type RelationOrderForField<C extends Contract, K extends ResourceKey<C>, F extends OrderableRelationKey<C, K> & RelationFieldKeyOf<C, K>> = RelationCardinality<C, K, F> extends "many" ? HasCapabilityToken<C, K, F, "reducers", UnrestrictedProjection, "$count"> extends true ? Readonly<{
     $count: SortDirection;
 }> : never : OrderByEntry<C, RelationTarget<C, K, F>>;
 type OrderValue<C extends Contract, K extends ResourceKey<C>, F extends OrderableFieldKey<C, K>> = F extends OrderableScalarKey<C, K> ? ScalarOrderForField<C, K, F> : F extends OrderableRelationKey<C, K> & RelationFieldKeyOf<C, K> ? RelationOrderForField<C, K, F> : never;
-/**
- * One `orderBy` precedence entry: exactly one orderable field and its value.
- *
- * A to-one relation's value is the target's entry, so a self-relation
- * (`Author.mentor → Author`) or a one-to-one pair makes this type recursive. A
- * type argument is instantiated eagerly, so resolving `OrderByEntry<C, "Author">`
- * needed `OrderValue<…, "mentor">`, which IS `OrderByEntry<C, "Author">`: TS2615,
- * after which the entry degraded to `any` and refused nothing. A mapped property
- * is resolved only when read, by which time the entry it recurses into exists. The
- * projection walk never hit this because its recursion already sits behind an
- * object property (`{ select?: … }`).
- *
- * **No type-level depth cap, deliberately.** The runtime bound is the Contract's
- * `limits.maxNestingDepth` — each to-one hop counts one level, and one past it is
- * V1013 (`operation-nesting.ts` `walkOrderBy`). That limit is a `number` in the
- * Contract, resolved per scope at construction, so no literal exists for a type to
- * count against; a fixed cap would refuse what a Contract with a larger limit
- * accepts. `where` and `select` recurse uncapped for the same reason, and the
- * validation layer refuses past the limit for all three.
- */
+/** One `orderBy` precedence entry: exactly one orderable field and its value. */
 export type OrderByEntry<C extends Contract, K extends ResourceKey<C>> = {
     [F in OrderableFieldKey<C, K>]: {
         readonly [Only in F]: OrderValue<C, K, Only>;
@@ -264,15 +210,16 @@ export type OrderByEntry<C extends Contract, K extends ResourceKey<C>> = {
         readonly [Other in Exclude<OrderableFieldKey<C, K>, F>]?: never;
     };
 }[OrderableFieldKey<C, K>];
+/** An `orderBy` argument: one entry, or a list in order of precedence. */
 export type OrderByInput<C extends Contract, K extends ResourceKey<C>> = OrderByEntry<C, K> | readonly OrderByEntry<C, K>[];
-export type CursorInput<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms> = Readonly<{
-    [F in ScalarFieldKeyOf<C, K>]?: ScalarValueAt<C, K, F, Forms>;
-}>;
 /**
- * Scalar `select` carries no scope qualifier — the six scalar members were
- * measured uniform — so the scope reaches this reader only to keep one projection
- * walk asking one question.
+ * A `cursor` argument: scalar field values of the row the page starts from. Inside
+ * a transaction plan each may be a `$ref` to a non-null source of the same type.
  */
+export type CursorInput<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = Readonly<{
+    [F in ScalarFieldKeyOf<C, K>]?: ScalarValueAt<C, K, F, Forms> | SlotReference<C, K, F, ReferenceForms, "nonNullValue">;
+}>;
+/** The scalar fields selectable at one projection position. */
 type SelectableScalarKey<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope> = KeysWithCapability<C, K, ScalarFieldKeyOf<C, K>, "select", Scope>;
 type SelectableRelationKey<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope> = KeysWithCapability<C, K, RelationFieldKeyOf<C, K>, "select", Scope>;
 type IncludeRelationKey<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope> = KeysWithCapability<C, K, RelationFieldKeyOf<C, K>, "include", Scope>;
@@ -307,28 +254,14 @@ type ProjectionChoice<C extends Contract, K extends ResourceKey<C>, Scope extend
     select?: never;
 }>;
 /**
- * The argument object one relation entry carries inside a projection.
- *
- * `Scope` is the scope of the projection this entry sits in. It qualifies the
- * entry's own reducer question and nothing deeper: the target's projection is
- * taken at {@link UnrestrictedProjection}, because a scope qualifies the top
- * level of a projection only and the measurement is explicit that the full
- * surface returns one level in (see {@link ProjectionScope}). A reader who
- * narrowed it recursively would refuse what the ORM accepts.
+ * The argument object one relation entry carries inside a projection. `Scope`
+ * applies to this entry only; the related rows' own projection is
+ * unrestricted.
  */
 export type RelationProjectionInput<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K> = RelationFieldKeyOf<C, K>, Scope extends ProjectionScope = UnrestrictedProjection, Forms extends ScalarForms = UnstatedForms> = F extends RelationFieldKeyOf<C, K> ? Readonly<NestedWhereArgument<C, K, F, Forms> & NestedOrderArgument<C, K, F> & NestedPaginationArgument<C, K, F, "limit", Forms> & NestedPaginationArgument<C, K, F, "offset", Forms> & NestedPaginationArgument<C, K, F, "cursor", Forms> & ProjectionChoice<C, RelationTarget<C, K, F>, UnrestrictedProjection, RelationAllowsCount<C, K, F, Scope>, Forms>> : never;
 /**
  * One relation entry of a projection: exactly relation `F` of `Keys`, with its
  * argument object, and every other key of `Keys` absent.
- *
- * A projection's entry union is formed whenever its `select`/`include` constraint
- * is — at every call, including one that passes no projection — and a type
- * argument is instantiated when the union is: every relation's {@link
- * RelationProjectionInput} (its nested `where`, `orderBy`, pagination and
- * projection choice) for every relation the Resource has. A mapped property is
- * resolved only when an entry names it, so a call pays for the relations it
- * projects. Measured on the six-resource artifact shape: ≈4,500–6,700
- * instantiations per call whose projection names no relation.
  */
 type RelationProjectionEntry<C extends Contract, K extends ResourceKey<C>, Keys extends RelationFieldKeyOf<C, K>, F extends Keys, Scope extends ProjectionScope, Forms extends ScalarForms> = {
     readonly [Only in F]: RelationProjectionInput<C, K, Only & RelationFieldKeyOf<C, K>, Scope, Forms>;
@@ -342,93 +275,92 @@ type IncludeRelationProjectionEntry<C extends Contract, K extends ResourceKey<C>
     [F in IncludeRelationKey<C, K, Scope>]: RelationProjectionEntry<C, K, IncludeRelationKey<C, K, Scope>, F, Scope, Forms>;
 }[IncludeRelationKey<C, K, Scope>];
 /**
- * One entry of a `select` argument, at one projection scope.
- *
- * The scope precedes `AllowCount` because it qualifies which fields exist at
- * this position at all, while `AllowCount` only says whether the carrying entry
- * admits its parent's reducer. The default is the unrestricted position, so a
- * reader that states no scope keeps today's surface exactly.
+ * One entry of a `select` argument, at one projection position. The default is
+ * the unrestricted position.
  */
 export type ProjectionEntry<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope = 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);
+/** A `select` argument: the fields to return. */
 export type SelectInput<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = readonly ProjectionEntry<C, K, Scope, AllowCount, Forms>[];
+/** An `include` argument: the relations to return with each row. */
 export type IncludeInput<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope = 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<ScalarMutationDirective, unknown>>>;
+/** A relation write: one or more relation directives and their payloads. */
 export type RelationMutationAction = Readonly<Partial<Record<RelationMutationDirective, unknown>>>;
-/**
- * Scalar write members carry no scope qualifier — all six scalar members were
- * measured uniform — so the scope reaches this reader only to keep one mutation
- * walk asking one question.
- */
+/** The scalar fields writable at one stage and write position. */
 type WritableScalarKey<C extends Contract, K extends ResourceKey<C>, Stage extends "create" | "update", Scope extends WriteScope> = KeysWithCapability<C, K, ScalarFieldKeyOf<C, K>, Stage, Scope>;
 /**
- * The relations writable at one stage **in one write position**. The default is
- * the unrestricted position, which is what every nested write argument is and
- * what a caller that states no scope means.
+ * The relations writable at one stage in one write position. The default is
+ * the unrestricted position.
  */
 export type WritableRelationKey<C extends Contract, K extends ResourceKey<C>, Stage extends "create" | "update", Scope extends WriteScope = UnrestrictedWrite> = KeysWithCapability<C, K, RelationFieldKeyOf<C, K>, Stage, Scope>;
 type ManyOrOne<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Value> = RelationCardinality<C, K, F> extends "many" ? Value | readonly Value[] : Value;
-type ConnectOrCreateEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = Readonly<{
-    where: UniqueWhereInput<C, RelationTarget<C, K, F>, Forms>;
-    create: CreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms>;
+/**
+ * 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 Contract, K extends ResourceKey<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>>;
+/**
+ * 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 Contract, K extends ResourceKey<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> : WhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
+type ConnectOrCreateEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    where: UniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
+    create: CreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
 }>;
-type ToOneUpdateEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = Readonly<{
-    where?: WhereInput<C, RelationTarget<C, K, F>, Forms>;
-    data: UpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms>;
+type ToOneUpdateEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    where?: NestedWriteWhereInput<C, K, F, Forms, ReferenceForms>;
+    data: UpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
 }>;
-type ToManyUpdateEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = Readonly<{
-    where: WhereInput<C, RelationTarget<C, K, F>, Forms>;
-    data: UpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms>;
+type ToManyUpdateEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    where: NestedWriteWhereInput<C, K, F, Forms, ReferenceForms>;
+    data: UpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
 }>;
-type ToOneDeleteEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = true | Readonly<{
-    where?: WhereInput<C, RelationTarget<C, K, F>, Forms>;
+type ToOneDeleteEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = true | Readonly<{
+    where?: NestedWriteWhereInput<C, K, F, Forms, ReferenceForms>;
 }>;
-type ToManyDeleteEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = Readonly<{
-    where: WhereInput<C, RelationTarget<C, K, F>, Forms>;
+type ToManyDeleteEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    where: NestedWriteWhereInput<C, K, F, Forms, ReferenceForms>;
 }>;
-type ToOneUpsertEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = Readonly<{
-    where?: UniqueWhereInput<C, RelationTarget<C, K, F>, Forms>;
-    create: CreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms>;
-    update: UpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms>;
+type ToOneUpsertEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    where?: UniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
+    create: CreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
+    update: UpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
 }>;
-type ToManyUpsertEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms> = Readonly<{
-    where: UniqueWhereInput<C, RelationTarget<C, K, F>, Forms>;
-    create: CreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms>;
-    update: UpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms>;
+type ToManyUpsertEntry<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
+    where: UniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
+    create: CreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
+    update: UpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>;
 }>;
-type RelationDirectiveValue<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Directive extends RelationMutationDirective, Forms extends ScalarForms> = Directive extends "$create" ? ManyOrOne<C, K, F, CreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms>> : Directive extends "$connect" ? ManyOrOne<C, K, F, UniqueWhereInput<C, RelationTarget<C, K, F>, Forms>> : Directive extends "$connectOrCreate" ? ManyOrOne<C, K, F, ConnectOrCreateEntry<C, K, F, Forms>> : Directive extends "$disconnect" ? RelationCardinality<C, K, F> extends "one" ? true : UniqueWhereInput<C, RelationTarget<C, K, F>, Forms> | readonly UniqueWhereInput<C, RelationTarget<C, K, F>, Forms>[] : Directive extends "$set" ? RelationCardinality<C, K, F> extends "one" ? UniqueWhereInput<C, RelationTarget<C, K, F>, Forms> | null : readonly UniqueWhereInput<C, RelationTarget<C, K, F>, Forms>[] : Directive extends "$update" ? RelationCardinality<C, K, F> extends "one" ? ToOneUpdateEntry<C, K, F, Forms> : ManyOrOne<C, K, F, ToManyUpdateEntry<C, K, F, Forms>> : Directive extends "$delete" ? RelationCardinality<C, K, F> extends "one" ? ToOneDeleteEntry<C, K, F, Forms> : ManyOrOne<C, K, F, ToManyDeleteEntry<C, K, F, Forms>> : Directive extends "$upsert" ? RelationCardinality<C, K, F> extends "one" ? ToOneUpsertEntry<C, K, F, Forms> : ManyOrOne<C, K, F, ToManyUpsertEntry<C, K, F, Forms>> : never;
+type RelationDirectiveValue<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Directive extends RelationMutationDirective, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Directive extends "$create" ? ManyOrOne<C, K, F, CreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms>> : Directive extends "$connect" ? ManyOrOne<C, K, F, UniqueWhereInput<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 : UniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> | readonly UniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>[] : Directive extends "$set" ? RelationCardinality<C, K, F> extends "one" ? UniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> | null : readonly UniqueWhereInput<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.
- *
- * TypeScript runs no excess-property check against an object type with no known
- * properties, so an empty mapped member would type as `{}` and accept any key
- * silently, leaving it to `V1006` at runtime. One optional member on a
- * module-private symbol keeps the type weak — `{}` still assigns — while giving
- * the excess-property check something to measure against, so the diagnostic names
- * the offending key.
- *
- * The empty case is reachable by design: `directives: []` means "writable, with no
- * directive", distinct from an absent member (see `contracts/field.ts`).
  */
 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 Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Stage extends "create" | "update", Scope extends WriteScope, Forms extends ScalarForms> = RefuseEveryKeyWhenEmpty<Readonly<Partial<{
-    [Directive in Extract<CapabilityTokens<C, K, F, Stage, Scope>, RelationMutationDirective>]: RelationDirectiveValue<C, K, F, Directive, Forms>;
+type RelationMutationActionFor<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Stage extends "create" | "update", Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = RefuseEveryKeyWhenEmpty<Readonly<Partial<{
+    [Directive in Extract<CapabilityTokens<C, K, F, Stage, Scope>, RelationMutationDirective>]: RelationDirectiveValue<C, K, F, Directive, Forms, ReferenceForms>;
 }>>>;
 /**
- * One scalar mutation directive's operand, as `normalizeScalarMutation` reads
- * it: one entry of the field (`$push` on a list also takes a list of them), and
- * `$unset`'s operand reaches the adapter un-normalized, so core states nothing
- * about it.
+ * 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
+ * given.
  */
 type ScalarDirectiveOperand<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Directive extends ScalarMutationDirective, Forms extends ScalarForms> = Directive extends "$unset" ? unknown : Directive extends "$push" ? [ScalarFieldAt<C, K, F>["list"]] extends [false] ? ScalarAtomAt<C, K, F, Forms> : ScalarAtomAt<C, K, F, Forms> | readonly ScalarAtomAt<C, K, F, Forms>[] : ScalarAtomAt<C, K, F, Forms>;
 /**
  * The directive object a scalar field accepts at one stage, or `never` when it
- * advertises no directive — never an empty object type, which every non-nullish
- * value would satisfy and so would let any value through beside the typed one.
+ * advertises no directive.
  */
 type ScalarMutationActionFor<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Stage extends "create" | "update", Scope extends WriteScope, Forms extends ScalarForms> = [
     Extract<CapabilityTokens<C, K, F, Stage, Scope>, ScalarMutationDirective>
@@ -437,143 +369,106 @@ type ScalarMutationActionFor<C extends Contract, K extends ResourceKey<C>, F ext
 }>;
 /**
  * Each writable scalar takes its value under `Forms`, or a directive object of
- * the directives it advertises at this stage.
+ * 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 Contract, K extends ResourceKey<C>, Stage extends "create" | "update", Scope extends WriteScope, Forms extends ScalarForms> = Readonly<{
-    [F in WritableScalarKey<C, K, Stage, Scope>]?: ScalarValueAt<C, K, F, Forms> | ScalarMutationActionFor<C, K, F, Stage, Scope, Forms>;
+type ScalarMutationFields<C extends Contract, K extends ResourceKey<C>, Stage extends "create" | "update", Scope extends WriteScope, 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 Contract, K extends ResourceKey<C>, Stage extends "create" | "update", Scope extends WriteScope, Forms extends ScalarForms> = Readonly<{
-    [F in WritableRelationKey<C, K, Stage, Scope>]?: RelationMutationActionFor<C, K, F & RelationFieldKeyOf<C, K>, Stage, Scope, Forms>;
+type RelationMutationFields<C extends Contract, K extends ResourceKey<C>, Stage extends "create" | "update", Scope extends WriteScope, 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>;
 }>;
 /**
- * A `create` data argument, at one write position.
- *
- * The default is the unrestricted position: every nested occurrence of this type
- * — a `$create` payload, a `$connectOrCreate`'s `create`, an upsert branch — is a
- * write reached through a relation, and a scope qualifies the top level of a
- * write argument only (see {@link WriteScope}).
+ * A `create` data argument, at one write position. A write position applies
+ * to the top level only; nested writes use the unrestricted position (see
+ * {@link WriteScope}). `ReferenceForms` opens a transaction plan's reference
+ * positions — its scalar values and the unique keys its relation directives name
+ * — and is never passed to nested data, which holds none.
  */
-export type CreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "create", Scope, Forms> & RelationMutationFields<C, K, "create", Scope, Forms>>>;
+export type CreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "create", Scope, Forms, ReferenceForms> & RelationMutationFields<C, K, "create", Scope, Forms, ReferenceForms>>>;
 /** An `update` data argument, at one write position. See {@link CreateDataInput}. */
-export type UpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "update", Scope, Forms> & RelationMutationFields<C, K, "update", Scope, Forms>>>;
+export type UpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = 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>>>;
 type QueryProjectionArgs<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope, Forms extends ScalarForms> = ProjectionChoice<C, K, Scope, false, Forms>;
 /**
- * Every standard operation's argument object, with each argument position bound to
- * the argument SCOPE it is.
- *
- * The map is already keyed by `family.variant`, so binding the scope here is what
- * makes an over-advertised projection or nested write **unrepresentable** at the
- * authoring boundary rather than merely refused at runtime: twelve projection
- * cells and eight data cells, and `create.many`/`update.many` no longer share
- * their projection with `find.many` nor their data with `create.one`.
- *
- * **Two bulk-returning projections** — `create.many` and `update.many` are the
- * row-returning bulk writes, so their projection sits in `"bulkWrite"`. Every
- * other projection-carrying variant reads or writes one addressed record and sits
- * in `"record"`, including a multi-row READ: the axis is the write being bulk, not
- * the row count. `delete.many` is the one cell where that is a judgement rather
- * than a measurement — it is a bulk write that core's grammar gives a projection,
- * and no pilot engine answers it at all, so it keeps the surface it has today
- * instead of being narrowed on a supposition.
- *
- * **Four flat bulk writes** — `create.many`, `create.count`, `update.many` and
- * `update.count` carry a data argument of own columns and own reference fields;
- * the rest admit nested writes. `upsert.unique`'s two branches are both nested.
- *
- * **This binding is core's grammar, not the adapter's routing.** A variant's real
- * scope is an adapter fact and the adapter states it on the advertised variant
- * (`OperationVariantScopes`); a host that routed, say, `update.first` through a
- * bulk-returning call would make this map's `"record"` too generous.
- *
- * An unqualified capability holds in every scope, so a Contract whose adapter has
- * not measured the axis is bound to the same surface it had before the axis
- * existed.
+ * Every standard operation's argument object, with each argument at its
+ * projection or write position.
  */
-export type OperationArgumentMap<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms> = {
+export type OperationArgumentMap<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = {
     find: {
         first: QueryProjectionArgs<C, K, "record", Forms> & {
-            where?: WhereInput<C, K, Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
             orderBy?: OrderByInput<C, K>;
         };
         unique: QueryProjectionArgs<C, K, "record", Forms> & {
-            where: UniqueWhereInput<C, K, Forms>;
+            where: UniqueWhereInput<C, K, Forms, ReferenceForms>;
         };
         many: QueryProjectionArgs<C, K, "record", Forms> & {
-            where?: WhereInput<C, K, Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
             orderBy?: OrderByInput<C, K>;
             limit?: number;
             offset?: number;
-            cursor?: CursorInput<C, K, Forms>;
+            cursor?: CursorInput<C, K, Forms, ReferenceForms>;
         };
         count: {
-            where?: WhereInput<C, K, Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
         };
     };
     create: {
         one: QueryProjectionArgs<C, K, "record", Forms> & {
-            data: CreateDataInput<C, K, "nested", Forms>;
+            data: CreateDataInput<C, K, "nested", Forms, ReferenceForms>;
         };
         many: QueryProjectionArgs<C, K, "bulkWrite", Forms> & {
-            data: readonly CreateDataInput<C, K, "bulkWrite", Forms>[];
+            data: readonly CreateDataInput<C, K, "bulkWrite", Forms, ReferenceForms>[];
         };
         count: {
-            data: readonly CreateDataInput<C, K, "bulkWrite", Forms>[];
+            data: readonly CreateDataInput<C, K, "bulkWrite", Forms, ReferenceForms>[];
         };
     };
     update: {
         first: QueryProjectionArgs<C, K, "record", Forms> & {
-            where?: WhereInput<C, K, Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
             orderBy?: OrderByInput<C, K>;
-            data: UpdateDataInput<C, K, "nested", Forms>;
+            data: UpdateDataInput<C, K, "nested", Forms, ReferenceForms>;
         };
         unique: QueryProjectionArgs<C, K, "record", Forms> & {
-            where: UniqueWhereInput<C, K, Forms>;
-            data: UpdateDataInput<C, K, "nested", Forms>;
+            where: UniqueWhereInput<C, K, Forms, ReferenceForms>;
+            data: UpdateDataInput<C, K, "nested", Forms, ReferenceForms>;
         };
         many: QueryProjectionArgs<C, K, "bulkWrite", Forms> & {
-            where?: WhereInput<C, K, Forms>;
-            data: UpdateDataInput<C, K, "bulkWrite", Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
+            data: UpdateDataInput<C, K, "bulkWrite", Forms, ReferenceForms>;
         };
         count: {
-            where?: WhereInput<C, K, Forms>;
-            data: UpdateDataInput<C, K, "bulkWrite", Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
+            data: UpdateDataInput<C, K, "bulkWrite", Forms, ReferenceForms>;
         };
     };
     delete: {
         first: QueryProjectionArgs<C, K, "record", Forms> & {
-            where?: WhereInput<C, K, Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
             orderBy?: OrderByInput<C, K>;
         };
         unique: QueryProjectionArgs<C, K, "record", Forms> & {
-            where: UniqueWhereInput<C, K, Forms>;
+            where: UniqueWhereInput<C, K, Forms, ReferenceForms>;
         };
         many: QueryProjectionArgs<C, K, "record", Forms> & {
-            where?: WhereInput<C, K, Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
         };
         count: {
-            where?: WhereInput<C, K, Forms>;
+            where?: WhereInput<C, K, Forms, ReferenceForms>;
         };
     };
     upsert: {
         unique: QueryProjectionArgs<C, K, "record", Forms> & {
-            where: UniqueWhereInput<C, K, Forms>;
-            create: CreateDataInput<C, K, "nested", Forms>;
-            update: UpdateDataInput<C, K, "nested", Forms>;
+            where: UniqueWhereInput<C, K, Forms, ReferenceForms>;
+            create: CreateDataInput<C, K, "nested", Forms, ReferenceForms>;
+            update: UpdateDataInput<C, K, "nested", Forms, ReferenceForms>;
         };
     };
 };
-/**
- * One standard operation's argument object.
- *
- * `Forms` is the scalar-form map its scalar VALUES are read through — data,
- * filters, unique selectors and cursors, at every depth. Unstated, every built-in
- * value is `unknown` ({@link UnstatedForms}); the application façade passes
- * `ApplicationScalarForms`, so a `Date` handed to a `json` field or a number to a
- * `string` one is refused where it is written rather than by `V1001` at runtime.
- * The validation layer stays the guard either way.
- */
-export type OperationArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms = UnstatedForms> = I extends {
+/** One standard operation's argument object. */
+export type OperationArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = I extends {
     family: infer F;
     variant: infer V;
-} ? F extends keyof OperationArgumentMap<C, K, Forms> ? V extends keyof OperationArgumentMap<C, K, Forms>[F] ? OperationArgumentMap<C, K, Forms>[F][V] : never : never : never;
+} ? F extends keyof OperationArgumentMap<C, K, Forms, ReferenceForms> ? V extends keyof OperationArgumentMap<C, K, Forms, ReferenceForms>[F] ? OperationArgumentMap<C, K, Forms, ReferenceForms>[F][V] : never : never : never;
 export {};