@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

package/dist/config/forced-operation.validator.js

@@ -0,0 +1,66 @@
+import { isOperationVariantAvailable } from "../contracts/resource-operations.js";
+import { forcedOperationsOf } from "./pipeline-tree.resolver.js";
+function reachable(contract, resource, family, variant) {
+    if (!Object.hasOwn(contract.resources, resource)) {
+        return false;
+    }
+    const operations = contract.resources[resource]?.operations;
+    const variants = operations !== undefined && Object.hasOwn(operations, family)
+        ? operations[family]
+        : undefined;
+    if (variants === undefined) {
+        return false;
+    }
+    return variant === undefined
+        ? Object.values(variants).some((availability) => isOperationVariantAvailable(availability))
+        : Object.hasOwn(variants, variant) &&
+            isOperationVariantAvailable(variants[variant]);
+}
+function layerRecord(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : undefined;
+}
+function layersOf(config, origin) {
+    const layers = [];
+    const push = (name) => {
+        const record = layerRecord(config[name]);
+        if (record !== undefined) {
+            layers.push({ name, record });
+        }
+    };
+    if (origin === "agent") {
+        const parent = layerRecord(config.agent)?.extends ?? "client";
+        if (parent === "application" || parent === "client") {
+            push(parent);
+        }
+    }
+    push(origin);
+    return layers;
+}
+export function validateForcedOperations(config, contracts) {
+    const refused = new Map();
+    const origins = config.agent !== undefined || config.mcp !== undefined
+        ? ["application", "client", "agent"]
+        : ["application", "client"];
+    for (const origin of origins) {
+        const contract = contracts[origin];
+        if (contract.transactions !== "none") {
+            continue;
+        }
+        const forced = [
+            ...forcedOperationsOf(config, ""),
+            ...layersOf(config, origin).flatMap((layer) => forcedOperationsOf(layer.record, `${layer.name}.`)),
+        ];
+        for (const { path, resource, family, variant } of forced) {
+            if (reachable(contract, resource, family, variant)) {
+                refused.set(path, [...(refused.get(path) ?? []), origin]);
+            }
+        }
+    }
+    return [...refused].map(([path, layers]) => ({
+        code: "CONFIG_INVALID_VALUE",
+        path,
+        message: `${path}: forceTransaction runs a plain call as a one-step transaction, and the effective transactionsStyle of the ${layers.join(" and ")} ${layers.length === 1 ? "layer is" : "layers are"} "none"; set transactionsStyle: "interactive" there (the adapter must offer interactive transactions) or remove forceTransaction`,
+    }));
+}

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

@@ -1,49 +1,123 @@
-import type { Adapter } from "../adapters/adapter.interface.js";
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { ContractLimits } from "../contracts/contract-limits.js";
-import type { TransactionCapability } from "../contracts/transaction-capability.js";
-import type { FrameworkDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
-import type { AnyFrameworkConfig } from "./any-framework-config.js";
-import type { FrameworkBehaviorsConfig } from "./framework-behaviors-config.js";
-import type { FrameworkFieldsConfig } from "./framework-fields-config.js";
-import type { FrameworkRestrictionsConfig } from "./framework-restrictions-config.js";
-import type { PipelineConfig } from "./pipeline-config.js";
+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 { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
+import type { AvMisuseSink } from "../runtime/misuse-reporter.js";
+import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvConfigExemptions } from "./framework-exemptions-config.js";
+import type { AvConfigLayerKind, AvConfigResources } 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 FrameworkLimitsConfig = Partial<ContractLimits>;
+export type AvConfigLimits = Partial<AvContractLimits>;
+/** rc.0's layer keys, each refused with its rc.1 location. */
+type MovedLayerKeys = {
+    /** Moved: `exposed` + `exemptions`. */
+    readonly restrictions?: never;
+    /** Moved: `resources.<R>.fields.<f>.pipelines.compute`. */
+    readonly behaviors?: never;
+    /** Moved: `resources.<R>.fields.<f>.definition`. */
+    readonly fields?: never;
+    /** Moved: `transactionsStyle`. */
+    readonly transactions?: never;
+};
 /**
- * Settings available at the root and in the `application` and `client`
- * overlays. A setting in an overlay replaces the root's for that origin;
- * pipelines are added to the root's instead.
+ * 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 FrameworkScopeConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
-    /** Fields to add to Resources, or details to set on discovered fields. */
-    readonly fields?: FrameworkFieldsConfig<M>;
-    /** Computed values and read behaviors, per Resource and field. */
-    readonly behaviors?: FrameworkBehaviorsConfig<M, Cfg>;
-    /** What to hide or narrow: Resources, fields, capabilities and operations. */
-    readonly restrictions?: FrameworkRestrictionsConfig<M, Cfg>;
-    /** Request limits; see {@link FrameworkLimitsConfig}. */
-    readonly limits?: FrameworkLimitsConfig;
-    /** Guards, pipes, hooks, interceptors and filters run around each operation. */
-    readonly pipelines?: PipelineConfig<M>;
+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
+     * the adapter's model, an overlay the root's view.
+     */
+    readonly exposed?: boolean;
     /** `"none"` turns transactions off; `"interactive"` needs adapter support. */
-    readonly transactions?: TransactionCapability;
+    readonly transactionsStyle?: AvTransactionCapability;
+    /** Request limits; see {@link AvConfigLimits}. */
+    readonly limits?: AvConfigLimits;
+    /** 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>;
+    /**
+     * The entries that are the opposite of `exposed`. An overlay that sets them
+     * states its own `exposed`.
+     */
+    readonly exemptions?: AvConfigExemptions<M, Cfg>;
 };
 /**
  * The configuration passed to `createFramework`: the adapter, the mount path,
- * root settings, and optional `application` and `client` overlays.
+ * the root layer, optional `application` and `client` overlays, the optional
+ * `agent` layer, and `mcp`.
+ */
+export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = AvConfigLayer<M, Cfg, "root"> & {
+    /**
+     * Where the protocol's HTTP routes are mounted: `/api` serves
+     * `/api/_resources/…`, `/api/_contract` and `/api/_transactions`.
+     */
+    readonly api: string;
+    /** Moved in rc.1: the mount path is `api`. */
+    readonly entrypoint?: never;
+    /**
+     * Turns MCP on: the path the MCP endpoint is mounted at, or the path with the
+     * OAuth authorization its callers must present. Its tools are built from the
+     * Agent Contract.
+     */
+    readonly mcp?: AvConfigMcp;
+    readonly adapter: AvAdapter<M>;
+    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">;
+    /**
+     * 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
+     * layer's. Left out, the agent layer is that view exactly.
+     */
+    readonly agent?: AvConfigAgentLayer<M, Cfg>;
+};
+/**
+ * The `mcp` key: the MCP endpoint's mount path (`"/mcp"`), or the path with
+ * the authorization its callers must present.
+ */
+export type AvConfigMcp = string | {
+    /** The MCP endpoint's mount path, written as `api` is. */
+    readonly path: string;
+    /**
+     * OAuth for the endpoint. Left out, the endpoint takes no token.
+     */
+    readonly authorization?: {
+        /**
+         * The authorization servers (https URLs) a caller obtains its token
+         * from, advertised in the endpoint's protected-resource metadata.
+         */
+        readonly servers: readonly string[];
+        /**
+         * Checks one bearer token: what it resolves to (the caller, say) when
+         * the token is good, `null` when it is not.
+         */
+        readonly verify: (token: string) => unknown | null | Promise<unknown | null>;
+    };
+};
+/**
+ * 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 FrameworkConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = FrameworkScopeConfig<M, Cfg> & {
-    readonly entrypoint: string;
-    readonly adapter: Adapter<M>;
-    readonly diagnostics?: FrameworkDiagnosticsSink;
-    readonly application?: FrameworkScopeConfig<M, Cfg>;
-    readonly client?: FrameworkScopeConfig<M, Cfg>;
+export type AvConfigAgentLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = AvConfigLayer<M, Cfg, "overlay"> & {
+    /**
+     * The layer the agent starts from: `"client"` (the default), `"application"`
+     * or `"root"`. The agent never widens it.
+     */
+    readonly extends?: "client" | "application" | "root";
 };
-export type { AnyFieldsBlock, AnyFrameworkConfig, AnyScopeConfig, } from "./any-framework-config.js";
-export type { FrameworkBehaviorsConfig } from "./framework-behaviors-config.js";
-export type { FrameworkFieldLifecycleTrait, FrameworkFieldsConfig, FrameworkResourceFieldsConfig, FrameworkResourceKey, FrameworkScalarFieldConfig, FrameworkScalarTypeRef, } from "./framework-fields-config.js";
-export type { FrameworkCapabilitySetRestriction, FrameworkFieldRestrictions, FrameworkProjectionScopeRestriction, FrameworkRelationCapabilityRestrictions, FrameworkRelationFieldRestrictions, FrameworkRelationMutationRestriction, FrameworkRelationReducerRestriction, FrameworkResourceFieldRestrictions, FrameworkResourceOperationRestrictions, FrameworkResourceRestrictions, FrameworkRestrictionsConfig, FrameworkScalarCapabilityRestrictions, FrameworkScalarFieldRestrictions, } from "./framework-restrictions-config.js";
+export type { AvConfigAny, AvConfigLayerAny, AvConfigResourcesAny, } from "./any-framework-config.js";
+export type { AvFieldCompute, AvRelationFieldPipeline, AvScalarFieldPipeline, AvZCheck, } from "./field-pipeline-config.js";
+export type { AvConfigExemptions, AvConfigOperationsExemption, AvConfigRelationFieldExemption, AvConfigResourceExemption, AvConfigScalarFieldExemption, AvRelationFieldCapabilityName, AvScalarFieldCapabilityName, } from "./framework-exemptions-config.js";
+export type { AvConfigAddedFieldDefinition, AvConfigFieldDefinition, AvConfigFieldLifecycleTrait, AvConfigKnownFieldDefinition, AvConfigResourceKey, AvConfigScalarTypeRef, AvZFormat, } from "./framework-field-definition.js";
+export type { AvConfigFamily, AvConfigLayerKind, AvConfigOperations, AvConfigOverlayField, AvConfigResource, AvConfigResourceFields, AvConfigResources, AvConfigResourceTransactions, AvConfigRootField, AvConfigVariant, } from "./framework-resources-config.js";

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

@@ -0,0 +1,91 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterFieldKey } from "../adapters/adapter-resource.js";
+import type { AvPaginationCapability, AvRelationFilterCapability, AvRelationMutationDirective, AvRelationReducer, AvScalarFilterOperator, AvScalarMutationDirective } from "../contracts/capability.js";
+import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvEffectiveFieldKey } from "./effective-fields.js";
+import type { AvConfigResourceKey } from "./framework-field-definition.js";
+/** The capability names a scalar field's exemption can list. */
+export type AvScalarFieldCapabilityName = "select" | "filter" | "order" | "orderNulls" | "create" | "update";
+/** The capability names a relation field's exemption can list. */
+export type AvRelationFieldCapabilityName = "select" | "include" | "filter" | "order" | "pagination" | "reducers" | "create" | "update";
+/** A scalar field's exemption: whole, by capability name, or per capability. */
+export type AvConfigScalarFieldExemption = boolean | readonly AvScalarFieldCapabilityName[] | ({
+    readonly select?: boolean;
+    readonly filter?: boolean | readonly AvScalarFilterOperator[];
+    readonly order?: boolean;
+    readonly orderNulls?: boolean;
+    readonly create?: boolean | readonly AvScalarMutationDirective[];
+    readonly update?: boolean | readonly AvScalarMutationDirective[];
+} & NotAList);
+/** A relation field's exemption: whole, by capability name, or per capability. */
+export type AvConfigRelationFieldExemption = boolean | readonly AvRelationFieldCapabilityName[] | ({
+    readonly select?: boolean;
+    readonly include?: boolean;
+    readonly filter?: boolean | readonly AvRelationFilterCapability[];
+    readonly order?: boolean;
+    readonly pagination?: boolean | readonly AvPaginationCapability[];
+    readonly reducers?: boolean | readonly AvRelationReducer[];
+    readonly create?: boolean | readonly AvRelationMutationDirective[];
+    readonly update?: boolean | readonly AvRelationMutationDirective[];
+} & NotAList);
+/** The operations of Resource `R`, as the adapter model states them. */
+type ResourceOperationsOf<M extends AvAdapterModel, R extends AvConfigResourceKey<M>> = M["resources"][R]["operations"];
+/** The families Resource `R` offers. */
+type FamilyOf<M extends AvAdapterModel, R extends AvConfigResourceKey<M>> = Extract<keyof ResourceOperationsOf<M, R>, string>;
+/** The variants family `F` of Resource `R` offers. */
+type VariantOf<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, F extends FamilyOf<M, R>> = Extract<keyof NonNullable<ResourceOperationsOf<M, R>[F]>, string>;
+/**
+ * A Resource's operations exemption, in the nested form: whole, a list of
+ * families, or per family a list of variants or a per-variant object.
+ */
+export type AvConfigOperationsExemption<M extends AvAdapterModel = AvAdapterModel, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = boolean | readonly FamilyOf<M, R>[] | ({
+    readonly [F in FamilyOf<M, R>]?: boolean | readonly VariantOf<M, R, F>[] | ({
+        readonly [V in VariantOf<M, R, F>]?: boolean;
+    } & NotAList);
+} & NotAList);
+/** Refuses a list where the object form is meant. */
+type NotAList = {
+    readonly [index: number]: never;
+};
+/** The tokens one capability member offers, its position qualifier aside. */
+type MemberToken<Member> = Member extends {
+    readonly directives: readonly (infer Token)[];
+} ? Token : Member extends {
+    readonly reducers: readonly (infer Token)[];
+} ? Token : Member extends readonly (infer Token)[] ? Token : never;
+/** A token capability's exemption: whole, or the tokens the field offers. */
+type TokenExemption<Caps, K> = K extends keyof Caps ? boolean | readonly MemberToken<NonNullable<Caps[K]>>[] : boolean;
+/** The capability names a discovered scalar's exemption can name: its own, and `select`. */
+type ScalarNameOf<Caps> = Extract<keyof Caps, AvScalarFieldCapabilityName> | "select";
+/** A discovered scalar field's exemption, by its capabilities. */
+type ScalarFieldExemptionOf<Caps> = boolean | readonly ScalarNameOf<Caps>[] | ({
+    readonly [K in ScalarNameOf<Caps>]?: K extends "filter" | "create" | "update" ? TokenExemption<Caps, K> : boolean;
+} & NotAList);
+/** The capability names a discovered relation's exemption can name: its own. */
+type RelationNameOf<Caps> = Extract<keyof Caps, AvRelationFieldCapabilityName>;
+/** A discovered relation field's exemption, by its capabilities. */
+type RelationFieldExemptionOf<Caps> = boolean | readonly RelationNameOf<Caps>[] | ({
+    readonly [K in RelationNameOf<Caps>]?: K extends "select" | "include" | "order" ? boolean : TokenExemption<Caps, K>;
+} & NotAList);
+/** The exemption shape one effective field name admits. */
+type FieldExemptionFor<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, F extends string> = string extends F ? AvConfigScalarFieldExemption | AvConfigRelationFieldExemption : F extends AvAdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
+    readonly kind: "relation";
+    readonly capabilities: infer Caps;
+} ? RelationFieldExemptionOf<Caps> : M["resources"][R]["fields"][F] extends {
+    readonly capabilities: infer Caps;
+} ? ScalarFieldExemptionOf<Caps> : AvConfigScalarFieldExemption : AvConfigScalarFieldExemption;
+/** A Resource's exemption: whole, or its operations and fields. No list. */
+export type AvConfigResourceExemption<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = boolean | ({
+    readonly operations?: AvConfigOperationsExemption<M, R>;
+    readonly fields?: {
+        readonly [F in AvEffectiveFieldKey<M, Cfg, R>]?: FieldExemptionFor<M, R, F>;
+    };
+} & NotAList);
+/** The entries that are the opposite of a layer's `exposed`. */
+export type AvConfigExemptions<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = {
+    /** Per Resource, by the adapter's Resource names. */
+    readonly resources?: {
+        readonly [R in AvConfigResourceKey<M>]?: AvConfigResourceExemption<M, Cfg, R>;
+    };
+};
+export {};

package/dist/config/framework-exemptions-config.js

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

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

@@ -0,0 +1,78 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvScalarFieldCapabilities } from "../contracts/field.js";
+import type { JsonShape } from "../contracts/json-shape.js";
+import type { AvLifecycleTrait } from "../contracts/lifecycle-trait.js";
+/** The lifecycle traits a configuration may set on a field. */
+export type AvConfigFieldLifecycleTrait = Extract<AvLifecycleTrait, "VIRTUAL">;
+/** The names of the Resources in adapter model `M`. */
+export type AvConfigResourceKey<M extends AvAdapterModel> = Extract<keyof M["resources"], string>;
+/** A scalar type or an enum of adapter model `M`, by name. */
+export type AvConfigScalarTypeRef<M extends AvAdapterModel> = {
+    readonly scalar: Extract<keyof M["scalars"], string>;
+} | {
+    readonly enum: Extract<keyof M["enums"], string>;
+};
+/** zod's named string formats: the `format` names a configured field may state. */
+export declare const AVZ_FORMATS: readonly ["email", "url", "emoji", "uuid", "guid", "nanoid", "cuid", "cuid2", "ulid", "xid", "ksuid", "datetime", "date", "time", "duration", "ipv4", "ipv6", "cidrv4", "cidrv6", "base64", "base64url", "json_string", "e164", "credit_card", "iban", "jwt"];
+/**
+ * One of zod's named string formats. A configured (VIRTUAL) field states its
+ * `format` with one of these; any other name is refused.
+ */
+export type AvZFormat = (typeof AVZ_FORMATS)[number];
+/**
+ * A field's definition: its type, nullability, list-ness, lifecycle, format,
+ * capabilities and Json shape. Root only.
+ */
+export type AvConfigFieldDefinition<M extends AvAdapterModel = AvAdapterModel> = {
+    /** The field's scalar or enum type. A discovered field may only restate its own. */
+    readonly type?: AvConfigScalarTypeRef<M>;
+    /** Whether the field may be `null`. A discovered field may only restate its own. */
+    readonly nullable?: boolean;
+    /** Whether the field holds a list. A discovered field may only restate its own. */
+    readonly list?: boolean;
+    /** `["VIRTUAL"]`: a field the store does not hold. Configured fields only. */
+    readonly lifecycle?: readonly AvConfigFieldLifecycleTrait[];
+    /** The value's format, one of zod's named formats. Configured fields only. */
+    readonly format?: AvZFormat;
+    /** What callers may do with the field. Configured fields only. */
+    readonly capabilities?: Partial<AvScalarFieldCapabilities>;
+    /**
+     * A discovered Json field's shape, built with `AvZ` from
+     * `@aventara/core/avz`: writes to the field are checked against it, and its
+     * value is typed by it.
+     */
+    readonly json?: JsonShape;
+};
+/**
+ * What a definition may say about field `Field` the adapter discovered: restate
+ * its `type`, `nullable` and `list`, and give a Json field its shape.
+ */
+export type AvConfigKnownFieldDefinition<Field> = {
+    readonly type?: Field extends {
+        readonly type: infer Type;
+    } ? Type : never;
+    readonly nullable?: Field extends {
+        readonly nullable: infer Nullable;
+    } ? Nullable : never;
+    readonly list?: Field extends {
+        readonly list: infer List;
+    } ? List : never;
+    readonly lifecycle?: never;
+    readonly format?: never;
+    readonly capabilities?: never;
+    readonly json?: Field extends {
+        readonly type: {
+            readonly scalar: "json";
+        };
+    } ? JsonShape : never;
+};
+/**
+ * A configured field, which the adapter did not discover: `type`, `nullable` and
+ * `list` are required, and it takes no `json` shape.
+ */
+export type AvConfigAddedFieldDefinition<M extends AvAdapterModel = AvAdapterModel> = Omit<AvConfigFieldDefinition<M>, "type" | "nullable" | "list" | "json"> & {
+    readonly type: AvConfigScalarTypeRef<M>;
+    readonly nullable: boolean;
+    readonly list: boolean;
+    readonly json?: never;
+};

package/dist/config/framework-field-definition.js

@@ -0,0 +1,28 @@
+export const AVZ_FORMATS = [
+    "email",
+    "url",
+    "emoji",
+    "uuid",
+    "guid",
+    "nanoid",
+    "cuid",
+    "cuid2",
+    "ulid",
+    "xid",
+    "ksuid",
+    "datetime",
+    "date",
+    "time",
+    "duration",
+    "ipv4",
+    "ipv6",
+    "cidrv4",
+    "cidrv6",
+    "base64",
+    "base64url",
+    "json_string",
+    "e164",
+    "credit_card",
+    "iban",
+    "jwt",
+];

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

@@ -0,0 +1,116 @@
+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 { AvConfigAny } from "./any-framework-config.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";
+import type { AvPipeline, AvTransactionPipeline } from "./pipeline-config.js";
+/**
+ * Whether a layer is the root, where fields are defined, or an overlay
+ * (`application`, `client`), which registers stages on them but never defines one.
+ */
+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>>> = {
+    /**
+     * Stages that run for this one operation: at a variant, `ctx.$args` (and a
+     * pipe's arguments) are typed as the operation's arguments.
+     */
+    readonly pipelines?: AvPipeline<NoInfer<M>, R, F, V, A>;
+    /** 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;
+};
+/** 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>;
+};
+/** A Resource's transaction level. */
+export type AvConfigResourceTransactions<M extends AvAdapterModel = AvAdapterModel> = {
+    /** Stages that run once per transaction with a top-level step on the Resource. */
+    readonly pipelines?: AvTransactionPipeline<NoInfer<M>>;
+};
+/** A field's entry at the root: its definition and its stages. */
+export type AvConfigRootField<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = {
+    /** What the field is. Root only. */
+    readonly definition?: AvConfigFieldDefinition<M>;
+    /** The field's stages. */
+    readonly pipelines?: AvScalarFieldPipeline<M, Cfg, R>;
+};
+/** A field's entry in an overlay: its stages only. */
+export type AvConfigOverlayField<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = {
+    /** The field's stages, added to the root's. */
+    readonly pipelines?: AvScalarFieldPipeline<M, Cfg, R>;
+};
+/** The checks a scalar type takes, or `never`. */
+type ScalarChecks<Scalar> = Scalar extends "string" ? AvZCheck<"string"> : Scalar extends "int" | "float" ? AvZCheck<"number"> : Scalar extends "bigint" | "decimal" | "datetime" | "bytes" ? AvZCheck<Scalar> : never;
+/** The checks a discovered scalar field takes: its type's, and a list's length. */
+type FieldCheckOf<Field> = Field extends {
+    readonly type: infer Type;
+    readonly list: infer List;
+} ? (Type extends {
+    readonly scalar: infer Scalar;
+} ? string extends Scalar ? AvZCheck : ScalarChecks<Scalar> : never) | (false extends List ? never : AvZCheck<"list">) : AvZCheck;
+/** A discovered scalar field's stages, its `validators` typed by the field. */
+type KnownScalarFieldPipeline<M extends AvAdapterModel, Cfg, R extends AvConfigResourceKey<M>, Field> = Field extends {
+    readonly type: {
+        readonly scalar: "json";
+    };
+} ? Omit<AvScalarFieldPipeline<M, Cfg, R>, "validators"> & {
+    /** A Json field's checks are in its shape (`definition.json`). */
+    readonly validators?: never;
+} : AvScalarFieldPipeline<M, Cfg, R, FieldCheckOf<Field>>;
+/** The root entry one effective field name admits. */
+type RootFieldConfigFor<M extends AvAdapterModel, Cfg, R extends AvConfigResourceKey<M>, F extends string> = string extends F ? AvConfigRootField<M, Cfg, R> : F extends AvAdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
+    readonly kind: "relation";
+} ? {
+    readonly definition?: never;
+    readonly pipelines?: AvRelationFieldPipeline<M, R>;
+} : {
+    readonly definition?: AvConfigKnownFieldDefinition<M["resources"][R]["fields"][F]>;
+    readonly pipelines?: KnownScalarFieldPipeline<M, Cfg, R, M["resources"][R]["fields"][F]>;
+} : {
+    readonly definition: AvConfigAddedFieldDefinition<M>;
+    readonly pipelines?: AvScalarFieldPipeline<M, Cfg, R>;
+};
+/** The overlay entry one effective field name admits. */
+type OverlayFieldConfigFor<M extends AvAdapterModel, Cfg, R extends AvConfigResourceKey<M>, F extends string> = string extends F ? AvConfigOverlayField<M, Cfg, R> : F extends AvAdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
+    readonly kind: "relation";
+} ? {
+    readonly pipelines?: AvRelationFieldPipeline<M, R>;
+} : {
+    readonly pipelines?: KnownScalarFieldPipeline<M, Cfg, R, M["resources"][R]["fields"][F]>;
+} : AvConfigOverlayField<M, Cfg, R>;
+/** A Resource's fields at one layer, keyed by its effective field names. */
+export type AvConfigResourceFields<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Kind extends AvConfigLayerKind = "root"> = {
+    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"> = {
+    /** 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>;
+    /** 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 {};

package/dist/config/framework-resources-config.js

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

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

@@ -1,29 +1,65 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { AfterHook, BeforeHook, Filter, Guard, Interceptor, Pipe } from "../runtime/pipeline.js";
-/** Pipeline registrations for one configuration scope. See {@link PipelineContext}. */
-export type PipelineConfig<M extends AdapterModel = AdapterModel> = {
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvOperationFamily } from "../operations/operation-identity.js";
+import type { AvAfterHook, AvBeforeHook, AvFilter, AvGuard, AvInterceptor, AvPipe, AvTransactionAfterHook, AvTransactionBeforeHook, AvTransactionFilter, AvTransactionGuard, AvTransactionInterceptor, AvTransactionPipe } from "../runtime/pipeline.js";
+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> = {
     /** Run first; a guard returning `false` denies the operation with `A4001`. */
-    readonly guards?: readonly Guard<M>[];
+    readonly guards?: readonly AvGuard<M, R, F, V, A>[];
     /** Run in order on the arguments; a pipe may return replacement arguments. */
-    readonly pipes?: readonly Pipe<M>[];
-    /** Run just before (`before`) and after (`after`) the operation executes. */
+    readonly pipes?: readonly AvPipe<M, R, F, V, A>[];
+    /**
+     * Run around the operation, inside every level's interceptors: `before`
+     * hooks outer to inner, `after` hooks inner to outer.
+     */
     readonly hooks?: {
-        readonly before?: readonly BeforeHook<M>[];
-        readonly after?: readonly AfterHook<M>[];
+        readonly before?: readonly AvBeforeHook<M, R, F, V, A>[];
+        readonly after?: readonly AvAfterHook<M, R, F, V, A>[];
     };
-    /** Wrap the operation's execution; each calls `next()` to continue. */
-    readonly interceptors?: readonly Interceptor<M>[];
-    /** Turn a thrown error into a {@link FrameworkError} outcome. */
-    readonly filters?: readonly Filter<M>[];
+    /** 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>[];
 };
-/** The pipelines that run for one origin, root and overlay combined. */
+/**
+ * A Resource's transaction stages: they run once per transaction with a
+ * top-level step on the Resource, inside it, and see the whole plan.
+ */
+export type AvTransactionPipeline<M extends AvAdapterModel = AvAdapterModel> = {
+    readonly guards?: readonly AvTransactionGuard<M>[];
+    readonly pipes?: readonly AvTransactionPipe<M>[];
+    readonly hooks?: {
+        readonly before?: readonly AvTransactionBeforeHook<M>[];
+        readonly after?: readonly AvTransactionAfterHook<M>[];
+    };
+    readonly interceptors?: readonly AvTransactionInterceptor<M>[];
+    readonly filters?: readonly AvTransactionFilter<M>[];
+};
+/**
+ * One level's registrations, as one layer states them: the unit the pipeline
+ * tree composes (`pipeline-tree.resolver.ts`).
+ */
 export type ResolvedPipelineConfig = {
-    readonly guards: readonly Guard[];
-    readonly pipes: readonly Pipe[];
+    readonly guards: readonly AvGuard[];
+    readonly pipes: readonly AvPipe[];
+    readonly hooks: {
+        readonly before: readonly AvBeforeHook[];
+        readonly after: readonly AvAfterHook[];
+    };
+    readonly interceptors: readonly AvInterceptor[];
+    readonly filters: readonly AvFilter[];
+};
+/** One layer's registrations on one Resource's transactions. */
+export type ResolvedTransactionPipelineConfig = {
+    readonly guards: readonly AvTransactionGuard[];
+    readonly pipes: readonly AvTransactionPipe[];
     readonly hooks: {
-        readonly before: readonly BeforeHook[];
-        readonly after: readonly AfterHook[];
+        readonly before: readonly AvTransactionBeforeHook[];
+        readonly after: readonly AvTransactionAfterHook[];
     };
-    readonly interceptors: readonly Interceptor[];
-    readonly filters: readonly Filter[];
+    readonly interceptors: readonly AvTransactionInterceptor[];
+    readonly filters: readonly AvTransactionFilter[];
 };