@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

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

@@ -0,0 +1,47 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvZCheck } from "../avz/avz-check.registry.js";
+import type { AvComputeCreate, AvComputeRead, AvComputeUpdate } from "../runtime/field-compute.js";
+import type { AvFieldGuard, AvFieldPipe } from "../runtime/pipeline.js";
+import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvConfigResourceKey } from "./framework-field-definition.js";
+export type { AvZCheck } from "../avz/avz-check.registry.js";
+/**
+ * A scalar field's computed values, one stage per phase: `create` and `update`
+ * run before the write, `read` on each returned record.
+ */
+export type AvFieldCompute<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = {
+    /** Computes the value on every create; an upsert's create branch included. */
+    readonly create?: AvComputeCreate<M>;
+    /** Computes the value on every read of a returned record. */
+    readonly read?: AvComputeRead<M, Cfg, R>;
+    /** Computes the value on every update; an upsert's update branch included. */
+    readonly update?: AvComputeUpdate<M>;
+};
+/**
+ * A scalar field's stages: validators, field pipes, compute and write guards.
+ * `Check` is the checks the field takes (any, when the field's type is not
+ * known here).
+ */
+export type AvScalarFieldPipeline<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Check extends AvZCheck = AvZCheck> = {
+    /**
+     * Declarative checks on the value, built with `AvZ` and carried in the Contract;
+     * root's, then the overlay's. On a list field `AvZ.minItems` and `AvZ.maxItems`
+     * check the list and every other check each entry.
+     */
+    readonly validators?: readonly Check[];
+    /**
+     * Pure transforms of the sent value: value in, value out, no context. They run
+     * after the operation's pipes and before the validators; in a transaction, on
+     * literal values before it opens and on a `$ref` value at its step.
+     */
+    readonly pipes?: readonly AvFieldPipe[];
+    /** The field's computed values. */
+    readonly compute?: AvFieldCompute<M, Cfg, R>;
+    /** Write-only admission: run when the caller sends the field. */
+    readonly guards?: readonly AvFieldGuard<NoInfer<M>, R>[];
+};
+/** A relation field's stages: write guards only. */
+export type AvRelationFieldPipeline<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>> = {
+    /** Write-only admission: run for every write through the relation. */
+    readonly guards?: readonly AvFieldGuard<NoInfer<M>, R>[];
+};

package/dist/config/forced-operation.validator.d.ts

@@ -0,0 +1,10 @@
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { AvConfigDiagnostic } from "./config-diagnostic.js";
+type LayerRecord = Readonly<Record<string, unknown>>;
+/**
+ * The `forceTransaction` settings a forced call could not honour: one
+ * `CONFIG_INVALID_VALUE` per configuration path, naming every origin whose
+ * Contract offers the operation without transactions.
+ */
+export declare function validateForcedOperations(config: LayerRecord, contracts: AvContracts): readonly AvConfigDiagnostic[];
+export {};

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,52 +1,161 @@
-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 { FrameworkMisuseSink } from "../runtime/misuse-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 { 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, 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 FrameworkLimitsConfig = Partial<ContractLimits>;
+export type AvConfigLimits = Partial<AvContractLimits>;
 /**
- * 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<NoInfer<M>>;
+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`. */
+    readonly behaviors?: never;
+    /** Moved: `resources.<R>.fields.<f>.definition`. */
+    readonly fields?: never;
+    /** Moved: `transactionsStyle`. */
+    readonly transactions?: never;
+    /**
+     * 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, Layer>;
+    /**
+     * 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 FrameworkConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = FrameworkScopeConfig<M, Cfg> & {
-    readonly entrypoint: string;
-    readonly adapter: Adapter<M>;
-    readonly diagnostics?: FrameworkDiagnosticsSink;
+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>;
+    /**
+     * 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?: FrameworkMisuseSink;
-    readonly application?: FrameworkScopeConfig<M, Cfg>;
-    readonly client?: FrameworkScopeConfig<M, Cfg>;
+    readonly misuse?: AvMisuseSink;
+    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
+     * layer's. Left out, the agent layer is that view exactly.
+     */
+    readonly agent?: AvConfigAgentLayer<M, Cfg>;
 };
-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";
+/**
+ * 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. 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[];
+        /**
+         * 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 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.
+     */
+    readonly extends?: "client" | "application" | "root";
+};
+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",
+];