docs(architecture): add merge benefits and npm-version risk

Cover two further considerations: (1) merging removes privileged
cross-service endpoints (HMAC callback, /_internal lookups) and yields
operational simplicity, and (2) npm peer-dependency clashes are a risk only
if the two *processes* merge, not if they stay separate behind path routing
— bounded anyway by the pnpm non-flat workspace. Distinguish origin-merge
(recommended, no version risk) from process-merge throughout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aspiers

docs/architecture.md

@@ -137,6 +137,32 @@ endpoint to issue an AT Protocol authorization code. For new users, a handle-pic
     upstream already allows — so the one upstream validation that looks like a
     constraint actually _favors_ single-origin.
 
+  Beyond dissolving those costs, collapsing to one origin has **positive**
+  benefits the split forecloses:
+
+  - **Fewer privileged cross-service endpoints.** The split forces the two
+    services to talk over authenticated HTTP: the HMAC-signed
+    `/oauth/epds-callback` and the `/_internal/*` / `/_magic/*` lookup
+    endpoints (e.g. `account-by-email`, `check-email`), each an attack surface
+    that has to be signed, gated, and kept in sync. Co-located on one origin,
+    much of this can become in-process calls with no wire boundary to secure.
+    (Whether to also merge the _processes_ — versus keep two behind path
+    routing — is a separate decision; see the migration doc.)
+
+  - **Operational simplicity.** One origin means one TLS cert, one DNS record,
+    one CSP surface, and one set of cross-origin edge cases to reason about,
+    instead of a parent/subdomain pair whose relationship is itself
+    load-bearing config.
+
+  A **countervailing risk** applies only if the two _processes_ are merged
+  (not if they stay separate behind path routing): sharing one Node runtime
+  could surface npm peer-dependency conflicts between `auth-service`'s
+  `better-auth` and `pds-core`'s `@atproto/*` stack. In practice the repo is a
+  pnpm workspace with a non-flat `node_modules`, so each package already
+  resolves its own versions and the overlap today is minimal (`express`,
+  aligned). The risk is real but bounded, and avoided entirely by the
+  keep-two-processes option.
+
   The remaining real risk is not any of the three benefits but external
   addressability of `auth.<host>`: `authorization_endpoint` is published in AS
   metadata and cached by clients, and `EPDS_LINK_BASE_URL` appears in live

docs/design/single-domain-migration.md

@@ -28,6 +28,47 @@ The routing model is exactly pds-gatekeeper's: **Caddy routes by path**, sending
 auth-service process and everything else to the PDS. The auth-service stays a
 separate process; only its _origin_ changes.
 
+## Two levels of "merge" — keep them distinct
+
+This matters for both benefits and risks, so fix the terms up front:
+
+- **Merge the _origin_ (recommended baseline).** One hostname, Caddy path-routes
+  to two still-separate processes. Dissolves every cross-origin cost; keeps the
+  HMAC trust boundary; carries **no** npm-version risk.
+- **Merge the _processes_ (optional, later).** Fold auth-service into the
+  pds-core Node process. Adds the "fewer privileged endpoints" benefit in full
+  (calls become in-process) but is the only variant that can surface
+  dependency conflicts. Treat as a separate, later decision.
+
+## Positive benefits (beyond deleting costs)
+
+- **Fewer privileged cross-service endpoints.** The split _requires_ the two
+  services to communicate over authenticated HTTP: the HMAC-signed
+  `/oauth/epds-callback` plus the internal lookup endpoints (`/_internal/*`,
+  `/_magic/check-email`, `account-by-email`). Each is an attack surface that
+  must be signed, gated, and version-matched across the boundary. Merging the
+  origin lets some of these relax; merging the processes lets most become
+  in-process calls with no wire boundary at all.
+- **Operational simplicity.** One TLS cert, one DNS record, one CSP surface, one
+  origin's worth of cross-origin edge cases — instead of a parent/subdomain pair
+  whose `endsWith('.'+pdsHostname)` relationship is itself load-bearing config
+  threaded through several modules.
+
+## Risk: npm version clashes (process-merge only)
+
+Applies **only** to the process-merge variant, not the origin-merge baseline.
+
+- Today the repo is a **pnpm workspace** (`pnpm --recursive`) with pnpm's
+  default non-flat `node_modules`, so `auth-service` and `pds-core` already
+  resolve their dependencies independently.
+- Overlap is small: `pds-core` owns the heavy `@atproto/*` stack, `auth-service`
+  owns `better-auth`; the only shared runtime dep is `express ^4.18.2`, already
+  aligned.
+- A single Node process would force one resolution of any shared/peer dep. The
+  realistic conflict surface is a future `express` (or a transitive peer both
+  pull) diverging. Bounded, but a real reason to prefer keeping two processes
+  unless the in-process-call benefit is specifically wanted.
+
 ## What gets deleted
 
 The whole point. These exist solely because of cross-origin-same-site:
@@ -44,6 +85,10 @@ The whole point. These exist solely because of cross-origin-same-site:
    `session-reuse.ts:195-200`, the `parentCookieDomain` derivation in
    `pds-core/src/index.ts:930`, and `authOrigin` derivation in
    `chooser-enrichment.ts`. The two hostnames become one.
+4. **(Process-merge only) some privileged cross-service endpoints** — the
+   `/_internal/*` / `/_magic/*` HTTP lookups become in-process calls. The
+   HMAC-signed `/oauth/epds-callback` can also collapse to an in-process call
+   if the processes merge. See "Two levels of merge" above.
 
 ## What stays