@forgeax/engine-net 0.1.3 → 0.1.6

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

@@ -1 +1 @@
-{"version":3,"file":"authority.d.ts","sourceRoot":"","sources":["../../src/replication/authority.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAEL,KAAK,gBAAgB,EAGtB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEhF,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AASD,qBAAa,oBAAoB;;gBAOnB,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB;IAIrD,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAGnC,OAAO,IAAI,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC;IAG3C,WAAW,IAAI,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC;CAiGhD;AACD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,kBAAkB,GAC1B,oBAAoB,CAEtB"}
+{"version":3,"file":"authority.d.ts","sourceRoot":"","sources":["../../src/replication/authority.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,KAAK,EAEV,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,eAAe,GAAG,qBAAqB,GAAG;IACpD,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B,CAAC;AASF,qBAAa,oBAAoB;;gBAUnB,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,SAAS,GAAE,SAA0B;IAK5F,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAGnC,OAAO,IAAI,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC;IAG5C,WAAW,IAAI,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC;IAGhD,oBAAoB,CAAC,SAAS,UAAQ,GAAG,MAAM;CAyHhD;AACD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,kBAAkB,GAC1B,oBAAoB,CAEtB"}

package/dist/replication/codec.d.ts

@@ -1,26 +1,8 @@
 import { type Result } from '@forgeax/engine-types';
 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[];
-}
-export declare function encodeReplicationBatch(batch: ReplicationBatch, limits: ReplicationLimits): Result<Uint8Array, NetError>;
-export declare function decodeReplicationBatch(bytes: Uint8Array, limits: ReplicationLimits): Result<ReplicationBatch, NetError>;
+import type { ReplicationPacket } from './protocol';
+export type { ReplicationComponentRecord, ReplicationEntityRecord } from './protocol';
+export declare function encodeReplicationPacket(packet: ReplicationPacket, limits: ReplicationLimits): Result<Uint8Array, NetError>;
+export declare function decodeReplicationPacket(bytes: Uint8Array, limits: ReplicationLimits): Result<ReplicationPacket, NetError>;
 //# sourceMappingURL=codec.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/replication/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,aAAa,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAC7E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AACD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC5D;AACD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACvD;AA2MD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAI9B;AACD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAoBpC"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/replication/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAkD,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpG,YAAY,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAsStF,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAO9B;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAOrC"}

package/dist/replication/constants.d.ts

@@ -1,2 +1,5 @@
-export declare const REPLICATION_PROTOCOL_VERSION = 1;
+/** The sole application replication protocol version published by net. */
+export declare const REPLICATION_PROTOCOL_VERSION = 2;
+/** Fixed wire prefix used to reject non-v2 replication bytes before dispatch. */
+export declare const REPLICATION_PROTOCOL_PREFIX = "FXRP2";
 //# sourceMappingURL=constants.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/replication/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,4BAA4B,IAAI,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/replication/constants.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,UAAU,CAAC"}

package/dist/replication/errors.d.ts

@@ -1,4 +1,4 @@
-type NetErrorDetailByCode = {
+export type NetErrorDetailByCode = {
     'handshake-profile-mismatch': {
         readonly localFingerprint: string;
         readonly remoteFingerprint: string;
@@ -30,9 +30,29 @@ type NetErrorDetailByCode = {
     'apply-invariant-failed': {
         readonly reason: string;
     };
+    'protocol-unsupported-version': {
+        readonly receivedVersion: number;
+        readonly supportedVersion: number;
+    };
+    'session-illegal-transition': {
+        readonly from: string;
+        readonly to: string;
+    };
+    'recovery-policy-invalid': {
+        readonly field: string;
+        readonly reason: string;
+    };
+    'recovery-rejected': {
+        readonly reason: string;
+    };
+    'recovery-exhausted': {
+        readonly attempts: number;
+        readonly maxAttempts: number;
+    };
 };
 export type NetErrorCode = keyof NetErrorDetailByCode;
-export type NetErrorDetail = NetErrorDetailByCode[NetErrorCode];
+export type NetErrorDetailFor<C extends NetErrorCode> = NetErrorDetailByCode[C];
+export type NetErrorDetail = NetErrorDetailFor<NetErrorCode>;
 declare class NetErrorClass extends Error {
     readonly code: NetErrorCode;
     readonly expected: string;
@@ -47,7 +67,7 @@ declare class NetErrorClass extends Error {
 }
 type Variant<C extends NetErrorCode> = NetErrorClass & {
     readonly code: C;
-    readonly detail: NetErrorDetailByCode[C];
+    readonly detail: NetErrorDetailFor<C>;
 };
 export type NetError = {
     [C in NetErrorCode]: Variant<C>;
@@ -57,7 +77,7 @@ interface NetErrorConstructor {
         code: C;
         expected: string;
         hint: string;
-        detail: NetErrorDetailByCode[C];
+        detail: NetErrorDetailFor<C>;
     }): Variant<C>;
     readonly prototype: NetErrorClass;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/replication/errors.ts"],"names":[],"mappings":"AAAA,KAAK,oBAAoB,GAAG;IAC1B,4BAA4B,EAAE;QAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;KACpC,CAAC;IACF,wBAAwB,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,uBAAuB,EAAE;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,uBAAuB,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACtF,kBAAkB,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,gBAAgB,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,4BAA4B,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACrF,wBAAwB,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,oBAAoB,CAAC;AACtD,MAAM,MAAM,cAAc,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC;AAEhE,cAAM,aAAc,SAAQ,KAAK;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;gBACpB,IAAI,EAAE;QAChB,IAAI,EAAE,YAAY,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,cAAc,CAAC;KACxB;CAQF;AAED,KAAK,OAAO,CAAC,CAAC,SAAS,YAAY,IAAI,aAAa,GAAG;IACrD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;KACpB,CAAC,IAAI,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC;CAChC,CAAC,YAAY,CAAC,CAAC;AAEhB,UAAU,mBAAmB;IAC3B,KAAK,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE;QACjC,IAAI,EAAE,CAAC,CAAC;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;KACjC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACf,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;CACnC;AACD,eAAO,MAAM,QAAQ,EAAE,mBAAqE,CAAC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/replication/errors.ts"],"names":[],"mappings":"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"}

package/dist/replication/protocol.d.ts

@@ -0,0 +1,63 @@
+import type { SessionId } from '../session/recovery';
+/** Replicated ECS entity operations owned by the protocol manifest. */
+export type ReplicationEntityKind = 'upsert' | 'despawn';
+export interface ReplicationComponentRecord {
+    readonly name: string;
+    readonly operation?: 'replace' | 'remove';
+    readonly data: Record<string, unknown>;
+}
+export interface ReplicationEntityRecord {
+    readonly id: number;
+    readonly kind: ReplicationEntityKind;
+    readonly components: readonly ReplicationComponentRecord[];
+}
+export type ReplicationPacketKind = 'session-open' | 'session-resume' | 'baseline' | 'delta' | 'ack' | 'rejection';
+/** Control packet that opens or resumes one application session. */
+export interface ReplicationSessionPacket {
+    readonly version: 2;
+    readonly kind: 'session-open' | 'session-resume';
+    readonly sessionId: SessionId;
+    readonly epoch: number;
+    readonly sequence: 0;
+}
+/** Shared fields for baseline and delta data packets. */
+export interface ReplicationDataPacketBase {
+    readonly version: 2;
+    readonly kind: 'baseline' | 'delta';
+    readonly sessionId: SessionId;
+    readonly epoch: number;
+    readonly sequence: number;
+    readonly tick: number;
+    readonly fingerprint: string;
+    readonly entities: readonly ReplicationEntityRecord[];
+}
+/** Complete authoritative baseline; sequence one is required for every epoch. */
+export interface ReplicationBaselinePacket extends ReplicationDataPacketBase {
+    readonly kind: 'baseline';
+    readonly sequence: 1;
+}
+/** Ordered authoritative delta after the accepted baseline. */
+export interface ReplicationDeltaPacket extends ReplicationDataPacketBase {
+    readonly kind: 'delta';
+    readonly sequence: number;
+}
+export type ReplicationDataPacket = ReplicationBaselinePacket | ReplicationDeltaPacket;
+export interface ReplicationAckPacket {
+    readonly version: 2;
+    readonly kind: 'ack';
+    readonly sessionId: SessionId;
+    readonly epoch: number;
+    readonly acknowledgedSequence: number;
+}
+export interface ReplicationRejectionPacket {
+    readonly version: 2;
+    readonly kind: 'rejection';
+    readonly sessionId: SessionId;
+    readonly epoch: number;
+    readonly sequence: number;
+    readonly rejectedKind: ReplicationPacketKind;
+    readonly reason: string;
+}
+export type ReplicationPacket = ReplicationSessionPacket | ReplicationBaselinePacket | ReplicationDeltaPacket | ReplicationAckPacket | ReplicationRejectionPacket;
+export type ReplicationDataPacketKind = ReplicationDataPacket['kind'];
+//# sourceMappingURL=protocol.d.ts.map

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

@@ -1,12 +1,12 @@
 import type { Component, EntityHandle, World } from '@forgeax/engine-ecs';
 import { type Result } from '@forgeax/engine-types';
 import type { NetEndpoint } from '../endpoint/endpoint';
-import { type ReplicationBatch } from './codec';
 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?: NetEndpoint);
+    constructor(world: World, profile: ReplicationProfile, _endpoint?: unknown);
     entityFor(id: number): EntityHandle | undefined;
     readComponent(id: number, component: Component): Record<string, unknown> | undefined;
     snapshot(): readonly {
@@ -18,10 +18,13 @@ export declare class ReplicaCoordinator {
     clear(): void;
     get stopped(): boolean;
     get tick(): number;
-    validate(batch: ReplicationBatch): NetError | null;
-    apply(batch: ReplicationBatch): Result<void, NetError>;
+    /** 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 applyReplicaBatch(replica: ReplicaCoordinator, batch: ReplicationBatch): Result<void, NetError>;
-export declare function decodeAndApplyReplicaBatch(replica: ReplicaCoordinator, bytes: Uint8Array, limits: ReplicationLimits): Result<void, NetError>;
+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

@@ -1 +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;AACxD,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEvE,qBAAa,kBAAkB;;gBAOjB,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EAAE,WAAW;IAK7E,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;IAGlB,6EAA6E;IAC7E,KAAK,IAAI,IAAI;IAIb,IAAI,OAAO,IAAI,OAAO,CAErB;IACD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAOD,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,QAAQ,GAAG,IAAI;IAiFlD,KAAK,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC;CAwEvD;AACD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,CAAC,EAAE,WAAW,GACrB,kBAAkB,CAEpB;AACD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,gBAAgB,GACtB,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAExB;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAOxB"}
+{"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;IAiHxD,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

@@ -1,20 +1,42 @@
 import { type Result } from '@forgeax/engine-types';
-import type { NetEndpoint, PeerId } from '../endpoint/endpoint';
-import type { EndpointError } from '../endpoint/errors';
+import type { NetEndpoint, NetEndpointConnector, PeerId } from '../endpoint/endpoint';
+import { type EndpointError } from '../endpoint/errors';
 import type { AuthorityCoordinator } from '../replication/authority';
-import type { NetError } from '../replication/errors';
-import type { ReplicationLimits } from '../replication/profile';
+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 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 {
@@ -23,10 +45,22 @@ export declare class NetSession {
     receiveEvents(): readonly NetError[];
     drainRawMessages(): RawMessage[];
     getPeerSnapshot(): PeerSnapshot;
-    sendRaw(peerId: PeerId, data: Uint8Array): Result<void, EndpointError>;
+    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

@@ -1 +1 @@
-{"version":3,"file":"net-session.d.ts","sourceRoot":"","sources":["../../src/session/net-session.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE7F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,qBAAa,UAAU;;gBAWT,MAAM,EAAE,gBAAgB;IAKpC,aAAa,IAAI,SAAS,QAAQ,EAAE;IA4BpC,gBAAgB,IAAI,UAAU,EAAE;IAIhC,eAAe,IAAI,YAAY;IAK/B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC;IAKtE,eAAe,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI;IAItD,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIzC,aAAa,CAAC,WAAW,EAAE,kBAAkB,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAI/E,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAC;CAqBlD"}
+{"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

@@ -1,7 +1,13 @@
 import type { Plugin } from '@forgeax/engine-plugin';
-import type { NetEndpoint } from '../endpoint/endpoint';
+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 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;

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

@@ -1 +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,MAAM,sBAAsB,CAAC;AAGxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAsCzD"}
+{"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

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-net",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,9 +22,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-ecs": "0.1.3",
-    "@forgeax/engine-plugin": "0.1.3",
-    "@forgeax/engine-types": "0.1.3"
+    "@forgeax/engine-ecs": "0.1.6",
+    "@forgeax/engine-plugin": "0.1.6",
+    "@forgeax/engine-types": "0.1.6"
   },
   "forgeax": {
     "metrics": {

package/src/endpoint/endpoint.ts

@@ -48,3 +48,11 @@ export interface NetEndpoint {
   /** 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/memory.ts

@@ -4,7 +4,7 @@
 
 import type { Result } from '@forgeax/engine-types';
 import { err, ok } from '@forgeax/engine-types';
-import type { EndpointEvent, NetEndpoint, PeerId } from './endpoint';
+import type { EndpointEvent, NetEndpoint, NetEndpointConnector, PeerId } from './endpoint';
 import type { EndpointError as EndpointErrorType } from './errors';
 import { ENDPOINT_ERROR_HINTS, ENDPOINT_EXPECTED, EndpointError } from './errors';
 
@@ -170,3 +170,25 @@ export function createMemoryEndpointPairWithController(): {
 
   return { endpoints: [epA, epB], controller };
 }
+
+/** Create a replaceable, realm-neutral connector over a deterministic endpoint factory. */
+export function createMemoryEndpointConnector(
+  createEndpoint: () => NetEndpoint,
+): NetEndpointConnector {
+  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()));
+    },
+  };
+}

package/src/index.ts

@@ -4,7 +4,7 @@
 // and @forgeax/engine-types (Result, errors). No WebSocket, browser, app, or runtime dependency.
 
 // Endpoint contract (requirements AC-02, AC-13)
-export type { EndpointEvent, NetEndpoint, PeerId } from './endpoint/endpoint';
+export type { EndpointEvent, NetEndpoint, NetEndpointConnector, PeerId } from './endpoint/endpoint';
 export type { EndpointErrorCode, EndpointErrorDetail } from './endpoint/errors';
 export {
   ENDPOINT_ERROR_HINTS,
@@ -15,32 +15,76 @@ export {
 export type { MemoryFaultController } from './endpoint/memory';
 // Memory endpoint (requirements AC-03)
 export {
+  createMemoryEndpointConnector,
   createMemoryEndpointPair,
   createMemoryEndpointPairWithController,
 } from './endpoint/memory';
 export { AuthorityCoordinator, createAuthorityCoordinator } from './replication/authority';
-export type {
-  NetEntityId,
-  ReplicationBatch,
-  ReplicationComponentRecord,
-  ReplicationEntityRecord,
-} from './replication/codec';
-export { NetError, type NetErrorCode, type NetErrorDetail } from './replication/errors';
+export { decodeReplicationPacket, encodeReplicationPacket } from './replication/codec';
+export {
+  REPLICATION_PROTOCOL_PREFIX,
+  REPLICATION_PROTOCOL_VERSION,
+} from './replication/constants';
+export {
+  NetError,
+  type NetErrorCode,
+  type NetErrorDetail,
+  type NetErrorDetailByCode,
+  type NetErrorDetailFor,
+} from './replication/errors';
 export { validateHandshake } from './replication/handshake';
 export type {
   DefineReplicationOptions,
   ReplicationLimits,
   ReplicationProfile,
 } from './replication/profile';
-export { defineReplication } from './replication/profile';
+export { DEFAULT_REPLICATION_LIMITS, defineReplication } from './replication/profile';
+export type {
+  ReplicationAckPacket,
+  ReplicationBaselinePacket,
+  ReplicationComponentRecord,
+  ReplicationDataPacket,
+  ReplicationDataPacketBase,
+  ReplicationDataPacketKind,
+  ReplicationDeltaPacket,
+  ReplicationEntityKind,
+  ReplicationEntityRecord,
+  ReplicationPacket,
+  ReplicationPacketKind,
+  ReplicationRejectionPacket,
+  ReplicationSessionPacket,
+} from './replication/protocol';
 export {
-  applyReplicaBatch,
+  applyReplicationPacket,
   createReplicaCoordinator,
-  decodeAndApplyReplicaBatch,
+  decodeAndApplyReplicationPacket,
   ReplicaCoordinator,
 } from './replication/replica';
-export type { NetSessionConfig, PeerSnapshot, RawMessage } from './session/net-session';
+export type {
+  NetSessionConfig,
+  PeerSnapshot,
+  RawMessage,
+  SessionSnapshot,
+} from './session/net-session';
 // Session (requirements AC-04)
 export { NetSession } from './session/net-session';
+export type {
+  NetRecoveryOutcome,
+  NetRecoveryPolicy,
+  NetRecoverySnapshot,
+  NetSessionFailure,
+  NetSessionState,
+  NetSessionStateKind,
+  SessionId,
+} from './session/recovery';
+export {
+  createSessionId,
+  DEFAULT_NET_RECOVERY_POLICY,
+  isLegalNetSessionTransition,
+  RECOVERY_ERROR_CODES,
+  resolveNetRecoveryPolicy,
+  transitionNetSessionState,
+  validateNetRecoveryPolicy,
+} from './session/recovery';
 export type { NetPluginConfig } from './session/session-plugin';
 export { netPlugin } from './session/session-plugin';