vector-mirror 1.0.0

package/src/interface/tools.js

@@ -0,0 +1,437 @@
+/**
+ * tools.js - MCP Tool Definitions and Handlers (transport-agnostic)
+ * Vector Mirror v2.0 Phase 2
+ *
+ * Interface module: Exports { name, config, handler } per tool.
+ * BAUPLAN ref: Sektion 5 (Tools), 5.1 (Annotations), 7.3 (Architecture Separation), 9.3 (Descriptions)
+ * DEPENDS: pipeline.js, interface/schema.js
+ */
+import {
+  analyze,
+  analyzeErrorStructured,
+  arrange,
+  bookmark,
+  compare,
+  getConstraintTypes,
+  getStatus,
+  init,
+  inspect,
+  NO_BASELINE_HINT,
+  palette,
+  runSelftest,
+} from '../pipeline.js';
+// §RELAIS (an internal spec §0/§1) + P2/S1b Ein-Leib: die VOLLSTÄNDIGEN
+// Descriptions sind PROJEKTIONEN des Claims-Registers (claims.js — die eine
+// Quelle; Blöcke 1–3+5 via BLOCKS, Eigenheiten via EIGENHEITEN). tools.js
+// trägt KEINEN Description-Freitext mehr. Drift ist doppelt unmöglich: per
+// Konstruktion (Import) + per Protokoll-Selftest (tests/relais_red/
+// selftest_claims.mjs, S1 Wortidentität / S1b Vollstring-Pin / S2 Deckung).
+import { DESCRIPTIONS } from './claims.js';
+import {
+  analyzeInput,
+  analyzeOutput,
+  arrangeInput,
+  arrangeOutput,
+  bookmarkInput,
+  bookmarkOutput,
+  compareInput,
+  constraintsInput,
+  constraintsOutput,
+  inspectInput,
+  inspectOutput,
+  paletteInput,
+  paletteOutput,
+  selftestInput,
+  selftestOutput,
+  statusInput,
+  statusOutput,
+} from './schema.js';
+
+// ── ERROR RESPONSE HELPERS ──────────────────────────────────
+
+/** Schema-conformant error response for analyze/compare (outputSchema: analyzeOutput).
+ *  §H9 P2: die Hülle kommt aus pipeline.js#analyzeErrorStructured — EINE Quelle
+ *  statt physischer Kopie. Der frühere Inline-Spiegel trug denselben
+ *  Selbst-Widerspruch (isError:true + convergence:'SOLVED' + erfundene
+ *  randomUUID-analysisId); die wahre Form (null/null) lebt jetzt an genau
+ *  einem Ort und gilt für JS-API- und MCP-Rand identisch.
+ *  §6 RELAIS: optionales error{code,hint} aus der pipeline-Quelle wird additiv
+ *  eingebettet (NUR im isError-Pfad präsent; Parity: prose trägt den hint). */
+function analyzeErrorResponse(prose, error) {
+  return {
+    content: [{ type: 'text', text: prose }],
+    structuredContent: {
+      ...analyzeErrorStructured(),
+      ...(error ? { error } : {}),
+    },
+    isError: true,
+  };
+}
+
+/** Schema-conformant error response for inspect (outputSchema: inspectOutput).
+ *  §P2: scene.suppressed ist in inspectOutput REQUIRED (schema.js) — analog zum
+ *  analyzeErrorResponse-Muster (iteration.suppressed). Fehlt es, scheitert die
+ *  SDK-safeParse der structuredContent still. 0 = nichts getrunkt im Error-Pfad. */
+function inspectErrorResponse(prose, error) {
+  return {
+    content: [{ type: 'text', text: prose }],
+    structuredContent: {
+      scene: { width: 0, height: 0, grid: '0x0', elements: [], suppressed: 0 },
+      ...(error ? { error } : {}),
+    },
+    isError: true,
+  };
+}
+
+/** Schema-conformant error response for palette (outputSchema: paletteOutput). */
+function paletteErrorResponse(prose, error) {
+  return {
+    content: [{ type: 'text', text: prose }],
+    structuredContent: { colors: [], ...(error ? { error } : {}) },
+    isError: true,
+  };
+}
+
+/** Schema-conformant error response for bookmark (outputSchema: bookmarkOutput).
+ *  analysisId ist im Error-Pfad bereits eine validierte UUID (bookmarkInput
+ *  erzwingt .uuid()), erfüllt also bookmarkOutput.analysisId=.uuid(). */
+function bookmarkErrorResponse(prose, name, analysisId, error) {
+  return {
+    content: [{ type: 'text', text: prose }],
+    structuredContent: {
+      name: name ?? '',
+      analysisId,
+      stored: false,
+      bookmarkCount: 0,
+      ...(error ? { error } : {}),
+    },
+    isError: true,
+  };
+}
+
+// ── TOOL DEFINITIONS (registerTool-compatible) ──────────────
+
+/**
+ * Cluster 1: ANALYSE — vector_mirror_analyze
+ * BAUPLAN 5 Cluster 1 + 5.1 Annotations
+ */
+export const analyzeTool = {
+  name: 'vector_mirror_analyze',
+  config: {
+    // §RELAIS 5-Block-Form (an internal spec §1.1): Orientierung · Input-
+    // Grammatik · Output-Kernfelder · verifizierte Eigenheiten (Register-
+    // Projektion, endet mit P5-Zeile) · Next step. Budget ≤1300 Zeichen.
+    // P2/S1b: vollständig aus dem Register komponiert (claims.js BLOCKS).
+    description: DESCRIPTIONS.analyze,
+    inputSchema: analyzeInput,
+    outputSchema: analyzeOutput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  handler: async ({ svg, constraints, previousIssueCount }) => {
+    const result = await analyze(svg, constraints, previousIssueCount);
+    if (!result.structured)
+      return analyzeErrorResponse(result.prose, result.error);
+    return {
+      content: [{ type: 'text', text: result.prose }],
+      structuredContent: result.structured,
+    };
+  },
+};
+
+/**
+ * Cluster 1: ANALYSE — vector_mirror_compare
+ * BAUPLAN 5 Cluster 1 + 5.1 Annotations
+ */
+export const compareTool = {
+  name: 'vector_mirror_compare',
+  config: {
+    description: DESCRIPTIONS.compare,
+    inputSchema: compareInput,
+    outputSchema: analyzeOutput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+  },
+  handler: async ({ svg, constraints, analysisId }) => {
+    const result = await compare(svg, constraints, analysisId);
+    if (!result.structured)
+      return analyzeErrorResponse(result.prose, result.error);
+    return {
+      content: [{ type: 'text', text: result.prose }],
+      structuredContent: result.structured,
+      // §H9 K-13bc: der No-Baseline-Pfad liefert jetzt eine ehrliche non-null
+      // Hülle (statt null-Sentinel) — der Nutzungsfehler bleibt am MCP-Rand
+      // als isError projiziert (exakte Erkennung via NO_BASELINE_HINT, eine
+      // Quelle in pipeline.js; MCP-Verhalten wie vor H9).
+      ...(result.prose === NO_BASELINE_HINT ? { isError: true } : {}),
+    };
+  },
+};
+
+/**
+ * Cluster 1: ANALYSE — vector_mirror_bookmark
+ * §1.4 Globale Bookmarks (B-3, O1): Named-Baseline für den Sniper-Loop.
+ */
+export const bookmarkTool = {
+  name: 'vector_mirror_bookmark',
+  config: {
+    description: DESCRIPTIONS.bookmark,
+    inputSchema: bookmarkInput,
+    outputSchema: bookmarkOutput,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  handler: async ({ name, analysisId }) => {
+    const result = bookmark(name, analysisId);
+    if (!result.structured)
+      return bookmarkErrorResponse(
+        result.prose,
+        name,
+        analysisId,
+        result.error,
+      );
+    return {
+      content: [{ type: 'text', text: result.prose }],
+      structuredContent: result.structured,
+    };
+  },
+};
+
+/**
+ * Cluster 2: INSPEKTION — vector_mirror_inspect
+ * BAUPLAN 5 Cluster 2 + 5.1 Annotations
+ */
+export const inspectTool = {
+  name: 'vector_mirror_inspect',
+  config: {
+    description: DESCRIPTIONS.inspect,
+    inputSchema: inspectInput,
+    outputSchema: inspectOutput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  handler: async ({ svg }) => {
+    const result = await inspect(svg);
+    if (!result.structured)
+      return inspectErrorResponse(result.prose, result.error);
+    return {
+      content: [{ type: 'text', text: result.prose }],
+      structuredContent: result.structured,
+    };
+  },
+};
+
+/**
+ * Cluster 2: INSPEKTION — vector_mirror_palette
+ * BAUPLAN 5 Cluster 2 + 5.1 Annotations
+ */
+export const paletteTool = {
+  name: 'vector_mirror_palette',
+  config: {
+    description: DESCRIPTIONS.palette,
+    inputSchema: paletteInput,
+    outputSchema: paletteOutput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  handler: async ({ svg }) => {
+    const result = await palette(svg);
+    if (!result.structured)
+      return paletteErrorResponse(result.prose, result.error);
+    return {
+      content: [{ type: 'text', text: result.prose }],
+      structuredContent: result.structured,
+    };
+  },
+};
+
+/**
+ * Cluster 4: META — vector_mirror_constraints
+ * BAUPLAN 5 Cluster 4 + 5.1 Annotations
+ */
+export const constraintsTool = {
+  name: 'vector_mirror_constraints',
+  config: {
+    description: DESCRIPTIONS.constraints,
+    inputSchema: constraintsInput,
+    outputSchema: constraintsOutput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  handler: async () => {
+    const result = getConstraintTypes();
+    return {
+      content: [{ type: 'text', text: result.prose }],
+      structuredContent: result.structured,
+    };
+  },
+};
+
+/**
+ * Cluster 4: META — vector_mirror_status
+ * BAUPLAN 5 Cluster 4 + 5.1 Annotations
+ */
+export const statusTool = {
+  name: 'vector_mirror_status',
+  config: {
+    description: DESCRIPTIONS.status,
+    inputSchema: statusInput,
+    outputSchema: statusOutput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+  },
+  handler: async () => {
+    const result = getStatus();
+    return {
+      content: [{ type: 'text', text: result.prose }],
+      structuredContent: result.structured,
+    };
+  },
+};
+
+/**
+ * Cluster 3: EDITOR — vector_mirror_arrange
+ * BAUPLAN 5 Cluster 3 + 5.1 Annotations
+ */
+
+/** Schema-conformant error response for arrange (outputSchema: arrangeOutput). */
+function arrangeErrorResponse(prose, error) {
+  return {
+    content: [{ type: 'text', text: prose }],
+    structuredContent: {
+      attributes: {},
+      warnings: [prose],
+      ...(error ? { error } : {}),
+    },
+    isError: true,
+  };
+}
+
+export const arrangeTool = {
+  name: 'vector_mirror_arrange',
+  config: {
+    description: DESCRIPTIONS.arrange,
+    inputSchema: arrangeInput,
+    outputSchema: arrangeOutput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  handler: async ({ canvas, elements, constraints }) => {
+    try {
+      const result = arrange(canvas, elements, constraints);
+      // Defense-in-depth: sanitize NaN/Infinity before SDK validation (Audit Fix N)
+      const sanitized = JSON.parse(
+        JSON.stringify(result.structured, (_, v) =>
+          typeof v === 'number' && !Number.isFinite(v) ? 0 : v,
+        ),
+      );
+      return {
+        content: [{ type: 'text', text: result.prose }],
+        structuredContent: sanitized,
+      };
+    } catch (err) {
+      // §6 RELAIS: der Catch IST der Entstehungs-Ort dieses Fehlers (die
+      // pipeline wirft ohne Code) — ARRANGE_FAILED klassifiziert ihn, der
+      // hint trägt die geworfene Wahrheit und steht wortidentisch in der Prosa.
+      const hint = `Arrange fehlgeschlagen: ${err.message}`;
+      return arrangeErrorResponse(hint, { code: 'ARRANGE_FAILED', hint });
+    }
+  },
+};
+
+/**
+ * Cluster 4: META — vector_mirror_selftest (§1.9 Eichkörper-Selftest)
+ * 9. registriertes Tool. MISST nur (REGEL-3/9): läuft die 5 Kalibrierungs-
+ * Eichkörper (EK-1..5) und PARTIAL-matcht gegen die anti-zirk aus der Spec
+ * abgeleiteten expected-Felder (Grid/Farbe/Reliability-Wahrheit), NIE gegen
+ * gespeicherten Tool-Output (Anti-Zirkularität REGEL-2). Read-only, idempotent.
+ */
+export const selftestTool = {
+  name: 'vector_mirror_selftest',
+  config: {
+    description: DESCRIPTIONS.selftest,
+    inputSchema: selftestInput,
+    outputSchema: selftestOutput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  handler: async ({ full }) => {
+    const result = await runSelftest(full);
+    return {
+      content: [{ type: 'text', text: result.prose }],
+      structuredContent: result.structured,
+    };
+  },
+};
+
+// ── EXPORTS ─────────────────────────────────────────────────
+
+/** All tools as array for server.js registration loop. */
+export const tools = [
+  analyzeTool,
+  compareTool,
+  bookmarkTool,
+  inspectTool,
+  paletteTool,
+  arrangeTool,
+  constraintsTool,
+  statusTool,
+  selftestTool,
+];
+
+/**
+ * Legacy handler dispatcher (Phase 1 compatibility).
+ * Phase 2 uses server.js with registerTool() directly.
+ */
+export async function handleTool(name, args) {
+  await init();
+
+  try {
+    const tool = tools.find((t) => t.name === name);
+    if (!tool)
+      return { content: [{ type: 'text', text: `Unbekanntes Tool: ${name}` }] };
+    return await tool.handler(args);
+  } catch (err) {
+    return {
+      content: [
+        { type: 'text', text: `Vector Mirror Systemfehler: ${err.message}` },
+      ],
+    };
+  }
+}

package/src/lib/bbox.js

@@ -0,0 +1,17 @@
+/**
+ * bbox.js - Bounding-Box Mathematics
+ * Extracted from mirror.js:160-162
+ * Vector Mirror v2.0
+ */
+
+/**
+ * Returns true if two bounding boxes overlap.
+ */
+export function bboxOverlap(a, b) {
+  return !(
+    a.x + a.w <= b.x ||
+    b.x + b.w <= a.x ||
+    a.y + a.h <= b.y ||
+    b.y + b.h <= a.y
+  );
+}

package/src/lib/breaker.js

@@ -0,0 +1,240 @@
+/**
+ * breaker.js — Circuit-Breaker via Opossum 9.x (P1-03, VM-SM-002)
+ * Vector Mirror v2.5
+ *
+ * Schützt den Playwright-Browser vor "Permanent-Bricking" (VM-SM-002):
+ * Browser-Crashes oder Hangs öffnen den Breaker, Recovery erfolgt nach
+ * `resetTimeout` durch einen Liveness-Probe. User-Eingabefehler (ungültiges
+ * SVG, Size-Limit, Security-Violation) zählen NICHT gegen den Breaker —
+ * sie sind keine Browser-Fehler.
+ *
+ * Source-of-truth references:
+ *   - FIX_PLAN_2026-04-18 §1.2 P1-03 (revidiert via RB-11)
+ *   - RB-11 §6 Option A (Opossum 9.x adoptiert)
+ *   - RB-12 — BP/SOTA-Validation 2026-04-26 (Library-Source-of-Truth)
+ *   - ADR-030 (Eigenständigkeit) — Präzedenzfall in P1-03 dokumentiert
+ *   - KATALOG VM-SM-002 (Permanent-Bricking)
+ *   - Reproducer GEMINI-B2 (Browser-Crash-Recovery)
+ *
+ * Hexagonal-Vertrag: Lib module: keine Imports aus adapters/ oder interface/.
+ * `resolve` wird per Dependency-Injection an `createRenderOnce` übergeben.
+ *
+ * Opossum-Issue #564 Pitfall (relevant für errorFilter):
+ *   Wenn die Action einen Error WIRFT, dessen Code von errorFilter mit `true`
+ *   markiert wird, RESOLVED Opossum die `fire()`-Promise mit dem Error-Objekt
+ *   als Wert (statt zu rejecten). USER-Fehler dürfen daher NIE geworfen werden,
+ *   nur als Return-Object durchgereicht. `renderOnce` hält diesen Vertrag.
+ */
+
+import CircuitBreaker from 'opossum';
+
+/**
+ * Error-Codes aus `playwright.resolve()`, die User-Input-Fehler darstellen.
+ * Diese werden als reguläre Returns durchgereicht und zählen NICHT gegen
+ * den Breaker (der Browser ist gesund — der Input ist das Problem).
+ * @type {ReadonlySet<string>}
+ */
+export const USER_ERROR_CODES = Object.freeze(
+  new Set([
+    'INVALID_INPUT',
+    'SECURITY_VIOLATION',
+    'SVG_TOO_LARGE',
+    'NO_SVG_FOUND',
+    'EMPTY_SVG',
+    'TOO_MANY_ELEMENTS',
+    'NO_ELEMENTS',
+  ]),
+);
+
+/**
+ * Error-Codes, die einen Browser-Defekt anzeigen (page.setContent timeout,
+ * page.evaluate-Crash). Diese werden als geworfene Fehler weitergereicht,
+ * damit der Breaker sie zählen kann.
+ * @type {ReadonlySet<string>}
+ */
+export const BROWSER_ERROR_CODES = Object.freeze(new Set(['LOAD_FAILED']));
+
+/**
+ * Erzeugt eine `renderOnce`-Funktion, die einen Browser-Wrapper für `resolve()`
+ * darstellt: macht aus Browser-Fehler-Returns geworfene Errors mit `err.code`
+ * + `err.kind = 'BROWSER'`. User-Fehler bleiben als Returns durchgereicht.
+ *
+ * Hexagonal-DI: `resolveFn` wird injiziert (`pipeline.js` importiert sowohl
+ * `createRenderOnce` aus breaker.js als auch `resolve` aus playwright.js und
+ * verkabelt sie). breaker.js bleibt frei von adapters/-Imports.
+ *
+ * @param {Function} resolveFn  z.B. `playwright.resolve` (page, svgString) → Result
+ * @returns {Function}          (page, svgString) → Promise<Result>
+ */
+export function createRenderOnce(resolveFn) {
+  if (typeof resolveFn !== 'function') {
+    throw new TypeError('createRenderOnce: resolveFn muss Function sein');
+  }
+  return async function renderOnce(page, svgString) {
+    if (!page) {
+      const err = new Error('Playwright-Page nicht initialisiert');
+      err.code = 'NO_PAGE';
+      err.kind = 'BROWSER';
+      throw err;
+    }
+    const result = await resolveFn(page, svgString);
+    if (
+      result &&
+      typeof result === 'object' &&
+      result.error &&
+      BROWSER_ERROR_CODES.has(result.error)
+    ) {
+      const err = new Error(result.message || result.error);
+      err.code = result.error;
+      err.kind = 'BROWSER';
+      throw err;
+    }
+    return result;
+  };
+}
+
+/**
+ * Default-Optionen gemäß FIX_PLAN P1-03 + 1xAPI 2026 BP-Defaults
+ * (RB-12 §2.1 Quellenabgleich, identisch zu 1xAPI-Snippet).
+ * Tests können via `createBreaker(action, { ... })` überschreiben (z.B.
+ * `resetTimeout: 50` für schnelle State-Transitions).
+ */
+export const DEFAULT_BREAKER_OPTS = Object.freeze({
+  timeout: 5000, // per-call abort
+  errorThresholdPercentage: 50, // 50% Fail-Rate öffnet
+  resetTimeout: 30000, // half-open nach 30s
+  volumeThreshold: 5, // min 5 Fires vor Trip
+  rollingCountTimeout: 10000, // 10s sliding window
+  // §1.7 P5 Bulkhead: Singleton-Browser → capacity:1. Parallele Renders
+  // konkurrieren sonst um dieselbe Page (pageMutex in playwright.js
+  // serialisiert bereits setContent+evaluate; capacity:1 ist die
+  // Breaker-Ebene-Defense-in-Depth). Der 2. konkurrente fire wird mit
+  // ESEMLOCKED abgewiesen (fireResolve mappt das auf 'Concurrency-Limit
+  // erreicht'). Opossum-Semaphore (circuit.js Semaphore(capacity)).
+  capacity: 1,
+  name: 'render', // Multi-Breaker-Observability
+});
+
+/**
+ * Default `errorFilter`: USER-Fehler (Input-Probleme) zählen nicht.
+ * Browser-Fehler (`kind === 'BROWSER'`) zählen.
+ *
+ * Opossum-Konvention (RB-12 §2.2): `errorFilter(err) === true` ⇒ Fehler
+ * wird IGNORIERT (failure-stat nicht inkrementiert).
+ *
+ * VORSICHT (Issue #564): Diese Funktion wird nur ausgewertet, wenn die
+ * Action einen Error WIRFT. Ein gefilterter Error führt dann dazu, dass
+ * `fire()` mit dem Error-Objekt RESOLVED. Daher: USER-Codes dürfen niemals
+ * geworfen werden — `renderOnce` hält diesen Vertrag.
+ *
+ * @param {Error & {code?: string, kind?: string}} err
+ * @returns {boolean} true → ignorieren, false → zählen
+ */
+export function defaultErrorFilter(err) {
+  if (!err) return false;
+  if (err.kind === 'BROWSER') return false;
+  if (err.code && USER_ERROR_CODES.has(err.code)) return true;
+  return false;
+}
+
+/**
+ * Erzeugt einen Circuit-Breaker für die übergebene Action.
+ * Die Action wird i.d.R. via `createRenderOnce(resolveFn)` erzeugt.
+ *
+ * @param {Function} action  z.B. das Resultat von `createRenderOnce(resolve)`
+ * @param {object}   [opts]  Override gegen DEFAULT_BREAKER_OPTS
+ * @returns {CircuitBreaker}
+ */
+export function createBreaker(action, opts = {}) {
+  if (typeof action !== 'function') {
+    throw new TypeError('createBreaker: action muss Function sein');
+  }
+  const finalOpts = {
+    ...DEFAULT_BREAKER_OPTS,
+    errorFilter: defaultErrorFilter,
+    ...opts,
+  };
+  return new CircuitBreaker(action, finalOpts);
+}
+
+/**
+ * Re-Export von `CircuitBreaker.isOurError` für Pipeline-Integration:
+ * unterscheidet CB-eigene Rejections (EOPENBREAKER, ETIMEDOUT, ESHUTDOWN,
+ * ESEMLOCKED) von Action-Errors. Hilft, structuredContent-Codes korrekt zu
+ * mappen (Browser-Defekt vs. Breaker-Schutz).
+ *
+ * @param {Error} err
+ * @returns {boolean} true wenn Error vom Breaker selbst stammt
+ */
+export const isOurError = CircuitBreaker.isOurError;
+
+/**
+ * Liveness-Probe: Race zwischen `page.evaluate(() => 1)` und einem Timeout.
+ * Wird in pipeline.init() nach createResolver() aufgerufen, um zu erkennen,
+ * ob die Seite wirklich nutzbar ist (Crash-Detection vor erstem Render).
+ *
+ * Optional kann die Pipeline zusätzlich `breaker.healthCheck(() =>
+ * livenessPing(page), 30000)` als Hintergrund-Watchdog verkabeln (Opossum
+ * öffnet dann den Breaker bei Reject automatisch). RB-12 §2.4.
+ *
+ * @param {object} page
+ * @param {number} [timeoutMs=1000]
+ * @returns {Promise<boolean>}  true bei healthy, wirft sonst
+ */
+export async function livenessPing(page, timeoutMs = 1000) {
+  if (!page) {
+    const err = new Error('Playwright-Page nicht initialisiert');
+    err.code = 'NO_PAGE';
+    throw err;
+  }
+  let timer;
+  const timeoutP = new Promise((_, rej) => {
+    timer = setTimeout(() => {
+      const err = new Error(`Liveness-Ping Timeout nach ${timeoutMs}ms`);
+      err.code = 'LIVENESS_TIMEOUT';
+      rej(err);
+    }, timeoutMs);
+  });
+  try {
+    const value = await Promise.race([page.evaluate(() => 1), timeoutP]);
+    return value === 1;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Komprimiert breaker.stats für `vector_mirror_status` structured-Output.
+ * Subset gewählt: 6 Counter + name + semaphoreRejections + latencyMean.
+ * RB-12 §2.3 Quellenabgleich.
+ *
+ * @param {CircuitBreaker} breaker
+ * @returns {{
+ *   name: string,
+ *   state: 'open'|'half-open'|'closed',
+ *   fires: number, successes: number, failures: number,
+ *   timeouts: number, rejects: number, fallbacks: number,
+ *   semaphoreRejections: number, latencyMean: number
+ * }}
+ */
+export function getBreakerStats(breaker) {
+  if (!breaker) {
+    throw new TypeError('getBreakerStats: breaker required');
+  }
+  let state = 'closed';
+  if (breaker.opened) state = 'open';
+  else if (breaker.halfOpen) state = 'half-open';
+  const s = breaker.stats;
+  return {
+    name: breaker.name,
+    state,
+    fires: s.fires,
+    successes: s.successes,
+    failures: s.failures,
+    timeouts: s.timeouts,
+    rejects: s.rejects,
+    fallbacks: s.fallbacks,
+    semaphoreRejections: s.semaphoreRejections,
+    latencyMean: s.latencyMean,
+  };
+}