@aventara/core 0.1.0-pilot.2 → 0.1.0-pilot.4

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

@@ -4,7 +4,9 @@ import type { ProjectionScopes, ScalarField } from "../contracts/field.js";
 import type { ScalarAtom, ScalarForms, ScalarValueType } from "../contracts/scalar-value-type.js";
 import type { JsonValue } from "../runtime/json-value.js";
 import type { OperationIdentity } from "./operation-identity.js";
+/** The Resource names of Contract `C`. */
 export type ResourceKey<C extends Contract> = Extract<keyof C["resources"], string>;
+/** The field names of Resource `K` in Contract `C`. */
 export type FieldKey<C extends Contract, K extends ResourceKey<C>> = Extract<keyof C["resources"][K]["fields"], string>;
 type FieldAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>> = C["resources"][K]["fields"][F];
 type ScalarFieldAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>> = Extract<FieldAt<C, K, F>, {
@@ -22,49 +24,15 @@ type RelationFieldKeyOf<C extends Contract, K extends ResourceKey<C>> = {
 type CapabilitiesOf<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>> = FieldAt<C, K, F> extends {
     readonly capabilities: infer Capabilities;
 } ? Capabilities : never;
-/**
- * The argument scope a reader with no scope to thread reads a projection
- * capability at.
- *
- * `filter`, `order`, `orderNulls` and `pagination` were measured uniform across
- * every operation variant, so their readers have no scope to be given; and every
- * variant that carries a filter, an order, a cursor or a pagination argument
- * carries it in the unrestricted position — the bulk cells carry none of them.
- * Named rather than inlined so that a member which stops being uniform is found
- * by grepping one word instead of auditing `"record"` string literals.
- */
+/** The projection position read when no position applies: `"record"`. */
 type UnrestrictedProjection = "record";
-/**
- * The write mirror of {@link UnrestrictedProjection}, and the default for the
- * public write surfaces: a write argument reached through a relation is the
- * unrestricted position, because a scope qualifies the TOP LEVEL of an argument
- * only and does not narrow recursively (see {@link WriteScope}).
- */
+/** The write position read when no position applies, and the one nested writes use: `"nested"`. */
 type UnrestrictedWrite = "nested";
-/**
- * Whether a capability member's answer holds at one argument scope.
- *
- * The qualified arms state where they hold: a scope list on `select`/`include`,
- * a `scopes` member beside the tokens on `reducers`, `create` and `update`. The
- * unqualified arms state no scope and therefore hold in every one of them —
- * which is what keeps a Contract written before the axis existed meaning exactly
- * what it meant, and what lets an adapter that has not measured the axis say so
- * without losing a capability.
- *
- * Presence is deliberately NOT answered here: `false` and an absent member
- * arrive as unqualified values and would be reported as holding.
- * {@link HasCapability} owns the presence question and asks this one second.
- */
+/** Whether a capability member's answer holds at one argument scope. */
 type HoldsAtScope<Value, Scope extends ProjectionScope | WriteScope> = Value extends {
     readonly scopes: readonly (infer Stated)[];
 } ? Scope extends Stated ? true : false : Value extends ProjectionScopes ? Scope extends Value[number] ? true : false : true;
-/**
- * The tokens a capability member advertises, whichever arm it is written in — the
- * type-level mirror of `advertisedDirectives` and `advertisedReducers`, and
- * scope-blind for the same reason they are: reading the tokens and deciding where
- * they hold are two questions, and a reader handed both in one answer answers the
- * second by forgetting it. {@link CapabilityTokens} asks both.
- */
+/** The tokens a capability member advertises, in any argument position. */
 type AdvertisedTokens<Value> = Value extends {
     readonly scopes: readonly WriteScope[];
     readonly directives: readonly (infer Directive)[];
@@ -93,67 +61,38 @@ type KeysWithCapability<C extends Contract, K extends ResourceKey<C>, Keys exten
     [F in Keys]: HasCapability<C, K, F, Capability, Scope> extends true ? F : never;
 }[Keys];
 /**
- * The scalar-form map an argument surface reads its scalar VALUES through when
- * the caller names no side of a boundary: every built-in form `unknown`.
- *
- * It is `ScalarForms` itself — the constraint every map satisfies — so it tells a
- * reader nothing about a built-in value, which is the surface every caller had
- * before values were typed. An authoring mirror shared by both request origins (a
- * transaction plan, a hand-written request) cannot know whether its `Date`
- * travels as a `Date` or as an ISO string; a caller that does know passes
- * `ApplicationScalarForms` or `WireScalarForms` and is held to it.
- *
- * Enum members are not a form: they are the same strings on both sides, so an
- * enum-backed value is its member union under every map, this one included.
+ * The scalar-form map used when no side of a boundary is named: every built-in
+ * value is `unknown`. Pass `ApplicationScalarForms` or `WireScalarForms` to type
+ * values. Enum values are their member union under every map.
  */
 type UnstatedForms = ScalarForms;
-/**
- * Field `F`'s value under `Forms`: the one derivation a result reads
- * (`ScalarValueType`), read here for arguments, so an argument and a result
- * cannot disagree about what a field's value is.
- */
+/** Field `F`'s value under `Forms`, the same as in results. */
 type ScalarValueAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Forms extends ScalarForms> = ScalarFieldAt<C, K, F> extends infer Field extends ScalarField<C> ? ScalarValueType<C, Field, Forms> : never;
 /** One entry of field `F`'s value — the whole value when `F` is not a list. */
 type ScalarAtomAt<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Forms extends ScalarForms> = ScalarAtom<C, ScalarFieldAt<C, K, F>["type"], Forms>;
 /**
- * A JSON object: the value the runtime reads as an argument OBJECT rather than as
- * a value wherever a position admits both (`runtime/scalar-runtime.ts`
- * `isPlainRecord`), so those positions' value arms leave it out.
+ * A JSON object. Positions that accept both a value and an object of operators
+ * read a JSON object as the operators, so their value forms leave it out.
  */
 type JsonObject = Extract<JsonValue, {
     readonly [key: string]: JsonValue;
 }>;
 /**
- * The field-independent shape of one scalar filter: any value, or an object of
- * the operator vocabulary. `WhereInput` no longer reads it — it types each
- * field's operands through a scalar-form map (see `ScalarFilterFor`) — and it
- * stays exported as the vocabulary's own shape for a caller that holds no
- * Contract.
+ * The field-independent shape of one scalar filter: any value, or an object of the
+ * operator vocabulary.
  */
 export type ScalarFilterInput = unknown | Readonly<Partial<Record<ScalarFilterOperator, unknown>>>;
 /**
  * A scalar filter's shorthand equality value: the field's value, minus a JSON
  * object.
- *
- * Every reader of a filter position — the validation layer, the scalar runtime and
- * the adapter — reads it through one discriminant (`runtime/scalar-runtime.ts`
- * `isPlainRecord`): a plain record is an operator object, anything else is a
- * value. So a `Date`, a `Decimal` and a `Uint8Array` are shorthand for their
- * field, and a JSON object is an operator object by construction — `{ equals:
- * document }` carries it. The same exclusion as `not`'s value arm below.
  */
 type ScalarFilterShorthand<Value> = Exclude<Value, JsonObject>;
 /**
- * A scalar filter's operator object, each operand read the way
- * `normalizeScalarFilter` reads it: a comparison operand is the field's whole
- * value; `in`, `notIn`, `hasEvery` and `hasSome` a list of entries; `has` one
- * entry; a `json` field's `string*`/`array*` operand a {@link JsonValue}; `not` a
- * value or a nested operator object. `mode`, `isEmpty` and `path` reach the
- * adapter un-normalized, so core states nothing about them.
- *
- * Which operators a field advertises stays the validation layer's question
- * (`V1006`), exactly as before values were typed: this answers only what each
- * operand is.
+ * A scalar filter's operator object: a comparison operand is the field's whole
+ * value; `in`, `notIn`, `hasEvery` and `hasSome` take a list of entries; `has`
+ * one entry; a `json` field's `string*`/`array*` operand a {@link JsonValue};
+ * `not` a value or a nested operator object. `mode`, `isEmpty` and `path` are
+ * passed to the adapter as given.
  */
 type ScalarFilterOperators<Value, Atom, Json> = Readonly<{
     equals?: Value;
@@ -211,9 +150,13 @@ type IdentifierObject<C extends Contract, K extends ResourceKey<C>, I extends re
 } & {
     [F in Exclude<FieldKey<C, K>, I[number]>]?: never;
 }>;
+/** A `where` argument for a unique operation: the values of one identifier. */
 export type UniqueWhereInput<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms> = ActiveIdentifier<C, K> extends infer I ? I extends readonly string[] ? IdentifierObject<C, K, I, Forms> : never : never;
+/** `"asc"` or `"desc"`. */
 export type SortDirection = "asc" | "desc";
+/** Where `null`s sort: `"first"` or `"last"`. */
 export type NullsOrder = "first" | "last";
+/** How one scalar field sorts: a direction, or a direction and a `nulls` order. */
 export type ScalarOrderInput = SortDirection | Readonly<{
     sort: SortDirection;
     nulls: NullsOrder;
@@ -223,40 +166,15 @@ type OrderableRelationKey<C extends Contract, K extends ResourceKey<C>> = KeysWi
 type OrderableFieldKey<C extends Contract, K extends ResourceKey<C>> = OrderableScalarKey<C, K> | OrderableRelationKey<C, K>;
 type ScalarOrderForField<C extends Contract, K extends ResourceKey<C>, F extends OrderableScalarKey<C, K>> = ScalarFieldAt<C, K, F>["nullable"] extends true ? HasCapability<C, K, F, "orderNulls", UnrestrictedProjection> extends true ? ScalarOrderInput : SortDirection : SortDirection;
 /**
- * An `orderBy` reducer is not a PROJECTION position, so the projection scopes
- * beside the reducer list do not qualify it; and every variant that carries an
- * `orderBy` argument carries it in the unrestricted position, which is why this
- * reader does not thread a scope.
- *
- * A to-one value is **one** target entry, not an {@link OrderByInput}: the
- * runtime refuses a precedence list there (`validateOrderBy` requires a record
- * at a relation position, V1001), so admitting one would advertise what the
- * validation layer refuses.
+ * The `orderBy` value of a relation field: a to-many relation orders by
+ * `$count`; a to-one relation takes one entry of the related Resource's
+ * `orderBy`, not a list.
  */
 type RelationOrderForField<C extends Contract, K extends ResourceKey<C>, F extends OrderableRelationKey<C, K> & RelationFieldKeyOf<C, K>> = RelationCardinality<C, K, F> extends "many" ? HasCapabilityToken<C, K, F, "reducers", UnrestrictedProjection, "$count"> extends true ? Readonly<{
     $count: SortDirection;
 }> : never : OrderByEntry<C, RelationTarget<C, K, F>>;
 type OrderValue<C extends Contract, K extends ResourceKey<C>, F extends OrderableFieldKey<C, K>> = F extends OrderableScalarKey<C, K> ? ScalarOrderForField<C, K, F> : F extends OrderableRelationKey<C, K> & RelationFieldKeyOf<C, K> ? RelationOrderForField<C, K, F> : never;
-/**
- * One `orderBy` precedence entry: exactly one orderable field and its value.
- *
- * A to-one relation's value is the target's entry, so a self-relation
- * (`Author.mentor → Author`) or a one-to-one pair makes this type recursive. A
- * type argument is instantiated eagerly, so resolving `OrderByEntry<C, "Author">`
- * needed `OrderValue<…, "mentor">`, which IS `OrderByEntry<C, "Author">`: TS2615,
- * after which the entry degraded to `any` and refused nothing. A mapped property
- * is resolved only when read, by which time the entry it recurses into exists. The
- * projection walk never hit this because its recursion already sits behind an
- * object property (`{ select?: … }`).
- *
- * **No type-level depth cap, deliberately.** The runtime bound is the Contract's
- * `limits.maxNestingDepth` — each to-one hop counts one level, and one past it is
- * V1013 (`operation-nesting.ts` `walkOrderBy`). That limit is a `number` in the
- * Contract, resolved per scope at construction, so no literal exists for a type to
- * count against; a fixed cap would refuse what a Contract with a larger limit
- * accepts. `where` and `select` recurse uncapped for the same reason, and the
- * validation layer refuses past the limit for all three.
- */
+/** One `orderBy` precedence entry: exactly one orderable field and its value. */
 export type OrderByEntry<C extends Contract, K extends ResourceKey<C>> = {
     [F in OrderableFieldKey<C, K>]: {
         readonly [Only in F]: OrderValue<C, K, Only>;
@@ -264,15 +182,13 @@ export type OrderByEntry<C extends Contract, K extends ResourceKey<C>> = {
         readonly [Other in Exclude<OrderableFieldKey<C, K>, F>]?: never;
     };
 }[OrderableFieldKey<C, K>];
+/** An `orderBy` argument: one entry, or a list in order of precedence. */
 export type OrderByInput<C extends Contract, K extends ResourceKey<C>> = OrderByEntry<C, K> | readonly OrderByEntry<C, K>[];
+/** A `cursor` argument: scalar field values of the row the page starts from. */
 export type CursorInput<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms> = Readonly<{
     [F in ScalarFieldKeyOf<C, K>]?: ScalarValueAt<C, K, F, Forms>;
 }>;
-/**
- * Scalar `select` carries no scope qualifier — the six scalar members were
- * measured uniform — so the scope reaches this reader only to keep one projection
- * walk asking one question.
- */
+/** The scalar fields selectable at one projection position. */
 type SelectableScalarKey<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope> = KeysWithCapability<C, K, ScalarFieldKeyOf<C, K>, "select", Scope>;
 type SelectableRelationKey<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope> = KeysWithCapability<C, K, RelationFieldKeyOf<C, K>, "select", Scope>;
 type IncludeRelationKey<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope> = KeysWithCapability<C, K, RelationFieldKeyOf<C, K>, "include", Scope>;
@@ -307,28 +223,14 @@ type ProjectionChoice<C extends Contract, K extends ResourceKey<C>, Scope extend
     select?: never;
 }>;
 /**
- * The argument object one relation entry carries inside a projection.
- *
- * `Scope` is the scope of the projection this entry sits in. It qualifies the
- * entry's own reducer question and nothing deeper: the target's projection is
- * taken at {@link UnrestrictedProjection}, because a scope qualifies the top
- * level of a projection only and the measurement is explicit that the full
- * surface returns one level in (see {@link ProjectionScope}). A reader who
- * narrowed it recursively would refuse what the ORM accepts.
+ * The argument object one relation entry carries inside a projection. `Scope`
+ * applies to this entry only; the related rows' own projection is
+ * unrestricted.
  */
 export type RelationProjectionInput<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K> = RelationFieldKeyOf<C, K>, Scope extends ProjectionScope = UnrestrictedProjection, Forms extends ScalarForms = UnstatedForms> = F extends RelationFieldKeyOf<C, K> ? Readonly<NestedWhereArgument<C, K, F, Forms> & NestedOrderArgument<C, K, F> & NestedPaginationArgument<C, K, F, "limit", Forms> & NestedPaginationArgument<C, K, F, "offset", Forms> & NestedPaginationArgument<C, K, F, "cursor", Forms> & ProjectionChoice<C, RelationTarget<C, K, F>, UnrestrictedProjection, RelationAllowsCount<C, K, F, Scope>, Forms>> : never;
 /**
  * One relation entry of a projection: exactly relation `F` of `Keys`, with its
  * argument object, and every other key of `Keys` absent.
- *
- * A projection's entry union is formed whenever its `select`/`include` constraint
- * is — at every call, including one that passes no projection — and a type
- * argument is instantiated when the union is: every relation's {@link
- * RelationProjectionInput} (its nested `where`, `orderBy`, pagination and
- * projection choice) for every relation the Resource has. A mapped property is
- * resolved only when an entry names it, so a call pays for the relations it
- * projects. Measured on the six-resource artifact shape: ≈4,500–6,700
- * instantiations per call whose projection names no relation.
  */
 type RelationProjectionEntry<C extends Contract, K extends ResourceKey<C>, Keys extends RelationFieldKeyOf<C, K>, F extends Keys, Scope extends ProjectionScope, Forms extends ScalarForms> = {
     readonly [Only in F]: RelationProjectionInput<C, K, Only & RelationFieldKeyOf<C, K>, Scope, Forms>;
@@ -342,28 +244,23 @@ type IncludeRelationProjectionEntry<C extends Contract, K extends ResourceKey<C>
     [F in IncludeRelationKey<C, K, Scope>]: RelationProjectionEntry<C, K, IncludeRelationKey<C, K, Scope>, F, Scope, Forms>;
 }[IncludeRelationKey<C, K, Scope>];
 /**
- * One entry of a `select` argument, at one projection scope.
- *
- * The scope precedes `AllowCount` because it qualifies which fields exist at
- * this position at all, while `AllowCount` only says whether the carrying entry
- * admits its parent's reducer. The default is the unrestricted position, so a
- * reader that states no scope keeps today's surface exactly.
+ * One entry of a `select` argument, at one projection position. The default is
+ * the unrestricted position.
  */
 export type ProjectionEntry<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = SelectableScalarKey<C, K, Scope> | SelectableRelationKey<C, K, Scope> | SelectRelationProjectionEntry<C, K, Scope, Forms> | (AllowCount extends true ? "$count" : never);
+/** A `select` argument: the fields to return. */
 export type SelectInput<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = readonly ProjectionEntry<C, K, Scope, AllowCount, Forms>[];
+/** An `include` argument: the relations to return with each row. */
 export type IncludeInput<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope = UnrestrictedProjection, Forms extends ScalarForms = UnstatedForms> = readonly (IncludeRelationKey<C, K, Scope> | IncludeRelationProjectionEntry<C, K, Scope, Forms>)[];
+/** A scalar update directive and its operand, such as `{ $increment: 1 }`. */
 export type ScalarMutationAction = Readonly<Partial<Record<ScalarMutationDirective, unknown>>>;
+/** A relation write: one or more relation directives and their payloads. */
 export type RelationMutationAction = Readonly<Partial<Record<RelationMutationDirective, unknown>>>;
-/**
- * Scalar write members carry no scope qualifier — all six scalar members were
- * measured uniform — so the scope reaches this reader only to keep one mutation
- * walk asking one question.
- */
+/** The scalar fields writable at one stage and write position. */
 type WritableScalarKey<C extends Contract, K extends ResourceKey<C>, Stage extends "create" | "update", Scope extends WriteScope> = KeysWithCapability<C, K, ScalarFieldKeyOf<C, K>, Stage, Scope>;
 /**
- * The relations writable at one stage **in one write position**. The default is
- * the unrestricted position, which is what every nested write argument is and
- * what a caller that states no scope means.
+ * The relations writable at one stage in one write position. The default is
+ * the unrestricted position.
  */
 export type WritableRelationKey<C extends Contract, K extends ResourceKey<C>, Stage extends "create" | "update", Scope extends WriteScope = UnrestrictedWrite> = KeysWithCapability<C, K, RelationFieldKeyOf<C, K>, Stage, Scope>;
 type ManyOrOne<C extends Contract, K extends ResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Value> = RelationCardinality<C, K, F> extends "many" ? Value | readonly Value[] : Value;
@@ -399,16 +296,6 @@ type RelationDirectiveValue<C extends Contract, K extends ResourceKey<C>, F exte
 declare const NO_ADVERTISED_MEMBER: unique symbol;
 /**
  * A write member that advertises nothing: it accepts `{}` and refuses every key.
- *
- * TypeScript runs no excess-property check against an object type with no known
- * properties, so an empty mapped member would type as `{}` and accept any key
- * silently, leaving it to `V1006` at runtime. One optional member on a
- * module-private symbol keeps the type weak — `{}` still assigns — while giving
- * the excess-property check something to measure against, so the diagnostic names
- * the offending key.
- *
- * The empty case is reachable by design: `directives: []` means "writable, with no
- * directive", distinct from an absent member (see `contracts/field.ts`).
  */
 type NoAdvertisedMember = {
     readonly [NO_ADVERTISED_MEMBER]?: never;
@@ -419,16 +306,14 @@ type RelationMutationActionFor<C extends Contract, K extends ResourceKey<C>, F e
     [Directive in Extract<CapabilityTokens<C, K, F, Stage, Scope>, RelationMutationDirective>]: RelationDirectiveValue<C, K, F, Directive, Forms>;
 }>>>;
 /**
- * One scalar mutation directive's operand, as `normalizeScalarMutation` reads
- * it: one entry of the field (`$push` on a list also takes a list of them), and
- * `$unset`'s operand reaches the adapter un-normalized, so core states nothing
- * about it.
+ * One scalar mutation directive's operand: one entry of the field (`$push` on a
+ * list also takes a list of them). `$unset`'s operand is passed to the adapter as
+ * given.
  */
 type ScalarDirectiveOperand<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Directive extends ScalarMutationDirective, Forms extends ScalarForms> = Directive extends "$unset" ? unknown : Directive extends "$push" ? [ScalarFieldAt<C, K, F>["list"]] extends [false] ? ScalarAtomAt<C, K, F, Forms> : ScalarAtomAt<C, K, F, Forms> | readonly ScalarAtomAt<C, K, F, Forms>[] : ScalarAtomAt<C, K, F, Forms>;
 /**
  * The directive object a scalar field accepts at one stage, or `never` when it
- * advertises no directive — never an empty object type, which every non-nullish
- * value would satisfy and so would let any value through beside the typed one.
+ * advertises no directive.
  */
 type ScalarMutationActionFor<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>, Stage extends "create" | "update", Scope extends WriteScope, Forms extends ScalarForms> = [
     Extract<CapabilityTokens<C, K, F, Stage, Scope>, ScalarMutationDirective>
@@ -446,48 +331,17 @@ type RelationMutationFields<C extends Contract, K extends ResourceKey<C>, Stage
     [F in WritableRelationKey<C, K, Stage, Scope>]?: RelationMutationActionFor<C, K, F & RelationFieldKeyOf<C, K>, Stage, Scope, Forms>;
 }>;
 /**
- * A `create` data argument, at one write position.
- *
- * The default is the unrestricted position: every nested occurrence of this type
- * — a `$create` payload, a `$connectOrCreate`'s `create`, an upsert branch — is a
- * write reached through a relation, and a scope qualifies the top level of a
- * write argument only (see {@link WriteScope}).
+ * A `create` data argument, at one write position. A write position applies
+ * to the top level only; nested writes use the unrestricted position (see
+ * {@link WriteScope}).
  */
 export type CreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "create", Scope, Forms> & RelationMutationFields<C, K, "create", Scope, Forms>>>;
 /** An `update` data argument, at one write position. See {@link CreateDataInput}. */
 export type UpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "update", Scope, Forms> & RelationMutationFields<C, K, "update", Scope, Forms>>>;
 type QueryProjectionArgs<C extends Contract, K extends ResourceKey<C>, Scope extends ProjectionScope, Forms extends ScalarForms> = ProjectionChoice<C, K, Scope, false, Forms>;
 /**
- * Every standard operation's argument object, with each argument position bound to
- * the argument SCOPE it is.
- *
- * The map is already keyed by `family.variant`, so binding the scope here is what
- * makes an over-advertised projection or nested write **unrepresentable** at the
- * authoring boundary rather than merely refused at runtime: twelve projection
- * cells and eight data cells, and `create.many`/`update.many` no longer share
- * their projection with `find.many` nor their data with `create.one`.
- *
- * **Two bulk-returning projections** — `create.many` and `update.many` are the
- * row-returning bulk writes, so their projection sits in `"bulkWrite"`. Every
- * other projection-carrying variant reads or writes one addressed record and sits
- * in `"record"`, including a multi-row READ: the axis is the write being bulk, not
- * the row count. `delete.many` is the one cell where that is a judgement rather
- * than a measurement — it is a bulk write that core's grammar gives a projection,
- * and no pilot engine answers it at all, so it keeps the surface it has today
- * instead of being narrowed on a supposition.
- *
- * **Four flat bulk writes** — `create.many`, `create.count`, `update.many` and
- * `update.count` carry a data argument of own columns and own reference fields;
- * the rest admit nested writes. `upsert.unique`'s two branches are both nested.
- *
- * **This binding is core's grammar, not the adapter's routing.** A variant's real
- * scope is an adapter fact and the adapter states it on the advertised variant
- * (`OperationVariantScopes`); a host that routed, say, `update.first` through a
- * bulk-returning call would make this map's `"record"` too generous.
- *
- * An unqualified capability holds in every scope, so a Contract whose adapter has
- * not measured the axis is bound to the same surface it had before the axis
- * existed.
+ * Every standard operation's argument object, with each argument at its
+ * projection or write position.
  */
 export type OperationArgumentMap<C extends Contract, K extends ResourceKey<C>, Forms extends ScalarForms = UnstatedForms> = {
     find: {
@@ -562,16 +416,7 @@ export type OperationArgumentMap<C extends Contract, K extends ResourceKey<C>, F
         };
     };
 };
-/**
- * One standard operation's argument object.
- *
- * `Forms` is the scalar-form map its scalar VALUES are read through — data,
- * filters, unique selectors and cursors, at every depth. Unstated, every built-in
- * value is `unknown` ({@link UnstatedForms}); the application façade passes
- * `ApplicationScalarForms`, so a `Date` handed to a `json` field or a number to a
- * `string` one is refused where it is written rather than by `V1001` at runtime.
- * The validation layer stays the guard either way.
- */
+/** One standard operation's argument object. */
 export type OperationArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms = UnstatedForms> = I extends {
     family: infer F;
     variant: infer V;

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,5 @@ 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;

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