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

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

@@ -153,12 +153,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.`);
@@ -190,6 +193,14 @@ function validateScalarFilter(fieldName, field, 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 === "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);
         }
     }
 }
@@ -276,7 +287,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.`);

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 {};

package/dist/operations/structural-limits.walker.js

@@ -28,6 +28,109 @@ function nestingExceeded(state) {
         message: `Request nesting exceeds maxNestingDepth (${state.nestingLimit}).`,
     };
 }
+function jsonDepthExceeded(state, fieldPath) {
+    state.nestingAtField = true;
+    state.nesting = {
+        path: state.tracking ? fieldPath : ["arguments", state.rootKey],
+        code: "V1021",
+        message: `Json value depth exceeds maxJsonDepth (${state.jsonDepthLimit}).`,
+    };
+}
+function isJsonField(field) {
+    return "scalar" in field.type && field.type.scalar === "json";
+}
+function jsonValueExceeds(state, value) {
+    const deepest = new Map();
+    const ancestors = new Set();
+    const stack = [{ leave: false, value, level: 0 }];
+    while (stack.length > 0) {
+        const task = stack.pop();
+        if (task.leave) {
+            ancestors.delete(task.container);
+            continue;
+        }
+        const current = task.value;
+        if (typeof current !== "object" ||
+            current === null ||
+            ancestors.has(current)) {
+            continue;
+        }
+        const inner = task.level + 1;
+        if (inner > state.jsonDepthLimit) {
+            return true;
+        }
+        const seen = deepest.get(current);
+        if (seen !== undefined && seen >= inner) {
+            continue;
+        }
+        deepest.set(current, inner);
+        ancestors.add(current);
+        stack.push({ leave: true, container: current });
+        const entries = Array.isArray(current)
+            ? current
+            : Object.values(current);
+        for (const entry of entries) {
+            stack.push({ leave: false, value: entry, level: inner });
+        }
+    }
+    return false;
+}
+function walkJsonWrite(state, field, value, path) {
+    const operands = isRecord(value) && Object.keys(value).some((key) => key.startsWith("$"))
+        ? Object.entries(value)
+            .filter(([key]) => key !== "$unset" && key !== "$ref")
+            .map(([, operand]) => operand)
+        : [value];
+    for (const operand of operands) {
+        const values = field.list && Array.isArray(operand) ? operand : [operand];
+        for (const entry of values) {
+            if (jsonValueExceeds(state, entry)) {
+                jsonDepthExceeded(state, path);
+                return;
+            }
+        }
+    }
+}
+const JSON_LIST_OPERATORS = new Set(["in", "notIn", "hasEvery", "hasSome"]);
+const JSON_VALUELESS_OPERATORS = new Set(["mode", "isEmpty", "path"]);
+function walkJsonFilter(state, filter, depth, path) {
+    let level = depth;
+    let current = filter;
+    while (isRecord(current)) {
+        let next;
+        for (const operator of Object.keys(current)) {
+            const operand = current[operator];
+            if (operator === "not" && isRecord(operand)) {
+                next = operand;
+                continue;
+            }
+            if (JSON_VALUELESS_OPERATORS.has(operator)) {
+                continue;
+            }
+            const values = JSON_LIST_OPERATORS.has(operator) && Array.isArray(operand)
+                ? operand
+                : [operand];
+            for (const entry of values) {
+                if (jsonValueExceeds(state, entry)) {
+                    jsonDepthExceeded(state, path);
+                    return;
+                }
+            }
+        }
+        if (next === undefined) {
+            return;
+        }
+        level += 1;
+        if (level > state.nestingLimit) {
+            nestingExceeded(state);
+            return;
+        }
+        current = next;
+    }
+    if (jsonValueExceeds(state, current)) {
+        jsonDepthExceeded(state, path);
+    }
+}
 function countBooleanNode(state, path, key) {
     if (state.booleanExceeded) {
         return;
@@ -74,7 +177,18 @@ function walkWhere(state, resourceName, value, depth, path, counting) {
         }
         else {
             const field = lookupField(resource, key);
+            if (field?.kind === "scalar") {
+                if (isJsonField(field)) {
+                    walkJsonFilter(state, child, depth, extend(state, path, key));
+                }
+                else {
+                    walkScalarNot(state, child, depth);
+                }
+            }
             if (field?.kind !== "relation") {
+                if (state.nesting !== undefined) {
+                    return;
+                }
                 continue;
             }
             if (field.cardinality === "one") {
@@ -97,6 +211,22 @@ function walkWhere(state, resourceName, value, depth, path, counting) {
         }
     }
 }
+function walkScalarNot(state, filter, depth) {
+    let level = depth;
+    let current = filter;
+    while (isRecord(current) && Object.hasOwn(current, "not")) {
+        const operand = current.not;
+        if (!isRecord(operand)) {
+            return;
+        }
+        level += 1;
+        if (level > state.nestingLimit) {
+            nestingExceeded(state);
+            return;
+        }
+        current = operand;
+    }
+}
 function walkOrderBy(state, resourceName, value, depth) {
     const resource = lookupResource(state.contract, resourceName);
     if (resource === undefined) {
@@ -194,6 +324,13 @@ function walkMutationData(state, resourceName, value, depth, path, stage, counti
     for (const fieldName of Object.keys(value)) {
         const edge = lookupField(resource, fieldName);
         const directives = value[fieldName];
+        if (edge?.kind === "scalar" && isJsonField(edge)) {
+            walkJsonWrite(state, edge, directives, extend(state, path, fieldName));
+            if (state.nesting !== undefined) {
+                return;
+            }
+            continue;
+        }
         if (edge?.kind !== "relation" || !isRecord(directives)) {
             continue;
         }
@@ -321,11 +458,13 @@ function walk(contract, request, args, tracking) {
     const state = {
         contract,
         nestingLimit: contract.limits.maxNestingDepth,
+        jsonDepthLimit: contract.limits.maxJsonDepth,
         booleanLimit: contract.limits.maxBooleanNodes,
         tracking,
         rootKey: "",
         booleanCount: 0,
         nesting: undefined,
+        nestingAtField: false,
         booleanNodes: undefined,
         booleanExceeded: false,
     };
@@ -334,6 +473,12 @@ function walk(contract, request, args, tracking) {
 }
 export function findStructuralLimitIssues(contract, request, args) {
     const untracked = walk(contract, request, args, false);
+    if (untracked.nestingAtField) {
+        return {
+            nesting: walk(contract, request, args, true).nesting,
+            booleanNodes: undefined,
+        };
+    }
     if (untracked.nesting !== undefined || !untracked.booleanExceeded) {
         return { nesting: untracked.nesting, booleanNodes: undefined };
     }

package/dist/operations/validation-code.d.ts

@@ -1,14 +1,19 @@
+import type { AvFieldCheck } from "../contracts/field-check.js";
 /** The set of allocated Validation codes, as a runtime array. */
-export declare const VALIDATION_CODES: readonly ["V1000", "V1001", "V1002", "V1003", "V1004", "V1005", "V1006", "V1007", "V1008", "V1009", "V1010", "V1011", "V1012", "V1013", "V1014", "V1015", "V1016", "V1017", "V1018", "V1019"];
+export declare const VALIDATION_CODES: readonly ["V1000", "V1001", "V1002", "V1003", "V1004", "V1005", "V1006", "V1007", "V1008", "V1009", "V1010", "V1011", "V1012", "V1013", "V1014", "V1015", "V1016", "V1017", "V1018", "V1019", "V1020", "V1021"];
 /** A validation code (`V1000` and up), one per kind of argument problem. */
-export type ValidationCode = (typeof VALIDATION_CODES)[number];
+export type AvValidationCode = (typeof VALIDATION_CODES)[number];
 /** The framework's message for each validation code. */
-export declare const VALIDATION_CODE_MESSAGES: Readonly<Record<ValidationCode, string>>;
+export declare const VALIDATION_CODE_MESSAGES: Readonly<Record<AvValidationCode, string>>;
 /** One validation problem: its code, message and the argument path it is at. */
-export type ValidationIssue = {
+export type AvValidationIssue = {
     readonly path?: readonly (string | number)[];
-    readonly code: ValidationCode;
+    readonly code: AvValidationCode;
     readonly message: string;
+    /** The failed field validator's check name (`max_length`, `string_format`, …). */
+    readonly check?: AvFieldCheck["check"];
+    /** That check's parameters, as the Contract stores them (`{ maximum: 80 }`). */
+    readonly params?: Readonly<Record<string, unknown>>;
 };
 /** Builds one validation issue at its path. */
-export declare function validationIssue(code: ValidationCode, path: readonly (string | number)[], message: string): ValidationIssue;
+export declare function validationIssue(code: AvValidationCode, path: readonly (string | number)[], message: string): AvValidationIssue;

package/dist/operations/validation-code.js

@@ -19,6 +19,8 @@ export const VALIDATION_CODES = [
     "V1017",
     "V1018",
     "V1019",
+    "V1020",
+    "V1021",
 ];
 export const VALIDATION_CODE_MESSAGES = {
     V1000: "Required value missing.",
@@ -41,6 +43,8 @@ export const VALIDATION_CODE_MESSAGES = {
     V1017: "Transaction fingerprint mismatch.",
     V1018: "Transaction reference resolved to no value.",
     V1019: "Transaction step depends on a row removed by an earlier step's cascade",
+    V1020: "Transaction mixes application and client steps.",
+    V1021: "Json value depth limit exceeded.",
 };
 export function validationIssue(code, path, message) {
     return { code, path, message };