@forgeax/engine-net 0.1.2

package/src/replication/codec.ts

@@ -0,0 +1,257 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { REPLICATION_PROTOCOL_VERSION } from './constants';
+import { NetError } from './errors';
+import type { ReplicationLimits } from './profile';
+
+export type NetEntityId = number & { readonly __netEntityId: unique symbol };
+export interface ReplicationComponentRecord {
+  readonly name: string;
+  readonly operation?: 'replace' | 'remove';
+  readonly data: Record<string, unknown>;
+}
+export interface ReplicationEntityRecord {
+  readonly id: number;
+  readonly kind: 'upsert' | 'despawn';
+  readonly components: readonly ReplicationComponentRecord[];
+}
+export interface ReplicationBatch {
+  readonly version: number;
+  readonly fingerprint: string;
+  readonly tick: number;
+  readonly full: boolean;
+  readonly entities: readonly ReplicationEntityRecord[];
+}
+
+const REPLICATION_ENTITY_KINDS = [
+  'upsert',
+  'despawn',
+] as const satisfies readonly ReplicationEntityRecord['kind'][];
+
+function isReplicationEntityKind(value: unknown): value is ReplicationEntityRecord['kind'] {
+  return REPLICATION_ENTITY_KINDS.some((kind) => kind === value);
+}
+
+const TYPED_ARRAYS = {
+  Float32Array,
+  Float64Array,
+  Int8Array,
+  Int16Array,
+  Int32Array,
+  Uint8Array,
+  Uint8ClampedArray,
+  Uint16Array,
+  Uint32Array,
+} as const;
+type TypedArrayName = keyof typeof TYPED_ARRAYS;
+type PortableTypedArray = InstanceType<(typeof TYPED_ARRAYS)[TypedArrayName]>;
+
+function typedArrayName(value: unknown): TypedArrayName | undefined {
+  for (const [name, typedArrayConstructor] of Object.entries(TYPED_ARRAYS) as [
+    TypedArrayName,
+    (typeof TYPED_ARRAYS)[TypedArrayName],
+  ][]) {
+    if (value instanceof typedArrayConstructor) return name;
+  }
+  return undefined;
+}
+
+function canonicalize(value: unknown): unknown {
+  const name = typedArrayName(value);
+  if (name !== undefined)
+    return { $typedArray: name, values: Array.from(value as PortableTypedArray) };
+  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 as Record<string, unknown>)[key])]),
+    );
+  }
+  return value;
+}
+
+function reviveTypedArrays(
+  value: unknown,
+): { readonly value: unknown } | { readonly reason: string } {
+  if (Array.isArray(value)) {
+    const values: unknown[] = [];
+    for (const item of value) {
+      const revived = reviveTypedArrays(item);
+      if ('reason' in revived) return revived;
+      values.push(revived.value);
+    }
+    return { value: values };
+  }
+  if (value === null || typeof value !== 'object') return { value };
+  const record = value as Record<string, unknown>;
+  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 as TypedArrayName];
+    if (
+      typedArrayConstructor === undefined ||
+      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: Record<string, unknown> = {};
+  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: string, actual: number, maximum: number): NetError {
+  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: ReplicationBatch,
+  bytes: Uint8Array | undefined,
+  limits: ReplicationLimits,
+): NetError | null {
+  if (bytes !== undefined && 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: unknown): NetError | null => {
+    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 !== undefined) {
+      const contents = value as PortableTypedArray;
+      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 as Record<string, unknown>)) {
+        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: Uint8Array,
+): { readonly batch: ReplicationBatch } | { readonly reason: string } {
+  try {
+    const decoded: unknown = 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 as Partial<ReplicationBatch>;
+    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 as Partial<ReplicationEntityRecord>;
+      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 as Partial<ReplicationComponentRecord>;
+        if (
+          typeof entry.name !== 'string' ||
+          entry.name.length === 0 ||
+          (entry.operation !== undefined &&
+            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: batch as ReplicationBatch };
+  } catch {
+    return { reason: 'payload is not valid JSON' };
+  }
+}
+export function encodeReplicationBatch(
+  batch: ReplicationBatch,
+  limits: ReplicationLimits,
+): Result<Uint8Array, NetError> {
+  const bytes = new TextEncoder().encode(JSON.stringify(canonicalize(batch)));
+  const failure = validateLimits(batch, bytes, limits);
+  return failure ? err(failure) : ok(bytes);
+}
+export function decodeReplicationBatch(
+  bytes: Uint8Array,
+  limits: ReplicationLimits,
+): Result<ReplicationBatch, NetError> {
+  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);
+}

package/src/replication/constants.ts

@@ -0,0 +1 @@
+export const REPLICATION_PROTOCOL_VERSION = 1;

package/src/replication/errors.ts

@@ -0,0 +1,60 @@
+type NetErrorDetailByCode = {
+  'handshake-profile-mismatch': {
+    readonly localFingerprint: string;
+    readonly remoteFingerprint: string;
+  };
+  'decode-invalid-payload': { readonly reason: string };
+  'decode-limit-exceeded': {
+    readonly limit: string;
+    readonly actual: number;
+    readonly maximum: number;
+  };
+  'ordering-invalid-tick': { readonly receivedTick: number; readonly lastTick: number };
+  'identity-invalid': { readonly id: number; readonly reason: string };
+  'schema-invalid': { readonly component: string; readonly reason: string };
+  'remap-unresolved-reference': { readonly id: number; readonly referencedId: number };
+  'apply-invariant-failed': { readonly reason: string };
+};
+
+export type NetErrorCode = keyof NetErrorDetailByCode;
+export type NetErrorDetail = NetErrorDetailByCode[NetErrorCode];
+
+class NetErrorClass extends Error {
+  readonly code: NetErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: NetErrorDetail;
+  constructor(args: {
+    code: NetErrorCode;
+    expected: string;
+    hint: string;
+    detail: NetErrorDetail;
+  }) {
+    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;
+  }
+}
+
+type Variant<C extends NetErrorCode> = NetErrorClass & {
+  readonly code: C;
+  readonly detail: NetErrorDetailByCode[C];
+};
+
+export type NetError = {
+  [C in NetErrorCode]: Variant<C>;
+}[NetErrorCode];
+
+interface NetErrorConstructor {
+  new <C extends NetErrorCode>(args: {
+    code: C;
+    expected: string;
+    hint: string;
+    detail: NetErrorDetailByCode[C];
+  }): Variant<C>;
+  readonly prototype: NetErrorClass;
+}
+export const NetError: NetErrorConstructor = NetErrorClass as unknown as NetErrorConstructor;

package/src/replication/handshake.ts

@@ -0,0 +1,18 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { NetError } from './errors';
+import type { ReplicationProfile } from './profile';
+export function validateHandshake(
+  local: ReplicationProfile,
+  remote: ReplicationProfile,
+): Result<void, NetError> {
+  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(undefined);
+}

package/src/replication/profile.ts

@@ -0,0 +1,111 @@
+import type { Component } from '@forgeax/engine-ecs';
+import { validateProfileComponents } from '@forgeax/engine-ecs/externalization';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { err, ok, type Result } from '@forgeax/engine-types';
+export interface ReplicationLimits {
+  readonly maxMessageBytes: number;
+  readonly maxEntities: number;
+  readonly maxComponentOperations: number;
+  readonly maxStringBytes: number;
+  readonly maxBufferBytes: number;
+  readonly maxArrayElements: number;
+}
+export const DEFAULT_REPLICATION_LIMITS: ReplicationLimits = {
+  maxMessageBytes: 64 * 1024,
+  maxEntities: 1024,
+  maxComponentOperations: 4096,
+  maxStringBytes: 4096,
+  maxBufferBytes: 16 * 1024,
+  maxArrayElements: 1024,
+};
+
+import { NetError } from './errors';
+
+export interface ReplicationProfile {
+  readonly name: string;
+  readonly entities: ReplicationEntityFilter;
+  readonly components: readonly Component[];
+  readonly limits: ReplicationLimits;
+  readonly fingerprint: string;
+}
+export interface ReplicationEntityFilter {
+  readonly with: readonly Component[];
+  readonly without?: readonly Component[];
+}
+export interface DefineReplicationOptions {
+  readonly name: string;
+  readonly entities: ReplicationEntityFilter;
+  readonly components: readonly Component[];
+  readonly limits?: Partial<ReplicationLimits>;
+}
+function hash(text: string): string {
+  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: DefineReplicationOptions,
+  limits: ReplicationLimits,
+  fingerprint: string,
+): ReplicationProfile {
+  const entities: ReplicationEntityFilter = Object.freeze({
+    with: Object.freeze([...options.entities.with]),
+    ...(options.entities.without === undefined
+      ? {}
+      : { without: Object.freeze([...options.entities.without]) }),
+  });
+  return Object.freeze({
+    name: options.name,
+    entities,
+    components: Object.freeze([...options.components]),
+    limits: Object.freeze({ ...limits }),
+    fingerprint,
+  });
+}
+
+export function defineReplication(
+  options: DefineReplicationOptions,
+): Result<ReplicationProfile, NetError> {
+  const portable = validateProfileComponents(options.components);
+  if (!portable.valid) {
+    const first = portable.errors[0];
+    if (first === undefined) {
+      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: ReplicationLimits = { ...DEFAULT_REPLICATION_LIMITS, ...options.limits };
+  const signature = JSON.stringify({
+    name: options.name,
+    query: {
+      with: options.entities.with.map((component) => component.name),
+      ...(options.entities.without === undefined
+        ? {}
+        : { 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)));
+}

package/src/replication/replica.ts

@@ -0,0 +1,240 @@
+import type { Component, EntityHandle, World } from '@forgeax/engine-ecs';
+import { classifyEntityField } from '@forgeax/engine-ecs/externalization';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { NetEndpoint } from '../endpoint/endpoint';
+import { decodeReplicationBatch, type ReplicationBatch } from './codec';
+import { NetError } from './errors';
+import type { ReplicationLimits, ReplicationProfile } from './profile';
+
+export class ReplicaCoordinator {
+  readonly #world: World;
+  readonly #profile: ReplicationProfile;
+  readonly #endpoint: NetEndpoint | undefined;
+  readonly #entities = new Map<number, EntityHandle>();
+  #lastTick = 0;
+  #stopped = false;
+  constructor(world: World, profile: ReplicationProfile, endpoint?: NetEndpoint) {
+    this.#world = world;
+    this.#profile = profile;
+    this.#endpoint = endpoint;
+  }
+  entityFor(id: number): EntityHandle | undefined {
+    return this.#entities.get(id);
+  }
+  readComponent(id: number, component: Component): Record<string, unknown> | undefined {
+    const entity = this.#entities.get(id);
+    if (entity === undefined) return undefined;
+    const read = this.#world.get(entity, component);
+    return read.ok ? (read.value as Record<string, unknown>) : undefined;
+  }
+  snapshot(): readonly { id: number; components: readonly string[] }[] {
+    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(): void {
+    this.#endpoint?.close();
+  }
+  /** Remove the last replica baseline when the authority connection closes. */
+  clear(): void {
+    for (const entity of this.#entities.values()) this.#world.despawn(entity).unwrap();
+    this.#entities.clear();
+  }
+  get stopped(): boolean {
+    return this.#stopped;
+  }
+  get tick(): number {
+    return this.#lastTick;
+  }
+  #entityReferences(value: unknown): readonly unknown[] {
+    if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+      return Array.from(value as ArrayLike<unknown>);
+    }
+    return [];
+  }
+  validate(batch: ReplicationBatch): NetError | null {
+    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 = new Set<number>();
+    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 === undefined)
+          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: ReplicationBatch): Result<void, NetError> {
+    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 === undefined) 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 === undefined) 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 as number);
+                      if (reference === undefined)
+                        throw new Error(`missing entity reference ${id}`);
+                      return reference;
+                    })
+                  : value === null
+                    ? null
+                    : this.#entities.get(value as number);
+                if (mapped === undefined) throw new Error(`missing entity reference ${value}`);
+                return [field, mapped];
+              }),
+            );
+            const typedData = data as never;
+            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 === undefined) throw new Error(`missing despawn entity ${record.id}`);
+          this.#world.despawn(entity).unwrap();
+          this.#entities.delete(record.id);
+        }
+      this.#lastTick = batch.tick;
+      return ok(undefined);
+    } 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) },
+        }),
+      );
+    }
+  }
+}
+export function createReplicaCoordinator(
+  world: World,
+  profile: ReplicationProfile,
+  endpoint?: NetEndpoint,
+): ReplicaCoordinator {
+  return new ReplicaCoordinator(world, profile, endpoint);
+}
+export function applyReplicaBatch(
+  replica: ReplicaCoordinator,
+  batch: ReplicationBatch,
+): Result<void, NetError> {
+  return replica.apply(batch);
+}
+
+export function decodeAndApplyReplicaBatch(
+  replica: ReplicaCoordinator,
+  bytes: Uint8Array,
+  limits: ReplicationLimits,
+): Result<void, NetError> {
+  const decoded = decodeReplicationBatch(bytes, limits);
+  if (!decoded.ok) {
+    replica.disconnect();
+    return err(decoded.error);
+  }
+  return replica.apply(decoded.value);
+}