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

package/README.md

@@ -11,9 +11,9 @@ Core is ORM- and transport-agnostic: it imports neither Prisma nor NestJS. An ap
 ## Install
 
 ```bash
-npx @aventara/cli new my-api     # a new NestJS project with Prisma and Aventara
-npx @aventara/cli init           # or: add Aventara to an existing NestJS 12 project
-npm install @aventara/core       # the package on its own
+npx @aventara/cli@pilot new my-api     # a new NestJS project with Prisma and Aventara
+npx @aventara/cli@pilot init           # or: add Aventara to an existing NestJS 12 project
+npm install @aventara/core@pilot       # the package on its own
 ```
 
 Node `^22.18.0 || >=24.2.0`. ES modules, with a CommonJS `default` condition.

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

@@ -30,16 +30,16 @@ export type AdapterScalarField<M extends AdapterModel> = {
  * 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 (D-802) and would be wrong
- * for the next adapter.
+ * 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
+ * **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.
  */
 export type AdapterRelationField<M extends AdapterModel> = {

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

@@ -21,20 +21,18 @@ export type AdapterFieldKey<M extends AdapterModel, R extends Extract<keyof M["r
  * 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.
+ * `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.
+ * `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.
  *
- * This is why F-601 ("the second type parameter is dead") was closed as
- * mistaken rather than actioned. Deleting it is not a cleanup.
+ * Deleting it is not a cleanup.
  */
 export type AdapterResource<M extends AdapterModel, TFields extends AdapterFieldMap<M> = AdapterFieldMap<M>> = {
     readonly fields: TFields;

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

@@ -1,3 +1,4 @@
+import type { CreateRequirementTable } from "../runtime/create-requirement.js";
 import type { ReferentialActionTable } from "../runtime/referential-action.js";
 import type { AdapterModel } from "./adapter-model.js";
 import type { AdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
@@ -25,17 +26,26 @@ export interface Adapter<M extends AdapterModel = AdapterModel> extends AdapterO
      */
     readonly referentialActions?: ReferentialActionTable;
     /**
-     * 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 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.
+     *
+     * Optional so an Adapter that cannot state them is believed: core then checks
+     * nothing, and a missing value reaches the store as before.
+     */
+    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.
      *
-     * 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 (spec §14.5).
+     * 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.
      */
     transaction?<T>(work: (executor: AdapterOperationExecutor<M>) => Promise<T>): Promise<T>;
 }

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

@@ -1,10 +1,9 @@
 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
- * `ClientContract` (`validateClientContractStructure`; Phase 10 R3, the
- * architect's code, 2026-10-05). A framework-bug guard: the server never
- * serves what its own generator would refuse. `path` is the JSONPath
- * inside the ClientContract (`$.enums.status.values[1]`).
+ * `ClientContract`. A framework-bug guard: the server never serves what its own
+ * generator would refuse. `path` is the JSONPath inside the ClientContract
+ * (`$.enums.status.values[1]`).
  */
  | "COMPILER_INVALID_CLIENT_CONTRACT";
 export type ContractCompilerDiagnostic = {

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

@@ -17,7 +17,7 @@ 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 (F-817).
+ * 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
@@ -29,11 +29,12 @@ export type ContractCompilationResult = {
  *
  * 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 (C-855).
+ * 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.
+ * 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.
  */

package/dist/compiler/contract.compiler.js

@@ -150,36 +150,11 @@ function addConfiguredScalarField(config, path, diagnostics) {
         },
     };
 }
-/**
- * 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 (F-817).
- *
- * 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 (C-855).
- *
- * 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.
- */
 export function capabilityAddsBaseline(fieldKind, baseline, key, configured) {
     const axis = capabilityAxisFor(fieldKind, key);
     if (axis === undefined) {
         return false;
     }
-    // Every arm below answers `false` for a denial (`false`) and for no value at
-    // all: neither claims a token or a position.
     const baselineValue = baseline[key];
     switch (axis.kind) {
         case "flag":
@@ -216,12 +191,6 @@ export function capabilityAddsBaseline(fieldKind, baseline, key, configured) {
         }
     }
 }
-/**
- * The tokens a scope-qualified member value claims, and the positions it claims
- * them in: a bare token list claims every position on the axis, a
- * `{ <tokenKey>, scopes }` arm the positions it names. `undefined` for any other
- * shape, which is the output gate's to refuse.
- */
 function scopedTokenClaim(axis, configured) {
     if (isTokenList(configured)) {
         return { tokens: configured, positions: axis.axis };
@@ -236,11 +205,6 @@ function scopedTokenClaim(axis, configured) {
     }
     return undefined;
 }
-/**
- * What a scope-qualified baseline member advertises at one position, through the
- * shape's own `…At` owner for its token key. A baseline that is neither arm
- * advertises nothing — the same answer an absent member gives.
- */
 function advertisedTokensAt(tokenKey, baselineValue, position) {
     if (!isTokenList(baselineValue) && !isRecord(baselineValue)) {
         return undefined;
@@ -406,12 +370,6 @@ function applyBehaviors(projection, scope, config, diagnostics, allowRestrictedM
         }
     }
 }
-/**
- * Pinned against the restriction type AND the Contract member type, so a capability
- * member added to either surface fails to compile HERE rather than reaching the
- * restriction walk with no axis and being skipped, or reaching the output gate with
- * no axis and being refused.
- */
 const SCALAR_CAPABILITY_AXES = {
     select: { kind: "flag" },
     filter: { kind: "tokens" },
@@ -420,7 +378,6 @@ const SCALAR_CAPABILITY_AXES = {
     create: { kind: "tokens" },
     update: { kind: "tokens" },
 };
-/** @see SCALAR_CAPABILITY_AXES — the same pin, on the relation surface. */
 const RELATION_CAPABILITY_AXES = {
     select: { kind: "scopes", axis: PROJECTION_SCOPES },
     include: { kind: "scopes", axis: PROJECTION_SCOPES },
@@ -437,8 +394,6 @@ const RELATION_CAPABILITY_AXES = {
 };
 function capabilityAxisFor(kind, key) {
     const axes = kind === "scalar" ? SCALAR_CAPABILITY_AXES : RELATION_CAPABILITY_AXES;
-    // An OWN key: the table is a plain object, and `axes["toString"]` would answer
-    // with a prototype method rather than with "no axis".
     return Object.hasOwn(axes, key) ? axes[key] : undefined;
 }
 function unavailableCapability(path, message, diagnostics) {
@@ -456,10 +411,6 @@ function narrowedScopes(axis, holdsAtScope, requested, key, path, diagnostics) {
     if (requested.length === 0) {
         return { outcome: "denied" };
     }
-    // Membership of the axis is asked first, and of the axis ARRAY rather than of a
-    // literal: the unqualified baseline holds at every position, so a position that
-    // is not a position at all would pass the `holdsAt` read and be written into the
-    // Contract. The type forbids it; a configuration assembled at runtime does not.
     const unavailable = requested.filter((scope) => !axis.includes(scope) || !holdsAtScope(scope));
     if (unavailable.length > 0) {
         unavailableCapability(path, `capability "${key}" requested unavailable scopes: ${unavailable.join(", ")}`, diagnostics);
@@ -467,12 +418,6 @@ function narrowedScopes(axis, holdsAtScope, requested, key, path, diagnostics) {
     }
     return { outcome: "narrowed", scopes: [...requested] };
 }
-/**
- * A projection member narrowed by position. The baseline is consulted through
- * {@link holdsAt} rather than by inspecting the member's arm, so the unqualified
- * baseline keeps meaning *holds in every position* and a narrowing against it is a
- * narrowing rather than a mismatch.
- */
 function applyScopeRestriction(axis, baselineValue, current, key, requested, path, diagnostics) {
     const baseline = baselineValue;
     const narrowing = narrowedScopes(axis, (scope) => holdsAt(baseline, scope), requested, key, path, diagnostics);
@@ -485,19 +430,6 @@ function applyScopeRestriction(axis, baselineValue, current, key, requested, pat
     }
     current[key] = narrowing.scopes;
 }
-/**
- * A scope-qualified token member narrowed on either axis, or both. The tokens and
- * the positions are read through the shape owners — {@link advertisedDirectives} /
- * {@link advertisedReducers} for the token list, and the `…At` pair for the
- * positions — so the two arms of the Contract member are never destructured here.
- *
- * A token-only narrowing **keeps the qualifier the baseline carries**: narrowing
- * what may be written is not a statement about where it may be written, and
- * dropping the qualifier would widen the member to every position (C-855).
- *
- * Answers whether the restriction was a shape this member admits at all. `false`
- * leaves the diagnostic to the caller, which owns the one message for every axis.
- */
 function applyScopedTokenRestriction(tokenKey, axis, baselineValue, current, key, value, path, diagnostics) {
     const requestedTokens = Array.isArray(value)
         ? value
@@ -546,18 +478,11 @@ function applyScopedTokenRestriction(tokenKey, axis, baselineValue, current, key
     return true;
 }
 function applyCapabilityRestriction(fieldKind, inherited, restoration, current, key, value, path, diagnostics) {
-    // Denial needs no baseline: a layer may always refuse to carry a capability
-    // forward, including one an earlier layer already removed.
     if (value === false) {
         delete current[key];
         return;
     }
     const axis = capabilityAxisFor(fieldKind, key);
-    // The member is measured against what this layer INHERITED when it inherited
-    // one, and against the root baseline only when it inherited none — the one
-    // split, by role, that every arm below reads through (F-815, LayerBaselines).
-    // The operations axis draws the same line: an advertised variant keeps what it
-    // carries, an absent one is restored.
     const baselineValue = inherited?.[key] ?? restoration[key];
     if (axis === undefined ||
         baselineValue === undefined ||
@@ -565,13 +490,6 @@ function applyCapabilityRestriction(fieldKind, inherited, restoration, current,
         unavailableCapability(path, `capability "${key}" is not available in the canonical baseline`, diagnostics);
         return;
     }
-    // `true` takes the measured answer VERBATIM, qualifier included: what this layer
-    // inherited when there is one — *available, as narrowed above me* — and the
-    // root baseline's answer when the member is being restored. Preserving a
-    // qualified capability is not widening it — the distinction the operations axis
-    // draws between preserving a descriptor and replacing it with the unqualified
-    // arm — and the clone is of the ceiling this layer is measured against, so it
-    // can never exceed it.
     if (value === true) {
         current[key] = cloneValue(baselineValue);
         return;
@@ -640,11 +558,6 @@ function applyOperationRestrictions(restoration, current, restrictions, path, di
                 diagnostics.push(diagnostic("COMPILER_UNAVAILABLE_OPERATION", `${path}.${family}.${variant}`, `operation "${family}.${variant}" is not available in the canonical baseline`));
                 continue;
             }
-            // An already-advertised variant keeps the availability this projection
-            // carries: an earlier layer may have narrowed `true` to a descriptor, and
-            // later layers only narrow (C-858). Only a variant this scope restores
-            // takes the baseline's availability, cloned so that no two projections
-            // share one descriptor object.
             const target = currentFamily;
             if (!isOperationVariantAvailable(target[variant])) {
                 target[variant] = cloneValue(baselineAvailability);
@@ -742,9 +655,6 @@ function reconcileIdentifiers(resource, baseline, restrictions) {
             : undefined;
         if (isOperationVariantAvailable(baselineAvailability)) {
             const targetFamily = isRecord(currentFamily) ? currentFamily : {};
-            // Restoring the variant must not restate its availability: a variant this
-            // projection still advertises keeps the descriptor it carries, and one
-            // identifiers bring back takes the baseline's, cloned per projection.
             if (!isOperationVariantAvailable(targetFamily[variant])) {
                 targetFamily[variant] = cloneValue(baselineAvailability);
             }
@@ -799,11 +709,6 @@ function validateFieldLifecycle(field, path, diagnostics) {
         }
     }
     if (lifecycle.includes("VIRTUAL") &&
-        // Not `=== true`: a projection member may carry the scopes it holds in, and a
-        // field selectable in one scope needs an effective read behavior exactly as
-        // much as one selectable in every scope. The question is scope-blind because
-        // this check has no scope — `holdsInAnyScope` is the shape owner's name for
-        // that, so there is no hand-rolled comparison here either.
         holdsInAnyScope(capabilities.select) &&
         !lifecycle.includes("COMPUTED_ON_READ")) {
         diagnostics.push(diagnostic("COMPILER_MISSING_READ_BEHAVIOR", path, "selectable VIRTUAL field requires an effective read behavior"));
@@ -812,13 +717,6 @@ function validateFieldLifecycle(field, path, diagnostics) {
 function isTokenList(value) {
     return (Array.isArray(value) && value.every((entry) => typeof entry === "string"));
 }
-/**
- * Why a position list is not one the Contract can carry on this axis, or
- * `undefined` when it is. Empty is refused for the reason `ProjectionScopes` and
- * `WriteScopes` give — absent is already the one encoding of unavailable (C-843) —
- * and membership is asked of the axis ARRAY, so a position from the other axis is
- * as off-axis as a string that is no position at all.
- */
 function positionListFault(axis, positions) {
     if (positions.length === 0) {
         return "an empty position list";
@@ -828,17 +726,6 @@ function positionListFault(axis, positions) {
         ? `positions not on its axis: ${offAxis.join(", ")}`
         : undefined;
 }
-/**
- * Why a member value is not a shape its axis admits, or `undefined` when it is —
- * each arm the Contract type declares for that axis, and nothing else.
- *
- * Shape only. Whether the value is NARROWER than the layer it derives from is
- * C-858's question, and the restriction walk already answers it against
- * {@link LayerBaselines} (F-815); asking it again here would be the same rule in a
- * second place. Token vocabularies are not checked either: the token unions are
- * types with no runtime registry, and inventing one here would be a second source
- * of truth for them.
- */
 function representationFault(axis, value) {
     switch (axis.kind) {
         case "flag":
@@ -867,21 +754,8 @@ function representationFault(axis, value) {
         }
     }
 }
-/**
- * The output gate (F-816): every capability member a finished projection carries
- * is checked against the member-to-axis table before the projection can be hashed.
- *
- * The projection is assembled from configuration that may be built at runtime and
- * from an adapter model that is a runtime value, and two of the walks that assemble
- * it copy a member verbatim; the canonicalizer orders what it is handed and
- * deliberately rewrites nothing it does not recognise. So the type is not the
- * guard, the producers are not the guard, and without this the compiler emits —
- * and hashes — whatever its walks assembled.
- */
 function validateCapabilityRepresentation(field, path, diagnostics) {
     for (const [key, value] of Object.entries(field.capabilities)) {
-        // No `undefined` skip: an own property holding no value is not canonical JSON,
-        // and skipping it here hands the canonicalizer a throw instead of a diagnostic.
         const axis = capabilityAxisFor(field.kind, key);
         const fault = axis === undefined
             ? "no capability axis covers it"
@@ -953,7 +827,6 @@ function projectDerivedScope(model, scopeName, core, scope, diagnostics) {
     validateProjection(projection, baseline, scopeName, scope.restrictions, diagnostics);
     return projection;
 }
-/** Compile Core first, then derive Application and Client from the Core compilation lineage. */
 export async function compileContracts(model, config) {
     const compilerConfig = config;
     const diagnostics = [];
@@ -974,11 +847,6 @@ export async function compileContracts(model, config) {
         ...clientHashInput,
         protocol: { version: AVENTARA_PROTOCOL_VERSION, hash },
     });
-    // R3 (Phase 10): the server checks its own ClientContract before serving
-    // it — here, so construction fails before listen, and every consumer
-    // (`framework.client`, `/_transactions`, `/_contract`, the generator)
-    // reads a value that passed. A refusal is a framework bug or an Adapter
-    // defect the projection copied through, never a caller's.
     const structure = validateClientContractStructure(client);
     if (!structure.valid) {
         return {

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

@@ -28,8 +28,8 @@ export type ResolvedFrameworkScopeConfig<M extends AdapterModel = AdapterModel>
 };
 export type ResolvedFrameworkConfig<M extends AdapterModel = AdapterModel> = {
     /**
-     * The mount path in its canonical form (R4, F-822): `""` 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)*`.
+     * Normalized once, here; every reader sees this.
      */
     readonly entrypoint: string;
     readonly adapter: Adapter<M>;

package/dist/config/config.resolver.js

@@ -77,10 +77,6 @@ function resolveScope(root, scoped) {
         pipelines: resolvePipelines(root.pipelines, scoped?.pipelines),
     };
 }
-/**
- * The entrypoint's canonical mount path. Validation refuses a non-canonical one
- * first; a caller that resolves without validating meets the same diagnostic.
- */
 function resolveEntrypoint(entrypoint) {
     const normalized = normalizeEntrypoint(entrypoint);
     if (!normalized.ok) {
@@ -90,7 +86,6 @@ function resolveEntrypoint(entrypoint) {
     }
     return normalized.path;
 }
-/** Resolve root, application, and client configuration without compiling Contracts. */
 export function resolveFrameworkConfig(config) {
     const root = {
         ...(hasOwn(config, "fields") ? { fields: config.fields } : {}),

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

@@ -1,8 +1,8 @@
 import type { ConfigDiagnostic } from "./config-diagnostic.js";
 /**
- * The refusal of an entrypoint whose mount path is not canonical (R4, F-822,
- * Q15), from the normalizer's message: it names the defect and the rule —
- * never the value, which may carry credentials.
+ * 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.
  */
 export declare function entrypointRefusalDiagnostic(message: string): ConfigDiagnostic;
 /** Validate framework-owned authoring structure; later semantic leaves remain opaque. */

package/dist/config/config.validator.js

@@ -47,11 +47,6 @@ function isPlainRecord(value) {
 function diagnostic(code, path, message) {
     return { code, path, message };
 }
-/**
- * The refusal of an entrypoint whose mount path is not canonical (R4, F-822,
- * Q15), from the normalizer's message: it names the defect and the rule —
- * never the value, which may carry credentials.
- */
 export function entrypointRefusalDiagnostic(message) {
     return diagnostic("CONFIG_INVALID_VALUE", "entrypoint", `entrypoint ${message}`);
 }
@@ -151,8 +146,6 @@ function validateAdapter(value, diagnostics) {
         return;
     }
     const adapter = value;
-    // One property read, not two: `adapter.model` is a property of the
-    // adapter, so validation must not observe it more times than it needs.
     const model = adapter.model;
     if (model === null || typeof model !== "object") {
         diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "adapter.model", "adapter.model must be an object"));
@@ -165,7 +158,6 @@ function validateAdapter(value, diagnostics) {
         diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "adapter.transaction", "adapter.transaction must be a function when provided"));
     }
 }
-/** Validate framework-owned authoring structure; later semantic leaves remain opaque. */
 export function validateFrameworkConfig(value) {
     const diagnostics = [];
     if (!isPlainRecord(value)) {

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

@@ -28,13 +28,8 @@ export type AddedScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit
 /**
  * The shape one authored field name admits, by what the adapter knows of it.
  *
- * `string extends AdapterFieldKey<M, R>` is the wide default, and is
- * load-bearing for B4 exactly as it is in `FieldRestrictionsFor`: against an
- * abstract `AdapterModel` the discovered key set is erased to `string`, so
- * every name would otherwise land in the adapter-known bucket and every
- * added field would be rejected for carrying a `type`. Where there is no
- * discovered key set to discriminate on, the answer is today's undivided
- * {@link FrameworkScalarFieldConfig}.
+ * Where there is no discovered key set to discriminate on, the answer is today's
+ * undivided {@link FrameworkScalarFieldConfig}.
  */
 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";

package/dist/config/define-fields.js

@@ -1,18 +1,3 @@
-/**
- * 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 function defineFields(_model, fields) {
     return fields;
 }

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

@@ -26,9 +26,8 @@ type FieldsBlockKey<Block, R extends string> = [Block] extends [never] ? 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 (B4).
+ * 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.
  */
 export type ConfigFieldKey<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = FieldsBlockKey<FieldsBlockOf<Cfg>, R>;
 /**
@@ -37,11 +36,8 @@ export type ConfigFieldKey<M extends AdapterModel, Cfg, R extends FrameworkResou
  * 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 field hidden by
- * `restrictions` stays present in the narrowed key set, per ADR 0009's
- * Consequences: restriction is projection policy applied at compilation, not
- * a change to the resource's field identity. A `HiddenFieldKey` subtraction
- * would contradict the Accepted ADR and must not be reintroduced.
+ * There is deliberately no subtraction here. A `HiddenFieldKey` subtraction would
+ * contradict the Accepted ADR and must not be reintroduced.
  */
 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. */

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

@@ -1,8 +1,8 @@
 /**
- * The framework entrypoint's mount path, in its one canonical form (R4, F-822,
- * Q15): `""` 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}`;
 /**
@@ -27,7 +27,7 @@ export type EntrypointNormalization = {
 };
 /**
  * `AvProtocol.normalizeEntrypoint` — a mount path, as written, to its canonical
- * form or a refusal (R4, F-822, Q15).
+ * 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_`
@@ -36,8 +36,8 @@ export type EntrypointNormalization = {
  * 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
+ * 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`.
  */

package/dist/config/entrypoint.normalizer.js

@@ -1,4 +1,3 @@
-/** What a canonical segment is, stated once for every refusal's message. */
 const MOUNT_PATH_RULE = "a mount path is /-separated segments of ASCII letters, digits and -._~!$&'()*+,;=:@ only";
 const DEFECTS = {
     whitespace: "contains whitespace",
@@ -12,12 +11,7 @@ const DEFECTS = {
     "percent-encoding": "contains a percent sign, and percent-encoding is refused",
     character: "contains a character a path segment may not carry unencoded",
 };
-/**
- * RFC 3986 `pchar` without `%` (Q15): unreserved, sub-delims, `:` and `@`. A
- * canonical segment is one or more of these and nothing else.
- */
 const CANONICAL_SEGMENT = /^[A-Za-z0-9\-._~!$&'()*+,;=:@]+$/u;
-/** `.` or `..`, spelled as URL resolution recognises it: `.` or `%2e`, any case. */
 const DOT_SEGMENT = /^(?:\.|%2e)$/iu;
 const DOT_DOT_SEGMENT = /^(?:\.|%2e){2}$/iu;
 function refusal(reason) {
@@ -27,22 +21,6 @@ function refusal(reason) {
         message: `${DEFECTS[reason]}; ${MOUNT_PATH_RULE}`,
     };
 }
-/**
- * `AvProtocol.normalizeEntrypoint` — a mount path, as written, to its canonical
- * form or a refusal (R4, F-822, Q15).
- *
- * 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`.
- */
 export function normalizeEntrypoint(value) {
     if (/\s/u.test(value))
         return refusal("whitespace");