akanjs 3.0.0-beta.8 → 3.0.0

package/server/consoleSession.ts

@@ -1,6 +1,5 @@
 import { clearLine, createInterface, cursorTo, type Interface } from "node:readline";
 import { inspect } from "node:util";
-import { evaluateAkanConsoleInput, isAkanConsoleInputComplete } from "./consoleEvaluator";
 import { ConsolePasteFilter } from "./consolePasteFilter";
 
 export interface AkanConsoleCommand {
@@ -18,6 +17,58 @@ export interface AkanConsoleSessionOptions {
   commands?: Record<string, AkanConsoleCommand>;
 }
 
+type AsyncFunctionConstructor = new (...args: string[]) => (scope: object) => Promise<unknown>;
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as AsyncFunctionConstructor;
+
+const incompleteSyntaxMessages = [
+  "Unexpected end of script",
+  "Unexpected EOF",
+  "Unexpected token '}'",
+  "Multiline comment was not closed properly",
+  "Unexpected end of input",
+  "Unterminated",
+] as const;
+
+const createScope = (context: Record<string, unknown>) =>
+  new Proxy(context, {
+    has: () => true,
+    get(target, prop) {
+      if (prop === Symbol.unscopables) return undefined;
+      if (prop in target) return target[prop as keyof typeof target];
+      return (globalThis as Record<PropertyKey, unknown>)[prop];
+    },
+    set(target, prop, value) {
+      target[prop as keyof typeof target] = value;
+      return true;
+    },
+  });
+
+export const isAkanConsoleInputComplete = (source: string) => {
+  const trimmed = source.trim();
+  if (!trimmed) return true;
+  try {
+    new AsyncFunction(trimmed);
+    return true;
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) return true;
+    return !incompleteSyntaxMessages.some((message) => error.message.includes(message));
+  }
+};
+
+export const evaluateAkanConsoleInput = async (source: string, context: Record<string, unknown>) => {
+  const trimmed = source.trim();
+  if (!trimmed) return undefined;
+  const scope = createScope(context);
+
+  try {
+    return await new AsyncFunction("scope", `with (scope) { return await (${trimmed}); }`)(scope);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    return await new AsyncFunction("scope", `with (scope) { return await (async () => {\n${trimmed}\n})(); }`)(scope);
+  }
+};
+
 const commandNames = new Set([".help", ".globals", ".clear", ".exit", ".quit"]);
 
 export class AkanConsoleSession {
@@ -47,12 +98,10 @@ export class AkanConsoleSession {
     this.#commands = options.commands ?? {};
   }
 
-  /** Runs when the session closes; what a command that holds a connection uses to let go of it. */
   onClose(dispose: () => void) {
     this.#disposers.push(dispose);
   }
 
-  /** Output that arrives between keystrokes: the prompt line is cleared, the text lands, the prompt redraws. */
   write(text: string) {
     if (this.#closed || !this.#interface) {
       this.#output.write(text);
@@ -128,7 +177,7 @@ export class AkanConsoleSession {
       return;
     }
     if (!force && !isAkanConsoleInputComplete(source)) {
-      this.#promptContinuation();
+      this.#reprompt(this.#continuation);
       return;
     }
     this.#lines = [];
@@ -212,15 +261,9 @@ export class AkanConsoleSession {
     this.#output.write(`${error instanceof Error ? error.stack || error.message : String(error)}\n`);
   }
 
-  #reprompt() {
-    if (this.#closed || !this.#interface) return;
-    this.#interface.setPrompt(this.#prompt);
-    this.#interface.prompt();
-  }
-
-  #promptContinuation() {
+  #reprompt(prompt = this.#prompt) {
     if (this.#closed || !this.#interface) return;
-    this.#interface.setPrompt(this.#continuation);
+    this.#interface.setPrompt(prompt);
     this.#interface.prompt();
   }
 

package/server/contentEncoding.ts

@@ -7,12 +7,6 @@ const COMPRESSIBLE_TYPES = new Set([
   "image/svg+xml",
 ]);
 
-/**
- * br is tried first: it is ~15% smaller than gzip across the artifact and ~22% on the CSS bundle, and on a
- * model listing it is half of gzip's size at the same cost. The gzip entry stays the fallback because browsers
- * only advertise `br` on secure origins, so a plain-http dev server or an intermediary that rewrites
- * Accept-Encoding still gets a compressed body.
- */
 export const CONTENT_ENCODINGS = [
   { encoding: "br", ext: ".br", accept: /(?:^|,)\s*(?:br|\*)(?![\w-])\s*(?:;\s*q=([\d.]+))?/i },
   { encoding: "gzip", ext: ".gz", accept: /(?:^|,)\s*(?:gzip|\*)(?![\w-])\s*(?:;\s*q=([\d.]+))?/i },
@@ -28,20 +22,18 @@ export const acceptsEncoding = (acceptEncoding: string, accept: RegExp): boolean
 
 export const isCompressibleContentType = (contentType: string): boolean => {
   const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
-
+  
   if (type === "text/event-stream") return false;
   return type.startsWith("text/") || COMPRESSIBLE_TYPES.has(type);
 };
 
-/**
- * Quality 4, not brotli's default 11: on a 132KB model listing q4 lands at 1.4KB in 0.10ms, where q11 spends
- * tens of milliseconds to save a few hundred more bytes. gzip level 6 costs the same 0.10ms and lands at 2.7KB.
- */
 const BROTLI_QUALITY = 4;
 const GZIP_LEVEL = 6;
 /** Under a KB the framing bytes and the call cost more than the repetition they remove. */
 const MIN_COMPRESS_BYTES = 1024;
 
+const MAX_COMPRESS_BYTES = 4 * 1024 * 1024;
+
 const compressBody = (bytes: Uint8Array, encoding: ContentEncoding) =>
   encoding === "br"
     ? brotliCompressSync(bytes, {
@@ -52,24 +44,21 @@ const compressBody = (bytes: Uint8Array, encoding: ContentEncoding) =>
       })
     : gzipSync(bytes, { level: GZIP_LEVEL });
 
-export const negotiateContentEncoding = (req: Request): ContentEncoding | null => {
-  if (process.env.AKAN_HTTP_COMPRESS === "false" || process.env.AKAN_HTTP_COMPRESS === "0") return null;
-  const acceptEncoding = req.headers.get("accept-encoding") ?? "";
-  return CONTENT_ENCODINGS.find(({ accept }) => acceptsEncoding(acceptEncoding, accept))?.encoding ?? null;
-};
+const isWholeBody = (req: Request, response: Response) =>
+  !req.headers.has("range") &&
+  !response.headers.has("content-range") &&
+  response.status >= 200 &&
+  response.status < 300 &&
+  response.status !== 206;
 
-/**
- * Compresses a fully-materialized response the caller accepts an encoding for, or hands back the original.
- *
- * Buffers the body, so it is only ever applied where the body is already in memory — a signal endpoint's JSON.
- * A streamed response (SSR HTML, an RSC flight payload, an event stream) must not reach this: buffering one
- * would hold the whole render before the first byte, which is the opposite of what streaming it was for.
- */
 export const compressResponse = async (req: Request, response: Response): Promise<Response> => {
   if (response.headers.has("content-encoding") || !response.body) return response;
-  const contentType = response.headers.get("content-type") ?? "";
-  if (!isCompressibleContentType(contentType)) return response;
-  const encoding = negotiateContentEncoding(req);
+  if (!isWholeBody(req, response)) return response;
+  if (Number(response.headers.get("content-length")) > MAX_COMPRESS_BYTES) return response;
+  if (!isCompressibleContentType(response.headers.get("content-type") ?? "")) return response;
+  if (process.env.AKAN_HTTP_COMPRESS === "false" || process.env.AKAN_HTTP_COMPRESS === "0") return response;
+  const acceptEncoding = req.headers.get("accept-encoding") ?? "";
+  const encoding = CONTENT_ENCODINGS.find(({ accept }) => acceptsEncoding(acceptEncoding, accept))?.encoding;
   if (!encoding) return response;
   const bytes = new Uint8Array(await response.arrayBuffer());
   if (bytes.byteLength < MIN_COMPRESS_BYTES) return new Response(bytes, response);
@@ -81,3 +70,40 @@ export const compressResponse = async (req: Request, response: Response): Promis
   headers.append("Vary", "Accept-Encoding");
   return new Response(compressed, { status: response.status, statusText: response.statusText, headers });
 };
+
+export interface EncodedSidecar {
+  bytes: ArrayBuffer;
+  encoding: string;
+}
+
+export const resolveEncodedSidecar = async (
+  req: Request,
+  filePath: string,
+  contentType: string,
+): Promise<EncodedSidecar | null> => {
+  if (!isCompressibleContentType(contentType)) return null;
+  const acceptEncoding = req.headers.get("accept-encoding") ?? "";
+  for (const { encoding, ext, accept } of CONTENT_ENCODINGS) {
+    if (!acceptsEncoding(acceptEncoding, accept)) continue;
+    const file = Bun.file(`${filePath}${ext}`);
+    if (!(await file.exists())) continue;
+    const bytes = await file.bytes();
+    const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+    return { bytes: buffer, encoding };
+  }
+  return null;
+};
+
+export const encodedFileResponse = async (
+  req: Request,
+  filePath: string,
+  contentType: string,
+  headers: Headers,
+): Promise<Response> => {
+  const sidecar = await resolveEncodedSidecar(req, filePath, contentType);
+  if (!sidecar) return new Response(Bun.file(filePath).stream(), { headers });
+  headers.set("Content-Encoding", sidecar.encoding);
+  headers.set("Content-Length", String(sidecar.bytes.byteLength));
+  headers.set("Vary", "Accept-Encoding");
+  return new Response(sidecar.bytes, { headers });
+};

package/server/decorators.ts

@@ -1,27 +1,11 @@
-/**
- * Method decorators for a server class: `@Transaction`, `@Try`, `@CacheMethod`. Kept because `libs/util`'s
- * storage adaptors use `@Try` on their remote calls; new code follows the adaptor rule instead
- * (`catch` → `logger.error` → `return null`).
- */
+
 
 type DecoratedInstance = {
-  logger?: { warn?: (message: string) => void; trace?: (message: string) => void };
+  logger?: { warn?: (message: string) => void };
   __database?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> };
-  __databaseModel?: {
-    __database?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> };
-    __model?: { modelName: string };
-    __cache?: {
-      get: (key: string) => Promise<string | null>;
-      set: (key: string, value: string, option: unknown) => unknown;
-    };
-  };
+  __databaseModel?: { __database?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> } };
   database?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> };
   connection?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> };
-  __model?: { modelName: string };
-  __cache?: {
-    get: (key: string) => Promise<string | null>;
-    set: (key: string, value: string, option: unknown) => unknown;
-  };
 };
 
 /** Method decorator that catches errors and logs a warning instead of throwing. */
@@ -30,8 +14,7 @@ export const Try = () => {
     const originMethod = descriptor.value as (this: unknown, ...args: unknown[]) => unknown;
     descriptor.value = async function (...args: unknown[]) {
       try {
-        const result = await originMethod.apply(this, args);
-        return result;
+        return await originMethod.apply(this, args);
       } catch (e) {
         (this as DecoratedInstance).logger?.warn?.(`${key} action error return: ${e}`);
       }
@@ -53,52 +36,3 @@ export const Transaction = (): MethodDecorator => {
     return descriptor;
   }) as MethodDecorator;
 };
-
-/**
- * Method decorator that caches method results for the given timeout in milliseconds.
- *
- * Not `Cache` — `akanjs/signal` exports a `Cache` **middleware class**, and an app importing both barrels got
- * one name meaning two things.
- */
-export const CacheMethod = (timeout = 1000, getCacheKey?: (...args: unknown[]) => string): MethodDecorator => {
-  return ((_target: unknown, key: string, descriptor: PropertyDescriptor) => {
-    const originMethod = descriptor.value as (this: unknown, ...args: unknown[]) => unknown;
-    const cacheMap = new Map<string, unknown>();
-    const timerMap = new Map<string, NodeJS.Timeout>();
-    descriptor.value = async function (...args: unknown[]) {
-      const instance = this as DecoratedInstance;
-      const classType = instance.__model ? "doc" : instance.__databaseModel ? "service" : "class";
-      const model = instance.__model ?? instance.__databaseModel?.__model;
-      const cache = instance.__cache ?? instance.__databaseModel?.__cache;
-      const cacheKeyValue = getCacheKey ? getCacheKey(...args) : JSON.stringify(args);
-      const cacheKey = `${classType}:${model?.modelName ?? "unknown"}:${key}:${cacheKeyValue}`;
-      const getCache = async (cacheKey: string) => {
-        if (classType === "class") return cacheMap.get(cacheKey);
-        const cached = (await cache?.get(cacheKey)) as string | null;
-        if (cached) return JSON.parse(cached);
-        return null;
-      };
-      const setCache = async (cacheKey: string, value: unknown) => {
-        if (classType === "class") {
-          const existingTimer = timerMap.get(cacheKey);
-          if (existingTimer) clearTimeout(existingTimer);
-          cacheMap.set(cacheKey, value);
-          const timer = setTimeout(() => {
-            cacheMap.delete(cacheKey);
-            timerMap.delete(cacheKey);
-          }, timeout);
-          timerMap.set(cacheKey, timer);
-        } else await cache?.set(cacheKey, JSON.stringify(value), { PX: timeout });
-      };
-      const cachedData = await getCache(cacheKey);
-      if (cachedData) {
-        instance.logger?.trace?.(`${model?.modelName ?? "unknown"} cache hit: ${cacheKey}`);
-        return cachedData;
-      }
-      const result = await originMethod.apply(this, args);
-      await setCache(cacheKey, result);
-      instance.logger?.trace?.(`${model?.modelName ?? "unknown"} cache set: ${cacheKey}`);
-      return result;
-    };
-  }) as MethodDecorator;
-};

package/server/devtools/constantSerializer.ts

@@ -24,12 +24,7 @@ import type {
 
 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}.
- */
+/** Model references are emitted by name, never inlined, so a cyclic schema still yields a finite document. */
 export class ConstantSerializer {
   static serialize(): ConstantData {
     const models: Record<string, ConstantModelNode> = {};
@@ -94,7 +89,7 @@ export class ConstantSerializer {
     const fieldKind = props.fieldType ?? "property";
     
     const redacted = fieldKind === "secret";
-    const defaultKind = ConstantSerializer.#resolveDefaultKind(props.default);
+    const defaultKind = typeof props.default === "function" ? "function" : props.default == null ? "none" : "value";
     return {
       name,
       fieldKind,
@@ -125,13 +120,6 @@ export class ConstantSerializer {
     };
   }
 
-  /** `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) {

package/server/devtools/depsSerializer.ts

@@ -1,7 +1,6 @@
 import { type BaseEnv, INJECT_META } from "akanjs/base";
 import type { AdaptorCls, InjectInfo, ServiceCls } from "akanjs/service";
 import type { DiLifecycle } from "../di/diLifecycle";
-import { DevtoolsJson } from "./devtoolsJson";
 import type { DepEdge, DepEdgeKind, DepNode, DepNodeKind, DepsData } from "./types";
 
 export interface DepsSerializerContext {
@@ -17,13 +16,7 @@ export interface DepsSerializerContext {
 
 type InjectableCls = { [INJECT_META]?: Record<string, InjectInfo>; refName: string };
 
-/**
- * Turns the DI container into a plain node/edge graph for the `/_akan/deps` visualiser.
- *
- * Edge derivation mirrors `InjectInfo.resolveInjection` field-for-field, so the drawn graph is the one that
- * actually resolves at boot rather than a plausible reconstruction of it. Only classes and refNames are
- * emitted — never a live instance, which for `uses` routinely closes over credentials.
- */
+/** Edges mirror `InjectInfo.resolveInjection` field-for-field, so the graph is the one that resolves at boot. */
 export class DepsSerializer {
   readonly #context: DepsSerializerContext;
   readonly #nodes = new Map<string, DepNode>();
@@ -57,10 +50,7 @@ export class DepsSerializer {
     const { di } = this.#context;
     const serviceStageOf = DepsSerializer.#stageIndex(di.hierarchy.serviceStages);
     const adaptorStageOf = DepsSerializer.#stageIndex(di.hierarchy.adaptorStages);
-    const roleOf = new Map<string, string>();
-    di.registry.adaptorRole.forEach((impl, role) => {
-      roleOf.set(impl.refName, role.refName);
-    });
+    const roleOf = new Map([...di.registry.adaptorRole].map(([role, impl]) => [impl.refName, role.refName] as const));
 
     di.registry.serviceCls.forEach((cls, refName) => {
       this.#node("service", refName, {
@@ -112,24 +102,16 @@ export class DepsSerializer {
 
   #collectEdges() {
     const { di } = this.#context;
-    di.registry.serviceCls.forEach((cls, refName) => {
-      this.#edgesFrom(this.#node("service", refName), cls as InjectableCls);
-    });
-    di.registry.adaptorCls.forEach((cls, refName) => {
-      this.#edgesFrom(this.#node("adaptor", refName), cls as InjectableCls);
-    });
-    di.registry.serverSignalCls.forEach((cls, refName) => {
-      this.#edgesFrom(this.#node("serverSignal", refName), cls as unknown as InjectableCls);
-    });
-    di.registry.internalCls.forEach((cls, refName) => {
-      this.#edgesFrom(this.#node("internal", refName), cls as unknown as InjectableCls);
-    });
-    di.registry.endpointCls.forEach((cls, refName) => {
-      this.#edgesFrom(this.#node("endpoint", refName), cls as unknown as InjectableCls);
-    });
-    di.live.sliceCls.forEach((cls, refName) => {
-      this.#edgesFrom(this.#node("slice", refName), cls as unknown as InjectableCls);
-    });
+    const sources: [DepNodeKind, Map<string, unknown>][] = [
+      ["service", di.registry.serviceCls],
+      ["adaptor", di.registry.adaptorCls],
+      ["serverSignal", di.registry.serverSignalCls],
+      ["internal", di.registry.internalCls],
+      ["endpoint", di.registry.endpointCls],
+      ["slice", di.live.sliceCls],
+    ];
+    for (const [kind, classes] of sources)
+      for (const [refName, cls] of classes) this.#edgesFrom(this.#node(kind, refName), cls as InjectableCls);
   }
 
   #edgesFrom(from: string, cls: InjectableCls) {
@@ -193,9 +175,7 @@ export class DepsSerializer {
       detail: {
         local: Boolean(injectInfo.local),
         isMap: Boolean(injectInfo.isMap),
-        ...(injectInfo.cacheOption?.expireAt !== undefined
-          ? { expireAt: DevtoolsJson.toSafe(injectInfo.cacheOption.expireAt) }
-          : {}),
+        ...(injectInfo.ttl !== undefined ? { ttl: injectInfo.ttl } : {}),
       },
     };
   }
@@ -210,18 +190,12 @@ export class DepsSerializer {
     );
   }
 
-  /**
-   * An `env` inject only knows its keys by running its factory, and factories construct SDK clients and open
-   * sockets — so scan the source for `env.KEY` / `env["KEY"]` instead of invoking it. Slightly over-inclusive,
-   * which is fine: this is a local-dev endpoint reading unminified source, and it exposes names, never values.
-   */
   static #extractEnvKeys(fn: (options: never) => unknown): string[] {
     const source = Function.prototype.toString.call(fn);
     const matches = [...source.matchAll(/\.\s*([A-Za-z_$][\w$]*)|\[\s*["'`]([^"'`]+)["'`]\s*\]/g)];
     return [...new Set(matches.map((match) => match[1] ?? match[2]).filter((key): key is string => Boolean(key)))];
   }
 
-  /** Values only for `AKAN_PUBLIC_*`; every other key contributes its name and nothing else. */
   static #serializeEnv(env: BaseEnv): DepsData["env"] {
     const publicEnv: Record<string, string> = {};
     Object.entries(process.env).forEach(([key, value]) => {
@@ -232,13 +206,7 @@ export class DepsSerializer {
   }
 
   static #stageIndex(stages: string[][]): Map<string, number> {
-    const index = new Map<string, number>();
-    stages.forEach((stage, stageIdx) => {
-      stage.forEach((refName) => {
-        index.set(refName, stageIdx);
-      });
-    });
-    return index;
+    return new Map(stages.flatMap((stage, stageIdx) => stage.map((refName) => [refName, stageIdx] as const)));
   }
 
   static #classNameOf(value: unknown): string {

package/server/devtools/devtoolsJson.ts

@@ -1,17 +1,9 @@
 import { dayjs } from "akanjs/base";
 import type { Unserializable } from "./types";
 
-/**
- * Coerces arbitrary registry values into something `JSON.stringify` can round-trip.
- *
- * Registries hold whatever a `.constant.ts` happened to export — Dayjs defaults, Maps, Sets, classes,
- * closures, even cyclic graphs. The devtools payloads must never throw on one of those, so anything
- * unrepresentable degrades to an `Unserializable` marker the visualiser can render as-is.
- */
+/** Never throws: what JSON cannot represent (functions, classes, cycles, …) becomes an `Unserializable` marker. */
 export class DevtoolsJson {
-  static readonly #defaultMaxDepth = 6;
-
-  static toSafe(value: unknown, { maxDepth = DevtoolsJson.#defaultMaxDepth }: { maxDepth?: number } = {}): unknown {
+  static toSafe(value: unknown, { maxDepth = 6 }: { maxDepth?: number } = {}): unknown {
     return DevtoolsJson.#coerce(value, maxDepth, new WeakSet<object>());
   }
 
@@ -33,7 +25,6 @@ export class DevtoolsJson {
     }
   }
 
-  /** Returns `undefined` when `value` is not a leaf this method owns, so the caller keeps walking. */
   static #coercePrimitive(value: unknown): unknown {
     switch (typeof value) {
       case "string":
@@ -46,18 +37,15 @@ export class DevtoolsJson {
         return DevtoolsJson.#mark("bigint", String(value));
       case "symbol":
         return DevtoolsJson.#mark("symbol", (value as symbol).description);
-      case "function":
-        return DevtoolsJson.#coerceFunction(value as (...args: never[]) => unknown);
+      case "function": {
+        const isClass = /^\s*class\s/.test(Function.prototype.toString.call(value));
+        return DevtoolsJson.#mark(isClass ? "class" : "function", (value as () => unknown).name || undefined);
+      }
       default:
         return undefined;
     }
   }
 
-  static #coerceFunction(value: (...args: never[]) => unknown): Unserializable {
-    const isClass = /^\s*class\s/.test(Function.prototype.toString.call(value));
-    return DevtoolsJson.#mark(isClass ? "class" : "function", value.name || undefined);
-  }
-
   static #coerceObject(value: object, depthLeft: number, seen: WeakSet<object>): unknown {
     if (dayjs.isDayjs(value)) return value.toISOString();
     if (value instanceof Date) return value.toISOString();

package/server/devtools/devtoolsRouter.ts

@@ -19,21 +19,12 @@ export interface DevtoolsRouterContext {
   getStatus: () => string;
 }
 
-/**
- * Local-dev-only JSON endpoints that describe the running system for developer tools.
- *
- * These are registered as builtin routes rather than as signal endpoints so they stay off the `/api` prefix,
- * skip guards and the middleware chain, and — most importantly — never enter the `serializedSignal` payload
- * that ships to every client bundle in production.
- */
+/** Builtin routes, not signals: off `/api` and guards, and never in the `serializedSignal` payload sent to clients. */
 export class DevtoolsRouter {
   static readonly basePath = "/_akan";
   static readonly logger = new Logger("DevtoolsRouter");
 
-  /**
-   * `AKAN_DEVTOOLS` is an explicit override for debugging a deployed environment; otherwise the endpoints
-   * exist only under `AKAN_PUBLIC_ENV=local`. Shape mirrors `AkanServer.#isOpenApiEnvEnabled`.
-   */
+  /** Local-only unless `AKAN_DEVTOOLS` ("true"/"1", "false"/"0") overrides it, e.g. to debug a deployed env. */
   static isEnabled(env: BaseEnv): boolean {
     const override = process.env.AKAN_DEVTOOLS;
     if (override === "false" || override === "0") return false;
@@ -126,7 +117,6 @@ export class DevtoolsRouter {
     };
   }
 
-  /** `?lang=en` narrows the tree to one language — full dictionaries get large fast. */
   static #dictionary(req: Request): DictionaryData {
     const lang = new URL(req.url).searchParams.get("lang");
     const root = DictionaryRegistry.getRoot();

package/server/devtools/signalSerializer.ts

@@ -24,6 +24,7 @@ import { FetchSerializer } from "../../signal/serializer";
 import type { DatabaseModule, ServiceModule } from "../akanLib";
 import type { DiLifecycle } from "../di/diLifecycle";
 import { SignalResolver } from "../resolver";
+import { ApiRouter } from "../routing/apiRouter";
 import type { EndpointNode, InternalNode, RouteRow, SignalData, SignalNode, SliceNode } from "./types";
 
 export interface SignalSerializerContext {
@@ -33,15 +34,7 @@ export interface SignalSerializerContext {
   websocketPrefix: string;
 }
 
-/**
- * Builds the `/_akan/signal` payload from the live DI container.
- *
- * The client-side `getSerializedSignal()` is deliberately *not* used here: its map is seeded with the `base`
- * signal and only completed at build time via `applySignal`, so on a server process it under-reports the API.
- * Declared endpoints come from `FetchSerializer.serializeRegistry(di.live)` (what `/openapi.json` uses), the
- * framework-generated CRUD/slice endpoints come from the slice endpoint class the resolver synthesized, and
- * internals — absent from `SerializedSignal` entirely — are read straight off `INTERNAL_META`.
- */
+/** Built from the live DI container: on a server, `getSerializedSignal()` holds only the `base` signal. */
 export class SignalSerializer {
   static serialize({ di, serverMode, prefix, websocketPrefix }: SignalSerializerContext): SignalData {
     const serializedSignals = FetchSerializer.serializeRegistry(di.live).signal;
@@ -124,11 +117,6 @@ export class SignalSerializer {
     };
   }
 
-  /**
-   * `FetchSerializer` never populates `prefix`/`globalPrefix` (they are server-routing concerns), so a
-   * `{ globalPrefix: false }` endpoint is unreconstructable from the client payload alone. Read them off
-   * `ENDPOINT_META` instead of widening what ships to every client bundle.
-   */
   static #augmentAll(
     endpoints: Record<string, SerializedEndpoint>,
     endpointCls: EndpointCls,
@@ -157,7 +145,6 @@ export class SignalSerializer {
     return Object.fromEntries(Object.entries(endpoints).filter(([key]) => predicate(key)));
   }
 
-  /** The list/insight pair the resolver synthesizes per slice key — everything else on that class is CRUD. */
   static #sliceDerivedKeys(refName: string, sliceCls: SliceCls | undefined): Set<string> {
     const sliceMeta = (sliceCls?.[SLICE_META] ?? {}) as Record<string, SliceInfo>;
     return new Set(
@@ -215,7 +202,7 @@ export class SignalSerializer {
           method: node.type === "mutation" ? (info.signalOption.method ?? "POST") : transport === "http" ? "GET" : null,
           path:
             transport === "ws"
-              ? SignalSerializer.#joinPath(prefix, websocketPrefix)
+              ? ApiRouter.joinRoutePath(prefix, websocketPrefix)
               : SignalSerializer.#httpPath(key, info, defaultPrefix, prefix),
           guards: node.guards ?? [],
           ...(node.cache !== undefined ? { cache: node.cache } : {}),
@@ -226,34 +213,8 @@ export class SignalSerializer {
     });
   }
 
-  /** Mirrors `SignalResolver.resolveEndpoint` + `ApiRouter.applyGlobalPrefix` so paths match the real route table. */
   static #httpPath(key: string, info: EndpointInfo, defaultPrefix: string | undefined, apiPrefix: string): string {
-    const servicePrefix = SignalSerializer.#resolveServicePrefix(info.signalOption.prefix, defaultPrefix);
-    const localPath = `${servicePrefix}${info.getPath(key)}`;
-    if (info.signalOption.globalPrefix === false) return SignalSerializer.#normalizePath(localPath);
-    return SignalSerializer.#joinPath(apiPrefix, localPath);
-  }
-
-  static #resolveServicePrefix(prefix: false | string | undefined, defaultPrefix?: string): string {
-    if (prefix === false || prefix === "") return "";
-    const resolved = prefix ?? defaultPrefix;
-    if (!resolved) return "";
-    const trimmed = resolved.trim().replace(/^\/+|\/+$/g, "");
-    return trimmed ? `/${trimmed}` : "";
-  }
-
-  static #joinPath(prefix: string, path: string): string {
-    const normalizedPrefix = SignalSerializer.#normalizePath(prefix).replace(/\/$/, "");
-    const normalizedPath = SignalSerializer.#normalizePath(path);
-    if (normalizedPrefix === "/") return normalizedPath;
-    if (normalizedPath === "/") return normalizedPrefix;
-    return `${normalizedPrefix}${normalizedPath}`;
-  }
-
-  static #normalizePath(path: string): string {
-    const trimmed = path.trim();
-    if (!trimmed || trimmed === "/") return "/";
-    return `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
+    return ApiRouter.applyGlobalPrefix(apiPrefix, info.getRoutePath(key, defaultPrefix), info.signalOption);
   }
 
   static #serializeInternals(
@@ -270,7 +231,6 @@ export class SignalSerializer {
 
   static #serializeInternal(key: string, info: InternalInfo, serverMode: "federation" | "batch" | "all"): InternalNode {
     const option = info.signalOption;
-
     const schedulable = info.type !== "resolveField";
     const skip = schedulable ? SignalResolver.getScheduleSkipReason(info, serverMode) : null;
     return {