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

package/dist/adapters/adapter-field.d.ts

@@ -24,6 +24,20 @@ export type AvAdapterRelationField<M extends AvAdapterModel> = {
     readonly cardinality: "one" | "many";
     readonly nullable: boolean;
     readonly capabilities: AvRelationFieldCapabilities;
+    /**
+     * The target's relation field that is this relation's other end, when the data
+     * source pairs them (`User.posts` ↔ `Post.author`; a self-relation's two ends
+     * name each other). Absent: no pairing is stated, and no write is read as
+     * walking a relation back.
+     */
+    readonly inverse?: string;
+    /**
+     * The scalar fields of this Resource that hold the relation's reference, in
+     * the order the data source pairs them with the target's key
+     * (`Post.author` → `["authorId"]`), on an optional relation as on a required
+     * one. Absent on the end that holds no reference (`User.posts`); never empty.
+     */
+    readonly referenceFields?: readonly [string, ...string[]];
 };
 /** One field the adapter discovered: a scalar or a relation. */
 export type AvAdapterField<M extends AvAdapterModel> = AvAdapterScalarField<M> | AvAdapterRelationField<M>;

package/dist/adapters/adapter-model.d.ts

@@ -1,3 +1,4 @@
+import type { AvConfigComputedFields } from "../config/computed-fields.js";
 import type { AvEnumDefinition } from "../contracts/enum-definition.js";
 import type { ReferenceWriteLimit } from "../contracts/reference-write-limit.js";
 import type { AvScalarRegistry } from "../contracts/scalar.js";
@@ -23,4 +24,12 @@ export interface AvAdapterModel {
      * either way. Compiled into every Contract.
      */
     readonly referenceWrites?: ReferenceWriteLimit;
+    /**
+     * Type-only, never present at runtime: which fields the configuration's write
+     * compute fills, as an adapter's generate step read them off the
+     * configuration's type. A variant's guards, pipes and filters may leave
+     * exactly those out of a create. Absent: any create field may be computed, so
+     * those stages require none.
+     */
+    readonly "~computedFields"?: AvConfigComputedFields;
 }

package/dist/adapters/adapter.interface.d.ts

@@ -1,3 +1,4 @@
+import type { AvConfigComputedFields } from "../config/computed-fields.js";
 import type { ReferentialActionTable } from "../runtime/referential-action.js";
 import type { AvAdapterModel } from "./adapter-model.js";
 import type { AvAdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
@@ -30,6 +31,15 @@ export interface AvAdapter<M extends AvAdapterModel = AvAdapterModel> extends Av
      * or `$set` runs the target's `update` guards.
      */
     readonly referentialActions?: ReferentialActionTable;
+    /**
+     * Optional: which fields the configuration's write compute fills, as the
+     * Adapter's generate step read them when it wrote the model's type (the same
+     * statement as the type's `"~computedFields"`). When the Framework is
+     * constructed it is compared with the configuration, and a difference is a
+     * warning that the generated types are stale (`aventara:prepare` regenerates
+     * them); it changes no behaviour. Never part of a Contract or its hash.
+     */
+    readonly computedFields?: AvConfigComputedFields;
     /**
      * Optional: `true` when the Adapter runs developer SQL statements: standalone
      * through its own {@link executeSql}, and, when it has `transaction`, inside a

package/dist/compiler/contract-compiler-diagnostic.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeDescription } from "../runtime/error-guidance.js";
+import type { AvContractCompilerDiagnosticCode } from "./contract-compiler-diagnostic.js";
+/** Meaning, cause and fix of every contract-compilation diagnostic code. */
+export declare const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE: {
+    readonly [C in AvContractCompilerDiagnosticCode]: ErrorCodeDescription;
+};

package/dist/compiler/contract-compiler-diagnostic.guidance.js

@@ -0,0 +1,97 @@
+export const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE = {
+    COMPILER_UNKNOWN_RESOURCE: {
+        message: "Unknown Resource.",
+        cause: "A Resource name the adapter's model does not have, in resources or in exemptions.",
+        fix: "Use the model's exact name. After a schema change run `npm run aventara:prepare`.",
+    },
+    COMPILER_UNKNOWN_FIELD: {
+        message: "Unknown field.",
+        cause: "A field that is neither in the schema nor defined at the root.",
+        fix: "Fix the name, run aventara:prepare after a schema change, or add the field with a root definition.",
+    },
+    COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED: {
+        message: "A relation field takes write guards only.",
+        cause: "Field pipes or compute on a relation field.",
+        fix: "Put the stage on the relation's reference field, or use an operation pipe.",
+    },
+    COMPILER_INCOMPLETE_FIELD: {
+        message: "An added field is incomplete.",
+        cause: "A definition that adds a field leaves out type, nullable or list.",
+        fix: 'Spell out type, nullable and list, with lifecycle: ["VIRTUAL"] for a field that has no column.',
+    },
+    COMPILER_STRUCTURAL_FIELD_OVERRIDE: {
+        message: "A discovered field's structure was redefined.",
+        cause: "A definition on a field the adapter discovered changes its type, format or capabilities.",
+        fix: "Restate only its type, nullable and list. Change capabilities through exemptions and the column through the schema.",
+    },
+    COMPILER_MISSING_SCALAR: {
+        message: "Unknown scalar type.",
+        cause: "A definition names a scalar type that does not exist.",
+        fix: "Use a built-in scalar: string, boolean, int, float, bigint, decimal, datetime, bytes or json.",
+    },
+    COMPILER_MISSING_ENUM: {
+        message: "Unknown enum.",
+        cause: "A definition names an enum the model does not have.",
+        fix: "Use an enum of the schema, and run aventara:prepare after adding one.",
+    },
+    COMPILER_DANGLING_RELATION: {
+        message: "A visible relation points at a hidden Resource.",
+        cause: "A layer hides a Resource but still exposes a relation field that targets it.",
+        fix: "Hide the relation field too (`exemptions.resources.<R>.fields.<relation>: true`), or expose the target.",
+    },
+    COMPILER_UNAVAILABLE_OPERATION: {
+        message: "Operation not available.",
+        cause: "An operation the adapter does not offer (such as delete.many), or an overlay granting one that its parent hid.",
+        fix: "Remove it. To reach an operation from one overlay only, expose it at the root and hide it in the other overlay.",
+    },
+    COMPILER_UNAVAILABLE_CAPABILITY: {
+        message: "Capability not available.",
+        cause: "A capability or token the field does not offer, or an overlay (or the agent layer) granting one its parent hid. Overlays only narrow.",
+        fix: "Remove it, or expose it in the parent layer and hide it in the layer it must not reach.",
+    },
+    COMPILER_INVALID_LIFECYCLE: {
+        message: "Invalid field lifecycle.",
+        cause: "An added field declares a lifecycle other than VIRTUAL, a VIRTUAL field claims a database-generated lifecycle or a provider-side capability, or a definition redefines a discovered field's lifecycle.",
+        fix: 'Give an added field lifecycle: ["VIRTUAL"] and only the capabilities it can serve; computed lifecycles come from compute stages.',
+    },
+    COMPILER_MISSING_READ_COMPUTE: {
+        message: "A selectable virtual field has no compute.read.",
+        cause: "A VIRTUAL field that can be selected has no pipelines.compute.read stage.",
+        fix: "Add a compute.read stage, or make the field write-only with capabilities.select: false.",
+    },
+    COMPILER_INVALID_COMPUTE_DEPENDENCY: {
+        message: "Invalid compute.read dependency.",
+        cause: "A dependsOn entry that is not a stored scalar field of the same Resource.",
+        fix: "List only stored scalar fields of the Resource in dependsOn.",
+    },
+    COMPILER_RESERVED_RESOURCE_NAME: {
+        message: "Reserved Resource name.",
+        cause: "A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref).",
+        fix: "Rename the model; the table it maps to can keep its name.",
+    },
+    COMPILER_MISSING_IDENTIFIER: {
+        message: "A unique operation has no identifier.",
+        cause: "A layer exposes a unique variant (find.unique, update.unique, delete.unique, upsert.unique) and no complete identifier of the Resource: a Pick that did not pick one, or an Omit that hid every one.",
+        fix: "Expose an identifier field (id, or every field of one unique), or exempt the unique variants.",
+    },
+    COMPILER_HIDDEN_REQUIRED_FIELD: {
+        message: "A layer that creates a Resource hides a required field.",
+        cause: "A layer still creates the Resource (a create or upsert variant, or a nested create) while a required field, or a required relation's reference field, is hidden or has its create capability exempted, and no compute.create fills it.",
+        fix: "Expose the field, give it a compute.create stage, or exempt the layer's create operations.",
+    },
+    COMPILER_INVALID_VALIDATOR: {
+        message: "A field validator cannot apply.",
+        cause: "A validator that is not built with AvZ, does not fit the field's type (AvZ.maxLength on an int, AvZ.maxItems on a field that is not a list), or sits on a relation or Json field.",
+        fix: "Use an AvZ check that fits the field's type; a Json field's checks go in its json shape.",
+    },
+    COMPILER_INVALID_JSON_SHAPE: {
+        message: "A Json shape cannot apply.",
+        cause: "A json shape on a field that is not a discovered Json field, a shape not built with AvZ, or one that admits null or absence at its top level.",
+        fix: "Put the shape on a Json field, build it with AvZ, and keep its top level non-null (the column's nullability decides null).",
+    },
+    COMPILER_INVALID_CLIENT_CONTRACT: {
+        message: "The compiled client contract is invalid.",
+        cause: "The finished client contract failed its own structural check: a framework defect.",
+        fix: "Report it with the diagnostic's path and message.",
+    },
+};

package/dist/compiler/contract.compiler.js

@@ -1,5 +1,5 @@
 import { bindShapedField, jsonShapeOf } from "../avz/json-shape.registry.js";
-import { PROJECTION_SCOPES, WRITE_SCOPES } from "../contracts/capability.js";
+import { FILTER_MODES, PROJECTION_SCOPES, WRITE_SCOPES, } from "../contracts/capability.js";
 import { validateClientContractStructure } from "../contracts/client-contract-structure.validator.js";
 import { canonicalizeContract, canonicalizeContractMembers, canonicalizeJson, joinCanonicalContractMembers, recordCanonicalContractText, } from "../contracts/contract-canonicalizer.js";
 import { hashCanonicalContractText, } from "../contracts/contract-hash.js";
@@ -41,6 +41,12 @@ function normalizeAdapterScalarCapabilities(capabilities) {
         ...(capabilities.filter !== undefined
             ? { filter: [...capabilities.filter] }
             : {}),
+        ...(capabilities.filterModes !== undefined
+            ? { filterModes: [...capabilities.filterModes] }
+            : {}),
+        ...(capabilities.pathFilterModes !== undefined
+            ? { pathFilterModes: [...capabilities.pathFilterModes] }
+            : {}),
         ...(capabilities.order !== undefined ? { order: capabilities.order } : {}),
         ...(capabilities.orderNulls !== undefined
             ? { orderNulls: capabilities.orderNulls }
@@ -71,8 +77,42 @@ function cloneAdapterField(field) {
         cardinality: field.cardinality,
         nullable: field.nullable,
         capabilities: cloneValue(field.capabilities),
+        ...(typeof field.inverse === "string" ? { inverse: field.inverse } : {}),
+        ...(Array.isArray(field.referenceFields) && field.referenceFields.length > 0
+            ? { referenceFields: [...field.referenceFields] }
+            : {}),
     };
 }
+function pruneHiddenPairings(projection) {
+    const resources = projection.resources;
+    for (const [name, resource] of Object.entries(resources)) {
+        for (const field of Object.values(resource.fields)) {
+            if (field.kind !== "relation") {
+                continue;
+            }
+            if (Array.isArray(field.referenceFields)) {
+                const shown = field.referenceFields.filter((reference) => typeof reference === "string" &&
+                    Object.hasOwn(resource.fields, reference) &&
+                    resource.fields[reference]?.kind === "scalar");
+                if (shown.length > 0) {
+                    field.referenceFields = shown;
+                }
+                else {
+                    delete field.referenceFields;
+                }
+            }
+            if (typeof field.inverse !== "string") {
+                continue;
+            }
+            const other = Object.hasOwn(resources, String(field.target))
+                ? resources[String(field.target)]?.fields[field.inverse]
+                : undefined;
+            if (other?.kind !== "relation" || other.target !== name) {
+                delete field.inverse;
+            }
+        }
+    }
+}
 function cloneOperations(operations) {
     return cloneValue(operations);
 }
@@ -86,8 +126,40 @@ function cloneAdapterResource(resource) {
         operations: cloneOperations(resource.operations),
     };
 }
+function canonicalModes(modes) {
+    const stated = Array.isArray(modes) ? modes : [];
+    const known = FILTER_MODES.filter((mode) => mode === "default" || stated.includes(mode));
+    const unknown = stated.filter((mode) => !FILTER_MODES.includes(mode));
+    return [...known, ...unknown];
+}
+function qualifyFilterModes(projection) {
+    for (const resource of Object.values(projection.resources)) {
+        for (const field of Object.values(resource.fields)) {
+            if (field.kind !== "scalar") {
+                continue;
+            }
+            const capabilities = field.capabilities;
+            const filter = Array.isArray(capabilities.filter)
+                ? capabilities.filter
+                : [];
+            if (!filter.includes("mode")) {
+                delete capabilities.filterModes;
+                delete capabilities.pathFilterModes;
+                continue;
+            }
+            const stated = capabilities.filterModes;
+            capabilities.filterModes = canonicalModes(stated);
+            if (filter.includes("path")) {
+                capabilities.pathFilterModes = canonicalModes(capabilities.pathFilterModes ?? stated);
+            }
+            else {
+                delete capabilities.pathFilterModes;
+            }
+        }
+    }
+}
 function createBaseline(model) {
-    return {
+    const baseline = {
         scalars: Object.fromEntries(Object.entries(model.scalars).map(([key, value]) => [
             key,
             cloneValue(value),
@@ -106,6 +178,8 @@ function createBaseline(model) {
             ? {}
             : { referenceWrites: model.referenceWrites }),
     };
+    qualifyFilterModes(baseline);
+    return baseline;
 }
 function definitionPath(resource, field) {
     return `root.resources.${resource}.fields.${field}.definition`;
@@ -349,9 +423,14 @@ function checkReservedResourceNames(model, diagnostics) {
         }
     }
 }
+function isAdapterStated(axis) {
+    return axis?.kind === "limit" || axis?.kind === "adapterTokens";
+}
 const SCALAR_CAPABILITY_AXES = {
     select: { kind: "flag" },
     filter: { kind: "tokens" },
+    filterModes: { kind: "adapterTokens", values: FILTER_MODES },
+    pathFilterModes: { kind: "adapterTokens", values: FILTER_MODES },
     order: { kind: "flag" },
     orderNulls: { kind: "flag" },
     create: { kind: "tokens" },
@@ -445,11 +524,11 @@ function fieldName(resource, field) {
 }
 function exemptableAxis(walk, universeField, capability, label, path) {
     const axis = capabilityAxisFor(universeField.kind, capability);
-    if (axis === undefined || axis.kind === "limit") {
+    if (axis === undefined || isAdapterStated(axis)) {
         const names = Object.entries(universeField.kind === "scalar"
             ? SCALAR_CAPABILITY_AXES
             : RELATION_CAPABILITY_AXES)
-            .filter(([, entry]) => entry.kind !== "limit")
+            .filter(([, entry]) => !isAdapterStated(entry))
             .map(([name]) => name);
         unavailableCapability(path, `"${capability}" is not a capability a ${universeField.kind} field's exemption can name; it takes ${names.join(", ")}`, walk.diagnostics);
         return undefined;
@@ -533,7 +612,7 @@ function exemptField(walk, universeField, parentField, entry, label, path) {
     const result = walk.style === "omit" ? cloneValue(parentCapabilities) : {};
     if (walk.style === "pick") {
         for (const [key, value] of Object.entries(parentCapabilities)) {
-            if (capabilityAxisFor(universeField.kind, key)?.kind === "limit") {
+            if (isAdapterStated(capabilityAxisFor(universeField.kind, key))) {
                 result[key] = cloneValue(value);
             }
         }
@@ -552,7 +631,7 @@ function exemptField(walk, universeField, parentField, entry, label, path) {
         return undefined;
     }
     if (walk.style === "pick" &&
-        !Object.keys(result).some((key) => capabilityAxisFor(universeField.kind, key)?.kind !== "limit")) {
+        !Object.keys(result).some((key) => !isAdapterStated(capabilityAxisFor(universeField.kind, key)))) {
         return undefined;
     }
     return { ...cloneValue(parentField), capabilities: result };
@@ -839,6 +918,11 @@ function representationFault(axis, value) {
             return typeof value === "string" && axis.values.includes(value)
                 ? undefined
                 : `one of ${axis.values.join(", ")} is expected`;
+        case "adapterTokens":
+            return isTokenList(value) &&
+                value.every((token) => axis.values.includes(token))
+                ? undefined
+                : `a list of ${axis.values.join(", ")} is expected`;
         case "flag":
             return typeof value === "boolean" ? undefined : "a boolean is expected";
         case "tokens":
@@ -922,6 +1006,8 @@ function projectCore(model, config, diagnostics) {
     checkLayerValidators(baseline.resources, "root", config.trees.root, diagnostics);
     const validators = compileValidatorTable(baseline.resources, scope.pipelines);
     const projection = projectExposure({ layer: "root", style: exposureStyle(scope), diagnostics }, baseline, baseline, scope.exemptions);
+    qualifyFilterModes(projection);
+    pruneHiddenPairings(projection);
     projectCreateRequirements(model, projection.resources);
     checkHiddenRequirements(model, "root", baseline.resources, baseline.resources, projection.resources, diagnostics);
     applyValidators(projection.resources, validators);
@@ -950,6 +1036,8 @@ function projectDerivedScope(model, scopeName, core, parentView, config, diagnos
         diagnostics,
         ...(scopeName === "agent" ? { parent: config.agent.parent } : {}),
     }, baseline, parent, scope.exemptions);
+    qualifyFilterModes(projection);
+    pruneHiddenPairings(projection);
     projectCreateRequirements(model, projection.resources);
     checkHiddenRequirements(model, scopeName, baseline.resources, parent.resources, projection.resources, diagnostics);
     applyValidators(projection.resources, validators);

package/dist/config/computed-fields.d.ts

@@ -0,0 +1,62 @@
+import type { AvConfigAgentParent, AvConfigLayerName } from "./config-layer.js";
+/** The fields one layer's write compute fills, per Resource and phase. */
+type LayerComputedFields = Readonly<Record<string, {
+    /** Fields with a `compute.create` stage, sorted. */
+    readonly create?: readonly string[];
+    /** Fields with a `compute.update` stage, sorted. */
+    readonly update?: readonly string[];
+}>>;
+/**
+ * Which fields a configuration's write compute fills: per layer, the
+ * Resources, and per Resource the fields with a `compute.create` and a
+ * `compute.update` stage, each list sorted; and the layer the agent layer
+ * extends. Written by an adapter's generate step from the configuration's type,
+ * and compared with the configuration at startup.
+ */
+export type AvConfigComputedFields = {
+    readonly agent: LayerComputedFields;
+    /** The agent layer's `extends`: `"client"` when the configuration leaves it out. */
+    readonly agentExtends: AvConfigAgentParent;
+    readonly application: LayerComputedFields;
+    readonly client: LayerComputedFields;
+    readonly root: LayerComputedFields;
+};
+/** The layers whose compute may have filled a field when a stage of layer `L` runs. */
+type ComputingLayers<Facts extends AvConfigComputedFields, L extends AvConfigLayerName> = L extends "root" ? AvConfigLayerName : L extends "agent" ? "root" | "agent" | Exclude<Facts["agentExtends"], "root"> : "root" | L | (Facts["agentExtends"] extends L ? "agent" : never);
+/** `"<Resource>.<field>"` for every field a layer's `compute.create` fills. */
+type CreateComputedOf<Layer> = Layer extends object ? {
+    [R in keyof Layer]: Layer[R] extends {
+        readonly create?: readonly (infer Field extends string)[];
+    } ? `${R & string}.${Field}` : never;
+}[keyof Layer] : never;
+/**
+ * The create fields a variant's guards, pipes and filters of layer `L` may be
+ * told without, as `"<Resource>.<field>"`: those a layer whose compute runs for
+ * the stage's origins fills on create. `string` (every field) when the model's
+ * type carries no statement of them.
+ */
+export type AvPreComputeLift<M, L extends AvConfigLayerName> = M extends {
+    readonly "~computedFields"?: infer Facts;
+} ? Exclude<Facts, undefined> extends infer Stated extends AvConfigComputedFields ? string extends keyof Stated["root"] ? string : CreateComputedOf<Stated[ComputingLayers<Stated, L>]> : string : string;
+/** The configuration's layers' `resources` trees and the agent's parent. */
+export type ComputedFieldsSource = {
+    readonly trees: Readonly<Record<AvConfigLayerName, unknown>>;
+    readonly agentExtends: AvConfigAgentParent;
+};
+/** The computed fields of a configuration, in the form a generate step writes them. */
+export declare function computedFieldsOf(source: ComputedFieldsSource): AvConfigComputedFields;
+/**
+ * How the configuration's computed fields differ from the ones the generated
+ * types were written with, one sentence per difference; empty when they agree.
+ */
+export declare function computedFieldsDrift(generated: AvConfigComputedFields, configured: AvConfigComputedFields): string[];
+/** The warning's code, as `process.emitWarning` reports it. */
+export declare const STALE_GENERATED_TYPES_WARNING = "AVENTARA_STALE_GENERATED_TYPES";
+/**
+ * Warns, through `process.emitWarning` (code
+ * {@link STALE_GENERATED_TYPES_WARNING}), when the generated types' computed
+ * fields differ from the configuration's. Nothing to compare (an Adapter that
+ * carries none) warns nothing.
+ */
+export declare function warnOnStaleComputedFields(generated: AvConfigComputedFields | undefined, configured: AvConfigComputedFields): void;
+export {};

package/dist/config/computed-fields.js

@@ -0,0 +1,80 @@
+import { computeOfLayer } from "./field-compute.resolver.js";
+function layerComputedFields(resources) {
+    const result = {};
+    const compute = computeOfLayer(resources);
+    for (const resource of Object.keys(compute).sort()) {
+        const fields = compute[resource] ?? {};
+        const create = Object.keys(fields)
+            .filter((field) => fields[field]?.create !== undefined)
+            .sort();
+        const update = Object.keys(fields)
+            .filter((field) => fields[field]?.update !== undefined)
+            .sort();
+        if (create.length === 0 && update.length === 0) {
+            continue;
+        }
+        result[resource] = {
+            ...(create.length === 0 ? {} : { create }),
+            ...(update.length === 0 ? {} : { update }),
+        };
+    }
+    return result;
+}
+export function computedFieldsOf(source) {
+    return {
+        agent: layerComputedFields(source.trees.agent),
+        agentExtends: source.agentExtends,
+        application: layerComputedFields(source.trees.application),
+        client: layerComputedFields(source.trees.client),
+        root: layerComputedFields(source.trees.root),
+    };
+}
+const LAYERS = ["root", "application", "client", "agent"];
+const PHASES = ["create", "update"];
+function missingFrom(left, right) {
+    const missing = [];
+    for (const layer of LAYERS) {
+        for (const [resource, phases] of Object.entries(left[layer])) {
+            for (const phase of PHASES) {
+                for (const field of phases[phase] ?? []) {
+                    if (!right[layer][resource]?.[phase]?.includes(field)) {
+                        missing.push(`${layer} ${resource}.${field} (${phase})`);
+                    }
+                }
+            }
+        }
+    }
+    return missing;
+}
+export function computedFieldsDrift(generated, configured) {
+    const drift = [
+        ...missingFrom(configured, generated).map((entry) => `computed in the configuration, not in the types: ${entry}`),
+        ...missingFrom(generated, configured).map((entry) => `computed in the types, not in the configuration: ${entry}`),
+    ];
+    if (generated.agentExtends !== configured.agentExtends) {
+        drift.push(`the agent layer extends "${configured.agentExtends}", the types say "${generated.agentExtends}"`);
+    }
+    return drift;
+}
+export const STALE_GENERATED_TYPES_WARNING = "AVENTARA_STALE_GENERATED_TYPES";
+export function warnOnStaleComputedFields(generated, configured) {
+    if (generated === undefined) {
+        return;
+    }
+    const drift = computedFieldsDrift(generated, configured);
+    if (drift.length === 0) {
+        return;
+    }
+    const message = `generated types are stale: run aventara:prepare. The computed fields the pre-compute stages are typed with differ from the configuration's:\n${drift
+        .map((line) => `  - ${line}`)
+        .join("\n")}`;
+    const emitWarning = globalThis.process?.emitWarning;
+    if (typeof emitWarning === "function") {
+        emitWarning(message, {
+            type: "AventaraWarning",
+            code: STALE_GENERATED_TYPES_WARNING,
+        });
+        return;
+    }
+    globalThis.console?.warn(`AventaraWarning: ${message}`);
+}

package/dist/config/config-diagnostic.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeDescription } from "../runtime/error-guidance.js";
+import type { AvConfigDiagnosticCode } from "./config-diagnostic.js";
+/** Meaning, cause and fix of every configuration diagnostic code. */
+export declare const CONFIG_DIAGNOSTIC_GUIDANCE: {
+    readonly [C in AvConfigDiagnosticCode]: ErrorCodeDescription;
+};

package/dist/config/config-diagnostic.guidance.js

@@ -0,0 +1,32 @@
+export const CONFIG_DIAGNOSTIC_GUIDANCE = {
+    CONFIG_REQUIRED: {
+        message: "A required configuration key is missing.",
+        cause: "A key that must be present is absent: api, adapter, or an overlay's exposed when the overlay sets exemptions.",
+        fix: "Add the key at the diagnostic's path.",
+    },
+    CONFIG_UNKNOWN_PROPERTY: {
+        message: "Unknown configuration key.",
+        cause: "A key the configuration does not define at that place: a typo, or a key written at the wrong level of the tree.",
+        fix: 'Remove it, or move it where it belongs (the configuration reference\'s "Where a key can go").',
+    },
+    CONFIG_INVALID_TYPE: {
+        message: "A configuration key has the wrong type.",
+        cause: "A value of the wrong type, or a key set to an explicit undefined.",
+        fix: "Give the value the type the reference states; leave a key out rather than setting it to undefined.",
+    },
+    CONFIG_INVALID_VALUE: {
+        message: "A configuration value is not allowed.",
+        cause: 'A malformed api or mcp path, a negative limit, an unknown transactionsStyle, a format that is not a named zod format, or forceTransaction under an effective transactionsStyle "none".',
+        fix: "Use a value the message allows.",
+    },
+    CONFIG_MOVED_PROPERTY: {
+        message: "A configuration key moved in rc.1.",
+        cause: "Configuration written for 1.0.0-rc.0: restrictions, entrypoint, fields, behaviors, transactions or pipelines.before/after.",
+        fix: "Move it where the message says: restrictions to exposed + exemptions, entrypoint to api, fields to `resources.<R>.fields.<f>.definition`, transactions to transactionsStyle, before/after to pipelines.hooks.",
+    },
+    CONFIG_FORBIDDEN_IN_OVERLAY: {
+        message: "A root-only key is written in an overlay.",
+        cause: "A field definition in application, client or agent.",
+        fix: "Define the field once at the root (`resources.<R>.fields.<f>.definition`); an overlay only chooses its visibility.",
+    },
+};

package/dist/config/define-resource.d.ts

@@ -18,7 +18,7 @@ type ResourceOverlays = {
 };
 /** The overlay blocks `Overlays`, each checked against the root `Block`. */
 type CheckedOverlays<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, Block, Overlays> = {
-    readonly [L in keyof Overlays]: L extends OverlayLayer ? NoInfer<AvConfigResource<M, ResourceBlockConfig<R, Block>, R, "overlay"> & ExactOverlayResource<M, ResourceBlockConfig<R, Block>, R, Overlays[L]>> : never;
+    readonly [L in keyof Overlays]: L extends OverlayLayer ? NoInfer<AvConfigResource<M, ResourceBlockConfig<R, Block>, R, "overlay", L> & ExactOverlayResource<M, ResourceBlockConfig<R, Block>, R, Overlays[L]>> : never;
 };
 /**
  * What {@link defineResource} returns: `root`, and `application`, `client` and