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

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

@@ -10,13 +10,13 @@ export type FrameworkFieldBehaviorConfig<M extends AdapterModel = AdapterModel,
     readonly read?: false | FrameworkReadBehavior<M, Cfg, R>;
 };
 /**
- * Executable behavior bindings for one Resource, keyed on the single
- * effective field-key answer.
+ * Executable behavior bindings for one Resource, keyed on the single effective
+ * field-key answer.
  *
- * `Partial` is required, not cosmetic: a mapped type over a literal key set
- * would otherwise demand a binding for every field of the Resource. Under the
- * default `Cfg` the key set is `string`, the mapped half collapses to one
- * index signature and today's wide acceptance is preserved (B4).
+ * `Partial` is required, not cosmetic: a mapped type over a literal key set would
+ * otherwise demand a binding for every field of the Resource. Under the default
+ * `Cfg` the key set is `string`, the mapped half collapses to one index signature
+ * and today's wide acceptance is preserved.
  */
 export type FrameworkResourceBehaviorsConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = {
     readonly fields: Readonly<Partial<{

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

@@ -13,11 +13,9 @@ export type FrameworkLimitsConfig = Partial<ContractLimits>;
 /**
  * Configuration available at root and at application/client scopes.
  *
- * `Cfg` is the authored configuration literal this scope belongs to. Both
- * `restrictions` and `behaviors` read it, keying each Resource's field names
- * on `EffectiveFieldKey`; `pipelines` joins them at S7. Under the default
- * `AnyFrameworkConfig` the effective key set degenerates to `string`, so an
- * unannotated `FrameworkScopeConfig<M>` behaves exactly as it did before.
+ * `Cfg` is the authored configuration literal this scope belongs to. Under the
+ * default `AnyFrameworkConfig` the effective key set degenerates to `string`, so
+ * an unannotated `FrameworkScopeConfig<M>` behaves exactly as it did before.
  */
 export type FrameworkScopeConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
     readonly fields?: FrameworkFieldsConfig<M>;

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

@@ -7,27 +7,21 @@ import type { FrameworkResourceKey } from "./framework-fields-config.js";
 export type FrameworkCapabilitySetRestriction<T extends string> = boolean | readonly T[];
 /**
  * A restriction on a scope-qualified projection member: `select` and `include` on
- * a relation, where the capability is a POSITION list and carries no tokens at all.
+ * a relation, where the capability is a POSITION list and carries no tokens at
+ * all.
  *
  * Three operations, and they are three because narrowing a qualified capability is
  * not one thing:
  *
  * - `false` **denies** the capability — the member leaves the projection.
  * - a scope list **removes positions** — the member survives, reachable in fewer
- *   argument positions. Only positions the canonical baseline already advertises
- *   may be named: C-858, *"later layers only narrow"*, and naming one it does not
- *   is `COMPILER_UNAVAILABLE_CAPABILITY`, a compiler diagnostic rather than a type
- *   error, because a Contract is compiled from configuration that may be assembled
- *   at runtime.
- * - `true` **restores** the baseline member, qualifier included. Restoring a
- *   qualified member is not widening it — the same distinction S2b drew on the
- *   operations axis, where preserving a descriptor is narrowing-safe and replacing
- *   one with the unqualified arm is not.
+ *   argument positions.
+ * - `true` **restores** the baseline member, qualifier included.
  *
  * The **empty** list is the fourth operation written as a degenerate third: a
  * capability narrowed to no position is a capability that is not available, and
  * `ProjectionScopes` cannot represent an empty list, so the compiler denies the
- * member rather than emitting a second encoding of "absent" (C-843).
+ * member rather than emitting a second encoding of "absent".
  */
 export type FrameworkProjectionScopeRestriction = boolean | readonly ProjectionScope[];
 /**
@@ -128,34 +122,30 @@ type AdapterFieldRestrictionsFor<TField> = TField extends {
     readonly kind: "relation";
 } ? FrameworkRelationFieldRestrictions : FrameworkFieldRestrictions;
 /**
- * The restriction shape one effective field name admits. Three cases, in
- * order.
+ * The restriction shape one effective field name admits. Three cases, in order.
  *
- * `string extends F` is the wide default. Under `AnyFrameworkConfig`,
- * {@link EffectiveFieldKey} degenerates to `string`, the mapped type below
- * collapses to a single index signature and no field identity survives to
- * discriminate on. Today's wide acceptance is preserved there deliberately
- * (B4): narrowing below the resource key is opt-in, never imposed.
+ * `string extends F` is the wide default. Under `AnyFrameworkConfig`, {@link
+ * EffectiveFieldKey} degenerates to `string`, the mapped type below collapses to a
+ * single index signature and no field identity survives to discriminate on.
+ * Today's wide acceptance is preserved there deliberately: narrowing below the
+ * resource key is opt-in, never imposed.
  *
  * An adapter-discovered name is discriminated by the model's own `kind`.
  *
- * Anything else is a name the configuration's own `fields` block added. Per
- * the target type graph an added field is an added *scalar* field — there is
- * no configuration surface that authors a relation — so the answer is
- * {@link FrameworkScalarFieldRestrictions}. It is deliberately not the
- * undiscriminated {@link FrameworkFieldRestrictions}: falling back to that
- * union would reopen F-602 for exactly the fields `Cfg` was threaded here to
- * make nameable.
+ * Anything else is a name the configuration's own `fields` block added. Per the
+ * target type graph an added field is an added *scalar* field — there is no
+ * configuration surface that authors a relation — so the answer is {@link
+ * FrameworkScalarFieldRestrictions}.
  */
 type FieldRestrictionsFor<M extends AdapterModel, R extends FrameworkResourceKey<M>, F extends string> = string extends F ? FrameworkFieldRestrictions : F extends AdapterFieldKey<M, R> ? AdapterFieldRestrictionsFor<M["resources"][R]["fields"][F]> : FrameworkScalarFieldRestrictions;
 /**
  * Projection policy for one Resource's fields, keyed on the single effective
  * field-key answer.
  *
- * F-602 closed here. This type used to intersect the mapped half with
- * `Readonly<Record<string, FrameworkFieldRestrictions>>`, whose index
- * signature absorbed every field name the model does not declare. The
- * catch-all is gone: a name must be an adapter field or one `Cfg` adds.
+ * This type used to intersect the mapped half with `Readonly<Record<string,
+ * FrameworkFieldRestrictions>>`, whose index signature absorbed every field name
+ * the model does not declare. The catch-all is gone: a name must be an adapter
+ * field or one `Cfg` adds.
  */
 export type FrameworkResourceFieldRestrictions<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = Readonly<Partial<{
     [F in EffectiveFieldKey<M, Cfg, R>]: FieldRestrictionsFor<M, R, F>;

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

@@ -3,9 +3,7 @@ import type { AfterHook, BeforeHook, Filter, Guard, Interceptor, Pipe } from "..
 /**
  * Pipeline registrations for one configuration scope.
  *
- * Takes `M` only, not `<M, Cfg>` as B8 proposed: nothing a pipeline callback
- * is handed is field-keyed, so the authored configuration literal has nothing
- * to narrow here. See {@link PipelineContext}.
+ * See {@link PipelineContext}.
  */
 export type PipelineConfig<M extends AdapterModel = AdapterModel> = {
     readonly guards?: readonly Guard<M>[];
@@ -20,22 +18,14 @@ export type PipelineConfig<M extends AdapterModel = AdapterModel> = {
 /**
  * Fully normalized pipeline registration lists after scope composition.
  *
- * **Un-parameterized, deliberately, and not `ResolvedPipelineConfig<M, Cfg>`
- * as B12 proposed.** Resolution is where narrowing ends. The runtime builds
- * every pipeline context from `FrameworkOperationRequest.resource`, which is
- * a `string` off the wire, so it can never recover which literal it is
- * holding — the same reason `ResolvedFrameworkScopeConfig.behaviors` holds
- * the erased `FrameworkBehaviorsConfig`, and the same boundary ADR 0009 puts
- * contract compilation behind. Parameterizing this type would let `M` flow
- * past `resolveFrameworkConfig` into a runtime that cannot honour it, and
- * would force a cast at the context factory to manufacture a literal the
- * request does not carry.
+ * Parameterizing this type would let `M` flow past `resolveFrameworkConfig` into a
+ * runtime that cannot honour it, and would force a cast at the context factory to
+ * manufacture a literal the request does not carry.
  *
- * Unlike `behaviors`, erasing here costs nothing at the type level: `M`
- * occurs in these callbacks *only* in parameter position, never as a
- * mapped-type key, so `PipelineConfig<M>` is accepted where the erased form
- * is required and `resolvePipelines` composes the authored lists with no
- * cast at all.
+ * Unlike `behaviors`, erasing here costs nothing at the type level: `M` occurs in
+ * these callbacks *only* in parameter position, never as a mapped-type key, so
+ * `PipelineConfig<M>` is accepted where the erased form is required and
+ * `resolvePipelines` composes the authored lists with no cast at all.
  */
 export type ResolvedPipelineConfig = {
     readonly guards: readonly Guard[];

package/dist/contracts/capability.d.ts

@@ -7,24 +7,22 @@ export type RelationReducer = "$count";
 /**
  * Where a projected field may be asked for: the kind of argument POSITION a
  * projection sits in, not the operation that carries it. A variant states the
- * position its projection arguments sit in (`OperationScopes`); a field
- * states the positions it is projectable in. The axis is closed at two because
- * two is what both pilot engines answer — a third position would have to be
- * measured, not supposed.
+ * position its projection arguments sit in (`OperationScopes`); a field states the
+ * positions it is projectable in. The axis is closed at two because two is what
+ * both pilot engines answer — a third position would have to be measured, not
+ * supposed.
  *
  * **A scope qualifies the TOP LEVEL of a projection only. It does not narrow
  * recursively.** Measured at runtime on both pilot engines, 2026-10-03, not
- * inferred from types: a bulk-returning write accepted
- * `include: { <owned to-one>: { include: { <to-many>: true } } }` and populated
- * the rows (the nested to-many returned its 3 rows and a full reducer object),
- * while the SAME to-many asked for at depth 1 was refused outright. The reason is
- * visible in the generated types: a bulk projection types an admitted relation as
- * the *unrestricted* projection argument, so the full surface returns one level
- * in.
+ * inferred from types: a bulk-returning write accepted `include: { <owned to-one>:
+ * { include: { <to-many>: true } } }` and populated the rows (the nested to-many
+ * returned its 3 rows and a full reducer object), while the SAME to-many asked for
+ * at depth 1 was refused outright. The reason is visible in the generated types: a
+ * bulk projection types an admitted relation as the *unrestricted* projection
+ * argument, so the full surface returns one level in.
  *
  * A reader who assumes a scope narrows recursively will write a rule that refuses
- * what the ORM accepts. That breaches C-855 in the other direction, and
- * under-advertising is the same defect as over-advertising with the sign flipped.
+ * what the ORM accepts.
  *
  * # Why the axis is a value and the union is derived from it
  *
@@ -32,11 +30,10 @@ export type RelationReducer = "$count";
  * `TRANSACTION_CAPABILITIES` are, because one reader needs its **cardinality** at
  * runtime and not merely its member names: a scope list naming every member of the
  * axis says exactly what the unqualified arm says, so the canonicalizer collapses
- * it (C-843, and §4's rejection of one fact with two hashes). That reader asks
- * "does this list name every member of the axis?" against this array. A hardcoded
- * two would answer *yes* for a two-of-three list the day a third position is
- * measured, which widens every Contract carrying it and nothing downstream can
- * tell — so the derivation is load-bearing, not tidiness.
+ * it. That reader asks "does this list name every member of the axis?" against
+ * this array. A hardcoded two would answer *yes* for a two-of-three list the day a
+ * third position is measured, which widens every Contract carrying it and nothing
+ * downstream can tell — so the derivation is load-bearing, not tidiness.
  *
  * Declaration order is registry order and the canonicalizer orders scope lists by
  * it, the way it orders `pagination`.
@@ -47,8 +44,8 @@ export type ProjectionScope = (typeof PROJECTION_SCOPES)[number];
 /**
  * Where a field may be written: the kind of argument POSITION a write sits in, not
  * the operation that carries it. The mirror of {@link ProjectionScope} on the
- * mutation axis, and a separate union because the two axes are measured
- * separately — an adapter may narrow one without narrowing the other.
+ * mutation axis, and a separate union because the two axes are measured separately
+ * — an adapter may narrow one without narrowing the other.
  *
  * **A scope qualifies the TOP LEVEL of a write argument only. It does not narrow
  * recursively**, for the same reason {@link ProjectionScope} does not: past an
@@ -56,7 +53,7 @@ export type ProjectionScope = (typeof PROJECTION_SCOPES)[number];
  * `"bulkWrite"` admits no nested write at all, so today the rule has no admitted
  * top-level entry to apply beneath — it is stated because an adapter that admits
  * one must not then be narrowed a second level down, which would refuse what the
- * ORM accepts (C-855, sign flipped).
+ * ORM accepts.
  *
  * A value for the same reason {@link PROJECTION_SCOPES} is one, and a **separate**
  * array because the two axes are separate: a write scope list that names every

package/dist/contracts/capability.js

@@ -1,83 +1,8 @@
-/**
- * Where a projected field may be asked for: the kind of argument POSITION a
- * projection sits in, not the operation that carries it. A variant states the
- * position its projection arguments sit in (`OperationScopes`); a field
- * states the positions it is projectable in. The axis is closed at two because
- * two is what both pilot engines answer — a third position would have to be
- * measured, not supposed.
- *
- * **A scope qualifies the TOP LEVEL of a projection only. It does not narrow
- * recursively.** Measured at runtime on both pilot engines, 2026-10-03, not
- * inferred from types: a bulk-returning write accepted
- * `include: { <owned to-one>: { include: { <to-many>: true } } }` and populated
- * the rows (the nested to-many returned its 3 rows and a full reducer object),
- * while the SAME to-many asked for at depth 1 was refused outright. The reason is
- * visible in the generated types: a bulk projection types an admitted relation as
- * the *unrestricted* projection argument, so the full surface returns one level
- * in.
- *
- * A reader who assumes a scope narrows recursively will write a rule that refuses
- * what the ORM accepts. That breaches C-855 in the other direction, and
- * under-advertising is the same defect as over-advertising with the sign flipped.
- *
- * # Why the axis is a value and the union is derived from it
- *
- * The axis is written down exactly once, as `LIFECYCLE_TRAITS` and
- * `TRANSACTION_CAPABILITIES` are, because one reader needs its **cardinality** at
- * runtime and not merely its member names: a scope list naming every member of the
- * axis says exactly what the unqualified arm says, so the canonicalizer collapses
- * it (C-843, and §4's rejection of one fact with two hashes). That reader asks
- * "does this list name every member of the axis?" against this array. A hardcoded
- * two would answer *yes* for a two-of-three list the day a third position is
- * measured, which widens every Contract carrying it and nothing downstream can
- * tell — so the derivation is load-bearing, not tidiness.
- *
- * Declaration order is registry order and the canonicalizer orders scope lists by
- * it, the way it orders `pagination`.
- */
 export const PROJECTION_SCOPES = [
-    /**
-     * The unrestricted projection position: every row-returning read, and every
-     * row-returning write of one addressed record.
-     */
     "record",
-    /**
-     * The projection of the rows a BULK write returns, where the reachable set is
-     * narrower at the top level — on both pilot engines, only a relation the written
-     * row itself resolves. Named for the write being bulk and not for the row count:
-     * a multi-row READ projects in `"record"`.
-     */
     "bulkWrite",
 ];
-/**
- * Where a field may be written: the kind of argument POSITION a write sits in, not
- * the operation that carries it. The mirror of {@link ProjectionScope} on the
- * mutation axis, and a separate union because the two axes are measured
- * separately — an adapter may narrow one without narrowing the other.
- *
- * **A scope qualifies the TOP LEVEL of a write argument only. It does not narrow
- * recursively**, for the same reason {@link ProjectionScope} does not: past an
- * admitted entry the unrestricted surface returns. On both pilot engines
- * `"bulkWrite"` admits no nested write at all, so today the rule has no admitted
- * top-level entry to apply beneath — it is stated because an adapter that admits
- * one must not then be narrowed a second level down, which would refuse what the
- * ORM accepts (C-855, sign flipped).
- *
- * A value for the same reason {@link PROJECTION_SCOPES} is one, and a **separate**
- * array because the two axes are separate: a write scope list that names every
- * write position is degenerate, a write scope list that happens to have as many
- * members as the projection axis is not.
- */
 export const WRITE_SCOPES = [
-    /**
-     * The unrestricted write position: a write argument that admits nested writes of
-     * related records. `"nested"` is this repository's established word for "through
-     * a relation" — see {@link RelationFilterCapability}.
-     */
     "nested",
-    /**
-     * The data argument of a BULK write: the record's own columns and its own
-     * reference fields only.
-     */
     "bulkWrite",
 ];

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

@@ -1,9 +1,5 @@
 import type { ClientContract } from "./contract.js";
 /**
- * §15.3's *"validate ClientContract structure"*: whether an untrusted value IS a
- * `ClientContract` — every member present, of its JSON kind, inside its closed
- * vocabulary, and nothing else — before anything reads it as one.
- *
  * # Why core owns it
  *
  * The canonicalizer reads Contract members without validating them (it owns
@@ -15,30 +11,27 @@ import type { ClientContract } from "./contract.js";
  *
  * # One source of truth: the schema IS the type
  *
- * {@link CLIENT_CONTRACT_STRUCTURE} is a passive description, and
- * {@link Structured} decodes it into a TypeScript type. That decoded type must
- * be `ClientContract` exactly, in both directions:
+ * {@link CLIENT_CONTRACT_STRUCTURE} is a passive description, and {@link
+ * Structured} decodes it into a TypeScript type. That decoded type must be
+ * `ClientContract` exactly, in both directions:
  *
- * - **schema → type** is enforced here, at build time: the accepted arm hands
- *   back the decoded value as a `ClientContract` with no cast, so a schema that
- *   admits something the type does not fails to compile.
- * - **type → schema** is enforced by `client-contract-structure.validator.test-d.ts`:
- *   a schema that is stricter than the type — a vocabulary token missed, an
- *   optional member written as required — fails the type test.
+ * - **schema → type** is enforced here, at build time: the accepted arm hands back
+ *   the decoded value as a `ClientContract` with no cast, so a schema that admits
+ *   something the type does not fails to compile.
+ * - **type → schema** is enforced by
+ *   `client-contract-structure.validator.test-d.ts`: a schema that is stricter
+ *   than the type — a vocabulary token missed, an optional member written as
+ *   required — fails the type test.
  *
  * So a member added to, removed from or re-typed in core's ClientContract types
  * breaks the build or the type test until this schema says the same thing.
  *
  * # Where the line is
  *
- * The line is the TYPE, judged at the erased `ClientContract` (ADR 0009): what the
- * type admits is accepted, what it rules out is refused. Two consequences are
+ * The line is the TYPE, judged at the erased `ClientContract`: what the type
+ * admits is accepted, what it rules out is refused. Two consequences are
  * deliberate:
  *
- * - **Canonical-JSON encodability is not structure.** `number` admits `Infinity`
- *   and `string` admits a lone surrogate, so both pass here; canonicalization
- *   refuses them with `CanonicalJsonError` and its path, which is the existing
- *   §19.2 refusal (S0).
  * - **References are not structure.** At the erased type a relation `target`, a
  *   field's `{ scalar }`/`{ enum }` and an identifier's field keys are `string`,
  *   so a dangling reference passes. Referential consistency is a separate,
@@ -48,9 +41,9 @@ import type { ClientContract } from "./contract.js";
  * **an enum's values are distinct.** `readonly string[]` admits a repeat, but an
  * enum with one names a member twice — the generated client's `as const` object
  * would declare one key twice (TS1117) — so a repeat is refused at the second
- * occurrence, naming the first. The list node carries it as `unique`, which
- * {@link Structured} ignores, so the decoded type is still `ClientContract`
- * exactly. Every reader judges it here, once, rather than each re-checking it.
+ * occurrence, naming the first. The list node carries it as `unique`, which {@link
+ * Structured} ignores, so the decoded type is still `ClientContract` exactly.
+ * Every reader judges it here, once, rather than each re-checking it.
  *
  * The validator reads every member it judges and never throws on any input: a
  * value that is not JSON at all is reported, not crashed on.

package/dist/contracts/client-contract-structure.validator.js

@@ -14,7 +14,6 @@ function list(item) {
 function nonEmptyList(item) {
     return { is: "list", item, nonEmpty: true, unique: false };
 }
-/** A list of primitives in which no entry repeats an earlier one. */
 function uniqueList(item) {
     return { is: "list", item, nonEmpty: false, unique: true };
 }
@@ -27,12 +26,6 @@ function object(required, optional = {}) {
 function union(...arms) {
     return { is: "union", arms };
 }
-/*
- * The closed vocabularies `capability.ts` states as types only. Each array is
- * tied to its union by the type → schema check: a token missing here makes the
- * schema stricter than `ClientContract`, which fails the type test; a token not
- * in the union makes it looser, which fails the build.
- */
 const SCALAR_FILTER_OPERATORS = [
     "equals",
     "not",
@@ -168,7 +161,6 @@ const RESOURCE = object({
         upsert: object({}, { unique: OPERATION_AVAILABILITY }),
     }),
 });
-/** The structure of a ClientContract. Decodes to exactly `ClientContract`. */
 export const CLIENT_CONTRACT_STRUCTURE = object({
     scalars: registry(object({ builtin: literal([true]) })),
     enums: registry(object({ values: uniqueList(STRING) })),
@@ -186,14 +178,11 @@ export const CLIENT_CONTRACT_STRUCTURE = object({
         hash: { is: "prefixed", prefix: "sha256:" },
     }),
 });
-/** Judge whether `value` is a ClientContract. Never throws. */
 export function validateClientContractStructure(value) {
     const defect = defectOf(CLIENT_CONTRACT_STRUCTURE, value, "$", 0);
     if (defect !== undefined) {
         return { valid: false, path: defect.path, message: defect.message };
     }
-    // No cast to ClientContract: the decoded schema type must be assignable to it,
-    // which is the schema → type half of the one-source-of-truth check.
     const contract = value;
     return { valid: true, contract };
 }
@@ -265,7 +254,6 @@ function listDefect(node, value, path, depth) {
     if (node.nonEmpty && entries.length === 0) {
         return at(path, depth, "is an empty JSON array, and needs at least one entry");
     }
-    /** Each value's first index; read only when the list is `unique`. */
     const firstIndexOf = new Map();
     for (let index = 0; index < entries.length; index += 1) {
         const entryPath = `${path}[${index}]`;
@@ -283,13 +271,6 @@ function listDefect(node, value, path, depth) {
     }
     return undefined;
 }
-/**
- * A closed member set: every required member present, every present member
- * judged, and no member the type does not have. An unknown key is refused
- * rather than ignored — a reader that silently skipped part of an exact
- * Contract would be reading a different Contract, and keys outside
- * `protocol.version` are outside the hash, so nothing after this would see them.
- */
 function objectDefect(required, optional, value, path, depth) {
     const kind = kindDefect(value, "object", path, depth);
     if (kind !== undefined)
@@ -315,13 +296,6 @@ function objectDefect(required, optional, value, path, depth) {
         ? undefined
         : at(`${path}.${unknown}`, depth, "is not a member ClientContract has here");
 }
-/**
- * Accepted when any alternative accepts. An alternative whose JSON kind the value
- * does not have does not apply; among those that do, the refusal is the defect of
- * the one the value got furthest into, and where two got equally far no single
- * one is the better guess, so it names the position and lists both. When none
- * applies, the refusal names every kind that would have.
- */
 function unionDefect(arms, value, path, depth) {
     const defects = [];
     for (const arm of arms) {
@@ -351,7 +325,6 @@ function kindDefect(value, expected, path, depth) {
         ? undefined
         : mismatchAt(path, depth, describeValueKind(value), describeKind(expected));
 }
-/** Uses only `typeof` and `Array.isArray`, so it reads no property of the value. */
 function jsonKindOf(value) {
     if (value === null)
         return "null";

package/dist/contracts/contract-canonicalizer.js

@@ -3,12 +3,6 @@ import { LIFECYCLE_TRAITS } from "./lifecycle-trait.js";
 import { projectionScopeOf, writeScopeOf } from "./resource-operations.js";
 const PAGINATION_ORDER = ["limit", "offset", "cursor"];
 const REDUCER_ORDER = ["$count"];
-/**
- * Framework-owned rejection of a value JCS cannot represent. It extends
- * `TypeError` and keeps its inherited `name`, so existing `TypeError`
- * consumers and error text are unchanged, while callers that must attribute
- * a canonicalization failure to its input can recognize this class exactly.
- */
 export class CanonicalJsonError extends TypeError {
 }
 function compareCodeUnits(left, right) {
@@ -34,25 +28,6 @@ function normalizeStringSet(values, order) {
         return compareCodeUnits(left, right);
     });
 }
-/**
- * A scope list in canonical form: ordered as a set, or **`true`** where it names
- * every member of its axis.
- *
- * The collapse is the half of C-843 the type system cannot carry. A capability's
- * qualified arm and its unqualified arm are both live — an adapter that has not
- * measured the axis says `true`, and a Contract that predates the measurement keeps
- * its meaning — so a list naming every position says exactly what `true` says. Two
- * encodings of one semantic fact hash two ways, which is the ground the architect
- * rejected the flat-or-per-variant shape on, so canonical form picks one arm and it
- * is the unqualified one.
- *
- * "Names every member" is asked of the **axis array**, never of a literal count.
- * A hardcoded two would read a two-of-three list as unqualified the day a third
- * position is measured, silently widening every Contract that carried it — and
- * membership is tested as set EQUALITY rather than coverage, so a token that is not
- * on the axis at all (possible: this reads Contract data, not a checked type)
- * blocks the collapse instead of being absorbed by it.
- */
 function normalizeScopes(scopes, axis) {
     const normalized = normalizeStringSet(scopes, axis);
     const named = new Set(normalized);
@@ -62,20 +37,6 @@ function normalizeScopes(scopes, axis) {
 function isScopedArm(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/**
- * One scope-qualified capability arm in canonical form: its token list ordered as
- * the set it is, and its scope list ordered — or collapsed, which replaces the arm
- * with the bare token list, because that is this member's unqualified arm.
- *
- * The token list survives the collapse rather than being dropped: `directives: []`
- * means *"writable with no directive"* against an absent member's *"not writable
- * during this stage"*, two answers core already distinguishes, and the scope
- * qualifier may not merge them.
- *
- * Anything that is not this shape is returned untouched. The canonicalizer reads
- * Contract data and owns ordering, not validation — a member it does not recognize
- * is not a member it may rewrite.
- */
 function normalizeScopedArm(arm, tokenKey, tokenOrder, axis) {
     const tokens = arm[tokenKey];
     const scopes = arm.scopes;
@@ -90,8 +51,6 @@ function normalizeScopedArm(arm, tokenKey, tokenOrder, axis) {
 }
 function normalizeCapabilities(capabilities) {
     const normalized = { ...capabilities };
-    // Projection members: `boolean` unqualified, a scope list qualified. The
-    // boolean arm is already canonical, and a scalar `select` is only ever boolean.
     for (const key of ["select", "include"]) {
         const value = normalized[key];
         if (Array.isArray(value)) {
@@ -102,8 +61,6 @@ function normalizeCapabilities(capabilities) {
     if (Array.isArray(filter)) {
         normalized.filter = normalizeStringSet(filter);
     }
-    // Mutation stages: a bare directive list unqualified, `{ directives, scopes }`
-    // qualified. Scalar capabilities only ever carry the bare list.
     for (const key of ["create", "update"]) {
         const value = normalized[key];
         if (Array.isArray(value)) {
@@ -139,47 +96,11 @@ function normalizeField(field) {
         capabilities: normalizeCapabilities(field.capabilities),
     };
 }
-/**
- * Every key an operation availability descriptor may state, each paired with the
- * reader that answers what that key MEANS.
- *
- * The readers are the pair core already validates with, so this table is a list of
- * the axes the canonicalizer understands rather than a second definition of them.
- * A descriptor key absent from it is a key whose meaning this file does not know.
- */
 const VARIANT_SCOPE_READERS = [
     ["projection", projectionScopeOf],
     ["write", writeScopeOf],
 ];
 const VARIANT_SCOPE_KEYS = new Set(VARIANT_SCOPE_READERS.map(([key]) => key));
-/**
- * One operation availability leaf in canonical form: **`true`** where the descriptor
- * states nothing beyond what `true` states, and otherwise the descriptor untouched.
- *
- * This is S4's collapse on the operations axis. `OperationAvailability` is
- * `true | OperationVariantScopes`, both arms are live — an adapter that has not
- * measured the axes says `true`, and a Contract that predates the measurement keeps
- * its meaning — so a descriptor whose scopes are the ones `true` already means is a
- * second encoding of one semantic fact, and two encodings hash two ways. That is the
- * ground §4 rejected the flat-or-per-variant shape on, so canonical form picks one
- * arm and it is the unqualified one.
- *
- * **Redundant is asked of the READERS, never of a scope literal or an axis
- * cardinality.** `projectionScopeOf` and `writeScopeOf` are what a descriptor means
- * to everyone who consults it, so a descriptor says nothing beyond `true` exactly
- * when both answer for it what they answer for `true`. Deriving it this way is what
- * makes the eager-collapse failure mode unreachable: a descriptor stating any
- * narrower position — `projection: "bulkWrite"`, `write: "bulkWrite"`, a third
- * position measured later, or a token that is not on its axis at all (possible: this
- * reads Contract data, not a checked type) — moves a reader's answer and therefore
- * blocks the collapse, with nothing here to keep in sync. A collapse keyed on the
- * literal `"record"`/`"nested"` pair, or on "the descriptor fills every key, so it is
- * fully specified", would widen Contracts and leave nothing downstream able to tell.
- *
- * A descriptor stating a key no reader covers is returned untouched for the reason
- * {@link normalizeScopedArm} gives: the canonicalizer owns ordering, not validation,
- * and a key it does not recognize is not a key it may decide is redundant.
- */
 function normalizeOperationAvailability(availability) {
     if (!isScopedArm(availability)) {
         return availability;
@@ -192,17 +113,6 @@ function normalizeOperationAvailability(availability) {
     const saysNothingBeyondTrue = VARIANT_SCOPE_READERS.every(([, scopeOf]) => scopeOf(availability) === scopeOf(true));
     return saysNothingBeyondTrue ? true : availability;
 }
-/**
- * A Resource's advertised operations in canonical form: every availability leaf
- * canonicalized, and the tree otherwise as it was.
- *
- * Nothing here is sorted. The family and variant keys are object keys, which JCS
- * orders at encoding time, and the descriptor's own two keys are object keys for the
- * same reason — key order was never the defect, a redundant *encoding* was.
- *
- * A family that is not a plain object is returned untouched, which keeps this a
- * canonicalizer and not a validator.
- */
 function normalizeOperations(operations) {
     if (!isScopedArm(operations)) {
         return operations;
@@ -233,10 +143,6 @@ function normalizeResource(resource) {
         operations: normalizeOperations(resource.operations),
     };
 }
-/**
- * Normalize semantic sets and registry order while preserving arrays whose
- * order changes meaning, such as enum values and identifier field tuples.
- */
 function normalizeContract(contract) {
     const scalars = Object.fromEntries(Object.keys(contract.scalars)
         .sort(compareCodeUnits)
@@ -320,11 +226,9 @@ function canonicalizeValue(value, path) {
     });
     return `{${entries.join(",")}}`;
 }
-/** RFC 8785/JCS-compatible canonical encoding for JSON-safe Aventara data. */
 export function canonicalizeJson(value) {
     return canonicalizeValue(value, "$");
 }
-/** Canonical semantic representation used for deterministic Contract output. */
 export function canonicalizeContract(contract) {
     return canonicalizeJson(normalizeContract(contract));
 }

package/dist/contracts/contract-hash.js

@@ -9,7 +9,6 @@ export function createClientContractHashInput(contract) {
 function digestHex(digest) {
     return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
-/** Compute exact ClientContract identity with protocol.hash excluded. */
 export async function computeClientContractHash(contract) {
     const input = createClientContractHashInput(contract);
     const canonical = canonicalizeContract(input);
@@ -17,7 +16,6 @@ export async function computeClientContractHash(contract) {
     const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
     return `sha256:${digestHex(digest)}`;
 }
-/** Recompute and compare the advertised ClientContract identity. */
 export async function verifyClientContractHash(contract) {
     return (await computeClientContractHash(contract)) === contract.protocol.hash;
 }