@xnetjs/runtime 0.5.4 → 0.6.0

package/README.md

@@ -6,6 +6,11 @@ node-format validation, signing, encryption, SQLite-backed storage, and the live
 query/mutate/subscribe loop — is usable from **any** framework, a CLI, a worker,
 or a plain Node service.
 
+> **Alpha software.** xNet is released but early: this package is on npm and
+> usable today, but its API can change between releases, sometimes without a
+> migration path. Pin your version. See the
+> [project README](https://github.com/crs48/xNet#readme) for what alpha means here.
+
 Nothing here imports React. The `@xnetjs/react` hooks, the CLI, and other-framework
 adapters are thin bindings over this surface.
 

package/dist/index.d.ts

@@ -794,11 +794,21 @@ declare function createNodePool(config: NodePoolConfig): NodePool;
 /**
  * Trust class of a replication destination. A `trusted` hub holds plaintext and
  * can index/search/serve; a `zero-knowledge` hub holds only recipient-scoped
- * ciphertext and can relay but not read. Carried on the manifest shape here;
- * the plaintext-vs-ciphertext *gate* is a later phase (0258) and not yet
- * enforced.
+ * ciphertext and can relay but not read. The plaintext gate is ENFORCED at the
+ * publish path (`MultiHubSyncManager.publishScoped` withholds plaintext from
+ * zero-knowledge destinations — 0258, closed by 0383 W4); this predicate is
+ * the single definition of the rule.
  */
 type ReplicaTrust = 'trusted' | 'zero-knowledge';
+/** Payload classification for the plaintext gate. */
+type PayloadClass = 'plaintext' | 'ciphertext';
+/**
+ * May a destination of this trust class receive a payload of this class?
+ * Undefined trust is treated as `trusted` for compatibility with existing
+ * configs that never declared a class — tightening that default is a breaking
+ * change to make deliberately, not silently.
+ */
+declare function mayReceivePayload(trust: ReplicaTrust | undefined, payload: PayloadClass): boolean;
 /** The namespace for a Space's content — the routing key for the planner. */
 declare function spaceNamespace(ownerDID: string, spaceId: string): string;
 /**
@@ -910,8 +920,8 @@ interface HubConnection {
     /** The multiplexed transport for this hub. */
     transport: HubTransport;
     /**
-     * Trust class of this hub. Reserved for the plaintext vs zero-knowledge gate
-     * (0258); surfaced on `plannedHubs` but not yet enforced.
+     * Trust class of this hub. ENFORCED at `publishScoped` (0258/0383 W4): a
+     * `zero-knowledge` destination never receives a plaintext payload.
      */
     trust?: ReplicaTrust;
 }
@@ -947,8 +957,20 @@ interface MultiHubSyncManager {
     destinationsFor(namespace: string): string[];
     /** Join a node's room on exactly the hubs the policy selects. */
     joinScopedRoom(nodeId: string, namespace: string, handler: (data: Record<string, unknown>) => void): ScopedRoomHandle;
-    /** Publish to a room on exactly the hubs the namespace routes to. */
-    publishScoped(namespace: string, room: string, data: object): void;
+    /**
+     * Publish to a room on exactly the hubs the namespace routes to. The 0258
+     * trust gate is enforced here: plaintext payloads (the default class) are
+     * WITHHELD from `zero-knowledge` destinations; pass `payload: 'ciphertext'`
+     * for recipient-scoped envelopes, which may go anywhere. Returns which hubs
+     * received and which were withheld, so callers can surface the gap instead
+     * of silently under-replicating.
+     */
+    publishScoped(namespace: string, room: string, data: object, opts?: {
+        payload?: PayloadClass;
+    }): {
+        published: string[];
+        withheld: string[];
+    };
     /** Replace the routing policy; live rooms re-route to match (manifest-as-data). */
     setReplication(replication: SyncReplicationConfig | undefined): void;
     /** Connect every hub transport. */
@@ -1001,6 +1023,11 @@ type NodeSyncResponse = {
     room: string;
     changes: SerializedNodeChange[];
     highWaterMark: number;
+    /**
+     * The hub capped this response and more changes remain past `highWaterMark`.
+     * Older hubs never send it, in which case one response is the whole catch-up.
+     */
+    hasMore?: boolean;
 };
 /**
  * Listener for unknown change type events.
@@ -1041,7 +1068,14 @@ declare class NodeStoreSyncProvider {
     private queuedHashes;
     private sendTimer;
     private sentInWindow;
+    /**
+     * Whether the connected hub advertised `batch-push` in its handshake.
+     * Stays false against older hubs, which keeps the one-change-per-frame
+     * path as the compatible default.
+     */
+    private batchPushSupported;
     private syncResponseResolver;
+    private catchUpPages;
     private structuralRejections;
     private outboundHalted;
     private clearResolver;
@@ -1136,7 +1170,20 @@ declare class NodeStoreSyncProvider {
     private enqueueChange;
     private scheduleDrain;
     private drain;
+    /**
+     * Batched drain (exploration 0357): pack the queue into slabs of up to
+     * MAX_BATCH_CHANGES and send one frame per slab. `sentInWindow` counts
+     * CHANGES, not frames, matching how the hub charges its rate limit — so the
+     * budget stays a real bound on work rather than a bound on syscalls.
+     */
+    private drainBatched;
     private publishChange;
+    /**
+     * Send many changes in one frame. The hub verifies and authorizes each one
+     * individually and re-broadcasts them as ordinary `node-change` messages, so
+     * this is purely a transport-level batch.
+     */
+    private publishChangeBatch;
     private clearSendQueue;
     private serializeChange;
     private deserializeChange;
@@ -1298,7 +1345,7 @@ type InitialSyncManager = {
 declare function createInitialSyncManager(): InitialSyncManager;
 
 /**
- * The umbrella XNet Protocol Version.
+ * The umbrella xNet Protocol Version.
  *
  * Five subsystems version independently (the change record, the Yjs sync
  * envelope, awareness, schemas, the crypto level). To avoid a five-way
@@ -1369,4 +1416,4 @@ declare function negotiateProtocolVersion(ours: readonly string[], theirs: reado
  */
 declare function isProtocolCompatible(theirs: readonly string[]): boolean;
 
-export { type AdapterConformanceCheck, AdapterConformanceError, type AdapterConformanceResult, type BlobStoreForSync, type ConformanceClientFactory, type ConnectionManager, type ConnectionManagerConfig, type ConnectionStatus, type CreateXNetClientOptions, type HubConnection, type HubTransport, type InitialSyncManager, type InitialSyncMessage, type LiveQuery, type LiveQueryValue, METABRIDGE_ORIGIN, METABRIDGE_SEED_ORIGIN, type MetaBridge, type MultiHubConnectionManagerConfig, type MultiHubSyncManager, type MultiHubSyncManagerConfig, type NodePool, type NodePoolConfig, NodeStoreSyncProvider, type NodeSyncResponse, type OfflineQueue, type OfflineQueueConfig, type PlannedHub, type PoolEntryState, type ProgressListener, type QueueEntry, type Registry, type RegistryConfig, type RegistryStorage, type ReplicaTrust, type ReplicationDestinationSpec, type ReplicationScopeNode, type ScopedRoomHandle, type SerializedNodeChange, type SpaceReplicationPolicy, type SyncBlockedListener, type SyncBlockedReason, type SyncManager, type SyncManagerConfig, type SyncPhase, type SyncProgress, type SyncReconciliationOptions, type SyncReconciliationReport, type SyncStatus, type TrackedNode, WebSocketSyncProvider, type WebSocketSyncProviderOptions, XNET_AWARENESS_VERSION, XNET_DATA_MODEL_VERSION, XNET_PROTOCOL_VERSION, XNET_SCHEMA_VERSION, XNET_SUPPORTED_PROTOCOL_VERSIONS, XNET_SYNC_ENVELOPE_VERSION, XNET_UCAN_PROFILE, type XNetClient, type XNetClientBridgeMode, type XNetClientPluginOptions, type XNetClientRuntimePhase, type XNetClientRuntimeStatus, type XNetClientSyncOptions, type XNetClientTelemetry, type XNetClientUndoOptions, type XNetProtocolBundle, channelShareRoom, createConnectionManager, createInitialSyncManager, createMetaBridge, createMultiHubConnectionManager, createMultiHubSyncManager, createNodePool, createOfflineQueue, createRegistry, createSyncManager, createXNetClient, isProtocolCompatible, liveQuery, namespaceForNode, negotiateProtocolVersion, replicationConfigFromPolicies, runAdapterConformance, spaceNamespace, systemNamespace, workspaceShareRoom };
+export { type AdapterConformanceCheck, AdapterConformanceError, type AdapterConformanceResult, type BlobStoreForSync, type ConformanceClientFactory, type ConnectionManager, type ConnectionManagerConfig, type ConnectionStatus, type CreateXNetClientOptions, type HubConnection, type HubTransport, type InitialSyncManager, type InitialSyncMessage, type LiveQuery, type LiveQueryValue, METABRIDGE_ORIGIN, METABRIDGE_SEED_ORIGIN, type MetaBridge, type MultiHubConnectionManagerConfig, type MultiHubSyncManager, type MultiHubSyncManagerConfig, type NodePool, type NodePoolConfig, NodeStoreSyncProvider, type NodeSyncResponse, type OfflineQueue, type OfflineQueueConfig, type PayloadClass, type PlannedHub, type PoolEntryState, type ProgressListener, type QueueEntry, type Registry, type RegistryConfig, type RegistryStorage, type ReplicaTrust, type ReplicationDestinationSpec, type ReplicationScopeNode, type ScopedRoomHandle, type SerializedNodeChange, type SpaceReplicationPolicy, type SyncBlockedListener, type SyncBlockedReason, type SyncManager, type SyncManagerConfig, type SyncPhase, type SyncProgress, type SyncReconciliationOptions, type SyncReconciliationReport, type SyncStatus, type TrackedNode, WebSocketSyncProvider, type WebSocketSyncProviderOptions, XNET_AWARENESS_VERSION, XNET_DATA_MODEL_VERSION, XNET_PROTOCOL_VERSION, XNET_SCHEMA_VERSION, XNET_SUPPORTED_PROTOCOL_VERSIONS, XNET_SYNC_ENVELOPE_VERSION, XNET_UCAN_PROFILE, type XNetClient, type XNetClientBridgeMode, type XNetClientPluginOptions, type XNetClientRuntimePhase, type XNetClientRuntimeStatus, type XNetClientSyncOptions, type XNetClientTelemetry, type XNetClientUndoOptions, type XNetProtocolBundle, channelShareRoom, createConnectionManager, createInitialSyncManager, createMetaBridge, createMultiHubConnectionManager, createMultiHubSyncManager, createNodePool, createOfflineQueue, createRegistry, createSyncManager, createXNetClient, isProtocolCompatible, liveQuery, mayReceivePayload, namespaceForNode, negotiateProtocolVersion, replicationConfigFromPolicies, runAdapterConformance, spaceNamespace, systemNamespace, workspaceShareRoom };

package/dist/index.js

@@ -934,9 +934,12 @@ import { base64ToBytes, bytesToBase64 } from "@xnetjs/crypto";
 var KNOWN_CHANGE_TYPES = /* @__PURE__ */ new Set(["node-change"]);
 var MAX_SENDS_PER_WINDOW = 40;
 var SEND_WINDOW_MS = 1e3;
+var MAX_BATCH_CHANGES = 1e3;
+var MAX_BATCHED_CHANGES_PER_WINDOW = 5e3;
 var SYNC_RESPONSE_TIMEOUT_MS = 4e3;
 var STRUCTURAL_REJECTION_CODES = /* @__PURE__ */ new Set(["INVALID_HASH", "INVALID_SIGNATURE", "INVALID_CHANGE"]);
 var MAX_STRUCTURAL_REJECTIONS = 5;
+var MAX_CATCH_UP_PAGES = 500;
 var OUTBOUND_ENQUEUE_BATCH = 1024;
 var HEAVY_RESYNC_CHANGES = 5e3;
 var HEAVY_RESYNC_MS = 250;
@@ -981,8 +984,16 @@ var NodeStoreSyncProvider = class {
   queuedHashes = /* @__PURE__ */ new Set();
   sendTimer = null;
   sentInWindow = 0;
+  /**
+   * Whether the connected hub advertised `batch-push` in its handshake.
+   * Stays false against older hubs, which keeps the one-change-per-frame
+   * path as the compatible default.
+   */
+  batchPushSupported = false;
   // Request-sync-first: resolver for the in-flight node-sync-response wait.
   syncResponseResolver = null;
+  // Pages walked in the current catch-up burst (see MAX_CATCH_UP_PAGES).
+  catchUpPages = 0;
   // Protocol-skew circuit breaker state. `structuralRejections` counts
   // consecutive structural node-errors (reset on forward progress); once it
   // trips, `outboundHalted` stops all pushes until the next reconnect.
@@ -1081,6 +1092,7 @@ var NodeStoreSyncProvider = class {
   async onConnected() {
     this.outboundHalted = false;
     this.structuralRejections = 0;
+    this.catchUpPages = 0;
     await this.ensureCursorLoaded();
     if (!this.connection || this.connection.status !== "connected") return;
     this.requestSync();
@@ -1090,6 +1102,7 @@ var NodeStoreSyncProvider = class {
   onDisconnected() {
     this.clearSendQueue();
     this.resolveSyncResponse();
+    this.batchPushSupported = false;
   }
   async ensureCursorLoaded() {
     if (this.cursorLoaded) return;
@@ -1148,6 +1161,11 @@ var NodeStoreSyncProvider = class {
     }
   }
   handleDirectMessage(message) {
+    if (message.type === "handshake") {
+      const features = message.features;
+      this.batchPushSupported = Array.isArray(features) && features.includes("batch-push");
+      return;
+    }
     if (message.type === "node-cleared") {
       if (message.room === this.room) {
         this.resolveClear(typeof message.cleared === "number" ? message.cleared : 0);
@@ -1285,7 +1303,8 @@ var NodeStoreSyncProvider = class {
       this.pushedThrough = response.highWaterMark;
       void this.syncLocalChanges();
     }
-    if (response.highWaterMark > this.lastSyncedLamport) {
+    const advanced = response.highWaterMark > this.lastSyncedLamport;
+    if (advanced) {
       this.lastSyncedLamport = response.highWaterMark;
       this.pushedThrough = Math.max(this.pushedThrough, this.lastSyncedLamport);
       this.structuralRejections = 0;
@@ -1295,6 +1314,17 @@ var NodeStoreSyncProvider = class {
         console.warn("[NodeStoreSync] failed to persist sync cursor:", err);
       }
     }
+    if (response.hasMore === true && advanced && this.catchUpPages < MAX_CATCH_UP_PAGES && this.connection?.status === "connected") {
+      this.catchUpPages += 1;
+      this.requestSync();
+      return;
+    }
+    if (response.hasMore === true && this.catchUpPages >= MAX_CATCH_UP_PAGES) {
+      console.warn(
+        `[NodeStoreSync] stopping catch-up for ${this.room} after ${MAX_CATCH_UP_PAGES} pages (cursor ${this.lastSyncedLamport}); the remainder resumes on the next sync.`
+      );
+    }
+    this.catchUpPages = 0;
     this.resolveSyncResponse();
   }
   // ─── Outbound (throttled) ────────────────────────────────────────────────
@@ -1344,16 +1374,40 @@ var NodeStoreSyncProvider = class {
     if (this.outboundHalted) return;
     if (!this.connection || this.connection.status !== "connected") return;
     this.sentInWindow = 0;
-    while (this.sendQueue.length > 0 && this.sentInWindow < MAX_SENDS_PER_WINDOW) {
-      const change = this.sendQueue.shift();
-      this.queuedHashes.delete(change.hash);
-      this.publishChange(change);
-      this.sentInWindow += 1;
+    if (this.batchPushSupported) {
+      this.drainBatched();
+    } else {
+      while (this.sendQueue.length > 0 && this.sentInWindow < MAX_SENDS_PER_WINDOW) {
+        const change = this.sendQueue.shift();
+        this.queuedHashes.delete(change.hash);
+        this.publishChange(change);
+        this.sentInWindow += 1;
+      }
     }
     if (this.sendQueue.length > 0) {
       this.scheduleDrain(SEND_WINDOW_MS);
     }
   }
+  /**
+   * Batched drain (exploration 0357): pack the queue into slabs of up to
+   * MAX_BATCH_CHANGES and send one frame per slab. `sentInWindow` counts
+   * CHANGES, not frames, matching how the hub charges its rate limit — so the
+   * budget stays a real bound on work rather than a bound on syscalls.
+   */
+  drainBatched() {
+    while (this.sendQueue.length > 0 && this.sentInWindow < MAX_BATCHED_CHANGES_PER_WINDOW) {
+      const queued = this.sendQueue.length;
+      const slabSize = Math.min(
+        MAX_BATCH_CHANGES,
+        queued,
+        MAX_BATCHED_CHANGES_PER_WINDOW - this.sentInWindow
+      );
+      const slab = this.sendQueue.splice(0, slabSize);
+      for (const change of slab) this.queuedHashes.delete(change.hash);
+      this.publishChangeBatch(slab);
+      this.sentInWindow += slab.length;
+    }
+  }
   publishChange(change) {
     if (!this.connection) return;
     this.connection.publish(this.room, {
@@ -1363,6 +1417,22 @@ var NodeStoreSyncProvider = class {
     });
     this.pushedThrough = Math.max(this.pushedThrough, change.lamport);
   }
+  /**
+   * Send many changes in one frame. The hub verifies and authorizes each one
+   * individually and re-broadcasts them as ordinary `node-change` messages, so
+   * this is purely a transport-level batch.
+   */
+  publishChangeBatch(changes) {
+    if (!this.connection || changes.length === 0) return;
+    this.connection.publish(this.room, {
+      type: "node-change-batch",
+      room: this.room,
+      changes: changes.map((change) => this.serializeChange(change))
+    });
+    for (const change of changes) {
+      this.pushedThrough = Math.max(this.pushedThrough, change.lamport);
+    }
+  }
   clearSendQueue() {
     if (this.sendTimer) {
       clearTimeout(this.sendTimer);
@@ -3320,6 +3390,54 @@ var WebSocketSyncProvider = class {
   };
 };
 
+// src/sync/replication-scope.ts
+function mayReceivePayload(trust, payload) {
+  if (payload === "ciphertext") return true;
+  return trust !== "zero-knowledge";
+}
+function spaceNamespace(ownerDID, spaceId) {
+  return `xnet://${ownerDID}/space/${spaceId}/`;
+}
+function systemNamespace(ownerDID) {
+  return `xnet://${ownerDID}/sys/`;
+}
+function namespaceForNode(node, fallbackOwnerDID) {
+  const owner = node.createdBy ?? fallbackOwnerDID ?? "unknown";
+  return node.space ? spaceNamespace(owner, node.space) : spaceNamespace(owner, node.id);
+}
+function replicationConfigFromPolicies(policies) {
+  const hubsById = /* @__PURE__ */ new Map();
+  const namespacePolicies = [];
+  for (const policy of policies) {
+    const includeHubIds = [];
+    let minReplicas = 0;
+    for (const destination of policy.destinations) {
+      if (!hubsById.has(destination.hubId)) {
+        hubsById.set(destination.hubId, {
+          id: destination.hubId,
+          url: destination.url,
+          ...destination.priority === void 0 ? {} : { priority: destination.priority }
+        });
+      }
+      includeHubIds.push(destination.hubId);
+      if (destination.minReplicas && destination.minReplicas > minReplicas) {
+        minReplicas = destination.minReplicas;
+      }
+    }
+    namespacePolicies.push({
+      namespace: spaceNamespace(policy.ownerDID, policy.space),
+      includeHubIds,
+      ...minReplicas > 0 ? { minHubs: minReplicas } : {}
+    });
+  }
+  return {
+    federation: {
+      hubs: [...hubsById.values()],
+      namespacePolicies
+    }
+  };
+}
+
 // src/sync/MultiHubSyncManager.ts
 import {
   planReplicationDestinations
@@ -3410,10 +3528,21 @@ function createMultiHubSyncManager(config) {
         }
       };
     },
-    publishScoped(namespace, room, data) {
+    publishScoped(namespace, room, data, opts) {
+      const payload = opts?.payload ?? "plaintext";
+      const published = [];
+      const withheld = [];
       for (const hubId of reachableHubIds(namespace)) {
-        hubs.get(hubId)?.transport.publish(room, data);
+        const hub = hubs.get(hubId);
+        if (!hub) continue;
+        if (!mayReceivePayload(hub.trust, payload)) {
+          withheld.push(hubId);
+          continue;
+        }
+        hub.transport.publish(room, data);
+        published.push(hubId);
       }
+      return { published, withheld };
     },
     setReplication(next) {
       replication = next;
@@ -3433,50 +3562,6 @@ function createMultiHubSyncManager(config) {
   };
 }
 
-// src/sync/replication-scope.ts
-function spaceNamespace(ownerDID, spaceId) {
-  return `xnet://${ownerDID}/space/${spaceId}/`;
-}
-function systemNamespace(ownerDID) {
-  return `xnet://${ownerDID}/sys/`;
-}
-function namespaceForNode(node, fallbackOwnerDID) {
-  const owner = node.createdBy ?? fallbackOwnerDID ?? "unknown";
-  return node.space ? spaceNamespace(owner, node.space) : spaceNamespace(owner, node.id);
-}
-function replicationConfigFromPolicies(policies) {
-  const hubsById = /* @__PURE__ */ new Map();
-  const namespacePolicies = [];
-  for (const policy of policies) {
-    const includeHubIds = [];
-    let minReplicas = 0;
-    for (const destination of policy.destinations) {
-      if (!hubsById.has(destination.hubId)) {
-        hubsById.set(destination.hubId, {
-          id: destination.hubId,
-          url: destination.url,
-          ...destination.priority === void 0 ? {} : { priority: destination.priority }
-        });
-      }
-      includeHubIds.push(destination.hubId);
-      if (destination.minReplicas && destination.minReplicas > minReplicas) {
-        minReplicas = destination.minReplicas;
-      }
-    }
-    namespacePolicies.push({
-      namespace: spaceNamespace(policy.ownerDID, policy.space),
-      includeHubIds,
-      ...minReplicas > 0 ? { minHubs: minReplicas } : {}
-    });
-  }
-  return {
-    federation: {
-      hubs: [...hubsById.values()],
-      namespacePolicies
-    }
-  };
-}
-
 // src/sync/InitialSyncManager.ts
 function createInitialSyncManager() {
   let progress = {
@@ -3618,6 +3703,7 @@ export {
   createXNetClient,
   isProtocolCompatible,
   liveQuery,
+  mayReceivePayload,
   namespaceForNode,
   negotiateProtocolVersion,
   replicationConfigFromPolicies,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/runtime",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Framework-agnostic xNet runtime: createXNetClient() and sync orchestration, usable from any framework, a CLI, a worker, or a Node service",
   "license": "MIT",
   "repository": {
@@ -12,8 +12,8 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "files": [
@@ -28,15 +28,15 @@
   "dependencies": {
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.24",
-    "@xnetjs/core": "2.4.0",
-    "@xnetjs/crypto": "2.4.0",
-    "@xnetjs/data": "2.4.0",
-    "@xnetjs/data-bridge": "2.4.0",
-    "@xnetjs/history": "2.4.0",
-    "@xnetjs/identity": "2.4.0",
-    "@xnetjs/plugins": "2.4.0",
-    "@xnetjs/storage": "2.4.0",
-    "@xnetjs/sync": "2.4.0"
+    "@xnetjs/core": "3.0.0",
+    "@xnetjs/crypto": "3.0.0",
+    "@xnetjs/data": "3.0.0",
+    "@xnetjs/data-bridge": "3.0.0",
+    "@xnetjs/history": "3.0.0",
+    "@xnetjs/identity": "3.0.0",
+    "@xnetjs/plugins": "3.0.0",
+    "@xnetjs/storage": "3.0.0",
+    "@xnetjs/sync": "3.0.0"
   },
   "devDependencies": {
     "jsdom": "^26.0.0",