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

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

@@ -13,12 +13,7 @@ type SelectOf<Args> = Args extends {
 type IncludeOf<Args> = Args extends {
     readonly include?: infer Include;
 } ? Exclude<Include, undefined> : never;
-/**
- * The projection argument, held apart so the caller's literal is inferred and
- * nothing else is: only `select`/`include` drive the result, and every other
- * argument stays a plain declared type, which keeps its contextual typing and its
- * excess-property check.
- */
+/** The projection argument (`select`/`include`) of a call, which decides its result type. */
 type ProjectionArgument<Select, Include> = {
     readonly select?: Select;
     readonly include?: never;
@@ -37,10 +32,8 @@ type ArgumentList<Rest, Parameter> = Record<never, never> extends Rest ? [args?:
 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"];
 /**
- * The operation grammar `C` advertises: one property per Resource, one per
- * advertised family under it, one identity per advertised variant under that.
- * The one source every surface maps its calls over, so which operations exist is
- * decided once.
+ * 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>]: {
@@ -53,9 +46,9 @@ export type OperationGrammar<C extends Contract> = {
     };
 };
 /**
- * An operation's slot: its result, except that a first-style miss contributes
- * `null` — where the miss is not the `A1001` arm of a response of its own: a
- * committed plan's slot, and a remote call that resolves to the data.
+ * An operation's slot: its result, except that a first-style miss is `null`.
+ * 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;
 /**
@@ -72,13 +65,18 @@ type PlainCall<C extends Contract, R extends ResourceKey<C>, I extends Operation
  * 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>;
+/**
+ * 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>>>;
 /**
  * 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.
+ * present exactly where the result is one row. A handle is not a request and takes no
+ * options.
  */
 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 {};

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

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

package/dist/operations/operation-identity.js

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

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

@@ -5,11 +5,8 @@ import type { FieldKey, OperationArgumentsFor, ResourceKey } from "./operation-a
 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];
 /**
- * The default projection's keys: the scalars whose `select` is exactly `true`.
- *
- * Strict, as the runtime is: an absent member, `false`, and a member the Contract
- * widened to `boolean` are all left out, so a write-only field never appears and a
- * widened Contract under-promises rather than over-promises.
+ * 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 {
@@ -19,16 +16,11 @@ type DefaultKey<C extends Contract, K extends ResourceKey<C>> = {
         };
     } ? F : never;
 }[FieldKey<C, K>];
-/**
- * The field one projection entry names: a bare key, or a relation entry's key.
- * `$count` passes through and is dropped where every caller intersects the result
- * with the Resource's field keys, which is the one place that knows what a field is.
- */
+/** 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;
 /**
  * The argument object a relation entry carries for field `F`, or `never` when
- * the relation is only named. The `object` guard keeps a bare string entry from
- * matching its own apparent members (`"length"` would otherwise).
+ * the relation is only named.
  */
 type EntryArguments<Entry, F extends string> = Entry extends object ? Entry extends {
     readonly [Key in F]: infer Arguments;
@@ -43,12 +35,8 @@ type ProjectedFields<C extends Contract, K extends ResourceKey<C>, Keys extends
     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;
 };
 /**
- * One projection level: `select` is exactly its entries, `include` the defaults
- * plus the named relations, and anything else the defaults.
- *
- * An absent argument (`never`, from {@link EntryArguments}) is tested first and
- * explicitly: it would otherwise distribute to `never`, and inside a one-tuple it
- * would match the `select` arm, because `never` extends everything.
+ * 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 [{
     readonly select: readonly (infer Entry)[];
@@ -56,10 +44,8 @@ type ProjectedRecord<C extends Contract, K extends ResourceKey<C>, Arguments, Fo
     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>;
 /**
- * A to-many entry whose `select` asks for `$count`: the parent's reducer over the
- * relation, so the value is the envelope rather than the row array. `$count` and
- * the row fields are separated here because they are separate facts — the rows
- * are the target's projection, the count is the parent's reducer.
+ * 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] ? {
     readonly count: number;
@@ -67,56 +53,24 @@ type CountEnvelope<C extends Contract, Target extends ResourceKey<C>, Entry, For
     readonly data: readonly ProjectedFields<C, Target, Extract<EntryKey<Entry>, FieldKey<C, Target>>, Exclude<Entry, "$count">, Forms>[];
     readonly count: number;
 };
-/**
- * The entries of an argument's own `select`, or `never` when it has none.
- * Distributive on purpose: an absent argument (`never`) has no entries.
- */
+/** The entries of an argument's own `select`, or `never` when it has none. */
 type SelectEntry<Arguments> = Arguments extends {
     readonly select: readonly (infer Entry)[];
 } ? Entry : never;
 /**
- * The value of one relation entry.
- *
- * The nested projection is the target's own, at every depth: a scope qualifies
- * the top level of a projection only (`contracts/capability.ts`
- * `ProjectionScope`), and the argument constraint on {@link OperationResultFor}
- * has already admitted the entry at the position it sits in.
- *
- * A to-many entry is the envelope exactly when its own `select` carries `$count`;
- * otherwise — no argument, `include`, or a `select` without the reducer — it is
- * the row array.
+ * 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);
 /**
  * The value a standard operation returns in `OperationResponse.data` on success,
- * derived from the Contract, the Resource, the operation identity and the
- * projection argument.
- *
- * - `count` → `number`;
- * - `many` → `readonly Record[]`;
- * - `first`, `unique`, `one` → the record. **Not `| null`:** absence is an
- *   outcome, not a value — `A1001` answers `data: null` for a first-style miss and
- *   `A2003` refuses a strict unique one (`runtime/outcome-mapper.ts`
- *   `OUTCOME_TABLE`) — so folding `null` into the record would count it twice.
- *
- * `Args` is constrained to the operation's own argument type, so a projection
- * entry the Contract does not advertise at that position — a write-only field, an
- * unadvertised `$count`, a relation outside a bulk write's ceiling — is refused
- * here instead of typed as present.
- *
- * `Forms` is the scalar-form map. It defaults to the application forms, which are
- * what a framework-produced value is in either scope; a transport or a generated
- * client passes the wire forms and gets the same derivation.
+ * 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>;
 /**
- * {@link OperationResultFor}'s rule, for a caller that has already admitted the
- * projection argument against the operation's own argument type — the
- * application façade, which constrains its inferred `select`/`include` at the
- * call. It reads only the projection, so a caller holding just that need not
- * compute the whole argument object a second time to satisfy the constraint.
- *
- * Not exported from the package: one public spelling of the result rule.
+ * {@link OperationResultFor}, 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 {};

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

@@ -1,6 +1,7 @@
 import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "./operation-identity.js";
+import { type OperationIdentity } from "./operation-identity.js";
 import type { ValidationIssue } from "./validation-code.js";
+/** An operation's arguments as an object, before validation. */
 export type SemanticOperationArguments = Readonly<Record<string, unknown>>;
 type OperationValidationSuccess = {
     readonly ok: true;
@@ -10,15 +11,15 @@ type OperationValidationFailure = {
     readonly ok: false;
     readonly issues: readonly ValidationIssue[];
 };
+/** The answer of {@link validateOperationArguments}: success, or the issues found. */
 export type OperationValidationResult = OperationValidationSuccess | OperationValidationFailure;
 export type OperationValidationOptions = {
     readonly transactionReferences?: boolean;
 };
 /**
- * The Framework Validation Layer's issue for a request naming a Resource the
- * active Contract does not have (`V1005` at `["resource"]`, rolling up to
- * `A2001`). The one spelling — the protocol's absence answers build theirs with
- * it.
+ * The Framework Validation Layer's issue for a request naming a Resource the active
+ * 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 & {

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

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

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

@@ -1,24 +1,37 @@
 import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "./operation-identity.js";
+import { type OperationIdentity } from "./operation-identity.js";
 import { type OperationValidationOptions, type OperationValidationResult } from "./operation-validator-core.js";
 import type { ValidationIssue } 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: {
+    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: Contract, request: {
     readonly resource: string;
     readonly family: string;
     readonly variant: string;
 }): ValidationIssue;
 /**
- * Validates one standard operation's semantic arguments against the active
- * Contract. Operation availability and request-wide structural limits are
- * enforced before deeper grammar validation.
+ * 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 & {
+    readonly resource: string;
+}): ValidationIssue | 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 & {
     readonly resource: string;

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

@@ -7,7 +7,7 @@ import type { OperationIdentity } from "./operation-identity.js";
  * 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
@@ -25,15 +25,5 @@ export declare function resolveProjectionScope(resource: Resource<Contract> | un
 /**
  * The position a projection NESTED beneath an admitted relation sits in: the
  * unrestricted one, at every depth, under every top-level scope.
- *
- * **Measured at runtime on both pilot engines, 2026-10-03** — not inferred from
- * the types, which permit more than they accept. A bulk-returning write accepted
- * `include: { <owned to-one>: { include: { <to-many>: true } } }` and populated
- * the rows, while the same to-many asked for at the top level was refused
- * outright. The generated types say why: a bulk projection types an admitted
- * relation as the *unrestricted* projection argument, so the full surface returns
- * one level in.
- *
- * Naming it is the point.
  */
 export declare const NESTED_PROJECTION_SCOPE: ProjectionScope;

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

@@ -0,0 +1,19 @@
+import type { Contract } from "../contracts/contract.js";
+import type { OperationIdentity } from "./operation-identity.js";
+import type { ValidationIssue } 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;
+    /** The boolean-node issue, when there is no nesting issue. */
+    readonly booleanNodes: ValidationIssue | 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 & {
+    readonly resource: string;
+}, args: Readable): StructuralLimitsFinding;
+export {};