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

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,205 @@
+'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');
+
+/**
+ * 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);
+
+  return {
+    homeDir: home,
+
+    async getHighWatermark() {
+      if (!homeExists()) return 0;
+      const bounds = await getJournal().getBounds();
+      return bounds.lastSequence;
+    },
+
+    async readEvents(options = {}) {
+      return getJournal().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 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 trim = await journal.trimThrough(result.sequence);
+              projection.trimmedThrough = trim.trimmedThrough;
+            }
+          }
+        } catch (err) {
+          projection = { sealed: false, turnCount: 0, error: err && err.message ? err.message : String(err) };
+        }
+      }
+      return {
+        sequence: result.sequence,
+        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) {
+      return getRegistry().ackConsumerCursor(name, sequence);
+    },
+
+    async unregisterConsumer(name) {
+      return getRegistry().unregisterConsumer(name);
+    },
+
+    async compact({ throughSequence } = {}) {
+      return compactJournal(getJournal(), getRegistry(), { throughSequence });
+    },
+
+    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 };

package/src/bridge/core/commit-projection.js

@@ -0,0 +1,288 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { ensureDirSync, writeTextAtomicSync } = require('./fs-utils');
+const { EVENT_SCHEMA, BOUNDARY_SCHEMA } = require('./journal');
+const { ConversationQuery } = require('../query/conversation-query');
+
+// Per-commit conversation sealing: a read-only projection of the routed
+// project journal. When a commit boundary lands in a registered project's
+// journal, the conversations belonging to that commit are frozen into
+// `<store>/commits/<commitSha>.md`. The journal stays the only source of
+// truth — sealed files are rebuildable at any time via rebuildSealedFiles.
+
+const COMMIT_SHA_PATTERN = /^[0-9a-f]{7,64}$/;
+
+function isUncommittedBoundary(boundary) {
+  return Boolean(boundary && boundary.meta && boundary.meta.uncommitted);
+}
+
+function sealDirFor(storeDir) {
+  return path.join(storeDir, 'commits');
+}
+
+function sha256Hex(value) {
+  return `sha256:${crypto.createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+function isConversationEvent(record) {
+  return record.schema === EVENT_SCHEMA && (record.eventType === 'user_prompt' || record.eventType === 'assistant_response');
+}
+
+function isBoundaryRecord(record) {
+  return record.schema === BOUNDARY_SCHEMA;
+}
+
+// A fence longer than any backtick run inside the content, so bodies can
+// never break out of their block.
+function fenceFor(content) {
+  const runs = String(content == null ? '' : content).match(/`+/g) || [];
+  const longest = runs.reduce((max, run) => Math.max(max, run.length), 0);
+  return '`'.repeat(Math.max(3, longest + 1));
+}
+
+function yamlScalar(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'number') return String(value);
+  const text = String(value);
+  if (/^[A-Za-z0-9][A-Za-z0-9_.\/-]*$/.test(text)) return text;
+  return `'${text.replace(/'/g, "''")}'`;
+}
+
+function localDay(iso) {
+  if (!iso) return null;
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return null;
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+function localDayTime(iso) {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+function renderEventBlock(label, event) {
+  const fence = fenceFor(event.content);
+  return [`### ${label}`, '', fence, String(event.content == null ? '' : event.content), fence, ''].join('\n');
+}
+
+function renderSealedMarkdown({ boundary, turns, unpaired }) {
+  // sealedAt is derived from persisted boundary facts (never the wall clock)
+  // so a rebuild reproduces byte-identical files.
+  const sealedAt = boundary.capturedAt || boundary.committedAt || null;
+  const uncommitted = isUncommittedBoundary(boundary);
+  const lines = ['---'];
+  if (uncommitted) {
+    lines.push('subject: 未提交的对话');
+    lines.push('uncommitted: true');
+  } else {
+    lines.push(`commitSha: ${yamlScalar(boundary.commitSha)}`);
+    if (boundary.subject !== undefined && boundary.subject !== null) {
+      lines.push(`subject: ${yamlScalar(boundary.subject)}`);
+    }
+  }
+  if (boundary.branch !== undefined && boundary.branch !== null) lines.push(`branch: ${yamlScalar(boundary.branch)}`);
+  if (boundary.committedAt) lines.push(`committedAt: ${yamlScalar(boundary.committedAt)}`);
+  if (sealedAt) lines.push(`sealedAt: ${yamlScalar(sealedAt)}`);
+  lines.push(`boundarySequence: ${yamlScalar(boundary.sequence)}`);
+  lines.push(`previousBoundarySequence: ${yamlScalar(boundary.previousRepoBoundarySequence == null ? null : boundary.previousRepoBoundarySequence)}`);
+  lines.push(`turnCount: ${yamlScalar(turns.length)}`);
+  lines.push(`unpairedEventCount: ${yamlScalar(unpaired.length)}`);
+  lines.push(`contentHash: ${yamlScalar(sha256Hex(canonicalProof({ boundary, turns, unpaired })))}`);
+  lines.push('---', '');
+  turns.forEach((turn, index) => {
+    const first = (turn.userEvents[0] || turn.assistantEvents[0]);
+    const when = localDayTime(first && first.capturedAt);
+    const confidence = (first && first.identityConfidence) || 'unavailable';
+    lines.push(`## Turn ${index + 1}${when ? ` — ${when}` : ''} (${turn.turnId}, ${confidence})`, '');
+    turn.userEvents.forEach((event) => lines.push(renderEventBlock('用户', event)));
+    turn.assistantEvents.forEach((event) => lines.push(renderEventBlock('助手', event)));
+  });
+  if (unpaired.length) {
+    lines.push('## 未配对事件', '');
+    unpaired.forEach((event) => {
+      const label = `${event.role === 'user' ? '用户' : '助手'}${event.turnId ? ` — ${event.turnId}` : ''}`;
+      lines.push(renderEventBlock(label, event));
+    });
+  }
+  return `${lines.join('\n')}`;
+}
+
+// Provenance digest over the sealed bodies (aligned with the knowledge base's
+// frozen-snapshot hashing: content-addressed, no volatile fields).
+function canonicalProof({ boundary, turns, unpaired }) {
+  return JSON.stringify({
+    commitSha: String(boundary.commitSha),
+    turns: turns.map((turn) => ({
+      turnId: turn.turnId,
+      events: turn.userEvents.concat(turn.assistantEvents).map((event) => [event.eventId, event.role, event.content])
+    })),
+    unpaired: unpaired.map((event) => [event.eventId, event.role, event.content])
+  });
+}
+
+/**
+ * Freeze the conversations belonging to one commit boundary into
+ * `<sealDir>/<commitSha>.md`.
+ *
+ * Belongs-to rule: conversation events with sequence in
+ * (previousRepoBoundarySequence, boundary.sequence], plus every turn that was
+ * still open at commit time (openTurnIdsAtCommit — the user's ask is the
+ * requirement truth even when the reply has not arrived yet). Window events
+ * that no selected turn consumed (e.g. a reply that arrived after the previous
+ * commit sealed its turn's prompt) are appended as 未配对事件, so every
+ * conversation body in the journal lands in at least one sealed file.
+ *
+ * @returns {sealed, path?, turnCount, unpairedEventCount?, reason?}
+ */
+async function sealCommitConversations({ journal, sealDir, boundary } = {}) {
+  if (!journal) throw new Error('sealCommitConversations requires journal');
+  if (typeof sealDir !== 'string' || !sealDir) throw new Error('sealCommitConversations requires sealDir');
+  if (!boundary || typeof boundary !== 'object') throw new Error('sealCommitConversations requires boundary');
+  const uncommitted = isUncommittedBoundary(boundary);
+  const commitSha = String(boundary.commitSha || '').trim().toLowerCase();
+  let target;
+  if (uncommitted) {
+    const day = localDay(boundary.capturedAt || boundary.committedAt) || 'unknown-date';
+    if (typeof boundary.sequence !== 'number') {
+      return { sealed: false, turnCount: 0, reason: 'boundary-sequence-missing' };
+    }
+    target = path.join(sealDir, `${day}-uncommitted-${boundary.sequence}.md`);
+  } else {
+    if (!COMMIT_SHA_PATTERN.test(commitSha)) {
+      return { sealed: false, turnCount: 0, reason: 'no-commit-sha' };
+    }
+    target = path.join(sealDir, `${commitSha}.md`);
+  }
+  if (fs.existsSync(target)) {
+    return { sealed: false, path: target, turnCount: 0, reason: 'already-sealed' };
+  }
+  if (typeof boundary.sequence !== 'number') {
+    return { sealed: false, turnCount: 0, reason: 'boundary-sequence-missing' };
+  }
+  const to = boundary.sequence;
+  const from = Math.max((typeof boundary.previousRepoBoundarySequence === 'number' ? boundary.previousRepoBoundarySequence : 0) + 1, 1);
+
+  // Open turns may start before the window, so turns are assembled over the
+  // whole prefix up to the boundary — not just the window itself.
+  const prefix = (await journal.readEvents({ fromSequence: 1, toSequence: to })).filter(isConversationEvent);
+  if (!prefix.length) {
+    return { sealed: false, turnCount: 0, reason: 'no-conversations' };
+  }
+  const query = new ConversationQuery({ journal });
+  // _projectTurns is package-internal reuse: the projection shares the exact
+  // turn-assembly rule the console's browsing view uses.
+  const allTurns = query._projectTurns(prefix);
+  const openIds = new Set(boundary.openTurnIdsAtCommit || []);
+  const turns = allTurns
+    .filter((turn) => openIds.has(turn.turnId) || (turn.startSequence >= from && turn.startSequence <= to))
+    .sort((a, b) => a.startSequence - b.startSequence);
+
+  const consumed = new Set();
+  for (const turn of turns) {
+    for (const event of turn.userEvents.concat(turn.assistantEvents)) consumed.add(event.eventId);
+  }
+  const unpaired = prefix.filter((event) => event.sequence >= from && event.sequence <= to && !consumed.has(event.eventId));
+  if (!turns.length && !unpaired.length) {
+    return { sealed: false, turnCount: 0, reason: 'no-conversations' };
+  }
+
+  const markdown = renderSealedMarkdown({ boundary: { ...boundary, commitSha }, turns, unpaired });
+  ensureDirSync(sealDir);
+  writeTextAtomicSync(target, `${markdown}\n`);
+  return { sealed: true, path: target, turnCount: turns.length, unpairedEventCount: unpaired.length };
+}
+
+/**
+ * Age fuse for conversations that will never be committed: when the newest
+ * conversation event after the last boundary is older than maxAgeDays, append
+ * a synthetic boundary (meta.uncommitted) and seal the tail into
+ * commits/<day>-uncommitted-<seq>.md, then trim the journal. Idempotent per
+ * run: nothing happens while no new events arrived after the last boundary.
+ */
+async function sealUncommittedTail({ journal, sealDir, maxAgeDays = 14, now = Date.now() } = {}) {
+  if (!journal) throw new Error('sealUncommittedTail requires journal');
+  if (typeof sealDir !== 'string' || !sealDir) throw new Error('sealUncommittedTail requires sealDir');
+  const records = await journal.readEvents({});
+  const boundaries = records.filter(isBoundaryRecord);
+  const lastBoundarySeq = boundaries.reduce((max, b) => Math.max(max, b.sequence), 0);
+  const tailEvents = records.filter(isConversationEvent).filter((e) => e.sequence > lastBoundarySeq);
+  if (!tailEvents.length) {
+    return { sealed: false, reason: 'nothing-after-last-boundary' };
+  }
+  const newest = tailEvents.reduce((a, b) => (String(b.capturedAt || '') > String(a.capturedAt || '') ? b : a));
+  const ageMs = now - Date.parse(newest.capturedAt || '');
+  if (!Number.isFinite(ageMs) || ageMs < maxAgeDays * 86400000) {
+    return { sealed: false, reason: 'too-young' };
+  }
+  const repoIdentity = newest.repoIdentity;
+  if (!repoIdentity) {
+    return { sealed: false, reason: 'no-repo-identity' };
+  }
+  const appended = await journal.appendCommitBoundary(repoIdentity, { meta: { uncommitted: true } });
+  const boundary = {
+    commitSha: undefined,
+    capturedAt: newest.capturedAt,
+    sequence: appended.sequence,
+    openTurnIdsAtCommit: appended.openTurnIdsAtCommit,
+    previousRepoBoundarySequence: appended.previousRepoBoundarySequence,
+    meta: { uncommitted: true }
+  };
+  const result = await sealCommitConversations({ journal, sealDir, boundary });
+  if (result.sealed || (result.reason === 'already-sealed' && fs.existsSync(result.path))) {
+    const trim = await journal.trimThrough(appended.sequence);
+    return { ...result, trimmedThrough: trim.trimmedThrough };
+  }
+  return result;
+}
+
+/**
+ * Boot-time reconciliation: trim the journal through the newest boundary
+ * whose sealed file verifiably exists on disk. Heals the window between a
+ * successful seal and a crashed trim, and adopts pre-upgrade journals that
+ * already carry sealed commits.
+ */
+async function reconcileTrim({ journal, sealDir } = {}) {
+  if (!journal) throw new Error('reconcileTrim requires journal');
+  if (typeof sealDir !== 'string' || !sealDir) throw new Error('reconcileTrim requires sealDir');
+  const records = await journal.readEvents({});
+  const boundaries = records
+    .filter(isBoundaryRecord)
+    .filter((b) => COMMIT_SHA_PATTERN.test(String(b.commitSha || '')))
+    .sort((a, b) => b.sequence - a.sequence);
+  for (const boundary of boundaries) {
+    if (fs.existsSync(path.join(sealDir, `${String(boundary.commitSha).toLowerCase()}.md`))) {
+      const trim = await journal.trimThrough(boundary.sequence);
+      return { trimmedThrough: trim.trimmedThrough, commitSha: boundary.commitSha, reason: trim.reason };
+    }
+  }
+  return { trimmedThrough: null, reason: 'no-sealed-boundary' };
+}
+
+/**
+ * Re-create any missing sealed file from the journal's persisted boundary
+ * records (disaster recovery). Existing files are left untouched, so a rebuild
+ * never rewrites history.
+ */
+async function rebuildSealedFiles({ journal, sealDir } = {}) {
+  if (!journal) throw new Error('rebuildSealedFiles requires journal');
+  if (typeof sealDir !== 'string' || !sealDir) throw new Error('rebuildSealedFiles requires sealDir');
+  const boundaries = (await journal.readEvents({})).filter(isBoundaryRecord);
+  const results = [];
+  for (const boundary of boundaries) {
+    results.push(await sealCommitConversations({ journal, sealDir, boundary }));
+  }
+  return {
+    boundaryCount: boundaries.length,
+    sealedCount: results.filter((result) => result.sealed).length,
+    results
+  };
+}
+
+module.exports = { sealDirFor, sealCommitConversations, rebuildSealedFiles, sealUncommittedTail, reconcileTrim };

package/src/bridge/core/compaction.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * Compact the durable journal prefix that every registered consumer has acked.
+ * Never removes data beyond minAck; requires at least one registered consumer;
+ * runs under the same journal lock as appendEvent/appendCommitBoundary.
+ */
+async function compactJournal(journal, consumerRegistry, { throughSequence } = {}) {
+  const minAck = await consumerRegistry.getMinAck();
+  if (minAck === null || minAck === undefined) {
+    return { compactedThrough: null, removedCount: 0, reason: 'no-consumers' };
+  }
+  const target = Math.min(minAck, throughSequence === undefined ? minAck : throughSequence);
+  return journal._withJournalLock(async () => {
+    if (target < journal.firstSequence) {
+      return { compactedThrough: journal.firstSequence - 1, removedCount: 0, reason: 'already-compacted' };
+    }
+    const removedCount = journal._compactTo(target);
+    return { compactedThrough: target, removedCount, reason: 'compacted' };
+  });
+}
+
+module.exports = { compactJournal };

package/src/bridge/core/consumer-registry.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CrossProcessLock, lockPathFor } = require('./lock');
+const { writeJsonAtomicSync, readJsonIfExists, ensureDirSync } = require('./fs-utils');
+
+class ConsumerRegistry {
+  constructor(homeDir) {
+    // Pure reads on a machine without a Bridge home must not create one;
+    // the directory is materialized on the first write.
+    this.homeDir = homeDir;
+    this.consumersFile = path.join(homeDir, 'consumers.json');
+    this.lock = new CrossProcessLock(lockPathFor(homeDir, 'install.lock'));
+  }
+
+  async _withLock(fn) {
+    return this.lock.withLock(fn);
+  }
+
+  _read() {
+    const saved = readJsonIfExists(this.consumersFile);
+    if (saved && typeof saved === 'object' && Array.isArray(saved.consumers)) {
+      return saved;
+    }
+    return { schema: 'bridge-consumers/v1', consumers: [] };
+  }
+
+  _write(state) {
+    ensureDirSync(this.homeDir);
+    writeJsonAtomicSync(this.consumersFile, state);
+  }
+
+  async registerConsumer(name, meta = {}) {
+    if (typeof name !== 'string' || !name) {
+      throw new TypeError('consumer name is required');
+    }
+    return this._withLock(async () => {
+      const state = this._read();
+      let entry = state.consumers.find((c) => c.name === name);
+      if (!entry) {
+        entry = { name, ack: 0, registeredAt: new Date().toISOString(), meta: {} };
+        state.consumers.push(entry);
+      }
+      entry.meta = { ...(entry.meta || {}), ...meta };
+      entry.lastSeenAt = new Date().toISOString();
+      this._write(state);
+      return { ...entry };
+    });
+  }
+
+  async unregisterConsumer(name) {
+    return this._withLock(async () => {
+      const state = this._read();
+      const before = state.consumers.length;
+      state.consumers = state.consumers.filter((c) => c.name !== name);
+      this._write(state);
+      return { removed: before - state.consumers.length };
+    });
+  }
+
+  async ackConsumerCursor(name, sequence) {
+    if (!Number.isInteger(sequence) || sequence < 0) {
+      throw new TypeError('ack sequence must be a non-negative integer');
+    }
+    return this._withLock(async () => {
+      const state = this._read();
+      const entry = state.consumers.find((c) => c.name === name);
+      if (!entry) {
+        const err = new Error(`consumer ${name} is not registered`);
+        err.code = 'CONSUMER_NOT_REGISTERED';
+        throw err;
+      }
+      if (sequence > entry.ack) {
+        entry.ack = sequence;
+      }
+      entry.lastSeenAt = new Date().toISOString();
+      this._write(state);
+      return { name, ack: entry.ack };
+    });
+  }
+
+  async getConsumers() {
+    if (!fs.existsSync(this.consumersFile)) return [];
+    return this._withLock(async () => {
+      const state = this._read();
+      return state.consumers.map((c) => ({ ...c }));
+    });
+  }
+
+  async getMinAck() {
+    if (!fs.existsSync(this.consumersFile)) return null;
+    return this._withLock(async () => {
+      const state = this._read();
+      if (state.consumers.length === 0) return null;
+      return state.consumers.reduce((min, c) => Math.min(min, c.ack), Number.POSITIVE_INFINITY);
+    });
+  }
+}
+
+module.exports = { ConsumerRegistry };