Kernel observation primitive (onUnobserved) → signals-native fetch cancellation in silo

[scottmessinger]

Closes #83. Built on top of #82 (this PR targets the #82 branch so the diff is just #83's changes — retarget to main once #82 lands).

Part 1 — Kernel owns the reactive system

packages/kernel/src/system.ts reimplements the primitive layer on alien-signals/system's createReactiveSystem(...) instead of importing signal/computed/effect from alien-signals directly. It's a faithful port of alien-signals 3.x's operator layer (update/notify/unwatched + the *Oper functions); the graph algorithm (link/unlink/propagate/checkDirty) is still delegated to alien-signals. The only behavioral additions:

• unwatched(node) additionally fires a registered onUnobserved handler.
• link(dep, sub) additionally fires a registered onObserved handler on the unobserved→observed (first-subscriber) transition.

Both are gated behind counters that stay 0 until a handler is registered, so the hot path is byte-for-byte the upstream behavior when observation is unused (e.g. the js-framework-benchmark never touches silo).

New public API

// @supergrain/kernel
export function onObservationChange(
  node: ReactiveNode,
  handlers: { onObserved?: () => void; onUnobserved?: () => void },
): () => void;
export function getObservationNode(proxy: object): ReactiveNode; // dedicated, never-written liveness node

trackNode / isObserved are exposed from @supergrain/kernel/internal (sharp tools).

All kernel imports of signal/computed/effect/startBatch/endBatch/getActiveSub/setActiveSub were repointed to the owned module (core.ts, read.ts, collections.ts, batch.ts, internal.ts, index.ts). @supergrain/husk also moved to the kernel's effect (otherwise its effects and kernel signals would live in separate graphs).

Liveness-node design (the issue's open question)

Approach (1) — a dedicated liveness node per handle — but not $VERSION, which bumps on every field write and would break fine-grained reactivity. The liveness node is never written; find/findQuery call trackNode so any rendering component subscribes to it. Unmounting the last observer ⇒ unwatched ⇒ deferred cancel.

Part 2 — Silo cancellation onto observation

• Replaced the manual subscribe/unsubscribe ref-counting in finder.ts with observation-driven cancellation: onUnobserved schedules the chunk interrupt after gcTimeMs; onObserved clears it on a quick re-subscribe; maybeInterrupt honors the partial-batch rule (only cancel when every key in an in-flight chunk is unobserved) and re-checks isObserved per key.
• Removed subscribeDocument / subscribeQuery from the DocumentStore interface and store.ts (cancellation is automatic now).
• useDocument / useQuery remain pure reactive reads — no useEffect, no imperative subscription.
• Rewrote tests/cancellation.test.ts to drive cancellation via observation, and added tests/react/cancellation.test.tsx for mount/unmount auto-cancel coverage.
• Updated the silo README "Cancellation" section + changesets.

Acceptance

• Unmounting the last observer interrupts the in-flight fetch after gcTimeMs; a surviving observer keeps it alive; partial-batch rule honored.
• A quick remount within gcTimeMs does not cancel.
• useDocument/useQuery contain no useEffect/imperative subscription.
• All five gates green: pnpm test (654), test:validate, typecheck, lint, format.
• silo src/ coverage 100% (finder/store/transitions incl. all cancellation branches); kernel system.ts ~98% (residual = upstream alien-signals graph internals, /* c8 ignore */ + justification).
• Perf — running pnpm perf:stats baseline vs optimized; will post results. (Note: the js-krauset prod build needed two pre-existing, unrelated fixes to run here — a gitignored bootstrap.min.css placeholder, and an alias-ordering bug where @supergrain/kernel matched before @supergrain/kernel/react; the latter is included.)

🤖 Generated with Claude Code

---

Generated by Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 99.16667% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.81%. Comparing base (1f9dba2) to head (49a5b0e).

Files with missing lines	Patch %	Lines
packages/kernel/src/system.ts	99.12%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@                       Coverage Diff                        @@
##           claude/relaxed-johnson-fEGH6      #84      +/-   ##
================================================================
- Coverage                         99.92%   99.81%   -0.12%     
================================================================
  Files                                33       34       +1     
  Lines                              1359     1595     +236     
  Branches                            283      324      +41     
================================================================
+ Hits                               1358     1592     +234     
- Partials                              1        3       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[scottmessinger]

Perf gate: no regression ✅

pnpm perf:stats on each side (packages/js-krauset), then perf:compare. Baseline = this branch with packages/kernel/src reverted to the #82 state (imports alien-signals directly); optimized = the owned system.ts.

baseline (8 runs) vs optimized (8 runs)

Benchmark                       baseline     optimized      diff   noise±%
─────────────────────────────────────────────────────────────────────────
create rows (1k)                 100.2ms        98.5ms     -1.8%    ±13.2
replace all rows                 106.3ms       111.5ms     +4.9%    ±5.5
partial update (10th)            217.8ms       209.9ms     -3.6%    ±14.2
select row                        14.9ms        14.1ms     -5.5%    ±8.2
swap rows                         63.6ms        67.0ms     +5.4%    ±8.5
create many rows (10k)          1281.9ms      1286.2ms     +0.3%    ±1.8
append rows (1k to 1k)           108.6ms       118.3ms     +9.0%    ±10.5
clear rows                        80.1ms        83.6ms     +4.4%    ±3.8
─────────────────────────────────────────────────────────────────────────
TOTAL (weighted, Krause)          1068.0        1074.8     +0.6%

Read: every per-benchmark delta is within (or below) that benchmark's own run-to-run stddev (the noise±% column = baseline stddev/mean), and the mix of +/- deltas with a +0.6% weighted total is noise, not signal. This matches the design: the operator layer is a line-for-line port of alien-signals 3.x, and the only additions (the link/unwatched observation hooks) are gated behind counters that stay 0 when no observation handler is registered — js-krauset never touches silo, so it never registers one.

Caveat per CLAUDE.md: this ran in a shared cloud container with CPU throttling, so absolute variance is higher and I used 8 runs/side rather than 15. The weighted total and the stddev bands are unambiguous about there being no regression, but a confirmation pass on a quiet machine (pnpm perf:stats baseline 15 / optimized 15) is worthwhile before merge.

Also functionally validated through the real prod bundle: js-krauset correctness pnpm test → 10/10 with the owned reactive system.

Note: running the benchmark here needed two pre-existing, unrelated js-krauset build fixes — a placeholder for the gitignored css/bootstrap/dist/css/bootstrap.min.css (local only, not committed), and an alias-ordering fix in vite.config.ts where @supergrain/kernel matched before @supergrain/kernel/react (committed).

---

Generated by Claude Code

[scottmessinger]

Perf validation (rigorous pass): no significant difference ✅

Following up on the earlier 8×8 with a fuller run — and after the latest commit removed the link wrapper entirely (the hot read/write path now calls baseLink directly; the only residual delta vs baseline is one gated if (observerCount !== 0) in unwatched, which is skipped for js-krauset since it never registers an observer).

Method: pnpm perf:stats baseline 15 (kernel reverted to the #82 state — imports alien-signals directly) and pnpm perf:stats optimized 15 (this branch), then perf:compare + a Welch's t-test per benchmark (n=15 each).

baseline (15) vs optimized (15)

Benchmark                       baseline   optimized    diff      t      p    sig?
──────────────────────────────────────────────────────────────────────────────────
create rows (1k)                  76.2ms      77.7ms   +2.0%   0.66  0.518   no
replace all rows                  90.5ms      90.9ms   +0.4%   0.17  0.865   no
partial update (10th)            151.1ms     147.7ms   -2.2%  -0.42  0.679   no
select row                        12.1ms      11.6ms   -3.6%  -0.59  0.562   no
swap rows                         47.2ms      44.3ms   -6.2%  -1.04  0.308   no
create many rows (10k)          1110.9ms    1092.1ms   -1.7%  -1.36  0.187   no
append rows (1k to 1k)            85.5ms      90.4ms   +5.8%   1.81  0.083   no
clear rows                        63.0ms      63.3ms   +0.6%   0.25  0.803   no
──────────────────────────────────────────────────────────────────────────────────
TOTAL (weighted, Krause)           888.0       879.3   -1.0%

Read: no benchmark reaches significance at α=0.05 (nearest is append-1k, p=0.083); the deltas are a mix of + and − and the weighted total is −1.0% (optimized nominally faster this run, vs +0.6% last session — the sign flipping across sessions is the tell that this is noise). This is the expected null result for a faithful operator port with a zero-overhead hot path.

Caveat unchanged: shared cloud container, so absolute times drift between sessions (create-1k was ~100ms last session, ~76ms now). The t-test controls for within-session variance; a final confirmation on a quiet machine is still worth doing pre-merge, but there is no evidence of regression.

---

Generated by Claude Code