@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

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

@@ -1,5 +1,5 @@
 /** The request limits a Contract enforces. */
-export type ContractLimits = {
+export type AvContractLimits = {
     /** The largest request body accepted, in bytes. */
     readonly maxRequestBytes: number;
     /** How deeply arguments may nest. */
@@ -10,6 +10,8 @@ export type ContractLimits = {
     readonly maxTransactionOperations: number;
     /** The most boolean and filter nodes one request may hold. */
     readonly maxBooleanNodes: number;
+    /** How deeply a `json` field's value may nest: its arrays and objects, counted from the value. */
+    readonly maxJsonDepth: number;
 };
 /** The limits in force when the configuration sets none. */
 export declare const DEFAULT_CONTRACT_LIMITS: {
@@ -18,4 +20,5 @@ export declare const DEFAULT_CONTRACT_LIMITS: {
     readonly maxListLimit: 250;
     readonly maxTransactionOperations: 20;
     readonly maxBooleanNodes: 50;
+    readonly maxJsonDepth: 64;
 };

package/dist/contracts/contract-limits.js

@@ -4,4 +4,5 @@ export const DEFAULT_CONTRACT_LIMITS = {
     maxListLimit: 250,
     maxTransactionOperations: 20,
     maxBooleanNodes: 50,
+    maxJsonDepth: 64,
 };

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

@@ -1,6 +1,6 @@
-import type { Contract } from "./contract.js";
-import type { Field } from "./field.js";
-import type { Resource } from "./resource.js";
+import type { AvContract } from "./contract.js";
+import type { AvField } from "./field.js";
+import type { AvResource } from "./resource.js";
 /**
  * Own-property lookups over Contract registries.
  *
@@ -12,5 +12,5 @@ import type { Resource } from "./resource.js";
  * must go through here so an unknown key is unknown, whatever its name.
  */
 export declare function lookupOwn<T>(registry: Readonly<Record<string, T>> | undefined, key: string): T | undefined;
-export declare function lookupResource<C extends Contract>(contract: C, resourceName: string): Resource<C> | undefined;
-export declare function lookupField<C extends Contract>(resource: Resource<C> | undefined, fieldName: string): Field<C> | undefined;
+export declare function lookupResource<C extends AvContract>(contract: C, resourceName: string): AvResource<C> | undefined;
+export declare function lookupField<C extends AvContract>(resource: AvResource<C> | undefined, fieldName: string): AvField<C> | undefined;

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

@@ -5,13 +5,13 @@
  */
 export declare const AVENTARA_PROTOCOL_VERSION: 1;
 /** A Contract hash: `sha256:` followed by the hex digest. */
-export type ContractHash = `sha256:${string}`;
+export type AvContractHash = `sha256:${string}`;
 /** The protocol a Contract is written for. */
-export type ContractProtocol = {
+export type AvContractProtocol = {
     /** 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;
+export type AvContractClientProtocol = AvContractProtocol & {
+    readonly hash: AvContractHash;
 };

package/dist/contracts/contract.d.ts

@@ -1,22 +1,24 @@
-import type { ContractLimits } from "./contract-limits.js";
-import type { ClientContractProtocol } from "./contract-protocol.js";
-import type { EnumDefinition } from "./enum-definition.js";
+import type { AvContractClientAccess } from "./contract-access.js";
+import type { AvContractLimits } from "./contract-limits.js";
+import type { AvContractClientProtocol } from "./contract-protocol.js";
+import type { AvEnumDefinition } from "./enum-definition.js";
+import type { AvCoreField } from "./field.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";
+import type { AvResource } from "./resource.js";
+import type { AvScalarRegistry } from "./scalar.js";
+import type { AvTransactionCapability } from "./transaction-capability.js";
 /** What every Contract describes: scalars, enums, Resources, limits and transactions. */
-export interface Contract {
+export interface AvContract {
     /** The scalar types available. */
-    readonly scalars: ScalarRegistry;
+    readonly scalars: AvScalarRegistry;
     /** The enums, by name. */
-    readonly enums: Readonly<Record<string, EnumDefinition>>;
+    readonly enums: Readonly<Record<string, AvEnumDefinition>>;
     /** The Resources, by name. */
-    readonly resources: Readonly<Record<string, Resource<this>>>;
+    readonly resources: Readonly<Record<string, AvResource<this>>>;
     /** The request limits in force. */
-    readonly limits: ContractLimits;
+    readonly limits: AvContractLimits;
     /** Whether interactive transactions are available. */
-    readonly transactions: TransactionCapability;
+    readonly transactions: AvTransactionCapability;
     /**
      * `"uniform"` when one record must write the relations that hold a reference
      * either all as relations or all through their reference fields; a record
@@ -24,17 +26,49 @@ export interface Contract {
      */
     readonly referenceWrites?: ReferenceWriteLimit;
 }
-/** The Contract compiled from the root configuration. */
-export interface CoreContract extends Contract {
+/**
+ * The Contract compiled from the root configuration. Its relation fields also
+ * state the target's fields their reference names (`references`), and its
+ * Resources the database schema the store keeps them in (`schema`) and whether
+ * another service owns them (`managedElsewhere`), which no other Contract
+ * carries.
+ */
+export interface AvContractCore extends AvContract {
+    /** The Resources, by name. */
+    readonly resources: Readonly<Record<string, AvCoreResource>>;
+}
+/**
+ * A Resource as the Core Contract states it: its fields are
+ * {@link AvCoreField}s, so its relation fields carry `references`.
+ */
+export interface AvCoreResource extends AvResource<AvContractCore> {
+    readonly fields: Readonly<Record<string, AvCoreField<AvContractCore>>>;
+    /** The database schema the store keeps this Resource in, when the adapter states one. */
+    readonly schema?: string;
+    /** Present when another service owns this Resource: it is read, never written. */
+    readonly managedElsewhere?: true;
 }
 /** The Contract in-process calls run under (`framework.application`). */
-export interface ApplicationContract extends Contract {
+export interface AvContractApplication extends AvContract {
 }
 /**
  * The Contract remote clients run under, published at `GET /_contract` and
  * identified by its hash.
  */
-export interface ClientContract extends Contract {
+export interface AvContractClient extends AvContract {
+    /** The protocol version and this Contract's hash. */
+    readonly protocol: AvContractClientProtocol;
+    /**
+     * Present exactly when the framework's `access` option is configured: the
+     * `POST /_access/can` route, and `$access`'s other verbs when it has `verbs`.
+     */
+    readonly access?: AvContractClientAccess;
+}
+/**
+ * The Contract an AI agent's calls run under (the `agent` layer), identified by
+ * its hash. MCP tools are built from it.
+ */
+export interface AvContractAgent extends AvContract {
     /** The protocol version and this Contract's hash. */
-    readonly protocol: ClientContractProtocol;
+    readonly protocol: AvContractClientProtocol;
 }

package/dist/contracts/create-requirements.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A required to-one relation and the scalar fields that hold its reference,
+ * relation first: `["author", "authorId"]`. A create writes the relation, or
+ * every one of the fields together (`["author", "tenantId", "authorId"]` for a
+ * composite reference), never both.
+ */
+export type AvCreateRequirementGroup = readonly [string, string, ...string[]];
+/**
+ * What a create of one Resource cannot do without, as the Contract's layer
+ * exposes it. Only fields the layer lets a caller write at create appear: a
+ * group whose reference fields the layer hides is its relation alone, in
+ * `required`; one whose relation it hides is its reference fields, in
+ * `required`; a field a compute stage fills at create (`COMPUTED_ON_CREATE`) is
+ * not required.
+ */
+export type AvCreateRequirements = {
+    /**
+     * The fields every create must write: scalars with no default, generated or
+     * computed value, and relations whose reference fields the layer hides.
+     */
+    readonly required?: readonly [string, ...string[]];
+    /** The required relations a create writes either way: see {@link AvCreateRequirementGroup}. */
+    readonly oneOf?: readonly [
+        AvCreateRequirementGroup,
+        ...AvCreateRequirementGroup[]
+    ];
+    /**
+     * By parent Resource, then by its relation: the fields above that a create
+     * nested through that relation gets from its parent, so it is not required
+     * there. `{ "User": { "posts": ["author", "authorId"] } }`: a post created in
+     * `User.posts` needs neither `author` nor `authorId`; a group any of whose
+     * fields is listed is satisfied whole.
+     */
+    readonly parentSupplies?: Readonly<Record<string, Readonly<Record<string, readonly [string, ...string[]]>>>>;
+};

package/dist/contracts/create-requirements.js

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

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

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

package/dist/contracts/field-check.d.ts

@@ -0,0 +1,101 @@
+/** The named string formats: what `AvZ.email()`, `AvZ.uuid()` and the rest check. */
+export type AvFieldCheckFormat = "email" | "url" | "emoji" | "uuid" | "guid" | "nanoid" | "cuid" | "cuid2" | "ulid" | "xid" | "ksuid" | "datetime" | "date" | "time" | "duration" | "ipv4" | "ipv6" | "cidrv4" | "cidrv6" | "base64" | "base64url" | "json_string" | "e164" | "credit_card" | "iban" | "jwt";
+/**
+ * A bound on a value (`AvZ.lt`, `AvZ.gte`, `AvZ.positive`, …). `value` is a number
+ * for an `int` or `float` field and a Json number; for a `bigint`, `decimal` or
+ * `datetime` field it is the bound's wire string.
+ */
+export type AvFieldRangeCheck = {
+    readonly check: "less_than" | "greater_than";
+    readonly value: number | string;
+    readonly inclusive: boolean;
+};
+/** `AvZ.multipleOf`: `value` is written as {@link AvFieldRangeCheck}'s is. */
+export type AvFieldMultipleCheck = {
+    readonly check: "multiple_of";
+    readonly value: number | string;
+};
+/** A length bound: a string's, or with `list: true` a list's. */
+export type AvFieldLengthCheck = {
+    readonly check: "max_length";
+    readonly maximum: number;
+    readonly list?: true;
+} | {
+    readonly check: "min_length";
+    readonly minimum: number;
+    readonly list?: true;
+} | {
+    readonly check: "length_equals";
+    readonly length: number;
+};
+/** A pattern or a named format a string must match. */
+export type AvFieldFormatCheck = {
+    readonly check: "string_format";
+    readonly format: "regex";
+    /** A JavaScript regular expression: its `source` and its `flags`. */
+    readonly pattern: {
+        readonly source: string;
+        readonly flags: string;
+    };
+} | {
+    readonly check: "string_format";
+    readonly format: "includes";
+    readonly includes: string;
+} | {
+    readonly check: "string_format";
+    readonly format: "starts_with";
+    readonly prefix: string;
+} | {
+    readonly check: "string_format";
+    readonly format: "ends_with";
+    readonly suffix: string;
+} | {
+    readonly check: "string_format";
+    readonly format: "lowercase" | "uppercase" | AvFieldCheckFormat;
+};
+/** A `bytes` value's byte length. */
+export type AvFieldSizeCheck = {
+    readonly check: "max_size";
+    readonly maximum: number;
+} | {
+    readonly check: "min_size";
+    readonly minimum: number;
+} | {
+    readonly check: "size_equals";
+    readonly size: number;
+};
+/**
+ * One field validator as the Contract stores it: its check's name (`check`) and
+ * the check's parameters.
+ */
+export type AvFieldCheck = AvFieldRangeCheck | AvFieldMultipleCheck | AvFieldLengthCheck | AvFieldFormatCheck | AvFieldSizeCheck;
+/** The checks a Json Shape's string node may carry: its length, a pattern or a format. */
+export type AvJsonStringCheck = {
+    readonly check: "max_length";
+    readonly maximum: number;
+} | {
+    readonly check: "min_length";
+    readonly minimum: number;
+} | {
+    readonly check: "length_equals";
+    readonly length: number;
+} | AvFieldFormatCheck;
+/** The checks a Json Shape's number or integer node may carry: bounds are numbers. */
+export type AvJsonNumberCheck = {
+    readonly check: "less_than" | "greater_than";
+    readonly value: number;
+    readonly inclusive: boolean;
+} | {
+    readonly check: "multiple_of";
+    readonly value: number;
+};
+/** The checks a Json Shape's array node may carry: its length. */
+export type AvJsonListCheck = {
+    readonly check: "max_length";
+    readonly maximum: number;
+    readonly list: true;
+} | {
+    readonly check: "min_length";
+    readonly minimum: number;
+    readonly list: true;
+};

package/dist/contracts/field-check.js

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

package/dist/contracts/field.d.ts

@@ -1,72 +1,89 @@
-import type { PaginationCapability, ProjectionScope, RelationFilterCapability, RelationMutationDirective, RelationReducer, ScalarFilterOperator, ScalarMutationDirective, WriteScope } from "./capability.js";
-import type { Contract } from "./contract.js";
+import type { AvPaginationCapability, AvProjectionScope, AvRelationFilterCapability, AvRelationMutationDirective, AvRelationReducer, AvScalarFilterOperator, AvScalarMutationDirective, AvWriteScope, ScalarFilterMode } from "./capability.js";
+import type { AvContract } from "./contract.js";
+import type { AvFieldCheck } from "./field-check.js";
 import type { JsonSchema } from "./json-shape.js";
-import type { LifecycleTrait } from "./lifecycle-trait.js";
+import type { AvLifecycleTrait } from "./lifecycle-trait.js";
 /** A format name that refines a scalar type, carried in the Contract as data. */
-export type ScalarFormat = string;
+export type AvScalarFormat = string;
 /** The projection positions a field can be selected in (at least one). */
-export type ProjectionScopes = readonly [ProjectionScope, ...ProjectionScope[]];
+export type AvProjectionScopes = readonly [
+    AvProjectionScope,
+    ...AvProjectionScope[]
+];
 /**
  * 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}.
+ * applies to the top level of a write argument only; see {@link AvWriteScope}.
  */
-export type WriteScopes = readonly [WriteScope, ...WriteScope[]];
+export type AvWriteScopes = readonly [AvWriteScope, ...AvWriteScope[]];
 /**
  * Whether a relation can be selected or included: `true`, or the projection
  * positions it can be used in.
  */
-export type RelationProjectionCapability = boolean | ProjectionScopes;
+export type AvRelationProjectionCapability = boolean | AvProjectionScopes;
 /**
  * The reducers a relation admits, qualified by the projection positions they are
  * admitted in. The reducer list and the scope list are separate facts: `$count` is
  * one of a closed set of reducers, and the scopes say where the reducer may be
  * asked for.
  */
-export type ScopedRelationReducers = {
-    readonly reducers: readonly RelationReducer[];
-    readonly scopes: ProjectionScopes;
+export type AvScopedRelationReducers = {
+    readonly reducers: readonly AvRelationReducer[];
+    readonly scopes: AvProjectionScopes;
 };
 /**
  * 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;
+export type AvRelationReducerCapability = readonly AvRelationReducer[] | AvScopedRelationReducers;
 /**
  * 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;
+export type AvScopedRelationMutations = {
+    readonly directives: readonly AvRelationMutationDirective[];
+    readonly scopes: AvWriteScopes;
 };
 /**
  * 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;
+export type AvRelationMutationCapability = readonly AvRelationMutationDirective[] | AvScopedRelationMutations;
 /** What can be done with a scalar field. Scalar capabilities apply in every position. */
-export type ScalarFieldCapabilities = {
+export type AvScalarFieldCapabilities = {
     readonly select?: boolean;
-    readonly filter?: readonly ScalarFilterOperator[];
+    readonly filter?: readonly AvScalarFilterOperator[];
+    /**
+     * The modes the `mode` operator takes on this field: `"default"` (the
+     * database's own comparison) always, and `"sensitive"` or `"insensitive"`
+     * where the adapter honours them. Present exactly when `filter` offers `mode`.
+     */
+    readonly filterModes?: readonly ScalarFilterMode[];
+    /**
+     * A `json` field's modes when the filter names a `path`: the text compared is
+     * the value at that path rather than the whole document, and the database may
+     * honour more modes there. Present exactly when `filter` offers `mode` and
+     * `path`; without a `path`, `filterModes` applies.
+     */
+    readonly pathFilterModes?: readonly ScalarFilterMode[];
     readonly order?: boolean;
     readonly orderNulls?: boolean;
-    readonly create?: readonly ScalarMutationDirective[];
-    readonly update?: readonly ScalarMutationDirective[];
+    readonly create?: readonly AvScalarMutationDirective[];
+    readonly update?: readonly AvScalarMutationDirective[];
 };
 /** What can be done with a relation field. */
-export type RelationFieldCapabilities = {
-    readonly select?: RelationProjectionCapability;
-    readonly include?: RelationProjectionCapability;
-    readonly filter?: readonly RelationFilterCapability[];
+export type AvRelationFieldCapabilities = {
+    readonly select?: AvRelationProjectionCapability;
+    readonly include?: AvRelationProjectionCapability;
+    readonly filter?: readonly AvRelationFilterCapability[];
     readonly order?: boolean;
-    readonly pagination?: readonly PaginationCapability[];
-    readonly reducers?: RelationReducerCapability;
-    readonly create?: RelationMutationCapability;
-    readonly update?: RelationMutationCapability;
+    readonly pagination?: readonly AvPaginationCapability[];
+    readonly reducers?: AvRelationReducerCapability;
+    readonly create?: AvRelationMutationCapability;
+    readonly update?: AvRelationMutationCapability;
     /**
      * What the `where` of a nested `$update` or `$delete` through this relation may
-     * filter: `"scalar"` — the target's scalar fields only, combined with
+     * filter: `"scalar"` means the target's scalar fields only, combined with
      * `AND`/`OR`/`NOT`, and no relation filter at any depth. Absent: any filter the
      * target takes.
      */
@@ -76,53 +93,103 @@ export type RelationFieldCapabilities = {
  * 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;
+export declare function advertisedReducers(capability: AvRelationReducerCapability | undefined): readonly AvRelationReducer[] | undefined;
 /** Whether a projection capability holds at one projection position. */
-export declare function holdsAt(capability: RelationProjectionCapability | undefined, scope: ProjectionScope): boolean;
+export declare function holdsAt(capability: AvRelationProjectionCapability | undefined, scope: AvProjectionScope): boolean;
 /**
  * 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;
+export declare function holdsInAnyScope(capability: AvRelationProjectionCapability | undefined): boolean;
 /**
  * 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;
+export declare function advertisedReducersAt(capability: AvRelationReducerCapability | undefined, scope: AvProjectionScope): readonly AvRelationReducer[] | undefined;
 /**
  * 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;
+export declare function advertisedDirectives(capability: AvRelationMutationCapability | undefined): readonly AvRelationMutationDirective[] | undefined;
 /**
  * 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;
+export declare function advertisedDirectivesAt(capability: AvRelationMutationCapability | undefined, scope: AvWriteScope): readonly AvRelationMutationDirective[] | undefined;
 /** A scalar field, including an enum-backed one. */
-export type ScalarField<C extends Contract> = {
+export type AvScalarField<C extends AvContract> = {
     readonly kind: "scalar";
     readonly type: {
         readonly scalar: Extract<keyof C["scalars"], string>;
     } | {
         readonly enum: Extract<keyof C["enums"], string>;
     };
-    readonly format?: ScalarFormat;
+    readonly format?: AvScalarFormat;
     readonly nullable: boolean;
     readonly list: boolean;
-    readonly lifecycle: readonly LifecycleTrait[];
-    readonly capabilities: ScalarFieldCapabilities;
+    readonly lifecycle: readonly AvLifecycleTrait[];
+    readonly capabilities: AvScalarFieldCapabilities;
     /** A `json` field's shape, as JSON Schema: what every value written to it is. */
     readonly json?: JsonSchema;
+    /**
+     * The field's validators: the root's checks, then the overlay's, in
+     * registration order. On a list field a check applies to each entry, except a
+     * `list: true` length check, which applies to the list.
+     */
+    readonly validators?: readonly AvFieldCheck[];
+    /**
+     * `true` when the policy governs the field: it is left out of every default
+     * projection, and a caller that wants it names it (`select: ["$defaults",
+     * "email"]`).
+     */
+    readonly governed?: true;
 };
 /** A relation field; the `target` Resource describes the related row. */
-export type RelationField<C extends Contract> = {
+export type AvRelationField<C extends AvContract> = {
     readonly kind: "relation";
     readonly target: Extract<keyof C["resources"], string>;
     readonly cardinality: "one" | "many";
     readonly nullable: boolean;
-    readonly capabilities: RelationFieldCapabilities;
+    readonly capabilities: AvRelationFieldCapabilities;
+    /**
+     * The target's relation field that is this relation's other end
+     * (`User.posts` ↔ `Post.author`): a record written through this relation sits
+     * at that field's `"loopback"` write position. Absent when the adapter states
+     * no pairing or the layer hides the other end.
+     */
+    readonly inverse?: string;
+    /**
+     * The scalar fields of this Resource that hold the relation's reference, in the
+     * order the data source pairs them with the target's key (`Post.category` has
+     * `["categoryId"]`). Writing the relation and one of them in one record names
+     * the reference twice; inside a record written through the relation's other
+     * end they sit at the `"loopback"` position with it. Absent on the end that
+     * holds no reference, and where the layer shows none of them.
+     */
+    readonly referenceFields?: readonly [string, ...string[]];
+    /**
+     * `true` when the policy engine's `governed` set names the relation: including
+     * it on rows the caller may not read it on refuses the request.
+     */
+    readonly governed?: true;
 };
 /** One field of a Resource: a scalar or a relation. */
-export type Field<C extends Contract> = ScalarField<C> | RelationField<C>;
+export type AvField<C extends AvContract> = AvScalarField<C> | AvRelationField<C>;
+/**
+ * A relation field as the Core Contract states it: an {@link AvRelationField}
+ * and, on the end that holds the reference, the target's fields it names.
+ */
+export type AvCoreRelationField<C extends AvContract> = AvRelationField<C> & {
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in the
+     * same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`). Present only beside a `referenceFields` the
+     * Contract states whole, and only when every one of them is a scalar field
+     * the Core Contract shows on the target; absent on the end that holds no
+     * reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
+};
+/** One field of a Resource as the Core Contract states it. */
+export type AvCoreField<C extends AvContract> = AvScalarField<C> | AvCoreRelationField<C>;

package/dist/contracts/identifier.d.ts

@@ -1,7 +1,7 @@
-import type { Contract } from "./contract.js";
-import type { Field } from "./field.js";
+import type { AvContract } from "./contract.js";
+import type { AvField } from "./field.js";
 /** Keys of `TFields` whose field can be scalar-shaped. */
-export type ScalarFieldKey<TFields extends Readonly<Record<string, Field<Contract>>>> = Extract<{
+export type AvScalarFieldKey<TFields extends Readonly<Record<string, AvField<AvContract>>>> = Extract<{
     [K in keyof TFields]: [
         Extract<TFields[K], {
             readonly kind: "scalar";
@@ -9,4 +9,4 @@ export type ScalarFieldKey<TFields extends Readonly<Record<string, Field<Contrac
     ] extends [never] ? never : K;
 }[keyof TFields], string>;
 /** Non-empty tuple of scalar field keys that identifies at most one Resource. */
-export type Identifier<TFields extends Readonly<Record<string, Field<Contract>>>> = readonly [ScalarFieldKey<TFields>, ...ScalarFieldKey<TFields>[]];
+export type AvIdentifier<TFields extends Readonly<Record<string, AvField<AvContract>>>> = readonly [AvScalarFieldKey<TFields>, ...AvScalarFieldKey<TFields>[]];

package/dist/contracts/json-schema.projector.d.ts

@@ -0,0 +1,11 @@
+type Schema = {
+    readonly [key: string]: unknown;
+};
+/**
+ * `value` projected onto `schema` (the `json` field subset): every object down
+ * to the members the schema declares, a list member by member, frozen.
+ *
+ * @throws TypeError when the value is not one the schema describes.
+ */
+export declare function projectJsonValue(value: unknown, schema: Schema): unknown;
+export {};

package/dist/contracts/json-schema.projector.js

@@ -0,0 +1,78 @@
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function memberSchema(schema) {
+    if (!isRecord(schema)) {
+        throw new TypeError("the schema is not one of the forms a ClientContract states");
+    }
+    return schema;
+}
+function fits(value, schema) {
+    if (Object.hasOwn(schema, "const")) {
+        return value === schema.const;
+    }
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.includes(value);
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const options = schema[keyword];
+        if (Array.isArray(options)) {
+            return options.some((option) => fits(value, option));
+        }
+    }
+    switch (schema.type) {
+        case "null":
+            return value === null;
+        case "boolean":
+            return typeof value === "boolean";
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number";
+        case "integer":
+            return Number.isInteger(value);
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isRecord(value);
+        default:
+            return false;
+    }
+}
+export function projectJsonValue(value, schema) {
+    if (!fits(value, schema)) {
+        throw new TypeError("the value is not the one the ClientContract describes");
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const options = schema[keyword];
+        if (Array.isArray(options)) {
+            const option = options.find((candidate) => fits(value, candidate));
+            return projectJsonValue(value, option);
+        }
+    }
+    if (Array.isArray(value)) {
+        const prefix = schema.prefixItems;
+        const items = Array.isArray(prefix)
+            ? undefined
+            : memberSchema(schema.items);
+        return Object.freeze(value.map((member, index) => projectJsonValue(member, items ?? memberSchema(prefix[index]))));
+    }
+    if (isRecord(value)) {
+        const properties = schema.properties;
+        if (isRecord(properties)) {
+            const copy = {};
+            for (const [key, member] of Object.entries(properties)) {
+                if (Object.hasOwn(value, key) && value[key] !== undefined) {
+                    copy[key] = projectJsonValue(value[key], member);
+                }
+            }
+            return Object.freeze(copy);
+        }
+        const values = memberSchema(schema.additionalProperties);
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, member]) => [
+            key,
+            projectJsonValue(member, values),
+        ])));
+    }
+    return value;
+}