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

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

@@ -1,29 +1,51 @@
-import type { RelationFieldCapabilities, ScalarFieldCapabilities, ScalarFormat } from "../contracts/field.js";
-import type { LifecycleTrait } from "../contracts/lifecycle-trait.js";
-import type { AdapterModel } from "./adapter-model.js";
+import type { AvRelationFieldCapabilities, AvScalarFieldCapabilities, AvScalarFormat } from "../contracts/field.js";
+import type { AvLifecycleTrait } from "../contracts/lifecycle-trait.js";
+import type { AvAdapterModel } from "./adapter-model.js";
 /** Provider-observable lifecycle facts available during adapter discovery. */
-export type AdapterLifecycleTrait = Extract<LifecycleTrait, "DEFAULTED" | "GENERATED_ON_CREATE" | "GENERATED_ON_UPDATE">;
+export type AvAdapterLifecycleTrait = Extract<AvLifecycleTrait, "DEFAULTED" | "GENERATED_ON_CREATE" | "GENERATED_ON_UPDATE">;
 /** Scalar-shaped provider field expressed only in Aventara vocabulary. */
-export type AdapterScalarField<M extends AdapterModel> = {
+export type AvAdapterScalarField<M extends AvAdapterModel> = {
     readonly kind: "scalar";
     readonly type: {
         readonly scalar: Extract<keyof M["scalars"], string>;
     } | {
         readonly enum: Extract<keyof M["enums"], string>;
     };
-    readonly format?: ScalarFormat;
+    readonly format?: AvScalarFormat;
     readonly nullable: boolean;
     readonly list: boolean;
-    readonly lifecycle: readonly AdapterLifecycleTrait[];
-    readonly capabilities: ScalarFieldCapabilities;
+    readonly lifecycle: readonly AvAdapterLifecycleTrait[];
+    readonly capabilities: AvScalarFieldCapabilities;
 };
 /** A discovered relation field; the `target` Resource describes the related row. */
-export type AdapterRelationField<M extends AdapterModel> = {
+export type AvAdapterRelationField<M extends AvAdapterModel> = {
     readonly kind: "relation";
     readonly target: Extract<keyof M["resources"], string>;
     readonly cardinality: "one" | "many";
     readonly nullable: boolean;
-    readonly capabilities: RelationFieldCapabilities;
+    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[]];
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in
+     * the same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`, so `Post.authorId` holds `User.id`). Stated only
+     * beside `referenceFields`, with as many entries; absent on the end that
+     * holds no reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
 };
 /** One field the adapter discovered: a scalar or a relation. */
-export type AdapterField<M extends AdapterModel> = AdapterScalarField<M> | AdapterRelationField<M>;
+export type AvAdapterField<M extends AvAdapterModel> = AvAdapterScalarField<M> | AvAdapterRelationField<M>;

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

@@ -1,7 +1,7 @@
-import type { AdapterField } from "./adapter-field.js";
-import type { AdapterModel } from "./adapter-model.js";
+import type { AvAdapterField } from "./adapter-field.js";
+import type { AvAdapterModel } from "./adapter-model.js";
 /** Keys of `TFields` whose discovered field can be scalar-shaped. */
-export type AdapterScalarFieldKey<TFields extends Readonly<Record<string, AdapterField<AdapterModel>>>> = Extract<{
+export type AvAdapterScalarFieldKey<TFields extends Readonly<Record<string, AvAdapterField<AvAdapterModel>>>> = Extract<{
     [K in keyof TFields]: [
         Extract<TFields[K], {
             readonly kind: "scalar";
@@ -9,7 +9,16 @@ export type AdapterScalarFieldKey<TFields extends Readonly<Record<string, Adapte
     ] extends [never] ? never : K;
 }[keyof TFields], string>;
 /** Non-empty scalar-field tuple discovered as provider uniqueness. */
-export type AdapterIdentifier<TFields extends Readonly<Record<string, AdapterField<AdapterModel>>>> = readonly [
-    AdapterScalarFieldKey<TFields>,
-    ...AdapterScalarFieldKey<TFields>[]
+export type AvAdapterIdentifier<TFields extends Readonly<Record<string, AvAdapterField<AvAdapterModel>>>> = readonly [
+    AvAdapterScalarFieldKey<TFields>,
+    ...AvAdapterScalarFieldKey<TFields>[]
 ];
+/**
+ * The Resource's identifier as the Adapter states it first: in the Adapter's
+ * own order (an ORM adapter's is its schema's, so the primary key). The Core
+ * Contract sorts identifiers for its hash, so its first one is the
+ * alphabetically first (`email` before `id`) and says nothing about which is
+ * the primary key; the model keeps the order it declared. Empty for a Resource
+ * the model does not hold or that has no identifier.
+ */
+export declare function adapterPrimaryIdentifier(model: AvAdapterModel, resource: string): readonly string[];

package/dist/adapters/adapter-identifier.js

@@ -1 +1,6 @@
-export {};
+export function adapterPrimaryIdentifier(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : undefined) ?? []);
+}

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

@@ -1,21 +1,22 @@
-import type { EnumDefinition } from "../contracts/enum-definition.js";
+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 { ScalarRegistry } from "../contracts/scalar.js";
-import type { TransactionCapability } from "../contracts/transaction-capability.js";
-import type { AdapterResource } from "./adapter-resource.js";
+import type { AvScalarRegistry } from "../contracts/scalar.js";
+import type { AvTransactionCapability } from "../contracts/transaction-capability.js";
+import type { AvAdapterResource } from "./adapter-resource.js";
 /**
  * Canonical provider-discovery facts before framework configuration or
  * Contract compilation is applied.
  */
-export interface AdapterModel {
+export interface AvAdapterModel {
     /** The scalar types the data source supports. */
-    readonly scalars: ScalarRegistry;
+    readonly scalars: AvScalarRegistry;
     /** The enums the data source declares, by name. */
-    readonly enums: Readonly<Record<string, EnumDefinition>>;
+    readonly enums: Readonly<Record<string, AvEnumDefinition>>;
     /** The discovered Resources, by name. */
-    readonly resources: Readonly<Record<string, AdapterResource<this>>>;
+    readonly resources: Readonly<Record<string, AvAdapterResource<this>>>;
     /** Whether the adapter can run interactive transactions. */
-    readonly transactions: TransactionCapability;
+    readonly transactions: AvTransactionCapability;
     /**
      * `"uniform"` when the data source takes one record's references only one
      * way at a time: every relation that holds a reference written as a
@@ -23,4 +24,12 @@ export interface AdapterModel {
      * 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-operation-executor.interface.d.ts

@@ -1,10 +1,10 @@
-import type { AdapterModel } from "./adapter-model.js";
-import type { AdapterOperation } from "./adapter-operation.js";
+import type { AvAdapterModel } from "./adapter-model.js";
+import type { AvAdapterOperation } from "./adapter-operation.js";
 /**
  * Executes one operation against the provider, directly or inside a provider
  * transaction.
  */
-export interface AdapterOperationExecutor<M extends AdapterModel = AdapterModel> {
+export interface AvAdapterOperationExecutor<M extends AvAdapterModel = AvAdapterModel> {
     /** Runs one validated operation and resolves its raw result. */
-    execute(operation: AdapterOperation<M>): Promise<unknown>;
+    execute(operation: AvAdapterOperation<M>): Promise<unknown>;
 }

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

@@ -1,12 +1,27 @@
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
-import type { AdapterModel } from "./adapter-model.js";
+import type { AvAdapterModel } from "./adapter-model.js";
 /**
- * Provider execution request after framework semantic validation.
- * Operation identity and arguments remain provider-neutral; adapters receive
- * only validated semantic argument objects, never raw transport input.
+ * Provider execution request after framework semantic validation. Operation
+ * identity and arguments remain provider-neutral; adapters receive only validated
+ * semantic argument objects, never raw transport input.
+ *
+ * Three shapes exist here only, each an `AND`: a list of conditions in the general
+ * `where` grammar the addressed row must also meet.
+ *
+ * - The flat unique selector of an `update.unique` or a `delete.unique` may carry
+ *   it. A row the selector names that misses them is a miss (the same `null` as a
+ *   row that is not there).
+ * - A `cursor` may carry it, at the root of a `find.many` and in a to-many
+ *   relation's arguments. A row the cursor names that misses them is a cursor that
+ *   names no row: the same answer as a cursor on a row that is not there.
+ * - A row the selector names that misses them, or no row, is refused: the adapter
+ *   fails the operation with `A4002`.
+ *
+ * An adapter must honour it or refuse the operation, never drop it: dropping it
+ * would write a row the conditions exclude, or position a page at one.
  */
-export type AdapterOperation<M extends AdapterModel = AdapterModel> = OperationIdentity & {
+export type AvAdapterOperation<M extends AvAdapterModel = AvAdapterModel> = AvOperationIdentity & {
     readonly resource: Extract<keyof M["resources"], string>;
     readonly arguments: SemanticOperationArguments;
 };

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

@@ -1,20 +1,34 @@
-import type { ResourceOperations } from "../contracts/resource-operations.js";
-import type { AdapterField } from "./adapter-field.js";
-import type { AdapterIdentifier } from "./adapter-identifier.js";
-import type { AdapterModel } from "./adapter-model.js";
+import type { AvCreateRequirements } from "../contracts/create-requirements.js";
+import type { AvResourceOperations } from "../contracts/resource-operations.js";
+import type { AvAdapterField } from "./adapter-field.js";
+import type { AvAdapterIdentifier } from "./adapter-identifier.js";
+import type { AvAdapterModel } from "./adapter-model.js";
 /** A discovered Resource's fields, by name. */
-export type AdapterFieldMap<M extends AdapterModel> = Readonly<Record<string, AdapterField<M>>>;
+export type AvAdapterFieldMap<M extends AvAdapterModel> = Readonly<Record<string, AvAdapterField<M>>>;
 /**
  * The field names the adapter discovered for Resource `R`, before any
  * configuration adds to them.
  */
-export type AdapterFieldKey<M extends AdapterModel, R extends Extract<keyof M["resources"], string>> = Extract<keyof M["resources"][R]["fields"], string>;
+export type AvAdapterFieldKey<M extends AvAdapterModel, R extends Extract<keyof M["resources"], string>> = Extract<keyof M["resources"][R]["fields"], string>;
 /** Provider-discovered facts for one Aventara Resource candidate. */
-export type AdapterResource<M extends AdapterModel, TFields extends AdapterFieldMap<M> = AdapterFieldMap<M>> = {
+export type AvAdapterResource<M extends AvAdapterModel, TFields extends AvAdapterFieldMap<M> = AvAdapterFieldMap<M>> = {
     /** The Resource's fields, by name. */
     readonly fields: TFields;
     /** The field tuples that identify at most one row. */
-    readonly identifiers: readonly AdapterIdentifier<TFields>[];
+    readonly identifiers: readonly AvAdapterIdentifier<TFields>[];
     /** The standard operations the data source can run for this Resource. */
-    readonly operations: ResourceOperations;
+    readonly operations: AvResourceOperations;
+    /**
+     * What a create cannot do without, in the store's own terms: every field it
+     * requires, every required to-one relation with its reference fields, and
+     * the relation (`parentSupplies`) through which a nested create gets them
+     * from its parent. Absent when it requires nothing, or when the adapter
+     * cannot say; nothing is then checked or typed before the store.
+     */
+    readonly createRequirements?: AvCreateRequirements;
+    /**
+     * The database schema the store keeps this Resource in (a PostgreSQL schema,
+     * say), when the store has schemas and the model names one. Absent otherwise.
+     */
+    readonly schema?: string;
 };

package/dist/adapters/adapter-sql-statement.d.ts

@@ -0,0 +1,19 @@
+import type { AvDecimal } from "../runtime/decimal.js";
+import type { AvJsonValue } from "../runtime/json-value.js";
+/**
+ * One value a developer SQL statement binds, after every `$ref` in it was
+ * resolved: a primitive, a `Date`, a {@link AvDecimal}, a `Uint8Array`, or a
+ * plain object or array, which is a JSON value and is bound as JSON text. Never
+ * spliced into the statement's text.
+ */
+export type AvAdapterSqlValue = string | number | boolean | bigint | null | Date | AvDecimal | Uint8Array | AvJsonValue;
+/**
+ * One developer SQL statement, as `framework.appTx.$sql` wrote it: the static
+ * text of its tagged template, and the values written between those pieces, in
+ * order. `strings` holds exactly one entry more than `values`. The adapter binds
+ * every value as a parameter of the statement; no value ever becomes SQL text.
+ */
+export type AvAdapterSqlStatement = {
+    readonly strings: readonly string[];
+    readonly values: readonly AvAdapterSqlValue[];
+};

package/dist/adapters/adapter-transaction-executor.interface.d.ts

@@ -0,0 +1,19 @@
+import type { AvAdapterModel } from "./adapter-model.js";
+import type { AvAdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
+import type { AvAdapterSqlStatement } from "./adapter-sql-statement.js";
+/**
+ * What an Adapter's `transaction` callback is handed: the transaction-scoped
+ * operation executor, and — when the Adapter declares `sqlStatements` — the
+ * statement runner `framework.appTx.$sql` steps run through.
+ */
+export interface AvAdapterTransactionExecutor<M extends AvAdapterModel = AvAdapterModel> extends AvAdapterOperationExecutor<M> {
+    /**
+     * Runs one developer SQL statement on the open transaction, every value bound
+     * as a parameter, and resolves the rows it returned (none for a statement that
+     * returns no rows). Present exactly when the Adapter declares `sqlStatements`.
+     *
+     * A failure is thrown like an operation's: a deliberate `AvError` for
+     * an outcome the Adapter classified, anything else to be answered `A3001`.
+     */
+    executeSql?(statement: AvAdapterSqlStatement): Promise<readonly unknown[]>;
+}

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

@@ -1,50 +1,80 @@
-import type { CreateRequirementTable } from "../runtime/create-requirement.js";
+import type { AvConfigComputedFields } from "../config/computed-fields.js";
 import type { ReferentialActionTable } from "../runtime/referential-action.js";
-import type { AdapterModel } from "./adapter-model.js";
-import type { AdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
+import type { AvAdapterModel } from "./adapter-model.js";
+import type { AvAdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
+import type { AvAdapterSqlStatement } from "./adapter-sql-statement.js";
+import type { AvAdapterTransactionExecutor } from "./adapter-transaction-executor.interface.js";
 /** Provider-specific implementation of Aventara discovery and execution. */
-export interface Adapter<M extends AdapterModel = AdapterModel> extends AdapterOperationExecutor<M> {
+export interface AvAdapter<M extends AvAdapterModel = AvAdapterModel> extends AvAdapterOperationExecutor<M> {
     /**
      * What the adapter discovered about the data source, in Aventara's vocabulary.
      * Read once, synchronously, when the framework is constructed.
      */
     readonly model: M;
     /**
-     * Optional referential actions: for each Resource that holds a reference,
-     * every relation holding one — the fields that hold it (`references`) and
-     * what deleting a referenced row does to its rows. Read once when the
-     * framework is constructed; never part of a Contract or its hash.
+     * Optional referential actions: for each Resource that holds a reference, every
+     * relation holding one: the fields that hold it (`references`) and what deleting a
+     * referenced row does to its rows. Read once when the framework is constructed;
+     * never part of a Contract or its hash.
+     *
+     * An edge listed under Resource `R` says that deleting a `target` row does
+     * `onDelete` to rows of `R`, and that `R`'s `references` fields hold the relation
+     * `field`'s reference.
      *
-     * An edge listed under Resource `R` says **deleting a `target` row does
-     * `onDelete` to rows of `R`**, and that `R`'s `references` fields hold the
-     * relation `field`'s reference.
+     * The same edges say which side of a relation holds its key: a nested `$connect`,
+     * `$disconnect` or `$set` on a to-one relation the parent holds runs none of the
+     * target's stages, and otherwise runs the target's `update` guards.
      *
-     * When absent, no cascade is planned and no transaction plan is refused
-     * because of one (`V1019`); a write that sets a relation and a field holding
-     * its reference both is not refused before the store; and a required
-     * relation can be satisfied only by writing the relation.
+     * When absent, no cascade is planned and no transaction plan is refused because of
+     * one (`V1019`); a write that sets a relation and a field holding its reference
+     * both is not refused before the store; and every nested `$connect`, `$disconnect`
+     * or `$set` runs the target's `update` guards.
      */
     readonly referentialActions?: ReferentialActionTable;
     /**
-     * Optional create requirements: for each Resource, the values its store
-     * cannot create a row without. Read once when the framework is constructed;
-     * never part of a Contract or its hash.
+     * 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
+     * transaction through the `executeSql` of the executor that callback is handed
+     * (`AvAdapterTransactionExecutor.executeSql`). `framework.appTx.$sql` steps and
+     * `ctx.$sql` need it. Read once when the framework is constructed; never part
+     * of a Contract or its hash.
+     *
+     * When absent, a plan holding an `appTx.$sql` step is refused before the
+     * transaction opens (`A2002`/`V1006` at the step), and so is every `ctx.$sql`.
+     */
+    readonly sqlStatements?: boolean;
+    /**
+     * Runs one developer SQL statement outside any transaction, as a plain
+     * statement, every value bound as a parameter, and resolves the rows it
+     * returned (none for a statement that returns no rows). Present exactly when
+     * the Adapter declares `sqlStatements`. `ctx.$sql` outside a transaction runs
+     * through it.
      *
-     * When absent, creates are not checked for missing values before they reach
-     * the store.
+     * A failure is thrown like an operation's: a deliberate `AvError` for an
+     * outcome the Adapter classified, anything else to be answered `A3001`.
      */
-    readonly createRequirements?: CreateRequirementTable;
+    executeSql?(statement: AvAdapterSqlStatement): Promise<readonly unknown[]>;
     /**
      * Optional callback transaction capability, required exactly when the
      * discovered model declares `transactions: "interactive"`. The callback
-     * receives only a transaction-scoped operation executor, never the provider
-     * client itself, and every operation of a plan executes through it.
+     * receives only a transaction-scoped executor, never the provider client
+     * itself, and every step of a plan executes through it.
      *
-     * The implementation must reject with the exact value `work` threw — by identity,
-     * never a wrapper — and must not resolve after `work` rejected; rollback is
-     * implied by that rejection. Guards, pipes, hooks and interceptors of every plan
-     * operation run inside `work` while the provider transaction is open, so they must
-     * not perform network I/O or unrelated slow work.
+     * The implementation must reject with the exact value `work` threw (by identity,
+     * never a wrapper) and must not resolve after `work` rejected; rollback is
+     * implied by that rejection. Every step's interceptors and hooks, and the touched
+     * Resources' transaction stages, run inside `work` while the provider transaction
+     * is open, so they must not perform network I/O or unrelated slow work. A step's
+     * guards, pipes and validators run before it opens.
      */
-    transaction?<T>(work: (executor: AdapterOperationExecutor<M>) => Promise<T>): Promise<T>;
+    transaction?<T>(work: (executor: AvAdapterTransactionExecutor<M>) => Promise<T>): Promise<T>;
 }

package/dist/avz/avz-check.factory.d.ts

@@ -0,0 +1,83 @@
+import { type AvZCheck } from "./avz-check.registry.js";
+/** The fields a bound applies to, by the kind of value it was written as. */
+type BoundTarget<Value> = Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal";
+/** A value below `value`. */
+export declare const lt: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<BoundTarget<Value>>;
+/** A value at most `value`. */
+export declare const lte: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<BoundTarget<Value>>;
+/** A value above `value`. */
+export declare const gt: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<BoundTarget<Value>>;
+/** A value at least `value`. */
+export declare const gte: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<BoundTarget<Value>>;
+/** A value above zero. */
+export declare const positive: () => AvZCheck<"number" | "bigint" | "decimal">;
+/** A value at least zero. */
+export declare const nonnegative: () => AvZCheck<"number" | "bigint" | "decimal">;
+/** A value below zero. */
+export declare const negative: () => AvZCheck<"number" | "bigint" | "decimal">;
+/** A value at most zero. */
+export declare const nonpositive: () => AvZCheck<"number" | "bigint" | "decimal">;
+/** A multiple of `value` (not zero). */
+export declare const multipleOf: <const Value extends number | bigint>(value: Value) => AvZCheck<Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+/** A string of at most `maximum` characters (Unicode code points). */
+export declare const maxLength: (maximum: number) => AvZCheck<"string">;
+/** A string of at least `minimum` characters (Unicode code points). */
+export declare const minLength: (minimum: number) => AvZCheck<"string">;
+/** A string of exactly `length` characters (Unicode code points). */
+export declare const length: (exact: number) => AvZCheck<"string">;
+/** A list of at most `maximum` entries. */
+export declare const maxItems: (maximum: number) => AvZCheck<"list">;
+/** A list of at least `minimum` entries. */
+export declare const minItems: (minimum: number) => AvZCheck<"list">;
+/** Bytes of at most `maximum` in length. */
+export declare const maxSize: (maximum: number) => AvZCheck<"bytes">;
+/** Bytes of at least `minimum` in length. */
+export declare const minSize: (minimum: number) => AvZCheck<"bytes">;
+/** Bytes of exactly `size` in length. */
+export declare const size: (exact: number) => AvZCheck<"bytes">;
+/** A string `pattern` matches (a JavaScript regular expression; its flags count). */
+export declare const regex: (pattern: RegExp) => AvZCheck<"string">;
+/** A string containing `value`. */
+export declare const includes: (value: string) => AvZCheck<"string">;
+/** A string starting with `prefix`. */
+export declare const startsWith: (prefix: string) => AvZCheck<"string">;
+/** A string ending with `suffix`. */
+export declare const endsWith: (suffix: string) => AvZCheck<"string">;
+/** A string with no uppercase letter (A–Z). */
+export declare const lowercase: () => AvZCheck<"string">;
+/** A string with no lowercase letter (a–z). */
+export declare const uppercase: () => AvZCheck<"string">;
+export declare const email: () => AvZCheck<"string">;
+export declare const url: () => AvZCheck<"string">;
+export declare const emoji: () => AvZCheck<"string">;
+export declare const uuid: () => AvZCheck<"string">;
+export declare const guid: () => AvZCheck<"string">;
+export declare const nanoid: () => AvZCheck<"string">;
+export declare const cuid: () => AvZCheck<"string">;
+export declare const cuid2: () => AvZCheck<"string">;
+export declare const ulid: () => AvZCheck<"string">;
+export declare const xid: () => AvZCheck<"string">;
+export declare const ksuid: () => AvZCheck<"string">;
+export declare const ipv4: () => AvZCheck<"string">;
+export declare const ipv6: () => AvZCheck<"string">;
+export declare const cidrv4: () => AvZCheck<"string">;
+export declare const cidrv6: () => AvZCheck<"string">;
+export declare const base64: () => AvZCheck<"string">;
+export declare const base64url: () => AvZCheck<"string">;
+export declare const jsonString: () => AvZCheck<"string">;
+export declare const e164: () => AvZCheck<"string">;
+export declare const creditCard: () => AvZCheck<"string">;
+export declare const iban: () => AvZCheck<"string">;
+export declare const jwt: () => AvZCheck<"string">;
+/** zod's ISO 8601 formats, as `z.iso` names them. */
+export declare const iso: Readonly<{
+    /** A date-time in UTC (`Z`), seconds required, any fraction (`z.iso.datetime()`). */
+    datetime: () => AvZCheck<"string">;
+    /** A calendar date, `YYYY-MM-DD` (`z.iso.date()`). */
+    date: () => AvZCheck<"string">;
+    /** A time, `HH:MM` with optional seconds and fraction (`z.iso.time()`). */
+    time: () => AvZCheck<"string">;
+    /** A duration such as `P3DT4H` (`z.iso.duration()`). */
+    duration: () => AvZCheck<"string">;
+}>;
+export {};

package/dist/avz/avz-check.factory.js

@@ -0,0 +1,116 @@
+import { registerAvZCheck, } from "./avz-check.registry.js";
+const CHECK_PROTOTYPE = Object.freeze(Object.create(null));
+function build(data) {
+    const check = Object.freeze(Object.assign(Object.create(CHECK_PROTOTYPE), data));
+    registerAvZCheck(check, Object.freeze({ ...data }));
+    return check;
+}
+function bound(builder, value) {
+    if ((typeof value === "number" && Number.isFinite(value)) ||
+        typeof value === "bigint" ||
+        (value instanceof Date && !Number.isNaN(value.getTime()))) {
+        return value instanceof Date ? new Date(value.getTime()) : value;
+    }
+    throw new TypeError(`AvZ.${builder}: the bound must be a finite number, a bigint or a valid Date.`);
+}
+function count(builder, value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+        return value;
+    }
+    throw new TypeError(`AvZ.${builder}: the length must be a non-negative integer.`);
+}
+function text(builder, value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    throw new TypeError(`AvZ.${builder}: the text must be a string.`);
+}
+const range = (builder, check, inclusive) => (value) => build({ check, value: bound(builder, value), inclusive });
+const sign = (check, inclusive) => () => build({ check, value: 0, inclusive });
+export const lt = range("lt", "less_than", false);
+export const lte = range("lte", "less_than", true);
+export const gt = range("gt", "greater_than", false);
+export const gte = range("gte", "greater_than", true);
+export const positive = sign("greater_than", false);
+export const nonnegative = sign("greater_than", true);
+export const negative = sign("less_than", false);
+export const nonpositive = sign("less_than", true);
+export const multipleOf = (value) => {
+    const step = bound("multipleOf", value);
+    if (step instanceof Date || step === 0 || step === 0n) {
+        throw new TypeError("AvZ.multipleOf: the step must be a non-zero finite number or bigint.");
+    }
+    return build({ check: "multiple_of", value: step });
+};
+export const maxLength = (maximum) => build({ check: "max_length", maximum: count("maxLength", maximum) });
+export const minLength = (minimum) => build({ check: "min_length", minimum: count("minLength", minimum) });
+export const length = (exact) => build({ check: "length_equals", length: count("length", exact) });
+export const maxItems = (maximum) => build({
+    check: "max_length",
+    maximum: count("maxItems", maximum),
+    list: true,
+});
+export const minItems = (minimum) => build({
+    check: "min_length",
+    minimum: count("minItems", minimum),
+    list: true,
+});
+export const maxSize = (maximum) => build({ check: "max_size", maximum: count("maxSize", maximum) });
+export const minSize = (minimum) => build({ check: "min_size", minimum: count("minSize", minimum) });
+export const size = (exact) => build({ check: "size_equals", size: count("size", exact) });
+export const regex = (pattern) => {
+    if (!(pattern instanceof RegExp)) {
+        throw new TypeError("AvZ.regex: the pattern must be a RegExp.");
+    }
+    return build({
+        check: "string_format",
+        format: "regex",
+        pattern: { source: pattern.source, flags: pattern.flags },
+    });
+};
+export const includes = (value) => build({
+    check: "string_format",
+    format: "includes",
+    includes: text("includes", value),
+});
+export const startsWith = (prefix) => build({
+    check: "string_format",
+    format: "starts_with",
+    prefix: text("startsWith", prefix),
+});
+export const endsWith = (suffix) => build({
+    check: "string_format",
+    format: "ends_with",
+    suffix: text("endsWith", suffix),
+});
+export const lowercase = () => build({ check: "string_format", format: "lowercase" });
+export const uppercase = () => build({ check: "string_format", format: "uppercase" });
+const named = (format) => () => build({ check: "string_format", format });
+export const email = named("email");
+export const url = named("url");
+export const emoji = named("emoji");
+export const uuid = named("uuid");
+export const guid = named("guid");
+export const nanoid = named("nanoid");
+export const cuid = named("cuid");
+export const cuid2 = named("cuid2");
+export const ulid = named("ulid");
+export const xid = named("xid");
+export const ksuid = named("ksuid");
+export const ipv4 = named("ipv4");
+export const ipv6 = named("ipv6");
+export const cidrv4 = named("cidrv4");
+export const cidrv6 = named("cidrv6");
+export const base64 = named("base64");
+export const base64url = named("base64url");
+export const jsonString = named("json_string");
+export const e164 = named("e164");
+export const creditCard = named("credit_card");
+export const iban = named("iban");
+export const jwt = named("jwt");
+export const iso = Object.freeze({
+    datetime: named("datetime"),
+    date: named("date"),
+    time: named("time"),
+    duration: named("duration"),
+});

package/dist/avz/avz-check.registry.d.ts

@@ -0,0 +1,35 @@
+import type { AvFieldCheck } from "../contracts/field-check.js";
+declare const avzCheckTarget: unique symbol;
+/**
+ * What a check applies to: a field's scalar type (`int` and `float` are
+ * `"number"`), a Json Shape node (a string, a number or an integer), or a list's
+ * own length (`"list"`).
+ */
+export type AvZCheckTarget = "string" | "number" | "bigint" | "decimal" | "datetime" | "bytes" | "list";
+/**
+ * A declarative check built with `AvZ` from `@aventara/core/avz` (`AvZ.maxLength(80)`,
+ * `AvZ.email()`, …): a field validator, or a check on a Json Shape node.
+ */
+export interface AvZCheck<Target extends AvZCheckTarget = never> {
+    readonly [avzCheckTarget]: (target: Target) => void;
+}
+/**
+ * A check as `AvZ` built it: the Contract's form, except that a bound or a step
+ * is the value the developer wrote (a number, a bigint or a `Date`) until the
+ * compiler writes it in the form of the field it lands on.
+ */
+export type AvZAuthoredCheck = {
+    readonly check: "less_than" | "greater_than";
+    readonly value: number | bigint | Date;
+    readonly inclusive: boolean;
+} | {
+    readonly check: "multiple_of";
+    readonly value: number | bigint;
+} | Exclude<AvFieldCheck, {
+    readonly check: "less_than" | "greater_than" | "multiple_of";
+}>;
+/** Records `check` as built by `AvZ`. For `@aventara/core/avz` only. */
+export declare function registerAvZCheck(check: object, data: AvZAuthoredCheck): void;
+/** The check `value` is, or `undefined` when `AvZ` did not build it. */
+export declare function avzCheckOf(value: unknown): AvZAuthoredCheck | undefined;
+export {};