@nimbus-sh/platform 0.2.0 → 0.3.0

package/dist/composition.d.ts

@@ -1,4 +1,28 @@
-/** Shared composition state for core workspaces and the process fabric. */
+/**
+ * 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;

package/dist/composition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,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"}
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/platform",
-  "version": "0.2.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

@@ -1,4 +1,28 @@
-/** Shared composition state for core workspaces and the process fabric. */
+/**
+ * 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>;