akanjs 2.0.6 → 2.0.7

package/service/predefinedAdaptor/storage.adaptor.ts

@@ -16,6 +16,7 @@ export interface UploadRequest {
   meta?: { [key: string]: string };
   rename?: string;
   host?: string;
+  access?: "public" | "private";
 }
 export interface CopyRequest {
   bucket: string;
@@ -29,6 +30,7 @@ export interface UploadFromStreamRequest {
   body: ReadableStream;
   mimetype: string;
   root?: string;
+  access?: "public" | "private";
   updateProgress: (progress: { loaded?: number; total?: number; part?: number }) => void;
   uploadSuccess: (url: string) => void;
 }
@@ -47,17 +49,22 @@ export interface StorageAdaptor {
   saveData(request: DownloadRequest): Promise<LocalFilePath>;
   copyData(request: CopyRequest): Promise<string>;
   deleteData(url: string): Promise<boolean>;
+  deleteDataByPath(path: string): Promise<boolean>;
 }
 
 export interface BlobStorageOptions extends BaseEnv {
-  blobStorage?: { baseDir?: string; urlPrefix?: string };
+  blobStorage?: { baseDir?: string; privateBaseDir?: string; urlPrefix?: string };
 }
 
 export class BlobStorage
   extends adapt("blobStorage", ({ env }) => ({
     root: env(
       ({ appName, blobStorage = { baseDir: "local", urlPrefix: "/backend/localFile/getBlob" } }: BlobStorageOptions) =>
-        `${process.env.AKAN_WORKSPACE_ROOT ?? "."}/${blobStorage.baseDir}/${appName}/backend`,
+        `${process.env.AKAN_WORKSPACE_ROOT ?? "."}/${blobStorage.baseDir ?? "local"}/${appName}/backend`,
+    ),
+    privateRoot: env(
+      ({ appName, blobStorage = { privateBaseDir: "local" } }: BlobStorageOptions) =>
+        `${process.env.AKAN_WORKSPACE_ROOT ?? "."}/${blobStorage.privateBaseDir ?? "local"}/${appName}/server-private`,
     ),
     urlPrefix: env(
       ({ blobStorage = { urlPrefix: "/backend/localFile/getBlob" } }: BlobStorageOptions) => blobStorage.urlPrefix,
@@ -68,12 +75,15 @@ export class BlobStorage
   #localPathToUrl(path: string) {
     return `${this.urlPrefix}/${path}`;
   }
+  #resolveFilePath(path: string) {
+    return path.startsWith("private/") ? `${this.privateRoot}/${path}` : `${this.root}/${path}`;
+  }
   async readData(path: string): Promise<ReadableStream> {
-    const filePath = `${this.root}/${path}`;
+    const filePath = this.#resolveFilePath(path);
     return Bun.file(filePath).stream();
   }
   async readDataAsJson<T>(path: string) {
-    const filePath = `${this.root}/${path}`;
+    const filePath = this.#resolveFilePath(path);
     return Bun.file(filePath).json() as T;
   }
   async getDataList(prefix?: string) {
@@ -81,14 +91,21 @@ export class BlobStorage
     const paths = Array.from(new Bun.Glob("*").scanSync({ cwd: dir, onlyFiles: false }));
     return paths.map((path) => this.#localPathToUrl(path));
   }
-  async uploadDataFromLocal({ path, localPath, meta }: UploadRequest) {
-    const filePath = `${this.root}/${path}`;
+  async uploadDataFromLocal({ path, localPath, meta, access = "public" }: UploadRequest) {
+    const filePath = access === "private" ? `${this.privateRoot}/${path}` : `${this.root}/${path}`;
     await Bun.write(filePath, Bun.file(localPath));
     if (meta) await Bun.write(`${filePath}.meta`, JSON.stringify(meta));
     return this.#localPathToUrl(path);
   }
-  async uploadDataFromStream({ path, body, mimetype, updateProgress, uploadSuccess }: UploadFromStreamRequest) {
-    const filePath = `${this.root}/${path}`;
+  async uploadDataFromStream({
+    path,
+    body,
+    mimetype,
+    updateProgress,
+    uploadSuccess,
+    access = "public",
+  }: UploadFromStreamRequest) {
+    const filePath = access === "private" ? `${this.privateRoot}/${path}` : `${this.root}/${path}`;
     try {
       await Bun.write(filePath, new Response(body));
       uploadSuccess(this.#localPathToUrl(path));
@@ -106,12 +123,21 @@ export class BlobStorage
     await Bun.write(`${this.root}/${pastePath}`, Bun.file(`${this.root}/${copyPath}`));
     return pastePath;
   }
+  async deleteDataByPath(path: string) {
+    try {
+      await Bun.file(this.#resolveFilePath(path)).delete();
+      return true;
+    } catch (error) {
+      this.logger.error(error instanceof Error ? error.message : "Unknown error");
+      return false;
+    }
+  }
   async deleteData(url: string) {
     try {
       const basePath = this.#localPathToUrl("");
       if (!url.startsWith(basePath)) throw new Error("Invalid Base URL, Unable to delete data");
       const path = url.replace(basePath, "");
-      await Bun.file(`${this.root}/${path}`).delete();
+      await this.deleteDataByPath(path);
       return true;
     } catch (error) {
       this.logger.error(error instanceof Error ? error.message : "Unknown error");

package/signal/index.ts

@@ -15,4 +15,5 @@ export * from "./signalContext";
 export * from "./signalRegistry";
 export * from "./slice";
 export * from "./sliceInfo";
+export * from "./trace";
 export * from "./types";

package/signal/middleware.ts

@@ -2,6 +2,7 @@ import type { BaseEnv, Cls, PromiseOrObject } from "akanjs/base";
 import { type CacheAdaptor, CacheAdaptorRole } from "akanjs/service";
 import dayjs from "dayjs";
 import type { SignalContext } from "./signalContext";
+import { traceCache } from "./trace";
 
 export interface Middleware<Env extends BaseEnv = BaseEnv> {
   use(env: Env): PromiseOrObject<(context: SignalContext, next: () => Promise<unknown>) => PromiseOrObject<unknown>>;
@@ -52,12 +53,15 @@ export class Cache extends middleware("cache") {
       if (cached) {
         context.adaptor.logger.debug(`Cache hit ${context.key}`);
         try {
-          return JSON.parse(cached);
+          const parsed = JSON.parse(cached);
+          traceCache(true);
+          return parsed;
         } catch (parseError) {
           context.adaptor.logger.warn(`Cache parse error ${context.key}: ${String(parseError)}`);
           await cache.delete(topic, key);
         }
       }
+      traceCache(false);
 
       const result = await next();
 

package/signal/signalContext.ts

@@ -18,6 +18,7 @@ import type { Adaptor, AdaptorCls, DatabaseService, InjectRegistry, LiveRegistry
 import type { Internal, InternalCls, InternalInfo, MiddlewareCls } from ".";
 import type { EndpointInfo } from "./endpointInfo";
 import { Exception } from "./exception";
+import { isTraceEnabled, runWithTrace, SignalTrace, traceSpan } from "./trace";
 
 export type SignalTransportType = "http" | "websocket";
 
@@ -54,6 +55,7 @@ export class SignalContext<
   adaptor: Adaptor;
   args: unknown[] = [];
   internalArgs: unknown[] = [];
+  trace: SignalTrace | null = null;
   #registry: InjectRegistry;
   #env: Env;
   #live: LiveRegistry;
@@ -87,6 +89,7 @@ export class SignalContext<
     this.#env = env;
     this.#live = live;
     this.#middleware = middleware;
+    if (isTraceEnabled()) this.trace = new SignalTrace(key, endpointInfo.type);
   }
 
   getAdaptor<T extends Adaptor>(adaptorCls: AdaptorCls<T>): T {
@@ -97,11 +100,18 @@ export class SignalContext<
     return instance as T;
   }
   async init() {
-    this.args = await this.ctx.getArgs(this.endpointInfo);
+    if (this.trace) {
+      const start = performance.now();
+      this.args = await this.ctx.getArgs(this.endpointInfo);
+      this.trace.recordSpan("argParse", performance.now() - start);
+    } else {
+      this.args = await this.ctx.getArgs(this.endpointInfo);
+    }
     return this;
   }
   async #checkGuards() {
     const guards = this.endpointInfo.signalOption.guards ?? [];
+    if (guards.length === 0) return;
     for (const GuardCls of guards) {
       const guard = new GuardCls();
       const canPass = guard.canPass(this);
@@ -109,41 +119,72 @@ export class SignalContext<
     }
   }
   async exec() {
+    if (!this.trace) return await this.#exec();
+    return await runWithTrace(this.trace, async () => {
+      try {
+        return await this.#exec();
+      } finally {
+        this.trace?.finalize();
+      }
+    });
+  }
+  async #exec() {
     if (!this.endpointInfo.execFn) throw new Exception.Error("Exec function is not set");
-    const middlewares = [...this.#middleware.values(), ...(this.endpointInfo.signalOption.middlewares ?? [])];
+    const endpointMiddlewares = this.endpointInfo.signalOption.middlewares ?? [];
     const coreExec = async () => {
       if (!this.endpointInfo.execFn) throw new Exception.Error("Exec function is not set");
-      await this.#checkGuards();
-      this.internalArgs = await Promise.all(
-        this.endpointInfo.internalArgs.map((arg) => {
-          const argValue = new arg.argRef().getArg(this) ?? null;
-          if (argValue === null && !arg.option?.nullable)
-            throw new Exception.Unauthorized(`Internal Argument ${arg.argRef.name} is required`);
-          return argValue;
-        }),
+      if (this.trace) await traceSpan("guards", () => this.#checkGuards());
+      else await this.#checkGuards();
+      if (this.endpointInfo.internalArgs.length > 0) {
+        this.internalArgs = await Promise.all(
+          this.endpointInfo.internalArgs.map((arg) => {
+            const argValue = new arg.argRef().getArg(this) ?? null;
+            if (argValue === null && !arg.option?.nullable)
+              throw new Exception.Unauthorized(`Internal Argument ${arg.argRef.name} is required`);
+            return argValue;
+          }),
+        );
+      }
+      if (!this.trace) return await this.endpointInfo.execFn.call(this.adaptor, ...this.args, ...this.internalArgs);
+      return await traceSpan(
+        "handler",
+        async () => await this.endpointInfo.execFn?.call(this.adaptor, ...this.args, ...this.internalArgs),
       );
-      const result = await this.endpointInfo.execFn.call(this.adaptor, ...this.args, ...this.internalArgs);
-      return result;
     };
     let next = coreExec;
-    for (let i = middlewares.length - 1; i >= 0; i--) {
-      const MiddlewareCls = middlewares[i];
-      if (!MiddlewareCls) continue;
-      const middleware = new MiddlewareCls();
-      const currentNext = next;
-      next = async () => await (await middleware.use(this.getEnv()))(this, currentNext);
+    if (this.#middleware.size > 0 || endpointMiddlewares.length > 0) {
+      const middlewares = [...this.#middleware.values(), ...endpointMiddlewares];
+      for (let i = middlewares.length - 1; i >= 0; i--) {
+        const MiddlewareCls = middlewares[i];
+        if (!MiddlewareCls) continue;
+        const middleware = new MiddlewareCls();
+        const currentNext = next;
+        next = async () => await (await middleware.use(this.getEnv()))(this, currentNext);
+      }
     }
-    const result = await next();
+    const result = this.trace ? await traceSpan("execChain", () => next()) : await next();
     if (this.endpointInfo.type === "pubsub") return;
     if (result instanceof Response) return result;
-    const resolved = await SignalContext.resolveReturn(result, {
-      signalContext: this,
-      returnRef: this.endpointInfo.returns.returnRef,
-      arrDepth: this.endpointInfo.returns.arrDepth,
-      registry: this.#registry,
-      live: this.#live,
-    });
-    return this.ctx.makeResponse(resolved, this.endpointInfo);
+    if (!this.trace) {
+      const resolved = await SignalContext.resolveReturn(result, {
+        signalContext: this,
+        returnRef: this.endpointInfo.returns.returnRef,
+        arrDepth: this.endpointInfo.returns.arrDepth,
+        registry: this.#registry,
+        live: this.#live,
+      });
+      return this.ctx.makeResponse(resolved, this.endpointInfo);
+    }
+    const resolved = await traceSpan("resolveReturn", () =>
+      SignalContext.resolveReturn(result, {
+        signalContext: this,
+        returnRef: this.endpointInfo.returns.returnRef,
+        arrDepth: this.endpointInfo.returns.arrDepth,
+        registry: this.#registry,
+        live: this.#live,
+      }),
+    );
+    return await traceSpan("serialize", async () => this.ctx.makeResponse(resolved, this.endpointInfo));
   }
   static async try(
     endpoint: Adaptor,
@@ -257,6 +298,11 @@ export class SignalContext<
     service: DatabaseService,
     { arrDepth, nullable }: { arrDepth: number; nullable: boolean },
   ): Promise<unknown> {
+    if (value === null || value === undefined) {
+      if (nullable) return null;
+      throw new Error(`Document ${value} is not found`);
+    }
+    if (arrDepth > 0 && Array.isArray(value) && value.length === 0) return [];
     if (arrDepth === 0)
       return await service.__load(String(value)).then((doc) => {
         if (doc === null) {
@@ -300,19 +346,24 @@ export class SignalContext<
 export class HttpExecutionContext<Appended = unknown> {
   req: Bun.BunRequest & Appended;
   res = Response;
-  url: URL;
+  #url: URL | null = null;
   params: RuntimeRecord = {};
   searchParams: RuntimeRecord = {};
   body: RuntimeRecord = {};
   constructor(req: Bun.BunRequest) {
     this.req = req as Bun.BunRequest & Appended;
-    this.url = new URL(req.url);
+  }
+  get url() {
+    if (!this.#url) this.#url = new URL(this.req.url);
+    return this.#url;
   }
   async getArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
+    if (endpointInfo.args.length === 0) return [];
     this.params = this.req.params;
     
-    const hasUploadArgs = endpointInfo.args.some((arg) => arg.type === "body" && arg.argRef === Upload);
-    if (endpointInfo.type === "mutation" && this.req.body) {
+    const hasBodyArgs = endpointInfo.args.some((arg) => arg.type === "body");
+    const hasUploadArgs = hasBodyArgs && endpointInfo.args.some((arg) => arg.type === "body" && arg.argRef === Upload);
+    if (endpointInfo.type === "mutation" && hasBodyArgs && this.req.body) {
       if (hasUploadArgs) {
         const formData = await this.req.formData();
         this.body = {};
@@ -361,6 +412,9 @@ export class HttpExecutionContext<Appended = unknown> {
   }
   makeResponse(result: unknown, endpointInfo: EndpointInfo) {
     if (result instanceof Response) return result;
+    if (endpointInfo.returns.arrDepth === 0 && PrimitiveRegistry.has(endpointInfo.returns.returnRef as Cls)) {
+      return this.res.json(result);
+    }
     const value = serialize(endpointInfo.returns.returnRef, endpointInfo.returns.arrDepth, result, "object", {
       nullable: endpointInfo.returns.nullable,
     });

package/signal/trace.ts

@@ -0,0 +1,279 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Lightweight request tracing for Akan signals.
+ *
+ * Everything here is gated behind the `AKAN_TRACE=1` environment flag so that the
+ * production hot path pays nothing when tracing is disabled (see {@link isTraceEnabled}).
+ * The goal is internal performance work (per-stage latency breakdown, query counts,
+ * cache hit ratio) rather than full distributed tracing.
+ */
+
+let traceEnabledCache: boolean | null = null;
+
+/** Whether request tracing is enabled. Cached after first read. */
+export const isTraceEnabled = (): boolean => {
+  if (traceEnabledCache === null) traceEnabledCache = process.env.AKAN_TRACE === "1";
+  return traceEnabledCache;
+};
+
+/** Override the trace flag at runtime (tests / harness control). */
+export const setTraceEnabled = (enabled: boolean): void => {
+  traceEnabledCache = enabled;
+};
+
+export interface SpanRecord {
+  name: string;
+  durationMs: number;
+}
+
+const MAX_SPANS_PER_TRACE = 64;
+
+/** Per-request trace context. Threaded via {@link AsyncLocalStorage}. */
+export class SignalTrace {
+  readonly traceId: string;
+  readonly endpointKey: string;
+  readonly endpointType: string;
+  readonly startedAt: number;
+  readonly spans: SpanRecord[] = [];
+  dbQueryCount = 0;
+  dbQueryMs = 0;
+  cacheHits = 0;
+  cacheMisses = 0;
+  dataLoaderBatchCount = 0;
+  dataLoaderKeyCount = 0;
+  #finalized = false;
+
+  constructor(endpointKey: string, endpointType: string) {
+    this.endpointKey = endpointKey;
+    this.endpointType = endpointType;
+    this.startedAt = performance.now();
+    this.traceId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+
+  recordSpan(name: string, durationMs: number): void {
+    if (this.spans.length >= MAX_SPANS_PER_TRACE) return;
+    this.spans.push({ name, durationMs });
+  }
+
+  countDbQuery(durationMs: number): void {
+    this.dbQueryCount += 1;
+    this.dbQueryMs += durationMs;
+  }
+
+  countCache(hit: boolean): void {
+    if (hit) this.cacheHits += 1;
+    else this.cacheMisses += 1;
+  }
+
+  countDataLoaderBatch(keyCount: number): void {
+    this.dataLoaderBatchCount += 1;
+    this.dataLoaderKeyCount += keyCount;
+  }
+
+  finalize(): void {
+    if (this.#finalized) return;
+    this.#finalized = true;
+    const totalMs = performance.now() - this.startedAt;
+    this.recordSpan("total", totalMs);
+    traceAggregator.ingest(this);
+    maybeFlushTraceFile();
+  }
+}
+
+const traceProcessStore = process as unknown as {
+  __akanTraceAls?: AsyncLocalStorage<SignalTrace>;
+  __akanTraceAggregator?: TraceAggregator;
+};
+
+let alsInstance = traceProcessStore.__akanTraceAls;
+if (!alsInstance) {
+  alsInstance = new AsyncLocalStorage<SignalTrace>();
+  traceProcessStore.__akanTraceAls = alsInstance;
+}
+const als = alsInstance;
+
+export const getCurrentTrace = (): SignalTrace | undefined => als.getStore();
+
+/** Run `fn` with `trace` as the ambient request trace. */
+export const runWithTrace = <T>(trace: SignalTrace, fn: () => T): T => als.run(trace, fn);
+
+/**
+ * Time an async stage under the current trace. When tracing is off (or no trace is
+ * active) this is a thin passthrough with no measurement overhead.
+ */
+export const traceSpan = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
+  const trace = getCurrentTrace();
+  if (!trace) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    trace.recordSpan(name, performance.now() - start);
+  }
+};
+
+/** Record a DB query duration against the current trace (no-op when untraced). */
+export const traceDbQuery = (durationMs: number): void => {
+  getCurrentTrace()?.countDbQuery(durationMs);
+};
+
+/** Record a cache hit/miss against the current trace (no-op when untraced). */
+export const traceCache = (hit: boolean): void => {
+  getCurrentTrace()?.countCache(hit);
+};
+
+/** Record a DataLoader batch against the current trace (no-op when untraced). */
+export const traceDataLoaderBatch = (keyCount: number): void => {
+  getCurrentTrace()?.countDataLoaderBatch(keyCount);
+};
+
+interface SpanStat {
+  count: number;
+  sumMs: number;
+  maxMs: number;
+  samples: number[];
+}
+
+interface EndpointStat {
+  endpointKey: string;
+  endpointType: string;
+  requests: number;
+  spans: Map<string, SpanStat>;
+  dbQueryCount: number;
+  dbQueryMs: number;
+  cacheHits: number;
+  cacheMisses: number;
+  dataLoaderBatchCount: number;
+  dataLoaderKeyCount: number;
+}
+
+const RING_SIZE = 1024;
+
+const percentile = (sorted: number[], p: number): number => {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+  return sorted[idx] ?? 0;
+};
+
+/**
+ * Process-wide aggregator. Keeps rolling per-endpoint, per-span statistics with a
+ * bounded sample ring per span so percentiles stay representative of steady state
+ * without unbounded memory growth.
+ */
+class TraceAggregator {
+  #endpoints = new Map<string, EndpointStat>();
+
+  ingest(trace: SignalTrace): void {
+    const id = `${trace.endpointType}:${trace.endpointKey}`;
+    let stat = this.#endpoints.get(id);
+    if (!stat) {
+      stat = {
+        endpointKey: trace.endpointKey,
+        endpointType: trace.endpointType,
+        requests: 0,
+        spans: new Map(),
+        dbQueryCount: 0,
+        dbQueryMs: 0,
+        cacheHits: 0,
+        cacheMisses: 0,
+        dataLoaderBatchCount: 0,
+        dataLoaderKeyCount: 0,
+      };
+      this.#endpoints.set(id, stat);
+    }
+    stat.requests += 1;
+    stat.dbQueryCount += trace.dbQueryCount;
+    stat.dbQueryMs += trace.dbQueryMs;
+    stat.cacheHits += trace.cacheHits;
+    stat.cacheMisses += trace.cacheMisses;
+    stat.dataLoaderBatchCount += trace.dataLoaderBatchCount;
+    stat.dataLoaderKeyCount += trace.dataLoaderKeyCount;
+    for (const span of trace.spans) {
+      let spanStat = stat.spans.get(span.name);
+      if (!spanStat) {
+        spanStat = { count: 0, sumMs: 0, maxMs: 0, samples: [] };
+        stat.spans.set(span.name, spanStat);
+      }
+      spanStat.count += 1;
+      spanStat.sumMs += span.durationMs;
+      spanStat.maxMs = Math.max(spanStat.maxMs, span.durationMs);
+      if (spanStat.samples.length < RING_SIZE) spanStat.samples.push(span.durationMs);
+      else spanStat.samples[spanStat.count % RING_SIZE] = span.durationMs;
+    }
+  }
+
+  reset(): void {
+    this.#endpoints.clear();
+  }
+
+  /** Summarized snapshot suitable for JSON exposure on the metrics endpoint. */
+  snapshot() {
+    const endpoints = [...this.#endpoints.values()].map((stat) => {
+      const spans = [...stat.spans.entries()].map(([name, s]) => {
+        const sorted = [...s.samples].sort((a, b) => a - b);
+        return {
+          name,
+          count: s.count,
+          meanMs: round(s.sumMs / s.count),
+          p50Ms: round(percentile(sorted, 50)),
+          p95Ms: round(percentile(sorted, 95)),
+          p99Ms: round(percentile(sorted, 99)),
+          maxMs: round(s.maxMs),
+        };
+      });
+      spans.sort((a, b) => b.meanMs - a.meanMs);
+      const cacheTotal = stat.cacheHits + stat.cacheMisses;
+      return {
+        endpoint: `${stat.endpointType}:${stat.endpointKey}`,
+        requests: stat.requests,
+        avgDbQueriesPerRequest: round(stat.dbQueryCount / stat.requests),
+        avgDbQueryMsPerRequest: round(stat.dbQueryMs / stat.requests),
+        cacheHitRatio: cacheTotal ? round(stat.cacheHits / cacheTotal, 4) : null,
+        avgDataLoaderBatchSize: stat.dataLoaderBatchCount
+          ? round(stat.dataLoaderKeyCount / stat.dataLoaderBatchCount)
+          : null,
+        spans,
+      };
+    });
+    endpoints.sort((a, b) => b.requests - a.requests);
+    return { enabled: isTraceEnabled(), endpoints };
+  }
+}
+
+const round = (value: number, digits = 3): number => {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+};
+
+let aggregatorInstance = traceProcessStore.__akanTraceAggregator;
+if (!aggregatorInstance) {
+  aggregatorInstance = new TraceAggregator();
+  traceProcessStore.__akanTraceAggregator = aggregatorInstance;
+}
+export const traceAggregator: TraceAggregator = aggregatorInstance;
+
+/** Snapshot of all aggregated trace stats. Safe to call when tracing is disabled. */
+export const getTraceSnapshot = () => traceAggregator.snapshot();
+
+/**
+ * Optional file sink for the aggregated snapshot.
+ *
+ * The akan worker loads the app-server bundle and the framework metrics collector in
+ * separate module realms that share neither `globalThis` nor `process`, so the in-realm
+ * aggregator that records spans cannot be read by the metrics endpoint's collector. When
+ * `AKAN_TRACE_FILE` is set, the recording realm instead flushes the cumulative snapshot to
+ * that path (throttled), where any external reader (e.g. the benchmark harness) can pick it
+ * up. This is a benchmarking/diagnostics aid, not a production hot-path concern.
+ */
+const traceFilePath = process.env.AKAN_TRACE_FILE;
+let lastTraceFlushAt = 0;
+const TRACE_FLUSH_INTERVAL_MS = 1_000;
+
+const maybeFlushTraceFile = (): void => {
+  if (!traceFilePath) return;
+  const now = Date.now();
+  if (now - lastTraceFlushAt < TRACE_FLUSH_INTERVAL_MS) return;
+  lastTraceFlushAt = now;
+  void Bun.write(traceFilePath, JSON.stringify(traceAggregator.snapshot())).catch(() => {});
+};

package/types/devkit/capacitorApp.d.ts

@@ -8,6 +8,8 @@ interface RunConfig {
     env: "local" | "debug" | "develop" | "main";
     regenerate?: boolean;
 }
+interface PrepareConfig extends RunConfig {
+}
 export declare class CapacitorApp {
     #private;
     private readonly app;
@@ -18,19 +20,26 @@ export declare class CapacitorApp {
     };
     iosTargetName: string;
     readonly targetRoot: string;
+    readonly targetRootPath: string;
+    readonly targetWebRoot: string;
+    readonly targetAssetRoot: string;
+    readonly iosRootPath = "ios";
+    readonly iosProjectPath = "ios/App";
+    readonly androidRootPath = "android";
     constructor(app: AppExecutor, target: AkanMobileTargetConfig);
-    init({ platform, regenerate }?: {
+    init({ platform, operation, env, regenerate, }?: {
         platform?: "ios" | "android";
-        regenerate?: boolean;
-    }): Promise<this>;
+    } & Partial<PrepareConfig>): Promise<this>;
     save(): Promise<void>;
-    buildIos(options?: {
+    buildIos({ env, regenerate }?: {
+        env?: RunConfig["env"];
         regenerate?: boolean;
     }): Promise<void>;
     syncIos(): Promise<void>;
     openIos(): Promise<void>;
     runIos({ operation, env, regenerate }: RunConfig): Promise<void>;
-    buildAndroid(assembleType: "apk" | "aab", options?: {
+    buildAndroid(assembleType: "apk" | "aab", { env, regenerate }?: {
+        env?: RunConfig["env"];
         regenerate?: boolean;
     }): Promise<void>;
     openAndroid(): Promise<void>;

package/types/server/processMetricsCollector.d.ts

@@ -2,6 +2,8 @@ import type { AkanMetricsReport } from "akanjs/service";
 export declare class ProcessMetricsCollector {
     #private;
     static parseMemoryLogIntervalMs(value?: string | undefined): number;
+    /** Begin sampling event-loop lag. Idempotent; safe to call from each server role. */
+    static startEventLoopLagMonitor(intervalMs?: number): void;
     static collect(extra?: AkanMetricsReport): Promise<AkanMetricsReport>;
     static formatBytes(bytes?: number): string;
     static format(metrics: AkanMetricsReport): string;

package/types/service/ipcTypes.d.ts

@@ -108,6 +108,11 @@ export interface AkanMetricsReport {
     httpHtmlCacheHits?: number;
     httpHtmlCacheMisses?: number;
     httpHtmlCacheBypass?: number;
+    eventLoopLagMeanMs?: number;
+    eventLoopLagP99Ms?: number;
+    eventLoopLagMaxMs?: number;
+    gcDurationMs?: number;
+    trace?: unknown;
 }
 export type AkanIpcMessage = {
     type: "ready";