feat(sites): link org_sites to projects — site ids are immutable and never reused

[tlgimenes]

What

The database now records which project each site belongs to: org_sites.project_id. Once a project has a site id (slug), no UI and no API request can change it.

Why

The site slug is the site's public id. CDN paths, site tokens, telemetry and asset URLs all carry it. Site tokens can't be revoked, so the rules are:

• Immutable: once a project has a slug, it never changes.
• Never reused across orgs: once a project has used a slug, the slug never goes to another org, and deleting the org doesn't free it. After the project is deleted, the same org may link it to another of its projects.
• One site per project: a partial unique index on project_id enforces it.

Before this PR, the only link between a project and its site was the project's member-editable metadata.siteSlug, or its title for older imports. Any metadata write could rewrite it.

Migration 235-org-sites-project-link

New columns on org_sites:

• project_id text NULL REFERENCES connections(id) ON DELETE SET NULL, unique where not null. Deleting a project keeps the slug reserved for its org; the same org may then link it to another of its projects itself (normal link path). Another org never can.
• linked_at timestamptz NULL, set when the slug is first used and never cleared. A used slug can't be released or moved to another org; a relink keeps the first linked_at. Every row that exists when the migration runs is marked used (linked_at = created_at when no project could be linked): each came from a deco.cx import or backfill, so it's a real public site that may already have tokens out.

organization_id: now nullable, with the FK changed from ON DELETE CASCADE to ON DELETE SET NULL. A row with no org is a tombstone that nobody can claim.

• RESTRICT would break org deletion (auth.api.deleteOrganization).
• CASCADE is what freed slugs for reuse.
• SET NULL keeps org deletion working and keeps the slug reserved forever.

Backfill: it reads projects and never writes them. For each row, it links the single project in the same org whose metadata.siteSlug is exactly the slug. Nothing else is a match: no title fallback, no case- or whitespace-variant.

With 0 or more than 1 candidates, the row stays unlinked (but marked used) and is counted; nothing is guessed. Malformed metadata JSON is counted, never cast in SQL, so one bad row can't abort the migration. The migration logs one summary line:

[migration 235] org_sites: linked=N (planned=…, skipped_deleted_project=…) none=… ambiguous=… unlinked_marked_used=… unparseable_project_metadata=…

It also logs one line per ambiguous slug, listing the slug and its project ids.

To see unlinked rows:

SELECT slug, organization_id, source FROM org_sites
WHERE project_id IS NULL AND organization_id IS NOT NULL;

Locking. Kysely's Migrator runs pending migrations in one transaction, so locks are held until commit while old pods serve. The migration therefore:

1. sets SET LOCAL lock_timeout = '5s' first — a blocked ALTER fails fast and the deploy retries, instead of queueing every writer behind it;
2. plans the backfill with reads only (ACCESS SHARE) before any ALTER;
3. runs the ALTERs (ACCESS EXCLUSIVE on org_sites, SHARE ROW EXCLUSIVE on connections and organization for the FKs; the org FK is added NOT VALID then validated);
4. applies the plan in set-based UPDATE … FROM (VALUES …) batches of 1000, with EXISTS (SELECT 1 FROM connections …) so a project deleted since planning is skipped instead of aborting the deploy.

To size the lock window before merging (no prod DB access from here):

SELECT (SELECT count(*) FROM org_sites) AS org_sites,
       (SELECT count(*) FROM connections WHERE connection_type = 'VIRTUAL') AS projects;

Down: restores the previous shape: NOT NULL with CASCADE, and the new columns and index dropped. It refuses while tombstones exist (dropping them would silently make a deleted org's slugs claimable again); an operator who accepts that deletes them explicitly first.

Storage port (OrgSiteStoragePort)

• getByProject(projectId): new; returns the slug linked to a project.

• link({ slug, organizationId, projectId, by }): new. It links once and is idempotent for the same pair. It refuses with a typed OrgSiteLinkError in these cases:

  Code	When
  not_found	No row for the slug
  reserved	Tombstone
  not_owned	Another org owns the slug
  linked_elsewhere	Another project has the slug
  project_has_other_slug	The project already has a different slug
  project_not_found	Not a project of this org

  A used slug that is unlinked now (its project was deleted, or a legacy row) links like any other: the owning org may link it to one of its projects, linked_at keeps the first use. Another org gets not_owned, a tombstone reserved. Cross-org moves of a used slug aren't supported in code; operators do them by hand in the DB.

• claimSite: refuses a tombstone (reserved).

• reassignSite (deployment-admin "move site here"): refuses tombstones and used slugs (in_use).

• releaseSite: refuses used slugs (in_use).

v7 behaviour on main

Reading a project's site: VirtualMCPStorage findById and the list* methods overlay metadata.siteSlug from the link. The ~180 readers of metadata.siteSlug (tabs, section editors, editor-resolve, admin lists) are unchanged, and they get the linked slug.

• Choice: metadata.siteSlug stays as a mirror. It's a read-time overlay; projects aren't rewritten. Removing it would have touched every reader.
• For projects that aren't linked yet, the stored value still applies.

Authorization: experiments ownership (assertOwnsSite / resolveOwnedAnalyticsSite) now follows the link.

• A linked slug names its project.
• Another org's project that sets the same siteSlug owns nothing.
• A tombstoned slug is nobody's.
• Unlinked projects keep the legacy match, so v7 isn't affected. Known gap, kept for v7 compatibility: an unlinked slug owned by another org still matches this org's look-alike project (see "Decided (2026-10-08)", item 4).

The deployment-admin project list (listSiteProjects) shows only the linked project for a linked slug.

Create (COLLECTION_VIRTUAL_MCP_CREATE, which the deco.cx import uses after /deco-sites/prepare claims the slug): it links the slug when the org owns a free row. Otherwise the slug is stored unlinked, which keeps importing the same storefront into several orgs working, and it still can't change after that.

Org-level gates (hosting, monitor, file configs, infra billing, has-site, notices) already check org_sites ownership and are unchanged.

"Users can't change site slugs via the UI"

Where the UI could set or change a slug

Where	How	Now
Project settings → name (project-identity.tsx)	Renaming a project whose slug was its title	The rename pins the old title as the slug (existing pin-site-slug). With the link, the slug no longer depends on the title. A new read-only Site id row shows it with the note "The site id can't change: CDN paths, tokens and asset URLs use it." — also for a repo-backed legacy project whose slug is still its title.
deco.cx import (import-from-deco-dialog.tsx)	Sets siteSlug from the picked site at create time	This is the one flow that sets it, once, and create links it
Deployment admin → Sites (routes/admin/orgs.tsx)	Remove / move a slug between orgs	Used slugs show In use, with no Remove button and an explanation. "Move site here" is hidden for a used slug, and the server refuses it too
Admin project metadata editor	—	Already allowlists only analyticsSiteSlug; siteSlug is rejected (existing test)

There is no free-text siteSlug input anywhere else in apps/web. Other metadata writers (dev-agent setup, project profile, new-project dialog) never send it, and the API guard covers them anyway.

API enforcement: every write path

Any change refuses with SITE_SLUG_IMMUTABLE ("The site id can't change: CDN paths, tokens and asset URLs use it.").

• COLLECTION_VIRTUAL_MCP_UPDATE (UI, Decopilot, MCP):
  • Refuses changing or clearing a slug, and refuses setting one on a project that has none.
  • Sending the same value is allowed, because forms send the whole metadata back.
  • metadata: null keeps siteSlug, the same way it keeps sandboxMap.
• COLLECTION_CONNECTIONS_UPDATE on a VIRTUAL (project) row: the same check, it puts the slug back if the metadata write left it out, and a title change on a legacy title-slug project pins the slug (as COLLECTION_VIRTUAL_MCP_UPDATE does).
• VirtualMCPStorage.patchMetadata (admin single-key writes): refuses siteSlug in set or unset, behind the admin allow-list.
• VirtualMCPStorage.update: defence in depth for internal writers (sandbox start, reports setup, set-repository, pinned views). It keeps the current slug through any metadata rewrite and throws on a different one.
• Admin POST/DELETE /api/_admin/orgs/:orgId/sites: returns 409 with reserved / in_use and a message. The owned_by_other_org 409 now carries reassignable.

Rollout

The migration is safe on production data.

• Schema changes: two nullable columns and an FK swap on the small org_sites table, under a 5s lock_timeout (see Locking).
• Backfill: planned from reads before any lock, applied in set-based batches; reads only projects in orgs that have sites, and never writes them.
• Previous release: keeps working on the new schema, which the rollback-compat workflow checks. It always inserts an org, ignores the new columns, and its release DELETE still works on unused rows.

v7 is unaffected:

• Unlinked projects behave as before.
• The only behaviour changes are refusals: of slug changes, of releasing or moving any pre-existing or used slug to another org, and of experiments on a tombstoned slug.

Stack

This is the base of the v8 Studio stack, and it can be reviewed and merged on its own against main. On top of it are three parallel tracks, then e2e:

• API track: refactor(api): extract gen-artifact + commit message from commit-coalescer #7800 → chore(api): depend on @decocms/blocks; run Studio CLI by path #7801 → feat(hosted): delivery bucket settings, store and CDN purge #7802 → feat(hosted): CDN draft store and draft-over-main content storage #7804 → feat(hosted): release objects and publishDraft #7806 → feat(hosted): site_editor_content_protocol flag; releases timeline, scope, draft publish status #7809 → feat(hosted): site tokens #7811 → feat(hosted): claim a project's site slug for its org on create #7821 → feat(hosted): admin backfill of site claims #7823 → feat(api): /rpc, v8 draft pointer and publish; hosted routes #7824 → feat(api): proxy /_sandbox/rpc and report draft publish status #7825
• Go daemon track: feat(daemon): JS-exact JSON for the content protocol #7812 → feat(daemon): block keys/file names and protocol errors #7813 → feat(daemon): filesystem content store over the working tree #7814 → feat(daemon): secret guard and ciphertext checks #7815 → feat(daemon): content-protocol RPC router and read methods #7847 → feat(daemon): content-protocol blocks.apply and write paths #7817 → feat(daemon): asset uploads + handler tests #7818 → feat(daemon): mount /_sandbox/rpc and /assets; bounded tree-lock wait #7819 → test(daemon-e2e): content protocol conformance against the daemon #7820
• Web track: feat(web): deco serve connection model + copy #7803 → feat(web): content backend selection (pure) #7805 → feat(web): v8 schema shapes #7807 → feat(web): flat redirects keep unknown fields; pages by manifest #7808 → feat(web): schemaless model #7810 → feat(web): useContentBackend (probe GitHub, sandbox, deco serve) #7816 → feat(web): content-protocol client API; editor hooks use it #7822 → feat(web): protocol fields: browser-encrypted secrets, asset uploads #7826 → feat(web): v8 sites always get the new blocks editor; no async rendering on v8 #7827 → feat(web): deco serve notices #7828 → feat(web): discover a running deco serve on localhost #7829 → feat(web): schemaless content editor #7830 → feat(web): CMS settings model #7831 → feat(web): v8 variant previews through the draft pointer #7832 → feat(web): sections editor and Preview switch on the content backend #7833 → feat(web): Content tab switches on the content backend #7834 → feat(web): the Local draft option connects deco serve #7835 → feat(web): first-run guide for deco serve #7836 → feat(web): account-less /site-editor over deco serve #7837 → feat(web): /site-editor on the org rail #7838 → feat(web): Releases tab for hosted v8 projects #7839 → feat(web): hosted Publish and site tokens #7840
• E2E (on the web track; merge after all three tracks): test(e2e): delivery CDN stub server #7841 → test(e2e): site editor over a deco serve connect link #7842 → test(e2e): content protocol, drafts and publish over GitHub #7843

The top of the stack (#7843) has the same tree as feat/blocks-v8-hosted. It replaces #7728, #7770 and #7766.

Decided (2026-10-08)

1. Every pre-existing slug is permanently used (linked_at = created_at when no project could be linked): never released or moved to another org.
2. After a project is deleted, the same org relinks its own used slug to another of its projects by itself, through the normal claim/link path (no admin). Cross-org relinking isn't supported in code: another org's slug is refused (not_owned), a tombstone (org deleted) is refused (reserved); operators handle those by hand in the DB. The deployment-admin POST /api/_admin/orgs/:orgId/sites/:slug/link endpoint and the relink_requires_admin code are removed.
3. The backfill's title-based match is dropped: it links only an exact metadata.siteSlug match within the org; everything else stays unlinked (and marked used).
4. Known gap, kept: experiments on an unlinked slug another org owns still match this org's look-alike project (v7 behaviour). Refusing it would be a v7 behaviour change for orgs that imported a storefront they don't own in org_sites.

Tests

• apps/api/migrations/235-org-sites-project-link.integration.test.ts runs on a seeded DB and covers:
  • links only an exact metadata.siteSlug match; a title or a case/whitespace variant is never a match
  • unlinked legacy rows are marked used: release and reassign refused; the owning org links one itself, another org can't
  • a planned link to a project deleted since planning is skipped
  • ambiguous and none rows stay unlinked
  • malformed JSON
  • other-org look-alikes
  • org delete leaves a tombstone
  • project delete keeps the slug and linked_at
  • one slug per project
  • down refuses with tombstones; down/up round trip
• apps/api/src/storage/org-sites-link.integration.test.ts covers:
  • every port rule, including the same org relinking after a project is deleted (keeping linked_at) and another org / a tombstone refused
  • tombstone, release and reassign refusals
  • storage overlay and pinning
  • create links or stays unlinked
  • update tool refusals and allowed writes
  • connections-update refusal, and rename through it pins a legacy slug
  • patchMetadata refuses siteSlug
  • experiments ownership, including tombstones
• apps/api/src/tools/virtual/site-slug-guard.test.ts: unit tests for the guard.
• apps/web/src/views/virtual-mcp/settings/project-site-id.test.tsx: checks the read-only site id and its explanation, and which projects show one.
• apps/api/src/api/routes/admin-project-metadata.test.ts: the admin project list prefers the linked project.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WNwbSEePYNcY5YCgqZURig