@nimbus-sh/fabric 0.1.0 → 0.3.0

package/src/bindings.ts

@@ -25,11 +25,11 @@
 
 import { WorkerEntrypoint } from 'cloudflare:workers';
 import { z } from 'zod/v4';
-import { disposeRpcResource, useRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
-import { supervisorEntrypoint, supervisorEntrypointName } from './ctx-exports.js';
-import { requireStagedBootAssembler } from './process-fabric.js';
-import { assertModuleMapWithinCodeLimit } from './workerd-facet-host.js';
-import type { EntrypointLoopbackFactory } from './ctx-exports.js';
+import { disposeRpcResource, useRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { supervisorEntrypoint, supervisorEntrypointName } from './composition.js';
+import { stagedBootAssembler } from './composition.js';
+import { assertModuleMapWithinCodeLimit } from './budgets.js';
+import type { EntrypointLoopbackFactory } from './composition.js';
 import type { WorkerCode } from './vendor/types.js';
 
 /**
@@ -578,7 +578,7 @@ export class NimbusLoadedEntrypoint extends WorkerEntrypoint<NimbusLoaderShimEnv
       // alive.
       const stage = props.stage;
       outerStub = outerLoader.get(props.key, async () => {
-        const assembled = await requireStagedBootAssembler()(this.env, stage);
+        const assembled = await stagedBootAssembler()(this.env, stage);
         assertModuleMapWithinCodeLimit(
           (assembled as { modules?: Record<string, unknown> }).modules ?? {},
         );

package/src/budgets.ts

@@ -0,0 +1,308 @@
+/**
+ * budgets.ts — per-DO accounting for the platform budgets the fabric spends:
+ * the Worker Loader's two caps, the facet-ID lifetime budget, and the
+ * dynamic-worker module-map ceiling.
+ *
+ * Measured on production workerd: a Durable Object admits ~5–6 concurrent
+ * dynamic workers before the platform refuses with "Too many concurrent
+ * dynamic workers", one DO method can drive at most 4 concurrent Loader
+ * fetches, and loader-cache entries are never released — every DISTINCT
+ * `loader.get(id)` permanently consumes one of the dynamic-worker slots for
+ * the object's lifetime. Nimbus stays under the caps by construction
+ * (`IN_DO_THRESHOLD` = 5 in the fanout pool), which until now meant the slots
+ * were counted in prose. This ledger counts them at the fabric's loader call
+ * sites instead — the loader pool's slots, a resident process's keyed worker,
+ * a one-shot's load — so proximity is measurable and a cap failure can name
+ * the ids actually holding slots.
+ *
+ * Measurement only: no admission control. The caps are the platform's, they
+ * are approximate ("~5–6"), and a gate on an approximate number would refuse
+ * work the platform would have run.
+ *
+ * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
+ * caps are per Durable Object, and dynamic workers die with the isolate that
+ * loaded them, so a ledger that goes away with its host describes nothing
+ * that still exists.
+ */
+
+import { classifyError } from '@nimbus-sh/platform/oom-classify.js';
+
+interface LoaderLedger {
+  /** Distinct loader ids ever gotten — each one a permanently consumed slot. */
+  ids: Set<string>;
+  /** In-flight calls into dynamic workers, right now. */
+  liveFetches: number;
+  /** The most that were ever in flight at once. */
+  peakLiveFetches: number;
+}
+
+const ledgers = new WeakMap<object, LoaderLedger>();
+
+function ledger(ctx: object): LoaderLedger {
+  let entry = ledgers.get(ctx);
+  if (!entry) {
+    entry = { ids: new Set(), liveFetches: 0, peakLiveFetches: 0 };
+    ledgers.set(ctx, entry);
+  }
+  return entry;
+}
+
+/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
+export function recordLoaderId(ctx: object, id: string): void {
+  ledger(ctx).ids.add(id);
+}
+
+/**
+ * Count one call into a dynamic worker as a live Loader fetch; the returned
+ * function ends it (idempotently), from the caller's own `finally`.
+ *
+ * A begin/end pair rather than a wrapper on purpose, and the shape is
+ * load-bearing: wrapping the stub call in a ledger-owned async frame
+ * (`trackLoaderFetch(ctx, () => entrypoint.execute(...))`) left the hosting
+ * Durable Object poisoned after every pooled dispatch — the next fabric
+ * activity hung the object or reset the instance outright (pid base jumped,
+ * every attached WebSocket dropped with no close frame), measured 7/7 on
+ * staging and gone 3/3 with the direct call restored. Same seam-quirk class
+ * as pipelined `fetch.call`, which workerd refuses for dynamically-loaded
+ * workers: an RPC stub call must stay a direct property call awaited by the
+ * frame that made it, so the ledger only brackets it.
+ */
+export function beginLoaderFetch(ctx: object): () => void {
+  const entry = ledger(ctx);
+  entry.liveFetches++;
+  entry.peakLiveFetches = Math.max(entry.peakLiveFetches, entry.liveFetches);
+  let ended = false;
+  return () => {
+    if (ended) return;
+    ended = true;
+    entry.liveFetches--;
+  };
+}
+
+/** Snapshot for the diag surface. Pure read; no I/O. */
+export function loaderLedgerStats(ctx: object): {
+  idsEverGotten: string[];
+  liveFetches: number;
+  peakLiveFetches: number;
+} {
+  const entry = ledger(ctx);
+  return {
+    idsEverGotten: [...entry.ids],
+    liveFetches: entry.liveFetches,
+    peakLiveFetches: entry.peakLiveFetches,
+  };
+}
+
+/**
+ * Name the per-DO accounting on a "Too many concurrent dynamic workers"
+ * failure; hand every other error back untouched. The platform's message
+ * says only that the cap was hit — which ids hold the slots, and that a
+ * keyed id can never give one back, is what the operator needs to know to
+ * shrink anything.
+ */
+export function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error {
+  if (classifyError(error) !== 'dynamic_worker_cap') return error;
+  const entry = ledger(ctx);
+  const platform = error instanceof Error ? error.message : String(error);
+  return new Error(
+    `${platform} — this Durable Object has ${entry.ids.size} loader id(s) permanently `
+      + `holding dynamic-worker slots (a loader.get id is never released): `
+      + `${[...entry.ids].join(', ') || '(none recorded)'}; live Loader fetches ${entry.liveFetches}, `
+      + `peak ${entry.peakLiveFetches}`,
+    { cause: error },
+  );
+}
+
+// ── Dynamic-worker module-map ceiling ───────────────────────────────────────
+
+/**
+ * Total bytes a dynamic Worker's module map may carry, across every member of
+ * it. A hard platform limit, not a policy knob: 62 MiB lands and 64 MiB is
+ * refused with "Dynamic Worker code size (N bytes) exceeds the maximum allowed
+ * size of 67108864 bytes", confirmed at five sizes with two trials each. The
+ * budget is shared, so a ruby process is already 34.3 MiB down before its disk
+ * is counted.
+ */
+export const DYNAMIC_WORKER_CODE_LIMIT_BYTES = 67_108_864;
+
+/**
+ * Refuse a module map over {@link DYNAMIC_WORKER_CODE_LIMIT_BYTES}, naming
+ * the largest members. The platform's own refusal reports one number for a
+ * budget shared across every member of the map, which tells the operator
+ * nothing about WHAT to shrink — so every fabric seam that assembles a map
+ * runs this before the loader sees it.
+ *
+ * Costed to its two paths. Under the ceiling: one length read per member —
+ * UTF-16 code units for text, which equal UTF-8 bytes for the ASCII module
+ * text the generators emit and undercount otherwise; the platform's own
+ * refusal still backstops the exotic case, because this check exists to name
+ * members, not to be the ceiling. Over it: exact UTF-8 sizes, computed only
+ * then, sorted so the biggest lever is first.
+ */
+export function assertModuleMapWithinCodeLimit(modules: Record<string, unknown>): void {
+  let estimate = 0;
+  for (const content of Object.values(modules)) {
+    estimate += memberBytes(content, null);
+  }
+  if (estimate <= DYNAMIC_WORKER_CODE_LIMIT_BYTES) return;
+
+  const encoder = new TextEncoder();
+  const sized = Object.entries(modules)
+    .map(([name, content]) => ({ name, bytes: memberBytes(content, encoder) }))
+    .sort((a, b) => b.bytes - a.bytes);
+  const total = sized.reduce((sum, member) => sum + member.bytes, 0);
+  const top = sized.slice(0, 5)
+    .map(({ name, bytes }) => `'${name}' (${bytes.toLocaleString('en-US')} bytes)`)
+    .join(', ');
+  throw new Error(
+    `Nimbus: dynamic-worker module map is ${total.toLocaleString('en-US')} bytes, over the `
+      + `${DYNAMIC_WORKER_CODE_LIMIT_BYTES.toLocaleString('en-US')}-byte platform ceiling shared by `
+      + `every member. Largest members: ${top}`,
+  );
+}
+
+/**
+ * Bytes one module-map member carries, across the loader's content kinds
+ * (plain string, `{ js | cjs | py | text }`, `{ wasm | data }`). With an
+ * encoder, text is measured exactly; without one, by code-unit length.
+ */
+function memberBytes(content: unknown, encoder: TextEncoder | null): number {
+  const textBytes = (text: string): number =>
+    encoder ? encoder.encode(text).byteLength : text.length;
+  if (typeof content === 'string') return textBytes(content);
+  if (content !== null && typeof content === 'object') {
+    for (const value of Object.values(content)) {
+      if (typeof value === 'string') return textBytes(value);
+      if (value instanceof ArrayBuffer) return value.byteLength;
+      if (ArrayBuffer.isView(value)) return value.byteLength;
+    }
+  }
+  return 0;
+}
+
+// ── Facet-ID lifetime budget ────────────────────────────────────────────────
+
+/**
+ * Facet IDs a Durable Object is granted over its LIFETIME. Append-only and
+ * never reclaimed, so crossing it is unrecoverable for the object — which is
+ * why the ledger below counts consumption durably instead of leaving the
+ * bound as prose the slot book merely respects.
+ */
+export const FACET_ID_LIFETIME_BUDGET = 65_536;
+
+/** Where the ledger persists the count of facet names ever minted. */
+export const FACET_NAME_HIGH_WATER_KEY = 'fabric_facet_name_high_water';
+
+/** The slice of storage the facet-name ledger persists through. */
+interface FacetNameLedgerStorage {
+  storage: {
+    get(key: string): Promise<unknown> | unknown;
+    put(key: string, value: unknown): Promise<void>;
+  };
+}
+
+/**
+ * One hosting actor's durable facet-name count, as an adopt-then-advance
+ * chain. It starts as the read of {@link FACET_NAME_HIGH_WATER_KEY} and
+ * every later link writes only a LARGER count — a fresh incarnation restarts
+ * its slot cursor at zero, and a write that had not adopted first would
+ * clobber the lifetime count down to this incarnation's. The chain never
+ * rejects.
+ */
+interface FacetNameLedger {
+  chain: Promise<number>;
+  /** The largest count the chain has adopted or durably written. */
+  known: number;
+  /** The largest count ever recorded this incarnation, durable or not. */
+  minted: number;
+}
+
+const facetNameLedgers = new WeakMap<object, FacetNameLedger>();
+
+function facetNameLedger(ctx: FacetNameLedgerStorage): FacetNameLedger {
+  let ledger = facetNameLedgers.get(ctx);
+  if (!ledger) {
+    const created: FacetNameLedger = { chain: Promise.resolve(0), known: 0, minted: 0 };
+    created.chain = Promise.resolve(ctx.storage.get(FACET_NAME_HIGH_WATER_KEY))
+      .then((value) => (typeof value === 'number' ? value : 0))
+      .catch(() => 0)
+      .then((adopted) => {
+        created.known = Math.max(created.known, adopted);
+        return adopted;
+      });
+    ledger = created;
+    facetNameLedgers.set(ctx, ledger);
+  }
+  return ledger;
+}
+
+/**
+ * Advance the durable ledger to this incarnation's name count, if it is a new
+ * lifetime high. Chained behind adoption so the comparison is always against
+ * the real persisted value; a failed write leaves the old link's count and the
+ * next mint tries again — the ledger may transiently undercount, never over.
+ */
+export function recordFacetNameMinted(ctx: FacetNameLedgerStorage, count: number): void {
+  const ledger = facetNameLedger(ctx);
+  ledger.minted = Math.max(ledger.minted, count);
+  ledger.chain = ledger.chain.then(async (durable) => {
+    if (count <= durable) return durable;
+    try {
+      await ctx.storage.put(FACET_NAME_HIGH_WATER_KEY, count);
+    } catch {
+      return durable;
+    }
+    ledger.known = Math.max(ledger.known, count);
+    return count;
+  });
+}
+
+/** The best count available without awaiting storage: minted or adopted. */
+export function facetNameCount(ctx: FacetNameLedgerStorage): number {
+  const ledger = facetNameLedger(ctx);
+  return Math.max(ledger.known, ledger.minted);
+}
+
+/** The count with adoption awaited, for a first failure on a fresh boot. */
+export async function facetNameCountDurable(ctx: FacetNameLedgerStorage): Promise<number> {
+  const ledger = facetNameLedger(ctx);
+  const durable = await ledger.chain;
+  return Math.max(durable, ledger.minted);
+}
+
+/**
+ * The lifetime facet-ID ledger: how many facet names this fabric has ever
+ * minted on the Durable Object, against the 65,536 the platform will ever
+ * grant it. `consumed` only ever counts FIRST uses — a reused name, in this
+ * incarnation or any earlier one, cost no new ID, which is the slot book's
+ * whole reason to exist. Surfaced so an operator can see proximity to a wall
+ * whose crossing is unrecoverable, instead of discovering it from the
+ * platform's opaque failure.
+ */
+export async function facetIdBudget(
+  ctx: FacetNameLedgerStorage,
+): Promise<{ consumed: number; budget: number }> {
+  return {
+    consumed: await facetNameCountDurable(ctx),
+    budget: FACET_ID_LIFETIME_BUDGET,
+  };
+}
+
+/**
+ * Name the facet-ID budget on a creation failure at the wall; below it, hand
+ * the error back untouched. Exhaustion is the one failure here the platform
+ * reports opaquely AND that no teardown, retry or reset can undo, so the
+ * ledger — the only witness to the real cause — does the naming. Not a
+ * threshold: the comparison is against the budget itself.
+ */
+export function withFacetBudgetNamed(consumed: number, error: unknown): unknown {
+  if (consumed < FACET_ID_LIFETIME_BUDGET) return error;
+  const platform = error instanceof Error ? error.message : String(error);
+  return new Error(
+    `Nimbus: facet creation failed with this Durable Object's `
+      + `${FACET_ID_LIFETIME_BUDGET.toLocaleString('en-US')} facet-ID lifetime budget consumed `
+      + `(${consumed} facet names ever created). Facet IDs are append-only and never reclaimed, `
+      + `so this failure is permanent for the object: ${platform}`,
+    { cause: error },
+  );
+}

package/src/composition.ts

@@ -0,0 +1,16 @@
+// Core and fabric share one holder without introducing a dependency cycle.
+export {
+  adoptCtxExports,
+  composeFabric,
+  getCtxExports,
+  stagedBootAssembler,
+  supervisorEntrypoint,
+  supervisorEntrypointName,
+} from '@nimbus-sh/platform/composition.js';
+
+export type {
+  CtxExports,
+  EntrypointLoopbackFactory,
+  FabricComposition,
+  StagedBootAssembler,
+} from '@nimbus-sh/platform/composition.js';

package/src/connections.ts

@@ -0,0 +1,140 @@
+/**
+ * connections.ts — typed, validated, hibernation-durable per-connection
+ * state over the WebSocket attachment.
+ *
+ * Specified from Proteus's DeviceSocketHub (`cf-backend/src/user/device-hub.ts`)
+ * and CLI rpc gate (`cf-backend/src/cli/rpc-gate.ts`), which split the
+ * pattern into its two halves:
+ *   - a TAG is the immutable-at-accept lookup key and authorization — it
+ *     rides the hibernation state, which is why the rpc gate persists auth
+ *     scopes as a tag: "an in-memory allowlist would silently widen to full
+ *     access on wake". That is a security property, and it is why this
+ *     module keeps NO in-memory mirror: `ctx.getWebSockets` is the only
+ *     source of truth for liveness, re-derived on every read.
+ *   - the ATTACHMENT is the mutable per-connection payload. It outlives the
+ *     code that wrote it — it survives deploys — so what a previous version
+ *     wrote is untrusted input, and every read is schema-validated, never
+ *     cast (device-hub.ts:49-53).
+ *
+ * Two platform facts the wrapper enforces where the consumer only documents:
+ *   - attachments are STRUCTURED-CLONED, not JSON-encoded: a Set survives as
+ *     a Set and silently fails an array schema on read (proven by Proteus's
+ *     workerd test, do-socket-attachment.test.ts). Validating on WRITE turns
+ *     that silent read-side null into a loud write-side error.
+ *   - the bound is {@link WS_ATTACHMENT_LIMIT_BYTES} (16,384) on the
+ *     SERIALIZED bytes — workerd re-serializes on every set to check it
+ *     (web-socket.h, MAX_ATTACHMENT_SIZE). A JSON-length measurement is an
+ *     approximation, so this module never pre-refuses on it; it lets the
+ *     platform be the ceiling and NAMES the failure honestly when it trips.
+ *
+ * Reconnect replaces: accepting a socket under a key closes every open
+ * socket already holding that key (1000, 'replaced by a new connection'),
+ * exactly as the device hub does.
+ */
+
+import { z } from 'zod/v4';
+import { WS_ATTACHMENT_LIMIT_BYTES } from '@nimbus-sh/platform/limits.js';
+
+const WS_OPEN = 1;
+
+/** A hibernatable WebSocket, as this module drives it. */
+export interface ConnectionSocket {
+  readyState: number;
+  close(code?: number, reason?: string): void;
+  serializeAttachment(value: unknown): void;
+  deserializeAttachment(): unknown;
+}
+
+/** The hosting actor's hibernation surface. */
+export interface ConnectionsContext {
+  acceptWebSocket(ws: ConnectionSocket, tags?: string[]): void;
+  getWebSockets(tag?: string): ConnectionSocket[];
+  getTags(ws: ConnectionSocket): string[];
+}
+
+/** The per-connection hub of one hosting actor. Cheap accessor; it holds no
+ *  state of its own, which is the point. */
+export function connections<T>(ctx: ConnectionsContext, schema: z.ZodType<T>): Connections<T> {
+  return new Connections(ctx, schema);
+}
+
+export class Connections<T> {
+  constructor(
+    private readonly ctx: ConnectionsContext,
+    private readonly schema: z.ZodType<T>,
+  ) {}
+
+  /**
+   * Accept a socket under an identity key, replacing whatever already holds
+   * it. The attachment validates BEFORE anything else happens, so a rejected
+   * newcomer cannot evict the live connection it failed to replace.
+   */
+  accept(ws: ConnectionSocket, opts: { key: string; tags?: string[]; attachment: T }): void {
+    const validated = this.schema.parse(opts.attachment);
+    for (const old of this.ctx.getWebSockets(opts.key)) {
+      if (old.readyState === WS_OPEN) old.close(1000, 'replaced by a new connection');
+    }
+    this.ctx.acceptWebSocket(ws, [opts.key, ...(opts.tags ?? [])]);
+    this.writeSerialized(ws, validated);
+  }
+
+  /** The open socket holding a tag, re-derived from the platform. */
+  get(tag: string): ConnectionSocket | null {
+    for (const ws of this.ctx.getWebSockets(tag)) {
+      if (ws.readyState === WS_OPEN) return ws;
+    }
+    return null;
+  }
+
+  /** Every open socket (optionally: holding a tag). */
+  list(tag?: string): ConnectionSocket[] {
+    return this.ctx.getWebSockets(tag).filter((ws) => ws.readyState === WS_OPEN);
+  }
+
+  /** A socket's tags — identity key first, then whatever accept added. */
+  tags(ws: ConnectionSocket): string[] {
+    return this.ctx.getTags(ws);
+  }
+
+  /**
+   * The attachment, validated. Null when it does not parse — an attachment
+   * written by a previous deploy is untrusted input, and a null is honest
+   * where a cast would be a lie.
+   */
+  read(ws: ConnectionSocket): T | null {
+    const parsed = this.schema.safeParse(ws.deserializeAttachment());
+    return parsed.success ? parsed.data : null;
+  }
+
+  /** Replace the attachment, validated on the way in. */
+  write(ws: ConnectionSocket, attachment: T): void {
+    this.writeSerialized(ws, this.schema.parse(attachment));
+  }
+
+  private writeSerialized(ws: ConnectionSocket, validated: T): void {
+    try {
+      ws.serializeAttachment(validated);
+    } catch (e) {
+      const approx = jsonLength(validated);
+      throw new Error(
+        `fabric: WebSocket attachment refused by the platform — the bound is `
+          + `${WS_ATTACHMENT_LIMIT_BYTES.toLocaleString('en-US')} bytes of SERIALIZED attachment `
+          + `(workerd MAX_ATTACHMENT_SIZE), and this value is ~${approx.toLocaleString('en-US')} bytes `
+          + `as JSON text (an approximation; the serialized form is what counts): ${errorText(e)}`,
+        { cause: e },
+      );
+    }
+  }
+}
+
+function jsonLength(value: unknown): number {
+  try {
+    return JSON.stringify(value)?.length ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/derived.ts

@@ -0,0 +1,135 @@
+/**
+ * derived.ts — a watermark memo: derive a cheap key, compare, rebuild only
+ * on change.
+ *
+ * Proteus's ActorAgent hand-rolls this pair four times — cached value plus
+ * cached key, compared and rebuilt inline: the system prompt (key composed
+ * from soul text, executors, model, tools, stance), the tool set (keyed
+ * partly on `_craftCacheKey()`, two synchronous SQLite aggregates), the MCP
+ * tool surface (keyed on UserDO's `mcp_updated_at`), and the SOUL text
+ * (no key at all — push-invalidated by `setSoul`). The consumer port moved
+ * the prompt and tool-set pairs onto `derived` cleanly; the MCP pair needs
+ * the per-call context and the hooks; the SOUL pair cannot move at all.
+ *
+ * The SOUL pair names this module's limit: a value LOADED asynchronously
+ * (an awaited file read at turn start) but READ synchronously (the prompt
+ * builder consults what is already in memory). Neither variant expresses
+ * that split — `derived` cannot await the load, `derivedAsync` cannot serve
+ * a synchronous read — so an async-load/sync-read snapshot stays a
+ * hand-rolled field with a push invalidation.
+ *
+ * `derived` is synchronous end to end, because its consumers are: Think
+ * calls `getSystemPrompt(): string` synchronously, and nothing synchronous
+ * may await — the init-gate rule. `derivedAsync` exists because ONE consumer
+ * call site needs it: the MCP surface awaits a cross-DO RPC for both the
+ * watermark and the build, and its proven failure policy is stale-on-error —
+ * a watermark or build failure serves the last good value without touching
+ * the stored key, and only surfaces when there is no value to serve.
+ *
+ * `invalidate()` is the push half the SOUL memo proved: an out-of-band write
+ * (`setSoul`) clears the memo so the next read rebuilds under an unchanged
+ * watermark.
+ */
+
+export interface Derived<T, C = void> {
+  /**
+   * `context` reaches the watermark and the build of THIS call — the seam
+   * for per-call state (a stub, a caller identity, a work mode). The memo
+   * stores one value; the watermark must cover everything the build reads,
+   * context included, or a context change serves another context's value.
+   */
+  get(context: C): T;
+  /** Force the next get to rebuild, watermark unchanged. */
+  invalidate(): void;
+}
+
+/**
+ * The consumer's logging seams. Both MCP logs the port could not express:
+ * `onRebuild` fires after a build stores (the "rebuilt @ wm=N" line), and
+ * `onStale` — async only — fires when a failure serves the stale value,
+ * the one path where the error is otherwise absorbed. A surfaced error
+ * (nothing stale to serve) reports itself.
+ */
+export interface DerivedHooks {
+  /** After a build stores. `previousKey` is undefined on the first build. */
+  onRebuild?(previousKey: string | number | undefined, nextKey: string | number): void;
+}
+
+export interface DerivedAsyncHooks extends DerivedHooks {
+  /** A watermark or build failure just served the stale value. */
+  onStale?(error: unknown): void;
+}
+
+export function derived<T, C = void>(
+  watermark: (context: C) => string | number,
+  build: (context: C, key: string | number) => T,
+  hooks: DerivedHooks = {},
+): Derived<T, C> {
+  let key: string | number | undefined;
+  let value: T | undefined;
+  let has = false;
+  return {
+    get(context: C): T {
+      const next = watermark(context);
+      if (has && next === key) return value as T;
+      value = build(context, next);
+      hooks.onRebuild?.(key, next);
+      key = next;
+      has = true;
+      return value;
+    },
+    invalidate(): void {
+      has = false;
+      value = undefined;
+    },
+  };
+}
+
+export interface DerivedAsync<T, C = void> {
+  get(context: C): Promise<T>;
+  invalidate(): void;
+}
+
+export function derivedAsync<T, C = void>(
+  watermark: (context: C) => Promise<string | number>,
+  build: (context: C, key: string | number) => Promise<T>,
+  hooks: DerivedAsyncHooks = {},
+): DerivedAsync<T, C> {
+  let key: string | number | undefined;
+  let value: T | undefined;
+  let has = false;
+  return {
+    async get(context: C): Promise<T> {
+      let next: string | number;
+      try {
+        next = await watermark(context);
+      } catch (e) {
+        if (has) {
+          hooks.onStale?.(e);
+          return value as T;
+        }
+        throw e;
+      }
+      if (has && next === key) return value as T;
+      let built: T;
+      try {
+        built = await build(context, next);
+      } catch (e) {
+        if (has) {
+          hooks.onStale?.(e);
+          return value as T;
+        }
+        throw e;
+      }
+      value = built;
+      hooks.onRebuild?.(key, next);
+      key = next;
+      has = true;
+      return built;
+    },
+    invalidate(): void {
+      has = false;
+      value = undefined;
+    },
+  };
+}