akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/README.ko.md

@@ -26,7 +26,7 @@ generated reference가 같은 의도에서 이어집니다.
 
 ## 요구사항
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript 중심의 애플리케이션 코드
 - React 기반 UI surface
 

package/README.md

@@ -25,7 +25,7 @@ server, app packaging, deployment artifacts, and generated references.
 
 ## Requirements
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript-first application code
 - React-based UI surfaces
 

package/base/symbols.ts

@@ -13,6 +13,10 @@ export const STATE_META = Symbol.for("akan.state");
 export const STATE_INIT_META = Symbol.for("akan.state.init");
 export const STATE_DERIVED_META = Symbol.for("akan.state.derived");
 export const ACTION_META = Symbol.for("akan.action");
+/** Which module declared each action. See `ActionOwner`. */
+export const ACTION_OWNER_META = Symbol.for("akan.action.owner");
+/** What a dispatcher does, carried on the function so a component handed one can annotate the DOM with it. */
+export const ACTION_TAG = Symbol.for("akan.action.tag");
 export const SERVER_VALUE = Symbol.for("akan.value.server");
 export const CLIENT_VALUE = Symbol.for("akan.value.client");
 export const DEFAULT_VALUE = Symbol.for("akan.value.default");

package/client/clientRuntime.ts

@@ -75,6 +75,13 @@ globalWithRuntime[CLIENT_RUNTIME_KEY] = state;
 const missingRuntimeError = () =>
   new Error("Akan client runtime is not registered. Import the generated app client first.");
 
+const applyRuntimeErrorConstructor = (runtime: ClientRuntime) => {
+  const instance = (runtime.fetch as RuntimeFetch | undefined)?.instance as
+    | { setErrorConstructor?: (Err: unknown) => void }
+    | undefined;
+  if (typeof instance?.setErrorConstructor === "function") instance.setErrorConstructor(runtime.Err);
+};
+
 export const registerClientRuntime = <Runtime>(
   runtime: Runtime,
   { scope = "app" }: { scope?: RuntimeScope } = {},
@@ -82,6 +89,7 @@ export const registerClientRuntime = <Runtime>(
   if (state.scope === "app" && scope === "lib") return runtime;
   state.runtime = runtime as ClientRuntime;
   state.scope = scope;
+  applyRuntimeErrorConstructor(state.runtime);
   return runtime;
 };
 

package/client/cn.ts

@@ -38,10 +38,17 @@ export const colorTokens = [
   "ring",
 ];
 
+/**
+ * Akan's semantic radius tokens (`--radius-box` / `--radius-field` in ui/styles.css). Without them
+ * `cn("rounded-field", "rounded-full")` keeps both classes and stylesheet order decides the winner.
+ */
+export const radiusTokens = ["box", "field"];
+
 const twMerge = extendTailwindMerge({
   extend: {
     theme: {
       color: colorTokens,
+      radius: radiusTokens,
     },
   },
 });

package/client/csrTypes.ts

@@ -455,6 +455,7 @@ export interface FrameLayoutState {
   keyboard: KeyboardFrameState;
   contentViewport: FrameContentViewportState;
   keyboardAccessory: KeyboardAccessoryFrameState;
+  contentAnchor?: "bottom";
   platformProfile: FramePlatformProfile;
   zIndex: FrameLayerZIndex;
   pageStateByPath: Map<string, PageState>;
@@ -463,6 +464,7 @@ export interface FrameSlotRegistration {
   scope?: FrameSlotScope;
   type: FrameSlotType;
   role?: FrameSlotRole;
+  contentAnchor?: "bottom";
   height?: number;
   estimatedHeight?: number;
   source?: "navbar" | "topInset" | "bottomInset" | "bottomTab" | (string & {});

package/client/frameDebug.ts

@@ -20,9 +20,10 @@ const isFrameDebugEnabled = () => {
 export function debugFrame(event: string, payload: DebugPayload = {}) {
   if (!isFrameDebugEnabled()) return;
   debugSeq += 1;
-  console.info(`[akan:frame:${debugSessionId}:${debugSeq}] ${event}`, {
+  const details = {
     href: window.location.href,
     now: Math.round(performance.now()),
     ...payload,
-  });
+  };
+  console.info(`[akan:frame:${debugSessionId}:${debugSeq}] ${event}`, details, JSON.stringify(details));
 }

package/common/Logger.ts

@@ -60,6 +60,10 @@ export class Logger {
   static isVerbose() {
     return Logger.#levelIdx <= 1;
   }
+  /** For hot-path callers that would otherwise build a message the level is about to discard. */
+  static shouldLog(logLevel: LogLevel) {
+    return Logger.#shouldLog(logLevel);
+  }
 
   name?: string;
   constructor(name?: string) {

package/common/deepObjectify.ts

@@ -1,9 +1,16 @@
 import { isDayjs } from "./isDayjs";
 
-export const deepObjectify = <T = unknown>(
-  obj: T | null | undefined,
-  option: { serializable?: boolean; convertDate?: "string" | "number" } = {},
-): T => {
+interface DeepObjectifyOption {
+  serializable?: boolean;
+  convertDate?: "string" | "number";
+}
+
+const objectifyChild = (value: unknown, option: DeepObjectifyOption): unknown => {
+  const modelValue = value as { __ModelType__?: string } | null | undefined;
+  return modelValue?.__ModelType__ && !option.serializable ? value : deepObjectify(value, option);
+};
+
+export const deepObjectify = <T = unknown>(obj: T | null | undefined, option: DeepObjectifyOption = {}): T => {
   if (isDayjs(obj) || obj?.constructor === Date) {
     if (!option.serializable && !option.convertDate) return obj as T;
     if (option.convertDate === "string") return obj.toISOString() as T;
@@ -12,13 +19,20 @@ export const deepObjectify = <T = unknown>(
     else return (isDayjs(obj) ? obj.toDate() : obj) as T;
   } else if (Array.isArray(obj)) {
     return obj.map((o: unknown) => deepObjectify(o, option)) as T;
+  } else if (obj instanceof Map) {
+    
+    const entries = [...obj.entries()].map(
+      ([key, value]: [string, unknown]) => [key, objectifyChild(value, option)] as const,
+    );
+    return (option.serializable ? Object.fromEntries(entries) : new Map(entries)) as T;
+  } else if (obj instanceof Set) {
+    const values = [...obj.values()].map((value: unknown) => objectifyChild(value, option));
+    return (option.serializable ? values : new Set(values)) as T;
   } else if (obj && typeof obj === "object") {
     const val: Record<string, unknown> = {};
     const objRecord = obj as Record<string, unknown>;
     Object.keys(obj).forEach((key) => {
-      const fieldValue = objRecord[key] as { __ModelType__: string } | null | undefined;
-      if (fieldValue?.__ModelType__ && !option.serializable) val[key] = fieldValue;
-      else if (typeof objRecord[key] !== "function") val[key] = deepObjectify(fieldValue, option);
+      if (typeof objRecord[key] !== "function") val[key] = objectifyChild(objRecord[key], option);
     });
     return val as T;
   } else {

package/common/index.ts

@@ -27,6 +27,15 @@ export {
   resolveAkanI18nConfig,
 } from "./localeConfig";
 export { lowerlize } from "./lowerlize";
+export {
+  isMcpDescribableArg,
+  type McpExposureEndpoint,
+  type McpExposureOption,
+  mcpBaseVerbOf,
+  mcpHintsOf,
+  mcpPromptRefusalOf,
+  mcpRefusalOf,
+} from "./mcpExposure";
 export { mergeVersion } from "./mergeVersion";
 export { objectify } from "./objectify";
 export { pathGet } from "./pathGet";
@@ -36,12 +45,17 @@ export { randomPicks } from "./randomPicks";
 export {
   assertUniqueRoutePatterns,
   compareRouteSpecificity,
+  getRouteExports,
   isRouteSourceFile,
   isSpecialRouteLeaf,
+  LAYOUT_ROUTE_EXPORTS,
   matchRoutePattern,
   normalizeRoutePattern,
+  PAGE_ROUTE_EXPORTS,
   type ParsedRouteModuleKey,
   parseRouteModuleKey,
+  RESERVED_ROUTE_CONFIG_EXPORTS,
+  ROOT_LAYOUT_ROUTE_EXPORTS,
   type RouteModuleKind,
   routeSegmentToPatternPart,
   routeSegmentToTreePath,

package/common/mcpExposure.ts

@@ -0,0 +1,99 @@
+import { capitalize } from "./capitalize";
+
+/**
+ * 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: { refName: string };
+  args: { name: string; refName: string; type: string; arrDepth?: number; nullable?: boolean }[];
+  guards?: string[];
+  fileUpload?: boolean;
+}
+
+export interface McpExposureOption {
+  /**
+   * 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.
+   */
+  readOnly?: boolean;
+}
+
+/** `Any` publishes as the empty schema, which tells a model nothing — so it is left out rather than described. */
+export const isMcpDescribableArg = (arg: { refName: string }) => arg.refName !== "Any";
+
+/** Which CRUD verb a generated endpoint key is, or `null` when the key is not one of the five. */
+export const mcpBaseVerbOf = (refName: string, key: string) => {
+  const cap = capitalize(refName);
+  if (key === refName || key === `light${cap}`) return "get" as const;
+  if (key === `create${cap}`) return "create" as const;
+  if (key === `update${cap}`) return "update" as const;
+  if (key === `remove${cap}`) return "remove" as const;
+  return 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.
+ */
+export const mcpHintsOf = (key: string, endpoint: { type: string }) => {
+  const readOnly = endpoint.type === "query";
+  const destructive = !readOnly && /^(remove|delete)/.test(key);
+  return {
+    readOnlyHint: readOnly,
+    destructiveHint: destructive,
+    idempotentHint: readOnly || /^(set|update)/.test(key),
+    openWorldHint: false,
+  };
+};
+
+/** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
+export const mcpRefusalOf = (endpoint: McpExposureEndpoint, { readOnly }: McpExposureOption = {}): string | null => {
+
+  if (!endpoint.guards?.length)
+    return "it declares no guards, and exposure follows them — write `guards: [Public]` if anonymous access is the intent.";
+  if (endpoint.type === "prompt") return mcpPromptRefusalOf(endpoint);
+  if (endpoint.type === "pubsub" || endpoint.type === "message")
+    return `\`${endpoint.type}\` rides the websocket, and its internal arguments read a socket an MCP request does not have.`;
+  if (readOnly && endpoint.type !== "query")
+    return "this deployment is read-only, which drops every endpoint that is not a query.";
+  if (endpoint.returns.refName === "Any" || endpoint.returns.refName === "Upload")
+    return `a return typed \`${endpoint.returns.refName}\` cannot be described to a model.`;
+  if (endpoint.fileUpload || endpoint.args.some((arg) => arg.refName === "Upload"))
+    return "a file upload has no MCP representation.";
+  if (endpoint.type === "mutation" && !endpoint.guards.some((name) => name !== "Public"))
+    return "a mutation needs a real guard — `[Public]` is having none, spelled out.";
+  const opaque = endpoint.args.find((arg) => !isMcpDescribableArg(arg) && arg.type !== "search" && !arg.nullable);
+  if (opaque)
+    return `its required argument \`${opaque.name}\` is typed \`Any\`, which is left out of the published schema — expose a named filter slice instead.`;
+  return null;
+};
+
+/**
+ * A prompt is a read exposed on the same terms as a query, so every rejection here is one thing: an argument
+ * `prompts/get` cannot carry. Its `arguments` is a flat string map — one string per name, and no schema beside it
+ * — which rules out the argument *kinds* the builder already refuses and, just as surely, two argument *types* it
+ * accepts. A tool escapes both because it publishes a real JSON Schema.
+ */
+export const mcpPromptRefusalOf = (endpoint: McpExposureEndpoint): string | null => {
+  const carried = endpoint.args.find((arg) => arg.type === "body" || arg.type === "msg" || arg.type === "room");
+  if (carried)
+    return `a prompt's arguments travel as a flat string map, so its \`${carried.type}\` argument \`${carried.name}\` cannot be carried.`;
+
+  const list = endpoint.args.find((arg) => arg.arrDepth);
+  if (list)
+    return `a prompt argument is one string, so its list argument \`${list.name}\` could never carry more than one value.`;
+
+  const opaque = endpoint.args.find((arg) => !isMcpDescribableArg(arg));
+  if (opaque)
+    return `its argument \`${opaque.name}\` is typed \`Any\`, and a prompt has no schema in which to describe one.`;
+  return null;
+};

package/common/pathSet.ts

@@ -1,16 +1,28 @@
 type MutableIndexable = Record<string | number, unknown>;
 type PathSegment = string | number;
+type Container = MutableIndexable | Map<PathSegment, unknown>;
 
 const toPathSegments = (path: string | readonly PathSegment[]) =>
   Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];
 
+const readChild = (container: Container, key: PathSegment) =>
+  container instanceof Map ? container.get(key) : container[key];
+
+const writeChild = (container: Container, key: PathSegment, value: unknown) => {
+  if (container instanceof Map) container.set(key, value);
+  else container[key] = value;
+};
+
 export const pathSet = <T>(obj: T, path: string | readonly PathSegment[], value: unknown): T => {
   if (Object(obj) !== obj) return obj;
   const pathSegments = toPathSegments(path);
-  pathSegments.slice(0, -1).reduce<MutableIndexable>((a, c, i) => {
-    if (Object(a[c]) === a[c]) return a[c] as MutableIndexable;
-    a[c] = Math.abs(Number(pathSegments[i + 1])) >> 0 === +pathSegments[i + 1] ? [] : {};
-    return a[c] as MutableIndexable;
-  }, obj as MutableIndexable)[pathSegments[pathSegments.length - 1]] = value;
+  const parent = pathSegments.slice(0, -1).reduce<Container>((a, c, i) => {
+    const child = readChild(a, c);
+    if (Object(child) === child) return child as Container;
+    const created = Math.abs(Number(pathSegments[i + 1])) >> 0 === +pathSegments[i + 1] ? [] : {};
+    writeChild(a, c, created);
+    return created as unknown as Container;
+  }, obj as Container);
+  writeChild(parent, pathSegments[pathSegments.length - 1], value);
   return obj;
 };

package/common/routeConvention.ts

@@ -9,6 +9,36 @@ const DIRECTORY_SCOPED_LEAVES = new Set(["_layout", "_index", "_overrides"]);
 
 export type RouteModuleKind = "page" | "layout" | "overrides";
 
+export const PAGE_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
+  "default",
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "Loading",
+]);
+export const LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([...PAGE_ROUTE_EXPORTS, "NotFound", "Error"]);
+export const ROOT_LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
+  ...LAYOUT_ROUTE_EXPORTS,
+  "fonts",
+  "manifest",
+  "theme",
+  "reconnect",
+  "wsConnect",
+  "layoutStyle",
+  "gaTrackingId",
+]);
+/** Root-layout exports that are plain config rather than components, so a PascalCase check cannot allow them. */
+export const RESERVED_ROUTE_CONFIG_EXPORTS: ReadonlySet<string> = new Set(
+  [...ROOT_LAYOUT_ROUTE_EXPORTS].filter((name) => name !== "default" && !/^[A-Z]/.test(name)),
+);
+
+export function getRouteExports(kind: "page" | "layout", { rootLayout = false } = {}): ReadonlySet<string> {
+  if (kind === "page") return PAGE_ROUTE_EXPORTS;
+  return rootLayout ? ROOT_LAYOUT_ROUTE_EXPORTS : LAYOUT_ROUTE_EXPORTS;
+}
+
 export interface ParsedRouteModuleKey {
   key: string;
   kind: RouteModuleKind;

package/constant/crystalize.ts

@@ -30,8 +30,10 @@ export const crystalize = (field: FieldProps, value: unknown): unknown => {
       isArray: false,
       arrDepth: 0,
     };
+    
+    const entries = value instanceof Map ? [...value.entries()] : Object.entries(value as Record<string, unknown>);
     return new Map(
-      Object.entries(value as Record<string, unknown>).map(([key, val]) => [
+      entries.map(([key, val]: [string, unknown]) => [
         key,
         field.of
           ? applyFnToArrayObjects(val, (v: never) => crystalize(mapValueField, v))

package/constant/fieldInfo.ts

@@ -450,7 +450,13 @@ export class ConstantField<
   get isMap() {
     return (this.modelRef as Cls) === Map;
   }
+
+  #props: FieldProps | null = null;
   getProps(): FieldProps {
+    this.#props ??= Object.freeze(this.#buildProps());
+    return this.#props;
+  }
+  #buildProps(): FieldProps {
     return {
       nullable: this.nullable as unknown as boolean,
       ref: this.ref,

package/constant/getDefault.ts

@@ -2,17 +2,45 @@ import { DEFAULT_VALUE, FIELD_META, type PrimitiveScalar } from "akanjs/base";
 import type { FieldObject } from ".";
 import type { DefaultOf } from "./types";
 
+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. */
+  perCall: [key: string, make: () => 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`.
+ */
 export const getDefault = <T>(fieldObj: FieldObject): DefaultOf<T> => {
-  const result: Record<string, unknown> = {};
+  let plan = planCache.get(fieldObj);
+  if (!plan) {
+    plan = buildPlan(fieldObj);
+    planCache.set(fieldObj, plan);
+  }
+  const result: Record<string, unknown> = { ...plan.shared };
+  for (const [key, make] of plan.perCall) result[key] = make();
+  return result as DefaultOf<T>;
+};
+
+const buildPlan = (fieldObj: FieldObject): DefaultPlan => {
+  const shared: Record<string, unknown> = {};
+  const perCall: [string, () => unknown][] = [];
   for (const [key, field] of Object.entries(fieldObj)) {
-    if (field.fieldType === "hidden" || field.fieldType === "secret") result[key] = null;
+    if (field.fieldType === "hidden" || field.fieldType === "secret") shared[key] = null;
     else if (field.default !== undefined && field.default !== null) {
-      if (typeof field.default === "function") result[key] = (field.default as () => object)();
-      else result[key] = field.default as object;
-    } else if (field.isArray) result[key] = [];
-    else if (field.nullable) result[key] = null;
-    else if (field.isClass) result[key] = field.isScalar ? getDefault(field.modelRef[FIELD_META]) : null;
-    else result[key] = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
+      if (typeof field.default === "function") perCall.push([key, field.default as () => unknown]);
+      else shared[key] = field.default as object;
+    } else if (field.isArray) perCall.push([key, () => []]);
+    else if (field.nullable) shared[key] = null;
+    else if (field.isClass) {
+      if (field.isScalar) perCall.push([key, () => getDefault(field.modelRef[FIELD_META])]);
+      else shared[key] = null;
+    } else shared[key] = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
   }
-  return result as DefaultOf<T>;
+  return { shared, perCall };
 };

package/constant/immerify.ts

@@ -9,7 +9,7 @@ export const immerify = <T extends object>(modelRef: ConstantModelRef, objOrArr:
   }) as Record<string, unknown>;
   const objRecord = objOrArr as Record<string, unknown>;
   Object.entries(modelRef[FIELD_META]).forEach(([key, field]) => {
-    if (field.isScalar && field.isClass && !!objRecord[key])
+    if (field.isScalar && field.isClass && objRecord[key])
       immeredObj[key] = immerify(field.modelRef, objRecord[key] as object);
   });
   return immeredObj as T;

package/constant/index.ts

@@ -5,6 +5,8 @@ export * from "./deserialize";
 export * from "./fieldInfo";
 export * from "./getDefault";
 export * from "./immerify";
+export * from "./labelOf";
+export * from "./mask";
 export * from "./purify";
 export * from "./serialize";
 export * from "./textFieldPathSet";

package/constant/labelOf.ts

@@ -0,0 +1,17 @@
+/**
+ * The one line a human scans for, 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.
+ */
+export const labelOf = (model: unknown, value: unknown): string | undefined => {
+  if (!value || typeof value !== "object") return undefined;
+  const source = value as Record<string, unknown>;
+  const paths = (model as { text?: { title?: Iterable<string> } } | null)?.text?.title;
+  const titlePath = [...(paths ?? [])].find((path) => !path.includes(".") && !path.includes("["));
+  for (const key of [titlePath, "title", "name"]) {
+    if (!key) continue;
+    const candidate = source[key];
+    if (typeof candidate === "string" && candidate) return candidate;
+  }
+  return undefined;
+};

package/constant/mask.ts

@@ -0,0 +1,60 @@
+import { FIELD_META } 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.
+ */
+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;
+  modelRef?: MaskModel;
+}
+
+export const maskFieldsOf = (model: MaskModel): Record<string, MaskField> | null => {
+  const fields = (model as unknown as { [key: symbol]: unknown })[FIELD_META];
+  return fields && typeof fields === "object" ? (fields as Record<string, MaskField>) : null;
+};
+
+/** The `hidden` and `secret` field names of `model` that `value` still carries populated. */
+export const leakingFieldsOf = (model: MaskModel, value: Record<string, unknown>): string[] => {
+  const fields = maskFieldsOf(model);
+  if (!fields) return [];
+  return Object.entries(fields)
+    .filter(([key, field]) => (field.fieldType === "hidden" || field.fieldType === "secret") && key in value)
+    .map(([key]) => key);
+};
+
+/**
+ * Strips what a model marks `hidden` or `secret`, by the model the caller names rather than by the one the value
+ * happens to still carry.
+ *
+ * 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.
+ */
+export const mask = (model: MaskModel, value: unknown): unknown => {
+  if (value === null || value === undefined || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item: unknown) => mask(model, item));
+  const fields = maskFieldsOf(model);
+  if (!fields) return value;
+  const source = value as Record<string, unknown>;
+  const masked: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(fields)) {
+    if (field.fieldType === "hidden" || field.fieldType === "secret" || !(key in source)) continue;
+    masked[key] = field.isClass && field.modelRef ? mask(field.modelRef, source[key]) : source[key];
+  }
+  return masked;
+};

package/constant/purify.ts

@@ -31,18 +31,24 @@ type Purified<O> = O extends BaseObject
       : O extends object
         ? PurifiedModel<O>
         : O;
-type PurifiedWithObjectToId<T, StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> = {
-  [K in StateKeys as null extends T[K] ? never : K]: Purified<T[K]>;
-} & {
-  [K in StateKeys as null extends T[K] ? K : never]?: Purified<T[K]> | undefined;
-};
-export type PurifiedModel<T> = T extends (infer S)[]
-  ? PurifiedModel<S>[]
-  : T extends string | number | boolean | Dayjs | File
+type PurifiedWithObjectToId<T, StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> =
+  
+  unknown extends T
     ? T
-    : T extends Map<infer K, infer V>
-      ? Map<K, PurifiedModel<V>>
-      : PurifiedWithObjectToId<T>;
+    : {
+        [K in StateKeys as null extends T[K] ? never : K]: Purified<T[K]>;
+      } & {
+        [K in StateKeys as null extends T[K] ? K : never]?: Purified<T[K]> | undefined;
+      };
+export type PurifiedModel<T> = unknown extends T
+  ? T
+  : T extends (infer S)[]
+    ? PurifiedModel<S>[]
+    : T extends string | number | boolean | Dayjs | File
+      ? T
+      : T extends Map<infer K, infer V>
+        ? Map<K, PurifiedModel<V>>
+        : PurifiedWithObjectToId<T>;
 
 export type UploadableClientArg<T> = [T] extends [File[]] ? File[] | FileList : T;
 

package/constant/types.ts

@@ -14,18 +14,20 @@ type ObjectToId<O> = O extends BaseObject
         ? DocumentModel<O>
         : O;
 
-type Docify<T, _StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> = {
-  [K in _StateKeys as null extends T[K] ? never : K]-?: ObjectToId<NonNullable<T[K]>>;
-} & {
-  [K in _StateKeys as null extends T[K] ? K : never]?: ObjectToId<NonNullable<T[K]>> | undefined;
-};
-export type DocumentModel<T> = T extends (infer S)[]
-  ? DocumentModel<S>[]
-  : T extends string | number | boolean | Dayjs | File
-    ? T
-    : T extends Map<infer K, infer V>
-      ? Map<K, DocumentModel<V>>
-      : Docify<T>;
+type Docify<T, _StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> = unknown extends T
+  ? T
+  : { [K in _StateKeys as null extends T[K] ? never : K]-?: ObjectToId<NonNullable<T[K]>> } & {
+      [K in _StateKeys as null extends T[K] ? K : never]?: ObjectToId<NonNullable<T[K]>> | undefined;
+    };
+export type DocumentModel<T> = unknown extends T
+  ? T
+  : T extends (infer S)[]
+    ? DocumentModel<S>[]
+    : T extends string | number | boolean | Dayjs | File
+      ? T
+      : T extends Map<infer K, infer V>
+        ? Map<K, DocumentModel<V>>
+        : Docify<T>;
 
 export type FieldState<T> = T extends { id: string } ? T | null : T;
 export type DefaultOf<S> = GetStateObject<{ [K in keyof S]: FieldState<S[K]> }>;

package/dictionary/DictionaryLookup.ts

@@ -0,0 +1,30 @@
+import { pathGet } from "akanjs/common";
+import { DictionaryRegistry } from "./dictionaryRegistry";
+import type { DictionaryNode } from "./trans";
+
+/**
+ * Reads translated text out of the merged dictionary tree by dotted key (`user.signal.createUser.arg.data.desc`).
+ *
+ * Unlike `translate`, a missing key resolves to `undefined` rather than echoing the key back: callers here are
+ * document generators (OpenAPI, MCP) that must omit an absent description instead of emitting `"user.signal.…"`
+ * as if it were prose. The merged root is snapshotted once per instance, so build a fresh one per document.
+ */
+export class DictionaryLookup {
+  readonly language: string;
+  readonly #models: Record<string, DictionaryNode>;
+  constructor(language?: string) {
+    const root = DictionaryRegistry.getRoot();
+    this.language = language && root[language] ? language : (Object.keys(root).at(0) ?? "en");
+    this.#models = root[this.language] ?? {};
+  }
+
+  /** A bare refName names the model node itself, which holds no text of its own — its label is `<refName>.modelName`. */
+  text(key: string): string | undefined {
+    const [refName, ...rest] = key.split(".");
+    if (!refName) return undefined;
+    const model = this.#models[refName];
+    const node = (rest.length ? pathGet(rest.join("."), model) : model) as { t?: unknown } | null;
+    const text = node?.t;
+    return typeof text === "string" && text.length ? text : undefined;
+  }
+}