doxum 0.1.40 → 0.1.42

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

@@ -61,6 +61,29 @@ This file is maintainer-only. Application/library consumers should use [Public A
    initialization failure releases already-created projection resources and preserves the
    original error. Document dirty/pending state has one write owner; structural
    materialization only reads it.
+   Collection storage installs an accepted entry batch through one persistent index
+   application. The index owns AVL batch merge/balance; storage owns the current Map
+   and formal ids; output sealing owns equality and publication. Share untouched
+   subtrees and copy the affected path union once for pure value updates. Batch
+   structural changes require height-aware join/concat, not just single-edit repair.
+   Preserve lazy index creation, durable old snapshots, zero index work for pure
+   reorder, and per-install versions for demanded reads inside a Runtime batch.
+   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