@mmstack/mesh-protocol 0.1.0 → 0.2.0

package/README.md

@@ -97,6 +97,13 @@ matches a path. For richer rules, write your own `OpPolicy` with `canWrite` and
 Schema-aware validation (deriving a policy from your data model) composes on top and stays in
 your codebase, not here.
 
+Two boundaries to be clear about. Policy gates writes, not reads: every member of a room sees
+the whole root, so the room is the confidentiality boundary, and data with different audiences
+belongs in different rooms. And because the relay folds envelopes into snapshots, it reads
+plaintext; end-to-end encryption where the server sees only ciphertext is incompatible with
+server-side compaction as designed. Encrypt the transport and the stored data, but treat the
+relay as inside the trust boundary.
+
 ## Adapter recipes
 
 The relay is pure over injected sockets, so an adapter is a few lines of glue.
@@ -139,8 +146,46 @@ export class MeshRoom {
 }
 ```
 
-Durable storage (journal persistence across restarts) rides the same seam and lands with a
-later release. In-memory rooms cover dev and single-process deployments today.
+## Persistence
+
+Rooms live in memory. That covers dev and single-process deployments, and when the relay
+restarts, the first client to rejoin seeds the room from its own local state, so nothing is
+lost as long as somebody was online. For durability beyond that, the relay exposes a seam
+rather than a storage engine, because the envelope already is the persistence record: an
+event-sourced journal is just `snapshot + envelopes`, compacted by re-snapshotting.
+
+`onCommit` fires after every envelope is sequenced and folded, with the envelope and the
+room's current `{ seq, epoch, root }`. Append the envelope to your journal, and checkpoint the
+root as often as you like. The relay never awaits it, so batching and backpressure belong to
+your adapter:
+
+```ts
+const relay = createRelay({
+  onCommit: (room, env, state) => {
+    journal.append(room, env); // your DB, KV, or DO storage
+    if (state.seq % 100 === 0) checkpoints.put(room, state);
+  },
+});
+```
+
+`relay.hydrate(room, snapshot)` restores a persisted room before clients join (relay boot, or
+inside a Durable Object's `blockConcurrencyWhile`). It refuses once the room has state or
+members, so your load can race a fast client without corrupting a live sequence space:
+
+```ts
+const saved = await checkpoints.get(roomName);
+if (saved) {
+  relay.hydrate(roomName, {
+    ...saved, // seq, epoch, root
+    journal: await journal.tail(roomName, saved.seq),
+  });
+}
+```
+
+Restoring the persisted `epoch` is what lets clients that were connected before the restart
+keep their sequence watermark and catch up with a cheap `delta` answer. Omit it and they fall
+back to a full snapshot, which is always safe. The optional journal tail is only there to make
+those delta answers possible; the room is complete without it.
 
 ## WebRTC signaling
 

package/index.d.ts

@@ -1,10 +1,4 @@
 //#region src/lib/wire.d.ts
-/**
- * Canonical wire types of the mmstack op protocol (op-protocol RFC §3/§6). Structurally
- * identical to the L0 types in `@mmstack/primitives` — deliberately NOT imported from there,
- * so this package stays zero-dependency and never drags Angular peers onto a server. The
- * client package asserts mutual assignability at compile time.
- */
 type Key = string | number;
 type StoreOp = {
   kind: 'set';
@@ -30,6 +24,12 @@ type OpEnvelope = {
   readonly hlc: Hlc;
   readonly policyVersion: number;
   readonly ops: readonly StoreOp[];
+  /**
+   * Present only on a MIGRATION envelope: the new `schemaVersion` this envelope
+   * establishes. The relay bumps the room's schema + epoch when it sequences one; normal writes
+   * omit it.
+   */
+  readonly schemaVersion?: number;
 };
 /** An envelope the relay has ordered: `seq` is the room-scoped total order. */
 type SeqEnvelope = OpEnvelope & {
@@ -46,7 +46,8 @@ type HelloMsg = {
   readonly origin: string;
   readonly proto: number;
   readonly policyVersion: number; /** Last room seq this client has applied — enables the delta answer on reconnect. */
-  readonly seq?: number;
+  readonly seq?: number; /** The data shape this client speaks, older-than-room is rejected `schema`. */
+  readonly schemaVersion?: number;
 };
 type ClientEnvMsg = {
   readonly t: 'env';
@@ -66,14 +67,15 @@ type ClientSignalMsg = {
   readonly data: unknown;
 };
 type ClientMsg = HelloMsg | ClientEnvMsg | ClientPresenceMsg | ClientSignalMsg;
-/** The tri-state join answer (RFC §6), plus the current presence roster. */
+/** The tri-state join answer, plus the current presence roster. */
 type WelcomeMsg = {
   readonly t: 'welcome';
   readonly room: string;
   readonly seq: number;
   /** Room-instance nonce: changes when a room is recreated (relay restart, DO eviction),
    *  so clients know their seq watermark belongs to a dead seq space. */
-  readonly epoch: string;
+  readonly epoch: string; /** The room's current data shape. */
+  readonly schemaVersion: number;
   readonly peers: readonly PresenceState[]; /** Origins currently in the room (membership ≠ presence) — the P2P bootstrap roster. */
   readonly members: readonly string[];
 } & ({
@@ -99,7 +101,7 @@ type ServerPresenceMsg = {
 type RejectMsg = {
   readonly t: 'reject';
   readonly room: string;
-  readonly reason: 'proto' | 'policy-version' | 'unauthorized';
+  readonly reason: 'proto' | 'policy-version' | 'unauthorized' | 'schema';
   readonly expected?: number;
 };
 type EjectMsg = {
@@ -130,8 +132,7 @@ declare function applyWireOps<T>(root: T, ops: readonly StoreOp[]): T;
 //#endregion
 //#region src/lib/policy.d.ts
 /**
- * The principal behind a connection, as authenticated by the adapter (the relay never mints
- * identity — RFC §3). `kind` distinguishes non-human peers: an agent is a user (§0), just one
+ * The principal behind a connection, as authenticated by the adapter. `kind` distinguishes non-human peers: an agent is a user, just one
  * whose policy is usually narrower.
  */
 type PrincipalCtx = {
@@ -140,10 +141,13 @@ type PrincipalCtx = {
   readonly claims?: Readonly<Record<string, unknown>>;
 };
 /**
- * Pure, deterministic, versioned validation (RFC §7). Run symmetrically on emit and on
+ * Pure, deterministic, versioned validation. Run symmetrically on emit and on
  * apply: honest peers never emit invalid ops, so any violation observed on the wire is a
  * buggy or malicious writer — tripwire semantics eject it deterministically. Never skip an
  * op mid-log.
+ *
+ * This is a WRITE ACL, not a read ACL: every room member sees the whole root, so the room is
+ * the confidentiality boundary. Data with different audiences belongs in different rooms.
  */
 type OpPolicy = {
   canWrite?(ctx: PrincipalCtx, path: readonly Key[]): boolean;
@@ -184,6 +188,32 @@ type RelayOptions = {
   readonly journalLimit?: number;
   readonly now?: () => number;
   readonly onViolation?: (room: string, violation: PolicyViolation) => void;
+  /**
+   * The persistence egress: fired after an envelope is sequenced, folded into the room
+   * snapshot, and broadcast. The envelope is the persistence record (append it to a journal);
+   * `state` carries the folded root for throttled checkpoints. Called synchronously and never
+   * awaited: batch, debounce, and store at the adapter layer. Pair with {@link Relay.hydrate}.
+   */
+  readonly onCommit?: (room: string, env: SeqEnvelope, state: RoomState) => void;
+};
+/** The room's durable state at a commit: what a checkpoint needs to capture. */
+type RoomState = {
+  readonly seq: number;
+  readonly epoch: string;
+  readonly root: unknown; /** The room's data shape; restored via {@link Relay.hydrate}. */
+  readonly schemaVersion: number;
+};
+/** A persisted room to restore via {@link Relay.hydrate}. */
+type RoomSnapshot = {
+  readonly seq: number;
+  readonly root: unknown;
+  /**
+   * Restore the persisted epoch so clients reconnecting across the restart keep their seq
+   * watermark and get a `delta` answer; omit to mint a fresh one (they re-snapshot instead).
+   */
+  readonly epoch?: string; /** Restore the persisted schema version (a compacted snapshot is post-migration). */
+  readonly schemaVersion?: number; /** Journal tail (ascending seq, entries at or below `seq`) enabling those delta answers. */
+  readonly journal?: readonly SeqEnvelope[];
 };
 type RelayConnection = {
   receive(msg: ClientMsg): void;
@@ -197,9 +227,15 @@ type RoomInfo = {
 type Relay = {
   /** Attach an authenticated connection. `ctx.writer` is the trusted principal. */connect(socket: RelaySocket, ctx: PrincipalCtx): RelayConnection;
   room(name: string): RoomInfo | undefined;
+  /**
+   * Restore a persisted room before clients join (relay boot, Durable Object wake). Refused
+   * (`false`) once the room has state or members: hydrating a live seq space would corrupt
+   * it. Load asynchronously at the adapter layer, then hydrate synchronously.
+   */
+  hydrate(name: string, snapshot: RoomSnapshot): boolean;
 };
 /**
- * The reference relay core (op-protocol RFC §6/§7): room-scoped sequencing, journal +
+ * The reference relay core: room-scoped sequencing, journal +
  * snapshot compaction, the tri-state join answer, presence fan-out, and tripwire policy
  * enforcement. Pure over injected sockets — runs identically under ws, Bun, a Durable
  * Object, or an in-memory test pair. The relay never interprets ops beyond folding them
@@ -213,4 +249,4 @@ type Relay = {
  */
 declare function createRelay(opt?: RelayOptions): Relay;
 //#endregion
-export { type ClientEnvMsg, type ClientMsg, type ClientPresenceMsg, type ClientSignalMsg, type EjectMsg, type HelloMsg, type Hlc, type Key, MESH_PROTO_VERSION, type MemberMsg, type OpEnvelope, type OpPolicy, type PathAclRule, type PolicyViolation, type PresenceState, type PrincipalCtx, type RejectMsg, type Relay, type RelayConnection, type RelayLimits, type RelayOptions, type RelaySocket, type RoomInfo, type SeqEnvelope, type ServerEnvMsg, type ServerMsg, type ServerPresenceMsg, type ServerSignalMsg, type StoreOp, type WelcomeMsg, applyWireOps, checkEnvelope, createRelay, pathPrefixAcl };
+export { type ClientEnvMsg, type ClientMsg, type ClientPresenceMsg, type ClientSignalMsg, type EjectMsg, type HelloMsg, type Hlc, type Key, MESH_PROTO_VERSION, type MemberMsg, type OpEnvelope, type OpPolicy, type PathAclRule, type PolicyViolation, type PresenceState, type PrincipalCtx, type RejectMsg, type Relay, type RelayConnection, type RelayLimits, type RelayOptions, type RelaySocket, type RoomInfo, type RoomSnapshot, type RoomState, type SeqEnvelope, type ServerEnvMsg, type ServerMsg, type ServerPresenceMsg, type ServerSignalMsg, type StoreOp, type WelcomeMsg, applyWireOps, checkEnvelope, createRelay, pathPrefixAcl };

package/index.js

@@ -60,7 +60,7 @@ function applyAt(container, path, idx, op) {
 //#region src/lib/relay.ts
 let epochCounter = 0;
 /**
-* The reference relay core (op-protocol RFC §6/§7): room-scoped sequencing, journal +
+* The reference relay core: room-scoped sequencing, journal +
 * snapshot compaction, the tri-state join answer, presence fan-out, and tripwire policy
 * enforcement. Pure over injected sockets — runs identically under ws, Bun, a Durable
 * Object, or an in-memory test pair. The relay never interprets ops beyond folding them
@@ -85,6 +85,7 @@ function createRelay(opt = {}) {
 			room = {
 				seq: 0,
 				epoch: `${now().toString(36)}-${(++epochCounter).toString(36)}`,
+				schemaVersion: 0,
 				root: void 0,
 				journal: [],
 				members: /* @__PURE__ */ new Set(),
@@ -158,6 +159,16 @@ function createRelay(opt = {}) {
 				journal: room.journal.length
 			} : void 0;
 		},
+		hydrate: (name, snapshot) => {
+			const room = roomOf(name);
+			if (room.seq !== 0 || room.members.size > 0 || room.journal.length > 0) return false;
+			room.seq = snapshot.seq;
+			room.root = snapshot.root;
+			if (snapshot.epoch !== void 0) room.epoch = snapshot.epoch;
+			if (snapshot.schemaVersion !== void 0) room.schemaVersion = snapshot.schemaVersion;
+			if (snapshot.journal) room.journal = snapshot.journal.filter((e) => e.seq <= snapshot.seq).sort((a, b) => a.seq - b.seq).slice(-journalLimit);
+			return true;
+		},
 		connect: (socket, ctx) => {
 			const joined = /* @__PURE__ */ new Map();
 			const disconnect = () => {
@@ -206,6 +217,15 @@ function createRelay(opt = {}) {
 							});
 							return;
 						}
+						if (msg.schemaVersion !== void 0 && msg.schemaVersion < room.schemaVersion) {
+							socket.send({
+								t: "reject",
+								room: msg.room,
+								reason: "schema",
+								expected: room.schemaVersion
+							});
+							return;
+						}
 						for (const prior of [...room.members]) {
 							if (prior.origin !== msg.origin) continue;
 							room.members.delete(prior);
@@ -230,6 +250,7 @@ function createRelay(opt = {}) {
 							room: msg.room,
 							seq: room.seq,
 							epoch: room.epoch,
+							schemaVersion: room.schemaVersion,
 							peers,
 							members: [...room.members].filter((m) => m !== member).map((m) => m.origin)
 						};
@@ -303,12 +324,22 @@ function createRelay(opt = {}) {
 					};
 					room.journal.push(seqEnv);
 					room.root = applyWireOps(room.root, env.ops);
+					if (env.schemaVersion !== void 0 && env.schemaVersion > room.schemaVersion) {
+						room.schemaVersion = env.schemaVersion;
+						room.epoch = `${now().toString(36)}-${(++epochCounter).toString(36)}`;
+					}
 					if (room.journal.length > journalLimit) room.journal.shift();
 					broadcast(room, {
 						t: "env",
 						room: msg.room,
 						env: seqEnv
 					});
+					opt.onCommit?.(msg.room, seqEnv, {
+						seq: room.seq,
+						epoch: room.epoch,
+						root: room.root,
+						schemaVersion: room.schemaVersion
+					});
 				}
 			};
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/mesh-protocol",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -33,4 +33,4 @@
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/mesh/protocol",
   "sideEffects": false
-}
+}