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

package/dist/contracts/field.d.ts

@@ -1,49 +1,18 @@
 import type { PaginationCapability, ProjectionScope, RelationFilterCapability, RelationMutationDirective, RelationReducer, ScalarFilterOperator, ScalarMutationDirective, WriteScope } from "./capability.js";
 import type { Contract } from "./contract.js";
 import type { LifecycleTrait } from "./lifecycle-trait.js";
-/** Passive scalar format identity; concrete codec semantics remain protocol-owned. */
+/** A format name that refines a scalar type, carried in the Contract as data. */
 export type ScalarFormat = string;
-/**
- * The projection positions a field is projectable in: at least one, because an
- * EMPTY list is not a third answer.
- *
- * `absent ≠ empty` is this repository's established rule and the validation layer
- * already acts on the difference, so the empty list has to be unrepresentable
- * rather than merely discouraged. An absent capability member is "not available at
- * all"; an empty list would say the same thing in a second encoding, which is one
- * semantic fact with two hashes.
- *
- * **A scope list qualifies the TOP LEVEL of a projection only. It does not narrow
- * recursively** — see {@link ProjectionScope}, where the runtime measurement and
- * the reason are recorded.
- */
+/** The projection positions a field can be selected in (at least one). */
 export type ProjectionScopes = readonly [ProjectionScope, ...ProjectionScope[]];
 /**
- * The write positions a field is writable in: at least one, for the reason
- * {@link ProjectionScopes} gives. Here the distinction is sharper still, because
- * the directive list beside it is separately allowed to be empty and already
- * means something: on a relation mutation member, absent answers `V1006` *"is not
- * writable during <stage>"* while `[]` answers *"writable with no directive"*. A
- * scope list that could also be empty would put a third, unreachable answer next
- * to those two.
- *
- * **A scope list qualifies the TOP LEVEL of a write argument only. It does not
- * narrow recursively** — see {@link WriteScope}.
+ * The write positions a field can be written in (at least one). A scope list
+ * applies to the top level of a write argument only; see {@link WriteScope}.
  */
 export type WriteScopes = readonly [WriteScope, ...WriteScope[]];
 /**
- * Whether a relation is projectable, and — when the adapter has measured it — the
- * projection positions it is projectable in.
- *
- * `true`/`false` is the unqualified answer: available, or not, in every projection
- * position. A {@link ProjectionScopes} list is the qualified answer, and it exists
- * because both pilot engines measurably narrow the top level of a BULK write's
- * returned-row projection to the relations the written row itself resolves, while
- * advertising the full surface on every read.
- *
- * The unqualified arm is retained deliberately: an adapter that has not measured
- * the axis must be able to say so, and a Contract that predates the measurement
- * must keep its meaning.
+ * Whether a relation can be selected or included: `true`, or the projection
+ * positions it can be used in.
  */
 export type RelationProjectionCapability = boolean | ProjectionScopes;
 /**
@@ -57,36 +26,25 @@ export type ScopedRelationReducers = {
     readonly scopes: ProjectionScopes;
 };
 /**
- * A relation's reducer capability: the bare reducer list is the unqualified
- * answer, the scoped form the measured one. Discriminated structurally — the
- * unqualified arm is an array, the qualified arm an object.
+ * A relation's reducers: a reducer list, or an object with the reducers and
+ * the projection positions they apply in.
  */
 export type RelationReducerCapability = readonly RelationReducer[] | ScopedRelationReducers;
 /**
- * The mutation directives a relation admits at one write stage, qualified by the
- * write positions they are admitted in.
- *
- * `directives: []` stays meaningful and stays distinct from an absent member —
- * "writable with no directive" against "not writable during this stage" — so the
- * scoped form carries the directive list rather than replacing it.
+ * The mutation directives a relation admits at one write stage, and the write
+ * positions they are admitted in. `directives: []` means writable with no
+ * directive.
  */
 export type ScopedRelationMutations = {
     readonly directives: readonly RelationMutationDirective[];
     readonly scopes: WriteScopes;
 };
 /**
- * A relation's write capability at one stage: the bare directive list is the
- * unqualified answer, the scoped form the measured one. Discriminated structurally
- * — the unqualified arm is an array, the qualified arm an object.
+ * A relation's write capability for `create` or `update`: a directive list, or
+ * an object with the directives and the write positions they apply in.
  */
 export type RelationMutationCapability = readonly RelationMutationDirective[] | ScopedRelationMutations;
-/**
- * Scalar capabilities carry no scope qualifier. Measured on both pilot engines,
- * 2026-10-03: all six members are uniform across every operation variant on the
- * axis — the same scalar members, the same operands, the same declared input
- * symbols in the singular and the bulk forms. Qualifying them would encode a
- * variation that does not exist.
- */
+/** What can be done with a scalar field. Scalar capabilities apply in every position. */
 export type ScalarFieldCapabilities = {
     readonly select?: boolean;
     readonly filter?: readonly ScalarFilterOperator[];
@@ -95,18 +53,7 @@ export type ScalarFieldCapabilities = {
     readonly create?: readonly ScalarMutationDirective[];
     readonly update?: readonly ScalarMutationDirective[];
 };
-/**
- * Relation capabilities. Five of the eight members are scope-qualified, which is
- * exactly the five the survey measured as varying by operation variant, by two
- * independent mechanisms: the bulk-returning projection ceiling (`select`,
- * `include`, `reducers`) and the flat bulk write stage (`create`, `update`).
- *
- * The other three are left alone on the same evidence. `filter` is uniform
- * (`<M>WhereInput` and `<M>WhereUniqueInput` agree member-for-member on relation
- * members), `order` is uniform (one orderBy input type across every orderBy-carrying
- * variant), and `pagination` is read off the edge's own arguments, the same symbol
- * under every projection that admits the edge at all.
- */
+/** What can be done with a relation field. */
 export type RelationFieldCapabilities = {
     readonly select?: RelationProjectionCapability;
     readonly include?: RelationProjectionCapability;
@@ -118,119 +65,34 @@ export type RelationFieldCapabilities = {
     readonly update?: RelationMutationCapability;
 };
 /**
- * The reducers a relation advertises, whichever arm the member is written in,
- * **ignoring the scope qualifier**.
- *
- * Scope-blind on purpose, and only for a reader on an axis the scope does not
- * qualify. `orderBy: { <to-many>: { $count: … } }` is the one such reader: ordering
- * was measured uniform across every variant that carries an `orderBy` argument, so
- * there is no projection position to ask about and asking would invent one.
- *
- * Every reader on the projection axis wants {@link advertisedReducersAt} instead.
+ * The reducers a relation advertises, in any projection position. Use
+ * {@link advertisedReducersAt} for one position.
  */
 export declare function advertisedReducers(capability: RelationReducerCapability | undefined): readonly RelationReducer[] | undefined;
-/**
- * Whether a projection capability holds at one projection scope — **the one home
- * of the scope-aware capability read.**
- *
- * Every reader that has a scope asks this, and no reader compares a capability
- * member to `true` any more. That is not tidiness: a qualified member is an
- * object/array, so `member === true` is `false` for *every* scope, and the six
- * `select`/`include` comparisons this function replaces read a measured
- * `["record"]` as **unavailable everywhere** — a to-many projection refused on
- * `update.first`, which is the single-record scope the adapter advertises it in.
- *
- * The parameter admits `boolean` as well as {@link ProjectionScopes} because the
- * unqualified arm means *holds in every scope*: an adapter that has not measured
- * the axis, and every Contract that predates the measurement, must keep answering
- * what they answered before. So `true` holds at every scope and `false`/absent at
- * none, and the qualified arm is consulted only where one exists.
- *
- * **A scope qualifies the TOP LEVEL of a projection only** — see {@link
- * ProjectionScope}, where the runtime measurement is recorded. A caller that
- * recurses must ask about the nested position with the unrestricted scope, not
- * with its own.
- */
+/** Whether a projection capability holds at one projection position. */
 export declare function holdsAt(capability: RelationProjectionCapability | undefined, scope: ProjectionScope): boolean;
 /**
- * Whether a projection capability holds in **any** scope — the scope-blind
- * question, for the one reader that legitimately has no scope to ask about.
- *
- * It exists so that reader does not hand-roll `=== true` either. The Contract
- * compiler's VIRTUAL lifecycle check asks whether a field is selectable *at all*
- * before requiring an effective read behavior; a field selectable in one scope
- * needs that behavior exactly as much as one selectable in every scope.
- *
- * A reader with a scope must use {@link holdsAt}. This one answers a strictly
- * weaker question and will over-advertise if used in its place.
+ * Whether a projection capability holds in **any** projection position. Use
+ * {@link holdsAt} when the position is known.
  */
 export declare function holdsInAnyScope(capability: RelationProjectionCapability | undefined): boolean;
 /**
- * The reducers a relation advertises **at one projection scope**: the tokens where
- * the member holds there, and `undefined` where it does not.
- *
- * One call rather than two, because the two-call form is the defect. A reader that
- * asks {@link advertisedReducers} for the tokens and then has to remember a second
- * {@link holdsAt} call will forget it, and a forgotten scope check is a silent
- * over-advertisement. Here the scope cannot be forgotten: there is no way to get
- * the tokens without naming the position they are wanted in.
- *
- * `undefined` is the same answer an absent member gives, which is correct — a
- * reducer that does not hold at this scope is not advertised at this scope — and
- * it keeps `[]` meaning what it means everywhere else: advertised, with no
- * reducer.
+ * The reducers a relation advertises at one projection position, or
+ * `undefined` where it has none there.
  */
 export declare function advertisedReducersAt(capability: RelationReducerCapability | undefined, scope: ProjectionScope): readonly RelationReducer[] | undefined;
 /**
- * The mutation directives a relation advertises at one write stage, whichever arm
- * the member is written in, **ignoring the scope qualifier**. `undefined` and `[]`
- * stay distinct: the stage is unavailable, or available with no directive.
- *
- * Scope-blind on purpose, and only for a reader that has no write position to ask
- * about or whose answer may only be WIDER than the validator's. Two readers
- * qualify. `operation-boolean-nodes.ts`'s `maxBooleanNodes` walk descends a
- * relation mutation to count the filter nodes inside it; reading scope-blind makes
- * that walk a superset of what the grammar walk admits, which is the harmless
- * direction — it counts inside a write that is about to be refused, and it can
- * never stop counting inside one that is admitted. An adapter's own write
- * translator is the other: it is handed the write site's verdict by whoever
- * dispatched it and holds no advertised variant to resolve a scope from.
- *
- * Every reader on the write axis that HAS a position wants {@link
- * advertisedDirectivesAt} instead.
- *
- * See {@link advertisedReducers} for why the scopes are not returned beside them.
+ * The mutation directives a relation advertises at one write stage, in any
+ * write position. `undefined` means the stage is unavailable; `[]` means
+ * available with no directive.
  */
 export declare function advertisedDirectives(capability: RelationMutationCapability | undefined): readonly RelationMutationDirective[] | undefined;
 /**
- * The mutation directives a relation advertises **at one write scope**: the
- * directives where the member holds there, and `undefined` where it does not —
- * **the one home of the scope-aware write read**, and the write mirror of {@link
- * advertisedReducersAt}.
- *
- * One call rather than two, for the reason {@link advertisedReducersAt} gives: a
- * reader that fetches the directives and then has to remember a separate scope
- * check will forget it, and a forgotten scope check is a silent
- * over-advertisement. Here the position cannot be forgotten, because there is no
- * way to reach the directives without naming it.
- *
- * `undefined` for a stage that does not hold at this scope is the same answer an
- * absent member gives, which is what the caller must say: a relation that is not
- * writable in this write position is *"not writable during <stage>"* there. That
- * keeps `[]` meaning what it means everywhere else — advertised, with no directive
- * — so the two live answers `V1006` already distinguishes stay two, and the scope
- * does not invent a third.
- *
- * The unqualified arm is an array and means *holds in every write position*: an
- * adapter that has not measured the axis, and every Contract that predates the
- * measurement, keep the write surface they had.
- *
- * **A scope qualifies the TOP LEVEL of a write argument only** — see {@link
- * WriteScope}. A caller that recurses into a nested write must ask about the
- * nested position with the unrestricted scope, not with its own.
+ * The mutation directives a relation advertises at one write position, or
+ * `undefined` where it is not writable there.
  */
 export declare function advertisedDirectivesAt(capability: RelationMutationCapability | undefined, scope: WriteScope): readonly RelationMutationDirective[] | undefined;
-/** Atomic field from the API/query perspective, including enum-backed fields. */
+/** A scalar field, including an enum-backed one. */
 export type ScalarField<C extends Contract> = {
     readonly kind: "scalar";
     readonly type: {
@@ -244,7 +106,7 @@ export type ScalarField<C extends Contract> = {
     readonly lifecycle: readonly LifecycleTrait[];
     readonly capabilities: ScalarFieldCapabilities;
 };
-/** Relation edge only; the target Resource owns the returned object shape. */
+/** A relation field; the `target` Resource describes the related row. */
 export type RelationField<C extends Contract> = {
     readonly kind: "relation";
     readonly target: Extract<keyof C["resources"], string>;
@@ -252,4 +114,5 @@ export type RelationField<C extends Contract> = {
     readonly nullable: boolean;
     readonly capabilities: RelationFieldCapabilities;
 };
+/** One field of a Resource: a scalar or a relation. */
 export type Field<C extends Contract> = ScalarField<C> | RelationField<C>;

package/dist/contracts/identifier.d.ts

@@ -1,21 +1,6 @@
 import type { Contract } from "./contract.js";
 import type { Field } from "./field.js";
-/**
- * Keys of `TFields` whose Field can be scalar-shaped.
- *
- * `TFields[K]` is an indexed access, not a naked type parameter, so a bare
- * conditional would not distribute over a union-valued field. With the
- * abstract `ResourceFieldMap` default every key maps to the whole `Field`
- * union, which is not a subtype of the scalar branch, so the bare form
- * collapses to `never` and makes `Identifier` uninhabitable. `Extract` selects
- * the scalar branch out of the union instead, so a key is kept unless it is
- * provably relation-only.
- *
- * The branch is selected by its `kind` discriminant rather than by
- * `ScalarField<Contract>`: `Field<C>` measures as invariant in `C`, so a
- * `Field<ClientContract>` is not assignable to a `Field<Contract>` and the
- * `Extract` would collapse again. This mirrors `AdapterScalarFieldKey`.
- */
+/** Keys of `TFields` whose field can be scalar-shaped. */
 export type ScalarFieldKey<TFields extends Readonly<Record<string, Field<Contract>>>> = Extract<{
     [K in keyof TFields]: [
         Extract<TFields[K], {

package/dist/contracts/lifecycle-trait.d.ts

@@ -1,7 +1,8 @@
 /**
- * Lifecycle traits describe value ownership/derivation without implying
- * writability. Generated values are ORM/database-owned; computed values are
- * framework/developer-owned; virtual describes persistence only.
+ * Where a field's value comes from, without saying whether it is writable:
+ * `DEFAULTED` and `GENERATED_ON_*` by the data source, `COMPUTED_ON_*` by a
+ * framework behavior; `VIRTUAL` marks a field that is not stored.
  */
 export declare const LIFECYCLE_TRAITS: readonly ["DEFAULTED", "GENERATED_ON_CREATE", "GENERATED_ON_UPDATE", "COMPUTED_ON_CREATE", "COMPUTED_ON_UPDATE", "COMPUTED_ON_READ", "VIRTUAL"];
+/** One of {@link LIFECYCLE_TRAITS}. */
 export type LifecycleTrait = (typeof LIFECYCLE_TRAITS)[number];

package/dist/contracts/resource-operations.d.ts

@@ -3,19 +3,6 @@ import type { ProjectionScope, WriteScope } from "./capability.js";
  * The argument scopes one advertised operation variant qualifies its arguments
  * with: which projection position its projection arguments sit in, and which write
  * position its data argument sits in.
- *
- * The variant-to-scope map is an ADAPTER fact, not a protocol constant — a
- * variant's projection position depends on which ORM call the adapter routes it to
- * — so the advertised variant carries the answer rather than core tabulating it.
- *
- * At least one scope must be stated. A descriptor stating neither says exactly
- * what `true` says, and one semantic fact with two encodings is one fact with two
- * hashes.
- *
- * Named for the variant it qualifies, and deliberately not `OperationScopes`:
- * `OperationScope` is a public (now deprecated) alias of `RequestOrigin`, meaning
- * `"application" | "client"`, and two public names one character apart with
- * nothing in common is a vocabulary collision, not a near-miss.
  */
 export type OperationVariantScopes = {
     readonly projection: ProjectionScope;
@@ -60,63 +47,16 @@ export type ResourceOperations = {
     };
 };
 /**
- * Whether one `ResourceOperations` leaf advertises an available variant.
- *
- * Availability is **presence**: the leaf is `true`, or it is the descriptor that
- * qualifies the variant's arguments. A descriptor states how the variant's
- * arguments are scoped — it never retracts the variant — so `leaf === true` is
- * the wrong question wherever availability is read, and the leaf's widening to
- * `true | OperationVariantScopes` made every hand-rolled copy of that question
- * silently wrong. The question has one home so the next widening of
- * `OperationAvailability` reaches every reader at once.
- *
- * The parameter is `unknown` because the readers are the request validator and
- * the Contract compiler, which hold the leaf as a Contract value keyed by an
- * untrusted or mid-compilation string. Descriptor *shape* is not judged here: a
- * present leaf is an available variant, and validating what the descriptor says
- * belongs to whoever owns the descriptor's own invariants.
+ * Whether one `ResourceOperations` entry marks its variant available: it is
+ * `true` or an argument-position descriptor.
  */
 export declare function isOperationVariantAvailable(availability: unknown): availability is OperationAvailability;
 /**
  * The projection position one advertised variant's projection arguments sit in.
- *
- * `"record"` — the unrestricted position — is the answer for `true`, for an absent
- * leaf and for a descriptor that qualifies only its write argument, because the
- * unqualified arm means *nothing is narrowed here*. A Contract written before the
- * axis existed therefore keeps validating exactly as it did, which is what makes
- * the widening in {@link OperationAvailability} non-breaking for a producer that
- * has not measured it.
- *
- * The map from variant to scope is **not** here and must never be:
- * `update.first`'s projection position is the single-record one only because an
- * adapter chose to route that variant to a single-record provider call, and an
- * adapter that routes it to a bulk one moves the answer. Core reads what the
- * advertised variant carries rather than tabulating one scope per variant name.
- *
- * `unknown` for the same reason {@link isOperationVariantAvailable} takes it: the
- * caller holds the leaf keyed by an untrusted request string.
  */
 export declare function projectionScopeOf(availability: unknown): ProjectionScope;
 /**
  * The write position one advertised variant's data argument sits in, and the write
  * mirror of {@link projectionScopeOf}.
- *
- * `"nested"` — the unrestricted position — is the answer for `true`, for an absent
- * leaf and for a descriptor that qualifies only its projection argument, for the
- * same reason `"record"` is on the projection axis: the unqualified arm means
- * *nothing is narrowed here*, so a Contract written before the axis existed keeps
- * the write surface it had.
- *
- * The two axes are read by two functions, not one that returns a pair, because
- * they are measured and consulted separately — `WRITE_SCOPES` is a separate array
- * from `PROJECTION_SCOPES` for that reason — and a caller that needs only one
- * position should not be handed the other to discard.
- *
- * The mirror exists so that *"what does this descriptor mean?"* has one answer per
- * axis rather than one answer and one convention. The canonicalizer's collapse of
- * a redundant descriptor is keyed on these two functions' answer for `true`: a
- * descriptor says nothing beyond `true` exactly when every reader answers for it
- * what it answers for `true`, and that test is only as honest as the readers being
- * the single statement of each axis's unqualified scope.
  */
 export declare function writeScopeOf(availability: unknown): WriteScope;

package/dist/contracts/resource.d.ts

@@ -2,7 +2,9 @@ import type { Contract } from "./contract.js";
 import type { Field } from "./field.js";
 import type { Identifier } from "./identifier.js";
 import type { ResourceOperations } from "./resource-operations.js";
+/** A Resource's fields, by name. */
 export type ResourceFieldMap<C extends Contract> = Readonly<Record<string, Field<C>>>;
+/** One Resource: its fields, identifiers and available operations. */
 export type Resource<C extends Contract, TFields extends ResourceFieldMap<C> = ResourceFieldMap<C>> = {
     readonly fields: TFields;
     readonly identifiers: readonly Identifier<TFields>[];

package/dist/contracts/scalar-value-type.d.ts

@@ -4,31 +4,16 @@ import type { Contract } from "./contract.js";
 import type { ScalarField } from "./field.js";
 import type { BuiltInScalar } from "./scalar.js";
 /**
- * A scalar-form map: the TypeScript type each built-in scalar takes on one side of
- * a boundary. Every built-in must be answered, so a map that forgets one fails to
- * compile where it is passed rather than typing that scalar as `unknown`.
- *
- * It is a parameter rather than a fixed table because one derivation serves more
- * than one side: the application forms below for an in-process caller, and the
- * wire forms for a transport or a generated client.
- *
- * This constraint is not exported: a map is checked for completeness where it is
- * passed, so a consumer never has to name it.
+ * A scalar-form map: the TypeScript type each built-in scalar takes on one side
+ * of a boundary. Every built-in must be listed.
  */
 export type ScalarForms = {
     readonly [Scalar in BuiltInScalar]: unknown;
 };
 /**
- * The value form every framework-produced scalar takes, in either request scope.
- *
- * Output is scope-independent: output validation normalizes with `"runtime"`,
- * which maps to the application branch of `normalizeScalarAtom`, and the adapter
- * is held to it (`runtime/scalar-runtime.ts`, `runtime/output-validator.ts`). So
- * a client-scope caller receives these forms too, in process; the wire encoding
- * happens on a transport's way out.
- *
- * `decimal` is core's own {@link Decimal} — never a provider's decimal class —
- * which is what `normalizeScalarAtom`'s `instanceof Decimal` check enforces.
+ * The TypeScript form each built-in scalar takes in process: in results of
+ * either origin, and in `framework.application` arguments. `decimal` is
+ * Aventara's own {@link Decimal}.
  */
 export type ApplicationScalarForms = {
     readonly string: string;
@@ -40,17 +25,15 @@ export type ApplicationScalarForms = {
     readonly datetime: Date;
     readonly bytes: Uint8Array;
     /**
-     * `normalizeScalarFieldValue` refuses a field-level `null` on a required field and
-     * on a list entry, and reads it as the field's absence where `nullable: true`, so
-     * the `| null` comes from the Contract's `nullable` like every other scalar's. A
-     * `null` INSIDE the value is JSON's.
+     * Any JSON value. A field-level `null` is the field's absence and is allowed
+     * only where the field is nullable; a `null` inside the value is JSON's own.
      */
     readonly json: Exclude<JsonValue, null>;
 };
 /**
- * The encoded forms the client-scope input branch of `normalizeScalarAtom`
- * accepts: base-10 bigint strings, decimal strings, canonical ISO-8601 UTC
- * datetimes and RFC 4648 base64 bytes.
+ * The encoded forms of the built-in scalars: base-10 bigint strings, decimal strings,
+ * canonical ISO-8601 UTC datetimes and RFC 4648 base64 bytes. For a transport or a
+ * generated client to pass as `Forms`.
  */
 export type WireScalarForms = {
     readonly string: string;
@@ -61,20 +44,10 @@ export type WireScalarForms = {
     readonly decimal: string;
     readonly datetime: string;
     readonly bytes: string;
-    /**
-     * The same form as the application's: `normalizeJsonValue` has no client
-     * branch, and a JSON value needs no encoding to cross a JSON wire.
-     */
+    /** The same as in process: a JSON value needs no encoding to cross a JSON wire. */
     readonly json: Exclude<JsonValue, null>;
 };
-/**
- * One value of a scalar field, before `list` and `nullable` apply.
- *
- * Exported to the argument surface only, never from the package: a filter's
- * `in`, a list's `has` and a mutation directive's operand each take one entry of
- * a list field, which is exactly this, and a second spelling of it would be a
- * second derivation of one rule.
- */
+/** One value of a scalar field, before `list` and `nullable` apply. */
 export type ScalarAtom<C extends Contract, Type, Forms extends ScalarForms> = Type extends {
     readonly enum: infer Enum extends keyof C["enums"];
 } ? C["enums"][Enum]["values"][number] : Type extends {
@@ -86,17 +59,13 @@ export type ScalarAtom<C extends Contract, Type, Forms extends ScalarForms> = Ty
  */
 type ListValue<List, Atom> = [List] extends [false] ? Atom : [List] extends [true] ? readonly Atom[] : Atom | readonly Atom[];
 /**
- * The value type of one scalar field, under one scalar-form map.
+ * The value type of one scalar field, under one scalar-form map:
  *
- * - enum-backed → the member union of `EnumDefinition.values` (literal only while
- *   the model is `as const`; a widened model answers `string`);
+ * - enum-backed → the union of its values (literal only while the model is
+ *   `as const`; otherwise `string`);
  * - built-in scalar → `Forms[scalar]`;
- * - `list: true` → `readonly T[]`, whose entries are never `null`
- *   (`normalizeScalarFieldValue` refuses a null entry);
+ * - `list: true` → `readonly T[]`, whose entries are never `null`;
  * - `nullable: true` → `| null`, on the whole value, list or not.
- *
- * Nullability is read as "can it be `true`", so a Contract that widened the flag
- * to `boolean` is typed nullable rather than promised non-null.
  */
 export type ScalarValueType<C extends Contract, Field extends ScalarField<C>, Forms extends ScalarForms = ApplicationScalarForms> = ListValue<Field["list"], ScalarAtom<C, Field["type"], Forms>> | (true extends Field["nullable"] ? null : never);
 export {};

package/dist/contracts/scalar.d.ts

@@ -1,9 +1,10 @@
-/** Scalar identities owned by the Aventara v1 protocol. */
+/** The built-in scalar types of the Aventara protocol. */
 export declare const BUILT_IN_SCALARS: readonly ["string", "boolean", "int", "float", "bigint", "decimal", "datetime", "bytes", "json"];
+/** One of {@link BUILT_IN_SCALARS}. */
 export type BuiltInScalar = (typeof BUILT_IN_SCALARS)[number];
-/** Passive definition for a built-in scalar registry entry. */
+/** One entry of a scalar registry. */
 export type ScalarDefinition = {
     readonly builtin: true;
 };
-/** Passive scalar registry exposed by an AdapterModel or Contract. */
+/** The scalar types an adapter model or Contract supports, by name. */
 export type ScalarRegistry = Readonly<Record<string, ScalarDefinition>>;

package/dist/contracts/transaction-capability.d.ts

@@ -1,2 +1,4 @@
+/** The transaction capabilities. */
 export declare const TRANSACTION_CAPABILITIES: readonly ["none", "interactive"];
+/** `"none"` or `"interactive"`: whether transactions can run. */
 export type TransactionCapability = (typeof TRANSACTION_CAPABILITIES)[number];

package/dist/contracts/wire-scalar-format.d.ts

@@ -2,9 +2,9 @@ import type { BuiltInScalar } from "./scalar.js";
 import type { ApplicationScalarForms, WireScalarForms } from "./scalar-value-type.js";
 /**
  * The built-in scalars whose wire form is not their runtime form — the ones a JSON
- * wire carries as a string with a grammar of its own. Derived from the two form
- * maps rather than listed, so a built-in scalar added with a string wire form
- * fails to compile below until its grammar is written.
+ * wire carries as a string with a grammar of its own. Derived from the two form maps
+ * rather than listed, so a built-in scalar added with a string wire form fails to
+ * compile below until its grammar is written.
  */
 type WireEncodedScalar = {
     readonly [S in BuiltInScalar]: WireScalarForms[S] extends ApplicationScalarForms[S] ? never : S;
@@ -13,18 +13,6 @@ type WireEncodedScalar = {
  * `AvProtocol.scalarFormats` — the wire grammars of protocol version 1, as passive
  * data: one anchored pattern SOURCE string per wire-encoded scalar, in
  * `BUILT_IN_SCALARS` order.
- *
- * The one source: execution decodes client-scope arguments with these
- * (`runtime/scalar-runtime.ts`, `runtime/decimal.ts`), `@aventara/core/protocol`
- * re-exports this object, and the client generator emits each source by value into
- * the generated runtime as a regular-expression literal. Strings, not `RegExp`s,
- * so it survives JSON and can be emitted; frozen, so no consumer can rewrite a
- * grammar in place.
- *
- * A grammar is the SHAPE only. Two scalars carry one more rule each, applied where
- * they decode: a `datetime` must also round-trip `toISOString()` exactly, and a
- * `bytes` string's padded group must leave its unused bits zero ({@link
- * decodeBase64}).
  */
 export declare const scalarFormats: Readonly<{
     readonly bigint: "^-?(?:0|[1-9]\\d*)$";
@@ -32,18 +20,15 @@ export declare const scalarFormats: Readonly<{
     readonly datetime: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$";
     readonly bytes: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$";
 }>;
-/** {@link scalarFormats}, compiled once for execution's own decoding. */
+/** {@link scalarFormats}, compiled to regular expressions. */
 export declare const WIRE_SCALAR_PATTERNS: {
     readonly [S in WireEncodedScalar]: RegExp;
 };
 /** RFC 4648 base64, standard alphabet, padded: the canonical spelling of `bytes`. */
 export declare function encodeBase64(bytes: Uint8Array): string;
 /**
- * The bytes of a CANONICAL RFC 4648 base64 string; `undefined` for any other
- * string. Canonical means the grammar plus one rule the grammar cannot state: the
- * bits a padded final group does not carry must be zero, or two wire strings would
- * name one byte sequence (`"AB=="` and `"AA=="` both `[0]`). The generated
- * client's decoder applies the same rule.
+ * The bytes of a canonical RFC 4648 base64 string; `undefined` for any other
+ * string, including one whose unused padding bits are not zero.
  */
 export declare function decodeBase64(wire: string): Uint8Array | undefined;
 export {};