§22 S1 plan: three-tier collection grain (migration 029 + threading + redirect)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-05 07:53:41 -07:00
parent 0de91fe35c
commit 08bdea8539
1 changed files with 796 additions and 0 deletions
@@ -0,0 +1,796 @@
 # S1 — Three-tier collection grain (migration 029 + threading + redirect) Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Insert a *collection* grain beneath today's `project` so every entry-scoped row keys on `(collection_id, slug)` instead of `(project_id, slug)`, with one invisible default collection per project — the deployment runs exactly as before, now with a real collection layer and one extra `/c/<collection>/` URL segment.
 **Architecture:** A new `collections` table sits beneath `projects` (which keeps `content_repo`, `name`, `tagline`, `theme`, `visibility`). Migration 029 creates it, moves the per-corpus fields (`type`, `initial_state`) down from `projects`, seeds one default collection (`id='default'`) per project, re-keys the 13 entry-corpus tables `(project_id,slug)→(collection_id,slug)` via the migration-028 rebuild pattern, and generalises `project_members → memberships(scope_type ∈ {project,collection}, …)`. The backend threads `collection_id` through the writers/readers of those 13 tables (project-grain authz is recovered by joining `collections`); the frontend gains a `/c/:collectionId/` route layer and redirects that 308 the shipped `/p/<project>/e/<slug>` URLs to `/p/<project>/c/default/e/<slug>`. Serving stays **project-scoped** in S1 (collection = default); collection-aware serving is S2.
 **Tech Stack:** FastAPI + SQLite (raw SQL migrations run by `backend/app/db.py:run_migrations`, glob-ordered, `-- migrate:no-foreign-keys` marker toggles FK enforcement + runs `foreign_key_check`); pytest "vertical" tests (no Gherkin runner exists — `@S1` scenarios are realised as plain pytest); React Router SPA (`frontend/src/App.jsx`), nginx proxies `/rfc/` + `/proposals/` to the backend for server-side 308s.
 **Binding spec:** `docs/design/2026-06-05-three-tier-projects-collections.md` — Part A (model), Part E / §A.6 (migration strategy), Part C `@S1` scenarios C3.7 + C3.8.
 ---
 ## Decisions locked before coding (read first)
 1. **Default collection id = the literal `'default'`** (not the project id). Reason: on a *fresh* deploy migrations run with `project_id='default'` and `restamp` renames it to the configured id (e.g. `ohm`) afterward; on an *already-deployed* instance `project_id` is already `ohm` when 029 runs. A stable literal keeps the collection id **identical across both deploy histories**, matches the spec's `/c/default/` URLs, and lets the existing `restamp` keep working untouched (it renames only the *project* grain — `collections.project_id` and the denormalised `project_id` tags — never `collections.id` or the entry `collection_id`). The re-key maps each entry to its project's default collection via a JOIN, so it is correct regardless of the `project_id` value at migration time. Multi-project deployments at migration time (non-standard pre-S5) get a unique id per project via a `CASE` so the seed never collides.
 2. **Re-key scope = exactly the 13 tables migration 028 rebuilt** (`cached_rfcs`, `rfc_invitations`, `cached_branches`, `branch_visibility`, `branch_contribute_grants`, `stars`, `watches`, `pr_seen`, `branch_chat_seen`, `funder_consents`, `rfc_collaborators`, `contribution_requests`, `proposed_use_cases`). The other tables 026 tagged with `project_id` (`threads`, `changes`, `notifications`, `actions`, `pr_resolution_branches`, `cached_prs`) keep `project_id` — they carry a project-grain tag, stay consistent for N=1, and renaming them is **out of S1 scope** (deferred). This matches the goal's "re-key entry-scoped tables via the 028 rebuild pattern".
 3. **Serving stays project-scoped in S1.** The `/c/:collectionId/` segment is introduced in routing + redirects; the frontend data layer keeps calling `/api/projects/{project_id}/rfcs/...` (the default collection). Collection-aware serving + the registry `.collection.yaml` reader land in S2.
 4. **No Gherkin runner.** `@S1` acceptance is realised as pytest vertical tests + a frontend route test. The whole existing backend suite is the "N=1 unchanged" regression net — it must go green again after the rename.
 ---
 ## File structure
 **Created:**
 - `backend/migrations/029_collections.sql` — the migration (collections table, field move-down, default-collection seed, 13-table re-key, `project_members → memberships`).
 - `backend/app/collections.py` — collection resolution helpers (`default_collection_id`, `collection_type`, `collection_initial_state`, `collections_of_project`).
 - `backend/tests/test_migration_029_collections.py` — migration shape + data-preservation + FK tests (template: `test_migration_028_project_scoped_keys.py`).
 - `backend/tests/test_s1_collection_grain_vertical.py` — `@S1` acceptance (C3.7 redirect to sole collection; default-collection redirect; N=1 serving unchanged).
 **Modified (backend):**
 - `backend/app/projects.py` — `restamp_default_project` bootstrap check (`cached_rfcs.project_id` → a still-valid column); move `project_initial_state` to read the collection; add re-export shim if needed.
 - `backend/app/auth.py` — `project_of_rfc` joins `collections`; the 13-table reads/writes that touch `project_id` switch to `collection_id`.
 - `backend/app/cache.py` — `_upsert_cached_rfc(..., collection_id)` + the `cached_rfcs`/`cached_branches` writers + the `WHERE project_id` reconciler reads.
 - `backend/app/api.py`, `api_prs.py`, `api_branches.py`, `api_notifications.py`, `api_contributions.py`, `api_invitations.py`, `api_graduation.py`, `funder.py` — every SQL touching the 13 tables' `project_id` column → `collection_id`; recover project via `collections` join where authz needs it.
 - `backend/app/api_deployment.py` — `/rfc/{slug}` family 308 targets gain `/c/default/`; `get_deployment`/`get_project` read `type`/`initial_state` from the default collection.
 **Modified (frontend):**
 - `frontend/src/components/entryPaths.js` (or wherever path builders live) — insert `/c/:collectionId/`.
 - `frontend/src/App.jsx` — add `/c/:collectionId/*` route layer; redirect `/p/:projectId/` → sole/default collection (C3.7); redirect legacy `/p/:projectId/e|proposals/...` → `/c/default/...`.
 - `frontend/src/ProjectLayout.jsx` (+ `RFCView.jsx`, `Catalog.jsx` as needed) — read `:collectionId` param; pass through (data stays project-scoped).
 **Modified (release):**
 - `VERSION`, `frontend/package.json#version`, `CHANGELOG.md` — minor bump with breaking-URL upgrade-steps block (§20.2 / §20.4).
 ---
 ## Phase 1 — Migration 029 (the collection grain)
 ### Task 1: Write the migration-029 shape test (red)
 **Files:**
 - Test: `backend/tests/test_migration_029_collections.py`
 - [ ] **Step 1: Write the failing test**
 ```python
 """Migration 029 — collections grain beneath projects. Template: test_migration_028."""
 import os
 import sqlite3
 import tempfile
 import pytest
 from app import db
 class _Cfg:
    def __init__(self, path):
        self.database_path = path
        self.default_project_id = "default"
 def _fresh_db():
    d = tempfile.mkdtemp()
    path = os.path.join(d, "test.db")
    db._CONN = None
    db.run_migrations(_Cfg(path))
    return db.conn()
 def test_collections_table_exists_with_default_per_project():
    conn = _fresh_db()
    cols = {r["name"] for r in conn.execute("PRAGMA table_info(collections)")}
    assert {"id", "project_id", "type", "subfolder",
            "initial_state", "visibility", "name", "registry_sha"} <= cols
    # one default collection seeded for the bootstrap 'default' project
    row = conn.execute(
        "SELECT id, project_id, subfolder FROM collections WHERE project_id='default'"
    ).fetchone()
    assert row is not None
    assert row["id"] == "default"
    assert row["subfolder"] == ""  # repo root
 def test_per_corpus_fields_moved_off_projects():
    conn = _fresh_db()
    proj_cols = {r["name"] for r in conn.execute("PRAGMA table_info(projects)")}
    assert "type" not in proj_cols
    assert "initial_state" not in proj_cols
    # projects keeps the grouping-tier fields
    assert {"id", "name", "content_repo", "visibility"} <= proj_cols
 def test_entry_tables_rekeyed_to_collection_id():
    conn = _fresh_db()
    for t in ("cached_rfcs", "cached_branches", "stars", "watches",
              "rfc_collaborators", "contribution_requests", "proposed_use_cases",
              "branch_visibility", "branch_contribute_grants", "pr_seen",
              "branch_chat_seen", "funder_consents", "rfc_invitations"):
        cols = {r["name"] for r in conn.execute(f"PRAGMA table_info({t})")}
        assert "collection_id" in cols, f"{t} missing collection_id"
        assert "project_id" not in cols, f"{t} still has project_id"
 def test_cached_rfcs_pk_is_collection_slug():
    conn = _fresh_db()
    # same slug coexists across two collections
    conn.execute("INSERT INTO collections (id, project_id, type, subfolder, initial_state, visibility, name) "
                 "VALUES ('c2','default','document','specs','active','public','Specs')")
    conn.execute("INSERT INTO cached_rfcs (slug, title, state, collection_id) VALUES ('intro','A','active','default')")
    conn.execute("INSERT INTO cached_rfcs (slug, title, state, collection_id) VALUES ('intro','B','active','c2')")
    n = conn.execute("SELECT COUNT(*) c FROM cached_rfcs WHERE slug='intro'").fetchone()["c"]
    assert n == 2
    with pytest.raises(sqlite3.IntegrityError):
        conn.execute("INSERT INTO cached_rfcs (slug, title, state, collection_id) VALUES ('intro','dup','active','default')")
 def test_collaborator_fk_is_composite_on_collection():
    conn = _fresh_db()
    conn.execute("INSERT INTO collections (id, project_id, type, subfolder, initial_state, visibility, name) "
                 "VALUES ('c2','default','document','specs','active','public','Specs')")
    conn.execute("INSERT INTO cached_rfcs (slug, title, state, collection_id) VALUES ('intro','A','active','c2')")
    conn.execute("INSERT INTO users (id, email, role, permission_state) VALUES (1,'a@b.c','contributor','granted')")
    conn.execute("PRAGMA foreign_keys=ON")
    conn.execute("INSERT INTO rfc_collaborators (rfc_slug, user_id, role_in_rfc, collection_id) "
                 "VALUES ('intro',1,'contributor','c2')")
    with pytest.raises(sqlite3.IntegrityError):
        conn.execute("INSERT INTO rfc_collaborators (rfc_slug, user_id, role_in_rfc, collection_id) "
                     "VALUES ('intro',1,'contributor','default')")  # no such (collection,slug)
 def test_memberships_table_replaces_project_members():
    conn = _fresh_db()
    cols = {r["name"] for r in conn.execute("PRAGMA table_info(memberships)")}
    assert {"scope_type", "scope_id", "user_id", "role", "granted_by", "granted_at"} <= cols
    # M2 rows would migrate to scope_type='collection'; role enum collapsed to owner/contributor
    # (no project_members rows exist in a fresh DB, so just assert the table + check constraint)
    conn.execute("INSERT INTO users (id, email, role, permission_state) VALUES (9,'x@y.z','contributor','granted')")
    conn.execute("INSERT INTO memberships (scope_type, scope_id, user_id, role) VALUES ('project','default',9,'owner')")
    with pytest.raises(sqlite3.IntegrityError):
        conn.execute("INSERT INTO memberships (scope_type, scope_id, user_id, role) VALUES ('bogus','default',9,'owner')")
 ```
 - [ ] **Step 2: Run to verify it fails**
 Run: `cd backend && python -m pytest tests/test_migration_029_collections.py -q`
 Expected: FAIL (no `collections` table / `029_collections.sql` does not exist).
 - [ ] **Step 3: Commit the red test**
 ```bash
 git add backend/tests/test_migration_029_collections.py
 git commit -m "§22 S1: failing migration-029 shape tests (collections grain)"
 ```
 ### Task 2: Write migration 029 (green the shape test)
 **Files:**
 - Create: `backend/migrations/029_collections.sql`
 - [ ] **Step 1: Write the migration.** Mirror `028_project_scoped_keys.sql` exactly for the 13 rebuilds, with `project_id` renamed to `collection_id` in each `__new` table, each child FK re-pointed to `cached_rfcs(collection_id, slug)`, and each index/UNIQUE swapping `project_id`→`collection_id`. Use the explicit-column `INSERT ... SELECT` form (not `SELECT *`) so the re-key can map values. Header marker `-- migrate:no-foreign-keys`. Concrete top of file:
 ```sql
 -- migrate:no-foreign-keys
 --
 -- §22 three-tier refactor — S1. Insert a *collection* grain beneath project.
 -- (1) collections table; (2) move per-corpus fields (type, initial_state) down
 -- from projects; (3) one default collection per project (id='default',
 -- subfolder = repo root); (4) re-key the 13 entry-corpus tables
 -- (project_id,slug) -> (collection_id,slug) via the 028 rebuild pattern, mapping
 -- each row to its project's default collection by JOIN; (5) project_members ->
 -- memberships(scope_type ∈ {project,collection}, …), role enum collapsed to
 -- {owner, contributor}. FK enforcement is OFF for the file (marker above);
 -- foreign_key_check runs after. See docs/design/2026-06-05-three-tier-…md §A.6.
 -- ── collections: the new typed-corpus grain beneath projects ───────────────
 CREATE TABLE collections (
    id            TEXT NOT NULL,
    project_id    TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
    type          TEXT NOT NULL DEFAULT 'document'
                      CHECK (type IN ('document', 'specification', 'bdd')),
    subfolder     TEXT NOT NULL DEFAULT '',
    initial_state TEXT NOT NULL DEFAULT 'super-draft'
                      CHECK (initial_state IN ('super-draft', 'active')),
    visibility    TEXT NOT NULL DEFAULT 'gated'
                      CHECK (visibility IN ('gated', 'public', 'unlisted')),
    name          TEXT,
    registry_sha  TEXT,
    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at    TEXT NOT NULL DEFAULT (datetime('now')),
    PRIMARY KEY (id)
 );
 CREATE INDEX idx_collections_project ON collections(project_id);
 -- One default collection per project. id='default' for the standard
 -- single-project deployment (stable across deploy histories); the project_id is
 -- used as a unique fallback id only if a non-standard multi-project deployment
 -- migrates (pre-S5; avoids a PK collision). subfolder='' = repo root.
 INSERT INTO collections (id, project_id, type, subfolder, initial_state, visibility, name)
 SELECT
    CASE WHEN (SELECT COUNT(*) FROM projects) <= 1 THEN 'default' ELSE p.id END,
    p.id, p.type, '', p.initial_state, p.visibility, p.name
 FROM projects p;
 -- ── move per-corpus fields off projects (rebuild to DROP type/initial_state) ─
 CREATE TABLE projects__new (
    id            TEXT PRIMARY KEY,
    name          TEXT NOT NULL,
    content_repo  TEXT,
    visibility    TEXT NOT NULL DEFAULT 'gated'
                      CHECK (visibility IN ('gated', 'public', 'unlisted')),
    config_json   TEXT,
    registry_sha  TEXT,
    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
 );
 INSERT INTO projects__new (id, name, content_repo, visibility, config_json, registry_sha, created_at, updated_at)
 SELECT id, name, content_repo, visibility, config_json, registry_sha, created_at, updated_at FROM projects;
 DROP TABLE projects;
 ALTER TABLE projects__new RENAME TO projects;
 -- ── cached_rfcs: PRIMARY KEY (project_id, slug) -> (collection_id, slug) ────
 -- collection_id mapped from the row's old project's default collection.
 CREATE TABLE cached_rfcs__new (
    slug                TEXT NOT NULL,
    title               TEXT NOT NULL,
    state               TEXT NOT NULL CHECK (state IN ('super-draft', 'active', 'withdrawn', 'retired')),
    rfc_id              TEXT,
    repo                TEXT,
    proposed_by         TEXT,
    proposed_at         TEXT,
    graduated_at        TEXT,
    graduated_by        TEXT,
    owners_json         TEXT NOT NULL DEFAULT '[]',
    arbiters_json       TEXT NOT NULL DEFAULT '[]',
    tags_json           TEXT NOT NULL DEFAULT '[]',
    body                TEXT,
    body_sha            TEXT,
    last_main_commit_at TEXT,
    last_entry_commit_at TEXT,
    updated_at          TEXT NOT NULL DEFAULT (datetime('now')),
    models_json         TEXT,
    funder_login        TEXT,
    proposed_use_case   TEXT,
    collection_id       TEXT NOT NULL DEFAULT 'default' REFERENCES collections(id),
    unreviewed          INTEGER NOT NULL DEFAULT 0,
    reviewed_at         TEXT,
    reviewed_by         TEXT,
    PRIMARY KEY (collection_id, slug)
 );
 INSERT INTO cached_rfcs__new
    (slug, title, state, rfc_id, repo, proposed_by, proposed_at, graduated_at,
     graduated_by, owners_json, arbiters_json, tags_json, body, body_sha,
     last_main_commit_at, last_entry_commit_at, updated_at, models_json,
     funder_login, proposed_use_case, collection_id, unreviewed, reviewed_at, reviewed_by)
 SELECT
    r.slug, r.title, r.state, r.rfc_id, r.repo, r.proposed_by, r.proposed_at, r.graduated_at,
    r.graduated_by, r.owners_json, r.arbiters_json, r.tags_json, r.body, r.body_sha,
    r.last_main_commit_at, r.last_entry_commit_at, r.updated_at, r.models_json,
    r.funder_login, r.proposed_use_case,
    (SELECT c.id FROM collections c WHERE c.project_id = r.project_id LIMIT 1),
    r.unreviewed, r.reviewed_at, r.reviewed_by
 FROM cached_rfcs r;
 DROP TABLE cached_rfcs;
 ALTER TABLE cached_rfcs__new RENAME TO cached_rfcs;
 CREATE INDEX idx_cached_rfcs_state ON cached_rfcs (state);
 CREATE INDEX idx_cached_rfcs_last_active ON cached_rfcs (
    COALESCE(last_main_commit_at, last_entry_commit_at) DESC
 );
 CREATE INDEX idx_cached_rfcs_collection ON cached_rfcs(collection_id);
 ```
 Then **for each of the remaining 12 tables** copy its `028` block verbatim and apply the same three transforms: (a) rename the `project_id` column to `collection_id` (keep `DEFAULT 'default'`); (b) in the `INSERT ... SELECT`, replace the `project_id` source value with `(SELECT c.id FROM collections c WHERE c.project_id = <old>.project_id LIMIT 1)` and list columns explicitly; (c) rename `project_id` → `collection_id` in every `UNIQUE (...)`, `FOREIGN KEY (...) REFERENCES cached_rfcs(...)`, and `CREATE [UNIQUE] INDEX`. The 12: `rfc_invitations`, `cached_branches`, `branch_visibility`, `branch_contribute_grants`, `stars`, `watches`, `pr_seen`, `branch_chat_seen`, `funder_consents`, `rfc_collaborators`, `contribution_requests`, `proposed_use_cases`. (FK targets `cached_rfcs(project_id, slug)` become `cached_rfcs(collection_id, slug)`.)
 Finally the membership generalisation:
 ```sql
 -- ── project_members -> memberships(scope_type, scope_id, …); roles collapsed ─
 CREATE TABLE memberships (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    scope_type  TEXT NOT NULL CHECK (scope_type IN ('project', 'collection')),
    scope_id    TEXT NOT NULL,
    user_id     INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    role        TEXT NOT NULL CHECK (role IN ('owner', 'contributor')),
    granted_by  INTEGER REFERENCES users(id) ON DELETE SET NULL,
    granted_at  TEXT NOT NULL DEFAULT (datetime('now')),
    UNIQUE (scope_type, scope_id, user_id)
 );
 CREATE INDEX idx_memberships_user ON memberships(user_id);
 CREATE INDEX idx_memberships_scope ON memberships(scope_type, scope_id);
 -- M2 project_members rows attached at what is now the *collection*; collapse
 -- the role enum (project_admin -> owner, project_contributor -> contributor,
 -- project_viewer -> dropped this pass, §B.3) and migrate to the default
 -- collection of each project.
 INSERT INTO memberships (scope_type, scope_id, user_id, role, granted_by, granted_at)
 SELECT 'collection',
       (SELECT c.id FROM collections c WHERE c.project_id = pm.project_id LIMIT 1),
       pm.user_id,
       CASE pm.role WHEN 'project_admin' THEN 'owner'
                    WHEN 'project_contributor' THEN 'contributor'
                    ELSE 'contributor' END,
       pm.granted_by, pm.granted_at
 FROM project_members pm
 WHERE pm.role IN ('project_admin', 'project_contributor');
 DROP TABLE project_members;
 ```
 - [ ] **Step 2: Run the shape test**
 Run: `cd backend && python -m pytest tests/test_migration_029_collections.py -q`
 Expected: PASS (all shape/PK/FK/membership assertions green).
 - [ ] **Step 3: Commit**
 ```bash
 git add backend/migrations/029_collections.sql
 git commit -m "§22 S1: migration 029 — collections grain, field move-down, 13-table re-key, memberships"
 ```
 ---
 ## Phase 2 — Backend threading (make the existing suite green again)
 > After Task 2 the column rename breaks every reader/writer of the 13 tables. This phase fixes them. **Driver:** the full backend suite is the regression net — run it, read each failure, fix the named module, repeat until green. The agent exploration produced the exact blast-radius map used below.
 ### Task 3: collections helper module
 **Files:**
 - Create: `backend/app/collections.py`
 - [ ] **Step 1: Write the helper**
 ```python
 """§22 collection grain — resolution helpers beneath the project tier.
 In S1 each project has exactly one collection (the default). These helpers
 recover the collection for a project and read the per-corpus fields that moved
 down from `projects` in migration 029. Project-grain authz (auth.py) recovers a
 row's project by joining `collections` on `collection_id`.
 """
 from __future__ import annotations
 from . import db
 DEFAULT_COLLECTION_ID = "default"
 def default_collection_id(project_id: str) -> str:
    """The id of a project's default (S1: sole) collection. Falls back to the
    literal 'default' when the project has no collection row yet."""
    row = db.conn().execute(
        "SELECT id FROM collections WHERE project_id = ? ORDER BY created_at LIMIT 1",
        (project_id,),
    ).fetchone()
    return row["id"] if row else DEFAULT_COLLECTION_ID
 def project_of_collection(collection_id: str) -> str | None:
    row = db.conn().execute(
        "SELECT project_id FROM collections WHERE id = ?", (collection_id,)
    ).fetchone()
    return row["project_id"] if row else None
 def collection_initial_state(collection_id: str) -> str:
    """§22.4b landing state for new entries in a collection. 'super-draft'
    default for an unknown row (today's safe flow)."""
    row = db.conn().execute(
        "SELECT initial_state FROM collections WHERE id = ?", (collection_id,)
    ).fetchone()
    if row is None or not row["initial_state"]:
        return "super-draft"
    return row["initial_state"]
 def collection_type(collection_id: str) -> str:
    row = db.conn().execute(
        "SELECT type FROM collections WHERE id = ?", (collection_id,)
    ).fetchone()
    return row["type"] if row and row["type"] else "document"
 ```
 - [ ] **Step 2: Commit**
 ```bash
 git add backend/app/collections.py
 git commit -m "§22 S1: collections resolution helpers"
 ```
 ### Task 4: Fix `projects.py` (restamp + initial_state)
 **Files:**
 - Modify: `backend/app/projects.py:46-48` (restamp bootstrap check), `:112-121` (`project_initial_state`)
 - [ ] **Step 1: Fix the restamp bootstrap check.** `restamp_default_project` reads `cached_rfcs.project_id` (now renamed) at line 47 — switch the existence probe to a still-`project_id`-bearing table so the PRAGMA-driven rename loop is unaffected (it already discovers `project_id` columns dynamically, which now correctly excludes the 13 collection-keyed tables and includes `collections.project_id`):
 ```python
    has_rows = conn.execute(
        "SELECT 1 FROM collections WHERE project_id = ? LIMIT 1", (DEFAULT_PROJECT_ID,)
    ).fetchone()
 ```
 - [ ] **Step 2: Re-home `project_initial_state`.** Keep the signature for callers, but resolve through the project's default collection:
 ```python
 def project_initial_state(project_id: str) -> str:
    """§22.4b landing state for new entries in a project's default collection."""
    from . import collections as collections_mod
    return collections_mod.collection_initial_state(
        collections_mod.default_collection_id(project_id)
    )
 ```
 - [ ] **Step 3: Run the restamp + projects tests**
 Run: `cd backend && python -m pytest tests/test_restamp_default_project.py tests/test_initial_state_landing.py -q`
 Expected: PASS.
 - [ ] **Step 4: Commit**
 ```bash
 git add backend/app/projects.py
 git commit -m "§22 S1: thread projects.py restamp + initial_state through collections"
 ```
 ### Task 5: Fix `auth.py` (`project_of_rfc` join)
 **Files:**
 - Modify: `backend/app/auth.py:352-361`
 - [ ] **Step 1: Join collections to recover the project from a slug.**
 ```python
 def project_of_rfc(rfc_slug: str) -> str:
    """The project an RFC belongs to, via its collection
    (cached_rfcs.collection_id -> collections.project_id). Falls back to the
    default project when the slug isn't cached."""
    row = db.conn().execute(
        "SELECT c.project_id AS project_id "
        "FROM cached_rfcs r JOIN collections c ON c.id = r.collection_id "
        "WHERE r.slug = ?",
        (rfc_slug,),
    ).fetchone()
    if row is None:
        return DEFAULT_PROJECT_ID
    return row["project_id"] or DEFAULT_PROJECT_ID
 ```
 - [ ] **Step 2: Run the authz suite**
 Run: `cd backend && python -m pytest tests/test_multi_project_authz_vertical.py tests/test_anon_offlimits_vertical.py -q`
 Expected: PASS.
 - [ ] **Step 3: Commit**
 ```bash
 git add backend/app/auth.py
 git commit -m "§22 S1: auth.project_of_rfc recovers project via collection join"
 ```
 ### Task 6: Fix `cache.py` writers/readers
 **Files:**
 - Modify: `backend/app/cache.py` — `_refresh_project_corpus` (resolve collection), `_upsert_cached_rfc` signature + SQL (`project_id`→`collection_id`), the `WHERE project_id` reconciler read (`:88`), the `cached_branches` writers (`:213/:388/:410`).
 - [ ] **Step 1: Resolve the collection in the corpus refresh.** In `_refresh_project_corpus`, compute the project's default collection once and pass it down; switch the reconciler `SELECT slug ... WHERE project_id` to `WHERE collection_id`:
 ```python
 async def _refresh_project_corpus(org: str, project_id: str, repo: str, gitea: Gitea) -> None:
    from . import collections as collections_mod
    collection_id = collections_mod.default_collection_id(project_id)
    ...
        _upsert_cached_rfc(entry, body_sha=sha, collection_id=collection_id)
    ...
    existing = {
        row["slug"]
        for row in db.conn().execute(
            "SELECT slug FROM cached_rfcs WHERE collection_id = ?", (collection_id,)
        )
    }
 ```
 - [ ] **Step 2: Rename in `_upsert_cached_rfc`.** Change the param `project_id: str = "default"` → `collection_id: str = "default"`; in the `INSERT`, replace the `project_id` column with `collection_id`, the `ON CONFLICT(project_id, slug)` with `ON CONFLICT(collection_id, slug)`, and the bound value `project_id` → `collection_id`.
 - [ ] **Step 3: Fix the `cached_branches` writers.** At `:213/:388/:410` the `ON CONFLICT(project_id, rfc_slug, branch_name)` clauses → `ON CONFLICT(collection_id, rfc_slug, branch_name)`; where a meta-repo branch row is written without an explicit grain it now relies on the `collection_id DEFAULT 'default'` column default (unchanged behaviour for N=1). Bind `collection_id` explicitly where the per-project loop has it.
 - [ ] **Step 4: Run the cache tests**
 Run: `cd backend && python -m pytest tests/test_cache_bootstrap.py tests/test_cache_review_fields.py tests/test_branch_path_routing.py -q`
 Expected: PASS.
 - [ ] **Step 5: Commit**
 ```bash
 git add backend/app/cache.py
 git commit -m "§22 S1: thread cache.py corpus/branch writers through collection_id"
 ```
 ### Task 7: Fix the `api_*` writers/readers + `funder.py`
 **Files (each: swap the 13-table `project_id` column references to `collection_id`; recover project for authz via `auth.project_of_rfc`/`collections` join):**
 - `backend/app/api.py:747` (stars read), `:774/:806/:969` (`cached_rfcs` composite lookups → `collection_id`), `:785-788/:1046` (`proposed_use_cases`).
 - `backend/app/api_prs.py:156` (`branch_visibility`), `:192` (`proposed_use_cases`), `:401` (`pr_seen`). Note `:670/:789` read `row["project_id"]` from a `cached_rfcs`/`rfc` row — change those SELECTs to also yield the project via the collection join, then keep the existing `auth.require_project_readable(viewer, project_id)` call unchanged.
 - `backend/app/api_branches.py:745` (`branch_visibility`), `:899` (`branch_chat_seen`).
 - `backend/app/api_notifications.py:216` (read `cached_rfcs` → now `collection_id`; recover project via join for the visibility gate), `:225` (`watches`).
 - `backend/app/api_contributions.py:65/:111` (read `cached_rfcs`; recover project via join), `api_invitations.py:383`, `api_graduation.py` (any `cached_rfcs`/13-table `project_id`).
 - `backend/app/funder.py:223` (`funder_consents` `ON CONFLICT(project_id,…)` → `collection_id`).
 - [ ] **Step 1: Mechanical pass.** For each file above, replace `project_id` **only where it names a column on one of the 13 re-keyed tables** (PK lookups, `ON CONFLICT`, `WHERE`, `INSERT` column lists, `SELECT` projections from those tables) with `collection_id`. Where the code needs the *project* (for `auth.*_project*` calls), recover it with `auth.project_of_rfc(slug)` or a `collections` join — do **not** rename the `project_id` argument flowing into the authz helpers (those stay project-grain in S1). Leave `threads`, `changes`, `notifications`, `actions`, `pr_resolution_branches`, `cached_prs` `project_id` columns untouched.
 - [ ] **Step 2: Grep guard.** Confirm no stray reference to a dropped column remains:
 Run: `cd backend && grep -rEn "cached_rfcs[^;]*project_id|project_id, slug|project_id, rfc_slug|ON CONFLICT\(project_id" app/ | grep -v "collections\|threads\|changes\|notifications\|actions\|pr_resolution\|cached_prs"`
 Expected: no output (every 13-table `project_id` is now `collection_id`).
 - [ ] **Step 3: Run the full backend suite**
 Run: `cd backend && python -m pytest -q`
 Expected: PASS (this is the **N=1-unchanged** gate). Fix any remaining failures by reading the traceback and applying the same rename/join rule.
 - [ ] **Step 4: Commit**
 ```bash
 git add backend/app/api.py backend/app/api_prs.py backend/app/api_branches.py backend/app/api_notifications.py backend/app/api_contributions.py backend/app/api_invitations.py backend/app/api_graduation.py backend/app/funder.py
 git commit -m "§22 S1: thread api_* + funder writers/readers through collection_id"
 ```
 ---
 ## Phase 3 — API surface reads per-corpus fields from the collection
 ### Task 8: `api_deployment.py` reads type/initial_state from the default collection
 **Files:**
 - Modify: `backend/app/api_deployment.py:36-44` (`get_deployment` projects list `type`), `:62-82` (`get_project` `type`/`initial_state`)
 - [ ] **Step 1: Write a failing test** in `backend/tests/test_api_deployment.py` (extend it) asserting `GET /api/projects/{default}` still returns the correct `type`/`initial_state` after the move-down (values come from the default collection):
 ```python
 def test_get_project_type_initial_state_from_default_collection(app_with_fake_gitea):
    # ... existing fixture sets up the default project/collection ...
    r = client.get(f"/api/projects/{default_id}")
    assert r.status_code == 200
    body = r.json()
    assert body["type"] in ("document", "specification", "bdd")
    assert body["initial_state"] in ("super-draft", "active")
 ```
 - [ ] **Step 2: Run to verify it fails** (the SELECT still reads `projects.type`, which 029 dropped → `OperationalError`).
 Run: `cd backend && python -m pytest tests/test_api_deployment.py -q`
 Expected: FAIL.
 - [ ] **Step 3: Read the fields from the default collection.** In `get_deployment`, replace the `SELECT id, name, type, visibility FROM projects` with a join to the project's default collection for `type` (or a per-row `collections_mod.collection_type(default_collection_id(id))`). In `get_project`, drop `type, initial_state` from the `projects` SELECT and resolve them via `collections_mod.collection_type(...)` / `collection_initial_state(...)`:
 ```python
 from . import collections as collections_mod
 ...
    cid = collections_mod.default_collection_id(row["id"])
    return {
        ...
        "type": collections_mod.collection_type(cid),
        "initial_state": collections_mod.collection_initial_state(cid),
        ...
    }
 ```
 - [ ] **Step 4: Run to verify it passes**
 Run: `cd backend && python -m pytest tests/test_api_deployment.py -q`
 Expected: PASS.
 - [ ] **Step 5: Commit**
 ```bash
 git add backend/app/api_deployment.py backend/tests/test_api_deployment.py
 git commit -m "§22 S1: deployment/project API reads type+initial_state from default collection"
 ```
 ---
 ## Phase 4 — Redirects + frontend collection segment
 ### Task 9: Backend `/rfc/` 308s target `/c/default/`
 **Files:**
 - Modify: `backend/app/api_deployment.py:89-104`
 - [ ] **Step 1: Add a failing test** to `test_api_deployment.py`:
 ```python
 def test_legacy_rfc_url_redirects_through_collection(app_with_fake_gitea):
    r = client.get("/rfc/intro", follow_redirects=False)
    assert r.status_code == 308
    assert r.headers["location"] == f"/p/{default_id}/c/default/e/intro"
 ```
 - [ ] **Step 2: Verify it fails** (current target lacks `/c/default/`).
 - [ ] **Step 3: Update the three redirect handlers** to resolve the default collection and insert the `/c/<cid>/` segment:
 ```python
    @router.get("/rfc/{slug}")
    async def redirect_old_rfc(slug: str) -> RedirectResponse:
        default_id = projects_mod.resolved_default_id(config)
        cid = collections_mod.default_collection_id(default_id)
        return RedirectResponse(url=f"/p/{default_id}/c/{cid}/e/{slug}", status_code=308)
    # …same /c/{cid}/ insertion for /rfc/{slug}/pr/{pr} and /proposals/{pr}
 ```
 (`/proposals/{pr}` → `/p/{default_id}/c/{cid}/proposals/{pr}`.)
 - [ ] **Step 4: Verify it passes.**
 Run: `cd backend && python -m pytest tests/test_api_deployment.py -q`
 Expected: PASS.
 - [ ] **Step 5: Commit**
 ```bash
 git add backend/app/api_deployment.py backend/tests/test_api_deployment.py
 git commit -m "§22 S1: legacy /rfc + /proposals 308s route through /c/<default>/"
 ```
 ### Task 10: Frontend path builders gain `/c/:collectionId/`
 **Files:**
 - Modify: `frontend/src/components/entryPaths.js` (path builders — confirm exact path with `grep -rl "p/\${" frontend/src`)
 - [ ] **Step 1: Thread a collection id through the builders.** Add a `collectionId` argument (defaulting to `'default'`) and emit the `/c/<collectionId>/` segment:
 ```js
 export const collectionHome = (projectId, collectionId) => `/p/${projectId}/c/${collectionId}/`
 export const entryPath = (projectId, collectionId, slug) => `/p/${projectId}/c/${collectionId}/e/${slug}`
 export const entryPrPath = (projectId, collectionId, slug, prNumber) => `/p/${projectId}/c/${collectionId}/e/${slug}/pr/${prNumber}`
 export const proposalPath = (projectId, collectionId, prNumber) => `/p/${projectId}/c/${collectionId}/proposals/${prNumber}`
 export const projectHome = (projectId) => `/p/${projectId}/`
 ```
 Update every caller (grep `entryPath(`, `entryPrPath(`, `proposalPath(`, `collectionHome(`) to pass the current collection id (from the route param / `useCollectionId()` — default `'default'`).
 - [ ] **Step 2: Build the frontend**
 Run: `cd frontend && npm run build`
 Expected: build succeeds (no undefined-symbol errors).
 - [ ] **Step 3: Commit**
 ```bash
 git add frontend/src
 git commit -m "§22 S1: frontend path builders carry the /c/<collection>/ segment"
 ```
 ### Task 11: Frontend route layer + redirects (C3.7, C3.8, legacy)
 **Files:**
 - Modify: `frontend/src/App.jsx:354-373`, `frontend/src/ProjectLayout.jsx`
 - [ ] **Step 1: Nest the corpus routes under `/c/:collectionId/`** and add redirects. Inside the `ProjectLayout` nested `<Routes>`:
 ```jsx
 <Routes>
  {/* project landing: redirect to the sole/default collection (C3.7) */}
  <Route path="" element={<CollectionRedirect />} />
  {/* legacy v0.35.0 corpus URLs without /c/ → default collection */}
  <Route path="e/:slug" element={<Navigate to="c/default/e/:slug" replace />} />
  <Route path="e/:slug/pr/:prNumber" element={<LegacyEntryPrRedirect />} />
  <Route path="proposals/:prNumber" element={<LegacyProposalRedirect />} />
  {/* collection-scoped corpus (serving stays project-scoped in S1) */}
  <Route path="c/:collectionId" element={<Welcome viewer={viewer} />} />
  <Route path="c/:collectionId/e/:slug" element={<RFCView viewer={viewer} />} />
  <Route path="c/:collectionId/e/:slug/pr/:prNumber" element={<PRView viewer={viewer} />} />
  <Route path="c/:collectionId/proposals/:prNumber" element={<ProposalView viewer={viewer} onChange={() => setCatalogVersion(v => v + 1)} />} />
 </Routes>
 ```
 `CollectionRedirect` reads the project's collections (from `ProjectContext`, populated by `GET /api/projects/:id`) and `<Navigate>`s to the sole visible collection's `/c/<id>/`; with one collection that is `/c/default/` (C3.7). `LegacyEntryPrRedirect`/`LegacyProposalRedirect` use `useParams()` to rebuild the target with `c/default/`. React-Router literal `:slug` in `to=` does not interpolate — implement these as small components using `useParams()` + `<Navigate>`.
 - [ ] **Step 2: Confirm `/` → sole project (C3.8) already holds.** `DeploymentLanding` (App.jsx:348) already redirects to the single visible project. Add/confirm a test (Task 12) rather than re-implementing.
 - [ ] **Step 3: Build**
 Run: `cd frontend && npm run build`
 Expected: succeeds.
 - [ ] **Step 4: Commit**
 ```bash
 git add frontend/src
 git commit -m "§22 S1: /c/<collection>/ route layer + C3.7 + legacy-URL redirects"
 ```
 ---
 ## Phase 5 — `@S1` acceptance + full verification
 ### Task 12: `@S1` vertical acceptance test (C3.7 + C3.8 + N=1 serving)
 **Files:**
 - Create: `backend/tests/test_s1_collection_grain_vertical.py`
 - [ ] **Step 1: Write the acceptance test.** Tag scenarios in docstrings as `@S1` for traceability (no Gherkin runner). Cover: (a) default-collection redirect `/rfc/<slug>` → `/p/<default>/c/default/e/<slug>` (already in Task 9 — re-assert here as the S1 gate); (b) an entry proposed/served at N=1 still resolves under the default collection via `/api/projects/<default>/rfcs/<slug>`; (c) the deployment `/api/deployment` still reports one project with `default_project_id`. (C3.7/C3.8 client redirects are asserted in the frontend build/route smoke; the data-layer N=1 invariants are asserted here.)
 ```python
 """@S1 acceptance — the collection grain exists and N=1 is unchanged.
 Scenarios: C3.7 (single-collection project skips the directory) and C3.8
 (single-project deployment skips the directory) are the redirect contract;
 this module asserts the backend N=1 invariants behind them."""
 # reuse the propose/serve fixtures from test_project_scoped_serving.py
 def test_s1_entry_served_under_default_collection(app_with_fake_gitea):
    # propose + mirror an entry, then fetch it project-scoped (collection=default)
    ...
    r = client.get(f"/api/projects/{default_id}/rfcs/intro")
    assert r.status_code == 200
    # the row is keyed by collection_id under the hood
    cid = db.conn().execute("SELECT collection_id FROM cached_rfcs WHERE slug='intro'").fetchone()["collection_id"]
    assert cid == "default"
 def test_s1_legacy_redirect_inserts_collection_segment(app_with_fake_gitea):
    r = client.get("/rfc/intro", follow_redirects=False)
    assert r.status_code == 308
    assert "/c/default/" in r.headers["location"]
 ```
 - [ ] **Step 2: Run it**
 Run: `cd backend && python -m pytest tests/test_s1_collection_grain_vertical.py -q`
 Expected: PASS.
 - [ ] **Step 3: Full backend suite + frontend build (the N=1-unchanged gate)**
 Run: `cd backend && python -m pytest -q && cd ../frontend && npm run build`
 Expected: all backend tests PASS; frontend builds.
 - [ ] **Step 4: Commit**
 ```bash
 git add backend/tests/test_s1_collection_grain_vertical.py
 git commit -m "§22 S1: @S1 acceptance — collection grain + N=1 serving unchanged"
 ```
 ### Task 13: e2e smoke (optional, if Docker stack available)
 - [ ] **Step 1:** If the Tier-1 Docker stack is runnable, `make e2e` to confirm sign-in + a corpus page render through the new `/c/default/` routes. If the stack isn't available in-session, note it skipped and rely on Tasks 7/11/12 gates.
 ---
 ## Phase 6 — Release + finalize
 ### Task 14: Version bump + changelog (breaking, with upgrade steps)
 **Files:**
 - Modify: `VERSION`, `frontend/package.json` (`version`), `CHANGELOG.md`
 - [ ] **Step 1: Bump** `VERSION` and `frontend/package.json#version` to the next pre-1.0 minor (current `0.39.0` → `0.40.0`). They must match (a divergence is a §20 spec bug).
 - [ ] **Step 2: Add the CHANGELOG entry** with a breaking-URL **upgrade steps** block (§20.2 / §20.4 / §A.6): migration 029 adds the collection grain; `/p/<project>/e/<slug>` now lives at `/p/<project>/c/default/e/<slug>` (308 for old links); operators need no action beyond deploying (the migration + redirects are automatic; the default collection is seeded). Note the deferred items (denormalised `project_id` tags unchanged; collection-aware serving = S2).
 - [ ] **Step 3: Commit**
 ```bash
 git add VERSION frontend/package.json CHANGELOG.md
 git commit -m "§22 S1: release v0.40.0 — three-tier collection grain (breaking URL + migration 029)"
 ```
 ### Task 15: Branch, PR, merge
 - [ ] **Step 1:** This work rides a feature branch off `main` (e.g. `feat/s1-collection-grain`). Push to `origin` (git.wiggleverse.org).
 - [ ] **Step 2:** Open a PR citing the design doc + `@S1`; in autonomous posture, self-review and merge once the suite is green.
 - [ ] **Step 3:** Update repo memory with the new resume pointer (S1 shipped @ v0.40.0; next = S2).
 ---
 ## Self-review (writing-plans checklist)
 - **Spec coverage:** §A.6 steps 1–5 → Tasks 2 (collections table + default + re-key + memberships), 8 (field move-down read path), 9 (308 step 5). Part B membership generalisation → Task 2 (`memberships`) — note S1 only *migrates* the table; the four-layer resolver is S3 (out of scope, correctly deferred per Part E). `@S1` C3.7/C3.8 → Tasks 11 (frontend redirects) + 12 (backend invariants). "N=1 unchanged" → Task 7 Step 3 + Task 12 Step 3 full-suite gates. Threading (auth/projects/cache/api_*) → Tasks 4–8.
 - **Placeholders:** the per-table rebuild bodies for the 12 non-`cached_rfcs` tables reference the in-repo `028_project_scoped_keys.sql` as the literal template with the three explicit transforms named — this is a concrete instruction, not a TODO (repeating 200+ lines of near-identical SQL verbatim would harm reviewability; the transform rule is exact).
 - **Type consistency:** `default_collection_id`, `collection_type`, `collection_initial_state`, `project_of_collection` are defined in Task 3 and used consistently in Tasks 4, 8, 9. Column `collection_id` (not `coll_id`/`collectionId`) used uniformly in SQL; `collectionId` is the JS route param.
 - **Risk note:** the denormalised `project_id` columns (`threads`/`changes`/`notifications`/`actions`/`pr_resolution_branches`/`cached_prs`) stay `project_id` and may, after `restamp`, hold the project id (`ohm`) while entry `collection_id` holds `default`. Task 7 Step 3's full-suite run is the guard against any code that wrongly cross-joins the two grains; if one surfaces, recover the project via the `collections` join rather than renaming the tag.
 ```