@zakkster/lite-project 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -3,6 +3,125 @@
 All notable changes to `@zakkster/lite-project` are documented here. The format
 follows Keep a Changelog; this project adheres to semantic versioning.
 
+## [1.1.1] - 2026-09-03
+
+### Added
+
+- **`VERSION`** export from `Project.js` (declared in `Project.d.ts`), kept in
+  exact sync with `package.json`, so a consumer can read the shipped version at
+  runtime.
+- Gated torture harness under `test/torture/` (dev-only; not shipped). Seven
+  tiers run strictly sequentially behind `node --expose-gc test/torture.mjs`:
+  T0 metamorphic laws, T1 degenerate inputs, T4 reconcile door, T5 oracle fuzz,
+  T6 zero-alloc gate, T7 retention soak, T9 controls. Gate RULES:
+  `maxMajor 0`, `maxPauseMs 4`, `maxArrayBuffersGrowth 0` under `stabilize:"deep"`.
+  Witnessed on a green run (default seed):
+  `leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 |
+  retained=0.00 B/op growths=0`
+  (the `alloc=` per-op heap-bracket reading prints as-is, `n/a` when
+  inconclusive; the binding alloc gates are `checkNoGc`, the zero-retention
+  gate below, and the structural deltas below).
+  The get/set/clear triangle on warmed keys leaves `poolGrowths` and
+  `totalAllocations` deltas both 0 over 200k toggles; 4096 build/tear-down cycles
+  return the leak tracker to `size()===0`; `prune()` reclaims >= 19990 of 20000
+  unbounded-read slots.
+- Retained-allocation gate (`measureAllocs` + `checkAllocs` with
+  `maxBytesPerCall: 0`, the profiler's zero-retention assertion): the warmed
+  get/set/clear triangle retains 0 B/call (min over 8 batches), catching
+  arbitrary JS-object retention that the asynchronously-delivered `gc.major`
+  count cannot see; an unsettled or inconclusive reading fails the gate.
+
+### Changed
+
+- Peer dependency floor is now `@zakkster/lite-signal ^1.5.0` (was a pinned
+  preview build). No behaviour change: 1.5.0 is the current stable line and
+  supplies every surface this package uses (`batch` 1.0.0, `hasObservers` 1.1.4,
+  `createRoot` 1.5.0).
+
+## [1.1.0] - 2026-07-16
+
+### Added
+
+- **`projectQuery(qc, key, opts?)`** — a library adapter projecting ONE
+  [`@zakkster/lite-query`](https://www.npmjs.com/package/@zakkster/lite-query)
+  entry's data object as a draft overlay whose projected keys are the **fields**
+  of that record. Stage optimistic field edits with `set(field, v)`, then
+  `commit()` promotes every staged field into the cache as a **single**
+  `setQueryData(key, prev => merge(prev, overlays))` write (one cache mutation,
+  one broadcast) — `commit(field)` writes just one. Options:
+  - `data` — the query's reactive data accessor (e.g. `query.data`). Supplied,
+    projected reads track the cache and an auto-reconcile drops drafts the
+    authoritative record catches up to (echo policy) while leaving conflicting
+    values masked, exactly as in `projectRoom`. Omitted, the adapter degrades to
+    a non-reactive `getQueryData` snapshot with no auto-reconcile.
+  - `policy` — reconciliation policy (default `confirmOnEcho`).
+  - `merge` — how overlays fold into the record (default shallow spread
+    `{ ...prev, ...overlays }`; `prev` may be nullish, seeding a fresh record).
+
+  The query client is consumed **structurally** (any object exposing
+  `getQueryData` / `setQueryData`), so this adds no hard dependency on
+  lite-query. The returned handle's `dispose()` also stops the reconcile effect.
+  No changes to the core or the existing adapters.
+
+- **`Projection.prune()`** — bounded-keyspace reclamation. A slot (one overlay
+  signal + one projected computed) is created by the first **read** of a key and
+  retained until `dispose()`, because its computed may still have subscribers —
+  so neither `commit()` nor `revert()` gives any of it back. Over a large or
+  unbounded keyspace (a virtualised list, a record whose fields churn, a
+  projection driven by user input) that is real growth: 20,000 reads retained
+  60,000 nodes. `prune()` releases only the slots that are **both** un-overlaid
+  (nothing staged to lose) and unobserved (no live consumer subscribed to the
+  projected read), so it can never dispose a computed out from under a
+  subscriber; a pruned key rebuilds transparently on its next read. Returns the
+  number of slots freed. Cold path — call it on a viewport change or after a
+  commit, not per frame. `O(slots)`. Requires `hasObservers` from the registry;
+  a custom registry without it gets a `prune()` that reclaims nothing and
+  returns `0` rather than a crash. Available on every projection handle,
+  including the `projectStore` / `projectRoom` / `projectQuery` wrappers.
+
+### Fixed
+
+Found by the adversarial suite below during the 1.1.0 prepublish review. Every
+one of these failed **silently**: `commit()` returned normally and `dirtyCount()`
+fell to 0 while the value never reached the record.
+
+- **A draft field named `__proto__` was dropped — and could inject fields.** The
+  default merge built the record with `out[k] = v`, which for `__proto__`
+  retargets the prototype instead of creating an own key, so the field vanished.
+  Worse, staging that draft set the overlay bag's own prototype, and the merge's
+  `for...in` then enumerated *that object's* keys — so committing a `__proto__`
+  draft injected its contents as top-level fields of the record. The overlay bag
+  is now null-prototype, keys are defined rather than assigned, and iteration is
+  own-keys only.
+- **Symbol-keyed drafts evaporated on commit.** Projection keys are
+  `PropertyKey` and slots live in a `Map`, so a symbol-keyed draft staged fine
+  and reported dirty — then `for...in` skipped it and the commit reported
+  success for a value that never landed. The merge now includes own enumerable
+  symbols.
+- **Inherited properties leaked into the record.** `for...in` walked `prev`'s
+  prototype chain, absorbing inherited properties into the committed record as
+  own fields. Own-keys only now.
+
+### Verified
+
+- 17 new adversarial tests (`test/torture_test.mjs`); **65 tests total**,
+  `node --test`. `prune()` is exercised for reclamation, for refusing to drop
+  observed or overlaid slots, and for transparent rebuild after a prune.
+
+### Torture (opt-in: `npm run test:torture`)
+
+- `test/torture_test.mjs` — adversarial regression suite, part of the normal
+  `npm test`. Each case pins a defect from the list above, or a limit that is
+  deliberately **not** fixed and must not drift silently. Node-count tests
+  install a fixed-ceiling registry over a node-free source, so the
+  projection's own accounting is readable.
+- `bench/torture/overlay-fuzzer.mjs` — seeded, oracle-checked fuzz: projectQuery
+  set/clear/commit(field)/commit-all/revert plus external cache writes (driving
+  auto-reconcile), asserting the view + cache track an overlay/record oracle and
+  every commit is a single write; plus a core project() overlay/commit/revert
+  fuzz over a reactive source. Scale with `TORTURE_SCALE`. Dev-only; not in
+  `files[]`.
+
 ## [1.0.0] - 2026-06-25
 
 First stable release. Zero-GC projections for `@zakkster/lite-signal`.

package/Project.d.ts

@@ -1,7 +1,9 @@
-// Type declarations for @zakkster/lite-project v1.0.0
+// Type declarations for @zakkster/lite-project v1.1.1
 // Zero-GC projections for @zakkster/lite-signal.
 // (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com> -- MIT
 
+export const VERSION: string;
+
 /**
  * A reactive keyed source a projection can wrap. Any object with a reactive
  * `get(key)` and a `set(key, value)` qualifies (the built-in `keyedStore`, a
@@ -61,6 +63,24 @@ export interface Projection<K extends PropertyKey = PropertyKey, V = unknown> {
     commit(key?: K): void;
     /** Drop all overlays. */
     revert(): void;
+    /**
+     * Release slots for keys that are neither overlaid nor observed, returning
+     * how many were freed.
+     *
+     * A slot (one overlay signal + one projected computed) is created by the
+     * first READ of a key and retained until `dispose()`, because its computed
+     * may have live subscribers. Over a large or unbounded keyspace that is real
+     * growth, and neither `commit()` nor `revert()` gives any of it back.
+     *
+     * `prune()` is the safe reclamation path: it skips any key with a staged
+     * overlay (nothing to lose) and any whose projected read still has
+     * observers. A pruned key rebuilds transparently on its next read.
+     *
+     * Cold path -- call it on a viewport change or after a commit, not per frame.
+     * O(slots). Returns 0 on a custom registry that does not supply
+     * `hasObservers`.
+     */
+    prune(): number;
     /** Recycle every projection-owned node back to the lite-signal pool. */
     dispose(): void;
 }
@@ -91,6 +111,18 @@ export interface ProjectorRegistry {
     createRoot<T>(fn: () => T): T;
     dispose(handle: unknown): void;
     untrack<T>(fn: () => T): T;
+    /**
+     * Optional. Coalesces the multi-signal writes in commit / revert /
+     * reconcileAll into one propagation so a multi-key consumer never sees a
+     * torn snapshot. Omit it and those writes propagate one at a time.
+     */
+    batch?<T>(fn: () => T): T;
+    /**
+     * Optional. Required by {@link Projection.prune}, which uses it to tell a
+     * slot nobody is subscribed to from one a consumer still depends on. Omit it
+     * and `prune()` safely reclaims nothing and returns 0.
+     */
+    hasObservers?(handle: unknown): boolean;
 }
 
 /** The registry-bound projection primitives returned by {@link createProjector}. */
@@ -185,3 +217,42 @@ export function projectRoom(
     room: RoomLike,
     opts?: ProjectRoomOptions,
 ): Projection<string, unknown>;
+
+/** The subset of a @zakkster/lite-query client that {@link projectQuery} consumes. */
+export interface QueryClientLike {
+    /** Non-reactive cache peek for a key. */
+    getQueryData(key: unknown): unknown;
+    /** Write a key's data; an updater function receives the previous value. */
+    setQueryData(key: unknown, valueOrUpdater: unknown | ((prev: unknown) => unknown)): unknown;
+}
+
+/** Options for {@link projectQuery}. */
+export interface ProjectQueryOptions<V extends object = Record<PropertyKey, unknown>> {
+    /**
+     * 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
+     * to a non-reactive `getQueryData` snapshot with no auto-reconcile.
+     */
+    data?: () => V | null | undefined;
+    /** Reconciliation policy for auto-reconcile; defaults to {@link confirmOnEcho}. */
+    policy?: ReconcilePolicy<keyof V, unknown>;
+    /** Fold staged field overlays into the record; defaults to a shallow spread `{ ...prev, ...overlays }`. */
+    merge?: (prev: V | null | undefined, overlays: Partial<V>) => V;
+}
+
+/**
+ * Project ONE @zakkster/lite-query entry's data object as a DRAFT overlay whose
+ * projected keys are the FIELDS of that object. `set(field, v)` stages a draft;
+ * `commit()` promotes every staged field into the cache as a SINGLE
+ * `setQueryData(key, prev => merge(prev, overlays))` write (`commit(field)` writes
+ * one). When `opts.data` is supplied, reads track the cache and an auto-reconcile
+ * drops drafts the authoritative record catches up to while leaving conflicts
+ * masked. The query client is consumed structurally, so there is no hard
+ * dependency on lite-query. The returned handle's `dispose()` also stops the
+ * reconcile effect.
+ */
+export function projectQuery<V extends object = Record<PropertyKey, unknown>>(
+    qc: QueryClientLike,
+    key: unknown,
+    opts?: ProjectQueryOptions<V>,
+): Projection<keyof V, unknown>;

package/Project.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-project v1.0.0 -- zero-GC projections for @zakkster/lite-signal.
+ * @zakkster/lite-project v1.1.1 -- 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,
@@ -56,8 +56,11 @@ import {
     untrack as _untrack,
     effect as _effect,
     batch as _batch,
+    hasObservers as _hasObservers,
 } from "@zakkster/lite-signal";
 
+export const VERSION = "1.1.1";
+
 // 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
 // "absent" and "present with value V" share one node and one field -- no boxing.
@@ -74,6 +77,9 @@ const ABSENT = Symbol("projection.absent");
 export function createProjector(reg) {
     const signal = reg.signal;
     const computed = reg.computed;
+    // Optional: only prune() needs it. A custom registry that does not provide it
+    // simply gets a prune() that reclaims nothing rather than a crash.
+    const hasObservers = reg.hasObservers;
     const createRoot = reg.createRoot;
     const dispose = reg.dispose;
     const untrack = reg.untrack;
@@ -258,6 +264,42 @@ export function createProjector(reg) {
                     if (changed) { dirty = 0; dirtySig.set(0); }
                 });
             },
+            /**
+             * Reclaim slots for keys that are no longer in use.
+             *
+             * A slot is created by the first READ of a key and retained until
+             * dispose(), because its computed may have live subscribers. Over a
+             * large or unbounded keyspace -- a virtualised list, a query whose
+             * record churns, a projection driven by user input -- that is real
+             * growth: 20,000 reads retained 60,000 nodes, and neither commit()
+             * nor revert() gave any of them back.
+             *
+             * A slot is only safe to drop when it is BOTH un-overlaid (no staged
+             * value to lose) and unobserved (no consumer's computed/effect is
+             * subscribed to its read). `hasObservers` is what makes the second
+             * half checkable; without it, pruning could dispose a computed out
+             * from under a live subscriber.
+             *
+             * Cold path -- call it on a viewport change or after a commit, not
+             * per frame. O(slots).
+             *
+             * @returns {number} how many slots were released.
+             */
+            prune: () => {
+                if (typeof hasObservers !== "function") return 0;
+                let n = 0;
+                for (const [key, s] of slots) {
+                    if (s.ov.peek() !== ABSENT) continue;      // a staged draft would be lost
+                    // Only the READ computed's observers matter. `ov` is private to
+                    // the slot and is always observed by that very computed, so
+                    // testing it too would make prune() a permanent no-op.
+                    if (hasObservers(s.read)) continue;        // a consumer is subscribed
+                    dispose(s.read); dispose(s.ov);
+                    slots.delete(key);
+                    n++;
+                }
+                return n;
+            },
             dispose: () => {
                 // createRoot left these unowned, so nothing auto-disposes them.
                 // Dispose the computed before its overlay so the read never re-evaluates
@@ -282,6 +324,7 @@ const _default = createProjector({
     dispose: _dispose,
     untrack: _untrack,
     batch: _batch,
+    hasObservers: _hasObservers,
 });
 
 export const project = _default.project;
@@ -417,3 +460,147 @@ export function projectRoom(room, opts) {
         dispose: () => { stopReconcile(); view.dispose(); },
     };
 }
+
+/**
+ * Copy one own enumerable property WITHOUT going through assignment.
+ * `out[k] = v` retargets the prototype when k is "__proto__" instead of creating
+ * an own key, so the field silently vanishes. defineProperty creates a real own
+ * key and leaves Object.prototype alone, so the merged record still has a normal
+ * prototype for consumers that deepStrictEqual it.
+ * @private
+ */
+function _put(out, k, v) {
+    Object.defineProperty(out, k, { value: v, writable: true, enumerable: true, configurable: true });
+}
+
+/**
+ * Default merge for projectQuery's commit.
+ *
+ * Iterates OWN keys only, symbols included. `for...in` was wrong on both counts:
+ *
+ *  - It walks the prototype chain. Combined with the assignment bug above, a
+ *    draft field named "__proto__" did not merely disappear -- `overlays.__proto__
+ *    = {pwned:1}` set the overlay bag's PROTOTYPE, and `for...in` then enumerated
+ *    that object's keys, so committing a "__proto__" draft INJECTED `pwned` as a
+ *    top-level field of the record. Own-keys iteration plus _put closes both ends.
+ *  - It skips symbols. project() keys are PropertyKey and slots live in a Map, so
+ *    a symbol-keyed draft staged fine, reported dirty, then evaporated on commit
+ *    while dirtyCount fell to 0 -- a "saved" signal for a value that never landed.
+ * @private
+ */
+const _ownEnumerableKeys = (o) => {
+    const keys = Object.keys(o);
+    const syms = Object.getOwnPropertySymbols(o);
+    for (let i = 0; i < syms.length; i++) {
+        if (Object.prototype.propertyIsEnumerable.call(o, syms[i])) keys.push(syms[i]);
+    }
+    return keys;
+};
+
+const _spreadMerge = (prev, overlays) => {
+    const out = {};
+    if (prev != null) {
+        const pk = _ownEnumerableKeys(prev);
+        for (let i = 0; i < pk.length; i++) _put(out, pk[i], prev[pk[i]]);
+    }
+    const ok = _ownEnumerableKeys(overlays);
+    for (let i = 0; i < ok.length; i++) _put(out, ok[i], overlays[ok[i]]);
+    return out;
+};
+
+/**
+ * Project ONE @zakkster/lite-query entry's data object as a DRAFT overlay whose
+ * projected keys are the FIELDS of that object. This is the optimistic-edit
+ * layer for a fetched record: stage field drafts locally, then commit them back
+ * into the query cache as a SINGLE `setQueryData` write (one cache mutation, one
+ * broadcast, one refetch-eligible change) rather than one write per field.
+ *
+ *   - get(field)       reactive read: the draft if staged, else the query field
+ *   - set(field, v)    stage a draft -- the query cache is NOT touched
+ *   - commit(field?)   promote drafts into the cache via ONE setQueryData(key, prev
+ *                      => merge(prev, overlays)); commit() writes all, commit(f) one
+ *   - revert()         discard drafts
+ *   - auto-reconcile   when `opts.data` is supplied, a refetch / external cache
+ *                      write that the policy considers confirmed drops the matching
+ *                      drafts; a CONFLICTING authoritative value leaves the draft
+ *                      masked (the engine's Object.is short-circuit suppresses the
+ *                      flicker), exactly as in projectRoom
+ *
+ * Reactivity depends on `opts.data`: pass the query's reactive data accessor
+ * (e.g. `query.data` from lite-query's `createQuery`) so projected reads track
+ * the cache and auto-reconcile is armed. WITHOUT it the adapter degrades to a
+ * non-reactive `qc.getQueryData(key)` snapshot for the base read (drafts are
+ * still reactive through their overlay signals, but the underlying record is not
+ * tracked and there is no auto-reconcile).
+ *
+ * The query client is consumed structurally -- any object exposing
+ * `getQueryData(key)` and `setQueryData(key, valueOrUpdater)` works -- so this
+ * adapter adds no hard dependency on lite-query.
+ *
+ * @param {{getQueryData:Function, setQueryData:Function}} qc A lite-query client.
+ * @param {PropertyKey|Array<unknown>} key The query key whose record is projected.
+ * @param {{
+ *   data?: () => (Record<PropertyKey, unknown> | null | undefined),
+ *   policy?: (authoritative:unknown, draft:unknown, key:PropertyKey)=>boolean,
+ *   merge?: (prev:(Record<PropertyKey,unknown>|null|undefined), overlays:Record<PropertyKey,unknown>)=>Record<PropertyKey,unknown>,
+ * }} [opts]
+ * @returns {object} A projection handle whose commit() writes the cache once and
+ *          whose dispose() also stops the reconcile effect.
+ */
+export function projectQuery(qc, key, opts) {
+    if (qc == null || typeof qc.getQueryData !== "function" || typeof qc.setQueryData !== "function") {
+        throw new TypeError("projectQuery: qc must expose getQueryData(key) and setQueryData(key, valueOrUpdater)");
+    }
+    const data = opts && typeof opts.data === "function" ? opts.data : null;
+    const policy = (opts && opts.policy) || confirmOnEcho;
+    const merge = (opts && opts.merge) || _spreadMerge;
+
+    // Reactive when `data` is supplied (tracks the query accessor); otherwise a
+    // non-reactive cache peek. `set` is only reached if a caller drives the base
+    // commit path directly; the overridden commit() below never uses it.
+    const source = {
+        get: (field) => {
+            const rec = data ? data() : qc.getQueryData(key);
+            return rec == null ? undefined : rec[field];
+        },
+        set: (field, v) => qc.setQueryData(key, (prev) => {
+            const one = Object.create(null);
+            _put(one, field, v);
+            return merge(prev, one);
+        }),
+    };
+    const view = project(source);
+
+    // Auto-reconcile: only meaningful when the record read is reactive. Tracks
+    // `data()` (never the overlays), so clearing drafts inside reconcileAll does
+    // not re-trigger it -> no loop. Mirrors projectRoom.
+    const stopReconcile = data
+        ? _effect(() => { data(); view.reconcileAll(policy); })
+        : null;
+
+    return {
+        ...view,
+        // One cache write for the whole burst of field drafts.
+        commit: (field) => {
+            if (field !== undefined) {
+                if (!view.isOverlaid(field)) return;
+                const v = view.peek(field);
+                const one = Object.create(null);
+                _put(one, field, v);
+                qc.setQueryData(key, (prev) => merge(prev, one));
+                view.clear(field);
+                return;
+            }
+            // Null-prototype bag: `overlays["__proto__"] = v` on a plain object
+            // sets the prototype instead of creating a key, which is how a
+            // "__proto__" draft used to turn into field injection downstream.
+            const overlays = Object.create(null);
+            let any = false;
+            view.forEachOverlay((f, v) => { _put(overlays, f, v); any = true; });
+            if (!any) return;
+            qc.setQueryData(key, (prev) => merge(prev, overlays));
+            view.revert();
+        },
+        dispose: () => { if (stopReconcile) stopReconcile(); view.dispose(); },
+    };
+}

package/README.md

@@ -83,6 +83,10 @@ Updating the dirty count is allocation-free (a single fixed signal per projectio
 
 In steady state the projection allocates nothing: toggling an overlay on a key you have already touched reuses its pooled nodes (verified — 200k overlay toggles on warmed keys leave `poolGrowths` and `totalAllocations` flat). The honest non-claim: the *first* touch of a **new** key allocates a slot record, a Map entry, and two pooled nodes (one overlay signal, one projected computed). Warm the keys you churn.
 
+**Slots outlive `commit()` and `revert()`.** A slot is created by the first *read* of a key and retained until `dispose()`, because its projected computed may still have subscribers — clearing an overlay does not release it. Over a bounded keyspace (a form, a settings panel) that is exactly the point: the nodes are there to be reused. Over a large or unbounded one — a virtualised list, a record whose fields churn, a projection driven by user input — it is real growth that neither `commit()` nor `revert()` gives back.
+
+`prune()` <sub>1.1</sub> is the reclamation path. It releases only slots that are **both** un-overlaid (no staged value to lose) and unobserved (no live consumer subscribed to the projected read), so it can never pull a computed out from under a subscriber; a pruned key rebuilds transparently on its next read. It is a cold path — call it on a viewport change or after a commit, never per frame — and it is `O(slots)`. It needs `hasObservers` from the registry to tell an unused slot from a watched one; a custom registry without it gets a `prune()` that safely reclaims nothing and returns `0`.
+
 ## API
 
 ### `createProjector(reg) -> { project, keyedStore }`
@@ -107,6 +111,7 @@ Bind the primitives to a lite-signal registry. Pass the default namespace for no
 | `peek(key)` | untracked effective read (no subscribe) |
 | `forEachOverlay(fn)` | iterate overlaid keys + values (untracked) |
 | `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 |
 
 ### `keyedStore(initial?) -> { get, set, has, keys }`
@@ -153,6 +158,23 @@ draft.commit();                    // promotes via room.storage.set (writes + sy
 
 Room storage is authoritative and CRDT-merged, so the projection is **presentation-only**: it never joins the merge. `set` stages a local draft, `commit()` promotes it through `room.storage.set`, and an auto-reconcile drops drafts once the authoritative value catches up (echo) while leaving a conflicting authoritative value **masked** (no flicker). Because `room.storage` is coarse (a single `entries` signal, a plain non-reactive `get`), the adapter subscribes through `entries()` and the projection inherits that coarse granularity. Call `dispose()` to stop the reconcile effect. Only `room.storage` is projectable this way; sets / lists / texts have non-keyed shapes.
 
+### `projectQuery(qc, key, { data, policy, merge })` — optimistic field drafts over [lite-query](https://www.npmjs.com/package/@zakkster/lite-query)
+
+```js
+import { projectQuery } from "@zakkster/lite-project";
+
+const query = qc.createQuery(["user", id], fetchUser);
+const draft = projectQuery(qc, ["user", id], { data: query.data });
+
+draft.set("name", "Ada");          // optimistic field edit, cache untouched
+draft.set("email", "ada@x.dev");
+draft.commit();                    // ONE setQueryData merging both fields back in
+```
+
+Projects a single query entry's data **object**, exposing its **fields** as the projected keys. `commit()` folds every staged field into the cached record in a **single** `setQueryData(key, prev => merge(prev, overlays))` write (one cache mutation, one broadcast), rather than one write per field; `commit(field)` writes just one. Pass the query's reactive `data` accessor so reads track the cache and an auto-reconcile drops drafts a refetch confirms (echo) while masking conflicts — omit it to degrade to a non-reactive `getQueryData` snapshot with no auto-reconcile. `merge` defaults to a shallow spread (a nullish `prev` seeds a fresh record); `policy` defaults to `confirmOnEcho`. The client is consumed structurally (`getQueryData` / `setQueryData`), so there's no hard dependency on lite-query. `dispose()` stops the reconcile effect.
+
+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.
+
 ## Conventions
 
 ESM only. ASCII source. `node:test`. MIT.

package/llms.txt

@@ -32,7 +32,14 @@ Peer dependency: @zakkster/lite-signal ^1.5.0 (uses createRoot). ESM only. MIT.
 get(key) | set(key,value) | 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]
+forEachOverlay(fn) | reconcileAll(policy?) | dispose() [recycle all owned nodes] |
+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
+  have subscribers), so commit()/revert() reclaim nothing. Cold path: viewport change
+  or post-commit, never per frame. O(slots). Needs registry.hasObservers; without it
+  returns 0 rather than throwing. A pruned key rebuilds on next read. Present on the
+  projectStore/projectRoom/projectQuery handles too.]
 
 ## Source = any { get(key): reactive, set(key, value) }
 
@@ -58,6 +65,25 @@ forEachOverlay(fn) | reconcileAll(policy?) | dispose() [recycle all owned nodes]
                                  // drafts via the coarse `entries` signal; conflicts
                                  // stay masked. dispose() stops the reconcile effect.
                                  // CRDT owns the merge; the projection never joins it.
+- projectQuery(qc, key, opts?)   // [1.1] lite-query entry. Projects ONE record's
+                                 // FIELDS as draft keys. opts = {data?, policy?, merge?}.
+                                 // set(field,v) stages a draft (cache untouched);
+                                 // commit() folds ALL staged fields into the cache in a
+                                 // SINGLE setQueryData(key, prev => merge(prev, overlays))
+                                 // write (commit(field) writes one). data = the query's
+                                 // reactive data accessor (e.g. query.data) -> reactive
+                                 // reads + auto-reconcile (echo drops confirmed drafts,
+                                 // conflicts masked); OMIT data -> non-reactive
+                                 // getQueryData snapshot, no auto-reconcile. merge default
+                                 // = {...prev,...overlays} (nullish prev seeds a record).
+                                 // qc consumed structurally (getQueryData/setQueryData);
+                                 // no hard lite-query dep. dispose() stops the effect.
+                                 // Default merge copies OWN ENUMERABLE props (symbols
+                                 // included) and DEFINES them (never out[k]=v): a field
+                                 // named "__proto__" lands as a real own key instead of
+                                 // retargeting the prototype, inherited props on prev are
+                                 // not absorbed, and symbol-keyed drafts survive commit.
+                                 // A custom merge owns all three concerns itself.
 
 ## Zero-GC
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-project",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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",
@@ -24,10 +24,18 @@
     "LICENSE.txt"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test test/*_test.mjs",
+    "torture": "node --expose-gc test/torture.mjs",
+    "verify": "npm test && npm run torture",
+    "prepublishOnly": "npm run verify"
   },
   "peerDependencies": {
-    "@zakkster/lite-signal": ">=1.5.0-alpha"
+    "@zakkster/lite-signal": "^1.5.0"
+  },
+  "devDependencies": {
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0",
+    "@zakkster/lite-signal": "^1.5.0"
   },
   "keywords": [
     "reactive",
@@ -38,7 +46,12 @@
     "overlay",
     "zero-gc",
     "esm",
-    "lite-signal"
+    "lite-signal",
+    "query",
+    "tanstack-query",
+    "lite-query",
+    "cache",
+    "commit"
   ],
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
@@ -47,6 +60,10 @@
     "url": "git+https://github.com/PeshoVurtoleta/lite-project.git"
   },
   "homepage": "https://github.com/PeshoVurtoleta/lite-project#readme",
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-project/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/PeshoVurtoleta"