akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/constant/fieldInfo.ts

@@ -106,12 +106,7 @@ export interface ConstantFieldProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
-  /**
-   * Renders on the page, never reaches an agent. Stripped wherever a value is masked for an AI caller — the
-   * in-page agent's reads and every MCP result — and left untouched everywhere else, so a `File`'s blur
-   * placeholder still ships to `<Image>`. Unlike `hidden`/`secret` this is about cost, not secrecy: a field
-   * nothing can answer a question with is pure spend on every turn it rides.
-   */
+  /** Stripped from every AI-facing read (in-page agent, MCP) and untouched everywhere else: cost, not secrecy. */
   visual?: boolean;
   meta?: Metadata;
 }
@@ -279,7 +274,6 @@ export type FieldInfoObjectToFieldObject<Obj extends FieldInfoObject> = {
   [K in keyof Obj]: ConstantFieldFromInfo<Obj[K]>;
 };
 
-/** Runtime metadata for a single Akan constant field. */
 export class ConstantField<
   FieldType extends ConstantFieldKind = ConstantFieldKind,
   Value extends ConstantFieldTypeInput | null = any,
@@ -309,31 +303,31 @@ export class ConstantField<
       count: field(Int, { default: 0, accumulate: {} }).toField(),
     };
   }
-  readonly nullable: Nullable;
-  readonly ref?: string;
-  readonly refPath?: string;
-  readonly refType?: "child" | "parent" | "relation";
-  readonly default: FieldValue | ((doc: { id: string }) => FieldValue);
-  readonly type?: FieldPreset;
-  readonly fieldType: FieldType;
-  readonly immutable: boolean;
-  readonly min?: number;
-  readonly max?: number;
-  readonly enum?: EnumInstance;
-  readonly select: boolean;
-  readonly minlength?: number;
-  readonly maxlength?: number;
-  readonly accumulate?: any;
-  readonly example?: FieldValue;
-  readonly of?: MapValue; 
-  readonly validate?: (value: FieldValue, model: any) => boolean;
-  readonly text?: TextFieldRole;
-  readonly cascade?: CascadeAction;
-  readonly visual: boolean;
-  readonly modelRef: ConstantModelRef;
-  readonly arrDepth: number;
-  readonly optArrDepth: number;
-  readonly meta: Metadata;
+  declare readonly nullable: Nullable;
+  declare readonly ref?: string;
+  declare readonly refPath?: string;
+  declare readonly refType?: "child" | "parent" | "relation";
+  declare readonly default: FieldValue | ((doc: { id: string }) => FieldValue);
+  declare readonly type?: FieldPreset;
+  declare readonly fieldType: FieldType;
+  declare readonly immutable: boolean;
+  declare readonly min?: number;
+  declare readonly max?: number;
+  declare readonly enum?: EnumInstance;
+  declare readonly select: boolean;
+  declare readonly minlength?: number;
+  declare readonly maxlength?: number;
+  declare readonly accumulate?: any;
+  declare readonly example?: FieldValue;
+  declare readonly of?: MapValue; 
+  declare readonly validate?: (value: FieldValue, model: any) => boolean;
+  declare readonly text?: TextFieldRole;
+  declare readonly cascade?: CascadeAction;
+  declare readonly visual: boolean;
+  declare readonly modelRef: ConstantModelRef;
+  declare readonly arrDepth: number;
+  declare readonly optArrDepth: number;
+  declare readonly meta: Metadata;
   declare _isScalar: IsScalar;
   declare _isRelation: IsRelation;
   declare _isEnum: IsEnum;
@@ -342,31 +336,7 @@ export class ConstantField<
   declare _isSecret: IsSecret;
   declare _isMap: IsMap;
   constructor(props: ConstantFieldBuildProps<FieldType, FieldValue, MapValue, Metadata>) {
-    this.nullable = props.nullable as unknown as Nullable;
-    this.ref = props.ref;
-    this.refPath = props.refPath;
-    this.refType = props.refType;
-    this.default = props.default;
-    this.type = props.type;
-    this.fieldType = props.fieldType;
-    this.immutable = props.immutable;
-    this.min = props.min;
-    this.max = props.max;
-    this.enum = props.enum;
-    this.select = props.select;
-    this.minlength = props.minlength;
-    this.maxlength = props.maxlength;
-    this.accumulate = props.accumulate;
-    this.example = props.example;
-    this.of = props.of;
-    this.validate = props.validate;
-    this.text = props.text;
-    this.cascade = props.cascade;
-    this.visual = props.visual;
-    this.modelRef = props.modelRef;
-    this.arrDepth = props.arrDepth;
-    this.optArrDepth = props.optArrDepth;
-    this.meta = props.meta;
+    Object.assign(this, props);
   }
 
   static fromFieldInfo<
@@ -468,57 +438,15 @@ export class ConstantField<
     return this.#props;
   }
   #buildProps(): FieldProps {
-    return {
-      nullable: this.nullable as unknown as boolean,
-      ref: this.ref,
-      refPath: this.refPath,
-      refType: this.refType,
-      default: this.default,
-      type: this.type,
-      fieldType: this.fieldType,
-      immutable: this.immutable,
-      min: this.min,
-      max: this.max,
-      enum: this.enum,
-      select: this.select,
-      minlength: this.minlength,
-      maxlength: this.maxlength,
-      accumulate: this.accumulate,
-      example: this.example,
-      of: this.of,
-      validate: this.validate,
-      text: this.text,
-      cascade: this.cascade,
-      visual: this.visual,
-      modelRef: this.modelRef,
-      arrDepth: this.arrDepth,
-      optArrDepth: this.optArrDepth,
-      meta: this.meta,
-      isClass: this.isClass,
-      isScalar: this.isScalar,
-      isArray: this.isArray,
-      isMap: this.isMap,
-    };
+    return { ...this, isClass: this.isClass, isScalar: this.isScalar, isArray: this.isArray, isMap: this.isMap };
   }
 }
 export interface FieldObject {
   [key: string]: ConstantField;
 }
 
-/**
- * `text` names a column in the plaintext search mirror, so a masked field carrying one would publish what it
- * masks through search — the class build refuses it (`TextFieldPaths`). Removing the key from the option type
- * moves that refusal to the call site, where the fix is obvious. Distributive because `FieldOption` is a union:
- * a plain `Omit` over it would collapse to the keys the members share.
- */
 type WithoutTextRole<Option> = Option extends unknown ? Omit<Option, "text"> : never;
 
-/**
- * A wildcard owner is read off the row at removal time, so `removeWithAny` without a `refPath` names nothing to
- * read it from — and the price of that action (no cascade in the app removes in one query) is one nobody should
- * pay for a declaration that cascades nothing. Pairing the two in the option type refuses it at the call site;
- * `CascadePaths` keeps the same refusal for the macro and bundled paths that reach it without a typecheck.
- */
 type CascadeOption =
   | { cascade?: "removeRef" | "removeWith"; refPath?: string }
   | { cascade: "removeWithAny"; refPath: string };
@@ -552,7 +480,6 @@ export type PlainTypeToFieldType<PlainType> = PlainType extends [infer First, ..
       ? StringConstructor
       : typeof Any;
 
-/** Builds a stored property field with optional validation, default, ref, text, and metadata options. */
 export const field = <
   ExplicitType,
   Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,
@@ -566,13 +493,7 @@ export const field = <
     fieldType: "property",
   });
 
-/**
- * A stored property the page renders and an agent never sees — `field(value, { visual: true })`, spelled short
- * because the reason to reach for it is always the same one. A blur placeholder, a rendered HTML body, a
- * serialized geometry: real data the screen needs, and hundreds of tokens per record that no question is answered
- * from. It stays a plain `property` everywhere else, so persistence, search, forms and the page response are
- * untouched.
- */
+/** `field(value, { visual: true })`: a stored property the page renders and an agent never sees. */
 field.visual = <
   ExplicitType,
   Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,
@@ -613,7 +534,7 @@ field.secret = <
     select: false,
     nullable: true,
   });
-/** Builds a resolved field that is derived rather than treated as a stored property. */
+/** A derived field, never stored. */
 export const resolve = <
   ExplicitType,
   Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,

package/constant/fieldQueryMeta.ts

@@ -2,19 +2,12 @@ import { FIELD_META } from "akanjs/base";
 import { ConstantRegistry } from "./constantRegistry";
 import type { FieldObject } from "./fieldInfo";
 
-/**
- * The query a field's value stands for, declared on the field itself with `.meta(...)`. A summary counter is the
- * case this exists for: `hau` is however many rows one filter returns, so the tile showing it can open that exact
- * listing without the page restating the filter beside it.
- *
- * The shape is read structurally rather than by class, so an app declares it with whatever builder it already has.
- */
+/** The query a field's value counts, declared with `.meta(...)`; read structurally, so any builder can produce it. */
 export interface FieldQueryMeta {
-  /** The model the query runs against. */
   refName: string;
   /** One of that model's declared filter keys. */
   queryKey: string | null;
-  /** Read when the query is applied, so an arg relative to now — `() => [dayjs().subtract(1, "hour")]` — is current. */
+  /** A thunk is read when the query is applied, so an arg relative to now stays current. */
   queryArgs?: unknown[] | (() => unknown[]);
 }
 
@@ -26,7 +19,6 @@ const isFieldQueryMeta = (meta: unknown): meta is FieldQueryMeta => {
   return queryArgs === undefined || Array.isArray(queryArgs) || typeof queryArgs === "function";
 };
 
-/** The query one field of `refName` names, or nothing when the model, the field, or the declaration is absent. */
 export const fieldQueryMetaOf = (refName: string, field: string): FieldQueryMeta | undefined => {
   const cnst = ConstantRegistry.getDatabase(refName, { allowEmpty: true });
   const fieldMap = cnst?.full[FIELD_META] as FieldObject | undefined;

package/constant/getDefault.ts

@@ -5,17 +5,13 @@ import type { DefaultOf } from "./types";
 export interface DefaultPlan {
   /** Fields whose default is a value that can be shared: a primitive, `null`, or the field's own literal. */
   shared: Record<string, unknown>;
-  /** Fields that have to be produced per call — a thunk, a fresh array, or a nested scalar record. */
+  /** Fields produced per call: a thunk, a fresh array, a nested scalar record, or a primitive's structured default. */
   perCall: Map<string, () => unknown>;
 }
 
 const planCache = new WeakMap<FieldObject, DefaultPlan>();
 
-/**
- * The split is what keeps this faithful: `default: () => dayjs()` still means "now" on every call, and an array
- * or nested-scalar default is still a fresh object, so two documents filled from the same model never end up
- * sharing one. Only values that were already shared before this cache existed live in `shared`.
- */
+/** A thunk default runs per call and an array or nested-scalar default is fresh, so no two results share one. */
 export const getDefault = <T>(fieldObj: FieldObject): DefaultOf<T> => {
   const plan = defaultPlanOf(fieldObj);
   const result: Record<string, unknown> = { ...plan.shared };
@@ -23,7 +19,7 @@ export const getDefault = <T>(fieldObj: FieldObject): DefaultOf<T> => {
   return result as DefaultOf<T>;
 };
 
-/** The per-field default rules, split as above; `HydrationPlan` reads them per field so a present value skips its thunk. */
+/** Read per field by `HydrationPlan`, so a present value skips its default thunk. */
 export const defaultPlanOf = (fieldObj: FieldObject): DefaultPlan => {
   const cached = planCache.get(fieldObj);
   if (cached) return cached;
@@ -49,7 +45,19 @@ const buildPlan = (fieldObj: FieldObject): DefaultPlan => {
     else if (field.isClass) {
       if (field.isScalar) perCall.set(key, () => getDefault(field.modelRef[FIELD_META]));
       else shared[key] = null;
-    } else shared[key] = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
+    } else {
+      const primitiveDefault = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
+      if (isStructured(primitiveDefault)) perCall.set(key, () => structuredClone(primitiveDefault));
+      else shared[key] = primitiveDefault;
+    }
   }
   return { shared, perCall };
 };
+
+const isStructured = (value: unknown): value is object =>
+  typeof value === "object" &&
+  value !== null &&
+  (Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+/** Copies a plain object or array; an instance (`Dayjs`, `Uint8Array`) is returned as is, keeping its prototype. */
+export const freshPrimitiveValue = <T>(value: T): T => (isStructured(value) ? structuredClone(value) : value);

package/constant/hydrationPlan.ts

@@ -17,14 +17,6 @@ interface PlanOwner {
   [FIELD_META]: FieldObject;
 }
 
-/**
- * One hydration plan per model class, compiled from `FIELD_META` on the first instance. Reading the field map,
- * resolving `getProps()` and dispatching on the field kind used to happen per field per instance, and was most of
- * what a listing paid after the dayjs objects — a plan turns a row into a plain loop over precomputed converters.
- *
- * Cached per class rather than per field map because `fullModelOf` extends a lib model's `FIELD_META` in place;
- * `applyConstantStatics` resets the entry whenever it finishes wiring a class.
- */
 export class HydrationPlan {
   static #byClass = new WeakMap<object, HydrationPlan>();
   static of(cls: PlanOwner): HydrationPlan {
@@ -47,7 +39,7 @@ export class HydrationPlan {
       const convert: Converter = isDateSlot ? toDateValue : converterOf(props);
       const perCall = defaults.perCall.get(key);
       const rawDefault = perCall ?? (() => defaults.shared[key]);
-
+      
       return { key, target: isDateSlot ? dateSlotOf(key) : key, convert, makeDefault: () => convert(rawDefault()) };
     });
   }

package/constant/index.ts

@@ -2,7 +2,6 @@ export * from "./cascadePaths";
 export * from "./constantRegistry";
 export * from "./crystalize";
 export * from "./dateSlot";
-export * from "./deserialize";
 export * from "./fieldInfo";
 export * from "./fieldQueryMeta";
 export * from "./getDefault";

package/constant/labelOf.ts

@@ -1,9 +1,4 @@
-/**
- * The one line a human scans for. A model that writes its own `Light<Model>.label()` owns the answer, since
- * display logic is the Light class's job; otherwise it is derived from what the model already declared — the
- * `text: "title"` search role names exactly that field, so an agent-facing label costs no new declaration.
- * Falls back to the conventional `title`/`name` keys; the id is the caller's floor.
- */
+/** The model's own `label()`, else its `text: "title"` field, else `title`/`name`; the id is the caller's floor. */
 export const labelOf = (model: unknown, value: unknown): string | undefined => {
   if (!value || typeof value !== "object") return undefined;
   const source = value as Record<string, unknown>;

package/constant/mask.ts

@@ -1,20 +1,17 @@
-import { FIELD_META } from "akanjs/base";
+import { type Cls, FIELD_META, getNonArrayModel, type PrimitiveAgentFace, PrimitiveRegistry } from "akanjs/base";
 
-/**
- * A model as masking reads it — the constructor, for the field metadata it carries at runtime.
- *
- * Structural rather than `ConstantModelRef` so that anything holding the class can name it, and read through
- * `FIELD_META` the way `resolveReturn` reads it.
- */
+/** Structural rather than `ConstantModelRef`, so anything holding the class can name it; read through `FIELD_META`. */
 export interface MaskModel {
   name: string;
 }
 
-/** The part of a field's metadata masking turns on. Mirrors what `resolveReturn` branches over. */
 interface MaskField {
   fieldType?: string;
   isClass?: boolean;
+  isMap?: boolean;
   modelRef?: MaskModel;
+  of?: unknown;
+  arrDepth?: number;
   visual?: boolean;
 }
 
@@ -23,12 +20,7 @@ export const maskFieldsOf = (model: MaskModel): Record<string, MaskField> | null
   return fields && typeof fields === "object" ? (fields as Record<string, MaskField>) : null;
 };
 
-/**
- * The `hidden` and `secret` field names of `model` that `value` still carries populated.
- *
- * `visual` is deliberately not among them. A refusal here means a value must not be published at all, and a blur
- * placeholder is not a secret — it is merely not worth its tokens, which masking answers by dropping it.
- */
+/** The `hidden`/`secret` fields `value` still carries; `visual` is cost, not secrecy, so it never counts as a leak. */
 export const leakingFieldsOf = (model: MaskModel, value: Record<string, unknown>): string[] => {
   const fields = maskFieldsOf(model);
   if (!fields) return [];
@@ -38,19 +30,8 @@ export const leakingFieldsOf = (model: MaskModel, value: Record<string, unknown>
 };
 
 /**
- * Strips what a model marks `hidden`, `secret`, or `visual`, by the model the caller names rather than by the one
- * the value happens to still carry. The first two are secrecy and the third is cost, but the answer is the same
- * one — leave the field out — and this is the only place every AI-facing read already passes through.
- *
- * That distinction is the whole point. A check that reads the class off the value can only mask what arrives as an
- * instance, so a `{ ...doc }` spread, a `toJSON()`, an `immerify()`, or a round-trip through `JSON.stringify` reaches
- * its destination with the metadata already gone and nothing can be done about it. A named model is metadata the
- * value cannot lose, so a hydrated document and a plain object copied out of one mask identically.
- *
- * This is the field half of `resolveReturn` and deliberately not the whole of it. That one also loads every relation
- * it walks past, which is right for a query's return value and wrong here, where the value is already in hand.
- *
- * Returns `unknown` rather than the argument's type, because what comes back is missing fields that type promises.
+ * Drops `hidden`, `secret` and `visual` fields for every AI-facing read, by the model named rather than the value's
+ * class, so a spread or JSON copy masks the same; unlike `resolveReturn` it loads no relation.
  */
 export const mask = (model: MaskModel, value: unknown): unknown => {
   if (value === null || value === undefined || typeof value !== "object") return value;
@@ -61,22 +42,39 @@ export const mask = (model: MaskModel, value: unknown): unknown => {
   const masked: Record<string, unknown> = {};
   for (const [key, field] of Object.entries(fields)) {
     if (field.fieldType === "hidden" || field.fieldType === "secret" || field.visual || !(key in source)) continue;
-    masked[key] = field.isClass && field.modelRef ? mask(field.modelRef, source[key]) : source[key];
+    masked[key] = maskField(field, source[key]);
   }
   return masked;
 };
 
+/** The primitive's `agent.read` through `arrDepth` array levels when it declares an agent face; the value otherwise. */
+export const agentRead = (modelRef: unknown, value: unknown, arrDepth = 0): unknown => {
+  const face = PrimitiveRegistry.agentOf(modelRef);
+  return face ? readThrough(face, value, arrDepth) : value;
+};
+
+const readThrough = (face: PrimitiveAgentFace, value: unknown, arrDepth: number): unknown => {
+  if (value === null || value === undefined) return value;
+  if (arrDepth > 0 && Array.isArray(value)) return value.map((item) => readThrough(face, item, arrDepth - 1));
+  return face.read(value);
+};
+
+const maskField = (field: MaskField, value: unknown): unknown => {
+  if (field.isClass && field.modelRef) return mask(field.modelRef, value);
+  if (field.isMap) return maskMapValues(field.of, value);
+  return agentRead(field.modelRef, value, field.arrDepth ?? 0);
+};
+
+const maskMapValues = (of: unknown, value: unknown): unknown => {
+  const [valueRef, arrDepth] = getNonArrayModel(of as Cls);
+  if (!PrimitiveRegistry.agentOf(valueRef) || value === null || typeof value !== "object") return value;
+  const entries = value instanceof Map ? [...value.entries()] : Object.entries(value);
+  return Object.fromEntries(entries.map(([key, item]) => [key, agentRead(valueRef, item, arrDepth)]));
+};
+
 /**
- * Drops what a model marks `hidden` or `secret`, and nothing else.
- *
- * The sibling of `mask()` for the one caller that is not an AI read: a saved form draft. Two differences matter.
- * It keeps `visual` — a rendered body is exactly the field a user spent twenty minutes on, and dropping it from a
- * draft loses the work the draft exists to protect. And it is subtractive rather than reconstructive: `mask()`
- * builds its result from the field metadata, so a key the metadata does not name — `id`, which is what decides
- * whether a form creates or updates — would not survive the round trip.
- *
- * `for...in` rather than `Object.keys`, because a model instance keeps its Date fields as enumerable prototype
- * accessors.
+ * Drops only `hidden`/`secret`, for a saved form draft: `visual` is the user's work and a key the metadata does not
+ * name (`id`) must survive. `for...in` because Date fields are enumerable prototype accessors.
  */
 export const stripSecrets = (model: MaskModel, value: unknown): unknown => {
   if (value === null || value === undefined || typeof value !== "object") return value;

package/constant/purify.ts

@@ -66,14 +66,12 @@ export type PurifyFuncV2<
 
 const getPurifyFn = (modelRef: Cls): ((value: unknown) => unknown) => {
   const [valueRef] = getNonArrayModel(modelRef);
-  const purifyFn = PrimitiveRegistry.has(valueRef)
+  return PrimitiveRegistry.has(valueRef)
     ? (value: unknown) => (valueRef as unknown as typeof PrimitiveScalar)._serialize(value as never)
     : (value: unknown) => value as object;
-  return purifyFn;
 };
 
 const purify = (field: FieldProps, key: string, value: unknown, self: Record<string, unknown>): unknown => {
-  
   if (
     field.nullable &&
     (value === null ||
@@ -111,13 +109,11 @@ const purify = (field: FieldProps, key: string, value: unknown, self: Record<str
     throw new Error(`Invalid Value (Failed to pass validation) / ${value} in ${key}`);
   if (!field.nullable && !value && value !== 0 && value !== false && (field.modelRef as Cls) !== Any)
     throw new Error(`Invalid Value (Nullable) in ${key} for value ${value}`);
-
-  const purifyFn = getPurifyFn(field.modelRef);
-  return purifyFn(value);
+  return getPurifyFn(field.modelRef)(value);
 };
 
-export const makePurify = <I>(modelRef: ConstantModelRef<I>): PurifyFunc<I> => {
-  const fn = ((self: Record<string, unknown>, isChild?: boolean): unknown => {
+export const makePurify = <I>(modelRef: ConstantModelRef<I>): PurifyFunc<I> =>
+  ((self: Record<string, unknown>, isChild?: boolean): unknown => {
     try {
       if (isChild && !ConstantRegistry.isScalar(modelRef)) {
         const id = self.id as string;
@@ -125,10 +121,8 @@ export const makePurify = <I>(modelRef: ConstantModelRef<I>): PurifyFunc<I> => {
         return id;
       }
       const result: Record<string, unknown> = {};
-      Object.entries(modelRef[FIELD_META]).forEach(([key, field]) => {
-        const value = self[key] as object;
-        result[key] = purify(field.getProps(), key, value, self) as object;
-      });
+      for (const [key, field] of Object.entries(modelRef[FIELD_META]))
+        result[key] = purify(field.getProps(), key, self[key], self);
       return result;
     } catch (err) {
       if (isChild) throw new Error(err as string);
@@ -136,5 +130,3 @@ export const makePurify = <I>(modelRef: ConstantModelRef<I>): PurifyFunc<I> => {
       return null;
     }
   }) as PurifyFunc<I>;
-  return fn;
-};

package/constant/serialize.ts

@@ -3,6 +3,7 @@ import {
   applyFnToArrayObjects,
   type Cls,
   type Dayjs,
+  type EnumInstance,
   FIELD_META,
   getNonArrayModel,
   ID,
@@ -10,7 +11,7 @@ import {
   type PrimitiveScalar,
 } from "akanjs/base";
 
-import type { ConstantCls, ConstantModelRef } from ".";
+import { type ConstantCls, type ConstantModelRef, ConstantRegistry, type FieldProps, withSharedInstances } from ".";
 
 export type Serialized<O> = O extends (infer V)[]
   ? Serialized<V>[]
@@ -22,12 +23,10 @@ export type Serialized<O> = O extends (infer V)[]
         ? { [K in keyof O]: Serialized<O[K]> }
         : O;
 
-const getSerializeFn = (inputRef: Cls, { optional = false }: { optional?: boolean } = {}) => {
-  const serializeFn = PrimitiveRegistry.has(inputRef)
+const getSerializeFn = (inputRef: Cls, { optional = false }: { optional?: boolean } = {}) =>
+  PrimitiveRegistry.has(inputRef)
     ? (value: unknown) => (inputRef as typeof PrimitiveScalar)._serialize(value as never, { optional })
     : (value: unknown) => value as object;
-  return serializeFn;
-};
 const serializeInput = <Input = unknown>(
   value: Input | Input[],
   inputRef: ConstantModelRef<Input> | PrimitiveScalar,
@@ -86,3 +85,81 @@ export const serialize = (
     throw new Error(`Invalid Value (Nullable) in ${argRef} for value ${value}${key ? ` in ${key}` : ""}`);
   return serializeInput(value, argRef, arrDepth, serializeType, { optional: nullable }) as object[];
 };
+
+const getDeserializeFn = (inputRef: ConstantModelRef | PrimitiveScalar) =>
+  PrimitiveRegistry.has(inputRef as Cls)
+    ? (value: unknown) => (inputRef as unknown as typeof PrimitiveScalar)._parse(value as never)
+    : (value: unknown) => value as object;
+const deserializeMap = (value: unknown, field: Pick<FieldProps, "of">) => {
+  if (!field.of) return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>).map(([key, val]) => [
+      key,
+      applyFnToArrayObjects(val, (v: never) => deserializeInput(v, field.of as ConstantModelRef, 0)),
+    ]),
+  );
+};
+
+const deserializeInput = <Input = unknown>(
+  value: Input | Input[],
+  inputRef: ConstantModelRef<Input> | PrimitiveScalar,
+  arrDepth: number,
+  convertFn: (value: unknown) => unknown = (value: unknown) => value,
+): Input | Input[] => {
+  if (arrDepth && Array.isArray(value))
+    return value.map((v) => deserializeInput(v, inputRef, arrDepth - 1, convertFn) as Input) as unknown as Input[];
+  if ((inputRef as ConstantCls).prototype === Map.prototype) {
+    const deserializeFn = getDeserializeFn(inputRef);
+    const entries = value instanceof Map ? [...value.entries()] : Object.entries(value as Record<string, unknown>);
+    return convertFn(
+      Object.fromEntries(entries.map(([key, val]) => [key, applyFnToArrayObjects(val, deserializeFn)])),
+    ) as Input;
+  }
+  if (PrimitiveRegistry.has(inputRef as Cls)) return convertFn(getDeserializeFn(inputRef)(value)) as Input;
+  if (!ConstantRegistry.isScalar(inputRef as Cls)) return convertFn(value) as Input;
+  return convertFn(
+    Object.fromEntries(
+      Object.entries((inputRef as ConstantCls)[FIELD_META]).map(([key, field]) => [
+        key,
+        field.isMap
+          ? deserializeMap((value as Record<string, unknown>)[key], field.getProps())
+          : deserialize(field.modelRef, field.arrDepth, (value as Record<string, unknown>)[key], {
+              key,
+              nullable: field.nullable,
+              enum: field.enum,
+            }),
+      ]),
+    ),
+  ) as Input;
+};
+
+interface DeserializeOption {
+  key?: string;
+  nullable?: boolean;
+  convertFn?: (value: unknown) => unknown;
+  enum?: EnumInstance;
+}
+
+const assertEnumValue = (enumRef: EnumInstance, value: unknown, key?: string): void => {
+  if (Array.isArray(value)) {
+    for (const item of value) assertEnumValue(enumRef, item, key);
+    return;
+  }
+  if (value === null || value === undefined || enumRef.has(value as never)) return;
+  throw new Error(`Invalid Enum Value in ${key}: ${String(value)} is not one of ${enumRef.values.join(", ")}`);
+};
+
+export const deserialize = (
+  argRef: ConstantModelRef | PrimitiveScalar,
+  arrDepth: number,
+  value: unknown,
+  { key, nullable = false, convertFn, enum: enumRef }: DeserializeOption,
+) => {
+  if (nullable && (value === null || value === undefined)) return null;
+  else if (!nullable && (value === null || value === undefined) && argRef !== Any)
+    throw new Error(`Invalid Value (Nullable) in ${key} ${argRef} for value ${value}`);
+
+  const result = withSharedInstances(() => deserializeInput(value, argRef, arrDepth, convertFn)) as object[];
+  if (enumRef) assertEnumValue(enumRef, result, key);
+  return result;
+};

package/constant/textFieldPaths.ts

@@ -17,7 +17,7 @@ export class TextFieldPaths extends TextFieldPathSet {
         this.#assertIndexable(key, field.text, field);
         this[field.text].add(key);
       }
-
+      
       if (field.isClass && field.isScalar) this.#mergeChild(key, field);
     }
     return this;
@@ -34,7 +34,6 @@ export class TextFieldPaths extends TextFieldPathSet {
   }
 
   #assertReachable(path: string, parent: ConstantField) {
-
     const fix = `Drop the text role on "${path}", or leave the parent unmasked.`;
     if (parent.fieldType === "secret") throw new Error(`Text field "${path}" is under a secret field. ${fix}`);
     if (parent.fieldType === "hidden") throw new Error(`Text field "${path}" is under a hidden field. ${fix}`);
@@ -43,7 +42,7 @@ export class TextFieldPaths extends TextFieldPathSet {
   }
 
   #assertIndexable(key: string, role: TextFieldRole, field: ConstantField) {
-
+    
     const masked = `The search mirror stores plaintext. Drop the text role on "${key}", or make the field plain.`;
     if (field.fieldType === "secret")
       throw new Error(`Text field "${key}" is secret and must not be indexed. ${masked}`);

package/constant/types.ts

@@ -109,12 +109,8 @@ export interface ProtoPatch {
 
 export const DEFAULT_PAGE_SIZE = 20;
 /**
- * The most rows one list request may take, whatever it asks for.
- *
- * A page size arrives from the client, so without a ceiling anyone who may read one page may read the whole
- * table in a single request — and `LIMIT 0` or `LIMIT -1` reaches SQLite as "no limit at all", so the two ways
- * of asking for nothing were the two ways of asking for everything. `resolvePageLimit` is the one place that
- * decides; a caller wanting more pages asks for more pages.
+ * The most rows one list request may take: the page size is client input, so without a ceiling one request could
+ * read the whole table, and `LIMIT 0`/`-1` reaches SQLite as no limit at all.
  */
 export const MAX_PAGE_SIZE = 500;