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

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.d.ts

@@ -1,12 +1,17 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { ResolvedFrameworkConfig } from "../config/config.resolver.js";
-import type { ApplicationContract, ClientContract, CoreContract } from "../contracts/contract.js";
-import type { ContractCompilerDiagnostic } from "./contract-compiler-diagnostic.js";
-/** The Core, Application and Client Contracts compiled from one configuration. */
-export type FrameworkContracts = {
-    readonly core: CoreContract;
-    readonly application: ApplicationContract;
-    readonly client: ClientContract;
+import type { AvContractAgent, AvContractApplication, AvContractClient, AvContractCore } from "../contracts/contract.js";
+import type { AvContractCompilerDiagnostic } from "./contract-compiler-diagnostic.js";
+/** The Core, Application, Client and Agent Contracts compiled from one configuration. */
+export type AvContracts = {
+    readonly core: AvContractCore;
+    readonly application: AvContractApplication;
+    readonly client: AvContractClient;
+    /**
+     * The agent layer's Contract, which MCP tools are built from. With no `agent`
+     * layer configured it is the Client Contract's view.
+     */
+    readonly agent: AvContractAgent;
 };
 /**
  * The result of {@link compileContracts}: the three Contracts, or the
@@ -14,19 +19,14 @@ export type FrameworkContracts = {
  */
 export type ContractCompilationResult = {
     readonly ok: true;
-    readonly contracts: FrameworkContracts;
+    readonly contracts: AvContracts;
 } | {
     readonly ok: false;
-    readonly diagnostics: readonly ContractCompilerDiagnostic[];
+    readonly diagnostics: readonly AvContractCompilerDiagnostic[];
 };
-/**
- * Whether writing `configured` VERBATIM as capability member `key` would advertise
- * something `baseline` does not — the question the `fields` walk asks before it copies
- * a value onto an adapter field.
- */
-export declare function capabilityAddsBaseline(fieldKind: "scalar" | "relation", baseline: Readonly<Record<string, unknown>>, key: string, configured: unknown): boolean;
 /**
  * Compiles the Core Contract from the adapter model and the root
- * configuration, then the Application and Client Contracts from it.
+ * configuration, then the Application and Client Contracts from it, then the
+ * Agent Contract from the view of the layer it extends.
  */
-export declare function compileContracts<M extends AdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;
+export declare function compileContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;