@continuum-dev/session 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CooperContinuum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,306 @@
+# ♾️ @continuum-dev/session
+
+**The Stateful Ledger for Generative UI.** Give your AI agents memory, conflict resolution, and time-travel capabilities.
+
+[![npm version](https://badge.fury.io/js/@continuum-dev%2Fsession.svg)](https://badge.fury.io/js/@continuum-dev%2Fsession)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## The Problem: The User and the AI are Fighting
+
+Building a multi-turn Generative UI introduces a massive state management problem: **concurrency and conflict**.
+
+- **Data Clobbering:** The user is typing in a text field, but the AI suddenly pushes an updated view and tries to overwrite their in-progress input.
+- **Hallucinations:** The AI generates a broken layout or removes critical UI. You need deterministic undo.
+- **Persistence:** A user closes the tab and returns later. You need exact rehydration of generated view, user state, and timeline.
+
+Standard state managers are optimized for deterministic single-author UIs. They struggle when the UI schema itself mutates over time.
+
+## The Solution
+
+**Continuum Session** is a stateful lifecycle manager built on top of `@continuum-dev/runtime`. It converts a stream of AI view mutations and user interactions into a structured, event-sourced session ledger.
+
+It tracks event history, manages checkpoints, protects dirty user input with proposals, and serializes the entire session into a portable blob for resumable experiences.
+
+```bash
+npm install @continuum-dev/session
+```
+
+## Core Capabilities
+
+- ⏱️ **Time-Travel (Undo/Rewind):** Auto-checkpoints on `pushView()`, plus manual checkpoints and rewind support.
+- 🛡️ **Conflict Resolution (Proposals):** Dirty values are protected from AI overwrites by staging proposed values.
+- 💾 **Portable Persistence:** `serialize()` and `deserialize()` capture and restore full session state.
+- ⚡ **Action Registry:** Register and dispatch typed action handlers by intent id.
+- 📖 **Event-Sourced Timeline:** Interactions, intents, checkpoint boundaries, and reconciliation diagnostics are preserved.
+
+---
+
+## Quick Start
+
+```typescript
+import { createSession } from '@continuum-dev/session';
+
+const session = createSession();
+
+session.pushView({
+  viewId: 'agent-form',
+  version: '1.0',
+  nodes: [{ id: 'field_1', key: 'username', type: 'field' }]
+});
+
+session.updateState('field_1', { value: 'Alice' });
+
+const snapshot = session.getSnapshot();
+console.log(snapshot?.data.values['field_1'].value); // 'Alice'
+```
+
+---
+
+## Public API Reference
+
+The package exports:
+
+- `./lib/session.js`
+- `./lib/types.js`
+
+### 1) Initialization and Lifecycle
+
+#### `createSession(options?)`
+
+Creates a fresh session ledger.
+
+```typescript
+function createSession(options?: SessionOptions): Session;
+```
+
+#### `deserialize(data, options?)`
+
+Restores a previously serialized session blob.
+
+```typescript
+function deserialize(data: unknown, options?: SessionOptions): Session;
+```
+
+#### `hydrateOrCreate(options?)`
+
+Creates from persisted storage when available, otherwise creates a new session.
+
+```typescript
+function hydrateOrCreate(options?: SessionOptions): Session;
+```
+
+Persistence note:
+
+- When `options.persistence` is provided, snapshot writes are debounced by 200ms.
+- `SessionPersistenceOptions.maxBytes` enforces a payload size cap before writes.
+- `SessionPersistenceOptions.onError` receives `size_limit` and `storage_error` events.
+- Browser `storage` events are consumed for cross-tab session synchronization.
+
+#### `sessionFactory`
+
+DI-friendly factory object for session creation and deserialization.
+
+```typescript
+const sessionFactory: SessionFactory = { createSession, deserialize };
+```
+
+#### Subscriptions
+
+Listen to state and issue updates.
+
+```typescript
+const stopSnapshot = session.onSnapshot((snapshot) => {
+  // update UI
+});
+
+const stopIssues = session.onIssues((issues) => {
+  // handle warnings/errors
+});
+```
+
+### 2) View and State Updates
+
+#### `session.pushView(view)`
+
+Pushes a new AI-generated view, runs reconciliation, updates detached values, marks stale pending intents on version change, and creates an auto-checkpoint.
+
+```typescript
+session.pushView({ viewId: 'form', version: '2.0', nodes: [] });
+```
+
+#### `session.updateState(nodeId, payload)`
+
+Records a data update interaction for a node.
+
+```typescript
+session.updateState('email', { value: 'test@example.com', isDirty: true });
+```
+
+#### `session.recordIntent(interaction)`
+
+Records a raw interaction event.
+
+```typescript
+session.recordIntent({
+  nodeId: 'email',
+  type: 'data-update',
+  payload: { value: 'test@example.com' }
+});
+```
+
+#### Viewport APIs
+
+```typescript
+session.updateViewportState('table_1', { scrollY: 320, isFocused: true });
+const viewport = session.getViewportState('table_1');
+```
+
+### 3) Anti-Clobbering with Proposals
+
+When a node has dirty user state and AI proposes a new value, Continuum stages the proposal instead of overwriting immediately.
+
+#### `session.proposeValue(nodeId, value, source?)`
+
+```typescript
+session.proposeValue('email', { value: 'ai_guess@example.com' }, 'ai-agent');
+```
+
+#### `session.getPendingProposals()`
+
+```typescript
+const proposals = session.getPendingProposals();
+```
+
+#### `session.acceptProposal(nodeId)` / `session.rejectProposal(nodeId)`
+
+```typescript
+session.acceptProposal('email');
+session.rejectProposal('email');
+```
+
+### 4) Time Travel with Checkpoints
+
+#### `session.checkpoint()`
+
+Manually captures a checkpoint snapshot.
+
+```typescript
+const cp = session.checkpoint();
+```
+
+#### `session.rewind(checkpointId)`
+
+Rewinds to a checkpoint id and truncates checkpoint history after that point.
+
+```typescript
+session.rewind(cp.checkpointId);
+```
+
+#### `session.restoreFromCheckpoint(checkpoint)`
+
+Restores to a checkpoint object without truncating the checkpoint stack.
+
+```typescript
+session.restoreFromCheckpoint(cp);
+```
+
+#### `session.getCheckpoints()`
+
+```typescript
+const checkpoints = session.getCheckpoints();
+```
+
+### 5) Intents and Event Sourcing
+
+#### `session.submitIntent(intent)`
+
+Queue a pending user intent for AI/backend processing.
+
+```typescript
+session.submitIntent({
+  nodeId: 'submit_btn',
+  intentName: 'execute_search',
+  payload: { term: 'Continuum' }
+});
+```
+
+#### `session.getPendingIntents()`, `session.validateIntent(intentId)`, `session.cancelIntent(intentId)`
+
+```typescript
+const intents = session.getPendingIntents();
+session.validateIntent(intents[0].intentId);
+session.cancelIntent(intents[0].intentId);
+```
+
+#### `session.getEventLog()`
+
+```typescript
+const log = session.getEventLog();
+```
+
+### 6) Actions Registry
+
+Register local handlers for semantic intent ids and dispatch them with current session snapshot data.
+
+```typescript
+session.registerAction('fetch_data', { label: 'Fetch Data' }, async ({ snapshot, nodeId }) => {
+  void snapshot;
+  void nodeId;
+});
+
+await session.dispatchAction('fetch_data', 'btn_1');
+```
+
+Also available:
+
+- `session.unregisterAction(intentId)`
+- `session.getRegisteredActions()`
+
+### 7) Teardown, Persistence, and Maintenance
+
+```typescript
+const blob = session.serialize();
+const detached = session.getDetachedValues();
+session.purgeDetachedValues();
+
+session.reset();
+const final = session.destroy();
+```
+
+Persistence behavior:
+
+- `serialize()` returns a JSON-safe payload with `formatVersion: 1`.
+- Automatic persistence writes are debounced (200ms) to reduce storage churn.
+- If `maxBytes` is exceeded, the write is skipped and `onError` is invoked.
+- Remote storage updates can rehydrate in-memory state for cross-tab continuity.
+
+`destroy()` returns:
+
+```typescript
+{ issues: ReconciliationIssue[] }
+```
+
+### 8) Core Types
+
+Primary exported types from `src/lib/types.ts`:
+
+- `Session`
+- `SessionOptions`
+- `SessionFactory`
+- `SessionPersistenceOptions`
+- `SessionPersistenceStorage`
+
+---
+
+## Architecture Context
+
+`@continuum-dev/session` handles stateful timeline management and lifecycle orchestration. It delegates structural data reconciliation to `@continuum-dev/runtime` whenever a new view is pushed.
+
+Framework bindings can wrap this package for UI-first usage:
+
+- `@continuum-dev/react`
+- `@continuum-dev/angular`
+
+## License
+
+MIT © CooperContinuum

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from './lib/session.js';
+export * from './lib/types.js';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../packages/session/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}

package/index.js

@@ -0,0 +1,2 @@
+export * from './lib/session.js';
+export * from './lib/types.js';

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

@@ -0,0 +1,7 @@
+import type { PendingAction } from '@continuum/contract';
+import type { SessionState } from './session-state.js';
+export declare function submitAction(internal: SessionState, partial: Omit<PendingAction, 'id' | 'createdAt' | 'status' | 'schemaVersion'>): void;
+export declare function validateAction(internal: SessionState, actionId: string): boolean;
+export declare function cancelAction(internal: SessionState, actionId: string): boolean;
+export declare function markAllPendingActionsAsStale(internal: SessionState): void;
+//# sourceMappingURL=action-manager.d.ts.map

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

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

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

@@ -0,0 +1,39 @@
+import type { Checkpoint } from '@continuum/contract';
+import type { SessionState } from './session-state.js';
+/**
+ * Deep clones checkpoint payloads to prevent accidental shared mutations.
+ *
+ * @param value Snapshot value to clone.
+ * @returns Structured cloned value.
+ */
+export declare function cloneCheckpointSnapshot<T>(value: T): T;
+/**
+ * Creates an automatic checkpoint from current snapshot state.
+ *
+ * Auto checkpoints are pruned first when exceeding `maxCheckpoints`.
+ *
+ * @param internal Mutable internal session state.
+ */
+export declare function autoCheckpoint(internal: SessionState): void;
+/**
+ * Creates a manual checkpoint and appends it to the checkpoint stack.
+ *
+ * @param internal Mutable internal session state.
+ * @returns The created checkpoint.
+ */
+export declare function createManualCheckpoint(internal: SessionState): Checkpoint;
+/**
+ * Restores state from a checkpoint without truncating checkpoint history.
+ *
+ * @param internal Mutable internal session state.
+ * @param cp Checkpoint to restore from.
+ */
+export declare function restoreFromCheckpoint(internal: SessionState, cp: Checkpoint): void;
+/**
+ * Rewinds state to a checkpoint id and truncates checkpoints after it.
+ *
+ * @param internal Mutable internal session state.
+ * @param checkpointId Target checkpoint id.
+ */
+export declare function rewind(internal: SessionState, checkpointId: string): void;
+//# sourceMappingURL=checkpoint-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-manager.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/checkpoint-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOvD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAqB3D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,YAAY,GAAG,UAAU,CAezE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,UAAU,GAAG,IAAI,CAalF;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAkBzE"}

package/lib/session/checkpoint-manager.js

@@ -0,0 +1,106 @@
+import { generateId } from './session-state.js';
+import { buildSnapshotFromCurrentState, notifySnapshotAndIssueListeners, } from './listeners.js';
+/**
+ * Deep clones checkpoint payloads to prevent accidental shared mutations.
+ *
+ * @param value Snapshot value to clone.
+ * @returns Structured cloned value.
+ */
+export function cloneCheckpointSnapshot(value) {
+    return structuredClone(value);
+}
+/**
+ * Creates an automatic checkpoint from current snapshot state.
+ *
+ * Auto checkpoints are pruned first when exceeding `maxCheckpoints`.
+ *
+ * @param internal Mutable internal session state.
+ */
+export function autoCheckpoint(internal) {
+    const snapshot = buildSnapshotFromCurrentState(internal);
+    if (!snapshot)
+        return;
+    const id = generateId('cp', internal.clock);
+    internal.checkpoints.push({
+        checkpointId: id,
+        sessionId: internal.sessionId,
+        snapshot: cloneCheckpointSnapshot(snapshot),
+        eventIndex: internal.eventLog.length,
+        timestamp: internal.clock(),
+        trigger: 'auto',
+    });
+    if (internal.checkpoints.length > internal.maxCheckpoints) {
+        const overflow = internal.checkpoints.length - internal.maxCheckpoints;
+        for (let index = 0; index < overflow; index += 1) {
+            const removableIndex = internal.checkpoints.findIndex((checkpoint) => checkpoint.trigger === 'auto');
+            if (removableIndex === -1)
+                break;
+            internal.checkpoints.splice(removableIndex, 1);
+        }
+    }
+}
+/**
+ * Creates a manual checkpoint and appends it to the checkpoint stack.
+ *
+ * @param internal Mutable internal session state.
+ * @returns The created checkpoint.
+ */
+export function createManualCheckpoint(internal) {
+    const snapshot = buildSnapshotFromCurrentState(internal);
+    if (!snapshot) {
+        throw new Error('Cannot create checkpoint before pushing a view');
+    }
+    const checkpoint = {
+        checkpointId: generateId('cp', internal.clock),
+        sessionId: internal.sessionId,
+        snapshot: cloneCheckpointSnapshot(snapshot),
+        eventIndex: internal.eventLog.length,
+        timestamp: internal.clock(),
+        trigger: 'manual',
+    };
+    internal.checkpoints.push(checkpoint);
+    return checkpoint;
+}
+/**
+ * Restores state from a checkpoint without truncating checkpoint history.
+ *
+ * @param internal Mutable internal session state.
+ * @param cp Checkpoint to restore from.
+ */
+export function restoreFromCheckpoint(internal, cp) {
+    if (internal.destroyed)
+        return;
+    internal.currentView = cloneCheckpointSnapshot(cp.snapshot.view);
+    internal.currentData = cloneCheckpointSnapshot(cp.snapshot.data);
+    internal.priorView = null;
+    internal.eventLog = internal.eventLog.slice(0, cp.eventIndex);
+    internal.issues = [];
+    internal.diffs = [];
+    internal.resolutions = [];
+    internal.pendingIntents = [];
+    notifySnapshotAndIssueListeners(internal);
+}
+/**
+ * Rewinds state to a checkpoint id and truncates checkpoints after it.
+ *
+ * @param internal Mutable internal session state.
+ * @param checkpointId Target checkpoint id.
+ */
+export function rewind(internal, checkpointId) {
+    if (internal.destroyed)
+        return;
+    const idx = internal.checkpoints.findIndex((cp) => cp.checkpointId === checkpointId);
+    if (idx === -1)
+        throw new Error(`Checkpoint ${checkpointId} not found`);
+    const cp = internal.checkpoints[idx];
+    internal.checkpoints = internal.checkpoints.slice(0, idx + 1);
+    internal.currentView = cloneCheckpointSnapshot(cp.snapshot.view);
+    internal.currentData = cloneCheckpointSnapshot(cp.snapshot.data);
+    internal.priorView = null;
+    internal.eventLog = internal.eventLog.slice(0, cp.eventIndex);
+    internal.issues = [];
+    internal.diffs = [];
+    internal.resolutions = [];
+    internal.pendingIntents = [];
+    notifySnapshotAndIssueListeners(internal);
+}

package/lib/session/destroyer.d.ts

@@ -0,0 +1,12 @@
+import type { ReconciliationIssue } from '@continuum/runtime';
+import type { SessionState } from './session-state.js';
+/**
+ * Destroys a session and clears all mutable state containers.
+ *
+ * @param internal Mutable internal session state.
+ * @returns Final snapshot of issues captured before teardown.
+ */
+export declare function teardownSessionAndClearState(internal: SessionState): {
+    issues: ReconciliationIssue[];
+};
+//# sourceMappingURL=destroyer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"destroyer.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/destroyer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,YAAY,GAAG;IAAE,MAAM,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAetG"}

package/lib/session/destroyer.js

@@ -0,0 +1,22 @@
+/**
+ * Destroys a session and clears all mutable state containers.
+ *
+ * @param internal Mutable internal session state.
+ * @returns Final snapshot of issues captured before teardown.
+ */
+export function teardownSessionAndClearState(internal) {
+    internal.destroyed = true;
+    internal.currentView = null;
+    internal.currentData = null;
+    internal.priorView = null;
+    internal.eventLog = [];
+    internal.pendingIntents = [];
+    internal.checkpoints = [];
+    const result = { issues: [...internal.issues] };
+    internal.issues = [];
+    internal.diffs = [];
+    internal.resolutions = [];
+    internal.snapshotListeners.clear();
+    internal.issueListeners.clear();
+    return result;
+}

package/lib/session/event-log.d.ts

@@ -0,0 +1,13 @@
+import type { Interaction } from '@continuum/contract';
+import type { SessionState } from './session-state.js';
+/**
+ * Records an interaction event and applies its payload to current data state.
+ *
+ * The function updates event log, value lineage, optional validation issues,
+ * and latest auto-checkpoint snapshot.
+ *
+ * @param internal Mutable internal session state.
+ * @param partial Interaction payload without generated metadata.
+ */
+export declare function recordIntent(internal: SessionState, partial: Omit<Interaction, 'interactionId' | 'timestamp' | 'sessionId' | 'viewVersion'>): void;
+//# sourceMappingURL=event-log.d.ts.map

package/lib/session/event-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/event-log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,WAAW,EAA2B,MAAM,qBAAqB,CAAC;AAE1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAsDvD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,eAAe,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC,GACtF,IAAI,CAiFN"}

package/lib/session/event-log.js

@@ -0,0 +1,126 @@
+import { getChildNodes, ISSUE_CODES, ISSUE_SEVERITY, isInteractionType } from '@continuum/contract';
+import { generateId } from './session-state.js';
+import { buildSnapshotFromCurrentState, notifySnapshotAndIssueListeners } from './listeners.js';
+import { cloneCheckpointSnapshot } from './checkpoint-manager.js';
+import { validateNodeValue } from '@continuum/runtime';
+function collectNodesByCanonicalId(nodes) {
+    const byId = new Map();
+    const walk = (items, parentPath) => {
+        for (const node of items) {
+            const nodeId = parentPath.length > 0 ? `${parentPath}/${node.id}` : node.id;
+            byId.set(nodeId, node);
+            const children = getChildNodes(node);
+            if (children.length > 0) {
+                walk(children, nodeId);
+            }
+        }
+    };
+    walk(nodes, '');
+    return byId;
+}
+function resolveNodeLookupEntry(nodes, requestedId) {
+    const canonicalMap = collectNodesByCanonicalId(nodes);
+    const direct = canonicalMap.get(requestedId);
+    if (direct) {
+        return { canonicalId: requestedId, node: direct };
+    }
+    const matches = [];
+    const walk = (items, parentPath) => {
+        for (const node of items) {
+            const canonicalId = parentPath.length > 0 ? `${parentPath}/${node.id}` : node.id;
+            if (node.id === requestedId) {
+                matches.push({ canonicalId, node });
+            }
+            const children = getChildNodes(node);
+            if (children.length > 0) {
+                walk(children, canonicalId);
+            }
+        }
+    };
+    walk(nodes, '');
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    return null;
+}
+/**
+ * Records an interaction event and applies its payload to current data state.
+ *
+ * The function updates event log, value lineage, optional validation issues,
+ * and latest auto-checkpoint snapshot.
+ *
+ * @param internal Mutable internal session state.
+ * @param partial Interaction payload without generated metadata.
+ */
+export function recordIntent(internal, partial) {
+    if (internal.destroyed || !internal.currentData || !internal.currentView)
+        return;
+    if (!isInteractionType(partial.type)) {
+        throw new Error(`Invalid interaction type: ${String(partial.type)}`);
+    }
+    const now = internal.clock();
+    const id = generateId('int', internal.clock);
+    const interaction = {
+        interactionId: id,
+        sessionId: internal.sessionId,
+        viewVersion: internal.currentView.version,
+        timestamp: now,
+        nodeId: partial.nodeId,
+        type: partial.type,
+        payload: partial.payload,
+    };
+    internal.eventLog.push(interaction);
+    if (internal.eventLog.length > internal.maxEventLogSize) {
+        internal.eventLog.splice(0, internal.eventLog.length - internal.maxEventLogSize);
+    }
+    const resolvedEntry = resolveNodeLookupEntry(internal.currentView.nodes, partial.nodeId);
+    if (!resolvedEntry) {
+        internal.issues = [
+            ...internal.issues,
+            {
+                severity: ISSUE_SEVERITY.WARNING,
+                nodeId: partial.nodeId,
+                message: `Node ${partial.nodeId} not found in current view`,
+                code: ISSUE_CODES.UNKNOWN_NODE,
+            },
+        ];
+        notifySnapshotAndIssueListeners(internal);
+        return;
+    }
+    const { canonicalId, node } = resolvedEntry;
+    internal.currentData = {
+        ...internal.currentData,
+        values: {
+            ...internal.currentData.values,
+            [canonicalId]: partial.payload,
+        },
+        lineage: {
+            ...internal.currentData.lineage,
+            timestamp: now,
+            lastInteractionId: id,
+        },
+        valueLineage: {
+            ...internal.currentData.valueLineage,
+            [canonicalId]: {
+                lastUpdated: now,
+                lastInteractionId: id,
+            },
+        },
+    };
+    if (internal.validateOnUpdate) {
+        const validationIssues = validateNodeValue(node, partial.payload);
+        if (validationIssues.length > 0) {
+            internal.issues = [...internal.issues, ...validationIssues];
+        }
+    }
+    const lastAutoCheckpoint = [...internal.checkpoints]
+        .reverse()
+        .find((checkpoint) => checkpoint.trigger === 'auto');
+    if (lastAutoCheckpoint) {
+        const snapshot = buildSnapshotFromCurrentState(internal);
+        if (snapshot) {
+            lastAutoCheckpoint.snapshot = cloneCheckpointSnapshot(snapshot);
+        }
+    }
+    notifySnapshotAndIssueListeners(internal);
+}