@lenne.tech/nest-server 11.31.2 → 11.32.0

package/src/core/modules/hub/hub-config.helper.spec.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+
+import { isHubEnabled, isHubQueriesEnabled, normalizeHubConfig } from './hub-config.helper';
+
+describe('hub-config.helper', () => {
+  describe('isHubEnabled', () => {
+    it('is disabled by default (undefined)', () => {
+      expect(isHubEnabled(undefined)).toBe(false);
+      expect(isHubEnabled(false)).toBe(false);
+    });
+
+    it('is enabled for true / {} / a config object', () => {
+      expect(isHubEnabled(true)).toBe(true);
+      expect(isHubEnabled({})).toBe(true);
+      expect(isHubEnabled({ path: 'x' })).toBe(true);
+    });
+
+    it('respects explicit { enabled: false }', () => {
+      expect(isHubEnabled({ enabled: false, path: 'x' })).toBe(false);
+    });
+  });
+
+  describe('isHubQueriesEnabled', () => {
+    it('is off by default even when the hub is enabled', () => {
+      expect(isHubQueriesEnabled(true)).toBe(false);
+      expect(isHubQueriesEnabled({})).toBe(false);
+    });
+
+    it('is on when queries collector is explicitly enabled', () => {
+      expect(isHubQueriesEnabled({ collectors: { queries: true } })).toBe(true);
+      expect(isHubQueriesEnabled({ collectors: { queries: { warnMs: 5 } } })).toBe(true);
+      expect(isHubQueriesEnabled({ collectors: { queries: { enabled: false } } })).toBe(false);
+    });
+
+    it('is off when the hub itself is disabled', () => {
+      expect(isHubQueriesEnabled(false)).toBe(false);
+      expect(isHubQueriesEnabled({ collectors: { queries: true }, enabled: false })).toBe(false);
+    });
+  });
+
+  describe('normalizeHubConfig', () => {
+    it('applies defaults for the boolean-true form', () => {
+      const cfg = normalizeHubConfig(true, { env: 'local', version: '1.2.3' });
+
+      expect(cfg.path).toBe('hub');
+      expect(cfg.roles).toEqual(['admin']);
+      expect(cfg.actions).toBe(true);
+      expect(cfg.pollIntervalMs).toBe(5000);
+      expect(cfg.env).toBe('local');
+      expect(cfg.version).toBe('1.2.3');
+      // Default collectors: logs + traces on, queries off.
+      expect(cfg.collectors.logs).not.toBe(false);
+      expect(cfg.collectors.traces).not.toBe(false);
+      expect(cfg.collectors.queries).toBe(false);
+    });
+
+    it('clamps the poll interval to the minimum', () => {
+      const cfg = normalizeHubConfig({ pollIntervalMs: 10 }, { env: 'local', version: '1' });
+      expect(cfg.pollIntervalMs).toBe(1000);
+    });
+
+    it('normalizes a single role string to an array', () => {
+      const cfg = normalizeHubConfig({ roles: 'S_USER' }, { env: 'local', version: '1' });
+      expect(cfg.roles).toEqual(['S_USER']);
+    });
+
+    it('keeps roles: false (opt-out of auth)', () => {
+      const cfg = normalizeHubConfig({ roles: false }, { env: 'local', version: '1' });
+      expect(cfg.roles).toBe(false);
+    });
+
+    it('resolves the queries collector with thresholds when enabled', () => {
+      const cfg = normalizeHubConfig({ collectors: { queries: { warnMs: 5 } } }, { env: 'local', version: '1' });
+      expect(cfg.collectors.queries).not.toBe(false);
+      if (cfg.collectors.queries) {
+        expect(cfg.collectors.queries.warnMs).toBe(5);
+        expect(cfg.collectors.queries.criticalMs).toBe(200);
+        expect(cfg.collectors.queries.capacity).toBe(500);
+      }
+    });
+
+    it('defaults the mailbox to disabled but enables it with capture mode when present', () => {
+      expect(normalizeHubConfig({}, { env: 'local', version: '1' }).mailbox).toBe(false);
+
+      const cfg = normalizeHubConfig({ mailbox: true }, { env: 'local', version: '1' });
+      expect(cfg.mailbox).not.toBe(false);
+      if (cfg.mailbox) {
+        expect(cfg.mailbox.mode).toBe('capture');
+        expect(cfg.mailbox.capacity).toBe(100);
+      }
+    });
+
+    it('resolves default external links', () => {
+      const cfg = normalizeHubConfig(
+        {},
+        { env: 'local', graphQlEnabled: true, permissionsPath: 'permissions', version: '1' },
+      );
+      expect(cfg.links.swagger).toBe('/swagger');
+      expect(cfg.links.graphql).toBe('/graphql');
+      expect(cfg.links.permissions).toBe('/permissions');
+    });
+
+    it('omits the graphql link when GraphQL is disabled', () => {
+      const cfg = normalizeHubConfig({}, { env: 'local', graphQlEnabled: false, version: '1' });
+      expect(cfg.links.graphql).toBeUndefined();
+    });
+  });
+});

package/src/core/modules/hub/hub-config.helper.ts

@@ -0,0 +1,233 @@
+import { RoleEnum } from '../../common/enums/role.enum';
+import { getVersion } from '../../common/helpers/meta.helper';
+
+import {
+  HUB_DEFAULT_LOG_CAPACITY,
+  HUB_DEFAULT_LOG_MAX_MESSAGE_LENGTH,
+  HUB_DEFAULT_MAILBOX_CAPACITY,
+  HUB_DEFAULT_MAILBOX_MAX_MAIL_SIZE,
+  HUB_DEFAULT_MIGRATIONS_COLLECTION,
+  HUB_DEFAULT_MIGRATIONS_DIR,
+  HUB_DEFAULT_PATH,
+  HUB_DEFAULT_POLL_INTERVAL_MS,
+  HUB_DEFAULT_QUERY_CAPACITY,
+  HUB_DEFAULT_QUERY_CRITICAL_MS,
+  HUB_DEFAULT_QUERY_MAX_SHAPE_LENGTH,
+  HUB_DEFAULT_QUERY_WARN_MS,
+  HUB_DEFAULT_TRACE_CAPACITY,
+  HUB_DEFAULT_TRACE_SLOW_MS,
+  HUB_MIN_POLL_INTERVAL_MS,
+} from './hub.constants';
+import {
+  IHubConfig,
+  IHubLogsConfig,
+  IHubMailboxConfig,
+  IHubQueriesConfig,
+  IHubTracesConfig,
+  ResolvedHubConfig,
+} from './interfaces/hub-config.interface';
+
+/** Context needed to resolve environment-dependent defaults (env badge, links, mailbox guard). */
+export interface HubConfigContext {
+  env: string;
+  graphQlEnabled?: boolean;
+  permissionsPath?: string;
+  version: string;
+}
+
+/**
+ * Environments treated as NON-reachable (local dev / test / CI). These are the ONLY envs where a
+ * public Hub (`roles: false`) or mailbox `capture` mode are allowed without an explicit acknowledgment.
+ * Everything else is treated as reachable — fail-safe by design, so a custom prod-like env name
+ * (`prod`, `live`, `preprod`, `production-eu`, `staging-2`, …) cannot bypass the startup guards.
+ */
+const NON_REACHABLE_ENVS = new Set(['ci', 'development', 'e2e', 'local', 'test']);
+
+/** True when `env` is a reachable/deployed environment (anything not in the known non-reachable set). */
+export function isReachableEnv(env: string | undefined): boolean {
+  return !NON_REACHABLE_ENVS.has((env ?? '').toLowerCase());
+}
+
+/** True when the Hub should be registered (presence implies enabled, unless `{ enabled: false }`). */
+export function isHubEnabled(config: boolean | IHubConfig | undefined): boolean {
+  if (config === true) {
+    return true;
+  }
+  if (config === false || config === undefined || config === null) {
+    return false;
+  }
+  return config.enabled !== false;
+}
+
+/** True when the query profiler is active — gates the `monitorCommands` opt-in in core.module.ts. */
+export function isHubQueriesEnabled(config: boolean | IHubConfig | undefined): boolean {
+  if (!isHubEnabled(config) || typeof config !== 'object') {
+    return false;
+  }
+  return isCollectorEnabled(config.collectors?.queries);
+}
+
+/**
+ * Resolve `boolean | IHubConfig` into a fully-defaulted {@link ResolvedHubConfig}.
+ * The result is bound to the `HUB_CONFIG` token and injected throughout the module.
+ */
+export function normalizeHubConfig(config: boolean | IHubConfig, ctx: HubConfigContext): ResolvedHubConfig {
+  const cfg: IHubConfig = typeof config === 'object' && config !== null ? config : {};
+
+  return {
+    actions: cfg.actions !== false,
+    allowPublicAccessInProduction: cfg.allowPublicAccessInProduction === true,
+    collectors: {
+      logs: resolveLogsCollector(cfg.collectors?.logs, true),
+      queries: resolveQueriesCollector(cfg.collectors?.queries, false),
+      traces: resolveTracesCollector(cfg.collectors?.traces, true),
+    },
+    db:
+      cfg.db === false
+        ? false
+        : { includeIndexes: typeof cfg.db === 'object' ? cfg.db.includeIndexes === true : false },
+    emailPreview: cfg.emailPreview !== false,
+    env: ctx.env,
+    links: resolveLinks(cfg.links, ctx),
+    loginEndpoint: cfg.loginEndpoint ?? '/iam/sign-in/email',
+    logoutEndpoint: cfg.logoutEndpoint ?? '/iam/sign-out',
+    mailbox: resolveMailbox(cfg.mailbox),
+    migrations: resolveMigrations(cfg.migrations),
+    path: sanitizePath(cfg.path) || HUB_DEFAULT_PATH,
+    pollIntervalMs: Math.max(HUB_MIN_POLL_INTERVAL_MS, cfg.pollIntervalMs ?? HUB_DEFAULT_POLL_INTERVAL_MS),
+    roles: resolveRoles(cfg.roles),
+    // Prefer an explicit version; otherwise read it from package.json (same source as getBuildInfo).
+    version: ctx.version && ctx.version !== 'unknown' ? ctx.version : getVersion(),
+  };
+}
+
+function isCollectorEnabled(value: boolean | { enabled?: boolean } | undefined, defaultOn = false): boolean {
+  if (value === undefined) {
+    return defaultOn;
+  }
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  return value.enabled !== false;
+}
+
+function resolveLinks(links: IHubConfig['links'], ctx: HubConfigContext): ResolvedHubConfig['links'] {
+  const out: ResolvedHubConfig['links'] = {};
+
+  const swagger = links?.swagger;
+  if (swagger !== false) {
+    out.swagger = typeof swagger === 'string' ? swagger : '/swagger';
+  }
+
+  const graphql = links?.graphql;
+  if (graphql === false) {
+    // explicitly hidden
+  } else if (typeof graphql === 'string') {
+    out.graphql = graphql;
+  } else if (ctx.graphQlEnabled !== false) {
+    out.graphql = '/graphql';
+  }
+
+  const permissions = links?.permissions;
+  if (permissions === false) {
+    // explicitly hidden
+  } else if (typeof permissions === 'string') {
+    out.permissions = permissions;
+  } else if (ctx.permissionsPath) {
+    out.permissions = '/' + ctx.permissionsPath.replace(/^\/+/, '');
+  }
+
+  if (links?.mailpit) {
+    out.mailpit = links.mailpit;
+  }
+
+  return out;
+}
+
+function resolveLogsCollector(
+  value: boolean | IHubLogsConfig | undefined,
+  defaultOn: boolean,
+): ResolvedHubConfig['collectors']['logs'] {
+  if (!isCollectorEnabled(value, defaultOn)) {
+    return false;
+  }
+  const obj: IHubLogsConfig = typeof value === 'object' ? value : {};
+  return {
+    capacity: obj.capacity ?? HUB_DEFAULT_LOG_CAPACITY,
+    excludeContexts: obj.excludeContexts ?? [],
+    levels: obj.levels ?? ['log', 'warn', 'error', 'fatal'],
+    maxMessageLength: obj.maxMessageLength ?? HUB_DEFAULT_LOG_MAX_MESSAGE_LENGTH,
+  };
+}
+
+function resolveMailbox(value: boolean | IHubMailboxConfig | undefined): ResolvedHubConfig['mailbox'] {
+  if (!isCollectorEnabled(value, false)) {
+    return false;
+  }
+  const obj: IHubMailboxConfig = typeof value === 'object' ? value : {};
+  return {
+    capacity: obj.capacity ?? HUB_DEFAULT_MAILBOX_CAPACITY,
+    maxMailSize: obj.maxMailSize ?? HUB_DEFAULT_MAILBOX_MAX_MAIL_SIZE,
+    mode: obj.mode === 'copy' ? 'copy' : 'capture',
+  };
+}
+
+function resolveMigrations(value: false | IHubConfig['migrations']): ResolvedHubConfig['migrations'] {
+  if (value === false) {
+    return false;
+  }
+  const obj = typeof value === 'object' && value ? value : {};
+  return {
+    collectionName: obj.collectionName ?? HUB_DEFAULT_MIGRATIONS_COLLECTION,
+    dir: obj.dir ?? HUB_DEFAULT_MIGRATIONS_DIR,
+    lockCollectionName: obj.lockCollectionName,
+  };
+}
+
+function resolveQueriesCollector(
+  value: boolean | IHubQueriesConfig | undefined,
+  defaultOn: boolean,
+): ResolvedHubConfig['collectors']['queries'] {
+  if (!isCollectorEnabled(value, defaultOn)) {
+    return false;
+  }
+  const obj: IHubQueriesConfig = typeof value === 'object' ? value : {};
+  return {
+    capacity: obj.capacity ?? HUB_DEFAULT_QUERY_CAPACITY,
+    criticalMs: obj.criticalMs ?? HUB_DEFAULT_QUERY_CRITICAL_MS,
+    ignoreCommands: obj.ignoreCommands,
+    maxShapeLength: obj.maxShapeLength ?? HUB_DEFAULT_QUERY_MAX_SHAPE_LENGTH,
+    warnMs: obj.warnMs ?? HUB_DEFAULT_QUERY_WARN_MS,
+  };
+}
+
+function resolveRoles(roles: IHubConfig['roles']): false | string[] {
+  if (roles === false) {
+    return false;
+  }
+  if (roles === undefined) {
+    return [RoleEnum.ADMIN];
+  }
+  return Array.isArray(roles) ? roles : [roles];
+}
+
+function resolveTracesCollector(
+  value: boolean | IHubTracesConfig | undefined,
+  defaultOn: boolean,
+): ResolvedHubConfig['collectors']['traces'] {
+  if (!isCollectorEnabled(value, defaultOn)) {
+    return false;
+  }
+  const obj: IHubTracesConfig = typeof value === 'object' ? value : {};
+  return {
+    capacity: obj.capacity ?? HUB_DEFAULT_TRACE_CAPACITY,
+    captureGraphQlOperation: obj.captureGraphQlOperation !== false,
+    excludePaths: obj.excludePaths ?? ['/hub'],
+    slowMs: obj.slowMs ?? HUB_DEFAULT_TRACE_SLOW_MS,
+  };
+}
+
+/** Strip leading/trailing slashes so the path composes cleanly with `Reflect.defineMetadata`. */
+function sanitizePath(path: string | undefined): string {
+  return (path ?? '').replace(/^\/+|\/+$/g, '');
+}

package/src/core/modules/hub/hub-nav.ts

@@ -0,0 +1,66 @@
+/**
+ * Single source of truth for the Hub's panels: id, route sub-path, title, sidebar group and the
+ * JSON sidecar the client polls. The HTML shell renders the sidebar from this list; the client
+ * runtime routes and renders from the same list (embedded into the shell).
+ *
+ * Pure data — no imports — so both the server shell builder and the client-JS string can share it.
+ */
+
+export type HubPanelGroup = 'Overview' | 'Runtime' | 'Data' | 'API & Docs';
+
+export interface HubPanel {
+  /** Sidebar group. */
+  readonly group: HubPanelGroup;
+  /** Stable id (also the client router key). */
+  readonly id: string;
+  /** Sidecar sub-path relative to the base path (e.g. 'dashboard.json'). Empty when the panel has none. */
+  readonly json: string;
+  /** Whether the panel depends on an optional source and may render an "unavailable" state. */
+  readonly optional?: boolean;
+  /** Route sub-path relative to the base path (''=dashboard root). */
+  readonly path: string;
+  /** Human-readable title. */
+  readonly title: string;
+}
+
+export const HUB_PANELS: readonly HubPanel[] = [
+  { group: 'Overview', id: 'dashboard', json: 'dashboard.json', path: '', title: 'Dashboard' },
+  { group: 'Overview', id: 'diagnostics', json: 'diagnostics.json', path: 'diagnostics', title: 'Diagnostics' },
+  { group: 'Runtime', id: 'logs', json: 'logs.json', path: 'logs', title: 'Logs' },
+  { group: 'Runtime', id: 'traces', json: 'traces.json', path: 'traces', title: 'Request Traces' },
+  { group: 'Runtime', id: 'queries', json: 'queries.json', path: 'queries', title: 'Query Performance' },
+  { group: 'Runtime', id: 'cron', json: 'cron.json', optional: true, path: 'cron', title: 'Cron Jobs' },
+  { group: 'Data', id: 'db', json: 'db.json', path: 'db', title: 'Database' },
+  { group: 'Data', id: 'models', json: 'models.json', path: 'models', title: 'Models / ERD' },
+  { group: 'Data', id: 'migrations', json: 'migrations.json', path: 'migrations', title: 'Migrations' },
+  { group: 'Data', id: 'files', json: 'files.json', path: 'files', title: 'Files' },
+  { group: 'Data', id: 'config', json: 'config.json', path: 'config', title: 'Config' },
+  {
+    group: 'Data',
+    id: 'auth-migration',
+    json: 'auth-migration.json',
+    optional: true,
+    path: 'auth-migration',
+    title: 'Auth Migration',
+  },
+  {
+    group: 'API & Docs',
+    id: 'routes',
+    json: 'routes.json',
+    optional: true,
+    path: 'routes',
+    title: 'Routes / Permissions',
+  },
+  { group: 'API & Docs', id: 'error-codes', json: 'error-codes.json', path: 'error-codes', title: 'Error Codes' },
+  { group: 'API & Docs', id: 'emails', json: 'emails.json', path: 'emails', title: 'Email Preview' },
+  { group: 'API & Docs', id: 'mailbox', json: 'mailbox.json', optional: true, path: 'mailbox', title: 'Mailbox' },
+  { group: 'API & Docs', id: 'ai', json: 'ai.json', optional: true, path: 'ai', title: 'AI' },
+] as const;
+
+export const HUB_PANEL_GROUPS: readonly HubPanelGroup[] = ['Overview', 'Runtime', 'Data', 'API & Docs'];
+
+/** Find the panel that a given route sub-path renders. */
+export function findHubPanelByPath(subPath: string): HubPanel | undefined {
+  const normalized = subPath.replace(/^\/+|\/+$/g, '');
+  return HUB_PANELS.find((panel) => panel.path === normalized);
+}

package/src/core/modules/hub/hub-ring-buffer.spec.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+
+import { HubRingBuffer } from './hub-ring-buffer';
+
+interface TestEntry {
+  seq: number;
+  timestamp: number;
+  value: string;
+}
+
+describe('HubRingBuffer', () => {
+  it('assigns monotonic sequence numbers and a timestamp', () => {
+    const buffer = new HubRingBuffer<TestEntry>(3);
+    const a = buffer.add({ value: 'a' });
+    const b = buffer.add({ value: 'b' });
+
+    expect(a.seq).toBe(0);
+    expect(b.seq).toBe(1);
+    expect(typeof a.timestamp).toBe('number');
+    expect(b.seq).toBeGreaterThan(a.seq);
+  });
+
+  it('honors an explicitly provided timestamp', () => {
+    const buffer = new HubRingBuffer<TestEntry>(3);
+    const entry = buffer.add({ timestamp: 123456, value: 'a' });
+
+    expect(entry.timestamp).toBe(123456);
+  });
+
+  it('evicts the oldest entries once capacity is exceeded (fixed memory)', () => {
+    const buffer = new HubRingBuffer<TestEntry>(3);
+    for (const value of ['a', 'b', 'c', 'd', 'e']) {
+      buffer.add({ value });
+    }
+
+    const items = buffer.recent();
+    expect(items.map((i) => i.value)).toEqual(['c', 'd', 'e']);
+    expect(buffer.size).toBe(3);
+  });
+
+  it('recent(limit) returns the newest N entries, oldest→newest', () => {
+    const buffer = new HubRingBuffer<TestEntry>(5);
+    for (const value of ['a', 'b', 'c', 'd']) {
+      buffer.add({ value });
+    }
+
+    expect(buffer.recent(2).map((i) => i.value)).toEqual(['c', 'd']);
+  });
+
+  it('since(seq) returns only entries newer than the cursor', () => {
+    const buffer = new HubRingBuffer<TestEntry>(10);
+    buffer.add({ value: 'a' }); // seq 0
+    const b = buffer.add({ value: 'b' }); // seq 1
+    buffer.add({ value: 'c' }); // seq 2
+
+    expect(buffer.since(b.seq).map((i) => i.value)).toEqual(['c']);
+    expect(buffer.since(-1).map((i) => i.value)).toEqual(['a', 'b', 'c']);
+    expect(buffer.since(buffer.lastSeq)).toEqual([]);
+  });
+
+  it('since(seq) clamps to what is still retained after eviction', () => {
+    const buffer = new HubRingBuffer<TestEntry>(3);
+    for (const value of ['a', 'b', 'c', 'd', 'e']) {
+      buffer.add({ value }); // seqs 0..4, only 2,3,4 retained
+    }
+
+    // Asking since an evicted cursor (seq 0) returns only what survives, no crash, no duplicates.
+    expect(buffer.since(0).map((i) => i.value)).toEqual(['c', 'd', 'e']);
+    expect(buffer.firstRetainedSeq).toBe(2);
+  });
+
+  it('exposes lastSeq (-1 when empty) and firstRetainedSeq', () => {
+    const buffer = new HubRingBuffer<TestEntry>(3);
+    expect(buffer.lastSeq).toBe(-1);
+    expect(buffer.firstRetainedSeq).toBe(-1);
+    expect(buffer.size).toBe(0);
+
+    buffer.add({ value: 'a' });
+    expect(buffer.lastSeq).toBe(0);
+    expect(buffer.firstRetainedSeq).toBe(0);
+  });
+
+  it('clear() empties the buffer but keeps the sequence counter monotonic', () => {
+    const buffer = new HubRingBuffer<TestEntry>(3);
+    buffer.add({ value: 'a' });
+    buffer.add({ value: 'b' });
+    buffer.clear();
+
+    expect(buffer.size).toBe(0);
+    expect(buffer.recent()).toEqual([]);
+    // A new entry after clear must not reuse an old seq (cursors stay valid across a clear).
+    const c = buffer.add({ value: 'c' });
+    expect(c.seq).toBe(2);
+  });
+});

package/src/core/modules/hub/hub-ring-buffer.ts

@@ -0,0 +1,101 @@
+/**
+ * The minimum shape every Hub ring-buffer entry carries.
+ *
+ * `seq` is a monotonic, per-buffer sequence number (never reused, survives eviction and `clear()`),
+ * so polling clients can pass the last seq they saw as a cursor and receive only newer entries.
+ */
+export interface HubBufferEntry {
+  /** Monotonic per-buffer sequence number (0-based, never reused). */
+  seq: number;
+  /** Epoch milliseconds. */
+  timestamp: number;
+}
+
+/**
+ * Fixed-size ring buffer with O(1) append and cursor-based reads.
+ *
+ * - Append writes into `slots[seq % capacity]` — no `Array.shift()` (which would be O(n) and, on the
+ *   long-lived buffers the Hub keeps, a steady GC drag). Memory is strictly `capacity × recordSize`.
+ * - No timers, no statics: one instance per collector per Nest app instance, so parallel e2e apps in
+ *   one process never share buffer state.
+ *
+ * See CLAUDE.md "High-Frequency Path Design Rules" (buffers need a size cap + eviction).
+ */
+export class HubRingBuffer<T extends HubBufferEntry> {
+  /** Fixed capacity (entries retained). */
+  public readonly capacity: number;
+
+  /** Watermark raised by `clear()`: no seq below this is considered retained. */
+  private minValidSeq = 0;
+  private nextSeq = 0;
+  private readonly slots: (T | undefined)[];
+
+  constructor(capacity: number) {
+    this.capacity = Math.max(1, Math.floor(capacity));
+    this.slots = Array.from<T | undefined>({ length: this.capacity });
+  }
+
+  /** Seq of the oldest retained entry (`-1` when empty) — clients detect eviction gaps against this. */
+  get firstRetainedSeq(): number {
+    return this.size === 0 ? -1 : this.oldestSeq;
+  }
+
+  /** Highest assigned seq (`-1` when nothing was ever added) — the client's next cursor. */
+  get lastSeq(): number {
+    return this.nextSeq - 1;
+  }
+
+  /** Number of entries currently retained. */
+  get size(): number {
+    return this.nextSeq - this.oldestSeq;
+  }
+
+  /** Earliest seq that could still be retained (bounded by capacity and by the last `clear()`). */
+  private get oldestSeq(): number {
+    return Math.max(this.nextSeq - this.capacity, this.minValidSeq);
+  }
+
+  /**
+   * Append an entry. Assigns `seq` + `timestamp` (unless a timestamp is supplied) and overwrites the
+   * oldest slot once full. Returns the fully-formed entry.
+   */
+  add(entry: Omit<T, 'seq' | 'timestamp'> & { timestamp?: number }): T {
+    const full = {
+      ...entry,
+      seq: this.nextSeq,
+      timestamp: entry.timestamp ?? Date.now(),
+    } as T;
+    this.slots[this.nextSeq % this.capacity] = full;
+    this.nextSeq++;
+    return full;
+  }
+
+  /** Drop all retained entries. The seq counter keeps advancing so existing cursors stay valid. */
+  clear(): void {
+    this.slots.fill(undefined);
+    this.minValidSeq = this.nextSeq;
+  }
+
+  /** Newest up to `limit` entries, oldest→newest. */
+  recent(limit: number = this.capacity): T[] {
+    return this.collect(this.nextSeq - Math.max(0, limit));
+  }
+
+  /** Entries with `seq > sinceSeq`, clamped to what is still retained, oldest→newest. */
+  since(sinceSeq: number, limit: number = this.capacity): T[] {
+    const start = Math.max(sinceSeq + 1, this.nextSeq - Math.max(0, limit));
+    return this.collect(start);
+  }
+
+  private collect(startSeq: number): T[] {
+    const from = Math.max(startSeq, this.oldestSeq, 0);
+    const result: T[] = [];
+    for (let seq = from; seq < this.nextSeq; seq++) {
+      const entry = this.slots[seq % this.capacity];
+      if (entry !== undefined && entry.seq === seq) {
+        result.push(entry);
+      }
+    }
+    return result;
+  }
+}

package/src/core/modules/hub/hub.constants.ts

@@ -0,0 +1,84 @@
+/**
+ * Dependency-injection tokens and numeric defaults of the Hub module.
+ *
+ * They live in a dedicated, import-free leaf file — never in `core-hub.module.ts` or a service — so
+ * that no file needing a token has to import the module (or vice versa) and close an import cycle.
+ *
+ * On a cycle, a token read at MODULE-EVALUATION time — inside an `@Inject()` decorator argument, in
+ * `design:paramtypes` metadata, or in a static field initializer — reads a `const` still in its
+ * temporal dead zone, and SWC-compiled builds (`nest start -b swc`) die at startup with:
+ *
+ *   ReferenceError: Cannot access 'HUB_CONFIG' before initialization
+ *
+ * A file that imports nothing can never be mid-evaluation when someone imports it, in any module
+ * system, under any compiler. That is the whole point — keep it import-free.
+ *
+ * `tsc`, `pnpm test` and `oxlint` are all blind to a regression here; only `pnpm run check:swc-tdz`
+ * sees it. See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
+
+/**
+ * Token for injecting the resolved Hub configuration.
+ *
+ * Injected type: `ResolvedHubConfig` (see interfaces/hub-config.interface.ts).
+ */
+export const HUB_CONFIG = 'HUB_CONFIG';
+
+/**
+ * Token for the optional outgoing-mail capture hook.
+ *
+ * `EmailService` injects it with `@Optional() @Inject(HUB_EMAIL_CAPTURE)`. When the Hub mailbox is
+ * enabled, `CoreHubModule` binds it to the mailbox service; otherwise it resolves to `undefined` and
+ * the mail path stays untouched (zero cost).
+ *
+ * Injected type: `IHubEmailCapture` (see interfaces/hub-config.interface.ts).
+ */
+export const HUB_EMAIL_CAPTURE = 'HUB_EMAIL_CAPTURE';
+
+/** Default base path for all Hub routes. */
+export const HUB_DEFAULT_PATH = 'hub';
+
+/** Default client poll interval (ms) for JSON sidecars. */
+export const HUB_DEFAULT_POLL_INTERVAL_MS = 5000;
+
+/** Lower clamp for the client poll interval (ms) — protects the server from hammering. */
+export const HUB_MIN_POLL_INTERVAL_MS = 1000;
+
+/** Default ring-buffer capacity for the log collector. */
+export const HUB_DEFAULT_LOG_CAPACITY = 500;
+
+/** Default per-record message cap (characters) for the log collector. */
+export const HUB_DEFAULT_LOG_MAX_MESSAGE_LENGTH = 2048;
+
+/** Default ring-buffer capacity for the request-trace collector. */
+export const HUB_DEFAULT_TRACE_CAPACITY = 200;
+
+/** Default duration (ms) above which a request trace is flagged slow. */
+export const HUB_DEFAULT_TRACE_SLOW_MS = 1000;
+
+/** Default ring-buffer capacity for the query profiler. */
+export const HUB_DEFAULT_QUERY_CAPACITY = 500;
+
+/** Default duration (ms) above which a query is classified "warn". */
+export const HUB_DEFAULT_QUERY_WARN_MS = 50;
+
+/** Default duration (ms) above which a query is classified "critical". */
+export const HUB_DEFAULT_QUERY_CRITICAL_MS = 200;
+
+/** Default command-summary length cap (characters) for the query profiler. */
+export const HUB_DEFAULT_QUERY_MAX_SHAPE_LENGTH = 512;
+
+/** Hard cap on the query profiler's in-flight (pending) command map before oldest-first eviction. */
+export const HUB_QUERY_PENDING_LIMIT = 1000;
+
+/** Default number of captured mails retained by the mailbox. */
+export const HUB_DEFAULT_MAILBOX_CAPACITY = 100;
+
+/** Default per-mail size cap (bytes, html + text) retained by the mailbox. */
+export const HUB_DEFAULT_MAILBOX_MAX_MAIL_SIZE = 262144;
+
+/** Default migrations directory (mirrors the migrate CLI default). */
+export const HUB_DEFAULT_MIGRATIONS_DIR = './migrations';
+
+/** Default MongoDB collection holding migration state. */
+export const HUB_DEFAULT_MIGRATIONS_COLLECTION = 'migrations';