akanjs 3.0.0-beta.8 → 3.0.0

package/server/hmr/ssrDevShim.ts

@@ -0,0 +1,112 @@
+import { type CsrDevManifest, SSR_DEV_CHUNK, SSR_DEV_ID_PREFIX, SSR_DEV_ROUTE_PREFIX } from "./csrDevManifest";
+import { CSR_DEV_RUNTIME_SCRIPT } from "./csrDevRuntime";
+
+export class SsrDevShim {
+  static readonly runtimeUrl = `${SSR_DEV_ROUTE_PREFIX}runtime.js?v=${Bun.hash(CSR_DEV_RUNTIME_SCRIPT).toString(36)}`;
+  static readonly #body = `var baseLoad = self.__webpack_chunk_load__;
+  var baseRequire = self.__webpack_require__;
+  var booting = null;
+  var built = null;
+  function wait(ms) {
+    return new Promise(function (resolve) { setTimeout(resolve, ms); });
+  }
+  function script(src) {
+    return new Promise(function (resolve, reject) {
+      var el = document.createElement("script");
+      el.src = src;
+      el.async = false;
+      el.onload = function () { resolve(); };
+      el.onerror = function () { reject(new Error("[akan-ssr-dev] " + src + " failed to load")); };
+      document.head.appendChild(el);
+    });
+  }
+  function state() {
+    return fetch(c.prefix + "boot.json?wait=10000", { cache: "no-store" }).then(function (res) {
+      return res.ok ? res.json() : wait(1000).then(state);
+    }, function () {
+      return wait(1000).then(state);
+    });
+  }
+  function load(vendors, attempt) {
+    self.__AKAN_SSR_EPOCH__ = built.epoch;
+    return Promise.all([vendors, script(c.prefix + built.vendorFile)]).then(function () {
+      return script(c.prefix + "app.js?g=" + built.generation);
+    }).catch(function (error) {
+      if (attempt >= 3) throw error;
+      return wait(500).then(state).then(function (next) {
+        built = next;
+        return load(vendors, attempt + 1);
+      });
+    });
+  }
+  function reloadOnto(vendorFile, attempt) {
+    return state().then(function (current) {
+      if (current.vendorFile === vendorFile) {
+        self.location.reload();
+        return new Promise(function () {});
+      }
+      if (attempt < 4) return wait(500).then(function () { return reloadOnto(vendorFile, attempt + 1); });
+    });
+  }
+  function catchUp() {
+    var hello = self.__AKAN_SSR_HELLO_GENERATION__;
+    if (typeof hello === "number") self.__akan.catchUp(hello, c.prefix);
+  }
+  function runtime(attempt) {
+    return script(c.runtime).catch(function (error) {
+      if (attempt >= 3) throw error;
+      return wait(500).then(state).then(function () { return runtime(attempt + 1); });
+    });
+  }
+  function boot() {
+    if (!booting)
+      booting = self.__AKAN_SSR_BOOT__ = runtime(0).then(function () {
+        var early = self.__AKAN_SSR_EARLY_UPDATES__ || [];
+        self.__AKAN_SSR_EARLY_UPDATES__ = null;
+        for (var i = 0; i < early.length; i++) self.__akan.hot(early[i]);
+        return c.vendorFile ? c : state();
+      }).then(function (current) {
+        built = current;
+        return load(Promise.all(c.vendors.map(function (specifier) {
+          return import(specifier).then(function (ns) { self.__akan.provide("vendor:" + specifier, ns); });
+        })), 0);
+      }).then(function () {
+        var started = self.__akan.inspect();
+        if (typeof started.epoch === "number") self.__AKAN_SSR_EPOCH__ = started.epoch;
+        var vendorFile = started.vendorFile;
+        if (!vendorFile || vendorFile === built.vendorFile) return catchUp();
+        if (started.failed) return reloadOnto(vendorFile, 0);
+        return script(c.prefix + vendorFile).then(catchUp, function () { return reloadOnto(vendorFile, 0); });
+      }).catch(function (error) {
+        var failed = built || c;
+        self.__AKAN_SSR_BOOT_FAILED__ = { generation: failed.generation || 0, epoch: failed.epoch };
+        throw error;
+      });
+    return booting;
+  }
+  self.__webpack_chunk_load__ = function (id) { return id === c.chunk ? boot() : baseLoad(id); };
+  var require = function (id) {
+    if (typeof id !== "string" || id.indexOf(c.idPrefix) !== 0) return baseRequire(id);
+    var moduleId = id.slice(c.idPrefix.length);
+    var registry = self.__akan;
+    if (registry.has(moduleId)) return registry.require(moduleId);
+    return registry.whenDefined(moduleId).then(function () { return registry.require(moduleId); });
+  };
+  require.u = baseRequire.u;
+  self.__webpack_require__ = require;`;
+
+  /** `vendors` are the import map's specifiers: the registry requires them as `vendor:<specifier>`, never compiles them. */
+  static script(manifest: CsrDevManifest | null, vendors: string[]): string {
+    const config = {
+      chunk: SSR_DEV_CHUNK,
+      idPrefix: SSR_DEV_ID_PREFIX,
+      prefix: SSR_DEV_ROUTE_PREFIX,
+      runtime: SsrDevShim.runtimeUrl,
+      generation: manifest?.generation ?? 0,
+      vendorFile: manifest?.vendorFile ?? null,
+      epoch: manifest?.epoch ?? null,
+      vendors,
+    };
+    return `(function (c) {\n  ${SsrDevShim.#body}\n})(${JSON.stringify(config)});`;
+  }
+}

package/server/hmr/ssrUpdateQueue.ts

@@ -0,0 +1,111 @@
+import type { SsrUpdatedPayload } from "../artifact";
+import type { HmrMessage } from "./wsHub";
+
+export type SsrUpdateMessage = Extract<HmrMessage, { type: "ssr-update" }>;
+
+interface HeldUpdate {
+  message: SsrUpdateMessage;
+  hold: boolean;
+  batchGeneration?: number;
+  heldAt: number;
+}
+
+export class SsrUpdateQueue {
+  readonly #send: (message: SsrUpdateMessage) => void;
+  readonly #maxHoldMs: number;
+  readonly #held: HeldUpdate[] = [];
+  #timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(send: (message: SsrUpdateMessage) => void, { maxHoldMs = 15_000 }: { maxHoldMs?: number } = {}) {
+    this.#send = send;
+    this.#maxHoldMs = maxHoldMs;
+  }
+
+  get size(): number {
+    return this.#held.length;
+  }
+
+  push(update: SsrUpdatedPayload): void {
+    const message: SsrUpdateMessage = {
+      type: "ssr-update",
+      generation: update.generation,
+      url: update.patchUrl,
+      changedIds: update.changedIds,
+      reload: update.reload,
+      reason: update.reason,
+      trace: update.trace,
+    };
+    const entry: HeldUpdate = {
+      message,
+      hold: !!update.hold,
+      batchGeneration: update.batchGeneration,
+      heldAt: Date.now(),
+    };
+
+    if (update.reload) {
+      for (const held of this.#held.splice(0)) {
+        if (!held.hold) continue;
+        entry.hold = true;
+        entry.heldAt = Math.min(entry.heldAt, held.heldAt);
+        if (held.batchGeneration !== undefined)
+          entry.batchGeneration = Math.max(entry.batchGeneration ?? held.batchGeneration, held.batchGeneration);
+      }
+    }
+    if (!entry.hold && this.#held.length === 0) {
+      this.#stopTimer();
+      this.#send(message);
+      return;
+    }
+    this.#held.push(entry);
+    this.#arm();
+  }
+
+  /**
+   * The pages batch of `generation` finished or failed: sends what it covers and everything queued behind that, and
+   * says whether a reload went out (the tabs then need no RSC refresh).
+   */
+  release(generation: number | undefined): { released: number; reload: boolean } {
+    return this.#shift((held) => !this.#waitsPast(held, generation), true);
+  }
+
+  /** Drops what the pages batch of `generation` covers, or everything without one: the tabs are about to reload. */
+  clear(generation?: number): void {
+    if (generation === undefined) this.#held.length = 0;
+    else this.#shift((held) => !this.#waitsPast(held, generation), false);
+    this.#arm();
+  }
+
+  #waitsPast(held: HeldUpdate, generation: number | undefined): boolean {
+    return held.hold && held.batchGeneration !== undefined && (generation ?? -1) < held.batchGeneration;
+  }
+
+  #shift(due: (held: HeldUpdate) => boolean, send: boolean): { released: number; reload: boolean } {
+    let released = 0;
+    let reload = false;
+    for (let next = this.#held[0]; next && due(next); next = this.#held[0]) {
+      this.#held.shift();
+      if (send) this.#send(next.message);
+      released += 1;
+      reload ||= !!next.message.reload;
+    }
+    this.#arm();
+    return { released, reload };
+  }
+
+  #arm(): void {
+    this.#stopTimer();
+    const head = this.#held[0];
+    if (!head) return;
+    const delay = Math.max(0, head.heldAt + this.#maxHoldMs - Date.now());
+    this.#timer = setTimeout(() => {
+      this.#timer = null;
+      const now = Date.now();
+      this.#shift((held) => !held.hold || now - held.heldAt >= this.#maxHoldMs, true);
+    }, delay);
+  }
+
+  #stopTimer(): void {
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+}

package/server/hmr/wsHub.ts

@@ -1,9 +1,20 @@
 import { Logger } from "akanjs/common";
-import type { BuildPhase } from "../artifact";
+import type { BuildPhase, HmrTrace } from "../artifact";
+
+export type ChangeKind = "code" | "css" | "config" | "ignore";
+
+export interface ChangeBatch {
+  files: string[];
+  kinds: Set<Exclude<ChangeKind, "ignore">>;
+  trace?: HmrTrace;
+}
+
+export type HmrClientKind = "ssr" | "csr";
 
 export interface HmrWsData {
   kind: "akan-hmr";
   openedAt: number;
+  client?: HmrClientKind;
 }
 
 export type HmrMessage =
@@ -11,15 +22,38 @@ export type HmrMessage =
       type: "hello";
       buildId: number;
       cssAssets?: Record<string, { cssUrl: string; cssRelPath: string }>;
+      csrGeneration?: number;
+      ssrGeneration?: number;
+      ssrEpoch?: number;
+      /** The phases failing now, each sent right after: a tab drops an error it holds for any other. */
+      failingPhases?: string[];
     }
   | { type: "reload"; buildId: number }
-  | { type: "rsc-refresh"; buildId: number; generation?: number; changedFiles?: string[]; routeIds?: string[] }
   | {
-      type: "client-refresh";
+      type: "csr-update";
+      generation: number;
+      url?: string;
+      changedIds?: string[];
+      reload?: boolean;
+      reason?: string;
+      trace?: HmrTrace;
+    }
+  | {
+      type: "ssr-update";
+      generation: number;
+      url?: string;
+      changedIds?: string[];
+      reload?: boolean;
+      reason?: string;
+      trace?: HmrTrace;
+    }
+  | {
+      type: "rsc-refresh";
       buildId: number;
       generation?: number;
       changedFiles?: string[];
       routeIds?: string[];
+      trace?: HmrTrace;
     }
   | { type: "css-update"; cssAssets?: Record<string, { cssUrl: string; cssRelPath: string }> }
   | { type: "sync-navigation"; clientId: string; href: string; kind?: "push" | "replace" | "back" | "pop" }
@@ -35,34 +69,43 @@ export type HmrMessage =
   | { type: "error"; message: string };
 
 export const HMR_WS_TOPIC = "__akan_hmr";
+export const HMR_CSR_WS_TOPIC = "__akan_hmr_csr";
 
 export class HmrWsHub {
   readonly #logger = new Logger("HmrWsHub");
   readonly #conns = new Set<Bun.ServerWebSocket<HmrWsData>>();
   #publish: ((topic: string, payload: string) => void) | null = null;
 
-  get size(): number {
-    return this.#conns.size;
-  }
-
   setPublisher(publish: (topic: string, payload: string) => void): void {
     this.#publish = publish;
   }
 
   attach(ws: Bun.ServerWebSocket<HmrWsData>): void {
-    ws.subscribe(HMR_WS_TOPIC);
+    ws.subscribe(HmrWsHub.#topicOf(ws.data?.client));
     this.#conns.add(ws);
-    this.#logger.verbose(`[hmr] ws connected (total=${this.#conns.size})`);
+    this.#logger.verbose(`[hmr] ws connected client=${ws.data?.client ?? "ssr"} (total=${this.#conns.size})`);
   }
 
   detach(ws: Bun.ServerWebSocket<HmrWsData>): void {
-    ws.unsubscribe(HMR_WS_TOPIC);
+    ws.unsubscribe(HmrWsHub.#topicOf(ws.data?.client));
     if (this.#conns.delete(ws)) this.#logger.verbose(`[hmr] ws disconnected (total=${this.#conns.size})`);
   }
 
   broadcast(msg: HmrMessage): void {
     const payload = JSON.stringify(msg);
-    this.#publish?.(HMR_WS_TOPIC, payload);
+    const audience = HmrWsHub.#audienceOf(msg);
+    if (audience !== "csr") this.#publish?.(HMR_WS_TOPIC, payload);
+    if (audience !== "ssr") this.#publish?.(HMR_CSR_WS_TOPIC, payload);
+  }
+
+  static #audienceOf(msg: HmrMessage): HmrClientKind | "all" {
+    if (msg.type === "csr-update") return "csr";
+    if (msg.type === "reload" || msg.type === "rsc-refresh" || msg.type === "ssr-update") return "ssr";
+    return "all";
+  }
+
+  static #topicOf(client: HmrClientKind | undefined): string {
+    return client === "csr" ? HMR_CSR_WS_TOPIC : HMR_WS_TOPIC;
   }
 
   handleMessage(message: string): void {
@@ -78,7 +121,7 @@ export class HmrWsHub {
   }
 }
 
-const isSyncNavigationEnabled = () =>
+export const isSyncNavigationEnabled = () =>
   process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "true" ||
   process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "1" ||
   process.env.SYNC_DOMAIN === "true" ||

package/server/imageOptimizer.ts

@@ -61,6 +61,7 @@ export class ImageOptimizer {
   static readonly #avif = "image/avif";
   static readonly #heic = "image/heic";
   static readonly #bypassTypes = new Set(["image/x-icon", "image/x-icns", "image/bmp", "image/jxl", "image/heic"]);
+  static readonly #encodableTypes = new Set(["image/jpeg", "image/png", "image/webp", "image/avif"]);
 
   #publicDir: string;
   #cacheDir: string;
@@ -84,20 +85,10 @@ export class ImageOptimizer {
     this.#semaphore = new Semaphore(ImageOptimizer.#resolveConcurrency(this.#config.maxConcurrency));
   }
 
-  /**
-   * Bun.Image encodes on the worker pool that fs, hashing and every other off-thread call also queue on, and the
-   * pool is sized by the CPU count Bun sees — 1 under a container `cpu` limit. Holding image work to half the
-   * slots leaves a stat or a bcrypt waiting behind a couple of encodes instead of behind the whole flood.
-   */
   static #resolveConcurrency(configured: number): number {
     return configured > 0 ? configured : Math.max(1, Math.floor(navigator.hardwareConcurrency / 2));
   }
 
-  /**
-   * AVIF, HEIC and TIFF ride the OS codec, which only the `system` backend has — macOS and Windows.
-   * A Linux container runs the `bun` backend, where both encode and decode raise
-   * `ERR_IMAGE_FORMAT_UNSUPPORTED`, so those types are decided up front rather than thrown at.
-   */
   static #isCodecAvailable(contentType: string): boolean {
     if (contentType !== ImageOptimizer.#avif && contentType !== ImageOptimizer.#heic && contentType !== "image/tiff")
       return true;
@@ -117,10 +108,6 @@ export class ImageOptimizer {
     }
   }
 
-  /**
-   * A cold `srcSet` puts the same width in flight several times over, and the cache file only exists once
-   * the first of them has finished, so identical requests join one run instead of each fetching and encoding.
-   */
   async #loadOptimizedImage(parsed: ParsedImageRequest): Promise<OptimizedImage> {
     const key = `${parsed.href}|${parsed.width}|${parsed.quality}|${parsed.outputType}`;
     const joined = this.#inflight.get(key);
@@ -149,12 +136,6 @@ export class ImageOptimizer {
     return optimized;
   }
 
-  /**
-   * The bytes are keyed by the source's own etag/mtime, so finding them means reading the source first — free for
-   * a local file, a full re-download for a remote one. This pointer is keyed by the request alone and carries the
-   * TTL (upstream `max-age`, floored by `minimumCacheTTL`), so a warm remote image never touches the origin.
-   * Dev is left out: re-fetching every time is what makes an upstream edit show up immediately.
-   */
   async #readRemotePointer(parsed: ParsedImageRequest): Promise<OptimizedImage | null> {
     let pointer: RemoteCachePointer;
     try {
@@ -250,11 +231,12 @@ export class ImageOptimizer {
       return { error: `"q" parameter (quality) of ${quality} is not allowed` };
     }
 
+    const accept = req.headers.get("accept") ?? "";
     return {
       href,
       width,
       quality,
-      outputType: ImageOptimizer.#getPreferredOutputType(req.headers.get("accept") ?? "", this.#config.formats),
+      outputType: this.#config.formats.find((format) => accept.includes(format)) ?? "",
       isRemote,
     };
   }
@@ -329,6 +311,7 @@ export class ImageOptimizer {
       shouldBypass || !params.outputType || inputType === ImageOptimizer.#webp || inputType === ImageOptimizer.#avif
         ? inputType
         : params.outputType;
+    const shouldEncode = !shouldBypass && ImageOptimizer.#encodableTypes.has(outputType);
     const cachePath = this.#getCachePath({
       href: params.href,
       width: params.width,
@@ -351,7 +334,7 @@ export class ImageOptimizer {
     let buffer = source.buffer;
     let contentType = inputType;
     let cacheable = true;
-    if (!shouldBypass) {
+    if (shouldEncode) {
       try {
         buffer = await this.#semaphore.run(() =>
           ImageOptimizer.#optimize(source.buffer, {
@@ -415,10 +398,6 @@ export class ImageOptimizer {
     return await image.jpeg({ quality: options.quality }).toBuffer();
   }
 
-  static #getPreferredOutputType(accept: string, formats: AkanImageFormat[]): AkanImageFormat | "" {
-    return formats.find((format) => accept.includes(format)) ?? "";
-  }
-
   static #hasRemoteMatch(patterns: AkanImagePattern[], url: URL): boolean {
     return patterns.some((pattern) => {
       if (pattern.protocol && `${pattern.protocol}:` !== url.protocol) return false;

package/server/index.ts

@@ -6,7 +6,8 @@ export * from "./artifact";
 export * from "./console";
 export * from "./decorators";
 export * from "./devtools";
-export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch";
+export type { ChangeBatch, ChangeKind } from "./hmr/wsHub";
+export * from "./nativeFile";
 export * from "./oauth";
 export * from "./processMetricsCollector";
 export * from "./proxy";

package/server/lifecycle/orphanGroup.ts

@@ -0,0 +1,21 @@
+import { SelfExec } from "../selfExec";
+
+export class OrphanGroup {
+  static exit(code: number, { leads = SelfExec.carried && process.platform !== "win32", graceMs = 1_000 } = {}) {
+    if (!leads) process.exit(code);
+    process.removeAllListeners("SIGTERM");
+    process.on("SIGTERM", () => undefined);
+    OrphanGroup.#signal("SIGTERM");
+    setTimeout(() => {
+      OrphanGroup.#signal("SIGKILL");
+      process.exit(code);
+    }, graceMs);
+  }
+
+  static #signal(signal: NodeJS.Signals) {
+    try {
+      process.kill(-process.pid, signal);
+    } catch {
+    }
+  }
+}

package/server/lifecycle/portInUse.ts

@@ -1,7 +1,4 @@
-/**
- * Detects "address already in use" listen failures across the shapes Bun throws them in
- * (`code: "EADDRINUSE"` on newer versions, message-only on older ones).
- */
+/** Bun reports EADDRINUSE as `code` on newer versions and only in the message on older ones; both count. */
 export const isPortInUseError = (error: unknown): boolean => {
   if (!error || typeof error !== "object") return false;
   const candidate = error as { code?: unknown; message?: unknown };

package/server/lifecycle/runtimeDir.ts

@@ -1,9 +1,5 @@
 import path from "node:path";
 
-/**
- * Where a replica keeps its child sockets and rotating logs. Both the gateway and a solo server resolve it,
- * and they must land on the same directory: switching between the two modes must not move the log file.
- */
 export const resolveRuntimeDir = (runtimeDir?: string): string =>
   path.resolve(
     runtimeDir ??

package/server/lifecycle/shutdownManager.ts

@@ -1,15 +1,6 @@
 import type { Logger } from "akanjs/common";
 
 export class ShutdownManager {
-  /**
-   * Registers process-level handlers that drive `onShutdown` on:
-   *   - SIGTERM / SIGINT (graceful stop → exit(0) on success, exit(1) on error)
-   *   - uncaughtException (best-effort stop → exit(1))
-   *   - unhandledRejection (logged at error, process kept alive; see `#isFatalUnhandledRejection`)
-   *
-   * Kept separate from `AkanServer` so the server class doesn't have to know about
-   * Node-level process events, and so tests can opt out by not calling it.
-   */
   static register(logger: Logger, onShutdown: () => Promise<void>): void {
     const signals: NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
 
@@ -28,34 +19,18 @@ export class ShutdownManager {
 
     process.on("uncaughtException", async (error) => {
       logger.error(`Uncaught exception: ${ShutdownManager.#formatError(error)}`);
-      try {
-        await onShutdown();
-        process.exit(1);
-      } catch {
-        process.exit(1);
-      }
+      await onShutdown().catch(() => undefined);
+      process.exit(1);
     });
 
     process.on("unhandledRejection", async (reason) => {
       logger.error(`Unhandled rejection: ${ShutdownManager.#formatError(reason)}`);
       if (!ShutdownManager.#isFatalUnhandledRejection()) return;
-      try {
-        await onShutdown();
-        process.exit(1);
-      } catch {
-        process.exit(1);
-      }
+      await onShutdown().catch(() => undefined);
+      process.exit(1);
     });
   }
 
-  /**
-   * A rejected promise nobody awaited is scoped to whatever built it, so it cannot leave the process in the
-   * unknown state an `uncaughtException` does — while exiting over one drops every other in-flight request,
-   * every websocket, and (under federation) restarts the replica. React's streaming SSR is the case that forced
-   * this: it rejects `stream.allReady` for a post-shell render failure and holds no handler of its own, so one
-   * page's boundary error used to kill a whole child. Set `AKAN_FATAL_UNHANDLED_REJECTION=1` to restore the
-   * exit for a deployment that would rather crash than serve on.
-   */
   static #isFatalUnhandledRejection(): boolean {
     const flag = process.env.AKAN_FATAL_UNHANDLED_REJECTION;
     return flag === "1" || flag === "true";

package/server/logging/childOutputReader.ts

@@ -3,9 +3,7 @@ import { Logger, type LogLevel, type LogRecord, logSeverity } from "akanjs/commo
 export type ChildOutputType = "stdout" | "stderr";
 
 export interface ChildOutputReaderOptions {
-  /** A complete stdout line, newline included. */
   onLine: (line: string) => void;
-  /** A stderr block of newline-terminated lines; one stack trace arrives as one block. */
   onBlock: (lines: string[]) => void;
   blockMaxLines?: number;
   blockIdleMs?: number;
@@ -20,11 +18,6 @@ export interface ChildRecordInput {
   pid: number | null;
 }
 
-/**
- * Splits a child process's stdout and stderr into lines. stderr is block-buffered — a runtime writes a stack
- * trace in many small writes and a reader wants it whole — and a block closes on a blank line, at
- * `blockMaxLines`, after `blockIdleMs` of silence, or when the stream ends.
- */
 export class ChildOutputReader {
   static readonly defaultBlockMaxLines = 64;
   static readonly defaultBlockIdleMs = 50;
@@ -44,10 +37,6 @@ export class ChildOutputReader {
     this.#blockIdleMs = blockIdleMs ?? ChildOutputReader.defaultBlockIdleMs;
   }
 
-  /**
-   * Wraps what a child wrote past its Logger — a `console.*` call, a runtime error, a crash — as a record of the
-   * process that read it, so an ndjson stdout stays one JSON line per event even for the line that killed a child.
-   */
   static toRecord({ type, text, name, role, replicaIdx, pid }: ChildRecordInput): LogRecord {
     const level: LogLevel = type === "stderr" ? "error" : "info";
     const at = Date.now();
@@ -98,7 +87,6 @@ export class ChildOutputReader {
     this.#partial[type] = buffered;
   }
 
-  /** Ends the stream's partial line and, for stderr, the block it belongs to. */
   flush(type: ChildOutputType) {
     const partial = this.#partial[type];
     this.#partial[type] = "";

package/server/logging/hubFileSink.ts

@@ -1,4 +1,4 @@
-import { Logger } from "akanjs/common";
+import { Logger, logSeverity } from "akanjs/common";
 import type { LogHub, LogHubEntry } from "./logHub";
 import { LogStdoutWriter } from "./logStdoutWriter";
 import type { RotatingLogWriter } from "./rotatingLogWriter";
@@ -9,11 +9,6 @@ export interface HubFileSinkOptions {
   json: boolean;
 }
 
-/**
- * The rotating log file fed from the hub instead of from this process's own Logger. In an ndjson deployment a
- * child writes no text line the owner could relay, so the file is written from the records that reached the
- * hub — every process in one place, keyed the way the text-mode files were.
- */
 export class HubFileSink {
   #subscription: { unsubscribe(): void } | null;
 
@@ -26,6 +21,15 @@ export class HubFileSink {
     });
   }
 
+  static attach(writer: RotatingLogWriter, hub: LogHub | null, label: string): () => void {
+    if (!hub || !Logger.isNdjson) return Logger.addSink((entry) => void writer.write(label, entry.plainMessage));
+    const sink = new HubFileSink(hub, writer, {
+      minSev: logSeverity[Logger.fileLevel],
+      json: Logger.format === "ndjson-only",
+    });
+    return () => sink.close();
+  }
+
   static processKey({ record }: LogHubEntry): string {
     const role = record.role ?? "app";
     if (role === "gateway" || record.replicaIdx === null) return role;

package/server/logging/logControlSocket.ts

@@ -26,13 +26,6 @@ interface ClientState {
   subscriptions: Map<string, () => void>;
 }
 
-/**
- * A unix domain socket in the runtime directory, `0600`, speaking NDJSON both ways. Filesystem permission is
- * the whole authentication: no TCP port is opened. `akan logs` and the console's `.tail` are its clients.
- *
- * Nothing in here logs per delivered record — a subscriber asking for everything would otherwise receive the
- * line about its own delivery, forever.
- */
 export class LogControlSocket {
   static readonly fileName = "akan-control.sock";
   static readonly maxPendingBytes = 1024 * 1024;
@@ -52,6 +45,19 @@ export class LogControlSocket {
     this.path = LogControlSocket.pathIn(runtimeDir);
   }
 
+  static async open(hub: LogHub, runtimeDir: string, logger: Logger): Promise<LogControlSocket | null> {
+    const control = new LogControlSocket(hub, runtimeDir);
+    try {
+      await control.start();
+      return control;
+    } catch (error) {
+      logger.warn(
+        `Log control socket unavailable at ${control.path}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return null;
+    }
+  }
+
   async start() {
     await mkdir(path.dirname(this.path), { recursive: true });
     await rm(this.path, { force: true });