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

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

@@ -1,8 +1,9 @@
 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>;
@@ -69,7 +70,13 @@ type UnstatedForms = ScalarForms;
 /** 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. 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.
@@ -87,71 +94,92 @@ export type ScalarFilterInput = unknown | Readonly<Partial<Record<ScalarFilterOp
  * object.
  */
 type ScalarFilterShorthand<Value> = Exclude<Value, JsonObject>;
+/**
+ * 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.
+ * 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;
 }>;
-/** A `where` argument for a unique operation: the values of one identifier. */
-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"`. */
@@ -184,9 +212,12 @@ export type OrderByEntry<C extends Contract, K extends ResourceKey<C>> = {
 }[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>[];
-/** A `cursor` argument: scalar field values of the row the page starts from. */
-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>;
+/**
+ * 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>;
@@ -264,35 +295,51 @@ type WritableScalarKey<C extends Contract, K extends ResourceKey<C>, Stage exten
  */
 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.
@@ -302,8 +349,8 @@ type NoAdvertisedMember = {
 };
 /** `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: one entry of the field (`$push` on a
@@ -322,103 +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. A write position applies
  * to the top level only; nested writes use the unrestricted position (see
- * {@link WriteScope}).
+ * {@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 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. */
-export type OperationArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms = UnstatedForms> = I extends {
+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 {};

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

@@ -14,3 +14,5 @@ export type OperationIdentity = {
 }[OperationFamily];
 /** Parses a family and variant into an {@link OperationIdentity}, or `undefined` when they name no standard operation. */
 export declare function parseOperationIdentity(family: string, variant: string): OperationIdentity | undefined;
+/** Whether `family` names one of the standard operation families. */
+export declare function isOperationFamily(family: string): boolean;

package/dist/operations/operation-identity.js

@@ -23,3 +23,6 @@ export function parseOperationIdentity(family, variant) {
     }
     return { family, variant };
 }
+export function isOperationFamily(family) {
+    return Object.keys(STANDARD_OPERATIONS).some((key) => key.startsWith(`${family}.`));
+}

package/dist/operations/operation-validator-core.d.ts

@@ -1,5 +1,5 @@
 import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "./operation-identity.js";
+import { type OperationIdentity } from "./operation-identity.js";
 import type { ValidationIssue } from "./validation-code.js";
 /** An operation's arguments as an object, before validation. */
 export type SemanticOperationArguments = Readonly<Record<string, unknown>>;

package/dist/operations/operation-validator-core.js

@@ -2,6 +2,7 @@ import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { advertisedDirectivesAt, advertisedReducers, advertisedReducersAt, holdsAt, } from "../contracts/field.js";
 import { isPlainRecord } from "../runtime/scalar-runtime.js";
 import { routeTransactionReferenceCandidate } from "../transactions/transaction-reference.js";
+import { isOperationFamily, } from "./operation-identity.js";
 import { NESTED_PROJECTION_SCOPE, resolveProjectionScope, } from "./projection-scope.resolver.js";
 import { NESTED_WRITE_SCOPE, resolveWriteScope, } from "./write-scope.resolver.js";
 const OPERATION_ARGUMENT_RULES = {
@@ -111,7 +112,7 @@ function validateTopLevelArguments(request, args) {
     const rule = OPERATION_ARGUMENT_RULES[key];
     const issues = [];
     if (rule === undefined) {
-        addIssue(issues, "V1001", ["operation"], `Operation "${key}" is not part of the standard operation grammar.`);
+        addIssue(issues, "V1001", [isOperationFamily(request.family) ? "variant" : "family"], `Operation "${key}" is not part of the standard operation grammar.`);
         return issues;
     }
     for (const required of rule.required) {
@@ -168,6 +169,13 @@ function validateScalarFilter(fieldName, field, value, path, state) {
         }
         return;
     }
+    if (state.transactionReferences === true &&
+        routeTransactionReferenceCandidate(value).kind !== "ordinary") {
+        if (!includes(supported, "equals")) {
+            addIssue(state.issues, "V1006", path, `Equality filtering is not available on field "${fieldName}".`);
+        }
+        return;
+    }
     if (!isPlainRecord(value)) {
         if (!includes(supported, "equals")) {
             addIssue(state.issues, "V1006", path, `Equality filtering is not available on field "${fieldName}".`);
@@ -270,6 +278,9 @@ function validateWhere(contract, resourceName, where, path, state, depth) {
         if (field.kind === "scalar") {
             validateScalarFilter(key, field, value, fieldPath, state);
         }
+        else if (state.scalarOnly === true) {
+            addIssue(state.issues, "V1006", fieldPath, `Relation filter "${key}" is not available here: a nested $update or $delete filter on this relation takes scalar fields only.`);
+        }
         else {
             validateRelationFilter(contract, key, field, value, fieldPath, state, depth);
         }
@@ -570,7 +581,7 @@ function validateScalarMutation(fieldName, field, value, stage, path, issues, tr
         }
     }
 }
-function validateRelationMutationEntry(contract, edge, directive, value, path, issues) {
+function validateRelationMutationEntry(contract, edge, directive, value, path, issues, transactionReferences) {
     const target = edge.target;
     if (edge.cardinality === "one" && Array.isArray(value)) {
         addIssue(issues, "V1012", path, `To-one relation directive "${directive}" does not accept arrays.`);
@@ -619,7 +630,7 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
     if (directive === "$create") {
         const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
         for (const entry of entries) {
-            validateMutationData(contract, target, entry, "create", NESTED_WRITE_SCOPE, path, issues);
+            validateMutationData(contract, target, entry, "create", NESTED_WRITE_SCOPE, path, issues, transactionReferences);
         }
         return;
     }
@@ -631,7 +642,7 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
                 continue;
             }
             validateUniqueSelector(contract, target, entry.where, [...path, "where"], issues);
-            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...path, "create"], issues);
+            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...path, "create"], issues, transactionReferences);
         }
         return;
     }
@@ -650,13 +661,15 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
                 const state = {
                     issues,
                     structuralRoot: [...path, "where"],
+                    transactionReferences,
+                    scalarOnly: edge.capabilities.nestedWriteFilter === "scalar",
                     booleanFilterNodes: 0,
                     nestingExceeded: false,
                     booleanNodesExceeded: false,
                 };
                 validateWhere(contract, target, entry.where, [...path, "where"], state, 1);
             }
-            validateMutationData(contract, target, entry.data, "update", NESTED_WRITE_SCOPE, [...path, "data"], issues);
+            validateMutationData(contract, target, entry.data, "update", NESTED_WRITE_SCOPE, [...path, "data"], issues, transactionReferences);
         }
         return;
     }
@@ -671,6 +684,8 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
                 const state = {
                     issues,
                     structuralRoot: [...path, "where"],
+                    transactionReferences,
+                    scalarOnly: edge.capabilities.nestedWriteFilter === "scalar",
                     booleanFilterNodes: 0,
                     nestingExceeded: false,
                     booleanNodesExceeded: false,
@@ -685,6 +700,8 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
                 const state = {
                     issues,
                     structuralRoot: [...path, "where"],
+                    transactionReferences,
+                    scalarOnly: edge.capabilities.nestedWriteFilter === "scalar",
                     booleanFilterNodes: 0,
                     nestingExceeded: false,
                     booleanNodesExceeded: false,
@@ -707,12 +724,12 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
             if ("where" in entry) {
                 validateUniqueSelector(contract, target, entry.where, [...path, "where"], issues);
             }
-            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...path, "create"], issues);
-            validateMutationData(contract, target, entry.update, "update", NESTED_WRITE_SCOPE, [...path, "update"], issues);
+            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...path, "create"], issues, transactionReferences);
+            validateMutationData(contract, target, entry.update, "update", NESTED_WRITE_SCOPE, [...path, "update"], issues, transactionReferences);
         }
     }
 }
-function validateRelationMutation(contract, fieldName, field, value, stage, scope, path, issues) {
+function validateRelationMutation(contract, fieldName, field, value, stage, scope, path, issues, transactionReferences) {
     const directives = advertisedDirectivesAt(field.capabilities[stage], scope);
     if (directives === undefined) {
         addIssue(issues, "V1006", path, `Relation "${fieldName}" is not writable during ${stage}.`);
@@ -728,7 +745,7 @@ function validateRelationMutation(contract, fieldName, field, value, stage, scop
             addIssue(issues, "V1006", directivePath, `Relation mutation directive "${directive}" is not available on relation "${fieldName}".`);
             continue;
         }
-        validateRelationMutationEntry(contract, field, directive, directiveValue, directivePath, issues);
+        validateRelationMutationEntry(contract, field, directive, directiveValue, directivePath, issues, transactionReferences);
     }
 }
 function validateMutationData(contract, resourceName, data, stage, scope, path, issues, transactionReferences = false) {
@@ -752,7 +769,7 @@ function validateMutationData(contract, resourceName, data, stage, scope, path,
             validateScalarMutation(fieldName, field, value, stage, fieldPath, issues, transactionReferences);
         }
         else {
-            validateRelationMutation(contract, fieldName, field, value, stage, scope, fieldPath, issues);
+            validateRelationMutation(contract, fieldName, field, value, stage, scope, fieldPath, issues, transactionReferences);
         }
     }
 }
@@ -830,6 +847,7 @@ export function validateOperationArguments(contract, request, options) {
             const state = {
                 issues,
                 structuralRoot: ["arguments", "where"],
+                transactionReferences: options?.transactionReferences === true,
                 booleanFilterNodes: 0,
                 nestingExceeded: false,
                 booleanNodesExceeded: false,