akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/server/cachePolicy.ts

@@ -83,16 +83,6 @@ export function resolveAutoRouteCacheTtl(input: {
   return normalizeRouteCacheTtl(input.ttl, input.defaultTtl ?? DEFAULT_ROUTE_CACHE_TTL_SECONDS);
 }
 
-export function combineMinRevalidate(...values: Array<number | false | null | undefined>): number | false | undefined {
-  let out: number | undefined;
-  for (const value of values) {
-    if (value === undefined || value === null) continue;
-    if (value === false) return false;
-    out = out === undefined ? value : Math.min(out, value);
-  }
-  return out;
-}
-
 export function getClientFacingOrigin(request: Request, url = new URL(request.url)): string {
   return originFromRequest(request.headers, url);
 }
@@ -105,6 +95,9 @@ export function isPublicRouteCacheableRequest(request: Request): boolean {
   return [...parseCookieHeader(cookie).keys()].every((name) => name === "theme");
 }
 
+const isAtOrUnder = (value: string, prefix: string) =>
+  value === prefix || value.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`);
+
 export function isRouteCachePathAllowed(
   pathname: string,
   options: { allow?: string | null; deny?: string | null; defaultAllow?: boolean } = {},
@@ -115,9 +108,7 @@ export function isRouteCachePathAllowed(
       .map((prefix) => prefix.trim())
       .filter(Boolean);
     if (prefixes.length === 0) return false;
-    return prefixes.some(
-      (prefix) => pathname === prefix || pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`),
-    );
+    return prefixes.some((prefix) => isAtOrUnder(pathname, prefix));
   };
   if (matches(options.deny)) return false;
   const allow = options.allow ?? "";
@@ -165,10 +156,6 @@ export function resolvePublicRouteCacheEntryDecision(input: PublicRouteCacheEntr
   return { entry: createRouteCacheEntry({ request: input.request, url: input.url, theme: input.theme, ttl }) };
 }
 
-export function resolvePublicRouteCacheEntry(input: PublicRouteCacheEntryInput): RouteCacheEntry | null {
-  return resolvePublicRouteCacheEntryDecision(input).entry;
-}
-
 export function resolveRouteCacheStoreTtl(baseTtl: number, state: RouteCacheRenderState): number | null {
   if (!state.cacheable || state.revalidate === false) return null;
   if (typeof state.revalidate !== "number") return baseTtl;
@@ -185,7 +172,7 @@ export function shouldStoreRouteCache(input: {
   const dynamicUsage = input.dynamicUsage ? { ...input.dynamicUsage } : undefined;
   const routeId = input.policy?.routeId;
   const tags = input.policy ? [...input.policy.tags] : undefined;
-  const revalidate = combineMinRevalidate(input.policy?.revalidate);
+  const revalidate = input.policy?.revalidate;
   if (input.renderControlType) {
     const reason =
       input.renderControlType === "redirect" && input.lateRedirect
@@ -215,10 +202,7 @@ export function shouldInvalidateRouteCacheEntry(
       if (!path) return false;
       const normalized = path.startsWith("/") ? path : `/${path}`;
       return (
-        metadata.pathname === normalized ||
-        metadata.pathname.startsWith(normalized.endsWith("/") ? normalized : `${normalized}/`) ||
-        metadata.routeId === normalized ||
-        Boolean(metadata.routeId?.startsWith(normalized.endsWith("/") ? normalized : `${normalized}/`))
+        isAtOrUnder(metadata.pathname, normalized) || (!!metadata.routeId && isAtOrUnder(metadata.routeId, normalized))
       );
     });
   }
@@ -226,22 +210,13 @@ export function shouldInvalidateRouteCacheEntry(
 }
 
 export interface LruTtlCacheOptions<T> {
-  /**
-   * Measures one entry's payload. Entry count alone says nothing about a cache whose entries span
-   * three orders of magnitude, and a byte ceiling needs a running total to enforce. The default
-   * reports 0 rather than guessing, so `byteSize` stays honest about not knowing.
-   */
+  /** Defaults to reporting 0 rather than guessing, so `byteSize` stays honest about not knowing. */
   sizeOf?: (value: T) => number;
   /** Total payload ceiling. 0 leaves the cache bounded only by `maxEntries`. */
   maxBytes?: number;
   /** An entry over this is not stored at all, rather than evicting everything else to fit it. */
   maxEntryBytes?: number;
-  /**
-   * Cadence of the idle sweep. Without one a filled cache never shrinks: an entry is dropped only
-   * when its own key is fetched after expiry or when a write evicts it, so a pod that stops
-   * serving holds its peak forever — measured at 100 entries / 21.4 MiB still resident 310s after
-   * the last request, with a 30s TTL. 0 disables it.
-   */
+  /** Idle sweep cadence; without it a cache nobody reads or writes never releases expired entries. 0 disables it. */
   sweepIntervalMs?: number;
 }
 
@@ -288,7 +263,6 @@ export class LruTtlCache<T> {
     return entry.value;
   }
 
-  /** Returns whether the entry was stored; a payload over `maxEntryBytes` is rejected. */
   set(key: string, value: T, ttlSeconds: number): boolean {
     this.#remove(key);
     const byteLength = LruTtlCache.#measure(this.#sizeOf, value);
@@ -306,12 +280,6 @@ export class LruTtlCache<T> {
     return true;
   }
 
-  /**
-   * Drops every expired entry. Deliberately a full scan rather than a walk from the oldest that
-   * stops at the first live entry: insertion order is *LRU* order because `get` reinserts, and TTLs
-   * differ per entry, so expiry is not monotonic in map order and an early break would leave
-   * expired entries behind. The map is bounded by `maxEntries`, so the scan is cheap.
-   */
   sweepExpired(now = Date.now()): number {
     let removed = 0;
     for (const [key, entry] of this.#entries) {
@@ -322,7 +290,6 @@ export class LruTtlCache<T> {
     return removed;
   }
 
-  /** Stops the idle sweep. The cache stays usable; only the timer goes away. */
   dispose(): void {
     if (!this.#sweepTimer) return;
     clearInterval(this.#sweepTimer);
@@ -349,8 +316,7 @@ export class LruTtlCache<T> {
   }
 
   static parseByteCeiling(value: string | undefined | null, fallback = 0): number {
-    const parsed = Number.parseInt(value ?? "", 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+    return parsePositiveInt(value) ?? fallback;
   }
 
   #remove(key: string): boolean {
@@ -363,7 +329,7 @@ export class LruTtlCache<T> {
 
   #removeOldest(): boolean {
     const oldest = this.#entries.keys().next().value;
-    if (!oldest) return false;
+    if (oldest === undefined) return false;
     return this.#remove(oldest);
   }
 

package/server/console.ts

@@ -7,7 +7,7 @@ import { type AkanConsoleCommand, AkanConsoleSession } from "./consoleSession";
 import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
 import { LogControlUnavailableError, LogTailClient } from "./logging/logTailClient";
 
-export * from "./consoleEvaluator";
+export { evaluateAkanConsoleInput, isAkanConsoleInputComplete } from "./consoleSession";
 
 export interface AkanConsoleOptions {
   prompt?: string;
@@ -28,10 +28,7 @@ export const parseAkanConsoleQuery = (args: string): Record<string, string> => {
   return query;
 };
 
-/**
- * `.tail` and `.trace` attach to the *running* server's control socket — the console booted its own
- * `listen: false` server, whose logs are not the ones anybody is looking for.
- */
+/** Attaches to the running server's control socket, not the console's own `listen: false` server. */
 export const createAkanConsoleLogCommands = (
   appName: string,
   runtimeDir: string,
@@ -124,16 +121,16 @@ export interface AkanConsoleContext extends Record<string, unknown> {
   debug: () => ReturnType<AkanServer["inspectConsole"]>;
 }
 
-export const assertAkanConsoleAllowed = (
-  env: Pick<BaseEnv, "environment" | "operationMode"> = {
-    environment: (process.env.AKAN_PUBLIC_ENV ?? "debug") as BaseEnv["environment"],
-    operationMode: (process.env.AKAN_PUBLIC_OPERATION_MODE ?? "cloud") as BaseEnv["operationMode"],
-  },
-) => {
+export const assertAkanConsoleAllowed = (env: Partial<Pick<BaseEnv, "environment" | "operationMode">> = {}) => {
+  const environment = env.environment ?? ((process.env.AKAN_PUBLIC_ENV ?? "debug") as BaseEnv["environment"]);
+  const operationMode =
+    env.operationMode ??
+    ((process.env.AKAN_PUBLIC_OPERATION_MODE ??
+      (environment === "local" ? "local" : "cloud")) as BaseEnv["operationMode"]);
   const isProductionLike =
-    env.environment === "main" ||
-    env.operationMode === "cloud" ||
-    env.operationMode === "edge" ||
+    environment === "main" ||
+    operationMode === "cloud" ||
+    operationMode === "edge" ||
     process.env.NODE_ENV === "production";
   if (!isProductionLike || process.env.AKAN_CONSOLE === "1") return;
 
@@ -171,7 +168,7 @@ export const createAkanConsoleContext = (
   server: AkanServer,
   globals: Record<string, unknown> = {},
 ): AkanConsoleContext => {
-  const context = {
+  return {
     server,
     env: server.env,
     get: server.get.bind(server) as AkanServer["get"],
@@ -182,7 +179,6 @@ export const createAkanConsoleContext = (
     debug: () => server.inspectConsole(),
     ...globals,
   };
-  return context;
 };
 
 export const startAkanConsole = async (server: AkanServer, options: AkanConsoleOptions = {}) => {

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,15 +22,11 @@ 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. */
@@ -52,24 +42,12 @@ 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;
-};
-
-/**
- * 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 (!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 +59,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 {