reverse-engineering-anything/docs/adr/javascript/pushed-effect-invalidation.md

JavaScript effects invalidate reads through one effect log

Status

Accepted (2026-11-15) for plan W10 step 3. Implementation lands in slices, one target kind per PR. Each slice removes the reader-side checks it replaces and reports its corpus measurement.

Context

The semantic engine records effects while it indexes a source:

• binding writes;
• member writes and escapes from the member-mutation phase;
• ambient writes and escapes;
• direct eval sites that may rebind names in visible activations;
• global-code sites (eval, Function) that may replace globals.

Readers then pull invalidation by calling one helper per effect kind before they trust a value. Measured at 104b1a35b4, outside the owner module javascriptSemanticOpaqueEffects.ts, 32 calls in 14 files make this check:

Helper	Calls	Files
referenceMayHaveChangedAt	12	8
semanticOpaqueBindingReadMayHaveChanged	7	5
semanticOpaqueGlobalMayHaveChanged	4	4
semanticBindingMayHaveOpaqueEffect	4	2
semanticOpaqueNameMayHaveChanged	3	2
semanticOpaqueBindingEffects	2	1

Most readers combine two to four of these calls. For example, an intrinsic read combines semanticOpaqueNameMayHaveChanged, semanticOpaqueGlobalMayHaveChanged and ambientEscapes.covers, and a receiver walk calls referenceMayHaveChangedAt for both the method and __proto__.

A reader that omits one of these calls reports a stale fact with complete coverage. The direct-eval invalidation fix had to land twice, six days apart: 9ac76d3d94 for semantic values and 26e155987f (#7053) for Electron reads. The structural audit (report 14, C1 point 5) records this as "readers must ask".

The classification of implicit execution (#10605, #10631) and the member-mutation work allowance (#11144) do not replace these checks. They decide where code may run and bound the work, but readers still decide separately whether a recorded effect applies to their read.

Decision

1. One effect log owner. javascriptSemanticEffectLog.ts holds every recorded effect, keyed by its target:

   • a binding id;
   • an ambient root path;
   • an activation scope, for name introduction by sloppy direct eval;
   • global code.

   Each entry keeps the effect node, its kind and its property path. Producers append to the log when they record an effect. Nothing else writes to it.

2. One read query. Readers ask whether a read of a target, at a site and for a property path, may observe an earlier effect: effectLog.mayObserve(read, target, path). They state the value they read, not the effect kinds that could change it.

   The owner keeps the existing proofs inside this query: effect timing, capture-before-effect, read-before-effect within one activation, strict and sloppy eval, and path disjointness. No reader evaluates these proofs.

3. Caches keep the whole-state clear. Recording an effect still calls clearSemanticValueCaches, which drops every cached value. Per-target invalidation was measured and declined; see Per-target cache invalidation. A value-engine read that consults a cache therefore sees every earlier effect without asking for it.

4. Completeness is explicit. The log records which producer phases are complete. Before the member-mutation phase completes, a member-path query answers "may observe", which is the current conservative referenceMayHaveChangedAt behavior when nothing is indexed. A phase refused by its work allowance never completes.

5. Guard. After each slice, an architecture guard forbids importing the superseded helpers outside the effect log. When the last slice lands, the helpers are deleted and the guard prevents a new reader-side check from returning.

Migration

Slices move one target kind at a time, so each stays reviewable and measurable:

1. Global code and introduced names. This covers semanticOpaqueGlobalMayHaveChanged and semanticOpaqueNameMayHaveChanged at intrinsic and global reads (typed arrays, timers, async effects, module interop and expression shapes).
2. Binding rebinding. This covers semanticBindingMayHaveOpaqueEffect, semanticOpaqueBindingReadMayHaveChanged and semanticOpaqueBindingEffects.
3. Member paths. This covers referenceMayHaveChangedAt (receiver walks, network, Electron, map, route and resource readers) and the effects view in visitSemanticReferenceEffectsAtSite.

Each slice is measured cold on the 14 published bundles of the W10 corpus, before and after. The measurement covers per-value status digests, the total unknown count, elapsed and CPU time, and peak RSS. A slice that changes no proof should change no status.

The slice stops and is reported, not merged, if it shows either of these:

• unknown rises by more than 0.1% of examined values on the corpus, or on any single bundle;
• a status changes from unknown to a definite value. That is a soundness regression and is never accepted.

Merging JavaScriptSymbolicBindings (W10 step 4, audit C2) follows the last slice, because its one consumer should read values through the same log.

Rejected alternatives

Folding global-code effects into isUnmodifiedGlobalReference

One prototype added the global-code check (eval, Function) to isUnmodifiedGlobalReference, so that every caller of that helper would refuse a global that opaque code may replace. It was measured at 3d9d35ab26 on the 14 corpus bundles:

• Static findings and value statuses did not change. No status changed from unknown to a definite value, and the unknown count stayed at 69,348.
• The full semantic IR changed on the 4 bundles that contain Function(. Callers of the helper dropped operation records without recording an unknown in their place:
  • handlebars: boundary operations fell from 9 to 3.
  • isomorphic-git: boundary operations fell from 37 to 10 and timer operations from 6 to 0. Of the promise operations, 26 were removed and 17 became unresolved awaited expressions.
  • underscore: timer operations fell from 7 to 0 and boundary operations from 3 to 0.
  • vue: boundary operations fell from 36 to 2, timer operations from 9 to 0 and promise operations from 29 to 23.

The only Function( site in handlebars is Function("return this")(), which cannot replace a global, so none of the handlebars removals is justified. The fold is rejected: it silently drops records instead of marking them unknown. A read that opaque code may change must stay in the IR and be reported as unknown, not omitted. Global-code reads go through the effect log query (decision 2) instead.

Exempting constant-source Function bodies

Exempting constant Function bodies that cannot write, such as return this, would have removed the handlebars regressions. The rule is not adopted: it adds a new precision proof for one observed pattern and is not needed once readers ask the effect log. It can be proposed separately with its own measurement.

Per-target cache invalidation

The first draft of decision 3 invalidated only the cached values that depend on an effect's target. Existing caches store a result under the binding it was computed for (bindingId), even when it read other bindings, and the expression and capture caches have the same shape. Per-target invalidation would therefore need every cached value to record the targets it read, plus a reverse index from target to dependents.

It was measured at the head of #11282 (effect log slice 1) on the 14 corpus bundles, with clearSemanticValueCaches instrumented locally:

• Clears per bundle range from 1,340 (underscore) to 32,269 (openpgp). Almost all come from the member-mutation phase, which clears once per recorded effect.
• The binding values those clears discard are few: 0 to 306 primitive and 36 to 1,391 caller-independent values per bundle. The expression and capture caches are WeakMaps, so their entries were not counted.
• Upper bound: with every clear disabled (unsound; the IR changes on all 5 measured bundles), CPU time fell by 9% on zip.js and isomorphic-git, 8% on openpgp and 4% on rxjs, and did not change measurably on vue. Peak RSS did not change. These are 2 alternating runs per bundle under a load average of 9 to 11, so the smaller figures are within noise.

Per-target invalidation could recover only part of that 4 to 9% bound, at the cost of dependency tracking in every value cache and a reverse index. It is declined.

Clearing once per member-mutation convergence round instead of once per effect is also declined. Values read later in the same round would be stale, and there is no argument yet that the round's fixed point makes them safe.

Consequences

• A new reader cannot forget an effect kind, because it asks one question about the value it reads.
• Effect proofs have one owner. A precision fix, such as a new disjointness proof, applies to every reader at once.
• Cache invalidation is unchanged: every recorded effect still clears the whole value state. Removing every clear would save at most 9% CPU on the measured bundles.
• The log retains effect entries until the source's analysis ends. They are already retained today in bindingWrites, memberWrites, escapedPaths, the ambient effect lists and opaqueEffects. The log replaces those indexes rather than adding a copy.
• Until the last slice lands, readers use both forms. The guard's counted baseline can only shrink.