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

package/dist/adapters/adapter-discovery-diagnostic.d.ts

@@ -1,4 +1,6 @@
+/** Codes of {@link AdapterDiscoveryDiagnostic}. */
 export type AdapterDiscoveryDiagnosticCode = "DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH";
+/** A problem found in what the adapter discovered, reported at framework construction. */
 export type AdapterDiscoveryDiagnostic = {
     readonly code: AdapterDiscoveryDiagnosticCode;
     readonly path: "adapter.transactions";

package/dist/adapters/adapter-field.d.ts

@@ -3,13 +3,7 @@ import type { LifecycleTrait } from "../contracts/lifecycle-trait.js";
 import type { AdapterModel } from "./adapter-model.js";
 /** Provider-observable lifecycle facts available during adapter discovery. */
 export type AdapterLifecycleTrait = Extract<LifecycleTrait, "DEFAULTED" | "GENERATED_ON_CREATE" | "GENERATED_ON_UPDATE">;
-/**
- * Scalar-shaped provider field expressed only in Aventara vocabulary.
- *
- * Scalar capabilities carry no scope qualifier, measured and not assumed: all six
- * members are uniform across every operation variant on both pilot engines, so a
- * discoverer has nothing per-position to answer here.
- */
+/** Scalar-shaped provider field expressed only in Aventara vocabulary. */
 export type AdapterScalarField<M extends AdapterModel> = {
     readonly kind: "scalar";
     readonly type: {
@@ -23,25 +17,7 @@ export type AdapterScalarField<M extends AdapterModel> = {
     readonly lifecycle: readonly AdapterLifecycleTrait[];
     readonly capabilities: ScalarFieldCapabilities;
 };
-/**
- * Provider relation edge; the target AdapterResource owns object shape.
- *
- * The capabilities are the Contract's own {@link RelationFieldCapabilities}, scope
- * qualifier included, and that sharing is the point: the ADAPTER is the only party
- * that can measure which argument positions a relation is reachable in, because
- * the answer depends on which provider call each operation variant is routed to.
- * Core tabulating it would be a tabulated provider fact and would be wrong for the
- * next adapter.
- *
- * The qualifier is OPTIONAL at this boundary, as it is in the Contract: an adapter
- * that has not measured the axis states the unqualified answer and is believed,
- * which is what keeps a surface that predates the measurement meaningful rather
- * than silently narrowed.
- *
- * **A scope qualifies the TOP LEVEL of an argument only** — the measurement and
- * the reason are recorded on `ProjectionScope`, and a discoverer that narrows
- * recursively would advertise less than the provider accepts.
- */
+/** A discovered relation field; the `target` Resource describes the related row. */
 export type AdapterRelationField<M extends AdapterModel> = {
     readonly kind: "relation";
     readonly target: Extract<keyof M["resources"], string>;
@@ -49,4 +25,5 @@ export type AdapterRelationField<M extends AdapterModel> = {
     readonly nullable: boolean;
     readonly capabilities: RelationFieldCapabilities;
 };
+/** One field the adapter discovered: a scalar or a relation. */
 export type AdapterField<M extends AdapterModel> = AdapterScalarField<M> | AdapterRelationField<M>;

package/dist/adapters/adapter-identifier.d.ts

@@ -1,16 +1,6 @@
 import type { AdapterField } from "./adapter-field.js";
 import type { AdapterModel } from "./adapter-model.js";
-/**
- * Keys of `TFields` whose discovered 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 `AdapterFieldMap` default every key maps to the whole
- * `AdapterField` union, which is not a subtype of the scalar branch, so the
- * bare form collapses to `never` and makes `AdapterIdentifier` uninhabitable.
- * `Extract` selects the scalar branch out of the union instead, so a key is
- * kept unless it is provably relation-only.
- */
+/** Keys of `TFields` whose discovered field can be scalar-shaped. */
 export type AdapterScalarFieldKey<TFields extends Readonly<Record<string, AdapterField<AdapterModel>>>> = Extract<{
     [K in keyof TFields]: [
         Extract<TFields[K], {

package/dist/adapters/adapter-model.d.ts

@@ -7,8 +7,12 @@ import type { AdapterResource } from "./adapter-resource.js";
  * Contract compilation is applied.
  */
 export interface AdapterModel {
+    /** The scalar types the data source supports. */
     readonly scalars: ScalarRegistry;
+    /** The enums the data source declares, by name. */
     readonly enums: Readonly<Record<string, EnumDefinition>>;
+    /** The discovered Resources, by name. */
     readonly resources: Readonly<Record<string, AdapterResource<this>>>;
+    /** Whether the adapter can run interactive transactions. */
     readonly transactions: TransactionCapability;
 }

package/dist/adapters/adapter-operation-executor.interface.d.ts

@@ -1,6 +1,10 @@
 import type { AdapterModel } from "./adapter-model.js";
 import type { AdapterOperation } from "./adapter-operation.js";
-/** Small execution seam usable both directly and inside provider transactions. */
+/**
+ * Executes one operation against the provider, directly or inside a provider
+ * transaction.
+ */
 export interface AdapterOperationExecutor<M extends AdapterModel = AdapterModel> {
+    /** Runs one validated operation and resolves its raw result. */
     execute(operation: AdapterOperation<M>): Promise<unknown>;
 }

package/dist/adapters/adapter-resource.d.ts

@@ -2,40 +2,19 @@ import type { ResourceOperations } from "../contracts/resource-operations.js";
 import type { AdapterField } from "./adapter-field.js";
 import type { AdapterIdentifier } from "./adapter-identifier.js";
 import type { AdapterModel } from "./adapter-model.js";
+/** A discovered Resource's fields, by name. */
 export type AdapterFieldMap<M extends AdapterModel> = Readonly<Record<string, AdapterField<M>>>;
 /**
- * The field names the adapter discovered for `R`.
- *
- * This is the lower layer of `EffectiveFieldKey`, in
- * `config/effective-fields.ts`: everything the provider already knows about,
- * before any configuration is applied. Named in prose rather than with a
- * `{@link}` because a resolvable link would need an import, and `adapters/`
- * must not reach into `config/`.
- *
- * `R`'s constraint is written out rather than imported as
- * `FrameworkResourceKey<M>` — the identical type — because `adapters/` owns
- * the Base layer and must not depend on `config/`.
+ * The field names the adapter discovered for Resource `R`, before any
+ * configuration adds to them.
  */
 export type AdapterFieldKey<M extends AdapterModel, R extends Extract<keyof M["resources"], string>> = Extract<keyof M["resources"][R]["fields"], string>;
-/**
- * Provider-discovered facts for one Aventara Resource candidate.
- *
- * `TFields` is never supplied by a caller — every in-repo site writes
- * `AdapterResource<M>` — but it is **load-bearing and must not be inlined**. It is
- * the indirection that keeps `M` out of this type's body.
- *
- * `AdapterField<M>` is invariant in `M` (it reads `keyof M["scalars"]` and `keyof
- * M["resources"]`). If `M` reached the body, `AdapterResource` would acquire an
- * invariant variance marker, and every concrete model would stop satisfying the
- * self-typed `AdapterModel.resources: Readonly<Record<string,
- * AdapterResource<this>>>` constraint. Measured: 43 type errors across the adapter
- * and index type tests, and identically 43 whether the parameter is deleted or
- * merely bypassed — so it is the body occurrence that matters, not the arity.
- *
- * Deleting it is not a cleanup.
- */
+/** Provider-discovered facts for one Aventara Resource candidate. */
 export type AdapterResource<M extends AdapterModel, TFields extends AdapterFieldMap<M> = AdapterFieldMap<M>> = {
+    /** The Resource's fields, by name. */
     readonly fields: TFields;
+    /** The field tuples that identify at most one row. */
     readonly identifiers: readonly AdapterIdentifier<TFields>[];
+    /** The standard operations the data source can run for this Resource. */
     readonly operations: ResourceOperations;
 };

package/dist/adapters/adapter.interface.d.ts

@@ -5,47 +5,42 @@ import type { AdapterOperationExecutor } from "./adapter-operation-executor.inte
 /** Provider-specific implementation of Aventara discovery and execution. */
 export interface Adapter<M extends AdapterModel = AdapterModel> extends AdapterOperationExecutor<M> {
     /**
-     * Canonical provider-discovery facts, held by the adapter and read
-     * synchronously at framework construction. Discovery is a property, not a
-     * call: the model is a settled fact of the constructed adapter, so it
-     * cannot fail, change, or be observed twice during construction.
+     * What the adapter discovered about the data source, in Aventara's vocabulary.
+     * Read once, synchronously, when the framework is constructed.
      */
     readonly model: M;
     /**
      * Optional referential actions: for each Resource that holds a reference,
-     * what deleting a referenced row does to its rows, in Aventara's words
-     * (`runtime/referential-action.ts`). Read once at framework construction,
-     * like `model`, and never part of a Contract or its hash.
+     * what deleting a referenced row does to its rows. Read once when the
+     * framework is constructed; never part of a Contract or its hash.
      *
-     * Direction, because getting it backwards is silent: an edge listed under
-     * Resource `R` says **deleting a `target` row does `onDelete` to rows of
-     * `R`**.
+     * An edge listed under Resource `R` says **deleting a `target` row does
+     * `onDelete` to rows of `R`**.
      *
-     * Optional so an Adapter that cannot state them is believed: core then plans
-     * no cascade, and a transaction plan is never refused for one (`V1019`).
+     * When absent, no cascade is planned and no transaction plan is refused
+     * because of one (`V1019`).
      */
     readonly referentialActions?: ReferentialActionTable;
     /**
      * Optional create requirements: for each Resource, the values its store
-     * cannot create a row without, in Aventara's words
-     * (`runtime/create-requirement.ts`). Read once at framework construction,
-     * like `model`, and never part of a Contract or its hash.
+     * cannot create a row without. Read once when the framework is constructed;
+     * never part of a Contract or its hash.
      *
-     * Optional so an Adapter that cannot state them is believed: core then checks
-     * nothing, and a missing value reaches the store as before.
+     * When absent, creates are not checked for missing values before they reach
+     * the store.
      */
     readonly createRequirements?: CreateRequirementTable;
     /**
-     * Optional callback transaction capability, required exactly when the discovered
-     * model declares `transactions: "interactive"`. The callback receives only a
-     * transaction-scoped operation executor, never the provider client itself, and
-     * every operation of a plan executes through it.
+     * Optional callback transaction capability, required exactly when the
+     * discovered model declares `transactions: "interactive"`. The callback
+     * receives only a transaction-scoped operation executor, never the provider
+     * client itself, and every operation of a plan executes through it.
      *
-     * The implementation MUST reject with the exact value `work` threw — by identity,
-     * never a wrapper — and MUST NOT resolve after `work` rejected; rollback is
-     * implied by that rejection. Framework guards, pipes, hooks and interceptors of
-     * every plan operation run inside `work` while the provider transaction is open,
-     * so they must not perform network I/O or unrelated slow work.
+     * The implementation must reject with the exact value `work` threw — by identity,
+     * never a wrapper — and must not resolve after `work` rejected; rollback is
+     * implied by that rejection. Guards, pipes, hooks and interceptors of every plan
+     * operation run inside `work` while the provider transaction is open, so they must
+     * not perform network I/O or unrelated slow work.
      */
     transaction?<T>(work: (executor: AdapterOperationExecutor<M>) => Promise<T>): Promise<T>;
 }

package/dist/compiler/contract-compiler-diagnostic.d.ts

@@ -1,3 +1,4 @@
+/** Codes of {@link ContractCompilerDiagnostic}. */
 export type ContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMPILER_UNKNOWN_FIELD" | "COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED" | "COMPILER_INCOMPLETE_FIELD" | "COMPILER_STRUCTURAL_FIELD_OVERRIDE" | "COMPILER_MISSING_SCALAR" | "COMPILER_MISSING_ENUM" | "COMPILER_DANGLING_RELATION" | "COMPILER_UNAVAILABLE_OPERATION" | "COMPILER_UNAVAILABLE_CAPABILITY" | "COMPILER_INVALID_LIFECYCLE" | "COMPILER_MISSING_READ_BEHAVIOR" | "COMPILER_INVALID_BEHAVIOR_DEPENDENCY"
 /**
  * The finished, hashed client projection is not a structurally valid
@@ -6,6 +7,7 @@ export type ContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMP
  * (`$.enums.status.values[1]`).
  */
  | "COMPILER_INVALID_CLIENT_CONTRACT";
+/** One reason a configuration could not be compiled into Contracts. */
 export type ContractCompilerDiagnostic = {
     readonly code: ContractCompilerDiagnosticCode;
     readonly path: string;

package/dist/compiler/contract.compiler.d.ts

@@ -2,11 +2,16 @@ import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { ResolvedFrameworkConfig } from "../config/config.resolver.js";
 import type { ApplicationContract, ClientContract, CoreContract } from "../contracts/contract.js";
 import type { ContractCompilerDiagnostic } from "./contract-compiler-diagnostic.js";
+/** The Core, Application and Client Contracts compiled from one configuration. */
 export type FrameworkContracts = {
     readonly core: CoreContract;
     readonly application: ApplicationContract;
     readonly client: ClientContract;
 };
+/**
+ * The result of {@link compileContracts}: the three Contracts, or the
+ * diagnostics that stopped compilation.
+ */
 export type ContractCompilationResult = {
     readonly ok: true;
     readonly contracts: FrameworkContracts;
@@ -16,28 +21,12 @@ export type ContractCompilationResult = {
 };
 /**
  * Whether writing `configured` VERBATIM as capability member `key` would advertise
- * something `baseline` does not — the question the `fields` walk asks before it
- * copies a value onto an adapter field.
- *
- * Answered on the member's AXIS, off the same `satisfies`-pinned table the
- * restriction walk and the output gate read, and the baseline is read through the
- * shape's own owners: {@link holdsAt} for a position list, the `…At` readers for a
- * scope-qualified token arm. Never off the runtime shape of the value: an
- * object-shaped arm used to match no branch and pass unexamined, and `true` was
- * compared to the baseline with `!== true`, which reads a qualified baseline as
- * *not advertised* even where it holds in every position.
- *
- * The unqualified forms keep their meaning: `true` and a bare token list claim
- * every position on the axis, so either one over a qualified baseline is an
- * addition — writing it verbatim would widen the member.
- *
- * A key no axis covers, and a value its axis does not admit, are not additions;
- * they are unrepresentable, and the output gate ({@link
- * validateCapabilityRepresentation}) is the one place that says so. So is a
- * position off the axis.
- *
- * Exported for its unit test only; it is not part of the package surface.
+ * something `baseline` does not — the question the `fields` walk asks before it copies
+ * a value onto an adapter field.
  */
 export declare function capabilityAddsBaseline(fieldKind: "scalar" | "relation", baseline: Readonly<Record<string, unknown>>, key: string, configured: unknown): boolean;
-/** Compile Core first, then derive Application and Client from the Core compilation lineage. */
+/**
+ * Compiles the Core Contract from the adapter model and the root
+ * configuration, then the Application and Client Contracts from it.
+ */
 export declare function compileContracts<M extends AdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;

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

@@ -1,11 +1,4 @@
-/**
- * A `fields` block whose resource and field names are both unconstrained.
- *
- * The `undefined` in the value position is required, not incidental: under
- * `exactOptionalPropertyTypes` a real `fields` block is a `Partial` record,
- * so its values include `undefined` and it would not otherwise be assignable
- * to the widest block.
- */
+/** A `fields` block whose resource and field names are both unconstrained. */
 export type AnyFieldsBlock = Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
 /** The widest scope overlay: a `fields` block, and anything else. */
 export type AnyScopeConfig = {
@@ -13,24 +6,10 @@ export type AnyScopeConfig = {
     readonly fields?: AnyFieldsBlock;
 };
 /**
- * The widest authoring configuration: every resource admits every field name.
- *
- * This is the default argument of the `Cfg` parameter threaded through
- * `FrameworkScopeConfig`, `FrameworkConfig`, `Framework` and
- * `createFramework`. Because it constrains nothing, a `FrameworkConfig<M>`
- * written without a `Cfg` argument behaves exactly as it did before `Cfg`
- * existed: narrowing below the resource key is opt-in, never imposed.
- *
- * `Cfg` is the authored configuration literal itself, not a shape the
- * framework validates. Its only job is to carry the field names the
- * configuration adds — at the root layer and at each scope overlay — so that
- * a resource's effective field-key set is computable from the adapter model
- * plus the configuration alone, and never from a compiled Contract.
- *
- * The index signature is what makes "widest" true. Without it this is a weak
- * type, and a configuration that happens to declare no `fields`,
- * `application` or `client` would have no property in common with it and be
- * rejected — the opposite of the intended default.
+ * The widest configuration type: every resource admits every field name. It
+ * is the default `Cfg` of `FrameworkConfig`, `Framework` and
+ * `createFramework`; pass your own configuration's type instead to get field
+ * names checked.
  */
 export type AnyFrameworkConfig = {
     readonly [key: string]: unknown;

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

@@ -1,4 +1,6 @@
+/** Codes of {@link ConfigDiagnostic}. */
 export type ConfigDiagnosticCode = "CONFIG_REQUIRED" | "CONFIG_UNKNOWN_PROPERTY" | "CONFIG_INVALID_TYPE" | "CONFIG_INVALID_VALUE";
+/** One problem found in a configuration, at its path. */
 export type ConfigDiagnostic = {
     readonly code: ConfigDiagnosticCode;
     readonly path: string;

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

@@ -1,25 +1,12 @@
 /**
- * One layer of the configuration tree the framework is built on: `root` is the
- * configuration's own top level and compiles to the Core Contract; `application`
- * and `client` are the overlays resolved on top of it and compile to the
- * Application and Client Contracts.
- *
- * The one source of truth for the layer set. {@link RequestOrigin} is derived
- * from it rather than declared beside it, so the two cannot drift.
- *
- * Deliberately not named `…Scope`: that word already carries several unrelated
- * meanings in this package (the framework scope configuration, the pipeline
- * `scope`, and the capability positions `ProjectionScope`/`WriteScope`), and a
- * layer of the configuration tree is none of them.
+ * One layer of the configuration: `root` is the configuration's own top level
+ * and compiles to the Core Contract; `application` and `client` are overlays
+ * on top of it and compile to the Application and Client Contracts.
  */
 export type ConfigLayer = "root" | "application" | "client";
 /**
- * The layers a request can originate at: every {@link ConfigLayer} except
- * `root`. `root` is a real layer for the compiler — the Core Contract every
- * other layer derives from — but no request is ever made against it, so it is
- * not an origin.
- *
- * It is also the set of overlays a configuration may declare, because each
- * origin sees exactly the root layer plus its own overlay.
+ * The layers a request can come from: `application` (in-process calls) or
+ * `client` (remote calls). Each sees the root configuration plus its own
+ * overlay.
  */
 export type RequestOrigin = Exclude<ConfigLayer, "root">;

package/dist/config/config.resolver.d.ts

@@ -7,33 +7,25 @@ import type { FrameworkConfig, FrameworkLimitsConfig } from "./framework-config.
 import type { FrameworkFieldsConfig } from "./framework-fields-config.js";
 import type { FrameworkRestrictionsConfig } from "./framework-restrictions-config.js";
 import type { ResolvedPipelineConfig } from "./pipeline-config.js";
+/** One resolved layer of the configuration: root, application or client. */
 export type ResolvedFrameworkScopeConfig<M extends AdapterModel = AdapterModel> = {
     readonly fields: FrameworkFieldsConfig<M> | undefined;
-    /**
-     * The **erased** behaviors view, deliberately not `FrameworkBehaviorsConfig<M>`.
-     *
-     * A compute context carries `resource: R`, so a behavior bound to one
-     * Resource is a callback that accepts only that Resource's name. That makes
-     * `FrameworkBehaviorsConfig<M>` contravariant in the Resource key and *not*
-     * a subtype of the widest instantiation — correctly so. The runtime dispatches
-     * by string key and can never recover which literal it holds, so it consumes
-     * behaviors erased, exactly as it consumes the compiled Contract: narrowing is
-     * an authoring-time affordance, and resolution is the boundary where it ends.
-     */
+    /** The behaviors configuration, with Resource and field keys as plain strings. */
     readonly behaviors: FrameworkBehaviorsConfig | undefined;
     readonly restrictions: FrameworkRestrictionsConfig<M> | undefined;
     readonly limits: FrameworkLimitsConfig | undefined;
     readonly pipelines: ResolvedPipelineConfig;
     readonly transactions: TransactionCapability | undefined;
 };
+/** A configuration after defaults and overlays are resolved, before compilation. */
 export type ResolvedFrameworkConfig<M extends AdapterModel = AdapterModel> = {
     /**
-     * The mount path in its canonical form: `""` at the root, otherwise `/seg(/seg)*`.
-     * Normalized once, here; every reader sees this.
+     * The mount path in its canonical form: `""` at the root, otherwise
+     * `/seg(/seg)*`.
      */
     readonly entrypoint: string;
     readonly adapter: Adapter<M>;
-    /** Root-only, never scoped: the framework owns this channel. */
+    /** The diagnostics sink, from the root configuration only. */
     readonly diagnostics: FrameworkDiagnosticsSink | undefined;
     readonly root: ResolvedFrameworkScopeConfig<M>;
     readonly application: ResolvedFrameworkScopeConfig<M>;

package/dist/config/config.validator.d.ts

@@ -1,9 +1,12 @@
 import type { ConfigDiagnostic } from "./config-diagnostic.js";
 /**
  * The refusal of an entrypoint whose mount path is not canonical, from the
- * normalizer's message: it names the defect and the rule — never the value, which
- * may carry credentials.
+ * normalizer's message: it names the defect and the rule — never the value, which may
+ * carry credentials.
  */
 export declare function entrypointRefusalDiagnostic(message: string): ConfigDiagnostic;
-/** Validate framework-owned authoring structure; later semantic leaves remain opaque. */
+/**
+ * Checks the structure of a configuration object and reports each problem as
+ * a {@link ConfigDiagnostic}.
+ */
 export declare function validateFrameworkConfig(value: unknown): readonly ConfigDiagnostic[];

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

@@ -2,55 +2,26 @@ import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { AdapterFieldKey } from "../adapters/adapter-resource.js";
 import type { FrameworkResourceKey, FrameworkScalarFieldConfig, FrameworkScalarTypeRef } from "./framework-fields-config.js";
 /**
- * What an author may still say about a field the adapter already discovered.
- *
- * Everything in {@link FrameworkScalarFieldConfig} except `type`: the adapter
- * owns a discovered field's scalar/enum identity, so restating it here would
- * create a second source of truth for a fact discovery already settled.
- * `type?: never` rather than an omission so the rejection is a pointed
- * assignability error at the offending property, not a whole-object one.
+ * What a configuration may say about a field the adapter already discovered:
+ * everything in {@link FrameworkScalarFieldConfig} except `type`.
  */
 export type KnownScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type"> & {
     readonly type?: never;
 };
 /**
- * A scalar field the configuration adds, which the adapter never discovered.
- *
- * Nothing upstream can supply the structural leaves for a name that exists
- * nowhere in the provider, so `type`, `nullable` and `list` are required
- * here while they stay optional on the augmentation shape.
+ * A scalar field the configuration adds, which the adapter did not discover.
+ * `type`, `nullable` and `list` are required.
  */
 export type AddedScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type" | "nullable" | "list"> & {
     readonly type: FrameworkScalarTypeRef<M>;
     readonly nullable: boolean;
     readonly list: boolean;
 };
-/**
- * The shape one authored field name admits, by what the adapter knows of it.
- *
- * Where there is no discovered key set to discriminate on, the answer is today's
- * undivided {@link FrameworkScalarFieldConfig}.
- */
+/** The shape one authored field name admits, by what the adapter knows of it. */
 type ScalarFieldConfigFor<M extends AdapterModel, R extends FrameworkResourceKey<M>, F> = string extends AdapterFieldKey<M, R> ? FrameworkScalarFieldConfig<M> : F extends AdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
     readonly kind: "relation";
 } ? never : KnownScalarFieldConfig<M> : AddedScalarFieldConfig<M>;
-/**
- * The constraint an authored `fields` block is checked against, keyed on the
- * block's **own** names.
- *
- * `Self` is the literal being checked, which is why {@link defineFields} is
- * F-bounded: a `satisfies FrameworkFieldsConfig<M>` annotation maps the
- * value shape over an open key set, which collapses to a single index
- * signature, and an index signature cannot tell a discovered name from an
- * added one. The three buckets are only reachable from a mapped type keyed
- * on `keyof Self`.
- *
- * The self-reference is legal here despite the workstream's stopping rule 3
- * because the `fields` block carries no callbacks: nothing inside it needs
- * contextual typing, so there is no inference to collapse. A callback
- * appearing in this block is the signal that this encoding has stopped
- * being safe.
- */
+/** The shape an authored `fields` block is checked against, keyed on its own names. */
 export type FrameworkFieldsShape<M extends AdapterModel, Self> = {
     readonly [R in keyof Self]: R extends FrameworkResourceKey<M> ? {
         readonly [F in keyof Self[R]]: ScalarFieldConfigFor<M, R, F>;
@@ -59,17 +30,6 @@ export type FrameworkFieldsShape<M extends AdapterModel, Self> = {
 /**
  * Authors stage 1 of a configuration: the `fields` block, checked against
  * what the adapter discovered and returned unwidened.
- *
- * The returned literal is stage 2's `Cfg` fields block, so the names it adds
- * are nameable from `restrictions`, `behaviors` and `dependsOn`.
- *
- * `M` is bound by the **model value**, not a type argument: TypeScript has
- * no partial type-argument inference, so `defineFields<M>({ … })` would
- * force `Self` to be written out by hand. The model is already a value at
- * the authoring site, so binding it there costs nothing.
- *
- * The model argument is type-level only — the returned block is the authored
- * one, unchanged.
  */
 export declare function defineFields<M extends AdapterModel, const Self extends FrameworkFieldsShape<M, Self>>(_model: M, fields: Self): Self;
 export {};

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

@@ -13,41 +13,18 @@ import type { FrameworkResourceKey } from "./framework-fields-config.js";
 type FieldsBlockOf<Layer> = Layer extends {
     readonly fields?: infer Block;
 } ? Block extends AnyFieldsBlock ? Block : never : never;
-/**
- * The field names a single `fields` block declares for `R`.
- *
- * The `[Block] extends [never]` guard is load-bearing, not defensive: `keyof
- * never` is `string | number | symbol`, so a layer with no `fields` block
- * would otherwise widen the whole effective key set back to `string` and
- * silently erase every narrowing downstream of it.
- */
+/** The field names a single `fields` block declares for `R`. */
 type FieldsBlockKey<Block, R extends string> = [Block] extends [never] ? never : R extends keyof Block ? Extract<keyof NonNullable<Block[R]>, string> : never;
-/**
- * The field names `Cfg`'s own root `fields` block adds for `R`.
- *
- * Under the default `Cfg` this degenerates to `string`: `AnyFieldsBlock` maps
- * every resource name to an open record, so the effective key set widens back to
- * an index-signature-compatible `string` and today's wide acceptance is preserved.
- */
+/** The field names the configuration's root `fields` block adds to Resource `R`. */
 export type ConfigFieldKey<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = FieldsBlockKey<FieldsBlockOf<Cfg>, R>;
-/**
- * The single answer to "what are `R`'s field names under this configuration".
- *
- * Nothing else in the framework may compute a field-key set; `restrictions`,
- * `behaviors` and `dependsOn` all key on this type.
- *
- * There is deliberately no subtraction here. A `HiddenFieldKey` subtraction would
- * contradict the Accepted ADR and must not be reintroduced.
- */
+/** The single answer to "what are `R`'s field names under this configuration". */
 export type EffectiveFieldKey<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = AdapterFieldKey<M, R> | ConfigFieldKey<M, Cfg, R>;
 /** The overlay `Cfg` carries for `Origin`, or `never` when it declares none. */
 type OriginOverlayOf<Cfg, Origin extends RequestOrigin> = Origin extends keyof Cfg ? NonNullable<Cfg[Origin]> : never;
 /**
- * `R`'s effective field names as seen from one request origin: the root layer
- * plus whatever the `application` or `client` overlay adds on top of it.
- *
- * Origins are siblings, never parents: an overlay contributes to its own origin
- * only, so a name added under `client` is not visible under `application`.
+ * `R`'s field names as seen from one request origin: the root layer plus
+ * whatever the `application` or `client` overlay adds. A name added under
+ * `client` is not visible under `application`, and the other way round.
  */
 export type EffectiveFieldKeyAt<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>, Origin extends RequestOrigin> = EffectiveFieldKey<M, Cfg, R> | FieldsBlockKey<FieldsBlockOf<OriginOverlayOf<Cfg, Origin>>, R>;
 export {};

package/dist/config/entrypoint.normalizer.d.ts

@@ -1,8 +1,8 @@
 /**
- * The framework entrypoint's mount path, in its one canonical form: `""` at the
- * root, otherwise `/seg(/seg)*` — one leading slash, no trailing slash, no empty
- * segment. Root is the empty string, not `"/"`, so a route joins onto it by
- * concatenation with no special case.
+ * The framework entrypoint's mount path, in its one canonical form: `""` at the root,
+ * otherwise `/seg(/seg)*` — one leading slash, no trailing slash, no empty segment.
+ * Root is the empty string, not `"/"`, so a route joins onto it by concatenation with
+ * no special case.
  */
 export type EntrypointPath = "" | `/${string}`;
 /**
@@ -26,19 +26,7 @@ export type EntrypointNormalization = {
     readonly message: string;
 };
 /**
- * `AvProtocol.normalizeEntrypoint` — a mount path, as written, to its canonical
- * form or a refusal.
- *
- * The one source of the rule: config resolution stores the canonical form as
- * `framework.entrypoint`, config validation turns a refusal into a `CONFIG_`
- * diagnostic, and the client generator's `resolveEntrypoint` hands it the mount
- * path of the URL it is given — as written, before a URL parser has trimmed,
- * resolved or percent-encoded anything. Execution code reads it from here;
- * `@aventara/core/protocol` re-exports it, and the main entry does not.
- *
- * Checked in order, so each value has one reason: whitespace, a scheme (`://`), a
- * query, a fragment, a `..` or `.` segment (either separator, `%2e` spelling
- * included), a backslash, a non-ASCII character, a `%`, and finally any other
- * character outside RFC 3986's `pchar`.
+ * `AvProtocol.normalizeEntrypoint` — a mount path, as written, to its canonical form
+ * or a refusal.
  */
 export declare function normalizeEntrypoint(value: string): EntrypointNormalization;

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

@@ -3,27 +3,28 @@ import type { ComputedReadBehavior, ComputeOnCreate, ComputeOnUpdate } from "../
 import type { AnyFrameworkConfig } from "./any-framework-config.js";
 import type { EffectiveFieldKey } from "./effective-fields.js";
 import type { FrameworkResourceKey } from "./framework-fields-config.js";
+/** A read behavior: a compute function, or one declaring the fields it reads. */
 export type FrameworkReadBehavior<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = ComputedReadBehavior<M, Cfg, R>;
+/**
+ * A field's behaviors: a value computed on create, on update, or on read.
+ * `false` turns off a behavior set at an outer layer.
+ */
 export type FrameworkFieldBehaviorConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = {
+    /** Computes the field's value when a row is created. */
     readonly create?: false | ComputeOnCreate<M, Cfg, R>;
+    /** Computes the field's value when a row is updated. */
     readonly update?: false | ComputeOnUpdate<M, Cfg, R>;
+    /** Computes the field's value when a row is read. */
     readonly read?: false | FrameworkReadBehavior<M, Cfg, R>;
 };
-/**
- * Executable behavior bindings for one Resource, keyed on the single effective
- * field-key answer.
- *
- * `Partial` is required, not cosmetic: a mapped type over a literal key set would
- * otherwise demand a binding for every field of the Resource. Under the default
- * `Cfg` the key set is `string`, the mapped half collapses to one index signature
- * and today's wide acceptance is preserved.
- */
+/** Behaviors for one Resource's fields. */
 export type FrameworkResourceBehaviorsConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = {
+    /** Behaviors per field name. */
     readonly fields: Readonly<Partial<{
         [F in EffectiveFieldKey<M, Cfg, R>]: FrameworkFieldBehaviorConfig<M, Cfg, R>;
     }>>;
 };
-/** Executable server-side behavior bindings keyed by canonical Resource. */
+/** Server-side behaviors, per Resource. */
 export type FrameworkBehaviorsConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = Readonly<Partial<{
     [R in FrameworkResourceKey<M>]: FrameworkResourceBehaviorsConfig<M, Cfg, R>;
 }>>;