Migrate @supergrain/silo network/async layer to Effect + upgrade reactive core to alien-signals 3.x

[scottmessinger]

Summary

Two coordinated changes:

1. @supergrain/silo — rebuild the network/async layer on an internal Effect engine and remodel its reactive handle. Effect-powered, Promise-first at the boundary. Breaking for silo (→ v5).
2. @supergrain/kernel — upgrade the reactive core alien-signals 2.0.7 → 3.2.1. Breaking for kernel (effect cleanup semantics).

Principle: the engine gets structured concurrency, typed errors, retry/timeout, deterministic time; consumers get a plain Promise API, with Effect as an opt-in for power users.

@supergrain/silo

Promise-first adapters with an abort signal.

interface DocumentAdapter {
  find(ids: string[], ctx?: { signal: AbortSignal }):
    Promise | Effect.Effect;
}

• Return a Promise (common case) — the store runs it on its Effect engine and turns a rejection into a typed AdapterError. Thread ctx.signal into fetch(url, { signal }) for a real network abort, or ignore it.
• Return an Effect (opt-in) — used as-is, with native interruption / typed errors / resources.

Engine, fully on Effect. Batch window on Effect.sleep; per-chunk fan-out via Effect.forEach; per-model retry (Schedule) / timeout (Duration); typed AdapterError/NotFoundError/ProcessorError (SiloError); exhaustive applyEvent statechart. The whole pipeline is on Effect's clock — deterministic under TestClock.

Hooks are pure reactive reads. useDocument / useQuery are return store.find(...) / return store.findQuery(...) — no useEffect, no imperative subscription, no JSON.stringify. They return a stable reactive handle and the tracked component re-renders on the fields it reads.

Fetch cancellation is an opt-in capability (for now). Each chunk runs on its own interruptible fiber. store.subscribeDocument(type, id) / store.subscribeQuery(type, params) ref-count interest and return an unsubscribe fn; when the last subscriber for every key in an in-flight chunk leaves, the fetch is interrupted (aborting the signal) and its handles reset to idle (a new Abort statechart event) so renewed interest refetches. gcTimeMs (default 0 = next tick) defers the interrupt. The hooks deliberately don't auto-wire this — true "cancel when a handle has no reactive observers" needs a kernel observation primitive that doesn't exist yet. Tracked in #83 (signals-native auto-cancel as a focused follow-up on top of the 3.x core).

Handle is a status-discriminated union over flat fields:

type DocumentHandle =
  | { status: "pending"; value: undefined; error: undefined; fetchedAt: undefined; isFetching: boolean; promise }
  | { status: "success"; value: T; error: E | undefined; fetchedAt: Date; isFetching: boolean; promise }  // refetch error coexists
  | { status: "error"; value: undefined; error: E; fetchedAt: undefined; isFetching: boolean; promise };

Narrowing on status (or value !== undefined) refines value to T. error/value coexist in success (stale-while-revalidate); isFetching is orthogonal so a background refetch doesn't flip status or re-render value readers. One stable reactive object, per-field tracking.

@supergrain/kernel — alien-signals 3.x

• Breaking — effect cleanup semantics. effect(fn) (re-exported from @supergrain/kernel, and the engine behind useSignalEffect) now treats fn's return value as a cleanup function (runs before each re-run and on dispose), matching React's useEffect model. A callback that returns a non-function value throws "cleanup is not a function" on its next run — read signals for subscription with a statement body or void: effect(() => void store.count). useSignalEffect now accepts () => void | (() => void) and wires the cleanup to the component lifecycle.
• Internal rename. getCurrentSub/setCurrentSub → getActiveSub/setActiveSub (renamed throughout; @supergrain/kernel/internal re-exports the new names). ReactiveNode now imported from alien-signals/system. No change to the public package-root API.
• All reactive semantics (fine-grained tracking, batching, Map/Set notification coalescing) unchanged.

@supergrain/queries

QueryAdapter.fetch returns Promise | Effect; create-query normalizes both before its backoff loop. Pagination/reactivity unchanged.

@supergrain/husk

Reverted to the original Promise-based reactivePromise/reactiveTask. Drops the effect dependency.

Verification

• pnpm test: 621 passed (51 files) — incl. kernel 175 · mill 52 · husk 52 · silo 185
• pnpm run test:validate ✅ (5) · repo-wide typecheck ✅ · lint 0 errors ✅ · format ✅
• silo executable src/ coverage 100% (finder/store/transitions), incl. all cancellation branches
• Tests: cancellation.test.ts (subscriber-gating, partial-batch, re-subscribe, refetch, signal-ignored discard, query cancellation, ref-count + evicted-handle/bucket edges) and test-clock.test.ts (TestClock-driven batch window)
• Pre-existing: the js-krauset benchmark prod build fails on a missing bootstrap.min.css asset (unrelated; not run by root pnpm test)

Migration (silo consumers)

handle.data → handle.value; handle.isPending → handle.value === undefined && handle.isFetching; handle.hasData → handle.value !== undefined; status literals are lowercase. Promise adapters keep working as-is; add { signal } only if you want wire-level abort.

Follow-up

• Kernel observation primitive (onUnobserved) → signals-native fetch cancellation in silo #83 — kernel observation primitive (onUnobserved) → signals-native auto-cancellation in silo (replaces the opt-in subscribe* capability).

https://claude.ai/code/session_016FNH6xY9sFPmBaThUcHPAc

[codecov]

Codecov Report

❌ Patch coverage is 99.27007% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 99.92%. Comparing base (a8a0c30) to head (1f9dba2).

Files with missing lines	Patch %	Lines
packages/queries/src/create-query.ts	85.71%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##              main      #82      +/-   ##
===========================================
- Coverage   100.00%   99.92%   -0.08%     
===========================================
  Files           31       33       +2     
  Lines         1312     1359      +47     
  Branches       256      283      +27     
===========================================
+ Hits          1312     1358      +46     
- Partials         0        1       +1     

☔ 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.