@aventara/core 0.1.0-pilot.1 → 0.1.0-pilot.3

package/dist/framework/framework.d.ts

@@ -11,19 +11,19 @@ export type Framework<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkC
     readonly entrypoint: string;
     readonly contracts: FrameworkContracts;
     /**
-     * The typed in-process façade: `framework.application.<resource>.<family>.<variant>(args)`.
+     * The typed in-process façade:
+     * `framework.application.<resource>.<family>.<variant>(args)`.
      *
-     * Arguments and results are derived from the Application Contract's view of
-     * `M` and `Cfg` (`ApplicationContractView`), so this is the member that reads
-     * the pair: two configurations that differ in one `fields` entry give two
-     * different `Framework` types. Each call is an application-scope request to
-     * {@link execute} — the same totality guard and validation layer — which still
-     * refuses what a restriction removed, since restrictions stay invisible to the
-     * types (ADR 0009).
+     * Arguments and results are derived from the Application Contract's view of `M`
+     * and `Cfg` (`ApplicationContractView`), so this is the member that reads the
+     * pair: two configurations that differ in one `fields` entry give two different
+     * `Framework` types. Each call is an application-scope request to {@link execute}
+     * — the same totality guard and validation layer — which still refuses what a
+     * restriction removed, since restrictions stay invisible to the types.
      *
      * A call's optional second argument is its `ExecutionOptions`: a supplied
-     * `requestId` is the request's, in every pipeline context and diagnostic;
-     * omitted or empty, a fresh id is minted per call (F-833).
+     * `requestId` is the request's, in every pipeline context and diagnostic; omitted
+     * or empty, a fresh id is minted per call.
      */
     readonly application: ApplicationOperations<M, Cfg>;
     /**
@@ -58,33 +58,32 @@ export type Framework<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkC
     /**
      * Validates a whole transaction plan, then runs its operations strictly
      * sequentially inside one Adapter transaction. Answers `A1009` with each
-     * operation's final data in plan order, the failing operation's own code
-     * with `cause.operation` after rollback, or `A3002` when the transaction
-     * infrastructure fails. Total: it resolves for every input.
+     * operation's final data in plan order, the failing operation's own code with
+     * `cause.operation` after rollback, or `A3002` when the transaction infrastructure
+     * fails. Total: it resolves for every input.
      *
-     * Every operation's guards, pipes, hooks and interceptors run while the
-     * provider transaction is open and must not perform network I/O or
-     * unrelated slow work (spec §14.5). The Adapter must reject with the exact
-     * value its transaction callback threw, by identity.
+     * Every operation's guards, pipes, hooks and interceptors run while the provider
+     * transaction is open and must not perform network I/O or unrelated slow work. The
+     * Adapter must reject with the exact value its transaction callback threw, by
+     * identity.
      */
     executeTransaction(request: FrameworkTransactionRequest): Promise<TransactionResponse>;
     /**
      * The one typed transaction runner: `framework.transaction([h1, h2, …])`.
      *
      * Binds each `$ref` to its source's position in this list, fingerprints every
-     * step, and runs the resulting passive plan through the same validation layer
-     * and transaction runtime as {@link executeTransaction} — each step under its
-     * own handle's origin, its own layer's Contract and pipelines, inside one
-     * Adapter transaction. The committed response is typed per position.
+     * step, and runs the resulting passive plan through the same validation layer and
+     * transaction runtime as {@link executeTransaction} — each step under its own
+     * handle's origin, its own layer's Contract and pipelines, inside one Adapter
+     * transaction. The committed response is typed per position.
      *
      * Refused before anything runs: an entry that is not one of this Framework's
-     * handles, or the same handle twice (`A2004`/`V1001`); a `$ref` to a handle not
-     * in the list (`A2007`/`V1010`). Total: it resolves for every input.
+     * handles, or the same handle twice (`A2004`/`V1001`); a `$ref` to a handle not in
+     * the list (`A2007`/`V1010`). Total: it resolves for every input.
      *
-     * The optional second argument is the run's `ExecutionOptions`: its
-     * `requestId` is every step's, under either origin; omitted or empty, one id
-     * is minted for the run. Handles take no options — a handle is not a request
-     * (Q14).
+     * The optional second argument is the run's `ExecutionOptions`: its `requestId` is
+     * every step's, under either origin; omitted or empty, one id is minted for the
+     * run. Handles take no options — a handle is not a request.
      */
     readonly transaction: TransactionRunner;
 };

package/dist/framework/framework.factory.js

@@ -10,26 +10,6 @@ import { createTransactionPlanAssembler } from "../transactions/transaction-plan
 import { createTransactionRuntime } from "../transactions/transaction-runtime.js";
 import { FrameworkConstructionError } from "./framework-construction.error.js";
 import { createOperationFacade, createOperationTree, } from "./operation-facade.js";
-/**
- * Validate, read the model, resolve, compile, and bind one Aventara Framework
- * instance.
- *
- * The parameter is deliberately `Cfg & FrameworkConfig<M, Cfg>` rather than
- * the obvious `FrameworkConfig<M, Cfg>`. `Cfg` has to appear somewhere the
- * compiler actually infers from; inside `FrameworkConfig`'s body it only ever
- * reaches non-inference positions, so it would fall back to its
- * `AnyFrameworkConfig` default with no error reported anywhere, and every
- * narrowing keyed on the authored configuration would quietly widen. The
- * intersection puts `Cfg` directly against the argument type.
- *
- * `Cfg` is a `const` type parameter for the same reason: it stands for the
- * configuration *as authored*. Without `const`, inferring `Cfg` from an
- * inline configuration literal widens its scalar references away from their
- * literal types, and the widened `Cfg` then loses to the intersection's own
- * `FrameworkConfig` half — a call site that compiles today stops compiling.
- * A configuration passed as an already-annotated variable is unaffected
- * either way.
- */
 export async function createFramework(config) {
     const configDiagnostics = validateFrameworkConfig(config);
     if (configDiagnostics.length > 0) {
@@ -62,8 +42,6 @@ export async function createFramework(config) {
         config: resolvedConfig,
     });
     const executeOperation = (request) => executeTotally(execute, request, resolvedConfig.diagnostics);
-    // A client-origin call in process carries the server's own protocol
-    // identity: there is no remote generated client whose hash could be stale.
     const protocol = {
         version: AVENTARA_PROTOCOL_VERSION,
         hash: compilation.contracts.client.protocol.hash,
@@ -91,23 +69,11 @@ export async function createFramework(config) {
         clientTx: createOperationTree(model, (resource, identity) => (args) => assembler.defer("client", resource, identity, args === undefined ? {} : args)),
         execute: executeOperation,
         executeTransaction: (request) => executeTransactionTotally(executeTransaction, request, resolvedConfig.diagnostics),
-        // The result type is the handles' derivation, an authoring affordance
-        // (ADR 0009): every slot was held to its own Contract by output validation.
         transaction: ((operations, options) => runTransactionTotally(executeTransaction, assembler, operations, requestIdOf(options), resolvedConfig.diagnostics)),
     };
     recordDiagnosticsSink(framework, resolvedConfig.diagnostics);
     return framework;
 }
-/**
- * Outermost totality guard on the public execution seam. The validation
- * boundary and the pipeline boundary do the real work; this covers only what
- * they cannot — a failure inside those boundaries themselves. It reads
- * nothing off the caught value and calls no sanitizer: the envelope is a
- * constant, so this guard is incapable of failing. Reporting the raw error
- * to the diagnostics channel preserves that property, because the reporter
- * is total by construction. `Framework.execute()` therefore resolves to a
- * valid OperationResponse for every input.
- */
 async function executeTotally(execute, request, diagnostics) {
     const report = createDiagnosticsReporter(diagnostics, request);
     try {
@@ -118,12 +84,6 @@ async function executeTotally(execute, request, diagnostics) {
         return internalFailure();
     }
 }
-/**
- * Outermost totality guard for the transport-independent transaction seam.
- * The channel it binds is the only diagnostics route of the plan: the guard
- * reports through its plan-level reporter, and the executor receives the
- * same channel.
- */
 async function executeTransactionTotally(execute, request, diagnostics, origins) {
     const channel = createTransactionDiagnosticsChannel(diagnostics, request);
     const report = channel.transaction();
@@ -135,15 +95,6 @@ async function executeTransactionTotally(execute, request, diagnostics, origins)
         return internalFailure();
     }
 }
-/**
- * The typed runner's seam: assemble the handles into the passive plan, then run
- * it through the same guard as `executeTransaction`, each step under its own
- * origin. The plan is server code's, so its request is application-origin — no
- * remote client identity to check — and every origin a step carries is gated by
- * the validation layer. Assembly sits inside the same totality boundary: it
- * resolves for every input. `requestId` is the run's — the caller's, or minted
- * once for the whole run — so every step and every diagnostic carries one id.
- */
 async function runTransactionTotally(execute, assembler, operations, requestId, diagnostics) {
     let assembled;
     try {

package/dist/framework/operation-facade.js

@@ -1,25 +1,9 @@
 import { isOperationVariantAvailable } from "../contracts/resource-operations.js";
 import { parseOperationIdentity } from "../operations/operation-identity.js";
 import { requestIdOf } from "../runtime/request-id.js";
-/**
- * Builds a façade over `model`, the same object its types are read from, so a
- * call that type-checks always reaches `execute`: a Resource, variant or field
- * the active Contract does not carry is still a function here, and the
- * validation layer answers it.
- *
- * Each call's request is `request`'s — its origin — under the caller's
- * `ExecutionOptions.requestId`, or a freshly minted id when there is none; an
- * omitted argument is the empty argument object, which the type admits only
- * when every member is optional.
- */
 export function createOperationFacade(model, request, execute) {
     return createOperationTree(model, (resource, identity) => (args, options) => execute(request(resource, identity, args === undefined ? {} : args, requestIdOf(options))));
 }
-/**
- * The runtime shape every façade and builder shares: one frozen property per
- * Resource of `model`, one per family under it, one leaf per variant the model
- * advertises in the standard grammar.
- */
 export function createOperationTree(model, leaf) {
     const resources = Object.entries(model.resources).map(([resource, { operations }]) => {
         const families = Object.entries(operations).map(([family, variants]) => [family, variantLeaves(leaf, resource, family, variants)]);
@@ -27,7 +11,6 @@ export function createOperationTree(model, leaf) {
     });
     return Object.freeze(Object.fromEntries(resources));
 }
-/** One family's leaves: each advertised variant of the standard grammar. */
 function variantLeaves(leaf, resource, family, variants) {
     const leaves = Object.entries(variants ?? {}).flatMap(([variant, availability]) => {
         const identity = parseOperationIdentity(family, variant);

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

@@ -59,11 +59,11 @@ type HoldsAtScope<Value, Scope extends ProjectionScope | WriteScope> = Value ext
     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
+ * 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 (C-855). {@link CapabilityTokens} asks both.
+ * second by forgetting it. {@link CapabilityTokens} asks both.
  */
 type AdvertisedTokens<Value> = Value extends {
     readonly scopes: readonly WriteScope[];
@@ -135,13 +135,12 @@ export type ScalarFilterInput = unknown | Readonly<Partial<Record<ScalarFilterOp
  * 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 (spec §9.1), and a JSON object is an operator
- * object by construction — `{ equals: document }` carries it. The same
- * exclusion as `not`'s value arm below.
+ * 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>;
 /**
@@ -241,25 +240,22 @@ type OrderValue<C extends Contract, K extends ResourceKey<C>, F extends Orderabl
 /**
  * One `orderBy` precedence entry: exactly one orderable field and its value.
  *
- * **The value is read inside the entry's own mapped property, never handed in
- * as a type argument** — the shape {@link RelationProjectionEntry} shares, and
- * the whole of F-823. 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
+ * 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.
+ * `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.
  */
 export type OrderByEntry<C extends Contract, K extends ResourceKey<C>> = {
     [F in OrderableFieldKey<C, K>]: {
@@ -325,16 +321,14 @@ export type RelationProjectionInput<C extends Contract, K extends ResourceKey<C>
  * One relation entry of a projection: exactly relation `F` of `Keys`, with its
  * argument object, and every other key of `Keys` absent.
  *
- * **The argument object is read inside the entry's own mapped property, never
- * handed in as a type argument** — the shape {@link OrderByEntry} has for
- * F-823's reason, kept here for cost. 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.
+ * 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>;
@@ -408,13 +402,13 @@ declare const NO_ADVERTISED_MEMBER: unique symbol;
  *
  * 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 (F-810). One optional member on a
+ * 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 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`).
+ * 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;
@@ -489,11 +483,7 @@ type QueryProjectionArgs<C extends Contract, K extends ResourceKey<C>, Scope ext
  * **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. The
- * consequence is that the type can over-advertise where an adapter is narrower,
- * never the reverse, and the runtime guard refuses what it advertised — which is
- * why this surface is not a substitute for the validation layer (ADR 0009: the
- * compiled Contract is untyped, so no type here is load-bearing at runtime).
+ * 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
@@ -580,7 +570,7 @@ export type OperationArgumentMap<C extends Contract, K extends ResourceKey<C>, F
  * 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 (ADR 0009).
+ * The validation layer stays the guard either way.
  */
 export type OperationArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms = UnstatedForms> = I extends {
     family: infer F;

package/dist/operations/operation-boolean-nodes.js

@@ -95,10 +95,6 @@ function projectionRelation(contract, resourceName, entry, mode, scope) {
     if (field?.kind !== "relation") {
         return undefined;
     }
-    // The SAME scope-aware read the grammar walk uses. This walk skips a relation it
-    // cannot descend, so reading the member scope-blind would stop counting beneath
-    // every measured relation — `maxBooleanNodes` silently unenforced inside a
-    // projection the grammar walk then admits.
     if (mode === "select" && !holdsAt(field.capabilities.select, scope)) {
         return undefined;
     }
@@ -132,7 +128,6 @@ function walkProjection(state, resourceName, value, mode, scope, path) {
             if (!(nestedMode in relation.value)) {
                 continue;
             }
-            // Nested is unrestricted at every depth — {@link NESTED_PROJECTION_SCOPE}.
             const issue = walkProjection(state, relation.edge.target, relation.value[nestedMode], nestedMode, NESTED_PROJECTION_SCOPE, [...relationPath, nestedMode]);
             if (issue !== undefined) {
                 return issue;
@@ -157,12 +152,6 @@ function walkMutationData(state, resourceName, value, stage, path) {
         if (edge?.kind !== "relation" || !isRecord(fieldValue)) {
             continue;
         }
-        // Scope-blind, unlike the projection read above, and deliberately: this walk
-        // may only ever be a SUPERSET of what the grammar walk admits. The write scope
-        // narrows the top level of a write, so a scope-aware read here could only
-        // descend less — and a walk that stops counting inside a write the grammar walk
-        // admits is `maxBooleanNodes` silently unenforced. Counting inside one it is
-        // about to refuse costs a node tally nobody reads.
         const supported = advertisedDirectives(edge.capabilities[stage]);
         for (const [directive, directiveValue] of Object.entries(fieldValue)) {
             if (supported?.includes(directive) !== true) {
@@ -241,11 +230,6 @@ function isUniqueOperation(request) {
             request.family === "delete" ||
             request.family === "upsert"));
 }
-/**
- * Enforces maxBooleanNodes across every general where tree in one semantic
- * operation, including root filters, returned-relation filters, and nested
- * relation mutation filters. Unique selectors are intentionally excluded.
- */
 export function findOperationBooleanNodeIssue(contract, request, args) {
     const state = { contract, count: 0 };
     const projectionScope = resolveProjectionScope(lookupResource(contract, request.resource), request);

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

@@ -54,8 +54,8 @@ export type OperationGrammar<C extends Contract> = {
 };
 /**
  * An operation's slot: its result, except that a first-style miss contributes
- * `null` (DA-1) — 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.
+ * `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.
  */
 export type OperationSlot<I extends OperationIdentity, Result> = I["variant"] extends "first" ? Result | null : Result;
 /**
@@ -72,18 +72,13 @@ 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 DA-3 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 (Q14).
+ * 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.js

@@ -16,7 +16,6 @@ const STANDARD_OPERATIONS = {
     "delete.count": true,
     "upsert.unique": true,
 };
-/** Parses one exact standard operation family/variant pair. */
 export function parseOperationIdentity(family, variant) {
     const key = `${family}.${variant}`;
     if (!Object.hasOwn(STANDARD_OPERATIONS, key)) {

package/dist/operations/operation-nesting.js

@@ -257,11 +257,6 @@ function walkMutationData(context, resourceName, value, depth, path) {
     }
     return undefined;
 }
-/**
- * Enforces the Contract's semantic nesting limit across where, projection,
- * orderBy, mutation data, and relation traversal before deeper argument
- * validation.
- */
 export function findOperationNestingIssue(contract, resourceName, args) {
     if ("where" in args) {
         const rootPath = ["arguments", "where"];

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

@@ -90,7 +90,7 @@ type RelationResult<C extends Contract, Target extends ResourceKey<C>, Relation
 /**
  * The value a standard operation returns in `OperationResponse.data` on success,
  * derived from the Contract, the Resource, the operation identity and the
- * projection argument (F-701).
+ * projection argument.
  *
  * - `count` → `number`;
  * - `many` → `readonly Record[]`;
@@ -104,9 +104,9 @@ type RelationResult<C extends Contract, Target extends ResourceKey<C>, Relation
  * unadvertised `$count`, a relation outside a bulk write's ceiling — is refused
  * here instead of typed as present.
  *
- * `Forms` (Q3 = 3a) 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.
+ * `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.
  */
 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>;
 /**

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

@@ -17,8 +17,8 @@ export type OperationValidationOptions = {
 /**
  * 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
- * (`@aventara/core/protocol`, Q2's O3) build theirs with it.
+ * `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

@@ -168,11 +168,6 @@ function validateScalarFilter(fieldName, field, value, path, state) {
         }
         return;
     }
-    // Equality shorthand: anything that is not a plain record is a value — a
-    // `Date`, a `Decimal` and a `Uint8Array` included — read through the scalar
-    // runtime's own discriminant, which holds it to the field's scalar after
-    // this layer (`normalizeScalarFilter`). Reading every object as operators
-    // refused the shorthand the ORM accepts (C-855, sign flipped).
     if (!isPlainRecord(value)) {
         if (!includes(supported, "equals")) {
             addIssue(state.issues, "V1006", path, `Equality filtering is not available on field "${fieldName}".`);
@@ -409,14 +404,7 @@ function validateCursor(contract, resourceName, cursor, orderBy, path, issues) {
         addIssue(issues, "V1009", path, "orderBy must include a complete Resource identifier as an explicit tie-breaker.");
     }
 }
-function validateProjection(contract, resourceName, mode, value, 
-/**
- * The projection position THIS projection's own field and relation entries sit
- * in. The caller resolves it once from the advertised variant; a nested call
- * passes {@link NESTED_PROJECTION_SCOPE}, because a scope qualifies the top level
- * only. A `$count` entry is the exception and reads {@link ReducerOwner.scope}.
- */
-scope, path, issues, reducerOwner) {
+function validateProjection(contract, resourceName, mode, value, scope, path, issues, reducerOwner) {
     if (!Array.isArray(value)) {
         addIssue(issues, "V1008", path, `${mode} must be an array.`);
         return;
@@ -431,10 +419,7 @@ scope, path, issues, reducerOwner) {
         if (entry === "$count") {
             if (mode !== "select" ||
                 reducerOwner?.edge.cardinality !== "many" ||
-                !includes(advertisedReducersAt(reducerOwner.edge.capabilities.reducers, 
-                // The OWNER's position, not this projection's: see
-                // {@link ReducerOwner}.
-                reducerOwner.scope), "$count")) {
+                !includes(advertisedReducersAt(reducerOwner.edge.capabilities.reducers, reducerOwner.scope), "$count")) {
                 addIssue(issues, "V1008", entryPath, "$count is available only as an advertised to-many relation reducer.");
             }
             return;
@@ -477,16 +462,10 @@ scope, path, issues, reducerOwner) {
             addIssue(issues, "V1008", relationPath, `Relation "${relationName}" is not available for ${mode}.`);
             return;
         }
-        validateRelationProjection(contract, field, 
-        // The position the edge itself was admitted in. The edge's nested
-        // projection is unrestricted, but a `$count` of this edge is carried at
-        // THIS level, so the scope has to travel with the edge.
-        scope, entry[relationName], relationPath, issues);
+        validateRelationProjection(contract, field, scope, entry[relationName], relationPath, issues);
     });
 }
-function validateRelationProjection(contract, edge, 
-/** The projection position `edge` itself was admitted in — see {@link ReducerOwner}. */
-scope, value, path, issues) {
+function validateRelationProjection(contract, edge, scope, value, path, issues) {
     if (!isRecord(value)) {
         addIssue(issues, "V1008", path, "Customized relation projection must be an object.");
         return;
@@ -551,10 +530,6 @@ scope, value, path, issues) {
             validateCursor(contract, edge.target, value.cursor, value.orderBy, [...path, "cursor"], issues);
         }
     }
-    // Past an admitted relation the unrestricted surface returns, measured on both
-    // pilot engines — see {@link NESTED_PROJECTION_SCOPE}. The edge's own scope is
-    // deliberately NOT passed down: a recursive narrowing would refuse what the ORM
-    // accepts.
     if ("select" in value) {
         validateProjection(contract, edge.target, "select", value.select, NESTED_PROJECTION_SCOPE, [...path, "select"], issues, { edge, scope });
     }
@@ -595,16 +570,6 @@ function validateScalarMutation(fieldName, field, value, stage, path, issues, tr
         }
     }
 }
-/**
- * One relation mutation directive's operand, past the point where the directive
- * itself was admitted.
- *
- * It takes **no write scope**, and that is the rule rather than an omission: every
- * data object it reaches is nested, and {@link NESTED_WRITE_SCOPE} is the answer at
- * every depth. A parameter here would be a parameter this function could only
- * ignore, and the next reader would thread the caller's scope through it and refuse
- * what the ORM accepts.
- */
 function validateRelationMutationEntry(contract, edge, directive, value, path, issues) {
     const target = edge.target;
     if (edge.cardinality === "one" && Array.isArray(value)) {
@@ -747,13 +712,7 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
         }
     }
 }
-function validateRelationMutation(contract, fieldName, field, value, stage, 
-/** The write position this relation member itself sits in; see {@link WriteScope}. */
-scope, path, issues) {
-    // Scope-aware, through the shape owner's one reader. A stage that does not hold
-    // at this write position is not writable at this write position, and says so with
-    // the message an absent member already has — which is why the two answers
-    // `advertisedDirectivesAt` can give are the two this branch already handled.
+function validateRelationMutation(contract, fieldName, field, value, stage, scope, path, issues) {
     const directives = advertisedDirectivesAt(field.capabilities[stage], scope);
     if (directives === undefined) {
         addIssue(issues, "V1006", path, `Relation "${fieldName}" is not writable during ${stage}.`);
@@ -772,15 +731,7 @@ scope, path, issues) {
         validateRelationMutationEntry(contract, field, directive, directiveValue, directivePath, issues);
     }
 }
-function validateMutationData(contract, resourceName, data, stage, 
-/**
- * The write position THIS data object's own relation members sit in. The caller
- * resolves it once from the advertised variant; a nested call passes
- * {@link NESTED_WRITE_SCOPE}, because a scope qualifies the top level only.
- * Scalar members never read it — all six scalar capability members were measured
- * uniform across every variant on the axis.
- */
-scope, path, issues, transactionReferences = false) {
+function validateMutationData(contract, resourceName, data, stage, scope, path, issues, transactionReferences = false) {
     if (!isRecord(data)) {
         addIssue(issues, "V1001", path, `${stage} data must be an object.`);
         return;
@@ -806,14 +757,6 @@ scope, path, issues, transactionReferences = false) {
     }
 }
 function validateMutationArguments(contract, resourceName, request, args, issues, options) {
-    // The one resolution, from the variant the Resource advertises, and the write
-    // mirror of the projection scope resolved at the top level. It qualifies the top
-    // level of the write argument only; everything beneath an admitted relation
-    // directive is nested and asks about the unrestricted position instead.
-    //
-    // Resolved here rather than passed in because `request` is what carries the
-    // variant, and an argument walk handed a scope could be handed one resolved for a
-    // different request.
     const scope = resolveWriteScope(getResource(contract, resourceName), request);
     if (request.family === "create") {
         if (!("data" in args)) {
@@ -853,12 +796,6 @@ function isUniqueOperation(request) {
             request.family === "delete" ||
             request.family === "upsert"));
 }
-/**
- * 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
- * (`@aventara/core/protocol`, Q2's O3) build theirs with it.
- */
 export function resourceUnavailableIssue(resource) {
     return {
         code: "V1005",
@@ -911,8 +848,6 @@ export function validateOperationArguments(contract, request, options) {
     if ("cursor" in request.arguments) {
         validateCursor(contract, request.resource, request.arguments.cursor, request.arguments.orderBy, ["arguments", "cursor"], issues);
     }
-    // The one resolution, from the variant the Resource advertises. Everything below
-    // the top level is nested and asks about the unrestricted position instead.
     const projectionScope = resolveProjectionScope(resource, request);
     if ("select" in request.arguments) {
         validateProjection(contract, request.resource, "select", request.arguments.select, projectionScope, ["arguments", "select"], issues);