enpilink 1.0.2

package/dist/server/mock-seed.d.ts

@@ -0,0 +1,62 @@
+import type { AnalyticsEvent, LogEntry, StorageAdapter } from "./storage/types.js";
+/**
+ * Mock demo seed (MD). Populates a {@link StorageAdapter} with a realistic,
+ * clearly-labelled spread of demo analytics so the observability Dashboard
+ * renders full and good-looking immediately — for demos and screenshots, with
+ * NO real traffic.
+ *
+ * Determinism is a hard requirement: given the same `seed` + the same base
+ * timestamp (`now`), {@link generateMockEvents} / {@link generateMockLogs}
+ * produce byte-identical output every run. There is NO `Math.random()` and NO
+ * `Date.now()` drift — the only randomness comes from the seeded
+ * {@link mulberry32} PRNG, and every timestamp is derived from the injected
+ * base. This keeps screenshots reproducible across runs and machines.
+ *
+ * This is opt-in only (wired to `enpilink dev --mock` / `ENPILINK_MOCK`); it is
+ * never invoked on a normal dev/prod run.
+ */
+/**
+ * `mulberry32` — a tiny, fast, well-distributed 32-bit PRNG. Pure function of
+ * its seed: same seed → same sequence. Returns a generator producing floats in
+ * `[0, 1)`. Used for ALL "randomness" in the mock seed so output is fully
+ * deterministic.
+ */
+export declare function mulberry32(seed: number): () => number;
+/** Default seed for the demo dataset (arbitrary fixed constant). */
+export declare const MOCK_SEED = 1592594996;
+/** Options for {@link generateMockEvents} / {@link seedMockData}. */
+export interface MockSeedOptions {
+    /**
+     * The base "now" timestamp (epoch ms). All events are placed BEFORE this so
+     * the dashboard's default trailing window shows them. Injected (never
+     * `Date.now()`) so output is deterministic.
+     */
+    now: number;
+    /** PRNG seed. Defaults to {@link MOCK_SEED}. */
+    seed?: number;
+    /** Number of `tool_call` events to generate. Defaults to 600. */
+    count?: number;
+    /** Time span the events are spread over, in ms. Defaults to ~10 days. */
+    spanMs?: number;
+}
+/**
+ * Build a deterministic, weighted, time-ordered list of demo `tool_call`
+ * events spanning `[now - spanMs, now]`. Latencies follow a per-tool
+ * distribution (with an occasional heavy tail), and errors are injected at each
+ * tool's configured rate. Pure function of `(now, seed, count, spanMs)`.
+ */
+export declare function generateMockEvents(opts: MockSeedOptions): AnalyticsEvent[];
+/**
+ * Build a deterministic list of demo log lines spread across the same window.
+ * Pure function of `(now, seed)`.
+ */
+export declare function generateMockLogs(opts: MockSeedOptions): LogEntry[];
+/**
+ * Seed `storage` with the deterministic demo dataset. Records all generated
+ * events + logs. Errors are swallowed per-write (a demo seed must never break
+ * server startup). Idempotency is NOT guaranteed — call once at startup.
+ */
+export declare function seedMockData(storage: StorageAdapter, opts: MockSeedOptions): Promise<{
+    events: number;
+    logs: number;
+}>;

package/dist/server/mock-seed.js

@@ -0,0 +1,251 @@
+/**
+ * Mock demo seed (MD). Populates a {@link StorageAdapter} with a realistic,
+ * clearly-labelled spread of demo analytics so the observability Dashboard
+ * renders full and good-looking immediately — for demos and screenshots, with
+ * NO real traffic.
+ *
+ * Determinism is a hard requirement: given the same `seed` + the same base
+ * timestamp (`now`), {@link generateMockEvents} / {@link generateMockLogs}
+ * produce byte-identical output every run. There is NO `Math.random()` and NO
+ * `Date.now()` drift — the only randomness comes from the seeded
+ * {@link mulberry32} PRNG, and every timestamp is derived from the injected
+ * base. This keeps screenshots reproducible across runs and machines.
+ *
+ * This is opt-in only (wired to `enpilink dev --mock` / `ENPILINK_MOCK`); it is
+ * never invoked on a normal dev/prod run.
+ */
+/**
+ * `mulberry32` — a tiny, fast, well-distributed 32-bit PRNG. Pure function of
+ * its seed: same seed → same sequence. Returns a generator producing floats in
+ * `[0, 1)`. Used for ALL "randomness" in the mock seed so output is fully
+ * deterministic.
+ */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Default seed for the demo dataset (arbitrary fixed constant). */
+export const MOCK_SEED = 0x5eed1234;
+/**
+ * A curated, realistic spread of demo tools — varied names, latencies (fast
+ * lookups → slow LLM/search calls), and a sensible error rate per tool. Fixed
+ * data, no randomness, so the shape of the dashboard is stable.
+ */
+const MOCK_TOOLS = [
+    {
+        tool: "search_documents",
+        method: "tools/call",
+        baseMs: 180,
+        errorRate: 0.04,
+        weight: 9,
+    },
+    {
+        tool: "get_weather",
+        method: "tools/call",
+        baseMs: 90,
+        errorRate: 0.02,
+        weight: 7,
+    },
+    {
+        tool: "create_invoice",
+        method: "tools/call",
+        baseMs: 320,
+        errorRate: 0.08,
+        weight: 5,
+    },
+    {
+        tool: "send_email",
+        method: "tools/call",
+        baseMs: 240,
+        errorRate: 0.11,
+        weight: 4,
+    },
+    {
+        tool: "summarize_text",
+        method: "tools/call",
+        baseMs: 1100,
+        errorRate: 0.06,
+        weight: 6,
+    },
+    {
+        tool: "list_customers",
+        method: "tools/call",
+        baseMs: 60,
+        errorRate: 0.01,
+        weight: 8,
+    },
+    {
+        tool: "run_report",
+        method: "tools/call",
+        baseMs: 1700,
+        errorRate: 0.13,
+        weight: 3,
+    },
+    {
+        tool: "translate",
+        method: "tools/call",
+        baseMs: 420,
+        errorRate: 0.05,
+        weight: 5,
+    },
+    {
+        tool: undefined,
+        method: "tools/list",
+        baseMs: 8,
+        errorRate: 0.0,
+        weight: 6,
+    },
+    {
+        tool: undefined,
+        method: "initialize",
+        baseMs: 4,
+        errorRate: 0.0,
+        weight: 4,
+    },
+];
+/** Demo log messages, paired with a level, for the live-log feed. */
+const MOCK_LOGS = [
+    { level: "info", msg: "MCP server ready — accepting tool calls" },
+    { level: "info", msg: "search_documents: indexed 1,284 documents" },
+    { level: "debug", msg: "cache hit for get_weather(region=eu-west)" },
+    { level: "info", msg: "create_invoice: invoice #INV-4821 generated" },
+    {
+        level: "warning",
+        msg: "send_email: rate limit approaching (87% of quota)",
+    },
+    { level: "info", msg: "summarize_text: 4,096 tokens → 312 tokens" },
+    {
+        level: "error",
+        msg: "run_report: upstream timeout after 5000ms, retrying",
+    },
+    { level: "info", msg: "translate: en → ja (confidence 0.97)" },
+    { level: "debug", msg: "list_customers: page 3 of 12 served from replica" },
+    {
+        level: "warning",
+        msg: "create_invoice: tax rate fallback used for region=unknown",
+    },
+    { level: "error", msg: "send_email: SMTP 421 service not available" },
+    {
+        level: "info",
+        msg: "health check ok — storage=memory, analytics=on (demo)",
+    },
+];
+const DEFAULT_COUNT = 600;
+// Spread the demo events across ~10 days so the dashboard's default 7-day range
+// (M9) looks full rather than sparse. Still deterministic (same seed+base →
+// identical output) — only the time window widened, the count is unchanged.
+const DEFAULT_SPAN_MS = 10 * 24 * 60 * 60 * 1000; // ~10 days
+/**
+ * Build a deterministic, weighted, time-ordered list of demo `tool_call`
+ * events spanning `[now - spanMs, now]`. Latencies follow a per-tool
+ * distribution (with an occasional heavy tail), and errors are injected at each
+ * tool's configured rate. Pure function of `(now, seed, count, spanMs)`.
+ */
+export function generateMockEvents(opts) {
+    const now = opts.now;
+    const seed = opts.seed ?? MOCK_SEED;
+    const count = opts.count ?? DEFAULT_COUNT;
+    const spanMs = opts.spanMs ?? DEFAULT_SPAN_MS;
+    const rand = mulberry32(seed);
+    // Weighted pick table for tools.
+    const totalWeight = MOCK_TOOLS.reduce((sum, t) => sum + t.weight, 0);
+    const events = [];
+    for (let i = 0; i < count; i++) {
+        // Pick a tool by weight.
+        let pick = rand() * totalWeight;
+        let chosen = MOCK_TOOLS[0];
+        for (const t of MOCK_TOOLS) {
+            pick -= t.weight;
+            if (pick <= 0) {
+                chosen = t;
+                break;
+            }
+        }
+        // Spread events across the window with a slight rising trend toward `now`
+        // (more recent activity), so the volume chart looks alive.
+        const trend = (i / count) ** 0.85;
+        const jitter = (rand() - 0.5) * (spanMs / count) * 8;
+        const ts = Math.round(now - spanMs + trend * spanMs + jitter);
+        const clampedTs = Math.min(now - 250, Math.max(now - spanMs, ts));
+        // Latency: baseline ± lognormal-ish spread, with a rare heavy tail.
+        const noise = 0.55 + rand() * 0.95; // 0.55x .. 1.5x
+        const tail = rand() < 0.05 ? 2.4 + rand() * 2.2 : 1; // ~5% slow tail
+        const ms = Math.max(1, Math.round(chosen.baseMs * noise * tail));
+        const ok = rand() >= chosen.errorRate;
+        events.push({
+            ts: clampedTs,
+            type: "tool_call",
+            tool: chosen.tool,
+            method: chosen.method,
+            ms,
+            ok,
+            error: ok ? undefined : "demo error: simulated upstream failure",
+            meta: { demo: true },
+        });
+    }
+    // Storage adapters return most-recent-first; keep the seeded array
+    // oldest-first for readability (recordEvent order doesn't matter).
+    events.sort((a, b) => a.ts - b.ts);
+    return events;
+}
+/**
+ * Build a deterministic list of demo log lines spread across the same window.
+ * Pure function of `(now, seed)`.
+ */
+export function generateMockLogs(opts) {
+    const now = opts.now;
+    const seed = opts.seed ?? MOCK_SEED;
+    const spanMs = opts.spanMs ?? DEFAULT_SPAN_MS;
+    // Offset the seed so log jitter is independent of event jitter but still
+    // fully deterministic.
+    const rand = mulberry32((seed ^ 0x9e3779b9) >>> 0);
+    const logs = [];
+    const n = MOCK_LOGS.length;
+    for (let i = 0; i < n; i++) {
+        const entry = MOCK_LOGS[i];
+        const frac = (i + 1) / (n + 1);
+        const jitter = (rand() - 0.5) * (spanMs / n);
+        const ts = Math.round(now - spanMs + frac * spanMs + jitter);
+        logs.push({
+            ts: Math.min(now - 100, Math.max(now - spanMs, ts)),
+            level: entry.level,
+            msg: entry.msg,
+            data: { demo: true },
+        });
+    }
+    logs.sort((a, b) => a.ts - b.ts);
+    return logs;
+}
+/**
+ * Seed `storage` with the deterministic demo dataset. Records all generated
+ * events + logs. Errors are swallowed per-write (a demo seed must never break
+ * server startup). Idempotency is NOT guaranteed — call once at startup.
+ */
+export async function seedMockData(storage, opts) {
+    const events = generateMockEvents(opts);
+    const logs = generateMockLogs(opts);
+    for (const e of events) {
+        try {
+            await storage.recordEvent(e);
+        }
+        catch {
+            // Demo seeding must never break startup.
+        }
+    }
+    for (const l of logs) {
+        try {
+            await storage.appendLog(l);
+        }
+        catch {
+            // Demo seeding must never break startup.
+        }
+    }
+    return { events: events.length, logs: logs.length };
+}
+//# sourceMappingURL=mock-seed.js.map

package/dist/server/mock-seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-seed.js","sourceRoot":"","sources":["../../src/server/mock-seed.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  AnalyticsEvent,\n  LogEntry,\n  StorageAdapter,\n} from \"./storage/types.js\";\n\n/**\n * Mock demo seed (MD). Populates a {@link StorageAdapter} with a realistic,\n * clearly-labelled spread of demo analytics so the observability Dashboard\n * renders full and good-looking immediately — for demos and screenshots, with\n * NO real traffic.\n *\n * Determinism is a hard requirement: given the same `seed` + the same base\n * timestamp (`now`), {@link generateMockEvents} / {@link generateMockLogs}\n * produce byte-identical output every run. There is NO `Math.random()` and NO\n * `Date.now()` drift — the only randomness comes from the seeded\n * {@link mulberry32} PRNG, and every timestamp is derived from the injected\n * base. This keeps screenshots reproducible across runs and machines.\n *\n * This is opt-in only (wired to `enpilink dev --mock` / `ENPILINK_MOCK`); it is\n * never invoked on a normal dev/prod run.\n */\n\n/**\n * `mulberry32` — a tiny, fast, well-distributed 32-bit PRNG. Pure function of\n * its seed: same seed → same sequence. Returns a generator producing floats in\n * `[0, 1)`. Used for ALL \"randomness\" in the mock seed so output is fully\n * deterministic.\n */\nexport function mulberry32(seed: number): () => number {\n  let a = seed >>> 0;\n  return () => {\n    a |= 0;\n    a = (a + 0x6d2b79f5) | 0;\n    let t = Math.imul(a ^ (a >>> 15), 1 | a);\n    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n  };\n}\n\n/** Default seed for the demo dataset (arbitrary fixed constant). */\nexport const MOCK_SEED = 0x5eed1234;\n\n/** A demo tool: name, MCP method, baseline latency, and a relative error rate. */\ninterface MockTool {\n  tool: string;\n  method: string;\n  /** Baseline latency in ms (the distribution is built around this). */\n  baseMs: number;\n  /** Fraction of calls that error, in `[0, 1]`. */\n  errorRate: number;\n  /** Relative call-volume weight (higher → more calls). */\n  weight: number;\n}\n\n/**\n * A curated, realistic spread of demo tools — varied names, latencies (fast\n * lookups → slow LLM/search calls), and a sensible error rate per tool. Fixed\n * data, no randomness, so the shape of the dashboard is stable.\n */\nconst MOCK_TOOLS: MockTool[] = [\n  {\n    tool: \"search_documents\",\n    method: \"tools/call\",\n    baseMs: 180,\n    errorRate: 0.04,\n    weight: 9,\n  },\n  {\n    tool: \"get_weather\",\n    method: \"tools/call\",\n    baseMs: 90,\n    errorRate: 0.02,\n    weight: 7,\n  },\n  {\n    tool: \"create_invoice\",\n    method: \"tools/call\",\n    baseMs: 320,\n    errorRate: 0.08,\n    weight: 5,\n  },\n  {\n    tool: \"send_email\",\n    method: \"tools/call\",\n    baseMs: 240,\n    errorRate: 0.11,\n    weight: 4,\n  },\n  {\n    tool: \"summarize_text\",\n    method: \"tools/call\",\n    baseMs: 1100,\n    errorRate: 0.06,\n    weight: 6,\n  },\n  {\n    tool: \"list_customers\",\n    method: \"tools/call\",\n    baseMs: 60,\n    errorRate: 0.01,\n    weight: 8,\n  },\n  {\n    tool: \"run_report\",\n    method: \"tools/call\",\n    baseMs: 1700,\n    errorRate: 0.13,\n    weight: 3,\n  },\n  {\n    tool: \"translate\",\n    method: \"tools/call\",\n    baseMs: 420,\n    errorRate: 0.05,\n    weight: 5,\n  },\n  {\n    tool: undefined as unknown as string,\n    method: \"tools/list\",\n    baseMs: 8,\n    errorRate: 0.0,\n    weight: 6,\n  },\n  {\n    tool: undefined as unknown as string,\n    method: \"initialize\",\n    baseMs: 4,\n    errorRate: 0.0,\n    weight: 4,\n  },\n];\n\n/** Demo log messages, paired with a level, for the live-log feed. */\nconst MOCK_LOGS: Array<{ level: LogEntry[\"level\"]; msg: string }> = [\n  { level: \"info\", msg: \"MCP server ready — accepting tool calls\" },\n  { level: \"info\", msg: \"search_documents: indexed 1,284 documents\" },\n  { level: \"debug\", msg: \"cache hit for get_weather(region=eu-west)\" },\n  { level: \"info\", msg: \"create_invoice: invoice #INV-4821 generated\" },\n  {\n    level: \"warning\",\n    msg: \"send_email: rate limit approaching (87% of quota)\",\n  },\n  { level: \"info\", msg: \"summarize_text: 4,096 tokens → 312 tokens\" },\n  {\n    level: \"error\",\n    msg: \"run_report: upstream timeout after 5000ms, retrying\",\n  },\n  { level: \"info\", msg: \"translate: en → ja (confidence 0.97)\" },\n  { level: \"debug\", msg: \"list_customers: page 3 of 12 served from replica\" },\n  {\n    level: \"warning\",\n    msg: \"create_invoice: tax rate fallback used for region=unknown\",\n  },\n  { level: \"error\", msg: \"send_email: SMTP 421 service not available\" },\n  {\n    level: \"info\",\n    msg: \"health check ok — storage=memory, analytics=on (demo)\",\n  },\n];\n\n/** Options for {@link generateMockEvents} / {@link seedMockData}. */\nexport interface MockSeedOptions {\n  /**\n   * The base \"now\" timestamp (epoch ms). All events are placed BEFORE this so\n   * the dashboard's default trailing window shows them. Injected (never\n   * `Date.now()`) so output is deterministic.\n   */\n  now: number;\n  /** PRNG seed. Defaults to {@link MOCK_SEED}. */\n  seed?: number;\n  /** Number of `tool_call` events to generate. Defaults to 600. */\n  count?: number;\n  /** Time span the events are spread over, in ms. Defaults to ~10 days. */\n  spanMs?: number;\n}\n\nconst DEFAULT_COUNT = 600;\n// Spread the demo events across ~10 days so the dashboard's default 7-day range\n// (M9) looks full rather than sparse. Still deterministic (same seed+base →\n// identical output) — only the time window widened, the count is unchanged.\nconst DEFAULT_SPAN_MS = 10 * 24 * 60 * 60 * 1000; // ~10 days\n\n/**\n * Build a deterministic, weighted, time-ordered list of demo `tool_call`\n * events spanning `[now - spanMs, now]`. Latencies follow a per-tool\n * distribution (with an occasional heavy tail), and errors are injected at each\n * tool's configured rate. Pure function of `(now, seed, count, spanMs)`.\n */\nexport function generateMockEvents(opts: MockSeedOptions): AnalyticsEvent[] {\n  const now = opts.now;\n  const seed = opts.seed ?? MOCK_SEED;\n  const count = opts.count ?? DEFAULT_COUNT;\n  const spanMs = opts.spanMs ?? DEFAULT_SPAN_MS;\n  const rand = mulberry32(seed);\n\n  // Weighted pick table for tools.\n  const totalWeight = MOCK_TOOLS.reduce((sum, t) => sum + t.weight, 0);\n\n  const events: AnalyticsEvent[] = [];\n  for (let i = 0; i < count; i++) {\n    // Pick a tool by weight.\n    let pick = rand() * totalWeight;\n    let chosen = MOCK_TOOLS[0] as MockTool;\n    for (const t of MOCK_TOOLS) {\n      pick -= t.weight;\n      if (pick <= 0) {\n        chosen = t;\n        break;\n      }\n    }\n\n    // Spread events across the window with a slight rising trend toward `now`\n    // (more recent activity), so the volume chart looks alive.\n    const trend = (i / count) ** 0.85;\n    const jitter = (rand() - 0.5) * (spanMs / count) * 8;\n    const ts = Math.round(now - spanMs + trend * spanMs + jitter);\n    const clampedTs = Math.min(now - 250, Math.max(now - spanMs, ts));\n\n    // Latency: baseline ± lognormal-ish spread, with a rare heavy tail.\n    const noise = 0.55 + rand() * 0.95; // 0.55x .. 1.5x\n    const tail = rand() < 0.05 ? 2.4 + rand() * 2.2 : 1; // ~5% slow tail\n    const ms = Math.max(1, Math.round(chosen.baseMs * noise * tail));\n\n    const ok = rand() >= chosen.errorRate;\n\n    events.push({\n      ts: clampedTs,\n      type: \"tool_call\",\n      tool: chosen.tool,\n      method: chosen.method,\n      ms,\n      ok,\n      error: ok ? undefined : \"demo error: simulated upstream failure\",\n      meta: { demo: true },\n    });\n  }\n\n  // Storage adapters return most-recent-first; keep the seeded array\n  // oldest-first for readability (recordEvent order doesn't matter).\n  events.sort((a, b) => a.ts - b.ts);\n  return events;\n}\n\n/**\n * Build a deterministic list of demo log lines spread across the same window.\n * Pure function of `(now, seed)`.\n */\nexport function generateMockLogs(opts: MockSeedOptions): LogEntry[] {\n  const now = opts.now;\n  const seed = opts.seed ?? MOCK_SEED;\n  const spanMs = opts.spanMs ?? DEFAULT_SPAN_MS;\n  // Offset the seed so log jitter is independent of event jitter but still\n  // fully deterministic.\n  const rand = mulberry32((seed ^ 0x9e3779b9) >>> 0);\n\n  const logs: LogEntry[] = [];\n  const n = MOCK_LOGS.length;\n  for (let i = 0; i < n; i++) {\n    const entry = MOCK_LOGS[i] as { level: LogEntry[\"level\"]; msg: string };\n    const frac = (i + 1) / (n + 1);\n    const jitter = (rand() - 0.5) * (spanMs / n);\n    const ts = Math.round(now - spanMs + frac * spanMs + jitter);\n    logs.push({\n      ts: Math.min(now - 100, Math.max(now - spanMs, ts)),\n      level: entry.level,\n      msg: entry.msg,\n      data: { demo: true },\n    });\n  }\n  logs.sort((a, b) => a.ts - b.ts);\n  return logs;\n}\n\n/**\n * Seed `storage` with the deterministic demo dataset. Records all generated\n * events + logs. Errors are swallowed per-write (a demo seed must never break\n * server startup). Idempotency is NOT guaranteed — call once at startup.\n */\nexport async function seedMockData(\n  storage: StorageAdapter,\n  opts: MockSeedOptions,\n): Promise<{ events: number; logs: number }> {\n  const events = generateMockEvents(opts);\n  const logs = generateMockLogs(opts);\n\n  for (const e of events) {\n    try {\n      await storage.recordEvent(e);\n    } catch {\n      // Demo seeding must never break startup.\n    }\n  }\n  for (const l of logs) {\n    try {\n      await storage.appendLog(l);\n    } catch {\n      // Demo seeding must never break startup.\n    }\n  }\n  return { events: events.length, logs: logs.length };\n}\n"]}

package/dist/server/mock-seed.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/mock-seed.test.js

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { generateMockEvents, generateMockLogs, MOCK_SEED, mulberry32, seedMockData, } from "./mock-seed.js";
+import { MemoryStorageAdapter } from "./storage/memory.js";
+const BASE = 1_700_000_000_000; // fixed base timestamp
+describe("mulberry32", () => {
+    it("is a pure function of its seed (same seed → same sequence)", () => {
+        const a = mulberry32(123);
+        const b = mulberry32(123);
+        const seqA = [a(), a(), a(), a(), a()];
+        const seqB = [b(), b(), b(), b(), b()];
+        expect(seqA).toEqual(seqB);
+    });
+    it("produces floats in [0, 1)", () => {
+        const r = mulberry32(MOCK_SEED);
+        for (let i = 0; i < 1000; i++) {
+            const v = r();
+            expect(v).toBeGreaterThanOrEqual(0);
+            expect(v).toBeLessThan(1);
+        }
+    });
+    it("differs for different seeds", () => {
+        expect(mulberry32(1)()).not.toEqual(mulberry32(2)());
+    });
+});
+describe("generateMockEvents (determinism)", () => {
+    it("same seed + base → byte-identical events", () => {
+        const a = generateMockEvents({ now: BASE });
+        const b = generateMockEvents({ now: BASE });
+        expect(JSON.stringify(a)).toEqual(JSON.stringify(b));
+    });
+    it("a different base shifts every timestamp by the same delta", () => {
+        const a = generateMockEvents({ now: BASE });
+        const b = generateMockEvents({ now: BASE + 10_000 });
+        expect(a).toHaveLength(b.length);
+        // Non-ts fields are identical (PRNG sequence unchanged); ts shifts by +10s.
+        for (let i = 0; i < a.length; i++) {
+            const ea = a[i];
+            const eb = b[i];
+            expect(eb?.ts).toBe((ea?.ts ?? 0) + 10_000);
+            expect(eb?.tool).toBe(ea?.tool);
+            expect(eb?.ms).toBe(ea?.ms);
+            expect(eb?.ok).toBe(ea?.ok);
+        }
+    });
+    it("a different seed produces a different dataset", () => {
+        const a = generateMockEvents({ now: BASE, seed: 1 });
+        const b = generateMockEvents({ now: BASE, seed: 2 });
+        expect(JSON.stringify(a)).not.toEqual(JSON.stringify(b));
+    });
+    it("honors count, keeps events within the window, oldest-first", () => {
+        const span = 6 * 60 * 60 * 1000;
+        const events = generateMockEvents({ now: BASE, count: 120, spanMs: span });
+        expect(events).toHaveLength(120);
+        for (let i = 1; i < events.length; i++) {
+            expect((events[i]?.ts ?? 0) >= (events[i - 1]?.ts ?? 0)).toBe(true);
+        }
+        for (const e of events) {
+            expect(e.ts).toBeGreaterThanOrEqual(BASE - span);
+            expect(e.ts).toBeLessThanOrEqual(BASE);
+            expect(e.ms).toBeGreaterThanOrEqual(1);
+            expect(e.type).toBe("tool_call");
+        }
+    });
+    it("spreads the default dataset across ~7–14 days (M9: fills the 7d default)", () => {
+        // The default window widened from 6h to ~10 days so the dashboard's
+        // default Last-7-days range looks full. Verify deterministically (fixed
+        // base) without hardcoding the exact span.
+        const events = generateMockEvents({ now: BASE });
+        expect(events).toHaveLength(600);
+        const oldest = events[0]?.ts ?? 0;
+        const newest = events.at(-1)?.ts ?? 0;
+        const spanDays = (newest - oldest) / (24 * 60 * 60 * 1000);
+        expect(spanDays).toBeGreaterThanOrEqual(7);
+        expect(spanDays).toBeLessThanOrEqual(14);
+        // All within [now-14d, now]; comfortably more than a day's worth before now.
+        for (const e of events) {
+            expect(e.ts).toBeLessThanOrEqual(BASE);
+            expect(e.ts).toBeGreaterThanOrEqual(BASE - 14 * 24 * 60 * 60 * 1000);
+        }
+        // A healthy chunk of events falls inside the default 7-day window.
+        const sevenDaysAgo = BASE - 7 * 24 * 60 * 60 * 1000;
+        const inLast7d = events.filter((e) => e.ts >= sevenDaysAgo).length;
+        expect(inLast7d).toBeGreaterThan(200);
+    });
+    it("default window is deterministic (same base → identical wide spread)", () => {
+        expect(JSON.stringify(generateMockEvents({ now: BASE }))).toEqual(JSON.stringify(generateMockEvents({ now: BASE })));
+    });
+    it("produces a sensible (non-zero, non-total) error spread", () => {
+        const events = generateMockEvents({ now: BASE, count: 600 });
+        const errors = events.filter((e) => e.ok === false).length;
+        expect(errors).toBeGreaterThan(0);
+        expect(errors).toBeLessThan(events.length);
+    });
+});
+describe("generateMockLogs (determinism)", () => {
+    it("same seed + base → identical logs", () => {
+        expect(JSON.stringify(generateMockLogs({ now: BASE }))).toEqual(JSON.stringify(generateMockLogs({ now: BASE })));
+    });
+    it("includes multiple severity levels", () => {
+        const levels = new Set(generateMockLogs({ now: BASE }).map((l) => l.level));
+        expect(levels.has("info")).toBe(true);
+        expect(levels.has("error")).toBe(true);
+    });
+});
+describe("seedMockData", () => {
+    it("writes the generated events + logs into storage deterministically", async () => {
+        const s1 = new MemoryStorageAdapter();
+        await s1.init();
+        const r1 = await seedMockData(s1, { now: BASE, count: 50 });
+        expect(r1.events).toBe(50);
+        const s2 = new MemoryStorageAdapter();
+        await s2.init();
+        await seedMockData(s2, { now: BASE, count: 50 });
+        const e1 = await s1.queryEvents({ since: 0, limit: 5000 });
+        const e2 = await s2.queryEvents({ since: 0, limit: 5000 });
+        expect(JSON.stringify(e1)).toEqual(JSON.stringify(e2));
+        expect(e1.length).toBe(50);
+        const l1 = await s1.queryLogs({ since: 0, limit: 5000 });
+        expect(l1.length).toBeGreaterThan(0);
+    });
+});
+//# sourceMappingURL=mock-seed.test.js.map

package/dist/server/mock-seed.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-seed.test.js","sourceRoot":"","sources":["../../src/server/mock-seed.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport {\n  generateMockEvents,\n  generateMockLogs,\n  MOCK_SEED,\n  mulberry32,\n  seedMockData,\n} from \"./mock-seed.js\";\nimport { MemoryStorageAdapter } from \"./storage/memory.js\";\n\nconst BASE = 1_700_000_000_000; // fixed base timestamp\n\ndescribe(\"mulberry32\", () => {\n  it(\"is a pure function of its seed (same seed → same sequence)\", () => {\n    const a = mulberry32(123);\n    const b = mulberry32(123);\n    const seqA = [a(), a(), a(), a(), a()];\n    const seqB = [b(), b(), b(), b(), b()];\n    expect(seqA).toEqual(seqB);\n  });\n\n  it(\"produces floats in [0, 1)\", () => {\n    const r = mulberry32(MOCK_SEED);\n    for (let i = 0; i < 1000; i++) {\n      const v = r();\n      expect(v).toBeGreaterThanOrEqual(0);\n      expect(v).toBeLessThan(1);\n    }\n  });\n\n  it(\"differs for different seeds\", () => {\n    expect(mulberry32(1)()).not.toEqual(mulberry32(2)());\n  });\n});\n\ndescribe(\"generateMockEvents (determinism)\", () => {\n  it(\"same seed + base → byte-identical events\", () => {\n    const a = generateMockEvents({ now: BASE });\n    const b = generateMockEvents({ now: BASE });\n    expect(JSON.stringify(a)).toEqual(JSON.stringify(b));\n  });\n\n  it(\"a different base shifts every timestamp by the same delta\", () => {\n    const a = generateMockEvents({ now: BASE });\n    const b = generateMockEvents({ now: BASE + 10_000 });\n    expect(a).toHaveLength(b.length);\n    // Non-ts fields are identical (PRNG sequence unchanged); ts shifts by +10s.\n    for (let i = 0; i < a.length; i++) {\n      const ea = a[i];\n      const eb = b[i];\n      expect(eb?.ts).toBe((ea?.ts ?? 0) + 10_000);\n      expect(eb?.tool).toBe(ea?.tool);\n      expect(eb?.ms).toBe(ea?.ms);\n      expect(eb?.ok).toBe(ea?.ok);\n    }\n  });\n\n  it(\"a different seed produces a different dataset\", () => {\n    const a = generateMockEvents({ now: BASE, seed: 1 });\n    const b = generateMockEvents({ now: BASE, seed: 2 });\n    expect(JSON.stringify(a)).not.toEqual(JSON.stringify(b));\n  });\n\n  it(\"honors count, keeps events within the window, oldest-first\", () => {\n    const span = 6 * 60 * 60 * 1000;\n    const events = generateMockEvents({ now: BASE, count: 120, spanMs: span });\n    expect(events).toHaveLength(120);\n    for (let i = 1; i < events.length; i++) {\n      expect((events[i]?.ts ?? 0) >= (events[i - 1]?.ts ?? 0)).toBe(true);\n    }\n    for (const e of events) {\n      expect(e.ts).toBeGreaterThanOrEqual(BASE - span);\n      expect(e.ts).toBeLessThanOrEqual(BASE);\n      expect(e.ms).toBeGreaterThanOrEqual(1);\n      expect(e.type).toBe(\"tool_call\");\n    }\n  });\n\n  it(\"spreads the default dataset across ~7–14 days (M9: fills the 7d default)\", () => {\n    // The default window widened from 6h to ~10 days so the dashboard's\n    // default Last-7-days range looks full. Verify deterministically (fixed\n    // base) without hardcoding the exact span.\n    const events = generateMockEvents({ now: BASE });\n    expect(events).toHaveLength(600);\n    const oldest = events[0]?.ts ?? 0;\n    const newest = events.at(-1)?.ts ?? 0;\n    const spanDays = (newest - oldest) / (24 * 60 * 60 * 1000);\n    expect(spanDays).toBeGreaterThanOrEqual(7);\n    expect(spanDays).toBeLessThanOrEqual(14);\n    // All within [now-14d, now]; comfortably more than a day's worth before now.\n    for (const e of events) {\n      expect(e.ts).toBeLessThanOrEqual(BASE);\n      expect(e.ts).toBeGreaterThanOrEqual(BASE - 14 * 24 * 60 * 60 * 1000);\n    }\n    // A healthy chunk of events falls inside the default 7-day window.\n    const sevenDaysAgo = BASE - 7 * 24 * 60 * 60 * 1000;\n    const inLast7d = events.filter((e) => e.ts >= sevenDaysAgo).length;\n    expect(inLast7d).toBeGreaterThan(200);\n  });\n\n  it(\"default window is deterministic (same base → identical wide spread)\", () => {\n    expect(JSON.stringify(generateMockEvents({ now: BASE }))).toEqual(\n      JSON.stringify(generateMockEvents({ now: BASE })),\n    );\n  });\n\n  it(\"produces a sensible (non-zero, non-total) error spread\", () => {\n    const events = generateMockEvents({ now: BASE, count: 600 });\n    const errors = events.filter((e) => e.ok === false).length;\n    expect(errors).toBeGreaterThan(0);\n    expect(errors).toBeLessThan(events.length);\n  });\n});\n\ndescribe(\"generateMockLogs (determinism)\", () => {\n  it(\"same seed + base → identical logs\", () => {\n    expect(JSON.stringify(generateMockLogs({ now: BASE }))).toEqual(\n      JSON.stringify(generateMockLogs({ now: BASE })),\n    );\n  });\n\n  it(\"includes multiple severity levels\", () => {\n    const levels = new Set(generateMockLogs({ now: BASE }).map((l) => l.level));\n    expect(levels.has(\"info\")).toBe(true);\n    expect(levels.has(\"error\")).toBe(true);\n  });\n});\n\ndescribe(\"seedMockData\", () => {\n  it(\"writes the generated events + logs into storage deterministically\", async () => {\n    const s1 = new MemoryStorageAdapter();\n    await s1.init();\n    const r1 = await seedMockData(s1, { now: BASE, count: 50 });\n    expect(r1.events).toBe(50);\n\n    const s2 = new MemoryStorageAdapter();\n    await s2.init();\n    await seedMockData(s2, { now: BASE, count: 50 });\n\n    const e1 = await s1.queryEvents({ since: 0, limit: 5000 });\n    const e2 = await s2.queryEvents({ since: 0, limit: 5000 });\n    expect(JSON.stringify(e1)).toEqual(JSON.stringify(e2));\n    expect(e1.length).toBe(50);\n\n    const l1 = await s1.queryLogs({ since: 0, limit: 5000 });\n    expect(l1.length).toBeGreaterThan(0);\n  });\n});\n"]}

package/dist/server/observability.d.ts

@@ -0,0 +1,149 @@
+import { type Router } from "express";
+import type { AnalyticsEvent, StorageAdapter } from "./storage/types.js";
+/**
+ * Observability read API (M3). Pure core — reads the SAME active
+ * {@link StorageAdapter} the analytics middleware + log sink write to, via
+ * {@link getActiveStorage}. It does NOT depend on `@enpilink/console`.
+ *
+ * Mounted dev-only (under the `NODE_ENV !== "production"` block in
+ * `express.ts`) at `/__enpilink/observability/`. The `/__enpilink/` prefix
+ * avoids colliding with user-defined routes; the dev-only mount keeps prod
+ * surface unchanged (prod admin is M5).
+ *
+ * Graceful when analytics is OFF: storage is read PER-REQUEST (it may be `null`
+ * when disabled or before the server applies middleware). When there is no
+ * active storage every route returns a 200 with `{ enabled: false }` / an empty
+ * payload — NEVER a 500. The storage may also change between requests, so we
+ * never cache it.
+ */
+/** A single point on the calls-over-time series. */
+export interface TimeBucket {
+    /** Bucket start, epoch ms (aligned to `bucketMs`). */
+    ts: number;
+    /** Total calls in the bucket. */
+    count: number;
+    /** Errored calls in the bucket. */
+    errors: number;
+}
+/** Per-tool (or per-method) aggregate row. */
+export interface ToolStat {
+    /** Tool name, or the method name when there is no tool (non-`tools/call`). */
+    name: string;
+    /** Total calls. */
+    count: number;
+    /** Errored calls. */
+    errors: number;
+    /** Error rate in `[0, 1]`. */
+    errorRate: number;
+    /** Median latency (ms). */
+    p50: number;
+    /** 95th-percentile latency (ms). */
+    p95: number;
+    /** 99th-percentile latency (ms). */
+    p99: number;
+    /** Average latency (ms) over events with timing. */
+    avg: number;
+}
+/** Per-MCP-method aggregate row (e.g. `tools/call`, `tools/list`). */
+export interface MethodStat {
+    /** MCP method name, or `"unknown"`. */
+    method: string;
+    /** Total calls. */
+    count: number;
+    /** Errored calls. */
+    errors: number;
+}
+/** A single bar of the latency histogram. */
+export interface LatencyBucket {
+    /** Inclusive lower bound of the bucket (ms). */
+    from: number;
+    /** Exclusive upper bound of the bucket (ms), or `null` for the open top bin. */
+    to: number | null;
+    /** Number of events whose latency fell in this bucket. */
+    count: number;
+}
+/** The aggregate returned by `GET /summary` when analytics is enabled. */
+export interface ObservabilitySummary {
+    enabled: true;
+    /** Window the summary was computed over (epoch ms). */
+    since: number;
+    /** Total events considered. */
+    total: number;
+    /** Errored events. */
+    errors: number;
+    /** Error rate in `[0, 1]`. */
+    errorRate: number;
+    /** Median latency across all events (ms). */
+    p50: number;
+    /** 95th-percentile latency across all events (ms). */
+    p95: number;
+    /** 99th-percentile latency across all events (ms). */
+    p99: number;
+    /** Average latency across all timed events (ms). */
+    avg: number;
+    /** Throughput: calls per minute over the window `[since, latest event]`. */
+    throughputPerMin: number;
+    /** Bucket width used for {@link callsOverTime} (ms). */
+    bucketMs: number;
+    /** Calls-over-time series, oldest bucket first. */
+    callsOverTime: TimeBucket[];
+    /** Top tools/methods by call count (descending). */
+    topTools: ToolStat[];
+    /** Slowest tools/methods by p95 latency (descending). Only timed tools. */
+    slowestTools: ToolStat[];
+    /** Calls grouped by MCP method (descending by count). */
+    byMethod: MethodStat[];
+    /** Latency distribution histogram (fixed buckets). */
+    latencyHistogram: LatencyBucket[];
+}
+/** The disabled/no-storage shape — a valid 200 payload, never a 500. */
+export interface ObservabilityDisabled {
+    enabled: false;
+    total: 0;
+    errors: 0;
+    errorRate: 0;
+    p50: 0;
+    p95: 0;
+    p99: 0;
+    avg: 0;
+    throughputPerMin: 0;
+    bucketMs: number;
+    callsOverTime: [];
+    topTools: [];
+    slowestTools: [];
+    byMethod: [];
+    latencyHistogram: [];
+}
+/**
+ * Percentile of a numeric sample using nearest-rank (lower) interpolation.
+ * Returns `0` for an empty sample. `p` is in `[0, 1]`. Tolerates `ms === 0`
+ * (a zero-latency call is a real data point, not a missing one).
+ */
+export declare function percentile(sorted: number[], p: number): number;
+/** Options for {@link summarize}. */
+export interface SummarizeOptions {
+    /** Lower bound used in the response (epoch ms). */
+    since: number;
+    /** Bucket width for the calls-over-time series (ms). Defaults to 60_000. */
+    bucketMs?: number;
+    /** Max tools in `topTools`. Defaults to 10. */
+    topLimit?: number;
+}
+/**
+ * Aggregate raw events into a {@link ObservabilitySummary}. Pure + deterministic
+ * (no clock, no I/O) so it is unit-testable with injected events. The storage
+ * adapter intentionally does NOT aggregate — all rollups happen here.
+ *
+ * - Latency percentiles only consider events with a numeric `ms` (including
+ *   `ms === 0`); events without timing are excluded from p50/p95 but still
+ *   counted toward totals + error rate.
+ * - `ok === false` (or a present `error`) counts as an error.
+ * - Tools group by `tool`, falling back to `method`, then `"unknown"`.
+ */
+export declare function summarize(events: AnalyticsEvent[], opts: SummarizeOptions): ObservabilitySummary;
+/**
+ * Build the observability read API router. All routes read storage
+ * per-request via {@link getActiveStorage} (overridable for tests) so the
+ * disabled / not-yet-installed path returns a 200 empty payload, never a 500.
+ */
+export declare function createObservabilityRouter(getStorage?: () => StorageAdapter | null): Router;