setName() persists __ps_name for non-idFromName DOs

For DOs where `ctx.id.name` is undefined (Cloudflare Agents facets and
similar framework-level bootstrap patterns), `setName(name)` now writes
the name to the legacy `__ps_name` storage key in addition to stashing
it in memory. This makes `setName()` the sanctioned bootstrap API:
frameworks no longer need to write `__ps_name` directly themselves —
PartyServer manages its own storage layout.

For DOs addressed via idFromName/getByName, behavior is unchanged:
ctx.id.name carries the name, no storage write happens.

Migration for framework authors who currently do:

    await this.ctx.storage.put("__ps_name", name);
    await this.__unsafe_ensureInitialized();

becomes:

    await this.setName(name);

Backward compatible — the existing direct-storage pattern keeps working
since the storage write becomes idempotent.

Adds SetNameBootstrapServer + 3 tests covering:
1. setName() persists __ps_name for newUniqueId DOs
2. Cold-wake fetch recovers the name via the storage fallback
3. setName() does NOT write storage when ctx.id.name is set (regression
   guard for the 0.5.0 zero-storage-write win on the happy path)

Made-with: Cursor

Author: threepointone

.changeset/setname-bootstrap.md

@@ -0,0 +1,27 @@
+---
+"partyserver": patch
+---
+
+`setName()` is now the sanctioned bootstrap API for non-`idFromName` DOs.
+
+When `ctx.id.name` is undefined (e.g. Cloudflare Agents facets, which are spawned via `ctx.facets.get(...)` rather than `idFromName()`), `setName(name)` now persists the name to the legacy `__ps_name` storage key in addition to stashing it in memory. This means cold-wake invocations of the DO recover the name through `#ensureInitialized()`'s legacy storage fallback without the framework having to reach into PartyServer's private storage layout.
+
+Frameworks that previously did:
+
+```ts
+await this.ctx.storage.put("__ps_name", name);
+await this.__unsafe_ensureInitialized();
+```
+
+can now do:
+
+```ts
+await this.setName(name);
+```
+
+Backward compatible:
+
+- For DOs addressed via `idFromName()` / `getByName()` (the happy path), `setName()` continues to NOT write storage — `ctx.id.name` is the source of truth and `setName()` is just a no-op-plus-onStart.
+- The pre-existing direct-storage-write pattern keeps working — the storage write becomes idempotent with what `setName()` would do.
+
+`setName()`'s `@deprecated` docblock has been clarified: it remains the supported API for framework-level bootstrap of non-`idFromName` DOs and for delivering initial `props` to `onStart()`. The deprecation only applies to redundant calls on DOs that were addressed via `idFromName()`.

packages/partyserver/src/index.ts

@@ -670,19 +670,27 @@ export class Server<
   }
 
   /**
-   * @deprecated for callers that address DOs via `idFromName()` /
-   * `getByName()` — `this.name` is available automatically from
-   * `ctx.id.name` and calling `setName()` is redundant.
+   * Establish this server's name and trigger `onStart()`.
+   *
+   * Two distinct use cases:
    *
-   * 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
+   *   1. **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.
+   *      facets (spawned via `ctx.facets.get(...)`). `setName()` is the
+   *      sanctioned bootstrap primitive: it stashes the name in memory
+   *      AND persists it to storage (under `__ps_name`) so the name
+   *      survives DO eviction and is recovered on cold wake by
+   *      `#ensureInitialized()`.
+   *   2. **Delivering initial `props` to `onStart()`** via the optional
+   *      second argument.
+   *
+   * For DOs addressed via `idFromName()` / `getByName()`, calling
+   * `setName()` is redundant — `this.name` is available automatically
+   * from `ctx.id.name`. Throws if `name` does not match `ctx.id.name`.
+   *
+   * @deprecated for callers that address DOs via `idFromName()` /
+   * `getByName()`. Still the supported API for framework-level
+   * bootstrap and props delivery.
    */
   async setName(name: string, props?: Props) {
     if (!name) {
@@ -703,10 +711,14 @@ export class Server<
       this.#_props = props;
     }
     if (!this.#_name && ctxName === undefined) {
-      // Legacy path only (DO was addressed without idFromName). Stash the
-      // name in memory so subsequent handlers can read `this.name`.
-      // No storage write: PartyServer no longer persists the name itself.
+      // Bootstrap path (DO was addressed without idFromName, e.g.
+      // Cloudflare Agents facets). Stash the name in memory AND
+      // persist to storage so that subsequent cold-wake invocations
+      // (fetch, alarm, websocket handlers, RPC via
+      // `__unsafe_ensureInitialized`) can recover the name through
+      // `#ensureInitialized()`'s legacy fallback.
       this.#_name = name;
+      await this.ctx.storage.put(NAME_STORAGE_KEY, name);
     }
     await this.#ensureInitialized();
   }

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

@@ -722,6 +722,49 @@ describe("x-partykit-room header applied before onStart", () => {
   });
 });
 
+describe("setName() as bootstrap API for non-idFromName DOs", () => {
+  it("persists __ps_name to storage so the name survives eviction", async () => {
+    const id = env.SetNameBootstrapServer.newUniqueId();
+    const stub = env.SetNameBootstrapServer.get(id);
+
+    const result = await stub.bootstrap("setname-bootstrap-test");
+    expect(result.onStartName).toBe("setname-bootstrap-test");
+
+    // Verify setName() persisted to storage. Frameworks no longer need
+    // to write __ps_name themselves — `setName()` covers it.
+    const stored = await stub.readStoredName();
+    expect(stored).toBe("setname-bootstrap-test");
+  });
+
+  it("recovers the name on cold-wake fetch via the storage fallback", async () => {
+    const id = env.SetNameBootstrapServer.newUniqueId();
+    const stub = env.SetNameBootstrapServer.get(id);
+    await stub.bootstrap("setname-coldwake-test");
+
+    // Subsequent fetch with no header — must hydrate from storage.
+    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("setname-coldwake-test");
+  });
+
+  it("does NOT write storage when the DO was addressed via idFromName", async () => {
+    // For normal idFromName DOs, ctx.id.name carries the name and
+    // setName() is redundant. It must not write `__ps_name` to
+    // storage in this path — that would re-introduce the per-setName
+    // storage write that 0.5.0 eliminated.
+    const id = env.SetNameBootstrapServer.idFromName("setname-no-write");
+    const stub = env.SetNameBootstrapServer.get(id);
+
+    // Calling setName with the matching name is a no-op on storage;
+    // it just runs onStart.
+    await stub.setName("setname-no-write");
+
+    const stored = await stub.readStoredName();
+    expect(stored).toBeUndefined();
+  });
+});
+
 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

packages/partyserver/src/tests/worker.ts

@@ -16,6 +16,7 @@ export type Env = {
   AlarmNameServer: DurableObjectNamespace<AlarmNameServer>;
   NoNameServer: DurableObjectNamespace<NoNameServer>;
   HeaderOnlyOnStartServer: DurableObjectNamespace<HeaderOnlyOnStartServer>;
+  SetNameBootstrapServer: DurableObjectNamespace<SetNameBootstrapServer>;
   FacetLikeBootstrapServer: DurableObjectNamespace<FacetLikeBootstrapServer>;
   NameInConstructorServer: DurableObjectNamespace<NameInConstructorServer>;
   Mixed: DurableObjectNamespace<Mixed>;
@@ -281,6 +282,47 @@ export class HeaderOnlyOnStartServer extends Server {
   }
 }
 
+/**
+ * Same scenario as `FacetLikeBootstrapServer`, but uses the sanctioned
+ * `setName()` bootstrap API instead of writing `__ps_name` directly to
+ * storage. Verifies that `setName()` alone is sufficient: it stashes
+ * `#_name` in memory AND persists it to storage so cold-wake fetches
+ * recover the name through `#ensureInitialized()`'s legacy fallback.
+ */
+export class SetNameBootstrapServer 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.setName(name);
+    return { onStartName: this.onStartName };
+  }
+
+  /**
+   * Probe storage from outside the DO to verify `setName()` persisted
+   * the name under the legacy `__ps_name` key.
+   */
+  async readStoredName(): Promise<string | undefined> {
+    return this.ctx.storage.get<string>("__ps_name");
+  }
+
+  onRequest(): Response {
+    return Response.json({
+      name: this.name,
+      onStartName: this.onStartName
+    });
+  }
+}
+
 /**
  * Simulates a framework-level bootstrap pattern (e.g. Cloudflare Agents
  * facets) where the DO is NOT addressed via `idFromName()` — so

packages/partyserver/src/tests/wrangler.jsonc

@@ -91,6 +91,10 @@
         "name": "HeaderOnlyOnStartServer",
         "class_name": "HeaderOnlyOnStartServer"
       },
+      {
+        "name": "SetNameBootstrapServer",
+        "class_name": "SetNameBootstrapServer"
+      },
       {
         "name": "FacetLikeBootstrapServer",
         "class_name": "FacetLikeBootstrapServer"
@@ -125,6 +129,7 @@
         "UriServerInMemory",
         "PropsServer",
         "HeaderOnlyOnStartServer",
+        "SetNameBootstrapServer",
         "FacetLikeBootstrapServer",
         "NameInConstructorServer"
       ]