@nimbus-sh/fabric 0.1.0 → 0.3.0

package/dist/derived.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 declare function derived<T, C = void>(watermark: (context: C) => string | number, build: (context: C, key: string | number) => T, hooks?: DerivedHooks): Derived<T, C>;
+export interface DerivedAsync<T, C = void> {
+    get(context: C): Promise<T>;
+    invalidate(): void;
+}
+export declare function derivedAsync<T, C = void>(watermark: (context: C) => Promise<string | number>, build: (context: C, key: string | number) => Promise<T>, hooks?: DerivedAsyncHooks): DerivedAsync<T, C>;
+//# sourceMappingURL=derived.d.ts.map

package/dist/derived.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived.d.ts","sourceRoot":"","sources":["../src/derived.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,OAAO,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI;IAClC;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;IACnB,0DAA0D;IAC1D,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,SAAS,CAAC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACtF;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,gEAAgE;IAChE,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,EACjC,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,EAC1C,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,KAAK,CAAC,EAC9C,KAAK,GAAE,YAAiB,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAmBf;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI;IACvC,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,EACtC,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,EACnD,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACvD,KAAK,GAAE,iBAAsB,GAC5B,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAsCpB"}

package/dist/derived.js

@@ -0,0 +1,95 @@
+/**
+ * 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 function derived(watermark, build, hooks = {}) {
+    let key;
+    let value;
+    let has = false;
+    return {
+        get(context) {
+            const next = watermark(context);
+            if (has && next === key)
+                return value;
+            value = build(context, next);
+            hooks.onRebuild?.(key, next);
+            key = next;
+            has = true;
+            return value;
+        },
+        invalidate() {
+            has = false;
+            value = undefined;
+        },
+    };
+}
+export function derivedAsync(watermark, build, hooks = {}) {
+    let key;
+    let value;
+    let has = false;
+    return {
+        async get(context) {
+            let next;
+            try {
+                next = await watermark(context);
+            }
+            catch (e) {
+                if (has) {
+                    hooks.onStale?.(e);
+                    return value;
+                }
+                throw e;
+            }
+            if (has && next === key)
+                return value;
+            let built;
+            try {
+                built = await build(context, next);
+            }
+            catch (e) {
+                if (has) {
+                    hooks.onStale?.(e);
+                    return value;
+                }
+                throw e;
+            }
+            value = built;
+            hooks.onRebuild?.(key, next);
+            key = next;
+            has = true;
+            return built;
+        },
+        invalidate() {
+            has = false;
+            value = undefined;
+        },
+    };
+}

package/dist/do-calls.d.ts

@@ -0,0 +1,94 @@
+/**
+ * do-calls.ts — the two verbs for calling another Durable Object, split by
+ * the one property that decides whether a retry is safe.
+ *
+ * Both consumers asked for this. Proteus hand-wrote the retry
+ * (`cf-backend/src/lib/do-rpc.ts`) with the rule its header states:
+ * "An operation that appends, sends, charges or mints is never wrapped: a
+ * dropped call there may already have run, so a retry is a correctness bug
+ * wearing resilience as a costume." agent-core has no retry machinery at all
+ * and its backlog calls the gap "the most production-proven gap in the
+ * corpus". Here the rule is a type: `idempotent` retries, `mutating` cannot.
+ *
+ * What the platform contract requires, and this keeps:
+ *   - a FRESH stub per attempt. Cloudflare documents that many exceptions
+ *     leave a stub permanently broken, so both verbs take a stub RESOLVER,
+ *     not a stub — which is also what lets placement pins and auth wrappers
+ *     compose (agent-core's PlacementResolver pins an Actor to one
+ *     jurisdiction for life; the resolver seam is where that lives).
+ *   - `overloaded` is never retried, by either verb: retrying an overloaded
+ *     object is what overloaded it.
+ *   - attempts and backoff are the consumer-proven bounds: 3 attempts total,
+ *     full-jitter delays in [0, 2**attempt * 60ms).
+ *
+ * The resolver MINTS a stub per call and the verb disposes each one it
+ * minted — that ownership is what makes the fresh-stub retry real.
+ *
+ * The stub method call itself happens inside the CALLER's closure
+ * (`(stub) => stub.method(args)`): nothing here proxies property resolution
+ * or dispatches by method name. Do NOT use these verbs around a dynamically
+ * loaded worker's entrypoint stub — those calls must stay direct property
+ * calls bracketed by `beginLoaderFetch` (budgets.ts records the 7/7 staging
+ * poisoning that rule comes from). These verbs are for Durable Object
+ * namespace stubs, where the thunk shape is production-proven in Proteus.
+ */
+import { type DoCallClass } from '@nimbus-sh/platform/oom-classify.js';
+export interface DoCallRetryPolicy {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    /**
+     * Called once per retry, before its backoff delay, with the failure the
+     * retry is answering. The consumer's logging seam: Proteus's hand-rolled
+     * predecessor logged every retry so a flaky object is visible in Workers
+     * Logs rather than silently absorbed, and `operation` names it there.
+     */
+    onRetry?(info: DoCallRetryInfo): void;
+}
+/** What one retry is answering: which call, which platform class, which
+ *  attempt just failed out of how many. */
+export interface DoCallRetryInfo {
+    operation: string;
+    classification: DoCallClass;
+    /** The 1-based attempt that failed; the retry about to run is attempt+1. */
+    attempt: number;
+    maxAttempts: number;
+    error: unknown;
+}
+/**
+ * Mints one stub per call. `idempotent` calls it once per attempt.
+ *
+ * MINT means mint. Both verbs dispose the stub they were handed when the
+ * call settles — on success as much as on failure (`disposeRpcResource`).
+ * A resolver that returns a shared, long-lived stub hands its other users
+ * a disposed stub, and only in production: a test double is a plain object
+ * with nothing to dispose, so the test stays green while the deployed
+ * Worker breaks on the second call.
+ */
+export type DoStubResolver<S> = () => S | Promise<S>;
+/**
+ * A failed `mutating` call, typed so the caller can act on WHAT failed:
+ * `classification` names the platform condition, and a transient class on a
+ * mutating call means the call may already have run — the indeterminacy the
+ * consumer's rule exists to surface rather than paper over.
+ */
+export declare class DoCallError extends Error {
+    readonly operation: string;
+    readonly verb: 'idempotent' | 'mutating';
+    readonly classification: DoCallClass;
+    constructor(operation: string, verb: 'idempotent' | 'mutating', classification: DoCallClass, cause: unknown);
+}
+/**
+ * Call another Durable Object with an operation that is safe to repeat: a
+ * read, or a converge-to-a-value write. Transient failures retry on a fresh
+ * stub with full-jitter backoff; overloaded and permanent failures surface
+ * unchanged, as does the last error at exhaustion.
+ */
+export declare function idempotent<S, T>(operation: string, stub: DoStubResolver<S>, call: (stub: S) => Promise<T>, policy?: DoCallRetryPolicy): Promise<T>;
+/**
+ * Call another Durable Object with an operation that appends, sends, charges
+ * or mints. NEVER retried — a dropped call may already have run. Failure
+ * surfaces as a {@link DoCallError} carrying the classification, so the
+ * caller can tell a refusal from an indeterminate drop.
+ */
+export declare function mutating<S, T>(operation: string, stub: DoStubResolver<S>, call: (stub: S) => Promise<T>): Promise<T>;
+//# sourceMappingURL=do-calls.d.ts.map

package/dist/do-calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"do-calls.d.ts","sourceRoot":"","sources":["../src/do-calls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAqC,KAAK,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAU1G,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;CACvC;AAED;2CAC2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,WAAW,CAAC;IAC5B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAErD;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU;IACxC,QAAQ,CAAC,cAAc,EAAE,WAAW;gBAF3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,YAAY,GAAG,UAAU,EAC/B,cAAc,EAAE,WAAW,EACpC,KAAK,EAAE,OAAO;CASjB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC7B,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAUZ"}

package/dist/do-calls.js

@@ -0,0 +1,111 @@
+/**
+ * do-calls.ts — the two verbs for calling another Durable Object, split by
+ * the one property that decides whether a retry is safe.
+ *
+ * Both consumers asked for this. Proteus hand-wrote the retry
+ * (`cf-backend/src/lib/do-rpc.ts`) with the rule its header states:
+ * "An operation that appends, sends, charges or mints is never wrapped: a
+ * dropped call there may already have run, so a retry is a correctness bug
+ * wearing resilience as a costume." agent-core has no retry machinery at all
+ * and its backlog calls the gap "the most production-proven gap in the
+ * corpus". Here the rule is a type: `idempotent` retries, `mutating` cannot.
+ *
+ * What the platform contract requires, and this keeps:
+ *   - a FRESH stub per attempt. Cloudflare documents that many exceptions
+ *     leave a stub permanently broken, so both verbs take a stub RESOLVER,
+ *     not a stub — which is also what lets placement pins and auth wrappers
+ *     compose (agent-core's PlacementResolver pins an Actor to one
+ *     jurisdiction for life; the resolver seam is where that lives).
+ *   - `overloaded` is never retried, by either verb: retrying an overloaded
+ *     object is what overloaded it.
+ *   - attempts and backoff are the consumer-proven bounds: 3 attempts total,
+ *     full-jitter delays in [0, 2**attempt * 60ms).
+ *
+ * The resolver MINTS a stub per call and the verb disposes each one it
+ * minted — that ownership is what makes the fresh-stub retry real.
+ *
+ * The stub method call itself happens inside the CALLER's closure
+ * (`(stub) => stub.method(args)`): nothing here proxies property resolution
+ * or dispatches by method name. Do NOT use these verbs around a dynamically
+ * loaded worker's entrypoint stub — those calls must stay direct property
+ * calls bracketed by `beginLoaderFetch` (budgets.ts records the 7/7 staging
+ * poisoning that rule comes from). These verbs are for Durable Object
+ * namespace stubs, where the thunk shape is production-proven in Proteus.
+ */
+import { classifyDoCall, isRetryableDoCall } from '@nimbus-sh/platform/oom-classify.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+/** Total attempts. Two retries is what a dropped connection or a deploy
+ *  bounce needs; beyond that the object is not coming back inside this
+ *  request (the consumer's measured bound). */
+const MAX_ATTEMPTS = 3;
+/** Full-jitter base, in the shape the Agents SDK itself uses. */
+const BASE_DELAY_MS = 60;
+/**
+ * A failed `mutating` call, typed so the caller can act on WHAT failed:
+ * `classification` names the platform condition, and a transient class on a
+ * mutating call means the call may already have run — the indeterminacy the
+ * consumer's rule exists to surface rather than paper over.
+ */
+export class DoCallError extends Error {
+    operation;
+    verb;
+    classification;
+    constructor(operation, verb, classification, cause) {
+        const text = cause instanceof Error ? cause.message : String(cause);
+        const indeterminate = isRetryableDoCall(classification)
+            ? ' — a dropped mutating call may already have run, so it is not retried'
+            : '';
+        super(`${verb} call '${operation}' failed [${classification}]: ${text}${indeterminate}`, { cause });
+        this.operation = operation;
+        this.verb = verb;
+        this.classification = classification;
+        this.name = 'DoCallError';
+    }
+}
+/**
+ * Call another Durable Object with an operation that is safe to repeat: a
+ * read, or a converge-to-a-value write. Transient failures retry on a fresh
+ * stub with full-jitter backoff; overloaded and permanent failures surface
+ * unchanged, as does the last error at exhaustion.
+ */
+export async function idempotent(operation, stub, call, policy = {}) {
+    const maxAttempts = policy.maxAttempts ?? MAX_ATTEMPTS;
+    const baseDelayMs = policy.baseDelayMs ?? BASE_DELAY_MS;
+    for (let attempt = 1;; attempt++) {
+        const minted = await stub();
+        try {
+            const result = await call(minted);
+            disposeRpcResource(minted);
+            return result;
+        }
+        catch (error) {
+            // A stub that threw may be permanently broken; it is never reused.
+            disposeRpcResource(minted);
+            const classification = classifyDoCall(error);
+            if (!isRetryableDoCall(classification) || attempt >= maxAttempts)
+                throw error;
+            policy.onRetry?.({ operation, classification, attempt, maxAttempts, error });
+            await new Promise((resolve) => {
+                setTimeout(resolve, Math.floor(Math.random() * 2 ** attempt * baseDelayMs));
+            });
+        }
+    }
+}
+/**
+ * Call another Durable Object with an operation that appends, sends, charges
+ * or mints. NEVER retried — a dropped call may already have run. Failure
+ * surfaces as a {@link DoCallError} carrying the classification, so the
+ * caller can tell a refusal from an indeterminate drop.
+ */
+export async function mutating(operation, stub, call) {
+    const minted = await stub();
+    try {
+        const result = await call(minted);
+        disposeRpcResource(minted);
+        return result;
+    }
+    catch (error) {
+        disposeRpcResource(minted);
+        throw new DoCallError(operation, 'mutating', classifyDoCall(error), error);
+    }
+}

package/dist/facet-pool.d.ts

@@ -0,0 +1,90 @@
+/**
+ * facet-pool.ts — leased facets, so reclaiming storage is the default and
+ * leaking it takes intent.
+ *
+ * Proteus's facet-spawn.ts (313 lines) exists because the platform's two
+ * teardown verbs are indistinguishable to a caller and only one gives
+ * storage back: `abort` is mid-flight eviction with storage KEPT, `delete`
+ * is terminal with storage WIPED. Its docstring records the cost of
+ * confusing them: "the leak this module previously had, in which every head
+ * and every MCTS branch abandoned a permanent database inside the
+ * orchestrator DO". The lease makes that leak unreachable: disposal retires
+ * the facet (evict, then wipe), and keeping storage is the explicit opt-in
+ * (`detach()`, today's abort).
+ *
+ * The constraints a caller must not be surprised by, from Proteus's platform
+ * catalog (all proven by probe or by source):
+ *   - a facet cannot set alarms (`do.facet.no_alarms`) — a head cannot
+ *     schedule its own resumption; everything time-driven routes through the
+ *     root's single alarm (`timers`).
+ *   - a facet stub is coordinator-local (`do.facet.stub_local`) — it cannot
+ *     be transferred, stored, or re-invoked indirectly.
+ *   - facet storage is charged to the ROOT's shared budget, and a clone that
+ *     crosses it is an uncatchable reset, not an error (`do.storage.bytes`).
+ *   - a parent and its facets are evicted JOINTLY after minutes idle, so
+ *     in-memory facet state is never safe to assume between two RPCs.
+ *   - 65,536 facet ids per DO lifetime (`do.facet.count`), append-only and
+ *     never reclaimed — the binding constraint for the leak, reached an
+ *     order of magnitude before the byte quota. The pool counts first-use
+ *     names in the durable ledger (budgets.ts) and refuses a NEW name at the
+ *     wall by name, instead of letting the platform fail opaquely. Refusal
+ *     at the wall is exact, not a threshold: the ledger never overcounts.
+ *
+ * A failed reclaim stays loud (facet-spawn's `runOnceAndReclaim`): storage
+ * that was not given back is a permanent charge against the root's quota,
+ * and swallowing that is how the original leak stayed invisible.
+ *
+ * The pool drives the RAW `ctx.facets` container and assumes it is the only
+ * thing naming facets on this actor. The Agents SDK's sub-agent layer makes
+ * the same assumption from the other side — it owns facet naming and runs
+ * its own cleanup — so the two are mutually exclusive on one actor:
+ * whichever acts second aborts or retires facets the other still tracks,
+ * and the facet-id ledger here counts only the names this pool minted.
+ */
+/** `ctx.facets`, as the pool drives it — same surface the facet host uses. */
+export interface FacetPoolContainer {
+    get(name: string, start: () => Promise<{
+        class: unknown;
+    }>): unknown;
+    abort(name: string, reason?: unknown): void;
+    delete(name: string): void;
+}
+/** The hosting actor's context: its facet container, and the storage the
+ *  facet-id ledger persists through. */
+export interface FacetPoolContext {
+    facets?: FacetPoolContainer;
+    storage: {
+        get(key: string): Promise<unknown> | unknown;
+        put(key: string, value: unknown): Promise<void>;
+    };
+}
+/**
+ * One leased facet. Dispose (or `retire()`) evicts the instance and WIPES
+ * its storage; `detach()` first to keep the storage — after it, disposal
+ * only evicts. The stub is coordinator-local: do not store it past the turn
+ * or hand it to anything else.
+ */
+export interface FacetLease<S> {
+    readonly name: string;
+    readonly stub: S;
+    /** Keep the facet's storage: disposal becomes eviction only. */
+    detach(): void;
+    /** Idempotent. Throws, loudly, when the platform refuses the wipe. */
+    retire(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** The facet pool of one hosting actor. Cheap accessor, like `timers()`. */
+export declare function facetPool(ctx: FacetPoolContext): FacetPool;
+export declare class FacetPool {
+    private readonly ctx;
+    constructor(ctx: FacetPoolContext);
+    /**
+     * Open (or re-enter) the named facet under a lease. A first-use name
+     * consumes one of the object's 65,536 lifetime facet ids and is refused at
+     * the wall; a reused name costs nothing, in this incarnation or any other.
+     */
+    acquire<S = unknown>(name: string, start: () => Promise<{
+        class: unknown;
+    }>): Promise<FacetLease<S>>;
+}
+//# sourceMappingURL=facet-pool.d.ts.map

package/dist/facet-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facet-pool.d.ts","sourceRoot":"","sources":["../src/facet-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AASH,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC;IACrE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;wCACwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,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;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,gEAAgE;IAChE,MAAM,IAAI,IAAI,CAAC;IACf,sEAAsE;IACtE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAKD,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,CAE1D;AAED,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,gBAAgB;IAElD;;;;OAIG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,GACvC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CAiD1B"}

package/dist/facet-pool.js

@@ -0,0 +1,113 @@
+/**
+ * facet-pool.ts — leased facets, so reclaiming storage is the default and
+ * leaking it takes intent.
+ *
+ * Proteus's facet-spawn.ts (313 lines) exists because the platform's two
+ * teardown verbs are indistinguishable to a caller and only one gives
+ * storage back: `abort` is mid-flight eviction with storage KEPT, `delete`
+ * is terminal with storage WIPED. Its docstring records the cost of
+ * confusing them: "the leak this module previously had, in which every head
+ * and every MCTS branch abandoned a permanent database inside the
+ * orchestrator DO". The lease makes that leak unreachable: disposal retires
+ * the facet (evict, then wipe), and keeping storage is the explicit opt-in
+ * (`detach()`, today's abort).
+ *
+ * The constraints a caller must not be surprised by, from Proteus's platform
+ * catalog (all proven by probe or by source):
+ *   - a facet cannot set alarms (`do.facet.no_alarms`) — a head cannot
+ *     schedule its own resumption; everything time-driven routes through the
+ *     root's single alarm (`timers`).
+ *   - a facet stub is coordinator-local (`do.facet.stub_local`) — it cannot
+ *     be transferred, stored, or re-invoked indirectly.
+ *   - facet storage is charged to the ROOT's shared budget, and a clone that
+ *     crosses it is an uncatchable reset, not an error (`do.storage.bytes`).
+ *   - a parent and its facets are evicted JOINTLY after minutes idle, so
+ *     in-memory facet state is never safe to assume between two RPCs.
+ *   - 65,536 facet ids per DO lifetime (`do.facet.count`), append-only and
+ *     never reclaimed — the binding constraint for the leak, reached an
+ *     order of magnitude before the byte quota. The pool counts first-use
+ *     names in the durable ledger (budgets.ts) and refuses a NEW name at the
+ *     wall by name, instead of letting the platform fail opaquely. Refusal
+ *     at the wall is exact, not a threshold: the ledger never overcounts.
+ *
+ * A failed reclaim stays loud (facet-spawn's `runOnceAndReclaim`): storage
+ * that was not given back is a permanent charge against the root's quota,
+ * and swallowing that is how the original leak stayed invisible.
+ *
+ * The pool drives the RAW `ctx.facets` container and assumes it is the only
+ * thing naming facets on this actor. The Agents SDK's sub-agent layer makes
+ * the same assumption from the other side — it owns facet naming and runs
+ * its own cleanup — so the two are mutually exclusive on one actor:
+ * whichever acts second aborts or retires facets the other still tracks,
+ * and the facet-id ledger here counts only the names this pool minted.
+ */
+import { FACET_ID_LIFETIME_BUDGET, facetNameCount, recordFacetNameMinted, withFacetBudgetNamed, } from './budgets.js';
+/** Names this ctx's pool has already charged to the lifetime ledger. */
+const chargedNames = new WeakMap();
+/** The facet pool of one hosting actor. Cheap accessor, like `timers()`. */
+export function facetPool(ctx) {
+    return new FacetPool(ctx);
+}
+export class FacetPool {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Open (or re-enter) the named facet under a lease. A first-use name
+     * consumes one of the object's 65,536 lifetime facet ids and is refused at
+     * the wall; a reused name costs nothing, in this incarnation or any other.
+     */
+    async acquire(name, start) {
+        const facets = this.ctx.facets;
+        if (!facets || typeof facets.get !== 'function') {
+            throw new Error('fabric: ctx.facets is unavailable in this Durable Object; facets cannot be leased');
+        }
+        let charged = chargedNames.get(this.ctx);
+        if (!charged) {
+            charged = new Set();
+            chargedNames.set(this.ctx, charged);
+        }
+        if (!charged.has(name)) {
+            const consumed = facetNameCount(this.ctx);
+            if (consumed >= FACET_ID_LIFETIME_BUDGET) {
+                throw withFacetBudgetNamed(consumed, new Error(`facet '${name}' refused before creation: no lifetime ids remain`));
+            }
+            recordFacetNameMinted(this.ctx, consumed + 1);
+            charged.add(name);
+        }
+        const stub = facets.get(name, start);
+        let settled = false;
+        let keepStorage = false;
+        const retire = async () => {
+            if (settled)
+                return;
+            settled = true;
+            // Evict first so the wipe never lands under a live writer; a facet
+            // already gone makes the abort a no-op.
+            try {
+                facets.abort(name, new Error('fabric: facet lease retired'));
+            }
+            catch { /* already gone */ }
+            if (keepStorage)
+                return;
+            try {
+                facets.delete(name);
+            }
+            catch (e) {
+                throw new Error(`fabric: facet '${name}' was evicted but its storage was not reclaimed — `
+                    + `it is leaked into the root Durable Object's shared quota: ${errorText(e)}`, { cause: e });
+            }
+        };
+        return {
+            name,
+            stub,
+            detach() { keepStorage = true; },
+            retire,
+            [Symbol.asyncDispose]: retire,
+        };
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}