@kontextmind/kxm 0.7.72 → 0.7.74

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.72",
+  "version": "0.7.74",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/client.ts

@@ -632,15 +632,27 @@ export class HubClient {
   }
 
   private async request<T = unknown>(path: string, init: RequestInit = {}, includeIdentity = true): Promise<T> {
-    const requestTimeoutMs = this.options.requestTimeoutMs ?? 15_000;
+    return await hubJsonRequest<T>(this.options, path, init, this.headers(includeIdentity));
+  }
+}
+
+/** One JSON request to the hub with a bounded timeout. A non-2xx answer
+ * becomes a `HubHttpError` carrying the hub's code and next-action hints. */
+async function hubJsonRequest<T>(
+  options: { serverUrl: string; requestTimeoutMs?: number; fetchImpl?: typeof fetch },
+  path: string,
+  init: RequestInit,
+  headers: Record<string, string>,
+): Promise<T> {
+    const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
     const timeoutSignal = AbortSignal.timeout(requestTimeoutMs);
     const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
     let response: Response;
     try {
-      response = await (this.options.fetchImpl ?? fetch)(`${this.options.serverUrl.replace(/\/$/, "")}${path}`, {
+      response = await (options.fetchImpl ?? fetch)(`${options.serverUrl.replace(/\/$/, "")}${path}`, {
         ...init,
         signal,
-        headers: { ...this.headers(includeIdentity), ...(init.headers ?? {}) },
+        headers: { ...headers, ...(init.headers ?? {}) },
       });
     } catch (error) {
       if (timeoutSignal.aborted) throw new Error(`request timed out after ${requestTimeoutMs}ms`);
@@ -672,5 +684,75 @@ export class HubClient {
       );
     }
     return body as T;
+}
+
+export interface RuntimeHubClientOptions {
+  serverUrl: string;
+  /** The hub project this Runtime reports into; its token is the admission. */
+  project: string;
+  authToken?: string;
+  runtimeId: string;
+  /** Box label; defaults to the hostname. Never used for authorization. */
+  host?: string;
+  requestTimeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+export interface RuntimePresenceView {
+  runtimeId: string;
+  host?: string;
+  registeredAt: string;
+  heartbeatAt: string;
+  leaseExpiresAt: string;
+  presence: "online" | "expired";
+}
+
+export interface SyncPushResult {
+  projectId?: string;
+  runId?: string;
+  sequence?: number;
+  outcome: "accepted" | "duplicate" | "conflict" | "rejected";
+  code?: string;
+}
+
+export interface SyncPushResponse {
+  results: SyncPushResult[];
+  cursors: Array<{ projectId: string; runId: string; cursor: number }>;
+}
+
+/**
+ * The Runtime's machine client for one hub project (P5). It registers
+ * presence and pushes derived sync events outbound; the hub never calls the
+ * Runtime back. No agent identity, no message verbs.
+ */
+export class RuntimeHubClient {
+  readonly options: RuntimeHubClientOptions;
+
+  constructor(options: RuntimeHubClientOptions) {
+    this.options = options;
+  }
+
+  async heartbeat(): Promise<RuntimePresenceView> {
+    const result = await this.request<{ presence: RuntimePresenceView }>("/v1/runtime/presence", {
+      project: this.options.project,
+      runtimeId: this.options.runtimeId,
+      host: this.options.host ?? defaultHostLabel(),
+    });
+    return result.presence;
+  }
+
+  /** Push already-derived `kxm.sync-event.v1` objects, in outbox order. */
+  async pushSyncEvents(events: readonly unknown[]): Promise<SyncPushResponse> {
+    return await this.request<SyncPushResponse>("/v1/sync/events", {
+      project: this.options.project,
+      runtimeId: this.options.runtimeId,
+      events,
+    });
+  }
+
+  private async request<T>(path: string, body: unknown): Promise<T> {
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (this.options.authToken) headers.authorization = `Bearer ${this.options.authToken}`;
+    return await hubJsonRequest<T>(this.options, path, { method: "POST", body: JSON.stringify(body) }, headers);
   }
 }

package/plugins/kxm/src/database.ts

@@ -593,7 +593,7 @@ export function discoverProjectStores(projectRoot: string, options: { hubDataPat
   if (existsSync(hubPath)) {
     // Must track HUB_STORE_SCHEMA_VERSION in store.ts: the hub's own fresh backup is
     // restored through this ceiling, so a bump left behind here refuses it.
-    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: 4 });
+    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: 5 });
   }
 
   const registryPath = join(root, ".kxm", "runtime", "registry.db");
@@ -615,7 +615,7 @@ export function discoverProjectStores(projectRoot: string, options: { hubDataPat
         stores.push({
           storeId: `events:${key}`,
           sourcePath: join(eventsDir, entry.name),
-          maxSupportedVersion: 4,
+          maxSupportedVersion: 6,
         });
       }
     }
@@ -731,14 +731,14 @@ export function restoreBackup(
 
     // The hub-store ceiling. Must track HUB_STORE_SCHEMA_VERSION in store.ts for the
     // same reason as the events ceiling below.
-    let maxSupported = 4;
+    let maxSupported = 5;
     if (store.storeId === "registry" || store.storeId === "binding-store") {
       maxSupported = 1;
     } else if (store.storeId.startsWith("events:")) {
       // Must track KXM_EVENT_STORE_SCHEMA_VERSION in runtime-store.ts. The pin is
       // the e6 backup/restore round-trip test: bump one without the other and it
       // refuses its own fresh backup.
-      maxSupported = 5;
+      maxSupported = 6;
     }
 
     let targetPath = store.sourcePath;

package/plugins/kxm/src/external-effects.ts

@@ -32,7 +32,7 @@ export type ExternalActionKind =
   | "tracker-issue"
   | "webhook";
 
-export type ExternalEffectStatus = "in-flight" | "committed" | "failed" | "aborted";
+export type ExternalEffectStatus = "in-flight" | "committed" | "failed" | "aborted" | "uncertain";
 
 export interface ExternalEffectReceipt {
   schema: typeof EXTERNAL_EFFECT_SCHEMA;
@@ -233,6 +233,13 @@ export class ExternalEffectsLedger {
 
     const existing = this.getReceipt(effectKey);
     if (existing) {
+      if (existing.status === "uncertain") {
+        return {
+          ok: false,
+          error: `effect_uncertain: ${input.actionKind} on ${input.targetRef} is parked as uncertain after a fencing conflict and requires explicit recovery`,
+          existing,
+        };
+      }
       if (existing.status === "committed") {
         return {
           ok: false,
@@ -315,6 +322,12 @@ export class ExternalEffectsLedger {
     return { ok: true, lastHeartbeatAt: now };
   }
 
+  /** Park an effect as uncertain: a fencing conflict means the outside world
+   * may have been touched, and only explicit recovery can unblock it. */
+  markUncertain(effectKey: string): void {
+    this.db.prepare("UPDATE external_effects SET status = 'uncertain' WHERE effect_key = ? AND status = 'in-flight'").run(effectKey);
+  }
+
   commitEffect(
     effectKey: string,
     receiptPayload: Record<string, unknown>,
@@ -392,6 +405,8 @@ export type SharedEffectRefusalCode =
   | "effect_lease_superseded"
   | "effect_already_committed"
   | "effect_in_flight"
+  /** The effect is parked as uncertain after a fencing conflict. */
+  | "effect_uncertain"
   | "effect_not_in_flight"
   | "effect_not_found";
 
@@ -494,6 +509,7 @@ export async function claimSharedEffect(input: {
 }): Promise<SharedEffectClaim | SharedEffectRefusal> {
   const needsLease = effectRequiresHubLease(input.actionKind, input.targetRef, input.runId);
   let lease: EffectLease | undefined;
+  let leaseRenewed = false;
 
   if (needsLease) {
     if (!input.lease) {
@@ -506,6 +522,7 @@ export async function claimSharedEffect(input: {
     try {
       const acquired = await input.lease.acquireLease(input.targetRef, input.leaseTtlMs ?? DEFAULT_LEASE_TIMEOUT_MS);
       lease = acquired.lease;
+      leaseRenewed = acquired.renewed === true;
     } catch (error) {
       const code = errorCodeOf(error);
       if (code === "lease_held") {
@@ -535,12 +552,17 @@ export async function claimSharedEffect(input: {
   });
 
   if (!claimed.ok) {
-    // The ledger refused after the lease was taken, so give the resource back
-    // rather than parking it until the TTL runs out.
-    if (lease && input.lease) await releaseQuietly(input.lease, input.targetRef, lease.fencingToken);
+    // Only hand back a lease this caller newly acquired. A renewal of an
+    // existing holder's lease must survive a claim refusal: the original
+    // effect is still in-flight and still needs the fence.
+    if (lease && input.lease && !leaseRenewed) {
+      await releaseQuietly(input.lease, input.targetRef, lease.fencingToken);
+    }
     return {
       ok: false,
-      code: claimed.error.startsWith("effect_already_committed") ? "effect_already_committed" : "effect_in_flight",
+      code: claimed.error.startsWith("effect_already_committed")
+        ? "effect_already_committed"
+        : claimed.error.startsWith("effect_uncertain") ? "effect_uncertain" : "effect_in_flight",
       error: claimed.error,
       existing: claimed.existing,
     };
@@ -653,6 +675,9 @@ export async function commitSharedEffect(input: {
       await input.lease.renewLease(receipt.targetRef, receipt.fencingToken!, input.leaseTtlMs ?? DEFAULT_LEASE_TIMEOUT_MS);
     } catch (error) {
       const code = errorCodeOf(error);
+      if (isLeaseLost(code)) {
+        input.ledger.markUncertain(input.effectKey);
+      }
       return {
         ok: false,
         code: isLeaseLost(code) ? "effect_lease_superseded" : "effect_lease_unavailable",

package/plugins/kxm/src/hub.ts

@@ -17,6 +17,7 @@ import {
   MAX_LEASE_RESOURCE_CHARS,
   MAX_LEASE_TTL_MS,
   MAX_MESSAGE_TTL_MS,
+  MAX_SYNC_BATCH_EVENTS,
   MIN_LEASE_TTL_MS,
   MIN_MESSAGE_TTL_MS,
   MIN_MESSAGE_RETENTION_MS,
@@ -33,8 +34,12 @@ import {
   type HubEvent,
   type LeaseRecord,
   type MessageRecord,
+  type RuntimePresenceRecord,
+  type StoredSyncEvent,
   type WorkflowMessageContext,
 } from "./protocol.ts";
+import { kxmCanonicalJson, syncEventSchemaErrors, type JsonValue } from "./project-config.ts";
+import { kxmSyncEventHash } from "./sync-transform.ts";
 import { workflowScopeExtras } from "./diagnostics.ts";
 import { timingSafeStringCompare } from "./commands.ts";
 import { arbitrate, explainContextItem, journalEntryToContextItem, memoryRecordToContextItem, rolePolicy } from "./arbiter.ts";
@@ -137,6 +142,32 @@ function publicAgent(agent: StoredAgent, staleAfterMs: number, now = Date.now())
   return toAgentRecord(identity, staleAfterMs, now);
 }
 
+/** Runtime ids share the contract's opaque-id shape (`rtm_…`). */
+const RUNTIME_ID_PATTERN = /^[a-z][a-z0-9]{1,15}_[A-Za-z0-9][A-Za-z0-9_-]{5,127}$/;
+
+function requireRuntimeId(value: unknown): string {
+  const runtimeId = requireString(value, "runtimeId", { max: 144 });
+  if (!RUNTIME_ID_PATTERN.test(runtimeId)) {
+    throw new ProtocolError(400, "runtimeId must be an opaque runtime id", "invalid_runtime_id");
+  }
+  return runtimeId;
+}
+
+/** A Runtime's presence as readers see it. The lease is the same hub-clocked
+ * window agents get: `heartbeatAt + staleAfterMs`. */
+function runtimePresenceView(record: RuntimePresenceRecord, staleAfterMs: number, nowMs: number) {
+  const heartbeatMs = Date.parse(record.heartbeatAt);
+  const leaseExpiresMs = Number.isFinite(heartbeatMs) ? heartbeatMs + staleAfterMs : 0;
+  return {
+    runtimeId: record.runtimeId,
+    ...(record.host ? { host: record.host } : {}),
+    registeredAt: record.registeredAt,
+    heartbeatAt: record.heartbeatAt,
+    leaseExpiresAt: new Date(leaseExpiresMs).toISOString(),
+    presence: leaseExpiresMs > nowMs ? "online" as const : "expired" as const,
+  };
+}
+
 function safeTokenEqual(actual: string | undefined, expected: string): boolean {
   return timingSafeStringCompare(actual, expected);
 }
@@ -506,6 +537,11 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     leasesGranted: 0,
     leasesRefused: 0,
     leasesReleased: 0,
+    syncEventsAccepted: 0,
+    syncEventsDuplicate: 0,
+    syncEventsRefused: 0,
+    syncConflicts: 0,
+    runtimeHeartbeats: 0,
   };
   let cleanupTimer: NodeJS.Timeout | undefined;
   let closed = false;
@@ -672,6 +708,74 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     }
   }
 
+  /**
+   * Synchronized runs grouped by their home Runtime. Built from the gapless
+   * prefix of each run only, so a missing sequence is shown as pending and
+   * never papered over. `orphaned` is view state: the home Runtime's presence
+   * lease has expired (or it never registered). Nothing is migrated.
+   */
+  function homeRuntimesView(project: string, nowMs: number) {
+    const presence = new Map(store.listRuntimePresence(project).map((record) => [record.runtimeId, record]));
+    const runs = new Map<string, StoredSyncEvent[]>();
+    for (const event of store.listSyncEvents(project)) {
+      const key = `${event.projectId}\u0000${event.runId}`;
+      const bucket = runs.get(key);
+      if (bucket) bucket.push(event);
+      else runs.set(key, [event]);
+    }
+    const homes = new Map<string, Array<Record<string, unknown>>>();
+    for (const events of runs.values()) {
+      const first = events[0]!;
+      let cursor = 0;
+      let status: string | undefined;
+      let workflowId: string | undefined;
+      let displayTitle: string | undefined;
+      let updatedAt: string | undefined;
+      for (const event of events) {
+        if (event.sequence !== cursor + 1) break;
+        cursor = event.sequence;
+        const parsed = JSON.parse(event.bytes) as { occurredAt?: string; payload?: Record<string, unknown> };
+        const payload = parsed.payload ?? {};
+        if (event.eventType.startsWith("run.") && typeof payload.status === "string") status = payload.status;
+        if (typeof payload.workflowId === "string") workflowId = payload.workflowId;
+        if (typeof payload.displayTitle === "string") displayTitle = payload.displayTitle;
+        if (typeof parsed.occurredAt === "string") updatedAt = parsed.occurredAt;
+      }
+      const home = presence.get(first.homeRuntimeId);
+      const orphaned = !home || runtimePresenceView(home, staleAfterMs, nowMs).presence === "expired";
+      const list = homes.get(first.homeRuntimeId) ?? [];
+      list.push({
+        projectId: first.projectId,
+        runId: first.runId,
+        ...(workflowId ? { workflowId } : {}),
+        ...(displayTitle ? { displayTitle } : {}),
+        ...(status ? { status } : {}),
+        lastSequence: cursor,
+        pendingGap: events.length > cursor,
+        ...(updatedAt ? { updatedAt } : {}),
+        orphaned,
+      });
+      homes.set(first.homeRuntimeId, list);
+    }
+    for (const runtimeId of presence.keys()) if (!homes.has(runtimeId)) homes.set(runtimeId, []);
+    return [...homes.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([runtimeId, homeRuns]) => {
+        const record = presence.get(runtimeId);
+        const view = record ? runtimePresenceView(record, staleAfterMs, nowMs) : undefined;
+        return {
+          runtimeId,
+          ...(view ? { host: view.host, heartbeatAt: view.heartbeatAt, leaseExpiresAt: view.leaseExpiresAt } : {}),
+          presence: view?.presence ?? "unknown",
+          orphaned: !view || view.presence === "expired",
+          runs: homeRuns
+            .sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")))
+            .slice(0, 16),
+          runTotal: homeRuns.length,
+        };
+      });
+  }
+
   function opsSnapshot(project: string) {
     const snapshotAt = Date.now();
     const projectAgents = [...agents.values()]
@@ -716,6 +820,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         };
       }),
       runTotal: projectRuns.length,
+      homeRuntimes: homeRuntimesView(project, hubNow()),
       plans: [...journal.values()]
         .filter((entry) => entry.category === "plan" && projectRuns.some((run) => run.id === entry.runId))
         .sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt))
@@ -1173,6 +1278,16 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       `kxm_leases_refused_total ${counters.leasesRefused}`,
       "# TYPE kxm_leases_released_total counter",
       `kxm_leases_released_total ${counters.leasesReleased}`,
+      "# TYPE kxm_sync_events_accepted_total counter",
+      `kxm_sync_events_accepted_total ${counters.syncEventsAccepted}`,
+      "# TYPE kxm_sync_events_duplicate_total counter",
+      `kxm_sync_events_duplicate_total ${counters.syncEventsDuplicate}`,
+      "# TYPE kxm_sync_events_refused_total counter",
+      `kxm_sync_events_refused_total ${counters.syncEventsRefused}`,
+      "# TYPE kxm_sync_conflicts_total counter",
+      `kxm_sync_conflicts_total ${counters.syncConflicts}`,
+      "# TYPE kxm_runtime_heartbeats_total counter",
+      `kxm_runtime_heartbeats_total ${counters.runtimeHeartbeats}`,
       "",
     ].join("\n");
   }
@@ -2259,6 +2374,112 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         return;
       }
 
+      // Runtime presence (P5). A Runtime is a machine client, not an agent: it
+      // is admitted by the project token and declares its id and host label.
+      // The hub stamps the heartbeat with its own clock; that stamp plus
+      // staleAfterMs is the presence lease the ops snapshot reads.
+      if (method === "POST" && url.pathname === "/v1/runtime/presence") {
+        const body = await readJson(request);
+        const project = requireString(body.project, "project", { max: 128 });
+        requireProjectAuth(request, project);
+        const runtimeId = requireRuntimeId(body.runtimeId);
+        const hostLabel = optionalString(body.host, "host", MAX_AGENT_HOST_CHARS);
+        const heartbeatAt = new Date(hubNow()).toISOString();
+        const existing = store.getRuntimePresence(project, runtimeId);
+        const record: RuntimePresenceRecord = {
+          runtimeId,
+          project,
+          ...(hostLabel ? { host: hostLabel } : {}),
+          registeredAt: existing?.registeredAt ?? heartbeatAt,
+          heartbeatAt,
+        };
+        store.saveRuntimePresence(record);
+        counters.runtimeHeartbeats += 1;
+        if (!existing) logger({ event: "runtime_registered", project, runtimeId, ...(hostLabel ? { host: hostLabel } : {}) });
+        json(response, existing ? 200 : 201, { presence: runtimePresenceView(record, staleAfterMs, hubNow()) });
+        return;
+      }
+
+      // Run-fact sync (P5), not a peer transport. Each event is accepted once by
+      // {projectId, runId, sequence}: identical bytes are an idempotent
+      // duplicate, different bytes under a used sequence are refused and raised
+      // as a security alert. Out-of-order events are held; the per-run cursor is
+      // the gapless prefix, so a gap stays pending until it is filled.
+      if (method === "POST" && url.pathname === "/v1/sync/events") {
+        const body = await readJson(request);
+        const project = requireString(body.project, "project", { max: 128 });
+        requireProjectAuth(request, project);
+        const runtimeId = requireRuntimeId(body.runtimeId);
+        if (!Array.isArray(body.events)) {
+          throw new ProtocolError(400, "events must be an array", "invalid_sync_batch");
+        }
+        if (body.events.length > MAX_SYNC_BATCH_EVENTS) {
+          throw new ProtocolError(413, `a sync batch holds at most ${MAX_SYNC_BATCH_EVENTS} events`, "sync_batch_too_large");
+        }
+        const receivedAt = new Date(hubNow()).toISOString();
+        const results: Array<Record<string, unknown>> = [];
+        const touched = new Map<string, { projectId: string; runId: string }>();
+        for (const candidate of body.events as unknown[]) {
+          const identity = candidate && typeof candidate === "object" && !Array.isArray(candidate)
+            ? candidate as Record<string, unknown>
+            : {};
+          const echo = {
+            ...(typeof identity.projectId === "string" ? { projectId: identity.projectId.slice(0, 144) } : {}),
+            ...(typeof identity.runId === "string" ? { runId: identity.runId.slice(0, 144) } : {}),
+            ...(Number.isInteger(identity.sequence) ? { sequence: identity.sequence } : {}),
+          };
+          if (syncEventSchemaErrors(candidate) !== undefined) {
+            counters.syncEventsRefused += 1;
+            results.push({ ...echo, outcome: "rejected", code: "sync_event_invalid" });
+            continue;
+          }
+          const event = identity as { projectId: string; runId: string; sequence: number; homeRuntimeId: string; eventType: string };
+          if (event.homeRuntimeId !== runtimeId) {
+            counters.syncEventsRefused += 1;
+            logger({ event: "security_alert", alert: "sync_runtime_mismatch", project, runtimeId, ...echo, homeRuntimeId: event.homeRuntimeId });
+            results.push({ ...echo, outcome: "rejected", code: "sync_runtime_mismatch" });
+            continue;
+          }
+          const bytes = kxmCanonicalJson(candidate as JsonValue);
+          const contentHash = kxmSyncEventHash(bytes);
+          const outcome = store.ingestSyncEvent({
+            projectId: event.projectId,
+            runId: event.runId,
+            sequence: event.sequence,
+            hubProject: project,
+            homeRuntimeId: event.homeRuntimeId,
+            eventType: event.eventType,
+            contentHash,
+            receivedAt,
+            bytes,
+          });
+          if (outcome.outcome === "conflict") {
+            counters.syncConflicts += 1;
+            counters.syncEventsRefused += 1;
+            logger({
+              event: "security_alert",
+              alert: "sync_sequence_conflict",
+              reason: outcome.reason,
+              project,
+              runtimeId,
+              ...echo,
+              presentedHash: contentHash,
+              ...(outcome.existingHash ? { existingHash: outcome.existingHash } : {}),
+            });
+            results.push({ ...echo, outcome: "conflict", code: `sync_${outcome.reason}` });
+            continue;
+          }
+          if (outcome.outcome === "accepted") counters.syncEventsAccepted += 1;
+          else counters.syncEventsDuplicate += 1;
+          touched.set(`${event.projectId}\u0000${event.runId}`, { projectId: event.projectId, runId: event.runId });
+          results.push({ ...echo, outcome: outcome.outcome });
+        }
+        const cursors = [...touched.values()].map((run) => ({ ...run, cursor: store.syncCursor(run.projectId, run.runId) }));
+        if (results.some((result) => result.outcome === "accepted")) publishOps(project, "workflows");
+        json(response, 200, { results, cursors });
+        return;
+      }
+
       // One writer, one clock. Every branch below decides inside a single store
       // transaction, so two agents racing for the same resource cannot both read it
       // free. The fencing token increments only on takeover, which is what lets a

package/plugins/kxm/src/mcp-server.ts

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.72";
+const VERSION = "0.7.74";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/project-config.ts

@@ -163,6 +163,7 @@ export class KxmSchemaRegistry {
   readonly driveReceiptValidator: ValidateFunction;
   readonly coordinatorValidator: ValidateFunction;
   readonly intakeMessageValidator: ValidateFunction;
+  readonly syncEventValidator: ValidateFunction;
 
   constructor(schemasDir = DEFAULT_SCHEMA_DIR) {
     this.schemasDir = resolve(schemasDir);
@@ -180,6 +181,7 @@ export class KxmSchemaRegistry {
     const driveReceiptFile = "drive-receipt.schema.json";
     const coordinatorFile = "coordinator.schema.json";
     const intakeMessageFile = "intake-message.schema.json";
+    const syncEventFile = "sync-event.schema.json";
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, localBindingsFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, templateProvenanceFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, initOperationFile)));
@@ -188,6 +190,7 @@ export class KxmSchemaRegistry {
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, driveReceiptFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, coordinatorFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, intakeMessageFile)));
+    this.ajv.addSchema(readJsonObject(join(this.schemasDir, syncEventFile)));
     for (const [kind, definition] of Object.entries(RESOURCE_SCHEMA) as [KxmResourceKind, { identity: string; file: string }][]) {
       const validator = this.ajv.getSchema(`https://schemas.kxm.dev/${definition.file}`);
       if (!validator) throw new Error(`schema did not compile: ${definition.file}`);
@@ -201,6 +204,7 @@ export class KxmSchemaRegistry {
     const driveReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${driveReceiptFile}`);
     const coordinatorValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${coordinatorFile}`);
     const intakeMessageValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${intakeMessageFile}`);
+    const syncEventValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${syncEventFile}`);
     if (!localBindingsValidator) throw new Error(`schema did not compile: ${localBindingsFile}`);
     if (!templateProvenanceValidator) throw new Error(`schema did not compile: ${templateProvenanceFile}`);
     if (!initOperationValidator) throw new Error(`schema did not compile: ${initOperationFile}`);
@@ -209,6 +213,7 @@ export class KxmSchemaRegistry {
     if (!driveReceiptValidator) throw new Error(`schema did not compile: ${driveReceiptFile}`);
     if (!coordinatorValidator) throw new Error(`schema did not compile: ${coordinatorFile}`);
     if (!intakeMessageValidator) throw new Error(`schema did not compile: ${intakeMessageFile}`);
+    if (!syncEventValidator) throw new Error(`schema did not compile: ${syncEventFile}`);
     this.localBindingsValidator = localBindingsValidator;
     this.templateProvenanceValidator = templateProvenanceValidator;
     this.initOperationValidator = initOperationValidator;
@@ -217,6 +222,7 @@ export class KxmSchemaRegistry {
     this.driveReceiptValidator = driveReceiptValidator;
     this.coordinatorValidator = coordinatorValidator;
     this.intakeMessageValidator = intakeMessageValidator;
+    this.syncEventValidator = syncEventValidator;
   }
 
   validate(kind: KxmResourceKind, value: JsonObject, file: string): KxmConfigIssue[] {
@@ -274,6 +280,15 @@ export function validateRunEvent(value: unknown, file: string): void {
   }
 }
 
+/** Check a derived sync object against `kxm.sync-event.v1`. Returns the
+ * schema errors instead of throwing so the transform can fall back to a
+ * degraded object and the hub can refuse one event without failing a batch. */
+export function syncEventSchemaErrors(value: unknown): string | undefined {
+  const registry = (cachedRunEventRegistry ??= new KxmSchemaRegistry());
+  if (registry.syncEventValidator(value)) return undefined;
+  return registry.ajv.errorsText(registry.syncEventValidator.errors, { separator: "; " });
+}
+
 /** Validate a drive receipt against `kxm.drive-receipt.v1`. Throws `drive_receipt_invalid`. */
 export function validateDriveReceipt(value: unknown, file: string): void {
   const registry = (cachedRunEventRegistry ??= new KxmSchemaRegistry());

package/plugins/kxm/src/protocol.ts

@@ -93,6 +93,33 @@ export interface LeaseRecord {
   expiresAt: string;
 }
 
+/** A Runtime's machine-client presence in one hub project (P5). Not an agent:
+ * it holds no agent key, sends no messages, and is admitted by the project
+ * token alone. `heartbeatAt` is the hub's clock. */
+export interface RuntimePresenceRecord {
+  runtimeId: string;
+  project: string;
+  host?: string;
+  registeredAt: string;
+  heartbeatAt: string;
+}
+
+/** One accepted sync event as the hub holds it (P5). `bytes` is the canonical
+ * `kxm.sync-event.v1` text; `contentHash` is its sha256, the conflict test. */
+export interface StoredSyncEvent {
+  projectId: string;
+  runId: string;
+  sequence: number;
+  hubProject: string;
+  homeRuntimeId: string;
+  eventType: string;
+  contentHash: string;
+  receivedAt: string;
+  bytes: string;
+}
+
+export const MAX_SYNC_BATCH_EVENTS = 100;
+
 export interface MessageReply {
   content: string;
   createdAt: string;