@nimbus-sh/fabric 0.1.0 → 0.3.0

package/dist/bindings.js

@@ -24,10 +24,10 @@
  */
 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 { 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';
 /**
  * `ctx.exports` — workerd's loopback bag, which the installed
  * @cloudflare/workers-types does not put on `ExecutionContext`. Probed rather
@@ -448,7 +448,7 @@ export class NimbusLoadedEntrypoint extends WorkerEntrypoint {
             // 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.modules ?? {});
                 const supervisorBinding = await this._supervisorBinding(props);
                 if (!supervisorBinding)

package/dist/budgets.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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.
+ */
+/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
+export declare function recordLoaderId(ctx: object, id: string): void;
+/**
+ * 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 declare function beginLoaderFetch(ctx: object): () => void;
+/** Snapshot for the diag surface. Pure read; no I/O. */
+export declare function loaderLedgerStats(ctx: object): {
+    idsEverGotten: string[];
+    liveFetches: number;
+    peakLiveFetches: number;
+};
+/**
+ * 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 declare function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error;
+/**
+ * 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 declare const DYNAMIC_WORKER_CODE_LIMIT_BYTES = 67108864;
+/**
+ * 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 declare function assertModuleMapWithinCodeLimit(modules: Record<string, unknown>): void;
+/**
+ * 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 declare const FACET_ID_LIFETIME_BUDGET = 65536;
+/** Where the ledger persists the count of facet names ever minted. */
+export declare 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>;
+    };
+}
+/**
+ * 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 declare function recordFacetNameMinted(ctx: FacetNameLedgerStorage, count: number): void;
+/** The best count available without awaiting storage: minted or adopted. */
+export declare function facetNameCount(ctx: FacetNameLedgerStorage): number;
+/** The count with adoption awaited, for a first failure on a fresh boot. */
+export declare function facetNameCountDurable(ctx: FacetNameLedgerStorage): Promise<number>;
+/**
+ * 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 declare function facetIdBudget(ctx: FacetNameLedgerStorage): Promise<{
+    consumed: number;
+    budget: number;
+}>;
+/**
+ * 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 declare function withFacetBudgetNamed(consumed: number, error: unknown): unknown;
+export {};
+//# sourceMappingURL=budgets.d.ts.map

package/dist/budgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budgets.d.ts","sourceRoot":"","sources":["../src/budgets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAwBH,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,IAAI,CAUxD;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC9C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB,CAOA;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAW7E;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,WAAa,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAoBrF;AAuBD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,iCAAiC,CAAC;AAExE,mEAAmE;AACnE,UAAU,sBAAsB;IAC9B,OAAO,EAAE;QACP,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;QAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACjD,CAAC;CACH;AAqCD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAatF;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,GAAG,EAAE,sBAAsB,GAAG,MAAM,CAGlE;AAED,4EAA4E;AAC5E,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAIxF;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAK/C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAU9E"}

package/dist/budgets.js

@@ -0,0 +1,248 @@
+/**
+ * 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';
+const ledgers = new WeakMap();
+function ledger(ctx) {
+    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, id) {
+    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) {
+    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) {
+    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(ctx, 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) {
+    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, encoder) {
+    const textBytes = (text) => 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';
+const facetNameLedgers = new WeakMap();
+function facetNameLedger(ctx) {
+    let ledger = facetNameLedgers.get(ctx);
+    if (!ledger) {
+        const created = { 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, count) {
+    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) {
+    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) {
+    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) {
+    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, error) {
+    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/dist/composition.d.ts

@@ -0,0 +1,3 @@
+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';
+//# 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":"AACA,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,oCAAoC,CAAC;AAE5C,YAAY,EACV,UAAU,EACV,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,oCAAoC,CAAC"}

package/dist/composition.js

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

package/dist/connections.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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';
+/** 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 declare function connections<T>(ctx: ConnectionsContext, schema: z.ZodType<T>): Connections<T>;
+export declare class Connections<T> {
+    private readonly ctx;
+    private readonly schema;
+    constructor(ctx: ConnectionsContext, 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;
+    /** The open socket holding a tag, re-derived from the platform. */
+    get(tag: string): ConnectionSocket | null;
+    /** Every open socket (optionally: holding a tag). */
+    list(tag?: string): ConnectionSocket[];
+    /** A socket's tags — identity key first, then whatever accept added. */
+    tags(ws: ConnectionSocket): string[];
+    /**
+     * 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;
+    /** Replace the attachment, validated on the way in. */
+    write(ws: ConnectionSocket, attachment: T): void;
+    private writeSerialized;
+}
+//# sourceMappingURL=connections.d.ts.map

package/dist/connections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAK3B,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1C,qBAAqB,IAAI,OAAO,CAAC;CAClC;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,eAAe,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC7D,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAChD,OAAO,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAAC;CACzC;AAED;4CAC4C;AAC5C,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,kBAAkB,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAE5F;AAED,qBAAa,WAAW,CAAC,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,GAAG,EAAE,kBAAkB,EACvB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAGvC;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,CAAC,CAAA;KAAE,GAAG,IAAI;IASzF,mEAAmE;IACnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAOzC,qDAAqD;IACrD,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAItC,wEAAwE;IACxE,IAAI,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,EAAE;IAIpC;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,gBAAgB,GAAG,CAAC,GAAG,IAAI;IAKpC,uDAAuD;IACvD,KAAK,CAAC,EAAE,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC,GAAG,IAAI;IAIhD,OAAO,CAAC,eAAe;CAcxB"}

package/dist/connections.js

@@ -0,0 +1,114 @@
+/**
+ * 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 { WS_ATTACHMENT_LIMIT_BYTES } from '@nimbus-sh/platform/limits.js';
+const WS_OPEN = 1;
+/** The per-connection hub of one hosting actor. Cheap accessor; it holds no
+ *  state of its own, which is the point. */
+export function connections(ctx, schema) {
+    return new Connections(ctx, schema);
+}
+export class Connections {
+    ctx;
+    schema;
+    constructor(ctx, schema) {
+        this.ctx = ctx;
+        this.schema = schema;
+    }
+    /**
+     * 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, opts) {
+        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) {
+        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) {
+        return this.ctx.getWebSockets(tag).filter((ws) => ws.readyState === WS_OPEN);
+    }
+    /** A socket's tags — identity key first, then whatever accept added. */
+    tags(ws) {
+        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) {
+        const parsed = this.schema.safeParse(ws.deserializeAttachment());
+        return parsed.success ? parsed.data : null;
+    }
+    /** Replace the attachment, validated on the way in. */
+    write(ws, attachment) {
+        this.writeSerialized(ws, this.schema.parse(attachment));
+    }
+    writeSerialized(ws, validated) {
+        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) {
+    try {
+        return JSON.stringify(value)?.length ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}