akanjs 2.0.6 → 2.0.7

package/devkit/capacitorApp.ts

@@ -15,37 +15,53 @@ interface RunConfig {
   regenerate?: boolean;
 }
 
+interface PrepareConfig extends RunConfig {}
+
 export class CapacitorApp {
   project: MobileProject & { ios: IosProject; android: AndroidProject };
   iosTargetName = "App";
   readonly targetRoot: string;
+  readonly targetRootPath: string;
+  readonly targetWebRoot: string;
+  readonly targetAssetRoot: string;
+  readonly iosRootPath = "ios";
+  readonly iosProjectPath = "ios/App";
+  readonly androidRootPath = "android";
   constructor(
     private readonly app: AppExecutor,
     readonly target: AkanMobileTargetConfig,
   ) {
-    this.targetRoot = path.join(this.app.cwdPath, "mobile", this.target.name);
-    this.project = new MobileProject(this.targetRoot, {
-      android: { path: "android" },
-      ios: { path: "ios/App" },
+    this.targetRootPath = path.posix.join("mobile", this.target.name);
+    this.targetRoot = path.join(this.app.cwdPath, this.targetRootPath);
+    this.targetWebRoot = path.join(this.targetRoot, "www");
+    this.targetAssetRoot = path.join(this.targetRoot, "assets");
+    this.project = new MobileProject(this.app.cwdPath, {
+      android: { path: this.androidRootPath },
+      ios: { path: this.iosProjectPath },
     }) as MobileProject & { ios: IosProject; android: AndroidProject };
   }
-  async init({ platform, regenerate = false }: { platform?: "ios" | "android"; regenerate?: boolean } = {}) {
+  async init({
+    platform,
+    operation = "release",
+    env = "debug",
+    regenerate = false,
+  }: { platform?: "ios" | "android" } & Partial<PrepareConfig> = {}) {
     await mkdir(this.targetRoot, { recursive: true });
     await this.#writeCapacitorConfig();
     if (regenerate) {
       if (!platform || platform === "ios")
-        await rm(path.join(this.targetRoot, "ios"), { recursive: true, force: true });
+        await rm(path.join(this.app.cwdPath, this.iosRootPath), { recursive: true, force: true });
       if (!platform || platform === "android")
-        await rm(path.join(this.targetRoot, "android"), { recursive: true, force: true });
+        await rm(path.join(this.app.cwdPath, this.androidRootPath), { recursive: true, force: true });
     }
     const project = this.project as MobileProject;
     await this.project.load();
     if ((!platform || platform === "android") && !project.android) {
-      await this.#spawn("npx", ["cap", "add", "android"]);
+      await this.#spawnMobile("npx", ["cap", "add", "android"], { operation, env });
       await this.project.load();
     }
     if ((!platform || platform === "ios") && !project.ios) {
-      await this.#spawn("npx", ["cap", "add", "ios"]);
+      await this.#spawnMobile("npx", ["cap", "add", "ios"], { operation, env });
       await this.project.load();
     }
     return this;
@@ -53,58 +69,54 @@ export class CapacitorApp {
   async save() {
     await this.project.commit();
   }
-  async #prepareIos({ regenerate = false }: { regenerate?: boolean } = {}) {
-    await this.init({ platform: "ios", regenerate });
+  async #prepareIos({ operation, env, regenerate = false }: PrepareConfig) {
+    await this.init({ platform: "ios", operation, env, regenerate });
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("ios");
     await this.#applyIosMetadata();
     await this.#applyPermissions();
     await this.#applyLinks();
     await this.project.commit();
-    await this.#generateAssets();
+    await this.#generateAssets({ operation, env });
     this.app.verbose(`syncing iOS`);
-    await this.#spawn("npx", ["cap", "sync", "ios"]);
+    await this.#spawnMobile("npx", ["cap", "sync", "ios"], { operation, env });
     this.app.verbose(`sync completed.`);
   }
-  async buildIos(options: { regenerate?: boolean } = {}) {
+  async buildIos({ env = "debug", regenerate = false }: { env?: RunConfig["env"]; regenerate?: boolean } = {}) {
     await this.prepareWww();
-    await this.#prepareIos(options);
-    await this.#spawn("npx", ["cap", "build", "ios"], { stdio: "inherit" });
+    await this.#prepareIos({ operation: "release", env, regenerate });
+    await this.#spawnMobile("npx", ["cap", "build", "ios"], { operation: "release", env }, { stdio: "inherit" });
     this.app.verbose(`build completed iOS.`);
     return;
   }
   async syncIos() {
-    await this.#spawn("npx", ["cap", "sync", "ios"]);
+    await this.#spawnMobile("npx", ["cap", "sync", "ios"], { operation: "local", env: "local" });
   }
   async openIos() {
-    await this.#spawn("npx", ["cap", "open", "ios"]);
+    await this.#spawnMobile("npx", ["cap", "open", "ios"], { operation: "local", env: "local" });
   }
   async runIos({ operation, env, regenerate = false }: RunConfig) {
     if (operation === "release") await this.prepareWww();
-    await this.#prepareIos({ regenerate });
+    await this.#prepareIos({ operation, env, regenerate });
     const args = ["cap", "run", "ios"];
-    if (operation !== "release") args.push("--live-reload");
-    await this.#spawn("npx", args, {
-      env: this.#commandEnv(operation, env),
-      stdio: "inherit",
-    });
+    await this.#spawnMobile("npx", args, { operation, env }, { stdio: "inherit" });
   }
 
-  async #prepareAndroid({ regenerate = false }: { regenerate?: boolean } = {}) {
-    await this.init({ platform: "android", regenerate });
+  async #prepareAndroid({ operation, env, regenerate = false }: PrepareConfig) {
+    await this.init({ platform: "android", operation, env, regenerate });
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("android");
     await this.#applyAndroidMetadata();
     await this.#applyPermissions();
     await this.#applyLinks();
     await this.project.commit();
-    await this.#generateAssets();
-    await this.#spawn("npx", ["cap", "sync", "android"]);
+    await this.#generateAssets({ operation, env });
+    await this.#spawnMobile("npx", ["cap", "sync", "android"], { operation, env });
   }
 
   async #updateAndroidBuildTypes() {
 
-    const appGradle = await FileEditor.create(`${this.targetRoot}/android/app/build.gradle`);
+    const appGradle = await FileEditor.create(path.join(this.app.cwdPath, this.androidRootPath, "app/build.gradle"));
     const buildTypesBlock = `
       debug {
         applicationIdSuffix ".debug"
@@ -139,9 +151,12 @@ export class CapacitorApp {
     }
     await appGradle.save();
   }
-  async buildAndroid(assembleType: "apk" | "aab", options: { regenerate?: boolean } = {}) {
+  async buildAndroid(
+    assembleType: "apk" | "aab",
+    { env = "debug", regenerate = false }: { env?: RunConfig["env"]; regenerate?: boolean } = {},
+  ) {
     await this.prepareWww();
-    await this.#prepareAndroid(options);
+    await this.#prepareAndroid({ operation: "release", env, regenerate });
     await this.#updateAndroidBuildTypes();
     
     const isWindows = process.platform === "win32";
@@ -149,45 +164,44 @@ export class CapacitorApp {
 
     await this.app.spawn(gradleCommand, [assembleType === "apk" ? "assembleRelease" : "bundleRelease"], {
       stdio: "inherit",
-      cwd: `${this.targetRoot}/android`,
+      cwd: path.join(this.app.cwdPath, this.androidRootPath),
+      env: this.#commandEnv("release", env),
     });
   }
   async openAndroid() {
-    await this.#spawn("npx", ["cap", "open", "android"]);
+    await this.#spawnMobile("npx", ["cap", "open", "android"], { operation: "local", env: "local" });
   }
   async syncAndroid(options: { regenerate?: boolean } = {}) {
     await this.prepareWww();
-    await this.#prepareAndroid(options);
+    await this.#prepareAndroid({ operation: "release", env: "debug", ...options });
     this.app.log(`Sync Android Completed.`);
   }
   async runAndroid({ operation, env, regenerate = false }: RunConfig) {
     if (operation === "release") await this.prepareWww();
-    await this.#prepareAndroid({ regenerate });
+    await this.#prepareAndroid({ operation, env, regenerate });
     this.app.logger.info(`Running Android in ${operation} mode on ${env} env`);
     const args = ["cap", "run", "android"];
-    if (operation !== "release") args.push("--live-reload");
-    await this.#spawn("npx", args, {
-      env: this.#commandEnv(operation, env),
-      stdio: "inherit",
-    });
+    await this.#spawnMobile("npx", args, { operation, env }, { stdio: "inherit" });
   }
 
   async releaseIos() {
     await this.prepareWww();
-    await this.#prepareIos();
+    await this.#prepareIos({ operation: "release", env: "main" });
   }
   async releaseAndroid() {
     await this.prepareWww();
-    await this.#prepareAndroid();
+    await this.#prepareAndroid({ operation: "release", env: "main" });
   }
   async prepareWww() {
     const htmlSource = path.join(this.app.dist.cwdPath, "csr", targetHtmlFilename(this.target));
     if (!(await Bun.file(htmlSource).exists()))
       throw new Error(`CSR html for mobile target '${this.target.name}' not found: ${htmlSource}`);
-    const wwwDir = path.join(this.targetRoot, "www");
-    await rm(wwwDir, { recursive: true, force: true });
-    await mkdir(wwwDir, { recursive: true });
-    await Bun.write(path.join(wwwDir, "index.html"), this.#injectMobileTargetMeta(await Bun.file(htmlSource).text()));
+    await rm(this.targetWebRoot, { recursive: true, force: true });
+    await mkdir(this.targetWebRoot, { recursive: true });
+    await Bun.write(
+      path.join(this.targetWebRoot, "index.html"),
+      this.#injectMobileTargetMeta(await Bun.file(htmlSource).text()),
+    );
   }
   #injectMobileTargetMeta(html: string) {
     const basePath = this.target.basePath?.replace(/^\/+|\/+$/g, "") ?? "";
@@ -198,45 +212,75 @@ export class CapacitorApp {
   async #writeCapacitorConfig() {
     await mkdir(this.targetRoot, { recursive: true });
     const appInfoPath = path
-      .relative(this.targetRoot, path.join(this.app.cwdPath, "akan.app.json"))
+      .relative(this.app.cwdPath, path.join(this.app.cwdPath, "akan.app.json"))
       .split(path.sep)
       .join("/");
     const baseConfigPath = path
-      .relative(this.targetRoot, path.join(this.app.workspace.cwdPath, "pkgs/akanjs/devkit/capacitor.base.config"))
+      .relative(this.app.cwdPath, path.join(this.app.workspace.cwdPath, "pkgs/akanjs/devkit/capacitor.base.config"))
       .split(path.sep)
       .join("/");
-    const content = `import { withBase } from "${baseConfigPath.startsWith(".") ? baseConfigPath : `./${baseConfigPath}`}";
-import appInfo from "${appInfoPath}";
+    const content = `import type { AppScanResult } from "akanjs/devkit";
+import { withBase } from "${baseConfigPath.startsWith(".") ? baseConfigPath : `./${baseConfigPath}`}";
+import appInfo from "${appInfoPath.startsWith(".") ? appInfoPath : `./${appInfoPath}`}";
 
-export default withBase((config) => config, appInfo, "${this.target.name}");
+export default withBase(
+  (config, target) => ({
+    ...config,
+    webDir: \`mobile/\${target.name}/www\`,
+    android: {
+      ...config.android,
+      path: "android",
+    },
+    ios: {
+      ...config.ios,
+      path: "ios",
+    },
+  }),
+  appInfo as AppScanResult,
+);
 `;
-    await Bun.write(path.join(this.targetRoot, "capacitor.config.ts"), content);
+    await Bun.write(path.join(this.app.cwdPath, "capacitor.config.ts"), content);
   }
   async #prepareTargetAssets() {
     if (!this.target.assets) return;
-    const assetsDir = path.join(this.targetRoot, "assets");
-    await mkdir(assetsDir, { recursive: true });
+    await mkdir(this.targetAssetRoot, { recursive: true });
     if (this.target.assets.icon)
-      await cp(path.join(this.app.cwdPath, this.target.assets.icon), path.join(assetsDir, "icon.png"), { force: true });
+      await cp(path.join(this.app.cwdPath, this.target.assets.icon), path.join(this.targetAssetRoot, "icon.png"), {
+        force: true,
+      });
     if (this.target.assets.splash)
-      await cp(path.join(this.app.cwdPath, this.target.assets.splash), path.join(assetsDir, "splash.png"), {
+      await cp(path.join(this.app.cwdPath, this.target.assets.splash), path.join(this.targetAssetRoot, "splash.png"), {
         force: true,
       });
   }
   async #prepareExternalFiles(platform: "ios" | "android") {
     const files = this.target.files?.[platform];
     if (!files) return;
+    const platformRoot = path.join(this.app.cwdPath, platform === "ios" ? this.iosRootPath : this.androidRootPath);
     await Promise.all(
       Object.entries(files).map(async ([to, from]) => {
-        const targetPath = path.join(this.targetRoot, platform, to);
+        const targetPath = path.join(platformRoot, to);
         await mkdir(path.dirname(targetPath), { recursive: true });
         await cp(path.join(this.app.cwdPath, from), targetPath, { force: true });
       }),
     );
   }
-  async #generateAssets() {
+  async #generateAssets({ operation, env }: Pick<RunConfig, "operation" | "env">) {
     if (!this.target.assets) return;
-    await this.#spawn("npx", ["@capacitor/assets", "generate"]);
+    await this.#spawnMobile(
+      "npx",
+      [
+        "@capacitor/assets",
+        "generate",
+        "--assetPath",
+        path.posix.join(this.targetRootPath, "assets"),
+        "--iosProject",
+        this.iosProjectPath,
+        "--androidProject",
+        this.androidRootPath,
+      ],
+      { operation, env },
+    );
   }
   async #applyIosMetadata() {
     this.project.ios.setBundleId("App", "Debug", this.target.appId);
@@ -291,16 +335,26 @@ export default withBase((config) => config, appInfo, "${this.target.name}");
     }
   }
   #commandEnv(operation: "local" | "release", env: "local" | "debug" | "develop" | "main") {
-    return {
-      ...process.env,
+    return this.app.getCommandEnv({
       APP_OPERATION_MODE: operation,
-      AKAN_PUBLIC_OPERATION_MODE: operation,
+      AKAN_PUBLIC_OPERATION_MODE: env === "local" ? "local" : "cloud",
       AKAN_PUBLIC_ENV: env,
       AKAN_MOBILE_TARGET: this.target.name,
-    };
+    });
   }
   async #spawn(command: string, args: string[] = [], options: Parameters<AppExecutor["spawn"]>[2] = {}) {
-    return await this.app.spawn(command, args, { cwd: this.targetRoot, ...options });
+    return await this.app.spawn(command, args, { cwd: this.app.cwdPath, ...options });
+  }
+  async #spawnMobile(
+    command: string,
+    args: string[] = [],
+    { operation, env }: Pick<RunConfig, "operation" | "env">,
+    options: Parameters<AppExecutor["spawn"]>[2] = {},
+  ) {
+    return await this.#spawn(command, args, {
+      ...options,
+      env: { ...this.#commandEnv(operation, env), ...options.env },
+    });
   }
   async addCamera() {
     await this.#setPermissionInIos({

package/devkit/mobile/mobileTarget.ts

@@ -36,9 +36,10 @@ const resolveMobileTargetByBasePath = (
   const [template] = targets;
   if (!template) return undefined;
   return {
-    name: template.name,
+    name: normalizedBasePath,
     config: {
       ...template.config,
+      name: normalizedBasePath,
       basePath: normalizedBasePath,
     },
   };

package/devkit/scanInfo.ts

@@ -59,6 +59,7 @@ const appRootAllowedDirs = new Set([
   "env",
   "ios",
   "lib",
+  "mobile",
   "page",
   "private",
   "public",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "sourceType": "module",
   "type": "module",
   "bin": {

package/server/akanApp.ts

@@ -2,6 +2,7 @@ import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
+import { isTraceEnabled } from "akanjs/signal";
 import type { BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
@@ -85,6 +86,7 @@ export class AkanApp {
   readonly #builderReqMap = new Map<number, { childIdx: number; childLocalId: number }>();
   #server: Bun.Server<GatewayWsData> | null = null;
   #rrIdx = 0;
+  #federationChildCache: ChildState[] | null = null;
   #snapshotTimer: Timer | null = null;
   #healthTimer: Timer | null = null;
   #metricsTimer: Timer | null = null;
@@ -93,6 +95,9 @@ export class AkanApp {
   readonly #childOutputBuffers = new Map<string, string>();
   static readonly #ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
   #gatewayMetrics: AkanMetricsReport = {};
+  #proxyHopCount = 0;
+  #proxyHopSumMs = 0;
+  #proxyHopMaxMs = 0;
   #resolveStopped: (() => void) | null = null;
   #exitAfterStop = false;
   #stopping = false;
@@ -248,6 +253,7 @@ export class AkanApp {
       lastRestartAt: previous?.lastRestartAt,
       lastRestartReason: previous?.lastRestartReason,
     });
+    this.#invalidateFederationChildCache();
     this.#pipeOutput(idx, role, proc.stdout, "stdout");
     this.#pipeOutput(idx, role, proc.stderr, "stderr");
     proc.exited.then((code) => this.#handleChildExit(idx, proc, code));
@@ -258,6 +264,7 @@ export class AkanApp {
     if (!child || child.proc !== proc) return;
     child.status = "exited";
     child.lastExitCode = code;
+    this.#invalidateFederationChildCache();
     this.#removeChildRooms(idx);
     if (this.#stopping) return;
     void this.#scheduleChildRestart(child, proc, `exit:${code ?? "unknown"}`);
@@ -276,6 +283,7 @@ export class AkanApp {
     child.status = reason === "health-timeout" ? "unhealthy" : "exited";
     child.upstream = undefined;
     child.healthPath = undefined;
+    this.#invalidateFederationChildCache();
     child.lastRestartReason = reason;
     child.lastRestartAt = Date.now();
     this.#removeChildRooms(child.idx);
@@ -403,6 +411,7 @@ export class AkanApp {
     const url = new URL(req.url);
     if (url.pathname === "/_akan/app/health") return Response.json(this.#getHealthStatus());
     if (url.pathname === "/_akan/app/metrics") return Response.json(this.#getMetricsStatus());
+    if (url.pathname === "/_akan/bench/ping") return new Response("ok");
     if (this.#isWebSocketPath(url.pathname)) return this.#upgradeWebSocket(req, server);
     const assetResponse = await this.#serveImmutableArtifact(req, url);
     if (assetResponse) return assetResponse;
@@ -526,6 +535,13 @@ export class AkanApp {
       rooms: this.#roomChildren.size,
       sockets: this.#socketRooms.size,
       gateway: this.#gatewayMetrics,
+      proxyHop: this.#proxyHopCount
+        ? {
+            count: this.#proxyHopCount,
+            meanMs: Math.round((this.#proxyHopSumMs / this.#proxyHopCount) * 1000) / 1000,
+            maxMs: Math.round(this.#proxyHopMaxMs * 1000) / 1000,
+          }
+        : null,
       children: [...this.#children.values()].map((child) => ({
         idx: child.idx,
         role: child.role,
@@ -551,6 +567,8 @@ export class AkanApp {
     const headers = this.#makeProxyHeaders(req, child.idx);
     child.metrics.activeRequests = (child.metrics.activeRequests ?? 0) + 1;
     child.metrics.totalRequests = (child.metrics.totalRequests ?? 0) + 1;
+    const traced = isTraceEnabled();
+    const hopStart = traced ? performance.now() : 0;
     try {
       const upstreamRes = await fetch(upstreamUrl, {
         unix: child.upstream.socketPath,
@@ -563,9 +581,20 @@ export class AkanApp {
       return this.#proxyResponse(upstreamRes);
     } finally {
       child.metrics.activeRequests = Math.max(0, (child.metrics.activeRequests ?? 1) - 1);
+      if (traced) this.#recordProxyHop(performance.now() - hopStart);
     }
   }
 
+  /**
+   * Gateway-observed upstream round-trip time. The pure proxy overhead is this value
+   * minus the child handler time captured in the per-request trace.
+   */
+  #recordProxyHop(durationMs: number) {
+    this.#proxyHopCount += 1;
+    this.#proxyHopSumMs += durationMs;
+    this.#proxyHopMaxMs = Math.max(this.#proxyHopMaxMs, durationMs);
+  }
+
   #proxyResponse(upstreamRes: Response): Response {
     const headers = new Headers(upstreamRes.headers);
 
@@ -652,27 +681,36 @@ export class AkanApp {
   #makeProxyHeaders(req: Request, childIdx: number) {
     const headers = new Headers(req.headers);
     for (const key of AkanApp.#hopByHopHeaders) headers.delete(key);
-    const url = new URL(req.url);
     const forwardedFor = headers.get("x-forwarded-for");
     const clientAddress = headers.get("x-real-ip") ?? "127.0.0.1";
+    const host = headers.get("host");
     headers.set("x-forwarded-for", forwardedFor ? `${forwardedFor}, ${clientAddress}` : clientAddress);
-    headers.set("x-forwarded-host", headers.get("host") ?? url.host);
-    headers.set("x-forwarded-proto", url.protocol.replace(":", ""));
+    headers.set("x-forwarded-host", host ?? new URL(req.url).host);
+    headers.set("x-forwarded-proto", req.url.startsWith("https:") ? "https" : "http");
     headers.set("x-akan-child-idx", String(childIdx));
-    headers.set("x-request-id", headers.get("x-request-id") ?? crypto.randomUUID());
+    if (!headers.has("x-request-id") && process.env.AKAN_BENCH_SKIP_REQUEST_ID !== "1") {
+      headers.set("x-request-id", crypto.randomUUID());
+    }
     headers.set("host", "akan-child");
     return headers;
   }
 
+  #invalidateFederationChildCache() {
+    this.#federationChildCache = null;
+  }
+
   #pickFederationChild() {
-    const candidates = [...this.#children.values()].filter(
-      (child) =>
-        (child.role === "federation" || child.role === "all") &&
-        child.ready &&
-        child.status !== "unhealthy" &&
-        child.status !== "exited" &&
-        !child.proc.killed,
-    );
+    const candidates =
+      this.#federationChildCache ??
+      [...this.#children.values()].filter(
+        (child) =>
+          (child.role === "federation" || child.role === "all") &&
+          child.ready &&
+          child.status !== "unhealthy" &&
+          child.status !== "exited" &&
+          !child.proc.killed,
+      );
+    this.#federationChildCache = candidates;
     if (candidates.length === 0) return null;
     const child = candidates[this.#rrIdx % candidates.length];
     this.#rrIdx++;
@@ -761,6 +799,7 @@ export class AkanApp {
     child.lastPongAt = Date.now();
     child.restartAttempts = 0;
     child.restartPending = false;
+    this.#invalidateFederationChildCache();
     if ([...this.#children.values()].every((item) => item.ready)) {
       process.send?.({ type: "backend-ready", pid: process.pid } satisfies AkanIpcMessage);
       this.logger.verbose(`All ${this.#children.size} child process(es) are ready`);
@@ -772,6 +811,7 @@ export class AkanApp {
     if (!child) return;
     child.status = "healthy";
     child.lastPongAt = Date.now();
+    this.#invalidateFederationChildCache();
   }
 
   #deliverPubsub(originIdx: number, message: Extract<AkanIpcMessage, { type: "pubsub.publish" }>) {
@@ -903,6 +943,7 @@ export class AkanApp {
       if (child.proc.killed || child.status === "exited") continue;
       if (child.lastPongAt && now - child.lastPongAt > 5_000) {
         child.status = "unhealthy";
+        this.#invalidateFederationChildCache();
         void this.#scheduleChildRestart(child, child.proc, "health-timeout");
         return;
       }

package/server/processMetricsCollector.ts

@@ -1,4 +1,5 @@
 import type { AkanMetricsReport } from "akanjs/service";
+import { getTraceSnapshot, isTraceEnabled } from "akanjs/signal";
 
 type BunJscHeapStats = {
   heapSize?: number;
@@ -8,19 +9,83 @@ type BunJscHeapStats = {
   protectedObjectCount?: number;
 };
 
+/**
+ * Samples event-loop scheduling delay by measuring how late a fixed-interval timer
+ * actually fires. The sample window is summarized and reset on each metrics report,
+ * so values reflect recent load rather than process lifetime.
+ */
+class EventLoopLagMonitor {
+  static readonly #maxSamples = 600;
+  #timer: ReturnType<typeof setInterval> | null = null;
+  #intervalMs = 500;
+  #lastTickAt = 0;
+  #samples: number[] = [];
+  #maxMs = 0;
+
+  start(intervalMs = 500): void {
+    if (this.#timer) return;
+    this.#intervalMs = intervalMs;
+    this.#lastTickAt = performance.now();
+    this.#timer = setInterval(() => {
+      const now = performance.now();
+      const lag = Math.max(0, now - this.#lastTickAt - this.#intervalMs);
+      this.#lastTickAt = now;
+      this.#maxMs = Math.max(this.#maxMs, lag);
+      if (this.#samples.length < EventLoopLagMonitor.#maxSamples) this.#samples.push(lag);
+      else this.#samples[Math.floor(Math.random() * EventLoopLagMonitor.#maxSamples)] = lag;
+    }, intervalMs);
+    
+    (this.#timer as { unref?: () => void }).unref?.();
+  }
+
+  /** Summarize the current window and reset it. */
+  snapshotAndReset(): { meanMs: number; p99Ms: number; maxMs: number } | null {
+    if (this.#samples.length === 0) return null;
+    const sorted = [...this.#samples].sort((a, b) => a - b);
+    const sum = sorted.reduce((acc, v) => acc + v, 0);
+    const p99Index = Math.min(sorted.length - 1, Math.floor(0.99 * sorted.length));
+    const result = {
+      meanMs: round(sum / sorted.length),
+      p99Ms: round(sorted[p99Index] ?? 0),
+      maxMs: round(this.#maxMs),
+    };
+    this.#samples = [];
+    this.#maxMs = 0;
+    return result;
+  }
+}
+
+const round = (value: number, digits = 3): number => {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+};
+
 export class ProcessMetricsCollector {
   static readonly #defaultMemoryLogIntervalMs = 60_000;
+  static readonly #lagMonitor = new EventLoopLagMonitor();
 
   static parseMemoryLogIntervalMs(value = process.env.AKAN_MEMORY_LOG_INTERVAL_MS) {
     const parsed = Number.parseInt(value ?? "", 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : ProcessMetricsCollector.#defaultMemoryLogIntervalMs;
   }
 
+  /** Begin sampling event-loop lag. Idempotent; safe to call from each server role. */
+  static startEventLoopLagMonitor(intervalMs = 500): void {
+    ProcessMetricsCollector.#lagMonitor.start(intervalMs);
+  }
+
   static async collect(extra: AkanMetricsReport = {}): Promise<AkanMetricsReport> {
-    if (process.env.AKAN_MEMORY_GC_ON_REPORT === "1") Bun.gc(true);
+    ProcessMetricsCollector.#lagMonitor.start();
+    let gcDurationMs: number | undefined;
+    if (process.env.AKAN_MEMORY_GC_ON_REPORT === "1") {
+      const gcStart = performance.now();
+      Bun.gc(true);
+      gcDurationMs = round(performance.now() - gcStart);
+    }
     const memory = process.memoryUsage();
     const resourceUsage = process.resourceUsage?.();
     const jsc = await ProcessMetricsCollector.#collectJscHeapStats();
+    const lag = ProcessMetricsCollector.#lagMonitor.snapshotAndReset();
     return {
       pid: process.pid,
       reportedAt: Date.now(),
@@ -45,6 +110,15 @@ export class ProcessMetricsCollector {
             jscProtectedObjectCount: jsc.protectedObjectCount,
           }
         : {}),
+      ...(lag
+        ? {
+            eventLoopLagMeanMs: lag.meanMs,
+            eventLoopLagP99Ms: lag.p99Ms,
+            eventLoopLagMaxMs: lag.maxMs,
+          }
+        : {}),
+      ...(gcDurationMs !== undefined ? { gcDurationMs } : {}),
+      ...(isTraceEnabled() ? { trace: getTraceSnapshot() } : {}),
       ...extra,
     };
   }
@@ -64,6 +138,10 @@ export class ProcessMetricsCollector {
       ...(metrics.jscHeapSizeBytes !== undefined
         ? [`jscHeap=${ProcessMetricsCollector.formatBytes(metrics.jscHeapSizeBytes)}`]
         : []),
+      ...(metrics.eventLoopLagMeanMs !== undefined
+        ? [`elLag=${metrics.eventLoopLagMeanMs}/${metrics.eventLoopLagP99Ms ?? 0}/${metrics.eventLoopLagMaxMs ?? 0}ms`]
+        : []),
+      ...(metrics.gcDurationMs !== undefined ? [`gc=${metrics.gcDurationMs}ms`] : []),
     ].join(" ");
   }