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

package/dist/config/framework-config.d.ts

@@ -8,33 +8,33 @@ import type { FrameworkBehaviorsConfig } from "./framework-behaviors-config.js";
 import type { FrameworkFieldsConfig } from "./framework-fields-config.js";
 import type { FrameworkRestrictionsConfig } from "./framework-restrictions-config.js";
 import type { PipelineConfig } from "./pipeline-config.js";
-/** Authoring limits remain partial until compilation resolves framework defaults. */
+/**
+ * Request limits to override; each one left out takes its default from
+ * {@link DEFAULT_CONTRACT_LIMITS}.
+ */
 export type FrameworkLimitsConfig = Partial<ContractLimits>;
 /**
- * Configuration available at root and at application/client scopes.
- *
- * `Cfg` is the authored configuration literal this scope belongs to. Under the
- * default `AnyFrameworkConfig` the effective key set degenerates to `string`, so
- * an unannotated `FrameworkScopeConfig<M>` behaves exactly as it did before.
+ * Settings available at the root and in the `application` and `client`
+ * overlays. A setting in an overlay replaces the root's for that origin;
+ * pipelines are added to the root's instead.
  */
 export type FrameworkScopeConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
+    /** Fields to add to Resources, or details to set on discovered fields. */
     readonly fields?: FrameworkFieldsConfig<M>;
+    /** Computed values and read behaviors, per Resource and field. */
     readonly behaviors?: FrameworkBehaviorsConfig<M, Cfg>;
+    /** What to hide or narrow: Resources, fields, capabilities and operations. */
     readonly restrictions?: FrameworkRestrictionsConfig<M, Cfg>;
+    /** Request limits; see {@link FrameworkLimitsConfig}. */
     readonly limits?: FrameworkLimitsConfig;
+    /** Guards, pipes, hooks, interceptors and filters run around each operation. */
     readonly pipelines?: PipelineConfig<M>;
+    /** `"none"` turns transactions off; `"interactive"` needs adapter support. */
     readonly transactions?: TransactionCapability;
 };
 /**
- * Aventara authoring configuration.
- *
- * Root properties are the root/core/default source. There is intentionally no
- * `core` namespace; `application` and `client` are scoped overlays.
- *
- * `diagnostics` is deliberately root-only and absent from
- * {@link FrameworkScopeConfig}: the framework owns the channel that reports
- * the developer's own unplanned failures, so it is neither scoped, ordered,
- * composable nor overridable.
+ * The configuration passed to `createFramework`: the adapter, the mount path,
+ * root settings, and optional `application` and `client` overlays.
  */
 export type FrameworkConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = FrameworkScopeConfig<M, Cfg> & {
     readonly entrypoint: string;

package/dist/config/framework-fields-config.d.ts

@@ -1,29 +1,36 @@
 import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { ScalarFieldCapabilities, ScalarFormat } from "../contracts/field.js";
 import type { LifecycleTrait } from "../contracts/lifecycle-trait.js";
+/** The lifecycle traits a configuration may set on a field. */
 export type FrameworkFieldLifecycleTrait = Extract<LifecycleTrait, "VIRTUAL">;
+/** The names of the Resources in adapter model `M`. */
 export type FrameworkResourceKey<M extends AdapterModel> = Extract<keyof M["resources"], string>;
+/** A scalar type or an enum of adapter model `M`, by name. */
 export type FrameworkScalarTypeRef<M extends AdapterModel> = {
     readonly scalar: Extract<keyof M["scalars"], string>;
 } | {
     readonly enum: Extract<keyof M["enums"], string>;
 };
 /**
- * Passive scalar-field authoring data applied by the Contract compiler.
- *
- * Existing adapter scalar fields remain the structural baseline. A field name
- * absent from the adapter model represents a framework-added scalar field and
- * must provide the structural leaves required by compilation.
+ * A scalar field's settings. For a discovered field, the discovered values are
+ * the baseline; a field the adapter did not discover must state `type`,
+ * `nullable` and `list`.
  */
 export type FrameworkScalarFieldConfig<M extends AdapterModel = AdapterModel> = {
+    /** The field's scalar or enum type. */
     readonly type?: FrameworkScalarTypeRef<M>;
+    /** The scalar's format name, carried in the Contract. */
     readonly format?: ScalarFormat;
+    /** Whether the field may be `null`. */
     readonly nullable?: boolean;
+    /** Whether the field holds a list of values. */
     readonly list?: boolean;
-    /** Field config owns persistence metadata only; generated/computed traits have other owners. */
+    /** Persistence traits: `"VIRTUAL"` marks a field the store does not hold. */
     readonly lifecycle?: readonly FrameworkFieldLifecycleTrait[];
+    /** The field's capabilities; see {@link ScalarFieldCapabilities}. */
     readonly capabilities?: Partial<ScalarFieldCapabilities>;
 };
+/** Field settings for one Resource, by field name. */
 export type FrameworkResourceFieldsConfig<M extends AdapterModel = AdapterModel> = Readonly<Record<string, FrameworkScalarFieldConfig<M>>>;
-/** Scalar augmentation/metadata keyed by canonical Adapter Resource identity. */
+/** Fields to add or describe, per Resource. */
 export type FrameworkFieldsConfig<M extends AdapterModel = AdapterModel> = Readonly<Partial<Record<FrameworkResourceKey<M>, FrameworkResourceFieldsConfig<M>>>>;

package/dist/config/framework-restrictions-config.d.ts

@@ -4,69 +4,54 @@ import type { PaginationCapability, ProjectionScope, RelationFilterCapability, R
 import type { AnyFrameworkConfig } from "./any-framework-config.js";
 import type { EffectiveFieldKey } from "./effective-fields.js";
 import type { FrameworkResourceKey } from "./framework-fields-config.js";
+/**
+ * `true` keeps a capability, `false` removes it, and a list keeps only the
+ * listed entries. Restrictions only narrow what the adapter offers.
+ */
 export type FrameworkCapabilitySetRestriction<T extends string> = boolean | readonly T[];
 /**
- * A restriction on a scope-qualified projection member: `select` and `include` on
- * a relation, where the capability is a POSITION list and carries no tokens at
- * all.
- *
- * Three operations, and they are three because narrowing a qualified capability is
- * not one thing:
- *
- * - `false` **denies** the capability — the member leaves the projection.
- * - a scope list **removes positions** — the member survives, reachable in fewer
- *   argument positions.
- * - `true` **restores** the baseline member, qualifier included.
- *
- * The **empty** list is the fourth operation written as a degenerate third: a
- * capability narrowed to no position is a capability that is not available, and
- * `ProjectionScopes` cannot represent an empty list, so the compiler denies the
- * member rather than emitting a second encoding of "absent".
+ * A restriction on a relation's `select` or `include` capability: `true`,
+ * `false`, or the projection positions to keep.
  */
 export type FrameworkProjectionScopeRestriction = boolean | readonly ProjectionScope[];
 /**
- * A restriction on a scope-qualified write member: `create` and `update` on a
- * relation.
- *
- * Removing a directive and removing a write position are **different narrowings**,
- * so each is authorable without restating the other. The bare directive list keeps
- * the grammar it has always had and narrows tokens only, leaving the positions the
- * baseline advertises in place; the object arm names either axis, or both.
+ * A restriction on a relation's `create` or `update` capability. A directive
+ * list narrows the directives only; the object form can also narrow the write
+ * positions (`scopes`).
  *
- * `directives: []` is NOT a denial. "Writable with no directive" and "not writable
- * during this stage" are two answers `V1006` already distinguishes, so an empty
- * directive list narrows the tokens to none and leaves the member present —
- * `scopes: []` is what denies it, for the reason
- * {@link FrameworkProjectionScopeRestriction} gives.
+ * `directives: []` leaves the relation writable with no directive;
+ * `scopes: []` or `false` makes it not writable.
  */
 export type FrameworkRelationMutationRestriction = boolean | readonly RelationMutationDirective[] | {
     readonly directives?: readonly RelationMutationDirective[];
     readonly scopes?: readonly WriteScope[];
 };
 /**
- * A restriction on a relation's scope-qualified reducer member. The write mirror is
- * {@link FrameworkRelationMutationRestriction}; the token key is the one the
- * Contract arm uses, so the restriction is written in the vocabulary of the value
- * it narrows rather than a second one.
+ * A restriction on a relation's `reducers` capability: `true`, `false`, a
+ * reducer list, or an object narrowing reducers and projection positions.
  */
 export type FrameworkRelationReducerRestriction = boolean | readonly RelationReducer[] | {
     readonly reducers?: readonly RelationReducer[];
     readonly scopes?: readonly ProjectionScope[];
 };
+/** Restrictions on a scalar field's capabilities. */
 export type FrameworkScalarCapabilityRestrictions = {
+    /** Whether the field can be selected. */
     readonly select?: boolean;
+    /** The filter operators to keep. */
     readonly filter?: FrameworkCapabilitySetRestriction<ScalarFilterOperator>;
+    /** Whether results can be ordered by the field. */
     readonly order?: boolean;
+    /** Whether ordering can place `null`s first or last. */
     readonly orderNulls?: boolean;
+    /** The directives to keep when creating. */
     readonly create?: FrameworkCapabilitySetRestriction<ScalarMutationDirective>;
+    /** The directives to keep when updating. */
     readonly update?: FrameworkCapabilitySetRestriction<ScalarMutationDirective>;
 };
 /**
- * Five of the eight members take a scope-aware restriction: exactly the five the
- * Contract carries a scope qualifier on. `filter`, `order` and `pagination` were
- * measured uniform across every operation variant, so there is no position to name
- * and a grammar that let one be named would invent a narrowing the adapter cannot
- * honour.
+ * Restrictions on a relation field's capabilities. `select`, `include`,
+ * `reducers`, `create` and `update` can also be narrowed by argument position.
  */
 export type FrameworkRelationCapabilityRestrictions = {
     readonly select?: FrameworkProjectionScopeRestriction;
@@ -78,15 +63,26 @@ export type FrameworkRelationCapabilityRestrictions = {
     readonly create?: FrameworkRelationMutationRestriction;
     readonly update?: FrameworkRelationMutationRestriction;
 };
+/** Restrictions for one scalar field. */
 export type FrameworkScalarFieldRestrictions = {
+    /** `true` hides the field. */
     readonly hidden?: boolean;
+    /** Capabilities to narrow. */
     readonly capabilities?: FrameworkScalarCapabilityRestrictions;
 };
+/** Restrictions for one relation field. */
 export type FrameworkRelationFieldRestrictions = {
+    /** `true` hides the field. */
     readonly hidden?: boolean;
+    /** Capabilities to narrow. */
     readonly capabilities?: FrameworkRelationCapabilityRestrictions;
 };
+/** Restrictions for one field: scalar or relation. */
 export type FrameworkFieldRestrictions = FrameworkScalarFieldRestrictions | FrameworkRelationFieldRestrictions;
+/**
+ * Standard operations to turn off, by family and variant: `false` removes
+ * one the adapter offers.
+ */
 export type FrameworkResourceOperationRestrictions = {
     readonly find?: {
         readonly first?: boolean;
@@ -122,40 +118,24 @@ type AdapterFieldRestrictionsFor<TField> = TField extends {
     readonly kind: "relation";
 } ? FrameworkRelationFieldRestrictions : FrameworkFieldRestrictions;
 /**
- * The restriction shape one effective field name admits. Three cases, in order.
- *
- * `string extends F` is the wide default. Under `AnyFrameworkConfig`, {@link
- * EffectiveFieldKey} degenerates to `string`, the mapped type below collapses to a
- * single index signature and no field identity survives to discriminate on.
- * Today's wide acceptance is preserved there deliberately: narrowing below the
- * resource key is opt-in, never imposed.
- *
- * An adapter-discovered name is discriminated by the model's own `kind`.
- *
- * Anything else is a name the configuration's own `fields` block added. Per the
- * target type graph an added field is an added *scalar* field — there is no
- * configuration surface that authors a relation — so the answer is {@link
- * FrameworkScalarFieldRestrictions}.
+ * The restriction shape one effective field name admits. Three cases, in
+ * order.
  */
 type FieldRestrictionsFor<M extends AdapterModel, R extends FrameworkResourceKey<M>, F extends string> = string extends F ? FrameworkFieldRestrictions : F extends AdapterFieldKey<M, R> ? AdapterFieldRestrictionsFor<M["resources"][R]["fields"][F]> : FrameworkScalarFieldRestrictions;
-/**
- * Projection policy for one Resource's fields, keyed on the single effective
- * field-key answer.
- *
- * This type used to intersect the mapped half with `Readonly<Record<string,
- * FrameworkFieldRestrictions>>`, whose index signature absorbed every field name
- * the model does not declare. The catch-all is gone: a name must be an adapter
- * field or one `Cfg` adds.
- */
+/** Restrictions for one Resource's fields, by field name. */
 export type FrameworkResourceFieldRestrictions<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = Readonly<Partial<{
     [F in EffectiveFieldKey<M, Cfg, R>]: FieldRestrictionsFor<M, R, F>;
 }>>;
+/** Restrictions for one Resource. */
 export type FrameworkResourceRestrictions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = {
+    /** `true` hides the whole Resource. */
     readonly hidden?: boolean;
+    /** Restrictions per field. */
     readonly fields?: FrameworkResourceFieldRestrictions<M, Cfg, R>;
+    /** Standard operations to turn off. */
     readonly operations?: FrameworkResourceOperationRestrictions;
 };
-/** Projection policy keyed by canonical Adapter Resource identity. */
+/** What to hide or narrow, per Resource. */
 export type FrameworkRestrictionsConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = Readonly<Partial<{
     [R in FrameworkResourceKey<M>]: FrameworkResourceRestrictions<M, Cfg, R>;
 }>>;

package/dist/config/pipeline-config.d.ts

@@ -1,32 +1,22 @@
 import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { AfterHook, BeforeHook, Filter, Guard, Interceptor, Pipe } from "../runtime/pipeline.js";
-/**
- * Pipeline registrations for one configuration scope.
- *
- * See {@link PipelineContext}.
- */
+/** Pipeline registrations for one configuration scope. See {@link PipelineContext}. */
 export type PipelineConfig<M extends AdapterModel = AdapterModel> = {
+    /** Run first; a guard returning `false` denies the operation with `A4001`. */
     readonly guards?: readonly Guard<M>[];
+    /** Run in order on the arguments; a pipe may return replacement arguments. */
     readonly pipes?: readonly Pipe<M>[];
+    /** Run just before (`before`) and after (`after`) the operation executes. */
     readonly hooks?: {
         readonly before?: readonly BeforeHook<M>[];
         readonly after?: readonly AfterHook<M>[];
     };
+    /** Wrap the operation's execution; each calls `next()` to continue. */
     readonly interceptors?: readonly Interceptor<M>[];
+    /** Turn a thrown error into a {@link FrameworkError} outcome. */
     readonly filters?: readonly Filter<M>[];
 };
-/**
- * Fully normalized pipeline registration lists after scope composition.
- *
- * Parameterizing this type would let `M` flow past `resolveFrameworkConfig` into a
- * runtime that cannot honour it, and would force a cast at the context factory to
- * manufacture a literal the request does not carry.
- *
- * Unlike `behaviors`, erasing here costs nothing at the type level: `M` occurs in
- * these callbacks *only* in parameter position, never as a mapped-type key, so
- * `PipelineConfig<M>` is accepted where the erased form is required and
- * `resolvePipelines` composes the authored lists with no cast at all.
- */
+/** The pipelines that run for one origin, root and overlay combined. */
 export type ResolvedPipelineConfig = {
     readonly guards: readonly Guard[];
     readonly pipes: readonly Pipe[];

package/dist/contracts/capability.d.ts

@@ -1,64 +1,28 @@
+/** The operators a scalar field can be filtered with. */
 export type ScalarFilterOperator = "equals" | "not" | "in" | "notIn" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith" | "mode" | "has" | "hasEvery" | "hasSome" | "isEmpty" | "path" | "stringContains" | "stringStartsWith" | "stringEndsWith" | "arrayContains" | "arrayStartsWith" | "arrayEndsWith";
+/** What an update can do to a scalar value besides setting it. */
 export type ScalarMutationDirective = "$increment" | "$decrement" | "$multiply" | "$divide" | "$push" | "$unset";
+/** How a relation can be filtered on. */
 export type RelationFilterCapability = "nested" | "match" | "null" | "some" | "every" | "none";
+/** What a write can do to a relation: `$create`, `$connect` and the rest. */
 export type RelationMutationDirective = "$create" | "$connect" | "$connectOrCreate" | "$disconnect" | "$set" | "$update" | "$delete" | "$upsert";
+/** How a list of related rows can be paginated. */
 export type PaginationCapability = "limit" | "offset" | "cursor";
+/** What a projection can compute over a to-many relation. */
 export type RelationReducer = "$count";
 /**
- * Where a projected field may be asked for: the kind of argument POSITION a
- * projection sits in, not the operation that carries it. A variant states the
- * position its projection arguments sit in (`OperationScopes`); a field states the
- * positions it is projectable in. The axis is closed at two because two is what
- * both pilot engines answer — a third position would have to be measured, not
- * supposed.
- *
- * **A scope qualifies the TOP LEVEL of a projection only. It does not narrow
- * recursively.** Measured at runtime on both pilot engines, 2026-10-03, not
- * inferred from types: a bulk-returning write accepted `include: { <owned to-one>:
- * { include: { <to-many>: true } } }` and populated the rows (the nested to-many
- * returned its 3 rows and a full reducer object), while the SAME to-many asked for
- * at depth 1 was refused outright. The reason is visible in the generated types: a
- * bulk projection types an admitted relation as the *unrestricted* projection
- * argument, so the full surface returns one level in.
- *
- * A reader who assumes a scope narrows recursively will write a rule that refuses
- * what the ORM accepts.
- *
- * # Why the axis is a value and the union is derived from it
- *
- * The axis is written down exactly once, as `LIFECYCLE_TRAITS` and
- * `TRANSACTION_CAPABILITIES` are, because one reader needs its **cardinality** at
- * runtime and not merely its member names: a scope list naming every member of the
- * axis says exactly what the unqualified arm says, so the canonicalizer collapses
- * it. That reader asks "does this list name every member of the axis?" against
- * this array. A hardcoded two would answer *yes* for a two-of-three list the day a
- * third position is measured, which widens every Contract carrying it and nothing
- * downstream can tell — so the derivation is load-bearing, not tidiness.
- *
- * Declaration order is registry order and the canonicalizer orders scope lists by
- * it, the way it orders `pagination`.
+ * Where a projected field may be asked for: the kind of argument POSITION a projection
+ * sits in, not the operation that carries it. A variant states the position its
+ * projection arguments sit in (`OperationScopes`); a field states the positions it is
+ * projectable in.
  */
 export declare const PROJECTION_SCOPES: readonly ["record", "bulkWrite"];
 /** @see PROJECTION_SCOPES — the axis this union is derived from. */
 export type ProjectionScope = (typeof PROJECTION_SCOPES)[number];
 /**
- * Where a field may be written: the kind of argument POSITION a write sits in, not
- * the operation that carries it. The mirror of {@link ProjectionScope} on the
- * mutation axis, and a separate union because the two axes are measured separately
- * — an adapter may narrow one without narrowing the other.
- *
- * **A scope qualifies the TOP LEVEL of a write argument only. It does not narrow
- * recursively**, for the same reason {@link ProjectionScope} does not: past an
- * admitted entry the unrestricted surface returns. On both pilot engines
- * `"bulkWrite"` admits no nested write at all, so today the rule has no admitted
- * top-level entry to apply beneath — it is stated because an adapter that admits
- * one must not then be narrowed a second level down, which would refuse what the
- * ORM accepts.
- *
- * A value for the same reason {@link PROJECTION_SCOPES} is one, and a **separate**
- * array because the two axes are separate: a write scope list that names every
- * write position is degenerate, a write scope list that happens to have as many
- * members as the projection axis is not.
+ * Where a field may be written: the kind of argument POSITION a write sits in,
+ * not the operation that carries it. The write counterpart of
+ * {@link ProjectionScope}.
  */
 export declare const WRITE_SCOPES: readonly ["nested", "bulkWrite"];
 /** @see WRITE_SCOPES — the axis this union is derived from. */

package/dist/contracts/client-contract-structure.validator.d.ts

@@ -1,52 +1,9 @@
 import type { ClientContract } from "./contract.js";
 /**
- * # Why core owns it
- *
- * The canonicalizer reads Contract members without validating them (it owns
- * ordering, not validation), so a body with a valid envelope and a malformed
- * member — `resources: { Spell: 5 }` — reaches it and throws a plain `TypeError`.
- * The structure of a ClientContract is a core fact, so its check is core's, and
- * every reader of an untrusted Contract (the client generator today, a host
- * asserting what it serves tomorrow) asks this one function.
- *
- * # One source of truth: the schema IS the type
- *
- * {@link CLIENT_CONTRACT_STRUCTURE} is a passive description, and {@link
- * Structured} decodes it into a TypeScript type. That decoded type must be
- * `ClientContract` exactly, in both directions:
- *
- * - **schema → type** is enforced here, at build time: the accepted arm hands back
- *   the decoded value as a `ClientContract` with no cast, so a schema that admits
- *   something the type does not fails to compile.
- * - **type → schema** is enforced by
- *   `client-contract-structure.validator.test-d.ts`: a schema that is stricter
- *   than the type — a vocabulary token missed, an optional member written as
- *   required — fails the type test.
- *
- * So a member added to, removed from or re-typed in core's ClientContract types
- * breaks the build or the type test until this schema says the same thing.
- *
- * # Where the line is
- *
- * The line is the TYPE, judged at the erased `ClientContract`: what the type
- * admits is accepted, what it rules out is refused. Two consequences are
- * deliberate:
- *
- * - **References are not structure.** At the erased type a relation `target`, a
- *   field's `{ scalar }`/`{ enum }` and an identifier's field keys are `string`,
- *   so a dangling reference passes. Referential consistency is a separate,
- *   semantic check.
- *
- * One rule is stricter than the type, because no TypeScript type can state it:
- * **an enum's values are distinct.** `readonly string[]` admits a repeat, but an
- * enum with one names a member twice — the generated client's `as const` object
- * would declare one key twice (TS1117) — so a repeat is refused at the second
- * occurrence, naming the first. The list node carries it as `unique`, which {@link
- * Structured} ignores, so the decoded type is still `ClientContract` exactly.
- * Every reader judges it here, once, rather than each re-checking it.
- *
- * The validator reads every member it judges and never throws on any input: a
- * value that is not JSON at all is reported, not crashed on.
+ * Whether an untrusted value is a `ClientContract`: every member present, of its JSON
+ * kind, inside its closed vocabulary, and nothing else. An enum's values must be
+ * distinct. Reads every member it judges and never throws on any input; a value that
+ * is not JSON at all is reported.
  */
 /** A literal a closed vocabulary can hold. */
 type Literal = string | number | boolean;
@@ -1103,12 +1060,9 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
     readonly optional: Record<never, never>;
 };
 /**
- * The answer. A refusal names the first defect found, as a `path` in the
- * JSONPath form `CanonicalJsonError` already uses (`$.resources.Spell`) and a
- * `message` clause that begins with that path in quotes.
- *
- * The specification allocates no error code to a malformed ClientContract — the
- * A/V codes are request outcomes, not generator failures — so none is invented.
+ * The answer of {@link validateClientContractStructure}. A refusal names the
+ * first defect found, as a `path` in JSONPath form (`$.resources.Spell`) and
+ * a `message` that begins with that path in quotes.
  */
 export type ClientContractStructureVerdict = {
     readonly valid: true;

package/dist/contracts/contract-canonicalizer.d.ts

@@ -1,13 +1,11 @@
 import type { Contract } from "./contract.js";
 /**
- * Framework-owned rejection of a value JCS cannot represent. It extends
- * `TypeError` and keeps its inherited `name`, so existing `TypeError`
- * consumers and error text are unchanged, while callers that must attribute
- * a canonicalization failure to its input can recognize this class exactly.
+ * Thrown when a value cannot be written as canonical JSON (RFC 8785). It is a
+ * `TypeError`.
  */
 export declare class CanonicalJsonError extends TypeError {
 }
-/** RFC 8785/JCS-compatible canonical encoding for JSON-safe Aventara data. */
+/** Canonical JSON (RFC 8785) for a JSON-safe value. */
 export declare function canonicalizeJson(value: unknown): string;
-/** Canonical semantic representation used for deterministic Contract output. */
+/** The Contract as canonical JSON (RFC 8785): the same bytes for the same Contract. */
 export declare function canonicalizeContract<C extends Contract>(contract: C): string;

package/dist/contracts/contract-hash.d.ts

@@ -1,10 +1,11 @@
 import type { ClientContract } from "./contract.js";
 import type { ContractHash, ContractProtocol } from "./contract-protocol.js";
+/** A ClientContract whose `protocol` does not carry the hash yet. */
 export type ClientContractHashInput = Omit<ClientContract, "protocol"> & {
     readonly protocol: ContractProtocol;
 };
 export declare function createClientContractHashInput(contract: ClientContract | ClientContractHashInput): ClientContractHashInput;
-/** Compute exact ClientContract identity with protocol.hash excluded. */
+/** Computes a ClientContract's `sha256:` hash, ignoring `protocol.hash` itself. */
 export declare function computeClientContractHash(contract: ClientContract | ClientContractHashInput): Promise<ContractHash>;
-/** Recompute and compare the advertised ClientContract identity. */
+/** Whether a ClientContract's `protocol.hash` matches its content. */
 export declare function verifyClientContractHash(contract: ClientContract): Promise<boolean>;

package/dist/contracts/contract-limits.d.ts

@@ -1,11 +1,17 @@
+/** The request limits a Contract enforces. */
 export type ContractLimits = {
+    /** The largest request body accepted, in bytes. */
     readonly maxRequestBytes: number;
+    /** How deeply arguments may nest. */
     readonly maxNestingDepth: number;
+    /** The largest `limit` a list read may ask for. */
     readonly maxListLimit: number;
+    /** The most operations one transaction may hold. */
     readonly maxTransactionOperations: number;
+    /** The most boolean and filter nodes one request may hold. */
     readonly maxBooleanNodes: number;
 };
-/** Conservative v1 framework defaults resolved before scoped limit overrides. */
+/** The limits in force when the configuration sets none. */
 export declare const DEFAULT_CONTRACT_LIMITS: {
     readonly maxRequestBytes: 1048576;
     readonly maxNestingDepth: 12;

package/dist/contracts/contract-protocol.d.ts

@@ -1,18 +1,17 @@
 /**
- * Aventara's external communication protocol version.
- *
- * This is intentionally independent from framework/package versions and from
- * application-specific Contract changes. Resource/field/configuration/database
- * changes are identified by the ClientContract hash and do not require a
- * protocol-version bump by themselves. Increment this value only when a
- * breaking change makes previous-protocol clients unable to correctly parse or
- * interpret Aventara's external protocol semantics.
+ * The version of Aventara's wire protocol. It changes only when older
+ * clients can no longer read the protocol correctly; schema and
+ * configuration changes are tracked by the ClientContract hash instead.
  */
 export declare const AVENTARA_PROTOCOL_VERSION: 1;
+/** A Contract hash: `sha256:` followed by the hex digest. */
 export type ContractHash = `sha256:${string}`;
+/** The protocol a Contract is written for. */
 export type ContractProtocol = {
+    /** The protocol version; see {@link AVENTARA_PROTOCOL_VERSION}. */
     readonly version: typeof AVENTARA_PROTOCOL_VERSION;
 };
+/** A ClientContract's `protocol`: the protocol version and the Contract hash. */
 export type ClientContractProtocol = ContractProtocol & {
     readonly hash: ContractHash;
 };

package/dist/contracts/contract.d.ts

@@ -4,21 +4,30 @@ import type { EnumDefinition } from "./enum-definition.js";
 import type { Resource } from "./resource.js";
 import type { ScalarRegistry } from "./scalar.js";
 import type { TransactionCapability } from "./transaction-capability.js";
-/** Passive semantic description shared by every Aventara Contract form. */
+/** What every Contract describes: scalars, enums, Resources, limits and transactions. */
 export interface Contract {
+    /** The scalar types available. */
     readonly scalars: ScalarRegistry;
+    /** The enums, by name. */
     readonly enums: Readonly<Record<string, EnumDefinition>>;
+    /** The Resources, by name. */
     readonly resources: Readonly<Record<string, Resource<this>>>;
+    /** The request limits in force. */
     readonly limits: ContractLimits;
+    /** Whether interactive transactions are available. */
     readonly transactions: TransactionCapability;
 }
-/** Root-scope Contract form. Distinction becomes behavioral during compilation. */
+/** The Contract compiled from the root configuration. */
 export interface CoreContract extends Contract {
 }
-/** Same-process application-operation Contract form. */
+/** The Contract in-process calls run under (`framework.application`). */
 export interface ApplicationContract extends Contract {
 }
-/** Remotely introspectable external-consumer Contract form with exact identity. */
+/**
+ * The Contract remote clients run under, published at `GET /_contract` and
+ * identified by its hash.
+ */
 export interface ClientContract extends Contract {
+    /** The protocol version and this Contract's hash. */
     readonly protocol: ClientContractProtocol;
 }

package/dist/contracts/enum-definition.d.ts

@@ -1,3 +1,5 @@
+/** An enum: its allowed values. */
 export type EnumDefinition = {
+    /** The allowed values, in declaration order. */
     readonly values: readonly string[];
 };