@nimbus-sh/platform 0.1.0 → 0.3.0

package/README.md

@@ -4,32 +4,166 @@
 > cloud OS. This README is edited and maintained with Claude (AI) and
 > presented as-is.
 
-The zero-dependency leaf under
-[`@nimbus-sh/core`](https://www.npmjs.com/package/@nimbus-sh/core) and
-[`@nimbus-sh/fabric`](https://www.npmjs.com/package/@nimbus-sh/fabric): the
-measured Cloudflare platform truths both are built on, separated from the
-policy Nimbus layers on top of them.
-
-- `limits.js` — the measured limits tables: storage-transaction bounds, the
-  RPC payload envelope, and the supervisor memory budgets. Each constant's doc
-  comment carries the measurement that set it.
-- `oom-classify.js` / `oom-discriminator.js` — the error taxonomy for isolates
-  that die without throwing: OOM vs CPU reset vs transient DO reset vs
-  overload, and the failure ring that attributes them after the fact.
+The measured limits of the Cloudflare Workers platform, and a classifier for
+the failures workerd reports only as prose.
+
+Some Workers failures give you nothing to branch on. A Durable Object call
+comes back with the words `internal error`. An isolate dies without throwing.
+A write past a cap resets the object instead of failing. This package holds
+the numbers those failures happen at, and the matchers that name a caught
+error. No call site has to string-match its own.
+
+Use it if you write Workers or Durable Object code. It answers whether to
+retry a failed call, and what the limit is before you write past it. It has
+no runtime dependencies and imports nothing from `cloudflare:`, so it loads
+in workerd,
+bun, and node.
+
+## Install
+
+```bash
+npm install @nimbus-sh/platform
+```
+
+## Retry or fail
+
+`classifyDoCall` reads a failed Durable Object call and returns one class.
+It walks the cause chain, because a wrapper error drops the runtime's
+`.retryable` property and only the joined prose survives. `isRetryableDoCall`
+says which classes a retry may act on.
+
+```ts
+import { classifyDoCall, isRetryableDoCall, describeError } from '@nimbus-sh/platform';
+
+export async function callWithRetry<T>(call: () => Promise<T>, attempts = 3): Promise<T> {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      // Mint a fresh stub inside `call`: a stub that failed once is spent.
+      return await call();
+    } catch (error) {
+      const outcome = classifyDoCall(error);
+      if (attempt >= attempts || !isRetryableDoCall(outcome)) {
+        throw new Error(`${outcome}: ${describeError(error)}`, { cause: error });
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100 * 2 ** attempt));
+    }
+  }
+}
+```
+
+| Class | What happened | Retry |
+|---|---|---|
+| `superseded_isolate` | a deploy replaced the isolate mid-call | yes |
+| `connection_lost` | the stub or storage connection dropped | yes |
+| `storage_reset` | storage reset the object: cold start, live write, or timeout | yes |
+| `retryable_flag` | the runtime flagged the error `retryable` itself | yes |
+| `overloaded` | the object shed the call under queue pressure | never |
+| `permanent` | the call ran and the answer is the error | no |
+
+`overloaded` is checked first and vetoes the rest, because retrying an
+overloaded object is what overloaded it. Cloudflare's own error-handling
+guidance forbids it.
+
+`describeError` gives one line you can log: the error's class, whether the
+text came from a remote isolate, and the condition it classifies as. Reach
+for it wherever you would otherwise write `e?.message ?? String(e)` and get
+back the word `internal error`.
+
+## Naming what died
+
+`classifyError` maps an error, or a bare stderr line, to one cause:
+`sqlite_nomem`, `sqlite_full`, `oom`, `cpu_exceeded`, `clone_refused`,
+`rpc_timeout`, `subrequest_cap`, `dynamic_worker_cap`, `condemnation`,
+`hard_evict`, or `unknown`.
+
+```ts
+import { classifyError } from '@nimbus-sh/platform';
+
+export function remedy(error: unknown): string {
+  switch (classifyError(error)) {
+    case 'sqlite_full':   return 'drain data; reads and DELETEs still work at the wall';
+    case 'sqlite_nomem':  return 'retry with a smaller transaction';
+    case 'clone_refused': return 'ship the payload in slices under the RPC envelope';
+    case 'cpu_exceeded':  return 're-enter the object; yielding inside the turn buys nothing';
+    default:              return 'unclassified: keep the message and widen the rules';
+  }
+}
+```
+
+The split between `sqlite_full` and `sqlite_nomem` carries the remedy. At the
+storage wall, reads and deletes keep working and you drain data; on NOMEM you
+ask for a smaller transaction.
+
+Both `exceededMemory` and `exceededCpu` are uncatchable inside the isolate
+that dies. Only a caller across an RPC boundary sees the message, and
+isolates also vanish with no message at all. A low `cpu_exceeded` count is
+therefore not evidence that CPU was not the cause.
+
+`isTransientDoReset` and `isDoOverloaded` answer those two narrower questions
+on their own.
+
+## Limits
+
+Every constant is a fact about the platform: a hard ceiling, or a measured
+envelope proven safe against one.
+
+```ts
+import { MAX_RPC_SAFE_PAYLOAD_BYTES } from '@nimbus-sh/platform';
+
+export function* slices(bytes: Uint8Array): Generator<Uint8Array> {
+  for (let at = 0; at < bytes.length; at += MAX_RPC_SAFE_PAYLOAD_BYTES) {
+    yield bytes.subarray(at, at + MAX_RPC_SAFE_PAYLOAD_BYTES);
+  }
+}
+```
+
+| Constant | Value | What it bounds |
+|---|---|---|
+| `CHUNK_SIZE` | 65,536 | the storage and wire quantum every other bound is counted in |
+| `MAX_TX_BLOB_BYTES` | 1 MiB | bytes one storage transaction may hold outstanding; the platform resets the object over the turn, not the total |
+| `MAX_TX_LOGICAL_ROWS` / `MAX_TX_SQL_EXECS` | 256 / 64 | rows and execs in that same transaction |
+| `SQLITE_MAX_ROW_BYTES` | 2,000,000 | bytes per ROW, key length included; budget values against the row bound |
+| `SQLITE_MAX_STATEMENT_BYTES` | 100 KiB | SQL text per exec |
+| `SQLITE_MAX_BOUND_PARAMETERS` | 100 | bound parameters per query; a batched insert breaches this first |
+| `DO_STORAGE_LIMIT_BYTES` | 10,000,000,000 | storage per Durable Object, shared by every facet and clone under it, with no copy-on-write credit |
+| `BLOCK_CONCURRENCY_CANCEL_MS` | 30,000 | how long a `blockConcurrencyWhile()` callback may run before the object is reset |
+| `WS_ATTACHMENT_LIMIT_BYTES` | 16,384 | serialized bytes per hibernatable WebSocket attachment |
+| `MAX_RPC_SAFE_PAYLOAD_BYTES` | 28 MiB | bytes to send in one RPC value, under the platform's 32 MiB |
+
+Each constant's doc comment carries the measurement that set it, and says
+whether the value is documented by Cloudflare or probed. `SQLITE_MAX_ROW_BYTES`
+is 2,000,000 against a measured single-value ceiling of 2,199,981 bytes,
+because budgeting a row against the value ceiling would be wrong.
+
+The supervisor budget constants (`SUPERVISOR_HEAP_CEILING_BYTES` and the
+allocation budgets beside it) are Nimbus policy derived from the 128 MiB
+isolate ceiling. They are soft admission targets, and the doc comments say so.
+
+## The rest of the surface
+
 - `heap-estimate.js` / `heavy-alloc-coord.js` / `weighted-credit-pool.js` —
-  the instrumented supervisor heap model and the weighted admission budget
-  behind it.
-- `diag-counters.js` / `install-phase.js` — the deterministic allocation-site
-  counters that replace `process.memoryUsage()` (which returns 0 in a Durable
-  Object), and the phase taxonomy they report.
-- `rpc-dispose.js` — explicit `Symbol.dispose` handling for RPC resources,
-  including on error paths.
+  an instrumented heap model for a supervisor Durable Object, and the
+  weighted admission budget that holds allocations under it.
+  `estimateSupervisorHeap` returns a lower bound, and `HEAP_BLIND_SPOTS`
+  names the allocation sites it cannot see.
+- `diag-counters.js` / `install-phase.js` — deterministic allocation-site
+  counters, because `process.memoryUsage()` returns 0 in a Durable Object,
+  plus the phase taxonomy they report against.
+- `oom-discriminator.js` — the failure ring that attributes a death after the
+  fact: `recordFailure`, `getFailures`, and a snapshot pair that carries the
+  ring across a reset.
+- `rpc-dispose.js` — `disposeRpcResource` and `disposeRpcResources`, explicit
+  `Symbol.dispose` for RPC values, including on error paths.
 - `w7-frame.js` — the incremental typed record format for streamed bulk
-  filesystem writes, and the batch payload types it encodes.
+  filesystem writes, with `encodeWriteBatchStream` and the batch payload
+  types it encodes.
+
+## Related packages
 
-No runtime dependencies, no imports from any other Nimbus package. Everything
-above it — core's filesystem and shell, fabric's Durable Object machinery, the
-worker — consumes this package; nothing here knows about them.
+[`@nimbus-sh/core`](https://www.npmjs.com/package/@nimbus-sh/core) is the
+backend-agnostic OS, and
+[`@nimbus-sh/fabric`](https://www.npmjs.com/package/@nimbus-sh/fabric) is the
+Durable Object machinery. Both are built on the limits and the taxonomy here.
 
 ## License
 

package/dist/composition.d.ts

@@ -0,0 +1,50 @@
+/**
+ * composition.ts — the ONE seam an embedder wires the fabric through.
+ *
+ * The fabric mints supervisor bindings and assembles staged boots for the
+ * programs it hosts, but the entrypoint class that answers those bindings
+ * and the artifact sources a stage names both belong to the embedder. The
+ * embedder states them once, in its composition root, with one call:
+ *
+ *   composeFabric({
+ *     supervisorEntrypoint: 'SupervisorRPC',
+ *     stagedBootAssembler: (env, stage) => assembleConfig(env, stage),
+ *   });
+ *
+ * First-write-wins, like every holder in this module: the composition
+ * root's module scope runs once per isolate, before any request.
+ *
+ * `ctx.exports` is runtime state, not composition: workerd mints it per
+ * instance, so the embedder captures it where the platform hands it over —
+ * the first fetch, or the DO constructor — with {@link adoptCtxExports}.
+ *
+ * This module stays a leaf (no fabric imports) so helpers (notably
+ * isolate-pool.ts) can read `ctx.exports` without transitively importing
+ * the Durable Object classes, which is what lets the pool be unit-tested
+ * in a plain Node/Bun process.
+ */
+export type EntrypointLoopbackFactory = <Stub = unknown>(options: {
+    props: object;
+}) => Stub;
+export type CtxExports = Record<string, EntrypointLoopbackFactory | undefined>;
+export type StagedBootAssembler = (env: unknown, stage: unknown) => Promise<object>;
+export interface FabricComposition {
+    supervisorEntrypoint: string;
+    stagedBootAssembler?: StagedBootAssembler;
+    /** Durable Object namespace binding that owns the workspace. */
+    hostNamespace?: string;
+    /** RPC method the host forwards to workspace.supervisorOp. */
+    hostDispatchMethod?: string;
+}
+export declare const DEFAULT_HOST_NAMESPACE = "NIMBUS_SESSION";
+export declare const DEFAULT_HOST_DISPATCH_METHOD = "supervisorOp";
+/** Composition and loopback exports are first-write-wins for this isolate. */
+export declare function composeFabric(value: FabricComposition): void;
+export declare function adoptCtxExports(value: CtxExports): void;
+export declare function getCtxExports(): CtxExports | null;
+export declare function supervisorEntrypoint(exportsObj?: unknown): EntrypointLoopbackFactory | null;
+export declare function supervisorEntrypointName(): string | null;
+export declare function hostNamespace(): string;
+export declare function hostDispatchMethod(): string;
+export declare function stagedBootAssembler(): StagedBootAssembler;
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAC7F,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC,CAAC;AAC/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEpF,MAAM,WAAW,iBAAiB;IAChC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AACvD,eAAO,MAAM,4BAA4B,iBAAiB,CAAC;AAI3D,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAE5D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAEvD;AAED,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED,wBAAgB,oBAAoB,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,yBAAyB,GAAG,IAAI,CAO3F;AAED,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAExD;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,mBAAmB,IAAI,mBAAmB,CASzD"}

package/dist/composition.js

@@ -0,0 +1,43 @@
+export const DEFAULT_HOST_NAMESPACE = 'NIMBUS_SESSION';
+export const DEFAULT_HOST_DISPATCH_METHOD = 'supervisorOp';
+let composition = null;
+let ctxExports = null;
+/** Composition and loopback exports are first-write-wins for this isolate. */
+export function composeFabric(value) {
+    if (!composition)
+        composition = value;
+}
+export function adoptCtxExports(value) {
+    if (!ctxExports)
+        ctxExports = value;
+}
+export function getCtxExports() {
+    return ctxExports;
+}
+export function supervisorEntrypoint(exportsObj) {
+    const exports = exportsObj ?? ctxExports;
+    const name = composition?.supervisorEntrypoint;
+    if (!name)
+        return null;
+    if ((typeof exports !== 'object' && typeof exports !== 'function') || exports === null)
+        return null;
+    const factory = exports[name];
+    return typeof factory === 'function' ? factory : null;
+}
+export function supervisorEntrypointName() {
+    return composition?.supervisorEntrypoint ?? null;
+}
+export function hostNamespace() {
+    return composition?.hostNamespace ?? DEFAULT_HOST_NAMESPACE;
+}
+export function hostDispatchMethod() {
+    return composition?.hostDispatchMethod ?? DEFAULT_HOST_DISPATCH_METHOD;
+}
+export function stagedBootAssembler() {
+    const assembler = composition?.stagedBootAssembler;
+    if (!assembler) {
+        throw new Error('fabric: no staged-boot assembler composed; a \'staged\' boot spec '
+            + 'cannot be assembled without one (composeFabric)');
+    }
+    return assembler;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/platform",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The measured Cloudflare platform truths Nimbus is built on — error taxonomy, limits tables, budget coordination, and wire-format primitives, with zero runtime dependencies.",
   "keywords": [
     "cloudflare",

package/src/composition.ts

@@ -0,0 +1,87 @@
+/**
+ * composition.ts — the ONE seam an embedder wires the fabric through.
+ *
+ * The fabric mints supervisor bindings and assembles staged boots for the
+ * programs it hosts, but the entrypoint class that answers those bindings
+ * and the artifact sources a stage names both belong to the embedder. The
+ * embedder states them once, in its composition root, with one call:
+ *
+ *   composeFabric({
+ *     supervisorEntrypoint: 'SupervisorRPC',
+ *     stagedBootAssembler: (env, stage) => assembleConfig(env, stage),
+ *   });
+ *
+ * First-write-wins, like every holder in this module: the composition
+ * root's module scope runs once per isolate, before any request.
+ *
+ * `ctx.exports` is runtime state, not composition: workerd mints it per
+ * instance, so the embedder captures it where the platform hands it over —
+ * the first fetch, or the DO constructor — with {@link adoptCtxExports}.
+ *
+ * This module stays a leaf (no fabric imports) so helpers (notably
+ * isolate-pool.ts) can read `ctx.exports` without transitively importing
+ * the Durable Object classes, which is what lets the pool be unit-tested
+ * in a plain Node/Bun process.
+ */
+export type EntrypointLoopbackFactory = <Stub = unknown>(options: { props: object }) => Stub;
+export type CtxExports = Record<string, EntrypointLoopbackFactory | undefined>;
+export type StagedBootAssembler = (env: unknown, stage: unknown) => Promise<object>;
+
+export interface FabricComposition {
+  supervisorEntrypoint: string;
+  stagedBootAssembler?: StagedBootAssembler;
+  /** Durable Object namespace binding that owns the workspace. */
+  hostNamespace?: string;
+  /** RPC method the host forwards to workspace.supervisorOp. */
+  hostDispatchMethod?: string;
+}
+
+export const DEFAULT_HOST_NAMESPACE = 'NIMBUS_SESSION';
+export const DEFAULT_HOST_DISPATCH_METHOD = 'supervisorOp';
+let composition: FabricComposition | null = null;
+let ctxExports: CtxExports | null = null;
+
+/** Composition and loopback exports are first-write-wins for this isolate. */
+export function composeFabric(value: FabricComposition): void {
+  if (!composition) composition = value;
+}
+
+export function adoptCtxExports(value: CtxExports): void {
+  if (!ctxExports) ctxExports = value;
+}
+
+export function getCtxExports(): CtxExports | null {
+  return ctxExports;
+}
+
+export function supervisorEntrypoint(exportsObj?: unknown): EntrypointLoopbackFactory | null {
+  const exports = exportsObj ?? ctxExports;
+  const name = composition?.supervisorEntrypoint;
+  if (!name) return null;
+  if ((typeof exports !== 'object' && typeof exports !== 'function') || exports === null) return null;
+  const factory = (exports as Record<string, unknown>)[name];
+  return typeof factory === 'function' ? factory as EntrypointLoopbackFactory : null;
+}
+
+export function supervisorEntrypointName(): string | null {
+  return composition?.supervisorEntrypoint ?? null;
+}
+
+export function hostNamespace(): string {
+  return composition?.hostNamespace ?? DEFAULT_HOST_NAMESPACE;
+}
+
+export function hostDispatchMethod(): string {
+  return composition?.hostDispatchMethod ?? DEFAULT_HOST_DISPATCH_METHOD;
+}
+
+export function stagedBootAssembler(): StagedBootAssembler {
+  const assembler = composition?.stagedBootAssembler;
+  if (!assembler) {
+    throw new Error(
+      'fabric: no staged-boot assembler composed; a \'staged\' boot spec '
+        + 'cannot be assembled without one (composeFabric)',
+    );
+  }
+  return assembler;
+}