Document facet bootstrap pattern, no runtime change

Adds README + setName() docstring guidance pointing facet users at the
explicit FacetStartupOptions.id pattern, plus an end-to-end test fixture
(FacetParent / FacetChild) that pins both the implicit-id workerd
contract and the recommended explicit-id behavior. Per the Cloudflare
facet docs, passing `id: someBoundDoNamespace.idFromName(facetName)` to
ctx.facets.get() gives the facet its own ctx.id.name, so partyserver's
existing name getter does the right thing without any setName/__ps_name
override mechanism. The runtime is byte-identical to 0.5.2.

Also bumps sibling packages' devDependency on partyserver from ^0.5.1
to ^0.5.2 for consistency, and tidies CHANGELOG formatting.

Made-with: Cursor

Author: threepointone

.changeset/facet-name-resolution.md

@@ -0,0 +1,17 @@
+---
+"partyserver": patch
+---
+
+Document and test the supported pattern for using PartyServer with [Durable Object Facets](https://developers.cloudflare.com/dynamic-workers/usage/durable-object-facets/). No runtime behavior change.
+
+**Background.** Facets spawned via `ctx.facets.get(name, factory)` _without_ an explicit `id` in `FacetStartupOptions` inherit the parent DO's `ctx.id` — including `ctx.id.name`. PartyServer's `name` getter reads `ctx.id.name` straight through, so on an implicit-id facet `this.name` returns the _parent's_ name rather than the facet's logical name. This is a faithful reflection of the workerd contract, but it's almost never what framework authors expect.
+
+The fix is at the call site, not in PartyServer: pass `id: someBoundDONamespace.idFromName(facetName)` to `ctx.facets.get(...)`. The facet then gets its own native `ctx.id.name === facetName` and PartyServer's `name` getter does the right thing automatically. No `setName()` is required, no `__ps_name` storage record is written, and cold-wake recovery happens for free because the factory re-runs and `idFromName` is deterministic.
+
+This release adds:
+
+- **A "Using PartyServer with Durable Object Facets" section in the README** that walks through the recommended pattern with a code example, calls out the implicit-id footgun explicitly, and documents that plain-string `id` values are not a substitute for `idFromName(facetName)` (workerd treats string ids as `idFromString`-like, so the resulting facet has no `ctx.id.name`).
+- **`setName()` docstring updated** to clarify that facets are NOT a `setName()` use case — point to the explicit-`id` pattern instead. The original `setName()` `ctx.id.name` mismatch throw is preserved as a typo guard for the `idFromName` happy path.
+- **End-to-end facet test coverage** against the real workerd `ctx.facets.get(...)` API. A `FacetParent` / `FacetChild` fixture exercises both the implicit-id path (pinning the runtime contract that `this.name` returns the parent's name in that flow — i.e., behavior-as-documentation so framework authors are unsurprised) and the explicit-id path (recommended; verifies that all reasonable id-construction strategies work and that cold wake recovers without any storage record). Plain-string `id` is also tested; the test asserts it does NOT carry a name, pinning the contract so callers don't get tempted by the type signature.
+
+The runtime behavior of `Server` (the `name` getter, `setName()`, the legacy `__ps_name` hydrate inside `#ensureInitialized()`) is unchanged from 0.5.2.

package-lock.json

@@ -37,6 +37,6 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260424.1",
     "hono": "^4.12.15",
-    "partyserver": "^0.5.1"
+    "partyserver": "^0.5.2"
   }
 }

packages/hono-party/package.json

@@ -22,7 +22,6 @@
   ```
 
   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.
 
@@ -37,7 +36,6 @@
   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.
@@ -52,7 +50,6 @@
   Durable Objects now expose `ctx.id.name` on every entry point (constructor, fetch, alarm, hibernating websocket handlers) when the DO is addressed via `idFromName()`/`getByName()`. PartyServer now uses this as the primary source of `this.name`, which simplifies routing, eliminates storage writes, and makes `this.name` available inside the constructor.
 
   Changes in `partyserver`:
-
   - `this.name` resolves from `this.ctx.id.name`. The apologetic `workerd#2240` error message is gone.
   - `this.name` is now available **inside the constructor** and from class field initializers, not just after `setName()`/`fetch()` has run.
   - `routePartykitRequest` no longer issues a `setName()`/`_initAndFetch()` RPC before `fetch()`. The WebSocket path goes from 2 RPCs to 1; the HTTP path remains 1 RPC. Props, when supplied, are delivered to the DO via the `x-partykit-props` request header, set after `onBeforeConnect`/`onBeforeRequest` hooks run.
@@ -64,7 +61,6 @@
   - When reading `this.name` throws, it is because `ctx.id.name` is undefined and no legacy fallback has populated the name: the DO was addressed via `idFromString()` or `newUniqueId()` (both unsupported), the runtime is too old to expose `ctx.id.name`, or a pre-2026-03-15 alarm fired before the legacy storage fallback ran.
 
   Changes in all affected packages (`partyserver`, `partysub`, `partysync`, `y-partyserver`, `hono-party`):
-
   - `@cloudflare/workers-types` peer dependency bumped from `^4.20240729.0` to `^4.20260424.1`. The old range predates `ctx.id.name` in the type surface.
 
   Not supported: addressing PartyServer DOs via `idFromString()` or `newUniqueId()`. These paths return `ctx.id.name === undefined` inside the DO and will surface as a clear error from `this.name`. PartyServer has always assumed name-based addressing via `getServerByName` / `routePartykitRequest`; this release makes that assumption explicit.
@@ -385,14 +381,12 @@
 ### Patch Changes
 
 - [`528adea`](https://github.com/threepointone/partyserver/commit/528adeaced6dce6e888d2f54cc75c3569bf2c277) Thanks [@threepointone](https://github.com/threepointone)! - some fixes and tweaks
-
   - getServerByName was throwing on all requests
   - `Env` is now an optional arg when defining `Server`
   - `y-partyserver/provider` can now take an optional `prefix` arg to use a custom url to connect
   - `routePartyKitRequest`/`getServerByName` now accepts `jurisdiction`
 
   bonus:
-
   - added a bunch of fixtures
   - added stubs for docs
 

packages/partyserver/CHANGELOG.md

@@ -129,7 +129,9 @@ These methods can be optionally `async`:
 
 ## Properties
 
-- `.name` - (readonly) the server's name, as provided to `getServerByName()` or `routePartykitRequest()`. Resolves from the underlying Durable Object's `ctx.id.name`, so it is available inside every entry point — including the constructor, `onStart()`, `onAlarm()`, and hibernating websocket handlers. This assumes the DO was addressed via `idFromName()`/`getByName()` (which is the only supported way to address PartyServer DOs).
+- `.name` - (readonly) the server's name. Resolves from the underlying Durable Object's `ctx.id.name`, populated whenever the DO is addressed via `idFromName()` / `getByName()` — which is the supported way to address PartyServer DOs. Available inside every entry point including the constructor, `onStart()`, `onAlarm()`, and hibernating websocket handlers. (For the narrow case of legacy DOs bootstrapped via `setName()` — e.g. a `__ps_name` storage record from an older version — that override is recovered automatically. PartyServer no longer writes that record itself for new DOs.)
+
+  DOs addressed via `idFromString()` or `newUniqueId()` without a `setName()` bootstrap are not supported and `.name` will throw.
 
 - `.ctx` - the context object for the Durable Object, containing references to [`storage`](https://developers.cloudflare.com/durable-objects/api/transactional-storage-api/)
 
@@ -176,6 +178,47 @@ export class MyServer extends Server {
     - If it returns `undefined` or `null`, the request will be passed to the server as normal.
   - `onBeforeRequest` - A function that can modify the request before it's passed to the server. This is exactly the same as `onBeforeConnect`, but for HTTP requests.
 
+### Using PartyServer with Durable Object Facets
+
+[Durable Object Facets](https://developers.cloudflare.com/dynamic-workers/usage/durable-object-facets/) let you spawn a child DO from inside a parent's isolate via `ctx.facets.get(name, factory)`. This is useful for frameworks (e.g. Cloudflare Agents sub-agents) that want isolated SQLite storage per facet without exposing a separate Durable Object namespace.
+
+Facets that extend `Server` work, but **you must pass an explicit `id` in `FacetStartupOptions`**. Otherwise the facet inherits the parent DO's `ctx.id` (including `ctx.id.name`), and `this.name` on the facet will return the _parent's_ name — almost never what you want.
+
+```ts
+import { Server } from "partyserver";
+
+export class FacetChild extends Server {
+  // `this.name` here will report `facetName` (NOT the parent's name)
+  // because we passed an explicit `id` at spawn time below.
+  onStart() {
+    console.log("facet started:", this.name);
+  }
+}
+
+export class ParentServer extends Server {
+  async fetch(request: Request) {
+    const facetName = "child-foo";
+
+    // Recommended: construct the id via `ctx.exports[BoundDOClass]`,
+    // which is also a `DurableObjectNamespace`. Any bound DO class
+    // works — the id is opaque + a name; nothing routes through the
+    // namespace at runtime for facets.
+    const id = this.ctx.exports.ParentServer.idFromName(facetName);
+
+    const facet = this.ctx.facets.get(facetName, () => ({
+      class: this.ctx.exports.FacetChild,
+      id // <-- the critical bit
+    }));
+
+    return facet.fetch(request);
+  }
+}
+```
+
+Without the explicit `id`, the facet's `ctx.id.name` is the parent's name, `this.name` returns the parent's name, and `setName(facetName)` throws (it would mismatch `ctx.id.name`). With the explicit `id`, the facet has its own native `ctx.id.name`, no `setName()` is needed, no storage write is involved, and cold wakes recover the name automatically (the factory re-runs and `idFromName(facetName)` is deterministic).
+
+Plain strings (`id: "child-foo"`) are NOT a substitute for `idFromName(facetName)` — workerd treats a string `id` as `idFromString`-like and the resulting facet has no `ctx.id.name`, so `this.name` will throw.
+
 ## Comparison to Erlang/Elixir
 
 "Wait", I hear you say, "this looks a lot like Erlang/Elixir's actor model!" And you'd be right! Durable Objects are inspired by the actor model/[GenServer](https://hexdocs.pm/elixir/1.12/GenServer.html) and aims to provide a similar experience for developers building applications on Cloudflare Workers. It's implemented fully in the infrastructure layer, so you don't have to maintain your own infrastructure.

packages/partyserver/README.md

@@ -551,15 +551,19 @@ export class Server<
    *   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`.
+   *   2. Legacy framework-level bootstrap patterns that write
+   *      `__ps_name` directly (or call `setName()`) before triggering
+   *      `__unsafe_ensureInitialized()` — typically DOs addressed via
+   *      `idFromString()` / `newUniqueId()` plus a name override.
    *
    * 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.
+   *
+   * Not relevant to Cloudflare Agents facets — the recommended
+   * facet pattern passes an explicit `id` in `FacetStartupOptions`,
+   * so the facet has its own `ctx.id.name` and never hits this
+   * fallback. See the README for the full pattern.
    */
   async #hydrateNameFromLegacyStorage(): Promise<void> {
     if (this.#_name) return;
@@ -672,25 +676,43 @@ export class Server<
   /**
    * Establish this server's name and trigger `onStart()`.
    *
-   * Two distinct use cases:
+   * Use cases:
    *
-   *   1. **Framework-level bootstrap of non-`idFromName` DOs** where
-   *      `ctx.id.name` is undefined — for example, Cloudflare Agents
-   *      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.
+   *   1. **Framework-level bootstrap of DOs where `ctx.id.name` is
+   *      undefined** — e.g. DOs addressed via `idFromString()` /
+   *      `newUniqueId()`. `setName()` stashes the name in memory and
+   *      persists it under `__ps_name` so cold-wake invocations
+   *      recover it via `#ensureInitialized()`'s legacy fallback.
+   *   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`.
    *
+   * **Not appropriate for facets.** Cloudflare Agents and any other
+   * framework using `ctx.facets.get(...)` should pass an explicit
+   * `id` in `FacetStartupOptions` so the facet has its own
+   * `ctx.id.name`:
+   *
+   * ```ts
+   * const stub = ctx.facets.get(facetKey, () => ({
+   *   class: ChildClass,
+   *   id: ctx.exports.SomeBoundDOClass.idFromName(facetName),
+   * }));
+   * ```
+   *
+   * Without an explicit `id`, the facet inherits the parent DO's
+   * `ctx.id` (including `ctx.id.name`), and `setName()` will throw
+   * the ctx.id.name-mismatch error because the facet's intended
+   * name differs from the parent's. See
+   * https://developers.cloudflare.com/dynamic-workers/usage/durable-object-facets/
+   * for the `FacetStartupOptions.id` semantics.
+   *
    * @deprecated for callers that address DOs via `idFromName()` /
    * `getByName()`. Still the supported API for framework-level
-   * bootstrap and props delivery.
+   * bootstrap of header/`newUniqueId`-addressed DOs and for
+   * delivering initial `props` to `onStart()`.
    */
   async setName(name: string, props?: Props) {
     if (!name) {