@aventara/core 0.1.0-pilot.4 → 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,16 +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-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-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

@@ -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) {
@@ -152,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.`);
@@ -168,6 +172,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}".`);
@@ -182,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);
         }
     }
 }
@@ -268,7 +287,10 @@ 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.`);
         }
         else {
             validateRelationFilter(contract, key, field, value, fieldPath, state, depth);
@@ -570,7 +592,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 +641,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 +653,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 +672,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 +695,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 +711,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 +735,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 +756,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 +780,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 +858,7 @@ export function validateOperationArguments(contract, request, options) {
             const state = {
                 issues,
                 structuralRoot: ["arguments", "where"],
+                transactionReferences: options?.transactionReferences === true,
                 booleanFilterNodes: 0,
                 nestingExceeded: false,
                 booleanNodesExceeded: false,

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

@@ -1,24 +1,39 @@
-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: AvContract, request: {
+    readonly resource: string;
+    readonly family: string;
+}): "family" | "variant";
 /**
  * The Framework Validation Layer's issue for a `(resource, family, variant)` the
- * active Contract does not advertise on a Resource it has (`V1006` at `["operation"]`,
- * rolling up to `A2002`). The one spelling — the protocol's absence answers build
- * theirs with it, so a caller cannot tell which layer answered.
+ * active Contract does not advertise on a Resource it has: `V1006`, rolling up to
+ * `A2002`, at the key that is wrong (`["family"]` or `["variant"]`, see
+ * {@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(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: AvContract, request: AvOperationIdentity & {
+    readonly resource: string;
+}): 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/operation-validator.js

@@ -1,8 +1,8 @@
 import { lookupOwn, lookupResource } from "../contracts/contract-lookup.js";
 import { isOperationVariantAvailable, } from "../contracts/resource-operations.js";
-import { findOperationBooleanNodeIssue } from "./operation-boolean-nodes.js";
-import { findOperationNestingIssue } from "./operation-nesting.js";
+import { isOperationFamily, } from "./operation-identity.js";
 import { validateOperationArguments as validateSemanticOperationArguments, } from "./operation-validator-core.js";
+import { findStructuralLimitIssues } from "./structural-limits.walker.js";
 function isArgumentObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -15,13 +15,28 @@ function isOperationAvailable(contract, request) {
     const family = lookupOwn(advertised, request.family);
     return isOperationVariantAvailable(lookupOwn(family, request.variant));
 }
-export function operationUnavailableIssue(request) {
+export function unavailableOperationKey(contract, request) {
+    if (!isOperationFamily(request.family)) {
+        return "family";
+    }
+    const variants = lookupOwn(lookupResource(contract, request.resource)?.operations, request.family);
+    return variants !== undefined &&
+        Object.keys(variants).some((variant) => isOperationVariantAvailable(lookupOwn(variants, variant)))
+        ? "variant"
+        : "family";
+}
+export function operationUnavailableIssue(contract, request) {
     return {
-        path: ["operation"],
+        path: [unavailableOperationKey(contract, request)],
         code: "V1006",
         message: `Operation "${request.family}.${request.variant}" is not available on Resource "${request.resource}".`,
     };
 }
+export function findOperationAvailabilityIssue(contract, request) {
+    return isOperationAvailable(contract, request)
+        ? undefined
+        : operationUnavailableIssue(contract, request);
+}
 function hasGeneralRootWhere(request) {
     if (!("where" in request.arguments)) {
         return false;
@@ -33,15 +48,16 @@ function hasGeneralRootWhere(request) {
             request.family === "upsert"));
 }
 export function validateOperationArguments(contract, request, options) {
-    if (!isOperationAvailable(contract, request)) {
-        return { ok: false, issues: [operationUnavailableIssue(request)] };
+    const unavailable = findOperationAvailabilityIssue(contract, request);
+    if (unavailable !== undefined) {
+        return { ok: false, issues: [unavailable] };
     }
     if (isArgumentObject(request.arguments)) {
-        const nestingIssue = findOperationNestingIssue(contract, request.resource, request.arguments);
-        if (nestingIssue !== undefined) {
-            return { ok: false, issues: [nestingIssue] };
+        const finding = findStructuralLimitIssues(contract, request, request.arguments);
+        if (finding.nesting !== undefined) {
+            return { ok: false, issues: [finding.nesting] };
         }
-        const booleanNodeIssue = findOperationBooleanNodeIssue(contract, request, request.arguments);
+        const booleanNodeIssue = finding.booleanNodes;
         if (booleanNodeIssue !== undefined) {
             return {
                 ok: false,

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

@@ -1,13 +1,13 @@
-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.
  *
  * Two readers need the answer and they run one after the other over the same
- * request — the `maxBooleanNodes` walk in `operation-boolean-nodes.ts`, then the
+ * request — the `maxBooleanNodes` tally in `structural-limits.walker.ts`, then the
  * grammar walk in `operation-validator-core.ts`. They must agree: a walk that
  * resolved a wider scope than the validator would count nodes inside a projection
  * the validator then refuses (harmless), and a walk that resolved a narrower one
@@ -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

@@ -0,0 +1,19 @@
+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: AvValidationIssue | undefined;
+    /** The boolean-node issue, when there is no nesting issue. */
+    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: AvContract, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: Readable): StructuralLimitsFinding;
+export {};