@continuum-dev/runtime 0.1.0

package/lib/context.js

@@ -0,0 +1,305 @@
+import { ISSUE_SEVERITY, ISSUE_CODES } from '@continuum/contract';
+import { traverseViewNodes } from './reconciliation/view-traversal.js';
+/**
+ * Scans a view tree for duplicate ids/keys and traversal-level issues.
+ *
+ * Useful for preflight checks when validating generated views before running
+ * full reconciliation.
+ *
+ * @param nodes Root nodes from a view definition.
+ * @returns Aggregated issues for duplicates and traversal anomalies.
+ */
+export function collectDuplicateIssues(nodes) {
+    const issues = [];
+    const byId = new Map();
+    const byKey = new Map();
+    const traversal = traverseViewNodes(nodes);
+    for (const entry of traversal.visited) {
+        const indexedId = entry.nodeId;
+        if (byId.has(indexedId)) {
+            issues.push({
+                severity: ISSUE_SEVERITY.ERROR,
+                nodeId: entry.node.id,
+                message: `Duplicate node id: ${entry.node.id}`,
+                code: ISSUE_CODES.DUPLICATE_NODE_ID,
+            });
+        }
+        byId.set(indexedId, entry.node);
+        if (entry.node.key) {
+            const indexedKey = toIndexedKey(entry.node.key, entry.parentPath);
+            if (byKey.has(indexedKey)) {
+                issues.push({
+                    severity: ISSUE_SEVERITY.WARNING,
+                    nodeId: entry.node.id,
+                    message: `Duplicate node key: ${entry.node.key}`,
+                    code: ISSUE_CODES.DUPLICATE_NODE_KEY,
+                });
+            }
+            byKey.set(indexedKey, entry.node);
+        }
+    }
+    issues.push(...traversal.issues);
+    return issues;
+}
+/**
+ * Builds lookup maps used by the reconciliation matching pipeline.
+ *
+ * Context indexes scoped ids and semantic keys so downstream logic can resolve
+ * carry/migrate/restore decisions in O(1) lookups.
+ *
+ * @param newView Target view for this reconciliation cycle.
+ * @param priorView Previous view to compare against, if available.
+ * @returns Indexed reconciliation context consumed by resolver stages.
+ */
+export function buildReconciliationContext(newView, priorView) {
+    const newById = new Map();
+    const newByKey = new Map();
+    const priorById = new Map();
+    const priorByKey = new Map();
+    const newIdsByRawId = new Map();
+    const priorIdsByRawId = new Map();
+    const newNodeIds = new WeakMap();
+    const priorNodeIds = new WeakMap();
+    const issues = [];
+    const newTraversal = traverseViewNodes(newView.nodes);
+    const priorTraversal = priorView ? traverseViewNodes(priorView.nodes) : null;
+    const newKeyCounts = collectKeyCounts(newTraversal.visited);
+    const priorKeyCounts = priorTraversal ? collectKeyCounts(priorTraversal.visited) : new Map();
+    issues.push(...newTraversal.issues);
+    if (priorTraversal) {
+        issues.push(...priorTraversal.issues);
+    }
+    indexNodesByIdAndKey(newTraversal.visited, newById, newByKey, newIdsByRawId, newNodeIds, newKeyCounts, issues);
+    if (priorView) {
+        indexNodesByIdAndKey(priorTraversal?.visited ?? [], priorById, priorByKey, priorIdsByRawId, priorNodeIds, priorKeyCounts, issues);
+    }
+    return {
+        newView,
+        priorView,
+        newById,
+        newByKey,
+        priorById,
+        priorByKey,
+        newIdsByRawId,
+        priorIdsByRawId,
+        newNodeIds,
+        priorNodeIds,
+        newKeyCounts,
+        priorKeyCounts,
+        issues,
+    };
+}
+/**
+ * Resolves the best prior-view match for a node in the new view.
+ *
+ * Matching is attempted in deterministic order: scoped id, semantic key,
+ * dot-suffix key fallback, and unique raw-id fallback.
+ *
+ * @param ctx Reconciliation context with prior/new indexes.
+ * @param newNode Node from the new view to resolve against prior view.
+ * @returns Matched prior node, or null when no candidate can be resolved.
+ */
+export function findPriorNode(ctx, newNode) {
+    // 1. Exact Full Path ID
+    const newNodeId = ctx.newNodeIds.get(newNode) ?? newNode.id;
+    const byId = ctx.priorById.get(newNodeId) ?? ctx.priorById.get(newNode.id);
+    if (byId)
+        return byId;
+    // 2. Exact Key
+    if (newNode.key) {
+        const byKey = findByKey(ctx.priorByKey, newNode.key, newNodeId);
+        if (byKey)
+            return byKey;
+        // 3. Dot-Notation Suffix Key
+        if (newNode.key.includes('.')) {
+            const parts = newNode.key.split('.');
+            const suffix = parts[parts.length - 1];
+            if (suffix) {
+                const bySuffixKey = findByKey(ctx.priorByKey, suffix, newNodeId);
+                if (bySuffixKey)
+                    return bySuffixKey;
+            }
+        }
+    }
+    // 4. Unique Raw ID Mapping
+    const candidates = ctx.priorIdsByRawId.get(newNode.id);
+    if (candidates && candidates.length === 1) {
+        const uniquePriorId = candidates[0];
+        const uniqueNode = ctx.priorById.get(uniquePriorId);
+        if (uniqueNode)
+            return uniqueNode;
+    }
+    // 5. Dot-Notation Suffix ID Match (Match newly dot-notated key to old unique raw ID)
+    if (newNode.key && newNode.key.includes('.')) {
+        const parts = newNode.key.split('.');
+        const suffix = parts[parts.length - 1];
+        if (suffix) {
+            const keyCandidates = ctx.priorIdsByRawId.get(suffix);
+            if (keyCandidates && keyCandidates.length === 1) {
+                const uniqueNode = ctx.priorById.get(keyCandidates[0]);
+                if (uniqueNode)
+                    return uniqueNode;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Builds a value lookup that supports id-based and key-based carry.
+ *
+ * The returned map contains direct prior ids plus remapped ids when semantic
+ * key matches indicate the value should move to a different node id.
+ *
+ * @param priorData Previous data snapshot.
+ * @param ctx Reconciliation context built from prior/new views.
+ * @returns Value lookup used by node resolution.
+ */
+export function buildPriorValueLookupByIdAndKey(priorData, ctx) {
+    const map = new Map();
+    for (const [priorId, priorValue] of Object.entries(priorData.values)) {
+        map.set(priorId, priorValue);
+        const resolvedPriorId = resolveIdFromSnapshot(ctx.priorById, ctx.priorIdsByRawId, priorId);
+        if (resolvedPriorId && resolvedPriorId !== priorId) {
+            map.set(resolvedPriorId, priorValue);
+        }
+        const priorNode = resolvedPriorId ? ctx.priorById.get(resolvedPriorId) : undefined;
+        if (priorNode?.key) {
+            const newNode = findByKey(ctx.newByKey, priorNode.key, resolvedPriorId ?? priorNode.id);
+            if (newNode) {
+                const newNodeId = ctx.newNodeIds.get(newNode) ?? newNode.id;
+                map.set(newNodeId, priorValue);
+            }
+        }
+    }
+    return map;
+}
+/**
+ * Reports whether a match was resolved by id or by semantic key.
+ *
+ * This metadata is attached to reconciliation resolution records so consumers
+ * can explain why a value was carried/migrated/restored.
+ *
+ * @param ctx Reconciliation context with id/key indexes.
+ * @param newNode Node from the new view.
+ * @param priorNode Prior match candidate for the new node.
+ * @returns `id`, `key`, or null when no prior node exists.
+ */
+export function determineNodeMatchStrategy(ctx, newNode, priorNode) {
+    if (!priorNode)
+        return null;
+    const newNodeId = ctx.newNodeIds.get(newNode) ?? newNode.id;
+    if (ctx.priorById.has(newNodeId) || ctx.priorById.has(newNode.id))
+        return 'id';
+    if (newNode.key && (ctx.priorByKey.has(newNode.key) || findByKey(ctx.priorByKey, newNode.key, newNodeId) === priorNode))
+        return 'key';
+    if (newNode.key && newNode.key.includes('.')) {
+        const parts = newNode.key.split('.');
+        const suffix = parts[parts.length - 1];
+        if (suffix && findByKey(ctx.priorByKey, suffix, newNodeId) === priorNode)
+            return 'key';
+    }
+    if (priorNode.id === newNode.id)
+        return 'id';
+    if (newNode.key && newNode.key.includes('.')) {
+        const parts = newNode.key.split('.');
+        const suffix = parts[parts.length - 1];
+        if (suffix && priorNode.id === suffix)
+            return 'id';
+    }
+    return 'id'; // fallback to id for other fuzzy matches
+}
+/**
+ * Resolves a snapshot value key to a unique scoped prior node id.
+ *
+ * @param ctx Reconciliation context with prior-view indexes.
+ * @param priorId Snapshot key from `priorData.values`.
+ * @returns Scoped prior id when uniquely resolvable; otherwise null.
+ */
+export function resolvePriorSnapshotId(ctx, priorId) {
+    return resolveIdFromSnapshot(ctx.priorById, ctx.priorIdsByRawId, priorId);
+}
+/**
+ * Finds the best new-view node candidate for a given prior node by key.
+ *
+ * @param ctx Reconciliation context with new-view key indexes.
+ * @param priorNode Prior-view node to map forward.
+ * @returns Matching new-view node, or null when no key-compatible node exists.
+ */
+export function findNewNodeByPriorNode(ctx, priorNode) {
+    if (!priorNode.key)
+        return null;
+    const priorId = ctx.priorNodeIds.get(priorNode) ?? priorNode.id;
+    return (findByKey(ctx.newByKey, priorNode.key, priorId) ?? null);
+}
+function collectKeyCounts(traversed) {
+    const counts = new Map();
+    for (const entry of traversed) {
+        if (entry.node.key) {
+            counts.set(entry.node.key, (counts.get(entry.node.key) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+function indexNodesByIdAndKey(traversed, byId, byKey, idsByRawId, nodeIds, keyCounts, issues) {
+    for (const entry of traversed) {
+        const indexedId = entry.nodeId;
+        if (byId.has(indexedId)) {
+            issues.push({
+                severity: ISSUE_SEVERITY.ERROR,
+                nodeId: entry.node.id,
+                message: `Duplicate node id: ${entry.node.id}`,
+                code: ISSUE_CODES.DUPLICATE_NODE_ID,
+            });
+        }
+        byId.set(indexedId, entry.node);
+        nodeIds.set(entry.node, indexedId);
+        idsByRawId.set(entry.node.id, [...(idsByRawId.get(entry.node.id) ?? []), indexedId]);
+        if (entry.node.key) {
+            const indexedKey = toIndexedKey(entry.node.key, entry.parentPath);
+            if (byKey.has(indexedKey)) {
+                issues.push({
+                    severity: ISSUE_SEVERITY.WARNING,
+                    nodeId: entry.node.id,
+                    message: `Duplicate node key: ${entry.node.key}`,
+                    code: ISSUE_CODES.DUPLICATE_NODE_KEY,
+                });
+            }
+            byKey.set(indexedKey, entry.node);
+            if (!byKey.has(entry.node.key) && (keyCounts.get(entry.node.key) ?? 0) === 1) {
+                byKey.set(entry.node.key, entry.node);
+            }
+        }
+    }
+}
+function toIndexedKey(key, parentPath) {
+    if (parentPath.length > 0) {
+        return `${parentPath}/${key}`;
+    }
+    return key;
+}
+function resolveIdFromSnapshot(byId, idsByRawId, id) {
+    if (byId.has(id)) {
+        return id;
+    }
+    const candidates = idsByRawId.get(id) ?? [];
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    return null;
+}
+function findByKey(byKey, rawKey, scopedNodeId) {
+    const parentPath = parentOf(scopedNodeId);
+    if (parentPath) {
+        const scoped = byKey.get(`${parentPath}/${rawKey}`);
+        if (scoped)
+            return scoped;
+    }
+    return byKey.get(rawKey);
+}
+function parentOf(path) {
+    const idx = path.lastIndexOf('/');
+    if (idx === -1) {
+        return '';
+    }
+    return path.slice(0, idx);
+}

package/lib/reconcile.d.ts

@@ -0,0 +1,17 @@
+import type { DataSnapshot, ViewDefinition } from '@continuum/contract';
+import type { ReconciliationOptions, ReconciliationResult } from './types.js';
+/**
+ * Reconciles user state across view mutations produced by AI or server-side layout changes.
+ *
+ * This is the main runtime entrypoint. Provide the new view plus optional prior view/data,
+ * and the runtime returns a deterministic result with merged state, diffs, issue diagnostics,
+ * and per-node resolutions.
+ *
+ * @param newView Current view definition to reconcile into.
+ * @param priorView Previous view definition. Pass null for first render or unknown history.
+ * @param priorData Previous data snapshot. Pass null for fresh sessions.
+ * @param options Optional reconciliation behavior flags and migration extension hooks.
+ * @returns The reconciled state and reconciliation metadata for this transition.
+ */
+export declare function reconcile(newView: ViewDefinition, priorView: ViewDefinition | null, priorData: DataSnapshot | null, options?: ReconciliationOptions): ReconciliationResult;
+//# sourceMappingURL=reconcile.d.ts.map

package/lib/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../../packages/runtime/src/lib/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA4B,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAElG,OAAO,KAAK,EAA6B,qBAAqB,EAAE,oBAAoB,EAAa,MAAM,YAAY,CAAC;AAOpH;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,cAAc,GAAG,IAAI,EAChC,SAAS,EAAE,YAAY,GAAG,IAAI,EAC9B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAYtB"}

package/lib/reconcile.js

@@ -0,0 +1,76 @@
+import { DATA_RESOLUTIONS } from '@continuum/contract';
+import { buildReconciliationContext, buildPriorValueLookupByIdAndKey } from './context.js';
+import { buildFreshSessionResult, buildBlindCarryResult, assembleReconciliationResult } from './reconciliation/state-builder.js';
+import { resolveAllNodes, detectRemovedNodes } from './reconciliation/node-resolver.js';
+import { restoredDiff, restoredResolution } from './reconciliation/differ.js';
+/**
+ * Reconciles user state across view mutations produced by AI or server-side layout changes.
+ *
+ * This is the main runtime entrypoint. Provide the new view plus optional prior view/data,
+ * and the runtime returns a deterministic result with merged state, diffs, issue diagnostics,
+ * and per-node resolutions.
+ *
+ * @param newView Current view definition to reconcile into.
+ * @param priorView Previous view definition. Pass null for first render or unknown history.
+ * @param priorData Previous data snapshot. Pass null for fresh sessions.
+ * @param options Optional reconciliation behavior flags and migration extension hooks.
+ * @returns The reconciled state and reconciliation metadata for this transition.
+ */
+export function reconcile(newView, priorView, priorData, options = {}) {
+    const now = (options.clock ?? Date.now)();
+    if (!priorData) {
+        return buildFreshSessionResult(newView, now);
+    }
+    if (!priorView) {
+        return buildBlindCarryResult(newView, priorData, now, options);
+    }
+    return reconcileViewTransition(newView, priorView, priorData, now, options);
+}
+/**
+ * After resolving new nodes and detecting removals, check whether any nodes
+ * resolved as "added" (no prior match) can be restored from values that were
+ * just detached in the same push. This closes the gap where renaming both
+ * a node's ID and key in a single pushView would lose data until the next push.
+ */
+function restoreFromSamePushDetachments(resolved, removals, ctx) {
+    const justDetached = removals.detachedValues;
+    if (!justDetached || Object.keys(justDetached).length === 0) {
+        return;
+    }
+    for (let i = 0; i < resolved.resolutions.length; i++) {
+        const resolution = resolved.resolutions[i];
+        if (resolution.resolution !== DATA_RESOLUTIONS.ADDED) {
+            continue;
+        }
+        const nodeId = resolution.nodeId;
+        if (resolved.values[nodeId] !== undefined) {
+            continue;
+        }
+        const newNode = ctx.newById.get(nodeId);
+        if (!newNode) {
+            continue;
+        }
+        const detachedKey = newNode.key ?? nodeId;
+        const detachedEntry = justDetached[detachedKey];
+        if (!detachedEntry) {
+            continue;
+        }
+        if (detachedEntry.previousNodeType !== newNode.type) {
+            continue;
+        }
+        resolved.values[nodeId] = detachedEntry.value;
+        resolved.restoredDetachedKeys.add(detachedKey);
+        resolved.diffs.push(restoredDiff(nodeId, detachedEntry.value));
+        resolved.resolutions[i] = restoredResolution(nodeId, newNode.type, detachedEntry.value);
+    }
+}
+function reconcileViewTransition(newView, priorView, priorData, now, options) {
+    const ctx = buildReconciliationContext(newView, priorView);
+    const priorValues = buildPriorValueLookupByIdAndKey(priorData, ctx);
+    const resolved = resolveAllNodes(ctx, priorValues, priorData, now, options);
+    const removals = detectRemovedNodes(ctx, priorData, options, now);
+    restoreFromSamePushDetachments(resolved, removals, ctx);
+    const result = assembleReconciliationResult(resolved, removals, priorData, newView, now);
+    result.issues.unshift(...ctx.issues);
+    return result;
+}

package/lib/reconciliation/collection-resolver.d.ts

@@ -0,0 +1,13 @@
+import type { CollectionNode, CollectionNodeState, NodeValue } from '@continuum/contract';
+import type { ReconciliationIssue, ReconciliationOptions } from '../types.js';
+interface CollectionResolutionResult {
+    value: NodeValue<CollectionNodeState>;
+    issues: ReconciliationIssue[];
+    didMigrateItems: boolean;
+}
+export declare function resolveCollectionDefaultValues(node: CollectionNode): NodeValue<CollectionNodeState>;
+export declare function createInitialCollectionValue(node: CollectionNode): NodeValue<CollectionNodeState>;
+export declare function reconcileCollectionValue(priorNode: CollectionNode, newNode: CollectionNode, priorValue: unknown, options: ReconciliationOptions): CollectionResolutionResult;
+export declare function normalizeCollectionValue(node: CollectionNode, value: unknown): NodeValue<CollectionNodeState>;
+export {};
+//# sourceMappingURL=collection-resolver.d.ts.map

package/lib/reconciliation/collection-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-resolver.d.ts","sourceRoot":"","sources":["../../../../../packages/runtime/src/lib/reconciliation/collection-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,SAAS,EAAY,MAAM,qBAAqB,CAAC;AAGpG,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAS9E,UAAU,0BAA0B;IAClC,KAAK,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC;IACtC,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAAC,mBAAmB,CAAC,CA4BnG;AAED,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAAC,mBAAmB,CAAC,CAUjG;AAoFD,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,qBAAqB,GAC7B,0BAA0B,CA+H5B;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,OAAO,GACb,SAAS,CAAC,mBAAmB,CAAC,CAShC"}