akanjs 3.0.0-alpha.6 → 3.0.0-alpha.60

package/CHANGELOG.md

@@ -1,5 +1,108 @@
 # akanjs
 
+## 2.4.2
+
+### Minor Changes
+
+- 11aa655: feat(constant): remove a relation's target with its owner via `cascade: "remove"`
+
+  A relation field can now take its target down with it: `image: field(File, { cascade: "remove" })`, arrays
+  included. The removal runs through the **target's service**, so the target's own `_postRemove` runs with it —
+  that is how removing a model also deletes the file's stored blob or object, with no extra wiring in the owning
+  module.
+
+  Only a relation accepts the option. A `String`, an `ID`, a scalar, and a nested array each fail while the class
+  is being built, naming the field: none of them points at a document the framework could remove.
+
+  Target services resolve lazily, at removal time, so a cascade adds no boot-order edge between two services and a
+  cascade cycle cannot fail the boot. They resolve _before_ the parent is touched, so a model cascading into a
+  module the app never mounted fails with nothing half-removed.
+
+  Two limits worth knowing. Nothing checks whether another document still references the same target, so declaring
+  `cascade` asserts that the field owns its target exclusively. And query-level removal (`deleteManyByQuery` /
+  `updateManyByQuery`) stamps `removedAt` in one atomic update that fires no hooks and therefore no cascade —
+  remove documents one at a time when they cascade.
+
+- 11aa655: feat(store): invalidate sibling slices on create and refetch them in `Load.Units`
+
+  A model with more than one parent is listed by more than one slice, and a create could only ever be spliced
+  into the slice it was issued from. Creating a `bizDoc` from `bizDocInOrg` left `bizDocListInProject` without
+  it, and an RSC navigation back to that page replayed a cached payload whose server-stamped
+  `bizDocInitAtInProject` still satisfied `Load.Units`' cache check — so the new document stayed invisible until
+  a full reload.
+
+  `create<Model>` and `create<Model>InForm` now stamp a new per-slice `<model>StaleAt<Suffix>` on every slice
+  _except_ the one named by `sliceName`. Whether the new document belongs to a sibling slice is a server-side
+  filter decision, so the siblings are marked for revalidation rather than patched optimistically. `Load.Units`
+  refetches through `refresh<Model><Suffix>` when its slice's `StaleAt` is newer than its `InitAt`, and a
+  completed refresh restamps `InitAt` past `StaleAt` to end the stale state. The refetch is skipped while the
+  list is already loading, which also dedups several `Load.Units` mounted on one slice.
+
+  `Load.Units` also takes a `staleTime` prop, in milliseconds, for age-based revalidation independent of any
+  create: `staleTime={0}` always refetches on mount, `staleTime={30_000}` refetches only when the cached data is
+  older than 30s. Omitting it leaves the component purely invalidation-driven.
+
+  Update and remove are unchanged — they already walk every slice, because a document they touch is one the
+  cached lists can be searched for by id.
+
+- 11aa655: feat(server): add subRoute hosts at runtime with `AKAN_SUB_ROUTE_HOSTS`
+
+  An app resolved a request Host to a basePath through a map fixed at build time — the domains written into
+  `akan.config.ts` plus the generated `<basePath>-<branch>.<serveDomain>`. A platform that mints its hostnames when
+  a project is created cannot write either one into the repo, so its subRoute hosts fell through to the root app.
+
+  `AKAN_SUB_ROUTE_HOSTS` adds to that map at boot, in the same spirit as `AKAN_PUBLIC_BASE_PATHS`:
+
+  ```
+  AKAN_SUB_ROUTE_HOSTS="soft=soft-abc.try.akanjs.com,soft.acme.com;office=office-abc.try.akanjs.com"
+  ```
+
+  Hosts are matched lowercased and without a port, exactly as the built-in ones are. The env mapping is a union with
+  the built one, never a replacement, so a tenant's own domains keep working and removing the env restores the
+  previous behaviour byte for byte.
+
+  A basePath the build does not serve is dropped with a warning rather than 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. A malformed
+  entry is skipped the same way: the value is rendered by a deployment platform, and one bad character must not turn
+  into a boot loop across every pod.
+
+  `x-base-path` is now checked against the basePaths the build serves before it is trusted, matching the check
+  `getBasePathFromPathname` already applied to it. An unrecognised value falls through to host matching instead of
+  selecting a basePath that resolves to nothing.
+
+- 25d5b15: feat(devkit): sync lib `page` trees into apps and honor `pageConfig.devOnly`
+
+  Apps can opt in with `syncPageLibs` (`true` / lib list) so `akan sync` links each lib's routes under
+  `page/(libs)/(<lib>)` — once per basePath when the app has subRoutes. The link is generated and
+  gitignored; the lib source stays the edit target. Collision on the resolved route pattern is a
+  sync-time error.
+
+  `pageConfig.devOnly: true` (literal only) keeps a route out of `akan build` while `akan start` still
+  serves it. On a `_layout` it excludes the whole subtree. Symlink-aware file ops avoid wiping a synced
+  lib when cleaning an app link, and dangling lib links no longer break `getApps`.
+
+- 25d5b15: feat(signal): refresh websocket credentials in-session and re-check pubsub rooms
+
+  Handshake credentials now live on `AppWsData` (headers/cookies only). Clients that hold the token in
+  memory send it with `fetch.setJwt(...)`, which forwards an `__auth` frame; the server swaps the
+  snapshot synchronously and re-runs each subscribed room's guards, unsubscribing the ones that fail.
+
+  Guards should read the caller with `context.get("account")` instead of branching on HTTP vs websocket
+  transport. Slice-level guards still only wrap generated query/mutation endpoints — a pubsub endpoint
+  needs its own `guards` if the room itself must be protected.
+
+### Patch Changes
+
+- 6d58c7e: add search feature for sqlit database with fts5
+- 25d5b15: fix(ui): refresh EditModal when the hydrated edit payload is stale
+
+  RSC navigation can replay a cached page tree, and an edit shell hydrated from that payload can show
+  arbitrarily old form data. EditModal now treats a cache replay (or a `modelViewAt` older than 60s) as
+  stale and refetches via `edit<Model>` while keeping the modal open on the last known id.
+
+- 42cf7a2: Normalize unsendable relayed WebSocket close codes to 1001 so Bun's global client WebSocket.close no longer throws InvalidAccessError at the gateway's client-to-upstream relay when a peer disappears without a close frame (code 1006). The upstream-to-client relay applies the same normalization defensively.
+- 04cb46d: Allow the documented wsConnect export during source validation for root layouts, including base-path and grouped root boundaries, while continuing to reject it on nested layouts.
+
 ## 2.4.1
 
 ### Patch Changes

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/baseEnv.ts

@@ -15,7 +15,7 @@ export interface BaseEnv {
   operationMode: "local" | "edge" | "cloud" | "module";
   databaseMode?: DatabaseMode;
 }
-export type BackendEnv = BaseEnv & {
+export type BackendEnv = {
   hostname?: string | null;
   port?: number;
   database?: {
@@ -73,15 +73,18 @@ export type ClientEnv = BaseEnv & {
 
 let cachedEnv: ClientEnv | undefined;
 
+const missingPublicEnv = (key: string) =>
+  `getEnv() cannot run at build time: akan build does not inject ${key}. Call it from a runtime function instead of at module scope (e.g. env(() => getEnv()) in adapt(), a method body, or a default thunk).`;
+
 /** Reads and caches Akan runtime environment values from process/browser environment settings. */
 export const getEnv = (): ClientEnv => {
   if (cachedEnv) return cachedEnv;
   const appName = process.env.AKAN_PUBLIC_APP_NAME ?? "unknown";
   const repoName = process.env.AKAN_PUBLIC_REPO_NAME ?? "unknown";
   const serveDomain = process.env.AKAN_PUBLIC_SERVE_DOMAIN ?? "unknown";
-  if (appName === "unknown") throw new Error("environment variable AKAN_PUBLIC_APP_NAME is required");
-  if (repoName === "unknown") throw new Error("environment variable AKAN_PUBLIC_REPO_NAME is required");
-  if (serveDomain === "unknown") throw new Error("environment variable AKAN_PUBLIC_SERVE_DOMAIN is required");
+  if (appName === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_APP_NAME"));
+  if (repoName === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_REPO_NAME"));
+  if (serveDomain === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_SERVE_DOMAIN"));
   const environment = (process.env.AKAN_PUBLIC_ENV ?? "debug") as BaseEnv["environment"];
   const operationMode = (process.env.AKAN_PUBLIC_OPERATION_MODE ??
     (environment === "local" ? "local" : "cloud")) as BaseEnv["operationMode"];

package/base/primitiveRegistry.ts

@@ -209,12 +209,12 @@ declare global {
     [DEFAULT_VALUE]: boolean;
     [PURIFIED_VALUE]: boolean;
     [EXAMPLE_VALUE]: boolean;
-    validate(value: boolean | number): boolean;
-    parseValue(input: boolean | number): boolean | number;
-    serializeValue(value: boolean | number): boolean | number;
-    _parse(input: boolean | number): boolean;
-    _serialize(value: boolean | number): boolean;
-    _checkValue(value: boolean | number): void;
+    validate(value: boolean | number | string): boolean;
+    parseValue(input: boolean | number | string): boolean | number | string;
+    serializeValue(value: boolean | number | string): boolean | number | string;
+    _parse(input: boolean | number | string): boolean;
+    _serialize(value: boolean | number | string): boolean;
+    _checkValue(value: boolean | number | string): void;
   }
   interface DateConstructor {
     refName: "Date";
@@ -305,10 +305,14 @@ Object.assign(String, scalarPrimitiveStatics, {
 });
 PrimitiveRegistry.register(String);
 
-const normalizeBooleanPrimitiveValue = (value: boolean | number): boolean | null => {
+const normalizeBooleanPrimitiveValue = (value: boolean | number | string): boolean | null => {
   if (typeof value === "boolean") return value;
   if (value === 1) return true;
   if (value === 0) return false;
+  if (typeof value !== "string") return null;
+  const text = value.trim().toLowerCase();
+  if (text === "true" || text === "1") return true;
+  if (text === "false" || text === "0") return false;
   return null;
 };
 
@@ -317,13 +321,13 @@ Object.assign(Boolean, {
   refName: "Boolean",
   [DEFAULT_VALUE]: false,
   [EXAMPLE_VALUE]: true,
-  validate(value: boolean | number) {
+  validate(value: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(value) !== null;
   },
-  parseValue(input: boolean | number) {
+  parseValue(input: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(input) ?? input;
   },
-  serializeValue(value: boolean | number) {
+  serializeValue(value: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(value) ?? value;
   },
 });

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/capacitor.ts

@@ -46,6 +46,28 @@ export type CapacitorContactsModule = {
   };
 };
 
+export type CapacitorSpeechRecognitionModule = {
+  SpeechRecognition: {
+    available: () => Promise<{ available: boolean }>;
+    checkPermissions: () => Promise<{ speechRecognition: CapacitorPermissionState }>;
+    requestPermissions: () => Promise<{ speechRecognition: CapacitorPermissionState }>;
+    start: (options: Record<string, unknown>) => Promise<{ matches?: string[] }>;
+    stop: () => Promise<void>;
+    removeAllListeners: () => Promise<void> | void;
+    addListener: (
+      eventName: string,
+      listenerFunc: (data: { matches?: string[] }) => void,
+    ) => Promise<{ remove: () => Promise<void> | void }> | { remove: () => Promise<void> | void };
+  };
+};
+
+export type CapacitorTextToSpeechModule = {
+  TextToSpeech: {
+    speak: (options: { text: string; lang?: string; rate?: number }) => Promise<void>;
+    stop: () => Promise<void>;
+  };
+};
+
 export type CapacitorCoreModule = {
   CapacitorCookies: {
     setCookie: (options: { key: string; value: string; path?: string }) => Promise<void> | void;
@@ -155,6 +177,8 @@ type CapacitorModuleMap = {
   preferences: CapacitorPreferencesModule;
   pushNotifications: CapacitorPushNotificationsModule;
   safeArea: CapacitorSafeAreaModule;
+  speechRecognition: CapacitorSpeechRecognitionModule;
+  textToSpeech: CapacitorTextToSpeechModule;
   updater: CapacitorUpdaterModule;
 };
 
@@ -257,6 +281,16 @@ export const loadCapacitorSafeArea = () =>
     SafeArea: getCapacitorPlugin<CapacitorSafeAreaModule["SafeArea"]>("SafeArea"),
   }));
 
+export const loadCapacitorSpeechRecognition = () =>
+  loadCapacitorModule("speechRecognition", async () => ({
+    SpeechRecognition: getCapacitorPlugin<CapacitorSpeechRecognitionModule["SpeechRecognition"]>("SpeechRecognition"),
+  }));
+
+export const loadCapacitorTextToSpeech = () =>
+  loadCapacitorModule("textToSpeech", async () => ({
+    TextToSpeech: getCapacitorPlugin<CapacitorTextToSpeechModule["TextToSpeech"]>("TextToSpeech"),
+  }));
+
 export const loadCapacitorUpdater = () =>
   loadCapacitorModule("updater", async () => ({
     CapacitorUpdater: getCapacitorPlugin<CapacitorUpdaterModule["CapacitorUpdater"]>("CapacitorUpdater"),

package/client/clientRuntime.ts

@@ -1,4 +1,5 @@
 import type { SliceMeta } from "akanjs/fetch";
+import type { SerializedArg } from "akanjs/signal";
 import type { ReactNode } from "react";
 import type { TransMessageOption } from "./makePageProto";
 
@@ -47,6 +48,10 @@ type RuntimeFetch = typeof globalThis.fetch & {
   serializedSignal: Record<string, unknown>;
   setJwt: (jwt: string | null) => void;
   slice: Record<string, SliceMeta>;
+  /** Sort keys per model refName, registered from each serialized signal's filter. */
+  sortKeyMap?: Map<string, string[]>;
+  /** Filter queries per model refName, with the args each one takes — what the root slice picks from. */
+  filterQueryMap?: Map<string, { [queryKey: string]: SerializedArg[] }>;
   ws: RuntimeWs;
   [key: string]: unknown;
 };
@@ -75,6 +80,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 +94,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/csrTypes.ts

@@ -1,9 +1,10 @@
 "use client";
 import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/src/types";
 import type { PromiseOrObject } from "akanjs/base";
-import { createContext, type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
+import { type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
 import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } from "react-spring";
 import type { RouterInstance } from "./router";
+import { sharedContext } from "./sharedContext";
 import type { ReactFont } from "./types";
 
 export type TransitionType = "none" | "fade" | "bottomUp" | "stack" | "scaleOut";
@@ -349,7 +350,7 @@ export type UseCsrTransition = CsrTransitionStyles & {
 };
 
 export type CsrContextType = RouteState & UseCsrTransition;
-export const csrContext = createContext<CsrContextType>({} as unknown as CsrContextType);
+export const csrContext = sharedContext<CsrContextType>("csr", {} as unknown as CsrContextType);
 export const useCsr = () => {
   const contextValues = useContext(csrContext);
   return contextValues;
@@ -363,7 +364,7 @@ export interface PathContextType {
   setGestureEnabled: (enabled: boolean) => void;
   registerFrameSlot: (slot: FrameSlotRegistration) => () => void;
 }
-export const pathContext = createContext<PathContextType>({} as unknown as PathContextType);
+export const pathContext = sharedContext<PathContextType>("path", {} as unknown as PathContextType);
 export const usePathCtx = () => {
   const contextValues = useContext(pathContext);
   return contextValues;

package/client/index.ts

@@ -11,6 +11,7 @@ export * from "./locale";
 export * from "./makePageProto";
 export * from "./router";
 export * from "./rscNavigation";
+export * from "./sharedContext";
 export * from "./storage";
 export * from "./translator";
 export * from "./types";

package/client/locale.ts

@@ -1,4 +1,4 @@
 "use client";
-import { createContext } from "react";
+import { sharedContext } from "./sharedContext";
 
-export const dictionaryContext = createContext<{ [key: string]: { [key: string]: string } }>({});
+export const dictionaryContext = sharedContext<{ [key: string]: { [key: string]: string } }>("dictionary", {});

package/client/sharedContext.ts

@@ -0,0 +1,31 @@
+"use client";
+import { type Context, createContext } from "react";
+
+/**
+ * A React context interned on `globalThis`, which is how every context this framework owns must be made.
+ *
+ * An akan build does not give an app one copy of `akanjs`: it inlines each reachable module into every client
+ * chunk that reaches it — four copies of the agent runtime in this repo's own docs app. A context is identified
+ * by object identity, so a Provider mounted from one copy is invisible to a consumer holding another, and the
+ * consumer silently reads the context's default instead.
+ *
+ * Silently is the whole problem. `UiOverrideContext` was a plain `createContext`, so a route's `_overrides.tsx`
+ * bound its slots in the chunk holding the generated provider and every overridable component in another chunk
+ * kept rendering the framework default — no throw, no warning, and only *some* slots affected, which reads like
+ * a bug in the app's own component. The same shape cost a zone every tool it declared.
+ *
+ * The rule is therefore mechanical rather than case-by-case: a context whose Provider and consumers can be
+ * bundled apart is every context worth having, so all of them go through here. A test fails if one does not.
+ *
+ * `use-agentic` carries its own twin under a `useAgentic.` prefix, deliberately — it ships as a standalone
+ * package and cannot import this one. The prefixes keep the two namespaces from ever meeting.
+ */
+export const sharedContext = <T>(name: string, initial: T): Context<T> => {
+  const key = Symbol.for(`akanjs.context.${name}`);
+  const holder = globalThis as typeof globalThis & { [slot: symbol]: Context<T> | undefined };
+  const existing = holder[key];
+  if (existing) return existing;
+  const created = createContext(initial);
+  holder[key] = created;
+  return created;
+};

package/client/translator.ts

@@ -1,4 +1,4 @@
-import { pathGet } from "akanjs/common";
+import { pathGetLoose } from "akanjs/common";
 
 export interface Dictionary {
   [key: string]: {
@@ -63,7 +63,7 @@ export class Translator {
   static translateByLocale(lang: string, key: string, param?: Record<string, string | number>): string {
     const dictionary = getTranslatorState().langDictionaryMap.get(lang);
     if (!dictionary) return key;
-    const msg = (pathGet(key, dictionary, ".", { t: key }) as { t: string }).t;
+    const msg = (pathGetLoose(key, dictionary, ".", { t: key }) as { t: string }).t;
     return param ? msg.replace(/{([^}]+)}/g, (_, key: string) => param[key] as string) : msg;
   }
 

package/client/types.ts

@@ -1,5 +1,5 @@
 import type { BaseInsight } from "akanjs/constant";
-import type { FetchInitForm, SliceMeta } from "akanjs/fetch";
+import type { FetchInitForm, QuerySetting, SliceMeta } from "akanjs/fetch";
 import type { ReactElement, ReactNode } from "react";
 
 export type ReactFontStyle = "normal" | "italic" | "oblique";
@@ -109,7 +109,7 @@ const slugFontPart = (value: string) =>
 export interface ModelsProps<M extends { id: string }> {
   className?: string;
   slice?: SliceMeta;
-  query?: Record<string, unknown>;
+  query?: QuerySetting;
   init?: FetchInitForm<any, any>;
   onClickItem?: (model: M) => unknown;
 }
@@ -127,7 +127,7 @@ export type ModelProps<T extends string, L extends { id: string }> = { [key in T
 export interface ModelDashboardProps<Summary> {
   className?: string;
   summary: Summary;
-  queryMap?: Record<string, unknown>;
+  queryMap?: { [column: string]: QuerySetting };
   columns?: (keyof Summary)[];
   hidePresents?: boolean;
   slice?: SliceMeta;

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,21 +27,37 @@ 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";
+export { pathGetLoose } from "./pathGetLoose";
 export { pathSet } from "./pathSet";
 export { randomPick } from "./randomPick";
 export { randomPicks } from "./randomPicks";
 export {
   assertUniqueRoutePatterns,
   compareRouteSpecificity,
+  getPageSourceFileViolation,
+  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/pathGetLoose.ts

@@ -0,0 +1,31 @@
+type Indexable = Record<string, unknown>;
+
+const isIndexable = (value: unknown): value is Indexable => Object(value) === value;
+
+/**
+ * Reads a dotted path whose segments may themselves contain the separator.
+ *
+ * Dictionary keys are built as `<refName>.<value>` and an enum value is a real-world identifier — `gpt-5.6-terra`,
+ * `v1.2` — so the key is not a clean dotted path and `pathGet` splits it into segments that were never nodes.
+ * The tree stores such a key literally, so resolution has to try joined prefixes too.
+ */
+export const pathGetLoose = (
+  path: string | readonly string[],
+  obj: unknown,
+  separator = ".",
+  fallback: unknown = null,
+): unknown => {
+  const walk = (node: unknown, rest: readonly string[]): unknown => {
+    if (!rest.length) return node;
+    if (!isIndexable(node)) return undefined;
+    
+    for (let take = 1; take <= rest.length; take += 1) {
+      const child = node[rest.slice(0, take).join(separator)];
+      if (child === undefined) continue;
+      const found = walk(child, rest.slice(take));
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  return walk(obj, Array.isArray(path) ? [...path] : (path as string).split(separator)) ?? fallback;
+};