@forgeax/engine-net 0.0.0-dev.8d955ade1c79

package/dist/replication/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/replication/protocol.ts"],"names":[],"mappings":"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"}

package/dist/replication/replica.d.ts

@@ -0,0 +1,30 @@
+import type { Component, EntityHandle, World } from '@forgeax/engine-ecs';
+import { type Result } from '@forgeax/engine-types';
+import type { NetEndpoint } from '../endpoint/endpoint';
+import { NetError } from './errors';
+import type { ReplicationLimits, ReplicationProfile } from './profile';
+import type { ReplicationDataPacket } from './protocol';
+export declare class ReplicaCoordinator {
+    #private;
+    constructor(world: World, profile: ReplicationProfile, _endpoint?: unknown);
+    entityFor(id: number): EntityHandle | undefined;
+    readComponent(id: number, component: Component): Record<string, unknown> | undefined;
+    snapshot(): readonly {
+        id: number;
+        components: readonly string[];
+    }[];
+    disconnect(): void;
+    /** Remove the last replica baseline when the authority connection closes. */
+    clear(): void;
+    get stopped(): boolean;
+    get tick(): number;
+    /** Report the last accepted, duplicate, or stale-epoch packet decision. */
+    get lastPacketOutcome(): 'accepted' | 'duplicate' | 'ignored-old-epoch';
+    getPendingUnresolvedReferences(): number;
+    validate(packet: ReplicationDataPacket): NetError | null;
+    apply(packet: ReplicationDataPacket): Result<void, NetError>;
+}
+export declare function createReplicaCoordinator(world: World, profile: ReplicationProfile, endpoint?: NetEndpoint): ReplicaCoordinator;
+export declare function applyReplicationPacket(replica: ReplicaCoordinator, packet: ReplicationDataPacket): Result<void, NetError>;
+export declare function decodeAndApplyReplicationPacket(replica: ReplicaCoordinator, bytes: Uint8Array, limits: ReplicationLimits): Result<void, NetError>;
+//# sourceMappingURL=replica.d.ts.map

package/dist/replication/replica.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replica.d.ts","sourceRoot":"","sources":["../../src/replication/replica.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAG1E,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,qBAAa,kBAAkB;;gBASjB,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,SAAS,CAAC,EAAE,OAAO;IAI1E,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAG/C,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAMpF,QAAQ,IAAI,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE;IAUpE,UAAU,IAAI,IAAI;IAClB,6EAA6E;IAC7E,KAAK,IAAI,IAAI;IAIb,IAAI,OAAO,IAAI,OAAO,CAErB;IACD,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,2EAA2E;IAC3E,IAAI,iBAAiB,IAAI,UAAU,GAAG,WAAW,GAAG,mBAAmB,CAEtE;IACD,8BAA8B,IAAI,MAAM;IASxC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,QAAQ,GAAG,IAAI;IAkHxD,KAAK,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC;CAoF7D;AACD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,CAAC,EAAE,WAAW,GACrB,kBAAkB,CAEpB;AACD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,qBAAqB,GAC5B,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAExB;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAgBxB"}

package/dist/session/net-session.d.ts

@@ -0,0 +1,66 @@
+import { type Result } from '@forgeax/engine-types';
+import type { NetEndpoint, NetEndpointConnector, PeerId } from '../endpoint/endpoint';
+import { type EndpointError } from '../endpoint/errors';
+import type { AuthorityCoordinator } from '../replication/authority';
+import { NetError } from '../replication/errors';
+import { type ReplicationLimits } from '../replication/profile';
+import { type ReplicaCoordinator } from '../replication/replica';
+import { type NetRecoveryOutcome, type NetRecoveryPolicy, type NetRecoverySnapshot, type SessionId } from './recovery';
+export interface PeerSnapshot {
+    readonly peerIds: ReadonlyArray<PeerId>;
+    readonly connected: boolean;
+}
+export interface SessionSnapshot {
+    readonly sessionIds: ReadonlyArray<SessionId>;
+    readonly connected: boolean;
+}
+export interface NetSessionClock {
+    readonly now: () => number;
+    readonly schedule: (delayMs: number, callback: () => void) => {
+        cancel(): void;
+    };
+}
+export interface NetSessionResourceCounts {
+    readonly pendingConnects: number;
+    readonly timers: number;
+    readonly ledgers: number;
+    readonly callbacks: number;
+}
+export interface NetSessionConfig {
+    readonly endpoint?: NetEndpoint;
+    readonly connector?: NetEndpointConnector;
+    readonly sessionId?: SessionId | number;
+    readonly recovery?: Partial<NetRecoveryPolicy>;
+    readonly clock?: NetSessionClock;
+    readonly maxRawMessages: number;
+}
+export interface RawMessage {
+    readonly peerId: PeerId;
+    readonly sessionId: SessionId;
+    readonly data: Uint8Array;
+}
+export declare class NetSession {
+    #private;
+    constructor(config: NetSessionConfig);
+    receiveEvents(): readonly NetError[];
+    drainRawMessages(): RawMessage[];
+    getPeerSnapshot(): PeerSnapshot;
+    getSessionSnapshot(): SessionSnapshot;
+    /** Return lifecycle, epoch, sequence, ledger, and owned-resource evidence. */
+    getRecoverySnapshot(): NetRecoverySnapshot;
+    getResourceSnapshot(): NetSessionResourceCounts;
+    recover(): NetRecoveryOutcome;
+    advanceRecovery(): void;
+    sendRaw(peerId: PeerId, data: Uint8Array): Result<void, EndpointError | NetError>;
+    /** Send one application command through the current replica attachment. */
+    sendToAuthority(sessionId: SessionId, data: Uint8Array): Result<void, EndpointError | NetError>;
+    /** Send one application message to an authority-owned logical session. */
+    sendToSession(sessionId: SessionId, data: Uint8Array): Result<void, EndpointError | NetError>;
+    attachAuthority(authority: AuthorityCoordinator): void;
+    requestFullBaseline(peerId: PeerId): void;
+    requestFullBaselineForSession(sessionId: SessionId): void;
+    attachReplica(coordinator: ReplicaCoordinator, limits: ReplicationLimits): void;
+    publish(): Result<void, NetError | EndpointError>;
+    dispose(): void;
+}
+//# sourceMappingURL=net-session.d.ts.map

package/dist/session/net-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-session.d.ts","sourceRoot":"","sources":["../../src/session/net-session.ts"],"names":[],"mappings":"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"}

package/dist/session/recovery.d.ts

@@ -0,0 +1,93 @@
+import { type Result } from '@forgeax/engine-types';
+import type { NetEndpointConnector } from '../endpoint/endpoint';
+import type { EndpointError } from '../endpoint/errors';
+import { NetError, type NetErrorCode } from '../replication/errors';
+declare const sessionIdBrand: unique symbol;
+/** Authority-issued application identity; it is distinct from transport PeerId. */
+export type SessionId = number & {
+    readonly [sessionIdBrand]: true;
+};
+export type NetSessionStateKind = 'connecting' | 'resyncing' | 'active' | 'recovering' | 'failed' | 'retired';
+export type NetSessionFailure = NetError | EndpointError;
+/** Public lifecycle state owned by one logical session. */
+export type NetSessionState = {
+    readonly kind: 'connecting';
+    readonly sessionId: SessionId;
+} | {
+    readonly kind: 'resyncing';
+    readonly sessionId: SessionId;
+    readonly epoch: number;
+} | {
+    readonly kind: 'active';
+    readonly sessionId: SessionId;
+    readonly epoch: number;
+    readonly sequence: number;
+} | {
+    readonly kind: 'recovering';
+    readonly sessionId: SessionId;
+    readonly epoch: number;
+    readonly attempt: number;
+} | {
+    readonly kind: 'failed';
+    readonly sessionId: SessionId;
+    readonly error: NetSessionFailure;
+} | {
+    readonly kind: 'retired';
+    readonly sessionId: SessionId;
+    readonly reason: 'disposed' | 'terminal-failure';
+};
+export interface NetRecoveryPolicy {
+    readonly maxSessions: number;
+    readonly maxPendingPackets: number;
+    readonly ackTimeoutMs: number;
+    readonly maxPacketRetries: number;
+    readonly maxReconnectAttempts: number;
+    readonly reconnectDeadlineMs: number;
+    readonly reconnectDelaysMs: readonly number[];
+}
+/** Finite, deterministic recovery bounds shared by every transport adapter. */
+export declare const DEFAULT_NET_RECOVERY_POLICY: NetRecoveryPolicy;
+/** Validate a complete policy without mutating it. */
+export declare function validateNetRecoveryPolicy(policy: NetRecoveryPolicy): Result<void, NetError>;
+/** Merge caller overrides with the bounded defaults and validate the result. */
+export declare function resolveNetRecoveryPolicy(overrides?: Partial<NetRecoveryPolicy>): Result<NetRecoveryPolicy, NetError>;
+/** Create a positive application identity without allowing plain numbers to cross the seam. */
+export declare function createSessionId(value: number): Result<SessionId, NetError>;
+/** Observable bounded accounting for one logical recovery session. */
+export interface NetRecoverySnapshot {
+    readonly sessionId: SessionId;
+    readonly state: NetSessionState;
+    readonly pendingPackets: number;
+    readonly maxPendingPackets: number;
+    readonly acknowledgedSequence: number;
+    readonly reconnectAttempts: number;
+    readonly epoch: number;
+    readonly sequence: number;
+    readonly ownedResources: {
+        readonly pendingConnects: number;
+        readonly timers: number;
+        readonly ledgers: number;
+        readonly callbacks: number;
+    };
+    readonly lastError?: NetSessionFailure;
+}
+/** Stable result kinds for repeated recovery requests. */
+export type NetRecoveryOutcome = {
+    readonly kind: 'started';
+    readonly sessionId: SessionId;
+} | {
+    readonly kind: 'already-recovering';
+    readonly sessionId: SessionId;
+} | {
+    readonly kind: 'already-active';
+    readonly sessionId: SessionId;
+} | {
+    readonly kind: 'retired';
+    readonly sessionId: SessionId;
+};
+export declare function isLegalNetSessionTransition(from: NetSessionStateKind, to: NetSessionStateKind): boolean;
+/** Validate an immutable state replacement before a session publishes it. */
+export declare function transitionNetSessionState(from: NetSessionState, to: NetSessionState): Result<NetSessionState, NetError>;
+export type { NetEndpointConnector };
+export declare const RECOVERY_ERROR_CODES: readonly NetErrorCode[];
+//# sourceMappingURL=recovery.d.ts.map

package/dist/session/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/session/recovery.ts"],"names":[],"mappings":"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"}

package/dist/session/session-plugin.d.ts

@@ -0,0 +1,14 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+import type { NetEndpoint, NetEndpointConnector } from '../endpoint/endpoint';
+import { type NetSessionClock } from './net-session';
+import type { NetRecoveryPolicy } from './recovery';
+export interface NetPluginConfig {
+    readonly endpoint?: NetEndpoint;
+    readonly connector?: NetEndpointConnector;
+    readonly sessionId?: number;
+    readonly recovery?: Partial<NetRecoveryPolicy>;
+    readonly clock?: NetSessionClock;
+    readonly maxRawMessages?: number;
+}
+export declare function netPlugin(config: NetPluginConfig): Plugin;
+//# sourceMappingURL=session-plugin.d.ts.map

package/dist/session/session-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-plugin.d.ts","sourceRoot":"","sources":["../../src/session/session-plugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiDzD"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@forgeax/engine-net",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Memory network transport, replication session, and profile-driven ECS sync for forgeax Engine.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-plugin": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library package; no runtime canvas; E2E proof deferred to Loop 3"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "no performance benchmarks; deterministic correctness verified by unit and model tests"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; net correctness gated by pnpm test:unit"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/endpoint/endpoint.ts

@@ -0,0 +1,58 @@
+// @forgeax/engine-net -- transport-only endpoint contract.
+//
+// NetEndpoint is the minimum transport seam: complete bytes, actual PeerId,
+// and connect/disconnect lifecycle. No ECS, profile, or codec dependency.
+// Reliable ordered delivery per peer or explicit connection failure.
+// (requirements AC-02, plan-strategy D-3)
+
+import type { Result } from '@forgeax/engine-types';
+import type { EndpointError } from './errors';
+
+// ---------------------------------------------------------------------------
+// PeerId -- opaque, branded peer identity (transport-level, not NetEntityId)
+// ---------------------------------------------------------------------------
+
+declare const __peerIdBrand: unique symbol;
+
+/** Opaque transport-level peer identity. Never a plain number. */
+export type PeerId = number & { readonly [__peerIdBrand]: true };
+
+// ---------------------------------------------------------------------------
+// Endpoint events
+// ---------------------------------------------------------------------------
+
+/** Transport-level event emitted by NetEndpoint.poll(). */
+export type EndpointEvent =
+  | { readonly kind: 'peer-connected'; readonly peerId: PeerId }
+  | { readonly kind: 'peer-disconnected'; readonly peerId: PeerId }
+  | { readonly kind: 'message'; readonly peerId: PeerId; readonly data: Uint8Array };
+
+// ---------------------------------------------------------------------------
+// NetEndpoint -- transport-only contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Transport-only endpoint contract.
+ *
+ * Delivers complete Uint8Array messages with actual PeerId and connect/disconnect
+ * lifecycle. Reliable ordered delivery per peer or explicit connection failure.
+ * No ECS, profile, or codec knowledge.
+ */
+export interface NetEndpoint {
+  /** Poll for pending events (connect, disconnect, message). Returns empty array when idle. */
+  poll(): EndpointEvent[];
+
+  /** Send a complete message to a connected peer. Returns structured error on failure. */
+  send(peerId: PeerId, data: Uint8Array): Result<void, EndpointError>;
+
+  /** Close the endpoint. No further send/poll should succeed after close. */
+  close(): Result<void, EndpointError>;
+}
+
+/**
+ * Realm-neutral capability for creating a replacement endpoint.
+ * Session policy, retry bounds, and replication semantics remain in net.
+ */
+export interface NetEndpointConnector {
+  connect(signal: AbortSignal): Promise<Result<NetEndpoint, EndpointError>>;
+}

package/src/endpoint/errors.ts

@@ -0,0 +1,164 @@
+// @forgeax/engine-net -- endpoint structured errors.
+//
+// Closed union of transport-level failures. Each variant carries .code, .expected,
+// .hint, and per-code .detail. AI users exhaustively switch on .code without a
+// default branch (requirements AC-13).
+
+import type { PeerId } from './endpoint';
+
+// ---------------------------------------------------------------------------
+// EndpointErrorCode -- closed 5-member union derived from endpointErrorPolicy
+// ---------------------------------------------------------------------------
+
+/** Transport-level endpoint error codes (requirements AC-02, AC-13). */
+export type EndpointErrorCode = keyof typeof endpointErrorPolicy;
+
+// ---------------------------------------------------------------------------
+// Per-code detail payloads
+// ---------------------------------------------------------------------------
+
+export interface EndpointDetailPeerNotFound {
+  readonly peerId: PeerId;
+}
+
+export interface EndpointDetailConnectionClosed {
+  readonly peerId: PeerId;
+}
+
+export interface EndpointDetailSendFailed {
+  readonly peerId: PeerId;
+  readonly cause: string;
+}
+
+export interface EndpointDetailAlreadyClosed {
+  readonly cause: string;
+}
+
+export interface EndpointDetailConnectionFailed {
+  readonly address: string;
+  readonly cause: string;
+}
+
+// ---------------------------------------------------------------------------
+// Conditional resolver
+// ---------------------------------------------------------------------------
+
+export type EndpointErrorDetailFor<C extends EndpointErrorCode> = C extends 'peer-not-found'
+  ? EndpointDetailPeerNotFound
+  : C extends 'connection-closed'
+    ? EndpointDetailConnectionClosed
+    : C extends 'send-failed'
+      ? EndpointDetailSendFailed
+      : C extends 'already-closed'
+        ? EndpointDetailAlreadyClosed
+        : C extends 'connection-failed'
+          ? EndpointDetailConnectionFailed
+          : never;
+
+/** Tagged union of all endpoint error detail variants. */
+export type EndpointErrorDetail = EndpointErrorDetailFor<EndpointErrorCode>;
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+class EndpointErrorClass extends Error {
+  readonly code: EndpointErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: EndpointErrorDetail;
+
+  constructor(args: {
+    code: EndpointErrorCode;
+    expected: string;
+    hint: string;
+    detail: EndpointErrorDetail;
+  }) {
+    let suffix = '';
+    if (args.code === 'peer-not-found') {
+      const d = args.detail as EndpointDetailPeerNotFound;
+      suffix = ` (peerId=${d.peerId})`;
+    } else if (args.code === 'connection-closed') {
+      const d = args.detail as EndpointDetailConnectionClosed;
+      suffix = ` (peerId=${d.peerId})`;
+    } else if (args.code === 'send-failed') {
+      const d = args.detail as EndpointDetailSendFailed;
+      suffix = ` (peerId=${d.peerId}, cause=${d.cause})`;
+    } else if (args.code === 'already-closed') {
+      const d = args.detail as EndpointDetailAlreadyClosed;
+      suffix = ` (cause=${d.cause})`;
+    } else if (args.code === 'connection-failed') {
+      const d = args.detail as EndpointDetailConnectionFailed;
+      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;
+  }
+}
+
+type EndpointErrorVariant<C extends EndpointErrorCode> = EndpointErrorClass & {
+  readonly code: C;
+  readonly detail: EndpointErrorDetailFor<C>;
+};
+
+export type EndpointError = {
+  [C in EndpointErrorCode]: EndpointErrorVariant<C>;
+}[EndpointErrorCode];
+
+interface EndpointErrorConstructor {
+  new <C extends EndpointErrorCode>(args: {
+    code: C;
+    expected: string;
+    hint: string;
+    detail: EndpointErrorDetailFor<C>;
+  }): EndpointErrorVariant<C>;
+  readonly prototype: EndpointErrorClass;
+}
+
+export const EndpointError: EndpointErrorConstructor =
+  EndpointErrorClass as unknown as EndpointErrorConstructor;
+
+type EndpointErrorPolicy = { readonly expected: string; readonly hint: string };
+
+const 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',
+  },
+} satisfies Record<string, EndpointErrorPolicy>;
+
+/** Expected-invariant table per error code. */
+export const ENDPOINT_EXPECTED: Readonly<Record<EndpointErrorCode, string>> = Object.fromEntries(
+  Object.entries(endpointErrorPolicy).map(([code, policy]) => [code, policy.expected]),
+) as Readonly<Record<EndpointErrorCode, string>>;
+
+/** Actionable hint table per error code. */
+export const ENDPOINT_ERROR_HINTS: Readonly<Record<EndpointErrorCode, string>> = Object.fromEntries(
+  Object.entries(endpointErrorPolicy).map(([code, policy]) => [code, policy.hint]),
+) as Readonly<Record<EndpointErrorCode, string>>;
+
+/** Type guard for narrowing unknown to EndpointError. */
+export function isEndpointError(err: unknown): err is EndpointError {
+  return err instanceof EndpointErrorClass;
+}