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

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

@@ -103,9 +103,11 @@ type TokenOf<Member> = Member extends {
 } ? {
     [K in keyof Member]: K extends "scopes" ? never : Member[K] extends readonly (infer Token)[] ? Token : never;
 }[keyof Member] : Member extends readonly (infer Token)[] ? Token : never;
+/** The capability members an exemption never names. */
+type AdapterStatedMember = "nestedWriteFilter" | "filterModes" | "pathFilterModes";
 /** A field's exemption against its capabilities: their names, and each one's tokens. */
-type CapabilityExemptionSchema<Caps> = ListOf<Exclude<keyof Caps, "nestedWriteFilter">> & {
-    readonly [K in Exclude<keyof Caps, "nestedWriteFilter">]-?: ListOf<TokenOf<NonNullable<Caps[K]>>>;
+type CapabilityExemptionSchema<Caps> = ListOf<Exclude<keyof Caps, AdapterStatedMember>> & {
+    readonly [K in Exclude<keyof Caps, AdapterStatedMember>]-?: ListOf<TokenOf<NonNullable<Caps[K]>>>;
 };
 type FieldExemptionSchema<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, F> = F extends AvAdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
     readonly kind: "relation";
@@ -131,33 +133,58 @@ type ExemptionsSchema<M extends AvAdapterModel, Cfg> = {
         };
     };
 };
-/** A Pick overlay's exemptions, against the root's view. */
-type PickExemptionsSchema<Resources> = {
+declare const refusal: unique symbol;
+/** What a level refuses an unknown key for: `layer` cannot expose it, `parent` hid it, under `at`. */
+type Refusal<Layer extends string, Parent extends string, At extends string> = {
+    readonly [refusal]: {
+        readonly layer: Layer;
+        readonly parent: Parent;
+        readonly at: At;
+    };
+};
+/** The sentence a refused key `K` holding `Value` is typed as; `never` for an entry written `false`. */
+type RefusalOf<Info, K, Value> = [Value] extends [false] ? never : Info extends {
+    readonly layer: infer Layer extends string;
+    readonly parent: infer Parent extends string;
+    readonly at: infer At extends string;
+} ? Value extends readonly unknown[] ? {
+    readonly [S in `Error: ${Layer} cannot expose '${At}${K & string}': hidden by ${Parent}`]: true;
+} : readonly [
+    `Error: ${Layer} cannot expose '${At}${K & string}': hidden by ${Parent}`
+] : never;
+/** A Pick layer's operations exemption, a family or variant its parent hid refused by name. */
+type PickOperationsSchema<Ops, Layer extends string, Parent extends string, R extends string> = ListOf<keyof Ops> & {
+    readonly [F in keyof Ops]-?: ListOf<keyof NonNullable<Ops[F]>> & {
+        readonly [V in keyof NonNullable<Ops[F]>]: Leaf;
+    } & Refusal<Layer, Parent, `${R}.${F & string}.`>;
+} & Refusal<Layer, Parent, `${R}.`>;
+/** The fields of one Resource of a view. */
+type ViewFields<Resource> = Resource extends {
+    readonly fields: infer Fields;
+} ? Fields : never;
+/** A Pick layer's exemptions, against its parent's view. */
+type PickExemptionsSchema<Resources, Layer extends string, Parent extends string> = {
     readonly resources: {
         readonly [R in keyof Resources]: {
-            readonly operations: OperationsExemptionSchema<Resources[R] extends {
+            readonly operations: PickOperationsSchema<Resources[R] extends {
                 readonly operations: infer Ops;
-            } ? Ops : never>;
+            } ? Ops : never, Layer, Parent, R & string>;
             readonly fields: {
-                readonly [F in keyof (Resources[R] extends {
-                    readonly fields: infer Fields;
-                } ? Fields : never)]: CapabilityExemptionSchema<(Resources[R] extends {
-                    readonly fields: infer Fields;
-                } ? Fields : never)[F] extends {
+                readonly [F in keyof ViewFields<Resources[R]>]: CapabilityExemptionSchema<ViewFields<Resources[R]>[F] extends {
                     readonly capabilities: infer Caps;
-                } ? Caps : never>;
-            };
+                } ? Caps : never> & Refusal<Layer, Parent, `${R & string}.${F & string}.`>;
+            } & Refusal<Layer, Parent, `${R & string}.`>;
         };
-    };
+    } & Refusal<Layer, Parent, "">;
 };
 /** A layer's own configuration: `application`, `client` or `agent`. */
 type OverlayOf<Cfg, Layer extends "application" | "client" | "agent"> = (Cfg & {
     readonly [L in Layer]?: unknown;
 })[Layer];
 /** An overlay's exemptions schema, by the overlay's own `exposed`. */
-type OverlayExemptionsSchema<M extends AvAdapterModel, Cfg, Overlay> = Overlay extends {
+type OverlayExemptionsSchema<M extends AvAdapterModel, Cfg, Overlay, Layer extends "application" | "client"> = Overlay extends {
     readonly exposed: false;
-} ? PickExemptionsSchema<RootViewResources<M, Cfg>> : ExemptionsSchema<M, Cfg>;
+} ? PickExemptionsSchema<RootViewResources<M, Cfg>, Layer, "root"> : ExemptionsSchema<M, Cfg>;
 type LayerKeysSchema = {
     readonly exposed: Leaf;
     readonly transactionsStyle: Leaf;
@@ -183,7 +210,7 @@ type OverlaySchema<M extends AvAdapterModel, Cfg, Layer extends "application" |
     readonly resources: {
         readonly [R in AvConfigResourceKey<M>]: ResourceSchema<M, R, FieldsSchema<M, R, "overlay", AvEffectiveFieldKey<M, Cfg, R>>>;
     };
-    readonly exemptions: OverlayExemptionsSchema<M, Cfg, OverlayOf<Cfg, Layer>>;
+    readonly exemptions: OverlayExemptionsSchema<M, Cfg, OverlayOf<Cfg, Layer>, Layer>;
 };
 type McpSchema = {
     readonly path: Leaf;
@@ -197,7 +224,7 @@ type AgentParentOf<Cfg> = OverlayOf<Cfg, "agent"> extends {
     readonly extends: infer Parent;
 } ? Parent : "client";
 /** A Pick agent's exemptions, against the view of the layer it extends. */
-type AgentPickExemptionsSchema<M extends AvAdapterModel, Cfg, Parent> = Parent extends "application" | "client" ? [Parent] extends ["application"] | ["client"] ? PickExemptionsSchema<OverlayViewResources<M, Cfg, Parent>> : PickExemptionsSchema<RootViewResources<M, Cfg>> : PickExemptionsSchema<RootViewResources<M, Cfg>>;
+type AgentPickExemptionsSchema<M extends AvAdapterModel, Cfg, Parent> = Parent extends "application" | "client" ? [Parent] extends ["application"] | ["client"] ? PickExemptionsSchema<OverlayViewResources<M, Cfg, Parent>, "agent", Parent> : PickExemptionsSchema<RootViewResources<M, Cfg>, "agent", "root"> : PickExemptionsSchema<RootViewResources<M, Cfg>, "agent", "root">;
 type AgentSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
     readonly extends: Leaf;
     readonly resources: {
@@ -219,9 +246,12 @@ type RootSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
     readonly client: OverlaySchema<M, Cfg, "client">;
     readonly agent: AgentSchema<M, Cfg>;
 };
-/** `V` with every key schema `S` lacks mapped to `never`; every leaf `unknown`. */
+/**
+ * `V` with every key schema `S` lacks mapped to `never`, or to the sentence a
+ * refusing level states; every leaf `unknown`.
+ */
 type Exact<S, V> = [S] extends [Leaf] ? unknown : V extends readonly unknown[] ? S extends ListOf<infer Names> ? readonly Names[] : unknown : V extends (...args: any) => any ? unknown : V extends object ? string extends keyof V ? unknown : {
-    readonly [K in keyof V]: K extends keyof S ? Exact<S[K], V[K]> : typeof otherKeys extends keyof S ? Exact<S[typeof otherKeys], V[K]> : never;
+    readonly [K in keyof V]: K extends keyof S ? Exact<S[K], V[K]> : typeof otherKeys extends keyof S ? Exact<S[typeof otherKeys], V[K]> : typeof refusal extends keyof S ? RefusalOf<S[typeof refusal], K, V[K]> : never;
 } : unknown;
 /**
  * The authored configuration `Cfg`, checked key by key: a key no level of the

package/dist/config/field-compute.resolver.d.ts

@@ -17,3 +17,5 @@ export declare function computeOfLayer(resources: unknown): ResolvedComputeConfi
  * chained phase by phase. Nothing is disabled from below.
  */
 export declare function chainCompute(root: ResolvedComputeConfig, overlay: ResolvedComputeConfig): ResolvedComputeConfig;
+/** The fields of `resource` with a `compute.create` stage in `compute`. */
+export declare function createComputedFields(compute: ResolvedComputeConfig, resource: string): ReadonlySet<string>;

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

@@ -113,3 +113,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

@@ -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",
 ];