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

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

@@ -5,9 +5,9 @@ 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;
 /**
- * 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.
+ * 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 +24,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;
@@ -51,14 +40,9 @@ type ConfiguredCapabilities<FieldConfig> = [FieldConfig] extends [never] ? Recor
     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 +52,20 @@ 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. */
 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. */
+/** A scalar the configuration adds, exactly as the configuration states it. */
 type AddedField<FieldConfig> = {
     readonly kind: "scalar";
     readonly type: FieldConfig extends {
@@ -110,86 +86,42 @@ 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 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.
+ * A Resource's fields in the view: the model's and the ones the configuration
+ * adds, less the ones this view's restrictions hide.
  */
 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>>;
 };
-/**
- * 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.
- */
+/** One Resource in the view: the model's own, with its fields layered. */
 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];
 };
 /**
- * `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 layered `restrictions` block
+ * whose `hidden` entries this view applies, or `never` for a view that applies
+ * none.
  */
 type LayeredResources<Resources, Block, Restrictions> = {
     readonly [R in Exclude<keyof Resources, HiddenKey<Restrictions>>]: LayeredResource<Resources[R], EntryOf<Block, R>, EntryOf<Restrictions, 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}).
+ * One derived Contract's type: the model, with a layer's `fields` block applied
+ * and, when `Restrictions` is a block rather than `never`, its hidden entries
+ * removed.
  */
 type DerivedContractView<M extends AdapterModel, FieldsBlock, Restrictions> = {
     readonly scalars: M["scalars"];
@@ -200,28 +132,13 @@ type DerivedContractView<M extends AdapterModel, FieldsBlock, Restrictions> = {
 };
 /**
  * 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`).
+ * configuration.
  */
 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.
+ * 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">> : 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,31 @@ 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.
+     * A call is validated like any other request, so it still refuses what a
+     * restriction removed. 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 is absent, 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 +44,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>>;

package/dist/framework/operation-facade.d.ts

@@ -9,13 +9,9 @@ import type { FrameworkOperationRequest } from "../runtime/operation-request.js"
 import type { OperationResponse } from "../runtime/operation-response.js";
 import type { ApplicationContractView, ClientContractView } from "./contract-view.js";
 /**
- * A model whose Resource names are not literal — the abstract `AdapterModel`
- * behind the default `Framework` — has no Contract to type a call against, so a
- * surface over it is typed as the opaque object it is, and such a caller uses
- * `execute`. It is also what keeps a typed `Framework<M, Cfg>` assignable to
- * `Framework` cheaply: deriving every argument and result over a `string`-keyed
- * Contract, for all sixteen operations, measured at ≈250,000 instantiations for
- * nothing a caller could use.
+ * A model whose Resource names are not literal — the abstract `AdapterModel` behind
+ * the default `Framework` — has no Contract to type a call against, so a surface over
+ * it is typed as the opaque object it is, and such a caller uses `execute`.
  */
 type OpaqueSurface = {
     readonly [resource: string]: unknown;