@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/debug/event-ring-buffer.ts

@@ -0,0 +1,64 @@
+// @internal — Bounded ring buffer backing TelemetryBus channel tails.
+//
+// Fixed-size circular buffer. `push` drops the oldest when full. `tail(n)`
+// returns the last `n` items in insertion order (oldest→newest). No
+// allocation in the steady state once the buffer fills up — we overwrite
+// in place.
+//
+// Browser + Node safe (no globals beyond standard JS). Imported by
+// `src/runtime/debug/telemetry-bus.ts` and, transitively, by the Phase 2
+// Railway-hosted `services/debug/` Next.js service via the in-process
+// `runtime.debug.getBus()` accessor.
+
+export class EventRingBuffer<T> {
+  private readonly capacity: number;
+  private buf: (T | undefined)[];
+  private writeIndex = 0;
+  private count = 0;
+
+  constructor(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error(`EventRingBuffer capacity must be a positive integer, got ${capacity}`);
+    }
+    this.capacity = capacity;
+    this.buf = new Array(capacity);
+  }
+
+  push(item: T): void {
+    this.buf[this.writeIndex] = item;
+    this.writeIndex = (this.writeIndex + 1) % this.capacity;
+    if (this.count < this.capacity) this.count += 1;
+  }
+
+  /** Returns last n items in insertion order (oldest first). */
+  tail(n: number): T[] {
+    const take = Math.min(n, this.count);
+    if (take <= 0) return [];
+    const out: T[] = new Array(take);
+    // Oldest in the current window lives `count` items behind writeIndex.
+    const start = (this.writeIndex - take + this.capacity) % this.capacity;
+    for (let i = 0; i < take; i += 1) {
+      out[i] = this.buf[(start + i) % this.capacity] as T;
+    }
+    return out;
+  }
+
+  /** All buffered items in insertion order (up to capacity). */
+  all(): T[] {
+    return this.tail(this.count);
+  }
+
+  size(): number {
+    return this.count;
+  }
+
+  getCapacity(): number {
+    return this.capacity;
+  }
+
+  clear(): void {
+    this.buf = new Array(this.capacity);
+    this.writeIndex = 0;
+    this.count = 0;
+  }
+}

package/src/runtime/debug/probability-sampler.ts

@@ -0,0 +1,18 @@
+// Probability-gated emit helper for telemetry channels whose full-volume
+// emission would be unbounded (e.g. per-formatting-resolution samples).
+//
+// Contract: `shouldEmitSample(rate)` returns `true` with probability
+// `rate`, `false` otherwise. Edge cases:
+//   - `rate <= 0` → always `false`
+//   - `rate >= 1` → always `true`
+//   - NaN or non-finite → always `false` (conservative)
+//
+// Not cryptographically random — uses Math.random. Suitable for
+// telemetry sampling; NOT for security decisions.
+
+export function shouldEmitSample(rate: number): boolean {
+  if (!Number.isFinite(rate)) return false;
+  if (rate <= 0) return false;
+  if (rate >= 1) return true;
+  return Math.random() < rate;
+}

package/src/runtime/debug/runtime-debug-facet.ts

@@ -0,0 +1,67 @@
+// @internal — `runtime.debug` facet.
+//
+// The one handle into the runtime's telemetry bus + the on-demand projector
+// snapshot. Consumed by:
+//   - The harness dev drawer (`HarnessDebugPanel`), in-process.
+//   - The Phase 2 `services/debug/` Railway service, either in-process (Node
+//     executor) or through the hidden harness page's `window.__debug` RPC
+//     that proxies these methods.
+//
+// This module imports `TelemetryBus` + the projector. `DocumentRuntime`
+// constructs a `RuntimeDebugFacet` via `createRuntimeDebugFacet(runtime, bus)`
+// at the end of its factory and exposes it on the interface.
+
+import type { DocumentRuntime } from "../document-runtime.ts";
+import type { TelemetryBus } from "./telemetry-bus.ts";
+import {
+  buildDebugInspectorSnapshot,
+} from "./build-debug-inspector-snapshot.ts";
+import type {
+  DebugInspectorQuery,
+  DebugInspectorSnapshot,
+  RuntimeTelemetryEvent,
+  TelemetryChannel,
+} from "./types.ts";
+
+export interface RuntimeDebugFacet {
+  /** The live bus. Callers emit / subscribe / toggle channels here. */
+  readonly bus: TelemetryBus;
+  /** Compose a full `DebugInspectorSnapshot` on demand. */
+  getSnapshot(query?: DebugInspectorQuery): DebugInspectorSnapshot;
+  /** Read the last `n` events across all channels. */
+  tail(n?: number): RuntimeTelemetryEvent[];
+  /** Read the last `n` events from one channel. */
+  tailChannel(channel: TelemetryChannel, n?: number): RuntimeTelemetryEvent[];
+  /**
+   * Bulk-apply a partial channel record; returns the resulting channel
+   * state. Mirrors the `services/debug/` session API.
+   */
+  setChannels(flags: Partial<Record<TelemetryChannel, boolean>>): Record<TelemetryChannel, boolean>;
+  /** Current channel state. */
+  getChannels(): Record<TelemetryChannel, boolean>;
+}
+
+export function createRuntimeDebugFacet(
+  getRuntime: () => DocumentRuntime,
+  bus: TelemetryBus,
+): RuntimeDebugFacet {
+  return {
+    bus,
+    getSnapshot(query) {
+      return buildDebugInspectorSnapshot(getRuntime(), query, { bus });
+    },
+    tail(n = 64) {
+      return bus.tailAll(n);
+    },
+    tailChannel(channel, n = 64) {
+      return bus.tail(channel, n);
+    },
+    setChannels(flags) {
+      bus.setChannels(flags);
+      return bus.getChannels();
+    },
+    getChannels() {
+      return bus.getChannels();
+    },
+  };
+}

package/src/runtime/debug/stage-tokens.ts

@@ -0,0 +1,31 @@
+import type { TelemetryBus } from "./telemetry-bus.ts";
+import type { TelemetryChannel } from "./types.ts";
+
+let tokenSeq = 0;
+
+/**
+ * Bitmap-gated: no-ops when `channel` is disabled. When enabled, emits
+ * a stage-token event recording the crossing of a runtime boundary.
+ * Powers D1 lineage — the chain commit.start → commit.apply.complete
+ * proves no silent short-circuit swallowed a mutation.
+ */
+export function emitStageToken(
+  bus: TelemetryBus,
+  channel: TelemetryChannel,
+  stage: string,
+  inputs: Record<string, unknown>,
+): void {
+  if (!bus.isEnabled(channel)) return;
+  bus.emit({
+    channel,
+    type: stage,
+    t: typeof performance !== "undefined" && typeof performance.now === "function"
+      ? performance.now()
+      : Date.now(),
+    payload: {
+      stageTokenId: String(++tokenSeq),
+      emittedAtUtc: new Date().toISOString(),
+      inputs: { ...inputs },
+    },
+  });
+}

package/src/runtime/debug/telemetry-bus.ts

@@ -0,0 +1,271 @@
+// @internal — TelemetryBus.
+//
+// Session-scoped runtime telemetry channel hub. Consumed by:
+//   1. `DocumentRuntime` — owns one bus per runtime; exposes it via
+//      `runtime.debug.getBus()`. Hook-points (parse/serialize/api/scope/
+//      warning/commit/…) call `bus.emit(...)` or `bus.emitLazy(...)`.
+//   2. The harness dev drawer — reads `bus.tail(channel, n)` for the live
+//      event trace card.
+//   3. The Phase 2 `services/debug/` Railway service — the hidden
+//      `/session/[id]` page exposes `window.__debug.setChannels({...})`
+//      and `window.__debug.tailTelemetry(n)` that proxy to the bus.
+//
+// Performance contract (CLAUDE.md perf invariants 1/4/7):
+//   - All channels default to OFF.
+//   - `isEnabled(channel)` is a single integer bitmask AND.
+//   - `emit(ev)` early-returns when the channel bit is off before doing any
+//     work beyond the check.
+//   - `emitLazy(channel, factory)` does NOT invoke the factory when the
+//     channel is off; used at hot hook-points where building the payload
+//     would itself allocate (e.g. stringifying args, computing digests).
+//   - Ring buffer writes overwrite in place — no allocation in steady state.
+//
+// Browser + Node safe. No DOM / no performance.now dependency (uses a small
+// `now()` helper that falls back to `Date.now()` when performance is absent).
+
+import { EventRingBuffer } from "./event-ring-buffer.ts";
+import type { RuntimeTelemetryEvent, TelemetryChannel } from "./types.ts";
+
+// The fixed channel order defines each channel's bit position in the bitmap.
+// Changing the order is a break — consumers of recorded traces rely on it.
+//
+// F-2: `render` / `command` / `commit` / `collab` / `layout` are RESERVED —
+// present in the union so `setChannels()` stays API-stable, but no emit sites
+// exist yet. Phase C wires them. See TelemetryChannel docstring for details.
+export const TELEMETRY_CHANNELS: readonly TelemetryChannel[] = [
+  "api",
+  "parse",
+  "serialize",
+  "render",
+  "command",
+  "scope",
+  "warning",
+  "selection",
+  "commit",
+  "collab",
+  "layout",
+  "io",
+  "formatting",
+] as const;
+
+const CHANNEL_BIT: Record<TelemetryChannel, number> = (() => {
+  const bits: Partial<Record<TelemetryChannel, number>> = {};
+  for (let i = 0; i < TELEMETRY_CHANNELS.length; i += 1) {
+    bits[TELEMETRY_CHANNELS[i]] = 1 << i;
+  }
+  return bits as Record<TelemetryChannel, number>;
+})();
+
+function now(): number {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+
+export interface TelemetryBusOptions {
+  /** Default ring size applied to every channel. Defaults to 256. */
+  readonly defaultRingSize?: number;
+  /** Channels to enable on construction. Default: none. */
+  readonly initialChannels?: readonly TelemetryChannel[];
+  /**
+   * Optional monotonic clock override. Defaults to `performance.now()` when
+   * available, else `Date.now()`. Used by tests for determinism.
+   */
+  readonly clock?: () => number;
+}
+
+export type TelemetryListener = (ev: RuntimeTelemetryEvent) => void;
+
+interface Subscription {
+  readonly mask: number;
+  readonly listener: TelemetryListener;
+}
+
+export class TelemetryBus {
+  private enabledMask = 0;
+  private readonly rings: Map<TelemetryChannel, EventRingBuffer<RuntimeTelemetryEvent>> = new Map();
+  private readonly subscriptions: Set<Subscription> = new Set();
+  private readonly defaultRingSize: number;
+  private readonly clock: () => number;
+  private seq = 0;
+
+  constructor(options: TelemetryBusOptions = {}) {
+    this.defaultRingSize = options.defaultRingSize ?? 256;
+    this.clock = options.clock ?? now;
+    for (const ch of TELEMETRY_CHANNELS) {
+      this.rings.set(ch, new EventRingBuffer<RuntimeTelemetryEvent>(this.defaultRingSize));
+    }
+    if (options.initialChannels) {
+      for (const ch of options.initialChannels) this.enable(ch);
+    }
+  }
+
+  enable(channel: TelemetryChannel): void {
+    this.enabledMask |= CHANNEL_BIT[channel];
+  }
+
+  disable(channel: TelemetryChannel): void {
+    this.enabledMask &= ~CHANNEL_BIT[channel];
+  }
+
+  /**
+   * Bulk-apply a partial channel record — `{parse: true, render: false}`.
+   * Absent keys are left unchanged.
+   */
+  setChannels(channels: Partial<Record<TelemetryChannel, boolean>>): void {
+    for (const ch of TELEMETRY_CHANNELS) {
+      const flag = channels[ch];
+      if (flag === true) this.enable(ch);
+      else if (flag === false) this.disable(ch);
+    }
+  }
+
+  /** Snapshot of the current channel flags. */
+  getChannels(): Record<TelemetryChannel, boolean> {
+    const out = {} as Record<TelemetryChannel, boolean>;
+    for (const ch of TELEMETRY_CHANNELS) {
+      out[ch] = (this.enabledMask & CHANNEL_BIT[ch]) !== 0;
+    }
+    return out;
+  }
+
+  isEnabled(channel: TelemetryChannel): boolean {
+    return (this.enabledMask & CHANNEL_BIT[channel]) !== 0;
+  }
+
+  /**
+   * Emit a pre-built event. The `t` + `seq` fields are filled in by the
+   * bus if absent on the input.
+   *
+   * Call sites that would otherwise allocate a payload before checking the
+   * channel flag should prefer `emitLazy(channel, factory)`.
+   */
+  emit(event: RuntimeTelemetryEvent): void {
+    const channel = event.channel;
+    if ((this.enabledMask & CHANNEL_BIT[channel]) === 0) return;
+    const stamped: RuntimeTelemetryEvent = {
+      ...event,
+      t: typeof event.t === "number" ? event.t : this.clock(),
+      seq: this.seq++,
+    } as RuntimeTelemetryEvent & { seq: number };
+    this.rings.get(channel)!.push(stamped);
+    this.dispatchToSubscribers(stamped);
+  }
+
+  /**
+   * Hot-path emit: the factory runs only when the channel is on. Used by
+   * parse/serialize/api hook-points that would otherwise pay the
+   * serialization cost every keystroke.
+   */
+  emitLazy(
+    channel: TelemetryChannel,
+    factory: () => Omit<RuntimeTelemetryEvent, "channel" | "t" | "seq">,
+  ): void {
+    if ((this.enabledMask & CHANNEL_BIT[channel]) === 0) return;
+    const base = factory();
+    const stamped: RuntimeTelemetryEvent = {
+      channel,
+      type: base.type,
+      payload: base.payload,
+      t: this.clock(),
+      seq: this.seq++,
+    } as RuntimeTelemetryEvent & { seq: number };
+    this.rings.get(channel)!.push(stamped);
+    this.dispatchToSubscribers(stamped);
+  }
+
+  subscribe(channels: readonly TelemetryChannel[], listener: TelemetryListener): () => void {
+    let mask = 0;
+    for (const ch of channels) mask |= CHANNEL_BIT[ch];
+    const sub: Subscription = { mask, listener };
+    this.subscriptions.add(sub);
+    return () => {
+      this.subscriptions.delete(sub);
+    };
+  }
+
+  /** Returns last n events from a channel, oldest first. */
+  tail(channel: TelemetryChannel, n: number): RuntimeTelemetryEvent[] {
+    return this.rings.get(channel)!.tail(n);
+  }
+
+  /**
+   * Returns last n events across all channels, merged and sorted by `seq`
+   * ascending (i.e. oldest emission first). When `n` exceeds the total,
+   * all buffered events are returned.
+   */
+  tailAll(n: number): RuntimeTelemetryEvent[] {
+    const merged: RuntimeTelemetryEvent[] = [];
+    for (const ring of this.rings.values()) {
+      const items = ring.all();
+      for (const it of items) merged.push(it);
+    }
+    merged.sort((a, b) => ((a as { seq?: number }).seq ?? 0) - ((b as { seq?: number }).seq ?? 0));
+    if (merged.length <= n) return merged;
+    return merged.slice(merged.length - n);
+  }
+
+  setRingSize(channel: TelemetryChannel, size: number): void {
+    if (!Number.isInteger(size) || size <= 0) {
+      throw new Error(`TelemetryBus ring size must be a positive integer, got ${size}`);
+    }
+    const existing = this.rings.get(channel)!.all();
+    const next = new EventRingBuffer<RuntimeTelemetryEvent>(size);
+    const carry = existing.slice(Math.max(0, existing.length - size));
+    for (const ev of carry) next.push(ev);
+    this.rings.set(channel, next);
+  }
+
+  clear(channel?: TelemetryChannel): void {
+    if (channel) {
+      this.rings.get(channel)!.clear();
+    } else {
+      for (const ring of this.rings.values()) ring.clear();
+    }
+  }
+
+  private dispatchToSubscribers(ev: RuntimeTelemetryEvent): void {
+    const bit = CHANNEL_BIT[ev.channel];
+    for (const sub of this.subscriptions) {
+      if ((sub.mask & bit) !== 0) {
+        try {
+          sub.listener(ev);
+        } catch {
+          // Subscriber failures must not take down emitters.
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Shared no-op bus for code paths that run before the runtime is
+ * instantiated (loader probes, error boundaries). `isEnabled` always
+ * returns false; `emit`/`emitLazy` do nothing; `subscribe` returns a
+ * no-op unsubscriber.
+ */
+export const NOOP_TELEMETRY_BUS: Pick<
+  TelemetryBus,
+  "emit" | "emitLazy" | "isEnabled" | "subscribe" | "tail" | "tailAll" | "getChannels"
+> = {
+  emit() {},
+  emitLazy() {},
+  isEnabled() {
+    return false;
+  },
+  subscribe() {
+    return () => {};
+  },
+  tail() {
+    return [];
+  },
+  tailAll() {
+    return [];
+  },
+  getChannels() {
+    const out = {} as Record<TelemetryChannel, boolean>;
+    for (const ch of TELEMETRY_CHANNELS) out[ch] = false;
+    return out;
+  },
+};