@xnetjs/runtime 0.0.2 → 0.1.0

package/README.md

@@ -46,4 +46,87 @@ const decision = await client.auth.can({ action: 'write', nodeId: '…' })
 await client.destroy()
 ```
 
-See `docs/explorations/0185_*` for the design rationale.
+## Use xNet from any framework
+
+`client.query(schema, options)` returns the universal
+`{ getSnapshot, subscribe }` contract — the exact pair React's
+`useSyncExternalStore`, Vue's `shallowRef`, a Svelte store, a Solid signal, and
+Angular's `toSignal` all bind to. `liveQuery()` already adapts it into the
+**Svelte store contract**, so a binding for any framework is ~15–40 lines:
+
+```ts
+// Vue
+import { shallowRef, onScopeDispose } from 'vue'
+import { liveQuery } from '@xnetjs/runtime'
+
+export function useQuery(client, schema, options) {
+  const lq = liveQuery(client, schema, options)
+  const data = shallowRef(lq.get())
+  const stop = lq.subscribe((v) => (data.value = v))
+  onScopeDispose(() => {
+    stop()
+    lq.destroy()
+  })
+  return data // Ref<NodeState[] | null>
+}
+```
+
+```svelte
+<!-- Svelte: liveQuery IS a store, so $-auto-subscription just works -->
+<script>
+  import { liveQuery } from '@xnetjs/runtime'
+  const tasks = liveQuery(client, TaskSchema, { where: { status: 'todo' } })
+</script>
+{#each $tasks ?? [] as task}<li>{task.properties.title}</li>{/each}
+```
+
+```ts
+// Vanilla — no framework, no adapter package
+const tasks = liveQuery(client, TaskSchema)
+const stop = tasks.subscribe((rows) => render(rows ?? []))
+await client.mutate.create(TaskSchema, { title: 'Ship it' }) // re-renders
+// later: stop(); tasks.destroy(); await client.destroy()
+```
+
+### Validate a binding with `runAdapterConformance`
+
+Behaviour is tested **once**, framework-agnostically. Any adapter — or your own
+app — can run the same contract against its client factory:
+
+```ts
+import { runAdapterConformance } from '@xnetjs/runtime'
+import { MemoryNodeStorageAdapter } from '@xnetjs/data'
+
+// Throws on the first failed check; resolves with the result otherwise.
+await runAdapterConformance((overrides) =>
+  createXNetClient({
+    nodeStorage: new MemoryNodeStorageAdapter(),
+    authorDID,
+    signingKey,
+    ...overrides
+  })
+)
+```
+
+It asserts the reactive data contract: an immediate live-query snapshot then
+updates on `mutate`, no delivery after unsubscribe, one-shot `fetch` round-trips,
+the authorization surface is reachable and **denial surfaces**, and `destroy()`
+is idempotent.
+
+## Support tiers (what "supported" means)
+
+Per [exploration 0237](../../docs/explorations), framework support is layered —
+binding the data layer is cheap; carrying a full per-framework component
+ecosystem is not. The committed levels:
+
+| Tier       | Surface                                              | Scope                                                                  |
+| ---------- | ---------------------------------------------------- | ---------------------------------------------------------------------- |
+| **Tier 0** | `@xnetjs/runtime` — `createXNetClient` + `liveQuery` | **every** framework, headless; conformance-gated. This page.           |
+| **Tier 1** | `@xnetjs/react` — hooks **and** components           | first-class; the app dogfoods it.                                      |
+| **Tier 2** | thin Vue / Svelte data-binding adapters              | `useQuery`/`useMutate` only — **no components** — published on demand. |
+| **—**      | components in non-React frameworks                   | **not offered** (`@xnetjs/ui` is React-only by design).                |
+
+All UI components are React. Other frameworks consume the headless runtime.
+
+See `docs/explorations/0185_*` (runtime extraction) and
+`docs/explorations/0237_*` (support-tier policy) for the design rationale.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as Y from 'yjs';
 import { ContentId, DID, PolicyEvaluator, AuthCheckInput, AuthDecision } from '@xnetjs/core';
 import { NodeStore, NodeStorageAdapter, NodeContentCipher, StoreAuthAPI, SchemaLookup, LensRegistry, PropertyBuilder, DefinedSchema, NodeState, TransactionOperation, NodeChange, NodePayload } from '@xnetjs/data';
-import { SyncLifecycleState, SyncReplicationConfig, ChangeSigner } from '@xnetjs/sync';
+import { SyncLifecycleState, SyncReplicationConfig, ChangeSigner, ReplicationPlan } from '@xnetjs/sync';
 export { SyncLifecyclePhase, SyncLifecycleState } from '@xnetjs/sync';
 import { Awareness } from 'y-protocols/awareness';
 import { DataBridge, MainThreadBridgeOptions, SyncStatus as SyncStatus$1, QueryOptions, BridgeTransactionResult, AcquiredDoc } from '@xnetjs/data-bridge';
@@ -476,6 +476,77 @@ interface LiveQuery {
  */
 declare function liveQuery<P extends Record<string, PropertyBuilder>>(client: XNetClient, schema: DefinedSchema<P>, options?: QueryOptions<P>): LiveQuery;
 
+/**
+ * runAdapterConformance — the executable "use xNet from any framework" contract.
+ *
+ * Exploration 0237 argues that the costly part of multi-framework support is not
+ * *writing* a Vue/Svelte/Solid binding (each is ~40 lines over {@link liveQuery})
+ * but *validating* that every binding behaves identically forever. The answer is
+ * to test the behaviour **once**, framework-agnostically, and have each adapter
+ * run only a tiny render-harness check on top.
+ *
+ * This is that once. Given a `makeClient` factory, it asserts the reactive data
+ * contract every adapter depends on:
+ *
+ *   1. live query delivers an immediate snapshot, then updates on `mutate`
+ *   2. unsubscribing stops delivery
+ *   3. one-shot `fetch` round-trips a write
+ *   4. the authorization surface is reachable and **denial surfaces**
+ *   5. `destroy()` is idempotent
+ *
+ * It imports no test framework and no UI framework, so it runs in vitest, a
+ * browser test runner, or a plain Node script. It **throws** on the first failed
+ * check (with the full check list attached) and otherwise resolves with the
+ * result — so `await runAdapterConformance(makeClient)` *is* the assertion.
+ */
+
+/**
+ * Factory for the client under test. Accepts the same overrides
+ * {@link CreateXNetClientOptions} so the suite can, for example, inject a
+ * deny-writes evaluator for the authorization check. Adapter authors typically
+ * pass a one-liner that spreads `overrides` into `createXNetClient`.
+ */
+type ConformanceClientFactory = (overrides?: Partial<CreateXNetClientOptions>) => Promise<XNetClient>;
+/** Outcome of a single contract check. */
+interface AdapterConformanceCheck {
+    name: string;
+    passed: boolean;
+    detail?: string;
+}
+/** Aggregate result of a conformance run. */
+interface AdapterConformanceResult {
+    passed: boolean;
+    checks: AdapterConformanceCheck[];
+}
+/** Thrown when one or more checks fail; carries the full check list. */
+declare class AdapterConformanceError extends Error {
+    readonly checks: AdapterConformanceCheck[];
+    constructor(checks: AdapterConformanceCheck[]);
+}
+/**
+ * Run the full adapter-conformance suite against a client factory.
+ *
+ * Resolves with the {@link AdapterConformanceResult} when every check passes,
+ * and throws {@link AdapterConformanceError} (with the full check list) on the
+ * first failure — so the call itself is the assertion.
+ *
+ * @example
+ * ```ts
+ * import { runAdapterConformance } from '@xnetjs/runtime'
+ * import { MemoryNodeStorageAdapter } from '@xnetjs/data'
+ *
+ * await runAdapterConformance((overrides) =>
+ *   createXNetClient({
+ *     nodeStorage: new MemoryNodeStorageAdapter(),
+ *     authorDID,
+ *     signingKey,
+ *     ...overrides
+ *   })
+ * )
+ * ```
+ */
+declare function runAdapterConformance(makeClient: ConformanceClientFactory): Promise<AdapterConformanceResult>;
+
 /**
  * WebSocketSyncProvider - Syncs Y.Doc via WebSocket relay
  *
@@ -640,6 +711,21 @@ interface NodePoolConfig {
     onDocUpdate?: (nodeId: string, doc: Y.Doc) => void;
     /** Optional callback before a doc is evicted */
     onDocEvict?: (nodeId: string, doc: Y.Doc) => void;
+    /**
+     * Predicate marking a node's Y.Doc as **ephemeral** — never persisted to
+     * `yjs_state` and never cold-loaded from it. Workspace presence is the
+     * canonical case: it is republished continuously and has no value across
+     * reloads, yet (as a `gc:false` doc, written on every awareness tick) its
+     * persisted blob grows unboundedly and its cold read at boot head-of-line
+     * blocked every landing query on the single SQLite worker (exploration 0227).
+     * Defaults to the `presence-` id prefix.
+     */
+    isEphemeral?: (nodeId: string) => boolean;
+    /**
+     * Warn (once per load) when a `yjs_state` blob read or persisted exceeds this
+     * many bytes — a tripwire for unbounded `gc:false` growth. Default 5 MiB.
+     */
+    largeDocWarnBytes?: number;
 }
 interface NodePool {
     /** Acquire a Y.Doc for a Node (load from storage or create new) */
@@ -659,6 +745,193 @@ interface NodePool {
 }
 declare function createNodePool(config: NodePoolConfig): NodePool;
 
+/**
+ * Replication scope — the Space→namespace shim that lets the (already built)
+ * `planReplicationDestinations` router key on something the runtime actually
+ * addresses (exploration 0258).
+ *
+ * The routing planner in `@xnetjs/sync` speaks in *namespaces* (strings like
+ * `xnet://<did>/space/<id>/`), but the runtime addresses per-node rooms
+ * (`xnet-doc-<nodeId>`). Nothing mapped one to the other, so the planner sat
+ * exported-but-unconsumed. A **Space** is the natural bridge: it is already the
+ * security boundary, every content node carries a single `space` relation, and
+ * a human reasons about "where does *this Space* live?". So the Space is the
+ * unit of replication, and its namespace is the routing key.
+ *
+ * This module also carries the "manifest as data" bridge:
+ * `replicationConfigFromPolicies` turns a set of per-Space replication policies
+ * (which can themselves be synced nodes) into the `SyncReplicationConfig` the
+ * planner consumes — so *editing where a Space lives* is ordinary data, not
+ * device-local config.
+ */
+
+/**
+ * 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.
+ */
+type ReplicaTrust = 'trusted' | 'zero-knowledge';
+/** The namespace for a Space's content — the routing key for the planner. */
+declare function spaceNamespace(ownerDID: string, spaceId: string): string;
+/**
+ * The namespace for a user's system data (schemas, authz, the manifest itself).
+ * Classified `system` by the planner (the `sys/` segment), so it can route to
+ * `defaultSystemHubIds` and be replicated everywhere for bootstrap.
+ */
+declare function systemNamespace(ownerDID: string): string;
+/** Minimal node shape the scope mapping needs. */
+interface ReplicationScopeNode {
+    id: string;
+    /** The Space this node's security lives in, if any. */
+    space?: string | null;
+    /** Author DID; scopes the namespace when no explicit owner is given. */
+    createdBy?: string | null;
+}
+/**
+ * The replication namespace for a node: its Space's namespace when it has one,
+ * otherwise a self-scoped namespace under its owner (so an unfiled node still
+ * has a stable, owner-scoped routing key).
+ */
+declare function namespaceForNode(node: ReplicationScopeNode, fallbackOwnerDID?: string): string;
+/** One destination in a Space's replication manifest. */
+interface ReplicationDestinationSpec {
+    /** Stable hub id used by routing policies. */
+    hubId: string;
+    /** WebSocket URL for the hub. */
+    url: string;
+    /** Lower is preferred when a `maxHubs` cap prunes a plan. */
+    priority?: number;
+    /**
+     * Trust class of this destination. Reserved for the plaintext vs
+     * zero-knowledge replication gate (0258); recorded on the manifest but not
+     * yet enforced.
+     */
+    trust?: ReplicaTrust;
+    /** Minimum replica count this Space wants (feeds the planner's `minHubs`). */
+    minReplicas?: number;
+}
+/**
+ * A per-Space replication policy — the "manifest of what goes where" as data.
+ * A group of these can be persisted as synced nodes; this module turns them
+ * into the config the planner consumes.
+ */
+interface SpaceReplicationPolicy {
+    /** The Space id (the replication scope). */
+    space: string;
+    /** Owner DID that scopes the Space's namespace. */
+    ownerDID: string;
+    /** Where this Space replicates. */
+    destinations: readonly ReplicationDestinationSpec[];
+}
+/**
+ * Build a `SyncReplicationConfig` from a set of per-Space replication policies.
+ *
+ * Each policy contributes:
+ *  - its destinations to a shared hub inventory (deduped by `hubId`), and
+ *  - a namespace policy for `spaceNamespace(ownerDID, space)` that includes
+ *    exactly those hubs, with `minHubs` set to the largest `minReplicas` any of
+ *    its destinations asks for.
+ *
+ * The result is a *pure function of the manifest*: change a policy and the plan
+ * changes deterministically, which is what makes "manifest as data" work.
+ */
+declare function replicationConfigFromPolicies(policies: readonly SpaceReplicationPolicy[]): SyncReplicationConfig;
+
+/**
+ * MultiHubSyncManager — the selective-routing brain for multi-home sync
+ * (exploration 0258).
+ *
+ * The pieces for multiplayer already existed but weren't joined up:
+ *  - `@xnetjs/sync`'s `planReplicationDestinations` decides *which hubs* a
+ *    namespace should replicate to — but nothing called it.
+ *  - `createMultiHubConnectionManager` already fans a *multiplexed* connection
+ *    (O(1) sockets per hub, not per doc) out to N hubs — but it publishes to
+ *    *every* hub unconditionally, with no per-scope selection.
+ *
+ * This manager sits between them: given a namespace (a Space's, via
+ * `replication-scope`), it consults the planner and joins/publishes a room on
+ * *only the hubs the policy selects*. With no policy it defaults to a full
+ * mirror (every configured hub), which is the safe local-first default —
+ * "back up everything to all your hubs" — and selective routing kicks in the
+ * moment a namespace policy is present.
+ *
+ * Because it routes over the existing multiplexed transports rather than
+ * opening a socket per (doc × hub), it does not reintroduce the connection
+ * explosion the exploration warned about.
+ *
+ * The transports are injected (any object with join/publish/connect), so the
+ * routing logic is unit-testable without real WebSockets, and the real caller
+ * passes `createConnectionManager(...)` per hub.
+ */
+
+/** The slice of a hub connection this manager drives (a `ConnectionManager` fits). */
+interface HubTransport {
+    connect(): void;
+    disconnect(): void;
+    /** Subscribe to a room; returns an unsubscribe function. */
+    joinRoom(room: string, handler: (data: Record<string, unknown>) => void): () => void;
+    /** Publish a message to a room. */
+    publish(room: string, data: object): void;
+}
+/** One hub the manager can route to. */
+interface HubConnection {
+    /** Stable hub id referenced by routing policies. */
+    hubId: string;
+    /** WebSocket URL (also used to overlay any policy hub entry by id). */
+    url: string;
+    /** 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?: ReplicaTrust;
+}
+interface MultiHubSyncManagerConfig {
+    /** One multiplexed connection per hub. */
+    hubs: readonly HubConnection[];
+    /** Routing policy — the `federation` half is finally consulted here. */
+    replication?: SyncReplicationConfig;
+    /** Map a node id to its wire room. Default: `xnet-doc-<nodeId>`. */
+    roomForNode?: (nodeId: string) => string;
+}
+/** A planned destination that the manager actually has a transport for. */
+interface PlannedHub {
+    hubId: string;
+    url: string;
+    trust: ReplicaTrust | undefined;
+}
+/** Handle for a room joined on the policy-selected hubs. */
+interface ScopedRoomHandle {
+    /** The plan that selected these hubs (carries diagnostics + trace). */
+    readonly plan: ReplicationPlan;
+    /** Hub ids this room is currently subscribed on. */
+    readonly hubIds: readonly string[];
+    /** Leave the room on every hub it was joined on. */
+    leave(): void;
+}
+interface MultiHubSyncManager {
+    /** The routing plan for a namespace (all destinations, incl. unknown hubs). */
+    planFor(namespace: string): ReplicationPlan;
+    /** Planned destinations the manager has a transport for. */
+    plannedHubs(namespace: string): PlannedHub[];
+    /** Hub ids a namespace routes to (and that we can reach). */
+    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;
+    /** Replace the routing policy; live rooms re-route to match (manifest-as-data). */
+    setReplication(replication: SyncReplicationConfig | undefined): void;
+    /** Connect every hub transport. */
+    connect(): void;
+    /** Leave every room and disconnect every hub transport. */
+    disconnect(): void;
+}
+declare function createMultiHubSyncManager(config: MultiHubSyncManagerConfig): MultiHubSyncManager;
+
 /**
  * NodeStoreSyncProvider - Sync NodeChange events via hub ConnectionManager.
  *
@@ -1017,4 +1290,4 @@ declare function negotiateProtocolVersion(ours: readonly string[], theirs: reado
  */
 declare function isProtocolCompatible(theirs: readonly string[]): boolean;
 
-export { type BlobStoreForSync, type ConnectionManager, type ConnectionManagerConfig, type ConnectionStatus, type CreateXNetClientOptions, type InitialSyncManager, type InitialSyncMessage, type LiveQuery, type LiveQueryValue, METABRIDGE_ORIGIN, METABRIDGE_SEED_ORIGIN, type MetaBridge, type MultiHubConnectionManagerConfig, type NodePool, type NodePoolConfig, NodeStoreSyncProvider, type NodeSyncResponse, type OfflineQueue, type OfflineQueueConfig, type PoolEntryState, type ProgressListener, type QueueEntry, type Registry, type RegistryConfig, type RegistryStorage, type SerializedNodeChange, 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, createConnectionManager, createInitialSyncManager, createMetaBridge, createMultiHubConnectionManager, createNodePool, createOfflineQueue, createRegistry, createSyncManager, createXNetClient, isProtocolCompatible, liveQuery, negotiateProtocolVersion };
+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 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, createConnectionManager, createInitialSyncManager, createMetaBridge, createMultiHubConnectionManager, createMultiHubSyncManager, createNodePool, createOfflineQueue, createRegistry, createSyncManager, createXNetClient, isProtocolCompatible, liveQuery, namespaceForNode, negotiateProtocolVersion, replicationConfigFromPolicies, runAdapterConformance, spaceNamespace, systemNamespace };

package/dist/index.js

@@ -697,20 +697,62 @@ function createMetaBridge(store, options) {
 
 // src/sync/node-pool.ts
 import * as Y from "yjs";
+var DEFAULT_LARGE_DOC_WARN_BYTES = 5 * 1024 * 1024;
+function defaultIsEphemeral(nodeId) {
+  return nodeId.startsWith("presence-");
+}
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function bootDebugEnabled() {
+  try {
+    return typeof localStorage !== "undefined" && localStorage.getItem("xnet:boot:debug") === "true";
+  } catch {
+    return false;
+  }
+}
 function createNodePool(config) {
   const entries = /* @__PURE__ */ new Map();
   const persistTimers = /* @__PURE__ */ new Map();
   const maxWarm = config.maxWarm ?? 50;
   const persistDelay = config.persistDelay ?? 2e3;
+  const isEphemeral = config.isEphemeral ?? defaultIsEphemeral;
+  const largeDocWarnBytes = config.largeDocWarnBytes ?? DEFAULT_LARGE_DOC_WARN_BYTES;
+  let firstAcquireMarked = false;
+  function markFirstAcquire() {
+    if (firstAcquireMarked) return;
+    firstAcquireMarked = true;
+    try {
+      performance?.mark?.("xnet:docpool:first-acquire");
+    } catch {
+    }
+  }
   async function loadDoc(nodeId) {
     const doc = new Y.Doc({ guid: nodeId, gc: false });
+    if (isEphemeral(nodeId)) return doc;
+    const t0 = nowMs();
     const content = await config.storage.getDocumentContent(nodeId);
+    const tRead = nowMs();
     if (content && content.length > 0) {
       Y.applyUpdate(doc, content);
+      const tApply = nowMs();
+      if (content.length >= largeDocWarnBytes) {
+        console.warn(
+          `[NodePool] large yjs_state blob for ${nodeId}: ${content.length} bytes \u2014 consider compacting (gc:false retains tombstones)`
+        );
+      }
+      if (bootDebugEnabled()) {
+        console.info("[xNet] loadDoc", nodeId, {
+          bytes: content.length,
+          readMs: Math.round(tRead - t0),
+          applyMs: Math.round(tApply - tRead)
+        });
+      }
     }
     return doc;
   }
   function schedulePersist(nodeId) {
+    if (isEphemeral(nodeId)) return;
     const existing = persistTimers.get(nodeId);
     if (existing) clearTimeout(existing);
     persistTimers.set(
@@ -741,8 +783,15 @@ function createNodePool(config) {
     await Promise.all(
       toEvict.map(async ([id, entry]) => {
         try {
-          const content = Y.encodeStateAsUpdate(entry.doc);
-          await config.storage.setDocumentContent(id, content);
+          if (!isEphemeral(id)) {
+            const content = Y.encodeStateAsUpdate(entry.doc);
+            if (content.length >= largeDocWarnBytes) {
+              console.warn(
+                `[NodePool] large yjs_state blob for ${id}: ${content.length} bytes \u2014 consider compacting (gc:false retains tombstones)`
+              );
+            }
+            await config.storage.setDocumentContent(id, content);
+          }
         } catch (err) {
           console.error(`[NodePool] Failed to persist document ${id} during eviction:`, err);
         }
@@ -762,9 +811,11 @@ function createNodePool(config) {
         entry.refCount++;
         entry.state = "active";
         entry.lastAccess = Date.now();
+        markFirstAcquire();
         return entry.doc;
       }
       const doc = await loadDoc(nodeId);
+      markFirstAcquire();
       doc.on("update", () => {
         const e = entries.get(nodeId);
         if (e) {
@@ -811,7 +862,7 @@ function createNodePool(config) {
       persistTimers.clear();
       const promises = [];
       for (const [id, entry] of entries) {
-        if (entry.dirty) {
+        if (entry.dirty && !isEphemeral(id)) {
           const content = Y.encodeStateAsUpdate(entry.doc);
           promises.push(
             config.storage.setDocumentContent(id, content).then(() => {
@@ -841,6 +892,15 @@ var SEND_WINDOW_MS = 1e3;
 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 OUTBOUND_ENQUEUE_BATCH = 1024;
+var HEAVY_RESYNC_CHANGES = 5e3;
+var HEAVY_RESYNC_MS = 250;
+function nowMs2() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function yieldToEventLoop() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
 var NodeStoreSyncProvider = class {
   constructor(store, room) {
     this.store = store;
@@ -1119,6 +1179,13 @@ var NodeStoreSyncProvider = class {
         await this.store.applyRemoteChanges(knownChanges);
       }
     }
+    if (response.highWaterMark > 0 && !this.outboundHalted && response.highWaterMark < this.lastSyncedLamport && this.pushedThrough > response.highWaterMark) {
+      console.warn(
+        `[NodeStoreSync] hub high-water mark ${response.highWaterMark} is below the confirmed cursor ${this.lastSyncedLamport} (hub rollback?); re-offering local changes`
+      );
+      this.pushedThrough = response.highWaterMark;
+      void this.syncLocalChanges();
+    }
     if (response.highWaterMark > this.lastSyncedLamport) {
       this.lastSyncedLamport = response.highWaterMark;
       this.pushedThrough = Math.max(this.pushedThrough, this.lastSyncedLamport);
@@ -1136,11 +1203,25 @@ var NodeStoreSyncProvider = class {
   async syncLocalChanges() {
     if (this.outboundHalted) return;
     if (!this.connection || this.connection.status !== "connected") return;
+    const t0 = nowMs2();
     const changes = await this.store.getChangesSince(this.pushedThrough);
     if (changes.length === 0) return;
-    changes.sort((a, b) => a.lamport - b.lamport || a.authorDID.localeCompare(b.authorDID));
-    for (const change of changes) {
-      this.enqueueChange(change);
+    const fetchMs = nowMs2() - t0;
+    changes.sort(
+      (a, b) => a.lamport - b.lamport || (a.authorDID < b.authorDID ? -1 : a.authorDID > b.authorDID ? 1 : 0)
+    );
+    const sortMs = nowMs2() - t0 - fetchMs;
+    for (let i = 0; i < changes.length; i++) {
+      this.enqueueChange(changes[i]);
+      if ((i + 1) % OUTBOUND_ENQUEUE_BATCH === 0 && i + 1 < changes.length) {
+        if (this.outboundHalted || this.connection?.status !== "connected") return;
+        await yieldToEventLoop();
+      }
+    }
+    if (changes.length >= HEAVY_RESYNC_CHANGES || fetchMs + sortMs >= HEAVY_RESYNC_MS) {
+      console.warn(
+        `[NodeStoreSync] heavy outbound resync: ${changes.length} changes, fetch+deserialize ${Math.round(fetchMs)}ms, sort ${Math.round(sortMs)}ms (cursor ${this.pushedThrough})`
+      );
     }
   }
   /** Queue a change for throttled broadcast (deduped by hash). */
@@ -1477,18 +1558,24 @@ function createRegistryStorageAdapter(storage) {
   return {
     async get(key) {
       try {
+        if (storage.getAppState) {
+          const json = await storage.getAppState(key);
+          return json ? JSON.parse(json) : null;
+        }
         const content = await storage.getDocumentContent(key);
         if (!content || content.length === 0) return null;
-        const json = decoder.decode(content);
-        return JSON.parse(json);
+        return JSON.parse(decoder.decode(content));
       } catch {
         return null;
       }
     },
     async set(key, entries) {
       const json = JSON.stringify(entries);
-      const bytes = encoder.encode(json);
-      await storage.setDocumentContent(key, bytes);
+      if (storage.setAppState) {
+        await storage.setAppState(key, json);
+        return;
+      }
+      await storage.setDocumentContent(key, encoder.encode(json));
     }
   };
 }
@@ -1669,6 +1756,7 @@ function createSyncManager(config) {
   const offlineQueue = createOfflineQueue({
     storage: config.storage
   });
+  let offlineQueueReady = Promise.resolve();
   const nodeSyncProvider = config.nodeSyncRoom ? new NodeStoreSyncProvider(config.nodeStore, config.nodeSyncRoom) : null;
   let blobSync = null;
   if (config.blobStore) {
@@ -2128,9 +2216,16 @@ function createSyncManager(config) {
       if (lifecycleInput.stopped) return;
       log2("Registry loaded, tracked nodes:", registry.getTracked().length);
       attachPersistenceListeners();
-      await offlineQueue.load();
-      log2("Offline queue loaded, size:", offlineQueue.size);
-      updateLifecycle({ localReady: true });
+      offlineQueueReady = offlineQueue.load().then(() => {
+        log2("Offline queue loaded, size:", offlineQueue.size);
+        updateLifecycle({ localReady: true });
+        if (connection.status === "connected") {
+          void drainOfflineQueue();
+        }
+      }).catch((err) => {
+        log2("Offline queue load failed:", err);
+        updateLifecycle({ localReady: true });
+      });
       log2("Connecting to signaling server...");
       connection.connect();
       nodeSyncProvider?.attach(connection);
@@ -2163,6 +2258,7 @@ function createSyncManager(config) {
       await pool.flushAll();
       registry.prune();
       await registry.save();
+      await offlineQueueReady.catch(() => void 0);
       await offlineQueue.save();
       await pool.destroy();
     },
@@ -2541,6 +2637,158 @@ function liveQuery(client, schema, options) {
   };
 }
 
+// src/adapter-conformance.ts
+import { defineSchema, text } from "@xnetjs/data";
+var ConformanceSchema = defineSchema({
+  name: "ConformanceItem",
+  namespace: "xnet://adapter-conformance/",
+  properties: { label: text({ required: true }) }
+});
+var AdapterConformanceError = class extends Error {
+  checks;
+  constructor(checks) {
+    const failed = checks.filter((c) => !c.passed).map((c) => `${c.name}: ${c.detail ?? "failed"}`);
+    super(`adapter conformance failed:
+  ${failed.join("\n  ")}`);
+    this.name = "AdapterConformanceError";
+    this.checks = checks;
+  }
+};
+var tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+function denyWrites() {
+  const decide = async (input) => ({
+    allowed: input.action === "read",
+    action: input.action,
+    subject: input.subject,
+    resource: input.nodeId,
+    roles: [],
+    grants: [],
+    reasons: [],
+    cached: false,
+    evaluatedAt: 0,
+    duration: 0
+  });
+  return {
+    can: decide,
+    explain: async () => {
+      throw new Error("conformance: explain() is not exercised");
+    },
+    invalidate: () => {
+    },
+    invalidateSubject: () => {
+    }
+  };
+}
+async function withClient(makeClient, overrides, body) {
+  const client = await makeClient(overrides);
+  try {
+    await body(client);
+  } finally {
+    await client.destroy();
+  }
+}
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+var CHECKS = [
+  {
+    name: "live-query:immediate-and-update",
+    run: (makeClient) => withClient(makeClient, void 0, async (client) => {
+      const items = liveQuery(client, ConformanceSchema);
+      const seen = [];
+      const unsubscribe = items.subscribe((rows) => seen.push(rows === null ? null : rows.length));
+      assert(seen.length >= 1, "subscribe did not deliver an immediate snapshot");
+      await client.mutate.create(ConformanceSchema, { label: "alpha" });
+      await tick();
+      assert(seen.at(-1) === 1, `expected 1 row after create, saw ${String(seen.at(-1))}`);
+      assert(items.get()?.length === 1, "get() did not reflect the write");
+      unsubscribe();
+      items.destroy();
+    })
+  },
+  {
+    name: "live-query:stops-after-unsubscribe",
+    run: (makeClient) => withClient(makeClient, void 0, async (client) => {
+      const items = liveQuery(client, ConformanceSchema);
+      let calls = 0;
+      const unsubscribe = items.subscribe(() => {
+        calls += 1;
+      });
+      const afterSubscribe = calls;
+      unsubscribe();
+      await client.mutate.create(ConformanceSchema, { label: "ignored" });
+      await tick();
+      assert(calls === afterSubscribe, "subscriber was notified after unsubscribe");
+      items.destroy();
+    })
+  },
+  {
+    name: "mutate:round-trips-via-fetch",
+    run: (makeClient) => withClient(makeClient, void 0, async (client) => {
+      await client.mutate.create(ConformanceSchema, { label: "beta" });
+      const rows = await client.fetch(ConformanceSchema);
+      assert(rows.length === 1, `expected 1 fetched row, saw ${rows.length}`);
+      assert(rows[0].properties.label === "beta", "fetched row lost its properties");
+    })
+  },
+  {
+    name: "auth:permissive-by-default",
+    run: (makeClient) => withClient(makeClient, void 0, async (client) => {
+      const decision = await client.can({
+        subject: client.authorDID,
+        action: "write",
+        nodeId: "conformance-node"
+      });
+      assert(typeof decision.allowed === "boolean", "can() did not return an AuthDecision");
+      assert(decision.allowed === true, "default client was not permissive");
+    })
+  },
+  {
+    name: "auth:denial-surfaces",
+    run: (makeClient) => withClient(makeClient, { authEvaluator: denyWrites() }, async (client) => {
+      const write = await client.can({
+        subject: client.authorDID,
+        action: "write",
+        nodeId: "conformance-node"
+      });
+      const read = await client.can({
+        subject: client.authorDID,
+        action: "read",
+        nodeId: "conformance-node"
+      });
+      assert(write.allowed === false, "denied write was reported as allowed");
+      assert(read.allowed === true, "allowed read was reported as denied");
+    })
+  },
+  {
+    name: "lifecycle:destroy-is-idempotent",
+    run: async (makeClient) => {
+      const client = await makeClient();
+      await client.destroy();
+      await client.destroy();
+      assert(client.runtimeStatus.phase === "destroyed", "phase was not destroyed after destroy()");
+    }
+  }
+];
+async function runAdapterConformance(makeClient) {
+  const checks = [];
+  for (const check of CHECKS) {
+    try {
+      await check.run(makeClient);
+      checks.push({ name: check.name, passed: true });
+    } catch (error) {
+      checks.push({
+        name: check.name,
+        passed: false,
+        detail: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  const passed = checks.every((c) => c.passed);
+  if (!passed) throw new AdapterConformanceError(checks);
+  return { passed, checks };
+}
+
 // src/sync/WebSocketSyncProvider.ts
 import { resolveSyncReplicationPolicy as resolveSyncReplicationPolicy2, signYjsUpdate as signYjsUpdate2, verifyYjsEnvelopeV1 as verifyYjsEnvelopeV12 } from "@xnetjs/sync";
 import {
@@ -2919,6 +3167,163 @@ var WebSocketSyncProvider = class {
   };
 };
 
+// src/sync/MultiHubSyncManager.ts
+import {
+  planReplicationDestinations
+} from "@xnetjs/sync";
+var defaultRoomForNode = (nodeId) => `xnet-doc-${nodeId}`;
+function createMultiHubSyncManager(config) {
+  const hubs = /* @__PURE__ */ new Map();
+  for (const hub of config.hubs) {
+    if (hub.hubId && !hubs.has(hub.hubId)) hubs.set(hub.hubId, hub);
+  }
+  const roomForNode = config.roomForNode ?? defaultRoomForNode;
+  const activeRooms = /* @__PURE__ */ new Set();
+  let replication = config.replication;
+  function effectiveConfig() {
+    const overlays = new Map(
+      (replication?.federation?.hubs ?? []).map((hub) => [hub.id, hub])
+    );
+    const mergedHubs = [...hubs.values()].map((hub) => {
+      const overlay = overlays.get(hub.hubId);
+      return { id: hub.hubId, url: hub.url, ...overlay ?? {} };
+    });
+    for (const [id, overlay] of overlays) {
+      if (!hubs.has(id)) mergedHubs.push(overlay);
+    }
+    return {
+      ...replication?.compatibility ? { compatibility: replication.compatibility } : {},
+      federation: {
+        hubs: mergedHubs,
+        ...replication?.federation?.namespacePolicies ? { namespacePolicies: replication.federation.namespacePolicies } : {},
+        ...replication?.federation?.defaultSystemHubIds ? { defaultSystemHubIds: replication.federation.defaultSystemHubIds } : {},
+        ...replication?.federation?.defaultUserHubIds ? { defaultUserHubIds: replication.federation.defaultUserHubIds } : {}
+      }
+    };
+  }
+  function planFor(namespace) {
+    return planReplicationDestinations({ namespace, config: effectiveConfig() });
+  }
+  function reachableHubIds(namespace) {
+    return planFor(namespace).destinations.map((destination) => destination.hubId).filter((hubId) => hubs.has(hubId));
+  }
+  function reconcileRoom(room) {
+    const wanted = new Set(reachableHubIds(room.namespace));
+    for (const [hubId, unsubscribe] of room.subscriptions) {
+      if (!wanted.has(hubId)) {
+        unsubscribe();
+        room.subscriptions.delete(hubId);
+      }
+    }
+    for (const hubId of wanted) {
+      if (!room.subscriptions.has(hubId)) {
+        const hub = hubs.get(hubId);
+        if (hub) room.subscriptions.set(hubId, hub.transport.joinRoom(room.room, room.handler));
+      }
+    }
+  }
+  return {
+    planFor,
+    plannedHubs(namespace) {
+      return planFor(namespace).destinations.flatMap((destination) => {
+        const hub = hubs.get(destination.hubId);
+        return hub ? [{ hubId: hub.hubId, url: hub.url, trust: hub.trust }] : [];
+      });
+    },
+    destinationsFor: reachableHubIds,
+    joinScopedRoom(nodeId, namespace, handler) {
+      const room = roomForNode(nodeId);
+      const active = {
+        nodeId,
+        namespace,
+        room,
+        handler,
+        subscriptions: /* @__PURE__ */ new Map()
+      };
+      for (const hubId of reachableHubIds(namespace)) {
+        const hub = hubs.get(hubId);
+        if (hub) active.subscriptions.set(hubId, hub.transport.joinRoom(room, handler));
+      }
+      activeRooms.add(active);
+      return {
+        plan: planFor(namespace),
+        get hubIds() {
+          return [...active.subscriptions.keys()];
+        },
+        leave() {
+          for (const unsubscribe of active.subscriptions.values()) unsubscribe();
+          active.subscriptions.clear();
+          activeRooms.delete(active);
+        }
+      };
+    },
+    publishScoped(namespace, room, data) {
+      for (const hubId of reachableHubIds(namespace)) {
+        hubs.get(hubId)?.transport.publish(room, data);
+      }
+    },
+    setReplication(next) {
+      replication = next;
+      for (const room of activeRooms) reconcileRoom(room);
+    },
+    connect() {
+      for (const hub of hubs.values()) hub.transport.connect();
+    },
+    disconnect() {
+      for (const room of activeRooms) {
+        for (const unsubscribe of room.subscriptions.values()) unsubscribe();
+        room.subscriptions.clear();
+      }
+      activeRooms.clear();
+      for (const hub of hubs.values()) hub.transport.disconnect();
+    }
+  };
+}
+
+// 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 = {
@@ -3035,6 +3440,7 @@ function isProtocolCompatible(theirs) {
   return negotiateProtocolVersion(XNET_SUPPORTED_PROTOCOL_VERSIONS, theirs) !== null;
 }
 export {
+  AdapterConformanceError,
   METABRIDGE_ORIGIN,
   METABRIDGE_SEED_ORIGIN,
   NodeStoreSyncProvider,
@@ -3050,6 +3456,7 @@ export {
   createInitialSyncManager,
   createMetaBridge,
   createMultiHubConnectionManager,
+  createMultiHubSyncManager,
   createNodePool,
   createOfflineQueue,
   createRegistry,
@@ -3057,5 +3464,10 @@ export {
   createXNetClient,
   isProtocolCompatible,
   liveQuery,
-  negotiateProtocolVersion
+  namespaceForNode,
+  negotiateProtocolVersion,
+  replicationConfigFromPolicies,
+  runAdapterConformance,
+  spaceNamespace,
+  systemNamespace
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/runtime",
-  "version": "0.0.2",
+  "version": "0.1.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": {
@@ -28,15 +28,15 @@
   "dependencies": {
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.24",
-    "@xnetjs/core": "0.0.3",
-    "@xnetjs/crypto": "0.0.3",
-    "@xnetjs/data": "0.0.3",
-    "@xnetjs/data-bridge": "0.0.3",
-    "@xnetjs/history": "0.0.3",
-    "@xnetjs/identity": "0.0.3",
-    "@xnetjs/plugins": "0.0.3",
-    "@xnetjs/storage": "0.0.3",
-    "@xnetjs/sync": "0.0.3"
+    "@xnetjs/core": "0.1.0",
+    "@xnetjs/crypto": "0.1.0",
+    "@xnetjs/data-bridge": "0.1.0",
+    "@xnetjs/data": "0.1.0",
+    "@xnetjs/history": "0.1.0",
+    "@xnetjs/identity": "0.1.0",
+    "@xnetjs/plugins": "0.1.0",
+    "@xnetjs/storage": "0.1.0",
+    "@xnetjs/sync": "0.1.0"
   },
   "devDependencies": {
     "jsdom": "^26.0.0",