@aventara/core 1.0.0-rc.0 → 1.0.0-rc.2

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

@@ -1,12 +1,14 @@
-import type { Contract } from "../contracts/contract.js";
+import type { AvContract } from "../contracts/contract.js";
 import type { ScalarForms } from "../contracts/scalar-value-type.js";
-import type { OperationResponse } from "../runtime/operation-response.js";
-import type { Operation } from "../transactions/deferred-operation.js";
+import type { AvOperation } from "../transactions/deferred-operation.js";
 import type { ReferenceableArgumentsFor } from "../transactions/transaction-reference.js";
-import type { OperationArgumentsFor, ResourceKey } from "./operation-arguments.js";
-import type { OperationFamily, OperationIdentity, OperationVariant } from "./operation-identity.js";
+import type { AvOperationArgumentsFor, AvResourceKey } from "./operation-arguments.js";
+import type { AvOperationFamily, AvOperationIdentity, AvOperationVariant } from "./operation-identity.js";
 import type { AdmittedOperationResult } from "./operation-result.js";
 type ProjectionKey = "select" | "include";
+/** The origin of a deferred handle's builder (`AvOperationHandle`). */
+type HandleOrigin = "application" | "client";
+type AnyOrigin = any;
 type SelectOf<Args> = Args extends {
     readonly select?: infer Select;
 } ? Exclude<Select, undefined> : never;
@@ -30,15 +32,15 @@ type InferredProjection<Select, Include> = [Select] extends [never] ? [Include]
 type ArgumentList<Rest, Parameter> = Record<never, never> extends Rest ? [args?: Parameter] : [args: Parameter];
 /** A direct call's parameters: the argument, then the caller's per-call options. */
 type CallArgumentList<Rest, Parameter, Options> = Record<never, never> extends Rest ? [args?: Parameter, options?: Options] : [args: Parameter, options?: Options];
-type ResourceOperationsOf<C extends Contract, R extends ResourceKey<C>> = C["resources"][R]["operations"];
+type ResourceOperationsOf<C extends AvContract, R extends AvResourceKey<C>> = C["resources"][R]["operations"];
 /**
  * The operations Contract `C` advertises: one property per Resource, one per
  * family under it, one identity per variant under that.
  */
-export type OperationGrammar<C extends Contract> = {
-    readonly [R in ResourceKey<C>]: {
-        readonly [F in Extract<keyof ResourceOperationsOf<C, R>, OperationFamily>]: {
-            readonly [V in Extract<keyof NonNullable<ResourceOperationsOf<C, R>[F]>, OperationVariant<F>>]: Extract<OperationIdentity, {
+export type AvOperationGrammar<C extends AvContract> = {
+    readonly [R in AvResourceKey<C>]: {
+        readonly [F in Extract<keyof ResourceOperationsOf<C, R>, AvOperationFamily>]: {
+            readonly [V in Extract<keyof NonNullable<ResourceOperationsOf<C, R>[F]>, AvOperationVariant<F>>]: Extract<AvOperationIdentity, {
                 readonly family: F;
                 readonly variant: V;
             }>;
@@ -50,33 +52,30 @@ export type OperationGrammar<C extends Contract> = {
  * This is the value a committed transaction or a remote call returns for the
  * operation.
  */
-export type OperationSlot<I extends OperationIdentity, Result> = I["variant"] extends "first" ? Result | null : Result;
-/**
- * What a direct call resolves, by its `Settlement`: `"response"` — the whole
- * `OperationResponse`, as core's façades answer in process, never throwing;
- * `"data"` — the slot, as a remote client answers, every failure thrown.
- */
-type Settled<Settlement extends "response" | "data", I extends OperationIdentity, Result> = Settlement extends "data" ? OperationSlot<I, Result> : OperationResponse<Result>;
-type ProjectingCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Args, ResultForms extends ScalarForms, Settlement extends "response" | "data", Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<Settlement, I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
-type PlainCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Args, ResultForms extends ScalarForms, Settlement extends "response" | "data", Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<Settlement, I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
+export type AvOperationSlot<I extends AvOperationIdentity, Result> = I["variant"] extends "first" ? Result | null : Result;
+/** What a direct call resolves: the slot, every failure thrown. */
+type Settled<I extends AvOperationIdentity, Result> = AvOperationSlot<I, Result>;
+type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
+type PlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
 /**
  * One direct call: its arguments in `Forms`, its result in `ResultForms`,
- * resolving as `Settlement` says, taking `Options` per call — generic in its
+ * resolving the slot and throwing every failure, taking `Options` per call. It is generic in its
  * projection when it carries one.
  */
-export type OperationCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms, Settlement extends "response" | "data", Options> = "select" extends keyof OperationArgumentsFor<C, R, I, Forms> ? ProjectingCall<C, R, I, OperationArgumentsFor<C, R, I, Forms>, ResultForms, Settlement, Options> : PlainCall<C, R, I, OperationArgumentsFor<C, R, I, Forms>, ResultForms, Settlement, Options>;
+export type AvOperationCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms, Options> = "select" extends keyof AvOperationArgumentsFor<C, R, I, Forms> ? ProjectingCall<C, R, I, AvOperationArgumentsFor<C, R, I, Forms>, ResultForms, Options> : PlainCall<C, R, I, AvOperationArgumentsFor<C, R, I, Forms>, ResultForms, Options>;
 /**
  * A deferred operation's arguments: `Forms`, with reference positions opened to a
  * `$ref` typed in `ResultForms` — the forms the source's final data is read in, so a
  * reference carries what its source resolves.
  */
-type DeferredArguments<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
-type DeferredProjectingCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Args, ResultForms extends ScalarForms> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => Operation<OperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
-type DeferredPlainCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Args, ResultForms extends ScalarForms> = (...args: ArgumentList<Args, Args>) => Operation<OperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
+type DeferredArguments<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
+type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
+type DeferredPlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = (...args: ArgumentList<Args, Args>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>, Origin>;
 /**
- * One deferred operation: a handle typed `Operation<OperationSlot<…>>` — `$ref`
- * present exactly where the result is one row. A handle is not a request and takes no
- * options.
+ * One deferred operation: a handle typed `AvOperation<AvOperationSlot<…>, Origin>`,
+ * with `$ref` present exactly where the result is one row. A handle is not a
+ * request and takes no options. `Origin` is the builder's: a transaction's
+ * handles all share one.
  */
-export type DeferredOperationCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = "select" extends keyof DeferredArguments<C, R, I, Forms, ResultForms> ? DeferredProjectingCall<C, R, I, DeferredArguments<C, R, I, Forms, ResultForms>, ResultForms> : DeferredPlainCall<C, R, I, DeferredArguments<C, R, I, Forms, ResultForms>, ResultForms>;
+export type AvDeferredOperationCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms, Origin extends HandleOrigin = AnyOrigin> = "select" extends keyof DeferredArguments<C, R, I, Forms, ResultForms> ? DeferredProjectingCall<C, R, I, DeferredArguments<C, R, I, Forms, ResultForms>, ResultForms, Origin> : DeferredPlainCall<C, R, I, DeferredArguments<C, R, I, Forms, ResultForms>, ResultForms, Origin>;
 export {};

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

@@ -1,18 +1,18 @@
-import type { ResourceOperations } from "../contracts/resource-operations.js";
+import type { AvResourceOperations } from "../contracts/resource-operations.js";
 /** A standard operation family: `find`, `create`, `update`, `delete` or `upsert`. */
-export type OperationFamily = Extract<keyof ResourceOperations, string>;
+export type AvOperationFamily = Extract<keyof AvResourceOperations, string>;
 /** The variants of operation family `F`, such as `many` or `unique`. */
-export type OperationVariant<F extends OperationFamily> = Extract<keyof NonNullable<ResourceOperations[F]>, string>;
+export type AvOperationVariant<F extends AvOperationFamily> = Extract<keyof NonNullable<AvResourceOperations[F]>, string>;
 /** A standard operation's `family` and `variant`. */
-export type OperationIdentity = {
-    [F in OperationFamily]: {
-        [V in OperationVariant<F>]: {
+export type AvOperationIdentity = {
+    [F in AvOperationFamily]: {
+        [V in AvOperationVariant<F>]: {
             readonly family: F;
             readonly variant: V;
         };
-    }[OperationVariant<F>];
-}[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;
+    }[AvOperationVariant<F>];
+}[AvOperationFamily];
+/** Parses a family and variant into an {@link AvOperationIdentity}, or `undefined` when they name no standard operation. */
+export declare function parseOperationIdentity(family: string, variant: string): AvOperationIdentity | undefined;
 /** Whether `family` names one of the standard operation families. */
 export declare function isOperationFamily(family: string): boolean;

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

@@ -1,21 +1,21 @@
-import type { Contract } from "../contracts/contract.js";
-import type { RelationField, ScalarField } from "../contracts/field.js";
-import type { ApplicationScalarForms, ScalarForms, ScalarValueType } from "../contracts/scalar-value-type.js";
-import type { FieldKey, OperationArgumentsFor, ResourceKey } from "./operation-arguments.js";
-import type { OperationIdentity } from "./operation-identity.js";
-type FieldOf<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>> = C["resources"][K]["fields"][F];
+import type { AvContract } from "../contracts/contract.js";
+import type { AvRelationField, AvScalarField } from "../contracts/field.js";
+import type { AvApplicationScalarForms, AvScalarValueType, ScalarForms } from "../contracts/scalar-value-type.js";
+import type { AvFieldKey, AvOperationArgumentsFor, AvResourceKey } from "./operation-arguments.js";
+import type { AvOperationIdentity } from "./operation-identity.js";
+type FieldOf<C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>> = C["resources"][K]["fields"][F];
 /**
  * The fields returned when no projection is given: the scalars whose `select`
  * is exactly `true`. A write-only field never appears.
  */
-type DefaultKey<C extends Contract, K extends ResourceKey<C>> = {
-    [F in FieldKey<C, K>]: FieldOf<C, K, F> extends {
+type DefaultKey<C extends AvContract, K extends AvResourceKey<C>> = {
+    [F in AvFieldKey<C, K>]: FieldOf<C, K, F> extends {
         readonly kind: "scalar";
         readonly capabilities: {
             readonly select: true;
         };
     } ? F : never;
-}[FieldKey<C, K>];
+}[AvFieldKey<C, K>];
 /** The field one projection entry names: a bare key, or a relation entry's key. */
 type EntryKey<Entry> = Entry extends string ? Entry : Entry extends object ? Extract<keyof Entry, string> : never;
 /**
@@ -31,26 +31,26 @@ type EntryArguments<Entry, F extends string> = Entry extends object ? Entry exte
  * `Entries` carries the relation entries' own arguments down; the scalar branch
  * ignores them.
  */
-type ProjectedFields<C extends Contract, K extends ResourceKey<C>, Keys extends FieldKey<C, K>, Entries, Forms extends ScalarForms> = {
-    readonly [F in Keys]: FieldOf<C, K, F> extends ScalarField<C> ? ScalarValueType<C, FieldOf<C, K, F>, Forms> : FieldOf<C, K, F> extends RelationField<C> ? RelationResult<C, Extract<FieldOf<C, K, F>["target"], ResourceKey<C>>, FieldOf<C, K, F>, EntryArguments<Entries, F>, Forms> : never;
+type ProjectedFields<C extends AvContract, K extends AvResourceKey<C>, Keys extends AvFieldKey<C, K>, Entries, Forms extends ScalarForms> = {
+    readonly [F in Keys]: FieldOf<C, K, F> extends AvScalarField<C> ? AvScalarValueType<C, FieldOf<C, K, F>, Forms> : FieldOf<C, K, F> extends AvRelationField<C> ? RelationResult<C, Extract<FieldOf<C, K, F>["target"], AvResourceKey<C>>, FieldOf<C, K, F>, EntryArguments<Entries, F>, Forms> : never;
 };
 /**
  * One projection level: `select` returns exactly its entries, `include` the
  * default fields plus the named relations, and no projection the default fields.
  */
-type ProjectedRecord<C extends Contract, K extends ResourceKey<C>, Arguments, Forms extends ScalarForms> = [Arguments] extends [never] ? ProjectedFields<C, K, DefaultKey<C, K>, never, Forms> : [Arguments] extends [{
+type ProjectedRecord<C extends AvContract, K extends AvResourceKey<C>, Arguments, Forms extends ScalarForms> = [Arguments] extends [never] ? ProjectedFields<C, K, DefaultKey<C, K>, never, Forms> : [Arguments] extends [{
     readonly select: readonly (infer Entry)[];
-}] ? ProjectedFields<C, K, Extract<EntryKey<Entry>, FieldKey<C, K>>, Entry, Forms> : [Arguments] extends [{
+}] ? ProjectedFields<C, K, Extract<EntryKey<Entry>, AvFieldKey<C, K>>, Entry, Forms> : [Arguments] extends [{
     readonly include: readonly (infer Entry)[];
-}] ? ProjectedFields<C, K, DefaultKey<C, K> | Extract<EntryKey<Entry>, FieldKey<C, K>>, Entry, Forms> : ProjectedFields<C, K, DefaultKey<C, K>, never, Forms>;
+}] ? ProjectedFields<C, K, DefaultKey<C, K> | Extract<EntryKey<Entry>, AvFieldKey<C, K>>, Entry, Forms> : ProjectedFields<C, K, DefaultKey<C, K>, never, Forms>;
 /**
  * A to-many entry whose `select` asks for `$count`: the value is an object with
  * the rows and the count, not the row array.
  */
-type CountEnvelope<C extends Contract, Target extends ResourceKey<C>, Entry, Forms extends ScalarForms> = [Exclude<Entry, "$count">] extends [never] ? {
+type CountEnvelope<C extends AvContract, Target extends AvResourceKey<C>, Entry, Forms extends ScalarForms> = [Exclude<Entry, "$count">] extends [never] ? {
     readonly count: number;
 } : {
-    readonly data: readonly ProjectedFields<C, Target, Extract<EntryKey<Entry>, FieldKey<C, Target>>, Exclude<Entry, "$count">, Forms>[];
+    readonly data: readonly ProjectedFields<C, Target, Extract<EntryKey<Entry>, AvFieldKey<C, Target>>, Exclude<Entry, "$count">, Forms>[];
     readonly count: number;
 };
 /** The entries of an argument's own `select`, or `never` when it has none. */
@@ -61,16 +61,16 @@ type SelectEntry<Arguments> = Arguments extends {
  * The value of one relation entry. A to-many entry is the rows-and-count object
  * when its own `select` asks for `$count`; otherwise the row array.
  */
-type RelationResult<C extends Contract, Target extends ResourceKey<C>, Relation extends RelationField<C>, Arguments, Forms extends ScalarForms> = Relation["cardinality"] extends "many" ? [Extract<SelectEntry<Arguments>, "$count">] extends [never] ? readonly ProjectedRecord<C, Target, Arguments, Forms>[] : CountEnvelope<C, Target, SelectEntry<Arguments>, Forms> : ProjectedRecord<C, Target, Arguments, Forms> | (true extends Relation["nullable"] ? null : never);
+type RelationResult<C extends AvContract, Target extends AvResourceKey<C>, Relation extends AvRelationField<C>, Arguments, Forms extends ScalarForms> = Relation["cardinality"] extends "many" ? [Extract<SelectEntry<Arguments>, "$count">] extends [never] ? readonly ProjectedRecord<C, Target, Arguments, Forms>[] : CountEnvelope<C, Target, SelectEntry<Arguments>, Forms> : ProjectedRecord<C, Target, Arguments, Forms> | (true extends Relation["nullable"] ? null : never);
 /**
- * The value a standard operation returns in `OperationResponse.data` on success,
+ * The value a standard operation returns in `AvOperationResponse.data` on success,
  * derived from the Contract, the Resource, the operation identity and the projection
  * argument.
  */
-export type OperationResultFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Args extends OperationArgumentsFor<C, K, I>, Forms extends ScalarForms = ApplicationScalarForms> = AdmittedOperationResult<C, K, I, Args, Forms>;
+export type AvOperationResultFor<C extends AvContract, K extends AvResourceKey<C>, I extends AvOperationIdentity, Args extends AvOperationArgumentsFor<C, K, I>, Forms extends ScalarForms = AvApplicationScalarForms> = AdmittedOperationResult<C, K, I, Args, Forms>;
 /**
- * {@link OperationResultFor}, for a projection already checked against the
+ * {@link AvOperationResultFor}, for a projection already checked against the
  * operation's argument type.
  */
-export type AdmittedOperationResult<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Args, Forms extends ScalarForms = ApplicationScalarForms> = I["variant"] extends "count" ? number : I["variant"] extends "many" ? readonly ProjectedRecord<C, K, Args, Forms>[] : ProjectedRecord<C, K, Args, Forms>;
+export type AdmittedOperationResult<C extends AvContract, K extends AvResourceKey<C>, I extends AvOperationIdentity, Args, Forms extends ScalarForms = AvApplicationScalarForms> = I["variant"] extends "count" ? number : I["variant"] extends "many" ? readonly ProjectedRecord<C, K, Args, Forms>[] : ProjectedRecord<C, K, Args, Forms>;
 export {};

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

@@ -1,6 +1,6 @@
-import type { Contract } from "../contracts/contract.js";
-import { type OperationIdentity } from "./operation-identity.js";
-import type { ValidationIssue } from "./validation-code.js";
+import type { AvContract } from "../contracts/contract.js";
+import { type AvOperationIdentity } from "./operation-identity.js";
+import type { AvValidationIssue } from "./validation-code.js";
 /** An operation's arguments as an object, before validation. */
 export type SemanticOperationArguments = Readonly<Record<string, unknown>>;
 type OperationValidationSuccess = {
@@ -9,7 +9,7 @@ type OperationValidationSuccess = {
 };
 type OperationValidationFailure = {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
 /** The answer of {@link validateOperationArguments}: success, or the issues found. */
 export type OperationValidationResult = OperationValidationSuccess | OperationValidationFailure;
@@ -21,8 +21,8 @@ export type OperationValidationOptions = {
  * Contract does not have (`V1005` at `["resource"]`, rolling up to `A2001`). The one
  * spelling — the protocol's absence answers build theirs with it.
  */
-export declare function resourceUnavailableIssue(resource: string): ValidationIssue;
-export declare function validateOperationArguments(contract: Contract, request: OperationIdentity & {
+export declare function resourceUnavailableIssue(resource: string): AvValidationIssue;
+export declare function validateOperationArguments(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
     readonly arguments: unknown;
 }, options?: OperationValidationOptions): OperationValidationResult;

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

@@ -1,10 +1,11 @@
+import { FILTER_MODES, } from "../contracts/capability.js";
 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 { isPlainRecord, unsentReadValueIssue, } 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";
+import { NESTED_WRITE_SCOPE, resolveWriteScope, TO_MANY_UPDATE_WRITE_SCOPE, } from "./write-scope.resolver.js";
 const OPERATION_ARGUMENT_RULES = {
     "find.first": {
         allowed: ["where", "orderBy", "select", "include"],
@@ -153,12 +154,15 @@ function checkDepth(contract, state, depth) {
     }
     return false;
 }
-function validateScalarFilter(fieldName, field, value, path, state) {
+function validateScalarFilter(contract, fieldName, field, value, path, state, depth) {
     const supported = field.capabilities.filter;
     if (supported === undefined) {
         addIssue(state.issues, "V1006", path, `Filtering is not available on field "${fieldName}".`);
         return;
     }
+    validateScalarCondition(contract, fieldName, field, supported, value, path, state, depth);
+}
+function validateScalarCondition(contract, fieldName, field, supported, value, path, state, depth) {
     if (value === null) {
         if (!field.nullable) {
             addIssue(state.issues, "V1001", path, `Field "${fieldName}" is not nullable.`);
@@ -187,11 +191,63 @@ function validateScalarFilter(fieldName, field, value, path, state) {
         addIssue(state.issues, "V1001", path, `Filter object for field "${fieldName}" must contain an operator.`);
         return;
     }
+    refuseDanglingQualifiers(fieldName, value, path, state);
     for (const operator of operators) {
         if (!includes(supported, operator)) {
             addIssue(state.issues, "V1006", [...path, operator], `Filter operator "${operator}" is not available on field "${fieldName}".`);
+            continue;
+        }
+        if (operator === "mode") {
+            refuseUnavailableMode(field, fieldName, value, path, state);
+            continue;
         }
+        if (operator === "not") {
+            const operand = value[operator];
+            if (isPlainRecord(operand) && !checkDepth(contract, state, depth + 1)) {
+                continue;
+            }
+            validateScalarCondition(contract, fieldName, field, supported, operand, [...path, operator], state, isPlainRecord(operand) ? depth + 1 : depth);
+        }
+    }
+}
+function refuseDanglingQualifiers(fieldName, level, path, state) {
+    const qualifiers = DANGLING_QUALIFIERS.filter((key) => Object.hasOwn(level, key));
+    if (qualifiers.length === 0) {
+        return;
+    }
+    const compares = Object.entries(level).some(([operator, operand]) => !includes(DANGLING_QUALIFIERS, operator) &&
+        !(operator === "not" && isNegatedOperatorObject(operand, state)));
+    if (compares) {
+        return;
     }
+    for (const qualifier of qualifiers) {
+        addIssue(state.issues, "V1001", [...path, qualifier], `${qualifier} on field "${fieldName}" qualifies no operator: write it next to the operator it applies to (inside "not" to apply to a negated one).`);
+    }
+}
+const DANGLING_QUALIFIERS = ["mode", "path"];
+function isNegatedOperatorObject(operand, state) {
+    return (isPlainRecord(operand) &&
+        !(state.transactionReferences === true &&
+            routeTransactionReferenceCandidate(operand).kind !== "ordinary"));
+}
+function refuseUnavailableMode(field, fieldName, level, path, state) {
+    const mode = level.mode;
+    if (mode === "default" ||
+        typeof mode !== "string" ||
+        !includes(FILTER_MODES, mode)) {
+        return;
+    }
+    const { filterModes = [], pathFilterModes } = field.capabilities;
+    const atPath = Object.hasOwn(level, "path") && pathFilterModes !== undefined;
+    if (includes(atPath ? pathFilterModes : filterModes, mode)) {
+        return;
+    }
+    const where = atPath
+        ? " at a path"
+        : pathFilterModes !== undefined && includes(pathFilterModes, mode)
+            ? " without a path"
+            : "";
+    addIssue(state.issues, "V1006", [...path, "mode"], `Filter mode "${mode}" is not available on field "${fieldName}"${where}.`);
 }
 function validateRelationFilter(contract, fieldName, field, value, path, state, depth) {
     const supported = field.capabilities.filter;
@@ -199,6 +255,10 @@ function validateRelationFilter(contract, fieldName, field, value, path, state,
         addIssue(state.issues, "V1006", path, `Filtering is not available on relation "${fieldName}".`);
         return;
     }
+    if (value === undefined) {
+        state.issues.push(unsentReadValueIssue(path));
+        return;
+    }
     if (field.cardinality === "one") {
         if (value === null) {
             if (!field.nullable || !includes(supported, "null")) {
@@ -238,10 +298,20 @@ function validateRelationFilter(contract, fieldName, field, value, path, state,
         validateWhere(contract, field.target, value[operator], [...path, operator], state, depth + 1);
     }
 }
+const UNDEFINED_ARGUMENT_MESSAGES = {
+    where: "where must not be undefined: leave the key out to mean no filter.",
+    limit: "limit must not be undefined: leave the key out to mean no limit.",
+    offset: "offset must not be undefined: leave the key out to mean no offset.",
+    cursor: "cursor must not be undefined: leave the key out to mean no cursor.",
+};
 function validateWhere(contract, resourceName, where, path, state, depth) {
     if (!checkDepth(contract, state, depth)) {
         return;
     }
+    if (where === undefined) {
+        state.issues.push(unsentReadValueIssue(path));
+        return;
+    }
     if (!isRecord(where)) {
         addIssue(state.issues, "V1001", path, "where must be an object.");
         return;
@@ -276,7 +346,7 @@ function validateWhere(contract, resourceName, where, path, state, depth) {
         }
         const fieldPath = [...path, key];
         if (field.kind === "scalar") {
-            validateScalarFilter(key, field, value, fieldPath, state);
+            validateScalarFilter(contract, key, field, value, fieldPath, state, depth);
         }
         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.`);
@@ -355,7 +425,9 @@ function validateOrderBy(contract, resourceName, orderBy, path, issues) {
                 valueKeys[1] !== "sort" ||
                 (value.sort !== "asc" && value.sort !== "desc") ||
                 (value.nulls !== "first" && value.nulls !== "last")) {
-                addIssue(issues, "V1001", fieldPath, `Extended null ordering for "${fieldName}" must contain sort and nulls.`);
+                addIssue(issues, "V1001", fieldPath, Object.hasOwn(value, "$ref")
+                    ? `A transaction reference cannot stand in orderBy: order "${fieldName}" by "asc", "desc" or { sort, nulls }.`
+                    : `Null ordering for "${fieldName}" must be exactly { sort: "asc" | "desc", nulls: "first" | "last" }.`);
                 continue;
             }
             if (!field.nullable || field.capabilities.orderNulls !== true) {
@@ -382,6 +454,10 @@ function validateOrderBy(contract, resourceName, orderBy, path, issues) {
     return analysis;
 }
 function validatePaginationValue(contract, name, value, path, issues) {
+    if (value === undefined) {
+        addIssue(issues, "V1001", path, UNDEFINED_ARGUMENT_MESSAGES[name]);
+        return;
+    }
     if (!Number.isInteger(value) || typeof value !== "number" || value < 0) {
         addIssue(issues, "V1001", path, `${name} must be a non-negative integer.`);
         return;
@@ -391,6 +467,10 @@ function validatePaginationValue(contract, name, value, path, issues) {
     }
 }
 function validateCursor(contract, resourceName, cursor, orderBy, path, issues) {
+    if (cursor === undefined) {
+        addIssue(issues, "V1009", path, UNDEFINED_ARGUMENT_MESSAGES.cursor);
+        return;
+    }
     if (!isRecord(cursor) || orderBy === undefined) {
         addIssue(issues, "V1009", path, "Cursor pagination requires an object cursor and explicit deterministic orderBy.");
         return;
@@ -502,6 +582,9 @@ function validateRelationProjection(contract, edge, scope, value, path, issues)
         if (!includes(edge.capabilities.filter, "nested")) {
             addIssue(issues, "V1006", [...path, "where"], "Nested returned-relation filtering is not available on this edge.");
         }
+        else if (value.where === undefined) {
+            addIssue(issues, "V1001", [...path, "where"], UNDEFINED_ARGUMENT_MESSAGES.where);
+        }
         else {
             const state = {
                 issues,
@@ -575,11 +658,16 @@ function validateScalarMutation(fieldName, field, value, stage, path, issues, tr
         addIssue(issues, "V1001", path, "Scalar mutation action objects may contain only $-prefixed directive keys.");
         return;
     }
+    let unavailable = false;
     for (const directive of directiveKeys) {
         if (!includes(directives, directive)) {
+            unavailable = true;
             addIssue(issues, "V1006", [...path, directive], `Mutation directive "${directive}" is not available on field "${fieldName}".`);
         }
     }
+    if (!unavailable && directiveKeys.length > 1) {
+        addIssue(issues, "V1001", path, "Scalar mutation action objects may contain only one directive.");
+    }
 }
 function validateRelationMutationEntry(contract, edge, directive, value, path, issues, transactionReferences) {
     const target = edge.target;
@@ -669,7 +757,9 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
                 };
                 validateWhere(contract, target, entry.where, [...path, "where"], state, 1);
             }
-            validateMutationData(contract, target, entry.data, "update", NESTED_WRITE_SCOPE, [...path, "data"], issues, transactionReferences);
+            validateMutationData(contract, target, entry.data, "update", edge.cardinality === "many"
+                ? TO_MANY_UPDATE_WRITE_SCOPE
+                : NESTED_WRITE_SCOPE, [...path, "data"], issues, transactionReferences);
         }
         return;
     }
@@ -843,6 +933,9 @@ export function validateOperationArguments(contract, request, options) {
         if (isUniqueOperation(request)) {
             validateUniqueSelector(contract, request.resource, request.arguments.where, ["arguments", "where"], issues);
         }
+        else if (request.arguments.where === undefined) {
+            addIssue(issues, "V1001", ["arguments", "where"], UNDEFINED_ARGUMENT_MESSAGES.where);
+        }
         else {
             const state = {
                 issues,

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

@@ -1,10 +1,10 @@
-import type { Contract } from "../contracts/contract.js";
-import { type OperationIdentity } from "./operation-identity.js";
+import type { AvContract } from "../contracts/contract.js";
+import { type AvOperationIdentity } from "./operation-identity.js";
 import { type OperationValidationOptions, type OperationValidationResult } from "./operation-validator-core.js";
-import type { ValidationIssue } from "./validation-code.js";
+import type { AvValidationIssue } from "./validation-code.js";
 export type { OperationValidationOptions, OperationValidationResult, SemanticOperationArguments, } from "./operation-validator-core.js";
 /** The key of a request's operation identity that makes it unavailable. */
-export declare function unavailableOperationKey(contract: Contract, request: {
+export declare function unavailableOperationKey(contract: AvContract, request: {
     readonly resource: string;
     readonly family: string;
 }): "family" | "variant";
@@ -15,25 +15,25 @@ export declare function unavailableOperationKey(contract: Contract, request: {
  * {@link unavailableOperationKey}). The one spelling — the protocol's absence
  * answers build theirs with it, so a caller cannot tell which layer answered.
  */
-export declare function operationUnavailableIssue(contract: Contract, request: {
+export declare function operationUnavailableIssue(contract: AvContract, request: {
     readonly resource: string;
     readonly family: string;
     readonly variant: string;
-}): ValidationIssue;
+}): AvValidationIssue;
 /**
  * The availability answer alone — `V1006` when the active Contract does not advertise
  * the operation on a Resource it has — read from the request's identity, never its
  * arguments. A door that refuses unreadable arguments asks this first, so an
  * unadvertised operation answers `A2002` whatever its arguments hold.
  */
-export declare function findOperationAvailabilityIssue(contract: Contract, request: OperationIdentity & {
+export declare function findOperationAvailabilityIssue(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
-}): ValidationIssue | undefined;
+}): AvValidationIssue | undefined;
 /**
  * Validates one standard operation's arguments against a Contract. Operation
  * availability and request limits are checked before the arguments' grammar.
  */
-export declare function validateOperationArguments(contract: Contract, request: OperationIdentity & {
+export declare function validateOperationArguments(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
     readonly arguments: unknown;
 }, options?: OperationValidationOptions): OperationValidationResult;

package/dist/operations/projection-scope.resolver.d.ts

@@ -1,7 +1,7 @@
-import type { ProjectionScope } from "../contracts/capability.js";
-import type { Contract } from "../contracts/contract.js";
-import type { Resource } from "../contracts/resource.js";
-import type { OperationIdentity } from "./operation-identity.js";
+import type { AvProjectionScope } from "../contracts/capability.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvResource } from "../contracts/resource.js";
+import type { AvOperationIdentity } from "./operation-identity.js";
 /**
  * Which projection position one request's **top-level** projection arguments sit
  * in, read off the variant the Resource advertises.
@@ -21,9 +21,9 @@ import type { OperationIdentity } from "./operation-identity.js";
  * answering `"record"` for one keeps this function a projection question rather
  * than a second, weaker copy of the availability gate.
  */
-export declare function resolveProjectionScope(resource: Resource<Contract> | undefined, request: OperationIdentity): ProjectionScope;
+export declare function resolveProjectionScope(resource: AvResource<AvContract> | undefined, request: AvOperationIdentity): AvProjectionScope;
 /**
  * The position a projection NESTED beneath an admitted relation sits in: the
  * unrestricted one, at every depth, under every top-level scope.
  */
-export declare const NESTED_PROJECTION_SCOPE: ProjectionScope;
+export declare const NESTED_PROJECTION_SCOPE: AvProjectionScope;

package/dist/operations/structural-limits.walker.d.ts

@@ -1,19 +1,19 @@
-import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "./operation-identity.js";
-import type { ValidationIssue } from "./validation-code.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "./operation-identity.js";
+import type { AvValidationIssue } from "./validation-code.js";
 type Readable = Readonly<Record<string, unknown>>;
 /** What one walk of an operation's arguments found. */
 export type StructuralLimitsFinding = {
     /** The nesting issue, which wins over any boolean-node issue. */
-    readonly nesting: ValidationIssue | undefined;
+    readonly nesting: AvValidationIssue | undefined;
     /** The boolean-node issue, when there is no nesting issue. */
-    readonly booleanNodes: ValidationIssue | undefined;
+    readonly booleanNodes: AvValidationIssue | undefined;
 };
 /**
  * Enforces the structural limits on one operation's argument object: the nesting
  * issue if there is one, otherwise the boolean-node issue if there is one.
  */
-export declare function findStructuralLimitIssues(contract: Contract, request: OperationIdentity & {
+export declare function findStructuralLimitIssues(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
 }, args: Readable): StructuralLimitsFinding;
 export {};