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

package/dist/compiler/contract.compiler.js

@@ -6,6 +6,7 @@ import { DEFAULT_CONTRACT_LIMITS, } from "../contracts/contract-limits.js";
 import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
 import { advertisedDirectives, advertisedDirectivesAt, advertisedReducers, advertisedReducersAt, holdsAt, holdsInAnyScope, } from "../contracts/field.js";
 import { isOperationVariantAvailable, } from "../contracts/resource-operations.js";
+import { bindShapedField, jsonShapeOf } from "../json/json-shape.registry.js";
 const UNIQUE_VARIANTS = [
     ["find", "unique"],
     ["update", "unique"],
@@ -99,6 +100,9 @@ function createBaseline(model) {
         ])),
         limits: { ...DEFAULT_CONTRACT_LIMITS },
         transactions: model.transactions,
+        ...(model.referenceWrites === undefined
+            ? {}
+            : { referenceWrites: model.referenceWrites }),
     };
 }
 function scalarFieldPath(scope, resource, field) {
@@ -111,6 +115,10 @@ function structuralValueMatches(field, config, key) {
     return JSON.stringify(field[key]) === JSON.stringify(config[key]);
 }
 function addConfiguredScalarField(config, path, diagnostics) {
+    if (config.json !== undefined) {
+        refuseJsonShape(path, "is not a field of the adapter model", diagnostics);
+        return undefined;
+    }
     const missing = ["type", "nullable", "list"].filter((key) => config[key] === undefined);
     if (missing.length > 0) {
         diagnostics.push(diagnostic("COMPILER_INCOMPLETE_FIELD", path, `framework-added scalar field is missing required properties: ${missing.join(", ")}`));
@@ -157,6 +165,8 @@ export function capabilityAddsBaseline(fieldKind, baseline, key, configured) {
     }
     const baselineValue = baseline[key];
     switch (axis.kind) {
+        case "limit":
+            return baselineValue !== undefined && configured !== baselineValue;
         case "flag":
             return configured === true && baselineValue !== true;
         case "tokens": {
@@ -213,6 +223,31 @@ function advertisedTokensAt(tokenKey, baselineValue, position) {
         ? advertisedDirectivesAt(baselineValue, position)
         : advertisedReducersAt(baselineValue, position);
 }
+function fieldLabel(path) {
+    const [, resource, , field] = path.split(".").slice(1);
+    return `${resource}.${field}`;
+}
+function refuseJsonShape(path, reason, diagnostics) {
+    diagnostics.push(diagnostic("COMPILER_INVALID_JSON_SHAPE", `${path}.json`, `field "${fieldLabel(path)}" ${reason}; only a Json field the adapter discovered may declare a "json" shape`));
+}
+function applyJsonShape(field, baselineField, shape, path, diagnostics) {
+    const type = baselineField.type;
+    if (type.scalar !== "json") {
+        refuseJsonShape(path, `is ${type.scalar === undefined ? "an enum" : `${/^[aeiou]/.test(type.scalar) ? "an" : "a"} ${type.scalar}`} field`, diagnostics);
+        return;
+    }
+    const runtime = jsonShapeOf(shape);
+    if (runtime === undefined) {
+        diagnostics.push(diagnostic("COMPILER_INVALID_JSON_SHAPE", `${path}.json`, `field "${fieldLabel(path)}": "json" must be a shape built with AvZ from "@aventara/core/json"; a Zod schema or any other value is not accepted`));
+        return;
+    }
+    if (runtime.validate(null).length === 0 ||
+        runtime.validate(undefined).length === 0) {
+        diagnostics.push(diagnostic("COMPILER_INVALID_JSON_SHAPE", `${path}.json`, `field "${fieldLabel(path)}": a field's shape cannot admit null or absence at its top level; whether the field may be null comes from the adapter model`));
+        return;
+    }
+    field.json = cloneValue(runtime.schema);
+}
 function applyExistingScalarConfig(field, baselineField, config, path, diagnostics) {
     for (const key of ["type", "nullable", "list"]) {
         if (!structuralValueMatches(field, config, key)) {
@@ -222,6 +257,9 @@ function applyExistingScalarConfig(field, baselineField, config, path, diagnosti
     if (config.format !== undefined) {
         field.format = config.format;
     }
+    if (config.json !== undefined) {
+        applyJsonShape(field, baselineField, config.json, path, diagnostics);
+    }
     if (config.lifecycle !== undefined) {
         diagnostics.push(diagnostic("COMPILER_INVALID_LIFECYCLE", `${path}.lifecycle`, "existing adapter field lifecycle cannot be redefined by framework field configuration"));
     }
@@ -243,6 +281,9 @@ function applyFrameworkOwnedScalarConfig(field, config, path, diagnostics) {
             field[key] = cloneValue(config[key]);
         }
     }
+    if (config.json !== undefined) {
+        refuseJsonShape(path, "is not a field of the adapter model", diagnostics);
+    }
     if (config.format !== undefined) {
         field.format = config.format;
     }
@@ -391,6 +432,7 @@ const RELATION_CAPABILITY_AXES = {
     },
     create: { kind: "scopedTokens", tokenKey: "directives", axis: WRITE_SCOPES },
     update: { kind: "scopedTokens", tokenKey: "directives", axis: WRITE_SCOPES },
+    nestedWriteFilter: { kind: "limit", values: ["scalar"] },
 };
 function capabilityAxisFor(kind, key) {
     const axes = kind === "scalar" ? SCALAR_CAPABILITY_AXES : RELATION_CAPABILITY_AXES;
@@ -478,6 +520,10 @@ function applyScopedTokenRestriction(tokenKey, axis, baselineValue, current, key
     return true;
 }
 function applyCapabilityRestriction(fieldKind, inherited, restoration, current, key, value, path, diagnostics) {
+    if (capabilityAxisFor(fieldKind, key)?.kind === "limit") {
+        unavailableCapability(path, `capability "${key}" is an adapter limit and takes no restriction`, diagnostics);
+        return;
+    }
     if (value === false) {
         delete current[key];
         return;
@@ -728,6 +774,10 @@ function positionListFault(axis, positions) {
 }
 function representationFault(axis, value) {
     switch (axis.kind) {
+        case "limit":
+            return typeof value === "string" && axis.values.includes(value)
+                ? undefined
+                : `one of ${axis.values.join(", ")} is expected`;
         case "flag":
             return typeof value === "boolean" ? undefined : "a boolean is expected";
         case "tokens":
@@ -827,6 +877,20 @@ function projectDerivedScope(model, scopeName, core, scope, diagnostics) {
     validateProjection(projection, baseline, scopeName, scope.restrictions, diagnostics);
     return projection;
 }
+function bindShapedFields(contract, fields) {
+    for (const [resourceName, resource] of Object.entries(contract.resources)) {
+        for (const [fieldName, field] of Object.entries(resource.fields)) {
+            if (field.kind !== "scalar" || field.json === undefined) {
+                continue;
+            }
+            const shape = jsonShapeOf(fields?.[resourceName]?.[fieldName]?.json);
+            if (shape === undefined) {
+                throw new Error(`the Contract compiler found no shape for shaped field "${resourceName}.${fieldName}"`);
+            }
+            bindShapedField(field, shape);
+        }
+    }
+}
 export async function compileContracts(model, config) {
     const compilerConfig = config;
     const diagnostics = [];
@@ -856,6 +920,9 @@ export async function compileContracts(model, config) {
             ],
         };
     }
+    bindShapedFields(core, compilerConfig.root.fields);
+    bindShapedFields(application, compilerConfig.application.fields);
+    bindShapedFields(client, compilerConfig.client.fields);
     return {
         ok: true,
         contracts: { core, application, client },

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

@@ -2,6 +2,7 @@ import type { Adapter } from "../adapters/adapter.interface.js";
 import type { AdapterModel } from "../adapters/adapter-model.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 { FrameworkBehaviorsConfig } from "./framework-behaviors-config.js";
 import type { FrameworkConfig, FrameworkLimitsConfig } from "./framework-config.js";
 import type { FrameworkFieldsConfig } from "./framework-fields-config.js";
@@ -27,6 +28,8 @@ export type ResolvedFrameworkConfig<M extends AdapterModel = AdapterModel> = {
     readonly adapter: Adapter<M>;
     /** The diagnostics sink, from the root configuration only. */
     readonly diagnostics: FrameworkDiagnosticsSink | undefined;
+    /** The misuse sink, from the root configuration only. */
+    readonly misuse: FrameworkMisuseSink | undefined;
     readonly root: ResolvedFrameworkScopeConfig<M>;
     readonly application: ResolvedFrameworkScopeConfig<M>;
     readonly client: ResolvedFrameworkScopeConfig<M>;

package/dist/config/config.resolver.js

@@ -103,6 +103,7 @@ export function resolveFrameworkConfig(config) {
         entrypoint: resolveEntrypoint(config.entrypoint),
         adapter: config.adapter,
         diagnostics: config.diagnostics,
+        misuse: config.misuse,
         root: resolveScope(root),
         application: resolveScope(root, config.application),
         client: resolveScope(root, config.client),

package/dist/config/config.validator.js

@@ -10,6 +10,7 @@ const ROOT_PROPERTIES = new Set([
     "pipelines",
     "transactions",
     "diagnostics",
+    "misuse",
     "application",
     "client",
 ]);
@@ -206,6 +207,11 @@ export function validateFrameworkConfig(value) {
         typeof value.diagnostics !== "function") {
         diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "diagnostics", "diagnostics must be a function when provided"));
     }
+    if (Object.hasOwn(value, "misuse") &&
+        value.misuse !== undefined &&
+        typeof value.misuse !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "misuse", "misuse must be a function when provided"));
+    }
     if (Object.hasOwn(value, "application")) {
         validateScope(value.application, "application", diagnostics);
     }

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

@@ -10,17 +10,24 @@ export type KnownScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit
 };
 /**
  * A scalar field the configuration adds, which the adapter did not discover.
- * `type`, `nullable` and `list` are required.
+ * `type`, `nullable` and `list` are required; it takes no `json` shape.
  */
-export type AddedScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type" | "nullable" | "list"> & {
+export type AddedScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type" | "nullable" | "list" | "json"> & {
     readonly type: FrameworkScalarTypeRef<M>;
     readonly nullable: boolean;
     readonly list: boolean;
+    readonly json?: never;
 };
 /** The shape one authored field name admits, by what the adapter knows of it. */
 type ScalarFieldConfigFor<M extends AdapterModel, R extends FrameworkResourceKey<M>, F> = string extends AdapterFieldKey<M, R> ? FrameworkScalarFieldConfig<M> : F extends AdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
     readonly kind: "relation";
-} ? never : KnownScalarFieldConfig<M> : AddedScalarFieldConfig<M>;
+} ? never : M["resources"][R]["fields"][F] extends {
+    readonly type: {
+        readonly scalar: "json";
+    };
+} ? KnownScalarFieldConfig<M> : Omit<KnownScalarFieldConfig<M>, "json"> & {
+    readonly json?: never;
+} : AddedScalarFieldConfig<M>;
 /** The shape an authored `fields` block is checked against, keyed on its own names. */
 export type FrameworkFieldsShape<M extends AdapterModel, Self> = {
     readonly [R in keyof Self]: R extends FrameworkResourceKey<M> ? {

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

@@ -3,6 +3,7 @@ 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";
@@ -28,7 +29,7 @@ export type FrameworkScopeConfig<M extends AdapterModel = AdapterModel, Cfg = An
     /** Request limits; see {@link FrameworkLimitsConfig}. */
     readonly limits?: FrameworkLimitsConfig;
     /** Guards, pipes, hooks, interceptors and filters run around each operation. */
-    readonly pipelines?: PipelineConfig<M>;
+    readonly pipelines?: PipelineConfig<NoInfer<M>>;
     /** `"none"` turns transactions off; `"interactive"` needs adapter support. */
     readonly transactions?: TransactionCapability;
 };
@@ -40,6 +41,8 @@ export type FrameworkConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFram
     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,5 +1,6 @@
 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">;
@@ -29,6 +30,11 @@ export type FrameworkScalarFieldConfig<M extends AdapterModel = AdapterModel> =
     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>>>;

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

@@ -1,4 +1,5 @@
 import type { ClientContract } from "./contract.js";
+import type { JsonSchema } from "./json-shape.js";
 /**
  * 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
@@ -44,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
@@ -79,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]>;
@@ -219,6 +227,9 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                         readonly format: {
                                             readonly is: "string";
                                         };
+                                        readonly json: {
+                                            readonly is: "jsonSchema";
+                                        };
                                     };
                                 };
                                 readonly relation: {
@@ -396,6 +407,10 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                                         readonly optional: Record<never, never>;
                                                     }];
                                                 };
+                                                readonly nestedWriteFilter: {
+                                                    readonly is: "literal";
+                                                    readonly values: readonly ["scalar"];
+                                                };
                                             };
                                         };
                                     };
@@ -1057,7 +1072,12 @@ 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 of {@link validateClientContractStructure}. A refusal names the

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.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.d.ts

@@ -1,6 +1,7 @@
 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";
@@ -16,6 +17,12 @@ export interface Contract {
     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;
 }
 /** The Contract compiled from the root configuration. */
 export interface CoreContract extends Contract {

package/dist/contracts/field.d.ts

@@ -1,5 +1,6 @@
 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";
 /** A format name that refines a scalar type, carried in the Contract as data. */
 export type ScalarFormat = string;
@@ -63,6 +64,13 @@ 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, in any projection position. Use
@@ -105,6 +113,8 @@ 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;
 };
 /** A relation field; the `target` Resource describes the related row. */
 export type RelationField<C extends Contract> = {

package/dist/contracts/json-shape.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The phantom key a Json Shape's TypeScript type travels under. Type-level only:
+ * no value ever holds it.
+ */
+declare const jsonShapeValue: unique symbol;
+/**
+ * A Json Shape, as the type system sees it: the TypeScript type `Value` of a
+ * value that conforms to it. `AvZ` builds every one; a value from anywhere else —
+ * a Zod schema included — is not one.
+ */
+export interface JsonShape<Value = unknown> {
+    readonly [jsonShapeValue]: Value;
+}
+/** The TypeScript type a {@link JsonShape} describes. */
+export type JsonShapeValue<Shape extends JsonShape> = Shape[typeof jsonShapeValue];
+/** A JSON primitive: what a `const` names. */
+export type JsonSchemaPrimitive = string | number | boolean | null;
+/**
+ * A Json Shape in a Contract: passive JSON Schema (draft 2020-12), restricted to
+ * the forms Aventara emits.
+ */
+export type JsonSchema = {
+    readonly type: "string" | "number" | "integer" | "boolean" | "null";
+} | {
+    readonly const: JsonSchemaPrimitive;
+} | {
+    readonly type: "string";
+    readonly enum: readonly [string, ...string[]];
+} | {
+    readonly type: "object";
+    readonly properties: {
+        readonly [key: string]: JsonSchema;
+    };
+    readonly required?: readonly string[];
+    readonly additionalProperties: false;
+} | {
+    readonly type: "object";
+    readonly additionalProperties: JsonSchema;
+} | {
+    readonly type: "array";
+    readonly items: JsonSchema;
+} | {
+    readonly type: "array";
+    readonly prefixItems: readonly [JsonSchema, ...JsonSchema[]];
+    readonly items: false;
+    readonly minItems: number;
+    readonly maxItems: number;
+} | {
+    readonly anyOf: readonly [JsonSchema, JsonSchema, ...JsonSchema[]];
+} | {
+    readonly oneOf: readonly [JsonSchema, ...JsonSchema[]];
+};
+/**
+ * The type-level carrier of a shaped Json field's TypeScript type, on the field's
+ * `json` member in a typed Contract view. Never present at runtime.
+ */
+export type JsonFieldType<Value> = {
+    readonly "~jsonType": Value;
+};
+/**
+ * A shaped Json field's `json` member in a typed Contract view: the schema, and
+ * the type it describes.
+ */
+export type ShapedJsonSchema<Value> = JsonSchema & JsonFieldType<Value>;
+export {};

package/dist/contracts/json-shape.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/reference-write-limit.d.ts

@@ -0,0 +1,7 @@
+/** The limits a data source may put on how one record writes its references. */
+export declare const REFERENCE_WRITE_LIMITS: readonly ["uniform"];
+/**
+ * `"uniform"`: one record writes the relations that hold a reference either all
+ * as relations or all through their reference fields, never some each way.
+ */
+export type ReferenceWriteLimit = (typeof REFERENCE_WRITE_LIMITS)[number];

package/dist/contracts/reference-write-limit.js

@@ -0,0 +1 @@
+export const REFERENCE_WRITE_LIMITS = ["uniform"];