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

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

@@ -1,6 +1,7 @@
 import { PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
 import { AVENTARA_PROTOCOL_VERSION } from "./contract-protocol.js";
 import { LIFECYCLE_TRAITS } from "./lifecycle-trait.js";
+import { REFERENCE_WRITE_LIMITS } from "./reference-write-limit.js";
 import { TRANSACTION_CAPABILITIES } from "./transaction-capability.js";
 const STRING = { is: "string" };
 const NUMBER = { is: "number" };
@@ -106,7 +107,7 @@ const SCALAR_FIELD = object({
         create: list(literal(SCALAR_MUTATION_DIRECTIVES)),
         update: list(literal(SCALAR_MUTATION_DIRECTIVES)),
     }),
-}, { format: STRING });
+}, { format: STRING, json: { is: "jsonSchema" } });
 const RELATION_FIELD = object({
     kind: literal(["relation"]),
     target: STRING,
@@ -124,6 +125,7 @@ const RELATION_FIELD = object({
         })),
         create: RELATION_MUTATION,
         update: RELATION_MUTATION,
+        nestedWriteFilter: literal(["scalar"]),
     }),
 });
 const OPERATION_AVAILABILITY = union(literal([true]), object({ projection: literal(PROJECTION_SCOPES) }, { write: literal(WRITE_SCOPES) }), object({ write: literal(WRITE_SCOPES) }, { projection: literal(PROJECTION_SCOPES) }));
@@ -177,7 +179,7 @@ export const CLIENT_CONTRACT_STRUCTURE = object({
         version: literal([AVENTARA_PROTOCOL_VERSION]),
         hash: { is: "prefixed", prefix: "sha256:" },
     }),
-});
+}, { referenceWrites: literal(REFERENCE_WRITE_LIMITS) });
 export function validateClientContractStructure(value) {
     const defect = defectOf(CLIENT_CONTRACT_STRUCTURE, value, "$", 0);
     if (defect !== undefined) {
@@ -233,6 +235,101 @@ function defectOf(node, value, path, depth) {
         }
         case "union":
             return unionDefect(node.arms, value, path, depth);
+        case "jsonSchema":
+            return jsonSchemaDefect(value, path, depth);
+    }
+}
+const JSON_SCHEMA_SCALAR_TYPES = [
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "null",
+];
+const JSON_PRIMITIVE = union(STRING, NUMBER, BOOLEAN);
+function jsonSchemaDefect(value, path, depth) {
+    const kind = kindDefect(value, "object", path, depth);
+    if (kind !== undefined)
+        return kind;
+    const schema = value;
+    const keys = Object.keys(schema).sort().join(",");
+    const child = (member, entry, at = `${path}.${member}`) => jsonSchemaDefect(entry, at, depth + 1);
+    const children = (member, minimum) => {
+        const listKind = kindDefect(schema[member], "array", `${path}.${member}`, depth + 1);
+        if (listKind !== undefined)
+            return listKind;
+        const entries = schema[member];
+        if (entries.length < minimum) {
+            return at(`${path}.${member}`, depth + 1, `needs at least ${minimum} entries`);
+        }
+        for (let index = 0; index < entries.length; index += 1) {
+            const defect = child(member, entries[index], `${path}.${member}[${index}]`);
+            if (defect !== undefined)
+                return defect;
+        }
+        return undefined;
+    };
+    switch (keys) {
+        case "type":
+            return literalDefect(JSON_SCHEMA_SCALAR_TYPES, schema.type, `${path}.type`, depth + 1);
+        case "const":
+            return Object.is(schema.const, null)
+                ? undefined
+                : defectOf(JSON_PRIMITIVE, schema.const, `${path}.const`, depth + 1);
+        case "enum,type":
+            return (literalDefect(["string"], schema.type, `${path}.type`, depth + 1) ??
+                defectOf({ is: "list", item: STRING, nonEmpty: true, unique: true }, schema.enum, `${path}.enum`, depth + 1));
+        case "additionalProperties,properties,type":
+        case "additionalProperties,properties,required,type": {
+            const typeDefect = literalDefect(["object"], schema.type, `${path}.type`, depth + 1) ??
+                literalDefect([false], schema.additionalProperties, `${path}.additionalProperties`, depth + 1);
+            if (typeDefect !== undefined)
+                return typeDefect;
+            const propertiesKind = kindDefect(schema.properties, "object", `${path}.properties`, depth + 1);
+            if (propertiesKind !== undefined)
+                return propertiesKind;
+            const properties = schema.properties;
+            for (const name of Object.keys(properties)) {
+                const defect = child("properties", properties[name], `${path}.properties.${name}`);
+                if (defect !== undefined)
+                    return defect;
+            }
+            if (!Object.hasOwn(schema, "required"))
+                return undefined;
+            const requiredDefect = defectOf({ is: "list", item: STRING, nonEmpty: false, unique: true }, schema.required, `${path}.required`, depth + 1);
+            if (requiredDefect !== undefined)
+                return requiredDefect;
+            const undeclared = schema.required.findIndex((name) => !Object.hasOwn(properties, name));
+            return undeclared === -1
+                ? undefined
+                : at(`${path}.required[${undeclared}]`, depth + 1, "names a key that is not one of the object's properties");
+        }
+        case "additionalProperties,type":
+            return (literalDefect(["object"], schema.type, `${path}.type`, depth + 1) ??
+                child("additionalProperties", schema.additionalProperties));
+        case "items,type":
+            return (literalDefect(["array"], schema.type, `${path}.type`, depth + 1) ??
+                child("items", schema.items));
+        case "items,maxItems,minItems,prefixItems,type": {
+            const defect = literalDefect(["array"], schema.type, `${path}.type`, depth + 1) ??
+                literalDefect([false], schema.items, `${path}.items`, depth + 1) ??
+                children("prefixItems", 1);
+            if (defect !== undefined)
+                return defect;
+            const length = schema.prefixItems.length;
+            for (const bound of ["minItems", "maxItems"]) {
+                if (schema[bound] !== length) {
+                    return at(`${path}.${bound}`, depth + 1, `is ${JSON.stringify(schema[bound])}, not the tuple's length ${length}`);
+                }
+            }
+            return undefined;
+        }
+        case "anyOf":
+            return children("anyOf", 2);
+        case "oneOf":
+            return children("oneOf", 1);
+        default:
+            return at(path, depth, `is not a Json Shape schema: its keywords {${keys}} are not one of the forms Aventara emits`);
     }
 }
 function literalDefect(values, value, path, depth) {

package/dist/contracts/contract-canonicalizer.d.ts

@@ -1,13 +1,11 @@
 import type { Contract } from "./contract.js";
 /**
- * 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.
+ * Thrown when a value cannot be written as canonical JSON (RFC 8785). It is a
+ * `TypeError`.
  */
 export declare class CanonicalJsonError extends TypeError {
 }
-/** RFC 8785/JCS-compatible canonical encoding for JSON-safe Aventara data. */
+/** Canonical JSON (RFC 8785) for a JSON-safe value. */
 export declare function canonicalizeJson(value: unknown): string;
-/** Canonical semantic representation used for deterministic Contract output. */
+/** The Contract as canonical JSON (RFC 8785): the same bytes for the same Contract. */
 export declare function canonicalizeContract<C extends Contract>(contract: C): string;

package/dist/contracts/contract-canonicalizer.js

@@ -83,10 +83,42 @@ function normalizeCapabilities(capabilities) {
     }
     return normalized;
 }
+function normalizeJsonSchema(schema) {
+    if (Array.isArray(schema)) {
+        return schema.map(normalizeJsonSchema);
+    }
+    if (typeof schema !== "object" || schema === null) {
+        return schema;
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "required" && Array.isArray(value)) {
+            normalized[key] = [...value].sort((left, right) => compareCodeUnits(String(left), String(right)));
+        }
+        else if (key === "properties" &&
+            typeof value === "object" &&
+            value !== null) {
+            normalized[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => [
+                name,
+                normalizeJsonSchema(child),
+            ]));
+        }
+        else if (key === "const" || key === "enum") {
+            normalized[key] = value;
+        }
+        else {
+            normalized[key] = normalizeJsonSchema(value);
+        }
+    }
+    return normalized;
+}
 function normalizeField(field) {
     if (field.kind === "scalar") {
         return {
             ...field,
+            ...(field.json !== undefined
+                ? { json: normalizeJsonSchema(field.json) }
+                : {}),
             lifecycle: normalizeStringSet(field.lifecycle, LIFECYCLE_TRAITS),
             capabilities: normalizeCapabilities(field.capabilities),
         };

package/dist/contracts/contract-hash.d.ts

@@ -1,10 +1,11 @@
 import type { ClientContract } from "./contract.js";
 import type { ContractHash, ContractProtocol } from "./contract-protocol.js";
+/** A ClientContract whose `protocol` does not carry the hash yet. */
 export type ClientContractHashInput = Omit<ClientContract, "protocol"> & {
     readonly protocol: ContractProtocol;
 };
 export declare function createClientContractHashInput(contract: ClientContract | ClientContractHashInput): ClientContractHashInput;
-/** Compute exact ClientContract identity with protocol.hash excluded. */
+/** Computes a ClientContract's `sha256:` hash, ignoring `protocol.hash` itself. */
 export declare function computeClientContractHash(contract: ClientContract | ClientContractHashInput): Promise<ContractHash>;
-/** Recompute and compare the advertised ClientContract identity. */
+/** Whether a ClientContract's `protocol.hash` matches its content. */
 export declare function verifyClientContractHash(contract: ClientContract): Promise<boolean>;

package/dist/contracts/contract-limits.d.ts

@@ -1,11 +1,17 @@
+/** The request limits a Contract enforces. */
 export type ContractLimits = {
+    /** The largest request body accepted, in bytes. */
     readonly maxRequestBytes: number;
+    /** How deeply arguments may nest. */
     readonly maxNestingDepth: number;
+    /** The largest `limit` a list read may ask for. */
     readonly maxListLimit: number;
+    /** The most operations one transaction may hold. */
     readonly maxTransactionOperations: number;
+    /** The most boolean and filter nodes one request may hold. */
     readonly maxBooleanNodes: number;
 };
-/** Conservative v1 framework defaults resolved before scoped limit overrides. */
+/** The limits in force when the configuration sets none. */
 export declare const DEFAULT_CONTRACT_LIMITS: {
     readonly maxRequestBytes: 1048576;
     readonly maxNestingDepth: 12;

package/dist/contracts/contract-protocol.d.ts

@@ -1,18 +1,17 @@
 /**
- * Aventara's external communication protocol version.
- *
- * This is intentionally independent from framework/package versions and from
- * application-specific Contract changes. Resource/field/configuration/database
- * changes are identified by the ClientContract hash and do not require a
- * protocol-version bump by themselves. Increment this value only when a
- * breaking change makes previous-protocol clients unable to correctly parse or
- * interpret Aventara's external protocol semantics.
+ * The version of Aventara's wire protocol. It changes only when older
+ * clients can no longer read the protocol correctly; schema and
+ * configuration changes are tracked by the ClientContract hash instead.
  */
 export declare const AVENTARA_PROTOCOL_VERSION: 1;
+/** A Contract hash: `sha256:` followed by the hex digest. */
 export type ContractHash = `sha256:${string}`;
+/** The protocol a Contract is written for. */
 export type ContractProtocol = {
+    /** The protocol version; see {@link AVENTARA_PROTOCOL_VERSION}. */
     readonly version: typeof AVENTARA_PROTOCOL_VERSION;
 };
+/** A ClientContract's `protocol`: the protocol version and the Contract hash. */
 export type ClientContractProtocol = ContractProtocol & {
     readonly hash: ContractHash;
 };

package/dist/contracts/contract.d.ts

@@ -1,24 +1,40 @@
 import type { ContractLimits } from "./contract-limits.js";
 import type { ClientContractProtocol } from "./contract-protocol.js";
 import type { EnumDefinition } from "./enum-definition.js";
+import type { ReferenceWriteLimit } from "./reference-write-limit.js";
 import type { Resource } from "./resource.js";
 import type { ScalarRegistry } from "./scalar.js";
 import type { TransactionCapability } from "./transaction-capability.js";
-/** Passive semantic description shared by every Aventara Contract form. */
+/** What every Contract describes: scalars, enums, Resources, limits and transactions. */
 export interface Contract {
+    /** The scalar types available. */
     readonly scalars: ScalarRegistry;
+    /** The enums, by name. */
     readonly enums: Readonly<Record<string, EnumDefinition>>;
+    /** The Resources, by name. */
     readonly resources: Readonly<Record<string, Resource<this>>>;
+    /** The request limits in force. */
     readonly limits: ContractLimits;
+    /** Whether interactive transactions are available. */
     readonly transactions: TransactionCapability;
+    /**
+     * `"uniform"` when one record must write the relations that hold a reference
+     * either all as relations or all through their reference fields; a record
+     * that mixes them is refused with `A2004`. Absent: each relation either way.
+     */
+    readonly referenceWrites?: ReferenceWriteLimit;
 }
-/** Root-scope Contract form. Distinction becomes behavioral during compilation. */
+/** The Contract compiled from the root configuration. */
 export interface CoreContract extends Contract {
 }
-/** Same-process application-operation Contract form. */
+/** The Contract in-process calls run under (`framework.application`). */
 export interface ApplicationContract extends Contract {
 }
-/** Remotely introspectable external-consumer Contract form with exact identity. */
+/**
+ * The Contract remote clients run under, published at `GET /_contract` and
+ * identified by its hash.
+ */
 export interface ClientContract extends Contract {
+    /** The protocol version and this Contract's hash. */
     readonly protocol: ClientContractProtocol;
 }

package/dist/contracts/enum-definition.d.ts

@@ -1,3 +1,5 @@
+/** An enum: its allowed values. */
 export type EnumDefinition = {
+    /** The allowed values, in declaration order. */
     readonly values: readonly string[];
 };

package/dist/contracts/field.d.ts

@@ -1,49 +1,19 @@
 import type { PaginationCapability, ProjectionScope, RelationFilterCapability, RelationMutationDirective, RelationReducer, ScalarFilterOperator, ScalarMutationDirective, WriteScope } from "./capability.js";
 import type { Contract } from "./contract.js";
+import type { JsonSchema } from "./json-shape.js";
 import type { LifecycleTrait } from "./lifecycle-trait.js";
-/** Passive scalar format identity; concrete codec semantics remain protocol-owned. */
+/** A format name that refines a scalar type, carried in the Contract as data. */
 export type ScalarFormat = string;
-/**
- * The projection positions a field is projectable in: at least one, because an
- * EMPTY list is not a third answer.
- *
- * `absent ≠ empty` is this repository's established rule and the validation layer
- * already acts on the difference, so the empty list has to be unrepresentable
- * rather than merely discouraged. An absent capability member is "not available at
- * all"; an empty list would say the same thing in a second encoding, which is one
- * semantic fact with two hashes.
- *
- * **A scope list qualifies the TOP LEVEL of a projection only. It does not narrow
- * recursively** — see {@link ProjectionScope}, where the runtime measurement and
- * the reason are recorded.
- */
+/** The projection positions a field can be selected in (at least one). */
 export type ProjectionScopes = readonly [ProjectionScope, ...ProjectionScope[]];
 /**
- * The write positions a field is writable in: at least one, for the reason
- * {@link ProjectionScopes} gives. Here the distinction is sharper still, because
- * the directive list beside it is separately allowed to be empty and already
- * means something: on a relation mutation member, absent answers `V1006` *"is not
- * writable during <stage>"* while `[]` answers *"writable with no directive"*. A
- * scope list that could also be empty would put a third, unreachable answer next
- * to those two.
- *
- * **A scope list qualifies the TOP LEVEL of a write argument only. It does not
- * narrow recursively** — see {@link WriteScope}.
+ * The write positions a field can be written in (at least one). A scope list
+ * applies to the top level of a write argument only; see {@link WriteScope}.
  */
 export type WriteScopes = readonly [WriteScope, ...WriteScope[]];
 /**
- * Whether a relation is projectable, and — when the adapter has measured it — the
- * projection positions it is projectable in.
- *
- * `true`/`false` is the unqualified answer: available, or not, in every projection
- * position. A {@link ProjectionScopes} list is the qualified answer, and it exists
- * because both pilot engines measurably narrow the top level of a BULK write's
- * returned-row projection to the relations the written row itself resolves, while
- * advertising the full surface on every read.
- *
- * The unqualified arm is retained deliberately: an adapter that has not measured
- * the axis must be able to say so, and a Contract that predates the measurement
- * must keep its meaning.
+ * Whether a relation can be selected or included: `true`, or the projection
+ * positions it can be used in.
  */
 export type RelationProjectionCapability = boolean | ProjectionScopes;
 /**
@@ -57,36 +27,25 @@ export type ScopedRelationReducers = {
     readonly scopes: ProjectionScopes;
 };
 /**
- * A relation's reducer capability: the bare reducer list is the unqualified
- * answer, the scoped form the measured one. Discriminated structurally — the
- * unqualified arm is an array, the qualified arm an object.
+ * A relation's reducers: a reducer list, or an object with the reducers and
+ * the projection positions they apply in.
  */
 export type RelationReducerCapability = readonly RelationReducer[] | ScopedRelationReducers;
 /**
- * The mutation directives a relation admits at one write stage, qualified by the
- * write positions they are admitted in.
- *
- * `directives: []` stays meaningful and stays distinct from an absent member —
- * "writable with no directive" against "not writable during this stage" — so the
- * scoped form carries the directive list rather than replacing it.
+ * The mutation directives a relation admits at one write stage, and the write
+ * positions they are admitted in. `directives: []` means writable with no
+ * directive.
  */
 export type ScopedRelationMutations = {
     readonly directives: readonly RelationMutationDirective[];
     readonly scopes: WriteScopes;
 };
 /**
- * A relation's write capability at one stage: the bare directive list is the
- * unqualified answer, the scoped form the measured one. Discriminated structurally
- * — the unqualified arm is an array, the qualified arm an object.
+ * A relation's write capability for `create` or `update`: a directive list, or
+ * an object with the directives and the write positions they apply in.
  */
 export type RelationMutationCapability = readonly RelationMutationDirective[] | ScopedRelationMutations;
-/**
- * Scalar capabilities carry no scope qualifier. Measured on both pilot engines,
- * 2026-10-03: all six members are uniform across every operation variant on the
- * axis — the same scalar members, the same operands, the same declared input
- * symbols in the singular and the bulk forms. Qualifying them would encode a
- * variation that does not exist.
- */
+/** What can be done with a scalar field. Scalar capabilities apply in every position. */
 export type ScalarFieldCapabilities = {
     readonly select?: boolean;
     readonly filter?: readonly ScalarFilterOperator[];
@@ -95,18 +54,7 @@ export type ScalarFieldCapabilities = {
     readonly create?: readonly ScalarMutationDirective[];
     readonly update?: readonly ScalarMutationDirective[];
 };
-/**
- * Relation capabilities. Five of the eight members are scope-qualified, which is
- * exactly the five the survey measured as varying by operation variant, by two
- * independent mechanisms: the bulk-returning projection ceiling (`select`,
- * `include`, `reducers`) and the flat bulk write stage (`create`, `update`).
- *
- * The other three are left alone on the same evidence. `filter` is uniform
- * (`<M>WhereInput` and `<M>WhereUniqueInput` agree member-for-member on relation
- * members), `order` is uniform (one orderBy input type across every orderBy-carrying
- * variant), and `pagination` is read off the edge's own arguments, the same symbol
- * under every projection that admits the edge at all.
- */
+/** What can be done with a relation field. */
 export type RelationFieldCapabilities = {
     readonly select?: RelationProjectionCapability;
     readonly include?: RelationProjectionCapability;
@@ -116,121 +64,43 @@ export type RelationFieldCapabilities = {
     readonly reducers?: RelationReducerCapability;
     readonly create?: RelationMutationCapability;
     readonly update?: RelationMutationCapability;
+    /**
+     * What the `where` of a nested `$update` or `$delete` through this relation may
+     * filter: `"scalar"` — the target's scalar fields only, combined with
+     * `AND`/`OR`/`NOT`, and no relation filter at any depth. Absent: any filter the
+     * target takes.
+     */
+    readonly nestedWriteFilter?: "scalar";
 };
 /**
- * The reducers a relation advertises, whichever arm the member is written in,
- * **ignoring the scope qualifier**.
- *
- * Scope-blind on purpose, and only for a reader on an axis the scope does not
- * qualify. `orderBy: { <to-many>: { $count: … } }` is the one such reader: ordering
- * was measured uniform across every variant that carries an `orderBy` argument, so
- * there is no projection position to ask about and asking would invent one.
- *
- * Every reader on the projection axis wants {@link advertisedReducersAt} instead.
+ * The reducers a relation advertises, in any projection position. Use
+ * {@link advertisedReducersAt} for one position.
  */
 export declare function advertisedReducers(capability: RelationReducerCapability | undefined): readonly RelationReducer[] | undefined;
-/**
- * Whether a projection capability holds at one projection scope — **the one home
- * of the scope-aware capability read.**
- *
- * Every reader that has a scope asks this, and no reader compares a capability
- * member to `true` any more. That is not tidiness: a qualified member is an
- * object/array, so `member === true` is `false` for *every* scope, and the six
- * `select`/`include` comparisons this function replaces read a measured
- * `["record"]` as **unavailable everywhere** — a to-many projection refused on
- * `update.first`, which is the single-record scope the adapter advertises it in.
- *
- * The parameter admits `boolean` as well as {@link ProjectionScopes} because the
- * unqualified arm means *holds in every scope*: an adapter that has not measured
- * the axis, and every Contract that predates the measurement, must keep answering
- * what they answered before. So `true` holds at every scope and `false`/absent at
- * none, and the qualified arm is consulted only where one exists.
- *
- * **A scope qualifies the TOP LEVEL of a projection only** — see {@link
- * ProjectionScope}, where the runtime measurement is recorded. A caller that
- * recurses must ask about the nested position with the unrestricted scope, not
- * with its own.
- */
+/** Whether a projection capability holds at one projection position. */
 export declare function holdsAt(capability: RelationProjectionCapability | undefined, scope: ProjectionScope): boolean;
 /**
- * Whether a projection capability holds in **any** scope — the scope-blind
- * question, for the one reader that legitimately has no scope to ask about.
- *
- * It exists so that reader does not hand-roll `=== true` either. The Contract
- * compiler's VIRTUAL lifecycle check asks whether a field is selectable *at all*
- * before requiring an effective read behavior; a field selectable in one scope
- * needs that behavior exactly as much as one selectable in every scope.
- *
- * A reader with a scope must use {@link holdsAt}. This one answers a strictly
- * weaker question and will over-advertise if used in its place.
+ * Whether a projection capability holds in **any** projection position. Use
+ * {@link holdsAt} when the position is known.
  */
 export declare function holdsInAnyScope(capability: RelationProjectionCapability | undefined): boolean;
 /**
- * The reducers a relation advertises **at one projection scope**: the tokens where
- * the member holds there, and `undefined` where it does not.
- *
- * One call rather than two, because the two-call form is the defect. A reader that
- * asks {@link advertisedReducers} for the tokens and then has to remember a second
- * {@link holdsAt} call will forget it, and a forgotten scope check is a silent
- * over-advertisement. Here the scope cannot be forgotten: there is no way to get
- * the tokens without naming the position they are wanted in.
- *
- * `undefined` is the same answer an absent member gives, which is correct — a
- * reducer that does not hold at this scope is not advertised at this scope — and
- * it keeps `[]` meaning what it means everywhere else: advertised, with no
- * reducer.
+ * The reducers a relation advertises at one projection position, or
+ * `undefined` where it has none there.
  */
 export declare function advertisedReducersAt(capability: RelationReducerCapability | undefined, scope: ProjectionScope): readonly RelationReducer[] | undefined;
 /**
- * The mutation directives a relation advertises at one write stage, whichever arm
- * the member is written in, **ignoring the scope qualifier**. `undefined` and `[]`
- * stay distinct: the stage is unavailable, or available with no directive.
- *
- * Scope-blind on purpose, and only for a reader that has no write position to ask
- * about or whose answer may only be WIDER than the validator's. Two readers
- * qualify. `operation-boolean-nodes.ts`'s `maxBooleanNodes` walk descends a
- * relation mutation to count the filter nodes inside it; reading scope-blind makes
- * that walk a superset of what the grammar walk admits, which is the harmless
- * direction — it counts inside a write that is about to be refused, and it can
- * never stop counting inside one that is admitted. An adapter's own write
- * translator is the other: it is handed the write site's verdict by whoever
- * dispatched it and holds no advertised variant to resolve a scope from.
- *
- * Every reader on the write axis that HAS a position wants {@link
- * advertisedDirectivesAt} instead.
- *
- * See {@link advertisedReducers} for why the scopes are not returned beside them.
+ * The mutation directives a relation advertises at one write stage, in any
+ * write position. `undefined` means the stage is unavailable; `[]` means
+ * available with no directive.
  */
 export declare function advertisedDirectives(capability: RelationMutationCapability | undefined): readonly RelationMutationDirective[] | undefined;
 /**
- * The mutation directives a relation advertises **at one write scope**: the
- * directives where the member holds there, and `undefined` where it does not —
- * **the one home of the scope-aware write read**, and the write mirror of {@link
- * advertisedReducersAt}.
- *
- * One call rather than two, for the reason {@link advertisedReducersAt} gives: a
- * reader that fetches the directives and then has to remember a separate scope
- * check will forget it, and a forgotten scope check is a silent
- * over-advertisement. Here the position cannot be forgotten, because there is no
- * way to reach the directives without naming it.
- *
- * `undefined` for a stage that does not hold at this scope is the same answer an
- * absent member gives, which is what the caller must say: a relation that is not
- * writable in this write position is *"not writable during <stage>"* there. That
- * keeps `[]` meaning what it means everywhere else — advertised, with no directive
- * — so the two live answers `V1006` already distinguishes stay two, and the scope
- * does not invent a third.
- *
- * The unqualified arm is an array and means *holds in every write position*: an
- * adapter that has not measured the axis, and every Contract that predates the
- * measurement, keep the write surface they had.
- *
- * **A scope qualifies the TOP LEVEL of a write argument only** — see {@link
- * WriteScope}. A caller that recurses into a nested write must ask about the
- * nested position with the unrestricted scope, not with its own.
+ * The mutation directives a relation advertises at one write position, or
+ * `undefined` where it is not writable there.
  */
 export declare function advertisedDirectivesAt(capability: RelationMutationCapability | undefined, scope: WriteScope): readonly RelationMutationDirective[] | undefined;
-/** Atomic field from the API/query perspective, including enum-backed fields. */
+/** A scalar field, including an enum-backed one. */
 export type ScalarField<C extends Contract> = {
     readonly kind: "scalar";
     readonly type: {
@@ -243,8 +113,10 @@ export type ScalarField<C extends Contract> = {
     readonly list: boolean;
     readonly lifecycle: readonly LifecycleTrait[];
     readonly capabilities: ScalarFieldCapabilities;
+    /** A `json` field's shape, as JSON Schema: what every value written to it is. */
+    readonly json?: JsonSchema;
 };
-/** Relation edge only; the target Resource owns the returned object shape. */
+/** A relation field; the `target` Resource describes the related row. */
 export type RelationField<C extends Contract> = {
     readonly kind: "relation";
     readonly target: Extract<keyof C["resources"], string>;
@@ -252,4 +124,5 @@ export type RelationField<C extends Contract> = {
     readonly nullable: boolean;
     readonly capabilities: RelationFieldCapabilities;
 };
+/** One field of a Resource: a scalar or a relation. */
 export type Field<C extends Contract> = ScalarField<C> | RelationField<C>;

package/dist/contracts/identifier.d.ts

@@ -1,21 +1,6 @@
 import type { Contract } from "./contract.js";
 import type { Field } from "./field.js";
-/**
- * Keys of `TFields` whose Field can be scalar-shaped.
- *
- * `TFields[K]` is an indexed access, not a naked type parameter, so a bare
- * conditional would not distribute over a union-valued field. With the
- * abstract `ResourceFieldMap` default every key maps to the whole `Field`
- * union, which is not a subtype of the scalar branch, so the bare form
- * collapses to `never` and makes `Identifier` uninhabitable. `Extract` selects
- * the scalar branch out of the union instead, so a key is kept unless it is
- * provably relation-only.
- *
- * The branch is selected by its `kind` discriminant rather than by
- * `ScalarField<Contract>`: `Field<C>` measures as invariant in `C`, so a
- * `Field<ClientContract>` is not assignable to a `Field<Contract>` and the
- * `Extract` would collapse again. This mirrors `AdapterScalarFieldKey`.
- */
+/** Keys of `TFields` whose field can be scalar-shaped. */
 export type ScalarFieldKey<TFields extends Readonly<Record<string, Field<Contract>>>> = Extract<{
     [K in keyof TFields]: [
         Extract<TFields[K], {