@continuum-dev/session 0.1.0

package/lib/session/intent-manager.d.ts

@@ -0,0 +1,34 @@
+import type { PendingIntent } from '@continuum/contract';
+import type { SessionState } from './session-state.js';
+/**
+ * Queues a pending intent on the current view version.
+ *
+ * @param internal Mutable internal session state.
+ * @param partial Intent payload without generated metadata.
+ */
+export declare function submitIntent(internal: SessionState, partial: Omit<PendingIntent, 'intentId' | 'queuedAt' | 'status' | 'viewVersion'>): void;
+/**
+ * Marks an intent as validated.
+ *
+ * @param internal Mutable internal session state.
+ * @param intentId Target intent id.
+ * @returns True when the intent exists.
+ */
+export declare function validateIntent(internal: SessionState, intentId: string): boolean;
+/**
+ * Marks an intent as cancelled.
+ *
+ * @param internal Mutable internal session state.
+ * @param intentId Target intent id.
+ * @returns True when the intent exists.
+ */
+export declare function cancelIntent(internal: SessionState, intentId: string): boolean;
+/**
+ * Marks all currently pending intents as stale.
+ *
+ * Used when view version changes invalidate unresolved intents.
+ *
+ * @param internal Mutable internal session state.
+ */
+export declare function markAllPendingIntentsAsStale(internal: SessionState): void;
+//# sourceMappingURL=intent-manager.d.ts.map

package/lib/session/intent-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-manager.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/intent-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC,GAC/E,IAAI,CAiBN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKhF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK9E;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAMzE"}

package/lib/session/intent-manager.js

@@ -0,0 +1,67 @@
+import { INTENT_STATUS } from '@continuum/contract';
+import { generateId } from './session-state.js';
+/**
+ * Queues a pending intent on the current view version.
+ *
+ * @param internal Mutable internal session state.
+ * @param partial Intent payload without generated metadata.
+ */
+export function submitIntent(internal, partial) {
+    if (internal.destroyed || !internal.currentView)
+        return;
+    const intent = {
+        intentId: generateId('intent', internal.clock),
+        nodeId: partial.nodeId,
+        intentName: partial.intentName,
+        payload: partial.payload,
+        queuedAt: internal.clock(),
+        viewVersion: internal.currentView.version,
+        status: INTENT_STATUS.PENDING,
+    };
+    internal.pendingIntents.push(intent);
+    if (internal.pendingIntents.length > internal.maxPendingIntents) {
+        internal.pendingIntents.splice(0, internal.pendingIntents.length - internal.maxPendingIntents);
+    }
+}
+/**
+ * Marks an intent as validated.
+ *
+ * @param internal Mutable internal session state.
+ * @param intentId Target intent id.
+ * @returns True when the intent exists.
+ */
+export function validateIntent(internal, intentId) {
+    const intent = internal.pendingIntents.find((a) => a.intentId === intentId);
+    if (!intent)
+        return false;
+    intent.status = INTENT_STATUS.VALIDATED;
+    return true;
+}
+/**
+ * Marks an intent as cancelled.
+ *
+ * @param internal Mutable internal session state.
+ * @param intentId Target intent id.
+ * @returns True when the intent exists.
+ */
+export function cancelIntent(internal, intentId) {
+    const intent = internal.pendingIntents.find((a) => a.intentId === intentId);
+    if (!intent)
+        return false;
+    intent.status = INTENT_STATUS.CANCELLED;
+    return true;
+}
+/**
+ * Marks all currently pending intents as stale.
+ *
+ * Used when view version changes invalidate unresolved intents.
+ *
+ * @param internal Mutable internal session state.
+ */
+export function markAllPendingIntentsAsStale(internal) {
+    for (const intent of internal.pendingIntents) {
+        if (intent.status === INTENT_STATUS.PENDING) {
+            intent.status = INTENT_STATUS.STALE;
+        }
+    }
+}

package/lib/session/listeners.d.ts

@@ -0,0 +1,49 @@
+import type { ContinuitySnapshot } from '@continuum/contract';
+import type { ReconciliationIssue } from '@continuum/runtime';
+import type { SessionState } from './session-state.js';
+/**
+ * Builds a continuity snapshot from internal view/data state.
+ *
+ * @param internal Mutable internal session state.
+ * @returns Snapshot when both view and data are present, otherwise null.
+ */
+export declare function buildSnapshotFromCurrentState(internal: SessionState): ContinuitySnapshot | null;
+/**
+ * Notifies all snapshot listeners with the latest snapshot value.
+ *
+ * Listener exceptions are swallowed so one faulty subscriber cannot block others.
+ *
+ * @param internal Mutable internal session state.
+ */
+export declare function notifySnapshotListeners(internal: SessionState): void;
+/**
+ * Notifies all issue listeners with a cloned issue array.
+ *
+ * Listener exceptions are swallowed so one faulty subscriber cannot block others.
+ *
+ * @param internal Mutable internal session state.
+ */
+export declare function notifyIssueListeners(internal: SessionState): void;
+/**
+ * Notifies snapshot listeners, then issue listeners.
+ *
+ * @param internal Mutable internal session state.
+ */
+export declare function notifySnapshotAndIssueListeners(internal: SessionState): void;
+/**
+ * Registers a snapshot listener.
+ *
+ * @param internal Mutable internal session state.
+ * @param listener Snapshot callback.
+ * @returns Unsubscribe function.
+ */
+export declare function subscribeSnapshot(internal: SessionState, listener: (snapshot: ContinuitySnapshot | null) => void): () => void;
+/**
+ * Registers an issue listener.
+ *
+ * @param internal Mutable internal session state.
+ * @param listener Issues callback.
+ * @returns Unsubscribe function.
+ */
+export declare function subscribeIssues(internal: SessionState, listener: (issues: ReconciliationIssue[]) => void): () => void;
+//# sourceMappingURL=listeners.d.ts.map

package/lib/session/listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/listeners.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,GAAG,IAAI,CAG/F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CASpE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAQjE;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAG5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,KAAK,IAAI,GACtD,MAAM,IAAI,CAGZ;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,IAAI,GAChD,MAAM,IAAI,CAGZ"}

package/lib/session/listeners.js

@@ -0,0 +1,77 @@
+/**
+ * Builds a continuity snapshot from internal view/data state.
+ *
+ * @param internal Mutable internal session state.
+ * @returns Snapshot when both view and data are present, otherwise null.
+ */
+export function buildSnapshotFromCurrentState(internal) {
+    if (!internal.currentView || !internal.currentData)
+        return null;
+    return { view: internal.currentView, data: internal.currentData };
+}
+/**
+ * Notifies all snapshot listeners with the latest snapshot value.
+ *
+ * Listener exceptions are swallowed so one faulty subscriber cannot block others.
+ *
+ * @param internal Mutable internal session state.
+ */
+export function notifySnapshotListeners(internal) {
+    const snapshot = buildSnapshotFromCurrentState(internal);
+    for (const listener of internal.snapshotListeners) {
+        try {
+            listener(snapshot);
+        }
+        catch {
+            continue;
+        }
+    }
+}
+/**
+ * Notifies all issue listeners with a cloned issue array.
+ *
+ * Listener exceptions are swallowed so one faulty subscriber cannot block others.
+ *
+ * @param internal Mutable internal session state.
+ */
+export function notifyIssueListeners(internal) {
+    for (const listener of internal.issueListeners) {
+        try {
+            listener([...internal.issues]);
+        }
+        catch {
+            continue;
+        }
+    }
+}
+/**
+ * Notifies snapshot listeners, then issue listeners.
+ *
+ * @param internal Mutable internal session state.
+ */
+export function notifySnapshotAndIssueListeners(internal) {
+    notifySnapshotListeners(internal);
+    notifyIssueListeners(internal);
+}
+/**
+ * Registers a snapshot listener.
+ *
+ * @param internal Mutable internal session state.
+ * @param listener Snapshot callback.
+ * @returns Unsubscribe function.
+ */
+export function subscribeSnapshot(internal, listener) {
+    internal.snapshotListeners.add(listener);
+    return () => { internal.snapshotListeners.delete(listener); };
+}
+/**
+ * Registers an issue listener.
+ *
+ * @param internal Mutable internal session state.
+ * @param listener Issues callback.
+ * @returns Unsubscribe function.
+ */
+export function subscribeIssues(internal, listener) {
+    internal.issueListeners.add(listener);
+    return () => { internal.issueListeners.delete(listener); };
+}

package/lib/session/persistence.d.ts

@@ -0,0 +1,14 @@
+import type { SessionState } from './session-state.js';
+import type { SessionPersistenceOptions } from '../types.js';
+/**
+ * Attaches persistence synchronization to a session.
+ *
+ * Persists snapshots to storage with debounce and applies remote `storage` events
+ * (for example, cross-tab updates) back into the active session state.
+ *
+ * @param internal Mutable internal session state.
+ * @param options Persistence storage options.
+ * @returns Cleanup function that unsubscribes listeners and removes event handlers.
+ */
+export declare function attachPersistence(internal: SessionState, options: SessionPersistenceOptions): () => void;
+//# sourceMappingURL=persistence.d.ts.map

package/lib/session/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAkB7D;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,yBAAyB,GACjC,MAAM,IAAI,CAsEZ"}

package/lib/session/persistence.js

@@ -0,0 +1,99 @@
+import { replaceInternalState } from './session-state.js';
+import { subscribeSnapshot, notifySnapshotAndIssueListeners } from './listeners.js';
+import { serializeSession, deserializeToState } from './serializer.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isMatchingStorageEvent(event, storage, key) {
+    if (!isRecord(event))
+        return false;
+    if (event.key !== key)
+        return false;
+    if (event.newValue === null || typeof event.newValue !== 'string')
+        return false;
+    if (event.storageArea !== undefined && event.storageArea !== storage)
+        return false;
+    return true;
+}
+/**
+ * Attaches persistence synchronization to a session.
+ *
+ * Persists snapshots to storage with debounce and applies remote `storage` events
+ * (for example, cross-tab updates) back into the active session state.
+ *
+ * @param internal Mutable internal session state.
+ * @param options Persistence storage options.
+ * @returns Cleanup function that unsubscribes listeners and removes event handlers.
+ */
+export function attachPersistence(internal, options) {
+    const key = options.key ?? 'continuum_session';
+    const storage = options.storage;
+    let timeout;
+    let isApplyingRemote = false;
+    const encoder = new TextEncoder();
+    const unsubscribe = subscribeSnapshot(internal, () => {
+        if (isApplyingRemote)
+            return;
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            try {
+                const payload = JSON.stringify(serializeSession(internal));
+                const attemptedBytes = encoder.encode(payload).byteLength;
+                if (typeof options.maxBytes === 'number'
+                    && Number.isFinite(options.maxBytes)
+                    && options.maxBytes >= 0
+                    && attemptedBytes > options.maxBytes) {
+                    options.onError?.({
+                        reason: 'size_limit',
+                        key,
+                        attemptedBytes,
+                        maxBytes: options.maxBytes,
+                    });
+                    return;
+                }
+                storage.setItem(key, payload);
+            }
+            catch (cause) {
+                options.onError?.({
+                    reason: 'storage_error',
+                    key,
+                    cause,
+                });
+            }
+        }, 200);
+    });
+    const onStorage = (event) => {
+        if (!isMatchingStorageEvent(event, storage, key))
+            return;
+        try {
+            const raw = JSON.parse(event.newValue);
+            const next = deserializeToState(raw, internal.clock, {
+                maxEventLogSize: internal.maxEventLogSize,
+                maxPendingIntents: internal.maxPendingIntents,
+                maxCheckpoints: internal.maxCheckpoints,
+            });
+            isApplyingRemote = true;
+            replaceInternalState(internal, next);
+            notifySnapshotAndIssueListeners(internal);
+        }
+        catch {
+        }
+        finally {
+            isApplyingRemote = false;
+        }
+    };
+    const maybeAdd = globalThis.addEventListener;
+    const maybeRemove = globalThis.removeEventListener;
+    if (maybeAdd) {
+        maybeAdd('storage', onStorage);
+    }
+    return () => {
+        if (timeout)
+            clearTimeout(timeout);
+        unsubscribe();
+        if (maybeRemove) {
+            maybeRemove('storage', onStorage);
+        }
+    };
+}

package/lib/session/schema-pusher.d.ts

@@ -0,0 +1,4 @@
+import type { SchemaSnapshot } from '@continuum/contract';
+import type { SessionState } from './session-state.js';
+export declare function pushSchema(internal: SessionState, schema: SchemaSnapshot): void;
+//# sourceMappingURL=schema-pusher.d.ts.map

package/lib/session/schema-pusher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-pusher.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/schema-pusher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiBvD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAgC/E"}

package/lib/session/serializer.d.ts

@@ -0,0 +1,25 @@
+import type { SessionState } from './session-state.js';
+/**
+ * Serializes internal session state into a JSON-compatible payload.
+ *
+ * @param internal Mutable internal session state.
+ * @returns Deep-cloned serialized payload.
+ */
+export declare function serializeSession(internal: SessionState): unknown;
+/**
+ * Deserializes a serialized session payload into internal session state.
+ *
+ * Accepts missing `formatVersion` for backward compatibility. When present,
+ * only version `1` is supported.
+ *
+ * @param data Serialized payload object.
+ * @param clock Clock source for resumed runtime operations.
+ * @param limits Optional caps for event log, pending intents, and checkpoints.
+ * @returns Reconstructed internal session state.
+ */
+export declare function deserializeToState(data: unknown, clock: () => number, limits?: {
+    maxEventLogSize?: number;
+    maxPendingIntents?: number;
+    maxCheckpoints?: number;
+}): SessionState;
+//# sourceMappingURL=serializer.d.ts.map

package/lib/session/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/serializer.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQvD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAmBhE;AAuFD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,MAAM,EACnB,MAAM,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GACzF,YAAY,CAoCd"}

package/lib/session/serializer.js

@@ -0,0 +1,126 @@
+import { isInteractionType } from '@continuum/contract';
+const CURRENT_FORMAT_VERSION = 1;
+function deepClone(value) {
+    return structuredClone(value);
+}
+/**
+ * Serializes internal session state into a JSON-compatible payload.
+ *
+ * @param internal Mutable internal session state.
+ * @returns Deep-cloned serialized payload.
+ */
+export function serializeSession(internal) {
+    return deepClone({
+        formatVersion: CURRENT_FORMAT_VERSION,
+        sessionId: internal.sessionId,
+        currentView: internal.currentView,
+        currentData: internal.currentData,
+        priorView: internal.priorView,
+        eventLog: internal.eventLog,
+        pendingIntents: internal.pendingIntents,
+        checkpoints: internal.checkpoints,
+        issues: internal.issues,
+        diffs: internal.diffs,
+        resolutions: internal.resolutions,
+        settings: {
+            allowBlindCarry: internal.reconciliationOptions?.allowBlindCarry,
+            allowPartialRestore: internal.reconciliationOptions?.allowPartialRestore,
+            validateOnUpdate: internal.validateOnUpdate,
+        },
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function assertArrayField(data, field) {
+    const value = data[field];
+    if (value !== undefined && !Array.isArray(value)) {
+        throw new Error(`Invalid serialized session: "${String(field)}" must be an array`);
+    }
+}
+function assertObjectOrNullField(data, field) {
+    const value = data[field];
+    if (value !== undefined && value !== null && !isRecord(value)) {
+        throw new Error(`Invalid serialized session: "${field}" must be an object or null`);
+    }
+}
+function assertValidEventLogTypes(data) {
+    const value = data.eventLog;
+    if (!Array.isArray(value))
+        return;
+    for (let i = 0; i < value.length; i++) {
+        const interaction = value[i];
+        if (!isRecord(interaction)) {
+            throw new Error(`Invalid serialized session: "eventLog[${i}]" must be an object`);
+        }
+        if (!isInteractionType(interaction.type)) {
+            throw new Error(`Invalid serialized session: "eventLog[${i}].type" must be a valid interaction type`);
+        }
+    }
+}
+function validateSerializedSessionData(data) {
+    if (!isRecord(data)) {
+        throw new Error('Invalid serialized session: expected an object');
+    }
+    if (typeof data.sessionId !== 'string') {
+        throw new Error('Invalid serialized session: "sessionId" must be a string');
+    }
+    if (data.formatVersion !== undefined &&
+        typeof data.formatVersion !== 'number') {
+        throw new Error('Invalid serialized session: "formatVersion" must be a number');
+    }
+    assertObjectOrNullField(data, 'currentView');
+    assertObjectOrNullField(data, 'currentData');
+    assertObjectOrNullField(data, 'priorView');
+    assertArrayField(data, 'eventLog');
+    assertArrayField(data, 'pendingIntents');
+    assertArrayField(data, 'checkpoints');
+    assertArrayField(data, 'issues');
+    assertArrayField(data, 'diffs');
+    assertArrayField(data, 'resolutions');
+    assertValidEventLogTypes(data);
+}
+/**
+ * Deserializes a serialized session payload into internal session state.
+ *
+ * Accepts missing `formatVersion` for backward compatibility. When present,
+ * only version `1` is supported.
+ *
+ * @param data Serialized payload object.
+ * @param clock Clock source for resumed runtime operations.
+ * @param limits Optional caps for event log, pending intents, and checkpoints.
+ * @returns Reconstructed internal session state.
+ */
+export function deserializeToState(data, clock, limits) {
+    validateSerializedSessionData(data);
+    const raw = data;
+    if (raw.formatVersion !== undefined && raw.formatVersion !== CURRENT_FORMAT_VERSION) {
+        throw new Error(`Unsupported format version ${raw.formatVersion}. This runtime supports version ${CURRENT_FORMAT_VERSION}.`);
+    }
+    return {
+        sessionId: raw.sessionId,
+        clock,
+        maxEventLogSize: limits?.maxEventLogSize ?? 1000,
+        maxPendingIntents: limits?.maxPendingIntents ?? 500,
+        maxCheckpoints: limits?.maxCheckpoints ?? 50,
+        reconciliationOptions: {
+            allowBlindCarry: raw.settings?.allowBlindCarry,
+            allowPartialRestore: raw.settings?.allowPartialRestore,
+        },
+        validateOnUpdate: raw.settings?.validateOnUpdate ?? false,
+        currentView: raw.currentView ?? null,
+        currentData: raw.currentData ?? null,
+        priorView: raw.priorView ?? null,
+        issues: raw.issues ?? [],
+        diffs: raw.diffs ?? [],
+        resolutions: raw.resolutions ?? [],
+        eventLog: (raw.eventLog ?? []).slice(-(limits?.maxEventLogSize ?? 1000)),
+        pendingIntents: (raw.pendingIntents ?? []).slice(-(limits?.maxPendingIntents ?? 500)),
+        checkpoints: (raw.checkpoints ?? []).slice(-(limits?.maxCheckpoints ?? 50)),
+        snapshotListeners: new Set(),
+        issueListeners: new Set(),
+        pendingProposals: {},
+        actionRegistry: new Map(),
+        destroyed: false,
+    };
+}

package/lib/session/session-state.d.ts

@@ -0,0 +1,65 @@
+import type { ContinuitySnapshot, Interaction, PendingIntent, Checkpoint, ViewDefinition, DataSnapshot, DetachedValuePolicy, ProposedValue, ActionRegistration, ActionHandler } from '@continuum/contract';
+import type { ReconciliationIssue, ReconciliationOptions, ReconciliationResolution, StateDiff } from '@continuum/runtime';
+/**
+ * Internal mutable session backing state.
+ *
+ * This shape is not exported from the package barrel and is intended for
+ * internal orchestration modules only.
+ */
+export interface SessionState {
+    sessionId: string;
+    clock: () => number;
+    maxEventLogSize: number;
+    maxPendingIntents: number;
+    maxCheckpoints: number;
+    reconciliationOptions?: Omit<ReconciliationOptions, 'clock'>;
+    validateOnUpdate: boolean;
+    detachedValuePolicy?: DetachedValuePolicy;
+    currentView: ViewDefinition | null;
+    currentData: DataSnapshot | null;
+    priorView: ViewDefinition | null;
+    issues: ReconciliationIssue[];
+    diffs: StateDiff[];
+    resolutions: ReconciliationResolution[];
+    eventLog: Interaction[];
+    pendingIntents: PendingIntent[];
+    checkpoints: Checkpoint[];
+    snapshotListeners: Set<(snapshot: ContinuitySnapshot) => void>;
+    issueListeners: Set<(issues: ReconciliationIssue[]) => void>;
+    pendingProposals: Record<string, ProposedValue>;
+    actionRegistry: Map<string, {
+        registration: ActionRegistration;
+        handler: ActionHandler;
+    }>;
+    destroyed: boolean;
+}
+/**
+ * Creates default empty internal session state.
+ *
+ * @param sessionId Generated session id.
+ * @param clock Clock source used for ids/timestamps.
+ * @returns Initialized internal state object.
+ */
+export declare function createEmptySessionState(sessionId: string, clock: () => number): SessionState;
+/**
+ * Resets active timeline data while preserving configuration and listeners.
+ *
+ * @param internal Mutable internal session state.
+ */
+export declare function resetSessionState(internal: SessionState): void;
+/**
+ * Replaces runtime portions of internal state from another state object.
+ *
+ * @param internal Destination state object.
+ * @param next Source state values to apply.
+ */
+export declare function replaceInternalState(internal: SessionState, next: SessionState): void;
+/**
+ * Generates a unique id using prefix, timestamp, and random UUID bytes.
+ *
+ * @param prefix Id namespace prefix.
+ * @param clock Clock source used for timestamp component.
+ * @returns Stable unique id string.
+ */
+export declare function generateId(prefix: string, clock: () => number): string;
+//# sourceMappingURL=session-state.d.ts.map

package/lib/session/session-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-state.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/session-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,UAAU,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,aAAa,EACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,SAAS,EACV,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;IAC7D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,WAAW,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,YAAY,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,iBAAiB,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAAC,CAAC;IAC/D,cAAc,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,IAAI,CAAC,CAAC;IAC7D,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAChD,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,kBAAkB,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IAC1F,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,MAAM,GAAG,YAAY,CAwB5F;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAW9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,YAAY,GACjB,IAAI,CAYN;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,MAAM,GAAG,MAAM,CAGtE"}

package/lib/session/session-state.js

@@ -0,0 +1,79 @@
+/**
+ * Creates default empty internal session state.
+ *
+ * @param sessionId Generated session id.
+ * @param clock Clock source used for ids/timestamps.
+ * @returns Initialized internal state object.
+ */
+export function createEmptySessionState(sessionId, clock) {
+    return {
+        sessionId,
+        clock,
+        maxEventLogSize: 1000,
+        maxPendingIntents: 500,
+        maxCheckpoints: 50,
+        reconciliationOptions: undefined,
+        validateOnUpdate: false,
+        currentView: null,
+        currentData: null,
+        priorView: null,
+        issues: [],
+        diffs: [],
+        resolutions: [],
+        eventLog: [],
+        pendingIntents: [],
+        checkpoints: [],
+        snapshotListeners: new Set(),
+        issueListeners: new Set(),
+        pendingProposals: {},
+        actionRegistry: new Map(),
+        destroyed: false,
+    };
+}
+/**
+ * Resets active timeline data while preserving configuration and listeners.
+ *
+ * @param internal Mutable internal session state.
+ */
+export function resetSessionState(internal) {
+    internal.currentView = null;
+    internal.currentData = null;
+    internal.priorView = null;
+    internal.issues = [];
+    internal.diffs = [];
+    internal.resolutions = [];
+    internal.eventLog = [];
+    internal.pendingIntents = [];
+    internal.checkpoints = [];
+    internal.pendingProposals = {};
+}
+/**
+ * Replaces runtime portions of internal state from another state object.
+ *
+ * @param internal Destination state object.
+ * @param next Source state values to apply.
+ */
+export function replaceInternalState(internal, next) {
+    internal.currentView = next.currentView;
+    internal.currentData = next.currentData;
+    internal.priorView = next.priorView;
+    internal.issues = next.issues;
+    internal.diffs = next.diffs;
+    internal.resolutions = next.resolutions;
+    internal.eventLog = next.eventLog;
+    internal.pendingIntents = next.pendingIntents;
+    internal.checkpoints = next.checkpoints;
+    internal.validateOnUpdate = next.validateOnUpdate;
+    internal.reconciliationOptions = next.reconciliationOptions;
+}
+/**
+ * Generates a unique id using prefix, timestamp, and random UUID bytes.
+ *
+ * @param prefix Id namespace prefix.
+ * @param clock Clock source used for timestamp component.
+ * @returns Stable unique id string.
+ */
+export function generateId(prefix, clock) {
+    const randomPart = globalThis.crypto.randomUUID().replace(/-/g, '');
+    return `${prefix}_${clock()}_${randomPart}`;
+}