@aventara/core 0.1.0-pilot.3 → 1.0.0-rc.0

package/dist/framework/contract-view.d.ts

@@ -2,12 +2,16 @@ import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { AnyFrameworkConfig } from "../config/any-framework-config.js";
 import type { RequestOrigin } from "../config/config-layer.js";
 import type { ContractLimits } from "../contracts/contract-limits.js";
-/** Whether `resolveRecord` descends into a value: an object that is no array. */
-type IsLayeredRecord<T> = [T] extends [readonly unknown[]] ? false : [T] extends [object] ? true : false;
+import type { JsonShape, ShapedJsonSchema } from "../contracts/json-shape.js";
 /**
- * Rule 4 at the type level: `resolveRecord(root, scoped)`. A key `Scoped` states
- * wins; when both sides are records the two merge, recursively; otherwise the
- * scoped leaf replaces the root one wholesale.
+ * Whether `resolveRecord` descends into a value: an object that is no array and
+ * no Json Shape.
+ */
+type IsLayeredRecord<T> = [T] extends [readonly unknown[]] ? false : [T] extends [JsonShape] ? false : [T] extends [object] ? true : false;
+/**
+ * A root record with a scoped record layered over it: a key the scoped side
+ * states wins; when both sides are records they merge, recursively; otherwise
+ * the scoped value replaces the root one.
  */
 type LayeredRecord<Root, Scoped> = {
     readonly [K in keyof Root | keyof Scoped]: K extends keyof Scoped ? K extends keyof Root ? [IsLayeredRecord<Root[K]>, IsLayeredRecord<Scoped[K]>] extends [
@@ -24,19 +28,8 @@ type LayeredRecord<Root, Scoped> = {
 type LiteralRecord<T> = unknown extends T ? never : [NonNullable<T>] extends [never] ? never : [NonNullable<T>] extends [object] ? string extends keyof NonNullable<T> ? never : NonNullable<T> : never;
 type LayeredBlocks<Root, Scoped> = [Root] extends [never] ? Scoped : [Scoped] extends [never] ? Root : LayeredRecord<Root, Scoped>;
 /**
- * One configuration block as a derived Contract is compiled from it (rule 4):
- * root `Key`, with layer `Layer`'s `Key` layered over it.
- *
- * **Read by indexed access, deliberately not through `effective-fields.ts`'s
- * `FieldsBlockOf`.** That reader (`Cfg extends { fields?: infer Block } ? Block
- * extends AnyFieldsBlock ? … `) is right for a key set, but here it makes
- * TypeScript's variance probe treat `Cfg` as irrelevant to this view, so
- * `Framework<M, A>` and `Framework<M, B>` compare identical whatever their `fields`
- * say — the collapse `framework.factory.test-d.ts`'s non-collapse rows exist to
- * catch, and measured: substituting `FieldsBlockOf` here fails both of them. An
- * indexed access is related only when its object types are, so the probe sees
- * `Cfg`. The rows, not this comment, are the guard: the measurement is
- * TypeScript's, and it can move.
+ * One configuration block as a derived Contract is compiled from it: the root
+ * `Key`, with layer `Layer`'s `Key` layered over it.
  */
 type LayerBlock<Cfg, Layer extends RequestOrigin, Key extends "fields" | "restrictions"> = LayeredBlocks<LiteralRecord<(Cfg & {
     readonly [K in Key]?: unknown;
@@ -45,20 +38,19 @@ type LayerBlock<Cfg, Layer extends RequestOrigin, Key extends "fields" | "restri
 })[Layer] & {
     readonly [K in Key]?: unknown;
 })[Key]>>;
+/** Root's own `Key` block, before any layer is layered over it. */
+type RootBlock<Cfg, Key extends "fields" | "restrictions"> = LiteralRecord<(Cfg & {
+    readonly [K in Key]?: unknown;
+})[Key]>;
 /** One key's entry in a layered block, or `never` when the block has none. */
 type EntryOf<Block, Key> = [Block] extends [never] ? never : Key extends keyof Block ? LiteralRecord<NonNullable<Block[Key]>> : never;
 type ConfiguredCapabilities<FieldConfig> = [FieldConfig] extends [never] ? Record<never, never> : FieldConfig extends {
     readonly capabilities: infer Capabilities;
 } ? NonNullable<Capabilities> : Record<never, never>;
 /**
- * Rule 3: a configured member replaces the field's own, and `select` defaults to
- * `true` when neither states it.
- *
- * The override is the first, homomorphic part — mapped over the field's own
- * members, so a member the model leaves optional stays optional rather than
- * becoming a required `T | undefined` that no Contract admits. The other two parts
- * only ADD keys the first does not have, so intersecting them can never narrow a
- * member (the `true & false` failure is an intersection over a SHARED key).
+ * A field's capabilities with the configured ones applied: a configured member
+ * replaces the field's own, and `select` defaults to `true` when neither states
+ * it.
  */
 type LayeredCapabilities<Own, Configured> = {
     readonly [P in keyof Own]: P extends keyof Configured ? Configured[P] : Own[P];
@@ -68,28 +60,29 @@ type LayeredCapabilities<Own, Configured> = {
     readonly select: true;
 });
 /**
- * Rule 1 with rule 3: a model field keeps every structural fact and takes its
- * capabilities from the layered configuration. A relation is the model's
- * (configuring one fails construction).
- *
- * **A field the layer does not configure, and whose capabilities state `select`,
- * is the model's own field type** — rule 3 changes nothing about it, so the view
- * re-states nothing. That is every field of a typical model but the handful a
- * configuration names, and it is what keeps the view's cost proportional to the
- * configuration rather than to the schema: every reader of a field (each
- * capability question, the `Contract` check a surface asks once) reads the model's
- * literal directly instead of a mapped copy of it.
+ * A discovered field as the view sees it: every structural fact from the model,
+ * its capabilities with the configuration applied. A relation is the model's
+ * own.
  */
 type LayeredModelField<Field, FieldConfig> = Field extends {
     readonly kind: "scalar";
 } ? [FieldConfig] extends [never] ? Field extends {
     readonly capabilities: infer Capabilities;
 } ? "select" extends keyof Capabilities ? Field : ConfiguredModelField<Field, FieldConfig> : ConfiguredModelField<Field, FieldConfig> : ConfiguredModelField<Field, FieldConfig> : Field;
-/** A model scalar with rule 3 applied: its capabilities layered member by member. */
+/**
+ * A discovered scalar with its configured capabilities applied, member by member,
+ * and its configured Json Shape, whose type its value takes.
+ */
 type ConfiguredModelField<Field, FieldConfig> = {
     readonly [P in keyof Field]: P extends "capabilities" ? LayeredCapabilities<Field[P], ConfiguredCapabilities<FieldConfig>> : Field[P];
-};
-/** Rule 2 with rule 3: a configuration-added scalar, exactly as it states itself. */
+} & ConfiguredJsonShape<FieldConfig>;
+/** A configured Json Shape as a view field's `json` member; nothing otherwise. */
+type ConfiguredJsonShape<FieldConfig> = [FieldConfig] extends [never] ? unknown : FieldConfig extends {
+    readonly json: JsonShape<infer Value>;
+} ? {
+    readonly json: ShapedJsonSchema<Value>;
+} : unknown;
+/** A scalar the configuration adds, exactly as the configuration states it. */
 type AddedField<FieldConfig> = {
     readonly kind: "scalar";
     readonly type: FieldConfig extends {
@@ -110,118 +103,147 @@ type AddedFieldKey<ModelFields, ResourceConfig> = [ResourceConfig] extends [
     never
 ] ? never : Exclude<Extract<keyof ResourceConfig, string>, keyof ModelFields>;
 /**
- * Rule 5: whether a layered restriction entry hides what it names. Only a literal
- * `true` does — `false` restores, and a widened `boolean` promises neither, so
- * the thing stays in the view and the validation layer answers it.
+ * Whether a restriction entry hides what it names: only a literal `hidden: true`
+ * does; `false` restores it.
  */
 type IsHidden<Restriction> = [Restriction] extends [never] ? false : Restriction extends {
     readonly hidden: true;
 } ? true : false;
 /**
- * Rule 5 for a whole block: the keys whose layered restriction hides them, or
- * `never` for a view that reads no restriction.
- *
- * **A key set, computed once per block, rather than a per-key test in an `as`
- * clause.** A remapped mapped type (`[K in … as …]`) re-evaluates its `as` for
- * every key whenever any of its keys or members is asked for; a mapped type over
- * `Exclude<keys, HiddenKey<…>>` reads this set once. Measured on the artifact's
- * shape: ≈2,300 instantiations per client-origin call, and the remapped form was
- * the costliest single term of a client-layer surface.
+ * The keys a restrictions block hides, or `never` for a view that reads no
+ * restrictions.
  */
 type HiddenKey<Restrictions> = [Restrictions] extends [never] ? never : {
     [K in keyof Restrictions]-?: IsHidden<EntryOf<Restrictions, K>> extends true ? K : never;
 }[keyof Restrictions];
+/** A restriction entry's `capabilities` block, or `never` when it states none. */
+type CapabilityRestrictionsOf<Entry> = [Entry] extends [never] ? never : EntryOf<Entry, "capabilities">;
+/** A restriction member that is a literal `false`: a denial. */
+type IsDenial<Value> = [Value] extends [false] ? true : false;
+/** A restriction member that is a literal `true`: a restoration. */
+type IsRestoration<Value> = [Value] extends [true] ? true : false;
+/** The tokens a capability member advertises, its qualifier aside. */
+type MemberTokens<Member, TokenKey extends string> = Member extends {
+    readonly scopes: unknown;
+} ? TokenKey extends keyof Member ? Member[TokenKey] : never : Member;
+/** The positions a scope-qualified member holds in; `never` for an unqualified one. */
+type MemberScopes<Member> = Member extends {
+    readonly scopes: infer Scopes;
+} ? Scopes : never;
+/** A relation's `create`, `update` or `reducers` member narrowed by a restriction. */
+type NarrowedScopedTokens<Member, Restriction, TokenKey extends "directives" | "reducers"> = Restriction extends readonly unknown[] ? [MemberScopes<Member>] extends [never] ? Restriction : {
+    readonly [K in TokenKey | "scopes"]: K extends "scopes" ? MemberScopes<Member> : Restriction;
+} : Restriction extends object ? (Restriction extends {
+    readonly scopes: infer Scopes;
+} ? Scopes : MemberScopes<Member>) extends infer Scopes ? [Scopes] extends [never] ? Restriction extends {
+    readonly [K in TokenKey]: infer Tokens;
+} ? Tokens : MemberTokens<Member, TokenKey> : Scopes extends readonly [] ? false : {
+    readonly [K in TokenKey | "scopes"]: K extends "scopes" ? Scopes : Restriction extends {
+        readonly [T in TokenKey]: infer Tokens;
+    } ? Tokens : MemberTokens<Member, TokenKey>;
+} : never : Member;
+/** One capability member narrowed by a list (or, on a relation, an object) restriction. */
+type NarrowedMember<Kind, Key, Member, Restriction> = Kind extends "relation" ? Key extends "select" | "include" ? Restriction extends readonly [] ? false : Restriction : Key extends "create" | "update" ? NarrowedScopedTokens<Member, Restriction, "directives"> : Key extends "reducers" ? NarrowedScopedTokens<Member, Restriction, "reducers"> : Restriction : Restriction;
+/** One capability member of a field under its layer's restrictions. */
+type RestrictedMember<Kind, Key, Member, Root, Layered> = IsRestoration<Layered> extends true ? Root extends readonly unknown[] | {
+    readonly scopes?: unknown;
+} ? NarrowedMember<Kind, Key, Member, Root> : Member : [Layered] extends [boolean] ? Member : NarrowedMember<Kind, Key, Member, Layered>;
+/** The members a capabilities restriction denies, or narrows to nothing. */
+type DeniedMember<Kind, Own, Root, Layered> = {
+    [P in keyof Own]-?: P extends keyof Layered ? IsDenial<Layered[P]> extends true ? P : [
+        RestrictedMember<Kind, P, Own[P], P extends keyof Root ? Root[P] : undefined, Layered[P]>
+    ] extends [false] ? P : never : never;
+}[keyof Own];
+/** A field's capabilities under its layer's restrictions. */
+type RestrictedCapabilities<Kind, Own, Root, Layered> = {
+    readonly [P in keyof Own as P extends DeniedMember<Kind, Own, Root, Layered> ? never : P]: P extends keyof Layered ? RestrictedMember<Kind, P, Own[P], P extends keyof Root ? Root[P] : undefined, Layered[P]> : Own[P];
+};
+/** A view field with its layer's capability restrictions applied. */
+type RestrictedField<Field, RootEntry, Entry> = [
+    CapabilityRestrictionsOf<Entry>
+] extends [never] ? Field : {
+    readonly [P in keyof Field]: P extends "capabilities" ? RestrictedCapabilities<Field extends {
+        readonly kind: infer Kind;
+    } ? Kind : never, Field[P], CapabilityRestrictionsOf<RootEntry>, CapabilityRestrictionsOf<Entry>> : Field[P];
+};
 /**
- * A Resource's fields in the view: the model's keys and the configuration-added
- * ones (rule 2), less the ones this view's restrictions hide (rule 5).
- *
- * **One mapped type, with no conditional around it and no `as` clause.** Every
- * branch here is one more structure TypeScript's variance probe of `Framework`
- * walks — paid by every program that compares two `Framework` types
- * (`Awaited<Promise<Framework<…>>>` is one); a separate branch per case measured
- * at +9,000 instantiations there, and naming the field rule below as an alias at
- * +2,300.
- */
-type LayeredFields<ModelFields, ResourceConfig, FieldRestrictions> = {
-    readonly [F in Exclude<keyof ModelFields | AddedFieldKey<ModelFields, ResourceConfig>, HiddenKey<FieldRestrictions>>]: F extends keyof ModelFields ? LayeredModelField<ModelFields[F], EntryOf<ResourceConfig, F>> : AddedField<EntryOf<ResourceConfig, F>>;
+ * A Resource's fields in the view: the model's and the ones the configuration
+ * adds, less the ones this view's restrictions hide, each with its capability
+ * restrictions applied.
+ */
+type LayeredFields<ModelFields, ResourceConfig, FieldRestrictions, RootFieldRestrictions> = {
+    readonly [F in Exclude<keyof ModelFields | AddedFieldKey<ModelFields, ResourceConfig>, HiddenKey<FieldRestrictions>>]: RestrictedField<F extends keyof ModelFields ? LayeredModelField<ModelFields[F], EntryOf<ResourceConfig, F>> : AddedField<EntryOf<ResourceConfig, F>>, EntryOf<RootFieldRestrictions, F>, EntryOf<FieldRestrictions, F>>;
 };
+/** The variants of one family an operations restriction turns off: literal `false` only. */
+type DisabledVariant<FamilyRestriction> = [FamilyRestriction] extends [never] ? never : {
+    [V in keyof FamilyRestriction]-?: IsDenial<FamilyRestriction[V]> extends true ? V : never;
+}[keyof FamilyRestriction];
+/** The variants of the unique style, which need an identifier the layer keeps. */
+type UniqueVariant = "unique";
 /**
- * One Resource in the view: the model's own, with its fields layered.
- *
- * **Declared invariant (`in out`) rather than measured.** Comparing two
- * `Framework` types — `Awaited<Promise<Framework<…>>>` does, and so does handing
- * a typed Framework to a host that holds the untyped one — makes TypeScript
- * measure `Framework`'s variance by walking every alias under it with marker
- * types; measured, this alias and the field machinery under it were ≈22,000 of
- * that walk's ≈29,000 instantiations, paid once by every program. Its measured
- * answer was already invariant in all three parameters, so the declaration
- * states the same answer without the walk.
- *
- * **Only here, deliberately.** The measurement also marked `Framework`'s model
- * parameter *unreliable*, and that mark is what lets a typed `Framework<M, Cfg>`
- * still be assigned to the untyped `Framework` (TypeScript then falls back to
- * comparing structure, where every surface of the untyped Framework is opaque).
- * Declaring the variance any higher — on `DerivedContractView` itself — removes
- * the mark, and `transaction-runtime.spec.ts`'s `Promise<Framework>` stops
- * compiling.
- */
-type LayeredResource<in out Resource, in out ResourceConfig, in out ResourceRestrictions> = {
-    readonly [P in keyof Resource]: P extends "fields" ? LayeredFields<Resource[P], ResourceConfig, EntryOf<ResourceRestrictions, "fields">> : Resource[P];
+ * The variants of one family the layer advertises: the model's, less those turned
+ * off, less the unique one when no identifier survives.
+ */
+type AvailableVariant<Family, FamilyRestriction, UniqueLost> = Exclude<keyof Family, DisabledVariant<FamilyRestriction> | (UniqueLost extends true ? UniqueVariant : never)>;
+/** The families with at least one variant the layer advertises. */
+type AvailableFamily<Operations, OperationRestrictions, UniqueLost> = {
+    [F in keyof Operations]-?: [
+        AvailableVariant<NonNullable<Operations[F]>, EntryOf<OperationRestrictions, F>, UniqueLost>
+    ] extends [never] ? never : F;
+}[keyof Operations];
+/** A Resource's operations under its layer's restrictions. */
+type RestrictedOperations<Operations, OperationRestrictions, UniqueLost> = [
+    OperationRestrictions
+] extends [never] ? UniqueLost extends true ? LayerOperations<Operations, never, UniqueLost> : Operations : LayerOperations<Operations, OperationRestrictions, UniqueLost>;
+type LayerOperations<Operations, OperationRestrictions, UniqueLost> = {
+    readonly [F in AvailableFamily<Operations, OperationRestrictions, UniqueLost>]: {
+        readonly [V in AvailableVariant<NonNullable<Operations[F]>, EntryOf<OperationRestrictions, F>, UniqueLost>]: NonNullable<Operations[F]>[V];
+    };
+};
+/** A Resource's identifiers less those naming a hidden field. */
+type KeptIdentifiers<Identifiers, Hidden> = [Hidden] extends [never] ? Identifiers : Identifiers extends readonly (infer Identifier)[] ? readonly (Identifier extends readonly (infer Field)[] ? [Extract<Field, Hidden>] extends [never] ? Identifier : never : never)[] : Identifiers;
+/** Whether hiding fields left a Resource with no identifier at all. */
+type IdentifiersLost<Identifiers, Hidden> = [Hidden] extends [never] ? false : [
+    KeptIdentifiers<Identifiers, Hidden> extends readonly (infer Kept)[] ? Kept : never
+] extends [never] ? true : false;
+/**
+ * One Resource in the view: the model's own, with its fields layered and its
+ * layer's restrictions applied to its fields, operations and identifiers.
+ */
+type LayeredResource<in out Resource, in out ResourceConfig, in out ResourceRestrictions, in out RootResourceRestrictions> = {
+    readonly [P in keyof Resource]: P extends "fields" ? LayeredFields<Resource[P], ResourceConfig, EntryOf<ResourceRestrictions, "fields">, EntryOf<RootResourceRestrictions, "fields">> : P extends "operations" ? RestrictedOperations<Resource[P], EntryOf<ResourceRestrictions, "operations">, IdentifiersLost<Resource extends {
+        readonly identifiers: infer Ids;
+    } ? Ids : never, HiddenKey<EntryOf<ResourceRestrictions, "fields">>>> : P extends "identifiers" ? KeptIdentifiers<Resource[P], HiddenKey<EntryOf<ResourceRestrictions, "fields">>> : Resource[P];
 };
 /**
- * `Restrictions` is the layered `restrictions` block whose `hidden` this layer's
- * view reads (rule 5), or `never` for a view that reads none.
+ * The Resources in the view. `Restrictions` is the layer's layered
+ * `restrictions` block and `RootRestrictions` root's own, whose narrowings a
+ * restoration inherits; both `never` for a configuration that restricts nothing.
  */
-type LayeredResources<Resources, Block, Restrictions> = {
-    readonly [R in Exclude<keyof Resources, HiddenKey<Restrictions>>]: LayeredResource<Resources[R], EntryOf<Block, R>, EntryOf<Restrictions, R>>;
+type LayeredResources<Resources, Block, Restrictions, RootRestrictions> = {
+    readonly [R in Exclude<keyof Resources, HiddenKey<Restrictions>>]: LayeredResource<Resources[R], EntryOf<Block, R>, EntryOf<Restrictions, R>, EntryOf<RootRestrictions, R>>;
 };
 /**
- * One derived Contract's view: the model, with a layer's layered `fields` block
- * applied (rules 1–4) and, when `Restrictions` is a block rather than `never`,
- * its `hidden` (rule 5).
- *
- * **Keyed on the two blocks it reads, never on the configuration.** TypeScript
- * keys an instantiated type on the arguments of the alias it is reached through,
- * so a view instantiated through an alias over `Cfg` is a distinct type for every
- * configuration, and two `Framework`s whose configurations differ only in what
- * the view never reads — a pipeline, a diagnostics sink, the other layer — carry
- * four distinct surfaces that only a structural walk of every operation of every
- * Resource can prove equal. Measured on `transaction-plan-validator.spec.ts`,
- * where two such Frameworks share one array literal: ≈95,000 instantiations for
- * that one line, ≈4,000 keyed on blocks. The two named views below reach this
- * type through a conditional for that reason (see {@link ApplicationContractView}).
- */
-type DerivedContractView<M extends AdapterModel, FieldsBlock, Restrictions> = {
+ * One derived Contract's type: the model, with a layer's `fields` block applied
+ * and its layered `restrictions` block (`Restrictions`, over root's own,
+ * `RootRestrictions`) applied.
+ */
+type DerivedContractView<M extends AdapterModel, FieldsBlock, Restrictions, RootRestrictions> = {
     readonly scalars: M["scalars"];
     readonly enums: M["enums"];
-    readonly resources: LayeredResources<M["resources"], FieldsBlock, Restrictions>;
+    readonly resources: LayeredResources<M["resources"], FieldsBlock, Restrictions, RootRestrictions>;
     readonly limits: ContractLimits;
     readonly transactions: M["transactions"];
 };
 /**
  * The Application Contract's type, derived from the adapter model and the
- * configuration literal by rules 1–4 above.
- *
- * It is fed to the same `OperationArgumentsFor` and `OperationResultFor` a
- * generated client feeds its ClientContract literal to: one derivation, two
- * sources of a Contract type. `limits` is the type every Contract carries; its
- * values are resolved at construction and no derivation reads them.
- *
- * The conditional is always true. It is there so that the view this resolves to is
- * `DerivedContractView` keyed on its blocks: a conditional's resolved branch is
- * the branch's own type, while a plain alias over `Cfg` would key the instantiated
- * view on the whole configuration (see `DerivedContractView`).
- */
-export type ApplicationContractView<M extends AdapterModel, Cfg = AnyFrameworkConfig> = [Cfg] extends [unknown] ? DerivedContractView<M, LayerBlock<Cfg, "application", "fields">, never> : never;
-/**
- * The Client Contract's type, by the same four rules over `client.fields`, plus
- * rule 5: what the client layer hides is absent. Typed under ClientContract rules
- * for the in-process client-origin surfaces (`framework.client`,
- * `framework.clientTx`).
- *
- * Not exported from the package; a generated client reads the deployed
- * ClientContract literal itself. Resolved through a conditional for the reason
- * {@link ApplicationContractView} gives.
- */
-export type ClientContractView<M extends AdapterModel, Cfg = AnyFrameworkConfig> = [Cfg] extends [unknown] ? DerivedContractView<M, LayerBlock<Cfg, "client", "fields">, LayerBlock<Cfg, "client", "restrictions">> : never;
+ * configuration.
+ */
+export type ApplicationContractView<M extends AdapterModel, Cfg = AnyFrameworkConfig> = [Cfg] extends [unknown] ? DerivedContractView<M, LayerBlock<Cfg, "application", "fields">, LayerBlock<Cfg, "application", "restrictions">, RootBlock<Cfg, "restrictions">> : never;
+/**
+ * The Client Contract's type, derived from the adapter model and the
+ * configuration: what the client layer hides is absent. It types
+ * `framework.client` and `framework.clientTx`.
+ */
+export type ClientContractView<M extends AdapterModel, Cfg = AnyFrameworkConfig> = [Cfg] extends [unknown] ? DerivedContractView<M, LayerBlock<Cfg, "client", "fields">, LayerBlock<Cfg, "client", "restrictions">, RootBlock<Cfg, "restrictions">> : never;
 export {};

package/dist/framework/framework-construction.error.d.ts

@@ -1,9 +1,14 @@
 import type { AdapterDiscoveryDiagnostic } from "../adapters/adapter-discovery-diagnostic.js";
 import type { ContractCompilerDiagnostic } from "../compiler/contract-compiler-diagnostic.js";
 import type { ConfigDiagnostic } from "../config/config-diagnostic.js";
+/** The construction step that failed. */
 export type FrameworkConstructionStage = "configuration" | "discovery" | "contract-compilation";
+/** One problem reported by {@link FrameworkConstructionError}. */
 export type FrameworkConstructionDiagnostic = ConfigDiagnostic | AdapterDiscoveryDiagnostic | ContractCompilerDiagnostic;
-/** Startup failure with deterministic diagnostics from the earliest failed construction stage. */
+/**
+ * Thrown by {@link createFramework} when construction fails: `stage` says
+ * where, and `diagnostics` lists every problem found there.
+ */
 export declare class FrameworkConstructionError extends Error {
     readonly stage: FrameworkConstructionStage;
     readonly diagnostics: readonly FrameworkConstructionDiagnostic[];

package/dist/framework/framework.d.ts

@@ -7,36 +7,33 @@ import type { TransactionRunner } from "../transactions/deferred-operation.js";
 import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
 import type { TransactionResponse } from "../transactions/transaction-response.js";
 import type { ApplicationOperations, ApplicationTransactionBuilders, ClientOperations, ClientTransactionBuilders } from "./operation-facade.js";
+/**
+ * One Aventara instance, as returned by {@link createFramework}: its compiled
+ * Contracts, typed in-process operations, transaction builders and the
+ * untyped `execute` entry a transport calls.
+ */
 export type Framework<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
     readonly entrypoint: string;
     readonly contracts: FrameworkContracts;
     /**
-     * The typed in-process façade:
-     * `framework.application.<resource>.<family>.<variant>(args)`.
+     * Typed in-process operations under the Application Contract:
+     * `framework.application.<resource>.<family>.<variant>(args, options?)`.
      *
-     * Arguments and results are derived from the Application Contract's view of `M`
-     * and `Cfg` (`ApplicationContractView`), so this is the member that reads the
-     * pair: two configurations that differ in one `fields` entry give two different
-     * `Framework` types. Each call is an application-scope request to {@link execute}
-     * — the same totality guard and validation layer — which still refuses what a
-     * restriction removed, since restrictions stay invisible to the types.
-     *
-     * A call's optional second argument is its `ExecutionOptions`: a supplied
-     * `requestId` is the request's, in every pipeline context and diagnostic; omitted
-     * or empty, a fresh id is minted per call.
+     * Typed from the Application Contract as configured: what the application's
+     * restrictions hide, deny or turn off is absent from the types, and a call is
+     * validated like any other request. The optional second argument is
+     * {@link ExecutionOptions}.
      */
     readonly application: ApplicationOperations<M, Cfg>;
     /**
-     * The same façade under ClientContract rules:
-     * `framework.client.<resource>.<family>.<variant>(args)`.
+     * The same operations under ClientContract rules:
+     * `framework.client.<resource>.<family>.<variant>(args, options?)`.
      *
-     * Typed from the Client Contract's view of `M` and `Cfg` — what the client
-     * layer hides is absent, and arguments are read in the wire forms a decoded
-     * request body carries, so a transport can hand it `req.body` as it is. Each
-     * call is a client-origin request to {@link execute} carrying the server's own
-     * protocol identity: the Client Contract, the client pipelines, and the same
-     * validation layer, which answers whatever a free-flow body says. Takes the
-     * same `ExecutionOptions` second argument as {@link application}.
+     * What the client layer hides, denies or turns off is absent from the types,
+     * as from a generated client, and arguments are read in the wire
+     * forms a decoded request body carries, so a transport can pass `req.body` as
+     * it is. Each call runs the client pipelines and the same validation as a
+     * remote request.
      */
     readonly client: ClientOperations<M, Cfg>;
     /**
@@ -49,41 +46,31 @@ export type Framework<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkC
      */
     readonly appTx: ApplicationTransactionBuilders<M, Cfg>;
     /**
-     * The same builders under ClientContract rules: the Client Contract's view,
-     * wire-form arguments. Client and application handles may share one
-     * {@link transaction}; each step runs under its own handle's rules.
+     * The same builders under ClientContract rules, taking wire-form arguments.
+     * Client and application handles may share one {@link transaction}; each step
+     * runs under its own handle's rules.
      */
     readonly clientTx: ClientTransactionBuilders<M, Cfg>;
     execute(request: FrameworkOperationRequest): Promise<OperationResponse>;
     /**
-     * Validates a whole transaction plan, then runs its operations strictly
-     * sequentially inside one Adapter transaction. Answers `A1009` with each
-     * operation's final data in plan order, the failing operation's own code with
-     * `cause.operation` after rollback, or `A3002` when the transaction infrastructure
-     * fails. Total: it resolves for every input.
+     * Validates a whole transaction plan, then runs its operations one after
+     * another inside one Adapter transaction. Answers `A1009` with each
+     * operation's final data in plan order, the failing operation's own code
+     * with `cause.operation` after rollback, or `A3002` when the transaction
+     * itself fails. Never rejects.
      *
-     * Every operation's guards, pipes, hooks and interceptors run while the provider
-     * transaction is open and must not perform network I/O or unrelated slow work. The
-     * Adapter must reject with the exact value its transaction callback threw, by
-     * identity.
+     * Guards, pipes, hooks and interceptors run while the transaction is open, so
+     * they should not perform network I/O or other slow work.
      */
     executeTransaction(request: FrameworkTransactionRequest): Promise<TransactionResponse>;
     /**
-     * The one typed transaction runner: `framework.transaction([h1, h2, …])`.
-     *
-     * Binds each `$ref` to its source's position in this list, fingerprints every
-     * step, and runs the resulting passive plan through the same validation layer and
-     * transaction runtime as {@link executeTransaction} — each step under its own
-     * handle's origin, its own layer's Contract and pipelines, inside one Adapter
-     * transaction. The committed response is typed per position.
+     * Runs handles from `appTx`/`clientTx` as one transaction:
+     * `framework.transaction([h1, h2, …], options?)`. Resolves the committed
+     * response, typed per position, or the failure response. Never rejects.
      *
      * Refused before anything runs: an entry that is not one of this Framework's
-     * handles, or the same handle twice (`A2004`/`V1001`); a `$ref` to a handle not in
-     * the list (`A2007`/`V1010`). Total: it resolves for every input.
-     *
-     * The optional second argument is the run's `ExecutionOptions`: its `requestId` is
-     * every step's, under either origin; omitted or empty, one id is minted for the
-     * run. Handles take no options — a handle is not a request.
+     * handles, or the same handle twice (`A2004`/`V1001`); a `$ref` to a handle
+     * not in the list (`A2007`/`V1010`).
      */
     readonly transaction: TransactionRunner;
 };

package/dist/framework/framework.factory.d.ts

@@ -3,23 +3,9 @@ import type { AnyFrameworkConfig } from "../config/any-framework-config.js";
 import type { FrameworkConfig } from "../config/framework-config.js";
 import type { Framework } from "./framework.js";
 /**
- * Validate, read the model, resolve, compile, and bind one Aventara Framework
- * instance.
+ * Creates a Framework: validates the configuration, reads the adapter's
+ * model and compiles the Contracts.
  *
- * The parameter is deliberately `Cfg & FrameworkConfig<M, Cfg>` rather than
- * the obvious `FrameworkConfig<M, Cfg>`. `Cfg` has to appear somewhere the
- * compiler actually infers from; inside `FrameworkConfig`'s body it only ever
- * reaches non-inference positions, so it would fall back to its
- * `AnyFrameworkConfig` default with no error reported anywhere, and every
- * narrowing keyed on the authored configuration would quietly widen. The
- * intersection puts `Cfg` directly against the argument type.
- *
- * `Cfg` is a `const` type parameter for the same reason: it stands for the
- * configuration *as authored*. Without `const`, inferring `Cfg` from an
- * inline configuration literal widens its scalar references away from their
- * literal types, and the widened `Cfg` then loses to the intersection's own
- * `FrameworkConfig` half — a call site that compiles today stops compiling.
- * A configuration passed as an already-annotated variable is unaffected
- * either way.
+ * @throws {@link FrameworkConstructionError} when any of those steps fails.
  */
 export declare function createFramework<M extends AdapterModel, const Cfg = AnyFrameworkConfig>(config: Cfg & FrameworkConfig<M, Cfg>): Promise<Framework<M, Cfg>>;