@sanqianx/ai-coding-event-bridge-console 0.5.1 → 0.7.0

package/src/bridge/connectors/codex/hook-entry.js

@@ -0,0 +1,215 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { validateAndNormalizeEvent } = require('../../core/event-schema');
+const { resolveRepoContext } = require('../../core/repo-context');
+const { journalFor } = require('../../core/journal-router');
+const { CodexCursorStore } = require('./cursor-store');
+const { parseSessionChunk, extractMessage, extractWorkspaceMeta } = require('./session-parser');
+const { isCaptureDisabled, captureDisabledResult } = require('../capture-guard');
+const { notifyConsumers } = require('../claude-code/notify');
+const { CrossProcessLock } = require('../../core/lock');
+
+/**
+ * Deterministic Codex capture.
+ *
+ * The notify payload is only a wake-up signal; it never carries the workspace.
+ * The real workspace comes from the session's authoritative rollout metadata
+ * (session_meta.payload.cwd / turn_context.payload.cwd) — NEVER from the
+ * session file's location, which is Codex runtime storage. Bytes are consumed
+ * incrementally per session; a partial trailing line stays unread until the
+ * next wake-up. When no authoritative cwd can be parsed, a
+ * codex-workspace-unresolved gap is recorded and the event is never bound to
+ * any project.
+ */
+
+function recordGap(home, reason, meta = {}) {
+  try {
+    const gapsFile = path.join(home, 'journal', 'capture-gaps.jsonl');
+    fs.mkdirSync(path.dirname(gapsFile), { recursive: true });
+    fs.appendFileSync(
+      gapsFile,
+      `${JSON.stringify({ schema: 'bridge-capture-gap/v1', source: 'codex', reason, ...meta, at: new Date().toISOString() })}\n`
+    );
+  } catch (_) {
+    // Gap persistence is best effort; the decision to not guess stands regardless.
+  }
+}
+
+function normalizedPath(filePath) {
+  const resolved = path.resolve(filePath);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function fileKey(sessionsRoot, filePath) {
+  return path.relative(path.resolve(sessionsRoot), path.resolve(filePath)).split(path.sep).join('/');
+}
+
+async function findSessionFiles(sessionsRoot, sessionId) {
+  // Deterministic discovery: Codex rollout files embed the session id in the
+  // file name; we search by exact id, never by mtime.
+  const stack = [sessionsRoot];
+  const matches = [];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_) {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && entry.name.endsWith('.jsonl') && entry.name.includes(sessionId)) {
+        matches.push(full);
+      }
+    }
+  }
+  return matches.sort((left, right) => fileKey(sessionsRoot, left).localeCompare(fileKey(sessionsRoot, right)));
+}
+
+async function findSessionFile(sessionsRoot, sessionId) {
+  const files = await findSessionFiles(sessionsRoot, sessionId);
+  return files[0] || null;
+}
+
+function emptyFileState(filePath) {
+  return {
+    filePath,
+    byteOffset: 0,
+    lastRecordKey: null,
+    activeCwd: null,
+    repoIdentity: null,
+    projectPath: null,
+    branch: null,
+    headAtCapture: null
+  };
+}
+
+async function captureSessionUnlocked({ home, sessionsRoot, sessionId, cursorStore }) {
+  const cursor = cursorStore.read(sessionId);
+  const filePaths = await findSessionFiles(sessionsRoot, sessionId);
+  if (!filePaths.length) {
+    recordGap(home, 'session-file-not-found', { sessionId });
+    return { status: 'gap', reason: 'session-file-not-found' };
+  }
+
+  if (cursor.legacyFile) {
+    const legacyMatch = filePaths.find(candidate => normalizedPath(candidate) === normalizedPath(cursor.legacyFile.filePath));
+    if (legacyMatch) {
+      cursor.files[fileKey(sessionsRoot, legacyMatch)] = { ...cursor.legacyFile, filePath: legacyMatch };
+    }
+    delete cursor.legacyFile;
+  }
+
+  let captured = 0;
+  let completeBytes = 0;
+
+  for (const filePath of filePaths) {
+    const key = fileKey(sessionsRoot, filePath);
+    const state = cursor.files[key] || emptyFileState(filePath);
+    state.filePath = filePath;
+    const fromOffset = state.byteOffset || 0;
+    const parsed = parseSessionChunk(filePath, fromOffset);
+    let unresolvedGapRecorded = false;
+
+    for (let index = 0; index < parsed.records.length; index += 1) {
+      const record = parsed.records[index];
+      const meta = extractWorkspaceMeta(record);
+      if (meta) {
+        if (meta.cwd && meta.cwd !== state.activeCwd) {
+          // Authoritative workspace switch (session start or turn_context change).
+          const repo = await resolveRepoContext(meta.cwd);
+          state.activeCwd = meta.cwd;
+          state.repoIdentity = repo.repoIdentity;
+          state.projectPath = repo.projectPath;
+          state.branch = repo.branch;
+          state.headAtCapture = repo.headAtCapture;
+        }
+        continue;
+      }
+      const message = extractMessage(record);
+      if (!message) continue;
+      if (!state.repoIdentity && !unresolvedGapRecorded) {
+        recordGap(home, 'codex-workspace-unresolved', { sessionId, rolloutFile: key });
+        unresolvedGapRecorded = true;
+      }
+      const byteOffset = parsed.recordOffsets[index];
+      const recordKey = `${key}:${byteOffset}`;
+      const event = validateAndNormalizeEvent({
+        source: 'codex',
+        eventType: message.role === 'user' ? 'user_prompt' : 'assistant_response',
+        role: message.role,
+        content: message.text,
+        sessionId,
+        turnId: message.turnId,
+        repoIdentity: state.repoIdentity,
+        projectPath: state.projectPath,
+        branch: state.branch,
+        headAtCapture: state.headAtCapture,
+        identityConfidence: message.turnId ? 'exact' : 'partial',
+        captureStatus: 'complete',
+        rawEventType: record.type || 'message',
+        eventKey: `codex:${sessionId}:${recordKey}`,
+        meta: { recordKey, rolloutFile: key, byteOffset, phase: message.phase }
+      });
+      // The workspace can switch mid-session (turn_context), so the journal is
+      // routed per record from the authoritative identity, never per session.
+      const journal = journalFor(home, state.repoIdentity);
+      const appended = await journal.appendConversationEvent(event);
+      state.lastRecordKey = recordKey;
+      if (!appended.duplicate) captured += 1;
+    }
+
+    state.byteOffset = fromOffset + parsed.completeBytes;
+    cursor.files[key] = state;
+    completeBytes += parsed.completeBytes;
+  }
+
+  cursorStore.write(sessionId, cursor);
+  return { status: 'captured', captured, files: filePaths.length, completeBytes };
+}
+
+async function captureSession({ home, sessionsRoot, sessionId }) {
+  const cursorStore = new CodexCursorStore(home);
+  const safe = String(sessionId).replace(/[^A-Za-z0-9._-]/g, '_');
+  const lock = new CrossProcessLock(path.join(home, 'cursors', 'codex', `${safe}.capture.lock`));
+  return lock.withLock(() => captureSessionUnlocked({ home, sessionsRoot, sessionId, cursorStore }));
+}
+
+async function main({ home, payload }) {
+  if (isCaptureDisabled(process.env, payload)) {
+    return captureDisabledResult();
+  }
+  if (!payload || typeof payload !== 'object') {
+    return { status: 'ignored' };
+  }
+  const sessionId = payload.session_id || payload.sessionId || null;
+  if (!sessionId || typeof sessionId !== 'string') {
+    // Ambiguous notify: never fall back to the newest session by mtime.
+    recordGap(home, 'notify-session-unresolved', { keys: Object.keys(payload).slice(0, 8) });
+    return { status: 'gap', reason: 'notify-session-unresolved' };
+  }
+  const sessionsRoot =
+    payload.sessions_root ||
+    (process.env.CODEX_SESSIONS_ROOT) ||
+    path.join(home, 'fixtures', 'codex-sessions');
+  const result = await captureSession({
+    home,
+    sessionsRoot,
+    sessionId
+  });
+  if (result.status === 'captured' && result.captured > 0) {
+    await notifyConsumers(home, { source: 'codex', sessionId });
+  }
+  return result;
+}
+
+function mainFailOpen({ home, payload }) {
+  return main({ home, payload }).catch(() => ({ status: 'fail-open' }));
+}
+
+module.exports = { main, mainFailOpen, captureSession, findSessionFile, findSessionFiles, recordGap };

package/src/bridge/connectors/codex/session-parser.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Incremental Codex session JSONL parser. Reads only appended bytes after the
+ * cursor offset, tolerates a partial trailing line, and classifies records
+ * into messages and workspace metadata. Never re-reads the whole file and
+ * never selects sessions by mtime — the caller identifies the session file
+ * deterministically.
+ */
+function parseSessionChunk(filePath, fromOffset) {
+  const size = fs.statSync(filePath).size;
+  if (size <= fromOffset) return { records: [], recordOffsets: [], completeBytes: 0, size };
+  const fd = fs.openSync(filePath, 'r');
+  let raw;
+  try {
+    const buf = Buffer.alloc(size - fromOffset);
+    const read = fs.readSync(fd, buf, 0, buf.length, fromOffset);
+    raw = buf.toString('utf8', 0, read);
+  } finally {
+    fs.closeSync(fd);
+  }
+  const records = [];
+  const recordOffsets = [];
+  let completeBytes = 0;
+  const chunks = raw.split('\n');
+  for (let i = 0; i < chunks.length; i++) {
+    const line = chunks[i];
+    if (i === chunks.length - 1) break; // trailing bytes without newline = partial
+    if (line.length === 0) {
+      completeBytes += 1;
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (_) {
+      parsed = null;
+    }
+    if (parsed && typeof parsed === 'object') {
+      records.push(parsed);
+      recordOffsets.push(fromOffset + completeBytes);
+    }
+    completeBytes += Buffer.byteLength(line, 'utf8') + 1;
+  }
+  return { records, recordOffsets, completeBytes, size };
+}
+
+/**
+ * Authoritative workspace metadata from Codex rollout records:
+ * session_meta.payload.cwd and turn_context.payload.cwd. A verified
+ * turn_context cwd may update the active workspace for subsequent events.
+ */
+function extractWorkspaceMeta(record) {
+  if (!record || typeof record !== 'object') return null;
+  const payload = record.payload && typeof record.payload === 'object' ? record.payload : null;
+  if (record.type === 'session_meta' || (payload && payload.type === 'session_meta')) {
+    const cwd = payload && typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : null;
+    return { kind: 'session_meta', cwd };
+  }
+  if (record.type === 'turn_context' || (payload && payload.type === 'turn_context')) {
+    const cwd = payload && typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : null;
+    return { kind: 'turn_context', cwd };
+  }
+  return null;
+}
+
+function extractMessage(record) {
+  if (!record || typeof record !== 'object') return null;
+  const payload = record.payload && typeof record.payload === 'object' ? record.payload : record;
+  const role = payload.role || record.role;
+  if (role !== 'user' && role !== 'assistant') return null;
+  const text = collectText(payload.content !== undefined ? payload.content : record.content);
+  if (text === null) return null;
+  const passthrough = payload.internal_chat_message_metadata_passthrough;
+  const nestedTurnId = passthrough && typeof passthrough === 'object' ? passthrough.turn_id : null;
+  return {
+    role,
+    text,
+    turnId: payload.turn_id || nestedTurnId || record.turn_id || null,
+    phase: typeof payload.phase === 'string' && payload.phase ? payload.phase : null
+  };
+}
+
+function collectText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    const parts = [];
+    for (const item of content) {
+      if (typeof item === 'string') parts.push(item);
+      else if (item && typeof item === 'object' && typeof item.text === 'string') parts.push(item.text);
+    }
+    if (parts.length) return parts.join('\n');
+    return null;
+  }
+  return null;
+}
+
+module.exports = { parseSessionChunk, extractMessage, extractWorkspaceMeta };

package/src/bridge/connectors/opencode/hook-entry.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const { validateAndNormalizeEvent } = require('../../core/event-schema');
+const { resolveRepoContext } = require('../../core/repo-context');
+const { journalFor } = require('../../core/journal-router');
+const { isCaptureDisabled, captureDisabledResult } = require('../capture-guard');
+const { notifyConsumers } = require('../claude-code/notify');
+
+/**
+ * OpenCode plugin capture. The plugin ships the native event to the stable
+ * shim; capture is a local durable append first via the canonical
+ * conversation path (Bridge-owned turn identity). There is no HTTP endpoint
+ * dependency — consumer wake-up uses the generic best-effort notify channel
+ * only. Capture-disable is checked before any repo/journal work.
+ */
+async function main({ home, payload }) {
+  if (isCaptureDisabled(process.env, payload)) {
+    return captureDisabledResult();
+  }
+  if (!payload || typeof payload !== 'object') {
+    return { status: 'ignored' };
+  }
+  if (payload.type !== 'user' && payload.type !== 'assistant') {
+    // Tool/file/todo lifecycle events stay out of the conversation truth.
+    return { status: 'ignored' };
+  }
+  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+  const repo = await resolveRepoContext(cwd);
+  const journal = journalFor(home, repo.repoIdentity);
+  const isUser = payload.type === 'user';
+  const event = validateAndNormalizeEvent({
+    source: 'opencode',
+    eventType: isUser ? 'user_prompt' : 'assistant_response',
+    role: isUser ? 'user' : 'assistant',
+    content: typeof payload.text === 'string' ? payload.text : null,
+    sessionId: payload.sessionId || payload.session_id || null,
+    turnId: payload.turnId || null,
+    repoIdentity: repo.repoIdentity,
+    projectPath: repo.projectPath,
+    branch: repo.branch,
+    headAtCapture: repo.headAtCapture,
+    identityConfidence: payload.sessionId ? (payload.turnId ? 'exact' : 'partial') : 'unavailable',
+    captureStatus: typeof payload.text === 'string' ? 'complete' : 'partial',
+    rawEventType: payload.type
+  });
+  const appended = await journal.appendConversationEvent(event);
+  await notifyConsumers(home, { source: 'opencode', sequence: appended.sequence, eventId: appended.eventId });
+  return { status: 'captured', sequence: appended.sequence, turnId: appended.turnId };
+}
+
+function mainFailOpen({ home, payload }) {
+  return main({ home, payload }).catch(() => ({ status: 'fail-open' }));
+}
+
+module.exports = { main, mainFailOpen };

package/src/bridge/core/bridge.js

@@ -0,0 +1,246 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { bridgeHome } = require('./paths');
+const { Journal } = require('./journal');
+const { ConsumerRegistry } = require('./consumer-registry');
+const { compactJournal } = require('./compaction');
+const { journalFor, globalJournalDir } = require('./journal-router');
+const projectRegistry = require('./project-registry');
+const { sealCommitConversations, sealDirFor } = require('./commit-projection');
+const { resolveRepoContext } = require('./repo-context');
+const { validateAndNormalizeEvent } = require('./event-schema');
+const { notifyConsumers } = require('../connectors/claude-code/notify');
+
+/**
+ * Stable host-facing facade over the Bridge runtime. Hosts (Project-Knowledge,
+ * DevTask-Radar, ...) must talk to this facade only — never to Journal
+ * internals or Bridge filesystem layout.
+ */
+function createBridge({ homeDir } = {}) {
+  const home = bridgeHome(homeDir);
+  // Lazy internals: constructing a facade must not touch the filesystem, so
+  // merely loading a Bridge (e.g. in a host test) creates no runtime home.
+  let journal = null;
+  let registry = null;
+  const getJournal = () => {
+    if (!journal) journal = new Journal(path.join(home, 'journal'));
+    return journal;
+  };
+  const getRegistry = () => {
+    if (!registry) registry = new ConsumerRegistry(home);
+    return registry;
+  };
+  // Pure reads on a machine where no Bridge home exists yet must not
+  // materialize one: status queries stay side-effect free.
+  const homeExists = () => fs.existsSync(home);
+  const selectJournal = (journalId = 'global') => {
+    if (journalId === 'global') return getJournal();
+    const project = projectRegistry.listProjects(home).find(p => p.id === journalId);
+    if (!project) throw Object.assign(new Error('journal is not registered'), { code: 'JOURNAL_NOT_FOUND' });
+    return journalFor(home, project.id);
+  };
+
+  return {
+    homeDir: home,
+
+    async listJournals() {
+      return [{ journalId: 'global', projectId: null }, ...projectRegistry.listProjects(home).map(p => ({ journalId: p.id, projectId: p.id, repoPath: p.path }))];
+    },
+
+    async getHighWatermark({ journalId = 'global' } = {}) {
+      if (!homeExists()) return 0;
+      const bounds = await selectJournal(journalId).getBounds();
+      return bounds.lastSequence;
+    },
+
+    async readEvents(options = {}) {
+      return selectJournal(options.journalId).readEvents(options);
+    },
+
+    // Host-side injection for tests and explicit workflows; automatic capture
+    // flows through the connectors' canonical append path.
+    async appendConversationEvent(event) {
+      return getJournal().appendConversationEvent(event);
+    },
+
+    async captureWorkbenchEvent(input) {
+      if (!['user_prompt', 'assistant_response', 'session_end'].includes(input?.eventType)
+        || typeof input.projectPath !== 'string' || !path.isAbsolute(input.projectPath)
+        || typeof input.eventKey !== 'string' || !input.eventKey.startsWith('workbench:')
+        || !input.sessionId || !input.turnId || input.content && (typeof input.content !== 'string' || input.content.length > 200000)) {
+        throw Object.assign(new Error('Invalid native workbench event'), { code: 'CAPTURE_INVALID' });
+      }
+      const repo = await resolveRepoContext(input.projectPath);
+      const project = projectRegistry.findProject(home, repo.repoIdentity);
+      if (!project || fs.realpathSync(project.path) !== fs.realpathSync(input.projectPath)) {
+        throw Object.assign(new Error('Workbench project is not registered'), { code: 'PROJECT_NOT_REGISTERED' });
+      }
+      const event = validateAndNormalizeEvent({
+        source: input.source, eventType: input.eventType, role: input.eventType === 'user_prompt' ? 'user' : input.eventType === 'assistant_response' ? 'assistant' : null,
+        content: input.eventType === 'session_end' ? undefined : input.content, sessionId: input.sessionId, turnId: input.turnId, eventKey: input.eventKey,
+        repoIdentity: repo.repoIdentity, projectPath: repo.projectPath, branch: repo.branch, headAtCapture: repo.headAtCapture,
+        capturedAt: typeof input.capturedAt === 'string' && !Number.isNaN(Date.parse(input.capturedAt)) ? input.capturedAt : new Date().toISOString(),
+        identityConfidence: 'exact', captureStatus: 'complete', meta: { origin: 'claude-ai-workbench', outcome: input.outcome === 'failed' ? 'failed' : 'completed' },
+      });
+      const appended = await journalFor(home, repo.repoIdentity).appendConversationEvent(event);
+      await notifyConsumers(home, { sequence: appended.sequence, eventId: appended.eventId });
+      return { status: 'captured', ...appended };
+    },
+
+    async appendCommitBoundary({ projectId, repoIdentity, commitSha, parentShas, parents, branch, subject, committedAt, operationId, meta } = {}) {
+      if (!repoIdentity) {
+        throw new Error('appendCommitBoundary requires repoIdentity');
+      }
+      // Boundaries live in the same journal as the repo's conversation events
+      // (openTurnIdsAtCommit is computed from that journal's open-turn state).
+      const journal = journalFor(home, repoIdentity);
+      const result = await journal.appendCommitBoundary(repoIdentity, {
+        commitSha,
+        parents: parents !== undefined ? parents : parentShas,
+        branch,
+        subject,
+        committedAt,
+        projectId,
+        operationId,
+        meta
+      });
+      const routed = journal.journalDir !== globalJournalDir(home);
+      let bridgeCursorAtCommit = result.sequence;
+      if (routed) {
+        // Routed to a registered project's journal: the boundary is not in the
+        // global journal, so the global consumer watermark is unchanged. Keep
+        // the returned cursor conservative (never past unseen global content).
+        const bounds = await getJournal().getBounds();
+        bridgeCursorAtCommit = bounds.lastSequence;
+      }
+      // A routed boundary means a registered project just committed: freeze
+      // that commit's conversations into <store>/commits/<sha>.md. Projection
+      // failures are reported, never thrown — the journal remains the only
+      // source of truth and the boundary is already durable.
+      let projection = { sealed: false, turnCount: 0, reason: routed ? 'project-not-registered' : 'global-journal' };
+      if (routed) {
+        try {
+          const project = projectRegistry.findProject(home, repoIdentity);
+          if (project) {
+            const sealDir = sealDirFor(project.store);
+            projection = await sealCommitConversations({
+              journal,
+              sealDir,
+              boundary: {
+                commitSha,
+                branch,
+                subject,
+                committedAt,
+                sequence: result.sequence,
+                openTurnIdsAtCommit: result.openTurnIdsAtCommit,
+                previousRepoBoundarySequence: result.previousRepoBoundarySequence
+              }
+            });
+            // The journal is a conveyor: once the archive copy verifiably
+            // exists on disk, drop the sealed prefix. On any miss the prefix
+            // stays and the next boundary's seal window covers it (self-heal).
+            if (projection.sealed || (projection.reason === 'already-sealed' && fs.existsSync(projection.path))) {
+              const minAck = await getRegistry().getMinAck({ journalId: project.id });
+              const trim = await journal.trimThrough(minAck === null ? result.sequence : Math.min(result.sequence, minAck));
+              projection.trimmedThrough = trim.trimmedThrough;
+            }
+          }
+        } catch (err) {
+          projection = { sealed: false, turnCount: 0, error: err && err.message ? err.message : String(err) };
+        }
+      }
+      return {
+        sequence: result.sequence,
+        journalId: routed ? projectRegistry.findProject(home, repoIdentity).id : 'global',
+        bridgeCursorAtCommit,
+        openTurnIdsAtCommit: result.openTurnIdsAtCommit,
+        previousRepoBoundarySequence: result.previousRepoBoundarySequence,
+        committedAt: committedAt || new Date().toISOString(),
+        projection
+      };
+    },
+
+    async registerConsumer(name, meta = {}) {
+      return getRegistry().registerConsumer(name, meta);
+    },
+
+    async getConsumer(name) {
+      if (!homeExists()) return null;
+      const consumers = await getRegistry().getConsumers();
+      return consumers.find((consumer) => consumer.name === name) || null;
+    },
+
+    async listConsumers() {
+      if (!homeExists()) return [];
+      return getRegistry().getConsumers();
+    },
+
+    async ackConsumerCursor(name, sequence, options = {}) {
+      const high = await this.getHighWatermark(options);
+      if (sequence > high) throw Object.assign(new Error('ack exceeds journal high watermark'), { code: 'ACK_OUT_OF_RANGE' });
+      return getRegistry().ackConsumerCursor(name, sequence, options);
+    },
+
+    async unregisterConsumer(name) {
+      return getRegistry().unregisterConsumer(name);
+    },
+
+    async compact({ throughSequence, journalId = 'global' } = {}) {
+      return compactJournal(selectJournal(journalId), getRegistry(), { throughSequence, journalId });
+    },
+
+    async getHealth() {
+      if (!homeExists()) {
+        return {
+          journalSizeBytes: 0,
+          firstSequence: 0,
+          lastSequence: 0,
+          minConsumerAck: null,
+          oldestUnackedAt: null,
+          consumers: []
+        };
+      }
+      const liveJournal = getJournal();
+      const [bounds, consumers, minConsumerAck] = await Promise.all([
+        liveJournal.getBounds(),
+        getRegistry().getConsumers(),
+        getRegistry().getMinAck()
+      ]);
+      let journalSizeBytes = 0;
+      try {
+        journalSizeBytes = fs.statSync(liveJournal.eventsFile).size;
+      } catch (_) {
+        journalSizeBytes = 0;
+      }
+      let oldestUnackedAt = null;
+      if (minConsumerAck !== null && bounds.lastSequence > minConsumerAck) {
+        try {
+          const pending = await liveJournal.readEvents({ fromSequence: minConsumerAck + 1, toSequence: minConsumerAck + 1, limit: 1 });
+          if (pending.length) oldestUnackedAt = pending[0].capturedAt || null;
+        } catch (_) {
+          oldestUnackedAt = null;
+        }
+      }
+      return {
+        journalSizeBytes,
+        firstSequence: bounds.firstSequence,
+        lastSequence: bounds.lastSequence,
+        minConsumerAck,
+        oldestUnackedAt,
+        consumers: consumers.map((consumer) => ({
+          name: consumer.name,
+          ack: consumer.ack,
+          lastSeenAt: consumer.lastSeenAt || null
+        }))
+      };
+    },
+
+    // Introspection helpers for diagnostics; not part of the frozen contract.
+    get _journal() { return journal; },
+    get _registry() { return registry; }
+  };
+}
+
+module.exports = { createBridge };