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

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

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

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

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

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

@@ -3,43 +3,46 @@ import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { ContractLimits } from "../contracts/contract-limits.js";
 import type { TransactionCapability } from "../contracts/transaction-capability.js";
 import type { FrameworkDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
+import type { FrameworkMisuseSink } from "../runtime/misuse-reporter.js";
 import type { AnyFrameworkConfig } from "./any-framework-config.js";
 import type { FrameworkBehaviorsConfig } from "./framework-behaviors-config.js";
 import type { FrameworkFieldsConfig } from "./framework-fields-config.js";
 import type { FrameworkRestrictionsConfig } from "./framework-restrictions-config.js";
 import type { PipelineConfig } from "./pipeline-config.js";
-/** Authoring limits remain partial until compilation resolves framework defaults. */
+/**
+ * Request limits to override; each one left out takes its default from
+ * {@link DEFAULT_CONTRACT_LIMITS}.
+ */
 export type FrameworkLimitsConfig = Partial<ContractLimits>;
 /**
- * Configuration available at root and at application/client scopes.
- *
- * `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.
+ * Settings available at the root and in the `application` and `client`
+ * overlays. A setting in an overlay replaces the root's for that origin;
+ * pipelines are added to the root's instead.
  */
 export type FrameworkScopeConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
+    /** Fields to add to Resources, or details to set on discovered fields. */
     readonly fields?: FrameworkFieldsConfig<M>;
+    /** Computed values and read behaviors, per Resource and field. */
     readonly behaviors?: FrameworkBehaviorsConfig<M, Cfg>;
+    /** What to hide or narrow: Resources, fields, capabilities and operations. */
     readonly restrictions?: FrameworkRestrictionsConfig<M, Cfg>;
+    /** Request limits; see {@link FrameworkLimitsConfig}. */
     readonly limits?: FrameworkLimitsConfig;
-    readonly pipelines?: PipelineConfig<M>;
+    /** Guards, pipes, hooks, interceptors and filters run around each operation. */
+    readonly pipelines?: PipelineConfig<NoInfer<M>>;
+    /** `"none"` turns transactions off; `"interactive"` needs adapter support. */
     readonly transactions?: TransactionCapability;
 };
 /**
- * Aventara authoring configuration.
- *
- * Root properties are the root/core/default source. There is intentionally no
- * `core` namespace; `application` and `client` are scoped overlays.
- *
- * `diagnostics` is deliberately root-only and absent from
- * {@link FrameworkScopeConfig}: the framework owns the channel that reports
- * the developer's own unplanned failures, so it is neither scoped, ordered,
- * composable nor overridable.
+ * The configuration passed to `createFramework`: the adapter, the mount path,
+ * root settings, and optional `application` and `client` overlays.
  */
 export type FrameworkConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = FrameworkScopeConfig<M, Cfg> & {
     readonly entrypoint: string;
     readonly adapter: Adapter<M>;
     readonly diagnostics?: FrameworkDiagnosticsSink;
+    /** Told about every caller value refused as unreadable or not plain data. */
+    readonly misuse?: FrameworkMisuseSink;
     readonly application?: FrameworkScopeConfig<M, Cfg>;
     readonly client?: FrameworkScopeConfig<M, Cfg>;
 };

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

@@ -1,29 +1,42 @@
 import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { ScalarFieldCapabilities, ScalarFormat } from "../contracts/field.js";
+import type { JsonShape } from "../contracts/json-shape.js";
 import type { LifecycleTrait } from "../contracts/lifecycle-trait.js";
+/** The lifecycle traits a configuration may set on a field. */
 export type FrameworkFieldLifecycleTrait = Extract<LifecycleTrait, "VIRTUAL">;
+/** The names of the Resources in adapter model `M`. */
 export type FrameworkResourceKey<M extends AdapterModel> = Extract<keyof M["resources"], string>;
+/** A scalar type or an enum of adapter model `M`, by name. */
 export type FrameworkScalarTypeRef<M extends AdapterModel> = {
     readonly scalar: Extract<keyof M["scalars"], string>;
 } | {
     readonly enum: Extract<keyof M["enums"], string>;
 };
 /**
- * Passive scalar-field authoring data applied by the Contract compiler.
- *
- * Existing adapter scalar fields remain the structural baseline. A field name
- * absent from the adapter model represents a framework-added scalar field and
- * must provide the structural leaves required by compilation.
+ * A scalar field's settings. For a discovered field, the discovered values are
+ * the baseline; a field the adapter did not discover must state `type`,
+ * `nullable` and `list`.
  */
 export type FrameworkScalarFieldConfig<M extends AdapterModel = AdapterModel> = {
+    /** The field's scalar or enum type. */
     readonly type?: FrameworkScalarTypeRef<M>;
+    /** The scalar's format name, carried in the Contract. */
     readonly format?: ScalarFormat;
+    /** Whether the field may be `null`. */
     readonly nullable?: boolean;
+    /** Whether the field holds a list of values. */
     readonly list?: boolean;
-    /** Field config owns persistence metadata only; generated/computed traits have other owners. */
+    /** Persistence traits: `"VIRTUAL"` marks a field the store does not hold. */
     readonly lifecycle?: readonly FrameworkFieldLifecycleTrait[];
+    /** The field's capabilities; see {@link ScalarFieldCapabilities}. */
     readonly capabilities?: Partial<ScalarFieldCapabilities>;
+    /**
+     * A Json field's shape, built with `AvZ` from `@aventara/core/json`: writes
+     * to the field are checked against it, and its value is typed by it.
+     */
+    readonly json?: JsonShape;
 };
+/** Field settings for one Resource, by field name. */
 export type FrameworkResourceFieldsConfig<M extends AdapterModel = AdapterModel> = Readonly<Record<string, FrameworkScalarFieldConfig<M>>>;
-/** Scalar augmentation/metadata keyed by canonical Adapter Resource identity. */
+/** Fields to add or describe, per Resource. */
 export type FrameworkFieldsConfig<M extends AdapterModel = AdapterModel> = Readonly<Partial<Record<FrameworkResourceKey<M>, FrameworkResourceFieldsConfig<M>>>>;

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

@@ -4,69 +4,54 @@ import type { PaginationCapability, ProjectionScope, RelationFilterCapability, R
 import type { AnyFrameworkConfig } from "./any-framework-config.js";
 import type { EffectiveFieldKey } from "./effective-fields.js";
 import type { FrameworkResourceKey } from "./framework-fields-config.js";
+/**
+ * `true` keeps a capability, `false` removes it, and a list keeps only the
+ * listed entries. Restrictions only narrow what the adapter offers.
+ */
 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.
- *
- * 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.
- * - `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".
+ * A restriction on a relation's `select` or `include` capability: `true`,
+ * `false`, or the projection positions to keep.
  */
 export type FrameworkProjectionScopeRestriction = boolean | readonly ProjectionScope[];
 /**
- * A restriction on a scope-qualified write member: `create` and `update` on a
- * relation.
- *
- * Removing a directive and removing a write position are **different narrowings**,
- * so each is authorable without restating the other. The bare directive list keeps
- * the grammar it has always had and narrows tokens only, leaving the positions the
- * baseline advertises in place; the object arm names either axis, or both.
+ * A restriction on a relation's `create` or `update` capability. A directive
+ * list narrows the directives only; the object form can also narrow the write
+ * positions (`scopes`).
  *
- * `directives: []` is NOT a denial. "Writable with no directive" and "not writable
- * during this stage" are two answers `V1006` already distinguishes, so an empty
- * directive list narrows the tokens to none and leaves the member present —
- * `scopes: []` is what denies it, for the reason
- * {@link FrameworkProjectionScopeRestriction} gives.
+ * `directives: []` leaves the relation writable with no directive;
+ * `scopes: []` or `false` makes it not writable.
  */
 export type FrameworkRelationMutationRestriction = boolean | readonly RelationMutationDirective[] | {
     readonly directives?: readonly RelationMutationDirective[];
     readonly scopes?: readonly WriteScope[];
 };
 /**
- * A restriction on a relation's scope-qualified reducer member. The write mirror is
- * {@link FrameworkRelationMutationRestriction}; the token key is the one the
- * Contract arm uses, so the restriction is written in the vocabulary of the value
- * it narrows rather than a second one.
+ * A restriction on a relation's `reducers` capability: `true`, `false`, a
+ * reducer list, or an object narrowing reducers and projection positions.
  */
 export type FrameworkRelationReducerRestriction = boolean | readonly RelationReducer[] | {
     readonly reducers?: readonly RelationReducer[];
     readonly scopes?: readonly ProjectionScope[];
 };
+/** Restrictions on a scalar field's capabilities. */
 export type FrameworkScalarCapabilityRestrictions = {
+    /** Whether the field can be selected. */
     readonly select?: boolean;
+    /** The filter operators to keep. */
     readonly filter?: FrameworkCapabilitySetRestriction<ScalarFilterOperator>;
+    /** Whether results can be ordered by the field. */
     readonly order?: boolean;
+    /** Whether ordering can place `null`s first or last. */
     readonly orderNulls?: boolean;
+    /** The directives to keep when creating. */
     readonly create?: FrameworkCapabilitySetRestriction<ScalarMutationDirective>;
+    /** The directives to keep when updating. */
     readonly update?: FrameworkCapabilitySetRestriction<ScalarMutationDirective>;
 };
 /**
- * Five of the eight members take a scope-aware restriction: exactly the five the
- * Contract carries a scope qualifier on. `filter`, `order` and `pagination` were
- * measured uniform across every operation variant, so there is no position to name
- * and a grammar that let one be named would invent a narrowing the adapter cannot
- * honour.
+ * Restrictions on a relation field's capabilities. `select`, `include`,
+ * `reducers`, `create` and `update` can also be narrowed by argument position.
  */
 export type FrameworkRelationCapabilityRestrictions = {
     readonly select?: FrameworkProjectionScopeRestriction;
@@ -78,15 +63,26 @@ export type FrameworkRelationCapabilityRestrictions = {
     readonly create?: FrameworkRelationMutationRestriction;
     readonly update?: FrameworkRelationMutationRestriction;
 };
+/** Restrictions for one scalar field. */
 export type FrameworkScalarFieldRestrictions = {
+    /** `true` hides the field. */
     readonly hidden?: boolean;
+    /** Capabilities to narrow. */
     readonly capabilities?: FrameworkScalarCapabilityRestrictions;
 };
+/** Restrictions for one relation field. */
 export type FrameworkRelationFieldRestrictions = {
+    /** `true` hides the field. */
     readonly hidden?: boolean;
+    /** Capabilities to narrow. */
     readonly capabilities?: FrameworkRelationCapabilityRestrictions;
 };
+/** Restrictions for one field: scalar or relation. */
 export type FrameworkFieldRestrictions = FrameworkScalarFieldRestrictions | FrameworkRelationFieldRestrictions;
+/**
+ * Standard operations to turn off, by family and variant: `false` removes
+ * one the adapter offers.
+ */
 export type FrameworkResourceOperationRestrictions = {
     readonly find?: {
         readonly first?: boolean;
@@ -122,40 +118,24 @@ type AdapterFieldRestrictionsFor<TField> = TField extends {
     readonly kind: "relation";
 } ? FrameworkRelationFieldRestrictions : FrameworkFieldRestrictions;
 /**
- * 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: 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}.
+ * The restriction shape one effective field name admits. Three cases, in
+ * order.
  */
 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.
- *
- * 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.
- */
+/** Restrictions for one Resource's fields, by field name. */
 export type FrameworkResourceFieldRestrictions<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = Readonly<Partial<{
     [F in EffectiveFieldKey<M, Cfg, R>]: FieldRestrictionsFor<M, R, F>;
 }>>;
+/** Restrictions for one Resource. */
 export type FrameworkResourceRestrictions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = {
+    /** `true` hides the whole Resource. */
     readonly hidden?: boolean;
+    /** Restrictions per field. */
     readonly fields?: FrameworkResourceFieldRestrictions<M, Cfg, R>;
+    /** Standard operations to turn off. */
     readonly operations?: FrameworkResourceOperationRestrictions;
 };
-/** Projection policy keyed by canonical Adapter Resource identity. */
+/** What to hide or narrow, per Resource. */
 export type FrameworkRestrictionsConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = Readonly<Partial<{
     [R in FrameworkResourceKey<M>]: FrameworkResourceRestrictions<M, Cfg, R>;
 }>>;

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

@@ -1,32 +1,22 @@
 import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { AfterHook, BeforeHook, Filter, Guard, Interceptor, Pipe } from "../runtime/pipeline.js";
-/**
- * Pipeline registrations for one configuration scope.
- *
- * See {@link PipelineContext}.
- */
+/** Pipeline registrations for one configuration scope. See {@link PipelineContext}. */
 export type PipelineConfig<M extends AdapterModel = AdapterModel> = {
+    /** Run first; a guard returning `false` denies the operation with `A4001`. */
     readonly guards?: readonly Guard<M>[];
+    /** Run in order on the arguments; a pipe may return replacement arguments. */
     readonly pipes?: readonly Pipe<M>[];
+    /** Run just before (`before`) and after (`after`) the operation executes. */
     readonly hooks?: {
         readonly before?: readonly BeforeHook<M>[];
         readonly after?: readonly AfterHook<M>[];
     };
+    /** Wrap the operation's execution; each calls `next()` to continue. */
     readonly interceptors?: readonly Interceptor<M>[];
+    /** Turn a thrown error into a {@link FrameworkError} outcome. */
     readonly filters?: readonly Filter<M>[];
 };
-/**
- * Fully normalized pipeline registration lists after scope composition.
- *
- * 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.
- */
+/** The pipelines that run for one origin, root and overlay combined. */
 export type ResolvedPipelineConfig = {
     readonly guards: readonly Guard[];
     readonly pipes: readonly Pipe[];

package/dist/contracts/capability.d.ts

@@ -1,64 +1,28 @@
+/** The operators a scalar field can be filtered with. */
 export type ScalarFilterOperator = "equals" | "not" | "in" | "notIn" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith" | "mode" | "has" | "hasEvery" | "hasSome" | "isEmpty" | "path" | "stringContains" | "stringStartsWith" | "stringEndsWith" | "arrayContains" | "arrayStartsWith" | "arrayEndsWith";
+/** What an update can do to a scalar value besides setting it. */
 export type ScalarMutationDirective = "$increment" | "$decrement" | "$multiply" | "$divide" | "$push" | "$unset";
+/** How a relation can be filtered on. */
 export type RelationFilterCapability = "nested" | "match" | "null" | "some" | "every" | "none";
+/** What a write can do to a relation: `$create`, `$connect` and the rest. */
 export type RelationMutationDirective = "$create" | "$connect" | "$connectOrCreate" | "$disconnect" | "$set" | "$update" | "$delete" | "$upsert";
+/** How a list of related rows can be paginated. */
 export type PaginationCapability = "limit" | "offset" | "cursor";
+/** What a projection can compute over a to-many relation. */
 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.
- *
- * **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.
- *
- * # 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. 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`.
+ * 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.
  */
 export declare const PROJECTION_SCOPES: readonly ["record", "bulkWrite"];
 /** @see PROJECTION_SCOPES — the axis this union is derived from. */
 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.
- *
- * **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.
- *
- * 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.
+ * Where a field may be written: the kind of argument POSITION a write sits in,
+ * not the operation that carries it. The write counterpart of
+ * {@link ProjectionScope}.
  */
 export declare const WRITE_SCOPES: readonly ["nested", "bulkWrite"];
 /** @see WRITE_SCOPES — the axis this union is derived from. */

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

@@ -1,52 +1,10 @@
 import type { ClientContract } from "./contract.js";
+import type { JsonSchema } from "./json-shape.js";
 /**
- * # Why core owns it
- *
- * The canonicalizer reads Contract members without validating them (it owns
- * ordering, not validation), so a body with a valid envelope and a malformed
- * member — `resources: { Spell: 5 }` — reaches it and throws a plain `TypeError`.
- * The structure of a ClientContract is a core fact, so its check is core's, and
- * every reader of an untrusted Contract (the client generator today, a host
- * asserting what it serves tomorrow) asks this one function.
- *
- * # 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:
- *
- * - **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`: what the type
- * admits is accepted, what it rules out is refused. Two consequences are
- * deliberate:
- *
- * - **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,
- *   semantic check.
- *
- * One rule is stricter than the type, because no TypeScript type can state it:
- * **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.
- *
- * 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.
+ * Whether an untrusted value is a `ClientContract`: every member present, of its JSON
+ * kind, inside its closed vocabulary, and nothing else. An enum's values must be
+ * distinct. Reads every member it judges and never throws on any input; a value that
+ * is not JSON at all is reported.
  */
 /** A literal a closed vocabulary can hold. */
 type Literal = string | number | boolean;
@@ -87,6 +45,12 @@ export type StructureNode = {
 } | {
     readonly is: "union";
     readonly arms: readonly StructureNode[];
+} | {
+    /**
+     * A Json Shape's schema: recursive, so judged by its own reader
+     * ({@link jsonSchemaDefect}) rather than spelled out in nodes.
+     */
+    readonly is: "jsonSchema";
 };
 /**
  * The TypeScript type a structure description admits, dispatched through a
@@ -122,6 +86,7 @@ type StructuredBy<N> = {
     readonly union: N extends {
         readonly arms: readonly (infer A)[];
     } ? Structured<A> : never;
+    readonly jsonSchema: JsonSchema;
 };
 type StructuredObject<R, O> = {
     readonly [K in keyof R]: Structured<R[K]>;
@@ -262,6 +227,9 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                         readonly format: {
                                             readonly is: "string";
                                         };
+                                        readonly json: {
+                                            readonly is: "jsonSchema";
+                                        };
                                     };
                                 };
                                 readonly relation: {
@@ -439,6 +407,10 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                                         readonly optional: Record<never, never>;
                                                     }];
                                                 };
+                                                readonly nestedWriteFilter: {
+                                                    readonly is: "literal";
+                                                    readonly values: readonly ["scalar"];
+                                                };
                                             };
                                         };
                                     };
@@ -1100,15 +1072,17 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
             readonly optional: Record<never, never>;
         };
     };
-    readonly optional: Record<never, never>;
+    readonly optional: {
+        readonly referenceWrites: {
+            readonly is: "literal";
+            readonly values: readonly ["uniform"];
+        };
+    };
 };
 /**
- * The answer. A refusal names the first defect found, as a `path` in the
- * JSONPath form `CanonicalJsonError` already uses (`$.resources.Spell`) and a
- * `message` clause that begins with that path in quotes.
- *
- * The specification allocates no error code to a malformed ClientContract — the
- * A/V codes are request outcomes, not generator failures — so none is invented.
+ * The answer of {@link validateClientContractStructure}. A refusal names the
+ * first defect found, as a `path` in JSONPath form (`$.resources.Spell`) and
+ * a `message` that begins with that path in quotes.
  */
 export type ClientContractStructureVerdict = {
     readonly valid: true;