@forgeax/engine-net 0.1.2

package/dist/index.mjs

@@ -0,0 +1,903 @@
+import { err, ok } from '@forgeax/engine-types';
+import { validateProfileComponents, projectComponentData, classifyEntityField } from '@forgeax/engine-ecs/externalization';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { Update, FixedUpdate } from '@forgeax/engine-ecs';
+
+// src/endpoint/errors.ts
+var EndpointErrorClass = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(args) {
+    let suffix = "";
+    if (args.code === "peer-not-found") {
+      const d = args.detail;
+      suffix = ` (peerId=${d.peerId})`;
+    } else if (args.code === "connection-closed") {
+      const d = args.detail;
+      suffix = ` (peerId=${d.peerId})`;
+    } else if (args.code === "send-failed") {
+      const d = args.detail;
+      suffix = ` (peerId=${d.peerId}, cause=${d.cause})`;
+    } else if (args.code === "already-closed") {
+      const d = args.detail;
+      suffix = ` (cause=${d.cause})`;
+    } else if (args.code === "connection-failed") {
+      const d = args.detail;
+      suffix = ` (address=${d.address}, cause=${d.cause})`;
+    }
+    super(`[EndpointError ${args.code}] expected: ${args.expected}; hint: ${args.hint}${suffix}`);
+    this.name = "EndpointError";
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+};
+var EndpointError = EndpointErrorClass;
+var endpointErrorPolicy = {
+  "peer-not-found": {
+    expected: "the target peer must exist in the current connection set",
+    hint: "verify the PeerId is from a connect event; check that the peer has not disconnected"
+  },
+  "connection-closed": {
+    expected: "the peer connection must be alive for the operation",
+    hint: "the peer disconnected; poll for a disconnect event and handle the lifecycle"
+  },
+  "send-failed": {
+    expected: "message bytes must be delivered to the target peer or the connection must fail",
+    hint: "the memory connection is broken; the peer may have disconnected or the buffer is full"
+  },
+  "already-closed": {
+    expected: "the endpoint must be open for any operation",
+    hint: "the endpoint is closed; create a new endpoint pair for further communication"
+  },
+  "connection-failed": {
+    expected: "the endpoint factory must successfully establish a connection or bind to the listen address",
+    hint: "the initial connection or bind failed; verify the address is reachable and the port is not in use, then retry"
+  }
+};
+var ENDPOINT_EXPECTED = Object.fromEntries(
+  Object.entries(endpointErrorPolicy).map(([code, policy]) => [code, policy.expected])
+);
+var ENDPOINT_ERROR_HINTS = Object.fromEntries(
+  Object.entries(endpointErrorPolicy).map(([code, policy]) => [code, policy.hint])
+);
+function isEndpointError(err8) {
+  return err8 instanceof EndpointErrorClass;
+}
+var MemoryEndpoint = class {
+  _peerId;
+  _remote = null;
+  _closed = false;
+  _remoteConnected = false;
+  _incoming = [];
+  _delayed = [];
+  _state = { delayNext: false, duplicateNext: false, malformNext: false };
+  constructor(peerId) {
+    this._peerId = peerId;
+  }
+  poll() {
+    if (this._closed) return [];
+    const events = this._incoming.splice(0);
+    this._incoming = this._delayed.splice(0);
+    return events;
+  }
+  send(peerId, data) {
+    if (this._closed) {
+      return err(
+        new EndpointError({
+          code: "already-closed",
+          expected: ENDPOINT_EXPECTED["already-closed"],
+          hint: ENDPOINT_ERROR_HINTS["already-closed"],
+          detail: { cause: "endpoint is closed" }
+        })
+      );
+    }
+    if (!this._remote || this._remote._peerId !== peerId) {
+      return err(
+        new EndpointError({
+          code: "peer-not-found",
+          expected: ENDPOINT_EXPECTED["peer-not-found"],
+          hint: ENDPOINT_ERROR_HINTS["peer-not-found"],
+          detail: { peerId }
+        })
+      );
+    }
+    if (!this._remoteConnected) {
+      return err(
+        new EndpointError({
+          code: "connection-closed",
+          expected: ENDPOINT_EXPECTED["connection-closed"],
+          hint: ENDPOINT_ERROR_HINTS["connection-closed"],
+          detail: { peerId }
+        })
+      );
+    }
+    const deliver = (bytes) => {
+      if (this._state.delayNext) {
+        this._remote?._delayed.push({ kind: "message", peerId: this._peerId, data: bytes });
+        this._state.delayNext = false;
+      } else {
+        this._remote?._incoming.push({ kind: "message", peerId: this._peerId, data: bytes });
+      }
+    };
+    if (this._state.malformNext) {
+      const corrupted = new Uint8Array(data);
+      if (corrupted.length > 0) {
+        const firstByte = corrupted[0];
+        if (firstByte !== void 0) corrupted[0] = firstByte ^ 255;
+      }
+      deliver(corrupted);
+      this._state.malformNext = false;
+    } else {
+      deliver(data);
+      if (this._state.duplicateNext) {
+        this._state.duplicateNext = false;
+        if (this._state.delayNext) {
+          this._remote?._delayed.push({ kind: "message", peerId: this._peerId, data });
+          this._state.delayNext = false;
+        } else {
+          this._remote?._incoming.push({ kind: "message", peerId: this._peerId, data });
+        }
+      }
+    }
+    return ok(void 0);
+  }
+  close() {
+    if (this._closed) {
+      return err(
+        new EndpointError({
+          code: "already-closed",
+          expected: ENDPOINT_EXPECTED["already-closed"],
+          hint: ENDPOINT_ERROR_HINTS["already-closed"],
+          detail: { cause: "endpoint is already closed" }
+        })
+      );
+    }
+    this._closed = true;
+    this._remoteConnected = false;
+    if (this._remote && !this._remote._closed) {
+      this._remote._remoteConnected = false;
+      this._remote._incoming.push({ kind: "peer-disconnected", peerId: this._peerId });
+    }
+    return ok(void 0);
+  }
+  _forceDisconnect() {
+    if (this._remote && !this._remote._closed) {
+      this._remote._remoteConnected = false;
+      this._remote._incoming.push({ kind: "peer-disconnected", peerId: this._peerId });
+    }
+    this._remoteConnected = false;
+  }
+};
+function createMemoryEndpointPair() {
+  const epA = new MemoryEndpoint(1);
+  const epB = new MemoryEndpoint(2);
+  epA._remote = epB;
+  epB._remote = epA;
+  epA._remoteConnected = true;
+  epB._remoteConnected = true;
+  epA._incoming.push({ kind: "peer-connected", peerId: 2 });
+  epB._incoming.push({ kind: "peer-connected", peerId: 1 });
+  return [epA, epB];
+}
+function createMemoryEndpointPairWithController() {
+  const [epA, epB] = createMemoryEndpointPair();
+  const controller = {
+    delayNextDelivery(_ms) {
+      epA._state.delayNext = true;
+    },
+    duplicateNextDelivery() {
+      epA._state.duplicateNext = true;
+    },
+    malformNextDelivery() {
+      epA._state.malformNext = true;
+    },
+    disconnectPeer(endpoint) {
+      endpoint._forceDisconnect();
+    }
+  };
+  return { endpoints: [epA, epB], controller };
+}
+
+// src/replication/constants.ts
+var REPLICATION_PROTOCOL_VERSION = 1;
+
+// src/replication/errors.ts
+var NetErrorClass = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(args) {
+    super(`[NetError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = "NetError";
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+};
+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,
+  Int8Array,
+  Int16Array,
+  Int32Array,
+  Uint8Array,
+  Uint8ClampedArray,
+  Uint16Array,
+  Uint32Array
+};
+function typedArrayName(value) {
+  for (const [name, typedArrayConstructor] of Object.entries(TYPED_ARRAYS)) {
+    if (value instanceof typedArrayConstructor) return name;
+  }
+  return void 0;
+}
+function canonicalize(value) {
+  const name = typedArrayName(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") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])])
+    );
+  }
+  return value;
+}
+function reviveTypedArrays(value) {
+  if (Array.isArray(value)) {
+    const values = [];
+    for (const item of value) {
+      const revived2 = reviveTypedArrays(item);
+      if ("reason" in revived2) return revived2;
+      values.push(revived2.value);
+    }
+    return { value: values };
+  }
+  if (value === null || typeof value !== "object") return { value };
+  const record = value;
+  if ("$typedArray" in record || "values" 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];
+    if (typedArrayConstructor === void 0 || record.values.some((item) => typeof item !== "number"))
+      return { reason: "typed-array tag contains an unsupported type or non-numeric value" };
+    return { value: new typedArrayConstructor(record.values) };
+  }
+  const revived = {};
+  for (const [key, item] of Object.entries(record)) {
+    const nested = reviveTypedArrays(item);
+    if ("reason" in nested) return nested;
+    revived[key] = nested.value;
+  }
+  return { value: revived };
+}
+function limitError(limit, actual, maximum) {
+  return new NetError({
+    code: "decode-limit-exceeded",
+    expected: `${limit} must not exceed ${maximum}`,
+    hint: "reduce the replicated payload or configure matching declared limits",
+    detail: { limit, actual, maximum }
+  });
+}
+function validateLimits(batch, 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);
+  let operations = 0;
+  const visit = (value) => {
+    if (typeof value === "string" && new TextEncoder().encode(value).byteLength > limits.maxStringBytes)
+      return limitError(
+        "maxStringBytes",
+        new TextEncoder().encode(value).byteLength,
+        limits.maxStringBytes
+      );
+    const typedArray = typedArrayName(value);
+    if (typedArray !== void 0) {
+      const contents = value;
+      if (contents.byteLength > limits.maxBufferBytes)
+        return limitError("maxBufferBytes", contents.byteLength, limits.maxBufferBytes);
+      if (contents.length > limits.maxArrayElements)
+        return limitError("maxArrayElements", contents.length, limits.maxArrayElements);
+      return null;
+    }
+    if (Array.isArray(value)) {
+      if (value.length > limits.maxArrayElements)
+        return limitError("maxArrayElements", value.length, limits.maxArrayElements);
+      for (const item of value) {
+        const problem = visit(item);
+        if (problem) return problem;
+      }
+    }
+    if (value !== null && typeof value === "object" && !(value instanceof Uint8Array))
+      for (const item of Object.values(value)) {
+        const problem = visit(item);
+        if (problem) return problem;
+      }
+    return null;
+  };
+  for (const entity of batch.entities) {
+    operations += entity.components.length;
+    for (const component of entity.components) {
+      const problem = visit(component.data);
+      if (problem) return problem;
+    }
+  }
+  return operations > limits.maxComponentOperations ? limitError("maxComponentOperations", operations, limits.maxComponentOperations) : null;
+}
+function parse(bytes) {
+  try {
+    const decoded = JSON.parse(new TextDecoder().decode(bytes));
+    const revived = reviveTypedArrays(decoded);
+    if ("reason" in revived) return revived;
+    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 { batch };
+  } catch {
+    return { reason: "payload is not valid JSON" };
+  }
+}
+function encodeReplicationBatch(batch, limits) {
+  const bytes = new TextEncoder().encode(JSON.stringify(canonicalize(batch)));
+  const failure = validateLimits(batch, bytes, limits);
+  return failure ? err(failure) : ok(bytes);
+}
+function decodeReplicationBatch(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);
+}
+var DEFAULT_REPLICATION_LIMITS = {
+  maxMessageBytes: 64 * 1024,
+  maxEntities: 1024,
+  maxComponentOperations: 4096,
+  maxStringBytes: 4096,
+  maxBufferBytes: 16 * 1024,
+  maxArrayElements: 1024
+};
+function hash(text) {
+  let value = 2166136261;
+  for (const char of text) {
+    value ^= char.charCodeAt(0);
+    value = Math.imul(value, 16777619);
+  }
+  return (value >>> 0).toString(16).padStart(8, "0");
+}
+function immutableProfile(options, limits, fingerprint) {
+  const entities = Object.freeze({
+    with: Object.freeze([...options.entities.with]),
+    ...options.entities.without === void 0 ? {} : { without: Object.freeze([...options.entities.without]) }
+  });
+  return Object.freeze({
+    name: options.name,
+    entities,
+    components: Object.freeze([...options.components]),
+    limits: Object.freeze({ ...limits }),
+    fingerprint
+  });
+}
+function defineReplication(options) {
+  const portable = validateProfileComponents(options.components);
+  if (!portable.valid) {
+    const first = portable.errors[0];
+    if (first === void 0) {
+      return err(
+        new NetError({
+          code: "schema-invalid",
+          expected: "portable replication components",
+          hint: "select only components accepted by the ECS externalization kernel",
+          detail: { component: "", reason: "portable validation failed without a diagnostic" }
+        })
+      );
+    }
+    return err(
+      new NetError({
+        code: "schema-invalid",
+        expected: first.expected,
+        hint: first.hint,
+        detail: { component: first.component, reason: first.code }
+      })
+    );
+  }
+  const limits = { ...DEFAULT_REPLICATION_LIMITS, ...options.limits };
+  const signature = JSON.stringify({
+    name: options.name,
+    query: {
+      with: options.entities.with.map((component) => component.name),
+      ...options.entities.without === void 0 ? {} : { without: options.entities.without.map((component) => component.name) }
+    },
+    components: options.components.map((component) => ({
+      name: component.name,
+      schema: componentSchema(component)
+    })),
+    limits
+  });
+  return ok(immutableProfile(options, limits, hash(signature)));
+}
+
+// src/replication/authority.ts
+function stable(value) {
+  return JSON.stringify(value);
+}
+var AuthorityCoordinator = class {
+  #world;
+  #profile;
+  #ids = /* @__PURE__ */ new Map();
+  #known = /* @__PURE__ */ new Map();
+  #nextId = 1;
+  #tick = 0;
+  constructor(world, profile) {
+    this.#world = world;
+    this.#profile = profile;
+  }
+  idFor(entity) {
+    return this.#ids.get(entity) ?? 0;
+  }
+  publish() {
+    return this.#publish(false);
+  }
+  publishFull() {
+    return this.#publish(true);
+  }
+  #publish(forceFull) {
+    const candidateIds = new Map(this.#ids);
+    let candidateNextId = this.#nextId;
+    const current = /* @__PURE__ */ new Map();
+    const query = this.#world.query(this.#profile.entities).unwrap();
+    for (const row of query) {
+      if (!candidateIds.has(row.entity)) candidateIds.set(row.entity, candidateNextId++);
+    }
+    for (const row of query) {
+      const entity = row.entity;
+      const components = [];
+      for (const component of this.#profile.components) {
+        const raw = this.#world.get(entity, component);
+        if (raw.ok) {
+          components.push({
+            name: component.name,
+            data: projectComponentData(
+              component,
+              raw.value,
+              (reference) => candidateIds.get(reference) ?? 0
+            )
+          });
+        }
+      }
+      const id = candidateIds.get(entity);
+      if (id !== void 0) current.set(entity, { id, components });
+    }
+    const full = forceFull || this.#tick === 0;
+    const entities = [];
+    for (const [entity, entry] of current) {
+      const prior = this.#known.get(entity);
+      const components = full || prior === void 0 ? entry.components : [
+        ...entry.components.filter(
+          (component) => prior.components.get(component.name) !== stable(component.data)
+        ),
+        ...[...prior.components.keys()].filter((name) => !entry.components.some((component) => component.name === name)).map((name) => ({ name, operation: "remove", data: {} }))
+      ];
+      if (full || prior === void 0 || components.length > 0)
+        entities.push({ id: entry.id, kind: "upsert", components });
+    }
+    if (!full)
+      for (const [entity, prior] of this.#known) {
+        if (!current.has(entity)) entities.push({ id: prior.id, kind: "despawn", components: [] });
+      }
+    const candidateKnown = /* @__PURE__ */ new Map();
+    for (const [entity, entry] of current) {
+      candidateKnown.set(entity, {
+        id: entry.id,
+        components: new Map(
+          entry.components.map((component) => [component.name, stable(component.data)])
+        )
+      });
+    }
+    for (const [entity] of candidateIds) {
+      if (!current.has(entity)) candidateIds.delete(entity);
+    }
+    const batch = {
+      version: REPLICATION_PROTOCOL_VERSION,
+      fingerprint: this.#profile.fingerprint,
+      tick: this.#tick + 1,
+      full,
+      entities
+    };
+    const encoded = encodeReplicationBatch(
+      batch,
+      this.#profile.limits ?? DEFAULT_REPLICATION_LIMITS
+    );
+    if (!encoded.ok) return err(encoded.error);
+    this.#ids.clear();
+    for (const [entity, id] of candidateIds) this.#ids.set(entity, id);
+    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 });
+  }
+};
+function createAuthorityCoordinator(world, profile) {
+  return new AuthorityCoordinator(world, profile);
+}
+function validateHandshake(local, remote) {
+  if (local.fingerprint !== remote.fingerprint)
+    return err(
+      new NetError({
+        code: "handshake-profile-mismatch",
+        expected: "matching protocol, profile, and declared limits",
+        hint: "use identical ordered replication components and limits on both peers",
+        detail: { localFingerprint: local.fingerprint, remoteFingerprint: remote.fingerprint }
+      })
+    );
+  return ok(void 0);
+}
+var ReplicaCoordinator = class {
+  #world;
+  #profile;
+  #endpoint;
+  #entities = /* @__PURE__ */ new Map();
+  #lastTick = 0;
+  #stopped = false;
+  constructor(world, profile, endpoint) {
+    this.#world = world;
+    this.#profile = profile;
+    this.#endpoint = endpoint;
+  }
+  entityFor(id) {
+    return this.#entities.get(id);
+  }
+  readComponent(id, component) {
+    const entity = this.#entities.get(id);
+    if (entity === void 0) return void 0;
+    const read = this.#world.get(entity, component);
+    return read.ok ? read.value : void 0;
+  }
+  snapshot() {
+    return [...this.#entities].map(([id, entity]) => ({
+      id,
+      components: this.#profile.components.filter((component) => this.#world.get(entity, component).ok).map((component) => component.name)
+    })).sort((a, b) => a.id - b.id);
+  }
+  disconnect() {
+    this.#endpoint?.close();
+  }
+  /** Remove the last replica baseline when the authority connection closes. */
+  clear() {
+    for (const entity of this.#entities.values()) this.#world.despawn(entity).unwrap();
+    this.#entities.clear();
+  }
+  get stopped() {
+    return this.#stopped;
+  }
+  get tick() {
+    return this.#lastTick;
+  }
+  #entityReferences(value) {
+    if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+      return Array.from(value);
+    }
+    return [];
+  }
+  validate(batch) {
+    if (this.#stopped)
+      return new NetError({
+        code: "apply-invariant-failed",
+        expected: "an active replica coordinator",
+        hint: "create a new session after a fatal apply failure",
+        detail: { reason: "replication stopped" }
+      });
+    if (batch.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)
+      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 }
+      });
+    const batchIds = /* @__PURE__ */ new Set();
+    for (const record of batch.entities) {
+      if (!Number.isSafeInteger(record.id) || record.id <= 0 || batchIds.has(record.id))
+        return new NetError({
+          code: "identity-invalid",
+          expected: "unique non-zero NetEntityId values",
+          hint: "use session-issued identity values exactly once per batch",
+          detail: { id: record.id, reason: "zero, invalid, or duplicate identity" }
+        });
+      batchIds.add(record.id);
+    }
+    for (const record of batch.entities) {
+      if (record.kind === "despawn" && !this.#entities.has(record.id))
+        return new NetError({
+          code: "identity-invalid",
+          expected: "a known identity for despawn",
+          hint: "do not reuse or despawn unknown network identities",
+          detail: { id: record.id, reason: "unknown identity" }
+        });
+      for (const entry of record.components) {
+        const component = this.#profile.components.find(
+          (candidate) => candidate.name === entry.name
+        );
+        if (component === void 0)
+          return new NetError({
+            code: "schema-invalid",
+            expected: "a component selected by the negotiated profile",
+            hint: "send only components from the ordered replication profile",
+            detail: { component: entry.name, reason: "unselected component" }
+          });
+        if (entry.operation === "remove") continue;
+        for (const [field, value] of Object.entries(entry.data)) {
+          if (!(field in componentSchema(component)))
+            return new NetError({
+              code: "schema-invalid",
+              expected: "component fields declared by the negotiated ECS schema",
+              hint: "send only fields declared by the replicated component token",
+              detail: { component: entry.name, reason: `unknown field ${field}` }
+            });
+          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)))
+              return new NetError({
+                code: "remap-unresolved-reference",
+                expected: "every entity reference to resolve in the current or same batch",
+                hint: "include the referenced spawn in this batch; cross-batch pending references are unsupported",
+                detail: { id: record.id, referencedId: Number(reference) }
+              });
+        }
+      }
+    }
+    return null;
+  }
+  apply(batch) {
+    const failure = this.validate(batch);
+    if (failure) {
+      this.disconnect();
+      return err(failure);
+    }
+    try {
+      for (const record of batch.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)
+        if (record.kind === "upsert") {
+          const entity = this.#entities.get(record.id);
+          if (entity === void 0) throw new Error(`missing allocated entity ${record.id}`);
+          for (const entry of record.components) {
+            const component = this.#profile.components.find(
+              (candidate) => candidate.name === entry.name
+            );
+            if (component === void 0) throw new Error(`missing profile component ${entry.name}`);
+            if (entry.operation === "remove") {
+              const removal = this.#world.removeComponent(entity, component);
+              if (!removal.ok) throw removal.error;
+              continue;
+            }
+            const data = Object.fromEntries(
+              Object.entries(entry.data).map(([field, value]) => {
+                const kind = classifyEntityField(component, field);
+                if (kind === null) return [field, value];
+                const mapped = kind.isArray ? this.#entityReferences(value).map((id) => {
+                  if (id === null) return null;
+                  const reference = this.#entities.get(id);
+                  if (reference === void 0)
+                    throw new Error(`missing entity reference ${id}`);
+                  return reference;
+                }) : value === null ? null : this.#entities.get(value);
+                if (mapped === void 0) throw new Error(`missing entity reference ${value}`);
+                return [field, mapped];
+              })
+            );
+            const typedData = data;
+            const exists = this.#world.get(entity, component);
+            const write = exists.ok ? this.#world.set(entity, component, typedData) : this.#world.addComponent(entity, { component, data: typedData });
+            if (!write.ok) throw write.error;
+          }
+        }
+      for (const record of batch.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;
+      return ok(void 0);
+    } catch (cause) {
+      this.#stopped = true;
+      return err(
+        new NetError({
+          code: "apply-invariant-failed",
+          expected: "ECS apply invariants to accept a validated batch",
+          hint: "stop this replication session and inspect the ECS error",
+          detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+        })
+      );
+    }
+  }
+};
+function createReplicaCoordinator(world, profile, endpoint) {
+  return new ReplicaCoordinator(world, profile, endpoint);
+}
+function applyReplicaBatch(replica, batch) {
+  return replica.apply(batch);
+}
+function decodeAndApplyReplicaBatch(replica, bytes, limits) {
+  const decoded = decodeReplicationBatch(bytes, limits);
+  if (!decoded.ok) {
+    replica.disconnect();
+    return err(decoded.error);
+  }
+  return replica.apply(decoded.value);
+}
+var NetSession = class {
+  #endpoint;
+  #peerIds = /* @__PURE__ */ new Set();
+  #rawMessages = [];
+  #maxRawMessages;
+  #authority;
+  #pendingFullPeers = /* @__PURE__ */ new Set();
+  #replica;
+  constructor(config) {
+    this.#endpoint = config.endpoint;
+    this.#maxRawMessages = config.maxRawMessages;
+  }
+  receiveEvents() {
+    const errors = [];
+    for (const event of this.#endpoint.poll()) {
+      if (event.kind === "peer-connected") {
+        this.#peerIds.add(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 {
+        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 });
+        }
+      }
+    }
+    return errors;
+  }
+  drainRawMessages() {
+    return this.#rawMessages.splice(0);
+  }
+  getPeerSnapshot() {
+    const peerIds = [...this.#peerIds].sort((left, right) => left - right);
+    return { peerIds, connected: peerIds.length > 0 };
+  }
+  sendRaw(peerId, data) {
+    const result = this.#endpoint.send(peerId, data);
+    return result.ok ? ok(void 0) : err(result.error);
+  }
+  attachAuthority(authority) {
+    this.#authority = authority;
+  }
+  requestFullBaseline(peerId) {
+    if (this.#peerIds.has(peerId)) this.#pendingFullPeers.add(peerId);
+  }
+  attachReplica(coordinator, limits) {
+    this.#replica = { coordinator, limits };
+  }
+  publish() {
+    if (this.#authority === void 0) return ok(void 0);
+    if (this.#pendingFullPeers.size > 0) {
+      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);
+        }
+      }
+      this.#pendingFullPeers.clear();
+    }
+    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);
+    }
+    return ok(void 0);
+  }
+};
+function netPlugin(config) {
+  return {
+    name: "net-session",
+    inject: ["world"],
+    apply(ctx) {
+      const world = ctx.world;
+      const session = new NetSession({
+        endpoint: config.endpoint,
+        maxRawMessages: config.maxRawMessages ?? 256
+      });
+      ctx.effect(() => {
+        world.insertResource("net-session", session);
+        return () => world.removeResource("net-session");
+      }, "net/session-resource");
+      ctx.effect(() => {
+        world.addSystem(Update, {
+          name: "net-receive",
+          queries: [],
+          before: [FixedUpdate],
+          fn: (world2) => world2.getResource("net-session").receiveEvents()
+        }).unwrap();
+        return () => world.removeSystem(Update, "net-receive");
+      }, "net/receive");
+      ctx.effect(() => {
+        world.addSystem(Update, {
+          name: "net-publish",
+          queries: [],
+          after: [FixedUpdate],
+          fn: (world2) => world2.getResource("net-session").publish()
+        }).unwrap();
+        return () => world.removeSystem(Update, "net-publish");
+      }, "net/publish");
+    }
+  };
+}
+
+export { AuthorityCoordinator, ENDPOINT_ERROR_HINTS, ENDPOINT_EXPECTED, EndpointError, NetError, NetSession, ReplicaCoordinator, applyReplicaBatch, createAuthorityCoordinator, createMemoryEndpointPair, createMemoryEndpointPairWithController, createReplicaCoordinator, decodeAndApplyReplicaBatch, defineReplication, isEndpointError, netPlugin, validateHandshake };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map