@asaidimu/anansi 4.0.2 → 8.6.2

package/index.d.mts

@@ -0,0 +1,1081 @@
+import "@asaidimu/query";
+//#region src/schema/generated.d.ts
+type ComparisonOperator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte" | "in" | "nin" | "contains" | "ncontains" | "exists" | "nexists";
+type Constraint = ConstraintMetadata & ConstraintUnion;
+interface ConstraintGroup {
+  operator: LogicalOperatorEnum;
+  rules: ConstraintUnion[];
+}
+interface ConstraintMetadata {
+  description?: string;
+  name: string;
+}
+interface ConstraintRule {
+  fields?: String[];
+  parameters?: unknown;
+  predicate: string;
+}
+type ConstraintUnion = ConstraintRule | ConstraintGroup;
+interface FieldDefinition {
+  default?: unknown;
+  deprecated?: boolean;
+  description?: string;
+  metadata?: unknown;
+  name: string;
+  nullable?: boolean;
+  required?: boolean;
+  schema?: SchemaReference | SchemaReferenceArray | InlineTypeDescriptor;
+  type: FieldType;
+  unique?: boolean;
+}
+type FieldType = "unknown" | "string" | "number" | "integer" | "decimal" | "boolean" | "array" | "enum" | "object" | "record" | "union" | "composite" | "geometry" | "bytes";
+interface IndexCondition {
+  field: string;
+  operator: ComparisonOperator;
+  value: unknown;
+}
+interface IndexConditionGroup {
+  conditions: IndexConditionUnion[];
+  operator: LogicalOperatorEnum;
+}
+type IndexConditionUnion = IndexCondition | IndexConditionGroup;
+interface IndexDefinition {
+  condition?: IndexCondition | IndexConditionGroup;
+  description?: string;
+  fields: String[];
+  name: string;
+  order?: IndexOrder;
+  type: IndexType;
+  unique?: boolean;
+}
+type IndexOrder = "asc" | "desc";
+type IndexType = "normal" | "unique" | "primary" | "spatial" | "fulltext";
+interface InlineTypeDescriptor {
+  type: InlineTypeKind;
+  values?: Unknown[];
+}
+type InlineTypeKind = "string" | "number" | "integer" | "decimal" | "boolean" | "bytes" | "unknown" | "record";
+type LogicalOperatorEnum = "and" | "or" | "not" | "nor" | "xor" | "nand" | "xnor";
+interface NestedSchemaDefinition {
+  concrete?: boolean;
+  constraints?: Record<string, Constraint>;
+  default?: unknown;
+  description?: string;
+  fields?: Record<string, FieldDefinition>;
+  indexes?: Record<string, IndexDefinition>;
+  metadata?: unknown;
+  name: string;
+  schema?: SchemaReference | SchemaReferenceArray | InlineTypeDescriptor;
+  type?: FieldType;
+  values?: Unknown[];
+}
+interface SchemaReference {
+  constraints?: Record<string, Constraint>;
+  id: string;
+  indexes?: Record<string, IndexDefinition>;
+}
+type SchemaReferenceArray = SchemaReference[];
+type String = string;
+type Unknown = unknown;
+/** Meta-schema defining the structure of schema definitions */
+interface SchemaDefinition {
+  constraints?: Record<string, Constraint>;
+  description?: string;
+  fields?: Record<string, FieldDefinition>;
+  indexes?: Record<string, IndexDefinition>;
+  metadata?: unknown;
+  name: string;
+  schemas?: Record<string, NestedSchemaDefinition>;
+  version: string;
+}
+//#endregion
+//#region src/schema/types.d.ts
+/** FieldDefinition plus Go-supported field-level enum `values`. */
+type FieldDef = FieldDefinition & {
+  values?: unknown[];
+};
+/**
+ * Parsed literal wrapper — mirrors Go LiteralValue zero/null semantics:
+ * absent key → "zero", explicit JSON null → "null".
+ */
+declare class Literal {
+  readonly kind: "zero" | "null" | "string" | "integer" | "float" | "boolean" | "object" | "array";
+  readonly value: unknown;
+  constructor(kind: "zero" | "null" | "string" | "integer" | "float" | "boolean" | "object" | "array", value: unknown);
+  isZero(): boolean;
+  isNull(): boolean;
+  static fromJSON(v: unknown): Literal;
+}
+declare function parseSchema(data: string | SchemaDefinition | Record<string, unknown>): SchemaDefinition;
+//#endregion
+//#region src/schema/compile.d.ts
+/** Canonical field-type union, straight from the meta schema. */
+type FieldType$2 = FieldType;
+interface ResolvedEnum {
+  lookup: Map<string, unknown>;
+  complex: unknown[];
+  expectNumeric: boolean;
+}
+interface ResolvedNested {
+  id: string;
+  name: string;
+  effectiveType: FieldType$2;
+  fields: ResolvedField[];
+  isRecursive: boolean;
+  values?: unknown[];
+  enumDef?: ResolvedEnum;
+}
+interface ResolvedContainer {
+  itemSchema?: ResolvedNested;
+  itemType?: FieldType$2;
+  itemEnum?: ResolvedEnum;
+  record: boolean;
+}
+type ResolvedKind = {
+  tag: "scalar";
+} | {
+  tag: "enum";
+  enumDef: ResolvedEnum;
+} | {
+  tag: "object";
+  schema: ResolvedNested;
+} | {
+  tag: "container";
+  c: ResolvedContainer;
+} | {
+  tag: "union";
+  variants: ResolvedNested[];
+} | {
+  tag: "composite";
+  parts: ResolvedNested[];
+} | {
+  tag: "recursive";
+  schemaId: string;
+};
+interface ResolvedField {
+  id: string;
+  name: string;
+  path: string;
+  type: FieldType$2;
+  required: boolean;
+  deprecated: boolean;
+  unique: boolean;
+  nullable: boolean;
+  hasDefault: boolean;
+  kind: ResolvedKind;
+}
+declare class Compiler {
+  readonly source: SchemaDefinition;
+  private readonly nested;
+  private readonly building;
+  constructor(source: SchemaDefinition);
+  compile(): {
+    root: ResolvedField[];
+    schemas: Map<string, ResolvedNested>;
+  };
+  private compileNested;
+  private compileFields;
+  private compileField;
+  private resolve;
+  private require;
+  private synthesizeInline;
+}
+declare function buildEnum(values: unknown[], t?: FieldType$2): ResolvedEnum;
+//#endregion
+//#region src/schema/link.d.ts
+declare const FD_NO_CHILD = 63;
+declare const MAX_SCHEMA_SLOTS = 63;
+declare const MULTI_STEP_BASE: number;
+type FieldKind = 0 | 1 | 2 | 3;
+interface FieldDescriptor {
+  raw: number;
+  dt: number;
+  kind: FieldKind;
+  schemaIdx: number;
+  fieldIdx: number;
+  childSchemaIdx: number;
+  terminal: boolean;
+  required: boolean;
+  hasDefault: boolean;
+  deprecated: boolean;
+  unique: boolean;
+  nullable: boolean;
+  recursive: boolean;
+}
+/** Internal DataPoint (side-table identity) — compiled.go:186 formula. */
+declare function internalDP(fd: FieldDescriptor): number;
+declare function makeDescriptor(dt: number, kind: FieldKind, schemaIdx: number, fieldIdx: number, o: {
+  required: boolean;
+  hasDefault: boolean;
+  deprecated: boolean;
+  unique: boolean;
+  terminal: boolean;
+  nullable: boolean;
+  recursive: boolean;
+  child: number;
+}): FieldDescriptor;
+declare function unpackDescriptor(raw: number): FieldDescriptor;
+interface Slot {
+  fieldStart: number;
+  fieldCount: number;
+  footprint: number;
+}
+interface FieldMeta {
+  name: string;
+  path: string;
+}
+/** A linked field: everything the wire codec needs. */
+interface LinkedField {
+  meta: FieldMeta;
+  fd: FieldDescriptor;
+  /** Canonical user-data DataPoint written by the Sparse format. */
+  dp: number;
+  /** Absolute descriptor index across all slots. */
+  abs: number;
+  /** For array_object fields: the linked child slot's fields. */
+  child?: LinkedSlot;
+}
+interface LinkedSlot {
+  idx: number;
+  slot: Slot;
+  fields: LinkedField[];
+}
+interface LinkResult {
+  slots: Slot[];
+  metas: FieldMeta[];
+  descriptors: FieldDescriptor[];
+  localOffsets: number[];
+  fieldTypes: FieldType$2[];
+  root: LinkedSlot;
+  /** abs index of each root-level array_object field's linked child */
+  childrenByPath: Map<string, LinkedSlot>;
+}
+/**
+ * Address computation (address.go computeAddress).
+ * steps = [(schemaIdx,fieldIdx), ...] with the LAST step being the leaf.
+ */
+declare function addressForSteps(slots: Slot[], descriptors: FieldDescriptor[], localOffsets: number[], steps: Array<[number, number]>): number;
+/** Canonical Sparse DataPoint for an addressed leaf. */
+declare function userDataDP(dt: number, addr: number): number;
+declare function link(source: SchemaDefinition): LinkResult;
+interface ManifestField {
+  /** Field's declared name (relative to its own slot). */
+  name: string;
+  /** Full dotted mount path from the document root ("address.street"). */
+  path: string;
+  /** container.DataType name tag. */
+  t: string;
+  /** Canonical Sparse DataPoint. */
+  dp: number;
+  /** TypeArrayObject element fields (full mount paths). */
+  child?: ManifestField[];
+}
+/** Build the language-neutral wire manifest from linked tables. */
+declare function buildManifest(l: LinkResult): ManifestField[];
+//#endregion
+//#region src/schema/dt.d.ts
+declare const container: {
+  readonly TypeUnknown: 0;
+  readonly TypeInt: 1;
+  readonly TypeFloat: 2;
+  readonly TypeString: 3;
+  readonly TypeBool: 4;
+  readonly TypeBytes: 5;
+  readonly TypeGeometry: 6;
+  readonly TypeRecord: 7;
+  readonly TypeArrayUnknown: 8;
+  readonly TypeArrayInt: 9;
+  readonly TypeArrayFloat: 10;
+  readonly TypeArrayString: 11;
+  readonly TypeArrayBool: 12;
+  readonly TypeArrayBytes: 13;
+  readonly TypeArrayObject: 14;
+  readonly TypeArrayGeometry: 15;
+};
+//#endregion
+//#region src/wire/packet.d.ts
+declare const FLAG_COMPRESSED = 4;
+declare const FLAG_ENCRYPTED = 64;
+declare const FLAG_HASH_PRESENT = 128;
+type EncodeKind = "auto" | "dense" | "sparse";
+declare function encodeDocument(fields: ManifestField[], doc: Record<string, unknown>, fullVersion?: number, kind?: EncodeKind): Uint8Array;
+declare function decodeDocument(data: Uint8Array, fields: ManifestField[]): {
+  version: number;
+  doc: Record<string, unknown>;
+};
+declare function encodeBatchRows(fields: ManifestField[], docs: Record<string, unknown>[], fullVersion?: number): Uint8Array;
+declare function encodeBatchColumnar(fields: ManifestField[], docs: Record<string, unknown>[], fullVersion?: number): Uint8Array;
+declare function decodeBatch(data: Uint8Array, fields: ManifestField[]): {
+  version: number;
+  docs: Record<string, unknown>[];
+};
+//#endregion
+//#region src/wire/transforms.d.ts
+interface EncodeTransforms {
+  /** Compress the packet body (flags bit 2). */
+  compression?: boolean;
+  /** Embed BLAKE3-truncated digest over the plaintext body (bit 7). */
+  integrity?: boolean;
+  /** Seal with AES-256-GCM under this 32-byte key (bit 6). */
+  encryptionKey?: Uint8Array;
+}
+interface DecodeTransforms {
+  decryptionKey?: Uint8Array;
+}
+/** Full-duplex single-document encode with transforms. */
+declare function encodeAnansiPacket(fields: ManifestField[], doc: Record<string, unknown>, fullVersion?: number, opts?: EncodeTransforms & {
+  kind?: EncodeKind;
+}): Promise<Uint8Array>;
+/** Full-duplex single-document decode with transforms. */
+declare function decodeAnansiPacket(data: Uint8Array, fields: ManifestField[], opts?: DecodeTransforms): Promise<{
+  version: number;
+  doc: Record<string, unknown>;
+}>;
+/** Batch row-oriented encode with transforms. */
+declare function encodeAnansiBatchRows(fields: ManifestField[], docs: Record<string, unknown>[], fullVersion?: number, opts?: EncodeTransforms): Promise<Uint8Array>;
+/**
+ * Columnar batch encode. Transforms are supported only on the row paths —
+ * columnar ENCODE parity is still pending in TS; pass empty options to emit
+ * a plain packet (decoding transformed columnar packets IS supported).
+ */
+/** Columnar batch encode with transforms — full duplex. */
+declare function encodeAnansiBatchColumnar(fields: ManifestField[], docs: Record<string, unknown>[], fullVersion?: number, opts?: EncodeTransforms): Promise<Uint8Array>;
+/** Full-duplex batch decode (row dense/sparse and columnar) with transforms. */
+declare function decodeAnansiBatch(data: Uint8Array, fields: ManifestField[], opts?: DecodeTransforms): Promise<{
+  version: number;
+  docs: Record<string, unknown>[];
+}>;
+//#endregion
+//#region src/codec.d.ts
+interface AnansiCodecOptions extends EncodeTransforms {
+  /** Schema version stamped into outgoing packets (0–1023). */
+  fullVersion?: number;
+  /** Force Dense/Sparse instead of the density heuristic. */
+  kind?: EncodeKind;
+  /** Key used to decrypt incoming packets (if the server encrypts). */
+  decryptionKey?: Uint8Array;
+}
+declare class AnansiCodec {
+  readonly linked: LinkResult;
+  readonly fields: ManifestField[];
+  readonly fullVersion: number;
+  private readonly kind;
+  private readonly enc;
+  private readonly dec;
+  private constructor();
+  /**
+   * Compile a schema definition and bind it to a codec instance.
+   *
+   * ```ts
+   * const codec = await AnansiCodec.create(schemaJSON);            // plain
+   * const codec = await AnansiCodec.create(schemaJSON, {
+   *   fullVersion: 7,
+   *   transforms: { compression: true, integrity: true },
+   * });
+   * ```
+   *
+   * Instances are immutable; cache one per schema version (or per endpoint)
+   * and share it freely across requests.
+   */
+  static create(schema: string | SchemaDefinition | Record<string, unknown>, opts?: AnansiCodecOptions): Promise<AnansiCodec>;
+  /** Encode a single document (Dense/Sparse per configured strategy). */
+  encode(doc: Record<string, unknown>): Promise<Uint8Array>;
+  /** Decode a single-document packet. Accepts plain and transformed frames. */
+  decode(data: Uint8Array): Promise<{
+    version: number;
+    doc: Record<string, unknown>;
+  }>;
+  /** Encode many documents as one row-oriented batch. */
+  encodeBatch(docs: Record<string, unknown>[]): Promise<Uint8Array>;
+  /** Decode any batch packet (row dense/sparse, columnar, transformed). */
+  decodeBatch(data: Uint8Array): Promise<{
+    version: number;
+    docs: Record<string, unknown>[];
+  }>;
+  /**
+   * Columnar batch encode. Note: columnar output with transforms enabled is
+   * pending in TypeScript — with transforms unset this emits plain packets.
+   */
+  encodeColumnar(docs: Record<string, unknown>[]): Promise<Uint8Array>;
+}
+//#endregion
+//#region src/validation/types/hints.d.ts
+/**
+ * hints.ts
+ *
+ * Defines type hints for generating form input controls based on schema field definitions.
+ * Each hint type corresponds to a specific input control, providing metadata for code generation.
+ */
+/**
+ * Hints for generating a file input control.
+ */
+type FileHint = {
+  type: "file";
+  subtype: "video" | "audio" | "image" | "pdf" | "doc" | "txt";
+  label?: string;
+  embed?: boolean;
+  mimes?: string | string[];
+  preview?: boolean;
+  size?: {
+    max?: number;
+    min?: number;
+  };
+  dimensions?: {
+    width: number;
+    height: number;
+  };
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating a text-based input control.
+ */
+type TextHint = {
+  type: "text" | "email" | "tel" | "url" | "textarea";
+  label?: string;
+  placeholder?: string;
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating a secret input control (e.g., passwords, API keys).
+ */
+type SecretHint = {
+  type: "secret";
+  label?: string;
+  placeholder?: string;
+  password?: boolean;
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating a number-based input control.
+ */
+type NumberHint = {
+  type: "number" | "range" | "integer" | "decimal";
+  label?: string;
+  step?: number;
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating a boolean input control.
+ */
+type BooleanHint = {
+  type: "checkbox" | "radio";
+  label?: string;
+  radioLabels?: {
+    true: string;
+    false: string;
+  };
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating an enum input control.
+ */
+type EnumHint = {
+  type: "select" | "radio";
+  label?: string;
+  group?: string;
+  ignore?: boolean;
+  options?: Array<{
+    value: string | number;
+    label: string;
+  }>;
+};
+/**
+ * Hints for generating an array input control.
+ */
+type ArrayHint = {
+  type: "list";
+  label?: string;
+  itemHint?: {
+    type: string;
+  };
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating a set input control.
+ */
+type SetHint = {
+  type: "tags";
+  label?: string;
+  itemHint?: {
+    type: string;
+  };
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating an object input control.
+ */
+type ObjectHint = {
+  type: "group";
+  label?: string;
+  collapsible?: boolean;
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating a date input control.
+ */
+type DateHint = {
+  type: "date" | "datetime" | "time";
+  label?: string;
+  placeholder?: string;
+  min?: string;
+  max?: string;
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Hints for generating a code input control (e.g., for code snippets or scripts).
+ */
+type CodeHint = {
+  type: "code";
+  label?: string;
+  language?: string;
+  placeholder?: string;
+  readonly?: boolean;
+  editorOptions?: {
+    lineNumbers?: boolean;
+    wordWrap?: boolean;
+    minimap?: boolean;
+  };
+  group?: string;
+  ignore?: boolean;
+};
+/**
+ * Union type for all possible input hints.
+ * Note: DynamicHint removed to avoid overlap with TextHint; use TextHint for generic text needs.
+ */
+type InputHint = FileHint | TextHint | SecretHint | NumberHint | BooleanHint | EnumHint | ArrayHint | SetHint | ObjectHint | DateHint | CodeHint;
+/**
+ * Defines metadata for a group of inputs at the schema level.
+ */
+type GroupDefinition = {
+  name: string;
+  label?: string;
+  description?: string;
+};
+/**
+ * Defines hints at the schema level, including group metadata.
+ */
+type SchemaHint = {
+  groups?: GroupDefinition[];
+};
+//#endregion
+//#region src/validation/types/schema-definition.d.ts
+/**
+ * Basic field types supported by the schema system.
+ * Matches the `FieldTypeEnum` in the meta‑schema.
+ */
+type FieldType$1 = "unknown" | "string" | "number" | "integer" | "decimal" | "boolean" | "array" | "set" | "enum" | "object" | "record" | "union" | "composite" | "geometry" | "bytes";
+/**
+ * Index types for optimizing different query patterns.
+ * Matches the `IndexTypeEnum` in the meta‑schema.
+ */
+type IndexType$1 = "normal" | "unique" | "primary" | "spatial" | "fulltext";
+/**
+ * Logical operators used in constraint groups and index condition groups.
+ * Matches the `LogicalOperatorEnum` in the meta‑schema.
+ */
+type LogicalOperatorEnum$1 = "and" | "or" | "not" | "nor" | "xor" | "nand" | "xnor";
+/**
+ * Comparison operators for index conditions.
+ * Matches the `ComparisonOperatorEnum` in the meta‑schema.
+ */
+type ComparisonOperator$1 = "eq" | "neq" | "lt" | "lte" | "gt" | "gte" | "in" | "nin" | "contains" | "ncontains" | "exists" | "nexists";
+/**
+ * Inline type descriptor kinds.
+ * Matches the `InlineTypeEnum` in the meta‑schema.
+ */
+type InlineTypeKind$1 = "string" | "number" | "integer" | "decimal" | "boolean" | "bytes" | "unknown" | "record";
+/**
+ * Sort order for index fields.
+ * Matches the `IndexOrderEnum` in the meta‑schema.
+ */
+type IndexOrder$1 = "asc" | "desc";
+/**
+ * Shared metadata properties for most schema components.
+ */
+interface BaseMetadata extends Record<string, any> {
+  description?: string;
+  /** Arbitrary key‑value pairs for implementation‑specific metadata. */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Metadata for components that also have a human‑readable name.
+ */
+interface NamedMetadata extends BaseMetadata {
+  name: string;
+}
+/**
+ * Reference to another schema (e.g., for `object`, `array`, `union` types).
+ * May include local overrides for indexes and constraints.
+ */
+interface SchemaReference$1 extends BaseMetadata {
+  id: string;
+  indexes?: Record<string, IndexDefinition$1>;
+  constraints?: Record<string, Constraint$1 | ConstraintGroup$1>;
+}
+/**
+ * Inline type descriptor – used when a simple type is defined directly
+ * without a separate schema reference.
+ */
+interface InlineTypeDescriptor$1 extends BaseMetadata {
+  type: InlineTypeKind$1;
+  values?: Array<string | number>;
+}
+/**
+ * Defines a field within a schema.
+ * Matches the `Field` schema in the meta‑schema.
+ */
+interface FieldDefinition$1<T = unknown> extends NamedMetadata {
+  type: FieldType$1;
+  required?: boolean;
+  nullable?: boolean;
+  deprecated?: boolean;
+  unique?: boolean;
+  default?: T;
+  /**
+   * The `schema` property is used for complex types:
+   * - For `array`/`set`: a single `SchemaReference` pointing to the item schema.
+   * - For `object`: a single `SchemaReference` pointing to the object schema.
+   * - For `union`: an array of `SchemaReference`s.
+   * - For `enum`: an `InlineTypeDescriptor` (or `values` on the field itself).
+   * - For primitive overrides: an `InlineTypeDescriptor`.
+   */
+  schema?: SchemaReference$1 | SchemaReference$1[] | InlineTypeDescriptor$1;
+  /** @deprecated Use `schema` instead. */
+  nestedSchema?: SchemaReference$1;
+  hint?: {
+    input: InputHint;
+  };
+}
+/**
+ * A single index condition (leaf node).
+ * Matches the `IndexCondition` schema in the meta‑schema.
+ */
+interface IndexCondition$1 extends BaseMetadata {
+  operator: ComparisonOperator$1;
+  field: string;
+  value: unknown;
+}
+/**
+ * A group of index conditions combined with a logical operator.
+ * Matches the `IndexConditionGroup` schema in the meta‑schema.
+ */
+interface IndexConditionGroup$1 extends BaseMetadata {
+  operator: LogicalOperatorEnum$1;
+  conditions: Array<IndexCondition$1 | IndexConditionGroup$1>;
+}
+/**
+ * Defines an index for optimizing queries or enforcing uniqueness.
+ * Matches the `Index` schema in the meta‑schema.
+ */
+interface IndexDefinition$1 extends NamedMetadata {
+  unique?: boolean;
+  type: IndexType$1;
+  fields: string[];
+  order?: IndexOrder$1;
+  condition?: IndexCondition$1 | IndexConditionGroup$1;
+}
+/**
+ * A predicate‑based constraint rule.
+ * Matches the `ConstraintRule` schema in the meta‑schema.
+ */
+interface ConstraintRule$1 extends NamedMetadata {
+  predicate: string;
+  parameters?: unknown;
+  fields?: string[];
+}
+/**
+ * A group of constraints combined with a logical operator.
+ * Matches the `ConstraintGroup` schema in the meta‑schema.
+ */
+interface ConstraintGroup$1 extends NamedMetadata {
+  operator: LogicalOperatorEnum$1;
+  rules: Array<ConstraintRule$1 | ConstraintGroup$1>;
+}
+/**
+ * A constraint can be either a single rule or a logical group of rules.
+ * Matches the `Constraint` composite in the meta‑schema.
+ */
+type Constraint$1 = ConstraintRule$1 | ConstraintGroup$1;
+/**
+ * A reusable nested schema definition.
+ * Matches the `NestedSchema` schema in the meta‑schema.
+ *
+ * A nested schema can be either:
+ * - An **object schema** (with `fields`, and optionally `indexes`, `constraints`),
+ * - A **primitive type alias** (with `type` and optionally `default`, `values`, `schema`).
+ */
+type NestedSchemaDefinition$1<T = unknown> = NamedMetadata & {
+  indexes?: Record<string, IndexDefinition$1>;
+  constraints?: Record<string, Constraint$1>;
+} & ({
+  /**
+   * Object schema: defines the fields of the nested object.
+   * The `fields` record maps field IDs to `FieldDefinition`s.
+   */
+  fields: Record<string, FieldDefinition$1>;
+} | {
+  /**
+   * Primitive type alias.
+   * The `type` must not be `"object"``.
+   */
+  type: Exclude<FieldType$1, "object">;
+  default?: T;
+  values?: Array<string | number>;
+  schema?: SchemaReference$1 | SchemaReference$1[];
+});
+/**
+ * Defines a complete schema.
+ * Matches the top‑level `Schema` structure in the meta‑schema.
+ */
+interface SchemaDefinition$1 extends NamedMetadata {
+  version: string;
+  /** Map of field IDs to field definitions. */
+  fields: Record<string, FieldDefinition$1>;
+  /** Map of index IDs to index definitions. */
+  indexes?: Record<string, IndexDefinition$1>;
+  /** Map of constraint IDs to constraint definitions. */
+  constraints?: Record<string, Constraint$1>;
+  /** Map of nested schema IDs to nested schema definitions. */
+  schemas?: Record<string, NestedSchemaDefinition$1>;
+  /**
+   * Optional data migration definitions.
+   * @extension
+   */
+  migrations?: Array<Migration>;
+  /**
+   * UI/input hints.
+   * @extension
+   */
+  hints?: SchemaHint;
+  /**
+   * Mock data generator.
+   * @extension
+   */
+  mock?: <T>(
+  /** Lazy-typed: @faker-js/faker is a dev-only peer; kept out of bundle. */
+  faker: unknown) => Generator<T, void, unknown>;
+  /**
+   * Domain dependencies.
+   * @extension
+   */
+  dependencies?: string[];
+  /** @deprecated Use `schemas` instead. */
+  nestedSchemas?: Record<string, NestedSchemaDefinition$1>;
+  /** @deprecated Use top‑level `indexes`, `constraints`, `schemas` directly. */
+  registry?: {
+    schemas?: Record<string, NestedSchemaDefinition$1>;
+    constraints?: Record<string, Constraint$1>;
+    indexes?: Record<string, IndexDefinition$1>;
+  };
+}
+/**
+ * Implements Partial Update Semantics:
+ * - `undefined`: No change to the property.
+ * - `null`: Clear/remove the property (if allowed by NonNullable).
+ * - `value`: Set the property to the provided value.
+ */
+type Patch<T, NonNullable extends keyof T = never> = { [K in keyof T]?: K extends NonNullable ? T[K] : T[K] | null; };
+type FieldPatch = Patch<FieldDefinition$1, "name" | "type">;
+type ConstraintPatch = Patch<Constraint$1, "name">;
+type IndexPatch = Patch<IndexDefinition$1, "name">;
+type SchemaChange = {
+  type: "modifyProperty";
+  id: keyof NamedMetadata | "version";
+  value: any;
+} | {
+  type: "addField";
+  id: string;
+  definition: FieldDefinition$1;
+} | {
+  type: "removeField";
+  id: string;
+} | {
+  type: "modifyField";
+  id: string;
+  changes: FieldPatch;
+} | {
+  type: "addIndex";
+  id: string;
+  definition: IndexDefinition$1;
+} | {
+  type: "removeIndex";
+  id: string;
+} | {
+  type: "modifyIndex";
+  id: string;
+  changes: IndexPatch;
+} | {
+  type: "addConstraint";
+  id: string;
+  constraint: Constraint$1;
+} | {
+  type: "removeConstraint";
+  id: string;
+} | {
+  type: "modifyConstraint";
+  id: string;
+  changes: ConstraintPatch;
+} | {
+  type: "addSchema";
+  id: string;
+  definition: NestedSchemaDefinition$1;
+} | {
+  type: "removeSchema";
+  id: string;
+} | {
+  type: "modifySchema";
+  id: string;
+  changes: Array<SchemaChange>;
+};
+type TransformFunction<Initial, Next> = (ctx: any, data: Initial) => Next | Promise<Next>;
+interface DataTransform<Initial, Next> {
+  forward: TransformFunction<Initial, Next>;
+  backward: TransformFunction<Next, Initial>;
+}
+interface Migration<Initial = any, Next = any> {
+  id: string;
+  version: {
+    source: string;
+    target?: string;
+  };
+  changes: SchemaChange[];
+  description: string;
+  rollback?: SchemaChange[];
+  transform: string | DataTransform<Initial, Next>;
+  createdAt: string;
+  dependencies?: string[];
+  checksum: string;
+}
+//#endregion
+//#region src/validation/types/validator.d.ts
+/** A single validation failure produced by a node. */
+interface Issue {
+  /** Machine-readable error code (e.g. "TYPE_MISMATCH", "REQUIRED_FIELD_MISSING"). */
+  code: string;
+  /** Human-readable description. */
+  message: string;
+  /** Dot-separated path to the offending value (e.g. "user.address.street"). */
+  path: string;
+}
+/**
+ * Controls how strictly the validator interprets missing / unexpected fields.
+ *
+ * - `strict`        — full validation; required, unexpected, type, and constraint issues are all reported.
+ * - `partialStrict` — missing-required issues are suppressed; everything else is reported.
+ * - `loose`         — missing-required *and* unexpected-field issues are both suppressed.
+ */
+type ValidationMode = "strict" | "partialStrict" | "loose";
+interface ValidationConfig {
+  /** Maximum nesting depth before aborting recursive traversal. Default: 20. */
+  maxDepth: number;
+  /** Validation strictness mode. Default: "strict". */
+  mode: ValidationMode;
+}
+declare function defaultValidationConfig(): ValidationConfig;
+/** Parameters passed to every predicate invocation. */
+interface PredicateParams {
+  /** The original top-level document (never changes across recursive calls). */
+  root: Record<string, unknown>;
+  /**
+   * The data being validated at the current scope.
+   * For global constraints this is the full root; for recursive/nested constraints
+   * this is the sub-document at the constraint's base path.
+   */
+  data: unknown;
+  /** Resolved field keys (relative to `data`) that the predicate should inspect. */
+  keys: string[];
+  /** Arbitrary predicate-specific parameters declared in the schema. */
+  parameters?: unknown;
+}
+/**
+ * A predicate function.
+ * Returns an array of Issues (empty = success).
+ * May be synchronous or asynchronous.
+ */
+type PredicateFn = (params: PredicateParams) => Issue[] | Promise<Issue[]>;
+/** Map of predicate name → predicate function. */
+type PredicateMap = Record<string, PredicateFn>;
+/**
+ * A leaf constraint: a named predicate with optional field paths and parameters.
+ * Mirrors Go's `ConstraintRule`.
+ */
+interface ValidatorConstraintRule {
+  kind: "rule";
+  name: string;
+  description: string | undefined;
+  predicate: string;
+  parameters: unknown;
+  fields: string[];
+}
+/**
+ * A logical group of constraints combined with a `LogicalOperator`.
+ * Mirrors Go's `ConstraintGroup`.
+ */
+interface ValidatorConstraintGroup {
+  kind: "group";
+  name: string;
+  description: string | undefined;
+  operator: string;
+  rules: ValidatorConstraint[];
+}
+/** A constraint is either a single rule or a logical group of rules. */
+type ValidatorConstraint = ValidatorConstraintRule | ValidatorConstraintGroup;
+/** Keyed map of constraint ID → ValidatorConstraint. */
+type SchemaConstraintMap = Record<string, ValidatorConstraint>;
+interface NodeResult {
+  issues: Issue[];
+  success: boolean;
+  skipped: boolean;
+}
+interface ValidationContext {
+  /** The original top-level document; never changes. */
+  originalRoot: Record<string, unknown>;
+  /** The current root being validated (may be a sub-document for recursive schemas). */
+  rootData: unknown;
+  /** Alias for rootData — kept for parity with Go. */
+  data: unknown;
+  /** The predicate function registry. */
+  functionMap: PredicateMap;
+  /** Maximum allowed nesting depth. */
+  maxDepth: number;
+  /** Validation strictness. */
+  mode: ValidationMode;
+  /**
+   * Per-node success state. Index = node ID, value = success (true) | failure (false) | absent (undefined).
+   * Used by the traversal loop to propagate skipping when a dependency failed.
+   */
+  visited: Map<number, boolean>;
+  /** Accumulated issues for this traversal. */
+  issues: Issue[];
+}
+//#endregion
+//#region src/validation/nodes.d.ts
+interface ValidationNode {
+  execute(ctx: ValidationContext): Promise<NodeResult>;
+  getDependencies(): number[];
+  getID(): number;
+  getPath(): string;
+  getPathParts(): string[];
+}
+//#endregion
+//#region src/validation/graph.d.ts
+declare class BuildContext {
+  /** Ref-count of schemas currently being built. */
+  private readonly buildingSchemas;
+  /** Cache of pre-built recursive graphs keyed by schemaID + constraint hash. */
+  private readonly recursiveGraphCache;
+  isRecursive(schemaID: string): boolean;
+  markBuilding(schemaID: string): void;
+  unmarkBuilding(schemaID: string): void;
+  makeGraphCacheKey(schemaID: string, constraints: SchemaConstraintMap): string;
+  getOrBuildRecursiveGraph(schemaID: string, schemaDef: NestedSchemaDefinition$1, instanceConstraints: SchemaConstraintMap, topLevelSchema: SchemaDefinition$1): Promise<ValidationGraph>;
+}
+/** Internal tracking node used only during graph construction. */
+interface TrackNode {
+  id: number;
+  deps: number[];
+}
+declare class ValidationGraph {
+  private nodes;
+  private dependencies;
+  private visitedState;
+  private executionOrder;
+  private nextNodeID;
+  /** Paths explicitly marked nullable:true (null is a legal value). */
+  readonly nullablePaths: Set<string>;
+  buildNodeID(): number;
+  addNode(node: ValidationNode): void;
+  private createUnexpectedFieldsNode;
+  private createRequiredFieldNode;
+  private createTypeCheckNode;
+  private createCompletionNode;
+  finalize(): void;
+  traverse(fmap: PredicateMap, document: Record<string, unknown>, mode: ValidationMode, maxDepth: number, originalRoot: Record<string, unknown>): Promise<Issue[]>;
+  /**
+   * Builds the validation graph from a SchemaDefinition.
+   * Returns the root TrackNodes (for wiring dependencies).
+   * Mirrors Go's `graph.buildFromSchema`.
+   */
+  buildFromSchema(schema: SchemaDefinition$1, basePath: string, baseParts: string[], addedConstraints: Map<string, boolean>, nsd: NestedSchemaDefinition$1 | null, schemaRefConstraints: SchemaConstraintMap, topLevelSchema: SchemaDefinition$1, buildCtx: BuildContext, skipUnexpectedCheck: boolean, skipUnexpectedForObjects: boolean): Promise<TrackNode[]>;
+  private buildFieldNodes;
+  private buildFieldTypeNodes;
+  private buildObjectFieldNodes;
+  /**
+   * Mirrors Go's `buildContainerNode`.
+   * Returns an ArrayValidationNode or RecordValidationNode depending on `itemKind`.
+   */
+  private buildContainerNode;
+  private buildEnumNode;
+  private buildUnionNode;
+  private buildCompositeNode;
+  private buildFromEffectiveConstraints;
+  private buildFromConstraintRuleWithScope;
+  /**
+   * Creates a standalone ValidationGraph for a single field, used by array /
+   * record / union / composite nodes.
+   * Mirrors Go's `graph.createSubGraph`.
+   */
+  createSubGraph(rootFieldName: string, rootFieldDef: FieldDefinition$1, basePath: string, originalTopLevelSchema: SchemaDefinition$1, buildCtx: BuildContext, skipUnexpectedCheck: boolean, skipUnexpectedForObjects: boolean): Promise<ValidationGraph>;
+}
+//#endregion
+//#region src/validation/validator.d.ts
+declare class DocumentValidator {
+  private readonly fmap;
+  private readonly graph;
+  private readonly config;
+  protected constructor(graph: ValidationGraph, fmap: PredicateMap, config: ValidationConfig);
+  /**
+   * Full validation: reports missing required fields, unexpected fields,
+   * type mismatches, and constraint violations.
+   */
+  validate(document: Record<string, unknown>): Promise<Issue[]>;
+  /**
+   * Partial-strict validation: suppresses REQUIRED_FIELD_MISSING issues.
+   * Use when validating partial updates (e.g. PATCH payloads).
+   */
+  validatePartial(document: Record<string, unknown>): Promise<Issue[]>;
+  /**
+   * Loose validation: suppresses both REQUIRED_FIELD_MISSING and
+   * UNEXPECTED_FIELD issues.  Validates only present fields for type and
+   * constraints.
+   */
+  validateLoose(document: Record<string, unknown>): Promise<Issue[]>;
+  /**
+   * Builds a DocumentValidator from a SchemaDefinition.
+   *
+   * This compiles the schema into a validation DAG exactly once; subsequent
+   * calls to `validate()` / `validatePartial()` / `validateLoose()` traverse
+   * the pre-compiled graph and are fast.
+   *
+   * Throws if the schema contains structural errors that prevent graph construction
+   * (e.g. dangling schema references, composite parts with unsupported types).
+   */
+  static create(schema: SchemaDefinition$1, fmap: PredicateMap, config?: ValidationConfig): Promise<DocumentValidator>;
+}
+//#endregion
+//#region src/validation/schema-validator.d.ts
+/**
+ * A dedicated validator for ensuring schema definitions themselves
+ * conform to the meta-schema rules.
+ */
+declare class SchemaValidator {
+  private static validator;
+  /**
+   * Validates a schema definition against the meta-schema rules.
+   */
+  static validate(schemaDef: SchemaDefinition$1): Promise<Issue[]>;
+}
+//#endregion
+//#region src/validation/predicates.d.ts
+declare const metaSchemaPredicateMap: PredicateMap;
+//#endregion
+export { AnansiCodec, type AnansiCodecOptions, ComparisonOperator, Compiler, Constraint, ConstraintGroup, ConstraintMetadata, ConstraintRule, ConstraintUnion, container as DataTypes, type DecodeTransforms, DocumentValidator, type EncodeKind, type EncodeTransforms, FD_NO_CHILD, FLAG_COMPRESSED, FLAG_ENCRYPTED, FLAG_HASH_PRESENT, FieldDef, FieldDefinition, type FieldDescriptor, FieldType, IndexCondition, IndexConditionGroup, IndexConditionUnion, IndexDefinition, IndexOrder, IndexType, InlineTypeDescriptor, InlineTypeKind, type Issue, type LinkResult, type LinkedField, type LinkedSlot, Literal, LogicalOperatorEnum, MAX_SCHEMA_SLOTS, MULTI_STEP_BASE, type ManifestField, NestedSchemaDefinition, type PredicateMap, type ResolvedEnum, type ResolvedField, type ResolvedNested, SchemaDefinition, SchemaReference, SchemaReferenceArray, SchemaValidator, type Slot, String, Unknown, type ValidationConfig, addressForSteps, buildEnum, buildManifest, decodeAnansiBatch, decodeAnansiPacket, decodeBatch, decodeDocument, defaultValidationConfig, encodeAnansiBatchColumnar, encodeAnansiBatchRows, encodeAnansiPacket, encodeBatchColumnar, encodeBatchRows, encodeDocument, internalDP, link, makeDescriptor, metaSchemaPredicateMap, parseSchema, unpackDescriptor, userDataDP };