fix(db): reconcile staging's ledger by recovering three out-of-band migrations (#316, #265)

[AndresL230]

Staging's migration ledger has three rows recorded under filenames that exist nowhere in this repo — and git log --all finds nothing for any of them, so they were applied out-of-band. migrate-staging.yml's preflight refuses to apply anything on top of that drift, correctly, which means all 11 pending migrations are stuck, including the fixes for #316 and #265.

on disk 45 | recorded 37 | pending 11
ORPHANS (recorded here, absent from the repo)
0019_newsletter_approved_at.sql <-- NUMBER COLLIDES WITH 0019_conventions_terms_schools.sql
0032_retire_summer_2026.sql <-- NUMBER COLLIDES WITH 0032_rooms_missing_columns.sql
0033_offering_section_not_null.sql <-- NUMBER COLLIDES WITH 0033_realtime_publish_room_messages.sql

Two of them were applied within hours of this being written (2026-08-01 01:55 and 03:51), so this is ongoing drift, not archaeology.

Why transcription, and why these exact filenames

schema_migrations.filename is the primary key, and the runner treats any basename it hasn't recorded as pending. That gives exactly one reconciliation move that doesn't involve hand-editing a live ledger: restore the files under their exact recorded names. Then staging sees them as recorded-and-present (neither pending nor orphan), while prod and every fresh local database see them as pending and apply them for real.

A timestamped name would not work — it would leave the orphan in place and re-run the DDL.

All three are written idempotently, because environments genuinely disagree about whether they ran: staging recorded them, prod got the newsletter column via 0026_ops.sql, and a fresh database gets them here first.

What each one actually does

0019_newsletter_approved_at.sql — a no-op everywhere except the ledger. 0026_ops.sql:30 already carries the column with a comment saying "Absorbed from 0019_newsletter_approved_at (drift fix; prod already has this column)". Restored purely to clear the orphan.

0032_retire_summer_2026.sql — this one changes data and behaviour. It deletes the Summer 2026 term and moves Fall 2026's start_date back to 2026-05-18 to close the 98-day hole that would otherwise open in 0019's deliberately contiguous date cover (current_term() resolves by date; a date in the hole resolves to no term, and resolve_offering(create=True) then can't place an enrollment). Consequence worth stating: a date like today resolved to summer-2026 before and resolves to fall-2026 after. Offerings are repointed before the term row is deleted, since course_offerings.term_id is the only FK into terms (verified against the live schema) and it's ON DELETE RESTRICT.

0033_offering_section_not_null.sql — section becomes NOT NULL DEFAULT ''. This is the one with a real design argument behind it, below.

The section design, and why staging's version wins

0020 made section nullable and course_offerings_unique is UNIQUE (course_id, term_id, section). Plain UNIQUE treats NULLs as distinct, so two NULL-section rows for the same course+term both survive — which is what 0036 patches, with a partial unique index over WHERE section IS NULL.

But NULL was never the only way to say "no section". Every seeder in this repo writes the empty string:

	writes section as
db/seed_staging.py:119	""
db/seed_local_rich.py:140	""
db/e2e_staging_http.py:69	""
services/academics.py::resolve_offering	omits the key → NULL

So a seeded offering and a resolve_offering'd one for the same course+term were two different values, and 0036 — scoped to WHERE section IS NULL — couldn't see the pair. The duplicate-offering bug 0036 exists to prevent walks in through the '' door.

Collapsing NULL into '' removes the second door: one representation of "no section", covered directly by the constraint that was already there. resolve_offering needs no code change — it still omits the key, the DEFAULT supplies '', and a lost race still surfaces as the 409 its existing handler re-selects on. Its docstring and the 409 comment did need updating, since both cited 0036 by number for a guarantee it no longer provides.

0036 is left untouched (it's already applied elsewhere; applied migrations are immutable) and becomes a permanent no-op — a partial index over a predicate no row can satisfy. 20260801062439_drop_dead_null_section_index.sql removes it, so it can't be mistaken for the thing holding the invariant up.

The guard bump

_LEGACY_NUMERIC_COUNT goes 45 → 48, with the reasoning in the file. These aren't newly claimed numbers — the numbers were already spoken for by rows in a live ledger. The count stays closed at 48; a genuinely new NNNN_ file still fails CI.

What this unblocks

Both of these are already fixed in main and blocked solely on the backlog:

• staging: avatars storage bucket is private but code expects public read #316 — 0041_avatars_bucket_public.sql is pending; staging still reports avatars public=false, so every avatar renders broken. That migration's own header says it: "writing this migration does not by itself fix staging — it converges on the next python -m db.migrate run."
• Rewire Gradescope sync onto enrollment-keyed gradebook (post-redesign) #265 — 0042_assignments_source_gradescope.sql is pending; staging's assignments_source_check is still CHECK (source IN ('manual','syllabus')), so every source='gradescope' insert the merged sync code writes would violate it.

Verification

• Backend suite: 1553 passed, 38 skipped. ruff check clean.
• New ordering pins in test_migrations.py: 0033-before-0036 (reversed, 0036 would index live NULL rows and 0033 would then silently empty it), 0036-before-the-drop, and 0019-before-0032 (reversed, the DELETE matches nothing and 0019 re-seeds the term).
• Full local e2e cycle — the real gate here, since it replays the whole chain against an empty database.

Note for whoever does prod

This PR deliberately stops short of prod. 0032 is a product decision about which terms exist, and it will apply there on the next run. Prod's ledger state also needs checking first — it may not have one at all, in which case db.migrate would treat all 48 as pending.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project ybgqdonkoqftwrmweuyv because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@AndresL230, you've reached your PR review limit, so we couldn't start this review.

Next review available in:21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aaf1009-2b6f-414d-babe-894e45e4ff74

📥 Commits

Reviewing files that changed from the base of the PR and between 39204d1 and 6422966.

📒 Files selected for processing (14)

• CLAUDE.md
• backend/db/migrations/0019_newsletter_approved_at.sql
• backend/db/migrations/0032_retire_summer_2026.sql
• backend/db/migrations/0033_offering_section_not_null.sql
• backend/db/migrations/20260801062439_drop_dead_null_section_index.sql
• backend/db/migrations/README.md
• backend/db/seed_local_rich.py
• backend/db/seed_staging.py
• backend/routes/onboarding.py
• backend/services/academics.py
• backend/tests/test_migration_naming.py
• backend/tests/test_migrations.py
• backend/tests/test_seed_staging.py
• frontend/e2e/semester-scope.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	6422966	Commit Preview URL Branch Preview URL	Aug 01 2026, 06:59 AM

[AndresL230]

Code review

Found 4 issues:

1. 0033's backfill can violate course_offerings_unique and abort the entire migration run. course_offerings_unique is UNIQUE (course_id, term_id, section) and Postgres treats NULL as distinct, so (c1, t1, NULL) and (c1, t1, '') coexist legally — which is exactly the mixed state this migration's own comment says exists, since the seeders write '' while resolve_offering wrote NULL. The blind UPDATE collapses that pair onto one key and raises a duplicate-key error. Two NULL rows for the same course+term collide the same way, and 0036's partial index cannot prevent it because 0036 applies after this file. db/migrate.py::apply_migration sends the whole file as one transaction with no per-file recovery, so the failure also stops every migration queued behind it. Neither verification lane can see this: the e2e replay starts from an empty table, and the hermetic suite mocks the DB.

Sapling/backend/db/migrations/0033_offering_section_not_null.sql

Lines 47 to 49 in b2331aa

	UPDATE course_offerings SET section =''WHERE section IS NULL;

2. 0032's repoint has the identical shape. If a course already has an offering in both summer-2026 and fall-2026 with the same section, moving the summer row onto fall-2026 collides on the same constraint. resolve_offering(create=True) never sets section, so every app-created offering shares the identical default — this is not an exotic data shape.

Sapling/backend/db/migrations/0032_retire_summer_2026.sql

Lines 35 to 39 in b2331aa

	-- 1. Move any Summer 2026 offering into Fall 2026 before the term disappears.
	UPDATE course_offerings
	SET term_id ='fall-2026'
	WHERE term_id ='summer-2026';

3. CLAUDE.md and backend/db/migrations/README.md both still say the legacy NNNN_ set is frozen at 45 files. This PR makes it 48 and bumps the guard, but the rationale for the exception lives only in a test-file comment and the PR description — not in either document CLAUDE.md tells readers to trust. (CLAUDE.md says "The 45 existing NNNN_ files are frozen and must never be renamed... Full rationale in backend/db/migrations/README.md".)

Sapling/CLAUDE.md

Lines 86 to 88 in b2331aa

	- All Supabase access goes through `db/connection.py::table()`. Do not instantiate `httpx` clients or import `supabase` directly elsewhere. The one sanctioned exception is `db/migrate.py`, which connects with psycopg to run DDL.
	- Schema changes are append-only migrations in `backend/db/migrations/` (applied via `python -m db.migrate`); never edit an applied migration or run DDL in the Supabase dashboard. **New migrations use a UTC timestamp prefix** — `date -u +%Y%m%d%H%M%S` — because sequential `NNNN_` numbers are claimed at write time and only validated at merge, so concurrent branches collide. The 45 existing `NNNN_` files are frozen and must never be renamed: the ledger keys on basename, so a rename re-runs the migration. Full rationale in `backend/db/migrations/README.md`.
	- Term/offering/enrollment resolution goes through `services/academics.py`. The HTTP boundary keeps the abstract `course_id`; the graph stays on the abstract course, gradebook keys on `enrollment_id`, and study/analytics key on `offering_id`.

4. The new seed comment names the wrong constraint. seed_offerings() upserts with on_conflict="course_id,term_id,section", so course_offerings_unique is the conflict target — it routes into an UPDATE rather than failing. A renamed id would instead fail on enrollments.offering_id's FK (no ON UPDATE, so NO ACTION) when the UPDATE tries to change a referenced id. The conclusion — don't rename the ids — still holds, but for a different reason than stated.

Sapling/backend/db/seed_local_rich.py

Lines 126 to 131 in b2331aa

	(OFF_CS_S26, COURSE_CS, TERM_SPRING_2026, "Dr. Ada Lovelace", "MWF 11:00", "Hall A"),
	# Keeps its `su26` id: 0032 moved Summer offerings into Fall 2026, and the
	# ids are opaque keys, not claims about the term. Renaming them would leave
	# the old rows behind on an existing local database, where the old and new
	# offering would collide on course_offerings_unique (course_id, term_id, '').
	(OFF_ENG_SU26, COURSE_ENG, TERM_FALL_2026, "Prof. Maya Angelou", "MTWTh 10:00", "Hall C"),

Below the bar but worth folding in while these files are open: _PINNED_PAIRS in test_migrations.py wasn't extended for the three duplicate-prefix groups this PR creates; 0019_newsletter_approved_at.sql is pinned by no exact-name assertion, so a rename would keep len(legacy) == 48 and pass CI while silently reopening the orphan; and routes/onboarding.py:92 still describes resolve_offering as "creating a NULL-section offering".

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

Staging's migration ledger has three rows recorded under filenames that exist nowhere in this repo — and git log --all finds nothing for any of them, so they were applied out-of-band. migrate-staging.yml's preflight refuses to apply anything on top of that drift, correctly, which means all 11 pending migrations are stuck, including the fixes for #316 and #265.

on disk 45 | recorded 37 | pending 11
ORPHANS (recorded here, absent from the repo)
0019_newsletter_approved_at.sql <-- NUMBER COLLIDES WITH 0019_conventions_terms_schools.sql
0032_retire_summer_2026.sql <-- NUMBER COLLIDES WITH 0032_rooms_missing_columns.sql
0033_offering_section_not_null.sql <-- NUMBER COLLIDES WITH 0033_realtime_publish_room_messages.sql

Two of them were applied within hours of this being written (2026-08-01 01:55 and 03:51), so this is ongoing drift, not archaeology.

Why transcription, and why these exact filenames

schema_migrations.filename is the primary key, and the runner treats any basename it hasn't recorded as pending. That gives exactly one reconciliation move that doesn't involve hand-editing a live ledger: restore the files under their exact recorded names. Then staging sees them as recorded-and-present (neither pending nor orphan), while prod and every fresh local database see them as pending and apply them for real.

A timestamped name would not work — it would leave the orphan in place and re-run the DDL.

All three are written idempotently, because environments genuinely disagree about whether they ran: staging recorded them, prod got the newsletter column via 0026_ops.sql, and a fresh database gets them here first.

What each one actually does

0019_newsletter_approved_at.sql — a no-op everywhere except the ledger. 0026_ops.sql:30 already carries the column with a comment saying "Absorbed from 0019_newsletter_approved_at (drift fix; prod already has this column)". Restored purely to clear the orphan.

0032_retire_summer_2026.sql — this one changes data and behaviour. It deletes the Summer 2026 term and moves Fall 2026's start_date back to 2026-05-18 to close the 98-day hole that would otherwise open in 0019's deliberately contiguous date cover (current_term() resolves by date; a date in the hole resolves to no term, and resolve_offering(create=True) then can't place an enrollment). Consequence worth stating: a date like today resolved to summer-2026 before and resolves to fall-2026 after. Offerings are repointed before the term row is deleted, since course_offerings.term_id is the only FK into terms (verified against the live schema) and it's ON DELETE RESTRICT.

0033_offering_section_not_null.sql — section becomes NOT NULL DEFAULT ''. This is the one with a real design argument behind it, below.

The section design, and why staging's version wins

0020 made section nullable and course_offerings_unique is UNIQUE (course_id, term_id, section). Plain UNIQUE treats NULLs as distinct, so two NULL-section rows for the same course+term both survive — which is what 0036 patches, with a partial unique index over WHERE section IS NULL.

But NULL was never the only way to say "no section". Every seeder in this repo writes the empty string:

	writes section as
db/seed_staging.py:119	""
db/seed_local_rich.py:140	""
db/e2e_staging_http.py:69	""
services/academics.py::resolve_offering	omits the key → NULL

So a seeded offering and a resolve_offering'd one for the same course+term were two different values, and 0036 — scoped to WHERE section IS NULL — couldn't see the pair. The duplicate-offering bug 0036 exists to prevent walks in through the '' door.

Collapsing NULL into '' removes the second door: one representation of "no section", covered directly by the constraint that was already there. resolve_offering needs no code change — it still omits the key, the DEFAULT supplies '', and a lost race still surfaces as the 409 its existing handler re-selects on. Its docstring and the 409 comment did need updating, since both cited 0036 by number for a guarantee it no longer provides.

0036 is left untouched (it's already applied elsewhere; applied migrations are immutable) and becomes a permanent no-op — a partial index over a predicate no row can satisfy. 20260801062439_drop_dead_null_section_index.sql removes it, so it can't be mistaken for the thing holding the invariant up.

The guard bump

_LEGACY_NUMERIC_COUNT goes 45 → 48, with the reasoning in the file. These aren't newly claimed numbers — the numbers were already spoken for by rows in a live ledger. The count stays closed at 48; a genuinely new NNNN_ file still fails CI.

What this unblocks

Both of these are already fixed in main and blocked solely on the backlog:

• staging: avatars storage bucket is private but code expects public read #316 — 0041_avatars_bucket_public.sql is pending; staging still reports avatars public=false, so every avatar renders broken. That migration's own header says it: "writing this migration does not by itself fix staging — it converges on the next python -m db.migrate run."
• Rewire Gradescope sync onto enrollment-keyed gradebook (post-redesign) #265 — 0042_assignments_source_gradescope.sql is pending; staging's assignments_source_check is still CHECK (source IN ('manual','syllabus')), so every source='gradescope' insert the merged sync code writes would violate it.

Verification

• Backend suite: 1553 passed, 38 skipped. ruff check clean.
• New ordering pins in test_migrations.py: 0033-before-0036 (reversed, 0036 would index live NULL rows and 0033 would then silently empty it), 0036-before-the-drop, and 0019-before-0032 (reversed, the DELETE matches nothing and 0019 re-seeds the term).
• Full local e2e cycle — the real gate here, since it replays the whole chain against an empty database.

Note for whoever does prod

This PR deliberately stops short of prod. 0032 is a product decision about which terms exist, and it will apply there on the next run. Prod's ledger state also needs checking first — it may not have one at all, in which case db.migrate would treat all 48 as pending.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project ybgqdonkoqftwrmweuyv because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@AndresL230, you've reached your PR review limit, so we couldn't start this review.

Next review available in:21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aaf1009-2b6f-414d-babe-894e45e4ff74

📥 Commits

Reviewing files that changed from the base of the PR and between 39204d1 and 6422966.

📒 Files selected for processing (14)

• CLAUDE.md
• backend/db/migrations/0019_newsletter_approved_at.sql
• backend/db/migrations/0032_retire_summer_2026.sql
• backend/db/migrations/0033_offering_section_not_null.sql
• backend/db/migrations/20260801062439_drop_dead_null_section_index.sql
• backend/db/migrations/README.md
• backend/db/seed_local_rich.py
• backend/db/seed_staging.py
• backend/routes/onboarding.py
• backend/services/academics.py
• backend/tests/test_migration_naming.py
• backend/tests/test_migrations.py
• backend/tests/test_seed_staging.py
• frontend/e2e/semester-scope.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	6422966	Commit Preview URL Branch Preview URL	Aug 01 2026, 06:59 AM

[AndresL230]

Code review

Found 4 issues:

1. 0033's backfill can violate course_offerings_unique and abort the entire migration run. course_offerings_unique is UNIQUE (course_id, term_id, section) and Postgres treats NULL as distinct, so (c1, t1, NULL) and (c1, t1, '') coexist legally — which is exactly the mixed state this migration's own comment says exists, since the seeders write '' while resolve_offering wrote NULL. The blind UPDATE collapses that pair onto one key and raises a duplicate-key error. Two NULL rows for the same course+term collide the same way, and 0036's partial index cannot prevent it because 0036 applies after this file. db/migrate.py::apply_migration sends the whole file as one transaction with no per-file recovery, so the failure also stops every migration queued behind it. Neither verification lane can see this: the e2e replay starts from an empty table, and the hermetic suite mocks the DB.

Sapling/backend/db/migrations/0033_offering_section_not_null.sql

Lines 47 to 49 in b2331aa

	UPDATE course_offerings SET section =''WHERE section IS NULL;

2. 0032's repoint has the identical shape. If a course already has an offering in both summer-2026 and fall-2026 with the same section, moving the summer row onto fall-2026 collides on the same constraint. resolve_offering(create=True) never sets section, so every app-created offering shares the identical default — this is not an exotic data shape.

Sapling/backend/db/migrations/0032_retire_summer_2026.sql

Lines 35 to 39 in b2331aa

	-- 1. Move any Summer 2026 offering into Fall 2026 before the term disappears.
	UPDATE course_offerings
	SET term_id ='fall-2026'
	WHERE term_id ='summer-2026';

3. CLAUDE.md and backend/db/migrations/README.md both still say the legacy NNNN_ set is frozen at 45 files. This PR makes it 48 and bumps the guard, but the rationale for the exception lives only in a test-file comment and the PR description — not in either document CLAUDE.md tells readers to trust. (CLAUDE.md says "The 45 existing NNNN_ files are frozen and must never be renamed... Full rationale in backend/db/migrations/README.md".)

Sapling/CLAUDE.md

Lines 86 to 88 in b2331aa

	- All Supabase access goes through `db/connection.py::table()`. Do not instantiate `httpx` clients or import `supabase` directly elsewhere. The one sanctioned exception is `db/migrate.py`, which connects with psycopg to run DDL.
	- Schema changes are append-only migrations in `backend/db/migrations/` (applied via `python -m db.migrate`); never edit an applied migration or run DDL in the Supabase dashboard. **New migrations use a UTC timestamp prefix** — `date -u +%Y%m%d%H%M%S` — because sequential `NNNN_` numbers are claimed at write time and only validated at merge, so concurrent branches collide. The 45 existing `NNNN_` files are frozen and must never be renamed: the ledger keys on basename, so a rename re-runs the migration. Full rationale in `backend/db/migrations/README.md`.
	- Term/offering/enrollment resolution goes through `services/academics.py`. The HTTP boundary keeps the abstract `course_id`; the graph stays on the abstract course, gradebook keys on `enrollment_id`, and study/analytics key on `offering_id`.

4. The new seed comment names the wrong constraint. seed_offerings() upserts with on_conflict="course_id,term_id,section", so course_offerings_unique is the conflict target — it routes into an UPDATE rather than failing. A renamed id would instead fail on enrollments.offering_id's FK (no ON UPDATE, so NO ACTION) when the UPDATE tries to change a referenced id. The conclusion — don't rename the ids — still holds, but for a different reason than stated.

Sapling/backend/db/seed_local_rich.py

Lines 126 to 131 in b2331aa

	(OFF_CS_S26, COURSE_CS, TERM_SPRING_2026, "Dr. Ada Lovelace", "MWF 11:00", "Hall A"),
	# Keeps its `su26` id: 0032 moved Summer offerings into Fall 2026, and the
	# ids are opaque keys, not claims about the term. Renaming them would leave
	# the old rows behind on an existing local database, where the old and new
	# offering would collide on course_offerings_unique (course_id, term_id, '').
	(OFF_ENG_SU26, COURSE_ENG, TERM_FALL_2026, "Prof. Maya Angelou", "MTWTh 10:00", "Hall C"),

Below the bar but worth folding in while these files are open: _PINNED_PAIRS in test_migrations.py wasn't extended for the three duplicate-prefix groups this PR creates; 0019_newsletter_approved_at.sql is pinned by no exact-name assertion, so a rename would keep len(legacy) == 48 and pass CI while silently reopening the orphan; and routes/onboarding.py:92 still describes resolve_offering as "creating a NULL-section offering".

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

Staging's migration ledger has three rows recorded under filenames that exist nowhere in this repo — and git log --all finds nothing for any of them, so they were applied out-of-band. migrate-staging.yml's preflight refuses to apply anything on top of that drift, correctly, which means all 11 pending migrations are stuck, including the fixes for #316 and #265.

on disk 45 | recorded 37 | pending 11
ORPHANS (recorded here, absent from the repo)
0019_newsletter_approved_at.sql <-- NUMBER COLLIDES WITH 0019_conventions_terms_schools.sql
0032_retire_summer_2026.sql <-- NUMBER COLLIDES WITH 0032_rooms_missing_columns.sql
0033_offering_section_not_null.sql <-- NUMBER COLLIDES WITH 0033_realtime_publish_room_messages.sql

Two of them were applied within hours of this being written (2026-08-01 01:55 and 03:51), so this is ongoing drift, not archaeology.

Why transcription, and why these exact filenames

schema_migrations.filename is the primary key, and the runner treats any basename it hasn't recorded as pending. That gives exactly one reconciliation move that doesn't involve hand-editing a live ledger: restore the files under their exact recorded names. Then staging sees them as recorded-and-present (neither pending nor orphan), while prod and every fresh local database see them as pending and apply them for real.

A timestamped name would not work — it would leave the orphan in place and re-run the DDL.

All three are written idempotently, because environments genuinely disagree about whether they ran: staging recorded them, prod got the newsletter column via 0026_ops.sql, and a fresh database gets them here first.

What each one actually does

0019_newsletter_approved_at.sql — a no-op everywhere except the ledger. 0026_ops.sql:30 already carries the column with a comment saying "Absorbed from 0019_newsletter_approved_at (drift fix; prod already has this column)". Restored purely to clear the orphan.

0032_retire_summer_2026.sql — this one changes data and behaviour. It deletes the Summer 2026 term and moves Fall 2026's start_date back to 2026-05-18 to close the 98-day hole that would otherwise open in 0019's deliberately contiguous date cover (current_term() resolves by date; a date in the hole resolves to no term, and resolve_offering(create=True) then can't place an enrollment). Consequence worth stating: a date like today resolved to summer-2026 before and resolves to fall-2026 after. Offerings are repointed before the term row is deleted, since course_offerings.term_id is the only FK into terms (verified against the live schema) and it's ON DELETE RESTRICT.

0033_offering_section_not_null.sql — section becomes NOT NULL DEFAULT ''. This is the one with a real design argument behind it, below.

The section design, and why staging's version wins

0020 made section nullable and course_offerings_unique is UNIQUE (course_id, term_id, section). Plain UNIQUE treats NULLs as distinct, so two NULL-section rows for the same course+term both survive — which is what 0036 patches, with a partial unique index over WHERE section IS NULL.

But NULL was never the only way to say "no section". Every seeder in this repo writes the empty string:

	writes section as
db/seed_staging.py:119	""
db/seed_local_rich.py:140	""
db/e2e_staging_http.py:69	""
services/academics.py::resolve_offering	omits the key → NULL

So a seeded offering and a resolve_offering'd one for the same course+term were two different values, and 0036 — scoped to WHERE section IS NULL — couldn't see the pair. The duplicate-offering bug 0036 exists to prevent walks in through the '' door.

Collapsing NULL into '' removes the second door: one representation of "no section", covered directly by the constraint that was already there. resolve_offering needs no code change — it still omits the key, the DEFAULT supplies '', and a lost race still surfaces as the 409 its existing handler re-selects on. Its docstring and the 409 comment did need updating, since both cited 0036 by number for a guarantee it no longer provides.

0036 is left untouched (it's already applied elsewhere; applied migrations are immutable) and becomes a permanent no-op — a partial index over a predicate no row can satisfy. 20260801062439_drop_dead_null_section_index.sql removes it, so it can't be mistaken for the thing holding the invariant up.

The guard bump

_LEGACY_NUMERIC_COUNT goes 45 → 48, with the reasoning in the file. These aren't newly claimed numbers — the numbers were already spoken for by rows in a live ledger. The count stays closed at 48; a genuinely new NNNN_ file still fails CI.

What this unblocks

Both of these are already fixed in main and blocked solely on the backlog:

• staging: avatars storage bucket is private but code expects public read #316 — 0041_avatars_bucket_public.sql is pending; staging still reports avatars public=false, so every avatar renders broken. That migration's own header says it: "writing this migration does not by itself fix staging — it converges on the next python -m db.migrate run."
• Rewire Gradescope sync onto enrollment-keyed gradebook (post-redesign) #265 — 0042_assignments_source_gradescope.sql is pending; staging's assignments_source_check is still CHECK (source IN ('manual','syllabus')), so every source='gradescope' insert the merged sync code writes would violate it.

Verification

• Backend suite: 1553 passed, 38 skipped. ruff check clean.
• New ordering pins in test_migrations.py: 0033-before-0036 (reversed, 0036 would index live NULL rows and 0033 would then silently empty it), 0036-before-the-drop, and 0019-before-0032 (reversed, the DELETE matches nothing and 0019 re-seeds the term).
• Full local e2e cycle — the real gate here, since it replays the whole chain against an empty database.

Note for whoever does prod

This PR deliberately stops short of prod. 0032 is a product decision about which terms exist, and it will apply there on the next run. Prod's ledger state also needs checking first — it may not have one at all, in which case db.migrate would treat all 48 as pending.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project ybgqdonkoqftwrmweuyv because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@AndresL230, you've reached your PR review limit, so we couldn't start this review.

Next review available in:21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aaf1009-2b6f-414d-babe-894e45e4ff74

📥 Commits

Reviewing files that changed from the base of the PR and between 39204d1 and 6422966.

📒 Files selected for processing (14)

• CLAUDE.md
• backend/db/migrations/0019_newsletter_approved_at.sql
• backend/db/migrations/0032_retire_summer_2026.sql
• backend/db/migrations/0033_offering_section_not_null.sql
• backend/db/migrations/20260801062439_drop_dead_null_section_index.sql
• backend/db/migrations/README.md
• backend/db/seed_local_rich.py
• backend/db/seed_staging.py
• backend/routes/onboarding.py
• backend/services/academics.py
• backend/tests/test_migration_naming.py
• backend/tests/test_migrations.py
• backend/tests/test_seed_staging.py
• frontend/e2e/semester-scope.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	6422966	Commit Preview URL Branch Preview URL	Aug 01 2026, 06:59 AM

[AndresL230]

Code review

Found 4 issues:

1. 0033's backfill can violate course_offerings_unique and abort the entire migration run. course_offerings_unique is UNIQUE (course_id, term_id, section) and Postgres treats NULL as distinct, so (c1, t1, NULL) and (c1, t1, '') coexist legally — which is exactly the mixed state this migration's own comment says exists, since the seeders write '' while resolve_offering wrote NULL. The blind UPDATE collapses that pair onto one key and raises a duplicate-key error. Two NULL rows for the same course+term collide the same way, and 0036's partial index cannot prevent it because 0036 applies after this file. db/migrate.py::apply_migration sends the whole file as one transaction with no per-file recovery, so the failure also stops every migration queued behind it. Neither verification lane can see this: the e2e replay starts from an empty table, and the hermetic suite mocks the DB.

Sapling/backend/db/migrations/0033_offering_section_not_null.sql

Lines 47 to 49 in b2331aa

	UPDATE course_offerings SET section =''WHERE section IS NULL;

2. 0032's repoint has the identical shape. If a course already has an offering in both summer-2026 and fall-2026 with the same section, moving the summer row onto fall-2026 collides on the same constraint. resolve_offering(create=True) never sets section, so every app-created offering shares the identical default — this is not an exotic data shape.

Sapling/backend/db/migrations/0032_retire_summer_2026.sql

Lines 35 to 39 in b2331aa

	-- 1. Move any Summer 2026 offering into Fall 2026 before the term disappears.
	UPDATE course_offerings
	SET term_id ='fall-2026'
	WHERE term_id ='summer-2026';

3. CLAUDE.md and backend/db/migrations/README.md both still say the legacy NNNN_ set is frozen at 45 files. This PR makes it 48 and bumps the guard, but the rationale for the exception lives only in a test-file comment and the PR description — not in either document CLAUDE.md tells readers to trust. (CLAUDE.md says "The 45 existing NNNN_ files are frozen and must never be renamed... Full rationale in backend/db/migrations/README.md".)

Sapling/CLAUDE.md

Lines 86 to 88 in b2331aa

	- All Supabase access goes through `db/connection.py::table()`. Do not instantiate `httpx` clients or import `supabase` directly elsewhere. The one sanctioned exception is `db/migrate.py`, which connects with psycopg to run DDL.
	- Schema changes are append-only migrations in `backend/db/migrations/` (applied via `python -m db.migrate`); never edit an applied migration or run DDL in the Supabase dashboard. **New migrations use a UTC timestamp prefix** — `date -u +%Y%m%d%H%M%S` — because sequential `NNNN_` numbers are claimed at write time and only validated at merge, so concurrent branches collide. The 45 existing `NNNN_` files are frozen and must never be renamed: the ledger keys on basename, so a rename re-runs the migration. Full rationale in `backend/db/migrations/README.md`.
	- Term/offering/enrollment resolution goes through `services/academics.py`. The HTTP boundary keeps the abstract `course_id`; the graph stays on the abstract course, gradebook keys on `enrollment_id`, and study/analytics key on `offering_id`.

4. The new seed comment names the wrong constraint. seed_offerings() upserts with on_conflict="course_id,term_id,section", so course_offerings_unique is the conflict target — it routes into an UPDATE rather than failing. A renamed id would instead fail on enrollments.offering_id's FK (no ON UPDATE, so NO ACTION) when the UPDATE tries to change a referenced id. The conclusion — don't rename the ids — still holds, but for a different reason than stated.

Sapling/backend/db/seed_local_rich.py

Lines 126 to 131 in b2331aa

	(OFF_CS_S26, COURSE_CS, TERM_SPRING_2026, "Dr. Ada Lovelace", "MWF 11:00", "Hall A"),
	# Keeps its `su26` id: 0032 moved Summer offerings into Fall 2026, and the
	# ids are opaque keys, not claims about the term. Renaming them would leave
	# the old rows behind on an existing local database, where the old and new
	# offering would collide on course_offerings_unique (course_id, term_id, '').
	(OFF_ENG_SU26, COURSE_ENG, TERM_FALL_2026, "Prof. Maya Angelou", "MTWTh 10:00", "Hall C"),

Below the bar but worth folding in while these files are open: _PINNED_PAIRS in test_migrations.py wasn't extended for the three duplicate-prefix groups this PR creates; 0019_newsletter_approved_at.sql is pinned by no exact-name assertion, so a rename would keep len(legacy) == 48 and pass CI while silently reopening the orphan; and routes/onboarding.py:92 still describes resolve_offering as "creating a NULL-section offering".

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

Staging's migration ledger has three rows recorded under filenames that exist nowhere in this repo — and git log --all finds nothing for any of them, so they were applied out-of-band. migrate-staging.yml's preflight refuses to apply anything on top of that drift, correctly, which means all 11 pending migrations are stuck, including the fixes for #316 and #265.

on disk 45 | recorded 37 | pending 11
ORPHANS (recorded here, absent from the repo)
0019_newsletter_approved_at.sql <-- NUMBER COLLIDES WITH 0019_conventions_terms_schools.sql
0032_retire_summer_2026.sql <-- NUMBER COLLIDES WITH 0032_rooms_missing_columns.sql
0033_offering_section_not_null.sql <-- NUMBER COLLIDES WITH 0033_realtime_publish_room_messages.sql

Two of them were applied within hours of this being written (2026-08-01 01:55 and 03:51), so this is ongoing drift, not archaeology.

Why transcription, and why these exact filenames

schema_migrations.filename is the primary key, and the runner treats any basename it hasn't recorded as pending. That gives exactly one reconciliation move that doesn't involve hand-editing a live ledger: restore the files under their exact recorded names. Then staging sees them as recorded-and-present (neither pending nor orphan), while prod and every fresh local database see them as pending and apply them for real.

A timestamped name would not work — it would leave the orphan in place and re-run the DDL.

All three are written idempotently, because environments genuinely disagree about whether they ran: staging recorded them, prod got the newsletter column via 0026_ops.sql, and a fresh database gets them here first.

What each one actually does

0019_newsletter_approved_at.sql — a no-op everywhere except the ledger. 0026_ops.sql:30 already carries the column with a comment saying "Absorbed from 0019_newsletter_approved_at (drift fix; prod already has this column)". Restored purely to clear the orphan.

0032_retire_summer_2026.sql — this one changes data and behaviour. It deletes the Summer 2026 term and moves Fall 2026's start_date back to 2026-05-18 to close the 98-day hole that would otherwise open in 0019's deliberately contiguous date cover (current_term() resolves by date; a date in the hole resolves to no term, and resolve_offering(create=True) then can't place an enrollment). Consequence worth stating: a date like today resolved to summer-2026 before and resolves to fall-2026 after. Offerings are repointed before the term row is deleted, since course_offerings.term_id is the only FK into terms (verified against the live schema) and it's ON DELETE RESTRICT.

0033_offering_section_not_null.sql — section becomes NOT NULL DEFAULT ''. This is the one with a real design argument behind it, below.

The section design, and why staging's version wins

0020 made section nullable and course_offerings_unique is UNIQUE (course_id, term_id, section). Plain UNIQUE treats NULLs as distinct, so two NULL-section rows for the same course+term both survive — which is what 0036 patches, with a partial unique index over WHERE section IS NULL.

But NULL was never the only way to say "no section". Every seeder in this repo writes the empty string:

	writes section as
db/seed_staging.py:119	""
db/seed_local_rich.py:140	""
db/e2e_staging_http.py:69	""
services/academics.py::resolve_offering	omits the key → NULL

So a seeded offering and a resolve_offering'd one for the same course+term were two different values, and 0036 — scoped to WHERE section IS NULL — couldn't see the pair. The duplicate-offering bug 0036 exists to prevent walks in through the '' door.

Collapsing NULL into '' removes the second door: one representation of "no section", covered directly by the constraint that was already there. resolve_offering needs no code change — it still omits the key, the DEFAULT supplies '', and a lost race still surfaces as the 409 its existing handler re-selects on. Its docstring and the 409 comment did need updating, since both cited 0036 by number for a guarantee it no longer provides.

0036 is left untouched (it's already applied elsewhere; applied migrations are immutable) and becomes a permanent no-op — a partial index over a predicate no row can satisfy. 20260801062439_drop_dead_null_section_index.sql removes it, so it can't be mistaken for the thing holding the invariant up.

The guard bump

_LEGACY_NUMERIC_COUNT goes 45 → 48, with the reasoning in the file. These aren't newly claimed numbers — the numbers were already spoken for by rows in a live ledger. The count stays closed at 48; a genuinely new NNNN_ file still fails CI.

What this unblocks

Both of these are already fixed in main and blocked solely on the backlog:

• staging: avatars storage bucket is private but code expects public read #316 — 0041_avatars_bucket_public.sql is pending; staging still reports avatars public=false, so every avatar renders broken. That migration's own header says it: "writing this migration does not by itself fix staging — it converges on the next python -m db.migrate run."
• Rewire Gradescope sync onto enrollment-keyed gradebook (post-redesign) #265 — 0042_assignments_source_gradescope.sql is pending; staging's assignments_source_check is still CHECK (source IN ('manual','syllabus')), so every source='gradescope' insert the merged sync code writes would violate it.

Verification

• Backend suite: 1553 passed, 38 skipped. ruff check clean.
• New ordering pins in test_migrations.py: 0033-before-0036 (reversed, 0036 would index live NULL rows and 0033 would then silently empty it), 0036-before-the-drop, and 0019-before-0032 (reversed, the DELETE matches nothing and 0019 re-seeds the term).
• Full local e2e cycle — the real gate here, since it replays the whole chain against an empty database.

Note for whoever does prod

This PR deliberately stops short of prod. 0032 is a product decision about which terms exist, and it will apply there on the next run. Prod's ledger state also needs checking first — it may not have one at all, in which case db.migrate would treat all 48 as pending.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project ybgqdonkoqftwrmweuyv because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@AndresL230, you've reached your PR review limit, so we couldn't start this review.

Next review available in:21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aaf1009-2b6f-414d-babe-894e45e4ff74

📥 Commits

Reviewing files that changed from the base of the PR and between 39204d1 and 6422966.

📒 Files selected for processing (14)

• CLAUDE.md
• backend/db/migrations/0019_newsletter_approved_at.sql
• backend/db/migrations/0032_retire_summer_2026.sql
• backend/db/migrations/0033_offering_section_not_null.sql
• backend/db/migrations/20260801062439_drop_dead_null_section_index.sql
• backend/db/migrations/README.md
• backend/db/seed_local_rich.py
• backend/db/seed_staging.py
• backend/routes/onboarding.py
• backend/services/academics.py
• backend/tests/test_migration_naming.py
• backend/tests/test_migrations.py
• backend/tests/test_seed_staging.py
• frontend/e2e/semester-scope.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	6422966	Commit Preview URL Branch Preview URL	Aug 01 2026, 06:59 AM

[AndresL230]

Code review

Found 4 issues:

1. 0033's backfill can violate course_offerings_unique and abort the entire migration run. course_offerings_unique is UNIQUE (course_id, term_id, section) and Postgres treats NULL as distinct, so (c1, t1, NULL) and (c1, t1, '') coexist legally — which is exactly the mixed state this migration's own comment says exists, since the seeders write '' while resolve_offering wrote NULL. The blind UPDATE collapses that pair onto one key and raises a duplicate-key error. Two NULL rows for the same course+term collide the same way, and 0036's partial index cannot prevent it because 0036 applies after this file. db/migrate.py::apply_migration sends the whole file as one transaction with no per-file recovery, so the failure also stops every migration queued behind it. Neither verification lane can see this: the e2e replay starts from an empty table, and the hermetic suite mocks the DB.

Sapling/backend/db/migrations/0033_offering_section_not_null.sql

Lines 47 to 49 in b2331aa

	UPDATE course_offerings SET section =''WHERE section IS NULL;

2. 0032's repoint has the identical shape. If a course already has an offering in both summer-2026 and fall-2026 with the same section, moving the summer row onto fall-2026 collides on the same constraint. resolve_offering(create=True) never sets section, so every app-created offering shares the identical default — this is not an exotic data shape.

Sapling/backend/db/migrations/0032_retire_summer_2026.sql

Lines 35 to 39 in b2331aa

	-- 1. Move any Summer 2026 offering into Fall 2026 before the term disappears.
	UPDATE course_offerings
	SET term_id ='fall-2026'
	WHERE term_id ='summer-2026';

3. CLAUDE.md and backend/db/migrations/README.md both still say the legacy NNNN_ set is frozen at 45 files. This PR makes it 48 and bumps the guard, but the rationale for the exception lives only in a test-file comment and the PR description — not in either document CLAUDE.md tells readers to trust. (CLAUDE.md says "The 45 existing NNNN_ files are frozen and must never be renamed... Full rationale in backend/db/migrations/README.md".)

Sapling/CLAUDE.md

Lines 86 to 88 in b2331aa

	- All Supabase access goes through `db/connection.py::table()`. Do not instantiate `httpx` clients or import `supabase` directly elsewhere. The one sanctioned exception is `db/migrate.py`, which connects with psycopg to run DDL.
	- Schema changes are append-only migrations in `backend/db/migrations/` (applied via `python -m db.migrate`); never edit an applied migration or run DDL in the Supabase dashboard. **New migrations use a UTC timestamp prefix** — `date -u +%Y%m%d%H%M%S` — because sequential `NNNN_` numbers are claimed at write time and only validated at merge, so concurrent branches collide. The 45 existing `NNNN_` files are frozen and must never be renamed: the ledger keys on basename, so a rename re-runs the migration. Full rationale in `backend/db/migrations/README.md`.
	- Term/offering/enrollment resolution goes through `services/academics.py`. The HTTP boundary keeps the abstract `course_id`; the graph stays on the abstract course, gradebook keys on `enrollment_id`, and study/analytics key on `offering_id`.

4. The new seed comment names the wrong constraint. seed_offerings() upserts with on_conflict="course_id,term_id,section", so course_offerings_unique is the conflict target — it routes into an UPDATE rather than failing. A renamed id would instead fail on enrollments.offering_id's FK (no ON UPDATE, so NO ACTION) when the UPDATE tries to change a referenced id. The conclusion — don't rename the ids — still holds, but for a different reason than stated.

Sapling/backend/db/seed_local_rich.py

Lines 126 to 131 in b2331aa

	(OFF_CS_S26, COURSE_CS, TERM_SPRING_2026, "Dr. Ada Lovelace", "MWF 11:00", "Hall A"),
	# Keeps its `su26` id: 0032 moved Summer offerings into Fall 2026, and the
	# ids are opaque keys, not claims about the term. Renaming them would leave
	# the old rows behind on an existing local database, where the old and new
	# offering would collide on course_offerings_unique (course_id, term_id, '').
	(OFF_ENG_SU26, COURSE_ENG, TERM_FALL_2026, "Prof. Maya Angelou", "MTWTh 10:00", "Hall C"),

Below the bar but worth folding in while these files are open: _PINNED_PAIRS in test_migrations.py wasn't extended for the three duplicate-prefix groups this PR creates; 0019_newsletter_approved_at.sql is pinned by no exact-name assertion, so a rename would keep len(legacy) == 48 and pass CI while silently reopening the orphan; and routes/onboarding.py:92 still describes resolve_offering as "creating a NULL-section offering".

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

Staging's migration ledger has three rows recorded under filenames that exist nowhere in this repo — and git log --all finds nothing for any of them, so they were applied out-of-band. migrate-staging.yml's preflight refuses to apply anything on top of that drift, correctly, which means all 11 pending migrations are stuck, including the fixes for #316 and #265.

on disk 45 | recorded 37 | pending 11
ORPHANS (recorded here, absent from the repo)
0019_newsletter_approved_at.sql <-- NUMBER COLLIDES WITH 0019_conventions_terms_schools.sql
0032_retire_summer_2026.sql <-- NUMBER COLLIDES WITH 0032_rooms_missing_columns.sql
0033_offering_section_not_null.sql <-- NUMBER COLLIDES WITH 0033_realtime_publish_room_messages.sql

Two of them were applied within hours of this being written (2026-08-01 01:55 and 03:51), so this is ongoing drift, not archaeology.

Why transcription, and why these exact filenames

schema_migrations.filename is the primary key, and the runner treats any basename it hasn't recorded as pending. That gives exactly one reconciliation move that doesn't involve hand-editing a live ledger: restore the files under their exact recorded names. Then staging sees them as recorded-and-present (neither pending nor orphan), while prod and every fresh local database see them as pending and apply them for real.

A timestamped name would not work — it would leave the orphan in place and re-run the DDL.

All three are written idempotently, because environments genuinely disagree about whether they ran: staging recorded them, prod got the newsletter column via 0026_ops.sql, and a fresh database gets them here first.

What each one actually does

0019_newsletter_approved_at.sql — a no-op everywhere except the ledger. 0026_ops.sql:30 already carries the column with a comment saying "Absorbed from 0019_newsletter_approved_at (drift fix; prod already has this column)". Restored purely to clear the orphan.

0032_retire_summer_2026.sql — this one changes data and behaviour. It deletes the Summer 2026 term and moves Fall 2026's start_date back to 2026-05-18 to close the 98-day hole that would otherwise open in 0019's deliberately contiguous date cover (current_term() resolves by date; a date in the hole resolves to no term, and resolve_offering(create=True) then can't place an enrollment). Consequence worth stating: a date like today resolved to summer-2026 before and resolves to fall-2026 after. Offerings are repointed before the term row is deleted, since course_offerings.term_id is the only FK into terms (verified against the live schema) and it's ON DELETE RESTRICT.

0033_offering_section_not_null.sql — section becomes NOT NULL DEFAULT ''. This is the one with a real design argument behind it, below.

The section design, and why staging's version wins

0020 made section nullable and course_offerings_unique is UNIQUE (course_id, term_id, section). Plain UNIQUE treats NULLs as distinct, so two NULL-section rows for the same course+term both survive — which is what 0036 patches, with a partial unique index over WHERE section IS NULL.

But NULL was never the only way to say "no section". Every seeder in this repo writes the empty string:

	writes section as
db/seed_staging.py:119	""
db/seed_local_rich.py:140	""
db/e2e_staging_http.py:69	""
services/academics.py::resolve_offering	omits the key → NULL

So a seeded offering and a resolve_offering'd one for the same course+term were two different values, and 0036 — scoped to WHERE section IS NULL — couldn't see the pair. The duplicate-offering bug 0036 exists to prevent walks in through the '' door.

Collapsing NULL into '' removes the second door: one representation of "no section", covered directly by the constraint that was already there. resolve_offering needs no code change — it still omits the key, the DEFAULT supplies '', and a lost race still surfaces as the 409 its existing handler re-selects on. Its docstring and the 409 comment did need updating, since both cited 0036 by number for a guarantee it no longer provides.

0036 is left untouched (it's already applied elsewhere; applied migrations are immutable) and becomes a permanent no-op — a partial index over a predicate no row can satisfy. 20260801062439_drop_dead_null_section_index.sql removes it, so it can't be mistaken for the thing holding the invariant up.

The guard bump

_LEGACY_NUMERIC_COUNT goes 45 → 48, with the reasoning in the file. These aren't newly claimed numbers — the numbers were already spoken for by rows in a live ledger. The count stays closed at 48; a genuinely new NNNN_ file still fails CI.

What this unblocks

Both of these are already fixed in main and blocked solely on the backlog:

• staging: avatars storage bucket is private but code expects public read #316 — 0041_avatars_bucket_public.sql is pending; staging still reports avatars public=false, so every avatar renders broken. That migration's own header says it: "writing this migration does not by itself fix staging — it converges on the next python -m db.migrate run."
• Rewire Gradescope sync onto enrollment-keyed gradebook (post-redesign) #265 — 0042_assignments_source_gradescope.sql is pending; staging's assignments_source_check is still CHECK (source IN ('manual','syllabus')), so every source='gradescope' insert the merged sync code writes would violate it.

Verification

• Backend suite: 1553 passed, 38 skipped. ruff check clean.
• New ordering pins in test_migrations.py: 0033-before-0036 (reversed, 0036 would index live NULL rows and 0033 would then silently empty it), 0036-before-the-drop, and 0019-before-0032 (reversed, the DELETE matches nothing and 0019 re-seeds the term).
• Full local e2e cycle — the real gate here, since it replays the whole chain against an empty database.

Note for whoever does prod

This PR deliberately stops short of prod. 0032 is a product decision about which terms exist, and it will apply there on the next run. Prod's ledger state also needs checking first — it may not have one at all, in which case db.migrate would treat all 48 as pending.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project ybgqdonkoqftwrmweuyv because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@AndresL230, you've reached your PR review limit, so we couldn't start this review.

Next review available in:21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aaf1009-2b6f-414d-babe-894e45e4ff74

📥 Commits

Reviewing files that changed from the base of the PR and between 39204d1 and 6422966.

📒 Files selected for processing (14)

• CLAUDE.md
• backend/db/migrations/0019_newsletter_approved_at.sql
• backend/db/migrations/0032_retire_summer_2026.sql
• backend/db/migrations/0033_offering_section_not_null.sql
• backend/db/migrations/20260801062439_drop_dead_null_section_index.sql
• backend/db/migrations/README.md
• backend/db/seed_local_rich.py
• backend/db/seed_staging.py
• backend/routes/onboarding.py
• backend/services/academics.py
• backend/tests/test_migration_naming.py
• backend/tests/test_migrations.py
• backend/tests/test_seed_staging.py
• frontend/e2e/semester-scope.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	6422966	Commit Preview URL Branch Preview URL	Aug 01 2026, 06:59 AM

[AndresL230]

Code review

Found 4 issues:

1. 0033's backfill can violate course_offerings_unique and abort the entire migration run. course_offerings_unique is UNIQUE (course_id, term_id, section) and Postgres treats NULL as distinct, so (c1, t1, NULL) and (c1, t1, '') coexist legally — which is exactly the mixed state this migration's own comment says exists, since the seeders write '' while resolve_offering wrote NULL. The blind UPDATE collapses that pair onto one key and raises a duplicate-key error. Two NULL rows for the same course+term collide the same way, and 0036's partial index cannot prevent it because 0036 applies after this file. db/migrate.py::apply_migration sends the whole file as one transaction with no per-file recovery, so the failure also stops every migration queued behind it. Neither verification lane can see this: the e2e replay starts from an empty table, and the hermetic suite mocks the DB.

Sapling/backend/db/migrations/0033_offering_section_not_null.sql

Lines 47 to 49 in b2331aa

	UPDATE course_offerings SET section =''WHERE section IS NULL;

2. 0032's repoint has the identical shape. If a course already has an offering in both summer-2026 and fall-2026 with the same section, moving the summer row onto fall-2026 collides on the same constraint. resolve_offering(create=True) never sets section, so every app-created offering shares the identical default — this is not an exotic data shape.

Sapling/backend/db/migrations/0032_retire_summer_2026.sql

Lines 35 to 39 in b2331aa

	-- 1. Move any Summer 2026 offering into Fall 2026 before the term disappears.
	UPDATE course_offerings
	SET term_id ='fall-2026'
	WHERE term_id ='summer-2026';

3. CLAUDE.md and backend/db/migrations/README.md both still say the legacy NNNN_ set is frozen at 45 files. This PR makes it 48 and bumps the guard, but the rationale for the exception lives only in a test-file comment and the PR description — not in either document CLAUDE.md tells readers to trust. (CLAUDE.md says "The 45 existing NNNN_ files are frozen and must never be renamed... Full rationale in backend/db/migrations/README.md".)

Sapling/CLAUDE.md

Lines 86 to 88 in b2331aa

	- All Supabase access goes through `db/connection.py::table()`. Do not instantiate `httpx` clients or import `supabase` directly elsewhere. The one sanctioned exception is `db/migrate.py`, which connects with psycopg to run DDL.
	- Schema changes are append-only migrations in `backend/db/migrations/` (applied via `python -m db.migrate`); never edit an applied migration or run DDL in the Supabase dashboard. **New migrations use a UTC timestamp prefix** — `date -u +%Y%m%d%H%M%S` — because sequential `NNNN_` numbers are claimed at write time and only validated at merge, so concurrent branches collide. The 45 existing `NNNN_` files are frozen and must never be renamed: the ledger keys on basename, so a rename re-runs the migration. Full rationale in `backend/db/migrations/README.md`.
	- Term/offering/enrollment resolution goes through `services/academics.py`. The HTTP boundary keeps the abstract `course_id`; the graph stays on the abstract course, gradebook keys on `enrollment_id`, and study/analytics key on `offering_id`.

4. The new seed comment names the wrong constraint. seed_offerings() upserts with on_conflict="course_id,term_id,section", so course_offerings_unique is the conflict target — it routes into an UPDATE rather than failing. A renamed id would instead fail on enrollments.offering_id's FK (no ON UPDATE, so NO ACTION) when the UPDATE tries to change a referenced id. The conclusion — don't rename the ids — still holds, but for a different reason than stated.

Sapling/backend/db/seed_local_rich.py

Lines 126 to 131 in b2331aa

	(OFF_CS_S26, COURSE_CS, TERM_SPRING_2026, "Dr. Ada Lovelace", "MWF 11:00", "Hall A"),
	# Keeps its `su26` id: 0032 moved Summer offerings into Fall 2026, and the
	# ids are opaque keys, not claims about the term. Renaming them would leave
	# the old rows behind on an existing local database, where the old and new
	# offering would collide on course_offerings_unique (course_id, term_id, '').
	(OFF_ENG_SU26, COURSE_ENG, TERM_FALL_2026, "Prof. Maya Angelou", "MTWTh 10:00", "Hall C"),

Below the bar but worth folding in while these files are open: _PINNED_PAIRS in test_migrations.py wasn't extended for the three duplicate-prefix groups this PR creates; 0019_newsletter_approved_at.sql is pinned by no exact-name assertion, so a rename would keep len(legacy) == 48 and pass CI while silently reopening the orphan; and routes/onboarding.py:92 still describes resolve_offering as "creating a NULL-section offering".

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

Staging's migration ledger has three rows recorded under filenames that exist nowhere in this repo — and git log --all finds nothing for any of them, so they were applied out-of-band. migrate-staging.yml's preflight refuses to apply anything on top of that drift, correctly, which means all 11 pending migrations are stuck, including the fixes for #316 and #265.

on disk 45 | recorded 37 | pending 11
ORPHANS (recorded here, absent from the repo)
0019_newsletter_approved_at.sql <-- NUMBER COLLIDES WITH 0019_conventions_terms_schools.sql
0032_retire_summer_2026.sql <-- NUMBER COLLIDES WITH 0032_rooms_missing_columns.sql
0033_offering_section_not_null.sql <-- NUMBER COLLIDES WITH 0033_realtime_publish_room_messages.sql

Two of them were applied within hours of this being written (2026-08-01 01:55 and 03:51), so this is ongoing drift, not archaeology.

Why transcription, and why these exact filenames

schema_migrations.filename is the primary key, and the runner treats any basename it hasn't recorded as pending. That gives exactly one reconciliation move that doesn't involve hand-editing a live ledger: restore the files under their exact recorded names. Then staging sees them as recorded-and-present (neither pending nor orphan), while prod and every fresh local database see them as pending and apply them for real.

A timestamped name would not work — it would leave the orphan in place and re-run the DDL.

All three are written idempotently, because environments genuinely disagree about whether they ran: staging recorded them, prod got the newsletter column via 0026_ops.sql, and a fresh database gets them here first.

What each one actually does

0019_newsletter_approved_at.sql — a no-op everywhere except the ledger. 0026_ops.sql:30 already carries the column with a comment saying "Absorbed from 0019_newsletter_approved_at (drift fix; prod already has this column)". Restored purely to clear the orphan.

0032_retire_summer_2026.sql — this one changes data and behaviour. It deletes the Summer 2026 term and moves Fall 2026's start_date back to 2026-05-18 to close the 98-day hole that would otherwise open in 0019's deliberately contiguous date cover (current_term() resolves by date; a date in the hole resolves to no term, and resolve_offering(create=True) then can't place an enrollment). Consequence worth stating: a date like today resolved to summer-2026 before and resolves to fall-2026 after. Offerings are repointed before the term row is deleted, since course_offerings.term_id is the only FK into terms (verified against the live schema) and it's ON DELETE RESTRICT.

0033_offering_section_not_null.sql — section becomes NOT NULL DEFAULT ''. This is the one with a real design argument behind it, below.

The section design, and why staging's version wins

0020 made section nullable and course_offerings_unique is UNIQUE (course_id, term_id, section). Plain UNIQUE treats NULLs as distinct, so two NULL-section rows for the same course+term both survive — which is what 0036 patches, with a partial unique index over WHERE section IS NULL.

But NULL was never the only way to say "no section". Every seeder in this repo writes the empty string:

	writes section as
db/seed_staging.py:119	""
db/seed_local_rich.py:140	""
db/e2e_staging_http.py:69	""
services/academics.py::resolve_offering	omits the key → NULL

So a seeded offering and a resolve_offering'd one for the same course+term were two different values, and 0036 — scoped to WHERE section IS NULL — couldn't see the pair. The duplicate-offering bug 0036 exists to prevent walks in through the '' door.

Collapsing NULL into '' removes the second door: one representation of "no section", covered directly by the constraint that was already there. resolve_offering needs no code change — it still omits the key, the DEFAULT supplies '', and a lost race still surfaces as the 409 its existing handler re-selects on. Its docstring and the 409 comment did need updating, since both cited 0036 by number for a guarantee it no longer provides.

0036 is left untouched (it's already applied elsewhere; applied migrations are immutable) and becomes a permanent no-op — a partial index over a predicate no row can satisfy. 20260801062439_drop_dead_null_section_index.sql removes it, so it can't be mistaken for the thing holding the invariant up.

The guard bump

_LEGACY_NUMERIC_COUNT goes 45 → 48, with the reasoning in the file. These aren't newly claimed numbers — the numbers were already spoken for by rows in a live ledger. The count stays closed at 48; a genuinely new NNNN_ file still fails CI.

What this unblocks

Both of these are already fixed in main and blocked solely on the backlog:

• staging: avatars storage bucket is private but code expects public read #316 — 0041_avatars_bucket_public.sql is pending; staging still reports avatars public=false, so every avatar renders broken. That migration's own header says it: "writing this migration does not by itself fix staging — it converges on the next python -m db.migrate run."
• Rewire Gradescope sync onto enrollment-keyed gradebook (post-redesign) #265 — 0042_assignments_source_gradescope.sql is pending; staging's assignments_source_check is still CHECK (source IN ('manual','syllabus')), so every source='gradescope' insert the merged sync code writes would violate it.

Verification

• Backend suite: 1553 passed, 38 skipped. ruff check clean.
• New ordering pins in test_migrations.py: 0033-before-0036 (reversed, 0036 would index live NULL rows and 0033 would then silently empty it), 0036-before-the-drop, and 0019-before-0032 (reversed, the DELETE matches nothing and 0019 re-seeds the term).
• Full local e2e cycle — the real gate here, since it replays the whole chain against an empty database.

Note for whoever does prod

This PR deliberately stops short of prod. 0032 is a product decision about which terms exist, and it will apply there on the next run. Prod's ledger state also needs checking first — it may not have one at all, in which case db.migrate would treat all 48 as pending.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project ybgqdonkoqftwrmweuyv because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@AndresL230, you've reached your PR review limit, so we couldn't start this review.

Next review available in:21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aaf1009-2b6f-414d-babe-894e45e4ff74

📥 Commits

Reviewing files that changed from the base of the PR and between 39204d1 and 6422966.

📒 Files selected for processing (14)

• CLAUDE.md
• backend/db/migrations/0019_newsletter_approved_at.sql
• backend/db/migrations/0032_retire_summer_2026.sql
• backend/db/migrations/0033_offering_section_not_null.sql
• backend/db/migrations/20260801062439_drop_dead_null_section_index.sql
• backend/db/migrations/README.md
• backend/db/seed_local_rich.py
• backend/db/seed_staging.py
• backend/routes/onboarding.py
• backend/services/academics.py
• backend/tests/test_migration_naming.py
• backend/tests/test_migrations.py
• backend/tests/test_seed_staging.py
• frontend/e2e/semester-scope.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	6422966	Commit Preview URL Branch Preview URL	Aug 01 2026, 06:59 AM

[AndresL230]

Code review

Found 4 issues:

1. 0033's backfill can violate course_offerings_unique and abort the entire migration run. course_offerings_unique is UNIQUE (course_id, term_id, section) and Postgres treats NULL as distinct, so (c1, t1, NULL) and (c1, t1, '') coexist legally — which is exactly the mixed state this migration's own comment says exists, since the seeders write '' while resolve_offering wrote NULL. The blind UPDATE collapses that pair onto one key and raises a duplicate-key error. Two NULL rows for the same course+term collide the same way, and 0036's partial index cannot prevent it because 0036 applies after this file. db/migrate.py::apply_migration sends the whole file as one transaction with no per-file recovery, so the failure also stops every migration queued behind it. Neither verification lane can see this: the e2e replay starts from an empty table, and the hermetic suite mocks the DB.

Sapling/backend/db/migrations/0033_offering_section_not_null.sql

Lines 47 to 49 in b2331aa

	UPDATE course_offerings SET section =''WHERE section IS NULL;

2. 0032's repoint has the identical shape. If a course already has an offering in both summer-2026 and fall-2026 with the same section, moving the summer row onto fall-2026 collides on the same constraint. resolve_offering(create=True) never sets section, so every app-created offering shares the identical default — this is not an exotic data shape.

Sapling/backend/db/migrations/0032_retire_summer_2026.sql

Lines 35 to 39 in b2331aa

	-- 1. Move any Summer 2026 offering into Fall 2026 before the term disappears.
	UPDATE course_offerings
	SET term_id ='fall-2026'
	WHERE term_id ='summer-2026';

3. CLAUDE.md and backend/db/migrations/README.md both still say the legacy NNNN_ set is frozen at 45 files. This PR makes it 48 and bumps the guard, but the rationale for the exception lives only in a test-file comment and the PR description — not in either document CLAUDE.md tells readers to trust. (CLAUDE.md says "The 45 existing NNNN_ files are frozen and must never be renamed... Full rationale in backend/db/migrations/README.md".)

Sapling/CLAUDE.md

Lines 86 to 88 in b2331aa

	- All Supabase access goes through `db/connection.py::table()`. Do not instantiate `httpx` clients or import `supabase` directly elsewhere. The one sanctioned exception is `db/migrate.py`, which connects with psycopg to run DDL.
	- Schema changes are append-only migrations in `backend/db/migrations/` (applied via `python -m db.migrate`); never edit an applied migration or run DDL in the Supabase dashboard. **New migrations use a UTC timestamp prefix** — `date -u +%Y%m%d%H%M%S` — because sequential `NNNN_` numbers are claimed at write time and only validated at merge, so concurrent branches collide. The 45 existing `NNNN_` files are frozen and must never be renamed: the ledger keys on basename, so a rename re-runs the migration. Full rationale in `backend/db/migrations/README.md`.
	- Term/offering/enrollment resolution goes through `services/academics.py`. The HTTP boundary keeps the abstract `course_id`; the graph stays on the abstract course, gradebook keys on `enrollment_id`, and study/analytics key on `offering_id`.

4. The new seed comment names the wrong constraint. seed_offerings() upserts with on_conflict="course_id,term_id,section", so course_offerings_unique is the conflict target — it routes into an UPDATE rather than failing. A renamed id would instead fail on enrollments.offering_id's FK (no ON UPDATE, so NO ACTION) when the UPDATE tries to change a referenced id. The conclusion — don't rename the ids — still holds, but for a different reason than stated.

Sapling/backend/db/seed_local_rich.py

Lines 126 to 131 in b2331aa

	(OFF_CS_S26, COURSE_CS, TERM_SPRING_2026, "Dr. Ada Lovelace", "MWF 11:00", "Hall A"),
	# Keeps its `su26` id: 0032 moved Summer offerings into Fall 2026, and the
	# ids are opaque keys, not claims about the term. Renaming them would leave
	# the old rows behind on an existing local database, where the old and new
	# offering would collide on course_offerings_unique (course_id, term_id, '').
	(OFF_ENG_SU26, COURSE_ENG, TERM_FALL_2026, "Prof. Maya Angelou", "MTWTh 10:00", "Hall C"),

Below the bar but worth folding in while these files are open: _PINNED_PAIRS in test_migrations.py wasn't extended for the three duplicate-prefix groups this PR creates; 0019_newsletter_approved_at.sql is pinned by no exact-name assertion, so a rename would keep len(legacy) == 48 and pass CI while silently reopening the orphan; and routes/onboarding.py:92 still describes resolve_offering as "creating a NULL-section offering".

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

Staging's migration ledger has three rows recorded under filenames that exist nowhere in this repo — and git log --all finds nothing for any of them, so they were applied out-of-band. migrate-staging.yml's preflight refuses to apply anything on top of that drift, correctly, which means all 11 pending migrations are stuck, including the fixes for #316 and #265.

on disk 45 | recorded 37 | pending 11
ORPHANS (recorded here, absent from the repo)
0019_newsletter_approved_at.sql <-- NUMBER COLLIDES WITH 0019_conventions_terms_schools.sql
0032_retire_summer_2026.sql <-- NUMBER COLLIDES WITH 0032_rooms_missing_columns.sql
0033_offering_section_not_null.sql <-- NUMBER COLLIDES WITH 0033_realtime_publish_room_messages.sql

Two of them were applied within hours of this being written (2026-08-01 01:55 and 03:51), so this is ongoing drift, not archaeology.

Why transcription, and why these exact filenames

schema_migrations.filename is the primary key, and the runner treats any basename it hasn't recorded as pending. That gives exactly one reconciliation move that doesn't involve hand-editing a live ledger: restore the files under their exact recorded names. Then staging sees them as recorded-and-present (neither pending nor orphan), while prod and every fresh local database see them as pending and apply them for real.

A timestamped name would not work — it would leave the orphan in place and re-run the DDL.

All three are written idempotently, because environments genuinely disagree about whether they ran: staging recorded them, prod got the newsletter column via 0026_ops.sql, and a fresh database gets them here first.

What each one actually does

0019_newsletter_approved_at.sql — a no-op everywhere except the ledger. 0026_ops.sql:30 already carries the column with a comment saying "Absorbed from 0019_newsletter_approved_at (drift fix; prod already has this column)". Restored purely to clear the orphan.

0032_retire_summer_2026.sql — this one changes data and behaviour. It deletes the Summer 2026 term and moves Fall 2026's start_date back to 2026-05-18 to close the 98-day hole that would otherwise open in 0019's deliberately contiguous date cover (current_term() resolves by date; a date in the hole resolves to no term, and resolve_offering(create=True) then can't place an enrollment). Consequence worth stating: a date like today resolved to summer-2026 before and resolves to fall-2026 after. Offerings are repointed before the term row is deleted, since course_offerings.term_id is the only FK into terms (verified against the live schema) and it's ON DELETE RESTRICT.

0033_offering_section_not_null.sql — section becomes NOT NULL DEFAULT ''. This is the one with a real design argument behind it, below.

The section design, and why staging's version wins

0020 made section nullable and course_offerings_unique is UNIQUE (course_id, term_id, section). Plain UNIQUE treats NULLs as distinct, so two NULL-section rows for the same course+term both survive — which is what 0036 patches, with a partial unique index over WHERE section IS NULL.

But NULL was never the only way to say "no section". Every seeder in this repo writes the empty string:

	writes section as
db/seed_staging.py:119	""
db/seed_local_rich.py:140	""
db/e2e_staging_http.py:69	""
services/academics.py::resolve_offering	omits the key → NULL

So a seeded offering and a resolve_offering'd one for the same course+term were two different values, and 0036 — scoped to WHERE section IS NULL — couldn't see the pair. The duplicate-offering bug 0036 exists to prevent walks in through the '' door.

Collapsing NULL into '' removes the second door: one representation of "no section", covered directly by the constraint that was already there. resolve_offering needs no code change — it still omits the key, the DEFAULT supplies '', and a lost race still surfaces as the 409 its existing handler re-selects on. Its docstring and the 409 comment did need updating, since both cited 0036 by number for a guarantee it no longer provides.

0036 is left untouched (it's already applied elsewhere; applied migrations are immutable) and becomes a permanent no-op — a partial index over a predicate no row can satisfy. 20260801062439_drop_dead_null_section_index.sql removes it, so it can't be mistaken for the thing holding the invariant up.

The guard bump

_LEGACY_NUMERIC_COUNT goes 45 → 48, with the reasoning in the file. These aren't newly claimed numbers — the numbers were already spoken for by rows in a live ledger. The count stays closed at 48; a genuinely new NNNN_ file still fails CI.

What this unblocks

Both of these are already fixed in main and blocked solely on the backlog:

• staging: avatars storage bucket is private but code expects public read #316 — 0041_avatars_bucket_public.sql is pending; staging still reports avatars public=false, so every avatar renders broken. That migration's own header says it: "writing this migration does not by itself fix staging — it converges on the next python -m db.migrate run."
• Rewire Gradescope sync onto enrollment-keyed gradebook (post-redesign) #265 — 0042_assignments_source_gradescope.sql is pending; staging's assignments_source_check is still CHECK (source IN ('manual','syllabus')), so every source='gradescope' insert the merged sync code writes would violate it.

Verification

• Backend suite: 1553 passed, 38 skipped. ruff check clean.
• New ordering pins in test_migrations.py: 0033-before-0036 (reversed, 0036 would index live NULL rows and 0033 would then silently empty it), 0036-before-the-drop, and 0019-before-0032 (reversed, the DELETE matches nothing and 0019 re-seeds the term).
• Full local e2e cycle — the real gate here, since it replays the whole chain against an empty database.

Note for whoever does prod

This PR deliberately stops short of prod. 0032 is a product decision about which terms exist, and it will apply there on the next run. Prod's ledger state also needs checking first — it may not have one at all, in which case db.migrate would treat all 48 as pending.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project ybgqdonkoqftwrmweuyv because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@AndresL230, you've reached your PR review limit, so we couldn't start this review.

Next review available in:21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aaf1009-2b6f-414d-babe-894e45e4ff74

📥 Commits

Reviewing files that changed from the base of the PR and between 39204d1 and 6422966.

📒 Files selected for processing (14)

• CLAUDE.md
• backend/db/migrations/0019_newsletter_approved_at.sql
• backend/db/migrations/0032_retire_summer_2026.sql
• backend/db/migrations/0033_offering_section_not_null.sql
• backend/db/migrations/20260801062439_drop_dead_null_section_index.sql
• backend/db/migrations/README.md
• backend/db/seed_local_rich.py
• backend/db/seed_staging.py
• backend/routes/onboarding.py
• backend/services/academics.py
• backend/tests/test_migration_naming.py
• backend/tests/test_migrations.py
• backend/tests/test_seed_staging.py
• frontend/e2e/semester-scope.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	6422966	Commit Preview URL Branch Preview URL	Aug 01 2026, 06:59 AM

[AndresL230]

Code review

Found 4 issues:

1. 0033's backfill can violate course_offerings_unique and abort the entire migration run. course_offerings_unique is UNIQUE (course_id, term_id, section) and Postgres treats NULL as distinct, so (c1, t1, NULL) and (c1, t1, '') coexist legally — which is exactly the mixed state this migration's own comment says exists, since the seeders write '' while resolve_offering wrote NULL. The blind UPDATE collapses that pair onto one key and raises a duplicate-key error. Two NULL rows for the same course+term collide the same way, and 0036's partial index cannot prevent it because 0036 applies after this file. db/migrate.py::apply_migration sends the whole file as one transaction with no per-file recovery, so the failure also stops every migration queued behind it. Neither verification lane can see this: the e2e replay starts from an empty table, and the hermetic suite mocks the DB.

Sapling/backend/db/migrations/0033_offering_section_not_null.sql

Lines 47 to 49 in b2331aa

	UPDATE course_offerings SET section =''WHERE section IS NULL;

2. 0032's repoint has the identical shape. If a course already has an offering in both summer-2026 and fall-2026 with the same section, moving the summer row onto fall-2026 collides on the same constraint. resolve_offering(create=True) never sets section, so every app-created offering shares the identical default — this is not an exotic data shape.

Sapling/backend/db/migrations/0032_retire_summer_2026.sql

Lines 35 to 39 in b2331aa

	-- 1. Move any Summer 2026 offering into Fall 2026 before the term disappears.
	UPDATE course_offerings
	SET term_id ='fall-2026'
	WHERE term_id ='summer-2026';

3. CLAUDE.md and backend/db/migrations/README.md both still say the legacy NNNN_ set is frozen at 45 files. This PR makes it 48 and bumps the guard, but the rationale for the exception lives only in a test-file comment and the PR description — not in either document CLAUDE.md tells readers to trust. (CLAUDE.md says "The 45 existing NNNN_ files are frozen and must never be renamed... Full rationale in backend/db/migrations/README.md".)

Sapling/CLAUDE.md

Lines 86 to 88 in b2331aa

	- All Supabase access goes through `db/connection.py::table()`. Do not instantiate `httpx` clients or import `supabase` directly elsewhere. The one sanctioned exception is `db/migrate.py`, which connects with psycopg to run DDL.
	- Schema changes are append-only migrations in `backend/db/migrations/` (applied via `python -m db.migrate`); never edit an applied migration or run DDL in the Supabase dashboard. **New migrations use a UTC timestamp prefix** — `date -u +%Y%m%d%H%M%S` — because sequential `NNNN_` numbers are claimed at write time and only validated at merge, so concurrent branches collide. The 45 existing `NNNN_` files are frozen and must never be renamed: the ledger keys on basename, so a rename re-runs the migration. Full rationale in `backend/db/migrations/README.md`.
	- Term/offering/enrollment resolution goes through `services/academics.py`. The HTTP boundary keeps the abstract `course_id`; the graph stays on the abstract course, gradebook keys on `enrollment_id`, and study/analytics key on `offering_id`.

4. The new seed comment names the wrong constraint. seed_offerings() upserts with on_conflict="course_id,term_id,section", so course_offerings_unique is the conflict target — it routes into an UPDATE rather than failing. A renamed id would instead fail on enrollments.offering_id's FK (no ON UPDATE, so NO ACTION) when the UPDATE tries to change a referenced id. The conclusion — don't rename the ids — still holds, but for a different reason than stated.

Sapling/backend/db/seed_local_rich.py

Lines 126 to 131 in b2331aa

	(OFF_CS_S26, COURSE_CS, TERM_SPRING_2026, "Dr. Ada Lovelace", "MWF 11:00", "Hall A"),
	# Keeps its `su26` id: 0032 moved Summer offerings into Fall 2026, and the
	# ids are opaque keys, not claims about the term. Renaming them would leave
	# the old rows behind on an existing local database, where the old and new
	# offering would collide on course_offerings_unique (course_id, term_id, '').
	(OFF_ENG_SU26, COURSE_ENG, TERM_FALL_2026, "Prof. Maya Angelou", "MTWTh 10:00", "Hall C"),

Below the bar but worth folding in while these files are open: _PINNED_PAIRS in test_migrations.py wasn't extended for the three duplicate-prefix groups this PR creates; 0019_newsletter_approved_at.sql is pinned by no exact-name assertion, so a rename would keep len(legacy) == 48 and pass CI while silently reopening the orphan; and routes/onboarding.py:92 still describes resolve_offering as "creating a NULL-section offering".

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

Staging's migration ledger has three rows recorded under filenames that exist nowhere in this repo — and git log --all finds nothing for any of them, so they were applied out-of-band. migrate-staging.yml's preflight refuses to apply anything on top of that drift, correctly, which means all 11 pending migrations are stuck, including the fixes for #316 and #265.

on disk 45 | recorded 37 | pending 11
ORPHANS (recorded here, absent from the repo)
0019_newsletter_approved_at.sql <-- NUMBER COLLIDES WITH 0019_conventions_terms_schools.sql
0032_retire_summer_2026.sql <-- NUMBER COLLIDES WITH 0032_rooms_missing_columns.sql
0033_offering_section_not_null.sql <-- NUMBER COLLIDES WITH 0033_realtime_publish_room_messages.sql

Two of them were applied within hours of this being written (2026-08-01 01:55 and 03:51), so this is ongoing drift, not archaeology.

Why transcription, and why these exact filenames

schema_migrations.filename is the primary key, and the runner treats any basename it hasn't recorded as pending. That gives exactly one reconciliation move that doesn't involve hand-editing a live ledger: restore the files under their exact recorded names. Then staging sees them as recorded-and-present (neither pending nor orphan), while prod and every fresh local database see them as pending and apply them for real.

A timestamped name would not work — it would leave the orphan in place and re-run the DDL.

All three are written idempotently, because environments genuinely disagree about whether they ran: staging recorded them, prod got the newsletter column via 0026_ops.sql, and a fresh database gets them here first.

What each one actually does

0019_newsletter_approved_at.sql — a no-op everywhere except the ledger. 0026_ops.sql:30 already carries the column with a comment saying "Absorbed from 0019_newsletter_approved_at (drift fix; prod already has this column)". Restored purely to clear the orphan.

0032_retire_summer_2026.sql — this one changes data and behaviour. It deletes the Summer 2026 term and moves Fall 2026's start_date back to 2026-05-18 to close the 98-day hole that would otherwise open in 0019's deliberately contiguous date cover (current_term() resolves by date; a date in the hole resolves to no term, and resolve_offering(create=True) then can't place an enrollment). Consequence worth stating: a date like today resolved to summer-2026 before and resolves to fall-2026 after. Offerings are repointed before the term row is deleted, since course_offerings.term_id is the only FK into terms (verified against the live schema) and it's ON DELETE RESTRICT.

0033_offering_section_not_null.sql — section becomes NOT NULL DEFAULT ''. This is the one with a real design argument behind it, below.

The section design, and why staging's version wins

0020 made section nullable and course_offerings_unique is UNIQUE (course_id, term_id, section). Plain UNIQUE treats NULLs as distinct, so two NULL-section rows for the same course+term both survive — which is what 0036 patches, with a partial unique index over WHERE section IS NULL.

But NULL was never the only way to say "no section". Every seeder in this repo writes the empty string:

	writes section as
db/seed_staging.py:119	""
db/seed_local_rich.py:140	""
db/e2e_staging_http.py:69	""
services/academics.py::resolve_offering	omits the key → NULL

So a seeded offering and a resolve_offering'd one for the same course+term were two different values, and 0036 — scoped to WHERE section IS NULL — couldn't see the pair. The duplicate-offering bug 0036 exists to prevent walks in through the '' door.

Collapsing NULL into '' removes the second door: one representation of "no section", covered directly by the constraint that was already there. resolve_offering needs no code change — it still omits the key, the DEFAULT supplies '', and a lost race still surfaces as the 409 its existing handler re-selects on. Its docstring and the 409 comment did need updating, since both cited 0036 by number for a guarantee it no longer provides.

0036 is left untouched (it's already applied elsewhere; applied migrations are immutable) and becomes a permanent no-op — a partial index over a predicate no row can satisfy. 20260801062439_drop_dead_null_section_index.sql removes it, so it can't be mistaken for the thing holding the invariant up.

The guard bump

_LEGACY_NUMERIC_COUNT goes 45 → 48, with the reasoning in the file. These aren't newly claimed numbers — the numbers were already spoken for by rows in a live ledger. The count stays closed at 48; a genuinely new NNNN_ file still fails CI.

What this unblocks

Both of these are already fixed in main and blocked solely on the backlog:

• staging: avatars storage bucket is private but code expects public read #316 — 0041_avatars_bucket_public.sql is pending; staging still reports avatars public=false, so every avatar renders broken. That migration's own header says it: "writing this migration does not by itself fix staging — it converges on the next python -m db.migrate run."
• Rewire Gradescope sync onto enrollment-keyed gradebook (post-redesign) #265 — 0042_assignments_source_gradescope.sql is pending; staging's assignments_source_check is still CHECK (source IN ('manual','syllabus')), so every source='gradescope' insert the merged sync code writes would violate it.

Verification

• Backend suite: 1553 passed, 38 skipped. ruff check clean.
• New ordering pins in test_migrations.py: 0033-before-0036 (reversed, 0036 would index live NULL rows and 0033 would then silently empty it), 0036-before-the-drop, and 0019-before-0032 (reversed, the DELETE matches nothing and 0019 re-seeds the term).
• Full local e2e cycle — the real gate here, since it replays the whole chain against an empty database.

Note for whoever does prod

This PR deliberately stops short of prod. 0032 is a product decision about which terms exist, and it will apply there on the next run. Prod's ledger state also needs checking first — it may not have one at all, in which case db.migrate would treat all 48 as pending.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project ybgqdonkoqftwrmweuyv because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@AndresL230, you've reached your PR review limit, so we couldn't start this review.

Next review available in:21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aaf1009-2b6f-414d-babe-894e45e4ff74

📥 Commits

Reviewing files that changed from the base of the PR and between 39204d1 and 6422966.

📒 Files selected for processing (14)

• CLAUDE.md
• backend/db/migrations/0019_newsletter_approved_at.sql
• backend/db/migrations/0032_retire_summer_2026.sql
• backend/db/migrations/0033_offering_section_not_null.sql
• backend/db/migrations/20260801062439_drop_dead_null_section_index.sql
• backend/db/migrations/README.md
• backend/db/seed_local_rich.py
• backend/db/seed_staging.py
• backend/routes/onboarding.py
• backend/services/academics.py
• backend/tests/test_migration_naming.py
• backend/tests/test_migrations.py
• backend/tests/test_seed_staging.py
• frontend/e2e/semester-scope.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	6422966	Commit Preview URL Branch Preview URL	Aug 01 2026, 06:59 AM

[AndresL230]

Code review

Found 4 issues:

1. 0033's backfill can violate course_offerings_unique and abort the entire migration run. course_offerings_unique is UNIQUE (course_id, term_id, section) and Postgres treats NULL as distinct, so (c1, t1, NULL) and (c1, t1, '') coexist legally — which is exactly the mixed state this migration's own comment says exists, since the seeders write '' while resolve_offering wrote NULL. The blind UPDATE collapses that pair onto one key and raises a duplicate-key error. Two NULL rows for the same course+term collide the same way, and 0036's partial index cannot prevent it because 0036 applies after this file. db/migrate.py::apply_migration sends the whole file as one transaction with no per-file recovery, so the failure also stops every migration queued behind it. Neither verification lane can see this: the e2e replay starts from an empty table, and the hermetic suite mocks the DB.

Sapling/backend/db/migrations/0033_offering_section_not_null.sql

Lines 47 to 49 in b2331aa

	UPDATE course_offerings SET section =''WHERE section IS NULL;

2. 0032's repoint has the identical shape. If a course already has an offering in both summer-2026 and fall-2026 with the same section, moving the summer row onto fall-2026 collides on the same constraint. resolve_offering(create=True) never sets section, so every app-created offering shares the identical default — this is not an exotic data shape.

Sapling/backend/db/migrations/0032_retire_summer_2026.sql

Lines 35 to 39 in b2331aa

	-- 1. Move any Summer 2026 offering into Fall 2026 before the term disappears.
	UPDATE course_offerings
	SET term_id ='fall-2026'
	WHERE term_id ='summer-2026';

3. CLAUDE.md and backend/db/migrations/README.md both still say the legacy NNNN_ set is frozen at 45 files. This PR makes it 48 and bumps the guard, but the rationale for the exception lives only in a test-file comment and the PR description — not in either document CLAUDE.md tells readers to trust. (CLAUDE.md says "The 45 existing NNNN_ files are frozen and must never be renamed... Full rationale in backend/db/migrations/README.md".)

Sapling/CLAUDE.md

Lines 86 to 88 in b2331aa

	- All Supabase access goes through `db/connection.py::table()`. Do not instantiate `httpx` clients or import `supabase` directly elsewhere. The one sanctioned exception is `db/migrate.py`, which connects with psycopg to run DDL.
	- Schema changes are append-only migrations in `backend/db/migrations/` (applied via `python -m db.migrate`); never edit an applied migration or run DDL in the Supabase dashboard. **New migrations use a UTC timestamp prefix** — `date -u +%Y%m%d%H%M%S` — because sequential `NNNN_` numbers are claimed at write time and only validated at merge, so concurrent branches collide. The 45 existing `NNNN_` files are frozen and must never be renamed: the ledger keys on basename, so a rename re-runs the migration. Full rationale in `backend/db/migrations/README.md`.
	- Term/offering/enrollment resolution goes through `services/academics.py`. The HTTP boundary keeps the abstract `course_id`; the graph stays on the abstract course, gradebook keys on `enrollment_id`, and study/analytics key on `offering_id`.

4. The new seed comment names the wrong constraint. seed_offerings() upserts with on_conflict="course_id,term_id,section", so course_offerings_unique is the conflict target — it routes into an UPDATE rather than failing. A renamed id would instead fail on enrollments.offering_id's FK (no ON UPDATE, so NO ACTION) when the UPDATE tries to change a referenced id. The conclusion — don't rename the ids — still holds, but for a different reason than stated.

Sapling/backend/db/seed_local_rich.py

Lines 126 to 131 in b2331aa

	(OFF_CS_S26, COURSE_CS, TERM_SPRING_2026, "Dr. Ada Lovelace", "MWF 11:00", "Hall A"),
	# Keeps its `su26` id: 0032 moved Summer offerings into Fall 2026, and the
	# ids are opaque keys, not claims about the term. Renaming them would leave
	# the old rows behind on an existing local database, where the old and new
	# offering would collide on course_offerings_unique (course_id, term_id, '').
	(OFF_ENG_SU26, COURSE_ENG, TERM_FALL_2026, "Prof. Maya Angelou", "MTWTh 10:00", "Hall C"),

Below the bar but worth folding in while these files are open: _PINNED_PAIRS in test_migrations.py wasn't extended for the three duplicate-prefix groups this PR creates; 0019_newsletter_approved_at.sql is pinned by no exact-name assertion, so a rename would keep len(legacy) == 48 and pass CI while silently reopening the orphan; and routes/onboarding.py:92 still describes resolve_offering as "creating a NULL-section offering".

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}