@kontextmind/kxm 0.7.71 → 0.7.73

package/plugins/kxm/src/hub.ts

@@ -4,6 +4,7 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { isIP } from "node:net";
 import { dirname, join, resolve } from "node:path";
 import {
+  DEFAULT_LEASE_TTL_MS,
   DEFAULT_MAX_HOPS,
   DEFAULT_MESSAGE_RETENTION_MS,
   DEFAULT_MESSAGE_TTL_MS,
@@ -13,7 +14,11 @@ import {
   MAX_AGENT_HOST_CHARS,
   MAX_BODY_BYTES,
   MAX_CONTENT_CHARS,
+  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,
   ProtocolError,
@@ -27,9 +32,14 @@ import {
   type AgentRecord,
   type DeliveryMode,
   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";
@@ -39,7 +49,7 @@ import { NativeStateProvider } from "./state.ts";
 import { SkillLifecycle } from "./skills.ts";
 import { compileKnowledgeWiki, lintKnowledgeWiki, type WikiSourcePool } from "./wiki.ts";
 import { buildRetrospective, writeRetrospective } from "./retrospective.ts";
-import { MeshStore, type StoredAgent } from "./store.ts";
+import { MeshStore, type LeaseRefusal, type StoredAgent } from "./store.ts";
 import {
   canonicalWorkflowEvidenceKey,
   approveWorkflowDegradation,
@@ -91,6 +101,10 @@ export interface MeshHubOptions {
   skillsDir?: string;
   skillLifecycle?: SkillLifecycle;
   repoRoot?: string;
+  /** The hub clock every lease decision reads. Injectable so a test can move a
+   * lease past its deadline instead of sleeping through a real TTL; production
+   * leaves it at `Date.now`. It is never a client-supplied time. */
+  now?: () => number;
 }
 
 export interface MeshHub {
@@ -128,10 +142,68 @@ 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);
 }
 
+/** The wire answer for a lease the hub will not extend or release. Every one of
+ * these means the caller's token no longer authorizes a shared write: the
+ * holder must stop, not retry. The current lease rides along so the caller can
+ * record who holds the resource now. */
+function leaseRefusal(reason: LeaseRefusal, name: string, lease?: LeaseRecord): ProtocolError {
+  if (reason === "missing") {
+    return new ProtocolError(404, `no lease is held on ${name}`, "lease_not_found");
+  }
+  if (reason === "expired") {
+    return new ProtocolError(
+      409,
+      `lease on ${name} expired at ${lease?.expiresAt ?? "its deadline"}; re-acquire to take it over`,
+      "lease_expired",
+      { lease },
+    );
+  }
+  if (reason === "held") {
+    return new ProtocolError(
+      409,
+      `lease on ${name} is held by ${lease?.holderAgentName ?? "another agent"} until ${lease?.expiresAt ?? "its deadline"}`,
+      "lease_held",
+      { lease },
+    );
+  }
+  return new ProtocolError(
+    409,
+    `fencing token for ${name} was superseded; the hub is now at token ${lease?.fencingToken ?? "a newer value"}`,
+    "lease_superseded",
+    { lease },
+  );
+}
+
 function bearerToken(request: IncomingMessage): string | undefined {
   const header = request.headers.authorization;
   return header?.startsWith("Bearer ") ? header.slice(7) : undefined;
@@ -409,6 +481,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       };
   const webhookWorkflows = new Map((options.webhookWorkflows ?? []).map((workflow) => [workflow.id, workflow]));
   const logger = options.logger ?? (() => undefined);
+  const hubNow = options.now ?? (() => Date.now());
   const assetsDir = options.assetsDir;
   const hubRepoRoot = options.repoRoot ?? (options.dataPath && options.dataPath !== ":memory:" ? resolve(dirname(dirname(options.dataPath))) : process.cwd());
   const store = new MeshStore(options.dataPath);
@@ -461,6 +534,14 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     contextRequests: 0,
     attemptLatencySecondsTotal: 0,
     meteredCostUsdTotal: 0,
+    leasesGranted: 0,
+    leasesRefused: 0,
+    leasesReleased: 0,
+    syncEventsAccepted: 0,
+    syncEventsDuplicate: 0,
+    syncEventsRefused: 0,
+    syncConflicts: 0,
+    runtimeHeartbeats: 0,
   };
   let cleanupTimer: NodeJS.Timeout | undefined;
   let closed = false;
@@ -627,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()]
@@ -671,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))
@@ -1065,6 +1215,16 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     for (const runId of swept.purgedRuns) {
       logger({ event: "workflow_run_purged", runId });
     }
+    for (const lease of swept.purgedLeases) {
+      logger({
+        event: "lease_purged",
+        resource: lease.resource,
+        project: lease.project,
+        agentId: lease.holderAgentId,
+        fencingToken: lease.fencingToken,
+        expiresAt: lease.expiresAt,
+      });
+    }
   }
 
   function metricsBody(): string {
@@ -1112,6 +1272,22 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       `kxm_attempt_latency_seconds_total ${counters.attemptLatencySecondsTotal}`,
       "# TYPE kxm_metered_cost_usd_total counter",
       `kxm_metered_cost_usd_total ${counters.meteredCostUsdTotal}`,
+      "# TYPE kxm_leases_granted_total counter",
+      `kxm_leases_granted_total ${counters.leasesGranted}`,
+      "# TYPE kxm_leases_refused_total counter",
+      `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");
   }
@@ -2198,6 +2374,187 @@ 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
+      // holder that slept past its deadline be refused at commit instead of writing
+      // behind whoever replaced it.
+      const leaseMatch = url.pathname.match(/^\/v1\/leases\/([^/]+)\/(acquire|renew|release)$/);
+      if (method === "POST" && leaseMatch) {
+        const holder = requireAgent(request);
+        requireProjectAuth(request, holder.project);
+        const name = requireString(decodeURIComponent(leaseMatch[1]!), "resource", { max: MAX_LEASE_RESOURCE_CHARS });
+        const action = leaseMatch[2]!;
+        const body = await readJson(request);
+        // The caller never names the prefix, so the same branch in two projects is
+        // two leases and neither project can reach the other's.
+        const resource = `${holder.project}/${name}`;
+        const nowMs = hubNow();
+        const leaseLog = { resource, project: holder.project, agentId: holder.id, agentName: holder.name };
+
+        if (action === "acquire") {
+          const ttlMs = parseBoundedInteger(body.ttlMs, "ttlMs", DEFAULT_LEASE_TTL_MS, MIN_LEASE_TTL_MS, MAX_LEASE_TTL_MS);
+          const outcome = store.acquireLease({
+            resource,
+            project: holder.project,
+            name,
+            holderAgentId: holder.id,
+            holderAgentName: holder.name,
+            ttlMs,
+            nowMs,
+          });
+          if (!outcome.ok) {
+            counters.leasesRefused += 1;
+            logger({ event: "lease_denied", ...leaseLog, reason: outcome.reason, heldBy: outcome.lease?.holderAgentId });
+            throw leaseRefusal(outcome.reason, name, outcome.lease);
+          }
+          counters.leasesGranted += 1;
+          logger({
+            event: outcome.renewed ? "lease_renewed" : "lease_acquired",
+            ...leaseLog,
+            fencingToken: outcome.lease.fencingToken,
+            expiresAt: outcome.lease.expiresAt,
+          });
+          json(response, 200, { lease: outcome.lease, renewed: outcome.renewed });
+          return;
+        }
+
+        if (body.fencingToken === undefined) {
+          throw new ProtocolError(400, "fencingToken is required", "lease_token_required");
+        }
+        const fencingToken = parseBoundedInteger(body.fencingToken, "fencingToken", 1, 1, Number.MAX_SAFE_INTEGER);
+        if (action === "renew") {
+          const ttlMs = parseBoundedInteger(body.ttlMs, "ttlMs", DEFAULT_LEASE_TTL_MS, MIN_LEASE_TTL_MS, MAX_LEASE_TTL_MS);
+          const outcome = store.renewLease({ resource, holderAgentId: holder.id, fencingToken, ttlMs, nowMs });
+          if (!outcome.ok) {
+            counters.leasesRefused += 1;
+            logger({ event: "lease_denied", ...leaseLog, reason: outcome.reason, fencingToken });
+            throw leaseRefusal(outcome.reason, name, outcome.lease);
+          }
+          counters.leasesGranted += 1;
+          logger({ event: "lease_renewed", ...leaseLog, fencingToken, expiresAt: outcome.lease.expiresAt });
+          json(response, 200, { lease: outcome.lease, renewed: true });
+          return;
+        }
+
+        const outcome = store.releaseLease({ resource, holderAgentId: holder.id, fencingToken });
+        if (!outcome.ok) {
+          counters.leasesRefused += 1;
+          logger({ event: "lease_denied", ...leaseLog, reason: outcome.reason, fencingToken });
+          throw leaseRefusal(outcome.reason, name, outcome.lease);
+        }
+        counters.leasesReleased += 1;
+        logger({ event: "lease_released", ...leaseLog, fencingToken });
+        json(response, 200, { released: true, lease: outcome.lease });
+        return;
+      }
+
       if (method === "GET" && url.pathname === "/v1/events") {
         const agentId = requireString(url.searchParams.get("agentId"), "agentId", { max: 80 });
         const current = requireAgent(request, agentId);

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.71";
+const VERSION = "0.7.73";
 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

@@ -13,6 +13,10 @@ export const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
 export const MAX_BODY_BYTES = 256 * 1024;
 export const MAX_CONTENT_CHARS = 32_000;
 export const MAX_AGENT_HOST_CHARS = 64;
+export const MIN_LEASE_TTL_MS = 5_000;
+export const MAX_LEASE_TTL_MS = 10 * 60_000;
+export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
+export const MAX_LEASE_RESOURCE_CHARS = 200;
 
 export type DeliveryMode = "steer" | "followUp" | "nextTurn";
 export type MessageStatus = "queued" | "delivered" | "replied" | "cancelled" | "expired" | "error";
@@ -68,6 +72,54 @@ export function toAgentRecord(agent: AgentIdentity, staleAfterMs?: number, now?:
   return { ...agent, ...agentPresenceView(agent, staleAfterMs, now) };
 }
 
+/** One hub-held fenced lease over a project-scoped resource.
+ *
+ * `resource` is what the store keys on: the caller's project prefixed onto the
+ * name it asked for, so two projects naming the same branch never contend.
+ * Expiry is the hub's clock, never the holder's, and `fencingToken` increments
+ * only when a new holder takes over an expired lease — a renewal keeps its
+ * token, so a writer that comes back after a takeover can be told its token
+ * was superseded instead of being allowed to commit. */
+export interface LeaseRecord {
+  /** `${project}/${name}`. */
+  resource: string;
+  project: string;
+  /** The resource as the caller named it, without the project prefix. */
+  name: string;
+  holderAgentId: string;
+  holderAgentName: string;
+  fencingToken: number;
+  acquiredAt: string;
+  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;