akanjs 3.0.0-beta.9 → 3.0.1

package/types/common/mcpExposure.d.ts

@@ -1,13 +1,3 @@
-/**
- * What MCP says about one endpoint: whether it is published, why it is not, and the hints it carries.
- *
- * Structurally typed like the rest of `common/` so the same rules answer on both sides — the server builds its
- * catalogue from them and the browser API explorer badges an endpoint from them. A second implementation would
- * eventually disagree, and an audit surface that disagrees with the catalogue is worse than none.
- *
- * Every rejection returns the sentence an author reads, at boot in the server log and in the explorer. Fail-closed
- * with no reason leaves an author whose endpoint is missing from the catalogue nowhere to look but the source.
- */
 export interface McpExposureEndpoint {
     type: string;
     returns: {
@@ -27,26 +17,17 @@ export interface McpExposureEndpoint {
     agents?: boolean;
 }
 export interface McpExposureOption {
-    /** The model the endpoint belongs to and the name it is published under: one rule reads the key, not the shape. */
     refName: string;
     key: string;
-    /**
-     * The read-only deployment valve, which is server configuration. The browser explorer cannot know it and so
-     * badges what the code decided; the boot log is where a read-only deployment says what it dropped.
-     */
+    /** The read-only deployment valve: server configuration the browser explorer cannot know. */
     readOnly?: boolean;
 }
-/** `Any` publishes as the empty schema, which tells a model nothing — so it is left out rather than described. */
+/** `Any` publishes as the empty schema, which tells a model nothing, so it is left out. */
 export declare const isMcpDescribableArg: (arg: {
     refName: string;
 }) => boolean;
-/** Which CRUD verb a generated endpoint key is, or `null` when the key is not one of the five. */
 export declare const mcpBaseVerbOf: (refName: string, key: string) => "get" | "create" | "update" | "remove" | null;
-/**
- * The hints a client renders beside a tool. Hints only — clients are told to distrust them, so they inform a UI
- * and never stand in for a guard. `openWorldHint` is always false: every endpoint reaches this app's own
- * database, not the wider internet.
- */
+/** Hints never stand in for a guard; `openWorldHint` is false: every endpoint reaches this app's own database. */
 export declare const mcpHintsOf: (key: string, endpoint: {
     type: string;
 }) => {
@@ -55,5 +36,4 @@ export declare const mcpHintsOf: (key: string, endpoint: {
     idempotentHint: boolean;
     openWorldHint: boolean;
 };
-/** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
 export declare const mcpRefusalOf: (endpoint: McpExposureEndpoint, { refName, key, readOnly }: McpExposureOption) => string | null;

package/types/common/objectPath.d.ts

@@ -0,0 +1,10 @@
+type PathSegment = string | number;
+type Indexable = Record<PathSegment, unknown>;
+export declare const isIndexable: (value: unknown) => value is Indexable;
+/** `a.0.b` and `a[0].b` are the same segments, for writes and reads alike. */
+export declare const toPathSegments: (path: string | readonly PathSegment[]) => any[];
+export declare const pathGet: (path: string | (string | number)[], obj: unknown, separator?: string, fallback?: unknown) => unknown;
+export declare const pathSet: <T>(obj: T, path: string | readonly PathSegment[], value: unknown) => T;
+/** Also tries joined prefixes, for keys whose segments contain the separator (an enum value like `gpt-5.6-terra`). */
+export declare const pathGetLoose: (path: string | readonly string[], obj: unknown, separator?: string, fallback?: unknown) => unknown;
+export {};

package/types/common/objectify.d.ts

@@ -1 +1,8 @@
 export declare const objectify: <T extends object>(obj: T, keys?: (keyof T)[]) => Partial<T>;
+export declare const plainFieldsOf: (source: object) => Record<string, unknown>;
+interface DeepObjectifyOption {
+    serializable?: boolean;
+    convertDate?: "string" | "number";
+}
+export declare const deepObjectify: <T = unknown>(obj: T | null | undefined, option?: DeepObjectifyOption) => T;
+export {};

package/types/common/phone.d.ts

@@ -0,0 +1,2 @@
+export declare const isPhoneNumber: (phone?: string | null) => boolean;
+export declare const formatPhone: (value: string) => string;

package/types/common/randomPick.d.ts

@@ -1 +1,2 @@
 export declare const randomPick: <T = unknown>(arr: T[] | readonly T[]) => T;
+export declare const randomPicks: <T>(arr: T[] | readonly T[], count?: number, allowDuplicate?: boolean) => T[];

package/types/common/requestOrigin.d.ts

@@ -1,20 +1,3 @@
-/**
- * The origin a caller actually saw, and whether a body claims to be JSON. Both read only headers and a URL, so
- * they answer the same way for the cache layer, the CSRF gate, and anything else that has to compare origins.
- */
 export declare const originFromRequest: (headers: Headers, url: URL) => string;
-/**
- * The host a caller addressed, which — unlike the scheme — every proxy that rewrites the request still reports.
- * `Host` is set by the browser from the URL it was told to open, so it names *this* deployment even for a
- * request some other page initiated.
- */
 export declare const hostFromRequest: (headers: Headers, url: URL) => string;
-/**
- * Whether a request body may be read as JSON.
- *
- * `Request.json()` parses whatever bytes it holds regardless of this header, and the three content types a
- * cross-site form can send — `text/plain`, `application/x-www-form-urlencoded`, `multipart/form-data` — are
- * exactly the ones a browser sends with **no preflight**. Requiring the JSON type is therefore what puts a
- * preflight in front of every mutation that carries a body.
- */
 export declare const isJsonContentType: (contentType: string | null) => boolean;

package/types/common/restClient.d.ts

@@ -1,10 +1,3 @@
-/**
- * A plain REST client for a service that is not an Akan API: base url, headers, timeout, JSON in and out.
- *
- * Not `akanjs/fetch`'s `HttpClient`, which builds an Akan endpoint's path from its serialized args and restores
- * an `Err` from the response. Two classes of the same name in one package meant an app importing both barrels
- * got a collision, so this one is named for what it is.
- */
 export interface RestClientOptions {
     baseUrl?: string;
     headers?: HeadersInit;

package/types/common/round.d.ts

@@ -0,0 +1 @@
+export declare const round: (value: number, digits?: number) => number;

package/types/common/routeConvention.d.ts

@@ -16,7 +16,6 @@ export interface ParsedRouteModuleKey {
     ext: string;
     leaf: string;
     pattern: string;
-    isSpecialRoute: boolean;
     isInternalRootLayout: boolean;
 }
 export interface ValidateSubRoutePageKeyOptions {
@@ -27,22 +26,18 @@ export interface ValidatePageSourceFileOptions {
     filePath?: string;
 }
 export declare function isRouteSourceFile(filePath: string): boolean;
-/**
- * Why a `page/` file breaks the route convention, or null when it is fine. Null also covers a non-source
- * asset, which `page/` tolerates. `akan sync <lib>` reports these alongside its other layout violations,
- * so the rule stays in one place instead of being restated where it cannot afford to throw.
- */
+/** `null` when the file is fine, including a non-source asset, which `page/` tolerates. */
 export declare function getPageSourceFileViolation(filePath: string): string | null;
 export declare function validatePageSourceFile(filePath: string, options?: ValidatePageSourceFileOptions): boolean;
 export declare function validateSubRoutePageKey(key: string, basePaths: Iterable<string>, options?: ValidateSubRoutePageKeyOptions): void;
 export declare function parseRouteModuleKey(key: string): ParsedRouteModuleKey;
-export declare function isSpecialRouteLeaf(leaf: string): boolean;
 export declare function tryParseRouteModuleKey(key: string): ParsedRouteModuleKey | null;
 export declare function normalizeRoutePattern(segments: string[]): string;
 export declare function routeSegmentToPatternPart(segment: string): string;
 export declare function routeSegmentToTreePath(segment: string): string;
 export declare function compareRouteSpecificity(a: string, b: string): number;
 export declare function matchRoutePattern(pattern: string, pathname: string): Record<string, string> | null;
+export declare function matchRoutePrefix(pattern: string, pathname: string): Record<string, string> | null;
 export declare function assertUniqueRoutePatterns(entries: {
     key: string;
     pattern: string;

package/types/common/sleep.d.ts

@@ -1,2 +1 @@
-/** Resolves after the requested delay in milliseconds. */
 export declare const sleep: (ms: number) => Promise<unknown>;

package/types/common/subRoute.d.ts

@@ -1,15 +1,13 @@
 import type { AkanI18nConfig } from "./localeConfig.d.ts";
 export declare const parseBasePaths: (value: string | string[] | Set<string> | undefined | null) => string[];
 /**
- * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A deployment platform
- * renders this value, so a malformed entry is skipped rather than thrown: one bad character must not CrashLoop
- * every pod that received it.
+ * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A malformed entry is
+ * skipped, not thrown: a deployment platform renders this value, and one bad character must not CrashLoop pods.
  */
 export declare const parseSubRouteHosts: (value: string | undefined | null) => Record<string, string[]>;
 /**
- * Unions the env mapping onto the one baked into the build artifact, never replacing it — dropping the env is the
- * rollback path. A basePath the build does not serve is reported back instead of honoured: the route tree is a
- * build output, so accepting one would answer every request under it with a 404 and nothing to explain why.
+ * Unions the env mapping onto the build's own, never replacing it (dropping the env is the rollback path). A basePath
+ * the build does not serve is reported back, not honoured: the route tree is a build output.
  */
 export declare const resolveSubRouteHosts: ({ subRoutes, basePaths, env, }: {
     subRoutes: Record<string, string[]>;

package/types/common/toError.d.ts

@@ -0,0 +1 @@
+export declare const toError: (reason: unknown) => Error;

package/types/common/tunnelWire.d.ts

@@ -0,0 +1,161 @@
+/** `http` and `tcp` payloads are raw binary frames; a `websocket` one prefixes each with a `tunnelWsPayload` byte. */
+export type TunnelStreamKind = "http" | "websocket" | "tcp";
+export type TunnelResetCode = "originUnreachable" | "originTimeout" | "originRefused" | "protocol" | "canceled" | "tooLarge" | "internal";
+/** Pairs, not a record: `set-cookie` repeats, and a record keyed by name keeps only the last one. */
+export type TunnelHeaderList = [string, string][];
+export interface TunnelAgentIdentity {
+    /** The operator's name for this share. */
+    name: string;
+    version: string;
+    platform: string;
+}
+export interface TunnelHelloFrame {
+    type: "hello";
+    version: number;
+    /** What the agent intends to serve; the gateway answers with what the token grants. */
+    hostnames: string[];
+    agent: TunnelAgentIdentity;
+}
+export interface TunnelReadyFrame {
+    type: "ready";
+    version: number;
+    sessionId: string;
+    /** Authoritative: the agent serves these and nothing else, whatever it asked for. */
+    hostnames: string[];
+    urls: string[];
+    /** Idle data sockets to hold; `maxSockets` is the ceiling the pool never grows past. */
+    idle: number;
+    maxSockets: number;
+    heartbeatMs: number;
+    /** Epoch ms, when the control plane put a TTL on this share. */
+    expiresAt?: number;
+}
+export interface TunnelPingFrame {
+    type: "ping";
+    at: number;
+}
+export interface TunnelPongFrame {
+    type: "pong";
+    at: number;
+}
+/** The gateway noticed the idle pool running short; the agent grows it to `idle`, capped by `maxSockets`. */
+export interface TunnelDemandFrame {
+    type: "demand";
+    idle: number;
+}
+/** A graceful goodbye from either side, so the peer stops reconnecting instead of treating it as a drop. */
+export interface TunnelByeFrame {
+    type: "bye";
+    reason?: string;
+}
+export type TunnelControlFromAgent = TunnelHelloFrame | TunnelPingFrame | TunnelPongFrame | TunnelByeFrame;
+export type TunnelControlFromGateway = TunnelReadyFrame | TunnelPingFrame | TunnelPongFrame | TunnelDemandFrame | TunnelByeFrame;
+/** First frame on a data socket; the session id names the agent connection it belongs to. */
+export interface TunnelAttachFrame {
+    type: "attach";
+    version: number;
+    sessionId: string;
+}
+/** The socket joined the idle pool; until this arrives the agent must not count it toward `idle`. */
+export interface TunnelAttachedFrame {
+    type: "attached";
+}
+export interface TunnelOpenFrame {
+    type: "open";
+    streamId: string;
+    kind: TunnelStreamKind;
+    /** The tunnel host the public caller addressed. */
+    hostname: string;
+    /** `http` and `websocket`. */
+    method?: string;
+    /** `http` and `websocket`: path plus query, already percent-encoded. */
+    path?: string;
+    /**
+     * `http` and `websocket`, replayed verbatim: the gateway strips every `forwardedHeaderNames` entry the caller sent
+     * (else Host header injection) and writes `x-forwarded-host` as the tunnel hostname (else CSRF refuses mutations).
+     */
+    headers?: TunnelHeaderList;
+    /** `tcp`: the port on the local origin to dial. */
+    port?: number;
+    /** Whether payload frames follow; absent or false means the request is complete as sent. */
+    body?: boolean;
+}
+export interface TunnelHeadFrame {
+    type: "head";
+    streamId: string;
+    /** `101` accepts a `websocket` open and `200` a `tcp` one; any other status is the agent declining. */
+    status: number;
+    statusText?: string;
+    headers: TunnelHeaderList;
+    body?: boolean;
+}
+/** No more payload in the direction this was sent; each direction ends independently. */
+export interface TunnelEndFrame {
+    type: "end";
+    streamId: string;
+}
+/** The stream failed; its socket is closed rather than returned to the pool. */
+export interface TunnelResetFrame {
+    type: "reset";
+    streamId: string;
+    code: TunnelResetCode;
+    message?: string;
+}
+/** Gateway → agent once both directions ended: the socket is idle again. Only `http` streams are released. */
+export interface TunnelReleaseFrame {
+    type: "release";
+    streamId: string;
+}
+export type TunnelDataFromAgent = TunnelAttachFrame | TunnelHeadFrame | TunnelEndFrame | TunnelResetFrame;
+export type TunnelDataFromGateway = TunnelAttachedFrame | TunnelOpenFrame | TunnelEndFrame | TunnelResetFrame | TunnelReleaseFrame;
+export type TunnelFrame = TunnelControlFromAgent | TunnelControlFromGateway | TunnelDataFromAgent | TunnelDataFromGateway;
+export declare const tunnelWsPayload: {
+    readonly text: 0;
+    readonly binary: 1;
+    /** Remainder is UTF-8 JSON `{ code, reason }` — the inner close, which is not the tunnel socket closing. */
+    readonly close: 2;
+};
+export type TunnelWsPayloadKind = (typeof tunnelWsPayload)[keyof typeof tunnelWsPayload];
+/** Stripped by both ends independently, so neither has to trust the other to have done it. */
+export declare const tunnelHopByHopHeaders: readonly ["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "proxy-connection", "te", "trailer", "transfer-encoding", "upgrade"];
+/**
+ * The only way a refusal reaches the agent, which treats these as final and any other close as a drop to retry: a
+ * refused upgrade arrives as a bare `1006`. Accept the upgrade and close on a later tick, never inside `open`.
+ */
+export declare const tunnelCloseCode: {
+    readonly unauthorized: 4001;
+    readonly unsupportedVersion: 4002;
+    readonly hostnameNotGranted: 4003;
+    readonly unknownSession: 4004;
+    /** A newer session for the same tunnel took over; this one must not reconnect. */
+    readonly superseded: 4005;
+    readonly streamLimit: 4008;
+    readonly goingAway: 4009;
+};
+export type TunnelCloseCode = (typeof tunnelCloseCode)[keyof typeof tunnelCloseCode];
+/** Includes `forwarded`, RFC 7239's single-header spelling of the same claim. */
+export declare const tunnelForwardedHeaders: readonly ["x-real-ip", "x-forwarded-for", "x-forwarded-port", "x-forwarded-host", "x-forwarded-proto", "forwarded"];
+export declare const tunnelWireContract: {
+    readonly version: 1;
+    readonly controlPath: "/_tunnel/control";
+    readonly dataPath: "/_tunnel/data";
+    readonly authScheme: "Bearer";
+    readonly defaultIdleSockets: 4;
+    readonly defaultMaxSockets: 128;
+    readonly defaultHeartbeatMs: 30000;
+    /** What a sender splits an `http` or `tcp` payload to. */
+    readonly chunkBytes: number;
+    /** Floor of every tunnel socket's `maxPayloadLength`: an inner 16 MB message plus its prefix rides one frame. */
+    readonly maxFrameBytes: number;
+    readonly stripForwarded: (headers: Headers) => Headers;
+    readonly forwardedHeaderNames: readonly ["x-real-ip", "x-forwarded-for", "x-forwarded-port", "x-forwarded-host", "x-forwarded-proto", "forwarded"];
+    readonly isHopByHop: (name: string) => boolean;
+    readonly headerList: (headers: Headers) => TunnelHeaderList;
+    readonly headersOf: (list: TunnelHeaderList) => Headers;
+    readonly encodeWsPayload: (kind: TunnelWsPayloadKind, data: Uint8Array) => Uint8Array;
+    readonly decodeWsPayload: (frame: Uint8Array) => {
+        kind: TunnelWsPayloadKind;
+        data: Uint8Array;
+    } | null;
+    readonly parseFrame: (raw: string) => TunnelFrame | null;
+};

package/types/common/types.d.ts

@@ -5,17 +5,9 @@ export interface FetchPolicy<Returns = unknown> {
     onError?: (error: string) => void;
     token?: string;
     partial?: string[];
-    /**
-     * Milliseconds before this call is abandoned, `false` to wait as long as the runtime will. Overrides the
-     * endpoint's declared `timeout`, which overrides the client's own default.
-     */
+    /** Milliseconds, or `false` to wait as long as the runtime will; overrides the endpoint's declared `timeout`. */
     timeout?: number | false;
-    /**
-     * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
-     *
-     * Whatever was published while the socket was down is gone, and a room cannot say which messages those were, so
-     * a subscriber that has to stay correct reloads here instead of carrying on from a gap it cannot see.
-     */
+    /** `pubsub` only: called after a resubscribe, since whatever was published while the socket was down is gone. */
     onResync?: () => void;
 }
 export type SnakeCase<S extends string> = S extends `${infer T}_${infer U}` ? `${Lowercase<T>}_${SnakeCase<U>}` : S;
@@ -23,3 +15,7 @@ export type SnakeCaseObj<T> = {
     [K in keyof T as SnakeCase<K & string>]: T[K] extends object ? SnakeCaseObj<T[K]> : T[K];
 };
 export type SnakeMsg<Msg> = SnakeCaseObj<Msg>;
+/** Name-based dispatch over a generated surface: `as DynamicRecord` to index, then cast the read, never `as any`. */
+export type DynamicRecord<Value = unknown> = {
+    [key: string]: Value;
+};

package/types/common/version.d.ts

@@ -0,0 +1,6 @@
+export declare const mergeVersion: (major: number, minor: number, patch: number) => string;
+export declare const splitVersion: (version: string) => {
+    major: string;
+    minor: string;
+    patch: string;
+};

package/types/common/websocketContract.d.ts

@@ -0,0 +1,41 @@
+export interface WebsocketAuthRequest {
+    key: string;
+    data: [string | null];
+}
+export interface WebsocketAuthAckData {
+    type: "auth";
+    revokedRooms: string[];
+}
+export declare const websocketAuthContract: {
+    readonly key: "__auth";
+    readonly makeRequest: (jwt: string | null) => WebsocketAuthRequest;
+    readonly makeAck: (revokedRooms: string[]) => WebsocketAuthAckData;
+    readonly readJwt: (data: unknown) => string | null;
+};
+export interface WebsocketHeartbeatRequest {
+    key: string;
+    data: [];
+}
+export interface WebsocketHeartbeatAckData {
+    type: "pong";
+}
+export declare const websocketHeartbeatContract: {
+    readonly key: "__ping";
+    /** Under the 60s idle timeout nginx and most CDNs ship with. */
+    readonly intervalMs: 45000;
+    /** Without any inbound frame this long, the socket is assumed half-open and reconnected. */
+    readonly silenceMs: number;
+    readonly makeRequest: () => WebsocketHeartbeatRequest;
+    readonly makeAck: () => WebsocketHeartbeatAckData;
+};
+export declare const websocketRoomContract: {
+    readonly idOf: (key: string, args: unknown[]) => string;
+};
+export interface WebsocketBinaryFrame {
+    roomId: string;
+    payload: Uint8Array;
+}
+export declare const websocketBinaryFrameContract: {
+    readonly encode: ({ roomId, payload }: WebsocketBinaryFrame) => Uint8Array;
+    readonly decode: (data: ArrayBuffer | Uint8Array) => WebsocketBinaryFrame | null;
+};

package/types/constant/cascadePaths.d.ts

@@ -1,11 +1,8 @@
 import type { FieldObject } from "./fieldInfo.d.ts";
 import type { ConstantModelRef } from "./via.d.ts";
 /**
- * Which end of a relation goes away with the other. `removeRef` removes what the field points at when this
- * document is removed; `removeWith` removes this document when what the field points at is removed. The two
- * read identically on a relation field, so the value has to name the direction — a mistake here is a data loss.
- * `removeWithAny` is `removeWith` over an owner that is unknowable at build time, and it names the whole
- * decision in one value so the widening cannot be declared apart from the direction it widens.
+ * `removeRef`: removing this document removes what the field points at. `removeWith`: removing what the field points
+ * at removes this document. `removeWithAny`: `removeWith` over an owner unknowable at build time.
  */
 export declare const cascadeActions: readonly ["removeRef", "removeWith", "removeWithAny"];
 export type CascadeAction = (typeof cascadeActions)[number];

package/types/constant/constantRegistry.d.ts

@@ -1,8 +1,8 @@
 import { type Cls, type EnumInstance, type GetStateObject, type PrimitiveScalar } from "akanjs/base";
 import { type ConstantCls, type ConstantModelRef, type FieldObject, type PurifiedModel } from ".";
 import type { ConstantType, DefaultOf, DocumentModel, QueryOf } from "./types.d.ts";
-/** Runtime registry for Akan constant model metadata, refs, enums, and generated model contracts. */
 export declare class ConstantRegistry {
+    #private;
     static database: Map<string, ConstantModel<string, any, any, any, any, any, FieldObject, Capitalize<string>, DefaultOf<any>, DefaultOf<any>, GetStateObject<any>, GetStateObject<any>, DefaultOf<any>, any, any, any, any, GetStateObject<any>, GetStateObject<any>>>;
     static scalar: Map<string, ScalarConstantModel<string, any, DefaultOf<any>, any, any>>;
     static enum: Map<string, EnumInstance>;
@@ -37,10 +37,10 @@ export declare class ConstantRegistry {
         allowEmpty?: AllowEmpty;
     }): AllowEmpty extends true ? ScalarConstantModel | undefined : ScalarConstantModel;
     static getModelRef(refName: string, modelType?: ConstantType): Cls | typeof PrimitiveScalar;
-    static buildModel<T extends string, InputRef extends ConstantModelRef, ObjectRef extends ConstantModelRef, FullFieldObj extends FieldObject, FullRef extends ConstantModelRef<any, FullFieldObj>, LightRef extends ConstantModelRef, InsightRef extends ConstantModelRef, Input = InstanceType<InputRef>, Obj = InstanceType<ObjectRef>, Full = InstanceType<FullRef>, Light = InstanceType<LightRef>, Insight = InstanceType<InsightRef>>(refName: T, inputRef: InputRef, objectRef: ObjectRef, fullRef: FullRef, lightRef: LightRef, insightRef: InsightRef, constExports: Record<string, unknown>): ConstantModel<T, Input, Obj, Full, Light, Insight, FullFieldObj, Capitalize<T>, DefaultOf<Full>, DefaultOf<Input>, GetStateObject<Full>, GetStateObject<Input>, DefaultOf<Insight>, PurifiedModel<Input>, DocumentModel<Full>, DocumentModel<Input>, QueryOf<DocumentModel<Full>>, GetStateObject<Light>, GetStateObject<Insight>>;
+    static buildModel<T extends string, InputRef extends ConstantModelRef, ObjectRef extends ConstantModelRef, FullFieldObj extends FieldObject, FullRef extends ConstantModelRef<any, FullFieldObj>, LightRef extends ConstantModelRef, InsightRef extends ConstantModelRef, Input = InstanceType<InputRef>, Obj = InstanceType<ObjectRef>, Full = InstanceType<FullRef>, Light = InstanceType<LightRef>, Insight = InstanceType<InsightRef>>(refName: T, inputRef: InputRef, objectRef: ObjectRef, fullRef: FullRef, lightRef: LightRef, insightRef: InsightRef, constExports: Record<string, unknown>): ConstantModel<T, Input, Obj, Full, Light, Insight, FullFieldObj, Capitalize<T>, DefaultOf<Full>, DefaultOf<Input>, GetStateObject<Full>, GetStateObject<Input>, DefaultOf<Insight>, PurifiedModel<Input>, DocumentModel<Full>, DocumentModel<Input>, any, GetStateObject<Light>, GetStateObject<Insight>>;
     static buildScalar<T extends string, Model>(refName: T, Model: Cls<Model>, constExports: Record<string, unknown>): ScalarConstantModel<T, Model, DefaultOf<Model>, DocumentModel<Model>, PurifiedModel<Model>>;
-    static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable?: boolean): Value;
-    static deserialize<Value>(modelRef: Cls | Cls[], value: Value, nullable?: boolean): Value;
+    static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable?: boolean, of?: Cls | Cls[]): Value;
+    static deserialize<Value>(modelRef: Cls | Cls[], value: Value, nullable?: boolean, of?: Cls | Cls[]): Value;
 }
 export interface ConstantModel<T extends string = string, Input = any, Obj = any, Full = any, Light = any, Insight = any, FullFieldObj extends FieldObject = FieldObject, _CapitalizedRefName extends string = Capitalize<T>, _Default = DefaultOf<Full>, _DefaultInput = DefaultOf<Input>, _DefaultState = GetStateObject<Full>, _DefaultStateInput = GetStateObject<Input>, _DefaultInsight = DefaultOf<Insight>, _PurifiedInput = PurifiedModel<Input>, _Doc = DocumentModel<Full>, _DocInput = DocumentModel<Input>, _QueryOfDoc = QueryOf<_Doc>, _StateLight = GetStateObject<Light>, _StateInsight = GetStateObject<Insight>> {
     refName: T;

package/types/constant/dateSlot.d.ts

@@ -1,11 +1,6 @@
 export declare const dateSlotOf: (key: string) => symbol;
 /** A caller's own `Date` is copied: the slot must not alias an object the caller can still mutate. */
 export declare const toDateValue: (value: unknown) => Date | null | undefined;
-/**
- * Enumerable so `for...in` — `plainFieldsOf`, `immerify`, `deepObjectify` — still sees the field. immer calls a
- * prototype setter with the draft as `this`, so a write through the accessor stays copy-on-write, and the getter
- * writes nothing, so a read never marks a draft modified.
- */
 export declare const dateAccessorOf: (key: string) => PropertyDescriptor;
 export declare const isDateSlotField: (props: {
     modelRef: unknown;

package/types/constant/fieldInfo.d.ts

@@ -47,12 +47,7 @@ export interface ConstantFieldProps<FieldType extends ConstantFieldKind = Consta
     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;
 }
@@ -118,7 +113,6 @@ type ConstantFieldFromInfo<Info> = Info extends FieldInfo<infer FieldType, infer
 export type FieldInfoObjectToFieldObject<Obj extends FieldInfoObject> = {
     [K in keyof Obj]: ConstantFieldFromInfo<Obj[K]>;
 };
-/** Runtime metadata for a single Akan constant field. */
 export declare class ConstantField<FieldType extends ConstantFieldKind = ConstantFieldKind, Value extends ConstantFieldTypeInput | null = any, FieldValue = any, MapValue = any, Nullable extends boolean = boolean, IsRelation extends boolean = boolean, IsEnum extends boolean = boolean, IsPrimitive extends boolean = boolean, IsScalar extends boolean = boolean, IsHidden extends boolean = boolean, IsSecret extends boolean = boolean, IsMap extends boolean = boolean, Metadata = {
     [key: string]: any;
 }> implements ConstantFieldBuildProps<FieldType, FieldValue, MapValue, Metadata> {
@@ -172,19 +166,7 @@ export declare class ConstantField<FieldType extends ConstantFieldKind = Constan
 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;
@@ -199,14 +181,13 @@ type FieldOption<Value extends ConstantFieldTypeInput, MapValue = Value extends
     [key: string]: any;
 }, _FieldToValue = FieldToValue<Value, MapValue> | null | undefined> = WithCascadePair<Omit<ConstantFieldProps<ConstantFieldKind, _FieldToValue, MapValue, Metadata>, "enum" | "meta" | "nullable" | "fieldType" | "select">> | WithCascadePair<Omit<ConstantFieldProps<ConstantFieldKind, SingleValue<_FieldToValue>, MapValue, Metadata>, "enum" | "meta" | "nullable" | "fieldType" | "select">>[];
 export type PlainTypeToFieldType<PlainType> = PlainType extends [infer First, ...infer Rest] ? PlainTypeToFieldType<First>[] : PlainType extends number ? typeof Int | typeof Float : PlainType extends string ? StringConstructor : typeof Any;
-/** Builds a stored property field with optional validation, default, ref, text, and metadata options. */
 export declare const field: {
     <ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: FieldOption<Value, MapValue>): FieldInfo<"property", Value, ExplicitType, MapValue, FieldKindSource<Value>, UnCls<FieldKindSource<Value>> extends BaseObject ? true : false, FieldKindSource<Value> extends infer T ? T extends FieldKindSource<Value> ? T extends EnumInstance<string, any> ? true : false : never : never, FieldKindSource<Value> extends infer T_1 ? T_1 extends FieldKindSource<Value> ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, FieldKindSource<Value> extends infer T_2 ? T_2 extends FieldKindSource<Value> ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) ? T_3 extends true ? false : (FieldKindSource<Value> extends infer T_4 ? T_4 extends FieldKindSource<Value> ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (FieldKindSource<Value> extends infer T_12 ? T_12 extends FieldKindSource<Value> ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (FieldKindSource<Value> extends infer T_6 ? T_6 extends FieldKindSource<Value> ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (FieldKindSource<Value> extends infer T_11 ? T_11 extends FieldKindSource<Value> ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (FieldKindSource<Value> extends infer T_8 ? T_8 extends FieldKindSource<Value> ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (FieldKindSource<Value> extends infer T_10 ? T_10 extends FieldKindSource<Value> ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, false, false>;
     visual<ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: FieldOption<Value, MapValue>): FieldInfo<"property", Value, ExplicitType, MapValue, FieldKindSource<Value>, UnCls<FieldKindSource<Value>> extends BaseObject ? true : false, FieldKindSource<Value> extends infer T ? T extends FieldKindSource<Value> ? T extends EnumInstance<string, any> ? true : false : never : never, FieldKindSource<Value> extends infer T_1 ? T_1 extends FieldKindSource<Value> ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, FieldKindSource<Value> extends infer T_2 ? T_2 extends FieldKindSource<Value> ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) ? T_3 extends true ? false : (FieldKindSource<Value> extends infer T_4 ? T_4 extends FieldKindSource<Value> ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (FieldKindSource<Value> extends infer T_12 ? T_12 extends FieldKindSource<Value> ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (FieldKindSource<Value> extends infer T_6 ? T_6 extends FieldKindSource<Value> ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (FieldKindSource<Value> extends infer T_11 ? T_11 extends FieldKindSource<Value> ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (FieldKindSource<Value> extends infer T_8 ? T_8 extends FieldKindSource<Value> ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (FieldKindSource<Value> extends infer T_10 ? T_10 extends FieldKindSource<Value> ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, false, false>;
     hidden<ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: WithoutTextRole<FieldOption<Value, MapValue>>): FieldInfo<"hidden", Value, ExplicitType, MapValue, FieldKindSource<Value>, UnCls<FieldKindSource<Value>> extends BaseObject ? true : false, FieldKindSource<Value> extends infer T ? T extends FieldKindSource<Value> ? T extends EnumInstance<string, any> ? true : false : never : never, FieldKindSource<Value> extends infer T_1 ? T_1 extends FieldKindSource<Value> ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, FieldKindSource<Value> extends infer T_2 ? T_2 extends FieldKindSource<Value> ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) ? T_3 extends true ? false : (FieldKindSource<Value> extends infer T_4 ? T_4 extends FieldKindSource<Value> ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (FieldKindSource<Value> extends infer T_12 ? T_12 extends FieldKindSource<Value> ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (FieldKindSource<Value> extends infer T_6 ? T_6 extends FieldKindSource<Value> ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (FieldKindSource<Value> extends infer T_11 ? T_11 extends FieldKindSource<Value> ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (FieldKindSource<Value> extends infer T_8 ? T_8 extends FieldKindSource<Value> ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (FieldKindSource<Value> extends infer T_10 ? T_10 extends FieldKindSource<Value> ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, true, false>;
     secret<ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: WithoutTextRole<FieldOption<Value, MapValue>>): FieldInfo<"secret", Value | null, ExplicitType | null, MapValue, SingleValue<Value> & {}, UnCls<SingleValue<Value> & {}> extends BaseObject ? true : false, SingleValue<Value> & {} extends infer T ? T extends SingleValue<Value> & {} ? T extends EnumInstance<string, any> ? true : false : never : never, SingleValue<Value> & {} extends infer T_1 ? T_1 extends SingleValue<Value> & {} ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, SingleValue<Value> & {} extends infer T_2 ? T_2 extends SingleValue<Value> & {} ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<SingleValue<Value> & {}> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<SingleValue<Value> & {}> extends BaseObject ? true : false) ? T_3 extends true ? false : (SingleValue<Value> & {} extends infer T_4 ? T_4 extends SingleValue<Value> & {} ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (SingleValue<Value> & {} extends infer T_12 ? T_12 extends SingleValue<Value> & {} ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (SingleValue<Value> & {} extends infer T_6 ? T_6 extends SingleValue<Value> & {} ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (SingleValue<Value> & {} extends infer T_11 ? T_11 extends SingleValue<Value> & {} ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (SingleValue<Value> & {} extends infer T_8 ? T_8 extends SingleValue<Value> & {} ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (SingleValue<Value> & {} extends infer T_10 ? T_10 extends SingleValue<Value> & {} ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, false, true>;
 };
-/** Builds a resolved field that is derived rather than treated as a stored property. */
+/** A derived field, never stored. */
 export declare const resolve: <ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: WithoutTextRole<FieldOption<Value, MapValue>>) => FieldInfo<"resolve", Value, ExplicitType, MapValue, FieldKindSource<Value>, UnCls<FieldKindSource<Value>> extends BaseObject ? true : false, FieldKindSource<Value> extends infer T ? T extends FieldKindSource<Value> ? T extends EnumInstance<string, any> ? true : false : never : never, FieldKindSource<Value> extends infer T_1 ? T_1 extends FieldKindSource<Value> ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, FieldKindSource<Value> extends infer T_2 ? T_2 extends FieldKindSource<Value> ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) ? T_3 extends true ? false : (FieldKindSource<Value> extends infer T_4 ? T_4 extends FieldKindSource<Value> ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (FieldKindSource<Value> extends infer T_12 ? T_12 extends FieldKindSource<Value> ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (FieldKindSource<Value> extends infer T_6 ? T_6 extends FieldKindSource<Value> ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (FieldKindSource<Value> extends infer T_11 ? T_11 extends FieldKindSource<Value> ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (FieldKindSource<Value> extends infer T_8 ? T_8 extends FieldKindSource<Value> ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (FieldKindSource<Value> extends infer T_10 ? T_10 extends FieldKindSource<Value> ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, false, false>;
 export type FieldBuilder = typeof field;
 export type FieldResolver = typeof resolve;

package/types/constant/fieldQueryMeta.d.ts

@@ -1,17 +1,9 @@
-/**
- * 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[]);
 }
-/** The query one field of `refName` names, or nothing when the model, the field, or the declaration is absent. */
 export declare const fieldQueryMetaOf: (refName: string, field: string) => FieldQueryMeta | undefined;

package/types/constant/getDefault.d.ts

@@ -3,14 +3,12 @@ import type { DefaultOf } from "./types.d.ts";
 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>;
 }
-/**
- * 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 declare const getDefault: <T>(fieldObj: FieldObject) => 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 declare const defaultPlanOf: (fieldObj: FieldObject) => DefaultPlan;
+/** Copies a plain object or array; an instance (`Dayjs`, `Uint8Array`) is returned as is, keeping its prototype. */
+export declare const freshPrimitiveValue: <T>(value: T) => T;

package/types/constant/hydrationPlan.d.ts

@@ -3,14 +3,6 @@ import type { FieldObject } from "./fieldInfo.d.ts";
 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 declare class HydrationPlan {
     #private;
     static of(cls: PlanOwner): HydrationPlan;

package/types/constant/index.d.ts

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