doxum 0.1.41 → 0.1.42

package/dist/{transform-D6njdP3k.cjs → transform-BPh55GWO.cjs}

@@ -261,7 +261,8 @@ var ProjectionDisposedError = class extends Error {
 //#endregion
 //#region core/src/projection/graph/scheduler.ts
 const createScheduler = (onError) => {
-	let disposed = false;
+	let lifecycle = "active";
+	let lockDepth = 0;
 	let depth = 0;
 	let batchSequence = 0;
 	let activeBatch;
@@ -279,13 +280,39 @@ const createScheduler = (onError) => {
 	let reportingFailures = [];
 	const guards = /* @__PURE__ */ new Set();
 	const assertActive = () => {
-		if (disposed) throw new ProjectionDisposedError();
+		if (lifecycle === "disposed" || phase === "release") throw new ProjectionDisposedError();
 	};
 	const assertIdle = () => {
 		assertActive();
-		if (phase !== "idle") throw new Error("Projection cannot be re-entered during input callbacks, processing or notification.");
+		if (phase !== "idle" && phase !== "cleanup") throw new Error("Projection cannot be re-entered during input callbacks, processing or notification.");
+	};
+	const assertCommand = () => {
+		assertActive();
+		if (lifecycle === "closing" || phase === "cleanup") throw new Error("Projection cleanup only permits reads and unsubscribe.");
+		assertIdle();
+	};
+	const lock = (value) => {
+		const previous = lockDepth;
+		lockDepth += value ? 1 : -1;
+		if (!previous || !lockDepth) guards.forEach((guard) => guard(value));
+	};
+	const beginClose = () => {
+		if (lifecycle !== "active") return false;
+		assertCommand();
+		lifecycle = "closing";
+		return true;
+	};
+	const withPhase = (next, run) => {
+		const previous = phase;
+		phase = next;
+		lock(true);
+		try {
+			return run();
+		} finally {
+			lock(false);
+			phase = previous;
+		}
 	};
-	const lock = (value) => guards.forEach((guard) => guard(value));
 	const markDirty = (producer) => {
 		const pending = [producer];
 		for (let index = 0; index < pending.length; index++) {
@@ -302,7 +329,7 @@ const createScheduler = (onError) => {
 	};
 	const errorFor = (producer, cause, kind = producer.kind === "source" ? "source" : "processor") => new ProjectionError(kind, cause);
 	const capture = (source) => {
-		if (disposed) return;
+		if (lifecycle === "disposed") return;
 		if (phase !== "idle") {
 			source.fault = errorFor(source, /* @__PURE__ */ new Error("Source changed while projection was running."), "source");
 			errors.push(source.fault);
@@ -422,18 +449,9 @@ const createScheduler = (onError) => {
 			}
 		}
 	};
-	const compute = (run) => {
-		phase = "compute";
-		lock(true);
-		try {
-			return run();
-		} finally {
-			lock(false);
-			phase = "idle";
-		}
-	};
+	const compute = (run) => withPhase("compute", run);
 	const settle = () => {
-		if (disposed || depth || phase !== "idle") return;
+		if (lifecycle !== "active" || depth || phase !== "idle") return;
 		const cause = settleCause();
 		compute(() => {
 			for (const producer of dirty) advance(producer, cause);
@@ -449,7 +467,7 @@ const createScheduler = (onError) => {
 		}
 	};
 	const flush = () => {
-		if (disposed || depth) return [];
+		if (lifecycle !== "active" || depth || phase === "cleanup" || phase === "release") return [];
 		if (emissions.size || completed.size) profile.projection("flushes");
 		phase = "notify";
 		lock(true);
@@ -497,7 +515,7 @@ const createScheduler = (onError) => {
 		return result;
 	};
 	const batch = (callback, options) => {
-		assertIdle();
+		assertCommand();
 		if (depth === 0) activeBatch = Object.freeze({
 			id: ++batchSequence,
 			...options?.cause === void 0 ? {} : { cause: options.cause }
@@ -524,7 +542,8 @@ const createScheduler = (onError) => {
 		}
 	};
 	const releaseProducer = (producer) => {
-		assertIdle();
+		if (producer.disposed) return;
+		if (phase !== "release") assertIdle();
 		if (producer.outputs.some((output) => output.hasConsumers())) throw new Error("Projection producer is still used by another processor.");
 		producer.disposed = true;
 		dirty.delete(producer);
@@ -554,6 +573,16 @@ const createScheduler = (onError) => {
 	return {
 		assertActive,
 		assertIdle,
+		assertCommand,
+		beginClose,
+		cleanup(run) {
+			assertIdle();
+			return withPhase("cleanup", run);
+		},
+		releaseOwned(run) {
+			assertIdle();
+			return withPhase("release", run);
+		},
 		capture,
 		settle,
 		ensureCurrent,
@@ -562,15 +591,17 @@ const createScheduler = (onError) => {
 		registerGuard(guard) {
 			assertActive();
 			guards.add(guard);
+			if (lockDepth) guard(true);
 			let registered = true;
 			return () => {
 				if (!registered) return;
 				registered = false;
 				guards.delete(guard);
+				if (lockDepth) guard(false);
 			};
 		},
 		get active() {
-			return !disposed;
+			return lifecycle !== "disposed" && phase !== "release";
 		},
 		addSource(source) {
 			assertIdle();
@@ -584,7 +615,7 @@ const createScheduler = (onError) => {
 		releaseProducer,
 		nextId: () => sequence++,
 		acceptInput(callback) {
-			assertIdle();
+			assertCommand();
 			phase = "input";
 			lock(true);
 			try {
@@ -600,38 +631,39 @@ const createScheduler = (onError) => {
 		},
 		batch,
 		batchContext: () => activeBatch,
-		dispose() {
-			if (disposed) return;
-			assertIdle();
-			disposed = true;
+		dispose(releaseConsumers, releaseSources) {
+			if (lifecycle === "disposed") return;
+			if (lifecycle === "active") beginClose();
 			const failures = [];
-			processors.forEach((processor) => {
-				processor.disposed = true;
-				try {
-					processor.release();
-				} catch (error) {
-					failures.push(error);
-				}
-			});
-			sources.forEach((source) => {
-				source.disposed = true;
+			const attempt = (run) => {
 				try {
-					source.release();
+					run();
 				} catch (error) {
 					failures.push(error);
 				}
-			});
-			processors.clear();
-			sources.clear();
-			pendingSources.clear();
-			dirty.clear();
-			queued.clear();
-			completed.clear();
-			emissions.clear();
-			forced.clear();
-			guards.clear();
-			errors.length = 0;
-			reportingFailures = [];
+			};
+			try {
+				withPhase("release", () => {
+					attempt(releaseConsumers);
+					for (const processor of [...processors].reverse()) attempt(() => releaseProducer(processor));
+					for (const source of [...sources].reverse()) attempt(() => releaseProducer(source));
+					attempt(releaseSources);
+				});
+			} finally {
+				lifecycle = "disposed";
+				processors.clear();
+				sources.clear();
+				pendingSources.clear();
+				dirty.clear();
+				queued.clear();
+				completed.clear();
+				emissions.clear();
+				forced.clear();
+				guards.clear();
+				errors.length = 0;
+				reportingFailures = [];
+			}
+			if (failures.length === 1) throw failures[0];
 			if (failures.length) throw new AggregateError(failures, "Projection cleanup failed.");
 		}
 	};

package/dist/{transform-CKJ1ivhz.js → transform-BvDYPUMm.js}

@@ -261,7 +261,8 @@ var ProjectionDisposedError = class extends Error {
 //#endregion
 //#region core/src/projection/graph/scheduler.ts
 const createScheduler = (onError) => {
-	let disposed = false;
+	let lifecycle = "active";
+	let lockDepth = 0;
 	let depth = 0;
 	let batchSequence = 0;
 	let activeBatch;
@@ -279,13 +280,39 @@ const createScheduler = (onError) => {
 	let reportingFailures = [];
 	const guards = /* @__PURE__ */ new Set();
 	const assertActive = () => {
-		if (disposed) throw new ProjectionDisposedError();
+		if (lifecycle === "disposed" || phase === "release") throw new ProjectionDisposedError();
 	};
 	const assertIdle = () => {
 		assertActive();
-		if (phase !== "idle") throw new Error("Projection cannot be re-entered during input callbacks, processing or notification.");
+		if (phase !== "idle" && phase !== "cleanup") throw new Error("Projection cannot be re-entered during input callbacks, processing or notification.");
+	};
+	const assertCommand = () => {
+		assertActive();
+		if (lifecycle === "closing" || phase === "cleanup") throw new Error("Projection cleanup only permits reads and unsubscribe.");
+		assertIdle();
+	};
+	const lock = (value) => {
+		const previous = lockDepth;
+		lockDepth += value ? 1 : -1;
+		if (!previous || !lockDepth) guards.forEach((guard) => guard(value));
+	};
+	const beginClose = () => {
+		if (lifecycle !== "active") return false;
+		assertCommand();
+		lifecycle = "closing";
+		return true;
+	};
+	const withPhase = (next, run) => {
+		const previous = phase;
+		phase = next;
+		lock(true);
+		try {
+			return run();
+		} finally {
+			lock(false);
+			phase = previous;
+		}
 	};
-	const lock = (value) => guards.forEach((guard) => guard(value));
 	const markDirty = (producer) => {
 		const pending = [producer];
 		for (let index = 0; index < pending.length; index++) {
@@ -302,7 +329,7 @@ const createScheduler = (onError) => {
 	};
 	const errorFor = (producer, cause, kind = producer.kind === "source" ? "source" : "processor") => new ProjectionError(kind, cause);
 	const capture = (source) => {
-		if (disposed) return;
+		if (lifecycle === "disposed") return;
 		if (phase !== "idle") {
 			source.fault = errorFor(source, /* @__PURE__ */ new Error("Source changed while projection was running."), "source");
 			errors.push(source.fault);
@@ -422,18 +449,9 @@ const createScheduler = (onError) => {
 			}
 		}
 	};
-	const compute = (run) => {
-		phase = "compute";
-		lock(true);
-		try {
-			return run();
-		} finally {
-			lock(false);
-			phase = "idle";
-		}
-	};
+	const compute = (run) => withPhase("compute", run);
 	const settle = () => {
-		if (disposed || depth || phase !== "idle") return;
+		if (lifecycle !== "active" || depth || phase !== "idle") return;
 		const cause = settleCause();
 		compute(() => {
 			for (const producer of dirty) advance(producer, cause);
@@ -449,7 +467,7 @@ const createScheduler = (onError) => {
 		}
 	};
 	const flush = () => {
-		if (disposed || depth) return [];
+		if (lifecycle !== "active" || depth || phase === "cleanup" || phase === "release") return [];
 		if (emissions.size || completed.size) profile.projection("flushes");
 		phase = "notify";
 		lock(true);
@@ -497,7 +515,7 @@ const createScheduler = (onError) => {
 		return result;
 	};
 	const batch = (callback, options) => {
-		assertIdle();
+		assertCommand();
 		if (depth === 0) activeBatch = Object.freeze({
 			id: ++batchSequence,
 			...options?.cause === void 0 ? {} : { cause: options.cause }
@@ -524,7 +542,8 @@ const createScheduler = (onError) => {
 		}
 	};
 	const releaseProducer = (producer) => {
-		assertIdle();
+		if (producer.disposed) return;
+		if (phase !== "release") assertIdle();
 		if (producer.outputs.some((output) => output.hasConsumers())) throw new Error("Projection producer is still used by another processor.");
 		producer.disposed = true;
 		dirty.delete(producer);
@@ -554,6 +573,16 @@ const createScheduler = (onError) => {
 	return {
 		assertActive,
 		assertIdle,
+		assertCommand,
+		beginClose,
+		cleanup(run) {
+			assertIdle();
+			return withPhase("cleanup", run);
+		},
+		releaseOwned(run) {
+			assertIdle();
+			return withPhase("release", run);
+		},
 		capture,
 		settle,
 		ensureCurrent,
@@ -562,15 +591,17 @@ const createScheduler = (onError) => {
 		registerGuard(guard) {
 			assertActive();
 			guards.add(guard);
+			if (lockDepth) guard(true);
 			let registered = true;
 			return () => {
 				if (!registered) return;
 				registered = false;
 				guards.delete(guard);
+				if (lockDepth) guard(false);
 			};
 		},
 		get active() {
-			return !disposed;
+			return lifecycle !== "disposed" && phase !== "release";
 		},
 		addSource(source) {
 			assertIdle();
@@ -584,7 +615,7 @@ const createScheduler = (onError) => {
 		releaseProducer,
 		nextId: () => sequence++,
 		acceptInput(callback) {
-			assertIdle();
+			assertCommand();
 			phase = "input";
 			lock(true);
 			try {
@@ -600,38 +631,39 @@ const createScheduler = (onError) => {
 		},
 		batch,
 		batchContext: () => activeBatch,
-		dispose() {
-			if (disposed) return;
-			assertIdle();
-			disposed = true;
+		dispose(releaseConsumers, releaseSources) {
+			if (lifecycle === "disposed") return;
+			if (lifecycle === "active") beginClose();
 			const failures = [];
-			processors.forEach((processor) => {
-				processor.disposed = true;
-				try {
-					processor.release();
-				} catch (error) {
-					failures.push(error);
-				}
-			});
-			sources.forEach((source) => {
-				source.disposed = true;
+			const attempt = (run) => {
 				try {
-					source.release();
+					run();
 				} catch (error) {
 					failures.push(error);
 				}
-			});
-			processors.clear();
-			sources.clear();
-			pendingSources.clear();
-			dirty.clear();
-			queued.clear();
-			completed.clear();
-			emissions.clear();
-			forced.clear();
-			guards.clear();
-			errors.length = 0;
-			reportingFailures = [];
+			};
+			try {
+				withPhase("release", () => {
+					attempt(releaseConsumers);
+					for (const processor of [...processors].reverse()) attempt(() => releaseProducer(processor));
+					for (const source of [...sources].reverse()) attempt(() => releaseProducer(source));
+					attempt(releaseSources);
+				});
+			} finally {
+				lifecycle = "disposed";
+				processors.clear();
+				sources.clear();
+				pendingSources.clear();
+				dirty.clear();
+				queued.clear();
+				completed.clear();
+				emissions.clear();
+				forced.clear();
+				guards.clear();
+				errors.length = 0;
+				reportingFailures = [];
+			}
+			if (failures.length === 1) throw failures[0];
 			if (failures.length) throw new AggregateError(failures, "Projection cleanup failed.");
 		}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxum",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "private": false,
   "license": "MIT",
   "description": "Doxum is a typed runtime for complex mutable documents.",

package/skills/doxum-runtime/references/integrations.md

@@ -88,16 +88,47 @@ React consumes Doxum through `doxum/react` only. Do not duplicate Runtime subscr
 ### Projection provider
 
 ```tsx
-const runtime = useMemo(() => createProjectionRuntime({ onError: report }), []);
+// runtime is created and disposed by the application/service outside rendering.
+function ApplicationView({ runtime }: { runtime: ProjectionRuntime }) {
+  return (
+    <ProjectionProvider runtime={runtime} fallback={null}>
+      <App />
+    </ProjectionProvider>
+  );
+}
+```
+
+`runtime` mode owns a child scope, not the supplied Runtime. Scope acquisition happens
+after commit; first render and SSR show `fallback` (default `null`). Every Effect setup
+uses a fresh scope, including StrictMode replay. A runtime change replaces the scope
+and remounts the child subtree with fresh local definitions/state. Abandoned renders
+acquire no scope. Do not create a disposable scope or Runtime in `useMemo` and rely on
+an Effect to clean up that render-created resource.
 
-return (
-  <ProjectionProvider value={runtime}>
-    <App />
-  </ProjectionProvider>
-);
+For synchronous SSR or externally owned lifetimes, inject the owner explicitly:
+`<ProjectionProvider value={runtimeOrScope}>`. This mode never disposes the supplied
+owner and takes no fallback. Never combine `runtime` and `value`.
+
+`useProjectionScope()` returns an existing context scope. It works inside a managed
+Provider or `value={scope}`, and throws for a missing Provider or `value={runtime}`.
+It does not accept a Runtime argument or allocate another scope. To declare local
+state, memoize a definition owned by the current scope, with the scope as a dependency:
+
+```tsx
+const scope = useProjectionScope();
+const mode = useMemo(() => scope.own(input('all')), [scope]);
+const [value, update] = useInput(mode);
 ```
 
-The provider accepts a root `ProjectionRuntime` or `ProjectionScope`. The component/service that creates it owns disposal. Do not create a new Runtime on every render.
+A scope does not adopt root projections merely because a component reads them. Use
+`scope.onDispose` for synchronous finalization that needs projection reads; do not rely
+on React parent/child cleanup order. Cleanup may read and unsubscribe, but may not write,
+batch, subscribe or register more resources. Perform domain commands before disposal.
+Registration returns an idempotent cancellation function suitable for Effect cleanup.
+If work must run on scope shutdown, leave its registration active until that shutdown;
+cancelling it in an earlier component cleanup intentionally prevents it from running.
+Parent Runtime disposal ends its scopes; subsequent React cleanup and unsubscribe are
+safe no-ops. Ordinary reads after disposal still throw.
 
 ### Reading projections
 

package/skills/doxum-runtime/references/invariants.md

@@ -71,6 +71,19 @@ This file is maintainer-only. Application/library consumers should use [Public A
    Sorting changed keys is internal lookup work, never formal order. Count node
    allocations and sorting separately from selector calls; this is not an O(delta)
    guarantee for all collection maintenance.
+   Scheduler owns Runtime active/closing/disposed state and cleanup/read/command
+   admission; scope owns only its status and local resource membership. Cleanup stacks
+   are cancellable and LIFO, child callbacks precede parent callbacks, and graph teardown
+   starts only after all callbacks. Cleanup permits demanded/lazy reads but no new public
+   resources or writes. Restore the caller phase after nested computation and balance
+   document locks for connections registered/detached while a lock is held. Release
+   dependents before dependencies; close all resources even after failures. Disposed
+   reads still throw; only repeated dispose/unsubscribe/cancellation are no-ops.
+   Simple listener sets share subscription.ts registration identity/removal semantics;
+   notification snapshot order/error policy remains with each notification owner.
+   React managed scope acquisition happens after commit, never in render/useMemo;
+   borrowed owner injection never takes disposal ownership. Fresh Effect setups own
+   fresh scopes/subtrees. Keep the managed first-render/SSR fallback explicit.
 10. Local sync uses Web Lock leadership and contiguous durable sequence. Writes precede
     asynchronous persistence. Version 5 / format 3 rejects old databases without editing
     them. External replace and remote apply are prohibited while attached.

package/skills/doxum-runtime/references/projections.md

@@ -459,6 +459,28 @@ Rules:
 - the same definition cannot belong to two scopes;
 - `scope.items` has the same membership/readable semantics as `runtime.items` and ends with scope disposal.
 
+`scope.onDispose(cleanup)` and `runtime.onDispose(cleanup)` register synchronous LIFO
+callbacks; the returned function cancels that one registration without executing it.
+Runtime shutdown runs scope callbacks in reverse creation order, then root callbacks,
+while the graph remains readable. All callbacks finish before teardown. Scope-only
+disposal leaves root materialization alive. Read/Readable.current retain normal demand,
+lazy initialization, ownership and fault semantics during cleanup; commands, new
+subscriptions/resources and cleanup registrations are rejected. Connected document
+writes are locked. Cleanup does not flush projection notifications. Business writes
+belong before disposal. Existing source unsubscribe/processor release are teardown,
+not read-capable cleanup callbacks.
+
+All callbacks/releases are attempted even on failure; errors escape after terminal
+closure. `dispose` can be called repeatedly, after an earlier cleanup failure, or on a
+scope already ended by its parent. Unsubscribe and cleanup-registration cancellation
+are idempotent. Each subscription owns a distinct registration even if callbacks are
+identical; old unsubscribe functions cannot detach a newer registration. Normal reads,
+commands, resource creation and existing Readable access still throw after disposal.
+
+For React, use the managed `ProjectionProvider runtime={runtime}`; acquire the current
+scope with `useProjectionScope()`. Read [React ownership and SSR](integrations.md#projection-provider)
+before choosing managed versus externally owned Provider mode.
+
 ## Batching
 
 ```ts

package/skills/doxum-runtime/references/public-api.md

@@ -420,6 +420,7 @@ type ProjectionRuntime = {
   update<K,V,R>(input: CollectionInput<K,V>, run: (draft: CollectionInputDraft<K,V>) => Synchronous<R>): void;
   batch<T>(run: () => Synchronous<T>, options?: { cause?: unknown }): T;
   scope(): ProjectionScope;
+  onDispose<R>(cleanup: () => Synchronous<R>): Unsubscribe;
   dispose(): void;
 };
 
@@ -600,25 +601,36 @@ incremental.group(
 
 Every declared output must be returned from the static output tree exactly once.
 
+Runtime/scope `onDispose` registers synchronous, cancellable LIFO cleanup. Child scope
+callbacks precede parent Runtime callbacks; projections remain readable until all
+callbacks finish. Cleanup rejects commands/new registrations. Failures do not interrupt
+remaining teardown and are thrown only after closure. `dispose` and unsubscribe are
+idempotent; all normal projection access still throws after disposal. See
+[cleanup and scope ownership](projections.md#projectionscope).
+
 ## `doxum/react`
 
 ### Public symbol inventory
 
 <!-- exports:doxum/react:start -->
 
-| Public export         | Role                                               |
-| --------------------- | -------------------------------------------------- |
-| `ProjectionProvider`  | Provide a `ProjectionRuntime` or `ProjectionScope` |
-| `useDocumentSelector` | React adapter for Core document `select`           |
-| `useReadable`         | Subscribe to any Doxum `Readable`                  |
-| `useHistory`          | Read history state and expose undo/redo callbacks  |
-| `useProjection`       | Read projection or projection selector             |
-| `useInput`            | Read/update scalar or collection projection input  |
+| Public export             | Role                                                      |
+| ------------------------- | --------------------------------------------------------- |
+| `ProjectionProvider`      | Manage a scope from a Runtime or borrow an external owner |
+| `ProjectionProviderProps` | Mutually exclusive managed/borrowed Provider props        |
+| `useProjectionScope`      | Read the current scope from context; never allocate one   |
+| `useDocumentSelector`     | React adapter for Core document `select`                  |
+| `useReadable`             | Subscribe to any Doxum `Readable`                         |
+| `useHistory`              | Read history state and expose undo/redo callbacks         |
+| `useProjection`           | Read projection or projection selector                    |
+| `useInput`                | Read/update scalar or collection projection input         |
 
 <!-- exports:doxum/react:end -->
 
 ```ts
+<ProjectionProvider runtime={runtime} fallback={null}>...</ProjectionProvider>
 <ProjectionProvider value={runtimeOrScope}>...</ProjectionProvider>
+useProjectionScope(): ProjectionScope
 
 useProjection(projection): T
 useProjection(projection, selector, equality?): R
@@ -629,6 +641,13 @@ useReadable(readable): T
 useHistory(history): HistoryState & { undo(): OperationResult<C>; redo(): OperationResult<C> }
 ```
 
+Managed `runtime` mode owns only a child scope, acquired after commit. Initial render
+and SSR use `fallback` (default `null`); StrictMode setup replay and runtime replacement
+create a fresh scope generation and remount its subtree. Borrowed `value` mode injects
+synchronously and never disposes the supplied owner. Use it for synchronous SSR with
+request-owned resources. `useProjectionScope()` requires a scope in context, including
+an explicitly injected scope; an injected root Runtime does not implicitly create one.
+
 ## `doxum/local-sync`
 
 ### Public symbol inventory