@nimbus-sh/fabric 0.1.0 → 0.2.0

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,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.
+ */
+/**
+ * One entry of `ctx.exports`: a top-level entrypoint's loopback factory, which
+ * mints a Service Binding stub for that entrypoint when called with props.
+ *
+ * The stub's RPC surface belongs to the entrypoint CLASS, which this leaf
+ * cannot see — `Cloudflare.Exports` is derived from the embedder's own main
+ * module, so for a library it evaluates to `{}`. A caller that knows the class
+ * names the surface it expects (`factory<MySupervisorRpc>({ props })`); one
+ * that does not gets `unknown` and has to narrow, same as
+ * `DurableObjectNamespace<T>` and `RpcStub<T>` in @cloudflare/workers-types.
+ */
+export type EntrypointLoopbackFactory = <Stub = unknown>(options: {
+    props: object;
+}) => Stub;
+/**
+ * `ctx.exports` itself — one factory per top-level entrypoint export, keyed by
+ * export name. Absent names read as undefined, which is how a caller finds out
+ * the embedder's entry module does not re-export the class it needs.
+ */
+export type CtxExports = Record<string, EntrypointLoopbackFactory | undefined>;
+/**
+ * Assemble a complete Worker Loader config from a staged-artifact spec. The
+ * embedder supplies this: a stage names artifact sources only the embedder
+ * knows how to fetch (Nimbus's largest staged artifact is a ~23 MB module map
+ * from ASSETS), and the assembler runs inside the loader's cache-miss callback
+ * so those sources are materialized only while the facet actually loads.
+ * `env` is whichever hosting actor's env the facet is opened with.
+ */
+export type StagedBootAssembler = (env: unknown, stage: unknown) => Promise<object>;
+/** What an embedder states about itself, once, in its composition root. */
+export interface FabricComposition {
+    /**
+     * The ctx.exports name of the embedder's supervisor WorkerEntrypoint. The
+     * fabric mints one supervisor binding per hosted program from it
+     * (`env.SUPERVISOR` inside the facet).
+     */
+    supervisorEntrypoint: string;
+    /** Only embedders that use 'staged' boot specs supply one. */
+    stagedBootAssembler?: StagedBootAssembler;
+}
+/** Register the embedder's composition. First-write-wins. */
+export declare function composeFabric(composition: FabricComposition): void;
+/**
+ * Capture `ctx.exports` for the helpers that mint loopback bindings. The
+ * embedder calls this where the platform hands the bag over — the first
+ * fetch, or the DO constructor. First-write-wins.
+ */
+export declare function adoptCtxExports(value: CtxExports): void;
+export declare function getCtxExports(): CtxExports | null;
+/**
+ * Resolve the composed supervisor entrypoint on an exports object —
+ * `exportsObj` when given (a WorkerEntrypoint reads its own ctx.exports),
+ * the adopted ctx.exports otherwise. Calling the result with props mints one
+ * supervisor binding (`env.SUPERVISOR`) for one hosted program. Null when
+ * either half is missing; the caller decides whether that degrades or throws.
+ */
+export declare function supervisorEntrypoint(exportsObj?: unknown): EntrypointLoopbackFactory | null;
+/** The composed name, for error messages that point at the missing export. */
+export declare function supervisorEntrypointName(): string | null;
+/** The composed assembler; a 'staged' boot spec cannot assemble without one. */
+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;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAE7F;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,OAAO,KACX,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAID,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAGlE;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAGvD;AAED,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,yBAAyB,GAAG,IAAI,CAO3F;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAExD;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,IAAI,mBAAmB,CASzD"}

package/dist/composition.js

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+let _composition = null;
+/** Register the embedder's composition. First-write-wins. */
+export function composeFabric(composition) {
+    if (_composition)
+        return;
+    _composition = composition;
+}
+let _ctxExports = null;
+/**
+ * Capture `ctx.exports` for the helpers that mint loopback bindings. The
+ * embedder calls this where the platform hands the bag over — the first
+ * fetch, or the DO constructor. First-write-wins.
+ */
+export function adoptCtxExports(value) {
+    if (_ctxExports)
+        return;
+    _ctxExports = value;
+}
+export function getCtxExports() {
+    return _ctxExports;
+}
+/**
+ * Resolve the composed supervisor entrypoint on an exports object —
+ * `exportsObj` when given (a WorkerEntrypoint reads its own ctx.exports),
+ * the adopted ctx.exports otherwise. Calling the result with props mints one
+ * supervisor binding (`env.SUPERVISOR`) for one hosted program. Null when
+ * either half is missing; the caller decides whether that degrades or throws.
+ */
+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;
+}
+/** The composed name, for error messages that point at the missing export. */
+export function supervisorEntrypointName() {
+    return _composition?.supervisorEntrypoint ?? null;
+}
+/** The composed assembler; a 'staged' boot spec cannot assemble without one. */
+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/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);
+}