@aventara/core 1.0.0-rc.1 → 1.0.0-rc.2

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

@@ -5,8 +5,9 @@ import type { AvTransactionCapability } from "../contracts/transaction-capabilit
 import type { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
 import type { AvMisuseSink } from "../runtime/misuse-reporter.js";
 import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvConfigLayerName } from "./config-layer.js";
 import type { AvConfigExemptions } from "./framework-exemptions-config.js";
-import type { AvConfigLayerKind, AvConfigResources } from "./framework-resources-config.js";
+import type { AvConfigLayerKind, AvConfigResources, LayerOfKind } from "./framework-resources-config.js";
 import type { AvPipeline } from "./pipeline-config.js";
 /**
  * Request limits to override; each one left out takes its default from
@@ -29,7 +30,7 @@ type MovedLayerKeys = {
  * `agent`. Stages are added to the root's; `transactionsStyle` and `limits`
  * replace it where an overlay states them; exposure only narrows.
  */
-export type AvConfigLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, Kind extends AvConfigLayerKind = "root"> = MovedLayerKeys & {
+export type AvConfigLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, Kind extends AvConfigLayerKind = "root", Layer extends AvConfigLayerName = LayerOfKind<Kind>> = MovedLayerKeys & {
     /**
      * Whether the layer's `exemptions` hide (`true`, the root's default) or are
      * the only entries exposed (`false`). Each layer narrows its parent: the root
@@ -43,7 +44,7 @@ export type AvConfigLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvCon
     /** Guards, pipes, hooks, interceptors and filters run around every operation of the layer. */
     readonly pipelines?: AvPipeline<NoInfer<M>>;
     /** The per-Resource tree: stages, operations, transactions and fields. */
-    readonly resources?: AvConfigResources<M, Cfg, Kind>;
+    readonly resources?: AvConfigResources<M, Cfg, Kind, Layer>;
     /**
      * The entries that are the opposite of `exposed`. An overlay that sets them
      * states its own `exposed`.
@@ -73,8 +74,8 @@ export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAn
     readonly diagnostics?: AvDiagnosticsSink;
     /** Told about every caller value refused as unreadable or not plain data. */
     readonly misuse?: AvMisuseSink;
-    readonly application?: AvConfigLayer<M, Cfg, "overlay">;
-    readonly client?: AvConfigLayer<M, Cfg, "overlay">;
+    readonly application?: AvConfigLayer<M, Cfg, "overlay", "application">;
+    readonly client?: AvConfigLayer<M, Cfg, "overlay", "client">;
     /**
      * The layer an AI agent's calls run under. It narrows the view of the layer it
      * `extends` (the client's when left out), and its stages run after that
@@ -109,7 +110,7 @@ export type AvConfigMcp = string | {
  * The `agent` layer: the six layer keys, and `extends`, the layer whose final
  * view it narrows and whose stages run before its own.
  */
-export type AvConfigAgentLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = AvConfigLayer<M, Cfg, "overlay"> & {
+export type AvConfigAgentLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = AvConfigLayer<M, Cfg, "overlay", "agent"> & {
     /**
      * The layer the agent starts from: `"client"` (the default), `"application"`
      * or `"root"`. The agent never widens it.

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

@@ -2,8 +2,10 @@ import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvAdapterFieldKey } from "../adapters/adapter-resource.js";
 import type { AvZCheck } from "../avz/avz-check.registry.js";
 import type { AvOperationFamily } from "../operations/operation-identity.js";
-import type { AvStageArguments } from "../runtime/pipeline.js";
+import type { AvPreComputeStageArguments, AvStageArguments } from "../runtime/pipeline.js";
 import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvPreComputeLift } from "./computed-fields.js";
+import type { AvConfigLayerName } from "./config-layer.js";
 import type { AvEffectiveFieldKey } from "./effective-fields.js";
 import type { AvRelationFieldPipeline, AvScalarFieldPipeline } from "./field-pipeline-config.js";
 import type { AvConfigAddedFieldDefinition, AvConfigFieldDefinition, AvConfigKnownFieldDefinition, AvConfigResourceKey } from "./framework-field-definition.js";
@@ -14,12 +16,14 @@ import type { AvPipeline, AvTransactionPipeline } from "./pipeline-config.js";
  */
 export type AvConfigLayerKind = "root" | "overlay";
 /** One operation variant's level: its stages and `forceTransaction`. */
-export type AvConfigVariant<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = NoInfer<AvStageArguments<M, R, F, V>>> = {
+export type AvConfigVariant<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = NoInfer<AvStageArguments<M, R, F, V>>, PreCompute = NoInfer<AvPreComputeStageArguments<M, R, F, V>>> = {
     /**
      * Stages that run for this one operation: at a variant, `ctx.$args` (and a
-     * pipe's arguments) are typed as the operation's arguments.
+     * pipe's arguments) are typed as the operation's arguments; in a guard, a
+     * pipe or a filter a create may lack the fields `compute.create` fills
+     * (write compute runs after them).
      */
-    readonly pipelines?: AvPipeline<NoInfer<M>, R, F, V, A>;
+    readonly pipelines?: AvPipeline<NoInfer<M>, R, F, V, A, PreCompute>;
     /** Runs a plain call of this operation as a one-step transaction. */
     readonly forceTransaction?: boolean;
 };
@@ -31,12 +35,12 @@ type FamilyStageVariant<F extends AvOperationFamily, V extends string> = F exten
  */
 export type AvConfigFamily<M extends AvAdapterModel = AvAdapterModel, Variants = {
     readonly [V in "first" | "unique" | "many" | "count" | "one"]?: unknown;
-}, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily> = AvConfigVariant<M, R, F, FamilyStageVariant<F, Extract<keyof NonNullable<Variants>, string>>, unknown> & {
-    readonly [V in Extract<keyof NonNullable<Variants>, string>]?: AvConfigVariant<M, R, F, V> | undefined;
+}, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, Layer extends AvConfigLayerName = "root"> = AvConfigVariant<M, R, F, FamilyStageVariant<F, Extract<keyof NonNullable<Variants>, string>>, unknown, unknown> & {
+    readonly [V in Extract<keyof NonNullable<Variants>, string>]?: AvConfigVariant<M, R, F, V, NoInfer<AvStageArguments<M, R, F, V>>, NoInfer<AvPreComputeStageArguments<M, R, F, V, AvPreComputeLift<M, Layer>>>> | undefined;
 };
 /** A Resource's families, as the adapter model offers them, each with its level. */
-export type AvConfigOperations<M extends AvAdapterModel = AvAdapterModel, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = {
-    readonly [F in Extract<keyof M["resources"][R]["operations"], AvOperationFamily>]?: AvConfigFamily<M, M["resources"][R]["operations"][F], R, F>;
+export type AvConfigOperations<M extends AvAdapterModel = AvAdapterModel, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Layer extends AvConfigLayerName = "root"> = {
+    readonly [F in Extract<keyof M["resources"][R]["operations"], AvOperationFamily>]?: AvConfigFamily<M, M["resources"][R]["operations"][F], R, F, Layer>;
 };
 /** A Resource's transaction level. */
 export type AvConfigResourceTransactions<M extends AvAdapterModel = AvAdapterModel> = {
@@ -99,18 +103,20 @@ export type AvConfigResourceFields<in out M extends AvAdapterModel = AvAdapterMo
     readonly [F in AvEffectiveFieldKey<M, Cfg, R>]?: Kind extends "root" ? RootFieldConfigFor<M, Cfg, R, F> : OverlayFieldConfigFor<M, Cfg, R, F>;
 };
 /** One Resource's tree: its stages, operations, transactions and fields. */
-export type AvConfigResource<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Kind extends AvConfigLayerKind = "root"> = {
+export type AvConfigResource<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Kind extends AvConfigLayerKind = "root", Layer extends AvConfigLayerName = LayerOfKind<Kind>> = {
     /** Stages that run for every operation of this Resource. */
     readonly pipelines?: AvPipeline<NoInfer<M>, R>;
     /** Per family, and per variant under its family. */
-    readonly operations?: AvConfigOperations<M, R>;
+    readonly operations?: AvConfigOperations<M, R, Layer>;
     /** Stages that run once per transaction with a top-level step on this Resource. */
     readonly transactions?: AvConfigResourceTransactions<M>;
     /** Per field: its definition (root only) and its stages. */
     readonly fields?: AvConfigResourceFields<M, Cfg, R, Kind>;
 };
 /** The `resources` tree of one layer, keyed by the adapter's Resource names. */
-export type AvConfigResources<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out Kind extends AvConfigLayerKind = "root"> = {
-    readonly [R in AvConfigResourceKey<M>]?: AvConfigResource<M, Cfg, R, Kind>;
+export type AvConfigResources<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out Kind extends AvConfigLayerKind = "root", in out Layer extends AvConfigLayerName = LayerOfKind<Kind>> = {
+    readonly [R in AvConfigResourceKey<M>]?: AvConfigResource<M, Cfg, R, Kind, Layer>;
 };
+/** The layers a tree of kind `Kind` may be written in, when it names none. */
+export type LayerOfKind<Kind extends AvConfigLayerKind> = Kind extends "root" ? "root" : Exclude<AvConfigLayerName, "root">;
 export {};

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

@@ -6,11 +6,11 @@ import type { AvConfigResourceKey } from "./framework-field-definition.js";
  * Pipeline registrations for one level of the configuration: a layer, a
  * Resource, a family or a variant. See {@link AvContext}.
  */
-export type AvPipeline<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = {
+export type AvPipeline<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown, PreCompute = A> = {
     /** Run first; a guard returning `false` denies the operation with `A4001`. */
-    readonly guards?: readonly AvGuard<M, R, F, V, A>[];
+    readonly guards?: readonly AvGuard<M, R, F, V, PreCompute>[];
     /** Run in order on the arguments; a pipe may return replacement arguments. */
-    readonly pipes?: readonly AvPipe<M, R, F, V, A>[];
+    readonly pipes?: readonly AvPipe<M, R, F, V, PreCompute>[];
     /**
      * Run around the operation, inside every level's interceptors: `before`
      * hooks outer to inner, `after` hooks inner to outer.
@@ -22,7 +22,7 @@ export type AvPipeline<M extends AvAdapterModel = AvAdapterModel, R extends stri
     /** Wrap everything below this level; each calls `next()` to continue. */
     readonly interceptors?: readonly AvInterceptor<M, R, F, V, A>[];
     /** Turn a thrown error into a {@link AvError} outcome. */
-    readonly filters?: readonly AvFilter<M, R, F, V, A>[];
+    readonly filters?: readonly AvFilter<M, R, F, V, PreCompute>[];
 };
 /**
  * A Resource's transaction stages: they run once per transaction with a

package/dist/contracts/capability.d.ts

@@ -1,5 +1,14 @@
 /** The operators a scalar field can be filtered with. */
 export type AvScalarFilterOperator = "equals" | "not" | "in" | "notIn" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith" | "mode" | "has" | "hasEvery" | "hasSome" | "isEmpty" | "path" | "stringContains" | "stringStartsWith" | "stringEndsWith" | "arrayContains" | "arrayStartsWith" | "arrayEndsWith";
+/**
+ * The case-sensitivity a text filter's `mode` asks for. `"default"` is whatever
+ * the database's own comparison does and is always available; `"sensitive"` and
+ * `"insensitive"` are an explicit promise, available on a field only where its
+ * `filterModes` lists them.
+ */
+export declare const FILTER_MODES: readonly ["default", "sensitive", "insensitive"];
+/** @see FILTER_MODES, the axis this union is derived from. */
+export type ScalarFilterMode = (typeof FILTER_MODES)[number];
 /** What an update can do to a scalar value besides setting it. */
 export type AvScalarMutationDirective = "$increment" | "$decrement" | "$multiply" | "$divide" | "$push" | "$unset";
 /** How a relation can be filtered on. */
@@ -24,6 +33,6 @@ export type AvProjectionScope = (typeof PROJECTION_SCOPES)[number];
  * not the operation that carries it. The write counterpart of
  * {@link AvProjectionScope}.
  */
-export declare const WRITE_SCOPES: readonly ["nested", "bulkWrite"];
+export declare const WRITE_SCOPES: readonly ["nested", "bulkWrite", "loopback"];
 /** @see WRITE_SCOPES, the axis this union is derived from. */
 export type AvWriteScope = (typeof WRITE_SCOPES)[number];

package/dist/contracts/capability.js

@@ -1,3 +1,4 @@
+export const FILTER_MODES = ["default", "sensitive", "insensitive"];
 export const PROJECTION_SCOPES = [
     "record",
     "bulkWrite",
@@ -5,4 +6,5 @@ export const PROJECTION_SCOPES = [
 export const WRITE_SCOPES = [
     "nested",
     "bulkWrite",
+    "loopback",
 ];

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

@@ -197,6 +197,24 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                                     readonly minimum: 0;
                                                     readonly unique: false;
                                                 };
+                                                readonly filterModes: {
+                                                    readonly is: "list";
+                                                    readonly item: {
+                                                        readonly is: "literal";
+                                                        readonly values: readonly ["default", "sensitive", "insensitive"];
+                                                    };
+                                                    readonly minimum: 0;
+                                                    readonly unique: false;
+                                                };
+                                                readonly pathFilterModes: {
+                                                    readonly is: "list";
+                                                    readonly item: {
+                                                        readonly is: "literal";
+                                                        readonly values: readonly ["default", "sensitive", "insensitive"];
+                                                    };
+                                                    readonly minimum: 0;
+                                                    readonly unique: false;
+                                                };
                                                 readonly order: {
                                                     readonly is: "boolean";
                                                 };
@@ -613,7 +631,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                                                 readonly is: "list";
                                                                 readonly item: {
                                                                     readonly is: "literal";
-                                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                                 };
                                                                 readonly minimum: 1;
                                                                 readonly unique: false;
@@ -648,7 +666,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                                                 readonly is: "list";
                                                                 readonly item: {
                                                                     readonly is: "literal";
-                                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                                 };
                                                                 readonly minimum: 1;
                                                                 readonly unique: false;
@@ -664,7 +682,19 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             };
                                         };
                                     };
-                                    readonly optional: Record<never, never>;
+                                    readonly optional: {
+                                        readonly inverse: {
+                                            readonly is: "string";
+                                        };
+                                        readonly referenceFields: {
+                                            readonly is: "list";
+                                            readonly item: {
+                                                readonly is: "string";
+                                            };
+                                            readonly minimum: 1;
+                                            readonly unique: false;
+                                        };
+                                    };
                                 };
                             };
                         };
@@ -706,7 +736,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -714,7 +744,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -741,7 +771,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -749,7 +779,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -776,7 +806,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -784,7 +814,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -811,7 +841,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -819,7 +849,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -852,7 +882,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -860,7 +890,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -887,7 +917,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -895,7 +925,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -922,7 +952,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -930,7 +960,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -963,7 +993,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -971,7 +1001,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -998,7 +1028,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -1006,7 +1036,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -1033,7 +1063,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -1041,7 +1071,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -1068,7 +1098,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -1076,7 +1106,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -1109,7 +1139,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -1117,7 +1147,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -1144,7 +1174,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -1152,7 +1182,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -1179,7 +1209,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -1187,7 +1217,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -1214,7 +1244,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -1222,7 +1252,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {
@@ -1255,7 +1285,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly optional: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                         }, {
@@ -1263,7 +1293,7 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly required: {
                                                 readonly write: {
                                                     readonly is: "literal";
-                                                    readonly values: readonly ["nested", "bulkWrite"];
+                                                    readonly values: readonly ["nested", "bulkWrite", "loopback"];
                                                 };
                                             };
                                             readonly optional: {

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

@@ -1,4 +1,4 @@
-import { PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
+import { FILTER_MODES, 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";
@@ -226,6 +226,8 @@ const SCALAR_FIELD = object({
     capabilities: object({}, {
         select: BOOLEAN,
         filter: list(literal(SCALAR_FILTER_OPERATORS)),
+        filterModes: list(literal(FILTER_MODES)),
+        pathFilterModes: list(literal(FILTER_MODES)),
         order: BOOLEAN,
         orderNulls: BOOLEAN,
         create: list(literal(SCALAR_MUTATION_DIRECTIVES)),
@@ -255,7 +257,7 @@ const RELATION_FIELD = object({
         update: RELATION_MUTATION,
         nestedWriteFilter: literal(["scalar"]),
     }),
-});
+}, { inverse: STRING, referenceFields: nonEmptyList(STRING) });
 const OPERATION_AVAILABILITY = union(literal([true]), object({ projection: literal(PROJECTION_SCOPES) }, { write: literal(WRITE_SCOPES) }), object({ write: literal(WRITE_SCOPES) }, { projection: literal(PROJECTION_SCOPES) }));
 const RESOURCE = object({
     fields: registry({

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

@@ -7,6 +7,13 @@ export declare class AvCanonicalJsonError extends TypeError {
 }
 /** Canonical JSON (RFC 8785) for a JSON-safe value. */
 export declare function canonicalizeJson(value: unknown): string;
+/**
+ * Canonical JSON (RFC 8785) for a value as JSON carries it: a key holding
+ * `undefined` is left out, and an array element holding it (or a hole) is
+ * `null`, as `JSON.stringify` writes them. Everything else as
+ * {@link canonicalizeJson}.
+ */
+export declare function canonicalizeWireJson(value: unknown): string;
 /** One top-level member of a canonical Contract: its key and its value's canonical text. */
 export type CanonicalContractMember = {
     readonly key: string;

package/dist/contracts/contract-canonicalizer.js

@@ -1,4 +1,4 @@
-import { PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
+import { FILTER_MODES, PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
 import { LIFECYCLE_TRAITS } from "./lifecycle-trait.js";
 import { projectionScopeOf, writeScopeOf } from "./resource-operations.js";
 const PAGINATION_ORDER = ["limit", "offset", "cursor"];
@@ -61,6 +61,12 @@ function normalizeCapabilities(capabilities) {
     if (Array.isArray(filter)) {
         normalized.filter = normalizeStringSet(filter);
     }
+    for (const key of ["filterModes", "pathFilterModes"]) {
+        const modes = normalized[key];
+        if (Array.isArray(modes)) {
+            normalized[key] = normalizeStringSet(modes, FILTER_MODES);
+        }
+    }
     for (const key of ["create", "update"]) {
         const value = normalized[key];
         if (Array.isArray(value)) {
@@ -286,7 +292,7 @@ function canonicalizePrimitive(value, link) {
             return undefined;
     }
 }
-function canonicalizeValue(value, link = undefined) {
+function canonicalizeValue(value, link = undefined, undefinedAsJson = false) {
     const output = [];
     const stack = [{ kind: "value", value, link }];
     while (stack.length > 0) {
@@ -310,7 +316,10 @@ function canonicalizeValue(value, link = undefined) {
             output.push("[");
             stack.push({ kind: "text", text: "]" });
             for (let index = current.length - 1; index >= 0; index -= 1) {
-                if (index in current) {
+                if (undefinedAsJson && current[index] === undefined) {
+                    stack.push({ kind: "text", text: "null" });
+                }
+                else if (index in current) {
                     stack.push({
                         kind: "value",
                         value: current[index],
@@ -328,7 +337,9 @@ function canonicalizeValue(value, link = undefined) {
             throw new AvCanonicalJsonError(`non-plain object at ${pathOf(link)} is not canonical JSON`);
         }
         const record = current;
-        const keys = Object.keys(record).sort(compareCodeUnits);
+        const keys = Object.keys(record)
+            .filter((key) => !undefinedAsJson || record[key] !== undefined)
+            .sort(compareCodeUnits);
         output.push("{");
         stack.push({ kind: "text", text: "}" });
         for (let index = keys.length - 1; index >= 0; index -= 1) {
@@ -349,6 +360,9 @@ function canonicalizeValue(value, link = undefined) {
 export function canonicalizeJson(value) {
     return canonicalizeValue(value);
 }
+export function canonicalizeWireJson(value) {
+    return canonicalizeValue(value, undefined, true);
+}
 export function canonicalizeContractMembers(contract) {
     const record = normalizeContract(contract);
     return Object.keys(record)