@mandujs/core 0.21.0 → 0.22.1

package/src/observability/event-bus.ts

@@ -1,79 +1,81 @@
-/** Mandu Unified EventBus -- foundation for the observability system. */
-
-export type EventType = "http" | "mcp" | "guard" | "build" | "error" | "cache" | "ws";
-export type ObservabilitySeverity = "info" | "warn" | "error";
-
-export interface ObservabilityEvent {
-  id: string;
-  correlationId?: string;
-  type: EventType;
-  severity: ObservabilitySeverity;
-  source: string;
-  timestamp: number;
-  message: string;
-  data?: Record<string, unknown>;
-  duration?: number;
-}
-
-export type EventHandler = (event: ObservabilityEvent) => void;
-
-class ManduEventBus {
-  private handlers = new Map<string, Set<EventHandler>>();
-  private recent: ObservabilityEvent[] = [];
-  private maxRecent = 200;
-
-  on(type: EventType | "*", handler: EventHandler): () => void {
-    let set = this.handlers.get(type);
-    if (!set) {
-      set = new Set();
-      this.handlers.set(type, set);
-    }
-    set.add(handler);
-    return () => { set!.delete(handler); };
-  }
-
-  emit(event: Omit<ObservabilityEvent, "id" | "timestamp">): void {
-    const full: ObservabilityEvent = {
-      ...event,
-      id: crypto.randomUUID(),
-      timestamp: Date.now(),
-    };
-    this.recent.push(full);
-    if (this.recent.length > this.maxRecent) {
-      this.recent = this.recent.slice(-this.maxRecent);
-    }
-    this.handlers.get(full.type)?.forEach((h) => h(full));
-    this.handlers.get("*")?.forEach((h) => h(full));
-  }
-
-  getRecent(
-    count?: number,
-    filter?: { type?: EventType; severity?: ObservabilitySeverity },
-  ): ObservabilityEvent[] {
-    let result = this.recent;
-    if (filter?.type) result = result.filter((e) => e.type === filter.type);
-    if (filter?.severity) result = result.filter((e) => e.severity === filter.severity);
-    return count ? result.slice(-count) : result;
-  }
-
-  getStats(windowMs?: number): Record<EventType, { count: number; errors: number; avgDuration: number }> {
-    const cutoff = windowMs ? Date.now() - windowMs : 0;
-    const ALL: EventType[] = ["http", "mcp", "guard", "build", "error", "cache", "ws"];
-    const stats = {} as Record<EventType, { count: number; errors: number; avgDuration: number }>;
-    const dur = {} as Record<EventType, number[]>;
-    for (const t of ALL) { stats[t] = { count: 0, errors: 0, avgDuration: 0 }; dur[t] = []; }
-    for (const e of this.recent) {
-      if (e.timestamp < cutoff) continue;
-      stats[e.type].count++;
-      if (e.severity === "error") stats[e.type].errors++;
-      if (e.duration !== undefined) dur[e.type].push(e.duration);
-    }
-    for (const t of ALL) {
-      const d = dur[t];
-      stats[t].avgDuration = d.length ? d.reduce((a, b) => a + b, 0) / d.length : 0;
-    }
-    return stats;
-  }
-}
-
-export const eventBus = new ManduEventBus();
+/** Mandu Unified EventBus -- foundation for the observability system. */
+
+import { newId } from "../id";
+
+export type EventType = "http" | "mcp" | "guard" | "build" | "error" | "cache" | "ws";
+export type ObservabilitySeverity = "info" | "warn" | "error";
+
+export interface ObservabilityEvent {
+  id: string;
+  correlationId?: string;
+  type: EventType;
+  severity: ObservabilitySeverity;
+  source: string;
+  timestamp: number;
+  message: string;
+  data?: Record<string, unknown>;
+  duration?: number;
+}
+
+export type EventHandler = (event: ObservabilityEvent) => void;
+
+class ManduEventBus {
+  private handlers = new Map<string, Set<EventHandler>>();
+  private recent: ObservabilityEvent[] = [];
+  private maxRecent = 200;
+
+  on(type: EventType | "*", handler: EventHandler): () => void {
+    let set = this.handlers.get(type);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(type, set);
+    }
+    set.add(handler);
+    return () => { set!.delete(handler); };
+  }
+
+  emit(event: Omit<ObservabilityEvent, "id" | "timestamp">): void {
+    const full: ObservabilityEvent = {
+      ...event,
+      id: newId(),
+      timestamp: Date.now(),
+    };
+    this.recent.push(full);
+    if (this.recent.length > this.maxRecent) {
+      this.recent = this.recent.slice(-this.maxRecent);
+    }
+    this.handlers.get(full.type)?.forEach((h) => h(full));
+    this.handlers.get("*")?.forEach((h) => h(full));
+  }
+
+  getRecent(
+    count?: number,
+    filter?: { type?: EventType; severity?: ObservabilitySeverity },
+  ): ObservabilityEvent[] {
+    let result = this.recent;
+    if (filter?.type) result = result.filter((e) => e.type === filter.type);
+    if (filter?.severity) result = result.filter((e) => e.severity === filter.severity);
+    return count ? result.slice(-count) : result;
+  }
+
+  getStats(windowMs?: number): Record<EventType, { count: number; errors: number; avgDuration: number }> {
+    const cutoff = windowMs ? Date.now() - windowMs : 0;
+    const ALL: EventType[] = ["http", "mcp", "guard", "build", "error", "cache", "ws"];
+    const stats = {} as Record<EventType, { count: number; errors: number; avgDuration: number }>;
+    const dur = {} as Record<EventType, number[]>;
+    for (const t of ALL) { stats[t] = { count: 0, errors: 0, avgDuration: 0 }; dur[t] = []; }
+    for (const e of this.recent) {
+      if (e.timestamp < cutoff) continue;
+      stats[e.type].count++;
+      if (e.severity === "error") stats[e.type].errors++;
+      if (e.duration !== undefined) dur[e.type].push(e.duration);
+    }
+    for (const t of ALL) {
+      const d = dur[t];
+      stats[t].avgDuration = d.length ? d.reduce((a, b) => a + b, 0) / d.length : 0;
+    }
+    return stats;
+  }
+}
+
+export const eventBus = new ManduEventBus();

package/src/paths.ts

@@ -20,7 +20,32 @@ export interface GeneratedPaths {
   resourceTypesDir: string;
   resourceSlotsDir: string;
   resourceClientDir: string;
+  /** User-authored resource schema files (spec/resources). */
   resourceSchemasDir: string;
+  /**
+   * Phase 4c — Generated per-resource repo modules
+   * (`.mandu/generated/server/repos/{name}.repo.ts`). DERIVED; regenerated
+   * on every build when the resource declares `options.persistence`.
+   */
+  resourceReposDir: string;
+  /**
+   * Phase 4c — Per-resource CREATE TABLE DDL snapshots for humans
+   * (`.mandu/generated/server/schema/{table}.sql`). DERIVED; not applied
+   * by the migration runner — applied migrations live in `migrationsDir`.
+   */
+  resourceSchemaOutDir: string;
+  /**
+   * Phase 4c — Schema state directory (`.mandu/schema`). Holds
+   * `applied.json` (owned by the migration runner after successful apply).
+   * The Phase 4c generator only READS from here — never writes.
+   */
+  schemaStateDir: string;
+  /**
+   * Phase 4c — User-visible migration files directory
+   * (`spec/db/migrations`). `mandu db plan` writes `NNNN_auto_*.sql`
+   * here, the runner reads it on `mandu db apply`.
+   */
+  migrationsDir: string;
 }
 
 /**
@@ -38,6 +63,10 @@ export function resolveGeneratedPaths(rootDir: string): GeneratedPaths {
     resourceSlotsDir: path.join(rootDir, "spec/slots"),
     resourceClientDir: path.join(rootDir, ".mandu/generated/client"),
     resourceSchemasDir: path.join(rootDir, "spec/resources"),
+    resourceReposDir: path.join(rootDir, ".mandu/generated/server/repos"),
+    resourceSchemaOutDir: path.join(rootDir, ".mandu/generated/server/schema"),
+    schemaStateDir: path.join(rootDir, ".mandu/schema"),
+    migrationsDir: path.join(rootDir, "spec/db/migrations"),
   };
 }
 
@@ -56,4 +85,12 @@ export const GENERATED_RELATIVE_PATHS = {
   slots: "spec/slots",
   client: ".mandu/generated/client",
   resourceSchemas: "spec/resources",
+  /** Phase 4c — repo emission target. */
+  resourceRepos: ".mandu/generated/server/repos",
+  /** Phase 4c — per-resource CREATE TABLE snapshots (documentation). */
+  resourceSchemaOut: ".mandu/generated/server/schema",
+  /** Phase 4c — applied.json lives here (runner-owned). */
+  schemaState: ".mandu/schema",
+  /** Phase 4c — user-visible migrations directory. */
+  migrations: "spec/db/migrations",
 } as const;

package/src/perf/hmr-markers.ts

@@ -0,0 +1,215 @@
+/**
+ * Phase 7.0 — HMR perf marker names (B4 fix)
+ *
+ * Purpose: give Agent B (incremental bundled import), Agent A (reliability),
+ * and Agent F (perf validation) a single vocabulary for marker names passed
+ * to `mark()` / `measure()` / `withPerf()`.
+ *
+ * Why a shared module: in Phase 7.0 diagnostics we found that
+ * `cli/commands/dev.ts:322-363`'s `handleSSRChange` chain has NO perf
+ * markers — `dev:rebuild` wraps only `_doBuild`, so the true SSR rebuild
+ * walltime (1.5~2 s vs 200ms target) is invisible. Without consistent
+ * marker naming across agents, each would pick ad-hoc strings and
+ * Agent F's benchmark script would have to grep for a hundred variants.
+ *
+ * When adding new markers:
+ *   1. Add the constant here.
+ *   2. Use it in production code as `mark(HMR_PERF.SSR_HANDLER_RELOAD)`
+ *      (not a string literal).
+ *   3. Update `docs/bun/phase-7-benchmarks.md` (Agent F owns it).
+ *
+ * References:
+ *   docs/bun/phase-7-diagnostics/performance-reliability.md §2 B4
+ *   docs/bun/phase-7-team-plan.md §3.2
+ */
+
+/**
+ * All HMR-related perf markers. String literals are frozen — do not
+ * mutate. Marker names follow the `<area>:<step>` convention so grep
+ * and log aggregation work predictably.
+ */
+export const HMR_PERF = {
+  // ─── File detection → build invocation ─────────────────────────────────
+
+  /** Raw fs event received (watcher). */
+  FILE_DETECT: "hmr:file-detect",
+
+  /** After per-file debounce, before `handleFileChange()` runs. */
+  DEBOUNCE_FLUSH: "hmr:debounce-flush",
+
+  /** Coalesced batch dispatched to the rebuild path. */
+  BATCH_DISPATCH: "hmr:batch-dispatch",
+
+  // ─── Rebuild outer frame ───────────────────────────────────────────────
+
+  /** Wall-clock from batch dispatch → WS broadcast complete. The P95
+   *  target (≤50 ms island / ≤200 ms SSR / ≤500 ms cold) is measured on
+   *  this marker. */
+  REBUILD_TOTAL: "hmr:rebuild-total",
+
+  /** `_doBuild` body (covers both `buildClientBundles` + SSR path). */
+  DO_BUILD: "hmr:do-build",
+
+  // ─── SSR handler reload chain (B4 newly-instrumented) ──────────────────
+
+  /** `handleSSRChange` mutex section — from enter to exit. */
+  SSR_HANDLER_RELOAD: "ssr:handler-reload",
+
+  /** `bundledImport` call — the single largest SSR cost today. Incremental
+   *  path (Agent B) should target near-zero on cache hits. */
+  SSR_BUNDLED_IMPORT: "ssr:bundled-import",
+
+  /** `clearDefaultRegistry` + `registeredLayouts.clear` (fast). */
+  SSR_CLEAR_REGISTRY: "ssr:clear-registry",
+
+  /** `registerManifestHandlers(manifest, true)` — per-route re-registration. */
+  SSR_REGISTER_HANDLERS: "ssr:register-handlers",
+
+  /** Prerender regeneration (issue #188 fix). Measures only the prerender
+   *  re-run, not the HTML delivery. */
+  PRERENDER_REGEN: "prerender:regen",
+
+  // ─── Client bundle path ────────────────────────────────────────────────
+
+  /** Per-island rebuild. Sub-marker of DO_BUILD when kind === "islands-only". */
+  ISLAND_REBUILD: "island:rebuild",
+
+  /** Framework bundle (runtime/router/vendor/devtools). Should be SKIPPED
+   *  on common-dir rebuild (fire when skipFrameworkBundles === false). */
+  FRAMEWORK_REBUILD: "framework:rebuild",
+
+  /** Vendor shim build. Sub-marker of FRAMEWORK_REBUILD. */
+  VENDOR_SHIM_BUILD: "framework:vendor-shim",
+
+  // ─── HMR transport ─────────────────────────────────────────────────────
+
+  /** Time to serialize + send to all connected clients. */
+  HMR_BROADCAST: "hmr:broadcast",
+
+  /** Replay buffer enqueue (B8). */
+  HMR_REPLAY_ENQUEUE: "hmr:replay-enqueue",
+
+  /** Client reconnect — `?since=<id>` processing. */
+  HMR_REPLAY_FLUSH: "hmr:replay-flush",
+
+  // ─── Incremental bundled import internals (Agent B) ────────────────────
+
+  /** Import graph lookup for a root path. */
+  INCR_GRAPH_LOOKUP: "incr:graph-lookup",
+
+  /** Cache hit (no rebuild needed — changed file not in descendants). */
+  INCR_CACHE_HIT: "incr:cache-hit",
+
+  /** Cache miss (rebuild required). */
+  INCR_CACHE_MISS: "incr:cache-miss",
+
+  /** Graph rebuild after new build — updates descendants map. */
+  INCR_GRAPH_UPDATE: "incr:graph-update",
+
+  // ─── Cold boot path (Phase 7.1 B_gap — R0.3 diagnostic identified 9
+  //     unmeasured stages accounting for 150~210 ms of the 626 ms cold
+  //     start. Instrumenting these unlocks Tier 1 / Tier 2 optimizations.) ─
+
+  /** `validateAndReport(rootDir)` — mandu.config.ts load + schema check. */
+  BOOT_VALIDATE_CONFIG: "boot:validate-config",
+
+  /** `validateRuntimeLockfile` — bun.lock check + advisory warnings. */
+  BOOT_LOCKFILE_CHECK: "boot:lockfile-check",
+
+  /** `loadEnv({ rootDir, env: "development" })` — .env / .env.development. */
+  BOOT_LOAD_ENV: "boot:load-env",
+
+  /** `startSqliteStore(rootDir)` — observability store (optional). Should
+   *  become fire-and-forget in Tier 1 so it doesn't block ready. */
+  BOOT_SQLITE_START: "boot:sqlite-start",
+
+  /** `checkDirectory(guardConfig, rootDir)` — Architecture Guard preflight. */
+  BOOT_GUARD_PREFLIGHT: "boot:guard-preflight",
+
+  /** `resolveAvailablePort(desiredPort, ...)` — port probe (may be slow on
+   *  Windows due to TIME_WAIT; Phase 0 already added retry). */
+  BOOT_RESOLVE_PORT: "boot:resolve-port",
+
+  /** `createHMRServer(port, options?)` — Bun.serve + WebSocket + replay
+   *  buffer setup. Phase 7.0.R4 added Origin allowlist + rate limit. */
+  BOOT_HMR_SERVER: "boot:hmr-server",
+
+  /** `startServer(manifest, ...)` — Bun.serve for the actual app. */
+  BOOT_START_SERVER: "boot:start-server",
+
+  /** `watchFSRoutes(...)` — chokidar watcher for spec/slots + app/ routes.
+   *  Phase 7.1.A may not be able to remove this; it tracks new-route
+   *  creation which `_doBuild` does not. */
+  BOOT_WATCH_FS_ROUTES: "boot:watch-fs-routes",
+
+  // ─── Phase 7.2 ─────────────────────────────────────────────────────────
+
+  /** Tier 2 vendor shim disk-cache hit — all 4 shim outputs loaded from
+   *  `.mandu/vendor-cache/` instead of rebuilt. Target: >95% on warm dev. */
+  VENDOR_CACHE_HIT: "vendor:cache-hit",
+
+  /** Tier 2 miss — any reason (no manifest / version mismatch / tamper /
+   *  first boot). Full `buildVendorShims` runs. */
+  VENDOR_CACHE_MISS: "vendor:cache-miss",
+
+  /** Tier 2 cache write — after a successful rebuild, persist to disk.
+   *  Only fires on miss paths. */
+  VENDOR_CACHE_WRITE: "vendor:cache-write",
+
+  /** HDR (Hot Data Revalidation) — slot change triggered a loader
+   *  refetch without a React tree remount. Measures WS broadcast →
+   *  client loader settled → props applied. Target: ≤ 150 ms P95. */
+  HDR_REFETCH: "hdr:refetch",
+
+  // ─── Phase 7.3 ─────────────────────────────────────────────────────────
+
+  /** JIT pre-warm — `mandu dev` boot kicks off fire-and-forget imports
+   *  of the hot SSR modules (react, react-dom, react-dom/server) so
+   *  Bun's JITTier compiler has them ready before the user's first edit.
+   *
+   *  This marker measures the prewarm Promise's total wall-clock from
+   *  boot-start to all `import()` settling — it is NOT on the critical
+   *  path to "ready" (see `startPrewarmIdle`), so values here are
+   *  informational for benchmarks only. Phase 7.2 F observed first-iter
+   *  cold +41 ms vs warm steady-state; the goal is to absorb that into
+   *  prewarm before the user hits a file save. */
+  JIT_PREWARM: "boot:jit-prewarm",
+
+  /** API route handler reload (`handleAPIChange`) — `.route.ts` /
+   *  `.route.tsx` change. Symmetric to `SSR_HANDLER_RELOAD` for page /
+   *  layout reloads. Phase 7.2 §7.4 flagged that `handleAPIChange` was
+   *  missing a top-level `withPerf()` wrap so Agent D's MANDU_PERF=1
+   *  trace couldn't attribute API reload walltime.
+   *
+   *  Semantically API reloads are a subset of "route handler reload"
+   *  (`SSR_HANDLER_RELOAD`), but a distinct marker lets benchmark scripts
+   *  separate page vs API reload populations when computing P95. */
+  API_HANDLER_RELOAD: "api:handler-reload",
+} as const;
+
+/**
+ * Union of all marker names — useful when a function accepts an arbitrary
+ * marker as a parameter and you want compile-time exhaustiveness.
+ */
+export type HMRPerfMarker = (typeof HMR_PERF)[keyof typeof HMR_PERF];
+
+/**
+ * Human-readable target thresholds. Source of truth for Agent F's hard
+ * assertion pass/fail logic. Values in milliseconds.
+ */
+export const HMR_PERF_TARGETS = {
+  /** Cold dev start (`mandu dev` → "ready" log). */
+  COLD_START_MS: 500,
+
+  /** Island-only rebuild P95, measured on REBUILD_TOTAL. */
+  ISLAND_REBUILD_P95_MS: 50,
+
+  /** SSR page rebuild P95, measured on REBUILD_TOTAL when kind === "ssr-only". */
+  SSR_REBUILD_P95_MS: 200,
+
+  /** Common-dir rebuild P95 (fan-out across multiple islands/SSR modules). */
+  COMMON_DIR_REBUILD_P95_MS: 400,
+
+  /** CSS-only rebuild P95. */
+  CSS_REBUILD_P95_MS: 100,
+} as const;

package/src/perf/index.ts

@@ -0,0 +1,104 @@
+/**
+ * Mandu Perf Module
+ *
+ * Lightweight, opt-in measurement markers built on `Bun.nanoseconds()`.
+ *
+ * Enable at process boot with `MANDU_PERF=1`. When disabled, every function is
+ * a single-branch no-op (no allocation, no Map lookups, no logging) so it is
+ * safe to sprinkle markers across hot paths.
+ *
+ * Rationale for `console.log` (not the structured logger):
+ * measurement is a cross-cutting concern and must not depend on the log
+ * pipeline it may itself be measuring. Keeping the output path trivial also
+ * preserves the "zero-overhead when disabled, minimal overhead when enabled"
+ * contract.
+ *
+ * @example
+ * ```ts
+ * import { mark, measure, withPerf } from "@mandujs/core/perf";
+ *
+ * mark("build:start");
+ * await doWork();
+ * measure("full build", "build:start");
+ *
+ * const result = await withPerf("ssr:render", () => render(route));
+ * ```
+ *
+ * @module perf
+ */
+
+// Module-load snapshot. `isPerfEnabled()` is a stable answer per process.
+let enabled: boolean = process.env.MANDU_PERF === "1";
+
+// Lazily-initialized marker table. Stays `null` when disabled so no allocation
+// occurs on the disabled fast path.
+let marks: Map<string, number> | null = null;
+
+/**
+ * Whether perf markers are active for this process.
+ *
+ * Cached at module load from `MANDU_PERF=1`; changing the env var afterwards
+ * has no effect (see `_resetCacheForTesting` for test-only overrides).
+ */
+export function isPerfEnabled(): boolean {
+  return enabled;
+}
+
+/**
+ * Record a start marker. Later passed to {@link measure} as `startName`.
+ *
+ * No-op when perf is disabled.
+ */
+export function mark(name: string): void {
+  if (!enabled) return;
+  if (marks === null) marks = new Map<string, number>();
+  marks.set(name, Bun.nanoseconds());
+}
+
+/**
+ * Log elapsed milliseconds since `startName` was marked and return the value.
+ *
+ * Returns `0` (and does not log or throw) if `startName` was never marked, so
+ * callers can safely remove a `mark()` without breaking a `measure()` site.
+ * No-op (returns `0`) when perf is disabled.
+ */
+export function measure(label: string, startName: string): number {
+  if (!enabled) return 0;
+  if (marks === null) return 0;
+  const start = marks.get(startName);
+  if (start === undefined) return 0;
+  const ms = (Bun.nanoseconds() - start) / 1_000_000;
+  console.log(`[perf] ${label}: ${ms.toFixed(2)}ms`);
+  return ms;
+}
+
+/**
+ * Measure the duration of `fn` and log on completion. Propagates the resolved
+ * value and re-throws errors (still logging the elapsed time before rethrow).
+ *
+ * When perf is disabled, `fn` is invoked directly with no wrapping overhead
+ * beyond a single branch and a `Promise.resolve`.
+ */
+export async function withPerf<T>(label: string, fn: () => T | Promise<T>): Promise<T> {
+  if (!enabled) return await fn();
+  const start = Bun.nanoseconds();
+  try {
+    return await fn();
+  } finally {
+    const ms = (Bun.nanoseconds() - start) / 1_000_000;
+    console.log(`[perf] ${label}: ${ms.toFixed(2)}ms`);
+  }
+}
+
+/**
+ * Test-only: re-read `MANDU_PERF` from the environment and clear marker state.
+ *
+ * Not part of the public surface; intentionally prefixed with `_` and excluded
+ * from the module-level TSDoc examples. Stable across the test suite only.
+ *
+ * @internal
+ */
+export function _resetCacheForTesting(): void {
+  enabled = process.env.MANDU_PERF === "1";
+  marks = null;
+}