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

package/dist/avz/avz.js

@@ -0,0 +1,354 @@
+import { array as zodArray, boolean as zodBoolean, discriminatedUnion as zodDiscriminatedUnion, enum as zodEnum, int as zodInt, literal as zodLiteral, null as zodNull, nullable as zodNullable, number as zodNumber, optional as zodOptional, record as zodRecord, strictObject as zodStrictObject, string as zodString, tuple as zodTuple, union as zodUnion, } from "zod/mini";
+import { fieldCheckIssue, passesFieldCheck, } from "../runtime/field-check.evaluator.js";
+import * as checks from "./avz-check.factory.js";
+import { avzCheckOf, } from "./avz-check.registry.js";
+import { registerJsonShape } from "./json-shape.registry.js";
+import { AVZ_CHECK_ISSUE, translateZodIssues, } from "./zod-issue.translator.js";
+const z = {
+    string: zodString,
+    number: zodNumber,
+    int: zodInt,
+    boolean: zodBoolean,
+    null: zodNull,
+    literal: zodLiteral,
+    enum: zodEnum,
+    strictObject: zodStrictObject,
+    array: zodArray,
+    tuple: zodTuple,
+    record: zodRecord,
+    union: zodUnion,
+    discriminatedUnion: zodDiscriminatedUnion,
+    optional: zodOptional,
+    nullable: zodNullable,
+};
+const compiled = new WeakMap();
+function compiledOf(builder, value) {
+    const found = typeof value === "object" && value !== null
+        ? compiled.get(value)
+        : undefined;
+    if (found === undefined) {
+        throw new TypeError(`AvZ.${builder}: every part of a shape must be built with AvZ (a Zod schema or any other value is not accepted).`);
+    }
+    return found;
+}
+function requiredPart(builder, value) {
+    const part = compiledOf(builder, value);
+    if (part.optionalKey) {
+        throw new TypeError(`AvZ.${builder}: AvZ.optional marks an object key that may be left out; use it only for a field of AvZ.object.`);
+    }
+    return part;
+}
+function build(node, zod, schema, optionalKey = false, checked) {
+    const shape = Object.freeze(Object.assign(Object.create(SHAPE_PROTOTYPE), { kind: node.kind }));
+    const frozenSchema = deepFreeze(schema);
+    compiled.set(shape, {
+        node,
+        zod,
+        schema: frozenSchema,
+        optionalKey,
+        unchecked: checked?.unchecked ?? zod,
+        checks: checked?.checks ?? [],
+    });
+    registerJsonShape(shape, {
+        schema: frozenSchema,
+        validate: (value) => {
+            const result = zod.safeParse(value);
+            return result.success
+                ? []
+                : translateZodIssues(node, value, result.error.issues);
+        },
+    });
+    return shape;
+}
+const CHECKABLE = {
+    string: { target: "string", subject: "string", label: "string" },
+    number: { target: "number", subject: "number", label: "number" },
+    int: { target: "number", subject: "number", label: "int" },
+    array: { target: "list", subject: "number", label: "array" },
+};
+function shapeCheck(kind, target, added) {
+    const data = avzCheckOf(added);
+    if (data === undefined) {
+        throw new TypeError(`AvZ.${kind}(…).check: every check must be built with AvZ (AvZ.maxLength(…), AvZ.email(), …); a Zod check or any other value is not accepted.`);
+    }
+    const fits = target === "string"
+        ? data.check === "string_format" ||
+            data.check === "length_equals" ||
+            ((data.check === "max_length" || data.check === "min_length") &&
+                data.list !== true)
+        : target === "number"
+            ? (data.check === "less_than" ||
+                data.check === "greater_than" ||
+                data.check === "multiple_of") &&
+                typeof data.value === "number"
+            : (data.check === "max_length" || data.check === "min_length") &&
+                data.list === true;
+    if (!fits) {
+        throw new TypeError(`AvZ.${kind}(…).check: the check "${data.check}"${"format" in data ? ` (${data.format})` : ""} does not apply to ${kind === "array" ? "an array's length; an array takes AvZ.minItems and AvZ.maxItems" : `a${kind === "int" ? "n" : ""} ${kind} shape`}.`);
+    }
+    return data;
+}
+function zodChecks(checks, subject) {
+    return (payload) => {
+        for (const check of checks) {
+            if (passesFieldCheck(check, payload.value, subject)) {
+                continue;
+            }
+            const issue = fieldCheckIssue(check, subject, []);
+            payload.issues.push({
+                code: "custom",
+                message: issue.message,
+                input: payload.value,
+                path: [],
+                params: { [AVZ_CHECK_ISSUE]: issue },
+                continue: true,
+            });
+        }
+    };
+}
+function addChecks(...added) {
+    const part = compiledOf("check", this);
+    const kind = part.node.kind;
+    const checkable = CHECKABLE[kind];
+    if (added.length === 0) {
+        return this;
+    }
+    if (checkable === undefined) {
+        throw new TypeError(`AvZ.${kind}(…).check: only a string, number, int or array shape takes checks.`);
+    }
+    const all = [
+        ...part.checks,
+        ...added.map((check) => shapeCheck(kind, checkable.target, check)),
+    ];
+    return build(part.node, part.unchecked.check(zodChecks(all, checkable.subject)), { ...part.schema, checks: all }, part.optionalKey, { unchecked: part.unchecked, checks: all });
+}
+const SHAPE_PROTOTYPE = Object.freeze(Object.assign(Object.create(null), { check: addChecks }));
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        for (const child of Object.values(value)) {
+            deepFreeze(child);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+function isLiteralValue(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)));
+}
+const string = () => build({ kind: "string" }, z.string(), { type: "string" });
+const number = () => build({ kind: "number" }, z.number(), { type: "number" });
+const int = () => build({ kind: "int" }, z.int(), { type: "integer" });
+const boolean = () => build({ kind: "boolean" }, z.boolean(), { type: "boolean" });
+const nullShape = () => build({ kind: "null" }, z.null(), { type: "null" });
+const literal = (value) => {
+    if (!isLiteralValue(value)) {
+        throw new TypeError("AvZ.literal: the value must be a string, a finite number, a boolean or null.");
+    }
+    return build({ kind: "literal", value }, z.literal(value), { const: value });
+};
+const enumShape = (values) => {
+    if (!Array.isArray(values) ||
+        values.length === 0 ||
+        values.some((value) => typeof value !== "string") ||
+        new Set(values).size !== values.length) {
+        throw new TypeError("AvZ.enum: the values must be a non-empty list of distinct strings.");
+    }
+    const copy = [...values];
+    return build({ kind: "enum", values: copy }, z.enum(copy), {
+        type: "string",
+        enum: copy,
+    });
+};
+function contractKeyOrder(keys) {
+    const sorted = [...keys].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+    return Object.keys(Object.fromEntries(sorted.map((key) => [key, true])));
+}
+const object = (fields) => {
+    if (typeof fields !== "object" || fields === null || Array.isArray(fields)) {
+        throw new TypeError("AvZ.object: the fields must be an object of shapes.");
+    }
+    const nodes = {};
+    const zods = {};
+    const properties = {};
+    const required = [];
+    for (const key of Object.keys(fields)) {
+        const part = compiledOf("object", fields[key]);
+        nodes[key] = part.node;
+        properties[key] = part.schema;
+        if (!part.optionalKey) {
+            required.push(key);
+        }
+    }
+    for (const key of contractKeyOrder(Object.keys(fields))) {
+        zods[key] = compiledOf("object", fields[key]).zod;
+    }
+    return build({ kind: "object", fields: nodes }, z.strictObject(zods), {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        additionalProperties: false,
+    });
+};
+const array = (item) => {
+    const part = requiredPart("array", item);
+    return build({ kind: "array", item: part.node }, z.array(part.zod), {
+        type: "array",
+        items: part.schema,
+    });
+};
+const tuple = (items) => {
+    if (!Array.isArray(items) || items.length === 0) {
+        throw new TypeError("AvZ.tuple: the items must be a non-empty list of shapes.");
+    }
+    const parts = items.map((item) => requiredPart("tuple", item));
+    return build({ kind: "tuple", items: parts.map((part) => part.node) }, z.tuple(parts.map((part) => part.zod)), {
+        type: "array",
+        prefixItems: parts.map((part) => part.schema),
+        items: false,
+        minItems: parts.length,
+        maxItems: parts.length,
+    });
+};
+const record = (key, value) => {
+    const keyPart = requiredPart("record", key);
+    const valuePart = requiredPart("record", value);
+    const keyNode = keyPart.node;
+    const keys = keyNode.kind === "enum"
+        ? keyNode.values
+        : keyNode.kind === "literal" && typeof keyNode.value === "string"
+            ? [keyNode.value]
+            : keyNode.kind === "string"
+                ? undefined
+                : null;
+    if (keys === null) {
+        throw new TypeError("AvZ.record: the key must be AvZ.string(), AvZ.enum([...]) or a string AvZ.literal(...).");
+    }
+    const schema = keys === undefined
+        ? { type: "object", additionalProperties: valuePart.schema }
+        : {
+            type: "object",
+            properties: Object.fromEntries(keys.map((entry) => [entry, valuePart.schema])),
+            required: [...keys],
+            additionalProperties: false,
+        };
+    return build({ kind: "record", value: valuePart.node }, z.record(keyNode.kind === "enum"
+        ? z.enum(contractKeyOrder(keyNode.values))
+        : keyPart.zod, valuePart.zod), schema);
+};
+const union = (options) => {
+    if (!Array.isArray(options) || options.length < 2) {
+        throw new TypeError("AvZ.union: the options must be a list of at least two shapes.");
+    }
+    const parts = options.map((option) => requiredPart("union", option));
+    return build({ kind: "union", options: parts.map((part) => part.node) }, z.union(parts.map((part) => part.zod)), {
+        anyOf: parts.map((part) => part.schema),
+    });
+};
+const discriminatedUnion = (discriminator, options) => {
+    if (typeof discriminator !== "string" ||
+        !Array.isArray(options) ||
+        options.length === 0) {
+        throw new TypeError("AvZ.discriminatedUnion: give the discriminator key and a non-empty list of object shapes.");
+    }
+    const parts = options.map((option) => requiredPart("discriminatedUnion", option));
+    const tags = new Map();
+    parts.forEach((part, index) => {
+        const tag = part.node.kind === "object" ? part.node.fields[discriminator] : undefined;
+        const values = tag?.kind === "literal"
+            ? [tag.value]
+            : tag?.kind === "enum"
+                ? tag.values
+                : undefined;
+        if (values === undefined) {
+            throw new TypeError(`AvZ.discriminatedUnion: option ${index} must be an AvZ.object whose "${discriminator}" is an AvZ.literal or an AvZ.enum.`);
+        }
+        for (const value of values) {
+            if (tags.has(value)) {
+                throw new TypeError(`AvZ.discriminatedUnion: options ${tags.get(value)} and ${index} both match "${discriminator}" ${JSON.stringify(value)}.`);
+            }
+            tags.set(value, index);
+        }
+    });
+    return build({
+        kind: "discriminatedUnion",
+        discriminator,
+        options: parts.map((part) => part.node),
+    }, z.discriminatedUnion(discriminator, parts.map((part) => part.zod)), {
+        oneOf: parts.map((part) => part.schema),
+    });
+};
+const optional = (inner) => {
+    const part = compiledOf("optional", inner);
+    return build({ kind: "optional", inner: part.node }, z.optional(part.zod), part.schema, true);
+};
+const nullable = (inner) => {
+    const part = compiledOf("nullable", inner);
+    return build({ kind: "nullable", inner: part.node }, z.nullable(part.zod), { anyOf: [part.schema, { type: "null" }] }, part.optionalKey);
+};
+export class AvZ {
+    constructor() { }
+    static string = string;
+    static number = number;
+    static int = int;
+    static boolean = boolean;
+    static null = nullShape;
+    static literal = literal;
+    static enum = enumShape;
+    static object = object;
+    static array = array;
+    static tuple = tuple;
+    static record = record;
+    static union = union;
+    static discriminatedUnion = discriminatedUnion;
+    static optional = optional;
+    static nullable = nullable;
+    static lt = checks.lt;
+    static lte = checks.lte;
+    static gt = checks.gt;
+    static gte = checks.gte;
+    static positive = checks.positive;
+    static nonnegative = checks.nonnegative;
+    static negative = checks.negative;
+    static nonpositive = checks.nonpositive;
+    static multipleOf = checks.multipleOf;
+    static maxLength = checks.maxLength;
+    static minLength = checks.minLength;
+    static length = checks.length;
+    static maxItems = checks.maxItems;
+    static minItems = checks.minItems;
+    static maxSize = checks.maxSize;
+    static minSize = checks.minSize;
+    static size = checks.size;
+    static regex = checks.regex;
+    static includes = checks.includes;
+    static startsWith = checks.startsWith;
+    static endsWith = checks.endsWith;
+    static lowercase = checks.lowercase;
+    static uppercase = checks.uppercase;
+    static email = checks.email;
+    static url = checks.url;
+    static emoji = checks.emoji;
+    static uuid = checks.uuid;
+    static guid = checks.guid;
+    static nanoid = checks.nanoid;
+    static cuid = checks.cuid;
+    static cuid2 = checks.cuid2;
+    static ulid = checks.ulid;
+    static xid = checks.xid;
+    static ksuid = checks.ksuid;
+    static ipv4 = checks.ipv4;
+    static ipv6 = checks.ipv6;
+    static cidrv4 = checks.cidrv4;
+    static cidrv6 = checks.cidrv6;
+    static base64 = checks.base64;
+    static base64url = checks.base64url;
+    static jsonString = checks.jsonString;
+    static e164 = checks.e164;
+    static creditCard = checks.creditCard;
+    static iban = checks.iban;
+    static jwt = checks.jwt;
+    static iso = checks.iso;
+}

package/dist/avz/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@aventara/core/avz` — `AvZ`, which builds the TypeScript shape of a Json
+ * field, and the types of the shapes it builds.
+ */
+export type { ShapedJsonSchema as AvZShapedSchema } from "../contracts/json-shape.js";
+export type { AvZNullable, AvZObject, AvZOptional, AvZShape } from "./avz.js";
+export { AvZ } from "./avz.js";

package/dist/avz/index.js

@@ -0,0 +1 @@
+export { AvZ } from "./avz.js";

package/dist/avz/json-shape.registry.d.ts

@@ -0,0 +1,22 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
+import type { JsonSchema } from "../contracts/json-shape.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+/** What core may do with a Json Shape: read its Contract form, check a value. */
+export type JsonShapeRuntime = {
+    /** The shape's Contract form. */
+    readonly schema: JsonSchema;
+    /**
+     * Every way `value` — a JSON value — does not conform, each at its path inside
+     * the value; none when it conforms.
+     */
+    readonly validate: (value: unknown) => readonly AvValidationIssue[];
+};
+/** Records `shape` as a Json Shape. For `@aventara/core/avz` only. */
+export declare function registerJsonShape(shape: object, runtime: JsonShapeRuntime): void;
+/** The Json Shape `value` is, or `undefined` when `AvZ` did not build it. */
+export declare function jsonShapeOf(value: unknown): JsonShapeRuntime | undefined;
+/** Binds a compiled Contract field to the shape it enforces. Compiler only. */
+export declare function bindShapedField(field: AvScalarField<AvContract>, shape: JsonShapeRuntime): void;
+/** The shape a compiled Contract field enforces, or `undefined`. */
+export declare function shapeOfField(field: AvScalarField<AvContract>): JsonShapeRuntime | undefined;

package/dist/avz/json-shape.registry.js

@@ -0,0 +1,16 @@
+const shapes = new WeakMap();
+const fields = new WeakMap();
+export function registerJsonShape(shape, runtime) {
+    shapes.set(shape, runtime);
+}
+export function jsonShapeOf(value) {
+    return typeof value === "object" && value !== null
+        ? shapes.get(value)
+        : undefined;
+}
+export function bindShapedField(field, shape) {
+    fields.set(field, shape);
+}
+export function shapeOfField(field) {
+    return fields.get(field);
+}

package/dist/avz/zod-issue.translator.d.ts

@@ -0,0 +1,57 @@
+import type { JsonSchemaPrimitive } from "../contracts/json-shape.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+/**
+ * The key a shape node's failed check travels under in its Zod issue's `params`:
+ * the finished Aventara issue, path relative to the node (`avz.ts`).
+ */
+export declare const AVZ_CHECK_ISSUE = "aventara.check";
+/** A shape as the translator reads it: its form and its parts, no Zod. */
+export type AvZNode = {
+    readonly kind: "string" | "number" | "int" | "boolean" | "null";
+} | {
+    readonly kind: "literal";
+    readonly value: JsonSchemaPrimitive;
+} | {
+    readonly kind: "enum";
+    readonly values: readonly string[];
+} | {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, AvZNode>>;
+} | {
+    readonly kind: "array";
+    readonly item: AvZNode;
+} | {
+    readonly kind: "tuple";
+    readonly items: readonly AvZNode[];
+} | {
+    readonly kind: "record";
+    readonly value: AvZNode;
+} | {
+    readonly kind: "union";
+    readonly options: readonly AvZNode[];
+} | {
+    readonly kind: "discriminatedUnion";
+    readonly discriminator: string;
+    readonly options: readonly AvZNode[];
+} | {
+    readonly kind: "optional" | "nullable";
+    readonly inner: AvZNode;
+};
+/** The members of a Zod issue this module reads. */
+type ZodIssueLike = {
+    readonly code: string;
+    readonly path: readonly PropertyKey[];
+    readonly origin?: string;
+    readonly keys?: readonly string[];
+    readonly note?: string;
+    readonly options?: readonly unknown[];
+    readonly minimum?: unknown;
+    readonly maximum?: unknown;
+    readonly params?: Readonly<Record<string, unknown>>;
+};
+/**
+ * Aventara's issues for the ones Zod raised judging `value` against the shape
+ * `root`: each at its path inside the value, in Zod's order.
+ */
+export declare function translateZodIssues(root: AvZNode, value: unknown, issues: readonly ZodIssueLike[]): readonly AvValidationIssue[];
+export {};

package/dist/avz/zod-issue.translator.js

@@ -0,0 +1,149 @@
+export const AVZ_CHECK_ISSUE = "aventara.check";
+const MISSING = Symbol("missing");
+function issue(code, path, message) {
+    return { code, path, message };
+}
+function valueAt(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (typeof current !== "object" ||
+            current === null ||
+            !Object.hasOwn(current, segment)) {
+            return MISSING;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function unwrap(node) {
+    return node.kind === "optional" || node.kind === "nullable"
+        ? unwrap(node.inner)
+        : node;
+}
+function selectedOption(node, value) {
+    const tag = valueAt(value, [node.discriminator]);
+    return node.options.find((option) => {
+        const field = option.kind === "object" ? option.fields[node.discriminator] : undefined;
+        const inner = field === undefined ? undefined : unwrap(field);
+        return inner?.kind === "literal"
+            ? Object.is(inner.value, tag)
+            : inner?.kind === "enum" && inner.values.includes(tag);
+    });
+}
+function nodeAt(root, value, path) {
+    let node = root;
+    let current = value;
+    for (const segment of path) {
+        node = node === undefined ? undefined : unwrap(node);
+        if (node?.kind === "discriminatedUnion") {
+            node = selectedOption(node, current);
+        }
+        switch (node?.kind) {
+            case "object":
+                node = node.fields[segment];
+                break;
+            case "array":
+                node = node.item;
+                break;
+            case "tuple":
+                node = typeof segment === "number" ? node.items[segment] : undefined;
+                break;
+            case "record":
+                node = node.value;
+                break;
+            default:
+                return undefined;
+        }
+        current = valueAt(current, [segment]);
+    }
+    return node;
+}
+function describe(node) {
+    if (node === undefined) {
+        return "the field's shape";
+    }
+    switch (node.kind) {
+        case "string":
+            return "a string";
+        case "number":
+            return "a number";
+        case "int":
+            return "an integer";
+        case "boolean":
+            return "a boolean";
+        case "null":
+            return "null";
+        case "literal":
+            return JSON.stringify(node.value);
+        case "enum":
+            return `one of ${node.values.map((value) => JSON.stringify(value)).join(", ")}`;
+        case "object":
+        case "record":
+            return "an object";
+        case "array":
+            return "a list";
+        case "tuple":
+            return `a list of exactly ${node.items.length} entries`;
+        case "union":
+        case "discriminatedUnion":
+            return [...new Set(node.options.map(describe))].join(" or ");
+        case "optional":
+            return describe(node.inner);
+        case "nullable":
+            return `${describe(node.inner)} or null`;
+    }
+}
+function pathOf(path) {
+    return path.map((segment) => typeof segment === "symbol" ? String(segment) : segment);
+}
+function translateOne(root, value, zodIssue) {
+    const path = pathOf(zodIssue.path);
+    const node = nodeAt(root, value, path);
+    const absent = path.length > 0 && valueAt(value, path) === MISSING;
+    if (absent &&
+        (zodIssue.code === "invalid_type" || zodIssue.code === "invalid_value")) {
+        return [issue("V1000", path, "Required value missing.")];
+    }
+    switch (zodIssue.code) {
+        case "custom": {
+            const checked = zodIssue.params?.[AVZ_CHECK_ISSUE];
+            return checked === undefined
+                ? [issue("V1001", path, `Value does not match ${describe(node)}.`)]
+                : [{ ...checked, path: [...path, ...(checked.path ?? [])] }];
+        }
+        case "invalid_type":
+            return [issue("V1001", path, `Value must be ${describe(node)}.`)];
+        case "invalid_value":
+            return [issue("V1002", path, `Value must be ${describe(node)}.`)];
+        case "unrecognized_keys":
+            return (zodIssue.keys ?? []).map((key) => issue("V1005", [...path, key], "Key is not part of the shape."));
+        case "invalid_union": {
+            if (zodIssue.note !== undefined && Array.isArray(zodIssue.options)) {
+                if (absent) {
+                    return [issue("V1000", path, "Required value missing.")];
+                }
+                const allowed = zodIssue.options
+                    .map((option) => JSON.stringify(option))
+                    .join(", ");
+                return [issue("V1002", path, `Value must be one of ${allowed}.`)];
+            }
+            return [issue("V1001", path, `Value must be ${describe(node)}.`)];
+        }
+        case "too_big":
+        case "too_small":
+            if (zodIssue.origin === "array" && node !== undefined) {
+                return [issue("V1001", path, `Value must be ${describe(node)}.`)];
+            }
+            if (zodIssue.origin === "int" || zodIssue.origin === "number") {
+                return [
+                    issue("V1004", path, "Value must be a safe integer (between -9007199254740991 and 9007199254740991)."),
+                ];
+            }
+            return [issue("V1001", path, `Value does not match ${describe(node)}.`)];
+        default:
+            return [issue("V1001", path, `Value does not match ${describe(node)}.`)];
+    }
+}
+export function translateZodIssues(root, value, issues) {
+    return issues.flatMap((zodIssue) => translateOne(root, value, zodIssue));
+}

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

@@ -1,15 +1,47 @@
-/** Codes of {@link ContractCompilerDiagnostic}. */
-export type ContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMPILER_UNKNOWN_FIELD" | "COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED" | "COMPILER_INCOMPLETE_FIELD" | "COMPILER_STRUCTURAL_FIELD_OVERRIDE" | "COMPILER_MISSING_SCALAR" | "COMPILER_MISSING_ENUM" | "COMPILER_DANGLING_RELATION" | "COMPILER_UNAVAILABLE_OPERATION" | "COMPILER_UNAVAILABLE_CAPABILITY" | "COMPILER_INVALID_LIFECYCLE" | "COMPILER_MISSING_READ_BEHAVIOR" | "COMPILER_INVALID_BEHAVIOR_DEPENDENCY"
+/** Codes of {@link AvContractCompilerDiagnostic}. */
+export type AvContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMPILER_UNKNOWN_FIELD" | "COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED" | "COMPILER_INCOMPLETE_FIELD" | "COMPILER_STRUCTURAL_FIELD_OVERRIDE" | "COMPILER_MISSING_SCALAR" | "COMPILER_MISSING_ENUM" | "COMPILER_DANGLING_RELATION" | "COMPILER_UNAVAILABLE_OPERATION" | "COMPILER_UNAVAILABLE_CAPABILITY" | "COMPILER_INVALID_LIFECYCLE" | "COMPILER_MISSING_READ_COMPUTE" | "COMPILER_INVALID_COMPUTE_DEPENDENCY"
+/**
+ * A Resource name the adapter model holds starts with `$`, which is reserved
+ * for the framework's own names (`ctx.$sql`, `$ref`, …).
+ */
+ | "COMPILER_RESERVED_RESOURCE_NAME"
+/**
+ * A layer exposes a unique operation variant (`find.unique`, `update.unique`,
+ * `delete.unique`, `upsert.unique`) and no complete identifier of its Resource:
+ * a Pick that did not pick one, or an Omit that hid every one.
+ */
+ | "COMPILER_MISSING_IDENTIFIER"
+/**
+ * A layer still creates a Resource (a create or upsert variant, or a nested
+ * create through a parent's relation) and leaves one of its create
+ * requirements unwritable on create: a required field hidden or with its
+ * `create` capability exempted and no `compute.create`, or a required relation
+ * not writable on create with a reference field neither writable nor computed.
+ */
+ | "COMPILER_HIDDEN_REQUIRED_FIELD"
+/**
+ * A field validator cannot apply: it is not a check built with `AvZ`, it does
+ * not fit the field's type (`AvZ.maxLength` on an `int` field, `AvZ.maxItems`
+ * on a field that is not a list), or the field is a relation or a Json field
+ * (whose checks are in its shape).
+ */
+ | "COMPILER_INVALID_VALIDATOR"
+/**
+ * A field's `json` shape cannot apply: the field is not a Json field the
+ * adapter discovered, the value is not a shape built with `AvZ`, or the shape
+ * admits `null` or absence at its top level.
+ */
+ | "COMPILER_INVALID_JSON_SHAPE"
 /**
  * The finished, hashed client projection is not a structurally valid
- * `ClientContract`. A framework-bug guard: the server never serves what its own
+ * `AvContractClient`. A framework-bug guard: the server never serves what its own
  * generator would refuse. `path` is the JSONPath inside the ClientContract
  * (`$.enums.status.values[1]`).
  */
  | "COMPILER_INVALID_CLIENT_CONTRACT";
 /** One reason a configuration could not be compiled into Contracts. */
-export type ContractCompilerDiagnostic = {
-    readonly code: ContractCompilerDiagnosticCode;
+export type AvContractCompilerDiagnostic = {
+    readonly code: AvContractCompilerDiagnosticCode;
     readonly path: string;
     readonly message: string;
 };