akanjs 3.0.0-alpha.45 → 3.0.0-alpha.47

package/base/baseEnv.ts

@@ -73,15 +73,18 @@ export type ClientEnv = BaseEnv & {
 
 let cachedEnv: ClientEnv | undefined;
 
+const missingPublicEnv = (key: string) =>
+  `getEnv() cannot run at build time: akan build does not inject ${key}. Call it from a runtime function instead of at module scope (e.g. env(() => getEnv()) in adapt(), a method body, or a default thunk).`;
+
 /** Reads and caches Akan runtime environment values from process/browser environment settings. */
 export const getEnv = (): ClientEnv => {
   if (cachedEnv) return cachedEnv;
   const appName = process.env.AKAN_PUBLIC_APP_NAME ?? "unknown";
   const repoName = process.env.AKAN_PUBLIC_REPO_NAME ?? "unknown";
   const serveDomain = process.env.AKAN_PUBLIC_SERVE_DOMAIN ?? "unknown";
-  if (appName === "unknown") throw new Error("environment variable AKAN_PUBLIC_APP_NAME is required");
-  if (repoName === "unknown") throw new Error("environment variable AKAN_PUBLIC_REPO_NAME is required");
-  if (serveDomain === "unknown") throw new Error("environment variable AKAN_PUBLIC_SERVE_DOMAIN is required");
+  if (appName === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_APP_NAME"));
+  if (repoName === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_REPO_NAME"));
+  if (serveDomain === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_SERVE_DOMAIN"));
   const environment = (process.env.AKAN_PUBLIC_ENV ?? "debug") as BaseEnv["environment"];
   const operationMode = (process.env.AKAN_PUBLIC_OPERATION_MODE ??
     (environment === "local" ? "local" : "cloud")) as BaseEnv["operationMode"];

package/base/primitiveRegistry.ts

@@ -209,12 +209,12 @@ declare global {
     [DEFAULT_VALUE]: boolean;
     [PURIFIED_VALUE]: boolean;
     [EXAMPLE_VALUE]: boolean;
-    validate(value: boolean | number): boolean;
-    parseValue(input: boolean | number): boolean | number;
-    serializeValue(value: boolean | number): boolean | number;
-    _parse(input: boolean | number): boolean;
-    _serialize(value: boolean | number): boolean;
-    _checkValue(value: boolean | number): void;
+    validate(value: boolean | number | string): boolean;
+    parseValue(input: boolean | number | string): boolean | number | string;
+    serializeValue(value: boolean | number | string): boolean | number | string;
+    _parse(input: boolean | number | string): boolean;
+    _serialize(value: boolean | number | string): boolean;
+    _checkValue(value: boolean | number | string): void;
   }
   interface DateConstructor {
     refName: "Date";
@@ -305,10 +305,14 @@ Object.assign(String, scalarPrimitiveStatics, {
 });
 PrimitiveRegistry.register(String);
 
-const normalizeBooleanPrimitiveValue = (value: boolean | number): boolean | null => {
+const normalizeBooleanPrimitiveValue = (value: boolean | number | string): boolean | null => {
   if (typeof value === "boolean") return value;
   if (value === 1) return true;
   if (value === 0) return false;
+  if (typeof value !== "string") return null;
+  const text = value.trim().toLowerCase();
+  if (text === "true" || text === "1") return true;
+  if (text === "false" || text === "0") return false;
   return null;
 };
 
@@ -317,13 +321,13 @@ Object.assign(Boolean, {
   refName: "Boolean",
   [DEFAULT_VALUE]: false,
   [EXAMPLE_VALUE]: true,
-  validate(value: boolean | number) {
+  validate(value: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(value) !== null;
   },
-  parseValue(input: boolean | number) {
+  parseValue(input: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(input) ?? input;
   },
-  serializeValue(value: boolean | number) {
+  serializeValue(value: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(value) ?? value;
   },
 });

package/common/index.ts

@@ -45,6 +45,7 @@ export { randomPicks } from "./randomPicks";
 export {
   assertUniqueRoutePatterns,
   compareRouteSpecificity,
+  getPageSourceFileViolation,
   getRouteExports,
   isRouteSourceFile,
   isSpecialRouteLeaf,

package/common/routeConvention.ts

@@ -67,27 +67,37 @@ export function isRouteSourceFile(filePath: string): boolean {
   return tryParseRouteModuleKey(key) !== null;
 }
 
-export function validatePageSourceFile(filePath: string, options: ValidatePageSourceFileOptions = {}): boolean {
-  if (!SOURCE_EXT_RE.test(filePath)) return false;
+/**
+ * Why a `page/` file breaks the route convention, or null when it is fine. Null also covers a non-source
+ * asset, which `page/` tolerates. `akan sync <lib>` reports these alongside its other layout violations,
+ * so the rule stays in one place instead of being restated where it cannot afford to throw.
+ */
+export function getPageSourceFileViolation(filePath: string): string | null {
+  if (!SOURCE_EXT_RE.test(filePath)) return null;
 
   const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
   const match = ROUTE_SOURCE_RE.exec(key);
-  const displayPath = options.filePath ?? key;
-  if (!match) throw new Error(`[route-convention] invalid page source file: ${displayPath}`);
+  if (!match) return "invalid page source file";
 
   const file = match[1] as string;
   const ext = match[2] as string;
   const leaf = file.split("/").filter(Boolean).at(-1);
-  if (!leaf) throw new Error(`[route-convention] invalid page source file: ${displayPath}`);
+  if (!leaf) return "invalid page source file";
 
-  if (ext !== "tsx") throw new Error(`[route-convention] route source files under page/ must use .tsx: ${displayPath}`);
+  if (ext !== "tsx") return "route source files under page/ must use .tsx";
   if (leaf.startsWith("_") && !RESERVED_ROUTE_FILES.has(leaf) && leaf !== INTERNAL_ROOT_LAYOUT_LEAF)
-    throw new Error(
-      `[route-convention] only _index.tsx, _layout.tsx and _overrides.tsx are allowed as reserved route files under page/: ${displayPath}`,
-    );
-  if (/^[A-Z]/.test(leaf))
-    throw new Error(`[route-convention] route page filenames must not start with an uppercase letter: ${displayPath}`);
-  return true;
+    return "only _index.tsx, _layout.tsx and _overrides.tsx are allowed as reserved route files under page/";
+  if (/^[A-Z]/.test(leaf)) return "route page filenames must not start with an uppercase letter";
+  return null;
+}
+
+export function validatePageSourceFile(filePath: string, options: ValidatePageSourceFileOptions = {}): boolean {
+  if (!SOURCE_EXT_RE.test(filePath)) return false;
+
+  const violation = getPageSourceFileViolation(filePath);
+  if (!violation) return true;
+  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
+  throw new Error(`[route-convention] ${violation}: ${options.filePath ?? key}`);
 }
 
 export function validateSubRoutePageKey(

package/constant/via.ts

@@ -430,10 +430,14 @@ declare global {
 }
 
 const applyConstantStatics = <Model>(model: ConstantCls<Model>, fieldMap: FieldObject): ConstantCls<Model> => {
-  const defaultValue = getDefault(model[FIELD_META]);
+
+  let defaultValue: DefaultOf<Model> | undefined;
   Object.assign(model, {
     purify: makePurify(model),
-    getDefault: () => ({ ...defaultValue }),
+    getDefault: () => {
+      defaultValue ??= getDefault<Model>(model[FIELD_META]);
+      return { ...defaultValue };
+    },
   });
   Object.entries(fieldMap).forEach(([, field]) => {
     if (field.enum) model.enums.add(field.enum);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.45",
+  "version": "3.0.0-alpha.47",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -37,7 +37,6 @@ interface ChildState {
 
 interface GatewayWsData {
   childIdx: number;
-  socketId: string;
   upstream: WebSocket;
 }
 
@@ -582,8 +581,8 @@ export class AkanApp {
     const upstreamWs = new WebSocket(`ws://${upstream.host}:${upstream.port}${url.pathname}${url.search}`, {
       headers: this.#makeProxyHeaders(req, child.idx),
     } as unknown as string[]);
-    const socketId = crypto.randomUUID();
-    const upgraded = server.upgrade(req, { data: { childIdx: child.idx, socketId, upstream: upstreamWs } });
+
+    const upgraded = server.upgrade(req, { data: { childIdx: child.idx, upstream: upstreamWs } });
     if (!upgraded) {
       upstreamWs.close();
       return new Response("WebSocket upgrade failed", { status: 500 });

package/server/routing/appWsData.ts

@@ -41,10 +41,17 @@ export class AppWsData {
   account?: unknown;
   /** The `authorization` value `account` was resolved from, so each frame need not re-verify it. */
   resolvedAuthorization?: string;
-  socketId?: string;
+  /**
+   * Identity of this connection, minted here so every app socket carries one from its first frame and
+   * adaptors and endpoints only ever read it. Per-connection and process-local — a reconnect gets a new
+   * one, and the federation gateway's own socket is a different one — so it is never a caller identity.
+   * It outlives a credential swap on purpose: the socket is still the same socket.
+   */
+  socketId: string;
   constructor(headers: Headers) {
     this.createdAt = Date.now();
     this.headers = headers;
     this.cookies = new Bun.CookieMap(headers.get("cookie") ?? "");
+    this.socketId = Bun.randomUUIDv7();
   }
 }

package/service/adapt.ts

@@ -4,8 +4,8 @@ import { type ExtractInjectInfoObject, type InjectBuilder, type InjectInfo, inje
 
 export interface Adaptor {
   readonly logger: Logger;
-  onInit(): Promise<void>;
-  onDestroy(): Promise<void>;
+  onInit(): Promise<void> | void;
+  onDestroy(): Promise<void> | void;
 }
 
 export type AdaptorCls<
@@ -30,9 +30,9 @@ export function adapt(name: string, injectBuilder?: InjectBuilder) {
     readonly logger = new Logger(name);
     static readonly [INJECT_META] = injectInfoMap;
     static readonly refName = name;
-    async onInit() {
+    onInit(): Promise<void> | void {
     }
-    async onDestroy() {
+    onDestroy(): Promise<void> | void {
     }
   }
   return Adaptor;

package/service/predefinedAdaptor/solidPubsub.adaptor.ts

@@ -3,9 +3,13 @@ import { adapt } from "../adapt";
 import { sendAkanIpc } from "../ipcTypes";
 import type { WebsocketAdaptor, WsRedisEventHandler, WsSocketData } from "./websocket.adaptor";
 
-const getSocketId = (ws: Bun.ServerWebSocket<unknown>, serverId: string) => {
+/**
+ * `AppWsData` mints the id at the handshake, so this reads it; the fallback only covers a socket that
+ * was upgraded outside the app router, where nothing else would have given it one.
+ */
+const getSocketId = (ws: Bun.ServerWebSocket<unknown>) => {
   const data = ws.data as WsSocketData;
-  if (!data.socketId) data.socketId = `${serverId}-${Bun.randomUUIDv7()}`;
+  data.socketId ??= Bun.randomUUIDv7();
   return data.socketId;
 };
 
@@ -64,7 +68,7 @@ export class SolidPubSub
   }
 
   async joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void> {
-    const socketId = getSocketId(ws, this.serverId);
+    const socketId = getSocketId(ws);
     const rooms = this.#socketRooms.get(socketId) ?? new Set<string>();
     rooms.add(room);
     this.#socketRooms.set(socketId, rooms);
@@ -72,7 +76,7 @@ export class SolidPubSub
   }
 
   async leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void> {
-    const socketId = getSocketId(ws, this.serverId);
+    const socketId = getSocketId(ws);
     const rooms = this.#socketRooms.get(socketId);
     rooms?.delete(room);
     if (!rooms || rooms.size === 0) this.#socketRooms.delete(socketId);
@@ -80,7 +84,7 @@ export class SolidPubSub
   }
 
   async leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void> {
-    const socketId = getSocketId(ws, this.serverId);
+    const socketId = getSocketId(ws);
     const rooms = this.#socketRooms.get(socketId);
     if (rooms) {
       for (const room of rooms) sendAkanIpc({ type: "pubsub.unsubscribe", roomId: room, socketId, pid: process.pid });
@@ -89,7 +93,7 @@ export class SolidPubSub
   }
 
   async registerSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void> {
-    getSocketId(ws, this.serverId);
+    getSocketId(ws);
   }
 
   async unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void> {

package/service/predefinedAdaptor/websocket.adaptor.ts

@@ -209,9 +209,14 @@ export class WebSocketRedisAdaptor
     await pipeline.exec();
   }
 
+  /**
+   * `AppWsData` mints the id at the handshake, so this reads it; the fallback only covers a socket that
+   * was upgraded outside the app router. The owning server is recorded in the socket hash below, so the
+   * id itself carries no prefix.
+   */
   #getSocketId(ws: Bun.ServerWebSocket<unknown>): string {
     const data = ws.data as WsSocketData;
-    if (!data.socketId) data.socketId = `${this.serverId}-${Bun.randomUUIDv7()}`;
+    data.socketId ??= Bun.randomUUIDv7();
     return data.socketId;
   }
 

package/service/serve.ts

@@ -12,7 +12,7 @@ import {
 import type { DatabaseService, DatabaseServiceForModel } from "./types";
 
 interface ServiceOptions {
-  enabled?: boolean;
+  enabled?: boolean | (() => boolean);
   serverMode?: "batch" | "federation";
 }
 export type ServiceType = "database" | "plain";
@@ -43,9 +43,9 @@ const avoidKeys = new Set([
 export interface Service {
   readonly logger: Logger;
   
-  onInit(): Promise<void>;
+  onInit(): Promise<void> | void;
   _libsOnInit(): Promise<void>;
-  onDestroy(): Promise<void>;
+  onDestroy(): Promise<void> | void;
   _libsOnDestroy(): Promise<void>;
 }
 
@@ -102,9 +102,10 @@ export function serve(
     ...(typeof optionOrInjectBuilder === "function" && injectBuilderOrExtendSrv ? [injectBuilderOrExtendSrv] : []),
     ...extendSrvs,
   ] as ServiceCls[];
-  const isEnabled =
+  const enabledOption =
     option.enabled ??
     (!option.serverMode || process.env.SERVER_MODE === option.serverMode || process.env.SERVER_MODE === "all");
+  let enabledCache: boolean | undefined;
   const serviceType = typeof refNameOrDb === "string" ? "plain" : "database";
   const injectInfoMap = injectBuilder(injectionBuilder(refName));
   if (serviceType === "database")
@@ -115,15 +116,20 @@ export function serve(
   const srvRef = class Service {
     static readonly type = serviceType;
     static readonly refName = refName;
-    static enabled = isEnabled;
+    static get enabled() {
+      
+      if (enabledCache === undefined)
+        enabledCache = typeof enabledOption === "function" ? enabledOption() : enabledOption;
+      return enabledCache;
+    }
     static get name() {
       return `${capitalize(refName)}Service`;
     }
     static [INJECT_META] = {};
     readonly logger = new Logger(this.constructor.name);
-    async onInit() {
+    onInit(): Promise<void> | void {
     }
-    async onDestroy() {
+    onDestroy(): Promise<void> | void {
     }
   };
   applyMixins(srvRef, extSrvs, avoidKeys);
@@ -132,10 +138,11 @@ export function serve(
   const onDestroyFns = extSrvs.map((srv) => srv.prototype.onDestroy);
   Object.assign(srvRef.prototype, {
     async _libsOnInit(this: Service) {
-      await Promise.all([...onInitFns.map((onInit) => onInit?.call(this)), this.onInit()]);
+      
+      await Promise.all([...onInitFns, this.onInit].map(async (onInit) => await onInit?.call(this)));
     },
     async _libsOnDestroy(this: Service) {
-      await Promise.all([...onDestroyFns.map((onDestroy) => onDestroy?.call(this)), this.onDestroy()]);
+      await Promise.all([...onDestroyFns, this.onDestroy].map(async (onDestroy) => await onDestroy?.call(this)));
     },
   });
 

package/signal/intercept.ts

@@ -7,8 +7,8 @@ export type InterceptorCls<Methods = {}, InjectMap extends { [key: string]: Inje
   Methods &
     ExtractInjectInfoObject<InjectMap> & {
       readonly logger: Logger;
-      onInit(): Promise<void>;
-      onDestroy(): Promise<void>;
+      onInit(): Promise<void> | void;
+      onDestroy(): Promise<void> | void;
       intercept(context: SignalContext): AsyncGenerator<unknown> | Promise<unknown>;
     },
   { readonly [INJECT_META]: InjectMap; readonly refName: string }
@@ -31,9 +31,9 @@ export function intercept(refName: string, injectBuilder?: InjectBuilder) {
     intercept(context: SignalContext): AsyncGenerator | Promise<(res: Response) => Promise<Response>> {
       return Promise.resolve((res: Response) => Promise.resolve(res));
     }
-    async onInit() {
+    onInit(): Promise<void> | void {
     }
-    async onDestroy() {
+    onDestroy(): Promise<void> | void {
     }
   };
 }

package/signal/internalArg.ts

@@ -21,15 +21,20 @@ export class Res implements InternalArg {
   }
 }
 
-/** Injects websocket state and subscription hooks into message/pubsub handlers. */
+/**
+ * Injects websocket state, this connection's id, and subscription hooks into message/pubsub handlers.
+ * `socketId` is the one `AppWsData` minted at the handshake, so a handler never reads `ws.data` to
+ * tell two callers apart — and never mints an id of its own, which would not match the room bookkeeping.
+ */
 export class Ws implements InternalArg {
   onDisconnect?: () => void;
   onUnsubscribe?: () => void;
   getArg(context: SignalContext) {
-    const webSocketContext = context.getWebSocketContext();
+    const webSocketContext = context.getWebSocketContext<{ socketId: string }>();
     const ws = webSocketContext.ws;
     return {
       ws,
+      socketId: ws.data.socketId,
       subscribe: webSocketContext.eventType === "subscribe",
       on: webSocketContext.on,
       off: webSocketContext.off,

package/types/base/primitiveRegistry.d.ts

@@ -114,12 +114,12 @@ declare global {
         [DEFAULT_VALUE]: boolean;
         [PURIFIED_VALUE]: boolean;
         [EXAMPLE_VALUE]: boolean;
-        validate(value: boolean | number): boolean;
-        parseValue(input: boolean | number): boolean | number;
-        serializeValue(value: boolean | number): boolean | number;
-        _parse(input: boolean | number): boolean;
-        _serialize(value: boolean | number): boolean;
-        _checkValue(value: boolean | number): void;
+        validate(value: boolean | number | string): boolean;
+        parseValue(input: boolean | number | string): boolean | number | string;
+        serializeValue(value: boolean | number | string): boolean | number | string;
+        _parse(input: boolean | number | string): boolean;
+        _serialize(value: boolean | number | string): boolean;
+        _checkValue(value: boolean | number | string): void;
     }
     interface DateConstructor {
         refName: "Date";

package/types/common/index.d.ts

@@ -24,7 +24,7 @@ export { pathGet } from "./pathGet.d.ts";
 export { pathSet } from "./pathSet.d.ts";
 export { randomPick } from "./randomPick.d.ts";
 export { randomPicks } from "./randomPicks.d.ts";
-export { assertUniqueRoutePatterns, compareRouteSpecificity, getRouteExports, isRouteSourceFile, isSpecialRouteLeaf, LAYOUT_ROUTE_EXPORTS, matchRoutePattern, normalizeRoutePattern, PAGE_ROUTE_EXPORTS, type ParsedRouteModuleKey, parseRouteModuleKey, RESERVED_ROUTE_CONFIG_EXPORTS, ROOT_LAYOUT_ROUTE_EXPORTS, type RouteModuleKind, routeSegmentToPatternPart, routeSegmentToTreePath, tryParseRouteModuleKey, type ValidatePageSourceFileOptions, type ValidateSubRoutePageKeyOptions, validatePageSourceFile, validateSubRoutePageKey, } from "./routeConvention.d.ts";
+export { assertUniqueRoutePatterns, compareRouteSpecificity, getPageSourceFileViolation, getRouteExports, isRouteSourceFile, isSpecialRouteLeaf, LAYOUT_ROUTE_EXPORTS, matchRoutePattern, normalizeRoutePattern, PAGE_ROUTE_EXPORTS, type ParsedRouteModuleKey, parseRouteModuleKey, RESERVED_ROUTE_CONFIG_EXPORTS, ROOT_LAYOUT_ROUTE_EXPORTS, type RouteModuleKind, routeSegmentToPatternPart, routeSegmentToTreePath, tryParseRouteModuleKey, type ValidatePageSourceFileOptions, type ValidateSubRoutePageKeyOptions, validatePageSourceFile, validateSubRoutePageKey, } from "./routeConvention.d.ts";
 export { sleep } from "./sleep.d.ts";
 export { splitVersion } from "./splitVersion.d.ts";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute.d.ts";

package/types/common/routeConvention.d.ts

@@ -27,6 +27,12 @@ export interface ValidatePageSourceFileOptions {
     filePath?: string;
 }
 export declare function isRouteSourceFile(filePath: string): boolean;
+/**
+ * Why a `page/` file breaks the route convention, or null when it is fine. Null also covers a non-source
+ * asset, which `page/` tolerates. `akan sync <lib>` reports these alongside its other layout violations,
+ * so the rule stays in one place instead of being restated where it cannot afford to throw.
+ */
+export declare function getPageSourceFileViolation(filePath: string): string | null;
 export declare function validatePageSourceFile(filePath: string, options?: ValidatePageSourceFileOptions): boolean;
 export declare function validateSubRoutePageKey(key: string, basePaths: Iterable<string>, options?: ValidateSubRoutePageKeyOptions): void;
 export declare function parseRouteModuleKey(key: string): ParsedRouteModuleKey;

package/types/server/routing/appWsData.d.ts

@@ -19,6 +19,12 @@ export declare class AppWsData {
     account?: unknown;
     /** The `authorization` value `account` was resolved from, so each frame need not re-verify it. */
     resolvedAuthorization?: string;
-    socketId?: string;
+    /**
+     * Identity of this connection, minted here so every app socket carries one from its first frame and
+     * adaptors and endpoints only ever read it. Per-connection and process-local — a reconnect gets a new
+     * one, and the federation gateway's own socket is a different one — so it is never a caller identity.
+     * It outlives a credential swap on purpose: the socket is still the same socket.
+     */
+    socketId: string;
     constructor(headers: Headers);
 }

package/types/service/adapt.d.ts

@@ -3,8 +3,8 @@ import { Logger } from "akanjs/common";
 import { type ExtractInjectInfoObject, type InjectBuilder, type InjectInfo } from "./injectInfo.d.ts";
 export interface Adaptor {
     readonly logger: Logger;
-    onInit(): Promise<void>;
-    onDestroy(): Promise<void>;
+    onInit(): Promise<void> | void;
+    onDestroy(): Promise<void> | void;
 }
 export type AdaptorCls<Methods = any, InjectMap extends Record<string, InjectInfo> = {}> = Cls<Methods & ExtractInjectInfoObject<InjectMap> & Adaptor, {
     readonly [INJECT_META]: InjectMap;

package/types/service/serve.d.ts

@@ -4,15 +4,15 @@ import type { DatabaseModel } from "akanjs/document";
 import { type ExtractInjectInfoObject, type InjectBuilder, InjectInfo } from "./injectInfo.d.ts";
 import type { DatabaseServiceForModel } from "./types.d.ts";
 interface ServiceOptions {
-    enabled?: boolean;
+    enabled?: boolean | (() => boolean);
     serverMode?: "batch" | "federation";
 }
 export type ServiceType = "database" | "plain";
 export interface Service {
     readonly logger: Logger;
-    onInit(): Promise<void>;
+    onInit(): Promise<void> | void;
     _libsOnInit(): Promise<void>;
-    onDestroy(): Promise<void>;
+    onDestroy(): Promise<void> | void;
     _libsOnDestroy(): Promise<void>;
 }
 export type ServiceCls<RefName extends string = string, Methods = {}, InjectMap extends {

package/types/signal/intercept.d.ts

@@ -6,8 +6,8 @@ export type InterceptorCls<Methods = {}, InjectMap extends {
     [key: string]: InjectInfo;
 } = {}> = Cls<Methods & ExtractInjectInfoObject<InjectMap> & {
     readonly logger: Logger;
-    onInit(): Promise<void>;
-    onDestroy(): Promise<void>;
+    onInit(): Promise<void> | void;
+    onDestroy(): Promise<void> | void;
     intercept(context: SignalContext): AsyncGenerator<unknown> | Promise<unknown>;
 }, {
     readonly [INJECT_META]: InjectMap;

package/types/signal/internalArg.d.ts

@@ -18,12 +18,19 @@ export declare class Res implements InternalArg {
         redirect(url: string | URL, status?: number): Response;
     };
 }
-/** Injects websocket state and subscription hooks into message/pubsub handlers. */
+/**
+ * Injects websocket state, this connection's id, and subscription hooks into message/pubsub handlers.
+ * `socketId` is the one `AppWsData` minted at the handshake, so a handler never reads `ws.data` to
+ * tell two callers apart — and never mints an id of its own, which would not match the room bookkeeping.
+ */
 export declare class Ws implements InternalArg {
     onDisconnect?: () => void;
     onUnsubscribe?: () => void;
     getArg(context: SignalContext): {
-        ws: Bun.ServerWebSocket<unknown>;
+        ws: Bun.ServerWebSocket<{
+            socketId: string;
+        }>;
+        socketId: string;
         subscribe: boolean;
         on: (event: "disconnect" | "unsubscribe", handler: () => void) => void;
         off: (event: "disconnect" | "unsubscribe", handler: () => void) => void;