@forgeax/engine-net 0.1.4 → 0.1.7

package/dist/index.mjs

@@ -64,8 +64,8 @@ var ENDPOINT_EXPECTED = Object.fromEntries(
 var ENDPOINT_ERROR_HINTS = Object.fromEntries(
   Object.entries(endpointErrorPolicy).map(([code, policy]) => [code, policy.hint])
 );
-function isEndpointError(err8) {
-  return err8 instanceof EndpointErrorClass;
+function isEndpointError(err9) {
+  return err9 instanceof EndpointErrorClass;
 }
 var MemoryEndpoint = class {
   _peerId;
@@ -201,9 +201,28 @@ function createMemoryEndpointPairWithController() {
   };
   return { endpoints: [epA, epB], controller };
 }
+function createMemoryEndpointConnector(createEndpoint) {
+  return {
+    connect(signal) {
+      if (signal.aborted)
+        return Promise.resolve(
+          err(
+            new EndpointError({
+              code: "connection-failed",
+              expected: ENDPOINT_EXPECTED["connection-failed"],
+              hint: ENDPOINT_ERROR_HINTS["connection-failed"],
+              detail: { address: "memory", cause: "connect aborted" }
+            })
+          )
+        );
+      return Promise.resolve(ok(createEndpoint()));
+    }
+  };
+}
 
 // src/replication/constants.ts
-var REPLICATION_PROTOCOL_VERSION = 1;
+var REPLICATION_PROTOCOL_VERSION = 2;
+var REPLICATION_PROTOCOL_PREFIX = "FXRP2";
 
 // src/replication/errors.ts
 var NetErrorClass = class extends Error {
@@ -223,13 +242,6 @@ var NetErrorClass = class extends Error {
 var NetError = NetErrorClass;
 
 // src/replication/codec.ts
-var REPLICATION_ENTITY_KINDS = [
-  "upsert",
-  "despawn"
-];
-function isReplicationEntityKind(value) {
-  return REPLICATION_ENTITY_KINDS.some((kind) => kind === value);
-}
 var TYPED_ARRAYS = {
   Float32Array,
   Float64Array,
@@ -241,6 +253,30 @@ var TYPED_ARRAYS = {
   Uint16Array,
   Uint32Array
 };
+var PACKET_KINDS = [
+  "session-open",
+  "session-resume",
+  "baseline",
+  "delta",
+  "ack",
+  "rejection"
+];
+var REPLICATION_ENTITY_KINDS = [
+  "upsert",
+  "despawn"
+];
+function isPacketKind(value) {
+  return PACKET_KINDS.some((kind) => kind === value);
+}
+function isReplicationEntityKind(value) {
+  return REPLICATION_ENTITY_KINDS.some((kind) => kind === value);
+}
+function isSafeNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isSessionId(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
 function typedArrayName(value) {
   for (const [name, typedArrayConstructor] of Object.entries(TYPED_ARRAYS)) {
     if (value instanceof typedArrayConstructor) return name;
@@ -252,11 +288,10 @@ function canonicalize(value) {
   if (name !== void 0)
     return { $typedArray: name, values: Array.from(value) };
   if (Array.isArray(value)) return value.map(canonicalize);
-  if (value !== null && typeof value === "object") {
+  if (value !== null && typeof value === "object")
     return Object.fromEntries(
       Object.keys(value).sort().map((key) => [key, canonicalize(value[key])])
     );
-  }
   return value;
 }
 function reviveTypedArrays(value) {
@@ -271,7 +306,7 @@ function reviveTypedArrays(value) {
   }
   if (value === null || typeof value !== "object") return { value };
   const record = value;
-  if ("$typedArray" in record || "values" in record) {
+  if ("$typedArray" in record) {
     if (Object.keys(record).length !== 2 || typeof record.$typedArray !== "string" || !Array.isArray(record.values))
       return { reason: "typed-array tag must contain only an allowlisted name and values array" };
     const typedArrayConstructor = TYPED_ARRAYS[record.$typedArray];
@@ -295,11 +330,57 @@ function limitError(limit, actual, maximum) {
     detail: { limit, actual, maximum }
   });
 }
-function validateLimits(batch, bytes, limits) {
+function invalid(reason) {
+  return new NetError({
+    code: "decode-invalid-payload",
+    expected: `a version ${REPLICATION_PROTOCOL_VERSION} ${REPLICATION_PROTOCOL_PREFIX} packet`,
+    hint: "send bytes produced by the protocol-v2 replication codec",
+    detail: { reason }
+  });
+}
+function validateEntities(entities) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const [entityIndex, entity] of entities.entries()) {
+    if (entity === null || typeof entity !== "object" || !isSafeNonNegativeInteger(entity.id) || !isReplicationEntityKind(entity.kind) || !Array.isArray(entity.components) || ids.has(entity.id))
+      return `entity record ${entityIndex} has an invalid or duplicate identity`;
+    ids.add(entity.id);
+    for (const [componentIndex, component] of entity.components.entries()) {
+      if (component === null || typeof component !== "object" || typeof component.name !== "string" || component.name.length === 0 || component.operation !== void 0 && component.operation !== "replace" && component.operation !== "remove" || component.data === null || typeof component.data !== "object" || Array.isArray(component.data) || component.operation === "remove" && Object.keys(component.data).length !== 0)
+        return `component record ${entityIndex}:${componentIndex} has invalid fields`;
+    }
+  }
+  return void 0;
+}
+function validatePacket(packet) {
+  if (packet.version !== REPLICATION_PROTOCOL_VERSION)
+    return "packet protocol version is unsupported";
+  if (!isPacketKind(packet.kind)) return "packet kind is unsupported";
+  if (!isSessionId(packet.sessionId)) return "sessionId must be a positive safe integer";
+  if (!isSafeNonNegativeInteger(packet.epoch)) return "epoch must be a non-negative safe integer";
+  if (packet.kind === "session-open" || packet.kind === "session-resume")
+    return packet.sequence === 0 ? void 0 : "session control sequence must be zero";
+  if (packet.kind === "ack")
+    return isSafeNonNegativeInteger(packet.acknowledgedSequence) ? void 0 : "acknowledgedSequence must be a non-negative safe integer";
+  if (!isSafeNonNegativeInteger(packet.sequence) || packet.sequence === 0)
+    return "sequence must be a positive safe integer";
+  if (packet.kind === "baseline" && packet.sequence !== 1) return "baseline sequence must be one";
+  if (packet.kind === "rejection") {
+    if (!isPacketKind(packet.rejectedKind) || typeof packet.reason !== "string")
+      return "rejection details are invalid";
+    return void 0;
+  }
+  if (packet.kind !== "baseline" && packet.kind !== "delta")
+    return "packet kind does not carry a data payload";
+  if (typeof packet.tick !== "number" || !Number.isSafeInteger(packet.tick))
+    return "tick must be a safe integer";
+  if (typeof packet.fingerprint !== "string") return "fingerprint must be a string";
+  return validateEntities(packet.entities);
+}
+function validateLimits(packet, bytes, limits) {
   if (bytes !== void 0 && bytes.byteLength > limits.maxMessageBytes)
     return limitError("maxMessageBytes", bytes.byteLength, limits.maxMessageBytes);
-  if (batch.entities.length > limits.maxEntities)
-    return limitError("maxEntities", batch.entities.length, limits.maxEntities);
+  if (packet.entities.length > limits.maxEntities)
+    return limitError("maxEntities", packet.entities.length, limits.maxEntities);
   let operations = 0;
   const visit = (value) => {
     if (typeof value === "string" && new TextEncoder().encode(value).byteLength > limits.maxStringBytes)
@@ -332,7 +413,7 @@ function validateLimits(batch, bytes, limits) {
       }
     return null;
   };
-  for (const entity of batch.entities) {
+  for (const entity of packet.entities) {
     operations += entity.components.length;
     for (const component of entity.components) {
       const problem = visit(component.data);
@@ -342,58 +423,57 @@ function validateLimits(batch, bytes, limits) {
   return operations > limits.maxComponentOperations ? limitError("maxComponentOperations", operations, limits.maxComponentOperations) : null;
 }
 function parse(bytes) {
+  const text = new TextDecoder().decode(bytes);
+  const separator = text.indexOf("\n");
+  if (separator < 0 || text.slice(0, separator) !== REPLICATION_PROTOCOL_PREFIX)
+    return { error: invalid("packet prefix does not match protocol-v2") };
   try {
-    const decoded = JSON.parse(new TextDecoder().decode(bytes));
+    const decoded = JSON.parse(text.slice(separator + 1));
     const revived = reviveTypedArrays(decoded);
-    if ("reason" in revived) return revived;
+    if ("reason" in revived) return { error: invalid(revived.reason) };
     if (revived.value === null || typeof revived.value !== "object")
-      return { reason: "batch must be an object" };
-    const batch = revived.value;
-    if (!Array.isArray(batch.entities) || typeof batch.fingerprint !== "string" || !Number.isSafeInteger(batch.tick) || !Number.isSafeInteger(batch.version) || typeof batch.full !== "boolean")
-      return { reason: "batch envelope has an invalid field type" };
-    for (const [entityIndex, entity] of batch.entities.entries()) {
-      if (entity === null || typeof entity !== "object")
-        return { reason: `entity record ${entityIndex} must be an object` };
-      const record = entity;
-      if (!Number.isSafeInteger(record.id) || !isReplicationEntityKind(record.kind) || !Array.isArray(record.components))
-        return { reason: `entity record ${entityIndex} has an invalid field type` };
-      for (const [componentIndex, component] of record.components.entries()) {
-        if (component === null || typeof component !== "object")
-          return { reason: `component record ${entityIndex}:${componentIndex} must be an object` };
-        const entry = component;
-        if (typeof entry.name !== "string" || entry.name.length === 0 || entry.operation !== void 0 && entry.operation !== "replace" && entry.operation !== "remove" || entry.data === null || typeof entry.data !== "object" || Array.isArray(entry.data) || entry.operation === "remove" && Object.keys(entry.data).length !== 0)
-          return {
-            reason: `component record ${entityIndex}:${componentIndex} has an invalid field type`
-          };
-      }
+      return { error: invalid("packet must be an object") };
+    const packet = revived.value;
+    const reason = validatePacket(packet);
+    if (reason !== void 0) {
+      if (typeof packet.version === "number" && packet.version !== REPLICATION_PROTOCOL_VERSION)
+        return {
+          error: new NetError({
+            code: "protocol-unsupported-version",
+            expected: `protocol version ${REPLICATION_PROTOCOL_VERSION}`,
+            hint: "upgrade the peer before sending replicated bytes",
+            detail: {
+              receivedVersion: packet.version,
+              supportedVersion: REPLICATION_PROTOCOL_VERSION
+            }
+          })
+        };
+      return { error: invalid(reason) };
     }
-    return { batch };
+    return { packet };
   } catch {
-    return { reason: "payload is not valid JSON" };
+    return { error: invalid("payload is not valid JSON") };
   }
 }
-function encodeReplicationBatch(batch, limits) {
-  const bytes = new TextEncoder().encode(JSON.stringify(canonicalize(batch)));
-  const failure = validateLimits(batch, bytes, limits);
+function isDataPacket(packet) {
+  return packet.kind === "baseline" || packet.kind === "delta";
+}
+function encodeReplicationPacket(packet, limits) {
+  const reason = validatePacket(packet);
+  if (reason !== void 0) return err(invalid(reason));
+  const body = JSON.stringify(canonicalize(packet));
+  const bytes = new TextEncoder().encode(`${REPLICATION_PROTOCOL_PREFIX}
+${body}`);
+  const failure = isDataPacket(packet) ? validateLimits(packet, bytes, limits) : null;
   return failure ? err(failure) : ok(bytes);
 }
-function decodeReplicationBatch(bytes, limits) {
+function decodeReplicationPacket(bytes, limits) {
   if (bytes.byteLength > limits.maxMessageBytes)
     return err(limitError("maxMessageBytes", bytes.byteLength, limits.maxMessageBytes));
   const parsed = parse(bytes);
-  if ("reason" in parsed || parsed.batch.version !== REPLICATION_PROTOCOL_VERSION)
-    return err(
-      new NetError({
-        code: "decode-invalid-payload",
-        expected: `a version ${REPLICATION_PROTOCOL_VERSION} canonical replication batch`,
-        hint: "send bytes produced by the replication codec for the negotiated protocol",
-        detail: {
-          reason: "reason" in parsed ? parsed.reason : "batch protocol version does not match the decoder"
-        }
-      })
-    );
-  const failure = validateLimits(parsed.batch, bytes, limits);
-  return failure ? err(failure) : ok(parsed.batch);
+  if ("error" in parsed) return err(parsed.error);
+  const failure = isDataPacket(parsed.packet) ? validateLimits(parsed.packet, bytes, limits) : null;
+  return failure ? err(failure) : ok(parsed.packet);
 }
 var DEFAULT_REPLICATION_LIMITS = {
   maxMessageBytes: 64 * 1024,
@@ -474,9 +554,13 @@ var AuthorityCoordinator = class {
   #known = /* @__PURE__ */ new Map();
   #nextId = 1;
   #tick = 0;
-  constructor(world, profile) {
+  #epoch = 0;
+  #sequence = 0;
+  #sessionId;
+  constructor(world, profile, sessionId = 1) {
     this.#world = world;
     this.#profile = profile;
+    this.#sessionId = sessionId;
   }
   idFor(entity) {
     return this.#ids.get(entity) ?? 0;
@@ -487,6 +571,9 @@ var AuthorityCoordinator = class {
   publishFull() {
     return this.#publish(true);
   }
+  nextPublicationEpoch(forceFull = false) {
+    return forceFull && this.#tick > 0 ? this.#epoch + 1 : this.#epoch;
+  }
   #publish(forceFull) {
     const candidateIds = new Map(this.#ids);
     let candidateNextId = this.#nextId;
@@ -515,6 +602,14 @@ var AuthorityCoordinator = class {
       if (id !== void 0) current.set(entity, { id, components });
     }
     const full = forceFull || this.#tick === 0;
+    let nextEpoch = this.#epoch;
+    let nextSequence = this.#sequence;
+    if (forceFull && this.#tick > 0) {
+      nextEpoch += 1;
+      nextSequence = 0;
+    }
+    if (full && nextSequence === 0) nextSequence = 1;
+    else nextSequence += 1;
     const entities = [];
     for (const [entity, entry] of current) {
       const prior = this.#known.get(entity);
@@ -543,15 +638,27 @@ var AuthorityCoordinator = class {
     for (const [entity] of candidateIds) {
       if (!current.has(entity)) candidateIds.delete(entity);
     }
-    const batch = {
+    const packet = full ? {
       version: REPLICATION_PROTOCOL_VERSION,
+      kind: "baseline",
+      sessionId: this.#sessionId,
+      epoch: nextEpoch,
+      sequence: nextSequence,
+      fingerprint: this.#profile.fingerprint,
+      tick: this.#tick + 1,
+      entities
+    } : {
+      version: REPLICATION_PROTOCOL_VERSION,
+      kind: "delta",
+      sessionId: this.#sessionId,
+      epoch: nextEpoch,
+      sequence: nextSequence,
       fingerprint: this.#profile.fingerprint,
       tick: this.#tick + 1,
-      full,
       entities
     };
-    const encoded = encodeReplicationBatch(
-      batch,
+    const encoded = encodeReplicationPacket(
+      packet,
       this.#profile.limits ?? DEFAULT_REPLICATION_LIMITS
     );
     if (!encoded.ok) return err(encoded.error);
@@ -560,8 +667,10 @@ var AuthorityCoordinator = class {
     this.#known.clear();
     for (const [entity, known] of candidateKnown) this.#known.set(entity, known);
     this.#nextId = candidateNextId;
-    this.#tick = batch.tick;
-    return ok({ ...batch, bytes: encoded.value });
+    this.#tick = packet.tick;
+    this.#epoch = nextEpoch;
+    this.#sequence = nextSequence;
+    return ok({ ...packet, bytes: encoded.value });
   }
 };
 function createAuthorityCoordinator(world, profile) {
@@ -582,14 +691,15 @@ function validateHandshake(local, remote) {
 var ReplicaCoordinator = class {
   #world;
   #profile;
-  #endpoint;
   #entities = /* @__PURE__ */ new Map();
   #lastTick = 0;
+  #epoch = -1;
+  #lastSequence = 0;
+  #lastPacketOutcome = "accepted";
   #stopped = false;
-  constructor(world, profile, endpoint) {
+  constructor(world, profile, _endpoint) {
     this.#world = world;
     this.#profile = profile;
-    this.#endpoint = endpoint;
   }
   entityFor(id) {
     return this.#entities.get(id);
@@ -607,7 +717,6 @@ var ReplicaCoordinator = class {
     })).sort((a, b) => a.id - b.id);
   }
   disconnect() {
-    this.#endpoint?.close();
   }
   /** Remove the last replica baseline when the authority connection closes. */
   clear() {
@@ -620,13 +729,21 @@ var ReplicaCoordinator = class {
   get tick() {
     return this.#lastTick;
   }
+  /** Report the last accepted, duplicate, or stale-epoch packet decision. */
+  get lastPacketOutcome() {
+    return this.#lastPacketOutcome;
+  }
+  getPendingUnresolvedReferences() {
+    return 0;
+  }
   #entityReferences(value) {
     if (Array.isArray(value) || ArrayBuffer.isView(value)) {
       return Array.from(value);
     }
     return [];
   }
-  validate(batch) {
+  validate(packet) {
+    this.#lastPacketOutcome = "accepted";
     if (this.#stopped)
       return new NetError({
         code: "apply-invariant-failed",
@@ -634,22 +751,54 @@ var ReplicaCoordinator = class {
         hint: "create a new session after a fatal apply failure",
         detail: { reason: "replication stopped" }
       });
-    if (batch.fingerprint !== this.#profile.fingerprint)
+    if (packet.fingerprint !== this.#profile.fingerprint)
       return new NetError({
         code: "schema-invalid",
         expected: "a batch for the negotiated replication profile",
         hint: "complete handshake before applying replication bytes",
         detail: { component: "", reason: "fingerprint mismatch" }
       });
-    if (batch.tick <= this.#lastTick)
+    const newEpoch = packet.epoch > this.#epoch;
+    if (this.#epoch < 0 && packet.kind !== "baseline")
+      return new NetError({
+        code: "session-illegal-transition",
+        expected: "a baseline before any delta in a session epoch",
+        hint: "accept a complete authoritative baseline before applying deltas",
+        detail: { from: "connecting", to: packet.kind }
+      });
+    if (packet.epoch > this.#epoch && (packet.kind !== "baseline" || packet.sequence !== 1))
+      return new NetError({
+        code: "session-illegal-transition",
+        expected: "a sequence-one baseline at the start of a new epoch",
+        hint: "request a fresh baseline before applying the next delta",
+        detail: { from: "resyncing", to: packet.kind }
+      });
+    if (packet.epoch < this.#epoch) return null;
+    if (packet.kind === "baseline" && !newEpoch && this.#lastSequence >= 1) {
+      this.#lastPacketOutcome = "duplicate";
+      return null;
+    }
+    if (packet.kind === "delta" && packet.sequence <= this.#lastSequence) {
+      this.#lastPacketOutcome = "duplicate";
+      return null;
+    }
+    if (packet.kind === "delta" && packet.sequence !== this.#lastSequence + 1)
+      return new NetError({
+        code: "ordering-invalid-tick",
+        expected: "the next contiguous replication sequence",
+        hint: "request a fresh baseline when a sequence gap is detected",
+        detail: { receivedTick: packet.sequence, lastTick: this.#lastSequence }
+      });
+    if (!newEpoch && packet.tick <= this.#lastTick)
       return new NetError({
         code: "ordering-invalid-tick",
         expected: "a strictly monotonic authority tick",
         hint: "discard duplicate, stale, and out-of-order batches",
-        detail: { receivedTick: batch.tick, lastTick: this.#lastTick }
+        detail: { receivedTick: packet.tick, lastTick: this.#lastTick }
       });
     const batchIds = /* @__PURE__ */ new Set();
-    for (const record of batch.entities) {
+    const knownIds = newEpoch ? /* @__PURE__ */ new Set() : new Set(this.#entities.keys());
+    for (const record of packet.entities) {
       if (!Number.isSafeInteger(record.id) || record.id <= 0 || batchIds.has(record.id))
         return new NetError({
           code: "identity-invalid",
@@ -659,8 +808,8 @@ var ReplicaCoordinator = class {
         });
       batchIds.add(record.id);
     }
-    for (const record of batch.entities) {
-      if (record.kind === "despawn" && !this.#entities.has(record.id))
+    for (const record of packet.entities) {
+      if (record.kind === "despawn" && !knownIds.has(record.id))
         return new NetError({
           code: "identity-invalid",
           expected: "a known identity for despawn",
@@ -690,7 +839,7 @@ var ReplicaCoordinator = class {
           const kind = classifyEntityField(component, field);
           const refs = kind?.isArray ? this.#entityReferences(value) : kind ? [value] : [];
           for (const reference of refs)
-            if (reference !== null && (typeof reference !== "number" || reference === 0 || !this.#entities.has(reference) && !batchIds.has(reference)))
+            if (reference !== null && (typeof reference !== "number" || reference === 0 || !knownIds.has(reference) && !batchIds.has(reference)))
               return new NetError({
                 code: "remap-unresolved-reference",
                 expected: "every entity reference to resolve in the current or same batch",
@@ -702,17 +851,26 @@ var ReplicaCoordinator = class {
     }
     return null;
   }
-  apply(batch) {
-    const failure = this.validate(batch);
+  apply(packet) {
+    const failure = this.validate(packet);
     if (failure) {
-      this.disconnect();
       return err(failure);
     }
+    if (packet.epoch < this.#epoch) {
+      this.#lastPacketOutcome = "ignored-old-epoch";
+      return ok(void 0);
+    }
+    if (this.#lastPacketOutcome === "duplicate") return ok(void 0);
+    const replacingEpoch = packet.epoch > this.#epoch;
     try {
-      for (const record of batch.entities)
+      if (replacingEpoch) {
+        for (const entity of this.#entities.values()) this.#world.despawn(entity).unwrap();
+        this.#entities.clear();
+      }
+      for (const record of packet.entities)
         if (record.kind === "upsert" && !this.#entities.has(record.id))
           this.#entities.set(record.id, this.#world.spawn().unwrap());
-      for (const record of batch.entities)
+      for (const record of packet.entities)
         if (record.kind === "upsert") {
           const entity = this.#entities.get(record.id);
           if (entity === void 0) throw new Error(`missing allocated entity ${record.id}`);
@@ -747,14 +905,17 @@ var ReplicaCoordinator = class {
             if (!write.ok) throw write.error;
           }
         }
-      for (const record of batch.entities)
+      for (const record of packet.entities)
         if (record.kind === "despawn") {
           const entity = this.#entities.get(record.id);
           if (entity === void 0) throw new Error(`missing despawn entity ${record.id}`);
           this.#world.despawn(entity).unwrap();
           this.#entities.delete(record.id);
         }
-      this.#lastTick = batch.tick;
+      this.#epoch = packet.epoch;
+      this.#lastSequence = packet.sequence;
+      this.#lastTick = packet.tick;
+      this.#lastPacketOutcome = "accepted";
       return ok(void 0);
     } catch (cause) {
       this.#stopped = true;
@@ -772,51 +933,402 @@ var ReplicaCoordinator = class {
 function createReplicaCoordinator(world, profile, endpoint) {
   return new ReplicaCoordinator(world, profile, endpoint);
 }
-function applyReplicaBatch(replica, batch) {
-  return replica.apply(batch);
+function applyReplicationPacket(replica, packet) {
+  return replica.apply(packet);
 }
-function decodeAndApplyReplicaBatch(replica, bytes, limits) {
-  const decoded = decodeReplicationBatch(bytes, limits);
+function decodeAndApplyReplicationPacket(replica, bytes, limits) {
+  const decoded = decodeReplicationPacket(bytes, limits);
   if (!decoded.ok) {
-    replica.disconnect();
     return err(decoded.error);
   }
+  if (decoded.value.kind !== "baseline" && decoded.value.kind !== "delta") {
+    return err(
+      new NetError({
+        code: "decode-invalid-payload",
+        expected: "a baseline or delta replication packet",
+        hint: "apply only data packets through the replica coordinator",
+        detail: { reason: "control packet cannot be applied as ECS data" }
+      })
+    );
+  }
   return replica.apply(decoded.value);
 }
+var DEFAULT_NET_RECOVERY_POLICY = Object.freeze({
+  maxSessions: 64,
+  maxPendingPackets: 32,
+  ackTimeoutMs: 250,
+  maxPacketRetries: 3,
+  maxReconnectAttempts: 5,
+  reconnectDeadlineMs: 1e4,
+  reconnectDelaysMs: Object.freeze([0, 100, 200, 400, 800])
+});
+function policyError(field, reason) {
+  return new NetError({
+    code: "recovery-policy-invalid",
+    expected: "finite positive recovery policy bounds",
+    hint: "provide positive safe integers and a finite non-negative delay sequence",
+    detail: { field, reason }
+  });
+}
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function validateNetRecoveryPolicy(policy) {
+  const positiveFields = [
+    "maxSessions",
+    "maxPendingPackets",
+    "ackTimeoutMs",
+    "maxPacketRetries",
+    "maxReconnectAttempts",
+    "reconnectDeadlineMs"
+  ];
+  for (const field of positiveFields) {
+    if (!isPositiveSafeInteger(policy[field]))
+      return err(policyError(field, "value must be a positive safe integer"));
+  }
+  if (!Array.isArray(policy.reconnectDelaysMs) || policy.reconnectDelaysMs.length === 0 || policy.reconnectDelaysMs.some((delay) => !Number.isSafeInteger(delay) || delay < 0))
+    return err(
+      policyError("reconnectDelaysMs", "values must be a non-empty finite delay sequence")
+    );
+  return ok(void 0);
+}
+function resolveNetRecoveryPolicy(overrides = {}) {
+  const policy = {
+    ...DEFAULT_NET_RECOVERY_POLICY,
+    ...overrides,
+    reconnectDelaysMs: overrides.reconnectDelaysMs === void 0 ? DEFAULT_NET_RECOVERY_POLICY.reconnectDelaysMs : [...overrides.reconnectDelaysMs]
+  };
+  const valid = validateNetRecoveryPolicy(policy);
+  return valid.ok ? ok(Object.freeze(policy)) : err(valid.error);
+}
+function createSessionId(value) {
+  if (!isPositiveSafeInteger(value))
+    return err(
+      new NetError({
+        code: "recovery-policy-invalid",
+        expected: "a positive safe integer SessionId",
+        hint: "use the authority-issued application session identity",
+        detail: { field: "sessionId", reason: "SessionId must be a positive safe integer" }
+      })
+    );
+  return ok(value);
+}
+var LEGAL_TRANSITIONS = {
+  connecting: ["recovering", "resyncing", "failed", "retired"],
+  resyncing: ["active", "recovering", "failed", "retired"],
+  active: ["active", "recovering", "failed", "retired"],
+  recovering: ["recovering", "resyncing", "failed", "retired"],
+  failed: ["retired"],
+  retired: ["retired"]
+};
+function isLegalNetSessionTransition(from, to) {
+  return LEGAL_TRANSITIONS[from].includes(to);
+}
+function transitionNetSessionState(from, to) {
+  if (from.sessionId !== to.sessionId || !isLegalNetSessionTransition(from.kind, to.kind))
+    return err(
+      new NetError({
+        code: "session-illegal-transition",
+        expected: "a legal transition for the same SessionId",
+        hint: "wait for the current session state or retire the session before replacing it",
+        detail: { from: from.kind, to: to.kind }
+      })
+    );
+  return ok(to);
+}
+var RECOVERY_ERROR_CODES = [
+  "protocol-unsupported-version",
+  "session-illegal-transition",
+  "recovery-policy-invalid",
+  "recovery-rejected",
+  "recovery-exhausted"
+];
+
+// src/session/net-session.ts
+var defaultClock = {
+  now: () => Date.now(),
+  schedule: (delayMs, callback) => {
+    const id = globalThis.setTimeout(callback, delayMs);
+    return { cancel: () => globalThis.clearTimeout(id) };
+  }
+};
+function recoveryFailure(reason) {
+  return new NetError({
+    code: "recovery-rejected",
+    expected: "a recoverable NetSession lifecycle operation",
+    hint: "inspect the current snapshot and retire the session after terminal failure",
+    detail: { reason }
+  });
+}
+function initialState(sessionId, endpoint) {
+  return endpoint === void 0 ? { kind: "connecting", sessionId } : { kind: "resyncing", sessionId, epoch: 0 };
+}
 var NetSession = class {
   #endpoint;
+  #connector;
+  #clock;
+  #policy;
+  #sessionId;
   #peerIds = /* @__PURE__ */ new Set();
+  #sessionPeers = /* @__PURE__ */ new Map();
+  #announcedPeers = /* @__PURE__ */ new Set();
+  #sessionAnnounced = false;
   #rawMessages = [];
   #maxRawMessages;
   #authority;
   #pendingFullPeers = /* @__PURE__ */ new Set();
   #replica;
+  #state;
+  #lastError;
+  #epoch = 0;
+  #sequence = 0;
+  #acknowledgedSequence = 0;
+  #reconnectAttempts = 0;
+  #pendingConnect;
+  #retryTimer;
+  #ledger = /* @__PURE__ */ new Map();
+  #disposed = false;
   constructor(config) {
     this.#endpoint = config.endpoint;
+    this.#connector = config.connector;
+    this.#clock = config.clock ?? defaultClock;
     this.#maxRawMessages = config.maxRawMessages;
+    const resolvedSessionId = this.#resolveSessionId(config.sessionId);
+    this.#sessionId = resolvedSessionId.ok ? resolvedSessionId.value : 1;
+    const policy = resolveNetRecoveryPolicy(config.recovery);
+    this.#policy = policy.ok ? policy.value : DEFAULT_NET_RECOVERY_POLICY;
+    this.#state = initialState(this.#sessionId, this.#endpoint);
+    if (!resolvedSessionId.ok) this.#setFailure(resolvedSessionId.error);
+    else if (!policy.ok) this.#setFailure(policy.error);
+  }
+  #resolveSessionId(value) {
+    return createSessionId(value ?? 1);
+  }
+  #setState(next) {
+    const transition = transitionNetSessionState(this.#state, next);
+    if (transition.ok) {
+      this.#state = transition.value;
+      return;
+    }
+    this.#setFailure(transition.error);
+  }
+  #setFailure(failure) {
+    this.#lastError = failure;
+    if (this.#state.kind !== "failed" && this.#state.kind !== "retired")
+      this.#setState({ kind: "failed", sessionId: this.#sessionId, error: failure });
+    this.#authority = void 0;
+    this.#peerIds.clear();
+    this.#sessionPeers.clear();
+    this.#announcedPeers.clear();
+    this.#sessionAnnounced = false;
+    this.#pendingFullPeers.clear();
+    this.#rawMessages = [];
+    this.#clearRecoveryWork();
+    this.#endpoint?.close();
+  }
+  #clearRecoveryWork() {
+    this.#retryTimer?.cancel();
+    this.#retryTimer = void 0;
+    this.#pendingConnect?.abort();
+    this.#pendingConnect = void 0;
+    this.#ledger.clear();
+  }
+  #beginRecovery() {
+    const previousEndpoint = this.#endpoint;
+    this.#endpoint = void 0;
+    previousEndpoint?.close();
+    if (this.#state.kind === "connecting" || this.#state.kind === "active" || this.#state.kind === "resyncing")
+      this.#setState({
+        kind: "recovering",
+        sessionId: this.#sessionId,
+        epoch: this.#epoch,
+        attempt: 0
+      });
+    this.#ledger.clear();
+    this.#sequence = 0;
+    this.#acknowledgedSequence = 0;
+    this.#peerIds.clear();
+    this.#sessionPeers.clear();
+    this.#announcedPeers.clear();
+    this.#sessionAnnounced = false;
+    this.#pendingFullPeers.clear();
+    this.#rawMessages = [];
+  }
+  #attemptRecovery() {
+    if (this.#disposed || this.#state.kind !== "recovering" || this.#pendingConnect) return;
+    if (this.#reconnectAttempts >= this.#policy.maxReconnectAttempts) {
+      this.#setFailure(
+        new NetError({
+          code: "recovery-exhausted",
+          expected: "reconnect attempts within the configured finite bound",
+          hint: "inspect the failure and create a new session after exhaustion",
+          detail: {
+            attempts: this.#reconnectAttempts,
+            maxAttempts: this.#policy.maxReconnectAttempts
+          }
+        })
+      );
+      return;
+    }
+    this.#reconnectAttempts += 1;
+    this.#setState({
+      kind: "recovering",
+      sessionId: this.#sessionId,
+      epoch: this.#epoch,
+      attempt: this.#reconnectAttempts
+    });
+    if (this.#connector === void 0) {
+      if (this.#reconnectAttempts >= this.#policy.maxReconnectAttempts) this.#attemptRecovery();
+      return;
+    }
+    const controller = new AbortController();
+    this.#pendingConnect = { abort: () => controller.abort() };
+    void this.#connector.connect(controller.signal).then(
+      (result) => this.#connected(result),
+      (cause) => this.#connectFailed(cause)
+    );
+  }
+  #connected(result) {
+    this.#pendingConnect = void 0;
+    if (this.#disposed || this.#state.kind !== "recovering") {
+      if (result.ok) result.value.close();
+      return;
+    }
+    if (!result.ok) {
+      this.#connectFailed(result.error);
+      return;
+    }
+    this.#endpoint?.close();
+    this.#endpoint = result.value;
+    this.#lastError = void 0;
+    this.#epoch += 1;
+    this.#sequence = 0;
+    this.#acknowledgedSequence = 0;
+    this.#ledger.clear();
+    this.#setState({ kind: "resyncing", sessionId: this.#sessionId, epoch: this.#epoch });
+  }
+  #connectFailed(cause) {
+    this.#pendingConnect = void 0;
+    if (this.#disposed || this.#state.kind !== "recovering") return;
+    const failure = cause instanceof NetError ? cause : isEndpointError(cause) ? cause : recoveryFailure("connector attempt failed");
+    if (this.#reconnectAttempts >= this.#policy.maxReconnectAttempts) {
+      this.#setFailure(
+        new NetError({
+          code: "recovery-exhausted",
+          expected: "reconnect attempts within the configured finite bound",
+          hint: "inspect the endpoint failure and create a new session after exhaustion",
+          detail: {
+            attempts: this.#reconnectAttempts,
+            maxAttempts: this.#policy.maxReconnectAttempts
+          }
+        })
+      );
+      return;
+    }
+    this.#lastError = failure;
+    this.advanceRecovery();
+  }
+  #handleAck(packet) {
+    if (packet.sessionId !== this.#sessionId && !this.#sessionPeers.has(packet.sessionId))
+      return err(
+        new NetError({
+          code: "recovery-rejected",
+          expected: "an ACK for the current SessionId",
+          hint: "discard ACKs from another logical session",
+          detail: { reason: "ACK SessionId does not match the current session" }
+        })
+      );
+    if (packet.epoch !== this.#epoch || packet.acknowledgedSequence > this.#sequence)
+      return ok(void 0);
+    if (packet.acknowledgedSequence <= this.#acknowledgedSequence) return ok(void 0);
+    this.#acknowledgedSequence = packet.acknowledgedSequence;
+    for (const sequence of this.#ledger.keys())
+      if (sequence <= packet.acknowledgedSequence) this.#ledger.delete(sequence);
+    return ok(void 0);
+  }
+  #receiveMessage(peerId, data, errors) {
+    if (this.#state.kind === "recovering" || this.#state.kind === "failed" || this.#state.kind === "retired")
+      return;
+    const limits = this.#replica?.limits ?? DEFAULT_REPLICATION_LIMITS;
+    const decoded = decodeReplicationPacket(data, limits);
+    if (!decoded.ok) {
+      if (this.#replica === void 0) {
+        this.#queueRawMessage(peerId, data);
+        return;
+      }
+      errors.push(decoded.error);
+      this.#setFailure(decoded.error);
+      return;
+    }
+    if (decoded.value.kind === "session-open" || decoded.value.kind === "session-resume") {
+      this.#bindSession(decoded.value.sessionId, peerId);
+      return;
+    }
+    if (decoded.value.kind === "ack") {
+      const handled = this.#handleAck(decoded.value);
+      if (!handled.ok) {
+        errors.push(handled.error);
+        this.#setFailure(handled.error);
+      }
+      return;
+    }
+    if (decoded.value.kind !== "baseline" && decoded.value.kind !== "delta") {
+      if (decoded.value.kind === "rejection") {
+        const failure = recoveryFailure(
+          `peer rejected ${decoded.value.rejectedKind}: ${decoded.value.reason}`
+        );
+        errors.push(failure);
+        this.#setFailure(failure);
+      }
+      return;
+    }
+    if (this.#replica === void 0) {
+      this.#queueRawMessage(peerId, data);
+      return;
+    }
+    const applied = decodeAndApplyReplicationPacket(
+      this.#replica.coordinator,
+      data,
+      this.#replica.limits
+    );
+    if (!applied.ok) {
+      errors.push(applied.error);
+      this.#setFailure(applied.error);
+      return;
+    }
+    const packetOutcome = this.#replica.coordinator.lastPacketOutcome;
+    if (packetOutcome === "accepted") {
+      this.#epoch = decoded.value.epoch;
+      this.#sequence = decoded.value.sequence;
+      this.#acknowledgedSequence = decoded.value.sequence;
+      this.#setState({
+        kind: "active",
+        sessionId: this.#sessionId,
+        epoch: this.#epoch,
+        sequence: this.#sequence
+      });
+    }
+    if (packetOutcome === "accepted" || packetOutcome === "duplicate")
+      this.#sendReplicationAck(peerId, decoded.value);
   }
   receiveEvents() {
     const errors = [];
-    for (const event of this.#endpoint.poll()) {
+    if (this.#disposed || this.#state.kind === "failed" || this.#state.kind === "retired")
+      return errors;
+    for (const event of this.#endpoint?.poll() ?? []) {
       if (event.kind === "peer-connected") {
         this.#peerIds.add(event.peerId);
+        if (this.#replica !== void 0) this.#bindSession(this.#sessionId, event.peerId);
+        else this.#bindSession(this.#sessionForPeer(event.peerId), event.peerId);
         this.#pendingFullPeers.add(event.peerId);
       } else if (event.kind === "peer-disconnected") {
-        this.#peerIds.delete(event.peerId);
-        this.#pendingFullPeers.delete(event.peerId);
-        this.#replica?.coordinator.clear();
-      } else {
+        this.#forgetPeer(event.peerId);
         if (this.#replica !== void 0) {
-          const result = decodeAndApplyReplicaBatch(
-            this.#replica.coordinator,
-            event.data,
-            this.#replica.limits
-          );
-          if (!result.ok) errors.push(result.error);
-        } else if (this.#rawMessages.length < this.#maxRawMessages) {
-          this.#rawMessages.push({ peerId: event.peerId, data: event.data });
+          this.#replica.coordinator.clear();
+          this.#beginRecovery();
+          this.advanceRecovery();
         }
-      }
+      } else this.#receiveMessage(event.peerId, event.data, errors);
     }
     return errors;
   }
@@ -827,9 +1339,78 @@ var NetSession = class {
     const peerIds = [...this.#peerIds].sort((left, right) => left - right);
     return { peerIds, connected: peerIds.length > 0 };
   }
+  getSessionSnapshot() {
+    const sessionIds = [...this.#sessionPeers.keys()].sort((left, right) => left - right);
+    return { sessionIds, connected: sessionIds.length > 0 };
+  }
+  /** Return lifecycle, epoch, sequence, ledger, and owned-resource evidence. */
+  getRecoverySnapshot() {
+    return {
+      sessionId: this.#sessionId,
+      state: this.#state,
+      pendingPackets: this.#ledger.size,
+      maxPendingPackets: this.#policy.maxPendingPackets,
+      acknowledgedSequence: this.#acknowledgedSequence,
+      reconnectAttempts: this.#reconnectAttempts,
+      epoch: this.#epoch,
+      sequence: this.#sequence,
+      ...this.#lastError === void 0 ? {} : { lastError: this.#lastError },
+      ownedResources: {
+        pendingConnects: this.#pendingConnect === void 0 ? 0 : 1,
+        timers: this.#retryTimer === void 0 ? 0 : 1,
+        ledgers: this.#ledger.size === 0 ? 0 : 1,
+        callbacks: 0
+      }
+    };
+  }
+  getResourceSnapshot() {
+    return this.getRecoverySnapshot().ownedResources;
+  }
+  recover() {
+    if (this.#state.kind === "retired" || this.#state.kind === "failed")
+      return { kind: "retired", sessionId: this.#sessionId };
+    if (this.#state.kind === "recovering")
+      return { kind: "already-recovering", sessionId: this.#sessionId };
+    this.#beginRecovery();
+    return { kind: "started", sessionId: this.#sessionId };
+  }
+  advanceRecovery() {
+    if (this.#state.kind !== "recovering") return;
+    const delay = this.#policy.reconnectDelaysMs[Math.min(this.#reconnectAttempts, this.#policy.reconnectDelaysMs.length - 1)];
+    if (delay === void 0 || delay === 0) this.#attemptRecovery();
+    else {
+      this.#retryTimer?.cancel();
+      this.#retryTimer = this.#clock.schedule(delay, () => {
+        this.#retryTimer = void 0;
+        this.#attemptRecovery();
+      });
+    }
+  }
   sendRaw(peerId, data) {
-    const result = this.#endpoint.send(peerId, data);
-    return result.ok ? ok(void 0) : err(result.error);
+    if (this.#state.kind !== "active") return err(recoveryFailure("session is not active"));
+    return this.#sendToPeer(peerId, data);
+  }
+  /** Send one application command through the current replica attachment. */
+  sendToAuthority(sessionId, data) {
+    if (sessionId !== this.#sessionId)
+      return err(recoveryFailure("session id does not belong to this NetSession"));
+    if (this.#state.kind === "recovering" || this.#state.kind === "failed" || this.#state.kind === "retired")
+      return err(recoveryFailure("session is not connected to the authority"));
+    const peerId = this.#peerForSession(sessionId);
+    if (peerId === void 0) return err(recoveryFailure("authority peer is not connected"));
+    if (this.#replica !== void 0) {
+      const announced = this.#announceSession(peerId);
+      if (!announced.ok) return announced;
+    }
+    return this.#sendToPeer(peerId, data);
+  }
+  /** Send one application message to an authority-owned logical session. */
+  sendToSession(sessionId, data) {
+    if (this.#state.kind === "failed" || this.#state.kind === "retired")
+      return err(recoveryFailure("session is not connected to the authority"));
+    const peerId = this.#peerForSession(sessionId);
+    if (peerId === void 0) return err(recoveryFailure("logical session is not connected"));
+    return this.#sendToPeer(peerId, data);
   }
   attachAuthority(authority) {
     this.#authority = authority;
@@ -837,30 +1418,183 @@ var NetSession = class {
   requestFullBaseline(peerId) {
     if (this.#peerIds.has(peerId)) this.#pendingFullPeers.add(peerId);
   }
+  requestFullBaselineForSession(sessionId) {
+    const peerId = this.#sessionPeers.get(sessionId);
+    if (peerId !== void 0) this.requestFullBaseline(peerId);
+  }
   attachReplica(coordinator, limits) {
     this.#replica = { coordinator, limits };
   }
+  #ledgerBoundError() {
+    return new NetError({
+      code: "recovery-rejected",
+      expected: "published packets within the configured finite ACK bound",
+      hint: "wait for a cumulative ACK before publishing more packets",
+      detail: { reason: "ACK ledger bound reached" }
+    });
+  }
+  #ensurePublicationCapacity(expectedEpoch) {
+    if (expectedEpoch === this.#epoch && this.#ledger.size >= this.#policy.maxPendingPackets)
+      return err(this.#ledgerBoundError());
+    return ok(void 0);
+  }
+  #reservePublished(packet) {
+    if (packet.epoch !== this.#epoch) {
+      this.#ledger.clear();
+      this.#acknowledgedSequence = 0;
+      this.#epoch = packet.epoch;
+    }
+    if (this.#ledger.size >= this.#policy.maxPendingPackets && !this.#ledger.has(packet.sequence))
+      return err(this.#ledgerBoundError());
+    this.#sequence = packet.sequence;
+    this.#ledger.set(packet.sequence, packet.bytes);
+    return ok(void 0);
+  }
+  #sendPublished(packet, peerIds) {
+    const reserved = this.#reservePublished(packet);
+    if (!reserved.ok) return reserved;
+    if (this.#endpoint === void 0) return err(recoveryFailure("session has no endpoint"));
+    let delivered = false;
+    for (const peerId of peerIds) {
+      const sent = this.#endpoint.send(peerId, packet.bytes);
+      if (!sent.ok) {
+        if (sent.error.code === "connection-closed") {
+          this.#forgetPeer(peerId);
+          continue;
+        }
+        this.#ledger.delete(packet.sequence);
+        return err(sent.error);
+      }
+      delivered = true;
+    }
+    if (!delivered) this.#ledger.delete(packet.sequence);
+    return ok(void 0);
+  }
   publish() {
-    if (this.#authority === void 0) return ok(void 0);
+    if (this.#authority === void 0 || this.#endpoint === void 0 || this.#peerIds.size === 0)
+      return ok(void 0);
     if (this.#pendingFullPeers.size > 0) {
+      const capacity2 = this.#ensurePublicationCapacity(this.#authority.nextPublicationEpoch(true));
+      if (!capacity2.ok) return capacity2;
       const published2 = this.#authority.publishFull();
       if (!published2.ok) return err(published2.error);
-      for (const peerId of this.#pendingFullPeers) {
-        if (this.#peerIds.has(peerId)) {
-          const sent = this.#endpoint.send(peerId, published2.value.bytes);
-          if (!sent.ok) return err(sent.error);
-        }
-      }
+      const sent2 = this.#sendPublished(published2.value, [...this.#peerIds]);
+      if (!sent2.ok) return err(sent2.error);
       this.#pendingFullPeers.clear();
+      return ok(void 0);
     }
+    const capacity = this.#ensurePublicationCapacity(this.#authority.nextPublicationEpoch());
+    if (!capacity.ok) return capacity;
     const published = this.#authority.publish();
     if (!published.ok) return err(published.error);
-    for (const peerId of this.#peerIds) {
-      const sent = this.#endpoint.send(peerId, published.value.bytes);
-      if (!sent.ok) return err(sent.error);
+    const sent = this.#sendPublished(published.value, [...this.#peerIds]);
+    if (!sent.ok) return err(sent.error);
+    return ok(void 0);
+  }
+  dispose() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.#clearRecoveryWork();
+    this.#endpoint?.close();
+    this.#endpoint = void 0;
+    this.#replica?.coordinator.clear();
+    this.#replica = void 0;
+    this.#authority = void 0;
+    this.#peerIds.clear();
+    this.#sessionPeers.clear();
+    this.#announcedPeers.clear();
+    this.#sessionAnnounced = false;
+    this.#pendingFullPeers.clear();
+    this.#rawMessages = [];
+    if (this.#state.kind !== "retired")
+      this.#setState({ kind: "retired", sessionId: this.#sessionId, reason: "disposed" });
+  }
+  #queueRawMessage(peerId, data) {
+    if (this.#rawMessages.length >= this.#maxRawMessages) return;
+    this.#rawMessages.push({
+      peerId,
+      sessionId: this.#sessionForPeer(peerId),
+      data: new Uint8Array(data)
+    });
+  }
+  #sessionForPeer(peerId) {
+    for (const [sessionId2, mappedPeerId] of this.#sessionPeers)
+      if (mappedPeerId === peerId) return sessionId2;
+    if (this.#replica !== void 0) {
+      this.#bindSession(this.#sessionId, peerId);
+      return this.#sessionId;
     }
+    const created = createSessionId(peerId);
+    const sessionId = created.ok ? created.value : this.#sessionId;
+    this.#bindSession(sessionId, peerId);
+    return sessionId;
+  }
+  #bindSession(sessionId, peerId) {
+    for (const [mappedSessionId, mappedPeerId] of this.#sessionPeers)
+      if (mappedSessionId === sessionId || mappedPeerId === peerId)
+        this.#sessionPeers.delete(mappedSessionId);
+    this.#sessionPeers.set(sessionId, peerId);
+  }
+  #forgetPeer(peerId) {
+    this.#peerIds.delete(peerId);
+    for (const [sessionId, mappedPeerId] of this.#sessionPeers)
+      if (mappedPeerId === peerId) this.#sessionPeers.delete(sessionId);
+    this.#announcedPeers.delete(peerId);
+    this.#pendingFullPeers.delete(peerId);
+  }
+  #peerForSession(sessionId) {
+    const mapped = this.#sessionPeers.get(sessionId);
+    if (mapped !== void 0 && this.#peerIds.has(mapped)) return mapped;
+    if (this.#replica !== void 0 && this.#peerIds.size === 1) {
+      const peerId = [...this.#peerIds][0];
+      if (peerId !== void 0) {
+        this.#bindSession(sessionId, peerId);
+        return peerId;
+      }
+    }
+    return void 0;
+  }
+  #announceSession(peerId) {
+    if (this.#announcedPeers.has(peerId)) return ok(void 0);
+    const packet = {
+      version: 2,
+      kind: this.#sessionAnnounced ? "session-resume" : "session-open",
+      sessionId: this.#sessionId,
+      epoch: this.#epoch,
+      sequence: 0
+    };
+    const encoded = encodeReplicationPacket(packet, DEFAULT_REPLICATION_LIMITS);
+    if (!encoded.ok) return err(encoded.error);
+    const sent = this.#sendToPeer(peerId, encoded.value);
+    if (!sent.ok) return sent;
+    this.#announcedPeers.add(peerId);
+    this.#sessionAnnounced = true;
     return ok(void 0);
   }
+  #sendToPeer(peerId, data) {
+    const result = this.#endpoint?.send(peerId, data);
+    if (result === void 0) return err(recoveryFailure("session has no endpoint"));
+    return result.ok ? ok(void 0) : err(result.error);
+  }
+  /** ACK accepted data at the session boundary; consumers should not reimplement this wire step. */
+  #sendReplicationAck(peerId, packet) {
+    const encoded = encodeReplicationPacket(
+      {
+        version: 2,
+        kind: "ack",
+        sessionId: packet.sessionId,
+        epoch: packet.epoch,
+        acknowledgedSequence: packet.sequence
+      },
+      DEFAULT_REPLICATION_LIMITS
+    );
+    if (!encoded.ok) {
+      this.#setFailure(encoded.error);
+      return;
+    }
+    const sent = this.#sendToPeer(peerId, encoded.value);
+    if (!sent.ok) this.#lastError = sent.error;
+  }
 };
 function netPlugin(config) {
   return {
@@ -869,12 +1603,23 @@ function netPlugin(config) {
     apply(ctx) {
       const world = ctx.world;
       const session = new NetSession({
-        endpoint: config.endpoint,
+        ...config.endpoint === void 0 ? {} : { endpoint: config.endpoint },
+        ...config.connector === void 0 ? {} : { connector: config.connector },
+        ...config.sessionId === void 0 ? {} : { sessionId: config.sessionId },
+        ...config.recovery === void 0 ? {} : { recovery: config.recovery },
+        ...config.clock === void 0 ? {} : { clock: config.clock },
         maxRawMessages: config.maxRawMessages ?? 256
       });
       ctx.effect(() => {
         world.insertResource("net-session", session);
-        return () => world.removeResource("net-session");
+        if (config.connector !== void 0 && config.endpoint === void 0) {
+          session.recover();
+          session.advanceRecovery();
+        }
+        return () => {
+          session.dispose();
+          world.removeResource("net-session");
+        };
       }, "net/session-resource");
       ctx.effect(() => {
         world.addSystem(Update, {
@@ -898,6 +1643,6 @@ function netPlugin(config) {
   };
 }
 
-export { AuthorityCoordinator, ENDPOINT_ERROR_HINTS, ENDPOINT_EXPECTED, EndpointError, NetError, NetSession, ReplicaCoordinator, applyReplicaBatch, createAuthorityCoordinator, createMemoryEndpointPair, createMemoryEndpointPairWithController, createReplicaCoordinator, decodeAndApplyReplicaBatch, defineReplication, isEndpointError, netPlugin, validateHandshake };
+export { AuthorityCoordinator, DEFAULT_NET_RECOVERY_POLICY, DEFAULT_REPLICATION_LIMITS, ENDPOINT_ERROR_HINTS, ENDPOINT_EXPECTED, EndpointError, NetError, NetSession, RECOVERY_ERROR_CODES, REPLICATION_PROTOCOL_PREFIX, REPLICATION_PROTOCOL_VERSION, ReplicaCoordinator, applyReplicationPacket, createAuthorityCoordinator, createMemoryEndpointConnector, createMemoryEndpointPair, createMemoryEndpointPairWithController, createReplicaCoordinator, createSessionId, decodeAndApplyReplicationPacket, decodeReplicationPacket, defineReplication, encodeReplicationPacket, isEndpointError, isLegalNetSessionTransition, netPlugin, resolveNetRecoveryPolicy, transitionNetSessionState, validateHandshake, validateNetRecoveryPolicy };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map