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

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)

package/dist/contracts/field.d.ts

@@ -1,4 +1,4 @@
-import type { AvPaginationCapability, AvProjectionScope, AvRelationFilterCapability, AvRelationMutationDirective, AvRelationReducer, AvScalarFilterOperator, AvScalarMutationDirective, AvWriteScope } from "./capability.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";
@@ -53,6 +53,19 @@ export type AvRelationMutationCapability = readonly AvRelationMutationDirective[
 export type AvScalarFieldCapabilities = {
     readonly select?: boolean;
     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 AvScalarMutationDirective[];
@@ -133,6 +146,22 @@ export type AvRelationField<C extends AvContract> = {
     readonly cardinality: "one" | "many";
     readonly nullable: boolean;
     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[]];
 };
 /** One field of a Resource: a scalar or a relation. */
 export type AvField<C extends AvContract> = AvScalarField<C> | AvRelationField<C>;

package/dist/framework/contract-view.d.ts

@@ -111,9 +111,9 @@ type ComputedOnCreateKey<FieldsBlock> = [FieldsBlock] extends [never] ? never :
  * none is satisfied and leaves `oneOf`. A member left empty is absent, as the
  * compiler leaves it (`projectCreateRequirements`).
  */
-type RequirementsLessComputed<Requirements, Computed> = [Computed] extends [
-    never
-] ? Requirements : {
+export type RequirementsLessComputed<Requirements, Computed> = [
+    Computed
+] extends [never] ? Requirements : {
     readonly [P in keyof Requirements as P extends "required" | "oneOf" ? LessComputed<P, Requirements[P], Computed> extends readonly [] ? never : P : P]: P extends "required" | "oneOf" ? LessComputed<P, Requirements[P], Computed> : Requirements[P];
 };
 /** One member of a statement less `Computed`: its names, or its groups. */
@@ -207,7 +207,7 @@ type OmittedMember<Member, Entry> = Entry extends readonly unknown[] ? WithToken
 /** One capability member under a Pick object entry: a token list keeps only those tokens. */
 type PickedMember<Member, Entry> = Entry extends readonly unknown[] ? WithTokens<Member, Extract<MemberTokens<Member>, Listed<Entry>>> : Member;
 /** The capability members no exemption names and a Pick still keeps. */
-type AdapterLimit = "nestedWriteFilter";
+type AdapterLimit = "nestedWriteFilter" | "filterModes" | "pathFilterModes";
 /** A field's capabilities under its exemption, a list of names or an object. */
 type ExemptedCapabilities<Caps, Entry, Style> = Style extends "omit" ? Entry extends readonly unknown[] ? {
     readonly [P in keyof Caps as P extends Listed<Entry> ? never : P]: Caps[P];

package/dist/framework/framework-construction.error.d.ts

@@ -3,8 +3,16 @@ import type { AvContractCompilerDiagnostic } from "../compiler/contract-compiler
 import type { AvConfigDiagnostic } from "../config/config-diagnostic.js";
 /** The construction step that failed. */
 export type AvConstructionStage = "configuration" | "discovery" | "contract-compilation";
-/** One problem reported by {@link AvConstructionError}. */
-export type AvConstructionDiagnostic = AvConfigDiagnostic | AvAdapterDiscoveryDiagnostic | AvContractCompilerDiagnostic;
+/** One problem found while constructing, before its documentation link is added. */
+type ConstructionProblem = AvConfigDiagnostic | AvAdapterDiscoveryDiagnostic | AvContractCompilerDiagnostic;
+/**
+ * One problem reported by {@link AvConstructionError}: its `code`, `path` and
+ * `message`, and `docs`, the URL of the code's entry on the error-codes page
+ * (the same as `AvErrorCatalog[code].docs`).
+ */
+export type AvConstructionDiagnostic = ConstructionProblem & {
+    readonly docs: string;
+};
 /**
  * Thrown by {@link createFramework} when construction fails: `stage` says
  * where, and `diagnostics` lists every problem found there.
@@ -12,5 +20,6 @@ export type AvConstructionDiagnostic = AvConfigDiagnostic | AvAdapterDiscoveryDi
 export declare class AvConstructionError extends Error {
     readonly stage: AvConstructionStage;
     readonly diagnostics: readonly AvConstructionDiagnostic[];
-    constructor(stage: AvConstructionStage, diagnostics: readonly AvConstructionDiagnostic[]);
+    constructor(stage: AvConstructionStage, diagnostics: readonly ConstructionProblem[]);
 }
+export {};

package/dist/framework/framework-construction.error.js

@@ -1,3 +1,4 @@
+import { errorDocsUrl } from "../runtime/error.catalog.js";
 const FRAMEWORK_CONSTRUCTION_MESSAGES = {
     configuration: "Aventara framework configuration validation failed",
     discovery: "Aventara adapter discovery validation failed",
@@ -10,6 +11,9 @@ export class AvConstructionError extends Error {
         super(FRAMEWORK_CONSTRUCTION_MESSAGES[stage]);
         this.name = "AvConstructionError";
         this.stage = stage;
-        this.diagnostics = [...diagnostics];
+        this.diagnostics = diagnostics.map((diagnostic) => ({
+            ...diagnostic,
+            docs: errorDocsUrl(diagnostic.code),
+        }));
     }
 }

package/dist/framework/framework.factory.d.ts

@@ -10,4 +10,4 @@ import type { AvFramework } from "./framework.js";
  *
  * @throws {@link AvConstructionError} when any of those steps fails.
  */
-export declare function createFramework<M extends AvAdapterModel, const Cfg = AvConfigAny>(config: Cfg & AvConfig<M, Cfg> & AvConfigExact<M, Cfg>): Promise<AvFramework<M, ErasedConfig<Cfg>>>;
+export declare function createFramework<M extends AvAdapterModel, const Cfg = AvConfigAny>(config: Cfg & AvConfigExact<M, Cfg> & AvConfig<M, Cfg>): Promise<AvFramework<M, ErasedConfig<Cfg>>>;

package/dist/framework/framework.factory.js

@@ -1,4 +1,5 @@
 import { compileContracts } from "../compiler/contract.compiler.js";
+import { computedFieldsOf, warnOnStaleComputedFields, } from "../config/computed-fields.js";
 import { resolveFrameworkConfig } from "../config/config.resolver.js";
 import { validateFrameworkConfig } from "../config/config.validator.js";
 import { validateForcedOperations } from "../config/forced-operation.validator.js";
@@ -34,6 +35,10 @@ export async function createFramework(config) {
         ]);
     }
     const resolvedConfig = resolveFrameworkConfig(config);
+    warnOnStaleComputedFields(config.adapter.computedFields, computedFieldsOf({
+        trees: resolvedConfig.trees,
+        agentExtends: resolvedConfig.agent.parent,
+    }));
     const compilation = await compileContracts(model, resolvedConfig);
     if (!compilation.ok) {
         throw new AvConstructionError("contract-compilation", compilation.diagnostics);
@@ -89,8 +94,10 @@ export async function createFramework(config) {
     };
     recordDiagnosticsSink(framework, resolvedConfig.diagnostics);
     recordOwnedExecution(framework, {
-        execute: (request) => executeTotally(execute, request, resolvedConfig.diagnostics, "owned"),
-        executeTransaction: (request) => executeTransactionTotally(executeTransaction, request, resolvedConfig.diagnostics, undefined, { source: "owned" }),
+        execute: (request, refused) => executeTotally(execute, request, resolvedConfig.diagnostics, refused === undefined ? "owned" : { refused }),
+        executeTransaction: (request, refused) => executeTransactionTotally(executeTransaction, request, resolvedConfig.diagnostics, undefined, refused === undefined
+            ? { source: "owned" }
+            : { source: "owned", refused }),
     });
     return framework;
 }

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { AvAdapterDiscoveryDiagnostic, AvAdapterDiscoveryDiagnosticCode, }
 export type { AvAdapterModel } from "./adapters/adapter-model.js";
 export type { AvContracts } from "./compiler/contract.compiler.js";
 export type { AvContractCompilerDiagnostic, AvContractCompilerDiagnosticCode, } from "./compiler/contract-compiler-diagnostic.js";
+export type { AvConfigComputedFields } from "./config/computed-fields.js";
 export type { AvMcpEndpoint } from "./config/config.resolver.js";
 export type { AvConfigDiagnostic, AvConfigDiagnosticCode, } from "./config/config-diagnostic.js";
 export type { AvConfigLayerName, AvRequestOrigin, } from "./config/config-layer.js";
@@ -38,6 +39,7 @@ export type { AvOperationResultFor } from "./operations/operation-result.js";
 export type { AvValidationCode, AvValidationIssue, } from "./operations/validation-code.js";
 export { AvDecimal } from "./runtime/decimal.js";
 export type { AvDiagnostic, AvDiagnosticsSink, AvMcpDiagnostic, AvOperationDiagnostic, AvTransactionDiagnostic, } from "./runtime/diagnostics-reporter.js";
+export { AvErrorCatalog, type AvErrorCatalogCode, type AvErrorCatalogEntry, type AvErrorKind, } from "./runtime/error.catalog.js";
 export type { AvExecutionOptions } from "./runtime/execution-options.js";
 export type { AvComputeContext, AvComputeCreate, AvComputeRead, AvComputeUpdate, } from "./runtime/field-compute.js";
 export { AvAuthError, AvConflictError, AvContractMismatchError, AvError, AvInternalError, AvNotFoundError, AvProtocolError, AvValidationError, } from "./runtime/framework-error.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export { defineResource, } from "./config/define-resource.js";
 export { createFramework } from "./framework/framework.factory.js";
 export { AvConstructionError } from "./framework/framework-construction.error.js";
 export { AvDecimal } from "./runtime/decimal.js";
+export { AvErrorCatalog, } from "./runtime/error.catalog.js";
 export { AvAuthError, AvConflictError, AvContractMismatchError, AvError, AvInternalError, AvNotFoundError, AvProtocolError, AvValidationError, } from "./runtime/framework-error.js";
 export { AvTransactionIntegrityError } from "./transactions/transaction-integrity-error.js";
 export { AvTransactionSlotPathError } from "./transactions/transaction-slot-path-error.js";

package/dist/internal.d.ts

@@ -28,6 +28,8 @@ export { isOperationVariantAvailable, projectionScopeOf, writeScopeOf, } from ".
 export { BUILT_IN_SCALARS } from "./contracts/scalar.js";
 export { TRANSACTION_CAPABILITIES } from "./contracts/transaction-capability.js";
 export type { AvContractApplicationView } from "./framework/contract-view.js";
+export type { AvDatabaseRefusal } from "./operations/database-refusal.js";
+export { DATABASE_REFUSALS } from "./operations/database-refusal.js";
 export type { SemanticOperationArguments } from "./operations/operation-validator.js";
 export { VALIDATION_CODES } from "./operations/validation-code.js";
 export { mcpFailureReporterOf } from "./runtime/diagnostics-reporter.js";