akanjs 2.4.1-rc.2 → 2.4.1-rc.4

package/client/device.ts

@@ -1,12 +1,12 @@
 "use client";
 import type { RefObject } from "react";
-import { debugFrame } from "./frameDebug";
 import type {
   CapacitorDeviceInfo,
   CapacitorHapticsModule,
   CapacitorKeyboardInfo,
   CapacitorKeyboardModule,
 } from "./capacitor";
+import { debugFrame } from "./frameDebug";
 
 type DeviceInfo = CapacitorDeviceInfo;
 type Keyboard = CapacitorKeyboardModule["Keyboard"];

package/client/router.ts

@@ -112,7 +112,10 @@ const normalizeRouteManifestPath = (href: string, prefix = "") => {
   return segments.length === 0 ? "/" : `/${segments.join("/")}`;
 };
 
-export const normalizeDeepLinkHref = (href: string, origin = globalThis.window?.location?.origin ?? "http://localhost") => {
+export const normalizeDeepLinkHref = (
+  href: string,
+  origin = globalThis.window?.location?.origin ?? "http://localhost",
+) => {
   const url = new URL(href, origin);
   if (url.protocol === "http:" || url.protocol === "https:") return `${url.pathname}${url.search}${url.hash}`;
   const hostPath = url.hostname ? `/${url.hostname}` : "";
@@ -268,7 +271,11 @@ class Router {
     const state = (history.state ?? {}) as Record<string, unknown>;
     const akanState = (state.__akanRouter ?? {}) as { idx?: number };
     this.#historyIdx = Number.isInteger(akanState.idx) ? (akanState.idx as number) : this.#historyIdx;
-    history.replaceState({ ...state, __akanRouter: { ...akanState, idx: this.#historyIdx } }, "", globalThis.window.location.href);
+    history.replaceState(
+      { ...state, __akanRouter: { ...akanState, idx: this.#historyIdx } },
+      "",
+      globalThis.window.location.href,
+    );
     if (!globalThis.window.addEventListener) return;
     globalThis.window.addEventListener("popstate", (event) => {
       const nextState = ((event.state as Record<string, unknown> | null)?.__akanRouter ?? {}) as { idx?: number };
@@ -336,7 +343,9 @@ class Router {
     }
     const stack = this.#routePaths.size > 0 ? this.#getExistingSegmentStack(path) : [path];
     const baseStack =
-      stack.length > 1 || this.#indexPath === path || stack.includes(this.#indexPath) ? stack : [this.#indexPath, ...stack];
+      stack.length > 1 || this.#indexPath === path || stack.includes(this.#indexPath)
+        ? stack
+        : [this.#indexPath, ...stack];
     const dedupedStack = baseStack.filter((candidate, index) => baseStack.indexOf(candidate) === index);
     const target = `${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
     return dedupedStack.map((candidate, index) => (index === dedupedStack.length - 1 ? target : candidate));

package/dictionary/dictionaryRegistry.ts

@@ -0,0 +1,87 @@
+import { ModelDictInfo, ScalarDictInfo, ServiceDictInfo } from "./dictInfo";
+import type { DictModule } from "./locale";
+import type { DictionaryNode, RootDictionary } from "./trans";
+
+export type DictionaryModuleKind = "model" | "scalar" | "service";
+
+export interface DictionaryModuleInfo {
+  kind: DictionaryModuleKind;
+  languages: string[];
+}
+
+/**
+ * Collects every dictionary tree built by `makeTrans` so a server process can read the merged result.
+ *
+ * `makeTrans` keeps its `rootDictionary` in a closure and `AkanLib` carries no dictionary, so without this
+ * the i18n tree is unreachable from `AkanServer`. Registration happens at module-evaluation time, which the
+ * API process reaches because it imports the generated `server.ts` (which re-exports `lib/dict.ts`) whole.
+ */
+export class DictionaryRegistry {
+  static readonly #roots: RootDictionary[] = [];
+  static readonly #modules = new Map<string, DictionaryModuleInfo>();
+
+  /** Registration order is base → libs → app, matching `makeDictionary`, so a later root wins on conflict. */
+  static register(root: RootDictionary, transMap: Record<string, DictModule<string, string>>) {
+    DictionaryRegistry.#roots.push(root);
+    Object.entries(transMap).forEach(([refName, trans]) => {
+      DictionaryRegistry.#modules.set(refName, {
+        kind: DictionaryRegistry.#resolveKind(trans),
+        languages: [...((trans.dict as { languages?: string[] }).languages ?? [])],
+      });
+    });
+  }
+
+  static getRoot(): RootDictionary {
+    const merged = {} as RootDictionary;
+    DictionaryRegistry.#roots.forEach((root) => {
+      Object.entries(root).forEach(([language, models]) => {
+        merged[language] = { ...(merged[language] ?? {}), ...models };
+      });
+    });
+    return merged;
+  }
+
+  static getLanguages(): string[] {
+    return [...new Set(DictionaryRegistry.#roots.flatMap((root) => Object.keys(root)))];
+  }
+
+  static getModules(): Record<string, DictionaryModuleInfo> {
+    return Object.fromEntries([...DictionaryRegistry.#modules.entries()].map(([key, info]) => [key, { ...info }]));
+  }
+
+  /** Flattened dotted paths of every leaf translation, e.g. `"user.signal.createUser.arg.data"`. */
+  static getKeys(root: RootDictionary = DictionaryRegistry.getRoot()): string[] {
+    const keys = new Set<string>();
+    Object.values(root).forEach((models) => {
+      Object.entries(models).forEach(([refName, node]) => {
+        DictionaryRegistry.#collectKeys(refName, node, keys);
+      });
+    });
+    return [...keys].sort();
+  }
+
+  /** Test-only reset; the registry is module-level global state. */
+  static clear() {
+    DictionaryRegistry.#roots.length = 0;
+    DictionaryRegistry.#modules.clear();
+  }
+
+  static #collectKeys(path: string, node: DictionaryNode, keys: Set<string>) {
+    if (typeof node.t === "string") keys.add(path);
+    Object.entries(node).forEach(([key, value]) => {
+      if (key === "t" || !DictionaryRegistry.#isNode(value)) return;
+      DictionaryRegistry.#collectKeys(`${path}.${key}`, value, keys);
+    });
+  }
+
+  static #isNode(value: unknown): value is DictionaryNode {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+
+  static #resolveKind(trans: DictModule<string, string>): DictionaryModuleKind {
+    if (trans.dict instanceof ModelDictInfo) return "model";
+    if (trans.dict instanceof ScalarDictInfo) return "scalar";
+    if (trans.dict instanceof ServiceDictInfo) return "service";
+    return "service";
+  }
+}

package/dictionary/index.ts

@@ -8,5 +8,6 @@ export {
   getDictionary,
   translate,
 } from "./dictionary";
+export * from "./dictionaryRegistry";
 export * from "./locale";
 export * from "./trans";

package/dictionary/trans.ts

@@ -1,6 +1,7 @@
 import type { GetStateObject, ObjectAssign, Prettify } from "akanjs/base";
 import { pathGet } from "akanjs/common";
 
+import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictModule } from "./locale";
 
 type TranslationSingle = readonly [string, string] | readonly [string, string, string, string];
@@ -106,6 +107,7 @@ export const makeTrans = <
   Object.entries(transMap).forEach(([refName, trans]) => {
     trans.dict._registerToRoot(refName, rootDictionary);
   });
+  DictionaryRegistry.register(rootDictionary, transMap);
   class Err extends Error {
     readonly error: string;
     readonly statusCode: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.4.1-rc.2",
+  "version": "2.4.1-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -165,6 +165,16 @@
       "types": "./types/server/rscWorker.d.ts",
       "import": "./server/rscWorker.tsx",
       "default": "./server/rscWorker.tsx"
+    },
+    "./server/memoryLimit": {
+      "types": "./types/server/memoryLimit.d.ts",
+      "import": "./server/memoryLimit.ts",
+      "default": "./server/memoryLimit.ts"
+    },
+    "./server/lifecycle/portInUse": {
+      "types": "./types/server/lifecycle/portInUse.d.ts",
+      "import": "./server/lifecycle/portInUse.ts",
+      "default": "./server/lifecycle/portInUse.ts"
     }
   },
   "dependencies": {

package/server/SSR_MEMORY_DIAGNOSIS.md

@@ -105,3 +105,50 @@ AKAN_RSC_WORKER_RECYCLE_GRACE_MS=5000
 ```
 
 Validate that recycle happens only when `rscPendingRenderCount` is `0`, and that the new `rscWorkerPid` becomes ready before traffic continues.
+
+## Dev Builder Recycle
+
+The dev builder has the same problem for a different reason: `Bun.build` retains native bundler arenas
+that no GC reclaims, so the process only returns that memory by exiting. `AkanAppHost` therefore
+recycles it — gracefully, after its queues drain and once it has stayed quiet — past a ceiling:
+
+```sh
+AKAN_BUILDER_MAX_RSS_MB=1200   # 0 leaves the builder unbounded; default is 1200 in dev
+AKAN_BUILDER_MAX_RSS=1200mb    # same ceiling with a unit suffix
+```
+
+Both resolve through `MemoryLimit.resolveMaxRssBytes`, so `AKAN_MEMORY_LIMIT` or a cgroup limit also
+applies (the builder takes 35% of it, the RSC worker 55%). Look for `recycling builder pid=…` followed
+by `exiting for recycle` and `announced boot state after recycle`; the last line is what re-points a
+running backend at the replacement's artifact.
+
+**How much of that RSS is actually unreclaimable is platform-specific.** Measured on Bun 1.3.14: macOS
+returns none of the bundler arenas (0% after 60s idle) while Linux purges them after ~10-15s of quiet,
+46-59% of the builder's peak. Since the builder reports its RSS only when its queues drain, that sample
+is its *peak* — so before committing, the host waits 20s and re-reads the builder's RSS from the OS,
+and skips the recycle if the allocator gave the memory back by itself:
+
+```
+[builder-recycle] holding 20s to see whether the allocator returns it (rss=522MiB>=400MiB after 6 build(s))
+[builder-recycle] skipped: the builder fell to 214MiB (ceiling 400MiB) on its own, …
+```
+
+A builder more than 1.5× over the ceiling skips the wait, since no purge would rescue it. On macOS the
+re-read returns the same value, so the only cost there is the delay.
+
+## Dev Idle Suspend
+
+A dev server that nobody is editing still pays for a builder. After five minutes with no build
+activity and no route request, `AkanAppHost` releases the builder entirely and watches for edits with
+a plain `fs.watch` instead. The backend stays up, so the preview URL keeps serving; only build
+capacity goes away. The next edit — or the first request that needs a build — brings it back, paying
+one cold boot build (~3.5s on `apps/akan`, ~0.3s on a single-route app).
+
+```sh
+AKAN_DEV_IDLE_SUSPEND_MS=300000   # default; 0 keeps the builder resident for the whole session
+```
+
+Requests that arrive mid-wake are held and replayed against the new builder rather than answered with
+`builder is stopped`. A suspend is skipped while a build is red, while any restart or recovery is
+pending, or within 30s of a previous wake. Look for `[idle-suspend] … released the builder`, then
+`[idle-suspend] waking (…)` and `[idle-suspend] awake in …ms`.

package/server/akanApp.ts

@@ -1197,7 +1197,7 @@ export class AkanApp {
     const reader = stream.getReader();
     const decoder = new TextDecoder();
     try {
-      while (true) {
+      for (;;) {
         const { done, value } = await reader.read();
         if (done) break;
         const text = decoder.decode(value, { stream: true });
@@ -1213,7 +1213,7 @@ export class AkanApp {
 
   #writeChildOutput(idx: number, role: AkanChildRole, type: "stdout" | "stderr", bufferKey: string, text: string) {
     let buffered = `${this.#childOutputBuffers.get(bufferKey) ?? ""}${text}`;
-    while (true) {
+    for (;;) {
       const newlineIdx = buffered.indexOf("\n");
       if (newlineIdx === -1) break;
       const line = buffered.slice(0, newlineIdx + 1);

package/server/akanServer.ts

@@ -14,6 +14,7 @@ import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import type { BuilderRpc } from "./artifact";
+import { DevtoolsRouter } from "./devtools";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { isPortInUseError } from "./lifecycle/portInUse";
@@ -449,19 +450,32 @@ export class AkanServer {
   }
 
   #createBuiltinRoutes(): HttpRoutes {
-    if (!this.openapi) return {};
-    return {
-      "/openapi.json": {
-        GET: () =>
-          Response.json(
-            createOpenApiDocument(FetchSerializer.serializeRegistry(this.#di.live).signal, {
-              title: `${this.env.appName} API`,
-              version: "0.0.0",
-              servers: this.#getOpenApiServers(),
-            }),
-          ),
-      },
-    };
+    const openapiRoutes: HttpRoutes = this.openapi
+      ? {
+          "/openapi.json": {
+            GET: () =>
+              Response.json(
+                createOpenApiDocument(FetchSerializer.serializeRegistry(this.#di.live).signal, {
+                  title: `${this.env.appName} API`,
+                  version: "0.0.0",
+                  servers: this.#getOpenApiServers(),
+                }),
+              ),
+          },
+        }
+      : {};
+
+    const devtoolsRoutes = new DevtoolsRouter({
+      di: this.#di,
+      env: this.env,
+      name: this.name,
+      serverMode: this.serverMode,
+      prefix: this.prefix,
+      websocketPrefix: this.websocketPrefix,
+      openapi: this.openapi,
+      getStatus: () => this.status,
+    }).createRoutes();
+    return { ...openapiRoutes, ...devtoolsRoutes };
   }
 
   #getOpenApiServers() {

package/server/artifact/builderRpc.ts

@@ -96,10 +96,9 @@ export class BuilderRpc {
   ): Promise<BuildRouteClientResult> {
     if (this.#disposed) throw new Error("[builder] rpc is disposed");
     const id = this.#nextId++;
-    const payload = await new Promise<BuildRouteResultPayload>((resolve, reject) => {
-      this.#pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
-      this.#send({ type: "build-route", id, routeId, seeds, knownEntries: [...knownEntries], generation });
-    });
+    const payload = await this.#request<BuildRouteResultPayload>(id, `build-route ${routeId}`, () =>
+      this.#send({ type: "build-route", id, routeId, seeds, knownEntries: [...knownEntries], generation }),
+    );
     return {
       manifestDelta: payload.manifestDelta,
       ssrManifestDelta: { moduleLoading: null, moduleMap: payload.ssrManifestDelta },
@@ -118,9 +117,54 @@ export class BuilderRpc {
   async buildCsr(reason: string): Promise<void> {
     if (this.#disposed) throw new Error("[builder] rpc is disposed");
     const id = this.#nextId++;
-    await new Promise<void>((resolve, reject) => {
-      this.#pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
-      this.#send({ type: "build-csr", id, reason });
+    await this.#request<void>(id, `build-csr (${reason})`, () => this.#send({ type: "build-csr", id, reason }));
+  }
+
+  /**
+   * How long to wait for the builder before failing a request. `AKAN_BUILDER_RPC_TIMEOUT_MS` overrides.
+   *
+   * Generous, because a cold CSR build of every page legitimately takes tens of seconds; the point is not
+   * to be tight but to be finite.
+   */
+  static #timeoutMs(): number {
+    const configured = Number(process.env.AKAN_BUILDER_RPC_TIMEOUT_MS);
+    if (Number.isFinite(configured) && configured > 0) return configured;
+    return 120_000;
+  }
+
+  /**
+   * One builder request, which fails rather than waiting forever.
+   *
+   * Nothing answers a request whose builder exits after receiving it: the dev host replies `ok:false` only
+   * when the *send* fails, and it does not track in-flight ids. The builder exits routinely — it is recycled
+   * every few builds once its RSS passes the ceiling — so a page request that happens to be mid route-build
+   * left this promise pending forever, and the browser tab span with no error, no log and nothing to retry.
+   * Observed from the other side as a `fetch` that sat for 225s against a 60s budget.
+   */
+  async #request<T>(id: number, label: string, send: () => void): Promise<T> {
+    const timeoutMs = BuilderRpc.#timeoutMs();
+    return await new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(
+          new Error(
+            `[builder] ${label} got no answer in ${timeoutMs}ms; the builder was likely recycled or restarted mid-request — reload to retry`,
+          ),
+        );
+      }, timeoutMs);
+      
+      timer.unref?.();
+      this.#pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value as T);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      send();
     });
   }
 

package/server/artifact/ipcTypes.ts

@@ -9,11 +9,21 @@ export interface BuildRouteResultPayload {
   generation?: number;
 }
 
+/**
+ * Marks a frontend payload that re-announces a freshly booted artifact rather than reporting an edit.
+ * A recycled builder rebuilds every artifact from scratch, but a running backend read
+ * `base-artifact.json` once at boot and never re-reads it, so the new state has to be pushed. The
+ * host drops such a payload when the hashed output did not actually move, which keeps a clean
+ * recycle invisible to connected browsers.
+ */
+export type BuilderStateReason = "builder-recycle";
+
 export interface CssPayload {
   cssAssets: Record<string, { cssUrl: string; cssRelPath: string }>;
   cssBase64ByUrl: Record<string, string>;
   generation?: number;
   changedFiles?: string[];
+  reason?: BuilderStateReason;
 }
 
 export type DevChangeRole = "server" | "client" | "shared" | "barrel" | "config" | "css";
@@ -71,11 +81,38 @@ export type BuilderCsrRes =
   | { type: "build-csr-res"; id: number; ok: true }
   | { type: "build-csr-res"; id: number; ok: false; error: string };
 
+/**
+ * Asks the builder to finish its queued work and exit, which is the only way bundler memory is
+ * returned to the OS (see `BuilderMetrics`). The host's existing restart path brings up a
+ * replacement, so a graceful drain — rather than a kill — keeps a rebuild in flight from being
+ * truncated.
+ */
+export type BuilderControl = { type: "builder-shutdown"; reason: string };
+
 export interface PagesBundlePayload {
   bundlePath: string;
   buildId: number;
   generation?: number;
   changedFiles?: string[];
+  reason?: BuilderStateReason;
+}
+
+/**
+ * `Bun.build` retains native bundler arenas that `Bun.gc(true)` never reclaims — the JS heap stays flat
+ * while RSS climbs. **How much comes back without exiting is platform-specific**: measured on Bun
+ * 1.3.14, macOS returns none of it (0% after 60s idle) while Linux purges 46-59% after ~10-15s idle.
+ * The dev host recycles past a ceiling to bound the macOS case.
+ *
+ * Because this is only reported when the builder's queues drain, `rssBytes` is a *peak* sample. On
+ * Linux it goes stale within seconds, so the host re-reads the builder's RSS from the OS before acting
+ * on it. See `local/optimize-resource/09-linux-retention-measurement.md`.
+ */
+export interface BuilderMetrics {
+  rssBytes: number;
+  /** The builder's newest generation; 0 until it has processed a watch batch since spawning. */
+  generation: number;
+  /** Work items completed since this builder spawned, so a host can require real work before recycling. */
+  workCount: number;
 }
 
 export type BuilderEvent =
@@ -90,6 +127,7 @@ export type BuilderEvent =
     }
   | { type: "css-updated"; data: CssPayload }
   | { type: "pages-updated"; data: PagesBundlePayload }
-  | { type: "build-status"; data: DevBuildStatus };
+  | { type: "build-status"; data: DevBuildStatus }
+  | { type: "builder-metrics"; data: BuilderMetrics };
 
-export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderEvent;
+export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderControl | BuilderEvent;

package/server/devtools/constantSerializer.ts

@@ -0,0 +1,195 @@
+import {
+  type Cls,
+  type EnumInstance,
+  FIELD_META,
+  getNonArrayModel,
+  isEnum,
+  PrimitiveRegistry,
+  type PrimitiveScalar,
+} from "akanjs/base";
+import { type ConstantCls, type ConstantField, ConstantRegistry, type ConstantType } from "akanjs/constant";
+import { DatabaseRegistry, type FilterInfo, getFilterMeta } from "akanjs/document";
+import { DevtoolsJson } from "./devtoolsJson";
+import type {
+  ConstantData,
+  ConstantFieldNode,
+  ConstantModelNode,
+  ConstantModelView,
+  ConstantModelViewKey,
+  EnumNode,
+  FieldType,
+  FilterArg,
+  RelationEdge,
+} from "./types";
+
+const modelViewKeys = ["input", "object", "full", "light", "insight"] as const;
+
+/**
+ * Walks `ConstantRegistry` into the `/_akan/constant` payload.
+ *
+ * Model references are emitted by name only, never inlined, so a cyclic schema still produces a finite
+ * document. Anything the registry holds that JSON cannot express goes through {@link DevtoolsJson}.
+ */
+export class ConstantSerializer {
+  static serialize(): ConstantData {
+    const models: Record<string, ConstantModelNode> = {};
+    const relations: RelationEdge[] = [];
+    for (const [refName, cnst] of ConstantRegistry.database.entries()) {
+      const views = {} as Record<ConstantModelViewKey, ConstantModelView>;
+      const modelNames = {} as Record<ConstantModelViewKey, string>;
+      for (const viewKey of modelViewKeys) {
+        const view = ConstantSerializer.#serializeView(cnst[viewKey] as ConstantCls, viewKey);
+        views[viewKey] = view;
+        modelNames[viewKey] = view.modelName;
+        relations.push(...ConstantSerializer.#collectRelations(refName, view));
+      }
+      models[refName] = {
+        refName,
+        modelNames,
+        views,
+        ...ConstantSerializer.#serializeFilter(refName),
+      };
+    }
+
+    const scalars: Record<string, ConstantModelView> = {};
+    for (const [refName, scalar] of ConstantRegistry.scalar.entries()) {
+      scalars[refName] = ConstantSerializer.#serializeView(scalar.model, "scalar");
+    }
+
+    const enums: Record<string, EnumNode> = {};
+    for (const [key, enumRef] of ConstantRegistry.enum.entries()) {
+      enums[key] = { key, refName: enumRef.refName, values: [...enumRef.values] as (string | number)[] };
+    }
+
+    const values: Record<string, unknown> = {};
+    for (const [key, value] of ConstantRegistry.value.entries()) {
+      values[key] = DevtoolsJson.toSafe(value);
+    }
+
+    return { models, scalars, enums, values, primitives: PrimitiveRegistry.getNames().sort(), relations };
+  }
+
+  static #serializeView(modelRef: ConstantCls | undefined, modelType: ConstantType): ConstantModelView {
+    const fieldMeta = (modelRef as { [FIELD_META]?: Record<string, ConstantField> } | undefined)?.[FIELD_META] ?? {};
+    const fields: Record<string, ConstantFieldNode> = {};
+    for (const [name, field] of Object.entries(fieldMeta)) {
+      fields[name] = ConstantSerializer.#serializeField(name, field);
+    }
+    return {
+      modelName: modelRef ? ConstantRegistry.getModelName(modelRef) : "Unknown",
+      modelType,
+      fields,
+    };
+  }
+
+  static #serializeField(name: string, field: ConstantField): ConstantFieldNode {
+    const props = field.getProps();
+    const fieldKind = props.fieldType ?? "property";
+    
+    const redacted = fieldKind === "secret";
+    const defaultKind = ConstantSerializer.#resolveDefaultKind(props.default);
+    return {
+      name,
+      fieldKind,
+      type: ConstantSerializer.#resolveFieldType(props),
+      arrDepth: props.arrDepth,
+      nullable: Boolean(props.nullable),
+      immutable: Boolean(props.immutable),
+      select: props.select !== false,
+      defaultKind: redacted && defaultKind === "value" ? "none" : defaultKind,
+      ...(!redacted && defaultKind === "value" ? { default: DevtoolsJson.toSafe(props.default) } : {}),
+      ...(props.ref ? { ref: props.ref } : {}),
+      ...(props.refPath ? { refPath: props.refPath } : {}),
+      ...(props.refType ? { refType: props.refType } : {}),
+      ...(props.min !== undefined ? { min: props.min } : {}),
+      ...(props.max !== undefined ? { max: props.max } : {}),
+      ...(props.minlength !== undefined ? { minlength: props.minlength } : {}),
+      ...(props.maxlength !== undefined ? { maxlength: props.maxlength } : {}),
+      ...(props.type ? { preset: props.type } : {}),
+      ...(props.text ? { text: props.text } : {}),
+      ...(props.accumulate !== undefined ? { accumulate: DevtoolsJson.toSafe(props.accumulate) } : {}),
+      ...(!redacted && props.example !== undefined && props.example !== null
+        ? { example: DevtoolsJson.toSafe(props.example) }
+        : {}),
+      ...(props.meta && Object.keys(props.meta).length
+        ? { meta: DevtoolsJson.toSafe(props.meta) as Record<string, unknown> }
+        : {}),
+      hasValidate: typeof props.validate === "function",
+    };
+  }
+
+  /** `default: () => dayjs()` is idiomatic here — report the factory without ever invoking it. */
+  static #resolveDefaultKind(value: unknown): ConstantFieldNode["defaultKind"] {
+    if (typeof value === "function") return "function";
+    if (value === null || value === undefined) return "none";
+    return "value";
+  }
+
+  static #resolveFieldType(props: ReturnType<ConstantField["getProps"]>): FieldType {
+    if (props.enum) return ConstantSerializer.#enumType(props.enum);
+    if (props.isMap) {
+      const [valueRef, valueArrDepth] = getNonArrayModel(props.of as Cls);
+      return { kind: "map", value: ConstantSerializer.#resolveModelRef(valueRef as Cls), valueArrDepth };
+    }
+    return ConstantSerializer.#resolveModelRef(props.modelRef as Cls);
+  }
+
+  static #enumType(enumRef: EnumInstance): FieldType {
+    return { kind: "enum", refName: enumRef.refName, values: [...enumRef.values] as (string | number)[] };
+  }
+
+  static #resolveModelRef(modelRef: Cls): FieldType {
+    if (isEnum(modelRef)) return ConstantSerializer.#enumType(modelRef as unknown as EnumInstance);
+    if (PrimitiveRegistry.has(modelRef))
+      return { kind: "primitive", refName: PrimitiveRegistry.getName(modelRef as typeof PrimitiveScalar) };
+    const refName = ConstantRegistry.getRefName(modelRef, { allowEmpty: true });
+    if (!refName) return { kind: "unknown", refName: modelRef.name || "Unknown" };
+    return {
+      kind: "model",
+      refName,
+      modelType: (modelRef as ConstantCls).modelType ?? "scalar",
+      modelName: ConstantRegistry.getModelName(modelRef),
+    };
+  }
+
+  static #collectRelations(refName: string, view: ConstantModelView): RelationEdge[] {
+    return Object.values(view.fields)
+      .filter((field) => field.type.kind === "model")
+      .map((field) => {
+        const type = field.type as Extract<FieldType, { kind: "model" }>;
+        return {
+          from: refName,
+          fromView: view.modelType,
+          field: field.name,
+          to: type.refName,
+          toView: type.modelType,
+          arrDepth: field.arrDepth,
+          nullable: field.nullable,
+          ...(field.refType ? { refType: field.refType } : {}),
+        };
+      });
+  }
+
+  static #serializeFilter(refName: string): Pick<ConstantModelNode, "filter"> {
+    const database = DatabaseRegistry.getDatabase(refName, { allowEmpty: true });
+    const filterMeta = database?.filter ? getFilterMeta(database.filter, { allowEmpty: true }) : undefined;
+    if (!filterMeta) return {};
+    const query: Record<string, FilterArg[]> = {};
+    for (const [key, filterInfo] of Object.entries(filterMeta.query as Record<string, FilterInfo>)) {
+      query[key] = (filterInfo.args ?? []).map((arg) => ConstantSerializer.#serializeFilterArg(arg));
+    }
+    return { filter: { query, sort: Object.keys(filterMeta.sort ?? {}) } };
+  }
+
+  static #serializeFilterArg(arg: FilterInfo["args"][number]): FilterArg {
+    const [single, arrDepth] = getNonArrayModel(arg.argRef as Cls);
+    return {
+      name: arg.name,
+      type: ConstantSerializer.#resolveModelRef(single as Cls),
+      arrDepth,
+      nullable: Boolean(arg.option?.nullable),
+      ...(arg.option?.ref ? { ref: arg.option.ref } : {}),
+      ...(arg.option?.default !== undefined ? { default: DevtoolsJson.toSafe(arg.option.default) } : {}),
+    };
+  }
+}