@mmstack/mesh-protocol 0.1.1 → 0.3.0

package/README.md

@@ -23,11 +23,13 @@ change; the relay assigns each one a room-scoped sequence number and fans it out
 relay only orders and stores opaque ops, it needs to understand nothing about your data. That
 is the point: a smart client with a dumb server.
 
-The relay is deliberately small. It sequences, keeps a journal, compacts a snapshot, answers a
-joining client with whatever it is missing, routes presence, and enforces an optional policy.
-It does not merge, validate schemas, or hold application logic. Conflict resolution is the
-client's job, and it happens per path, so two people editing different fields of the same
-record never collide.
+The relay is deliberately small. It sequences, keeps a journal, retains per-path register
+state, answers a joining client with whatever it is missing, routes presence, and enforces an
+optional policy. It does not merge, validate schemas, or hold application logic. Conflict
+resolution is the client's job: how concurrent writes fold into a value is client-configured
+policy, which is exactly why the relay never materializes a value of its own. It retains the
+concurrent writes and their supersession watermarks per path, and every client folds that same
+register state with its own rules.
 
 ## The envelope
 
@@ -39,10 +41,16 @@ type OpEnvelope = {
   version: number;       // per-origin counter, for gap detection
   hlc: { p: number; l: number }; // hybrid logical clock, for last-writer-wins ordering
   policyVersion: number; // the room policy this writer validated against
-  ops: readonly StoreOp[];
+  ops: readonly SyncOp[];
 };
 ```
 
+Each op is a structural `set`, `delete`, or `clear` plus two pieces of causal metadata: `cites`
+lists the sibling writes the emitter observed at that path (exactly those get superseded; an
+uncited concurrent write survives as a sibling), and `epoch` is the op's precedence term. An op
+without citations cannot be merged soundly, so envelopes from another protocol version are
+rejected outright rather than silently mixed into a room.
+
 `origin` and `writer` are separate on purpose. Two tabs of one signed-in user share a `writer`
 but differ by `origin`. `writer` is a stable, opaque pseudonym: the protocol forbids putting a
 real name in the envelope, so a person's display name lives in a mutable directory outside the
@@ -58,10 +66,14 @@ const relay = createRelay({
   policyVersion: 1,
   policy: myOpPolicy,           // optional, see below
   limits: { maxOpsPerEnvelope: 1024, maxEnvelopesPerSecond: 50 },
-  journalLimit: 1000,           // ops kept for delta catch-up before folding to a snapshot
+  journalLimit: 1000,           // envelopes kept for delta catch-up before compacting into register state
 });
 ```
 
+One sizing note: a subtree replace legitimately emits one `set` plus one `clear` per observed
+live descendant register in a single envelope, so a tightened `maxOpsPerEnvelope` must still
+accommodate honest clear-groups.
+
 `relay.connect(socket, ctx)` attaches one authenticated connection and returns
 `{ receive, disconnect }`. You pump inbound frames into `receive` and call `disconnect` on
 close. The `socket` is anything with `send(msg)` and `close()`, so the same relay drives a
@@ -71,9 +83,11 @@ When a client joins, the relay answers with one of three shapes:
 
 - `up-to-date` when the client already has the latest sequence,
 - `delta` with just the envelopes it missed, for a quick reconnect,
-- `snapshot` with the full root, when the client is too far behind for the journal to cover.
-
-Deletes fold correctly into the snapshot, so a late joiner never resurrects a removed key.
+- `snapshot` with the room's register state, when the client is too far behind for the journal
+  to cover. The client folds the registers with its own merge policy to derive its root, so a
+  late joiner ends up with exactly the state (and the supersession knowledge) of a peer that
+  saw every envelope. Deletes ride along as tombstone registers, so a late joiner never
+  resurrects a removed key.
 
 ## Trust: `OpPolicy` and the tripwire
 
@@ -97,6 +111,14 @@ 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. A `clear` op counts as a write at its path, so ACLs see a subtree
+replace's clear-group like any other write. And because the relay compacts envelopes into
+register state, 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.
@@ -145,12 +167,12 @@ Rooms live in memory. That covers dev and single-process deployments, and when t
 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.
+event-sourced journal is just `register checkpoint + envelopes`, compacted by re-checkpointing.
 
-`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:
+`onCommit` fires after every envelope is sequenced and retained, with the envelope and the
+room's current `{ seq, instance, registers, wm, schemaVersion }`. Append the envelope to your
+journal, and checkpoint the register state as often as you like. The relay never awaits it, so
+batching and backpressure belong to your adapter:
 
 ```ts
 const relay = createRelay({
@@ -169,16 +191,16 @@ members, so your load can race a fast client without corrupting a live sequence
 const saved = await checkpoints.get(roomName);
 if (saved) {
   relay.hydrate(roomName, {
-    ...saved, // seq, epoch, root
+    ...saved, // seq, instance, registers, wm
     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.
+Restoring the persisted `instance` nonce 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,5 +1,10 @@
 //#region src/lib/wire.d.ts
 type Key = string | number;
+/**
+ * One structural operation. `set` and `delete` change a value at a path; `clear` retires a
+ * per-path register without contributing a value (the observed-remove half of a subtree
+ * replace). A `clear` is still a WRITE at its path for policy purposes.
+ */
 type StoreOp = {
   kind: 'set';
   path: readonly Key[];
@@ -9,13 +14,36 @@ type StoreOp = {
   kind: 'delete';
   path: readonly Key[];
   prev: unknown;
+} | {
+  kind: 'clear';
+  path: readonly Key[];
 };
 /** Hybrid logical clock stamp: physical epoch ms + logical counter. */
 type Hlc = {
   readonly p: number;
   readonly l: number;
 };
-declare const MESH_PROTO_VERSION = 1;
+/** The identity of one write at one path: the emitting replica plus its clock stamp. */
+type Dot = {
+  readonly origin: string;
+  readonly hlc: Hlc;
+};
+/**
+ * A wire op: a structural {@link StoreOp} plus the causal metadata the per-path register
+ * needs. `cites` lists the sibling dot(s) the writer observed at the op's path when it wrote
+ * (exactly those get superseded); `epoch` is the op's precedence term, stamped at emission.
+ */
+type SyncOp = StoreOp & {
+  readonly cites: readonly Dot[];
+  readonly epoch: number;
+};
+/**
+ * Wire protocol version. Version 2 ops carry `cites` + `epoch`: an op without citations
+ * cannot be merged soundly (it would supersede nothing and its siblings would accumulate
+ * forever), so the relay rejects envelopes from any other protocol version outright rather
+ * than silently mixing pre-citation emitters into a room.
+ */
+declare const MESH_PROTO_VERSION = 2;
 type OpEnvelope = {
   readonly proto: number;
   readonly origin: string;
@@ -23,12 +51,43 @@ type OpEnvelope = {
   readonly version: number;
   readonly hlc: Hlc;
   readonly policyVersion: number;
-  readonly ops: readonly StoreOp[];
+  readonly ops: readonly SyncOp[];
+  /**
+   * Present only on a MIGRATION envelope: the new `schemaVersion` this envelope
+   * establishes. The relay bumps the room's schema + instance 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 & {
   readonly seq: number;
 };
+/**
+ * One retained concurrent write at a path. A register keeps at most one sibling per origin
+ * (a replica's newer op replaces its own older one), so state stays bounded by the
+ * concurrent-writer count, not the op count.
+ */
+type SyncSibling = {
+  readonly kind: 'set' | 'delete' | 'clear'; /** The written value for a `set`; absent for `delete`/`clear`. */
+  readonly value?: unknown; /** The emitter's inversion hint, kept for value-merging folds on the client. */
+  readonly prev?: unknown;
+  readonly writer: string;
+  readonly origin: string;
+  readonly hlc: Hlc;
+  readonly epoch: number;
+};
+/**
+ * Serializable per-path register state: the retained siblings plus the per-origin
+ * supersession watermarks. This is what a snapshot ships, never a folded value: the fold is
+ * client-configured policy, so a joiner seeded with a bare value could neither supersede nor
+ * be superseded correctly afterwards.
+ */
+type RegisterCheckpoint = {
+  readonly path: readonly Key[];
+  readonly siblings: readonly SyncSibling[];
+  readonly water: Readonly<Record<string, Hlc>>;
+};
 type PresenceState = {
   readonly origin: string;
   readonly writer: string; /** Consumer-defined activity payload (cursor, section, agent activity descriptor…). */
@@ -40,7 +99,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 +120,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 instance: 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[];
 } & ({
@@ -76,8 +137,9 @@ type WelcomeMsg = {
   readonly mode: 'delta';
   readonly envs: readonly SeqEnvelope[];
 } | {
-  readonly mode: 'snapshot';
-  readonly root: unknown;
+  readonly mode: 'snapshot'; /** The room's retained register state; the client folds it with its own policy. */
+  readonly registers: readonly RegisterCheckpoint[]; /** Per-origin envelope-version high-water marks at the snapshot point. */
+  readonly wm: Readonly<Record<string, number>>;
 });
 type ServerEnvMsg = {
   readonly t: 'env';
@@ -93,7 +155,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 = {
@@ -115,17 +177,18 @@ type ServerSignalMsg = {
   readonly from: string;
   readonly data: unknown;
 };
-type ServerMsg = WelcomeMsg | ServerEnvMsg | ServerPresenceMsg | RejectMsg | EjectMsg | MemberMsg | ServerSignalMsg;
-/**
- * Minimal pure op application for the relay's snapshot compaction — the same fold the L0
- * `applyOps` performs, owned here so the protocol package stays dependency-free.
- */
-declare function applyWireOps<T>(root: T, ops: readonly StoreOp[]): T;
+/** The room's stability frontier advanced (the relay compacted past it). A client may reclaim its
+ *  own register state at or below this stamp; a straggler below it is rejected at ingest. */
+type FrontierMsg = {
+  readonly t: 'frontier';
+  readonly room: string;
+  readonly frontier: Hlc;
+};
+type ServerMsg = WelcomeMsg | ServerEnvMsg | ServerPresenceMsg | RejectMsg | EjectMsg | MemberMsg | ServerSignalMsg | FrontierMsg;
 //#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 +197,21 @@ 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.
+ *
+ * A `clear` op counts as a write at its path (it retires that path's register as part of a
+ * subtree replace), so `canWrite` and `validate` see clears like any other op.
+ *
+ * This gates SHAPE and PATH access on a trusted `ctx.writer` (your adapter authenticates it). It
+ * does not by itself check the precedence an op claims or the authenticity of its citations; a rule
+ * like "only this role may override" belongs in `validate` against that trusted writer. A direct
+ * peer-to-peer connection bypasses the relay, so a peer-to-peer room is trust-full for authority.
  */
 type OpPolicy = {
   canWrite?(ctx: PrincipalCtx, path: readonly Key[]): boolean;
@@ -145,7 +219,8 @@ type OpPolicy = {
 };
 type PolicyViolation = {
   readonly writer: string;
-  readonly reason: 'can-write' | 'validate' | 'writer-mismatch' | 'proto' | 'ops-limit' | 'rate';
+  readonly reason: 'can-write' | 'validate' | 'malformed' | 'writer-mismatch' | 'proto' | 'ops-limit' | 'rate'; /** the specific well-formedness failure, when `reason` is `'malformed'`. */
+  readonly detail?: string;
   readonly path?: readonly Key[];
 };
 /** Check one envelope against a policy; `null` means clean. */
@@ -161,6 +236,43 @@ type PathAclRule = {
 };
 declare function pathPrefixAcl(rules: readonly PathAclRule[]): OpPolicy;
 //#endregion
+//#region src/lib/register.d.ts
+/**
+ * The relay's per-room register retention. It runs the same pure ingest rules a client's
+ * register runs (per path, keep the best op per origin plus the per-origin citation
+ * watermarks; live means above-watermark) and NOTHING else: it never resolves a conflict
+ * and never materializes a value. Conflict resolution (the fold) is client-configured
+ * policy, so a relay that folded values would seed joiners with one client's semantics;
+ * retention is uniform and policy-free, and identical register state folds identically on
+ * every client.
+ */
+type RegisterStore = {
+  /** Fold one sequenced envelope's ops into the per-path registers (retention only). */ingest(env: OpEnvelope): void; /** Serializable register state for a welcome snapshot or a persistence checkpoint. */
+  checkpoint(): RegisterCheckpoint[]; /** Merge checkpointed register state in (idempotent): the hydrate path. */
+  load(registers: readonly RegisterCheckpoint[]): void;
+  /**
+   * Compaction at the retention frontier (the stamp the journal no longer covers): drops
+   * superseded siblings and stale watermarks at or below it, and drops a register whose live
+   * set is a lone tombstone below it, but only when nothing else still materializes that
+   * key (no live descendant register, and no live ancestor `set` value containing it), so a
+   * dropped tombstone can never resurrect the value it deleted.
+   */
+  compact(frontier: Hlc): void; /** Drop all register state (a migration establishes a fresh retention window). */
+  reset(): void;
+};
+declare function createRegisterStore(): RegisterStore;
+//#endregion
+//#region src/lib/validate.d.ts
+/**
+ * Deterministic, total well-formedness check for a received envelope: returns a short reason string
+ * when it must be rejected WHOLE, or `null` when it is well-formed. It reads only the envelope, so
+ * the relay and every client accept or reject a given envelope identically. This is the STRUCTURAL
+ * TWIN of the client's `validateEnvelope` in @mmstack/primitives; the two must stay byte-identical
+ * in their accept/reject decisions (a parity property in the mesh client spec pins this). It
+ * validates SHAPE, not authority: authority and access control stay in the relay's policy check.
+ */
+declare function validateEnvelope(env: OpEnvelope): string | null;
+//#endregion
 //#region src/lib/relay.d.ts
 /** What the relay needs from a connection — implement over ws, a DO WebSocket, or a test pair. */
 type RelaySocket = {
@@ -168,39 +280,50 @@ type RelaySocket = {
   close?(): void;
 };
 type RelayLimits = {
-  /** Ops per envelope; a larger envelope is a violation (default 1024). */readonly maxOpsPerEnvelope?: number; /** Sustained envelopes/second per writer (token bucket, burst = 2×; off by default). */
+  /**
+   * Ops per envelope; a larger envelope is a violation (default 1024). A subtree replace
+   * legitimately emits one `set` plus one `clear` per observed live descendant register in a
+   * single envelope, so a tightened limit must still accommodate honest clear-groups.
+   */
+  readonly maxOpsPerEnvelope?: number; /** Sustained envelopes/second per writer (token bucket, burst = 2×; off by default). */
   readonly maxEnvelopesPerSecond?: number;
 };
 type RelayOptions = {
   /** Validation/ACL applied to every envelope; violations eject the writer (tripwire). */readonly policy?: OpPolicy;
   readonly policyVersion?: number;
-  readonly limits?: RelayLimits; /** Seq-envelopes retained per room for delta answers; older fold into the snapshot (default 1000). */
+  readonly limits?: RelayLimits; /** Seq-envelopes retained per room for delta answers; older compact into register state (default 1000). */
   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}.
+   * The persistence egress: fired after an envelope is sequenced, retained into the room's
+   * register state, and broadcast. The envelope is the persistence record (append it to a
+   * journal); `state` carries the retained register state 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;
+  readonly instance: string; /** The room's retained per-path register state, never a folded value. */
+  readonly registers: readonly RegisterCheckpoint[]; /** Per-origin envelope-version high-water marks. */
+  readonly wm: Readonly<Record<string, number>>; /** 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;
+  readonly seq: number; /** The retained register state captured at the checkpoint. */
+  readonly registers?: readonly RegisterCheckpoint[]; /** Per-origin envelope-version high-water marks captured at the checkpoint. */
+  readonly wm?: Readonly<Record<string, number>>;
   /**
-   * 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).
+   * Restore the persisted instance nonce 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 instance?: 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,18 +346,21 @@ type Relay = {
   hydrate(name: string, snapshot: RoomSnapshot): boolean;
 };
 /**
- * The reference relay core (op-protocol RFC §6/§7): 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
- * for snapshots, and never mints identity: `writer` comes from the adapter's auth.
+ * The reference relay core: room-scoped sequencing, journal + register-state 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 RETAINS ops (per-path registers, the same pure ingest rules every client
+ * runs) but never resolves them: conflict resolution is client-configured policy, so a relay
+ * that folded values would seed late joiners into permanent divergence from established
+ * peers. Snapshots therefore ship register state, never a value tree. It also never mints
+ * identity: `writer` comes from the adapter's auth.
  *
  * Room-initialization contract: a fresh room (seq 0) answers `up-to-date`; the first client
- * then SEEDS it with a root-set envelope so the room's snapshot root is complete (deletes
- * fold correctly, joiners replace-hydrate). Near-simultaneous first-joins of a brand-new
- * room may last-writer-wins their seeds; rooms created by a single client first (the
- * overwhelmingly common case) are unaffected.
+ * then SEEDS it with a root-set envelope so the room's register state is complete (joiners
+ * hydrate from it). Near-simultaneous first-joins of a brand-new room may race their seeds
+ * (the register retains both as concurrent siblings); rooms created by a single client first
+ * (the overwhelmingly common case) are unaffected.
  */
 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 RoomSnapshot, type RoomState, 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 Dot, 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 RegisterCheckpoint, type RegisterStore, 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 SyncOp, type SyncSibling, type WelcomeMsg, checkEnvelope, createRegisterStore, createRelay, pathPrefixAcl, validateEnvelope };

package/index.js

@@ -28,49 +28,192 @@ function pathPrefixAcl(rules) {
 	}) };
 }
 //#endregion
-//#region src/lib/wire.ts
-const MESH_PROTO_VERSION = 1;
+//#region src/lib/register.ts
+const SEP = "";
+const keyOf = (path) => path.map(String).join(SEP);
+const compareHlc = (a, b) => a.p !== b.p ? a.p - b.p : a.l - b.l;
+function createRegisterStore() {
+	const registers = /* @__PURE__ */ new Map();
+	const regAt = (path) => {
+		const key = keyOf(path);
+		let reg = registers.get(key);
+		if (!reg) {
+			reg = {
+				path,
+				siblings: /* @__PURE__ */ new Map(),
+				water: /* @__PURE__ */ new Map()
+			};
+			registers.set(key, reg);
+		}
+		return reg;
+	};
+	const liveOf = (reg) => {
+		const out = [];
+		for (const [origin, s] of reg.siblings) {
+			const w = reg.water.get(origin);
+			if (!w || compareHlc(s.hlc, w) > 0) out.push(s);
+		}
+		return out;
+	};
+	const isContainer = (v) => typeof v === "object" && v !== null;
+	/** Does `value` (an ancestor sibling's set value) still contain the key at `rel`? */
+	const contains = (value, rel) => {
+		let cur = value;
+		for (let i = 0; i < rel.length; i++) {
+			if (!isContainer(cur) || !Object.hasOwn(cur, String(rel[i]))) return false;
+			cur = cur[String(rel[i])];
+		}
+		return true;
+	};
+	/** A lone tombstone is droppable only if nothing else still materializes its key. */
+	const tombstoneDroppable = (key, reg) => {
+		for (const [k, other] of registers) {
+			if (k === key) continue;
+			if (k.startsWith(key + SEP)) {
+				if (liveOf(other).length > 0) return false;
+			} else if (key.startsWith(k === "" ? "" : k + SEP)) {
+				const rel = reg.path.slice(other.path.length);
+				for (const s of liveOf(other)) if (s.kind === "set" && contains(s.value, rel)) return false;
+			}
+		}
+		return true;
+	};
+	return {
+		ingest: (env) => {
+			for (const op of env.ops) {
+				if (!op.path.length && op.kind !== "set") continue;
+				const reg = regAt(op.path);
+				for (const c of op.cites ?? []) {
+					if (c.origin === env.origin && compareHlc(c.hlc, env.hlc) === 0) continue;
+					const cur = reg.water.get(c.origin);
+					if (!cur || compareHlc(c.hlc, cur) > 0) reg.water.set(c.origin, c.hlc);
+				}
+				const best = reg.siblings.get(env.origin);
+				if (!best || compareHlc(env.hlc, best.hlc) > 0) {
+					const sib = {
+						kind: op.kind,
+						writer: env.writer,
+						origin: env.origin,
+						hlc: env.hlc,
+						epoch: op.epoch ?? 0
+					};
+					if (op.kind === "set") sib.value = op.next;
+					if (op.kind !== "clear" && Object.hasOwn(op, "prev")) sib.prev = op.prev;
+					reg.siblings.set(env.origin, sib);
+				}
+			}
+		},
+		checkpoint: () => {
+			const out = [];
+			for (const reg of registers.values()) out.push({
+				path: reg.path,
+				siblings: [...reg.siblings.values()],
+				water: Object.fromEntries(reg.water)
+			});
+			return out;
+		},
+		load: (regs) => {
+			for (const r of regs) {
+				const reg = regAt(r.path);
+				for (const s of r.siblings) {
+					const cur = reg.siblings.get(s.origin);
+					if (!cur || compareHlc(s.hlc, cur.hlc) > 0) reg.siblings.set(s.origin, s);
+				}
+				for (const [origin, h] of Object.entries(r.water)) {
+					const cur = reg.water.get(origin);
+					if (!cur || compareHlc(h, cur) > 0) reg.water.set(origin, h);
+				}
+			}
+		},
+		compact: (frontier) => {
+			for (const [key, reg] of [...registers]) {
+				for (const [origin, s] of [...reg.siblings]) {
+					const w = reg.water.get(origin);
+					if (compareHlc(s.hlc, frontier) <= 0 && w && compareHlc(s.hlc, w) <= 0) reg.siblings.delete(origin);
+				}
+				for (const [origin, h] of [...reg.water]) if (compareHlc(h, frontier) <= 0) reg.water.delete(origin);
+				if (reg.siblings.size === 0 && reg.water.size === 0) registers.delete(key);
+			}
+			const byDepth = [...registers.entries()].sort((a, b) => b[1].path.length - a[1].path.length);
+			for (const [key, reg] of byDepth) {
+				const live = liveOf(reg);
+				if (live.length === 1 && live[0].kind === "delete" && reg.siblings.size === 1 && compareHlc(live[0].hlc, frontier) <= 0 && tombstoneDroppable(key, reg)) registers.delete(key);
+			}
+		},
+		reset: () => registers.clear()
+	};
+}
+//#endregion
+//#region src/lib/validate.ts
+const hasControlChar = (s) => {
+	for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) < 32) return true;
+	return false;
+};
+const isCleanId = (v) => typeof v === "string" && v.length > 0 && !hasControlChar(v);
+const isFiniteHlc = (h) => !!h && typeof h === "object" && Number.isFinite(h.p) && Number.isFinite(h.l);
 /**
-* Minimal pure op application for the relay's snapshot compaction — the same fold the L0
-* `applyOps` performs, owned here so the protocol package stays dependency-free.
+* Deterministic, total well-formedness check for a received envelope: returns a short reason string
+* when it must be rejected WHOLE, or `null` when it is well-formed. It reads only the envelope, so
+* the relay and every client accept or reject a given envelope identically. This is the STRUCTURAL
+* TWIN of the client's `validateEnvelope` in @mmstack/primitives; the two must stay byte-identical
+* in their accept/reject decisions (a parity property in the mesh client spec pins this). It
+* validates SHAPE, not authority: authority and access control stay in the relay's policy check.
 */
-function applyWireOps(root, ops) {
-	let next = root;
-	for (const op of ops) {
-		if (op.path.length === 0) {
-			if (op.kind === "set") next = op.next;
-			continue;
+function validateEnvelope(env) {
+	if (!env || typeof env !== "object") return "envelope";
+	if (!isCleanId(env.origin)) return "origin";
+	if (!isCleanId(env.writer)) return "writer";
+	if (!isFiniteHlc(env.hlc)) return "hlc";
+	if (!Number.isInteger(env.version) || env.version <= 0) return "version";
+	if (!Array.isArray(env.ops)) return "ops";
+	const seenPaths = /* @__PURE__ */ new Set();
+	for (const op of env.ops) {
+		if (!op || typeof op !== "object") return "op";
+		if (op.kind !== "set" && op.kind !== "delete" && op.kind !== "clear") return "kind";
+		if (!Array.isArray(op.path)) return "path";
+		for (const seg of op.path) {
+			if (typeof seg === "string" && hasControlChar(seg)) return "path-control";
+			if (seg === "__proto__") return "path-proto";
 		}
-		next = applyAt(next, op.path, 0, op);
+		if (op.path.length === 0 && op.kind !== "set") return "root-op";
+		const epoch = op.epoch;
+		if (typeof epoch !== "number" || !Number.isFinite(epoch) || epoch < 0) return "epoch";
+		const cites = op.cites;
+		if (!Array.isArray(cites)) return "cites";
+		for (const c of cites) if (!c || typeof c !== "object" || !isCleanId(c.origin) || !isFiniteHlc(c.hlc)) return "cites";
+		const key = op.path.map(String).join(String.fromCharCode(31));
+		if (seenPaths.has(key)) return "dup-path";
+		seenPaths.add(key);
 	}
-	return next;
-}
-function applyAt(container, path, idx, op) {
-	const seg = path[idx];
-	const base = Array.isArray(container) ? container.slice() : container !== null && typeof container === "object" ? { ...container } : typeof seg === "number" ? [] : {};
-	if (idx === path.length - 1) {
-		if (op.kind === "delete") delete base[seg];
-		else base[seg] = op.next;
-		return base;
-	}
-	base[seg] = applyAt(base[seg], path, idx + 1, op);
-	return base;
+	return null;
 }
 //#endregion
+//#region src/lib/wire.ts
+/**
+* Wire protocol version. Version 2 ops carry `cites` + `epoch`: an op without citations
+* cannot be merged soundly (it would supersede nothing and its siblings would accumulate
+* forever), so the relay rejects envelopes from any other protocol version outright rather
+* than silently mixing pre-citation emitters into a room.
+*/
+const MESH_PROTO_VERSION = 2;
+//#endregion
 //#region src/lib/relay.ts
-let epochCounter = 0;
+let instanceCounter = 0;
 /**
-* The reference relay core (op-protocol RFC §6/§7): 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
-* for snapshots, and never mints identity: `writer` comes from the adapter's auth.
+* The reference relay core: room-scoped sequencing, journal + register-state 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 RETAINS ops (per-path registers, the same pure ingest rules every client
+* runs) but never resolves them: conflict resolution is client-configured policy, so a relay
+* that folded values would seed late joiners into permanent divergence from established
+* peers. Snapshots therefore ship register state, never a value tree. It also never mints
+* identity: `writer` comes from the adapter's auth.
 *
 * Room-initialization contract: a fresh room (seq 0) answers `up-to-date`; the first client
-* then SEEDS it with a root-set envelope so the room's snapshot root is complete (deletes
-* fold correctly, joiners replace-hydrate). Near-simultaneous first-joins of a brand-new
-* room may last-writer-wins their seeds; rooms created by a single client first (the
-* overwhelmingly common case) are unaffected.
+* then SEEDS it with a root-set envelope so the room's register state is complete (joiners
+* hydrate from it). Near-simultaneous first-joins of a brand-new room may race their seeds
+* (the register retains both as concurrent siblings); rooms created by a single client first
+* (the overwhelmingly common case) are unaffected.
 */
 function createRelay(opt = {}) {
 	const rooms = /* @__PURE__ */ new Map();
@@ -79,13 +222,17 @@ function createRelay(opt = {}) {
 	const maxOps = opt.limits?.maxOpsPerEnvelope ?? 1024;
 	const rate = opt.limits?.maxEnvelopesPerSecond;
 	const now = opt.now ?? Date.now;
+	const mintInstance = () => `${now().toString(36)}-${(++instanceCounter).toString(36)}`;
 	const roomOf = (name) => {
 		let room = rooms.get(name);
 		if (!room) {
 			room = {
 				seq: 0,
-				epoch: `${now().toString(36)}-${(++epochCounter).toString(36)}`,
-				root: void 0,
+				instance: mintInstance(),
+				schemaVersion: 0,
+				registers: createRegisterStore(),
+				wm: /* @__PURE__ */ new Map(),
+				frontier: void 0,
 				journal: [],
 				members: /* @__PURE__ */ new Set(),
 				presence: /* @__PURE__ */ new Map(),
@@ -96,6 +243,10 @@ function createRelay(opt = {}) {
 		}
 		return room;
 	};
+	const maybeEvictEmpty = (name) => {
+		const room = rooms.get(name);
+		if (room && room.members.size === 0 && room.seq === 0 && room.ejected.size === 0) rooms.delete(name);
+	};
 	const broadcast = (room, msg, except) => {
 		for (const member of room.members) if (member !== except) member.socket.send(msg);
 	};
@@ -149,6 +300,7 @@ function createRelay(opt = {}) {
 		bucket.tokens -= 1;
 		return false;
 	};
+	const laterHlc = (a, b) => !a || b.p > a.p || b.p === a.p && b.l > a.l ? b : a;
 	return {
 		room: (name) => {
 			const room = rooms.get(name);
@@ -162,8 +314,10 @@ function createRelay(opt = {}) {
 			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;
+			room.registers.load(snapshot.registers ?? []);
+			for (const [origin, v] of Object.entries(snapshot.wm ?? {})) room.wm.set(origin, Math.max(room.wm.get(origin) ?? 0, v));
+			if (snapshot.instance !== void 0) room.instance = snapshot.instance;
+			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;
 		},
@@ -181,6 +335,7 @@ function createRelay(opt = {}) {
 						origin: member.origin,
 						gone: true
 					});
+					maybeEvictEmpty(name);
 				}
 				joined.clear();
 			};
@@ -197,13 +352,14 @@ function createRelay(opt = {}) {
 							});
 							return;
 						}
-						if (msg.proto !== 1) {
+						if (msg.proto !== 2) {
 							socket.send({
 								t: "reject",
 								room: msg.room,
 								reason: "proto",
-								expected: 1
+								expected: 2
 							});
+							maybeEvictEmpty(msg.room);
 							return;
 						}
 						if (msg.policyVersion !== policyVersion) {
@@ -213,6 +369,17 @@ function createRelay(opt = {}) {
 								reason: "policy-version",
 								expected: policyVersion
 							});
+							maybeEvictEmpty(msg.room);
+							return;
+						}
+						if (msg.schemaVersion !== void 0 && msg.schemaVersion < room.schemaVersion) {
+							socket.send({
+								t: "reject",
+								room: msg.room,
+								reason: "schema",
+								expected: room.schemaVersion
+							});
+							maybeEvictEmpty(msg.room);
 							return;
 						}
 						for (const prior of [...room.members]) {
@@ -238,7 +405,8 @@ function createRelay(opt = {}) {
 							t: "welcome",
 							room: msg.room,
 							seq: room.seq,
-							epoch: room.epoch,
+							instance: room.instance,
+							schemaVersion: room.schemaVersion,
 							peers,
 							members: [...room.members].filter((m) => m !== member).map((m) => m.origin)
 						};
@@ -256,7 +424,8 @@ function createRelay(opt = {}) {
 						} else socket.send({
 							...base,
 							mode: "snapshot",
-							root: room.root
+							registers: room.registers.checkpoint(),
+							wm: Object.fromEntries(room.wm)
 						});
 						return;
 					}
@@ -292,9 +461,14 @@ function createRelay(opt = {}) {
 						return;
 					}
 					const env = msg.env;
-					const violation = env.policyVersion !== policyVersion || env.proto !== 1 ? {
+					const malformed = validateEnvelope(env);
+					const violation = env.policyVersion !== policyVersion || env.proto !== 2 ? {
 						writer: ctx.writer,
 						reason: "proto"
+					} : malformed !== null ? {
+						writer: ctx.writer,
+						reason: "malformed",
+						detail: malformed
 					} : env.ops.length > maxOps ? {
 						writer: ctx.writer,
 						reason: "ops-limit"
@@ -306,13 +480,33 @@ function createRelay(opt = {}) {
 						eject(msg.room, room, ctx.writer, violation);
 						return;
 					}
+					if (env.schemaVersion !== void 0 && env.schemaVersion < room.schemaVersion) return;
 					const seqEnv = {
 						...env,
 						seq: ++room.seq
 					};
 					room.journal.push(seqEnv);
-					room.root = applyWireOps(room.root, env.ops);
-					if (room.journal.length > journalLimit) room.journal.shift();
+					if (env.schemaVersion !== void 0 && env.schemaVersion > room.schemaVersion) {
+						room.schemaVersion = env.schemaVersion;
+						room.instance = mintInstance();
+						room.registers.reset();
+						room.frontier = void 0;
+						room.journal = [seqEnv];
+					}
+					room.registers.ingest(env);
+					room.wm.set(env.origin, Math.max(room.wm.get(env.origin) ?? 0, env.version));
+					if (room.journal.length > journalLimit) {
+						const trimmed = room.journal.shift();
+						if (trimmed) {
+							room.frontier = laterHlc(room.frontier, trimmed.hlc);
+							room.registers.compact(room.frontier);
+							broadcast(room, {
+								t: "frontier",
+								room: msg.room,
+								frontier: room.frontier
+							});
+						}
+					}
 					broadcast(room, {
 						t: "env",
 						room: msg.room,
@@ -320,8 +514,10 @@ function createRelay(opt = {}) {
 					});
 					opt.onCommit?.(msg.room, seqEnv, {
 						seq: room.seq,
-						epoch: room.epoch,
-						root: room.root
+						instance: room.instance,
+						registers: room.registers.checkpoint(),
+						wm: Object.fromEntries(room.wm),
+						schemaVersion: room.schemaVersion
 					});
 				}
 			};
@@ -329,4 +525,4 @@ function createRelay(opt = {}) {
 	};
 }
 //#endregion
-export { MESH_PROTO_VERSION, applyWireOps, checkEnvelope, createRelay, pathPrefixAcl };
+export { MESH_PROTO_VERSION, checkEnvelope, createRegisterStore, createRelay, pathPrefixAcl, validateEnvelope };

package/package.json

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