@zakkster/lite-project 1.1.1 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,200 @@
 All notable changes to `@zakkster/lite-project` are documented here. The format
 follows Keep a Changelog; this project adheres to semantic versioning.
 
+## [1.4.0] - 2026-09-05
+
+### Added
+
+- **`projectCRDT(map, opts?)`** -- a draft-overlay adapter for a
+  `@zakkster/lite-crdt` LWW-Map (`doc.map(name)`). Unlike `projectRoom` (which
+  wraps lite-room's **coarse** storage -- one `entries` signal, any change re-runs
+  every projected key), an LWW-Map has **fine-grained** reactive `get(key)`, so
+  `projectCRDT` is truly granular: overlaying or committing one cell never re-runs
+  a consumer of another. `set(key, value)` stages a local draft (the CRDT is
+  untouched); `commit(key?)` promotes drafts via `map.set` (one op per committed
+  key -- LWW ops are commutative + idempotent, so N frames are semantically one);
+  an auto-reconcile drops drafts the authoritative cell catches up to (a local
+  echo or a remote `applyOp`) while leaving conflicts -- and a concurrent
+  authoritative **delete** (reads as `undefined`) -- masked. The reconcile trigger
+  is ONE effect that reads `dirtyCount()` (tracked -- re-derives the dependency set
+  on every overlay-set transition) plus `map.get(k)` for each currently-overlaid
+  key, then calls `reconcileAll(policy)`; it re-runs only on overlay-set
+  transitions and on authoritative changes to overlaid keys. The map is consumed
+  **structurally** (any `{ get, set }` with a fine-grained reactive `get`), so
+  there is no hard dependency on lite-crdt, and the adapter never touches the doc,
+  `map.store`, or the coarse reads (`keys`/`values`/`entries`/`size`).
+- **`opts.transact`** -- an optional hook (e.g. `doc.transact`) that wraps both
+  `commit` and `commitWhere` so an N-key burst coalesces into ONE ops frame + one
+  change (measured: staging 3 keys emits 0 ops; committing emits 3 ops / 3 frames
+  with no `transact`, 3 ops / **1** frame under `transact`). The branch is resolved
+  once at construction; a supplied-but-non-function `transact` throws before any
+  node is created. `LWWMapLike`, `ProjectCRDTOptions`, and the `projectCRDT`
+  declaration added to `Project.d.ts`; `decisions/0003-project-crdt.md` records the
+  design.
+
+### Notes (recorded contracts, not bugs)
+
+- **Read-only object wrapper.** lite-crdt's `get(key)` returns a deep **read-only
+  wrapper** for object/array values (a different reference than the one passed to
+  `set`, WeakMap-cached and stable across reads). So `confirmOnEcho` (`Object.is`)
+  can **never** auto-confirm an object-valued draft over `projectCRDT`, even on a
+  genuine local echo -- use a `{ ttl }` draft (the shipped self-heal) or a
+  caller-supplied **structural** policy (whose reads pass through the wrapper
+  transparently). A policy must never attempt to mutate the authoritative value it
+  is handed for an object -- it is that read-only wrapper and lite-crdt throws
+  `readonly`. Scalars confirm normally.
+- **String-coercion key aliasing.** lite-crdt coerces every map key to a string,
+  but projection slots are keyed by `PropertyKey`. Drafts on `5` and `"5"` are TWO
+  projection slots that commit into ONE CRDT cell (last write wins), and
+  `dirtyCount()` never reveals the collision -- stage under one key type. A
+  `"__proto__"` map key is not usable in lite-crdt (`map.set` throws
+  `CRDTError("misconfigured")`); the adapter does not wrap that policy -- a commit
+  of a `"__proto__"` draft propagates the CRDT's own error with the draft still
+  staged and `dirtyCount()` consistent (fail closed).
+- **Dispose order.** `doc.dispose()` makes subsequent mutations silent no-ops, so a
+  commit **after** the doc is disposed writes nothing yet still clears the drafts
+  (an inherited dead-source data-loss class). Dispose the projection **before** the
+  doc.
+
+### Tests
+
+- `test/crdt_test.mjs` (19 tests, real `@zakkster/lite-crdt` on the default
+  registry): op-counter (stage/commit/transact frames), the wrapper pin (object
+  draft after a genuine echo stays overlaid; a structural policy drops it), TTL
+  heal over `projectCRDT`, numeric/symbol key-alias pins, `"__proto__"` commit
+  fail-closed, granularity (a consumer of `get("b")` runs once across 10 commits to
+  `"a"`; the reconcile effect does not fire on non-overlaid-key writes), missing-key
+  draft (`from === undefined`; a remote `applyOp` re-runs the projected read),
+  authoritative-delete conflict, dispose ordering, and the post-`doc.dispose()`
+  commit hazard.
+- Torture: `makeFakeMap` (a registry-parametric structural fake LWW-Map) drives new
+  `T4` (echo/conflict/late-overlay per key), `T5` (`projectCRDT` fuzz oracle + the
+  granularity law), `T6` (a warm echo-drop reconcile pass -- retains 0 B/call),
+  and `T9` controls `(j)` (a coarse-read effect fails the granularity law) and
+  `(k)` (a peek-only stale-deps effect misses a late-overlay echo). GATE unchanged:
+  `leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 | retained=0.00 B/op growths=0`.
+
+## [1.3.0] - 2026-09-05
+
+### Added
+
+- **Overlay TTL -- `set(key, value, { ttl })`.** Stage an overlay that
+  auto-**reverts** at `now() + ttl` (a finite number > 0, in the clock's units):
+  the draft is dropped and the source is **never** touched -- "the optimistic edit
+  expired; fall back to authoritative". One re-armed platform timer per projection
+  (each slot stores its own deadline; arm/fire do an `O(slots)` cold scan -- no
+  side `Map`, no per-`set` allocation on the warm path). A bad `ttl`
+  (`0`, `-1`, `NaN`, `Infinity`, `"5"`, `null`, ...) throws **before** staging. A
+  re-set **with** `ttl` re-arms (an earlier deadline re-arms eagerly; a later one
+  lets the armed timer fire spuriously and re-arm); a re-set **without** `ttl`
+  cancels the pending expiry -- each `set` fully specifies its overlay's lifetime.
+  Every transition to un-overlaid (`clear`, `commit(key)`, `commit()`, `revert`,
+  a `reconcileAll` drop, `commitWhere`, `clearWhere`, and the fire itself) cancels
+  that key's expiry, and `dispose()` cancels any pending handle.
+- **Injectable clock -- `project(source, { now, setTimer, clearTimer })`.**
+  All-or-none: supply all three (each a function) or none. A **mixed** clock is a
+  `TypeError` (it would compute deadlines on one timeline and arm on another --
+  fail closed). Defaults wrap `performance.now` / `setTimeout` / `clearTimeout`.
+  Forwarded by `projectStore(store, opts?)`, `projectRoom(room, opts?)`, and
+  `projectQuery(qc, key, opts?)` (the flat bag; `project` reads only the clock
+  keys). `SetOptions`, `ProjectionClock`, and `ProjectOptions` added to
+  `Project.d.ts`.
+- **`Projection.commitWhere(pred)` / `Projection.clearWhere(pred)`** -- predicate-
+  scoped partial save / discard. `pred(key, stagedValue)` (the `forEachOverlay`
+  callback order, not `ReconcilePolicy`'s), visited in slots order, one reactive
+  propagation each. `commitWhere` writes and clears only the matching overlays;
+  `clearWhere` drops them with **zero** source writes. A throwing `pred` is
+  non-atomic on the core handle (already-committed keys stay committed and
+  `dirtyCount() === overlaidCount()`). `projectQuery` **overrides** `commitWhere`
+  to keep the single-write law: one `setQueryData(key, prev => merge(prev,
+  overlays))` for the matching fields, then the committed fields are cleared
+  per-key -- the non-matching drafts survive (it does **not** reuse the `commit()`
+  override's `revert()`, which would drop them too).
+
+  **F-03 recorded.** `confirmOnEcho` is reference-equality (`Object.is`), so an
+  object-valued draft can never echo-confirm against a structurally-equal source
+  value of a different reference. The fix is a **caller-supplied** structural
+  policy (`reconcileAll(policy)` and the `forEachPatch` skip param accept one);
+  this library ships **no** deep-equal helper (a naive structural equal is a
+  fail-open trap). The TTL is the shipped safety net: a stuck object draft
+  self-heals on its deadline. Recorded in `decisions/0002-overlay-ttl.md`
+  (dev-only; not shipped).
+
+### Verified
+
+- 30 new `test/ttl_test.mjs` cases (fire at / not-before the deadline, byte-
+  identical source after a fire, re-arm + one-handle, plain re-set cancels,
+  `null` / `{}` / `{policy}` bags behave as plain `set` and still cancel,
+  cancellation at every ABSENT-transition site, the F-03 self-heal, the ttl +
+  mixed-clock + non-object-`project`-opts `TypeError`s, `commitWhere` /
+  `clearWhere` exact match + one
+  propagation + throwing-pred consistency, a set-with-ttl honoured inside a fire
+  subscriber, post-dispose inertness, and the four adapters incl. the
+  `projectQuery` single-write `commitWhere`); **114 tests total**, `node --test`.
+- Torture green (default seed):
+  `leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 |
+  alloc=n/a retained=0.00 B/op growths=0` (the binding channels are `major=0`,
+  `retained=0.00`, `growths=0`; the `alloc=` per-op bracket prints as-is, `n/a`
+  when the profiler's heap window was inconclusive). T4 gains the TTL door
+  (deterministic fake clock: expire / not-before / re-arm / cancel + the F-03
+  object heal). T6 gains Proof 5 -- warm ttl re-set + `commitWhere` + `clearWhere`
+  under an injected no-op clock retain `0 B/call` at `maxBytesPerCall 0` (the warm
+  no-ttl triangle passes the P0 gates unchanged). T7 gains a 1000-TTL sub-soak:
+  `maxOutstanding() === 1` at every instant, `0` after the drain fire and after
+  `dispose()`, tracker back to `size()===0`. T9 gains controls (h) a default-clock
+  projection tripping the deterministic expiry assertion, and (i) a leaky per-key
+  timer tripping the one-handle bound.
+
+## [1.2.0] - 2026-09-05
+
+### Added
+
+- **`Projection.forEachPatch(fn, skip?)`** -- emit the staged drafts as a
+  `(key, from, to)` stream, where `from` is the **untracked** current source
+  value and `to` the staged overlay. Read-only and untracked: it touches neither
+  the source nor the overlays and subscribes the caller to nothing, so it is safe
+  inside an effect. Visits exactly the overlaid keys, in `forEachOverlay` order,
+  with a **zero-allocation** per-key body (the source read is hoisted through one
+  closure per projection, never one per key). The optional `skip` reuses the
+  `ReconcilePolicy` shape `(from, to, key) => boolean` -- pass `confirmOnEcho` to
+  drop unchanged drafts. A throwing `source.get` propagates on the offending key
+  with the overlay bag intact (no writes happen anywhere in the call).
+- **`Projection.toPatch(skip?)`** -- the cold convenience that materializes the
+  same stream as `[{ key, from, to }, ...]` (same visit set, order, and values).
+  The per-key record is this form's documented allocation; reach for
+  `forEachPatch` when you need the zero-alloc callback. Both methods are present
+  on the `projectStore` / `projectRoom` / `projectQuery` handles (for
+  `projectQuery`, `from` is the cached record's field value; for `projectRoom`,
+  `room.storage.get`).
+- **`Patch<K, V>`** interface (`{ key, from, to }`) exported from `Project.d.ts`.
+
+  **The decision -- unchanged drafts are emitted by default.** An overlaid key is
+  emitted whether or not `Object.is(from, to)`. This keeps the visit set
+  definitionally equal to `forEachOverlay`, `dirtyCount()`, and `commit()`'s write
+  set, so `toPatch().length === dirtyCount()` always holds; a patch consumer is a
+  protocol (an LWW-Map op, a CRDT timestamp bump, an HTTP PATCH field), not a diff
+  viewer, so dropping an unchanged key would be silent data loss one layer out.
+  Callers who want the filter pass `forEachPatch(fn, confirmOnEcho)`. Recorded in
+  `decisions/0001-patch-emission.md` (dev-only; not shipped).
+
+### Verified
+
+- 17 new `test/patch_test.mjs` cases (visit-set exactness + order, from/to vs
+  source and overlay, `toPatch()` == the callback stream, the emit-by-default and
+  echo-skip pins, the tracking contract, `__proto__` / symbol / numeric keys,
+  `undefined` / `NaN` / `-0` under `Object.is`, fail-closed on a throwing
+  `source.get`, patch-apply == commit, and all four adapter handles); **84 tests
+  total**, `node --test`.
+- Torture green (default seed):
+  `leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 |
+  alloc=n/a retained=0.00 B/op growths=0`. T5 gains the metamorphic law (the
+  emitted patch applied to a fresh source copy == `commit()` into it, across the
+  fuzz corpus incl. object drafts). T6 gains Proof 4 -- `forEachPatch` over a
+  warm overlaid set passes both the heap gate (`maxMajor 0`, `maxPauseMs 4`,
+  `maxArrayBuffersGrowth 0`) and the zero-retention gate (`maxBytesPerCall 0`).
+  T9 gains control (g): a per-visit-allocating emitter body demonstrably trips the
+  retained-alloc gate through the same helper.
+
 ## [1.1.1] - 2026-09-03
 
 ### Added

package/Project.d.ts

@@ -1,4 +1,4 @@
-// Type declarations for @zakkster/lite-project v1.1.1
+// Type declarations for @zakkster/lite-project v1.4.0
 // Zero-GC projections for @zakkster/lite-signal.
 // (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com> -- MIT
 
@@ -25,6 +25,41 @@ export interface ProjectionSource<K extends PropertyKey = PropertyKey, V = unkno
 export type ReconcilePolicy<K extends PropertyKey = PropertyKey, V = unknown> =
     (authoritative: V, overlayValue: V, key: K) => boolean;
 
+/**
+ * Options for a single {@link Projection.set}. `ttl` (a finite number > 0, in the
+ * clock's units) auto-REVERTS the staged overlay at `now() + ttl` -- the source is
+ * never touched. A bad `ttl` throws before staging; a re-set without `ttl` cancels
+ * a prior expiry (each set fully specifies its overlay's lifetime).
+ */
+export interface SetOptions {
+    ttl?: number;
+}
+
+/**
+ * An injectable clock for overlay TTL. `now()` returns a monotonic number,
+ * `setTimer(fn, ms)` schedules `fn` after `ms` and returns a handle, and
+ * `clearTimer(handle)` cancels it. All-or-none: supply all three or none.
+ */
+export interface ProjectionClock {
+    now(): number;
+    setTimer(fn: () => void, ms: number): unknown;
+    clearTimer(handle: unknown): void;
+}
+
+/** Options for {@link project} / {@link Projector.project}: an optional injectable clock. */
+export interface ProjectOptions extends Partial<ProjectionClock> {}
+
+/**
+ * One staged draft as a patch entry: the current source value (`from`) and the
+ * staged overlay value (`to`) for `key`. The materialized shape returned by
+ * {@link Projection.toPatch}.
+ */
+export interface Patch<K extends PropertyKey = PropertyKey, V = unknown> {
+    key: K;
+    from: V;
+    to: V;
+}
+
 /**
  * A projection handle: a granular, derived, non-mutating draft overlay over a
  * keyed source. Each touched key owns one overlay signal + one projected
@@ -33,8 +68,12 @@ export type ReconcilePolicy<K extends PropertyKey = PropertyKey, V = unknown> =
 export interface Projection<K extends PropertyKey = PropertyKey, V = unknown> {
     /** Reactive: the overlay value if one is staged for `key`, else the source value. */
     get(key: K): V;
-    /** Stage an EPHEMERAL overlay for `key`. The source is NOT mutated. */
-    set(key: K, value: V): void;
+    /**
+     * Stage an EPHEMERAL overlay for `key`. The source is NOT mutated. Pass
+     * `{ ttl }` to auto-revert the overlay at `now() + ttl`; a re-set without
+     * `ttl` cancels a pending expiry.
+     */
+    set(key: K, value: V, opts?: SetOptions): void;
     /** Drop one key's overlay (revert that key to the source). */
     clear(key: K): void;
     /** Untracked diagnostic: is `key` currently overlaid? */
@@ -53,6 +92,26 @@ export interface Projection<K extends PropertyKey = PropertyKey, V = unknown> {
     peek(key: K): V;
     /** Iterate currently-overlaid keys with their overlay values (untracked). */
     forEachOverlay(fn: (key: K, value: V) => void): void;
+    /**
+     * Emit the staged drafts as a patch stream `fn(key, from, to)` -- `from` is
+     * the UNTRACKED current source value, `to` the staged overlay. Read-only and
+     * untracked: it touches neither the source nor the overlays and subscribes the
+     * caller to nothing, so it is safe inside an effect. Visits exactly the
+     * overlaid keys, in {@link Projection.forEachOverlay} order, with a zero-alloc
+     * per-key body. An overlaid key is emitted whether or not `Object.is(from, to)`
+     * (the visit set stays equal to `dirtyCount()`); pass `skip` -- the same
+     * predicate shape reconcile uses, e.g. {@link confirmOnEcho} -- to drop
+     * unchanged drafts. A throwing `source.get` propagates on that key with the
+     * overlay bag intact (callers needing atomicity use {@link Projection.toPatch}).
+     */
+    forEachPatch(fn: (key: K, from: V, to: V) => void, skip?: ReconcilePolicy<K, V>): void;
+    /**
+     * Cold convenience over {@link Projection.forEachPatch}: materialize the drafts
+     * as `[{ key, from, to }, ...]` -- same visit set, order, and values. The
+     * per-key record is this form's allocation; reach for `forEachPatch` when you
+     * need the zero-alloc callback.
+     */
+    toPatch(skip?: ReconcilePolicy<K, V>): Array<Patch<K, V>>;
     /**
      * Full-snapshot reconciliation: drop every overlay the policy considers
      * confirmed against the current (untracked) source value. Presentation-only --
@@ -61,6 +120,18 @@ export interface Projection<K extends PropertyKey = PropertyKey, V = unknown> {
     reconcileAll(policy?: ReconcilePolicy<K, V>): void;
     /** Write staged overlays into the source, then clear them. With `key`, commits just that key. */
     commit(key?: K): void;
+    /**
+     * Predicate-scoped partial commit: write and clear only the overlaid keys for
+     * which `pred(key, stagedValue)` returns true (the {@link Projection.forEachOverlay}
+     * callback order), in one propagation. A throwing `pred` propagates with the
+     * already-committed keys committed and `dirtyCount() === overlaidCount()`.
+     */
+    commitWhere(pred: (key: K, value: V) => boolean): void;
+    /**
+     * Predicate-scoped partial discard: drop only the overlaid keys for which
+     * `pred(key, stagedValue)` returns true. The source is never touched.
+     */
+    clearWhere(pred: (key: K, value: V) => boolean): void;
     /** Drop all overlays. */
     revert(): void;
     /**
@@ -129,6 +200,7 @@ export interface ProjectorRegistry {
 export interface Projector {
     project<K extends PropertyKey = PropertyKey, V = unknown>(
         source: ProjectionSource<K, V>,
+        opts?: ProjectOptions,
     ): Projection<K, V>;
     keyedStore<K extends PropertyKey = PropertyKey, V = unknown>(
         initial?: Record<PropertyKey, V>,
@@ -141,6 +213,7 @@ export function createProjector(reg: ProjectorRegistry): Projector;
 /** Project a keyed source (default registry). */
 export function project<K extends PropertyKey = PropertyKey, V = unknown>(
     source: ProjectionSource<K, V>,
+    opts?: ProjectOptions,
 ): Projection<K, V>;
 
 /** Minimal built-in keyed reactive source (default registry). */
@@ -188,6 +261,7 @@ export function makeReconciler<K extends PropertyKey = PropertyKey, V = unknown>
  */
 export function projectStore<V = unknown>(
     store: Record<PropertyKey, V>,
+    opts?: ProjectOptions,
 ): Projection<PropertyKey, V>;
 
 /** The subset of a @zakkster/lite-room handle that {@link projectRoom} consumes. */
@@ -200,8 +274,8 @@ export interface RoomLike {
     };
 }
 
-/** Options for {@link projectRoom}. */
-export interface ProjectRoomOptions {
+/** Options for {@link projectRoom}. Extends the injectable clock for overlay TTL. */
+export interface ProjectRoomOptions extends Partial<ProjectionClock> {
     /** Reconciliation policy; defaults to {@link confirmOnEcho}. */
     policy?: ReconcilePolicy<string, unknown>;
 }
@@ -226,8 +300,9 @@ export interface QueryClientLike {
     setQueryData(key: unknown, valueOrUpdater: unknown | ((prev: unknown) => unknown)): unknown;
 }
 
-/** Options for {@link projectQuery}. */
-export interface ProjectQueryOptions<V extends object = Record<PropertyKey, unknown>> {
+/** Options for {@link projectQuery}. Extends the injectable clock for overlay TTL. */
+export interface ProjectQueryOptions<V extends object = Record<PropertyKey, unknown>>
+    extends Partial<ProjectionClock> {
     /**
      * The query's reactive data accessor (e.g. `query.data`). When supplied,
      * projected reads track the cache and auto-reconcile is armed. Omit to degrade
@@ -256,3 +331,53 @@ export function projectQuery<V extends object = Record<PropertyKey, unknown>>(
     key: unknown,
     opts?: ProjectQueryOptions<V>,
 ): Projection<keyof V, unknown>;
+
+/**
+ * The subset of a @zakkster/lite-crdt LWW-Map (`doc.map(name)`) that
+ * {@link projectCRDT} consumes. `get(key)` must be a FINE-GRAINED reactive read
+ * (re-runs only when that key's cell changes); `set(key, value)` emits a CRDT op.
+ * Keys are string-coerced by lite-crdt.
+ */
+export interface LWWMapLike {
+    /** Fine-grained reactive read: tracks the cell backing `key`. */
+    get(key: string): unknown;
+    /** Write the cell for `key` (emits a CRDT op). */
+    set(key: string, value: unknown): void;
+    /** Optional authoritative delete (emits a tombstone op). */
+    delete?(key: string): void;
+}
+
+/** Options for {@link projectCRDT}. Extends the injectable clock for overlay TTL. */
+export interface ProjectCRDTOptions extends Partial<ProjectionClock> {
+    /** Reconciliation policy for auto-reconcile; defaults to {@link confirmOnEcho}. */
+    policy?: ReconcilePolicy<string, unknown>;
+    /**
+     * Optional transact hook (e.g. `doc.transact`) that wraps `commit` and
+     * `commitWhere` so an N-key burst coalesces into ONE ops frame + one change.
+     * A supplied-but-non-function value throws before any node is created.
+     */
+    transact?: <T>(fn: () => T) => T;
+}
+
+/**
+ * Project a @zakkster/lite-crdt LWW-Map (`doc.map(name)`) as a per-key DRAFT
+ * overlay. Inherits the map's fine-grained granularity, so overlaying or
+ * committing one cell never re-runs a consumer of another. `set` stages a local
+ * draft, `commit(key?)` promotes drafts via `map.set` (one op per key; pass
+ * `opts.transact` to coalesce a burst into one frame), and an auto-reconcile drops
+ * drafts the authoritative cell catches up to while leaving conflicts (and
+ * concurrent authoritative deletes) masked.
+ *
+ * TWO recorded hazards: (1) lite-crdt's `get` returns a deep READ-ONLY WRAPPER for
+ * object values, so `confirmOnEcho` (Object.is) never auto-confirms an object
+ * draft -- use a `{ ttl }` draft or a structural policy, and never mutate the
+ * authoritative value a policy is handed. (2) Keys are string-coerced, so drafts
+ * on `5` and `"5"` are two slots committing into one cell (last write wins).
+ * Consumed structurally (no hard dependency on lite-crdt) and never touches the
+ * doc or `map.store`. Dispose the projection BEFORE the doc. The returned handle's
+ * `dispose()` also stops the reconcile effect.
+ */
+export function projectCRDT(
+    map: LWWMapLike,
+    opts?: ProjectCRDTOptions,
+): Projection<string, unknown>;

package/Project.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-project v1.1.1 -- zero-GC projections for @zakkster/lite-signal.
+ * @zakkster/lite-project v1.4.0 -- zero-GC projections for @zakkster/lite-signal.
  * -----------------------------------------------------------------------------
  * A projection is a granular, derived, NON-MUTATING reactive view over a keyed
  * source: a lens that can carry ephemeral overlays (optimistic edits, merges,
@@ -21,6 +21,27 @@
  *                circuit -- does NOT churn downstream consumers. The optimistic value
  *                is stable under source noise.
  *
+ * Patch emission (forEachPatch / toPatch) exposes the staged drafts as a
+ * (key, from, to) stream for a save/sync trigger. It is READ-ONLY and UNTRACKED:
+ * it never touches the source or the overlays and subscribes the caller to nothing.
+ *
+ * -- OVERLAY TTL + PARTIAL COMMIT (1.3) --
+ * set(key, v, {ttl}) stages an overlay that auto-REVERTS at now()+ttl (drop the
+ * overlay, source untouched -- "the optimistic edit expired, fall back to
+ * authoritative"). ONE re-armed platform timer per projection; each slot stores its
+ * own deadline; every transition to ABSENT cancels that key's expiry. The clock is
+ * injectable and all-or-none via project(source, {now, setTimer, clearTimer}) --
+ * a mixed clock is a TypeError. commitWhere(pred) / clearWhere(pred) apply a
+ * predicate-scoped partial save / discard: pred(key, stagedValue), the
+ * forEachOverlay callback order.
+ *
+ * -- F-03 (recorded) -- confirmOnEcho is reference-equality (Object.is): an
+ * object-valued draft can never echo-confirm against a structurally-equal source
+ * value of a different reference. The fix is a CALLER-supplied structural policy
+ * (reconcileAll(policy) / the forEachPatch skip param accept one); this library
+ * ships NO deep-equal helper (a naive structural equal is a fail-open trap). The
+ * TTL is the shipped safety net: a stuck object draft self-heals on its deadline.
+ *
  * -- OWNERSHIP (why createRoot) --
  * Per-key nodes are created LAZILY, on the first get/set of a key -- which happens
  * inside whatever consumer effect first reads that key. Without detachment the
@@ -41,6 +62,15 @@
  *       are the public-handle cost, the same split @zakkster/lite-signal itself draws
  *       between pooled internals and escaping handles. Warm the keys you will churn.
  *
+ * -- ADAPTERS -- projectStore / projectRoom / projectQuery / projectCRDT [1.4].
+ * projectCRDT wraps a @zakkster/lite-crdt LWW-Map's FINE-GRAINED reactive get(key)
+ * for true per-key drafts. TWO recorded hazards: (1) get(key) returns a deep
+ * READ-ONLY WRAPPER for object values, so confirmOnEcho (Object.is) can never
+ * auto-confirm an object draft (use {ttl} or a structural policy; never mutate the
+ * authoritative wrapper); (2) lite-crdt STRING-COERCES keys, so drafts on `5` and
+ * `"5"` are two slots that commit into one cell (last write wins) -- stage under
+ * one key type. See the projectCRDT JSDoc for the full contract.
+ *
  * Registry-parametric: createProjector(reg) binds to any registry (the default one,
  * or a createRegistry({...}) for isolated tests). Default-bound `project` /
  * `keyedStore` are exported for the common case.
@@ -59,7 +89,7 @@ import {
     hasObservers as _hasObservers,
 } from "@zakkster/lite-signal";
 
-export const VERSION = "1.1.1";
+export const VERSION = "1.4.0";
 
 // Module-level sentinel for "this key has no overlay". A unique symbol, never a
 // per-operation allocation. Stored directly in the overlay signal's value slot, so
@@ -119,9 +149,12 @@ export function createProjector(reg) {
      * and can commit / revert it.
      *
      * @param {{get:(key:PropertyKey)=>unknown, set:(key:PropertyKey, v:unknown)=>void}} source
+     * @param {{now?:Function, setTimer?:Function, clearTimer?:Function}} [opts] Optional
+     *        injectable clock for overlay TTL (all-or-none: if any is supplied, all three
+     *        must be functions). Defaults wrap performance.now / setTimeout / clearTimeout.
      * @returns {{
      *   get:(key:PropertyKey)=>unknown,         // reactive: overlay value if set, else source
-     *   set:(key:PropertyKey, v:unknown)=>void,  // stage an EPHEMERAL overlay (source untouched)
+     *   set:(key:PropertyKey, v:unknown, opts?:{ttl?:number})=>void, // stage an EPHEMERAL overlay; {ttl} auto-reverts it (source untouched)
      *   clear:(key:PropertyKey)=>void,           // drop one key's overlay (revert that key)
      *   isOverlaid:(key:PropertyKey)=>boolean,   // untracked diagnostic
      *   overlaidCount:()=>number,                // untracked diagnostic
@@ -129,15 +162,43 @@ export function createProjector(reg) {
      *   isDirty:()=>boolean,                     // TRACKED: any staged overlays? (reactive)
      *   peek:(key:PropertyKey)=>unknown,         // untracked effective read (no subscribe)
      *   forEachOverlay:(fn:(key:PropertyKey, value:unknown)=>void)=>void, // iterate overlaid keys (untracked)
+     *   forEachPatch:(fn:(key:PropertyKey, from:unknown, to:unknown)=>void, skip?:Function)=>void, // patch stream (untracked, read-only)
+     *   toPatch:(skip?:Function)=>Array<{key:PropertyKey, from:unknown, to:unknown}>, // materialized patch (cold convenience)
      *   reconcileAll:(policy?:(authoritative:unknown, overlayValue:unknown, key:PropertyKey)=>boolean)=>void, // drop confirmed overlays
      *   commit:(key?:PropertyKey)=>void,         // write one key's overlay, or all, into the source then clear
+     *   commitWhere:(pred:(key:PropertyKey, value:unknown)=>boolean)=>void, // write + clear only the matching overlays
+     *   clearWhere:(pred:(key:PropertyKey, value:unknown)=>boolean)=>void,  // drop only the matching overlays (source untouched)
      *   revert:()=>void,                         // drop all overlays
      *   dispose:()=>void,                        // recycle every projection-owned node to the pool
      * }}
      */
-    function project(source) {
-        // key -> { ov: overlay signal (ABSENT | value), read: projected computed }.
-        // Lazily populated. One entry per touched key, retained until dispose().
+    function project(source, opts) {
+        // Injectable, all-or-none clock (S1). now/setTimer/clearTimer let the TTL
+        // run on a deterministic timeline in tests. A MIXED clock computes
+        // deadlines on one timeline and arms on another -> fail closed. Defaults
+        // wrap the platform globals in arrows: bare `setTimeout` refs throw
+        // "Illegal invocation" in browsers, and performance.now is monotonic so an
+        // NTP step cannot make a deadline unreachable (setTimer takes a delta).
+        if (opts != null && typeof opts !== "object") {
+            throw new TypeError("project: opts must be an object");
+        }
+        let _now, _setTimer, _clearTimer;
+        if (opts != null && (opts.now !== undefined || opts.setTimer !== undefined || opts.clearTimer !== undefined)) {
+            if (typeof opts.now !== "function" || typeof opts.setTimer !== "function" || typeof opts.clearTimer !== "function") {
+                throw new TypeError("project: now/setTimer/clearTimer must all be functions (all-or-none clock)");
+            }
+            _now = opts.now; _setTimer = opts.setTimer; _clearTimer = opts.clearTimer;
+        } else {
+            _now = () => performance.now();
+            _setTimer = (fn, ms) => setTimeout(fn, ms);
+            _clearTimer = (h) => clearTimeout(h);
+        }
+
+        // key -> { ov: overlay signal (ABSENT | value), read: projected computed,
+        // exp: deadline (0 == no expiry) }. Lazily populated. One entry per touched
+        // key, retained until dispose(). `exp` is a THIRD field at birth so the
+        // hidden class is stable; a ttl set is one field write, never a side Map.
+        // Invariant: exp !== 0 implies overlaid, so prune() never orphans a deadline.
         const slots = new Map();
 
         const slotFor = (key) => {
@@ -153,7 +214,7 @@ export function createProjector(reg) {
                         const base = source.get(key); // track the source cell too
                         return o === ABSENT ? base : o;
                     });
-                    return { ov, read };
+                    return { ov, read, exp: 0 };
                 });
                 slots.set(key, s);
             }
@@ -169,19 +230,134 @@ export function createProjector(reg) {
         const dirtySig = createRoot(() => signal(0));
         let dirty = 0;
 
+        // -- Overlay TTL (per-projection). ONE platform timer, re-armed; each slot
+        // stores its own deadline in `exp`, and arm/fire do an O(slots) cold scan.
+        // A min-heap would allocate per push -- rejected. `armedAt` is the deadline
+        // the live handle is set for; clear-before-set in _armAt bounds outstanding
+        // handles to exactly 1 (T7). ttlCount is the count of slots with exp !== 0.
+        let timerHandle = null; let armedAt = 0; let ttlCount = 0;
+        const _cancelTimer = () => {
+            if (timerHandle !== null) { _clearTimer(timerHandle); timerHandle = null; armedAt = 0; }
+        };
+        const _armAt = (d) => {
+            if (timerHandle !== null) _clearTimer(timerHandle);   // clear-before-set: <= 1 handle
+            armedAt = d;
+            const ms = d - _now();
+            timerHandle = _setTimer(_fire, ms > 0 ? ms : 0);      // clamp delta >= 0
+        };
+        // THE single cancellation helper: every transition to ABSENT calls it, so a
+        // stale deadline can never outlive its overlay. A hoisted function
+        // declaration (not an arrow) so it is defined before the closures above
+        // that reference it.
+        function _dropExp(s) {
+            if (s.exp !== 0) { s.exp = 0; if (--ttlCount === 0) _cancelTimer(); }
+        }
+        // The existing plain-set body, hoisted: stage `v` as an overlay and keep the
+        // dirty bookkeeping. Returns the slot so callers can set/clear its expiry.
+        const _stage = (key, v) => {
+            const s = slotFor(key);
+            const wasAbsent = s.ov.peek() === ABSENT;
+            s.ov.set(v);
+            if (wasAbsent) { dirty++; dirtySig.set(dirty); }
+            return s;
+        };
+        // The fire handler: ONE hoisted per-projection closure (the _readSrc
+        // precedent). Reverts exactly the keys due (exp <= now), in one batch, with
+        // per-drop dirty bookkeeping (clear()'s fail-closed pattern: a throwing
+        // _now/registry leaves dirty == overlaid count). The source is NEVER touched.
+        // _rearm runs AFTER the batch, so a subscriber's set(k,v,{ttl}) during the
+        // flush is honoured; _armAt clears first, so still <= 1 handle (T1).
+        const _fire = () => {
+            timerHandle = null; armedAt = 0;
+            if (ttlCount === 0) return;               // spurious after a full cancel / post-dispose
+            const t = _now();
+            batch(() => {
+                for (const s of slots.values()) {
+                    const e = s.exp;
+                    if (e === 0 || e > t) continue;   // not due -> untouched
+                    _dropExp(s);
+                    if (s.ov.peek() !== ABSENT) { s.ov.set(ABSENT); dirty--; dirtySig.set(dirty); }
+                }
+            });
+            _rearm();
+        };
+        const _rearm = () => {
+            if (ttlCount === 0) { _cancelTimer(); return; }
+            let min = Infinity;
+            for (const s of slots.values()) { const e = s.exp; if (e !== 0 && e < min) min = e; }
+            if (min === Infinity) { ttlCount = 0; _cancelTimer(); return; }   // defensive, fail closed
+            _armAt(min);
+        };
+        // Cold ttl branch of set(). A {}/{policy} bag (ttl === undefined) behaves as
+        // plain set AND still cancels a prior expiry. A bad ttl throws BEFORE staging,
+        // so the bag and source stay untouched. A re-set with an EARLIER deadline
+        // re-arms; a LATER one does not (the armed earlier timer fires spuriously and
+        // re-arms -- that is the contract).
+        const _setWithOpts = (key, v, o) => {
+            // A null bag is tolerated (old 2-arg-era `set(k, v, null)` behaved as
+            // a plain set), mirroring project(source, null). Non-null non-object
+            // bags degrade to a plain set via undefined member reads.
+            const ttl = o == null ? undefined : o.ttl;
+            if (ttl === undefined) { _dropExp(_stage(key, v)); return; }
+            if (!Number.isFinite(ttl) || ttl <= 0) {
+                throw new TypeError("set: ttl must be a finite number > 0");
+            }
+            const d = _now() + ttl;
+            if (!Number.isFinite(d)) {
+                throw new TypeError("project: clock now() must return a finite number");
+            }
+            const s = _stage(key, v);
+            if (s.exp === 0) ttlCount++;
+            s.exp = d;
+            if (timerHandle === null || d < armedAt) _armAt(d);
+        };
+
+        // Patch emission: iterate exactly the overlaid keys, handing scalars
+        // (key, from, to) to `fn` -- `from` is the UNTRACKED current source value,
+        // `to` the staged overlay. Read-only: overlays via .peek(), source under
+        // untrack, so calling this inside an effect subscribes to nothing. The
+        // visit set / order is byte-identical to forEachOverlay. Optional `skip`
+        // reuses ReconcilePolicy: (from, to, key) => true drops that key from the
+        // stream (e.g. `forEachPatch(fn, confirmOnEcho)` skips echoes); default
+        // undefined emits every overlaid key, changed or not. A throwing
+        // source.get propagates on the offending key with no writes anywhere, so
+        // the overlay bag is intact by construction (fn may already have run for
+        // earlier keys; callers needing atomicity use toPatch()).
+        const forEachPatch = (fn, skip) => {
+            for (const [key, s] of slots) {
+                const to = s.ov.peek();
+                if (to === ABSENT) continue;
+                _pk = key;
+                const from = untrack(_readSrc);
+                if (skip !== undefined && skip(from, to, key)) continue;
+                fn(key, from, to);
+            }
+        };
+
+        // Hoisted scratch for forEachPatch's untracked source read: ONE closure
+        // per projection, never per key/call, so the per-key emit body allocates
+        // nothing. `untrack` needs a function; _readSrc is it.
+        let _pk;
+        const _readSrc = () => source.get(_pk);
+
         return {
             get: (key) => slotFor(key).read(),
-            set: (key, v) => {
-                const s = slotFor(key);
-                const wasAbsent = s.ov.peek() === ABSENT;
-                s.ov.set(v);
-                if (wasAbsent) { dirty++; dirtySig.set(dirty); }
+            // Hot path (warm no-ttl): one arg load + !== undefined compare (not
+            // taken), one _stage (identical work to the old body), one _dropExp
+            // (one field load + !== 0 compare, not taken). Zero allocation, zero
+            // branches taken. All ttl logic lives in the cold _setWithOpts. The
+            // opts branch also STILL cancels a prior expiry (set(k,v,{}) -> plain).
+            set: (key, v, opts) => {
+                if (opts !== undefined) { _setWithOpts(key, v, opts); return; }
+                const s = _stage(key, v);
+                _dropExp(s);
             },
             clear: (key) => {
                 const s = slots.get(key);
                 if (s !== undefined && s.ov.peek() !== ABSENT) {
                     s.ov.set(ABSENT);
                     dirty--; dirtySig.set(dirty);
+                    _dropExp(s);
                 }
             },
             isOverlaid: (key) => {
@@ -208,6 +384,18 @@ export function createProjector(reg) {
                     if (o !== ABSENT) fn(key, o);
                 }
             },
+            // Emit the overlaid keys as a patch stream fn(key, from, to). Untracked,
+            // read-only, zero-alloc per-key body. See forEachPatch above.
+            forEachPatch,
+            // Cold convenience over forEachPatch: materialize the drafts as
+            // [{ key, from, to }, ...] (same visit set, order, values). The
+            // per-key record is the documented allocation of this form; reach for
+            // forEachPatch when you need the zero-alloc callback.
+            toPatch: (skip) => {
+                const out = [];
+                forEachPatch((key, from, to) => { out.push({ key, from, to }); }, skip);
+                return out;
+            },
             // Full-snapshot reconciliation: drop every overlay the policy considers
             // confirmed against the CURRENT (untracked) source value. For sources that
             // sync wholesale rather than per-key. Presentation-only -- the source owns
@@ -220,7 +408,7 @@ export function createProjector(reg) {
                         const o = s.ov.peek();
                         if (o !== ABSENT) {
                             const authoritative = untrack(() => source.get(key));
-                            if (pol(authoritative, o, key)) { s.ov.set(ABSENT); dropped++; }
+                            if (pol(authoritative, o, key)) { s.ov.set(ABSENT); _dropExp(s); dropped++; }
                         }
                     }
                     if (dropped) { dirty -= dropped; dirtySig.set(dirty); }
@@ -242,7 +430,7 @@ export function createProjector(reg) {
                             const o = s.ov.peek();
                             if (o !== ABSENT) {
                                 source.set(key, o); s.ov.set(ABSENT);
-                                dirty--; dirtySig.set(dirty);
+                                dirty--; dirtySig.set(dirty); _dropExp(s);
                             }
                         }
                         return;
@@ -250,7 +438,7 @@ export function createProjector(reg) {
                     let changed = false;
                     for (const [k, s] of slots) {
                         const o = s.ov.peek();
-                        if (o !== ABSENT) { source.set(k, o); s.ov.set(ABSENT); changed = true; }
+                        if (o !== ABSENT) { source.set(k, o); s.ov.set(ABSENT); _dropExp(s); changed = true; }
                     }
                     if (changed) { dirty = 0; dirtySig.set(0); }
                 });
@@ -259,11 +447,39 @@ export function createProjector(reg) {
                 batch(() => {
                     let changed = false;
                     for (const s of slots.values()) {
-                        if (s.ov.peek() !== ABSENT) { s.ov.set(ABSENT); changed = true; }
+                        if (s.ov.peek() !== ABSENT) { s.ov.set(ABSENT); _dropExp(s); changed = true; }
                     }
                     if (changed) { dirty = 0; dirtySig.set(0); }
                 });
             },
+            // Predicate-scoped partial ops (S7). pred(key, stagedValue) -- the
+            // forEachOverlay callback order, NOT ReconcilePolicy's. Visit slots in
+            // insertion order, ONE batch, per-drop dirty bookkeeping so a throwing
+            // pred leaves dirtyCount() === overlaidCount() (batch's finally still
+            // flushes): already-committed keys stay committed, no rollback.
+            commitWhere: (pred) => {
+                if (typeof pred !== "function") throw new TypeError("commitWhere: pred must be a function");
+                batch(() => {
+                    for (const [k, s] of slots) {
+                        const o = s.ov.peek();
+                        if (o === ABSENT) continue;
+                        if (!pred(k, o)) continue;
+                        source.set(k, o);
+                        s.ov.set(ABSENT); dirty--; dirtySig.set(dirty); _dropExp(s);
+                    }
+                });
+            },
+            clearWhere: (pred) => {
+                if (typeof pred !== "function") throw new TypeError("clearWhere: pred must be a function");
+                batch(() => {
+                    for (const [k, s] of slots) {
+                        const o = s.ov.peek();
+                        if (o === ABSENT) continue;
+                        if (!pred(k, o)) continue;
+                        s.ov.set(ABSENT); dirty--; dirtySig.set(dirty); _dropExp(s);
+                    }
+                });
+            },
             /**
              * Reclaim slots for keys that are no longer in use.
              *
@@ -308,6 +524,9 @@ export function createProjector(reg) {
                 dispose(dirtySig);
                 slots.clear();
                 dirty = 0;
+                // Cancel any pending TTL handle: a live setTimeout would hold the
+                // event loop open for up to `ttl` ms and retain this closure (T6).
+                _cancelTimer(); ttlCount = 0;
             },
         };
     }
@@ -408,8 +627,8 @@ export function makeReconciler(view, policy) {
  * @param {object} store A lite-store proxy from `store(...)`.
  * @returns {object} A projection handle (get/set/clear/commit/revert/isOverlaid/peek/...).
  */
-export function projectStore(store) {
-    return project(fromProxy(store));
+export function projectStore(store, opts) {
+    return project(fromProxy(store), opts);
 }
 
 /**
@@ -446,7 +665,9 @@ export function projectRoom(room, opts) {
         get: (key) => { room.storage.entries(); return room.storage.get(key); },
         set: (key, value) => room.storage.set(key, value),
     };
-    const view = project(source);
+    // Forward the flat opts bag: project reads only the clock keys (now/setTimer/
+    // clearTimer); policy is consumed above and ignored there.
+    const view = project(source, opts);
     // Drop confirmed drafts whenever authoritative state changes. The effect
     // tracks `entries` (not overlays/projected computeds), so view.clear() inside
     // reconcileAll never re-triggers it -> no loop. reconcileAll reads the source
@@ -569,7 +790,9 @@ export function projectQuery(qc, key, opts) {
             return merge(prev, one);
         }),
     };
-    const view = project(source);
+    // Forward the flat opts bag: project reads only the clock keys (now/setTimer/
+    // clearTimer); data/policy/merge are consumed above and ignored there.
+    const view = project(source, opts);
 
     // Auto-reconcile: only meaningful when the record read is reactive. Tracks
     // `data()` (never the overlays), so clearing drafts inside reconcileAll does
@@ -601,6 +824,120 @@ export function projectQuery(qc, key, opts) {
             qc.setQueryData(key, (prev) => merge(prev, overlays));
             view.revert();
         },
+        // Partial commit as ONE cache write (mirrors commit() above). NOT
+        // view.commitWhere: that would issue one setQueryData per matching field,
+        // breaking the single-write law. And NOT view.revert() after the write:
+        // revert drops the NON-matching drafts too (silent data loss) and skips
+        // per-key exp cancellation -- so clear ONLY the committed fields, in a
+        // batch, which folds the N dirtySig writes into one propagation.
+        commitWhere: (pred) => {
+            if (typeof pred !== "function") throw new TypeError("commitWhere: pred must be a function");
+            const overlays = Object.create(null);
+            let any = false;
+            view.forEachOverlay((f, v) => { if (pred(f, v)) { _put(overlays, f, v); any = true; } });
+            if (!any) return;
+            qc.setQueryData(key, (prev) => merge(prev, overlays));
+            _batch(() => {
+                const ks = _ownEnumerableKeys(overlays);
+                for (let i = 0; i < ks.length; i++) view.clear(ks[i]);
+            });
+        },
         dispose: () => { if (stopReconcile) stopReconcile(); view.dispose(); },
     };
 }
+
+/**
+ * Project a @zakkster/lite-crdt LWW-Map (`doc.map(name)`) as a per-key DRAFT
+ * overlay for optimistic / tentative UI. Unlike projectRoom (which wraps
+ * lite-room's COARSE storage -- one entries signal, any change re-runs every
+ * projected key), an LWW-Map has FINE-GRAINED reactive `get(key)`, so this
+ * adapter is truly granular: overlaying or committing one cell never re-runs a
+ * consumer of another. The projection never joins the merge -- it only decides
+ * what the local view tentatively overrides:
+ *
+ *   - set(key, value)  stage a draft -- local only, NOT synced, the CRDT untouched
+ *   - commit(key?)     promote drafts via `map.set` (emits ops + syncs). One op
+ *                      per committed key (N ops / N frames); LWW ops are
+ *                      commutative + idempotent so N frames == 1 semantically.
+ *                      Pass opts.transact (e.g. doc.transact) to coalesce a burst
+ *                      into ONE ops frame + one change (commit and commitWhere both
+ *                      wrap through it)
+ *   - revert()         discard drafts
+ *   - auto-reconcile   whenever an OVERLAID key's authoritative cell changes (local
+ *                      echo or a remote applyOp), drafts the policy considers
+ *                      confirmed are dropped; a CONFLICTING authoritative value --
+ *                      including a concurrent authoritative DELETE (reads as
+ *                      undefined) -- leaves the draft masked
+ *
+ * The map handle is consumed STRUCTURALLY: any object exposing a fine-grained
+ * reactive `get(key)` and a `set(key, value)` works, so this adapter adds no hard
+ * dependency on lite-crdt and never touches the doc, `map.store`, or the coarse
+ * reads (keys/values/entries/size). The reconcile effect tracks exactly the
+ * source cell of each currently-overlaid key (via `view.dirtyCount()` for the
+ * overlay-set dependency + a bare `map.get(k)` per overlaid key), so it re-runs
+ * on overlay-set transitions and on authoritative changes to overlaid keys only.
+ *
+ * -- READ-ONLY WRAPPER (object values), the recorded contract --
+ * lite-crdt's `get(key)` returns a deep READ-ONLY WRAPPER for object/array values
+ * (a different reference than the one passed to set), WeakMap-cached so it is
+ * stable across reads. Two consequences: (1) confirmOnEcho (Object.is) can NEVER
+ * auto-confirm an OBJECT-valued draft over projectCRDT, even on a genuine local
+ * echo -- the wrapper breaks reference equality (scalars confirm normally); use a
+ * {ttl} draft (the shipped heal) or a caller-supplied STRUCTURAL policy, whose
+ * reads pass through the wrapper transparently. (2) A policy must NEVER attempt to
+ * MUTATE the authoritative argument it is handed for an object value -- it is that
+ * read-only wrapper and lite-crdt throws `readonly`.
+ *
+ * -- STRING-COERCION KEY ALIASING (caller hazard) --
+ * lite-crdt coerces every map key to a string, but projection slots are keyed by
+ * PropertyKey. So drafts on `5` and `"5"` (or a Symbol coerced elsewhere) are TWO
+ * projection slots that commit into ONE CRDT cell -- last write wins, and
+ * dirtyCount() never reveals the collision. Stage under ONE key type. A
+ * `"__proto__"` map key is not usable in lite-crdt: `map.set` throws
+ * CRDTError("misconfigured"). The adapter does NOT wrap that policy -- a commit of
+ * a `"__proto__"` draft propagates the CRDT's own error with the draft still
+ * staged and dirtyCount() consistent (fail closed).
+ *
+ * -- DISPOSE ORDER --
+ * `doc.dispose()` makes subsequent mutations SILENT no-ops, so a commit AFTER the
+ * doc is disposed writes nothing yet still clears the drafts (an inherited
+ * dead-source data-loss class). Dispose the PROJECTION before the doc.
+ *
+ * @param {{get:(key:string)=>unknown, set:(key:string, value:unknown)=>void, delete?:(key:string)=>void}} map
+ *        A lite-crdt LWW-Map (`doc.map(name)`) or any structural equivalent.
+ * @param {{policy?: (authoritative:unknown, draft:unknown, key:string)=>boolean,
+ *          transact?: <T>(fn:()=>T)=>T,
+ *          now?:Function, setTimer?:Function, clearTimer?:Function}} [opts]
+ *        Reconciliation policy (default confirmOnEcho), an optional transact hook
+ *        that wraps commit/commitWhere, and the injectable overlay-TTL clock.
+ * @returns {object} A projection handle whose dispose() also stops the reconcile effect.
+ */
+export function projectCRDT(map, opts) {
+    if (map == null || typeof map.get !== "function" || typeof map.set !== "function") {
+        throw new TypeError("projectCRDT: map must expose get(key) and set(key, value)");
+    }
+    const policy = (opts && opts.policy) || confirmOnEcho;
+    // Fail closed: a supplied-but-not-a-function transact throws BEFORE any node
+    // is created. The branch is resolved once here, never per commit call.
+    const tx = opts && opts.transact !== undefined ? opts.transact : null;
+    if (tx !== null && typeof tx !== "function") {
+        throw new TypeError("projectCRDT: transact must be a function");
+    }
+    const source = { get: (k) => map.get(k), set: (k, v) => map.set(k, v) };
+    // Forward the flat opts bag: project reads only the clock keys (now/setTimer/
+    // clearTimer); policy/transact are consumed above and ignored there.
+    const view = project(source, opts);
+
+    // ONE hoisted per-adapter closure: forEachOverlay's callback, never a
+    // per-run arrow. The second callback arg (the staged value) is ignored.
+    const _trackSrc = (k) => { map.get(k); };
+    const stopReconcile = _effect(() => {
+        view.dirtyCount();                 // TRACKED: re-establishes deps on every overlay-set change
+        view.forEachOverlay(_trackSrc);    // TRACKED map.get per overlaid key (overlay side peeks)
+        view.reconcileAll(policy);         // untracked reads inside -> adds no deps
+    });
+
+    const commit = tx === null ? view.commit : (key) => { tx(() => view.commit(key)); };
+    const commitWhere = tx === null ? view.commitWhere : (pred) => { tx(() => view.commitWhere(pred)); };
+    return { ...view, commit, commitWhere, dispose: () => { stopReconcile(); view.dispose(); } };
+}

package/README.md

@@ -93,16 +93,18 @@ In steady state the projection allocates nothing: toggling an overlay on a key y
 
 Bind the primitives to a lite-signal registry. Pass the default namespace for normal use, or a `createRegistry({...})` result for an isolated graph (tests, the zero-GC gate). The package also exports `project` and `keyedStore` pre-bound to the default registry for the common case.
 
-### `project(source) -> Projection`
+### `project(source, opts?) -> Projection`
 
-`source` is any object with a reactive `get(key)` and a `set(key, value)`. Returns a handle:
+`source` is any object with a reactive `get(key)` and a `set(key, value)`. `opts` is an optional injectable clock for overlay TTL -- `{ now, setTimer, clearTimer }`, all-or-none (a mixed clock is a `TypeError`); it defaults to `performance.now` / `setTimeout` / `clearTimeout`. Returns a handle:
 
 | method | description |
 | --- | --- |
 | `get(key)` | reactive: overlay value if staged, else the source value |
-| `set(key, value)` | stage an **ephemeral** overlay (source untouched) |
+| `set(key, value, opts?)` | stage an **ephemeral** overlay (source untouched); pass `{ ttl }` to auto-revert it <sub>1.3</sub> |
 | `clear(key)` | drop one key's overlay (revert that key) |
 | `commit(key?)` | write one key's overlay (or, with no arg, all) into the source, then clear |
+| `commitWhere(pred)` | write + clear only the overlays where `pred(key, value)` is true <sub>1.3</sub> |
+| `clearWhere(pred)` | drop only the overlays where `pred(key, value)` is true (source untouched) <sub>1.3</sub> |
 | `revert()` | drop all overlays |
 | `dirtyCount()` | **tracked / reactive**: count of staged overlays — wire a Save badge to it |
 | `isDirty()` | **tracked / reactive**: `dirtyCount() > 0` |
@@ -110,6 +112,8 @@ Bind the primitives to a lite-signal registry. Pass the default namespace for no
 | `overlaidCount()` | untracked diagnostic: number of overlaid keys |
 | `peek(key)` | untracked effective read (no subscribe) |
 | `forEachOverlay(fn)` | iterate overlaid keys + values (untracked) |
+| `forEachPatch(fn, skip?)` | emit staged drafts as a `(key, from, to)` stream (untracked, read-only, zero-alloc per key) <sub>1.2</sub> |
+| `toPatch(skip?)` | materialize the drafts as `[{ key, from, to }, ...]` (cold convenience over `forEachPatch`) <sub>1.2</sub> |
 | `reconcileAll(policy?)` | drop overlays the policy confirms against the current source |
 | `prune()` | release slots for keys that are neither overlaid nor observed; returns how many were freed <sub>1.1</sub> |
 | `dispose()` | recycle every projection-owned node back to the pool |
@@ -175,6 +179,82 @@ Projects a single query entry's data **object**, exposing its **fields** as the
 
 The default merge copies **own enumerable** properties, symbols included, and defines them rather than assigning them. That matters for three field names you would otherwise lose silently: a field literally called `__proto__` lands as a real own key (assignment would retarget the prototype and drop it), inherited properties on `prev` are not absorbed into the record, and a symbol-keyed draft survives the commit instead of evaporating while `dirtyCount()` reports it saved. A custom `merge` is on its own for all three.
 
+### `projectCRDT(map, { policy, transact })` -- fine-grained drafts over [lite-crdt](https://www.npmjs.com/package/@zakkster/lite-crdt) <sub>1.4</sub>
+
+```js
+import { projectCRDT } from "@zakkster/lite-project";
+
+const doc = createCRDTDoc({ replicaId });
+const map = doc.map("profile");                       // a lite-crdt LWW-Map
+const draft = projectCRDT(map, { transact: doc.transact });
+
+draft.set("name", "Ada");          // optimistic edit, the CRDT is untouched
+draft.set("city", "London");
+draft.commit();                    // both cells promoted in ONE ops frame (transact)
+```
+
+Where `projectRoom` wraps lite-room's **coarse** storage (a single `entries` signal -- any change re-evaluates every projected key), a lite-crdt LWW-Map exposes a **fine-grained** reactive `get(key)`, so `projectCRDT` is truly granular: overlaying or committing one cell never re-runs a consumer of another. `set(key, value)` stages a local draft (no op emitted); `commit(key?)` promotes drafts through `map.set` -- one op per committed key (LWW ops are commutative and idempotent, so N frames are semantically one). Pass `transact` (e.g. `doc.transact`) to coalesce a burst into a single ops frame; it wraps both `commit` and `commitWhere`. An auto-reconcile drops a draft the authoritative cell catches up to (a local echo or a remote `applyOp`) while leaving **conflicts** -- and a concurrent authoritative **delete**, which reads as `undefined` -- masked. The map is consumed structurally (any `{ get, set }` whose `get` is fine-grained reactive), so there is no hard dependency on lite-crdt, and the projection never touches the doc or `map.store`. `dispose()` stops the reconcile effect.
+
+Two hazards are recorded contracts, not bugs:
+
+- **Read-only object wrapper.** lite-crdt's `get(key)` returns a deep **read-only wrapper** for object/array values (a different reference than the one you passed to `set`). So `confirmOnEcho` (`Object.is`) can never auto-confirm an **object-valued** draft, even on a genuine local echo -- the wrapper breaks reference equality. Use a `{ ttl }` draft (the shipped self-heal) or a caller-supplied **structural** policy, whose reads pass through the wrapper transparently; never mutate the authoritative value a policy is handed (it is read-only and lite-crdt throws). Scalars confirm normally.
+- **String-coercion key aliasing.** lite-crdt coerces every map key to a string. Drafts on `5` and `"5"` are two projection slots that commit into one cell (last write wins), and `dirtyCount()` never reveals the collision -- stage under one key type. A `"__proto__"` map key throws `CRDTError` on commit (fail closed: the draft stays staged). And because `doc.dispose()` makes writes silent no-ops, a commit **after** the doc is disposed writes nothing yet still clears the drafts -- dispose the projection before the doc.
+
+## Patch emission <sub>1.2</sub>
+
+The overlay bag already knows every staged draft's `to`; `forEachPatch` adds the source's `from` so a draft can cross the wire without re-walking the view.
+
+```js
+const draft = project(source);
+draft.set("name", "Ada");
+draft.set("email", "ada@x.dev");
+
+// Zero-alloc callback: hand each draft to a serializer / transport.
+draft.forEachPatch((key, from, to) => {
+  wire.send({ op: "set", key, prev: from, next: to });
+});
+
+// Cold convenience: materialize the same deltas as an array.
+const patch = draft.toPatch();   // [{ key: "name", from: undefined, to: "Ada" }, ...]
+```
+
+`from` is the **untracked** current source value, `to` the staged overlay. Both methods are read-only and untracked -- calling them inside an effect subscribes it to nothing -- and visit exactly the overlaid keys, in `forEachOverlay` order. `forEachPatch` allocates nothing per key; `toPatch` is the cold convenience whose per-key record is its documented allocation.
+
+An overlaid key is emitted whether or not `Object.is(from, to)`: the visit set stays equal to `dirtyCount()` and `commit()`'s write set, so a patch consumer (an LWW-Map op, a CRDT bump, an HTTP PATCH field) is never silently dropped. To suppress unchanged drafts, pass the same predicate shape reconcile uses -> `draft.forEachPatch(fn, confirmOnEcho)`. A throwing `source.get` propagates on the offending key with the overlay bag intact; callers needing atomicity use `toPatch()` (a partial array never escapes). The patch and `commit()` are two views of one delta: applying `toPatch()` to a copy of the source yields the same state `commit()` would write.
+
+Present on the `projectStore` / `projectRoom` / `projectQuery` handles too (for `projectQuery`, `from` is the cached record's field value).
+
+## Overlay TTL + partial commit <sub>1.3</sub>
+
+A pending overlay that never gets its ack has no way back. `set(key, value, { ttl })` gives it one: the overlay auto-**reverts** at `now() + ttl` (a finite number > 0), dropping the draft while the source stays untouched -- "the optimistic edit expired; fall back to authoritative".
+
+```js
+const draft = project(source);
+
+draft.set("status", "saving", { ttl: 5000 });   // reverts in 5s unless the ack clears it first
+// ... the server confirms -> draft.clear("status") (or reconcile) cancels the expiry
+```
+
+One re-armed timer runs per projection (each key stores its own deadline; arm and fire do an `O(slots)` cold scan, so the warm `set` path allocates nothing). A bad `ttl` throws **before** staging. A re-set **with** `ttl` re-arms; a re-set **without** `ttl` cancels the pending expiry -- each `set` fully specifies its overlay's lifetime. Every transition to un-overlaid (`clear`, `commit`, `revert`, a reconcile drop, `commitWhere` / `clearWhere`, and the fire itself) cancels that key's expiry, and `dispose()` cancels any pending handle.
+
+For a **deterministic** TTL (tests, an animation clock, a server tick) pass an injectable clock -- all-or-none, or a mixed clock is a `TypeError`:
+
+```js
+let t = 0;
+const clock = { now: () => t, setTimer: (fn, ms) => schedule(fn, t + ms), clearTimer: cancel };
+const draft = project(source, clock);            // forwarded by projectStore/projectRoom/projectQuery too
+```
+
+`commitWhere(pred)` and `clearWhere(pred)` are predicate-scoped partial saves: `pred(key, stagedValue)` (the `forEachOverlay` callback order) selects which overlays to act on, in one reactive propagation. `commitWhere` writes and clears only the matches; `clearWhere` discards them with zero source writes. A throwing `pred` is non-atomic on the core handle -- already-committed keys stay committed and `dirtyCount() === overlaidCount()`. On `projectQuery`, `commitWhere` is still a **single** `setQueryData` write for the matching fields, and the non-matching drafts survive.
+
+```js
+draft.set("name", "Ada");
+draft.set("email", "ada@x.dev");
+draft.commitWhere((key) => key !== "email");     // save name, keep email staged
+```
+
+**F-03.** `confirmOnEcho` is reference-equality (`Object.is`), so an object-valued draft can never echo-confirm against a structurally-equal source value of a different reference. The fix is a **caller-supplied** structural policy -- `reconcileAll(policy)` and the `forEachPatch` skip param both accept one; this library ships **no** deep-equal helper (a naive structural equal is a fail-open trap). The TTL is the shipped safety net: a stuck object draft self-heals on its deadline.
+
 ## Conventions
 
 ESM only. ASCII source. `node:test`. MIT.

package/llms.txt

@@ -24,15 +24,48 @@ Peer dependency: @zakkster/lite-signal ^1.5.0 (uses createRoot). ESM only. MIT.
 ## Entry points
 
 - createProjector(reg) -> { project, keyedStore }   // bind to any lite-signal registry
-- project(source) -> Projection                       // default registry
+- project(source, opts?) -> Projection                // default registry. [1.3] opts =
+                                                      // {now?, setTimer?, clearTimer?} injectable
+                                                      // clock for overlay TTL (all-or-none; mixed = TypeError)
 - keyedStore(initial?) -> { get, set, has, keys }     // minimal built-in source
+- VERSION -> string                                   // shipped package version, synced to package.json
 
 ## Projection handle
 
-get(key) | set(key,value) | clear(key) | commit(key?) [one key or all] | revert() |
+get(key) | set(key,value,opts?) | clear(key) | commit(key?) [one key or all] | revert() |
 dirtyCount() [TRACKED reactive] | isDirty() [TRACKED reactive] |
 isOverlaid(key) | overlaidCount() | peek(key) [untracked effective read] |
 forEachOverlay(fn) | reconcileAll(policy?) | dispose() [recycle all owned nodes] |
+commitWhere(pred) [1.3] | clearWhere(pred) [1.3]
+  [predicate-scoped partial ops. pred(key, stagedValue) -- the forEachOverlay callback
+  order, NOT ReconcilePolicy's. Visit slots in insertion order, ONE reactive propagation
+  each. commitWhere writes source.set(key,value) + clears each matching overlay; clearWhere
+  drops matching overlays with ZERO source writes. A throwing pred is non-atomic on the core
+  handle: already-committed keys stay committed, dirtyCount()===overlaidCount(). projectQuery
+  OVERRIDES commitWhere to keep the single-write law (one setQueryData for the matching fields,
+  then clear them per-key; non-matching drafts survive -- it does NOT reuse commit()'s revert()).] |
+set(key,value,{ttl}) [1.3]
+  [overlay TTL: schedules an auto-REVERT at now()+ttl (a finite number > 0, source untouched --
+  "the optimistic edit expired, fall back to authoritative"). ONE re-armed platform timer per
+  projection; each slot stores its own deadline; O(slots) cold scan on arm/fire (no side Map,
+  no per-set alloc on the warm path). Bad ttl (0/-1/NaN/Infinity/"5"/null) throws BEFORE staging.
+  Re-set WITH ttl re-arms (earlier deadline re-arms eagerly, later one fires spuriously + re-arms);
+  re-set WITHOUT ttl cancels the expiry (each set fully specifies its overlay's lifetime). EVERY
+  transition to un-overlaid (clear/commit(key)/commit()/revert/reconcileAll drop/commitWhere/
+  clearWhere/the fire) cancels that key's expiry; dispose() cancels the pending handle. F-03:
+  confirmOnEcho is reference-equality (Object.is) -- an object draft cannot echo-confirm across
+  references; the fix is a caller-supplied structural policy (reconcileAll/forEachPatch skip
+  accept one), NO deep-equal helper ships (fail-open trap), and the TTL is the shipped self-heal.] |
+forEachPatch(fn, skip?) [1.2] | toPatch(skip?) -> [{key,from,to}] [1.2]
+  [patch emission: iterate exactly the overlaid keys as fn(key, from, to) -- from =
+  UNTRACKED current source value, to = staged overlay. Read-only + untracked: safe
+  inside an effect, subscribes to nothing. Same visit set/order as forEachOverlay,
+  zero-alloc per-key body. Emits UNCHANGED drafts by default (visit set stays equal
+  to dirtyCount()); pass a reconcile-policy predicate (from,to,key)=>bool, e.g.
+  confirmOnEcho, to skip echoes. A throwing source.get propagates on that key with
+  the overlay bag intact. toPatch() is the cold convenience that materializes the
+  stream (its per-key record is the documented allocation). Present on the
+  projectStore/projectRoom/projectQuery handles too.] |
 prune() -> number [1.1] [release slots that are BOTH un-overlaid AND unobserved;
   returns how many were freed. A slot = 1 overlay signal + 1 projected computed,
   created by the first READ of a key and retained until dispose() (its computed may
@@ -55,10 +88,10 @@ prune() -> number [1.1] [release slots that are BOTH un-overlaid AND unobserved;
 
 ## Library adapters
 
-- projectStore(store)            // lite-store proxy. Per-key granular drafts;
+- projectStore(store, opts?)     // [1.3] opts forwards the injectable clock. lite-store proxy. Per-key granular drafts;
                                  // commit() writes through store[key]=v.
                                  // Top-level keys; pass a nested proxy to go deeper.
-- projectRoom(room, {policy?})   // lite-room room.storage (LWW-Map).
+- projectRoom(room, {policy?})   // [1.3] opts also carry the clock keys (now/setTimer/clearTimer). lite-room room.storage (LWW-Map).
                                  // Presentation-only optimistic drafts: set = local
                                  // draft (not synced), commit() = room.storage.set
                                  // (writes + syncs), auto-reconcile drops confirmed
@@ -84,6 +117,31 @@ prune() -> number [1.1] [release slots that are BOTH un-overlaid AND unobserved;
                                  // retargeting the prototype, inherited props on prev are
                                  // not absorbed, and symbol-keyed drafts survive commit.
                                  // A custom merge owns all three concerns itself.
+- projectCRDT(map, opts?)        // [1.4] lite-crdt LWW-Map (doc.map(name)). FINE-GRAINED
+                                 // per-key drafts (unlike projectRoom's coarse storage):
+                                 // overlaying/committing one cell never re-runs a consumer
+                                 // of another. opts = {policy?, transact?, + clock keys}.
+                                 // set(key,v) stages a draft (CRDT untouched); commit(key?)
+                                 // promotes via map.set (one op per key / N frames; pass
+                                 // opts.transact = doc.transact to coalesce a burst into ONE
+                                 // ops frame + one change -- wraps commit AND commitWhere).
+                                 // auto-reconcile drops confirmed drafts on an overlaid key's
+                                 // authoritative change (local echo or remote applyOp);
+                                 // conflicts AND concurrent authoritative deletes (read as
+                                 // undefined) stay masked. map consumed structurally
+                                 // (get/set); no hard lite-crdt dep; never touches the doc or
+                                 // map.store. dispose() stops the reconcile effect.
+                                 // HAZARD (recorded): lite-crdt's get returns a deep READ-ONLY
+                                 // WRAPPER for object values -> Object.is confirmOnEcho can
+                                 // NEVER auto-confirm an object draft (use {ttl} or a
+                                 // structural policy; never mutate the authoritative wrapper).
+                                 // HAZARD: lite-crdt STRING-COERCES keys, so drafts on 5 and
+                                 // "5" are two projection slots committing into ONE cell (last
+                                 // write wins); dirtyCount() never reveals it -- stage under one
+                                 // key type. A "__proto__" map key throws CRDTError on commit
+                                 // (fail closed: the draft stays staged). Dispose the projection
+                                 // BEFORE the doc (a commit after doc.dispose() writes nothing
+                                 // yet still clears the drafts -- the dead-source hazard).
 
 ## Zero-GC
 
@@ -97,4 +155,6 @@ a Map entry, and two pooled nodes. Warm the keys you churn.
   consumer that first reads the key; without detachment they would be adopted by
   that consumer and cascade-disposed on its next re-run. createRoot detaches them.
 - A projection only refines what the source exposes: over lite-room's coarse
-  storage it is coarse (any storage change re-evaluates every projected key).
+  storage it is coarse (any storage change re-evaluates every projected key). Over
+  a lite-crdt LWW-Map (projectCRDT) it is FINE-GRAINED -- per-key reactive get(key)
+  -- so committing one cell never re-runs a consumer of another. [1.4]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-project",
-  "version": "1.1.1",
+  "version": "1.4.0",
   "description": "Zero-GC projections for @zakkster/lite-signal: granular, derived, non-mutating reactive overlays with commit / revert / reconcile, and draft adapters for lite-store and lite-room.",
   "type": "module",
   "main": "./Project.js",
@@ -33,9 +33,11 @@
     "@zakkster/lite-signal": "^1.5.0"
   },
   "devDependencies": {
+    "@zakkster/lite-crdt": "^2.0.0",
     "@zakkster/lite-gc-profiler": "^1.16.0",
     "@zakkster/lite-leak": "^1.10.0",
-    "@zakkster/lite-signal": "^1.5.0"
+    "@zakkster/lite-signal": "^1.5.0",
+    "@zakkster/lite-store": "^1.2.1"
   },
   "keywords": [
     "reactive",