@mmstack/mesh-protocol 0.1.1 → 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.

package/index.d.ts

@@ -24,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 & {
@@ -40,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';
@@ -60,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[];
 } & ({
@@ -93,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 = {
@@ -124,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 = {
@@ -134,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;
@@ -190,7 +200,8 @@ type RelayOptions = {
 type RoomState = {
   readonly seq: number;
   readonly epoch: string;
-  readonly root: unknown;
+  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 = {
@@ -200,7 +211,8 @@ type RoomSnapshot = {
    * 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; /** Journal tail (ascending seq, entries at or below `seq`) enabling those delta answers. */
+  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 = {
@@ -223,7 +235,7 @@ type Relay = {
   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

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(),
@@ -164,6 +165,7 @@ function createRelay(opt = {}) {
 			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;
 		},
@@ -215,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);
@@ -239,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)
 						};
@@ -312,6 +324,10 @@ 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",
@@ -321,7 +337,8 @@ function createRelay(opt = {}) {
 					opt.onCommit?.(msg.room, seqEnv, {
 						seq: room.seq,
 						epoch: room.epoch,
-						root: room.root
+						root: room.root,
+						schemaVersion: room.schemaVersion
 					});
 				}
 			};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/mesh-protocol",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",