tetherdb 0.1.0

package/dist/server/validate.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Security, input validation, and sanitization utilities for the TetherDB server.
+ * Protects server-side storage and synchronization from injection and traversal attacks.
+ *
+ * @module tetherdb/server/validate
+ */
+/** Minimum allowed username character length. */
+export declare const MIN_USERNAME_LENGTH = 4;
+/** Maximum allowed username character length. */
+export declare const MAX_USERNAME_LENGTH = 128;
+/** Minimum allowed password character length. */
+export declare const MIN_PASSWORD_LENGTH = 4;
+/** Maximum allowed password character length. */
+export declare const MAX_PASSWORD_LENGTH = 512;
+/** Maximum allowable future timestamp drift in milliseconds (5 minutes). */
+export declare const MAX_FUTURE_TIMESTAMP_DRIFT_MS: number;
+/**
+ * Validates a change timestamp, ensuring it is a valid finite epoch number
+ * and does not exceed the maximum allowable future drift.
+ *
+ * @param timestamp - The epoch timestamp in milliseconds.
+ * @param maxFutureDriftMs - Optional maximum allowable future drift in ms (defaults to 5 minutes).
+ * @returns The validated timestamp.
+ * @throws TetherServerError if timestamp is not finite, is non-positive, or exceeds drift bounds.
+ */
+export declare function validateTimestamp(timestamp: number, maxFutureDriftMs?: number): number;
+/**
+ * Validates a user ID string ensuring it is safe for filesystem use.
+ *
+ * @param userId - The user ID to validate.
+ * @returns The validated user ID.
+ * @throws TetherServerError if the user ID is invalid or contains unsafe characters.
+ */
+export declare function validateUserId(userId: string): string;
+/**
+ * Validates an application namespace identifier.
+ *
+ * @param appId - The application ID to validate.
+ * @returns The validated application ID.
+ * @throws TetherServerError if the application ID is invalid.
+ */
+export declare function validateAppId(appId: string): string;
+/**
+ * Validates a table name ensuring it is safe for filesystem use.
+ *
+ * @param tableName - The table name to validate.
+ * @returns The validated table name.
+ * @throws TetherServerError if the table name is invalid.
+ */
+export declare function validateTableName(tableName: string): string;
+/**
+ * Validates a record ID ensuring it is a non-empty string within size limits.
+ *
+ * @param id - The record identifier to validate.
+ * @returns The validated record ID.
+ * @throws TetherServerError if the record ID is invalid or exceeds max length.
+ */
+export declare function validateRecordId(id: string): string;
+/**
+ * Normalizes a username by trimming whitespace and converting to lowercase.
+ *
+ * @param username - The raw username string.
+ * @returns The normalized username (lowercase and trimmed).
+ */
+export declare function normalizeUsername(username: string): string;
+/**
+ * Validates and normalizes a username for account creation or authentication.
+ * Usernames must be between 4 and 128 characters long.
+ *
+ * @param username - The username to validate.
+ * @returns The validated and normalized username (trimmed and lowercase).
+ * @throws TetherServerError if the username is invalid or out of length bounds.
+ */
+export declare function validateUsername(username: string): string;
+/**
+ * Normalizes a password by trimming surrounding whitespace.
+ *
+ * @param password - The raw password string.
+ * @returns The normalized password (trimmed).
+ */
+export declare function normalizePassword(password: string): string;
+/**
+ * Validates a password for user account creation or authentication.
+ *
+ * @param password - The password string to validate.
+ * @returns The validated password.
+ * @throws TetherServerError if the password is not a string, is empty, or exceeds length bounds.
+ */
+export declare function validatePassword(password: string): string;
+/**
+ * Validates a client correlation or batch ID.
+ *
+ * @param id - The batch or client identifier.
+ * @param name - Identifier type description (e.g. 'batchId', 'clientId').
+ * @returns The validated ID.
+ * @throws TetherServerError if the identifier format is invalid.
+ */
+export declare function validateIdentifier(id: string, name?: string): string;
+/**
+ * Estimates the byte size of an arbitrary JavaScript value or object when serialized.
+ *
+ * @param value - The value to measure.
+ * @returns Size in bytes.
+ */
+export declare function calculateByteSize(value: unknown): number;
+/**
+ * Calculates a 2-character hex/hash bucket for directory partitioning by user ID.
+ *
+ * @param userId - Unique user identifier.
+ * @returns 2-character bucket string (e.g. 'f4', '0a').
+ */
+export declare function getUserBucket(userId: string): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/server/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/server/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,4EAA4E;AAC5E,eAAO,MAAM,6BAA6B,QAAgB,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,gBAAgB,SAAgC,GAC/C,MAAM,CAkBR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkBzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkBzD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,SAAe,GAAG,MAAM,CAQ1E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUxD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIpD"}

package/dist/shared/clock.d.cts

@@ -0,0 +1,22 @@
+import type { ChangeRecord, StoredRecord } from './types.cjs';
+/**
+ * Determines whether an incoming mutation should overwrite an existing stored record
+ * using Last-Write-Wins (LWW) conflict resolution.
+ *
+ * Conflict resolution rules:
+ * 1. If no existing record exists, returns `true`.
+ * 2. If incoming timestamp is strictly greater, returns `true`.
+ * 3. If incoming timestamp is strictly less, returns `false`.
+ * 4. If timestamps are equal, performs deterministic lexicographical tie-breaking using `clientId`.
+ *
+ * @param incoming - The candidate change record with timestamp and optional client metadata.
+ * @param existing - The current record stored locally or on the server.
+ * @returns `true` if the incoming change wins the conflict and should overwrite the existing record; otherwise `false`.
+ */
+export declare function shouldOverwrite(incoming: Pick<ChangeRecord, 'timestamp'> & {
+    clientId?: string;
+    version?: number;
+}, existing?: Pick<StoredRecord, 'timestamp' | 'version'> & {
+    clientId?: string;
+}): boolean;
+//# sourceMappingURL=clock.d.ts.map

package/dist/shared/clock.d.ts

@@ -0,0 +1,22 @@
+import type { ChangeRecord, StoredRecord } from './types.js';
+/**
+ * Determines whether an incoming mutation should overwrite an existing stored record
+ * using Last-Write-Wins (LWW) conflict resolution.
+ *
+ * Conflict resolution rules:
+ * 1. If no existing record exists, returns `true`.
+ * 2. If incoming timestamp is strictly greater, returns `true`.
+ * 3. If incoming timestamp is strictly less, returns `false`.
+ * 4. If timestamps are equal, performs deterministic lexicographical tie-breaking using `clientId`.
+ *
+ * @param incoming - The candidate change record with timestamp and optional client metadata.
+ * @param existing - The current record stored locally or on the server.
+ * @returns `true` if the incoming change wins the conflict and should overwrite the existing record; otherwise `false`.
+ */
+export declare function shouldOverwrite(incoming: Pick<ChangeRecord, 'timestamp'> & {
+    clientId?: string;
+    version?: number;
+}, existing?: Pick<StoredRecord, 'timestamp' | 'version'> & {
+    clientId?: string;
+}): boolean;
+//# sourceMappingURL=clock.d.ts.map

package/dist/shared/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/shared/clock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,EACD,QAAQ,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC,GAAG;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAaT"}

package/dist/shared/path.d.cts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for path normalization across client and server.
+ */
+/**
+ * Normalizes a base path ensuring it starts with a leading slash and has no trailing slash.
+ * An empty string or single slash normalizes to an empty string.
+ *
+ * @param path - The base path to normalize.
+ * @returns Normalized base path (e.g. '/api' or '').
+ */
+export declare function normalizeBasePath(path: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/shared/path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for path normalization across client and server.
+ */
+/**
+ * Normalizes a base path ensuring it starts with a leading slash and has no trailing slash.
+ * An empty string or single slash normalizes to an empty string.
+ *
+ * @param path - The base path to normalize.
+ * @returns Normalized base path (e.g. '/api' or '').
+ */
+export declare function normalizeBasePath(path: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/shared/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/shared/path.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD"}

package/dist/shared/types.d.cts

@@ -0,0 +1,234 @@
+/**
+ * The type of mutation operation performed on a record.
+ */
+export declare enum OperationType {
+    /** Insert or update a record payload. */
+    Put = "put",
+    /** Delete a record (tombstone). */
+    Delete = "delete"
+}
+/**
+ * Represents an individual mutation operation record to be synced.
+ *
+ * @typeParam T - The data type of the record payload.
+ */
+export interface ChangeRecord<T = unknown> {
+    /** The target table name. */
+    table: string;
+    /** The unique record identifier within the table. */
+    id: string;
+    /** The mutation operation type. */
+    op: OperationType;
+    /** The data payload for 'put' operations. */
+    data?: T;
+    /** Monotonic epoch timestamp when the change was initiated. */
+    timestamp: number;
+    /** Identifier of the client that originated the change. */
+    clientId: string;
+    /** Incremental version counter for the record. */
+    version?: number;
+    /** Server-assigned global sequential index. */
+    seq?: number;
+}
+/**
+ * Represents a persisted record with local metadata.
+ *
+ * @typeParam T - The data type of the stored record value.
+ */
+export interface StoredRecord<T = unknown> {
+    /** The unique record identifier. */
+    id: string;
+    /** The stored value payload. */
+    data: T;
+    /** Epoch timestamp of the last write. */
+    timestamp: number;
+    /** Record revision version. */
+    version: number;
+    /** Flag indicating whether the record is marked as deleted (tombstone). */
+    deleted?: boolean;
+    /** Identifier of client that performed the write. */
+    clientId?: string;
+}
+/**
+ * Represents a single record entry in a full database snapshot.
+ *
+ * @typeParam T - The data type of the record payload.
+ */
+export interface SnapshotRecord<T = unknown> extends StoredRecord<T> {
+    /** The table name. */
+    table: string;
+}
+/**
+ * Current wire protocol version number.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * Types of messages sent from the client to the server over the WebSocket sync connection.
+ */
+export declare enum ClientMessageType {
+    /** Authenticate connection with user token and initial sync sequence. */
+    Auth = "auth",
+    /** Submit a batch of local pending changes to the server. */
+    ChangeBatch = "change_batch",
+    /** Heartbeat ping message to verify connection liveness. */
+    Ping = "ping"
+}
+/**
+ * Client authentication handshake message.
+ */
+export interface AuthClientMessage {
+    type: ClientMessageType.Auth;
+    /** Wire protocol version number (must equal `PROTOCOL_VERSION`). */
+    protocolVersion: number;
+    /** Signed authentication session token. */
+    token: string;
+    /** Unique client instance identifier. */
+    clientId: string;
+    /** Last synchronized sequence number known to the client. */
+    lastSyncSeq?: number;
+    /** Application namespace identifier. */
+    appId: string;
+    /** Optional client capabilities supported by this client session. */
+    capabilities?: string[];
+}
+/**
+ * Client mutation batch message.
+ */
+export interface ChangeBatchClientMessage {
+    type: ClientMessageType.ChangeBatch;
+    /** Unique client instance identifier. */
+    clientId: string;
+    /** Unique batch correlation identifier. */
+    batchId: string;
+    /** Array of change operations to apply. */
+    changes: ChangeRecord[];
+}
+/**
+ * Client heartbeat ping message.
+ */
+export interface PingClientMessage {
+    type: ClientMessageType.Ping;
+}
+/**
+ * Discriminated union of all messages sent from client to server.
+ */
+export type ClientMessage = AuthClientMessage | ChangeBatchClientMessage | PingClientMessage;
+/**
+ * Types of messages sent from the server to the client over the WebSocket sync connection.
+ */
+export declare enum ServerMessageType {
+    /** Authentication succeeded. */
+    AuthSuccess = "auth_success",
+    /** Authentication failed. */
+    AuthError = "auth_error",
+    /** Full dataset snapshot sent when client connects without prior sync sequence. */
+    SyncSnapshot = "sync_snapshot",
+    /** Delta diff of changes that occurred since client's lastSyncSeq. */
+    SyncDiff = "sync_diff",
+    /** Confirmation that a client change batch was applied. */
+    ChangeAck = "change_ack",
+    /** Real-time broadcast of changes applied by another client session of the same user. */
+    BroadcastChanges = "broadcast_changes",
+    /** Heartbeat pong response. */
+    Pong = "pong",
+    /** General server error notification. */
+    Error = "error"
+}
+/**
+ * Server authentication success response message.
+ */
+export interface AuthSuccessServerMessage {
+    type: ServerMessageType.AuthSuccess;
+    /** Wire protocol version number. */
+    protocolVersion: number;
+    /** Authenticated user account identifier. */
+    userId: string;
+    /** Current global sequence number of the user's data on the server. */
+    currentSeq: number;
+    /** Refreshed session token for sliding session validity. */
+    token?: string;
+    /** Optional server capabilities supported by this server instance. */
+    capabilities?: string[];
+}
+/**
+ * Server authentication failure response message.
+ */
+export interface AuthErrorServerMessage {
+    type: ServerMessageType.AuthError;
+    /** Error description message. */
+    message: string;
+}
+/**
+ * Server full dataset snapshot message.
+ */
+export interface SyncSnapshotServerMessage {
+    type: ServerMessageType.SyncSnapshot;
+    /** Sequence number corresponding to the snapshot state. */
+    seq: number;
+    /** All active records across tables. */
+    snapshot: SnapshotRecord[];
+}
+/**
+ * Server incremental delta diff message.
+ */
+export interface SyncDiffServerMessage {
+    type: ServerMessageType.SyncDiff;
+    /** Starting sequence number (exclusive). */
+    fromSeq: number;
+    /** Ending sequence number (inclusive). */
+    toSeq: number;
+    /** Array of applied changes in sequential order. */
+    changes: ChangeRecord[];
+}
+/**
+ * Server batch acknowledgement message.
+ */
+export interface ChangeAckServerMessage {
+    type: ServerMessageType.ChangeAck;
+    /** The correlation identifier of the acknowledged batch. */
+    batchId: string;
+    /** The new global sequence number after applying the batch. */
+    appliedSeq: number;
+}
+/**
+ * Server real-time changes broadcast message.
+ */
+export interface BroadcastChangesServerMessage {
+    type: ServerMessageType.BroadcastChanges;
+    /** Client ID that originated the change. */
+    fromClientId: string;
+    /** Global sequence number assigned to these changes. */
+    seq: number;
+    /** Array of applied changes. */
+    changes: ChangeRecord[];
+}
+/**
+ * Server heartbeat pong response message.
+ */
+export interface PongServerMessage {
+    type: ServerMessageType.Pong;
+}
+/**
+ * Server error notification message.
+ */
+export interface ErrorServerMessage {
+    type: ServerMessageType.Error;
+    /** Error description message. */
+    message: string;
+}
+/**
+ * Discriminated union of all messages sent from server to client.
+ */
+export type ServerMessage = AuthSuccessServerMessage | AuthErrorServerMessage | SyncSnapshotServerMessage | SyncDiffServerMessage | ChangeAckServerMessage | BroadcastChangesServerMessage | PongServerMessage | ErrorServerMessage;
+/**
+ * Metadata stored locally tracking synchronization progress.
+ */
+export interface SyncMetadata {
+    /** The latest sequence number synchronized with the server. */
+    lastSyncSeq: number;
+    /** Epoch timestamp of the last successful synchronization. */
+    lastSyncTimestamp: number;
+    /** Unique client instance identifier. */
+    clientId: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts

@@ -0,0 +1,234 @@
+/**
+ * The type of mutation operation performed on a record.
+ */
+export declare enum OperationType {
+    /** Insert or update a record payload. */
+    Put = "put",
+    /** Delete a record (tombstone). */
+    Delete = "delete"
+}
+/**
+ * Represents an individual mutation operation record to be synced.
+ *
+ * @typeParam T - The data type of the record payload.
+ */
+export interface ChangeRecord<T = unknown> {
+    /** The target table name. */
+    table: string;
+    /** The unique record identifier within the table. */
+    id: string;
+    /** The mutation operation type. */
+    op: OperationType;
+    /** The data payload for 'put' operations. */
+    data?: T;
+    /** Monotonic epoch timestamp when the change was initiated. */
+    timestamp: number;
+    /** Identifier of the client that originated the change. */
+    clientId: string;
+    /** Incremental version counter for the record. */
+    version?: number;
+    /** Server-assigned global sequential index. */
+    seq?: number;
+}
+/**
+ * Represents a persisted record with local metadata.
+ *
+ * @typeParam T - The data type of the stored record value.
+ */
+export interface StoredRecord<T = unknown> {
+    /** The unique record identifier. */
+    id: string;
+    /** The stored value payload. */
+    data: T;
+    /** Epoch timestamp of the last write. */
+    timestamp: number;
+    /** Record revision version. */
+    version: number;
+    /** Flag indicating whether the record is marked as deleted (tombstone). */
+    deleted?: boolean;
+    /** Identifier of client that performed the write. */
+    clientId?: string;
+}
+/**
+ * Represents a single record entry in a full database snapshot.
+ *
+ * @typeParam T - The data type of the record payload.
+ */
+export interface SnapshotRecord<T = unknown> extends StoredRecord<T> {
+    /** The table name. */
+    table: string;
+}
+/**
+ * Current wire protocol version number.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * Types of messages sent from the client to the server over the WebSocket sync connection.
+ */
+export declare enum ClientMessageType {
+    /** Authenticate connection with user token and initial sync sequence. */
+    Auth = "auth",
+    /** Submit a batch of local pending changes to the server. */
+    ChangeBatch = "change_batch",
+    /** Heartbeat ping message to verify connection liveness. */
+    Ping = "ping"
+}
+/**
+ * Client authentication handshake message.
+ */
+export interface AuthClientMessage {
+    type: ClientMessageType.Auth;
+    /** Wire protocol version number (must equal `PROTOCOL_VERSION`). */
+    protocolVersion: number;
+    /** Signed authentication session token. */
+    token: string;
+    /** Unique client instance identifier. */
+    clientId: string;
+    /** Last synchronized sequence number known to the client. */
+    lastSyncSeq?: number;
+    /** Application namespace identifier. */
+    appId: string;
+    /** Optional client capabilities supported by this client session. */
+    capabilities?: string[];
+}
+/**
+ * Client mutation batch message.
+ */
+export interface ChangeBatchClientMessage {
+    type: ClientMessageType.ChangeBatch;
+    /** Unique client instance identifier. */
+    clientId: string;
+    /** Unique batch correlation identifier. */
+    batchId: string;
+    /** Array of change operations to apply. */
+    changes: ChangeRecord[];
+}
+/**
+ * Client heartbeat ping message.
+ */
+export interface PingClientMessage {
+    type: ClientMessageType.Ping;
+}
+/**
+ * Discriminated union of all messages sent from client to server.
+ */
+export type ClientMessage = AuthClientMessage | ChangeBatchClientMessage | PingClientMessage;
+/**
+ * Types of messages sent from the server to the client over the WebSocket sync connection.
+ */
+export declare enum ServerMessageType {
+    /** Authentication succeeded. */
+    AuthSuccess = "auth_success",
+    /** Authentication failed. */
+    AuthError = "auth_error",
+    /** Full dataset snapshot sent when client connects without prior sync sequence. */
+    SyncSnapshot = "sync_snapshot",
+    /** Delta diff of changes that occurred since client's lastSyncSeq. */
+    SyncDiff = "sync_diff",
+    /** Confirmation that a client change batch was applied. */
+    ChangeAck = "change_ack",
+    /** Real-time broadcast of changes applied by another client session of the same user. */
+    BroadcastChanges = "broadcast_changes",
+    /** Heartbeat pong response. */
+    Pong = "pong",
+    /** General server error notification. */
+    Error = "error"
+}
+/**
+ * Server authentication success response message.
+ */
+export interface AuthSuccessServerMessage {
+    type: ServerMessageType.AuthSuccess;
+    /** Wire protocol version number. */
+    protocolVersion: number;
+    /** Authenticated user account identifier. */
+    userId: string;
+    /** Current global sequence number of the user's data on the server. */
+    currentSeq: number;
+    /** Refreshed session token for sliding session validity. */
+    token?: string;
+    /** Optional server capabilities supported by this server instance. */
+    capabilities?: string[];
+}
+/**
+ * Server authentication failure response message.
+ */
+export interface AuthErrorServerMessage {
+    type: ServerMessageType.AuthError;
+    /** Error description message. */
+    message: string;
+}
+/**
+ * Server full dataset snapshot message.
+ */
+export interface SyncSnapshotServerMessage {
+    type: ServerMessageType.SyncSnapshot;
+    /** Sequence number corresponding to the snapshot state. */
+    seq: number;
+    /** All active records across tables. */
+    snapshot: SnapshotRecord[];
+}
+/**
+ * Server incremental delta diff message.
+ */
+export interface SyncDiffServerMessage {
+    type: ServerMessageType.SyncDiff;
+    /** Starting sequence number (exclusive). */
+    fromSeq: number;
+    /** Ending sequence number (inclusive). */
+    toSeq: number;
+    /** Array of applied changes in sequential order. */
+    changes: ChangeRecord[];
+}
+/**
+ * Server batch acknowledgement message.
+ */
+export interface ChangeAckServerMessage {
+    type: ServerMessageType.ChangeAck;
+    /** The correlation identifier of the acknowledged batch. */
+    batchId: string;
+    /** The new global sequence number after applying the batch. */
+    appliedSeq: number;
+}
+/**
+ * Server real-time changes broadcast message.
+ */
+export interface BroadcastChangesServerMessage {
+    type: ServerMessageType.BroadcastChanges;
+    /** Client ID that originated the change. */
+    fromClientId: string;
+    /** Global sequence number assigned to these changes. */
+    seq: number;
+    /** Array of applied changes. */
+    changes: ChangeRecord[];
+}
+/**
+ * Server heartbeat pong response message.
+ */
+export interface PongServerMessage {
+    type: ServerMessageType.Pong;
+}
+/**
+ * Server error notification message.
+ */
+export interface ErrorServerMessage {
+    type: ServerMessageType.Error;
+    /** Error description message. */
+    message: string;
+}
+/**
+ * Discriminated union of all messages sent from server to client.
+ */
+export type ServerMessage = AuthSuccessServerMessage | AuthErrorServerMessage | SyncSnapshotServerMessage | SyncDiffServerMessage | ChangeAckServerMessage | BroadcastChangesServerMessage | PongServerMessage | ErrorServerMessage;
+/**
+ * Metadata stored locally tracking synchronization progress.
+ */
+export interface SyncMetadata {
+    /** The latest sequence number synchronized with the server. */
+    lastSyncSeq: number;
+    /** Epoch timestamp of the last successful synchronization. */
+    lastSyncTimestamp: number;
+    /** Unique client instance identifier. */
+    clientId: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

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