@markless/runtime 0.3.1 → 0.3.2

package/dist/graph-C1ACA8O1.d.ts

@@ -0,0 +1,214 @@
+import { ProtocolStatePayload } from "@markless/serializer";
+
+//#region src/graph-reconcile.d.ts
+/**
+ * One array inside a derived value that reconciles by key instead of by
+ * element identity. `path` names the array (`[]` is the derived value itself)
+ * and `keyPath` is read on each element to get its identity.
+ */
+type RuntimeGraphReconcileKey = {
+  readonly path: ReadonlyArray<string>;
+  readonly keyPath: ReadonlyArray<string>;
+};
+/** Reconcile options carried by a computed or async computed graph node. */
+type RuntimeGraphReconcileOptions = {
+  readonly keyed?: ReadonlyArray<RuntimeGraphReconcileKey>;
+};
+/**
+ * Objects a state write touched during the current flush, mapped to the paths
+ * written beneath them. State writes mutate objects in place, so a derived
+ * value that still holds the same object reference is not unchanged when that
+ * object was written through. See `diffDerivedValue`.
+ */
+type WriteTouchedRecord = ReadonlyMap<object, ReadonlyArray<ReadonlyArray<string>>>;
+type DiffDerivedValueInput = {
+  readonly previous: unknown;
+  readonly next: unknown;
+  readonly keyed?: ReadonlyArray<RuntimeGraphReconcileKey>;
+  readonly touched?: WriteTouchedRecord;
+  readonly baselineStale?: boolean;
+  /**
+   * What an `Object.is`-identical plain object or array below the root means.
+   * `'unchanged'` (the default) trusts identity, which is sound for a caller
+   * that also supplies the write-touched record of the same flush.
+   * `'unknown'` is for a caller with no such record — the async commit — and
+   * reports every identical container at its own path instead.
+   */
+  readonly identicalContainers?: 'unchanged' | 'unknown';
+};
+/**
+ * Compares a derived value with the previous value of the same graph node and
+ * reports the graph paths that changed. It never mutates either value: the
+ * caller replaces the node's value pointer and invalidates the reported paths.
+ *
+ * Rules (specs/framework/03-state-graph.md "Derived reconciliation"):
+ * - identical references are unchanged, unless a write touched that object in
+ *   this flush, in which case the touched remainders are reported; the same
+ *   holds when only the previous value held the written object, because an
+ *   in-place write left that baseline already carrying the new field;
+ * - primitives, functions, `Map`, `Set`, `Date` and class instances are leaves;
+ * - plain objects reconcile field by field;
+ * - arrays reconcile by declared key, otherwise by element identity, and a
+ *   length or structural mismatch reports the array's own path;
+ * - a declared key that is missing or duplicated on either side falls back to
+ *   structural reconciliation for that array, which reports the array's own
+ *   path: keys are never matched partially and an index is never identity;
+ * - a missing baseline (first value, or a value whose write-touched record was
+ *   already cleared) reports the whole node.
+ *
+ * `identicalContainers: 'unknown'` is for a caller that has no write-touched
+ * record for the flush that produced the new value, so identity below the root
+ * proves nothing: every `Object.is`-identical plain object or array met below
+ * the root is reported at its own path and is not walked into. An identical
+ * root still reports nothing — nothing narrower is known about it, and the
+ * caller decides what a wholly identical value means — and identical
+ * primitives and other leaves stay unchanged. The default, `'unchanged'`,
+ * trusts identity as above.
+ */
+declare function diffDerivedValue(input: DiffDerivedValueInput): ReadonlyArray<ReadonlyArray<string>>;
+//#endregion
+//#region src/graph.d.ts
+type RuntimeGraphCell = {
+  readonly graphNodeId: string;
+  readonly value: unknown;
+  readonly readInitializer?: () => unknown;
+};
+type RuntimeGraphRead = (graphNodeId: string, path?: ReadonlyArray<string>) => unknown;
+type RuntimeGraphComputedDependency = {
+  readonly graphNodeId: string;
+  readonly path?: ReadonlyArray<string>;
+};
+type RuntimeGraphComputed = {
+  readonly graphNodeId: string;
+  readonly dependencies: ReadonlyArray<RuntimeGraphComputedDependency>;
+  readonly compute: (read: RuntimeGraphRead) => unknown; /** How re-derived values reconcile against the node's previous value. */
+  readonly reconcile?: RuntimeGraphReconcileOptions;
+};
+type RuntimeGraphComputedDependencyNode = Omit<RuntimeGraphComputed, 'compute'> & {
+  readonly compute?: never;
+};
+type RuntimeGraphAsyncSnapshot = {
+  readonly status: 'idle';
+  readonly version: 0;
+} | {
+  readonly status: 'pending';
+  readonly version: number;
+  readonly key: unknown;
+  readonly value?: unknown;
+} | {
+  readonly status: 'fulfilled';
+  readonly version: number;
+  readonly key: unknown;
+  readonly value: unknown;
+} | {
+  readonly status: 'rejected';
+  readonly version: number;
+  readonly key: unknown;
+  readonly error: unknown;
+};
+type RuntimeGraphAsyncComputed = {
+  readonly graphNodeId: string;
+  readonly dependencies: ReadonlyArray<RuntimeGraphComputedDependency>;
+  readonly initialSnapshot?: RuntimeGraphAsyncSnapshot;
+  readonly key: (read: RuntimeGraphRead) => unknown; /** How a fulfilled value reconciles against the previously published one. */
+  readonly reconcile?: RuntimeGraphReconcileOptions;
+  readonly run: (input: {
+    readonly key: unknown;
+    readonly signal: AbortSignal;
+    readonly read: RuntimeGraphRead;
+  }) => unknown | Promise<unknown>;
+};
+type DomJournalEntry = {
+  readonly type: 'setText';
+  readonly locator: string;
+  readonly value: unknown;
+} | {
+  readonly type: 'setAttr' | 'setProp';
+  readonly locator: string;
+  readonly name: string;
+  readonly value: unknown;
+} | {
+  readonly type: 'insertRange';
+  readonly locator: string;
+  readonly fragment: unknown;
+} | {
+  readonly type: 'removeRange';
+  readonly locator: string;
+} | {
+  readonly type: 'moveRange';
+  readonly locator: string;
+  readonly before: string;
+} | {
+  readonly type: 'runCleanup';
+  readonly locator: string;
+};
+type DomJournalResult = DomJournalEntry | ReadonlyArray<DomJournalEntry>;
+type DomJournalListener = (entries: ReadonlyArray<DomJournalEntry>) => void | Promise<void>;
+type RuntimeGraphInput = {
+  readonly cells: ReadonlyArray<RuntimeGraphCell>;
+  readonly computed?: ReadonlyArray<RuntimeGraphComputed | RuntimeGraphComputedDependencyNode>;
+  readonly asyncComputed?: ReadonlyArray<RuntimeGraphAsyncComputed>;
+  readonly sharedDefinitions?: ProtocolStatePayload['sharedDefinitions'];
+};
+type RuntimeGraphWrite = {
+  readonly graphNodeId: string;
+  readonly path?: ReadonlyArray<string>;
+  readonly value: unknown;
+};
+type RuntimeGraphSharedWrite = {
+  readonly definitionId: string;
+  readonly propertyName: string;
+  readonly path?: ReadonlyArray<string>;
+  readonly value: unknown;
+};
+type RuntimeGraphSharedPatchOperation = readonly [operation: 'set', path: ReadonlyArray<string>, value: unknown];
+type RuntimeGraphSharedPatch = {
+  readonly id: string;
+  readonly scope?: RuntimeSharedDefinition['scope'];
+  readonly version: number;
+  readonly patch: ReadonlyArray<RuntimeGraphSharedPatchOperation>;
+};
+type RuntimeGraphUpdate = {
+  readonly graphNodeId: string;
+  readonly path?: ReadonlyArray<string>;
+  readonly update: (value: unknown) => unknown;
+  readonly returnValue?: 'previous' | 'next';
+};
+type RuntimeGraphCall = {
+  readonly graphNodeId: string;
+  readonly path?: ReadonlyArray<string>;
+  readonly method: string;
+  readonly args?: ReadonlyArray<unknown>;
+};
+type RuntimeGraphDelete = {
+  readonly graphNodeId: string;
+  readonly path: ReadonlyArray<string>;
+};
+type RuntimeGraphSubscription = {
+  readonly id: string;
+  readonly graphNodeId: string;
+  readonly path?: ReadonlyArray<string>;
+  readonly run: (value: unknown) => DomJournalResult | void | Promise<DomJournalResult | void>;
+};
+type RuntimeGraph = {
+  readonly read: (graphNodeId: string, path?: ReadonlyArray<string>) => unknown; /** Available only in debug-enabled builds (`__MARKLESS_DEBUG_ENABLED__`). */
+  readonly peekAsyncSnapshot?: (graphNodeId: string) => RuntimeGraphAsyncSnapshot | undefined;
+  readonly readShared: (definitionId: string, propertyName: string, path?: ReadonlyArray<string>) => unknown;
+  readonly writeShared: (write: RuntimeGraphSharedWrite) => boolean;
+  readonly getSharedDefinition: (definitionId: string) => NonNullable<ProtocolStatePayload['sharedDefinitions']>[number] | undefined;
+  readonly listSharedDefinitions: () => NonNullable<ProtocolStatePayload['sharedDefinitions']>;
+  readonly takeSharedPatches: () => RuntimeGraphSharedPatch[];
+  readonly applySharedPatch: (patch: RuntimeGraphSharedPatch) => boolean;
+  readonly write: (write: RuntimeGraphWrite) => void;
+  readonly update: (update: RuntimeGraphUpdate) => unknown;
+  readonly call: (call: RuntimeGraphCall) => unknown;
+  readonly delete: (deletion: RuntimeGraphDelete) => boolean;
+  readonly subscribe: (subscription: RuntimeGraphSubscription) => () => void;
+  readonly subscribeJournal: (listener: DomJournalListener) => () => void;
+  readonly flush: () => Promise<void>;
+  readonly takeJournal: () => DomJournalEntry[];
+};
+type RuntimeSharedDefinition = NonNullable<ProtocolStatePayload['sharedDefinitions']>[number];
+declare function createRuntimeGraph(input: RuntimeGraphInput): RuntimeGraph;
+//#endregion
+export { RuntimeGraphReconcileKey as C, diffDerivedValue as E, DiffDerivedValueInput as S, WriteTouchedRecord as T, RuntimeGraphSharedWrite as _, RuntimeGraphAsyncComputed as a, RuntimeGraphWrite as b, RuntimeGraphCell as c, RuntimeGraphComputedDependencyNode as d, RuntimeGraphDelete as f, RuntimeGraphSharedPatchOperation as g, RuntimeGraphSharedPatch as h, RuntimeGraph as i, RuntimeGraphComputed as l, RuntimeGraphRead as m, DomJournalListener as n, RuntimeGraphAsyncSnapshot as o, RuntimeGraphInput as p, DomJournalResult as r, RuntimeGraphCall as s, DomJournalEntry as t, RuntimeGraphComputedDependency as u, RuntimeGraphSubscription as v, RuntimeGraphReconcileOptions as w, createRuntimeGraph as x, RuntimeGraphUpdate as y };

package/dist/{graph-DoSjSC5T.js → graph-DAwgoMQ1.js}

@@ -144,6 +144,201 @@ function arraySlotsEqual(before, after) {
 	});
 }
 //#endregion
+//#region src/graph-reconcile.ts
+const WHOLE_NODE = Object.freeze([Object.freeze([])]);
+/**
+* Compares a derived value with the previous value of the same graph node and
+* reports the graph paths that changed. It never mutates either value: the
+* caller replaces the node's value pointer and invalidates the reported paths.
+*
+* Rules (specs/framework/03-state-graph.md "Derived reconciliation"):
+* - identical references are unchanged, unless a write touched that object in
+*   this flush, in which case the touched remainders are reported; the same
+*   holds when only the previous value held the written object, because an
+*   in-place write left that baseline already carrying the new field;
+* - primitives, functions, `Map`, `Set`, `Date` and class instances are leaves;
+* - plain objects reconcile field by field;
+* - arrays reconcile by declared key, otherwise by element identity, and a
+*   length or structural mismatch reports the array's own path;
+* - a declared key that is missing or duplicated on either side falls back to
+*   structural reconciliation for that array, which reports the array's own
+*   path: keys are never matched partially and an index is never identity;
+* - a missing baseline (first value, or a value whose write-touched record was
+*   already cleared) reports the whole node.
+*
+* `identicalContainers: 'unknown'` is for a caller that has no write-touched
+* record for the flush that produced the new value, so identity below the root
+* proves nothing: every `Object.is`-identical plain object or array met below
+* the root is reported at its own path and is not walked into. An identical
+* root still reports nothing — nothing narrower is known about it, and the
+* caller decides what a wholly identical value means — and identical
+* primitives and other leaves stay unchanged. The default, `'unchanged'`,
+* trusts identity as above.
+*/
+function diffDerivedValue(input) {
+	if (input.baselineStale) return WHOLE_NODE;
+	if (input.previous === void 0 && input.next !== void 0) return WHOLE_NODE;
+	const changed = [];
+	const active = /* @__PURE__ */ new Map();
+	function emitTouched(value, path) {
+		if (!input.touched || typeof value !== "object" || value === null) return;
+		const remainders = input.touched.get(value);
+		if (!remainders) return;
+		for (const remaining of remainders) {
+			const touchedPath = [...path, ...remaining];
+			if (changed.some((entry) => samePath(entry, touchedPath))) continue;
+			changed.push(touchedPath);
+		}
+	}
+	/**
+	* What an identical reference met at `path` reports. With a write-touched
+	* record identity means unchanged apart from the recorded remainders; in
+	* `'unknown'` mode there is no such record, so an identical container below
+	* the root is reported whole rather than trusted or walked into.
+	*/
+	function reportIdentical(value, path) {
+		if (input.identicalContainers === "unknown" && path.length > 0 && isDiffableContainer(value)) {
+			changed.push(path);
+			return;
+		}
+		emitTouched(value, path);
+	}
+	function keyedFor(path) {
+		return input.keyed?.find((entry) => samePath(entry.path, path));
+	}
+	function walkArray(previous, next, path) {
+		const mark = changed.length;
+		const fallBackToStructural = () => {
+			changed.length = mark;
+			changed.push(path);
+		};
+		if (previous.length !== next.length) {
+			fallBackToStructural();
+			return;
+		}
+		const keyed = keyedFor(path);
+		if (keyed) {
+			const fault = keyFault(previous, keyed) ?? keyFault(next, keyed);
+			if (fault) {
+				reportKeyFault(path, keyed, fault);
+				fallBackToStructural();
+				return;
+			}
+		}
+		for (let index = 0; index < next.length; index++) {
+			const previousItem = previous[index];
+			const nextItem = next[index];
+			const itemPath = [...path, String(index)];
+			if (Object.is(previousItem, nextItem)) {
+				reportIdentical(nextItem, itemPath);
+				continue;
+			}
+			if (keyed && isDiffableContainer(previousItem) && isDiffableContainer(nextItem)) {
+				const previousKey = readPath(previousItem, keyed.keyPath);
+				const nextKey = readPath(nextItem, keyed.keyPath);
+				if (!Object.is(previousKey, nextKey)) {
+					fallBackToStructural();
+					return;
+				}
+				walk(previousItem, nextItem, itemPath);
+				continue;
+			}
+			changed.push(itemPath);
+		}
+	}
+	function walkObject(previous, next, path) {
+		for (const key of new Set([...Object.keys(previous), ...Object.keys(next)])) {
+			const keyPath = [...path, key];
+			const inPrevious = Object.prototype.hasOwnProperty.call(previous, key);
+			const inNext = Object.prototype.hasOwnProperty.call(next, key);
+			if (!inPrevious || !inNext) {
+				changed.push(keyPath);
+				continue;
+			}
+			walk(previous[key], next[key], keyPath);
+		}
+	}
+	function walk(previous, next, path) {
+		if (Object.is(previous, next)) {
+			reportIdentical(next, path);
+			return;
+		}
+		if (!isDiffableContainer(previous) || !isDiffableContainer(next)) {
+			changed.push(path);
+			return;
+		}
+		const previousIsArray = Array.isArray(previous);
+		if (previousIsArray !== Array.isArray(next)) {
+			changed.push(path);
+			return;
+		}
+		let pairedWithPrevious = active.get(previous);
+		if (pairedWithPrevious?.has(next)) return;
+		if (!pairedWithPrevious) {
+			pairedWithPrevious = /* @__PURE__ */ new Set();
+			active.set(previous, pairedWithPrevious);
+		}
+		pairedWithPrevious.add(next);
+		try {
+			if (previousIsArray) walkArray(previous, next, path);
+			else walkObject(previous, next, path);
+		} finally {
+			pairedWithPrevious.delete(next);
+			if (pairedWithPrevious.size === 0) active.delete(previous);
+		}
+		emitTouched(previous, path);
+	}
+	walk(input.previous, input.next, []);
+	return changed;
+}
+/**
+* Reads the declared key of every element and reports the first element that
+* has no key or repeats one already used in the same array. Reads only; it
+* never touches the elements it inspects.
+*/
+function keyFault(items, keyed) {
+	const seen = /* @__PURE__ */ new Set();
+	for (let index = 0; index < items.length; index++) {
+		const key = readPath(items[index], keyed.keyPath);
+		if (key === void 0) return {
+			reason: "missing",
+			index,
+			key
+		};
+		if (seen.has(key)) return {
+			reason: "duplicate",
+			index,
+			key
+		};
+		seen.add(key);
+	}
+}
+/**
+* Names the array and the offending key in debug-enabled builds. Keyed
+* reconciliation degrading to structural reconciliation is silent in
+* production — the result is still correct, only coarser.
+*/
+function reportKeyFault(path, keyed, fault) {
+	if (typeof __MARKLESS_DEBUG_ENABLED__ === "undefined" || !__MARKLESS_DEBUG_ENABLED__) return;
+	const array = path.length === 0 ? "the derived value" : `derived path ${path.join(".")}`;
+	const keyPath = keyed.keyPath.length === 0 ? "the element itself" : keyed.keyPath.join(".");
+	const cause = fault.reason === "missing" ? `element ${fault.index} has no key at ${keyPath}` : `key ${describeKey(fault.key)} at ${keyPath} is used by more than one element (element ${fault.index})`;
+	console.warn(`markless: reconciling ${array} by key is not possible because ${cause}; falling back to structural reconciliation for that array.`);
+}
+function describeKey(key) {
+	return typeof key === "string" ? JSON.stringify(key) : String(key);
+}
+/** Plain objects and arrays are the only values reconciliation walks into. */
+function isDiffableContainer(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (Array.isArray(value)) return true;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function samePath(a, b) {
+	return a.length === b.length && a.every((segment, index) => b[index] === segment);
+}
+//#endregion
 //#region src/graph-async.ts
 const ASYNC_SNAPSHOT_META_KEYS = new Set([
 	"status",
@@ -267,10 +462,59 @@ function startAsyncComputed(input) {
 	}
 }
 function publish(input, snapshot) {
+	const previous = input.node.snapshot;
 	input.node.snapshot = snapshot;
-	input.markDirtyPath(input.node.graphNodeId, []);
+	for (const path of asyncCommitPaths(input.node, previous, snapshot)) input.markDirtyPath(input.node.graphNodeId, path);
 	input.scheduleFlush();
 }
+/**
+* The graph paths a snapshot commit changed. Snapshot metadata is addressed as
+* `status`/`version`/`key`/`error`; the fulfilled value is addressed both as
+* `value.<path>` and, for compiled reads, as the bare `<path>` (see
+* `readAsyncComputedNode`), so a changed value path is reported in both
+* coordinate systems.
+*
+* A value commit compares structurally only. Unlike a sync computed, an async
+* snapshot can land long after the flush that wrote the state it embeds, so the
+* per-flush write-touched record is already cleared by the time it publishes.
+* Identity below the root therefore proves nothing here: a runner that returns
+* live state objects publishes the very rows a later write mutated in place,
+* and treating them as unchanged would silently withhold that write from the
+* subscribers of those paths. The diff runs in `identicalContainers: 'unknown'`
+* mode, which reports each identical nested container at its path; a value
+* rebuilt from fresh objects still reconciles field by field, and an identical
+* root is handled by the whole-node rule below.
+*/
+function asyncCommitPaths(node, previous, next) {
+	const paths = [];
+	if (previous.status !== next.status) paths.push(["status"]);
+	if (previous.version !== next.version) paths.push(["version"]);
+	if (!Object.is(snapshotField(previous, "key"), snapshotField(next, "key"))) paths.push(["key"]);
+	if (!Object.is(snapshotField(previous, "error"), snapshotField(next, "error"))) paths.push(["error"]);
+	if (next.status === "pending") return paths;
+	const previousValue = snapshotField(previous, "value");
+	const nextValue = snapshotField(next, "value");
+	if (!Object.is(previousValue, nextValue) && isDiffableContainer(previousValue) && isDiffableContainer(nextValue)) {
+		const changed = diffDerivedValue({
+			previous: previousValue,
+			next: nextValue,
+			keyed: node.reconcile?.keyed,
+			identicalContainers: "unknown"
+		});
+		if (changed.every((path) => path.length > 0)) {
+			for (const path of changed) {
+				paths.push(["value", ...path]);
+				if (!ASYNC_SNAPSHOT_META_KEYS.has(path[0])) paths.push([...path]);
+			}
+			return paths;
+		}
+	}
+	paths.push([]);
+	return paths;
+}
+function snapshotField(snapshot, field) {
+	return snapshot[field];
+}
 //#endregion
 //#region src/graph-computed.ts
 function createRuntimeComputedNodes(computedInput) {
@@ -278,15 +522,35 @@ function createRuntimeComputedNodes(computedInput) {
 	for (const computed of computedInput ?? []) computedNodes.set(computed.graphNodeId, {
 		...computed,
 		dirty: true,
+		invalidated: false,
+		baselineStale: false,
 		value: void 0
 	});
 	return computedNodes;
 }
-function readComputedNode(computed, readGraph, path) {
+function readComputedNode(computed, readGraph, path, reconcile) {
 	const { compute } = computed;
 	if (computed.dirty && compute) {
-		computed.value = compute(readGraph);
+		const previous = computed.value;
+		const next = compute(readGraph);
+		const changed = computed.invalidated && reconcile ? diffDerivedValue({
+			previous,
+			next,
+			keyed: computed.reconcile?.keyed,
+			touched: reconcile.touched,
+			baselineStale: computed.baselineStale
+		}) : [];
+		computed.value = next;
 		computed.dirty = false;
+		computed.invalidated = false;
+		computed.baselineStale = false;
+		if (reconcile && changed.length > 0) {
+			for (const changedPath of changed) reconcile.dirtyPaths.push({
+				graphNodeId: computed.graphNodeId,
+				path: changedPath
+			});
+			reconcile.scheduleFlush();
+		}
 	}
 	return readPath(computed.value, path);
 }
@@ -296,10 +560,8 @@ function markComputedDirty(input) {
 	const computed = input.computedNodes.get(input.graphNodeId);
 	if (!computed?.compute) return;
 	computed.dirty = true;
-	input.dirtyPaths.push({
-		graphNodeId: input.graphNodeId,
-		path: []
-	});
+	computed.invalidated = true;
+	input.dirtyComputedIds.add(input.graphNodeId);
 	for (const dependent of input.computedNodes.values()) if (dependent.dependencies.some((dependency) => dependency.graphNodeId === input.graphNodeId) && dependent.compute) markComputedDirty({
 		...input,
 		graphNodeId: dependent.graphNodeId
@@ -437,6 +699,8 @@ function createRuntimeGraph(input) {
 	const subscriptions = [];
 	const journalListeners = [];
 	const dirtyPaths = [];
+	const dirtyComputedIds = /* @__PURE__ */ new Set();
+	const writeTouched = /* @__PURE__ */ new Map();
 	const journal = [];
 	let flushScheduled = false;
 	let flushing = false;
@@ -445,9 +709,16 @@ function createRuntimeGraph(input) {
 		cells.set(cell.graphNodeId, cell.value);
 		if (cell.readInitializer) readInitializers.set(cell.graphNodeId, cell.readInitializer);
 	}
+	const reconcileContext = {
+		dirtyPaths,
+		touched: writeTouched,
+		scheduleFlush: () => {
+			scheduleFlush();
+		}
+	};
 	const readGraph = (graphNodeId, path = []) => {
 		const computed = computedNodes.get(graphNodeId);
-		if (computed?.compute) return readComputedNode(computed, readGraph, path);
+		if (computed?.compute) return readComputedNode(computed, readGraph, path, reconcileContext);
 		const asyncComputed = asyncComputedNodes.get(graphNodeId);
 		if (asyncComputed) return readAsyncComputedNode(asyncComputed, path, () => demandAsyncComputed$1(asyncComputed));
 		const initialize = readInitializers.get(graphNodeId);
@@ -465,17 +736,34 @@ function createRuntimeGraph(input) {
 		}
 		return readPath(cells.get(graphNodeId), path);
 	};
+	const recordWriteTouched = (graphNodeId, path) => {
+		if (computedNodes.has(graphNodeId)) return;
+		let container = cells.get(graphNodeId);
+		for (let depth = 0; depth <= path.length; depth++) {
+			if (typeof container === "object" && container !== null) {
+				const remainders = writeTouched.get(container) ?? [];
+				const remaining = path.slice(depth);
+				if (!remainders.some((entry) => samePath(entry, remaining))) {
+					remainders.push(remaining);
+					writeTouched.set(container, remainders);
+				}
+			}
+			if (depth === path.length) break;
+			container = readPath(container, [path[depth]]);
+		}
+	};
 	const markDirtyPath = (graphNodeId, path) => {
 		dirtyPaths.push({
 			graphNodeId,
 			path
 		});
+		recordWriteTouched(graphNodeId, path);
 		markDirtyComputedDependencies({
 			graphNodeId,
 			path,
 			computedNodes,
 			asyncComputedNodes,
-			dirtyPaths,
+			dirtyComputedIds,
 			invalidateAsyncComputed: invalidateAsyncComputed$1
 		});
 	};
@@ -514,12 +802,32 @@ function createRuntimeGraph(input) {
 		activeFlush = runFlush();
 		return activeFlush;
 	};
+	const recomputeSubscribedComputeds = () => {
+		for (const graphNodeId of Array.from(dirtyComputedIds)) {
+			if (!computedNodes.get(graphNodeId)?.dirty) {
+				dirtyComputedIds.delete(graphNodeId);
+				continue;
+			}
+			if (!subscriptions.some((subscription) => subscription.graphNodeId === graphNodeId)) continue;
+			dirtyComputedIds.delete(graphNodeId);
+			readGraph(graphNodeId);
+		}
+	};
+	const settleReconcileBaselines = () => {
+		for (const graphNodeId of dirtyComputedIds) {
+			const computed = computedNodes.get(graphNodeId);
+			if (computed?.dirty) computed.baselineStale = true;
+		}
+		dirtyComputedIds.clear();
+		writeTouched.clear();
+	};
 	const runFlush = async () => {
 		flushScheduled = false;
 		flushing = true;
 		try {
 			try {
 				while (dirtyPaths.length > 0) {
+					recomputeSubscribedComputeds();
 					const pending = dirtyPaths.splice(0);
 					const ranSubscriptions = /* @__PURE__ */ new Set();
 					for (const subscription of subscriptions) {
@@ -530,6 +838,7 @@ function createRuntimeGraph(input) {
 					}
 				}
 			} finally {
+				settleReconcileBaselines();
 				flushing = false;
 			}
 			await notifyJournalListeners();
@@ -555,6 +864,22 @@ function createRuntimeGraph(input) {
 		write(write) {
 			const path = write.path ?? [];
 			const current = cells.get(write.graphNodeId);
+			const computed = computedNodes.get(write.graphNodeId);
+			if (computed && !computed.compute && path.length === 0) {
+				const changed = diffDerivedValue({
+					previous: current,
+					next: write.value,
+					keyed: computed.reconcile?.keyed,
+					touched: writeTouched,
+					baselineStale: computed.baselineStale
+				});
+				cells.set(write.graphNodeId, write.value);
+				computed.baselineStale = false;
+				if (changed.length === 0) return;
+				for (const changedPath of changed) markDirtyPath(write.graphNodeId, changedPath);
+				scheduleFlush();
+				return;
+			}
 			if (Object.is(readPath(current, path), write.value)) return;
 			cells.set(write.graphNodeId, writePath(current, path, write.value));
 			markDirtyPath(write.graphNodeId, dirtyPathForGraphWrite(current, path));
@@ -613,4 +938,4 @@ function createRuntimeGraph(input) {
 	};
 }
 //#endregion
-export { createRuntimeGraph as t };
+export { diffDerivedValue as n, createRuntimeGraph as t };

package/dist/graph.d.ts

@@ -1,145 +1,2 @@
-import { ProtocolStatePayload } from "@markless/serializer";
-
-//#region src/graph.d.ts
-type RuntimeGraphCell = {
-  readonly graphNodeId: string;
-  readonly value: unknown;
-  readonly readInitializer?: () => unknown;
-};
-type RuntimeGraphRead = (graphNodeId: string, path?: ReadonlyArray<string>) => unknown;
-type RuntimeGraphComputedDependency = {
-  readonly graphNodeId: string;
-  readonly path?: ReadonlyArray<string>;
-};
-type RuntimeGraphComputed = {
-  readonly graphNodeId: string;
-  readonly dependencies: ReadonlyArray<RuntimeGraphComputedDependency>;
-  readonly compute: (read: RuntimeGraphRead) => unknown;
-};
-type RuntimeGraphComputedDependencyNode = Omit<RuntimeGraphComputed, 'compute'> & {
-  readonly compute?: never;
-};
-type RuntimeGraphAsyncSnapshot = {
-  readonly status: 'idle';
-  readonly version: 0;
-} | {
-  readonly status: 'pending';
-  readonly version: number;
-  readonly key: unknown;
-  readonly value?: unknown;
-} | {
-  readonly status: 'fulfilled';
-  readonly version: number;
-  readonly key: unknown;
-  readonly value: unknown;
-} | {
-  readonly status: 'rejected';
-  readonly version: number;
-  readonly key: unknown;
-  readonly error: unknown;
-};
-type RuntimeGraphAsyncComputed = {
-  readonly graphNodeId: string;
-  readonly dependencies: ReadonlyArray<RuntimeGraphComputedDependency>;
-  readonly initialSnapshot?: RuntimeGraphAsyncSnapshot;
-  readonly key: (read: RuntimeGraphRead) => unknown;
-  readonly run: (input: {
-    readonly key: unknown;
-    readonly signal: AbortSignal;
-    readonly read: RuntimeGraphRead;
-  }) => unknown | Promise<unknown>;
-};
-type DomJournalEntry = {
-  readonly type: 'setText';
-  readonly locator: string;
-  readonly value: unknown;
-} | {
-  readonly type: 'setAttr' | 'setProp';
-  readonly locator: string;
-  readonly name: string;
-  readonly value: unknown;
-} | {
-  readonly type: 'insertRange';
-  readonly locator: string;
-  readonly fragment: unknown;
-} | {
-  readonly type: 'removeRange';
-  readonly locator: string;
-} | {
-  readonly type: 'moveRange';
-  readonly locator: string;
-  readonly before: string;
-} | {
-  readonly type: 'runCleanup';
-  readonly locator: string;
-};
-type DomJournalResult = DomJournalEntry | ReadonlyArray<DomJournalEntry>;
-type DomJournalListener = (entries: ReadonlyArray<DomJournalEntry>) => void | Promise<void>;
-type RuntimeGraphInput = {
-  readonly cells: ReadonlyArray<RuntimeGraphCell>;
-  readonly computed?: ReadonlyArray<RuntimeGraphComputed | RuntimeGraphComputedDependencyNode>;
-  readonly asyncComputed?: ReadonlyArray<RuntimeGraphAsyncComputed>;
-  readonly sharedDefinitions?: ProtocolStatePayload['sharedDefinitions'];
-};
-type RuntimeGraphWrite = {
-  readonly graphNodeId: string;
-  readonly path?: ReadonlyArray<string>;
-  readonly value: unknown;
-};
-type RuntimeGraphSharedWrite = {
-  readonly definitionId: string;
-  readonly propertyName: string;
-  readonly path?: ReadonlyArray<string>;
-  readonly value: unknown;
-};
-type RuntimeGraphSharedPatchOperation = readonly [operation: 'set', path: ReadonlyArray<string>, value: unknown];
-type RuntimeGraphSharedPatch = {
-  readonly id: string;
-  readonly scope?: RuntimeSharedDefinition['scope'];
-  readonly version: number;
-  readonly patch: ReadonlyArray<RuntimeGraphSharedPatchOperation>;
-};
-type RuntimeGraphUpdate = {
-  readonly graphNodeId: string;
-  readonly path?: ReadonlyArray<string>;
-  readonly update: (value: unknown) => unknown;
-  readonly returnValue?: 'previous' | 'next';
-};
-type RuntimeGraphCall = {
-  readonly graphNodeId: string;
-  readonly path?: ReadonlyArray<string>;
-  readonly method: string;
-  readonly args?: ReadonlyArray<unknown>;
-};
-type RuntimeGraphDelete = {
-  readonly graphNodeId: string;
-  readonly path: ReadonlyArray<string>;
-};
-type RuntimeGraphSubscription = {
-  readonly id: string;
-  readonly graphNodeId: string;
-  readonly path?: ReadonlyArray<string>;
-  readonly run: (value: unknown) => DomJournalResult | void | Promise<DomJournalResult | void>;
-};
-type RuntimeGraph = {
-  readonly read: (graphNodeId: string, path?: ReadonlyArray<string>) => unknown; /** Available only in debug-enabled builds (`__MARKLESS_DEBUG_ENABLED__`). */
-  readonly peekAsyncSnapshot?: (graphNodeId: string) => RuntimeGraphAsyncSnapshot | undefined;
-  readonly readShared: (definitionId: string, propertyName: string, path?: ReadonlyArray<string>) => unknown;
-  readonly writeShared: (write: RuntimeGraphSharedWrite) => boolean;
-  readonly getSharedDefinition: (definitionId: string) => NonNullable<ProtocolStatePayload['sharedDefinitions']>[number] | undefined;
-  readonly listSharedDefinitions: () => NonNullable<ProtocolStatePayload['sharedDefinitions']>;
-  readonly takeSharedPatches: () => RuntimeGraphSharedPatch[];
-  readonly applySharedPatch: (patch: RuntimeGraphSharedPatch) => boolean;
-  readonly write: (write: RuntimeGraphWrite) => void;
-  readonly update: (update: RuntimeGraphUpdate) => unknown;
-  readonly call: (call: RuntimeGraphCall) => unknown;
-  readonly delete: (deletion: RuntimeGraphDelete) => boolean;
-  readonly subscribe: (subscription: RuntimeGraphSubscription) => () => void;
-  readonly subscribeJournal: (listener: DomJournalListener) => () => void;
-  readonly flush: () => Promise<void>;
-  readonly takeJournal: () => DomJournalEntry[];
-};
-type RuntimeSharedDefinition = NonNullable<ProtocolStatePayload['sharedDefinitions']>[number];
-declare function createRuntimeGraph(input: RuntimeGraphInput): RuntimeGraph;
-//#endregion
-export { DomJournalEntry, DomJournalListener, DomJournalResult, RuntimeGraph, RuntimeGraphAsyncComputed, RuntimeGraphAsyncSnapshot, RuntimeGraphCall, RuntimeGraphCell, RuntimeGraphComputed, RuntimeGraphComputedDependency, RuntimeGraphComputedDependencyNode, RuntimeGraphDelete, RuntimeGraphInput, RuntimeGraphRead, RuntimeGraphSharedPatch, RuntimeGraphSharedPatchOperation, RuntimeGraphSharedWrite, RuntimeGraphSubscription, RuntimeGraphUpdate, RuntimeGraphWrite, createRuntimeGraph };
+import { C as RuntimeGraphReconcileKey, E as diffDerivedValue, S as DiffDerivedValueInput, T as WriteTouchedRecord, _ as RuntimeGraphSharedWrite, a as RuntimeGraphAsyncComputed, b as RuntimeGraphWrite, c as RuntimeGraphCell, d as RuntimeGraphComputedDependencyNode, f as RuntimeGraphDelete, g as RuntimeGraphSharedPatchOperation, h as RuntimeGraphSharedPatch, i as RuntimeGraph, l as RuntimeGraphComputed, m as RuntimeGraphRead, n as DomJournalListener, o as RuntimeGraphAsyncSnapshot, p as RuntimeGraphInput, r as DomJournalResult, s as RuntimeGraphCall, t as DomJournalEntry, u as RuntimeGraphComputedDependency, v as RuntimeGraphSubscription, w as RuntimeGraphReconcileOptions, x as createRuntimeGraph, y as RuntimeGraphUpdate } from "./graph-C1ACA8O1.js";
+export { DiffDerivedValueInput, DomJournalEntry, DomJournalListener, DomJournalResult, RuntimeGraph, RuntimeGraphAsyncComputed, RuntimeGraphAsyncSnapshot, RuntimeGraphCall, RuntimeGraphCell, RuntimeGraphComputed, RuntimeGraphComputedDependency, RuntimeGraphComputedDependencyNode, RuntimeGraphDelete, RuntimeGraphInput, RuntimeGraphRead, RuntimeGraphReconcileKey, RuntimeGraphReconcileOptions, RuntimeGraphSharedPatch, RuntimeGraphSharedPatchOperation, RuntimeGraphSharedWrite, RuntimeGraphSubscription, RuntimeGraphUpdate, RuntimeGraphWrite, WriteTouchedRecord, createRuntimeGraph, diffDerivedValue };

package/dist/graph.js

@@ -1,2 +1,2 @@
-import { t as createRuntimeGraph } from "./graph-DoSjSC5T.js";
-export { createRuntimeGraph };
+import { n as diffDerivedValue, t as createRuntimeGraph } from "./graph-DAwgoMQ1.js";
+export { createRuntimeGraph, diffDerivedValue };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { DomJournalEntry, DomJournalListener, DomJournalResult, RuntimeGraph, RuntimeGraphAsyncComputed, RuntimeGraphAsyncSnapshot, RuntimeGraphCall, RuntimeGraphCell, RuntimeGraphComputed, RuntimeGraphComputedDependency, RuntimeGraphComputedDependencyNode, RuntimeGraphDelete, RuntimeGraphInput, RuntimeGraphRead, RuntimeGraphSharedPatch, RuntimeGraphSharedPatchOperation, RuntimeGraphSharedWrite, RuntimeGraphSubscription, RuntimeGraphUpdate, RuntimeGraphWrite, createRuntimeGraph } from "./graph.js";
-export { DomJournalEntry, DomJournalListener, DomJournalResult, RuntimeGraph, RuntimeGraphAsyncComputed, RuntimeGraphAsyncSnapshot, RuntimeGraphCall, RuntimeGraphCell, RuntimeGraphComputed, RuntimeGraphComputedDependency, RuntimeGraphComputedDependencyNode, RuntimeGraphDelete, RuntimeGraphInput, RuntimeGraphRead, RuntimeGraphSharedPatch, RuntimeGraphSharedPatchOperation, RuntimeGraphSharedWrite, RuntimeGraphSubscription, RuntimeGraphUpdate, RuntimeGraphWrite, createRuntimeGraph };
+import { C as RuntimeGraphReconcileKey, E as diffDerivedValue, S as DiffDerivedValueInput, T as WriteTouchedRecord, _ as RuntimeGraphSharedWrite, a as RuntimeGraphAsyncComputed, b as RuntimeGraphWrite, c as RuntimeGraphCell, d as RuntimeGraphComputedDependencyNode, f as RuntimeGraphDelete, g as RuntimeGraphSharedPatchOperation, h as RuntimeGraphSharedPatch, i as RuntimeGraph, l as RuntimeGraphComputed, m as RuntimeGraphRead, n as DomJournalListener, o as RuntimeGraphAsyncSnapshot, p as RuntimeGraphInput, r as DomJournalResult, s as RuntimeGraphCall, t as DomJournalEntry, u as RuntimeGraphComputedDependency, v as RuntimeGraphSubscription, w as RuntimeGraphReconcileOptions, x as createRuntimeGraph, y as RuntimeGraphUpdate } from "./graph-C1ACA8O1.js";
+export { DiffDerivedValueInput, DomJournalEntry, DomJournalListener, DomJournalResult, RuntimeGraph, RuntimeGraphAsyncComputed, RuntimeGraphAsyncSnapshot, RuntimeGraphCall, RuntimeGraphCell, RuntimeGraphComputed, RuntimeGraphComputedDependency, RuntimeGraphComputedDependencyNode, RuntimeGraphDelete, RuntimeGraphInput, RuntimeGraphRead, RuntimeGraphReconcileKey, RuntimeGraphReconcileOptions, RuntimeGraphSharedPatch, RuntimeGraphSharedPatchOperation, RuntimeGraphSharedWrite, RuntimeGraphSubscription, RuntimeGraphUpdate, RuntimeGraphWrite, WriteTouchedRecord, createRuntimeGraph, diffDerivedValue };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { t as createRuntimeGraph } from "./graph-DoSjSC5T.js";
-export { createRuntimeGraph };
+import { n as diffDerivedValue, t as createRuntimeGraph } from "./graph-DAwgoMQ1.js";
+export { createRuntimeGraph, diffDerivedValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markless/runtime",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Markless state graph runtime: reads, writes, computed invalidation, flush journal.",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,7 @@
     }
   },
   "dependencies": {
-    "@markless/serializer": "0.3.1"
+    "@markless/serializer": "0.3.2"
   },
   "files": [
     "dist"