epoch-2: Proxy-based API, hooks instrumentation, docs overhaul

[nerdalytics]

Summary

• Migrate reactive core from function-based (v1000) to Proxy-based API (v2000) with natural JS syntax (state.value instead of state())
• Add zero-cost hooks instrumentation system across all four primitives (state, effect, derive, batch)
• Rewrite all documentation to match the actual implementation — fix wrong API signatures, remove fictional features, add hooks coverage
• Optimize performance across 6 phases: batch/flush, effect lifecycle, subscriber lookup, WeakMap elimination, readList fast path, hot-path inlining
• Add property-based testing suite covering core reactive invariants across all primitives
• Merge trunk (tree-shaking sideEffects: false, CI OIDC publishing, multi-cycle benchmark)
• Replace uglify-js with esbuild for minification
• Fix all exactOptionalPropertyTypes and noUncheckedIndexedAccess type errors for strict LTS build

Changes

Core (src/index.ts)

• Proxy-based state() with five handler traps (get, set, deleteProperty, has, ownKeys)
• derive() returns { value, reactive } — disposal via reactive = false toggle, not dispose() method
• All four primitives accept optional hooks parameter as last argument
• Hook types in src/types.ts, composition utility in src/hooks/
• Handler factory return types narrowed with NonNullable<> for exactOptionalPropertyTypes compliance

Performance Optimizations

• Phase 1: Stable dependency skip on re-runs, reuse module-level arrays, merge read-tracking functions, remove dead code
• Phase 2: Reference-equality fast paths in dep comparison, replace spreads with loops in cleanup
• Phase 3: Cache symbol property access in getSubscribers
• Phase 4: Replace 5 global WeakMaps (effectDependencies, effectStateReads, parentEffect, childEffects, subscriberCache) with direct EffectFunction properties (__deps, __reads, __parent, __children); change inner reads tracking from WeakMap to Map; simplify promoteTempToGlobal to 2 assignments; remove subscriberCache layer
• Phase 5: Ordered readList fast path for stable dependency re-runs — captures reads as an ordered array on first run, replays exact sequence on re-runs to detect stable deps without Set/Map allocation
• Phase 6: Hot-path inlining via isolated A/B benchmarking — each optimization tested in isolation and in combinations on separate branches before merging:
  • Inline no-subscriber write path: skip performWrite/checkInfiniteLoop when !currentEffect (~28% improvement on subscriberless writes)
  • Shared singleton handler for hookless states: pre-built HOOKLESS_HANDLER at module level avoids 5 factory calls + 1 object allocation per state (~33% improvement on state creation)

Phase 6 methodology: We tested each candidate optimization on an isolated branch from the same base, then in pairwise combinations. We rejected one candidate (inline no-effect read path) after isolated testing showed it regressed its target benchmark by ~7% — a regression hidden when measured cumulatively with other changes.

Benchmark Results

Worktree-based comparison, 1M iterations, 10 cycles x 7 samples = 70 total per benchmark. Medians shown.

Benchmark	trunk (v1000)	epoch-2 (v2000)	Delta
Effect-heavy (epoch-2 wins)
state + derive + 2 effects	1443.54ms	846.57ms	-41.4%
100 states individual	139.57ms	50.03ms	-64.2%
state write 100 subs	448.24ms	180.22ms	-59.8%
state write 1 sub	56.73ms	34.55ms	-39.1%
state + derive	578.99ms	432.84ms	-25.2%
effect triggers	26.95ms	20.42ms	-24.2%
derive chain depth 10	7.54ms	6.40ms	-15.1%
Proxy overhead (trunk wins)
state read (no effect)	4.13ms	30.27ms	+633%
state creation	9.24ms	44.25ms	+379%
state no subs	12.77ms	62.81ms	+392%
batch + derive	25.82ms	92.16ms	+257%
batch + derive + 2 effects	32.89ms	92.25ms	+180%
Neutral
many dependencies	3.23ms	3.56ms	+10.2%
100 states batched	3.08ms	3.33ms	+8.1%
classic loop (control)	3.70ms	3.74ms	+1.1%

Interpretation: Epoch-2's Proxy-based architecture pays a fixed cost on bare reads/writes/creation (no subscribers involved). Where it matters — effect re-runs, subscriber notification, derive chains — epoch-2 is 15-64% faster due to per-property tracking, stable-dep skip, readList fast path, and inlined hot paths.

Documentation (docs/README*.md, README.md, .github/README.md)

• Fix API signatures across all primitive docs to include hooks parameters
• Replace all dispose() / Symbol.dispose / using references with reactive toggle in README.derive.md
• Replace fictional batchDirtyTargets with actual pendingEffects + deferredEffectCreations mechanism in README.batch.md
• Fix architecture details, proxy diagram, batch/flush internals in README.core.md
• Rewrite README.debugging.md — remove fictional env-var debug system (BEACON_DEBUG, NODE_ENV, devLogRead/Write/Assert), replace with hooks-based debugging
• Add README.hooks.md covering all 16 hook callbacks, composition, error isolation
• Add hooks links and sections to every primitive doc
• Remove all v2000.0.0 version references from prose
• Tighten README prose: cut filler words, switch passive voice to active, remove duplicate Architecture subsections, fix factually wrong browser FAQ

Refactoring

• Decompose monolithic functions to reduce cognitive complexity (threshold 4)
• Improve internal variable and function naming
• Import composeHook from hooks module instead of inlining

Tests

• Reorganize test suite: {primitive}-core.test.ts, {primitive}-hooks.test.ts, integration, behavior
• Add hooks test coverage for all four primitives + compose utility
• 193 unit/integration/PBT tests passing, 100% branch coverage, 100% function coverage
• Fix noUncheckedIndexedAccess type errors across all property-based test files
• Property-based testing suite (11 test files, 64 tests) covering core reactive invariants:
  • state: array mutations, same-value optimization, proxy identity, deep reactivity, frozen/sealed objects, frozen children of reactive state
  • effect: cleanup completeness, infinite loop detection boundary, dynamic dependency tracking
  • batch: effect deduplication, error recovery
  • derive: consistency invariants

Infrastructure

• Merge trunk: absorb tree-shaking sideEffects: false, CI OIDC npm publishing, multi-cycle benchmark
• Replace uglify-js with esbuild for postbuild minification
• Fix Biome npm scripts: check:fix now runs biome check --write (was biome format --fix)
• Tighten cognitive complexity threshold to 10
• Add AGENTS.md hierarchy with CLAUDE.md symlinks across all domains
• Move full README content to .github/README.md, keep root README as install + quick start only
• Update CI workflows, bump dependencies

Test plan

• npm test — 193/193 tests pass (129 unit + 64 property-based, 27 suites)
• npm run test:coverage — meets coverage targets (100% branches, 100% functions, 90% lines)
• npm run build — builds successfully (esbuild minification)
• tsc -p tsconfig.lts.json — zero type errors under strict mode
• npm run check — Biome lint + format + assists clean
• npm run benchmark — confirms performance improvement
• Verify tree-shaking: state-only bundle eliminates derive and batch code
• Verify CI OIDC: publish job uses id-token: write, no NODE_AUTH_TOKEN
• Verify no references to removed features: grep -r "dispose()" docs/ shows only effect disposals
• Verify no fictional features: grep -rE "BEACON_DEBUG|devLog|batchDirtyTargets|v2000\.0\.0" docs/ returns empty