@aventara/core 0.1.0-pilot.3 → 1.0.0-rc.0

package/dist/contracts/json-shape.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The phantom key a Json Shape's TypeScript type travels under. Type-level only:
+ * no value ever holds it.
+ */
+declare const jsonShapeValue: unique symbol;
+/**
+ * A Json Shape, as the type system sees it: the TypeScript type `Value` of a
+ * value that conforms to it. `AvZ` builds every one; a value from anywhere else —
+ * a Zod schema included — is not one.
+ */
+export interface JsonShape<Value = unknown> {
+    readonly [jsonShapeValue]: Value;
+}
+/** The TypeScript type a {@link JsonShape} describes. */
+export type JsonShapeValue<Shape extends JsonShape> = Shape[typeof jsonShapeValue];
+/** A JSON primitive: what a `const` names. */
+export type JsonSchemaPrimitive = string | number | boolean | null;
+/**
+ * A Json Shape in a Contract: passive JSON Schema (draft 2020-12), restricted to
+ * the forms Aventara emits.
+ */
+export type JsonSchema = {
+    readonly type: "string" | "number" | "integer" | "boolean" | "null";
+} | {
+    readonly const: JsonSchemaPrimitive;
+} | {
+    readonly type: "string";
+    readonly enum: readonly [string, ...string[]];
+} | {
+    readonly type: "object";
+    readonly properties: {
+        readonly [key: string]: JsonSchema;
+    };
+    readonly required?: readonly string[];
+    readonly additionalProperties: false;
+} | {
+    readonly type: "object";
+    readonly additionalProperties: JsonSchema;
+} | {
+    readonly type: "array";
+    readonly items: JsonSchema;
+} | {
+    readonly type: "array";
+    readonly prefixItems: readonly [JsonSchema, ...JsonSchema[]];
+    readonly items: false;
+    readonly minItems: number;
+    readonly maxItems: number;
+} | {
+    readonly anyOf: readonly [JsonSchema, JsonSchema, ...JsonSchema[]];
+} | {
+    readonly oneOf: readonly [JsonSchema, ...JsonSchema[]];
+};
+/**
+ * The type-level carrier of a shaped Json field's TypeScript type, on the field's
+ * `json` member in a typed Contract view. Never present at runtime.
+ */
+export type JsonFieldType<Value> = {
+    readonly "~jsonType": Value;
+};
+/**
+ * A shaped Json field's `json` member in a typed Contract view: the schema, and
+ * the type it describes.
+ */
+export type ShapedJsonSchema<Value> = JsonSchema & JsonFieldType<Value>;
+export {};

package/dist/contracts/json-shape.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/lifecycle-trait.d.ts

@@ -1,7 +1,8 @@
 /**
- * Lifecycle traits describe value ownership/derivation without implying
- * writability. Generated values are ORM/database-owned; computed values are
- * framework/developer-owned; virtual describes persistence only.
+ * Where a field's value comes from, without saying whether it is writable:
+ * `DEFAULTED` and `GENERATED_ON_*` by the data source, `COMPUTED_ON_*` by a
+ * framework behavior; `VIRTUAL` marks a field that is not stored.
  */
 export declare const LIFECYCLE_TRAITS: readonly ["DEFAULTED", "GENERATED_ON_CREATE", "GENERATED_ON_UPDATE", "COMPUTED_ON_CREATE", "COMPUTED_ON_UPDATE", "COMPUTED_ON_READ", "VIRTUAL"];
+/** One of {@link LIFECYCLE_TRAITS}. */
 export type LifecycleTrait = (typeof LIFECYCLE_TRAITS)[number];

package/dist/contracts/reference-write-limit.d.ts

@@ -0,0 +1,7 @@
+/** The limits a data source may put on how one record writes its references. */
+export declare const REFERENCE_WRITE_LIMITS: readonly ["uniform"];
+/**
+ * `"uniform"`: one record writes the relations that hold a reference either all
+ * as relations or all through their reference fields, never some each way.
+ */
+export type ReferenceWriteLimit = (typeof REFERENCE_WRITE_LIMITS)[number];

package/dist/contracts/reference-write-limit.js

@@ -0,0 +1 @@
+export const REFERENCE_WRITE_LIMITS = ["uniform"];

package/dist/contracts/resource-operations.d.ts

@@ -3,19 +3,6 @@ import type { ProjectionScope, WriteScope } from "./capability.js";
  * The argument scopes one advertised operation variant qualifies its arguments
  * with: which projection position its projection arguments sit in, and which write
  * position its data argument sits in.
- *
- * The variant-to-scope map is an ADAPTER fact, not a protocol constant — a
- * variant's projection position depends on which ORM call the adapter routes it to
- * — so the advertised variant carries the answer rather than core tabulating it.
- *
- * At least one scope must be stated. A descriptor stating neither says exactly
- * what `true` says, and one semantic fact with two encodings is one fact with two
- * hashes.
- *
- * Named for the variant it qualifies, and deliberately not `OperationScopes`:
- * `OperationScope` is a public (now deprecated) alias of `RequestOrigin`, meaning
- * `"application" | "client"`, and two public names one character apart with
- * nothing in common is a vocabulary collision, not a near-miss.
  */
 export type OperationVariantScopes = {
     readonly projection: ProjectionScope;
@@ -60,63 +47,16 @@ export type ResourceOperations = {
     };
 };
 /**
- * Whether one `ResourceOperations` leaf advertises an available variant.
- *
- * Availability is **presence**: the leaf is `true`, or it is the descriptor that
- * qualifies the variant's arguments. A descriptor states how the variant's
- * arguments are scoped — it never retracts the variant — so `leaf === true` is
- * the wrong question wherever availability is read, and the leaf's widening to
- * `true | OperationVariantScopes` made every hand-rolled copy of that question
- * silently wrong. The question has one home so the next widening of
- * `OperationAvailability` reaches every reader at once.
- *
- * The parameter is `unknown` because the readers are the request validator and
- * the Contract compiler, which hold the leaf as a Contract value keyed by an
- * untrusted or mid-compilation string. Descriptor *shape* is not judged here: a
- * present leaf is an available variant, and validating what the descriptor says
- * belongs to whoever owns the descriptor's own invariants.
+ * Whether one `ResourceOperations` entry marks its variant available: it is
+ * `true` or an argument-position descriptor.
  */
 export declare function isOperationVariantAvailable(availability: unknown): availability is OperationAvailability;
 /**
  * The projection position one advertised variant's projection arguments sit in.
- *
- * `"record"` — the unrestricted position — is the answer for `true`, for an absent
- * leaf and for a descriptor that qualifies only its write argument, because the
- * unqualified arm means *nothing is narrowed here*. A Contract written before the
- * axis existed therefore keeps validating exactly as it did, which is what makes
- * the widening in {@link OperationAvailability} non-breaking for a producer that
- * has not measured it.
- *
- * The map from variant to scope is **not** here and must never be:
- * `update.first`'s projection position is the single-record one only because an
- * adapter chose to route that variant to a single-record provider call, and an
- * adapter that routes it to a bulk one moves the answer. Core reads what the
- * advertised variant carries rather than tabulating one scope per variant name.
- *
- * `unknown` for the same reason {@link isOperationVariantAvailable} takes it: the
- * caller holds the leaf keyed by an untrusted request string.
  */
 export declare function projectionScopeOf(availability: unknown): ProjectionScope;
 /**
  * The write position one advertised variant's data argument sits in, and the write
  * mirror of {@link projectionScopeOf}.
- *
- * `"nested"` — the unrestricted position — is the answer for `true`, for an absent
- * leaf and for a descriptor that qualifies only its projection argument, for the
- * same reason `"record"` is on the projection axis: the unqualified arm means
- * *nothing is narrowed here*, so a Contract written before the axis existed keeps
- * the write surface it had.
- *
- * The two axes are read by two functions, not one that returns a pair, because
- * they are measured and consulted separately — `WRITE_SCOPES` is a separate array
- * from `PROJECTION_SCOPES` for that reason — and a caller that needs only one
- * position should not be handed the other to discard.
- *
- * The mirror exists so that *"what does this descriptor mean?"* has one answer per
- * axis rather than one answer and one convention. The canonicalizer's collapse of
- * a redundant descriptor is keyed on these two functions' answer for `true`: a
- * descriptor says nothing beyond `true` exactly when every reader answers for it
- * what it answers for `true`, and that test is only as honest as the readers being
- * the single statement of each axis's unqualified scope.
  */
 export declare function writeScopeOf(availability: unknown): WriteScope;

package/dist/contracts/resource.d.ts

@@ -2,7 +2,9 @@ import type { Contract } from "./contract.js";
 import type { Field } from "./field.js";
 import type { Identifier } from "./identifier.js";
 import type { ResourceOperations } from "./resource-operations.js";
+/** A Resource's fields, by name. */
 export type ResourceFieldMap<C extends Contract> = Readonly<Record<string, Field<C>>>;
+/** One Resource: its fields, identifiers and available operations. */
 export type Resource<C extends Contract, TFields extends ResourceFieldMap<C> = ResourceFieldMap<C>> = {
     readonly fields: TFields;
     readonly identifiers: readonly Identifier<TFields>[];

package/dist/contracts/scalar-value-type.d.ts

@@ -2,33 +2,19 @@ import type { Decimal } from "../runtime/decimal.js";
 import type { JsonValue } from "../runtime/json-value.js";
 import type { Contract } from "./contract.js";
 import type { ScalarField } from "./field.js";
+import type { JsonFieldType } from "./json-shape.js";
 import type { BuiltInScalar } from "./scalar.js";
 /**
- * A scalar-form map: the TypeScript type each built-in scalar takes on one side of
- * a boundary. Every built-in must be answered, so a map that forgets one fails to
- * compile where it is passed rather than typing that scalar as `unknown`.
- *
- * It is a parameter rather than a fixed table because one derivation serves more
- * than one side: the application forms below for an in-process caller, and the
- * wire forms for a transport or a generated client.
- *
- * This constraint is not exported: a map is checked for completeness where it is
- * passed, so a consumer never has to name it.
+ * A scalar-form map: the TypeScript type each built-in scalar takes on one side
+ * of a boundary. Every built-in must be listed.
  */
 export type ScalarForms = {
     readonly [Scalar in BuiltInScalar]: unknown;
 };
 /**
- * The value form every framework-produced scalar takes, in either request scope.
- *
- * Output is scope-independent: output validation normalizes with `"runtime"`,
- * which maps to the application branch of `normalizeScalarAtom`, and the adapter
- * is held to it (`runtime/scalar-runtime.ts`, `runtime/output-validator.ts`). So
- * a client-scope caller receives these forms too, in process; the wire encoding
- * happens on a transport's way out.
- *
- * `decimal` is core's own {@link Decimal} — never a provider's decimal class —
- * which is what `normalizeScalarAtom`'s `instanceof Decimal` check enforces.
+ * The TypeScript form each built-in scalar takes in process: in results of
+ * either origin, and in `framework.application` arguments. `decimal` is
+ * Aventara's own {@link Decimal}.
  */
 export type ApplicationScalarForms = {
     readonly string: string;
@@ -40,17 +26,15 @@ export type ApplicationScalarForms = {
     readonly datetime: Date;
     readonly bytes: Uint8Array;
     /**
-     * `normalizeScalarFieldValue` refuses a field-level `null` on a required field and
-     * on a list entry, and reads it as the field's absence where `nullable: true`, so
-     * the `| null` comes from the Contract's `nullable` like every other scalar's. A
-     * `null` INSIDE the value is JSON's.
+     * Any JSON value. A field-level `null` is the field's absence and is allowed
+     * only where the field is nullable; a `null` inside the value is JSON's own.
      */
     readonly json: Exclude<JsonValue, null>;
 };
 /**
- * The encoded forms the client-scope input branch of `normalizeScalarAtom`
- * accepts: base-10 bigint strings, decimal strings, canonical ISO-8601 UTC
- * datetimes and RFC 4648 base64 bytes.
+ * The encoded forms of the built-in scalars: base-10 bigint strings, decimal strings,
+ * canonical ISO-8601 UTC datetimes and RFC 4648 base64 bytes. For a transport or a
+ * generated client to pass as `Forms`.
  */
 export type WireScalarForms = {
     readonly string: string;
@@ -61,42 +45,38 @@ export type WireScalarForms = {
     readonly decimal: string;
     readonly datetime: string;
     readonly bytes: string;
-    /**
-     * The same form as the application's: `normalizeJsonValue` has no client
-     * branch, and a JSON value needs no encoding to cross a JSON wire.
-     */
+    /** The same as in process: a JSON value needs no encoding to cross a JSON wire. */
     readonly json: Exclude<JsonValue, null>;
 };
-/**
- * One value of a scalar field, before `list` and `nullable` apply.
- *
- * Exported to the argument surface only, never from the package: a filter's
- * `in`, a list's `has` and a mutation directive's operand each take one entry of
- * a list field, which is exactly this, and a second spelling of it would be a
- * second derivation of one rule.
- */
+/** One value of a scalar field, before `list` and `nullable` apply. */
 export type ScalarAtom<C extends Contract, Type, Forms extends ScalarForms> = Type extends {
     readonly enum: infer Enum extends keyof C["enums"];
 } ? C["enums"][Enum]["values"][number] : Type extends {
     readonly scalar: infer Scalar;
 } ? Scalar extends keyof Forms ? Forms[Scalar] : unknown : never;
+/**
+ * One value of a scalar field, before `list` and `nullable` apply: its Json
+ * Shape's type where the field is shaped, otherwise {@link ScalarAtom}.
+ */
+export type FieldAtom<C extends Contract, Field extends {
+    readonly type: unknown;
+    readonly json?: unknown;
+}, Forms extends ScalarForms> = Field extends {
+    readonly json: JsonFieldType<infer Value>;
+} ? Value : ScalarAtom<C, Field["type"], Forms>;
 /**
  * `list: true` makes the value a read-only array of atoms. A `list` the Contract
  * left as a plain `boolean` admits either, so neither form is promised.
  */
 type ListValue<List, Atom> = [List] extends [false] ? Atom : [List] extends [true] ? readonly Atom[] : Atom | readonly Atom[];
 /**
- * The value type of one scalar field, under one scalar-form map.
+ * The value type of one scalar field, under one scalar-form map:
  *
- * - enum-backed → the member union of `EnumDefinition.values` (literal only while
- *   the model is `as const`; a widened model answers `string`);
+ * - enum-backed → the union of its values (literal only while the model is
+ *   `as const`; otherwise `string`);
  * - built-in scalar → `Forms[scalar]`;
- * - `list: true` → `readonly T[]`, whose entries are never `null`
- *   (`normalizeScalarFieldValue` refuses a null entry);
+ * - `list: true` → `readonly T[]`, whose entries are never `null`;
  * - `nullable: true` → `| null`, on the whole value, list or not.
- *
- * Nullability is read as "can it be `true`", so a Contract that widened the flag
- * to `boolean` is typed nullable rather than promised non-null.
  */
-export type ScalarValueType<C extends Contract, Field extends ScalarField<C>, Forms extends ScalarForms = ApplicationScalarForms> = ListValue<Field["list"], ScalarAtom<C, Field["type"], Forms>> | (true extends Field["nullable"] ? null : never);
+export type ScalarValueType<C extends Contract, Field extends ScalarField<C>, Forms extends ScalarForms = ApplicationScalarForms> = ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never);
 export {};

package/dist/contracts/scalar.d.ts

@@ -1,9 +1,10 @@
-/** Scalar identities owned by the Aventara v1 protocol. */
+/** The built-in scalar types of the Aventara protocol. */
 export declare const BUILT_IN_SCALARS: readonly ["string", "boolean", "int", "float", "bigint", "decimal", "datetime", "bytes", "json"];
+/** One of {@link BUILT_IN_SCALARS}. */
 export type BuiltInScalar = (typeof BUILT_IN_SCALARS)[number];
-/** Passive definition for a built-in scalar registry entry. */
+/** One entry of a scalar registry. */
 export type ScalarDefinition = {
     readonly builtin: true;
 };
-/** Passive scalar registry exposed by an AdapterModel or Contract. */
+/** The scalar types an adapter model or Contract supports, by name. */
 export type ScalarRegistry = Readonly<Record<string, ScalarDefinition>>;

package/dist/contracts/transaction-capability.d.ts

@@ -1,2 +1,4 @@
+/** The transaction capabilities. */
 export declare const TRANSACTION_CAPABILITIES: readonly ["none", "interactive"];
+/** `"none"` or `"interactive"`: whether transactions can run. */
 export type TransactionCapability = (typeof TRANSACTION_CAPABILITIES)[number];

package/dist/contracts/wire-scalar-format.d.ts

@@ -2,9 +2,9 @@ import type { BuiltInScalar } from "./scalar.js";
 import type { ApplicationScalarForms, WireScalarForms } from "./scalar-value-type.js";
 /**
  * The built-in scalars whose wire form is not their runtime form — the ones a JSON
- * wire carries as a string with a grammar of its own. Derived from the two form
- * maps rather than listed, so a built-in scalar added with a string wire form
- * fails to compile below until its grammar is written.
+ * wire carries as a string with a grammar of its own. Derived from the two form maps
+ * rather than listed, so a built-in scalar added with a string wire form fails to
+ * compile below until its grammar is written.
  */
 type WireEncodedScalar = {
     readonly [S in BuiltInScalar]: WireScalarForms[S] extends ApplicationScalarForms[S] ? never : S;
@@ -13,18 +13,6 @@ type WireEncodedScalar = {
  * `AvProtocol.scalarFormats` — the wire grammars of protocol version 1, as passive
  * data: one anchored pattern SOURCE string per wire-encoded scalar, in
  * `BUILT_IN_SCALARS` order.
- *
- * The one source: execution decodes client-scope arguments with these
- * (`runtime/scalar-runtime.ts`, `runtime/decimal.ts`), `@aventara/core/protocol`
- * re-exports this object, and the client generator emits each source by value into
- * the generated runtime as a regular-expression literal. Strings, not `RegExp`s,
- * so it survives JSON and can be emitted; frozen, so no consumer can rewrite a
- * grammar in place.
- *
- * A grammar is the SHAPE only. Two scalars carry one more rule each, applied where
- * they decode: a `datetime` must also round-trip `toISOString()` exactly, and a
- * `bytes` string's padded group must leave its unused bits zero ({@link
- * decodeBase64}).
  */
 export declare const scalarFormats: Readonly<{
     readonly bigint: "^-?(?:0|[1-9]\\d*)$";
@@ -32,18 +20,15 @@ export declare const scalarFormats: Readonly<{
     readonly datetime: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$";
     readonly bytes: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$";
 }>;
-/** {@link scalarFormats}, compiled once for execution's own decoding. */
+/** {@link scalarFormats}, compiled to regular expressions. */
 export declare const WIRE_SCALAR_PATTERNS: {
     readonly [S in WireEncodedScalar]: RegExp;
 };
 /** RFC 4648 base64, standard alphabet, padded: the canonical spelling of `bytes`. */
 export declare function encodeBase64(bytes: Uint8Array): string;
 /**
- * The bytes of a CANONICAL RFC 4648 base64 string; `undefined` for any other
- * string. Canonical means the grammar plus one rule the grammar cannot state: the
- * bits a padded final group does not carry must be zero, or two wire strings would
- * name one byte sequence (`"AB=="` and `"AA=="` both `[0]`). The generated
- * client's decoder applies the same rule.
+ * The bytes of a canonical RFC 4648 base64 string; `undefined` for any other
+ * string, including one whose unused padding bits are not zero.
  */
 export declare function decodeBase64(wire: string): Uint8Array | undefined;
 export {};