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

package/dist/config/field-compute.resolver.js

@@ -1,3 +1,4 @@
+import { isRecord } from "../runtime/record.guard.js";
 function chainWrite(root, overlay) {
     if (root === undefined || overlay === undefined) {
         return root ?? overlay;
@@ -46,9 +47,6 @@ function chainRead(root, overlay) {
         ? compute
         : { dependsOn, compute };
 }
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 export function computeOfLayer(resources) {
     const result = {};
     if (!isRecord(resources)) {
@@ -113,3 +111,11 @@ export function chainCompute(root, overlay) {
     }
     return result;
 }
+export function createComputedFields(compute, resource) {
+    const fields = Object.hasOwn(compute, resource)
+        ? compute[resource]
+        : undefined;
+    return new Set(Object.entries(fields ?? {})
+        .filter(([, phases]) => phases.create !== undefined)
+        .map(([field]) => field));
+}

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

@@ -2,19 +2,28 @@ import type { AvAdapter } from "../adapters/adapter.interface.js";
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvContractLimits } from "../contracts/contract-limits.js";
 import type { AvTransactionCapability } from "../contracts/transaction-capability.js";
+import type { AvAccessProvider } from "../policy/access-provider.interface.js";
+import type { AvPolicyEngine } from "../policy/policy-engine.js";
+import type { AvPrebuiltContracts } from "../prebuilt/prebuilt-contracts.js";
 import type { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
 import type { AvMisuseSink } from "../runtime/misuse-reporter.js";
+import type { AvState } from "../runtime/request-state.js";
 import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvConfigLayerName, AvRequestOrigin } 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
  * {@link DEFAULT_CONTRACT_LIMITS}.
  */
 export type AvConfigLimits = Partial<AvContractLimits>;
-/** rc.0's layer keys, each refused with its rc.1 location. */
-type MovedLayerKeys = {
+/**
+ * The six keys every layer holds: the root, `application`, `client` and
+ * `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", Layer extends AvConfigLayerName = LayerOfKind<Kind>> = {
     /** Moved: `exposed` + `exemptions`. */
     readonly restrictions?: never;
     /** Moved: `resources.<R>.fields.<f>.pipelines.compute`. */
@@ -23,13 +32,6 @@ type MovedLayerKeys = {
     readonly fields?: never;
     /** Moved: `transactionsStyle`. */
     readonly transactions?: never;
-};
-/**
- * The six keys every layer holds: the root, `application`, `client` and
- * `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 & {
     /**
      * 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 +45,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`.
@@ -70,11 +72,45 @@ export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAn
      */
     readonly mcp?: AvConfigMcp;
     readonly adapter: AvAdapter<M>;
+    /**
+     * Contracts compiled ahead of time (the generated `aventaraContracts`), for a
+     * fast cold start on serverless and edge platforms. Used only when they were
+     * compiled from this configuration and the adapter's model by this core;
+     * otherwise the Contracts are compiled at startup, as without it, and a
+     * `AVENTARA_PREBUILT_STALE` warning says why.
+     */
+    readonly prebuilt?: AvPrebuiltContracts;
+    /**
+     * The policy engine every client and agent request is checked against, and
+     * how a request's principal is derived from its `ctx.$state`. Application
+     * calls bypass it unless they name a principal (`{ as }`); calls a stage
+     * makes through `ctx` always do.
+     */
+    readonly policy?: {
+        readonly engine: AvPolicyEngine;
+        /**
+         * The request's principal, from its `ctx.$state` and its layer; `null` for
+         * an anonymous caller. It may answer with a promise (rc.5), which is
+         * awaited; a throw or a rejection answers `A3000`.
+         */
+        readonly principal: (facts: {
+            readonly $state: AvState;
+            readonly $origin: AvRequestOrigin;
+        }) => unknown;
+    };
+    /**
+     * The access provider (Aventara Access, or one written by hand): its
+     * `policy` engine checks every client and agent request, with
+     * `ctx.$state.me` as the principal, and the host seeds each request's
+     * `ctx.$state` with its `state`. Not together with `policy`, nor with a
+     * host's own `state` option.
+     */
+    readonly access?: AvAccessProvider;
     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
@@ -95,7 +131,9 @@ export type AvConfigMcp = string | {
     readonly authorization?: {
         /**
          * The authorization servers (https URLs) a caller obtains its token
-         * from, advertised in the endpoint's protected-resource metadata.
+         * from, advertised in the endpoint's protected-resource metadata. A
+         * server on this machine may be http: `http://127.0.0.1` or
+         * `http://[::1]`, with any port and path (not `localhost`).
          */
         readonly servers: readonly string[];
         /**
@@ -109,7 +147,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,29 +16,29 @@ 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;
 };
-/** The variants a family's stages are told: its own, and `"one"` for a nested target. */
-type FamilyStageVariant<F extends AvOperationFamily, V extends string> = F extends "create" | "update" | "delete" ? V | "one" : V;
 /**
  * One operation family's level: stages and `forceTransaction` for every variant
  * of it, and each variant's own level by name.
  */
 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, F extends "create" | "update" | "delete" ? Extract<keyof NonNullable<Variants>, string> | "one" : 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 +101,27 @@ 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>;
+    /**
+     * `true`: another service owns this Resource's table and migrates it. It is
+     * read and joined, never written: it has no write operation, no nested write
+     * reaches its rows, and the client and agent Contracts leave it out, with
+     * every relation to it. Root only.
+     */
+    readonly managedElsewhere?: Kind extends "root" ? boolean : never;
 };
 /** 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,18 @@ 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 read's cache stage, `cache({ for: "user", maxAge: 60 })`: the reads this
+     * level covers (its `find` operations) are also served as a GET a browser or
+     * a CDN may keep. The most specific level's stage wins. Always write `for`,
+     * even for the default `"user"`: the audience is the promise this read
+     * makes, and it should be visible in the code.
+     */
+    readonly cache?: {
+        readonly for?: "user" | "anonymous" | "everyone";
+        readonly maxAge: number;
+    };
 };
 /**
  * A Resource's transaction stages: they run once per transaction with a
@@ -51,6 +62,11 @@ export type ResolvedPipelineConfig = {
     };
     readonly interceptors: readonly AvInterceptor[];
     readonly filters: readonly AvFilter[];
+    /** The level's read cache stage, as authored (validated); rc.11. */
+    readonly cache?: {
+        readonly for?: "user" | "anonymous" | "everyone";
+        readonly maxAge: number;
+    };
 };
 /** One layer's registrations on one Resource's transactions. */
 export type ResolvedTransactionPipelineConfig = {

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

@@ -2,12 +2,12 @@ import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { AvFieldGuard, AvFieldPipe } from "../runtime/pipeline.js";
 import type { ResolvedPipelineConfig, ResolvedTransactionPipelineConfig } from "./pipeline-config.js";
 /** One variant's levels and whether a layer forces it. */
-export type ResolvedVariantPipelines = {
+type ResolvedVariantPipelines = {
     readonly pipelines: readonly ResolvedPipelineConfig[];
     readonly forceTransaction: boolean;
 };
 /** One family's levels, its variants' and whether a layer forces the family. */
-export type ResolvedFamilyPipelines = ResolvedVariantPipelines & {
+type ResolvedFamilyPipelines = ResolvedVariantPipelines & {
     readonly variants: Readonly<Record<string, ResolvedVariantPipelines>>;
 };
 /** One field's stages for one origin: the root's, then the overlay's. */

package/dist/config/pipeline-tree.resolver.js

@@ -1,6 +1,4 @@
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
+import { isRecord } from "../runtime/record.guard.js";
 function own(record, key) {
     return record !== undefined && Object.hasOwn(record, key)
         ? record[key]
@@ -23,6 +21,7 @@ function levelOf(value) {
         },
         interceptors: list(pipeline.interceptors),
         filters: list(pipeline.filters),
+        ...(isRecord(pipeline.cache) ? { cache: pipeline.cache } : {}),
     };
 }
 function transactionLevelOf(value) {

package/dist/contracts/access-route.rules.d.ts

@@ -0,0 +1,10 @@
+/**
+ * An absolute `http:`/`https:` URL, or a root-relative path other than `"/"`:
+ * never `//host`, a backslash, a control character, a space or a dot segment.
+ */
+export declare function isAccessUrl(value: unknown): value is string;
+/**
+ * A verb's path under the section's `url`: starting with one `/`, never a
+ * backslash, a control character, a space or a dot segment.
+ */
+export declare function isAccessPath(value: unknown): value is string;

package/dist/contracts/access-route.rules.js

@@ -0,0 +1,45 @@
+function hasControlOrSpace(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x20 || code === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+}
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+function hasDotSegment(path) {
+    const end = path.search(/[?#]/);
+    return (end === -1 ? path : path.slice(0, end))
+        .split("/")
+        .some((segment) => DOT_SEGMENT.test(segment));
+}
+export function isAccessUrl(value) {
+    if (typeof value !== "string" ||
+        value.includes("\\") ||
+        hasControlOrSpace(value)) {
+        return false;
+    }
+    if (value.startsWith("/")) {
+        return value !== "/" && !value.startsWith("//") && !hasDotSegment(value);
+    }
+    const authority = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*/i.exec(value)?.[0];
+    if (authority === undefined || hasDotSegment(value.slice(authority.length))) {
+        return false;
+    }
+    try {
+        const { protocol } = new URL(value);
+        return protocol === "https:" || protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}
+export function isAccessPath(value) {
+    return (typeof value === "string" &&
+        value.startsWith("/") &&
+        !value.startsWith("//") &&
+        !value.includes("\\") &&
+        !hasControlOrSpace(value) &&
+        !hasDotSegment(value));
+}

package/dist/contracts/canonical-json.writer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The canonical JSON text (RFC 8785) of a JSON value: an object's keys in
+ * UTF-16 code-unit order, a member holding `undefined` left out, nothing but
+ * `null`, booleans, finite numbers, strings, arrays and plain objects. Throws a
+ * `TypeError` for anything else, a lone surrogate in a string or key included.
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/contracts/canonical-json.writer.js

@@ -0,0 +1,55 @@
+export function canonicalJson(value) {
+    const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+    const text = (string) => {
+        if (LONE_SURROGATE.test(string)) {
+            throw new TypeError("Canonical JSON cannot write a lone surrogate.");
+        }
+        return JSON.stringify(string);
+    };
+    const write = (current, ancestors) => {
+        if (current === null) {
+            return "null";
+        }
+        switch (typeof current) {
+            case "boolean":
+                return current ? "true" : "false";
+            case "number":
+                if (!Number.isFinite(current)) {
+                    throw new TypeError("Canonical JSON cannot write a non-finite number.");
+                }
+                return JSON.stringify(current);
+            case "string":
+                return text(current);
+            case "object":
+                break;
+            default:
+                throw new TypeError(`Canonical JSON cannot write a ${typeof current}.`);
+        }
+        const container = current;
+        if (ancestors.includes(container)) {
+            throw new TypeError("Canonical JSON cannot write a cycle.");
+        }
+        const path = [...ancestors, container];
+        if (Array.isArray(container)) {
+            const items = [];
+            for (let index = 0; index < container.length; index += 1) {
+                items.push(write(container[index] ?? null, path));
+            }
+            return `[${items.join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(container);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Canonical JSON writes plain objects only.");
+        }
+        const record = container;
+        const members = [];
+        for (const key of Object.keys(record).sort((left, right) => left < right ? -1 : left > right ? 1 : 0)) {
+            const member = record[key];
+            if (member !== undefined) {
+                members.push(`${text(key)}:${write(member, path)}`);
+            }
+        }
+        return `{${members.join(",")}}`;
+    };
+    return write(value, []);
+}

package/dist/contracts/capability.d.ts

@@ -1,11 +1,36 @@
 /** 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. */
 export type AvRelationFilterCapability = "nested" | "match" | "null" | "some" | "every" | "none";
 /** What a write can do to a relation: `$create`, `$connect` and the rest. */
 export type AvRelationMutationDirective = "$create" | "$connect" | "$connectOrCreate" | "$disconnect" | "$set" | "$update" | "$delete" | "$upsert";
+/** The to-one directives that change which row the relation links. */
+export declare const TO_ONE_RELINK_DIRECTIVES: readonly ["$connect", "$connectOrCreate", "$create", "$set", "$disconnect"];
+/** The to-one directives that write the row the relation links. */
+export declare const TO_ONE_REWRITE_DIRECTIVES: readonly ["$update", "$upsert"];
+/** @see TO_ONE_RELINK_DIRECTIVES */
+export type ToOneRelinkDirective = (typeof TO_ONE_RELINK_DIRECTIVES)[number];
+/** @see TO_ONE_REWRITE_DIRECTIVES */
+export type ToOneRewriteDirective = (typeof TO_ONE_REWRITE_DIRECTIVES)[number];
+/**
+ * A to-one operand's directives that both relink the relation and write the
+ * linked row, or `undefined` when it does not pair them.
+ */
+export declare function toOneRelinkWithRewrite(operand: Readonly<Record<string, unknown>>): {
+    readonly rewrite: readonly ToOneRewriteDirective[];
+    readonly relink: readonly ToOneRelinkDirective[];
+} | undefined;
 /** How a list of related rows can be paginated. */
 export type AvPaginationCapability = "limit" | "offset" | "cursor";
 /** What a projection can compute over a to-many relation. */
@@ -24,6 +49,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,22 @@
+export const FILTER_MODES = ["default", "sensitive", "insensitive"];
+export const TO_ONE_RELINK_DIRECTIVES = [
+    "$connect",
+    "$connectOrCreate",
+    "$create",
+    "$set",
+    "$disconnect",
+];
+export const TO_ONE_REWRITE_DIRECTIVES = [
+    "$update",
+    "$upsert",
+];
+export function toOneRelinkWithRewrite(operand) {
+    const rewrite = TO_ONE_REWRITE_DIRECTIVES.filter((key) => Object.hasOwn(operand, key));
+    const relink = TO_ONE_RELINK_DIRECTIVES.filter((key) => Object.hasOwn(operand, key));
+    return rewrite.length === 0 || relink.length === 0
+        ? undefined
+        : { rewrite, relink };
+}
 export const PROJECTION_SCOPES = [
     "record",
     "bulkWrite",
@@ -5,4 +24,5 @@ export const PROJECTION_SCOPES = [
 export const WRITE_SCOPES = [
     "nested",
     "bulkWrite",
+    "loopback",
 ];