Code weight: simplify the draft proxy and share its equality walker#

Reviewed executable revision: 556cbd8ff (base 18abceee4, the fetched origin/main at review time). This record follows in a documentation-only commit.

• a6445a7c2 adds the draft revert oracle and the clone and deepEquals laws on unchanged production code.
• 639ed5a1e extends the revert oracle after a refactor mutant survived. The extension also passes on unchanged code.
• 6b68b8dc3 is the refactor.
• cccaf1b9e returns functions stored in a draft as stored, with a new native-differential law. This is a behavior change and a lost-write fix.
• 1a07cd3ce applies review fixes: a stronger revert grammar and witness, a duplicate comment, and a redundant key in check in getChanges (about 14 minified bytes).
• fcc353d5d through a49ae90e3 fix the bugs that a second review found. Each fix extends an oracle first. See Fixes from the second review.
• 31b2a6bd4 removes draft code that only bought speed. See Code weight over speed.
• b825e6483 fixes a CodeRabbit finding in the defineProperty fix: a non-configurable property with an object value threw. See Fixes from the second review.
• 0ce101acf fixes two more lost-write classes from CodeRabbit review: accessor definitions and typed-array mutator methods.
• cbd2aff06 and 556cbd8ff act on a loss audit of these oracles against docs/contributing/oracle-tests.md. They fix one bug, make the array and typed-array laws generated, and close the audit's grammar, checkpoint, and replay gaps.
• 7e5dfee25 fixes three bugs that code review found in the earlier fixes: class write-backs, writes after Object.freeze, and subarray reads.

Change#

packages/db/src/proxy.ts builds the drafts that collection.update and withChangeTracking pass to callbacks.

• The write-only proxyCache, the symbol-key branches over assigned_, and the one-use createObjectProxy wrapper are deleted. Every writer of assigned_ stores a string key (String(prop), String(index), or ''), so the symbol branches could not run.

• The custom array iterator is deleted. Arrays bind the native Array.prototype[Symbol.iterator] to the draft, so each element read takes the get trap and its parent edge. draft[Symbol.iterator]() now returns a native Array Iterator.

• The set trap's revert path sets modified and calls checkParentStatus on its own tracker. That function already clears tracking and continues up the chain when every value is reverted.

• draftValuesEqual becomes a draft mode of deepEqualsInternal in packages/db/src/utils.ts. Draft mode keeps Map and Set order, RegExp lastIndex, and array holes. The general mode does not change.

• A function stored as data (a field, an array element, a nested object member) is now returned as stored. See Stored functions.

The audit prototype also rewrote deepClone as one Reflect.ownKeys loop. That loop made every draft 8% to 17% slower, so the refactor first kept the original two-loop form. 31b2a6bd4 adopts the shorter loop. See Code weight over speed.

Each row bundles the built dist, with private members renamed, for base and 31b2a6bd4 under the same package.json. The refactor alone (1a07cd3ce) saved 1,739 minified and 453 gzip bytes on the full public API. The fixes from the second review added 917 minified and 303 gzip bytes. 31b2a6bd4 then removed 623 minified and 193 gzip bytes of speed-only code.

Why the oracle work came first#

Sixteen source mutants on unchanged code model plausible mistakes in this refactor. Before this work, eight of them passed the whole db suite (7,596 tests). Seven are real gaps:

• A partial revert treated as a full revert, which drops the remaining change (P2).
• A nested write under a symbol key treated as no change (E5).
• deepClone copying non-enumerable string keys, or dropping enumerable or non-enumerable symbol keys (C1, C2, C3).
• deepEquals comparing RegExp lastIndex, or treating array holes as differences (D2, D4).

The eighth, a wrong parent edge for array iterator elements (P4), is equivalent under every public observation. See Mutant calibration.

A ninth (deepEquals comparing Maps in order) failed one unrelated test only.

The draft revert oracle#

packages/db/tests/proxy-revert-oracle.property.test.ts generates write histories on a draft of a three-field row. An operation sets a field to a new value, reverts it to its original, deletes it, writes a nested property (a string or symbol key), writes an array index, or writes a row property through for...of. Values are primitives (including -0 and NaN), Dates, RegExps, Maps (with primitive or Set values), Sets, arrays with holes, objects with a symbol key, and arrays of rows.

The model applies the same operations to plain-data specs and compares values with its own encoding of draft equality. It never reads a draft. After each history, the check asserts:

• getChanges() holds exactly the fields whose final value differs from the original, each with that value, and deleted fields as undefined.
• The draft reads back the model's final value.
• The original row is unchanged.

The generator also emits a revert of a field that is currently changed, so most reverts run the set trap's revert branch. A second property builds partial reverts directly: it changes two or three fields in any order, then reverts all of them but one.

Each property runs a fixed campaign (seed 2026101) and a random campaign: 400 general histories and 200 partial-revert histories. TANSTACK_DB_PROXY_REVERT_SEED and TANSTACK_DB_PROXY_REVERT_PATH select a replay. A positive witness requires the fixed general campaign to reach every operation, a change made only under a nested symbol key, and effective reverts: at least 10 histories where a change survives a revert, and at least 30 histories that end fully reverted. A revert counts only when the field differs from its original before the revert. Eleven pinned histories hold one rule each.

Review of the first version found that its witness also counted reverts of unchanged fields, which write an equal value and do nothing. With those excluded, the first grammar reached 10 partial and 11 full reverts in 400 histories. The changed-field revert and the partial-revert property raise that coverage. Mutant N2 now fails 6 of the oracle's 16 cases, including both partial-revert campaigns.

Limits:

• Map, Set, and array mutator methods (set, add, push) mark a value changed without a revert check. The native-operation tests in proxy.test.ts own them.
• Top-level symbol writes are outside the grammar. getChanges() does not report them, and the coverage map lists symbol writes as unsupported.

Clone key classes and deepEquals order rules#

• proxy-detachment-contract.test.ts pins that a draft copies a row's own enumerable string keys and every own symbol key, enumerable or not, and does not copy non-enumerable string keys. This is current behavior, not a promise.
• utils.property.test.ts adds four generated laws: deepEquals ignores Map and Set insertion order, RegExp lastIndex, and array holes. These are the rules draft equality keeps, so a shared walker must not leak one mode into the other.

Stored functions#

The get trap bound every function it returned to the private copy, so it could call built-in methods such as Map.prototype.get, which reject a Proxy receiver. That binding also applied to functions stored as data:

On main, array iteration was the only read path that kept identity, because the custom array iterator did not take the get trap. The native iterator does, so the refactor first lost identity there too.

The binding had a worse effect: a stored method saw the private copy as this. A method such as bump() { this.count++ } then changed the copy without tracking, and getChanges() reported no change. Inside collection.update, that write was lost.

cccaf1b9e returns an own data function as stored. A call then sees the draft as this, so its writes take the set trap. Inherited Array, Map, and Set methods keep their draft handling.

proxy.test.ts adds a native-differential law. Each probe runs on a native row and on a draft of an equal row, and the results must be equal. The probes are field access, array index, for...of, spread, includes and indexOf, an array callback, a nested field, Object.values, a Map value, a Set member, a call, a function assigned during the callback, and this inside a stored method. One more case checks that a write through this appears in getChanges(). The law fails 8 of 14 cases on main and 10 of 14 on the refactor before the fix.

Fixes from the second review#

A second review found one regression in the refactor and several bugs that main also has. Each fix extends an owner first, so the new law fails before the fix. Bytes are for the full public API, minified and gzip, against the commit before.

Design decisions for these fixes:

• Typed-array class. Draft equality treats a typed array of another class as a change. deepEquals still ignores the class, as utils.test.ts has pinned since #434.
• Array read methods. Every non-mutating method reads through the draft. b57d60022 first ran searches, join, keys, and toString on the copy for speed. 31b2a6bd4 removed that list. Running the element methods on the copy and then replacing elements with drafts was faster but cost 167 more gzip bytes.
• Classes and keyless objects. In both modes, instances of two different classes differ. A plain or null-prototype object from any realm compares by keys with any class, because draft snapshots and plain JSON hold class instances as plain objects. (815432ebd first made a plain object differ from a class instance; 7e5dfee25 reverted that after review found that writing back the row's own instance became a change.) A class instance without enumerable keys equals only itself. URLs compare by href, because a draft copies a URL by its href; by identity, an untouched URL would differ from its own snapshot.

The law that takes its methods from Array.prototype closes a whole class: a new built-in method fails the law until it has arguments. Its last case also caught the bound constructor.

Limits that remain:

• A draft reads a class instance of the original row as a plain object, so a private-field getter reads undefined. The detachment contract owns that boundary. The revert oracle writes class instances but never starts with one.
• A built-in method called through this on a nested Map or Set draft, such as Map.prototype.get.call(this.m, key), throws, because the receiver is a Proxy. This is a Proxy limit.
• Reading an object under a frozen or fixed key of a draft counts that key as changed, because the Proxy invariants require the raw copy. The row may publish an equal value.
• Writing back a keyless class instance of the original row counts as a change, because the snapshot holds it as an empty plain object.
• DataView setters on a draft are not tracked. No owner generates a DataView.
• A mutator method that changes nothing, such as sort on a sorted array or add of a present Set member, counts as a change, so the row publishes an equal value. Arrays, Maps, and Sets did this on main. Typed arrays do too since 0ce101acf. This is a deliberate limit: a revert check after mutators would cost bytes to avoid a publish of an equal value.

I4 first survived every owner, because no test edited an array while an iterator was open. The iteration contract's array law closes that gap. K7 first survived too, and utils.property now compares a URL with an object that inherits the same href. A5 gives the same results and is only slower: searches through the draft compare memoized drafts.

Code weight over speed#

Drafts run inside collection.update callbacks. These calls are rare and almost never touch large values, so draft speed does not matter, and bytes do. 31b2a6bd4 removes code that only bought speed:

Mutants of each new form fail the owners:

The I and A3 to A5 mutants in the previous section apply to code that 31b2a6bd4 removed.

Mutant calibration#

"Owners" are the revert oracle and the four existing owners (proxy.test.ts, proxy-detachment-contract.test.ts, proxy-iteration-contract.test.ts, utils.property.test.ts). "Before" is the owners without this change's tests. The full-suite column shows whether any other db test caught the mutant.

On unchanged production (18abceee4)#

P4 is equivalent under every public observation. An array element's parent edge feeds only the array's own revert check, and getChanges() works at the row level, where it compares each field with draft equality. A wrong edge can make the array mark itself reverted early, but the row then compares the field by value and still reports the change. The refactor's native iterator records the right edge through the get trap.

On the refactor (6b68b8dc3)#

N14 first survived, because generated Map values were only primitives. 639ed5a1e lets Map values be nested Sets and adds a pinned case for a reordered Set inside a Map value.

Performance#

Each timing process loads one implementation and runs each workload five times after two warm-up passes. Processes alternate, and each ratio is the median of 11 processes of each. An A/A control of two copies of the base stayed within ±1%.

Each ratio is new time over base time. "Prototype loop" is the audit prototype. "Kept loop" is the final code. The array-method row was measured with the stored-function fix, which adds an own-property check before each inherited method is handled. A second run with the fix gave 0.830, 0.876, and 0.766 for the three draft rows above. Bisection showed that its deepClone loop caused the regression: the equality fold alone was faster (0.92, 1.00, 0.81 on the draft rows), and the other proxy changes with the original loop were faster too (0.92, 0.93, 1.03). deepClone runs twice for each draft, and the Reflect.ownKeys loop calls propertyIsEnumerable for each key. Keeping the two-loop form costs about 18 minified bytes. The harness is not checked in.

Timings for the fixes#

These timings describe a49ae90e3. 31b2a6bd4 removed the iterator and the copy-method list for code weight, so the iteration and join rows no longer hold. These runs used 11 processes of each variant. The machine was loaded, and an A/A control stayed within ±5%.

The iterator first used a generator, which made object elements 1.4 times slower. It also named the get trap as a function expression, which made every draft write about 7% slower. The kept iterator is a module function. It calls the trap through the handler object and skips primitives. The class check in deepEquals runs after the keys match, so an unequal row exits before it.

ORC-001 through ORC-014#

The owners are:

• R, the revert oracle proxy-revert-oracle.property.test.ts: four generated properties over one grammar (general histories, partial reverts, nested round trips, and URL and keyless writes).
• N, the native-methods oracle proxy-native-methods.property.test.ts: generated array and typed-array calls compared with native values.
• T, the native-differential tables in proxy.test.ts: stored functions, defineProperty, and frozen and sealed drafts. These are bounded enumerations, not important generated properties.
• U, the laws this change adds to utils.property.test.ts.

ORC-004 controls#

R (all four properties share one grammar).

• Reconstruction: the pinned histories rebuild each rule and each reported bug in R's own grammar and check. These include a nested add-then-delete, a stale parent edge, a key added as undefined, a typed-array subclass, typed NaN, a URL write, a keyless write, and a class-instance write-back. The general grammar reaches each of their shapes. 556cbd8ff added the same-object revert so that a write-back of the row's own object is generated, not only pinned.
• Ablation: each mutant in Mutant calibration and Fixes from the second review removes one rule, edge, or clause. Every one fails an owner, except P4, which is equivalent.
• Range: three fields. Values are primitives 0, -0, 1, NaN, "a", "b", null, and undefined; Dates (including invalid); RegExps with lastIndex 0 or 1; Maps of up to two entries, with values that may be Sets; Sets of up to two members; arrays of up to three slots with holes; objects with up to two string keys and a symbol key; arrays of rows; typed arrays of up to three elements (three classes); URLs; a keyed class instance; and, as written values only, a keyless class instance. The marginal cases are empty containers, -0 and NaN, holes, and an absent key against a key holding undefined. Typed-array subclasses, URLs, keyless instances, and the class write-back each exposed a missing rule when first added.
• Exclusion: applicable rejects a nested write on a value that is not an object, an index write beyond the length or into a Uint8Array, and a revert of a field that is absent both originally and now. Model and driver skip the same operations. Mutator methods and top-level symbol writes are outside the grammar.

N (arrays and typed arrays).

• Reconstruction: the rows of the earlier pinned tables run for every method as fixed cases.
• Ablation: mutants A1, A2, N3, M1, M2, Y1, Y3, S1, and S2 each fail an owner.
• Range: array rows of up to four slots from 0 to 3, undefined, holes, objects, and nested arrays of up to two objects. Typed rows of up to four values from 0, -0, 1, 2, NaN, and 3.5. An index-shaped argument from 0 to 4, so negative and out-of-range indexes occur. Every method of the built-in prototypes. The marginal cases are empty rows, holes, and duplicate elements.
• Exclusion: every generated call is legal JavaScript, and a native throw is an observation that the draft must reproduce. A callback that writes is outside the grammar.

U. The laws use small fixed value sets with the pinned pairs inside the same property. Mutants K1 to K7 and R1 to R4 are the ablations. Every pair in the domain is legal, so no exclusion applies.

The two-step callback property was already on main. This change only adds its campaigns and replay, and it makes no new grammar claim for it.

Reusable boundary laws (ORC-013)#

Bug-class closure (ORC-012)#

Each class below is bounded by contract, histories, production path, and observation. Open cells name their owner.

None of these classes has a known reachable counterexample to its claimed law. The open cells are listed in the coverage map's Drafts row.

Guide prompts that do not apply#

The guide's reusable boundary-law checklist targets adapter and lifecycle oracles. Drafts have no provider, classifier, transport, await boundary, or acquired resource, so real-provider conformance, minimal ambiguity, name invariance, await-boundary transitions, local/transport refinement, and partial-construction cleanup do not apply. Representation symmetry appears as the class rule above. Value-and-work refinement does not apply, because no work bound is promised.

Verification#

On 556cbd8ff, which includes origin/main at 3463cf8ad, with the built dist:

• packages/db Vitest, typecheck off: 199 files, 7,801 tests.
• packages/db tsc --noEmit: no errors.
• pnpm check:mangle: 368 names.
• pnpm test:minified-db: error names, index metadata, query rows, and live updates.
• pnpm --filter @tanstack/db test:dist: 5 files, 290 tests.

The environment was Node v24.19.0 and Vitest 3.2.4 on Darwin arm64.