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

package/dist/avz/avz.d.ts

@@ -0,0 +1,203 @@
+import type { JsonSchemaPrimitive, JsonShape, JsonShapeValue } from "../contracts/json-shape.js";
+import { type AvZCheck } from "./avz-check.registry.js";
+/** The forms a Json Shape takes. */
+export type AvZKind = "string" | "number" | "int" | "boolean" | "null" | "literal" | "enum" | "object" | "array" | "tuple" | "record" | "union" | "discriminatedUnion" | "optional" | "nullable";
+/** The checks a shape of one kind takes: a string's, a number's, a list's length; else none. */
+type AvZShapeCheck<Kind extends AvZKind> = Kind extends "string" ? AvZCheck<"string"> : Kind extends "number" | "int" ? AvZCheck<"number"> : Kind extends "array" ? AvZCheck<"list"> : never;
+/**
+ * A Json Shape built with {@link AvZ}: opaque, its `kind` and `check` its only
+ * members. Its TypeScript type is `AvZ.infer<typeof shape>`.
+ */
+export interface AvZShape<Value = unknown, Kind extends AvZKind = AvZKind> extends JsonShape<Value> {
+    readonly kind: Kind;
+    /**
+     * The same shape with `checks` added: a string takes length, pattern and
+     * format checks, a number or an integer takes bounds and `multipleOf`, an
+     * array takes `AvZ.minItems`/`AvZ.maxItems`. No other shape takes any.
+     */
+    check(...checks: readonly AvZShapeCheck<Kind>[]): this;
+}
+/** The fields of an object shape, by key. */
+export type AvZFields = {
+    readonly [key: string]: AvZShape;
+};
+declare const avzOptionalKey: unique symbol;
+/** Marks a shape whose object key may be left out. Type-level only. */
+interface AvZOptionalKey {
+    readonly [avzOptionalKey]: true;
+}
+type FieldKeysOptional<Fields extends AvZFields> = {
+    [Key in keyof Fields]: Fields[Key] extends AvZOptionalKey ? Key : never;
+}[keyof Fields];
+type Flatten<T> = {
+    [Key in keyof T]: T[Key];
+} & {};
+/** The value an object shape describes. */
+type AvZObjectValue<Fields extends AvZFields> = ObjectValueOf<Fields, FieldKeysOptional<Fields>>;
+type ObjectValueOf<Fields extends AvZFields, Optional extends keyof Fields> = Flatten<{
+    -readonly [Key in Exclude<keyof Fields, Optional>]: JsonShapeValue<Fields[Key]>;
+} & {
+    -readonly [Key in Optional]?: JsonShapeValue<Fields[Key]>;
+}>;
+/** An object shape: closed, so a key it does not declare is refused. */
+export interface AvZObject<Fields extends AvZFields = AvZFields> extends AvZShape<AvZObjectValue<Fields>, "object"> {
+    readonly fields: Fields;
+}
+/** A shape whose object key may be left out. */
+export interface AvZOptional<Inner extends AvZShape = AvZShape> extends AvZShape<JsonShapeValue<Inner> | undefined, "optional">, AvZOptionalKey {
+}
+/** A shape that also admits `null`. */
+export type AvZNullable<Inner extends AvZShape = AvZShape> = AvZShape<JsonShapeValue<Inner> | null, "nullable"> & (Inner extends AvZOptionalKey ? AvZOptionalKey : unknown);
+/** A value a literal shape may hold. */
+export type AvZLiteralValue = JsonSchemaPrimitive;
+/** What keys a record shape: any string, an enum's values or one literal. */
+type AvZRecordKey = AvZShape<string, "string"> | AvZShape<string, "enum"> | AvZShape<string, "literal">;
+/** An option of a discriminated union: an object whose discriminator is a literal or an enum. */
+type AvZDiscriminable<Discriminator extends string> = AvZObject<{
+    readonly [Key in Discriminator]: AvZShape<AvZLiteralValue, "literal"> | AvZShape<string, "enum">;
+} & AvZFields>;
+type TupleValue<Items extends readonly AvZShape[]> = {
+    -readonly [Index in keyof Items]: JsonShapeValue<Items[Index]>;
+};
+/**
+ * Builds Json Shapes (the type of a Json field, declared at
+ * `resources.<Resource>.fields.<field>.definition.json`) and checks in zod's
+ * vocabulary: a field's `validators`, and a shape node's `check(...)`. No
+ * refinements, transforms or defaults. Objects are closed: a key the shape does
+ * not declare is refused.
+ */
+export declare class AvZ {
+    private constructor();
+    /** Any string. */
+    static readonly string: () => AvZShape<string, "string">;
+    /** Any finite number. */
+    static readonly number: () => AvZShape<number, "number">;
+    /** An integer (a safe one). */
+    static readonly int: () => AvZShape<number, "int">;
+    /** `true` or `false`. */
+    static readonly boolean: () => AvZShape<boolean, "boolean">;
+    /** `null`. */
+    static readonly null: () => AvZShape<null, "null">;
+    /** Exactly `value`: a string, a finite number, a boolean or `null`. */
+    static readonly literal: <const Value extends AvZLiteralValue>(value: Value) => AvZShape<Value, "literal">;
+    /** One of `values`. */
+    static readonly enum: <const Values extends readonly [string, ...string[]]>(values: Values) => AvZShape<Values[number], "enum">;
+    /** An object with exactly these keys; `AvZ.optional` marks one that may be left out. */
+    static readonly object: <const Fields extends AvZFields>(fields: Fields) => AvZObject<Fields>;
+    /** A list of `item`s. */
+    static readonly array: <Item extends AvZShape>(item: Item) => AvZShape<JsonShapeValue<Item>[], "array">;
+    /** A list of exactly these items, in order. */
+    static readonly tuple: <const Items extends readonly [AvZShape, ...AvZShape[]]>(items: Items) => AvZShape<TupleValue<Items>, "tuple">;
+    /** An object of `value`s, keyed by any string, an enum's values or a literal. */
+    static readonly record: <Key extends AvZRecordKey, Value extends AvZShape>(key: Key, value: Value) => AvZShape<Record<JsonShapeValue<Key>, JsonShapeValue<Value>>, "record">;
+    /** Any one of `options`. */
+    static readonly union: <const Options extends readonly [AvZShape, AvZShape, ...AvZShape[]]>(options: Options) => AvZShape<JsonShapeValue<Options[number]>, "union">;
+    /** One of `options`, told apart by the literal or enum at `discriminator`. */
+    static readonly discriminatedUnion: <Discriminator extends string, const Options extends readonly [AvZDiscriminable<Discriminator>, ...AvZDiscriminable<Discriminator>[]]>(discriminator: Discriminator, options: Options) => AvZShape<JsonShapeValue<Options[number]>, "discriminatedUnion">;
+    /** An object key that may be left out. */
+    static readonly optional: <Inner extends AvZShape>(inner: Inner) => AvZOptional<Inner>;
+    /** `inner`, or `null`. */
+    static readonly nullable: <Inner extends AvZShape>(inner: Inner) => AvZNullable<Inner>;
+    /** A value below `value` (a number, a bigint or a `Date`). */
+    static readonly lt: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A value at most `value` (a number, a bigint or a `Date`). */
+    static readonly lte: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A value above `value` (a number, a bigint or a `Date`). */
+    static readonly gt: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A value at least `value` (a number, a bigint or a `Date`). */
+    static readonly gte: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A value above zero. */
+    static readonly positive: () => AvZCheck<"number" | "bigint" | "decimal">;
+    /** A value at least zero. */
+    static readonly nonnegative: () => AvZCheck<"number" | "bigint" | "decimal">;
+    /** A value below zero. */
+    static readonly negative: () => AvZCheck<"number" | "bigint" | "decimal">;
+    /** A value at most zero. */
+    static readonly nonpositive: () => AvZCheck<"number" | "bigint" | "decimal">;
+    /** A multiple of `value`. */
+    static readonly multipleOf: <const Value extends number | bigint>(value: Value) => AvZCheck<Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A string of at most `maximum` characters; on a list field, each entry. */
+    static readonly maxLength: (maximum: number) => AvZCheck<"string">;
+    /** A string of at least `minimum` characters; on a list field, each entry. */
+    static readonly minLength: (minimum: number) => AvZCheck<"string">;
+    /** A string of exactly `length` characters; on a list field, each entry. */
+    static readonly length: (exact: number) => AvZCheck<"string">;
+    /** A list of at most `maximum` entries: a list field, or an array shape. */
+    static readonly maxItems: (maximum: number) => AvZCheck<"list">;
+    /** A list of at least `minimum` entries: a list field, or an array shape. */
+    static readonly minItems: (minimum: number) => AvZCheck<"list">;
+    /** Bytes of at most `maximum` in length. */
+    static readonly maxSize: (maximum: number) => AvZCheck<"bytes">;
+    /** Bytes of at least `minimum` in length. */
+    static readonly minSize: (minimum: number) => AvZCheck<"bytes">;
+    /** Bytes of exactly `size` in length. */
+    static readonly size: (exact: number) => AvZCheck<"bytes">;
+    /** A string the pattern matches: a JavaScript regular expression, flags included. */
+    static readonly regex: (pattern: RegExp) => AvZCheck<"string">;
+    /** A string containing `value`. */
+    static readonly includes: (value: string) => AvZCheck<"string">;
+    /** A string starting with `prefix`. */
+    static readonly startsWith: (prefix: string) => AvZCheck<"string">;
+    /** A string ending with `suffix`. */
+    static readonly endsWith: (suffix: string) => AvZCheck<"string">;
+    /** A string with no uppercase letter. */
+    static readonly lowercase: () => AvZCheck<"string">;
+    /** A string with no lowercase letter. */
+    static readonly uppercase: () => AvZCheck<"string">;
+    /** An email address. */
+    static readonly email: () => AvZCheck<"string">;
+    /** A URL. */
+    static readonly url: () => AvZCheck<"string">;
+    /** Emoji only. */
+    static readonly emoji: () => AvZCheck<"string">;
+    /** A UUID (any version). */
+    static readonly uuid: () => AvZCheck<"string">;
+    /** A GUID: any 8-4-4-4-12 hex identifier. */
+    static readonly guid: () => AvZCheck<"string">;
+    /** A Nano ID. */
+    static readonly nanoid: () => AvZCheck<"string">;
+    /** A CUID. */
+    static readonly cuid: () => AvZCheck<"string">;
+    /** A CUID2. */
+    static readonly cuid2: () => AvZCheck<"string">;
+    /** A ULID. */
+    static readonly ulid: () => AvZCheck<"string">;
+    /** An XID. */
+    static readonly xid: () => AvZCheck<"string">;
+    /** A KSUID. */
+    static readonly ksuid: () => AvZCheck<"string">;
+    /** An IPv4 address. */
+    static readonly ipv4: () => AvZCheck<"string">;
+    /** An IPv6 address. */
+    static readonly ipv6: () => AvZCheck<"string">;
+    /** An IPv4 CIDR block. */
+    static readonly cidrv4: () => AvZCheck<"string">;
+    /** An IPv6 CIDR block. */
+    static readonly cidrv6: () => AvZCheck<"string">;
+    /** Base64. */
+    static readonly base64: () => AvZCheck<"string">;
+    /** Base64url. */
+    static readonly base64url: () => AvZCheck<"string">;
+    /** A string that parses as JSON (zod's `json_string` format). */
+    static readonly jsonString: () => AvZCheck<"string">;
+    /** An E.164 phone number. */
+    static readonly e164: () => AvZCheck<"string">;
+    /** A credit card number (Luhn-checked). */
+    static readonly creditCard: () => AvZCheck<"string">;
+    /** An IBAN (checksum-checked). */
+    static readonly iban: () => AvZCheck<"string">;
+    /** A JWT. */
+    static readonly jwt: () => AvZCheck<"string">;
+    /** ISO 8601: `datetime`, `date`, `time` and `duration`. */
+    static readonly iso: Readonly<{
+        datetime: () => AvZCheck<"string">;
+        date: () => AvZCheck<"string">;
+        time: () => AvZCheck<"string">;
+        duration: () => AvZCheck<"string">;
+    }>;
+}
+export declare namespace AvZ {
+    /** The TypeScript type a shape describes. */
+    type infer<Shape extends JsonShape> = JsonShapeValue<Shape>;
+}
+export {};

package/dist/{json → avz}/avz.js

@@ -1,8 +1,26 @@
-import * as zodMini from "zod/mini";
+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 { translateZodIssues } from "./zod-issue.translator.js";
-const z = zodMini;
-const SHAPE_PROTOTYPE = Object.freeze(Object.create(null));
+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
@@ -20,10 +38,17 @@ function requiredPart(builder, value) {
     }
     return part;
 }
-function build(node, zod, schema, optionalKey = false) {
+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 });
+    compiled.set(shape, {
+        node,
+        zod,
+        schema: frozenSchema,
+        optionalKey,
+        unchecked: checked?.unchecked ?? zod,
+        checks: checked?.checks ?? [],
+    });
     registerJsonShape(shape, {
         schema: frozenSchema,
         validate: (value) => {
@@ -35,6 +60,69 @@ function build(node, zod, schema, optionalKey = false) {
     });
     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)) {
@@ -74,6 +162,10 @@ const enumShape = (values) => {
         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.");
@@ -85,12 +177,14 @@ const object = (fields) => {
     for (const key of Object.keys(fields)) {
         const part = compiledOf("object", fields[key]);
         nodes[key] = part.node;
-        zods[key] = part.zod;
         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,
@@ -140,7 +234,9 @@ const record = (key, value) => {
             required: [...keys],
             additionalProperties: false,
         };
-    return build({ kind: "record", value: valuePart.node }, z.record(keyPart.zod, valuePart.zod), schema);
+    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) {
@@ -209,4 +305,50 @@ export class AvZ {
     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/{json → avz}/index.d.ts

@@ -1,6 +1,7 @@
 /**
- * `@aventara/core/json` — `AvZ`, which builds the TypeScript shape of a Json
+ * `@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/{json → avz}/json-shape.registry.d.ts

@@ -1,7 +1,7 @@
-import type { Contract } from "../contracts/contract.js";
-import type { ScalarField } from "../contracts/field.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
 import type { JsonSchema } from "../contracts/json-shape.js";
-import type { ValidationIssue } from "../operations/validation-code.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. */
@@ -10,13 +10,13 @@ export type JsonShapeRuntime = {
      * 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 ValidationIssue[];
+    readonly validate: (value: unknown) => readonly AvValidationIssue[];
 };
-/** Records `shape` as a Json Shape. For `@aventara/core/json` only. */
+/** 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: ScalarField<Contract>, shape: JsonShapeRuntime): void;
+export declare function bindShapedField(field: AvScalarField<AvContract>, shape: JsonShapeRuntime): void;
 /** The shape a compiled Contract field enforces, or `undefined`. */
-export declare function shapeOfField(field: ScalarField<Contract>): JsonShapeRuntime | undefined;
+export declare function shapeOfField(field: AvScalarField<AvContract>): JsonShapeRuntime | undefined;

package/dist/{json → avz}/zod-issue.translator.d.ts

@@ -1,5 +1,10 @@
 import type { JsonSchemaPrimitive } from "../contracts/json-shape.js";
-import type { ValidationIssue } from "../operations/validation-code.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";
@@ -42,10 +47,11 @@ type ZodIssueLike = {
     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 ValidationIssue[];
+export declare function translateZodIssues(root: AvZNode, value: unknown, issues: readonly ZodIssueLike[]): readonly AvValidationIssue[];
 export {};

package/dist/{json → avz}/zod-issue.translator.js

@@ -1,3 +1,4 @@
+export const AVZ_CHECK_ISSUE = "aventara.check";
 const MISSING = Symbol("missing");
 function issue(code, path, message) {
     return { code, path, message };
@@ -104,6 +105,12 @@ function translateOne(root, value, zodIssue) {
         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":

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

@@ -1,5 +1,31 @@
-/** 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
@@ -8,14 +34,14 @@ export type ContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMP
  | "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;
 };

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.",
+    },
+};