@kontextmind/kxm 0.7.72 → 0.7.73

package/plugins/kxm/src/runtime-store.ts

@@ -4,6 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
 import { KxmConfigError, validateCoordinator, validateDriveReceipt, validateIntakeMessage, validateRunEvent, kxmCanonicalJson, type JsonValue, type KxmConfigIssue, type KxmConfigOptions } from "./project-config.ts";
 import { kxmUserStateRoot } from "./bindings.ts";
+import { deriveKxmSyncEvent, kxmSyncEventBytes, KxmSyncRedactor } from "./sync-transform.ts";
 
 /* ------------------------------------------------------------------ *
  * Runtime registry (per-user, platform state root)
@@ -225,6 +226,16 @@ export class KxmRuntimeRegistry {
   }
 
   /** Register or revalidate a project's home binding. Home Runtime is immutable. */
+  /** All projects registered to this Runtime, for restart recovery: the
+   * supervisor needs to reopen their contexts so pending outbox rows resume
+   * syncing and presence keeps beating. */
+  projectsForRuntime(homeRuntimeId: string): Array<{ projectRoot: string; projectId: string }> {
+    const rows = this.database.prepare(
+      "SELECT project_root, project_id FROM projects WHERE home_runtime_id = ? ORDER BY registered_at",
+    ).all(homeRuntimeId) as Array<{ project_root: string; project_id: string }>;
+    return rows.map((row) => ({ projectRoot: row.project_root, projectId: row.project_id }));
+  }
+
   registerProject(registration: { projectId: string; projectRoot: string; homeRuntimeId: string; configRevision?: string; now: string }): KxmProjectRegistration {
     const projectRoot = resolve(registration.projectRoot);
     const projectKey = projectRuntimeKey(projectRoot);
@@ -550,7 +561,7 @@ export interface KxmCommandRecord {
   recordedAt: string;
 }
 
-export const KXM_EVENT_STORE_SCHEMA_VERSION = 5;
+export const KXM_EVENT_STORE_SCHEMA_VERSION = 6;
 export const KXM_DRIVE_RECEIPT_SCHEMA = "kxm.drive-receipt.v1";
 export const DRIVE_RECEIPT_MAX_BYTES = 8 * 1024;
 
@@ -586,6 +597,7 @@ const EVENT_STORE_TABLES = {
     "schema", "record",
   ],
   project_controls: ["project_id", "paused", "reason", "updated_at", "actor", "schema", "record"],
+  outbox: ["seq", "run_id", "sequence", "sync_event", "attempted_at", "acked_at"],
 } as const;
 
 /**
@@ -780,8 +792,31 @@ CREATE TABLE project_controls (
   schema TEXT NOT NULL,
   record TEXT NOT NULL
 ) STRICT;
+CREATE TABLE IF NOT EXISTS outbox (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT NOT NULL,
+  sequence INTEGER NOT NULL,
+  sync_event TEXT NOT NULL,
+  attempted_at TEXT,
+  acked_at TEXT,
+  UNIQUE (run_id, sequence)
+) STRICT;
+CREATE INDEX outbox_pending ON outbox(seq) WHERE acked_at IS NULL;
 `;
 
+/**
+ * One outbox row: the already-derived `kxm.sync-event.v1` bytes plus retry
+ * transport metadata. The local source payload is never kept here.
+ */
+export interface KxmOutboxRow {
+  seq: number;
+  runId: string;
+  sequence: number;
+  syncEvent: string;
+  attemptedAt?: string;
+  ackedAt?: string;
+}
+
 /** One persisted coordinator identity (`kxm.coordinator.v1`). */
 export interface KxmCoordinatorRow {
   coordinatorId: string;
@@ -818,6 +853,9 @@ export interface KxmProjectControlRow {
 
 export class KxmRunEventStore {
   readonly path: string;
+  /** Secret values registered here are replaced in every sync object this
+   * store derives. In memory only: they are never written anywhere. */
+  readonly syncRedactor = new KxmSyncRedactor();
   private readonly database: DatabaseSync;
 
   constructor(path: string) {
@@ -933,6 +971,16 @@ export class KxmRunEventStore {
     return row ? runFromRow(row) : undefined;
   }
 
+  /** All projects registered to this Runtime, for restart recovery: the
+   * supervisor needs to reopen their contexts so pending outbox rows resume
+   * syncing and presence keeps beating. */
+  projectsForRuntime(homeRuntimeId: string): Array<{ projectRoot: string; projectId: string }> {
+    const rows = this.database.prepare(
+      "SELECT project_root, project_id FROM projects WHERE home_runtime_id = ? ORDER BY registered_at",
+    ).all(homeRuntimeId) as Array<{ project_root: string; project_id: string }>;
+    return rows.map((row) => ({ projectRoot: row.project_root, projectId: row.project_id }));
+  }
+
   runsForProject(projectId: string, limit = 50): KxmRunRecord[] {
     const rows = this.database.prepare(`
       SELECT run_id, project_id, home_runtime_id, workflow_id, prompt_sha256, status, config_revision, memory_revision, executor_policy_revision, tool_policy_revision, created_at, updated_at
@@ -974,6 +1022,46 @@ export class KxmRunEventStore {
       event.schema,
       event.homeRuntimeId,
     );
+    // Allowlist before outbox: the row holds only the derived sync object, and
+    // it commits (or rolls back) with the event in the caller's transaction.
+    const syncEvent = deriveKxmSyncEvent(event, { redactor: this.syncRedactor });
+    this.database.prepare("INSERT INTO outbox (run_id, sequence, sync_event) VALUES (?, ?, ?)")
+      .run(event.runId, event.sequence, kxmSyncEventBytes(syncEvent));
+  }
+
+  /** Unacknowledged outbox rows after `afterSeq`, in outbox order, oldest first. */
+  pendingOutbox(limit = 100, afterSeq = 0): KxmOutboxRow[] {
+    const rows = this.database.prepare(`
+      SELECT seq, run_id, sequence, sync_event, attempted_at, acked_at
+      FROM outbox WHERE acked_at IS NULL AND seq > ? ORDER BY seq ASC LIMIT ?
+    `).all(afterSeq, limit) as OutboxSqlRow[];
+    return rows.map(outboxFromRow);
+  }
+
+  /** Every outbox row of one run, acknowledged or not, in sequence order. */
+  outboxForRun(runId: string): KxmOutboxRow[] {
+    const rows = this.database.prepare(`
+      SELECT seq, run_id, sequence, sync_event, attempted_at, acked_at
+      FROM outbox WHERE run_id = ? ORDER BY sequence ASC
+    `).all(runId) as OutboxSqlRow[];
+    return rows.map(outboxFromRow);
+  }
+
+  markOutboxAttempted(seqs: readonly number[], at: string): void {
+    const statement = this.database.prepare("UPDATE outbox SET attempted_at = ? WHERE seq = ? AND acked_at IS NULL");
+    this.transaction(() => {
+      for (const seq of seqs) statement.run(at, seq);
+    });
+  }
+
+  /** Advance the cursor: the hub holds these rows now. Returns rows newly acked. */
+  ackOutbox(seqs: readonly number[], at: string): number {
+    const statement = this.database.prepare("UPDATE outbox SET acked_at = ? WHERE seq = ? AND acked_at IS NULL");
+    return this.transaction(() => {
+      let changed = 0;
+      for (const seq of seqs) changed += Number(statement.run(at, seq).changes);
+      return changed;
+    });
   }
 
   events(runId: string, afterSequence = 0, limit = 200): KxmRunEvent[] {
@@ -1585,6 +1673,26 @@ function parseDriveReceipt(raw: string): KxmDriveReceipt {
   return parsed as KxmDriveReceipt;
 }
 
+type OutboxSqlRow = {
+  seq: number;
+  run_id: string;
+  sequence: number;
+  sync_event: string;
+  attempted_at: string | null;
+  acked_at: string | null;
+};
+
+function outboxFromRow(row: OutboxSqlRow): KxmOutboxRow {
+  return {
+    seq: row.seq,
+    runId: row.run_id,
+    sequence: row.sequence,
+    syncEvent: row.sync_event,
+    ...(row.attempted_at !== null ? { attemptedAt: row.attempted_at } : {}),
+    ...(row.acked_at !== null ? { ackedAt: row.acked_at } : {}),
+  };
+}
+
 function runFromRow(row: {
   run_id: string;
   project_id: string;

package/plugins/kxm/src/runtime-supervisor.ts

@@ -11,6 +11,7 @@ import {
   runtimeError,
   verifyKxmDriveReceipt,
   kxmRuntimePaths,
+  type KxmRunEventStore,
   type KxmRuntimePaths,
 } from "./runtime-store.ts";
 import {
@@ -26,6 +27,10 @@ import { createKxmOneShotProducer } from "./oneshot-producer.ts";
 import { isRouteAdmitted } from "./routes.ts";
 import { KxmRunScheduler, createKxmSimulatedProducer, recordDriveReceipt, recoverKxmRun, kxmDrivePollProjection } from "./engine.ts";
 import { kxmDriveSession, kxmOpenDriveSessions } from "./runtime-owner.ts";
+import { RuntimeHubClient } from "./client.ts";
+import { readHubBinding } from "./hub-binding.ts";
+import { resolveClientHubAuthToken } from "./hub-env.ts";
+import { defaultProjectName } from "./project-name.ts";
 
 /* ------------------------------------------------------------------ *
  * Token management
@@ -351,6 +356,96 @@ async function driveSessionStillPending(settled: Promise<unknown>): Promise<bool
   return pending;
 }
 
+/* ------------------------------------------------------------------ *
+ * Runtime → hub sync (P5): outbound only
+ * ------------------------------------------------------------------ */
+
+export const DEFAULT_RUNTIME_SYNC_INTERVAL_MS = 10_000;
+const MIN_RUNTIME_SYNC_INTERVAL_MS = 250;
+const MAX_RUNTIME_SYNC_INTERVAL_MS = 60_000;
+const OUTBOX_PUSH_BATCH = 32;
+
+/** How often the supervisor heartbeats and pushes its outbox. Keep it well
+ * under the hub's presence lease (30 s by default). */
+export function runtimeSyncIntervalMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.KXM_RUNTIME_SYNC_INTERVAL_MS?.trim();
+  if (!raw) return DEFAULT_RUNTIME_SYNC_INTERVAL_MS;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed)) return DEFAULT_RUNTIME_SYNC_INTERVAL_MS;
+  return Math.min(MAX_RUNTIME_SYNC_INTERVAL_MS, Math.max(MIN_RUNTIME_SYNC_INTERVAL_MS, parsed));
+}
+
+export interface KxmOutboxSyncResult {
+  pushed: number;
+  acked: number;
+  conflicts: number;
+  rejected: number;
+}
+
+/**
+ * Push every pending outbox row to the bound hub in outbox order and advance
+ * the cursor on each acknowledgement. Accepted and duplicate rows are acked;
+ * a conflict or rejection stays pending (the hub has raised the alert) and is
+ * skipped for the rest of this pass. A transport failure leaves every row
+ * pending for a safe retry.
+ */
+export async function syncKxmOutbox(
+  eventStore: KxmRunEventStore,
+  client: RuntimeHubClient,
+  options: { now?: () => string; batchSize?: number } = {},
+): Promise<KxmOutboxSyncResult> {
+  const now = options.now ?? (() => new Date().toISOString());
+  const batchSize = options.batchSize ?? OUTBOX_PUSH_BATCH;
+  const result: KxmOutboxSyncResult = { pushed: 0, acked: 0, conflicts: 0, rejected: 0 };
+  let afterSeq = 0;
+  for (;;) {
+    const rows = eventStore.pendingOutbox(batchSize, afterSeq);
+    if (rows.length === 0) return result;
+    // Batch by serialized byte size, not just count: the hub rejects requests
+    // over its body ceiling (HTTP 413), and retrying the same oversized batch
+    // would permanently block the queue. Trim to the byte budget and leave the
+    // rest for the next iteration.
+    const MAX_BATCH_BYTES = 200_000; // hub ceiling is 256 KiB; leave headroom
+    let byteBudget = MAX_BATCH_BYTES;
+    let sendCount = 0;
+    for (const row of rows) {
+      const rowBytes = Buffer.byteLength(row.syncEvent, "utf8") + 64; // JSON overhead
+      if (sendCount > 0 && byteBudget - rowBytes < 0) break;
+      byteBudget -= rowBytes;
+      sendCount += 1;
+    }
+    const batch = rows.slice(0, sendCount);
+    if (batch.length === 0) batch.push(rows[0]!); // one oversized row: send alone, hub will 413
+    afterSeq = batch[batch.length - 1]!.seq;
+    eventStore.markOutboxAttempted(batch.map((row) => row.seq), now());
+    const response = await client.pushSyncEvents(batch.map((row) => JSON.parse(row.syncEvent) as unknown));
+    result.pushed += batch.length;
+    const outcomes = new Map(response.results.map((entry) => [`${entry.runId}\u0000${entry.sequence}`, entry.outcome]));
+    const acked: number[] = [];
+    for (const row of batch) {
+      const outcome = outcomes.get(`${row.runId}\u0000${row.sequence}`);
+      if (outcome === "accepted" || outcome === "duplicate") acked.push(row.seq);
+      else if (outcome === "conflict") result.conflicts += 1;
+      else result.rejected += 1;
+    }
+    result.acked += eventStore.ackOutbox(acked, now());
+  }
+}
+
+/** Where this Runtime reports one project, or nothing when no hub is bound. */
+function runtimeHubClientFor(context: KxmRuntimeContext, env: NodeJS.ProcessEnv): RuntimeHubClient | undefined {
+  const serverUrl = env.KXM_SERVER_URL?.trim() || readHubBinding(env)?.url;
+  if (!serverUrl) return undefined;
+  const project = defaultProjectName(context.projectRoot, env);
+  const authToken = resolveClientHubAuthToken(env, project);
+  return new RuntimeHubClient({
+    serverUrl,
+    project,
+    runtimeId: context.homeRuntimeId,
+    ...(authToken ? { authToken } : {}),
+  });
+}
+
 export interface KxmRuntimeSupervisor {
   server: Server;
   port: number;
@@ -395,6 +490,21 @@ async function startKxmRuntimeSupervisorInner(
   let activeRuntimeId = runtimeId;
 
   const contexts = new Map<string, KxmRuntimeContext>();
+  const registerSyncCredentials = (context: KxmRuntimeContext): void => {
+    // Register credentials on the store's redactor at context creation —
+    // BEFORE any event can be appended — so the very first outbox row is
+    // already scrubbed. Registering on the sync tick leaves a window where
+    // appended events retain credentials.
+    const hubToken = resolveClientHubAuthToken(process.env, defaultProjectName(context.projectRoot, process.env));
+    if (hubToken) context.eventStore.syncRedactor.register(hubToken);
+    for (const key of Object.keys(process.env)) {
+      if ((key.startsWith("KXM_") && (key.endsWith("_TOKEN") || key.endsWith("_KEY"))) || key.endsWith("_API_KEY") || key.endsWith("_SECRET")) {
+        const value = process.env[key]?.trim();
+        if (value) context.eventStore.syncRedactor.register(value);
+      }
+    }
+  };
+
   const contextFor = (projectRoot: string): KxmRuntimeContext => {
     if (!isAbsolute(projectRoot)) {
       throw runtimeError("runtime_request_invalid", "projectRoot", "projectRoot must be an absolute path");
@@ -403,6 +513,7 @@ async function startKxmRuntimeSupervisorInner(
     const existing = contexts.get(key);
     if (existing) return existing;
     const context = openKxmRuntimeContext(projectRoot, { homeRuntimeId: activeRuntimeId, stateRoot: paths.stateRoot });
+    registerSyncCredentials(context);
     contexts.set(key, context);
     return context;
   };
@@ -774,11 +885,50 @@ async function startKxmRuntimeSupervisorInner(
   }, 1000);
   heartbeat.unref();
 
+  // Outbound only: the supervisor pulls nothing and exposes nothing to the hub.
+  // A tick that finds no bound hub, no credential or an unreachable hub does
+  // nothing; outbox rows stay pending and local execution never waits on it.
+  //
+  // Restart recovery: contexts are only populated on demand (a project request
+  // opens one), so a restarted supervisor would see an empty map and silently
+  // stop syncing every registered project's pending outbox rows. Reopen the
+  // projects this Runtime owns before the first tick.
+  for (const reg of registry.projectsForRuntime(activeRuntimeId)) {
+    try {
+      contextFor(reg.projectRoot);
+    } catch {
+      // A project whose checkout has moved or been deleted stays skipped; its
+      // outbox rows remain pending and its presence expires, which is visible
+      // in the ops snapshot as orphaned.
+    }
+  }
+
+  let syncing = false;
+  const syncTimer = setInterval(() => {
+    if (syncing || stopping) return;
+    syncing = true;
+    void (async () => {
+      for (const context of [...contexts.values()]) {
+
+        try {
+          const client = runtimeHubClientFor(context, process.env);
+          if (!client) continue;
+          await client.heartbeat();
+          await syncKxmOutbox(context.eventStore, client, { now });
+        } catch {
+          // Retry on the next tick.
+        }
+      }
+    })().finally(() => { syncing = false; });
+  }, runtimeSyncIntervalMs());
+  syncTimer.unref();
+
   let stopping = false;
   const stop = async (): Promise<void> => {
     if (stopping) return;
     stopping = true;
     clearInterval(heartbeat);
+    clearInterval(syncTimer);
     try { registry.markStopping(process.pid, now()); } catch { /* best effort */ }
     const openSessions = [...contexts.values()].flatMap((context) => (
       kxmOpenDriveSessions(context.eventStore.path).map((session) => ({ context, session }))

package/plugins/kxm/src/store.ts

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import type { DatabaseSync } from "./sqlite.ts";
-import type { AgentIdentity, LeaseRecord, MessageRecord } from "./protocol.ts";
+import type { AgentIdentity, LeaseRecord, MessageRecord, RuntimePresenceRecord, StoredSyncEvent } from "./protocol.ts";
 import type { ContextItem } from "./context.ts";
 import type { WorkflowJournalEntry, WorkflowRun } from "./workflow.ts";
 import {
@@ -9,7 +9,7 @@ import {
   type DatabaseSchemaSpec,
 } from "./database.ts";
 
-export const HUB_STORE_SCHEMA_VERSION = 4;
+export const HUB_STORE_SCHEMA_VERSION = 5;
 
 export const HUB_STORE_TABLES: Readonly<Record<string, readonly string[]>> = Object.freeze({
   agents: Object.freeze(["id", "record"]),
@@ -20,9 +20,13 @@ export const HUB_STORE_TABLES: Readonly<Record<string, readonly string[]>> = Obj
   workflow_journal: Object.freeze(["id", "run_id", "category", "area", "record"]),
   context_items: Object.freeze(["id", "project", "kind", "record"]),
   leases: Object.freeze(["resource", "holder_agent_id", "fencing_token", "expires_at", "record"]),
+  sync_events: Object.freeze([
+    "project_id", "run_id", "sequence", "hub_project", "home_runtime_id", "event_type", "content_hash", "received_at", "record",
+  ]),
+  runtime_presence: Object.freeze(["runtime_id", "hub_project", "host", "heartbeat", "record"]),
 });
 
-export const HUB_STORE_SCHEMA_V4 = `
+export const HUB_STORE_SCHEMA_V5 = `
   CREATE TABLE IF NOT EXISTS agents (
     id TEXT PRIMARY KEY,
     record TEXT NOT NULL
@@ -78,10 +82,31 @@ export const HUB_STORE_SCHEMA_V4 = `
     expires_at TEXT NOT NULL,
     record TEXT NOT NULL
   ) STRICT;
+  CREATE TABLE IF NOT EXISTS sync_events (
+    project_id TEXT NOT NULL,
+    run_id TEXT NOT NULL,
+    sequence INTEGER NOT NULL,
+    hub_project TEXT NOT NULL,
+    home_runtime_id TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    content_hash TEXT NOT NULL,
+    received_at TEXT NOT NULL,
+    record TEXT NOT NULL,
+    PRIMARY KEY (project_id, run_id, sequence)
+  ) STRICT;
+  CREATE INDEX IF NOT EXISTS sync_events_hub_project ON sync_events(hub_project, run_id, sequence);
+  CREATE TABLE IF NOT EXISTS runtime_presence (
+    runtime_id TEXT NOT NULL,
+    hub_project TEXT NOT NULL,
+    host TEXT,
+    heartbeat TEXT NOT NULL,
+    record TEXT NOT NULL,
+    PRIMARY KEY (hub_project, runtime_id)
+  ) STRICT;
 `;
 
 export const HUB_STORE_SCHEMA_SPEC: DatabaseSchemaSpec = Object.freeze({
-  schema: HUB_STORE_SCHEMA_V4,
+  schema: HUB_STORE_SCHEMA_V5,
   version: HUB_STORE_SCHEMA_VERSION,
   tables: HUB_STORE_TABLES,
 });
@@ -112,6 +137,17 @@ export interface LeaseAcquireInput {
   nowMs: number;
 }
 
+/** How one pushed sync event landed. `conflict` is a security alert: the
+ * same `{projectId, runId, sequence}` already holds different bytes, or the
+ * run already belongs to another project or home Runtime. */
+export type SyncIngestOutcome =
+  | { outcome: "accepted" | "duplicate" }
+  | { outcome: "conflict"; reason: "sequence_reused" | "project_mismatch" | "home_runtime_mismatch"; existingHash?: string };
+
+function syncKey(projectId: string, runId: string, sequence: number): string {
+  return `${projectId}\u0000${runId}\u0000${sequence}`;
+}
+
 function parseLeaseRecord(record: string): LeaseRecord | undefined {
   try {
     return JSON.parse(record) as LeaseRecord;
@@ -127,6 +163,32 @@ function leaseHasLapsed(lease: LeaseRecord, nowMs: number): boolean {
   return !Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs;
 }
 
+type SyncEventSqlRow = {
+  project_id: string;
+  run_id: string;
+  sequence: number;
+  hub_project: string;
+  home_runtime_id: string;
+  event_type: string;
+  content_hash: string;
+  received_at: string;
+  record: string;
+};
+
+function syncEventFromRow(row: SyncEventSqlRow): StoredSyncEvent {
+  return {
+    projectId: row.project_id,
+    runId: row.run_id,
+    sequence: row.sequence,
+    hubProject: row.hub_project,
+    homeRuntimeId: row.home_runtime_id,
+    eventType: row.event_type,
+    contentHash: row.content_hash,
+    receivedAt: row.received_at,
+    bytes: row.record,
+  };
+}
+
 class MessageMap extends Map<string, MessageRecord> {
   private readonly store: MeshStore;
 
@@ -167,6 +229,9 @@ export class MeshStore {
   readonly journal = new Map<string, WorkflowJournalEntry>();
   readonly contextItems = new Map<string, ContextItem>();
   readonly leases = new Map<string, LeaseRecord>();
+  /** Memory-only stores keep sync state here; a database store reads SQLite. */
+  private readonly syncEvents = new Map<string, StoredSyncEvent>();
+  private readonly runtimePresence = new Map<string, RuntimePresenceRecord>();
   readonly path?: string;
   private readonly database?: DatabaseSync;
   private readonly agentSequences = new Map<string, number>();
@@ -508,6 +573,144 @@ export class MeshStore {
     this.database?.prepare("DELETE FROM leases WHERE resource = ?").run(resource);
   }
 
+  // ----- Runtime → hub sync (P5) -----
+
+  /**
+   * Accept one sync event exactly once by `{projectId, runId, sequence}`,
+   * deciding inside one transaction. Identical bytes are an idempotent
+   * duplicate; different bytes under a used sequence are refused, and so is a
+   * run that already belongs to another hub project or home Runtime.
+   */
+  ingestSyncEvent(event: StoredSyncEvent): SyncIngestOutcome {
+    const decide = (): SyncIngestOutcome => {
+      const existing = this.readSyncEvent(event.projectId, event.runId, event.sequence);
+      if (existing) {
+        if (existing.contentHash === event.contentHash && existing.hubProject === event.hubProject) return { outcome: "duplicate" };
+        return { outcome: "conflict", reason: "sequence_reused", existingHash: existing.contentHash };
+      }
+      const owner = this.syncProjectOwner(event.projectId);
+      if (owner !== undefined && owner !== event.hubProject) return { outcome: "conflict", reason: "project_mismatch" };
+      const home = this.syncRunHome(event.projectId, event.runId);
+      if (home !== undefined && home !== event.homeRuntimeId) return { outcome: "conflict", reason: "home_runtime_mismatch" };
+      this.writeSyncEvent(event);
+      return { outcome: "accepted" };
+    };
+    return this.database ? withDatabaseTransaction(this.database, decide) : decide();
+  }
+
+  /** Every sync event one hub project holds, by run then sequence. */
+  listSyncEvents(hubProject: string): StoredSyncEvent[] {
+    if (!this.database) {
+      return [...this.syncEvents.values()]
+        .filter((event) => event.hubProject === hubProject)
+        .sort((left, right) => left.runId.localeCompare(right.runId) || left.sequence - right.sequence);
+    }
+    const rows = this.database.prepare(`
+      SELECT project_id, run_id, sequence, hub_project, home_runtime_id, event_type, content_hash, received_at, record
+      FROM sync_events WHERE hub_project = ? ORDER BY run_id ASC, sequence ASC
+    `).all(hubProject) as SyncEventSqlRow[];
+    return rows.map(syncEventFromRow);
+  }
+
+  /** Highest sequence of one run with no gap below it; 0 when sequence 1 is missing. */
+  syncCursor(projectId: string, runId: string): number {
+    const sequences = this.database
+      ? (this.database.prepare("SELECT sequence FROM sync_events WHERE project_id = ? AND run_id = ? ORDER BY sequence ASC")
+        .all(projectId, runId) as Array<{ sequence: number }>).map((row) => row.sequence)
+      : [...this.syncEvents.values()]
+        .filter((event) => event.projectId === projectId && event.runId === runId)
+        .map((event) => event.sequence)
+        .sort((left, right) => left - right);
+    let cursor = 0;
+    for (const sequence of sequences) {
+      if (sequence !== cursor + 1) break;
+      cursor = sequence;
+    }
+    return cursor;
+  }
+
+  saveRuntimePresence(record: RuntimePresenceRecord): void {
+    this.runtimePresence.set(`${record.project}\u0000${record.runtimeId}`, record);
+    this.database?.prepare(`
+      INSERT INTO runtime_presence (runtime_id, hub_project, host, heartbeat, record) VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(hub_project, runtime_id) DO UPDATE SET
+        host = excluded.host,
+        heartbeat = excluded.heartbeat,
+        record = excluded.record
+    `).run(record.runtimeId, record.project, record.host ?? null, record.heartbeatAt, JSON.stringify(record));
+  }
+
+  getRuntimePresence(project: string, runtimeId: string): RuntimePresenceRecord | undefined {
+    if (!this.database) return this.runtimePresence.get(`${project}\u0000${runtimeId}`);
+    const row = this.database.prepare("SELECT record FROM runtime_presence WHERE hub_project = ? AND runtime_id = ?")
+      .get(project, runtimeId) as { record: string } | undefined;
+    return row ? JSON.parse(row.record) as RuntimePresenceRecord : undefined;
+  }
+
+  listRuntimePresence(project: string): RuntimePresenceRecord[] {
+    if (!this.database) {
+      return [...this.runtimePresence.values()]
+        .filter((record) => record.project === project)
+        .sort((left, right) => left.runtimeId.localeCompare(right.runtimeId));
+    }
+    const rows = this.database.prepare("SELECT record FROM runtime_presence WHERE hub_project = ? ORDER BY runtime_id ASC")
+      .all(project) as Array<{ record: string }>;
+    return rows.map((row) => JSON.parse(row.record) as RuntimePresenceRecord);
+  }
+
+  private readSyncEvent(projectId: string, runId: string, sequence: number): StoredSyncEvent | undefined {
+    if (!this.database) return this.syncEvents.get(syncKey(projectId, runId, sequence));
+    const row = this.database.prepare(`
+      SELECT project_id, run_id, sequence, hub_project, home_runtime_id, event_type, content_hash, received_at, record
+      FROM sync_events WHERE project_id = ? AND run_id = ? AND sequence = ?
+    `).get(projectId, runId, sequence) as SyncEventSqlRow | undefined;
+    return row ? syncEventFromRow(row) : undefined;
+  }
+
+  private syncProjectOwner(projectId: string): string | undefined {
+    if (!this.database) {
+      for (const event of this.syncEvents.values()) if (event.projectId === projectId) return event.hubProject;
+      return undefined;
+    }
+    const row = this.database.prepare("SELECT hub_project FROM sync_events WHERE project_id = ? LIMIT 1").get(projectId) as
+      | { hub_project: string }
+      | undefined;
+    return row?.hub_project;
+  }
+
+  private syncRunHome(projectId: string, runId: string): string | undefined {
+    if (!this.database) {
+      for (const event of this.syncEvents.values()) {
+        if (event.projectId === projectId && event.runId === runId) return event.homeRuntimeId;
+      }
+      return undefined;
+    }
+    const row = this.database.prepare("SELECT home_runtime_id FROM sync_events WHERE project_id = ? AND run_id = ? LIMIT 1")
+      .get(projectId, runId) as { home_runtime_id: string } | undefined;
+    return row?.home_runtime_id;
+  }
+
+  private writeSyncEvent(event: StoredSyncEvent): void {
+    if (!this.database) {
+      this.syncEvents.set(syncKey(event.projectId, event.runId, event.sequence), event);
+      return;
+    }
+    this.database.prepare(`
+      INSERT INTO sync_events (project_id, run_id, sequence, hub_project, home_runtime_id, event_type, content_hash, received_at, record)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      event.projectId,
+      event.runId,
+      event.sequence,
+      event.hubProject,
+      event.homeRuntimeId,
+      event.eventType,
+      event.contentHash,
+      event.receivedAt,
+      event.bytes,
+    );
+  }
+
   deleteWorkflowRun(runId: string): void {
     this.workflowRuns.delete(runId);
     this.database?.prepare("DELETE FROM workflow_runs WHERE id = ?").run(runId);