@hegemonart/get-design-done 1.21.0 → 1.23.0

package/scripts/lib/domain-primitives/wcag.cjs

@@ -0,0 +1,166 @@
+/**
+ * domain-primitives/wcag.cjs — minimal WCAG validator (Plan 23-09).
+ *
+ * Three checks (no axe-core dep):
+ *   1. Contrast ratio (WCAG 1.4.3 / 1.4.6) — given fg + bg colors,
+ *      compute the ratio. Pass: ≥4.5 (AA normal text), fail: <4.5.
+ *   2. Tap target size (WCAG 2.5.5 AAA / 2.5.8 AA) — given width+height
+ *      in CSS pixels, fail if either dimension <24 (AA) or <44 (AAA).
+ *   3. ARIA label presence — given a snippet of HTML, look for
+ *      <button>, <a>, <input> elements without an accessible name
+ *      (no text content AND no aria-label/aria-labelledby).
+ *
+ * All inputs are passed by the caller — this module does not parse
+ * arbitrary CSS or run a browser. Each check returns an Array<HeuristicHit>.
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} HeuristicHit
+ * @property {string} rule_id
+ * @property {'P0'|'P1'|'P2'|'P3'} severity
+ * @property {string} summary
+ * @property {string} [evidence]
+ * @property {number} [line]
+ * @property {string} file
+ */
+
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+function hexToRgb(hex) {
+  if (typeof hex !== 'string') return null;
+  const m = hex.match(HEX_RE);
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  return {
+    r: parseInt(h.slice(0, 2), 16),
+    g: parseInt(h.slice(2, 4), 16),
+    b: parseInt(h.slice(4, 6), 16),
+  };
+}
+
+function relLuminance({ r, g, b }) {
+  const channel = (v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+/**
+ * WCAG 1.4.3 contrast ratio between two colors.
+ * @param {string} fgHex
+ * @param {string} bgHex
+ * @returns {number} 1.0 to 21.0
+ */
+function contrastRatio(fgHex, bgHex) {
+  const fg = hexToRgb(fgHex);
+  const bg = hexToRgb(bgHex);
+  if (!fg || !bg) return NaN;
+  const lf = relLuminance(fg);
+  const lb = relLuminance(bg);
+  const [hi, lo] = lf > lb ? [lf, lb] : [lb, lf];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Check contrast against AA (4.5:1) or AAA (7:1) threshold.
+ *
+ * @param {{file: string, fg: string, bg: string, level?: 'AA'|'AAA', context?: string}} input
+ * @returns {HeuristicHit[]}
+ */
+function checkContrast(input) {
+  if (!input || typeof input.fg !== 'string' || typeof input.bg !== 'string') return [];
+  const ratio = contrastRatio(input.fg, input.bg);
+  const level = input.level ?? 'AA';
+  const minimum = level === 'AAA' ? 7 : 4.5;
+  if (Number.isNaN(ratio)) {
+    return [{
+      rule_id: 'wcag/1.4.3',
+      severity: 'P2',
+      summary: `unparseable color: fg=${input.fg} bg=${input.bg}`,
+      file: input.file,
+    }];
+  }
+  if (ratio >= minimum) return [];
+  return [{
+    rule_id: level === 'AAA' ? 'wcag/1.4.6' : 'wcag/1.4.3',
+    severity: ratio < 3 ? 'P0' : 'P1',
+    summary: `Contrast ratio ${ratio.toFixed(2)} below ${level} minimum ${minimum}:1`,
+    evidence: `fg=${input.fg}, bg=${input.bg}, ratio=${ratio.toFixed(2)}`,
+    file: input.file,
+  }];
+}
+
+/**
+ * Check tap target size (WCAG 2.5.5 / 2.5.8).
+ *
+ * @param {{file: string, width: number, height: number, level?: 'AA'|'AAA', name?: string}} input
+ * @returns {HeuristicHit[]}
+ */
+function checkTapTarget(input) {
+  if (!input || typeof input.width !== 'number' || typeof input.height !== 'number') return [];
+  const level = input.level ?? 'AA';
+  const min = level === 'AAA' ? 44 : 24;
+  if (input.width >= min && input.height >= min) return [];
+  return [{
+    rule_id: level === 'AAA' ? 'wcag/2.5.5' : 'wcag/2.5.8',
+    severity: 'P1',
+    summary: `Tap target ${input.width}×${input.height}px below ${level} minimum ${min}×${min}px${input.name ? ` (${input.name})` : ''}`,
+    evidence: `${input.width}×${input.height}`,
+    file: input.file,
+  }];
+}
+
+const INTERACTIVE_RE = /<(button|a|input)\b([^>]*)>([\s\S]*?)<\/\1>|<input\b([^>]*)\/?>/gi;
+
+/**
+ * Check that interactive elements have an accessible name.
+ *
+ * @param {{file: string, content: string}} input
+ * @returns {HeuristicHit[]}
+ */
+function checkAriaLabels(input) {
+  if (!input || typeof input.content !== 'string') return [];
+  const hits = [];
+  // Walk lines so we can attach line numbers.
+  const lines = input.content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i];
+    const elementMatches = [...ln.matchAll(/<(button|a|input)\b([^>]*?)(?:\s*\/)?>([^<]*)?/gi)];
+    for (const em of elementMatches) {
+      const tag = em[1].toLowerCase();
+      const attrs = em[2] || '';
+      const inner = (em[3] || '').trim();
+      const hasAriaLabel = /\baria-labell?e?d?b?y?\s*=/.test(attrs);
+      const hasTitle = /\btitle\s*=\s*["'][^"']+["']/.test(attrs);
+      const hasAlt = /\balt\s*=\s*["'][^"']+["']/.test(attrs);
+      if (tag === 'input') {
+        // Inputs with type=submit/button can rely on `value` attr.
+        const hasValue = /\bvalue\s*=\s*["'][^"']+["']/.test(attrs);
+        if (hasAriaLabel || hasTitle || hasValue) continue;
+      } else if (inner.length > 0 || hasAriaLabel || hasTitle || hasAlt) {
+        continue;
+      }
+      hits.push({
+        rule_id: 'wcag/4.1.2',
+        severity: 'P1',
+        summary: `<${tag}> has no accessible name (no text content + no aria-label/title)`,
+        evidence: em[0].slice(0, 200),
+        line: i + 1,
+        file: input.file,
+      });
+    }
+  }
+  return hits;
+}
+
+module.exports = {
+  contrastRatio,
+  hexToRgb,
+  checkContrast,
+  checkTapTarget,
+  checkAriaLabels,
+};

package/scripts/lib/event-chain.cjs

@@ -0,0 +1,177 @@
+/**
+ * event-chain.cjs — append-only causal event chain (Plan 22-04).
+ *
+ * Lives at `.design/gep/events.jsonl` (gep = "GDD Event Provenance").
+ * One JSONL line per event with parent-id linkage so consumers can
+ * walk decision → agent-spawn → outcome chains for retroactive audit.
+ *
+ * Schema:
+ *   {
+ *     event_id:        UUIDv4 (random)
+ *     parent_event_id: string | null
+ *     ts:              ISO-8601
+ *     agent:           string
+ *     decision_refs:   string[]   // STATE.md decision IDs (D-NN, etc.)
+ *     outcome:         string     // free-form: 'pass' / 'fail' / 'rolled-back' / …
+ *     rollback_reason: string?    // present iff outcome = 'rolled-back'
+ *     ...rest:         opaque caller-supplied fields preserved verbatim
+ *   }
+ *
+ * Why a separate file from .design/telemetry/events.jsonl:
+ *   * the chain is a CAUSAL overlay — rows have semantic meaning
+ *   * the general event-stream is a high-volume firehose
+ *   * /gdd:audit --retroactive walks the chain; it should not have to
+ *     scan a 100k-line firehose for causal rows
+ */
+
+'use strict';
+
+const { appendFileSync, mkdirSync, readFileSync, existsSync } = require('node:fs');
+const { dirname, isAbsolute, join, resolve } = require('node:path');
+const { randomUUID } = require('node:crypto');
+
+const DEFAULT_CHAIN_PATH = '.design/gep/events.jsonl';
+
+/**
+ * Resolve the on-disk chain file path, honouring an absolute override.
+ *
+ * @param {{baseDir?: string, path?: string}} [opts]
+ * @returns {string}
+ */
+function chainPathFor(opts = {}) {
+  if (opts.path) {
+    return isAbsolute(opts.path) ? opts.path : resolve(opts.baseDir ?? process.cwd(), opts.path);
+  }
+  const base = opts.baseDir ?? process.cwd();
+  return resolve(base, DEFAULT_CHAIN_PATH);
+}
+
+/**
+ * Append one chain event. Returns the event_id (caller may not have
+ * supplied one).
+ *
+ * Required fields: agent, outcome.
+ * Optional: parent_event_id, decision_refs, rollback_reason, plus any
+ * opaque extra fields which are preserved verbatim.
+ *
+ * @param {{
+ *   event_id?: string,
+ *   parent_event_id?: string | null,
+ *   agent: string,
+ *   decision_refs?: string[],
+ *   outcome: string,
+ *   rollback_reason?: string,
+ *   ts?: string,
+ *   path?: string,
+ *   baseDir?: string,
+ *   [k: string]: unknown,
+ * }} input
+ * @returns {string} event_id
+ */
+function appendChainEvent(input) {
+  if (!input || typeof input.agent !== 'string' || input.agent.length === 0) {
+    throw new TypeError('appendChainEvent: agent is required');
+  }
+  if (typeof input.outcome !== 'string' || input.outcome.length === 0) {
+    throw new TypeError('appendChainEvent: outcome is required');
+  }
+  const event_id = input.event_id || randomUUID();
+  const record = {
+    event_id,
+    parent_event_id: input.parent_event_id ?? null,
+    ts: input.ts || new Date().toISOString(),
+    agent: input.agent,
+    decision_refs: Array.isArray(input.decision_refs) ? input.decision_refs : [],
+    outcome: input.outcome,
+  };
+  if (input.rollback_reason !== undefined) {
+    record.rollback_reason = input.rollback_reason;
+  }
+  // Preserve opaque extras (any keys not already on `record`).
+  for (const key of Object.keys(input)) {
+    if (key === 'path' || key === 'baseDir') continue;
+    if (!(key in record)) {
+      record[key] = input[key];
+    }
+  }
+  const path = chainPathFor({ baseDir: input.baseDir, path: input.path });
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(record) + '\n', { flag: 'a' });
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `[event-chain] write failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+  return event_id;
+}
+
+/**
+ * Read the chain file and yield each parsed record. Invalid JSON lines
+ * are skipped with a stderr warning.
+ *
+ * @param {{path?: string, baseDir?: string}} [opts]
+ * @returns {Generator<Record<string, unknown>>}
+ */
+function* readChain(opts = {}) {
+  const path = chainPathFor(opts);
+  if (!existsSync(path)) return;
+  const raw = readFileSync(path, 'utf8');
+  let lineNum = 0;
+  for (const line of raw.split('\n')) {
+    lineNum += 1;
+    if (line.trim() === '') continue;
+    try {
+      yield JSON.parse(line);
+    } catch (err) {
+      try {
+        process.stderr.write(
+          `[event-chain] skipping invalid line ${lineNum} at ${path}\n`,
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+}
+
+/**
+ * Walk parents of `event_id` until reaching a row with no parent.
+ * Returns the chain in caller-→-root order, i.e. `[event, parent, …]`.
+ *
+ * Returns an empty array if the event_id is not found.
+ *
+ * @param {string} event_id
+ * @param {{path?: string, baseDir?: string}} [opts]
+ * @returns {Array<Record<string, unknown>>}
+ */
+function walkParents(event_id, opts = {}) {
+  /** @type {Map<string, Record<string, unknown>>} */
+  const byId = new Map();
+  for (const ev of readChain(opts)) {
+    byId.set(/** @type {string} */ (ev.event_id), ev);
+  }
+  const chain = [];
+  /** @type {string | null | undefined} */
+  let id = event_id;
+  const visited = new Set();
+  while (id && byId.has(id) && !visited.has(id)) {
+    visited.add(id);
+    const ev = byId.get(id);
+    chain.push(ev);
+    id = /** @type {string | null | undefined} */ (ev.parent_event_id);
+  }
+  return chain;
+}
+
+module.exports = {
+  appendChainEvent,
+  readChain,
+  walkParents,
+  chainPathFor,
+  DEFAULT_CHAIN_PATH,
+};

package/scripts/lib/event-stream/index.ts

@@ -33,11 +33,31 @@ export type {
   StageExitedEvent,
   HookFiredEvent,
   ErrorEvent,
+  WaveStartedEvent,
+  WaveCompletedEvent,
+  BlockerAddedEvent,
+  DecisionAddedEvent,
+  MustHaveAddedEvent,
+  ParallelismVerdictEvent,
+  CostUpdateEvent,
+  RateLimitEvent,
+  ApiRetryEvent,
+  CompactBoundaryEvent,
+  McpProbeEvent,
+  ReflectionProposedEvent,
+  ConnectionStatusChangeEvent,
+  ToolCallStartedEvent,
+  ToolCallCompletedEvent,
+  AgentSpawnEvent,
+  AgentOutcomeEvent,
 } from './types.ts';
+export { KNOWN_EVENT_TYPES } from './types.ts';
 export { EventBus } from './emitter.ts';
 export type { EventHandler, Unsubscribe } from './emitter.ts';
 export { EventWriter, DEFAULT_EVENTS_PATH, DEFAULT_MAX_LINE_BYTES } from './writer.ts';
 export type { WriterOptions } from './writer.ts';
+export { readEvents, aggregate } from './reader.ts';
+export type { ReadEventsOptions, AggregateResult } from './reader.ts';
 
 /**
  * Lazily-constructed module-level singletons. `getWriter()` honors the

package/scripts/lib/event-stream/reader.ts

@@ -0,0 +1,139 @@
+// scripts/lib/event-stream/reader.ts — typed JSONL reader + aggregator
+// (Plan 22-05).
+//
+// `readEvents()` is a streaming async iterator over the persisted event
+// log. It uses `readline` over a `fs.createReadStream`, so the entire
+// file is never held in memory — events.jsonl can grow to gigabytes
+// without OOM-ing a tail consumer.
+//
+// `aggregate()` collects an event iterable into a structured rollup
+// (counts by type / stage / cycle / agent + totals). Aggregation
+// always materialises the iterator, so callers that already have very
+// large logs should pre-filter via `readEvents({filter: …})` before
+// aggregating.
+
+import { createReadStream, existsSync, type ReadStream } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import type { BaseEvent } from './types.ts';
+import { DEFAULT_EVENTS_PATH } from './writer.ts';
+
+/** Options for {@link readEvents}. */
+export interface ReadEventsOptions {
+  /** Source file path. Default: `.design/telemetry/events.jsonl` (resolved against cwd). */
+  path?: string;
+  /** Resolution base for relative `path`. Default: `process.cwd()`. */
+  baseDir?: string;
+  /** Match by event type — string is exact-equal, RegExp is `.test(type)`. */
+  type?: string | RegExp;
+  /** Custom predicate; runs after `type` filter if both are supplied. */
+  predicate?: (ev: BaseEvent) => boolean;
+  /** Inclusive lower bound on `timestamp` (ISO-8601 string). */
+  since?: string;
+  /** Inclusive upper bound on `timestamp` (ISO-8601 string). */
+  until?: string;
+}
+
+/** Result shape from {@link aggregate}. */
+export interface AggregateResult {
+  byType: Record<string, number>;
+  byStage: Record<string, number>;
+  byCycle: Record<string, number>;
+  byAgent: Record<string, number>;
+  totals: {
+    count: number;
+    error_count: number;
+    truncated_count: number;
+  };
+}
+
+/**
+ * Resolve the read path the same way the writer does: absolute paths
+ * win; relative paths resolve against `baseDir` (defaults to cwd).
+ */
+function resolveReadPath(opts: ReadEventsOptions): string {
+  const raw = opts.path ?? DEFAULT_EVENTS_PATH;
+  if (isAbsolute(raw)) return raw;
+  return resolve(opts.baseDir ?? process.cwd(), raw);
+}
+
+/**
+ * Stream events from the JSONL log line-by-line. Invalid JSON lines
+ * are skipped silently — the writer guarantees well-formed output, so
+ * a malformed line is a data-corruption signal that should not crash
+ * a tail consumer.
+ *
+ * Filters apply in this order: type → predicate → since/until. The
+ * type filter is the cheapest, so it short-circuits first.
+ */
+export async function* readEvents(
+  opts: ReadEventsOptions = {},
+): AsyncIterable<BaseEvent> {
+  const path = resolveReadPath(opts);
+  if (!existsSync(path)) return;
+
+  const stream: ReadStream = createReadStream(path, { encoding: 'utf8' });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+  const typeRe = opts.type instanceof RegExp ? opts.type : null;
+  const typeStr = typeof opts.type === 'string' ? opts.type : null;
+
+  try {
+    for await (const line of rl) {
+      if (line.trim() === '') continue;
+      let ev: BaseEvent;
+      try {
+        ev = JSON.parse(line) as BaseEvent;
+      } catch {
+        continue;
+      }
+      if (typeStr !== null && ev.type !== typeStr) continue;
+      if (typeRe !== null && !typeRe.test(ev.type)) continue;
+      if (opts.predicate && !opts.predicate(ev)) continue;
+      if (opts.since !== undefined && ev.timestamp < opts.since) continue;
+      if (opts.until !== undefined && ev.timestamp > opts.until) continue;
+      yield ev;
+    }
+  } finally {
+    rl.close();
+    stream.close();
+  }
+}
+
+/**
+ * Synchronous aggregator that drains an iterable of events and rolls
+ * them up by type / stage / cycle / agent. `agent` is read from
+ * `payload.agent` (the trajectory + cost-update + agent.spawn shapes
+ * all expose it there).
+ */
+export async function aggregate(
+  events: AsyncIterable<BaseEvent> | Iterable<BaseEvent>,
+): Promise<AggregateResult> {
+  const result: AggregateResult = {
+    byType: {},
+    byStage: {},
+    byCycle: {},
+    byAgent: {},
+    totals: { count: 0, error_count: 0, truncated_count: 0 },
+  };
+
+  /** @param {Record<string, number>} bucket @param {string} key */
+  const inc = (bucket: Record<string, number>, key: string) => {
+    bucket[key] = (bucket[key] ?? 0) + 1;
+  };
+
+  for await (const ev of events as AsyncIterable<BaseEvent>) {
+    result.totals.count += 1;
+    inc(result.byType, ev.type);
+    if (ev.type === 'error') result.totals.error_count += 1;
+    if (ev._truncated === true) result.totals.truncated_count += 1;
+    if (ev.stage) inc(result.byStage, String(ev.stage));
+    if (ev.cycle) inc(result.byCycle, ev.cycle);
+    const payload = ev.payload as Record<string, unknown> | undefined;
+    if (payload && typeof payload['agent'] === 'string') {
+      inc(result.byAgent, payload['agent'] as string);
+    }
+  }
+  return result;
+}

package/scripts/lib/event-stream/types.ts

@@ -112,6 +112,112 @@ export type ErrorEvent = BaseEvent & {
   payload: { code: string; message: string; kind: string };
 };
 
+// ---------------------------------------------------------------------------
+// Phase 22 — pre-registered subtypes expansion (Plan 22-01)
+// ---------------------------------------------------------------------------
+
+/** Wave orchestration — Plan 21 parallel-mapper / wave execution. */
+export type WaveStartedEvent = BaseEvent & {
+  type: 'wave.started';
+  payload: { wave: string; plan_count: number };
+};
+export type WaveCompletedEvent = BaseEvent & {
+  type: 'wave.completed';
+  payload: { wave: string; duration_ms: number; outcome: 'pass' | 'fail' };
+};
+
+/** STATE.md mutation lifecycle (Plan 20-03). */
+export type BlockerAddedEvent = BaseEvent & {
+  type: 'blocker.added';
+  payload: { id: string; summary: string; source: string };
+};
+export type DecisionAddedEvent = BaseEvent & {
+  type: 'decision.added';
+  payload: { id: string; summary: string; source: string };
+};
+export type MustHaveAddedEvent = BaseEvent & {
+  type: 'must_have.added';
+  payload: { id: string; summary: string; source: string };
+};
+
+/** Parallelism decision engine output — Plan 21 explore-parallel-runner. */
+export type ParallelismVerdictEvent = BaseEvent & {
+  type: 'parallelism.verdict';
+  payload: { task_ids: string[]; verdict: 'parallel' | 'sequential'; reason: string };
+};
+
+/** Phase 10.1 cost-telemetry event-stream sink. */
+export type CostUpdateEvent = BaseEvent & {
+  type: 'cost.update';
+  payload: { agent: string; tier: string; usd: number; tokens_in: number; tokens_out: number };
+};
+
+/** Rate-guard / backoff stream (Plan 20-10, 20-11). */
+export type RateLimitEvent = BaseEvent & {
+  type: 'rate_limit';
+  payload: { provider: string; reset_at: string; remaining: number };
+};
+export type ApiRetryEvent = BaseEvent & {
+  type: 'api.retry';
+  payload: { provider: string; attempt: number; delay_ms: number; reason: string };
+};
+
+/** Context-window churn; emitted by `hooks/context-exhaustion.ts`. */
+export type CompactBoundaryEvent = BaseEvent & {
+  type: 'compact.boundary';
+  payload: { tokens_before: number; tokens_after: number };
+};
+
+/** MCP liveness probe from connection-probe primitive (Plan 22-08). */
+export type McpProbeEvent = BaseEvent & {
+  type: 'mcp.probe';
+  payload: { name: string; status: 'ok' | 'degraded' | 'down'; latency_ms?: number };
+};
+
+/** Reflector proposal (Phase 11 post-cycle reflector → event stream). */
+export type ReflectionProposedEvent = BaseEvent & {
+  type: 'reflection.proposed';
+  payload: { kind: string; target_file: string; summary: string };
+};
+
+/** Connection state transitions emitted by `connection-probe` (Plan 22-08). */
+export type ConnectionStatusChangeEvent = BaseEvent & {
+  type: 'connection.status_change';
+  payload: { name: string; from: string; to: string };
+};
+
+/** Per-tool-call trajectory (Plan 22-03). */
+export type ToolCallStartedEvent = BaseEvent & {
+  type: 'tool_call.started';
+  payload: { tool: string; args_hash: string };
+};
+export type ToolCallCompletedEvent = BaseEvent & {
+  type: 'tool_call.completed';
+  payload: {
+    tool: string;
+    args_hash: string;
+    result_hash: string;
+    latency_ms: number;
+    status: 'ok' | 'error';
+  };
+};
+
+/** Agent-level lifecycle (Plan 21 pipeline-runner / subagent spawn). */
+export type AgentSpawnEvent = BaseEvent & {
+  type: 'agent.spawn';
+  payload: { agent: string; task_id?: string; tier?: string };
+};
+export type AgentOutcomeEvent = BaseEvent & {
+  type: 'agent.outcome';
+  payload: {
+    agent: string;
+    task_id?: string;
+    outcome: 'pass' | 'fail' | 'halted';
+    duration_ms: number;
+    cost_usd?: number;
+  };
+};
+
 /**
  * Union of all pre-registered event types. Not a closed enum at the
  * envelope level — callers can emit unknown types — but downstream
@@ -124,4 +230,52 @@ export type KnownEvent =
   | StageEnteredEvent
   | StageExitedEvent
   | HookFiredEvent
-  | ErrorEvent;
+  | ErrorEvent
+  | WaveStartedEvent
+  | WaveCompletedEvent
+  | BlockerAddedEvent
+  | DecisionAddedEvent
+  | MustHaveAddedEvent
+  | ParallelismVerdictEvent
+  | CostUpdateEvent
+  | RateLimitEvent
+  | ApiRetryEvent
+  | CompactBoundaryEvent
+  | McpProbeEvent
+  | ReflectionProposedEvent
+  | ConnectionStatusChangeEvent
+  | ToolCallStartedEvent
+  | ToolCallCompletedEvent
+  | AgentSpawnEvent
+  | AgentOutcomeEvent;
+
+/**
+ * Runtime list of all pre-registered event `type` strings. Used by the
+ * Phase 22 baseline test and the CLI transport's `--list-types`
+ * subcommand.
+ */
+export const KNOWN_EVENT_TYPES: readonly string[] = [
+  'state.mutation',
+  'state.transition',
+  'stage.entered',
+  'stage.exited',
+  'hook.fired',
+  'error',
+  'wave.started',
+  'wave.completed',
+  'blocker.added',
+  'decision.added',
+  'must_have.added',
+  'parallelism.verdict',
+  'cost.update',
+  'rate_limit',
+  'api.retry',
+  'compact.boundary',
+  'mcp.probe',
+  'reflection.proposed',
+  'connection.status_change',
+  'tool_call.started',
+  'tool_call.completed',
+  'agent.spawn',
+  'agent.outcome',
+] as const;