Fix: restore __ps_name storage hydrate for Agents facets (0.5.1)

0.5.0 moved the legacy __ps_name storage hydrate into `alarm()` only,
which broke Cloudflare Agents facets and any other framework that
writes __ps_name directly before calling __unsafe_ensureInitialized().

Facet DOs are spawned via `ctx.facets.get(...)` rather than
`idFromName()`, so their `ctx.id.name` is `undefined`. They were
relying on PartyServer's `#ensureInitialized()` calling
`#hydrateNameFromStorage()` to populate `this.name` before `onStart()`.

This PR:

- Moves the hydrate from `alarm()` into `#ensureInitialized()`, gated on
  `!ctx.id.name && !#_name` so the happy path (normal idFromName DOs)
  still pays zero storage reads.
- Simplifies `Server.fetch()` to delegate the hydrate to
  `#ensureInitialized()`. The x-partykit-room header remains as a
  last-resort fallback when neither ctx.id.name nor storage has a value.
- Simplifies `Server.alarm()` — no separate hydrate call needed.
- Softens `@deprecated` on `setName()` to clarify it's still the right
  primitive for framework bootstrap of non-idFromName DOs (e.g. facets).
- Adds FacetLikeBootstrapServer + tests covering the fetch-time and
  RPC-time hydrate paths.

Made-with: Cursor

Author: threepointone

.changeset/fix-facet-hydrate.md

@@ -0,0 +1,14 @@
+---
+"partyserver": patch
+---
+
+Fix: restore legacy `__ps_name` storage fallback for framework bootstrap patterns.
+
+0.5.0 moved the legacy storage hydrate into `alarm()` only, breaking Cloudflare Agents facets and any other framework that writes `__ps_name` directly before calling `__unsafe_ensureInitialized()`. Facet DOs are spawned via `ctx.facets.get(...)` rather than `idFromName()` and therefore have `ctx.id.name === undefined`; they relied on PartyServer reading the storage record back to populate `this.name` before `onStart()`.
+
+Changes:
+
+- Move the legacy `__ps_name` hydrate from `alarm()` into `#ensureInitialized()`, still gated on `!ctx.id.name && !#_name` so it costs nothing on the happy path (normal `idFromName()`/`getByName()` DOs skip the storage read entirely).
+- `Server.fetch()` now delegates to `#ensureInitialized()` for the hydrate instead of doing its own. The `x-partykit-room` header fallback remains as a last resort when neither `ctx.id.name` nor a legacy storage record is available.
+- `Server.alarm()` is simplified — it no longer needs its own hydrate call since `#ensureInitialized()` handles it.
+- `setName()`'s `@deprecated` docblock is softened to clarify that it remains appropriate for framework-level bootstrap of non-`idFromName` DOs (e.g. Agents facets), not just a deprecated compatibility shim.

packages/partyserver/src/index.ts

@@ -389,24 +389,26 @@ export class Server<
         this.#_props = JSON.parse(props);
       }
 
-      // Legacy fallback for callers that bypass `routePartykitRequest`/
-      // `getServerByName` and invoke `stub.fetch()` directly with the
-      // `x-partykit-room` header. When the DO was addressed via
-      // `idFromName()`/`getByName()`, `ctx.id.name` provides the name and
-      // this branch is a no-op.
+      // Name resolution in `#ensureInitialized()` consults
+      // `ctx.id.name`, then a legacy storage record, so by the time it
+      // returns `this.name` is populated for any properly-addressed
+      // DO or any DO bootstrapped via the legacy `__ps_name` storage
+      // record (e.g. Cloudflare Agents facets). The only remaining
+      // case is a caller that bypasses both — then we fall back to
+      // the `x-partykit-room` request header.
+      await this.#ensureInitialized();
+
       if (!this.ctx.id.name && !this.#_name) {
         const room = request.headers.get("x-partykit-room");
         if (!room) {
-          throw new Error(`Cannot determine the name for ${this.#ParentClass.name}: this.ctx.id.name is undefined and no x-partykit-room header is present. Likely causes:
+          throw new Error(`Cannot determine the name for ${this.#ParentClass.name}: this.ctx.id.name is undefined, no legacy __ps_name storage record is present, and no x-partykit-room header was supplied. Likely causes:
   1. The stub was built via idFromString()/newUniqueId(). PartyServer requires name-based addressing (idFromName/getByName).
   2. The workerd/wrangler runtime is too old to expose ctx.id.name — update to a recent wrangler release.
   3. You called stub.fetch() directly without going through routePartykitRequest()/getServerByName(). Prefer those, or set the x-partykit-room header.`);
         }
         this.#_name = room;
       }
 
-      await this.#ensureInitialized();
-
       const url = new URL(request.url);
 
       if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
@@ -543,10 +545,21 @@ export class Server<
   }
 
   /**
-   * Read a legacy name record from storage. Only used for alarms scheduled
-   * before 2026-03-15, which fire without `ctx.id.name` populated on the
-   * alarm handler. See:
-   * https://developers.cloudflare.com/durable-objects/api/id/#name
+   * Read the legacy `__ps_name` storage record as a fallback source of
+   * `this.name` when `ctx.id.name` is unavailable. Covers:
+   *
+   *   1. Pre-2026-03-15 alarms, which fire without `ctx.id.name`
+   *      populated on the alarm handler (see the Durable Objects
+   *      ID docs: https://developers.cloudflare.com/durable-objects/api/id/#name).
+   *   2. Framework-level bootstrap patterns that write `__ps_name`
+   *      directly before calling `__unsafe_ensureInitialized()` —
+   *      notably Cloudflare Agents facets, which are addressed via
+   *      `ctx.facets.get()` rather than `idFromName()` and therefore
+   *      do not receive a `ctx.id.name`.
+   *
+   * PartyServer no longer writes this record itself. Everything that
+   * reads it is reading something written by an older version of
+   * PartyServer or by a framework that embeds it.
    */
   async #hydrateNameFromLegacyStorage(): Promise<void> {
     if (this.#_name) return;
@@ -569,6 +582,17 @@ export class Server<
 
   async #ensureInitialized(): Promise<void> {
     if (this.#status === "started") return;
+
+    // Name resolution fallback. The happy path (DO addressed via
+    // idFromName/getByName) short-circuits here because `ctx.id.name`
+    // is already populated — no storage read. The slow path covers
+    // pre-2026-03-15 alarms and framework bootstrap patterns (e.g.
+    // Agents facets) that write `__ps_name` directly before the
+    // first `onStart()` runs.
+    if (!this.ctx.id.name && !this.#_name) {
+      await this.#hydrateNameFromLegacyStorage();
+    }
+
     let error: unknown;
     await this.ctx.blockConcurrencyWhile(async () => {
       this.#status = "starting";
@@ -646,11 +670,19 @@ export class Server<
   }
 
   /**
-   * @deprecated The DO's name is available automatically via `ctx.id.name`
-   * as long as the stub was created with `idFromName()`/`getByName()`.
-   * Callers generally no longer need `setName()`; it is retained for
-   * backward compatibility (including delivering initial `props` to
-   * `onStart()`).
+   * @deprecated for callers that address DOs via `idFromName()` /
+   * `getByName()` — `this.name` is available automatically from
+   * `ctx.id.name` and calling `setName()` is redundant.
+   *
+   * Still appropriate for two use cases:
+   *   1. Delivering initial `props` to `onStart()` (via the optional
+   *      second argument).
+   *   2. Framework-level bootstrap of non-`idFromName` DOs where
+   *      `ctx.id.name` is undefined — for example, Cloudflare Agents
+   *      facets. Calling `setName(name)` from inside such a DO stashes
+   *      the name in memory for the current instance; for
+   *      survival-across-eviction, write `__ps_name` to storage as
+   *      well.
    */
   async setName(name: string, props?: Props) {
     if (!name) {
@@ -842,13 +874,6 @@ export class Server<
   }
 
   async alarm(): Promise<void> {
-    // Alarms scheduled before 2026-03-15 fire without `ctx.id.name`.
-    // Recover the name from the legacy storage record if present so that
-    // `this.name` / `onStart()` / `onAlarm()` keep working during the
-    // upgrade window while those alarms drain.
-    if (!this.ctx.id.name && !this.#_name) {
-      await this.#hydrateNameFromLegacyStorage();
-    }
     await this.#ensureInitialized();
     await this.onAlarm();
   }

packages/partyserver/src/tests/index.test.ts

@@ -699,6 +699,50 @@ describe("this.name in the constructor", () => {
   });
 });
 
+describe("Framework bootstrap fallback (Agents facets etc.)", () => {
+  it("hydrates this.name from __ps_name storage when ctx.id.name is undefined", async () => {
+    // Regression guard for Cloudflare Agents facets. Facets are spawned
+    // via `ctx.facets.get(...)`, not `idFromName()`, so their
+    // `ctx.id.name` is `undefined`. Agents bootstraps the name by
+    // writing `__ps_name` to storage and then calling
+    // `__unsafe_ensureInitialized()`. PartyServer's
+    // `#ensureInitialized()` must pick up the storage record as a
+    // fallback so `onStart()` can read `this.name`.
+    const id = env.FacetLikeBootstrapServer.newUniqueId();
+    const stub = env.FacetLikeBootstrapServer.get(id);
+    const result = await stub.bootstrap("facet-bootstrap-test");
+    expect(result.onStartName).toBe("facet-bootstrap-test");
+
+    // Follow-up fetch must also see the hydrated name (the #_name
+    // stashed during bootstrap survives in-memory as long as the DO
+    // instance isn't evicted).
+    const res = await stub.fetch(new Request("http://example.com/"));
+    const data = (await res.json()) as {
+      name: string;
+      onStartName: string | null;
+    };
+    expect(data.name).toBe("facet-bootstrap-test");
+    expect(data.onStartName).toBe("facet-bootstrap-test");
+  });
+
+  it("recovers from cold-wake fetch by re-reading storage when ctx.id.name is undefined", async () => {
+    // After the initial bootstrap, the DO may evict and come back
+    // cold. `Server.fetch()` must still resolve `this.name` via the
+    // storage fallback inside `#ensureInitialized()`, even without an
+    // `x-partykit-room` header.
+    const id = env.FacetLikeBootstrapServer.newUniqueId();
+    const stub = env.FacetLikeBootstrapServer.get(id);
+    await stub.bootstrap("facet-coldwake-test");
+
+    // Second, otherwise-unrelated fetch — no header, no bootstrap call.
+    // Simulates a later request arriving at the same DO.
+    const res = await stub.fetch(new Request("http://example.com/"));
+    expect(res.status).toBe(200);
+    const data = (await res.json()) as { name: string };
+    expect(data.name).toBe("facet-coldwake-test");
+  });
+});
+
 describe("Legacy fallbacks", () => {
   it("reads __ps_name from storage when ctx.id.name is undefined in an alarm", async () => {
     // Simulates the pre-2026-03-15 alarm migration scenario: an alarm was

packages/partyserver/src/tests/worker.ts

@@ -15,6 +15,7 @@ export type Env = {
   AlarmServer: DurableObjectNamespace<AlarmServer>;
   AlarmNameServer: DurableObjectNamespace<AlarmNameServer>;
   NoNameServer: DurableObjectNamespace<NoNameServer>;
+  FacetLikeBootstrapServer: DurableObjectNamespace<FacetLikeBootstrapServer>;
   NameInConstructorServer: DurableObjectNamespace<NameInConstructorServer>;
   Mixed: DurableObjectNamespace<Mixed>;
   ConfigurableState: DurableObjectNamespace<ConfigurableState>;
@@ -256,6 +257,41 @@ export class NoNameServer extends Server {
   }
 }
 
+/**
+ * Simulates a framework-level bootstrap pattern (e.g. Cloudflare Agents
+ * facets) where the DO is NOT addressed via `idFromName()` — so
+ * `ctx.id.name` is undefined — but the framework writes `__ps_name` to
+ * storage directly and then triggers `onStart()`. PartyServer must pick
+ * up the legacy storage record as a fallback so `onStart()` and
+ * subsequent handlers can read `this.name`.
+ */
+export class FacetLikeBootstrapServer extends Server {
+  static options = { hibernate: true };
+
+  onStartName: string | null = null;
+
+  async onStart() {
+    try {
+      this.onStartName = this.name;
+    } catch {
+      this.onStartName = null;
+    }
+  }
+
+  async bootstrap(name: string): Promise<{ onStartName: string | null }> {
+    await this.ctx.storage.put("__ps_name", name);
+    await this.__unsafe_ensureInitialized();
+    return { onStartName: this.onStartName };
+  }
+
+  onRequest(): Response {
+    return Response.json({
+      name: this.name,
+      onStartName: this.onStartName
+    });
+  }
+}
+
 /**
  * Regression guard for the headline Phase 1 capability: `this.name` must
  * be readable inside the constructor and from class field initializers,

packages/partyserver/src/tests/wrangler.jsonc

@@ -87,6 +87,10 @@
         "name": "PropsServer",
         "class_name": "PropsServer"
       },
+      {
+        "name": "FacetLikeBootstrapServer",
+        "class_name": "FacetLikeBootstrapServer"
+      },
       {
         "name": "NameInConstructorServer",
         "class_name": "NameInConstructorServer"
@@ -116,6 +120,7 @@
         "UriServer",
         "UriServerInMemory",
         "PropsServer",
+        "FacetLikeBootstrapServer",
         "NameInConstructorServer"
       ]
     }