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

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(), throughSequence = Infinity } = {}) {
+  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(Math.min(appended.sequence, throughSequence));
+    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, throughSequence = Infinity } = {}) {
+  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(Math.min(boundary.sequence, throughSequence));
+      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, journalId = 'global' } = {}) {
+  const minAck = await consumerRegistry.getMinAck({ journalId });
+  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,111 @@
+'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, { journalId = 'global' } = {}) {
+    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 (journalId === 'global') entry.ack = Math.max(entry.ack || 0, sequence);
+      else {
+        if (!consumesJournal(entry, journalId)) throw new Error(`consumer ${name} is not registered for journal ${journalId}`);
+        entry.cursors = { ...(entry.cursors || {}), [journalId]: Math.max((entry.cursors || {})[journalId] || 0, sequence) };
+      }
+      entry.lastSeenAt = new Date().toISOString();
+      this._write(state);
+      return { name, journalId, ack: journalId === 'global' ? entry.ack : entry.cursors[journalId] };
+    });
+  }
+
+  async getConsumers() {
+    if (!fs.existsSync(this.consumersFile)) return [];
+    return this._withLock(async () => {
+      const state = this._read();
+      return state.consumers.map((c) => ({ ...c }));
+    });
+  }
+
+  async getMinAck({ journalId = 'global' } = {}) {
+    if (!fs.existsSync(this.consumersFile)) return null;
+    return this._withLock(async () => {
+      const state = this._read();
+      const consumers = state.consumers.filter(c => consumesJournal(c, journalId));
+      if (consumers.length === 0) return null;
+      return consumers.reduce((min, c) => Math.min(min, journalId === 'global' ? c.ack || 0 : (c.cursors || {})[journalId] || 0), Number.POSITIVE_INFINITY);
+    });
+  }
+}
+
+// Legacy consumers are global-only. An explicit wildcard protects journals
+// created after registration too; an offline consumer is never expired.
+function consumesJournal(consumer, journalId) {
+  const journals = consumer.meta && consumer.meta.journals;
+  return Array.isArray(journals) ? journals.includes('*') || journals.includes(journalId) : journalId === 'global';
+}
+
+module.exports = { ConsumerRegistry, consumesJournal };

package/src/bridge/core/event-schema.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const { isValidRepoIdentityV1 } = require('./repo-context');
+
+const SOURCES = ['claude-code', 'codex', 'opencode', 'zcode'];
+const IDENTITY_CONFIDENCE_LEVELS = ['exact', 'partial', 'unavailable'];
+const CAPTURE_STATUSES = ['complete', 'partial', 'gap'];
+const ROLES = ['user', 'assistant'];
+
+// AUD-ID-001: a shared fake session id aggregates unrelated events.
+const FORBIDDEN_SESSION_IDS = new Set(['', 'unknown-session', 'unknown', 'null', 'none']);
+
+class EventSchemaError extends Error {
+  constructor(message, field) {
+    super(message);
+    this.name = 'EventSchemaError';
+    this.field = field;
+  }
+}
+
+function evidenceLevelFor({ sessionId, turnId }) {
+  if (sessionId && turnId) return 'exact';
+  if (sessionId || turnId) return 'partial';
+  return 'unavailable';
+}
+
+const CONFIDENCE_RANK = { unavailable: 0, partial: 1, exact: 2 };
+
+function clampConfidence(requested, evidence) {
+  return CONFIDENCE_RANK[requested] <= CONFIDENCE_RANK[evidence] ? requested : evidence;
+}
+
+function raiseConfidenceToEvidence(current, evidence) {
+  return CONFIDENCE_RANK[evidence] > CONFIDENCE_RANK[current] ? evidence : current;
+}
+
+function validateAndNormalizeEvent(input) {
+  if (!input || typeof input !== 'object') {
+    throw new EventSchemaError('event must be an object', 'event');
+  }
+  if (!SOURCES.includes(input.source)) {
+    throw new EventSchemaError(`source must be one of ${SOURCES.join(', ')}`, 'source');
+  }
+  if (typeof input.eventType !== 'string' || !input.eventType) {
+    throw new EventSchemaError('eventType is required', 'eventType');
+  }
+  if (input.role !== undefined && input.role !== null && !ROLES.includes(input.role)) {
+    throw new EventSchemaError('role must be user, assistant or null', 'role');
+  }
+  if (input.content !== undefined && input.content !== null && typeof input.content !== 'string') {
+    throw new EventSchemaError('content must be a string or null', 'content');
+  }
+
+  let sessionId = input.sessionId === undefined ? null : input.sessionId;
+  if (sessionId !== null) {
+    if (typeof sessionId !== 'string') {
+      throw new EventSchemaError('sessionId must be a string or null', 'sessionId');
+    }
+    if (FORBIDDEN_SESSION_IDS.has(sessionId.toLowerCase())) {
+      throw new EventSchemaError('fake session ids such as unknown-session are forbidden', 'sessionId');
+    }
+  }
+  let turnId = input.turnId === undefined ? null : input.turnId;
+  if (turnId !== null && typeof turnId !== 'string') {
+    throw new EventSchemaError('turnId must be a string or null', 'turnId');
+  }
+
+  if (
+    input.identityConfidence !== undefined &&
+    !IDENTITY_CONFIDENCE_LEVELS.includes(input.identityConfidence)
+  ) {
+    throw new EventSchemaError('identityConfidence must be exact, partial or unavailable', 'identityConfidence');
+  }
+  if (input.repoIdentity !== undefined && input.repoIdentity !== null) {
+    // New automatic data must use repo-identity/v1 objects from
+    // resolveRepoContext. Plain strings are legacy records only; malformed
+    // objects are rejected so a guessed identity can never enter the journal.
+    if (typeof input.repoIdentity !== 'string' && !isValidRepoIdentityV1(input.repoIdentity)) {
+      throw new EventSchemaError('repoIdentity must be a valid repo-identity/v1 object, a legacy string, or null', 'repoIdentity');
+    }
+  }
+  if (input.eventKey !== undefined && input.eventKey !== null) {
+    if (typeof input.eventKey !== 'string' || !input.eventKey) {
+      throw new EventSchemaError('eventKey must be a non-empty string when present', 'eventKey');
+    }
+  }
+  if (input.captureStatus !== undefined && !CAPTURE_STATUSES.includes(input.captureStatus)) {
+    throw new EventSchemaError('captureStatus must be complete, partial or gap', 'captureStatus');
+  }
+
+  // Confidence may never overstate the captured evidence.
+  const evidenceLevel = evidenceLevelFor({ sessionId, turnId });
+  const requested = input.identityConfidence || evidenceLevel;
+  const identityConfidence = clampConfidence(requested, evidenceLevel);
+
+  const normalized = {
+    source: input.source,
+    eventType: input.eventType,
+    role: input.role === undefined ? null : input.role,
+    sessionId,
+    turnId,
+    identityConfidence,
+    captureStatus: input.captureStatus || 'complete'
+  };
+  if (input.content !== undefined) normalized.content = input.content;
+  if (input.eventKey !== undefined) normalized.eventKey = input.eventKey;
+  if (input.repoIdentity !== undefined) normalized.repoIdentity = input.repoIdentity;
+  if (input.projectPath !== undefined) normalized.projectPath = input.projectPath;
+  if (input.branch !== undefined) normalized.branch = input.branch;
+  if (input.headAtCapture !== undefined) normalized.headAtCapture = input.headAtCapture;
+  if (input.capturedAt !== undefined) normalized.capturedAt = input.capturedAt;
+  if (input.rawEventType !== undefined) normalized.rawEventType = input.rawEventType;
+  if (input.meta !== undefined) normalized.meta = input.meta;
+  return normalized;
+}
+
+module.exports = {
+  validateAndNormalizeEvent,
+  EventSchemaError,
+  SOURCES,
+  IDENTITY_CONFIDENCE_LEVELS,
+  CAPTURE_STATUSES,
+  FORBIDDEN_SESSION_IDS,
+  evidenceLevelFor,
+  clampConfidence,
+  raiseConfidenceToEvidence
+};

package/src/bridge/core/fs-utils.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function fsyncDir(dir) {
+  try {
+    const fd = fs.openSync(dir, 'r');
+    try {
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (_) {
+    // Directory fsync is best effort (not supported for directories on Windows).
+  }
+}
+
+function appendLineSync(file, line) {
+  const fd = fs.openSync(file, 'a');
+  try {
+    fs.writeSync(fd, line);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function writeJsonAtomicSync(file, value) {
+  const tmp = `${file}.tmp`;
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+  fsyncDir(path.dirname(file));
+}
+
+function writeTextAtomicSync(file, text) {
+  const tmp = `${file}.tmp`;
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, text);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+  fsyncDir(path.dirname(file));
+}
+
+function readJsonIfExists(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err instanceof SyntaxError)) return null;
+    throw err;
+  }
+}
+
+function ensureDirSync(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyDirSync(src, dest) {
+  ensureDirSync(dest);
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(from, to);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+module.exports = { fsyncDir, appendLineSync, writeJsonAtomicSync, writeTextAtomicSync, readJsonIfExists, ensureDirSync, copyDirSync };

package/src/bridge/core/journal-router.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const path = require('path');
+const { Journal } = require('./journal');
+const { findProject } = require('./project-registry');
+
+/**
+ * Capture-side journal routing. Events for a registered project (matched by
+ * repoIdentity.workspaceId) are appended to that project's journal at
+ * `<store>/journal`; everything else — unknown repos and events with no repo
+ * identity — goes to the global journal at `<home>/journal`, so capture never
+ * depends on the registry being readable. Journal instances are cached per
+ * directory for the life of the process (the Codex connector appends many
+ * records per wake-up).
+ */
+
+const journalCache = new Map();
+
+function globalJournalDir(home) {
+  return path.join(home, 'journal');
+}
+
+function projectJournalDir(project) {
+  return path.join(project.store, 'journal');
+}
+
+function journalFor(home, repoIdentity) {
+  let dir = globalJournalDir(home);
+  const project = findProject(home, repoIdentity);
+  if (project) dir = projectJournalDir(project);
+  let journal = journalCache.get(dir);
+  if (!journal) {
+    journal = new Journal(dir);
+    journalCache.set(dir, journal);
+  }
+  return journal;
+}
+
+module.exports = { journalFor, globalJournalDir, projectJournalDir };