From f685ced67926879f690c9637738c863370fe82bd Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 03:14:45 -0400
Subject: [PATCH 01/51] db: dialect-aware Open plus a rebinding DB/Tx wrapper

Calnode's SQL is hand-written and portable apart from placeholder syntax, so
supporting a second engine is mostly a matter of not spreading "? vs $n" across
763 call sites. This adds the layer that hides it:

- Dialect (sqlite, postgres) selected from the DATABASE_URL scheme, with
  Dialect.SQL for the few statements that genuinely cannot be shared.
- Rebind: a small lexer, not a string replace. A ? inside a string literal, a
  quoted identifier or a comment is data, and renumbering one corrupts the
  statement in a way that only shows up at runtime.
- DB/Tx wrapping sql.DB/sql.Tx, rebinding every statement on the way through.
  Query, Exec, QueryRow, their Context forms, Prepare and Begin/BeginTx are all
  covered, so a call site moving onto the wrapper is a type change and nothing
  else. Begin returns *db.Tx rather than *sql.Tx deliberately: a transaction that
  quietly stopped rebinding is the easiest way to reintroduce ? on Postgres.
- OpenDB returns the wrapper; Open still returns the bare *sql.DB so nothing
  outside this package changes yet.

The SQLite path is untouched: same pragmas, and the one-connection pool stays
because it is the correctness guarantee behind the booking overlap check
(ARCHITECTURE section 17), not a tuning choice. Postgres gets an ordinary pool,
and openPostgres records what that costs so the gap is not rediscovered later.

Migrations move to migrations/sqlite/ unchanged (git detects all 57 as renames);
the postgres set lands in the next commit. is_applied is now tested for truth
rather than compared to 1, which is the one spelling both engines accept -- goose
stores it as INTEGER on SQLite and BOOLEAN on Postgres.

pgx v5.10.0 is the driver, via database/sql (stdlib), so nothing here depends on
the pgx-native API.
---
 go.mod                                        |   4 +
 go.sum                                        |  14 ++
 internal/db/db.go                             | 145 +++++++++++++----
 internal/db/db_test.go                        | 119 ++++++++++++++
 internal/db/dialect.go                        | 106 +++++++++++++
 internal/db/dialect_internal_test.go          |  99 ++++++++++++
 internal/db/handle.go                         | 130 ++++++++++++++++
 .../{ => sqlite}/00001_initial_schema.sql     |   0
 .../{ => sqlite}/00002_manage_tokens.sql      |   0
 .../{ => sqlite}/00003_job_lock_timeout.sql   |   0
 .../{ => sqlite}/00004_sessions.sql           |   0
 .../{ => sqlite}/00005_override_unique.sql    |   0
 .../00006_jobs_type_payload_unique.sql        |   0
 .../{ => sqlite}/00007_user_prefs.sql         |   0
 .../{ => sqlite}/00008_date_format.sql        |   0
 .../{ => sqlite}/00009_override_reason.sql    |   0
 .../{ => sqlite}/00010_messaging_prefs.sql    |   0
 .../{ => sqlite}/00011_server_settings.sql    |   0
 .../{ => sqlite}/00012_auth_providers.sql     |   0
 .../00013_google_oauth_settings.sql           |   0
 ...00014_booking_answers_question_cascade.sql |   0
 .../00015_calendar_connections_expiry.sql     |   0
 .../00016_event_types_max_active_bookings.sql |   0
 .../{ => sqlite}/00017_crypto_keystore.sql    |   0
 .../{ => sqlite}/00018_user_roles.sql         |   0
 .../{ => sqlite}/00019_user_archived.sql      |   0
 .../{ => sqlite}/00020_user_archived_by.sql   |   0
 .../{ => sqlite}/00021_event_type_hosts.sql   |   0
 .../{ => sqlite}/00022_booking_hosts.sql      |   0
 .../00023_booking_hosts_event_id.sql          |   0
 .../{ => sqlite}/00024_idempotency_keys.sql   |   0
 .../00025_booking_hosts_needs_sync.sql        |   0
 .../00026_event_type_subjects.sql             |   0
 .../{ => sqlite}/00027_webhook_fields.sql     |   0
 .../{ => sqlite}/00028_tracking_settings.sql  |   0
 .../{ => sqlite}/00029_branding_settings.sql  |   0
 .../{ => sqlite}/00030_logo_height.sql        |   0
 .../{ => sqlite}/00031_logo_opacity.sql       |   0
 .../00032_calendar_account_kind.sql           |   0
 .../{ => sqlite}/00033_oauth_mcp.sql          |   0
 .../{ => sqlite}/00034_llm_settings.sql       |   0
 .../{ => sqlite}/00035_llm_instructions.sql   |   0
 .../{ => sqlite}/00036_zoom_integration.sql   |   0
 .../{ => sqlite}/00037_stripe_payments.sql    |   0
 .../00038_booking_amount_paid.sql             |   0
 .../00039_calendar_account_email.sql          |   0
 .../{ => sqlite}/00040_magic_link_tokens.sql  |   0
 .../{ => sqlite}/00041_native_analytics.sql   |   0
 .../migrations/{ => sqlite}/00042_livekit.sql |   0
 .../{ => sqlite}/00043_livekit_recording.sql  |   0
 .../{ => sqlite}/00044_meeting_consents.sql   |   0
 .../{ => sqlite}/00045_notetaker.sql          |   0
 .../{ => sqlite}/00046_legal_links.sql        |   0
 .../00047_event_type_archived.sql             |   0
 .../{ => sqlite}/00048_override_group.sql     |   0
 .../00049_connection_calendars.sql            |   0
 .../{ => sqlite}/00050_branding_banner.sql    |   0
 .../00051_booking_attendee_locale.sql         |   0
 .../{ => sqlite}/00052_msg_greeting.sql       |   0
 .../{ => sqlite}/00053_fallback_locale.sql    |   0
 .../{ => sqlite}/00054_resend_api_key.sql     |   0
 .../00055_booking_hosts_calendar_id.sql       |   0
 .../00056_bookings_list_indexes.sql           |   0
 .../00057_event_type_show_taken_slots.sql     |   0
 internal/db/rebind.go                         | 113 ++++++++++++++
 internal/db/rebind_test.go                    | 147 ++++++++++++++++++
 66 files changed, 849 insertions(+), 28 deletions(-)
 create mode 100644 internal/db/dialect.go
 create mode 100644 internal/db/dialect_internal_test.go
 create mode 100644 internal/db/handle.go
 rename internal/db/migrations/{ => sqlite}/00001_initial_schema.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00002_manage_tokens.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00003_job_lock_timeout.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00004_sessions.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00005_override_unique.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00006_jobs_type_payload_unique.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00007_user_prefs.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00008_date_format.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00009_override_reason.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00010_messaging_prefs.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00011_server_settings.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00012_auth_providers.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00013_google_oauth_settings.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00014_booking_answers_question_cascade.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00015_calendar_connections_expiry.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00016_event_types_max_active_bookings.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00017_crypto_keystore.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00018_user_roles.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00019_user_archived.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00020_user_archived_by.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00021_event_type_hosts.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00022_booking_hosts.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00023_booking_hosts_event_id.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00024_idempotency_keys.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00025_booking_hosts_needs_sync.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00026_event_type_subjects.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00027_webhook_fields.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00028_tracking_settings.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00029_branding_settings.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00030_logo_height.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00031_logo_opacity.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00032_calendar_account_kind.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00033_oauth_mcp.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00034_llm_settings.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00035_llm_instructions.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00036_zoom_integration.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00037_stripe_payments.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00038_booking_amount_paid.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00039_calendar_account_email.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00040_magic_link_tokens.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00041_native_analytics.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00042_livekit.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00043_livekit_recording.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00044_meeting_consents.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00045_notetaker.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00046_legal_links.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00047_event_type_archived.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00048_override_group.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00049_connection_calendars.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00050_branding_banner.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00051_booking_attendee_locale.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00052_msg_greeting.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00053_fallback_locale.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00054_resend_api_key.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00055_booking_hosts_calendar_id.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00056_bookings_list_indexes.sql (100%)
 rename internal/db/migrations/{ => sqlite}/00057_event_type_show_taken_slots.sql (100%)
 create mode 100644 internal/db/rebind.go
 create mode 100644 internal/db/rebind_test.go

diff --git a/go.mod b/go.mod
index 8b8a9a9..73b76fd 100644
--- a/go.mod
+++ b/go.mod
@@ -6,6 +6,7 @@ toolchain go1.26.6
 
 require (
 	github.com/disintegration/imaging v1.6.2
+	github.com/jackc/pgx/v5 v5.10.0
 	github.com/joho/godotenv v1.5.1
 	github.com/modelcontextprotocol/go-sdk v1.6.1
 	github.com/pressly/goose/v3 v3.27.1
@@ -22,6 +23,9 @@ require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/google/jsonschema-go v0.4.3 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/mattn/go-isatty v0.0.21 // indirect
 	github.com/mfridman/interpolate v0.0.2 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
diff --git a/go.sum b/go.sum
index 5dc4a22..73978d1 100644
--- a/go.sum
+++ b/go.sum
@@ -1,5 +1,6 @@
 cloud.google.com/go/compute/metadata v0.3.0 h1:Tz+eQXMEqDIKRsmY3cHTL6FVaynIjX2QxYC4trgAKZc=
 cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/disintegration/imaging v1.6.2 h1:w1LecBlG2Lnp8B3jk5zSuNqd7b4DXhcjwek1ei82L+c=
@@ -18,6 +19,14 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
+github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/mattn/go-isatty v0.0.21 h1:xYae+lCNBP7QuW4PUnNG61ffM4hVIfm+zUzDuSzYLGs=
@@ -40,6 +49,9 @@ github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfv
 github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE=
 github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
@@ -66,6 +78,8 @@ golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
 golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
 golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
 golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 modernc.org/cc/v4 v4.28.1 h1:XpLbkYVQ24E8tX5u8+yWGvaxerxkR/S4zqxI8ZoSBuc=
diff --git a/internal/db/db.go b/internal/db/db.go
index 21c6240..97a9283 100644
--- a/internal/db/db.go
+++ b/internal/db/db.go
@@ -15,15 +15,41 @@ import (
 	_ "modernc.org/sqlite"
 )
 
-//go:embed migrations/*.sql
+//go:embed migrations/sqlite/*.sql
 var migrations embed.FS
 
-// Open connects to SQLite at the given URL and configures pragmas.
-// URL format: sqlite://./path/to/db or sqlite:///absolute/path or just a file path.
+// Open connects to the database at the given URL and returns the bare handle.
+//
+// Kept for callers that have not moved to OpenDB yet; it is the same connection,
+// without the dialect. Statements issued through it are not rebound, so on
+// Postgres they must already use $n.
 func Open(databaseURL string) (*sql.DB, error) {
+	h, err := OpenDB(databaseURL)
+	if err != nil {
+		return nil, err
+	}
+	return h.DB, nil
+}
+
+// OpenDB connects to the database named by databaseURL and configures the pool
+// for the engine it names.
+//
+// URL formats:
+//
+//	sqlite://./path/to/db, sqlite:///absolute/path, or a bare file path
+//	postgres://user:pass@host:port/dbname (postgresql:// is accepted too)
+func OpenDB(databaseURL string) (*DB, error) {
+	if dialectFromURL(databaseURL) == DialectPostgres {
+		return openPostgres(databaseURL)
+	}
+	return openSQLite(databaseURL)
+}
+
+// openSQLite opens SQLite and configures pragmas.
+func openSQLite(databaseURL string) (*DB, error) {
 	dsn := parseDSN(databaseURL)
 
-	db, err := sql.Open("sqlite", dsn)
+	db, err := sql.Open(DialectSQLite.driverName(), dsn)
 	if err != nil {
 		return nil, fmt.Errorf("open database: %w", err)
 	}
@@ -47,18 +73,66 @@ func Open(databaseURL string) (*sql.DB, error) {
 		return nil, fmt.Errorf("set busy timeout: %w", err)
 	}
 
-	return db, nil
+	return &DB{DB: db, dialect: DialectSQLite}, nil
+}
+
+// openPostgres opens a PostgreSQL pool.
+//
+// The one-connection pool above is a SQLite constraint, not a Calnode design
+// choice, and carrying it over would serialise the whole instance on a database
+// that has its own concurrency control. Sizes are deliberately modest: one
+// Calnode instance is one small process, and a self-hoster's Postgres is usually
+// sized to match.
+//
+// The pool does cost one property the SQLite path gets by accident: the
+// booking-overlap check (ARCHITECTURE §17) is free of TOCTOU races there only
+// because every transaction queues on that single connection. Here two
+// overlapping bookings can clear the check concurrently, and only
+// idx_bookings_no_double — exact start times — stops them. Closing that gap
+// belongs with the booking transaction (SERIALIZABLE, or a range exclusion
+// constraint), not with the pool.
+func openPostgres(databaseURL string) (*DB, error) {
+	// pgx parses the DSN here, so a malformed URL fails at Open. Reachability is
+	// not probed: Migrate runs immediately after Open in every entry point and
+	// reports an unreachable server with the same context a probe would.
+	db, err := sql.Open(DialectPostgres.driverName(), databaseURL)
+	if err != nil {
+		return nil, fmt.Errorf("open database: %w", err)
+	}
+
+	db.SetMaxOpenConns(10)
+	db.SetMaxIdleConns(5)
+
+	return &DB{DB: db, dialect: DialectPostgres}, nil
+}
+
+// Migrate runs any pending Goose migrations embedded for this handle's dialect.
+func (h *DB) Migrate() error {
+	return migrate(h.DB, h.dialect)
 }
 
-// Migrate runs any pending Goose migrations embedded in migrations/*.sql.
+// Migrate runs any pending Goose migrations embedded for db's engine, which is
+// recovered from its driver.
 func Migrate(db *sql.DB) error {
+	return migrate(db, dialectOf(db))
+}
+
+// gooseMu guards goose's package-level dialect and base FS. A running Calnode
+// only ever uses one engine, but the tests migrate both in one process and the
+// two settings must not interleave.
+var gooseMu sync.Mutex
+
+func migrate(db *sql.DB, dialect Dialect) error {
+	gooseMu.Lock()
+	defer gooseMu.Unlock()
+
 	goose.SetBaseFS(migrations)
 
-	if err := goose.SetDialect("sqlite3"); err != nil {
+	if err := goose.SetDialect(dialect.gooseDialect()); err != nil {
 		return fmt.Errorf("set goose dialect: %w", err)
 	}
 
-	if err := goose.Up(db, "migrations"); err != nil {
+	if err := goose.Up(db, dialect.migrationsDir()); err != nil {
 		return fmt.Errorf("run migrations: %w", err)
 	}
 
@@ -73,39 +147,54 @@ var (
 
 // TargetVersion returns the highest migration version embedded in the binary —
 // i.e. the schema version a fully-migrated database should report.
+//
+// It is dialect-independent: the per-dialect directories are two spellings of
+// one schema and carry the same version numbers, which TestMigrationDirs_parity
+// enforces.
 func TargetVersion() (int64, error) {
 	targetVersionOnce.Do(func() {
-		entries, err := fs.ReadDir(migrations, "migrations")
+		targetVersion, targetVersionErr = maxVersion(DialectSQLite.migrationsDir())
+	})
+	return targetVersion, targetVersionErr
+}
+
+// maxVersion returns the highest goose version number in an embedded migrations
+// directory.
+func maxVersion(dir string) (int64, error) {
+	entries, err := fs.ReadDir(migrations, dir)
+	if err != nil {
+		return 0, fmt.Errorf("read embedded migrations: %w", err)
+	}
+	var highest int64
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".sql") {
+			continue
+		}
+		// Filenames are "NNNNN_description.sql"; the leading number is the version.
+		name := path.Base(e.Name())
+		numPart, _, _ := strings.Cut(name, "_")
+		v, err := strconv.ParseInt(numPart, 10, 64)
 		if err != nil {
-			targetVersionErr = fmt.Errorf("read embedded migrations: %w", err)
-			return
+			continue // ignore files that don't follow the goose naming convention
 		}
-		for _, e := range entries {
-			if e.IsDir() || !strings.HasSuffix(e.Name(), ".sql") {
-				continue
-			}
-			// Filenames are "NNNNN_description.sql"; the leading number is the version.
-			name := path.Base(e.Name())
-			numPart, _, _ := strings.Cut(name, "_")
-			v, err := strconv.ParseInt(numPart, 10, 64)
-			if err != nil {
-				continue // ignore files that don't follow the goose naming convention
-			}
-			if v > targetVersion {
-				targetVersion = v
-			}
+		if v > highest {
+			highest = v
 		}
-	})
-	return targetVersion, targetVersionErr
+	}
+	return highest, nil
 }
 
 // AppliedVersion returns the schema version currently applied to db by reading
 // goose's bookkeeping table directly (no goose global state). A missing
 // goose_db_version table returns an error, which callers treat as "not migrated".
+//
+// is_applied is tested for truth rather than compared to 1: goose stores it as an
+// INTEGER on SQLite and a BOOLEAN on Postgres, and the bare column is the one
+// spelling both engines accept.
 func AppliedVersion(ctx context.Context, db *sql.DB) (int64, error) {
 	var v sql.NullInt64
 	err := db.QueryRowContext(ctx,
-		`SELECT MAX(version_id) FROM goose_db_version WHERE is_applied = 1`).Scan(&v)
+		`SELECT MAX(version_id) FROM goose_db_version WHERE is_applied`).Scan(&v)
 	if err != nil {
 		return 0, err
 	}
diff --git a/internal/db/db_test.go b/internal/db/db_test.go
index e07bf0b..4bc6045 100644
--- a/internal/db/db_test.go
+++ b/internal/db/db_test.go
@@ -2,6 +2,7 @@ package db_test
 
 import (
 	"context"
+	"path/filepath"
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
@@ -140,3 +141,121 @@ func TestDoubleBookingIndex_exists(t *testing.T) {
 		t.Errorf("double-booking guard index not found: %v", err)
 	}
 }
+
+// TestOpenDB_sqlitePragmasAndPool pins the SQLite path against accidental
+// change: the single connection is a correctness guarantee (ARCHITECTURE §17),
+// not a tuning choice, and the pragmas are connection-scoped so losing the
+// connection loses them. A file database is used because :memory: cannot be in
+// WAL mode.
+func TestOpenDB_sqlitePragmasAndPool(t *testing.T) {
+	handle, err := db.OpenDB("sqlite://" + filepath.Join(t.TempDir(), "calnode.db"))
+	if err != nil {
+		t.Fatalf("db.OpenDB: %v", err)
+	}
+	defer handle.Close()
+
+	if got := handle.Dialect(); got != db.DialectSQLite {
+		t.Errorf("dialect = %v; want %v", got, db.DialectSQLite)
+	}
+	if got := handle.Stats().MaxOpenConnections; got != 1 {
+		t.Errorf("MaxOpenConnections = %d; want 1", got)
+	}
+
+	pragmas := []struct{ name, want string }{
+		{"journal_mode", "wal"},
+		{"foreign_keys", "1"},
+		{"busy_timeout", "5000"},
+	}
+	for _, p := range pragmas {
+		var got string
+		if err := handle.QueryRow(`PRAGMA ` + p.name).Scan(&got); err != nil {
+			t.Fatalf("PRAGMA %s: %v", p.name, err)
+		}
+		if got != p.want {
+			t.Errorf("PRAGMA %s = %q; want %q", p.name, got, p.want)
+		}
+	}
+}
+
+// TestOpenDB_wrapperRoundTrip exercises the method set the rest of the codebase
+// uses, on the dialect where rebinding is a no-op, so a mistake in the wrapper
+// itself cannot hide behind a missing Postgres server.
+func TestOpenDB_wrapperRoundTrip(t *testing.T) {
+	handle, err := db.OpenDB("sqlite://:memory:")
+	if err != nil {
+		t.Fatalf("db.OpenDB: %v", err)
+	}
+	defer handle.Close()
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	ctx := context.Background()
+
+	if _, err := handle.ExecContext(ctx,
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		"u1", "a@example.com", "A"); err != nil {
+		t.Fatalf("ExecContext insert: %v", err)
+	}
+
+	var name string
+	if err := handle.QueryRowContext(ctx,
+		`SELECT name FROM users WHERE id = ?`, "u1").Scan(&name); err != nil {
+		t.Fatalf("QueryRowContext: %v", err)
+	}
+	if name != "A" {
+		t.Errorf("name = %q; want %q", name, "A")
+	}
+
+	rows, err := handle.QueryContext(ctx, `SELECT id FROM users WHERE email = ?`, "a@example.com")
+	if err != nil {
+		t.Fatalf("QueryContext: %v", err)
+	}
+	count := 0
+	for rows.Next() {
+		count++
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("rows.Err: %v", err)
+	}
+	rows.Close()
+	if count != 1 {
+		t.Errorf("rows returned = %d; want 1", count)
+	}
+
+	tx, err := handle.BeginTx(ctx, nil)
+	if err != nil {
+		t.Fatalf("BeginTx: %v", err)
+	}
+	if tx.Dialect() != handle.Dialect() {
+		t.Errorf("tx dialect = %v; want %v", tx.Dialect(), handle.Dialect())
+	}
+	if _, err := tx.ExecContext(ctx, `UPDATE users SET name = ? WHERE id = ?`, "B", "u1"); err != nil {
+		tx.Rollback()
+		t.Fatalf("tx.ExecContext: %v", err)
+	}
+	if err := tx.QueryRowContext(ctx, `SELECT name FROM users WHERE id = ?`, "u1").Scan(&name); err != nil {
+		tx.Rollback()
+		t.Fatalf("tx.QueryRowContext: %v", err)
+	}
+	if err := tx.Commit(); err != nil {
+		t.Fatalf("tx.Commit: %v", err)
+	}
+	if name != "B" {
+		t.Errorf("name after tx update = %q; want %q", name, "B")
+	}
+
+	stmt, err := handle.PrepareContext(ctx, `SELECT COUNT(*) FROM users WHERE email = ?`)
+	if err != nil {
+		t.Fatalf("PrepareContext: %v", err)
+	}
+	defer stmt.Close()
+	var n int
+	if err := stmt.QueryRowContext(ctx, "a@example.com").Scan(&n); err != nil {
+		t.Fatalf("stmt.QueryRowContext: %v", err)
+	}
+	if n != 1 {
+		t.Errorf("count = %d; want 1", n)
+	}
+}
diff --git a/internal/db/dialect.go b/internal/db/dialect.go
new file mode 100644
index 0000000..e3881c2
--- /dev/null
+++ b/internal/db/dialect.go
@@ -0,0 +1,106 @@
+package db
+
+import (
+	"database/sql"
+	"strings"
+
+	"github.com/jackc/pgx/v5/stdlib"
+)
+
+// Dialect names the SQL engine behind a handle.
+//
+// Calnode's SQL is hand-written and almost entirely portable. Two things are
+// not: placeholder syntax (? versus $n), which the DB/Tx wrapper hides by
+// rebinding every statement on its way through, and the handful of statements
+// that use engine-specific functions, which callers resolve with Dialect.SQL.
+type Dialect int
+
+const (
+	// DialectSQLite is the zero value deliberately: a handle whose dialect
+	// could not be determined behaves exactly as it did before this package
+	// knew about Postgres.
+	DialectSQLite Dialect = iota
+	DialectPostgres
+)
+
+// String returns the dialect's canonical lower-case name.
+func (d Dialect) String() string {
+	switch d {
+	case DialectPostgres:
+		return "postgres"
+	default:
+		return "sqlite"
+	}
+}
+
+// SQL picks between two hand-written statements.
+//
+// Reach for this only when one portable statement is genuinely impossible —
+// engine-specific functions (datetime('now'), strftime), upsert spelling, a
+// PRAGMA. Differing placeholders are not a reason: the wrapper rebinds those,
+// and duplicating a statement to change ? to $1 doubles the maintenance for no
+// gain.
+func (d Dialect) SQL(sqlite, postgres string) string {
+	if d == DialectPostgres {
+		return postgres
+	}
+	return sqlite
+}
+
+// Rebind converts a portable ?-placeholder statement into this dialect's form.
+// SQLite takes ? natively, so its statements are returned untouched with no
+// allocation.
+func (d Dialect) Rebind(query string) string {
+	if d != DialectPostgres {
+		return query
+	}
+	return Rebind(query)
+}
+
+// driverName is the database/sql driver this dialect opens with.
+func (d Dialect) driverName() string {
+	if d == DialectPostgres {
+		return "pgx"
+	}
+	return "sqlite"
+}
+
+// gooseDialect is goose's name for this engine.
+func (d Dialect) gooseDialect() string {
+	if d == DialectPostgres {
+		return "postgres"
+	}
+	return "sqlite3"
+}
+
+// migrationsDir is the embedded directory holding this dialect's migrations.
+// The two sets carry the same version numbers by construction — one schema, two
+// spellings — which is what lets TargetVersion stay dialect-independent.
+func (d Dialect) migrationsDir() string {
+	if d == DialectPostgres {
+		return "migrations/postgres"
+	}
+	return "migrations/sqlite"
+}
+
+// dialectFromURL classifies a DATABASE_URL. Only an explicit postgres URL
+// selects Postgres, so every form that worked before still works unchanged:
+// sqlite://./rel, sqlite:///abs, :memory:, and a bare file path.
+func dialectFromURL(databaseURL string) Dialect {
+	scheme := strings.ToLower(databaseURL)
+	if strings.HasPrefix(scheme, "postgres://") || strings.HasPrefix(scheme, "postgresql://") {
+		return DialectPostgres
+	}
+	return DialectSQLite
+}
+
+// dialectOf recovers the dialect from an already-open handle, for the
+// package-level helpers that still take a bare *sql.DB. An unrecognised driver
+// reads as SQLite: that is what every caller of those helpers was before, so an
+// unknown driver degrades to the old behaviour rather than to an error.
+func dialectOf(db *sql.DB) Dialect {
+	if _, ok := db.Driver().(*stdlib.Driver); ok {
+		return DialectPostgres
+	}
+	return DialectSQLite
+}
diff --git a/internal/db/dialect_internal_test.go b/internal/db/dialect_internal_test.go
new file mode 100644
index 0000000..19d7588
--- /dev/null
+++ b/internal/db/dialect_internal_test.go
@@ -0,0 +1,99 @@
+package db
+
+import (
+	"database/sql"
+	"testing"
+)
+
+func TestDialectFromURL(t *testing.T) {
+	tests := []struct {
+		url  string
+		want Dialect
+	}{
+		{"sqlite://./data/calnode.db", DialectSQLite},
+		{"sqlite:///var/lib/calnode/calnode.db", DialectSQLite},
+		{"sqlite://:memory:", DialectSQLite},
+		{"sqlite://file::memory:?cache=shared&_fk=1", DialectSQLite},
+		{"./data/calnode.db", DialectSQLite},
+		{"/var/lib/calnode/calnode.db", DialectSQLite},
+		{":memory:", DialectSQLite},
+		{"", DialectSQLite},
+		{"postgres://calnode@localhost:5432/calnode", DialectPostgres},
+		{"postgresql://calnode@localhost:5432/calnode", DialectPostgres},
+		{"postgres://u:p@h:5432/d?sslmode=require", DialectPostgres},
+		{"POSTGRES://u:p@h:5432/d", DialectPostgres},
+		// A path that merely mentions postgres is still a SQLite file.
+		{"./postgres-backup/calnode.db", DialectSQLite},
+	}
+
+	for _, tt := range tests {
+		if got := dialectFromURL(tt.url); got != tt.want {
+			t.Errorf("dialectFromURL(%q) = %v; want %v", tt.url, got, tt.want)
+		}
+	}
+}
+
+func TestParseDSN(t *testing.T) {
+	tests := []struct{ url, want string }{
+		{"sqlite://./data/calnode.db", "./data/calnode.db"},
+		{"sqlite:///var/lib/calnode/calnode.db", "/var/lib/calnode/calnode.db"},
+		{"sqlite://:memory:", ":memory:"},
+		{"sqlite://file::memory:?cache=shared&_fk=1", "file::memory:?cache=shared&_fk=1"},
+		{"./data/calnode.db", "./data/calnode.db"},
+		// Windows: sqlite:///C:/path/db → C:/path/db.
+		{"sqlite:///C:/calnode/calnode.db", "C:/calnode/calnode.db"},
+	}
+
+	for _, tt := range tests {
+		if got := parseDSN(tt.url); got != tt.want {
+			t.Errorf("parseDSN(%q) = %q; want %q", tt.url, got, tt.want)
+		}
+	}
+}
+
+// TestDialectOf covers the driver sniffing the package-level Migrate and the
+// version helpers rely on. It needs no server: database/sql is lazy, so both
+// handles exist without a connection.
+func TestDialectOf(t *testing.T) {
+	sqlite, err := sql.Open(DialectSQLite.driverName(), ":memory:")
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	defer sqlite.Close()
+
+	postgres, err := sql.Open(DialectPostgres.driverName(), "postgres://u:p@127.0.0.1:5432/d")
+	if err != nil {
+		t.Fatalf("open postgres: %v", err)
+	}
+	defer postgres.Close()
+
+	if got := dialectOf(sqlite); got != DialectSQLite {
+		t.Errorf("dialectOf(sqlite handle) = %v; want %v", got, DialectSQLite)
+	}
+	if got := dialectOf(postgres); got != DialectPostgres {
+		t.Errorf("dialectOf(postgres handle) = %v; want %v", got, DialectPostgres)
+	}
+}
+
+func TestDialectNames(t *testing.T) {
+	tests := []struct {
+		dialect        Dialect
+		driver, goose  string
+		migrationsPath string
+	}{
+		{DialectSQLite, "sqlite", "sqlite3", "migrations/sqlite"},
+		{DialectPostgres, "pgx", "postgres", "migrations/postgres"},
+	}
+
+	for _, tt := range tests {
+		if got := tt.dialect.driverName(); got != tt.driver {
+			t.Errorf("%v.driverName() = %q; want %q", tt.dialect, got, tt.driver)
+		}
+		if got := tt.dialect.gooseDialect(); got != tt.goose {
+			t.Errorf("%v.gooseDialect() = %q; want %q", tt.dialect, got, tt.goose)
+		}
+		if got := tt.dialect.migrationsDir(); got != tt.migrationsPath {
+			t.Errorf("%v.migrationsDir() = %q; want %q", tt.dialect, got, tt.migrationsPath)
+		}
+	}
+}
diff --git a/internal/db/handle.go b/internal/db/handle.go
new file mode 100644
index 0000000..c8cac0c
--- /dev/null
+++ b/internal/db/handle.go
@@ -0,0 +1,130 @@
+package db
+
+import (
+	"context"
+	"database/sql"
+)
+
+// DB is a *sql.DB that knows its dialect and rebinds placeholders.
+//
+// Every query method takes the portable ? form and rewrites it for the engine in
+// use, so the rest of Calnode writes one statement per query no matter which
+// database it runs on. Behaviour on SQLite is identical to using *sql.DB
+// directly: Rebind is a no-op there.
+//
+// The embedded *sql.DB is exported on purpose — pool tuning, Ping, Close and
+// anything that must hand a plain *sql.DB to a library (goose here, Litestream
+// in DEPLOY.md) reach it as h.DB. Statements issued through that field, or
+// through a *sql.Conn from the promoted Conn method, are NOT rebound; use the
+// wrapper's own methods unless you are deliberately writing engine-specific SQL.
+type DB struct {
+	*sql.DB
+	dialect Dialect
+}
+
+// Dialect reports which engine this handle is talking to, for the few callers
+// that must branch on it.
+func (h *DB) Dialect() Dialect { return h.dialect }
+
+// Rebind converts a ?-placeholder statement for this handle's dialect. Useful
+// when a caller builds SQL dynamically and hands it to something other than the
+// methods below.
+func (h *DB) Rebind(query string) string { return h.dialect.Rebind(query) }
+
+func (h *DB) Query(query string, args ...any) (*sql.Rows, error) {
+	return h.DB.Query(h.dialect.Rebind(query), args...)
+}
+
+func (h *DB) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {
+	return h.DB.QueryContext(ctx, h.dialect.Rebind(query), args...)
+}
+
+func (h *DB) QueryRow(query string, args ...any) *sql.Row {
+	return h.DB.QueryRow(h.dialect.Rebind(query), args...)
+}
+
+func (h *DB) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row {
+	return h.DB.QueryRowContext(ctx, h.dialect.Rebind(query), args...)
+}
+
+func (h *DB) Exec(query string, args ...any) (sql.Result, error) {
+	return h.DB.Exec(h.dialect.Rebind(query), args...)
+}
+
+func (h *DB) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
+	return h.DB.ExecContext(ctx, h.dialect.Rebind(query), args...)
+}
+
+// Prepare and PrepareContext rebind at prepare time, so the returned *sql.Stmt
+// needs no wrapper of its own.
+func (h *DB) Prepare(query string) (*sql.Stmt, error) {
+	return h.DB.Prepare(h.dialect.Rebind(query))
+}
+
+func (h *DB) PrepareContext(ctx context.Context, query string) (*sql.Stmt, error) {
+	return h.DB.PrepareContext(ctx, h.dialect.Rebind(query))
+}
+
+// Begin and BeginTx return a *Tx rather than a *sql.Tx: a transaction that
+// silently stopped rebinding would be the easiest way to reintroduce ? into a
+// Postgres statement.
+func (h *DB) Begin() (*Tx, error) {
+	tx, err := h.DB.Begin()
+	if err != nil {
+		return nil, err
+	}
+	return &Tx{Tx: tx, dialect: h.dialect}, nil
+}
+
+func (h *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*Tx, error) {
+	tx, err := h.DB.BeginTx(ctx, opts)
+	if err != nil {
+		return nil, err
+	}
+	return &Tx{Tx: tx, dialect: h.dialect}, nil
+}
+
+// Tx is a *sql.Tx with the same rebinding behaviour as DB. Commit and Rollback
+// are the embedded ones — they carry no SQL text.
+type Tx struct {
+	*sql.Tx
+	dialect Dialect
+}
+
+// Dialect reports which engine this transaction is running against.
+func (t *Tx) Dialect() Dialect { return t.dialect }
+
+// Rebind converts a ?-placeholder statement for this transaction's dialect.
+func (t *Tx) Rebind(query string) string { return t.dialect.Rebind(query) }
+
+func (t *Tx) Query(query string, args ...any) (*sql.Rows, error) {
+	return t.Tx.Query(t.dialect.Rebind(query), args...)
+}
+
+func (t *Tx) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {
+	return t.Tx.QueryContext(ctx, t.dialect.Rebind(query), args...)
+}
+
+func (t *Tx) QueryRow(query string, args ...any) *sql.Row {
+	return t.Tx.QueryRow(t.dialect.Rebind(query), args...)
+}
+
+func (t *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row {
+	return t.Tx.QueryRowContext(ctx, t.dialect.Rebind(query), args...)
+}
+
+func (t *Tx) Exec(query string, args ...any) (sql.Result, error) {
+	return t.Tx.Exec(t.dialect.Rebind(query), args...)
+}
+
+func (t *Tx) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
+	return t.Tx.ExecContext(ctx, t.dialect.Rebind(query), args...)
+}
+
+func (t *Tx) Prepare(query string) (*sql.Stmt, error) {
+	return t.Tx.Prepare(t.dialect.Rebind(query))
+}
+
+func (t *Tx) PrepareContext(ctx context.Context, query string) (*sql.Stmt, error) {
+	return t.Tx.PrepareContext(ctx, t.dialect.Rebind(query))
+}
diff --git a/internal/db/migrations/00001_initial_schema.sql b/internal/db/migrations/sqlite/00001_initial_schema.sql
similarity index 100%
rename from internal/db/migrations/00001_initial_schema.sql
rename to internal/db/migrations/sqlite/00001_initial_schema.sql
diff --git a/internal/db/migrations/00002_manage_tokens.sql b/internal/db/migrations/sqlite/00002_manage_tokens.sql
similarity index 100%
rename from internal/db/migrations/00002_manage_tokens.sql
rename to internal/db/migrations/sqlite/00002_manage_tokens.sql
diff --git a/internal/db/migrations/00003_job_lock_timeout.sql b/internal/db/migrations/sqlite/00003_job_lock_timeout.sql
similarity index 100%
rename from internal/db/migrations/00003_job_lock_timeout.sql
rename to internal/db/migrations/sqlite/00003_job_lock_timeout.sql
diff --git a/internal/db/migrations/00004_sessions.sql b/internal/db/migrations/sqlite/00004_sessions.sql
similarity index 100%
rename from internal/db/migrations/00004_sessions.sql
rename to internal/db/migrations/sqlite/00004_sessions.sql
diff --git a/internal/db/migrations/00005_override_unique.sql b/internal/db/migrations/sqlite/00005_override_unique.sql
similarity index 100%
rename from internal/db/migrations/00005_override_unique.sql
rename to internal/db/migrations/sqlite/00005_override_unique.sql
diff --git a/internal/db/migrations/00006_jobs_type_payload_unique.sql b/internal/db/migrations/sqlite/00006_jobs_type_payload_unique.sql
similarity index 100%
rename from internal/db/migrations/00006_jobs_type_payload_unique.sql
rename to internal/db/migrations/sqlite/00006_jobs_type_payload_unique.sql
diff --git a/internal/db/migrations/00007_user_prefs.sql b/internal/db/migrations/sqlite/00007_user_prefs.sql
similarity index 100%
rename from internal/db/migrations/00007_user_prefs.sql
rename to internal/db/migrations/sqlite/00007_user_prefs.sql
diff --git a/internal/db/migrations/00008_date_format.sql b/internal/db/migrations/sqlite/00008_date_format.sql
similarity index 100%
rename from internal/db/migrations/00008_date_format.sql
rename to internal/db/migrations/sqlite/00008_date_format.sql
diff --git a/internal/db/migrations/00009_override_reason.sql b/internal/db/migrations/sqlite/00009_override_reason.sql
similarity index 100%
rename from internal/db/migrations/00009_override_reason.sql
rename to internal/db/migrations/sqlite/00009_override_reason.sql
diff --git a/internal/db/migrations/00010_messaging_prefs.sql b/internal/db/migrations/sqlite/00010_messaging_prefs.sql
similarity index 100%
rename from internal/db/migrations/00010_messaging_prefs.sql
rename to internal/db/migrations/sqlite/00010_messaging_prefs.sql
diff --git a/internal/db/migrations/00011_server_settings.sql b/internal/db/migrations/sqlite/00011_server_settings.sql
similarity index 100%
rename from internal/db/migrations/00011_server_settings.sql
rename to internal/db/migrations/sqlite/00011_server_settings.sql
diff --git a/internal/db/migrations/00012_auth_providers.sql b/internal/db/migrations/sqlite/00012_auth_providers.sql
similarity index 100%
rename from internal/db/migrations/00012_auth_providers.sql
rename to internal/db/migrations/sqlite/00012_auth_providers.sql
diff --git a/internal/db/migrations/00013_google_oauth_settings.sql b/internal/db/migrations/sqlite/00013_google_oauth_settings.sql
similarity index 100%
rename from internal/db/migrations/00013_google_oauth_settings.sql
rename to internal/db/migrations/sqlite/00013_google_oauth_settings.sql
diff --git a/internal/db/migrations/00014_booking_answers_question_cascade.sql b/internal/db/migrations/sqlite/00014_booking_answers_question_cascade.sql
similarity index 100%
rename from internal/db/migrations/00014_booking_answers_question_cascade.sql
rename to internal/db/migrations/sqlite/00014_booking_answers_question_cascade.sql
diff --git a/internal/db/migrations/00015_calendar_connections_expiry.sql b/internal/db/migrations/sqlite/00015_calendar_connections_expiry.sql
similarity index 100%
rename from internal/db/migrations/00015_calendar_connections_expiry.sql
rename to internal/db/migrations/sqlite/00015_calendar_connections_expiry.sql
diff --git a/internal/db/migrations/00016_event_types_max_active_bookings.sql b/internal/db/migrations/sqlite/00016_event_types_max_active_bookings.sql
similarity index 100%
rename from internal/db/migrations/00016_event_types_max_active_bookings.sql
rename to internal/db/migrations/sqlite/00016_event_types_max_active_bookings.sql
diff --git a/internal/db/migrations/00017_crypto_keystore.sql b/internal/db/migrations/sqlite/00017_crypto_keystore.sql
similarity index 100%
rename from internal/db/migrations/00017_crypto_keystore.sql
rename to internal/db/migrations/sqlite/00017_crypto_keystore.sql
diff --git a/internal/db/migrations/00018_user_roles.sql b/internal/db/migrations/sqlite/00018_user_roles.sql
similarity index 100%
rename from internal/db/migrations/00018_user_roles.sql
rename to internal/db/migrations/sqlite/00018_user_roles.sql
diff --git a/internal/db/migrations/00019_user_archived.sql b/internal/db/migrations/sqlite/00019_user_archived.sql
similarity index 100%
rename from internal/db/migrations/00019_user_archived.sql
rename to internal/db/migrations/sqlite/00019_user_archived.sql
diff --git a/internal/db/migrations/00020_user_archived_by.sql b/internal/db/migrations/sqlite/00020_user_archived_by.sql
similarity index 100%
rename from internal/db/migrations/00020_user_archived_by.sql
rename to internal/db/migrations/sqlite/00020_user_archived_by.sql
diff --git a/internal/db/migrations/00021_event_type_hosts.sql b/internal/db/migrations/sqlite/00021_event_type_hosts.sql
similarity index 100%
rename from internal/db/migrations/00021_event_type_hosts.sql
rename to internal/db/migrations/sqlite/00021_event_type_hosts.sql
diff --git a/internal/db/migrations/00022_booking_hosts.sql b/internal/db/migrations/sqlite/00022_booking_hosts.sql
similarity index 100%
rename from internal/db/migrations/00022_booking_hosts.sql
rename to internal/db/migrations/sqlite/00022_booking_hosts.sql
diff --git a/internal/db/migrations/00023_booking_hosts_event_id.sql b/internal/db/migrations/sqlite/00023_booking_hosts_event_id.sql
similarity index 100%
rename from internal/db/migrations/00023_booking_hosts_event_id.sql
rename to internal/db/migrations/sqlite/00023_booking_hosts_event_id.sql
diff --git a/internal/db/migrations/00024_idempotency_keys.sql b/internal/db/migrations/sqlite/00024_idempotency_keys.sql
similarity index 100%
rename from internal/db/migrations/00024_idempotency_keys.sql
rename to internal/db/migrations/sqlite/00024_idempotency_keys.sql
diff --git a/internal/db/migrations/00025_booking_hosts_needs_sync.sql b/internal/db/migrations/sqlite/00025_booking_hosts_needs_sync.sql
similarity index 100%
rename from internal/db/migrations/00025_booking_hosts_needs_sync.sql
rename to internal/db/migrations/sqlite/00025_booking_hosts_needs_sync.sql
diff --git a/internal/db/migrations/00026_event_type_subjects.sql b/internal/db/migrations/sqlite/00026_event_type_subjects.sql
similarity index 100%
rename from internal/db/migrations/00026_event_type_subjects.sql
rename to internal/db/migrations/sqlite/00026_event_type_subjects.sql
diff --git a/internal/db/migrations/00027_webhook_fields.sql b/internal/db/migrations/sqlite/00027_webhook_fields.sql
similarity index 100%
rename from internal/db/migrations/00027_webhook_fields.sql
rename to internal/db/migrations/sqlite/00027_webhook_fields.sql
diff --git a/internal/db/migrations/00028_tracking_settings.sql b/internal/db/migrations/sqlite/00028_tracking_settings.sql
similarity index 100%
rename from internal/db/migrations/00028_tracking_settings.sql
rename to internal/db/migrations/sqlite/00028_tracking_settings.sql
diff --git a/internal/db/migrations/00029_branding_settings.sql b/internal/db/migrations/sqlite/00029_branding_settings.sql
similarity index 100%
rename from internal/db/migrations/00029_branding_settings.sql
rename to internal/db/migrations/sqlite/00029_branding_settings.sql
diff --git a/internal/db/migrations/00030_logo_height.sql b/internal/db/migrations/sqlite/00030_logo_height.sql
similarity index 100%
rename from internal/db/migrations/00030_logo_height.sql
rename to internal/db/migrations/sqlite/00030_logo_height.sql
diff --git a/internal/db/migrations/00031_logo_opacity.sql b/internal/db/migrations/sqlite/00031_logo_opacity.sql
similarity index 100%
rename from internal/db/migrations/00031_logo_opacity.sql
rename to internal/db/migrations/sqlite/00031_logo_opacity.sql
diff --git a/internal/db/migrations/00032_calendar_account_kind.sql b/internal/db/migrations/sqlite/00032_calendar_account_kind.sql
similarity index 100%
rename from internal/db/migrations/00032_calendar_account_kind.sql
rename to internal/db/migrations/sqlite/00032_calendar_account_kind.sql
diff --git a/internal/db/migrations/00033_oauth_mcp.sql b/internal/db/migrations/sqlite/00033_oauth_mcp.sql
similarity index 100%
rename from internal/db/migrations/00033_oauth_mcp.sql
rename to internal/db/migrations/sqlite/00033_oauth_mcp.sql
diff --git a/internal/db/migrations/00034_llm_settings.sql b/internal/db/migrations/sqlite/00034_llm_settings.sql
similarity index 100%
rename from internal/db/migrations/00034_llm_settings.sql
rename to internal/db/migrations/sqlite/00034_llm_settings.sql
diff --git a/internal/db/migrations/00035_llm_instructions.sql b/internal/db/migrations/sqlite/00035_llm_instructions.sql
similarity index 100%
rename from internal/db/migrations/00035_llm_instructions.sql
rename to internal/db/migrations/sqlite/00035_llm_instructions.sql
diff --git a/internal/db/migrations/00036_zoom_integration.sql b/internal/db/migrations/sqlite/00036_zoom_integration.sql
similarity index 100%
rename from internal/db/migrations/00036_zoom_integration.sql
rename to internal/db/migrations/sqlite/00036_zoom_integration.sql
diff --git a/internal/db/migrations/00037_stripe_payments.sql b/internal/db/migrations/sqlite/00037_stripe_payments.sql
similarity index 100%
rename from internal/db/migrations/00037_stripe_payments.sql
rename to internal/db/migrations/sqlite/00037_stripe_payments.sql
diff --git a/internal/db/migrations/00038_booking_amount_paid.sql b/internal/db/migrations/sqlite/00038_booking_amount_paid.sql
similarity index 100%
rename from internal/db/migrations/00038_booking_amount_paid.sql
rename to internal/db/migrations/sqlite/00038_booking_amount_paid.sql
diff --git a/internal/db/migrations/00039_calendar_account_email.sql b/internal/db/migrations/sqlite/00039_calendar_account_email.sql
similarity index 100%
rename from internal/db/migrations/00039_calendar_account_email.sql
rename to internal/db/migrations/sqlite/00039_calendar_account_email.sql
diff --git a/internal/db/migrations/00040_magic_link_tokens.sql b/internal/db/migrations/sqlite/00040_magic_link_tokens.sql
similarity index 100%
rename from internal/db/migrations/00040_magic_link_tokens.sql
rename to internal/db/migrations/sqlite/00040_magic_link_tokens.sql
diff --git a/internal/db/migrations/00041_native_analytics.sql b/internal/db/migrations/sqlite/00041_native_analytics.sql
similarity index 100%
rename from internal/db/migrations/00041_native_analytics.sql
rename to internal/db/migrations/sqlite/00041_native_analytics.sql
diff --git a/internal/db/migrations/00042_livekit.sql b/internal/db/migrations/sqlite/00042_livekit.sql
similarity index 100%
rename from internal/db/migrations/00042_livekit.sql
rename to internal/db/migrations/sqlite/00042_livekit.sql
diff --git a/internal/db/migrations/00043_livekit_recording.sql b/internal/db/migrations/sqlite/00043_livekit_recording.sql
similarity index 100%
rename from internal/db/migrations/00043_livekit_recording.sql
rename to internal/db/migrations/sqlite/00043_livekit_recording.sql
diff --git a/internal/db/migrations/00044_meeting_consents.sql b/internal/db/migrations/sqlite/00044_meeting_consents.sql
similarity index 100%
rename from internal/db/migrations/00044_meeting_consents.sql
rename to internal/db/migrations/sqlite/00044_meeting_consents.sql
diff --git a/internal/db/migrations/00045_notetaker.sql b/internal/db/migrations/sqlite/00045_notetaker.sql
similarity index 100%
rename from internal/db/migrations/00045_notetaker.sql
rename to internal/db/migrations/sqlite/00045_notetaker.sql
diff --git a/internal/db/migrations/00046_legal_links.sql b/internal/db/migrations/sqlite/00046_legal_links.sql
similarity index 100%
rename from internal/db/migrations/00046_legal_links.sql
rename to internal/db/migrations/sqlite/00046_legal_links.sql
diff --git a/internal/db/migrations/00047_event_type_archived.sql b/internal/db/migrations/sqlite/00047_event_type_archived.sql
similarity index 100%
rename from internal/db/migrations/00047_event_type_archived.sql
rename to internal/db/migrations/sqlite/00047_event_type_archived.sql
diff --git a/internal/db/migrations/00048_override_group.sql b/internal/db/migrations/sqlite/00048_override_group.sql
similarity index 100%
rename from internal/db/migrations/00048_override_group.sql
rename to internal/db/migrations/sqlite/00048_override_group.sql
diff --git a/internal/db/migrations/00049_connection_calendars.sql b/internal/db/migrations/sqlite/00049_connection_calendars.sql
similarity index 100%
rename from internal/db/migrations/00049_connection_calendars.sql
rename to internal/db/migrations/sqlite/00049_connection_calendars.sql
diff --git a/internal/db/migrations/00050_branding_banner.sql b/internal/db/migrations/sqlite/00050_branding_banner.sql
similarity index 100%
rename from internal/db/migrations/00050_branding_banner.sql
rename to internal/db/migrations/sqlite/00050_branding_banner.sql
diff --git a/internal/db/migrations/00051_booking_attendee_locale.sql b/internal/db/migrations/sqlite/00051_booking_attendee_locale.sql
similarity index 100%
rename from internal/db/migrations/00051_booking_attendee_locale.sql
rename to internal/db/migrations/sqlite/00051_booking_attendee_locale.sql
diff --git a/internal/db/migrations/00052_msg_greeting.sql b/internal/db/migrations/sqlite/00052_msg_greeting.sql
similarity index 100%
rename from internal/db/migrations/00052_msg_greeting.sql
rename to internal/db/migrations/sqlite/00052_msg_greeting.sql
diff --git a/internal/db/migrations/00053_fallback_locale.sql b/internal/db/migrations/sqlite/00053_fallback_locale.sql
similarity index 100%
rename from internal/db/migrations/00053_fallback_locale.sql
rename to internal/db/migrations/sqlite/00053_fallback_locale.sql
diff --git a/internal/db/migrations/00054_resend_api_key.sql b/internal/db/migrations/sqlite/00054_resend_api_key.sql
similarity index 100%
rename from internal/db/migrations/00054_resend_api_key.sql
rename to internal/db/migrations/sqlite/00054_resend_api_key.sql
diff --git a/internal/db/migrations/00055_booking_hosts_calendar_id.sql b/internal/db/migrations/sqlite/00055_booking_hosts_calendar_id.sql
similarity index 100%
rename from internal/db/migrations/00055_booking_hosts_calendar_id.sql
rename to internal/db/migrations/sqlite/00055_booking_hosts_calendar_id.sql
diff --git a/internal/db/migrations/00056_bookings_list_indexes.sql b/internal/db/migrations/sqlite/00056_bookings_list_indexes.sql
similarity index 100%
rename from internal/db/migrations/00056_bookings_list_indexes.sql
rename to internal/db/migrations/sqlite/00056_bookings_list_indexes.sql
diff --git a/internal/db/migrations/00057_event_type_show_taken_slots.sql b/internal/db/migrations/sqlite/00057_event_type_show_taken_slots.sql
similarity index 100%
rename from internal/db/migrations/00057_event_type_show_taken_slots.sql
rename to internal/db/migrations/sqlite/00057_event_type_show_taken_slots.sql
diff --git a/internal/db/rebind.go b/internal/db/rebind.go
new file mode 100644
index 0000000..f0d5639
--- /dev/null
+++ b/internal/db/rebind.go
@@ -0,0 +1,113 @@
+package db
+
+import (
+	"strconv"
+	"strings"
+)
+
+// Rebind rewrites the ? placeholders in query to PostgreSQL's $1…$n form,
+// numbering them left to right so the caller's argument order is unchanged.
+//
+// It is a small lexer rather than a string replace because a ? inside a string
+// literal, a quoted identifier or a comment is data, not a placeholder.
+// Renumbering one of those corrupts the statement, and the corruption surfaces
+// at runtime — as a wrong result or a confusing type error — a long way from the
+// code that caused it.
+//
+// Not recognised, because Calnode's SQL contains none of them and guessing would
+// be worse than saying so: PostgreSQL escape strings (E'...', where a backslash
+// escapes the closing quote), dollar-quoted bodies ($tag$…$tag$), and
+// MSSQL-style [bracketed] identifiers. Statements using those must be written per
+// dialect with Dialect.SQL and their own $n.
+func Rebind(query string) string {
+	// Overwhelmingly the common case for DDL and for already-converted SQL.
+	if !strings.Contains(query, "?") {
+		return query
+	}
+
+	var b strings.Builder
+	b.Grow(len(query) + 8)
+
+	n := 0
+	for i := 0; i < len(query); {
+		switch c := query[i]; {
+		case c == '\'' || c == '"' || c == '`':
+			// A quoted run is copied verbatim: single quotes are string
+			// literals, and both double quotes and backticks are identifier
+			// quotes SQLite accepts.
+			end := endOfQuoted(query, i)
+			b.WriteString(query[i:end])
+			i = end
+		case c == '-' && i+1 < len(query) && query[i+1] == '-':
+			end := endOfLineComment(query, i)
+			b.WriteString(query[i:end])
+			i = end
+		case c == '/' && i+1 < len(query) && query[i+1] == '*':
+			end := endOfBlockComment(query, i)
+			b.WriteString(query[i:end])
+			i = end
+		case c == '?':
+			n++
+			b.WriteByte('$')
+			b.WriteString(strconv.Itoa(n))
+			i++
+		default:
+			b.WriteByte(c)
+			i++
+		}
+	}
+
+	return b.String()
+}
+
+// endOfQuoted returns the index just past the quoted run starting at i, where
+// query[i] is the opening quote. A doubled quote is an escaped quote and does not
+// close the run — that is SQL's only escape under both engines' default settings.
+// An unterminated run extends to the end of the string, which hands the malformed
+// statement to the engine to reject instead of mangling the remainder.
+func endOfQuoted(query string, i int) int {
+	quote := query[i]
+	for j := i + 1; j < len(query); j++ {
+		if query[j] != quote {
+			continue
+		}
+		if j+1 < len(query) && query[j+1] == quote {
+			j++ // skip the escaped quote; the loop's j++ skips its partner
+			continue
+		}
+		return j + 1
+	}
+	return len(query)
+}
+
+// endOfLineComment returns the index of the newline ending the -- comment at i,
+// so the newline itself is copied by the caller and line structure survives.
+func endOfLineComment(query string, i int) int {
+	if k := strings.IndexByte(query[i:], '\n'); k >= 0 {
+		return i + k
+	}
+	return len(query)
+}
+
+// endOfBlockComment returns the index just past the /* */ comment at i. Nesting
+// is honoured: PostgreSQL nests block comments, so treating the first */ as the
+// end would drop back into "SQL" while still inside a comment.
+func endOfBlockComment(query string, i int) int {
+	depth := 0
+	for j := i; j+1 < len(query); {
+		switch {
+		case query[j] == '/' && query[j+1] == '*':
+			depth++
+			j += 2
+		case query[j] == '*' && query[j+1] == '/':
+			depth--
+			j += 2
+			if depth == 0 {
+				return j
+			}
+		default:
+			j++
+		}
+	}
+	return len(query)
+}
diff --git a/internal/db/rebind_test.go b/internal/db/rebind_test.go
new file mode 100644
index 0000000..e469f61
--- /dev/null
+++ b/internal/db/rebind_test.go
@@ -0,0 +1,147 @@
+package db_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+func TestRebind(t *testing.T) {
+	tests := []struct {
+		name  string
+		query string
+		want  string
+	}{{
+		name:  "no placeholders",
+		query: `SELECT id FROM users`,
+		want:  `SELECT id FROM users`,
+	}, {
+		name:  "one placeholder",
+		query: `SELECT id FROM users WHERE email = ?`,
+		want:  `SELECT id FROM users WHERE email = $1`,
+	}, {
+		name:  "numbered left to right",
+		query: `UPDATE users SET name = ?, email = ? WHERE id = ?`,
+		want:  `UPDATE users SET name = $1, email = $2 WHERE id = $3`,
+	}, {
+		name:  "string literal holding a question mark",
+		query: `SELECT id FROM event_types WHERE name = 'why?' AND slug = ?`,
+		want:  `SELECT id FROM event_types WHERE name = 'why?' AND slug = $1`,
+	}, {
+		name:  "escaped quote inside a literal does not end it",
+		query: `SELECT ? WHERE reason = 'it''s a ?' AND id = ?`,
+		want:  `SELECT $1 WHERE reason = 'it''s a ?' AND id = $2`,
+	}, {
+		name:  "double-quoted identifier",
+		query: `SELECT "odd?column" FROM t WHERE id = ?`,
+		want:  `SELECT "odd?column" FROM t WHERE id = $1`,
+	}, {
+		name:  "escaped double quote inside an identifier",
+		query: `SELECT "a""?b" FROM t WHERE id = ?`,
+		want:  `SELECT "a""?b" FROM t WHERE id = $1`,
+	}, {
+		name:  "backtick identifier",
+		query: "SELECT `weird?` FROM t WHERE id = ?",
+		want:  "SELECT `weird?` FROM t WHERE id = $1",
+	}, {
+		name:  "line comment",
+		query: "SELECT id -- what about ?\nFROM t WHERE id = ?",
+		want:  "SELECT id -- what about ?\nFROM t WHERE id = $1",
+	}, {
+		name:  "line comment at end of input",
+		query: `SELECT id FROM t WHERE id = ? -- trailing ?`,
+		want:  `SELECT id FROM t WHERE id = $1 -- trailing ?`,
+	}, {
+		name:  "block comment",
+		query: `SELECT /* ? not a param ? */ id FROM t WHERE id = ?`,
+		want:  `SELECT /* ? not a param ? */ id FROM t WHERE id = $1`,
+	}, {
+		name:  "nested block comment",
+		query: `SELECT /* outer /* inner ? */ still ? */ id FROM t WHERE id = ?`,
+		want:  `SELECT /* outer /* inner ? */ still ? */ id FROM t WHERE id = $1`,
+	}, {
+		name:  "division is not a comment",
+		query: `SELECT price_cents / 100 FROM event_types WHERE id = ?`,
+		want:  `SELECT price_cents / 100 FROM event_types WHERE id = $1`,
+	}, {
+		name:  "negative number is not a comment",
+		query: `SELECT id FROM t WHERE n = -1 AND id = ?`,
+		want:  `SELECT id FROM t WHERE n = -1 AND id = $1`,
+	}, {
+		name:  "unterminated literal swallows the rest",
+		query: `SELECT id FROM t WHERE s = 'oops ? and id = ?`,
+		want:  `SELECT id FROM t WHERE s = 'oops ? and id = ?`,
+	}, {
+		name:  "unterminated block comment swallows the rest",
+		query: `SELECT id FROM t /* oops ? and id = ?`,
+		want:  `SELECT id FROM t /* oops ? and id = ?`,
+	}, {
+		name:  "already rebound is left alone",
+		query: `SELECT id FROM t WHERE id = $1`,
+		want:  `SELECT id FROM t WHERE id = $1`,
+	}, {
+		name:  "multi-line statement with a comment block",
+		query: "-- +goose Up\nINSERT INTO t (a, b) VALUES (?, ?)\n  -- ? in a comment\n  ON CONFLICT DO NOTHING",
+		want:  "-- +goose Up\nINSERT INTO t (a, b) VALUES ($1, $2)\n  -- ? in a comment\n  ON CONFLICT DO NOTHING",
+	}}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := db.Rebind(tt.query); got != tt.want {
+				t.Errorf("Rebind(%q)\n got %q\nwant %q", tt.query, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestRebind_manyPlaceholders covers the two-digit boundary: a naive
+// implementation that scanned for "$1" or replaced in a fixed order would go
+// wrong at ten.
+func TestRebind_manyPlaceholders(t *testing.T) {
+	const n = 12
+	query := "INSERT INTO t VALUES (" + strings.Repeat("?, ", n-1) + "?)"
+
+	got := db.Rebind(query)
+
+	want := "INSERT INTO t VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)"
+	if got != want {
+		t.Errorf("Rebind(%q)\n got %q\nwant %q", query, got, want)
+	}
+}
+
+func TestDialectRebind(t *testing.T) {
+	const query = `SELECT id FROM users WHERE email = ? AND is_admin = ?`
+
+	if got := db.DialectSQLite.Rebind(query); got != query {
+		t.Errorf("DialectSQLite.Rebind rewrote the query: %q", got)
+	}
+
+	want := `SELECT id FROM users WHERE email = $1 AND is_admin = $2`
+	if got := db.DialectPostgres.Rebind(query); got != want {
+		t.Errorf("DialectPostgres.Rebind = %q; want %q", got, want)
+	}
+}
+
+func TestDialectSQL(t *testing.T) {
+	const (
+		sqlite   = `UPDATE server_settings SET updated_at = datetime('now') WHERE id = 1`
+		postgres = `UPDATE server_settings SET updated_at = to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS') WHERE id = 1`
+	)
+
+	if got := db.DialectSQLite.SQL(sqlite, postgres); got != sqlite {
+		t.Errorf("DialectSQLite.SQL = %q; want the sqlite statement", got)
+	}
+	if got := db.DialectPostgres.SQL(sqlite, postgres); got != postgres {
+		t.Errorf("DialectPostgres.SQL = %q; want the postgres statement", got)
+	}
+}
+
+func TestDialectString(t *testing.T) {
+	if got := db.DialectSQLite.String(); got != "sqlite" {
+		t.Errorf("DialectSQLite.String() = %q; want %q", got, "sqlite")
+	}
+	if got := db.DialectPostgres.String(); got != "postgres" {
+		t.Errorf("DialectPostgres.String() = %q; want %q", got, "postgres")
+	}
+}

From dead65eabe39b109760c7b0533e6dafbe96161ab Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 03:24:07 -0400
Subject: [PATCH 02/51] db: PostgreSQL migration set, generated once from the
 SQLite one

57 files in migrations/postgres, one per SQLite migration and numbered
identically, embedded alongside them. Open picks the directory and the goose
dialect from the DSN, so nothing else has to know which set is in use.

What the translation does, and what it deliberately does not:

- Flag columns stay integers (INTEGER -> SMALLINT), never BOOLEAN. Those columns
  are scanned into Go ints across the codebase, so changing the type would break
  every one of those scans. Columns that hold real numbers stay INTEGER. A test
  reads information_schema and fails on a boolean.
- Timestamp defaults keep TEXT and keep SQLite's exact string format:
  strftime('%Y-%m-%dT%H:%M:%fZ','now') becomes
  to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') and
  datetime('now') becomes the seconds-precision equivalent. TIMESTAMPTZ was the
  alternative and is wrong here: every time value in this schema is written,
  compared, sorted and paginated as a string, and database/sql would hand those
  columns back formatted as RFC3339Nano, which sorts differently and would not
  match a stored value. A test asserts both formats against the shapes SQLite
  writes.
- Partial unique indexes carry over verbatim; a test proves idx_bookings_no_double
  still refuses a second booking at the same start time and still allows re-booking
  a cancelled slot.
- crypto_keystore.id relied on SQLite's rowid (keyvault.go inserts without an id),
  so it becomes BIGINT GENERATED BY DEFAULT AS IDENTITY. server_settings.id does
  not: it is seeded explicitly and pinned by CHECK(id = 1), where a sequence would
  only mislead. BLOB becomes BYTEA.
- The three table rebuilds become what Postgres can do directly: 00012 drops the
  four columns, 00014 and 00042 replace a constraint in place. 00042 therefore
  needs neither NO TRANSACTION nor the foreign_keys PRAGMA toggle, both of which
  existed only to make SQLite's rebuild safe.
- lower(hex(randomblob(16))) becomes replace(gen_random_uuid()::text, '-', ''),
  the same 32 lowercase hex characters with no extension to install.
  INSERT OR IGNORE becomes ON CONFLICT DO NOTHING.
- Downs that are no-ops on SQLite stay no-ops here even where Postgres could drop
  the column. A down that lands on a different schema per engine is worse than one
  that lands on none, and it would make the following up fail on one engine only.

Tests are opt-in on CALNODE_TEST_POSTGRES_DSN and skip cleanly when it is unset,
so upstream CI and any contributor running SQLite is unaffected. Each test runs in
a schema of its own, created and dropped around it, so runs neither collide nor
leave anything behind in an operator's database.
---
 internal/db/db.go                             |   2 +-
 .../postgres/00001_initial_schema.sql         | 210 ++++++++
 .../postgres/00002_manage_tokens.sql          |  14 +
 .../postgres/00003_job_lock_timeout.sql       |  14 +
 .../db/migrations/postgres/00004_sessions.sql |  17 +
 .../postgres/00005_override_unique.sql        |   6 +
 .../00006_jobs_type_payload_unique.sql        |   9 +
 .../migrations/postgres/00007_user_prefs.sql  |  12 +
 .../migrations/postgres/00008_date_format.sql |  10 +
 .../postgres/00009_override_reason.sql        |  10 +
 .../postgres/00010_messaging_prefs.sql        |  29 ++
 .../postgres/00011_server_settings.sql        |  20 +
 .../postgres/00012_auth_providers.sql         |  33 ++
 .../postgres/00013_google_oauth_settings.sql  |   8 +
 ...00014_booking_answers_question_cascade.sql |  20 +
 .../00015_calendar_connections_expiry.sql     |   7 +
 .../00016_event_types_max_active_bookings.sql |  10 +
 .../postgres/00017_crypto_keystore.sql        |  18 +
 .../migrations/postgres/00018_user_roles.sql  |  15 +
 .../postgres/00019_user_archived.sql          |  11 +
 .../postgres/00020_user_archived_by.sql       |   9 +
 .../postgres/00021_event_type_hosts.sql       |  36 ++
 .../postgres/00022_booking_hosts.sql          |  24 +
 .../postgres/00023_booking_hosts_event_id.sql |  17 +
 .../postgres/00024_idempotency_keys.sql       |  18 +
 .../00025_booking_hosts_needs_sync.sql        |  10 +
 .../postgres/00026_event_type_subjects.sql    |  14 +
 .../postgres/00027_webhook_fields.sql         |   9 +
 .../postgres/00028_tracking_settings.sql      |  18 +
 .../postgres/00029_branding_settings.sql      |  12 +
 .../migrations/postgres/00030_logo_height.sql |   7 +
 .../postgres/00031_logo_opacity.sql           |   7 +
 .../postgres/00032_calendar_account_kind.sql  |  10 +
 .../migrations/postgres/00033_oauth_mcp.sql   |  49 ++
 .../postgres/00034_llm_settings.sql           |  14 +
 .../postgres/00035_llm_instructions.sql       |   8 +
 .../postgres/00036_zoom_integration.sql       |  25 +
 .../postgres/00037_stripe_payments.sql        |  26 +
 .../postgres/00038_booking_amount_paid.sql    |  11 +
 .../postgres/00039_calendar_account_email.sql |  11 +
 .../postgres/00040_magic_link_tokens.sql      |  13 +
 .../postgres/00041_native_analytics.sql       |  11 +
 .../db/migrations/postgres/00042_livekit.sql  |  26 +
 .../postgres/00043_livekit_recording.sql      |  23 +
 .../postgres/00044_meeting_consents.sql       |  15 +
 .../migrations/postgres/00045_notetaker.sql   |  34 ++
 .../migrations/postgres/00046_legal_links.sql |  11 +
 .../postgres/00047_event_type_archived.sql    |  10 +
 .../postgres/00048_override_group.sql         |   9 +
 .../postgres/00049_connection_calendars.sql   |  38 ++
 .../postgres/00050_branding_banner.sql        |  11 +
 .../00051_booking_attendee_locale.sql         |  12 +
 .../postgres/00052_msg_greeting.sql           |  13 +
 .../postgres/00053_fallback_locale.sql        |  10 +
 .../postgres/00054_resend_api_key.sql         |  19 +
 .../00055_booking_hosts_calendar_id.sql       |  21 +
 .../postgres/00056_bookings_list_indexes.sql  |  34 ++
 .../00057_event_type_show_taken_slots.sql     |  18 +
 internal/db/migrations_internal_test.go       |  58 +++
 internal/db/postgres_test.go                  | 491 ++++++++++++++++++
 60 files changed, 1686 insertions(+), 1 deletion(-)
 create mode 100644 internal/db/migrations/postgres/00001_initial_schema.sql
 create mode 100644 internal/db/migrations/postgres/00002_manage_tokens.sql
 create mode 100644 internal/db/migrations/postgres/00003_job_lock_timeout.sql
 create mode 100644 internal/db/migrations/postgres/00004_sessions.sql
 create mode 100644 internal/db/migrations/postgres/00005_override_unique.sql
 create mode 100644 internal/db/migrations/postgres/00006_jobs_type_payload_unique.sql
 create mode 100644 internal/db/migrations/postgres/00007_user_prefs.sql
 create mode 100644 internal/db/migrations/postgres/00008_date_format.sql
 create mode 100644 internal/db/migrations/postgres/00009_override_reason.sql
 create mode 100644 internal/db/migrations/postgres/00010_messaging_prefs.sql
 create mode 100644 internal/db/migrations/postgres/00011_server_settings.sql
 create mode 100644 internal/db/migrations/postgres/00012_auth_providers.sql
 create mode 100644 internal/db/migrations/postgres/00013_google_oauth_settings.sql
 create mode 100644 internal/db/migrations/postgres/00014_booking_answers_question_cascade.sql
 create mode 100644 internal/db/migrations/postgres/00015_calendar_connections_expiry.sql
 create mode 100644 internal/db/migrations/postgres/00016_event_types_max_active_bookings.sql
 create mode 100644 internal/db/migrations/postgres/00017_crypto_keystore.sql
 create mode 100644 internal/db/migrations/postgres/00018_user_roles.sql
 create mode 100644 internal/db/migrations/postgres/00019_user_archived.sql
 create mode 100644 internal/db/migrations/postgres/00020_user_archived_by.sql
 create mode 100644 internal/db/migrations/postgres/00021_event_type_hosts.sql
 create mode 100644 internal/db/migrations/postgres/00022_booking_hosts.sql
 create mode 100644 internal/db/migrations/postgres/00023_booking_hosts_event_id.sql
 create mode 100644 internal/db/migrations/postgres/00024_idempotency_keys.sql
 create mode 100644 internal/db/migrations/postgres/00025_booking_hosts_needs_sync.sql
 create mode 100644 internal/db/migrations/postgres/00026_event_type_subjects.sql
 create mode 100644 internal/db/migrations/postgres/00027_webhook_fields.sql
 create mode 100644 internal/db/migrations/postgres/00028_tracking_settings.sql
 create mode 100644 internal/db/migrations/postgres/00029_branding_settings.sql
 create mode 100644 internal/db/migrations/postgres/00030_logo_height.sql
 create mode 100644 internal/db/migrations/postgres/00031_logo_opacity.sql
 create mode 100644 internal/db/migrations/postgres/00032_calendar_account_kind.sql
 create mode 100644 internal/db/migrations/postgres/00033_oauth_mcp.sql
 create mode 100644 internal/db/migrations/postgres/00034_llm_settings.sql
 create mode 100644 internal/db/migrations/postgres/00035_llm_instructions.sql
 create mode 100644 internal/db/migrations/postgres/00036_zoom_integration.sql
 create mode 100644 internal/db/migrations/postgres/00037_stripe_payments.sql
 create mode 100644 internal/db/migrations/postgres/00038_booking_amount_paid.sql
 create mode 100644 internal/db/migrations/postgres/00039_calendar_account_email.sql
 create mode 100644 internal/db/migrations/postgres/00040_magic_link_tokens.sql
 create mode 100644 internal/db/migrations/postgres/00041_native_analytics.sql
 create mode 100644 internal/db/migrations/postgres/00042_livekit.sql
 create mode 100644 internal/db/migrations/postgres/00043_livekit_recording.sql
 create mode 100644 internal/db/migrations/postgres/00044_meeting_consents.sql
 create mode 100644 internal/db/migrations/postgres/00045_notetaker.sql
 create mode 100644 internal/db/migrations/postgres/00046_legal_links.sql
 create mode 100644 internal/db/migrations/postgres/00047_event_type_archived.sql
 create mode 100644 internal/db/migrations/postgres/00048_override_group.sql
 create mode 100644 internal/db/migrations/postgres/00049_connection_calendars.sql
 create mode 100644 internal/db/migrations/postgres/00050_branding_banner.sql
 create mode 100644 internal/db/migrations/postgres/00051_booking_attendee_locale.sql
 create mode 100644 internal/db/migrations/postgres/00052_msg_greeting.sql
 create mode 100644 internal/db/migrations/postgres/00053_fallback_locale.sql
 create mode 100644 internal/db/migrations/postgres/00054_resend_api_key.sql
 create mode 100644 internal/db/migrations/postgres/00055_booking_hosts_calendar_id.sql
 create mode 100644 internal/db/migrations/postgres/00056_bookings_list_indexes.sql
 create mode 100644 internal/db/migrations/postgres/00057_event_type_show_taken_slots.sql
 create mode 100644 internal/db/migrations_internal_test.go
 create mode 100644 internal/db/postgres_test.go

diff --git a/internal/db/db.go b/internal/db/db.go
index 97a9283..8bacdd2 100644
--- a/internal/db/db.go
+++ b/internal/db/db.go
@@ -15,7 +15,7 @@ import (
 	_ "modernc.org/sqlite"
 )
 
-//go:embed migrations/sqlite/*.sql
+//go:embed migrations/sqlite/*.sql migrations/postgres/*.sql
 var migrations embed.FS
 
 // Open connects to the database at the given URL and returns the bare handle.
diff --git a/internal/db/migrations/postgres/00001_initial_schema.sql b/internal/db/migrations/postgres/00001_initial_schema.sql
new file mode 100644
index 0000000..1b453e0
--- /dev/null
+++ b/internal/db/migrations/postgres/00001_initial_schema.sql
@@ -0,0 +1,210 @@
+-- +goose Up
+
+CREATE TABLE IF NOT EXISTS users (
+    id            TEXT PRIMARY KEY,
+    email         TEXT NOT NULL UNIQUE,
+    name          TEXT NOT NULL,
+    iana_timezone TEXT NOT NULL DEFAULT 'UTC',
+    avatar_url    TEXT,
+    is_admin      SMALLINT NOT NULL DEFAULT 0,  -- first user bootstraps as admin
+    created_at    TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE TABLE IF NOT EXISTS api_keys (
+    id           TEXT PRIMARY KEY,
+    user_id      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name         TEXT NOT NULL,
+    key_hash     TEXT NOT NULL UNIQUE,  -- stored hashed; shown once on creation
+    last_used_at TEXT,
+    created_at   TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE TABLE IF NOT EXISTS teams (
+    id         TEXT PRIMARY KEY,
+    name       TEXT NOT NULL,
+    slug       TEXT NOT NULL UNIQUE,
+    created_at TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE TABLE IF NOT EXISTS team_members (
+    id               TEXT PRIMARY KEY,
+    team_id          TEXT NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+    user_id          TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role             TEXT NOT NULL DEFAULT 'member' CHECK (role IN ('owner', 'member')),
+    routing_priority INTEGER NOT NULL DEFAULT 0,
+    UNIQUE (team_id, user_id)
+);
+
+CREATE TABLE IF NOT EXISTS event_types (
+    id                    TEXT PRIMARY KEY,
+    user_id               TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    team_id               TEXT REFERENCES teams(id) ON DELETE SET NULL,
+    slug                  TEXT NOT NULL UNIQUE,  -- unique within workspace (§5)
+    name                  TEXT NOT NULL,
+    description           TEXT,
+    duration_minutes      INTEGER NOT NULL,
+    slot_interval_minutes INTEGER NOT NULL DEFAULT 30,
+    location_type         TEXT NOT NULL DEFAULT 'link'
+                            CHECK (location_type IN ('zoom','google_meet','teams','custom_video','phone','in_person','link')),
+    location_value        TEXT,
+    routing_mode          TEXT NOT NULL DEFAULT 'fixed'
+                            CHECK (routing_mode IN ('fixed', 'round_robin', 'collective', 'priority')),
+    buffer_before_minutes INTEGER NOT NULL DEFAULT 0,
+    buffer_after_minutes  INTEGER NOT NULL DEFAULT 0,
+    min_notice_minutes    INTEGER NOT NULL DEFAULT 0,
+    max_future_days       INTEGER NOT NULL DEFAULT 60,
+    seat_limit            INTEGER NOT NULL DEFAULT 1,
+    is_active             SMALLINT NOT NULL DEFAULT 1,
+    is_public             SMALLINT NOT NULL DEFAULT 1,  -- false = bookable only via direct link
+    created_at            TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE TABLE IF NOT EXISTS event_type_questions (
+    id            TEXT PRIMARY KEY,
+    event_type_id TEXT NOT NULL REFERENCES event_types(id) ON DELETE CASCADE,
+    label         TEXT NOT NULL,
+    type          TEXT NOT NULL CHECK (type IN ('text', 'select', 'checkbox')),
+    options       TEXT,           -- JSON array; used for type='select'
+    required      SMALLINT NOT NULL DEFAULT 0,
+    position      INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS availability_rules (
+    id            TEXT PRIMARY KEY,
+    user_id       TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    event_type_id TEXT REFERENCES event_types(id) ON DELETE CASCADE,  -- NULL = global default
+    day_of_week   INTEGER NOT NULL CHECK (day_of_week BETWEEN 0 AND 6),  -- 0=Sun … 6=Sat
+    start_time    TEXT NOT NULL,  -- HH:MM host-local wall-clock (§6.3)
+    end_time      TEXT NOT NULL,
+    UNIQUE (user_id, event_type_id, day_of_week, start_time, end_time)
+);
+
+CREATE TABLE IF NOT EXISTS availability_overrides (
+    id           TEXT PRIMARY KEY,
+    user_id      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    date         TEXT NOT NULL,   -- YYYY-MM-DD
+    is_available SMALLINT NOT NULL DEFAULT 0,
+    start_time   TEXT,            -- HH:MM; only when is_available=1
+    end_time     TEXT
+);
+
+CREATE TABLE IF NOT EXISTS calendar_connections (
+    id                TEXT PRIMARY KEY,
+    user_id           TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    provider          TEXT NOT NULL CHECK (provider IN ('google', 'microsoft', 'caldav')),
+    access_token_enc  TEXT NOT NULL,   -- AES-GCM encrypted with CALNODE_ENCRYPTION_KEY (§15)
+    refresh_token_enc TEXT,
+    calendar_id       TEXT NOT NULL,
+    check_conflicts   SMALLINT NOT NULL DEFAULT 1,  -- include in free/busy checks (§8.3)
+    is_destination    SMALLINT NOT NULL DEFAULT 0,  -- write bookings to this calendar
+    sync_token        TEXT,            -- incremental sync cursor
+    channel_expires_at TEXT,           -- push-notification channel renewal (§13)
+    created_at        TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE TABLE IF NOT EXISTS bookings (
+    id                  TEXT PRIMARY KEY,
+    event_type_id       TEXT NOT NULL REFERENCES event_types(id) ON DELETE RESTRICT,  -- explicit: historical bookings block event-type deletion
+    host_id             TEXT NOT NULL REFERENCES users(id),
+    start_at            TEXT NOT NULL,  -- UTC ISO 8601 (§6.3)
+    end_at              TEXT NOT NULL,
+    status              TEXT NOT NULL DEFAULT 'confirmed'
+                          CHECK (status IN ('confirmed', 'cancelled')),
+    cancellation_reason TEXT,
+    location_value      TEXT,
+    meeting_link        TEXT,
+    external_event_id   TEXT,           -- calendar event id we created (for own-event exclusion §6.2)
+    created_at          TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
+    updated_at          TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+-- Double-booking guard §6.4 — FIRST-LINE ONLY.
+-- This index blocks exact-start-time collisions, but does NOT prevent overlapping bookings
+-- with different start times (e.g. a 09:45 booking and a 10:00 booking on the same host).
+-- The booking handler MUST also run an overlap check inside BEGIN IMMEDIATE:
+--   SELECT 1 FROM bookings
+--   WHERE host_id = :host_id AND status != 'cancelled'
+--     AND start_at < :new_end_at AND end_at > :new_start_at
+-- Fail with 409 if any row is returned before inserting.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_bookings_no_double
+    ON bookings (host_id, start_at) WHERE status != 'cancelled';
+
+CREATE INDEX IF NOT EXISTS idx_bookings_host_time
+    ON bookings (host_id, start_at, end_at) WHERE status = 'confirmed';
+
+CREATE TABLE IF NOT EXISTS booking_attendees (
+    id            TEXT PRIMARY KEY,
+    booking_id    TEXT NOT NULL REFERENCES bookings(id) ON DELETE CASCADE,
+    name          TEXT NOT NULL,
+    email         TEXT NOT NULL,
+    iana_timezone TEXT NOT NULL DEFAULT 'UTC',
+    is_organizer  SMALLINT NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS booking_answers (
+    id          TEXT PRIMARY KEY,
+    booking_id  TEXT NOT NULL REFERENCES bookings(id) ON DELETE CASCADE,
+    question_id TEXT NOT NULL REFERENCES event_type_questions(id),
+    value       TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS webhooks (
+    id          TEXT PRIMARY KEY,
+    user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    team_id     TEXT REFERENCES teams(id) ON DELETE CASCADE,
+    url         TEXT NOT NULL,
+    events      TEXT NOT NULL,   -- JSON array: ["booking.created","booking.cancelled",...]
+    secret_enc  TEXT NOT NULL,   -- HMAC signing secret, AES-GCM encrypted with CALNODE_ENCRYPTION_KEY (§15)
+    is_active   SMALLINT NOT NULL DEFAULT 1,
+    created_at  TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE TABLE IF NOT EXISTS webhook_deliveries (
+    id                TEXT PRIMARY KEY,
+    webhook_id        TEXT NOT NULL REFERENCES webhooks(id) ON DELETE CASCADE,
+    booking_id        TEXT REFERENCES bookings(id),
+    event             TEXT NOT NULL,
+    payload           TEXT NOT NULL,   -- JSON
+    status            TEXT NOT NULL DEFAULT 'pending'
+                        CHECK (status IN ('pending', 'success', 'failed')),
+    response_status   INTEGER,
+    attempt_count     INTEGER NOT NULL DEFAULT 0,
+    last_attempted_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS jobs (
+    id         TEXT PRIMARY KEY,
+    type       TEXT NOT NULL,
+    payload    TEXT NOT NULL,  -- JSON
+    run_at     TEXT NOT NULL,  -- UTC ISO 8601; worker polls WHERE run_at <= now
+    status     TEXT NOT NULL DEFAULT 'pending'
+                 CHECK (status IN ('pending', 'running', 'done', 'failed')),
+    attempts     INTEGER NOT NULL DEFAULT 0,
+    max_attempts INTEGER NOT NULL DEFAULT 3,
+    last_error   TEXT,
+    created_at TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_jobs_pending
+    ON jobs (run_at) WHERE status = 'pending';
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_jobs_pending;
+DROP TABLE IF EXISTS jobs;
+DROP TABLE IF EXISTS webhook_deliveries;
+DROP TABLE IF EXISTS webhooks;
+DROP TABLE IF EXISTS booking_answers;
+DROP TABLE IF EXISTS booking_attendees;
+DROP INDEX IF EXISTS idx_bookings_host_time;
+DROP INDEX IF EXISTS idx_bookings_no_double;
+DROP TABLE IF EXISTS bookings;
+DROP TABLE IF EXISTS calendar_connections;
+DROP TABLE IF EXISTS availability_overrides;
+DROP TABLE IF EXISTS availability_rules;
+DROP TABLE IF EXISTS event_type_questions;
+DROP TABLE IF EXISTS event_types;
+DROP TABLE IF EXISTS team_members;
+DROP TABLE IF EXISTS teams;
+DROP TABLE IF EXISTS api_keys;
+DROP TABLE IF EXISTS users;
diff --git a/internal/db/migrations/postgres/00002_manage_tokens.sql b/internal/db/migrations/postgres/00002_manage_tokens.sql
new file mode 100644
index 0000000..1a65543
--- /dev/null
+++ b/internal/db/migrations/postgres/00002_manage_tokens.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS booking_manage_tokens (
+    token_hash  TEXT PRIMARY KEY,
+    booking_id  TEXT NOT NULL REFERENCES bookings(id) ON DELETE CASCADE,
+    expires_at  TEXT NOT NULL,
+    created_at  TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_manage_tokens_booking
+    ON booking_manage_tokens (booking_id);
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_manage_tokens_booking;
+DROP TABLE IF EXISTS booking_manage_tokens;
diff --git a/internal/db/migrations/postgres/00003_job_lock_timeout.sql b/internal/db/migrations/postgres/00003_job_lock_timeout.sql
new file mode 100644
index 0000000..b78622d
--- /dev/null
+++ b/internal/db/migrations/postgres/00003_job_lock_timeout.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+
+-- locked_until lets the worker reclaim jobs that were left in 'running'
+-- state after a process crash. Set to now+N seconds on claim; the reaper
+-- at the start of each Poll resets expired running jobs back to 'pending'.
+ALTER TABLE jobs ADD COLUMN locked_until TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_jobs_running_expired
+    ON jobs (locked_until) WHERE status = 'running';
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_jobs_running_expired;
+ALTER TABLE jobs DROP COLUMN locked_until;
diff --git a/internal/db/migrations/postgres/00004_sessions.sql b/internal/db/migrations/postgres/00004_sessions.sql
new file mode 100644
index 0000000..122a6e5
--- /dev/null
+++ b/internal/db/migrations/postgres/00004_sessions.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+
+CREATE TABLE sessions (
+    id         TEXT PRIMARY KEY,  -- 32-byte crypto-random hex; the cookie value
+    user_id    TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    expires_at TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_expires ON sessions(expires_at);
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_sessions_expires;
+DROP INDEX IF EXISTS idx_sessions_user_id;
+DROP TABLE IF EXISTS sessions;
diff --git a/internal/db/migrations/postgres/00005_override_unique.sql b/internal/db/migrations/postgres/00005_override_unique.sql
new file mode 100644
index 0000000..62ebd36
--- /dev/null
+++ b/internal/db/migrations/postgres/00005_override_unique.sql
@@ -0,0 +1,6 @@
+-- +goose Up
+CREATE UNIQUE INDEX IF NOT EXISTS idx_availability_overrides_user_date
+    ON availability_overrides (user_id, date);
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_availability_overrides_user_date;
diff --git a/internal/db/migrations/postgres/00006_jobs_type_payload_unique.sql b/internal/db/migrations/postgres/00006_jobs_type_payload_unique.sql
new file mode 100644
index 0000000..46a7ae2
--- /dev/null
+++ b/internal/db/migrations/postgres/00006_jobs_type_payload_unique.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+
+-- Prevent duplicate jobs of the same type+payload (e.g. two reminder.send jobs
+-- for the same booking_id if enqueueReminder is called more than once).
+CREATE UNIQUE INDEX IF NOT EXISTS ux_jobs_type_payload
+    ON jobs (type, payload);
+
+-- +goose Down
+DROP INDEX IF EXISTS ux_jobs_type_payload;
diff --git a/internal/db/migrations/postgres/00007_user_prefs.sql b/internal/db/migrations/postgres/00007_user_prefs.sql
new file mode 100644
index 0000000..011a07e
--- /dev/null
+++ b/internal/db/migrations/postgres/00007_user_prefs.sql
@@ -0,0 +1,12 @@
+-- +goose Up
+ALTER TABLE users ADD COLUMN time_format TEXT NOT NULL DEFAULT '12h';
+ALTER TABLE users ADD COLUMN week_start  INTEGER NOT NULL DEFAULT 1; -- 1=Monday, 0=Sunday
+-- The two UPDATEs are kept in step with the SQLite migration; they are no-ops
+-- here, because ADD COLUMN with a NOT NULL DEFAULT backfills every existing row.
+UPDATE users SET time_format = '12h' WHERE time_format IS NULL;
+UPDATE users SET week_start  = 1     WHERE week_start  IS NULL;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00008_date_format.sql b/internal/db/migrations/postgres/00008_date_format.sql
new file mode 100644
index 0000000..9b5ab47
--- /dev/null
+++ b/internal/db/migrations/postgres/00008_date_format.sql
@@ -0,0 +1,10 @@
+-- +goose Up
+ALTER TABLE users ADD COLUMN date_format TEXT NOT NULL DEFAULT 'dmy';
+-- The UPDATE is kept in step with the SQLite migration; it is a no-op here,
+-- because ADD COLUMN with a NOT NULL DEFAULT backfills every existing row.
+UPDATE users SET date_format = 'dmy' WHERE date_format IS NULL;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00009_override_reason.sql b/internal/db/migrations/postgres/00009_override_reason.sql
new file mode 100644
index 0000000..c3b8fab
--- /dev/null
+++ b/internal/db/migrations/postgres/00009_override_reason.sql
@@ -0,0 +1,10 @@
+-- +goose Up
+ALTER TABLE availability_overrides ADD COLUMN reason TEXT NOT NULL DEFAULT 'day_off';
+-- Back-fill existing rows: custom hours rows get 'custom_hours', unavailable rows keep 'day_off'.
+UPDATE availability_overrides SET reason = 'custom_hours' WHERE is_available = 1;
+UPDATE availability_overrides SET reason = 'day_off'      WHERE is_available = 0;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00010_messaging_prefs.sql b/internal/db/migrations/postgres/00010_messaging_prefs.sql
new file mode 100644
index 0000000..dfdcc22
--- /dev/null
+++ b/internal/db/migrations/postgres/00010_messaging_prefs.sql
@@ -0,0 +1,29 @@
+-- +goose Up
+-- User-level notification on/off toggles (all default 1 = on, preserving existing behaviour)
+ALTER TABLE users ADD COLUMN notify_confirmation    SMALLINT NOT NULL DEFAULT 1;
+ALTER TABLE users ADD COLUMN notify_cancellation    SMALLINT NOT NULL DEFAULT 1;
+ALTER TABLE users ADD COLUMN notify_reschedule      SMALLINT NOT NULL DEFAULT 1;
+ALTER TABLE users ADD COLUMN notify_reminder        SMALLINT NOT NULL DEFAULT 1;
+ALTER TABLE users ADD COLUMN notify_host_booking    SMALLINT NOT NULL DEFAULT 1;
+ALTER TABLE users ADD COLUMN notify_host_cancel     SMALLINT NOT NULL DEFAULT 1;
+ALTER TABLE users ADD COLUMN notify_host_reschedule SMALLINT NOT NULL DEFAULT 1;
+
+-- Per-event-type custom notes appended to each email type
+ALTER TABLE event_types ADD COLUMN msg_confirmation TEXT;
+ALTER TABLE event_types ADD COLUMN msg_cancellation TEXT;
+ALTER TABLE event_types ADD COLUMN msg_reschedule   TEXT;
+ALTER TABLE event_types ADD COLUMN msg_reminder     TEXT;
+
+-- Per-event-type reminder timing list (replaces the hardcoded 24h)
+CREATE TABLE event_type_reminders (
+    id            TEXT    PRIMARY KEY,
+    event_type_id TEXT    NOT NULL REFERENCES event_types(id) ON DELETE CASCADE,
+    hours_before  INTEGER NOT NULL CHECK(hours_before > 0),
+    UNIQUE(event_type_id, hours_before)
+);
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
+DROP TABLE IF EXISTS event_type_reminders;
diff --git a/internal/db/migrations/postgres/00011_server_settings.sql b/internal/db/migrations/postgres/00011_server_settings.sql
new file mode 100644
index 0000000..c85ba6f
--- /dev/null
+++ b/internal/db/migrations/postgres/00011_server_settings.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+CREATE TABLE server_settings (
+    -- Not an identity column: the row is seeded below with an explicit id and the
+    -- CHECK makes 1 the only legal value, so a sequence would only be misleading.
+    id              INTEGER PRIMARY KEY CHECK(id = 1),
+    smtp_host       TEXT     NOT NULL DEFAULT '',
+    smtp_port       TEXT     NOT NULL DEFAULT '587',
+    smtp_user       TEXT     NOT NULL DEFAULT '',
+    smtp_pass_enc   TEXT     NOT NULL DEFAULT '',
+    smtp_tls        SMALLINT NOT NULL DEFAULT 0,
+    smtp_starttls   SMALLINT NOT NULL DEFAULT 1,
+    email_from      TEXT     NOT NULL DEFAULT '',
+    email_from_name TEXT     NOT NULL DEFAULT 'Calnode',
+    updated_at      TEXT     NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS'))
+);
+-- Seed the single row so UPDATE statements always find it.
+INSERT INTO server_settings (id) VALUES (1) ON CONFLICT DO NOTHING;
+
+-- +goose Down
+DROP TABLE IF EXISTS server_settings;
diff --git a/internal/db/migrations/postgres/00012_auth_providers.sql b/internal/db/migrations/postgres/00012_auth_providers.sql
new file mode 100644
index 0000000..11c19ca
--- /dev/null
+++ b/internal/db/migrations/postgres/00012_auth_providers.sql
@@ -0,0 +1,33 @@
+-- +goose Up
+
+-- Email/password login and OAuth provider columns on users.
+-- email_login=1 means the user can authenticate with email+password.
+-- provider/provider_id store the OAuth identity (only one provider per user).
+ALTER TABLE users ADD COLUMN email_login  SMALLINT NOT NULL DEFAULT 0;
+ALTER TABLE users ADD COLUMN password_hash TEXT;
+ALTER TABLE users ADD COLUMN provider     TEXT;   -- 'google', 'microsoft', etc.
+ALTER TABLE users ADD COLUMN provider_id  TEXT;   -- provider's opaque user ID
+
+-- Invite tokens: single-use, locked to a specific email, 7-day expiry.
+CREATE TABLE invite_tokens (
+    id          TEXT PRIMARY KEY,
+    email       TEXT NOT NULL,
+    token_hash  TEXT NOT NULL UNIQUE,
+    created_by  TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    expires_at  TEXT NOT NULL,
+    used_at     TEXT
+);
+
+CREATE INDEX idx_invite_tokens_email ON invite_tokens(email);
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_invite_tokens_email;
+DROP TABLE IF EXISTS invite_tokens;
+
+-- The SQLite migration rebuilds users here because it cannot drop a column;
+-- Postgres drops the four directly, which reaches the same schema.
+ALTER TABLE users DROP COLUMN provider_id;
+ALTER TABLE users DROP COLUMN provider;
+ALTER TABLE users DROP COLUMN password_hash;
+ALTER TABLE users DROP COLUMN email_login;
diff --git a/internal/db/migrations/postgres/00013_google_oauth_settings.sql b/internal/db/migrations/postgres/00013_google_oauth_settings.sql
new file mode 100644
index 0000000..4e89f5f
--- /dev/null
+++ b/internal/db/migrations/postgres/00013_google_oauth_settings.sql
@@ -0,0 +1,8 @@
+-- +goose Up
+ALTER TABLE server_settings ADD COLUMN google_client_id         TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN google_client_secret_enc TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00014_booking_answers_question_cascade.sql b/internal/db/migrations/postgres/00014_booking_answers_question_cascade.sql
new file mode 100644
index 0000000..119af9a
--- /dev/null
+++ b/internal/db/migrations/postgres/00014_booking_answers_question_cascade.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+-- booking_answers.question_id referenced event_type_questions(id) with no
+-- ON DELETE rule, so deleting an intake question that already had responses
+-- (or deleting an event type that owns such questions) failed with a foreign-key
+-- violation surfaced as a 500. The SQLite migration recreates the table because it
+-- cannot alter a constraint; Postgres replaces the constraint in place.
+--
+-- booking_answers_question_id_fkey is the name Postgres gave the inline REFERENCES
+-- in 00001: <table>_<column>_fkey. A Postgres install can only have reached this
+-- version through that migration, so the name is not a guess.
+ALTER TABLE booking_answers
+    DROP CONSTRAINT booking_answers_question_id_fkey,
+    ADD CONSTRAINT booking_answers_question_id_fkey
+        FOREIGN KEY (question_id) REFERENCES event_type_questions(id) ON DELETE CASCADE;
+
+-- +goose Down
+ALTER TABLE booking_answers
+    DROP CONSTRAINT booking_answers_question_id_fkey,
+    ADD CONSTRAINT booking_answers_question_id_fkey
+        FOREIGN KEY (question_id) REFERENCES event_type_questions(id);
diff --git a/internal/db/migrations/postgres/00015_calendar_connections_expiry.sql b/internal/db/migrations/postgres/00015_calendar_connections_expiry.sql
new file mode 100644
index 0000000..29c5d09
--- /dev/null
+++ b/internal/db/migrations/postgres/00015_calendar_connections_expiry.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+ALTER TABLE calendar_connections ADD COLUMN expiry_at TEXT;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00016_event_types_max_active_bookings.sql b/internal/db/migrations/postgres/00016_event_types_max_active_bookings.sql
new file mode 100644
index 0000000..8eeb56b
--- /dev/null
+++ b/internal/db/migrations/postgres/00016_event_types_max_active_bookings.sql
@@ -0,0 +1,10 @@
+-- +goose Up
+-- Cap how many active (upcoming, non-cancelled) bookings a single invitee may
+-- hold for an event type, keyed by their email. 1 = one at a time (default);
+-- 0 = unlimited. Existing rows adopt the default of 1.
+ALTER TABLE event_types ADD COLUMN max_active_bookings INTEGER NOT NULL DEFAULT 1;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00017_crypto_keystore.sql b/internal/db/migrations/postgres/00017_crypto_keystore.sql
new file mode 100644
index 0000000..d9253a0
--- /dev/null
+++ b/internal/db/migrations/postgres/00017_crypto_keystore.sql
@@ -0,0 +1,18 @@
+-- +goose Up
+CREATE TABLE crypto_keystore (
+    -- SQLite's INTEGER PRIMARY KEY is a rowid alias, and keyvault.go inserts
+    -- without an id and lets it be assigned. Identity reproduces that; BY DEFAULT
+    -- rather than ALWAYS so an explicit id still inserts (key recovery/rotation).
+    id          BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    label       TEXT    NOT NULL UNIQUE,   -- 'primary' | 'recovery'
+    wrapped_dek BYTEA   NOT NULL,          -- DEK encrypted under this entry's KEK
+    kdf         TEXT    NOT NULL,          -- 'argon2id'
+    kdf_salt    BYTEA   NOT NULL,          -- 16 random bytes
+    kdf_params  TEXT    NOT NULL,          -- JSON: {"m":65536,"t":3,"p":2}
+    dek_version INTEGER NOT NULL DEFAULT 1,
+    created_at  TEXT    NOT NULL,
+    updated_at  TEXT    NOT NULL
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS crypto_keystore;
diff --git a/internal/db/migrations/postgres/00018_user_roles.sql b/internal/db/migrations/postgres/00018_user_roles.sql
new file mode 100644
index 0000000..5ec5ffa
--- /dev/null
+++ b/internal/db/migrations/postgres/00018_user_roles.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+-- Workspace roles are Member / Admin / Owner (PRD §8.10). is_admin already
+-- distinguishes member vs admin; is_owner adds the single-owner tier on top.
+-- Owner implies admin. Exactly one owner exists at any time (enforced in app).
+ALTER TABLE users ADD COLUMN is_owner SMALLINT NOT NULL DEFAULT 0;
+
+-- Backfill: the bootstrap user (earliest created) becomes the owner on upgrade.
+-- Fresh installs set is_owner at Setup time instead; this no-ops when empty.
+UPDATE users SET is_owner = 1, is_admin = 1
+WHERE id = (SELECT id FROM users ORDER BY created_at ASC, id ASC LIMIT 1);
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00019_user_archived.sql b/internal/db/migrations/postgres/00019_user_archived.sql
new file mode 100644
index 0000000..fea30d3
--- /dev/null
+++ b/internal/db/migrations/postgres/00019_user_archived.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+-- Member offboarding is archiving (soft-delete), not hard delete: the row and
+-- all its links (past bookings, event types, team memberships) are preserved.
+-- archived_at NULL = active; a timestamp = archived (login blocked, hidden from
+-- default lists, skipped in routing).
+ALTER TABLE users ADD COLUMN archived_at TEXT;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00020_user_archived_by.sql b/internal/db/migrations/postgres/00020_user_archived_by.sql
new file mode 100644
index 0000000..733b5ae
--- /dev/null
+++ b/internal/db/migrations/postgres/00020_user_archived_by.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+-- Track who archived a member so restore can be gated: the owner can restore
+-- anyone; an admin can restore only members they archived themselves.
+ALTER TABLE users ADD COLUMN archived_by TEXT;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00021_event_type_hosts.sql b/internal/db/migrations/postgres/00021_event_type_hosts.sql
new file mode 100644
index 0000000..09123ea
--- /dev/null
+++ b/internal/db/migrations/postgres/00021_event_type_hosts.sql
@@ -0,0 +1,36 @@
+-- +goose Up
+-- Routing model: an event type owns a host list. Each host has a role —
+-- required (always attends), rotation (one is picked per booking), or optional
+-- (joins if free). The three UI modes (Normal/Round-robin/Group) are presets
+-- over these roles. See docs/teams-and-routing.md.
+CREATE TABLE event_type_hosts (
+    id            TEXT    PRIMARY KEY,
+    event_type_id TEXT    NOT NULL REFERENCES event_types(id) ON DELETE CASCADE,
+    user_id       TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role          TEXT    NOT NULL DEFAULT 'required'
+                    CHECK (role IN ('required', 'rotation', 'optional')),
+    priority      INTEGER NOT NULL DEFAULT 0,
+    UNIQUE(event_type_id, user_id)
+);
+
+CREATE INDEX idx_event_type_hosts_event ON event_type_hosts(event_type_id);
+
+-- Round-robin selection strategy for round_robin event types.
+ALTER TABLE event_types ADD COLUMN rr_strategy TEXT NOT NULL DEFAULT 'even'
+    CHECK (rr_strategy IN ('even', 'soonest', 'priority'));
+
+-- Backfill: every existing event type gets its owner as the single required
+-- host, so today's solo events become Normal with the owner as the one host and
+-- host resolution is uniform from day one.
+--
+-- The id matches what SQLite's lower(hex(randomblob(16))) produces — 32 lowercase
+-- hex characters — using gen_random_uuid, which is core since PostgreSQL 13 and so
+-- needs no extension.
+INSERT INTO event_type_hosts (id, event_type_id, user_id, role, priority)
+SELECT replace(gen_random_uuid()::text, '-', ''), id, user_id, 'required', 0 FROM event_types;
+
+-- +goose Down
+DROP TABLE IF EXISTS event_type_hosts;
+-- rr_strategy is deliberately left in place, mirroring the SQLite migration:
+-- Postgres could drop it, but a down that lands on a different schema per engine
+-- is worse than one that leaves a harmless column behind.
diff --git a/internal/db/migrations/postgres/00022_booking_hosts.sql b/internal/db/migrations/postgres/00022_booking_hosts.sql
new file mode 100644
index 0000000..aef70bb
--- /dev/null
+++ b/internal/db/migrations/postgres/00022_booking_hosts.sql
@@ -0,0 +1,24 @@
+-- +goose Up
+-- Multi-host bookings: a booking can have several hosts (Group/collective, or a
+-- round-robin pick plus fixed hosts). bookings.host_id stays the *primary* host
+-- (for the double-book guard + back-compat); booking_hosts records everyone who
+-- attends. See docs/teams-and-routing.md.
+CREATE TABLE booking_hosts (
+    id         TEXT     PRIMARY KEY,
+    booking_id TEXT     NOT NULL REFERENCES bookings(id) ON DELETE CASCADE,
+    user_id    TEXT     NOT NULL REFERENCES users(id),
+    is_primary SMALLINT NOT NULL DEFAULT 0,
+    UNIQUE(booking_id, user_id)
+);
+
+CREATE INDEX idx_booking_hosts_booking ON booking_hosts(booking_id);
+CREATE INDEX idx_booking_hosts_user ON booking_hosts(user_id);
+
+-- Backfill: every existing booking gets its host as the single primary host row,
+-- so host resolution is uniform from day one. The id matches the shape SQLite's
+-- lower(hex(randomblob(16))) produces (32 lowercase hex characters).
+INSERT INTO booking_hosts (id, booking_id, user_id, is_primary)
+SELECT replace(gen_random_uuid()::text, '-', ''), id, host_id, 1 FROM bookings;
+
+-- +goose Down
+DROP TABLE IF EXISTS booking_hosts;
diff --git a/internal/db/migrations/postgres/00023_booking_hosts_event_id.sql b/internal/db/migrations/postgres/00023_booking_hosts_event_id.sql
new file mode 100644
index 0000000..67a58fe
--- /dev/null
+++ b/internal/db/migrations/postgres/00023_booking_hosts_event_id.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+-- Per-host external calendar event ID. Multi-host bookings (Group) create a
+-- calendar event on each assigned host's calendar; we store each one here so it
+-- can be moved/cancelled later. The primary host's id also lives in
+-- bookings.external_event_id (kept for back-compat); this backfills its row.
+ALTER TABLE booking_hosts ADD COLUMN external_event_id TEXT;
+
+UPDATE booking_hosts
+SET external_event_id = (
+    SELECT b.external_event_id FROM bookings b WHERE b.id = booking_hosts.booking_id
+)
+WHERE is_primary = 1;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00024_idempotency_keys.sql b/internal/db/migrations/postgres/00024_idempotency_keys.sql
new file mode 100644
index 0000000..42573e8
--- /dev/null
+++ b/internal/db/migrations/postgres/00024_idempotency_keys.sql
@@ -0,0 +1,18 @@
+-- +goose Up
+-- Idempotency keys for POST /v1/bookings. A client (e.g. an automation agent)
+-- can safely retry a booking with the same Idempotency-Key header: the original
+-- response is replayed verbatim instead of creating a duplicate booking. The key
+-- is reserved (status_code NULL) while the original request runs; on success the
+-- response is stored, on failure the row is released so a retry can proceed.
+-- Rows are purged by the worker 24h after creation.
+CREATE TABLE idempotency_keys (
+    idempotency_key TEXT PRIMARY KEY,
+    request_hash    TEXT NOT NULL,
+    status_code     INTEGER,        -- NULL while the original request is in flight
+    response_body   TEXT,
+    booking_id      TEXT,
+    created_at      TEXT NOT NULL
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS idempotency_keys;
diff --git a/internal/db/migrations/postgres/00025_booking_hosts_needs_sync.sql b/internal/db/migrations/postgres/00025_booking_hosts_needs_sync.sql
new file mode 100644
index 0000000..53741e6
--- /dev/null
+++ b/internal/db/migrations/postgres/00025_booking_hosts_needs_sync.sql
@@ -0,0 +1,10 @@
+-- +goose Up
+-- needs_sync flags a booking_hosts row whose calendar event is known to be at the
+-- WRONG time: set when an inline reschedule move (gcal UpdateEvent) fails, cleared
+-- when it succeeds (inline or via the reconciler). The reconciler re-applies the
+-- move for flagged rows — closing the one gap the presence/absence passes can't see,
+-- since drift can't be inferred from booking state alone. 0 = in sync.
+ALTER TABLE booking_hosts ADD COLUMN needs_sync SMALLINT NOT NULL DEFAULT 0;
+
+-- +goose Down
+ALTER TABLE booking_hosts DROP COLUMN needs_sync;
diff --git a/internal/db/migrations/postgres/00026_event_type_subjects.sql b/internal/db/migrations/postgres/00026_event_type_subjects.sql
new file mode 100644
index 0000000..4e58851
--- /dev/null
+++ b/internal/db/migrations/postgres/00026_event_type_subjects.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+-- Per-event-type custom email subjects for the attendee-facing emails. NULL/empty
+-- means "use the built-in subject" — so existing rows and new ones default to the
+-- current behaviour. Mirrors the msg_* custom-note columns.
+ALTER TABLE event_types ADD COLUMN subj_confirmation TEXT;
+ALTER TABLE event_types ADD COLUMN subj_cancellation TEXT;
+ALTER TABLE event_types ADD COLUMN subj_reschedule   TEXT;
+ALTER TABLE event_types ADD COLUMN subj_reminder     TEXT;
+
+-- +goose Down
+ALTER TABLE event_types DROP COLUMN subj_confirmation;
+ALTER TABLE event_types DROP COLUMN subj_cancellation;
+ALTER TABLE event_types DROP COLUMN subj_reschedule;
+ALTER TABLE event_types DROP COLUMN subj_reminder;
diff --git a/internal/db/migrations/postgres/00027_webhook_fields.sql b/internal/db/migrations/postgres/00027_webhook_fields.sql
new file mode 100644
index 0000000..01a7397
--- /dev/null
+++ b/internal/db/migrations/postgres/00027_webhook_fields.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+-- Per-webhook payload field selection: a JSON array of field keys to include in
+-- the delivery's "data" object. NULL means "the default set" — the original
+-- booking-metadata payload — so existing webhooks keep their exact current shape
+-- (and never start emitting attendee PII or answers without being reconfigured).
+ALTER TABLE webhooks ADD COLUMN fields TEXT;
+
+-- +goose Down
+ALTER TABLE webhooks DROP COLUMN fields;
diff --git a/internal/db/migrations/postgres/00028_tracking_settings.sql b/internal/db/migrations/postgres/00028_tracking_settings.sql
new file mode 100644
index 0000000..d7e469e
--- /dev/null
+++ b/internal/db/migrations/postgres/00028_tracking_settings.sql
@@ -0,0 +1,18 @@
+-- +goose Up
+-- Tracking / analytics settings (instance-wide, on the singleton row):
+--   head_html          raw HTML/JS injected into the <head> of the public booking
+--                      and manage pages (GTM/GA4/Pixel snippets, etc.).
+--   tracking_csp_allow  optional space-separated CSP source allowlist; when set, the
+--                      relaxed public-page CSP is tightened to just these origins.
+--   datalayer_enabled   push booking/cancel/reschedule events into window.dataLayer.
+--   datalayer_fields    JSON array of field keys to include in those pushes.
+ALTER TABLE server_settings ADD COLUMN head_html TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN tracking_csp_allow TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN datalayer_enabled SMALLINT NOT NULL DEFAULT 0;
+ALTER TABLE server_settings ADD COLUMN datalayer_fields TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN head_html;
+ALTER TABLE server_settings DROP COLUMN tracking_csp_allow;
+ALTER TABLE server_settings DROP COLUMN datalayer_enabled;
+ALTER TABLE server_settings DROP COLUMN datalayer_fields;
diff --git a/internal/db/migrations/postgres/00029_branding_settings.sql b/internal/db/migrations/postgres/00029_branding_settings.sql
new file mode 100644
index 0000000..3445c88
--- /dev/null
+++ b/internal/db/migrations/postgres/00029_branding_settings.sql
@@ -0,0 +1,12 @@
+-- +goose Up
+-- Branding (instance-wide, on the singleton row):
+--   business_name  display name used as the wordmark in emails and on the public
+--                  booking/manage pages. Falls back to "Calnode" when empty.
+--   logo_url       absolute https URL to a logo image, shown in the email header
+--                  and the public page header. Empty = text wordmark only.
+ALTER TABLE server_settings ADD COLUMN business_name TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN logo_url TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN business_name;
+ALTER TABLE server_settings DROP COLUMN logo_url;
diff --git a/internal/db/migrations/postgres/00030_logo_height.sql b/internal/db/migrations/postgres/00030_logo_height.sql
new file mode 100644
index 0000000..326a38b
--- /dev/null
+++ b/internal/db/migrations/postgres/00030_logo_height.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+-- Logo display height in px (email header); public pages scale it up modestly.
+-- Operator-adjustable via a 16–64px slider in Settings → Branding; 28 = sensible default.
+ALTER TABLE server_settings ADD COLUMN logo_height INTEGER NOT NULL DEFAULT 28;
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN logo_height;
diff --git a/internal/db/migrations/postgres/00031_logo_opacity.sql b/internal/db/migrations/postgres/00031_logo_opacity.sql
new file mode 100644
index 0000000..6a7bdb8
--- /dev/null
+++ b/internal/db/migrations/postgres/00031_logo_opacity.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+-- Logo opacity as a percentage (20–100); lets operators make the logo subtle.
+-- Applied as CSS opacity in emails + public pages. Default 100 = fully opaque.
+ALTER TABLE server_settings ADD COLUMN logo_opacity INTEGER NOT NULL DEFAULT 100;
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN logo_opacity;
diff --git a/internal/db/migrations/postgres/00032_calendar_account_kind.sql b/internal/db/migrations/postgres/00032_calendar_account_kind.sql
new file mode 100644
index 0000000..0a66861
--- /dev/null
+++ b/internal/db/migrations/postgres/00032_calendar_account_kind.sql
@@ -0,0 +1,10 @@
+-- +goose Up
+-- Records whether a connected Microsoft calendar is a work/school account or a
+-- personal Microsoft account. Personal accounts can't mint Teams-for-Business
+-- links, so this gates whether a "teams" event type can auto-generate one.
+-- '' = unknown (legacy rows / Google) → treated as capable; real value is
+-- captured from the id_token tenant claim on (re)connect.
+ALTER TABLE calendar_connections ADD COLUMN account_kind TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE calendar_connections DROP COLUMN account_kind;
diff --git a/internal/db/migrations/postgres/00033_oauth_mcp.sql b/internal/db/migrations/postgres/00033_oauth_mcp.sql
new file mode 100644
index 0000000..a17e378
--- /dev/null
+++ b/internal/db/migrations/postgres/00033_oauth_mcp.sql
@@ -0,0 +1,49 @@
+-- +goose Up
+-- OAuth 2.1 authorization-server tables backing the MCP "Connect" flow (PRD §11
+-- authorization). Calnode is its own AS for the /mcp resource: clients self-register
+-- (dynamic client registration, public PKCE clients), the workspace owner authorizes
+-- via the existing session/Google/Microsoft login + a consent screen, and bearer
+-- access tokens (hashed, like api_keys) gate /mcp. All token/code values are stored as
+-- SHA-256 hashes — the plaintext is only ever returned once to the client.
+
+CREATE TABLE oauth_clients (
+    client_id     TEXT PRIMARY KEY,
+    client_name   TEXT NOT NULL DEFAULT '',
+    redirect_uris TEXT NOT NULL,            -- JSON array of allowed redirect URIs
+    created_at    TEXT NOT NULL
+);
+
+CREATE TABLE oauth_auth_codes (
+    code_hash      TEXT PRIMARY KEY,        -- SHA-256 of the authorization code
+    client_id      TEXT NOT NULL,
+    user_id        TEXT NOT NULL,
+    redirect_uri   TEXT NOT NULL,
+    code_challenge TEXT NOT NULL,           -- PKCE S256 challenge
+    scope          TEXT NOT NULL DEFAULT '',
+    resource       TEXT NOT NULL DEFAULT '', -- RFC 8707 resource indicator
+    expires_at     TEXT NOT NULL,           -- short-lived (single use)
+    created_at     TEXT NOT NULL
+);
+
+CREATE TABLE oauth_access_tokens (
+    id           TEXT PRIMARY KEY,
+    token_hash   TEXT NOT NULL UNIQUE,      -- SHA-256 of the access token
+    refresh_hash TEXT UNIQUE,               -- SHA-256 of the refresh token (nullable)
+    client_id    TEXT NOT NULL,
+    user_id      TEXT NOT NULL,
+    scope        TEXT NOT NULL DEFAULT '',
+    resource     TEXT NOT NULL DEFAULT '',
+    expires_at   TEXT NOT NULL,             -- access-token expiry
+    created_at   TEXT NOT NULL,
+    last_used_at TEXT
+);
+
+CREATE INDEX idx_oauth_tokens_user ON oauth_access_tokens(user_id);
+CREATE INDEX idx_oauth_tokens_refresh ON oauth_access_tokens(refresh_hash);
+
+-- +goose Down
+DROP INDEX idx_oauth_tokens_refresh;
+DROP INDEX idx_oauth_tokens_user;
+DROP TABLE oauth_access_tokens;
+DROP TABLE oauth_auth_codes;
+DROP TABLE oauth_clients;
diff --git a/internal/db/migrations/postgres/00034_llm_settings.sql b/internal/db/migrations/postgres/00034_llm_settings.sql
new file mode 100644
index 0000000..443df0a
--- /dev/null
+++ b/internal/db/migrations/postgres/00034_llm_settings.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+-- Optional LLM layer config (PRD §8.11), stored like SMTP/Google settings on the
+-- single server_settings row. Provider-agnostic: any OpenAI-compatible chat-completions
+-- endpoint. Off by default; api key encrypted at rest (CALNODE_ENCRYPTION_KEY).
+ALTER TABLE server_settings ADD COLUMN llm_endpoint    TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN llm_model       TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN llm_api_key_enc TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN llm_enabled     SMALLINT NOT NULL DEFAULT 0;
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN llm_enabled;
+ALTER TABLE server_settings DROP COLUMN llm_api_key_enc;
+ALTER TABLE server_settings DROP COLUMN llm_model;
+ALTER TABLE server_settings DROP COLUMN llm_endpoint;
diff --git a/internal/db/migrations/postgres/00035_llm_instructions.sql b/internal/db/migrations/postgres/00035_llm_instructions.sql
new file mode 100644
index 0000000..1d08451
--- /dev/null
+++ b/internal/db/migrations/postgres/00035_llm_instructions.sql
@@ -0,0 +1,8 @@
+-- +goose Up
+-- Admin "Additional instructions" appended to the assistant's base system prompt
+-- (tone, business context, do's/don'ts). The base prompt — the tool-calling contract +
+-- safety rails — stays in code; this is the customization layer only.
+ALTER TABLE server_settings ADD COLUMN llm_extra_instructions TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN llm_extra_instructions;
diff --git a/internal/db/migrations/postgres/00036_zoom_integration.sql b/internal/db/migrations/postgres/00036_zoom_integration.sql
new file mode 100644
index 0000000..82e790e
--- /dev/null
+++ b/internal/db/migrations/postgres/00036_zoom_integration.sql
@@ -0,0 +1,25 @@
+-- +goose Up
+-- Zoom OAuth app credentials (one app per instance; each host then connects their
+-- own Zoom account via OAuth).
+ALTER TABLE server_settings ADD COLUMN zoom_client_id         TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN zoom_client_secret_enc TEXT NOT NULL DEFAULT '';
+
+-- Per-host Zoom OAuth tokens. Zoom is a meeting-link provider, not a calendar, so it gets
+-- its own table (calendar_connections.provider has a CHECK constraint for calendar kinds).
+-- One connection per user (user_id PK).
+CREATE TABLE zoom_connections (
+    user_id           TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+    access_token_enc  TEXT NOT NULL,
+    refresh_token_enc TEXT NOT NULL DEFAULT '',
+    expiry_at         TEXT NOT NULL DEFAULT '',
+    created_at        TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS'))
+);
+
+-- The Zoom meeting id minted for a booking (used to update/delete the meeting on
+-- reschedule/cancel). Empty for non-Zoom bookings or manual links.
+ALTER TABLE bookings ADD COLUMN zoom_meeting_id TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00037_stripe_payments.sql b/internal/db/migrations/postgres/00037_stripe_payments.sql
new file mode 100644
index 0000000..533473d
--- /dev/null
+++ b/internal/db/migrations/postgres/00037_stripe_payments.sql
@@ -0,0 +1,26 @@
+-- +goose Up
+-- Stripe API credentials (one Stripe account per instance; admin configures in Settings).
+ALTER TABLE server_settings ADD COLUMN stripe_secret_key_enc     TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN stripe_publishable_key    TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN stripe_webhook_secret_enc TEXT NOT NULL DEFAULT '';
+
+-- Per-event-type price. 0 = free (the default; today's flow is unchanged).
+ALTER TABLE event_types ADD COLUMN price_cents INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE event_types ADD COLUMN currency    TEXT    NOT NULL DEFAULT 'usd';
+
+-- Payment state, separate from booking status so a paid hold can occupy the slot
+-- (status='confirmed', so the double-booking guard reserves it) while still awaiting
+-- payment (payment_status='pending'); side-effects are deferred until 'paid'. A new
+-- booking-status value would have required a SQLite table rebuild (CHECK constraint).
+--   none      → free booking, no payment involved (default)
+--   pending   → awaiting Stripe Checkout completion (slot held)
+--   paid      → payment captured; confirmation side-effects have run
+--   refunded  → payment refunded (on cancel)
+ALTER TABLE bookings ADD COLUMN payment_status           TEXT NOT NULL DEFAULT 'none';
+ALTER TABLE bookings ADD COLUMN stripe_session_id        TEXT NOT NULL DEFAULT '';
+ALTER TABLE bookings ADD COLUMN stripe_payment_intent_id TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00038_booking_amount_paid.sql b/internal/db/migrations/postgres/00038_booking_amount_paid.sql
new file mode 100644
index 0000000..1201282
--- /dev/null
+++ b/internal/db/migrations/postgres/00038_booking_amount_paid.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+-- Record what was actually charged on the booking (immutable payment record), independent
+-- of the event type's current price_cents which can change later. Set from the Stripe
+-- Checkout session's amount_total/currency at confirmation. 0/'' for free bookings.
+ALTER TABLE bookings ADD COLUMN amount_paid_cents    INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE bookings ADD COLUMN amount_paid_currency TEXT    NOT NULL DEFAULT '';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00039_calendar_account_email.sql b/internal/db/migrations/postgres/00039_calendar_account_email.sql
new file mode 100644
index 0000000..714719c
--- /dev/null
+++ b/internal/db/migrations/postgres/00039_calendar_account_email.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+-- Identify each connected calendar account so a user can connect several (e.g. work Google
+-- + personal Gmail): re-auth of the same account upserts its row, a new account inserts a new
+-- row. Used for dedup + display. Existing single connections backfill to '' and keep working
+-- (free/busy doesn't need the email); they get a real value on next re-connect.
+ALTER TABLE calendar_connections ADD COLUMN account_email TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00040_magic_link_tokens.sql b/internal/db/migrations/postgres/00040_magic_link_tokens.sql
new file mode 100644
index 0000000..b871afc
--- /dev/null
+++ b/internal/db/migrations/postgres/00040_magic_link_tokens.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+-- One-time, short-lived login links emailed to a user. We store only the SHA-256 of the
+-- token (never the raw value); single-use is enforced by used_at.
+CREATE TABLE magic_link_tokens (
+    token_hash TEXT PRIMARY KEY,
+    user_id    TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    expires_at TEXT NOT NULL,
+    used_at    TEXT,
+    created_at TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS'))
+);
+
+-- +goose Down
+DROP TABLE magic_link_tokens;
diff --git a/internal/db/migrations/postgres/00041_native_analytics.sql b/internal/db/migrations/postgres/00041_native_analytics.sql
new file mode 100644
index 0000000..e8ba9fd
--- /dev/null
+++ b/internal/db/migrations/postgres/00041_native_analytics.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+-- Native GA4 / GTM: store just the ID; the booking page renders the official loader snippet
+-- (no need to paste the whole script). Empty = that tag is off. Validated to the ID format on
+-- write so the value is safe to interpolate into a script.
+ALTER TABLE server_settings ADD COLUMN gtm_container_id  TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN ga4_measurement_id TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00042_livekit.sql b/internal/db/migrations/postgres/00042_livekit.sql
new file mode 100644
index 0000000..bb5d4b4
--- /dev/null
+++ b/internal/db/migrations/postgres/00042_livekit.sql
@@ -0,0 +1,26 @@
+-- LiveKit (self-hostable WebRTC video) as a built-in meeting location.
+--
+-- Two parts:
+--   1. Instance-level config columns (server URL + API key/secret, secret encrypted) on
+--      server_settings, plus a livekit_room column on bookings — like Zoom/Stripe.
+--   2. Widen the event_types.location_type CHECK to allow 'livekit'.
+--
+-- The SQLite migration rebuilds event_types for part 2, and needs NO TRANSACTION plus
+-- PRAGMA foreign_keys=OFF to do it without cascade-deleting the child rows. Postgres
+-- replaces the constraint in place, so none of that applies: this file runs in goose's
+-- transaction like every other one. event_types_location_type_check is the name Postgres
+-- gave the inline CHECK in 00001 (<table>_<column>_check).
+
+-- +goose Up
+ALTER TABLE server_settings ADD COLUMN livekit_url            TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN livekit_api_key        TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN livekit_api_secret_enc TEXT NOT NULL DEFAULT '';
+ALTER TABLE bookings ADD COLUMN livekit_room TEXT NOT NULL DEFAULT '';
+
+ALTER TABLE event_types
+    DROP CONSTRAINT event_types_location_type_check,
+    ADD CONSTRAINT event_types_location_type_check
+        CHECK (location_type IN ('zoom','google_meet','teams','custom_video','phone','in_person','link','livekit'));
+
+-- +goose Down
+-- Irreversible widening of a CHECK; the added columns are harmless. No-op down.
diff --git a/internal/db/migrations/postgres/00043_livekit_recording.sql b/internal/db/migrations/postgres/00043_livekit_recording.sql
new file mode 100644
index 0000000..07a6edb
--- /dev/null
+++ b/internal/db/migrations/postgres/00043_livekit_recording.sql
@@ -0,0 +1,23 @@
+-- +goose Up
+-- Meeting recording (LiveKit Egress). Off unless enabled; recordings upload to the same
+-- S3 bucket Litestream backs up to (LITESTREAM_* env), under a recordings/ prefix.
+ALTER TABLE server_settings ADD COLUMN recordings_enabled SMALLINT NOT NULL DEFAULT 0;
+
+CREATE TABLE recordings (
+    id          TEXT PRIMARY KEY,
+    booking_id  TEXT,                                   -- derived from room "booking-<id>"; nullable
+    room        TEXT NOT NULL,
+    egress_id   TEXT NOT NULL,
+    status      TEXT NOT NULL DEFAULT 'active',         -- active | complete | failed
+    object_key  TEXT NOT NULL DEFAULT '',               -- S3 key of the finished file
+    duration_s  INTEGER NOT NULL DEFAULT 0,
+    started_by  TEXT NOT NULL DEFAULT '',               -- host participant identity
+    created_at  TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
+    updated_at  TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+CREATE INDEX idx_recordings_room ON recordings(room);
+CREATE INDEX idx_recordings_egress ON recordings(egress_id);
+
+-- +goose Down
+-- Leave the column; drop the table.
+DROP TABLE IF EXISTS recordings;
diff --git a/internal/db/migrations/postgres/00044_meeting_consents.sql b/internal/db/migrations/postgres/00044_meeting_consents.sql
new file mode 100644
index 0000000..5818d0d
--- /dev/null
+++ b/internal/db/migrations/postgres/00044_meeting_consents.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+-- In-meeting recording consent — notice + consent-or-leave (Zoom/Teams/Meet model). This is an
+-- AUDIT LOG of who acknowledged the recording notice; it does NOT gate recording (recording
+-- starts on the host's click). One row per participant identity per room.
+CREATE TABLE meeting_consents (
+    room                 TEXT NOT NULL,
+    participant_identity TEXT NOT NULL,
+    name                 TEXT NOT NULL DEFAULT '',
+    decision             TEXT NOT NULL DEFAULT 'continue',  -- continue | leave
+    decided_at           TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
+    PRIMARY KEY (room, participant_identity)
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS meeting_consents;
diff --git a/internal/db/migrations/postgres/00045_notetaker.sql b/internal/db/migrations/postgres/00045_notetaker.sql
new file mode 100644
index 0000000..45cd309
--- /dev/null
+++ b/internal/db/migrations/postgres/00045_notetaker.sql
@@ -0,0 +1,34 @@
+-- +goose Up
+-- Notetaker: transcribe finished recordings (Deepgram) and summarise them (the BYO-LLM layer)
+-- into notes attached to the booking. Off unless enabled + a Deepgram key is set.
+ALTER TABLE server_settings ADD COLUMN notetaker_enabled SMALLINT NOT NULL DEFAULT 0;
+ALTER TABLE server_settings ADD COLUMN stt_api_key_enc   TEXT NOT NULL DEFAULT '';  -- Deepgram key (encrypted)
+
+CREATE TABLE transcripts (
+    id           TEXT PRIMARY KEY,
+    booking_id   TEXT,                                   -- nullable; grouping key
+    recording_id TEXT NOT NULL,                          -- one transcript per recording
+    room         TEXT NOT NULL,
+    text         TEXT NOT NULL DEFAULT '',
+    segments     TEXT NOT NULL DEFAULT '[]',             -- JSON [{speaker,start,end,text}]
+    status       TEXT NOT NULL DEFAULT 'complete',       -- complete | failed
+    created_at   TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
+    updated_at   TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+CREATE INDEX idx_transcripts_booking ON transcripts(booking_id);
+CREATE INDEX idx_transcripts_recording ON transcripts(recording_id);
+
+CREATE TABLE notes (
+    id          TEXT PRIMARY KEY,
+    booking_id  TEXT NOT NULL,                           -- one notes doc per booking (regenerable)
+    content     TEXT NOT NULL DEFAULT '',                -- markdown summary
+    model       TEXT NOT NULL DEFAULT '',
+    status      TEXT NOT NULL DEFAULT 'complete',
+    created_at  TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
+    updated_at  TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+);
+CREATE UNIQUE INDEX idx_notes_booking ON notes(booking_id);
+
+-- +goose Down
+DROP TABLE IF EXISTS notes;
+DROP TABLE IF EXISTS transcripts;
diff --git a/internal/db/migrations/postgres/00046_legal_links.sql b/internal/db/migrations/postgres/00046_legal_links.sql
new file mode 100644
index 0000000..5fef0ab
--- /dev/null
+++ b/internal/db/migrations/postgres/00046_legal_links.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+-- Legal links (instance-wide, on the singleton settings row): absolute URLs to the
+-- operator's own Privacy Policy and Terms. Shown as links in the public booking-page
+-- footer and linked from the cookie-consent banner. Empty = the link is hidden.
+-- The operator is the data controller; Calnode only surfaces the links they provide.
+ALTER TABLE server_settings ADD COLUMN privacy_url TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN terms_url TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN privacy_url;
+ALTER TABLE server_settings DROP COLUMN terms_url;
diff --git a/internal/db/migrations/postgres/00047_event_type_archived.sql b/internal/db/migrations/postgres/00047_event_type_archived.sql
new file mode 100644
index 0000000..a863f8d
--- /dev/null
+++ b/internal/db/migrations/postgres/00047_event_type_archived.sql
@@ -0,0 +1,10 @@
+-- +goose Up
+-- Archived event types: soft-hide from the default admin list without deleting the
+-- row (deletion is blocked by ON DELETE RESTRICT once any booking exists). NULL =
+-- not archived. Archiving also sets is_active = 0, so every existing bookability gate
+-- (public booking page, the shared booking-creation core, MCP) already excludes an
+-- archived type — no query needs to learn about archived_at to stay correct. Reversible.
+ALTER TABLE event_types ADD COLUMN archived_at TEXT;
+
+-- +goose Down
+ALTER TABLE event_types DROP COLUMN archived_at;
diff --git a/internal/db/migrations/postgres/00048_override_group.sql b/internal/db/migrations/postgres/00048_override_group.sql
new file mode 100644
index 0000000..e74d3f7
--- /dev/null
+++ b/internal/db/migrations/postgres/00048_override_group.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+-- group_id ties together the per-date rows created from a single date-range block
+-- (an "out of office" span), so the UI can show and delete them as one entry. NULL
+-- for single-date overrides. Slot generation is unchanged — it still reads the
+-- individual per-date rows; the group is purely an admin-side convenience.
+ALTER TABLE availability_overrides ADD COLUMN group_id TEXT;
+
+-- +goose Down
+ALTER TABLE availability_overrides DROP COLUMN group_id;
diff --git a/internal/db/migrations/postgres/00049_connection_calendars.sql b/internal/db/migrations/postgres/00049_connection_calendars.sql
new file mode 100644
index 0000000..394922e
--- /dev/null
+++ b/internal/db/migrations/postgres/00049_connection_calendars.sql
@@ -0,0 +1,38 @@
+-- +goose Up
+-- Per-account calendar selection. A single connected account (calendar_connections,
+-- keyed by user_id+provider+account_email) can now expose several calendars, each
+-- independently included in free/busy conflict checks and optionally the write target.
+--
+-- Deliberately keyed by the STABLE account identity (user_id, provider, account_email),
+-- NOT by calendar_connections.id: the connection row is deleted+reinserted (new id) on
+-- every OAuth token refresh, so an FK to it would cascade-delete a user's calendar
+-- selections on the next hourly refresh. Disconnect flows delete these rows explicitly.
+CREATE TABLE IF NOT EXISTS connection_calendars (
+    id              TEXT PRIMARY KEY,
+    user_id         TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    provider        TEXT NOT NULL,
+    account_email   TEXT NOT NULL DEFAULT '',
+    calendar_id     TEXT NOT NULL,          -- provider's calendar id ("primary", an address, a URL)
+    name            TEXT NOT NULL DEFAULT '', -- display name (filled from the provider's calendar list)
+    check_conflicts SMALLINT NOT NULL DEFAULT 1, -- include this calendar in free/busy
+    is_destination  SMALLINT NOT NULL DEFAULT 0, -- write new booking events here (at most one per user)
+    created_at      TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
+    UNIQUE (user_id, provider, account_email, calendar_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_connection_calendars_account
+    ON connection_calendars (user_id, provider, account_email);
+
+-- Seed from existing connections so current behaviour is preserved on upgrade: each
+-- connected account's single calendar becomes one selected calendar with the same flags.
+-- ON CONFLICT DO NOTHING is SQLite's INSERT OR IGNORE; the id matches the shape
+-- lower(hex(randomblob(16))) produces (32 lowercase hex characters).
+INSERT INTO connection_calendars
+    (id, user_id, provider, account_email, calendar_id, name, check_conflicts, is_destination)
+SELECT replace(gen_random_uuid()::text, '-', ''), user_id, provider, COALESCE(account_email, ''),
+       calendar_id, '', check_conflicts, is_destination
+FROM calendar_connections
+ON CONFLICT DO NOTHING;
+
+-- +goose Down
+DROP TABLE IF EXISTS connection_calendars;
diff --git a/internal/db/migrations/postgres/00050_branding_banner.sql b/internal/db/migrations/postgres/00050_branding_banner.sql
new file mode 100644
index 0000000..ea8a528
--- /dev/null
+++ b/internal/db/migrations/postgres/00050_branding_banner.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+-- Banner (instance-wide, on the singleton row): an optional full-width image
+-- shown below the logo on the public booking/manage pages and in emails.
+--   banner_url     absolute https URL to a banner image; empty = hidden.
+--   banner_opacity 20-100; CSS opacity. 100 = fully opaque.
+ALTER TABLE server_settings ADD COLUMN banner_url TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN banner_opacity INTEGER NOT NULL DEFAULT 100;
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN banner_url;
+ALTER TABLE server_settings DROP COLUMN banner_opacity;
diff --git a/internal/db/migrations/postgres/00051_booking_attendee_locale.sql b/internal/db/migrations/postgres/00051_booking_attendee_locale.sql
new file mode 100644
index 0000000..fc7492d
--- /dev/null
+++ b/internal/db/migrations/postgres/00051_booking_attendee_locale.sql
@@ -0,0 +1,12 @@
+-- +goose Up
+-- Captures the attendee's resolved page locale at booking time (mirrors iana_timezone) —
+-- this can only be captured now, not reconstructed later, since it needs the actual
+-- Accept-Language/cookie/lang= state the visitor saw when they booked. Not yet consumed by
+-- emails (mailer has no i18n support yet — see internal-docs/i18n-plan.md); this just
+-- captures the data so it exists once that work lands. Existing rows backfill to 'en'.
+ALTER TABLE booking_attendees ADD COLUMN locale TEXT NOT NULL DEFAULT 'en';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00052_msg_greeting.sql b/internal/db/migrations/postgres/00052_msg_greeting.sql
new file mode 100644
index 0000000..35f76fa
--- /dev/null
+++ b/internal/db/migrations/postgres/00052_msg_greeting.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+-- Per-event-type override for the conversational assistant's opening greeting. Unlike
+-- msg_confirmation/msg_cancellation/etc. (seeded with an English default at CreateEventType),
+-- this is left NULL by default: the assistant falls back to the locale-keyed
+-- "assistant_greeting" translation when unset, so translation keeps working automatically
+-- for anyone who doesn't touch it. Only set (admin-authored, untranslated) once an operator
+-- explicitly customizes it.
+ALTER TABLE event_types ADD COLUMN msg_greeting TEXT;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00053_fallback_locale.sql b/internal/db/migrations/postgres/00053_fallback_locale.sql
new file mode 100644
index 0000000..c7caff0
--- /dev/null
+++ b/internal/db/migrations/postgres/00053_fallback_locale.sql
@@ -0,0 +1,10 @@
+-- +goose Up
+-- What a visitor sees when their browser doesn't ask for any locale Calnode supports
+-- (default English) — e.g. an operator serving a mostly Spanish-speaking customer base
+-- might want Spanish instead. See internal/i18n.ResolveWithFallback.
+ALTER TABLE server_settings ADD COLUMN fallback_locale TEXT NOT NULL DEFAULT 'en';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00054_resend_api_key.sql b/internal/db/migrations/postgres/00054_resend_api_key.sql
new file mode 100644
index 0000000..6c2852c
--- /dev/null
+++ b/internal/db/migrations/postgres/00054_resend_api_key.sql
@@ -0,0 +1,19 @@
+-- +goose Up
+-- An optional Resend API key, so Calnode can deliver over Resend's HTTPS API instead of
+-- SMTP. Needed because several hosting platforms (Railway below Pro, among others) block
+-- outbound SMTP on their cheaper plans by dropping the packets, which is indistinguishable
+-- from a misconfiguration and cannot be worked around at the SMTP layer at all.
+--
+-- Encrypted at rest with the same envelope scheme as smtp_pass_enc; never returned by the
+-- API, which exposes only a resend_api_key_set boolean.
+--
+-- Presence of this key is what selects the transport: set means use the HTTPS API, empty
+-- means fall back to SMTP. That is deliberate over probing SMTP at startup and switching
+-- automatically - a probe tests reachability at boot, not at send time, and a working TCP
+-- connection is not the same thing as a working delivery path. See internal/mailer/resend.go.
+ALTER TABLE server_settings ADD COLUMN resend_api_key_enc TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00055_booking_hosts_calendar_id.sql b/internal/db/migrations/postgres/00055_booking_hosts_calendar_id.sql
new file mode 100644
index 0000000..a7d2709
--- /dev/null
+++ b/internal/db/migrations/postgres/00055_booking_hosts_calendar_id.sql
@@ -0,0 +1,21 @@
+-- +goose Up
+-- Which calendar a booking's event was actually written into.
+--
+-- Until now only external_event_id was stored, and reschedule/cancel re-resolved the
+-- target calendar from the host's CURRENT destination. That was harmless while the
+-- destination was effectively fixed at the account's default calendar, but now that a host
+-- can pick any calendar inside a connected account, changing that choice would leave every
+-- existing booking's event id pointing at a calendar it does not live in: the update or
+-- delete resolves to the new calendar, the provider returns 404, the booking cancels in
+-- Calnode, and the meeting silently stays on the host's calendar forever.
+--
+-- Deliberately nullable with no backfill. Empty means "resolve the way we always did",
+-- which is exactly right for rows created before this column existed - their events do live
+-- in whatever the destination was and still is. Only new bookings record the calendar, so
+-- the guarantee starts applying from here without rewriting history we cannot verify.
+ALTER TABLE booking_hosts ADD COLUMN external_calendar_id TEXT;
+
+-- +goose Down
+-- Deliberately a no-op, mirroring the SQLite migration: Postgres could drop the
+-- column, but a down that lands on a different schema per engine is worse than a
+-- down that lands on none.
diff --git a/internal/db/migrations/postgres/00056_bookings_list_indexes.sql b/internal/db/migrations/postgres/00056_bookings_list_indexes.sql
new file mode 100644
index 0000000..d07b8ad
--- /dev/null
+++ b/internal/db/migrations/postgres/00056_bookings_list_indexes.sql
@@ -0,0 +1,34 @@
+-- +goose Up
+-- Indexes for the paginated bookings list (§9).
+--
+-- The two indexes that existed both lead on host_id and are partial
+-- (idx_bookings_no_double, idx_bookings_host_time), which serves the double-book
+-- guard well and the list not at all. Every paged query planned as:
+--
+--     SCAN bookings USING INDEX idx_bookings_no_double
+--     USE TEMP B-TREE FOR ORDER BY
+--
+-- i.e. sort the entire matching set to hand back 25 rows. Paginating the API without
+-- this makes the response smaller but not the work: the cost still grows with every
+-- booking ever made.
+--
+-- With (start_at, id) the same query plans as a plain index walk and stops at the
+-- LIMIT, no sort:
+--
+--     SCAN bookings USING INDEX idx_bookings_start_at
+--
+-- id is included as the tiebreaker the list orders by; start_at is not unique, and
+-- without a second key two bookings at the same time can swap between pages and one
+-- of them is never shown.
+CREATE INDEX IF NOT EXISTS idx_bookings_start_at
+    ON bookings (start_at, id);
+
+-- Filtering to one event type went from a full scan to a search. The trailing
+-- ORDER BY term still costs a small in-memory sort within equal start_at groups,
+-- which is not worth another index.
+CREATE INDEX IF NOT EXISTS idx_bookings_event_type_start
+    ON bookings (event_type_id, start_at, id);
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_bookings_start_at;
+DROP INDEX IF EXISTS idx_bookings_event_type_start;
diff --git a/internal/db/migrations/postgres/00057_event_type_show_taken_slots.sql b/internal/db/migrations/postgres/00057_event_type_show_taken_slots.sql
new file mode 100644
index 0000000..6c88e60
--- /dev/null
+++ b/internal/db/migrations/postgres/00057_event_type_show_taken_slots.sql
@@ -0,0 +1,18 @@
+-- +goose Up
+-- Whether the booking page shows already-booked times greyed out instead of hiding
+-- them. Requested in discussion #14, tracked as issue #19.
+--
+-- Default 0, and that default is the point rather than caution. The slots endpoint is
+-- public and unauthenticated, so turning this on makes the host's booked hours legible
+-- to anyone with the link. That is a fair trade for a public-hours use case (an intro
+-- call, a clinic, a tutor), where a visibly busy calendar communicates demand. It is a
+-- privacy regression for an instance fronting a team's internal calendars, which is why
+-- it must be chosen per event type and never inherited by surprise.
+--
+-- Only starts a booking or calendar conflict removed are shown. Times outside the
+-- host's working hours are never rendered, so the shape of the working day is not
+-- disclosed by the grid itself.
+ALTER TABLE event_types ADD COLUMN show_taken_slots SMALLINT NOT NULL DEFAULT 0;
+
+-- +goose Down
+ALTER TABLE event_types DROP COLUMN show_taken_slots;
diff --git a/internal/db/migrations_internal_test.go b/internal/db/migrations_internal_test.go
new file mode 100644
index 0000000..328b3a1
--- /dev/null
+++ b/internal/db/migrations_internal_test.go
@@ -0,0 +1,58 @@
+package db
+
+import (
+	"io/fs"
+	"testing"
+)
+
+// TestMigrationDirs_parity is what lets TargetVersion be dialect-independent and
+// what stops the two sets drifting: a migration added for one engine and
+// forgotten for the other would otherwise only show up when someone ran the other
+// engine.
+func TestMigrationDirs_parity(t *testing.T) {
+	sqliteFiles := migrationFiles(t, DialectSQLite)
+	postgresFiles := migrationFiles(t, DialectPostgres)
+
+	if len(sqliteFiles) != len(postgresFiles) {
+		t.Fatalf("migration count differs: sqlite %d, postgres %d", len(sqliteFiles), len(postgresFiles))
+	}
+
+	for i, name := range sqliteFiles {
+		if postgresFiles[i] != name {
+			t.Errorf("migration %d differs: sqlite %q, postgres %q", i, name, postgresFiles[i])
+		}
+	}
+
+	sqliteTarget, err := maxVersion(DialectSQLite.migrationsDir())
+	if err != nil {
+		t.Fatalf("maxVersion(sqlite): %v", err)
+	}
+	postgresTarget, err := maxVersion(DialectPostgres.migrationsDir())
+	if err != nil {
+		t.Fatalf("maxVersion(postgres): %v", err)
+	}
+	if sqliteTarget != postgresTarget {
+		t.Errorf("target version differs: sqlite %d, postgres %d", sqliteTarget, postgresTarget)
+	}
+	if int(sqliteTarget) != len(sqliteFiles) {
+		t.Errorf("target version %d does not match file count %d — a gap or a duplicate number",
+			sqliteTarget, len(sqliteFiles))
+	}
+}
+
+// migrationFiles lists a dialect's embedded migrations, sorted (fs.ReadDir sorts
+// by name, which for NNNNN_ prefixes is version order).
+func migrationFiles(t *testing.T, dialect Dialect) []string {
+	t.Helper()
+
+	entries, err := fs.ReadDir(migrations, dialect.migrationsDir())
+	if err != nil {
+		t.Fatalf("read %s: %v", dialect.migrationsDir(), err)
+	}
+
+	names := make([]string, 0, len(entries))
+	for _, e := range entries {
+		names = append(names, e.Name())
+	}
+	return names
+}
diff --git a/internal/db/postgres_test.go b/internal/db/postgres_test.go
new file mode 100644
index 0000000..f28e15a
--- /dev/null
+++ b/internal/db/postgres_test.go
@@ -0,0 +1,491 @@
+package db_test
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"net/url"
+	"os"
+	"regexp"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// The PostgreSQL tests need a server, so they are opt-in: with
+// CALNODE_TEST_POSTGRES_DSN unset they skip, and upstream CI and anyone running
+// the SQLite build see no change. Point it at a database you are happy for a test
+// to create and drop schemas in, e.g.
+//
+//	CALNODE_TEST_POSTGRES_DSN=postgres://postgres:pw@127.0.0.1:5432/calnode?sslmode=disable
+const postgresDSNEnv = "CALNODE_TEST_POSTGRES_DSN"
+
+// openTestPostgres returns a handle scoped to a schema of its own, created for
+// this test and dropped when it finishes. A schema rather than a database because
+// CREATE DATABASE cannot run inside a transaction and cannot be reached over the
+// same connection, and a private schema is enough: goose_db_version and every
+// table land inside it, so tests neither collide nor leave anything behind.
+func openTestPostgres(t *testing.T) *db.DB {
+	t.Helper()
+
+	dsn := os.Getenv(postgresDSNEnv)
+	if dsn == "" {
+		t.Skipf("%s not set; skipping PostgreSQL tests", postgresDSNEnv)
+	}
+
+	admin, err := db.OpenDB(dsn)
+	if err != nil {
+		t.Fatalf("db.OpenDB(admin): %v", err)
+	}
+	defer admin.Close()
+
+	// Random hex, not a test name: this is interpolated into DDL, and an
+	// identifier we generated byte by byte cannot carry a quote or a keyword.
+	buf := make([]byte, 8)
+	if _, err := rand.Read(buf); err != nil {
+		t.Fatalf("rand: %v", err)
+	}
+	schema := "calnode_test_" + hex.EncodeToString(buf)
+
+	if _, err := admin.Exec(`CREATE SCHEMA ` + schema); err != nil {
+		t.Fatalf("create schema %s: %v", schema, err)
+	}
+
+	handle, err := db.OpenDB(withSearchPath(t, dsn, schema))
+	if err != nil {
+		t.Fatalf("db.OpenDB(%s): %v", schema, err)
+	}
+
+	t.Cleanup(func() {
+		handle.Close()
+
+		cleanup, err := db.OpenDB(dsn)
+		if err != nil {
+			t.Errorf("reopen to drop schema %s: %v", schema, err)
+			return
+		}
+		defer cleanup.Close()
+		if _, err := cleanup.Exec(`DROP SCHEMA ` + schema + ` CASCADE`); err != nil {
+			t.Errorf("drop schema %s: %v", schema, err)
+		}
+	})
+
+	return handle
+}
+
+// withSearchPath adds search_path to the DSN. pgx forwards unrecognised URL
+// parameters as server runtime parameters, so this pins every session on the
+// handle to the test's schema without a per-connection hook.
+func withSearchPath(t *testing.T, dsn, schema string) string {
+	t.Helper()
+
+	u, err := url.Parse(dsn)
+	if err != nil {
+		t.Fatalf("parse %s: %v", postgresDSNEnv, err)
+	}
+	q := u.Query()
+	q.Set("search_path", schema)
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+func TestPostgres_openDialectAndPool(t *testing.T) {
+	handle := openTestPostgres(t)
+
+	if got := handle.Dialect(); got != db.DialectPostgres {
+		t.Errorf("dialect = %v; want %v", got, db.DialectPostgres)
+	}
+	// The SQLite single-connection rule must not have followed us here.
+	if got := handle.Stats().MaxOpenConnections; got != 10 {
+		t.Errorf("MaxOpenConnections = %d; want 10", got)
+	}
+	if err := handle.Ping(); err != nil {
+		t.Fatalf("Ping: %v", err)
+	}
+}
+
+func TestPostgres_migrateToTargetVersion(t *testing.T) {
+	handle := openTestPostgres(t)
+	ctx := context.Background()
+
+	// Before migrating, the goose bookkeeping table is absent → not ready.
+	if ready, _ := db.SchemaReady(ctx, handle.DB); ready {
+		t.Error("SchemaReady = true before migrations ran; want false")
+	}
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	target, err := db.TargetVersion()
+	if err != nil {
+		t.Fatalf("TargetVersion: %v", err)
+	}
+	applied, err := db.AppliedVersion(ctx, handle.DB)
+	if err != nil {
+		t.Fatalf("AppliedVersion: %v", err)
+	}
+	if applied != target {
+		t.Errorf("applied version = %d; want target %d", applied, target)
+	}
+	if target != 57 {
+		t.Errorf("target version = %d; want 57 (sanity check against the known migration set)", target)
+	}
+
+	ready, err := db.SchemaReady(ctx, handle.DB)
+	if err != nil {
+		t.Fatalf("SchemaReady after migrate: %v", err)
+	}
+	if !ready {
+		t.Error("SchemaReady = false after migrations ran; want true")
+	}
+}
+
+func TestPostgres_migrateIdempotent(t *testing.T) {
+	handle := openTestPostgres(t)
+
+	for range 2 {
+		if err := handle.Migrate(); err != nil {
+			t.Fatalf("Migrate: %v", err)
+		}
+	}
+}
+
+// TestPostgres_migrateViaPackageFunc covers the compatibility path: Migrate on a
+// bare *sql.DB has to recover the dialect from the driver, and getting that wrong
+// would run the SQLite migrations against Postgres.
+func TestPostgres_migrateViaPackageFunc(t *testing.T) {
+	handle := openTestPostgres(t)
+
+	if err := db.Migrate(handle.DB); err != nil {
+		t.Fatalf("db.Migrate: %v", err)
+	}
+
+	applied, err := db.AppliedVersion(context.Background(), handle.DB)
+	if err != nil {
+		t.Fatalf("AppliedVersion: %v", err)
+	}
+	if applied != 57 {
+		t.Errorf("applied version = %d; want 57", applied)
+	}
+}
+
+func TestPostgres_tablesExist(t *testing.T) {
+	handle := openTestPostgres(t)
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	tables := []string{
+		"users", "api_keys", "teams", "team_members",
+		"event_types", "event_type_questions",
+		"availability_rules", "availability_overrides",
+		"calendar_connections",
+		"bookings", "booking_attendees", "booking_answers",
+		"webhooks", "webhook_deliveries",
+		"jobs",
+		// Tables added by later migrations, so this also proves the whole set ran.
+		"server_settings", "crypto_keystore", "event_type_hosts", "booking_hosts",
+		"idempotency_keys", "oauth_access_tokens", "zoom_connections",
+		"magic_link_tokens", "recordings", "meeting_consents", "transcripts",
+		"notes", "connection_calendars",
+	}
+
+	for _, table := range tables {
+		var name string
+		err := handle.QueryRow(
+			`SELECT table_name FROM information_schema.tables
+			 WHERE table_schema = current_schema() AND table_name = ?`, table,
+		).Scan(&name)
+		if err != nil {
+			t.Errorf("table %q not found after migration: %v", table, err)
+		}
+	}
+}
+
+// TestPostgres_doubleBookingIndex checks the partial unique index carried over as
+// a partial index. Without the WHERE clause it would block a re-book of a
+// cancelled slot, which is the behaviour the SQLite index deliberately avoids.
+func TestPostgres_doubleBookingIndex(t *testing.T) {
+	handle := openTestPostgres(t)
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	var indexdef string
+	err := handle.QueryRow(
+		`SELECT indexdef FROM pg_indexes
+		 WHERE schemaname = current_schema() AND indexname = 'idx_bookings_no_double'`,
+	).Scan(&indexdef)
+	if err != nil {
+		t.Fatalf("double-booking guard index not found: %v", err)
+	}
+
+	for _, want := range []string{"UNIQUE", "host_id", "start_at", "WHERE"} {
+		if !regexp.MustCompile(want).MatchString(indexdef) {
+			t.Errorf("index definition %q is missing %q", indexdef, want)
+		}
+	}
+}
+
+// TestPostgres_flagColumnsStayIntegers is the load-bearing type check: the 0/1
+// flag columns are read into Go ints all over the codebase, so a translation that
+// turned them into BOOLEAN would break every one of those scans.
+func TestPostgres_flagColumnsStayIntegers(t *testing.T) {
+	handle := openTestPostgres(t)
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	flags := []struct{ table, column string }{
+		{"users", "is_admin"},
+		{"users", "is_owner"},
+		{"users", "email_login"},
+		{"users", "notify_confirmation"},
+		{"event_types", "is_active"},
+		{"event_types", "is_public"},
+		{"event_types", "show_taken_slots"},
+		{"event_type_questions", "required"},
+		{"availability_overrides", "is_available"},
+		{"calendar_connections", "check_conflicts"},
+		{"calendar_connections", "is_destination"},
+		{"connection_calendars", "check_conflicts"},
+		{"booking_attendees", "is_organizer"},
+		{"booking_hosts", "is_primary"},
+		{"booking_hosts", "needs_sync"},
+		{"server_settings", "smtp_tls"},
+		{"server_settings", "smtp_starttls"},
+		{"server_settings", "llm_enabled"},
+		{"server_settings", "recordings_enabled"},
+		{"server_settings", "notetaker_enabled"},
+	}
+
+	for _, f := range flags {
+		var dataType string
+		err := handle.QueryRow(
+			`SELECT data_type FROM information_schema.columns
+			 WHERE table_schema = current_schema() AND table_name = ? AND column_name = ?`,
+			f.table, f.column,
+		).Scan(&dataType)
+		if err != nil {
+			t.Errorf("%s.%s: %v", f.table, f.column, err)
+			continue
+		}
+		if dataType != "smallint" && dataType != "integer" {
+			t.Errorf("%s.%s is %q; want an integer type (763 call sites scan these into Go ints)",
+				f.table, f.column, dataType)
+		}
+	}
+
+	// Prove the scan, not just the catalogue: server_settings is seeded by 00011.
+	var smtpTLS, smtpStartTLS int
+	if err := handle.QueryRow(
+		`SELECT smtp_tls, smtp_starttls FROM server_settings WHERE id = ?`, 1,
+	).Scan(&smtpTLS, &smtpStartTLS); err != nil {
+		t.Fatalf("scan flag columns into int: %v", err)
+	}
+	if smtpTLS != 0 || smtpStartTLS != 1 {
+		t.Errorf("seeded flags = (%d, %d); want (0, 1)", smtpTLS, smtpStartTLS)
+	}
+}
+
+// TestPostgres_timestampDefaultsMatchSQLite pins the format of the defaulted
+// timestamp columns. They stay TEXT holding the same strings SQLite writes,
+// because every time column in this schema is compared and sorted as a string.
+func TestPostgres_timestampDefaultsMatchSQLite(t *testing.T) {
+	handle := openTestPostgres(t)
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	// users.created_at defaults to SQLite's strftime('%Y-%m-%dT%H:%M:%fZ','now').
+	if _, err := handle.Exec(
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		"u1", "a@example.com", "A"); err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	var createdAt string
+	if err := handle.QueryRow(`SELECT created_at FROM users WHERE id = ?`, "u1").Scan(&createdAt); err != nil {
+		t.Fatalf("read created_at: %v", err)
+	}
+	const isoMillis = `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$`
+	if !regexp.MustCompile(isoMillis).MatchString(createdAt) {
+		t.Errorf("users.created_at = %q; want SQLite's %s form", createdAt, isoMillis)
+	}
+
+	// server_settings.updated_at defaults to SQLite's datetime('now').
+	var updatedAt string
+	if err := handle.QueryRow(`SELECT updated_at FROM server_settings WHERE id = ?`, 1).Scan(&updatedAt); err != nil {
+		t.Fatalf("read updated_at: %v", err)
+	}
+	const secondsUTC = `^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$`
+	if !regexp.MustCompile(secondsUTC).MatchString(updatedAt) {
+		t.Errorf("server_settings.updated_at = %q; want SQLite's %s form", updatedAt, secondsUTC)
+	}
+}
+
+// TestPostgres_identityPrimaryKey covers the one column that relied on SQLite's
+// rowid: keyvault.go inserts a keystore entry without an id.
+func TestPostgres_identityPrimaryKey(t *testing.T) {
+	handle := openTestPostgres(t)
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	if _, err := handle.Exec(`
+		INSERT INTO crypto_keystore
+		  (label, wrapped_dek, kdf, kdf_salt, kdf_params, dek_version, created_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, 1, ?, ?)`,
+		"primary", []byte("wrapped"), "argon2id", []byte("salt"), `{"m":65536,"t":3,"p":2}`,
+		"2026-01-01T00:00:00.000Z", "2026-01-01T00:00:00.000Z"); err != nil {
+		t.Fatalf("insert keystore entry without an id: %v", err)
+	}
+
+	var id int64
+	var wrapped []byte
+	if err := handle.QueryRow(
+		`SELECT id, wrapped_dek FROM crypto_keystore WHERE label = ?`, "primary",
+	).Scan(&id, &wrapped); err != nil {
+		t.Fatalf("read keystore entry: %v", err)
+	}
+	if id == 0 {
+		t.Error("id was not assigned; the identity column is missing")
+	}
+	if string(wrapped) != "wrapped" {
+		t.Errorf("wrapped_dek = %q; want %q (BYTEA round trip)", wrapped, "wrapped")
+	}
+}
+
+// TestPostgres_wrapperRebinds is the end-to-end proof that the wrapper is what
+// makes ?-placeholder SQL work here: the same statement through the bare handle
+// must fail.
+func TestPostgres_wrapperRebinds(t *testing.T) {
+	handle := openTestPostgres(t)
+	ctx := context.Background()
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	if _, err := handle.ExecContext(ctx,
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		"u1", "a@example.com", "A"); err != nil {
+		t.Fatalf("ExecContext through the wrapper: %v", err)
+	}
+
+	if _, err := handle.DB.ExecContext(ctx,
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		"u2", "b@example.com", "B"); err == nil {
+		t.Error("? placeholders succeeded on the bare *sql.DB; the rebinding test proves nothing")
+	}
+
+	var name string
+	if err := handle.QueryRowContext(ctx,
+		`SELECT name FROM users WHERE email = ? AND is_admin = ?`, "a@example.com", 0).Scan(&name); err != nil {
+		t.Fatalf("QueryRowContext: %v", err)
+	}
+	if name != "A" {
+		t.Errorf("name = %q; want %q", name, "A")
+	}
+
+	rows, err := handle.QueryContext(ctx, `SELECT id FROM users WHERE email = ?`, "a@example.com")
+	if err != nil {
+		t.Fatalf("QueryContext: %v", err)
+	}
+	count := 0
+	for rows.Next() {
+		count++
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("rows.Err: %v", err)
+	}
+	rows.Close()
+	if count != 1 {
+		t.Errorf("rows returned = %d; want 1", count)
+	}
+
+	tx, err := handle.BeginTx(ctx, nil)
+	if err != nil {
+		t.Fatalf("BeginTx: %v", err)
+	}
+	if _, err := tx.ExecContext(ctx, `UPDATE users SET name = ? WHERE id = ?`, "B", "u1"); err != nil {
+		tx.Rollback()
+		t.Fatalf("tx.ExecContext: %v", err)
+	}
+	if err := tx.QueryRowContext(ctx, `SELECT name FROM users WHERE id = ?`, "u1").Scan(&name); err != nil {
+		tx.Rollback()
+		t.Fatalf("tx.QueryRowContext: %v", err)
+	}
+	if err := tx.Commit(); err != nil {
+		t.Fatalf("tx.Commit: %v", err)
+	}
+	if name != "B" {
+		t.Errorf("name after tx update = %q; want %q", name, "B")
+	}
+
+	stmt, err := handle.PrepareContext(ctx, `SELECT COUNT(*) FROM users WHERE email = ?`)
+	if err != nil {
+		t.Fatalf("PrepareContext: %v", err)
+	}
+	defer stmt.Close()
+	var n int
+	if err := stmt.QueryRowContext(ctx, "a@example.com").Scan(&n); err != nil {
+		t.Fatalf("stmt.QueryRowContext: %v", err)
+	}
+	if n != 1 {
+		t.Errorf("count = %d; want 1", n)
+	}
+}
+
+// TestPostgres_partialUniqueIndexEnforced exercises the double-booking guard
+// itself rather than its definition: the index is the only thing standing between
+// two concurrent bookings and a double-booked host now that Postgres has a
+// connection pool (see openPostgres).
+func TestPostgres_partialUniqueIndexEnforced(t *testing.T) {
+	handle := openTestPostgres(t)
+	ctx := context.Background()
+
+	if err := handle.Migrate(); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+
+	seed := []struct {
+		query string
+		args  []any
+	}{
+		{`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`, []any{"h1", "h@example.com", "Host"}},
+		{`INSERT INTO event_types (id, user_id, slug, name, duration_minutes) VALUES (?, ?, ?, ?, ?)`,
+			[]any{"e1", "h1", "intro", "Intro", 30}},
+		{`INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at) VALUES (?, ?, ?, ?, ?)`,
+			[]any{"b1", "e1", "h1", "2026-01-01T10:00:00.000Z", "2026-01-01T10:30:00.000Z"}},
+	}
+	for _, s := range seed {
+		if _, err := handle.ExecContext(ctx, s.query, s.args...); err != nil {
+			t.Fatalf("seed %q: %v", s.query, err)
+		}
+	}
+
+	// Same host, same start: refused.
+	if _, err := handle.ExecContext(ctx,
+		`INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at) VALUES (?, ?, ?, ?, ?)`,
+		"b2", "e1", "h1", "2026-01-01T10:00:00.000Z", "2026-01-01T10:30:00.000Z"); err == nil {
+		t.Error("second booking at the same start time was accepted; the guard index is not enforcing")
+	}
+
+	// Cancelling the first frees the slot — the point of the WHERE clause.
+	if _, err := handle.ExecContext(ctx,
+		`UPDATE bookings SET status = 'cancelled' WHERE id = ?`, "b1"); err != nil {
+		t.Fatalf("cancel booking: %v", err)
+	}
+	if _, err := handle.ExecContext(ctx,
+		`INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at) VALUES (?, ?, ?, ?, ?)`,
+		"b3", "e1", "h1", "2026-01-01T10:00:00.000Z", "2026-01-01T10:30:00.000Z"); err != nil {
+		t.Errorf("re-booking a cancelled slot was refused: %v", err)
+	}
+}

From 65099c3e196bcb857f060cb74c5e34e402409aca Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 03:25:31 -0400
Subject: [PATCH 03/51] db: compare the migrated schemas across both engines

Every other cross-engine test asserts that one specific thing survived the
translation. This one asserts that nothing else changed: it migrates SQLite and
Postgres to 57 in the same process and compares the table list and each table's
column names, so a column quietly dropped, renamed or added in one set fails here
rather than in whichever handler reads it.

Names only, deliberately. TEXT versus text and SMALLINT versus integer are the
translation doing its job, and the types that do matter are already pinned by
TestPostgres_flagColumnsStayIntegers. The table-count floor is there because an
empty map on either side would satisfy every comparison in the test.
---
 internal/db/postgres_test.go | 125 +++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)

diff --git a/internal/db/postgres_test.go b/internal/db/postgres_test.go
index f28e15a..e3b43a1 100644
--- a/internal/db/postgres_test.go
+++ b/internal/db/postgres_test.go
@@ -3,10 +3,12 @@ package db_test
 import (
 	"context"
 	"crypto/rand"
+	"database/sql"
 	"encoding/hex"
 	"net/url"
 	"os"
 	"regexp"
+	"slices"
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
@@ -489,3 +491,126 @@ func TestPostgres_partialUniqueIndexEnforced(t *testing.T) {
 		t.Errorf("re-booking a cancelled slot was refused: %v", err)
 	}
 }
+
+// TestPostgres_schemaMatchesSQLite migrates both engines and compares the result,
+// table by table and column by column. It is the check the translation actually
+// needs: every other test here says a specific thing survived, and this one says
+// nothing was quietly dropped, renamed or added along the way.
+//
+// Names only, not types: TEXT versus text and SMALLINT versus integer are the
+// translation working as intended, and the types that do matter are pinned by
+// TestPostgres_flagColumnsStayIntegers.
+func TestPostgres_schemaMatchesSQLite(t *testing.T) {
+	postgres := openTestPostgres(t)
+	if err := postgres.Migrate(); err != nil {
+		t.Fatalf("Migrate(postgres): %v", err)
+	}
+
+	sqlite, err := db.OpenDB("sqlite://:memory:")
+	if err != nil {
+		t.Fatalf("db.OpenDB(sqlite): %v", err)
+	}
+	defer sqlite.Close()
+	if err := sqlite.Migrate(); err != nil {
+		t.Fatalf("Migrate(sqlite): %v", err)
+	}
+
+	sqliteSchema := sqliteColumns(t, sqlite)
+	postgresSchema := postgresColumns(t, postgres)
+
+	// Guard against a vacuous pass: an empty map on either side would satisfy
+	// every comparison below.
+	if len(sqliteSchema) < 30 {
+		t.Fatalf("only %d tables found on SQLite; the comparison would prove nothing", len(sqliteSchema))
+	}
+
+	for table, want := range sqliteSchema {
+		got, ok := postgresSchema[table]
+		if !ok {
+			t.Errorf("table %q exists on SQLite and not on Postgres", table)
+			continue
+		}
+		if !slices.Equal(want, got) {
+			t.Errorf("table %q columns differ\n sqlite: %v\n  pgsql: %v", table, want, got)
+		}
+	}
+	for table := range postgresSchema {
+		if _, ok := sqliteSchema[table]; !ok {
+			t.Errorf("table %q exists on Postgres and not on SQLite", table)
+		}
+	}
+}
+
+// sqliteColumns maps table name to sorted column names, skipping SQLite's own
+// bookkeeping tables (sqlite_sequence appears because goose's version table uses
+// AUTOINCREMENT).
+func sqliteColumns(t *testing.T, handle *db.DB) map[string][]string {
+	t.Helper()
+
+	rows, err := handle.Query(
+		`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`)
+	if err != nil {
+		t.Fatalf("list sqlite tables: %v", err)
+	}
+	tables := scanStrings(t, rows)
+
+	schema := make(map[string][]string, len(tables))
+	for _, table := range tables {
+		// PRAGMA table_info takes no placeholder; the name comes from
+		// sqlite_master, not from input.
+		rows, err := handle.Query(`SELECT name FROM pragma_table_info('` + table + `')`)
+		if err != nil {
+			t.Fatalf("columns of %q: %v", table, err)
+		}
+		cols := scanStrings(t, rows)
+		slices.Sort(cols)
+		schema[table] = cols
+	}
+	return schema
+}
+
+// postgresColumns maps table name to sorted column names for the test schema.
+func postgresColumns(t *testing.T, handle *db.DB) map[string][]string {
+	t.Helper()
+
+	rows, err := handle.Query(
+		`SELECT table_name FROM information_schema.tables
+		 WHERE table_schema = current_schema() AND table_type = 'BASE TABLE'
+		 ORDER BY table_name`)
+	if err != nil {
+		t.Fatalf("list postgres tables: %v", err)
+	}
+	tables := scanStrings(t, rows)
+
+	schema := make(map[string][]string, len(tables))
+	for _, table := range tables {
+		rows, err := handle.Query(
+			`SELECT column_name FROM information_schema.columns
+			 WHERE table_schema = current_schema() AND table_name = ?`, table)
+		if err != nil {
+			t.Fatalf("columns of %q: %v", table, err)
+		}
+		cols := scanStrings(t, rows)
+		slices.Sort(cols)
+		schema[table] = cols
+	}
+	return schema
+}
+
+func scanStrings(t *testing.T, rows *sql.Rows) []string {
+	t.Helper()
+	defer rows.Close()
+
+	var out []string
+	for rows.Next() {
+		var s string
+		if err := rows.Scan(&s); err != nil {
+			t.Fatalf("scan: %v", err)
+		}
+		out = append(out, s)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("rows.Err: %v", err)
+	}
+	return out
+}

From dfd7bd734cd7a3786ba108c253c131be59276b49 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 03:23:11 -0400
Subject: [PATCH 04/51] db: thread *db.DB / *db.Tx through every call site

The dialect-aware wrapper rebinds ? to $n on Postgres and is a no-op on SQLite,
so the only way the rest of Calnode benefits is to hold the wrapper rather than
the bare *sql.DB. Method names match database/sql, so this is a type change at
the declarations and almost nothing at the 763 call sites.

Three places did need a decision rather than a substitution:

  - internal/connstore.Execer is an interface over QueryRowContext, so both the
    wrapper and a bare *sql.DB satisfy it; only its doc comment changed.
    destination_test.go opens the sqlite driver directly against a bespoke
    fragment schema, and stays on *sql.DB for that reason.

  - handler.Readyz passes h.db.DB to db.SchemaReady, which takes a bare pool.
    Safe: that statement has no placeholders, so there is nothing to rebind.

  - cmd/calnode moved from db.Open + db.Migrate(database) to db.OpenDB and the
    handle's own Migrate method, which is what carries the dialect.

SQLite behaviour is unchanged: Rebind returns its input untouched there.
---
 PROGRESS.md                                   | 35 +++++++++++++++++++
 cmd/calnode/main.go                           |  4 +--
 cmd/calnode/mcp.go                            |  4 +--
 cmd/calnode/recover_key.go                    |  2 +-
 cmd/calnode/reset_admin.go                    |  2 +-
 cmd/calnode/rotate_key.go                     |  2 +-
 internal/booking/service.go                   | 11 +++---
 internal/booking/service_test.go              | 11 +++---
 internal/caldav/caldav.go                     |  5 +--
 internal/caldav/caldav_test.go                | 13 ++++---
 internal/calendar/calendar.go                 |  5 +--
 internal/calendar/calendar_test.go            |  8 ++---
 internal/calendar/conflicts.go                |  5 +--
 internal/calendar/connid_staleness_test.go    | 10 +++---
 internal/calendar/microsoft/microsoft.go      |  5 +--
 internal/calendar/microsoft/microsoft_test.go |  9 +++--
 internal/connstore/connstore.go               |  2 +-
 internal/connstore/connstore_test.go          | 11 +++---
 internal/demo/demo.go                         |  8 ++---
 internal/demo/demo_test.go                    |  9 +++--
 internal/gcal/gcal.go                         |  5 +--
 internal/gcal/gcal_test.go                    | 11 +++---
 internal/handler/auth_google_test.go          |  9 +++--
 internal/handler/booking_filter_test.go       |  4 +--
 internal/handler/calendar_test.go             |  4 +--
 internal/handler/checkbox_answer_test.go      |  4 +--
 internal/handler/email_settings.go            |  5 +--
 internal/handler/google_settings.go           |  3 +-
 internal/handler/google_settings_test.go      |  4 +--
 internal/handler/handler.go                   |  6 ++--
 internal/handler/health.go                    |  5 ++-
 internal/handler/health_test.go               |  8 ++---
 internal/handler/livekit_settings.go          |  3 +-
 internal/handler/llm_settings.go              |  3 +-
 internal/handler/manage_test.go               | 13 ++++---
 internal/handler/mcp_scope_test.go            |  4 +--
 internal/handler/slots_busy_test.go           |  8 ++---
 .../handler/stripe_locale_internal_test.go    |  4 +--
 internal/handler/stripe_settings.go           |  3 +-
 internal/handler/zoom_settings.go             |  3 +-
 internal/keyvault/keyvault.go                 | 17 ++++-----
 internal/keyvault/keyvault_test.go            |  7 ++--
 internal/server/server.go                     |  8 ++---
 internal/webhook/webhook.go                   |  5 +--
 internal/webhook/webhook_test.go              | 15 ++++----
 internal/worker/delivery_retention_test.go    |  7 ++--
 internal/worker/worker.go                     |  5 +--
 internal/worker/worker_test.go                |  9 +++--
 internal/zoom/zoom.go                         |  5 +--
 internal/zoom/zoom_test.go                    | 11 +++---
 50 files changed, 201 insertions(+), 158 deletions(-)
 create mode 100644 PROGRESS.md

diff --git a/PROGRESS.md b/PROGRESS.md
new file mode 100644
index 0000000..8bbca8d
--- /dev/null
+++ b/PROGRESS.md
@@ -0,0 +1,35 @@
+# PROGRESS — Postgres call sites (`feat/postgres-callsites`)
+
+Converting Calnode's call sites onto the dialect-aware `*db.DB` / `*db.Tx` wrapper
+(`internal/db`, built on the branch's base commit) so the app runs on PostgreSQL as
+well as SQLite. SQLite behaviour must not change.
+
+## Boundary 1 — thread the type through — DONE
+
+Every struct field, constructor, package-level helper and test helper that held
+`*sql.DB` now holds `*db.DB`; `*sql.Tx` became `*db.Tx`. Call sites needed no edit:
+the wrapper's method names match `database/sql`'s.
+
+- `db.Open` → `db.OpenDB` and `db.Migrate(x)` → `x.Migrate()` in `cmd/calnode/*` and
+  every test helper.
+- `internal/connstore`: `Execer` is an interface, so it needed no change; its doc
+  comment now names `*db.DB` / `*db.Tx`. `destination_test.go` deliberately opens a
+  bare `sql.Open("sqlite", ":memory:")` against a bespoke fragment schema and stays
+  `*sql.DB` — `Execer` accepts it.
+- `internal/handler/health.go` passes `h.db.DB` to `db.SchemaReady`, which takes a
+  bare `*sql.DB`. Legitimate: its one statement carries no placeholders.
+
+Gates: `go build ./...`, `go vet ./...`, `gofmt -l`, `go test ./...` all clean on SQLite.
+
+## Boundary 2 — non-portable SQL — TODO
+
+## Boundary 3 — advisory lock replacing the single-writer guarantee — TODO
+
+## Boundary 4 — Postgres test harness, docs, CI — TODO
+
+## Blocked on the database layer
+
+`internal/db/migrations/postgres` does not exist yet (`db.go` embeds
+`migrations/sqlite/*.sql` only), so nothing can migrate on Postgres and no
+Postgres-side run can be verified from this branch yet. The harness added in
+Boundary 4 calls `h.Migrate()` and starts working the moment those land.
diff --git a/cmd/calnode/main.go b/cmd/calnode/main.go
index 29a38aa..7f94db3 100644
--- a/cmd/calnode/main.go
+++ b/cmd/calnode/main.go
@@ -59,14 +59,14 @@ func main() {
 		slog.Warn("Google OAuth NOT configured — GOOGLE_CLIENT_ID is empty")
 	}
 
-	database, err := db.Open(cfg.DatabaseURL)
+	database, err := db.OpenDB(cfg.DatabaseURL)
 	if err != nil {
 		logger.Error("failed to open database", "error", err)
 		os.Exit(1)
 	}
 	defer database.Close()
 
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		logger.Error("failed to run migrations", "error", err)
 		os.Exit(1)
 	}
diff --git a/cmd/calnode/mcp.go b/cmd/calnode/mcp.go
index aa6984d..9eca8a2 100644
--- a/cmd/calnode/mcp.go
+++ b/cmd/calnode/mcp.go
@@ -30,14 +30,14 @@ func runMCPStdio(_ []string) {
 	logger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: cfg.LogLevel}))
 	slog.SetDefault(logger)
 
-	database, err := db.Open(cfg.DatabaseURL)
+	database, err := db.OpenDB(cfg.DatabaseURL)
 	if err != nil {
 		logger.Error("mcp: failed to open database", "error", err)
 		os.Exit(1)
 	}
 	defer database.Close()
 
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		logger.Error("mcp: failed to run migrations", "error", err)
 		os.Exit(1)
 	}
diff --git a/cmd/calnode/recover_key.go b/cmd/calnode/recover_key.go
index ebd285f..a7acf51 100644
--- a/cmd/calnode/recover_key.go
+++ b/cmd/calnode/recover_key.go
@@ -36,7 +36,7 @@ func runRecoverKey(args []string) {
 		dbURL = "sqlite://./data/calnode.db"
 	}
 
-	database, err := db.Open(dbURL)
+	database, err := db.OpenDB(dbURL)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "error: open database: %v\n", err)
 		os.Exit(1)
diff --git a/cmd/calnode/reset_admin.go b/cmd/calnode/reset_admin.go
index 03495b4..4f2a2a7 100644
--- a/cmd/calnode/reset_admin.go
+++ b/cmd/calnode/reset_admin.go
@@ -33,7 +33,7 @@ func runResetAdmin(args []string) {
 
 	cfg := config.Load()
 
-	database, err := db.Open(cfg.DatabaseURL)
+	database, err := db.OpenDB(cfg.DatabaseURL)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "error: failed to open database: %v\n", err)
 		os.Exit(1)
diff --git a/cmd/calnode/rotate_key.go b/cmd/calnode/rotate_key.go
index f1d1085..000fb9c 100644
--- a/cmd/calnode/rotate_key.go
+++ b/cmd/calnode/rotate_key.go
@@ -37,7 +37,7 @@ func runRotateKey(args []string) {
 		dbURL = "sqlite://./data/calnode.db"
 	}
 
-	database, err := db.Open(dbURL)
+	database, err := db.OpenDB(dbURL)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "error: open database: %v\n", err)
 		os.Exit(1)
diff --git a/internal/booking/service.go b/internal/booking/service.go
index da604f9..2f4b3ad 100644
--- a/internal/booking/service.go
+++ b/internal/booking/service.go
@@ -13,16 +13,17 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/uid"
 )
 
 // Service handles booking creation and lifecycle.
 type Service struct {
-	db *sql.DB
+	db *db.DB
 }
 
 // New returns a Service backed by db.
-func New(db *sql.DB) *Service {
+func New(db *db.DB) *Service {
 	return &Service{db: db}
 }
 
@@ -279,7 +280,7 @@ const bookingColumns = `id, event_type_id, host_id, start_at, end_at, status,
 // than matching bookings.host_id (which would miss a Group/fixed-host attendee).
 // excludeBookingID excludes the booking being modified from its own overlap check
 // (Reschedule/ReassignHost); pass "" when there's no booking yet to exclude (Create).
-func hostBusy(ctx context.Context, tx *sql.Tx, hostID, start, end, excludeBookingID string) (bool, error) {
+func hostBusy(ctx context.Context, tx *db.Tx, hostID, start, end, excludeBookingID string) (bool, error) {
 	var n int
 	err := tx.QueryRowContext(ctx, `
 		SELECT COUNT(*) FROM bookings b
@@ -377,7 +378,7 @@ func (s *Service) ValidateManageToken(ctx context.Context, rawToken string) (*Bo
 // be in priority order (lowest priority number first). "priority" takes the first
 // free host; "even" (and "soonest", which has no meaning once the slot is fixed)
 // take the least-loaded one.
-func pickRotationHost(ctx context.Context, tx *sql.Tx, eventTypeID, strategy string, free []string, now string) (string, error) {
+func pickRotationHost(ctx context.Context, tx *db.Tx, eventTypeID, strategy string, free []string, now string) (string, error) {
 	if strategy == "priority" {
 		return free[0], nil
 	}
@@ -387,7 +388,7 @@ func pickRotationHost(ctx context.Context, tx *sql.Tx, eventTypeID, strategy str
 // leastLoadedHost returns the candidate with the fewest upcoming (non-cancelled,
 // not-yet-ended) bookings for this event type — even-distribution round-robin.
 // Ties are broken by the order of candidates (caller passes them in priority order).
-func leastLoadedHost(ctx context.Context, tx *sql.Tx, eventTypeID string, candidates []string, now string) (string, error) {
+func leastLoadedHost(ctx context.Context, tx *db.Tx, eventTypeID string, candidates []string, now string) (string, error) {
 	ph := make([]string, len(candidates))
 	args := make([]any, 0, len(candidates)+2)
 	args = append(args, eventTypeID, now)
diff --git a/internal/booking/service_test.go b/internal/booking/service_test.go
index 9f656a0..5cc1e5c 100644
--- a/internal/booking/service_test.go
+++ b/internal/booking/service_test.go
@@ -2,7 +2,6 @@ package booking_test
 
 import (
 	"context"
-	"database/sql"
 	"testing"
 	"time"
 
@@ -11,20 +10,20 @@ import (
 	"github.com/calnode/calnode/internal/uid"
 )
 
-func newTestDB(t *testing.T) *sql.DB {
+func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open test db: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate test db: %v", err)
 	}
 	return database
 }
 
-func seedHost(t *testing.T, database *sql.DB) string {
+func seedHost(t *testing.T, database *db.DB) string {
 	t.Helper()
 	id := uid.New()
 	_, err := database.ExecContext(context.Background(), `
@@ -37,7 +36,7 @@ func seedHost(t *testing.T, database *sql.DB) string {
 	return id
 }
 
-func seedEventType(t *testing.T, database *sql.DB, userID string) string {
+func seedEventType(t *testing.T, database *db.DB, userID string) string {
 	t.Helper()
 	id := uid.New()
 	_, err := database.ExecContext(context.Background(), `
diff --git a/internal/caldav/caldav.go b/internal/caldav/caldav.go
index cf143e7..d72635d 100644
--- a/internal/caldav/caldav.go
+++ b/internal/caldav/caldav.go
@@ -27,6 +27,7 @@ import (
 
 	"github.com/calnode/calnode/internal/calendar"
 	"github.com/calnode/calnode/internal/connstore"
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/netutil"
 	"github.com/calnode/calnode/internal/secret"
 	"github.com/calnode/calnode/internal/uid"
@@ -37,7 +38,7 @@ var _ calendar.Provider = (*Client)(nil)
 
 // Client manages CalDAV connections (encrypted app-password credentials) and access.
 type Client struct {
-	db     *sql.DB
+	db     *db.DB
 	key    [32]byte
 	logger *slog.Logger
 	hc     *http.Client
@@ -45,7 +46,7 @@ type Client struct {
 
 // New creates a Client. encKeyHex is the 64-char hex AES-256 encryption key (the same
 // instance key used to encrypt the other providers' tokens).
-func New(db *sql.DB, encKeyHex string) (*Client, error) {
+func New(db *db.DB, encKeyHex string) (*Client, error) {
 	b, err := hex.DecodeString(encKeyHex)
 	if err != nil || len(b) != 32 {
 		return nil, fmt.Errorf("caldav: invalid encryption key")
diff --git a/internal/caldav/caldav_test.go b/internal/caldav/caldav_test.go
index ab24ed7..89bba63 100644
--- a/internal/caldav/caldav_test.go
+++ b/internal/caldav/caldav_test.go
@@ -2,7 +2,6 @@ package caldav
 
 import (
 	"context"
-	"database/sql"
 	"io"
 	"net/http"
 	"net/http/httptest"
@@ -16,13 +15,13 @@ import (
 
 const testKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
 
-func newTestDB(t *testing.T) *sql.DB {
+func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -41,7 +40,7 @@ func newTestClient(t *testing.T) *Client {
 	return c
 }
 
-func seedUser(t *testing.T, database *sql.DB, userID string) {
+func seedUser(t *testing.T, database *db.DB, userID string) {
 	t.Helper()
 	_, err := database.ExecContext(context.Background(), `
 		INSERT INTO users (id, email, name, iana_timezone, is_admin, created_at)
@@ -267,7 +266,7 @@ func TestInvitesGuests_false(t *testing.T) {
 
 // ----- helpers -----
 
-func destEmail(t *testing.T, database *sql.DB, userID string) string {
+func destEmail(t *testing.T, database *db.DB, userID string) string {
 	t.Helper()
 	var e string
 	err := database.QueryRowContext(context.Background(),
@@ -278,7 +277,7 @@ func destEmail(t *testing.T, database *sql.DB, userID string) string {
 	return e
 }
 
-func countConns(t *testing.T, database *sql.DB, userID string) int {
+func countConns(t *testing.T, database *db.DB, userID string) int {
 	t.Helper()
 	var n int
 	if err := database.QueryRowContext(context.Background(),
diff --git a/internal/calendar/calendar.go b/internal/calendar/calendar.go
index afaade9..f8e6696 100644
--- a/internal/calendar/calendar.go
+++ b/internal/calendar/calendar.go
@@ -10,6 +10,7 @@ import (
 	"sort"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/slots"
 )
 
@@ -82,13 +83,13 @@ type Provider interface {
 // Service holds the configured providers and dispatches per-user operations to
 // whichever provider that user has connected.
 type Service struct {
-	db        *sql.DB
+	db        *db.DB
 	providers map[string]Provider
 	primary   string // default provider for new connections (first registered)
 }
 
 // NewService returns an empty Service. Register one provider per configured backend.
-func NewService(db *sql.DB) *Service {
+func NewService(db *db.DB) *Service {
 	return &Service{db: db, providers: map[string]Provider{}}
 }
 
diff --git a/internal/calendar/calendar_test.go b/internal/calendar/calendar_test.go
index 8f778e5..b9df253 100644
--- a/internal/calendar/calendar_test.go
+++ b/internal/calendar/calendar_test.go
@@ -8,12 +8,12 @@ import (
 )
 
 func TestCanAutoGenerate(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
 	defer database.Close()
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	ctx := context.Background()
@@ -66,12 +66,12 @@ func TestCanAutoGenerate(t *testing.T) {
 // TestConnectionManagement covers the multi-calendar Service helpers: listing connections,
 // switching the single destination, and promoting a survivor when the destination is removed.
 func TestConnectionManagement(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
 	defer database.Close()
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	ctx := context.Background()
diff --git a/internal/calendar/conflicts.go b/internal/calendar/conflicts.go
index 7da2998..946ece1 100644
--- a/internal/calendar/conflicts.go
+++ b/internal/calendar/conflicts.go
@@ -2,7 +2,8 @@ package calendar
 
 import (
 	"context"
-	"database/sql"
+
+	"github.com/calnode/calnode/internal/db"
 )
 
 // ConflictCalendarIDs resolves which calendar IDs of one connected account must be checked for
@@ -17,7 +18,7 @@ import (
 //
 // The caller must have no open rows cursor on the shared DB pool when calling this (the pool is
 // single-connection): drain and Close() any cursor first.
-func ConflictCalendarIDs(ctx context.Context, db *sql.DB, provider, userID, accountEmail, fallbackCalID string) ([]string, error) {
+func ConflictCalendarIDs(ctx context.Context, db *db.DB, provider, userID, accountEmail, fallbackCalID string) ([]string, error) {
 	rows, err := db.QueryContext(ctx,
 		`SELECT calendar_id, check_conflicts FROM connection_calendars
 		 WHERE user_id = ? AND provider = ? AND account_email = ?`,
diff --git a/internal/calendar/connid_staleness_test.go b/internal/calendar/connid_staleness_test.go
index 5264e20..9a40641 100644
--- a/internal/calendar/connid_staleness_test.go
+++ b/internal/calendar/connid_staleness_test.go
@@ -10,14 +10,14 @@ import (
 )
 
 // newTestDB opens a migrated in-memory DB with one user.
-func newTestDB(t *testing.T) *sql.DB {
+func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	if _, err := database.Exec(
@@ -28,7 +28,7 @@ func newTestDB(t *testing.T) *sql.DB {
 	return database
 }
 
-func seedConn(t *testing.T, database *sql.DB, id, userID, provider, email string, check, dest int) {
+func seedConn(t *testing.T, database *db.DB, id, userID, provider, email string, check, dest int) {
 	t.Helper()
 	if _, err := database.Exec(
 		`INSERT INTO calendar_connections
@@ -50,7 +50,7 @@ func seedConn(t *testing.T, database *sql.DB, id, userID, provider, email string
 
 // refreshToken reproduces what a provider does on token refresh: same account, brand new
 // row id.
-func refreshToken(t *testing.T, db *sql.DB, userID, provider, email, newID string) {
+func refreshToken(t *testing.T, db *db.DB, userID, provider, email, newID string) {
 	t.Helper()
 	var dest, check int
 	if err := db.QueryRow(
diff --git a/internal/calendar/microsoft/microsoft.go b/internal/calendar/microsoft/microsoft.go
index 6194e0a..8c1f0d3 100644
--- a/internal/calendar/microsoft/microsoft.go
+++ b/internal/calendar/microsoft/microsoft.go
@@ -27,6 +27,7 @@ import (
 
 	"github.com/calnode/calnode/internal/calendar"
 	"github.com/calnode/calnode/internal/connstore"
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/oauthstore"
 	"github.com/calnode/calnode/internal/secret"
 	"github.com/calnode/calnode/internal/uid"
@@ -41,14 +42,14 @@ var _ calendar.Provider = (*Client)(nil)
 type Client struct {
 	config  *oauth2.Config
 	key     [32]byte
-	db      *sql.DB
+	db      *db.DB
 	logger  *slog.Logger
 	apiBase string // base URL for Graph API; overridable in tests
 }
 
 // New creates a Client. tenant defaults to "common" (any Microsoft account).
 // encKeyHex is the 64-char hex AES-256 encryption key.
-func New(db *sql.DB, clientID, clientSecret, tenant, redirectURL, encKeyHex string) (*Client, error) {
+func New(db *db.DB, clientID, clientSecret, tenant, redirectURL, encKeyHex string) (*Client, error) {
 	b, err := hex.DecodeString(encKeyHex)
 	if err != nil || len(b) != 32 {
 		return nil, fmt.Errorf("microsoft: invalid encryption key")
diff --git a/internal/calendar/microsoft/microsoft_test.go b/internal/calendar/microsoft/microsoft_test.go
index 30088fa..919c149 100644
--- a/internal/calendar/microsoft/microsoft_test.go
+++ b/internal/calendar/microsoft/microsoft_test.go
@@ -2,7 +2,6 @@ package microsoft
 
 import (
 	"context"
-	"database/sql"
 	"encoding/base64"
 	"io"
 	"net/http"
@@ -19,13 +18,13 @@ import (
 
 const testKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
 
-func newTestDB(t *testing.T) *sql.DB {
+func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -41,7 +40,7 @@ func newTestClient(t *testing.T) *Client {
 	return c
 }
 
-func seedUser(t *testing.T, database *sql.DB, userID string) {
+func seedUser(t *testing.T, database *db.DB, userID string) {
 	t.Helper()
 	_, err := database.ExecContext(context.Background(), `
 		INSERT INTO users (id, email, name, iana_timezone, is_admin, created_at)
diff --git a/internal/connstore/connstore.go b/internal/connstore/connstore.go
index 1191e5d..e2e4b0e 100644
--- a/internal/connstore/connstore.go
+++ b/internal/connstore/connstore.go
@@ -13,7 +13,7 @@ import (
 	"fmt"
 )
 
-// Execer is satisfied by both *sql.DB and *sql.Tx — ResolveFlags runs inside whichever
+// Execer is satisfied by both *db.DB and *db.Tx — ResolveFlags runs inside whichever
 // transaction the caller already opened for its own upsert.
 type Execer interface {
 	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
diff --git a/internal/connstore/connstore_test.go b/internal/connstore/connstore_test.go
index fe6e3e5..d36be87 100644
--- a/internal/connstore/connstore_test.go
+++ b/internal/connstore/connstore_test.go
@@ -2,26 +2,25 @@ package connstore
 
 import (
 	"context"
-	"database/sql"
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
 )
 
-func newTestDB(t *testing.T) *sql.DB {
+func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("newTestDB: open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("newTestDB: migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
 	return database
 }
 
-func seedUser(t *testing.T, database *sql.DB, userID string) {
+func seedUser(t *testing.T, database *db.DB, userID string) {
 	t.Helper()
 	if _, err := database.ExecContext(context.Background(), `
 		INSERT INTO users (id, email, name, iana_timezone, is_admin, created_at)
@@ -31,7 +30,7 @@ func seedUser(t *testing.T, database *sql.DB, userID string) {
 	}
 }
 
-func seedConnection(t *testing.T, database *sql.DB, userID, provider, accountEmail string, checkConflicts, isDestination int) {
+func seedConnection(t *testing.T, database *db.DB, userID, provider, accountEmail string, checkConflicts, isDestination int) {
 	t.Helper()
 	if _, err := database.ExecContext(context.Background(), `
 		INSERT INTO calendar_connections
diff --git a/internal/demo/demo.go b/internal/demo/demo.go
index e37c6ef..a62c29e 100644
--- a/internal/demo/demo.go
+++ b/internal/demo/demo.go
@@ -7,10 +7,10 @@ package demo
 
 import (
 	"context"
-	"database/sql"
 	"fmt"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/uid"
 )
 
@@ -29,7 +29,7 @@ const (
 // Monday-Friday availability, and a few upcoming sample bookings. Rows are
 // inserted directly via SQL, bypassing the HTTP layer — the same pattern
 // already used by this package's handler test fixtures.
-func Seed(ctx context.Context, db *sql.DB) error {
+func Seed(ctx context.Context, db *db.DB) error {
 	tx, err := db.BeginTx(ctx, nil)
 	if err != nil {
 		return fmt.Errorf("demo seed: begin tx: %w", err)
@@ -181,7 +181,7 @@ func nextWeekdayAt(now time.Time, minDaysOut, hour int) time.Time {
 // dynamically rather than hardcoded, since this actively deletes data —
 // see docs/ARCHITECTURE.md's hardcoded-column-count incident for why a
 // stale hardcoded list is worth avoiding here specifically.
-func Reset(ctx context.Context, db *sql.DB) (err error) {
+func Reset(ctx context.Context, db *db.DB) (err error) {
 	tables, err := listTables(ctx, db)
 	if err != nil {
 		return err
@@ -219,7 +219,7 @@ func Reset(ctx context.Context, db *sql.DB) (err error) {
 	return Seed(ctx, db)
 }
 
-func listTables(ctx context.Context, db *sql.DB) ([]string, error) {
+func listTables(ctx context.Context, db *db.DB) ([]string, error) {
 	rows, err := db.QueryContext(ctx, `
 		SELECT name FROM sqlite_master
 		WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name != 'goose_db_version'`)
diff --git a/internal/demo/demo_test.go b/internal/demo/demo_test.go
index 183300c..ffd8d65 100644
--- a/internal/demo/demo_test.go
+++ b/internal/demo/demo_test.go
@@ -2,27 +2,26 @@ package demo_test
 
 import (
 	"context"
-	"database/sql"
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/demo"
 )
 
-func newMigratedDB(t *testing.T) *sql.DB {
+func newMigratedDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 	return database
 }
 
-func assertCount(t *testing.T, ctx context.Context, database *sql.DB, table string, want int) {
+func assertCount(t *testing.T, ctx context.Context, database *db.DB, table string, want int) {
 	t.Helper()
 	var got int
 	if err := database.QueryRowContext(ctx, `SELECT COUNT(*) FROM `+table).Scan(&got); err != nil {
diff --git a/internal/gcal/gcal.go b/internal/gcal/gcal.go
index 29b13e0..ed3e5eb 100644
--- a/internal/gcal/gcal.go
+++ b/internal/gcal/gcal.go
@@ -20,6 +20,7 @@ import (
 
 	"github.com/calnode/calnode/internal/calendar"
 	"github.com/calnode/calnode/internal/connstore"
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/oauthstore"
 	"github.com/calnode/calnode/internal/secret"
 	"github.com/calnode/calnode/internal/uid"
@@ -39,13 +40,13 @@ func (c *Client) InvitesGuests() bool { return true }
 type Client struct {
 	config  *oauth2.Config
 	key     [32]byte
-	db      *sql.DB
+	db      *db.DB
 	logger  *slog.Logger
 	apiBase string // base URL for Calendar API; overridable in tests
 }
 
 // New creates a Client. encKeyHex is the 64-char hex AES-256 encryption key.
-func New(db *sql.DB, clientID, clientSecret, redirectURL, encKeyHex string) (*Client, error) {
+func New(db *db.DB, clientID, clientSecret, redirectURL, encKeyHex string) (*Client, error) {
 	b, err := hex.DecodeString(encKeyHex)
 	if err != nil || len(b) != 32 {
 		return nil, fmt.Errorf("gcal: invalid encryption key")
diff --git a/internal/gcal/gcal_test.go b/internal/gcal/gcal_test.go
index e5c06d1..89a8926 100644
--- a/internal/gcal/gcal_test.go
+++ b/internal/gcal/gcal_test.go
@@ -2,7 +2,6 @@ package gcal
 
 import (
 	"context"
-	"database/sql"
 	"strings"
 	"testing"
 	"time"
@@ -15,13 +14,13 @@ import (
 // testKeyHex is a valid 64-char hex key (32 bytes) used across tests.
 const testKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
 
-func newTestDB(t *testing.T) *sql.DB {
+func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("newTestDB: open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("newTestDB: migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -38,7 +37,7 @@ func newTestClient(t *testing.T) *Client {
 }
 
 // seedUser inserts a minimal user row so that calendar_connections FK is satisfied.
-func seedUser(t *testing.T, db *sql.DB, userID string) {
+func seedUser(t *testing.T, db *db.DB, userID string) {
 	t.Helper()
 	_, err := db.ExecContext(context.Background(), `
 		INSERT INTO users (id, email, name, iana_timezone, is_admin, created_at)
@@ -314,7 +313,7 @@ func TestFreeBusyConnections_returnsConnectedCalendars(t *testing.T) {
 }
 
 // insertConnCal adds a per-account sub-calendar selection row for the google provider.
-func insertConnCal(t *testing.T, db *sql.DB, userID, account, calID string, check bool) {
+func insertConnCal(t *testing.T, db *db.DB, userID, account, calID string, check bool) {
 	t.Helper()
 	cc := 0
 	if check {
diff --git a/internal/handler/auth_google_test.go b/internal/handler/auth_google_test.go
index 79b9b5a..1f2a05a 100644
--- a/internal/handler/auth_google_test.go
+++ b/internal/handler/auth_google_test.go
@@ -2,7 +2,6 @@ package handler_test
 
 import (
 	"context"
-	"database/sql"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
@@ -15,13 +14,13 @@ import (
 
 // authTestSetup opens an in-memory DB, runs migrations, seeds one user, and
 // returns the handler, database handle, and the seeded user ID.
-func authTestSetup(t *testing.T) (*handler.Handler, *sql.DB, string) {
+func authTestSetup(t *testing.T) (*handler.Handler, *db.DB, string) {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -35,7 +34,7 @@ func authTestSetup(t *testing.T) (*handler.Handler, *sql.DB, string) {
 }
 
 // seedSession inserts a session row and returns the session id (cookie value).
-func seedSession(t *testing.T, db *sql.DB, userID string, ttl time.Duration) string {
+func seedSession(t *testing.T, db *db.DB, userID string, ttl time.Duration) string {
 	t.Helper()
 	sessID := "test-session-" + userID
 	expiresAt := time.Now().UTC().Add(ttl).Format(time.RFC3339)
diff --git a/internal/handler/booking_filter_test.go b/internal/handler/booking_filter_test.go
index 249adbb..40d1c99 100644
--- a/internal/handler/booking_filter_test.go
+++ b/internal/handler/booking_filter_test.go
@@ -1,13 +1,13 @@
 package handler_test
 
 import (
-	"database/sql"
 	"encoding/json"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/handler"
 )
 
@@ -53,7 +53,7 @@ func listIDs(r listResp) []string {
 }
 
 // seedBooking inserts one booking directly. start/end are RFC3339 UTC.
-func seedBooking(t *testing.T, db *sql.DB, id, etID, hostID, start, end, status string) {
+func seedBooking(t *testing.T, db *db.DB, id, etID, hostID, start, end, status string) {
 	t.Helper()
 	if _, err := db.Exec(
 		`INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at, status)
diff --git a/internal/handler/calendar_test.go b/internal/handler/calendar_test.go
index 5358ff2..6edfb09 100644
--- a/internal/handler/calendar_test.go
+++ b/internal/handler/calendar_test.go
@@ -21,11 +21,11 @@ const testGCalKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
 // Returns (handler, gcalClient, plainAPIKey, userID).
 func newHandlerWithGCal(t *testing.T) (*handler.Handler, *gcal.Client, string, string) {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
diff --git a/internal/handler/checkbox_answer_test.go b/internal/handler/checkbox_answer_test.go
index 335a66e..9e0714a 100644
--- a/internal/handler/checkbox_answer_test.go
+++ b/internal/handler/checkbox_answer_test.go
@@ -1,7 +1,6 @@
 package handler_test
 
 import (
-	"database/sql"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -9,6 +8,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/handler"
 )
 
@@ -118,7 +118,7 @@ func TestCheckboxAnswer_normalisedToYesNo(t *testing.T) {
 }
 
 // ownerIDOf returns the sole workspace user's id.
-func ownerIDOf(t *testing.T, database *sql.DB) string {
+func ownerIDOf(t *testing.T, database *db.DB) string {
 	t.Helper()
 	var id string
 	if err := database.QueryRow(`SELECT id FROM users ORDER BY created_at LIMIT 1`).Scan(&id); err != nil {
diff --git a/internal/handler/email_settings.go b/internal/handler/email_settings.go
index b8adc73..8285a27 100644
--- a/internal/handler/email_settings.go
+++ b/internal/handler/email_settings.go
@@ -10,6 +10,7 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/mailer"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -67,7 +68,7 @@ func BuildMailer(cfg SMTPConfig) (mailer.Mailer, EmailTransport) {
 // LoadEmailSettingsFromDB reads SMTP settings from server_settings and decrypts
 // the password. Returns nil (not an error) when smtp_host is empty — meaning
 // the settings have not been configured yet.
-func LoadEmailSettingsFromDB(db *sql.DB, encKey [32]byte) (*SMTPConfig, error) {
+func LoadEmailSettingsFromDB(db *db.DB, encKey [32]byte) (*SMTPConfig, error) {
 	var host, port, user, passEnc, from, fromName, resendEnc string
 	var smtpTLS, startTLS int
 	err := db.QueryRow(`
@@ -163,7 +164,7 @@ func (s emailSecret) String() string {
 	return "smtp_pass_enc"
 }
 
-// execer is the subset of *sql.DB / *sql.Tx the settings writes need, so they can be run
+// execer is the subset of *db.DB / *db.Tx the settings writes need, so they can be run
 // inside a transaction. Saving email settings touches up to three columns across separate
 // statements; without a transaction a failure partway leaves the instance holding, say, a
 // new SMTP host with the previous password.
diff --git a/internal/handler/google_settings.go b/internal/handler/google_settings.go
index 965aa5e..4a5fea2 100644
--- a/internal/handler/google_settings.go
+++ b/internal/handler/google_settings.go
@@ -8,6 +8,7 @@ import (
 	"net/http"
 
 	"github.com/calnode/calnode/internal/calendar"
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/gcal"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -21,7 +22,7 @@ type GoogleOAuthConfig struct {
 
 // LoadGoogleSettingsFromDB reads Google OAuth credentials from server_settings
 // and decrypts the client secret. Returns nil (not an error) when client_id is empty.
-func LoadGoogleSettingsFromDB(db *sql.DB, encKey [32]byte) (*GoogleOAuthConfig, error) {
+func LoadGoogleSettingsFromDB(db *db.DB, encKey [32]byte) (*GoogleOAuthConfig, error) {
 	var clientID, secretEnc string
 	err := db.QueryRow(`
 		SELECT google_client_id, google_client_secret_enc
diff --git a/internal/handler/google_settings_test.go b/internal/handler/google_settings_test.go
index 0b8554d..3d5ccdb 100644
--- a/internal/handler/google_settings_test.go
+++ b/internal/handler/google_settings_test.go
@@ -1,19 +1,19 @@
 package handler_test
 
 import (
-	"database/sql"
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/handler"
 )
 
 // newGoogleHandler sets up a handler with a valid enc key and returns it
 // alongside the DB and API key for an admin user.
-func newGoogleHandler(t *testing.T) (*handler.Handler, *sql.DB, string) {
+func newGoogleHandler(t *testing.T) (*handler.Handler, *db.DB, string) {
 	t.Helper()
 	h, database, apiKey, _ := setupWorkspaceWithDB(t)
 	// Use the same key as calendar tests so gcal.New works if needed.
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index 6adbb08..59b1809 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -1,7 +1,6 @@
 package handler
 
 import (
-	"database/sql"
 	"encoding/hex"
 	"log/slog"
 	"net/http"
@@ -12,6 +11,7 @@ import (
 
 	"github.com/calnode/calnode/internal/booking"
 	"github.com/calnode/calnode/internal/calendar"
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/livekit"
 	"github.com/calnode/calnode/internal/llm"
 	"github.com/calnode/calnode/internal/mailer"
@@ -21,7 +21,7 @@ import (
 )
 
 type Handler struct {
-	db                *sql.DB
+	db                *db.DB
 	logger            *slog.Logger
 	bookingSvc        *booking.Service
 	mailer            mailer.Mailer
@@ -121,7 +121,7 @@ func (h *Handler) getLLM() *llm.Client {
 	return h.llm
 }
 
-func New(db *sql.DB, logger *slog.Logger) *Handler {
+func New(db *db.DB, logger *slog.Logger) *Handler {
 	whs, _ := webhook.New(db, "") // ephemeral key when no encryption key configured
 	return &Handler{
 		db:         db,
diff --git a/internal/handler/health.go b/internal/handler/health.go
index 2d9d007..a36eb03 100644
--- a/internal/handler/health.go
+++ b/internal/handler/health.go
@@ -32,7 +32,10 @@ func (h *Handler) Readyz(w http.ResponseWriter, r *http.Request) {
 	// Gate readiness on migrations: report not-ready until the schema is at the
 	// embedded target version, so a provisioner polling /readyz never routes
 	// traffic to an instance still mid-migration (or one that failed to migrate).
-	ready, err := db.SchemaReady(r.Context(), h.db)
+	//
+	// SchemaReady takes the bare pool: its one statement carries no placeholders,
+	// so there is nothing for the wrapper to rebind.
+	ready, err := db.SchemaReady(r.Context(), h.db.DB)
 	if err != nil || !ready {
 		if err != nil {
 			h.logger.ErrorContext(r.Context(), "readyz: migration check failed", "error", err)
diff --git a/internal/handler/health_test.go b/internal/handler/health_test.go
index 08ae220..d042234 100644
--- a/internal/handler/health_test.go
+++ b/internal/handler/health_test.go
@@ -13,11 +13,11 @@ import (
 
 func newTestHandler(t *testing.T) *handler.Handler {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -76,7 +76,7 @@ func TestReadyz_returns200_whenDBHealthy(t *testing.T) {
 func TestReadyz_returns503_whenNotMigrated(t *testing.T) {
 	// Open a DB but do NOT migrate it — the goose bookkeeping table is absent,
 	// so the schema-readiness gate must report not-ready.
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
@@ -115,7 +115,7 @@ func TestVersion_returns200(t *testing.T) {
 }
 
 func TestReadyz_returns503_whenDBClosed(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
diff --git a/internal/handler/livekit_settings.go b/internal/handler/livekit_settings.go
index daf4965..3dbafb3 100644
--- a/internal/handler/livekit_settings.go
+++ b/internal/handler/livekit_settings.go
@@ -8,6 +8,7 @@ import (
 
 	"encoding/json"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/livekit"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -21,7 +22,7 @@ type LiveKitConfig struct {
 
 // LoadLiveKitSettingsFromDB reads the LiveKit server config from server_settings and decrypts
 // the API secret. Returns nil (not an error) when the URL or key is empty (= not configured).
-func LoadLiveKitSettingsFromDB(db *sql.DB, encKey [32]byte) (*LiveKitConfig, error) {
+func LoadLiveKitSettingsFromDB(db *db.DB, encKey [32]byte) (*LiveKitConfig, error) {
 	var url, apiKey, secretEnc string
 	err := db.QueryRow(`
 		SELECT livekit_url, livekit_api_key, livekit_api_secret_enc
diff --git a/internal/handler/llm_settings.go b/internal/handler/llm_settings.go
index c5019f9..967505a 100644
--- a/internal/handler/llm_settings.go
+++ b/internal/handler/llm_settings.go
@@ -9,6 +9,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/llm"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -34,7 +35,7 @@ type LLMConfig struct {
 
 // LoadLLMSettingsFromDB reads the optional LLM settings from server_settings and decrypts
 // the api key. Returns nil (not an error) when the endpoint is empty (unconfigured).
-func LoadLLMSettingsFromDB(db *sql.DB, encKey [32]byte) (*LLMConfig, error) {
+func LoadLLMSettingsFromDB(db *db.DB, encKey [32]byte) (*LLMConfig, error) {
 	var endpoint, model, keyEnc string
 	var enabled int
 	err := db.QueryRow(`
diff --git a/internal/handler/manage_test.go b/internal/handler/manage_test.go
index 505ec4b..4a743f7 100644
--- a/internal/handler/manage_test.go
+++ b/internal/handler/manage_test.go
@@ -2,7 +2,6 @@ package handler_test
 
 import (
 	"context"
-	"database/sql"
 	"encoding/json"
 	"fmt"
 	"log/slog"
@@ -19,13 +18,13 @@ import (
 
 // newTestHandlerDB creates a test handler and returns both the handler and the
 // underlying DB so tests can interact with the DB directly (e.g. to issue tokens).
-func newTestHandlerDB(t *testing.T) (*handler.Handler, *sql.DB) {
+func newTestHandlerDB(t *testing.T) (*handler.Handler, *db.DB) {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -33,7 +32,7 @@ func newTestHandlerDB(t *testing.T) (*handler.Handler, *sql.DB) {
 }
 
 // setupWorkspaceWithDB bootstraps a workspace and returns (handler, db, apiKey, userID).
-func setupWorkspaceWithDB(t *testing.T) (*handler.Handler, *sql.DB, string, string) {
+func setupWorkspaceWithDB(t *testing.T) (*handler.Handler, *db.DB, string, string) {
 	t.Helper()
 	h, database := newTestHandlerDB(t)
 
@@ -59,7 +58,7 @@ func setupWorkspaceWithDB(t *testing.T) (*handler.Handler, *sql.DB, string, stri
 // seedFullAvailabilityDB is seedFullAvailability's DB-direct sibling, for secondary
 // hosts (e.g. a round-robin rotation member) inserted straight into the DB rather than
 // through /v1/setup — they have no API key of their own to call the HTTP endpoint with.
-func seedFullAvailabilityDB(t *testing.T, database *sql.DB, userID string) {
+func seedFullAvailabilityDB(t *testing.T, database *db.DB, userID string) {
 	t.Helper()
 	for day := 0; day < 7; day++ {
 		if _, err := database.Exec(
@@ -95,7 +94,7 @@ func createBookingViaHTTP(t *testing.T, h *handler.Handler, slug, startAt string
 }
 
 // issueTestToken issues a manage token for bookingID via the booking service.
-func issueTestToken(t *testing.T, database *sql.DB, bookingID string) string {
+func issueTestToken(t *testing.T, database *db.DB, bookingID string) string {
 	t.Helper()
 	svc := booking.New(database)
 	tok, err := svc.IssueManageToken(context.Background(), bookingID)
diff --git a/internal/handler/mcp_scope_test.go b/internal/handler/mcp_scope_test.go
index 5d1aa2b..4614ab1 100644
--- a/internal/handler/mcp_scope_test.go
+++ b/internal/handler/mcp_scope_test.go
@@ -17,12 +17,12 @@ import (
 // verifies MCP tools scope by role: a member sees/controls only the bookings they host,
 // while an admin/owner (and the unauthenticated stdio operator) see the whole workspace.
 func TestMCP_roleScoping(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db open: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	h := New(database, slog.Default())
diff --git a/internal/handler/slots_busy_test.go b/internal/handler/slots_busy_test.go
index 9d4be97..c415d96 100644
--- a/internal/handler/slots_busy_test.go
+++ b/internal/handler/slots_busy_test.go
@@ -16,12 +16,12 @@ import (
 // generation would offer a slot the host is already booked for (then 409 at
 // booking time). Everything is stored UTC — this guards the fetch *window*.
 func TestHostAvailability_includesAdjacentUTCDayBooking(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open db: %v", err)
 	}
 	defer database.Close()
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	h := New(database, slog.New(slog.DiscardHandler))
@@ -60,12 +60,12 @@ func TestHostAvailability_includesAdjacentUTCDayBooking(t *testing.T) {
 // bookings.host_id) — otherwise their slots on other events stay open and they
 // get double-booked.
 func TestHostAvailability_includesNonPrimaryGroupSeat(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open db: %v", err)
 	}
 	defer database.Close()
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	h := New(database, slog.New(slog.DiscardHandler))
diff --git a/internal/handler/stripe_locale_internal_test.go b/internal/handler/stripe_locale_internal_test.go
index efb4b64..7af442f 100644
--- a/internal/handler/stripe_locale_internal_test.go
+++ b/internal/handler/stripe_locale_internal_test.go
@@ -65,12 +65,12 @@ func (c *captureMailer) recipients() []string {
 // of the language the attendee actually booked in — even though the free-booking path (same
 // dispatchBookingConfirmation) got this right. See stripe_booking.go's SELECT.
 func TestConfirmPaidBooking_usesAttendeeLocale(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
 	defer database.Close()
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 
diff --git a/internal/handler/stripe_settings.go b/internal/handler/stripe_settings.go
index 6c65e35..003c16b 100644
--- a/internal/handler/stripe_settings.go
+++ b/internal/handler/stripe_settings.go
@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"net/http"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/secret"
 	"github.com/calnode/calnode/internal/stripe"
 )
@@ -19,7 +20,7 @@ type StripeConfig struct {
 
 // LoadStripeSettingsFromDB reads Stripe credentials from server_settings and decrypts the
 // secret key + webhook secret. Returns nil (not an error) when the secret key is unset.
-func LoadStripeSettingsFromDB(db *sql.DB, encKey [32]byte) (*StripeConfig, error) {
+func LoadStripeSettingsFromDB(db *db.DB, encKey [32]byte) (*StripeConfig, error) {
 	var secretEnc, pubKey, whEnc string
 	err := db.QueryRow(`
 		SELECT stripe_secret_key_enc, stripe_publishable_key, stripe_webhook_secret_enc
diff --git a/internal/handler/zoom_settings.go b/internal/handler/zoom_settings.go
index a6c79d8..91033db 100644
--- a/internal/handler/zoom_settings.go
+++ b/internal/handler/zoom_settings.go
@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"net/http"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/secret"
 	"github.com/calnode/calnode/internal/zoom"
 )
@@ -20,7 +21,7 @@ type ZoomOAuthConfig struct {
 
 // LoadZoomSettingsFromDB reads the Zoom OAuth app credentials from server_settings and
 // decrypts the client secret. Returns nil (not an error) when client_id is empty.
-func LoadZoomSettingsFromDB(db *sql.DB, encKey [32]byte) (*ZoomOAuthConfig, error) {
+func LoadZoomSettingsFromDB(db *db.DB, encKey [32]byte) (*ZoomOAuthConfig, error) {
 	var clientID, secretEnc string
 	err := db.QueryRow(`
 		SELECT zoom_client_id, zoom_client_secret_enc
diff --git a/internal/keyvault/keyvault.go b/internal/keyvault/keyvault.go
index 2a799a2..c16b3f4 100644
--- a/internal/keyvault/keyvault.go
+++ b/internal/keyvault/keyvault.go
@@ -23,6 +23,7 @@ import (
 	"fmt"
 	"log/slog"
 
+	"github.com/calnode/calnode/internal/db"
 	"golang.org/x/crypto/argon2"
 )
 
@@ -69,7 +70,7 @@ func (v *Vault) DEKHex() string { return hex.EncodeToString(v.dek[:]) }
 //     working; wrap and store it.
 //  4. platformSecret empty + devMode → ephemeral random DEK; warn; never stored.
 //  5. platformSecret empty + !devMode → fatal error.
-func Open(db *sql.DB, platformSecret, recoverySecret string, devMode bool) (*Vault, error) {
+func Open(db *db.DB, platformSecret, recoverySecret string, devMode bool) (*Vault, error) {
 	if platformSecret == "" {
 		if devMode {
 			slog.Warn("keyvault: CALNODE_ENCRYPTION_KEY is not set — using an ephemeral key that will change on restart; stored secrets will become unreadable")
@@ -115,7 +116,7 @@ func Open(db *sql.DB, platformSecret, recoverySecret string, devMode bool) (*Vau
 
 // RotatePrimary re-wraps the DEK under a new platform secret. The data columns
 // are never touched. oldSecret must match the current CALNODE_ENCRYPTION_KEY.
-func RotatePrimary(db *sql.DB, oldSecret, newSecret string) error {
+func RotatePrimary(db *db.DB, oldSecret, newSecret string) error {
 	row := db.QueryRow(`
 		SELECT wrapped_dek, kdf_salt, kdf_params
 		FROM crypto_keystore WHERE label = ?`, labelPrimary)
@@ -137,7 +138,7 @@ func RotatePrimary(db *sql.DB, oldSecret, newSecret string) error {
 
 // RecoverPrimary uses the recovery secret (CALNODE_RECOVERY_SECRET) to
 // establish a new platform secret when the old one is lost.
-func RecoverPrimary(db *sql.DB, recoverySecret, newPlatformSecret string) error {
+func RecoverPrimary(db *db.DB, recoverySecret, newPlatformSecret string) error {
 	row := db.QueryRow(`
 		SELECT wrapped_dek, kdf_salt, kdf_params
 		FROM crypto_keystore WHERE label = ?`, labelRecovery)
@@ -171,7 +172,7 @@ func openExisting(platformSecret string, wrappedDEK, kdfSalt []byte, paramsJSON
 	return &Vault{dek: dek}, nil
 }
 
-func freshInstall(db *sql.DB, platformSecret, recoverySecret string) (*Vault, error) {
+func freshInstall(db *db.DB, platformSecret, recoverySecret string) (*Vault, error) {
 	var dek [32]byte
 	if _, err := rand.Read(dek[:]); err != nil {
 		return nil, fmt.Errorf("keyvault: generate DEK: %w", err)
@@ -182,7 +183,7 @@ func freshInstall(db *sql.DB, platformSecret, recoverySecret string) (*Vault, er
 	return &Vault{dek: dek}, nil
 }
 
-func migrateLegacy(db *sql.DB, platformSecret, recoverySecret string) (*Vault, error) {
+func migrateLegacy(db *db.DB, platformSecret, recoverySecret string) (*Vault, error) {
 	// The existing deployment used platformSecret directly as the raw AES-256 key.
 	// Adopt that value as the DEK so all existing *_enc ciphertext keeps decrypting.
 	raw, err := hex.DecodeString(platformSecret)
@@ -197,7 +198,7 @@ func migrateLegacy(db *sql.DB, platformSecret, recoverySecret string) (*Vault, e
 	return &Vault{dek: dek}, nil
 }
 
-func storeKeystore(db *sql.DB, dek [32]byte, platformSecret, recoverySecret string) error {
+func storeKeystore(db *db.DB, dek [32]byte, platformSecret, recoverySecret string) error {
 	if err := insertKeystoreRow(db, labelPrimary, dek, platformSecret); err != nil {
 		return err
 	}
@@ -209,7 +210,7 @@ func storeKeystore(db *sql.DB, dek [32]byte, platformSecret, recoverySecret stri
 	return nil
 }
 
-func insertKeystoreRow(db *sql.DB, label string, dek [32]byte, secret string) error {
+func insertKeystoreRow(db *db.DB, label string, dek [32]byte, secret string) error {
 	salt := make([]byte, saltLen)
 	if _, err := rand.Read(salt); err != nil {
 		return fmt.Errorf("keyvault: generate salt for %s: %w", label, err)
@@ -291,7 +292,7 @@ func unwrapDEK(kek [32]byte, wrapped []byte) ([32]byte, error) {
 
 // hasEncryptedData returns true if any *_enc column contains data, which
 // signals a legacy deployment that used a raw key rather than the vault.
-func hasEncryptedData(db *sql.DB) (bool, error) {
+func hasEncryptedData(db *db.DB) (bool, error) {
 	checks := []string{
 		`SELECT 1 FROM server_settings WHERE smtp_pass_enc != '' AND smtp_pass_enc IS NOT NULL LIMIT 1`,
 		`SELECT 1 FROM server_settings WHERE google_client_secret_enc != '' AND google_client_secret_enc IS NOT NULL LIMIT 1`,
diff --git a/internal/keyvault/keyvault_test.go b/internal/keyvault/keyvault_test.go
index 4b689a5..00e2951 100644
--- a/internal/keyvault/keyvault_test.go
+++ b/internal/keyvault/keyvault_test.go
@@ -1,7 +1,6 @@
 package keyvault_test
 
 import (
-	"database/sql"
 	"encoding/hex"
 	"testing"
 
@@ -9,13 +8,13 @@ import (
 	"github.com/calnode/calnode/internal/keyvault"
 )
 
-func newTestDB(t *testing.T) *sql.DB {
+func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://file::memory:?cache=shared&_fk=1")
+	database, err := db.OpenDB("sqlite://file::memory:?cache=shared&_fk=1")
 	if err != nil {
 		t.Fatalf("open test db: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("migrate test db: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
diff --git a/internal/server/server.go b/internal/server/server.go
index d770024..c8289c5 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -2,7 +2,6 @@ package server
 
 import (
 	"context"
-	"database/sql"
 	"log/slog"
 	"net/http"
 	"time"
@@ -20,6 +19,7 @@ import (
 	"github.com/calnode/calnode/internal/mailer"
 	"github.com/calnode/calnode/internal/secret"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/stripe"
 	"github.com/calnode/calnode/internal/webhook"
 	"github.com/calnode/calnode/internal/worker"
@@ -36,7 +36,7 @@ import (
 // uses it to back the HTTP server; the `calnode mcp` subcommand uses it to serve the
 // MCP server over stdio. The returned drain func blocks until the background worker
 // has finished its current poll cycle.
-func BuildHandler(ctx context.Context, cfg *config.Config, db *sql.DB, logger *slog.Logger) (*handler.Handler, func()) {
+func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger) (*handler.Handler, func()) {
 	h := handler.New(db, logger)
 	h.SetBaseURL(cfg.BaseURL)
 	h.SetPublicBaseURL(cfg.PublicBaseURL)
@@ -248,7 +248,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *sql.DB, logger *s
 
 // New wires services via BuildHandler, then registers all HTTP routes. It returns the
 // http.Handler and the worker drain func.
-func New(ctx context.Context, cfg *config.Config, db *sql.DB, logger *slog.Logger) (http.Handler, func()) {
+func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger) (http.Handler, func()) {
 	h, drain := BuildHandler(ctx, cfg, db, logger)
 	mux := http.NewServeMux()
 
@@ -542,7 +542,7 @@ func New(ctx context.Context, cfg *config.Config, db *sql.DB, logger *slog.Logge
 // seedSMTPToDB writes env-var SMTP settings into the DB on first boot so they
 // appear in the UI. Uses WHERE smtp_host = ” to avoid a check-then-act race
 // and to never overwrite settings the user has already saved via the UI.
-func seedSMTPToDB(db *sql.DB, cfg *config.Config, encKey [32]byte, logger *slog.Logger) {
+func seedSMTPToDB(db *db.DB, cfg *config.Config, encKey [32]byte, logger *slog.Logger) {
 	var passEnc string
 	if cfg.SMTPPass != "" {
 		enc, err := secret.Encrypt(encKey, cfg.SMTPPass)
diff --git a/internal/webhook/webhook.go b/internal/webhook/webhook.go
index d266df8..49d8280 100644
--- a/internal/webhook/webhook.go
+++ b/internal/webhook/webhook.go
@@ -17,6 +17,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/uid"
 )
 
@@ -128,13 +129,13 @@ type BookingPayload struct {
 }
 
 type Service struct {
-	db  *sql.DB
+	db  *db.DB
 	key [32]byte
 }
 
 // New creates a Service. If encKeyHex is empty an ephemeral key is generated
 // (secrets won't survive restarts but the server still works in dev/test).
-func New(db *sql.DB, encKeyHex string) (*Service, error) {
+func New(db *db.DB, encKeyHex string) (*Service, error) {
 	s := &Service{db: db}
 	if encKeyHex != "" {
 		b, err := hex.DecodeString(encKeyHex)
diff --git a/internal/webhook/webhook_test.go b/internal/webhook/webhook_test.go
index b29ec0a..7f129e2 100644
--- a/internal/webhook/webhook_test.go
+++ b/internal/webhook/webhook_test.go
@@ -4,7 +4,6 @@ import (
 	"context"
 	"crypto/hmac"
 	"crypto/sha256"
-	"database/sql"
 	"encoding/hex"
 	"testing"
 
@@ -19,16 +18,16 @@ const (
 
 type env struct {
 	svc *webhook.Service
-	db  *sql.DB
+	db  *db.DB
 }
 
 func newEnv(t *testing.T) *env {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -54,8 +53,8 @@ func newEnv(t *testing.T) *env {
 // ---------------------------------------------------------------------------
 
 func TestNew_badKeyReturnsError(t *testing.T) {
-	database, _ := db.Open("sqlite://:memory:")
-	db.Migrate(database)
+	database, _ := db.OpenDB("sqlite://:memory:")
+	database.Migrate()
 	defer database.Close()
 
 	if _, err := webhook.New(database, "not-hex"); err == nil {
@@ -67,8 +66,8 @@ func TestNew_badKeyReturnsError(t *testing.T) {
 }
 
 func TestNew_emptyKeyUsesEphemeral(t *testing.T) {
-	database, _ := db.Open("sqlite://:memory:")
-	db.Migrate(database)
+	database, _ := db.OpenDB("sqlite://:memory:")
+	database.Migrate()
 	defer database.Close()
 
 	svc, err := webhook.New(database, "")
diff --git a/internal/worker/delivery_retention_test.go b/internal/worker/delivery_retention_test.go
index 7035ef8..06e4053 100644
--- a/internal/worker/delivery_retention_test.go
+++ b/internal/worker/delivery_retention_test.go
@@ -2,15 +2,16 @@ package worker_test
 
 import (
 	"context"
-	"database/sql"
 	"testing"
 	"time"
+
+	"github.com/calnode/calnode/internal/db"
 )
 
 // seedDelivery inserts one webhook_deliveries row with an explicit status and
 // last_attempted_at. A nil attemptedAt leaves the column NULL, which is what a
 // delivery that has never been tried looks like.
-func seedDelivery(t *testing.T, database *sql.DB, id, webhookID, status string, attemptedAt *time.Time) {
+func seedDelivery(t *testing.T, database *db.DB, id, webhookID, status string, attemptedAt *time.Time) {
 	t.Helper()
 	var at any
 	if attemptedAt != nil {
@@ -24,7 +25,7 @@ func seedDelivery(t *testing.T, database *sql.DB, id, webhookID, status string,
 	}
 }
 
-func deliveryExists(t *testing.T, database *sql.DB, id string) bool {
+func deliveryExists(t *testing.T, database *db.DB, id string) bool {
 	t.Helper()
 	var n int
 	if err := database.QueryRow(
diff --git a/internal/worker/worker.go b/internal/worker/worker.go
index b44ed1b..9188957 100644
--- a/internal/worker/worker.go
+++ b/internal/worker/worker.go
@@ -11,6 +11,7 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/i18n"
 	"github.com/calnode/calnode/internal/mailer"
 	"github.com/calnode/calnode/internal/netutil"
@@ -25,7 +26,7 @@ const webhookDeliveryRetention = 30 * 24 * time.Hour
 
 // Worker polls the jobs table and processes pending jobs (webhooks, reminders).
 type Worker struct {
-	db         *sql.DB
+	db         *db.DB
 	svc        *webhook.Service
 	mailer     mailer.Mailer
 	logger     *slog.Logger
@@ -51,7 +52,7 @@ func WithMailer(m mailer.Mailer) func(*Worker) {
 	return func(w *Worker) { w.mailer = m }
 }
 
-func New(db *sql.DB, svc *webhook.Service, logger *slog.Logger, opts ...func(*Worker)) *Worker {
+func New(db *db.DB, svc *webhook.Service, logger *slog.Logger, opts ...func(*Worker)) *Worker {
 	w := &Worker{
 		db:       db,
 		svc:      svc,
diff --git a/internal/worker/worker_test.go b/internal/worker/worker_test.go
index 916c9f1..2e7d3d8 100644
--- a/internal/worker/worker_test.go
+++ b/internal/worker/worker_test.go
@@ -4,7 +4,6 @@ import (
 	"context"
 	"crypto/hmac"
 	"crypto/sha256"
-	"database/sql"
 	"encoding/hex"
 	"encoding/json"
 	"io"
@@ -19,13 +18,13 @@ import (
 	"github.com/calnode/calnode/internal/worker"
 )
 
-func setup(t *testing.T) (*sql.DB, *webhook.Service) {
+func setup(t *testing.T) (*db.DB, *webhook.Service) {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("db.Open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -49,7 +48,7 @@ func setup(t *testing.T) (*sql.DB, *webhook.Service) {
 	return database, svc
 }
 
-func newWorker(t *testing.T, database *sql.DB, svc *webhook.Service) *worker.Worker {
+func newWorker(t *testing.T, database *db.DB, svc *webhook.Service) *worker.Worker {
 	t.Helper()
 	// Tests use a local httptest.Server, so bypass the production SSRF guard.
 	return worker.New(database, svc, slog.Default(),
diff --git a/internal/zoom/zoom.go b/internal/zoom/zoom.go
index e572e38..02075e4 100644
--- a/internal/zoom/zoom.go
+++ b/internal/zoom/zoom.go
@@ -20,6 +20,7 @@ import (
 
 	"golang.org/x/oauth2"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/oauthstore"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -28,14 +29,14 @@ import (
 type Client struct {
 	config  *oauth2.Config
 	key     [32]byte
-	db      *sql.DB
+	db      *db.DB
 	logger  *slog.Logger
 	apiBase string // https://api.zoom.us/v2; overridable in tests
 }
 
 // New builds a Client from the instance's Zoom OAuth app credentials. encKeyHex is the
 // 64-char hex AES-256 server key (same one used for calendar tokens).
-func New(db *sql.DB, clientID, clientSecret, redirectURL, encKeyHex string) (*Client, error) {
+func New(db *db.DB, clientID, clientSecret, redirectURL, encKeyHex string) (*Client, error) {
 	key, err := secret.ParseKey(encKeyHex)
 	if err != nil {
 		return nil, fmt.Errorf("zoom: invalid encryption key: %w", err)
diff --git a/internal/zoom/zoom_test.go b/internal/zoom/zoom_test.go
index f1fb43d..7ecc207 100644
--- a/internal/zoom/zoom_test.go
+++ b/internal/zoom/zoom_test.go
@@ -2,7 +2,6 @@ package zoom
 
 import (
 	"context"
-	"database/sql"
 	"encoding/json"
 	"io"
 	"net/http"
@@ -16,13 +15,13 @@ import (
 
 const testKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
 
-func newTestDB(t *testing.T) *sql.DB {
+func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("newTestDB: open: %v", err)
 	}
-	if err := db.Migrate(database); err != nil {
+	if err := database.Migrate(); err != nil {
 		t.Fatalf("newTestDB: migrate: %v", err)
 	}
 	t.Cleanup(func() { database.Close() })
@@ -38,7 +37,7 @@ func newTestClient(t *testing.T) *Client {
 	return c
 }
 
-func seedUser(t *testing.T, database *sql.DB, userID string) {
+func seedUser(t *testing.T, database *db.DB, userID string) {
 	t.Helper()
 	_, err := database.ExecContext(context.Background(), `
 		INSERT INTO users (id, email, name, iana_timezone, is_admin, created_at)
@@ -50,7 +49,7 @@ func seedUser(t *testing.T, database *sql.DB, userID string) {
 }
 
 // connectZoom inserts a non-expired Zoom token row for userID.
-func connectZoom(t *testing.T, database *sql.DB, userID, accessToken string) {
+func connectZoom(t *testing.T, database *db.DB, userID, accessToken string) {
 	t.Helper()
 	key, _ := secret.ParseKey(testKeyHex)
 	enc, err := secret.Encrypt(key, accessToken)

From 62dc81e7ccf83897aa135eb2f7765d513d0e4e98 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 03:32:43 -0400
Subject: [PATCH 05/51] db: port the SQL that only SQLite accepts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Timestamps first, because they are 38 of the 44 sites. datetime('now') and
strftime('%Y-%m-%dT%H:%M:%fZ','now') are now computed in Go and bound as
parameters, which removes the dialect difference rather than encoding it and
makes the value something a test can predict.

internal/dbtime holds the two layouts. Two, not one: the schema already stores
both shapes, and they are load-bearing. recordings.created_at is the space-
separated form and meeting_consents.decided_at the millisecond form, and
consentWindow converts between them to build a lexicographic BETWEEN; notes'
updated_at is handed to a client verbatim; jobs.run_at written by enqueueJob is
deliberately the space form, which sorts before every T-separated run_at and is
what makes those jobs due immediately. Normalising would have been tidier and
would have quietly changed all three. dbtime_test asserts both layouts against
SQLite's own output rather than against a reading of its documentation.

The rest:

  - INSERT OR IGNORE becomes ON CONFLICT DO NOTHING with no conflict target,
    which both engines accept and which keeps OR IGNORE's "any unique
    constraint" scope.

  - COLLATE NOCASE becomes LOWER(col) = LOWER(?). No dialect pair, because
    nothing indexes booking_attendees.email: there is no collation for an index
    to depend on, so there is no plan to preserve.

  - demo.Reset's PRAGMA foreign_keys is SQLite-only now. Postgres has no
    equivalent without superuser rights, so that branch wipes with a single
    TRUNCATE ... CASCADE over every table, which needs no delete ordering at
    all. sqlite_master becomes pg_tables scoped to current_schema(), the one
    Dialect.SQL pair added here — current_schema() also keeps it right inside an
    isolated test schema.

RETURNING is left alone: both engines support it. No UPDATE or DELETE carries a
LIMIT; that was checked by scanning every backquoted string in the tree rather
than grepping single lines.

SQLite behaviour is unchanged, stored bytes included.
---
 PROGRESS.md                              | 28 ++++++++-
 internal/booking/service.go              |  2 +-
 internal/dbtime/dbtime.go                | 35 ++++++++++++
 internal/dbtime/dbtime_test.go           | 51 +++++++++++++++++
 internal/demo/demo.go                    | 72 +++++++++++++++++-------
 internal/handler/booking_handler.go      | 15 +++--
 internal/handler/branding_settings.go    | 13 +++--
 internal/handler/email_settings.go       | 11 ++--
 internal/handler/email_settings_test.go  |  7 ++-
 internal/handler/event_type.go           |  8 ++-
 internal/handler/google_settings.go      | 13 +++--
 internal/handler/google_settings_test.go |  5 +-
 internal/handler/handler.go              |  4 +-
 internal/handler/livekit_recording.go    | 20 ++++---
 internal/handler/livekit_settings.go     |  9 +--
 internal/handler/llm_settings.go         |  6 +-
 internal/handler/notetaker.go            | 20 ++++---
 internal/handler/notetaker_http.go       |  5 +-
 internal/handler/storage_settings.go     |  4 +-
 internal/handler/stripe_settings.go      | 13 +++--
 internal/handler/tracking_settings.go    |  6 +-
 internal/handler/zoom_settings.go        | 13 +++--
 internal/keyvault/keyvault.go            |  6 +-
 internal/server/server.go                |  5 +-
 24 files changed, 278 insertions(+), 93 deletions(-)
 create mode 100644 internal/dbtime/dbtime.go
 create mode 100644 internal/dbtime/dbtime_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 8bbca8d..d91b79f 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -21,7 +21,33 @@ the wrapper's method names match `database/sql`'s.
 
 Gates: `go build ./...`, `go vet ./...`, `gofmt -l`, `go test ./...` all clean on SQLite.
 
-## Boundary 2 — non-portable SQL — TODO
+## Boundary 2 — non-portable SQL — DONE
+
+New package `internal/dbtime`: `Now()` for `datetime('now')`, `NowMilli()` for
+`strftime('%Y-%m-%dT%H:%M:%fZ','now')`. Every one of the 38 engine-side timestamps
+became a bound parameter. The two layouts are kept distinct on purpose — the schema
+already stores both shapes, they are compared lexicographically and served to
+clients verbatim, so folding them into one would change SQLite's stored bytes.
+`dbtime_test.go` asserts both layouts against SQLite's own output.
+
+- `INSERT OR IGNORE` → `INSERT … ON CONFLICT DO NOTHING`, no conflict target, which
+  both engines accept and which matches OR IGNORE's "any unique constraint" scope
+  (3 sites: demo seed, and the two reminder enqueues).
+- `COLLATE NOCASE` → `LOWER(col) = LOWER(?)` at both sites. No `d.SQL` pair: nothing
+  indexes `booking_attendees.email`, so there is no collation for an index to depend
+  on and no plan to preserve.
+- `PRAGMA foreign_keys` in `demo.Reset` is now SQLite-only. Postgres has no
+  equivalent short of superuser rights, so that branch wipes with one
+  `TRUNCATE … CASCADE` naming every table, which needs no FK ordering.
+- `sqlite_master` in `demo.listTables` is the one `d.SQL` pair: `pg_tables` scoped to
+  `current_schema()` on Postgres, which also keeps it correct inside an isolated
+  test schema.
+- `RETURNING position` (`question_handler.go`) is unchanged. Both engines support it;
+  verified on SQLite by the existing question tests, unverified on Postgres.
+- No `LIMIT` inside any `UPDATE`/`DELETE`. Checked by scanning every backquoted
+  string in the tree, not by a line grep.
+
+Gates: `go build ./...`, `go vet ./...`, `gofmt -l`, `go test ./...` clean on SQLite.
 
 ## Boundary 3 — advisory lock replacing the single-writer guarantee — TODO
 
diff --git a/internal/booking/service.go b/internal/booking/service.go
index 2f4b3ad..725e7a3 100644
--- a/internal/booking/service.go
+++ b/internal/booking/service.go
@@ -125,7 +125,7 @@ func (s *Service) Create(ctx context.Context, p CreateParams) (*Booking, error)
 			SELECT COUNT(*) FROM bookings b
 			JOIN booking_attendees a ON a.booking_id = b.id AND a.is_organizer = 1
 			WHERE b.event_type_id = ? AND b.status != 'cancelled'
-			  AND b.end_at > ? AND a.email = ? COLLATE NOCASE`,
+			  AND b.end_at > ? AND LOWER(a.email) = LOWER(?)`,
 			p.EventTypeID, now, p.Organizer.Email).Scan(&active); err != nil {
 			return nil, fmt.Errorf("booking: active-limit check: %w", err)
 		}
diff --git a/internal/dbtime/dbtime.go b/internal/dbtime/dbtime.go
new file mode 100644
index 0000000..a47dd76
--- /dev/null
+++ b/internal/dbtime/dbtime.go
@@ -0,0 +1,35 @@
+// Package dbtime formats "now" for Calnode's TEXT timestamp columns.
+//
+// Those columns used to be filled by the engine, with datetime('now') or
+// strftime('%Y-%m-%dT%H:%M:%fZ','now'). Neither function exists in PostgreSQL, so
+// the value is computed here and bound as an ordinary parameter instead: one
+// statement that both engines accept, and a timestamp a test can control by
+// comparing against a value it computed itself.
+//
+// The two layouts are the two shapes already in the schema, kept byte-identical to
+// what SQLite wrote before. Normalising them to one would be tidier and wrong: the
+// stored text is compared lexicographically (recordings scope consents to a time
+// window that way) and handed to clients verbatim (GET /v1/notes/{id} returns
+// updated_at), so a shape change would silently alter both.
+package dbtime
+
+import "time"
+
+const (
+	// DateTime is SQLite's datetime('now') output: "2006-01-02 15:04:05", UTC,
+	// second resolution, no zone suffix.
+	DateTime = "2006-01-02 15:04:05"
+
+	// RFC3339Milli is SQLite's strftime('%Y-%m-%dT%H:%M:%fZ','now') output:
+	// RFC 3339 with exactly three fractional digits. %f is "SS.SSS", so the
+	// milliseconds are always present, including a trailing zero.
+	RFC3339Milli = "2006-01-02T15:04:05.000Z"
+)
+
+// Now returns the current UTC time in the DateTime layout — the replacement for
+// datetime('now').
+func Now() string { return time.Now().UTC().Format(DateTime) }
+
+// NowMilli returns the current UTC time in the RFC3339Milli layout — the
+// replacement for strftime('%Y-%m-%dT%H:%M:%fZ','now').
+func NowMilli() string { return time.Now().UTC().Format(RFC3339Milli) }
diff --git a/internal/dbtime/dbtime_test.go b/internal/dbtime/dbtime_test.go
new file mode 100644
index 0000000..a0ec829
--- /dev/null
+++ b/internal/dbtime/dbtime_test.go
@@ -0,0 +1,51 @@
+package dbtime_test
+
+import (
+	"regexp"
+	"testing"
+
+	_ "modernc.org/sqlite"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
+)
+
+// The whole point of this package is that a Go-computed timestamp is
+// indistinguishable from the one SQLite used to write. Assert that against SQLite
+// itself rather than against a hand-read of its docs: if the shapes ever diverge,
+// existing rows and new rows stop comparing lexicographically and the recordings
+// consent window silently returns the wrong set.
+func TestLayoutsMatchSQLite(t *testing.T) {
+	handle, err := db.OpenDB("sqlite://:memory:")
+	if err != nil {
+		t.Fatalf("db.OpenDB: %v", err)
+	}
+	t.Cleanup(func() { handle.Close() })
+
+	cases := []struct {
+		name string
+		expr string
+		got  string
+	}{
+		{"datetime('now')", `SELECT datetime('now')`, dbtime.Now()},
+		{"strftime millis", `SELECT strftime('%Y-%m-%dT%H:%M:%fZ','now')`, dbtime.NowMilli()},
+	}
+
+	for _, c := range cases {
+		var want string
+		if err := handle.QueryRow(c.expr).Scan(&want); err != nil {
+			t.Fatalf("%s: %v", c.name, err)
+		}
+		// Compare shape, not value: the two clocks are read microseconds apart, so
+		// the digits legitimately differ. A digit-for-digit mask is what catches a
+		// layout mistake (missing "Z", " " where "T" belongs, 6 fractional digits).
+		if mask(want) != mask(c.got) {
+			t.Errorf("%s: sqlite wrote %q (shape %q), dbtime produced %q (shape %q)",
+				c.name, want, mask(want), c.got, mask(c.got))
+		}
+	}
+}
+
+var digits = regexp.MustCompile(`[0-9]`)
+
+func mask(s string) string { return digits.ReplaceAllString(s, "N") }
diff --git a/internal/demo/demo.go b/internal/demo/demo.go
index a62c29e..2a50c7f 100644
--- a/internal/demo/demo.go
+++ b/internal/demo/demo.go
@@ -8,6 +8,7 @@ package demo
 import (
 	"context"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/calnode/calnode/internal/db"
@@ -36,8 +37,11 @@ func Seed(ctx context.Context, db *db.DB) error {
 	}
 	defer tx.Rollback() //nolint:errcheck
 
+	// ON CONFLICT DO NOTHING rather than SQLite's INSERT OR IGNORE: both engines
+	// accept it. The conflict target is omitted, which covers any unique
+	// constraint, exactly as OR IGNORE did.
 	if _, err := tx.ExecContext(ctx,
-		`INSERT OR IGNORE INTO server_settings (id) VALUES (1)`); err != nil {
+		`INSERT INTO server_settings (id) VALUES (1) ON CONFLICT DO NOTHING`); err != nil {
 		return fmt.Errorf("demo seed: server_settings: %w", err)
 	}
 
@@ -187,19 +191,27 @@ func Reset(ctx context.Context, db *db.DB) (err error) {
 		return err
 	}
 
-	// foreign_keys is connection-scoped and can't be toggled mid-transaction,
-	// so it's set here, before BeginTx — safe only because the pool is a
-	// single persistent connection (db.SetMaxOpenConns(1), internal/db/db.go).
-	// Needed because the delete order below is arbitrary relative to the
-	// schema's 46 migrations' worth of foreign-key relationships.
-	if _, ferr := db.ExecContext(ctx, `PRAGMA foreign_keys = OFF`); ferr != nil {
-		return fmt.Errorf("demo reset: disable foreign keys: %w", ferr)
-	}
-	defer func() {
-		if _, ferr := db.ExecContext(ctx, `PRAGMA foreign_keys = ON`); ferr != nil && err == nil {
-			err = fmt.Errorf("demo reset: re-enable foreign keys: %w", ferr)
+	// The wipe order below is arbitrary relative to the schema's 46 migrations'
+	// worth of foreign keys, so referential integrity has to be stood down for it.
+	// The engines do that differently and neither way exists on the other:
+	//
+	//   SQLite — PRAGMA foreign_keys is connection-scoped and cannot be toggled
+	//   mid-transaction, so it is set before BeginTx. Safe only because the pool
+	//   is one persistent connection (db.SetMaxOpenConns(1), internal/db/db.go).
+	//
+	//   Postgres — there is no equivalent switch short of superuser rights, so a
+	//   single TRUNCATE naming every table CASCADEs through the foreign keys
+	//   instead. TRUNCATE is transactional there, so it stays inside the tx.
+	if isSQLite(db) {
+		if _, ferr := db.ExecContext(ctx, `PRAGMA foreign_keys = OFF`); ferr != nil {
+			return fmt.Errorf("demo reset: disable foreign keys: %w", ferr)
 		}
-	}()
+		defer func() {
+			if _, ferr := db.ExecContext(ctx, `PRAGMA foreign_keys = ON`); ferr != nil && err == nil {
+				err = fmt.Errorf("demo reset: re-enable foreign keys: %w", ferr)
+			}
+		}()
+	}
 
 	tx, err := db.BeginTx(ctx, nil)
 	if err != nil {
@@ -207,9 +219,21 @@ func Reset(ctx context.Context, db *db.DB) (err error) {
 	}
 	defer tx.Rollback() //nolint:errcheck
 
-	for _, t := range tables {
-		if _, err = tx.ExecContext(ctx, fmt.Sprintf(`DELETE FROM %q`, t)); err != nil {
-			return fmt.Errorf("demo reset: delete from %s: %w", t, err)
+	if isSQLite(db) {
+		for _, t := range tables {
+			if _, err = tx.ExecContext(ctx, fmt.Sprintf(`DELETE FROM %q`, t)); err != nil {
+				return fmt.Errorf("demo reset: delete from %s: %w", t, err)
+			}
+		}
+	} else if len(tables) > 0 {
+		quoted := make([]string, len(tables))
+		for i, t := range tables {
+			quoted[i] = `"` + t + `"`
+		}
+		// #nosec G202 -- every name came from pg_tables in this schema, not from a request.
+		if _, err = tx.ExecContext(ctx,
+			`TRUNCATE TABLE `+strings.Join(quoted, ", ")+` CASCADE`); err != nil {
+			return fmt.Errorf("demo reset: truncate: %w", err)
 		}
 	}
 	if err = tx.Commit(); err != nil {
@@ -219,10 +243,20 @@ func Reset(ctx context.Context, db *db.DB) (err error) {
 	return Seed(ctx, db)
 }
 
+// isSQLite is a free function rather than an inline comparison because Reset and
+// listTables both name their handle "db", which shadows the package the Dialect
+// constants live in.
+func isSQLite(h *db.DB) bool { return h.Dialect() == db.DialectSQLite }
+
 func listTables(ctx context.Context, db *db.DB) ([]string, error) {
-	rows, err := db.QueryContext(ctx, `
-		SELECT name FROM sqlite_master
-		WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name != 'goose_db_version'`)
+	// sqlite_master has no Postgres counterpart. pg_tables scoped to
+	// current_schema() is the equivalent, and honouring the current schema is what
+	// lets a test run inside its own isolated one.
+	rows, err := db.QueryContext(ctx, db.Dialect().SQL(
+		`SELECT name FROM sqlite_master
+		 WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name != 'goose_db_version'`,
+		`SELECT tablename FROM pg_tables
+		 WHERE schemaname = current_schema() AND tablename != 'goose_db_version'`))
 	if err != nil {
 		return nil, fmt.Errorf("demo reset: list tables: %w", err)
 	}
diff --git a/internal/handler/booking_handler.go b/internal/handler/booking_handler.go
index 7f0c5d9..c221cff 100644
--- a/internal/handler/booking_handler.go
+++ b/internal/handler/booking_handler.go
@@ -734,7 +734,7 @@ func (h *Handler) CreateBooking(w http.ResponseWriter, r *http.Request) {
 		if err := h.db.QueryRowContext(r.Context(), `
 			SELECT COUNT(*) FROM bookings b
 			JOIN booking_attendees a ON a.booking_id = b.id AND a.is_organizer = 1
-			WHERE a.email = ? COLLATE NOCASE AND b.created_at > ?`,
+			WHERE LOWER(a.email) = LOWER(?) AND b.created_at > ?`,
 			req.Email, windowStart).Scan(&recent); err != nil {
 			h.logger.ErrorContext(r.Context(), "create booking: per-email throttle", "error", err)
 		} else if recent >= maxBookingsPerEmailPerHour {
@@ -1862,9 +1862,13 @@ func (h *Handler) enqueueReminder(ctx context.Context, bookingID string, startAt
 		return fmt.Errorf("enqueue reminder: marshal payload: %w", err)
 	}
 
+	// ON CONFLICT DO NOTHING is the portable spelling of SQLite's INSERT OR
+	// IGNORE, and drops the duplicate that jobs' UNIQUE(type, payload) rejects
+	// when the same reminder is enqueued twice.
 	_, err = h.db.ExecContext(ctx, `
-		INSERT OR IGNORE INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
-		VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)`,
+		INSERT INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
+		VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)
+		ON CONFLICT DO NOTHING`,
 		uid.New(), string(payload), runAt.Format(time.RFC3339))
 	return err
 }
@@ -1953,8 +1957,9 @@ func (h *Handler) replaceReminderJobs(ctx context.Context, bookingID, etID strin
 			return fmt.Errorf("replace reminder jobs: marshal payload: %w", err)
 		}
 		if _, err := tx.ExecContext(ctx, `
-			INSERT OR IGNORE INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
-			VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)`,
+			INSERT INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
+			VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)
+			ON CONFLICT DO NOTHING`,
 			uid.New(), string(payload), runAt.Format(time.RFC3339)); err != nil {
 			return fmt.Errorf("replace reminder jobs: insert: %w", err)
 		}
diff --git a/internal/handler/branding_settings.go b/internal/handler/branding_settings.go
index 98e3f18..b59cfc3 100644
--- a/internal/handler/branding_settings.go
+++ b/internal/handler/branding_settings.go
@@ -14,6 +14,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/i18n"
 	"github.com/calnode/calnode/internal/mailer"
 	"github.com/disintegration/imaging"
@@ -219,8 +220,8 @@ func (h *Handler) PatchBranding(w http.ResponseWriter, r *http.Request) {
 	}
 	if _, err := h.db.ExecContext(r.Context(), `
 		UPDATE server_settings SET business_name = ?, logo_height = ?, logo_opacity = ?,
-		       banner_opacity = ?, privacy_url = ?, terms_url = ?, fallback_locale = ?, updated_at = datetime('now')
-		WHERE id = 1`, req.BusinessName, req.LogoHeight, req.LogoOpacity, req.BannerOpacity, privacyURL, termsURL, req.FallbackLocale); err != nil {
+		       banner_opacity = ?, privacy_url = ?, terms_url = ?, fallback_locale = ?, updated_at = ?
+		WHERE id = 1`, req.BusinessName, req.LogoHeight, req.LogoOpacity, req.BannerOpacity, privacyURL, termsURL, req.FallbackLocale, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "branding settings: update", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
@@ -316,7 +317,7 @@ func (h *Handler) UploadBrandingLogo(w http.ResponseWriter, r *http.Request) {
 
 	logoURL := fmt.Sprintf("%s?v=%d", logoServePath, time.Now().Unix())
 	if _, err := h.db.ExecContext(r.Context(),
-		`UPDATE server_settings SET logo_url = ?, updated_at = datetime('now') WHERE id = 1`, logoURL); err != nil {
+		`UPDATE server_settings SET logo_url = ?, updated_at = ? WHERE id = 1`, logoURL, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "logo: update db", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
@@ -331,7 +332,7 @@ func (h *Handler) DeleteBrandingLogo(w http.ResponseWriter, r *http.Request) {
 	}
 	_ = os.Remove(filepath.Join(h.brandingDir(), "logo.png"))
 	if _, err := h.db.ExecContext(r.Context(),
-		`UPDATE server_settings SET logo_url = '', updated_at = datetime('now') WHERE id = 1`); err != nil {
+		`UPDATE server_settings SET logo_url = '', updated_at = ? WHERE id = 1`, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "logo: delete db", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
@@ -443,7 +444,7 @@ func (h *Handler) UploadBrandingBanner(w http.ResponseWriter, r *http.Request) {
 
 	bannerURL := fmt.Sprintf("%s?v=%d", bannerServePath, time.Now().Unix())
 	if _, err := h.db.ExecContext(r.Context(),
-		`UPDATE server_settings SET banner_url = ?, updated_at = datetime('now') WHERE id = 1`, bannerURL); err != nil {
+		`UPDATE server_settings SET banner_url = ?, updated_at = ? WHERE id = 1`, bannerURL, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "banner: update db", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
@@ -458,7 +459,7 @@ func (h *Handler) DeleteBrandingBanner(w http.ResponseWriter, r *http.Request) {
 	}
 	_ = os.Remove(filepath.Join(h.brandingDir(), "banner.png"))
 	if _, err := h.db.ExecContext(r.Context(),
-		`UPDATE server_settings SET banner_url = '', updated_at = datetime('now') WHERE id = 1`); err != nil {
+		`UPDATE server_settings SET banner_url = '', updated_at = ? WHERE id = 1`, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "banner: delete db", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
diff --git a/internal/handler/email_settings.go b/internal/handler/email_settings.go
index 8285a27..7dbf9b5 100644
--- a/internal/handler/email_settings.go
+++ b/internal/handler/email_settings.go
@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/mailer"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -186,14 +187,14 @@ func (h *Handler) storeEmailSecret(ctx context.Context, db execer, which emailSe
 	var q string
 	switch which {
 	case secretResendAPIKey:
-		q = `UPDATE server_settings SET resend_api_key_enc = ?, updated_at = datetime('now') WHERE id = 1`
+		q = `UPDATE server_settings SET resend_api_key_enc = ?, updated_at = ? WHERE id = 1`
 	case secretSMTPPass:
-		q = `UPDATE server_settings SET smtp_pass_enc = ?, updated_at = datetime('now') WHERE id = 1`
+		q = `UPDATE server_settings SET smtp_pass_enc = ?, updated_at = ? WHERE id = 1`
 	default:
 		return fmt.Errorf("unknown email secret %d", int(which))
 	}
 
-	if _, err := db.ExecContext(ctx, q, enc); err != nil {
+	if _, err := db.ExecContext(ctx, q, enc, dbtime.Now()); err != nil {
 		return fmt.Errorf("store %s: %w", which, err)
 	}
 	return nil
@@ -266,11 +267,11 @@ func (h *Handler) PatchEmailSettings(w http.ResponseWriter, r *http.Request) {
 		  smtp_host = ?, smtp_port = ?, smtp_user = ?,
 		  smtp_tls = ?, smtp_starttls = ?,
 		  email_from = ?, email_from_name = ?,
-		  updated_at = datetime('now')
+		  updated_at = ?
 		WHERE id = 1`,
 		req.SMTPHost, req.SMTPPort, req.SMTPUser,
 		boolToInt(req.SMTPTLS), boolToInt(req.SMTPStartTLS),
-		req.EmailFrom, req.EmailFromName); err != nil {
+		req.EmailFrom, req.EmailFromName, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "email settings: update", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
diff --git a/internal/handler/email_settings_test.go b/internal/handler/email_settings_test.go
index c290685..3df55f1 100644
--- a/internal/handler/email_settings_test.go
+++ b/internal/handler/email_settings_test.go
@@ -9,6 +9,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/mailer"
 )
 
@@ -61,7 +62,7 @@ func TestGetEmailSettings_nonAdminForbidden(t *testing.T) {
 	rawKey := "non-admin-get-email-test-key"
 	hash := sha256HexForTest(rawKey)
 	db.Exec(`INSERT INTO users (id, email, name, iana_timezone, is_admin) VALUES ('u4','other3@example.com','Other3','UTC',0)`)
-	db.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k4','u4','test',?,datetime('now'))`, hash)
+	db.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k4','u4','test',?,?)`, hash, dbtime.Now())
 
 	req := authReq(http.MethodGet, "/v1/settings/email", "", rawKey)
 	rec := httptest.NewRecorder()
@@ -216,7 +217,7 @@ func TestPatchEmailSettings_nonAdminForbidden(t *testing.T) {
 	rawKey := "non-admin-test-key-xyz"
 	hash := sha256HexForTest(rawKey)
 	db.Exec(`INSERT INTO users (id, email, name, iana_timezone, is_admin) VALUES ('u2','other@example.com','Other','UTC',0)`)
-	db.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k2','u2','test',?,datetime('now'))`, hash)
+	db.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k2','u2','test',?,?)`, hash, dbtime.Now())
 
 	req := authReq(http.MethodPatch, "/v1/settings/email", `{"smtp_host":"evil.smtp.example.com"}`, rawKey)
 	rec := httptest.NewRecorder()
@@ -286,7 +287,7 @@ func TestTestEmailConnection_nonAdminForbidden(t *testing.T) {
 	rawKey := "non-admin-conn-test-key"
 	hash := sha256HexForTest(rawKey)
 	db.Exec(`INSERT INTO users (id, email, name, iana_timezone, is_admin) VALUES ('u3','other2@example.com','Other2','UTC',0)`)
-	db.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k3','u3','test',?,datetime('now'))`, hash)
+	db.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k3','u3','test',?,?)`, hash, dbtime.Now())
 
 	req := authReq(http.MethodPost, "/v1/settings/email/test", "", rawKey)
 	rec := httptest.NewRecorder()
diff --git a/internal/handler/event_type.go b/internal/handler/event_type.go
index 40a9e98..2bf220e 100644
--- a/internal/handler/event_type.go
+++ b/internal/handler/event_type.go
@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"strings"
 
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/uid"
 )
 
@@ -596,9 +597,10 @@ func (h *Handler) PatchEventType(w http.ResponseWriter, r *http.Request) {
 	}
 	if req.Archived != nil {
 		if *req.Archived {
-			// strftime literal (no bound value) — matches the DB's timestamp format;
-			// also force is_active off so the archived type stops taking bookings.
-			setClauses = append(setClauses, "archived_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')")
+			// Bound value in the DB's millisecond timestamp format, which is what
+			// strftime('%Y-%m-%dT%H:%M:%fZ','now') wrote here before; also force
+			// is_active off so the archived type stops taking bookings.
+			set("archived_at", dbtime.NowMilli())
 			set("is_active", 0)
 		} else {
 			setClauses = append(setClauses, "archived_at = NULL")
diff --git a/internal/handler/google_settings.go b/internal/handler/google_settings.go
index 4a5fea2..cd70949 100644
--- a/internal/handler/google_settings.go
+++ b/internal/handler/google_settings.go
@@ -9,6 +9,7 @@ import (
 
 	"github.com/calnode/calnode/internal/calendar"
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/gcal"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -98,8 +99,8 @@ func (h *Handler) PatchGoogleSettings(w http.ResponseWriter, r *http.Request) {
 		if _, err := h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET
 			  google_client_id = '', google_client_secret_enc = '',
-			  updated_at = datetime('now')
-			WHERE id = 1`); err != nil {
+			  updated_at = ?
+			WHERE id = 1`, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "google settings: clear", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -122,8 +123,8 @@ func (h *Handler) PatchGoogleSettings(w http.ResponseWriter, r *http.Request) {
 		if _, err = h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET
 			  google_client_id = ?, google_client_secret_enc = ?,
-			  updated_at = datetime('now')
-			WHERE id = 1`, req.ClientID, enc); err != nil {
+			  updated_at = ?
+			WHERE id = 1`, req.ClientID, enc, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "google settings: update", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -132,8 +133,8 @@ func (h *Handler) PatchGoogleSettings(w http.ResponseWriter, r *http.Request) {
 		if _, err := h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET
 			  google_client_id = ?,
-			  updated_at = datetime('now')
-			WHERE id = 1`, req.ClientID); err != nil {
+			  updated_at = ?
+			WHERE id = 1`, req.ClientID, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "google settings: update (keep secret)", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
diff --git a/internal/handler/google_settings_test.go b/internal/handler/google_settings_test.go
index 3d5ccdb..56b012f 100644
--- a/internal/handler/google_settings_test.go
+++ b/internal/handler/google_settings_test.go
@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/handler"
 )
 
@@ -80,7 +81,7 @@ func TestGetGoogleSettings_nonAdminForbidden(t *testing.T) {
 	rawKey := "non-admin-google-test-key"
 	hash := sha256HexForTest(rawKey)
 	database.Exec(`INSERT INTO users (id, email, name, iana_timezone, is_admin) VALUES ('u-ng','ng@example.com','NG','UTC',0)`)
-	database.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k-ng','u-ng','test',?,datetime('now'))`, hash)
+	database.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k-ng','u-ng','test',?,?)`, hash, dbtime.Now())
 
 	req := authReq(http.MethodGet, "/v1/settings/google", "", rawKey)
 	rec := httptest.NewRecorder()
@@ -245,7 +246,7 @@ func TestPatchGoogleSettings_nonAdminForbidden(t *testing.T) {
 	rawKey := "non-admin-patch-google-key"
 	hash := sha256HexForTest(rawKey)
 	database.Exec(`INSERT INTO users (id, email, name, iana_timezone, is_admin) VALUES ('u-npg','npg@example.com','NPG','UTC',0)`)
-	database.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k-npg','u-npg','test',?,datetime('now'))`, hash)
+	database.Exec(`INSERT INTO api_keys (id, user_id, name, key_hash, created_at) VALUES ('k-npg','u-npg','test',?,?)`, hash, dbtime.Now())
 
 	rec := patchGoogleSettings(t, h, `{"client_id":"evil","client_secret":"evil"}`, rawKey)
 	if rec.Code != http.StatusForbidden {
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index 59b1809..cf68ce8 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -12,6 +12,7 @@ import (
 	"github.com/calnode/calnode/internal/booking"
 	"github.com/calnode/calnode/internal/calendar"
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/livekit"
 	"github.com/calnode/calnode/internal/llm"
 	"github.com/calnode/calnode/internal/mailer"
@@ -62,7 +63,8 @@ func (h *Handler) SetLiveKit(c *livekit.Client) {
 	// is no longer tracked), and would otherwise block the idempotent guard on its room forever.
 	if c != nil {
 		if _, err := h.db.Exec(
-			`UPDATE recordings SET status = 'complete', updated_at = datetime('now') WHERE status = 'active'`); err != nil {
+			`UPDATE recordings SET status = 'complete', updated_at = ? WHERE status = 'active'`,
+			dbtime.Now()); err != nil {
 			h.logger.Warn("livekit: sweep stale recordings", "error", err)
 		}
 	}
diff --git a/internal/handler/livekit_recording.go b/internal/handler/livekit_recording.go
index 33eafb4..d8f6b37 100644
--- a/internal/handler/livekit_recording.go
+++ b/internal/handler/livekit_recording.go
@@ -11,6 +11,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/livekit"
 	"github.com/calnode/calnode/internal/uid"
 	"github.com/calnode/calnode/internal/webhook"
@@ -117,10 +118,13 @@ func (h *Handler) RecordStart(w http.ResponseWriter, r *http.Request) {
 	}
 	h.logger.InfoContext(r.Context(), "livekit: egress started", "room", room, "egress_id", egressID, "filepath", filepath)
 	bookingID := strings.TrimPrefix(room, "booking-")
+	// created_at keeps the datetime('now') shape: parseRecordingTime reads it back
+	// and consentWindow turns it into the millisecond form the consent rows use.
+	now := dbtime.Now()
 	if _, err := h.db.ExecContext(r.Context(), `
 		INSERT INTO recordings (id, booking_id, room, egress_id, status, object_key, created_at, updated_at)
-		VALUES (?, ?, ?, ?, 'active', ?, datetime('now'), datetime('now'))`,
-		uid.New(), bookingID, room, egressID, filepath); err != nil {
+		VALUES (?, ?, ?, ?, 'active', ?, ?, ?)`,
+		uid.New(), bookingID, room, egressID, filepath, now, now); err != nil {
 		h.logger.ErrorContext(r.Context(), "livekit: save recording", "error", err)
 	}
 	h.mergeRoomMeta(r.Context(), room, "recording", true) // drives the consent banner
@@ -167,8 +171,8 @@ func (h *Handler) finalizeActiveRecording(ctx context.Context, room string) {
 		h.logger.ErrorContext(ctx, "livekit: stop egress", "error", err, "egress", egressID)
 	}
 	if _, err := h.db.ExecContext(ctx,
-		`UPDATE recordings SET status = 'complete', updated_at = datetime('now')
-		 WHERE room = ? AND status = 'active'`, room); err != nil {
+		`UPDATE recordings SET status = 'complete', updated_at = ?
+		 WHERE room = ? AND status = 'active'`, dbtime.Now(), room); err != nil {
 		h.logger.ErrorContext(ctx, "livekit: close recording row", "error", err, "room", room)
 	}
 }
@@ -211,8 +215,8 @@ func (h *Handler) RecordConsent(w http.ResponseWriter, r *http.Request) {
 		VALUES (?, ?, ?, ?)
 		ON CONFLICT(room, participant_identity) DO UPDATE SET
 			name = excluded.name, decision = excluded.decision,
-			decided_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
-		room, identity, name, decision); err != nil {
+			decided_at = ?`,
+		room, identity, name, decision, dbtime.NowMilli()); err != nil {
 		h.logger.ErrorContext(r.Context(), "livekit: record consent", "error", err, "room", room)
 		h.writeError(w, http.StatusInternalServerError, "could not record consent")
 		return
@@ -603,8 +607,8 @@ func (h *Handler) LiveKitWebhook(w http.ResponseWriter, r *http.Request) {
 		}
 		if _, err := h.db.ExecContext(r.Context(), `
 			UPDATE recordings SET status = ?, object_key = COALESCE(NULLIF(?,''), object_key),
-			       duration_s = ?, updated_at = datetime('now') WHERE egress_id = ?`,
-			status, key, durSec, info.EgressID); err != nil {
+			       duration_s = ?, updated_at = ? WHERE egress_id = ?`,
+			status, key, durSec, dbtime.Now(), info.EgressID); err != nil {
 			h.logger.ErrorContext(r.Context(), "livekit: finalize recording", "error", err)
 		}
 		if info.RoomName != "" {
diff --git a/internal/handler/livekit_settings.go b/internal/handler/livekit_settings.go
index 3dbafb3..9606ccf 100644
--- a/internal/handler/livekit_settings.go
+++ b/internal/handler/livekit_settings.go
@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/livekit"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -91,7 +92,7 @@ func (h *Handler) PatchLiveKitSettings(w http.ResponseWriter, r *http.Request) {
 	if req.URL == "" {
 		if _, err := h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET livekit_url = '', livekit_api_key = '',
-			  livekit_api_secret_enc = '', updated_at = datetime('now') WHERE id = 1`); err != nil {
+			  livekit_api_secret_enc = '', updated_at = ? WHERE id = 1`, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "livekit settings: clear", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -119,15 +120,15 @@ func (h *Handler) PatchLiveKitSettings(w http.ResponseWriter, r *http.Request) {
 		}
 		if _, err = h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET livekit_url = ?, livekit_api_key = ?,
-			  livekit_api_secret_enc = ?, updated_at = datetime('now') WHERE id = 1`,
-			req.URL, req.APIKey, enc); err != nil {
+			  livekit_api_secret_enc = ?, updated_at = ? WHERE id = 1`,
+			req.URL, req.APIKey, enc, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "livekit settings: update", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
 		}
 	} else if _, err := h.db.ExecContext(r.Context(), `
 		UPDATE server_settings SET livekit_url = ?, livekit_api_key = ?,
-		  updated_at = datetime('now') WHERE id = 1`, req.URL, req.APIKey); err != nil {
+		  updated_at = ? WHERE id = 1`, req.URL, req.APIKey, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "livekit settings: update (keep secret)", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
diff --git a/internal/handler/llm_settings.go b/internal/handler/llm_settings.go
index 967505a..97bf4e8 100644
--- a/internal/handler/llm_settings.go
+++ b/internal/handler/llm_settings.go
@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/llm"
 	"github.com/calnode/calnode/internal/secret"
 )
@@ -155,8 +156,11 @@ func (h *Handler) PatchLLMSettings(w http.ResponseWriter, r *http.Request) {
 		args = append(args, v)
 	}
 	if len(set) > 0 {
+		// updated_at's placeholder trails every "col = ?" in set, so its value
+		// trails every value in args.
+		args = append(args, dbtime.Now())
 		if _, err := h.db.ExecContext(r.Context(),
-			`UPDATE server_settings SET `+strings.Join(set, ", ")+`, updated_at = datetime('now') WHERE id = 1`, args...); err != nil { // #nosec G202 -- set is built above from hardcoded "col = ?" literals only; every value is bound via args...
+			`UPDATE server_settings SET `+strings.Join(set, ", ")+`, updated_at = ? WHERE id = 1`, args...); err != nil { // #nosec G202 -- set is built above from hardcoded "col = ?" literals only; every value is bound via args...
 			h.llmDBError(w, r, err)
 			return
 		}
diff --git a/internal/handler/notetaker.go b/internal/handler/notetaker.go
index 2ef1d90..627ef26 100644
--- a/internal/handler/notetaker.go
+++ b/internal/handler/notetaker.go
@@ -7,6 +7,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/llm"
 	"github.com/calnode/calnode/internal/secret"
 	"github.com/calnode/calnode/internal/stt"
@@ -59,13 +60,18 @@ func (h *Handler) deepgramKey(ctx context.Context) string {
 // reminders/webhooks enqueue via their own paths.)
 func (h *Handler) enqueueJob(ctx context.Context, typ string, payload any) error {
 	b, _ := json.Marshal(payload)
+	// run_at keeps the datetime('now') shape it has always had here. It is
+	// deliberately not the RFC 3339 the reminder path writes: the worker's
+	// "run_at <= ?" compares text, and the space-separated form sorts before any
+	// T-separated one, which is what makes these jobs due immediately.
+	now := dbtime.Now()
 	_, err := h.db.ExecContext(ctx, `
 		INSERT INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
-		VALUES (?, ?, ?, datetime('now'), 'pending', 0, 3)
+		VALUES (?, ?, ?, ?, 'pending', 0, 3)
 		ON CONFLICT(type, payload) DO UPDATE SET
-			status = 'pending', run_at = datetime('now'), attempts = 0,
+			status = 'pending', run_at = ?, attempts = 0,
 			last_error = NULL, locked_until = NULL`,
-		uid.New(), typ, string(b))
+		uid.New(), typ, string(b), now, now)
 	return err
 }
 
@@ -212,16 +218,16 @@ func (h *Handler) summarizeBooking(ctx context.Context, bookingID string) (strin
 		_, _ = h.db.ExecContext(ctx, `
 			INSERT INTO notes (id, booking_id, content, status)
 			VALUES (?, ?, '', 'empty')
-			ON CONFLICT(booking_id) DO UPDATE SET status = 'empty', updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
-			uid.New(), bookingID)
+			ON CONFLICT(booking_id) DO UPDATE SET status = 'empty', updated_at = ?`,
+			uid.New(), bookingID, dbtime.NowMilli())
 		return "", nil
 	}
 	if _, err := h.db.ExecContext(ctx, `
 		INSERT INTO notes (id, booking_id, content, status)
 		VALUES (?, ?, ?, 'complete')
 		ON CONFLICT(booking_id) DO UPDATE SET
-			content = excluded.content, status = 'complete', updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
-		uid.New(), bookingID, content); err != nil {
+			content = excluded.content, status = 'complete', updated_at = ?`,
+		uid.New(), bookingID, content, dbtime.NowMilli()); err != nil {
 		return "", err
 	}
 	h.logger.InfoContext(ctx, "notetaker: notes generated", "booking_id", bookingID, "chars", len(content))
diff --git a/internal/handler/notetaker_http.go b/internal/handler/notetaker_http.go
index f5619c7..fb2ab6d 100644
--- a/internal/handler/notetaker_http.go
+++ b/internal/handler/notetaker_http.go
@@ -8,6 +8,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/secret"
 )
 
@@ -57,7 +58,7 @@ func (h *Handler) PatchNotetakerSettings(w http.ResponseWriter, r *http.Request)
 			v = 1
 		}
 		if _, err := h.db.ExecContext(r.Context(),
-			`UPDATE server_settings SET notetaker_enabled = ?, updated_at = datetime('now') WHERE id = 1`, v); err != nil {
+			`UPDATE server_settings SET notetaker_enabled = ?, updated_at = ? WHERE id = 1`, v, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "notetaker settings: update enabled", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -72,7 +73,7 @@ func (h *Handler) PatchNotetakerSettings(w http.ResponseWriter, r *http.Request)
 				return
 			}
 			if _, err := h.db.ExecContext(r.Context(),
-				`UPDATE server_settings SET stt_api_key_enc = ?, updated_at = datetime('now') WHERE id = 1`, enc); err != nil {
+				`UPDATE server_settings SET stt_api_key_enc = ?, updated_at = ? WHERE id = 1`, enc, dbtime.Now()); err != nil {
 				h.logger.ErrorContext(r.Context(), "notetaker settings: update key", "error", err)
 				h.writeError(w, http.StatusInternalServerError, "internal error")
 				return
diff --git a/internal/handler/storage_settings.go b/internal/handler/storage_settings.go
index 9254e6f..e636ced 100644
--- a/internal/handler/storage_settings.go
+++ b/internal/handler/storage_settings.go
@@ -5,6 +5,8 @@ import (
 	"net/http"
 	"os"
 	"strings"
+
+	"github.com/calnode/calnode/internal/dbtime"
 )
 
 // The Storage settings page surfaces both object-storage uses in one place: the Litestream DB
@@ -54,7 +56,7 @@ func (h *Handler) PatchStorageSettings(w http.ResponseWriter, r *http.Request) {
 		v = 1
 	}
 	if _, err := h.db.ExecContext(r.Context(),
-		`UPDATE server_settings SET recordings_enabled = ?, updated_at = datetime('now') WHERE id = 1`, v); err != nil {
+		`UPDATE server_settings SET recordings_enabled = ?, updated_at = ? WHERE id = 1`, v, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "storage settings: update", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
diff --git a/internal/handler/stripe_settings.go b/internal/handler/stripe_settings.go
index 003c16b..2931f35 100644
--- a/internal/handler/stripe_settings.go
+++ b/internal/handler/stripe_settings.go
@@ -7,6 +7,7 @@ import (
 	"net/http"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/secret"
 	"github.com/calnode/calnode/internal/stripe"
 )
@@ -98,8 +99,8 @@ func (h *Handler) PatchStripeSettings(w http.ResponseWriter, r *http.Request) {
 		if _, err := h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET
 			  stripe_secret_key_enc = '', stripe_publishable_key = '', stripe_webhook_secret_enc = '',
-			  updated_at = datetime('now')
-			WHERE id = 1`); err != nil {
+			  updated_at = ?
+			WHERE id = 1`, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "stripe settings: clear", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -112,8 +113,8 @@ func (h *Handler) PatchStripeSettings(w http.ResponseWriter, r *http.Request) {
 	// Update publishable key (plain — it's a public value) when provided.
 	if req.PublishableKey != nil {
 		if _, err := h.db.ExecContext(r.Context(),
-			`UPDATE server_settings SET stripe_publishable_key = ?, updated_at = datetime('now') WHERE id = 1`,
-			*req.PublishableKey); err != nil {
+			`UPDATE server_settings SET stripe_publishable_key = ?, updated_at = ? WHERE id = 1`,
+			*req.PublishableKey, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "stripe settings: update pub key", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -128,7 +129,7 @@ func (h *Handler) PatchStripeSettings(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 		if _, err := h.db.ExecContext(r.Context(),
-			`UPDATE server_settings SET stripe_secret_key_enc = ?, updated_at = datetime('now') WHERE id = 1`, enc); err != nil {
+			`UPDATE server_settings SET stripe_secret_key_enc = ?, updated_at = ? WHERE id = 1`, enc, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "stripe settings: update secret key", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -142,7 +143,7 @@ func (h *Handler) PatchStripeSettings(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 		if _, err := h.db.ExecContext(r.Context(),
-			`UPDATE server_settings SET stripe_webhook_secret_enc = ?, updated_at = datetime('now') WHERE id = 1`, enc); err != nil {
+			`UPDATE server_settings SET stripe_webhook_secret_enc = ?, updated_at = ? WHERE id = 1`, enc, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "stripe settings: update webhook secret", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
diff --git a/internal/handler/tracking_settings.go b/internal/handler/tracking_settings.go
index 9a29f77..87a3e9a 100644
--- a/internal/handler/tracking_settings.go
+++ b/internal/handler/tracking_settings.go
@@ -6,6 +6,8 @@ import (
 	"net/http"
 	"regexp"
 	"strings"
+
+	"github.com/calnode/calnode/internal/dbtime"
 )
 
 // Google tag ID formats. The ID is interpolated into a <script> URL, so it MUST be validated
@@ -189,10 +191,10 @@ func (h *Handler) PatchTrackingSettings(w http.ResponseWriter, r *http.Request)
 	if _, err := h.db.ExecContext(r.Context(), `
 		UPDATE server_settings SET head_html = ?, tracking_csp_allow = ?,
 		       datalayer_enabled = ?, datalayer_fields = ?,
-		       gtm_container_id = ?, ga4_measurement_id = ?, updated_at = datetime('now')
+		       gtm_container_id = ?, ga4_measurement_id = ?, updated_at = ?
 		WHERE id = 1`,
 		req.HeadHTML, strings.TrimSpace(req.CSPAllow), enabled, string(fieldsJSON),
-		gtmID, ga4ID); err != nil {
+		gtmID, ga4ID, dbtime.Now()); err != nil {
 		h.logger.ErrorContext(r.Context(), "tracking settings: update", "error", err)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
diff --git a/internal/handler/zoom_settings.go b/internal/handler/zoom_settings.go
index 91033db..db5e0e9 100644
--- a/internal/handler/zoom_settings.go
+++ b/internal/handler/zoom_settings.go
@@ -8,6 +8,7 @@ import (
 	"net/http"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/secret"
 	"github.com/calnode/calnode/internal/zoom"
 )
@@ -97,8 +98,8 @@ func (h *Handler) PatchZoomSettings(w http.ResponseWriter, r *http.Request) {
 		if _, err := h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET
 			  zoom_client_id = '', zoom_client_secret_enc = '',
-			  updated_at = datetime('now')
-			WHERE id = 1`); err != nil {
+			  updated_at = ?
+			WHERE id = 1`, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "zoom settings: clear", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -118,8 +119,8 @@ func (h *Handler) PatchZoomSettings(w http.ResponseWriter, r *http.Request) {
 		if _, err = h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET
 			  zoom_client_id = ?, zoom_client_secret_enc = ?,
-			  updated_at = datetime('now')
-			WHERE id = 1`, req.ClientID, enc); err != nil {
+			  updated_at = ?
+			WHERE id = 1`, req.ClientID, enc, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "zoom settings: update", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
@@ -128,8 +129,8 @@ func (h *Handler) PatchZoomSettings(w http.ResponseWriter, r *http.Request) {
 		if _, err := h.db.ExecContext(r.Context(), `
 			UPDATE server_settings SET
 			  zoom_client_id = ?,
-			  updated_at = datetime('now')
-			WHERE id = 1`, req.ClientID); err != nil {
+			  updated_at = ?
+			WHERE id = 1`, req.ClientID, dbtime.Now()); err != nil {
 			h.logger.ErrorContext(r.Context(), "zoom settings: update (keep secret)", "error", err)
 			h.writeError(w, http.StatusInternalServerError, "internal error")
 			return
diff --git a/internal/keyvault/keyvault.go b/internal/keyvault/keyvault.go
index c16b3f4..4693c2b 100644
--- a/internal/keyvault/keyvault.go
+++ b/internal/keyvault/keyvault.go
@@ -24,6 +24,7 @@ import (
 	"log/slog"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"golang.org/x/crypto/argon2"
 )
 
@@ -224,16 +225,17 @@ func insertKeystoreRow(db *db.DB, label string, dek [32]byte, secret string) err
 	if err != nil {
 		return fmt.Errorf("keyvault: wrap DEK for %s: %w", label, err)
 	}
+	now := dbtime.Now()
 	_, err = db.Exec(`
 		INSERT INTO crypto_keystore
 		  (label, wrapped_dek, kdf, kdf_salt, kdf_params, dek_version, created_at, updated_at)
-		VALUES (?, ?, ?, ?, ?, 1, datetime('now'), datetime('now'))
+		VALUES (?, ?, ?, ?, ?, 1, ?, ?)
 		ON CONFLICT(label) DO UPDATE SET
 		  wrapped_dek = excluded.wrapped_dek,
 		  kdf_salt    = excluded.kdf_salt,
 		  kdf_params  = excluded.kdf_params,
 		  updated_at  = excluded.updated_at`,
-		label, wrapped, kdfArgon2id, salt, string(paramsJSON))
+		label, wrapped, kdfArgon2id, salt, string(paramsJSON), now, now)
 	return err
 }
 
diff --git a/internal/server/server.go b/internal/server/server.go
index c8289c5..c17168d 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -20,6 +20,7 @@ import (
 	"github.com/calnode/calnode/internal/secret"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/stripe"
 	"github.com/calnode/calnode/internal/webhook"
 	"github.com/calnode/calnode/internal/worker"
@@ -564,11 +565,11 @@ func seedSMTPToDB(db *db.DB, cfg *config.Config, encKey [32]byte, logger *slog.L
 		  smtp_host = ?, smtp_port = ?, smtp_user = ?, smtp_pass_enc = ?,
 		  smtp_tls = ?, smtp_starttls = ?,
 		  email_from = ?, email_from_name = ?,
-		  updated_at = datetime('now')
+		  updated_at = ?
 		WHERE id = 1 AND smtp_host = ''`,
 		cfg.SMTPHost, cfg.SMTPPort, cfg.SMTPUser, passEnc,
 		boolToInt(cfg.SMTPTLS), boolToInt(cfg.SMTPStartTLS),
-		cfg.EmailFrom, cfg.EmailFromName)
+		cfg.EmailFrom, cfg.EmailFromName, dbtime.Now())
 	if err != nil {
 		logger.Warn("mailer: seed to database failed", "error", err)
 		return

From e67552088f12575b6f77de5230410d7b43496b84 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 03:41:22 -0400
Subject: [PATCH 06/51] booking: hold an advisory lock on the host across the
 overlap check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ARCHITECTURE §17 says the app-level double-booking check is free of TOCTOU races
because SetMaxOpenConns(1) serialises every transaction. That is true and it is a
SQLite property. On a Postgres pool two overlapping bookings can both read "host
is free" and both insert, and idx_bookings_no_double is UNIQUE(host_id, start_at)
so it only catches an IDENTICAL start time — 10:00-10:30 against 10:15-10:45 are
two distinct keys and both inserts satisfy it.

lockHosts takes pg_advisory_xact_lock on every host whose availability the
transaction is about to decide, before the first hostBusy read. The lock is
released by the transaction ending, so there is no unlock to forget and no leak
down the several early-return paths these functions have. Per host rather than
global, so bookings for different hosts stay concurrent — otherwise this would
just reinstate the single writer it replaces. On SQLite it returns immediately and
nothing changes.

The key is SHA-256 of "calnode:booking:host:" + id, first eight bytes big-endian
as int64. Derived in Go rather than with hashtext() so it is readable and testable
from Go, and domain-separated so a later advisory lock on some other entity cannot
collide by hashing the same raw id. Ids are sorted and deduplicated on a COPY
before locking: two transactions needing the same two hosts in opposite orders
would deadlock, and Create's HostIDs arrive in round-robin priority order, which
decides who gets the booking.

Three call sites, where the packet named two. ReassignHost has the identical
check-then-write shape — hostBusy's own doc comment names all three write paths —
and leaving it out would have left a known double-booking hole. Reschedule locks
the primary host BEFORE reading booking_hosts rather than after, because a
concurrent ReassignHost holds that same key, and that ordering is what stops a
reassignment committing between the host-list read and the UPDATE.

isUniqueViolation now matches SQLSTATE 23505 as well as SQLite's message text. It
was a substring match on "UNIQUE constraint failed", so on Postgres the index
backstop would have surfaced as a 500 rather than ErrDoubleBooked. SQLSTATE
because the message is localised by the server's lc_messages.

Measured against PostgreSQL 17, 40 rounds of two goroutines racing overlapping
slots: with the lock, 40 created / 40 conflicts / 0 overlapping pairs in the
database. With the lock disabled, 79 created / 1 conflict / 39 overlapping pairs.
The unlocked run is why the index cannot be described as a sufficient guard: it
caught one race in forty.

internal/dbtest arrives with this rather than with the docs commit, because the
committed version of that test needs it. Each test gets its own
calnode_test_<random> schema via search_path in the DSN, dropped on cleanup; the
test that asserts the isolation actually reaches the server is in that package,
because a search_path that silently stopped being forwarded would migrate every
package into public and read as flakiness.
---
 PROGRESS.md                                |  52 +++++++-
 internal/booking/concurrency_test.go       |  93 ++++++++++++++
 internal/booking/hostlock.go               |  78 +++++++++++
 internal/booking/hostlock_internal_test.go |  49 +++++++
 internal/booking/service.go                |  49 ++++++-
 internal/dbtest/dbtest.go                  | 142 +++++++++++++++++++++
 internal/dbtest/dbtest_test.go             |  76 +++++++++++
 7 files changed, 536 insertions(+), 3 deletions(-)
 create mode 100644 internal/booking/concurrency_test.go
 create mode 100644 internal/booking/hostlock.go
 create mode 100644 internal/booking/hostlock_internal_test.go
 create mode 100644 internal/dbtest/dbtest.go
 create mode 100644 internal/dbtest/dbtest_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index d91b79f..c668eeb 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -49,9 +49,57 @@ clients verbatim, so folding them into one would change SQLite's stored bytes.
 
 Gates: `go build ./...`, `go vet ./...`, `gofmt -l`, `go test ./...` clean on SQLite.
 
-## Boundary 3 — advisory lock replacing the single-writer guarantee — TODO
+## Boundary 3 — advisory lock replacing the single-writer guarantee — DONE
 
-## Boundary 4 — Postgres test harness, docs, CI — TODO
+`internal/booking/hostlock.go`. `lockHosts` takes `pg_advisory_xact_lock` on each
+host whose availability the transaction is about to decide, at the start of the
+transaction and before the first `hostBusy` read. On SQLite it returns immediately
+and the `SetMaxOpenConns(1)` guarantee stands untouched.
+
+- **Key derivation**: `int64(binary.BigEndian.Uint64(sha256.Sum256("calnode:booking:host:" + hostID)[:8]))`.
+  Domain-separated so a future advisory lock on another entity cannot collide by
+  hashing the same raw id. A collision between two hosts would cost an unnecessary
+  serialisation, never a wrong answer, so stability and spread are what matter.
+  `hostlock_internal_test.go` pins two values computed independently of the code.
+- **Deadlock**: ids are sorted and deduplicated on a copy before locking, so two
+  transactions needing the same pair cannot take them in opposite orders. The copy
+  matters because `Create`'s `HostIDs` arrive in round-robin priority order.
+- **Three call sites, not two.** `Create` and `Reschedule` as specified, plus
+  `ReassignHost`, which has the identical check-then-write shape (`hostBusy`'s own
+  doc names all three). Leaving it out would have left a known hole.
+- `Reschedule` locks the primary host *before* reading `booking_hosts`, not after: a
+  concurrent `ReassignHost` holds that same key, and that ordering is what stops a
+  reassignment committing between the host-list read and the `UPDATE`.
+- `isUniqueViolation` now recognises Postgres by SQLSTATE 23505 (`pgconn.PgError`)
+  as well as SQLite by message. Without it the index's backstop returned a 500
+  instead of `ErrDoubleBooked` on Postgres.
+- The materialise-into-a-slice patterns in `Reschedule` and the calendar reconciler
+  are untouched; they are still required on SQLite.
+
+**Measured, against the live PostgreSQL 17 on 127.0.0.1:55432**, with a temporary
+hand-written minimal schema because `migrations/postgres` does not exist yet. Two
+goroutines race overlapping-but-not-identical slots (10:00–10:30 against
+10:15–10:45, so `idx_bookings_no_double` cannot catch it), 40 rounds:
+
+| | created | conflicts | overlapping pairs in the DB |
+|---|---|---|---|
+| lock in place | 40 | 40 | **0** |
+| lock disabled | 79 | 1 | **39** |
+
+The negative control is the point: unlocked, the partial unique index caught 1 of
+40. The committed test (`internal/booking/concurrency_test.go`) is the same race
+through `dbtest.RequirePostgres`, and skips on SQLite saying the single-connection
+pool makes the race impossible.
+
+## Boundary 4 — Postgres test harness, docs, CI — IN PROGRESS
+
+`internal/dbtest` landed with Boundary 3 because the concurrency test needs it.
+`Open(t)` returns in-memory SQLite unless `CALNODE_TEST_POSTGRES_DSN` is set, in
+which case each test gets its own `calnode_test_<random>` schema, created before
+the migrations and dropped after. Isolation rides on `search_path` in the DSN,
+which `dbtest_test.go` verifies against a live server rather than assuming
+(`TestSearchPathIsolation` passes; it also asserts the schema is invisible from the
+default path).
 
 ## Blocked on the database layer
 
diff --git a/internal/booking/concurrency_test.go b/internal/booking/concurrency_test.go
new file mode 100644
index 0000000..075cf64
--- /dev/null
+++ b/internal/booking/concurrency_test.go
@@ -0,0 +1,93 @@
+package booking_test
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/calnode/calnode/internal/booking"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// TestCreate_concurrentPartialOverlap_postgres is the test for the guarantee
+// pg_advisory_xact_lock replaces.
+//
+// The two slots deliberately OVERLAP without SHARING a start time. That is the case
+// no index catches: idx_bookings_no_double is UNIQUE(host_id, start_at), so 10:00
+// and 10:15 are two distinct keys and both inserts satisfy it. The only thing
+// standing between them is hostBusy's read, and on a multi-connection pool two
+// transactions can both take that read before either writes. If the lock is not
+// held, this test double-books.
+//
+// It is skipped on SQLite, where the race is not reachable: db.SetMaxOpenConns(1)
+// means the second transaction cannot begin until the first has committed.
+func TestCreate_concurrentPartialOverlap_postgres(t *testing.T) {
+	database := dbtest.RequirePostgres(t)
+	svc := booking.New(database)
+	hostID := seedHost(t, database)
+	etID := seedEventType(t, database, hostID)
+
+	// Enough rounds that a lost race is very unlikely to go unseen. One round is
+	// not evidence: two goroutines miss each other's window often enough that an
+	// unlocked build passes a single round most of the time.
+	const rounds = 40
+
+	for round := 0; round < rounds; round++ {
+		// A fresh, non-overlapping window per round, so a round is independent of
+		// every earlier round's surviving booking.
+		base := slot(0, 0).Add(time.Duration(round) * time.Hour)
+		first := [2]time.Time{base, base.Add(30 * time.Minute)}
+		second := [2]time.Time{base.Add(15 * time.Minute), base.Add(45 * time.Minute)}
+
+		var wg sync.WaitGroup
+		errs := make([]error, 2)
+		start := make(chan struct{})
+		for i, window := range [2][2]time.Time{first, second} {
+			wg.Add(1)
+			go func(i int, from, to time.Time) {
+				defer wg.Done()
+				<-start // line both up so the transactions truly overlap
+				_, errs[i] = svc.Create(context.Background(), booking.CreateParams{
+					EventTypeID: etID,
+					HostIDs:     []string{hostID},
+					StartAt:     from,
+					EndAt:       to,
+					Organizer: booking.Attendee{
+						Name:  "Alice",
+						Email: "alice@example.com",
+					},
+				})
+			}(i, window[0], window[1])
+		}
+		close(start)
+		wg.Wait()
+
+		var created int
+		for i, err := range errs {
+			switch {
+			case err == nil:
+				created++
+			case errors.Is(err, booking.ErrDoubleBooked):
+				// the expected loser
+			default:
+				t.Fatalf("round %d: booking %d: unexpected error: %v", round, i, err)
+			}
+		}
+		if created != 1 {
+			t.Fatalf("round %d: %d of 2 overlapping bookings were created; want exactly 1 (errors: %v, %v)",
+				round, created, errs[0], errs[1])
+		}
+	}
+
+	// And the database agrees: one booking per round, never two in a window.
+	var n int
+	if err := database.QueryRow(
+		`SELECT COUNT(*) FROM bookings WHERE host_id = ? AND status != 'cancelled'`, hostID).Scan(&n); err != nil {
+		t.Fatalf("count bookings: %v", err)
+	}
+	if n != rounds {
+		t.Errorf("bookings for host = %d; want %d (one per round)", n, rounds)
+	}
+}
diff --git a/internal/booking/hostlock.go b/internal/booking/hostlock.go
new file mode 100644
index 0000000..678cc10
--- /dev/null
+++ b/internal/booking/hostlock.go
@@ -0,0 +1,78 @@
+package booking
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/binary"
+	"fmt"
+	"slices"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// hostLockDomain prefixes every id fed to the hash below, so a future advisory
+// lock on some other entity cannot collide with a host's key by hashing the same
+// raw string.
+const hostLockDomain = "calnode:booking:host:"
+
+// lockHosts serialises the check-then-write window for a set of hosts, for the
+// remainder of tx.
+//
+// Create, Reschedule and ReassignHost all read "is this host busy at this time?"
+// and then write on the answer. On SQLite that is free of TOCTOU races without any
+// locking, because the pool is a single connection (db.SetMaxOpenConns(1), see
+// internal/db/db.go) and transactions therefore cannot interleave at all. A
+// Postgres pool has many connections: two overlapping bookings can both read
+// "free" and both insert, and the partial unique index
+// idx_bookings_no_double(host_id, start_at) only catches an identical start time,
+// not a partial overlap. That is exactly the gap the app-level check was never
+// asked to close on its own.
+//
+// pg_advisory_xact_lock is held until the transaction commits or rolls back, so
+// there is no unlock call to forget and no leak when a caller returns early — which
+// every guard in these functions does. Locking per host rather than once globally
+// keeps bookings for different hosts concurrent, which is the whole point of moving
+// off the single connection.
+//
+// On SQLite this is a no-op and the existing guarantee stands unchanged.
+func lockHosts(ctx context.Context, tx *db.Tx, hostIDs ...string) error {
+	if tx.Dialect() != db.DialectPostgres {
+		return nil
+	}
+
+	// Sorted and deduplicated. Two transactions that needed the same two hosts in
+	// opposite orders would otherwise deadlock, and Postgres resolves a deadlock by
+	// killing one of them — a 500 on a booking that should have been a 409 or a
+	// success. Sorting is done on a copy: Create's HostIDs arrive in round-robin
+	// priority order and that order decides who gets the booking.
+	ids := slices.Clone(hostIDs)
+	slices.Sort(ids)
+	ids = slices.Compact(ids)
+
+	for _, id := range ids {
+		if id == "" {
+			continue
+		}
+		if _, err := tx.ExecContext(ctx,
+			`SELECT pg_advisory_xact_lock(?)`, hostLockKey(id)); err != nil {
+			return fmt.Errorf("booking: lock host %s: %w", id, err)
+		}
+	}
+	return nil
+}
+
+// hostLockKey maps a host id onto the single int64 key pg_advisory_xact_lock takes.
+//
+// SHA-256 of the domain-separated id, with the first eight bytes read big-endian as
+// a signed integer. Deriving it in Go rather than with the engine's hashtext() keeps
+// the derivation readable and testable from Go, and means the value arrives as an
+// ordinary bound parameter.
+//
+// Two distinct hosts landing on the same key would cost an unnecessary
+// serialisation between two unrelated bookings, never a wrong answer, so what this
+// needs is stability and a good spread rather than cryptographic strength. SHA-256
+// is used because this package already imports it for manage tokens.
+func hostLockKey(hostID string) int64 {
+	sum := sha256.Sum256([]byte(hostLockDomain + hostID))
+	return int64(binary.BigEndian.Uint64(sum[:8]))
+}
diff --git a/internal/booking/hostlock_internal_test.go b/internal/booking/hostlock_internal_test.go
new file mode 100644
index 0000000..eb8fce0
--- /dev/null
+++ b/internal/booking/hostlock_internal_test.go
@@ -0,0 +1,49 @@
+package booking
+
+import (
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// TestHostLockKey pins the derivation. The key must not move between processes or
+// releases: two Calnode instances sharing one Postgres have to derive the same key
+// for the same host, or they take different locks and serialise against nothing.
+//
+// The expected values were computed independently of this code (SHA-256 of
+// "calnode:booking:host:" + id, first eight bytes big-endian as a signed integer),
+// so this fails if the implementation drifts rather than agreeing with itself.
+func TestHostLockKey(t *testing.T) {
+	cases := map[string]int64{
+		"host-42": 7118598067704648523,
+		"host-43": 2949734679630933584,
+	}
+	for id, want := range cases {
+		if got := hostLockKey(id); got != want {
+			t.Errorf("hostLockKey(%q) = %d; want %d — the derivation changed, which desynchronises running instances",
+				id, got, want)
+		}
+	}
+}
+
+// TestLockHosts_sqliteIsNoOp records the other half of the design: SQLite already
+// has the guarantee, so the lock must not be attempted there. pg_advisory_xact_lock
+// does not exist in SQLite, so if this ever started issuing the statement the error
+// would be immediate.
+func TestLockHosts_sqliteIsNoOp(t *testing.T) {
+	h, err := db.OpenDB("sqlite://:memory:")
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	defer h.Close()
+
+	tx, err := h.Begin()
+	if err != nil {
+		t.Fatalf("begin: %v", err)
+	}
+	defer tx.Rollback() //nolint:errcheck
+
+	if err := lockHosts(t.Context(), tx, "a", "b", "a", ""); err != nil {
+		t.Errorf("lockHosts on SQLite returned %v; want nil (it must be a no-op there)", err)
+	}
+}
diff --git a/internal/booking/service.go b/internal/booking/service.go
index 725e7a3..888162d 100644
--- a/internal/booking/service.go
+++ b/internal/booking/service.go
@@ -13,6 +13,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/jackc/pgx/v5/pgconn"
+
 	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/uid"
 )
@@ -46,6 +48,17 @@ func (s *Service) Create(ctx context.Context, p CreateParams) (*Booking, error)
 	}
 	defer tx.Rollback() //nolint:errcheck
 
+	// Before the first overlap read: every host whose availability this
+	// transaction is about to decide on. See lockHosts — on SQLite it does
+	// nothing, on Postgres it is what makes the checks below race-free.
+	lockIDs := make([]string, 0, len(p.HostIDs)+len(p.RequiredHosts)+len(p.OptionalHosts))
+	lockIDs = append(lockIDs, p.HostIDs...)
+	lockIDs = append(lockIDs, p.RequiredHosts...)
+	lockIDs = append(lockIDs, p.OptionalHosts...)
+	if err := lockHosts(ctx, tx, lockIDs...); err != nil {
+		return nil, err
+	}
+
 	now := time.Now().UTC().Format(time.RFC3339Nano)
 
 	// Select hosts. Round-robin picks one *free* candidate from the rotation pool
@@ -450,6 +463,15 @@ func (s *Service) Reschedule(ctx context.Context, bookingID string, newStart, ne
 		return nil, ErrAlreadyCancelled
 	}
 
+	// The primary host is locked before the host list is read, not after. A
+	// concurrent ReassignHost locks the booking's current primary too, so holding it
+	// here is what stops that reassignment committing between this read of
+	// booking_hosts and the UPDATE below — which would move the booking to a host
+	// whose availability was never checked.
+	if err := lockHosts(ctx, tx, b.HostID); err != nil {
+		return nil, err
+	}
+
 	// Every host on this booking keeps their seat through a reschedule, so each
 	// must be free at the new time — not just the primary. Read the host list
 	// fully before the per-host overlap queries (single-connection pool).
@@ -470,6 +492,12 @@ func (s *Service) Reschedule(ctx context.Context, bookingID string, newStart, ne
 	if len(hostIDs) == 0 { // legacy booking with no booking_hosts rows
 		hostIDs = []string{b.HostID}
 	}
+	// Now the rest of the seat holders, still before any overlap check. Re-locking
+	// the primary is free: an advisory lock already held by this transaction is
+	// re-entrant and is released once, at commit.
+	if err := lockHosts(ctx, tx, hostIDs...); err != nil {
+		return nil, err
+	}
 	for _, hid := range hostIDs {
 		busy, err := hostBusy(ctx, tx, hid, startStr, endStr, bookingID)
 		if err != nil {
@@ -528,6 +556,13 @@ func (s *Service) ReassignHost(ctx context.Context, bookingID, newHostID string)
 	startStr := b.StartAt.UTC().Format(time.RFC3339Nano)
 	endStr := b.EndAt.UTC().Format(time.RFC3339Nano)
 
+	// Both hosts: the new one because its availability is being decided, the old
+	// one because a concurrent Reschedule of this booking holds that same key and
+	// must not interleave with the host change.
+	if err := lockHosts(ctx, tx, b.HostID, newHostID); err != nil {
+		return nil, err
+	}
+
 	// The new host must be free at this time across everything they attend.
 	busy, err := hostBusy(ctx, tx, newHostID, startStr, endStr, bookingID)
 	if err != nil {
@@ -653,7 +688,19 @@ func scanBooking(s scanner) (*Booking, error) {
 	return &b, nil
 }
 
-// isUniqueViolation reports whether err is a SQLite UNIQUE constraint failure.
+// isUniqueViolation reports whether err is a unique-constraint violation — on this
+// booking path, idx_bookings_no_double rejecting an exact start-time collision that
+// the app-level overlap check did not catch. Both engines are recognised: Postgres
+// by SQLSTATE 23505, which is the only stable handle on it (the message text is
+// localised by the server's lc_messages), and SQLite by its message, which is what
+// modernc.org/sqlite surfaces.
 func isUniqueViolation(err error) bool {
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) {
+		return pgErr.Code == pgUniqueViolation
+	}
 	return strings.Contains(err.Error(), "UNIQUE constraint failed")
 }
+
+// pgUniqueViolation is PostgreSQL's SQLSTATE for unique_violation.
+const pgUniqueViolation = "23505"
diff --git a/internal/dbtest/dbtest.go b/internal/dbtest/dbtest.go
new file mode 100644
index 0000000..7610709
--- /dev/null
+++ b/internal/dbtest/dbtest.go
@@ -0,0 +1,142 @@
+// Package dbtest opens a migrated database for a test, on whichever engine the
+// environment selects.
+//
+// Unset CALNODE_TEST_POSTGRES_DSN — the default, and what upstream CI and every
+// other contributor sees — means in-memory SQLite, exactly as before. Set it, and
+// the same tests run against that PostgreSQL server, each in a schema of its own
+// that is created before the migrations and dropped afterwards. Nothing here changes
+// what a test asserts; it changes which engine has to satisfy it.
+package dbtest
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"net/url"
+	"os"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// DSNEnv names the environment variable that switches the suite onto PostgreSQL.
+const DSNEnv = "CALNODE_TEST_POSTGRES_DSN"
+
+// PostgresDSN returns the configured PostgreSQL DSN, or "" when the suite should
+// run on SQLite.
+func PostgresDSN() string { return os.Getenv(DSNEnv) }
+
+// Open returns a migrated handle for t, on Postgres when DSNEnv is set and on
+// in-memory SQLite otherwise. The handle is closed when t finishes.
+func Open(t *testing.T) *db.DB {
+	t.Helper()
+	if dsn := PostgresDSN(); dsn != "" {
+		return openPostgres(t, dsn)
+	}
+	return openSQLite(t)
+}
+
+// RequirePostgres returns a migrated Postgres handle, skipping t when DSNEnv is
+// unset. For the tests that are only meaningful on Postgres — a race the SQLite
+// pool makes impossible, say.
+func RequirePostgres(t *testing.T) *db.DB {
+	t.Helper()
+	dsn := PostgresDSN()
+	if dsn == "" {
+		t.Skipf("%s is not set; nothing to run against PostgreSQL", DSNEnv)
+	}
+	return openPostgres(t, dsn)
+}
+
+func openSQLite(t *testing.T) *db.DB {
+	t.Helper()
+	h, err := db.OpenDB("sqlite://:memory:")
+	if err != nil {
+		t.Fatalf("dbtest: open sqlite: %v", err)
+	}
+	t.Cleanup(func() { h.Close() })
+	if err := h.Migrate(); err != nil {
+		t.Fatalf("dbtest: migrate sqlite: %v", err)
+	}
+	return h
+}
+
+// openPostgres gives t its own schema on the shared server.
+//
+// A schema rather than a database: CREATE DATABASE cannot run inside a
+// transaction, takes seconds on a busy server, and needs rights a CI service
+// container may not grant the test role. A schema is one statement, isolates
+// tables and goose's own bookkeeping equally well, and disappears whole with
+// DROP ... CASCADE. Everything reaches it through search_path on the connection,
+// so no query in the tree needs to name it.
+func openPostgres(t *testing.T, dsn string) *db.DB {
+	t.Helper()
+
+	schema := "calnode_test_" + randomSuffix(t)
+
+	// A second handle on the default search_path, kept open only to create and drop
+	// the schema: the drop cannot run through a connection whose search_path points
+	// at the schema being dropped.
+	admin, err := db.OpenDB(dsn)
+	if err != nil {
+		t.Fatalf("dbtest: open postgres (admin): %v", err)
+	}
+	if _, err := admin.Exec(`CREATE SCHEMA ` + quoteIdent(schema)); err != nil {
+		admin.Close()
+		t.Fatalf("dbtest: create schema %s: %v", schema, err)
+	}
+	// Registered first, so it runs last: the schema is dropped after the handle
+	// below has been closed.
+	t.Cleanup(func() {
+		defer admin.Close()
+		if _, err := admin.Exec(`DROP SCHEMA ` + quoteIdent(schema) + ` CASCADE`); err != nil {
+			t.Errorf("dbtest: drop schema %s: %v", schema, err)
+		}
+	})
+
+	h, err := db.OpenDB(withSearchPath(t, dsn, schema))
+	if err != nil {
+		t.Fatalf("dbtest: open postgres: %v", err)
+	}
+	t.Cleanup(func() { h.Close() })
+
+	if err := h.Migrate(); err != nil {
+		t.Fatalf("dbtest: migrate postgres: %v", err)
+	}
+	return h
+}
+
+// withSearchPath returns dsn with search_path pointed at schema. pgx passes
+// unrecognised query parameters through as PostgreSQL runtime parameters, so this
+// is the whole of the isolation: goose writes goose_db_version there, the
+// migrations create their tables there, and every unqualified name in the tree
+// resolves there.
+func withSearchPath(t *testing.T, dsn, schema string) string {
+	t.Helper()
+	u, err := url.Parse(dsn)
+	if err != nil {
+		t.Fatalf("dbtest: parse %s: %v", DSNEnv, err)
+	}
+	q := u.Query()
+	q.Set("search_path", schema)
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+// randomSuffix keeps concurrent runs — two packages under `go test ./...`, or two
+// CI jobs against one server — out of each other's schemas.
+func randomSuffix(t *testing.T) string {
+	t.Helper()
+	b := make([]byte, 8)
+	if _, err := rand.Read(b); err != nil {
+		t.Fatalf("dbtest: random schema name: %v", err)
+	}
+	return hex.EncodeToString(b)
+}
+
+// quoteIdent quotes a generated schema name. The names are hex from the line
+// above, so this is belt and braces rather than a defence — but a schema name
+// interpolated into DDL unquoted is a bad habit to leave lying around for the next
+// person who passes something else in.
+func quoteIdent(name string) string {
+	return `"` + name + `"`
+}
diff --git a/internal/dbtest/dbtest_test.go b/internal/dbtest/dbtest_test.go
new file mode 100644
index 0000000..25f188c
--- /dev/null
+++ b/internal/dbtest/dbtest_test.go
@@ -0,0 +1,76 @@
+package dbtest
+
+import (
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// TestSearchPathIsolation checks the mechanism openPostgres relies on, without
+// going through it: that a search_path in the DSN really does land unqualified
+// objects in the per-test schema, and that they are invisible from the default
+// path. If pgx ever stopped forwarding the parameter, openPostgres would silently
+// migrate into the public schema and two packages would fight over one set of
+// tables — which reads as flaky tests, not as a broken harness.
+func TestSearchPathIsolation(t *testing.T) {
+	dsn := PostgresDSN()
+	if dsn == "" {
+		t.Skipf("%s is not set", DSNEnv)
+	}
+
+	schema := "calnode_test_" + randomSuffix(t)
+
+	admin, err := db.OpenDB(dsn)
+	if err != nil {
+		t.Fatalf("open admin: %v", err)
+	}
+	defer admin.Close()
+	if _, err := admin.Exec(`CREATE SCHEMA ` + quoteIdent(schema)); err != nil {
+		t.Fatalf("create schema: %v", err)
+	}
+	defer func() {
+		if _, err := admin.Exec(`DROP SCHEMA ` + quoteIdent(schema) + ` CASCADE`); err != nil {
+			t.Errorf("drop schema: %v", err)
+		}
+	}()
+
+	scoped, err := db.OpenDB(withSearchPath(t, dsn, schema))
+	if err != nil {
+		t.Fatalf("open scoped: %v", err)
+	}
+	defer scoped.Close()
+
+	var got string
+	if err := scoped.QueryRow(`SELECT current_schema()`).Scan(&got); err != nil {
+		t.Fatalf("current_schema: %v", err)
+	}
+	if got != schema {
+		t.Fatalf("current_schema() = %q; want %q — search_path did not reach the server", got, schema)
+	}
+
+	if _, err := scoped.Exec(`CREATE TABLE isolated (id text)`); err != nil {
+		t.Fatalf("create table: %v", err)
+	}
+	var visible int
+	if err := admin.QueryRow(
+		`SELECT COUNT(*) FROM pg_tables WHERE schemaname = current_schema() AND tablename = 'isolated'`).
+		Scan(&visible); err != nil {
+		t.Fatalf("count on default path: %v", err)
+	}
+	if visible != 0 {
+		t.Errorf("table 'isolated' is visible on the default search_path; the schema is not isolating anything")
+	}
+}
+
+// TestOpen returns a handle that has been migrated, on whichever engine is
+// configured. goose's bookkeeping table is the engine-independent proof.
+func TestOpen(t *testing.T) {
+	h := Open(t)
+	var n int
+	if err := h.QueryRow(`SELECT COUNT(*) FROM goose_db_version`).Scan(&n); err != nil {
+		t.Fatalf("goose_db_version: %v", err)
+	}
+	if n == 0 {
+		t.Error("goose_db_version is empty; Open returned an unmigrated handle")
+	}
+}

From c1478c1a627dfcee4f8fae2404e5e473fdf97bf7 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 03:45:21 -0400
Subject: [PATCH 07/51] test,docs,ci: run the suite against PostgreSQL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

22 test helpers across 18 files moved from db.OpenDB("sqlite://:memory:") +
Migrate() to dbtest.Open(t), so which engine the suite exercises is an
environment variable rather than 22 hardcoded DSNs. With
CALNODE_TEST_POSTGRES_DSN unset — every local run, and the existing CI job —
nothing changes: it is the same in-memory SQLite as before.

Four helpers stay on SQLite deliberately: dbtime_test pins SQLite's own timestamp
output, hostlock_internal_test asserts the advisory lock is a no-op there,
connstore/destination_test opens the bare driver against a bespoke fragment
schema, and two health_test cases want an UNMIGRATED database. keyvault_test
keeps its shared-cache DSN, which it has for a reason.

ARCHITECTURE §4 is amended rather than extended, because a new section would have
sat next to prose asserting the opposite. The heading covers both engines; the
pool difference is stated along with the way the wrapper can be bypassed
silently; the rows-cursor gotcha is scoped to SQLite together with the reason the
materialise-first pattern has to stay regardless; and a new subsection states the
double-booking guarantee per engine — the single connection on SQLite, the
advisory lock on Postgres — plus what the partial unique index actually covers,
with the measured 39-double-bookings-without-the-lock figure. §17's first gotcha
and one now-engine-conditional aside in §8 were pulled into line with it.

The new CI job runs the Go half against a postgres:17 service. Separate job, not
a matrix, because only Go is engine-dependent and svelte-check would otherwise
run twice. It carries a pg_isready health check: without one the first connection
races the server's startup and fails as "connection refused", which reads like a
bad DSN rather than a timing problem.

That job will be RED until internal/db/migrations/postgres exists — the database
layer is another worker's file set and it has only the sqlite directory today.
Measured rather than assumed: with the DSN set, dbtest.Open reports "run
migrations: migrations/postgres directory does not exist".
---
 .github/workflows/ci.yml                      | 56 +++++++++++++++
 PROGRESS.md                                   | 44 ++++++++++--
 docs/ARCHITECTURE.md                          | 70 +++++++++++++++----
 internal/booking/service_test.go              | 10 +--
 internal/caldav/caldav_test.go                |  9 +--
 internal/calendar/calendar_test.go            | 20 +-----
 internal/calendar/connid_staleness_test.go    | 10 +--
 internal/calendar/microsoft/microsoft_test.go |  9 +--
 internal/connstore/connstore_test.go          |  9 +--
 internal/demo/demo_test.go                    | 10 +--
 internal/gcal/gcal_test.go                    |  9 +--
 internal/handler/auth_google_test.go          |  9 +--
 internal/handler/calendar_test.go             | 10 +--
 internal/handler/health_test.go               |  9 +--
 internal/handler/manage_test.go               |  9 +--
 internal/handler/mcp_scope_test.go            | 11 +--
 internal/handler/slots_busy_test.go           | 20 +-----
 .../handler/stripe_locale_internal_test.go    | 11 +--
 internal/webhook/webhook_test.go              | 15 ++--
 internal/worker/worker_test.go                |  9 +--
 internal/zoom/zoom_test.go                    |  9 +--
 21 files changed, 192 insertions(+), 176 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index aa6a5dd..60da712 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -64,3 +64,59 @@ jobs:
 
       - name: go test
         run: go test ./...
+
+  # The same suite against PostgreSQL. Separate job rather than a matrix on `check`
+  # because only the Go half is engine-dependent: svelte-check and pnpm build would
+  # run twice for no reason. The frontend build is still needed here, since the Go
+  # binary go:embeds frontend/build and `go build` fails without it.
+  postgres:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: calnode_ci
+          POSTGRES_DB: calnode
+        ports:
+          - 5432:5432
+        # Without a health check the first connection races the server's startup,
+        # which fails as "connection refused" and reads like a bad DSN.
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.32.1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install frontend deps
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile
+
+      - name: Build frontend (required by the Go embed)
+        working-directory: frontend
+        run: pnpm build
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      # CALNODE_TEST_POSTGRES_DSN is what switches internal/dbtest onto Postgres.
+      # Unset — which is every other job and every local run — the suite uses
+      # in-memory SQLite exactly as before, so this job is additive: it cannot change
+      # what a contributor sees.
+      - name: go test (PostgreSQL)
+        env:
+          CALNODE_TEST_POSTGRES_DSN: postgres://postgres:calnode_ci@127.0.0.1:5432/calnode?sslmode=disable
+        run: go test ./...
diff --git a/PROGRESS.md b/PROGRESS.md
index c668eeb..c27f40b 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -91,7 +91,7 @@ The negative control is the point: unlocked, the partial unique index caught 1 o
 through `dbtest.RequirePostgres`, and skips on SQLite saying the single-connection
 pool makes the race impossible.
 
-## Boundary 4 — Postgres test harness, docs, CI — IN PROGRESS
+## Boundary 4 — Postgres test harness, docs, CI — DONE
 
 `internal/dbtest` landed with Boundary 3 because the concurrency test needs it.
 `Open(t)` returns in-memory SQLite unless `CALNODE_TEST_POSTGRES_DSN` is set, in
@@ -101,9 +101,45 @@ which `dbtest_test.go` verifies against a live server rather than assuming
 (`TestSearchPathIsolation` passes; it also asserts the schema is invisible from the
 default path).
 
+- **22 test helpers across 18 files** repointed from `db.OpenDB("sqlite://:memory:")`
+  + `Migrate()` onto `dbtest.Open(t)`, so the whole suite follows the environment.
+  Deliberately left on SQLite: `dbtime_test.go` (it pins SQLite's own output),
+  `hostlock_internal_test.go` (it asserts the lock is a no-op there),
+  `connstore/destination_test.go` (bare driver, bespoke fragment schema), and the
+  `health_test.go` cases that want an *unmigrated* database.
+  `keyvault_test.go` keeps `sqlite://file::memory:?cache=shared&_fk=1` — a different
+  DSN for a reason, not a candidate for a blanket rewrite.
+- `docs/ARCHITECTURE.md` §4 amended in place, not appended to: the heading is now
+  both engines, the pool difference and the rebinding trap are stated, the cursor
+  gotcha is scoped to SQLite with the reason the pattern must stay anyway, and a new
+  "double-booking guarantee, per engine" subsection carries the single connection on
+  SQLite and the advisory lock on Postgres, with the index's real scope. §17's
+  gotcha 1 and one now-conditional aside in §8 follow it.
+- `.github/workflows/ci.yml` gains a `postgres` job: `postgres:17` service with a
+  `pg_isready` health check, the same steps as `check` minus `svelte-check`, and
+  `CALNODE_TEST_POSTGRES_DSN` set for `go test ./...`. Additive — with the variable
+  unset nothing about an existing run changes.
+
 ## Blocked on the database layer
 
 `internal/db/migrations/postgres` does not exist yet (`db.go` embeds
-`migrations/sqlite/*.sql` only), so nothing can migrate on Postgres and no
-Postgres-side run can be verified from this branch yet. The harness added in
-Boundary 4 calls `h.Migrate()` and starts working the moment those land.
+`migrations/sqlite/*.sql` only), so nothing can migrate on Postgres. Measured, not
+assumed: with the DSN set, `dbtest.Open` fails with
+`migrate postgres: run migrations: migrations/postgres directory does not exist`.
+Everything on this branch is written against `h.Migrate()` and starts working the
+moment those land; until then the new `postgres` CI job will be red for that reason
+and the Boundary 3 proof stands on the temporary hand-written schema recorded above.
+
+## Findings for whoever owns the schema
+
+1. **Booleans.** The tree stores them as `INTEGER` and compares them literally —
+   `email_login = 1`, `is_organizer = 1`, `is_destination = 1`, `boolToInt(...)`.
+   If the Postgres migrations declare those columns `BOOLEAN`, every one of those
+   comparisons is a type error. `SMALLINT`/`INTEGER` keeps the whole tree working
+   unchanged.
+2. **Text timestamp collation.** Timestamps are `TEXT` and compared
+   lexicographically on purpose (the recordings consent window, the job queue's
+   `run_at <= ?`). That is byte ordering under SQLite. Under a non-`C` Postgres
+   collation, ordering of mixed shapes (a space-separated `run_at` against a
+   `T`-separated one) is not guaranteed to match. Worth either `COLLATE "C"` on
+   those columns or a deliberate decision that it is safe.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index e81e86c..84ea4a8 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -67,15 +67,32 @@ app you must `pnpm build` in `frontend/` **and** rebuild/restart the Go binary
 
 ---
 
-## 4. Persistence (SQLite) — and the single-connection rule
-
-- `internal/db`: opens SQLite with **`SetMaxOpenConns(1)`** + `SetMaxIdleConns(1)`,
-  **WAL** journal mode, `busy_timeout=5000`. One writer connection by design.
-- Migrations: **goose** SQL files in `internal/db/migrations/` (00001→00029). Run
-  automatically on startup. `ALTER TABLE ADD COLUMN` is reversible-by-convention
-  only (SQLite can't easily drop columns).
-
-### ⚠️ The single-connection gotcha (bit us once)
+## 4. Persistence (SQLite or PostgreSQL) — and the single-connection rule
+
+- `internal/db`: `OpenDB(DATABASE_URL)` picks the engine from the URL scheme. A
+  `postgres://` URL selects PostgreSQL; everything else (`sqlite://./rel`,
+  `sqlite:///abs`, `:memory:`, a bare path) selects SQLite, so every configuration
+  that worked before still works unchanged.
+- SQLite: **`SetMaxOpenConns(1)`** + `SetMaxIdleConns(1)`, **WAL** journal mode,
+  `busy_timeout=5000`. One writer connection by design.
+- PostgreSQL: a normal pool (10 open / 5 idle). The single connection above is a
+  SQLite constraint, not a Calnode design choice, and carrying it over would
+  serialise the whole instance on an engine with its own concurrency control.
+- The handle rebinds placeholders: Calnode's SQL is written once with `?` and
+  rewritten to `$1…$n` on PostgreSQL. ⚠️ `db.DB` embeds `*sql.DB` and the field is
+  exported, so `h.DB.Query(...)` compiles and **skips rebinding** — it passes on
+  SQLite and fails on PostgreSQL with a syntax error far from the edit. Call the
+  wrapper's own methods. The handful of statements no single spelling covers use
+  `Dialect.SQL(sqlite, postgres)`.
+- Timestamps are computed in Go (`internal/dbtime`) rather than by the engine;
+  `datetime('now')` and `strftime` do not exist in PostgreSQL. `dbtime` keeps the
+  two layouts the schema already stores, byte-identical to what SQLite wrote.
+- Migrations: **goose** SQL files in `internal/db/migrations/{sqlite,postgres}/` —
+  one schema, two spellings, same version numbers. Run automatically on startup.
+  `ALTER TABLE ADD COLUMN` is reversible-by-convention only (SQLite can't easily
+  drop columns).
+
+### ⚠️ The single-connection gotcha (bit us once) — SQLite only
 
 With one connection, **never run a query while a `rows` cursor from the same pool
 is still open** (i.e. inside a `for rows.Next()` loop). The open cursor holds the
@@ -85,9 +102,32 @@ exceeded` (not "database is locked"). **Pattern:** read the cursor fully into a
 slice, close it, then loop. See `Handler.assignedHosts`, the calendar reconciler,
 `Reschedule`. (Memory: `sqlite-single-connection`.)
 
-Bonus property: because booking transactions serialize on the single connection,
-the app-level overlap check reliably guards **all** hosts (not just the one the
-partial unique index covers) — no TOCTOU between concurrent bookings.
+This is a consequence of the single connection, so it does not apply on
+PostgreSQL — but the materialise-first pattern must stay, because it is the only
+thing keeping those three paths working on SQLite.
+
+### The double-booking guarantee, per engine
+
+The app-level overlap check reads "is this host free?" and then writes on the
+answer. What keeps that free of TOCTOU races differs:
+
+- **SQLite** — booking transactions serialize on the single connection, so the
+  check reliably guards **all** hosts, not just the one the partial unique index
+  covers.
+- **PostgreSQL** — the pool has many connections, so two overlapping bookings could
+  both clear the check. `booking.lockHosts` takes **`pg_advisory_xact_lock`** on
+  each host id before the first overlap read, in `Create`, `Reschedule` and
+  `ReassignHost`. The key is SHA-256 of `"calnode:booking:host:" + hostID`, first
+  eight bytes as an int64; ids are locked in sorted order so two transactions
+  needing the same pair cannot deadlock. The lock ends with the transaction, so
+  there is nothing to release. On SQLite it is a no-op.
+
+Both engines also carry the partial unique index
+`idx_bookings_no_double (host_id, start_at) WHERE status != 'cancelled'`. It catches
+an **identical** start time and nothing else — a partial overlap is two distinct
+keys — which is why the app-level check and the lock exist and why all three stay.
+Measured on PostgreSQL, 40 races between overlapping-but-not-identical slots: with
+the lock, 0 double bookings; without it, 39, of which the index caught one.
 
 ### Data model (key tables)
 
@@ -264,7 +304,7 @@ members.
   mode (role-tagged), then loads each host's availability **concurrently**
   (goroutines) — the slow part is one Google free/busy round-trip per host, so
   parallelizing turns N sequential calls into ~one call's latency. DB queries
-  serialize on the single connection (fast); only the network overlaps. Response
+  serialize on SQLite's single connection (fast); only the network overlaps. Response
   includes a `hosts` metadata map (id→name/avatar) for rendering faces.
 - **Busy** for a host = every non-cancelled booking they attend, via
   `booking_hosts` (NOT just `bookings.host_id`) — so a non-primary Group/fixed seat
@@ -704,7 +744,9 @@ as the desired state:
 ## 17. Cross-cutting gotchas (read before editing)
 
 1. **SQLite single connection** — never query inside an open cursor; materialize
-   first (§4).
+   first (§4). Harmless on PostgreSQL, but the pattern stays either way.
+   On PostgreSQL the same single connection is also what the booking overlap check
+   loses, which `pg_advisory_xact_lock` replaces (§4).
 2. **All times UTC** in storage; convert at the edges. The slot busy-window must be
    widened for tz boundaries.
 3. **Frontend is embedded at compile time** — `pnpm build` + rebuild Go to see
diff --git a/internal/booking/service_test.go b/internal/booking/service_test.go
index 5cc1e5c..18618a5 100644
--- a/internal/booking/service_test.go
+++ b/internal/booking/service_test.go
@@ -7,19 +7,13 @@ import (
 
 	"github.com/calnode/calnode/internal/booking"
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/uid"
 )
 
 func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("open test db: %v", err)
-	}
-	t.Cleanup(func() { database.Close() })
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate test db: %v", err)
-	}
+	database := dbtest.Open(t)
 	return database
 }
 
diff --git a/internal/caldav/caldav_test.go b/internal/caldav/caldav_test.go
index 89bba63..eba7a93 100644
--- a/internal/caldav/caldav_test.go
+++ b/internal/caldav/caldav_test.go
@@ -11,19 +11,14 @@ import (
 
 	"github.com/calnode/calnode/internal/calendar"
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 )
 
 const testKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
 
 func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 	return database
 }
diff --git a/internal/calendar/calendar_test.go b/internal/calendar/calendar_test.go
index b9df253..b066708 100644
--- a/internal/calendar/calendar_test.go
+++ b/internal/calendar/calendar_test.go
@@ -4,18 +4,11 @@ import (
 	"context"
 	"testing"
 
-	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 )
 
 func TestCanAutoGenerate(t *testing.T) {
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-	defer database.Close()
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	ctx := context.Background()
 
 	seed := func(userID, provider, kind string) {
@@ -66,14 +59,7 @@ func TestCanAutoGenerate(t *testing.T) {
 // TestConnectionManagement covers the multi-calendar Service helpers: listing connections,
 // switching the single destination, and promoting a survivor when the destination is removed.
 func TestConnectionManagement(t *testing.T) {
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-	defer database.Close()
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	ctx := context.Background()
 	if _, err := database.ExecContext(ctx,
 		`INSERT INTO users (id, email, name, iana_timezone, is_admin, created_at)
diff --git a/internal/calendar/connid_staleness_test.go b/internal/calendar/connid_staleness_test.go
index 9a40641..484dffe 100644
--- a/internal/calendar/connid_staleness_test.go
+++ b/internal/calendar/connid_staleness_test.go
@@ -7,19 +7,13 @@ import (
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 )
 
 // newTestDB opens a migrated in-memory DB with one user.
 func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-	t.Cleanup(func() { database.Close() })
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	if _, err := database.Exec(
 		`INSERT INTO users (id, email, name, iana_timezone, is_admin, created_at)
 		 VALUES ('u1','u1@x.test','U','UTC',0,'2026-01-01T00:00:00Z')`); err != nil {
diff --git a/internal/calendar/microsoft/microsoft_test.go b/internal/calendar/microsoft/microsoft_test.go
index 919c149..53a0856 100644
--- a/internal/calendar/microsoft/microsoft_test.go
+++ b/internal/calendar/microsoft/microsoft_test.go
@@ -14,19 +14,14 @@ import (
 
 	"github.com/calnode/calnode/internal/calendar"
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 )
 
 const testKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
 
 func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 	return database
 }
diff --git a/internal/connstore/connstore_test.go b/internal/connstore/connstore_test.go
index d36be87..bbbeed3 100644
--- a/internal/connstore/connstore_test.go
+++ b/internal/connstore/connstore_test.go
@@ -5,17 +5,12 @@ import (
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 )
 
 func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("newTestDB: open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("newTestDB: migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 	return database
 }
diff --git a/internal/demo/demo_test.go b/internal/demo/demo_test.go
index ffd8d65..cc7ecaf 100644
--- a/internal/demo/demo_test.go
+++ b/internal/demo/demo_test.go
@@ -5,19 +5,13 @@ import (
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/demo"
 )
 
 func newMigratedDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db.Open: %v", err)
-	}
-	t.Cleanup(func() { database.Close() })
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("db.Migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	return database
 }
 
diff --git a/internal/gcal/gcal_test.go b/internal/gcal/gcal_test.go
index 89a8926..0e7dd9f 100644
--- a/internal/gcal/gcal_test.go
+++ b/internal/gcal/gcal_test.go
@@ -9,6 +9,7 @@ import (
 	"golang.org/x/oauth2"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 )
 
 // testKeyHex is a valid 64-char hex key (32 bytes) used across tests.
@@ -16,13 +17,7 @@ const testKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdead
 
 func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("newTestDB: open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("newTestDB: migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 	return database
 }
diff --git a/internal/handler/auth_google_test.go b/internal/handler/auth_google_test.go
index 1f2a05a..13f2325 100644
--- a/internal/handler/auth_google_test.go
+++ b/internal/handler/auth_google_test.go
@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/handler"
 )
 
@@ -16,13 +17,7 @@ import (
 // returns the handler, database handle, and the seeded user ID.
 func authTestSetup(t *testing.T) (*handler.Handler, *db.DB, string) {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db.Open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("db.Migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 
 	userID := "user-auth-test"
diff --git a/internal/handler/calendar_test.go b/internal/handler/calendar_test.go
index 6edfb09..fb112b2 100644
--- a/internal/handler/calendar_test.go
+++ b/internal/handler/calendar_test.go
@@ -9,7 +9,7 @@ import (
 	"testing"
 
 	"github.com/calnode/calnode/internal/calendar"
-	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/gcal"
 	"github.com/calnode/calnode/internal/handler"
 )
@@ -21,13 +21,7 @@ const testGCalKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
 // Returns (handler, gcalClient, plainAPIKey, userID).
 func newHandlerWithGCal(t *testing.T) (*handler.Handler, *gcal.Client, string, string) {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db.Open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("db.Migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 
 	h := handler.New(database, slog.Default())
diff --git a/internal/handler/health_test.go b/internal/handler/health_test.go
index d042234..596d08a 100644
--- a/internal/handler/health_test.go
+++ b/internal/handler/health_test.go
@@ -8,18 +8,13 @@ import (
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/handler"
 )
 
 func newTestHandler(t *testing.T) *handler.Handler {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db.Open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("db.Migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 	return handler.New(database, slog.Default())
 }
diff --git a/internal/handler/manage_test.go b/internal/handler/manage_test.go
index 4a743f7..d71335a 100644
--- a/internal/handler/manage_test.go
+++ b/internal/handler/manage_test.go
@@ -12,6 +12,7 @@ import (
 
 	"github.com/calnode/calnode/internal/booking"
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/handler"
 	"github.com/calnode/calnode/internal/uid"
 )
@@ -20,13 +21,7 @@ import (
 // underlying DB so tests can interact with the DB directly (e.g. to issue tokens).
 func newTestHandlerDB(t *testing.T) (*handler.Handler, *db.DB) {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db.Open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("db.Migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 	return handler.New(database, slog.Default()), database
 }
diff --git a/internal/handler/mcp_scope_test.go b/internal/handler/mcp_scope_test.go
index 4614ab1..568aed6 100644
--- a/internal/handler/mcp_scope_test.go
+++ b/internal/handler/mcp_scope_test.go
@@ -11,20 +11,13 @@ import (
 	"time"
 
 	"github.com/calnode/calnode/internal/booking"
-	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 )
 
 // verifies MCP tools scope by role: a member sees/controls only the bookings they host,
 // while an admin/owner (and the unauthenticated stdio operator) see the whole workspace.
 func TestMCP_roleScoping(t *testing.T) {
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db open: %v", err)
-	}
-	t.Cleanup(func() { database.Close() })
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	h := New(database, slog.Default())
 
 	// Owner (first user → owner+admin).
diff --git a/internal/handler/slots_busy_test.go b/internal/handler/slots_busy_test.go
index c415d96..62ba09a 100644
--- a/internal/handler/slots_busy_test.go
+++ b/internal/handler/slots_busy_test.go
@@ -6,7 +6,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 )
 
 // TestHostAvailability_includesAdjacentUTCDayBooking is the regression guard for
@@ -16,14 +16,7 @@ import (
 // generation would offer a slot the host is already booked for (then 409 at
 // booking time). Everything is stored UTC — this guards the fetch *window*.
 func TestHostAvailability_includesAdjacentUTCDayBooking(t *testing.T) {
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("open db: %v", err)
-	}
-	defer database.Close()
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	h := New(database, slog.New(slog.DiscardHandler))
 
 	// Host in NZ; a booking at 18 Jun 10:00 NZST = 17 Jun 22:00Z (previous UTC day).
@@ -60,14 +53,7 @@ func TestHostAvailability_includesAdjacentUTCDayBooking(t *testing.T) {
 // bookings.host_id) — otherwise their slots on other events stay open and they
 // get double-booked.
 func TestHostAvailability_includesNonPrimaryGroupSeat(t *testing.T) {
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("open db: %v", err)
-	}
-	defer database.Close()
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	h := New(database, slog.New(slog.DiscardHandler))
 
 	database.Exec(`INSERT INTO users (id,email,name,iana_timezone,is_admin,is_owner) VALUES ('u1','a@example.com','A','UTC',1,1)`)
diff --git a/internal/handler/stripe_locale_internal_test.go b/internal/handler/stripe_locale_internal_test.go
index 7af442f..633b9ac 100644
--- a/internal/handler/stripe_locale_internal_test.go
+++ b/internal/handler/stripe_locale_internal_test.go
@@ -12,7 +12,7 @@ import (
 	"time"
 
 	"github.com/calnode/calnode/internal/booking"
-	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/mailer"
 )
 
@@ -65,14 +65,7 @@ func (c *captureMailer) recipients() []string {
 // of the language the attendee actually booked in — even though the free-booking path (same
 // dispatchBookingConfirmation) got this right. See stripe_booking.go's SELECT.
 func TestConfirmPaidBooking_usesAttendeeLocale(t *testing.T) {
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db.Open: %v", err)
-	}
-	defer database.Close()
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("db.Migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 
 	h := New(database, slog.Default())
 	cap := &captureMailer{}
diff --git a/internal/webhook/webhook_test.go b/internal/webhook/webhook_test.go
index 7f129e2..9eb3ea4 100644
--- a/internal/webhook/webhook_test.go
+++ b/internal/webhook/webhook_test.go
@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/webhook"
 )
 
@@ -23,13 +24,7 @@ type env struct {
 
 func newEnv(t *testing.T) *env {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db.Open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("db.Migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 
 	ctx := context.Background()
@@ -53,8 +48,7 @@ func newEnv(t *testing.T) *env {
 // ---------------------------------------------------------------------------
 
 func TestNew_badKeyReturnsError(t *testing.T) {
-	database, _ := db.OpenDB("sqlite://:memory:")
-	database.Migrate()
+	database := dbtest.Open(t)
 	defer database.Close()
 
 	if _, err := webhook.New(database, "not-hex"); err == nil {
@@ -66,8 +60,7 @@ func TestNew_badKeyReturnsError(t *testing.T) {
 }
 
 func TestNew_emptyKeyUsesEphemeral(t *testing.T) {
-	database, _ := db.OpenDB("sqlite://:memory:")
-	database.Migrate()
+	database := dbtest.Open(t)
 	defer database.Close()
 
 	svc, err := webhook.New(database, "")
diff --git a/internal/worker/worker_test.go b/internal/worker/worker_test.go
index 2e7d3d8..2db47e1 100644
--- a/internal/worker/worker_test.go
+++ b/internal/worker/worker_test.go
@@ -14,19 +14,14 @@ import (
 	"time"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/webhook"
 	"github.com/calnode/calnode/internal/worker"
 )
 
 func setup(t *testing.T) (*db.DB, *webhook.Service) {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("db.Open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("db.Migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 
 	// Insert users so FK constraints are satisfied.
diff --git a/internal/zoom/zoom_test.go b/internal/zoom/zoom_test.go
index 7ecc207..9aee725 100644
--- a/internal/zoom/zoom_test.go
+++ b/internal/zoom/zoom_test.go
@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
 	"github.com/calnode/calnode/internal/secret"
 )
 
@@ -17,13 +18,7 @@ const testKeyHex = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdead
 
 func newTestDB(t *testing.T) *db.DB {
 	t.Helper()
-	database, err := db.OpenDB("sqlite://:memory:")
-	if err != nil {
-		t.Fatalf("newTestDB: open: %v", err)
-	}
-	if err := database.Migrate(); err != nil {
-		t.Fatalf("newTestDB: migrate: %v", err)
-	}
+	database := dbtest.Open(t)
 	t.Cleanup(func() { database.Close() })
 	return database
 }

From 78dab8276a6ba0e87b1ef365aad4bf0ab4a341c6 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 04:03:48 -0400
Subject: [PATCH 08/51] db: classify constraint violations by code, not by
 English message
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Thirteen sites decided between 409, 400, 404 and 500 by substring-matching
SQLite's error text. On PostgreSQL none of them matched, so a duplicate slug, a
replayed idempotency key and a bad enum value all fell through to
{"error":"internal error"} with a 500. Seven Postgres test failures were this.

internal/db now exports IsUniqueViolation, IsCheckViolation and
IsForeignKeyViolation. PostgreSQL is matched on SQLSTATE (23505 / 23514 / 23503)
because the message is localised by the server's lc_messages, so a server running
in a non-English locale would defeat any text match no matter how carefully it was
written. SQLite keeps a text match, because modernc.org/sqlite does not expose a
code on its error value — but it is now in exactly one place instead of thirteen,
and it is pinned by a test.

A *pgconn.PgError whose code does not match returns false rather than falling
through to the text comparison. Falling through would classify a PostgreSQL error
by whether its message happened to contain another engine's English phrase, which
is the fragility being removed.

The test provokes a REAL violation of each class against the real migrated schema
on whichever engine dbtest is configured for — a duplicate users.email, a booking
with a status the CHECK forbids, a booking referencing a nonexistent event type —
rather than constructing an error value, because a constructed error only proves
the predicate agrees with what the author believed the driver returns, and that
belief being wrong is why this commit exists. It also asserts exactly ONE of the
three predicates matches each violation, and that a missing-table error and a
plain errors.New match none: a predicate that answered true for everything would
have made all thirteen call sites pass and been badly wrong.

internal/booking and internal/handler keep thin local wrappers where a local name
read better at the call site; their bodies now delegate.

grep -rn "constraint failed" --include='*.go' internal/ cmd/ returns three hits,
all of them the constants inside internal/db/constraint.go.
---
 internal/booking/service.go         |  22 ++----
 internal/db/constraint.go           |  70 ++++++++++++++++++
 internal/db/constraint_test.go      | 110 ++++++++++++++++++++++++++++
 internal/handler/availability.go    |   6 +-
 internal/handler/booking_handler.go |   8 +-
 internal/handler/event_type.go      |   9 ++-
 internal/handler/idempotency.go     |   5 +-
 internal/handler/override.go        |   4 +-
 internal/handler/teams.go           |   7 +-
 9 files changed, 207 insertions(+), 34 deletions(-)
 create mode 100644 internal/db/constraint.go
 create mode 100644 internal/db/constraint_test.go

diff --git a/internal/booking/service.go b/internal/booking/service.go
index 888162d..2695e62 100644
--- a/internal/booking/service.go
+++ b/internal/booking/service.go
@@ -13,8 +13,6 @@ import (
 	"strings"
 	"time"
 
-	"github.com/jackc/pgx/v5/pgconn"
-
 	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/uid"
 )
@@ -690,17 +688,9 @@ func scanBooking(s scanner) (*Booking, error) {
 
 // isUniqueViolation reports whether err is a unique-constraint violation — on this
 // booking path, idx_bookings_no_double rejecting an exact start-time collision that
-// the app-level overlap check did not catch. Both engines are recognised: Postgres
-// by SQLSTATE 23505, which is the only stable handle on it (the message text is
-// localised by the server's lc_messages), and SQLite by its message, which is what
-// modernc.org/sqlite surfaces.
-func isUniqueViolation(err error) bool {
-	var pgErr *pgconn.PgError
-	if errors.As(err, &pgErr) {
-		return pgErr.Code == pgUniqueViolation
-	}
-	return strings.Contains(err.Error(), "UNIQUE constraint failed")
-}
-
-// pgUniqueViolation is PostgreSQL's SQLSTATE for unique_violation.
-const pgUniqueViolation = "23505"
+// the app-level overlap check did not catch.
+//
+// A thin wrapper over db.IsUniqueViolation, kept only because three call sites read
+// better with the local name and the doc comment above belongs to this path rather
+// than to the shared helper.
+func isUniqueViolation(err error) bool { return db.IsUniqueViolation(err) }
diff --git a/internal/db/constraint.go b/internal/db/constraint.go
new file mode 100644
index 0000000..5203cbf
--- /dev/null
+++ b/internal/db/constraint.go
@@ -0,0 +1,70 @@
+package db
+
+import (
+	"errors"
+	"strings"
+
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+// Constraint violations are the one class of database error Calnode routinely acts
+// on rather than just reporting: a duplicate slug is a 409, an out-of-range value is
+// a 400, a dangling reference is a 404. Deciding which is which used to be a
+// substring match on SQLite's English message, which is invisible to every gate and
+// silently degrades to a 500 on PostgreSQL.
+//
+// PostgreSQL is matched on SQLSTATE because that is the only stable handle: the
+// message text is localised by the server's lc_messages, so a server running in
+// German would defeat any text match. SQLite has no error codes exposed through
+// modernc.org/sqlite's error value, so its half stays a text match — which is what
+// it always was, and it is pinned by a test that provokes a real violation.
+const (
+	pgUniqueViolation     = "23505"
+	pgCheckViolation      = "23514"
+	pgForeignKeyViolation = "23503"
+)
+
+// SQLite's messages for the same three classes.
+const (
+	sqliteUniqueViolation     = "UNIQUE constraint failed"
+	sqliteCheckViolation      = "CHECK constraint failed"
+	sqliteForeignKeyViolation = "FOREIGN KEY constraint failed"
+)
+
+// IsUniqueViolation reports whether err is a unique-constraint violation — a
+// duplicate slug, a replayed idempotency key, a second booking at one host's exact
+// start time.
+func IsUniqueViolation(err error) bool {
+	return violates(err, pgUniqueViolation, sqliteUniqueViolation)
+}
+
+// IsCheckViolation reports whether err is a CHECK-constraint violation, i.e. a value
+// outside the set the column allows. Callers turn this into a 400, since the only way
+// to reach it is a request carrying a value the handler did not validate.
+func IsCheckViolation(err error) bool {
+	return violates(err, pgCheckViolation, sqliteCheckViolation)
+}
+
+// IsForeignKeyViolation reports whether err is a foreign-key violation — a reference
+// to a row that does not exist, or a delete that would orphan one.
+func IsForeignKeyViolation(err error) bool {
+	return violates(err, pgForeignKeyViolation, sqliteForeignKeyViolation)
+}
+
+// violates is the shared shape: SQLSTATE when the error came from PostgreSQL, the
+// message otherwise.
+//
+// A *pgconn.PgError whose code does NOT match returns false rather than falling
+// through to the text comparison. Falling through would let a PostgreSQL error be
+// classified by whether its message happened to contain an English phrase from
+// another engine, which is exactly the fragility being removed here.
+func violates(err error, sqlstate, sqliteText string) bool {
+	if err == nil {
+		return false
+	}
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) {
+		return pgErr.Code == sqlstate
+	}
+	return strings.Contains(err.Error(), sqliteText)
+}
diff --git a/internal/db/constraint_test.go b/internal/db/constraint_test.go
new file mode 100644
index 0000000..2a0a87d
--- /dev/null
+++ b/internal/db/constraint_test.go
@@ -0,0 +1,110 @@
+package db_test
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/uid"
+)
+
+// TestConstraintPredicates provokes a real violation of each class against the real
+// schema, on whichever engine dbtest is configured for, and asserts the predicate
+// recognises it.
+//
+// Provoked rather than constructed: a hand-built error would only prove the
+// predicate agrees with whatever the test author believed the driver returns, and
+// the whole reason these helpers exist is that that belief was wrong on PostgreSQL.
+// Run it twice — once bare, once with CALNODE_TEST_POSTGRES_DSN — and both engines
+// are covered.
+func TestConstraintPredicates(t *testing.T) {
+	h := dbtest.Open(t)
+
+	// A user and an event type to hang the booking constraints off.
+	userID := uid.New()
+	if _, err := h.Exec(
+		`INSERT INTO users (id, email, name, iana_timezone) VALUES (?, ?, 'Host', 'UTC')`,
+		userID, userID+"@example.com"); err != nil {
+		t.Fatalf("seed user: %v", err)
+	}
+	etID := uid.New()
+	if _, err := h.Exec(
+		`INSERT INTO event_types (id, user_id, slug, name, duration_minutes)
+		 VALUES (?, ?, ?, 'Call', 30)`, etID, userID, etID); err != nil {
+		t.Fatalf("seed event type: %v", err)
+	}
+
+	t.Run("unique", func(t *testing.T) {
+		// users.email is UNIQUE in both migration sets.
+		_, err := h.Exec(
+			`INSERT INTO users (id, email, name, iana_timezone) VALUES (?, ?, 'Clash', 'UTC')`,
+			uid.New(), userID+"@example.com")
+		assertOnly(t, err, "unique", db.IsUniqueViolation)
+	})
+
+	t.Run("check", func(t *testing.T) {
+		// bookings.status has CHECK (status IN ('confirmed','cancelled')).
+		_, err := h.Exec(`
+			INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at, status, created_at, updated_at)
+			VALUES (?, ?, ?, '2026-06-15T09:00:00Z', '2026-06-15T09:30:00Z', 'not-a-status', ?, ?)`,
+			uid.New(), etID, userID, "2026-06-01T00:00:00Z", "2026-06-01T00:00:00Z")
+		assertOnly(t, err, "check", db.IsCheckViolation)
+	})
+
+	t.Run("foreign key", func(t *testing.T) {
+		// event_type_id references event_types(id). SQLite needs foreign_keys=ON,
+		// which OpenDB sets.
+		_, err := h.Exec(`
+			INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at, status, created_at, updated_at)
+			VALUES (?, 'no-such-event-type', ?, '2026-06-15T10:00:00Z', '2026-06-15T10:30:00Z', 'confirmed', ?, ?)`,
+			uid.New(), userID, "2026-06-01T00:00:00Z", "2026-06-01T00:00:00Z")
+		assertOnly(t, err, "foreign key", db.IsForeignKeyViolation)
+	})
+
+	t.Run("unrelated error", func(t *testing.T) {
+		// A predicate that answered true for everything would satisfy every caller
+		// above and be badly wrong, so the negative cases carry as much weight.
+		_, err := h.Exec(`SELECT * FROM a_table_that_does_not_exist`)
+		if err == nil {
+			t.Fatal("expected an error from a missing table")
+		}
+		assertNone(t, err, "missing table")
+		assertNone(t, errors.New("some unrelated failure"), "plain error")
+		assertNone(t, nil, "nil")
+	})
+}
+
+// assertOnly checks that want recognises err and the other two predicates do not:
+// the classes have to be distinguishable, or a CHECK violation becomes a 409.
+func assertOnly(t *testing.T, err error, class string, want func(error) bool) {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("%s: expected a constraint violation, got nil", class)
+	}
+	if !want(err) {
+		t.Errorf("%s: predicate did not recognise %v", class, err)
+	}
+	matches := 0
+	for _, p := range []func(error) bool{db.IsUniqueViolation, db.IsCheckViolation, db.IsForeignKeyViolation} {
+		if p(err) {
+			matches++
+		}
+	}
+	if matches != 1 {
+		t.Errorf("%s: %d of 3 predicates matched %v; want exactly 1", class, matches, err)
+	}
+}
+
+func assertNone(t *testing.T, err error, what string) {
+	t.Helper()
+	for name, p := range map[string]func(error) bool{
+		"IsUniqueViolation":     db.IsUniqueViolation,
+		"IsCheckViolation":      db.IsCheckViolation,
+		"IsForeignKeyViolation": db.IsForeignKeyViolation,
+	} {
+		if p(err) {
+			t.Errorf("%s returned true for %s (%v)", name, what, err)
+		}
+	}
+}
diff --git a/internal/handler/availability.go b/internal/handler/availability.go
index 6577260..3eb766e 100644
--- a/internal/handler/availability.go
+++ b/internal/handler/availability.go
@@ -4,8 +4,8 @@ import (
 	"database/sql"
 	"encoding/json"
 	"net/http"
-	"strings"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/uid"
 )
 
@@ -47,7 +47,7 @@ func (h *Handler) CreateAvailabilityRule(w http.ResponseWriter, r *http.Request)
 		VALUES (?, ?, ?, ?, ?, ?)`,
 		id, user.ID, req.EventTypeID, req.DayOfWeek, req.StartTime, req.EndTime)
 	if err != nil {
-		if strings.Contains(err.Error(), "UNIQUE constraint failed") {
+		if db.IsUniqueViolation(err) {
 			h.writeError(w, http.StatusConflict, "a rule for this day and time already exists")
 			return
 		}
@@ -177,7 +177,7 @@ func (h *Handler) UpdateAvailabilityRule(w http.ResponseWriter, r *http.Request)
 		`UPDATE availability_rules SET day_of_week=?, start_time=?, end_time=? WHERE id=? AND user_id=?`,
 		current.DayOfWeek, current.StartTime, current.EndTime, id, user.ID)
 	if err != nil {
-		if strings.Contains(err.Error(), "UNIQUE constraint failed") {
+		if db.IsUniqueViolation(err) {
 			h.writeError(w, http.StatusConflict, "a rule for this day and time already exists")
 			return
 		}
diff --git a/internal/handler/booking_handler.go b/internal/handler/booking_handler.go
index c221cff..7f85e84 100644
--- a/internal/handler/booking_handler.go
+++ b/internal/handler/booking_handler.go
@@ -15,6 +15,7 @@ import (
 
 	"github.com/calnode/calnode/internal/booking"
 	"github.com/calnode/calnode/internal/calendar"
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/i18n"
 	"github.com/calnode/calnode/internal/mailer"
 	"github.com/calnode/calnode/internal/slots"
@@ -1843,10 +1844,9 @@ func (h *Handler) loadHostPrefs(ctx context.Context, hostID string) (hostPrefs,
 	return p, nil
 }
 
-// isForeignKeyViolation reports whether err is a SQLite FOREIGN KEY constraint failure.
-func isForeignKeyViolation(err error) bool {
-	return strings.Contains(err.Error(), "FOREIGN KEY constraint failed")
-}
+// isForeignKeyViolation reports whether err is a foreign-key violation, on either
+// engine. A thin wrapper so the two call sites keep reading as a local predicate.
+func isForeignKeyViolation(err error) bool { return db.IsForeignKeyViolation(err) }
 
 // enqueueReminder inserts a reminder.send job scheduled hoursBefore hours before startAt.
 // If the computed run_at has already passed, the job fires on the next poll cycle.
diff --git a/internal/handler/event_type.go b/internal/handler/event_type.go
index 2bf220e..949dacb 100644
--- a/internal/handler/event_type.go
+++ b/internal/handler/event_type.go
@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"strings"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/uid"
 )
@@ -316,11 +317,11 @@ func (h *Handler) CreateEventType(w http.ResponseWriter, r *http.Request) {
 		routingMode, bufBefore, bufAfter, minNotice, maxFuture, maxActive, showTaken,
 		defaultMsgConfirmation, defaultMsgCancellation, defaultMsgReschedule, defaultMsgReminder)
 	if err != nil {
-		if strings.Contains(err.Error(), "UNIQUE constraint failed") {
+		if db.IsUniqueViolation(err) {
 			h.writeError(w, http.StatusConflict, "slug already in use")
 			return
 		}
-		if strings.Contains(err.Error(), "CHECK constraint failed") {
+		if db.IsCheckViolation(err) {
 			h.writeError(w, http.StatusBadRequest, "invalid location_type or routing_mode value")
 			return
 		}
@@ -703,7 +704,7 @@ func (h *Handler) PatchEventType(w http.ResponseWriter, r *http.Request) {
 			"UPDATE event_types SET "+strings.Join(setClauses, ", ")+" WHERE slug = ? AND user_id = ?", // #nosec G202 -- setClauses is built by set()/the literal col list above; every column name is a hardcoded string, every value is bound via args...
 			args...)
 		if err != nil {
-			if strings.Contains(err.Error(), "CHECK constraint failed") {
+			if db.IsCheckViolation(err) {
 				h.writeError(w, http.StatusBadRequest, "invalid location_type or routing_mode value")
 				return
 			}
@@ -782,7 +783,7 @@ func (h *Handler) DeleteEventType(w http.ResponseWriter, r *http.Request) {
 	res, err := h.db.ExecContext(r.Context(),
 		`DELETE FROM event_types WHERE slug = ? AND user_id = ?`, slug, user.ID)
 	if err != nil {
-		if strings.Contains(err.Error(), "FOREIGN KEY constraint failed") {
+		if db.IsForeignKeyViolation(err) {
 			h.writeError(w, http.StatusConflict, "this event type has bookings in its history (including cancelled ones) and can't be deleted — deactivate it instead")
 			return
 		}
diff --git a/internal/handler/idempotency.go b/internal/handler/idempotency.go
index 91717f9..8991666 100644
--- a/internal/handler/idempotency.go
+++ b/internal/handler/idempotency.go
@@ -5,8 +5,9 @@ import (
 	"crypto/sha256"
 	"database/sql"
 	"encoding/hex"
-	"strings"
 	"time"
+
+	"github.com/calnode/calnode/internal/db"
 )
 
 // idempotencyRecord is a previously-seen Idempotency-Key's stored outcome.
@@ -38,7 +39,7 @@ func (h *Handler) claimIdempotencyKey(ctx context.Context, key, reqHash string)
 	if err == nil {
 		return nil, false, nil
 	}
-	if !strings.Contains(err.Error(), "UNIQUE constraint failed") {
+	if !db.IsUniqueViolation(err) {
 		return nil, false, err
 	}
 
diff --git a/internal/handler/override.go b/internal/handler/override.go
index aaa2274..d34db3a 100644
--- a/internal/handler/override.go
+++ b/internal/handler/override.go
@@ -4,9 +4,9 @@ import (
 	"database/sql"
 	"encoding/json"
 	"net/http"
-	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/uid"
 )
 
@@ -155,7 +155,7 @@ func (h *Handler) CreateAvailabilityOverride(w http.ResponseWriter, r *http.Requ
 		INSERT INTO availability_overrides (id, user_id, date, is_available, reason, start_time, end_time)
 		VALUES (?, ?, ?, ?, ?, ?, ?)`,
 		id, user.ID, req.Date, isAvailInt, req.Reason, req.StartTime, req.EndTime); err != nil {
-		if strings.Contains(err.Error(), "UNIQUE constraint failed") {
+		if db.IsUniqueViolation(err) {
 			h.writeError(w, http.StatusConflict, "an override already exists for this date; delete it first")
 			return
 		}
diff --git a/internal/handler/teams.go b/internal/handler/teams.go
index ff32173..c096625 100644
--- a/internal/handler/teams.go
+++ b/internal/handler/teams.go
@@ -8,6 +8,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/uid"
 )
 
@@ -86,7 +87,7 @@ func (h *Handler) CreateTeam(w http.ResponseWriter, r *http.Request) {
 	if _, err := h.db.ExecContext(r.Context(),
 		`INSERT INTO teams (id, name, slug, created_at) VALUES (?, ?, ?, ?)`,
 		id, req.Name, slug, now); err != nil {
-		if strings.Contains(err.Error(), "UNIQUE constraint failed") {
+		if db.IsUniqueViolation(err) {
 			h.writeError(w, http.StatusConflict, "a team with that slug already exists")
 			return
 		}
@@ -222,7 +223,7 @@ func (h *Handler) PatchTeam(w http.ResponseWriter, r *http.Request) {
 	res, err := h.db.ExecContext(r.Context(),
 		"UPDATE teams SET "+strings.Join(sets, ", ")+" WHERE id = ?", args...) // #nosec G202 -- sets is built above from hardcoded "col = ?" literals only; every value is bound via args...
 	if err != nil {
-		if strings.Contains(err.Error(), "UNIQUE constraint failed") {
+		if db.IsUniqueViolation(err) {
 			h.writeError(w, http.StatusConflict, "a team with that slug already exists")
 			return
 		}
@@ -306,7 +307,7 @@ func (h *Handler) AddTeamMember(w http.ResponseWriter, r *http.Request) {
 		INSERT INTO team_members (id, team_id, user_id, role, routing_priority)
 		VALUES (?, ?, ?, 'member', ?)`,
 		uid.New(), teamID, req.UserID, req.RoutingPriority); err != nil {
-		if strings.Contains(err.Error(), "UNIQUE constraint failed") {
+		if db.IsUniqueViolation(err) {
 			h.writeError(w, http.StatusConflict, "that user is already in this team")
 			return
 		}

From 4b86071e55115ac59e6975ecdf44533ce8db0825 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 04:12:53 -0400
Subject: [PATCH 09/51] db: the last four things only SQLite accepted
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

With the constraint predicates in, eight Postgres failures were left, and they were
four unrelated causes rather than one.

Computed booleans. "(user_id = ?) AS owned" and "(archived_at IS NOT NULL) AS
archived" are 0/1 on SQLite and a boolean on PostgreSQL, and the boolean does not
scan into the int the real 0/1 columns beside them use — "converting driver.Value
type bool to a int". Both are CASE WHEN ... THEN 1 ELSE 0 END now: portable, and
the same 0/1 convention the schema uses for stored flags, so the != 0 idiom in the
scanner is untouched.

json_extract in production. replaceReminderJobs deleted a booking's reminder jobs
by filtering on json_extract(payload, '$.booking_id'), a SQLite JSON1 function. On
PostgreSQL the DELETE errored, so rescheduling silently left the old reminder in
place — a real bug, not just a red test. No portable spelling exists, so this is a
Dialect.SQL pair: payload::json ->> 'booking_id', with the cast because the column
is TEXT rather than json.

ORDER BY rowid. webhook_deliveries had no timestamp of its own, so "the 50 most
recent" was rowid DESC. PostgreSQL has no rowid, and the query was not strictly
correct on SQLite either: rowid tracks insertion order only until something
renumbers it, and VACUUM may. Migration 00058 adds created_at to both dirs, the
writer binds it, and the order is created_at DESC, id DESC — the tiebreak because
two deliveries written in the same millisecond would otherwise come back in
whatever order the engine felt like. The default is a constant '' rather than a
timestamp expression because SQLite's ALTER TABLE ADD COLUMN forbids a
parenthesised DEFAULT; rows predating the migration sort last, which is where the
oldest deliveries belong.

randomblob in a gcal test helper: SQLite's id generator, swapped for uid.New(),
which is what every other row in those tests already used.

Two test changes, neither of them an assertion:

  - reschedule_test held its own copy of the json_extract expression AND discarded
    the Scan error, so "function json_extract does not exist" surfaced two seconds
    later as time.Parse failing on "". It now uses the same dialect pair and
    reports the query error, so the next engine difference names itself.

  - postgres_test pinned the migration count as the literal 57 in two places. It is
    now one named constant at 58, so adding a migration is a single edit that
    cannot be half-done.

go test -count=1 ./... is green on both engines from this commit: 28 of 28 packages
on SQLite, 28 of 28 on PostgreSQL.
---
 PROGRESS.md                                   | 59 +++++++++++++------
 .../00058_webhook_delivery_created_at.sql     | 16 +++++
 .../00058_webhook_delivery_created_at.sql     | 15 +++++
 internal/db/postgres_test.go                  | 14 +++--
 internal/gcal/gcal_test.go                    |  8 ++-
 internal/handler/booking_handler.go           | 18 ++++--
 internal/handler/event_type.go                | 12 ++--
 internal/handler/reschedule_test.go           | 16 ++++-
 internal/webhook/webhook.go                   | 12 ++--
 9 files changed, 132 insertions(+), 38 deletions(-)
 create mode 100644 internal/db/migrations/postgres/00058_webhook_delivery_created_at.sql
 create mode 100644 internal/db/migrations/sqlite/00058_webhook_delivery_created_at.sql

diff --git a/PROGRESS.md b/PROGRESS.md
index c27f40b..e586221 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -120,23 +120,48 @@ default path).
   `CALNODE_TEST_POSTGRES_DSN` set for `go test ./...`. Additive — with the variable
   unset nothing about an existing run changes.
 
-## Blocked on the database layer
-
-`internal/db/migrations/postgres` does not exist yet (`db.go` embeds
-`migrations/sqlite/*.sql` only), so nothing can migrate on Postgres. Measured, not
-assumed: with the DSN set, `dbtest.Open` fails with
-`migrate postgres: run migrations: migrations/postgres directory does not exist`.
-Everything on this branch is written against `h.Migrate()` and starts working the
-moment those land; until then the new `postgres` CI job will be red for that reason
-and the Boundary 3 proof stands on the temporary hand-written schema recorded above.
-
-## Findings for whoever owns the schema
-
-1. **Booleans.** The tree stores them as `INTEGER` and compares them literally —
-   `email_login = 1`, `is_organizer = 1`, `is_destination = 1`, `boolToInt(...)`.
-   If the Postgres migrations declare those columns `BOOLEAN`, every one of those
-   comparisons is a type error. `SMALLINT`/`INTEGER` keeps the whole tree working
-   unchanged.
+## No longer blocked
+
+`migrations/postgres` landed with `feat/postgres-core`, so the `postgres` CI job now
+has something to migrate and passes.
+
+## Boundary 5 — the suite actually green on both engines — DONE
+
+Rebased onto the finished `feat/postgres-core`, so `migrations/postgres` exists and
+the suite could finally run against PostgreSQL. **15 failures**, four distinct
+causes — not the one the first triage suggested.
+
+1. **Constraint classification (7 failures).** Thirteen sites decided 409/400/404
+   vs 500 by substring-matching SQLite's English error text. `internal/db` now
+   exports `IsUniqueViolation` / `IsCheckViolation` / `IsForeignKeyViolation`,
+   matching SQLSTATE 23505 / 23514 / 23503 on Postgres and the message on SQLite.
+   Pinned by `constraint_test.go`, which provokes a real violation of each class
+   against the real schema on whichever engine is configured, asserts exactly one
+   of three predicates matches, and asserts none match an unrelated error.
+2. **Engine-dependent boolean expressions (2 failures).** `(user_id = ?) AS owned`
+   and `(archived_at IS NOT NULL) AS archived` yield 0/1 on SQLite and a boolean on
+   Postgres, which does not scan into the `int` the columns beside them use. Both
+   are now `CASE WHEN … THEN 1 ELSE 0 END`, portable and matching the schema's own
+   0/1 convention.
+3. **`json_extract` in production (1 failure).** `replaceReminderJobs` filtered on
+   `json_extract(payload, '$.booking_id')`. No portable spelling exists, so this is
+   a second `d.SQL` pair: `payload::json ->> 'booking_id'` on Postgres (the cast is
+   needed because the column is TEXT). The reschedule test carried its own copy of
+   the same expression, and discarded the `Scan` error, so the real failure showed
+   up two seconds later as a time-parsing error.
+4. **`ORDER BY rowid` (3 failures).** `webhook_deliveries` had no timestamp of its
+   own, so recency was `rowid DESC` — unportable, and not strictly correct on
+   SQLite either, since VACUUM may renumber rowids. Migration **00058** adds
+   `created_at TEXT NOT NULL DEFAULT ''` to both dirs, the writer binds
+   `dbtime.NowMilli()`, and the query is `ORDER BY created_at DESC, id DESC`.
+5. **`randomblob` in a gcal test helper (2 failures).** SQLite-only id generator,
+   replaced with `uid.New()` like every other row in those tests.
+
+Both suites green in one commit: 28/28 packages on SQLite, 28/28 on PostgreSQL.
+
+1. **Booleans — resolved.** The Postgres migrations declare them `SMALLINT`, so the
+   tree's `= 1` comparisons and `boolToInt(...)` work unchanged. Only *computed*
+   boolean expressions in SELECT lists needed a fix (Boundary 5, cause 2).
 2. **Text timestamp collation.** Timestamps are `TEXT` and compared
    lexicographically on purpose (the recordings consent window, the job queue's
    `run_at <= ?`). That is byte ordering under SQLite. Under a non-`C` Postgres
diff --git a/internal/db/migrations/postgres/00058_webhook_delivery_created_at.sql b/internal/db/migrations/postgres/00058_webhook_delivery_created_at.sql
new file mode 100644
index 0000000..2892396
--- /dev/null
+++ b/internal/db/migrations/postgres/00058_webhook_delivery_created_at.sql
@@ -0,0 +1,16 @@
+-- +goose Up
+-- webhook_deliveries had no timestamp of its own, so "the 50 most recent deliveries"
+-- was expressed as ORDER BY rowid DESC. That is unportable — PostgreSQL has no rowid —
+-- and it was never quite correct here either: SQLite's rowid tracks insertion order
+-- only until something renumbers it, and VACUUM is allowed to.
+--
+-- The default is a constant empty string rather than a timestamp expression, matching
+-- the SQLite half (whose ALTER TABLE ADD COLUMN forbids a parenthesised DEFAULT) so the
+-- two engines backfill existing rows identically. New rows get their value bound by the
+-- writer (internal/webhook). Rows that predate this migration keep '', which sorts last
+-- under ORDER BY created_at DESC — correct, since they are the oldest deliveries on the
+-- instance.
+ALTER TABLE webhook_deliveries ADD COLUMN created_at TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE webhook_deliveries DROP COLUMN created_at;
diff --git a/internal/db/migrations/sqlite/00058_webhook_delivery_created_at.sql b/internal/db/migrations/sqlite/00058_webhook_delivery_created_at.sql
new file mode 100644
index 0000000..866ba46
--- /dev/null
+++ b/internal/db/migrations/sqlite/00058_webhook_delivery_created_at.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+-- webhook_deliveries had no timestamp of its own, so "the 50 most recent deliveries"
+-- was expressed as ORDER BY rowid DESC. That is unportable — PostgreSQL has no rowid —
+-- and it was never quite correct here either: SQLite's rowid tracks insertion order
+-- only until something renumbers it, and VACUUM is allowed to.
+--
+-- The default is a constant empty string rather than a timestamp expression because
+-- SQLite's ALTER TABLE ADD COLUMN forbids a parenthesised or non-deterministic DEFAULT.
+-- New rows get their value bound by the writer (internal/webhook). Rows that predate
+-- this migration keep '', which sorts last under ORDER BY created_at DESC — correct,
+-- since they are the oldest deliveries on the instance.
+ALTER TABLE webhook_deliveries ADD COLUMN created_at TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE webhook_deliveries DROP COLUMN created_at;
diff --git a/internal/db/postgres_test.go b/internal/db/postgres_test.go
index e3b43a1..3e59614 100644
--- a/internal/db/postgres_test.go
+++ b/internal/db/postgres_test.go
@@ -22,6 +22,12 @@ import (
 //	CALNODE_TEST_POSTGRES_DSN=postgres://postgres:pw@127.0.0.1:5432/calnode?sslmode=disable
 const postgresDSNEnv = "CALNODE_TEST_POSTGRES_DSN"
 
+// knownMigrationCount is the version a fully-migrated database must report. It is a
+// sanity check on the embedded set, not a property of PostgreSQL, so it moves with
+// every migration added — one named constant rather than the same literal in two
+// assertions, so adding one is a single edit that cannot be half-done.
+const knownMigrationCount = 58
+
 // openTestPostgres returns a handle scoped to a schema of its own, created for
 // this test and dropped when it finishes. A schema rather than a database because
 // CREATE DATABASE cannot run inside a transaction and cannot be reached over the
@@ -130,8 +136,8 @@ func TestPostgres_migrateToTargetVersion(t *testing.T) {
 	if applied != target {
 		t.Errorf("applied version = %d; want target %d", applied, target)
 	}
-	if target != 57 {
-		t.Errorf("target version = %d; want 57 (sanity check against the known migration set)", target)
+	if target != knownMigrationCount {
+		t.Errorf("target version = %d; want %d (sanity check against the known migration set)", target, knownMigrationCount)
 	}
 
 	ready, err := db.SchemaReady(ctx, handle.DB)
@@ -167,8 +173,8 @@ func TestPostgres_migrateViaPackageFunc(t *testing.T) {
 	if err != nil {
 		t.Fatalf("AppliedVersion: %v", err)
 	}
-	if applied != 57 {
-		t.Errorf("applied version = %d; want 57", applied)
+	if applied != knownMigrationCount {
+		t.Errorf("applied version = %d; want %d", applied, knownMigrationCount)
 	}
 }
 
diff --git a/internal/gcal/gcal_test.go b/internal/gcal/gcal_test.go
index 0e7dd9f..31780d6 100644
--- a/internal/gcal/gcal_test.go
+++ b/internal/gcal/gcal_test.go
@@ -10,6 +10,7 @@ import (
 
 	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/uid"
 )
 
 // testKeyHex is a valid 64-char hex key (32 bytes) used across tests.
@@ -314,10 +315,13 @@ func insertConnCal(t *testing.T, db *db.DB, userID, account, calID string, check
 	if check {
 		cc = 1
 	}
+	// uid.New() rather than lower(hex(randomblob(16))): randomblob is a SQLite
+	// built-in with no PostgreSQL counterpart, and every other row in these tests
+	// already gets its id from uid.
 	_, err := db.ExecContext(context.Background(), `
 		INSERT INTO connection_calendars (id, user_id, provider, account_email, calendar_id, name, check_conflicts, is_destination)
-		VALUES (lower(hex(randomblob(16))), ?, 'google', ?, ?, '', ?, 0)`,
-		userID, account, calID, cc)
+		VALUES (?, ?, 'google', ?, ?, '', ?, 0)`,
+		uid.New(), userID, account, calID, cc)
 	if err != nil {
 		t.Fatalf("insertConnCal(%q): %v", calID, err)
 	}
diff --git a/internal/handler/booking_handler.go b/internal/handler/booking_handler.go
index 7f85e84..2f558d3 100644
--- a/internal/handler/booking_handler.go
+++ b/internal/handler/booking_handler.go
@@ -1938,11 +1938,19 @@ func (h *Handler) replaceReminderJobs(ctx context.Context, bookingID, etID strin
 	}
 	defer tx.Rollback() //nolint:errcheck
 
-	if _, err := tx.ExecContext(ctx, `
-		DELETE FROM jobs
-		WHERE type = 'reminder.send'
-		  AND json_extract(payload, '$.booking_id') = ?
-		  AND status != 'running'`, bookingID); err != nil {
+	// jobs.payload is TEXT holding JSON, and extracting a field out of it is the one
+	// operation here with no spelling both engines accept: json_extract is SQLite's
+	// JSON1 function, ->> needs an explicit cast because the column is TEXT rather
+	// than json. Hence a dialect pair rather than one statement.
+	if _, err := tx.ExecContext(ctx, tx.Dialect().SQL(
+		`DELETE FROM jobs
+		 WHERE type = 'reminder.send'
+		   AND json_extract(payload, '$.booking_id') = ?
+		   AND status != 'running'`,
+		`DELETE FROM jobs
+		 WHERE type = 'reminder.send'
+		   AND payload::json ->> 'booking_id' = ?
+		   AND status != 'running'`), bookingID); err != nil {
 		return fmt.Errorf("replace reminder jobs: delete: %w", err)
 	}
 
diff --git a/internal/handler/event_type.go b/internal/handler/event_type.go
index 949dacb..b97ae09 100644
--- a/internal/handler/event_type.go
+++ b/internal/handler/event_type.go
@@ -162,8 +162,12 @@ const selectETCols = "SELECT " + etColumns + " FROM event_types"
 // listEventTypesQuery returns every event type the user owns OR is an assigned
 // host on, with an `owned` flag (the owner is also seeded into event_type_hosts,
 // so ownership is keyed on event_types.user_id, not host membership).
-const listEventTypesQuery = "SELECT " + etColumns + `, (user_id = ?) AS owned,
-	(archived_at IS NOT NULL) AS archived
+//
+// The two flags are CASE expressions rather than bare comparisons because a bare
+// comparison's type is engine-dependent: SQLite yields 0/1 and PostgreSQL yields a
+// boolean, and the boolean does not scan into the int the 0/1 columns beside it use.
+const listEventTypesQuery = "SELECT " + etColumns + `, CASE WHEN user_id = ? THEN 1 ELSE 0 END AS owned,
+	CASE WHEN archived_at IS NOT NULL THEN 1 ELSE 0 END AS archived
 FROM event_types
 WHERE user_id = ?
    OR id IN (SELECT event_type_id FROM event_type_hosts WHERE user_id = ?)
@@ -172,10 +176,10 @@ ORDER BY created_at`
 // getEventTypeQuery fetches one event type by slug if the user owns it or hosts
 // it, with the `owned` flag and the owner's name/email (so a read-only host knows
 // who to contact for changes).
-const getEventTypeQuery = "SELECT " + etColumns + `, (user_id = ?) AS owned,
+const getEventTypeQuery = "SELECT " + etColumns + `, CASE WHEN user_id = ? THEN 1 ELSE 0 END AS owned,
 	(SELECT name FROM users WHERE id = event_types.user_id) AS owner_name,
 	(SELECT email FROM users WHERE id = event_types.user_id) AS owner_email,
-	(archived_at IS NOT NULL) AS archived
+	CASE WHEN archived_at IS NOT NULL THEN 1 ELSE 0 END AS archived
 FROM event_types
 WHERE slug = ? AND (user_id = ? OR id IN (SELECT event_type_id FROM event_type_hosts WHERE user_id = ?))`
 
diff --git a/internal/handler/reschedule_test.go b/internal/handler/reschedule_test.go
index 26a01c7..7390481 100644
--- a/internal/handler/reschedule_test.go
+++ b/internal/handler/reschedule_test.go
@@ -106,13 +106,22 @@ func TestRescheduleBooking_updatesReminderJob(t *testing.T) {
 
 	// replaceReminderJobs deletes old jobs and inserts fresh ones keyed by booking_id.
 	// Poll until a pending reminder job with the correct run_at appears.
+	//
+	// The JSON lookup is a dialect pair for the same reason the production statement
+	// is one. The Scan error is captured rather than discarded: swallowing it turned a
+	// "json_extract does not exist" into an empty run_at and a two-second poll that
+	// then reported itself as a time-parsing failure.
 	var runAt string
+	var lastErr error
+	payloadMatch := database.Dialect().SQL(
+		`json_extract(payload, '$.booking_id') = ?`,
+		`payload::json ->> 'booking_id' = ?`)
 	deadline := time.Now().Add(2 * time.Second)
 	for time.Now().Before(deadline) {
-		database.QueryRowContext(ctx, `
+		lastErr = database.QueryRowContext(ctx, `
 			SELECT run_at FROM jobs
 			WHERE type = 'reminder.send'
-			  AND json_extract(payload, '$.booking_id') = ?
+			  AND `+payloadMatch+`
 			  AND status = 'pending'`, bookingID).
 			Scan(&runAt)
 		if runAt != "" && runAt != oldReminderAt.Format(time.RFC3339) {
@@ -120,6 +129,9 @@ func TestRescheduleBooking_updatesReminderJob(t *testing.T) {
 		}
 		time.Sleep(10 * time.Millisecond)
 	}
+	if runAt == "" {
+		t.Fatalf("no pending reminder job appeared within 2s; last query error: %v", lastErr)
+	}
 
 	gotRunAt, err := time.Parse(time.RFC3339, runAt)
 	if err != nil {
diff --git a/internal/webhook/webhook.go b/internal/webhook/webhook.go
index 49d8280..850bf94 100644
--- a/internal/webhook/webhook.go
+++ b/internal/webhook/webhook.go
@@ -18,6 +18,7 @@ import (
 	"time"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/uid"
 )
 
@@ -446,9 +447,9 @@ func (s *Service) Enqueue(ctx context.Context, event string, p BookingPayload) e
 		deliveryID := uid.New()
 		jobID := uid.New()
 		if _, err := tx.ExecContext(ctx, `
-			INSERT INTO webhook_deliveries (id, webhook_id, booking_id, event, payload, status)
-			VALUES (?, ?, ?, ?, ?, 'pending')`,
-			deliveryID, wh.id, bookingIDArg, event, string(payloadBytes)); err != nil {
+			INSERT INTO webhook_deliveries (id, webhook_id, booking_id, event, payload, status, created_at)
+			VALUES (?, ?, ?, ?, ?, 'pending', ?)`,
+			deliveryID, wh.id, bookingIDArg, event, string(payloadBytes), dbtime.NowMilli()); err != nil {
 			return fmt.Errorf("webhook: insert delivery: %w", err)
 		}
 		jobPayload, _ := json.Marshal(map[string]string{"webhook_delivery_id": deliveryID})
@@ -473,11 +474,14 @@ func (s *Service) ListDeliveries(ctx context.Context, userID, webhookID string)
 		return nil, ErrNotFound
 	}
 
+	// created_at DESC rather than rowid DESC: rowid is SQLite-only, and id is a random
+	// uid so it carries no recency. The id tiebreak makes two deliveries written in the
+	// same millisecond a stable order rather than whatever the engine returns.
 	rows, err := s.db.QueryContext(ctx, `
 		SELECT id, COALESCE(booking_id,''), event, status,
 		       response_status, attempt_count, last_attempted_at
 		FROM webhook_deliveries WHERE webhook_id = ?
-		ORDER BY rowid DESC LIMIT 50`, webhookID)
+		ORDER BY created_at DESC, id DESC LIMIT 50`, webhookID)
 	if err != nil {
 		return nil, fmt.Errorf("webhook: list deliveries: %w", err)
 	}

From 9c7792eda7fd5d59919591a4f29dca220efa6a91 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 04:35:48 -0400
Subject: [PATCH 10/51] db: classify constraint violations by SQLite's codes
 too, not its prose
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The comment in constraint.go claimed modernc.org/sqlite exposes no error codes.
That was wrong. It defines type Error with Code(), populated for every constraint
class, and the codes are SQLite's extended result codes. Measured against a real
in-memory database rather than read off a doc page:

  UNIQUE 2067, PRIMARY KEY 1555, CHECK 275, FOREIGN KEY 787, NOT NULL 1299

⛔ The reason this is worth a commit rather than a tidy-up: a PRIMARY KEY collision
reports 1555, NOT 2067, while still saying "UNIQUE constraint failed" in its
message. The text match caught both by accident. Switching to Code() == 2067 alone
would silently stop recognising primary-key collisions — and Calnode has one that
matters: idempotency_keys.idempotency_key is a bare PRIMARY KEY, so every idempotent
replay arrives as 1555. Verified by removing 1555 and re-running: the new subtest
fails naming the code and the table, and TestCreateBooking_idempotentReplay goes to
"replay: 500". So the regression was real, not theoretical.

IsUniqueViolation therefore matches BOTH 2067 and 1555. PostgreSQL needs no
equivalent change: a primary-key collision is 23505 like any other unique violation,
which is why the trap exists on only one side. Constants are named after the SQLite
symbols so the numbers are greppable.

The text comparison stays as a fallback, and only as a fallback. It covers an error
that arrives without its concrete driver type attached — a driver release that
changes the type, a layer that reformats rather than wraps — where the message is the
only signal left and answering from it beats returning a 500. TestConstraintTextFallback
exercises that branch directly, so it is not unexecuted code that reads like an
accident. A *pgconn.PgError or a *sqlite.Error whose code does not match is a
DEFINITE no and does not fall through: falling through would reintroduce this very
trap in reverse, readmitting a 1555 by its message after excluding it by code.

Also fixes a flake in the dbtest harness, which is what the two intermittent
handler failures under `go test ./...` actually were — not an application fault.
Calnode's handlers do several things fire-and-forget (notify hosts, enqueue webhook,
enqueue reminders), those goroutines outlive the test body, and closing the pool does
not stop an in-flight statement. DROP SCHEMA CASCADE needs an exclusive lock on every
object, meets them, and PostgreSQL reports "deadlock detected" (40P01) — visible only
under the full run, where packages compete and everything is slower, in a different
pair of tests each time. The drop now runs on a pinned connection with lock_timeout
set so an attempt fails fast instead of deadlocking, and retries within a bounded
budget; a schema that still cannot be dropped is reported, because a leaked schema
accumulates on a shared server.
---
 internal/db/constraint.go      | 82 ++++++++++++++++++++++++----------
 internal/db/constraint_test.go | 66 +++++++++++++++++++++++++++
 internal/dbtest/dbtest.go      | 49 +++++++++++++++++++-
 3 files changed, 172 insertions(+), 25 deletions(-)

diff --git a/internal/db/constraint.go b/internal/db/constraint.go
index 5203cbf..6b44e13 100644
--- a/internal/db/constraint.go
+++ b/internal/db/constraint.go
@@ -2,69 +2,103 @@ package db
 
 import (
 	"errors"
+	"slices"
 	"strings"
 
 	"github.com/jackc/pgx/v5/pgconn"
+	"modernc.org/sqlite"
 )
 
 // Constraint violations are the one class of database error Calnode routinely acts
 // on rather than just reporting: a duplicate slug is a 409, an out-of-range value is
 // a 400, a dangling reference is a 404. Deciding which is which used to be a
 // substring match on SQLite's English message, which is invisible to every gate and
-// silently degrades to a 500 on PostgreSQL.
+// degraded silently to a 500 on PostgreSQL.
 //
-// PostgreSQL is matched on SQLSTATE because that is the only stable handle: the
-// message text is localised by the server's lc_messages, so a server running in
-// German would defeat any text match. SQLite has no error codes exposed through
-// modernc.org/sqlite's error value, so its half stays a text match — which is what
-// it always was, and it is pinned by a test that provokes a real violation.
+// Both engines are matched on their error codes. Codes rather than text because the
+// text is not a contract: PostgreSQL localises its messages by the server's
+// lc_messages, so a server running in German defeats any text match no matter how
+// carefully written.
 const (
-	pgUniqueViolation     = "23505"
-	pgCheckViolation      = "23514"
-	pgForeignKeyViolation = "23503"
+	pgUniqueViolation     = "23505" // unique_violation, and PostgreSQL's code for a primary-key collision too
+	pgCheckViolation      = "23514" // check_violation
+	pgForeignKeyViolation = "23503" // foreign_key_violation
 )
 
-// SQLite's messages for the same three classes.
+// SQLite's extended result codes, as reported by (*sqlite.Error).Code().
+//
+// ⛔ SQLITE_CONSTRAINT_PRIMARYKEY is a SEPARATE code from
+// SQLITE_CONSTRAINT_UNIQUE even though both carry the message "UNIQUE constraint
+// failed". Matching only 2067 would silently stop recognising primary-key
+// collisions, and Calnode has one that matters: idempotency_keys.idempotency_key is
+// a bare PRIMARY KEY, so every idempotent replay arrives as 1555. Both belong to
+// IsUniqueViolation. PostgreSQL has no such split — a primary-key collision is
+// 23505 like any other unique violation — which is why the trap only exists on one
+// side.
 const (
-	sqliteUniqueViolation     = "UNIQUE constraint failed"
-	sqliteCheckViolation      = "CHECK constraint failed"
-	sqliteForeignKeyViolation = "FOREIGN KEY constraint failed"
+	sqliteConstraintCheck      = 275  // SQLITE_CONSTRAINT_CHECK
+	sqliteConstraintForeignKey = 787  // SQLITE_CONSTRAINT_FOREIGNKEY
+	sqliteConstraintPrimaryKey = 1555 // SQLITE_CONSTRAINT_PRIMARYKEY
+	sqliteConstraintUnique     = 2067 // SQLITE_CONSTRAINT_UNIQUE
+)
+
+// SQLite's message fragments, used only as a fallback — see violates.
+const (
+	sqliteUniqueText     = "UNIQUE constraint failed"
+	sqliteCheckText      = "CHECK constraint failed"
+	sqliteForeignKeyText = "FOREIGN KEY constraint failed"
 )
 
 // IsUniqueViolation reports whether err is a unique-constraint violation — a
 // duplicate slug, a replayed idempotency key, a second booking at one host's exact
-// start time.
+// start time. A primary-key collision counts, on both engines.
 func IsUniqueViolation(err error) bool {
-	return violates(err, pgUniqueViolation, sqliteUniqueViolation)
+	return violates(err, pgUniqueViolation, sqliteUniqueText,
+		sqliteConstraintUnique, sqliteConstraintPrimaryKey)
 }
 
 // IsCheckViolation reports whether err is a CHECK-constraint violation, i.e. a value
 // outside the set the column allows. Callers turn this into a 400, since the only way
 // to reach it is a request carrying a value the handler did not validate.
 func IsCheckViolation(err error) bool {
-	return violates(err, pgCheckViolation, sqliteCheckViolation)
+	return violates(err, pgCheckViolation, sqliteCheckText, sqliteConstraintCheck)
 }
 
 // IsForeignKeyViolation reports whether err is a foreign-key violation — a reference
 // to a row that does not exist, or a delete that would orphan one.
 func IsForeignKeyViolation(err error) bool {
-	return violates(err, pgForeignKeyViolation, sqliteForeignKeyViolation)
+	return violates(err, pgForeignKeyViolation, sqliteForeignKeyText, sqliteConstraintForeignKey)
 }
 
-// violates is the shared shape: SQLSTATE when the error came from PostgreSQL, the
-// message otherwise.
+// violates classifies err: the driver's own error code when one is available, the
+// message only when it is not.
+//
+// A driver error is a DEFINITE answer in both directions. A *pgconn.PgError or a
+// *sqlite.Error whose code does not match returns false and does not fall through to
+// the text comparison — falling through would classify an error by whether its
+// message happened to contain an English phrase, which is the fragility being
+// removed. It would also reintroduce the primary-key trap in reverse: a 1555 error
+// excluded by code would be readmitted by its "UNIQUE constraint failed" message.
 //
-// A *pgconn.PgError whose code does NOT match returns false rather than falling
-// through to the text comparison. Falling through would let a PostgreSQL error be
-// classified by whether its message happened to contain an English phrase from
-// another engine, which is exactly the fragility being removed here.
-func violates(err error, sqlstate, sqliteText string) bool {
+// The text fallback is deliberate rather than vestigial. It covers an error that
+// reaches here without the concrete driver type still attached — a driver release
+// that changes its error type, a layer that reformats an error into a plain one
+// instead of wrapping it. In that case the message is the only signal left, and
+// answering from it beats answering "not a constraint violation" and returning a 500.
+func violates(err error, sqlstate, sqliteText string, sqliteCodes ...int) bool {
 	if err == nil {
 		return false
 	}
+
 	var pgErr *pgconn.PgError
 	if errors.As(err, &pgErr) {
 		return pgErr.Code == sqlstate
 	}
+
+	var sqliteErr *sqlite.Error
+	if errors.As(err, &sqliteErr) {
+		return slices.Contains(sqliteCodes, sqliteErr.Code())
+	}
+
 	return strings.Contains(err.Error(), sqliteText)
 }
diff --git a/internal/db/constraint_test.go b/internal/db/constraint_test.go
index 2a0a87d..151c570 100644
--- a/internal/db/constraint_test.go
+++ b/internal/db/constraint_test.go
@@ -43,6 +43,31 @@ func TestConstraintPredicates(t *testing.T) {
 		assertOnly(t, err, "unique", db.IsUniqueViolation)
 	})
 
+	// ⛔ The case that distinguishes a correct implementation from a plausible one.
+	//
+	// SQLite reports a PRIMARY KEY collision as SQLITE_CONSTRAINT_PRIMARYKEY (1555),
+	// NOT as SQLITE_CONSTRAINT_UNIQUE (2067) — while still saying "UNIQUE constraint
+	// failed" in the message. So a predicate matching only 2067 passes the subtest
+	// above and fails here, and the old text match passed both by accident.
+	//
+	// This is not a theoretical shape: idempotency_keys.idempotency_key is a bare
+	// PRIMARY KEY, so claimIdempotencyKey's entire replay path depends on 1555 being
+	// classified as a unique violation. PostgreSQL reports 23505 for both, so this
+	// subtest is redundant there — and it runs there anyway, because "redundant on
+	// one engine" is exactly the assumption worth re-checking after a driver bump.
+	t.Run("unique via primary key", func(t *testing.T) {
+		key := uid.New()
+		if _, err := h.Exec(
+			`INSERT INTO idempotency_keys (idempotency_key, request_hash, created_at) VALUES (?, 'h', ?)`,
+			key, "2026-06-01T00:00:00Z"); err != nil {
+			t.Fatalf("seed idempotency key: %v", err)
+		}
+		_, err := h.Exec(
+			`INSERT INTO idempotency_keys (idempotency_key, request_hash, created_at) VALUES (?, 'h', ?)`,
+			key, "2026-06-01T00:00:00Z")
+		assertOnly(t, err, "primary key", db.IsUniqueViolation)
+	})
+
 	t.Run("check", func(t *testing.T) {
 		// bookings.status has CHECK (status IN ('confirmed','cancelled')).
 		_, err := h.Exec(`
@@ -73,6 +98,47 @@ func TestConstraintPredicates(t *testing.T) {
 		assertNone(t, errors.New("some unrelated failure"), "plain error")
 		assertNone(t, nil, "nil")
 	})
+
+	t.Run("unhandled constraint class", func(t *testing.T) {
+		// A NOT NULL violation is a constraint violation of a class nothing here
+		// classifies (SQLite 1299, PostgreSQL 23502). It must match none of the
+		// three, so a caller cannot turn it into a 409 by accident.
+		_, err := h.Exec(
+			`INSERT INTO users (id, email, name, iana_timezone) VALUES (?, ?, NULL, 'UTC')`,
+			uid.New(), uid.New()+"@example.com")
+		if err == nil {
+			t.Fatal("expected a NOT NULL violation")
+		}
+		assertNone(t, err, "not-null violation")
+	})
+}
+
+// TestConstraintTextFallback covers the branch no live engine reaches: an error that
+// arrives without its driver type still attached.
+//
+// It is engine-independent, so it needs no database. The branch exists for a driver
+// release that changes its error type, or a layer that reformats an error into a
+// plain one rather than wrapping it — in which case the message is the only signal
+// left, and answering from it beats returning a 500. Without this test the fallback
+// would be unexecuted code that reads like an accident.
+func TestConstraintTextFallback(t *testing.T) {
+	cases := []struct {
+		text string
+		want func(error) bool
+		name string
+	}{
+		{"boom: UNIQUE constraint failed: t.a", db.IsUniqueViolation, "unique"},
+		{"boom: CHECK constraint failed: n > 0", db.IsCheckViolation, "check"},
+		{"boom: FOREIGN KEY constraint failed", db.IsForeignKeyViolation, "foreign key"},
+	}
+	for _, c := range cases {
+		err := errors.New(c.text)
+		if !c.want(err) {
+			t.Errorf("%s: fallback did not recognise %q", c.name, c.text)
+		}
+	}
+	// And the fallback is still discriminating, not a catch-all.
+	assertNone(t, errors.New("NOT NULL constraint failed: t.a"), "not-null text")
 }
 
 // assertOnly checks that want recognises err and the other two predicates do not:
diff --git a/internal/dbtest/dbtest.go b/internal/dbtest/dbtest.go
index 7610709..b0cbba4 100644
--- a/internal/dbtest/dbtest.go
+++ b/internal/dbtest/dbtest.go
@@ -9,11 +9,13 @@
 package dbtest
 
 import (
+	"context"
 	"crypto/rand"
 	"encoding/hex"
 	"net/url"
 	"os"
 	"testing"
+	"time"
 
 	"github.com/calnode/calnode/internal/db"
 )
@@ -88,7 +90,7 @@ func openPostgres(t *testing.T, dsn string) *db.DB {
 	// below has been closed.
 	t.Cleanup(func() {
 		defer admin.Close()
-		if _, err := admin.Exec(`DROP SCHEMA ` + quoteIdent(schema) + ` CASCADE`); err != nil {
+		if err := dropSchema(admin, schema); err != nil {
 			t.Errorf("dbtest: drop schema %s: %v", schema, err)
 		}
 	})
@@ -105,6 +107,51 @@ func openPostgres(t *testing.T, dsn string) *db.DB {
 	return h
 }
 
+// dropSchema drops the test's schema, retrying while work the test started is still
+// finishing.
+//
+// Calnode's handlers do several things fire-and-forget: a booking spawns goroutines
+// to notify hosts, enqueue the webhook and enqueue reminders. Those outlive the test
+// BODY, and closing the pool does not stop them — database/sql closes idle
+// connections and lets in-flight statements run to completion. DROP SCHEMA CASCADE
+// needs an exclusive lock on every object in the schema, so it meets those
+// statements and PostgreSQL reports "deadlock detected" (SQLSTATE 40P01). It showed
+// up only under `go test ./...`, where packages run concurrently and everything is
+// slower — two handler tests out of several hundred, in a different pair each run.
+//
+// lock_timeout is what makes retrying viable: without it the DROP either waits
+// indefinitely or is chosen as a deadlock victim. With it the attempt fails fast and
+// cheaply, and the background work it was contending with has finished by the next
+// one. The budget is bounded so a schema that genuinely cannot be dropped is
+// reported rather than waited on forever — a leaked schema accumulates on a shared
+// server, so it is worth failing the test over.
+//
+// The statements run on ONE pinned connection because lock_timeout is per-session
+// and the pool would otherwise be free to apply the SET to a different connection
+// than the DROP. Neither statement has placeholders, so nothing needs rebinding.
+func dropSchema(admin *db.DB, schema string) error {
+	ctx := context.Background()
+	conn, err := admin.Conn(ctx)
+	if err != nil {
+		return err
+	}
+	defer conn.Close() //nolint:errcheck // returning the drop's error is more useful
+
+	if _, err := conn.ExecContext(ctx, `SET lock_timeout = '250ms'`); err != nil {
+		return err
+	}
+
+	const attempts = 20 // ~5s of wall clock, against background work that takes ms
+	var lastErr error
+	for i := 0; i < attempts; i++ {
+		if _, lastErr = conn.ExecContext(ctx, `DROP SCHEMA `+quoteIdent(schema)+` CASCADE`); lastErr == nil {
+			return nil
+		}
+		time.Sleep(250 * time.Millisecond)
+	}
+	return lastErr
+}
+
 // withSearchPath returns dsn with search_path pointed at schema. pgx passes
 // unrecognised query parameters through as PostgreSQL runtime parameters, so this
 // is the whole of the isolation: goose writes goose_db_version there, the

From 26f17b6979006710f66694de9d53b6ab2c3a58e7 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Fri, 4 Sep 2026 04:46:04 -0400
Subject: [PATCH 11/51] docs: record the SQLite error-code correction on the
 branch log

Includes the measured code table, the primary-key trap and how it was proved, and
the dbtest teardown deadlock that the two intermittent handler failures actually
were.
---
 PROGRESS.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/PROGRESS.md b/PROGRESS.md
index e586221..3db55d1 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -159,6 +159,42 @@ causes — not the one the first triage suggested.
 
 Both suites green in one commit: 28/28 packages on SQLite, 28/28 on PostgreSQL.
 
+## Boundary 6 — constraint codes on BOTH engines — DONE
+
+The first version of `constraint.go` claimed modernc.org/sqlite exposes no error
+codes and matched SQLite on message text. That was false: it defines `type Error`
+with `Code()`, populated for every constraint class. Measured, not read:
+
+| violation | SQLite `Code()` | PostgreSQL SQLSTATE |
+|---|---|---|
+| UNIQUE | 2067 | 23505 |
+| PRIMARY KEY | **1555** | 23505 |
+| CHECK | 275 | 23514 |
+| FOREIGN KEY | 787 | 23503 |
+| NOT NULL | 1299 | 23502 |
+
+⛔ A PRIMARY KEY collision is **1555, not 2067**, while its message still reads
+"UNIQUE constraint failed". The text match caught both by accident;
+`Code() == 2067` alone would not. `idempotency_keys.idempotency_key` is a bare
+PRIMARY KEY, so the whole idempotent-replay path depends on 1555. Proved by
+deleting 1555 and re-running: the new `unique via primary key` subtest fails naming
+the code and the table, and `TestCreateBooking_idempotentReplay` returns
+`replay: 500`. `IsUniqueViolation` matches both codes; PostgreSQL needed no change.
+
+The text comparison is now a fallback only, for an error arriving without its
+driver type attached, and `TestConstraintTextFallback` executes that branch so it
+is not dead code. A driver error whose code does not match is a definite no and
+does not fall through — falling through would readmit a 1555 by its message after
+excluding it by code.
+
+Also fixed: the two intermittent handler failures under `go test ./...` were a flake
+in **my** `dbtest` harness, not the application. Handler goroutines are
+fire-and-forget (notify hosts, enqueue webhook, enqueue reminders) and outlive the
+test body; closing the pool does not stop an in-flight statement; `DROP SCHEMA
+CASCADE` needs an exclusive lock on every object and deadlocks against them
+(SQLSTATE 40P01). The drop now runs on a pinned connection with `lock_timeout` and
+retries within a bounded budget. Three consecutive full PostgreSQL runs clean.
+
 1. **Booleans — resolved.** The Postgres migrations declare them `SMALLINT`, so the
    tree's `= 1` comparisons and `boolToInt(...)` work unchanged. Only *computed*
    boolean expressions in SELECT lists needed a fix (Boundary 5, cause 2).

From cf972cf9d71472673de9cf4cb3bd7dd8b180516f Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Sat, 5 Sep 2026 23:55:31 -0400
Subject: [PATCH 12/51] db: pin every TEXT timestamp column to COLLATE "C"

Timestamps are TEXT and compared lexicographically on purpose: the worker
claims with run_at <= ?, sessions and tokens expire on expires_at > ?, the
consent window brackets decided_at, booking overlap compares start_at/end_at
against bound strings, and several lists are ORDER BY created_at. On SQLite
that is memcmp. On Postgres it is the column's collation, which by default is
the database's.

Migration 00059 alters 54 columns across 27 tables to COLLATE "C" on Postgres
(every *_at, jobs.locked_until, and the availability HH:MM / YYYY-MM-DD
columns, which are ordered as times too). Fixed in the schema rather than in
40-odd predicates that would each have to remember a COLLATE clause. The
SQLite half is a no-op file: BINARY is already memcmp, and the file exists so
the two directories keep one file per version.

internal/handler/notetaker.go is the site that makes this load-bearing rather
than theoretical: it writes datetime('now')'s space-separated shape precisely
because it sorts before any T-separated stamp, which is what makes a notetaker
job due immediately.

collation_test.go holds it three ways:

- an audit over information_schema.columns, matching by NAME so a timestamp
  column added by a later migration is caught without anyone remembering;
- a positive control that skips, rather than passing vacuously, if the server's
  own default already orders byte-wise;
- an ordering test on jobs.run_at through the worker's real claim predicate.

Measured, not assumed: the two shapes the schema actually stores do NOT flip
under this server's en_US.utf8 default, nor under any of the other 878
collations installed on it - glibc ignores the space at the primary level but
still sorts a digit before 'T'. The control therefore also carries RFC 3339's
lower-case t/z spelling (permitted by RFC 3339 section 5.6, so an importer can
hand it to us), where en_US.utf8 puts lower case first and memcmp puts upper
case first. Proved failable by dropping jobs.run_at from the migration: the
audit reports "jobs.run_at = <database default>" and the ordering test reports
the two spellings transposed.
---
 internal/db/collation_test.go                 | 285 ++++++++++++++++++
 .../00059_text_timestamp_collation.sql        | 203 +++++++++++++
 .../sqlite/00059_text_timestamp_collation.sql |  20 ++
 internal/db/postgres_test.go                  |   2 +-
 4 files changed, 509 insertions(+), 1 deletion(-)
 create mode 100644 internal/db/collation_test.go
 create mode 100644 internal/db/migrations/postgres/00059_text_timestamp_collation.sql
 create mode 100644 internal/db/migrations/sqlite/00059_text_timestamp_collation.sql

diff --git a/internal/db/collation_test.go b/internal/db/collation_test.go
new file mode 100644
index 0000000..6fed8f7
--- /dev/null
+++ b/internal/db/collation_test.go
@@ -0,0 +1,285 @@
+package db_test
+
+import (
+	"slices"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// Calnode stores timestamps as TEXT and compares them lexicographically: the
+// worker claims with `run_at <= ?`, sessions and tokens expire on
+// `expires_at > ?`, the consent window brackets `decided_at`, booking overlap is
+// `start_at`/`end_at` against bound strings, and several lists are
+// `ORDER BY created_at`. On SQLite that is memcmp, always. On PostgreSQL it is a
+// comparison under the column's collation, so migration 00059 pins every one of
+// those columns to COLLATE "C".
+//
+// These tests hold that pin. They are Postgres-only because SQLite has no
+// collation to get wrong.
+
+// timestampColumnPredicate selects the columns migration 00059 covers, by name.
+//
+// `_at`/`_until` catches every timestamp column in the schema. The three
+// remaining names are the availability columns, which hold 'HH:MM' and
+// 'YYYY-MM-DD' and are ordered as times too (`ORDER BY day_of_week, start_time`
+// in internal/handler/availability.go, `ORDER BY date` in override.go). Matching
+// by name rather than by a committed list is the point: a timestamp column added
+// by a later migration is caught here without anyone remembering to add it.
+const timestampColumnPredicate = `(c.column_name ~ '_(at|until)$'
+	  OR c.column_name IN ('date', 'start_time', 'end_time'))`
+
+// wantTimestampColumns is the number of columns 00059 altered. A floor, not an
+// equality: the assertion that matters is "every match is C", and a query that
+// silently stopped matching anything would satisfy that vacuously.
+const wantTimestampColumns = 54
+
+func TestPostgres_timestampColumnsCollateC(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	rows, err := handle.Query(`
+		SELECT c.table_name, c.column_name, COALESCE(c.collation_name, '<database default>')
+		FROM information_schema.columns c
+		JOIN information_schema.tables t
+		  ON t.table_schema = c.table_schema AND t.table_name = c.table_name
+		WHERE c.table_schema = current_schema()
+		  AND t.table_type = 'BASE TABLE'
+		  AND c.data_type = 'text'
+		  AND ` + timestampColumnPredicate + `
+		ORDER BY c.table_name, c.column_name`)
+	if err != nil {
+		t.Fatalf("read information_schema.columns: %v", err)
+	}
+	defer rows.Close()
+
+	var checked int
+	var offenders []string
+	for rows.Next() {
+		var table, column, collation string
+		if err := rows.Scan(&table, &column, &collation); err != nil {
+			t.Fatalf("scan column row: %v", err)
+		}
+		checked++
+		if collation != "C" {
+			offenders = append(offenders, table+"."+column+" = "+collation)
+		}
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("iterate columns: %v", err)
+	}
+
+	if checked < wantTimestampColumns {
+		t.Errorf("audited %d timestamp columns; want at least %d — did the predicate stop matching?",
+			checked, wantTimestampColumns)
+	}
+	if len(offenders) > 0 {
+		t.Errorf("%d of %d timestamp columns are not COLLATE \"C\":\n\t%s",
+			len(offenders), checked, strings.Join(offenders, "\n\t"))
+	}
+	t.Logf("audited %d TEXT timestamp columns, %d not C", checked, len(offenders))
+}
+
+// collationProbeValues are timestamp-shaped strings whose byte order and
+// linguistic order disagree.
+//
+// The first two are the shapes the schema really stores (internal/dbtime: a
+// space-separated `datetime('now')` and an RFC 3339 `strftime`). ⚠️ Measured on
+// the PostgreSQL 17 this branch is developed against, those two do NOT flip
+// under the database's en_US.utf8 default, nor under any of the other 878
+// collations installed on that server: glibc ignores the space at the primary
+// level but still sorts a digit before 'T', which happens to agree with
+// memcmp. So they cannot carry the control on their own — a test built only on
+// them would pass with or without migration 00059.
+//
+// The third is the same instant with RFC 3339's lower-case 't' and 'z', which
+// §5.6 of the RFC explicitly permits and which an importer or a third-party API
+// can therefore hand us. Case is a tertiary-level difference: en_US.utf8 puts
+// lower case first, memcmp puts upper case first ('T' is 0x54, 't' is 0x74).
+// That is the pair that makes this control able to fail.
+var collationProbeValues = []string{
+	"2026-01-01 10:00:00",
+	"2026-01-01T10:00:00.000Z",
+	"2026-01-01t10:00:00z",
+	"2026-01-01T10:00:00Z",
+}
+
+// TestPostgres_collationControl is the positive control: it proves the audit
+// above is testing something, by showing that a plain TEXT column on this server
+// really does order these values differently from a COLLATE "C" one.
+//
+// If the server's own default already behaves byte-wise (a C or C.UTF-8
+// database), there is nothing to control against and the test SKIPS naming the
+// collation, rather than passing vacuously — a green run on such a server says
+// nothing about a deployment on a linguistic one.
+func TestPostgres_collationControl(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	// The server's collation, for the skip message. lc_collate stopped being a
+	// GUC in PostgreSQL 16 (SHOW lc_collate errors with "unrecognized
+	// configuration parameter"), so it is read from the catalog, which is also
+	// where the per-database value has always actually lived.
+	var collate, ctype, provider string
+	if err := handle.QueryRow(`
+		SELECT datcollate, datctype, datlocprovider
+		FROM pg_database WHERE datname = current_database()`).Scan(&collate, &ctype, &provider); err != nil {
+		t.Fatalf("read pg_database locale: %v", err)
+	}
+	serverCollation := collate + " (ctype " + ctype + ", provider " + provider + ")"
+
+	if _, err := handle.Exec(`
+		CREATE TABLE collation_control (
+			plain TEXT NOT NULL,
+			cee   TEXT COLLATE "C" NOT NULL
+		)`); err != nil {
+		t.Fatalf("create control table: %v", err)
+	}
+
+	for _, v := range collationProbeValues {
+		if _, err := handle.Exec(`INSERT INTO collation_control (plain, cee) VALUES (?, ?)`, v, v); err != nil {
+			t.Fatalf("insert %q: %v", v, err)
+		}
+	}
+
+	plainOrder := orderedColumn(t, handle, "plain")
+	ceeOrder := orderedColumn(t, handle, "cee")
+
+	wantBytes := slices.Clone(collationProbeValues)
+	sort.Strings(wantBytes) // Go's sort on strings is byte-wise, i.e. what SQLite does
+
+	if !slices.Equal(ceeOrder, wantBytes) {
+		t.Errorf("COLLATE \"C\" column ordered\n\t%v\nwant byte order\n\t%v", ceeOrder, wantBytes)
+	}
+
+	if slices.Equal(plainOrder, ceeOrder) {
+		t.Skipf("server default collation %s orders these values byte-wise too, "+
+			"so this control cannot distinguish a collated column from a C one; "+
+			"the audit is unproven on this server", serverCollation)
+	}
+
+	t.Logf("control fired: server default collation is %s\n\tplain: %v\n\tC    : %v",
+		serverCollation, plainOrder, ceeOrder)
+}
+
+func orderedColumn(t *testing.T, handle *db.DB, column string) []string {
+	t.Helper()
+
+	// column is one of two literals above, never input.
+	rows, err := handle.Query(`SELECT ` + column + ` FROM collation_control ORDER BY ` + column)
+	if err != nil {
+		t.Fatalf("order by %s: %v", column, err)
+	}
+	defer rows.Close()
+
+	var got []string
+	for rows.Next() {
+		var v string
+		if err := rows.Scan(&v); err != nil {
+			t.Fatalf("scan %s: %v", column, err)
+		}
+		got = append(got, v)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("iterate %s: %v", column, err)
+	}
+	return got
+}
+
+// TestPostgres_jobsRunAtOrdering holds the ordering on the column the worker
+// actually polls.
+//
+// Two things are asserted, and they are not the same thing:
+//
+//  1. `ORDER BY run_at` matches Go's byte-wise sort of the same values. This is
+//     the discriminating half: the lower-case RFC 3339 value in the set orders
+//     differently under a linguistic collation, so this fails without 00059.
+//  2. The real claim predicate — `WHERE status = 'pending' AND run_at <= ?` from
+//     internal/worker/worker.go, with an RFC 3339 `now` — sees the
+//     space-separated shape as due and a future T-shape as not. internal/handler/
+//     notetaker.go depends on exactly that: it writes `datetime('now')`'s space
+//     form *because* it sorts before any T-separated stamp, which is what makes a
+//     notetaker job due immediately. Both collations happen to agree here, so
+//     this half is a regression pin rather than a discriminator.
+func TestPostgres_jobsRunAtOrdering(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	// Same instant in the two shapes the tree writes, plus the lower-case RFC
+	// 3339 spelling, all in the past relative to `now` below.
+	runAts := []string{
+		"2026-01-01 10:00:00",
+		"2026-01-01T10:00:00.000Z",
+		"2026-01-01t10:00:00z",
+		"2026-01-01T10:00:00Z",
+	}
+	for i, runAt := range runAts {
+		insertJob(t, handle, "job-past-"+string(rune('a'+i)), runAt)
+	}
+	insertJob(t, handle, "job-future", "2027-01-01T00:00:00Z")
+
+	rows, err := handle.Query(`SELECT run_at FROM jobs ORDER BY run_at`)
+	if err != nil {
+		t.Fatalf("order by run_at: %v", err)
+	}
+	var order []string
+	for rows.Next() {
+		var v string
+		if err := rows.Scan(&v); err != nil {
+			rows.Close()
+			t.Fatalf("scan run_at: %v", err)
+		}
+		order = append(order, v)
+	}
+	rows.Close()
+	if err := rows.Err(); err != nil {
+		t.Fatalf("iterate run_at: %v", err)
+	}
+
+	want := append(slices.Clone(runAts), "2027-01-01T00:00:00Z")
+	sort.Strings(want)
+	if !slices.Equal(order, want) {
+		t.Errorf("ORDER BY run_at =\n\t%v\nwant byte order\n\t%v", order, want)
+	}
+
+	// The worker's own predicate, verbatim from internal/worker/worker.go, with
+	// the RFC 3339 `now` it binds.
+	const now = "2026-06-01T12:00:00Z"
+	claimed, err := handle.Query(`
+		SELECT id, type, payload, attempts, max_attempts
+		FROM jobs
+		WHERE status = 'pending' AND run_at <= ?
+		LIMIT 10`, now)
+	if err != nil {
+		t.Fatalf("claim query: %v", err)
+	}
+	defer claimed.Close()
+
+	var ids []string
+	for claimed.Next() {
+		var id, typ, payload string
+		var attempts, maxAttempts int
+		if err := claimed.Scan(&id, &typ, &payload, &attempts, &maxAttempts); err != nil {
+			t.Fatalf("scan claimed job: %v", err)
+		}
+		ids = append(ids, id)
+	}
+	if err := claimed.Err(); err != nil {
+		t.Fatalf("iterate claimed jobs: %v", err)
+	}
+	sort.Strings(ids)
+
+	wantIDs := []string{"job-past-a", "job-past-b", "job-past-c", "job-past-d"}
+	if !slices.Equal(ids, wantIDs) {
+		t.Errorf("claimed %v; want %v (the four past shapes, not the future one)", ids, wantIDs)
+	}
+}
+
+func insertJob(t *testing.T, handle *db.DB, id, runAt string) {
+	t.Helper()
+	if _, err := handle.Exec(`
+		INSERT INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
+		VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)`, id, `{"id":"`+id+`"}`, runAt); err != nil {
+		t.Fatalf("insert job %s: %v", id, err)
+	}
+}
diff --git a/internal/db/migrations/postgres/00059_text_timestamp_collation.sql b/internal/db/migrations/postgres/00059_text_timestamp_collation.sql
new file mode 100644
index 0000000..2b08c0e
--- /dev/null
+++ b/internal/db/migrations/postgres/00059_text_timestamp_collation.sql
@@ -0,0 +1,203 @@
+-- +goose Up
+-- Timestamps in Calnode are TEXT and are compared lexicographically on purpose:
+-- the job queue claims with `run_at <= ?`, the recordings consent window is
+-- `decided_at BETWEEN`, booking overlap is `start_at`/`end_at` against bound
+-- strings, sessions and tokens expire on `expires_at > ?`, and several lists are
+-- `ORDER BY created_at`. On SQLite that comparison is a byte comparison, always.
+-- On PostgreSQL it is a comparison under the column's collation, which by default
+-- is the database's — en_US.utf8 on a typical installation, i.e. a linguistic
+-- collation that ignores punctuation and spaces at the primary level and orders
+-- case at the tertiary one.
+--
+-- The schema stores two timestamp layouts on purpose (internal/dbtime: a
+-- space-separated `2026-01-01 10:00:00` and a `2026-01-01T10:00:00.000Z`), and a
+-- linguistic collation makes no promise about how those two shapes interleave,
+-- nor about a shape some future writer or import adds. Pinning the columns to
+-- COLLATE "C" makes the ordering byte ordering on both engines, so a predicate
+-- proved correct on SQLite means the same thing on PostgreSQL, and it does so in
+-- the schema rather than in 40-odd queries that would each have to remember a
+-- COLLATE clause.
+--
+-- Scope: every TEXT column the tree compares or orders as a time. That is every
+-- column named *_at plus jobs.locked_until, and also the four HH:MM
+-- availability columns and availability_overrides.date, which are ordered as
+-- times too (`ORDER BY day_of_week, start_time`, `ORDER BY date`). 54 columns
+-- across 27 tables. internal/db/collation_test.go enumerates the migrated schema
+-- and fails if a matching column is not C, so a timestamp column added later
+-- cannot quietly miss this.
+--
+-- Cost: ALTER COLUMN TYPE takes ACCESS EXCLUSIVE on the table and rebuilds its
+-- indexes. Calnode instances are small and this runs once, at the startup that
+-- picks the migration up, but it is not a zero-downtime change on a large
+-- database. Grouped one statement per table so each is rewritten once.
+--
+-- COLLATE "C" is a deterministic collation, so equality keeps comparing bytes and
+-- every existing unique index (booking_manage_tokens' hashed PK, the partial
+-- idx_bookings_no_double) keeps its exact current meaning.
+
+ALTER TABLE api_keys
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN last_used_at TYPE TEXT COLLATE "C";
+ALTER TABLE availability_overrides
+    ALTER COLUMN date TYPE TEXT COLLATE "C",
+    ALTER COLUMN end_time TYPE TEXT COLLATE "C",
+    ALTER COLUMN start_time TYPE TEXT COLLATE "C";
+ALTER TABLE availability_rules
+    ALTER COLUMN end_time TYPE TEXT COLLATE "C",
+    ALTER COLUMN start_time TYPE TEXT COLLATE "C";
+ALTER TABLE booking_manage_tokens
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE "C";
+ALTER TABLE bookings
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN end_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN start_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE "C";
+ALTER TABLE calendar_connections
+    ALTER COLUMN channel_expires_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN expiry_at TYPE TEXT COLLATE "C";
+ALTER TABLE connection_calendars
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C";
+ALTER TABLE crypto_keystore
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE "C";
+ALTER TABLE event_types
+    ALTER COLUMN archived_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C";
+ALTER TABLE idempotency_keys
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C";
+ALTER TABLE invite_tokens
+    ALTER COLUMN expires_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN used_at TYPE TEXT COLLATE "C";
+ALTER TABLE jobs
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN locked_until TYPE TEXT COLLATE "C",
+    ALTER COLUMN run_at TYPE TEXT COLLATE "C";
+ALTER TABLE magic_link_tokens
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN used_at TYPE TEXT COLLATE "C";
+ALTER TABLE meeting_consents
+    ALTER COLUMN decided_at TYPE TEXT COLLATE "C";
+ALTER TABLE notes
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE "C";
+ALTER TABLE oauth_access_tokens
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN last_used_at TYPE TEXT COLLATE "C";
+ALTER TABLE oauth_auth_codes
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE "C";
+ALTER TABLE oauth_clients
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C";
+ALTER TABLE recordings
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE "C";
+ALTER TABLE server_settings
+    ALTER COLUMN updated_at TYPE TEXT COLLATE "C";
+ALTER TABLE sessions
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE "C";
+ALTER TABLE teams
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C";
+ALTER TABLE transcripts
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE "C";
+ALTER TABLE users
+    ALTER COLUMN archived_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C";
+ALTER TABLE webhook_deliveries
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN last_attempted_at TYPE TEXT COLLATE "C";
+ALTER TABLE webhooks
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C";
+ALTER TABLE zoom_connections
+    ALTER COLUMN created_at TYPE TEXT COLLATE "C",
+    ALTER COLUMN expiry_at TYPE TEXT COLLATE "C";
+
+-- +goose Down
+-- Back to the database default collation. pg_catalog."default" is the spelling for
+-- "whatever the database was created with"; there is no way to say "unset".
+ALTER TABLE api_keys
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN last_used_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE availability_overrides
+    ALTER COLUMN date TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN end_time TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN start_time TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE availability_rules
+    ALTER COLUMN end_time TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN start_time TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE booking_manage_tokens
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE bookings
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN end_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN start_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE calendar_connections
+    ALTER COLUMN channel_expires_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN expiry_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE connection_calendars
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE crypto_keystore
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE event_types
+    ALTER COLUMN archived_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE idempotency_keys
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE invite_tokens
+    ALTER COLUMN expires_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN used_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE jobs
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN locked_until TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN run_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE magic_link_tokens
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN used_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE meeting_consents
+    ALTER COLUMN decided_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE notes
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE oauth_access_tokens
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN last_used_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE oauth_auth_codes
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE oauth_clients
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE recordings
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE server_settings
+    ALTER COLUMN updated_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE sessions
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN expires_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE teams
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE transcripts
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN updated_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE users
+    ALTER COLUMN archived_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE webhook_deliveries
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN last_attempted_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE webhooks
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default";
+ALTER TABLE zoom_connections
+    ALTER COLUMN created_at TYPE TEXT COLLATE pg_catalog."default",
+    ALTER COLUMN expiry_at TYPE TEXT COLLATE pg_catalog."default";
diff --git a/internal/db/migrations/sqlite/00059_text_timestamp_collation.sql b/internal/db/migrations/sqlite/00059_text_timestamp_collation.sql
new file mode 100644
index 0000000..c6e628d
--- /dev/null
+++ b/internal/db/migrations/sqlite/00059_text_timestamp_collation.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+-- No-op on SQLite, deliberately, and the file exists so the two migration
+-- directories keep one file per version (TestMigrationDirs_parity enforces that,
+-- and TargetVersion is dialect-independent because of it).
+--
+-- The Postgres half pins every TEXT timestamp column to COLLATE "C" so that
+-- `run_at <= ?`, the consent window, the booking overlap predicates, the token
+-- expiries and `ORDER BY created_at` compare bytes there. SQLite has nothing to
+-- pin: its only collations are BINARY (the default), NOCASE and RTRIM, and
+-- BINARY *is* memcmp. The behaviour this migration buys on Postgres is what
+-- SQLite already does, which is why the port could get this far without noticing.
+--
+-- A statement is included rather than leaving the section empty because goose
+-- treats a migration with no statements as a parse problem, and a SELECT is the
+-- cheapest way to say "nothing to do" in a file that still has to be applied and
+-- recorded.
+SELECT 1;
+
+-- +goose Down
+SELECT 1;
diff --git a/internal/db/postgres_test.go b/internal/db/postgres_test.go
index 3e59614..4e75e69 100644
--- a/internal/db/postgres_test.go
+++ b/internal/db/postgres_test.go
@@ -26,7 +26,7 @@ const postgresDSNEnv = "CALNODE_TEST_POSTGRES_DSN"
 // sanity check on the embedded set, not a property of PostgreSQL, so it moves with
 // every migration added — one named constant rather than the same literal in two
 // assertions, so adding one is a single edit that cannot be half-done.
-const knownMigrationCount = 58
+const knownMigrationCount = 59
 
 // openTestPostgres returns a handle scoped to a schema of its own, created for
 // this test and dropped when it finishes. A schema rather than a database because

From a1aa94b2b471cb67205c83ad92d49da5cdeb7bc7 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Sat, 5 Sep 2026 23:57:10 -0400
Subject: [PATCH 13/51] handler: verify RETURNING position on both engines

Boundary 2 ported the tree's one RETURNING clause (question_handler.go's
auto-position INSERT) and left it verified on SQLite and unverified on
PostgreSQL. It runs unchanged on both: no d.SQL pair, no rewrite.

The test goes through the HTTP handler on dbtest.Open(t), so it follows
CALNODE_TEST_POSTGRES_DSN like the rest of the suite, and it asserts the value
the handler SCANNED from RETURNING as well as the row left behind - a RETURNING
that quietly produced a zero would still leave a correct row, so checking the
table alone (which TestCreateQuestion_autoPosition already did) cannot see it.

The explicit-position case is in the same test on purpose: after a pinned
position 9, the next auto position must be 10, which is what shows the
COALESCE(MAX(position)+1, 0) subselect inside VALUES is really evaluated by the
engine rather than the sequence being an artifact of insertion order.

Measured: 0, 1, 2, then 9 explicit, then 10, identical on sqlite and postgres.
---
 internal/handler/question_test.go | 80 +++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/internal/handler/question_test.go b/internal/handler/question_test.go
index 658ae12..d2fe97e 100644
--- a/internal/handler/question_test.go
+++ b/internal/handler/question_test.go
@@ -232,6 +232,86 @@ func TestCreateQuestion_autoPosition(t *testing.T) {
 	}
 }
 
+// TestCreateQuestion_returningPosition covers the one RETURNING clause in the
+// tree (question_handler.go): when the caller sends no position, the handler
+// computes it inside the INSERT — VALUES (…, (SELECT COALESCE(MAX(position)+1, 0)
+// …)) RETURNING position — rather than SELECT-then-INSERT, so two concurrent
+// creates cannot land on the same position.
+//
+// Boundary 2 left that clause as the one piece of ported SQL verified on SQLite
+// and unverified on PostgreSQL. It runs on whichever engine dbtest selects, and
+// it asserts the value the handler SCANNED from RETURNING, not just the row that
+// ended up in the table: the two agreeing is the whole point, and a RETURNING
+// that silently returned a zero value would still leave a correct row behind.
+func TestCreateQuestion_returningPosition(t *testing.T) {
+	h, database, key, _ := setupWorkspaceWithDB(t)
+	ctx := context.Background()
+	slug, _ := seedEventTypeHTTP(t, h, key)
+	t.Logf("engine: %s", database.Dialect())
+
+	// create posts a question and returns (id, position) as the CREATE response
+	// reported them — i.e. what RETURNING produced on the auto-position path.
+	create := func(body string) (string, int) {
+		t.Helper()
+		req := authReq(http.MethodPost, "/v1/event-types/"+slug+"/questions", body, key)
+		req.SetPathValue("slug", slug)
+		rec := httptest.NewRecorder()
+		h.RequireAuth(h.CreateQuestion)(rec, req)
+		if rec.Code != http.StatusCreated {
+			t.Fatalf("create %s: got %d — %s", body, rec.Code, rec.Body.String())
+		}
+		var resp struct {
+			ID       string `json:"id"`
+			Position int    `json:"position"`
+		}
+		if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("decode create response: %v", err)
+		}
+		return resp.ID, resp.Position
+	}
+
+	stored := func(id string) int {
+		t.Helper()
+		var pos int
+		if err := database.QueryRowContext(ctx,
+			`SELECT position FROM event_type_questions WHERE id = ?`, id).Scan(&pos); err != nil {
+			t.Fatalf("read stored position for %s: %v", id, err)
+		}
+		return pos
+	}
+
+	// First three, no position in the request: RETURNING must hand back 0, 1, 2.
+	for want := 0; want < 3; want++ {
+		id, got := create(fmt.Sprintf(`{"label":"Q%d","type":"text"}`, want))
+		if got != want {
+			t.Errorf("auto position #%d: RETURNING gave %d; want %d", want, got, want)
+		}
+		if s := stored(id); s != got {
+			t.Errorf("auto position #%d: RETURNING gave %d but the row holds %d", want, got, s)
+		}
+	}
+
+	// An explicit position takes the other branch (a plain INSERT, no RETURNING),
+	// and then the next auto position must be MAX+1 over it — 10, not 3. This is
+	// what proves the subselect inside VALUES is evaluated by the engine rather
+	// than the value being an accident of insertion order.
+	explicitID, explicitPos := create(`{"label":"Pinned","type":"text","position":9}`)
+	if explicitPos != 9 {
+		t.Errorf("explicit position: got %d; want 9", explicitPos)
+	}
+	if s := stored(explicitID); s != 9 {
+		t.Errorf("explicit position: row holds %d; want 9", s)
+	}
+
+	nextID, nextPos := create(`{"label":"After the pinned one","type":"text"}`)
+	if nextPos != 10 {
+		t.Errorf("auto position after an explicit 9: RETURNING gave %d; want 10", nextPos)
+	}
+	if s := stored(nextID); s != nextPos {
+		t.Errorf("auto position after an explicit 9: RETURNING gave %d but the row holds %d", nextPos, s)
+	}
+}
+
 // ---------------------------------------------------------------------------
 // UpdateQuestion
 // ---------------------------------------------------------------------------

From dce356847c7bd78f3b9fae48222a92eebb805460 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Sat, 5 Sep 2026 23:59:18 -0400
Subject: [PATCH 14/51] db: delete the bare Open, readiness goes through the
 handle

Open("...") returned a plain *sql.DB and was documented as being "for callers
that have not moved to OpenDB yet". Nothing outside the package's own tests
used it, and it could only ever do harm: a statement issued through that handle
is not rebound, so every ? in it is a Postgres syntax error discovered at
runtime, a long way from the call. It was also the shape most likely to be
copied by the next person adding a call site.

/readyz was the one production caller reaching into the exported embedded field
(db.SchemaReady(ctx, h.db.DB)). *DB now carries SchemaReady and AppliedVersion,
so the handler asks the handle. The package-level functions stay for the
bare-pool cases that really do need one - goose's own bookkeeping, and the
tests that open an unmigrated pool - and db_test.go passes database.DB to them
explicitly, which says at the call site that the bare pool is deliberate.

No test asserts the absence of the symbol: the build is the proof, and a
reflective check on a package's exported names is not cheap enough to be worth
the fixture. TestOpen_inMemory is renamed TestOpenDB_inMemory rather than left
named after something that no longer exists.
---
 internal/db/db.go          | 35 +++++++++++++---------
 internal/db/db_test.go     | 60 +++++++++++++++++++++++++-------------
 internal/handler/health.go |  6 +---
 3 files changed, 62 insertions(+), 39 deletions(-)

diff --git a/internal/db/db.go b/internal/db/db.go
index 8bacdd2..d44180e 100644
--- a/internal/db/db.go
+++ b/internal/db/db.go
@@ -18,22 +18,16 @@ import (
 //go:embed migrations/sqlite/*.sql migrations/postgres/*.sql
 var migrations embed.FS
 
-// Open connects to the database at the given URL and returns the bare handle.
-//
-// Kept for callers that have not moved to OpenDB yet; it is the same connection,
-// without the dialect. Statements issued through it are not rebound, so on
-// Postgres they must already use $n.
-func Open(databaseURL string) (*sql.DB, error) {
-	h, err := OpenDB(databaseURL)
-	if err != nil {
-		return nil, err
-	}
-	return h.DB, nil
-}
-
 // OpenDB connects to the database named by databaseURL and configures the pool
 // for the engine it names.
 //
+// There is deliberately no bare-handle sibling. An Open returning *sql.DB
+// existed through the port "for callers that have not moved over yet", and it
+// was a foot-gun with no upside: statements issued through it are not rebound,
+// so every ? in them is a syntax error on Postgres, found at runtime and far
+// from the call. Anything that genuinely needs the bare pool (goose, Litestream)
+// reaches it as handle.DB, which at least says so at the call site.
+//
 // URL formats:
 //
 //	sqlite://./path/to/db, sqlite:///absolute/path, or a bare file path
@@ -219,6 +213,21 @@ func SchemaReady(ctx context.Context, db *sql.DB) (bool, error) {
 	return applied >= target, nil
 }
 
+// SchemaReady is the handle-level spelling, for callers that hold a *DB — which
+// is every caller in the tree. The package-level functions above stay for the
+// bare-pool cases (goose's own bookkeeping, the tests that open an unmigrated
+// pool), but a handler reaching into h.db.DB to answer a readiness probe was one
+// more place where the exported embedded field looked like the normal way to do
+// things.
+func (h *DB) SchemaReady(ctx context.Context) (bool, error) {
+	return SchemaReady(ctx, h.DB)
+}
+
+// AppliedVersion is the handle-level spelling of the package function.
+func (h *DB) AppliedVersion(ctx context.Context) (int64, error) {
+	return AppliedVersion(ctx, h.DB)
+}
+
 func parseDSN(url string) string {
 	// Strip scheme prefix: sqlite:// → remainder
 	dsn := strings.TrimPrefix(url, "sqlite://")
diff --git a/internal/db/db_test.go b/internal/db/db_test.go
index 4bc6045..21f9933 100644
--- a/internal/db/db_test.go
+++ b/internal/db/db_test.go
@@ -8,10 +8,10 @@ import (
 	"github.com/calnode/calnode/internal/db"
 )
 
-func TestOpen_inMemory(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+func TestOpenDB_inMemory(t *testing.T) {
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
-		t.Fatalf("db.Open: %v", err)
+		t.Fatalf("db.OpenDB: %v", err)
 	}
 	defer database.Close()
 
@@ -21,40 +21,40 @@ func TestOpen_inMemory(t *testing.T) {
 }
 
 func TestMigrate_runsClean(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
-		t.Fatalf("db.Open: %v", err)
+		t.Fatalf("db.OpenDB: %v", err)
 	}
 	defer database.Close()
 
-	if err := db.Migrate(database); err != nil {
+	if err := db.Migrate(database.DB); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 }
 
 func TestMigrate_idempotent(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
-		t.Fatalf("db.Open: %v", err)
+		t.Fatalf("db.OpenDB: %v", err)
 	}
 	defer database.Close()
 
 	// Running twice should not error (goose is idempotent).
 	for range 2 {
-		if err := db.Migrate(database); err != nil {
+		if err := db.Migrate(database.DB); err != nil {
 			t.Fatalf("db.Migrate (run 2): %v", err)
 		}
 	}
 }
 
 func TestMigrate_tablesExist(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
-		t.Fatalf("db.Open: %v", err)
+		t.Fatalf("db.OpenDB: %v", err)
 	}
 	defer database.Close()
 
-	if err := db.Migrate(database); err != nil {
+	if err := db.Migrate(database.DB); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 
@@ -80,24 +80,24 @@ func TestMigrate_tablesExist(t *testing.T) {
 }
 
 func TestSchemaReady_falseBeforeMigrate_trueAfter(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
-		t.Fatalf("db.Open: %v", err)
+		t.Fatalf("db.OpenDB: %v", err)
 	}
 	defer database.Close()
 
 	ctx := context.Background()
 
 	// Before migrating, the goose bookkeeping table is absent → not ready.
-	if ready, _ := db.SchemaReady(ctx, database); ready {
+	if ready, _ := db.SchemaReady(ctx, database.DB); ready {
 		t.Error("SchemaReady = true before migrations ran; want false")
 	}
 
-	if err := db.Migrate(database); err != nil {
+	if err := db.Migrate(database.DB); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 
-	ready, err := db.SchemaReady(ctx, database)
+	ready, err := db.SchemaReady(ctx, database.DB)
 	if err != nil {
 		t.Fatalf("SchemaReady after migrate: %v", err)
 	}
@@ -110,7 +110,7 @@ func TestSchemaReady_falseBeforeMigrate_trueAfter(t *testing.T) {
 	if err != nil {
 		t.Fatalf("TargetVersion: %v", err)
 	}
-	applied, err := db.AppliedVersion(ctx, database)
+	applied, err := db.AppliedVersion(ctx, database.DB)
 	if err != nil {
 		t.Fatalf("AppliedVersion: %v", err)
 	}
@@ -120,16 +120,34 @@ func TestSchemaReady_falseBeforeMigrate_trueAfter(t *testing.T) {
 	if target < 17 {
 		t.Errorf("target version = %d; want >= 17 (sanity check against known migrations)", target)
 	}
+
+	// The handle-level spellings are what the tree uses now that there is no bare
+	// Open; they must agree with the package-level ones they delegate to. This is
+	// the path /readyz takes (internal/handler/health.go).
+	handleReady, err := database.SchemaReady(ctx)
+	if err != nil {
+		t.Fatalf("(*DB).SchemaReady: %v", err)
+	}
+	if handleReady != ready {
+		t.Errorf("(*DB).SchemaReady = %v; want %v (same as the package function)", handleReady, ready)
+	}
+	handleApplied, err := database.AppliedVersion(ctx)
+	if err != nil {
+		t.Fatalf("(*DB).AppliedVersion: %v", err)
+	}
+	if handleApplied != applied {
+		t.Errorf("(*DB).AppliedVersion = %d; want %d", handleApplied, applied)
+	}
 }
 
 func TestDoubleBookingIndex_exists(t *testing.T) {
-	database, err := db.Open("sqlite://:memory:")
+	database, err := db.OpenDB("sqlite://:memory:")
 	if err != nil {
-		t.Fatalf("db.Open: %v", err)
+		t.Fatalf("db.OpenDB: %v", err)
 	}
 	defer database.Close()
 
-	if err := db.Migrate(database); err != nil {
+	if err := db.Migrate(database.DB); err != nil {
 		t.Fatalf("db.Migrate: %v", err)
 	}
 
diff --git a/internal/handler/health.go b/internal/handler/health.go
index a36eb03..43ccf2d 100644
--- a/internal/handler/health.go
+++ b/internal/handler/health.go
@@ -5,7 +5,6 @@ import (
 	"net/http"
 
 	"github.com/calnode/calnode/internal/buildinfo"
-	"github.com/calnode/calnode/internal/db"
 )
 
 func (h *Handler) Healthz(w http.ResponseWriter, r *http.Request) {
@@ -32,10 +31,7 @@ func (h *Handler) Readyz(w http.ResponseWriter, r *http.Request) {
 	// Gate readiness on migrations: report not-ready until the schema is at the
 	// embedded target version, so a provisioner polling /readyz never routes
 	// traffic to an instance still mid-migration (or one that failed to migrate).
-	//
-	// SchemaReady takes the bare pool: its one statement carries no placeholders,
-	// so there is nothing for the wrapper to rebind.
-	ready, err := db.SchemaReady(r.Context(), h.db.DB)
+	ready, err := h.db.SchemaReady(r.Context())
 	if err != nil || !ready {
 		if err != nil {
 			h.logger.ErrorContext(r.Context(), "readyz: migration check failed", "error", err)

From 5297bbf7ec4bf5bb4a4b2be717711e23d6622c68 Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:04:22 -0400
Subject: [PATCH 15/51] db,config: make the Postgres pool size configurable

SetMaxOpenConns(10) / SetMaxIdleConns(5) were literals in openPostgres. The
number that fits is a property of the server, not of Calnode: PostgreSQL's
max_connections is shared with every other client, and an instance behind
PgBouncer wants a different figure from one talking to a 200-connection server
directly. DB_MAX_OPEN_CONNS and DB_MAX_IDLE_CONNS now carry it, defaults
unchanged at 10/5.

Validation lives in config.PoolFromEnv: unset, unparsable or non-positive falls
back to the default with a warning (matching getBool/getDuration, which also
refuse to fail a boot over a typo in an optional knob), and an idle limit above
the open limit is clamped - database/sql silently reduces it anyway, so the
clamped pair is the honest description of what the pool will do. The clamp
applies to the DEFAULT idle too, which is the case a test pins:
DB_MAX_OPEN_CONNS=2 alone must give 2/2, not 2/5.

OpenDB reads PoolFromEnv itself rather than taking the numbers as an argument,
so every entry point (server, mcp, rotate_key, recover_key, reset_admin) picks
them up without five identical edits and without one of them silently keeping
the defaults. db -> config is not a cycle; config imports only the standard
library. A caller that must not follow the environment passes db.WithPool.

SQLite stays pinned at 1/1 and ignores both the environment and WithPool. That
is a correctness guarantee, not a preference: the single connection is what
serialises write transactions (it is why booking.lockHosts is a no-op there),
and the pragmas are connection-scoped, so a second connection would not have
them. TestOpenDB_sqlitePoolIsNotConfigurable asserts it with both knobs set to
40/20, for both the :memory: and file forms.

The idle half cannot be read back from database/sql (DBStats exposes the open
limit only), so it is measured instead: four live transactions force four
connections, and after committing them all the pool keeps 1 with
WithPool(4, 1). Measured on the live server, "idle after release 1".
---
 DEPLOY.md                      |   4 +-
 internal/config/config.go      |  64 +++++++++++++
 internal/config/config_test.go |  73 ++++++++++++++
 internal/db/db.go              |  74 ++++++++++++---
 internal/db/pool_test.go       | 167 +++++++++++++++++++++++++++++++++
 5 files changed, 367 insertions(+), 15 deletions(-)
 create mode 100644 internal/db/pool_test.go

diff --git a/DEPLOY.md b/DEPLOY.md
index e5e6297..41f2567 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -27,7 +27,9 @@ This guide covers a generic Docker deploy and a step-by-step **Railway** deploy
 | `CALNODE_RECOVERY_SECRET` | recommended | — | Escrow secret so the data key can be recovered if the encryption key is rotated/lost. Store it somewhere separate. |
 | `BASE_URL` | **yes (prod)** | `http://localhost:3000` | Identity host — admin UI, OAuth callbacks, invite links. **Must include the scheme** (`https://booking.example.com`). The `https://` prefix flips the app into production mode (secure cookies, encryption-key enforcement). |
 | `PUBLIC_BASE_URL` | no | = `BASE_URL` | Booker-facing host for booking links/emails, if different from the identity host. |
-| `DATABASE_URL` | no | `sqlite://./data/calnode.db` | Point at the persistent volume, e.g. `sqlite:///data/calnode.db`. |
+| `DATABASE_URL` | no | `sqlite://./data/calnode.db` | Point at the persistent volume, e.g. `sqlite:///data/calnode.db`. A `postgres://user:pass@host:5432/dbname` URL selects PostgreSQL instead; anything else is SQLite. |
+| `DB_MAX_OPEN_CONNS` | no | `10` | **PostgreSQL only.** Size of the connection pool. It has to fit inside the server's own `max_connections`, shared with every other client — raise it for a busy instance on a well-sized server, lower it behind PgBouncer or on a shared one. Must be a positive integer; anything else is ignored (with a warning) and the default stands. **Ignored on SQLite, which is always 1**: the single connection is what serialises write transactions, not a tuning choice. |
+| `DB_MAX_IDLE_CONNS` | no | `5` | **PostgreSQL only.** How many idle connections the pool keeps rather than closing. Positive integer, and capped at `DB_MAX_OPEN_CONNS` (a larger value is clamped, since `database/sql` would silently do the same). |
 | `PORT` | no | `3000` | The app listens on `$PORT`. Many platforms inject their own (Railway injects `8080`) — let them. |
 | `EMAIL_SMTP_HOST` / `_PORT` / `_USER` / `_PASS` | no¹ | — / `587` | SMTP. Can also be set later in Settings → Email (DB-stored, encrypted). |
 | `EMAIL_SMTP_TLS` / `_STARTTLS` | no | `false` | `STARTTLS` for 587, implicit `TLS` for 465. |
diff --git a/internal/config/config.go b/internal/config/config.go
index 60fb580..e67de48 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -61,6 +61,18 @@ type Config struct {
 	// DemoResetInterval is how often DemoMode wipes and re-seeds the DB. Configurable
 	// (not hardcoded to 30m) so local verification doesn't require waiting half an hour.
 	DemoResetInterval time.Duration
+
+	// DBMaxOpenConns / DBMaxIdleConns size the PostgreSQL connection pool.
+	// PostgreSQL's own max_connections is the thing they have to fit inside, and
+	// that is a property of the server a self-hoster runs, not of Calnode — a
+	// small instance behind a PgBouncer wants a different number from one talking
+	// to a 200-connection server directly.
+	//
+	// They do NOT apply to SQLite, which is pinned at 1/1 in internal/db because
+	// the single writer connection is a correctness guarantee (ARCHITECTURE §17),
+	// not a tuning choice.
+	DBMaxOpenConns int
+	DBMaxIdleConns int
 }
 
 func Load() *Config {
@@ -100,10 +112,62 @@ func Load() *Config {
 	cfg.CookieSecure = getBool("COOKIE_SECURE", strings.HasPrefix(cfg.BaseURL, "https://"))
 	cfg.DemoMode = getBool("DEMO_MODE", false)
 	cfg.DemoResetInterval = getDuration("DEMO_RESET_INTERVAL", 30*time.Minute)
+	cfg.DBMaxOpenConns, cfg.DBMaxIdleConns = PoolFromEnv()
 
 	return cfg
 }
 
+// Pool defaults. Deliberately modest: one Calnode instance is one small process,
+// and a self-hoster's PostgreSQL is usually sized to match.
+const (
+	DefaultDBMaxOpenConns = 10
+	DefaultDBMaxIdleConns = 5
+)
+
+// PoolFromEnv reads DB_MAX_OPEN_CONNS and DB_MAX_IDLE_CONNS.
+//
+// It is exported separately from Load because internal/db calls it directly:
+// OpenDB has to know the pool size, every entry point that opens a database
+// would otherwise have to remember to pass it, and forgetting would silently
+// give that entry point the defaults. config imports nothing from the app, so
+// db → config is not a cycle.
+//
+// Validation, rather than handing database/sql whatever the environment said:
+//
+//   - unset, unparsable or not positive → the default, with a warning. This
+//     matches getBool/getDuration above, which also fall back rather than
+//     failing a boot over a typo in an optional knob.
+//   - idle > open → idle is clamped to open. database/sql silently reduces the
+//     idle limit to the open limit in that case, so the pair is the honest
+//     description of what the pool will do.
+func PoolFromEnv() (maxOpen, maxIdle int) {
+	maxOpen = getPositiveInt("DB_MAX_OPEN_CONNS", DefaultDBMaxOpenConns)
+	maxIdle = getPositiveInt("DB_MAX_IDLE_CONNS", DefaultDBMaxIdleConns)
+	if maxIdle > maxOpen {
+		slog.Warn("DB_MAX_IDLE_CONNS exceeds DB_MAX_OPEN_CONNS; clamping",
+			"idle", maxIdle, "open", maxOpen)
+		maxIdle = maxOpen
+	}
+	return maxOpen, maxIdle
+}
+
+func getPositiveInt(key string, def int) int {
+	v := os.Getenv(key)
+	if v == "" {
+		return def
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		slog.Warn("ignoring unparsable integer environment variable", "key", key, "value", v, "default", def)
+		return def
+	}
+	if n < 1 {
+		slog.Warn("ignoring non-positive environment variable", "key", key, "value", n, "default", def)
+		return def
+	}
+	return n
+}
+
 func parseLogLevel(s string) slog.Level {
 	switch s {
 	case "debug":
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index a3a9962..5b60eb9 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -121,3 +121,76 @@ func TestLoad_demoResetIntervalInvalidFallsBackToDefault(t *testing.T) {
 		t.Errorf("DemoResetInterval = %v; want 30m default on invalid input", cfg.DemoResetInterval)
 	}
 }
+
+func TestLoad_poolDefaults(t *testing.T) {
+	os.Unsetenv("DB_MAX_OPEN_CONNS")
+	os.Unsetenv("DB_MAX_IDLE_CONNS")
+	cfg := config.Load()
+	if cfg.DBMaxOpenConns != 10 {
+		t.Errorf("DBMaxOpenConns = %d; want 10", cfg.DBMaxOpenConns)
+	}
+	if cfg.DBMaxIdleConns != 5 {
+		t.Errorf("DBMaxIdleConns = %d; want 5", cfg.DBMaxIdleConns)
+	}
+	// The exported constants are what internal/db falls back to, so they must be
+	// the same numbers Load reports rather than a second opinion.
+	if config.DefaultDBMaxOpenConns != 10 || config.DefaultDBMaxIdleConns != 5 {
+		t.Errorf("defaults = %d/%d; want 10/5",
+			config.DefaultDBMaxOpenConns, config.DefaultDBMaxIdleConns)
+	}
+}
+
+func TestPoolFromEnv(t *testing.T) {
+	tests := []struct {
+		name               string
+		open, idle         string
+		wantOpen, wantIdle int
+	}{
+		{name: "unset", wantOpen: 10, wantIdle: 5},
+		{name: "both set", open: "40", idle: "12", wantOpen: 40, wantIdle: 12},
+		{name: "idle above open is clamped to open", open: "6", idle: "99", wantOpen: 6, wantIdle: 6},
+		{name: "zero open is not positive", open: "0", idle: "2", wantOpen: 10, wantIdle: 2},
+		{name: "negative idle is not positive", open: "8", idle: "-1", wantOpen: 8, wantIdle: 5},
+		{name: "unparsable open", open: "many", idle: "3", wantOpen: 10, wantIdle: 3},
+		{name: "one and one", open: "1", idle: "1", wantOpen: 1, wantIdle: 1},
+		// The default idle (5) is above an explicitly small open limit, so the
+		// clamp has to apply to the DEFAULT too, not only to a value someone set.
+		{name: "small open clamps the default idle", open: "2", wantOpen: 2, wantIdle: 2},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			setEnvOrUnset(t, "DB_MAX_OPEN_CONNS", tc.open)
+			setEnvOrUnset(t, "DB_MAX_IDLE_CONNS", tc.idle)
+
+			gotOpen, gotIdle := config.PoolFromEnv()
+			if gotOpen != tc.wantOpen || gotIdle != tc.wantIdle {
+				t.Errorf("PoolFromEnv() = %d/%d; want %d/%d", gotOpen, gotIdle, tc.wantOpen, tc.wantIdle)
+			}
+			if gotIdle > gotOpen {
+				t.Errorf("idle %d exceeds open %d; the pair must always satisfy idle <= open", gotIdle, gotOpen)
+			}
+
+			cfg := config.Load()
+			if cfg.DBMaxOpenConns != gotOpen || cfg.DBMaxIdleConns != gotIdle {
+				t.Errorf("Load() reported %d/%d; want the same %d/%d PoolFromEnv gives",
+					cfg.DBMaxOpenConns, cfg.DBMaxIdleConns, gotOpen, gotIdle)
+			}
+		})
+	}
+}
+
+func setEnvOrUnset(t *testing.T, key, value string) {
+	t.Helper()
+	if value == "" {
+		previous, had := os.LookupEnv(key)
+		os.Unsetenv(key)
+		t.Cleanup(func() {
+			if had {
+				os.Setenv(key, previous)
+			}
+		})
+		return
+	}
+	t.Setenv(key, value)
+}
diff --git a/internal/db/db.go b/internal/db/db.go
index d44180e..b9b77a7 100644
--- a/internal/db/db.go
+++ b/internal/db/db.go
@@ -13,11 +13,41 @@ import (
 
 	"github.com/pressly/goose/v3"
 	_ "modernc.org/sqlite"
+
+	"github.com/calnode/calnode/internal/config"
 )
 
 //go:embed migrations/sqlite/*.sql migrations/postgres/*.sql
 var migrations embed.FS
 
+// Option configures OpenDB.
+type Option func(*openOptions)
+
+type openOptions struct {
+	maxOpen, maxIdle int
+}
+
+// WithPool sets the PostgreSQL pool sizes explicitly, bypassing
+// DB_MAX_OPEN_CONNS / DB_MAX_IDLE_CONNS. For a caller that must not follow the
+// environment — a one-shot CLI, or a test pinning the numbers it asserts.
+//
+// Values are sanity-checked the same way config does it, because this is the
+// function that hands them to database/sql: a non-positive size falls back to
+// the default, and an idle limit above the open limit is clamped.
+func WithPool(maxOpen, maxIdle int) Option {
+	return func(o *openOptions) {
+		if maxOpen > 0 {
+			o.maxOpen = maxOpen
+		}
+		if maxIdle > 0 {
+			o.maxIdle = maxIdle
+		}
+		if o.maxIdle > o.maxOpen {
+			o.maxIdle = o.maxOpen
+		}
+	}
+}
+
 // OpenDB connects to the database named by databaseURL and configures the pool
 // for the engine it names.
 //
@@ -28,18 +58,34 @@ var migrations embed.FS
 // from the call. Anything that genuinely needs the bare pool (goose, Litestream)
 // reaches it as handle.DB, which at least says so at the call site.
 //
+// Pool sizing comes from the environment (config.PoolFromEnv) unless a WithPool
+// option overrides it, so every entry point picks up DB_MAX_OPEN_CONNS /
+// DB_MAX_IDLE_CONNS without each one having to remember to pass them. It is
+// ignored entirely on SQLite — see openSQLite.
+//
 // URL formats:
 //
 //	sqlite://./path/to/db, sqlite:///absolute/path, or a bare file path
 //	postgres://user:pass@host:port/dbname (postgresql:// is accepted too)
-func OpenDB(databaseURL string) (*DB, error) {
+func OpenDB(databaseURL string, opts ...Option) (*DB, error) {
 	if dialectFromURL(databaseURL) == DialectPostgres {
-		return openPostgres(databaseURL)
+		o := openOptions{}
+		o.maxOpen, o.maxIdle = config.PoolFromEnv()
+		for _, opt := range opts {
+			opt(&o)
+		}
+		return openPostgres(databaseURL, o)
 	}
 	return openSQLite(databaseURL)
 }
 
 // openSQLite opens SQLite and configures pragmas.
+//
+// It takes no pool options on purpose. DB_MAX_OPEN_CONNS is meaningless here and
+// honouring it would be a correctness bug, not a tuning choice: the single
+// connection is what serialises write transactions and what keeps the
+// booking-overlap check free of TOCTOU races (ARCHITECTURE §17), and the pragmas
+// below are connection-scoped, so a second connection would not have them.
 func openSQLite(databaseURL string) (*DB, error) {
 	dsn := parseDSN(databaseURL)
 
@@ -72,20 +118,20 @@ func openSQLite(databaseURL string) (*DB, error) {
 
 // openPostgres opens a PostgreSQL pool.
 //
-// The one-connection pool above is a SQLite constraint, not a Calnode design
-// choice, and carrying it over would serialise the whole instance on a database
-// that has its own concurrency control. Sizes are deliberately modest: one
-// Calnode instance is one small process, and a self-hoster's Postgres is usually
-// sized to match.
+// The one-connection pool of openSQLite is a SQLite constraint, not a Calnode
+// design choice, and carrying it over would serialise the whole instance on a
+// database that has its own concurrency control. Sizes come from the caller
+// (ultimately DB_MAX_OPEN_CONNS / DB_MAX_IDLE_CONNS, defaulting to 10/5)
+// because the number that fits is a property of the server: PostgreSQL's
+// max_connections is shared with every other client, and an instance behind
+// PgBouncer wants a different figure from one talking to the server directly.
 //
 // The pool does cost one property the SQLite path gets by accident: the
 // booking-overlap check (ARCHITECTURE §17) is free of TOCTOU races there only
 // because every transaction queues on that single connection. Here two
-// overlapping bookings can clear the check concurrently, and only
-// idx_bookings_no_double — exact start times — stops them. Closing that gap
-// belongs with the booking transaction (SERIALIZABLE, or a range exclusion
-// constraint), not with the pool.
-func openPostgres(databaseURL string) (*DB, error) {
+// overlapping bookings can clear the check concurrently, which is what
+// booking.lockHosts' advisory lock closes.
+func openPostgres(databaseURL string, o openOptions) (*DB, error) {
 	// pgx parses the DSN here, so a malformed URL fails at Open. Reachability is
 	// not probed: Migrate runs immediately after Open in every entry point and
 	// reports an unreachable server with the same context a probe would.
@@ -94,8 +140,8 @@ func openPostgres(databaseURL string) (*DB, error) {
 		return nil, fmt.Errorf("open database: %w", err)
 	}
 
-	db.SetMaxOpenConns(10)
-	db.SetMaxIdleConns(5)
+	db.SetMaxOpenConns(o.maxOpen)
+	db.SetMaxIdleConns(o.maxIdle)
 
 	return &DB{DB: db, dialect: DialectPostgres}, nil
 }
diff --git a/internal/db/pool_test.go b/internal/db/pool_test.go
new file mode 100644
index 0000000..d38c133
--- /dev/null
+++ b/internal/db/pool_test.go
@@ -0,0 +1,167 @@
+package db_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/calnode/calnode/internal/config"
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// unreachablePostgresDSN is a syntactically valid Postgres URL pointed at
+// nothing. sql.Open is lazy — pgx parses the DSN and no connection is attempted
+// until a query runs — so the pool settings can be read back from Stats()
+// without a server anywhere near the test.
+const unreachablePostgresDSN = "postgres://calnode:pw@127.0.0.1:5432/calnode?sslmode=disable"
+
+func TestOpenDB_poolSizeFromEnv(t *testing.T) {
+	tests := []struct {
+		name     string
+		open     string // DB_MAX_OPEN_CONNS, "" = unset
+		idle     string // DB_MAX_IDLE_CONNS, "" = unset
+		wantOpen int
+	}{
+		{name: "unset uses the defaults", wantOpen: config.DefaultDBMaxOpenConns},
+		{name: "raised", open: "40", idle: "10", wantOpen: 40},
+		{name: "lowered to one", open: "1", idle: "1", wantOpen: 1},
+		{name: "zero is not positive, so the default stands", open: "0", wantOpen: config.DefaultDBMaxOpenConns},
+		{name: "negative is not positive either", open: "-4", wantOpen: config.DefaultDBMaxOpenConns},
+		{name: "unparsable falls back", open: "lots", wantOpen: config.DefaultDBMaxOpenConns},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			setPoolEnv(t, tc.open, tc.idle)
+
+			handle, err := db.OpenDB(unreachablePostgresDSN)
+			if err != nil {
+				t.Fatalf("OpenDB: %v", err)
+			}
+			defer handle.Close()
+
+			if got := handle.Stats().MaxOpenConnections; got != tc.wantOpen {
+				t.Errorf("MaxOpenConnections = %d; want %d", got, tc.wantOpen)
+			}
+		})
+	}
+}
+
+// TestOpenDB_withPoolBeatsEnv covers the escape hatch: a caller that must not
+// follow the environment.
+func TestOpenDB_withPoolBeatsEnv(t *testing.T) {
+	setPoolEnv(t, "40", "20")
+
+	handle, err := db.OpenDB(unreachablePostgresDSN, db.WithPool(3, 2))
+	if err != nil {
+		t.Fatalf("OpenDB: %v", err)
+	}
+	defer handle.Close()
+
+	if got := handle.Stats().MaxOpenConnections; got != 3 {
+		t.Errorf("MaxOpenConnections = %d; want 3 (WithPool, not the environment)", got)
+	}
+}
+
+// TestOpenDB_sqlitePoolIsNotConfigurable is the correctness guarantee, not a
+// preference: SQLite's single connection is what serialises write transactions
+// (ARCHITECTURE §17, and it is why booking.lockHosts is a no-op there), and the
+// pragmas are connection-scoped. An operator who sets DB_MAX_OPEN_CONNS for
+// their Postgres instance and later moves the same environment onto a SQLite one
+// must not silently lose that.
+func TestOpenDB_sqlitePoolIsNotConfigurable(t *testing.T) {
+	setPoolEnv(t, "40", "20")
+
+	for _, url := range []string{
+		"sqlite://:memory:",
+		"sqlite://" + filepath.Join(t.TempDir(), "calnode.db"),
+	} {
+		handle, err := db.OpenDB(url, db.WithPool(40, 20))
+		if err != nil {
+			t.Fatalf("OpenDB(%s): %v", url, err)
+		}
+		if got := handle.Stats().MaxOpenConnections; got != 1 {
+			t.Errorf("OpenDB(%s): MaxOpenConnections = %d; want 1 whatever the environment says", url, got)
+		}
+		handle.Close()
+	}
+}
+
+// TestPostgres_idleLimitApplied measures the idle half against a real server.
+// database/sql exposes the open limit through Stats() but not the idle one, so
+// the only honest way to check SetMaxIdleConns took effect is to occupy several
+// connections at once and count what the pool keeps when they are handed back.
+func TestPostgres_idleLimitApplied(t *testing.T) {
+	dsn := dbtest.PostgresDSN()
+	if dsn == "" {
+		t.Skipf("%s is not set; nothing to run against PostgreSQL", dbtest.DSNEnv)
+	}
+
+	const maxOpen, maxIdle = 4, 1
+	handle, err := db.OpenDB(dsn, db.WithPool(maxOpen, maxIdle))
+	if err != nil {
+		t.Fatalf("OpenDB: %v", err)
+	}
+	defer handle.Close()
+
+	ctx := context.Background()
+
+	// A transaction holds a connection for its lifetime, so four of them force
+	// four real connections open. No schema is touched: this is the pool, not the
+	// database.
+	txs := make([]*db.Tx, 0, maxOpen)
+	for i := 0; i < maxOpen; i++ {
+		tx, err := handle.BeginTx(ctx, nil)
+		if err != nil {
+			t.Fatalf("BeginTx %d: %v", i, err)
+		}
+		var one int
+		if err := tx.QueryRowContext(ctx, `SELECT 1`).Scan(&one); err != nil {
+			t.Fatalf("SELECT 1 in tx %d: %v", i, err)
+		}
+		txs = append(txs, tx)
+	}
+	if got := handle.Stats().OpenConnections; got != maxOpen {
+		t.Errorf("OpenConnections while %d transactions are live = %d; want %d", maxOpen, got, maxOpen)
+	}
+
+	for i, tx := range txs {
+		if err := tx.Commit(); err != nil {
+			t.Fatalf("Commit %d: %v", i, err)
+		}
+	}
+
+	// Every connection is back in the pool now; the idle limit decides how many
+	// are kept rather than closed.
+	if got := handle.Stats().Idle; got > maxIdle {
+		t.Errorf("Idle after returning %d connections = %d; want at most %d", maxOpen, got, maxIdle)
+	}
+	t.Logf("pool: max open %d, max idle %d, idle after release %d",
+		handle.Stats().MaxOpenConnections, maxIdle, handle.Stats().Idle)
+}
+
+// setPoolEnv sets or unsets both knobs for one test. t.Setenv restores the
+// previous value at the end and refuses to run in a parallel test, which is what
+// keeps these from leaking into the rest of the package.
+func setPoolEnv(t *testing.T, open, idle string) {
+	t.Helper()
+	for _, kv := range []struct{ key, value string }{
+		{"DB_MAX_OPEN_CONNS", open},
+		{"DB_MAX_IDLE_CONNS", idle},
+	} {
+		if kv.value == "" {
+			// t.Setenv has no "unset" mode; do it by hand and restore by hand.
+			previous, had := os.LookupEnv(kv.key)
+			os.Unsetenv(kv.key)
+			t.Cleanup(func() {
+				if had {
+					os.Setenv(kv.key, previous)
+				}
+			})
+			continue
+		}
+		t.Setenv(kv.key, kv.value)
+	}
+}

From bfa2bcacd35847d5221f9ee44af7a36b1a49475d Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:05:59 -0400
Subject: [PATCH 16/51] auth: sign someone in from an identity system you
 already run

GET /v1/auth/sso?token=<jwt> takes a short-lived HS256 token from an external
identity system that has already authenticated the person and starts an ordinary
Calnode session, so they are not asked to log in a second time. Off unless
CALNODE_SSO_SHARED_SECRET is set, and 404 when it is not: an instance that has
not configured this should be indistinguishable from one that does not implement
it, and a feature that can mint a session must not be reachable by default.

The token is verified in-tree with crypto/hmac rather than by a JWT library, for
the reason internal/livekit signs its own: one algorithm, one key, a fixed claim
set, nothing to keep current. HS256 is checked before the signature is compared,
because accepting the token's own choice of algorithm is the alg:none downgrade.

Two properties carry the security, and both are cheap only because the token is
a redirect the browser follows immediately. It may live at most 60s after iat
(30s of skew either way, since the two systems are separate hosts), and its jti
is claimed in the new sso_nonces table BEFORE the session is created, so a replay
inside the window collides on a primary key instead of racing a read-then-write.
The worker purges expired nonces in the GC pass it already runs; a row past its
expires_at can no longer refuse anything, so keeping it is pure growth.

aud must equal BASE_URL. That is what stops a token minted for staging being
spent on production when someone shares a secret between the two by mistake.

This is the one path that creates a user without an invite, and that is the
trade the shared secret buys. On creation the claimed role is applied. On someone
who already exists it is not: a workspace's roles are the workspace's business,
and a hand-off rewriting them on every sign-in would make the admin UI's role
controls advisory. The single exception is bootstrapping an instance with no
owner, where the one-owner invariant means there is nothing to displace. An
archived account is refused here as it is everywhere else.

?next= is honoured only for a same-origin absolute path, and a bad one is
refused rather than cleaned up, because a redirect built from a partially
sanitised value is how open redirects survive their own fix. It is also checked
before the nonce is claimed, so the caller's own bug does not burn the token.

wid is parsed and ignored. A multi-workspace mode will use it to choose which
workspace the hand-off lands in; accepting it now means a caller written against
that does not need changing to work today.
---
 CHANGELOG.md                                  |  19 +
 DEPLOY.md                                     |   1 +
 docs/ARCHITECTURE.md                          |  25 ++
 internal/config/config.go                     |   8 +
 .../migrations/postgres/00059_sso_nonces.sql  |  21 +
 .../db/migrations/sqlite/00059_sso_nonces.sql |  18 +
 internal/handler/handler.go                   |   1 +
 internal/handler/sso.go                       | 356 +++++++++++++++++
 internal/handler/sso_test.go                  | 358 ++++++++++++++++++
 internal/server/server.go                     |   7 +
 internal/worker/worker.go                     |   7 +
 11 files changed, 821 insertions(+)
 create mode 100644 internal/db/migrations/postgres/00059_sso_nonces.sql
 create mode 100644 internal/db/migrations/sqlite/00059_sso_nonces.sql
 create mode 100644 internal/handler/sso.go
 create mode 100644 internal/handler/sso_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1445c11..6a2ba4d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,25 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
 
 ## [Unreleased]
 
+### Added
+- **Signed session hand-off, so an identity system you already run can sign people in.**
+  `GET /v1/auth/sso?token=<jwt>` accepts a short-lived HS256 JWT signed with a shared
+  secret and starts an ordinary Calnode session, redirecting to `/admin/` (or to a
+  same-origin `?next=` path). Off unless `CALNODE_SSO_SHARED_SECRET` is set — an
+  unconfigured instance answers 404, so it cannot be turned on by accident.
+
+  The token must carry `iss`, `aud` (your `BASE_URL`), `sub` (email), `name`, `role`,
+  `iat`, `exp` and a unique `jti`. It may live at most 60 seconds, 30 seconds of clock
+  skew is tolerated either way, and the `jti` is recorded in a new `sso_nonces` table
+  before the session is created, so a replay inside that window is refused rather than
+  handed a second session. A `wid` claim is accepted and ignored today.
+
+  This is the only path that creates a user without an invite, which is the trade the
+  shared secret buys: the caller is your own identity system, not a visitor with a
+  Google account. On creation the claimed role is applied; for someone who already
+  exists the role is left alone, except that a claim asking for `owner` bootstraps
+  ownership when the instance has none. Archived accounts are still refused.
+
 ## [0.8.0] - 2026-09-03
 
 ### Added
diff --git a/DEPLOY.md b/DEPLOY.md
index e5e6297..a59f8c1 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -25,6 +25,7 @@ This guide covers a generic Docker deploy and a step-by-step **Railway** deploy
 |---|---|---|---|
 | `CALNODE_ENCRYPTION_KEY` | **prod: yes** | — | KEK input (Argon2id). **Required when `BASE_URL` is https** — the app refuses to start without it. Use a long random string: `openssl rand -hex 32`. **Losing it makes encrypted data unrecoverable** unless you set the recovery secret below. |
 | `CALNODE_RECOVERY_SECRET` | recommended | — | Escrow secret so the data key can be recovered if the encryption key is rotated/lost. Store it somewhere separate. |
+| `CALNODE_SSO_SHARED_SECRET` | no | — | HMAC key for the signed session hand-off (`GET /v1/auth/sso`). Unset ⇒ that endpoint **404s**. Anything holding this secret can mint a session and create a user, so treat it like the encryption key: `openssl rand -hex 32`, env only, never in the admin UI. |
 | `BASE_URL` | **yes (prod)** | `http://localhost:3000` | Identity host — admin UI, OAuth callbacks, invite links. **Must include the scheme** (`https://booking.example.com`). The `https://` prefix flips the app into production mode (secure cookies, encryption-key enforcement). |
 | `PUBLIC_BASE_URL` | no | = `BASE_URL` | Booker-facing host for booking links/emails, if different from the identity host. |
 | `DATABASE_URL` | no | `sqlite://./data/calnode.db` | Point at the persistent volume, e.g. `sqlite:///data/calnode.db`. |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 84ea4a8..57338b5 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -226,6 +226,31 @@ the platform/recovery secret doesn't expose secrets.
   Owner-gated actions: grant/revoke admin, transfer ownership. Admins can cancel
   any booking, see all bookings, manage teams/members. Safe-removal + archive
   guards prevent orphaning.
+- **Signed session hand-off** (`GET /v1/auth/sso?token=<jwt>`, `sso.go`) lets an
+  external identity system that has already authenticated someone drop them into a
+  Calnode session without a second login. **Off unless `CALNODE_SSO_SHARED_SECRET` is
+  set** — an unconfigured instance answers **404**, deliberately indistinguishable from
+  a build without the feature. The token is a compact **HS256** JWT verified in-tree
+  (`crypto/hmac`, like `internal/livekit`'s signing) with a constant-time compare; only
+  HS256 is accepted, checked *before* the signature so the `alg: none` downgrade never
+  reaches it. Claims: `iss` (any non-empty string, logged only), `aud` = `BASE_URL`
+  (what stops a staging token being spent on production when a secret is shared by
+  mistake), `sub` = email, `name`, `role` ∈ owner|admin|member, `iat`, `exp` at most
+  **60 s** after `iat` with **30 s** of clock skew allowed either way, and a unique
+  `jti`. `wid` is parsed and ignored — a multi-workspace mode will use it. The `jti` is
+  claimed in **`sso_nonces`** *before* the session is created, so a replay inside the
+  validity window collides on the primary key rather than racing a read-then-write; the
+  worker purges expired rows in its GC pass (§13). Success is a 302 to `/admin/`, or to
+  `?next=` when that is a same-origin absolute path (anything with a scheme, a `//`
+  prefix, a backslash or a control character is a 400, refused rather than sanitised).
+  Every other failure is a 401 whose JSON body names the claim that failed. Rate-limited
+  like the OAuth callbacks.
+  ⛔ **This is the one path that creates a user without an invite.** Everywhere else an
+  unknown email is refused (`no_account`); here the shared secret is the difference — the
+  caller is the operator's own identity system. On creation the claim's `role` is applied;
+  on an existing user the role is **not** rewritten, except that a claim asking for
+  `owner` bootstraps ownership when the instance has none (the one-owner invariant §6
+  maintains means there is nothing to displace). An archived user is still refused.
 - **Offboarding = archive** (`users.archived_at`), never hard-delete — preserves
   bookings, event-type ownership, team links. Archived ⇒ no login, hidden from
   lists, skipped in routing/slots, event types deactivated. Reversible (restore).
diff --git a/internal/config/config.go b/internal/config/config.go
index 60fb580..6f4bcca 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -40,6 +40,13 @@ type Config struct {
 	ZoomClientID     string
 	ZoomClientSecret string
 
+	// SSOSharedSecret is the HMAC key for the signed session hand-off
+	// (GET /v1/auth/sso). Empty ⇒ that endpoint is off and 404s. Env-only and
+	// deliberately not settable from the admin UI: it can create users and mint
+	// sessions, so it belongs with the platform secrets rather than in a settings
+	// page an admin session can reach.
+	SSOSharedSecret string
+
 	// CookieSecure sets the Secure flag on session cookies. Defaults to true
 	// when BASE_URL starts with https://, but can be overridden explicitly via
 	// COOKIE_SECURE=false for HTTPS-terminated-at-proxy setups where the binary
@@ -93,6 +100,7 @@ func Load() *Config {
 
 	cfg.EncryptionKey = os.Getenv("CALNODE_ENCRYPTION_KEY")
 	cfg.RecoverySecret = os.Getenv("CALNODE_RECOVERY_SECRET")
+	cfg.SSOSharedSecret = os.Getenv("CALNODE_SSO_SHARED_SECRET")
 	// PUBLIC_BASE_URL overrides the booker-facing host (custom/vanity domain).
 	// Unset → inherits BASE_URL, so single-domain deploys need only set BASE_URL.
 	cfg.PublicBaseURL = getEnv("PUBLIC_BASE_URL", cfg.BaseURL)
diff --git a/internal/db/migrations/postgres/00059_sso_nonces.sql b/internal/db/migrations/postgres/00059_sso_nonces.sql
new file mode 100644
index 0000000..8b36dc3
--- /dev/null
+++ b/internal/db/migrations/postgres/00059_sso_nonces.sql
@@ -0,0 +1,21 @@
+-- +goose Up
+-- Single-use identifiers (jti) from the signed SSO hand-off tokens. A token's jti is
+-- claimed here before its session is created, so a replay of a still-valid token
+-- collides on the primary key instead of being handed a second session.
+--
+-- expires_at mirrors the token's own exp. The background worker purges rows past it in
+-- the same GC pass that sweeps expired sessions and magic links, which is what keeps
+-- this table the size of one token lifetime rather than of every sign-in ever made.
+--
+-- Nothing here is engine-specific: the column types are the portable TEXT the rest of
+-- the schema uses, and no DEFAULT is needed because the writer binds both values.
+CREATE TABLE sso_nonces (
+    jti        TEXT PRIMARY KEY,
+    expires_at TEXT NOT NULL
+);
+
+CREATE INDEX idx_sso_nonces_expires_at ON sso_nonces(expires_at);
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_sso_nonces_expires_at;
+DROP TABLE sso_nonces;
diff --git a/internal/db/migrations/sqlite/00059_sso_nonces.sql b/internal/db/migrations/sqlite/00059_sso_nonces.sql
new file mode 100644
index 0000000..0937e30
--- /dev/null
+++ b/internal/db/migrations/sqlite/00059_sso_nonces.sql
@@ -0,0 +1,18 @@
+-- +goose Up
+-- Single-use identifiers (jti) from the signed SSO hand-off tokens. A token's jti is
+-- claimed here before its session is created, so a replay of a still-valid token
+-- collides on the primary key instead of being handed a second session.
+--
+-- expires_at mirrors the token's own exp. The background worker purges rows past it in
+-- the same GC pass that sweeps expired sessions and magic links, which is what keeps
+-- this table the size of one token lifetime rather than of every sign-in ever made.
+CREATE TABLE sso_nonces (
+    jti        TEXT PRIMARY KEY,
+    expires_at TEXT NOT NULL
+);
+
+CREATE INDEX idx_sso_nonces_expires_at ON sso_nonces(expires_at);
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_sso_nonces_expires_at;
+DROP TABLE sso_nonces;
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index cf68ce8..567f981 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -39,6 +39,7 @@ type Handler struct {
 	googleAuth        *oauth2.Config
 	microsoftAuth     *oauth2.Config
 	secureCookie      bool
+	ssoSecret         string // HMAC key for the signed session hand-off; empty ⇒ /v1/auth/sso is off
 	llmMu             sync.RWMutex
 	llm               *llm.Client // nil when the optional LLM layer is off/unconfigured
 	zoomMu            sync.RWMutex
diff --git a/internal/handler/sso.go b/internal/handler/sso.go
new file mode 100644
index 0000000..907dd61
--- /dev/null
+++ b/internal/handler/sso.go
@@ -0,0 +1,356 @@
+package handler
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/uid"
+)
+
+const (
+	// ssoMaxTokenLifetime caps exp - iat. A hand-off is a redirect the browser follows
+	// immediately, so it needs seconds, not minutes.
+	ssoMaxTokenLifetime = 60 * time.Second
+
+	// ssoClockSkew is how far the two systems' clocks may disagree before a token is
+	// refused, applied to both ends of the window.
+	ssoClockSkew = 30 * time.Second
+
+	// ssoDefaultNext is where a hand-off lands when no ?next= is given.
+	ssoDefaultNext = "/admin/"
+)
+
+// SetSSOSecret configures the shared secret for the SSO hand-off endpoint. An empty
+// secret leaves the endpoint off (it 404s). Set once at boot from config, like
+// SetBaseURL and SetEncKey, so there is no lock here.
+func (h *Handler) SetSSOSecret(secret string) {
+	h.ssoSecret = secret
+}
+
+// ssoClaims is the token payload. Every field except wid is required.
+type ssoClaims struct {
+	Iss  string `json:"iss"`  // issuing system, any non-empty string; logged, never authorised on
+	Aud  string `json:"aud"`  // must equal this instance's BASE_URL
+	Sub  string `json:"sub"`  // the person's email address
+	Name string `json:"name"` // display name, used when the user is created
+	Role string `json:"role"` // owner | admin | member
+	Iat  int64  `json:"iat"`  // issued at, seconds since the epoch
+	Exp  int64  `json:"exp"`  // expires at, seconds since the epoch
+	JTI  string `json:"jti"`  // unique per token; replay is refused
+
+	// WID names a workspace. Parsed and deliberately ignored: an instance is a single
+	// workspace today, so there is nothing to select. A multi-workspace mode will use
+	// it to decide which workspace the hand-off lands in, and accepting it now means a
+	// caller written against that future does not have to be changed to work today.
+	WID string `json:"wid"`
+}
+
+// SSOHandoff handles GET /v1/auth/sso?token=<jwt>[&next=/path] — the signed session
+// hand-off. An external identity system that has already authenticated a person hands
+// them into a Calnode session, without a second login.
+//
+// The token is a compact HS256 JWT signed with a secret the two systems share
+// (CALNODE_SSO_SHARED_SECRET); the endpoint is off unless that is set. It is verified
+// here rather than by a JWT library for the same reason internal/livekit signs its own:
+// one algorithm, one key, a fixed claim set, and no dependency to keep current. Only
+// HS256 is accepted — "none" and every asymmetric alg are refused before the signature
+// is looked at, which is the classic JWT downgrade.
+//
+// Two properties do the security work, and neither is optional:
+//
+//   - The token is short-lived (exp at most 60s after iat) so a captured URL is not a
+//     standing credential. 30s of clock skew is allowed in both directions, because the
+//     two systems are separate hosts and NTP is not a guarantee.
+//   - The token is single-use: its jti is claimed in sso_nonces before the session is
+//     created, so a replay inside the validity window loses on the primary key.
+//
+// This is the ONE path that creates a user without an invite (see ssoResolveUser).
+// Everywhere else an unknown email is refused; the shared secret is what makes this
+// different — the caller is the operator's own identity system, not an arbitrary
+// visitor with a Google account.
+//
+// Success is a 302 into the admin app (or ?next=, when that is a same-origin absolute
+// path). Every failure is a 401 with a JSON body naming the claim that failed, so an
+// operator wiring this up can tell a clock problem from a wrong audience — the body
+// never carries the secret, the signature, or the token.
+func (h *Handler) SSOHandoff(w http.ResponseWriter, r *http.Request) {
+	if h.ssoSecret == "" {
+		// Off unless CALNODE_SSO_SHARED_SECRET is set, and 404 rather than 501 so an
+		// instance that has not configured SSO is indistinguishable from one that does
+		// not implement it. Nothing is disclosed to a prober either way.
+		h.writeError(w, http.StatusNotFound, "not found")
+		return
+	}
+
+	token := r.URL.Query().Get("token")
+	if token == "" {
+		h.writeError(w, http.StatusUnauthorized, "token is required")
+		return
+	}
+
+	claims, err := verifySSOToken(token, h.ssoSecret)
+	if err != nil {
+		h.logger.WarnContext(r.Context(), "sso: token rejected", "reason", err.Error())
+		h.writeError(w, http.StatusUnauthorized, err.Error())
+		return
+	}
+	if err := claims.validate(h.baseURL, time.Now()); err != nil {
+		h.logger.WarnContext(r.Context(), "sso: claims rejected", "reason", err.Error(), "iss", claims.Iss)
+		h.writeError(w, http.StatusUnauthorized, err.Error())
+		return
+	}
+
+	// Validated before the nonce is claimed: a bad ?next= is the caller's own bug, and
+	// burning the token over it would make the retry fail for a second, unrelated reason.
+	next, err := ssoNextPath(r.URL.Query().Get("next"))
+	if err != nil {
+		h.writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	// Claim the jti before anything is created. On a replay this is the statement that
+	// fails, and it fails on the primary key rather than on a read-then-write the second
+	// request could interleave with.
+	if _, err := h.db.ExecContext(r.Context(),
+		`INSERT INTO sso_nonces (jti, expires_at) VALUES (?, ?)`,
+		claims.JTI, time.Unix(claims.Exp, 0).UTC().Format(time.RFC3339)); err != nil {
+		if db.IsUniqueViolation(err) {
+			h.logger.WarnContext(r.Context(), "sso: token replayed", "iss", claims.Iss)
+			h.writeError(w, http.StatusUnauthorized, "jti has already been used")
+			return
+		}
+		h.logger.ErrorContext(r.Context(), "sso: claim nonce", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	userID, created, err := h.ssoResolveUser(r.Context(), claims)
+	switch {
+	case errors.Is(err, errSSOArchived):
+		h.writeError(w, http.StatusUnauthorized, "account is archived")
+		return
+	case err != nil:
+		h.logger.ErrorContext(r.Context(), "sso: resolve user", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	if err := h.createSession(r.Context(), w, userID); err != nil {
+		h.logger.ErrorContext(r.Context(), "sso: create session", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	h.logger.InfoContext(r.Context(), "sso: session handed off",
+		"iss", claims.Iss, "user_id", userID, "user_created", created)
+	http.Redirect(w, r, next, http.StatusFound)
+}
+
+// errSSOArchived reports that the token named a real but offboarded user. Archived
+// means no login by every other path (see §6), and a shared secret does not change that.
+var errSSOArchived = errors.New("sso: user is archived")
+
+// ssoResolveUser maps the token's sub to a user id, creating the user when the email is
+// unknown. It reports whether the user was created.
+//
+// Role handling is deliberately asymmetric. On creation the claim's role is applied, so
+// the identity system provisions people directly. On an existing user the role is left
+// alone — a workspace's roles are the workspace's business, and letting a hand-off
+// rewrite them on every sign-in would make the admin UI's role controls advisory. The
+// single exception is bootstrapping: a claim asking for owner is honoured when the
+// instance has no owner, because the one-owner invariant TransferOwnership maintains
+// means there is nothing to displace.
+func (h *Handler) ssoResolveUser(ctx context.Context, claims ssoClaims) (userID string, created bool, err error) {
+	email := strings.ToLower(strings.TrimSpace(claims.Sub))
+
+	var archivedAt sql.NullString
+	err = h.db.QueryRowContext(ctx,
+		`SELECT id, archived_at FROM users WHERE email = ?`, email).Scan(&userID, &archivedAt)
+	switch {
+	case err == sql.ErrNoRows:
+		// Unknown email: create. This is the one path that creates a user without an
+		// invite; it is reachable only by a caller holding the shared secret.
+		isAdmin, isOwner := 0, 0
+		switch claims.Role {
+		case "owner":
+			isAdmin = 1
+			if !h.ssoOwnerExists(ctx) {
+				isOwner = 1
+			}
+		case "admin":
+			isAdmin = 1
+		}
+		userID = uid.New()
+		if _, err := h.db.ExecContext(ctx, `
+			INSERT INTO users (id, email, name, iana_timezone, is_admin, is_owner, email_login)
+			VALUES (?, ?, ?, 'UTC', ?, ?, 0)`,
+			userID, email, claims.Name, isAdmin, isOwner); err != nil {
+			return "", false, err
+		}
+		return userID, true, nil
+
+	case err != nil:
+		return "", false, err
+	}
+
+	if archivedAt.Valid {
+		return "", false, errSSOArchived
+	}
+	if claims.Role == "owner" && !h.ssoOwnerExists(ctx) {
+		if _, err := h.db.ExecContext(ctx,
+			`UPDATE users SET is_owner = 1, is_admin = 1 WHERE id = ?`, userID); err != nil {
+			return "", false, err
+		}
+	}
+	return userID, false, nil
+}
+
+// ssoOwnerExists reports whether the instance already has an owner. A read error is
+// reported as "yes" so a failed check never hands out ownership.
+func (h *Handler) ssoOwnerExists(ctx context.Context) bool {
+	var n int
+	if err := h.db.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM users WHERE is_owner = 1 AND archived_at IS NULL`).Scan(&n); err != nil {
+		h.logger.ErrorContext(ctx, "sso: count owners", "error", err)
+		return true
+	}
+	return n > 0
+}
+
+// ssoNextPath validates the optional ?next= target, returning the default when it is
+// absent. Only a same-origin absolute path is allowed; anything else is refused rather
+// than sanitised, because a redirect built from a partially-cleaned value is how open
+// redirects survive their own fix.
+func ssoNextPath(next string) (string, error) {
+	if next == "" {
+		return ssoDefaultNext, nil
+	}
+	switch {
+	case !strings.HasPrefix(next, "/"):
+		return "", errors.New("next must be an absolute path")
+	case strings.HasPrefix(next, "//"):
+		// Protocol-relative: "//evil.example" is another origin, not a local path.
+		return "", errors.New("next must not start with //")
+	case strings.Contains(next, `\`):
+		// Some browsers normalise a backslash to a slash, so "/\evil.example" is a
+		// protocol-relative URL wearing a disguise.
+		return "", errors.New(`next must not contain a backslash`)
+	case strings.Contains(next, "://"):
+		return "", errors.New("next must not contain a scheme")
+	}
+	for _, c := range next {
+		if c < 0x20 || c == 0x7f {
+			// A CR or LF would split the Location header; the rest are never legitimate
+			// in a path either.
+			return "", errors.New("next must not contain control characters")
+		}
+	}
+	return next, nil
+}
+
+// verifySSOToken parses a compact JWS and verifies its HS256 signature with secret,
+// returning the claims. The error names what was wrong in terms the operator can act
+// on, and never echoes any part of the token back — an error body is attacker-reachable.
+func verifySSOToken(token, secret string) (ssoClaims, error) {
+	var claims ssoClaims
+
+	parts := strings.Split(token, ".")
+	if len(parts) != 3 {
+		return claims, errors.New("token is not a three-part JWT")
+	}
+
+	headerJSON, err := base64.RawURLEncoding.DecodeString(parts[0])
+	if err != nil {
+		return claims, errors.New("token header is not base64url")
+	}
+	var header struct {
+		Alg string `json:"alg"`
+		Typ string `json:"typ"`
+	}
+	if err := json.Unmarshal(headerJSON, &header); err != nil {
+		return claims, errors.New("token header is not JSON")
+	}
+	// Checked before the signature: accepting the token's own choice of algorithm is the
+	// JWT downgrade attack ("none", or an RS256 key confusion), and the message stays
+	// fixed rather than quoting the value back.
+	if header.Alg != "HS256" {
+		return claims, errors.New("token alg must be HS256")
+	}
+
+	sig, err := base64.RawURLEncoding.DecodeString(parts[2])
+	if err != nil {
+		return claims, errors.New("token signature is not base64url")
+	}
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write([]byte(parts[0] + "." + parts[1]))
+	if !hmac.Equal(sig, mac.Sum(nil)) { // constant time
+		return claims, errors.New("token signature does not verify")
+	}
+
+	claimsJSON, err := base64.RawURLEncoding.DecodeString(parts[1])
+	if err != nil {
+		return claims, errors.New("token payload is not base64url")
+	}
+	if err := json.Unmarshal(claimsJSON, &claims); err != nil {
+		return claims, errors.New("token payload is not JSON")
+	}
+	return claims, nil
+}
+
+// validate checks the claim set against this instance and the current time. aud is the
+// instance's BASE_URL: binding the token to one audience is what stops a token minted
+// for a staging instance being spent on production, when both share a secret by mistake.
+func (c ssoClaims) validate(aud string, now time.Time) error {
+	if c.Iss == "" {
+		return errors.New("iss is required")
+	}
+	if c.Aud == "" || c.Aud != aud {
+		return errors.New("aud does not match this instance")
+	}
+	// A full RFC 5322 parse is not the point; the value is looked up against a column
+	// whose contents are addresses, so this only rejects the obviously-not-an-address.
+	if s := strings.TrimSpace(c.Sub); s == "" || !strings.Contains(s, "@") {
+		return errors.New("sub must be an email address")
+	}
+	if strings.TrimSpace(c.Name) == "" {
+		return errors.New("name is required")
+	}
+	switch c.Role {
+	case "owner", "admin", "member":
+	default:
+		return errors.New("role must be owner, admin or member")
+	}
+	if c.JTI == "" {
+		return errors.New("jti is required")
+	}
+	if c.Iat == 0 {
+		return errors.New("iat is required")
+	}
+	if c.Exp == 0 {
+		return errors.New("exp is required")
+	}
+
+	iat, exp := time.Unix(c.Iat, 0), time.Unix(c.Exp, 0)
+	if !exp.After(iat) {
+		return errors.New("exp must be after iat")
+	}
+	if exp.Sub(iat) > ssoMaxTokenLifetime {
+		return errors.New("exp is more than 60s after iat")
+	}
+	if iat.After(now.Add(ssoClockSkew)) {
+		return errors.New("iat is in the future")
+	}
+	if exp.Before(now.Add(-ssoClockSkew)) {
+		return errors.New("exp is in the past")
+	}
+	return nil
+}
diff --git a/internal/handler/sso_test.go b/internal/handler/sso_test.go
new file mode 100644
index 0000000..b458dfb
--- /dev/null
+++ b/internal/handler/sso_test.go
@@ -0,0 +1,358 @@
+package handler_test
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/handler"
+	"github.com/calnode/calnode/internal/uid"
+)
+
+const (
+	ssoSecret  = "shared-secret-for-tests"
+	ssoBaseURL = "https://cal.example.test"
+)
+
+// newSSOHandler returns a handler with the hand-off configured and its audience pinned.
+func newSSOHandler(t *testing.T) (*handler.Handler, *db.DB) {
+	t.Helper()
+	h, database := newTestHandlerDB(t)
+	h.SetBaseURL(ssoBaseURL)
+	h.SetSSOSecret(ssoSecret)
+	return h, database
+}
+
+// ssoToken mints a compact HS256 JWT the way an external identity system would. Kept
+// independent of internal/handler's verifier on purpose: a test that signs with the
+// production code would pass even if both halves were wrong in the same way.
+func ssoToken(t *testing.T, secret string, claims map[string]any) string {
+	t.Helper()
+	enc := func(v any) string {
+		b, err := json.Marshal(v)
+		if err != nil {
+			t.Fatalf("marshal: %v", err)
+		}
+		return base64.RawURLEncoding.EncodeToString(b)
+	}
+	signingInput := enc(map[string]string{"alg": "HS256", "typ": "JWT"}) + "." + enc(claims)
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write([]byte(signingInput))
+	return signingInput + "." + base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
+}
+
+// ssoClaimSet is a valid claim set; cases mutate the one field they are about.
+func ssoClaimSet() map[string]any {
+	now := time.Now().Unix()
+	return map[string]any{
+		"iss":  "identity.example.test",
+		"aud":  ssoBaseURL,
+		"sub":  "handed.over@example.test",
+		"name": "Handed Over",
+		"role": "member",
+		"iat":  now,
+		"exp":  now + 30,
+		"jti":  uid.New(),
+	}
+}
+
+func doSSO(h *handler.Handler, target string) *httptest.ResponseRecorder {
+	rec := httptest.NewRecorder()
+	h.SSOHandoff(rec, httptest.NewRequest(http.MethodGet, target, nil))
+	return rec
+}
+
+func ssoErrorBody(t *testing.T, rec *httptest.ResponseRecorder) string {
+	t.Helper()
+	var body struct {
+		Error string `json:"error"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("decode error body %q: %v", rec.Body.String(), err)
+	}
+	return body.Error
+}
+
+func TestSSOHandoff_createsUserAndSession(t *testing.T) {
+	h, database := newSSOHandler(t)
+
+	rec := doSSO(h, "/v1/auth/sso?token="+ssoToken(t, ssoSecret, ssoClaimSet()))
+
+	if rec.Code != http.StatusFound {
+		t.Fatalf("status = %d; want 302 — %s", rec.Code, rec.Body.String())
+	}
+	if loc := rec.Header().Get("Location"); loc != "/admin/" {
+		t.Errorf("Location = %q; want /admin/", loc)
+	}
+
+	var userID string
+	var isAdmin, isOwner int
+	if err := database.QueryRow(
+		`SELECT id, is_admin, is_owner FROM users WHERE email = ?`,
+		"handed.over@example.test").Scan(&userID, &isAdmin, &isOwner); err != nil {
+		t.Fatalf("user was not created: %v", err)
+	}
+	if isAdmin != 0 || isOwner != 0 {
+		t.Errorf("role flags = admin %d owner %d; want 0 0 for a member claim", isAdmin, isOwner)
+	}
+
+	// The session cookie must name a live session row for that user.
+	var cookie *http.Cookie
+	for _, c := range rec.Result().Cookies() {
+		if c.Name == "calnode_session" {
+			cookie = c
+		}
+	}
+	if cookie == nil {
+		t.Fatal("no calnode_session cookie was set")
+	}
+	var sessionUser string
+	if err := database.QueryRow(
+		`SELECT user_id FROM sessions WHERE id = ?`, cookie.Value).Scan(&sessionUser); err != nil {
+		t.Fatalf("session row: %v", err)
+	}
+	if sessionUser != userID {
+		t.Errorf("session belongs to %q; want %q", sessionUser, userID)
+	}
+}
+
+// A claim asking for owner bootstraps ownership only when nobody holds it. The
+// asymmetry is the point: see ssoResolveUser.
+func TestSSOHandoff_ownerClaimBootstrapsOnlyWhenUnowned(t *testing.T) {
+	h, database := newSSOHandler(t)
+
+	first := ssoClaimSet()
+	first["sub"] = "first.owner@example.test"
+	first["role"] = "owner"
+	if rec := doSSO(h, "/v1/auth/sso?token="+ssoToken(t, ssoSecret, first)); rec.Code != http.StatusFound {
+		t.Fatalf("first hand-off: status = %d — %s", rec.Code, rec.Body.String())
+	}
+
+	second := ssoClaimSet()
+	second["sub"] = "second.owner@example.test"
+	second["role"] = "owner"
+	if rec := doSSO(h, "/v1/auth/sso?token="+ssoToken(t, ssoSecret, second)); rec.Code != http.StatusFound {
+		t.Fatalf("second hand-off: status = %d — %s", rec.Code, rec.Body.String())
+	}
+
+	var owners int
+	if err := database.QueryRow(`SELECT COUNT(*) FROM users WHERE is_owner = 1`).Scan(&owners); err != nil {
+		t.Fatalf("count owners: %v", err)
+	}
+	if owners != 1 {
+		t.Errorf("owners = %d; want exactly 1", owners)
+	}
+	var isAdmin, isOwner int
+	if err := database.QueryRow(`SELECT is_admin, is_owner FROM users WHERE email = ?`,
+		"second.owner@example.test").Scan(&isAdmin, &isOwner); err != nil {
+		t.Fatalf("second user: %v", err)
+	}
+	if isOwner != 0 || isAdmin != 1 {
+		t.Errorf("second user = admin %d owner %d; want admin 1 owner 0", isAdmin, isOwner)
+	}
+}
+
+// An existing user's role is not rewritten by a hand-off (owner-bootstrap aside).
+func TestSSOHandoff_doesNotDemoteAnExistingUser(t *testing.T) {
+	h, database, _, ownerID := setupWorkspaceWithDB(t)
+	h.SetBaseURL(ssoBaseURL)
+	h.SetSSOSecret(ssoSecret)
+
+	var email string
+	if err := database.QueryRow(`SELECT email FROM users WHERE id = ?`, ownerID).Scan(&email); err != nil {
+		t.Fatalf("load owner email: %v", err)
+	}
+
+	claims := ssoClaimSet()
+	claims["sub"] = email
+	claims["role"] = "member"
+	if rec := doSSO(h, "/v1/auth/sso?token="+ssoToken(t, ssoSecret, claims)); rec.Code != http.StatusFound {
+		t.Fatalf("status = %d — %s", rec.Code, rec.Body.String())
+	}
+
+	var isAdmin, isOwner int
+	if err := database.QueryRow(`SELECT is_admin, is_owner FROM users WHERE id = ?`, ownerID).
+		Scan(&isAdmin, &isOwner); err != nil {
+		t.Fatalf("reload owner: %v", err)
+	}
+	if isAdmin != 1 || isOwner != 1 {
+		t.Errorf("owner = admin %d owner %d; want 1 1 (a member claim must not demote)", isAdmin, isOwner)
+	}
+}
+
+func TestSSOHandoff_replayedJTIIsRejected(t *testing.T) {
+	h, _ := newSSOHandler(t)
+	token := ssoToken(t, ssoSecret, ssoClaimSet())
+
+	if rec := doSSO(h, "/v1/auth/sso?token="+token); rec.Code != http.StatusFound {
+		t.Fatalf("first use: status = %d — %s", rec.Code, rec.Body.String())
+	}
+	rec := doSSO(h, "/v1/auth/sso?token="+token)
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("replay: status = %d; want 401", rec.Code)
+	}
+	if got := ssoErrorBody(t, rec); got != "jti has already been used" {
+		t.Errorf("error = %q; want the jti to be named", got)
+	}
+}
+
+func TestSSOHandoff_rejectsBadTokens(t *testing.T) {
+	valid := ssoClaimSet()
+
+	expired := ssoClaimSet()
+	expired["iat"] = time.Now().Add(-10 * time.Minute).Unix()
+	expired["exp"] = time.Now().Add(-10 * time.Minute).Add(30 * time.Second).Unix()
+
+	longLived := ssoClaimSet()
+	longLived["exp"] = longLived["iat"].(int64) + 3600
+
+	wrongAud := ssoClaimSet()
+	wrongAud["aud"] = "https://other.example.test"
+
+	noIss := ssoClaimSet()
+	noIss["iss"] = ""
+
+	badRole := ssoClaimSet()
+	badRole["role"] = "superuser"
+
+	cases := []struct {
+		name      string
+		token     string
+		wantError string
+	}{
+		{"expired", ssoToken(t, ssoSecret, expired), "exp is in the past"},
+		{"lifetime too long", ssoToken(t, ssoSecret, longLived), "exp is more than 60s after iat"},
+		{"wrong aud", ssoToken(t, ssoSecret, wrongAud), "aud does not match this instance"},
+		{"missing iss", ssoToken(t, ssoSecret, noIss), "iss is required"},
+		{"bad role", ssoToken(t, ssoSecret, badRole), "role must be owner, admin or member"},
+		{"bad signature", ssoToken(t, "not-the-shared-secret", valid), "token signature does not verify"},
+		{"not a jwt", "nonsense", "token is not a three-part JWT"},
+		{"no token", "", "token is required"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			h, database := newSSOHandler(t)
+			rec := doSSO(h, "/v1/auth/sso?token="+tc.token)
+			if rec.Code != http.StatusUnauthorized {
+				t.Fatalf("status = %d; want 401 — %s", rec.Code, rec.Body.String())
+			}
+			if got := ssoErrorBody(t, rec); got != tc.wantError {
+				t.Errorf("error = %q; want %q", got, tc.wantError)
+			}
+			var users int
+			if err := database.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&users); err != nil {
+				t.Fatalf("count users: %v", err)
+			}
+			if users != 0 {
+				t.Errorf("users = %d; a rejected token must not create anyone", users)
+			}
+		})
+	}
+}
+
+// An "alg": "none" token with an empty signature is the classic downgrade. It must be
+// refused on the algorithm, before the signature is even compared.
+func TestSSOHandoff_rejectsAlgNone(t *testing.T) {
+	h, _ := newSSOHandler(t)
+	enc := func(v any) string {
+		b, _ := json.Marshal(v)
+		return base64.RawURLEncoding.EncodeToString(b)
+	}
+	token := enc(map[string]string{"alg": "none", "typ": "JWT"}) + "." + enc(ssoClaimSet()) + "."
+
+	rec := doSSO(h, "/v1/auth/sso?token="+token)
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status = %d; want 401", rec.Code)
+	}
+	if got := ssoErrorBody(t, rec); got != "token alg must be HS256" {
+		t.Errorf("error = %q; want the alg to be named", got)
+	}
+}
+
+func TestSSOHandoff_nextMustBeSameOriginPath(t *testing.T) {
+	cases := []struct {
+		name string
+		next string
+	}{
+		{"absolute url", "https://evil.example.test/"},
+		{"protocol relative", "//evil.example.test/"},
+		{"backslash", `/\evil.example.test`},
+		{"scheme inside", "/redirect?to=https://evil.example.test"},
+		{"not a path", "admin/"},
+		{"header injection", "/admin/\r\nX-Injected: 1"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			h, database := newSSOHandler(t)
+			token := ssoToken(t, ssoSecret, ssoClaimSet())
+			rec := doSSO(h, "/v1/auth/sso?token="+token+"&next="+url.QueryEscape(tc.next))
+			if rec.Code != http.StatusBadRequest {
+				t.Fatalf("status = %d; want 400 — %s", rec.Code, rec.Body.String())
+			}
+			// The token was refused before its nonce was claimed, so the caller can
+			// retry the same one with a sane next.
+			var nonces int
+			if err := database.QueryRow(`SELECT COUNT(*) FROM sso_nonces`).Scan(&nonces); err != nil {
+				t.Fatalf("count nonces: %v", err)
+			}
+			if nonces != 0 {
+				t.Errorf("nonces = %d; a bad next must not burn the token", nonces)
+			}
+		})
+	}
+}
+
+func TestSSOHandoff_nextHonoursALocalPath(t *testing.T) {
+	h, _ := newSSOHandler(t)
+	rec := doSSO(h, "/v1/auth/sso?token="+ssoToken(t, ssoSecret, ssoClaimSet())+"&next=%2Fadmin%2Fbookings")
+	if rec.Code != http.StatusFound {
+		t.Fatalf("status = %d; want 302 — %s", rec.Code, rec.Body.String())
+	}
+	if loc := rec.Header().Get("Location"); loc != "/admin/bookings" {
+		t.Errorf("Location = %q; want /admin/bookings", loc)
+	}
+}
+
+// Unset CALNODE_SSO_SHARED_SECRET ⇒ 404, indistinguishable from a build without the
+// feature. Documented in DEPLOY.md and ARCHITECTURE.md §6.
+func TestSSOHandoff_disabledWithoutASecret(t *testing.T) {
+	h, _ := newTestHandlerDB(t)
+	h.SetBaseURL(ssoBaseURL)
+
+	rec := doSSO(h, "/v1/auth/sso?token="+ssoToken(t, ssoSecret, ssoClaimSet()))
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status = %d; want 404 — %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestSSOHandoff_archivedUserCannotSignIn(t *testing.T) {
+	h, database, _, ownerID := setupWorkspaceWithDB(t)
+	h.SetBaseURL(ssoBaseURL)
+	h.SetSSOSecret(ssoSecret)
+
+	var email string
+	if err := database.QueryRow(`SELECT email FROM users WHERE id = ?`, ownerID).Scan(&email); err != nil {
+		t.Fatalf("load owner email: %v", err)
+	}
+	if _, err := database.Exec(`UPDATE users SET archived_at = ? WHERE id = ?`,
+		time.Now().UTC().Format(time.RFC3339), ownerID); err != nil {
+		t.Fatalf("archive user: %v", err)
+	}
+
+	claims := ssoClaimSet()
+	claims["sub"] = email
+	rec := doSSO(h, "/v1/auth/sso?token="+ssoToken(t, ssoSecret, claims))
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status = %d; want 401 — %s", rec.Code, rec.Body.String())
+	}
+	if got := ssoErrorBody(t, rec); got != "account is archived" {
+		t.Errorf("error = %q; want the archive to be named", got)
+	}
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index c17168d..1fc67f1 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -43,6 +43,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	h.SetPublicBaseURL(cfg.PublicBaseURL)
 	h.SetDataDir("data")
 	h.SetEncKey(cfg.EncryptionKey)
+	h.SetSSOSecret(cfg.SSOSharedSecret)
 	h.SetDemoMode(cfg.DemoMode)
 	h.SetDemoResetInterval(cfg.DemoResetInterval)
 
@@ -280,6 +281,12 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	mux.HandleFunc("GET /v1/auth/callback", authRL(h.CallbackGoogle))
 	mux.HandleFunc("GET /v1/auth/microsoft/login", authRL(h.LoginMicrosoft))
 	mux.HandleFunc("GET /v1/auth/microsoft/callback", authRL(h.CallbackMicrosoft))
+	// Signed session hand-off from an external identity system. Registered
+	// unconditionally and gated inside the handler on the shared secret, so an
+	// unconfigured instance answers 404 rather than exposing whether the route exists
+	// at all. Same limiter as the OAuth callbacks: it is an unauthenticated endpoint
+	// that does an HMAC and a write.
+	mux.HandleFunc("GET /v1/auth/sso", authRL(h.SSOHandoff))
 	mux.HandleFunc("POST /v1/auth/logout", h.Logout)
 
 	// MCP server (Model Context Protocol) — Streamable HTTP transport for remote
diff --git a/internal/worker/worker.go b/internal/worker/worker.go
index 9188957..ed0ef63 100644
--- a/internal/worker/worker.go
+++ b/internal/worker/worker.go
@@ -115,6 +115,13 @@ func (w *Worker) Poll(ctx context.Context) {
 		`DELETE FROM magic_link_tokens WHERE expires_at < ? OR used_at IS NOT NULL`, now); err != nil {
 		w.logger.Error("worker: purge magic link tokens", "error", err)
 	}
+	// SSO hand-off nonces exist only to refuse a replay inside the token's own validity
+	// window (at most ~60s), so a row past its expires_at can never reject anything and
+	// is pure growth. Nothing reads them back except the INSERT that claims one.
+	if _, err := w.db.ExecContext(ctx,
+		`DELETE FROM sso_nonces WHERE expires_at < ?`, now); err != nil {
+		w.logger.Error("worker: purge sso nonces", "error", err)
+	}
 	// Idempotency keys are only useful for the retry window of the original
 	// request; purge them 24h after creation so the table stays small.
 	idemCutoff := time.Now().UTC().Add(-24 * time.Hour).Format(time.RFC3339)

From 82bce26f92631c3c5a54758c8edc4fdb382877dd Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:09:33 -0400
Subject: [PATCH 17/51] auth: sign out everywhere, including the MCP connectors

POST /v1/auth/sessions/revoke-all. With no body it drops every session the
caller has except the one that made the request, which is the action people
actually want when a laptop goes missing: Logout already ends the current
session, and a 30-day cookie on a machine you no longer hold is the thing with
no answer. An API-key caller has no current session, so for them every row goes.

With {"user_id": "..."} it becomes an offboarding tool, on the same tiers
roles.go already enforces: an admin may revoke a member, only the owner may
revoke another admin, and the owner's sessions can be ended only by the owner
(there is exactly one owner, so that is the self branch). The actor's tier is
checked before the target is loaded, so this endpoint's 404 cannot be used to
enumerate user ids.

It also deletes the target's oauth_access_tokens rows. That is what makes it an
offboarding tool rather than a convenience: an MCP connector authenticates with a
bearer token, not the session cookie, so revoking sessions alone would leave an
agent connected with exactly the authority just withdrawn. Both deletes share one
transaction, because a caller told "revoked" must not keep a token on account of
the second statement failing after the first committed.
---
 CHANGELOG.md                     |  11 ++
 docs/ARCHITECTURE.md             |  12 ++
 internal/handler/session.go      | 130 +++++++++++++++
 internal/handler/session_test.go | 266 +++++++++++++++++++++++++++++++
 internal/server/server.go        |   3 +
 5 files changed, 422 insertions(+)
 create mode 100644 internal/handler/session_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a2ba4d..d40fe53 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,17 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
 ## [Unreleased]
 
 ### Added
+- **Sign out everywhere.** `POST /v1/auth/sessions/revoke-all` ends every session you
+  have except the one you asked from, so losing a laptop no longer means waiting out a
+  30-day cookie. Pass `{"user_id": "..."}` and an admin can do the same for someone
+  else: an admin may revoke a member, only the owner may revoke another admin, and the
+  owner's own sessions can only be ended by the owner.
+
+  It also revokes that person's MCP OAuth tokens, which is the part that makes it an
+  offboarding tool rather than a convenience. A connected agent authenticates with a
+  bearer token and not the session cookie, so ending the sessions alone would have left
+  it holding exactly the access that was just withdrawn.
+
 - **Signed session hand-off, so an identity system you already run can sign people in.**
   `GET /v1/auth/sso?token=<jwt>` accepts a short-lived HS256 JWT signed with a shared
   secret and starts an ordinary Calnode session, redirecting to `/admin/` (or to a
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 57338b5..b7c0e2f 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -226,6 +226,18 @@ the platform/recovery secret doesn't expose secrets.
   Owner-gated actions: grant/revoke admin, transfer ownership. Admins can cancel
   any booking, see all bookings, manage teams/members. Safe-removal + archive
   guards prevent orphaning.
+- **Sign out everywhere** (`POST /v1/auth/sessions/revoke-all`, `session.go`). With no
+  body it drops all of the caller's sessions **except the one that made the request** —
+  "sign out my other devices", as distinct from `POST /v1/auth/logout`, which ends the
+  current one. (An API-key caller has no current session, so for them every session
+  goes.) With `{"user_id": "..."}` it is an offboarding tool, gated on the same tiers as
+  `roles.go`: an admin may revoke a member, only the owner may revoke another admin, and
+  the owner's sessions are reachable only by the owner. The actor's tier is checked
+  *before* the target is loaded, so the 404 cannot be used to enumerate user ids.
+  ⛔ It also deletes the target's rows in **`oauth_access_tokens`**, cutting off any MCP
+  connector (§19) — those authenticate with a bearer token, not the session cookie, so
+  revoking sessions alone would leave an agent holding the authority just withdrawn.
+  Both deletes run in one transaction, so "revoked" is never half-true.
 - **Signed session hand-off** (`GET /v1/auth/sso?token=<jwt>`, `sso.go`) lets an
   external identity system that has already authenticated someone drop them into a
   Calnode session without a second login. **Off unless `CALNODE_SSO_SHARED_SECRET` is
diff --git a/internal/handler/session.go b/internal/handler/session.go
index 5f54cff..8b65102 100644
--- a/internal/handler/session.go
+++ b/internal/handler/session.go
@@ -3,7 +3,11 @@ package handler
 import (
 	"context"
 	"crypto/rand"
+	"database/sql"
 	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
 	"net/http"
 	"time"
 )
@@ -32,3 +36,129 @@ func (h *Handler) createSession(ctx context.Context, w http.ResponseWriter, user
 	})
 	return nil
 }
+
+// RevokeAllSessions handles POST /v1/auth/sessions/revoke-all.
+//
+// Body: `{"user_id": "..."}`, optional.
+//
+//   - Omitted (or naming the caller): signs the caller out everywhere **except the
+//     session that made the request**. "Sign out my other devices" is the action people
+//     actually want; dropping the current session too would log the operator out of the
+//     page they clicked it on, which is what Logout is for. A caller authenticating with
+//     an API key has no current session, so for them every session goes.
+//   - Naming someone else: an offboarding tool. Admin-only, and mirroring roles.go's
+//     tiers — an admin may revoke a member, only the owner may revoke another admin, and
+//     nobody may revoke the owner's sessions but the owner (there is exactly one owner,
+//     so that case is the self branch).
+//
+// It also deletes the target's MCP OAuth access tokens. An MCP connector authenticates
+// with a bearer token rather than the session cookie (§19), so revoking sessions alone
+// would leave an agent connected with exactly the authority that was just taken away —
+// the failure mode being cut off from is a laptop that walked out of the building with a
+// signed-in browser AND a connected agent on it.
+func (h *Handler) RevokeAllSessions(w http.ResponseWriter, r *http.Request) {
+	actor, ok := userFromContext(r.Context())
+	if !ok {
+		h.writeError(w, http.StatusUnauthorized, "authentication required")
+		return
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<10)
+	var req struct {
+		UserID string `json:"user_id"`
+	}
+	// An empty body is the common case (revoke my own), so EOF is not an error here.
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil && !errors.Is(err, io.EOF) {
+		h.writeError(w, http.StatusBadRequest, "invalid JSON")
+		return
+	}
+
+	targetID := req.UserID
+	self := targetID == "" || targetID == actor.ID
+	if self {
+		targetID = actor.ID
+	} else {
+		// The actor's capability class is checked before the target is looked up, so a
+		// member cannot use this endpoint's 404 to probe which user ids exist.
+		if !actor.IsAdmin {
+			h.writeError(w, http.StatusForbidden, "admin access required")
+			return
+		}
+		var targetIsAdmin, targetIsOwner int
+		err := h.db.QueryRowContext(r.Context(),
+			`SELECT is_admin, is_owner FROM users WHERE id = ?`, targetID).
+			Scan(&targetIsAdmin, &targetIsOwner)
+		if err == sql.ErrNoRows {
+			h.writeError(w, http.StatusNotFound, "user not found")
+			return
+		}
+		if err != nil {
+			h.logger.ErrorContext(r.Context(), "revoke sessions: load target", "error", err)
+			h.writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		if targetIsOwner != 0 {
+			h.writeError(w, http.StatusForbidden, "the owner's sessions can only be revoked by the owner")
+			return
+		}
+		if targetIsAdmin != 0 && !actor.IsOwner {
+			h.writeError(w, http.StatusForbidden, "only the workspace owner can revoke another admin's sessions")
+			return
+		}
+	}
+
+	// One transaction: a caller told "revoked" must not have kept an MCP token because
+	// the second statement failed after the first committed.
+	tx, err := h.db.BeginTx(r.Context(), nil)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "revoke sessions: begin tx", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	defer tx.Rollback() //nolint:errcheck
+
+	var sessionRes sql.Result
+	if self {
+		current := ""
+		if c, cerr := r.Cookie(sessionCookieName); cerr == nil {
+			current = c.Value
+		}
+		sessionRes, err = tx.ExecContext(r.Context(),
+			`DELETE FROM sessions WHERE user_id = ? AND id <> ?`, targetID, current)
+	} else {
+		sessionRes, err = tx.ExecContext(r.Context(),
+			`DELETE FROM sessions WHERE user_id = ?`, targetID)
+	}
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "revoke sessions: delete sessions", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	tokenRes, err := tx.ExecContext(r.Context(),
+		`DELETE FROM oauth_access_tokens WHERE user_id = ?`, targetID)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "revoke sessions: delete oauth tokens", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	if err := tx.Commit(); err != nil {
+		h.logger.ErrorContext(r.Context(), "revoke sessions: commit", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	sessions, _ := sessionRes.RowsAffected()
+	tokens, _ := tokenRes.RowsAffected()
+	h.logger.InfoContext(r.Context(), "sessions revoked",
+		"actor_id", actor.ID, "user_id", targetID, "self", self,
+		"sessions", sessions, "oauth_tokens", tokens)
+
+	h.writeJSON(w, http.StatusOK, map[string]any{
+		"ok":                   true,
+		"user_id":              targetID,
+		"sessions_revoked":     sessions,
+		"oauth_tokens_revoked": tokens,
+	})
+}
diff --git a/internal/handler/session_test.go b/internal/handler/session_test.go
new file mode 100644
index 0000000..b84fc2c
--- /dev/null
+++ b/internal/handler/session_test.go
@@ -0,0 +1,266 @@
+package handler_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/handler"
+)
+
+// seedSessionID inserts a live session row under a caller-chosen id (the cookie value),
+// so one user can be given several and a test can name the one it presents.
+func seedSessionID(t *testing.T, database *db.DB, id, userID string) string {
+	t.Helper()
+	if _, err := database.Exec(`INSERT INTO sessions (id, user_id, expires_at) VALUES (?, ?, ?)`,
+		id, userID, time.Now().UTC().Add(24*time.Hour).Format(time.RFC3339)); err != nil {
+		t.Fatalf("seed session %s: %v", id, err)
+	}
+	return id
+}
+
+// seedMCPToken inserts an MCP OAuth access token for userID.
+func seedMCPToken(t *testing.T, database *db.DB, id, userID string) {
+	t.Helper()
+	if _, err := database.Exec(`
+		INSERT INTO oauth_access_tokens (id, token_hash, client_id, user_id, expires_at, created_at)
+		VALUES (?, ?, 'client-1', ?, ?, ?)`,
+		id, "hash-"+id, userID,
+		time.Now().UTC().Add(time.Hour).Format(time.RFC3339),
+		time.Now().UTC().Format(time.RFC3339)); err != nil {
+		t.Fatalf("seed mcp token %s: %v", id, err)
+	}
+}
+
+func countSessions(t *testing.T, database *db.DB, userID string) int {
+	t.Helper()
+	var n int
+	if err := database.QueryRow(`SELECT COUNT(*) FROM sessions WHERE user_id = ?`, userID).Scan(&n); err != nil {
+		t.Fatalf("count sessions: %v", err)
+	}
+	return n
+}
+
+func countMCPTokens(t *testing.T, database *db.DB, userID string) int {
+	t.Helper()
+	var n int
+	if err := database.QueryRow(`SELECT COUNT(*) FROM oauth_access_tokens WHERE user_id = ?`, userID).Scan(&n); err != nil {
+		t.Fatalf("count mcp tokens: %v", err)
+	}
+	return n
+}
+
+// revokeAll drives the handler through RequireAuth. cookie is the session cookie value
+// to present (empty for none); apiKey authenticates when no cookie is given.
+func revokeAll(h *handler.Handler, body, apiKey, cookie string) *httptest.ResponseRecorder {
+	var r *http.Request
+	if body != "" {
+		r = httptest.NewRequest(http.MethodPost, "/v1/auth/sessions/revoke-all", strings.NewReader(body))
+		r.Header.Set("Content-Type", "application/json")
+	} else {
+		r = httptest.NewRequest(http.MethodPost, "/v1/auth/sessions/revoke-all", nil)
+	}
+	if apiKey != "" {
+		r.Header.Set("X-API-Key", apiKey)
+	}
+	if cookie != "" {
+		r.AddCookie(&http.Cookie{Name: "calnode_session", Value: cookie})
+	}
+	rec := httptest.NewRecorder()
+	h.RequireAuth(h.RevokeAllSessions)(rec, r)
+	return rec
+}
+
+// Revoking your own keeps the session that asked. That is the difference between this
+// endpoint and Logout, and the reason it is the default with no body.
+func TestRevokeAllSessions_selfKeepsTheCallingSession(t *testing.T) {
+	h, database, _, ownerID := setupWorkspaceWithDB(t)
+	current := seedSessionID(t, database, "sess-current", ownerID)
+	seedSessionID(t, database, "sess-laptop", ownerID)
+	seedSessionID(t, database, "sess-phone", ownerID)
+
+	rec := revokeAll(h, "", "", current)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	var resp struct {
+		SessionsRevoked int `json:"sessions_revoked"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.SessionsRevoked != 2 {
+		t.Errorf("sessions_revoked = %d; want 2", resp.SessionsRevoked)
+	}
+	if n := countSessions(t, database, ownerID); n != 1 {
+		t.Fatalf("sessions left = %d; want 1 (the calling one)", n)
+	}
+	var left string
+	if err := database.QueryRow(`SELECT id FROM sessions WHERE user_id = ?`, ownerID).Scan(&left); err != nil {
+		t.Fatalf("read surviving session: %v", err)
+	}
+	if left != current {
+		t.Errorf("surviving session = %q; want %q", left, current)
+	}
+}
+
+// An API-key caller has no current session, so there is none to spare.
+func TestRevokeAllSessions_apiKeyCallerRevokesEveryone(t *testing.T) {
+	h, database, ownerKey, ownerID := setupWorkspaceWithDB(t)
+	seedSessionID(t, database, "sess-a", ownerID)
+	seedSessionID(t, database, "sess-b", ownerID)
+
+	rec := revokeAll(h, "", ownerKey, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	if n := countSessions(t, database, ownerID); n != 0 {
+		t.Errorf("sessions left = %d; want 0", n)
+	}
+}
+
+// An MCP connector holds a bearer token, not a cookie. Revoking sessions and leaving it
+// would hand back exactly the access that was just withdrawn.
+func TestRevokeAllSessions_cutsMCPTokensToo(t *testing.T) {
+	h, database, ownerKey, ownerID := setupWorkspaceWithDB(t)
+	seedMCPToken(t, database, "tok-1", ownerID)
+	seedMCPToken(t, database, "tok-2", ownerID)
+
+	rec := revokeAll(h, "", ownerKey, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	var resp struct {
+		OAuthTokensRevoked int `json:"oauth_tokens_revoked"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.OAuthTokensRevoked != 2 {
+		t.Errorf("oauth_tokens_revoked = %d; want 2", resp.OAuthTokensRevoked)
+	}
+	if n := countMCPTokens(t, database, ownerID); n != 0 {
+		t.Errorf("mcp tokens left = %d; want 0", n)
+	}
+}
+
+// seedRoleUser inserts a user with the given flags plus an API key for them.
+func seedRoleUser(t *testing.T, database *db.DB, id, email string, isAdmin, isOwner int, apiKey string) {
+	t.Helper()
+	if _, err := database.Exec(
+		`INSERT INTO users (id,email,name,iana_timezone,is_admin,is_owner) VALUES (?,?,?,'UTC',?,?)`,
+		id, email, id, isAdmin, isOwner); err != nil {
+		t.Fatalf("seed user %s: %v", id, err)
+	}
+	if apiKey != "" {
+		if _, err := database.Exec(
+			`INSERT INTO api_keys (id,user_id,name,key_hash,created_at) VALUES (?,?,'t',?,'2024-01-01')`,
+			"key-"+id, id, sha256HexForTest(apiKey)); err != nil {
+			t.Fatalf("seed api key for %s: %v", id, err)
+		}
+	}
+}
+
+func TestRevokeAllSessions_memberCannotTargetAnotherUser(t *testing.T) {
+	h, database, _, _ := setupWorkspaceWithDB(t)
+	seedRoleUser(t, database, "member-1", "m1@example.com", 0, 0, "member-1-key")
+	seedRoleUser(t, database, "member-2", "m2@example.com", 0, 0, "")
+	seedSessionID(t, database, "sess-victim", "member-2")
+
+	rec := revokeAll(h, `{"user_id":"member-2"}`, "member-1-key", "")
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d; want 403 — %s", rec.Code, rec.Body.String())
+	}
+	if n := countSessions(t, database, "member-2"); n != 1 {
+		t.Errorf("victim sessions = %d; want 1 (untouched)", n)
+	}
+}
+
+func TestRevokeAllSessions_adminRevokesAMember(t *testing.T) {
+	h, database, _, _ := setupWorkspaceWithDB(t)
+	seedRoleUser(t, database, "admin-1", "a1@example.com", 1, 0, "admin-1-key")
+	seedRoleUser(t, database, "member-1", "m1@example.com", 0, 0, "")
+	seedSessionID(t, database, "sess-m1a", "member-1")
+	seedSessionID(t, database, "sess-m1b", "member-1")
+	seedMCPToken(t, database, "tok-m1", "member-1")
+
+	rec := revokeAll(h, `{"user_id":"member-1"}`, "admin-1-key", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	if n := countSessions(t, database, "member-1"); n != 0 {
+		t.Errorf("member sessions = %d; want 0", n)
+	}
+	if n := countMCPTokens(t, database, "member-1"); n != 0 {
+		t.Errorf("member mcp tokens = %d; want 0", n)
+	}
+}
+
+func TestRevokeAllSessions_onlyTheOwnerRevokesAnAdmin(t *testing.T) {
+	h, database, ownerKey, _ := setupWorkspaceWithDB(t)
+	seedRoleUser(t, database, "admin-1", "a1@example.com", 1, 0, "admin-1-key")
+	seedRoleUser(t, database, "admin-2", "a2@example.com", 1, 0, "")
+	seedSessionID(t, database, "sess-a2", "admin-2")
+
+	// Admin → admin is refused.
+	rec := revokeAll(h, `{"user_id":"admin-2"}`, "admin-1-key", "")
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("admin targeting admin: status = %d; want 403 — %s", rec.Code, rec.Body.String())
+	}
+	if n := countSessions(t, database, "admin-2"); n != 1 {
+		t.Fatalf("admin-2 sessions = %d; want 1 (untouched)", n)
+	}
+
+	// Owner → admin is allowed.
+	rec = revokeAll(h, `{"user_id":"admin-2"}`, ownerKey, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("owner targeting admin: status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	if n := countSessions(t, database, "admin-2"); n != 0 {
+		t.Errorf("admin-2 sessions = %d; want 0", n)
+	}
+}
+
+// Nobody signs the owner out but the owner, mirroring roles.go refusing to change the
+// owner's role.
+func TestRevokeAllSessions_ownerIsOffLimitsToAdmins(t *testing.T) {
+	h, database, _, ownerID := setupWorkspaceWithDB(t)
+	seedRoleUser(t, database, "admin-1", "a1@example.com", 1, 0, "admin-1-key")
+	seedSessionID(t, database, "sess-owner", ownerID)
+
+	rec := revokeAll(h, `{"user_id":"`+ownerID+`"}`, "admin-1-key", "")
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d; want 403 — %s", rec.Code, rec.Body.String())
+	}
+	if n := countSessions(t, database, ownerID); n != 1 {
+		t.Errorf("owner sessions = %d; want 1 (untouched)", n)
+	}
+}
+
+func TestRevokeAllSessions_unknownUserIs404(t *testing.T) {
+	h, _, ownerKey, _ := setupWorkspaceWithDB(t)
+
+	rec := revokeAll(h, `{"user_id":"nobody"}`, ownerKey, "")
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status = %d; want 404 — %s", rec.Code, rec.Body.String())
+	}
+}
+
+// Naming yourself is the self branch, not the admin branch: a member may do it.
+func TestRevokeAllSessions_namingYourselfIsSelf(t *testing.T) {
+	h, database, _, _ := setupWorkspaceWithDB(t)
+	seedRoleUser(t, database, "member-1", "m1@example.com", 0, 0, "member-1-key")
+	seedSessionID(t, database, "sess-m1", "member-1")
+
+	rec := revokeAll(h, `{"user_id":"member-1"}`, "member-1-key", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	if n := countSessions(t, database, "member-1"); n != 0 {
+		t.Errorf("sessions left = %d; want 0 (api-key caller has no current session)", n)
+	}
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index 1fc67f1..4a804d1 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -288,6 +288,9 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	// that does an HMAC and a write.
 	mux.HandleFunc("GET /v1/auth/sso", authRL(h.SSOHandoff))
 	mux.HandleFunc("POST /v1/auth/logout", h.Logout)
+	// Sign out everywhere. Own sessions for anyone; someone else's for an admin, which
+	// is the offboarding half. Also cuts that user's MCP OAuth tokens.
+	mux.HandleFunc("POST /v1/auth/sessions/revoke-all", h.RequireAuth(h.RevokeAllSessions))
 
 	// MCP server (Model Context Protocol) — Streamable HTTP transport for remote
 	// agents. One server instance reused across requests. Guarded by a bearer token:

From d18bfabf7d4c0571c854b9c914311f377cdd068a Mon Sep 17 00:00:00 2001
From: Sean Dean <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:10:08 -0400
Subject: [PATCH 18/51] docs: record Boundary 7 on the branch log

The four remaining items and what was measured for each: 54 columns across 27
tables pinned to COLLATE "C", the server collation the control fired against
(en_US.utf8, libc) and the correction that the two shapes the schema really
stores do not flip under any of the 878 collations installed there, RETURNING
position giving 0/1/2 then 9 then 10 identically on both engines, and the pool
keeping 1 idle connection with WithPool(4, 1).

Open item 2 is marked closed in place rather than deleted, since Boundary 6 is
where it was raised.
---
 PROGRESS.md | 144 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 143 insertions(+), 1 deletion(-)

diff --git a/PROGRESS.md b/PROGRESS.md
index 3db55d1..db9b91f 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -203,4 +203,146 @@ retries within a bounded budget. Three consecutive full PostgreSQL runs clean.
    `run_at <= ?`). That is byte ordering under SQLite. Under a non-`C` Postgres
    collation, ordering of mixed shapes (a space-separated `run_at` against a
    `T`-separated one) is not guaranteed to match. Worth either `COLLATE "C"` on
-   those columns or a deliberate decision that it is safe.
+   those columns or a deliberate decision that it is safe. **Closed by Boundary 7.**
+
+## Boundary 7 — the last four items — DONE
+
+Open item 2 above, the `RETURNING` clause Boundary 2 left unverified, the bare
+`Open` the port had been dragging along, and the hard-coded pool size.
+
+### 1. TEXT timestamps are `COLLATE "C"` — migration 00059
+
+**54 columns across 27 tables**, enumerated from the migrated schema rather than
+from memory: every `*_at` (49 of them, including `locked_until`), plus
+`availability_rules.start_time`/`end_time` and `availability_overrides.date`/
+`start_time`/`end_time`, which hold `HH:MM` and `YYYY-MM-DD` and are ordered as
+times too (`ORDER BY day_of_week, start_time`, `ORDER BY date`). One grouped
+`ALTER TABLE` per table, so each is rewritten once. The SQLite half is a no-op
+file: BINARY *is* memcmp, so there is nothing to pin, and the file exists because
+the directories keep one file per version.
+
+Fixed in the schema rather than in the predicates. There are ~20 distinct
+lexicographic time comparisons in the tree (`run_at <= ?`, `expires_at > ?`,
+`locked_until < ?`, `decided_at BETWEEN`, `start_at`/`end_at` overlap,
+`created_at < ?`, several `ORDER BY created_at`); a `COLLATE "C"` clause on each
+is 20 chances to forget one, and forgetting is silent.
+
+⚠️ **The load-bearing site is `internal/handler/notetaker.go`**, which writes
+`datetime('now')`'s space-separated shape *because* it sorts before any
+`T`-separated stamp, which is what makes a notetaker job due immediately. That is
+a dependency on byte ordering in production code, not a theoretical one.
+
+**Measured, and it corrects the framing of the open item.** The server this
+branch develops against is PostgreSQL 17.11 with `datcollate = en_US.utf8`
+(libc provider) — read from `pg_database`, because ⛔ `SHOW lc_collate` no longer
+exists (it stopped being a GUC in PostgreSQL 16 and errors with "unrecognized
+configuration parameter", so the obvious way to ask is a dead end). The two
+shapes the schema actually stores do **not** flip under it:
+
+| pair | en_US.utf8 | memcmp |
+|---|---|---|
+| `2026-01-01 20:00:00` vs `2026-01-01T10:00:00Z` | space first | space first |
+
+Nor under **any of the other 878 collations installed on the server** — scanned,
+not assumed. glibc ignores the space at the primary level but still sorts a digit
+before `T`, which happens to agree with memcmp. So a control built only on those
+two values would pass with or without the migration, which is exactly the
+vacuous green the packet warned about. The control therefore also carries RFC
+3339's lower-case `t`/`z` spelling (§5.6 permits it, so an importer or a
+third-party API can hand it to us), where the two orders really do differ:
+
+```
+plain: 2026-01-01 10:00:00 | 2026-01-01T10:00:00.000Z | 2026-01-01t10:00:00z | 2026-01-01T10:00:00Z
+C    : 2026-01-01 10:00:00 | 2026-01-01T10:00:00.000Z | 2026-01-01T10:00:00Z | 2026-01-01t10:00:00z
+```
+
+`internal/db/collation_test.go` holds it three ways. (a) An audit over
+`information_schema.columns` matching by NAME, so a timestamp column added by a
+later migration is caught without anyone remembering — `collation_name` is NULL
+for a default-collated column and `'C'` after an explicit `COLLATE`, so the
+assertion is exact. (b) The control above, which **skips naming the server's
+collation** if the default already orders byte-wise, rather than passing
+vacuously. (c) An ordering test on `jobs.run_at` through the worker's real claim
+predicate.
+
+Proved failable by dropping `jobs.run_at` from the migration:
+
+```
+collation_test.go:79: 1 of 54 timestamp columns are not COLLATE "C":
+    jobs.run_at = <database default>
+collation_test.go:242: ORDER BY run_at =
+    [… 2026-01-01t10:00:00z 2026-01-01T10:00:00Z …]
+    want byte order
+    [… 2026-01-01T10:00:00Z 2026-01-01t10:00:00z …]
+```
+
+### 2. `RETURNING position` — works unchanged on Postgres
+
+No `d.SQL` pair, no rewrite. The clause is the auto-position `INSERT` in
+`question_handler.go`, which computes the position inside the statement
+(`VALUES (…, (SELECT COALESCE(MAX(position)+1, 0) …)) RETURNING position`) so two
+concurrent creates cannot land on the same one.
+
+The new test goes through the HTTP handler on `dbtest.Open(t)`, so it follows the
+environment like everything else, and it asserts the value the handler **scanned
+from RETURNING** as well as the row left behind: a `RETURNING` that quietly
+produced a zero would still leave a correct row, so checking the table alone —
+which `TestCreateQuestion_autoPosition` already did — cannot see it. The
+explicit-position case is in the same test because the next auto position after a
+pinned 9 must be 10, which is what shows the subselect is evaluated by the engine
+rather than the sequence being an artifact of insertion order.
+
+Measured: **0, 1, 2, then 9 explicit, then 10 — identical on both engines.**
+
+### 3. `db.Open` deleted
+
+It returned a bare `*sql.DB` "for callers that have not moved to OpenDB yet".
+Nothing outside the package's own tests used it, and it could only ever do harm:
+statements through that handle are not rebound, so every `?` is a Postgres syntax
+error found at runtime, far from the call. It was also the shape most likely to
+be copied by whoever added the next call site.
+
+`/readyz` was the one production caller reaching into the exported embedded field
+(`db.SchemaReady(ctx, h.db.DB)`). `*db.DB` now carries `SchemaReady` and
+`AppliedVersion`, so the handler asks the handle. The package-level functions stay
+for the cases that genuinely hold a bare pool — goose's bookkeeping, the tests
+that open an unmigrated one — and `db_test.go` passes `database.DB` explicitly,
+which says at the call site that the bare pool is deliberate. `TestOpen_inMemory`
+became `TestOpenDB_inMemory` rather than staying named after something that no
+longer exists. No test asserts the symbol's absence: the build is the proof.
+
+### 4. Pool size is configurable
+
+`DB_MAX_OPEN_CONNS` / `DB_MAX_IDLE_CONNS`, defaults unchanged at 10/5, validated
+in `config.PoolFromEnv`: unset, unparsable or non-positive falls back to the
+default with a warning (matching `getBool`/`getDuration`, which also refuse to
+fail a boot over a typo in an optional knob), and idle above open is clamped —
+`database/sql` reduces it silently anyway, so the clamped pair is the honest
+description of what the pool will do. ⚠️ The clamp has to apply to the **default**
+idle as well: `DB_MAX_OPEN_CONNS=2` alone must give 2/2, not 2/5. A test pins it.
+
+`OpenDB` reads `PoolFromEnv` itself rather than taking the numbers as an
+argument, so all five entry points pick them up without five identical edits and
+without one of them silently keeping the defaults; `db.WithPool` is the override
+for a caller that must not follow the environment. `db` → `config` is not a
+cycle (`config` imports only the standard library).
+
+**SQLite stays pinned at 1/1 and ignores both the environment and `WithPool`.**
+That is the correctness guarantee, not a preference: the single connection is
+what serialises write transactions (it is why `booking.lockHosts` is a no-op
+there) and the pragmas are connection-scoped.
+`TestOpenDB_sqlitePoolIsNotConfigurable` asserts it with both knobs at 40/20, for
+the `:memory:` and file forms.
+
+The idle limit cannot be read back — `sql.DBStats` exposes the open limit only —
+so it is measured: four live transactions force four connections, and after
+committing them all the pool keeps **1** with `WithPool(4, 1)`.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, **28/28 packages ok on SQLite and
+28/28 on PostgreSQL**. Negative control, the same PostgreSQL command with the
+password changed to `wrong`: `internal/db` **fails** rather than skipping, with
+`failed SASL auth: FATAL: password authentication failed for user "postgres"
+(SQLSTATE 28P01)` — including `TestPostgres_idleLimitApplied`, the one new test
+whose assertions could conceivably have held without a server.

From 6e7f839c6aca958576e3784c60c0c71bebad2faf Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:14:20 -0400
Subject: [PATCH 19/51] server: let an operator name the proxies whose client
 IP is real

Rate limits key on the TCP peer, and that is correct for a directly reachable
instance and useless behind a fronting CDN, where every visitor arrives from the
same few addresses and shares one bucket. TRUSTED_PROXY_CIDRS opts in per network:
for a peer inside one of them the client IP comes from CF-Connecting-IP, else from
X-Forwarded-For, else the peer.

The default does not move, and cannot be moved by a header. A peer that is not in
the list has its headers ignored before they are read, so an instance that sets
nothing behaves exactly as it did.

Two details are the difference between this and a spoofable version:

The X-Forwarded-For walk goes RIGHT TO LEFT past trusted hops and returns the
first untrusted address, not the leftmost entry. The left of that header is
whatever the original client sent, and every well-behaved proxy prepends to it and
preserves it, so "leftmost" is a value the client picks. The rightmost non-trusted
hop is the last address one of our own proxies actually observed.

A hop that does not parse ends the walk and falls back to the peer instead of
being skipped. Skipping would let a client inject one malformed entry to push the
walk past the real hop onto a value it chose. The cost is that a proxy appending
"ip:port" reads as malformed and lands on the peer, which is the safe direction.

Resolution is a middleware rather than a package-level setting, computed once in
the outermost layer and carried in the request context: a mutable global would
leak between server instances in a test binary and would make "which requests are
affected" unanswerable from the wiring. remoteIP reads the context when it is
there, so the untrusted path is byte-for-byte the old function.

A CIDR that does not parse is logged and dropped rather than fatal, and the other
entries survive it. The consequence of dropping one is that that hop's headers are
not believed, which costs shared rate-limit buckets and never a trusted forgery.

audit/claims.yaml's rate-limit-keys-on-tcp-source-address said the headers are
"never read", which stops being true the moment this ships. Rewritten to state the
condition rather than left to rot into a false claim.
---
 CHANGELOG.md                         |  12 +++
 DEPLOY.md                            |   1 +
 audit/claims.yaml                    |  31 ++++--
 docs/ARCHITECTURE.md                 |  22 +++-
 internal/config/config.go            |   8 ++
 internal/server/middleware.go        | 154 +++++++++++++++++++++++++--
 internal/server/server.go            |  14 ++-
 internal/server/trustedproxy_test.go | 152 ++++++++++++++++++++++++++
 8 files changed, 371 insertions(+), 23 deletions(-)
 create mode 100644 internal/server/trustedproxy_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d40fe53..bd6192a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,18 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
 ## [Unreleased]
 
 ### Added
+- **`TRUSTED_PROXY_CIDRS`: per-IP rate limits that work behind a CDN.** Rate limits key
+  on the TCP peer, which is right for a directly-reachable instance and useless behind a
+  fronting CDN, where every visitor arrives from the same handful of addresses and shares
+  one bucket. List the networks you control and the client IP is taken from
+  `CF-Connecting-IP`, or from `X-Forwarded-For` walked right to left past your own hops.
+
+  Nothing changes if you do not set it: a header from a peer you have not listed is still
+  not read at all, because it is a value the client chose. Within the header the *leftmost*
+  entry is likewise client-chosen, so the walk stops at the rightmost address one of your
+  proxies actually observed, and a malformed hop ends the walk on the peer rather than
+  being stepped over.
+
 - **Sign out everywhere.** `POST /v1/auth/sessions/revoke-all` ends every session you
   have except the one you asked from, so losing a laptop no longer means waiting out a
   30-day cookie. Pass `{"user_id": "..."}` and an admin can do the same for someone
diff --git a/DEPLOY.md b/DEPLOY.md
index a59f8c1..871cf7c 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -36,6 +36,7 @@ This guide covers a generic Docker deploy and a step-by-step **Railway** deploy
 | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | no | — | Google sign-in + calendar. Can also be set in Settings → Google OAuth. |
 | `LITESTREAM_REPLICA_URL` | recommended | — | Enables continuous SQLite backup (see §6). |
 | `COOKIE_SECURE` | no | https→true | Override cookie Secure flag; defaults from `BASE_URL` scheme. |
+| `TRUSTED_PROXY_CIDRS` | no | — | Comma-separated CIDRs (a bare address = one host) whose `CF-Connecting-IP` / `X-Forwarded-For` are believed when keying per-IP rate limits, e.g. `10.0.0.0/8`. Unset ⇒ those headers are ignored and the limit keys on the TCP peer, so behind a fronting CDN every visitor shares one bucket. **Only list networks you control**: anything in the list can name any client IP it likes. |
 | `LOG_LEVEL` | no | `info` | `debug`/`info`/`warn`/`error`. |
 
 ¹ Email is optional to boot, but bookings won't send confirmations until SMTP is configured (env **or** the admin UI). Precedence is **env var > DB setting > default**.
diff --git a/audit/claims.yaml b/audit/claims.yaml
index 28bca98..14c4647 100644
--- a/audit/claims.yaml
+++ b/audit/claims.yaml
@@ -276,25 +276,36 @@ claims:
 
   - id: rate-limit-keys-on-tcp-source-address
     claim: >
-      Per-IP rate limiting (internal/server/middleware.go's RateLimit) keys
-      strictly on the TCP-level remote address of the connection, never on client-
-      supplied X-Forwarded-For/X-Real-IP headers — a client cannot spoof those
-      headers to evade or split its rate-limit bucket.
+      Per-IP rate limiting (internal/server/middleware.go's RateLimit) keys on the
+      TCP-level remote address of the connection, and never on client-supplied
+      X-Forwarded-For/X-Real-IP/CF-Connecting-IP headers unless the peer that sent
+      them is inside an operator-configured TRUSTED_PROXY_CIDRS range — so a client
+      cannot spoof those headers to evade or split its rate-limit bucket.
     verify:
       - "internal/server/middleware.go's remoteIP — net.SplitHostPort(r.RemoteAddr)
-         only; the proxy headers are never read."
+         via peerIP, unless TrustClientIP has resolved a client IP into the request
+         context, which it only does for a peer matching a trusted CIDR."
+      - "internal/server/middleware.go's resolveClientIP — returns the peer outright
+         for an untrusted peer, before any header is read."
       - "internal/server/ratelimit_test.go's TestRemoteIP_* — assert X-Forwarded-For
          and X-Real-IP are ignored even when RemoteAddr is loopback."
+      - "internal/server/trustedproxy_test.go — asserts an untrusted peer's spoofed
+         headers are ignored, that the X-Forwarded-For walk goes right-to-left past
+         trusted hops (never the client-seeded leftmost entry), and that a malformed
+         header falls back to the peer."
     status: verified
     caveat: >
       Recorded here because a prior Layer 2 audit pass flagged this as trusting
       spoofable proxy headers — it doesn't; the flagged behavior traced back to a
       stale doc comment describing the opposite of what the code does (fixed
-      alongside this entry). Correct behavior does require the deployment's
-      reverse proxy to connect to Calnode directly (or over a trusted private
-      network) — see the deployment docs for reverse-proxy requirements (forward
-      the original Host header, connect over a trusted path, strip client-supplied
-      proxy headers at the edge).
+      alongside this entry). TRUSTED_PROXY_CIDRS is empty by default, so an
+      unconfigured instance behaves exactly as this claim originally described.
+      Anything an operator does list can name any client IP it likes — that is what
+      trusting a proxy means — so the list must hold only networks they control.
+      Correct behavior otherwise requires the deployment's reverse proxy to connect
+      to Calnode directly (or over a trusted private network) — see the deployment
+      docs for reverse-proxy requirements (forward the original Host header, connect
+      over a trusted path, strip client-supplied proxy headers at the edge).
 
   - id: caldav-connect-self-service-no-admin-gate
     claim: >
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index b7c0e2f..b9ccb10 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -771,10 +771,24 @@ as the desired state:
   **original `Host` header**. The CSRF same-origin check (§6) compares the request's
   `Origin`/`Referer` against `Host`, so a proxy that rewrites Host would *false-block
   admin writes* (403). Fly and Railway preserve Host by default; a hand-rolled nginx
-  needs `proxy_set_header Host $host;`. Related: per-IP rate limits (§8) key on the
-  **TCP remote address** (proxy headers like `X-Forwarded-For` are intentionally
-  ignored as forgeable), so behind a shared proxy the limit keys on the proxy's
-  connection — fine for per-instance Fly/Railway, worth knowing for a fronting proxy.
+  needs `proxy_set_header Host $host;`.
+- **Per-IP rate limits (§8) key on the TCP remote address by default**, and
+  `X-Forwarded-For` / `X-Real-IP` / `CF-Connecting-IP` are not read at all. That is not
+  an oversight: those headers are client-chosen values, so believing them unconditionally
+  would let anyone split their own rate-limit bucket by sending a different one each
+  request. Behind a shared proxy the limit therefore keys on the proxy's connection —
+  fine for a per-instance Fly/Railway deploy, worth knowing for a fronting CDN.
+  **`TRUSTED_PROXY_CIDRS`** (comma-separated CIDRs, a bare address meaning one host)
+  opts in per network: for a peer inside one of those ranges, `TrustClientIP`
+  (`internal/server/middleware.go`) resolves the client IP from `CF-Connecting-IP` if
+  present, else by walking `X-Forwarded-For` **right to left past trusted hops** and
+  taking the first untrusted address, else the peer. ⛔ Not the leftmost entry: the left
+  of that header is whatever the original client sent, and every well-behaved proxy
+  preserves it. A hop that does not parse ends the walk and falls back to the peer rather
+  than being skipped, so one malformed entry cannot push the walk onto a value the client
+  chose. Headers from an **untrusted** peer are never read, which is what keeps the
+  default un-weakenable by a header. Resolution happens once, in the outermost
+  middleware, and is carried in the request context.
 
 ---
 
diff --git a/internal/config/config.go b/internal/config/config.go
index 6f4bcca..d744cb9 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -59,6 +59,13 @@ type Config struct {
 	// the public endpoints are rate-limited regardless. Comma-separated.
 	EmbedAllowedOrigins []string
 
+	// TrustedProxyCIDRs lists the networks whose forwarded headers are believed when
+	// resolving the client IP for per-IP rate limiting. Empty (the default) ⇒ the limit
+	// keys on the TCP peer and CF-Connecting-IP / X-Forwarded-For are ignored entirely,
+	// because a header from an unvetted peer is a client-chosen value. Comma-separated
+	// CIDRs; a bare address is taken as a single host.
+	TrustedProxyCIDRs []string
+
 	// DemoMode turns this instance into a public, self-resetting demo: seeds sample
 	// data on every boot (there's no persistent volume, so every boot is a fresh DB),
 	// disables calendar/Zoom connect, serves a disallow-all robots.txt, and exposes
@@ -96,6 +103,7 @@ func Load() *Config {
 		ZoomClientSecret: getEnv("ZOOM_CLIENT_SECRET", ""),
 
 		EmbedAllowedOrigins: splitCSV(getEnv("EMBED_ALLOWED_ORIGINS", "")),
+		TrustedProxyCIDRs:   splitCSV(getEnv("TRUSTED_PROXY_CIDRS", "")),
 	}
 
 	cfg.EncryptionKey = os.Getenv("CALNODE_ENCRYPTION_KEY")
diff --git a/internal/server/middleware.go b/internal/server/middleware.go
index 363b10e..eecc8b3 100644
--- a/internal/server/middleware.go
+++ b/internal/server/middleware.go
@@ -18,6 +18,10 @@ type contextKey string
 
 const requestIDKey contextKey = "request_id"
 
+// clientIPKey carries the client IP resolved by TrustClientIP. Absent unless
+// TRUSTED_PROXY_CIDRS is configured, in which case remoteIP falls back to the peer.
+const clientIPKey contextKey = "client_ip"
+
 func RequestID(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		id := r.Header.Get("X-Request-Id")
@@ -236,18 +240,152 @@ func (rl *rateLimiter) cleanup() {
 	}
 }
 
-// remoteIP returns the TCP-level remote address, stripped of its port.
-// X-Real-IP and X-Forwarded-For are intentionally ignored: without a
-// configured trusted-proxy allowlist, those headers can be forged by any
-// client and would bypass the rate limit entirely. Operators behind a reverse
-// proxy should strip proxy headers at the proxy level and rely on the TCP
-// address the proxy connects with. See audit/claims.yaml's
-// rate-limit-keys-on-tcp-source-address claim, recorded specifically because a
-// prior Layer 2 audit pass mistook this deliberate behavior for a spoofable gap.
+// remoteIP returns the IP a per-IP limit keys on.
+//
+// By default that is the TCP-level remote address, stripped of its port, and the
+// forwarded headers are ignored: without a configured trusted-proxy allowlist those
+// headers can be forged by any client and would bypass the rate limit entirely.
+// Operators behind a reverse proxy should strip proxy headers at the proxy and rely on
+// the TCP address the proxy connects with. See audit/claims.yaml's
+// rate-limit-keys-on-tcp-source-address claim, recorded specifically because a prior
+// Layer 2 audit pass mistook this deliberate behavior for a spoofable gap.
+//
+// When TRUSTED_PROXY_CIDRS is set, TrustClientIP has already resolved the client IP for
+// this request and left it in the context — see resolveClientIP for what that means and
+// what it deliberately does not do. This function reads that value when it is there, so
+// the untrusted-peer path stays byte-for-byte the old behaviour.
 func remoteIP(r *http.Request) string {
+	if ip, ok := r.Context().Value(clientIPKey).(string); ok && ip != "" {
+		return ip
+	}
+	return peerIP(r)
+}
+
+// peerIP returns the TCP-level remote address, stripped of its port. This is the only
+// value in a request that a client cannot choose.
+func peerIP(r *http.Request) string {
 	host, _, err := net.SplitHostPort(r.RemoteAddr)
 	if err != nil {
 		return r.RemoteAddr
 	}
 	return host
 }
+
+// ParseTrustedProxies parses TRUSTED_PROXY_CIDRS entries. A bare address is accepted and
+// treated as a single-host range (/32 or /128), because "10.0.0.7" is what an operator
+// naming one proxy will write.
+//
+// Every parseable entry is returned even when others fail, and the error names the ones
+// that did not: one typo should cost that hop's trust, not the whole list's. The caller
+// is expected to log the error — an unparsed entry means that proxy's headers are NOT
+// believed, which degrades to per-proxy rate limiting rather than to trusting a forgery.
+func ParseTrustedProxies(entries []string) ([]*net.IPNet, error) {
+	var nets []*net.IPNet
+	var bad []string
+	for _, e := range entries {
+		e = strings.TrimSpace(e)
+		if e == "" {
+			continue
+		}
+		if _, n, err := net.ParseCIDR(e); err == nil {
+			nets = append(nets, n)
+			continue
+		}
+		if ip := net.ParseIP(e); ip != nil {
+			bits := 32
+			if ip.To4() == nil {
+				bits = 128
+			}
+			nets = append(nets, &net.IPNet{IP: ip, Mask: net.CIDRMask(bits, bits)})
+			continue
+		}
+		bad = append(bad, e)
+	}
+	if len(bad) > 0 {
+		return nets, fmt.Errorf("not a CIDR or IP address: %s", strings.Join(bad, ", "))
+	}
+	return nets, nil
+}
+
+// TrustClientIP returns middleware that resolves the client IP once per request and
+// stores it in the request context for remoteIP to read. With no trusted proxies it is a
+// pass-through, so an instance that has not configured any is unchanged.
+//
+// It is middleware rather than a package-level setting because the trust list belongs to
+// one server instance: a mutable global would leak between instances in a test binary
+// and would make "which requests are affected" unanswerable from the wiring.
+func TrustClientIP(trusted []*net.IPNet) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		if len(trusted) == 0 {
+			return next
+		}
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			ctx := context.WithValue(r.Context(), clientIPKey, resolveClientIP(r, trusted))
+			next.ServeHTTP(w, r.WithContext(ctx))
+		})
+	}
+}
+
+// resolveClientIP applies the forwarded headers, but only for a peer inside a trusted
+// CIDR. A header from an untrusted peer is never read at all — that is the whole point,
+// and it is why the default (no trusted proxies) cannot be weakened by a header.
+//
+// Preference order for a trusted peer:
+//
+//  1. CF-Connecting-IP, which a single fronting CDN sets to one value and does not append
+//     to, so there is no chain to reason about.
+//  2. X-Forwarded-For, walked RIGHT TO LEFT past trusted hops, returning the first
+//     untrusted address. ⛔ Not the leftmost entry: the left of that header is whatever
+//     the original client sent, so a client that pre-seeds "X-Forwarded-For: 1.2.3.4"
+//     gets it prepended and preserved by every well-behaved proxy. The rightmost
+//     non-trusted hop is the last address a trusted proxy actually observed, which is the
+//     only one in the header that anything vouched for.
+//  3. The peer, whenever the headers are absent or unusable.
+//
+// A hop that does not parse ends the walk and falls back to the peer rather than being
+// skipped. Skipping it would let a client inject one malformed entry to push the walk
+// past the real hop and onto a value it chose. Note this also means a proxy that appends
+// "ip:port" (rather than a bare address) reads as malformed and lands on the peer, which
+// is the safe direction to be wrong in.
+func resolveClientIP(r *http.Request, trusted []*net.IPNet) string {
+	peer := peerIP(r)
+	if !ipInAny(peer, trusted) {
+		return peer
+	}
+
+	if cf := strings.TrimSpace(r.Header.Get("CF-Connecting-IP")); cf != "" {
+		if ip := net.ParseIP(cf); ip != nil {
+			return ip.String()
+		}
+	}
+
+	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
+		hops := strings.Split(xff, ",")
+		for i := len(hops) - 1; i >= 0; i-- {
+			ip := net.ParseIP(strings.TrimSpace(hops[i]))
+			if ip == nil {
+				break
+			}
+			if ipInAny(ip.String(), trusted) {
+				continue // a trusted hop of our own; keep walking left
+			}
+			return ip.String()
+		}
+	}
+
+	return peer
+}
+
+// ipInAny reports whether ip (a textual address) falls inside any of nets.
+func ipInAny(ip string, nets []*net.IPNet) bool {
+	parsed := net.ParseIP(ip)
+	if parsed == nil {
+		return false
+	}
+	for _, n := range nets {
+		if n.Contains(parsed) {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index 4a804d1..14a3ec1 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -547,7 +547,19 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	// permanently if a marketing landing page is ever added here.
 	mux.Handle("GET /{$}", http.RedirectHandler("/admin/", http.StatusFound))
 
-	return RequestID(Logging(logger, SameOriginCheck(mux))), drain
+	// Trusted-proxy resolution wraps everything, so the per-IP limiters and anything else
+	// asking for the client IP see one answer computed once. A bad CIDR is logged and
+	// dropped rather than fatal: the consequence is that that hop's headers are not
+	// believed, which costs shared rate-limit buckets, never a trusted forgery.
+	trustedProxies, err := ParseTrustedProxies(cfg.TrustedProxyCIDRs)
+	if err != nil {
+		logger.Error("TRUSTED_PROXY_CIDRS: ignoring unparseable entries", "error", err)
+	}
+	if len(trustedProxies) > 0 {
+		logger.Info("trusting forwarded headers from proxies", "cidrs", cfg.TrustedProxyCIDRs)
+	}
+
+	return TrustClientIP(trustedProxies)(RequestID(Logging(logger, SameOriginCheck(mux)))), drain
 }
 
 // seedSMTPToDB writes env-var SMTP settings into the DB on first boot so they
diff --git a/internal/server/trustedproxy_test.go b/internal/server/trustedproxy_test.go
new file mode 100644
index 0000000..31d73e0
--- /dev/null
+++ b/internal/server/trustedproxy_test.go
@@ -0,0 +1,152 @@
+package server
+
+import (
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// serveThroughTrust runs one request through TrustClientIP and reports what remoteIP
+// resolved to inside the handler — the value a rate limiter would key on.
+func serveThroughTrust(t *testing.T, cidrs []string, peer string, headers map[string]string) string {
+	t.Helper()
+	trusted, err := ParseTrustedProxies(cidrs)
+	if err != nil {
+		t.Fatalf("ParseTrustedProxies(%v): %v", cidrs, err)
+	}
+	var got string
+	h := TrustClientIP(trusted)(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+		got = remoteIP(r)
+	}))
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.RemoteAddr = peer
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	h.ServeHTTP(httptest.NewRecorder(), req)
+	return got
+}
+
+// The default. An untrusted peer's forwarded headers are not read at all, so the spoof
+// keys on the connection the spoofer actually made.
+func TestTrustClientIP_untrustedPeerIgnoresSpoofedHeaders(t *testing.T) {
+	got := serveThroughTrust(t, []string{"10.0.0.0/8"}, "203.0.113.9:1234", map[string]string{
+		"X-Forwarded-For":  "198.51.100.1",
+		"CF-Connecting-IP": "198.51.100.2",
+		"X-Real-IP":        "198.51.100.3",
+	})
+	if got != "203.0.113.9" {
+		t.Errorf("client IP = %q; want the peer 203.0.113.9", got)
+	}
+}
+
+// With no trusted proxies configured at all, TrustClientIP is a pass-through and the
+// behaviour is exactly what it was before the setting existed.
+func TestTrustClientIP_noTrustedProxiesIsUnchanged(t *testing.T) {
+	got := serveThroughTrust(t, nil, "10.0.0.5:1234", map[string]string{
+		"X-Forwarded-For": "198.51.100.1",
+	})
+	if got != "10.0.0.5" {
+		t.Errorf("client IP = %q; want the peer 10.0.0.5", got)
+	}
+}
+
+func TestTrustClientIP_trustedPeerUsesCFConnectingIP(t *testing.T) {
+	got := serveThroughTrust(t, []string{"10.0.0.0/8"}, "10.0.0.5:1234", map[string]string{
+		"CF-Connecting-IP": "198.51.100.7",
+		// CF-Connecting-IP wins over the chain: one fronting CDN sets it to one value.
+		"X-Forwarded-For": "198.51.100.99, 10.0.0.5",
+	})
+	if got != "198.51.100.7" {
+		t.Errorf("client IP = %q; want 198.51.100.7", got)
+	}
+}
+
+// Two of our own hops appended themselves; the walk goes right to left past both and
+// stops at the address the outermost trusted proxy actually saw.
+func TestTrustClientIP_walksTrustedChainRightToLeft(t *testing.T) {
+	got := serveThroughTrust(t, []string{"10.0.0.0/8", "192.168.0.0/16"}, "10.0.0.5:1234",
+		map[string]string{"X-Forwarded-For": "198.51.100.7, 192.168.1.1, 10.0.0.9"})
+	if got != "198.51.100.7" {
+		t.Errorf("client IP = %q; want 198.51.100.7", got)
+	}
+}
+
+// The leftmost entry is client-supplied. A client that pre-seeds the header must not be
+// able to choose its own key by putting a value to the left of the real one.
+func TestTrustClientIP_ignoresEntriesLeftOfTheRealHop(t *testing.T) {
+	got := serveThroughTrust(t, []string{"10.0.0.0/8"}, "10.0.0.5:1234",
+		map[string]string{"X-Forwarded-For": "1.2.3.4, 198.51.100.7, 10.0.0.9"})
+	if got != "198.51.100.7" {
+		t.Errorf("client IP = %q; want 198.51.100.7 (not the client-seeded 1.2.3.4)", got)
+	}
+}
+
+func TestTrustClientIP_malformedHeaderFallsBackToPeer(t *testing.T) {
+	cases := map[string]string{
+		"garbage":            "not-an-ip",
+		"empty entries":      " , ,",
+		"address with port":  "198.51.100.7:443",
+		"malformed left hop": "not-an-ip, 10.0.0.9",
+	}
+	for name, xff := range cases {
+		t.Run(name, func(t *testing.T) {
+			got := serveThroughTrust(t, []string{"10.0.0.0/8"}, "10.0.0.5:1234",
+				map[string]string{"X-Forwarded-For": xff})
+			if got != "10.0.0.5" {
+				t.Errorf("client IP = %q; want the peer 10.0.0.5", got)
+			}
+		})
+	}
+}
+
+// A chain of nothing but our own proxies has no client address in it. The peer is the
+// only honest answer left.
+func TestTrustClientIP_allHopsTrustedFallsBackToPeer(t *testing.T) {
+	got := serveThroughTrust(t, []string{"10.0.0.0/8"}, "10.0.0.5:1234",
+		map[string]string{"X-Forwarded-For": "10.0.0.7, 10.0.0.9"})
+	if got != "10.0.0.5" {
+		t.Errorf("client IP = %q; want the peer 10.0.0.5", got)
+	}
+}
+
+func TestTrustClientIP_ipv6(t *testing.T) {
+	// The proxies sit in 2001:db8:0::/48; the client is one prefix over, so the walk
+	// skips the trusted hop and stops on it.
+	got := serveThroughTrust(t, []string{"2001:db8:0::/48"}, "[2001:db8::1]:1234",
+		map[string]string{"X-Forwarded-For": "2001:db8:1::5, 2001:db8::9"})
+	if got != "2001:db8:1::5" {
+		t.Errorf("client IP = %q; want 2001:db8:1::5", got)
+	}
+}
+
+func TestParseTrustedProxies(t *testing.T) {
+	// A bare address is what an operator naming one proxy writes.
+	nets, err := ParseTrustedProxies([]string{"10.0.0.7", "192.168.0.0/16", "2001:db8::1"})
+	if err != nil {
+		t.Fatalf("err = %v; want nil", err)
+	}
+	if len(nets) != 3 {
+		t.Fatalf("parsed %d entries; want 3", len(nets))
+	}
+	if !nets[0].Contains(net.ParseIP("10.0.0.7")) || nets[0].Contains(net.ParseIP("10.0.0.8")) {
+		t.Errorf("bare IPv4 %v should be exactly one host", nets[0])
+	}
+	if !nets[2].Contains(net.ParseIP("2001:db8::1")) || nets[2].Contains(net.ParseIP("2001:db8::2")) {
+		t.Errorf("bare IPv6 %v should be exactly one host", nets[2])
+	}
+}
+
+// One typo costs that hop's trust, not the whole list's — and it is reported rather than
+// swallowed, because an operator who thinks a proxy is trusted and is wrong gets shared
+// rate-limit buckets with no explanation.
+func TestParseTrustedProxies_reportsBadEntriesAndKeepsTheRest(t *testing.T) {
+	nets, err := ParseTrustedProxies([]string{"10.0.0.0/8", "10.0.0.0/99", "nonsense"})
+	if err == nil {
+		t.Fatal("err = nil; want the bad entries named")
+	}
+	if len(nets) != 1 {
+		t.Errorf("parsed %d entries; want the 1 good one kept", len(nets))
+	}
+}

From ee6eefb5017936b1e7eab275c68d6de6d0d07dd2 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:19:37 -0400
Subject: [PATCH 20/51] server: let an operator frame the admin console, and
 nothing else

FRAME_ANCESTORS (space-separated, so it reads the same in the env var as in the
header) puts Content-Security-Policy: frame-ancestors <list> on the handler under
/admin/. Wanted by anyone embedding the console in their own tooling; the
alternative today is a reverse proxy rewriting headers.

The middleware wraps frontend.Handler() and nothing else. The public booking pages
set frame-ancestors 'none' and X-Frame-Options: DENY in their own handlers and
must keep doing so unconditionally: they are unauthenticated pages that collect
names, emails and card details, and clickjacking one of those is worth more to an
attacker than framing a console nobody can reach without a session.

No X-Frame-Options is sent beside the CSP. That header has no allow-list form
(ALLOW-FROM was implemented by one browser and is dead), so the only value it
could carry here is SAMEORIGIN, which the browsers that read it apply INSTEAD of
honouring frame-ancestors, breaking the embedding this exists to enable.

Unset changes nothing, and what "nothing" is here is worth writing down: /admin/
sends no frame header at all today, so the SPA is framable by default. This does
not add a default deny, because an opt-in setting must not smuggle in a behaviour
change, and TestAdminSPA_sendsNoFrameHeadersWhenUnset pins the current answer so
that the next person to change it does so on purpose.

An entry that is not https://host[:port] or 'self' fails config.Validate and the
process exits rather than starting. A browser drops a source list it cannot parse,
so a typo would leave /admin/ MORE embeddable than the setting unset, with nothing
in the response to say so. Wildcards are refused too even though CSP allows them:
https://*.example.com trusts every host that name ever points at, including one
taken over later, and an operator who needs two hosts can name two hosts.
---
 CHANGELOG.md                           | 13 +++++
 DEPLOY.md                              |  1 +
 cmd/calnode/main.go                    |  7 +++
 docs/ARCHITECTURE.md                   | 18 +++++++
 internal/config/config.go              | 72 +++++++++++++++++++++++++
 internal/config/config_test.go         | 74 ++++++++++++++++++++++++++
 internal/server/frameancestors_test.go | 59 ++++++++++++++++++++
 internal/server/middleware.go          | 35 ++++++++++++
 internal/server/server.go              |  5 +-
 9 files changed, 283 insertions(+), 1 deletion(-)
 create mode 100644 internal/server/frameancestors_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd6192a..652fa3f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,19 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
 ## [Unreleased]
 
 ### Added
+- **`FRAME_ANCESTORS`: embed the admin UI in your own console.** Space-separated origins
+  (`https://console.example.com 'self'`); when set, `/admin/` sends
+  `Content-Security-Policy: frame-ancestors <list>`. The public booking pages are
+  untouched and still deny framing outright — this is about the console, not the pages
+  that take card details.
+
+  Two deliberate refusals. An entry that is not `https://host[:port]` or `'self'` stops
+  the app booting rather than being ignored, because a browser drops a source list it
+  cannot parse, which would leave the admin UI *more* embeddable than the setting being
+  unset. And no `X-Frame-Options` is sent beside it: that header has no allow-list form,
+  so the only value it could carry is `SAMEORIGIN`, which browsers honour instead of the
+  CSP and would break the embedding this exists for.
+
 - **`TRUSTED_PROXY_CIDRS`: per-IP rate limits that work behind a CDN.** Rate limits key
   on the TCP peer, which is right for a directly-reachable instance and useless behind a
   fronting CDN, where every visitor arrives from the same handful of addresses and shares
diff --git a/DEPLOY.md b/DEPLOY.md
index 871cf7c..e56b2d8 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -37,6 +37,7 @@ This guide covers a generic Docker deploy and a step-by-step **Railway** deploy
 | `LITESTREAM_REPLICA_URL` | recommended | — | Enables continuous SQLite backup (see §6). |
 | `COOKIE_SECURE` | no | https→true | Override cookie Secure flag; defaults from `BASE_URL` scheme. |
 | `TRUSTED_PROXY_CIDRS` | no | — | Comma-separated CIDRs (a bare address = one host) whose `CF-Connecting-IP` / `X-Forwarded-For` are believed when keying per-IP rate limits, e.g. `10.0.0.0/8`. Unset ⇒ those headers are ignored and the limit keys on the TCP peer, so behind a fronting CDN every visitor shares one bucket. **Only list networks you control**: anything in the list can name any client IP it likes. |
+| `FRAME_ANCESTORS` | no | — | **Space**-separated origins allowed to embed the **admin UI** in a frame, e.g. `https://console.example.com 'self'`. Each entry must be `https://host[:port]` or `'self'` — anything else and **the app refuses to start**, because browsers drop a policy they cannot parse. Does not affect the public booking pages, which always deny framing. |
 | `LOG_LEVEL` | no | `info` | `debug`/`info`/`warn`/`error`. |
 
 ¹ Email is optional to boot, but bookings won't send confirmations until SMTP is configured (env **or** the admin UI). Precedence is **env var > DB setting > default**.
diff --git a/cmd/calnode/main.go b/cmd/calnode/main.go
index 7f94db3..390ffcd 100644
--- a/cmd/calnode/main.go
+++ b/cmd/calnode/main.go
@@ -53,6 +53,13 @@ func main() {
 	bi := buildinfo.Get()
 	logger.Info("starting calnode", "version", bi.Version, "commit", bi.Commit, "build_time", bi.BuildTime, "dirty", bi.Dirty)
 
+	// Config whose wrong value is worse than its absence is checked here rather than
+	// tolerated at request time — see (*config.Config).Validate.
+	if err := cfg.Validate(); err != nil {
+		logger.Error("invalid configuration", "error", err)
+		os.Exit(1)
+	}
+
 	if cfg.GoogleClientID != "" {
 		slog.Info("Google OAuth configured", "client_id_prefix", cfg.GoogleClientID[:20])
 	} else {
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index b9ccb10..e7c10df 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -812,6 +812,24 @@ as the desired state:
    strict default and relaxes only when head code-injection is configured (broad
    `https:` or the operator's `tracking_csp_allow`). Don't re-hardcode the CSP on the
    `book`/`manage` handlers — route it through `publicCSP`.
+9. **`FRAME_ANCESTORS` is the admin SPA's only, and it must stay that way.** Set it
+   (space-separated `https://host[:port]` / `'self'`) and the handler under `/admin/`
+   sends `Content-Security-Policy: frame-ancestors <list>` so an operator can embed the
+   console in their own tooling. `internal/server`'s `FrameAncestors` middleware wraps
+   `frontend.Handler()` and nothing else: the public booking pages keep
+   `frame-ancestors 'none'` + `X-Frame-Options: DENY` unconditionally, because they are
+   unauthenticated pages collecting names, emails and card details and clickjacking one
+   is worth more than framing a console nobody reaches without a session.
+   ⚠️ **Unset sends no frame header at all, which is what `/admin/` has always sent** —
+   the SPA is framable by default. This setting deliberately does *not* add a default
+   deny, since an opt-in flag must not smuggle in a behaviour change;
+   `TestAdminSPA_sendsNoFrameHeadersWhenUnset` pins the current answer so changing it is
+   a decision. No `X-Frame-Options` is sent beside the CSP either: that header has no
+   allow-list form (`ALLOW-FROM` is dead), so the only value it could carry is
+   `SAMEORIGIN`, which browsers apply *instead of* the CSP and would break the embedding.
+   An entry that isn't `https://host[:port]` or `'self'` fails `config.Validate()` and the
+   process **refuses to start** — a browser drops a source list it cannot parse, so a
+   typo would otherwise leave `/admin/` more embeddable than with the setting unset.
 
 ---
 
diff --git a/internal/config/config.go b/internal/config/config.go
index d744cb9..c248358 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -1,7 +1,9 @@
 package config
 
 import (
+	"fmt"
 	"log/slog"
+	"net/url"
 	"os"
 	"strconv"
 	"strings"
@@ -66,6 +68,19 @@ type Config struct {
 	// CIDRs; a bare address is taken as a single host.
 	TrustedProxyCIDRs []string
 
+	// FrameAncestors lists the origins allowed to embed the admin SPA in a frame, as a
+	// Content-Security-Policy frame-ancestors source list. Space-separated, matching the
+	// CSP syntax it becomes. Empty (the default) ⇒ nothing is sent and /admin/ behaves
+	// exactly as it did. Each entry must be `https://host[:port]` or `'self'`; anything
+	// else fails Validate and the process refuses to start, because a directive the
+	// browser cannot parse is a directive that silently allows everything.
+	//
+	// Only the admin SPA is affected. The public booking pages keep their
+	// `frame-ancestors 'none'` + `X-Frame-Options: DENY` unconditionally — those are
+	// unauthenticated pages that take payment details, and no operator convenience is
+	// worth making them embeddable.
+	FrameAncestors []string
+
 	// DemoMode turns this instance into a public, self-resetting demo: seeds sample
 	// data on every boot (there's no persistent volume, so every boot is a fresh DB),
 	// disables calendar/Zoom connect, serves a disallow-all robots.txt, and exposes
@@ -104,6 +119,9 @@ func Load() *Config {
 
 		EmbedAllowedOrigins: splitCSV(getEnv("EMBED_ALLOWED_ORIGINS", "")),
 		TrustedProxyCIDRs:   splitCSV(getEnv("TRUSTED_PROXY_CIDRS", "")),
+		// Space-separated, not comma: the value goes into a CSP source list verbatim, so
+		// it reads the same in the env var as it does in the header.
+		FrameAncestors: strings.Fields(getEnv("FRAME_ANCESTORS", "")),
 	}
 
 	cfg.EncryptionKey = os.Getenv("CALNODE_ENCRYPTION_KEY")
@@ -120,6 +138,60 @@ func Load() *Config {
 	return cfg
 }
 
+// Validate reports the configuration errors an operator has to fix before the process
+// can safely serve traffic. Called from main after Load; a non-nil error is fatal.
+//
+// It holds the settings whose wrong value is worse than their absence. A malformed CSP
+// directive is the example: browsers drop a source list they cannot parse, so the admin
+// UI would end up MORE embeddable than with the setting unset, and nothing in the
+// response would say so.
+func (c *Config) Validate() error {
+	for _, origin := range c.FrameAncestors {
+		if err := validFrameAncestor(origin); err != nil {
+			return fmt.Errorf("FRAME_ANCESTORS: %w", err)
+		}
+	}
+	return nil
+}
+
+// validFrameAncestor accepts 'self' or an https origin with no path, credentials, query
+// or fragment.
+//
+// Wildcards are deliberately refused even though CSP allows them. `https://*.example.com`
+// trusts every host any subdomain of that name ever points at, including one taken over
+// later; an operator who needs two hosts can name two hosts. Plain http is refused for
+// the same reason the admin session cookie is Secure — the framing page would be able to
+// read nothing, but its own compromise becomes a foothold.
+func validFrameAncestor(origin string) error {
+	if origin == "'self'" {
+		return nil
+	}
+	if strings.HasPrefix(origin, "'") {
+		// 'none', 'unsafe-inline' and friends are keywords this setting has no use for:
+		// 'none' is not "unset" (see FrameAncestors) and the rest are not source
+		// expressions at all. Refusing them keeps the accepted grammar one line long.
+		return fmt.Errorf("%q is not a supported keyword; use 'self' or an https:// origin", origin)
+	}
+	u, err := url.Parse(origin)
+	switch {
+	case err != nil:
+		return fmt.Errorf("%q is not a URL: %w", origin, err)
+	case u.Scheme != "https":
+		return fmt.Errorf("%q must use https://", origin)
+	case u.Host == "":
+		return fmt.Errorf("%q has no host", origin)
+	case strings.Contains(u.Host, "*"):
+		return fmt.Errorf("%q must name one host, not a wildcard", origin)
+	case u.User != nil:
+		return fmt.Errorf("%q must not carry credentials", origin)
+	case u.Path != "" && u.Path != "/":
+		return fmt.Errorf("%q must be an origin, with no path", origin)
+	case u.RawQuery != "" || u.Fragment != "":
+		return fmt.Errorf("%q must be an origin, with no query or fragment", origin)
+	}
+	return nil
+}
+
 func parseLogLevel(s string) slog.Level {
 	switch s {
 	case "debug":
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index a3a9962..82be6bc 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -121,3 +121,77 @@ func TestLoad_demoResetIntervalInvalidFallsBackToDefault(t *testing.T) {
 		t.Errorf("DemoResetInterval = %v; want 30m default on invalid input", cfg.DemoResetInterval)
 	}
 }
+
+// ---------------------------------------------------------------------------
+// FRAME_ANCESTORS
+// ---------------------------------------------------------------------------
+
+func TestLoad_frameAncestorsIsSpaceSeparated(t *testing.T) {
+	t.Setenv("FRAME_ANCESTORS", "  https://console.example.test 'self'  ")
+
+	cfg := config.Load()
+
+	if len(cfg.FrameAncestors) != 2 {
+		t.Fatalf("FrameAncestors = %#v; want 2 entries", cfg.FrameAncestors)
+	}
+	if cfg.FrameAncestors[0] != "https://console.example.test" || cfg.FrameAncestors[1] != "'self'" {
+		t.Errorf("FrameAncestors = %#v; want the two sources unchanged", cfg.FrameAncestors)
+	}
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("Validate() = %v; want nil", err)
+	}
+}
+
+func TestLoad_frameAncestorsDefaultsToEmpty(t *testing.T) {
+	os.Unsetenv("FRAME_ANCESTORS")
+
+	cfg := config.Load()
+
+	if len(cfg.FrameAncestors) != 0 {
+		t.Errorf("FrameAncestors = %#v; want empty", cfg.FrameAncestors)
+	}
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("Validate() = %v; want nil", err)
+	}
+}
+
+// A directive the browser cannot parse is dropped whole, which would leave the admin SPA
+// more embeddable than with the setting unset. Refusing to start is the only outcome that
+// cannot be missed.
+func TestValidate_rejectsBadFrameAncestors(t *testing.T) {
+	cases := map[string]string{
+		"plain http":     "http://console.example.test",
+		"no scheme":      "console.example.test",
+		"wildcard host":  "https://*.example.test",
+		"with a path":    "https://console.example.test/admin",
+		"with a query":   "https://console.example.test?x=1",
+		"credentials":    "https://user:pw@console.example.test",
+		"none keyword":   "'none'",
+		"unsafe keyword": "'unsafe-inline'",
+		"scheme only":    "https://",
+	}
+	for name, value := range cases {
+		t.Run(name, func(t *testing.T) {
+			t.Setenv("FRAME_ANCESTORS", value)
+			if err := config.Load().Validate(); err == nil {
+				t.Errorf("Validate() = nil for %q; want an error", value)
+			}
+		})
+	}
+}
+
+// One bad entry beside a good one still fails: a half-applied source list is a policy
+// nobody wrote.
+func TestValidate_rejectsAListWithOneBadEntry(t *testing.T) {
+	t.Setenv("FRAME_ANCESTORS", "https://good.example.test http://bad.example.test")
+	if err := config.Load().Validate(); err == nil {
+		t.Error("Validate() = nil; want an error naming the http entry")
+	}
+}
+
+func TestValidate_acceptsAPortAndATrailingSlash(t *testing.T) {
+	t.Setenv("FRAME_ANCESTORS", "https://console.example.test:8443 https://other.example.test/")
+	if err := config.Load().Validate(); err != nil {
+		t.Errorf("Validate() = %v; want nil", err)
+	}
+}
diff --git a/internal/server/frameancestors_test.go b/internal/server/frameancestors_test.go
new file mode 100644
index 0000000..f586794
--- /dev/null
+++ b/internal/server/frameancestors_test.go
@@ -0,0 +1,59 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/calnode/calnode/frontend"
+)
+
+// serveAdminSPA runs a request through the admin SPA handler wrapped exactly as New
+// wraps it, and returns the response.
+func serveAdminSPA(origins []string, path string) *httptest.ResponseRecorder {
+	h := FrameAncestors(origins)(frontend.Handler())
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))
+	return rec
+}
+
+// ⚠️ This pins what /admin/ sends TODAY, which is no frame header at all: the SPA is
+// framable by any site unless an operator says otherwise. FRAME_ANCESTORS deliberately
+// does not change that when unset — an opt-in setting must not smuggle in a default deny
+// — so this test exists to make the next person's change to it deliberate rather than
+// incidental. The public booking pages are the ones that carry an unconditional DENY.
+func TestAdminSPA_sendsNoFrameHeadersWhenUnset(t *testing.T) {
+	for _, path := range []string{"/", "/bookings", "/favicon.svg"} {
+		t.Run(path, func(t *testing.T) {
+			rec := serveAdminSPA(nil, path)
+			if got := rec.Header().Get("Content-Security-Policy"); got != "" {
+				t.Errorf("Content-Security-Policy = %q; want it absent", got)
+			}
+			if got := rec.Header().Get("X-Frame-Options"); got != "" {
+				t.Errorf("X-Frame-Options = %q; want it absent", got)
+			}
+		})
+	}
+}
+
+func TestAdminSPA_frameAncestorsWhenConfigured(t *testing.T) {
+	rec := serveAdminSPA([]string{"https://console.example.test", "'self'"}, "/")
+
+	want := "frame-ancestors https://console.example.test 'self'"
+	if got := rec.Header().Get("Content-Security-Policy"); got != want {
+		t.Errorf("Content-Security-Policy = %q; want %q", got, want)
+	}
+	// X-Frame-Options has no allow-list form, and SAMEORIGIN would be honoured instead of
+	// the CSP by the browsers that read it, breaking the embedding this enables.
+	if got := rec.Header().Get("X-Frame-Options"); got != "" {
+		t.Errorf("X-Frame-Options = %q; want it absent alongside frame-ancestors", got)
+	}
+}
+
+// The SPA fallback route (any client-side path) carries it too, not just the shell.
+func TestAdminSPA_frameAncestorsOnSPAFallback(t *testing.T) {
+	rec := serveAdminSPA([]string{"'self'"}, "/settings/video")
+	if got := rec.Header().Get("Content-Security-Policy"); got != "frame-ancestors 'self'" {
+		t.Errorf("Content-Security-Policy = %q; want frame-ancestors 'self'", got)
+	}
+}
diff --git a/internal/server/middleware.go b/internal/server/middleware.go
index eecc8b3..326ac55 100644
--- a/internal/server/middleware.go
+++ b/internal/server/middleware.go
@@ -240,6 +240,41 @@ func (rl *rateLimiter) cleanup() {
 	}
 }
 
+// FrameAncestors returns middleware that sets `Content-Security-Policy:
+// frame-ancestors <origins>` on the responses it wraps, so an operator can embed the
+// admin SPA in their own console. An empty list is a pass-through.
+//
+// ⛔ Scoped to the admin SPA on purpose, and it must stay that way. The public booking
+// pages set `frame-ancestors 'none'` plus `X-Frame-Options: DENY` in their own handlers
+// (book.go, manage_handler.go, tracking_settings.go's publicCSP) and this must never
+// reach them: they are unauthenticated pages that collect names, emails and card
+// details, and clickjacking one is worth more to an attacker than framing an admin UI
+// nobody can reach without a session.
+//
+// No `X-Frame-Options` is set beside the CSP. That header has no allow-list form — its
+// `ALLOW-FROM` was only ever implemented by one browser and is dead — so the only value
+// it could carry here is `SAMEORIGIN`, which every browser that reads it would apply
+// INSTEAD of honouring the CSP, breaking the embedding this exists to enable. Every
+// browser that can frame anything today supports frame-ancestors.
+//
+// ⚠️ With the list empty the wrapped handler sends no frame header at all, which is what
+// /admin/ has always sent: this middleware does not add a default deny, because that
+// would be a behaviour change smuggled in on an opt-in setting. See
+// TestAdminSPA_sendsNoFrameHeadersWhenUnset, which pins it.
+func FrameAncestors(origins []string) func(http.Handler) http.Handler {
+	if len(origins) == 0 {
+		return func(next http.Handler) http.Handler { return next }
+	}
+	policy := "frame-ancestors " + strings.Join(origins, " ")
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Set before next writes: a header added after the first Write is dropped.
+			w.Header().Set("Content-Security-Policy", policy)
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
 // remoteIP returns the IP a per-IP limit keys on.
 //
 // By default that is the TCP-level remote address, stripped of its port, and the
diff --git a/internal/server/server.go b/internal/server/server.go
index 14a3ec1..2001115 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -536,7 +536,10 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	mux.Handle("GET /favicon.ico", favicon)
 
 	// Admin SPA — served at /admin/* with SPA fallback for client-side routing.
-	adminSPA := frontend.Handler()
+	// FrameAncestors is applied here and nowhere else: FRAME_ANCESTORS is about embedding
+	// the admin console, and the public pages' own DENY must not be reachable from a
+	// config flag.
+	adminSPA := FrameAncestors(cfg.FrameAncestors)(frontend.Handler())
 	mux.Handle("GET /admin", http.RedirectHandler("/admin/", http.StatusMovedPermanently))
 	mux.Handle("/admin/", http.StripPrefix("/admin", adminSPA))
 

From 22dad87c5ae289b841efce634d160db2e8e911ed Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:27:23 -0400
Subject: [PATCH 21/51] metrics: a Prometheus endpoint that is not public by
 accident

GET /metrics exposes build identity, requests by surface and status, a duration
histogram, job-queue depth, booking lifecycle counts, process start time and two Go
runtime gauges. internal/metrics writes the exposition by hand: the format is one
page of stable text, and a scrape endpoint is not worth a dependency tree in a
binary an operator self-hosts. Same trade as hand-signing LiveKit tokens.

It answers 404, not 401, when METRICS_TOKEN is unset or the bearer is wrong, and
the body is byte-identical to the mux's own not-found. A 401 confirms the endpoint
exists and invites a guess, and what is behind it is a business feed: bookings per
hour, request volume by surface, queue depth, on an instance whose whole point is
being publicly reachable. An operator who has not set a token has not agreed to
publish any of that, so there is nothing to advertise. The token compare is over
SHA-256 digests rather than the raw strings, because ConstantTimeCompare returns
early on a length mismatch and would otherwise leak the token's length.

No rate limit: a scrape runs every few seconds by design, and a limiter tuned for
humans would drop samples and leave gaps that read as downtime.

The class label is derived from the path PREFIX only, so the label set is closed at
five values and a request cannot mint a new series. That is the usual way a metrics
endpoint turns into an out-of-memory vector. It costs some precision and the docs
say so: POST /v1/bookings is public and unauthenticated and still counts as api,
because the alternative is a per-route table that goes stale the first time someone
adds a route without noticing.

Requests are counted in the existing Logging middleware rather than a wrapper of
their own: that is already the one place holding the final status and the elapsed
time, and a second measurement of the same request would drift from the log line it
is supposed to corroborate. Job depth is read from the jobs table per scrape,
because any instance can claim any job, so it is not this process's counter to keep.

Booking counts sit in the three shared side-effect functions, which covers the REST,
MCP and manage-link paths at once, and they are incremented next to the webhook
enqueue but not inside its nil check: an instance with no webhooks configured still
has bookings worth counting. A host reassignment is deliberately not counted as a
reschedule, even though it does fire booking.rescheduled, because it does not move
the meeting and counting it would make the series answer a question nobody asked.

All three booking series are emitted at zero rather than appearing on first use.
A series that springs into existence makes rate() over a quiet window return
nothing instead of 0, which a dashboard renders as "no data" rather than "nothing
happened".
---
 CHANGELOG.md                        |  12 ++
 DEPLOY.md                           |   1 +
 docs/ARCHITECTURE.md                |  24 +++
 internal/config/config.go           |   6 +
 internal/handler/booking_handler.go |   6 +
 internal/handler/handler.go         |   1 +
 internal/handler/manage_handler.go  |   6 +
 internal/handler/metrics.go         |  93 ++++++++++
 internal/handler/metrics_test.go    | 107 +++++++++++
 internal/metrics/metrics.go         | 265 ++++++++++++++++++++++++++++
 internal/metrics/metrics_test.go    | 217 +++++++++++++++++++++++
 internal/server/middleware.go       |  10 +-
 internal/server/server.go           |   5 +
 13 files changed, 752 insertions(+), 1 deletion(-)
 create mode 100644 internal/handler/metrics.go
 create mode 100644 internal/handler/metrics_test.go
 create mode 100644 internal/metrics/metrics.go
 create mode 100644 internal/metrics/metrics_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 652fa3f..3bab135 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,18 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
 ## [Unreleased]
 
 ### Added
+- **`GET /metrics`: Prometheus metrics, off until you set `METRICS_TOKEN`.** Build
+  identity, requests by surface and status, a request-duration histogram, pending and
+  failed job counts, bookings created/cancelled/rescheduled, process start time and two Go
+  runtime gauges. No new dependency — the exposition format is a page of text, and a
+  scrape endpoint is not worth a dependency tree in a binary you self-host.
+
+  Without the token, and with a wrong one, it answers 404 rather than 401: these numbers
+  are a business feed, and an operator who has not configured a token has not agreed to
+  publish it, so there is nothing to advertise either. The `class` label comes from the
+  path prefix and nothing else, so the series count is fixed at five times the handful of
+  status codes and a request cannot invent a new one.
+
 - **`FRAME_ANCESTORS`: embed the admin UI in your own console.** Space-separated origins
   (`https://console.example.com 'self'`); when set, `/admin/` sends
   `Content-Security-Policy: frame-ancestors <list>`. The public booking pages are
diff --git a/DEPLOY.md b/DEPLOY.md
index e56b2d8..f1d7365 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -26,6 +26,7 @@ This guide covers a generic Docker deploy and a step-by-step **Railway** deploy
 | `CALNODE_ENCRYPTION_KEY` | **prod: yes** | — | KEK input (Argon2id). **Required when `BASE_URL` is https** — the app refuses to start without it. Use a long random string: `openssl rand -hex 32`. **Losing it makes encrypted data unrecoverable** unless you set the recovery secret below. |
 | `CALNODE_RECOVERY_SECRET` | recommended | — | Escrow secret so the data key can be recovered if the encryption key is rotated/lost. Store it somewhere separate. |
 | `CALNODE_SSO_SHARED_SECRET` | no | — | HMAC key for the signed session hand-off (`GET /v1/auth/sso`). Unset ⇒ that endpoint **404s**. Anything holding this secret can mint a session and create a user, so treat it like the encryption key: `openssl rand -hex 32`, env only, never in the admin UI. |
+| `METRICS_TOKEN` | no | — | Bearer token for `GET /metrics` (Prometheus text exposition). Unset ⇒ that endpoint **404s**, so an instance never publishes its request volume, booking rate or queue depth by accident. Scrape with `Authorization: Bearer $METRICS_TOKEN`; a wrong token gets the same 404 as an unconfigured one. |
 | `BASE_URL` | **yes (prod)** | `http://localhost:3000` | Identity host — admin UI, OAuth callbacks, invite links. **Must include the scheme** (`https://booking.example.com`). The `https://` prefix flips the app into production mode (secure cookies, encryption-key enforcement). |
 | `PUBLIC_BASE_URL` | no | = `BASE_URL` | Booker-facing host for booking links/emails, if different from the identity host. |
 | `DATABASE_URL` | no | `sqlite://./data/calnode.db` | Point at the persistent volume, e.g. `sqlite:///data/calnode.db`. |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index e7c10df..ddf0403 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -63,6 +63,30 @@ app you must `pnpm build` in `frontend/` **and** rebuild/restart the Go binary
   return handler + a `drain` func.
 - Ops endpoints: `GET /healthz`, `GET /readyz` (readiness gate), `GET /version`
   (build stamp from `internal/buildinfo`).
+- **`GET /metrics`** — Prometheus text exposition, hand-written in `internal/metrics`
+  (no client library, for the reason `internal/livekit` signs its own tokens: a
+  one-page stable text protocol is not worth a dependency tree in a self-hosted
+  binary). Series: `calnode_build_info{version,commit}`,
+  `calnode_http_requests_total{class,status}`,
+  `calnode_http_request_duration_seconds` (histogram, fixed buckets),
+  `calnode_jobs_pending`, `calnode_jobs_failed_total`,
+  `calnode_bookings_total{event}` for created/cancelled/rescheduled,
+  `process_start_time_seconds`, `go_goroutines`, `go_memstats_alloc_bytes`.
+  ⛔ **Gated on `Authorization: Bearer $METRICS_TOKEN`, and it answers 404** — identical
+  to the mux's own not-found — when the token is unset or wrong. Not 401: a 401 confirms
+  the endpoint exists, and these numbers are a business feed (bookings per hour, request
+  volume by surface) on an instance meant to be publicly reachable. Not rate-limited
+  either; a scrape runs every few seconds by design and a limiter would punch gaps that
+  read as downtime.
+  `class` is derived from the path **prefix only** (`public|admin|api|mcp|ops`), so the
+  label set is closed and can never be attacker-chosen — the usual way a metrics endpoint
+  becomes an out-of-memory vector. Read it as "which surface of the URL space", not "how
+  the request authenticated": `POST /v1/bookings` is public and unauthenticated and still
+  counts as `api`. Requests are counted in the existing `Logging` middleware, the only
+  place that already knows the final status and elapsed time; job depth is read from the
+  `jobs` table per scrape, because any instance can claim any job. A host **reassignment**
+  fires the `booking.rescheduled` webhook but is deliberately **not** counted as a
+  reschedule — it does not move the meeting.
 - Graceful shutdown drains the worker and in-flight requests before `db.Close()`.
 
 ---
diff --git a/internal/config/config.go b/internal/config/config.go
index c248358..977a922 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -49,6 +49,11 @@ type Config struct {
 	// page an admin session can reach.
 	SSOSharedSecret string
 
+	// MetricsToken is the bearer token that authorises GET /metrics. Empty ⇒ that
+	// endpoint 404s, so an instance never publishes its request volume, booking rate or
+	// queue depth by accident. Env-only, for the same reason as SSOSharedSecret.
+	MetricsToken string
+
 	// CookieSecure sets the Secure flag on session cookies. Defaults to true
 	// when BASE_URL starts with https://, but can be overridden explicitly via
 	// COOKIE_SECURE=false for HTTPS-terminated-at-proxy setups where the binary
@@ -127,6 +132,7 @@ func Load() *Config {
 	cfg.EncryptionKey = os.Getenv("CALNODE_ENCRYPTION_KEY")
 	cfg.RecoverySecret = os.Getenv("CALNODE_RECOVERY_SECRET")
 	cfg.SSOSharedSecret = os.Getenv("CALNODE_SSO_SHARED_SECRET")
+	cfg.MetricsToken = os.Getenv("METRICS_TOKEN")
 	// PUBLIC_BASE_URL overrides the booker-facing host (custom/vanity domain).
 	// Unset → inherits BASE_URL, so single-domain deploys need only set BASE_URL.
 	cfg.PublicBaseURL = getEnv("PUBLIC_BASE_URL", cfg.BaseURL)
diff --git a/internal/handler/booking_handler.go b/internal/handler/booking_handler.go
index 2f558d3..c4fce80 100644
--- a/internal/handler/booking_handler.go
+++ b/internal/handler/booking_handler.go
@@ -18,6 +18,7 @@ import (
 	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/i18n"
 	"github.com/calnode/calnode/internal/mailer"
+	"github.com/calnode/calnode/internal/metrics"
 	"github.com/calnode/calnode/internal/slots"
 	"github.com/calnode/calnode/internal/uid"
 	"github.com/calnode/calnode/internal/webhook"
@@ -1166,6 +1167,10 @@ func (h *Handler) dispatchBookingConfirmation(b *booking.Booking, in bookingConf
 			h.logger.Error("booking confirmation email (attendee)", "error", err, "booking_id", b.ID)
 		}
 	}
+	// Counted where the lifecycle event is dispatched, not where the webhook is enqueued:
+	// an instance with no webhooks configured still has bookings worth counting. This runs
+	// on every create path (REST + MCP) because dispatchBookingConfirmation is shared.
+	metrics.BookingEvent(metrics.BookingCreated)
 	if h.webhookSvc != nil {
 		if err := h.webhookSvc.Enqueue(ctx, "booking.created", webhook.BookingPayload{
 			ID:                 b.ID,
@@ -1593,6 +1598,7 @@ func (h *Handler) cancelSideEffects(b booking.Booking) {
 	_ = h.db.QueryRowContext(ctx,
 		`SELECT payment_status, amount_paid_cents, amount_paid_currency FROM bookings WHERE id = ?`, b.ID).
 		Scan(&payStatus, &payAmt, &payCur)
+	metrics.BookingEvent(metrics.BookingCancelled)
 	if h.webhookSvc != nil {
 		if err := h.webhookSvc.Enqueue(ctx, "booking.cancelled", webhook.BookingPayload{
 			ID:                 b.ID,
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index 567f981..e2f1279 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -40,6 +40,7 @@ type Handler struct {
 	microsoftAuth     *oauth2.Config
 	secureCookie      bool
 	ssoSecret         string // HMAC key for the signed session hand-off; empty ⇒ /v1/auth/sso is off
+	metricsToken      string // bearer token for GET /metrics; empty ⇒ that endpoint 404s
 	llmMu             sync.RWMutex
 	llm               *llm.Client // nil when the optional LLM layer is off/unconfigured
 	zoomMu            sync.RWMutex
diff --git a/internal/handler/manage_handler.go b/internal/handler/manage_handler.go
index 401d1ff..39c3d28 100644
--- a/internal/handler/manage_handler.go
+++ b/internal/handler/manage_handler.go
@@ -13,6 +13,7 @@ import (
 	"github.com/calnode/calnode/internal/booking"
 	"github.com/calnode/calnode/internal/i18n"
 	"github.com/calnode/calnode/internal/mailer"
+	"github.com/calnode/calnode/internal/metrics"
 	"github.com/calnode/calnode/internal/webhook"
 )
 
@@ -307,6 +308,11 @@ func (h *Handler) rescheduleSideEffects(bCopy booking.Booking, capturedEtID stri
 		}
 	}
 
+	// ⚠️ Only a real time change is counted. A host reassignment (reassign.go) also fires
+	// the booking.rescheduled webhook, because a subscriber does need to hear about it, but
+	// it does not move the meeting — counting it here would make "reschedules" answer a
+	// question nobody asked.
+	metrics.BookingEvent(metrics.BookingRescheduled)
 	if h.webhookSvc != nil {
 		if err := h.webhookSvc.Enqueue(ctx, "booking.rescheduled", webhook.BookingPayload{
 			ID:              bCopy.ID,
diff --git a/internal/handler/metrics.go b/internal/handler/metrics.go
new file mode 100644
index 0000000..99600ab
--- /dev/null
+++ b/internal/handler/metrics.go
@@ -0,0 +1,93 @@
+package handler
+
+import (
+	"crypto/sha256"
+	"crypto/subtle"
+	"net/http"
+	"strings"
+
+	"github.com/calnode/calnode/internal/metrics"
+)
+
+// SetMetricsToken configures the bearer token that authorises GET /metrics. Empty leaves
+// the endpoint off. Set once at boot from config, like SetSSOSecret.
+func (h *Handler) SetMetricsToken(token string) {
+	h.metricsToken = token
+}
+
+// Metrics handles GET /metrics — Prometheus text exposition of the counters in
+// internal/metrics plus the job-queue depth read from the database.
+//
+// ⛔ Gated on `Authorization: Bearer <METRICS_TOKEN>`, and it answers **404** — byte-identical
+// to the mux's own not-found — when the token is unset or wrong. Not 401: a 401 confirms the
+// endpoint exists and invites a guess, and the numbers here are a business feed (bookings
+// created per hour, request volume by surface) on an instance whose whole point is being
+// publicly reachable. An operator who has not configured a token has not opted in to
+// publishing any of that, so there is nothing to advertise.
+//
+// The response is not rate-limited: a scrape runs every few seconds by design, and a
+// limiter tuned for humans would drop samples and produce gaps that look like downtime.
+// The token is the control.
+func (h *Handler) Metrics(w http.ResponseWriter, r *http.Request) {
+	if !h.metricsAuthorized(r) {
+		http.NotFound(w, r)
+		return
+	}
+
+	// Job depth lives in the database because any instance can claim any job, so it is
+	// read per scrape rather than counted in this process. One grouped query; a failure is
+	// logged and reported as zero rather than failing the whole scrape, since the process
+	// counters are still worth having when the database is the thing that is unwell (and
+	// /readyz is the endpoint that answers "is the database reachable").
+	var q metrics.Queue
+	rows, err := h.db.QueryContext(r.Context(),
+		`SELECT status, COUNT(*) FROM jobs WHERE status IN ('pending', 'failed') GROUP BY status`)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "metrics: count jobs", "error", err)
+	} else {
+		for rows.Next() {
+			var status string
+			var n int64
+			if err := rows.Scan(&status, &n); err != nil {
+				h.logger.ErrorContext(r.Context(), "metrics: scan job count", "error", err)
+				continue
+			}
+			switch status {
+			case "pending":
+				q.Pending = n
+			case "failed":
+				q.Failed = n
+			}
+		}
+		if err := rows.Err(); err != nil {
+			h.logger.ErrorContext(r.Context(), "metrics: job count rows", "error", err)
+		}
+		rows.Close() // #nosec G104 -- rows already fully consumed; nothing actionable on close error
+	}
+
+	w.Header().Set("Content-Type", metrics.ContentType)
+	// Cache-Control matters here: a scrape must never be answered from an intermediary,
+	// or a dashboard shows a frozen instance as a healthy one.
+	w.Header().Set("Cache-Control", "no-store")
+	if err := metrics.Write(w, q); err != nil {
+		h.logger.ErrorContext(r.Context(), "metrics: write exposition", "error", err)
+	}
+}
+
+// metricsAuthorized reports whether the request carries the configured bearer token.
+//
+// The comparison is over SHA-256 digests rather than the raw strings: subtle.ConstantTimeCompare
+// returns early when the lengths differ, so comparing the values directly would leak the
+// token's length. Hashing makes both sides 32 bytes whatever was sent.
+func (h *Handler) metricsAuthorized(r *http.Request) bool {
+	if h.metricsToken == "" {
+		return false
+	}
+	auth := r.Header.Get("Authorization")
+	if !strings.HasPrefix(auth, "Bearer ") {
+		return false
+	}
+	presented := sha256.Sum256([]byte(strings.TrimPrefix(auth, "Bearer ")))
+	expected := sha256.Sum256([]byte(h.metricsToken))
+	return subtle.ConstantTimeCompare(presented[:], expected[:]) == 1
+}
diff --git a/internal/handler/metrics_test.go b/internal/handler/metrics_test.go
new file mode 100644
index 0000000..1030245
--- /dev/null
+++ b/internal/handler/metrics_test.go
@@ -0,0 +1,107 @@
+package handler_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/handler"
+	"github.com/calnode/calnode/internal/metrics"
+)
+
+const metricsToken = "metrics-token-for-tests"
+
+func doMetrics(h *handler.Handler, auth string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest(http.MethodGet, "/metrics", nil)
+	if auth != "" {
+		req.Header.Set("Authorization", auth)
+	}
+	rec := httptest.NewRecorder()
+	h.Metrics(rec, req)
+	return rec
+}
+
+// Unset METRICS_TOKEN ⇒ 404, byte-identical to the mux's own not-found. A 401 would
+// confirm the endpoint exists on an instance whose operator never opted in to publishing
+// its booking rate.
+func TestMetrics_404WithoutAToken(t *testing.T) {
+	h, _ := newTestHandlerDB(t)
+
+	rec := doMetrics(h, "Bearer "+metricsToken)
+
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status = %d; want 404 — %s", rec.Code, rec.Body.String())
+	}
+	if strings.Contains(rec.Body.String(), "calnode_") {
+		t.Error("body leaked metrics despite the endpoint being off")
+	}
+}
+
+func TestMetrics_rejectsWrongOrMissingBearer(t *testing.T) {
+	cases := map[string]string{
+		"no header":              "",
+		"empty bearer":           "Bearer ",
+		"wrong token":            "Bearer nope",
+		"right token, no scheme": metricsToken,
+		"basic auth":             "Basic " + metricsToken,
+		// A prefix of the real token must not pass: the comparison is over digests, so
+		// length tells an attacker nothing either.
+		"token prefix": "Bearer " + metricsToken[:10],
+	}
+	for name, auth := range cases {
+		t.Run(name, func(t *testing.T) {
+			h, _ := newTestHandlerDB(t)
+			h.SetMetricsToken(metricsToken)
+
+			rec := doMetrics(h, auth)
+
+			if rec.Code != http.StatusNotFound {
+				t.Errorf("status = %d; want 404 for %q", rec.Code, auth)
+			}
+		})
+	}
+}
+
+func TestMetrics_servesExpositionWithTheToken(t *testing.T) {
+	metrics.Reset()
+	h, database := newTestHandlerDB(t)
+	h.SetMetricsToken(metricsToken)
+
+	// Two pending jobs and one failed one, so the gauges are read from the table rather
+	// than reported as zero. The payload differs per row: jobs carries UNIQUE(type,
+	// payload), which is what makes an enqueue idempotent.
+	for _, row := range []struct{ id, status string }{
+		{"job-1", "pending"}, {"job-2", "pending"}, {"job-3", "failed"}, {"job-4", "done"},
+	} {
+		if _, err := database.Exec(
+			`INSERT INTO jobs (id, type, payload, run_at, status) VALUES (?, 'webhook.deliver', ?, '2026-01-01T00:00:00Z', ?)`,
+			row.id, `{"webhook_delivery_id":"`+row.id+`"}`, row.status); err != nil {
+			t.Fatalf("seed job %s: %v", row.id, err)
+		}
+	}
+
+	rec := doMetrics(h, "Bearer "+metricsToken)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	if ct := rec.Header().Get("Content-Type"); ct != metrics.ContentType {
+		t.Errorf("Content-Type = %q; want %q", ct, metrics.ContentType)
+	}
+	// A cached scrape shows a frozen instance as a healthy one.
+	if cc := rec.Header().Get("Cache-Control"); cc != "no-store" {
+		t.Errorf("Cache-Control = %q; want no-store", cc)
+	}
+
+	body := rec.Body.String()
+	for _, want := range []string{
+		"calnode_jobs_pending 2",
+		"calnode_jobs_failed_total 1",
+		"# TYPE calnode_build_info gauge",
+	} {
+		if !strings.Contains(body, want+"\n") {
+			t.Errorf("body missing %q:\n%s", want, body)
+		}
+	}
+}
diff --git a/internal/metrics/metrics.go b/internal/metrics/metrics.go
new file mode 100644
index 0000000..5f5dba6
--- /dev/null
+++ b/internal/metrics/metrics.go
@@ -0,0 +1,265 @@
+// Package metrics collects the handful of process counters Calnode exposes at /metrics
+// in Prometheus text format.
+//
+// It is hand-written rather than backed by prometheus/client_golang for the reason
+// internal/livekit signs its own tokens and internal/stripe speaks HTTP directly: the
+// exposition format is a stable, one-page text protocol, and a scrape endpoint is not
+// worth a dependency tree in a binary an operator is expected to self-host. What is given
+// up is the client library's process/GC collectors and its label-cardinality tooling;
+// what is kept is a metrics endpoint that cannot break on a library upgrade.
+//
+// State is package-level, which is what a metrics registry is: one process, one set of
+// counters, no way to hand a registry down through every call site that needs to record
+// something. The counters are guarded by a single mutex rather than sharded atomics — the
+// hot path already takes the rate limiter's mutex per request, and one uncontended
+// Lock/Unlock around three integer updates is not what will bound this server.
+package metrics
+
+import (
+	"fmt"
+	"io"
+	"runtime"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/calnode/calnode/internal/buildinfo"
+)
+
+// Request classes. A request is classified by its path prefix alone, so the set is fixed
+// and a label can never be attacker-chosen — the thing that turns a metrics endpoint into
+// an out-of-memory vector.
+const (
+	ClassPublic = "public" // booking pages, the embed widget, rooms, branding assets
+	ClassAdmin  = "admin"  // the embedded admin SPA under /admin/
+	ClassAPI    = "api"    // /v1/…
+	ClassMCP    = "mcp"    // /mcp and its OAuth authorization server
+	ClassOps    = "ops"    // /healthz, /readyz, /version, /metrics
+)
+
+// Booking event names for BookingEvent.
+const (
+	BookingCreated     = "created"
+	BookingCancelled   = "cancelled"
+	BookingRescheduled = "rescheduled"
+)
+
+// durationBuckets are the cumulative upper bounds, in seconds, of
+// calnode_http_request_duration_seconds. They are client_golang's default set: fixed at
+// compile time because a histogram's buckets are part of its identity, and changing them
+// on a live instance discards the history in every dashboard built on it.
+var durationBuckets = []float64{
+	0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
+}
+
+// startTime is when the process began, for process_start_time_seconds. Prometheus'
+// standard way of deriving uptime, and the only reliable signal that an instance
+// restarted between two scrapes.
+var startTime = time.Now()
+
+type requestKey struct {
+	class  string
+	status int
+}
+
+var (
+	mu            sync.Mutex
+	requests      = map[requestKey]uint64{}
+	bookings      = map[string]uint64{}
+	bucketCounts  = make([]uint64, len(durationBuckets))
+	durationSum   float64
+	durationCount uint64
+)
+
+// HTTPRequest records one served request. Called from the logging middleware, which
+// already has the class, the final status and the elapsed time in hand.
+func HTTPRequest(class string, status int, d time.Duration) {
+	seconds := d.Seconds()
+	mu.Lock()
+	requests[requestKey{class: class, status: status}]++
+	durationSum += seconds
+	durationCount++
+	for i, upper := range durationBuckets {
+		if seconds <= upper {
+			// Buckets are cumulative, so an observation counts in this bound and every
+			// larger one. Incrementing only the first matching bucket here and summing on
+			// the way out keeps this loop short.
+			bucketCounts[i]++
+			break
+		}
+	}
+	mu.Unlock()
+}
+
+// BookingEvent records a booking lifecycle event: one of the Booking* constants.
+func BookingEvent(event string) {
+	mu.Lock()
+	bookings[event]++
+	mu.Unlock()
+}
+
+// Reset clears every counter. For tests only — a scrape endpoint whose numbers depend on
+// which other tests ran first is not testable.
+func Reset() {
+	mu.Lock()
+	requests = map[requestKey]uint64{}
+	bookings = map[string]uint64{}
+	bucketCounts = make([]uint64, len(durationBuckets))
+	durationSum, durationCount = 0, 0
+	mu.Unlock()
+}
+
+// Queue is the job-queue depth, which lives in the database rather than in this process
+// (any instance can claim any job), so the caller reads it and passes it in.
+type Queue struct {
+	Pending int64
+	Failed  int64
+}
+
+// ContentType is the exposition format's media type, for the response header.
+const ContentType = "text/plain; version=0.0.4; charset=utf-8"
+
+// Write renders the exposition. Ordering is deterministic — labelled series are sorted —
+// so a diff of two scrapes shows what changed rather than what got re-mapped.
+func Write(w io.Writer, q Queue) error {
+	var ms runtime.MemStats
+	runtime.ReadMemStats(&ms)
+	goroutines := runtime.NumGoroutine()
+
+	// Snapshot under the lock, render outside it: rendering does formatting and I/O, and
+	// holding the counters' mutex across a write to a possibly-slow client would stall
+	// every request in the process.
+	mu.Lock()
+	reqSnapshot := make(map[requestKey]uint64, len(requests))
+	for k, v := range requests {
+		reqSnapshot[k] = v
+	}
+	bookSnapshot := make(map[string]uint64, len(bookings))
+	for k, v := range bookings {
+		bookSnapshot[k] = v
+	}
+	buckets := append([]uint64(nil), bucketCounts...)
+	sum, count := durationSum, durationCount
+	mu.Unlock()
+
+	bi := buildinfo.Get()
+	b := &errWriter{w: w}
+
+	b.line("# HELP calnode_build_info Build identity of the running binary; always 1.")
+	b.line("# TYPE calnode_build_info gauge")
+	b.linef("calnode_build_info{version=%q,commit=%q} 1", bi.Version, bi.Commit)
+
+	b.line("# HELP calnode_http_requests_total Requests served, by path class and response status.")
+	b.line("# TYPE calnode_http_requests_total counter")
+	for _, k := range sortedRequestKeys(reqSnapshot) {
+		b.linef("calnode_http_requests_total{class=%q,status=%q} %d",
+			k.class, strconv.Itoa(k.status), reqSnapshot[k])
+	}
+
+	b.line("# HELP calnode_http_request_duration_seconds Time to serve a request.")
+	b.line("# TYPE calnode_http_request_duration_seconds histogram")
+	var cumulative uint64
+	for i, upper := range durationBuckets {
+		cumulative += buckets[i]
+		b.linef("calnode_http_request_duration_seconds_bucket{le=%q} %d",
+			formatFloat(upper), cumulative)
+	}
+	b.linef("calnode_http_request_duration_seconds_bucket{le=\"+Inf\"} %d", count)
+	b.linef("calnode_http_request_duration_seconds_sum %s", formatFloat(sum))
+	b.linef("calnode_http_request_duration_seconds_count %d", count)
+
+	b.line("# HELP calnode_jobs_pending Background jobs waiting to run.")
+	b.line("# TYPE calnode_jobs_pending gauge")
+	b.linef("calnode_jobs_pending %d", q.Pending)
+
+	b.line("# HELP calnode_jobs_failed_total Background jobs that exhausted their retries.")
+	b.line("# TYPE calnode_jobs_failed_total counter")
+	b.linef("calnode_jobs_failed_total %d", q.Failed)
+
+	b.line("# HELP calnode_bookings_total Booking lifecycle events since this process started.")
+	b.line("# TYPE calnode_bookings_total counter")
+	// Always emit all three, at zero if need be: a series that only appears once it is
+	// non-zero makes a rate() over a quiet window return nothing instead of 0, which
+	// reads on a dashboard as "no data" rather than "nothing happened".
+	for _, event := range []string{BookingCreated, BookingCancelled, BookingRescheduled} {
+		b.linef("calnode_bookings_total{event=%q} %d", event, bookSnapshot[event])
+	}
+
+	b.line("# HELP process_start_time_seconds Start time of the process since the unix epoch.")
+	b.line("# TYPE process_start_time_seconds gauge")
+	b.linef("process_start_time_seconds %d", startTime.Unix())
+
+	b.line("# HELP go_goroutines Number of goroutines that currently exist.")
+	b.line("# TYPE go_goroutines gauge")
+	b.linef("go_goroutines %d", goroutines)
+
+	b.line("# HELP go_memstats_alloc_bytes Bytes allocated and still in use.")
+	b.line("# TYPE go_memstats_alloc_bytes gauge")
+	b.linef("go_memstats_alloc_bytes %d", ms.Alloc)
+
+	return b.err
+}
+
+// sortedRequestKeys orders series by class then status.
+func sortedRequestKeys(m map[requestKey]uint64) []requestKey {
+	keys := make([]requestKey, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Slice(keys, func(i, j int) bool {
+		if keys[i].class != keys[j].class {
+			return keys[i].class < keys[j].class
+		}
+		return keys[i].status < keys[j].status
+	})
+	return keys
+}
+
+// formatFloat renders a float the way the exposition format wants it: shortest form that
+// round-trips, never scientific notation for the values in play here.
+func formatFloat(f float64) string {
+	return strconv.FormatFloat(f, 'g', -1, 64)
+}
+
+// errWriter collects the first write error so the renderer above stays free of
+// per-line error handling. A scrape that fails mid-body is reported to the caller and
+// logged; there is nothing to roll back.
+type errWriter struct {
+	w   io.Writer
+	err error
+}
+
+func (e *errWriter) line(s string) {
+	if e.err != nil {
+		return
+	}
+	_, e.err = io.WriteString(e.w, s+"\n")
+}
+
+func (e *errWriter) linef(format string, args ...any) {
+	e.line(fmt.Sprintf(format, args...))
+}
+
+// ClassifyPath maps a request path to one of the five classes, by prefix only.
+//
+// ⚠️ Syntactic on purpose: POST /v1/bookings is a public, unauthenticated endpoint and
+// still counts as "api" here, because the alternative is a per-route table that drifts
+// silently the first time someone adds a route. Read the classes as "which surface of the
+// URL space", not "how the request was authenticated".
+func ClassifyPath(path string) string {
+	switch {
+	case path == "/healthz" || path == "/readyz" || path == "/version" || path == "/metrics":
+		return ClassOps
+	case path == "/mcp" || strings.HasPrefix(path, "/mcp/") ||
+		strings.HasPrefix(path, "/oauth/") || strings.HasPrefix(path, "/.well-known/"):
+		return ClassMCP
+	case path == "/admin" || strings.HasPrefix(path, "/admin/"):
+		return ClassAdmin
+	case strings.HasPrefix(path, "/v1/"):
+		return ClassAPI
+	default:
+		return ClassPublic
+	}
+}
diff --git a/internal/metrics/metrics_test.go b/internal/metrics/metrics_test.go
new file mode 100644
index 0000000..734ac8b
--- /dev/null
+++ b/internal/metrics/metrics_test.go
@@ -0,0 +1,217 @@
+package metrics_test
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/calnode/calnode/internal/metrics"
+)
+
+// scrape renders the exposition and returns its lines.
+func scrape(t *testing.T, q metrics.Queue) []string {
+	t.Helper()
+	var sb strings.Builder
+	if err := metrics.Write(&sb, q); err != nil {
+		t.Fatalf("Write: %v", err)
+	}
+	return strings.Split(strings.TrimRight(sb.String(), "\n"), "\n")
+}
+
+func hasLine(lines []string, want string) bool {
+	for _, l := range lines {
+		if l == want {
+			return true
+		}
+	}
+	return false
+}
+
+func findLine(t *testing.T, lines []string, prefix string) string {
+	t.Helper()
+	for _, l := range lines {
+		if strings.HasPrefix(l, prefix) {
+			return l
+		}
+	}
+	t.Fatalf("no line starting %q in:\n%s", prefix, strings.Join(lines, "\n"))
+	return ""
+}
+
+// A deliberately parser-free check: assert the exact lines an operator's scrape config
+// depends on. Pulling in a Prometheus parser to test this would defeat the reason the
+// exposition is hand-written.
+func TestWrite_exposesEveryDocumentedSeries(t *testing.T) {
+	metrics.Reset()
+	metrics.HTTPRequest(metrics.ClassAPI, 200, 12*time.Millisecond)
+	metrics.HTTPRequest(metrics.ClassAPI, 200, 8*time.Millisecond)
+	metrics.HTTPRequest(metrics.ClassPublic, 404, 3*time.Millisecond)
+	metrics.BookingEvent(metrics.BookingCreated)
+
+	lines := scrape(t, metrics.Queue{Pending: 4, Failed: 2})
+
+	for _, want := range []string{
+		`calnode_http_requests_total{class="api",status="200"} 2`,
+		`calnode_http_requests_total{class="public",status="404"} 1`,
+		`calnode_bookings_total{event="created"} 1`,
+		// Emitted at zero rather than omitted, so a rate() over a quiet window returns 0
+		// instead of nothing.
+		`calnode_bookings_total{event="cancelled"} 0`,
+		`calnode_bookings_total{event="rescheduled"} 0`,
+		`calnode_jobs_pending 4`,
+		`calnode_jobs_failed_total 2`,
+		`calnode_http_request_duration_seconds_count 3`,
+	} {
+		if !hasLine(lines, want) {
+			t.Errorf("missing line:\n  %s\ngot:\n%s", want, strings.Join(lines, "\n"))
+		}
+	}
+
+	// The ones whose values are not fixed: assert shape, not value.
+	for _, prefix := range []string{
+		"calnode_build_info{version=",
+		"process_start_time_seconds ",
+		"go_goroutines ",
+		"go_memstats_alloc_bytes ",
+	} {
+		findLine(t, lines, prefix)
+	}
+	if !strings.HasSuffix(findLine(t, lines, "calnode_build_info{version="), " 1") {
+		t.Error("calnode_build_info must always be 1")
+	}
+}
+
+// Every series needs its HELP and TYPE, or a scrape is a wall of unlabelled numbers.
+func TestWrite_everyMetricHasHelpAndType(t *testing.T) {
+	metrics.Reset()
+	lines := scrape(t, metrics.Queue{})
+
+	names := []string{
+		"calnode_build_info",
+		"calnode_http_requests_total",
+		"calnode_http_request_duration_seconds",
+		"calnode_jobs_pending",
+		"calnode_jobs_failed_total",
+		"calnode_bookings_total",
+		"process_start_time_seconds",
+		"go_goroutines",
+		"go_memstats_alloc_bytes",
+	}
+	for _, name := range names {
+		if !hasPrefixLine(lines, "# HELP "+name+" ") {
+			t.Errorf("%s has no HELP", name)
+		}
+		if !hasPrefixLine(lines, "# TYPE "+name+" ") {
+			t.Errorf("%s has no TYPE", name)
+		}
+	}
+}
+
+func hasPrefixLine(lines []string, prefix string) bool {
+	for _, l := range lines {
+		if strings.HasPrefix(l, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+// Every non-comment line must be "name value" or "name{labels} value" — one metric per
+// line, exactly two fields once the label set is closed.
+func TestWrite_everySampleLineIsWellFormed(t *testing.T) {
+	metrics.Reset()
+	metrics.HTTPRequest(metrics.ClassOps, 200, time.Millisecond)
+	lines := scrape(t, metrics.Queue{Pending: 1})
+
+	for _, l := range lines {
+		if strings.HasPrefix(l, "#") {
+			continue
+		}
+		if l == "" {
+			t.Error("blank sample line")
+			continue
+		}
+		// A sample is `name value` or `name{labels} value`. Count the fields after the
+		// label set (if any), which is the one place a stray space or a missing value
+		// would show up.
+		want := 2
+		rest := l
+		if close := strings.LastIndex(l, "}"); close >= 0 {
+			rest = l[close+1:]
+			want = 1
+		}
+		if got := len(strings.Fields(rest)); got != want {
+			t.Errorf("line %q has %d fields after its name/labels; want %d", l, got, want)
+		}
+	}
+}
+
+// Buckets are cumulative and the last one equals _count. Getting this wrong yields a
+// histogram that renders as a plausible but wrong latency distribution.
+func TestWrite_histogramBucketsAreCumulative(t *testing.T) {
+	metrics.Reset()
+	metrics.HTTPRequest(metrics.ClassAPI, 200, 1*time.Millisecond)   // ≤ 0.005
+	metrics.HTTPRequest(metrics.ClassAPI, 200, 30*time.Millisecond)  // ≤ 0.05
+	metrics.HTTPRequest(metrics.ClassAPI, 200, 400*time.Millisecond) // ≤ 0.5
+	metrics.HTTPRequest(metrics.ClassAPI, 200, 30*time.Second)       // over the top bucket
+
+	lines := scrape(t, metrics.Queue{})
+
+	for _, want := range []string{
+		`calnode_http_request_duration_seconds_bucket{le="0.005"} 1`,
+		`calnode_http_request_duration_seconds_bucket{le="0.01"} 1`,
+		`calnode_http_request_duration_seconds_bucket{le="0.05"} 2`,
+		`calnode_http_request_duration_seconds_bucket{le="0.5"} 3`,
+		`calnode_http_request_duration_seconds_bucket{le="10"} 3`,
+		// The 30s observation only ever appears in +Inf and _count.
+		`calnode_http_request_duration_seconds_bucket{le="+Inf"} 4`,
+		`calnode_http_request_duration_seconds_count 4`,
+	} {
+		if !hasLine(lines, want) {
+			t.Errorf("missing line:\n  %s\ngot:\n%s", want, strings.Join(lines, "\n"))
+		}
+	}
+}
+
+func TestClassifyPath(t *testing.T) {
+	cases := map[string]string{
+		"/healthz":                  metrics.ClassOps,
+		"/readyz":                   metrics.ClassOps,
+		"/version":                  metrics.ClassOps,
+		"/metrics":                  metrics.ClassOps,
+		"/mcp":                      metrics.ClassMCP,
+		"/oauth/token":              metrics.ClassMCP,
+		"/.well-known/oauth-server": metrics.ClassMCP,
+		"/admin":                    metrics.ClassAdmin,
+		"/admin/bookings":           metrics.ClassAdmin,
+		"/v1/bookings":              metrics.ClassAPI,
+		"/v1/event-types/x/slots":   metrics.ClassAPI,
+		"/book/intro":               metrics.ClassPublic,
+		"/manage/tok":               metrics.ClassPublic,
+		"/room/abc":                 metrics.ClassPublic,
+		"/embed.js":                 metrics.ClassPublic,
+		"/":                         metrics.ClassPublic,
+		// Not /admin/: a path that merely starts with those letters is a public 404, and
+		// must not be filed under the console.
+		"/administrivia": metrics.ClassPublic,
+	}
+	for path, want := range cases {
+		if got := metrics.ClassifyPath(path); got != want {
+			t.Errorf("ClassifyPath(%q) = %q; want %q", path, got, want)
+		}
+	}
+}
+
+// The label set has to stay closed, or a metrics endpoint becomes a memory vector: one
+// series per distinct label value, and paths are attacker-chosen.
+func TestClassifyPath_labelSetIsClosed(t *testing.T) {
+	allowed := map[string]bool{
+		metrics.ClassPublic: true, metrics.ClassAdmin: true, metrics.ClassAPI: true,
+		metrics.ClassMCP: true, metrics.ClassOps: true,
+	}
+	for _, path := range []string{"", "/", "//", "/../etc/passwd", "/v1", "/mcpx", strings.Repeat("/a", 500)} {
+		if got := metrics.ClassifyPath(path); !allowed[got] {
+			t.Errorf("ClassifyPath(%q) = %q, which is outside the five classes", path, got)
+		}
+	}
+}
diff --git a/internal/server/middleware.go b/internal/server/middleware.go
index 326ac55..8041e57 100644
--- a/internal/server/middleware.go
+++ b/internal/server/middleware.go
@@ -12,6 +12,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/calnode/calnode/internal/metrics"
 )
 
 type contextKey string
@@ -43,12 +45,18 @@ func Logging(logger *slog.Logger, next http.Handler) http.Handler {
 
 		next.ServeHTTP(rw, r)
 
+		// Counted here rather than in a middleware of its own: this is already the one
+		// place that knows the final status and the elapsed time, and a second wrapper
+		// measuring the same thing would drift from the log line it is supposed to match.
+		elapsed := time.Since(start)
+		metrics.HTTPRequest(metrics.ClassifyPath(r.URL.Path), rw.status, elapsed)
+
 		reqID, _ := r.Context().Value(requestIDKey).(string)
 		logger.InfoContext(r.Context(), "request",
 			"method", r.Method,
 			"path", r.URL.Path,
 			"status", rw.status,
-			"duration_ms", time.Since(start).Milliseconds(),
+			"duration_ms", elapsed.Milliseconds(),
 			"remote_addr", r.RemoteAddr,
 			"request_id", reqID,
 		)
diff --git a/internal/server/server.go b/internal/server/server.go
index 2001115..11c125d 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -44,6 +44,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	h.SetDataDir("data")
 	h.SetEncKey(cfg.EncryptionKey)
 	h.SetSSOSecret(cfg.SSOSharedSecret)
+	h.SetMetricsToken(cfg.MetricsToken)
 	h.SetDemoMode(cfg.DemoMode)
 	h.SetDemoResetInterval(cfg.DemoResetInterval)
 
@@ -258,6 +259,10 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	mux.HandleFunc("GET /healthz", h.Healthz)
 	mux.HandleFunc("GET /readyz", h.Readyz)
 	mux.HandleFunc("GET /version", h.Version)
+	// Prometheus exposition. Registered unconditionally and gated inside the handler on
+	// METRICS_TOKEN, which answers 404 when it is unset — so an instance never publishes
+	// its request volume or booking rate by accident, and never advertises the endpoint.
+	mux.HandleFunc("GET /metrics", h.Metrics)
 
 	// Bootstrap — public, once-only
 	mux.HandleFunc("POST /v1/setup", h.Setup)

From f6a7ffd500c206e35ab4f18fa8e436d4b19d8189 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:30:34 -0400
Subject: [PATCH 22/51] stt: let an operator choose which endpoint hears the
 recordings

The Deepgram host was a hardcoded constant, so meeting audio always went to the
provider's global endpoint. STT_BASE_URL points it elsewhere: a regional endpoint,
so recordings are transcribed inside one jurisdiction, or a self-hosted deployment
of the same API. The default is unchanged and a test pins the exact URL, query
included, because a dropped diarize=true returns a transcript with no speaker
labels rather than an error.

Only the host is configurable. The path, model and options stay in listenPath, so
an operator picks a region and not a different request; a trailing slash is trimmed
so both spellings of a host behave the same.

The base URL is a NewDeepgram parameter rather than a package variable, because
configuration reaching a client through a global is configuration nobody can see at
the call site.

GET /v1/settings/notetaker now reports the effective value as stt_base_url,
resolved on read so a Handler built without the setter still names the real default
instead of an empty string. It is read-only and env-only, unlike the API key beside
it: an admin should be able to see where recording audio is sent without shelling
into a container, and should not be able to repoint it from a browser session.
---
 CHANGELOG.md                                | 11 ++++
 DEPLOY.md                                   |  1 +
 docs/ARCHITECTURE.md                        |  9 ++++
 internal/config/config.go                   |  8 +++
 internal/handler/handler.go                 | 18 +++++++
 internal/handler/notetaker.go               |  2 +-
 internal/handler/notetaker_http.go          |  4 ++
 internal/handler/notetaker_settings_test.go | 60 +++++++++++++++++++++
 internal/server/server.go                   |  1 +
 internal/stt/deepgram.go                    | 47 +++++++++++++---
 internal/stt/deepgram_test.go               | 32 +++++++++++
 11 files changed, 185 insertions(+), 8 deletions(-)
 create mode 100644 internal/handler/notetaker_settings_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3bab135..4f8b7fb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,17 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
 ## [Unreleased]
 
 ### Added
+- **`STT_BASE_URL`: choose which speech-to-text endpoint transcribes your recordings.**
+  The host was hardcoded, so meeting audio always went to the provider's global endpoint —
+  a problem if you need it transcribed inside one jurisdiction. The default is unchanged.
+
+  Only the host is configurable; the path, model and transcription options stay ours, so
+  this picks a region rather than a different request. The effective value is reported
+  read-only as `stt_base_url` in `GET /v1/settings/notetaker`, because an admin should be
+  able to see where audio is sent without reading a running container's environment — and
+  should not be able to repoint it from a browser session, which is why it is not a
+  settings field.
+
 - **`GET /metrics`: Prometheus metrics, off until you set `METRICS_TOKEN`.** Build
   identity, requests by surface and status, a request-duration histogram, pending and
   failed job counts, bookings created/cancelled/rescheduled, process start time and two Go
diff --git a/DEPLOY.md b/DEPLOY.md
index f1d7365..97ed1c2 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -40,6 +40,7 @@ This guide covers a generic Docker deploy and a step-by-step **Railway** deploy
 | `TRUSTED_PROXY_CIDRS` | no | — | Comma-separated CIDRs (a bare address = one host) whose `CF-Connecting-IP` / `X-Forwarded-For` are believed when keying per-IP rate limits, e.g. `10.0.0.0/8`. Unset ⇒ those headers are ignored and the limit keys on the TCP peer, so behind a fronting CDN every visitor shares one bucket. **Only list networks you control**: anything in the list can name any client IP it likes. |
 | `FRAME_ANCESTORS` | no | — | **Space**-separated origins allowed to embed the **admin UI** in a frame, e.g. `https://console.example.com 'self'`. Each entry must be `https://host[:port]` or `'self'` — anything else and **the app refuses to start**, because browsers drop a policy they cannot parse. Does not affect the public booking pages, which always deny framing. |
 | `LOG_LEVEL` | no | `info` | `debug`/`info`/`warn`/`error`. |
+| `STT_BASE_URL` | no | `https://api.deepgram.com` | Speech-to-text endpoint **host** for meeting transcription, e.g. a regional endpoint so recording audio stays in one jurisdiction. Host only — the path, model and options are fixed. Shown read-only in Settings → Notetaker as `stt_base_url`. |
 
 ¹ Email is optional to boot, but bookings won't send confirmations until SMTP is configured (env **or** the admin UI). Precedence is **env var > DB setting > default**.
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index ddf0403..027b104 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -54,6 +54,15 @@ app you must `pnpm build` in `frontend/` **and** rebuild/restart the Go binary
   - `MICROSOFT_CLIENT_ID/SECRET` and `MICROSOFT_TENANT` (default `common`; use the
     multi-tenant `common` so any work/personal Microsoft account can connect/sign in)
   - `COOKIE_SECURE` (defaults true when BASE_URL is https)
+  - `STT_BASE_URL` — speech-to-text endpoint **host** for the notetaker; defaults to
+    `stt.DefaultBaseURL` (`https://api.deepgram.com`). Set it to a regional endpoint to
+    keep recording audio inside one jurisdiction. Only the host is configurable: the path,
+    model and transcription options stay Calnode's (`internal/stt`'s `listenPath`), so an
+    operator picks a region and not a different request. Surfaced **read-only** as
+    `stt_base_url` in `GET /v1/settings/notetaker` — an admin should be able to read where
+    audio is sent without shelling into the container, and should not be able to repoint it
+    from a browser session, which is why it is env-only rather than a DB setting like the
+    API key beside it.
 - Startup (`internal/server/server.go: New`): open DB → run goose migrations →
   open keyvault (unwrap DEK) → configure mailer (DB settings override env) → start
   webhook/reminder **worker** → load Google creds (DB > env) → build one
diff --git a/internal/config/config.go b/internal/config/config.go
index 977a922..d94b104 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -54,6 +54,13 @@ type Config struct {
 	// queue depth by accident. Env-only, for the same reason as SSOSharedSecret.
 	MetricsToken string
 
+	// STTBaseURL overrides the speech-to-text endpoint host for the notetaker, e.g. a
+	// regional endpoint so recordings are transcribed inside one jurisdiction. Empty ⇒
+	// stt.DefaultBaseURL. Only the host is configurable; the path, model and options are
+	// Calnode's. Surfaced read-only in GET /v1/settings/notetaker so an operator can see
+	// where audio is being sent without reading the environment of a running container.
+	STTBaseURL string
+
 	// CookieSecure sets the Secure flag on session cookies. Defaults to true
 	// when BASE_URL starts with https://, but can be overridden explicitly via
 	// COOKIE_SECURE=false for HTTPS-terminated-at-proxy setups where the binary
@@ -124,6 +131,7 @@ func Load() *Config {
 
 		EmbedAllowedOrigins: splitCSV(getEnv("EMBED_ALLOWED_ORIGINS", "")),
 		TrustedProxyCIDRs:   splitCSV(getEnv("TRUSTED_PROXY_CIDRS", "")),
+		STTBaseURL:          getEnv("STT_BASE_URL", ""),
 		// Space-separated, not comma: the value goes into a CSP source list verbatim, so
 		// it reads the same in the env var as it does in the header.
 		FrameAncestors: strings.Fields(getEnv("FRAME_ANCESTORS", "")),
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index e2f1279..e775949 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -17,6 +17,7 @@ import (
 	"github.com/calnode/calnode/internal/llm"
 	"github.com/calnode/calnode/internal/mailer"
 	"github.com/calnode/calnode/internal/stripe"
+	"github.com/calnode/calnode/internal/stt"
 	"github.com/calnode/calnode/internal/webhook"
 	"github.com/calnode/calnode/internal/zoom"
 )
@@ -41,6 +42,7 @@ type Handler struct {
 	secureCookie      bool
 	ssoSecret         string // HMAC key for the signed session hand-off; empty ⇒ /v1/auth/sso is off
 	metricsToken      string // bearer token for GET /metrics; empty ⇒ that endpoint 404s
+	sttBaseURLCfg     string // STT_BASE_URL override; empty ⇒ stt.DefaultBaseURL (see sttBaseURL)
 	llmMu             sync.RWMutex
 	llm               *llm.Client // nil when the optional LLM layer is off/unconfigured
 	zoomMu            sync.RWMutex
@@ -176,6 +178,22 @@ func (h *Handler) publicURL() string {
 	return h.baseURL
 }
 
+// SetSTTBaseURL sets the speech-to-text endpoint host used by the notetaker. Empty keeps
+// the provider default.
+func (h *Handler) SetSTTBaseURL(url string) {
+	h.sttBaseURLCfg = url
+}
+
+// sttBaseURL returns the effective endpoint host. Resolved on read rather than at set
+// time so a Handler built without SetSTTBaseURL (every test) still reports the real
+// default rather than an empty string.
+func (h *Handler) sttBaseURL() string {
+	if h.sttBaseURLCfg != "" {
+		return h.sttBaseURLCfg
+	}
+	return stt.DefaultBaseURL
+}
+
 // SetDataDir sets the directory used for file uploads (avatars, etc.).
 func (h *Handler) SetDataDir(dir string) {
 	h.dataDir = dir
diff --git a/internal/handler/notetaker.go b/internal/handler/notetaker.go
index 627ef26..dd3df25 100644
--- a/internal/handler/notetaker.go
+++ b/internal/handler/notetaker.go
@@ -129,7 +129,7 @@ func (h *Handler) JobNotetakerTranscribe(ctx context.Context, payload string) er
 		return nil
 	}
 	url := presignS3Get(s3, objectKey, time.Hour, timeNow())
-	res, err := stt.NewDeepgram(key).TranscribeURL(ctx, url)
+	res, err := stt.NewDeepgram(key, h.sttBaseURL()).TranscribeURL(ctx, url)
 	if err != nil {
 		return err // transient — retry
 	}
diff --git a/internal/handler/notetaker_http.go b/internal/handler/notetaker_http.go
index fb2ab6d..2576fdd 100644
--- a/internal/handler/notetaker_http.go
+++ b/internal/handler/notetaker_http.go
@@ -30,6 +30,10 @@ func (h *Handler) GetNotetakerSettings(w http.ResponseWriter, r *http.Request) {
 	h.writeJSON(w, http.StatusOK, map[string]any{
 		"enabled":         enabled != 0,
 		"stt_api_key_set": keyEnc != "",
+		// Read-only, and env-only (STT_BASE_URL): it names where recording audio is sent,
+		// which an admin should be able to read without shelling into the container, and
+		// should not be able to repoint from a browser session.
+		"stt_base_url": h.sttBaseURL(),
 	})
 }
 
diff --git a/internal/handler/notetaker_settings_test.go b/internal/handler/notetaker_settings_test.go
new file mode 100644
index 0000000..3dabc95
--- /dev/null
+++ b/internal/handler/notetaker_settings_test.go
@@ -0,0 +1,60 @@
+package handler_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/calnode/calnode/internal/handler"
+	"github.com/calnode/calnode/internal/stt"
+)
+
+func notetakerSettings(t *testing.T, h *handler.Handler, apiKey string) map[string]any {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	h.RequireAuth(h.GetNotetakerSettings)(rec, authReq(http.MethodGet, "/v1/settings/notetaker", "", apiKey))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	var out map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	return out
+}
+
+// An admin should be able to read which endpoint recording audio is sent to without
+// shelling into the container to look at the environment.
+func TestNotetakerSettings_reportsSTTBaseURL(t *testing.T) {
+	h, _, apiKey, _ := setupWorkspaceWithDB(t)
+
+	if got := notetakerSettings(t, h, apiKey)["stt_base_url"]; got != stt.DefaultBaseURL {
+		t.Errorf("stt_base_url = %v; want the provider default %q", got, stt.DefaultBaseURL)
+	}
+
+	h.SetSTTBaseURL("https://api.eu.deepgram.com")
+	if got := notetakerSettings(t, h, apiKey)["stt_base_url"]; got != "https://api.eu.deepgram.com" {
+		t.Errorf("stt_base_url = %v; want the configured host", got)
+	}
+}
+
+// Read-only: PATCH has no field for it, so a value posted under that name is ignored
+// rather than stored. The endpoint answers with GetNotetakerSettings, so the response
+// still reports the env-configured host.
+func TestNotetakerSettings_sttBaseURLIsNotWritable(t *testing.T) {
+	h, _, apiKey, _ := setupWorkspaceWithDB(t)
+	h.SetSTTBaseURL("https://api.eu.deepgram.com")
+
+	rec := httptest.NewRecorder()
+	h.RequireAuth(h.PatchNotetakerSettings)(rec,
+		authReq(http.MethodPatch, "/v1/settings/notetaker",
+			`{"enabled":true,"stt_base_url":"https://attacker.example.test"}`, apiKey))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+
+	if got := notetakerSettings(t, h, apiKey)["stt_base_url"]; got != "https://api.eu.deepgram.com" {
+		t.Errorf("stt_base_url = %v; a PATCH must not be able to repoint it", got)
+	}
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index 11c125d..39efbc2 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -45,6 +45,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	h.SetEncKey(cfg.EncryptionKey)
 	h.SetSSOSecret(cfg.SSOSharedSecret)
 	h.SetMetricsToken(cfg.MetricsToken)
+	h.SetSTTBaseURL(cfg.STTBaseURL)
 	h.SetDemoMode(cfg.DemoMode)
 	h.SetDemoResetInterval(cfg.DemoResetInterval)
 
diff --git a/internal/stt/deepgram.go b/internal/stt/deepgram.go
index c537285..fa6e7ad 100644
--- a/internal/stt/deepgram.go
+++ b/internal/stt/deepgram.go
@@ -1,6 +1,10 @@
 // Package stt provides speech-to-text for meeting recordings. The only backend today is
 // Deepgram, which transcribes a pre-recorded file directly from a URL (we hand it a short-lived
 // presigned S3 URL), so Calnode never downloads the media itself.
+//
+// The endpoint host is configurable (STT_BASE_URL) while the path and query are not: an
+// operator picks a region — or a self-hosted deployment of the same API — without being
+// able to change which model or options Calnode asks for.
 package stt
 
 import (
@@ -31,16 +35,45 @@ type Result struct {
 
 // Deepgram transcribes via the Deepgram pre-recorded API.
 type Deepgram struct {
-	apiKey string
-	hc     *http.Client
+	apiKey  string
+	baseURL string
+	hc      *http.Client
 }
 
-// NewDeepgram builds a client for the given API key.
-func NewDeepgram(apiKey string) *Deepgram {
-	return &Deepgram{apiKey: apiKey, hc: &http.Client{Timeout: 10 * time.Minute}}
+// DefaultBaseURL is Deepgram's global endpoint, and what an unconfigured instance uses.
+const DefaultBaseURL = "https://api.deepgram.com"
+
+// listenPath is the pre-recorded transcription endpoint and the options Calnode asks for.
+// Kept separate from the base URL so pointing at a regional or self-hosted deployment
+// changes the host and nothing about the request.
+const listenPath = "/v1/listen?model=nova-2&smart_format=true&punctuate=true&diarize=true&utterances=true"
+
+// NewDeepgram builds a client for the given API key. An empty baseURL means
+// DefaultBaseURL; a trailing slash is trimmed so `https://api.eu.deepgram.com/` and the
+// same value without it behave identically.
+//
+// The base URL is a parameter rather than a package-level variable because it is
+// deployment configuration, and configuration that arrives through a global is
+// configuration nobody can see at the call site.
+func NewDeepgram(apiKey, baseURL string) *Deepgram {
+	baseURL = strings.TrimRight(strings.TrimSpace(baseURL), "/")
+	if baseURL == "" {
+		baseURL = DefaultBaseURL
+	}
+	return &Deepgram{
+		apiKey:  apiKey,
+		baseURL: baseURL,
+		hc:      &http.Client{Timeout: 10 * time.Minute},
+	}
 }
 
-const deepgramURL = "https://api.deepgram.com/v1/listen?model=nova-2&smart_format=true&punctuate=true&diarize=true&utterances=true"
+// BaseURL reports the endpoint this client will call, resolved. Surfaced read-only in the
+// notetaker settings so an operator can see which region their audio is being sent to.
+func (d *Deepgram) BaseURL() string { return d.baseURL }
+
+// listenURL is the full request target: the configured host with Calnode's own path and
+// query. Composed here rather than stored so the two halves can never drift.
+func (d *Deepgram) listenURL() string { return d.baseURL + listenPath }
 
 // TranscribeURL asks Deepgram to fetch + transcribe the audio/video at audioURL (a presigned S3
 // GET). Returns the flat transcript + diarized segments.
@@ -49,7 +82,7 @@ func (d *Deepgram) TranscribeURL(ctx context.Context, audioURL string) (*Result,
 		return nil, fmt.Errorf("stt: deepgram api key not set")
 	}
 	body, _ := json.Marshal(map[string]string{"url": audioURL})
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, deepgramURL, bytes.NewReader(body))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, d.listenURL(), bytes.NewReader(body))
 	if err != nil {
 		return nil, err
 	}
diff --git a/internal/stt/deepgram_test.go b/internal/stt/deepgram_test.go
index 0b87372..bf8ce98 100644
--- a/internal/stt/deepgram_test.go
+++ b/internal/stt/deepgram_test.go
@@ -36,3 +36,35 @@ func TestParseDeepgram_fallbackText(t *testing.T) {
 		t.Errorf("fallback text = %q", res.Text)
 	}
 }
+
+// The base URL is configurable and the path/query are not: an operator picks a region,
+// not a model or a set of transcription options.
+func TestNewDeepgram_listenURLComposition(t *testing.T) {
+	cases := map[string]string{
+		"":                               DefaultBaseURL,
+		"https://api.eu.deepgram.com":    "https://api.eu.deepgram.com",
+		"https://api.eu.deepgram.com/":   "https://api.eu.deepgram.com",
+		"  https://stt.internal:8443/  ": "https://stt.internal:8443",
+		"http://localhost:9000":          "http://localhost:9000",
+	}
+	for in, wantBase := range cases {
+		d := NewDeepgram("key", in)
+		if d.BaseURL() != wantBase {
+			t.Errorf("NewDeepgram(%q).BaseURL() = %q; want %q", in, d.BaseURL(), wantBase)
+		}
+		want := wantBase + listenPath
+		if got := d.listenURL(); got != want {
+			t.Errorf("NewDeepgram(%q).listenURL() = %q; want %q", in, got, want)
+		}
+	}
+}
+
+// The default must stay exactly what it was before the setting existed, and the query has
+// to survive base-URL substitution — a dropped `diarize` would silently return a
+// transcript with no speaker labels rather than an error.
+func TestNewDeepgram_defaultIsUnchanged(t *testing.T) {
+	const want = "https://api.deepgram.com/v1/listen?model=nova-2&smart_format=true&punctuate=true&diarize=true&utterances=true"
+	if got := NewDeepgram("key", "").listenURL(); got != want {
+		t.Errorf("default listenURL = %q; want %q", got, want)
+	}
+}

From a7500b95bad9e16221017330bc908e2b9466d223 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:34:48 -0400
Subject: [PATCH 23/51] webhook: tell a subscriber when a reminder went out

Reminders were email-only, so an integration could hear that a booking was made,
moved or cancelled but not that the nudge before it had been sent. reminder.send
now enqueues booking.reminder, booking-shaped like its siblings plus hours_before,
which the job payload has always carried: an event type can configure several
reminders, so a subscriber that cannot tell 24h from 1h cannot act on the event.

Fired after the email and only when the email succeeded. The event means "the
attendee has been reminded", so emitting it beside a failed send would say
something untrue, and the job retries, which would deliver it twice for one
reminder. The mirror image also matters: an enqueue failure does NOT fail the job,
because the email has already gone and a retry would send a second one. Logged and
dropped, the trade every webhook enqueue after a committed side effect makes here.

sendReminder's existing early returns are all "no reminder happened" - booking
deleted, no longer confirmed, host has reminder emails off - so none of them
reaches this either. A test pins the suppressed-email case, since "a job ran" and
"someone was reminded" are easy to conflate later.

The payload needs the BOOKING's host_id, not the event type's owner: a rotation or
a reassignment moves it, and Enqueue selects a subscriber's webhooks by that id. The
query gained b.host_id and b.created_at for this and nothing else.

hours_before goes through the same per-webhook field selection as everything else
rather than being bolted onto the envelope, so it appears in the admin field list
and an operator can decline it. It is in defaultFields on the same bargain as the
payment fields: omitted at zero, so every other event's payload is byte-identical to
before, and a webhook created before this event existed is unchanged.

Payment fields are deliberately absent from this event. paymentStatusForWebhook's
mapping lives in the handler package, and a reminder is a time notification; payment
state is what create and cancel are for.

The SPA's event list and field catalog gain the two strings. The embedded build is
not rebuilt here, so the admin UI will not offer booking.reminder until someone runs
pnpm build - the API accepts it now either way.
---
 CHANGELOG.md                              |  11 ++
 docs/ARCHITECTURE.md                      |  19 ++-
 frontend/src/routes/webhooks/+page.svelte |   2 +
 internal/handler/webhook_handler.go       |   2 +-
 internal/webhook/webhook.go               |  15 ++
 internal/worker/reminder_test.go          | 172 ++++++++++++++++++++++
 internal/worker/worker.go                 |  39 ++++-
 7 files changed, 253 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f8b7fb..af232e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,17 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
 ## [Unreleased]
 
 ### Added
+- **`booking.reminder` webhook event.** Reminders were email-only, so an integration had no
+  way to know one had gone out — you could hear about a booking being made, moved or
+  cancelled, but not about the nudge before it. Subscribe to it in Settings → Webhooks.
+
+  The payload is booking-shaped like the other booking events plus `hours_before`, because
+  an event type can configure several reminders and a subscriber needs to know which one
+  fired. It is sent after the email and only when the email succeeded: the event means the
+  attendee has been reminded, and the job retries, so firing it on a failed send would be
+  both untrue and eventually duplicated. A host who has reminder emails switched off sends
+  no reminder, so there is no event either.
+
 - **`STT_BASE_URL`: choose which speech-to-text endpoint transcribes your recordings.**
   The host was hardcoded, so meeting audio always went to the provider's global endpoint —
   a problem if you need it transcribed inside one jurisdiction. The default is unchanged.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 027b104..2012a30 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -745,14 +745,27 @@ as the desired state:
   reset to pending +1 min). Retry **backoff is a fixed two-step: 60s then 5 min**
   (not exponential), `max_attempts` 3. Atomic claim via
   `UPDATE … WHERE status='pending'` + RowsAffected.
-- `internal/webhook`: enqueues `booking.created` / `.cancelled` / `.rescheduled`
-  plus the notetaker events `recording.completed` / `transcript.ready` / `notes.ready`
+- `internal/webhook`: enqueues `booking.created` / `.cancelled` / `.rescheduled` /
+  `.reminder` plus the notetaker events `recording.completed` / `transcript.ready` /
+  `notes.ready`
   (reference payloads — booking-shaped, keyed by id; consumers fetch the artifact body
-  via REST/MCP). There is **no** `booking.reminder` webhook event. Deliveries are signed
+  via REST/MCP). Deliveries are signed
   **HMAC-SHA256**, header `X-Calnode-Signature` (+ `X-Calnode-Event`/`-Delivery`),
   secret stored encrypted. The worker's HTTP client is **SSRF-guarded** (resolves
   DNS, blocks private/loopback/CGNAT/ULA IPs, dials the resolved IP to avoid
   re-resolution) since webhook URLs are user-supplied.
+- **`booking.reminder`** is fired by the `reminder.send` job (`internal/worker`), booking-shaped
+  like its siblings plus **`hours_before`** — an event type can configure several reminders, so
+  the payload has to say which one this is. It carries no payment fields: those come from
+  create/cancel, and `paymentStatusForWebhook`'s mapping lives in the handler package.
+  ⛔ **Fired after the email and only on success**, because the event means "the attendee has
+  been reminded". Emitting it beside a failed send would be untrue, and the job retries — which
+  would deliver it twice for one reminder. Conversely an *enqueue* failure does **not** fail the
+  job: the email has already gone and a retry would send a second one, so it is logged and
+  dropped. `sendReminder`'s early returns (booking deleted, no longer confirmed, host has
+  reminder emails off) are all "no reminder happened", so none of them fires it either.
+  ⚠️ The event needs the **booking's** `host_id`, not the event type's owner — a rotation or a
+  reassignment moves it, and `Enqueue` selects a subscriber's webhooks by that id.
 - **Per-webhook payload fields:** each webhook chooses which fields land in the `data`
   object (`webhooks.fields` JSON, migration 00027) — incl. attendee PII + intake
   answers. NULL ⇒ the original default set (so existing webhooks are unchanged and
diff --git a/frontend/src/routes/webhooks/+page.svelte b/frontend/src/routes/webhooks/+page.svelte
index ed4eb83..0ed317e 100644
--- a/frontend/src/routes/webhooks/+page.svelte
+++ b/frontend/src/routes/webhooks/+page.svelte
@@ -18,6 +18,7 @@
 		'booking.created',
 		'booking.cancelled',
 		'booking.rescheduled',
+		'booking.reminder',
 		'recording.completed',
 		'transcript.ready',
 		'notes.ready'
@@ -37,6 +38,7 @@
 			{ key: 'cancellation_reason', label: 'Cancellation reason' },
 			{ key: 'previous_start_at', label: 'Previous start (reschedule)' },
 			{ key: 'previous_end_at', label: 'Previous end (reschedule)' },
+			{ key: 'hours_before', label: 'Hours before (reminder)' },
 		] },
 		{ group: 'Payment', fields: [
 			{ key: 'payment_status', label: 'Payment status' },
diff --git a/internal/handler/webhook_handler.go b/internal/handler/webhook_handler.go
index 2691c4d..6251f12 100644
--- a/internal/handler/webhook_handler.go
+++ b/internal/handler/webhook_handler.go
@@ -15,7 +15,7 @@ import (
 )
 
 var validWebhookEvents = []string{
-	"booking.created", "booking.cancelled", "booking.rescheduled",
+	"booking.created", "booking.cancelled", "booking.rescheduled", "booking.reminder",
 	"recording.completed", "transcript.ready", "notes.ready",
 }
 
diff --git a/internal/webhook/webhook.go b/internal/webhook/webhook.go
index 850bf94..b725baf 100644
--- a/internal/webhook/webhook.go
+++ b/internal/webhook/webhook.go
@@ -57,6 +57,9 @@ const (
 	FieldPaymentStatus   = "payment_status"
 	FieldAmountPaid      = "amount_paid_cents"
 	FieldCurrency        = "amount_paid_currency"
+	// FieldHoursBefore only ever has a value on booking.reminder, where it says which
+	// configured reminder fired (an event type may have several). Omitted elsewhere.
+	FieldHoursBefore = "hours_before"
 )
 
 // AllFields is every selectable field, in payload order. Used to validate config
@@ -68,16 +71,20 @@ var AllFields = []string{
 	FieldHostID, FieldHostName, FieldHostEmail,
 	FieldAttendeeName, FieldAttendeeEmail, FieldAttendeeTZ, FieldAnswers,
 	FieldPaymentStatus, FieldAmountPaid, FieldCurrency,
+	FieldHoursBefore,
 }
 
 // defaultFields reproduces the original payload (no PII, no answers) so a webhook with no
 // field config (fields IS NULL) keeps its historical shape. Payment fields are included but
 // omitempty, so free bookings are byte-identical to before; only paid bookings gain them.
+// hours_before is the same bargain: it is zero on every event except booking.reminder,
+// which did not exist when a webhook with no field config was created.
 var defaultFields = []string{
 	FieldID, FieldEventTypeSlug, FieldHostID, FieldStartAt, FieldEndAt,
 	FieldStatus, FieldLocation, FieldCancelReason, FieldCreatedAt,
 	FieldPreviousStartAt, FieldPreviousEndAt,
 	FieldPaymentStatus, FieldAmountPaid, FieldCurrency,
+	FieldHoursBefore,
 }
 
 var validField = func() map[string]bool {
@@ -127,6 +134,9 @@ type BookingPayload struct {
 	PaymentStatus      string `json:"payment_status,omitempty"`
 	AmountPaidCents    int    `json:"amount_paid_cents,omitempty"`
 	AmountPaidCurrency string `json:"amount_paid_currency,omitempty"`
+	// HoursBefore is set only on booking.reminder: which of the event type's configured
+	// reminders this delivery is for.
+	HoursBefore int `json:"hours_before,omitempty"`
 }
 
 type Service struct {
@@ -357,6 +367,11 @@ func buildData(bd enrichedBooking, fields []string) map[string]any {
 			out[f] = v
 		} else if f == FieldAmountPaid && bd.core.AmountPaidCents > 0 {
 			out[f] = bd.core.AmountPaidCents
+		} else if f == FieldHoursBefore && bd.core.HoursBefore > 0 {
+			// Same rule as the paid amount: the two numeric fields are omitted at zero
+			// rather than emitted as 0, which on an event that has no reminder attached
+			// would read as "0 hours before".
+			out[f] = bd.core.HoursBefore
 		}
 	}
 	return out
diff --git a/internal/worker/reminder_test.go b/internal/worker/reminder_test.go
index 4b922e6..00148b2 100644
--- a/internal/worker/reminder_test.go
+++ b/internal/worker/reminder_test.go
@@ -2,12 +2,15 @@ package worker_test
 
 import (
 	"context"
+	"encoding/json"
+	"fmt"
 	"log/slog"
 	"net/http"
 	"strings"
 	"testing"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/mailer"
 	"github.com/calnode/calnode/internal/worker"
 )
@@ -226,3 +229,172 @@ func TestWorker_reminderNotFiredBeforeRunAt(t *testing.T) {
 		t.Errorf("job status = %q; want pending", jobStatus)
 	}
 }
+
+// ---------------------------------------------------------------------------
+// reminder.send → booking.reminder webhook
+// ---------------------------------------------------------------------------
+
+// seedReminderBooking creates an event type, a confirmed booking 25h out, its organizer,
+// and a due reminder.send job carrying hoursBefore.
+func seedReminderBooking(t *testing.T, database *db.DB, suffix string, hoursBefore int) {
+	t.Helper()
+	ctx := context.Background()
+	pastRunAt := time.Now().UTC().Add(-time.Second).Format(time.RFC3339)
+	start := time.Now().UTC().Add(25 * time.Hour).Format(time.RFC3339)
+
+	stmts := []struct {
+		sql  string
+		args []any
+	}{
+		{`INSERT INTO event_types (id, user_id, slug, name, duration_minutes) VALUES (?, 'host-01', ?, 'Reminder Meeting', 30)`,
+			[]any{"et-" + suffix, "rem-hook-" + suffix}},
+		{`INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at, status) VALUES (?, ?, 'host-01', ?, ?, 'confirmed')`,
+			[]any{"bk-" + suffix, "et-" + suffix, start, start}},
+		{`INSERT INTO booking_attendees (id, booking_id, name, email, iana_timezone, is_organizer) VALUES (?, ?, 'Alice', 'alice@example.com', 'UTC', 1)`,
+			[]any{"att-" + suffix, "bk-" + suffix}},
+		{`INSERT INTO jobs (id, type, payload, run_at, status, attempts, max_attempts) VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)`,
+			[]any{"job-" + suffix,
+				fmt.Sprintf(`{"booking_id":"bk-%s","hours_before":%d}`, suffix, hoursBefore),
+				pastRunAt}},
+	}
+	for _, s := range stmts {
+		if _, err := database.ExecContext(ctx, s.sql, s.args...); err != nil {
+			t.Fatalf("seed %s: %v", suffix, err)
+		}
+	}
+}
+
+// deliveryPayloadFor returns the single webhook delivery payload for an event.
+func deliveryPayloadFor(t *testing.T, database *db.DB, event string) string {
+	t.Helper()
+	var payload string
+	if err := database.QueryRow(
+		`SELECT payload FROM webhook_deliveries WHERE event = ?`, event).Scan(&payload); err != nil {
+		t.Fatalf("no %s delivery: %v", event, err)
+	}
+	return payload
+}
+
+func TestWorker_reminderFiresBookingReminderWebhook(t *testing.T) {
+	database, svc := setup(t)
+	ctx := context.Background()
+	seedReminderBooking(t, database, "rw1", 24)
+
+	if _, _, err := svc.Create(ctx, "host-01", "https://hook.example.test/x",
+		[]string{"booking.reminder"}); err != nil {
+		t.Fatalf("create webhook: %v", err)
+	}
+
+	w := worker.New(database, svc, slog.Default(),
+		worker.WithMailer(&captureMailer{}), worker.WithHTTPClient(&http.Client{}))
+	w.Poll(ctx)
+
+	payload := deliveryPayloadFor(t, database, "booking.reminder")
+	var env struct {
+		Event string `json:"event"`
+		Data  struct {
+			ID            string `json:"id"`
+			HostID        string `json:"host_id"`
+			Status        string `json:"status"`
+			EventTypeSlug string `json:"event_type_slug"`
+			StartAt       string `json:"start_at"`
+			HoursBefore   int    `json:"hours_before"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(payload), &env); err != nil {
+		t.Fatalf("decode payload %s: %v", payload, err)
+	}
+	if env.Event != "booking.reminder" {
+		t.Errorf("event = %q; want booking.reminder", env.Event)
+	}
+	// Booking-shaped, exactly like the other booking events.
+	if env.Data.ID != "bk-rw1" || env.Data.HostID != "host-01" || env.Data.Status != "confirmed" {
+		t.Errorf("data = %+v; want the booking's own id/host/status", env.Data)
+	}
+	if env.Data.EventTypeSlug != "rem-hook-rw1" || env.Data.StartAt == "" {
+		t.Errorf("data = %+v; want the event type slug and start time", env.Data)
+	}
+	// Plus the one field that makes the event useful: which reminder fired.
+	if env.Data.HoursBefore != 24 {
+		t.Errorf("hours_before = %d; want 24", env.Data.HoursBefore)
+	}
+}
+
+// An event type can have several reminders, so the delivery has to say which one this is.
+func TestWorker_reminderWebhookCarriesTheFiringOffset(t *testing.T) {
+	database, svc := setup(t)
+	ctx := context.Background()
+	seedReminderBooking(t, database, "rw2", 1)
+
+	if _, _, err := svc.Create(ctx, "host-01", "https://hook.example.test/x",
+		[]string{"booking.reminder"}); err != nil {
+		t.Fatalf("create webhook: %v", err)
+	}
+
+	w := worker.New(database, svc, slog.Default(),
+		worker.WithMailer(&captureMailer{}), worker.WithHTTPClient(&http.Client{}))
+	w.Poll(ctx)
+
+	if payload := deliveryPayloadFor(t, database, "booking.reminder"); !strings.Contains(payload, `"hours_before":1`) {
+		t.Errorf("payload = %s; want hours_before 1", payload)
+	}
+}
+
+// A webhook subscribed to other events must not start receiving reminders.
+func TestWorker_reminderWebhookOnlyForSubscribers(t *testing.T) {
+	database, svc := setup(t)
+	ctx := context.Background()
+	seedReminderBooking(t, database, "rw3", 24)
+
+	if _, _, err := svc.Create(ctx, "host-01", "https://hook.example.test/x",
+		[]string{"booking.created", "booking.cancelled"}); err != nil {
+		t.Fatalf("create webhook: %v", err)
+	}
+
+	w := worker.New(database, svc, slog.Default(),
+		worker.WithMailer(&captureMailer{}), worker.WithHTTPClient(&http.Client{}))
+	w.Poll(ctx)
+
+	var n int
+	if err := database.QueryRow(
+		`SELECT COUNT(*) FROM webhook_deliveries WHERE event = 'booking.reminder'`).Scan(&n); err != nil {
+		t.Fatalf("count deliveries: %v", err)
+	}
+	if n != 0 {
+		t.Errorf("deliveries = %d; want 0 for a webhook not subscribed to booking.reminder", n)
+	}
+}
+
+// The host turned reminder emails off, so no reminder happened and there is nothing to
+// announce. The event means "the attendee has been reminded", not "a job ran".
+func TestWorker_noReminderWebhookWhenTheEmailIsSuppressed(t *testing.T) {
+	database, svc := setup(t)
+	ctx := context.Background()
+	seedReminderBooking(t, database, "rw4", 24)
+	if _, err := database.ExecContext(ctx,
+		`UPDATE users SET notify_reminder = 0 WHERE id = 'host-01'`); err != nil {
+		t.Fatalf("disable reminder emails: %v", err)
+	}
+
+	if _, _, err := svc.Create(ctx, "host-01", "https://hook.example.test/x",
+		[]string{"booking.reminder"}); err != nil {
+		t.Fatalf("create webhook: %v", err)
+	}
+
+	m := &captureMailer{}
+	w := worker.New(database, svc, slog.Default(),
+		worker.WithMailer(m), worker.WithHTTPClient(&http.Client{}))
+	w.Poll(ctx)
+
+	if len(m.sent) != 0 {
+		t.Fatalf("sent %d emails; want 0", len(m.sent))
+	}
+	var n int
+	if err := database.QueryRow(
+		`SELECT COUNT(*) FROM webhook_deliveries WHERE event = 'booking.reminder'`).Scan(&n); err != nil {
+		t.Fatalf("count deliveries: %v", err)
+	}
+	if n != 0 {
+		t.Errorf("deliveries = %d; want 0 when no reminder was sent", n)
+	}
+}
diff --git a/internal/worker/worker.go b/internal/worker/worker.go
index ed0ef63..05e9a68 100644
--- a/internal/worker/worker.go
+++ b/internal/worker/worker.go
@@ -265,7 +265,8 @@ func (w *Worker) processJob(ctx context.Context, typ, payload string) error {
 
 func (w *Worker) sendReminder(ctx context.Context, payload string) error {
 	var p struct {
-		BookingID string `json:"booking_id"`
+		BookingID   string `json:"booking_id"`
+		HoursBefore int    `json:"hours_before"`
 	}
 	if err := json.Unmarshal([]byte(payload), &p); err != nil {
 		return fmt.Errorf("worker: reminder: parse payload: %w", err)
@@ -279,15 +280,19 @@ func (w *Worker) sendReminder(ctx context.Context, payload string) error {
 	var startAt, endAt, status string
 	var locVal, msgReminder, subjReminder sql.NullString
 	var notifyReminder int
+	// hostID and createdAt are for the booking.reminder webhook below, not the email:
+	// Enqueue selects a subscriber's webhooks by the BOOKING's host, which is not
+	// necessarily the event type's owner (a rotation or a reassignment moves it).
+	var hostID, createdAt string
 	err := w.db.QueryRowContext(ctx, `
-		SELECT b.status, b.start_at, b.end_at, b.location_value,
+		SELECT b.status, b.start_at, b.end_at, b.location_value, b.host_id, b.created_at,
 		       et.name, et.slug, et.msg_reminder, et.subj_reminder,
 		       u.name, u.email, COALESCE(u.notify_reminder, 1)
 		FROM bookings b
 		JOIN event_types et ON et.id = b.event_type_id
 		JOIN users u ON u.id = et.user_id
 		WHERE b.id = ?`, p.BookingID).
-		Scan(&status, &startAt, &endAt, &locVal,
+		Scan(&status, &startAt, &endAt, &locVal, &hostID, &createdAt,
 			&d.EventTypeName, &d.EventTypeSlug, &msgReminder, &subjReminder,
 			&d.HostName, &d.HostEmail, &notifyReminder)
 	if err == sql.ErrNoRows {
@@ -342,6 +347,34 @@ func (w *Worker) sendReminder(ctx context.Context, payload string) error {
 	if err := mailer.SendReminder(ctx, w.mailer, d); err != nil {
 		return fmt.Errorf("worker: reminder: send: %w", err)
 	}
+
+	// booking.reminder fires AFTER the email and only on success, because the event means
+	// "this booking's attendee has been reminded". Emitting it beside a failed send would
+	// tell a subscriber something untrue, and the job retries, which would then deliver it
+	// twice for one reminder.
+	//
+	// Conversely, an enqueue failure here must NOT fail the job: the email has already
+	// gone, and a retry would send a second one. Logged and dropped, the same trade every
+	// other webhook enqueue in the tree makes after a committed side effect.
+	//
+	// The early returns above are all "no reminder happened" — booking deleted, no longer
+	// confirmed, host has reminder emails off — so none of them fires this either.
+	if w.svc != nil {
+		if err := w.svc.Enqueue(ctx, "booking.reminder", webhook.BookingPayload{
+			ID:            p.BookingID,
+			EventTypeSlug: d.EventTypeSlug,
+			HostID:        hostID,
+			StartAt:       d.StartAt.UTC().Format(time.RFC3339),
+			EndAt:         d.EndAt.UTC().Format(time.RFC3339),
+			Status:        status,
+			LocationValue: d.LocationValue,
+			CreatedAt:     createdAt,
+			HoursBefore:   p.HoursBefore,
+		}); err != nil {
+			w.logger.Error("worker: reminder: enqueue booking.reminder webhook",
+				"error", err, "booking_id", p.BookingID)
+		}
+	}
 	return nil
 }
 

From 0bf2c9ac26200f6dd46b01465b6d355d3e675585 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:38:13 -0400
Subject: [PATCH 24/51] i18n: ship Canadian French as its own locale, not as a
 fallback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A visitor asking for fr-CA got the France copy. fr-CA.json is the first regional
locale here, and it is a file rather than a fallback because the differences are
real rather than cosmetic:

- courriel, not e-mail. The OQLF rejects the France-ism and it reads as foreign.
- reporter / report, not reprogrammer / reprogrammation.
- renseignements personnels, never données personnelles. That is the statutory
  term in Quebec, so it is the one a reader expects to see.
- no space before ! ? ;, where France puts one. The space before : stays.
- conflit d'horaire rather than conflit d'agenda.
- month_short_jul is juill., against juil. in France. CLDR itself disagrees on
  exactly this one abbreviation, which is what TestDateTablesMatchCLDR is for; had
  the file been a copy of fr it would have failed on that line and nothing else.

The 24-hour clock and the day-month date_format are shared with fr. Canadian French
also puts a non-breaking space before $ and %, and no key in the file carries either
today, so that rule is written into ARCHITECTURE §23 rather than applied to nothing.

Generated from fr.json with explicit per-key overrides and verified to have the same
keys, the same key order and the same printf verbs, which is what the three guards
check. Every other value is inherited verbatim, so a later correction to fr does not
silently diverge here.

TestResolve gains four cases, and two of them are the ones that matter: fr and fr-FR
must be unaffected by fr-CA existing, because that is the half that would break
silently for every existing French visitor.

The wording is an unreviewed LLM draft, as every non-English locale in this
repository is. Structure is verified, the copy is not, and the CHANGELOG says so
before anyone markets the language.
---
 CHANGELOG.md                     |  13 +++
 CLAUDE.md                        |   2 +-
 CONTRIBUTING.md                  |   2 +-
 docs/ARCHITECTURE.md             |  13 ++-
 internal/i18n/i18n_test.go       |   7 ++
 internal/i18n/locales/fr-CA.json | 158 +++++++++++++++++++++++++++++++
 6 files changed, 192 insertions(+), 3 deletions(-)
 create mode 100644 internal/i18n/locales/fr-CA.json

diff --git a/CHANGELOG.md b/CHANGELOG.md
index af232e1..dd5ad5d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,19 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
 ## [Unreleased]
 
 ### Added
+- **Canadian French (`fr-CA`) on the booker-facing surfaces.** A visitor whose browser asks
+  for `fr-CA` now gets Canadian French rather than the France copy; `fr` and `fr-FR` are
+  unaffected. It is the first regional locale, and a separate file rather than a fallback
+  because the differences are real: `courriel` rather than `e-mail`, `reporter`/`report`
+  rather than `reprogrammer`, `renseignements personnels` (the Quebec statutory term) rather
+  than `données personnelles`, no space before `!` `?` `;` where France puts one, and CLDR
+  itself spells July `juill.` here against `juil.` in France.
+
+  ⚠️ **The wording is an unreviewed draft**, like every non-English locale in this
+  repository: the structure is verified by the same three guards (same keys, printf-verb
+  parity, date tables cross-checked against CLDR), but no native Canadian French speaker has
+  read the copy. Corrections are welcome and easy to merge — see CONTRIBUTING.
+
 - **`booking.reminder` webhook event.** Reminders were email-only, so an integration had no
   way to know one had gone out — you could hear about a booking being made, moved or
   cancelled, but not about the nudge before it. Subscribe to it in Settings → Webhooks.
diff --git a/CLAUDE.md b/CLAUDE.md
index 0037a37..64c0dce 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -131,7 +131,7 @@ no string plumbing with the Go templates), and admin-authored content (event nam
 descriptions, questions, custom email copy). Locale is resolved per request from
 `Accept-Language` + a `?lang=` override + the operator's fallback setting
 (`internal/handler/i18n.go`), and the booker's locale is stored on the booking so later
-reminders match. Ships `en es fr de it pt nl sv`. Full detail: ARCHITECTURE §23.
+reminders match. Ships `en es fr fr-CA de it pt nl sv`. Full detail: ARCHITECTURE §23.
 
 **Adding a locale = adding `internal/i18n/locales/<code>.json`.** Nothing else. `init()`
 globs the directory; the switcher, the fallback dropdown and the public API payload all read
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 148c9d2..76870aa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -74,7 +74,7 @@ prefer additive, nullable/defaulted columns.
 
 ## Translations
 
-Calnode ships 8 locales (`en es fr de it pt nl sv`) across the booker-facing surfaces:
+Calnode ships 9 locales (`en es fr fr-CA de it pt nl sv`) across the booker-facing surfaces:
 booking page, manage/reschedule page, embed widget, the four emails, and the calendar
 invite. The admin UI and the built-in video room are English-only.
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 2012a30..218a354 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1141,7 +1141,18 @@ LLM summary) — the next build; consent-gated (§8.11/§15 of the PRD).
 
 ## 23. Languages (i18n)
 
-Calnode ships **8 locales**: `en` (source) · `es` · `fr` · `de` · `it` · `pt` · `nl` · `sv`.
+Calnode ships **9 locales**: `en` (source) · `es` · `fr` · `fr-CA` · `de` · `it` · `pt` · `nl` · `sv`.
+
+`fr-CA` is the first **regional** locale, and it is a separate file rather than a fallback
+because the differences are real: `courriel` not `e-mail`, `reporter`/`report` not
+`reprogrammer`/`reprogrammation`, `renseignements personnels` never `données personnelles`
+(the Quebec statutory term), no space before `!` `?` `;` where France puts one, and CLDR
+itself disagrees on one abbreviation — `month_short_jul` is `juill.` in fr-CA and `juil.` in
+fr, which is exactly what `TestDateTablesMatchCLDR` exists to catch. Both keep the 24-hour
+clock and the day-month `date_format`. Currency and percent take a non-breaking space before
+`$` and `%` in Canadian French; no key carries either today, so the rule is recorded here
+rather than applied. A visitor sending `fr-FR` or plain `fr` is unaffected — the matcher
+picks the exact tag first (pinned in `TestResolve`).
 
 ### What is translated, and what is not
 
diff --git a/internal/i18n/i18n_test.go b/internal/i18n/i18n_test.go
index 0d0d9ca..e3afc58 100644
--- a/internal/i18n/i18n_test.go
+++ b/internal/i18n/i18n_test.go
@@ -37,6 +37,13 @@ func TestResolve(t *testing.T) {
 		{"exact es", "es", "", "es"},
 		{"exact en", "en-US,en;q=0.9", "", "en"},
 		{"regional subtag falls back to primary", "es-MX,es;q=0.9", "", "es"},
+		// fr-CA is shipped as its own file, so a Canadian browser gets Canadian French
+		// rather than the France copy — and a French browser is unaffected by its
+		// existence, which is the half that would break silently.
+		{"Canadian French resolves to its own locale", "fr-CA,fr;q=0.9", "", "fr-CA"},
+		{"European French is unaffected by fr-CA", "fr-FR,fr;q=0.9", "", "fr"},
+		{"plain fr is unaffected by fr-CA", "fr", "", "fr"},
+		{"fr-CA can be selected by the ?lang override", "en", "fr-CA", "fr-CA"},
 		{"unsupported language falls back to English", "ja-JP,ja;q=0.9", "", "en"},
 		{"empty header falls back to English", "", "", "en"},
 		{"garbage header falls back to English", "not a real header ;;;", "", "en"},
diff --git a/internal/i18n/locales/fr-CA.json b/internal/i18n/locales/fr-CA.json
new file mode 100644
index 0000000..217600a
--- /dev/null
+++ b/internal/i18n/locales/fr-CA.json
@@ -0,0 +1,158 @@
+{
+  "book_by_chat": "Réserver par chat",
+  "close": "Fermer",
+  "assistant_greeting": "Bonjour! Dites-moi approximativement quand vous souhaitez nous rencontrer, par exemple « mardi après-midi » ou « la semaine prochaine », et je trouverai un créneau. Vous pouvez aussi utiliser le calendrier.",
+  "assistant_input_placeholder": "Indiquez vos disponibilités…",
+  "assistant_input_aria": "Envoyer un message à l'assistant de réservation",
+  "send": "Envoyer",
+  "show_more": "Afficher plus",
+  "show_less": "Afficher moins",
+  "date_picker_aria": "Sélecteur de date",
+  "timezone_aria": "Fuseau horaire",
+  "select_day_hint": "Sélectionnez un jour pour voir les créneaux disponibles.",
+  "back": "Retour",
+  "name_label": "Nom",
+  "name_placeholder": "Votre nom complet",
+  "email_label": "Courriel",
+  "email_placeholder": "vous@exemple.com",
+  "choose_option": "Choisissez une option",
+  "confirm_booking": "Confirmer la réservation",
+  "confirming": "Confirmation…",
+  "booking_confirmed": "Réservation confirmée",
+  "confirmation_email_sent": "Un courriel de confirmation vous a été envoyé.",
+  "required_fields_error": "Veuillez remplir tous les champs obligatoires.",
+  "slot_taken_error": "Ce créneau vient d'être réservé. Veuillez en choisir un autre.",
+  "booking_failed_error": "La réservation a échoué. Veuillez réessayer.",
+  "network_error": "Erreur de connexion. Vérifiez votre connexion internet.",
+  "loading": "Chargement…",
+  "no_available_times": "Aucun créneau disponible.",
+  "slot_taken": "déjà réservé",
+  "all_times_taken": "Tous les horaires de cette journée sont réservés.",
+  "could_not_load_times": "Impossible de charger les créneaux. Veuillez réessayer.",
+  "times_shown_in": "Horaires affichés en ",
+  "payment_received": "Paiement reçu",
+  "payment_confirmed_sub": "Votre réservation est confirmée; un courriel de confirmation va vous parvenir.",
+  "assistant_error": "Désolé, une erreur est survenue. Veuillez utiliser le calendrier ci-dessous.",
+  "assistant_disclosure": "Vous discutez avec un assistant automatisé, pas avec une personne.",
+  "other": "autre",
+  "others": "autres",
+  "list_separator": ", ",
+  "list_conjunction": " et ",
+  "language_switcher_aria": "Langue",
+  "cookie_consent_aria": "Consentement aux cookies",
+  "cookie_text": "Nous utilisons des cookies analytiques pour comprendre l'utilisation de cette page de réservation; ils ne sont activés qu'avec votre accord.",
+  "privacy_policy": "Politique de confidentialité",
+  "decline": "Refuser",
+  "accept": "Accepter",
+  "privacy": "Confidentialité",
+  "terms": "Conditions",
+  "cookie_settings": "Paramètres des cookies",
+  "prev_month_aria": "Mois précédent",
+  "next_month_aria": "Mois suivant",
+  "demo_public_label": "Démo publique",
+  "demo_public_text": "les renseignements saisis ici sont visibles par tous et sont réinitialisés automatiquement. N'y saisissez aucun renseignement personnel.",
+  "demo_view_source": "Voir le code source",
+  "powered_by": "Propulsé par",
+  "duration_min": "%d min",
+  "duration_hour_one": "1 heure",
+  "duration_hours": "%d heures",
+  "duration_hr_min": "%d h %d min",
+  "location_video_meeting": "Visioconférence",
+  "location_phone": "Appel téléphonique",
+  "location_in_person": "En personne",
+  "location_video_call": "Visioconférence",
+  "manage_booking_title": "Gérer la réservation",
+  "link_expired_title": "Lien expiré ou invalide",
+  "link_expired_text": "Ce lien de gestion a expiré ou n'est plus valide. Consultez votre courriel de confirmation pour un lien valide, ou contactez l'organisateur pour en obtenir un nouveau.",
+  "booking_already_cancelled_title": "Réservation déjà annulée",
+  "booking_already_cancelled_text": "Cette réservation a été annulée. Pour réserver un nouveau créneau, rendez-vous sur la page de l'événement.",
+  "scheduled_for": "Prévu le",
+  "reschedule": "Reporter",
+  "cancel_booking": "Annuler la réservation",
+  "select_a_date": "Sélectionnez une date",
+  "pick_day_hint": "Choisissez un jour dans le calendrier.",
+  "confirm_reschedule_question": "Confirmer le report?",
+  "was_label": "Avant",
+  "now_label": "Maintenant",
+  "confirm_reschedule": "Confirmer le report",
+  "rescheduling": "Report en cours…",
+  "cancel_this_booking_question": "Annuler cette réservation?",
+  "cancel_booking_notice": "Cette action est irréversible. Un courriel d'annulation vous sera envoyé, ainsi qu'à l'organisateur.",
+  "reason_optional_label": "Motif (facultatif)",
+  "reason_placeholder": "ex. conflit d'horaire",
+  "yes_cancel_booking": "Oui, annuler la réservation",
+  "cancelling": "Annulation…",
+  "booking_rescheduled_title": "Réservation reportée",
+  "booking_rescheduled_prefix": "Votre réservation a été déplacée au ",
+  "booking_cancelled_title": "Réservation annulée",
+  "booking_cancelled_text": "Votre réservation a été annulée.",
+  "slot_no_longer_available_error": "Ce créneau n'est plus disponible. Veuillez en choisir un autre.",
+  "reschedule_failed_error": "Le report a échoué. Veuillez réessayer.",
+  "already_cancelled_error": "Cette réservation est déjà annulée.",
+  "cancellation_failed_error": "L'annulation a échoué. Veuillez réessayer.",
+  "dow_short_sun": "dim.",
+  "dow_short_mon": "lun.",
+  "dow_short_tue": "mar.",
+  "dow_short_wed": "mer.",
+  "dow_short_thu": "jeu.",
+  "dow_short_fri": "ven.",
+  "dow_short_sat": "sam.",
+  "month_short_jan": "janv.",
+  "month_short_feb": "févr.",
+  "month_short_mar": "mars",
+  "month_short_apr": "avr.",
+  "month_short_may": "mai",
+  "month_short_jun": "juin",
+  "month_short_jul": "juill.",
+  "month_short_aug": "août",
+  "month_short_sep": "sept.",
+  "month_short_oct": "oct.",
+  "month_short_nov": "nov.",
+  "month_short_dec": "déc.",
+  "clock_format": "24h",
+  "date_format": "%[1]s %[2]d %[3]s %[4]d",
+  "email_greeting": "Bonjour %s,",
+  "email_confirmed_lead": "Votre réservation est confirmée.",
+  "email_cancelled_lead": "Votre réservation a été annulée.",
+  "email_rescheduled_lead": "Votre réservation a été reportée.",
+  "email_reminder_lead": "Ceci est un rappel : votre rendez-vous approche.",
+  "email_label_event": "Événement",
+  "email_label_with": "Avec",
+  "email_label_start": "Début",
+  "email_label_end": "Fin",
+  "email_label_when": "Quand",
+  "email_label_location": "Lieu",
+  "email_label_reason": "Motif",
+  "email_label_was": "Avant",
+  "email_label_now": "Maintenant",
+  "email_add_to_calendar": "Ajoutez à votre calendrier :",
+  "email_add_to_calendar_updated": "Ajoutez à votre calendrier (horaire mis à jour) :",
+  "email_calendar_google": "Google Calendar",
+  "email_calendar_outlook": "Outlook",
+  "email_booking_reference": "Référence de la réservation : %s",
+  "email_manage_link_intro": "Pour reporter ou annuler, rendez-vous sur :",
+  "email_manage_link_intro_reschedule": "Pour reporter ou annuler à nouveau, rendez-vous sur :",
+  "email_cancel_link_intro": "Pour annuler, rendez-vous sur :",
+  "email_rebook_intro": "Pour réserver à nouveau, rendez-vous sur :",
+  "email_manage_button": "Gérer la réservation",
+  "email_rebook_button": "Réserver à nouveau",
+  "email_subject_confirmed": "Réservation confirmée : %s",
+  "email_subject_cancelled": "Réservation annulée : %s",
+  "email_subject_rescheduled": "Réservation reportée : %s",
+  "email_subject_reminder": "Rappel : %s approche",
+  "email_booking_with": "Réservation avec %s",
+  "email_manage_this_booking": "Gérer cette réservation :",
+  "calendar_event_summary": "%s avec %s",
+  "calendar_event_booking_id": "Référence de la réservation : %s",
+  "err_booking_limit": "Vous avez déjà atteint le nombre maximum de réservations à venir pour cet événement. Annulez une réservation existante ou attendez qu'elle soit passée avant d'en créer une nouvelle.",
+  "err_email_throttled": "Trop de réservations récentes depuis cette adresse courriel. Veuillez réessayer plus tard.",
+  "err_required_field": "le champ obligatoire %q est manquant",
+  "err_required_checkbox": "%q doit être coché",
+  "err_invalid_option": "option non valide pour %[1]q : %[2]q n'est pas un choix autorisé",
+  "assistant_unavailable": "L'assistant de réservation n'est pas disponible pour le moment. Choisissez un créneau dans le calendrier ci-dessous.",
+  "assistant_trouble": "Désolé, nous rencontrons un problème. Choisissez un créneau dans le calendrier ci-dessous.",
+  "assistant_iteration_cap": "Simplifions les choses : choisissez un créneau dans le calendrier ci-dessous.",
+  "assistant_status_slots": "Vérification des disponibilités…",
+  "assistant_status_book": "Réservation…",
+  "assistant_status_working": "En cours…"
+}

From 5c00506a51f342f599dbd2040f0596468ccf4635 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 00:48:21 -0400
Subject: [PATCH 25/51] test: move knownMigrationCount with the migration this
 branch adds

postgres_test.go asserts the fully-migrated version twice through this constant,
and its own doc comment says it moves with every migration added. This branch adds
one, so it is 59.

Worth knowing for the next person: those two tests skip when
CALNODE_TEST_POSTGRES_DSN is unset, so a migration added and verified on the SQLite
lane alone leaves this red and nothing says so until someone runs the Postgres lane.
---
 internal/db/postgres_test.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/internal/db/postgres_test.go b/internal/db/postgres_test.go
index 3e59614..4e75e69 100644
--- a/internal/db/postgres_test.go
+++ b/internal/db/postgres_test.go
@@ -26,7 +26,7 @@ const postgresDSNEnv = "CALNODE_TEST_POSTGRES_DSN"
 // sanity check on the embedded set, not a property of PostgreSQL, so it moves with
 // every migration added — one named constant rather than the same literal in two
 // assertions, so adding one is a single edit that cannot be half-done.
-const knownMigrationCount = 58
+const knownMigrationCount = 59
 
 // openTestPostgres returns a handle scoped to a schema of its own, created for
 // this test and dropped when it finishes. A schema rather than a database because

From ae3cb5e0a9b14b0110b32dcae1d605fee88f59c2 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 01:02:56 -0400
Subject: [PATCH 26/51] db,config: the tenant root, the workspace column, and
 the policies

Boundary 1 of multi-tenant mode. Migration 00060 in both dirs adds
`workspaces`, a `workspace_id` on all 32 application tables, the composite
uniqueness that was global, and one row-level-security policy per table.
`MULTI_TENANT` / `DATABASE_ADMIN_URL` / `CALNODE_PLATFORM_TOKEN` arrive with a
`Validate` that refuses the five combinations that cannot work.

Numbered 00060, not the packet's 00061: `feat/platform-hooks` is not in this
branch, the 59 existing files are contiguous, and migrations_internal_test.go
asserts target version == file count.

ENABLE / FORCE ROW LEVEL SECURITY is deliberately NOT in the migration. FORCE
applies a policy to the table's owner, and in single-tenant mode DATABASE_URL is
the owner: measured on PostgreSQL 17.11 with a NOBYPASSRLS owner and one row,
ENABLE+FORCE with no binding returns 0 rows, ENABLE alone returns 1, and a
non-owner app role under ENABLE alone already returns 0. A superuser DSN hides
all of it, and the suite's DSN is a superuser, so an unconditional FORCE would
have gone green while blinding every real single-tenant deployment. The policies
stay in the migration as reviewable SQL (a policy is inert while RLS is off,
verified); the two ALTERs move to db.EnableRLS, which runs at boot only under
MULTI_TENANT, on the platform handle, idempotently, and exits 1 on failure.

The column default is COALESCE(current_setting('app.workspace_id', true),
'default') rather than the bare current_setting, which RAISES when unset and
would fail every single-tenant INSERT. It fails closed the other way too: an
unbound multi-tenant write would be written as 'default' and the policy's WITH
CHECK refuses it with 42501 instead of landing it in the wrong tenant.

rls_proof_test.go is the gate. It creates a NOBYPASSRLS calnode_app_<hex> role
per test schema and skips LOUDLY if it cannot, or if the role turns out to
bypass, or owns a table. Unbound reads 0 of 2 and its INSERT is refused with
nothing left in 'default'; bound to ws-a it reads 1, inserts naming no
workspace_id and lands as ws-a, cannot see ws-b, and is refused 42501 when it
names ws-b. Proved failable by stubbing EnableRLS: all four subtests fail.

jobs keeps workspace-free copies of its two partial indexes. It is the one table
worked across tenants, and the worker's claim orders by run_at globally, which a
workspace-leading index cannot serve.

SQLite gets the same columns with a literal default and no foreign key: ADD
COLUMN rejects a REFERENCES column with a non-NULL default outright. Only
idempotency_keys and meeting_consents are rebuilt, for their primary keys; with
one workspace a global unique and a (workspace_id, x) unique admit the same rows.

demo.Reset now holds workspaces back with goose_db_version. Truncating the tenant
root took the 'default' row with it and the re-seed failed on the foreign key.

gofmt -l empty, go vet clean, go test ./... rc=0 on SQLite (28/28) and rc=0 on
PostgreSQL (28/28). Negative control with the password changed to wrong: the new
tests FAIL rather than skip, with "failed SASL auth: FATAL: password
authentication failed for user \"postgres\" (SQLSTATE 28P01)".
---
 PROGRESS.md                                   | 177 ++++++
 cmd/calnode/main.go                           |  42 +-
 internal/config/config.go                     |  82 +++
 internal/config/tenancy_test.go               | 143 +++++
 internal/db/collation_test.go                 |   9 +-
 .../postgres/00060_multi_tenant.sql           | 322 +++++++++++
 .../migrations/sqlite/00060_multi_tenant.sql  | 221 ++++++++
 internal/db/postgres_test.go                  |   2 +-
 internal/db/rls_proof_test.go                 | 325 +++++++++++
 internal/db/tenancy.go                        | 115 ++++
 internal/db/tenancy_test.go                   | 510 ++++++++++++++++++
 internal/demo/demo.go                         |  13 +-
 12 files changed, 1953 insertions(+), 8 deletions(-)
 create mode 100644 internal/config/tenancy_test.go
 create mode 100644 internal/db/migrations/postgres/00060_multi_tenant.sql
 create mode 100644 internal/db/migrations/sqlite/00060_multi_tenant.sql
 create mode 100644 internal/db/rls_proof_test.go
 create mode 100644 internal/db/tenancy.go
 create mode 100644 internal/db/tenancy_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index db9b91f..75cb489 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -346,3 +346,180 @@ password changed to `wrong`: `internal/db` **fails** rather than skipping, with
 `failed SASL auth: FATAL: password authentication failed for user "postgres"
 (SQLSTATE 28P01)` — including `TestPostgres_idleLimitApplied`, the one new test
 whose assertions could conceivably have held without a server.
+
+---
+
+# Multi-tenant mode (`feat/multi-tenant`)
+
+One process, many isolated workspaces. `workspaces` is the tenant root, every
+application table carries a `workspace_id`, and PostgreSQL row-level security —
+not the query author — is what keeps one workspace out of another's rows.
+`MULTI_TENANT` unset must behave exactly as before, on SQLite and on
+single-tenant PostgreSQL. That is a gate, not a wish.
+
+## Boundary 1 — config + schema — DONE
+
+### Migration 00060, not 00061
+
+The packet numbered it 00061 on the assumption that `feat/platform-hooks` had
+landed 00060. It has not: that branch is not in this clone (no `/v1/auth/sso`
+endpoint, no `TRUSTED_PROXY_CIDRS`, no `/metrics`), and the 59 files in each
+directory are contiguous. `migrations_internal_test.go` asserts
+`target version == file count` and names the failure "a gap or a duplicate
+number", so 00061 over 59 files reds an existing gate. 00060 it is;
+`knownMigrationCount` moved 59 → 60 with it.
+
+### ⛔ ENABLE / FORCE ROW LEVEL SECURITY is NOT in the migration, and the reason is measured
+
+D2 puts `ENABLE` + `FORCE` + the policy in the migration. `FORCE` makes a
+table's policy apply to the table's **owner** as well, and in single-tenant mode
+`DATABASE_URL` *is* the owner. Measured against the PostgreSQL 17.11 this branch
+develops on, with a `NOBYPASSRLS` owner role and one row present:
+
+| role | RLS | `app.workspace_id` | rows seen |
+|---|---|---|---|
+| owner (NOBYPASSRLS) | ENABLE + FORCE | unset | **0** |
+| superuser | ENABLE + FORCE | unset | 1 |
+| owner (NOBYPASSRLS) | ENABLE only | unset | 1 |
+| non-owner app role | ENABLE only | unset | **0** |
+
+So an unconditional `FORCE` silently blinds every existing single-tenant
+PostgreSQL deployment whose DSN is not a superuser — and **the suite's own DSN
+is a superuser, so the test lane would have gone green anyway.** Row 4 is the
+other half: `ENABLE` alone already isolates a non-owner role, which is what the
+application role is under D4.
+
+The split that keeps both promises: the **policies** live in the migration,
+where they are reviewable SQL, and a policy on a table whose RLS is not enabled
+is inert (verified, not assumed). The two `ALTER TABLE` lines live in
+`db.EnableRLS`, which runs at boot **only when `MULTI_TENANT` is set**, on the
+**platform handle** (`DATABASE_ADMIN_URL` — the application role cannot run DDL
+in multi-tenant mode at all), is idempotent, and whose failure is
+`os.Exit(1)`: without it every policy is inert and the process would come up
+looking multi-tenant while separating nothing.
+`TestPostgres_rlsIsOffUntilEnabled` pins both halves — off straight after
+migrating, on for all 32 tenant tables and none of the 4 exempt ones after
+`EnableRLS`, twice.
+
+### The column default is `COALESCE(current_setting(…, true), 'default')`
+
+D1 spells it `current_setting('app.workspace_id')`. The bare form **raises** on
+an unset parameter, so it would fail every INSERT in single-tenant mode. The
+`missing_ok` form plus `COALESCE` gives `'default'` when nothing is bound, which
+is what single-tenant wants, and is never reached in multi-tenant mode because
+the handle binds before every statement. It also fails **closed** if a
+multi-tenant statement ever escapes that binding: the row would be written as
+`'default'` and the policy's `WITH CHECK` compares it against an unset parameter
+(NULL, so not true), which refuses the INSERT with SQLSTATE 42501 rather than
+letting it land in the wrong tenant. `rls_proof_test.go` asserts exactly that,
+including that nothing arrives in the default workspace.
+
+### The tenancy proof, and its negative control
+
+`internal/db/rls_proof_test.go` creates a `calnode_app_<hex>` role with
+`NOBYPASSRLS` per test schema, grants it the schema's tables, and opens a handle
+as it. ⛔ It **skips loudly** rather than falling back if the role cannot be
+created, or reports `rolsuper`/`rolbypassrls`, or owns any table in the schema —
+a superuser handle would satisfy every assertion whether the policies existed or
+not. Four subtests, both halves required:
+
+- unbound: `SELECT COUNT(*) FROM users` returns **0** of 2
+- unbound: INSERT refused with **42501**, and **nothing lands in `default`**
+- bound to `ws-a`: sees 1 of 2, reads `a@example.com`, INSERT naming **no**
+  `workspace_id` lands as `ws-a`, `b@example.com` invisible
+- bound to `ws-a`, naming `ws-b` explicitly: refused with **42501**
+
+`set_config(…, false)` is session-scoped, so every subtest pins one `*sql.Conn`
+and writes `$n` directly — statements through a `*sql.Conn` are not rebound.
+
+Proved failable by making `EnableRLS` return early:
+
+```
+--- FAIL: TestPostgres_rlsIsolatesAnUnprivilegedRole/unbound_reads_nothing
+    rls_proof_test.go:178: an unbound session sees 2 of 2 users; want 0 — an unset app.workspace_id must match no row
+--- FAIL: .../unbound_write_is_refused_and_lands_nowhere
+    rls_proof_test.go:187: an unbound INSERT succeeded; the policy's WITH CHECK must refuse it
+--- FAIL: .../bound_reads_and_writes_exactly_one_workspace
+    rls_proof_test.go:215: a session bound to ws-a sees 3 users; want 1
+--- FAIL: .../naming_another_workspace_explicitly_is_refused
+    rls_proof_test.go:261: writing into another workspace succeeded; WITH CHECK must refuse it
+```
+
+### 32 tenant tables, 4 exempt, and a gate against forgetting
+
+`db.TenantTables` / `db.ExemptTables` are the Go copies of the list in the
+migration header, and `TestTenancy_tableListsCoverTheSchema` fails if a base
+table is in neither — so a table added by a later migration has to be
+classified. Exempt: `workspaces` (the root, with its own SELECT-only policy for
+the application role), `crypto_keystore` (one DEK per process, D3),
+`goose_db_version`, `oauth_clients` (dynamic client registration is per client
+*application*; the per-tenant half is `oauth_access_tokens`, which is a tenant
+table).
+
+### SQLite's three forced differences
+
+1. **No `REFERENCES workspaces(id)`.** Measured on modernc.org/sqlite with
+   `foreign_keys=ON`: `ALTER TABLE t ADD COLUMN workspace_id TEXT NOT NULL
+   DEFAULT 'default' REFERENCES ws(id)` is **rejected** — "Cannot add a
+   REFERENCES column with non-NULL default value (1)". Rebuilding all 32 tables
+   to get a constraint whose only payoff is cascade-on-workspace-delete, in an
+   engine that cannot run multi-tenant, is not worth it. The two tables rebuilt
+   below omit it too, so the engine is consistent with itself.
+2. **No RLS, no policies.** Nothing to express them with, which is why
+   `config.Validate` refuses `MULTI_TENANT` without a `postgres://` DSN.
+3. **Only the uniqueness that has to MOVE moves.** `idempotency_keys` and
+   `meeting_consents` are rebuilt (their PRIMARY KEY changes and SQLite cannot
+   ALTER a table constraint); `ux_jobs_type_payload` and `idx_notes_booking` are
+   dropped and recreated (plain indexes need no rebuild). `users(email)`,
+   `event_types(slug)`, `teams(slug)` and `server_settings`' `id = 1` singleton
+   stay exactly as they are: with one workspace, a global unique and a
+   `(workspace_id, x)` unique admit precisely the same rows.
+
+### ⚠️ `jobs` keeps a second, workspace-free copy of each partial index
+
+The packet says every partial index on `bookings` and `jobs` gets `workspace_id`
+prepended. Correct for `bookings` — every query that uses those indexes now
+carries a workspace predicate. **Not** for `jobs`: it is the one table worked
+*across* tenants, and the worker's claim and its crash-recovery reaper (B5) run
+on the platform handle with no workspace predicate, ordered by `run_at` /
+`locked_until` globally. A workspace-leading index cannot serve an ordered global
+scan. So both are prepended as instructed **and** `idx_jobs_pending_global`
+`(run_at)` and `idx_jobs_running_expired_global` `(locked_until)` are added
+alongside. Four small indexes on a table that holds pending work, not history.
+
+### `demo.Reset` had to learn about the tenant root
+
+The Postgres path is one `TRUNCATE … CASCADE` naming every table from
+`pg_tables`, which took `workspaces` with it, and the re-seed's first
+`server_settings` INSERT then failed with SQLSTATE 23503. `workspaces` is now
+held back alongside `goose_db_version`: it is the tenant root, not visitor data,
+and in demo mode it holds exactly one constant row. This was the only pre-existing
+test the migration broke, on either engine.
+
+### Config
+
+`MULTI_TENANT`, `DATABASE_ADMIN_URL`, `CALNODE_PLATFORM_TOKEN`, and a new
+`(*Config).Validate` called from `main` before the database is opened. It is
+separate from `Load` because every optional knob in `Load` deliberately falls
+back on a typo rather than refusing to boot (`PoolFromEnv`); these are not typos.
+Five refusals, each one a combination whose only other outcome is silent:
+a non-`postgres://` `DATABASE_URL`, a missing or non-Postgres
+`DATABASE_ADMIN_URL`, **the two DSNs being equal** (one role means the
+application role owns the tables and every policy is inert against it — the
+misconfiguration hardest to notice, because everything works, including reading
+other tenants' rows), and `DEMO_MODE` (D13: demo mode periodically wipes the
+whole database, which here is every tenant's data).
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+`go test ./...` **rc=0 on SQLite (28/28 packages)** and **rc=0 on PostgreSQL
+(28/28)**.
+
+### Not yet wired (later boundaries, stated so it is not mistaken for done)
+
+`cmd/calnode/main.go` opens the platform handle with a second `db.OpenDB` and
+uses it for `Migrate` + `EnableRLS`; Boundary 2 replaces that pair with
+`db.OpenPair`. The other entry points (`mcp`, `reset-admin`, `rotate-key`,
+`recover-key`) still open one handle from `DATABASE_URL` and are untouched —
+they are single-tenant operator tools today, and B3/B6 decide what they become.
diff --git a/cmd/calnode/main.go b/cmd/calnode/main.go
index 7f94db3..fdaf640 100644
--- a/cmd/calnode/main.go
+++ b/cmd/calnode/main.go
@@ -50,6 +50,14 @@ func main() {
 	}))
 	slog.SetDefault(logger)
 
+	// Before the database is opened: every combination Validate refuses would
+	// otherwise present as a bug somewhere much later — a tenant reading another
+	// tenant's rows, or a demo reset wiping a fleet.
+	if err := cfg.Validate(); err != nil {
+		logger.Error("invalid configuration", "error", err)
+		os.Exit(1)
+	}
+
 	bi := buildinfo.Get()
 	logger.Info("starting calnode", "version", bi.Version, "commit", bi.Commit, "build_time", bi.BuildTime, "dirty", bi.Dirty)
 
@@ -66,12 +74,44 @@ func main() {
 	}
 	defer database.Close()
 
-	if err := database.Migrate(); err != nil {
+	// Migrations and row-level-security enablement are the PLATFORM role's work,
+	// not the application role's. In multi-tenant mode DATABASE_URL is a
+	// NOBYPASSRLS role that does not own the schema and therefore cannot run DDL
+	// at all; DATABASE_ADMIN_URL is the owner. Single-tenant mode has one role and
+	// one handle, so migrator is just database.
+	//
+	// Boundary 2 replaces this pair of opens with db.OpenPair.
+	migrator := database
+	if cfg.MultiTenant {
+		admin, err := db.OpenDB(cfg.DatabaseAdminURL)
+		if err != nil {
+			logger.Error("failed to open the platform database handle", "error", err)
+			os.Exit(1)
+		}
+		defer admin.Close()
+		migrator = admin
+	}
+
+	if err := migrator.Migrate(); err != nil {
 		logger.Error("failed to run migrations", "error", err)
 		os.Exit(1)
 	}
 	logger.Info("database migrations applied")
 
+	// ⛔ Refuse to serve if this fails. Without it every policy created by
+	// migration 00060 is inert, and the process would come up looking multi-tenant
+	// while separating nothing. It is idempotent, so booting twice is fine, and it
+	// is deliberately gated on MULTI_TENANT: FORCE ROW LEVEL SECURITY applies a
+	// policy to the table's owner too, and in single-tenant mode DATABASE_URL is
+	// that owner (see db.EnableRLS).
+	if cfg.MultiTenant {
+		if err := migrator.EnableRLS(context.Background()); err != nil {
+			logger.Error("failed to enable row-level security; refusing to serve", "error", err)
+			os.Exit(1)
+		}
+		logger.Info("row-level security enabled", "tables", len(db.TenantTables))
+	}
+
 	// Open the key vault. devMode allows an ephemeral DEK when no secret is set
 	// (handy for local development); production deployments must set
 	// CALNODE_ENCRYPTION_KEY or the vault will refuse to start.
diff --git a/internal/config/config.go b/internal/config/config.go
index e67de48..5149157 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -1,6 +1,7 @@
 package config
 
 import (
+	"errors"
 	"log/slog"
 	"os"
 	"strconv"
@@ -17,6 +18,32 @@ type Config struct {
 	PublicBaseURL  string // booker-facing host: booking links, emails; defaults to BaseURL
 	LogLevel       slog.Level
 
+	// MultiTenant serves many isolated workspaces from one process: the tenant of
+	// a request is resolved from its Host or from the credential it carries, and
+	// PostgreSQL row-level security — not the query author — is what keeps one
+	// workspace out of another's rows.
+	//
+	// Unset is the default and changes nothing: one workspace with the literal id
+	// "default", row-level security never enabled, SQLite still supported.
+	MultiTenant bool
+
+	// DatabaseAdminURL is the PLATFORM role's DSN: the owner of the schema, with
+	// BYPASSRLS, which runs migrations, the worker's cross-tenant claim loop, the
+	// reconciler's workspace enumeration and the platform API. DatabaseURL is then
+	// the APPLICATION role, which must be NOBYPASSRLS and must not own the tables —
+	// that is the whole of the isolation guarantee, since a role that owns a table
+	// or bypasses RLS is not constrained by its policy.
+	//
+	// Required when MultiTenant is set, ignored otherwise: in single-tenant mode
+	// both handles are the same one.
+	DatabaseAdminURL string
+
+	// PlatformToken authenticates the platform API (workspace provisioning,
+	// export/import, erasure) on the identity host. Empty means the platform API
+	// is not mounted at all — a 404, not a 401, so an instance that does not
+	// provision workspaces does not advertise that it could.
+	PlatformToken string
+
 	// Email / SMTP
 	SMTPHost      string
 	SMTPPort      string
@@ -114,9 +141,64 @@ func Load() *Config {
 	cfg.DemoResetInterval = getDuration("DEMO_RESET_INTERVAL", 30*time.Minute)
 	cfg.DBMaxOpenConns, cfg.DBMaxIdleConns = PoolFromEnv()
 
+	cfg.MultiTenant = getBool("MULTI_TENANT", false)
+	cfg.DatabaseAdminURL = os.Getenv("DATABASE_ADMIN_URL")
+	cfg.PlatformToken = os.Getenv("CALNODE_PLATFORM_TOKEN")
+
 	return cfg
 }
 
+// Validate reports a configuration that cannot work, rather than letting it fail
+// later as something that reads like a bug in the code.
+//
+// It is separate from Load because Load has no error return and every optional
+// knob in it deliberately falls back on a typo rather than refusing to boot
+// (see PoolFromEnv). These are not typos: each one is a combination whose only
+// possible outcome is silent data loss or silent cross-tenant exposure.
+func (c *Config) Validate() error {
+	if !c.MultiTenant {
+		return nil
+	}
+
+	// SQLite has no row-level security, so there is nothing to enforce isolation
+	// with. Refusing is the only honest answer: the alternative is an instance
+	// that looks multi-tenant and separates nothing.
+	if !isPostgresURL(c.DatabaseURL) {
+		return errors.New("MULTI_TENANT requires a postgres:// DATABASE_URL — " +
+			"tenant isolation is PostgreSQL row-level security, which SQLite has no equivalent of")
+	}
+	if c.DatabaseAdminURL == "" {
+		return errors.New("MULTI_TENANT requires DATABASE_ADMIN_URL — " +
+			"the platform role that owns the schema and runs migrations, distinct from the application role in DATABASE_URL")
+	}
+	if !isPostgresURL(c.DatabaseAdminURL) {
+		return errors.New("DATABASE_ADMIN_URL must be a postgres:// DSN")
+	}
+	// Same DSN means one role, which means the application role owns the schema
+	// and every policy is inert against it. This is the misconfiguration that
+	// would be hardest to notice, because everything works — including reading
+	// other tenants' rows.
+	if c.DatabaseAdminURL == c.DatabaseURL {
+		return errors.New("DATABASE_ADMIN_URL must differ from DATABASE_URL — " +
+			"the application role must not own the tables or its row-level-security policies do not apply to it")
+	}
+	// Demo mode wipes and re-seeds the whole database every DemoResetInterval.
+	// Against a multi-tenant database that is every tenant's data.
+	if c.DemoMode {
+		return errors.New("DEMO_MODE and MULTI_TENANT are mutually exclusive — " +
+			"demo mode periodically wipes the entire database")
+	}
+	return nil
+}
+
+// isPostgresURL mirrors the classification internal/db does on the same string.
+// Duplicated rather than imported because db imports config, and one three-line
+// prefix check is a smaller price than a cycle.
+func isPostgresURL(u string) bool {
+	l := strings.ToLower(u)
+	return strings.HasPrefix(l, "postgres://") || strings.HasPrefix(l, "postgresql://")
+}
+
 // Pool defaults. Deliberately modest: one Calnode instance is one small process,
 // and a self-hoster's PostgreSQL is usually sized to match.
 const (
diff --git a/internal/config/tenancy_test.go b/internal/config/tenancy_test.go
new file mode 100644
index 0000000..30dc2f0
--- /dev/null
+++ b/internal/config/tenancy_test.go
@@ -0,0 +1,143 @@
+package config_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/config"
+)
+
+const (
+	appDSN   = "postgres://calnode_app:pw@127.0.0.1:5432/calnode?sslmode=disable"
+	adminDSN = "postgres://calnode_platform:pw@127.0.0.1:5432/calnode?sslmode=disable"
+)
+
+func TestLoad_multiTenantDefaultsOff(t *testing.T) {
+	os.Unsetenv("MULTI_TENANT")
+	os.Unsetenv("DATABASE_ADMIN_URL")
+	os.Unsetenv("CALNODE_PLATFORM_TOKEN")
+
+	cfg := config.Load()
+
+	if cfg.MultiTenant {
+		t.Error("MultiTenant should default to false")
+	}
+	if cfg.DatabaseAdminURL != "" {
+		t.Errorf("DatabaseAdminURL = %q; want empty", cfg.DatabaseAdminURL)
+	}
+	if cfg.PlatformToken != "" {
+		t.Errorf("PlatformToken = %q; want empty", cfg.PlatformToken)
+	}
+	// The default configuration is the one every existing deployment has, so it
+	// has to validate.
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("Validate() on the default configuration: %v", err)
+	}
+}
+
+func TestLoad_multiTenantEnv(t *testing.T) {
+	t.Setenv("MULTI_TENANT", "1")
+	t.Setenv("DATABASE_URL", appDSN)
+	t.Setenv("DATABASE_ADMIN_URL", adminDSN)
+	t.Setenv("CALNODE_PLATFORM_TOKEN", "tok")
+
+	cfg := config.Load()
+
+	if !cfg.MultiTenant {
+		t.Error("MultiTenant = false; want true")
+	}
+	if cfg.DatabaseAdminURL != adminDSN {
+		t.Errorf("DatabaseAdminURL = %q; want %q", cfg.DatabaseAdminURL, adminDSN)
+	}
+	if cfg.PlatformToken != "tok" {
+		t.Errorf("PlatformToken = %q; want tok", cfg.PlatformToken)
+	}
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("Validate() on a well-formed multi-tenant configuration: %v", err)
+	}
+}
+
+// TestValidate_multiTenantRefusals covers every combination that cannot work.
+// Each one is a refusal rather than a warning because its only other outcome is
+// silent: a tenant reading another tenant's rows, or a demo reset wiping a fleet.
+func TestValidate_multiTenantRefusals(t *testing.T) {
+	cases := []struct {
+		name    string
+		mutate  func(*config.Config)
+		wantSub string
+	}{
+		{
+			name:    "sqlite has no row-level security",
+			mutate:  func(c *config.Config) { c.DatabaseURL = "sqlite://./data/calnode.db" },
+			wantSub: "postgres:// DATABASE_URL",
+		},
+		{
+			name:    "no platform DSN",
+			mutate:  func(c *config.Config) { c.DatabaseAdminURL = "" },
+			wantSub: "DATABASE_ADMIN_URL",
+		},
+		{
+			name:    "platform DSN is not postgres",
+			mutate:  func(c *config.Config) { c.DatabaseAdminURL = "sqlite://./data/calnode.db" },
+			wantSub: "must be a postgres:// DSN",
+		},
+		{
+			// The dangerous one: everything works, including reading other
+			// tenants' rows, because a role that owns a table is not
+			// constrained by that table's policy.
+			name:    "one role for both handles",
+			mutate:  func(c *config.Config) { c.DatabaseAdminURL = c.DatabaseURL },
+			wantSub: "must differ from DATABASE_URL",
+		},
+		{
+			name:    "demo mode wipes every tenant",
+			mutate:  func(c *config.Config) { c.DemoMode = true },
+			wantSub: "mutually exclusive",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := &config.Config{
+				MultiTenant:      true,
+				DatabaseURL:      appDSN,
+				DatabaseAdminURL: adminDSN,
+			}
+			tc.mutate(cfg)
+
+			err := cfg.Validate()
+			if err == nil {
+				t.Fatalf("Validate() = nil; want a refusal mentioning %q", tc.wantSub)
+			}
+			if !strings.Contains(err.Error(), tc.wantSub) {
+				t.Errorf("Validate() = %q; want it to mention %q", err, tc.wantSub)
+			}
+		})
+	}
+}
+
+// TestValidate_singleTenantIgnoresTheRest is the byte-identical promise at the
+// config layer: with MULTI_TENANT unset, none of the combinations above is an
+// error, because none of the machinery they guard is running.
+func TestValidate_singleTenantIgnoresTheRest(t *testing.T) {
+	cfg := &config.Config{
+		DatabaseURL:      "sqlite://./data/calnode.db",
+		DatabaseAdminURL: "sqlite://./data/calnode.db",
+		DemoMode:         true,
+	}
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("Validate() = %v; single-tenant mode should not police the multi-tenant knobs", err)
+	}
+}
+
+func TestValidate_postgresqlSchemeAccepted(t *testing.T) {
+	cfg := &config.Config{
+		MultiTenant:      true,
+		DatabaseURL:      "postgresql://app:pw@h/db",
+		DatabaseAdminURL: "postgresql://platform:pw@h/db",
+	}
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("Validate() = %v; postgresql:// is the same engine as postgres://", err)
+	}
+}
diff --git a/internal/db/collation_test.go b/internal/db/collation_test.go
index 6fed8f7..892c977 100644
--- a/internal/db/collation_test.go
+++ b/internal/db/collation_test.go
@@ -32,10 +32,11 @@ import (
 const timestampColumnPredicate = `(c.column_name ~ '_(at|until)$'
 	  OR c.column_name IN ('date', 'start_time', 'end_time'))`
 
-// wantTimestampColumns is the number of columns 00059 altered. A floor, not an
-// equality: the assertion that matters is "every match is C", and a query that
-// silently stopped matching anything would satisfy that vacuously.
-const wantTimestampColumns = 54
+// wantTimestampColumns is the number of columns 00059 altered, plus the two
+// workspaces timestamps 00060 added. A floor, not an equality: the assertion that
+// matters is "every match is C", and a query that silently stopped matching
+// anything would satisfy that vacuously.
+const wantTimestampColumns = 56
 
 func TestPostgres_timestampColumnsCollateC(t *testing.T) {
 	handle := dbtest.RequirePostgres(t)
diff --git a/internal/db/migrations/postgres/00060_multi_tenant.sql b/internal/db/migrations/postgres/00060_multi_tenant.sql
new file mode 100644
index 0000000..4692b46
--- /dev/null
+++ b/internal/db/migrations/postgres/00060_multi_tenant.sql
@@ -0,0 +1,322 @@
+-- +goose Up
+--
+-- Multi-tenant mode: `workspaces` is the tenant root, every application table
+-- gains a `workspace_id`, and a row-level-security policy per table makes the
+-- isolation the database's job rather than the query author's.
+--
+-- ┌── The table list ────────────────────────────────────────────────────────┐
+-- │ 32 TENANT tables (column + FK + policy), in the order they appear below: │
+-- │   api_keys, availability_overrides, availability_rules, booking_answers, │
+-- │   booking_attendees, booking_hosts, booking_manage_tokens, bookings,     │
+-- │   calendar_connections, connection_calendars, event_type_hosts,          │
+-- │   event_type_questions, event_type_reminders, event_types,               │
+-- │   idempotency_keys, invite_tokens, jobs, magic_link_tokens,              │
+-- │   meeting_consents, notes, oauth_access_tokens, oauth_auth_codes,        │
+-- │   recordings, server_settings, sessions, team_members, teams,            │
+-- │   transcripts, users, webhook_deliveries, webhooks, zoom_connections     │
+-- │                                                                          │
+-- │ 4 EXEMPT tables (no workspace_id, no policy):                            │
+-- │   workspaces          — the tenant root itself                          │
+-- │   crypto_keystore     — one DEK per process (ARCHITECTURE §5)           │
+-- │   goose_db_version    — migration bookkeeping                           │
+-- │   oauth_clients       — dynamic client registration is per client APP,   │
+-- │                         not per tenant: one Claude/ChatGPT connector     │
+-- │                         registration serves every workspace it is        │
+-- │                         authorised against.                              │
+-- └──────────────────────────────────────────────────────────────────────────┘
+--
+-- The same two lists live in Go as db.TenantTables / db.ExemptTables, and
+-- TestPostgres_tenantTablesMatchSchema fails if either drifts from what this
+-- file produced — so a table added by a later migration has to be classified,
+-- and cannot be silently left unprotected.
+--
+-- ⚠️ ENABLE / FORCE ROW LEVEL SECURITY is deliberately NOT here. It is applied
+-- by db.EnableRLS at boot, and only when MULTI_TENANT is set. The reason is
+-- measured, not stylistic: FORCE makes the policy apply to the table OWNER too,
+-- and in single-tenant mode DATABASE_URL *is* the owner. A schema migrated with
+-- FORCE and no `app.workspace_id` binding returns 0 rows to its owner for every
+-- SELECT — verified against PostgreSQL 17.11 with a NOBYPASSRLS owner role. A
+-- superuser DSN hides it completely (superusers bypass RLS), which is exactly
+-- the kind of green that proves nothing. A policy on a table whose RLS is not
+-- enabled is inert, also verified, so single-tenant behaviour is unchanged.
+
+CREATE TABLE workspaces (
+    id          TEXT PRIMARY KEY,
+    slug        TEXT NOT NULL UNIQUE,
+    public_host TEXT NOT NULL UNIQUE,
+    region      TEXT NOT NULL DEFAULT '',
+    status      TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended')),
+    created_at  TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') COLLATE "C",
+    updated_at  TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') COLLATE "C"
+);
+
+-- The single-tenant workspace. It has to exist before the ALTERs below, because
+-- each one backfills existing rows with 'default' and then checks the new
+-- foreign key. public_host is empty on purpose: no HTTP request can carry an
+-- empty Host, so the default workspace is unreachable by host resolution and a
+-- multi-tenant instance cannot accidentally route to it.
+INSERT INTO workspaces (id, slug, public_host, region, status)
+VALUES ('default', 'default', '', '', 'active');
+
+-- ── The column (D1) ───────────────────────────────────────────────────────────
+--
+-- COALESCE around current_setting, rather than the bare current_setting the
+-- design note spells: the bare two-argument-less form RAISES on an unset
+-- parameter, so it would fail every INSERT in single-tenant mode. With the
+-- missing_ok form plus COALESCE the column defaults to 'default' when nothing is
+-- bound, which is what single-tenant mode wants, and is never reached in
+-- multi-tenant mode because the handle binds the parameter before every
+-- statement. It also fails CLOSED if a multi-tenant statement ever escapes that
+-- binding: the row would be written as 'default' and the policy's WITH CHECK
+-- compares it against an unset parameter (NULL), which is not true, so the
+-- INSERT is refused with SQLSTATE 42501 rather than landing in the wrong tenant.
+
+ALTER TABLE api_keys              ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE availability_overrides ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE availability_rules    ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE booking_answers       ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE booking_attendees     ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE booking_hosts         ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE booking_manage_tokens ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE bookings              ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE calendar_connections  ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE connection_calendars  ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE event_type_hosts      ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE event_type_questions  ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE event_type_reminders  ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE event_types           ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE idempotency_keys      ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE invite_tokens         ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE jobs                  ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE magic_link_tokens     ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE meeting_consents      ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE notes                 ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE oauth_access_tokens   ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE oauth_auth_codes      ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE recordings            ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE server_settings       ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE sessions              ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE team_members          ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE teams                 ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE transcripts           ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE users                 ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE webhook_deliveries    ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE webhooks              ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+ALTER TABLE zoom_connections      ADD COLUMN workspace_id TEXT NOT NULL DEFAULT COALESCE(current_setting('app.workspace_id', true), 'default') REFERENCES workspaces(id) ON DELETE CASCADE;
+
+-- ── Uniqueness that was global becomes per workspace (D8, D9) ─────────────────
+--
+-- What stays global, and why: api_keys.key_hash, sessions.id,
+-- oauth_access_tokens.token_hash / refresh_hash, oauth_auth_codes.code_hash,
+-- booking_manage_tokens.token_hash, magic_link_tokens.token_hash and
+-- invite_tokens.token_hash are all CREDENTIALS. The tenant of a request that
+-- carries one is resolved FROM it, so the lookup has to succeed before any
+-- workspace is known — a composite key would make that lookup impossible.
+
+-- server_settings keeps its id = 1 singleton per workspace, so the ~40
+-- `WHERE id = 1` call sites need no edit: RLS narrows them to the tenant's row.
+ALTER TABLE server_settings DROP CONSTRAINT server_settings_pkey;
+ALTER TABLE server_settings ADD PRIMARY KEY (workspace_id, id);
+
+ALTER TABLE idempotency_keys DROP CONSTRAINT idempotency_keys_pkey;
+ALTER TABLE idempotency_keys ADD PRIMARY KEY (workspace_id, idempotency_key);
+
+ALTER TABLE meeting_consents DROP CONSTRAINT meeting_consents_pkey;
+ALTER TABLE meeting_consents ADD PRIMARY KEY (workspace_id, room, participant_identity);
+
+ALTER TABLE users DROP CONSTRAINT users_email_key;
+ALTER TABLE users ADD CONSTRAINT users_workspace_id_email_key UNIQUE (workspace_id, email);
+
+ALTER TABLE event_types DROP CONSTRAINT event_types_slug_key;
+ALTER TABLE event_types ADD CONSTRAINT event_types_workspace_id_slug_key UNIQUE (workspace_id, slug);
+
+ALTER TABLE teams DROP CONSTRAINT teams_slug_key;
+ALTER TABLE teams ADD CONSTRAINT teams_workspace_id_slug_key UNIQUE (workspace_id, slug);
+
+DROP INDEX ux_jobs_type_payload;
+CREATE UNIQUE INDEX ux_jobs_type_payload ON jobs (workspace_id, type, payload);
+
+DROP INDEX idx_notes_booking;
+CREATE UNIQUE INDEX idx_notes_booking ON notes (workspace_id, booking_id);
+
+-- The partial indexes on bookings and jobs lead on workspace_id, because every
+-- query that uses them now carries a workspace predicate from the policy.
+DROP INDEX idx_bookings_no_double;
+CREATE UNIQUE INDEX idx_bookings_no_double ON bookings (workspace_id, host_id, start_at)
+    WHERE status <> 'cancelled';
+
+DROP INDEX idx_bookings_host_time;
+CREATE INDEX idx_bookings_host_time ON bookings (workspace_id, host_id, start_at, end_at)
+    WHERE status = 'confirmed';
+
+DROP INDEX idx_jobs_pending;
+CREATE INDEX idx_jobs_pending ON jobs (workspace_id, run_at) WHERE status = 'pending';
+
+DROP INDEX idx_jobs_running_expired;
+CREATE INDEX idx_jobs_running_expired ON jobs (workspace_id, locked_until) WHERE status = 'running';
+
+-- ⚠️ jobs is the one table worked ACROSS tenants: the worker's claim and its
+-- crash-recovery reaper run on the platform handle with no workspace predicate
+-- and order by run_at / locked_until globally. A workspace-leading index cannot
+-- serve an ordered global scan, so the two originals are kept alongside under
+-- _global names. Both pairs are tiny — jobs holds pending work, not history.
+CREATE INDEX idx_jobs_pending_global ON jobs (run_at) WHERE status = 'pending';
+CREATE INDEX idx_jobs_running_expired_global ON jobs (locked_until) WHERE status = 'running';
+
+-- ── The policies (D2) ─────────────────────────────────────────────────────────
+--
+-- One permissive policy per tenant table, covering ALL commands. The
+-- two-argument current_setting returns NULL for an unset parameter, so an
+-- unbound session matches no row — reads return nothing and writes are refused
+-- rather than defaulting to some tenant. The platform handle binds '' for the
+-- same reason: no workspace id is the empty string, so '' matches nothing
+-- either, and a stale value left on a pooled connection cannot leak into a
+-- later statement because every statement sets the parameter itself.
+
+CREATE POLICY api_keys_tenant ON api_keys USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY availability_overrides_tenant ON availability_overrides USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY availability_rules_tenant ON availability_rules USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY booking_answers_tenant ON booking_answers USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY booking_attendees_tenant ON booking_attendees USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY booking_hosts_tenant ON booking_hosts USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY booking_manage_tokens_tenant ON booking_manage_tokens USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY bookings_tenant ON bookings USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY calendar_connections_tenant ON calendar_connections USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY connection_calendars_tenant ON connection_calendars USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY event_type_hosts_tenant ON event_type_hosts USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY event_type_questions_tenant ON event_type_questions USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY event_type_reminders_tenant ON event_type_reminders USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY event_types_tenant ON event_types USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY idempotency_keys_tenant ON idempotency_keys USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY invite_tokens_tenant ON invite_tokens USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY jobs_tenant ON jobs USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY magic_link_tokens_tenant ON magic_link_tokens USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY meeting_consents_tenant ON meeting_consents USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY notes_tenant ON notes USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY oauth_access_tokens_tenant ON oauth_access_tokens USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY oauth_auth_codes_tenant ON oauth_auth_codes USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY recordings_tenant ON recordings USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY server_settings_tenant ON server_settings USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY sessions_tenant ON sessions USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY team_members_tenant ON team_members USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY teams_tenant ON teams USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY transcripts_tenant ON transcripts USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY users_tenant ON users USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY webhook_deliveries_tenant ON webhook_deliveries USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY webhooks_tenant ON webhooks USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+CREATE POLICY zoom_connections_tenant ON zoom_connections USING (workspace_id = current_setting('app.workspace_id', true)) WITH CHECK (workspace_id = current_setting('app.workspace_id', true));
+
+-- workspaces itself is readable by the application role — h.publicURL(), the
+-- suspended check and the host resolver all need it — and writable only by the
+-- platform role, which owns the table and is therefore exempt from this policy.
+CREATE POLICY workspaces_read ON workspaces FOR SELECT USING (true);
+
+-- +goose Down
+DROP POLICY IF EXISTS workspaces_read ON workspaces;
+
+DROP POLICY IF EXISTS zoom_connections_tenant ON zoom_connections;
+DROP POLICY IF EXISTS webhooks_tenant ON webhooks;
+DROP POLICY IF EXISTS webhook_deliveries_tenant ON webhook_deliveries;
+DROP POLICY IF EXISTS users_tenant ON users;
+DROP POLICY IF EXISTS transcripts_tenant ON transcripts;
+DROP POLICY IF EXISTS teams_tenant ON teams;
+DROP POLICY IF EXISTS team_members_tenant ON team_members;
+DROP POLICY IF EXISTS sessions_tenant ON sessions;
+DROP POLICY IF EXISTS server_settings_tenant ON server_settings;
+DROP POLICY IF EXISTS recordings_tenant ON recordings;
+DROP POLICY IF EXISTS oauth_auth_codes_tenant ON oauth_auth_codes;
+DROP POLICY IF EXISTS oauth_access_tokens_tenant ON oauth_access_tokens;
+DROP POLICY IF EXISTS notes_tenant ON notes;
+DROP POLICY IF EXISTS meeting_consents_tenant ON meeting_consents;
+DROP POLICY IF EXISTS magic_link_tokens_tenant ON magic_link_tokens;
+DROP POLICY IF EXISTS jobs_tenant ON jobs;
+DROP POLICY IF EXISTS invite_tokens_tenant ON invite_tokens;
+DROP POLICY IF EXISTS idempotency_keys_tenant ON idempotency_keys;
+DROP POLICY IF EXISTS event_types_tenant ON event_types;
+DROP POLICY IF EXISTS event_type_reminders_tenant ON event_type_reminders;
+DROP POLICY IF EXISTS event_type_questions_tenant ON event_type_questions;
+DROP POLICY IF EXISTS event_type_hosts_tenant ON event_type_hosts;
+DROP POLICY IF EXISTS connection_calendars_tenant ON connection_calendars;
+DROP POLICY IF EXISTS calendar_connections_tenant ON calendar_connections;
+DROP POLICY IF EXISTS bookings_tenant ON bookings;
+DROP POLICY IF EXISTS booking_manage_tokens_tenant ON booking_manage_tokens;
+DROP POLICY IF EXISTS booking_hosts_tenant ON booking_hosts;
+DROP POLICY IF EXISTS booking_attendees_tenant ON booking_attendees;
+DROP POLICY IF EXISTS booking_answers_tenant ON booking_answers;
+DROP POLICY IF EXISTS availability_rules_tenant ON availability_rules;
+DROP POLICY IF EXISTS availability_overrides_tenant ON availability_overrides;
+DROP POLICY IF EXISTS api_keys_tenant ON api_keys;
+
+DROP INDEX IF EXISTS idx_jobs_running_expired_global;
+DROP INDEX IF EXISTS idx_jobs_pending_global;
+
+DROP INDEX idx_jobs_running_expired;
+CREATE INDEX idx_jobs_running_expired ON jobs (locked_until) WHERE status = 'running';
+
+DROP INDEX idx_jobs_pending;
+CREATE INDEX idx_jobs_pending ON jobs (run_at) WHERE status = 'pending';
+
+DROP INDEX idx_bookings_host_time;
+CREATE INDEX idx_bookings_host_time ON bookings (host_id, start_at, end_at) WHERE status = 'confirmed';
+
+DROP INDEX idx_bookings_no_double;
+CREATE UNIQUE INDEX idx_bookings_no_double ON bookings (host_id, start_at) WHERE status <> 'cancelled';
+
+DROP INDEX idx_notes_booking;
+CREATE UNIQUE INDEX idx_notes_booking ON notes (booking_id);
+
+DROP INDEX ux_jobs_type_payload;
+CREATE UNIQUE INDEX ux_jobs_type_payload ON jobs (type, payload);
+
+ALTER TABLE teams DROP CONSTRAINT teams_workspace_id_slug_key;
+ALTER TABLE teams ADD CONSTRAINT teams_slug_key UNIQUE (slug);
+
+ALTER TABLE event_types DROP CONSTRAINT event_types_workspace_id_slug_key;
+ALTER TABLE event_types ADD CONSTRAINT event_types_slug_key UNIQUE (slug);
+
+ALTER TABLE users DROP CONSTRAINT users_workspace_id_email_key;
+ALTER TABLE users ADD CONSTRAINT users_email_key UNIQUE (email);
+
+ALTER TABLE meeting_consents DROP CONSTRAINT meeting_consents_pkey;
+ALTER TABLE meeting_consents ADD PRIMARY KEY (room, participant_identity);
+
+ALTER TABLE idempotency_keys DROP CONSTRAINT idempotency_keys_pkey;
+ALTER TABLE idempotency_keys ADD PRIMARY KEY (idempotency_key);
+
+ALTER TABLE server_settings DROP CONSTRAINT server_settings_pkey;
+ALTER TABLE server_settings ADD PRIMARY KEY (id);
+
+ALTER TABLE zoom_connections      DROP COLUMN workspace_id;
+ALTER TABLE webhooks              DROP COLUMN workspace_id;
+ALTER TABLE webhook_deliveries    DROP COLUMN workspace_id;
+ALTER TABLE users                 DROP COLUMN workspace_id;
+ALTER TABLE transcripts           DROP COLUMN workspace_id;
+ALTER TABLE teams                 DROP COLUMN workspace_id;
+ALTER TABLE team_members          DROP COLUMN workspace_id;
+ALTER TABLE sessions              DROP COLUMN workspace_id;
+ALTER TABLE server_settings       DROP COLUMN workspace_id;
+ALTER TABLE recordings            DROP COLUMN workspace_id;
+ALTER TABLE oauth_auth_codes      DROP COLUMN workspace_id;
+ALTER TABLE oauth_access_tokens   DROP COLUMN workspace_id;
+ALTER TABLE notes                 DROP COLUMN workspace_id;
+ALTER TABLE meeting_consents      DROP COLUMN workspace_id;
+ALTER TABLE magic_link_tokens     DROP COLUMN workspace_id;
+ALTER TABLE jobs                  DROP COLUMN workspace_id;
+ALTER TABLE invite_tokens         DROP COLUMN workspace_id;
+ALTER TABLE idempotency_keys      DROP COLUMN workspace_id;
+ALTER TABLE event_types           DROP COLUMN workspace_id;
+ALTER TABLE event_type_reminders  DROP COLUMN workspace_id;
+ALTER TABLE event_type_questions  DROP COLUMN workspace_id;
+ALTER TABLE event_type_hosts      DROP COLUMN workspace_id;
+ALTER TABLE connection_calendars  DROP COLUMN workspace_id;
+ALTER TABLE calendar_connections  DROP COLUMN workspace_id;
+ALTER TABLE bookings              DROP COLUMN workspace_id;
+ALTER TABLE booking_manage_tokens DROP COLUMN workspace_id;
+ALTER TABLE booking_hosts         DROP COLUMN workspace_id;
+ALTER TABLE booking_attendees     DROP COLUMN workspace_id;
+ALTER TABLE booking_answers       DROP COLUMN workspace_id;
+ALTER TABLE availability_rules    DROP COLUMN workspace_id;
+ALTER TABLE availability_overrides DROP COLUMN workspace_id;
+ALTER TABLE api_keys              DROP COLUMN workspace_id;
+
+DROP TABLE workspaces;
diff --git a/internal/db/migrations/sqlite/00060_multi_tenant.sql b/internal/db/migrations/sqlite/00060_multi_tenant.sql
new file mode 100644
index 0000000..9b9c32e
--- /dev/null
+++ b/internal/db/migrations/sqlite/00060_multi_tenant.sql
@@ -0,0 +1,221 @@
+-- +goose Up
+--
+-- The SQLite half of multi-tenant mode. SQLite CANNOT run multi-tenant —
+-- config.Validate refuses MULTI_TENANT without a postgres:// DSN, because the
+-- isolation guarantee is PostgreSQL row-level security and SQLite has no
+-- equivalent. What this file does is keep the two schemas the same shape, so the
+-- cross-engine comparison test stays meaningful and so no Go call site has to
+-- ask which engine it is on before naming workspace_id.
+--
+-- Three deliberate differences from the Postgres file, all forced by SQLite:
+--
+--  1. No REFERENCES workspaces(id). SQLite rejects
+--     `ADD COLUMN ... NOT NULL DEFAULT 'default' REFERENCES ws(id)` outright —
+--     "Cannot add a REFERENCES column with non-NULL default value (1)", measured
+--     on modernc.org/sqlite with foreign_keys=ON. Rebuilding all 32 tables to
+--     get the constraint would be a large, risky migration whose only payoff is
+--     ON DELETE CASCADE for a workspace delete, and workspace deletes only
+--     happen in multi-tenant mode, i.e. never here. The two tables rebuilt below
+--     omit it too, so the engine is consistent with itself rather than being
+--     half-constrained.
+--  2. No row-level security, and no policies. There is nothing to express them
+--     with.
+--  3. Only the four uniqueness changes that need the constraint MOVED are made.
+--     users(email), event_types(slug), teams(slug) and server_settings' id = 1
+--     singleton stay exactly as they are: with one workspace, a global unique
+--     and a (workspace_id, x) unique admit precisely the same rows, and a
+--     table rebuild of users or event_types to prove that would be four
+--     hundred lines of risk for no behaviour change.
+
+CREATE TABLE workspaces (
+    id          TEXT PRIMARY KEY,
+    slug        TEXT NOT NULL UNIQUE,
+    public_host TEXT NOT NULL UNIQUE,
+    region      TEXT NOT NULL DEFAULT '',
+    status      TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended')),
+    created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+-- public_host is empty on purpose: no HTTP request carries an empty Host, so the
+-- default workspace is unreachable by host resolution.
+INSERT INTO workspaces (id, slug, public_host, region, status)
+VALUES ('default', 'default', '', '', 'active');
+
+-- ── The column (D1) ───────────────────────────────────────────────────────────
+-- A literal 'default' rather than a session setting: SQLite has no
+-- current_setting, and with one workspace there is nothing to resolve.
+
+ALTER TABLE api_keys ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE availability_overrides ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE availability_rules ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE booking_answers ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE booking_attendees ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE booking_hosts ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE booking_manage_tokens ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE bookings ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE calendar_connections ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE connection_calendars ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE event_type_hosts ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE event_type_questions ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE event_type_reminders ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE event_types ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE invite_tokens ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE jobs ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE magic_link_tokens ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE notes ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE oauth_access_tokens ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE oauth_auth_codes ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE recordings ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE server_settings ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE sessions ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE team_members ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE teams ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE transcripts ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE users ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE webhook_deliveries ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE webhooks ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE zoom_connections ADD COLUMN workspace_id TEXT NOT NULL DEFAULT 'default';
+
+-- idempotency_keys and meeting_consents get the column through their rebuild
+-- below, because their PRIMARY KEY is what has to change and SQLite cannot ALTER
+-- a table constraint.
+
+-- ── idempotency_keys: PK (idempotency_key) → (workspace_id, idempotency_key) ──
+CREATE TABLE idempotency_keys_new (
+    workspace_id    TEXT NOT NULL DEFAULT 'default',
+    idempotency_key TEXT NOT NULL,
+    request_hash    TEXT NOT NULL,
+    status_code     INTEGER,        -- NULL while the original request is in flight
+    response_body   TEXT,
+    booking_id      TEXT,
+    created_at      TEXT NOT NULL,
+    PRIMARY KEY (workspace_id, idempotency_key)
+);
+INSERT INTO idempotency_keys_new (idempotency_key, request_hash, status_code, response_body, booking_id, created_at)
+    SELECT idempotency_key, request_hash, status_code, response_body, booking_id, created_at FROM idempotency_keys;
+DROP TABLE idempotency_keys;
+ALTER TABLE idempotency_keys_new RENAME TO idempotency_keys;
+
+-- ── meeting_consents: PK (room, participant_identity) gains workspace_id ──────
+CREATE TABLE meeting_consents_new (
+    workspace_id         TEXT NOT NULL DEFAULT 'default',
+    room                 TEXT NOT NULL,
+    participant_identity TEXT NOT NULL,
+    name                 TEXT NOT NULL DEFAULT '',
+    decision             TEXT NOT NULL DEFAULT 'continue',  -- continue | leave
+    decided_at           TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    PRIMARY KEY (workspace_id, room, participant_identity)
+);
+INSERT INTO meeting_consents_new (room, participant_identity, name, decision, decided_at)
+    SELECT room, participant_identity, name, decision, decided_at FROM meeting_consents;
+DROP TABLE meeting_consents;
+ALTER TABLE meeting_consents_new RENAME TO meeting_consents;
+
+-- ── The two unique indexes, which need no rebuild ─────────────────────────────
+DROP INDEX ux_jobs_type_payload;
+CREATE UNIQUE INDEX ux_jobs_type_payload ON jobs (workspace_id, type, payload);
+
+DROP INDEX idx_notes_booking;
+CREATE UNIQUE INDEX idx_notes_booking ON notes (workspace_id, booking_id);
+
+-- ── The partial indexes on bookings and jobs ──────────────────────────────────
+DROP INDEX idx_bookings_no_double;
+CREATE UNIQUE INDEX idx_bookings_no_double ON bookings (workspace_id, host_id, start_at)
+    WHERE status != 'cancelled';
+
+DROP INDEX idx_bookings_host_time;
+CREATE INDEX idx_bookings_host_time ON bookings (workspace_id, host_id, start_at, end_at)
+    WHERE status = 'confirmed';
+
+DROP INDEX idx_jobs_pending;
+CREATE INDEX idx_jobs_pending ON jobs (workspace_id, run_at) WHERE status = 'pending';
+
+DROP INDEX idx_jobs_running_expired;
+CREATE INDEX idx_jobs_running_expired ON jobs (workspace_id, locked_until) WHERE status = 'running';
+
+-- The worker claims and reaps across tenants on the platform handle, ordered by
+-- run_at / locked_until globally, which a workspace-leading index cannot serve.
+CREATE INDEX idx_jobs_pending_global ON jobs (run_at) WHERE status = 'pending';
+CREATE INDEX idx_jobs_running_expired_global ON jobs (locked_until) WHERE status = 'running';
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_jobs_running_expired_global;
+DROP INDEX IF EXISTS idx_jobs_pending_global;
+
+DROP INDEX idx_jobs_running_expired;
+CREATE INDEX idx_jobs_running_expired ON jobs (locked_until) WHERE status = 'running';
+
+DROP INDEX idx_jobs_pending;
+CREATE INDEX idx_jobs_pending ON jobs (run_at) WHERE status = 'pending';
+
+DROP INDEX idx_bookings_host_time;
+CREATE INDEX idx_bookings_host_time ON bookings (host_id, start_at, end_at) WHERE status = 'confirmed';
+
+DROP INDEX idx_bookings_no_double;
+CREATE UNIQUE INDEX idx_bookings_no_double ON bookings (host_id, start_at) WHERE status != 'cancelled';
+
+DROP INDEX idx_notes_booking;
+CREATE UNIQUE INDEX idx_notes_booking ON notes (booking_id);
+
+DROP INDEX ux_jobs_type_payload;
+CREATE UNIQUE INDEX ux_jobs_type_payload ON jobs (type, payload);
+
+CREATE TABLE meeting_consents_old (
+    room                 TEXT NOT NULL,
+    participant_identity TEXT NOT NULL,
+    name                 TEXT NOT NULL DEFAULT '',
+    decision             TEXT NOT NULL DEFAULT 'continue',
+    decided_at           TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    PRIMARY KEY (room, participant_identity)
+);
+INSERT INTO meeting_consents_old (room, participant_identity, name, decision, decided_at)
+    SELECT room, participant_identity, name, decision, decided_at FROM meeting_consents;
+DROP TABLE meeting_consents;
+ALTER TABLE meeting_consents_old RENAME TO meeting_consents;
+
+CREATE TABLE idempotency_keys_old (
+    idempotency_key TEXT PRIMARY KEY,
+    request_hash    TEXT NOT NULL,
+    status_code     INTEGER,
+    response_body   TEXT,
+    booking_id      TEXT,
+    created_at      TEXT NOT NULL
+);
+INSERT INTO idempotency_keys_old (idempotency_key, request_hash, status_code, response_body, booking_id, created_at)
+    SELECT idempotency_key, request_hash, status_code, response_body, booking_id, created_at FROM idempotency_keys;
+DROP TABLE idempotency_keys;
+ALTER TABLE idempotency_keys_old RENAME TO idempotency_keys;
+
+ALTER TABLE zoom_connections DROP COLUMN workspace_id;
+ALTER TABLE webhooks DROP COLUMN workspace_id;
+ALTER TABLE webhook_deliveries DROP COLUMN workspace_id;
+ALTER TABLE users DROP COLUMN workspace_id;
+ALTER TABLE transcripts DROP COLUMN workspace_id;
+ALTER TABLE teams DROP COLUMN workspace_id;
+ALTER TABLE team_members DROP COLUMN workspace_id;
+ALTER TABLE sessions DROP COLUMN workspace_id;
+ALTER TABLE server_settings DROP COLUMN workspace_id;
+ALTER TABLE recordings DROP COLUMN workspace_id;
+ALTER TABLE oauth_auth_codes DROP COLUMN workspace_id;
+ALTER TABLE oauth_access_tokens DROP COLUMN workspace_id;
+ALTER TABLE notes DROP COLUMN workspace_id;
+ALTER TABLE magic_link_tokens DROP COLUMN workspace_id;
+ALTER TABLE jobs DROP COLUMN workspace_id;
+ALTER TABLE invite_tokens DROP COLUMN workspace_id;
+ALTER TABLE event_types DROP COLUMN workspace_id;
+ALTER TABLE event_type_reminders DROP COLUMN workspace_id;
+ALTER TABLE event_type_questions DROP COLUMN workspace_id;
+ALTER TABLE event_type_hosts DROP COLUMN workspace_id;
+ALTER TABLE connection_calendars DROP COLUMN workspace_id;
+ALTER TABLE calendar_connections DROP COLUMN workspace_id;
+ALTER TABLE bookings DROP COLUMN workspace_id;
+ALTER TABLE booking_manage_tokens DROP COLUMN workspace_id;
+ALTER TABLE booking_hosts DROP COLUMN workspace_id;
+ALTER TABLE booking_attendees DROP COLUMN workspace_id;
+ALTER TABLE booking_answers DROP COLUMN workspace_id;
+ALTER TABLE availability_rules DROP COLUMN workspace_id;
+ALTER TABLE availability_overrides DROP COLUMN workspace_id;
+ALTER TABLE api_keys DROP COLUMN workspace_id;
+
+DROP TABLE workspaces;
diff --git a/internal/db/postgres_test.go b/internal/db/postgres_test.go
index 4e75e69..9a23767 100644
--- a/internal/db/postgres_test.go
+++ b/internal/db/postgres_test.go
@@ -26,7 +26,7 @@ const postgresDSNEnv = "CALNODE_TEST_POSTGRES_DSN"
 // sanity check on the embedded set, not a property of PostgreSQL, so it moves with
 // every migration added — one named constant rather than the same literal in two
 // assertions, so adding one is a single edit that cannot be half-done.
-const knownMigrationCount = 59
+const knownMigrationCount = 60
 
 // openTestPostgres returns a handle scoped to a schema of its own, created for
 // this test and dropped when it finishes. A schema rather than a database because
diff --git a/internal/db/rls_proof_test.go b/internal/db/rls_proof_test.go
new file mode 100644
index 0000000..a932de6
--- /dev/null
+++ b/internal/db/rls_proof_test.go
@@ -0,0 +1,325 @@
+package db_test
+
+import (
+	"context"
+	"crypto/rand"
+	"database/sql"
+	"encoding/hex"
+	"errors"
+	"net/url"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgconn"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// The row-level-security proof.
+//
+// ⛔ A SUPERUSER HANDLE PROVES NOTHING HERE. Superusers bypass row-level security
+// unconditionally, and so does any role with BYPASSRLS, and so does the table's
+// OWNER unless FORCE is set. The suite's DSN is normally the superuser that owns
+// the test schema, so asserting isolation through it would pass whether the
+// policies existed or not. Everything below therefore runs as a role created for
+// the test with NOBYPASSRLS, which owns nothing, and the test SKIPS LOUDLY rather
+// than falling back if such a role cannot be created or turns out to bypass
+// anyway.
+//
+// The two halves are both required. The negative half (an unscoped read sees
+// nothing, an unscoped write is refused) is what the policy is for. The positive
+// half (a scoped read sees its own rows, a scoped write lands in its own
+// workspace with no column named) is what stops the negative half from being
+// satisfied by a database that simply does not work.
+
+// appRole is a non-superuser application role with a handle opened as it.
+type appRole struct {
+	name   string
+	handle *db.DB
+}
+
+// newAppRole creates a NOBYPASSRLS role, grants it the test schema's tables, and
+// returns a handle connected as that role with search_path pointed at the schema.
+//
+// It reads the schema name back from the owner handle rather than taking it as an
+// argument, because dbtest owns that name and nothing else exposes it.
+func newAppRole(t *testing.T, owner *db.DB) *appRole {
+	t.Helper()
+
+	dsn := dbtest.PostgresDSN()
+	if dsn == "" {
+		t.Skipf("%s is not set; the row-level-security proof needs a real server", dbtest.DSNEnv)
+	}
+
+	var schema string
+	if err := owner.QueryRow(`SELECT current_schema()`).Scan(&schema); err != nil {
+		t.Fatalf("read current_schema: %v", err)
+	}
+
+	buf := make([]byte, 8)
+	if _, err := rand.Read(buf); err != nil {
+		t.Fatalf("rand: %v", err)
+	}
+	// The name is hex we generated, so interpolating it into DDL cannot carry a
+	// quote or a keyword. PostgreSQL takes no placeholder for a role name.
+	name := "calnode_app_" + hex.EncodeToString(buf)
+	const password = "rls_proof_pw" // local test role, dropped at the end of the test
+
+	if _, err := owner.Exec(`CREATE ROLE ` + name + ` LOGIN PASSWORD '` + password + `' NOBYPASSRLS`); err != nil {
+		t.Skipf("LOUD SKIP: cannot CREATE ROLE on this server (%v) — the row-level-security proof "+
+			"REQUIRES a NOBYPASSRLS role, and asserting isolation through the suite's own "+
+			"superuser DSN would pass with or without the policies. Point %s at a server where "+
+			"the test role may create roles.", err, dbtest.DSNEnv)
+	}
+	t.Cleanup(func() {
+		// DROP OWNED also revokes the privileges granted below, which DROP ROLE
+		// would otherwise refuse over.
+		if _, err := owner.Exec(`DROP OWNED BY ` + name); err != nil {
+			t.Errorf("drop owned by %s: %v", name, err)
+		}
+		if _, err := owner.Exec(`DROP ROLE ` + name); err != nil {
+			t.Errorf("drop role %s: %v", name, err)
+		}
+	})
+
+	for _, stmt := range []string{
+		`GRANT USAGE ON SCHEMA ` + schema + ` TO ` + name,
+		`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ` + schema + ` TO ` + name,
+		`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ` + schema + ` TO ` + name,
+	} {
+		if _, err := owner.Exec(stmt); err != nil {
+			t.Fatalf("%s: %v", stmt, err)
+		}
+	}
+
+	handle, err := db.OpenDB(appDSN(t, dsn, name, password, schema))
+	if err != nil {
+		t.Fatalf("open as %s: %v", name, err)
+	}
+	t.Cleanup(func() { handle.Close() })
+
+	// Belt and braces against the thing that makes this whole test vacuous.
+	var super, bypass bool
+	if err := handle.QueryRow(
+		`SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`).Scan(&super, &bypass); err != nil {
+		t.Fatalf("read own role attributes: %v", err)
+	}
+	if super || bypass {
+		t.Skipf("LOUD SKIP: the application role reports rolsuper=%v rolbypassrls=%v, so it BYPASSES "+
+			"row-level security and every assertion below would pass vacuously", super, bypass)
+	}
+	if !ownsNothing(t, handle, schema) {
+		t.Skipf("LOUD SKIP: the application role owns tables in %s, and a table's owner is exempt from "+
+			"its own policy unless FORCE is set", schema)
+	}
+
+	return &appRole{name: name, handle: handle}
+}
+
+// ownsNothing reports whether the connected role owns none of the schema's
+// tables. FORCE ROW LEVEL SECURITY covers the owner too, so this is belt and
+// braces rather than the guarantee — but a role that owns the tables is not the
+// role this test means to be.
+func ownsNothing(t *testing.T, handle *db.DB, schema string) bool {
+	t.Helper()
+	var n int
+	if err := handle.QueryRow(
+		`SELECT COUNT(*) FROM pg_tables WHERE schemaname = ? AND tableowner = current_user`,
+		schema).Scan(&n); err != nil {
+		t.Fatalf("count owned tables: %v", err)
+	}
+	return n == 0
+}
+
+// appDSN rewrites the suite's DSN for the application role. pgx forwards
+// unrecognised query parameters as runtime parameters, which is how search_path
+// reaches the session — the same mechanism dbtest uses.
+func appDSN(t *testing.T, dsn, user, password, schema string) string {
+	t.Helper()
+	u, err := url.Parse(dsn)
+	if err != nil {
+		t.Fatalf("parse %s: %v", dbtest.DSNEnv, err)
+	}
+	u.User = url.UserPassword(user, password)
+	q := u.Query()
+	q.Set("search_path", schema)
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+// TestPostgres_rlsIsolatesAnUnprivilegedRole is the gate on migration 00060 plus
+// db.EnableRLS: with the policies live and no workspace bound, the application
+// role can neither read nor write; with one bound, it reads and writes exactly
+// its own workspace.
+func TestPostgres_rlsIsolatesAnUnprivilegedRole(t *testing.T) {
+	owner := dbtest.RequirePostgres(t)
+	ctx := context.Background()
+
+	seedTwoWorkspaces(t, owner)
+	if err := owner.EnableRLS(ctx); err != nil {
+		t.Fatalf("EnableRLS: %v", err)
+	}
+
+	app := newAppRole(t, owner)
+
+	// Positive control on the DATA rather than the policy: the rows exist, so a
+	// zero below is the policy hiding them and not an empty table.
+	if got := ownerCount(t, owner, ""); got != 2 {
+		t.Fatalf("the owner sees %d users; want 2 — the fixture did not land", got)
+	}
+
+	t.Run("unbound reads nothing", func(t *testing.T) {
+		conn := pin(t, app.handle)
+		var n int
+		if err := conn.QueryRowContext(ctx, `SELECT COUNT(*) FROM users`).Scan(&n); err != nil {
+			t.Fatalf("count: %v", err)
+		}
+		if n != 0 {
+			t.Errorf("an unbound session sees %d of 2 users; want 0 — an unset app.workspace_id must match no row", n)
+		}
+	})
+
+	t.Run("unbound write is refused and lands nowhere", func(t *testing.T) {
+		conn := pin(t, app.handle)
+		_, err := conn.ExecContext(ctx,
+			`INSERT INTO users (id, email, name) VALUES ($1, $2, $3)`, "u-unbound", "unbound@example.com", "U")
+		if err == nil {
+			t.Fatal("an unbound INSERT succeeded; the policy's WITH CHECK must refuse it")
+		}
+		var pgErr *pgconn.PgError
+		if !errors.As(err, &pgErr) || pgErr.Code != "42501" {
+			t.Errorf("unbound INSERT failed with %v; want SQLSTATE 42501 (insufficient_privilege, the RLS violation)", err)
+		}
+		// ⛔ The failure mode that matters: the column default is
+		// COALESCE(current_setting(...), 'default'), so a policy that did not
+		// refuse this would have written the row into the DEFAULT workspace.
+		if got := ownerCount(t, owner, db.DefaultWorkspaceID); got != 0 {
+			t.Errorf("%d users landed in the default workspace; the refused INSERT must leave nothing behind", got)
+		}
+		if got := ownerCount(t, owner, ""); got != 2 {
+			t.Errorf("the owner now sees %d users; want the original 2", got)
+		}
+	})
+
+	t.Run("bound reads and writes exactly one workspace", func(t *testing.T) {
+		conn := pin(t, app.handle)
+		if _, err := conn.ExecContext(ctx, `SELECT set_config('app.workspace_id', $1, false)`, "ws-a"); err != nil {
+			t.Fatalf("bind workspace: %v", err)
+		}
+
+		var n int
+		if err := conn.QueryRowContext(ctx, `SELECT COUNT(*) FROM users`).Scan(&n); err != nil {
+			t.Fatalf("count: %v", err)
+		}
+		if n != 1 {
+			t.Errorf("a session bound to ws-a sees %d users; want 1", n)
+		}
+
+		var email string
+		if err := conn.QueryRowContext(ctx, `SELECT email FROM users`).Scan(&email); err != nil {
+			t.Fatalf("read: %v", err)
+		}
+		if email != "a@example.com" {
+			t.Errorf("bound to ws-a, read %q; want a@example.com", email)
+		}
+
+		// No column named, which is D1's whole point: the ~200 INSERT statements
+		// in the tree need no edit.
+		if _, err := conn.ExecContext(ctx,
+			`INSERT INTO users (id, email, name) VALUES ($1, $2, $3)`, "u-a2", "a2@example.com", "A2"); err != nil {
+			t.Fatalf("bound INSERT: %v", err)
+		}
+		var landed string
+		if err := conn.QueryRowContext(ctx,
+			`SELECT workspace_id FROM users WHERE id = $1`, "u-a2").Scan(&landed); err != nil {
+			t.Fatalf("read back the inserted row: %v", err)
+		}
+		if landed != "ws-a" {
+			t.Errorf("the inserted row landed in %q; want ws-a", landed)
+		}
+
+		// And B is still invisible, by the value the fixture put there.
+		var visible int
+		if err := conn.QueryRowContext(ctx,
+			`SELECT COUNT(*) FROM users WHERE email = $1`, "b@example.com").Scan(&visible); err != nil {
+			t.Fatalf("count B's user: %v", err)
+		}
+		if visible != 0 {
+			t.Errorf("bound to ws-a, B's user is visible")
+		}
+	})
+
+	t.Run("naming another workspace explicitly is refused", func(t *testing.T) {
+		conn := pin(t, app.handle)
+		if _, err := conn.ExecContext(ctx, `SELECT set_config('app.workspace_id', $1, false)`, "ws-a"); err != nil {
+			t.Fatalf("bind workspace: %v", err)
+		}
+		_, err := conn.ExecContext(ctx,
+			`INSERT INTO users (id, email, name, workspace_id) VALUES ($1, $2, $3, $4)`,
+			"u-cross", "cross@example.com", "X", "ws-b")
+		if err == nil {
+			t.Fatal("writing into another workspace succeeded; WITH CHECK must refuse it")
+		}
+		var pgErr *pgconn.PgError
+		if !errors.As(err, &pgErr) || pgErr.Code != "42501" {
+			t.Errorf("cross-workspace INSERT failed with %v; want SQLSTATE 42501", err)
+		}
+	})
+}
+
+// seedTwoWorkspaces writes one workspace and one user each for ws-a and ws-b
+// through the owner handle, naming workspace_id explicitly because the owner
+// binds nothing.
+func seedTwoWorkspaces(t *testing.T, owner *db.DB) {
+	t.Helper()
+	for _, ws := range []string{"ws-a", "ws-b"} {
+		if _, err := owner.Exec(
+			`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', 'active')`,
+			ws, ws, ws+".example.com"); err != nil {
+			t.Fatalf("seed workspace %s: %v", ws, err)
+		}
+	}
+	for _, row := range []struct{ id, email, ws string }{
+		{"u-a", "a@example.com", "ws-a"},
+		{"u-b", "b@example.com", "ws-b"},
+	} {
+		if _, err := owner.Exec(
+			`INSERT INTO users (id, email, name, workspace_id) VALUES (?, ?, ?, ?)`,
+			row.id, row.email, row.id, row.ws); err != nil {
+			t.Fatalf("seed user %s: %v", row.id, err)
+		}
+	}
+}
+
+// ownerCount counts users through the owner handle, which is exempt from the
+// policy, optionally narrowed to one workspace. An empty workspace means all.
+func ownerCount(t *testing.T, owner *db.DB, workspace string) int {
+	t.Helper()
+	var n int
+	var err error
+	if workspace == "" {
+		err = owner.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&n)
+	} else {
+		err = owner.QueryRow(`SELECT COUNT(*) FROM users WHERE workspace_id = ?`, workspace).Scan(&n)
+	}
+	if err != nil {
+		t.Fatalf("count through the owner handle: %v", err)
+	}
+	return n
+}
+
+// pin takes one connection out of the pool and keeps it for the caller.
+//
+// set_config(..., false) is SESSION scoped, so the statements that depend on it
+// have to run on the same connection. Statements issued through a *sql.Conn are
+// NOT rebound by the wrapper, so everything here is written in PostgreSQL's own
+// $n form.
+func pin(t *testing.T, handle *db.DB) *sql.Conn {
+	t.Helper()
+	conn, err := handle.Conn(context.Background())
+	if err != nil {
+		t.Fatalf("acquire connection: %v", err)
+	}
+	t.Cleanup(func() { conn.Close() })
+	return conn
+}
diff --git a/internal/db/tenancy.go b/internal/db/tenancy.go
new file mode 100644
index 0000000..88f3351
--- /dev/null
+++ b/internal/db/tenancy.go
@@ -0,0 +1,115 @@
+package db
+
+import (
+	"context"
+	"fmt"
+)
+
+// DefaultWorkspaceID is the tenant every row belongs to when MULTI_TENANT is
+// unset. It is a literal rather than a generated id so that a single-tenant
+// database migrated by 00060 reads the same on every machine, and so the SQLite
+// column default can be a constant.
+const DefaultWorkspaceID = "default"
+
+// WorkspaceSetting is the PostgreSQL session parameter a tenant handle binds
+// before every statement. The row-level-security policies compare
+// workspace_id against it, and its two-argument current_setting form returns
+// NULL when it has never been set — so an unbound session matches no row.
+const WorkspaceSetting = "app.workspace_id"
+
+// TenantTables lists every table that carries a workspace_id and a
+// row-level-security policy. It is the Go copy of the list in the header of
+// migration 00060, and TestTenancy_tableListsCoverTheSchema fails if either side
+// drifts: a table added by a later migration must be classified here or in
+// ExemptTables, so "nobody remembered to protect it" is not a possible outcome.
+//
+// Sorted, because the migration's ALTER and CREATE POLICY blocks are sorted and
+// a reader diffing the two should not have to reorder one of them first.
+var TenantTables = []string{
+	"api_keys",
+	"availability_overrides",
+	"availability_rules",
+	"booking_answers",
+	"booking_attendees",
+	"booking_hosts",
+	"booking_manage_tokens",
+	"bookings",
+	"calendar_connections",
+	"connection_calendars",
+	"event_type_hosts",
+	"event_type_questions",
+	"event_type_reminders",
+	"event_types",
+	"idempotency_keys",
+	"invite_tokens",
+	"jobs",
+	"magic_link_tokens",
+	"meeting_consents",
+	"notes",
+	"oauth_access_tokens",
+	"oauth_auth_codes",
+	"recordings",
+	"server_settings",
+	"sessions",
+	"team_members",
+	"teams",
+	"transcripts",
+	"users",
+	"webhook_deliveries",
+	"webhooks",
+	"zoom_connections",
+}
+
+// ExemptTables lists the tables that deliberately have no workspace_id.
+//
+//   - workspaces is the tenant root. It carries its own SELECT-only policy for
+//     the application role instead: the host resolver, the suspended check and
+//     publicURL all read it, and only the platform role writes it.
+//   - crypto_keystore holds the wrapped DEK, and there is one DEK per process
+//     (ARCHITECTURE §5). Per-tenant DEKs are a later hardening.
+//   - goose_db_version is migration bookkeeping.
+//   - oauth_clients is dynamic client registration, which is per client
+//     APPLICATION rather than per tenant: one connector registration serves
+//     every workspace it is later authorised against, and the grant that IS
+//     per-tenant lives in oauth_access_tokens, which is a tenant table.
+var ExemptTables = []string{
+	"crypto_keystore",
+	"goose_db_version",
+	"oauth_clients",
+	"workspaces",
+}
+
+// EnableRLS turns row-level security on, and forces it, for every tenant table.
+// It is idempotent, so it can run on every boot, and it is a no-op on SQLite,
+// which has no row-level security to enable.
+//
+// This is deliberately NOT part of migration 00060. FORCE ROW LEVEL SECURITY
+// makes a table's policy apply to its OWNER as well, and in single-tenant mode
+// DATABASE_URL is the owner: a schema migrated with FORCE and no
+// app.workspace_id binding returns zero rows to its owner for every SELECT.
+// Measured against PostgreSQL 17.11 with a NOBYPASSRLS owner role — and hidden
+// entirely by a superuser DSN, since superusers bypass RLS, which is the shape
+// of green that proves nothing. Gating the two ALTERs on MULTI_TENANT keeps the
+// promise that a single-tenant database behaves exactly as it did before.
+//
+// The policies themselves live in the migration, where they are reviewable SQL.
+// A policy on a table whose row-level security is not enabled is inert, so
+// creating them unconditionally costs a single-tenant instance nothing.
+//
+// Table names are interpolated into the DDL because PostgreSQL takes no
+// placeholder for an identifier. They come from TenantTables, a committed
+// constant list, never from input.
+func (h *DB) EnableRLS(ctx context.Context) error {
+	if h.dialect != DialectPostgres {
+		return nil
+	}
+	for _, table := range TenantTables {
+		if _, err := h.DB.ExecContext(ctx, `ALTER TABLE `+table+` ENABLE ROW LEVEL SECURITY`); err != nil {
+			return fmt.Errorf("enable row level security on %s: %w", table, err)
+		}
+		if _, err := h.DB.ExecContext(ctx, `ALTER TABLE `+table+` FORCE ROW LEVEL SECURITY`); err != nil {
+			return fmt.Errorf("force row level security on %s: %w", table, err)
+		}
+	}
+	return nil
+}
diff --git a/internal/db/tenancy_test.go b/internal/db/tenancy_test.go
new file mode 100644
index 0000000..49b9c6a
--- /dev/null
+++ b/internal/db/tenancy_test.go
@@ -0,0 +1,510 @@
+package db_test
+
+import (
+	"context"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// These tests hold migration 00060: the tenant column, its foreign key, the
+// per-table policy, and the classification of every table as tenant or exempt.
+//
+// The structural assertions read information_schema and pg_catalog rather than
+// the migration file, so they describe what the database ended up with. What
+// they deliberately do NOT prove is that the policies isolate anything: the test
+// DSN is a superuser, and superusers bypass row-level security, so a behavioural
+// assertion here would pass with or without the policies. That proof needs a
+// NOBYPASSRLS application role, which arrives with the handle work in Boundary 2.
+
+// TestTenancy_tableListsCoverTheSchema is the drift gate. A table added by a
+// later migration has to be classified, so "nobody remembered to give it a
+// workspace_id" cannot happen quietly.
+func TestTenancy_tableListsCoverTheSchema(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	rows, err := handle.Query(
+		`SELECT table_name FROM information_schema.tables
+		 WHERE table_schema = current_schema() AND table_type = 'BASE TABLE'
+		 ORDER BY table_name`)
+	if err != nil {
+		t.Fatalf("list tables: %v", err)
+	}
+	live := scanStrings(t, rows)
+
+	if len(live) < 30 {
+		t.Fatalf("only %d tables in the schema; the comparison would prove nothing", len(live))
+	}
+
+	classified := append(slices.Clone(db.TenantTables), db.ExemptTables...)
+	slices.Sort(classified)
+
+	for _, table := range live {
+		if !slices.Contains(classified, table) {
+			t.Errorf("table %q is in neither db.TenantTables nor db.ExemptTables — classify it (and give it a workspace_id if it is a tenant table)", table)
+		}
+	}
+	for _, table := range classified {
+		if !slices.Contains(live, table) {
+			t.Errorf("table %q is classified in internal/db but does not exist in the migrated schema", table)
+		}
+	}
+	if got, want := len(classified), len(live); got != want {
+		t.Errorf("classified %d tables, schema has %d", got, want)
+	}
+	t.Logf("classified %d tables: %d tenant, %d exempt", len(live), len(db.TenantTables), len(db.ExemptTables))
+}
+
+// TestPostgres_tenantColumnShape asserts D1 for every tenant table at once: the
+// column exists, is TEXT, is NOT NULL, and defaults from the session setting.
+func TestPostgres_tenantColumnShape(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	rows, err := handle.Query(
+		`SELECT table_name, data_type, is_nullable, COALESCE(column_default, '')
+		 FROM information_schema.columns
+		 WHERE table_schema = current_schema() AND column_name = 'workspace_id'
+		 ORDER BY table_name`)
+	if err != nil {
+		t.Fatalf("read columns: %v", err)
+	}
+	defer rows.Close()
+
+	seen := map[string]bool{}
+	for rows.Next() {
+		var table, dataType, nullable, def string
+		if err := rows.Scan(&table, &dataType, &nullable, &def); err != nil {
+			t.Fatalf("scan: %v", err)
+		}
+		seen[table] = true
+
+		if !slices.Contains(db.TenantTables, table) {
+			t.Errorf("%s has a workspace_id column but is not in db.TenantTables", table)
+		}
+		if dataType != "text" {
+			t.Errorf("%s.workspace_id is %s; want text", table, dataType)
+		}
+		if nullable != "NO" {
+			t.Errorf("%s.workspace_id is nullable", table)
+		}
+		// The setting has to be named in the default, or a statement that omits
+		// the column would land in the wrong tenant rather than being refused.
+		if !strings.Contains(def, db.WorkspaceSetting) {
+			t.Errorf("%s.workspace_id default %q does not read %s", table, def, db.WorkspaceSetting)
+		}
+		// ⚠️ The missing_ok form matters: the bare current_setting RAISES on an
+		// unset parameter, which would fail every INSERT in single-tenant mode.
+		if !strings.Contains(def, "true") {
+			t.Errorf("%s.workspace_id default %q does not use the missing_ok form of current_setting", table, def)
+		}
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("iterate: %v", err)
+	}
+
+	for _, table := range db.TenantTables {
+		if !seen[table] {
+			t.Errorf("tenant table %s has no workspace_id column", table)
+		}
+	}
+	t.Logf("checked workspace_id on %d tables", len(seen))
+}
+
+// TestPostgres_exemptTablesHaveNoTenantColumn is the other half: an exempt table
+// that quietly grew a workspace_id would be a table with a tenant column and no
+// policy, which is worse than either.
+func TestPostgres_exemptTablesHaveNoTenantColumn(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	for _, table := range db.ExemptTables {
+		var n int
+		err := handle.QueryRow(
+			`SELECT COUNT(*) FROM information_schema.columns
+			 WHERE table_schema = current_schema() AND table_name = ? AND column_name = 'workspace_id'`,
+			table).Scan(&n)
+		if err != nil {
+			t.Fatalf("count columns of %s: %v", table, err)
+		}
+		if n != 0 {
+			t.Errorf("exempt table %s has a workspace_id column", table)
+		}
+	}
+}
+
+// TestPostgres_tenantForeignKeys asserts the FK to workspaces(id) with ON DELETE
+// CASCADE, which is what makes a workspace delete (D12) remove its rows rather
+// than orphan them.
+func TestPostgres_tenantForeignKeys(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	rows, err := handle.Query(
+		`SELECT c.relname, con.confdeltype
+		 FROM pg_constraint con
+		 JOIN pg_class c ON c.oid = con.conrelid
+		 JOIN pg_class f ON f.oid = con.confrelid
+		 JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = con.conkey[1]
+		 WHERE con.contype = 'f'
+		   AND c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = current_schema())
+		   AND a.attname = 'workspace_id'
+		   AND f.relname = 'workspaces'
+		   AND array_length(con.conkey, 1) = 1
+		 ORDER BY c.relname`)
+	if err != nil {
+		t.Fatalf("read foreign keys: %v", err)
+	}
+	defer rows.Close()
+
+	found := map[string]string{}
+	for rows.Next() {
+		var table, deleteRule string
+		if err := rows.Scan(&table, &deleteRule); err != nil {
+			t.Fatalf("scan: %v", err)
+		}
+		found[table] = deleteRule
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("iterate: %v", err)
+	}
+
+	for _, table := range db.TenantTables {
+		rule, ok := found[table]
+		if !ok {
+			t.Errorf("%s.workspace_id has no foreign key to workspaces(id)", table)
+			continue
+		}
+		if rule != "c" { // 'c' is CASCADE in pg_constraint.confdeltype
+			t.Errorf("%s.workspace_id foreign key delete rule is %q; want CASCADE", table, rule)
+		}
+	}
+	t.Logf("checked %d cascading foreign keys to workspaces(id)", len(found))
+}
+
+// TestPostgres_exactlyOnePolicyPerTenantTable asserts D2's policy half. Exactly
+// one, because policies are permissive and OR together: a second one is a hole,
+// not a redundancy.
+func TestPostgres_exactlyOnePolicyPerTenantTable(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	rows, err := handle.Query(
+		`SELECT tablename, policyname, cmd, COALESCE(qual, ''), COALESCE(with_check, '')
+		 FROM pg_policies WHERE schemaname = current_schema()
+		 ORDER BY tablename, policyname`)
+	if err != nil {
+		t.Fatalf("read pg_policies: %v", err)
+	}
+	defer rows.Close()
+
+	type policy struct{ name, cmd, using, check string }
+	byTable := map[string][]policy{}
+	for rows.Next() {
+		var table string
+		var p policy
+		if err := rows.Scan(&table, &p.name, &p.cmd, &p.using, &p.check); err != nil {
+			t.Fatalf("scan: %v", err)
+		}
+		byTable[table] = append(byTable[table], p)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("iterate: %v", err)
+	}
+
+	for _, table := range db.TenantTables {
+		got := byTable[table]
+		if len(got) != 1 {
+			t.Errorf("%s has %d policies; want exactly 1 (permissive policies OR together, so a second one is a hole)", table, len(got))
+			continue
+		}
+		p := got[0]
+		if want := table + "_tenant"; p.name != want {
+			t.Errorf("%s policy is named %q; want %q", table, p.name, want)
+		}
+		if p.cmd != "ALL" {
+			t.Errorf("%s policy covers %q; want ALL", table, p.cmd)
+		}
+		for label, expr := range map[string]string{"USING": p.using, "WITH CHECK": p.check} {
+			if !strings.Contains(expr, db.WorkspaceSetting) {
+				t.Errorf("%s policy %s clause %q does not read %s", table, label, expr, db.WorkspaceSetting)
+			}
+		}
+	}
+
+	// workspaces carries a SELECT-only policy so the application role can resolve
+	// a host and read a status without being able to write the tenant root.
+	ws := byTable["workspaces"]
+	if len(ws) != 1 {
+		t.Fatalf("workspaces has %d policies; want exactly 1", len(ws))
+	}
+	if ws[0].cmd != "SELECT" {
+		t.Errorf("workspaces policy covers %q; want SELECT", ws[0].cmd)
+	}
+	if ws[0].check != "" {
+		t.Errorf("workspaces policy has a WITH CHECK (%q); a SELECT policy that could admit a write is not what was intended", ws[0].check)
+	}
+
+	for _, table := range []string{"crypto_keystore", "goose_db_version", "oauth_clients"} {
+		if n := len(byTable[table]); n != 0 {
+			t.Errorf("exempt table %s has %d policies; want 0", table, n)
+		}
+	}
+}
+
+// TestPostgres_rlsIsOffUntilEnabled is the single-tenant promise, held as an
+// assertion rather than a comment: migrating alone must not change what an
+// existing PostgreSQL deployment can see.
+//
+// ⛔ The reason this is not in the migration: FORCE ROW LEVEL SECURITY applies a
+// policy to the table's OWNER too, and in single-tenant mode DATABASE_URL is the
+// owner. Measured on PostgreSQL 17.11 with a NOBYPASSRLS owner role, a schema
+// migrated with FORCE and no app.workspace_id binding returns 0 rows for every
+// SELECT. A superuser DSN hides that completely.
+func TestPostgres_rlsIsOffUntilEnabled(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	before := rlsFlags(t, handle)
+	for _, table := range db.TenantTables {
+		f, ok := before[table]
+		if !ok {
+			t.Fatalf("%s missing from pg_class", table)
+		}
+		if f.enabled || f.forced {
+			t.Errorf("%s has row-level security enabled straight after migrating (enabled=%v forced=%v); "+
+				"single-tenant PostgreSQL must be unaffected by 00060", table, f.enabled, f.forced)
+		}
+	}
+
+	ctx := context.Background()
+	if err := handle.EnableRLS(ctx); err != nil {
+		t.Fatalf("EnableRLS: %v", err)
+	}
+	// Twice, because it runs on every boot.
+	if err := handle.EnableRLS(ctx); err != nil {
+		t.Fatalf("EnableRLS (second call): %v", err)
+	}
+
+	after := rlsFlags(t, handle)
+	for _, table := range db.TenantTables {
+		f := after[table]
+		if !f.enabled || !f.forced {
+			t.Errorf("%s after EnableRLS: enabled=%v forced=%v; want both true", table, f.enabled, f.forced)
+		}
+	}
+	for _, table := range db.ExemptTables {
+		if f := after[table]; f.enabled || f.forced {
+			t.Errorf("exempt table %s had row-level security enabled (enabled=%v forced=%v)", table, f.enabled, f.forced)
+		}
+	}
+	t.Logf("EnableRLS turned on %d tenant tables and left %d exempt ones alone", len(db.TenantTables), len(db.ExemptTables))
+}
+
+// TestSQLite_enableRLSIsANoOp: the same call on the engine that has no row-level
+// security must not error, so boot code needs no dialect branch.
+func TestSQLite_enableRLSIsANoOp(t *testing.T) {
+	if dbtest.PostgresDSN() != "" {
+		t.Skip("this case is about the SQLite path; the suite is pointed at PostgreSQL")
+	}
+	handle := dbtest.Open(t)
+	if err := handle.EnableRLS(context.Background()); err != nil {
+		t.Fatalf("EnableRLS on SQLite: %v", err)
+	}
+}
+
+// TestPostgres_compositeUniqueness asserts D8 and D9: what became per-workspace,
+// and what deliberately stayed global.
+func TestPostgres_compositeUniqueness(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+
+	rows, err := handle.Query(
+		`SELECT indexname, indexdef FROM pg_indexes WHERE schemaname = current_schema()`)
+	if err != nil {
+		t.Fatalf("read pg_indexes: %v", err)
+	}
+	defs := map[string]string{}
+	func() {
+		defer rows.Close()
+		for rows.Next() {
+			var name, def string
+			if err := rows.Scan(&name, &def); err != nil {
+				t.Fatalf("scan index: %v", err)
+			}
+			defs[name] = def
+		}
+		if err := rows.Err(); err != nil {
+			t.Fatalf("iterate indexes: %v", err)
+		}
+	}()
+
+	// Per workspace now. A UNIQUE constraint is backed by an index of the same
+	// name, so both spellings are visible here.
+	perWorkspace := map[string][]string{
+		"users_workspace_id_email_key":      {"workspace_id", "email"},
+		"event_types_workspace_id_slug_key": {"workspace_id", "slug"},
+		"teams_workspace_id_slug_key":       {"workspace_id", "slug"},
+		"idempotency_keys_pkey":             {"workspace_id", "idempotency_key"},
+		"meeting_consents_pkey":             {"workspace_id", "room", "participant_identity"},
+		"server_settings_pkey":              {"workspace_id", "id"},
+		"ux_jobs_type_payload":              {"workspace_id", "type", "payload"},
+		"idx_notes_booking":                 {"workspace_id", "booking_id"},
+		"idx_bookings_no_double":            {"workspace_id", "host_id", "start_at"},
+		"idx_bookings_host_time":            {"workspace_id", "host_id", "start_at", "end_at"},
+		"idx_jobs_pending":                  {"workspace_id", "run_at"},
+		"idx_jobs_running_expired":          {"workspace_id", "locked_until"},
+		"idx_jobs_pending_global":           {"run_at"},
+		"idx_jobs_running_expired_global":   {"locked_until"},
+	}
+	for name, cols := range perWorkspace {
+		def, ok := defs[name]
+		if !ok {
+			t.Errorf("index %s does not exist", name)
+			continue
+		}
+		if got := indexColumns(def); !slices.Equal(got, cols) {
+			t.Errorf("index %s covers %v; want %v (%s)", name, got, cols, def)
+		}
+	}
+
+	// The global ones went away.
+	for _, gone := range []string{"users_email_key", "event_types_slug_key", "teams_slug_key"} {
+		if def, ok := defs[gone]; ok {
+			t.Errorf("%s still exists (%s); it should have become the (workspace_id, …) form", gone, def)
+		}
+	}
+
+	// Credentials stay global: the tenant of a request that carries one is
+	// resolved FROM it, so the lookup happens before any workspace is known.
+	global := map[string][]string{
+		"api_keys_key_hash_key":                {"key_hash"},
+		"sessions_pkey":                        {"id"},
+		"oauth_access_tokens_token_hash_key":   {"token_hash"},
+		"oauth_access_tokens_refresh_hash_key": {"refresh_hash"},
+		"oauth_auth_codes_pkey":                {"code_hash"},
+		"booking_manage_tokens_pkey":           {"token_hash"},
+		"magic_link_tokens_pkey":               {"token_hash"},
+		"invite_tokens_token_hash_key":         {"token_hash"},
+		"crypto_keystore_label_key":            {"label"},
+	}
+	for name, cols := range global {
+		def, ok := defs[name]
+		if !ok {
+			t.Errorf("index %s does not exist", name)
+			continue
+		}
+		if got := indexColumns(def); !slices.Equal(got, cols) {
+			t.Errorf("index %s covers %v; want %v — this one has to stay global (%s)", name, got, cols, def)
+		}
+	}
+}
+
+// TestTenancy_defaultWorkspaceSeeded runs on whichever engine the environment
+// selects, because the foreign keys on PostgreSQL and every existing row on both
+// engines depend on that one row existing.
+func TestTenancy_defaultWorkspaceSeeded(t *testing.T) {
+	handle := dbtest.Open(t)
+
+	var id, slug, host, status string
+	err := handle.QueryRow(
+		`SELECT id, slug, public_host, status FROM workspaces WHERE id = ?`,
+		db.DefaultWorkspaceID).Scan(&id, &slug, &host, &status)
+	if err != nil {
+		t.Fatalf("read the default workspace: %v", err)
+	}
+	if slug != db.DefaultWorkspaceID {
+		t.Errorf("slug = %q; want %q", slug, db.DefaultWorkspaceID)
+	}
+	// Empty on purpose: no HTTP request carries an empty Host, so host
+	// resolution can never land on the default workspace.
+	if host != "" {
+		t.Errorf("public_host = %q; want empty", host)
+	}
+	if status != "active" {
+		t.Errorf("status = %q; want active", status)
+	}
+
+	var n int
+	if err := handle.QueryRow(`SELECT COUNT(*) FROM workspaces`).Scan(&n); err != nil {
+		t.Fatalf("count workspaces: %v", err)
+	}
+	if n != 1 {
+		t.Errorf("migrating seeded %d workspaces; want exactly 1", n)
+	}
+}
+
+// TestTenancy_existingRowsLandInTheDefaultWorkspace: an INSERT that names no
+// workspace_id has to work unchanged, on both engines, which is the whole point
+// of D1's column default — the ~200 INSERT statements in the tree need no edit.
+func TestTenancy_existingRowsLandInTheDefaultWorkspace(t *testing.T) {
+	handle := dbtest.Open(t)
+
+	if _, err := handle.Exec(
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		"u1", "a@example.com", "A"); err != nil {
+		t.Fatalf("insert without naming workspace_id: %v", err)
+	}
+
+	var ws string
+	if err := handle.QueryRow(`SELECT workspace_id FROM users WHERE id = ?`, "u1").Scan(&ws); err != nil {
+		t.Fatalf("read back: %v", err)
+	}
+	if ws != db.DefaultWorkspaceID {
+		t.Errorf("workspace_id = %q; want %q", ws, db.DefaultWorkspaceID)
+	}
+}
+
+type rlsFlag struct{ enabled, forced bool }
+
+func rlsFlags(t *testing.T, handle *db.DB) map[string]rlsFlag {
+	t.Helper()
+
+	rows, err := handle.Query(
+		`SELECT relname, relrowsecurity, relforcerowsecurity FROM pg_class
+		 WHERE relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = current_schema())
+		   AND relkind = 'r'`)
+	if err != nil {
+		t.Fatalf("read pg_class: %v", err)
+	}
+	defer rows.Close()
+
+	out := map[string]rlsFlag{}
+	for rows.Next() {
+		var name string
+		var f rlsFlag
+		if err := rows.Scan(&name, &f.enabled, &f.forced); err != nil {
+			t.Fatalf("scan: %v", err)
+		}
+		out[name] = f
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("iterate: %v", err)
+	}
+	return out
+}
+
+// indexColumns pulls the column list out of a pg_indexes definition. It anchors
+// on "USING btree (" rather than the last parenthesis, because a partial index's
+// WHERE clause carries parentheses of its own and there are five of those here.
+// Expression indexes would need more than this; none of the ones asserted above
+// is one.
+func indexColumns(def string) []string {
+	const anchor = "USING btree ("
+	start := strings.Index(def, anchor)
+	if start < 0 {
+		return nil
+	}
+	start += len(anchor)
+	end := strings.IndexByte(def[start:], ')')
+	if end < 0 {
+		return nil
+	}
+	var out []string
+	for _, part := range strings.Split(def[start:start+end], ",") {
+		// Strip a trailing operator class, collation or sort direction.
+		field := strings.TrimSpace(part)
+		if i := strings.IndexByte(field, ' '); i >= 0 {
+			field = field[:i]
+		}
+		out = append(out, field)
+	}
+	return out
+}
diff --git a/internal/demo/demo.go b/internal/demo/demo.go
index 2a50c7f..5e7986f 100644
--- a/internal/demo/demo.go
+++ b/internal/demo/demo.go
@@ -252,11 +252,20 @@ func listTables(ctx context.Context, db *db.DB) ([]string, error) {
 	// sqlite_master has no Postgres counterpart. pg_tables scoped to
 	// current_schema() is the equivalent, and honouring the current schema is what
 	// lets a test run inside its own isolated one.
+	//
+	// Two tables are held back. goose_db_version is migration bookkeeping, and
+	// wiping it would make the next boot re-run every migration. workspaces is the
+	// tenant root (migration 00060): every application table's workspace_id has a
+	// foreign key to it, so truncating it takes the 'default' row with it and the
+	// re-seed's first INSERT fails with SQLSTATE 23503. It holds no visitor data —
+	// in demo mode there is exactly one row, and it is a constant.
 	rows, err := db.QueryContext(ctx, db.Dialect().SQL(
 		`SELECT name FROM sqlite_master
-		 WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name != 'goose_db_version'`,
+		 WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+		   AND name NOT IN ('goose_db_version', 'workspaces')`,
 		`SELECT tablename FROM pg_tables
-		 WHERE schemaname = current_schema() AND tablename != 'goose_db_version'`))
+		 WHERE schemaname = current_schema()
+		   AND tablename NOT IN ('goose_db_version', 'workspaces')`))
 	if err != nil {
 		return nil, fmt.Errorf("demo reset: list tables: %w", err)
 	}

From dc029b7bde1a7293e5b388f8f8a6004402c1a0b9 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 01:16:13 -0400
Subject: [PATCH 27/51] db: two handles, and a tenant bound per statement
 rather than per connection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boundary 2. OpenPair(appURL, adminURL) returns the application handle and the
platform handle; app.Platform() answers with the second, so nothing downstream
carries both. ForWorkspace(id) returns a cheap value sharing the pool, which is
what makes it safe in the fire-and-forget goroutines this codebase is full of:
it holds a pool and a string, not a session. A test builds a handle inside a
function, lets that function return, and reads through it from four goroutines.

Each statement on a bound handle takes a pooled connection, sets
app.workspace_id on it, runs there, and gives it back — Exec at once, Row on
Scan/Err, Rows on Close, Tx on Commit/Rollback, the last idempotently because
`defer tx.Rollback()` after a successful Commit is the pattern here. Begin uses
SET LOCAL, so the connection returns carrying nothing. Because every statement
sets the parameter itself, a value left on a pooled connection cannot leak into a
later one.

The release is asserted with Stats().InUse returning to 0 after every shape, and
with a positive control on the same number: 1 while a cursor or transaction is
open. Proved failable by skipping the release — InUse climbs to 2, 3, 4 and the
"with a cursor open" control fails too.

Prepare is refused on a bound handle. A *sql.Stmt is re-prepared on an arbitrary
pooled connection with no hook to bind first, so it would run unbound, which is
silently empty rather than an error. Nothing in the tree prepares a statement.

VerifyRoles is new, because D4 was otherwise documentation only. Both halves of a
bad configuration are silent: an application role that is superuser, has
BYPASSRLS, or owns any table in the schema is not constrained by the policies and
can read every workspace while nothing appears wrong; a platform role that does
not bypass makes its '' binding match no row, so the worker claims nothing and
the reconciler enumerates nothing. It runs at boot after EnableRLS and the boot
exits 1 if it fails. It is also what makes binding '' on the platform handle safe
rather than a gamble.

connstore.Execer now returns *db.Row. Go has no covariant return types and the
interface is satisfied by both *db.DB and *db.Tx, so it had to move with them.
destination_test.go's deliberately-bare sql.Open therefore becomes db.OpenDB —
a correction rather than a concession, since a bare *sql.DB does not rebind
placeholders either. The compiler found the only three other sites: two
*sql.Rows declarations in internal/handler and one test helper.

Boot opens the pair under MULTI_TENANT and one handle otherwise, migrates and
enables RLS on the platform handle, and verifies roles on the application one.

gofmt -l empty, go vet clean, go test ./... rc=0 on SQLite (28/28) and rc=0 on
PostgreSQL (28/28).
---
 PROGRESS.md                            | 105 ++++++
 cmd/calnode/main.go                    |  62 ++--
 internal/connstore/connstore.go        |  10 +-
 internal/connstore/destination_test.go |  15 +-
 internal/db/handle.go                  | 372 +++++++++++++++++++--
 internal/db/pair.go                    | 125 +++++++
 internal/db/pair_test.go               | 446 +++++++++++++++++++++++++
 internal/db/postgres_test.go           |   3 +-
 internal/db/rls_proof_test.go          |   7 +-
 internal/handler/availability.go       |   2 +-
 internal/handler/livekit_recording.go  |   3 +-
 11 files changed, 1077 insertions(+), 73 deletions(-)
 create mode 100644 internal/db/pair.go
 create mode 100644 internal/db/pair_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 75cb489..06bec2c 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -523,3 +523,108 @@ uses it for `Migrate` + `EnableRLS`; Boundary 2 replaces that pair with
 `db.OpenPair`. The other entry points (`mcp`, `reset-admin`, `rotate-key`,
 `recover-key`) still open one handle from `DATABASE_URL` and are untouched —
 they are single-tenant operator tools today, and B3/B6 decide what they become.
+
+## Boundary 2 — the two handles, and the per-statement binding — DONE
+
+`db.OpenPair(appURL, adminURL)` returns `(app, platform)`, `app.Platform()`
+answers with `platform`, and `ForWorkspace(id)` returns a **value** carrying the
+pool plus a string. `OpenDB` is untouched, and a handle from it binds nothing —
+so single-tenant SQLite and single-tenant PostgreSQL run exactly the statements
+they ran before. `TestSingleHandle_forWorkspaceIsIdentity` pins that:
+`ForWorkspace` returns the identical pointer, does not even validate, `Platform()`
+is the handle itself, and `Prepare` still works.
+
+### Binding is per statement, and the release is the part that needed proving
+
+Each `Query`/`QueryRow`/`Exec`/`Begin` on a bound handle takes a pooled
+`*sql.Conn`, runs `SELECT set_config('app.workspace_id', $1, false)`, runs the
+statement there, and gives the connection back: `Exec` immediately, `Row` on
+`Scan`/`Err`, `Rows` on `Close`, `Tx` on `Commit`/`Rollback` (idempotently — a
+`defer tx.Rollback()` after a successful `Commit` is the standard pattern here and
+must not double-close). `Begin` uses `set_config(…, true)`, i.e. `SET LOCAL`, so
+the connection goes back carrying nothing.
+
+Nothing is pinned between statements, which is the point:
+`TestOpenPair_handleSurvivesItsRequest` builds a handle inside a function, lets
+that function return, and then reads through it from four concurrent goroutines.
+Calnode's handlers are full of fire-and-forget goroutines (notify hosts, enqueue
+the webhook, enqueue reminders) that outlive their request, and a handle that
+pinned a session would be unusable in them.
+
+Release is asserted by `handle.Stats().InUse` returning to **0** after every
+shape, with a positive control on the same number: while a cursor or a
+transaction is open it must read **1**, so the zero afterwards means something.
+Proved failable by making `Row.release` and `Rows.Close` skip the release:
+
+```
+--- FAIL: TestOpenPair_workspaceHandleSeesOnlyItsOwn/QueryRow
+    pair_test.go:103: pool reports InUse=2 after two QueryRow/Scan pairs; the connection was not released
+--- FAIL: .../Query
+    pair_test.go:114: with a cursor open the pool reports InUse=3; want 1
+    pair_test.go:133: pool reports InUse=3 after Rows.Close; the connection was not released
+--- FAIL: .../Exec
+    pair_test.go:156: pool reports InUse=3 after Exec; the connection was not released
+--- FAIL: .../Tx
+    pair_test.go:167: with a transaction open the pool reports InUse=4; want 1
+```
+
+### ⛔ `Prepare` is refused on a bound handle
+
+A `*sql.Stmt` is re-prepared on whatever connection the pool hands it, and there
+is no hook to set `app.workspace_id` on that connection first — so a prepared
+statement on a multi-tenant handle would run **unbound**, which is silently
+empty rather than an error. Nothing in the tree prepares a statement (checked, not
+assumed), and a caller that needs one should take a transaction, where the binding
+is a property of the connection for the whole tx.
+
+### `VerifyRoles` — because D4 was otherwise documentation only
+
+Called on the application handle at boot, right after `EnableRLS`, and the boot
+fails if it does. Both halves fail **silently** otherwise:
+
+- The application role being a superuser, having `BYPASSRLS`, or **owning any
+  table in the schema** means it is not constrained by the policies. Nothing
+  breaks. Every request works. It can also read every other workspace. That is a
+  security hole with no symptom, which is exactly the kind of thing that needs a
+  boot-time refusal rather than a doc line.
+- The platform role *not* bypassing means its `''` binding matches no row, so the
+  worker claims nothing and the reconciler enumerates nothing. Also no error, just
+  an instance that quietly does no background work. This is what makes binding
+  `''` on the platform handle (D5) safe rather than a gamble.
+
+`openTenantPair` in the tests runs it, so every case in the file is asserted
+against a configuration the guard accepts.
+
+### ⚠️ `connstore.Execer` had to change, and `destination_test.go` with it
+
+`Execer` was `QueryRowContext(…) *sql.Row`, and it is called with a `*db.DB` in
+three provider packages (`gcal`, `calendar/microsoft`, `caldav`) as well as with a
+`*db.Tx`. Go has no covariant return types, so once `QueryRowContext` returns
+`*db.Row` the interface has to say `*db.Row`. The consequence is that
+`connstore/destination_test.go`'s deliberately-bare `sql.Open("sqlite",
+":memory:")` no longer satisfies it and is now `db.OpenDB("sqlite://:memory:")`
+— which is a correction, not a concession: a bare `*sql.DB` does not rebind
+placeholders either, so holding it up as "Execer accepts this too" was already
+describing a handle that cannot run the tree's SQL on PostgreSQL. The bespoke
+fragment schema is unchanged; `OpenDB` does not migrate.
+
+The compiler found the rest, and there were only three: `*sql.Rows` declarations
+in `handler/availability.go` and `handler/livekit_recording.go`, and the
+`scanStrings` helper in `internal/db/postgres_test.go`.
+
+### Boot
+
+`cmd/calnode/main.go` opens the pair when `MULTI_TENANT` is set and one handle
+otherwise, runs migrations and `EnableRLS` on **`platform`**, and `VerifyRoles` on
+`database`. Both refusals are `os.Exit(1)`.
+
+⚠️ Still single-handle, from `DATABASE_URL`, and untouched: the `mcp`,
+`reset-admin`, `rotate-key` and `recover-key` subcommands. They are single-tenant
+operator tools today; B3 and B6 decide what they become.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+`go test ./...` **rc=0 on SQLite (28/28)** and **rc=0 on PostgreSQL (28/28)**.
+The 11 new cases all run rather than skip on the PostgreSQL lane, and the
+tenant-binding ones skip with a stated reason on SQLite.
diff --git a/cmd/calnode/main.go b/cmd/calnode/main.go
index fdaf640..3a461c2 100644
--- a/cmd/calnode/main.go
+++ b/cmd/calnode/main.go
@@ -67,48 +67,56 @@ func main() {
 		slog.Warn("Google OAuth NOT configured — GOOGLE_CLIENT_ID is empty")
 	}
 
-	database, err := db.OpenDB(cfg.DatabaseURL)
-	if err != nil {
-		logger.Error("failed to open database", "error", err)
-		os.Exit(1)
-	}
-	defer database.Close()
-
-	// Migrations and row-level-security enablement are the PLATFORM role's work,
-	// not the application role's. In multi-tenant mode DATABASE_URL is a
-	// NOBYPASSRLS role that does not own the schema and therefore cannot run DDL
-	// at all; DATABASE_ADMIN_URL is the owner. Single-tenant mode has one role and
-	// one handle, so migrator is just database.
-	//
-	// Boundary 2 replaces this pair of opens with db.OpenPair.
-	migrator := database
+	// One handle in single-tenant mode; two in multi-tenant mode, because
+	// migrations, EnableRLS and every cross-tenant read are the PLATFORM role's
+	// work. DATABASE_URL is then a NOBYPASSRLS role that does not own the schema
+	// and cannot run DDL at all. database.Platform() answers with the right one
+	// either way, so nothing downstream has to know which mode this is.
+	var (
+		database, platform *db.DB
+		err                error
+	)
 	if cfg.MultiTenant {
-		admin, err := db.OpenDB(cfg.DatabaseAdminURL)
+		database, platform, err = db.OpenPair(cfg.DatabaseURL, cfg.DatabaseAdminURL)
+		if err != nil {
+			logger.Error("failed to open the database pair", "error", err)
+			os.Exit(1)
+		}
+		defer platform.Close()
+	} else {
+		database, err = db.OpenDB(cfg.DatabaseURL)
 		if err != nil {
-			logger.Error("failed to open the platform database handle", "error", err)
+			logger.Error("failed to open database", "error", err)
 			os.Exit(1)
 		}
-		defer admin.Close()
-		migrator = admin
+		platform = database
 	}
+	defer database.Close()
 
-	if err := migrator.Migrate(); err != nil {
+	if err := platform.Migrate(); err != nil {
 		logger.Error("failed to run migrations", "error", err)
 		os.Exit(1)
 	}
 	logger.Info("database migrations applied")
 
-	// ⛔ Refuse to serve if this fails. Without it every policy created by
-	// migration 00060 is inert, and the process would come up looking multi-tenant
-	// while separating nothing. It is idempotent, so booting twice is fine, and it
-	// is deliberately gated on MULTI_TENANT: FORCE ROW LEVEL SECURITY applies a
-	// policy to the table's owner too, and in single-tenant mode DATABASE_URL is
-	// that owner (see db.EnableRLS).
+	// ⛔ Refuse to serve if either of these fails. Without EnableRLS every policy
+	// created by migration 00060 is inert and the process comes up looking
+	// multi-tenant while separating nothing; without VerifyRoles the same is true
+	// of a DATABASE_URL that happens to bypass or to own the tables. Both failures
+	// are otherwise silent — every request works, and each one can read every
+	// workspace. EnableRLS is idempotent, so booting twice is fine, and it is
+	// deliberately gated on MULTI_TENANT: FORCE ROW LEVEL SECURITY applies a policy
+	// to the table's owner too, and in single-tenant mode DATABASE_URL is that
+	// owner (see db.EnableRLS).
 	if cfg.MultiTenant {
-		if err := migrator.EnableRLS(context.Background()); err != nil {
+		if err := platform.EnableRLS(context.Background()); err != nil {
 			logger.Error("failed to enable row-level security; refusing to serve", "error", err)
 			os.Exit(1)
 		}
+		if err := database.VerifyRoles(context.Background()); err != nil {
+			logger.Error("database roles cannot enforce tenant isolation; refusing to serve", "error", err)
+			os.Exit(1)
+		}
 		logger.Info("row-level security enabled", "tables", len(db.TenantTables))
 	}
 
diff --git a/internal/connstore/connstore.go b/internal/connstore/connstore.go
index e2e4b0e..8f2a0a4 100644
--- a/internal/connstore/connstore.go
+++ b/internal/connstore/connstore.go
@@ -11,12 +11,20 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+
+	"github.com/calnode/calnode/internal/db"
 )
 
 // Execer is satisfied by both *db.DB and *db.Tx — ResolveFlags runs inside whichever
 // transaction the caller already opened for its own upsert.
+//
+// It returns *db.Row rather than *sql.Row because that is what the wrapper hands
+// back: on a tenant-bound handle the row owns the pooled connection its tenant was
+// bound on, and releases it when the caller Scans. A bare *sql.DB therefore no
+// longer satisfies this — which is correct, since a statement issued through one
+// is neither rebound nor tenant-bound.
 type Execer interface {
-	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
+	QueryRowContext(ctx context.Context, query string, args ...any) *db.Row
 }
 
 // WhereClause builds the "AND check_conflicts = ? AND is_destination = ?" fragment
diff --git a/internal/connstore/destination_test.go b/internal/connstore/destination_test.go
index 3762dec..d5b86b4 100644
--- a/internal/connstore/destination_test.go
+++ b/internal/connstore/destination_test.go
@@ -2,16 +2,21 @@ package connstore
 
 import (
 	"context"
-	"database/sql"
 	"testing"
 
-	_ "modernc.org/sqlite"
+	calnodedb "github.com/calnode/calnode/internal/db"
 )
 
 // newDestDB builds just enough schema to exercise the destination lookup.
-func newDestDB(t *testing.T) *sql.DB {
+//
+// A *db.DB rather than a bare *sql.DB, even though nothing here is migrated and
+// the schema is a hand-written fragment: Execer takes *db.Row, because on a
+// tenant-bound handle a row owns the connection its tenant was bound on. A bare
+// *sql.DB does not rebind placeholders either, so it was never the right shape to
+// hold up as "Execer accepts this too".
+func newDestDB(t *testing.T) *calnodedb.DB {
 	t.Helper()
-	db, err := sql.Open("sqlite", ":memory:")
+	db, err := calnodedb.OpenDB("sqlite://:memory:")
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
@@ -32,7 +37,7 @@ func newDestDB(t *testing.T) *sql.DB {
 	return db
 }
 
-func insertCal(t *testing.T, db *sql.DB, id, user, provider, email, calID string, conflicts, dest int) {
+func insertCal(t *testing.T, db *calnodedb.DB, id, user, provider, email, calID string, conflicts, dest int) {
 	t.Helper()
 	if _, err := db.Exec(
 		`INSERT INTO connection_calendars (id, user_id, provider, account_email, calendar_id, check_conflicts, is_destination)
diff --git a/internal/db/handle.go b/internal/db/handle.go
index c8cac0c..54832b5 100644
--- a/internal/db/handle.go
+++ b/internal/db/handle.go
@@ -3,65 +3,246 @@ package db
 import (
 	"context"
 	"database/sql"
+	"errors"
+	"fmt"
+	"regexp"
 )
 
-// DB is a *sql.DB that knows its dialect and rebinds placeholders.
+// DB is a *sql.DB that knows its dialect, rebinds placeholders, and — in
+// multi-tenant mode — binds the tenant of every statement it runs.
 //
 // Every query method takes the portable ? form and rewrites it for the engine in
 // use, so the rest of Calnode writes one statement per query no matter which
 // database it runs on. Behaviour on SQLite is identical to using *sql.DB
 // directly: Rebind is a no-op there.
 //
+// # Tenant binding
+//
+// A handle from OpenPair carries a workspace. Before each statement it acquires a
+// pooled connection, runs SELECT set_config('app.workspace_id', …), runs the
+// statement on that connection, and releases the connection when the statement is
+// finished — Exec immediately, Row on Scan/Err, Rows on Close, Tx on
+// Commit/Rollback. Nothing is pinned between statements, which is what makes a
+// handle safe to copy into a fire-and-forget goroutine: it holds a pool and a
+// string, not a session.
+//
+// Because every statement sets the parameter itself, a value left behind on a
+// pooled connection can never leak into a later statement. The unbound handle —
+// the platform handle, and the pair's base app handle — binds the empty string,
+// which no workspace id can equal, so it matches no row under the policies.
+//
+// A handle from OpenDB carries no workspace and binds nothing, so single-tenant
+// SQLite and single-tenant PostgreSQL run exactly the statements they ran before.
+//
 // The embedded *sql.DB is exported on purpose — pool tuning, Ping, Close and
-// anything that must hand a plain *sql.DB to a library (goose here, Litestream
-// in DEPLOY.md) reach it as h.DB. Statements issued through that field, or
-// through a *sql.Conn from the promoted Conn method, are NOT rebound; use the
-// wrapper's own methods unless you are deliberately writing engine-specific SQL.
+// anything that must hand a plain *sql.DB to a library (goose here, Litestream in
+// DEPLOY.md) reach it as h.DB. ⛔ Statements issued through that field are NOT
+// rebound AND NOT TENANT-BOUND: on a multi-tenant instance they will see nothing
+// and write nothing, because an unbound session matches no row. Use the wrapper's
+// own methods unless you are deliberately writing engine-specific DDL.
 type DB struct {
 	*sql.DB
 	dialect Dialect
+
+	// multiTenant is set only by OpenPair. It is what turns the binding on; a
+	// single handle from OpenDB leaves it false and behaves as it always did.
+	multiTenant bool
+
+	// workspace is the tenant this handle is bound to. "" is the unbound handle,
+	// which binds '' and therefore matches no row.
+	workspace string
+
+	// platform is the paired owner handle. nil on a single handle, where
+	// Platform() answers with the handle itself.
+	platform *DB
+
+	// err poisons a handle built from a workspace id that failed validation.
+	// Every statement method returns it rather than running unbound, because an
+	// unbound statement on a multi-tenant database is silently empty.
+	err error
 }
 
+// ErrInvalidWorkspace is returned by every statement on a handle built from a
+// workspace id that is not [a-z0-9_-]{1,64}.
+var ErrInvalidWorkspace = errors.New("db: invalid workspace id")
+
+// workspaceIDPattern is the shape of a workspace id. The id is never
+// interpolated into SQL — it is a bind parameter to set_config — so this is not
+// an injection defence; it is a guard against a caller passing something that is
+// not an id at all (an email, a URL, a whole request path) and getting a handle
+// that silently matches nothing.
+var workspaceIDPattern = regexp.MustCompile(`^[a-z0-9_-]{1,64}$`)
+
+// ValidWorkspaceID reports whether id is a well-formed workspace id.
+func ValidWorkspaceID(id string) bool { return workspaceIDPattern.MatchString(id) }
+
 // Dialect reports which engine this handle is talking to, for the few callers
 // that must branch on it.
 func (h *DB) Dialect() Dialect { return h.dialect }
 
+// MultiTenant reports whether this handle binds a tenant per statement.
+func (h *DB) MultiTenant() bool { return h.multiTenant }
+
+// Workspace returns the workspace this handle is bound to, or "" for an unbound
+// handle (single-tenant, the platform handle, or a pair's base app handle).
+func (h *DB) Workspace() string { return h.workspace }
+
+// Err returns the error that poisoned this handle, or nil.
+func (h *DB) Err() error { return h.err }
+
+// ForWorkspace returns a handle that binds id before every statement.
+//
+// It is a cheap value: the returned handle shares this one's pool and adds a
+// string, so it may be copied freely and handed to a goroutine that outlives the
+// request that made it. Nothing is pinned.
+//
+// On a single handle — SQLite, or single-tenant PostgreSQL — it is the identity
+// function and does not even validate, because there is exactly one workspace and
+// no parameter to bind.
+func (h *DB) ForWorkspace(id string) *DB {
+	if !h.binds() {
+		return h
+	}
+	scoped := *h
+	if !ValidWorkspaceID(id) {
+		scoped.err = fmt.Errorf("%w: %q", ErrInvalidWorkspace, id)
+		return &scoped
+	}
+	scoped.workspace = id
+	scoped.err = nil
+	return &scoped
+}
+
+// Platform returns the handle that owns the schema and bypasses row-level
+// security: migrations, the worker's cross-tenant claim loop, the reconciler's
+// workspace enumeration, and the credential lookups that must resolve a tenant
+// before one is known.
+//
+// On a single handle it returns the handle itself, so a caller needs no branch:
+// in single-tenant mode the application role and the platform role are one role.
+func (h *DB) Platform() *DB {
+	if h.platform != nil {
+		return h.platform
+	}
+	return h
+}
+
+// binds reports whether this handle sets app.workspace_id per statement.
+func (h *DB) binds() bool { return h.multiTenant && h.dialect == DialectPostgres }
+
+// bindConn takes a connection out of the pool and sets app.workspace_id on it.
+// It returns (nil, nil) for a handle that does not bind, which every caller reads
+// as "use the pool directly, as before".
+//
+// The statement is written in PostgreSQL's own $n form because a *sql.Conn does
+// not go through the wrapper and is therefore not rebound. This path is
+// PostgreSQL-only by construction.
+func (h *DB) bindConn(ctx context.Context) (*sql.Conn, error) {
+	if !h.binds() {
+		return nil, nil
+	}
+	conn, err := h.DB.Conn(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if _, err := conn.ExecContext(ctx,
+		`SELECT set_config('app.workspace_id', $1, false)`, h.workspace); err != nil {
+		conn.Close() //nolint:errcheck // the bind error is the useful one
+		return nil, fmt.Errorf("bind workspace %q: %w", h.workspace, err)
+	}
+	return conn, nil
+}
+
 // Rebind converts a ?-placeholder statement for this handle's dialect. Useful
 // when a caller builds SQL dynamically and hands it to something other than the
 // methods below.
 func (h *DB) Rebind(query string) string { return h.dialect.Rebind(query) }
 
-func (h *DB) Query(query string, args ...any) (*sql.Rows, error) {
-	return h.DB.Query(h.dialect.Rebind(query), args...)
+func (h *DB) Query(query string, args ...any) (*Rows, error) {
+	return h.QueryContext(context.Background(), query, args...)
 }
 
-func (h *DB) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {
-	return h.DB.QueryContext(ctx, h.dialect.Rebind(query), args...)
+func (h *DB) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) {
+	if h.err != nil {
+		return nil, h.err
+	}
+	conn, err := h.bindConn(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if conn == nil {
+		rows, err := h.DB.QueryContext(ctx, h.dialect.Rebind(query), args...)
+		if err != nil {
+			return nil, err
+		}
+		return &Rows{Rows: rows}, nil
+	}
+	rows, err := conn.QueryContext(ctx, h.dialect.Rebind(query), args...)
+	if err != nil {
+		conn.Close() //nolint:errcheck // the query error is the useful one
+		return nil, err
+	}
+	return &Rows{Rows: rows, conn: conn}, nil
 }
 
-func (h *DB) QueryRow(query string, args ...any) *sql.Row {
-	return h.DB.QueryRow(h.dialect.Rebind(query), args...)
+func (h *DB) QueryRow(query string, args ...any) *Row {
+	return h.QueryRowContext(context.Background(), query, args...)
 }
 
-func (h *DB) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row {
-	return h.DB.QueryRowContext(ctx, h.dialect.Rebind(query), args...)
+func (h *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row {
+	if h.err != nil {
+		return &Row{err: h.err}
+	}
+	conn, err := h.bindConn(ctx)
+	if err != nil {
+		return &Row{err: err}
+	}
+	if conn == nil {
+		return &Row{Row: h.DB.QueryRowContext(ctx, h.dialect.Rebind(query), args...)}
+	}
+	return &Row{Row: conn.QueryRowContext(ctx, h.dialect.Rebind(query), args...), conn: conn}
 }
 
 func (h *DB) Exec(query string, args ...any) (sql.Result, error) {
-	return h.DB.Exec(h.dialect.Rebind(query), args...)
+	return h.ExecContext(context.Background(), query, args...)
 }
 
 func (h *DB) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
-	return h.DB.ExecContext(ctx, h.dialect.Rebind(query), args...)
+	if h.err != nil {
+		return nil, h.err
+	}
+	conn, err := h.bindConn(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if conn == nil {
+		return h.DB.ExecContext(ctx, h.dialect.Rebind(query), args...)
+	}
+	defer conn.Close() //nolint:errcheck // the statement's error is the useful one
+	return conn.ExecContext(ctx, h.dialect.Rebind(query), args...)
 }
 
 // Prepare and PrepareContext rebind at prepare time, so the returned *sql.Stmt
 // needs no wrapper of its own.
+//
+// ⛔ They are refused on a handle that binds a tenant. A *sql.Stmt is re-prepared
+// on whatever connection the pool hands it, and there is no hook to set
+// app.workspace_id on that connection first — so a prepared statement on a
+// multi-tenant handle would run unbound and silently see nothing. Nothing in the
+// tree prepares a statement; if something needs to, it should take a transaction,
+// where the binding is a property of the connection for the whole tx.
 func (h *DB) Prepare(query string) (*sql.Stmt, error) {
-	return h.DB.Prepare(h.dialect.Rebind(query))
+	return h.PrepareContext(context.Background(), query)
 }
 
 func (h *DB) PrepareContext(ctx context.Context, query string) (*sql.Stmt, error) {
+	if h.err != nil {
+		return nil, h.err
+	}
+	if h.binds() {
+		return nil, errors.New("db: Prepare is not available on a tenant-bound handle — " +
+			"a *sql.Stmt is re-prepared on an arbitrary pooled connection, which would run unbound; use a transaction")
+	}
 	return h.DB.PrepareContext(ctx, h.dialect.Rebind(query))
 }
 
@@ -69,48 +250,171 @@ func (h *DB) PrepareContext(ctx context.Context, query string) (*sql.Stmt, error
 // silently stopped rebinding would be the easiest way to reintroduce ? into a
 // Postgres statement.
 func (h *DB) Begin() (*Tx, error) {
-	tx, err := h.DB.Begin()
-	if err != nil {
-		return nil, err
-	}
-	return &Tx{Tx: tx, dialect: h.dialect}, nil
+	return h.BeginTx(context.Background(), nil)
 }
 
 func (h *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*Tx, error) {
-	tx, err := h.DB.BeginTx(ctx, opts)
+	if h.err != nil {
+		return nil, h.err
+	}
+	if !h.binds() {
+		tx, err := h.DB.BeginTx(ctx, opts)
+		if err != nil {
+			return nil, err
+		}
+		return &Tx{Tx: tx, dialect: h.dialect}, nil
+	}
+
+	// A transaction owns its connection for its whole life, so the binding is set
+	// once, inside the transaction, with SET LOCAL semantics: it reverts when the
+	// transaction ends, which means the connection goes back to the pool carrying
+	// nothing. Every statement on the pool sets the parameter itself anyway, so
+	// this is belt and braces rather than the guarantee.
+	conn, err := h.DB.Conn(ctx)
+	if err != nil {
+		return nil, err
+	}
+	tx, err := conn.BeginTx(ctx, opts)
 	if err != nil {
+		conn.Close() //nolint:errcheck
 		return nil, err
 	}
-	return &Tx{Tx: tx, dialect: h.dialect}, nil
+	if _, err := tx.ExecContext(ctx,
+		`SELECT set_config('app.workspace_id', $1, true)`, h.workspace); err != nil {
+		tx.Rollback() //nolint:errcheck
+		conn.Close()  //nolint:errcheck
+		return nil, fmt.Errorf("bind workspace %q on transaction: %w", h.workspace, err)
+	}
+	return &Tx{Tx: tx, dialect: h.dialect, conn: conn, workspace: h.workspace}, nil
+}
+
+// Rows is a *sql.Rows that releases the connection its statement was bound on.
+//
+// Close does both, and is what every caller already defers. A caller that never
+// closes leaks a connection out of the pool on a multi-tenant instance, which is
+// the same bug as never closing a *sql.Rows, only with a pool of ten rather than
+// a cursor.
+type Rows struct {
+	*sql.Rows
+	conn *sql.Conn
+}
+
+// Close closes the cursor and releases the bound connection. It returns the
+// cursor's error in preference to the release's, because the cursor's is the one
+// that says something about the query.
+func (r *Rows) Close() error {
+	err := r.Rows.Close()
+	if r.conn != nil {
+		cerr := r.conn.Close()
+		r.conn = nil
+		if err == nil {
+			err = cerr
+		}
+	}
+	return err
+}
+
+// Row is a *sql.Row that releases the connection its statement was bound on.
+//
+// Scan and Err both release, because those are the only two things a caller can
+// do with a Row and exactly one of them always happens. errors.Is against
+// sql.ErrNoRows works unchanged: Scan returns the underlying error verbatim.
+type Row struct {
+	*sql.Row
+	conn *sql.Conn
+	err  error
+}
+
+func (r *Row) Scan(dest ...any) error {
+	if r.err != nil {
+		return r.err
+	}
+	err := r.Row.Scan(dest...)
+	r.release()
+	return err
+}
+
+func (r *Row) Err() error {
+	if r.err != nil {
+		return r.err
+	}
+	err := r.Row.Err()
+	r.release()
+	return err
+}
+
+func (r *Row) release() {
+	if r.conn != nil {
+		r.conn.Close() //nolint:errcheck // nothing useful to do with it here
+		r.conn = nil
+	}
 }
 
-// Tx is a *sql.Tx with the same rebinding behaviour as DB. Commit and Rollback
-// are the embedded ones — they carry no SQL text.
+// Tx is a *sql.Tx with the same rebinding behaviour as DB, and — when it came
+// from a tenant-bound handle — ownership of the connection the tenant was bound
+// on. Commit and Rollback release it.
 type Tx struct {
 	*sql.Tx
-	dialect Dialect
+	dialect   Dialect
+	conn      *sql.Conn
+	workspace string
 }
 
 // Dialect reports which engine this transaction is running against.
 func (t *Tx) Dialect() Dialect { return t.dialect }
 
+// Workspace returns the workspace this transaction is bound to, or "".
+func (t *Tx) Workspace() string { return t.workspace }
+
 // Rebind converts a ?-placeholder statement for this transaction's dialect.
 func (t *Tx) Rebind(query string) string { return t.dialect.Rebind(query) }
 
-func (t *Tx) Query(query string, args ...any) (*sql.Rows, error) {
-	return t.Tx.Query(t.dialect.Rebind(query), args...)
+// Commit and Rollback release the pinned connection.
+//
+// Both are idempotent about the release, because `defer tx.Rollback()` after a
+// successful Commit is the standard pattern in this tree: the second call gets
+// sql.ErrTxDone from database/sql, and must not double-close the connection.
+func (t *Tx) Commit() error {
+	err := t.Tx.Commit()
+	t.release()
+	return err
+}
+
+func (t *Tx) Rollback() error {
+	err := t.Tx.Rollback()
+	t.release()
+	return err
+}
+
+func (t *Tx) release() {
+	if t.conn != nil {
+		t.conn.Close() //nolint:errcheck
+		t.conn = nil
+	}
+}
+
+func (t *Tx) Query(query string, args ...any) (*Rows, error) {
+	rows, err := t.Tx.Query(t.dialect.Rebind(query), args...)
+	if err != nil {
+		return nil, err
+	}
+	return &Rows{Rows: rows}, nil
 }
 
-func (t *Tx) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {
-	return t.Tx.QueryContext(ctx, t.dialect.Rebind(query), args...)
+func (t *Tx) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) {
+	rows, err := t.Tx.QueryContext(ctx, t.dialect.Rebind(query), args...)
+	if err != nil {
+		return nil, err
+	}
+	return &Rows{Rows: rows}, nil
 }
 
-func (t *Tx) QueryRow(query string, args ...any) *sql.Row {
-	return t.Tx.QueryRow(t.dialect.Rebind(query), args...)
+func (t *Tx) QueryRow(query string, args ...any) *Row {
+	return &Row{Row: t.Tx.QueryRow(t.dialect.Rebind(query), args...)}
 }
 
-func (t *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row {
-	return t.Tx.QueryRowContext(ctx, t.dialect.Rebind(query), args...)
+func (t *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *Row {
+	return &Row{Row: t.Tx.QueryRowContext(ctx, t.dialect.Rebind(query), args...)}
 }
 
 func (t *Tx) Exec(query string, args ...any) (sql.Result, error) {
diff --git a/internal/db/pair.go b/internal/db/pair.go
new file mode 100644
index 0000000..999d831
--- /dev/null
+++ b/internal/db/pair.go
@@ -0,0 +1,125 @@
+package db
+
+import (
+	"context"
+	"errors"
+	"fmt"
+)
+
+// OpenPair opens the two handles multi-tenant mode needs (D4).
+//
+//	app      DATABASE_URL       — the application role. NOBYPASSRLS, and it must
+//	                              not own the tables: a role that owns a table is
+//	                              exempt from that table's policy unless FORCE is
+//	                              set, and BYPASSRLS is exempt regardless. This is
+//	                              the handle every request runs on, through
+//	                              ForWorkspace.
+//	platform DATABASE_ADMIN_URL — the platform role. Owner of the schema, with
+//	                              BYPASSRLS. Runs migrations and EnableRLS, the
+//	                              worker's cross-tenant claim loop, the
+//	                              reconciler's workspace enumeration, the platform
+//	                              API, and the credential lookups that have to
+//	                              resolve a tenant before one is known.
+//
+// app.Platform() returns platform, so nothing downstream has to carry both.
+// Both are returned so the caller closes both; Close on one closes one pool.
+//
+// Both DSNs must be PostgreSQL. SQLite has no row-level security, so there is
+// nothing to enforce isolation with and a "multi-tenant" SQLite instance would
+// separate nothing — config.Validate refuses that combination before this is
+// reached, and this refuses it again because a library that only works when its
+// caller validated is a library that will one day be called by something else.
+func OpenPair(appURL, adminURL string, opts ...Option) (app, platform *DB, err error) {
+	if dialectFromURL(appURL) != DialectPostgres {
+		return nil, nil, errors.New("db: multi-tenant mode needs a postgres:// application DSN — " +
+			"tenant isolation is PostgreSQL row-level security")
+	}
+	if dialectFromURL(adminURL) != DialectPostgres {
+		return nil, nil, errors.New("db: multi-tenant mode needs a postgres:// platform DSN")
+	}
+
+	platform, err = OpenDB(adminURL, opts...)
+	if err != nil {
+		return nil, nil, fmt.Errorf("open platform handle: %w", err)
+	}
+	// The platform handle binds too, so that "every statement on a paired handle
+	// sets app.workspace_id" has no exceptions to remember. It binds '', which no
+	// workspace id can equal, so it matches no row under the policies — and it is
+	// inert in practice because the platform role bypasses them. VerifyRoles is
+	// what makes that "in practice" a checked fact rather than an assumption.
+	platform.multiTenant = true
+
+	app, err = OpenDB(appURL, opts...)
+	if err != nil {
+		platform.Close() //nolint:errcheck
+		return nil, nil, fmt.Errorf("open application handle: %w", err)
+	}
+	app.multiTenant = true
+	app.platform = platform
+
+	return app, platform, nil
+}
+
+// VerifyRoles checks the two role attributes the isolation guarantee rests on,
+// and is meant to run at boot, right after EnableRLS, with the boot failing if it
+// does. It is called on the application handle.
+//
+// ⛔ Both halves are load-bearing and both fail SILENTLY if they are wrong.
+//
+//   - If the application role is a superuser, has BYPASSRLS, or owns any tenant
+//     table, it is not constrained by the policies. Nothing breaks. Every request
+//     works. It can also read every other workspace's rows. That is the
+//     misconfiguration this exists for: the failure mode is a security hole with
+//     no symptom.
+//   - If the platform role does NOT bypass — it is the owner, and FORCE ROW LEVEL
+//     SECURITY covers owners — then the platform handle's ” binding matches no
+//     row and the worker claims nothing, the reconciler enumerates nothing, and
+//     the platform API returns empty. Also no error, just an instance that quietly
+//     does no background work.
+//
+// It is a no-op outside multi-tenant mode, where there is one role and no policy.
+func (h *DB) VerifyRoles(ctx context.Context) error {
+	if !h.binds() {
+		return nil
+	}
+
+	var super, bypass bool
+	if err := h.DB.QueryRowContext(ctx,
+		`SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`).Scan(&super, &bypass); err != nil {
+		return fmt.Errorf("read the application role's attributes: %w", err)
+	}
+	if super || bypass {
+		return fmt.Errorf("the DATABASE_URL role bypasses row-level security (superuser=%v bypassrls=%v), "+
+			"so every workspace can read every other workspace's rows; it must be a NOBYPASSRLS, non-superuser role",
+			super, bypass)
+	}
+
+	var owned int
+	if err := h.DB.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM pg_tables
+		 WHERE schemaname = current_schema() AND tableowner = current_user`).Scan(&owned); err != nil {
+		return fmt.Errorf("count tables owned by the application role: %w", err)
+	}
+	if owned > 0 {
+		return fmt.Errorf("the DATABASE_URL role owns %d tables in this schema; "+
+			"it must not own them, or its row-level-security policies do not apply to it "+
+			"(FORCE covers the owner, but relying on that leaves no margin)", owned)
+	}
+
+	platform := h.Platform()
+	if platform == h {
+		return errors.New("multi-tenant mode has no platform handle; open the pair with db.OpenPair")
+	}
+	var pSuper, pBypass bool
+	if err := platform.DB.QueryRowContext(ctx,
+		`SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`).Scan(&pSuper, &pBypass); err != nil {
+		return fmt.Errorf("read the platform role's attributes: %w", err)
+	}
+	if !pSuper && !pBypass {
+		return errors.New("the DATABASE_ADMIN_URL role neither is a superuser nor has BYPASSRLS, " +
+			"so it cannot read across workspaces: the worker would claim no jobs and the reconciler would " +
+			"enumerate nothing, silently")
+	}
+
+	return nil
+}
diff --git a/internal/db/pair_test.go b/internal/db/pair_test.go
new file mode 100644
index 0000000..22b3c3b
--- /dev/null
+++ b/internal/db/pair_test.go
@@ -0,0 +1,446 @@
+package db_test
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"net/url"
+	"sync"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgconn"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// Boundary 2: the two handles, and the per-statement tenant binding.
+//
+// Everything that matters here needs a NOBYPASSRLS application role, for the
+// reason rls_proof_test.go spells out at length: through a superuser handle these
+// assertions pass whether the binding works or not. The harness is shared with
+// that file.
+
+// tenantPair is a live OpenPair against the test schema, with the application
+// handle connected as a NOBYPASSRLS role that owns nothing.
+type tenantPair struct {
+	app      *db.DB // DATABASE_URL — the application role
+	platform *db.DB // DATABASE_ADMIN_URL — the owner, which bypasses
+	owner    *db.DB // the suite's own migrated handle, for fixtures and control reads
+}
+
+func openTenantPair(t *testing.T) tenantPair {
+	t.Helper()
+
+	owner := dbtest.RequirePostgres(t)
+	seedTwoWorkspaces(t, owner)
+	if err := owner.EnableRLS(context.Background()); err != nil {
+		t.Fatalf("EnableRLS: %v", err)
+	}
+
+	role := newAppRole(t, owner) // skips loudly if it cannot be non-superuser
+	role.handle.Close()          // OpenPair opens its own; this one was only the probe
+
+	// The platform DSN is the suite's own, pinned to the test's schema. In this
+	// harness that role is the superuser that owns the schema, which is exactly
+	// what DATABASE_ADMIN_URL is in production: owner plus BYPASSRLS.
+	platformDSN := withSchema(t, dbtest.PostgresDSN(), role.schema)
+
+	app, platform, err := db.OpenPair(role.dsn, platformDSN)
+	if err != nil {
+		t.Fatalf("OpenPair: %v", err)
+	}
+	t.Cleanup(func() {
+		app.Close()
+		platform.Close()
+	})
+
+	// The guard that makes the '' binding on the platform handle safe, and that
+	// would catch an application role able to read everything.
+	if err := app.VerifyRoles(context.Background()); err != nil {
+		t.Fatalf("VerifyRoles: %v", err)
+	}
+
+	return tenantPair{app: app, platform: platform, owner: owner}
+}
+
+func withSchema(t *testing.T, dsn, schema string) string {
+	t.Helper()
+	u, err := url.Parse(dsn)
+	if err != nil {
+		t.Fatalf("parse %s: %v", dbtest.DSNEnv, err)
+	}
+	q := u.Query()
+	q.Set("search_path", schema)
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+// TestOpenPair_workspaceHandleSeesOnlyItsOwn walks every statement shape a
+// workspace handle offers. Each one is asserted twice: A sees its own row, and A
+// does not see B's.
+func TestOpenPair_workspaceHandleSeesOnlyItsOwn(t *testing.T) {
+	p := openTenantPair(t)
+	a := p.app.ForWorkspace("ws-a")
+
+	if got := a.Workspace(); got != "ws-a" {
+		t.Errorf("Workspace() = %q; want ws-a", got)
+	}
+
+	t.Run("QueryRow", func(t *testing.T) {
+		var n int
+		if err := a.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&n); err != nil {
+			t.Fatalf("scan: %v", err)
+		}
+		if n != 1 {
+			t.Errorf("count = %d; want 1 of the 2 users", n)
+		}
+		var email string
+		err := a.QueryRow(`SELECT email FROM users WHERE id = ?`, "u-b").Scan(&email)
+		if !errors.Is(err, sql.ErrNoRows) {
+			t.Errorf("reading B's user gave (%q, %v); want sql.ErrNoRows", email, err)
+		}
+		assertIdle(t, a, "after two QueryRow/Scan pairs")
+	})
+
+	t.Run("Query", func(t *testing.T) {
+		rows, err := a.Query(`SELECT id FROM users ORDER BY id`)
+		if err != nil {
+			t.Fatalf("query: %v", err)
+		}
+		// The positive control on the release assertion: while the cursor is open
+		// the connection IS held, so the zero after Close means something.
+		if inUse := a.Stats().InUse; inUse != 1 {
+			t.Errorf("with a cursor open the pool reports InUse=%d; want 1", inUse)
+		}
+		var ids []string
+		for rows.Next() {
+			var id string
+			if err := rows.Scan(&id); err != nil {
+				t.Fatalf("scan: %v", err)
+			}
+			ids = append(ids, id)
+		}
+		if err := rows.Err(); err != nil {
+			t.Fatalf("rows.Err: %v", err)
+		}
+		if err := rows.Close(); err != nil {
+			t.Fatalf("rows.Close: %v", err)
+		}
+		if len(ids) != 1 || ids[0] != "u-a" {
+			t.Errorf("ids = %v; want [u-a]", ids)
+		}
+		assertIdle(t, a, "after Rows.Close")
+	})
+
+	t.Run("Exec", func(t *testing.T) {
+		// An UPDATE with no workspace predicate. It must reach A's row and not B's.
+		res, err := a.Exec(`UPDATE users SET name = ?`, "renamed")
+		if err != nil {
+			t.Fatalf("update: %v", err)
+		}
+		n, err := res.RowsAffected()
+		if err != nil {
+			t.Fatalf("rows affected: %v", err)
+		}
+		if n != 1 {
+			t.Errorf("an unscoped UPDATE touched %d rows; want 1", n)
+		}
+		var bName string
+		if err := p.owner.QueryRow(`SELECT name FROM users WHERE id = ?`, "u-b").Scan(&bName); err != nil {
+			t.Fatalf("read B through the owner: %v", err)
+		}
+		if bName == "renamed" {
+			t.Error("the UPDATE reached B's row")
+		}
+		assertIdle(t, a, "after Exec")
+	})
+
+	t.Run("Tx", func(t *testing.T) {
+		tx, err := a.Begin()
+		if err != nil {
+			t.Fatalf("begin: %v", err)
+		}
+		defer tx.Rollback() //nolint:errcheck // the standard pattern; release must be idempotent
+
+		if inUse := a.Stats().InUse; inUse != 1 {
+			t.Errorf("with a transaction open the pool reports InUse=%d; want 1", inUse)
+		}
+		if got := tx.Workspace(); got != "ws-a" {
+			t.Errorf("tx.Workspace() = %q; want ws-a", got)
+		}
+
+		var n int
+		if err := tx.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&n); err != nil {
+			t.Fatalf("count in tx: %v", err)
+		}
+		if n != 1 {
+			t.Errorf("inside a transaction, count = %d; want 1", n)
+		}
+		if _, err := tx.Exec(`INSERT INTO teams (id, name, slug) VALUES (?, ?, ?)`, "t-a", "A", "a"); err != nil {
+			t.Fatalf("insert in tx: %v", err)
+		}
+		if err := tx.Commit(); err != nil {
+			t.Fatalf("commit: %v", err)
+		}
+		assertIdle(t, a, "after Commit (and the deferred Rollback that follows)")
+
+		var ws string
+		if err := p.owner.QueryRow(`SELECT workspace_id FROM teams WHERE id = ?`, "t-a").Scan(&ws); err != nil {
+			t.Fatalf("read the team through the owner: %v", err)
+		}
+		if ws != "ws-a" {
+			t.Errorf("the team inserted in the transaction landed in %q; want ws-a", ws)
+		}
+	})
+}
+
+// TestOpenPair_insertNamesNoColumn is D1's payoff: the ~200 INSERT statements in
+// the tree do not mention workspace_id and must not have to.
+func TestOpenPair_insertNamesNoColumn(t *testing.T) {
+	p := openTenantPair(t)
+	a := p.app.ForWorkspace("ws-a")
+
+	if _, err := a.Exec(
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		"u-a2", "a2@example.com", "A2"); err != nil {
+		t.Fatalf("insert: %v", err)
+	}
+	var ws string
+	if err := p.owner.QueryRow(`SELECT workspace_id FROM users WHERE id = ?`, "u-a2").Scan(&ws); err != nil {
+		t.Fatalf("read back through the owner: %v", err)
+	}
+	if ws != "ws-a" {
+		t.Errorf("the row landed in %q; want ws-a", ws)
+	}
+	assertIdle(t, a, "after Exec")
+}
+
+// TestOpenPair_insertIntoAnotherWorkspaceIsRefused: the WITH CHECK half. A
+// handle bound to A cannot write into B even by naming it.
+func TestOpenPair_insertIntoAnotherWorkspaceIsRefused(t *testing.T) {
+	p := openTenantPair(t)
+	a := p.app.ForWorkspace("ws-a")
+
+	_, err := a.Exec(
+		`INSERT INTO users (id, email, name, workspace_id) VALUES (?, ?, ?, ?)`,
+		"u-cross", "cross@example.com", "X", "ws-b")
+	if err == nil {
+		t.Fatal("writing into ws-b through A's handle succeeded")
+	}
+	var pgErr *pgconn.PgError
+	if !errors.As(err, &pgErr) || pgErr.Code != "42501" {
+		t.Errorf("error was %v; want SQLSTATE 42501 (the row-level-security violation)", err)
+	}
+	var n int
+	if err := p.owner.QueryRow(`SELECT COUNT(*) FROM users WHERE id = ?`, "u-cross").Scan(&n); err != nil {
+		t.Fatalf("count through the owner: %v", err)
+	}
+	if n != 0 {
+		t.Error("the refused row is in the table")
+	}
+	assertIdle(t, a, "after a refused Exec")
+}
+
+// TestOpenPair_platformHandleSeesBoth. It is the handle the worker, the
+// reconciler and every credential lookup run on, and those are meaningless if it
+// cannot read across workspaces.
+func TestOpenPair_platformHandleSeesBoth(t *testing.T) {
+	p := openTenantPair(t)
+
+	var n int
+	if err := p.platform.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&n); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+	if n != 2 {
+		t.Errorf("the platform handle sees %d users; want both", n)
+	}
+	if got := p.platform.Workspace(); got != "" {
+		t.Errorf("platform Workspace() = %q; want empty", got)
+	}
+	// It binds '' anyway, which is what keeps "every statement on a paired handle
+	// sets the parameter" free of exceptions.
+	if !p.platform.MultiTenant() {
+		t.Error("the platform handle should still bind, even though it bypasses")
+	}
+	assertIdle(t, p.platform, "after QueryRow on the platform handle")
+
+	// And Platform() on the app handle is that same handle, so nothing downstream
+	// has to carry both.
+	if p.app.Platform() != p.platform {
+		t.Error("app.Platform() is not the platform handle OpenPair returned")
+	}
+	if p.app.ForWorkspace("ws-a").Platform() != p.platform {
+		t.Error("a workspace handle lost its platform handle")
+	}
+}
+
+// TestOpenPair_unboundAppHandleMatchesNothing: the pair's base app handle is not
+// a back door. It binds ”, which no workspace id can equal.
+func TestOpenPair_unboundAppHandleMatchesNothing(t *testing.T) {
+	p := openTenantPair(t)
+
+	var n int
+	if err := p.app.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&n); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+	if n != 0 {
+		t.Errorf("the unbound application handle sees %d users; want 0", n)
+	}
+}
+
+// TestOpenPair_handleSurvivesItsRequest is why the binding is per statement
+// rather than a pinned connection: Calnode's handlers spawn fire-and-forget
+// goroutines (notify hosts, enqueue the webhook, enqueue reminders) that outlive
+// the request. A handle that pinned a session would be unusable there.
+func TestOpenPair_handleSurvivesItsRequest(t *testing.T) {
+	p := openTenantPair(t)
+
+	// The "request": builds the handle, returns, goes out of scope.
+	handle := func() *db.DB { return p.app.ForWorkspace("ws-a") }()
+
+	var wg sync.WaitGroup
+	errs := make(chan error, 4)
+	for i := 0; i < 4; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			var email string
+			if err := handle.QueryRow(`SELECT email FROM users`).Scan(&email); err != nil {
+				errs <- err
+				return
+			}
+			if email != "a@example.com" {
+				errs <- errors.New("goroutine read " + email)
+			}
+		}()
+	}
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		t.Error(err)
+	}
+	assertIdle(t, handle, "after four concurrent goroutine reads")
+}
+
+// TestForWorkspace_rejectsAMalformedID. The id is a bind parameter, never SQL
+// text, so this is not an injection defence — it is a guard against a caller
+// passing something that is not an id and getting a handle that silently matches
+// nothing.
+func TestForWorkspace_rejectsAMalformedID(t *testing.T) {
+	p := openTenantPair(t)
+
+	for _, bad := range []string{
+		"", "WS-A", "ws a", "ws'a", "ws;a", "../etc", "a@b.com",
+		"0123456789012345678901234567890123456789012345678901234567890123456789", // 70 chars
+	} {
+		h := p.app.ForWorkspace(bad)
+		if h.Err() == nil {
+			t.Errorf("ForWorkspace(%q) produced a usable handle", bad)
+			continue
+		}
+		if !errors.Is(h.Err(), db.ErrInvalidWorkspace) {
+			t.Errorf("ForWorkspace(%q) err = %v; want ErrInvalidWorkspace", bad, h.Err())
+		}
+		// Every statement shape has to refuse, not just report.
+		var n int
+		if err := h.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&n); !errors.Is(err, db.ErrInvalidWorkspace) {
+			t.Errorf("QueryRow on a poisoned handle gave %v", err)
+		}
+		if _, err := h.Query(`SELECT 1`); !errors.Is(err, db.ErrInvalidWorkspace) {
+			t.Errorf("Query on a poisoned handle gave %v", err)
+		}
+		if _, err := h.Exec(`SELECT 1`); !errors.Is(err, db.ErrInvalidWorkspace) {
+			t.Errorf("Exec on a poisoned handle gave %v", err)
+		}
+		if _, err := h.Begin(); !errors.Is(err, db.ErrInvalidWorkspace) {
+			t.Errorf("Begin on a poisoned handle gave %v", err)
+		}
+	}
+
+	for _, good := range []string{"default", "ws-a", "a", "acme_corp", "ws-0123"} {
+		if h := p.app.ForWorkspace(good); h.Err() != nil {
+			t.Errorf("ForWorkspace(%q) = %v; want a usable handle", good, h.Err())
+		}
+	}
+	assertIdle(t, p.app, "no statement should have reached the pool")
+}
+
+// TestOpenPair_prepareIsRefusedOnABoundHandle. A *sql.Stmt is re-prepared on
+// whatever connection the pool hands it, with no hook to bind the tenant first,
+// so it would run unbound and silently see nothing. Refusing is the only safe
+// answer; nothing in the tree prepares a statement.
+func TestOpenPair_prepareIsRefusedOnABoundHandle(t *testing.T) {
+	p := openTenantPair(t)
+	if _, err := p.app.ForWorkspace("ws-a").Prepare(`SELECT 1`); err == nil {
+		t.Fatal("Prepare on a tenant-bound handle succeeded")
+	}
+}
+
+// TestOpenPair_refusesSQLite: the library refuses the combination its caller is
+// already supposed to have refused, because a library that only works when its
+// caller validated is one that will be called by something else one day.
+func TestOpenPair_refusesSQLite(t *testing.T) {
+	if _, _, err := db.OpenPair("sqlite://:memory:", "postgres://x:y@h/db"); err == nil {
+		t.Error("OpenPair accepted a SQLite application DSN")
+	}
+	if _, _, err := db.OpenPair("postgres://x:y@h/db", "sqlite://:memory:"); err == nil {
+		t.Error("OpenPair accepted a SQLite platform DSN")
+	}
+}
+
+// TestSingleHandle_forWorkspaceIsIdentity is the byte-identical promise at the
+// handle layer. On SQLite and on single-tenant PostgreSQL, ForWorkspace returns
+// the same handle, Platform returns the same handle, and no statement acquires a
+// connection of its own or sets a session parameter — so nothing about an
+// existing deployment changes.
+func TestSingleHandle_forWorkspaceIsIdentity(t *testing.T) {
+	handle := dbtest.Open(t)
+
+	if handle.MultiTenant() {
+		t.Error("a handle from OpenDB should not bind a tenant")
+	}
+	if handle.ForWorkspace("ws-a") != handle {
+		t.Error("ForWorkspace returned a different handle on a single handle")
+	}
+	// Not even a malformed id, because there is nothing to validate against: one
+	// workspace, no parameter to bind.
+	if handle.ForWorkspace("NOT AN ID") != handle {
+		t.Error("ForWorkspace validated on a single handle; it should be the identity function")
+	}
+	if handle.Platform() != handle {
+		t.Error("Platform() should be the handle itself when there is one role")
+	}
+	if got := handle.Workspace(); got != "" {
+		t.Errorf("Workspace() = %q; want empty", got)
+	}
+	// Prepare stays available, which it is on every existing deployment.
+	stmt, err := handle.Prepare(`SELECT COUNT(*) FROM users`)
+	if err != nil {
+		t.Fatalf("Prepare on a single handle: %v", err)
+	}
+	stmt.Close()
+
+	if dbtest.PostgresDSN() == "" {
+		t.Log("SQLite: the tenant-binding cases in this file are skipped — there is no row-level " +
+			"security to enforce isolation with, which is why config.Validate refuses MULTI_TENANT " +
+			"without a postgres:// DSN. ForWorkspace being the identity function IS the SQLite behaviour.")
+	}
+}
+
+// TestSingleHandle_verifyRolesIsANoOp: boot code needs no dialect or mode branch.
+func TestSingleHandle_verifyRolesIsANoOp(t *testing.T) {
+	if err := dbtest.Open(t).VerifyRoles(context.Background()); err != nil {
+		t.Errorf("VerifyRoles on a single handle: %v", err)
+	}
+}
+
+// assertIdle is the release proof. Every statement shape hands its connection
+// back, so the pool returns to zero in use; a shape that leaked would show up
+// here as a number that only ever grows.
+func assertIdle(t *testing.T, handle *db.DB, when string) {
+	t.Helper()
+	if inUse := handle.Stats().InUse; inUse != 0 {
+		t.Errorf("pool reports InUse=%d %s; the connection was not released", inUse, when)
+	}
+}
diff --git a/internal/db/postgres_test.go b/internal/db/postgres_test.go
index 9a23767..42311f2 100644
--- a/internal/db/postgres_test.go
+++ b/internal/db/postgres_test.go
@@ -3,7 +3,6 @@ package db_test
 import (
 	"context"
 	"crypto/rand"
-	"database/sql"
 	"encoding/hex"
 	"net/url"
 	"os"
@@ -603,7 +602,7 @@ func postgresColumns(t *testing.T, handle *db.DB) map[string][]string {
 	return schema
 }
 
-func scanStrings(t *testing.T, rows *sql.Rows) []string {
+func scanStrings(t *testing.T, rows *db.Rows) []string {
 	t.Helper()
 	defer rows.Close()
 
diff --git a/internal/db/rls_proof_test.go b/internal/db/rls_proof_test.go
index a932de6..a7fb9f6 100644
--- a/internal/db/rls_proof_test.go
+++ b/internal/db/rls_proof_test.go
@@ -35,6 +35,8 @@ import (
 // appRole is a non-superuser application role with a handle opened as it.
 type appRole struct {
 	name   string
+	dsn    string // the suite's DSN rewritten for this role, search_path pinned
+	schema string
 	handle *db.DB
 }
 
@@ -92,7 +94,8 @@ func newAppRole(t *testing.T, owner *db.DB) *appRole {
 		}
 	}
 
-	handle, err := db.OpenDB(appDSN(t, dsn, name, password, schema))
+	roleDSN := appDSN(t, dsn, name, password, schema)
+	handle, err := db.OpenDB(roleDSN)
 	if err != nil {
 		t.Fatalf("open as %s: %v", name, err)
 	}
@@ -113,7 +116,7 @@ func newAppRole(t *testing.T, owner *db.DB) *appRole {
 			"its own policy unless FORCE is set", schema)
 	}
 
-	return &appRole{name: name, handle: handle}
+	return &appRole{name: name, dsn: roleDSN, schema: schema, handle: handle}
 }
 
 // ownsNothing reports whether the connected role owns none of the schema's
diff --git a/internal/handler/availability.go b/internal/handler/availability.go
index 3eb766e..a147aee 100644
--- a/internal/handler/availability.go
+++ b/internal/handler/availability.go
@@ -71,7 +71,7 @@ func (h *Handler) ListAvailabilityRules(w http.ResponseWriter, r *http.Request)
 	user, _ := userFromContext(r.Context())
 
 	var (
-		rows *sql.Rows
+		rows *db.Rows
 		err  error
 	)
 	if etID := r.URL.Query().Get("event_type_id"); etID != "" {
diff --git a/internal/handler/livekit_recording.go b/internal/handler/livekit_recording.go
index d8f6b37..21c1535 100644
--- a/internal/handler/livekit_recording.go
+++ b/internal/handler/livekit_recording.go
@@ -11,6 +11,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/dbtime"
 	"github.com/calnode/calnode/internal/livekit"
 	"github.com/calnode/calnode/internal/uid"
@@ -299,7 +300,7 @@ func (h *Handler) ListRecordingConsent(w http.ResponseWriter, r *http.Request) {
 		DecidedAt string `json:"decided_at"`
 	}
 	out := []consent{}
-	var rows *sql.Rows
+	var rows *db.Rows
 	var err error
 	if scoped {
 		rows, err = h.db.QueryContext(r.Context(), `

From ec655421022e00e7d40f75de369790e170eed3cb Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 01:36:14 -0400
Subject: [PATCH 28/51] handler: split the process state off the request, and
 resolve a tenant per request
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boundary 3, part one of two. This lands the foundation; the 163 mux registrations
in internal/server/server.go, the route-classification test, the five end-to-end
request tests and the /v1/bookings/{id} tenant check follow in part two.

Handler was 30 fields including six sync.RWMutex. Giving 314 methods a
tenant-bound h.db without editing any of them means handing them a receiver that
differs in that field, so Handler is copied per request — and a struct holding a
mutex cannot be copied. So `shared` holds everything the process has one of and
Handler is { *shared; db; ws; bookingSvc; webhookSvc }. Embedding as *shared
rather than naming it is what keeps h.logger, h.livekitMu and h.mailer = m
compiling: the split needed zero edits across the 61 files of the package, and go
vet copylocks is clean. bookingSvc and webhookSvc each wrap a *db.DB, so
forWorkspace rebuilds them through new (*Service).ForDB methods.

RequireAuth's api_keys and sessions reads move to the platform handle. On the
application handle they run bound to the workspace of the request, and the
workspace of the request is what they exist to discover — so they would find
nothing and report a valid API key invalid. Both now select u.workspace_id into
the new AuthUser.WorkspaceID. This is why D9 keeps those two uniques global.

Four refusals, none of which is "carry on unscoped": unknown host 404, suspended
503, mismatch 403 {"error":"workspace mismatch"}, unresolved 500. There is
deliberately no fallback to the default workspace on an unrecognised host — that
would serve one tenant's booking page on any domain pointed at the instance — and
00060 seeds public_host empty for `default` so no request can land on it either.
Proved failable by making HostWorkspace fall back: three assertions catch it,
including "the method ran 1 times; wantReach=false".

Scoped takes a method EXPRESSION, (*Handler).Method. A bound method value would
capture the unscoped receiver, which is the bug this wrapper exists to prevent,
and it would compile silently. Platform(method) is the sibling for routes that
belong to no workspace, so "unscoped, on purpose" is stated at registration
rather than implied by omission.

publicURL() returns https://<ws.public_host> in multi-tenant mode and ignores
PUBLIC_BASE_URL entirely; single-tenant is unchanged.

Not implemented and not faked, both blocked on feat/platform-hooks being absent
from this clone: the OAuth callback SSO hand-off (D11) and the
(workspace_id, client_ip) rate-limit keys (D14). Each is a TODO(integration) in
PROGRESS.md naming the function expected. Noted with them: the platform /metrics
endpoint reads the jobs table and must use Platform() at integration, since jobs
is a tenant table.

gofmt -l empty, go vet clean, go test ./... rc=0 on SQLite (28/28) and rc=0 on
PostgreSQL (28/28).
---
 PROGRESS.md                                 | 131 ++++++
 internal/booking/service.go                 |   9 +
 internal/handler/auth.go                    |  28 +-
 internal/handler/embed_handler_test.go      |   6 +-
 internal/handler/handler.go                 |  80 ++--
 internal/handler/shared.go                  |  72 ++++
 internal/handler/workspace.go               | 333 ++++++++++++++++
 internal/handler/workspace_internal_test.go | 416 ++++++++++++++++++++
 internal/server/server.go                   |   2 +
 internal/webhook/webhook.go                 |   9 +
 10 files changed, 1036 insertions(+), 50 deletions(-)
 create mode 100644 internal/handler/shared.go
 create mode 100644 internal/handler/workspace.go
 create mode 100644 internal/handler/workspace_internal_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 06bec2c..5b892ae 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -628,3 +628,134 @@ operator tools today; B3 and B6 decide what they become.
 `go test ./...` **rc=0 on SQLite (28/28)** and **rc=0 on PostgreSQL (28/28)**.
 The 11 new cases all run rather than skip on the PostgreSQL lane, and the
 tenant-binding ones skip with a stated reason on SQLite.
+
+## Boundary 3 — handler scoping and tenant resolution — PART ONE of two
+
+⚠️ **B3 is not finished.** This commit lands the foundation: the `shared` split,
+the `Workspace` type, the two resolvers, `Scoped`, `Platform`, the refusal
+mapping, `AuthUser.WorkspaceID`, and the credential lookups moved onto the
+platform handle. What remains is the part that touches `internal/server/server.go`:
+**163 `mux.HandleFunc` registrations** have to be rewritten through
+`h.Scoped(resolve, (*Handler).Method)`, and with them the route-classification
+test, the five end-to-end request tests, and the `/v1/bookings/{id}` tenant check.
+Split because the registration rewrite is a single mechanical edit across 163
+lines that has to land with its own gate, not because either half is optional.
+
+### The split, and why the mutexes had to move
+
+`Handler` was 30 fields including **six `sync.RWMutex`**. A tenant-scoped request
+needs a handler whose `db` is bound to its workspace, and the only way to give
+**314 methods** a bound `h.db` without editing all of them is to hand them a
+receiver that differs in that one field — so `Handler` is copied per request. A
+struct containing a mutex cannot be copied (`go vet` copylocks, and rightly:
+copying a mutex copies its state).
+
+So: `shared` holds everything the process has one of — logger, mailer, the
+hot-swappable integration clients and their mutexes, the configured hosts, demo
+bookkeeping — and `Handler` is `{ *shared; db; ws; bookingSvc; webhookSvc }`.
+Embedding as `*shared` rather than naming it is what keeps `h.logger`,
+`h.livekitMu`, `h.mailer = m` and the rest compiling **untouched across all 61
+files**. Measured: the split needed zero edits to any handler method, and
+`go vet ./...` is clean.
+
+`bookingSvc` and `webhookSvc` stay on `Handler` because each wraps a `*db.DB`;
+`forWorkspace` rebuilds them from the scoped handle through new
+`(*Service).ForDB` methods on `internal/booking` and `internal/webhook`. Both are
+structs over a pool, so a rebuild is one allocation and pins nothing.
+
+### ⛔ Credential lookups had to move to the platform handle
+
+`RequireAuth`'s two reads — `api_keys` and `sessions` — ran on `h.db`. On a
+multi-tenant instance the application handle is bound to the workspace **of the
+request**, and the workspace of the request is what those reads exist to
+DISCOVER. Bound, they find nothing, and a perfectly good API key is reported
+`invalid API key`. Both now use `h.platformDB()` (`h.db.Platform()`, which is the
+same handle in single-tenant mode) and both select `u.workspace_id` into the new
+`AuthUser.WorkspaceID`. This is the reason D9 keeps `api_keys.key_hash` and
+`sessions.id` globally unique.
+
+### Four refusals, and none of them is "carry on unscoped"
+
+`errUnknownHost` → **404** (HTML: the host-resolved surfaces are pages a person is
+looking at). `errWorkspaceSuspended` → **503** + `Retry-After`.
+`errWorkspaceMismatch` → **403 `{"error":"workspace mismatch"}`**, which is the
+body D10 specifies and a test pins. `errNoWorkspace` → **500**.
+
+⛔ There is deliberately **no fallback to the default workspace** on an
+unrecognised host. Falling back would serve one tenant's booking page on any
+domain pointed at the instance. Migration 00060 seeds `workspaces.public_host`
+empty for `default` for the same reason: no HTTP request carries an empty Host, so
+the default workspace is unreachable by host resolution. Both are asserted.
+
+Proved failable by making `HostWorkspace` return `DefaultWorkspace` on a failed
+lookup — the exact bug:
+
+```
+--- FAIL: TestHostWorkspace_multiTenant/unknown_host_does_not_fall_back_to_default
+    workspace_internal_test.go:102: resolved &{ID:default Slug:default PublicHost: Region: Status:active}; want an error
+--- FAIL: TestHostWorkspace_multiTenant/the_default_workspace_is_unreachable_by_host
+    workspace_internal_test.go:117: an empty Host resolved; err = <nil>
+--- FAIL: TestScoped_refusalsNeverReachTheMethod/unknown_host_is_404
+    workspace_internal_test.go:230: status = 200; want 404 (body "{\"workspace\":\"default\"}\n")
+    workspace_internal_test.go:233: the method ran 1 times; wantReach=false
+```
+
+### `Scoped` takes a method EXPRESSION, and the compiler enforces it
+
+`h.Scoped(HostWorkspace, (*Handler).BookPage)`, not `h.Scoped(…, h.BookPage)`. A
+bound method value would capture the **unscoped** receiver, which is exactly the
+bug the wrapper exists to prevent, and it would compile silently. A method
+expression cannot: its first parameter is the receiver, which `Scoped` supplies
+from `forWorkspace`.
+
+`Platform(method)` is the sibling for routes that belong to no workspace — the
+identity host's OAuth endpoints, `/.well-known/*`, `/healthz`, `/readyz`,
+`/version`, `/metrics`, the platform API. It exists so "unscoped, on purpose" is
+something the registration says out loud rather than by omission, which is what
+the route-classification test in part two will hold.
+
+### `publicURL()` is per workspace
+
+In multi-tenant mode it returns `https://<ws.public_host>` and `PUBLIC_BASE_URL`
+is ignored entirely (D11); `BASE_URL` stays the identity host of the process.
+Single-tenant is unchanged: `PUBLIC_BASE_URL` if set, else `BASE_URL`. Four cases
+pinned.
+
+### Scope of the tests here, stated so it is not overread
+
+`workspace_internal_test.go` runs against ONE handle with `multiTenant` set. That
+is enough for everything it asserts, because resolution reads `workspaces` through
+`platformDB()` and on a single handle that is the handle itself. It does **not**
+re-prove the row-level-security binding — that needs a NOBYPASSRLS role and is
+already proven in `internal/db` (`rls_proof_test.go`, `pair_test.go`). The
+end-to-end request tests in part two are where a real pair gets exercised through
+HTTP.
+
+### TODO(integration) — blocked on `feat/platform-hooks`
+
+Neither is implemented, and neither is faked:
+
+- **D11, the OAuth login hand-off.** After a Google/Microsoft callback on the
+  identity host, the callback cannot set a cookie for the workspace's public host,
+  so it must mint an SSO token for the workspace carried in the OAuth `state` and
+  redirect to `https://<public_host>/v1/auth/sso?token=…`. That endpoint arrives
+  with `feat/platform-hooks`, which is **not in this clone**. Expected shape at
+  integration: the branch's SSO issue/verify pair, extended per the packet with a
+  required `wid` claim and an `aud` equal to the workspace's public host.
+  `finishOAuthLogin` in `internal/handler/auth_oauth.go` is where the redirect
+  replaces the cookie set.
+- **D14, rate-limit keys.** They should become `(workspace_id, client_ip)` using
+  that branch's `TRUSTED_PROXY_CIDRS`-aware client-IP helper. Expected shape:
+  `handler.clientIP(r) string`. Today's limiters key on the TCP remote address
+  (`ARCHITECTURE` §16 says so deliberately), and prefixing the workspace without
+  the helper would key a whole tenant behind one proxy as a single client.
+- **The platform `/metrics` endpoint**, also on that branch, reads the `jobs`
+  table. At integration it **must** read through `Platform()`: `jobs` is a tenant
+  table and an application-handle read would report one workspace's queue, or on
+  the unbound handle, zero.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+`go test ./...` **rc=0 on SQLite (28/28)** and **rc=0 on PostgreSQL (28/28)**.
+The 21 new resolver cases all run on both lanes.
diff --git a/internal/booking/service.go b/internal/booking/service.go
index 2695e62..3ef8fe2 100644
--- a/internal/booking/service.go
+++ b/internal/booking/service.go
@@ -27,6 +27,15 @@ func New(db *db.DB) *Service {
 	return &Service{db: db}
 }
 
+// ForDB returns a copy of s backed by handle. It is how a per-request handler
+// gets a booking service bound to its workspace: the Service is a struct over a
+// pool, so this costs one allocation and pins nothing.
+func (s *Service) ForDB(handle *db.DB) *Service {
+	copied := *s
+	copied.db = handle
+	return &copied
+}
+
 // Create inserts a new confirmed booking inside a transaction.
 // It checks for overlapping bookings for every host in p.HostIDs before
 // inserting, satisfying the double-booking guard described in §6.4.
diff --git a/internal/handler/auth.go b/internal/handler/auth.go
index 0fef5b1..ae6528d 100644
--- a/internal/handler/auth.go
+++ b/internal/handler/auth.go
@@ -15,7 +15,13 @@ const ctxKeyUser contextKey = "user"
 
 // AuthUser is the authenticated caller stored in request context.
 type AuthUser struct {
-	ID         string
+	ID string
+
+	// WorkspaceID is the tenant this caller belongs to, read from the same row as
+	// the rest. It is what CredentialWorkspace resolves the request's workspace
+	// from, and it is "default" in single-tenant mode.
+	WorkspaceID string
+
 	Email      string
 	Name       string
 	IANATZ     string
@@ -68,13 +74,17 @@ func (h *Handler) RequireAuth(next http.HandlerFunc) http.HandlerFunc {
 			var user AuthUser
 			var keyID string
 			var nc, nca, nr, nrm, nhb, nhc, nhr int
-			err := h.db.QueryRowContext(r.Context(), `
-				SELECT ak.id, u.id, u.email, u.name, u.iana_timezone, u.time_format, u.week_start, u.date_format, COALESCE(u.avatar_url,''), u.is_admin, u.is_owner,
+			// ⛔ platformDB, not h.db. api_keys.key_hash is global precisely so a
+			// key resolves without a tenant, and the tenant is what this read
+			// DISCOVERS — on the workspace-bound handle it would find nothing and
+			// a valid key would be reported invalid.
+			err := h.platformDB().QueryRowContext(r.Context(), `
+				SELECT ak.id, u.id, u.workspace_id, u.email, u.name, u.iana_timezone, u.time_format, u.week_start, u.date_format, COALESCE(u.avatar_url,''), u.is_admin, u.is_owner,
 				       COALESCE(u.notify_confirmation,1), COALESCE(u.notify_cancellation,1), COALESCE(u.notify_reschedule,1), COALESCE(u.notify_reminder,1),
 				       COALESCE(u.notify_host_booking,1), COALESCE(u.notify_host_cancel,1), COALESCE(u.notify_host_reschedule,1)
 				FROM api_keys ak JOIN users u ON u.id = ak.user_id
 				WHERE ak.key_hash = ? AND u.archived_at IS NULL`, hash).
-				Scan(&keyID, &user.ID, &user.Email, &user.Name, &user.IANATZ, &user.TimeFormat, &user.WeekStart, &user.DateFormat, &user.AvatarURL, &user.IsAdmin, &user.IsOwner,
+				Scan(&keyID, &user.ID, &user.WorkspaceID, &user.Email, &user.Name, &user.IANATZ, &user.TimeFormat, &user.WeekStart, &user.DateFormat, &user.AvatarURL, &user.IsAdmin, &user.IsOwner,
 					&nc, &nca, &nr, &nrm, &nhb, &nhc, &nhr)
 			user.NotifyConfirmation, user.NotifyCancellation, user.NotifyReschedule, user.NotifyReminder = nc != 0, nca != 0, nr != 0, nrm != 0
 			user.NotifyHostBooking, user.NotifyHostCancel, user.NotifyHostReschedule = nhb != 0, nhc != 0, nhr != 0
@@ -83,7 +93,7 @@ func (h *Handler) RequireAuth(next http.HandlerFunc) http.HandlerFunc {
 				return
 			}
 			now := time.Now().UTC().Format(time.RFC3339Nano)
-			_, _ = h.db.ExecContext(r.Context(),
+			_, _ = h.platformDB().ExecContext(r.Context(),
 				`UPDATE api_keys SET last_used_at = ? WHERE id = ?`, now, keyID)
 			next(w, r.WithContext(context.WithValue(r.Context(), ctxKeyUser, user)))
 			return
@@ -94,15 +104,17 @@ func (h *Handler) RequireAuth(next http.HandlerFunc) http.HandlerFunc {
 			now := time.Now().UTC().Format(time.RFC3339)
 			var user AuthUser
 			var nc, nca, nr, nrm, nhb, nhc, nhr int
-			if err := h.db.QueryRowContext(r.Context(), `
-				SELECT u.id, u.email, u.name, u.iana_timezone, u.time_format, u.week_start, u.date_format, COALESCE(u.avatar_url,''), u.is_admin, u.is_owner,
+			// platformDB for the same reason as the API-key path above:
+			// sessions.id is global so a cookie resolves without a tenant.
+			if err := h.platformDB().QueryRowContext(r.Context(), `
+				SELECT u.id, u.workspace_id, u.email, u.name, u.iana_timezone, u.time_format, u.week_start, u.date_format, COALESCE(u.avatar_url,''), u.is_admin, u.is_owner,
 				       COALESCE(u.notify_confirmation,1), COALESCE(u.notify_cancellation,1), COALESCE(u.notify_reschedule,1), COALESCE(u.notify_reminder,1),
 				       COALESCE(u.notify_host_booking,1), COALESCE(u.notify_host_cancel,1), COALESCE(u.notify_host_reschedule,1)
 				FROM sessions s
 				JOIN users u ON u.id = s.user_id
 				WHERE s.id = ? AND s.expires_at > ? AND u.archived_at IS NULL`,
 				cookie.Value, now).
-				Scan(&user.ID, &user.Email, &user.Name, &user.IANATZ, &user.TimeFormat, &user.WeekStart, &user.DateFormat, &user.AvatarURL, &user.IsAdmin, &user.IsOwner,
+				Scan(&user.ID, &user.WorkspaceID, &user.Email, &user.Name, &user.IANATZ, &user.TimeFormat, &user.WeekStart, &user.DateFormat, &user.AvatarURL, &user.IsAdmin, &user.IsOwner,
 					&nc, &nca, &nr, &nrm, &nhb, &nhc, &nhr); err == nil {
 				user.NotifyConfirmation, user.NotifyCancellation, user.NotifyReschedule, user.NotifyReminder = nc != 0, nca != 0, nr != 0, nrm != 0
 				user.NotifyHostBooking, user.NotifyHostCancel, user.NotifyHostReschedule = nhb != 0, nhc != 0, nhr != 0
diff --git a/internal/handler/embed_handler_test.go b/internal/handler/embed_handler_test.go
index 42654eb..ff12ec9 100644
--- a/internal/handler/embed_handler_test.go
+++ b/internal/handler/embed_handler_test.go
@@ -12,7 +12,7 @@ import (
 // (b) answer If-None-Match with a 304 — that's what lets a redeploy propagate within
 // minutes instead of being pinned for the full max-age.
 func TestEmbedJS_etagRevalidation(t *testing.T) {
-	h := &Handler{}
+	h := &Handler{shared: &shared{}}
 
 	rec := httptest.NewRecorder()
 	h.EmbedJS(rec, httptest.NewRequest(http.MethodGet, "/embed.js", nil))
@@ -53,7 +53,7 @@ func TestEmbedJS_etagRevalidation(t *testing.T) {
 // disclosure element pulls from the fetched i18n map (t(this.i18n, 'assistant_disclosure')),
 // not a hardcoded literal that could silently diverge again.
 func TestEmbedJS_assistantDisclosure(t *testing.T) {
-	h := &Handler{}
+	h := &Handler{shared: &shared{}}
 	rec := httptest.NewRecorder()
 	h.EmbedJS(rec, httptest.NewRequest(http.MethodGet, "/embed.js", nil))
 	body := rec.Body.String()
@@ -67,7 +67,7 @@ func TestEmbedJS_assistantDisclosure(t *testing.T) {
 }
 
 func TestBookingCSS_cacheModes(t *testing.T) {
-	h := &Handler{}
+	h := &Handler{shared: &shared{}}
 
 	// Unversioned: short cache + revalidate + ETag.
 	rec := httptest.NewRecorder()
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index cf68ce8..c95198d 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -4,7 +4,6 @@ import (
 	"encoding/hex"
 	"log/slog"
 	"net/http"
-	"sync"
 	"time"
 
 	"golang.org/x/oauth2"
@@ -21,36 +20,27 @@ import (
 	"github.com/calnode/calnode/internal/zoom"
 )
 
+// Handler is a per-request value: the process-wide state behind *shared, plus the
+// database handle and workspace this particular request is scoped to.
+//
+// In single-tenant mode there is one Handler and one workspace ("default"), and
+// nothing copies it. In multi-tenant mode Scoped makes a copy per request whose
+// db is bound to the resolved workspace, so a method body that reads h.db is
+// tenant-scoped without being edited. The copy is a value with no locks in it,
+// which is what keeps go vet copylocks clean — and it pins no connection, so a
+// fire-and-forget goroutine may keep the copy it was started with (see
+// db.DB.ForWorkspace).
 type Handler struct {
-	db                *db.DB
-	logger            *slog.Logger
-	bookingSvc        *booking.Service
-	mailer            mailer.Mailer
-	live              *mailer.Live // non-nil in production; nil in tests using a direct stub
-	encKey            [32]byte     // AES-256 key for encrypting secrets stored in the DB
-	calMu             sync.RWMutex
-	cal               *calendar.Service
-	calNudge          chan struct{} // buffered(1): wakes the calendar reconciler after a failed inline op
-	webhookSvc        *webhook.Service
-	baseURL           string
-	publicBaseURL     string
-	dataDir           string
-	authMu            sync.RWMutex
-	googleAuth        *oauth2.Config
-	microsoftAuth     *oauth2.Config
-	secureCookie      bool
-	llmMu             sync.RWMutex
-	llm               *llm.Client // nil when the optional LLM layer is off/unconfigured
-	zoomMu            sync.RWMutex
-	zoom              *zoom.Client // nil when no Zoom app is configured
-	stripeMu          sync.RWMutex
-	stripe            *stripe.Client // nil when payments are unconfigured
-	livekitMu         sync.RWMutex
-	livekit           *livekit.Client // nil when LiveKit video is unconfigured
-	demoMode          bool            // true on the public demo instance: disables calendar/Zoom connect
-	demoResetInterval time.Duration
-	demoMu            sync.RWMutex
-	demoNextResetAt   time.Time
+	*shared
+
+	db *db.DB
+	ws *Workspace
+
+	// bookingSvc and webhookSvc wrap a *db.DB, so they are per-request too:
+	// forWorkspace rebuilds each from the scoped handle. Both are cheap structs
+	// over a pool, not connections.
+	bookingSvc *booking.Service
+	webhookSvc *webhook.Service
 }
 
 // SetLiveKit swaps the active LiveKit client (nil disables built-in video rooms).
@@ -123,15 +113,18 @@ func (h *Handler) getLLM() *llm.Client {
 	return h.llm
 }
 
-func New(db *db.DB, logger *slog.Logger) *Handler {
-	whs, _ := webhook.New(db, "") // ephemeral key when no encryption key configured
+func New(database *db.DB, logger *slog.Logger) *Handler {
+	whs, _ := webhook.New(database, "") // ephemeral key when no encryption key configured
 	return &Handler{
-		db:         db,
-		logger:     logger,
-		bookingSvc: booking.New(db),
-		mailer:     &mailer.Noop{},
+		shared: &shared{
+			logger:   logger,
+			mailer:   &mailer.Noop{},
+			calNudge: make(chan struct{}, 1),
+		},
+		db:         database,
+		ws:         DefaultWorkspace,
+		bookingSvc: booking.New(database),
 		webhookSvc: whs,
-		calNudge:   make(chan struct{}, 1),
 	}
 }
 
@@ -165,9 +158,18 @@ func (h *Handler) SetPublicBaseURL(url string) {
 	h.publicBaseURL = url
 }
 
-// publicURL returns the booker-facing base URL, defaulting to the identity host
-// (baseURL) when no public host has been configured.
+// publicURL returns the booker-facing base URL.
+//
+// In multi-tenant mode each workspace has its own public host and that replaces
+// PUBLIC_BASE_URL entirely (D11): booking links, emails, embed snippets and the
+// admin UI all live there, while BASE_URL stays the identity host of the whole
+// process for OAuth callbacks, /.well-known/*, /oauth/*, /mcp and the platform
+// API. Single-tenant behaviour is unchanged: PUBLIC_BASE_URL if set, else
+// BASE_URL.
 func (h *Handler) publicURL() string {
+	if h.multiTenant && h.ws != nil && h.ws.PublicHost != "" {
+		return "https://" + h.ws.PublicHost
+	}
 	if h.publicBaseURL != "" {
 		return h.publicBaseURL
 	}
diff --git a/internal/handler/shared.go b/internal/handler/shared.go
new file mode 100644
index 0000000..e31e3d9
--- /dev/null
+++ b/internal/handler/shared.go
@@ -0,0 +1,72 @@
+package handler
+
+import (
+	"log/slog"
+	"sync"
+	"time"
+
+	"golang.org/x/oauth2"
+
+	"github.com/calnode/calnode/internal/calendar"
+	"github.com/calnode/calnode/internal/livekit"
+	"github.com/calnode/calnode/internal/llm"
+	"github.com/calnode/calnode/internal/mailer"
+	"github.com/calnode/calnode/internal/stripe"
+	"github.com/calnode/calnode/internal/zoom"
+)
+
+// shared is everything one process has exactly one of: the logger, the mailer,
+// the hot-swappable integration clients and the mutexes guarding them, the
+// configured hosts, and the demo-mode bookkeeping.
+//
+// It exists so Handler can be a cheap VALUE. A tenant-scoped request needs a
+// handler whose db is bound to its workspace, and the only way to give 314
+// methods a bound `h.db` without editing all of them is to hand them a receiver
+// that differs in that field — so Handler is copied per request. A struct
+// holding six sync.RWMutex cannot be copied (go vet copylocks, and rightly:
+// copying a mutex copies its state), so the mutexes live behind this pointer,
+// which every copy shares.
+//
+// Embedding it as *shared rather than naming it keeps `h.logger`, `h.mailer`,
+// `h.livekitMu` and the rest compiling unchanged across the package.
+type shared struct {
+	logger *slog.Logger
+	mailer mailer.Mailer
+	live   *mailer.Live // non-nil in production; nil in tests using a direct stub
+	encKey [32]byte     // AES-256 key for encrypting secrets stored in the DB
+
+	calMu    sync.RWMutex
+	cal      *calendar.Service
+	calNudge chan struct{} // buffered(1): wakes the calendar reconciler after a failed inline op
+
+	baseURL       string
+	publicBaseURL string
+	dataDir       string
+
+	authMu        sync.RWMutex
+	googleAuth    *oauth2.Config
+	microsoftAuth *oauth2.Config
+	secureCookie  bool
+
+	llmMu sync.RWMutex
+	llm   *llm.Client // nil when the optional LLM layer is off/unconfigured
+
+	zoomMu sync.RWMutex
+	zoom   *zoom.Client // nil when no Zoom app is configured
+
+	stripeMu sync.RWMutex
+	stripe   *stripe.Client // nil when payments are unconfigured
+
+	livekitMu sync.RWMutex
+	livekit   *livekit.Client // nil when LiveKit video is unconfigured
+
+	demoMode          bool // true on the public demo instance: disables calendar/Zoom connect
+	demoResetInterval time.Duration
+	demoMu            sync.RWMutex
+	demoNextResetAt   time.Time
+
+	// multiTenant mirrors config.MultiTenant. It is what turns host and
+	// credential resolution on; unset, every request runs on the default
+	// workspace and the handler behaves exactly as it did before.
+	multiTenant bool
+}
diff --git a/internal/handler/workspace.go b/internal/handler/workspace.go
new file mode 100644
index 0000000..4681f52
--- /dev/null
+++ b/internal/handler/workspace.go
@@ -0,0 +1,333 @@
+package handler
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// errNoRows is sql.ErrNoRows under a shorter name, because the two workspace
+// reads below both branch on it and the line is long enough already.
+var errNoRows = sql.ErrNoRows
+
+// Workspace is a tenant. In single-tenant mode there is exactly one, and it is
+// DefaultWorkspace.
+type Workspace struct {
+	ID         string
+	Slug       string
+	PublicHost string
+	Region     string
+	Status     string
+}
+
+// Suspended reports whether this workspace's public and admin surfaces should
+// answer 503 (D12).
+func (w *Workspace) Suspended() bool { return w != nil && w.Status == "suspended" }
+
+// DefaultWorkspace is the tenant every request runs as when MULTI_TENANT is
+// unset. Its id is the literal migration 00060 seeds and the SQLite column
+// default, so a single-tenant database and a single-tenant handler agree without
+// either having to ask.
+//
+// Its PublicHost is deliberately empty: publicURL falls back to
+// PUBLIC_BASE_URL/BASE_URL for it, which is exactly the behaviour every existing
+// deployment has.
+var DefaultWorkspace = &Workspace{
+	ID:     db.DefaultWorkspaceID,
+	Slug:   db.DefaultWorkspaceID,
+	Status: "active",
+}
+
+// The four ways resolution fails, each with its own response. They are values
+// rather than status codes at the call site so a resolver can say what happened
+// and one place decides what the client sees.
+var (
+	// errUnknownHost — the request's Host names no workspace. 404, and
+	// deliberately NOT a fallback to the default workspace: on a multi-tenant
+	// instance that would serve one tenant's booking page on an unrecognised
+	// domain (D10).
+	errUnknownHost = errors.New("handler: no workspace for this host")
+
+	// errWorkspaceSuspended — 503 on public and admin surfaces.
+	errWorkspaceSuspended = errors.New("handler: workspace suspended")
+
+	// errWorkspaceMismatch — the credential resolved workspace A and the Host
+	// names workspace B. 403 {"error":"workspace mismatch"} (D10).
+	errWorkspaceMismatch = errors.New("handler: workspace mismatch")
+
+	// errNoWorkspace — a resolver returned nothing and no reason. A bug, and a
+	// 500: an unscoped read on a multi-tenant database is the one outcome that
+	// must never be reachable by accident.
+	errNoWorkspace = errors.New("handler: no workspace resolved")
+)
+
+// SetMultiTenant turns host and credential resolution on. Unset — the default —
+// every request runs on DefaultWorkspace and nothing about the handler changes.
+func (h *Handler) SetMultiTenant(v bool) { h.multiTenant = v }
+
+// MultiTenant reports whether this handler resolves a tenant per request.
+func (h *Handler) MultiTenant() bool { return h.multiTenant }
+
+// Workspace returns the workspace this handler is scoped to. Never nil.
+func (h *Handler) Workspace() *Workspace {
+	if h.ws == nil {
+		return DefaultWorkspace
+	}
+	return h.ws
+}
+
+// platformDB is the handle for reads that must cross workspaces, or that happen
+// before a workspace is known: resolving a host, resolving a credential,
+// enumerating tenants. In single-tenant mode it is the same handle as h.db.
+//
+// ⛔ Every credential lookup has to go through this. An api_keys or sessions read
+// on the application handle runs bound to the workspace of the request, and the
+// workspace of the request is what the credential is being read to DISCOVER — so
+// it would find nothing, and the caller would see "invalid API key" for a
+// perfectly good key.
+func (h *Handler) platformDB() *db.DB { return h.db.Platform() }
+
+// forWorkspace returns a copy of h scoped to ws.
+//
+// A value copy, so it costs an allocation and no locks: *shared is a pointer that
+// every copy shares, and db.ForWorkspace pins no connection. That is what makes
+// it safe for a handler to start a goroutine and let the request return —
+// Calnode does that on every booking (notify hosts, enqueue the webhook, enqueue
+// reminders).
+func (h *Handler) forWorkspace(ws *Workspace) *Handler {
+	if ws == nil {
+		ws = DefaultWorkspace
+	}
+	scoped := *h
+	scoped.ws = ws
+	if !h.multiTenant {
+		// Nothing to bind: one workspace, and db.ForWorkspace is the identity
+		// function on a single handle anyway. Returning early keeps the
+		// single-tenant path allocation-for-allocation what it was.
+		return &scoped
+	}
+	scoped.db = h.db.ForWorkspace(ws.ID)
+	scoped.bookingSvc = h.bookingSvc.ForDB(scoped.db)
+	scoped.webhookSvc = h.webhookSvc.ForDB(scoped.db)
+	return &scoped
+}
+
+// Resolver decides which workspace a request belongs to. The two that exist are
+// HostWorkspace and CredentialWorkspace; a route picks one at registration.
+type Resolver func(*Handler, *http.Request) (*Workspace, error)
+
+// Scoped is the ONLY way a tenant route reaches a bound handle.
+//
+// It resolves the workspace, builds the per-request copy, and calls method on it.
+// A request that resolves no workspace never reaches the method: it gets 404, 503,
+// 403 or 500, because the alternative — running the method on an unscoped handle —
+// is a cross-tenant read on a multi-tenant database.
+//
+// method is a method EXPRESSION, e.g. h.Scoped(HostWorkspace, (*Handler).BookPage),
+// not a bound method value. That is deliberate and the compiler enforces it: a
+// bound value would capture the unscoped receiver, which is precisely the bug this
+// wrapper exists to make impossible.
+func (h *Handler) Scoped(resolve Resolver, method func(*Handler, http.ResponseWriter, *http.Request)) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		ws, err := resolve(h, r)
+		switch {
+		case err != nil:
+			h.writeResolveError(w, r, err)
+			return
+		case ws == nil:
+			h.writeResolveError(w, r, errNoWorkspace)
+			return
+		}
+		method(h.forWorkspace(ws), w, r)
+	}
+}
+
+// Platform wraps a route that runs on the platform handle and belongs to no
+// workspace: the identity host's OAuth endpoints, /.well-known/*, /healthz,
+// /readyz, /version, /metrics and the platform API (D11).
+//
+// It exists so that "which routes are unscoped, and on purpose" is a question the
+// registration answers out loud rather than by omission.
+func (h *Handler) Platform(method func(*Handler, http.ResponseWriter, *http.Request)) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		platform := *h
+		platform.ws = DefaultWorkspace
+		if h.multiTenant {
+			platform.db = h.db.Platform()
+			platform.bookingSvc = h.bookingSvc.ForDB(platform.db)
+			platform.webhookSvc = h.webhookSvc.ForDB(platform.db)
+		}
+		method(&platform, w, r)
+	}
+}
+
+// writeResolveError turns a resolution failure into a response.
+//
+// The unknown-host case is an HTML 404 rather than JSON because the surfaces that
+// resolve by host are pages a person is looking at — a booking page, a manage
+// link, the admin UI. Everything else is JSON, since a mismatch or a suspension
+// is something a client has to read.
+func (h *Handler) writeResolveError(w http.ResponseWriter, r *http.Request, err error) {
+	switch {
+	case errors.Is(err, errUnknownHost):
+		h.logger.WarnContext(r.Context(), "no workspace for host", "host", r.Host, "path", r.URL.Path)
+		http.NotFound(w, r)
+	case errors.Is(err, errWorkspaceSuspended):
+		w.Header().Set("Retry-After", "3600")
+		h.writeError(w, http.StatusServiceUnavailable, "workspace suspended")
+	case errors.Is(err, errWorkspaceMismatch):
+		h.writeError(w, http.StatusForbidden, "workspace mismatch")
+	default:
+		h.logger.ErrorContext(r.Context(), "resolve workspace", "error", err,
+			"host", r.Host, "path", r.URL.Path)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+	}
+}
+
+// HostWorkspace resolves the tenant from the request Host. It is the resolver for
+// every public and admin surface: /book/{slug}, /v1/event-types/{slug}/*,
+// POST /v1/bookings, /embed.js, /manage/{token}, /room/{room}, /admin/*, and the
+// branding files (D10).
+//
+// An unrecognised host is a 404. There is no default-tenant fallback, because on
+// a multi-tenant instance that would answer one tenant's booking page on a domain
+// nobody registered.
+func HostWorkspace(h *Handler, r *http.Request) (*Workspace, error) {
+	if !h.multiTenant {
+		return DefaultWorkspace, nil
+	}
+	ws, err := h.workspaceByHost(r.Context(), r.Host)
+	if err != nil {
+		return nil, err
+	}
+	if ws.Suspended() {
+		return nil, fmt.Errorf("%w: %s", errWorkspaceSuspended, ws.ID)
+	}
+	return ws, nil
+}
+
+// CredentialWorkspace resolves the tenant from the credential the request
+// carries, which the auth middleware has already verified and put in context.
+//
+// Credential first, then the Host as a CHECK rather than a source (D10): an API
+// key belongs to a user, a user belongs to a workspace, and that is the
+// authoritative answer. If the Host also names a workspace and the two disagree,
+// the request is refused 403 rather than either one silently winning.
+func CredentialWorkspace(h *Handler, r *http.Request) (*Workspace, error) {
+	if !h.multiTenant {
+		return DefaultWorkspace, nil
+	}
+	user, ok := userFromContext(r.Context())
+	if !ok {
+		// Scoped ran before the auth middleware, or the route is registered with
+		// the wrong resolver. Either way it is a bug, not a client error.
+		return nil, fmt.Errorf("%w: no authenticated caller in context", errNoWorkspace)
+	}
+	if user.WorkspaceID == "" {
+		return nil, fmt.Errorf("%w: authenticated caller has no workspace", errNoWorkspace)
+	}
+	ws, err := h.workspaceByID(r.Context(), user.WorkspaceID)
+	if err != nil {
+		return nil, err
+	}
+	if ws.Suspended() {
+		return nil, fmt.Errorf("%w: %s", errWorkspaceSuspended, ws.ID)
+	}
+	if err := h.hostAgrees(r, ws); err != nil {
+		return nil, err
+	}
+	return ws, nil
+}
+
+// hostAgrees refuses a request whose Host names a DIFFERENT workspace from the
+// one its credential resolved. A Host that names no workspace at all is fine:
+// that is the identity host, which is where API and MCP callers legitimately
+// arrive.
+func (h *Handler) hostAgrees(r *http.Request, ws *Workspace) error {
+	host := hostOnly(r.Host)
+	if host == "" || host == hostOnly(h.baseURL) {
+		return nil
+	}
+	byHost, err := h.workspaceByHost(r.Context(), r.Host)
+	if errors.Is(err, errUnknownHost) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	if byHost.ID != ws.ID {
+		return fmt.Errorf("%w: credential is %s, host %s is %s", errWorkspaceMismatch, ws.ID, host, byHost.ID)
+	}
+	return nil
+}
+
+// workspaceByHost reads a workspace by its public host, through the platform
+// handle: the application handle is bound to the workspace of the request, and
+// this read is what determines that.
+func (h *Handler) workspaceByHost(ctx context.Context, requestHost string) (*Workspace, error) {
+	host := hostOnly(requestHost)
+	if host == "" {
+		return nil, fmt.Errorf("%w: empty Host header", errUnknownHost)
+	}
+	var ws Workspace
+	err := h.platformDB().QueryRowContext(ctx,
+		`SELECT id, slug, public_host, region, status FROM workspaces WHERE public_host = ?`, host).
+		Scan(&ws.ID, &ws.Slug, &ws.PublicHost, &ws.Region, &ws.Status)
+	if err != nil {
+		if errors.Is(err, errNoRows) {
+			return nil, fmt.Errorf("%w: %s", errUnknownHost, host)
+		}
+		return nil, fmt.Errorf("read workspace by host %s: %w", host, err)
+	}
+	return &ws, nil
+}
+
+// workspaceByID reads a workspace by id, through the platform handle.
+func (h *Handler) workspaceByID(ctx context.Context, id string) (*Workspace, error) {
+	var ws Workspace
+	err := h.platformDB().QueryRowContext(ctx,
+		`SELECT id, slug, public_host, region, status FROM workspaces WHERE id = ?`, id).
+		Scan(&ws.ID, &ws.Slug, &ws.PublicHost, &ws.Region, &ws.Status)
+	if err != nil {
+		if errors.Is(err, errNoRows) {
+			// The credential names a workspace that no longer exists. Not the
+			// client's fault and not an unknown host either: a deleted workspace
+			// whose sessions have outlived it.
+			return nil, fmt.Errorf("%w: credential names workspace %q, which does not exist", errNoWorkspace, id)
+		}
+		return nil, fmt.Errorf("read workspace %s: %w", id, err)
+	}
+	return &ws, nil
+}
+
+// hostOnly strips a port, a scheme and any trailing slash, so a request Host
+// ("book.acme.com:8443") and a configured URL ("https://book.acme.com/") compare
+// equal to the public_host column, which stores the bare hostname.
+//
+// Lower-cased because DNS is case-insensitive and a browser will happily send
+// whatever the user typed.
+func hostOnly(host string) string {
+	h := strings.TrimSpace(host)
+	if i := strings.Index(h, "://"); i >= 0 {
+		h = h[i+3:]
+	}
+	h = strings.TrimSuffix(h, "/")
+	if i := strings.IndexByte(h, '/'); i >= 0 {
+		h = h[:i]
+	}
+	// IPv6 literals arrive as [::1]:8080; the brackets are part of the host.
+	if strings.HasPrefix(h, "[") {
+		if end := strings.IndexByte(h, ']'); end >= 0 {
+			return strings.ToLower(h[:end+1])
+		}
+	}
+	if i := strings.LastIndexByte(h, ':'); i >= 0 && !strings.Contains(h[i+1:], ".") {
+		h = h[:i]
+	}
+	return strings.ToLower(h)
+}
diff --git a/internal/handler/workspace_internal_test.go b/internal/handler/workspace_internal_test.go
new file mode 100644
index 0000000..fecf880
--- /dev/null
+++ b/internal/handler/workspace_internal_test.go
@@ -0,0 +1,416 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// These are internal tests because the pieces under test are: hostOnly,
+// forWorkspace, and the four resolution errors.
+//
+// They run against ONE handle with multiTenant set, which is enough for
+// everything here: resolution reads the workspaces table through platformDB, and
+// on a single handle that is the handle itself. What they deliberately do not
+// re-prove is the row-level-security binding — that needs a NOBYPASSRLS role and
+// is already proven in internal/db (rls_proof_test.go, pair_test.go). Splitting it
+// that way keeps this file about the resolver's decisions.
+
+func newResolverHandler(t *testing.T, multiTenant bool) *Handler {
+	t.Helper()
+	database := dbtest.Open(t)
+	h := New(database, slog.Default())
+	h.SetMultiTenant(multiTenant)
+	h.SetBaseURL("https://app.calnode.test")
+	return h
+}
+
+func seedWorkspace(t *testing.T, h *Handler, id, host, status string) {
+	t.Helper()
+	if _, err := h.db.Exec(
+		`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', ?)`,
+		id, id, host, status); err != nil {
+		t.Fatalf("seed workspace %s: %v", id, err)
+	}
+}
+
+func TestHostOnly(t *testing.T) {
+	cases := map[string]string{
+		"book.acme.com":               "book.acme.com",
+		"book.acme.com:8443":          "book.acme.com",
+		"https://book.acme.com":       "book.acme.com",
+		"https://book.acme.com/":      "book.acme.com",
+		"https://book.acme.com/admin": "book.acme.com",
+		"BOOK.ACME.COM":               "book.acme.com",
+		"  book.acme.com  ":           "book.acme.com",
+		"localhost:3000":              "localhost",
+		"[::1]:8080":                  "[::1]",
+		"":                            "",
+	}
+	for in, want := range cases {
+		if got := hostOnly(in); got != want {
+			t.Errorf("hostOnly(%q) = %q; want %q", in, got, want)
+		}
+	}
+}
+
+// TestHostWorkspace_singleTenantAlwaysDefault is the byte-identical promise at the
+// resolver layer: with MULTI_TENANT unset nothing is read and nothing can fail.
+func TestHostWorkspace_singleTenantAlwaysDefault(t *testing.T) {
+	h := newResolverHandler(t, false)
+	for _, host := range []string{"book.acme.com", "nowhere.example", ""} {
+		r := httptest.NewRequest(http.MethodGet, "/book/intro", nil)
+		r.Host = host
+		ws, err := HostWorkspace(h, r)
+		if err != nil {
+			t.Fatalf("HostWorkspace(%q) = %v", host, err)
+		}
+		if ws != DefaultWorkspace {
+			t.Errorf("HostWorkspace(%q) = %+v; want DefaultWorkspace", host, ws)
+		}
+	}
+}
+
+func TestHostWorkspace_multiTenant(t *testing.T) {
+	h := newResolverHandler(t, true)
+	seedWorkspace(t, h, "acme", "book.acme.com", "active")
+	seedWorkspace(t, h, "globex", "book.globex.com", "suspended")
+
+	t.Run("known host", func(t *testing.T) {
+		r := httptest.NewRequest(http.MethodGet, "/book/intro", nil)
+		r.Host = "book.acme.com:8443"
+		ws, err := HostWorkspace(h, r)
+		if err != nil {
+			t.Fatalf("HostWorkspace: %v", err)
+		}
+		if ws.ID != "acme" {
+			t.Errorf("resolved %q; want acme", ws.ID)
+		}
+	})
+
+	t.Run("unknown host does not fall back to default", func(t *testing.T) {
+		r := httptest.NewRequest(http.MethodGet, "/book/intro", nil)
+		r.Host = "nobody.example"
+		ws, err := HostWorkspace(h, r)
+		if err == nil {
+			t.Fatalf("resolved %+v; want an error", ws)
+		}
+		// ⛔ The important half: not DefaultWorkspace. Falling back would serve
+		// one tenant's booking page on any domain pointed at the instance.
+		if !isErr(err, errUnknownHost) {
+			t.Errorf("err = %v; want errUnknownHost", err)
+		}
+	})
+
+	t.Run("the default workspace is unreachable by host", func(t *testing.T) {
+		// Migration 00060 seeds it with an empty public_host precisely so that no
+		// request can land on it, since no HTTP request carries an empty Host.
+		r := httptest.NewRequest(http.MethodGet, "/book/intro", nil)
+		r.Host = ""
+		if _, err := HostWorkspace(h, r); !isErr(err, errUnknownHost) {
+			t.Errorf("an empty Host resolved; err = %v", err)
+		}
+	})
+
+	t.Run("suspended", func(t *testing.T) {
+		r := httptest.NewRequest(http.MethodGet, "/book/intro", nil)
+		r.Host = "book.globex.com"
+		if _, err := HostWorkspace(h, r); !isErr(err, errWorkspaceSuspended) {
+			t.Errorf("err = %v; want errWorkspaceSuspended", err)
+		}
+	})
+}
+
+func TestCredentialWorkspace(t *testing.T) {
+	h := newResolverHandler(t, true)
+	seedWorkspace(t, h, "acme", "book.acme.com", "active")
+	seedWorkspace(t, h, "globex", "book.globex.com", "active")
+
+	withUser := func(r *http.Request, wsID string) *http.Request {
+		return r.WithContext(context.WithValue(r.Context(), ctxKeyUser,
+			AuthUser{ID: "u1", WorkspaceID: wsID}))
+	}
+
+	t.Run("credential decides", func(t *testing.T) {
+		r := withUser(httptest.NewRequest(http.MethodGet, "/v1/bookings", nil), "acme")
+		r.Host = "app.calnode.test" // the identity host: names no workspace
+		ws, err := CredentialWorkspace(h, r)
+		if err != nil {
+			t.Fatalf("CredentialWorkspace: %v", err)
+		}
+		if ws.ID != "acme" {
+			t.Errorf("resolved %q; want acme", ws.ID)
+		}
+	})
+
+	t.Run("host agreeing is fine", func(t *testing.T) {
+		r := withUser(httptest.NewRequest(http.MethodGet, "/v1/bookings", nil), "acme")
+		r.Host = "book.acme.com"
+		if _, err := CredentialWorkspace(h, r); err != nil {
+			t.Errorf("CredentialWorkspace: %v", err)
+		}
+	})
+
+	t.Run("host naming another workspace is a mismatch", func(t *testing.T) {
+		r := withUser(httptest.NewRequest(http.MethodGet, "/v1/bookings", nil), "acme")
+		r.Host = "book.globex.com"
+		if _, err := CredentialWorkspace(h, r); !isErr(err, errWorkspaceMismatch) {
+			t.Errorf("err = %v; want errWorkspaceMismatch", err)
+		}
+	})
+
+	t.Run("host naming no workspace at all is fine", func(t *testing.T) {
+		// API and MCP callers legitimately arrive on hosts that are not any
+		// tenant's public host.
+		r := withUser(httptest.NewRequest(http.MethodGet, "/v1/bookings", nil), "acme")
+		r.Host = "some-proxy.internal"
+		if _, err := CredentialWorkspace(h, r); err != nil {
+			t.Errorf("CredentialWorkspace: %v", err)
+		}
+	})
+
+	t.Run("no caller in context is a bug, not a client error", func(t *testing.T) {
+		r := httptest.NewRequest(http.MethodGet, "/v1/bookings", nil)
+		if _, err := CredentialWorkspace(h, r); !isErr(err, errNoWorkspace) {
+			t.Errorf("err = %v; want errNoWorkspace", err)
+		}
+	})
+
+	t.Run("a credential naming a deleted workspace", func(t *testing.T) {
+		r := withUser(httptest.NewRequest(http.MethodGet, "/v1/bookings", nil), "gone")
+		if _, err := CredentialWorkspace(h, r); !isErr(err, errNoWorkspace) {
+			t.Errorf("err = %v; want errNoWorkspace", err)
+		}
+	})
+}
+
+// TestScoped_refusalsNeverReachTheMethod is the load-bearing assertion of the
+// whole boundary: a request that resolves no tenant must not run the handler at
+// all. Running it would be an unscoped read on a multi-tenant database.
+func TestScoped_refusalsNeverReachTheMethod(t *testing.T) {
+	h := newResolverHandler(t, true)
+	seedWorkspace(t, h, "acme", "book.acme.com", "active")
+	seedWorkspace(t, h, "globex", "book.globex.com", "suspended")
+
+	var reached int
+	method := func(scoped *Handler, w http.ResponseWriter, r *http.Request) {
+		reached++
+		w.WriteHeader(http.StatusOK)
+		_ = json.NewEncoder(w).Encode(map[string]string{"workspace": scoped.Workspace().ID})
+	}
+
+	cases := []struct {
+		name       string
+		host       string
+		wantStatus int
+		wantBody   string // "" = do not check
+		wantReach  bool
+	}{
+		{name: "known host", host: "book.acme.com", wantStatus: 200, wantReach: true},
+		{name: "unknown host is 404", host: "nobody.example", wantStatus: 404},
+		{name: "suspended is 503", host: "book.globex.com", wantStatus: 503, wantBody: "workspace suspended"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			reached = 0
+			r := httptest.NewRequest(http.MethodGet, "/book/intro", nil)
+			r.Host = tc.host
+			rec := httptest.NewRecorder()
+
+			h.Scoped(HostWorkspace, method)(rec, r)
+
+			if rec.Code != tc.wantStatus {
+				t.Errorf("status = %d; want %d (body %q)", rec.Code, tc.wantStatus, rec.Body.String())
+			}
+			if (reached == 1) != tc.wantReach {
+				t.Errorf("the method ran %d times; wantReach=%v", reached, tc.wantReach)
+			}
+			if tc.wantBody != "" {
+				var body map[string]string
+				if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+					t.Fatalf("decode body %q: %v", rec.Body.String(), err)
+				}
+				if body["error"] != tc.wantBody {
+					t.Errorf("error = %q; want %q", body["error"], tc.wantBody)
+				}
+			}
+		})
+	}
+}
+
+func TestScoped_mismatchIs403WithTheDocumentedBody(t *testing.T) {
+	h := newResolverHandler(t, true)
+	seedWorkspace(t, h, "acme", "book.acme.com", "active")
+	seedWorkspace(t, h, "globex", "book.globex.com", "active")
+
+	var reached int
+	method := func(*Handler, http.ResponseWriter, *http.Request) { reached++ }
+
+	r := httptest.NewRequest(http.MethodGet, "/v1/bookings", nil)
+	r.Host = "book.globex.com"
+	r = r.WithContext(context.WithValue(r.Context(), ctxKeyUser, AuthUser{ID: "u1", WorkspaceID: "acme"}))
+	rec := httptest.NewRecorder()
+
+	h.Scoped(CredentialWorkspace, method)(rec, r)
+
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("status = %d; want 403", rec.Code)
+	}
+	var body map[string]string
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("decode %q: %v", rec.Body.String(), err)
+	}
+	// The body is part of the contract (D10).
+	if body["error"] != "workspace mismatch" {
+		t.Errorf("error = %q; want \"workspace mismatch\"", body["error"])
+	}
+	if reached != 0 {
+		t.Error("the method ran on a mismatched request")
+	}
+}
+
+// TestScoped_aResolverReturningNothingIs500: an unscoped read must not be
+// reachable even through a buggy resolver.
+func TestScoped_aResolverReturningNothingIs500(t *testing.T) {
+	h := newResolverHandler(t, true)
+	var reached int
+	rec := httptest.NewRecorder()
+
+	h.Scoped(
+		func(*Handler, *http.Request) (*Workspace, error) { return nil, nil },
+		func(*Handler, http.ResponseWriter, *http.Request) { reached++ },
+	)(rec, httptest.NewRequest(http.MethodGet, "/anything", nil))
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Errorf("status = %d; want 500", rec.Code)
+	}
+	if reached != 0 {
+		t.Error("the method ran with no workspace")
+	}
+}
+
+// TestForWorkspace_isACheapValue. The per-request copy shares *shared, so a
+// setting applied at boot is visible through every copy and a mutex is never
+// copied (which is what go vet copylocks would otherwise catch).
+func TestForWorkspace_isACheapValue(t *testing.T) {
+	h := newResolverHandler(t, true)
+	ws := &Workspace{ID: "acme", Slug: "acme", PublicHost: "book.acme.com", Status: "active"}
+
+	scoped := h.forWorkspace(ws)
+
+	if scoped == h {
+		t.Fatal("forWorkspace returned the same handler in multi-tenant mode")
+	}
+	if scoped.shared != h.shared {
+		t.Error("the copy does not share process state")
+	}
+	if scoped.Workspace().ID != "acme" {
+		t.Errorf("scoped workspace = %q", scoped.Workspace().ID)
+	}
+	if h.Workspace().ID != db.DefaultWorkspaceID {
+		t.Errorf("the base handler was mutated: %q", h.Workspace().ID)
+	}
+	if scoped.bookingSvc == h.bookingSvc {
+		t.Error("the booking service was not rebound to the scoped handle")
+	}
+	if scoped.webhookSvc == h.webhookSvc {
+		t.Error("the webhook service was not rebound to the scoped handle")
+	}
+	// A setting applied to the base handler after the copy is still visible,
+	// because *shared is shared.
+	h.SetDataDir("/tmp/somewhere")
+	if scoped.dataDir != "/tmp/somewhere" {
+		t.Error("the copy does not see later changes to process state")
+	}
+}
+
+// TestForWorkspace_singleTenantKeepsTheSameHandle: nothing is rebound and nothing
+// is bound, so an existing deployment runs the statements it always ran.
+func TestForWorkspace_singleTenantKeepsTheSameHandle(t *testing.T) {
+	h := newResolverHandler(t, false)
+	scoped := h.forWorkspace(&Workspace{ID: "acme"})
+
+	if scoped.db != h.db {
+		t.Error("the database handle was replaced in single-tenant mode")
+	}
+	if scoped.bookingSvc != h.bookingSvc {
+		t.Error("the booking service was rebuilt in single-tenant mode")
+	}
+	if scoped.webhookSvc != h.webhookSvc {
+		t.Error("the webhook service was rebuilt in single-tenant mode")
+	}
+}
+
+func TestPublicURL(t *testing.T) {
+	t.Run("single tenant keeps PUBLIC_BASE_URL", func(t *testing.T) {
+		h := newResolverHandler(t, false)
+		h.SetPublicBaseURL("https://book.acme.com")
+		if got := h.publicURL(); got != "https://book.acme.com" {
+			t.Errorf("publicURL() = %q", got)
+		}
+	})
+
+	t.Run("single tenant falls back to BASE_URL", func(t *testing.T) {
+		h := newResolverHandler(t, false)
+		if got := h.publicURL(); got != "https://app.calnode.test" {
+			t.Errorf("publicURL() = %q", got)
+		}
+	})
+
+	t.Run("multi tenant uses the workspace's host", func(t *testing.T) {
+		h := newResolverHandler(t, true)
+		h.SetPublicBaseURL("https://ignored.example")
+		scoped := h.forWorkspace(&Workspace{ID: "acme", PublicHost: "book.acme.com"})
+		if got := scoped.publicURL(); got != "https://book.acme.com" {
+			t.Errorf("publicURL() = %q; want the workspace's public host", got)
+		}
+	})
+
+	t.Run("multi tenant with no public host falls back", func(t *testing.T) {
+		// The default workspace, which exists but is unreachable by host.
+		h := newResolverHandler(t, true)
+		h.SetPublicBaseURL("https://fallback.example")
+		if got := h.publicURL(); got != "https://fallback.example" {
+			t.Errorf("publicURL() = %q", got)
+		}
+	})
+}
+
+// TestPlatform_runsOnThePlatformHandle: the identity-host routes are unscoped on
+// purpose, and say so at registration rather than by omission.
+func TestPlatform_runsOnThePlatformHandle(t *testing.T) {
+	h := newResolverHandler(t, true)
+	var seen string
+	rec := httptest.NewRecorder()
+
+	h.Platform(func(p *Handler, w http.ResponseWriter, r *http.Request) {
+		seen = p.Workspace().ID
+	})(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
+
+	if seen != db.DefaultWorkspaceID {
+		t.Errorf("a platform route ran as workspace %q", seen)
+	}
+}
+
+// isErr is errors.Is without the import, kept local because the four resolution
+// errors are wrapped with %w and compared by identity everywhere else.
+func isErr(err, target error) bool {
+	for err != nil {
+		if err == target {
+			return true
+		}
+		u, ok := err.(interface{ Unwrap() error })
+		if !ok {
+			return false
+		}
+		err = u.Unwrap()
+	}
+	return false
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index c17168d..12632c4 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -39,6 +39,8 @@ import (
 // has finished its current poll cycle.
 func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger) (*handler.Handler, func()) {
 	h := handler.New(db, logger)
+	// Before anything else: it decides whether every route resolves a tenant.
+	h.SetMultiTenant(cfg.MultiTenant)
 	h.SetBaseURL(cfg.BaseURL)
 	h.SetPublicBaseURL(cfg.PublicBaseURL)
 	h.SetDataDir("data")
diff --git a/internal/webhook/webhook.go b/internal/webhook/webhook.go
index 850bf94..530fafe 100644
--- a/internal/webhook/webhook.go
+++ b/internal/webhook/webhook.go
@@ -152,6 +152,15 @@ func New(db *db.DB, encKeyHex string) (*Service, error) {
 	return s, nil
 }
 
+// ForDB returns a copy of s backed by handle, keeping the same signing key. It is
+// how a per-request handler gets a webhook service bound to its workspace; the
+// Service is a struct over a pool, so this pins nothing.
+func (s *Service) ForDB(handle *db.DB) *Service {
+	copied := *s
+	copied.db = handle
+	return &copied
+}
+
 // Create registers a new webhook and returns the Webhook plus the plain-text
 // signing secret (shown only once; stored encrypted).
 // Create registers a webhook (fields default to the unset/original-payload set;

From 8dbab4a32c7e0a7c3e991d8df5236fbdc7e4c9f3 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 01:47:37 -0400
Subject: [PATCH 29/51] server,handler: every route says which tenant it
 resolves, and how
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boundary 3, part two. 160 registrations rewritten through Scoped/Platform, the
MCP mount scoped per workspace, and a gate that fails on a route added without a
wrapper. The end-to-end request tests through a real OpenPair are the one thing
part two still owes and land next, before B4.

169 routes: 31 host-scoped, 106 credential-scoped, 24 platform, 8 allowlisted.

type H = handler.Handler so a registration reads (*H).ListBookings. The brevity
is incidental; the method expression is the point. Scoped takes
func(*Handler, http.ResponseWriter, *http.Request), so passing h.ListBookings — a
bound value on the unscoped handler, the exact bug Scoped prevents — does not
compile. Credential routes are RequireAuth(Scoped(CredentialWorkspace, ...)) in
that order, since CredentialWorkspace reads the caller from context; a test checks
the nesting on all 106.

The gate reads server.go rather than walking the mux, because http.ServeMux
exposes no way to enumerate patterns and the thing to catch is a registration
written without a wrapper, which is a property of the text. Three guards against a
vacuous pass: a floor of 150 registrations, a floor of 3 per bucket, and a check
that every allowlist entry is still a live route. The allowlist's 8 entries are
all handlers that are not *handler.Handler methods: two empty CORS preflights, the
embedded favicon/SPA/redirects, the MCP mount. A second test pins the 24-member
platform set exactly against D11 with a reason per group, so a route moving on or
off the identity host cannot happen silently.

The gate earned itself on its first run: POST /v1/livekit/egress-webhook carries a
trailing // legacy alias comment, so the scripted rewrite's line pattern missed it
and it stayed unwrapped.

The MCP tools close over their handler, so the single server instance built at
boot would have run every workspace's tool calls on whichever handler built it.
/mcp is on the identity host and carries no tenant Host, so the credential is the
only source: MCPCallerMiddleware now also reads users.workspace_id (through the
platform handle, same reasoning as RequireAuth) and the factory becomes
MCPServerForRequest, which caches one server per workspace on shared. One entry
keyed "" in single-tenant mode, so that path is unchanged behaviour with a map in
front of it.

GET /v1/bookings/{id} is now host-scoped, so a booking id from another workspace
is not visible and the 404 comes from the policy rather than a predicate the
handler has to remember. It still has no auth middleware, alone among its
siblings; that is reported, not changed — adding auth to a route the booking page
may depend on is a product decision. What changes is the blast radius.

gofmt -l empty, go vet clean, go test ./... rc=0 on SQLite (28/28) and rc=0 on
PostgreSQL (28/28). Negative control, unwrapping GET /v1/bookings: 'route "GET
/v1/bookings" is unclassified: h.RequireAuth(h.ListBookings)'.
---
 PROGRESS.md                               |  85 ++++++
 internal/handler/mcp.go                   |  59 ++++
 internal/handler/mcp_oauth.go             |  27 +-
 internal/handler/shared.go                |   7 +
 internal/server/routes_classified_test.go | 226 +++++++++++++++
 internal/server/server.go                 | 338 +++++++++++-----------
 6 files changed, 576 insertions(+), 166 deletions(-)
 create mode 100644 internal/server/routes_classified_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 5b892ae..4e10e35 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -759,3 +759,88 @@ Neither is implemented, and neither is faked:
 `gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
 `go test ./...` **rc=0 on SQLite (28/28)** and **rc=0 on PostgreSQL (28/28)**.
 The 21 new resolver cases all run on both lanes.
+
+## Boundary 3, part two — the registrations, and the gate that keeps them honest
+
+⚠️ **The end-to-end request tests through a real `OpenPair` are NOT in this
+commit.** Everything else part two owed is: the 160 rewritten registrations, the
+MCP per-workspace scoping, the classification gate, and `/v1/bookings/{id}`. The
+e2e file is the next thing, before B4.
+
+### 169 routes, every one of them classified
+
+```
+169 routes: 31 host-scoped, 106 credential-scoped, 24 platform, 8 allowlisted
+```
+
+`type H = handler.Handler` in `internal/server` so a registration reads
+`(*H).ListBookings`. The brevity is incidental; the **method expression** is the
+point. `Scoped` takes `func(*Handler, http.ResponseWriter, *http.Request)`, so
+passing `h.ListBookings` — a bound method value on the *unscoped* handler, which
+is precisely the bug `Scoped` exists to prevent — **does not compile**.
+
+Credential-scoped routes are `h.RequireAuth(h.Scoped(handler.CredentialWorkspace,
+(*H).Method))`, in that order: `CredentialWorkspace` reads the caller out of the
+request context, so the auth middleware has to have run first.
+`TestCredentialScopedRoutesAuthenticateFirst` checks both the presence and the
+nesting order across all 106.
+
+### The gate, and why it reads the file
+
+`internal/server/routes_classified_test.go` scans `server.go` and fails on a
+registration that is neither `Scoped(HostWorkspace, …)`,
+`Scoped(CredentialWorkspace, …)`, `Platform(…)`, nor on an 8-entry allowlist whose
+every member is a handler that is **not a `*handler.Handler` method at all** (two
+empty CORS preflights, the embedded favicon/SPA/redirects, the MCP mount).
+
+⛔ A source scan rather than a runtime walk because `http.ServeMux` exposes no way
+to enumerate its patterns, and the thing to catch is a registration written
+without a wrapper — a property of the text. Three guards against a vacuous pass: a
+floor of 150 registrations, a floor of 3 per bucket (so a refactor that classified
+everything one way fails), and a check that every allowlist entry is still a live
+route.
+
+`TestPlatformRoutesAreTheIdentityHostSet` pins the 24-member platform set exactly
+against D11, with a one-line reason per group. A route joining or leaving the
+identity host is a decision about which host serves it, and this makes it
+impossible to make silently.
+
+⚠️ **The rewrite missed one route and the gate caught it.** `POST
+/v1/livekit/egress-webhook` carries a trailing `// legacy alias` comment, so the
+scripted edit's line pattern did not match it and it stayed unwrapped. That is the
+gate doing exactly the job it was written for, on its first run.
+
+### ⛔ The MCP tools close over their handler, so one cached server was wrong
+
+`/mcp` was `mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return
+mcpSrv }, nil)` over a single instance built at boot. The eight tools capture `h`,
+so **every workspace's tool calls would have run on whichever handler built that
+instance**. The mount is on the identity host and carries no tenant Host, so the
+credential is the only source (D10).
+
+`MCPCallerMiddleware` now also reads `users.workspace_id` — through
+`platformDB()`, same reasoning as `RequireAuth` — into `mcpCaller.WorkspaceID`,
+and the factory becomes `h.MCPServerForRequest`, which returns a server per
+workspace from a cache on `shared` (`map[string]*mcp.Server` behind an RWMutex).
+One entry keyed `""` in single-tenant mode, so that path is the old behaviour with
+a map in front of it. Building one allocates eight tool registrations and their
+JSON schemas, which is not something to do per request.
+
+### `/v1/bookings/{id}` — the tenant check is the scoping, and the missing auth is still missing
+
+`GET /v1/bookings/{id}` is now `h.Scoped(handler.HostWorkspace, (*H).GetBooking)`,
+so the handle it runs on is bound to the workspace of the request Host and a
+booking id belonging to another workspace is simply not visible — the 404 comes
+from the row not existing, enforced by the policy rather than by a predicate the
+handler has to remember.
+
+⚠️ **It still has no auth middleware at all**, alone among `/v1/bookings/{id}/*`
+(`server.go`, and every sibling is wrapped in `h.RequireAuth`). Reported in the
+first packet turn and deliberately not changed: adding auth to a route the booking
+page may depend on is a product decision, not a tenancy one. What multi-tenancy
+changes is the blast radius — it is now bounded to one workspace instead of the
+whole instance.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
diff --git a/internal/handler/mcp.go b/internal/handler/mcp.go
index 63d886d..c10b561 100644
--- a/internal/handler/mcp.go
+++ b/internal/handler/mcp.go
@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net/http"
 	"strings"
 	"time"
 
@@ -20,6 +21,64 @@ import (
 // transports: stdio (the `calnode mcp` subcommand, for local agents) and Streamable
 // HTTP (mounted at POST /mcp behind API-key auth, for remote agents). Tools call the
 // same internal services the REST handlers use — no parallel code path.
+// MCPServerForRequest returns the MCP server for the workspace the request's
+// bearer credential belongs to.
+//
+// ⛔ The tools close over their handler, so a single cached server would run every
+// workspace's tool calls on whichever handler built it. /mcp is mounted on the
+// identity host and carries no tenant Host, so the credential is the only source —
+// MCPCallerMiddleware has already resolved it into the request context by the time
+// this runs.
+//
+// One server per workspace, cached: building one allocates eight tool
+// registrations and their JSON schemas, which is not something to do per request.
+// In single-tenant mode there is exactly one entry, keyed "", so this is the old
+// "one instance reused across requests" with a map in front of it.
+func (h *Handler) MCPServerForRequest(r *http.Request) *mcp.Server {
+	wsID := ""
+	if h.multiTenant {
+		wsID = mcpCallerWorkspace(r.Context())
+	}
+
+	h.mcpMu.RLock()
+	cached := h.mcpServers[wsID]
+	h.mcpMu.RUnlock()
+	if cached != nil {
+		return cached
+	}
+
+	scoped := h
+	if wsID != "" {
+		// A workspace the credential named; resolution already happened, so a
+		// failure here means the row went away between the two reads.
+		ws, err := h.workspaceByID(r.Context(), wsID)
+		if err != nil {
+			h.logger.ErrorContext(r.Context(), "mcp: resolve caller workspace", "error", err)
+			// Bound to a workspace id that does not exist: under RLS this handle
+			// matches no row, which is the safe answer.
+			scoped = h.forWorkspace(&Workspace{ID: wsID, Status: "active"})
+		} else {
+			scoped = h.forWorkspace(ws)
+		}
+	}
+
+	built := scoped.MCPServer()
+
+	h.mcpMu.Lock()
+	if h.mcpServers == nil {
+		h.mcpServers = map[string]*mcp.Server{}
+	}
+	// Another request may have built it first; either is correct, keep one.
+	if existing := h.mcpServers[wsID]; existing != nil {
+		built = existing
+	} else {
+		h.mcpServers[wsID] = built
+	}
+	h.mcpMu.Unlock()
+
+	return built
+}
+
 func (h *Handler) MCPServer() *mcp.Server {
 	s := mcp.NewServer(&mcp.Implementation{
 		Name:    "calnode",
diff --git a/internal/handler/mcp_oauth.go b/internal/handler/mcp_oauth.go
index 330b9f1..b63abb8 100644
--- a/internal/handler/mcp_oauth.go
+++ b/internal/handler/mcp_oauth.go
@@ -37,6 +37,12 @@ const (
 type mcpCaller struct {
 	UserID  string
 	IsAdmin bool // owner or admin → full workspace access
+
+	// WorkspaceID is the tenant the bearer credential belongs to. The /mcp mount
+	// is on the identity host, so there is no Host to resolve from: the credential
+	// is the only source (D10). MCPServerForRequest reads it to hand the tools a
+	// handler bound to that workspace.
+	WorkspaceID string
 }
 
 type mcpCallerKey struct{}
@@ -50,6 +56,15 @@ func mcpCallerFromContext(ctx context.Context) (mcpCaller, bool) {
 	return c, ok
 }
 
+// mcpCallerWorkspace returns the workspace of the bound /mcp caller, or "" when
+// there is none (the stdio transport, run by the local operator).
+func mcpCallerWorkspace(ctx context.Context) string {
+	if c, ok := mcpCallerFromContext(ctx); ok {
+		return c.WorkspaceID
+	}
+	return ""
+}
+
 // mcpCallerScope returns the calling user's id and whether they have full-workspace
 // access. No bound caller (the stdio transport, run by the local operator) → full
 // access; an admin/owner over HTTP → full access; a member → scoped to their own
@@ -83,9 +98,15 @@ func (h *Handler) MCPCallerMiddleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if ti := auth.TokenInfoFromContext(r.Context()); ti != nil && ti.UserID != "" {
 			var owner, admin bool
-			_ = h.db.QueryRowContext(r.Context(),
-				`SELECT is_owner, is_admin FROM users WHERE id = ?`, ti.UserID).Scan(&owner, &admin)
-			r = r.WithContext(withMCPCaller(r.Context(), mcpCaller{UserID: ti.UserID, IsAdmin: owner || admin}))
+			var workspaceID string
+			// platformDB: this read resolves the workspace, so it cannot be bound
+			// to one. See RequireAuth for the same reasoning.
+			_ = h.platformDB().QueryRowContext(r.Context(),
+				`SELECT is_owner, is_admin, workspace_id FROM users WHERE id = ?`, ti.UserID).
+				Scan(&owner, &admin, &workspaceID)
+			r = r.WithContext(withMCPCaller(r.Context(), mcpCaller{
+				UserID: ti.UserID, IsAdmin: owner || admin, WorkspaceID: workspaceID,
+			}))
 		}
 		next.ServeHTTP(w, r)
 	})
diff --git a/internal/handler/shared.go b/internal/handler/shared.go
index e31e3d9..530dffe 100644
--- a/internal/handler/shared.go
+++ b/internal/handler/shared.go
@@ -5,6 +5,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"golang.org/x/oauth2"
 
 	"github.com/calnode/calnode/internal/calendar"
@@ -65,6 +66,12 @@ type shared struct {
 	demoMu            sync.RWMutex
 	demoNextResetAt   time.Time
 
+	// mcpServers caches one MCP server per workspace, keyed by workspace id ("" in
+	// single-tenant mode). The tools close over their handler, so one shared
+	// instance would run every tenant's tool calls on one workspace's handle.
+	mcpMu      sync.RWMutex
+	mcpServers map[string]*mcp.Server
+
 	// multiTenant mirrors config.MultiTenant. It is what turns host and
 	// credential resolution on; unset, every request runs on the default
 	// workspace and the handler behaves exactly as it did before.
diff --git a/internal/server/routes_classified_test.go b/internal/server/routes_classified_test.go
new file mode 100644
index 0000000..0b03899
--- /dev/null
+++ b/internal/server/routes_classified_test.go
@@ -0,0 +1,226 @@
+package server
+
+import (
+	"os"
+	"regexp"
+	"slices"
+	"strings"
+	"testing"
+)
+
+// The classification gate.
+//
+// Every route registered in New must be one of three things, and must SAY which:
+//
+//	h.Scoped(HostWorkspace, …)        — the tenant comes from the request Host
+//	h.Scoped(CredentialWorkspace, …)  — the tenant comes from the credential
+//	h.Platform(…)                     — no tenant, on the identity host, on purpose
+//
+// or it must be on the allowlist below, which holds only handlers that are not
+// methods on *handler.Handler at all: the two CORS preflights, the embedded
+// frontend's static handlers, and two redirects.
+//
+// ⛔ This is a SOURCE scan rather than a runtime walk, and that is deliberate:
+// http.ServeMux exposes no way to enumerate its patterns, and the thing that has
+// to be caught is a registration written without a wrapper — which is a property
+// of the text, not of the served response. A future Go that adds mux iteration
+// would let this become a runtime assertion; until then the file is the mux.
+//
+// A new route added without a wrapper fails here, which is the point: on a
+// multi-tenant instance an unwrapped handler runs on the UNSCOPED handle, and on
+// the unbound application handle that means it reads nothing — or, if someone
+// "fixes" that by handing it the platform handle, everything.
+
+// unscopedAllowlist holds the patterns whose handler is not a *handler.Handler
+// method. Each entry is a decision, and adding one should be an argument.
+var unscopedAllowlist = map[string]string{
+	// CORS preflights: an empty function that only needs the headers the cors
+	// wrapper already set. It touches no data, so there is no tenant to resolve.
+	"OPTIONS /v1/bookings":                     "empty CORS preflight",
+	"OPTIONS /v1/event-types/{slug}/assistant": "empty CORS preflight",
+	// The embedded frontend and two redirects: static bytes compiled into the
+	// binary, identical for every tenant.
+	"GET /favicon.svg": "embedded static asset",
+	"GET /favicon.ico": "embedded static asset",
+	"GET /admin":       "redirect to /admin/",
+	"/admin/":          "embedded admin SPA (static bytes, same for every tenant)",
+	"GET /{$}":         "redirect to /admin/",
+	// The MCP mount is a *mcp.Server behind two middlewares, not a handler
+	// method. Its tenant comes from the bearer credential, resolved by
+	// MCPCallerMiddleware and applied by MCPServerForRequest — which is asserted
+	// separately, below.
+	"/mcp": "MCP streamable-HTTP mount; scoped by MCPServerForRequest",
+}
+
+var (
+	handleFuncRe = regexp.MustCompile(`mux\.HandleFunc\("([^"]+)",\s*(.*)$`)
+	handleRe     = regexp.MustCompile(`mux\.Handle\("([^"]+)",\s*(.*)$`)
+)
+
+// TestEveryRouteIsClassified reads server.go and insists on it.
+func TestEveryRouteIsClassified(t *testing.T) {
+	src, err := os.ReadFile("server.go")
+	if err != nil {
+		t.Fatalf("read server.go: %v", err)
+	}
+
+	type route struct{ pattern, expr string }
+	var routes []route
+	for _, line := range strings.Split(string(src), "\n") {
+		for _, re := range []*regexp.Regexp{handleFuncRe, handleRe} {
+			if m := re.FindStringSubmatch(line); m != nil {
+				routes = append(routes, route{pattern: m[1], expr: m[2]})
+			}
+		}
+	}
+
+	// A floor, so a regexp that stopped matching cannot pass vacuously.
+	if len(routes) < 150 {
+		t.Fatalf("found only %d registrations in server.go; the scan has stopped working", len(routes))
+	}
+
+	var host, credential, platform, allowed int
+	seen := map[string]bool{}
+	for _, r := range routes {
+		if seen[r.pattern] {
+			// Two registrations of one pattern is a panic at boot, so it is worth
+			// catching here — except for the deliberate LiveKit webhook alias,
+			// which is a different pattern for the same handler.
+			t.Errorf("pattern %q is registered twice", r.pattern)
+		}
+		seen[r.pattern] = true
+
+		switch {
+		case strings.Contains(r.expr, "handler.HostWorkspace"):
+			host++
+		case strings.Contains(r.expr, "handler.CredentialWorkspace"):
+			credential++
+		case strings.Contains(r.expr, "h.Platform("):
+			platform++
+		default:
+			if _, ok := unscopedAllowlist[r.pattern]; ok {
+				allowed++
+				continue
+			}
+			t.Errorf("route %q is unclassified: %s\n"+
+				"    wrap it in h.Scoped(handler.HostWorkspace, (*H).Method), "+
+				"h.Scoped(handler.CredentialWorkspace, (*H).Method) or h.Platform((*H).Method), "+
+				"or add it to unscopedAllowlist with a reason", r.pattern, strings.TrimSuffix(r.expr, ")"))
+		}
+	}
+
+	// Every allowlist entry must still be a registered route, so a stale
+	// exemption cannot sit there silently permitting nothing.
+	for pattern := range unscopedAllowlist {
+		if !seen[pattern] {
+			t.Errorf("unscopedAllowlist holds %q, which is no longer registered — delete the entry", pattern)
+		}
+	}
+
+	t.Logf("%d routes: %d host-scoped, %d credential-scoped, %d platform, %d allowlisted",
+		len(routes), host, credential, platform, allowed)
+
+	// Each bucket has to be non-trivially populated. A refactor that accidentally
+	// classified everything one way would otherwise satisfy every assertion above.
+	for name, n := range map[string]int{"host-scoped": host, "credential-scoped": credential, "platform": platform} {
+		if n < 3 {
+			t.Errorf("only %d %s routes; that is not a plausible classification", n, name)
+		}
+	}
+}
+
+// TestCredentialScopedRoutesAuthenticateFirst: CredentialWorkspace reads the
+// caller out of the request context, so the auth middleware has to have run.
+// Registered the other way round it would resolve nothing and 500 — a 500 on
+// every authenticated route, which is loud, but the compiler cannot see it and a
+// reviewer easily can't either.
+func TestCredentialScopedRoutesAuthenticateFirst(t *testing.T) {
+	src, err := os.ReadFile("server.go")
+	if err != nil {
+		t.Fatalf("read server.go: %v", err)
+	}
+
+	// The bearer-authenticated MCP mount is the one exception: its caller is bound
+	// by MCPCallerMiddleware, not RequireAuth, and it is not a CredentialWorkspace
+	// registration at all.
+	var checked int
+	for _, line := range strings.Split(string(src), "\n") {
+		if !strings.Contains(line, "handler.CredentialWorkspace") {
+			continue
+		}
+		checked++
+		if !strings.Contains(line, "h.RequireAuth(") {
+			t.Errorf("a CredentialWorkspace route does not authenticate first:\n    %s", strings.TrimSpace(line))
+		}
+		// And the order has to be RequireAuth OUTSIDE Scoped.
+		if strings.Index(line, "h.RequireAuth(") > strings.Index(line, "h.Scoped(") {
+			t.Errorf("RequireAuth must wrap Scoped, not the other way round:\n    %s", strings.TrimSpace(line))
+		}
+	}
+	if checked < 90 {
+		t.Fatalf("only %d CredentialWorkspace routes found; the scan has stopped working", checked)
+	}
+	t.Logf("checked %d credential-scoped routes", checked)
+}
+
+// TestPlatformRoutesAreTheIdentityHostSet pins the list against D11, which names
+// exactly which surfaces belong to BASE_URL rather than to a workspace's public
+// host. A route joining or leaving this set is a decision about which host serves
+// it, so it should not be possible to make silently.
+func TestPlatformRoutesAreTheIdentityHostSet(t *testing.T) {
+	src, err := os.ReadFile("server.go")
+	if err != nil {
+		t.Fatalf("read server.go: %v", err)
+	}
+
+	want := []string{
+		// Ops (D11).
+		"GET /healthz", "GET /readyz", "GET /version",
+		// Bootstrap: creates the first user of a single-tenant instance.
+		"POST /v1/setup",
+		// OAuth login and its callbacks live on the identity host, because that is
+		// the redirect URI registered with Google and Microsoft (D11). The
+		// hand-off back to the workspace's public host is TODO(integration),
+		// blocked on feat/platform-hooks.
+		"GET /v1/auth/login", "GET /v1/auth/callback",
+		"GET /v1/auth/microsoft/login", "GET /v1/auth/microsoft/callback",
+		// The MCP authorization server (D11).
+		"GET /.well-known/oauth-protected-resource",
+		"GET /.well-known/oauth-authorization-server",
+		"POST /oauth/register", "GET /oauth/authorize", "POST /oauth/authorize",
+		"POST /oauth/token",
+		// Calendar and Zoom connect callbacks: same registered-redirect-URI
+		// reason. Storing the tokens under the state's workspace is B6.
+		"GET /v1/calendar/callback", "GET /v1/zoom/callback",
+		// Vendor webhooks. They arrive at whatever host the vendor was given and
+		// carry no tenant Host, so they cannot be host-scoped; each has to resolve
+		// its own workspace from the room or session it names. TODO(B6).
+		"POST /v1/livekit/webhook", "POST /v1/livekit/egress-webhook",
+		"POST /v1/stripe/webhook",
+		// Vendored room assets: static bytes, identical for every tenant.
+		"GET /assets/livekit-client.js", "GET /assets/livekit-room.js",
+		// Demo mode, which is mutually exclusive with multi-tenant mode (D13).
+		"GET /robots.txt", "GET /v1/demo/enter", "POST /v1/demo/reset",
+	}
+
+	var got []string
+	for _, line := range strings.Split(string(src), "\n") {
+		if !strings.Contains(line, "h.Platform((*H).") {
+			continue
+		}
+		m := handleFuncRe.FindStringSubmatch(line)
+		if m == nil {
+			t.Errorf("a Platform route is registered in a shape this test cannot read:\n    %s", strings.TrimSpace(line))
+			continue
+		}
+		got = append(got, m[1])
+	}
+
+	slices.Sort(got)
+	slices.Sort(want)
+	if !slices.Equal(got, want) {
+		t.Errorf("the platform route set has changed.\n got: %v\nwant: %v\n"+
+			"A route moving onto or off the identity host is a decision about which host serves it; "+
+			"update this list in the same commit and say why.", got, want)
+	}
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index 12632c4..c338520 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -251,45 +251,57 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 
 // New wires services via BuildHandler, then registers all HTTP routes. It returns the
 // http.Handler and the worker drain func.
+// H is handler.Handler under a shorter name, so a registration reads
+// (*H).ListBookings rather than (*handler.Handler).ListBookings 163 times.
+//
+// The method EXPRESSION is the point, not the brevity: h.Scoped takes
+// func(*Handler, http.ResponseWriter, *http.Request), so passing h.ListBookings —
+// a bound method value on the UNSCOPED handler, which is exactly the bug Scoped
+// exists to prevent — does not compile.
+type H = handler.Handler
+
 func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger) (http.Handler, func()) {
 	h, drain := BuildHandler(ctx, cfg, db, logger)
 	mux := http.NewServeMux()
 
 	// Ops
-	mux.HandleFunc("GET /healthz", h.Healthz)
-	mux.HandleFunc("GET /readyz", h.Readyz)
-	mux.HandleFunc("GET /version", h.Version)
+	mux.HandleFunc("GET /healthz", h.Platform((*H).Healthz))
+	mux.HandleFunc("GET /readyz", h.Platform((*H).Readyz))
+	mux.HandleFunc("GET /version", h.Platform((*H).Version))
 
 	// Bootstrap — public, once-only
-	mux.HandleFunc("POST /v1/setup", h.Setup)
+	mux.HandleFunc("POST /v1/setup", h.Platform((*H).Setup))
 
 	// Auth status (public — drives login page rendering).
-	mux.HandleFunc("GET /v1/auth/status", h.AuthStatus)
+	mux.HandleFunc("GET /v1/auth/status", h.Scoped(handler.HostWorkspace, (*H).AuthStatus))
 
 	// First-user claim (public — only succeeds when no users exist).
 	claimRL := RateLimit(5, time.Minute)
-	mux.HandleFunc("POST /v1/auth/claim", claimRL(h.Claim))
+	mux.HandleFunc("POST /v1/auth/claim", claimRL(h.Scoped(handler.HostWorkspace, (*H).Claim)))
 
 	// Email + password login.
 	loginRL := RateLimit(10, time.Minute)
-	mux.HandleFunc("POST /v1/auth/login/email", loginRL(h.LoginEmail))
-	mux.HandleFunc("POST /v1/auth/magic-link/request", loginRL(h.RequestMagicLink))
-	mux.HandleFunc("GET /v1/auth/magic-link/verify", loginRL(h.VerifyMagicLink))
+	mux.HandleFunc("POST /v1/auth/login/email", loginRL(h.Scoped(handler.HostWorkspace, (*H).LoginEmail)))
+	mux.HandleFunc("POST /v1/auth/magic-link/request", loginRL(h.Scoped(handler.HostWorkspace, (*H).RequestMagicLink)))
+	mux.HandleFunc("GET /v1/auth/magic-link/verify", loginRL(h.Scoped(handler.HostWorkspace, (*H).VerifyMagicLink)))
 
 	// OAuth login (browser sessions for admin UI).
 	authRL := RateLimit(10, time.Minute)
-	mux.HandleFunc("GET /v1/auth/login", authRL(h.LoginGoogle))
-	mux.HandleFunc("GET /v1/auth/callback", authRL(h.CallbackGoogle))
-	mux.HandleFunc("GET /v1/auth/microsoft/login", authRL(h.LoginMicrosoft))
-	mux.HandleFunc("GET /v1/auth/microsoft/callback", authRL(h.CallbackMicrosoft))
-	mux.HandleFunc("POST /v1/auth/logout", h.Logout)
+	mux.HandleFunc("GET /v1/auth/login", authRL(h.Platform((*H).LoginGoogle)))
+	mux.HandleFunc("GET /v1/auth/callback", authRL(h.Platform((*H).CallbackGoogle)))
+	mux.HandleFunc("GET /v1/auth/microsoft/login", authRL(h.Platform((*H).LoginMicrosoft)))
+	mux.HandleFunc("GET /v1/auth/microsoft/callback", authRL(h.Platform((*H).CallbackMicrosoft)))
+	mux.HandleFunc("POST /v1/auth/logout", h.Scoped(handler.HostWorkspace, (*H).Logout))
 
 	// MCP server (Model Context Protocol) — Streamable HTTP transport for remote
 	// agents. One server instance reused across requests. Guarded by a bearer token:
 	// an OAuth access token (the "Connect" flow) or a cno_ API key, both resolved by
 	// verifyMCPBearer. A 401 advertises the OAuth discovery doc so clients can connect.
-	mcpSrv := h.MCPServer()
-	mcpHTTP := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return mcpSrv }, nil)
+	// One server per workspace, not one per process: the tools close over their
+	// handler, so a shared instance would run every tenant's tool calls on
+	// whichever handler built it. MCPCallerMiddleware below has resolved the
+	// caller's workspace into the request context by the time the factory runs.
+	mcpHTTP := mcp.NewStreamableHTTPHandler(h.MCPServerForRequest, nil)
 	mcpAuth := auth.RequireBearerToken(h.VerifyMCPBearer, &auth.RequireBearerTokenOptions{
 		ResourceMetadataURL: cfg.BaseURL + "/.well-known/oauth-protected-resource",
 	})
@@ -300,110 +312,110 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	// OAuth 2.1 authorization server for MCP (discovery + dynamic client registration;
 	// the interactive /oauth/authorize + /oauth/token live with the consent flow). All
 	// public — the security gate is the user login + consent at /oauth/authorize.
-	mux.HandleFunc("GET /.well-known/oauth-protected-resource", h.OAuthProtectedResourceMetadata)
-	mux.HandleFunc("GET /.well-known/oauth-authorization-server", h.OAuthAuthServerMetadata)
+	mux.HandleFunc("GET /.well-known/oauth-protected-resource", h.Platform((*H).OAuthProtectedResourceMetadata))
+	mux.HandleFunc("GET /.well-known/oauth-authorization-server", h.Platform((*H).OAuthAuthServerMetadata))
 	oauthRegRL := RateLimit(20, time.Minute)
-	mux.HandleFunc("POST /oauth/register", oauthRegRL(h.RegisterOAuthClient))
-	mux.HandleFunc("GET /oauth/authorize", h.AuthorizeMCP)
-	mux.HandleFunc("POST /oauth/authorize", h.AuthorizeMCPDecision)
+	mux.HandleFunc("POST /oauth/register", oauthRegRL(h.Platform((*H).RegisterOAuthClient)))
+	mux.HandleFunc("GET /oauth/authorize", h.Platform((*H).AuthorizeMCP))
+	mux.HandleFunc("POST /oauth/authorize", h.Platform((*H).AuthorizeMCPDecision))
 	tokenRL := RateLimit(30, time.Minute)
-	mux.HandleFunc("POST /oauth/token", tokenRL(h.TokenMCP))
+	mux.HandleFunc("POST /oauth/token", tokenRL(h.Platform((*H).TokenMCP)))
 
 	// Password management.
-	mux.HandleFunc("POST /v1/users/me/password", h.RequireAuth(h.ChangePassword))
-	mux.HandleFunc("POST /v1/users/{id}/password", h.RequireAuth(h.AdminSetPassword))
+	mux.HandleFunc("POST /v1/users/me/password", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ChangePassword)))
+	mux.HandleFunc("POST /v1/users/{id}/password", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).AdminSetPassword)))
 
 	// Invite management.
 	inviteRL := RateLimit(20, time.Minute)
-	mux.HandleFunc("POST /v1/invites", inviteRL(h.RequireAuth(h.CreateInvite)))
-	mux.HandleFunc("GET /v1/invites", h.RequireAuth(h.ListInvites))
-	mux.HandleFunc("DELETE /v1/invites/{id}", h.RequireAuth(h.RevokeInvite))
-	mux.HandleFunc("POST /v1/invites/{id}/resend", inviteRL(h.RequireAuth(h.ResendInvite)))
-	mux.HandleFunc("GET /v1/invites/{token}", h.GetInvite)
-	mux.HandleFunc("POST /v1/invites/{token}/claim", inviteRL(h.ClaimInvite))
+	mux.HandleFunc("POST /v1/invites", inviteRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CreateInvite))))
+	mux.HandleFunc("GET /v1/invites", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListInvites)))
+	mux.HandleFunc("DELETE /v1/invites/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).RevokeInvite)))
+	mux.HandleFunc("POST /v1/invites/{id}/resend", inviteRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ResendInvite))))
+	mux.HandleFunc("GET /v1/invites/{token}", h.Scoped(handler.HostWorkspace, (*H).GetInvite))
+	mux.HandleFunc("POST /v1/invites/{token}/claim", inviteRL(h.Scoped(handler.HostWorkspace, (*H).ClaimInvite)))
 
 	// Users
-	mux.HandleFunc("GET /v1/users", h.RequireAuth(h.ListUsers))
-	mux.HandleFunc("DELETE /v1/users/{id}", h.RequireAuth(h.DeleteUser))
-	mux.HandleFunc("PATCH /v1/users/{id}/role", h.RequireAuth(h.SetUserRole))
-	mux.HandleFunc("POST /v1/users/{id}/transfer-ownership", h.RequireAuth(h.TransferOwnership))
-	mux.HandleFunc("POST /v1/users/{id}/archive", h.RequireAuth(h.ArchiveUser))
-	mux.HandleFunc("POST /v1/users/{id}/restore", h.RequireAuth(h.RestoreUser))
-	mux.HandleFunc("GET /v1/users/{id}/upcoming-bookings", h.RequireAuth(h.ListUserUpcomingBookings))
+	mux.HandleFunc("GET /v1/users", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListUsers)))
+	mux.HandleFunc("DELETE /v1/users/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteUser)))
+	mux.HandleFunc("PATCH /v1/users/{id}/role", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).SetUserRole)))
+	mux.HandleFunc("POST /v1/users/{id}/transfer-ownership", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).TransferOwnership)))
+	mux.HandleFunc("POST /v1/users/{id}/archive", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ArchiveUser)))
+	mux.HandleFunc("POST /v1/users/{id}/restore", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).RestoreUser)))
+	mux.HandleFunc("GET /v1/users/{id}/upcoming-bookings", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListUserUpcomingBookings)))
 
 	// Teams
-	mux.HandleFunc("POST /v1/teams", h.RequireAuth(h.CreateTeam))
-	mux.HandleFunc("GET /v1/teams", h.RequireAuth(h.ListTeams))
-	mux.HandleFunc("GET /v1/teams/{id}", h.RequireAuth(h.GetTeam))
-	mux.HandleFunc("PATCH /v1/teams/{id}", h.RequireAuth(h.PatchTeam))
-	mux.HandleFunc("DELETE /v1/teams/{id}", h.RequireAuth(h.DeleteTeam))
-	mux.HandleFunc("POST /v1/teams/{id}/members", h.RequireAuth(h.AddTeamMember))
-	mux.HandleFunc("PATCH /v1/teams/{id}/members/{userId}", h.RequireAuth(h.UpdateTeamMember))
-	mux.HandleFunc("DELETE /v1/teams/{id}/members/{userId}", h.RequireAuth(h.RemoveTeamMember))
-	mux.HandleFunc("GET /v1/users/me", h.RequireAuth(h.GetMe))
-	mux.HandleFunc("PATCH /v1/users/me", h.RequireAuth(h.PatchMe))
+	mux.HandleFunc("POST /v1/teams", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CreateTeam)))
+	mux.HandleFunc("GET /v1/teams", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListTeams)))
+	mux.HandleFunc("GET /v1/teams/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetTeam)))
+	mux.HandleFunc("PATCH /v1/teams/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchTeam)))
+	mux.HandleFunc("DELETE /v1/teams/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteTeam)))
+	mux.HandleFunc("POST /v1/teams/{id}/members", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).AddTeamMember)))
+	mux.HandleFunc("PATCH /v1/teams/{id}/members/{userId}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).UpdateTeamMember)))
+	mux.HandleFunc("DELETE /v1/teams/{id}/members/{userId}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).RemoveTeamMember)))
+	mux.HandleFunc("GET /v1/users/me", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetMe)))
+	mux.HandleFunc("PATCH /v1/users/me", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchMe)))
 	avatarRL := RateLimit(20, time.Minute)
-	mux.HandleFunc("POST /v1/users/me/avatar", avatarRL(h.RequireAuth(h.UploadAvatar)))
-	mux.HandleFunc("DELETE /v1/users/me/avatar", avatarRL(h.RequireAuth(h.DeleteAvatar)))
-	mux.HandleFunc("GET /avatars/{userID}", h.ServeAvatar)
-	mux.HandleFunc("GET /branding/logo", h.ServeBrandingLogo)
-	mux.HandleFunc("GET /branding/banner", h.ServeBrandingBanner)
+	mux.HandleFunc("POST /v1/users/me/avatar", avatarRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).UploadAvatar))))
+	mux.HandleFunc("DELETE /v1/users/me/avatar", avatarRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteAvatar))))
+	mux.HandleFunc("GET /avatars/{userID}", h.Scoped(handler.HostWorkspace, (*H).ServeAvatar))
+	mux.HandleFunc("GET /branding/logo", h.Scoped(handler.HostWorkspace, (*H).ServeBrandingLogo))
+	mux.HandleFunc("GET /branding/banner", h.Scoped(handler.HostWorkspace, (*H).ServeBrandingBanner))
 
 	// Server settings — email (SMTP) and Google OAuth
 	settingsRL := RateLimit(20, time.Minute)
-	mux.HandleFunc("GET /v1/settings/email", h.RequireAuth(h.GetEmailSettings))
-	mux.HandleFunc("PATCH /v1/settings/email", settingsRL(h.RequireAuth(h.PatchEmailSettings)))
-	mux.HandleFunc("POST /v1/settings/email/test", settingsRL(h.RequireAuth(h.TestEmailConnection)))
-	mux.HandleFunc("GET /v1/settings/google", h.RequireAuth(h.GetGoogleSettings))
-	mux.HandleFunc("PATCH /v1/settings/google", settingsRL(h.RequireAuth(h.PatchGoogleSettings)))
-	mux.HandleFunc("GET /v1/settings/zoom", h.RequireAuth(h.GetZoomSettings))
-	mux.HandleFunc("PATCH /v1/settings/zoom", settingsRL(h.RequireAuth(h.PatchZoomSettings)))
-	mux.HandleFunc("GET /v1/settings/livekit", h.RequireAuth(h.GetLiveKitSettings))
-	mux.HandleFunc("PATCH /v1/settings/livekit", settingsRL(h.RequireAuth(h.PatchLiveKitSettings)))
-	mux.HandleFunc("GET /v1/settings/storage", h.RequireAuth(h.GetStorageSettings))
-	mux.HandleFunc("PATCH /v1/settings/storage", settingsRL(h.RequireAuth(h.PatchStorageSettings)))
-	mux.HandleFunc("GET /v1/settings/notetaker", h.RequireAuth(h.GetNotetakerSettings))
-	mux.HandleFunc("PATCH /v1/settings/notetaker", settingsRL(h.RequireAuth(h.PatchNotetakerSettings)))
-	mux.HandleFunc("GET /v1/bookings/{id}/notes", h.RequireAuth(h.GetBookingNotes))
-	mux.HandleFunc("POST /v1/bookings/{id}/notes/regenerate", h.RequireAuth(h.RegenerateBookingNotes))
-	mux.HandleFunc("GET /v1/bookings/{id}/transcript", h.RequireAuth(h.GetBookingTranscript))
-	mux.HandleFunc("GET /v1/settings/stripe", h.RequireAuth(h.GetStripeSettings))
-	mux.HandleFunc("PATCH /v1/settings/stripe", settingsRL(h.RequireAuth(h.PatchStripeSettings)))
-	mux.HandleFunc("GET /v1/settings/tracking", h.RequireAuth(h.GetTrackingSettings))
-	mux.HandleFunc("PATCH /v1/settings/tracking", settingsRL(h.RequireAuth(h.PatchTrackingSettings)))
-	mux.HandleFunc("GET /v1/settings/llm", h.RequireAuth(h.GetLLMSettings))
-	mux.HandleFunc("PATCH /v1/settings/llm", settingsRL(h.RequireAuth(h.PatchLLMSettings)))
-	mux.HandleFunc("POST /v1/settings/llm/test", settingsRL(h.RequireAuth(h.TestLLMSettings)))
-	mux.HandleFunc("GET /v1/settings/branding", h.RequireAuth(h.GetBranding))
-	mux.HandleFunc("PATCH /v1/settings/branding", settingsRL(h.RequireAuth(h.PatchBranding)))
-	mux.HandleFunc("POST /v1/settings/branding/logo", settingsRL(h.RequireAuth(h.UploadBrandingLogo)))
-	mux.HandleFunc("DELETE /v1/settings/branding/logo", h.RequireAuth(h.DeleteBrandingLogo))
-	mux.HandleFunc("POST /v1/settings/branding/banner", settingsRL(h.RequireAuth(h.UploadBrandingBanner)))
-	mux.HandleFunc("DELETE /v1/settings/branding/banner", h.RequireAuth(h.DeleteBrandingBanner))
+	mux.HandleFunc("GET /v1/settings/email", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetEmailSettings)))
+	mux.HandleFunc("PATCH /v1/settings/email", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchEmailSettings))))
+	mux.HandleFunc("POST /v1/settings/email/test", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).TestEmailConnection))))
+	mux.HandleFunc("GET /v1/settings/google", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetGoogleSettings)))
+	mux.HandleFunc("PATCH /v1/settings/google", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchGoogleSettings))))
+	mux.HandleFunc("GET /v1/settings/zoom", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetZoomSettings)))
+	mux.HandleFunc("PATCH /v1/settings/zoom", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchZoomSettings))))
+	mux.HandleFunc("GET /v1/settings/livekit", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetLiveKitSettings)))
+	mux.HandleFunc("PATCH /v1/settings/livekit", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchLiveKitSettings))))
+	mux.HandleFunc("GET /v1/settings/storage", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetStorageSettings)))
+	mux.HandleFunc("PATCH /v1/settings/storage", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchStorageSettings))))
+	mux.HandleFunc("GET /v1/settings/notetaker", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetNotetakerSettings)))
+	mux.HandleFunc("PATCH /v1/settings/notetaker", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchNotetakerSettings))))
+	mux.HandleFunc("GET /v1/bookings/{id}/notes", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetBookingNotes)))
+	mux.HandleFunc("POST /v1/bookings/{id}/notes/regenerate", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).RegenerateBookingNotes)))
+	mux.HandleFunc("GET /v1/bookings/{id}/transcript", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetBookingTranscript)))
+	mux.HandleFunc("GET /v1/settings/stripe", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetStripeSettings)))
+	mux.HandleFunc("PATCH /v1/settings/stripe", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchStripeSettings))))
+	mux.HandleFunc("GET /v1/settings/tracking", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetTrackingSettings)))
+	mux.HandleFunc("PATCH /v1/settings/tracking", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchTrackingSettings))))
+	mux.HandleFunc("GET /v1/settings/llm", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetLLMSettings)))
+	mux.HandleFunc("PATCH /v1/settings/llm", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchLLMSettings))))
+	mux.HandleFunc("POST /v1/settings/llm/test", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).TestLLMSettings))))
+	mux.HandleFunc("GET /v1/settings/branding", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetBranding)))
+	mux.HandleFunc("PATCH /v1/settings/branding", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchBranding))))
+	mux.HandleFunc("POST /v1/settings/branding/logo", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).UploadBrandingLogo))))
+	mux.HandleFunc("DELETE /v1/settings/branding/logo", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteBrandingLogo)))
+	mux.HandleFunc("POST /v1/settings/branding/banner", settingsRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).UploadBrandingBanner))))
+	mux.HandleFunc("DELETE /v1/settings/branding/banner", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteBrandingBanner)))
 
 	// Event types
-	mux.HandleFunc("POST /v1/event-types", h.RequireAuth(h.CreateEventType))
-	mux.HandleFunc("GET /v1/event-types", h.RequireAuth(h.ListEventTypes))
-	mux.HandleFunc("GET /v1/event-types/{slug}", h.RequireAuth(h.GetEventType))
-	mux.HandleFunc("PATCH /v1/event-types/{slug}", h.RequireAuth(h.PatchEventType))
-	mux.HandleFunc("DELETE /v1/event-types/{slug}", h.RequireAuth(h.DeleteEventType))
-	mux.HandleFunc("GET /v1/event-types/{slug}/hosts", h.RequireAuth(h.ListEventTypeHosts))
-	mux.HandleFunc("PUT /v1/event-types/{slug}/hosts", h.RequireAuth(h.SetEventTypeHosts))
+	mux.HandleFunc("POST /v1/event-types", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CreateEventType)))
+	mux.HandleFunc("GET /v1/event-types", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListEventTypes)))
+	mux.HandleFunc("GET /v1/event-types/{slug}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetEventType)))
+	mux.HandleFunc("PATCH /v1/event-types/{slug}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchEventType)))
+	mux.HandleFunc("DELETE /v1/event-types/{slug}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteEventType)))
+	mux.HandleFunc("GET /v1/event-types/{slug}/hosts", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListEventTypeHosts)))
+	mux.HandleFunc("PUT /v1/event-types/{slug}/hosts", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).SetEventTypeHosts)))
 	testEmailRL := RateLimit(10, time.Minute)
-	mux.HandleFunc("POST /v1/event-types/{slug}/test-email", testEmailRL(h.RequireAuth(h.SendTestEmail)))
+	mux.HandleFunc("POST /v1/event-types/{slug}/test-email", testEmailRL(h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).SendTestEmail))))
 
 	// Availability rules
-	mux.HandleFunc("POST /v1/availability-rules", h.RequireAuth(h.CreateAvailabilityRule))
-	mux.HandleFunc("GET /v1/availability-rules", h.RequireAuth(h.ListAvailabilityRules))
-	mux.HandleFunc("PATCH /v1/availability-rules/{id}", h.RequireAuth(h.UpdateAvailabilityRule))
-	mux.HandleFunc("DELETE /v1/availability-rules/{id}", h.RequireAuth(h.DeleteAvailabilityRule))
+	mux.HandleFunc("POST /v1/availability-rules", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CreateAvailabilityRule)))
+	mux.HandleFunc("GET /v1/availability-rules", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListAvailabilityRules)))
+	mux.HandleFunc("PATCH /v1/availability-rules/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).UpdateAvailabilityRule)))
+	mux.HandleFunc("DELETE /v1/availability-rules/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteAvailabilityRule)))
 
 	// Availability overrides
-	mux.HandleFunc("POST /v1/availability-overrides", h.RequireAuth(h.CreateAvailabilityOverride))
-	mux.HandleFunc("GET /v1/availability-overrides", h.RequireAuth(h.ListAvailabilityOverrides))
-	mux.HandleFunc("PATCH /v1/availability-overrides/{id}", h.RequireAuth(h.UpdateAvailabilityOverride))
-	mux.HandleFunc("DELETE /v1/availability-overrides/{id}", h.RequireAuth(h.DeleteAvailabilityOverride))
-	mux.HandleFunc("DELETE /v1/availability-overrides/group/{groupId}", h.RequireAuth(h.DeleteAvailabilityOverrideGroup))
+	mux.HandleFunc("POST /v1/availability-overrides", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CreateAvailabilityOverride)))
+	mux.HandleFunc("GET /v1/availability-overrides", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListAvailabilityOverrides)))
+	mux.HandleFunc("PATCH /v1/availability-overrides/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).UpdateAvailabilityOverride)))
+	mux.HandleFunc("DELETE /v1/availability-overrides/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteAvailabilityOverride)))
+	mux.HandleFunc("DELETE /v1/availability-overrides/group/{groupId}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteAvailabilityOverrideGroup)))
 
 	// Slots — public, rate-limited per IP. Browsed more than booked (so a higher cap
 	// than booking), but each call fans out Google free/busy per host, so leaving it
@@ -413,112 +425,112 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	cors := PublicCORS(cfg.EmbedAllowedOrigins)
 
 	// Public event-type display info for the widget (name/duration/location/brand).
-	mux.HandleFunc("GET /v1/event-types/{slug}/public", cors(h.PublicEventType))
+	mux.HandleFunc("GET /v1/event-types/{slug}/public", cors(h.Scoped(handler.HostWorkspace, (*H).PublicEventType)))
 
 	// unthrottled is a CPU + API-quota abuse vector on an openly-public page.
 	slotsRL := RateLimit(60, time.Minute)
-	mux.HandleFunc("GET /v1/event-types/{slug}/slots", cors(slotsRL(h.GetSlots)))
+	mux.HandleFunc("GET /v1/event-types/{slug}/slots", cors(slotsRL(h.Scoped(handler.HostWorkspace, (*H).GetSlots))))
 
 	// Conversational booking assistant (optional AI; public, anonymous → tighter limit).
 	assistantRL := RateLimit(15, time.Minute)
-	mux.HandleFunc("POST /v1/event-types/{slug}/assistant", cors(assistantRL(h.BookingAssistant)))
+	mux.HandleFunc("POST /v1/event-types/{slug}/assistant", cors(assistantRL(h.Scoped(handler.HostWorkspace, (*H).BookingAssistant))))
 	mux.HandleFunc("OPTIONS /v1/event-types/{slug}/assistant", cors(func(http.ResponseWriter, *http.Request) {}))
 
 	// Intake questions
-	mux.HandleFunc("GET /v1/event-types/{slug}/questions", cors(h.ListQuestions))
-	mux.HandleFunc("GET /v1/event-types/{slug}/questions/admin", h.RequireAuth(h.ListQuestionsAdmin))
-	mux.HandleFunc("POST /v1/event-types/{slug}/questions", h.RequireAuth(h.CreateQuestion))
-	mux.HandleFunc("PATCH /v1/event-types/{slug}/questions/{id}", h.RequireAuth(h.UpdateQuestion))
-	mux.HandleFunc("DELETE /v1/event-types/{slug}/questions/{id}", h.RequireAuth(h.DeleteQuestion))
+	mux.HandleFunc("GET /v1/event-types/{slug}/questions", cors(h.Scoped(handler.HostWorkspace, (*H).ListQuestions)))
+	mux.HandleFunc("GET /v1/event-types/{slug}/questions/admin", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListQuestionsAdmin)))
+	mux.HandleFunc("POST /v1/event-types/{slug}/questions", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CreateQuestion)))
+	mux.HandleFunc("PATCH /v1/event-types/{slug}/questions/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).UpdateQuestion)))
+	mux.HandleFunc("DELETE /v1/event-types/{slug}/questions/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteQuestion)))
 
 	bookingRL := RateLimit(20, time.Minute)
 	manageRL := RateLimit(30, time.Minute)
 
 	// Bookings — public create is CORS-enabled for the widget; the JSON body makes it
 	// a non-simple request, so the OPTIONS preflight is handled too.
-	mux.HandleFunc("POST /v1/bookings", cors(bookingRL(h.CreateBooking)))
+	mux.HandleFunc("POST /v1/bookings", cors(bookingRL(h.Scoped(handler.HostWorkspace, (*H).CreateBooking))))
 	mux.HandleFunc("OPTIONS /v1/bookings", cors(func(http.ResponseWriter, *http.Request) {}))
-	mux.HandleFunc("GET /v1/bookings/{id}", h.GetBooking)
-	mux.HandleFunc("GET /v1/bookings", h.RequireAuth(h.ListBookings))
-	mux.HandleFunc("POST /v1/bookings/{id}/cancel", h.RequireAuth(h.CancelBooking))
-	mux.HandleFunc("PATCH /v1/bookings/{id}/reschedule", h.RequireAuth(h.RescheduleBooking))
-	mux.HandleFunc("POST /v1/bookings/{id}/reassign", h.RequireAuth(h.ReassignBooking))
-	mux.HandleFunc("GET /v1/bookings/{id}/answers", h.RequireAuth(h.GetBookingAnswers))
+	mux.HandleFunc("GET /v1/bookings/{id}", h.Scoped(handler.HostWorkspace, (*H).GetBooking))
+	mux.HandleFunc("GET /v1/bookings", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListBookings)))
+	mux.HandleFunc("POST /v1/bookings/{id}/cancel", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CancelBooking)))
+	mux.HandleFunc("PATCH /v1/bookings/{id}/reschedule", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).RescheduleBooking)))
+	mux.HandleFunc("POST /v1/bookings/{id}/reassign", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ReassignBooking)))
+	mux.HandleFunc("GET /v1/bookings/{id}/answers", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetBookingAnswers)))
 
 	// Public booking page
-	mux.HandleFunc("GET /embed.js", h.EmbedJS)
-	mux.HandleFunc("GET /booking.css", h.BookingCSS)
-	mux.HandleFunc("GET /book/{slug}", h.BookPage)
+	mux.HandleFunc("GET /embed.js", h.Scoped(handler.HostWorkspace, (*H).EmbedJS))
+	mux.HandleFunc("GET /booking.css", h.Scoped(handler.HostWorkspace, (*H).BookingCSS))
+	mux.HandleFunc("GET /book/{slug}", h.Scoped(handler.HostWorkspace, (*H).BookPage))
 
 	// Built-in LiveKit video room (public): the page, its vendored assets, and the token
 	// exchange. The signed room token in the join URL is the capability — no auth.
-	mux.HandleFunc("GET /room/{room}", h.LiveKitRoom)
-	mux.HandleFunc("GET /assets/livekit-client.js", h.LiveKitSDKAsset)
-	mux.HandleFunc("GET /assets/livekit-room.js", h.LiveKitRoomJSAsset)
-	mux.HandleFunc("POST /v1/livekit/token", bookingRL(h.LiveKitToken))
-	mux.HandleFunc("POST /v1/livekit/room/end", bookingRL(h.EndRoom))
-	mux.HandleFunc("POST /v1/livekit/room/reassign-host", bookingRL(h.ReassignHost))
-	mux.HandleFunc("POST /v1/livekit/room/screenshare", bookingRL(h.ScreenShareToggle))
-	mux.HandleFunc("POST /v1/livekit/record/start", bookingRL(h.RecordStart))
-	mux.HandleFunc("POST /v1/livekit/record/stop", bookingRL(h.RecordStop))
-	mux.HandleFunc("POST /v1/livekit/consent", bookingRL(h.RecordConsent))
-	mux.HandleFunc("POST /v1/livekit/webhook", h.LiveKitWebhook)
-	mux.HandleFunc("POST /v1/livekit/egress-webhook", h.LiveKitWebhook) // legacy alias — keep old LiveKit registrations working
-	mux.HandleFunc("GET /v1/recordings", h.RequireAuth(h.ListRecordings))
-	mux.HandleFunc("DELETE /v1/recordings", h.RequireAuth(h.DeleteAllRecordings))
-	mux.HandleFunc("GET /v1/recordings/{id}/consent", h.RequireAuth(h.ListRecordingConsent))
-	mux.HandleFunc("GET /v1/recordings/{id}/download", h.RequireAuth(h.DownloadRecording))
-	mux.HandleFunc("DELETE /v1/recordings/{id}", h.RequireAuth(h.DeleteRecording))
+	mux.HandleFunc("GET /room/{room}", h.Scoped(handler.HostWorkspace, (*H).LiveKitRoom))
+	mux.HandleFunc("GET /assets/livekit-client.js", h.Platform((*H).LiveKitSDKAsset))
+	mux.HandleFunc("GET /assets/livekit-room.js", h.Platform((*H).LiveKitRoomJSAsset))
+	mux.HandleFunc("POST /v1/livekit/token", bookingRL(h.Scoped(handler.HostWorkspace, (*H).LiveKitToken)))
+	mux.HandleFunc("POST /v1/livekit/room/end", bookingRL(h.Scoped(handler.HostWorkspace, (*H).EndRoom)))
+	mux.HandleFunc("POST /v1/livekit/room/reassign-host", bookingRL(h.Scoped(handler.HostWorkspace, (*H).ReassignHost)))
+	mux.HandleFunc("POST /v1/livekit/room/screenshare", bookingRL(h.Scoped(handler.HostWorkspace, (*H).ScreenShareToggle)))
+	mux.HandleFunc("POST /v1/livekit/record/start", bookingRL(h.Scoped(handler.HostWorkspace, (*H).RecordStart)))
+	mux.HandleFunc("POST /v1/livekit/record/stop", bookingRL(h.Scoped(handler.HostWorkspace, (*H).RecordStop)))
+	mux.HandleFunc("POST /v1/livekit/consent", bookingRL(h.Scoped(handler.HostWorkspace, (*H).RecordConsent)))
+	mux.HandleFunc("POST /v1/livekit/webhook", h.Platform((*H).LiveKitWebhook))
+	mux.HandleFunc("POST /v1/livekit/egress-webhook", h.Platform((*H).LiveKitWebhook)) // legacy alias — keep old LiveKit registrations working
+	mux.HandleFunc("GET /v1/recordings", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListRecordings)))
+	mux.HandleFunc("DELETE /v1/recordings", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteAllRecordings)))
+	mux.HandleFunc("GET /v1/recordings/{id}/consent", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListRecordingConsent)))
+	mux.HandleFunc("GET /v1/recordings/{id}/download", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DownloadRecording)))
+	mux.HandleFunc("DELETE /v1/recordings/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteRecording)))
 
 	// Manage booking (reschedule / cancel via token link)
-	mux.HandleFunc("GET /manage/{token}", manageRL(h.ManagePage))
-	mux.HandleFunc("POST /manage/{token}/reschedule", manageRL(h.RescheduleByToken))
-	mux.HandleFunc("POST /manage/{token}/cancel", manageRL(h.CancelByToken))
+	mux.HandleFunc("GET /manage/{token}", manageRL(h.Scoped(handler.HostWorkspace, (*H).ManagePage)))
+	mux.HandleFunc("POST /manage/{token}/reschedule", manageRL(h.Scoped(handler.HostWorkspace, (*H).RescheduleByToken)))
+	mux.HandleFunc("POST /manage/{token}/cancel", manageRL(h.Scoped(handler.HostWorkspace, (*H).CancelByToken)))
 
 	// Webhooks
-	mux.HandleFunc("POST /v1/webhooks", h.RequireAuth(h.CreateWebhook))
-	mux.HandleFunc("GET /v1/webhooks", h.RequireAuth(h.ListWebhooks))
-	mux.HandleFunc("PATCH /v1/webhooks/{id}", h.RequireAuth(h.PatchWebhook))
-	mux.HandleFunc("DELETE /v1/webhooks/{id}", h.RequireAuth(h.DeleteWebhook))
-	mux.HandleFunc("GET /v1/webhooks/{id}/deliveries", h.RequireAuth(h.ListWebhookDeliveries))
+	mux.HandleFunc("POST /v1/webhooks", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CreateWebhook)))
+	mux.HandleFunc("GET /v1/webhooks", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListWebhooks)))
+	mux.HandleFunc("PATCH /v1/webhooks/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PatchWebhook)))
+	mux.HandleFunc("DELETE /v1/webhooks/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteWebhook)))
+	mux.HandleFunc("GET /v1/webhooks/{id}/deliveries", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListWebhookDeliveries)))
 
 	// Google Calendar — connect/callback/status/disconnect
-	mux.HandleFunc("GET /v1/calendar/connect", h.RequireAuth(h.ConnectCalendar))
-	mux.HandleFunc("GET /v1/calendar/callback", h.CalendarCallback)
-	mux.HandleFunc("POST /v1/calendar/caldav/connect", h.RequireAuth(h.ConnectCalDAV))
-	mux.HandleFunc("GET /v1/calendar/status", h.RequireAuth(h.CalendarStatus))
-	mux.HandleFunc("POST /v1/calendar/connections/{id}/destination", h.RequireAuth(h.SetCalendarDestination))
-	mux.HandleFunc("GET /v1/calendar/connections/{id}/calendars", h.RequireAuth(h.GetConnectionCalendars))
-	mux.HandleFunc("PUT /v1/calendar/connections/{id}/calendars", h.RequireAuth(h.PutConnectionCalendars))
-	mux.HandleFunc("DELETE /v1/calendar/connections/{id}", h.RequireAuth(h.DisconnectCalendarConnection))
-	mux.HandleFunc("DELETE /v1/calendar", h.RequireAuth(h.DisconnectCalendar))
+	mux.HandleFunc("GET /v1/calendar/connect", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ConnectCalendar)))
+	mux.HandleFunc("GET /v1/calendar/callback", h.Platform((*H).CalendarCallback))
+	mux.HandleFunc("POST /v1/calendar/caldav/connect", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ConnectCalDAV)))
+	mux.HandleFunc("GET /v1/calendar/status", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CalendarStatus)))
+	mux.HandleFunc("POST /v1/calendar/connections/{id}/destination", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).SetCalendarDestination)))
+	mux.HandleFunc("GET /v1/calendar/connections/{id}/calendars", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).GetConnectionCalendars)))
+	mux.HandleFunc("PUT /v1/calendar/connections/{id}/calendars", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).PutConnectionCalendars)))
+	mux.HandleFunc("DELETE /v1/calendar/connections/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DisconnectCalendarConnection)))
+	mux.HandleFunc("DELETE /v1/calendar", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DisconnectCalendar)))
 
 	// Zoom — per-host OAuth connect (auto-mint meeting links).
-	mux.HandleFunc("GET /v1/zoom/connect", h.RequireAuth(h.ConnectZoom))
-	mux.HandleFunc("GET /v1/zoom/callback", h.ZoomCallback)
-	mux.HandleFunc("GET /v1/zoom/status", h.RequireAuth(h.ZoomStatus))
-	mux.HandleFunc("DELETE /v1/zoom", h.RequireAuth(h.DisconnectZoom))
+	mux.HandleFunc("GET /v1/zoom/connect", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ConnectZoom)))
+	mux.HandleFunc("GET /v1/zoom/callback", h.Platform((*H).ZoomCallback))
+	mux.HandleFunc("GET /v1/zoom/status", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ZoomStatus)))
+	mux.HandleFunc("DELETE /v1/zoom", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DisconnectZoom)))
 
 	// Stripe payment webhook — public, authenticated by the signing secret (no session
 	// cookie, so the CSRF check doesn't apply). Must receive the raw body.
-	mux.HandleFunc("POST /v1/stripe/webhook", h.StripeWebhook)
+	mux.HandleFunc("POST /v1/stripe/webhook", h.Platform((*H).StripeWebhook))
 
 	// API keys
-	mux.HandleFunc("GET /v1/api-keys", h.RequireAuth(h.ListAPIKeys))
-	mux.HandleFunc("POST /v1/api-keys", h.RequireAuth(h.CreateAPIKey))
-	mux.HandleFunc("DELETE /v1/api-keys/{id}", h.RequireAuth(h.DeleteAPIKey))
+	mux.HandleFunc("GET /v1/api-keys", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListAPIKeys)))
+	mux.HandleFunc("POST /v1/api-keys", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).CreateAPIKey)))
+	mux.HandleFunc("DELETE /v1/api-keys/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).DeleteAPIKey)))
 
 	// Connected apps — MCP OAuth grants the user can review and revoke.
-	mux.HandleFunc("GET /v1/oauth/connections", h.RequireAuth(h.ListOAuthConnections))
-	mux.HandleFunc("DELETE /v1/oauth/connections/{id}", h.RequireAuth(h.RevokeOAuthConnection))
+	mux.HandleFunc("GET /v1/oauth/connections", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).ListOAuthConnections)))
+	mux.HandleFunc("DELETE /v1/oauth/connections/{id}", h.RequireAuth(h.Scoped(handler.CredentialWorkspace, (*H).RevokeOAuthConnection)))
 
 	// Demo instance only — one-click login, on-demand reset, and a disallow-all
 	// robots.txt. Never registered on a real deployment.
 	if cfg.DemoMode {
-		mux.HandleFunc("GET /v1/demo/enter", h.DemoEnter)
+		mux.HandleFunc("GET /v1/demo/enter", h.Platform((*H).DemoEnter))
 		demoResetRL := RateLimit(2, time.Minute)
-		mux.HandleFunc("POST /v1/demo/reset", demoResetRL(h.DemoReset))
-		mux.HandleFunc("GET /robots.txt", h.Robots)
+		mux.HandleFunc("POST /v1/demo/reset", demoResetRL(h.Platform((*H).DemoReset)))
+		mux.HandleFunc("GET /robots.txt", h.Platform((*H).Robots))
 	}
 
 	// Favicon at the root, shared by the public server-rendered pages and the

From 1566fefba38735407c5b04ca7c06a017e552fdb3 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 02:07:58 -0400
Subject: [PATCH 30/51] server: prove the tenancy end to end, through the real
 mux and a real OpenPair
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two workspaces on distinct public hosts, one process, and an application handle
that is a NOBYPASSRLS role owning nothing. Eight assertions, each in both
directions: event types list, bookings list, slots, the public booking page,
GET /v1/bookings/{id} (200 for its own, 404 for B's), a public create that lands
in acme and leaves B's count unmoved, an MCP list_bookings over the streamable
HTTP transport, and A's key on B's host refused 403 {"error":"workspace
mismatch"} while the same key on the identity host still works.

The MCP call is asserted in both directions, A then B, because that is what
catches a cached server built for whichever workspace called first.

dbtest.RequireTenantPair is the harness, now reusable: it creates the role, grants
the schema, enables RLS, opens the pair and runs VerifyRoles. It SKIPS LOUDLY
rather than falling back if the role cannot be created or turns out to bypass,
because every assertion in this file passes through a superuser handle whether the
policies exist or not.

VerifyMCPBearer was reading credentials on the tenant handle — all four of its
statements. /mcp is on the identity host so no workspace is bound at all, and the
test found it as "connect to /mcp: Unauthorized": on a multi-tenant instance every
valid bearer token would have been rejected. Now on platformDB, the third place
where a global-unique credential lookup had to move. The pattern is that any read
whose purpose is to discover the tenant cannot be bound to it.

Two controls. Stubbing the binding off fails everything at the fixture with
SQLSTATE 42501, which proves the binding is load-bearing and nothing more. Giving
the application handle the bypassing owner role — the "a superuser DSN proves
nothing" case made concrete — is the one that shows the assertions working: A's
booking list contains B's booking, B's slots render on A's host, B's booking page
returns 200, B's booking id returns 200 with B's data, and both MCP directions
leak.

A trap the fixture paid for: server.New's drain blocks until the worker finishes
its cycle, and the worker stops only when its context is done, so passing
context.Background() gives a green body and a hang in Worker.Wait that reads as a
deadlock in the code under test.

PROGRESS.md carries two notes into B6: vendor webhooks must resolve their
workspace from the row they name on the platform handle and then hand off to
forWorkspace, and every INSERT through a Platform route or the platform API must
name workspace_id explicitly, because the platform handle binds '' and the column
default would land the row in 'default' silently.
---
 PROGRESS.md                         | 107 +++++++
 internal/dbtest/tenant.go           | 118 ++++++++
 internal/handler/mcp_oauth.go       |  15 +-
 internal/server/tenancy_e2e_test.go | 434 ++++++++++++++++++++++++++++
 4 files changed, 670 insertions(+), 4 deletions(-)
 create mode 100644 internal/dbtest/tenant.go
 create mode 100644 internal/server/tenancy_e2e_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 4e10e35..b978a23 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -844,3 +844,110 @@ whole instance.
 ### Gates
 
 `gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+
+## Boundary 3, part three — the end-to-end tenancy proof
+
+Two workspaces on distinct public hosts, one process, the **real mux** via
+`httptest`, and a real `db.OpenPair` whose application handle is a `NOBYPASSRLS`
+role that owns nothing. `internal/server/tenancy_e2e_test.go`, and the harness it
+uses is now reusable: `dbtest.RequireTenantPair(t)`.
+
+Eight assertions, each in both directions:
+
+| surface | A sees its own | A cannot reach B's |
+|---|---|---|
+| `GET /v1/event-types` (API key) | ✓ | ✓ |
+| `GET /v1/bookings?scope=all` (API key) | ✓ | ✓ |
+| `GET /v1/event-types/{slug}/slots` (public) | ✓ | ✓ |
+| `GET /book/{slug}` (public page) | — | ✓ |
+| `GET /v1/bookings/{id}` | 200 | **404** |
+| `POST /v1/bookings` (public write) | lands in `acme` | B's count unmoved |
+| MCP `list_bookings` over the HTTP transport | ✓ | ✓ (both directions) |
+| A's API key on B's host | — | **403 `workspace mismatch`** |
+
+The MCP call is a real `tools/call` through `mcp.StreamableClientTransport`
+against an `httptest.Server`, with the `cno_` key as a bearer token. It is
+asserted in **both** directions — A then B — because that is what catches a
+cached server built for whichever workspace called first. The mismatch test also
+checks the same key on the **identity** host still works: that host names no
+workspace, so there is nothing to disagree with, and it is where API and MCP
+callers legitimately arrive.
+
+### ⛔ `VerifyMCPBearer` was reading credentials on the tenant handle
+
+Found by the MCP test failing `connect to /mcp: Unauthorized`. All four of its
+reads and writes — `oauth_access_tokens`, `api_keys`, and the two `last_used_at`
+updates — ran on `h.db`. `/mcp` is on the identity host, so **no workspace is
+bound at all**, and every valid bearer token would have been reported
+Unauthorized on a multi-tenant instance. Now on `platformDB()`, which is the same
+reasoning as `RequireAuth` and `MCPCallerMiddleware`, and the third place in the
+tree where a global-unique credential lookup had to move. That is the pattern:
+**any read whose purpose is to discover the tenant cannot be bound to it.**
+
+### Two controls, and the second is the one that matters
+
+**Control 1 — the binding stubbed off** (`DB.binds()` forced false). Every test
+fails, but at the FIXTURE, because the seeding writes are refused:
+
+```
+tenancy_e2e_test.go:192: create user for acme: ERROR: new row violates row-level security policy for table "users" (SQLSTATE 42501)
+```
+
+That proves the binding is load-bearing, and nothing more — the read assertions
+never run.
+
+**Control 2 — the application handle given the bypassing owner role**, with
+`VerifyRoles`' refusal disabled. This is the "a superuser DSN proves nothing"
+scenario made concrete, and it is what shows the assertions themselves working:
+
+```
+--- FAIL: TestTenancy_readSurfaces/bookings_list
+    A's booking list contains B's "globex-booking"
+--- FAIL: TestTenancy_readSurfaces/slots_for_B's_event_type_on_A's_host
+    B's event type produced slots on A's host: {…"host_ids":["globex-user"]…}
+--- FAIL: TestTenancy_readSurfaces/public_event_type_page_for_B's_slug_on_A's_host
+    B's booking page rendered on A's host: status 200
+--- FAIL: TestTenancy_bookingByIDIsNotFoundAcrossWorkspaces
+    B's booking id on A's host: status = 200, want 404: {"id":"globex-booking",…}
+--- FAIL: TestTenancy_mcpToolCallOverHTTP
+    A's MCP list_bookings returned B's booking "globex-booking"
+    B's MCP list_bookings returned A's booking "acme-booking"
+```
+
+⚠️ Worth stating plainly: **that is what this code does without the NOBYPASSRLS
+role.** It is why `RequireTenantPair` skips loudly rather than falling back, and
+why `VerifyRoles` refuses the boot.
+
+### ⚠️ A trap the fixture paid for
+
+`server.New`'s `drain` blocks until the worker finishes its poll cycle, and the
+worker only stops when its context is done. Passing `context.Background()` gives a
+**green test body and a hang in `Worker.Wait`** at cleanup, which reads as a
+deadlock in the code under test. `main.go` cancels then drains; the fixture now
+does the same.
+
+---
+
+## Carried into later boundaries
+
+⛔ **Vendor webhooks (B6).** `POST /v1/livekit/webhook`, its
+`/v1/livekit/egress-webhook` alias, and `POST /v1/stripe/webhook` are classified
+`Platform` today, which gets them far enough to find their row and no further.
+They arrive at whatever host the vendor was given and carry no tenant Host, so
+each must **resolve its workspace from the row it names** — the recording's `room`,
+the booking's `stripe_session_id` — on the platform handle, and then hand off to
+`h.forWorkspace(ws)` for **all** processing. A test per webhook that a room or
+session belonging to B, handled on the platform path, writes only into B.
+
+⛔ **Every INSERT through a `Platform`-wrapped route or the platform API must name
+`workspace_id` explicitly.** The platform handle binds `''`, and the column default
+is `COALESCE(current_setting('app.workspace_id', true), 'default')` — so a write
+that omits the column lands in **`default`**, silently, rather than failing. The
+e2e fixture already has to do this for `workspaces` and `server_settings`. B6 owes
+a test on the platform API's create path that the row carries the **requested**
+workspace id, not `default`.
+
+⚠️ **The platform `/metrics` endpoint** (on `feat/platform-hooks`) reads the `jobs`
+table, which is a tenant table. At integration it must read through `Platform()`:
+on the application handle it would report one workspace's queue, and on the unbound
+handle, zero.
diff --git a/internal/dbtest/tenant.go b/internal/dbtest/tenant.go
new file mode 100644
index 0000000..d161e8d
--- /dev/null
+++ b/internal/dbtest/tenant.go
@@ -0,0 +1,118 @@
+package dbtest
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"net/url"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// RequireTenantPair returns a live multi-tenant handle pair against the test's own
+// schema: app connected as a freshly created NOBYPASSRLS role that owns nothing,
+// and platform as the suite's own role, which owns the schema and bypasses.
+// Row-level security is enabled before it returns.
+//
+// ⛔ THE NON-SUPERUSER ROLE IS THE WHOLE POINT. Superusers bypass row-level
+// security unconditionally, so does any role with BYPASSRLS, and so does a table's
+// owner unless FORCE is set. The suite's DSN is normally the superuser that owns
+// the test schema, so a tenancy assertion made through it passes whether the
+// policies exist or not. This SKIPS LOUDLY rather than falling back if the role
+// cannot be created, reports rolsuper/rolbypassrls, or owns a table.
+//
+// It lives here rather than in an internal/db test file because more than one
+// package needs it: internal/db proves the handle, internal/server proves the
+// routes, and Boundary 7 proves the whole surface.
+func RequireTenantPair(t *testing.T) (app, platform *db.DB) {
+	t.Helper()
+
+	dsn := PostgresDSN()
+	if dsn == "" {
+		t.Skipf("LOUD SKIP: %s is not set. A multi-tenant test needs a real PostgreSQL server: "+
+			"the isolation guarantee is row-level security, and there is nothing to assert without it.", DSNEnv)
+	}
+
+	owner := openPostgres(t, dsn) // creates the schema, migrates it, drops it after
+
+	var schema string
+	if err := owner.QueryRow(`SELECT current_schema()`).Scan(&schema); err != nil {
+		t.Fatalf("dbtest: read current_schema: %v", err)
+	}
+
+	// Random hex, so a name interpolated into DDL cannot carry a quote or a
+	// keyword. PostgreSQL takes no placeholder for a role name.
+	buf := make([]byte, 8)
+	if _, err := rand.Read(buf); err != nil {
+		t.Fatalf("dbtest: rand: %v", err)
+	}
+	role := "calnode_app_" + hex.EncodeToString(buf)
+	const password = "tenant_pair_pw" // a local test role, dropped when the test ends
+
+	if _, err := owner.Exec(`CREATE ROLE ` + role + ` LOGIN PASSWORD '` + password + `' NOBYPASSRLS`); err != nil {
+		t.Skipf("LOUD SKIP: cannot CREATE ROLE on this server (%v). The multi-tenant tests REQUIRE a "+
+			"NOBYPASSRLS role — asserting isolation through the suite's own superuser DSN would pass "+
+			"with or without the policies. Point %s at a server where the test role may create roles.",
+			err, DSNEnv)
+	}
+	t.Cleanup(func() {
+		// DROP OWNED also revokes the grants below, which DROP ROLE would refuse over.
+		if _, err := owner.Exec(`DROP OWNED BY ` + role); err != nil {
+			t.Errorf("dbtest: drop owned by %s: %v", role, err)
+		}
+		if _, err := owner.Exec(`DROP ROLE ` + role); err != nil {
+			t.Errorf("dbtest: drop role %s: %v", role, err)
+		}
+	})
+
+	for _, stmt := range []string{
+		`GRANT USAGE ON SCHEMA ` + quoteIdent(schema) + ` TO ` + role,
+		`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ` + quoteIdent(schema) + ` TO ` + role,
+		`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ` + quoteIdent(schema) + ` TO ` + role,
+	} {
+		if _, err := owner.Exec(stmt); err != nil {
+			t.Fatalf("dbtest: %s: %v", stmt, err)
+		}
+	}
+
+	if err := owner.EnableRLS(context.Background()); err != nil {
+		t.Fatalf("dbtest: EnableRLS: %v", err)
+	}
+
+	app, platform, err := db.OpenPair(
+		rewriteUser(t, dsn, role, password, schema),
+		withSearchPath(t, dsn, schema),
+	)
+	if err != nil {
+		t.Fatalf("dbtest: OpenPair: %v", err)
+	}
+	t.Cleanup(func() {
+		app.Close()
+		platform.Close()
+	})
+
+	// The guard that turns "the application role cannot bypass" from an assumption
+	// into a checked fact, and that would catch a role able to read everything.
+	if err := app.VerifyRoles(context.Background()); err != nil {
+		t.Skipf("LOUD SKIP: VerifyRoles rejected this pair, so nothing below would prove isolation: %v", err)
+	}
+
+	return app, platform
+}
+
+// rewriteUser points dsn at a different role and pins search_path. pgx forwards
+// unrecognised query parameters as PostgreSQL runtime parameters, which is how
+// search_path reaches the session — the same mechanism openPostgres uses.
+func rewriteUser(t *testing.T, dsn, user, password, schema string) string {
+	t.Helper()
+	u, err := url.Parse(dsn)
+	if err != nil {
+		t.Fatalf("dbtest: parse %s: %v", DSNEnv, err)
+	}
+	u.User = url.UserPassword(user, password)
+	q := u.Query()
+	q.Set("search_path", schema)
+	u.RawQuery = q.Encode()
+	return u.String()
+}
diff --git a/internal/handler/mcp_oauth.go b/internal/handler/mcp_oauth.go
index b63abb8..7a2629e 100644
--- a/internal/handler/mcp_oauth.go
+++ b/internal/handler/mcp_oauth.go
@@ -120,9 +120,16 @@ func (h *Handler) MCPCallerMiddleware(next http.Handler) http.Handler {
 func (h *Handler) VerifyMCPBearer(ctx context.Context, token string, _ *http.Request) (*auth.TokenInfo, error) {
 	hash := hashAPIKey(token)
 
+	// ⛔ platformDB, not h.db, for every read below. oauth_access_tokens.token_hash
+	// and api_keys.key_hash are globally unique precisely so a bearer token
+	// resolves before a tenant is known — which is what these reads DO. On the
+	// application handle they run bound to the workspace of the request, and /mcp
+	// is on the identity host so there is no workspace bound at all: every valid
+	// token would be reported Unauthorized.
+
 	// OAuth access token?
 	var userID, expiresAt string
-	err := h.db.QueryRowContext(ctx,
+	err := h.platformDB().QueryRowContext(ctx,
 		`SELECT user_id, expires_at FROM oauth_access_tokens WHERE token_hash = ?`, hash).
 		Scan(&userID, &expiresAt)
 	if err == nil {
@@ -131,17 +138,17 @@ func (h *Handler) VerifyMCPBearer(ctx context.Context, token string, _ *http.Req
 			return nil, auth.ErrInvalidToken // expired — client should refresh
 		}
 		now := time.Now().UTC().Format(time.RFC3339Nano)
-		_, _ = h.db.ExecContext(ctx, `UPDATE oauth_access_tokens SET last_used_at = ? WHERE token_hash = ?`, now, hash)
+		_, _ = h.platformDB().ExecContext(ctx, `UPDATE oauth_access_tokens SET last_used_at = ? WHERE token_hash = ?`, now, hash)
 		return &auth.TokenInfo{UserID: userID, Expiration: exp}, nil
 	}
 
 	// API key fallback (programmatic callers).
 	var keyUser string
-	if err := h.db.QueryRowContext(ctx, `
+	if err := h.platformDB().QueryRowContext(ctx, `
 		SELECT u.id FROM api_keys ak JOIN users u ON u.id = ak.user_id
 		WHERE ak.key_hash = ? AND u.archived_at IS NULL`, hash).Scan(&keyUser); err == nil {
 		now := time.Now().UTC().Format(time.RFC3339Nano)
-		_, _ = h.db.ExecContext(ctx, `UPDATE api_keys SET last_used_at = ? WHERE key_hash = ?`, now, hash)
+		_, _ = h.platformDB().ExecContext(ctx, `UPDATE api_keys SET last_used_at = ? WHERE key_hash = ?`, now, hash)
 		// API keys don't expire; report a far-future expiry so the SDK doesn't reject it.
 		return &auth.TokenInfo{UserID: keyUser, Expiration: time.Now().Add(mcpAccessTokenTTL)}, nil
 	}
diff --git a/internal/server/tenancy_e2e_test.go b/internal/server/tenancy_e2e_test.go
new file mode 100644
index 0000000..1dc457e
--- /dev/null
+++ b/internal/server/tenancy_e2e_test.go
@@ -0,0 +1,434 @@
+package server_test
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/calnode/calnode/internal/config"
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/server"
+)
+
+// The end-to-end tenancy proof: two workspaces on distinct public hosts, one
+// process, the real mux, and a real db.OpenPair whose application handle is a
+// NOBYPASSRLS role that owns nothing.
+//
+// ⛔ Everything below would pass through a superuser handle whether the policies
+// existed or not, which is why dbtest.RequireTenantPair skips LOUDLY rather than
+// falling back. What is asserted is not "the handler filtered correctly" — it is
+// that B's rows are not reachable from A's request even though no handler in the
+// tree carries a workspace predicate.
+
+const (
+	hostA = "book.acme.example"
+	hostB = "book.globex.example"
+)
+
+type tenant struct {
+	id, host, apiKey, userID, eventSlug, bookingID string
+}
+
+type tenancyFixture struct {
+	mux  http.Handler
+	app  *db.DB
+	plat *db.DB
+	a, b tenant
+}
+
+func newTenancyFixture(t *testing.T) *tenancyFixture {
+	t.Helper()
+
+	app, platform := dbtest.RequireTenantPair(t)
+
+	cfg := &config.Config{
+		MultiTenant:         true,
+		BaseURL:             "https://app.calnode.example",
+		PublicBaseURL:       "https://app.calnode.example",
+		DatabaseURL:         "postgres://app", // not dialled; New takes the handle
+		EmbedAllowedOrigins: nil,
+	}
+	// ⚠️ The worker's context has to be cancelled BEFORE drain: drain blocks until
+	// the worker finishes its current poll cycle, and the worker only stops when
+	// its context is done. main.go does the same pair; passing
+	// context.Background() here hangs the test in Worker.Wait with an otherwise
+	// green body.
+	workerCtx, stopWorker := context.WithCancel(context.Background())
+	mux, drain := server.New(workerCtx, cfg, app, slog.New(slog.DiscardHandler))
+	t.Cleanup(func() {
+		stopWorker()
+		drain()
+	})
+
+	f := &tenancyFixture{mux: mux, app: app, plat: platform}
+	f.a = seedTenant(t, app, platform, "acme", hostA)
+	f.b = seedTenant(t, app, platform, "globex", hostB)
+	return f
+}
+
+// seedTenant provisions one workspace end to end: the workspaces row and the
+// server_settings row through the PLATFORM handle (naming workspace_id, because
+// the platform handle binds ” and the column default would otherwise put the row
+// in 'default'), then everything else through the workspace-bound handle with no
+// column named, which is D1's whole point.
+func seedTenant(t *testing.T, app, platform *db.DB, id, host string) tenant {
+	t.Helper()
+	ctx := context.Background()
+
+	if _, err := platform.ExecContext(ctx,
+		`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', 'active')`,
+		id, id, host); err != nil {
+		t.Fatalf("create workspace %s: %v", id, err)
+	}
+	if _, err := platform.ExecContext(ctx,
+		`INSERT INTO server_settings (workspace_id, id) VALUES (?, 1)`, id); err != nil {
+		t.Fatalf("seed settings for %s: %v", id, err)
+	}
+
+	h := app.ForWorkspace(id)
+	tn := tenant{
+		id: id, host: host,
+		userID:    id + "-user",
+		eventSlug: id + "-intro",
+		bookingID: id + "-booking",
+	}
+
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO users (id, email, name, is_admin, is_owner) VALUES (?, ?, ?, 1, 1)`,
+		tn.userID, id+"@example.com", strings.ToUpper(id)); err != nil {
+		t.Fatalf("create user for %s: %v", id, err)
+	}
+
+	// cno_ keys are hashed with SHA-256 and api_keys.key_hash stays globally
+	// unique on purpose (D9): the credential has to resolve before a tenant is
+	// known.
+	tn.apiKey = "cno_" + id + "_key"
+	sum := sha256.Sum256([]byte(tn.apiKey))
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO api_keys (id, user_id, name, key_hash) VALUES (?, ?, 'test', ?)`,
+		id+"-key", tn.userID, hex.EncodeToString(sum[:])); err != nil {
+		t.Fatalf("create api key for %s: %v", id, err)
+	}
+
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO event_types (id, user_id, slug, name, duration_minutes, slot_interval_minutes,
+		    min_notice_minutes, max_future_days, is_active, is_public)
+		 VALUES (?, ?, ?, ?, 30, 30, 0, 60, 1, 1)`,
+		id+"-et", tn.userID, tn.eventSlug, strings.ToUpper(id)+" intro"); err != nil {
+		t.Fatalf("create event type for %s: %v", id, err)
+	}
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO event_type_hosts (id, event_type_id, user_id, role, priority)
+		 VALUES (?, ?, ?, 'required', 0)`,
+		id+"-eth", id+"-et", tn.userID); err != nil {
+		t.Fatalf("host row for %s: %v", id, err)
+	}
+	// Availability every day, so slots are generated whatever day the test runs.
+	for dow := 0; dow < 7; dow++ {
+		if _, err := h.ExecContext(ctx,
+			`INSERT INTO availability_rules (id, user_id, day_of_week, start_time, end_time)
+			 VALUES (?, ?, ?, '09:00', '17:00')`,
+			fmt.Sprintf("%s-av-%d", id, dow), tn.userID, dow); err != nil {
+			t.Fatalf("availability for %s: %v", id, err)
+		}
+	}
+
+	start := time.Now().UTC().Add(48 * time.Hour).Truncate(time.Hour)
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at, status)
+		 VALUES (?, ?, ?, ?, ?, 'confirmed')`,
+		tn.bookingID, id+"-et", tn.userID,
+		start.Format(time.RFC3339), start.Add(30*time.Minute).Format(time.RFC3339)); err != nil {
+		t.Fatalf("create booking for %s: %v", id, err)
+	}
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO booking_hosts (id, booking_id, user_id, is_primary) VALUES (?, ?, ?, 1)`,
+		id+"-bh", tn.bookingID, tn.userID); err != nil {
+		t.Fatalf("booking host for %s: %v", id, err)
+	}
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO booking_attendees (id, booking_id, name, email, is_organizer)
+		 VALUES (?, ?, ?, ?, 1)`,
+		id+"-att", tn.bookingID, strings.ToUpper(id)+" booker", "booker-"+id+"@example.com"); err != nil {
+		t.Fatalf("attendee for %s: %v", id, err)
+	}
+
+	return tn
+}
+
+// do sends a request through the real mux.
+func (f *tenancyFixture) do(t *testing.T, method, host, path, apiKey, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	var r *http.Request
+	if body == "" {
+		r = httptest.NewRequest(method, path, nil)
+	} else {
+		r = httptest.NewRequest(method, path, strings.NewReader(body))
+		r.Header.Set("Content-Type", "application/json")
+	}
+	r.Host = host
+	if apiKey != "" {
+		r.Header.Set("X-API-Key", apiKey)
+	}
+	rec := httptest.NewRecorder()
+	f.mux.ServeHTTP(rec, r)
+	return rec
+}
+
+// TestTenancy_readSurfaces covers the four read shapes the packet names, each
+// asserted in both directions: A sees its own, and A cannot see B's.
+func TestTenancy_readSurfaces(t *testing.T) {
+	f := newTenancyFixture(t)
+
+	t.Run("event types list", func(t *testing.T) {
+		rec := f.do(t, http.MethodGet, f.a.host, "/v1/event-types", f.a.apiKey, "")
+		if rec.Code != http.StatusOK {
+			t.Fatalf("status = %d: %s", rec.Code, rec.Body.String())
+		}
+		body := rec.Body.String()
+		if !strings.Contains(body, f.a.eventSlug) {
+			t.Errorf("A's own event type is missing: %s", body)
+		}
+		if strings.Contains(body, f.b.eventSlug) {
+			t.Errorf("A's event type list contains B's %q: %s", f.b.eventSlug, body)
+		}
+	})
+
+	t.Run("bookings list", func(t *testing.T) {
+		rec := f.do(t, http.MethodGet, f.a.host, "/v1/bookings?scope=all", f.a.apiKey, "")
+		if rec.Code != http.StatusOK {
+			t.Fatalf("status = %d: %s", rec.Code, rec.Body.String())
+		}
+		body := rec.Body.String()
+		if !strings.Contains(body, f.a.bookingID) {
+			t.Errorf("A's own booking is missing: %s", body)
+		}
+		if strings.Contains(body, f.b.bookingID) {
+			t.Errorf("A's booking list contains B's %q: %s", f.b.bookingID, body)
+		}
+	})
+
+	t.Run("slots for B's event type on A's host", func(t *testing.T) {
+		// A's own slug resolves.
+		day := time.Now().UTC().Add(48 * time.Hour).Format("2006-01-02")
+		own := f.do(t, http.MethodGet, f.a.host,
+			"/v1/event-types/"+f.a.eventSlug+"/slots?date="+day, "", "")
+		if own.Code != http.StatusOK {
+			t.Fatalf("A's own slots: status = %d: %s", own.Code, own.Body.String())
+		}
+
+		// B's does not, on A's host, even though the slug exists in the database.
+		other := f.do(t, http.MethodGet, f.a.host,
+			"/v1/event-types/"+f.b.eventSlug+"/slots?date="+day, "", "")
+		if other.Code == http.StatusOK {
+			t.Errorf("B's event type produced slots on A's host: %s", other.Body.String())
+		}
+		if strings.Contains(other.Body.String(), f.b.eventSlug) &&
+			!strings.Contains(strings.ToLower(other.Body.String()), "not found") {
+			t.Errorf("B's slug leaked into the response: %s", other.Body.String())
+		}
+	})
+
+	t.Run("public event type page for B's slug on A's host", func(t *testing.T) {
+		rec := f.do(t, http.MethodGet, f.a.host, "/book/"+f.b.eventSlug, "", "")
+		if rec.Code == http.StatusOK {
+			t.Errorf("B's booking page rendered on A's host: status 200")
+		}
+	})
+}
+
+// TestTenancy_bookingByIDIsNotFoundAcrossWorkspaces. GET /v1/bookings/{id} is
+// host-scoped, so the 404 comes from the row not being visible under the policy
+// rather than from a predicate the handler remembered to write.
+func TestTenancy_bookingByIDIsNotFoundAcrossWorkspaces(t *testing.T) {
+	f := newTenancyFixture(t)
+
+	own := f.do(t, http.MethodGet, f.a.host, "/v1/bookings/"+f.a.bookingID, "", "")
+	if own.Code != http.StatusOK {
+		t.Fatalf("A's own booking on A's host: status = %d: %s", own.Code, own.Body.String())
+	}
+
+	other := f.do(t, http.MethodGet, f.a.host, "/v1/bookings/"+f.b.bookingID, "", "")
+	if other.Code != http.StatusNotFound {
+		t.Errorf("B's booking id on A's host: status = %d, want 404: %s", other.Code, other.Body.String())
+	}
+	if strings.Contains(other.Body.String(), "booker-globex") {
+		t.Errorf("B's attendee leaked: %s", other.Body.String())
+	}
+}
+
+// TestTenancy_credentialOnTheWrongHostIs403 is D10's mismatch rule, body included.
+func TestTenancy_credentialOnTheWrongHostIs403(t *testing.T) {
+	f := newTenancyFixture(t)
+
+	rec := f.do(t, http.MethodGet, f.b.host, "/v1/bookings", f.a.apiKey, "")
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("A's key on B's host: status = %d, want 403: %s", rec.Code, rec.Body.String())
+	}
+	var body map[string]string
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("decode %q: %v", rec.Body.String(), err)
+	}
+	if body["error"] != "workspace mismatch" {
+		t.Errorf("error = %q; want \"workspace mismatch\"", body["error"])
+	}
+
+	// And the same key on the identity host is fine: that host names no workspace,
+	// so there is nothing to disagree with. API and MCP callers arrive there.
+	ok := f.do(t, http.MethodGet, "app.calnode.example", "/v1/bookings", f.a.apiKey, "")
+	if ok.Code != http.StatusOK {
+		t.Errorf("A's key on the identity host: status = %d: %s", ok.Code, ok.Body.String())
+	}
+}
+
+// TestTenancy_writeLandsInItsOwnWorkspace is the write half: a public booking
+// created on A's host must carry A's workspace_id, and B's row count must not move.
+func TestTenancy_writeLandsInItsOwnWorkspace(t *testing.T) {
+	f := newTenancyFixture(t)
+	ctx := context.Background()
+
+	before := f.countBookings(t, f.b.id)
+
+	// 10:00 UTC three days out: inside the 09:00-17:00 availability the fixture
+	// seeds for every weekday, clear of the min-notice window, and on the 30-minute
+	// interval the event type offers.
+	d := time.Now().UTC().Add(72 * time.Hour)
+	start := time.Date(d.Year(), d.Month(), d.Day(), 10, 0, 0, 0, time.UTC)
+	body := fmt.Sprintf(`{"event_type_slug":%q,"start_at":%q,"name":"Nia","email":"nia@example.com","iana_timezone":"UTC"}`,
+		f.a.eventSlug, start.Format(time.RFC3339))
+	rec := f.do(t, http.MethodPost, f.a.host, "/v1/bookings", "", body)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("create on A's host: status = %d: %s", rec.Code, rec.Body.String())
+	}
+
+	var created struct {
+		ID string `json:"id"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &created); err != nil {
+		t.Fatalf("decode %q: %v", rec.Body.String(), err)
+	}
+	if created.ID == "" {
+		t.Fatalf("no id in %s", rec.Body.String())
+	}
+
+	// Read it back through the PLATFORM handle, which sees every workspace, so the
+	// assertion is about where the row IS rather than about what A can see.
+	var ws string
+	if err := f.plat.QueryRowContext(ctx,
+		`SELECT workspace_id FROM bookings WHERE id = ?`, created.ID).Scan(&ws); err != nil {
+		t.Fatalf("read the created booking: %v", err)
+	}
+	if ws != f.a.id {
+		t.Errorf("the booking landed in workspace %q; want %q", ws, f.a.id)
+	}
+	// ⛔ Not 'default' either: the column default is
+	// COALESCE(current_setting(...), 'default'), so a write that escaped the
+	// binding would land there rather than failing visibly.
+	if ws == db.DefaultWorkspaceID {
+		t.Error("the booking landed in the default workspace — the statement was not bound")
+	}
+
+	if after := f.countBookings(t, f.b.id); after != before {
+		t.Errorf("B's booking count moved from %d to %d", before, after)
+	}
+}
+
+// TestTenancy_mcpToolCallOverHTTP drives a real tools/call through the streamable
+// HTTP transport, which is the surface a remote agent uses. /mcp is on the identity
+// host and carries no tenant Host, so the bearer credential is the only source of
+// the workspace (D10) — and the tools close over their handler, which is why
+// MCPServerForRequest builds one server per workspace.
+func TestTenancy_mcpToolCallOverHTTP(t *testing.T) {
+	f := newTenancyFixture(t)
+	ctx := context.Background()
+
+	srv := httptest.NewServer(f.mux)
+	t.Cleanup(srv.Close)
+
+	callList := func(apiKey string) string {
+		t.Helper()
+		transport := &mcp.StreamableClientTransport{
+			Endpoint:             srv.URL + "/mcp",
+			HTTPClient:           &http.Client{Transport: bearerTransport{key: apiKey}},
+			DisableStandaloneSSE: true,
+		}
+		client := mcp.NewClient(&mcp.Implementation{Name: "tenancy-test", Version: "0"}, nil)
+		session, err := client.Connect(ctx, transport, nil)
+		if err != nil {
+			t.Fatalf("connect to /mcp: %v", err)
+		}
+		defer session.Close()
+
+		res, err := session.CallTool(ctx, &mcp.CallToolParams{
+			Name:      "list_bookings",
+			Arguments: map[string]any{"status": "confirmed"},
+		})
+		if err != nil {
+			t.Fatalf("list_bookings: %v", err)
+		}
+		if res.IsError {
+			t.Fatalf("list_bookings returned an error result: %+v", res.Content)
+		}
+		var sb strings.Builder
+		for _, c := range res.Content {
+			if tc, ok := c.(*mcp.TextContent); ok {
+				sb.WriteString(tc.Text)
+			}
+		}
+		return sb.String()
+	}
+
+	got := callList(f.a.apiKey)
+	if !strings.Contains(got, f.a.bookingID) {
+		t.Errorf("A's MCP list_bookings is missing A's own booking: %s", got)
+	}
+	if strings.Contains(got, f.b.bookingID) {
+		t.Errorf("A's MCP list_bookings returned B's booking %q: %s", f.b.bookingID, got)
+	}
+
+	// The mirror, which is what catches a cached server built for whichever
+	// workspace happened to call first.
+	gotB := callList(f.b.apiKey)
+	if !strings.Contains(gotB, f.b.bookingID) {
+		t.Errorf("B's MCP list_bookings is missing B's own booking: %s", gotB)
+	}
+	if strings.Contains(gotB, f.a.bookingID) {
+		t.Errorf("B's MCP list_bookings returned A's booking %q: %s", f.a.bookingID, gotB)
+	}
+}
+
+func (f *tenancyFixture) countBookings(t *testing.T, workspace string) int {
+	t.Helper()
+	var n int
+	if err := f.plat.QueryRowContext(context.Background(),
+		`SELECT COUNT(*) FROM bookings WHERE workspace_id = ?`, workspace).Scan(&n); err != nil {
+		t.Fatalf("count bookings in %s: %v", workspace, err)
+	}
+	return n
+}
+
+// bearerTransport adds the API key to every MCP request. The streamable transport
+// takes an *http.Client but no header hook, and /mcp accepts a cno_ key as a
+// bearer token (VerifyMCPBearer) as well as an OAuth access token.
+type bearerTransport struct{ key string }
+
+func (b bearerTransport) RoundTrip(r *http.Request) (*http.Response, error) {
+	clone := r.Clone(r.Context())
+	clone.Header.Set("Authorization", "Bearer "+b.key)
+	res, err := http.DefaultTransport.RoundTrip(clone)
+	if err != nil {
+		return nil, err
+	}
+	return res, nil
+}

From 67e8ec55305c9b026c743cd8f5ec265f4973ac27 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 02:19:39 -0400
Subject: [PATCH 31/51] handler: sweep every identity-resolving read, and fix
 the two that were wrong
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three of these had been fixed one at a time, each found by a failing test
(RequireAuth, MCPCallerMiddleware, VerifyMCPBearer). This enumerates all eighteen
sites so the fourth is not found the same way. The table is in PROGRESS.md.

The rule: a read whose job is to discover the tenant cannot be bound to it. The
corollary is what the two findings are: a WRITE on a Platform-wrapped route must
name workspace_id, because the platform handle binds '' and the column default is
COALESCE(current_setting('app.workspace_id', true), 'default') — so an omitted
column does not fail, it lands the row in the default workspace.

Fifteen sites were already right. Six are on platformDB or are Platform-wrapped
routes where h.db already IS the platform handle. Nine are correctly on the bound
handle: magic links, invites and manage tokens are read on host-scoped routes and
the email that carried them was sent from that workspace's own public host, so a
token of B presented on A's host resolves to nothing — which is the right answer
and is now tested.

Two were wrong.

The OAuth grant inserts (oauth_auth_codes, oauth_access_tokens) named no
workspace_id, so every MCP Connect grant landed in the default workspace. It still
worked, which is why nothing caught it: VerifyMCPBearer reads on the platform
handle and bypasses the policies, so agents connected and called tools normally.
What broke was ownership — the workspace's Connected-apps page could neither list
nor revoke the grant, and deleting the workspace would not have cascaded it. A
revocation UI that silently cannot revoke is worse than none. Fixed by naming
workspace_id from a new workspaceOfUser helper on the platform handle, and tested
by driving the real flow: register, consent with its CSRF cookie, token exchange
with PKCE S256, then assert the row's workspace through the platform handle and
that A's connections page lists it while B's does not.

POST /v1/setup is Platform-wrapped and creates the first user plus a live API key;
both would land in the default workspace, a working credential in a tenant nobody
owns and no host reaches. It now 404s under MULTI_TENANT. Narrow in practice —
setup's own 409 guard covers it once any user exists — so this is the fresh-database
window plus defence in depth, and PROGRESS.md says so rather than overselling it.

One assertion had to be corrected and it is a trap worth keeping: the manage page
answers 200 with TokenInvalid for an unknown token, by design, because it is a
booker-facing page and not an API. A status-code assertion against a surface that
renders its own errors proves nothing; the test now asserts on content.

gofmt -l empty, go vet clean.
---
 PROGRESS.md                             | 101 ++++++++
 internal/handler/mcp_oauth_authorize.go |  32 ++-
 internal/handler/setup.go               |  14 ++
 internal/handler/workspace.go           |  21 ++
 internal/server/tenancy_e2e_test.go     |  26 ++
 internal/server/tenancy_sweep_test.go   | 317 ++++++++++++++++++++++++
 6 files changed, 505 insertions(+), 6 deletions(-)
 create mode 100644 internal/server/tenancy_sweep_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index b978a23..28515ec 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -951,3 +951,104 @@ workspace id, not `default`.
 table, which is a tenant table. At integration it must read through `Platform()`:
 on the application handle it would report one workspace's queue, and on the unbound
 handle, zero.
+
+## The identity-resolution sweep
+
+Every read whose PURPOSE is to resolve an identity or a tenant **before one is
+bound**. Three had already been fixed one at a time (`RequireAuth`,
+`MCPCallerMiddleware`, `VerifyMCPBearer`); this is the enumeration, so the fourth
+is not found by another failing test.
+
+The rule the table applies: **a read whose job is to discover the tenant cannot be
+bound to it.** The corollary, which is what the (c) rows are: **a write on a
+Platform-wrapped route must NAME `workspace_id`**, because the platform handle
+binds `''` and the column default is
+`COALESCE(current_setting('app.workspace_id', true), 'default')` — so an omitted
+column does not fail, it lands the row in the default workspace.
+
+| # | site | credential / lookup | route class | verdict |
+|---|---|---|---|---|
+| 1 | `auth.go:85,97` | `api_keys.key_hash` → user | any (middleware) | **(a)** `platformDB()` |
+| 2 | `auth.go:113` | `sessions.id` → user | any (middleware) | **(a)** `platformDB()` |
+| 3 | `mcp_oauth.go:86` | `users` role + workspace | `/mcp` | **(a)** `platformDB()` |
+| 4 | `mcp_oauth.go:133,141` | `oauth_access_tokens.token_hash` | `/mcp` | **(a)** `platformDB()` |
+| 5 | `mcp_oauth.go:148,151` | `api_keys.key_hash` (bearer) | `/mcp` | **(a)** `platformDB()` |
+| 6 | `mcp_oauth_authorize.go:409` | `sessions.id` → consenting user | Platform | **(a)** `h.db` **is** the platform handle inside `Platform()` |
+| 7 | `mcp_oauth_authorize.go:216,223` | `oauth_auth_codes.code_hash` | Platform | **(a)** same |
+| 8 | `mcp_oauth_authorize.go:250` | `oauth_access_tokens.refresh_hash` | Platform | **(a)** same |
+| 9 | `mcp_oauth.go:284`, `:220`, `mcp_oauth_authorize.go:344` | `oauth_clients.client_id` | Platform | **(a)** global table, no `workspace_id`, exempt from RLS by design (D2) |
+| 10 | `magic_link.go:68,100,115` | `magic_link_tokens.token_hash` | HostWorkspace | **(b)** the link was mailed from that workspace's own public host |
+| 11 | `invites.go:228,278` | `invite_tokens.token_hash` | HostWorkspace | **(b)** same |
+| 12 | `booking/service.go:386` | `booking_manage_tokens.token_hash` | HostWorkspace | **(b)** and this is how D10's "the token's booking belongs to that workspace" is enforced — by the policy, not a predicate |
+| 13 | `idempotency.go:37,51,63,73` | `idempotency_keys` PK | HostWorkspace | **(b)** PK is now `(workspace_id, key)`; two tenants may reuse a key |
+| 14 | `auth_google.go:105` | `sessions.id` (logout) | HostWorkspace | **(b)** a session of B on A's host matches nothing, which is the right answer |
+| 15 | `apikey.go`, `invites.go` admin, `mcp_oauth_admin.go` | by `user_id` / `id` | CredentialWorkspace | **(b)** bound, and that is what scopes them |
+| 16 | **`mcp_oauth_authorize.go:163`** | `INSERT oauth_auth_codes` | Platform | ⛔ **(c)** named no `workspace_id` |
+| 17 | **`mcp_oauth_authorize.go:279`** | `INSERT oauth_access_tokens` | Platform | ⛔ **(c)** named no `workspace_id` |
+| 18 | **`setup.go:75,84`** | `INSERT users` + `api_keys` | Platform | ⛔ **(c)** would seat the first owner and a live key in `default` |
+
+### (c) 16 and 17 — the OAuth grant landed in the wrong tenant
+
+⛔ **And it still worked, which is why nothing caught it.** `VerifyMCPBearer` reads
+on the platform handle, which bypasses the policies, so an agent could complete
+the Connect flow and call tools normally. What broke was **ownership**: the
+workspace's Connected-apps page (`GET /v1/oauth/connections`, a
+CredentialWorkspace route on the bound handle) could neither list nor revoke the
+grant, and deleting the workspace would not have cascaded it. A revocation UI that
+silently cannot revoke is worse than one that is absent.
+
+Fixed by naming `workspace_id`, resolved through a new
+`(*Handler).workspaceOfUser` on the platform handle.
+
+`TestSweep_oauthGrantLandsInTheOwnersWorkspace` drives the real flow — `POST
+/oauth/register`, the consent page and its CSRF cookie, the decision POST, then
+`POST /oauth/token` with PKCE S256 — and asserts the issued row's `workspace_id`
+through the platform handle, plus the observable consequence: A's Connected-apps
+page lists the grant and B's does not.
+
+### (c) 18 — `POST /v1/setup` in multi-tenant mode
+
+Platform-wrapped, and it creates the first user **plus a live API key**. Both would
+land in `default`: a working credential in a tenant nobody owns and no host
+reaches. It now 404s when `MULTI_TENANT` is set — 404 rather than 403 because on a
+multi-tenant instance the endpoint does not exist; workspaces and their owners come
+from the platform API.
+
+⚠️ **Honest scope: this is reachable only before any user exists in any
+workspace.** Setup's own "workspace already configured" guard (409) fires once
+there is one, which the negative control below shows. So it is a narrow window —
+a freshly provisioned multi-tenant database between migration and the first
+platform-API call — and defence in depth after that.
+
+### Controls
+
+Positive: all three sweep tests pass on the PostgreSQL lane.
+
+Negative, both fixes reverted:
+
+```
+--- FAIL: TestSweep_oauthGrantLandsInTheOwnersWorkspace
+    tenancy_sweep_test.go:81: no code in the redirect
+    "http://127.0.0.1:9999/cb?error=server_error&error_description=could+not+issue+code&…"
+--- FAIL: TestSweep_setupIsRefusedInMultiTenantMode
+    tenancy_sweep_test.go:149: POST /v1/setup: status = 409, want 404: {"error":"workspace already configured"}
+```
+
+⚠️ Both controls fail, but neither fails at the assertion I predicted, and that is
+worth recording rather than smoothing over. The OAuth one fails **earlier**: with
+`workspace_id` unnamed the auth-code write does not complete at all, surfacing as
+`could not issue code`. I did not have time to establish whether that is the policy
+refusing the write or an artifact of the reverted statement, so **the mechanism is
+unconfirmed** — what is confirmed is that the test distinguishes fixed from
+unfixed. The setup one fails on the status code only, because the fixture has
+users and the 409 guard fires first; it does **not** demonstrate a row being
+written, for the reason in the scope note above.
+
+### ⚠️ One assertion I had to correct, and it is a trap worth knowing
+
+The manage-page test first asserted `status != 200` for B's token on A's host. It
+failed: `ManagePage` renders **200 with `TokenInvalid: true`** for an unknown
+token, by design — it is a booker-facing page, not an API. The isolation was
+working; the assertion was wrong. It now asserts on content (none of B's booking
+id, host name or attendee address appears). A status-code assertion against a
+surface that renders its own errors proves nothing.
diff --git a/internal/handler/mcp_oauth_authorize.go b/internal/handler/mcp_oauth_authorize.go
index 8ab139f..0a94fc9 100644
--- a/internal/handler/mcp_oauth_authorize.go
+++ b/internal/handler/mcp_oauth_authorize.go
@@ -159,10 +159,19 @@ func (h *Handler) AuthorizeMCPDecision(w http.ResponseWriter, r *http.Request) {
 	code := "mcac_" + randHex(32)
 	expires := time.Now().UTC().Add(mcpAuthCodeTTL).Format(time.RFC3339)
 	now := time.Now().UTC().Format(time.RFC3339Nano)
+	// ⛔ workspace_id is NAMED because this route is Platform-wrapped: the platform
+	// handle binds '', and the column default would put the row in the DEFAULT
+	// workspace rather than the consenting user's.
+	workspaceID, wsErr := h.workspaceOfUser(r.Context(), userID)
+	if wsErr != nil {
+		h.logger.ErrorContext(r.Context(), "oauth: resolve consenting user's workspace", "error", wsErr)
+		h.redirectAuthError(w, r, ar, "server_error", "could not issue code")
+		return
+	}
 	if _, err := h.db.ExecContext(r.Context(), `
-		INSERT INTO oauth_auth_codes (code_hash, client_id, user_id, redirect_uri, code_challenge, scope, resource, expires_at, created_at)
-		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-		hashAPIKey(code), ar.ClientID, userID, ar.RedirectURI, ar.CodeChallenge, ar.Scope, ar.Resource, expires, now); err != nil {
+		INSERT INTO oauth_auth_codes (workspace_id, code_hash, client_id, user_id, redirect_uri, code_challenge, scope, resource, expires_at, created_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		workspaceID, hashAPIKey(code), ar.ClientID, userID, ar.RedirectURI, ar.CodeChallenge, ar.Scope, ar.Resource, expires, now); err != nil {
 		h.logger.ErrorContext(r.Context(), "oauth: store auth code", "error", err)
 		h.redirectAuthError(w, r, ar, "server_error", "could not issue code")
 		return
@@ -275,10 +284,21 @@ func (h *Handler) issueAndWriteTokens(w http.ResponseWriter, r *http.Request, cl
 			UPDATE oauth_access_tokens SET token_hash = ?, refresh_hash = ?, expires_at = ?, last_used_at = NULL
 			WHERE id = ?`, hashAPIKey(access), hashAPIKey(refresh), exp.Format(time.RFC3339), replaceID)
 	} else {
+		// ⛔ workspace_id NAMED, for the same reason as the auth code above: this
+		// runs on a Platform-wrapped route, so an omitted column lands the grant in
+		// the default workspace — where MCP would still verify it (the platform
+		// handle bypasses) but the owning workspace's Connected-apps page could
+		// neither list nor revoke it, and deleting the workspace would not remove it.
+		workspaceID, wsErr := h.workspaceOfUser(r.Context(), userID)
+		if wsErr != nil {
+			h.logger.ErrorContext(r.Context(), "oauth: resolve token owner's workspace", "error", wsErr)
+			writeOAuthError(w, http.StatusInternalServerError, "server_error", "could not issue token")
+			return
+		}
 		_, err = h.db.ExecContext(r.Context(), `
-			INSERT INTO oauth_access_tokens (id, token_hash, refresh_hash, client_id, user_id, scope, resource, expires_at, created_at)
-			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-			uid.New(), hashAPIKey(access), hashAPIKey(refresh), clientID, userID, scope, resource, exp.Format(time.RFC3339), now.Format(time.RFC3339Nano))
+			INSERT INTO oauth_access_tokens (workspace_id, id, token_hash, refresh_hash, client_id, user_id, scope, resource, expires_at, created_at)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			workspaceID, uid.New(), hashAPIKey(access), hashAPIKey(refresh), clientID, userID, scope, resource, exp.Format(time.RFC3339), now.Format(time.RFC3339Nano))
 	}
 	if err != nil {
 		h.logger.ErrorContext(r.Context(), "oauth: issue token", "error", err)
diff --git a/internal/handler/setup.go b/internal/handler/setup.go
index ba99c9d..c545316 100644
--- a/internal/handler/setup.go
+++ b/internal/handler/setup.go
@@ -14,6 +14,20 @@ import (
 // Setup handles POST /v1/setup — creates the first user and API key.
 // Returns 409 if the workspace is already configured.
 func (h *Handler) Setup(w http.ResponseWriter, r *http.Request) {
+	// ⛔ Refused in multi-tenant mode. This route is Platform-wrapped (it runs
+	// before any workspace exists, on the identity host), so its INSERTs into
+	// users and api_keys would land in the DEFAULT workspace — a first user and a
+	// live API key in a tenant nobody owns, reachable by no host. Workspaces and
+	// their owners are provisioned through the platform API instead.
+	//
+	// 404 rather than 403: on a multi-tenant instance this endpoint does not
+	// exist, and saying so is better than describing a bootstrap the caller
+	// cannot perform.
+	if h.multiTenant {
+		http.NotFound(w, r)
+		return
+	}
+
 	r.Body = http.MaxBytesReader(w, r.Body, 32<<10)
 	var req struct {
 		Name     string `json:"name"`
diff --git a/internal/handler/workspace.go b/internal/handler/workspace.go
index 4681f52..c6bc151 100644
--- a/internal/handler/workspace.go
+++ b/internal/handler/workspace.go
@@ -287,6 +287,27 @@ func (h *Handler) workspaceByHost(ctx context.Context, requestHost string) (*Wor
 	return &ws, nil
 }
 
+// workspaceOfUser resolves the workspace a user belongs to, through the platform
+// handle.
+//
+// ⛔ It exists for the INSERTs on Platform-wrapped routes. The platform handle
+// binds ”, and the workspace_id column defaults to
+// COALESCE(current_setting('app.workspace_id', true), 'default') — so a write that
+// omits the column lands in the DEFAULT workspace, silently, rather than failing.
+// A Platform route that writes a tenant row therefore has to name workspace_id,
+// and this is where it comes from.
+func (h *Handler) workspaceOfUser(ctx context.Context, userID string) (string, error) {
+	if !h.multiTenant {
+		return db.DefaultWorkspaceID, nil
+	}
+	var ws string
+	if err := h.platformDB().QueryRowContext(ctx,
+		`SELECT workspace_id FROM users WHERE id = ?`, userID).Scan(&ws); err != nil {
+		return "", fmt.Errorf("resolve the workspace of user %s: %w", userID, err)
+	}
+	return ws, nil
+}
+
 // workspaceByID reads a workspace by id, through the platform handle.
 func (h *Handler) workspaceByID(ctx context.Context, id string) (*Workspace, error) {
 	var ws Workspace
diff --git a/internal/server/tenancy_e2e_test.go b/internal/server/tenancy_e2e_test.go
index 1dc457e..d6be4d6 100644
--- a/internal/server/tenancy_e2e_test.go
+++ b/internal/server/tenancy_e2e_test.go
@@ -6,9 +6,11 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
+	"io"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"strings"
 	"testing"
 	"time"
@@ -167,6 +169,30 @@ func seedTenant(t *testing.T, app, platform *db.DB, id, host string) tenant {
 	return tn
 }
 
+// newRequest builds a request bound to a host, for the cases that need to add
+// cookies or headers before it is served.
+func newRequest(t *testing.T, method, host, path string, body io.Reader) *http.Request {
+	t.Helper()
+	r := httptest.NewRequest(method, path, body)
+	r.Host = host
+	return r
+}
+
+// serve runs a prepared request through the real mux.
+func (f *tenancyFixture) serve(r *http.Request) *httptest.ResponseRecorder {
+	rec := httptest.NewRecorder()
+	f.mux.ServeHTTP(rec, r)
+	return rec
+}
+
+// postForm sends a urlencoded form through the real mux.
+func (f *tenancyFixture) postForm(t *testing.T, host, path string, form url.Values) *httptest.ResponseRecorder {
+	t.Helper()
+	r := newRequest(t, http.MethodPost, host, path, strings.NewReader(form.Encode()))
+	r.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	return f.serve(r)
+}
+
 // do sends a request through the real mux.
 func (f *tenancyFixture) do(t *testing.T, method, host, path, apiKey, body string) *httptest.ResponseRecorder {
 	t.Helper()
diff --git a/internal/server/tenancy_sweep_test.go b/internal/server/tenancy_sweep_test.go
new file mode 100644
index 0000000..d65dd37
--- /dev/null
+++ b/internal/server/tenancy_sweep_test.go
@@ -0,0 +1,317 @@
+package server_test
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// The sweep's two (c) findings, each with the test that would have caught it.
+//
+// Both are the same shape: a Platform-wrapped route writing a TENANT row. The
+// platform handle binds '', and workspace_id defaults to
+// COALESCE(current_setting('app.workspace_id', true), 'default') — so an omitted
+// column does not fail, it lands the row in the default workspace. Nothing errors.
+// The row is simply in a tenant nobody owns and no host reaches.
+
+// TestSweep_oauthGrantLandsInTheOwnersWorkspace drives the real OAuth 2.1 flow
+// that the MCP "Connect" button uses — register a client, consent, exchange the
+// code — and asserts the resulting grant belongs to the consenting user's
+// workspace rather than to 'default'.
+//
+// ⛔ Before the fix the token still WORKED: VerifyMCPBearer reads on the platform
+// handle, which bypasses the policies, so an agent could connect and call tools.
+// What broke was ownership — the workspace's Connected-apps page could neither
+// list nor revoke the grant, and deleting the workspace would have left it behind.
+// That is why the assertion is on the row's workspace_id and on the page, not on
+// whether the token authenticates.
+func TestSweep_oauthGrantLandsInTheOwnersWorkspace(t *testing.T) {
+	f := newTenancyFixture(t)
+	ctx := context.Background()
+
+	// A browser session for A's owner, so /oauth/authorize finds a signed-in user
+	// instead of bouncing through the login flow. sessions.id is globally unique
+	// (D9) precisely so a cookie resolves before a tenant is known.
+	const sessionID = "sess-acme-oauth"
+	if _, err := f.app.ForWorkspace(f.a.id).ExecContext(ctx,
+		`INSERT INTO sessions (id, user_id, expires_at) VALUES (?, ?, ?)`,
+		sessionID, f.a.userID, "2099-01-01T00:00:00Z"); err != nil {
+		t.Fatalf("seed session: %v", err)
+	}
+
+	// 1. Dynamic client registration (RFC 7591). oauth_clients is a global table:
+	//    a connector registration is per client APPLICATION, not per tenant.
+	reg := f.do(t, http.MethodPost, "app.calnode.example", "/oauth/register", "",
+		`{"client_name":"sweep-test","redirect_uris":["http://127.0.0.1:9999/cb"]}`)
+	if reg.Code != http.StatusCreated && reg.Code != http.StatusOK {
+		t.Fatalf("register client: status = %d: %s", reg.Code, reg.Body.String())
+	}
+	var client struct {
+		ClientID string `json:"client_id"`
+	}
+	if err := json.Unmarshal(reg.Body.Bytes(), &client); err != nil {
+		t.Fatalf("decode registration %q: %v", reg.Body.String(), err)
+	}
+	if client.ClientID == "" {
+		t.Fatalf("no client_id in %s", reg.Body.String())
+	}
+
+	// 2. PKCE S256.
+	const verifier = "sweep-test-verifier-0123456789abcdefghijklmnop"
+	sum := sha256.Sum256([]byte(verifier))
+	challenge := base64.RawURLEncoding.EncodeToString(sum[:])
+
+	// 3. Consent. The decision POST is what writes oauth_auth_codes.
+	form := url.Values{
+		"client_id":             {client.ClientID},
+		"redirect_uri":          {"http://127.0.0.1:9999/cb"},
+		"code_challenge":        {challenge},
+		"code_challenge_method": {"S256"},
+		"response_type":         {"code"},
+		"state":                 {"xyz"},
+		"decision":              {"allow"},
+	}
+	code := f.oauthConsent(t, sessionID, form)
+
+	// 4. Token exchange. This is what writes oauth_access_tokens.
+	tokenForm := url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {code},
+		"redirect_uri":  {"http://127.0.0.1:9999/cb"},
+		"client_id":     {client.ClientID},
+		"code_verifier": {verifier},
+	}
+	tok := f.postForm(t, "app.calnode.example", "/oauth/token", tokenForm)
+	if tok.Code != http.StatusOK {
+		t.Fatalf("token exchange: status = %d: %s", tok.Code, tok.Body.String())
+	}
+
+	// The assertion. Read through the PLATFORM handle, which sees every workspace,
+	// so this is about where the row IS rather than what A can see.
+	var codeWS, tokenWS string
+	if err := f.plat.QueryRowContext(ctx,
+		`SELECT workspace_id FROM oauth_auth_codes WHERE user_id = ?`, f.a.userID).Scan(&codeWS); err != nil {
+		// The code is deleted on exchange (single use), so absence is expected;
+		// only a row in the wrong workspace is a failure.
+		codeWS = f.a.id
+	}
+	if codeWS != f.a.id {
+		t.Errorf("the authorization code landed in workspace %q; want %q", codeWS, f.a.id)
+	}
+	if err := f.plat.QueryRowContext(ctx,
+		`SELECT workspace_id FROM oauth_access_tokens WHERE user_id = ?`, f.a.userID).Scan(&tokenWS); err != nil {
+		t.Fatalf("read the issued token: %v", err)
+	}
+	if tokenWS != f.a.id {
+		t.Errorf("the access token landed in workspace %q; want %q", tokenWS, f.a.id)
+	}
+	if tokenWS == db.DefaultWorkspaceID {
+		t.Error("the grant landed in the default workspace — a Platform route wrote a tenant row without naming workspace_id")
+	}
+
+	// The observable consequence, which is what a user would report: the grant has
+	// to be listed on the workspace's Connected-apps page, which is a
+	// credential-scoped route running on the BOUND handle.
+	list := f.do(t, http.MethodGet, f.a.host, "/v1/oauth/connections", f.a.apiKey, "")
+	if list.Code != http.StatusOK {
+		t.Fatalf("list connections: status = %d: %s", list.Code, list.Body.String())
+	}
+	if !strings.Contains(list.Body.String(), "sweep-test") {
+		t.Errorf("A's Connected-apps page does not list the grant it just authorised: %s", list.Body.String())
+	}
+	// And B cannot see it.
+	other := f.do(t, http.MethodGet, f.b.host, "/v1/oauth/connections", f.b.apiKey, "")
+	if strings.Contains(other.Body.String(), "sweep-test") {
+		t.Errorf("B's Connected-apps page lists A's grant: %s", other.Body.String())
+	}
+}
+
+// TestSweep_setupIsRefusedInMultiTenantMode. POST /v1/setup is Platform-wrapped
+// and creates the first user plus a live API key. Unrefused, both land in the
+// default workspace: a working credential in a tenant nobody owns and no host
+// reaches. Workspaces and their owners are provisioned through the platform API.
+func TestSweep_setupIsRefusedInMultiTenantMode(t *testing.T) {
+	f := newTenancyFixture(t)
+	ctx := context.Background()
+
+	before := f.countIn(t, "users", db.DefaultWorkspaceID)
+
+	rec := f.do(t, http.MethodPost, "app.calnode.example", "/v1/setup", "",
+		`{"name":"Squatter","email":"squatter@example.com","timezone":"UTC"}`)
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("POST /v1/setup: status = %d, want 404: %s", rec.Code, rec.Body.String())
+	}
+
+	if after := f.countIn(t, "users", db.DefaultWorkspaceID); after != before {
+		t.Errorf("users in the default workspace went from %d to %d — setup wrote a row", before, after)
+	}
+	var keys int
+	if err := f.plat.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM api_keys WHERE workspace_id = ?`, db.DefaultWorkspaceID).Scan(&keys); err != nil {
+		t.Fatalf("count default-workspace api keys: %v", err)
+	}
+	if keys != 0 {
+		t.Errorf("%d API keys exist in the default workspace", keys)
+	}
+}
+
+// TestSweep_tenantLocalTokensDoNotResolveAcrossHosts is the (b) half of the
+// table: magic links, invites and manage tokens are read on the BOUND handle,
+// because the route that reads them is host-scoped and the email that carried
+// them was sent from that workspace's own public host. The test is that a token
+// of B presented on A's host resolves to nothing.
+func TestSweep_tenantLocalTokensDoNotResolveAcrossHosts(t *testing.T) {
+	f := newTenancyFixture(t)
+	ctx := context.Background()
+
+	hB := f.app.ForWorkspace(f.b.id)
+
+	// A magic-link token for B's user. token_hash is globally unique, so nothing
+	// but the binding stops A's host from finding it.
+	const magic = "magic-for-globex"
+	sum := sha256.Sum256([]byte(magic))
+	hash := encodeHex(sum[:])
+	if _, err := hB.ExecContext(ctx,
+		`INSERT INTO magic_link_tokens (token_hash, user_id, expires_at) VALUES (?, ?, ?)`,
+		hash, f.b.userID, "2099-01-01T00:00:00Z"); err != nil {
+		t.Fatalf("seed magic link: %v", err)
+	}
+
+	// On B's own host it is a valid login.
+	own := f.do(t, http.MethodGet, f.b.host, "/v1/auth/magic-link/verify?token="+magic, "", "")
+	if own.Code >= 400 {
+		t.Fatalf("B's magic link on B's host: status = %d: %s", own.Code, own.Body.String())
+	}
+
+	// A second token, because the first is single-use.
+	const magic2 = "magic-for-globex-2"
+	sum2 := sha256.Sum256([]byte(magic2))
+	if _, err := hB.ExecContext(ctx,
+		`INSERT INTO magic_link_tokens (token_hash, user_id, expires_at) VALUES (?, ?, ?)`,
+		encodeHex(sum2[:]), f.b.userID, "2099-01-01T00:00:00Z"); err != nil {
+		t.Fatalf("seed second magic link: %v", err)
+	}
+	// On A's host it resolves to nothing, and must not mint a session.
+	other := f.do(t, http.MethodGet, f.a.host, "/v1/auth/magic-link/verify?token="+magic2, "", "")
+	for _, c := range other.Result().Cookies() {
+		if c.Name == "calnode_session" && c.Value != "" {
+			t.Fatalf("B's magic link minted a session on A's host")
+		}
+	}
+
+	// A manage token for B's booking. The manage page is host-scoped, and D10 asks
+	// that the token's booking belong to the request's workspace — which the policy
+	// enforces without the handler carrying a predicate.
+	const manage = "manage-for-globex"
+	msum := sha256.Sum256([]byte(manage))
+	if _, err := hB.ExecContext(ctx,
+		`INSERT INTO booking_manage_tokens (token_hash, booking_id, expires_at) VALUES (?, ?, ?)`,
+		encodeHex(msum[:]), f.b.bookingID, "2099-01-01T00:00:00Z"); err != nil {
+		t.Fatalf("seed manage token: %v", err)
+	}
+	// ⚠️ The manage page answers 200 for an unknown token BY DESIGN — it is a
+	// booker-facing page that renders "this link is no longer valid", not an API.
+	// So the assertion is on the content: none of B's booking must appear.
+	onA := f.do(t, http.MethodGet, f.a.host, "/manage/"+manage, "", "")
+	for _, leak := range []string{f.b.bookingID, "GLOBEX", "booker-globex@example.com"} {
+		if strings.Contains(onA.Body.String(), leak) {
+			t.Errorf("B's manage token leaked %q on A's host", leak)
+		}
+	}
+	onB := f.do(t, http.MethodGet, f.b.host, "/manage/"+manage, "", "")
+	if onB.Code != http.StatusOK {
+		t.Errorf("B's manage token on B's own host: status = %d", onB.Code)
+	}
+}
+
+// oauthConsent posts the consent decision with the session cookie and the CSRF
+// token the consent page hands out, and returns the authorization code.
+func (f *tenancyFixture) oauthConsent(t *testing.T, sessionID string, form url.Values) string {
+	t.Helper()
+
+	// GET first: the consent page sets the CSRF cookie the POST has to echo.
+	get := "/oauth/authorize?" + url.Values{
+		"client_id":             form["client_id"],
+		"redirect_uri":          form["redirect_uri"],
+		"code_challenge":        form["code_challenge"],
+		"code_challenge_method": form["code_challenge_method"],
+		"response_type":         form["response_type"],
+		"state":                 form["state"],
+	}.Encode()
+
+	r := newRequest(t, http.MethodGet, "app.calnode.example", get, nil)
+	r.AddCookie(&http.Cookie{Name: "calnode_session", Value: sessionID})
+	page := f.serve(r)
+	if page.Code != http.StatusOK {
+		t.Fatalf("consent page: status = %d: %s", page.Code, firstLine(page.Body.String()))
+	}
+	var csrf string
+	for _, c := range page.Result().Cookies() {
+		if strings.Contains(c.Name, "csrf") {
+			csrf = c.Value
+		}
+	}
+	if csrf != "" {
+		form.Set("csrf", csrf)
+		form.Set("csrf_token", csrf)
+	}
+
+	post := newRequest(t, http.MethodPost, "app.calnode.example", "/oauth/authorize",
+		strings.NewReader(form.Encode()))
+	post.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	post.AddCookie(&http.Cookie{Name: "calnode_session", Value: sessionID})
+	if csrf != "" {
+		post.AddCookie(&http.Cookie{Name: "calnode_oauth_csrf", Value: csrf})
+	}
+	res := f.serve(post)
+	if res.Code != http.StatusFound && res.Code != http.StatusSeeOther {
+		t.Fatalf("consent decision: status = %d: %s", res.Code, firstLine(res.Body.String()))
+	}
+	loc, err := url.Parse(res.Header().Get("Location"))
+	if err != nil {
+		t.Fatalf("parse redirect %q: %v", res.Header().Get("Location"), err)
+	}
+	code := loc.Query().Get("code")
+	if code == "" {
+		t.Fatalf("no code in the redirect %q", res.Header().Get("Location"))
+	}
+	return code
+}
+
+func (f *tenancyFixture) countIn(t *testing.T, table, workspace string) int {
+	t.Helper()
+	var n int
+	// The table name is a literal from this file, never input.
+	if err := f.plat.QueryRowContext(context.Background(),
+		`SELECT COUNT(*) FROM `+table+` WHERE workspace_id = ?`, workspace).Scan(&n); err != nil {
+		t.Fatalf("count %s in %s: %v", table, workspace, err)
+	}
+	return n
+}
+
+func encodeHex(b []byte) string {
+	const hexDigits = "0123456789abcdef"
+	out := make([]byte, len(b)*2)
+	for i, c := range b {
+		out[i*2] = hexDigits[c>>4]
+		out[i*2+1] = hexDigits[c&0x0f]
+	}
+	return string(out)
+}
+
+func firstLine(s string) string {
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		return s[:i]
+	}
+	if len(s) > 200 {
+		return s[:200]
+	}
+	return s
+}

From d0d5860b9f384db610a9be4a34f7655f0b0bae93 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 02:34:55 -0400
Subject: [PATCH 32/51] handler: one hot client per workspace, not one per
 process
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boundary 4. The five Set/get singleton pairs on shared — mailer, LLM, Zoom,
Stripe, LiveKit — each behind its own RWMutex, become five tenantCache[T]. Every
value is built lazily from THAT workspace's server_settings row through the bound
handle. The settings-save handlers needed no edit: they already call SetX after
writing, and SetX now writes at h.cacheKey(), so a save on a credential-scoped
handler primes its own key and nobody else's.

Three deliberate things in the cache. The key is "" in single-tenant mode rather
than "default", so the map cannot grow past one entry and nothing that calls
ForWorkspace can make it. present is tracked separately from entries because nil
is a meaningful value — a workspace with no Stripe credentials caches a nil
client, and conflating nil with absent would rebuild it on every request. And the
builder runs outside the lock, because every builder reads server_settings and
holding the write lock across a round trip would serialise every tenant behind the
slowest; the first store wins, so 32 concurrent gets ran 1 builder and returned one
value.

mailer.From() is new on *SMTP, *Resend and *Live. The sender address is the only
per-workspace value a built mailer exposes, so without it the test could only
assert two mailers are different pointers, which a shared cache also satisfies.

The negative control is in the tree rather than run by hand: the same two mailers
built under the real keys and under a key stubbed to "", with both halves
asserted. It logs the bug in one line — with the key stubbed, B would send as
bookings@acme.example instead of hello@globex.example.

A single handle cannot tell two workspaces apart: db.ForWorkspace is the identity
function on a handle that did not come from OpenPair, so the first draft of these
tests compared a value with itself and failed as "mailer *mailer.Noop exposes no
From address" — which reads like a builder bug rather than a harness one. The four
workspace-distinguishing cases now take a real pair and skip loudly on SQLite.

One documented gap: getCal is unchanged. The calendar Service is a registry of
providers keyed by the instance's OAuth app, which D7 keeps platform-level, and
all three providers capture a *db.DB at construction — so making it per-tenant
needs a ForDB on the Service and each provider plus config plumbing. Today the
captured handle is the unbound one, which matches no row, so on a multi-tenant
instance calendar sync is inert rather than cross-tenant. Safe, but not working;
it belongs with B5, which touches the reconciler anyway. PROGRESS.md says so.

gofmt -l empty, go vet clean, all seven cases pass under -race.
---
 PROGRESS.md                          |  92 ++++++++
 internal/handler/booking_handler.go  |   8 +-
 internal/handler/email_settings.go   |   2 +-
 internal/handler/handler.go          | 135 ++++++++---
 internal/handler/invites.go          |   2 +-
 internal/handler/magic_link.go       |   4 +-
 internal/handler/manage_handler.go   |   4 +-
 internal/handler/reassign.go         |   4 +-
 internal/handler/shared.go           |  31 +--
 internal/handler/tenantcache.go      |  93 ++++++++
 internal/handler/tenantcache_test.go | 335 +++++++++++++++++++++++++++
 internal/handler/test_email.go       |   2 +-
 internal/mailer/live.go              |  12 +
 internal/mailer/resend.go            |   3 +
 internal/mailer/smtp.go              |   7 +
 15 files changed, 673 insertions(+), 61 deletions(-)
 create mode 100644 internal/handler/tenantcache.go
 create mode 100644 internal/handler/tenantcache_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 28515ec..3ecab24 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1052,3 +1052,95 @@ token, by design — it is a booker-facing page, not an API. The isolation was
 working; the assertion was wrong. It now asserts on content (none of B's booking
 id, host name or attendee address appears). A status-code assertion against a
 surface that renders its own errors proves nothing.
+
+## Boundary 4 — per-tenant runtime state — DONE (with one documented gap)
+
+Five Set/get singleton pairs on `shared`, each behind its own `sync.RWMutex`,
+became five `*tenantCache[T]`: **mailer, LLM, Zoom, Stripe, LiveKit**. Each value
+is built lazily from **that workspace's** `server_settings` row through the
+**bound** handle, and replaced when that workspace saves. The settings-save
+handlers needed **no edit**: they already call `SetX(...)` after writing, and
+`SetX` now writes at `h.cacheKey()`, so a save on a credential-scoped handler
+primes its own key and nobody else's.
+
+`internal/handler/tenantcache.go` is 90 lines and generic. Three things in it are
+deliberate:
+
+- **The key is `""` in single-tenant mode, not `"default"`.** One entry, built on
+  first ask, replaced by `SetX` exactly as before — so the map cannot grow past
+  one and nothing that calls `ForWorkspace` can make it.
+- **`present` is separate from `entries`, because nil is a MEANINGFUL value.** A
+  workspace with no Stripe credentials caches a nil `*stripe.Client`; if absence
+  and nil were the same thing, every request would rebuild it. A test pins that a
+  read after `SetStripe(nil)` does not grow the cache.
+- **The builder runs OUTSIDE the lock**, because every builder reads
+  `server_settings` — holding the write lock across a round trip would serialise
+  every tenant behind the slowest. The cost is that two concurrent
+  first-requests may both build; the first store wins and the loser is discarded.
+  Clients are stateless value wrappers, so that is waste, not incorrectness, and
+  `TestTenantCache_getBuildsOnceUnderContention` asserts all 32 callers get **one
+  value** (measured: 32 gets, 1 builder).
+
+### `mailer.From()` is new, and it is what makes the assertion possible
+
+The sender address is the only per-workspace value a built mailer exposes from
+outside, so `*SMTP`, `*Resend` and `*Live` (delegating) gained a `From()`.
+Without it the test could only assert that two mailers are different pointers,
+which a shared cache would also satisfy.
+
+### The negative control lives in the tree
+
+`TestTenantCache_keyIsWhatSeparatesThem` builds the same two mailers twice: once
+under the real keys, once under a key stubbed to `""`. Both halves are asserted,
+so the test fails if the real keys collide **and** if the stubbed key does not:
+
+```
+tenantcache_test.go:143: key stubbed to "": B would send as "bookings@acme.example" instead of "hello@globex.example"
+```
+
+That is the bug in one line — B's booking confirmations going out as A.
+
+### ⛔ A single handle cannot tell two workspaces apart, and the first draft of these tests did not
+
+`db.ForWorkspace` is the **identity function** on a handle that did not come from
+`OpenPair`, so every "scoped" copy read the same rows and the first version of
+this file compared a value with itself — it failed as
+`mailer *mailer.Noop exposes no From address`, which reads like a builder bug
+rather than a harness one. The four workspace-distinguishing cases now take a real
+pair through `dbtest.RequireTenantPair` and skip loudly on SQLite; the two
+pure-cache cases (`singleTenantKeepsOneEntry`, `getBuildsOnceUnderContention`) do
+not need one and run on both lanes.
+
+### ⚠️ The gap: the calendar Service is still a process-wide singleton
+
+`getCal` is unchanged. This is a scope decision, stated rather than hidden:
+
+- The `calendar.Service` is a registry of **providers** keyed by the instance's
+  Google/Microsoft OAuth **app** credentials, and D7 keeps `googleAuth` /
+  `microsoftAuth` platform-level. So the thing being cached is not obviously
+  per-tenant in the way an SMTP transport is.
+- Each provider (`gcal.New`, `microsoft.New`, `caldav.New`) **captures a `*db.DB`
+  at construction**. Making the Service per-tenant needs a `ForDB` on the Service
+  and on all three providers, plus the config plumbing to rebuild them per
+  workspace — more than this boundary.
+- **What that means today, measured against the design rather than guessed:** on a
+  multi-tenant instance the captured handle is the **unbound** application handle,
+  which under the policies matches no row. So calendar reads return nothing and
+  the integration is **inert**, not cross-tenant. That is the safe failure, but it
+  is a failure: a multi-tenant deployment has no working calendar sync until this
+  is finished. It belongs with B5, which touches the reconciler anyway.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+All seven cases pass **under `-race`** on the PostgreSQL lane:
+
+```
+--- PASS: TestTenantCache_mailerIsPerWorkspace (1.11s)
+--- PASS: TestTenantCache_keyIsWhatSeparatesThem (1.14s)
+--- PASS: TestTenantCache_saveInvalidatesOnlyThatWorkspace (1.14s)
+--- PASS: TestTenantCache_singleTenantKeepsOneEntry (0.78s)
+--- PASS: TestTenantCache_concurrentWorkspaces (1.33s)
+--- PASS: TestTenantCache_getBuildsOnceUnderContention (0.00s)
+--- PASS: TestTenantCache_llmAndStripeBuildFromTheirOwnRow (1.11s)
+```
diff --git a/internal/handler/booking_handler.go b/internal/handler/booking_handler.go
index 2f558d3..7afdafd 100644
--- a/internal/handler/booking_handler.go
+++ b/internal/handler/booking_handler.go
@@ -1097,7 +1097,7 @@ func (h *Handler) createHostEventsAndNotify(ctx context.Context, b *booking.Book
 			if livekitHostURL != "" {
 				hd.LocationValue = livekitHostURL // host email gets the controls-enabled link
 			}
-			if err := mailer.SendConfirmationToHost(ctx, h.mailer, hd); err != nil {
+			if err := mailer.SendConfirmationToHost(ctx, h.getMailer(), hd); err != nil {
 				h.logger.Error("booking confirmation email (host)", "error", err, "booking_id", b.ID, "host", host.UserID)
 			}
 		}
@@ -1162,7 +1162,7 @@ func (h *Handler) dispatchBookingConfirmation(b *booking.Booking, in bookingConf
 	bData.AttachICS = h.noConnectedDestination(ctx, b.HostID)
 	bData.ICSSequence = int(b.UpdatedAt.Unix())
 	if primaryPrefs.NotifyConfirmation {
-		if err := mailer.SendConfirmationToAttendee(ctx, h.mailer, bData); err != nil {
+		if err := mailer.SendConfirmationToAttendee(ctx, h.getMailer(), bData); err != nil {
 			h.logger.Error("booking confirmation email (attendee)", "error", err, "booking_id", b.ID)
 		}
 	}
@@ -1575,7 +1575,7 @@ func (h *Handler) cancelSideEffects(b booking.Booking) {
 		}
 		if prefs.NotifyHostCancel {
 			hd := h.hostBookingData(ctx, d, host, b.UpdatedAt)
-			if err := mailer.SendCancellationToHost(ctx, h.mailer, hd); err != nil {
+			if err := mailer.SendCancellationToHost(ctx, h.getMailer(), hd); err != nil {
 				h.logger.Error("booking cancellation email (host)", "error", err, "booking_id", b.ID, "host", host.UserID)
 			}
 		}
@@ -1583,7 +1583,7 @@ func (h *Handler) cancelSideEffects(b booking.Booking) {
 	d.AttachICS = h.noConnectedDestination(ctx, b.HostID)
 	d.ICSSequence = int(b.UpdatedAt.Unix())
 	if primaryPrefs.NotifyCancellation {
-		if err := mailer.SendCancellationToAttendee(ctx, h.mailer, d); err != nil {
+		if err := mailer.SendCancellationToAttendee(ctx, h.getMailer(), d); err != nil {
 			h.logger.Error("booking cancellation email (attendee)", "error", err, "booking_id", b.ID)
 		}
 	}
diff --git a/internal/handler/email_settings.go b/internal/handler/email_settings.go
index 7dbf9b5..df6ec28 100644
--- a/internal/handler/email_settings.go
+++ b/internal/handler/email_settings.go
@@ -396,7 +396,7 @@ func (h *Handler) TestEmailConnection(w http.ResponseWriter, r *http.Request) {
 		_, transport = BuildMailer(*cfg)
 	}
 
-	if err := h.mailer.Send(ctx, mailer.Message{
+	if err := h.getMailer().Send(ctx, mailer.Message{
 		To:      []string{user.Email},
 		Subject: "[TEST] Calnode email configuration",
 		Text:    "This is a test email from Calnode. If you received this, your email settings are working correctly.",
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index c95198d..a894607 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -46,9 +46,7 @@ type Handler struct {
 // SetLiveKit swaps the active LiveKit client (nil disables built-in video rooms).
 // Hot-reloadable from the LiveKit settings page.
 func (h *Handler) SetLiveKit(c *livekit.Client) {
-	h.livekitMu.Lock()
-	h.livekit = c
-	h.livekitMu.Unlock()
+	h.livekitCache.set(h.cacheKey(), c)
 	// Self-heal: any recording still 'active' is an orphan from before this restart (its egress
 	// is no longer tracked), and would otherwise block the idempotent guard on its room forever.
 	if c != nil {
@@ -60,66 +58,132 @@ func (h *Handler) SetLiveKit(c *livekit.Client) {
 	}
 }
 
-// getLiveKit returns the active LiveKit client, or nil when video is unconfigured.
+// getLiveKit returns this workspace's LiveKit client, or nil when video is
+// unconfigured for it. Built lazily from the workspace's own settings row.
 func (h *Handler) getLiveKit() *livekit.Client {
-	h.livekitMu.RLock()
-	defer h.livekitMu.RUnlock()
-	return h.livekit
+	return h.livekitCache.get(h.cacheKey(), func() *livekit.Client {
+		cfg, err := LoadLiveKitSettingsFromDB(h.db, h.encKey)
+		if err != nil {
+			h.logger.Warn("livekit: could not load settings", "workspace", h.cacheKey(), "error", err)
+			return nil
+		}
+		if cfg == nil {
+			return nil
+		}
+		return livekit.New(cfg.URL, cfg.APIKey, cfg.APISecret, h.encKey)
+	})
 }
 
 // SetStripe swaps the active Stripe client (nil disables paid bookings). Hot-reloadable
 // from the Payments settings page.
 func (h *Handler) SetStripe(c *stripe.Client) {
-	h.stripeMu.Lock()
-	h.stripe = c
-	h.stripeMu.Unlock()
+	h.stripeCache.set(h.cacheKey(), c)
 }
 
-// getStripe returns the active Stripe client, or nil when payments are unconfigured.
+// getStripe returns this workspace's Stripe client, or nil when payments are
+// unconfigured for it.
 func (h *Handler) getStripe() *stripe.Client {
-	h.stripeMu.RLock()
-	defer h.stripeMu.RUnlock()
-	return h.stripe
+	return h.stripeCache.get(h.cacheKey(), func() *stripe.Client {
+		cfg, err := LoadStripeSettingsFromDB(h.db, h.encKey)
+		if err != nil {
+			h.logger.Warn("stripe: could not load settings", "workspace", h.cacheKey(), "error", err)
+			return nil
+		}
+		if cfg == nil {
+			return nil
+		}
+		sc, err := stripe.New(cfg.SecretKey, cfg.PublishableKey, cfg.WebhookSecret)
+		if err != nil {
+			h.logger.Warn("stripe: init failed", "workspace", h.cacheKey(), "error", err)
+			return nil
+		}
+		return sc
+	})
 }
 
 // SetZoom swaps the active Zoom client (nil disables Zoom auto-minting). Hot-reloadable
 // from the Zoom settings page.
 func (h *Handler) SetZoom(c *zoom.Client) {
-	h.zoomMu.Lock()
-	h.zoom = c
-	h.zoomMu.Unlock()
+	h.zoomCache.set(h.cacheKey(), c)
 }
 
-// getZoom returns the active Zoom client, or nil when no Zoom app is configured.
+// getZoom returns this workspace's Zoom client, or nil when it has no Zoom app.
+//
+// zoom.New captures the handle it is given, so it gets h.db — the BOUND one —
+// and the per-host tokens it later reads are this workspace's.
 func (h *Handler) getZoom() *zoom.Client {
-	h.zoomMu.RLock()
-	defer h.zoomMu.RUnlock()
-	return h.zoom
+	return h.zoomCache.get(h.cacheKey(), func() *zoom.Client {
+		cfg, err := LoadZoomSettingsFromDB(h.db, h.encKey)
+		if err != nil {
+			h.logger.Warn("zoom: could not load settings", "workspace", h.cacheKey(), "error", err)
+			return nil
+		}
+		if cfg == nil || cfg.ClientID == "" || cfg.ClientSecret == "" {
+			return nil
+		}
+		zc, err := zoom.New(h.db, cfg.ClientID, cfg.ClientSecret, h.baseURL+"/v1/zoom/callback", hex.EncodeToString(h.encKey[:]))
+		if err != nil {
+			h.logger.Warn("zoom: init failed", "workspace", h.cacheKey(), "error", err)
+			return nil
+		}
+		return zc
+	})
 }
 
 // SetLLM swaps the active LLM client (nil disables AI features). Hot-reloadable from
 // the settings page.
 func (h *Handler) SetLLM(c *llm.Client) {
-	h.llmMu.Lock()
-	h.llm = c
-	h.llmMu.Unlock()
+	h.llmCache.set(h.cacheKey(), c)
 }
 
-// getLLM returns the active LLM client, or nil when AI is off — callers MUST nil-check
-// and fall back to the deterministic path.
+// getLLM returns this workspace's LLM client, or nil when AI is off for it —
+// callers MUST nil-check and fall back to the deterministic path.
 func (h *Handler) getLLM() *llm.Client {
-	h.llmMu.RLock()
-	defer h.llmMu.RUnlock()
-	return h.llm
+	return h.llmCache.get(h.cacheKey(), func() *llm.Client {
+		cfg, err := LoadLLMSettingsFromDB(h.db, h.encKey)
+		if err != nil {
+			h.logger.Warn("llm: could not load settings", "workspace", h.cacheKey(), "error", err)
+			return nil
+		}
+		if cfg == nil || !cfg.Enabled || cfg.Endpoint == "" {
+			return nil
+		}
+		return llm.New(llm.Config{Endpoint: cfg.Endpoint, Model: cfg.Model, APIKey: cfg.APIKey})
+	})
+}
+
+// getMailer returns this workspace's mailer.
+//
+// In single-tenant mode the entry is the process-wide *mailer.Live that boot
+// installed, so nothing changes. In multi-tenant mode each workspace's transport
+// is chosen by BuildMailer from its OWN settings row — which is what keeps one
+// tenant's SMTP credentials and From address out of another's email.
+func (h *Handler) getMailer() mailer.Mailer {
+	return h.mailerCache.get(h.cacheKey(), func() mailer.Mailer {
+		cfg, err := LoadEmailSettingsFromDB(h.db, h.encKey)
+		if err != nil {
+			h.logger.Warn("mailer: could not load settings", "workspace", h.cacheKey(), "error", err)
+			return &mailer.Noop{}
+		}
+		if cfg == nil {
+			return &mailer.Noop{}
+		}
+		m, _ := BuildMailer(*cfg)
+		return m
+	})
 }
 
 func New(database *db.DB, logger *slog.Logger) *Handler {
 	whs, _ := webhook.New(database, "") // ephemeral key when no encryption key configured
 	return &Handler{
 		shared: &shared{
-			logger:   logger,
-			mailer:   &mailer.Noop{},
-			calNudge: make(chan struct{}, 1),
+			logger:       logger,
+			calNudge:     make(chan struct{}, 1),
+			mailerCache:  newTenantCache[mailer.Mailer](),
+			llmCache:     newTenantCache[*llm.Client](),
+			zoomCache:    newTenantCache[*zoom.Client](),
+			stripeCache:  newTenantCache[*stripe.Client](),
+			livekitCache: newTenantCache[*livekit.Client](),
 		},
 		db:         database,
 		ws:         DefaultWorkspace,
@@ -131,7 +195,7 @@ func New(database *db.DB, logger *slog.Logger) *Handler {
 // SetMailer configures the email sender and the base URL used in email links.
 // If m is a *mailer.Live, it is also stored as h.live for hot-swap support.
 func (h *Handler) SetMailer(m mailer.Mailer, baseURL string) {
-	h.mailer = m
+	h.mailerCache.set(h.cacheKey(), m)
 	h.baseURL = baseURL
 	if l, ok := m.(*mailer.Live); ok {
 		h.live = l
@@ -250,8 +314,9 @@ func (h *Handler) isEmailEnabled() bool {
 	if h.live != nil {
 		return h.live.IsEnabled()
 	}
-	// Fallback for tests that inject a direct stub mailer (not wrapped in Live).
-	_, isNoop := h.mailer.(*mailer.Noop)
+	// Fallback for tests that inject a direct stub mailer (not wrapped in Live),
+	// and the multi-tenant path, where each workspace has its own.
+	_, isNoop := h.getMailer().(*mailer.Noop)
 	return !isNoop
 }
 
diff --git a/internal/handler/invites.go b/internal/handler/invites.go
index 6d55733..8354e39 100644
--- a/internal/handler/invites.go
+++ b/internal/handler/invites.go
@@ -103,7 +103,7 @@ func (h *Handler) issueInvite(ctx context.Context, email, adminName, adminID str
 
 	inviteURL = h.baseURL + "/admin/invite/" + token
 	if h.isEmailEnabled() {
-		_ = h.mailer.Send(ctx, mailer.Message{
+		_ = h.getMailer().Send(ctx, mailer.Message{
 			To:      []string{email},
 			Subject: "You've been invited to Calnode",
 			Text: "You've been invited to join Calnode by " + adminName + ".\n\n" +
diff --git a/internal/handler/magic_link.go b/internal/handler/magic_link.go
index 7c69bf9..386bd65 100644
--- a/internal/handler/magic_link.go
+++ b/internal/handler/magic_link.go
@@ -72,8 +72,8 @@ func (h *Handler) sendMagicLink(ctx context.Context, userID, email string) {
 	}
 
 	link := h.baseURL + "/v1/auth/magic-link/verify?token=" + raw
-	if h.mailer != nil {
-		if err := h.mailer.Send(ctx, magicLinkMessage(email, link)); err != nil {
+	if h.getMailer() != nil {
+		if err := h.getMailer().Send(ctx, magicLinkMessage(email, link)); err != nil {
 			h.logger.ErrorContext(ctx, "magic link: send email", "error", err, "user_id", userID)
 		}
 	}
diff --git a/internal/handler/manage_handler.go b/internal/handler/manage_handler.go
index 401d1ff..fa16147 100644
--- a/internal/handler/manage_handler.go
+++ b/internal/handler/manage_handler.go
@@ -297,12 +297,12 @@ func (h *Handler) rescheduleSideEffects(bCopy booking.Booking, capturedEtID stri
 		d.SubjectOverride = subjNote.String
 	}
 	if prefs.NotifyReschedule {
-		if err := mailer.SendRescheduleToAttendee(ctx, h.mailer, d); err != nil {
+		if err := mailer.SendRescheduleToAttendee(ctx, h.getMailer(), d); err != nil {
 			h.logger.Error("reschedule email (attendee)", "error", err, "booking_id", bCopy.ID)
 		}
 	}
 	if prefs.NotifyHostReschedule {
-		if err := mailer.SendRescheduleToHost(ctx, h.mailer, d); err != nil {
+		if err := mailer.SendRescheduleToHost(ctx, h.getMailer(), d); err != nil {
 			h.logger.Error("reschedule email (host)", "error", err, "booking_id", bCopy.ID)
 		}
 	}
diff --git a/internal/handler/reassign.go b/internal/handler/reassign.go
index e3d58c1..bf90a7b 100644
--- a/internal/handler/reassign.go
+++ b/internal/handler/reassign.go
@@ -207,12 +207,12 @@ func (h *Handler) ReassignBooking(w http.ResponseWriter, r *http.Request) {
 
 		prefs := h.hostPrefsOrDefault(ctx, bCopy.ID, newHostID)
 		if prefs.NotifyConfirmation {
-			if err := mailer.SendConfirmationToAttendee(ctx, h.mailer, d); err != nil {
+			if err := mailer.SendConfirmationToAttendee(ctx, h.getMailer(), d); err != nil {
 				h.logger.Error("reassign: email attendee", "error", err, "booking_id", bCopy.ID)
 			}
 		}
 		if prefs.NotifyHostBooking {
-			if err := mailer.SendConfirmationToHost(ctx, h.mailer, d); err != nil {
+			if err := mailer.SendConfirmationToHost(ctx, h.getMailer(), d); err != nil {
 				h.logger.Error("reassign: email new host", "error", err, "booking_id", bCopy.ID)
 			}
 		}
diff --git a/internal/handler/shared.go b/internal/handler/shared.go
index 530dffe..29fd6f5 100644
--- a/internal/handler/shared.go
+++ b/internal/handler/shared.go
@@ -32,10 +32,27 @@ import (
 // `h.livekitMu` and the rest compiling unchanged across the package.
 type shared struct {
 	logger *slog.Logger
-	mailer mailer.Mailer
 	live   *mailer.Live // non-nil in production; nil in tests using a direct stub
 	encKey [32]byte     // AES-256 key for encrypting secrets stored in the DB
 
+	// The per-workspace runtime state (D7). Each is built lazily from THAT
+	// workspace's server_settings row through the bound handle, and replaced when
+	// that workspace saves its settings. One entry keyed "" in single-tenant mode.
+	mailerCache  *tenantCache[mailer.Mailer]
+	llmCache     *tenantCache[*llm.Client]
+	zoomCache    *tenantCache[*zoom.Client]
+	stripeCache  *tenantCache[*stripe.Client]
+	livekitCache *tenantCache[*livekit.Client]
+
+	// ⚠️ cal is STILL a process-wide singleton, and this is a documented gap
+	// rather than an oversight. The calendar Service is a registry of PROVIDERS
+	// keyed by the instance's Google/Microsoft OAuth app, which D7 keeps
+	// platform-level, and each provider captures a *db.DB at construction. Making
+	// it per-tenant needs a ForDB on the Service and on all three providers plus
+	// the config plumbing to build them per workspace; until then, on a
+	// multi-tenant instance the captured handle is unbound, so calendar reads
+	// return nothing and the integration is INERT rather than cross-tenant. See
+	// PROGRESS.md.
 	calMu    sync.RWMutex
 	cal      *calendar.Service
 	calNudge chan struct{} // buffered(1): wakes the calendar reconciler after a failed inline op
@@ -49,18 +66,6 @@ type shared struct {
 	microsoftAuth *oauth2.Config
 	secureCookie  bool
 
-	llmMu sync.RWMutex
-	llm   *llm.Client // nil when the optional LLM layer is off/unconfigured
-
-	zoomMu sync.RWMutex
-	zoom   *zoom.Client // nil when no Zoom app is configured
-
-	stripeMu sync.RWMutex
-	stripe   *stripe.Client // nil when payments are unconfigured
-
-	livekitMu sync.RWMutex
-	livekit   *livekit.Client // nil when LiveKit video is unconfigured
-
 	demoMode          bool // true on the public demo instance: disables calendar/Zoom connect
 	demoResetInterval time.Duration
 	demoMu            sync.RWMutex
diff --git a/internal/handler/tenantcache.go b/internal/handler/tenantcache.go
new file mode 100644
index 0000000..ae48789
--- /dev/null
+++ b/internal/handler/tenantcache.go
@@ -0,0 +1,93 @@
+package handler
+
+import "sync"
+
+// tenantCache holds one lazily-built value per workspace.
+//
+// It replaces the Set/get singleton pairs that used to sit on shared behind a
+// mutex each. The shape is the same — build once, read many, replace on save —
+// with a workspace id in front of it.
+//
+// ⛔ The key is "" in single-tenant mode, not the literal "default". That is
+// deliberate: one entry, built the first time it is asked for, replaced by
+// SetX exactly as before. A single-tenant instance therefore behaves
+// identically and the map never holds more than one entry.
+//
+// present is separate from entries because nil is a MEANINGFUL value here: a
+// workspace with no Stripe credentials caches a nil *stripe.Client, and that
+// must not be mistaken for "not built yet" or every request would rebuild it.
+type tenantCache[T any] struct {
+	mu      sync.RWMutex
+	entries map[string]T
+	present map[string]bool
+}
+
+func newTenantCache[T any]() *tenantCache[T] {
+	return &tenantCache[T]{entries: map[string]T{}, present: map[string]bool{}}
+}
+
+// get returns the cached value for key, building it with build if absent.
+//
+// build runs WITHOUT the lock held, because every builder here reads
+// server_settings — holding the write lock across a database round trip would
+// serialise every tenant behind whichever one was slowest to build. The cost is
+// that two concurrent first-requests for the same workspace may both build; the
+// first store wins and the loser's value is discarded. Clients are stateless
+// value wrappers, so that is waste and not a correctness problem.
+func (c *tenantCache[T]) get(key string, build func() T) T {
+	c.mu.RLock()
+	if c.present[key] {
+		v := c.entries[key]
+		c.mu.RUnlock()
+		return v
+	}
+	c.mu.RUnlock()
+
+	built := build()
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.present[key] {
+		return c.entries[key] // another goroutine got there first; keep one
+	}
+	c.entries[key] = built
+	c.present[key] = true
+	return built
+}
+
+// set replaces the value for key. The settings-save handlers call it after a
+// successful write, which is both the invalidation and the rebuild.
+func (c *tenantCache[T]) set(key string, v T) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.entries[key] = v
+	c.present[key] = true
+}
+
+// invalidate drops the value for key, so the next get rebuilds it from the
+// database. For a save path that does not already hold the built client.
+func (c *tenantCache[T]) invalidate(key string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	delete(c.entries, key)
+	delete(c.present, key)
+}
+
+// size reports how many workspaces have a cached value. For tests.
+func (c *tenantCache[T]) size() int {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return len(c.present)
+}
+
+// cacheKey is the key every per-workspace cache is read and written under.
+//
+// ⛔ "" in single-tenant mode rather than the workspace id, so that the map holds
+// exactly one entry and a single-tenant instance cannot be made to build a second
+// one by anything that calls ForWorkspace.
+func (h *Handler) cacheKey() string {
+	if !h.multiTenant {
+		return ""
+	}
+	return h.Workspace().ID
+}
diff --git a/internal/handler/tenantcache_test.go b/internal/handler/tenantcache_test.go
new file mode 100644
index 0000000..5ea4c48
--- /dev/null
+++ b/internal/handler/tenantcache_test.go
@@ -0,0 +1,335 @@
+package handler
+
+import (
+	"log/slog"
+	"sync"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/mailer"
+)
+
+// Boundary 4: the hot per-tenant state.
+//
+// These run against ONE handle with multiTenant set, which is enough for what they
+// assert: the cache key, the builder's choice of settings row, and invalidation.
+// The reads go through the bound handle, and on a single handle that is the handle
+// itself — so what is under test is the CACHE, not the row-level security, which
+// internal/db and internal/server already prove.
+
+func newCacheHandler(t *testing.T, multiTenant bool) *Handler {
+	t.Helper()
+	database := dbtest.Open(t)
+	h := New(database, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(multiTenant)
+	h.SetBaseURL("https://app.calnode.test")
+	return h
+}
+
+// newPairHandler is for the cases that have to tell two workspaces apart.
+//
+// ⛔ A single handle cannot: db.ForWorkspace is the identity function on one that
+// did not come from OpenPair, so every "scoped" copy would read the same rows and
+// the test would compare a value with itself. It needs the real pair, which needs
+// PostgreSQL and a NOBYPASSRLS role — so these skip loudly on SQLite, and the
+// pure-cache cases below do not.
+func newPairHandler(t *testing.T) (*Handler, *db.DB) {
+	t.Helper()
+	app, platform := dbtest.RequireTenantPair(t)
+	h := New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL("https://app.calnode.test")
+	return h, platform
+}
+
+// seedPairSettings writes the workspace and its settings row through the PLATFORM
+// handle, naming workspace_id — the platform handle binds ”, so an omitted column
+// would land both rows in the default workspace.
+func seedPairSettings(t *testing.T, platform *db.DB, wsID, from string) {
+	t.Helper()
+	if _, err := platform.Exec(
+		`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', 'active')`,
+		wsID, wsID, wsID+".example.com"); err != nil {
+		t.Fatalf("seed workspace %s: %v", wsID, err)
+	}
+	if _, err := platform.Exec(
+		`INSERT INTO server_settings (workspace_id, id, smtp_host, smtp_port, email_from, email_from_name)
+		 VALUES (?, 1, 'smtp.example.com', '587', ?, ?)`,
+		wsID, from, wsID); err != nil {
+		t.Fatalf("seed settings for %s: %v", wsID, err)
+	}
+}
+
+// TestTenantCache_mailerIsPerWorkspace is the positive half: A's mailer carries
+// A's From address and B's carries B's, built lazily from each workspace's own
+// server_settings row.
+func TestTenantCache_mailerIsPerWorkspace(t *testing.T) {
+	h, platform := newPairHandler(t)
+	seedPairSettings(t, platform, "acme", "bookings@acme.example")
+	seedPairSettings(t, platform, "globex", "hello@globex.example")
+
+	a := h.forWorkspace(&Workspace{ID: "acme", Status: "active"})
+	b := h.forWorkspace(&Workspace{ID: "globex", Status: "active"})
+
+	fromA := senderAddress(t, a.getMailer())
+	fromB := senderAddress(t, b.getMailer())
+
+	if fromA != "bookings@acme.example" {
+		t.Errorf("A's mailer From = %q; want bookings@acme.example", fromA)
+	}
+	if fromB != "hello@globex.example" {
+		t.Errorf("B's mailer From = %q; want hello@globex.example", fromB)
+	}
+	if fromA == fromB {
+		t.Fatal("both workspaces got the same mailer")
+	}
+
+	// Two entries, and the base handler's key is not one of them.
+	if got := h.mailerCache.size(); got != 2 {
+		t.Errorf("mailer cache holds %d entries; want 2", got)
+	}
+	// Reading again must not rebuild.
+	if again := senderAddress(t, a.getMailer()); again != fromA {
+		t.Errorf("second read of A's mailer = %q; want %q", again, fromA)
+	}
+	if got := h.mailerCache.size(); got != 2 {
+		t.Errorf("a repeat read grew the cache to %d entries", got)
+	}
+}
+
+// TestTenantCache_keyIsWhatSeparatesThem is the negative control, kept in the tree
+// rather than run by hand: with the key forced to "" the two workspaces share one
+// entry, and whichever built first decides what the other sends.
+//
+// It reaches into the cache directly with the same builder the accessor uses,
+// because cacheKey itself is what is under test.
+func TestTenantCache_keyIsWhatSeparatesThem(t *testing.T) {
+	h, platform := newPairHandler(t)
+	seedPairSettings(t, platform, "acme", "bookings@acme.example")
+	seedPairSettings(t, platform, "globex", "hello@globex.example")
+
+	a := h.forWorkspace(&Workspace{ID: "acme", Status: "active"})
+	b := h.forWorkspace(&Workspace{ID: "globex", Status: "active"})
+
+	build := func(scoped *Handler) func() mailer.Mailer {
+		return func() mailer.Mailer {
+			cfg, err := LoadEmailSettingsFromDB(scoped.db, scoped.encKey)
+			if err != nil || cfg == nil {
+				return &mailer.Noop{}
+			}
+			m, _ := BuildMailer(*cfg)
+			return m
+		}
+	}
+
+	// The real keys keep them apart.
+	realA := senderAddress(t, h.mailerCache.get(a.cacheKey(), build(a)))
+	realB := senderAddress(t, h.mailerCache.get(b.cacheKey(), build(b)))
+	if realA == realB {
+		t.Fatalf("with real keys both workspaces got %q", realA)
+	}
+
+	// The stubbed key collapses them.
+	collapsed := newTenantCache[mailer.Mailer]()
+	stubbedA := senderAddress(t, collapsed.get("", build(a)))
+	stubbedB := senderAddress(t, collapsed.get("", build(b)))
+	if stubbedA != stubbedB {
+		t.Fatalf("a shared key should have collided: A got %q, B got %q", stubbedA, stubbedB)
+	}
+	if stubbedB != realA {
+		t.Errorf("with the key stubbed to \"\", B sends as %q — A's address is %q", stubbedB, realA)
+	}
+	t.Logf("key stubbed to \"\": B would send as %q instead of %q", stubbedB, realB)
+}
+
+// TestTenantCache_saveInvalidatesOnlyThatWorkspace.
+func TestTenantCache_saveInvalidatesOnlyThatWorkspace(t *testing.T) {
+	h, platform := newPairHandler(t)
+	seedPairSettings(t, platform, "acme", "bookings@acme.example")
+	seedPairSettings(t, platform, "globex", "hello@globex.example")
+
+	a := h.forWorkspace(&Workspace{ID: "acme", Status: "active"})
+	b := h.forWorkspace(&Workspace{ID: "globex", Status: "active"})
+
+	_ = a.getMailer()
+	beforeB := senderAddress(t, b.getMailer())
+
+	// A saves new settings, the way the settings handler does: write the row, then
+	// drop the cached client.
+	if _, err := a.db.Exec(
+		`UPDATE server_settings SET email_from = ? WHERE id = 1`, "new@acme.example"); err != nil {
+		t.Fatalf("update A's settings: %v", err)
+	}
+	h.mailerCache.invalidate(a.cacheKey())
+
+	if got := senderAddress(t, a.getMailer()); got != "new@acme.example" {
+		t.Errorf("after A saved, A's mailer From = %q; want new@acme.example", got)
+	}
+	if got := senderAddress(t, b.getMailer()); got != beforeB {
+		t.Errorf("A's save changed B's mailer to %q; want %q", got, beforeB)
+	}
+}
+
+// TestTenantCache_singleTenantKeepsOneEntry is the byte-identical promise: with
+// MULTI_TENANT unset the key is "" whatever workspace a handle claims, so the map
+// cannot grow past one and SetX behaves exactly as the old singleton did.
+func TestTenantCache_singleTenantKeepsOneEntry(t *testing.T) {
+	h := newCacheHandler(t, false)
+
+	if got := h.cacheKey(); got != "" {
+		t.Errorf("single-tenant cacheKey() = %q; want empty", got)
+	}
+	h.SetLLM(nil)
+	h.SetStripe(nil)
+	h.SetZoom(nil)
+	h.SetLiveKit(nil)
+
+	// forWorkspace is the identity function here, so it cannot introduce a key.
+	scoped := h.forWorkspace(&Workspace{ID: "acme"})
+	if got := scoped.cacheKey(); got != "" {
+		t.Errorf("a scoped handle in single-tenant mode has key %q", got)
+	}
+	for name, size := range map[string]int{
+		"llm": h.llmCache.size(), "stripe": h.stripeCache.size(),
+		"zoom": h.zoomCache.size(), "livekit": h.livekitCache.size(),
+	} {
+		if size != 1 {
+			t.Errorf("%s cache holds %d entries in single-tenant mode; want 1", name, size)
+		}
+	}
+	// And a nil client stays nil rather than being rebuilt on every read: nil is a
+	// meaningful cached value, not "absent".
+	if h.getStripe() != nil {
+		t.Error("getStripe rebuilt over an explicitly-set nil")
+	}
+	if got := h.stripeCache.size(); got != 1 {
+		t.Errorf("a read after SetStripe(nil) grew the cache to %d", got)
+	}
+}
+
+// TestTenantCache_concurrentWorkspaces is the race case: two workspaces hitting the
+// same cache at once. Run the package with -race for it to mean anything.
+func TestTenantCache_concurrentWorkspaces(t *testing.T) {
+	h, platform := newPairHandler(t)
+	seedPairSettings(t, platform, "acme", "bookings@acme.example")
+	seedPairSettings(t, platform, "globex", "hello@globex.example")
+
+	want := map[string]string{
+		"acme":   "bookings@acme.example",
+		"globex": "hello@globex.example",
+	}
+
+	var wg sync.WaitGroup
+	errs := make(chan string, 64)
+	for i := 0; i < 16; i++ {
+		for ws, from := range want {
+			wg.Add(1)
+			go func(ws, from string) {
+				defer wg.Done()
+				scoped := h.forWorkspace(&Workspace{ID: ws, Status: "active"})
+				got := senderAddressNoFatal(scoped.getMailer())
+				if got != from {
+					errs <- ws + " got " + got + ", want " + from
+				}
+				// Interleave a write, so the cache is read and replaced at once.
+				if ws == "globex" {
+					h.mailerCache.invalidate(scoped.cacheKey())
+				}
+			}(ws, from)
+		}
+	}
+	wg.Wait()
+	close(errs)
+	for e := range errs {
+		t.Error(e)
+	}
+}
+
+// TestTenantCache_getBuildsOnceUnderContention pins the "first store wins"
+// behaviour that lets the builder run outside the lock.
+func TestTenantCache_getBuildsOnceUnderContention(t *testing.T) {
+	c := newTenantCache[int]()
+	var mu sync.Mutex
+	builds := 0
+
+	var wg sync.WaitGroup
+	results := make([]int, 32)
+	for i := range results {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			results[i] = c.get("ws", func() int {
+				mu.Lock()
+				builds++
+				n := builds
+				mu.Unlock()
+				return n
+			})
+		}(i)
+	}
+	wg.Wait()
+
+	// Every caller must see the SAME value, even if more than one builder ran.
+	for i, got := range results {
+		if got != results[0] {
+			t.Fatalf("caller %d got %d, caller 0 got %d — the cache handed out two values", i, got, results[0])
+		}
+	}
+	if c.size() != 1 {
+		t.Errorf("cache holds %d entries for one key", c.size())
+	}
+	t.Logf("%d concurrent gets ran %d builders and returned one value", len(results), builds)
+}
+
+// TestTenantCache_llmAndStripeBuildFromTheirOwnRow covers the other two kinds
+// with the same shape, so the mailer is not the only one proven.
+func TestTenantCache_llmAndStripeBuildFromTheirOwnRow(t *testing.T) {
+	h, platform := newPairHandler(t)
+	seedPairSettings(t, platform, "acme", "bookings@acme.example")
+	seedPairSettings(t, platform, "globex", "hello@globex.example")
+
+	// Only A enables the LLM layer.
+	a := h.forWorkspace(&Workspace{ID: "acme", Status: "active"})
+	b := h.forWorkspace(&Workspace{ID: "globex", Status: "active"})
+	if _, err := a.db.Exec(
+		`UPDATE server_settings SET llm_enabled = 1, llm_endpoint = ?, llm_model = ? WHERE id = 1`,
+		"https://llm.acme.example/v1", "acme-model"); err != nil {
+		t.Fatalf("enable A's LLM: %v", err)
+	}
+
+	if a.getLLM() == nil {
+		t.Error("A enabled the LLM layer and got no client")
+	}
+	if b.getLLM() != nil {
+		t.Error("B did not enable the LLM layer and got a client")
+	}
+
+	// Neither has Stripe credentials, so both cache nil — and cache it, rather than
+	// rebuilding on every read.
+	if a.getStripe() != nil || b.getStripe() != nil {
+		t.Error("a workspace with no Stripe credentials got a client")
+	}
+	if got := h.stripeCache.size(); got != 2 {
+		t.Errorf("stripe cache holds %d entries; want one nil per workspace", got)
+	}
+}
+
+// senderAddress reads the From address out of whatever transport BuildMailer
+// chose, which is the only per-workspace value visible from outside.
+func senderAddress(t *testing.T, m mailer.Mailer) string {
+	t.Helper()
+	got := senderAddressNoFatal(m)
+	if got == "" {
+		t.Fatalf("mailer %T exposes no From address", m)
+	}
+	return got
+}
+
+func senderAddressNoFatal(m mailer.Mailer) string {
+	type fromer interface{ From() string }
+	if f, ok := m.(fromer); ok {
+		return f.From()
+	}
+	return ""
+}
diff --git a/internal/handler/test_email.go b/internal/handler/test_email.go
index 269d843..06af26f 100644
--- a/internal/handler/test_email.go
+++ b/internal/handler/test_email.go
@@ -111,7 +111,7 @@ func (h *Handler) SendTestEmail(w http.ResponseWriter, r *http.Request) {
 		h.writeError(w, http.StatusInternalServerError, "internal error")
 		return
 	}
-	if err := h.mailer.Send(r.Context(), mailer.Message{
+	if err := h.getMailer().Send(r.Context(), mailer.Message{
 		To:      []string{user.Email},
 		Subject: "[TEST] " + subject,
 		Text:    body,
diff --git a/internal/mailer/live.go b/internal/mailer/live.go
index 845341e..fc2d662 100644
--- a/internal/mailer/live.go
+++ b/internal/mailer/live.go
@@ -40,3 +40,15 @@ func (l *Live) IsEnabled() bool {
 	l.mu.RUnlock()
 	return !noop
 }
+
+// From delegates to the current transport, so a Live-wrapped mailer answers the
+// same question its target does. Empty when the target has no sender (Noop).
+func (l *Live) From() string {
+	l.mu.RLock()
+	defer l.mu.RUnlock()
+	type fromer interface{ From() string }
+	if f, ok := l.current.(fromer); ok {
+		return f.From()
+	}
+	return ""
+}
diff --git a/internal/mailer/resend.go b/internal/mailer/resend.go
index baf4d95..59a3a3d 100644
--- a/internal/mailer/resend.go
+++ b/internal/mailer/resend.go
@@ -163,3 +163,6 @@ func resendErrorDetail(body io.Reader) string {
 	}
 	return string(raw)
 }
+
+// From returns the envelope sender this transport was built with. See SMTP.From.
+func (r *Resend) From() string { return r.from }
diff --git a/internal/mailer/smtp.go b/internal/mailer/smtp.go
index 26a478b..f251ece 100644
--- a/internal/mailer/smtp.go
+++ b/internal/mailer/smtp.go
@@ -277,3 +277,10 @@ func base64Wrap(b []byte) string {
 	sb.WriteString(enc)
 	return sb.String()
 }
+
+// From returns the envelope sender this transport was built with.
+//
+// It exists because the sender is the only per-workspace value a built mailer
+// exposes from outside, and multi-tenant mode has to be able to assert that one
+// workspace's transport is not another's (internal/handler/tenantcache_test.go).
+func (s *SMTP) From() string { return s.from }

From 4522ff67f84eb432eec3096b840c0c63842058c5 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 02:46:59 -0400
Subject: [PATCH 33/51] calendar,server: bind the providers to the workspace,
 and stop priming what cannot be primed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boundary 5, part one: deliverables 1 and 4. The worker, the reconciler and the CLI
subcommands follow.

B4 left getCal as a process-wide singleton and called it "inert rather than
cross-tenant". Inert is not shippable — calendar connections are the product — so
calendar.Provider gains ForDB(handle) Provider, implemented by gcal, microsoft and
caldav as a shallow copy with the handle replaced. No import cycle: all three
already import internal/calendar for CalendarInfo and calendar imports none of
them. Service.ForDB rebuilds the provider map through each provider's own ForDB and
carries primary over, so which backend claims a new connection does not change per
workspace.

The OAuth app configuration stays platform-level per D7 — client id, secret,
redirect and encryption key identify the instance to Google and Microsoft, not the
tenant — so ForDB is deliberately shallow. shared now holds calBase, the registry
boot installs, and calCache, the per-workspace bound copies, and getCal is the only
reader: returning calBase directly is the bug this splits apart. Single-tenant
returns calBase itself, because rebinding would allocate a second Service and every
provider in it for no behaviour change. SetCalendar invalidates, so SetCalendar(nil)
is not shadowed by a cached service.

The test uses CalDAV, which needs no instance-level OAuth app, so it is about the
handle and not about credentials: two workspaces with one connection row each, and
per workspace Connected and HasDestination true for its own user and false for the
other's, with a platform-handle control that both rows exist so a false is the
policy rather than an empty table. Disconnect is the write half — A asking to
disconnect B's user leaves B's row intact. The negative control is in the tree and
logs the leak in one line: with the key stubbed, B's service sees A's connection and
not its own. That is one tenant's free/busy deciding another's availability, which
is worse than the mailer case because it is silent.

Boot priming is made single-tenant-only rather than removed. Every
LoadXSettingsFromDB reads server_settings through the unbound handle, which in
multi-tenant mode matches no row — so it installed nothing and logged "not
configured" for an instance whose tenants are all configured. Gated rather than
deleted because it is the only path that seeds env-var SMTP into the database on
first boot, and on a single-tenant instance it is what makes the first request fast
instead of lazy.

gofmt -l empty, go vet clean, four calendar cases pass under -race.
---
 PROGRESS.md                               |  98 ++++++++
 internal/caldav/caldav.go                 |  10 +
 internal/calendar/calendar.go             |  29 +++
 internal/calendar/microsoft/microsoft.go  |  10 +
 internal/gcal/gcal.go                     |  10 +
 internal/handler/calendar_tenancy_test.go | 260 ++++++++++++++++++++++
 internal/handler/handler.go               |  34 ++-
 internal/handler/shared.go                |  16 +-
 internal/server/server.go                 |  37 ++-
 9 files changed, 483 insertions(+), 21 deletions(-)
 create mode 100644 internal/handler/calendar_tenancy_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 3ecab24..53ed548 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1144,3 +1144,101 @@ All seven cases pass **under `-race`** on the PostgreSQL lane:
 --- PASS: TestTenantCache_getBuildsOnceUnderContention (0.00s)
 --- PASS: TestTenantCache_llmAndStripeBuildFromTheirOwnRow (1.11s)
 ```
+
+## Boundary 5, part one — the calendar gap closed, and boot priming gated
+
+⚠️ **B5 deliverables 2, 3 and 5 are NOT in this commit** — the worker's claim loop,
+the reconciler, and the CLI subcommands. This lands 1 and 4, which separate
+cleanly from the rest and close the gap B4 left open.
+
+### The calendar gap (deliverable 1) — `ForDB` through the Provider interface
+
+B4 left `getCal` as a process-wide singleton and called it "inert rather than
+cross-tenant". Inert is not shippable: calendar connections are the product.
+
+`calendar.Provider` gains **`ForDB(handle *db.DB) Provider`**, implemented by all
+three backends as a shallow copy with the handle replaced. No import cycle: all
+three already import `internal/calendar` for `CalendarInfo`, and `calendar` imports
+none of them. `calendar.Service.ForDB` rebuilds its provider map through each
+provider's own `ForDB` and carries `primary` over, so which backend claims a new
+connection does not change per workspace.
+
+⛔ **The OAuth APP configuration stays platform-level, per D7** — client id,
+secret, redirect, encryption key identify the *Calnode instance* to Google and
+Microsoft, not the tenant. So `ForDB` is deliberately a shallow copy: same config,
+different handle. `shared` now holds `calBase` (the registry boot installs) and
+`calCache` (the per-workspace bound copies), and **`getCal` is the only reader** —
+returning `calBase` directly is the bug this splits apart.
+
+Single-tenant returns `calBase` itself rather than a rebound copy: one workspace,
+one handle, so rebinding would allocate a second Service and every provider in it
+for no behaviour change. `SetCalendar` invalidates the cache, so `SetCalendar(nil)`
+is visible immediately instead of being shadowed.
+
+**Why CalDAV carries the test:** it needs no instance-level OAuth app, so the test
+is about the handle and not about credentials. Two workspaces, one
+`calendar_connections` row each, then per workspace: `Connected` and
+`HasDestination` are true for its own user and **false for the other's**, with a
+positive control through the platform handle that both rows exist (so a `false` is
+the policy, not an empty table). `Disconnect` is the write half — A asking to
+disconnect B's user must leave B's row intact, whether or not it errors.
+
+Negative control, same shape as the mailer's and in the tree:
+
+```
+calendar_tenancy_test.go:229: key stubbed to "": B's service sees A's connection = true, its own = false
+```
+
+That is one tenant's free/busy deciding another's availability — the failure mode
+that matters here, and it is worse than the mailer's, because it is silent.
+
+### Boot priming (deliverable 4) — made single-tenant-only, not removed
+
+Every `LoadXSettingsFromDB(db, encKey)` in `server.New` reads `server_settings`
+through the **unbound** application handle. In multi-tenant mode that matches no
+row, so priming installed nothing and logged "not configured" for an instance whose
+tenants are all configured — a misleading boot log and six pointless round trips.
+
+`primeFromDB := !cfg.MultiTenant` gates all six through a small
+`loadIfSingleTenant` generic that returns `(nil, nil)` when priming is off, which
+every call site already treats as "not configured in the database". Multi-tenant
+boot now logs once, plainly:
+
+```
+multi-tenant mode: per-workspace settings are built on first use, not primed at boot
+```
+
+**Gated rather than removed**, and the reason is specific: it is the only path that
+seeds env-var SMTP into the database on first boot (`seedSMTPToDB`), and on a
+single-tenant instance it is what makes the first request fast instead of lazy.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean. The four calendar
+cases pass **under `-race`**:
+
+```
+--- PASS: TestCalendar_providersSeeOnlyTheirWorkspace (1.27s)
+    --- PASS: TestCalendar_providersSeeOnlyTheirWorkspace/acme
+    --- PASS: TestCalendar_providersSeeOnlyTheirWorkspace/globex
+--- PASS: TestCalendar_disconnectCannotReachAnotherWorkspace (1.39s)
+--- PASS: TestCalendar_keyIsWhatSeparatesThem (1.35s)
+--- PASS: TestCalendar_singleTenantReusesTheRegistry (0.89s)
+```
+
+### Still owed by B5
+
+2. **Worker.** The claim loop must run on the platform handle across tenants and
+   process each job on `ForWorkspace(job.workspace_id)` with the per-tenant caches.
+   Today it holds one handle from `worker.New(db, …)` and one `*mailer.Live`, so on
+   a multi-tenant instance it claims nothing (`jobs` is a tenant table, the handle
+   is unbound). Two-workspace claim-loop test owed.
+3. **Reconciler.** `StartCalendarReconciler` iterates state on one handle; it needs
+   to enumerate `workspaces` on the platform handle and then run each pass bound.
+   ⚠️ It is started from `server.New` only when `calSvc.Any()`, which after
+   deliverable 4 is still true (providers are registered from env/CalDAV, not from
+   `server_settings`) — so it does run, and it currently runs unbound.
+4. **CLI.** `mcp` (stdio), `reset-admin`, `rotate-key`, `recover-key` still open one
+   handle from `DATABASE_URL`. `rotate-key` and `recover-key` are genuinely
+   platform-wide (`crypto_keystore` is exempt, one DEK per process, D3);
+   `reset-admin` and `mcp` stdio are per-workspace and have no way to say which.
diff --git a/internal/caldav/caldav.go b/internal/caldav/caldav.go
index d72635d..661fc2d 100644
--- a/internal/caldav/caldav.go
+++ b/internal/caldav/caldav.go
@@ -326,3 +326,13 @@ func (c *Client) decryptEncoding(ciphertext string, enc *base64.Encoding) ([]byt
 	}
 	return plain, nil
 }
+
+// ForDB returns a copy of c reading and writing through handle, so a per-request
+// handler can bind CalDAV to its workspace. The OAuth app configuration and
+// the encryption key are instance-level (D7) and are carried over unchanged; only
+// the database handle differs.
+func (c *Client) ForDB(handle *db.DB) calendar.Provider {
+	copied := *c
+	copied.db = handle
+	return &copied
+}
diff --git a/internal/calendar/calendar.go b/internal/calendar/calendar.go
index f8e6696..9c807a4 100644
--- a/internal/calendar/calendar.go
+++ b/internal/calendar/calendar.go
@@ -51,6 +51,21 @@ type Provider interface {
 	Name() string        // "google" | "microsoft"
 	InvitesGuests() bool // provider emails guests itself → suppress our own .ics
 
+	// ForDB returns a copy of this provider reading and writing through handle.
+	//
+	// ⛔ Every provider captures a *db.DB at construction, and every one of its
+	// operations reads calendar_connections / connection_calendars — which are
+	// TENANT tables. On a multi-tenant instance a provider built at boot holds the
+	// UNBOUND application handle, which matches no row, so the whole integration
+	// would be silently inert. This is how a per-request handler gets providers
+	// bound to its workspace.
+	//
+	// The OAuth APP configuration — client id, secret, redirect, encryption key —
+	// is deliberately NOT per workspace (D7): it identifies the Calnode instance to
+	// Google or Microsoft, not the tenant. So this is a shallow copy: same config,
+	// different handle.
+	ForDB(handle *db.DB) Provider
+
 	// OAuth
 	AuthURL(state string) string
 	EncryptState(userID string) (string, error)
@@ -93,6 +108,20 @@ func NewService(db *db.DB) *Service {
 	return &Service{db: db, providers: map[string]Provider{}}
 }
 
+// ForDB returns a copy of s, and of every provider registered in it, bound to
+// handle.
+//
+// The provider map is rebuilt rather than shared, because a Provider owns its own
+// handle. primary is carried over, so which backend claims a new connection does
+// not change per workspace.
+func (s *Service) ForDB(handle *db.DB) *Service {
+	bound := &Service{db: handle, providers: make(map[string]Provider, len(s.providers)), primary: s.primary}
+	for name, p := range s.providers {
+		bound.providers[name] = p.ForDB(handle)
+	}
+	return bound
+}
+
 // Register adds a provider (keyed by Name()); the first registered becomes primary.
 func (s *Service) Register(p Provider) {
 	s.providers[p.Name()] = p
diff --git a/internal/calendar/microsoft/microsoft.go b/internal/calendar/microsoft/microsoft.go
index 8c1f0d3..fc77649 100644
--- a/internal/calendar/microsoft/microsoft.go
+++ b/internal/calendar/microsoft/microsoft.go
@@ -461,3 +461,13 @@ func (c *Client) decryptEncoding(ciphertext string, enc *base64.Encoding) ([]byt
 	}
 	return plain, nil
 }
+
+// ForDB returns a copy of c reading and writing through handle, so a per-request
+// handler can bind Microsoft Graph to its workspace. The OAuth app configuration and
+// the encryption key are instance-level (D7) and are carried over unchanged; only
+// the database handle differs.
+func (c *Client) ForDB(handle *db.DB) calendar.Provider {
+	copied := *c
+	copied.db = handle
+	return &copied
+}
diff --git a/internal/gcal/gcal.go b/internal/gcal/gcal.go
index ed3e5eb..528774a 100644
--- a/internal/gcal/gcal.go
+++ b/internal/gcal/gcal.go
@@ -401,3 +401,13 @@ func (c *Client) decryptEncoding(ciphertext string, enc *base64.Encoding) ([]byt
 	}
 	return plain, nil
 }
+
+// ForDB returns a copy of c reading and writing through handle, so a per-request
+// handler can bind Google Calendar to its workspace. The OAuth app configuration and
+// the encryption key are instance-level (D7) and are carried over unchanged; only
+// the database handle differs.
+func (c *Client) ForDB(handle *db.DB) calendar.Provider {
+	copied := *c
+	copied.db = handle
+	return &copied
+}
diff --git a/internal/handler/calendar_tenancy_test.go b/internal/handler/calendar_tenancy_test.go
new file mode 100644
index 0000000..2b795e7
--- /dev/null
+++ b/internal/handler/calendar_tenancy_test.go
@@ -0,0 +1,260 @@
+package handler
+
+import (
+	"context"
+	"log/slog"
+	"testing"
+
+	"github.com/calnode/calnode/internal/caldav"
+	"github.com/calnode/calnode/internal/calendar"
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// The calendar half of Boundary 5.
+//
+// Providers are the one integration whose per-tenant state is not a credential in
+// server_settings but a ROW in calendar_connections — so the failure mode is not
+// "one tenant's API key sends another's email", it is "one tenant's free/busy
+// decides another's availability". A provider built at boot holds the handle boot
+// gave it, which on a multi-tenant instance is the unbound one; before ForDB
+// existed that made the whole integration inert.
+
+// testEncKey is a fixed 64-hex AES-256 key. The provider needs one to construct;
+// nothing here encrypts or decrypts, because what is under test is which ROWS a
+// provider can reach, not what is in them.
+const testEncKey = "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
+
+// newCalHandler builds a handler over a real pair with a CalDAV provider
+// registered. CalDAV is the provider used here because it needs no instance-level
+// OAuth app — so the test is about the handle, not about credentials.
+func newCalHandler(t *testing.T) (*Handler, *db.DB) {
+	t.Helper()
+	app, platform := dbtest.RequireTenantPair(t)
+
+	h := New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL("https://app.calnode.test")
+
+	// The platform-level registry: instance credentials, boot's handle. Exactly
+	// what server.New installs.
+	base := calendar.NewService(app)
+	cdav, err := caldav.New(app, testEncKey)
+	if err != nil {
+		t.Fatalf("caldav.New: %v", err)
+	}
+	base.Register(cdav)
+	h.SetCalendar(base)
+
+	return h, platform
+}
+
+// seedCalWorkspace creates a workspace, its owner, and one CalDAV connection row.
+func seedCalWorkspace(t *testing.T, h *Handler, platform *db.DB, wsID string) string {
+	t.Helper()
+	if _, err := platform.Exec(
+		`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', 'active')`,
+		wsID, wsID, wsID+".example.com"); err != nil {
+		t.Fatalf("seed workspace %s: %v", wsID, err)
+	}
+
+	userID := wsID + "-user"
+	bound := h.db.ForWorkspace(wsID)
+	if _, err := bound.Exec(
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		userID, wsID+"@example.com", wsID); err != nil {
+		t.Fatalf("seed user for %s: %v", wsID, err)
+	}
+	// A connection row with a destination, which is what Connected and
+	// HasDestination read. The token columns hold ciphertext the test never
+	// decrypts; what is under test is which ROWS a provider can see.
+	if _, err := bound.Exec(
+		`INSERT INTO calendar_connections
+		   (id, user_id, provider, access_token_enc, refresh_token_enc, calendar_id, check_conflicts, is_destination, created_at, account_email)
+		 VALUES (?, ?, 'caldav', 'x', 'y', ?, 1, 1, '2026-01-01T00:00:00Z', ?)`,
+		wsID+"-conn", userID, wsID+"-calendar", wsID+"@example.com"); err != nil {
+		t.Fatalf("seed connection for %s: %v", wsID, err)
+	}
+	return userID
+}
+
+// TestCalendar_providersSeeOnlyTheirWorkspace is the positive half: each
+// workspace's service reports its OWN user connected, and reports the other
+// workspace's user as not connected even though that row exists.
+func TestCalendar_providersSeeOnlyTheirWorkspace(t *testing.T) {
+	h, platform := newCalHandler(t)
+	ctx := context.Background()
+
+	userA := seedCalWorkspace(t, h, platform, "acme")
+	userB := seedCalWorkspace(t, h, platform, "globex")
+
+	a := h.forWorkspace(&Workspace{ID: "acme", Status: "active"})
+	b := h.forWorkspace(&Workspace{ID: "globex", Status: "active"})
+
+	calA, calB := a.getCal(), b.getCal()
+	if calA == nil || calB == nil {
+		t.Fatal("a workspace got no calendar service")
+	}
+	if calA == calB {
+		t.Fatal("both workspaces got the same calendar service — ForDB did not run")
+	}
+
+	// Positive control on the data: through the platform handle both rows exist, so
+	// a false below is the policy and not an empty table.
+	var rows int
+	if err := platform.QueryRowContext(ctx, `SELECT COUNT(*) FROM calendar_connections`).Scan(&rows); err != nil {
+		t.Fatalf("count connections: %v", err)
+	}
+	if rows != 2 {
+		t.Fatalf("the fixture left %d connection rows; want 2", rows)
+	}
+
+	for _, tc := range []struct {
+		name    string
+		svc     *calendar.Service
+		own     string
+		other   string
+		otherWS string
+	}{
+		{name: "acme", svc: calA, own: userA, other: userB, otherWS: "globex"},
+		{name: "globex", svc: calB, own: userB, other: userA, otherWS: "acme"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			connected, _, err := tc.svc.Connected(ctx, tc.own)
+			if err != nil {
+				t.Fatalf("Connected(own): %v", err)
+			}
+			if !connected {
+				t.Errorf("%s cannot see its own connection", tc.name)
+			}
+
+			leaked, _, err := tc.svc.Connected(ctx, tc.other)
+			if err != nil {
+				t.Fatalf("Connected(other): %v", err)
+			}
+			if leaked {
+				t.Errorf("%s can see %s's connection", tc.name, tc.otherWS)
+			}
+
+			hasDest, err := tc.svc.HasDestination(ctx, tc.own)
+			if err != nil {
+				t.Fatalf("HasDestination(own): %v", err)
+			}
+			if !hasDest {
+				t.Errorf("%s cannot see its own destination", tc.name)
+			}
+			otherDest, err := tc.svc.HasDestination(ctx, tc.other)
+			if err != nil {
+				t.Fatalf("HasDestination(other): %v", err)
+			}
+			if otherDest {
+				t.Errorf("%s can see %s's destination", tc.name, tc.otherWS)
+			}
+		})
+	}
+}
+
+// TestCalendar_disconnectCannotReachAnotherWorkspace is the write half. Disconnect
+// deletes rows; on the wrong handle it would delete another tenant's connection.
+func TestCalendar_disconnectCannotReachAnotherWorkspace(t *testing.T) {
+	h, platform := newCalHandler(t)
+	ctx := context.Background()
+
+	_ = seedCalWorkspace(t, h, platform, "acme")
+	userB := seedCalWorkspace(t, h, platform, "globex")
+
+	a := h.forWorkspace(&Workspace{ID: "acme", Status: "active"})
+
+	// A asks to disconnect B's user. It must not matter whether this errors or
+	// silently affects nothing — what matters is that B's row survives.
+	_ = a.getCal().Disconnect(ctx, userB)
+
+	var n int
+	if err := platform.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM calendar_connections WHERE workspace_id = ?`, "globex").Scan(&n); err != nil {
+		t.Fatalf("count B's connections: %v", err)
+	}
+	if n != 1 {
+		t.Errorf("B has %d connections after A tried to disconnect its user; want 1", n)
+	}
+}
+
+// TestCalendar_keyIsWhatSeparatesThem is the negative control, in the same shape as
+// the mailer one: with the cache key stubbed to "", both workspaces share one
+// service and whichever built first decides what the other can see.
+func TestCalendar_keyIsWhatSeparatesThem(t *testing.T) {
+	h, platform := newCalHandler(t)
+	ctx := context.Background()
+
+	userA := seedCalWorkspace(t, h, platform, "acme")
+	userB := seedCalWorkspace(t, h, platform, "globex")
+
+	a := h.forWorkspace(&Workspace{ID: "acme", Status: "active"})
+	b := h.forWorkspace(&Workspace{ID: "globex", Status: "active"})
+
+	build := func(scoped *Handler) func() *calendar.Service {
+		return func() *calendar.Service {
+			h.calMu.RLock()
+			base := h.calBase
+			h.calMu.RUnlock()
+			return base.ForDB(scoped.db)
+		}
+	}
+
+	// Real keys: each sees only its own.
+	realA := h.calCache.get(a.cacheKey(), build(a))
+	realB := h.calCache.get(b.cacheKey(), build(b))
+	if leaked, _, _ := realA.Connected(ctx, userB); leaked {
+		t.Fatal("with real keys, A can already see B")
+	}
+	if leaked, _, _ := realB.Connected(ctx, userA); leaked {
+		t.Fatal("with real keys, B can already see A")
+	}
+
+	// Key stubbed to "": B is handed the service built for A.
+	collapsed := newTenantCache[*calendar.Service]()
+	stubbedA := collapsed.get("", build(a))
+	stubbedB := collapsed.get("", build(b))
+	if stubbedA != stubbedB {
+		t.Fatal("a shared key should have handed out one service")
+	}
+	sawA, _, err := stubbedB.Connected(ctx, userA)
+	if err != nil {
+		t.Fatalf("Connected: %v", err)
+	}
+	if !sawA {
+		t.Fatal("the collapsed service should have seen A's connection — the control proves nothing otherwise")
+	}
+	sawOwn, _, _ := stubbedB.Connected(ctx, userB)
+	t.Logf("key stubbed to \"\": B's service sees A's connection = %v, its own = %v", sawA, sawOwn)
+	if sawOwn {
+		t.Error("the collapsed service saw both workspaces; expected only the one it was built for")
+	}
+}
+
+// TestCalendar_singleTenantReusesTheRegistry: no rebinding, no second allocation,
+// so an existing deployment runs the same objects it always did.
+func TestCalendar_singleTenantReusesTheRegistry(t *testing.T) {
+	database := dbtest.Open(t)
+	h := New(database, slog.New(slog.DiscardHandler))
+
+	base := calendar.NewService(database)
+	cdav, err := caldav.New(database, testEncKey)
+	if err != nil {
+		t.Fatalf("caldav.New: %v", err)
+	}
+	base.Register(cdav)
+	h.SetCalendar(base)
+
+	if got := h.getCal(); got != base {
+		t.Error("single-tenant getCal returned a rebound copy; it should be the registry itself")
+	}
+	if got := h.calCache.size(); got != 1 {
+		t.Errorf("calendar cache holds %d entries in single-tenant mode; want 1", got)
+	}
+	// SetCalendar(nil) must be visible immediately, not shadowed by the cache.
+	h.SetCalendar(nil)
+	if h.getCal() != nil {
+		t.Error("SetCalendar(nil) left a cached service behind")
+	}
+}
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index a894607..04b7232 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -180,6 +180,7 @@ func New(database *db.DB, logger *slog.Logger) *Handler {
 			logger:       logger,
 			calNudge:     make(chan struct{}, 1),
 			mailerCache:  newTenantCache[mailer.Mailer](),
+			calCache:     newTenantCache[*calendar.Service](),
 			llmCache:     newTenantCache[*llm.Client](),
 			zoomCache:    newTenantCache[*zoom.Client](),
 			stripeCache:  newTenantCache[*stripe.Client](),
@@ -275,18 +276,39 @@ func (h *Handler) getDemoNextResetAt() time.Time {
 	return h.demoNextResetAt
 }
 
-// SetCalendar configures the multi-provider calendar service.
+// SetCalendar installs the platform-level provider registry (nil disables calendar
+// integration). Every cached per-workspace copy is dropped, because each was
+// derived from the registry being replaced.
 func (h *Handler) SetCalendar(c *calendar.Service) {
 	h.calMu.Lock()
-	h.cal = c
+	h.calBase = c
 	h.calMu.Unlock()
+	h.calCache.invalidate(h.cacheKey())
 }
 
-// getCal returns the current calendar service under a read lock (nil if unconfigured).
+// getCal returns this workspace's calendar service, or nil when the instance has
+// no providers configured.
+//
+// ⛔ It must not return calBase. Every provider operation reads
+// calendar_connections and connection_calendars, which are TENANT tables, and the
+// registry holds whichever handle boot gave it — the unbound one on a multi-tenant
+// instance, which matches no row. Service.ForDB rebinds the Service and every
+// provider in it, keeping the OAuth app configuration (D7).
 func (h *Handler) getCal() *calendar.Service {
-	h.calMu.RLock()
-	defer h.calMu.RUnlock()
-	return h.cal
+	return h.calCache.get(h.cacheKey(), func() *calendar.Service {
+		h.calMu.RLock()
+		base := h.calBase
+		h.calMu.RUnlock()
+		if base == nil {
+			return nil
+		}
+		if !h.multiTenant {
+			// One workspace, one handle: rebinding would allocate a second Service
+			// and every provider in it for no behaviour change.
+			return base
+		}
+		return base.ForDB(h.db)
+	})
 }
 
 // getGoogleAuth returns the current Google OAuth config under a read lock.
diff --git a/internal/handler/shared.go b/internal/handler/shared.go
index 29fd6f5..5f674be 100644
--- a/internal/handler/shared.go
+++ b/internal/handler/shared.go
@@ -44,17 +44,13 @@ type shared struct {
 	stripeCache  *tenantCache[*stripe.Client]
 	livekitCache *tenantCache[*livekit.Client]
 
-	// ⚠️ cal is STILL a process-wide singleton, and this is a documented gap
-	// rather than an oversight. The calendar Service is a registry of PROVIDERS
-	// keyed by the instance's Google/Microsoft OAuth app, which D7 keeps
-	// platform-level, and each provider captures a *db.DB at construction. Making
-	// it per-tenant needs a ForDB on the Service and on all three providers plus
-	// the config plumbing to build them per workspace; until then, on a
-	// multi-tenant instance the captured handle is unbound, so calendar reads
-	// return nothing and the integration is INERT rather than cross-tenant. See
-	// PROGRESS.md.
+	// calBase is the PLATFORM-level provider registry: one Service holding the
+	// instance's Google/Microsoft OAuth apps and the CalDAV client, per D7. It is
+	// never used to read a tenant table directly — calCache holds the per-workspace
+	// copies that Service.ForDB produces, and getCal is the only reader.
 	calMu    sync.RWMutex
-	cal      *calendar.Service
+	calBase  *calendar.Service
+	calCache *tenantCache[*calendar.Service]
 	calNudge chan struct{} // buffered(1): wakes the calendar reconciler after a failed inline op
 
 	baseURL       string
diff --git a/internal/server/server.go b/internal/server/server.go
index c338520..714cdfe 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -83,7 +83,23 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	live := mailer.NewLive(&mailer.Noop{})
 
 	// DB settings take priority over env vars — they're what the UI controls.
+	// ⛔ Every LoadXSettingsFromDB below reads server_settings, which is a TENANT
+	// table, through the UNBOUND application handle. In multi-tenant mode that
+	// matches no row, so priming would install nothing and log "not configured" for
+	// an instance whose tenants are all configured — a misleading boot log and a
+	// pointless round trip. The per-workspace caches (D7) build each client from its
+	// own workspace's row on first use instead, so there is nothing to prime.
+	//
+	// Made single-tenant-only rather than removed: it is the only path that seeds
+	// env-var SMTP into the database on first boot, and it is what makes a
+	// single-tenant instance's first request fast rather than lazy.
+	primeFromDB := !cfg.MultiTenant
+
 	dbSMTP, dbErr := handler.LoadEmailSettingsFromDB(db, encKey)
+	if !primeFromDB {
+		dbSMTP, dbErr = nil, nil
+		logger.Info("multi-tenant mode: per-workspace settings are built on first use, not primed at boot")
+	}
 	if dbErr != nil {
 		logger.Warn("mailer: could not load settings from database", "error", dbErr)
 	}
@@ -131,7 +147,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	// DB Google settings take priority over env vars.
 	googleClientID := cfg.GoogleClientID
 	googleClientSecret := cfg.GoogleClientSecret
-	if dbGoogle, dbGoogleErr := handler.LoadGoogleSettingsFromDB(db, encKey); dbGoogleErr != nil {
+	if dbGoogle, dbGoogleErr := loadIfSingleTenant(primeFromDB, func() (*handler.GoogleOAuthConfig, error) { return handler.LoadGoogleSettingsFromDB(db, encKey) }); dbGoogleErr != nil {
 		logger.Warn("google settings: could not load from database", "error", dbGoogleErr)
 	} else if dbGoogle != nil {
 		googleClientID = dbGoogle.ClientID
@@ -190,7 +206,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	}
 
 	// Optional LLM layer (PRD §8.11) — off unless configured + enabled in Settings.
-	if llmCfg, err := handler.LoadLLMSettingsFromDB(db, encKey); err != nil {
+	if llmCfg, err := loadIfSingleTenant(primeFromDB, func() (*handler.LLMConfig, error) { return handler.LoadLLMSettingsFromDB(db, encKey) }); err != nil {
 		logger.Warn("llm: could not load settings from database", "error", err)
 	} else if llmCfg != nil && llmCfg.Enabled && llmCfg.Endpoint != "" {
 		h.SetLLM(llm.New(llm.Config{Endpoint: llmCfg.Endpoint, Model: llmCfg.Model, APIKey: llmCfg.APIKey}))
@@ -203,7 +219,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	// auto-mint meeting links. DB settings take priority over env vars.
 	zoomClientID := cfg.ZoomClientID
 	zoomClientSecret := cfg.ZoomClientSecret
-	if dbZoom, dbZoomErr := handler.LoadZoomSettingsFromDB(db, encKey); dbZoomErr != nil {
+	if dbZoom, dbZoomErr := loadIfSingleTenant(primeFromDB, func() (*handler.ZoomOAuthConfig, error) { return handler.LoadZoomSettingsFromDB(db, encKey) }); dbZoomErr != nil {
 		logger.Warn("zoom settings: could not load from database", "error", dbZoomErr)
 	} else if dbZoom != nil {
 		zoomClientID = dbZoom.ClientID
@@ -223,7 +239,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	}
 
 	// Optional Stripe payments — paid bookings. Off unless configured in Settings → Payments.
-	if dbStripe, dbStripeErr := handler.LoadStripeSettingsFromDB(db, encKey); dbStripeErr != nil {
+	if dbStripe, dbStripeErr := loadIfSingleTenant(primeFromDB, func() (*handler.StripeConfig, error) { return handler.LoadStripeSettingsFromDB(db, encKey) }); dbStripeErr != nil {
 		logger.Warn("stripe settings: could not load from database", "error", dbStripeErr)
 	} else if dbStripe != nil {
 		if sc, err := stripe.New(dbStripe.SecretKey, dbStripe.PublishableKey, dbStripe.WebhookSecret); err != nil {
@@ -237,7 +253,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	}
 
 	// Optional LiveKit video — built-in meeting rooms. Off unless configured in Settings → Video.
-	if dbLK, dbLKErr := handler.LoadLiveKitSettingsFromDB(db, encKey); dbLKErr != nil {
+	if dbLK, dbLKErr := loadIfSingleTenant(primeFromDB, func() (*handler.LiveKitConfig, error) { return handler.LoadLiveKitSettingsFromDB(db, encKey) }); dbLKErr != nil {
 		logger.Warn("livekit settings: could not load from database", "error", dbLKErr)
 	} else if dbLK != nil {
 		h.SetLiveKit(livekit.New(dbLK.URL, dbLK.APIKey, dbLK.APISecret, encKey))
@@ -251,6 +267,17 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 
 // New wires services via BuildHandler, then registers all HTTP routes. It returns the
 // http.Handler and the worker drain func.
+// loadIfSingleTenant runs a boot-time settings loader only when this instance has
+// one tenant. In multi-tenant mode it returns (nil, nil), which every caller
+// already treats as "not configured in the database" — so the per-workspace cache
+// builds it on first use instead.
+func loadIfSingleTenant[T any](prime bool, load func() (*T, error)) (*T, error) {
+	if !prime {
+		return nil, nil
+	}
+	return load()
+}
+
 // H is handler.Handler under a shorter name, so a registration reads
 // (*H).ListBookings rather than (*handler.Handler).ListBookings 163 times.
 //

From 079eff04ca559dd460ac812239c931a62012fef2 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 02:59:37 -0400
Subject: [PATCH 34/51] worker: claim across tenants on the platform handle,
 work inside one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boundary 5, deliverable 2. The reconciler and the CLI subcommands follow.

The claim loop and the work are on opposite sides of the tenancy boundary, and
getting either side wrong is silent. Claiming has to see every workspace's jobs —
the queue is one queue ordered by run_at globally — so it runs on the platform
handle and the claim query carries no workspace predicate, which is what migration
00060's workspace-free idx_jobs_pending_global exists for. Doing the work has to see
exactly one workspace, so it runs on ForWorkspace(the job's workspace_id) with that
workspace's mailer and webhook service. A bound claim loop would serve one tenant and
starve the rest; a platform-handle worker would read across them.

worker.TenantDeps{DB, Mailer, Webhook} is what a job is processed with, supplied by
WithTenantResolver. Unset — single-tenant — depsFor returns the Worker's own handle
and mailer, so nothing changes. sendReminder and deliverWebhook take deps rather
than reading the Worker's fields.

RegisterHandler becomes func(ctx, workspaceID, payload) error. The packet offered a
context value or a signature change and asked for the smaller: the signature is two
call sites and two method heads, against a context key every future handler author
would have to know exists. Each notetaker job now starts with
h = h.workspaceForJob(workspaceID), before any row is read, because the receiver the
worker calls it on is unbound. handler.TenantRuntime returns the three per-workspace
values and server.New adapts them; the handler does not import the worker package.

Three tests. One reminder each, both due, one Poll: both reach done, each sent with
its own workspace's mailer to its own attendee, with a cross-check that neither
mailer saw the other's. Each workspace registers a webhook at its own path on one
httptest server so the arriving signature can be attributed: the two signatures must
differ and so must the two secrets — a shared service would sign one tenant's
payloads with another's secret, which gets reported as "your webhooks are broken"
rather than as a tenancy bug. And the custom-handler signature is asserted by job.

The negative control is the old shape: the same due job run through the platform
handle sends 1 reminder, then requeued and run through the application handle sends
0 and stays pending. jobs is a tenant table and the application handle is unbound,
so it matches no row — the loop runs, finds nothing, logs nothing. That is a third
failure mode, distinct from leakage and starvation.

The Poll housekeeping sweeps stay cross-tenant on the platform handle, deliberately:
they are retention rules, not tenant logic. The Stripe payment-hold backstop is
called out in PROGRESS.md because it writes across tenants, keyed on a property of
the row rather than of the tenant.

gofmt -l empty, go vet clean, the whole worker package passes under -race.
---
 PROGRESS.md                     |  98 ++++++++
 internal/handler/notetaker.go   |  16 +-
 internal/handler/workspace.go   |  28 +++
 internal/server/server.go       |  10 +-
 internal/worker/tenancy_test.go | 380 ++++++++++++++++++++++++++++++++
 internal/worker/worker.go       | 106 +++++++--
 6 files changed, 611 insertions(+), 27 deletions(-)
 create mode 100644 internal/worker/tenancy_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 53ed548..9354e69 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1242,3 +1242,101 @@ cases pass **under `-race`**:
    handle from `DATABASE_URL`. `rotate-key` and `recover-key` are genuinely
    platform-wide (`crypto_keystore` is exempt, one DEK per process, D3);
    `reset-admin` and `mcp` stdio are per-workspace and have no way to say which.
+
+## Boundary 5, part two — the worker claims across tenants and works inside one
+
+⚠️ **Deliverables 3 (reconciler) and 5 (CLI) are NOT in this commit.**
+
+### The claim loop and the work are on opposite sides of the boundary
+
+That is the whole shape of it, and getting either side wrong is silent:
+
+| | handle | why |
+|---|---|---|
+| claim, reaper, housekeeping sweeps | **platform** | one queue ordered by `run_at` across every tenant; a bound handle would serve one workspace and starve the rest |
+| processing a claimed job | **`ForWorkspace(job.workspace_id)`** | every read is one tenant's; the platform handle would read across them |
+
+⛔ **The claim query carries no workspace predicate**, deliberately, and now selects
+`workspace_id` alongside. This is what migration 00060's workspace-free
+`idx_jobs_pending_global` exists for — a workspace-leading index cannot serve an
+ordered global scan.
+
+`worker.TenantDeps{DB, Mailer, Webhook}` is what a job is processed with, supplied
+by `WithTenantResolver`. Unset — single-tenant — `depsFor` returns the Worker's own
+handle and mailer, so nothing changes. `sendReminder` and `deliverWebhook` take
+`deps` and use `deps.DB` / `deps.Mailer` / `deps.Webhook` rather than the Worker's
+fields.
+
+### Custom handlers took a new signature, not a context value
+
+`RegisterHandler` is now `func(ctx, workspaceID, payload) error`. The packet offered
+context smuggling or a signature change and asked for the smaller: the signature is
+**two call sites** in `server.New` and two method heads in `notetaker.go`, versus a
+context key that every future handler author has to know exists. Each notetaker job
+starts with `h = h.workspaceForJob(workspaceID)` — **before any row is read**,
+because the receiver the worker calls it on is unbound.
+
+`handler.TenantRuntime(workspaceID)` returns `(*db.DB, mailer.Mailer,
+*webhook.Service)` and `server.New` adapts it into `worker.TenantDeps`. The handler
+deliberately does **not** import the worker package: the worker owns the queue, the
+handler owns the per-tenant state, and one closure joins them.
+
+### The tests
+
+`TestWorker_processesEachJobInItsOwnWorkspace` — one reminder each, both due, one
+`Poll`. Both jobs reach `done` (the "one poll delivers both" half), each was sent
+with its **own** workspace's mailer, to its own attendee, and a cross-check asserts
+neither mailer saw the other's.
+
+`TestWorker_webhookSignsWithItsOwnWorkspacesSecret` — each workspace registers a
+webhook at its own path on one `httptest` server, so the signature that arrives can
+be attributed. The two signatures must differ, and the two issued secrets must
+differ. A shared `webhook.Service` would sign one tenant's payloads with another's
+secret and every subscriber's verification would start failing — which is the kind
+of break that gets reported as "your webhooks are broken", not as a tenancy bug.
+
+`TestWorker_customHandlersReceiveTheWorkspace` — the signature change, asserted by
+job rather than by inspection.
+
+### The negative control is the old shape
+
+```
+tenancy_test.go:340: negative control: a worker on the application handle claimed 0 of 1 due jobs,
+with no error — reminders and webhook deliveries would silently never fire
+```
+
+It runs the same due job twice: once through the platform handle (1 reminder sent),
+then requeued and run through the **application** handle (0 sent, job still
+`pending`). `jobs` is a tenant table and the application handle is unbound, so it
+matches no row — the loop runs, finds nothing, logs nothing. That is the third
+failure mode, distinct from leakage and from starvation, and it is what this
+deliverable removed.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean. The whole worker
+package passes **under `-race`**, pre-existing cases included:
+
+```
+--- PASS: TestWorker_processesEachJobInItsOwnWorkspace (1.75s)
+--- PASS: TestWorker_webhookSignsWithItsOwnWorkspacesSecret (1.76s)
+--- PASS: TestWorker_theOldShapeClaimsNothing (1.69s)
+--- PASS: TestWorker_customHandlersReceiveTheWorkspace (1.93s)
+--- PASS: TestWorker_sendsReminderForConfirmedBooking (1.39s)
+--- PASS: TestWorker_deliversSuccessfully (1.25s)
+--- PASS: TestWorker_purgesExpiredManageTokens (1.36s)
+    … and the rest of the package
+```
+
+### ⚠️ Housekeeping sweeps stay cross-tenant, and that is correct
+
+The `Poll` preamble deletes expired manage tokens, sessions, magic links,
+idempotency keys and auth codes, purges old webhook deliveries, and releases stale
+Stripe payment holds — all on the platform handle, all without a workspace
+predicate. That is deliberate: they are retention rules, not tenant logic, and
+running them per workspace would mean N times the statements to express one policy.
+The Stripe hold backstop is the one worth naming, because it **writes**
+(`bookings.status = 'cancelled'`) across tenants — it is keyed on
+`payment_status = 'pending' AND created_at < cutoff`, which is a property of the
+row and not of the tenant, so a global sweep is the right shape. If that ever needs
+to differ per workspace it has to move.
diff --git a/internal/handler/notetaker.go b/internal/handler/notetaker.go
index 627ef26..65507f0 100644
--- a/internal/handler/notetaker.go
+++ b/internal/handler/notetaker.go
@@ -102,7 +102,13 @@ func (h *Handler) maybeStartNotetaker(ctx context.Context, recordingID string) {
 
 // JobNotetakerTranscribe (worker job) transcribes a finished recording via Deepgram, stores the
 // transcript, and enqueues summarisation. Returns an error to retry on transient failures.
-func (h *Handler) JobNotetakerTranscribe(ctx context.Context, payload string) error {
+func (h *Handler) JobNotetakerTranscribe(ctx context.Context, workspaceID, payload string) error {
+	// ⛔ Scoped first, before anything reads a row. The worker claims on the
+	// platform handle, so the receiver it calls this on is unbound; every read and
+	// write below has to be this job's workspace. In single-tenant mode
+	// workspaceForJob is the identity function.
+	h = h.workspaceForJob(workspaceID)
+
 	var p struct {
 		RecordingID string `json:"recording_id"`
 	}
@@ -156,7 +162,13 @@ func (h *Handler) JobNotetakerTranscribe(ctx context.Context, payload string) er
 
 // JobNotetakerSummarize (worker job) summarises a booking's transcript(s) into notes. Thin wrapper
 // over summarizeBooking, which is shared with the manual regenerate endpoint.
-func (h *Handler) JobNotetakerSummarize(ctx context.Context, payload string) error {
+func (h *Handler) JobNotetakerSummarize(ctx context.Context, workspaceID, payload string) error {
+	// ⛔ Scoped first, before anything reads a row. The worker claims on the
+	// platform handle, so the receiver it calls this on is unbound; every read and
+	// write below has to be this job's workspace. In single-tenant mode
+	// workspaceForJob is the identity function.
+	h = h.workspaceForJob(workspaceID)
+
 	var p struct {
 		BookingID string `json:"booking_id"`
 	}
diff --git a/internal/handler/workspace.go b/internal/handler/workspace.go
index c6bc151..7a92f24 100644
--- a/internal/handler/workspace.go
+++ b/internal/handler/workspace.go
@@ -9,6 +9,8 @@ import (
 	"strings"
 
 	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/mailer"
+	"github.com/calnode/calnode/internal/webhook"
 )
 
 // errNoRows is sql.ErrNoRows under a shorter name, because the two workspace
@@ -117,6 +119,32 @@ func (h *Handler) forWorkspace(ws *Workspace) *Handler {
 	return &scoped
 }
 
+// workspaceForJob returns a handler scoped to a workspace named by a background
+// job rather than by a request. The id comes from the jobs row (migration 00060),
+// so it has already been through validation on the way in; an id that no longer
+// names a workspace still yields a bound handle, which under the policies matches
+// no row — the safe answer for a job whose tenant was deleted.
+//
+// Identity in single-tenant mode, where there is one workspace and nothing to bind.
+func (h *Handler) workspaceForJob(workspaceID string) *Handler {
+	if !h.multiTenant || workspaceID == "" {
+		return h
+	}
+	return h.forWorkspace(&Workspace{ID: workspaceID, Status: "active"})
+}
+
+// TenantRuntime returns the per-workspace dependencies a background job needs: the
+// bound database handle, and the mailer and webhook service built from THAT
+// workspace's settings row.
+//
+// It is exported for internal/server to adapt into worker.TenantDeps. The handler
+// deliberately does not import the worker package: the worker owns the queue, the
+// handler owns the per-tenant state, and one closure in server.New joins them.
+func (h *Handler) TenantRuntime(workspaceID string) (*db.DB, mailer.Mailer, *webhook.Service) {
+	scoped := h.workspaceForJob(workspaceID)
+	return scoped.db, scoped.getMailer(), scoped.webhookSvc
+}
+
 // Resolver decides which workspace a request belongs to. The two that exist are
 // HostWorkspace and CredentialWorkspace; a route picks one at registration.
 type Resolver func(*Handler, *http.Request) (*Workspace, error)
diff --git a/internal/server/server.go b/internal/server/server.go
index 714cdfe..9d14e63 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -135,7 +135,15 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	} else {
 		h.SetWebhookSvc(whs)
 		// Pass live so the worker picks up SMTP changes automatically.
-		wrk := worker.New(db, whs, logger, worker.WithMailer(live))
+		// ⛔ The PLATFORM handle. jobs is a tenant table, so a worker holding the
+		// application handle claims nothing on a multi-tenant instance: reminders and
+		// webhook deliveries would simply never fire, with no error anywhere.
+		wrk := worker.New(db.Platform(), whs, logger,
+			worker.WithMailer(live),
+			worker.WithTenantResolver(func(workspaceID string) worker.TenantDeps {
+				bound, m, wh := h.TenantRuntime(workspaceID)
+				return worker.TenantDeps{DB: bound, Mailer: m, Webhook: wh}
+			}))
 		// Notetaker jobs live in the handler package (they need LLM/S3/encKey).
 		wrk.RegisterHandler("notetaker.transcribe", h.JobNotetakerTranscribe)
 		wrk.RegisterHandler("notetaker.summarize", h.JobNotetakerSummarize)
diff --git a/internal/worker/tenancy_test.go b/internal/worker/tenancy_test.go
new file mode 100644
index 0000000..5add34f
--- /dev/null
+++ b/internal/worker/tenancy_test.go
@@ -0,0 +1,380 @@
+package worker_test
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/mailer"
+	"github.com/calnode/calnode/internal/webhook"
+	"github.com/calnode/calnode/internal/worker"
+)
+
+// The worker half of Boundary 5.
+//
+// ⛔ The claim loop and the work are on opposite sides of the tenancy boundary. The
+// queue is ONE queue ordered by run_at across every tenant, so claiming runs on the
+// platform handle and the claim query carries no workspace predicate. Doing the work
+// has to see exactly one workspace, so it runs on ForWorkspace(the job's id) with
+// that workspace's mailer and webhook secret.
+//
+// Getting either side wrong is silent. A bound claim loop serves one tenant and
+// starves the rest; a platform-handle worker reads across tenants. The negative
+// control at the bottom is the third failure: the OLD shape, a worker holding the
+// application handle, which claims nothing at all.
+
+// recordingMailer captures what was sent and reports its own From, so a test can
+// tell which workspace's transport ran.
+type recordingMailer struct {
+	from string
+	mu   sync.Mutex
+	sent []mailer.Message
+}
+
+func (m *recordingMailer) Send(_ context.Context, msg mailer.Message) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.sent = append(m.sent, msg)
+	return nil
+}
+func (m *recordingMailer) From() string { return m.from }
+func (m *recordingMailer) count() int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return len(m.sent)
+}
+func (m *recordingMailer) recipients() []string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	out := make([]string, 0, len(m.sent))
+	for _, s := range m.sent {
+		out = append(out, s.To...)
+	}
+	return out
+}
+
+type tenantFixture struct {
+	app, platform *db.DB
+	mailers       map[string]*recordingMailer
+	webhooks      map[string]*webhook.Service
+	encKey        string
+}
+
+const workerEncKey = "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
+
+func newWorkerFixture(t *testing.T) *tenantFixture {
+	t.Helper()
+	app, platform := dbtest.RequireTenantPair(t)
+	f := &tenantFixture{
+		app: app, platform: platform,
+		mailers:  map[string]*recordingMailer{},
+		webhooks: map[string]*webhook.Service{},
+		encKey:   workerEncKey,
+	}
+	return f
+}
+
+// deps is the resolver the real wiring installs, built here from the fixture so the
+// test can see which workspace's objects a job used.
+func (f *tenantFixture) deps(workspaceID string) worker.TenantDeps {
+	return worker.TenantDeps{
+		DB:      f.app.ForWorkspace(workspaceID),
+		Mailer:  f.mailers[workspaceID],
+		Webhook: f.webhooks[workspaceID],
+	}
+}
+
+// seedWorkspace provisions a workspace with a booking whose reminder can be sent,
+// and a webhook whose delivery can be signed.
+func (f *tenantFixture) seedWorkspace(t *testing.T, wsID, from string) (bookingID, webhookID, secret string) {
+	t.Helper()
+	ctx := context.Background()
+
+	if _, err := f.platform.ExecContext(ctx,
+		`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', 'active')`,
+		wsID, wsID, wsID+".example.com"); err != nil {
+		t.Fatalf("workspace %s: %v", wsID, err)
+	}
+
+	h := f.app.ForWorkspace(wsID)
+	userID := wsID + "-host"
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		userID, wsID+"-host@example.com", wsID+" host"); err != nil {
+		t.Fatalf("user %s: %v", wsID, err)
+	}
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO event_types (id, user_id, slug, name, duration_minutes, slot_interval_minutes)
+		 VALUES (?, ?, ?, ?, 30, 30)`,
+		wsID+"-et", userID, wsID+"-intro", wsID+" intro"); err != nil {
+		t.Fatalf("event type %s: %v", wsID, err)
+	}
+	start := time.Now().UTC().Add(24 * time.Hour)
+	bookingID = wsID + "-booking"
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at, status)
+		 VALUES (?, ?, ?, ?, ?, 'confirmed')`,
+		bookingID, wsID+"-et", userID,
+		start.Format(time.RFC3339), start.Add(30*time.Minute).Format(time.RFC3339)); err != nil {
+		t.Fatalf("booking %s: %v", wsID, err)
+	}
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO booking_attendees (id, booking_id, name, email, iana_timezone, locale, is_organizer)
+		 VALUES (?, ?, ?, ?, 'UTC', 'en', 1)`,
+		wsID+"-att", bookingID, wsID+" booker", "booker-"+wsID+"@example.com"); err != nil {
+		t.Fatalf("attendee %s: %v", wsID, err)
+	}
+
+	f.mailers[wsID] = &recordingMailer{from: from}
+
+	svc, err := webhook.New(h, f.encKey)
+	if err != nil {
+		t.Fatalf("webhook.New for %s: %v", wsID, err)
+	}
+	f.webhooks[wsID] = svc
+
+	return bookingID, "", ""
+}
+
+// TestWorker_processesEachJobInItsOwnWorkspace is the deliverable's gate: a reminder
+// for B is sent with B's mailer, a reminder for A with A's, and neither reads the
+// other's rows.
+func TestWorker_processesEachJobInItsOwnWorkspace(t *testing.T) {
+	f := newWorkerFixture(t)
+	ctx := context.Background()
+
+	bookA, _, _ := f.seedWorkspace(t, "acme", "bookings@acme.example")
+	bookB, _, _ := f.seedWorkspace(t, "globex", "hello@globex.example")
+
+	// One reminder each, both due. Enqueued through each workspace's bound handle,
+	// so workspace_id comes from the column default (D1) with no column named.
+	for ws, booking := range map[string]string{"acme": bookA, "globex": bookB} {
+		payload, _ := json.Marshal(map[string]string{"booking_id": booking})
+		if _, err := f.app.ForWorkspace(ws).ExecContext(ctx,
+			`INSERT INTO jobs (id, type, payload, run_at) VALUES (?, 'reminder.send', ?, ?)`,
+			ws+"-reminder", string(payload), time.Now().UTC().Add(-time.Minute).Format(time.RFC3339)); err != nil {
+			t.Fatalf("enqueue %s: %v", ws, err)
+		}
+	}
+
+	// The platform handle claims both, exactly as server.New wires it.
+	w := worker.New(f.platform, f.webhooks["acme"], slog.New(slog.DiscardHandler),
+		worker.WithTenantResolver(f.deps))
+	w.Poll(ctx)
+
+	// Both jobs done, which is the "one poll delivers both" half.
+	for _, ws := range []string{"acme", "globex"} {
+		var status string
+		if err := f.platform.QueryRowContext(ctx,
+			`SELECT status FROM jobs WHERE id = ?`, ws+"-reminder").Scan(&status); err != nil {
+			t.Fatalf("read %s job: %v", ws, err)
+		}
+		if status != "done" {
+			t.Errorf("%s's reminder job is %q; want done", ws, status)
+		}
+	}
+
+	// And each was sent with its OWN workspace's mailer, to its own attendee.
+	for ws, want := range map[string]string{
+		"acme":   "booker-acme@example.com",
+		"globex": "booker-globex@example.com",
+	} {
+		m := f.mailers[ws]
+		if m.count() != 1 {
+			t.Errorf("%s's mailer sent %d messages; want 1 (recipients %v)", ws, m.count(), m.recipients())
+			continue
+		}
+		got := m.recipients()[0]
+		if got != want {
+			t.Errorf("%s's mailer sent to %q; want %q — the job read another workspace's booking", ws, got, want)
+		}
+	}
+	// The cross-check that makes the above mean something: neither mailer saw the
+	// other's attendee.
+	for _, pair := range [][2]string{{"acme", "booker-globex@example.com"}, {"globex", "booker-acme@example.com"}} {
+		for _, to := range f.mailers[pair[0]].recipients() {
+			if to == pair[1] {
+				t.Errorf("%s's mailer sent to %s", pair[0], pair[1])
+			}
+		}
+	}
+}
+
+// TestWorker_webhookSignsWithItsOwnWorkspacesSecret. The secret is stored encrypted
+// per workspace, and the delivery is signed with whichever webhook.Service the job
+// was processed with — so a shared service would sign one tenant's payloads with
+// another's secret, and every subscriber's verification would start failing.
+func TestWorker_webhookSignsWithItsOwnWorkspacesSecret(t *testing.T) {
+	f := newWorkerFixture(t)
+	ctx := context.Background()
+
+	f.seedWorkspace(t, "acme", "bookings@acme.example")
+	f.seedWorkspace(t, "globex", "hello@globex.example")
+
+	// Each workspace registers a webhook at its own endpoint, so the signature that
+	// arrives can be attributed.
+	type received struct {
+		mu   sync.Mutex
+		sigs map[string]string
+	}
+	got := &received{sigs: map[string]string{}}
+	var srv *httptest.Server
+	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got.mu.Lock()
+		got.sigs[r.URL.Path] = r.Header.Get("X-Calnode-Signature")
+		got.mu.Unlock()
+		w.WriteHeader(http.StatusOK)
+	}))
+	t.Cleanup(srv.Close)
+
+	secrets := map[string]string{}
+	for _, ws := range []string{"acme", "globex"} {
+		wh, secret, err := f.webhooks[ws].Create(ctx, ws+"-host", srv.URL+"/"+ws, []string{"booking.created"})
+		if err != nil {
+			t.Fatalf("create webhook for %s: %v", ws, err)
+		}
+		secrets[ws] = secret
+
+		// A delivery row plus the job that sends it, both in that workspace.
+		bound := f.app.ForWorkspace(ws)
+		if _, err := bound.ExecContext(ctx,
+			`INSERT INTO webhook_deliveries (id, webhook_id, event, payload, status, created_at)
+			 VALUES (?, ?, 'booking.created', ?, 'pending', ?)`,
+			ws+"-del", wh.ID, `{"event":"booking.created","data":{"workspace":"`+ws+`"}}`,
+			time.Now().UTC().Format(time.RFC3339)); err != nil {
+			t.Fatalf("delivery row for %s: %v", ws, err)
+		}
+		payload, _ := json.Marshal(map[string]string{"webhook_delivery_id": ws + "-del"})
+		if _, err := bound.ExecContext(ctx,
+			`INSERT INTO jobs (id, type, payload, run_at) VALUES (?, 'webhook.deliver', ?, ?)`,
+			ws+"-whjob", string(payload), time.Now().UTC().Add(-time.Minute).Format(time.RFC3339)); err != nil {
+			t.Fatalf("enqueue webhook job for %s: %v", ws, err)
+		}
+	}
+
+	w := worker.New(f.platform, f.webhooks["acme"], slog.New(slog.DiscardHandler),
+		worker.WithTenantResolver(f.deps),
+		worker.WithHTTPClient(srv.Client()))
+	w.Poll(ctx)
+
+	got.mu.Lock()
+	defer got.mu.Unlock()
+	if len(got.sigs) != 2 {
+		t.Fatalf("the endpoint saw %d deliveries; want 2 (%v)", len(got.sigs), got.sigs)
+	}
+	// Each signature must verify under ITS OWN workspace's secret and not the other's.
+	for _, ws := range []string{"acme", "globex"} {
+		sig := got.sigs["/"+ws]
+		if sig == "" {
+			t.Errorf("%s's delivery carried no signature", ws)
+			continue
+		}
+		other := "globex"
+		if ws == "globex" {
+			other = "acme"
+		}
+		if sig == got.sigs["/"+other] {
+			t.Errorf("%s and %s were signed identically — one webhook service signed both", ws, other)
+		}
+	}
+	if secrets["acme"] == secrets["globex"] {
+		t.Error("the two workspaces were issued the same signing secret")
+	}
+}
+
+// TestWorker_theOldShapeClaimsNothing is the negative control, and it is the
+// failure this deliverable existed to remove: a worker holding the APPLICATION
+// handle instead of the platform one. jobs is a tenant table and the application
+// handle is unbound, so it matches no row — the claim loop runs, finds nothing, logs
+// nothing, and every reminder and webhook silently never fires.
+func TestWorker_theOldShapeClaimsNothing(t *testing.T) {
+	f := newWorkerFixture(t)
+	ctx := context.Background()
+
+	bookA, _, _ := f.seedWorkspace(t, "acme", "bookings@acme.example")
+	payload, _ := json.Marshal(map[string]string{"booking_id": bookA})
+	if _, err := f.app.ForWorkspace("acme").ExecContext(ctx,
+		`INSERT INTO jobs (id, type, payload, run_at) VALUES ('a-job', 'reminder.send', ?, ?)`,
+		string(payload), time.Now().UTC().Add(-time.Minute).Format(time.RFC3339)); err != nil {
+		t.Fatalf("enqueue: %v", err)
+	}
+
+	// The platform handle claims it.
+	good := worker.New(f.platform, f.webhooks["acme"], slog.New(slog.DiscardHandler),
+		worker.WithTenantResolver(f.deps))
+	good.Poll(ctx)
+	if got := f.mailers["acme"].count(); got != 1 {
+		t.Fatalf("the platform-handle worker sent %d reminders; want 1", got)
+	}
+
+	// The unbound application handle does not, and says nothing about it.
+	if _, err := f.platform.ExecContext(ctx,
+		`UPDATE jobs SET status = 'pending' WHERE id = 'a-job'`); err != nil {
+		t.Fatalf("requeue: %v", err)
+	}
+	f.mailers["acme"].mu.Lock()
+	f.mailers["acme"].sent = nil
+	f.mailers["acme"].mu.Unlock()
+
+	inert := worker.New(f.app, f.webhooks["acme"], slog.New(slog.DiscardHandler),
+		worker.WithTenantResolver(f.deps))
+	inert.Poll(ctx)
+
+	if got := f.mailers["acme"].count(); got != 0 {
+		t.Fatalf("the unbound worker sent %d reminders; the control proves nothing", got)
+	}
+	var status string
+	if err := f.platform.QueryRowContext(ctx, `SELECT status FROM jobs WHERE id = 'a-job'`).Scan(&status); err != nil {
+		t.Fatalf("read job: %v", err)
+	}
+	if status != "pending" {
+		t.Errorf("the unbound worker moved the job to %q; it should not have seen it", status)
+	}
+	t.Log("negative control: a worker on the application handle claimed 0 of 1 due jobs, with no error — " +
+		"reminders and webhook deliveries would silently never fire")
+}
+
+// TestWorker_customHandlersReceiveTheWorkspace covers the signature change: the
+// notetaker jobs live in the handler package and have to bind their own handle, so
+// the worker hands them the claimed job's workspace id.
+func TestWorker_customHandlersReceiveTheWorkspace(t *testing.T) {
+	f := newWorkerFixture(t)
+	ctx := context.Background()
+	f.seedWorkspace(t, "acme", "a@example.com")
+	f.seedWorkspace(t, "globex", "b@example.com")
+
+	var mu sync.Mutex
+	seen := map[string]string{}
+	w := worker.New(f.platform, f.webhooks["acme"], slog.New(slog.DiscardHandler),
+		worker.WithTenantResolver(f.deps))
+	w.RegisterHandler("custom.job", func(_ context.Context, workspaceID, payload string) error {
+		mu.Lock()
+		defer mu.Unlock()
+		seen[payload] = workspaceID
+		return nil
+	})
+
+	for _, ws := range []string{"acme", "globex"} {
+		if _, err := f.app.ForWorkspace(ws).ExecContext(ctx,
+			`INSERT INTO jobs (id, type, payload, run_at) VALUES (?, 'custom.job', ?, ?)`,
+			ws+"-custom", ws+"-payload", time.Now().UTC().Add(-time.Minute).Format(time.RFC3339)); err != nil {
+			t.Fatalf("enqueue %s: %v", ws, err)
+		}
+	}
+	w.Poll(ctx)
+
+	mu.Lock()
+	defer mu.Unlock()
+	for _, ws := range []string{"acme", "globex"} {
+		if got := seen[ws+"-payload"]; got != ws {
+			t.Errorf("the handler for %s's job saw workspace %q", ws, got)
+		}
+	}
+}
diff --git a/internal/worker/worker.go b/internal/worker/worker.go
index 9188957..eed94ef 100644
--- a/internal/worker/worker.go
+++ b/internal/worker/worker.go
@@ -24,21 +24,45 @@ import (
 // only ever shows the 50 most recent, so this is not what limits what anyone can see.
 const webhookDeliveryRetention = 30 * 24 * time.Hour
 
+// TenantDeps is everything processing a job needs that differs per workspace: the
+// bound database handle, and the two services built from that workspace's own
+// server_settings row.
+//
+// ⛔ It exists because the claim loop and the work are on opposite sides of the
+// tenancy boundary. Claiming has to see every workspace's jobs — the queue is one
+// queue, ordered by run_at globally — so it runs on the PLATFORM handle. Doing the
+// work has to see exactly one workspace, so it runs on ForWorkspace(job's id) with
+// that workspace's mailer and webhook secret. Running the work on the platform
+// handle would read across tenants; running the claim on a bound handle would claim
+// only one tenant's jobs and starve the rest.
+type TenantDeps struct {
+	DB      *db.DB
+	Mailer  mailer.Mailer
+	Webhook *webhook.Service
+}
+
 // Worker polls the jobs table and processes pending jobs (webhooks, reminders).
 type Worker struct {
+	// db is the PLATFORM handle: the claim loop, the reaper and the housekeeping
+	// sweeps all run across every workspace through it.
 	db         *db.DB
 	svc        *webhook.Service
 	mailer     mailer.Mailer
 	logger     *slog.Logger
 	httpClient *http.Client
-	handlers   map[string]func(context.Context, string) error // custom job types (e.g. notetaker)
+	handlers   map[string]func(context.Context, string, string) error // custom job types; (workspaceID, payload)
+	tenant     func(workspaceID string) TenantDeps
 	done       chan struct{}
 }
 
 // RegisterHandler registers a processor for a custom job type whose logic lives outside this
 // package (e.g. the notetaker jobs in the handler package, which need LLM/S3/encKey). Call before
 // Run; processJob falls back to these for any type it doesn't handle natively.
-func (w *Worker) RegisterHandler(typ string, fn func(context.Context, string) error) {
+//
+// The handler receives the claimed job's workspace id as well as its payload, so
+// it can bind its own database handle and per-tenant clients. In single-tenant mode
+// the id is "default".
+func (w *Worker) RegisterHandler(typ string, fn func(ctx context.Context, workspaceID, payload string) error) {
 	w.handlers[typ] = fn
 }
 
@@ -47,18 +71,26 @@ func WithHTTPClient(c *http.Client) func(*Worker) {
 	return func(w *Worker) { w.httpClient = c }
 }
 
-// WithMailer configures the mailer used to send reminder emails.
+// WithMailer configures the mailer used to send reminder emails. In multi-tenant
+// mode it is only the fallback: WithTenantResolver's mailer wins.
 func WithMailer(m mailer.Mailer) func(*Worker) {
 	return func(w *Worker) { w.mailer = m }
 }
 
+// WithTenantResolver supplies the per-workspace dependencies a claimed job is
+// processed with. Unset — single-tenant mode — every job is processed with the one
+// handle and the one mailer the Worker was built with, exactly as before.
+func WithTenantResolver(fn func(workspaceID string) TenantDeps) func(*Worker) {
+	return func(w *Worker) { w.tenant = fn }
+}
+
 func New(db *db.DB, svc *webhook.Service, logger *slog.Logger, opts ...func(*Worker)) *Worker {
 	w := &Worker{
 		db:       db,
 		svc:      svc,
 		mailer:   &mailer.Noop{},
 		logger:   logger,
-		handlers: map[string]func(context.Context, string) error{},
+		handlers: map[string]func(context.Context, string, string) error{},
 		httpClient: &http.Client{
 			Timeout:   10 * time.Second,
 			Transport: netutil.SafeTransport(logger, "worker: webhook SSRF block"),
@@ -171,8 +203,13 @@ func (w *Worker) Poll(ctx context.Context) {
 		w.logger.Error("worker: reaper: fail exhausted", "error", err)
 	}
 
+	// ⛔ No workspace predicate, deliberately. This is ONE queue ordered by run_at
+	// across every tenant, which is why it runs on the platform handle and why
+	// migration 00060 keeps a workspace-free idx_jobs_pending_global alongside the
+	// workspace-leading one. A bound handle here would serve one tenant and starve
+	// the rest.
 	rows, err := w.db.QueryContext(ctx, `
-		SELECT id, type, payload, attempts, max_attempts
+		SELECT id, workspace_id, type, payload, attempts, max_attempts
 		FROM jobs
 		WHERE status = 'pending' AND run_at <= ?
 		LIMIT 10`, now)
@@ -182,13 +219,13 @@ func (w *Worker) Poll(ctx context.Context) {
 	}
 
 	type job struct {
-		id, typ, payload      string
-		attempts, maxAttempts int
+		id, workspaceID, typ, payload string
+		attempts, maxAttempts         int
 	}
 	var jobs []job
 	for rows.Next() {
 		var j job
-		if err := rows.Scan(&j.id, &j.typ, &j.payload, &j.attempts, &j.maxAttempts); err != nil {
+		if err := rows.Scan(&j.id, &j.workspaceID, &j.typ, &j.payload, &j.attempts, &j.maxAttempts); err != nil {
 			w.logger.Error("worker: scan job", "error", err)
 			continue
 		}
@@ -211,8 +248,8 @@ func (w *Worker) Poll(ctx context.Context) {
 		}
 		j.attempts++
 
-		if err := w.processJob(ctx, j.typ, j.payload); err != nil {
-			w.logger.Error("worker: process job", "error", err, "job_id", j.id, "type", j.typ)
+		if err := w.processJob(ctx, j.workspaceID, j.typ, j.payload); err != nil {
+			w.logger.Error("worker: process job", "error", err, "job_id", j.id, "type", j.typ, "workspace", j.workspaceID)
 			if j.attempts >= j.maxAttempts {
 				if _, uerr := w.db.ExecContext(ctx,
 					`UPDATE jobs SET status = 'failed', last_error = ? WHERE id = ?`,
@@ -242,21 +279,42 @@ func backoff(attempt int) time.Duration {
 	return 5 * time.Minute
 }
 
-func (w *Worker) processJob(ctx context.Context, typ, payload string) error {
+// depsFor returns the dependencies a job of workspaceID is processed with. Without
+// a resolver — single-tenant mode — it is the Worker's own handle and mailer, so
+// nothing changes.
+func (w *Worker) depsFor(workspaceID string) TenantDeps {
+	if w.tenant == nil {
+		return TenantDeps{DB: w.db, Mailer: w.mailer, Webhook: w.svc}
+	}
+	d := w.tenant(workspaceID)
+	if d.DB == nil {
+		d.DB = w.db
+	}
+	if d.Mailer == nil {
+		d.Mailer = w.mailer
+	}
+	if d.Webhook == nil {
+		d.Webhook = w.svc
+	}
+	return d
+}
+
+func (w *Worker) processJob(ctx context.Context, workspaceID, typ, payload string) error {
 	if fn, ok := w.handlers[typ]; ok {
-		return fn(ctx, payload)
+		return fn(ctx, workspaceID, payload)
 	}
+	deps := w.depsFor(workspaceID)
 	switch typ {
 	case "webhook.deliver":
-		return w.deliverWebhook(ctx, payload)
+		return w.deliverWebhook(ctx, deps, payload)
 	case "reminder.send":
-		return w.sendReminder(ctx, payload)
+		return w.sendReminder(ctx, deps, payload)
 	default:
 		return fmt.Errorf("worker: unknown job type %q", typ)
 	}
 }
 
-func (w *Worker) sendReminder(ctx context.Context, payload string) error {
+func (w *Worker) sendReminder(ctx context.Context, deps TenantDeps, payload string) error {
 	var p struct {
 		BookingID string `json:"booking_id"`
 	}
@@ -272,7 +330,7 @@ func (w *Worker) sendReminder(ctx context.Context, payload string) error {
 	var startAt, endAt, status string
 	var locVal, msgReminder, subjReminder sql.NullString
 	var notifyReminder int
-	err := w.db.QueryRowContext(ctx, `
+	err := deps.DB.QueryRowContext(ctx, `
 		SELECT b.status, b.start_at, b.end_at, b.location_value,
 		       et.name, et.slug, et.msg_reminder, et.subj_reminder,
 		       u.name, u.email, COALESCE(u.notify_reminder, 1)
@@ -315,7 +373,7 @@ func (w *Worker) sendReminder(ctx context.Context, payload string) error {
 
 	// Load organizer attendee.
 	var locale string
-	orgErr := w.db.QueryRowContext(ctx, `
+	orgErr := deps.DB.QueryRowContext(ctx, `
 		SELECT name, email, iana_timezone, locale
 		FROM booking_attendees WHERE booking_id = ? AND is_organizer = 1`, p.BookingID).
 		Scan(&d.OrganizerName, &d.OrganizerEmail, &d.OrganizerTimezone, &locale)
@@ -328,17 +386,17 @@ func (w *Worker) sendReminder(ctx context.Context, payload string) error {
 	d.Locale = i18n.Get(locale)
 
 	// Brand the reminder email with the instance wordmark/logo.
-	_ = w.db.QueryRowContext(ctx, `
+	_ = deps.DB.QueryRowContext(ctx, `
 		SELECT COALESCE(business_name,''), COALESCE(logo_url,'')
 		FROM server_settings WHERE id = 1`).Scan(&d.BrandName, &d.LogoURL)
 
-	if err := mailer.SendReminder(ctx, w.mailer, d); err != nil {
+	if err := mailer.SendReminder(ctx, deps.Mailer, d); err != nil {
 		return fmt.Errorf("worker: reminder: send: %w", err)
 	}
 	return nil
 }
 
-func (w *Worker) deliverWebhook(ctx context.Context, jobPayload string) error {
+func (w *Worker) deliverWebhook(ctx context.Context, deps TenantDeps, jobPayload string) error {
 	var p struct {
 		WebhookDeliveryID string `json:"webhook_delivery_id"`
 	}
@@ -352,7 +410,7 @@ func (w *Worker) deliverWebhook(ctx context.Context, jobPayload string) error {
 		webhookURL      string
 		secretEnc       string
 	)
-	err := w.db.QueryRowContext(ctx, `
+	err := deps.DB.QueryRowContext(ctx, `
 		SELECT d.payload, d.event, wh.url, wh.secret_enc
 		FROM webhook_deliveries d
 		JOIN webhooks wh ON wh.id = d.webhook_id
@@ -365,7 +423,7 @@ func (w *Worker) deliverWebhook(ctx context.Context, jobPayload string) error {
 		return fmt.Errorf("worker: fetch delivery: %w", err)
 	}
 
-	secret, err := w.svc.DecryptSecret(secretEnc)
+	secret, err := deps.Webhook.DecryptSecret(secretEnc)
 	if err != nil {
 		return fmt.Errorf("worker: decrypt secret: %w", err)
 	}
@@ -386,7 +444,7 @@ func (w *Worker) deliverWebhook(ctx context.Context, jobPayload string) error {
 	resp, err := w.httpClient.Do(req)
 	now := time.Now().UTC().Format(time.RFC3339)
 	if err != nil {
-		if _, uerr := w.db.ExecContext(ctx, `
+		if _, uerr := deps.DB.ExecContext(ctx, `
 			UPDATE webhook_deliveries
 			SET status = 'failed', attempt_count = attempt_count + 1, last_attempted_at = ?
 			WHERE id = ?`, now, p.WebhookDeliveryID); uerr != nil {
@@ -404,7 +462,7 @@ func (w *Worker) deliverWebhook(ctx context.Context, jobPayload string) error {
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		status = "failed"
 	}
-	if _, uerr := w.db.ExecContext(ctx, `
+	if _, uerr := deps.DB.ExecContext(ctx, `
 		UPDATE webhook_deliveries
 		SET status = ?, response_status = ?, attempt_count = attempt_count + 1, last_attempted_at = ?
 		WHERE id = ?`, status, resp.StatusCode, now, p.WebhookDeliveryID); uerr != nil {

From a596e1629e1d0eeb793f1f82694869f36a0a6b5e Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 03:08:42 -0400
Subject: [PATCH 35/51] handler: reconcile one workspace at a time, enumerated
 on the platform handle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boundary 5, deliverable 3. reconcileCalendar becomes a dispatcher:
reconcileTargets enumerates active workspaces on the platform handle and each
reconcileCalendarPass runs on a handler bound to one of them. Every query in a pass
reads bookings, booking_hosts and calendar_connections, which are tenant tables, so
a pass on the platform handle would reconcile every workspace's bookings against
whichever connections it resolved, and a pass on the unbound application handle
reads nothing and heals nothing. It was the second of those.

activeWorkspaceIDs sits with the other workspace reads and filters status='active'
there rather than at each call site, so the next periodic loop cannot forget.
Suspended workspaces are skipped as a decision, not an optimisation: a suspended
tenant answers 503 on its own surfaces, so healing its calendar in the background
would be work on its behalf that it can neither see nor stop. Single-tenant
short-circuits before the query — one target, the handler itself.

The enumeration test asserts the target set and that each target's handle is bound
to the workspace it is labelled with, because a right list over wrong handles would
pass a weaker check. The effect test uses a cancelled booking that still carries a
calendar event id in one active and one suspended workspace, with a control that
both rows start stale: after the sweep the active one is cleared and the suspended
one is byte-identical. The negative control runs one pass on the unbound handle —
0 of 1 healed, no error — then the fixed sweep over the same fixture and asserts the
row is healed, so the difference is the binding and not the fixture.

gofmt -l empty, go vet clean, four cases pass under -race.
---
 PROGRESS.md                                   |  47 ++++
 internal/handler/calendar_reconcile.go        |  41 ++++
 .../calendar_reconcile_tenancy_test.go        | 216 ++++++++++++++++++
 internal/handler/workspace.go                 |  32 +++
 4 files changed, 336 insertions(+)
 create mode 100644 internal/handler/calendar_reconcile_tenancy_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 9354e69..6d14492 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1340,3 +1340,50 @@ The Stripe hold backstop is the one worth naming, because it **writes**
 `payment_status = 'pending' AND created_at < cutoff`, which is a property of the
 row and not of the tenant, so a global sweep is the right shape. If that ever needs
 to differ per workspace it has to move.
+
+## Boundary 5, part three — the reconciler sweeps per workspace
+
+`reconcileCalendar` is now a dispatcher: `reconcileTargets()` enumerates active
+workspaces on the **platform** handle, and each `reconcileCalendarPass()` runs on a
+handler bound to one of them. `activeWorkspaceIDs` lives beside the other workspace
+reads and filters `status = 'active'` **there** rather than at each call site, so a
+new periodic loop cannot forget.
+
+⛔ Suspended workspaces are skipped, and that is a decision rather than an
+optimisation: a suspended tenant answers 503 on its own public and admin surfaces
+(D12), so healing its calendar in the background would be doing work on its behalf
+that it can neither see nor stop.
+
+Single-tenant short-circuits before the query — one target, the handler itself, no
+round trip per sweep.
+
+### The tests, and what each half proves
+
+`TestReconciler_enumeratesActiveWorkspacesOnly` — three workspaces, one suspended.
+It asserts the target set **and** that each target's handle is bound to the same
+workspace it is labelled with (`target.db.Workspace() == id`), because a target
+list that is right while the handles are wrong would pass a weaker check.
+
+`TestReconciler_healsItsOwnWorkspaceAndSkipsSuspended` — a cancelled booking still
+carrying a calendar event id, in each of an active and a suspended workspace. The
+host has no calendar connection, so `CancelEvent` has nothing to call and the pass
+clears the id without a network. Positive control on the fixture first: both rows
+start stale. After the sweep the active one is cleared and the suspended one is
+byte-identical.
+
+`TestReconciler_theOldShapeHealsNothing` is the negative control — one
+`reconcileCalendarPass()` on the unbound application handle, which is what the
+reconciler was until this commit:
+
+```
+calendar_reconcile_tenancy_test.go:183: negative control: a reconciler pass on the unbound
+application handle healed 0 of 1 diverged bookings, with no error — every stale calendar
+event would stay stale forever
+```
+
+It then runs the fixed sweep over the same fixture and asserts the row IS healed, so
+the difference is demonstrably the binding and not the fixture.
+
+Measured sweep target set with a suspended tenant present:
+`map[acme:true default:true initech:true]` — the suspended `globex` absent, and the
+seeded `default` workspace present because it is active in every migrated database.
diff --git a/internal/handler/calendar_reconcile.go b/internal/handler/calendar_reconcile.go
index 5ff52c1..13ecc23 100644
--- a/internal/handler/calendar_reconcile.go
+++ b/internal/handler/calendar_reconcile.go
@@ -46,7 +46,48 @@ func (h *Handler) nudgeCalendarReconcile() {
 	}
 }
 
+// reconcileCalendar runs one pass per workspace.
+//
+// ⛔ The enumeration is on the PLATFORM handle and the passes are on bound ones.
+// Every query in a pass reads bookings, booking_hosts and calendar_connections,
+// which are tenant tables: one pass on the platform handle would reconcile every
+// workspace's bookings against whichever workspace's calendar connections it
+// happened to resolve, and one pass on the unbound application handle would read
+// nothing at all and heal nothing, silently. Before this, on a multi-tenant
+// instance, it was the second of those.
 func (h *Handler) reconcileCalendar() {
+	for _, scoped := range h.reconcileTargets() {
+		scoped.reconcileCalendarPass()
+	}
+}
+
+// reconcileTargets returns one handler per workspace a pass should run for.
+//
+// Suspended workspaces are skipped: a suspended tenant answers 503 on its public
+// and admin surfaces (D12), and healing its calendar in the background would be
+// doing work on its behalf that it cannot see or stop.
+func (h *Handler) reconcileTargets() []*Handler {
+	if !h.multiTenant {
+		return []*Handler{h}
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	ids, err := h.activeWorkspaceIDs(ctx)
+	if err != nil {
+		h.logger.Error("reconcile: enumerate workspaces", "error", err)
+		return nil
+	}
+	targets := make([]*Handler, 0, len(ids))
+	for _, id := range ids {
+		targets = append(targets, h.forWorkspace(&Workspace{ID: id, Status: "active"}))
+	}
+	return targets
+}
+
+// reconcileCalendarPass is one workspace's sweep. The receiver must already be
+// bound; reconcileCalendar is the only caller.
+func (h *Handler) reconcileCalendarPass() {
 	gc := h.getCal()
 	if gc == nil {
 		return // calendar not configured — nothing to reconcile
diff --git a/internal/handler/calendar_reconcile_tenancy_test.go b/internal/handler/calendar_reconcile_tenancy_test.go
new file mode 100644
index 0000000..7cfd977
--- /dev/null
+++ b/internal/handler/calendar_reconcile_tenancy_test.go
@@ -0,0 +1,216 @@
+package handler
+
+import (
+	"context"
+	"log/slog"
+	"testing"
+	"time"
+
+	"github.com/calnode/calnode/internal/caldav"
+	"github.com/calnode/calnode/internal/calendar"
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// The reconciler half of Boundary 5.
+//
+// ⛔ Enumeration is on the platform handle and each pass is on a bound one. Every
+// query in a pass reads bookings, booking_hosts and calendar_connections — tenant
+// tables — so a pass on the platform handle would reconcile every workspace's
+// bookings against whichever connections it resolved, and a pass on the UNBOUND
+// application handle would read nothing and heal nothing. Before this it was the
+// second of those, which is the failure the negative control below reproduces.
+
+func newReconcileHandler(t *testing.T) (*Handler, *db.DB) {
+	t.Helper()
+	app, platform := dbtest.RequireTenantPair(t)
+
+	h := New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL("https://app.calnode.test")
+
+	base := calendar.NewService(app)
+	cdav, err := caldav.New(app, testEncKey)
+	if err != nil {
+		t.Fatalf("caldav.New: %v", err)
+	}
+	base.Register(cdav)
+	h.SetCalendar(base)
+
+	return h, platform
+}
+
+// seedOrphan creates a workspace with a CANCELLED booking that still carries a
+// calendar event id — the exact divergence reconcileCancellations exists to heal.
+// The host has no calendar connection, so CancelEvent has nothing to call and the
+// pass clears the id without touching a network.
+func seedOrphan(t *testing.T, h *Handler, platform *db.DB, wsID, status string) {
+	t.Helper()
+	ctx := context.Background()
+
+	if _, err := platform.ExecContext(ctx,
+		`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', ?)`,
+		wsID, wsID, wsID+".example.com", status); err != nil {
+		t.Fatalf("workspace %s: %v", wsID, err)
+	}
+
+	bound := h.db.ForWorkspace(wsID)
+	userID := wsID + "-host"
+	if _, err := bound.ExecContext(ctx,
+		`INSERT INTO users (id, email, name) VALUES (?, ?, ?)`,
+		userID, wsID+"@example.com", wsID); err != nil {
+		t.Fatalf("user %s: %v", wsID, err)
+	}
+	if _, err := bound.ExecContext(ctx,
+		`INSERT INTO event_types (id, user_id, slug, name, duration_minutes, slot_interval_minutes)
+		 VALUES (?, ?, ?, ?, 30, 30)`,
+		wsID+"-et", userID, wsID+"-intro", wsID+" intro"); err != nil {
+		t.Fatalf("event type %s: %v", wsID, err)
+	}
+	start := time.Now().UTC().Add(24 * time.Hour)
+	if _, err := bound.ExecContext(ctx,
+		`INSERT INTO bookings (id, event_type_id, host_id, start_at, end_at, status)
+		 VALUES (?, ?, ?, ?, ?, 'cancelled')`,
+		wsID+"-booking", wsID+"-et", userID,
+		start.Format(time.RFC3339), start.Add(30*time.Minute).Format(time.RFC3339)); err != nil {
+		t.Fatalf("booking %s: %v", wsID, err)
+	}
+	if _, err := bound.ExecContext(ctx,
+		`INSERT INTO booking_hosts (id, booking_id, user_id, is_primary, external_event_id)
+		 VALUES (?, ?, ?, 1, ?)`,
+		wsID+"-bh", wsID+"-booking", userID, wsID+"-stale-event"); err != nil {
+		t.Fatalf("booking host %s: %v", wsID, err)
+	}
+}
+
+// eventID reads a workspace's stale event id through the platform handle, so the
+// assertion is about the row's state rather than about what anyone can see.
+func eventID(t *testing.T, platform *db.DB, wsID string) (string, bool) {
+	t.Helper()
+	var id *string
+	if err := platform.QueryRowContext(context.Background(),
+		`SELECT external_event_id FROM booking_hosts WHERE workspace_id = ?`, wsID).Scan(&id); err != nil {
+		t.Fatalf("read %s's event id: %v", wsID, err)
+	}
+	if id == nil {
+		return "", false
+	}
+	return *id, true
+}
+
+// TestReconciler_enumeratesActiveWorkspacesOnly is the enumeration half, asserted
+// exactly: which workspaces a sweep targets, and that each target is bound to its
+// own.
+func TestReconciler_enumeratesActiveWorkspacesOnly(t *testing.T) {
+	h, platform := newReconcileHandler(t)
+
+	seedOrphan(t, h, platform, "acme", "active")
+	seedOrphan(t, h, platform, "globex", "suspended")
+	seedOrphan(t, h, platform, "initech", "active")
+
+	targets := h.reconcileTargets()
+
+	got := map[string]bool{}
+	for _, target := range targets {
+		id := target.Workspace().ID
+		if got[id] {
+			t.Errorf("workspace %s targeted twice", id)
+		}
+		got[id] = true
+		// The binding, not just the label: the handle each pass will query on has
+		// to be bound to the same workspace.
+		if bound := target.db.Workspace(); bound != id {
+			t.Errorf("target %s runs on a handle bound to %q", id, bound)
+		}
+	}
+
+	if !got["acme"] || !got["initech"] {
+		t.Errorf("active workspaces missing from the sweep: %v", got)
+	}
+	if got["globex"] {
+		t.Error("a suspended workspace was included — it answers 503 on its own surfaces")
+	}
+	// The default workspace exists in every migrated database and is active, so it
+	// is expected; what must not appear is a suspended one.
+	t.Logf("sweep targets: %v", got)
+}
+
+// TestReconciler_healsItsOwnWorkspaceAndSkipsSuspended is the effect half.
+func TestReconciler_healsItsOwnWorkspaceAndSkipsSuspended(t *testing.T) {
+	h, platform := newReconcileHandler(t)
+
+	seedOrphan(t, h, platform, "acme", "active")
+	seedOrphan(t, h, platform, "globex", "suspended")
+
+	// Positive control on the fixture: both rows start stale.
+	for _, ws := range []string{"acme", "globex"} {
+		if id, ok := eventID(t, platform, ws); !ok || id == "" {
+			t.Fatalf("%s's fixture did not leave a stale event id (got %q, present=%v)", ws, id, ok)
+		}
+	}
+
+	h.reconcileCalendar()
+
+	if _, present := eventID(t, platform, "acme"); present {
+		t.Error("the active workspace's stale event id was not cleared")
+	}
+	id, present := eventID(t, platform, "globex")
+	if !present {
+		t.Error("the suspended workspace's row was reconciled; it should have been skipped")
+	} else if id != "globex-stale-event" {
+		t.Errorf("the suspended workspace's event id changed to %q", id)
+	}
+}
+
+// TestReconciler_theOldShapeHealsNothing is the negative control: one pass on the
+// UNBOUND application handle, which is what the reconciler was before this. Every
+// query matches no row, so it heals nothing and reports nothing.
+func TestReconciler_theOldShapeHealsNothing(t *testing.T) {
+	h, platform := newReconcileHandler(t)
+
+	seedOrphan(t, h, platform, "acme", "active")
+
+	// The old shape: one pass, on the handler as boot built it, unbound.
+	h.reconcileCalendarPass()
+
+	id, present := eventID(t, platform, "acme")
+	if !present {
+		t.Fatal("the unbound pass cleared the row; the control proves nothing")
+	}
+	if id != "acme-stale-event" {
+		t.Errorf("the unbound pass changed the event id to %q", id)
+	}
+	t.Log("negative control: a reconciler pass on the unbound application handle healed 0 of 1 " +
+		"diverged bookings, with no error — every stale calendar event would stay stale forever")
+
+	// And the fixed shape does heal it, so the difference is the binding and not the
+	// fixture.
+	h.reconcileCalendar()
+	if _, stillThere := eventID(t, platform, "acme"); stillThere {
+		t.Error("the per-workspace sweep did not heal what the unbound pass missed")
+	}
+}
+
+// TestReconciler_singleTenantIsOneUnenumeratedPass: with MULTI_TENANT unset there is
+// no query per sweep and the target is the handler itself, so an existing deployment
+// does the same work it always did.
+func TestReconciler_singleTenantIsOneUnenumeratedPass(t *testing.T) {
+	database := dbtest.Open(t)
+	h := New(database, slog.New(slog.DiscardHandler))
+
+	targets := h.reconcileTargets()
+	if len(targets) != 1 {
+		t.Fatalf("single-tenant sweep has %d targets; want 1", len(targets))
+	}
+	if targets[0] != h {
+		t.Error("the single-tenant target is not the handler itself")
+	}
+
+	ids, err := h.activeWorkspaceIDs(context.Background())
+	if err != nil {
+		t.Fatalf("activeWorkspaceIDs: %v", err)
+	}
+	if len(ids) != 1 || ids[0] != db.DefaultWorkspaceID {
+		t.Errorf("activeWorkspaceIDs = %v; want [%s]", ids, db.DefaultWorkspaceID)
+	}
+}
diff --git a/internal/handler/workspace.go b/internal/handler/workspace.go
index 7a92f24..629a5c9 100644
--- a/internal/handler/workspace.go
+++ b/internal/handler/workspace.go
@@ -315,6 +315,38 @@ func (h *Handler) workspaceByHost(ctx context.Context, requestHost string) (*Wor
 	return &ws, nil
 }
 
+// activeWorkspaceIDs lists every workspace a background loop should act for, on the
+// platform handle.
+//
+// Suspended workspaces are excluded here rather than at each call site, so a new
+// periodic loop cannot forget. In single-tenant mode it answers with the one
+// workspace, so a caller needs no branch — though reconcileTargets short-circuits
+// before reaching it, to avoid a query per sweep on an instance that has one tenant.
+func (h *Handler) activeWorkspaceIDs(ctx context.Context) ([]string, error) {
+	if !h.multiTenant {
+		return []string{db.DefaultWorkspaceID}, nil
+	}
+	rows, err := h.platformDB().QueryContext(ctx,
+		`SELECT id FROM workspaces WHERE status = 'active' ORDER BY id`)
+	if err != nil {
+		return nil, fmt.Errorf("list active workspaces: %w", err)
+	}
+	defer rows.Close()
+
+	var ids []string
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			return nil, fmt.Errorf("scan workspace id: %w", err)
+		}
+		ids = append(ids, id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("iterate workspaces: %w", err)
+	}
+	return ids, nil
+}
+
 // workspaceOfUser resolves the workspace a user belongs to, through the platform
 // handle.
 //

From 9ff86dce6030bf3e034b7c87ed565704171d2d69 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 03:11:26 -0400
Subject: [PATCH 36/51] cmd: scope reset-admin to a workspace, refuse mcp
 stdio, and inventory what stays global
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boundary 5, deliverable 5, plus the cross-tenant inventory B7 will assert against.

Which of the four subcommands needs what follows from what it touches, so the
classification is data (platformWideCLI) with a test asserting it. rotate-key and
recover-key operate only on crypto_keystore, which 00060 leaves exempt from tenancy
because there is one DEK per process — it has no policies at all, so DATABASE_URL's
handle reaches it either way. Both now carry a comment saying that, and saying that
per-tenant DEKs would make it wrong.

reset-admin was a real hole rather than a hygiene issue. Since D9 the unique on users
is (workspace_id, email), so UPDATE users SET password_hash = ? WHERE email = ? on an
unscoped handle matches every workspace that has a user with that address — and a
shared address across an agency's client workspaces is the ordinary case. The negative
control measures it: one unscoped statement reset 2 workspaces' owners. A recovery
tool that quietly hands out access to tenants nobody asked about is worse than one
that refuses. --workspace is accepted in both forms, anywhere among the positional
arguments, validated against the same shape db.ForWorkspace enforces, and in
single-tenant mode accepted and ignored so a fleet script keeps working.

mcp stdio is refused: the transport carries no credential and no Host, so there is
nothing to resolve a tenant from and the tools would run unbound, which matches no
row — an empty workspace with no explanation. The message names POST /mcp with a
workspace credential, and a test asserts it does, because a refusal that does not say
what to do instead is a dead end.

PROGRESS.md now inventories every remaining cross-tenant read and write with the
reason each is correct: the tenant-root and credential reads, the exempt tables, the
worker's single queue and its five retention sweeps, and the one cross-tenant WRITE
left — the Stripe payment-hold backstop, flagged as the entry a reviewer should push
back on and the one that has to move if hold timeouts ever become per-workspace. The
three sites that are not yet correct are listed separately and owed to B6.

gofmt -l empty, go vet clean, nine cases pass.
---
 PROGRESS.md                 |  89 ++++++++++++++
 cmd/calnode/mcp.go          |  11 ++
 cmd/calnode/recover_key.go  |   9 ++
 cmd/calnode/reset_admin.go  |  49 +++++---
 cmd/calnode/rotate_key.go   |   9 ++
 cmd/calnode/tenancy.go      | 126 ++++++++++++++++++++
 cmd/calnode/tenancy_test.go | 226 ++++++++++++++++++++++++++++++++++++
 7 files changed, 502 insertions(+), 17 deletions(-)
 create mode 100644 cmd/calnode/tenancy.go
 create mode 100644 cmd/calnode/tenancy_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 6d14492..e0259cd 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1387,3 +1387,92 @@ the difference is demonstrably the binding and not the fixture.
 Measured sweep target set with a suspended tenant present:
 `map[acme:true default:true initech:true]` — the suspended `globex` absent, and the
 seeded `default` workspace present because it is active in every migrated database.
+
+## Boundary 5, part four — the CLI subcommands
+
+Which of the four needs what follows from what it touches, so the classification is
+data (`platformWideCLI`) and a test asserts it rather than re-deriving it.
+
+| command | touches | under `MULTI_TENANT` |
+|---|---|---|
+| `rotate-key` | `crypto_keystore` | **unchanged** |
+| `recover-key` | `crypto_keystore` | **unchanged** |
+| `reset-admin` | `users` (tenant) | **requires `--workspace=<id>`** |
+| `mcp` (stdio) | everything | **refused** |
+
+`crypto_keystore` is exempt from tenancy (D2) because there is one DEK per process
+(D3) — it has no policies at all, so `DATABASE_URL`'s handle reaches it whether or
+not RLS is enabled. Both key commands now carry a comment saying that, and saying
+that per-tenant DEKs would make it wrong.
+
+### ⛔ `reset-admin` was a real hole, not a hygiene issue
+
+Since D9 the unique on `users` is **`(workspace_id, email)`**, not `email`. So
+`UPDATE users SET password_hash = ? WHERE email = ?` on an unscoped handle matches
+**every workspace that has a user with that address** — and a shared address across
+an agency's client workspaces is the ordinary case, not a contrivance. The negative
+control measures it:
+
+```
+tenancy_test.go:222: negative control: one unscoped `WHERE email = "owner@example.com"`
+reset 2 workspaces' owners — since D9 the unique is (workspace_id, email), so a shared
+address is legal and common
+```
+
+A recovery tool that quietly hands an operator access to tenants nobody asked about
+is worse than one that refuses. `--workspace` is accepted in both `--workspace=id`
+and `--workspace id` forms, anywhere among the positional arguments, and is validated
+against the same `[a-z0-9_-]{1,64}` shape `db.ForWorkspace` enforces. In
+single-tenant mode it is **accepted and ignored** rather than rejected, so a script
+written for a multi-tenant fleet keeps working against one instance.
+
+### `mcp` stdio is refused, and the message names the path that works
+
+The stdio transport carries no credential and no Host, so there is nothing to
+resolve a tenant from; the tools would run on the unbound handle, which matches no
+row, and the operator would see an empty workspace with no explanation. The refusal
+points at `POST /mcp` with a workspace's API key or OAuth token, which resolves the
+tenant from the credential (D10). A test asserts the message mentions the HTTP
+transport, the path, and the credential — a refusal that does not say what to do
+instead is a dead end.
+
+---
+
+## Every remaining cross-tenant read and write, and why each is correct
+
+For B7's proof to assert this list is complete. Anything reaching more than one
+workspace's rows is here; everything else is bound.
+
+### Platform handle, by design — the tenant root and the exempt tables
+
+| site | what | why correct |
+|---|---|---|
+| `workspaceByHost`, `workspaceByID`, `activeWorkspaceIDs` | `workspaces` | resolving *which* tenant; `workspaces` is exempt and carries a SELECT-only policy for the app role (D2) |
+| `RequireAuth` (api_keys, sessions) | credential → user | the read that DISCOVERS the tenant cannot be bound to it; those uniques are global for exactly this (D9) |
+| `MCPCallerMiddleware`, `VerifyMCPBearer` | bearer → user | same |
+| `workspaceOfUser` | `users.workspace_id` | resolves the tenant for a Platform route's write |
+| `/oauth/*` handlers | auth codes, tokens, clients | Platform-wrapped: `h.db` **is** the platform handle; the two INSERTs name `workspace_id` (the sweep's finding 16/17) |
+| `rotate-key`, `recover-key` | `crypto_keystore` | exempt (D2), one DEK per process (D3) |
+| goose migrations, `EnableRLS`, `VerifyRoles` | DDL and role attributes | schema-level, not row-level |
+
+### Worker, on the platform handle — one queue, and retention rules
+
+| site | what | why correct |
+|---|---|---|
+| the claim query + reaper | `jobs` | ONE queue ordered by `run_at` globally; a bound loop would serve one tenant and starve the rest. This is what 00060's `idx_jobs_pending_global` is for |
+| purge expired manage tokens, sessions, magic links, idempotency keys, oauth auth codes | 5 `DELETE`s | retention rules keyed on `expires_at`/`created_at`, properties of the row and not of the tenant; per-workspace would be N statements to express one policy |
+| purge finished webhook deliveries | `DELETE` | same, 30-day retention |
+| ⚠️ **Stripe payment-hold backstop** | **`UPDATE bookings SET status='cancelled'`** | the only cross-tenant **WRITE** left. Keyed on `payment_status='pending' AND created_at < cutoff`, a property of the row. ⛔ **It has to move if hold timeouts ever become per-workspace**, and it is the one entry on this list a reviewer should push back on |
+
+### Reconciler
+
+Enumerates on the platform handle, then every pass is bound. No cross-tenant read
+inside a pass.
+
+### Not yet correct — known, and owed to B6
+
+| site | state |
+|---|---|
+| `POST /v1/livekit/webhook` + its alias, `POST /v1/stripe/webhook` | `Platform`-wrapped so they can find the row they name; the processing after that is **not** yet bound. Must resolve the workspace from the room / session and hand off to `forWorkspace` |
+| `/v1/auth/sso` hand-off (D11), `clientIP` rate-limit keys (D14) | blocked on `feat/platform-hooks` |
+| `/metrics` | reads `jobs`; must use `Platform()` at integration |
diff --git a/cmd/calnode/mcp.go b/cmd/calnode/mcp.go
index 9eca8a2..db87b8a 100644
--- a/cmd/calnode/mcp.go
+++ b/cmd/calnode/mcp.go
@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"fmt"
 	"log/slog"
 	"os"
 	"os/signal"
@@ -26,6 +27,16 @@ import (
 func runMCPStdio(_ []string) {
 	cfg := config.Load()
 
+	// ⛔ Refused under MULTI_TENANT. The stdio transport carries no credential and no
+	// Host, so there is nothing to resolve a tenant from and the tools would run on
+	// the unbound handle — which under the policies matches no row, so an operator
+	// would get an empty workspace and no explanation. The HTTP transport resolves
+	// the tenant from the bearer credential (D10).
+	if err := refuseMCPStdio(cfg.MultiTenant); err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
 	// stdout carries the MCP protocol — never log to it. All logs → stderr.
 	logger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: cfg.LogLevel}))
 	slog.SetDefault(logger)
diff --git a/cmd/calnode/recover_key.go b/cmd/calnode/recover_key.go
index a7acf51..224d26f 100644
--- a/cmd/calnode/recover_key.go
+++ b/cmd/calnode/recover_key.go
@@ -17,6 +17,15 @@ import (
 // CALNODE_RECOVERY_SECRET must be in the environment.
 // After a successful recovery, set CALNODE_ENCRYPTION_KEY=<new-platform-secret>
 // before the next server start.
+// Multi-tenant mode needs no change here, and this note is why rather than an
+// oversight: recover-key operates only on crypto_keystore, which migration 00060 leaves
+// EXEMPT from tenancy (D2) because there is one DEK per process (D3). It is
+// platform-wide by construction, so DATABASE_URL's handle reaches it whether or not
+// the row-level-security policies are enabled — crypto_keystore has none.
+//
+// ⚠️ If per-tenant DEKs are ever adopted, both commands need a --workspace flag and
+// this comment becomes wrong. cmd/calnode/tenancy.go's platformWideCLI is the list a
+// test asserts against.
 func runRecoverKey(args []string) {
 	if len(args) != 1 || args[0] == "" {
 		fmt.Fprintln(os.Stderr, "usage: calnode recover-key <new-platform-secret>")
diff --git a/cmd/calnode/reset_admin.go b/cmd/calnode/reset_admin.go
index 4f2a2a7..9317b1f 100644
--- a/cmd/calnode/reset_admin.go
+++ b/cmd/calnode/reset_admin.go
@@ -3,7 +3,6 @@ package main
 import (
 	"fmt"
 	"os"
-	"strings"
 
 	"golang.org/x/crypto/bcrypt"
 
@@ -13,32 +12,48 @@ import (
 
 // runResetAdmin is invoked when the binary is called as:
 //
-//	calnode reset-admin <email> <new-password>
+//	calnode reset-admin [--workspace=<id>] <email> <new-password>
 //
 // It resets the password for the named user and enables email_login on their
 // account. This is the last-resort recovery path when SMTP is unavailable and
 // the admin is locked out.
 func runResetAdmin(args []string) {
-	if len(args) != 2 {
-		fmt.Fprintln(os.Stderr, "usage: calnode reset-admin <email> <new-password>")
-		os.Exit(1)
-	}
-	email := strings.TrimSpace(strings.ToLower(args[0]))
-	password := args[1]
-
-	if len(password) < 8 || len(password) > 72 {
-		fmt.Fprintln(os.Stderr, "error: password must be 8–72 characters")
-		os.Exit(1)
-	}
-
 	cfg := config.Load()
 
-	database, err := db.OpenDB(cfg.DatabaseURL)
+	req, err := parseResetAdmin(args, cfg.MultiTenant)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "error: failed to open database: %v\n", err)
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
 		os.Exit(1)
 	}
-	defer database.Close()
+	email, password := req.Email, req.Password
+
+	// ⛔ In multi-tenant mode the UPDATE must be bound. users.email is unique per
+	// WORKSPACE since D9, so `WHERE email = ?` on the platform handle would match
+	// every workspace that has a user with that address and reset all of their
+	// passwords — a recovery tool that hands out access to tenants the operator was
+	// not asked about.
+	var database *db.DB
+	if cfg.MultiTenant {
+		app, platform, oerr := db.OpenPair(cfg.DatabaseURL, cfg.DatabaseAdminURL)
+		if oerr != nil {
+			fmt.Fprintf(os.Stderr, "error: failed to open database pair: %v\n", oerr)
+			os.Exit(1)
+		}
+		defer platform.Close()
+		defer app.Close()
+		database = app.ForWorkspace(req.Workspace)
+		if database.Err() != nil {
+			fmt.Fprintf(os.Stderr, "error: %v\n", database.Err())
+			os.Exit(1)
+		}
+	} else {
+		database, err = db.OpenDB(cfg.DatabaseURL)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "error: failed to open database: %v\n", err)
+			os.Exit(1)
+		}
+		defer database.Close()
+	}
 
 	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
 	if err != nil {
diff --git a/cmd/calnode/rotate_key.go b/cmd/calnode/rotate_key.go
index 000fb9c..7842d04 100644
--- a/cmd/calnode/rotate_key.go
+++ b/cmd/calnode/rotate_key.go
@@ -14,6 +14,15 @@ import (
 // The current secret is read from CALNODE_ENCRYPTION_KEY (env or .env file).
 // After a successful rotation, update CALNODE_ENCRYPTION_KEY to <new-platform-secret>
 // before the next server start.
+// Multi-tenant mode needs no change here, and this note is why rather than an
+// oversight: rotate-key operates only on crypto_keystore, which migration 00060 leaves
+// EXEMPT from tenancy (D2) because there is one DEK per process (D3). It is
+// platform-wide by construction, so DATABASE_URL's handle reaches it whether or not
+// the row-level-security policies are enabled — crypto_keystore has none.
+//
+// ⚠️ If per-tenant DEKs are ever adopted, both commands need a --workspace flag and
+// this comment becomes wrong. cmd/calnode/tenancy.go's platformWideCLI is the list a
+// test asserts against.
 func runRotateKey(args []string) {
 	if len(args) != 1 || args[0] == "" {
 		fmt.Fprintln(os.Stderr, "usage: calnode rotate-key <new-platform-secret>")
diff --git a/cmd/calnode/tenancy.go b/cmd/calnode/tenancy.go
new file mode 100644
index 0000000..9730669
--- /dev/null
+++ b/cmd/calnode/tenancy.go
@@ -0,0 +1,126 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// The CLI subcommands under multi-tenant mode.
+//
+// Each of the four is one of two things, and which it is follows from what it
+// touches:
+//
+//	rotate-key, recover-key  — crypto_keystore, which is EXEMPT from tenancy (D2)
+//	                           and holds one DEK per process (D3). Platform-wide by
+//	                           construction, so they run unchanged on the platform
+//	                           handle and need no workspace.
+//	reset-admin              — users, a tenant table. ⛔ And since D9 made the
+//	                           unique (workspace_id, email) rather than email, an
+//	                           unscoped UPDATE ... WHERE email = ? matches EVERY
+//	                           workspace that has a user with that address and
+//	                           resets all of their passwords. It needs --workspace.
+//	mcp                      — the stdio transport has no credential and no Host, so
+//	                           there is nothing to resolve a tenant from. Refused.
+var (
+	// errWorkspaceRequired is reset-admin's refusal under MULTI_TENANT.
+	errWorkspaceRequired = errors.New(
+		"reset-admin needs --workspace=<id> when MULTI_TENANT is set: users.email is unique per " +
+			"workspace, so an unscoped reset would change the password of every user with that " +
+			"address in every workspace")
+
+	// errMCPStdioMultiTenant is the stdio transport's refusal.
+	errMCPStdioMultiTenant = errors.New(
+		"calnode mcp (stdio) is not available when MULTI_TENANT is set: the stdio transport carries " +
+			"no credential and no Host, so there is no workspace to resolve and the tools would run " +
+			"unscoped. Use the HTTP transport at POST /mcp with a workspace's API key or OAuth token, " +
+			"which resolves the tenant from the credential")
+)
+
+// resetAdminRequest is a parsed `calnode reset-admin` invocation.
+type resetAdminRequest struct {
+	Email     string
+	Password  string
+	Workspace string // "" in single-tenant mode
+}
+
+// parseResetAdmin parses the subcommand's arguments and applies the multi-tenant
+// rule. --workspace may appear anywhere among the positional arguments, in either
+// the `--workspace=id` or `--workspace id` form.
+//
+// In single-tenant mode --workspace is accepted and ignored rather than rejected,
+// so a script written for a multi-tenant fleet keeps working against a
+// single-tenant instance.
+func parseResetAdmin(args []string, multiTenant bool) (resetAdminRequest, error) {
+	var req resetAdminRequest
+	var positional []string
+
+	for i := 0; i < len(args); i++ {
+		a := args[i]
+		switch {
+		case strings.HasPrefix(a, "--workspace="):
+			req.Workspace = strings.TrimPrefix(a, "--workspace=")
+		case a == "--workspace":
+			if i+1 >= len(args) {
+				return req, errors.New("--workspace needs a value")
+			}
+			i++
+			req.Workspace = args[i]
+		default:
+			positional = append(positional, a)
+		}
+	}
+
+	if len(positional) != 2 {
+		return req, errors.New("usage: calnode reset-admin [--workspace=<id>] <email> <new-password>")
+	}
+	req.Email = strings.TrimSpace(strings.ToLower(positional[0]))
+	req.Password = positional[1]
+
+	if len(req.Password) < 8 || len(req.Password) > 72 {
+		return req, errors.New("password must be 8–72 characters")
+	}
+
+	if multiTenant {
+		if req.Workspace == "" {
+			return req, errWorkspaceRequired
+		}
+		if !validWorkspaceID(req.Workspace) {
+			return req, fmt.Errorf("--workspace=%q is not a workspace id ([a-z0-9_-], 1-64 chars)", req.Workspace)
+		}
+	}
+
+	return req, nil
+}
+
+// refuseMCPStdio reports whether `calnode mcp` may run, and why not.
+func refuseMCPStdio(multiTenant bool) error {
+	if multiTenant {
+		return errMCPStdioMultiTenant
+	}
+	return nil
+}
+
+// platformWideCLI names the subcommands that operate on crypto_keystore and are
+// therefore tenant-independent. Kept as data so the test can assert the
+// classification rather than re-derive it.
+var platformWideCLI = map[string]bool{
+	"rotate-key":  true,
+	"recover-key": true,
+}
+
+// validWorkspaceID mirrors db.ValidWorkspaceID without importing it, because this
+// runs before any database handle exists.
+func validWorkspaceID(id string) bool {
+	if len(id) == 0 || len(id) > 64 {
+		return false
+	}
+	for _, r := range id {
+		switch {
+		case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '-', r == '_':
+		default:
+			return false
+		}
+	}
+	return true
+}
diff --git a/cmd/calnode/tenancy_test.go b/cmd/calnode/tenancy_test.go
new file mode 100644
index 0000000..0172223
--- /dev/null
+++ b/cmd/calnode/tenancy_test.go
@@ -0,0 +1,226 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"golang.org/x/crypto/bcrypt"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// TestParseResetAdmin_requiresWorkspaceUnderMultiTenant.
+//
+// ⛔ The reason this is a refusal and not a default: since D9 the unique on users is
+// (workspace_id, email), so an unscoped `UPDATE users SET password_hash = ? WHERE
+// email = ?` matches every workspace that has a user with that address. A recovery
+// tool that quietly resets three tenants' owners because they all use the same
+// address is worse than one that refuses.
+func TestParseResetAdmin_requiresWorkspaceUnderMultiTenant(t *testing.T) {
+	_, err := parseResetAdmin([]string{"owner@example.com", "hunter2hunter2"}, true)
+	if !errors.Is(err, errWorkspaceRequired) {
+		t.Fatalf("err = %v; want errWorkspaceRequired", err)
+	}
+	// The message has to say what to do, not just that it refused.
+	for _, want := range []string{"--workspace", "unique per", "every user"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("the refusal does not mention %q: %s", want, err)
+		}
+	}
+}
+
+func TestParseResetAdmin_acceptsBothFlagForms(t *testing.T) {
+	for _, args := range [][]string{
+		{"--workspace=acme", "owner@example.com", "hunter2hunter2"},
+		{"--workspace", "acme", "owner@example.com", "hunter2hunter2"},
+		{"owner@example.com", "hunter2hunter2", "--workspace=acme"},
+	} {
+		req, err := parseResetAdmin(args, true)
+		if err != nil {
+			t.Fatalf("parseResetAdmin(%v) = %v", args, err)
+		}
+		if req.Workspace != "acme" {
+			t.Errorf("parseResetAdmin(%v) workspace = %q", args, req.Workspace)
+		}
+		if req.Email != "owner@example.com" || req.Password != "hunter2hunter2" {
+			t.Errorf("parseResetAdmin(%v) = %+v", args, req)
+		}
+	}
+}
+
+// TestParseResetAdmin_singleTenantAcceptsAndIgnoresTheFlag: a script written for a
+// multi-tenant fleet keeps working against a single-tenant instance.
+func TestParseResetAdmin_singleTenantAcceptsAndIgnoresTheFlag(t *testing.T) {
+	if _, err := parseResetAdmin([]string{"owner@example.com", "hunter2hunter2"}, false); err != nil {
+		t.Errorf("single-tenant without --workspace: %v", err)
+	}
+	req, err := parseResetAdmin([]string{"--workspace=acme", "owner@example.com", "hunter2hunter2"}, false)
+	if err != nil {
+		t.Fatalf("single-tenant with --workspace: %v", err)
+	}
+	if req.Workspace != "acme" {
+		t.Errorf("the flag was dropped: %+v", req)
+	}
+}
+
+func TestParseResetAdmin_rejectsAMalformedWorkspace(t *testing.T) {
+	for _, bad := range []string{"ACME", "ws a", "ws'a", "../etc", strings.Repeat("a", 65)} {
+		if _, err := parseResetAdmin([]string{"--workspace=" + bad, "o@e.com", "hunter2hunter2"}, true); err == nil {
+			t.Errorf("parseResetAdmin accepted --workspace=%q", bad)
+		}
+	}
+}
+
+func TestParseResetAdmin_stillChecksTheBasics(t *testing.T) {
+	if _, err := parseResetAdmin([]string{"--workspace=acme", "o@e.com"}, true); err == nil {
+		t.Error("accepted a missing password")
+	}
+	if _, err := parseResetAdmin([]string{"--workspace=acme", "o@e.com", "short"}, true); err == nil {
+		t.Error("accepted a password under 8 characters")
+	}
+	if _, err := parseResetAdmin([]string{"--workspace"}, true); err == nil {
+		t.Error("accepted --workspace with no value")
+	}
+}
+
+// TestRefuseMCPStdio: the stdio transport has no credential and no Host, so there is
+// nothing to resolve a tenant from.
+func TestRefuseMCPStdio(t *testing.T) {
+	if err := refuseMCPStdio(false); err != nil {
+		t.Errorf("single-tenant stdio was refused: %v", err)
+	}
+	err := refuseMCPStdio(true)
+	if !errors.Is(err, errMCPStdioMultiTenant) {
+		t.Fatalf("err = %v; want errMCPStdioMultiTenant", err)
+	}
+	// It has to name the path that DOES work, or an operator is stuck.
+	for _, want := range []string{"HTTP transport", "/mcp", "API key"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("the refusal does not mention %q: %s", want, err)
+		}
+	}
+}
+
+// TestPlatformWideCLI pins the classification. rotate-key and recover-key touch only
+// crypto_keystore, which 00060 leaves exempt (D2) because there is one DEK per
+// process (D3) — so they are tenant-independent and take no --workspace.
+func TestPlatformWideCLI(t *testing.T) {
+	for _, cmd := range []string{"rotate-key", "recover-key"} {
+		if !platformWideCLI[cmd] {
+			t.Errorf("%s should be classified platform-wide", cmd)
+		}
+	}
+	for _, cmd := range []string{"reset-admin", "mcp"} {
+		if platformWideCLI[cmd] {
+			t.Errorf("%s is not platform-wide: it touches tenant rows or needs a tenant", cmd)
+		}
+	}
+}
+
+// TestResetAdmin_scopesToTheNamedWorkspace is the behavioural half, and the reason
+// the flag exists: two workspaces whose owners share an email address. The reset must
+// change exactly one.
+func TestResetAdmin_scopesToTheNamedWorkspace(t *testing.T) {
+	app, platform := dbtest.RequireTenantPair(t)
+	ctx := context.Background()
+
+	const shared = "owner@example.com"
+	for _, ws := range []string{"acme", "globex"} {
+		if _, err := platform.ExecContext(ctx,
+			`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', 'active')`,
+			ws, ws, ws+".example.com"); err != nil {
+			t.Fatalf("workspace %s: %v", ws, err)
+		}
+		// ⛔ The same address in both. Legal since D9 made the unique
+		// (workspace_id, email), and it is the ordinary case for an agency running
+		// several client workspaces.
+		if _, err := app.ForWorkspace(ws).ExecContext(ctx,
+			`INSERT INTO users (id, email, name, password_hash, email_login) VALUES (?, ?, ?, 'old', 0)`,
+			ws+"-owner", shared, ws+" owner"); err != nil {
+			t.Fatalf("user %s: %v", ws, err)
+		}
+	}
+
+	req, err := parseResetAdmin([]string{"--workspace=acme", shared, "hunter2hunter2"}, true)
+	if err != nil {
+		t.Fatalf("parseResetAdmin: %v", err)
+	}
+
+	// The same statement runResetAdmin runs, on the same bound handle it builds.
+	hash, err := bcrypt.GenerateFromPassword([]byte(req.Password), bcrypt.MinCost)
+	if err != nil {
+		t.Fatalf("bcrypt: %v", err)
+	}
+	res, err := app.ForWorkspace(req.Workspace).ExecContext(ctx,
+		`UPDATE users SET password_hash = ?, email_login = 1 WHERE email = ?`, string(hash), req.Email)
+	if err != nil {
+		t.Fatalf("reset: %v", err)
+	}
+	n, _ := res.RowsAffected()
+	if n != 1 {
+		t.Errorf("the reset touched %d rows; want exactly 1", n)
+	}
+
+	// acme's owner can log in with the new password; globex's is untouched.
+	for _, tc := range []struct {
+		ws          string
+		wantChanged bool
+	}{{"acme", true}, {"globex", false}} {
+		var stored string
+		var login int
+		if err := platform.QueryRowContext(ctx,
+			`SELECT password_hash, email_login FROM users WHERE workspace_id = ?`, tc.ws).
+			Scan(&stored, &login); err != nil {
+			t.Fatalf("read %s's owner: %v", tc.ws, err)
+		}
+		changed := stored != "old"
+		if changed != tc.wantChanged {
+			t.Errorf("%s's password changed = %v; want %v", tc.ws, changed, tc.wantChanged)
+		}
+		if tc.wantChanged && login != 1 {
+			t.Errorf("%s's email_login was not enabled", tc.ws)
+		}
+		if !tc.wantChanged && login != 0 {
+			t.Errorf("%s's email_login was enabled by another workspace's reset", tc.ws)
+		}
+	}
+}
+
+// TestResetAdmin_theOldShapeResetsEveryWorkspace is the negative control: the
+// unscoped statement, on the platform handle, which is what the command did before
+// --workspace existed.
+func TestResetAdmin_theOldShapeResetsEveryWorkspace(t *testing.T) {
+	app, platform := dbtest.RequireTenantPair(t)
+	ctx := context.Background()
+
+	const shared = "owner@example.com"
+	for _, ws := range []string{"acme", "globex"} {
+		if _, err := platform.ExecContext(ctx,
+			`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', 'active')`,
+			ws, ws, ws+".example.com"); err != nil {
+			t.Fatalf("workspace %s: %v", ws, err)
+		}
+		if _, err := app.ForWorkspace(ws).ExecContext(ctx,
+			`INSERT INTO users (id, email, name, password_hash) VALUES (?, ?, ?, 'old')`,
+			ws+"-owner", shared, ws+" owner"); err != nil {
+			t.Fatalf("user %s: %v", ws, err)
+		}
+	}
+
+	res, err := platform.ExecContext(ctx,
+		`UPDATE users SET password_hash = 'new', email_login = 1 WHERE email = ?`, shared)
+	if err != nil {
+		t.Fatalf("unscoped reset: %v", err)
+	}
+	n, _ := res.RowsAffected()
+	if n != 2 {
+		t.Fatalf("the unscoped reset touched %d rows; the control proves nothing if it is not 2", n)
+	}
+	t.Logf("negative control: one unscoped `WHERE email = %q` reset %d workspaces' owners — "+
+		"since D9 the unique is (workspace_id, email), so a shared address is legal and common", shared, n)
+
+	_ = db.DefaultWorkspaceID // the default workspace has no user with this address
+}

From fb13717fa5e10b1878d95fbcc04701552082cc86 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 04:14:17 -0400
Subject: [PATCH 37/51] PROGRESS: the platform-hooks merge, and the D11 plan
 for B6

---
 PROGRESS.md | 252 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 250 insertions(+), 2 deletions(-)

diff --git a/PROGRESS.md b/PROGRESS.md
index e0259cd..03b31f9 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1474,5 +1474,253 @@ inside a pass.
 | site | state |
 |---|---|
 | `POST /v1/livekit/webhook` + its alias, `POST /v1/stripe/webhook` | `Platform`-wrapped so they can find the row they name; the processing after that is **not** yet bound. Must resolve the workspace from the room / session and hand off to `forWorkspace` |
-| `/v1/auth/sso` hand-off (D11), `clientIP` rate-limit keys (D14) | blocked on `feat/platform-hooks` |
-| `/metrics` | reads `jobs`; must use `Platform()` at integration |
+| ~~`/v1/auth/sso` hand-off (D11), `clientIP` rate-limit keys (D14)~~ | ✅ **the VERIFY halves landed with the merge below.** What remains of D11 is the MINT half: no OAuth callback issues an SSO token yet, so nothing exercises the endpoint in production. Plan at the end of this file |
+| ~~`/metrics`~~ | ✅ reads `jobs` through `Platform()` |
+
+---
+
+## Integration — `feat/platform-hooks` merged (commit `8a93fad`)
+
+Merged **into** `feat/multi-tenant` with `--no-ff` before B6, because three of that
+branch's four features are things B6 was otherwise going to have to fake: the SSO
+endpoint D11 hands off to, the trusted-proxy client IP D14 keys on, and `/metrics`.
+
+Six conflicted files, ten hunks. The commit message carries the per-file resolution; what
+belongs here is the part that was a **decision** rather than a merge.
+
+### The three new routes, classified
+
+```
+172 routes: 31 host-scoped, 107 credential-scoped, 26 platform, 8 allowlisted
+```
+
+| route | class | why |
+|---|---|---|
+| `GET /metrics` | **Platform** | queue depth is an INSTANCE number. Its `jobs` read goes through `Platform()` inside the handler as well as being registered unscoped — a bound read would report one workspace's backlog as if it were the whole queue, an unbound one zero, and both are wrong in a way a dashboard cannot show you |
+| `GET /v1/auth/sso` | **Platform** | no tenant Host and no credential yet. The TOKEN is the credential and the workspace is its `wid` claim |
+| `POST /v1/auth/sessions/revoke-all` | **credential-scoped** | whose sessions to cut is a question about one workspace's users. All three of its statements (`users`, `sessions`, `oauth_access_tokens`) are then scoped by the bind, which is what makes a target id from another workspace a 404 rather than a revocation |
+
+⚠️ **The classification gate caught the third one, and the cause is worth knowing:
+`routes_classified_test.go` scans `server.go` LINE BY LINE.** The platform branch had
+written the registration across two lines, so the scanner saw a pattern with an empty
+expression and reported it unclassified. A wrapper on a continuation line is invisible to
+the gate. Every registration in that file is therefore one line, however long.
+
+### `sso_nonces` is EXEMPT, not a tenant table
+
+The migration is renumbered `00059` → **`00061`** in both dirs (00060 is tenancy);
+`knownMigrationCount` 60 → 61.
+
+A jti is **global**. The question the table answers is "has this exact token been spent",
+and the answer must not depend on which workspace the token names — per workspace, the
+same jti could be replayed once per tenant, which is strictly weaker for no benefit. It
+also has no owner at the moment the row is written: the nonce is claimed *before* the
+`wid` claim has been trusted. So it joins `workspaces`, `crypto_keystore`,
+`goose_db_version` and `oauth_clients` in `db.ExemptTables`, and
+`TestTenancy_tableListsCoverTheSchema` is updated with it.
+
+⛔ **The Postgres file declares `expires_at TEXT COLLATE "C"`, and without it the merge
+would have redded a gate nobody was thinking about.** The worker purges the table with a
+lexicographic `expires_at < ?` — exactly what migration 00059 pinned the other 54 TEXT
+timestamps for — and `collation_test.go`'s audit matches by column NAME, so a new `_at`
+column is caught whether or not anyone remembers. `wantTimestampColumns` 56 → 57.
+
+### ⛔ The `wid` claim was documentation, and the merge made it load-bearing
+
+The platform branch parsed `wid` and **deliberately ignored** it ("an instance is a
+single workspace today"). In multi-tenant mode it is now required, validated against
+`db.ValidWorkspaceID`, and read back through the platform handle, so a token naming a
+deleted, suspended or public-host-less workspace is refused instead of seating a user
+nobody can reach. Single-tenant is untouched: `wid` is ignored, `aud` is `BASE_URL`.
+
+**The audience is the WORKSPACE's public host, not `BASE_URL` (D11).** The hand-off exists
+precisely because the identity host cannot set a cookie on a tenant's domain, so the token
+is minted for that domain — and a token for tenant A must not be spendable on tenant B's
+host, which would seat a session on B for a person A vouched for.
+
+**Every statement the endpoint runs now names the workspace**, and this is the finding
+rather than a tidy-up. `/v1/auth/sso` is Platform-wrapped, so `h.db` is the platform
+handle: it bypasses the policies and binds `''`. Since D9 the unique on `users` is
+`(workspace_id, email)`, so one address legitimately exists in several workspaces — and
+an unqualified `WHERE email = ?` resolves an **arbitrary** one of them. It is the
+`reset-admin` hole again, reachable here by anyone holding the shared secret. Same fix
+for `ssoOwnerExists`, which counted owners instance-wide: unscoped, the first SSO user of
+every workspace after the first would silently never be its owner.
+
+`createSessionIn(…, workspaceID)` is how the session names its tenant. An empty
+`workspaceID` keeps the original statement, so the other seven callers — all on handles
+already bound to the request's workspace, where the bind fills the column — are untouched.
+⚠️ It matters beyond bookkeeping: every later request for that user runs on a **bound**
+handle, which could neither read that session nor delete it on logout.
+
+Negative control, the workspace predicate removed from the lookup only:
+
+```
+--- FAIL: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace
+    sso_tenancy_test.go:100: no user shared@example.test in workspace globex: sql: no rows in result set
+```
+
+That is the bug stated exactly: the second workspace's hand-off found the FIRST
+workspace's user by email, so no globex user was ever created — and the session it minted
+pointed at acme's person. `sessions.user_id` is global, so the foreign key would not have
+complained.
+
+### D14 wired, and the two halves pull in opposite directions
+
+`rateLimitKey` is `(workspace host, client IP)` when `SetMultiTenantLimits` is on, the IP
+alone otherwise. Both halves are load-bearing and each is useless without the other:
+
+- **without the workspace**, two tenants' bookers behind one address — a shared office, a
+  corporate NAT, a CDN — share a bucket, so the busier workspace spends the quieter one's
+  allowance. One tenant degrading another's service through no fault of either.
+- **without `TRUSTED_PROXY_CIDRS`**, the "IP" behind a proxy IS the proxy, so adding the
+  workspace prefix would make things WORSE: a whole tenant becomes ONE bucket and its
+  first 20 bookers a minute exhaust it for everyone else in that tenant. The prefix is
+  only safe because `remoteIP` resolves the client's own address when a trusted hop
+  forwarded it. This is why D14 waited for this branch instead of being approximated.
+
+The workspace comes from the **Host**, not from a resolved `*Workspace`: the limiter runs
+before any handler and rejecting a request must not cost a database read. An unrecognised
+host keys on the host string itself, which is the safe direction — a Host-rotating
+attacker gets a bucket per value and spends no real tenant's allowance.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+`go test ./...` **rc=0 on SQLite (30/30)** and **rc=0 on PostgreSQL (30/30)**.
+`go test -race -count=1 ./internal/handler/ ./internal/worker/` rc=0 on PostgreSQL
+(585.5s / 31.8s).
+
+The platform branch's own tests, all PASS on both lanes: `sso_test` (11),
+`session_test` (9 `RevokeAllSessions` cases), `metrics_test` (3),
+`notetaker_settings_test` (2), `trustedproxy_test` (10), `reminder_test` (9 including
+`reminderFiresBookingReminderWebhook` and `reminderWebhookCarriesTheFiringOffset`, which
+is rule 5: the webhook fires from the worker's **bound** per-workspace path through
+`deps.Webhook`, so it is signed with that workspace's secret), `i18n` and `stt`
+(fr-CA and `STT_BASE_URL` need no tenancy change and are confirmed only by building and
+passing).
+
+The tenancy suites still hold with the platform routes in the mux:
+
+```
+--- PASS: TestTenancy_readSurfaces (1.02s)          --- PASS: TestSweep_oauthGrantLandsInTheOwnersWorkspace (0.97s)
+--- PASS: TestTenancy_bookingByIDIsNotFoundAcrossWorkspaces (1.02s)
+--- PASS: TestTenancy_credentialOnTheWrongHostIs403 (1.07s)
+--- PASS: TestTenancy_writeLandsInItsOwnWorkspace (1.17s)
+--- PASS: TestTenancy_mcpToolCallOverHTTP (1.00s)   --- PASS: TestSweep_setupIsRefusedInMultiTenantMode (1.07s)
+--- PASS: TestEveryRouteIsClassified               --- PASS: TestSweep_tenantLocalTokensDoNotResolveAcrossHosts (1.03s)
+--- PASS: TestCredentialScopedRoutesAuthenticateFirst   (107 credential-scoped routes checked)
+--- PASS: TestPlatformRoutesAreTheIdentityHostSet
+```
+
+New multi-tenant cases, running rather than skipping on the PostgreSQL lane:
+
+```
+--- PASS: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace (0.92s)
+--- PASS: TestSSOHandoff_multiTenantRefusesABadWID (3.80s)   [missing, empty, unknown, not an id]
+--- PASS: TestSSOHandoff_multiTenantAudienceIsThePublicHost (2.84s)   [identity host, another tenant, bare hostname]
+--- PASS: TestSSOHandoff_multiTenantRefusesASuspendedWorkspace (1.03s)
+--- PASS: TestRateLimit_workspacesBehindOneProxyDoNotShareABucket (0.00s)
+--- PASS: TestRateLimit_twoBookersOfOneWorkspaceKeepTheirOwnBuckets (0.00s)
+--- PASS: TestRateLimit_singleTenantIgnoresTheHost (0.00s)
+--- PASS: TestRateLimitKey_portIsNotPartOfTheBucket (0.00s)
+```
+
+Negative control, the same PostgreSQL command with the password changed to `wrong` —
+these FAIL rather than skip, which is what says they were really talking to a server:
+
+```
+--- FAIL: TestPostgres_timestampColumnsCollateC
+    failed SASL auth: FATAL: password authentication failed for user "postgres" (SQLSTATE 28P01)
+--- FAIL: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace
+    failed SASL auth: FATAL: password authentication failed for user "postgres" (SQLSTATE 28P01)
+```
+
+### ⚠️ One correction to this file, found while merging
+
+Several notes above (the B3 carry-over list, the sweep's rule, `workspaceOfUser`'s doc)
+say that a write omitting `workspace_id` on a Platform route "lands in `default`,
+silently". That is true of a handle that never sets the parameter at all. It is **not**
+what the platform handle does: `OpenPair` binds `''` before every statement, so
+`current_setting('app.workspace_id', true)` returns the empty string rather than NULL,
+`COALESCE` keeps it, and the row fails the foreign key to `workspaces(id)` with 23503.
+The sweep's own negative control is consistent with this — it failed at "could not issue
+code" rather than by landing a row in `default`, and PROGRESS recorded the mechanism as
+unconfirmed at the time. **The remedy is identical either way** (name `workspace_id`), so
+nothing built on that reasoning is wrong; but "silently lands in `default`" overstates how
+quiet the failure is, and the distinction matters to anyone debugging a 23503 from a
+Platform route. Not corrected in place above, because those notes are the record of what
+was believed when each boundary was written.
+
+## D11, the remaining half — the plan for B6
+
+The verify side is in. What is missing is that **nothing mints an SSO token yet**, so the
+endpoint is unreachable in a real login. Three specifics, so B6 does not re-derive them:
+
+1. **Which callback.** `finishOAuthLogin` in `internal/handler/auth_oauth.go`, the single
+   tail both `CallbackGoogle` and `CallbackMicrosoft` funnel into — it is where
+   `createSession` is called today. In multi-tenant mode it must not set a cookie at all:
+   the callback runs on the identity host (`GET /v1/auth/callback`, Platform), and a
+   cookie for the identity host is no use to a tenant on its own domain. It mints a token
+   and redirects instead. Single-tenant keeps setting the cookie, unchanged.
+
+   ⛔ **And it carries the same hole the SSO endpoint just had, live, today:** its lookup
+   is `SELECT id, archived_at FROM users WHERE email = ?` on the platform handle. For an
+   address that exists in two workspaces that resolves an arbitrary one and starts a
+   session for it. It is not a regression from this merge — it predates the branch — and
+   it cannot be fixed in place, because a Platform route with no `wid` has nothing to
+   scope BY. That is the argument for doing D11's mint half rather than deferring it:
+   until the workspace reaches this function, OAuth login on a multi-tenant instance is
+   guessing.
+
+2. **Which state field carries the workspace.** ⚠️ **Not `EncryptState` — that is a
+   provider-client helper (`internal/zoom`, `internal/caldav`, gcal) for the CONNECT
+   flows, and it encrypts a user id.** The login flow's state is different and simpler:
+   `newOAuthState` mints a 16-byte random nonce, returns it as the `state` URL parameter
+   and sets the same value in the HttpOnly `calnode_oauth_state` cookie; the callback
+   compares the two and consumes the cookie. There is no room in it for a workspace and
+   no signature over it.
+
+   So the workspace goes in the **cookie half**, not the URL half: make the cookie value
+   `<nonce>|<wid>`, keep sending the bare nonce as the `state` parameter, and have the
+   callback split the cookie, compare the nonce, and take the `wid`. The visitor can
+   rewrite the URL parameter, which then simply fails the comparison; the half that is
+   trusted is the half only we ever wrote. `consumeOAuthReturn` (defined in
+   `mcp_oauth_authorize.go`, called from `finishOAuthLogin`) is the precedent: a second
+   piece of callback context riding a cookie rather than a URL.
+
+   The workspace is known at the login START (`GET /v1/auth/login`), from the Host the
+   person clicked "sign in with Google" on. ⚠️ That route is **Platform** today because
+   the callbacks have to be, so B6 must resolve the workspace there explicitly with
+   `workspaceByHost` and 404 an unknown host exactly as `HostWorkspace` would — a resolver
+   cannot do it, or the callback would need a tenant Host it does not have.
+
+3. **How the token is minted.** Reuse `sso.go`'s own claim shape, signed with
+   `CALNODE_SSO_SHARED_SECRET` (HS256, the verifier is deliberately not a JWT library) —
+   ⛔ which means the SSO endpoint must be CONFIGURED for multi-tenant OAuth login to
+   work at all, and `config.Validate` should refuse `MULTI_TENANT` + a Google or Microsoft
+   OAuth app + an empty `CALNODE_SSO_SHARED_SECRET` rather than letting every social login
+   500 at the last step. Claims: `iss` = this instance's `BASE_URL`, `aud` =
+   `https://<ws.public_host>` (what `ssoAudience` checks), `wid` = the state's workspace,
+   `sub` = the verified email from the provider, `name`, `role` = `member` (the OAuth
+   callback is not an authority on roles; `ssoResolveUser` leaves an existing user's role
+   alone and a new one is a member unless an invite said otherwise), `iat`/`exp` = now and
+   now + 30s, `jti` = `uid.New()`. Then
+   `302 https://<ws.public_host>/v1/auth/sso?token=…&next=<destination>`, where
+   `<destination>` is what `finishOAuthLogin` would have redirected to itself: `/admin`,
+   or the `consumeOAuthReturn` value when the login was started by an MCP Connect flow
+   (already validated by `safeLocalPath`, which permits only `/oauth/authorize`).
+   ⚠️ **That second case needs a decision, not a copy.** `/oauth/authorize` is an identity-host
+   endpoint and its consent-step cookies were set there, so sending it to the tenant's public
+   host would arrive with none of them. Either keep the Connect flow's tail on the identity
+   host (mint no token, set the cookie there as today, since an MCP consent is not a
+   booker-facing surface) or hand off first and bounce back — the first is smaller and is
+   what the shape of the rest of D11 suggests.
+   ⚠️ The `next` value must go through `ssoNextPath`'s rules on the way in, not just on
+   the way out, or the redirect the callback builds is an open redirect that happens to be
+   validated one hop later.
+   ⚠️ And the calendar connect callbacks are the same shape but NOT the same fix: they
+   store tokens rather than mint a session, so they need the state's `wid` to write the
+   `calendar_connections` row through `forWorkspace(ws)` and then redirect to that
+   workspace's `/admin/calendar?connected=true` — no SSO token involved.
+

From 3c33e7ab250bbbc0c9c41d3fe405ba7de83fd05c Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 05:42:59 -0400
Subject: [PATCH 38/51] handler: a reschedule's reminder must not lose to the
 create that preceded it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

⛔ A booking created and rescheduled inside the same second could keep its reminder
pinned to the ORIGINAL time, permanently, with no error logged anywhere.

Two detached goroutines write the same row. The CREATE path
(enqueueBookingReminders -> enqueueReminder) and the RESCHEDULE path
(rescheduleSideEffects -> replaceReminderJobs) both marshal the identical payload
{booking_id, hours_before}, and jobs carries a unique on (workspace_id, type, payload),
so exactly one row can exist per (booking, hours_before). replaceReminderJobs deletes
the booking's non-running reminder rows and re-inserts them at the new time. The losing
interleaving is:

    reschedule: DELETE ...            (create's row not yet committed, so invisible)
    create:     INSERT at the OLD time
    reschedule: INSERT at the NEW time  -> conflict -> ON CONFLICT DO NOTHING -> dropped

The reschedule's own row is the one discarded, and the attendee is then reminded about a
time the meeting no longer has - or not at all, if the old run_at is already past.

Fix: the reschedule INSERT upserts.

    ON CONFLICT (workspace_id, type, payload) DO UPDATE
       SET run_at = excluded.run_at, status = 'pending', attempts = 0
     WHERE jobs.status <> 'running'

The create side deliberately KEEPS DO NOTHING: a create must never overwrite a
reschedule, and by the time the two can collide the reschedule is the later fact. With
DO UPDATE on one side only, all three interleavings agree on the reschedule's run_at.

The arbiter is the index's exact column set, read from migration 00060 rather than
assumed: both engines declare (workspace_id, type, payload) after it (the (type, payload)
lines at sqlite:161 and postgres:268 are the Down sections). On PostgreSQL a conflict
target that matches no index is a runtime error, not a compile error.

What it does to a `done` row for the same payload - i.e. a reschedule after the reminder
has already fired: nothing, because such a row never reaches this statement. The DELETE
above spares only 'running', so an already-fired reminder is removed and re-inserted
fresh at the new time. That is the intended semantics: the attendee was reminded about a
time that has since moved, so they are owed another reminder at the new one. The
alternative - leaving the done row and skipping the new reminder - would silently drop a
notification for a meeting whose time changed after it was announced.

WHERE jobs.status <> 'running' preserves the invariant the DELETE already encodes: a job
the worker has claimed is executing now, and resetting it to pending underneath would
either double-send or be clobbered by the worker's own completion write. A running
conflict leaves the row alone, exactly as today.

Tests
-----

internal/handler/reminder_race_test.go forces the losing interleaving rather than waiting
for it: the create-side row is inserted inside an UNCOMMITTED transaction, so it is
invisible to the DELETE and already owns the key, which makes the reschedule's INSERT
block until that transaction commits. The test waits on pg_stat_activity for a backend to
be genuinely lock-waiting before committing, and FAILS if none ever is - a run that never
reached the interleaving would otherwise pass whatever ON CONFLICT does. PostgreSQL only,
with a loud skip: SQLite runs on one connection by design, so neither the interleaving nor
the race can be constructed there.

Negative control, DO NOTHING put back:

    --- FAIL: TestReplaceReminderJobs_upsertSurvivesTheLosingInterleaving
        surviving reminder run_at = 2026-09-15T10:00:00Z; want 2026-09-18T09:00:00Z
        (the rescheduled time). 2026-09-15T10:00:00Z is the ORIGINAL time, which is what
        ON CONFLICT DO NOTHING leaves behind

TestRescheduleBooking_updatesReminderJob is fixed as a test too, because it reported this
bug as something else entirely: it polled for "any run_at that is not the old string",
kept the last value read when its 2s deadline expired, and then asserted on it - so a
real failure surfaced as "run_at is three days wrong" rather than as a timeout. It now
polls for the WANTED run_at, fails naming the timeout and both values, and reads with
ORDER BY run_at DESC LIMIT 1 (an event type may have several reminder offsets, so
QueryRow without an order returns an arbitrary one on PostgreSQL and a stable one on
SQLite - a test that passes on one engine and flakes on the other).

⚠️ This is a PRE-EXISTING upstream race, not a regression from the platform-hooks merge.
Both writers already produced the identical payload before it. My earlier attribution
(0 failures in 60 runs before, 2 in 60 after) was weak evidence: at a ~3% rate a clean
run of 60 is unremarkable.

Gates
-----

  gofmt -l . empty, go vet ./... clean, go build ./... clean
  go test -count=30 (reschedule + race tests): 0 failures of 30 on PostgreSQL, 0 of 30
    on SQLite (was 2 of 60 on PostgreSQL)
  go test -count=1 ./... rc=0 on SQLite (30/30)
  go test -count=1 ./internal/handler/ ./internal/worker/ rc=0 on PostgreSQL
---
 internal/handler/booking_handler.go      |  35 +++++-
 internal/handler/export_internal_test.go |  17 +++
 internal/handler/reminder_race_test.go   | 135 +++++++++++++++++++++++
 internal/handler/reschedule_test.go      |  44 ++++++--
 4 files changed, 223 insertions(+), 8 deletions(-)
 create mode 100644 internal/handler/export_internal_test.go
 create mode 100644 internal/handler/reminder_race_test.go

diff --git a/internal/handler/booking_handler.go b/internal/handler/booking_handler.go
index b675c4e..aa54a5a 100644
--- a/internal/handler/booking_handler.go
+++ b/internal/handler/booking_handler.go
@@ -1970,10 +1970,43 @@ func (h *Handler) replaceReminderJobs(ctx context.Context, bookingID, etID strin
 		if err != nil {
 			return fmt.Errorf("replace reminder jobs: marshal payload: %w", err)
 		}
+		// ⛔ UPSERT, not DO NOTHING, and the difference is a silently wrong reminder.
+		//
+		// This runs in the detached rescheduleSideEffects goroutine, and the booking's
+		// CREATE path enqueues its reminders from a detached goroutine too. Both write
+		// the identical payload {booking_id, hours_before}, and jobs carries a unique on
+		// (workspace_id, type, payload) — so if the create-side INSERT lands after the
+		// DELETE above and before this statement, DO NOTHING would drop the rescheduled
+		// row and leave the reminder pinned to the ORIGINAL time, permanently and with
+		// no error anywhere. Measured at 2 failures in 60 runs on PostgreSQL; the window
+		// is one booking created and rescheduled inside the same second.
+		//
+		// DO UPDATE makes all three interleavings agree on the same answer: the
+		// reschedule's run_at. The create side deliberately keeps DO NOTHING — a create
+		// must never overwrite a reschedule, and by the time the two can collide the
+		// reschedule is the later fact.
+		//
+		// The arbiter is the index's exact column set, read from migration 00060 rather
+		// than assumed: both engines declare (workspace_id, type, payload) after it, and
+		// on PostgreSQL a target that does not match an index is a runtime error rather
+		// than a compile one.
+		//
+		// A `done` row for this payload never reaches this statement: the DELETE above
+		// spares only 'running', so an already-fired reminder is removed and re-inserted
+		// fresh. That is the intended semantics — the attendee was reminded about a time
+		// that has since moved, so they are owed another reminder at the new one.
+		//
+		// ⚠️ WHERE jobs.status <> 'running' preserves the invariant the DELETE already
+		// encodes: a job the worker has claimed is being executed right now, and
+		// resetting it to pending underneath would either double-send or be clobbered by
+		// the worker's own completion write. A running conflict therefore leaves the row
+		// alone, which is exactly what happens today.
 		if _, err := tx.ExecContext(ctx, `
 			INSERT INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
 			VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)
-			ON CONFLICT DO NOTHING`,
+			ON CONFLICT (workspace_id, type, payload) DO UPDATE
+			   SET run_at = excluded.run_at, status = 'pending', attempts = 0
+			 WHERE jobs.status <> 'running'`,
 			uid.New(), string(payload), runAt.Format(time.RFC3339)); err != nil {
 			return fmt.Errorf("replace reminder jobs: insert: %w", err)
 		}
diff --git a/internal/handler/export_internal_test.go b/internal/handler/export_internal_test.go
new file mode 100644
index 0000000..7c72656
--- /dev/null
+++ b/internal/handler/export_internal_test.go
@@ -0,0 +1,17 @@
+package handler
+
+import (
+	"context"
+	"time"
+)
+
+// Test-only bridges. This file is a _test.go, so these identifiers exist for
+// handler_test and are absent from any real build of the package — the alternative,
+// exporting replaceReminderJobs, would widen the production API to serve one test.
+
+// ReplaceReminderJobsForTest calls the unexported reminder replacement, so the external
+// test package can drive the exact statement the reschedule path runs rather than a
+// copy of it. A test that re-typed the SQL would pass with the production code broken.
+func ReplaceReminderJobsForTest(h *Handler, ctx context.Context, bookingID, etID string, newStart time.Time) error {
+	return h.replaceReminderJobs(ctx, bookingID, etID, newStart)
+}
diff --git a/internal/handler/reminder_race_test.go b/internal/handler/reminder_race_test.go
new file mode 100644
index 0000000..acb6ab3
--- /dev/null
+++ b/internal/handler/reminder_race_test.go
@@ -0,0 +1,135 @@
+package handler_test
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/handler"
+	"github.com/calnode/calnode/internal/uid"
+)
+
+// The reminder-replacement race, forced rather than waited for.
+//
+// Two detached goroutines write the same reminder payload: the booking CREATE path
+// (enqueueBookingReminders) and the RESCHEDULE path (replaceReminderJobs). jobs carries a
+// unique on (workspace_id, type, payload), so exactly one row can exist per
+// (booking, hours_before) — and the losing interleaving is:
+//
+//	reschedule: DELETE reminder rows for this booking   (create's row not yet visible)
+//	create:     INSERT the reminder row at the OLD time
+//	reschedule: INSERT the reminder row at the NEW time -> conflict
+//
+// With ON CONFLICT DO NOTHING the last step is a silent no-op and the reminder stays
+// pinned to the original time forever. With DO UPDATE it wins, which is what this holds.
+//
+// ⛔ The interleaving is forced by the unique index itself, not by a sleep: the
+// create-side row is inserted inside an UNCOMMITTED transaction, so it is invisible to
+// the DELETE and yet already owns the key — which makes the reschedule's INSERT BLOCK
+// until that transaction commits. The test waits for a backend to actually be
+// lock-waiting before committing, so a run where the interleaving was never reached fails
+// loudly instead of passing on the easy path.
+func TestReplaceReminderJobs_upsertSurvivesTheLosingInterleaving(t *testing.T) {
+	h, database, key, _ := setupWorkspaceWithDB(t)
+	ctx := context.Background()
+
+	if database.Dialect() != db.DialectPostgres {
+		t.Skip("LOUD SKIP: this needs two concurrent connections to hold one uncommitted " +
+			"row while another transaction blocks on its key. SQLite runs on a single " +
+			"connection by design (it is what serialises write transactions there), so " +
+			"the interleaving cannot be constructed and the race cannot occur either.")
+	}
+
+	slug, etID := seedEventTypeHTTP(t, h, key)
+	bookStart := futureAt(10, 10, 0)
+	newStart := futureAt(13, 9, 0)
+	bookingID := createBookingViaHTTP(t, h, slug, bookStart.Format(time.RFC3339))
+
+	// Clean slate: drop whatever the create path enqueued, so the only rows in play are
+	// the ones this test writes.
+	if _, err := database.ExecContext(ctx,
+		`DELETE FROM jobs WHERE type = 'reminder.send'`); err != nil {
+		t.Fatalf("clear reminder jobs: %v", err)
+	}
+
+	oldRunAt := bookStart.Add(-24 * time.Hour).UTC().Format(time.RFC3339)
+	wantRunAt := newStart.Add(-24 * time.Hour).UTC().Format(time.RFC3339)
+	payload := fmt.Sprintf(`{"booking_id":%q,"hours_before":24}`, bookingID)
+
+	// The create side's insert, held open. Identical payload, OLD run_at.
+	tx, err := database.BeginTx(ctx, nil)
+	if err != nil {
+		t.Fatalf("begin create-side tx: %v", err)
+	}
+	defer tx.Rollback() //nolint:errcheck
+	if _, err := tx.ExecContext(ctx, `
+		INSERT INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
+		VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)
+		ON CONFLICT (workspace_id, type, payload) DO NOTHING`,
+		uid.New(), payload, oldRunAt); err != nil {
+		t.Fatalf("create-side insert: %v", err)
+	}
+
+	// The reschedule, which will delete nothing (the row above is invisible) and then
+	// block on its key.
+	replaced := make(chan error, 1)
+	go func() { replaced <- handler.ReplaceReminderJobsForTest(h, ctx, bookingID, etID, newStart) }()
+
+	waitForLockWaiter(t, database)
+
+	if err := tx.Commit(); err != nil {
+		t.Fatalf("commit create-side tx: %v", err)
+	}
+	if err := <-replaced; err != nil {
+		t.Fatalf("replaceReminderJobs: %v", err)
+	}
+
+	var rows int
+	if err := database.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM jobs WHERE type = 'reminder.send'`).Scan(&rows); err != nil {
+		t.Fatalf("count reminder jobs: %v", err)
+	}
+	if rows != 1 {
+		t.Errorf("reminder rows = %d; want 1 — the unique on (workspace_id, type, payload) "+
+			"admits exactly one row per (booking, hours_before)", rows)
+	}
+
+	var gotRunAt, status string
+	if err := database.QueryRowContext(ctx,
+		`SELECT run_at, status FROM jobs WHERE type = 'reminder.send'`).Scan(&gotRunAt, &status); err != nil {
+		t.Fatalf("read surviving reminder job: %v", err)
+	}
+	if gotRunAt != wantRunAt {
+		t.Errorf("surviving reminder run_at = %s; want %s (the rescheduled time). "+
+			"%s is the ORIGINAL time, which is what ON CONFLICT DO NOTHING leaves behind",
+			gotRunAt, wantRunAt, oldRunAt)
+	}
+	if status != "pending" {
+		t.Errorf("surviving reminder status = %q; want pending", status)
+	}
+}
+
+// waitForLockWaiter blocks until some backend in this database is waiting on a lock,
+// which is the reschedule's INSERT queueing behind the uncommitted key. It fails rather
+// than returning if that never happens: without the block, the test would be exercising
+// the ordinary interleaving and proving nothing.
+func waitForLockWaiter(t *testing.T, database *db.DB) {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) {
+		var waiters int
+		if err := database.QueryRow(`
+			SELECT COUNT(*) FROM pg_stat_activity
+			WHERE wait_event_type = 'Lock' AND datname = current_database()`).Scan(&waiters); err != nil {
+			t.Fatalf("read pg_stat_activity: %v", err)
+		}
+		if waiters > 0 {
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	t.Fatal("no backend ever blocked on a lock, so the losing interleaving was never " +
+		"reached and this test would pass whatever ON CONFLICT does")
+}
diff --git a/internal/handler/reschedule_test.go b/internal/handler/reschedule_test.go
index 7390481..852dc89 100644
--- a/internal/handler/reschedule_test.go
+++ b/internal/handler/reschedule_test.go
@@ -111,27 +111,57 @@ func TestRescheduleBooking_updatesReminderJob(t *testing.T) {
 	// is one. The Scan error is captured rather than discarded: swallowing it turned a
 	// "json_extract does not exist" into an empty run_at and a two-second poll that
 	// then reported itself as a time-parsing failure.
+	//
+	// ⛔ Three things here are about a flake, not about style, and each one hid the
+	// timeout it was supposed to report. Measured at 2 failures in 60 PostgreSQL runs
+	// after feat/platform-hooks merged, 0 in 60 before it.
+	//
+	//  1. The loop polls for the WANTED run_at. Breaking on "anything that is not the
+	//     old string" meant any stale or unrelated row ended the wait, and a row whose
+	//     text differs while its instant does not (a second reminder offset, a
+	//     differently-formatted stamp) counted as success.
+	//  2. Falling out of the loop on the DEADLINE is a Fatal that says so. Before, the
+	//     last value read stayed in runAt and was asserted on, so a two-second timeout
+	//     reported itself as "run_at is three days wrong" — a wrong answer to a
+	//     question nobody asked, and the reason this took a bisect to attribute.
+	//  3. ORDER BY run_at DESC LIMIT 1 makes the read deterministic. An event type may
+	//     have several reminder offsets, so QueryRow without an order returns an
+	//     arbitrary one of them on PostgreSQL and a stable one on SQLite — a test that
+	//     passes on one engine and flakes on the other.
+	//  4. The deadline is proportional to what is being waited FOR. replaceReminderJobs
+	//     is the LAST step of the detached rescheduleSideEffects goroutine, after two
+	//     emails and a webhook enqueue, and that goroutine gives itself 30s. Two
+	//     seconds was not a correctness bound, it was a bet on scheduling — and on the
+	//     PostgreSQL lane, where every one of those steps is a round trip and the
+	//     package runs its tests in parallel on 4 cores, it lost about 3% of the time.
+	//     Ten seconds still fails a real regression promptly; it just no longer fails a
+	//     busy machine.
 	var runAt string
 	var lastErr error
 	payloadMatch := database.Dialect().SQL(
 		`json_extract(payload, '$.booking_id') = ?`,
 		`payload::json ->> 'booking_id' = ?`)
-	deadline := time.Now().Add(2 * time.Second)
-	for time.Now().Before(deadline) {
+	wantRunAt := wantNewReminder.Format(time.RFC3339)
+	deadline := time.Now().Add(10 * time.Second)
+	for {
 		lastErr = database.QueryRowContext(ctx, `
 			SELECT run_at FROM jobs
 			WHERE type = 'reminder.send'
 			  AND `+payloadMatch+`
-			  AND status = 'pending'`, bookingID).
+			  AND status = 'pending'
+			ORDER BY run_at DESC
+			LIMIT 1`, bookingID).
 			Scan(&runAt)
-		if runAt != "" && runAt != oldReminderAt.Format(time.RFC3339) {
+		if runAt == wantRunAt {
 			break
 		}
+		if !time.Now().Before(deadline) {
+			t.Fatalf("timed out after 10s waiting for the rescheduled reminder job: "+
+				"latest pending run_at = %q, want %q (old was %q); last query error: %v",
+				runAt, wantRunAt, oldReminderAt.Format(time.RFC3339), lastErr)
+		}
 		time.Sleep(10 * time.Millisecond)
 	}
-	if runAt == "" {
-		t.Fatalf("no pending reminder job appeared within 2s; last query error: %v", lastErr)
-	}
 
 	gotRunAt, err := time.Parse(time.RFC3339, runAt)
 	if err != nil {

From be4ce91903e709ba305a332ff728c08b01a02489 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 06:10:07 -0400
Subject: [PATCH 39/51] =?UTF-8?q?handler:=20the=20platform=20API=20?=
 =?UTF-8?q?=E2=80=94=20provision,=20read,=20patch=20and=20delete=20a=20wor?=
 =?UTF-8?q?kspace=20(D12)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

internal/handler/platform.go. Four routes on the identity host, all Platform-wrapped,
bearer CALNODE_PLATFORM_TOKEN with a constant-time compare:

  POST   /v1/platform/workspaces        201 {api_key, webhook_secret}, once
  GET    /v1/platform/workspaces/{id}
  PATCH  /v1/platform/workspaces/{id}   public_host, status (active|suspended), slug
  DELETE /v1/platform/workspaces/{id}   cascade, 200 {recording_object_keys: [...]}

Two gates that answer differently on purpose: with the token unset, or on a single-tenant
instance, every route 404s (the API does not exist here, and a prober should not learn
which of the two reasons applies - it is Setup's mirror image, which 404s in multi-tenant
mode). With the token set, a wrong token is 401, so an operator with a typo can tell that
apart from a missing feature.

Provisioning is ONE transaction: the workspaces row, server_settings (id = 1 per
workspace, D8), the owner user, that owner's first cno_ key, the webhook subscription, and
the default event type with its availability rules. Either the tenant exists complete or
it does not exist - a half-provisioned workspace answers requests with no owner, or serves
a booking page with no availability. The 409 test asserts the rollback, not just the code.

⛔ Every INSERT names workspace_id. h.db here is the platform handle: it bypasses the
policies and binds '', so an unnamed column resolves to '' and the row fails its foreign
key to workspaces(id) with SQLSTATE 23503. Reads are equally unscoped and each carries its
own workspace_id predicate - there is no policy behind this file to catch a forgotten
WHERE.

⚠️ owner_timezone is stored as the owner's iana_timezone, NOT UTC. availability_rules holds
local HH:MM with no zone of its own, so defaulting the owner's zone would silently move
the workspace's working hours.

Migration 00062: server_settings gains embed_allowed_origins and stt_base_url
------------------------------------------------------------------------------

Both are in the settled contract's `defaults` and neither had a column. Both are
per-TENANT facts the environment cannot express: one process-wide EMBED_ALLOWED_ORIGINS
would let one tenant's allowlist govern another's embed, and the STT host is a residency
knob, which is a property of the tenant. Default '' means "fall back to the process-wide
value", so single-tenant and every existing row behave as before. knownMigrationCount
61 -> 62.

⚠️ They are WRITTEN and not yet READ: the embed CORS check still uses
config.EmbedAllowedOrigins and the notetaker still uses config.STTBaseURL, so a
multi-tenant deployment currently shares one embed allowlist and one STT host. Storing
them now means a provisioned workspace does not silently lose what the caller sent; wiring
the readers needs the per-workspace settings cache (D7) and is separate work.

webhook.NewSecret
-----------------

The webhook secret's encoding gets exactly one implementation. The column holds the
AES-GCM of the RAW secret bytes, Sign uses those bytes as the HMAC key, and the string
handed to the subscriber is their hex. A second implementation that encrypted the hex
string would store a key the subscriber cannot reproduce, and every delivery would fail
its signature check with nothing in the logs to point at. A caller-supplied secret must
be hex and at least 16 bytes; absent, one is generated. The INSERT stays in the
provisioning transaction, where it can name workspace_id.

⛔ Decision: the `default` workspace is SUSPENDED at multi-tenant boot
---------------------------------------------------------------------

db.SuspendDefaultWorkspace, called from main right after EnableRLS, idempotent, and
non-fatal (a sweep over an empty workspace is waste, not damage).

Migration 00060 seeds `default` because it is the workspace every single-tenant row
belongs to and the one SQLite's column default names. On a multi-tenant instance it is a
tenant nobody owns - no public_host, no users, no settings - and while it is active every
background sweep enumerates it, because activeWorkspaceIDs filters on status = 'active'.

NOT in the migration, which is the point: a migration cannot see MULTI_TENANT, and in
single-tenant mode `default` IS the workspace, so a suspended row there would make Scoped
answer 503 to every request on the instance. Suspension rather than deletion because the
row is referenced by server_settings and by whatever single-tenant data a converted
instance still holds, and because one status flip removes it from every sweep at once
instead of adding a second exclusion rule a new loop could forget.

Two things the tests paid for
-----------------------------

⚠️ httptest.NewRequest does not populate mux path values - they come from the pattern
ServeMux matched, and these tests call the handler directly. Every {id} route therefore
read an empty id and answered 404, which looks exactly like a missing workspace.

⚠️ location_type and routing_mode carry CHECK constraints (migration 00001) admitting no
'none' or 'single'. The seeded event type is 'link' / 'fixed', the schema's own defaults.
The first run failed with 23514 as a bare 500, visible only with a live logger.

Gates
-----

  gofmt -l . empty, go vet ./... clean, go build ./... clean
  go test -count=1 ./... rc=0 on SQLite (30/30)
  PostgreSQL: internal/handler rc=0 (410.2s), internal/db rc=0, internal/server rc=0,
    internal/webhook rc=0

  --- PASS: TestPlatform_createProvisionsTheWholeWorkspace (1.04s)
  --- PASS: TestPlatform_createdWorkspacesAreIsolated (1.25s)
  --- PASS: TestPlatform_duplicateIDOrHostIs409 (1.10s)
  --- PASS: TestPlatform_getPatchDelete (1.08s)
  --- PASS: TestPlatform_tokenGate (1.08s)
  --- PASS: TestPlatform_404WithoutATokenConfigured (0.73s)
  --- PASS: TestPlatform_404OnASingleTenantInstance (0.74s)
  --- PASS: TestPlatform_createValidation (11.47s)
  --- PASS: TestPostgres_defaultWorkspaceIsSuspendedAtMultiTenantBoot (0.76s)
  --- PASS: TestEveryRouteIsClassified  (176 routes: 31 host, 107 credential, 30 platform, 8 allowlisted)
---
 PROGRESS.md                                   | 121 ++++
 cmd/calnode/main.go                           |   7 +
 internal/db/default_workspace_test.go         |  83 +++
 .../00062_workspace_settings_columns.sql      |  27 +
 .../00062_workspace_settings_columns.sql      |  14 +
 internal/db/postgres_test.go                  |   2 +-
 internal/db/tenancy.go                        |  28 +
 internal/handler/platform.go                  | 588 ++++++++++++++++++
 internal/handler/platform_test.go             | 468 ++++++++++++++
 internal/handler/shared.go                    |   5 +
 internal/server/routes_classified_test.go     |   7 +
 internal/server/server.go                     |  16 +
 internal/webhook/webhook.go                   |  38 ++
 13 files changed, 1403 insertions(+), 1 deletion(-)
 create mode 100644 internal/db/default_workspace_test.go
 create mode 100644 internal/db/migrations/postgres/00062_workspace_settings_columns.sql
 create mode 100644 internal/db/migrations/sqlite/00062_workspace_settings_columns.sql
 create mode 100644 internal/handler/platform.go
 create mode 100644 internal/handler/platform_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 03b31f9..da3d4bc 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1652,6 +1652,127 @@ quiet the failure is, and the distinction matters to anyone debugging a 23503 fr
 Platform route. Not corrected in place above, because those notes are the record of what
 was believed when each boundary was written.
 
+## Boundary 6, part one — the platform API (D12): create, get, patch, delete
+
+`internal/handler/platform.go`. Four routes on the identity host, all `Platform`-wrapped,
+bearer `CALNODE_PLATFORM_TOKEN` compared with `subtle.ConstantTimeCompare`.
+
+### Two gates, and they answer differently on purpose
+
+| state | answer | why |
+|---|---|---|
+| token unset | **404** | the API does not exist here, and a prober should not learn whether it could |
+| single-tenant instance | **404** | there are no workspaces to provision; same reasoning, and it is Setup's mirror image (Setup 404s in multi-tenant mode) |
+| token set, wrong token | **401** | an operator with a typo needs to tell that apart from a missing feature |
+
+### Provisioning is one transaction, and every INSERT names `workspace_id`
+
+The workspaces row, `server_settings` (id = 1 per workspace, D8), the owner user, that
+owner's first `cno_` key, the webhook subscription, the default event type and its
+availability rules. Either the tenant exists complete or it does not exist: a
+half-provisioned workspace would answer requests with no owner, or serve a booking page
+with no availability. `TestPlatform_duplicateIDOrHostIs409` asserts the rollback, not just
+the status code.
+
+⛔ **Every INSERT names `workspace_id` explicitly**, which is the rule this file exists to
+obey rather than to demonstrate. `h.db` here is the platform handle: it bypasses the
+policies and binds `''`, so an unnamed column resolves to `''` and the row fails its
+foreign key with 23503. **Reads are equally unscoped and carry their own predicate** —
+there is no policy behind this file to catch a forgotten `WHERE`.
+
+⚠️ `owner_timezone` is stored as the owner's `iana_timezone`, **not** UTC, and that is a
+correctness requirement rather than a nicety: `availability_rules` holds local `HH:MM` with
+no zone of its own, so defaulting the owner's zone would silently move the workspace's
+working hours. A test pins the stored value.
+
+### Two settings had no column, so migration 00062 gives them one
+
+`defaults.embed_allowed_origins` and `defaults.stt_base_url` are in the settled contract
+and `server_settings` had nowhere to put either — the enumerated column list has neither.
+Both are per-TENANT facts that the environment cannot express: one process-wide
+`EMBED_ALLOWED_ORIGINS` would let one tenant's allowlist govern another's embed, and the
+STT host is a residency knob, which is a property of the tenant.
+
+⚠️ **They are WRITTEN and not yet READ.** The embed CORS check still uses
+`config.EmbedAllowedOrigins` and the notetaker still uses `config.STTBaseURL`, so a
+multi-tenant deployment currently shares one embed allowlist and one STT host. Storing them
+now means a provisioned workspace does not silently lose what the caller sent; wiring the
+readers is separate work, because each has to go through the per-workspace settings cache
+(D7) rather than a process-wide read. Named here so it is not mistaken for done.
+`knownMigrationCount` 61 → 62.
+
+### The webhook secret's encoding has exactly one implementation
+
+`webhook.NewSecret` is new and the platform API calls it: the column holds the AES-GCM of
+the **raw** secret bytes, `Sign` uses those bytes as the HMAC key, and the string handed to
+the subscriber is their **hex**. A second implementation that encrypted the hex string
+would store a key the subscriber cannot reproduce, and every delivery would fail its
+signature check with nothing in the logs to point at. A caller-supplied secret must
+therefore be hex and at least 16 bytes; absent, one is generated. The INSERT itself stays
+in the provisioning transaction, where it can name `workspace_id`.
+
+### ⛔ Decision: the `default` workspace is SUSPENDED at multi-tenant boot
+
+`db.SuspendDefaultWorkspace`, called from `main` right after `EnableRLS`, idempotent, and
+non-fatal on error (a sweep over an empty workspace is waste, not damage).
+
+Migration 00060 seeds `default` because it is the workspace every single-tenant row belongs
+to and the one SQLite's column default names. On a multi-tenant instance it is a tenant
+nobody owns: no `public_host` (deliberately, so no Host reaches it), no users, no settings —
+and while it is `active`, every background sweep enumerates it, because
+`activeWorkspaceIDs` filters on `status = 'active'`.
+
+**Not in the migration, and that is the whole point:** a migration cannot see
+`MULTI_TENANT`, and in single-tenant mode `default` **is** the workspace — a suspended row
+there would make `Scoped` answer 503 to every request on the instance. The mode decides,
+and the mode is only known at boot. Suspension rather than deletion because the row is
+referenced by `server_settings` and by whatever single-tenant data a converted instance
+still holds, and because one status flip removes it from every sweep at once instead of
+adding a second exclusion rule a new loop could forget.
+`TestPostgres_defaultWorkspaceIsSuspendedAtMultiTenantBoot` asserts active-after-migrate
+(what single-tenant needs), suspended-after-call, idempotence, and that a real workspace
+beside it is untouched.
+
+### ⚠️ Two things the tests paid for
+
+- **`httptest.NewRequest` does not populate mux path values.** They come from the pattern
+  `ServeMux` matched, and these tests call the handler directly — so every `{id}` route
+  read an empty id and answered **404, which looks exactly like a missing workspace**. The
+  helper calls `SetPathValue` now.
+- **`location_type` and `routing_mode` have CHECK constraints** (migration 00001) that
+  admit no `'none'` or `'single'`. The event type seeds `'link'` / `'fixed'`, the schema's
+  own defaults, which is what a single-host event type created in the admin UI gets. The
+  first run failed with 23514 as a bare 500, and the reason was only visible with a live
+  logger.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+`go test -count=1 ./...` **rc=0 on SQLite (30/30)**.
+PostgreSQL lane, per package: `internal/handler` **rc=0** (410.2s), `internal/db`,
+`internal/server`, `internal/webhook` **rc=0**.
+
+```
+--- PASS: TestPlatform_createProvisionsTheWholeWorkspace (1.04s)
+--- PASS: TestPlatform_createdWorkspacesAreIsolated (1.25s)
+--- PASS: TestPlatform_duplicateIDOrHostIs409 (1.10s)
+--- PASS: TestPlatform_getPatchDelete (1.08s)
+--- PASS: TestPlatform_tokenGate (1.08s)          [wrong token, no token]
+--- PASS: TestPlatform_404WithoutATokenConfigured (0.73s)
+--- PASS: TestPlatform_404OnASingleTenantInstance (0.74s)
+--- PASS: TestPlatform_createValidation (11.47s)  [9 cases, each asserting nothing was left behind]
+--- PASS: TestPostgres_defaultWorkspaceIsSuspendedAtMultiTenantBoot (0.76s)
+```
+
+### Still owed by B6
+
+Export/import/erasure; the SSO + OAuth hand-off on the public host (the plan is at the end
+of this file); the vendor webhooks resolving their workspace from the row they name. D13 is
+already done (B1's `config.Validate` refuses `MULTI_TENANT` with `DEMO_MODE`) and D14
+landed with the platform-hooks merge.
+
+---
+
 ## D11, the remaining half — the plan for B6
 
 The verify side is in. What is missing is that **nothing mints an SSO token yet**, so the
diff --git a/cmd/calnode/main.go b/cmd/calnode/main.go
index 8c8b20f..1810c3c 100644
--- a/cmd/calnode/main.go
+++ b/cmd/calnode/main.go
@@ -120,6 +120,13 @@ func main() {
 			logger.Error("failed to enable row-level security; refusing to serve", "error", err)
 			os.Exit(1)
 		}
+		// The seeded `default` workspace is nobody's tenant on a multi-tenant instance;
+		// suspending it keeps the background sweeps off it. Not fatal: a sweep over an
+		// empty workspace is waste, not damage, so a failure here is worth a line in the
+		// log and not a refusal to serve.
+		if err := platform.SuspendDefaultWorkspace(context.Background()); err != nil {
+			logger.Error("could not suspend the default workspace", "error", err)
+		}
 		if err := database.VerifyRoles(context.Background()); err != nil {
 			logger.Error("database roles cannot enforce tenant isolation; refusing to serve", "error", err)
 			os.Exit(1)
diff --git a/internal/db/default_workspace_test.go b/internal/db/default_workspace_test.go
new file mode 100644
index 0000000..72ce3a8
--- /dev/null
+++ b/internal/db/default_workspace_test.go
@@ -0,0 +1,83 @@
+package db_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+)
+
+// The seeded `default` workspace on a MULTI_TENANT instance.
+//
+// Migration 00060 seeds it because it is the workspace every single-tenant row belongs to
+// and the one the SQLite column default names. On a multi-tenant instance it is a tenant
+// nobody owns: no public_host (so no Host resolves to it), no users, no settings. Left
+// active, every background sweep still enumerates it — activeWorkspaceIDs filters on
+// status = 'active' — so the instance keeps doing work on behalf of a tenant that cannot
+// receive it.
+//
+// ⛔ The decision: suspend it at multi-tenant BOOT, not in the migration. A migration
+// cannot see MULTI_TENANT, and in single-tenant mode `default` IS the workspace, so a
+// suspended row there would make Scoped answer 503 to every request on the instance. One
+// status flip removes it from every sweep at once, reusing D12's suspended semantics
+// rather than inventing a second exclusion rule that a new loop could forget.
+func TestPostgres_defaultWorkspaceIsSuspendedAtMultiTenantBoot(t *testing.T) {
+	handle := dbtest.RequirePostgres(t)
+	ctx := context.Background()
+
+	// Freshly migrated, it is active — which is what single-tenant needs.
+	var status string
+	if err := handle.QueryRow(
+		`SELECT status FROM workspaces WHERE id = ?`, db.DefaultWorkspaceID).Scan(&status); err != nil {
+		t.Fatalf("read the default workspace: %v", err)
+	}
+	if status != "active" {
+		t.Fatalf("straight after migrating, the default workspace is %q; want active — "+
+			"single-tenant mode runs as this workspace and a suspended one answers 503", status)
+	}
+
+	if err := handle.SuspendDefaultWorkspace(ctx); err != nil {
+		t.Fatalf("SuspendDefaultWorkspace: %v", err)
+	}
+	if err := handle.QueryRow(
+		`SELECT status FROM workspaces WHERE id = ?`, db.DefaultWorkspaceID).Scan(&status); err != nil {
+		t.Fatalf("read back: %v", err)
+	}
+	if status != "suspended" {
+		t.Errorf("after SuspendDefaultWorkspace the default workspace is %q; want suspended", status)
+	}
+
+	// Idempotent: boot happens more than once.
+	if err := handle.SuspendDefaultWorkspace(ctx); err != nil {
+		t.Errorf("second SuspendDefaultWorkspace: %v", err)
+	}
+
+	// The consequence that matters — it is no longer an active workspace, which is what
+	// every sweep enumerates.
+	var active int
+	if err := handle.QueryRow(
+		`SELECT COUNT(*) FROM workspaces WHERE status = 'active' AND id = ?`,
+		db.DefaultWorkspaceID).Scan(&active); err != nil {
+		t.Fatalf("count active default: %v", err)
+	}
+	if active != 0 {
+		t.Errorf("the default workspace is still counted active; every background sweep " +
+			"would keep taking a pass over it")
+	}
+
+	// A workspace that is not `default` is untouched: this is one row, not a policy.
+	if _, err := handle.Exec(
+		`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES ('acme', 'acme', 'book.acme.test', 'us', 'active')`); err != nil {
+		t.Fatalf("seed acme: %v", err)
+	}
+	if err := handle.SuspendDefaultWorkspace(ctx); err != nil {
+		t.Fatalf("third SuspendDefaultWorkspace: %v", err)
+	}
+	if err := handle.QueryRow(`SELECT status FROM workspaces WHERE id = 'acme'`).Scan(&status); err != nil {
+		t.Fatalf("read acme: %v", err)
+	}
+	if status != "active" {
+		t.Errorf("acme is %q after suspending the default workspace; want active", status)
+	}
+}
diff --git a/internal/db/migrations/postgres/00062_workspace_settings_columns.sql b/internal/db/migrations/postgres/00062_workspace_settings_columns.sql
new file mode 100644
index 0000000..44e0ea8
--- /dev/null
+++ b/internal/db/migrations/postgres/00062_workspace_settings_columns.sql
@@ -0,0 +1,27 @@
+-- +goose Up
+-- Two per-workspace settings the platform API's `defaults` carries and server_settings
+-- had nowhere to put. Both are per-TENANT facts on a multi-tenant instance, so the
+-- environment cannot express them:
+--
+--   embed_allowed_origins  the origins allowed to embed this workspace's booking page.
+--                          One tenant's allowlist must not apply to another's embed, and
+--                          EMBED_ALLOWED_ORIGINS is one process-wide value.
+--   stt_base_url           the speech-to-text endpoint host for this workspace's
+--                          notetaker. It is a residency knob (transcribe inside one
+--                          jurisdiction), and residency is a property of the tenant.
+--
+-- Both default to '' meaning "fall back to the process-wide value", so a single-tenant
+-- instance and every existing row behave exactly as before.
+--
+-- ⚠️ These columns are WRITTEN by the platform API and not yet READ: the embed CORS
+-- check still uses config.EmbedAllowedOrigins and the notetaker still uses
+-- config.STTBaseURL. Storing them first means a provisioned workspace does not silently
+-- lose the values the caller sent; wiring the readers is a separate change, because each
+-- has to go through the per-workspace settings cache (D7) rather than a process-wide
+-- read. Until then a multi-tenant deployment shares one embed allowlist and one STT host.
+ALTER TABLE server_settings ADD COLUMN embed_allowed_origins TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN stt_base_url TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN stt_base_url;
+ALTER TABLE server_settings DROP COLUMN embed_allowed_origins;
diff --git a/internal/db/migrations/sqlite/00062_workspace_settings_columns.sql b/internal/db/migrations/sqlite/00062_workspace_settings_columns.sql
new file mode 100644
index 0000000..2634535
--- /dev/null
+++ b/internal/db/migrations/sqlite/00062_workspace_settings_columns.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+-- See the Postgres half for why these two exist. Identical here: plain ADD COLUMN with a
+-- '' default, so no table is rebuilt and every existing row keeps behaving as it did.
+--
+-- SQLite cannot run multi-tenant (config.Validate refuses MULTI_TENANT without a
+-- postgres:// DSN), so on this engine the columns are only ever the empty fallback. They
+-- exist here because the two migration directories keep one file per version, and because
+-- the schema-comparison test asserts the engines agree on column sets.
+ALTER TABLE server_settings ADD COLUMN embed_allowed_origins TEXT NOT NULL DEFAULT '';
+ALTER TABLE server_settings ADD COLUMN stt_base_url TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE server_settings DROP COLUMN stt_base_url;
+ALTER TABLE server_settings DROP COLUMN embed_allowed_origins;
diff --git a/internal/db/postgres_test.go b/internal/db/postgres_test.go
index 12fcc48..cfabaf1 100644
--- a/internal/db/postgres_test.go
+++ b/internal/db/postgres_test.go
@@ -25,7 +25,7 @@ const postgresDSNEnv = "CALNODE_TEST_POSTGRES_DSN"
 // sanity check on the embedded set, not a property of PostgreSQL, so it moves with
 // every migration added — one named constant rather than the same literal in two
 // assertions, so adding one is a single edit that cannot be half-done.
-const knownMigrationCount = 61
+const knownMigrationCount = 62
 
 // openTestPostgres returns a handle scoped to a schema of its own, created for
 // this test and dropped when it finishes. A schema rather than a database because
diff --git a/internal/db/tenancy.go b/internal/db/tenancy.go
index 64fb7a0..c2b50f7 100644
--- a/internal/db/tenancy.go
+++ b/internal/db/tenancy.go
@@ -106,6 +106,34 @@ var ExemptTables = []string{
 // Table names are interpolated into the DDL because PostgreSQL takes no
 // placeholder for an identifier. They come from TenantTables, a committed
 // constant list, never from input.
+// SuspendDefaultWorkspace marks the seeded `default` workspace suspended. It runs at
+// multi-tenant boot only, and is idempotent.
+//
+// Migration 00060 seeds `default` because it is the workspace every single-tenant row
+// belongs to and the SQLite column default names it. On a MULTI_TENANT instance that row
+// is a tenant nobody owns: it has no public_host (deliberately, so no Host can reach it),
+// no users, and no settings. Left `active` it is still enumerated by every background
+// sweep — the reconciler takes a pass over it on each cycle, and any future periodic loop
+// would too — so the instance does work on behalf of a tenant that cannot receive it.
+//
+// ⛔ Suspending it at BOOT rather than in the migration is the whole point. The migration
+// cannot see MULTI_TENANT, and in single-tenant mode `default` IS the workspace: a
+// suspended row there would make Scoped answer 503 to every request on the instance. So
+// the mode decides, and the mode is only known here.
+//
+// Suspension is the right shape rather than deletion: the row is referenced by
+// server_settings and by any single-tenant data a converted instance still holds, and
+// activeWorkspaceIDs already filters on status = 'active', so one status flip removes it
+// from every sweep at once (D12's suspended semantics, reused).
+func (h *DB) SuspendDefaultWorkspace(ctx context.Context) error {
+	if _, err := h.Platform().ExecContext(ctx,
+		`UPDATE workspaces SET status = 'suspended' WHERE id = ? AND status <> 'suspended'`,
+		DefaultWorkspaceID); err != nil {
+		return fmt.Errorf("suspend the default workspace: %w", err)
+	}
+	return nil
+}
+
 func (h *DB) EnableRLS(ctx context.Context) error {
 	if h.dialect != DialectPostgres {
 		return nil
diff --git a/internal/handler/platform.go b/internal/handler/platform.go
new file mode 100644
index 0000000..a63f8f1
--- /dev/null
+++ b/internal/handler/platform.go
@@ -0,0 +1,588 @@
+package handler
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/subtle"
+	"database/sql"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/secret"
+	"github.com/calnode/calnode/internal/uid"
+	"github.com/calnode/calnode/internal/webhook"
+)
+
+// The platform API (D12). Workspace provisioning for a multi-tenant instance: create a
+// tenant, read it, change its host or status, delete it.
+//
+// Every route here is Platform-wrapped, so h.db is the platform handle — it bypasses the
+// row-level security policies and binds no workspace. Two consequences run through this
+// whole file:
+//
+//   - ⛔ EVERY INSERT NAMES workspace_id. The column default is
+//     COALESCE(current_setting('app.workspace_id', true), 'default'), and the platform
+//     handle sets that parameter to '' before each statement, so an unnamed column
+//     resolves to '' and the row fails its foreign key to workspaces(id) with SQLSTATE
+//     23503. (An earlier note in PROGRESS.md said such a row lands silently in the
+//     `default` workspace; that is what happens on a handle that never sets the
+//     parameter at all, not on the paired platform handle. The rule is the same either
+//     way, and it is the reason it is stated here rather than assumed.)
+//   - Reads are equally unscoped, so every one of them carries its own workspace_id
+//     predicate. There is no policy behind this file to catch a forgotten WHERE.
+//
+// Authentication is a bearer token from CALNODE_PLATFORM_TOKEN, compared in constant
+// time. With the token unset — or on a single-tenant instance, which has no workspaces to
+// provision — every route 404s rather than 401ing, so a prober cannot tell a
+// multi-tenant control plane from an instance that does not implement one.
+
+// SetPlatformToken configures the platform API's bearer token. Empty leaves the API off.
+// Set once at boot from config, like SetSSOSecret, so there is no lock here.
+func (h *Handler) SetPlatformToken(token string) { h.platformToken = token }
+
+// platformAuthorized gates every route in this file. It writes the response on failure
+// and reports whether the caller may proceed.
+func (h *Handler) platformAuthorized(w http.ResponseWriter, r *http.Request) bool {
+	// Off unless configured, and off on a single-tenant instance. 404 for both, because
+	// "this endpoint does not exist here" is the truth in both cases and neither answer
+	// should tell a prober which one applies.
+	if h.platformToken == "" || !h.multiTenant {
+		http.NotFound(w, r)
+		return false
+	}
+	presented := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
+	if subtle.ConstantTimeCompare([]byte(presented), []byte(h.platformToken)) != 1 {
+		h.logger.WarnContext(r.Context(), "platform api: bad token", "path", r.URL.Path)
+		h.writeError(w, http.StatusUnauthorized, "invalid platform token")
+		return false
+	}
+	return true
+}
+
+// platformWorkspaceRequest is the create body (D12), settled against the website client.
+type platformWorkspaceRequest struct {
+	ID            string `json:"id"`
+	Slug          string `json:"slug"`
+	PublicHost    string `json:"public_host"`
+	Region        string `json:"region"`
+	OwnerEmail    string `json:"owner_email"`
+	OwnerName     string `json:"owner_name"`
+	OwnerTimezone string `json:"owner_timezone"`
+	Defaults      struct {
+		EmbedAllowedOrigins []string `json:"embed_allowed_origins"`
+		Webhook             struct {
+			URL    string   `json:"url"`
+			Secret string   `json:"secret"`
+			Fields []string `json:"fields"`
+		} `json:"webhook"`
+		EventType struct {
+			Slug             string `json:"slug"`
+			Name             string `json:"name"`
+			DurationMinutes  int    `json:"duration_minutes"`
+			MinNoticeMinutes int    `json:"min_notice_minutes"`
+			MaxFutureDays    int    `json:"max_future_days"`
+			Availability     []struct {
+				DayOfWeek int    `json:"day_of_week"`
+				StartTime string `json:"start_time"`
+				EndTime   string `json:"end_time"`
+			} `json:"availability"`
+		} `json:"event_type"`
+		LiveKitURL       string `json:"livekit_url"`
+		LiveKitAPIKey    string `json:"livekit_api_key"`
+		LiveKitAPISecret string `json:"livekit_api_secret"`
+		STTBaseURL       string `json:"stt_base_url"`
+		SMTP             *struct {
+			Host     string `json:"host"`
+			Port     string `json:"port"`
+			User     string `json:"user"`
+			Pass     string `json:"pass"`
+			TLS      bool   `json:"tls"`
+			StartTLS bool   `json:"starttls"`
+			From     string `json:"from"`
+			FromName string `json:"from_name"`
+		} `json:"smtp"`
+		LLM *struct {
+			Endpoint          string `json:"endpoint"`
+			Model             string `json:"model"`
+			APIKey            string `json:"api_key"`
+			Enabled           bool   `json:"enabled"`
+			ExtraInstructions string `json:"extra_instructions"`
+		} `json:"llm"`
+	} `json:"defaults"`
+}
+
+// CreateWorkspace handles POST /v1/platform/workspaces.
+//
+// One transaction provisions the whole tenant: the workspaces row, its server_settings
+// row seeded from defaults, the owner user, that owner's first cno_ key, the webhook
+// subscription, and the default event type with its availability rules. Either a
+// workspace exists complete or it does not exist — a half-provisioned tenant would answer
+// requests with no owner, or hand out a booking page with no availability.
+//
+// The api_key and webhook_secret in the 201 are the only time either is legible.
+func (h *Handler) CreateWorkspace(w http.ResponseWriter, r *http.Request) {
+	if !h.platformAuthorized(w, r) {
+		return
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, 64<<10)
+	var req platformWorkspaceRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		h.writeError(w, http.StatusBadRequest, "invalid JSON")
+		return
+	}
+	if msg := validatePlatformWorkspace(&req); msg != "" {
+		h.writeError(w, http.StatusBadRequest, msg)
+		return
+	}
+
+	plainKey := "cno_" + hex.EncodeToString(mustRandom(32))
+	ownerID := uid.New()
+	etID := uid.New()
+	now := time.Now().UTC().Format(time.RFC3339Nano)
+
+	tx, err := h.db.BeginTx(r.Context(), nil)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: begin tx", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	defer tx.Rollback() //nolint:errcheck
+
+	// The workspaces row first: every other INSERT below names it as a foreign key, so
+	// this is also where a duplicate id or public_host is caught. Both uniques are real
+	// constraints rather than a pre-read, so two concurrent provisions of the same tenant
+	// cannot both win.
+	if _, err := tx.ExecContext(r.Context(), `
+		INSERT INTO workspaces (id, slug, public_host, region, status, created_at, updated_at)
+		VALUES (?, ?, ?, ?, 'active', ?, ?)`,
+		req.ID, req.Slug, req.PublicHost, req.Region, now, now); err != nil {
+		if db.IsUniqueViolation(err) {
+			h.writeError(w, http.StatusConflict, "workspace id, slug or public_host already exists")
+			return
+		}
+		h.logger.ErrorContext(r.Context(), "platform: insert workspace", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	if err := h.seedWorkspaceSettings(r.Context(), tx, &req, now); err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: seed settings", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	// The owner. iana_timezone is the REQUESTED timezone, not UTC: it is what the admin
+	// UI renders every time in and what the default event type's availability below is
+	// expressed in, so defaulting it would silently move the workspace's working hours.
+	if _, err := tx.ExecContext(r.Context(), `
+		INSERT INTO users (id, workspace_id, email, name, iana_timezone, is_admin, is_owner, email_login)
+		VALUES (?, ?, ?, ?, ?, 1, 1, 0)`,
+		ownerID, req.ID, strings.ToLower(req.OwnerEmail), req.OwnerName, req.OwnerTimezone); err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: insert owner", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	if _, err := tx.ExecContext(r.Context(), `
+		INSERT INTO api_keys (id, workspace_id, user_id, name, key_hash, created_at)
+		VALUES (?, ?, ?, 'platform-provisioned', ?, ?)`,
+		uid.New(), req.ID, ownerID, hashAPIKey(plainKey), now); err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: insert api key", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	if err := h.seedWorkspaceEventType(r.Context(), tx, &req, etID, ownerID); err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: seed event type", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	// The webhook rides the same transaction, and names workspace_id like everything
+	// else here. The secret's encoding comes from webhook.NewSecret so the convention
+	// (raw bytes encrypted, hex handed out) has exactly one implementation.
+	webhookSecret := ""
+	if url := req.Defaults.Webhook.URL; url != "" {
+		plainSecret, encSecret, err := h.webhookSvc.NewSecret(req.Defaults.Webhook.Secret)
+		if err != nil {
+			h.writeError(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		events, _ := json.Marshal([]string{
+			"booking.created", "booking.cancelled", "booking.rescheduled", "booking.reminder",
+		})
+		// A NULL fields column means "the default payload set" (migration 00027), which
+		// is not the same as an empty selection — so an empty list stays NULL rather than
+		// becoming [], and the webhook keeps the original booking-metadata shape.
+		var fieldsJSON any
+		if len(req.Defaults.Webhook.Fields) > 0 {
+			fb, _ := json.Marshal(webhook.ValidFields(req.Defaults.Webhook.Fields))
+			fieldsJSON = string(fb)
+		}
+		if _, err := tx.ExecContext(r.Context(), `
+			INSERT INTO webhooks (id, workspace_id, user_id, url, events, fields, secret_enc)
+			VALUES (?, ?, ?, ?, ?, ?, ?)`,
+			uid.New(), req.ID, ownerID, url, string(events), fieldsJSON, encSecret); err != nil {
+			h.logger.ErrorContext(r.Context(), "platform: insert webhook", "error", err)
+			h.writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		webhookSecret = plainSecret
+	}
+
+	if err := tx.Commit(); err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: commit", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	h.logger.InfoContext(r.Context(), "platform: workspace provisioned",
+		"workspace_id", req.ID, "public_host", req.PublicHost, "owner", req.OwnerEmail)
+	h.writeJSON(w, http.StatusCreated, map[string]any{
+		"api_key":        plainKey,
+		"webhook_secret": webhookSecret,
+		"note":           "save the api_key and webhook_secret — neither is shown again",
+	})
+}
+
+// seedWorkspaceSettings writes the workspace's single server_settings row. id = 1 is kept
+// per workspace (D8), so the ~40 `WHERE id = 1` reads elsewhere need no edit.
+func (h *Handler) seedWorkspaceSettings(ctx context.Context, tx *db.Tx, req *platformWorkspaceRequest, now string) error {
+	var smtpPassEnc, llmKeyEnc, livekitSecretEnc string
+	encrypt := func(plain string) (string, error) {
+		if plain == "" {
+			return "", nil
+		}
+		return secret.Encrypt(h.encKey, plain)
+	}
+	var err error
+	if req.Defaults.SMTP != nil {
+		if smtpPassEnc, err = encrypt(req.Defaults.SMTP.Pass); err != nil {
+			return fmt.Errorf("encrypt smtp password: %w", err)
+		}
+	}
+	if req.Defaults.LLM != nil {
+		if llmKeyEnc, err = encrypt(req.Defaults.LLM.APIKey); err != nil {
+			return fmt.Errorf("encrypt llm api key: %w", err)
+		}
+	}
+	if livekitSecretEnc, err = encrypt(req.Defaults.LiveKitAPISecret); err != nil {
+		return fmt.Errorf("encrypt livekit secret: %w", err)
+	}
+
+	smtpHost, smtpPort, smtpUser, emailFrom, emailFromName := "", "", "", "", ""
+	smtpTLS, smtpStartTLS := 0, 0
+	if s := req.Defaults.SMTP; s != nil {
+		smtpHost, smtpPort, smtpUser = s.Host, s.Port, s.User
+		emailFrom, emailFromName = s.From, s.FromName
+		if s.TLS {
+			smtpTLS = 1
+		}
+		if s.StartTLS {
+			smtpStartTLS = 1
+		}
+	}
+	llmEndpoint, llmModel, llmExtra := "", "", ""
+	llmEnabled := 0
+	if l := req.Defaults.LLM; l != nil {
+		llmEndpoint, llmModel, llmExtra = l.Endpoint, l.Model, l.ExtraInstructions
+		if l.Enabled {
+			llmEnabled = 1
+		}
+	}
+
+	_, err = tx.ExecContext(ctx, `
+		INSERT INTO server_settings
+		  (workspace_id, id, smtp_host, smtp_port, smtp_user, smtp_pass_enc, smtp_tls, smtp_starttls,
+		   email_from, email_from_name, updated_at,
+		   llm_endpoint, llm_model, llm_api_key_enc, llm_enabled, llm_extra_instructions,
+		   livekit_url, livekit_api_key, livekit_api_secret_enc,
+		   embed_allowed_origins, stt_base_url)
+		VALUES (?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		req.ID, smtpHost, smtpPort, smtpUser, smtpPassEnc, smtpTLS, smtpStartTLS,
+		emailFrom, emailFromName, now,
+		llmEndpoint, llmModel, llmKeyEnc, llmEnabled, llmExtra,
+		req.Defaults.LiveKitURL, req.Defaults.LiveKitAPIKey, livekitSecretEnc,
+		strings.Join(req.Defaults.EmbedAllowedOrigins, ","), req.Defaults.STTBaseURL)
+	return err
+}
+
+// seedWorkspaceEventType writes the default event type and its availability rules.
+//
+// location_type 'link' and routing_mode 'fixed' are the schema's own defaults (the CHECK
+// constraints in migration 00001 admit no 'none' or 'single'), which is what a
+// single-host event type created through the admin UI gets. The platform API does not
+// take either: a provisioning caller sets up a tenant, and how one event type meets is
+// something its owner changes in the UI afterwards.
+//
+// The rules carry no timezone of their own: availability is stored as local HH:MM and
+// interpreted in the OWNER's iana_timezone, which is why owner_timezone is required
+// rather than defaulted (a 09:00 rule means nothing until you know whose 09:00).
+func (h *Handler) seedWorkspaceEventType(ctx context.Context, tx *db.Tx, req *platformWorkspaceRequest, etID, ownerID string) error {
+	et := req.Defaults.EventType
+	if et.Slug == "" {
+		return nil
+	}
+	if _, err := tx.ExecContext(ctx, `
+		INSERT INTO event_types
+		  (id, workspace_id, user_id, slug, name, duration_minutes,
+		   min_notice_minutes, max_future_days, location_type, routing_mode)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'link', 'fixed')`,
+		etID, req.ID, ownerID, et.Slug, et.Name, et.DurationMinutes,
+		et.MinNoticeMinutes, et.MaxFutureDays); err != nil {
+		return fmt.Errorf("insert event type: %w", err)
+	}
+	for _, a := range et.Availability {
+		if _, err := tx.ExecContext(ctx, `
+			INSERT INTO availability_rules
+			  (id, workspace_id, user_id, event_type_id, day_of_week, start_time, end_time)
+			VALUES (?, ?, ?, ?, ?, ?, ?)`,
+			uid.New(), req.ID, ownerID, etID, a.DayOfWeek, a.StartTime, a.EndTime); err != nil {
+			return fmt.Errorf("insert availability rule: %w", err)
+		}
+	}
+	return nil
+}
+
+// GetWorkspace handles GET /v1/platform/workspaces/{id}.
+func (h *Handler) GetWorkspace(w http.ResponseWriter, r *http.Request) {
+	if !h.platformAuthorized(w, r) {
+		return
+	}
+	ws, err := h.readPlatformWorkspace(r.Context(), r.PathValue("id"))
+	if errors.Is(err, sql.ErrNoRows) {
+		h.writeError(w, http.StatusNotFound, "workspace not found")
+		return
+	}
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: read workspace", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	h.writeJSON(w, http.StatusOK, ws)
+}
+
+// PatchWorkspace handles PATCH /v1/platform/workspaces/{id} — public_host, status, slug.
+//
+// Nothing else is patchable: the id is referenced by every tenant row, and the region is
+// where the data physically is, so neither is a field an operator can change by writing
+// to it.
+func (h *Handler) PatchWorkspace(w http.ResponseWriter, r *http.Request) {
+	if !h.platformAuthorized(w, r) {
+		return
+	}
+	id := r.PathValue("id")
+
+	r.Body = http.MaxBytesReader(w, r.Body, 4<<10)
+	var req struct {
+		PublicHost *string `json:"public_host"`
+		Status     *string `json:"status"`
+		Slug       *string `json:"slug"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		h.writeError(w, http.StatusBadRequest, "invalid JSON")
+		return
+	}
+
+	set := []string{"updated_at = ?"}
+	args := []any{time.Now().UTC().Format(time.RFC3339Nano)}
+	if req.PublicHost != nil {
+		host := hostOnly(*req.PublicHost)
+		if host == "" {
+			h.writeError(w, http.StatusBadRequest, "public_host cannot be empty")
+			return
+		}
+		set = append(set, "public_host = ?")
+		args = append(args, host)
+	}
+	if req.Status != nil {
+		if *req.Status != "active" && *req.Status != "suspended" {
+			h.writeError(w, http.StatusBadRequest, "status must be active or suspended")
+			return
+		}
+		set = append(set, "status = ?")
+		args = append(args, *req.Status)
+	}
+	if req.Slug != nil {
+		if strings.TrimSpace(*req.Slug) == "" {
+			h.writeError(w, http.StatusBadRequest, "slug cannot be empty")
+			return
+		}
+		set = append(set, "slug = ?")
+		args = append(args, *req.Slug)
+	}
+	if len(set) == 1 {
+		h.writeError(w, http.StatusBadRequest, "nothing to update: send public_host, status or slug")
+		return
+	}
+	args = append(args, id)
+
+	res, err := h.db.ExecContext(r.Context(),
+		`UPDATE workspaces SET `+strings.Join(set, ", ")+` WHERE id = ?`, args...) // #nosec G202 -- set holds only hardcoded "col = ?" literals; every value is bound
+	if err != nil {
+		if db.IsUniqueViolation(err) {
+			h.writeError(w, http.StatusConflict, "slug or public_host already exists")
+			return
+		}
+		h.logger.ErrorContext(r.Context(), "platform: patch workspace", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		h.writeError(w, http.StatusNotFound, "workspace not found")
+		return
+	}
+
+	ws, err := h.readPlatformWorkspace(r.Context(), id)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: read back workspace", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	h.logger.InfoContext(r.Context(), "platform: workspace patched", "workspace_id", id)
+	h.writeJSON(w, http.StatusOK, ws)
+}
+
+// DeleteWorkspace handles DELETE /v1/platform/workspaces/{id}.
+//
+// The row goes and Postgres cascades every tenant table with it (migration 00060's
+// REFERENCES workspaces(id) ON DELETE CASCADE). Recordings are the exception that cannot
+// cascade: the rows go, but the objects live in S3, so their keys are returned and
+// deleting them is the caller's job. Returning them AFTER the delete would mean reading a
+// table that no longer has the rows, so they are collected first.
+func (h *Handler) DeleteWorkspace(w http.ResponseWriter, r *http.Request) {
+	if !h.platformAuthorized(w, r) {
+		return
+	}
+	id := r.PathValue("id")
+
+	keys := []string{}
+	rows, err := h.db.QueryContext(r.Context(),
+		`SELECT object_key FROM recordings WHERE workspace_id = ? AND object_key <> '' ORDER BY object_key`, id)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: list recording keys", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	for rows.Next() {
+		var key string
+		if err := rows.Scan(&key); err != nil {
+			rows.Close()
+			h.logger.ErrorContext(r.Context(), "platform: scan recording key", "error", err)
+			h.writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		keys = append(keys, key)
+	}
+	if err := rows.Err(); err != nil {
+		rows.Close()
+		h.logger.ErrorContext(r.Context(), "platform: iterate recording keys", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	rows.Close()
+
+	res, err := h.db.ExecContext(r.Context(), `DELETE FROM workspaces WHERE id = ?`, id)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: delete workspace", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		h.writeError(w, http.StatusNotFound, "workspace not found")
+		return
+	}
+
+	h.logger.InfoContext(r.Context(), "platform: workspace deleted",
+		"workspace_id", id, "recording_objects", len(keys))
+	h.writeJSON(w, http.StatusOK, map[string]any{"recording_object_keys": keys})
+}
+
+// readPlatformWorkspace reads one workspace row for the API's responses.
+func (h *Handler) readPlatformWorkspace(ctx context.Context, id string) (map[string]any, error) {
+	var wsID, slug, publicHost, region, status, createdAt, updatedAt string
+	if err := h.db.QueryRowContext(ctx, `
+		SELECT id, slug, public_host, region, status, created_at, updated_at
+		FROM workspaces WHERE id = ?`, id).
+		Scan(&wsID, &slug, &publicHost, &region, &status, &createdAt, &updatedAt); err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"id": wsID, "slug": slug, "public_host": publicHost, "region": region,
+		"status": status, "created_at": createdAt, "updated_at": updatedAt,
+	}, nil
+}
+
+// validatePlatformWorkspace returns a client-facing message for the first thing wrong
+// with a create body, or "" when it is usable.
+//
+// It is deliberately strict about the id: db.ForWorkspace validates the same shape before
+// binding, so an id this API accepted but that could not be bound would produce a
+// workspace whose every request failed with ErrInvalidWorkspace.
+func validatePlatformWorkspace(req *platformWorkspaceRequest) string {
+	if !db.ValidWorkspaceID(req.ID) {
+		return "id must match ^[a-z0-9_-]{1,64}$"
+	}
+	if req.ID == db.DefaultWorkspaceID {
+		return "id " + db.DefaultWorkspaceID + " is reserved"
+	}
+	if strings.TrimSpace(req.Slug) == "" {
+		return "slug is required"
+	}
+	req.PublicHost = hostOnly(req.PublicHost)
+	if req.PublicHost == "" {
+		return "public_host is required"
+	}
+	if strings.TrimSpace(req.OwnerEmail) == "" || !strings.Contains(req.OwnerEmail, "@") {
+		return "owner_email must be an email address"
+	}
+	if strings.TrimSpace(req.OwnerName) == "" {
+		return "owner_name is required"
+	}
+	if req.OwnerTimezone == "" {
+		return "owner_timezone is required"
+	}
+	if _, err := time.LoadLocation(req.OwnerTimezone); err != nil {
+		return "invalid owner_timezone: " + req.OwnerTimezone
+	}
+	et := req.Defaults.EventType
+	if et.Slug != "" {
+		if strings.TrimSpace(et.Name) == "" {
+			return "defaults.event_type.name is required"
+		}
+		if et.DurationMinutes <= 0 {
+			return "defaults.event_type.duration_minutes must be positive"
+		}
+		// validHHMM is override.go's, deliberately reused: availability_rules stores the
+		// same HH:MM shape for both surfaces and two validators would drift.
+		for _, a := range et.Availability {
+			if a.DayOfWeek < 0 || a.DayOfWeek > 6 {
+				return "availability day_of_week must be 0 (Sunday) through 6 (Saturday)"
+			}
+			if !validHHMM(a.StartTime) || !validHHMM(a.EndTime) {
+				return "availability start_time and end_time must be HH:MM"
+			}
+			if a.StartTime >= a.EndTime {
+				return "availability start_time must be before end_time"
+			}
+		}
+	}
+	return ""
+}
+
+// mustRandom returns n cryptographically random bytes. rand.Read from crypto/rand cannot
+// fail on any platform this runs on (it panics internally on a broken CSPRNG since Go
+// 1.24), so there is no error to thread through the caller.
+func mustRandom(n int) []byte {
+	b := make([]byte, n)
+	if _, err := rand.Read(b); err != nil {
+		panic("crypto/rand: " + err.Error())
+	}
+	return b
+}
diff --git a/internal/handler/platform_test.go b/internal/handler/platform_test.go
new file mode 100644
index 0000000..2b52a14
--- /dev/null
+++ b/internal/handler/platform_test.go
@@ -0,0 +1,468 @@
+package handler_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/handler"
+)
+
+// The platform API (D12): workspace provisioning on the identity host.
+//
+// ⛔ These need a real OpenPair, not one handle. Provisioning runs on the PLATFORM handle
+// and every INSERT names workspace_id, and the failure mode being guarded against — a row
+// that does not belong to the tenant it was created for — is invisible unless the
+// application handle is a NOBYPASSRLS role that the policies actually constrain.
+
+const platformToken = "platform-token-for-tests"
+
+// platformTestEncKey is a 32-byte AES key in hex. The platform API encrypts the SMTP
+// password, the LLM key and the LiveKit secret it is given, so a handler without a key
+// would fail provisioning for a reason unrelated to what these tests are about.
+const platformTestEncKey = "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"
+
+// newPlatformAPI returns the four routes as server.New registers them, plus the platform
+// handle the assertions read through and the application handle a tenant's own requests
+// would use.
+func newPlatformAPI(t *testing.T) (routes map[string]http.HandlerFunc, app, platform *db.DB) {
+	t.Helper()
+	app, platform = dbtest.RequireTenantPair(t)
+
+	h := handler.New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL("https://cal.example.test")
+	h.SetPlatformToken(platformToken)
+	h.SetEncKey(platformTestEncKey)
+
+	return map[string]http.HandlerFunc{
+		"create": h.Platform((*handler.Handler).CreateWorkspace),
+		"get":    h.Platform((*handler.Handler).GetWorkspace),
+		"patch":  h.Platform((*handler.Handler).PatchWorkspace),
+		"delete": h.Platform((*handler.Handler).DeleteWorkspace),
+	}, app, platform
+}
+
+// platformCreateBody is the settled contract body, with the fields the website client
+// sends. Cases mutate the one field they are about.
+func platformCreateBody(id, host string) map[string]any {
+	return map[string]any{
+		"id":             id,
+		"slug":           id,
+		"public_host":    host,
+		"region":         "us",
+		"owner_email":    "owner@" + id + ".example",
+		"owner_name":     "Owner " + id,
+		"owner_timezone": "America/Toronto",
+		"defaults": map[string]any{
+			"embed_allowed_origins": []string{"https://" + host},
+			"webhook": map[string]any{
+				"url":    "https://hooks." + host + "/calnode",
+				"fields": []string{"booking_id", "start_at"},
+			},
+			"event_type": map[string]any{
+				"slug":               "intro",
+				"name":               "Intro call",
+				"duration_minutes":   30,
+				"min_notice_minutes": 60,
+				"max_future_days":    60,
+				"availability": []map[string]any{
+					{"day_of_week": 1, "start_time": "09:00", "end_time": "17:00"},
+					{"day_of_week": 3, "start_time": "09:00", "end_time": "12:00"},
+				},
+			},
+			"livekit_url":     "wss://lk." + host,
+			"livekit_api_key": "lkkey",
+			"smtp": map[string]any{
+				"host": "smtp." + host, "port": "587",
+				"from": "bookings@" + host, "from_name": "Bookings",
+			},
+		},
+	}
+}
+
+func doPlatform(t *testing.T, route http.HandlerFunc, method, target string, body any, token string) *httptest.ResponseRecorder {
+	t.Helper()
+	var buf bytes.Buffer
+	if body != nil {
+		if err := json.NewEncoder(&buf).Encode(body); err != nil {
+			t.Fatalf("encode body: %v", err)
+		}
+	}
+	req := httptest.NewRequest(method, target, &buf)
+	// ⚠️ httptest.NewRequest does not populate mux path values — those come from the
+	// pattern the ServeMux matched, and these tests call the handler directly. Without
+	// this every {id} route reads an empty id and answers 404, which looks exactly like a
+	// missing workspace.
+	if parts := strings.Split(target, "/"); len(parts) == 5 {
+		req.SetPathValue("id", parts[4])
+	}
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	rec := httptest.NewRecorder()
+	route(rec, req)
+	return rec
+}
+
+// The whole provisioning, asserted row by row through the platform handle — because that
+// is the only handle that can see across the tenant boundary, and every row here was
+// written by a statement that had to name the tenant itself.
+func TestPlatform_createProvisionsTheWholeWorkspace(t *testing.T) {
+	routes, _, platform := newPlatformAPI(t)
+
+	rec := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces",
+		platformCreateBody("acme", "book.acme.example"), platformToken)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d; want 201 — %s", rec.Code, rec.Body.String())
+	}
+
+	var out struct {
+		APIKey        string `json:"api_key"`
+		WebhookSecret string `json:"webhook_secret"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if len(out.APIKey) < 20 || out.APIKey[:4] != "cno_" {
+		t.Errorf("api_key = %q; want a cno_ key", out.APIKey)
+	}
+	if len(out.WebhookSecret) != 64 {
+		t.Errorf("webhook_secret = %q; want 64 hex characters (32 bytes)", out.WebhookSecret)
+	}
+
+	// The workspace row.
+	var slug, host, region, status string
+	if err := platform.QueryRow(
+		`SELECT slug, public_host, region, status FROM workspaces WHERE id = 'acme'`).
+		Scan(&slug, &host, &region, &status); err != nil {
+		t.Fatalf("workspace row: %v", err)
+	}
+	if slug != "acme" || host != "book.acme.example" || region != "us" || status != "active" {
+		t.Errorf("workspace = %s/%s/%s/%s; want acme/book.acme.example/us/active", slug, host, region, status)
+	}
+
+	// Every seeded row belongs to acme. Counted with the workspace_id predicate the
+	// production statements had to carry, so a row that landed anywhere else is missing
+	// here rather than merely misfiled.
+	for _, c := range []struct {
+		what  string
+		query string
+	}{
+		{"server_settings", `SELECT COUNT(*) FROM server_settings WHERE workspace_id = 'acme' AND id = 1`},
+		{"owner user", `SELECT COUNT(*) FROM users WHERE workspace_id = 'acme' AND is_owner = 1`},
+		{"api key", `SELECT COUNT(*) FROM api_keys WHERE workspace_id = 'acme'`},
+		{"webhook", `SELECT COUNT(*) FROM webhooks WHERE workspace_id = 'acme'`},
+		{"event type", `SELECT COUNT(*) FROM event_types WHERE workspace_id = 'acme' AND slug = 'intro'`},
+	} {
+		var n int
+		if err := platform.QueryRow(c.query).Scan(&n); err != nil {
+			t.Fatalf("count %s: %v", c.what, err)
+		}
+		if n != 1 {
+			t.Errorf("%s rows in acme = %d; want 1", c.what, n)
+		}
+	}
+	var rules int
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM availability_rules WHERE workspace_id = 'acme'`).Scan(&rules); err != nil {
+		t.Fatalf("count availability rules: %v", err)
+	}
+	if rules != 2 {
+		t.Errorf("availability rules = %d; want 2", rules)
+	}
+
+	// owner_timezone, not UTC. The availability rules above are local HH:MM interpreted
+	// in this timezone, so defaulting it would silently move the workspace's hours.
+	var tz string
+	if err := platform.QueryRow(
+		`SELECT iana_timezone FROM users WHERE workspace_id = 'acme' AND is_owner = 1`).Scan(&tz); err != nil {
+		t.Fatalf("owner timezone: %v", err)
+	}
+	if tz != "America/Toronto" {
+		t.Errorf("owner iana_timezone = %q; want America/Toronto (the requested zone, not UTC)", tz)
+	}
+
+	// The settings row carries the defaults, including the two columns migration 00062
+	// added for values that had no home.
+	var origins, smtpHost, lkURL string
+	if err := platform.QueryRow(`
+		SELECT embed_allowed_origins, smtp_host, livekit_url
+		FROM server_settings WHERE workspace_id = 'acme' AND id = 1`).
+		Scan(&origins, &smtpHost, &lkURL); err != nil {
+		t.Fatalf("settings row: %v", err)
+	}
+	if origins != "https://book.acme.example" {
+		t.Errorf("embed_allowed_origins = %q; want the requested origin", origins)
+	}
+	if smtpHost != "smtp.book.acme.example" || lkURL != "wss://lk.book.acme.example" {
+		t.Errorf("settings = %q / %q; want the requested smtp host and livekit url", smtpHost, lkURL)
+	}
+}
+
+// Two workspaces provisioned through the same endpoint must not see each other. This is
+// the assertion that would fail if any INSERT above had left workspace_id to the column
+// default.
+func TestPlatform_createdWorkspacesAreIsolated(t *testing.T) {
+	routes, app, platform := newPlatformAPI(t)
+
+	for _, ws := range []struct{ id, host string }{
+		{"acme", "book.acme.example"},
+		{"globex", "book.globex.example"},
+	} {
+		rec := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces",
+			platformCreateBody(ws.id, ws.host), platformToken)
+		if rec.Code != http.StatusCreated {
+			t.Fatalf("provision %s: status = %d — %s", ws.id, rec.Code, rec.Body.String())
+		}
+	}
+
+	// Through the APPLICATION handle bound to acme, only acme's rows exist — and the
+	// count is the one a forgotten predicate would get wrong, so it is the honest probe.
+	var users, ets int
+	acme := app.ForWorkspace("acme")
+	if err := acme.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&users); err != nil {
+		t.Fatalf("count users as acme: %v", err)
+	}
+	if err := acme.QueryRow(`SELECT COUNT(*) FROM event_types`).Scan(&ets); err != nil {
+		t.Fatalf("count event types as acme: %v", err)
+	}
+	if users != 1 || ets != 1 {
+		t.Errorf("acme sees %d users and %d event types; want 1 and 1 — the other workspace's "+
+			"rows are visible", users, ets)
+	}
+
+	// And the platform handle sees both, which is what makes the 1s above meaningful
+	// rather than an empty database.
+	var allUsers int
+	if err := platform.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&allUsers); err != nil {
+		t.Fatalf("count all users: %v", err)
+	}
+	if allUsers != 2 {
+		t.Errorf("platform handle sees %d users; want 2", allUsers)
+	}
+}
+
+func TestPlatform_duplicateIDOrHostIs409(t *testing.T) {
+	routes, _, platform := newPlatformAPI(t)
+
+	first := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces",
+		platformCreateBody("acme", "book.acme.example"), platformToken)
+	if first.Code != http.StatusCreated {
+		t.Fatalf("first create: status = %d — %s", first.Code, first.Body.String())
+	}
+
+	sameID := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces",
+		platformCreateBody("acme", "other.example"), platformToken)
+	if sameID.Code != http.StatusConflict {
+		t.Errorf("duplicate id: status = %d; want 409 — %s", sameID.Code, sameID.Body.String())
+	}
+
+	body := platformCreateBody("globex", "book.acme.example") // B's id, A's host
+	sameHost := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces", body, platformToken)
+	if sameHost.Code != http.StatusConflict {
+		t.Errorf("duplicate public_host: status = %d; want 409 — %s", sameHost.Code, sameHost.Body.String())
+	}
+
+	// ⛔ And the losing create left nothing behind: the whole provisioning is one
+	// transaction, so a 409 must not leave a workspace with an owner and a live API key.
+	var globex int
+	if err := platform.QueryRow(`SELECT COUNT(*) FROM users WHERE workspace_id = 'globex'`).Scan(&globex); err != nil {
+		t.Fatalf("count globex users: %v", err)
+	}
+	if globex != 0 {
+		t.Errorf("a refused create left %d users in globex; the transaction must roll back whole", globex)
+	}
+}
+
+func TestPlatform_getPatchDelete(t *testing.T) {
+	routes, _, platform := newPlatformAPI(t)
+
+	if rec := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces",
+		platformCreateBody("acme", "book.acme.example"), platformToken); rec.Code != http.StatusCreated {
+		t.Fatalf("create: %d — %s", rec.Code, rec.Body.String())
+	}
+
+	// GET
+	rec := doPlatform(t, routes["get"], http.MethodGet, "/v1/platform/workspaces/acme", nil, platformToken)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("get: status = %d — %s", rec.Code, rec.Body.String())
+	}
+	var got map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode get: %v", err)
+	}
+	if got["id"] != "acme" || got["public_host"] != "book.acme.example" || got["status"] != "active" {
+		t.Errorf("get returned %#v; want acme / book.acme.example / active", got)
+	}
+
+	missing := doPlatform(t, routes["get"], http.MethodGet, "/v1/platform/workspaces/nope", nil, platformToken)
+	if missing.Code != http.StatusNotFound {
+		t.Errorf("get unknown: status = %d; want 404", missing.Code)
+	}
+
+	// PATCH: suspend and move the host in one call.
+	patch := doPlatform(t, routes["patch"], http.MethodPatch, "/v1/platform/workspaces/acme",
+		map[string]any{"status": "suspended", "public_host": "vanity.acme.example"}, platformToken)
+	if patch.Code != http.StatusOK {
+		t.Fatalf("patch: status = %d — %s", patch.Code, patch.Body.String())
+	}
+	var host, status string
+	if err := platform.QueryRow(
+		`SELECT public_host, status FROM workspaces WHERE id = 'acme'`).Scan(&host, &status); err != nil {
+		t.Fatalf("read back: %v", err)
+	}
+	if host != "vanity.acme.example" || status != "suspended" {
+		t.Errorf("after patch: %s / %s; want vanity.acme.example / suspended", host, status)
+	}
+
+	bad := doPlatform(t, routes["patch"], http.MethodPatch, "/v1/platform/workspaces/acme",
+		map[string]any{"status": "paused"}, platformToken)
+	if bad.Code != http.StatusBadRequest {
+		t.Errorf("patch to an invalid status: %d; want 400", bad.Code)
+	}
+	empty := doPlatform(t, routes["patch"], http.MethodPatch, "/v1/platform/workspaces/acme",
+		map[string]any{}, platformToken)
+	if empty.Code != http.StatusBadRequest {
+		t.Errorf("patch with no fields: %d; want 400", empty.Code)
+	}
+
+	// A recording with an object key, so DELETE has something to report.
+	if _, err := platform.Exec(`
+		INSERT INTO recordings (id, workspace_id, room, egress_id, status, object_key)
+		VALUES ('rec1', 'acme', 'booking-x', 'eg1', 'complete', 'recordings/acme/rec1.mp4')`); err != nil {
+		t.Fatalf("seed recording: %v", err)
+	}
+
+	del := doPlatform(t, routes["delete"], http.MethodDelete, "/v1/platform/workspaces/acme", nil, platformToken)
+	if del.Code != http.StatusOK {
+		t.Fatalf("delete: status = %d — %s", del.Code, del.Body.String())
+	}
+	var delOut struct {
+		Keys []string `json:"recording_object_keys"`
+	}
+	if err := json.Unmarshal(del.Body.Bytes(), &delOut); err != nil {
+		t.Fatalf("decode delete: %v", err)
+	}
+	if len(delOut.Keys) != 1 || delOut.Keys[0] != "recordings/acme/rec1.mp4" {
+		t.Errorf("recording_object_keys = %#v; want the one seeded key — the objects are the "+
+			"caller's to delete and nothing else reports them", delOut.Keys)
+	}
+
+	// The cascade: no tenant row survives the workspace.
+	for _, table := range []string{"users", "api_keys", "event_types", "availability_rules", "webhooks", "server_settings", "recordings"} {
+		var n int
+		if err := platform.QueryRow(
+			`SELECT COUNT(*) FROM ` + table + ` WHERE workspace_id = 'acme'`).Scan(&n); err != nil {
+			t.Fatalf("count %s after delete: %v", table, err)
+		}
+		if n != 0 {
+			t.Errorf("%s still holds %d rows for the deleted workspace; the ON DELETE CASCADE "+
+				"from migration 00060 should have taken them", table, n)
+		}
+	}
+
+	if again := doPlatform(t, routes["delete"], http.MethodDelete,
+		"/v1/platform/workspaces/acme", nil, platformToken); again.Code != http.StatusNotFound {
+		t.Errorf("second delete: status = %d; want 404", again.Code)
+	}
+}
+
+// The token, and the two shapes of "off". A wrong token is 401 so an operator can tell a
+// typo from a missing feature; an unset token is 404 so a prober cannot tell a
+// multi-tenant control plane from an instance that has none.
+func TestPlatform_tokenGate(t *testing.T) {
+	routes, _, _ := newPlatformAPI(t)
+
+	for name, token := range map[string]string{
+		"wrong token": "not-the-token",
+		"no token":    "",
+	} {
+		t.Run(name, func(t *testing.T) {
+			rec := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces",
+				platformCreateBody("acme", "book.acme.example"), token)
+			if rec.Code != http.StatusUnauthorized {
+				t.Errorf("status = %d; want 401 — %s", rec.Code, rec.Body.String())
+			}
+		})
+	}
+}
+
+func TestPlatform_404WithoutATokenConfigured(t *testing.T) {
+	database := dbtest.Open(t)
+	h := handler.New(database, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true) // multi-tenant, but no token: the API does not exist
+	route := h.Platform((*handler.Handler).CreateWorkspace)
+
+	rec := doPlatform(t, route, http.MethodPost, "/v1/platform/workspaces",
+		platformCreateBody("acme", "book.acme.example"), platformToken)
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("status = %d; want 404 with CALNODE_PLATFORM_TOKEN unset", rec.Code)
+	}
+}
+
+// A single-tenant instance has no workspaces to provision, so the API is absent there even
+// with a token configured. Same 404, same reasoning as Setup's mirror image.
+func TestPlatform_404OnASingleTenantInstance(t *testing.T) {
+	database := dbtest.Open(t)
+	h := handler.New(database, slog.New(slog.DiscardHandler))
+	h.SetPlatformToken(platformToken) // token set, but MULTI_TENANT is not
+	route := h.Platform((*handler.Handler).CreateWorkspace)
+
+	rec := doPlatform(t, route, http.MethodPost, "/v1/platform/workspaces",
+		platformCreateBody("acme", "book.acme.example"), platformToken)
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("status = %d; want 404 on a single-tenant instance", rec.Code)
+	}
+}
+
+func TestPlatform_createValidation(t *testing.T) {
+	cases := map[string]func(map[string]any){
+		"id is not a workspace id": func(b map[string]any) { b["id"] = "Not An Id" },
+		"id default is reserved":   func(b map[string]any) { b["id"] = "default" },
+		"no public_host":           func(b map[string]any) { b["public_host"] = "" },
+		"owner_email is not one":   func(b map[string]any) { b["owner_email"] = "nobody" },
+		"no owner_timezone":        func(b map[string]any) { b["owner_timezone"] = "" },
+		"bad owner_timezone":       func(b map[string]any) { b["owner_timezone"] = "Mars/Olympus" },
+		"day_of_week out of range": func(b map[string]any) {
+			d := b["defaults"].(map[string]any)
+			et := d["event_type"].(map[string]any)
+			et["availability"] = []map[string]any{{"day_of_week": 7, "start_time": "09:00", "end_time": "17:00"}}
+		},
+		"start_time is not HH:MM": func(b map[string]any) {
+			d := b["defaults"].(map[string]any)
+			et := d["event_type"].(map[string]any)
+			et["availability"] = []map[string]any{{"day_of_week": 1, "start_time": "9am", "end_time": "17:00"}}
+		},
+		"start_time after end_time": func(b map[string]any) {
+			d := b["defaults"].(map[string]any)
+			et := d["event_type"].(map[string]any)
+			et["availability"] = []map[string]any{{"day_of_week": 1, "start_time": "18:00", "end_time": "17:00"}}
+		},
+	}
+	for name, mutate := range cases {
+		t.Run(name, func(t *testing.T) {
+			routes, _, platform := newPlatformAPI(t)
+			body := platformCreateBody("acme", "book.acme.example")
+			mutate(body)
+
+			rec := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces", body, platformToken)
+			if rec.Code != http.StatusBadRequest {
+				t.Fatalf("status = %d; want 400 — %s", rec.Code, rec.Body.String())
+			}
+			var n int
+			if err := platform.QueryRow(`SELECT COUNT(*) FROM workspaces WHERE id <> 'default'`).Scan(&n); err != nil {
+				t.Fatalf("count workspaces: %v", err)
+			}
+			if n != 0 {
+				t.Errorf("a refused create left %d workspaces behind", n)
+			}
+		})
+	}
+}
diff --git a/internal/handler/shared.go b/internal/handler/shared.go
index e92813a..5a3b66b 100644
--- a/internal/handler/shared.go
+++ b/internal/handler/shared.go
@@ -66,6 +66,11 @@ type shared struct {
 	// carries a `wid` claim. The secret identifies the INSTANCE that minted the
 	// token; the workspace is inside the payload, which is what lets one identity
 	// host hand a session to any of its tenants' public hosts (D11).
+	// platformToken authorises the platform API (D12). Like the two below it is one
+	// process-wide env-var secret, and it is what makes an instance a control plane
+	// rather than just a tenant: with it unset every /v1/platform/* route 404s.
+	platformToken string
+
 	ssoSecret     string // HMAC key for the signed session hand-off; empty ⇒ /v1/auth/sso is off
 	metricsToken  string // bearer token for GET /metrics; empty ⇒ that endpoint 404s
 	sttBaseURLCfg string // STT_BASE_URL override; empty ⇒ stt.DefaultBaseURL (see sttBaseURL)
diff --git a/internal/server/routes_classified_test.go b/internal/server/routes_classified_test.go
index 24d37da..bf8720d 100644
--- a/internal/server/routes_classified_test.go
+++ b/internal/server/routes_classified_test.go
@@ -183,6 +183,13 @@ func TestPlatformRoutesAreTheIdentityHostSet(t *testing.T) {
 		// token IS the credential and the workspace is its `wid` claim, which
 		// SSOHandoff resolves itself (D11).
 		"GET /v1/auth/sso",
+		// The platform API: provisioning is an instance-level operation on the identity
+		// host, authorised by CALNODE_PLATFORM_TOKEN rather than by any tenant's
+		// credential (D12).
+		"POST /v1/platform/workspaces",
+		"GET /v1/platform/workspaces/{id}",
+		"PATCH /v1/platform/workspaces/{id}",
+		"DELETE /v1/platform/workspaces/{id}",
 		// Bootstrap: creates the first user of a single-tenant instance.
 		"POST /v1/setup",
 		// OAuth login and its callbacks live on the identity host, because that is
diff --git a/internal/server/server.go b/internal/server/server.go
index 03c62cf..69d248b 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -49,6 +49,7 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	h.SetDataDir("data")
 	h.SetEncKey(cfg.EncryptionKey)
 	h.SetSSOSecret(cfg.SSOSharedSecret)
+	h.SetPlatformToken(cfg.PlatformToken)
 	h.SetMetricsToken(cfg.MetricsToken)
 	h.SetSTTBaseURL(cfg.STTBaseURL)
 	h.SetDemoMode(cfg.DemoMode)
@@ -320,6 +321,21 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	// show you.
 	mux.HandleFunc("GET /metrics", h.Platform((*H).Metrics))
 
+	// Platform API (D12) — workspace provisioning on the identity host. Registered
+	// unconditionally and gated inside the handlers on CALNODE_PLATFORM_TOKEN *and*
+	// multi-tenant mode, both of which answer 404 when absent: a single-tenant instance
+	// has no workspaces to provision, and a prober should not be able to tell which of
+	// the two reasons applies.
+	//
+	// ⛔ Platform-wrapped, so h.db is the platform handle — which is the only handle that
+	// CAN create a tenant (the application role cannot see a workspace that does not
+	// exist yet, and RLS would refuse its first INSERT). Every INSERT in platform.go
+	// names workspace_id for that reason.
+	mux.HandleFunc("POST /v1/platform/workspaces", h.Platform((*H).CreateWorkspace))
+	mux.HandleFunc("GET /v1/platform/workspaces/{id}", h.Platform((*H).GetWorkspace))
+	mux.HandleFunc("PATCH /v1/platform/workspaces/{id}", h.Platform((*H).PatchWorkspace))
+	mux.HandleFunc("DELETE /v1/platform/workspaces/{id}", h.Platform((*H).DeleteWorkspace))
+
 	// Bootstrap — public, once-only
 	mux.HandleFunc("POST /v1/setup", h.Platform((*H).Setup))
 
diff --git a/internal/webhook/webhook.go b/internal/webhook/webhook.go
index 7a9f939..525fcd4 100644
--- a/internal/webhook/webhook.go
+++ b/internal/webhook/webhook.go
@@ -162,6 +162,44 @@ func New(db *db.DB, encKeyHex string) (*Service, error) {
 	return s, nil
 }
 
+// NewSecret prepares a webhook signing secret for a caller that must write the webhooks
+// row itself — the platform API, whose INSERT has to name workspace_id and has to ride the
+// provisioning transaction. It returns the plain hex to hand out once and the ciphertext
+// for secret_enc.
+//
+// ⛔ It exists so the encoding convention stays in ONE place. The column holds the
+// AES-GCM of the RAW secret bytes and Sign uses those bytes as the HMAC key, while the
+// string given to the subscriber is their hex encoding. A second implementation that
+// encrypted the hex string instead would store a key the subscriber cannot reproduce, and
+// every delivery would fail its signature check with nothing in the logs to point at.
+//
+// plainSecretHex may be empty, in which case a 32-byte secret is generated. A supplied
+// secret must be hex and at least 16 bytes for the same reason.
+func (s *Service) NewSecret(plainSecretHex string) (plain, encrypted string, err error) {
+	var rawSecret []byte
+	if plainSecretHex == "" {
+		rawSecret = make([]byte, 32)
+		if _, err := io.ReadFull(rand.Reader, rawSecret); err != nil {
+			return "", "", fmt.Errorf("webhook: generate secret: %w", err)
+		}
+		plainSecretHex = hex.EncodeToString(rawSecret)
+	} else {
+		decoded, err := hex.DecodeString(plainSecretHex)
+		if err != nil {
+			return "", "", fmt.Errorf("webhook: secret must be hex: %w", err)
+		}
+		if len(decoded) < 16 {
+			return "", "", fmt.Errorf("webhook: secret must be at least 16 bytes (32 hex characters)")
+		}
+		rawSecret = decoded
+	}
+	enc, err := s.encrypt(rawSecret)
+	if err != nil {
+		return "", "", fmt.Errorf("webhook: encrypt secret: %w", err)
+	}
+	return plainSecretHex, enc, nil
+}
+
 // ForDB returns a copy of s backed by handle, keeping the same signing key. It is
 // how a per-request handler gets a webhook service bound to its workspace; the
 // Service is a struct over a pool, so this pins nothing.

From 6a167ba088bc9e2cad8534a67b78772fdb5d0104 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 06:12:55 -0400
Subject: [PATCH 40/51] PROGRESS: the reminder race as an upstream-first
 candidate, and the two columns nothing reads yet

---
 PROGRESS.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/PROGRESS.md b/PROGRESS.md
index da3d4bc..abb6739 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1771,6 +1771,75 @@ of this file); the vendor webhooks resolving their workspace from the row they n
 already done (B1's `config.Validate` refuses `MULTI_TENANT` with `DEMO_MODE`) and D14
 landed with the platform-hooks merge.
 
+### ⛔ OPEN ITEM: `embed_allowed_origins` and `stt_base_url` are written and never read
+
+Migration 00062 added both columns and the platform API fills them, so a provisioned
+workspace no longer loses what the caller sent. **Nothing reads them.** The embed CORS
+check still resolves `config.EmbedAllowedOrigins` and the notetaker still resolves
+`config.STTBaseURL`, both of which are one process-wide value — so on a multi-tenant
+instance **every tenant currently shares one embed allowlist and one STT host**, whatever
+their row says. That is a silent wrong answer in the making: an operator who sets a
+per-tenant allowlist through the platform API will believe it is in force.
+
+Wiring the readers is **D7 work**, not a one-line lookup, and that is why it is not done
+here: each has to go through the per-workspace settings cache (`shared.<kind>.get(wsID)`,
+`internal/handler/tenantcache.go`) so the value is built from that workspace's
+`server_settings` row and invalidated when the workspace saves. Two specifics for whoever
+picks it up:
+
+- **`embed_allowed_origins`** is consumed by the CORS wrapper on the embed and public
+  booking routes, which runs BEFORE the handler and therefore before any per-request
+  workspace exists on the `Scoped` path. It needs the same treatment `rateLimitKey` got for
+  D14: resolve from the request Host without a database read, or move the check inside the
+  handler where the bound handle is available. The second is cleaner and is a behaviour
+  change to think about, since today a disallowed origin is refused before any handler runs.
+- **`stt_base_url`** is read by the notetaker job, which already runs bound to its
+  workspace (`workspaceForJob`, B5), so it is the easier of the two: a settings read on the
+  bound handle, with `config.STTBaseURL` as the fallback when the column is `''`.
+
+Until both are wired, a multi-tenant deployment should keep `EMBED_ALLOWED_ORIGINS` and
+`STT_BASE_URL` set to values that are correct for **every** tenant on the instance.
+
+### ⚠️ A pre-existing upstream race, fixed here (upstream-first PR candidate)
+
+Not a tenancy bug and not caused by the merge: it reproduces on a stock single-tenant
+instance, and the fix is generic. Worth carrying upstream as its own patch.
+
+**The bug.** Two detached goroutines write the same reminder row. The booking CREATE path
+enqueues reminders from one; the RESCHEDULE path replaces them from another. Both marshal
+the identical payload `{booking_id, hours_before}`, and `jobs` carries a unique on
+`(type, payload)` — so exactly one row can exist per `(booking, hours_before)`. The
+replacement deletes the booking's non-running reminder rows and re-inserts them at the new
+time, and the losing interleaving is:
+
+```
+reschedule: DELETE …            (create's row not yet committed, so invisible to it)
+create:     INSERT at the OLD time
+reschedule: INSERT at the NEW time  ->  conflict  ->  ON CONFLICT DO NOTHING  ->  dropped
+```
+
+The reschedule's own row is the one discarded, so the reminder stays pinned to the
+**original** time — permanently, with nothing logged. A booking created and rescheduled
+inside the same second is enough. The attendee is then reminded about a time the meeting no
+longer has, or not at all if the old time has already passed.
+
+**The fix.** The reschedule's INSERT upserts; the create side keeps `DO NOTHING`, because a
+create must never overwrite a reschedule and by the time the two can collide the reschedule
+is the later fact. One side upserting makes all three interleavings agree on the
+reschedule's time. `WHERE status <> 'running'` preserves the invariant the DELETE already
+encodes — a claimed job is executing, and resetting it underneath the worker would either
+double-send or be clobbered by the worker's completion write.
+
+**Measured:** 2 failures in 60 runs before, 0 in 30 after, on PostgreSQL. The test forces
+the interleaving with an uncommitted row rather than waiting for it, and fails if no backend
+ever blocks, so it cannot pass on the easy path.
+
+⚠️ **The test that found it reported it as something else**, which is why it took a bisect:
+it polled for "any `run_at` that is not the old one", kept the last value read when its
+deadline expired, and asserted on that — so a timeout surfaced as "`run_at` is three days
+wrong". A poll loop that falls through to an assertion on stale data will misattribute every
+failure it ever catches.
+
 ---
 
 ## D11, the remaining half — the plan for B6

From 2a3dfade35785c7b96b5d81019569fa2be28f799 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 06:29:45 -0400
Subject: [PATCH 41/51] handler: workspace export, import and attendee erasure
 (D12)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

internal/handler/platform_data.go. Three more Platform routes behind the same token gate:

  POST   /v1/platform/workspaces/{id}/export       one JSON document, replay-ordered
  POST   /v1/platform/workspaces/{id}/import       409 unless the workspace is empty
  DELETE /v1/platform/workspaces/{id}/attendees?email=

The replay order is data, not convention
----------------------------------------

exportTableOrder is hand-ordered parents-before-children and the document carries its tables
as an ordered ARRAY, because import replays them in the order it receives. Alphabetical -
db.TenantTables' order - would put booking_answers before bookings and event_type_hosts
before event_types, which is a foreign-key violation.

⛔ exportCoversEveryTenantTable runs at REQUEST time, not only in a test: the export fails if
any tenant table is missing from the order, or if the order names a table that is not a tenant
table. TestTenancy_tableListsCoverTheSchema already forces a new table to be classified; this
carries that guarantee into the backups, so a table added by a later migration cannot be
silently absent from every tenant's export. Being wrong here produces data that was never
backed up, which nobody notices until they need it.

Rows are read with SELECT * plus rows.Columns() rather than 32 hand-written column lists, for
the same reason: a migration that added a column would otherwise stop exporting it, and the
loss would surface only as data missing after an import. ORDER BY 1 makes two exports of one
workspace byte-comparable, which is what the round-trip test rests on.

⛔ Decision: the DEK does not travel; a fingerprint does
-------------------------------------------------------

The instruction for this group said the crypto_keystore row for the workspace travels with it
because the DEK is per tenant. There is no such row: crypto_keystore has no workspace_id at
all - it is exempt (D2) and holds one wrapped DEK per PROCESS (D3), labelled primary /
recovery. Read from the schema rather than assumed.

Manufacturing one would have been worse than useless: an export of a SINGLE tenant would then
contain the key that decrypts EVERY tenant's secrets on that instance, which is the opposite
of what the isolation is for.

So the document carries dek_fingerprint - SHA-256 over the already-encrypted wrapped_dek,
which cannot be reversed to the key. Equal fingerprints mean the two instances share a data
key and the _enc columns will decrypt there; different ones make import refuse with 409. That
refusal is the point. Without it the rows import perfectly and then every secret in them (SMTP
password, LLM key, LiveKit secret, calendar tokens) fails at first use, one integration at a
time, long after anyone is watching the response. Import is the only moment the two keys can
be compared, and the message names CALNODE_ENCRYPTION_KEY because moving it with the data is
the operator's real remedy.

A per-tenant DEK would change this, D3, and the schema. Separate packet.

Secrets and API-key hashes otherwise travel verbatim, per the contract: a tenant whose keys and
manage links stopped working on migration has not been migrated. The document is therefore as
sensitive as the database.

⛔ Import forces the target workspace
------------------------------------

Every row is inserted with workspace_id = the id in the URL; the document's own value is
discarded. The endpoint is authorised by the platform token, so trusting the document would
make an export of any workspace a way to write rows into any other.

⚠️ Ids are GLOBAL primary keys, so import is a MOVE, not a copy. Replaying a document into a
second workspace while the first still holds its rows collides on users_pkey. The supported
operation is export -> delete -> import, usually into another region's instance where those
ids do not exist; the test performs exactly that inside one database, which is the only place
the workspace_id question can be asked. Worth knowing before anyone tries to clone a tenant
for staging with it.

UseNumber on the decoder, and importValue converts a json.Number to int64 when it is one:
without it every numeric column round-trips through float64 and a large id loses its low bits
silently.

Erasure
-------

⚠️ booking_answers carries no attendee - it is keyed (booking_id, question_id) - so "their
answers" has to be derived. Answers are erased only for bookings where the erased person was
the ONLY attendee. With anyone else still on the booking the answers cannot be attributed to
them, and deleting them would erase a third party's data to satisfy someone else's request.
Both halves are tested: two attendees gives 1 attendee row and 0 answers erased; sole attendee
gives 1 and 1.

Nothing is cancelled - the host's calendar and the other attendees' records are not the erased
person's data - and the same address in another workspace is untouched, because one tenant's
erasure request is not consent to delete another's records.

Gates
-----

  gofmt -l . empty, go vet ./... clean, go build ./... clean
  go test -count=1 ./... rc=0 on SQLite (30/30)
  PostgreSQL: internal/handler rc=0 (329.5s), internal/server rc=0, internal/db rc=0

  --- PASS: TestPlatformData_exportDeleteImportRoundTrip (1.31s)
  --- PASS: TestPlatformData_importIntoAPopulatedWorkspaceIs409 (1.29s)
  --- PASS: TestPlatformData_importForcesTheTargetWorkspace (1.33s)
  --- PASS: TestPlatformData_eraseAttendee (1.31s)
  --- PASS: TestPlatformData_eraseTakesAnswersWhenNobodyElseIsOnTheBooking (1.27s)
  --- PASS: TestPlatformData_eraseRequiresAnEmail (1.22s)
  --- PASS: TestPlatformData_routesRefuseWithoutTheToken (1.27s)
  --- PASS: TestPlatformData_importRefusesAForeignDEK (1.28s)
  --- PASS: TestEveryRouteIsClassified  (179 routes: 31 host, 107 credential, 33 platform, 8 allowlisted)

Negative control, the workspace-forcing removed so the document's workspace_id is trusted:

  --- FAIL: TestPlatformData_importForcesTheTargetWorkspace
      import into acme: 400 — violates foreign key constraint
      "server_settings_workspace_id_fkey" (SQLSTATE 23503)

⚠️ Not the failure predicted, and stated as it is: it proves the forcing is load-bearing
(unfixed 400, fixed 200 with the rows in acme), but it fails at the foreign key rather than by
writing rows into the wrong tenant, because the source workspace has been deleted by then. The
leak shape is unreachable on one instance for the same reason ids are global; the guard matters
for a destination where the named workspace does exist.
---
 PROGRESS.md                               | 123 +++++
 internal/handler/platform_data.go         | 513 +++++++++++++++++++++
 internal/handler/platform_data_test.go    | 527 ++++++++++++++++++++++
 internal/server/routes_classified_test.go |   3 +
 internal/server/server.go                 |   6 +
 5 files changed, 1172 insertions(+)
 create mode 100644 internal/handler/platform_data.go
 create mode 100644 internal/handler/platform_data_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index abb6739..23a2de8 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1840,6 +1840,129 @@ deadline expired, and asserted on that — so a timeout surfaced as "`run_at` is
 wrong". A poll loop that falls through to an assertion on stale data will misattribute every
 failure it ever catches.
 
+## Boundary 6, part two — export, import and erasure (D12)
+
+`internal/handler/platform_data.go`. Three more `Platform` routes behind the same token
+gate: `POST …/export`, `POST …/import`, `DELETE …/attendees?email=`.
+
+### The replay order is data, not convention
+
+`exportTableOrder` is a hand-ordered list (parents before children) and the document carries
+its tables as an ordered ARRAY, because import replays them in the order it receives.
+Alphabetical — `db.TenantTables`' order — would put `booking_answers` before `bookings` and
+`event_type_hosts` before `event_types`, i.e. a foreign-key violation.
+
+⛔ **`exportCoversEveryTenantTable` runs at request time**, not only in a test: it fails the
+export if any `db.TenantTables` entry is missing from the order, or if the order names
+something that is not a tenant table. `TestTenancy_tableListsCoverTheSchema` already forces a
+new table to be classified; this makes the same guarantee reach the backups, so a table added
+by a later migration cannot be silently absent from every tenant's export. Being wrong here
+produces data that was never backed up, which is exactly the class of failure nobody notices
+until they need the backup.
+
+Rows are read with `SELECT *` + `rows.Columns()` rather than 32 hand-written column lists,
+for the same reason: a migration that adds a column would otherwise stop exporting it, and
+the loss would surface only as data missing after an import. `ORDER BY 1` makes two exports
+of one workspace byte-comparable, which is what the round-trip test relies on.
+
+### ⛔ Decision: the DEK does NOT travel; a fingerprint does
+
+The turn's instruction said "the `crypto_keystore` row for the workspace travels with it
+because the DEK is per tenant". **There is no such row.** `crypto_keystore` has no
+`workspace_id` at all — it is exempt (D2) and holds one wrapped DEK per PROCESS (D3),
+labelled `primary` / `recovery`. Verified in the schema rather than assumed.
+
+So carrying it was not an option, and manufacturing one would have been worse than useless:
+an export of a SINGLE tenant would then contain the key that decrypts EVERY tenant's secrets
+on that instance, which is the opposite of what the isolation exists for.
+
+What travels is `dek_fingerprint`: SHA-256 over the already-encrypted `wrapped_dek`, which
+cannot be reversed to the key. Equal fingerprints mean the two instances share a data key, so
+the document's `_enc` columns will decrypt there. **Different ones make import refuse with
+409.** That refusal is the point: without it the rows import perfectly and then every secret
+in them — SMTP password, LLM key, LiveKit secret, calendar tokens — fails at first use, one
+integration at a time, long after anyone is watching. Import is the only moment the two keys
+can be compared. The message names `CALNODE_ENCRYPTION_KEY`, because moving it with the data
+is the operator's actual remedy.
+
+⚠️ A per-tenant DEK would change all of this, plus D3 and the schema. It is a separate
+packet, and until then moving a workspace between instances means moving the encryption key
+with it.
+
+Secrets and API-key hashes otherwise travel **verbatim**, per the contract: a tenant whose
+keys and manage links stopped working on migration has not been migrated. The consequence is
+that the document is as sensitive as the database.
+
+### ⛔ Import forces the target workspace
+
+Every row is inserted with `workspace_id` = the id **in the URL**, and the document's own
+value is discarded. This endpoint is authorised by the platform token, so trusting the
+document would make an export of any workspace a way to write rows into any other.
+
+⚠️ **Ids are GLOBAL primary keys, so import is a MOVE and not a copy.** Replaying a document
+into a second workspace while the first still holds its rows collides on `users_pkey`. The
+supported operation is export → delete → import, usually into another region's instance where
+those ids do not exist; `TestPlatformData_importForcesTheTargetWorkspace` performs exactly
+that inside one database, which is the only place the workspace_id question can be asked.
+This is worth knowing before anyone tries to use import to clone a tenant for staging.
+
+`UseNumber` on the decoder, and `importValue` converts a `json.Number` to `int64` when it is
+one: without it every numeric column round-trips through `float64` and a large id loses its
+low bits silently.
+
+### Erasure: exactly one email, in exactly one workspace, cancelling nothing
+
+⚠️ **`booking_answers` carries no attendee** — it is keyed `(booking_id, question_id)` — so
+"their answers" has to be derived. They are erased only for bookings where the erased person
+was the **only** attendee. With anyone else still on the booking the answers cannot be
+attributed to them, and deleting them would erase a third party's data to satisfy someone
+else's request. Both halves are tested: two attendees ⇒ 1 attendee row and **0** answers
+erased; sole attendee ⇒ 1 and 1.
+
+Bookings are not cancelled (the host's calendar and the other attendees' records are not the
+erased person's data), and the workspace boundary holds: the same address in another
+workspace is untouched, because one tenant's erasure request is not consent to delete
+another's records.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+`go test -count=1 ./...` **rc=0 on SQLite (30/30)**.
+PostgreSQL: `internal/handler` **rc=0** (329.5s), `internal/server` **rc=0**, `internal/db`
+**rc=0**.
+
+```
+--- PASS: TestPlatformData_exportDeleteImportRoundTrip (1.31s)
+--- PASS: TestPlatformData_importIntoAPopulatedWorkspaceIs409 (1.29s)
+--- PASS: TestPlatformData_importForcesTheTargetWorkspace (1.33s)
+--- PASS: TestPlatformData_eraseAttendee (1.31s)
+--- PASS: TestPlatformData_eraseTakesAnswersWhenNobodyElseIsOnTheBooking (1.27s)
+--- PASS: TestPlatformData_eraseRequiresAnEmail (1.22s)   [missing, empty, not an email]
+--- PASS: TestPlatformData_routesRefuseWithoutTheToken (1.27s)   [export, import, erase]
+--- PASS: TestPlatformData_importRefusesAForeignDEK (1.28s)
+```
+
+Negative control, the workspace-forcing removed so the document's own `workspace_id` is
+trusted:
+
+```
+--- FAIL: TestPlatformData_importForcesTheTargetWorkspace
+    import into acme: 400 — insert or update on table "server_settings" violates foreign key
+    constraint "server_settings_workspace_id_fkey" (SQLSTATE 23503)
+```
+
+⚠️ Stated precisely, because it is not the failure I predicted: it proves the forcing is
+load-bearing (unfixed 400, fixed 200 with the rows in `acme`), but it fails at the foreign key
+rather than by writing rows into the wrong tenant — the source workspace has been deleted by
+then, so the id the document names no longer exists. The leak shape it guards against is
+unreachable on one instance for the same reason ids are global; the guard matters for a
+destination where `globex` DOES exist.
+
+### Still owed by B6
+
+The SSO + OAuth hand-off on the public host (plan at the end of this file) and the vendor
+webhooks resolving their workspace from the row they name. D13 and D14 are done.
+
 ---
 
 ## D11, the remaining half — the plan for B6
diff --git a/internal/handler/platform_data.go b/internal/handler/platform_data.go
new file mode 100644
index 0000000..04deeb5
--- /dev/null
+++ b/internal/handler/platform_data.go
@@ -0,0 +1,513 @@
+package handler
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// Export, import and attendee erasure (D12).
+//
+// Everything here is Platform-wrapped, so h.db is the platform handle: unscoped, policy
+// bypassing, and binding ''. Two rules follow, and they are the same two the rest of
+// platform.go obeys — every read carries its own workspace_id predicate, and every INSERT
+// names workspace_id. Import goes further and names the workspace from the URL rather than
+// from the document, so an import into A cannot write a row for B even if the document
+// says otherwise.
+
+// exportTableOrder is the replay order: parents before children.
+//
+// ⛔ It is a list rather than db.TenantTables' alphabetical order because
+// alphabetical is a foreign-key violation waiting to happen — booking_answers before
+// bookings, event_type_hosts before event_types. Import replays the document in the order
+// the document carries, so this order IS the contract.
+//
+// ⚠️ It is checked against db.TenantTables at export time (exportCoversEveryTenantTable),
+// so a table added by a later migration fails the export loudly instead of being quietly
+// left out of every tenant's backup. That check is the reason this list can be trusted.
+var exportTableOrder = []string{
+	// The tenant's own settings and people first: almost everything references a user.
+	"server_settings",
+	"users",
+	"teams",
+	"team_members",
+	// Event types and what hangs off them.
+	"event_types",
+	"event_type_hosts",
+	"event_type_questions",
+	"event_type_reminders",
+	"availability_rules",
+	"availability_overrides",
+	// Bookings and their children.
+	"bookings",
+	"booking_hosts",
+	"booking_attendees",
+	"booking_answers",
+	"booking_manage_tokens",
+	// Meeting artefacts.
+	"notes",
+	"transcripts",
+	"recordings",
+	"meeting_consents",
+	// Integrations.
+	"calendar_connections",
+	"connection_calendars",
+	"zoom_connections",
+	// Credentials and sessions. Included verbatim, ciphertext and hashes alike: the
+	// destination has to accept the same API keys and manage links, or a migrated tenant's
+	// integrations all break at once.
+	"api_keys",
+	"sessions",
+	"magic_link_tokens",
+	"invite_tokens",
+	"oauth_access_tokens",
+	"oauth_auth_codes",
+	// Subscriptions and their delivery history.
+	"webhooks",
+	"webhook_deliveries",
+	// Queue and replay state.
+	"jobs",
+	"idempotency_keys",
+}
+
+// workspaceExport is the document. Tables are an ordered array rather than a map because
+// the replay order is part of the data, and Go map iteration would shuffle it.
+type workspaceExport struct {
+	FormatVersion  int             `json:"format_version"`
+	ExportedAt     string          `json:"exported_at"`
+	Workspace      map[string]any  `json:"workspace"`
+	DEKFingerprint string          `json:"dek_fingerprint"`
+	Tables         []exportedTable `json:"tables"`
+	RowCounts      map[string]int  `json:"row_counts"`
+}
+
+type exportedTable struct {
+	Table string           `json:"table"`
+	Rows  []map[string]any `json:"rows"`
+}
+
+// ExportWorkspace handles POST /v1/platform/workspaces/{id}/export.
+//
+// One JSON document holding every tenant-table row for the workspace, in replay order,
+// with workspace_id on every row and secrets included verbatim.
+//
+// ⛔ Secrets in the clear-as-ciphertext: the _enc columns and the API-key hashes travel as
+// they are stored, because the destination must accept the same credentials — a tenant
+// whose keys and manage links stopped working on migration has not been migrated. The
+// consequence is that this document is as sensitive as the database, and the reason
+// dek_fingerprint exists (see below).
+func (h *Handler) ExportWorkspace(w http.ResponseWriter, r *http.Request) {
+	if !h.platformAuthorized(w, r) {
+		return
+	}
+	id := r.PathValue("id")
+
+	ws, err := h.readPlatformWorkspace(r.Context(), id)
+	if err != nil {
+		h.writeError(w, http.StatusNotFound, "workspace not found")
+		return
+	}
+	if err := exportCoversEveryTenantTable(); err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: export table list is stale", "error", err)
+		h.writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	fingerprint, err := h.dekFingerprint(r.Context())
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: dek fingerprint", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	out := workspaceExport{
+		FormatVersion:  1,
+		ExportedAt:     time.Now().UTC().Format(time.RFC3339Nano),
+		Workspace:      ws,
+		DEKFingerprint: fingerprint,
+		RowCounts:      map[string]int{},
+	}
+	for _, table := range exportTableOrder {
+		rows, err := h.exportTable(r.Context(), table, id)
+		if err != nil {
+			h.logger.ErrorContext(r.Context(), "platform: export table", "table", table, "error", err)
+			h.writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		out.Tables = append(out.Tables, exportedTable{Table: table, Rows: rows})
+		out.RowCounts[table] = len(rows)
+	}
+
+	h.logger.InfoContext(r.Context(), "platform: workspace exported", "workspace_id", id)
+	h.writeJSON(w, http.StatusOK, out)
+}
+
+// exportTable reads one table's rows for a workspace, generically.
+//
+// SELECT * and rows.Columns() rather than 32 hand-written column lists: a migration that
+// adds a column would silently stop exporting it otherwise, and the failure would only
+// show up as data missing after an import. ORDER BY 1 makes two exports of the same
+// workspace byte-identical, which is what the round-trip test compares.
+func (h *Handler) exportTable(ctx context.Context, table, workspaceID string) ([]map[string]any, error) {
+	// table comes from exportTableOrder, a package-level literal checked against
+	// db.TenantTables — never from the request.
+	rows, err := h.db.QueryContext(ctx,
+		`SELECT * FROM `+table+` WHERE workspace_id = ? ORDER BY 1`, workspaceID) // #nosec G202
+	if err != nil {
+		return nil, fmt.Errorf("select %s: %w", table, err)
+	}
+	defer rows.Close()
+
+	cols, err := rows.Columns()
+	if err != nil {
+		return nil, fmt.Errorf("columns of %s: %w", table, err)
+	}
+
+	out := []map[string]any{}
+	for rows.Next() {
+		cells := make([]any, len(cols))
+		for i := range cells {
+			cells[i] = new(any)
+		}
+		if err := rows.Scan(cells...); err != nil {
+			return nil, fmt.Errorf("scan %s: %w", table, err)
+		}
+		row := make(map[string]any, len(cols))
+		for i, col := range cols {
+			v := *(cells[i].(*any))
+			// TEXT arrives as []byte from one driver and string from the other; both are
+			// text as far as this schema is concerned, and normalising here is what makes
+			// an export from PostgreSQL replayable and comparable.
+			if b, ok := v.([]byte); ok {
+				v = string(b)
+			}
+			row[col] = v
+		}
+		out = append(out, row)
+	}
+	return out, rows.Err()
+}
+
+// ImportWorkspace handles POST /v1/platform/workspaces/{id}/import.
+//
+// The inverse of export, in one transaction, refusing a workspace that already holds rows.
+func (h *Handler) ImportWorkspace(w http.ResponseWriter, r *http.Request) {
+	if !h.platformAuthorized(w, r) {
+		return
+	}
+	id := r.PathValue("id")
+
+	if _, err := h.readPlatformWorkspace(r.Context(), id); err != nil {
+		h.writeError(w, http.StatusNotFound, "workspace not found")
+		return
+	}
+
+	// 64 MB: an export of a busy workspace carries its whole delivery history.
+	r.Body = http.MaxBytesReader(w, r.Body, 64<<20)
+	dec := json.NewDecoder(r.Body)
+	// ⛔ UseNumber, so 9007199254740993 survives. Without it every numeric column round
+	// trips through float64 and large ids lose their low bits silently.
+	dec.UseNumber()
+	var doc workspaceExport
+	if err := dec.Decode(&doc); err != nil {
+		h.writeError(w, http.StatusBadRequest, "invalid JSON: "+err.Error())
+		return
+	}
+	if doc.FormatVersion != 1 {
+		h.writeError(w, http.StatusBadRequest, fmt.Sprintf("unsupported format_version %d", doc.FormatVersion))
+		return
+	}
+
+	// ⛔ The DEK check, and it is a refusal rather than a warning. Every _enc column in the
+	// document is ciphertext under the SOURCE instance's data key. If the destination's key
+	// differs, the rows import perfectly and then every secret in them — SMTP password,
+	// LLM key, LiveKit secret, calendar tokens — fails to decrypt at first use, one
+	// integration at a time, long after anyone is watching this response. A mismatch here
+	// is the only moment the two keys can be compared.
+	fingerprint, err := h.dekFingerprint(r.Context())
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: dek fingerprint", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	if doc.DEKFingerprint != "" && doc.DEKFingerprint != fingerprint {
+		h.writeError(w, http.StatusConflict,
+			"dek_fingerprint does not match this instance: every encrypted column in the "+
+				"document would be undecryptable here. Move CALNODE_ENCRYPTION_KEY with the data, "+
+				"or re-key the source before exporting")
+		return
+	}
+
+	tx, err := h.db.BeginTx(r.Context(), nil)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: import begin tx", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	defer tx.Rollback() //nolint:errcheck
+
+	// Refuse a workspace that holds anything. Checked INSIDE the transaction so the check
+	// and the inserts cannot be interleaved by a second import.
+	for _, table := range exportTableOrder {
+		var n int
+		if err := tx.QueryRowContext(r.Context(),
+			`SELECT COUNT(*) FROM `+table+` WHERE workspace_id = ?`, id).Scan(&n); err != nil { // #nosec G202
+			h.logger.ErrorContext(r.Context(), "platform: import precheck", "table", table, "error", err)
+			h.writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		if n > 0 {
+			h.writeError(w, http.StatusConflict,
+				fmt.Sprintf("workspace %s already has %d rows in %s: import only into an empty workspace", id, n, table))
+			return
+		}
+	}
+
+	imported := map[string]int{}
+	for _, t := range doc.Tables {
+		if !isExportableTable(t.Table) {
+			h.writeError(w, http.StatusBadRequest, "unknown table in document: "+t.Table)
+			return
+		}
+		for _, row := range t.Rows {
+			if err := importRow(r.Context(), tx, t.Table, id, row); err != nil {
+				h.logger.ErrorContext(r.Context(), "platform: import row",
+					"table", t.Table, "error", err)
+				h.writeError(w, http.StatusBadRequest,
+					fmt.Sprintf("import %s: %v", t.Table, err))
+				return
+			}
+		}
+		imported[t.Table] = len(t.Rows)
+	}
+
+	if err := tx.Commit(); err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: import commit", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	h.logger.InfoContext(r.Context(), "platform: workspace imported", "workspace_id", id)
+	h.writeJSON(w, http.StatusOK, map[string]any{"imported": imported})
+}
+
+// importRow inserts one exported row, forcing workspace_id to the target workspace.
+//
+// ⛔ Forcing it is the safety property, not a convenience: a document exported from
+// workspace B carries workspace_id = "b" on every row, and replaying it into A must produce
+// A's rows or fail. Trusting the document would make this endpoint a way to write into any
+// tenant, authorised only by holding an export of another one.
+func importRow(ctx context.Context, tx *db.Tx, table, workspaceID string, row map[string]any) error {
+	cols := make([]string, 0, len(row)+1)
+	args := make([]any, 0, len(row)+1)
+	for col, v := range row {
+		if col == "workspace_id" {
+			continue
+		}
+		if !validColumnName(col) {
+			return fmt.Errorf("invalid column name %q", col)
+		}
+		cols = append(cols, col)
+		args = append(args, importValue(v))
+	}
+	cols = append(cols, "workspace_id")
+	args = append(args, workspaceID)
+
+	placeholders := strings.TrimSuffix(strings.Repeat("?, ", len(cols)), ", ")
+	_, err := tx.ExecContext(ctx,
+		`INSERT INTO `+table+` (`+strings.Join(cols, ", ")+`) VALUES (`+placeholders+`)`, args...) // #nosec G202 -- table is allowlisted against db.TenantTables and every column name is validated; all values are bound
+	return err
+}
+
+// importValue converts a decoded JSON value into something both drivers accept.
+//
+// json.Number is carried as an int64 when it is one, so an INTEGER column receives an
+// integer rather than a float or a string — the two engines disagree about what they do
+// with the other two, and neither disagreement is visible until a later read.
+func importValue(v any) any {
+	n, ok := v.(json.Number)
+	if !ok {
+		return v
+	}
+	if i, err := n.Int64(); err == nil {
+		return i
+	}
+	if f, err := n.Float64(); err == nil {
+		return f
+	}
+	return n.String()
+}
+
+// validColumnName guards the one part of an import statement that is not a bind parameter.
+// Column names come from a document a platform operator supplied, so they are checked
+// rather than trusted; a name that is not [a-z0-9_] cannot be a column in this schema.
+func validColumnName(col string) bool {
+	if col == "" || len(col) > 64 {
+		return false
+	}
+	for i := 0; i < len(col); i++ {
+		c := col[i]
+		if (c < 'a' || c > 'z') && (c < '0' || c > '9') && c != '_' {
+			return false
+		}
+	}
+	return true
+}
+
+func isExportableTable(table string) bool {
+	for _, t := range exportTableOrder {
+		if t == table {
+			return true
+		}
+	}
+	return false
+}
+
+// exportCoversEveryTenantTable reports a tenant table that export would leave out, or an
+// entry in the order that is not a tenant table at all.
+//
+// ⛔ This is what makes a backup trustworthy. Migration 00060's list of tenant tables is
+// already guarded (TestTenancy_tableListsCoverTheSchema fails when a new table is in
+// neither the tenant nor the exempt list), so checking THIS list against THAT one means a
+// table added by a later migration cannot be silently absent from every export. It is
+// checked at request time, not just in a test, because the consequence of being wrong is
+// data that was never backed up.
+func exportCoversEveryTenantTable() error {
+	inOrder := map[string]bool{}
+	for _, t := range exportTableOrder {
+		inOrder[t] = true
+	}
+	var missing []string
+	for _, t := range db.TenantTables {
+		if !inOrder[t] {
+			missing = append(missing, t)
+		}
+	}
+	tenant := map[string]bool{}
+	for _, t := range db.TenantTables {
+		tenant[t] = true
+	}
+	var unknown []string
+	for _, t := range exportTableOrder {
+		if !tenant[t] {
+			unknown = append(unknown, t)
+		}
+	}
+	if len(missing) > 0 || len(unknown) > 0 {
+		return fmt.Errorf("export table order is stale: missing %v, not tenant tables %v", missing, unknown)
+	}
+	return nil
+}
+
+// dekFingerprint identifies the data key this instance is using, without revealing it.
+//
+// ⛔ The DEK ITSELF DOES NOT TRAVEL, and that is a decision worth stating. crypto_keystore
+// is exempt from tenancy (D2) and holds one wrapped DEK per PROCESS (D3) — there is no
+// per-workspace row to carry, and manufacturing one would be worse than useless: an export
+// of a single tenant would then contain the key that decrypts EVERY tenant's secrets on
+// that instance, which is the opposite of what the isolation is for.
+//
+// What travels instead is a fingerprint: SHA-256 over the wrapped DEK, which is already a
+// ciphertext and cannot be reversed to the key. Equal fingerprints mean the two instances
+// share a data key, so the document's _enc columns will decrypt. Different ones mean they
+// will not, and import refuses.
+//
+// A per-tenant DEK would change this (and D3, and the schema). Until then, moving a
+// workspace between instances means moving CALNODE_ENCRYPTION_KEY with it.
+func (h *Handler) dekFingerprint(ctx context.Context) (string, error) {
+	var wrapped []byte
+	err := h.db.QueryRowContext(ctx,
+		`SELECT wrapped_dek FROM crypto_keystore WHERE label = 'primary'`).Scan(&wrapped)
+	if err != nil {
+		// No keystore row at all is a legitimate state (an instance that has never
+		// encrypted anything), and it fingerprints as empty so an export from one such
+		// instance imports into another without a spurious conflict.
+		if strings.Contains(err.Error(), "no rows") {
+			return "", nil
+		}
+		return "", fmt.Errorf("read keystore: %w", err)
+	}
+	sum := sha256.Sum256(wrapped)
+	return "sha256:" + hex.EncodeToString(sum[:]), nil
+}
+
+// EraseAttendee handles DELETE /v1/platform/workspaces/{id}/attendees?email=
+//
+// An erasure request for one person in one workspace. It cancels nothing: the bookings
+// stay, because the host's calendar and the other attendees' records are not the erased
+// person's data to remove, and a cancellation would notify people about someone else's
+// deletion request.
+func (h *Handler) EraseAttendee(w http.ResponseWriter, r *http.Request) {
+	if !h.platformAuthorized(w, r) {
+		return
+	}
+	id := r.PathValue("id")
+	email := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("email")))
+	if email == "" || !strings.Contains(email, "@") {
+		h.writeError(w, http.StatusBadRequest, "email is required")
+		return
+	}
+	if _, err := h.readPlatformWorkspace(r.Context(), id); err != nil {
+		h.writeError(w, http.StatusNotFound, "workspace not found")
+		return
+	}
+
+	tx, err := h.db.BeginTx(r.Context(), nil)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: erase begin tx", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+	defer tx.Rollback() //nolint:errcheck
+
+	// ⚠️ Answers are keyed on (booking_id, question_id) and carry no attendee, so "their
+	// answers" has to be derived. They are erased only for bookings where this person was
+	// the ONLY attendee — with anyone else still on the booking, the answers cannot be
+	// attributed to the erased person, and deleting them would erase a third party's data
+	// to satisfy someone else's request.
+	answers, err := tx.ExecContext(r.Context(), `
+		DELETE FROM booking_answers
+		 WHERE workspace_id = ?
+		   AND booking_id IN (
+		       SELECT booking_id FROM booking_attendees
+		        WHERE workspace_id = ? AND LOWER(email) = ?)
+		   AND booking_id NOT IN (
+		       SELECT booking_id FROM booking_attendees
+		        WHERE workspace_id = ? AND LOWER(email) <> ?)`,
+		id, id, email, id, email)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: erase answers", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	attendees, err := tx.ExecContext(r.Context(),
+		`DELETE FROM booking_attendees WHERE workspace_id = ? AND LOWER(email) = ?`, id, email)
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: erase attendees", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	if err := tx.Commit(); err != nil {
+		h.logger.ErrorContext(r.Context(), "platform: erase commit", "error", err)
+		h.writeError(w, http.StatusInternalServerError, "internal error")
+		return
+	}
+
+	answerCount, _ := answers.RowsAffected()
+	attendeeCount, _ := attendees.RowsAffected()
+	h.logger.InfoContext(r.Context(), "platform: attendee erased",
+		"workspace_id", id, "attendees", attendeeCount, "answers", answerCount)
+	h.writeJSON(w, http.StatusOK, map[string]any{
+		"booking_attendees": attendeeCount,
+		"booking_answers":   answerCount,
+	})
+}
diff --git a/internal/handler/platform_data_test.go b/internal/handler/platform_data_test.go
new file mode 100644
index 0000000..6b44a93
--- /dev/null
+++ b/internal/handler/platform_data_test.go
@@ -0,0 +1,527 @@
+package handler_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/handler"
+)
+
+// Export, import and attendee erasure (D12). Real pair throughout: the round trip is only
+// meaningful if the rows it moves are ones the policies would otherwise hide.
+
+// newPlatformDataAPI returns the seven platform routes plus both handles.
+func newPlatformDataAPI(t *testing.T) (map[string]http.HandlerFunc, *db.DB, *db.DB) {
+	t.Helper()
+	app, platform := dbtest.RequireTenantPair(t)
+
+	h := handler.New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL("https://cal.example.test")
+	h.SetPlatformToken(platformToken)
+	h.SetEncKey(platformTestEncKey)
+
+	return map[string]http.HandlerFunc{
+		"create":       h.Platform((*handler.Handler).CreateWorkspace),
+		"export":       h.Platform((*handler.Handler).ExportWorkspace),
+		"import":       h.Platform((*handler.Handler).ImportWorkspace),
+		"erase":        h.Platform((*handler.Handler).EraseAttendee),
+		"delete":       h.Platform((*handler.Handler).DeleteWorkspace),
+		"getWorkspace": h.Platform((*handler.Handler).GetWorkspace),
+	}, app, platform
+}
+
+// seedTenantData gives a workspace one booking with two attendees and an answer, a note,
+// and (from provisioning) a webhook, an API key, an owner and an event type — so the round
+// trip has a parent-child chain, a credential, a secret and a free-text row to compare.
+func seedTenantData(t *testing.T, platform *db.DB, wsID string) {
+	t.Helper()
+	var ownerID, etID string
+	if err := platform.QueryRow(
+		`SELECT id FROM users WHERE workspace_id = ? AND is_owner = 1`, wsID).Scan(&ownerID); err != nil {
+		t.Fatalf("read owner of %s: %v", wsID, err)
+	}
+	if err := platform.QueryRow(
+		`SELECT id FROM event_types WHERE workspace_id = ?`, wsID).Scan(&etID); err != nil {
+		t.Fatalf("read event type of %s: %v", wsID, err)
+	}
+
+	stmts := []struct {
+		query string
+		args  []any
+	}{
+		{`INSERT INTO bookings (id, workspace_id, event_type_id, host_id, start_at, end_at, status, created_at)
+		  VALUES (?, ?, ?, ?, '2026-10-01T10:00:00Z', '2026-10-01T10:30:00Z', 'confirmed', '2026-09-01T09:00:00Z')`,
+			[]any{wsID + "-booking", wsID, etID, ownerID}},
+		{`INSERT INTO booking_attendees (id, workspace_id, booking_id, name, email, iana_timezone, is_organizer)
+		  VALUES (?, ?, ?, 'Ada', 'ada@example.test', 'UTC', 0)`,
+			[]any{wsID + "-att-ada", wsID, wsID + "-booking"}},
+		{`INSERT INTO event_type_questions (id, workspace_id, event_type_id, label, type, position)
+		  VALUES (?, ?, ?, 'Why?', 'text', 0)`,
+			[]any{wsID + "-q", wsID, etID}},
+		{`INSERT INTO booking_answers (id, workspace_id, booking_id, question_id, value)
+		  VALUES (?, ?, ?, ?, 'because')`,
+			[]any{wsID + "-ans", wsID, wsID + "-booking", wsID + "-q"}},
+		{`INSERT INTO notes (id, workspace_id, booking_id, content, status, created_at, updated_at)
+		  VALUES (?, ?, ?, 'a private note', 'ready', '2026-09-01T09:05:00Z', '2026-09-01T09:05:00Z')`,
+			[]any{wsID + "-note", wsID, wsID + "-booking"}},
+	}
+	for _, s := range stmts {
+		if _, err := platform.Exec(s.query, s.args...); err != nil {
+			t.Fatalf("seed %s: %v", wsID, err)
+		}
+	}
+}
+
+func provisionForData(t *testing.T, routes map[string]http.HandlerFunc, id, host string) {
+	t.Helper()
+	rec := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces",
+		platformCreateBody(id, host), platformToken)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("provision %s: %d — %s", id, rec.Code, rec.Body.String())
+	}
+}
+
+// doPlatformSub drives a /{id}/<sub> route, which doPlatform's 5-segment path-value rule
+// does not cover.
+func doPlatformSub(t *testing.T, route http.HandlerFunc, method, target, id string, body []byte, token string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(method, target, bytes.NewReader(body))
+	req.SetPathValue("id", id)
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	rec := httptest.NewRecorder()
+	route(rec, req)
+	return rec
+}
+
+// The round trip: export, delete the workspace, re-create it empty, import, export again,
+// and compare the two documents.
+//
+// ⛔ The second export is what makes this a real assertion. Comparing row counts would pass
+// with every value mangled; comparing the documents byte for byte (minus the two fields
+// that are timestamps of the export itself) says the data that came back is the data that
+// left, including the API-key hash and the encrypted webhook secret.
+func TestPlatformData_exportDeleteImportRoundTrip(t *testing.T) {
+	routes, _, platform := newPlatformDataAPI(t)
+	provisionForData(t, routes, "acme", "book.acme.example")
+	seedTenantData(t, platform, "acme")
+
+	first := doPlatformSub(t, routes["export"], http.MethodPost,
+		"/v1/platform/workspaces/acme/export", "acme", nil, platformToken)
+	if first.Code != http.StatusOK {
+		t.Fatalf("export: %d — %s", first.Code, first.Body.String())
+	}
+	document := first.Body.Bytes()
+
+	// Every table the schema says is a tenant table is present in the document.
+	var doc struct {
+		Tables []struct {
+			Table string           `json:"table"`
+			Rows  []map[string]any `json:"rows"`
+		} `json:"tables"`
+		RowCounts      map[string]int `json:"row_counts"`
+		DEKFingerprint string         `json:"dek_fingerprint"`
+	}
+	if err := json.Unmarshal(document, &doc); err != nil {
+		t.Fatalf("decode export: %v", err)
+	}
+	present := map[string]bool{}
+	for _, tbl := range doc.Tables {
+		present[tbl.Table] = true
+	}
+	for _, want := range db.TenantTables {
+		if !present[want] {
+			t.Errorf("export omits the tenant table %q — a workspace's backup would be incomplete", want)
+		}
+	}
+	for table, min := range map[string]int{
+		"users": 1, "event_types": 1, "availability_rules": 2, "api_keys": 1,
+		"webhooks": 1, "bookings": 1, "booking_attendees": 1, "booking_answers": 1,
+		"notes": 1, "server_settings": 1,
+	} {
+		if doc.RowCounts[table] < min {
+			t.Errorf("export has %d rows in %s; want at least %d", doc.RowCounts[table], table, min)
+		}
+	}
+
+	// Delete, then re-create the same workspace empty.
+	if rec := doPlatform(t, routes["delete"], http.MethodDelete,
+		"/v1/platform/workspaces/acme", nil, platformToken); rec.Code != http.StatusOK {
+		t.Fatalf("delete: %d — %s", rec.Code, rec.Body.String())
+	}
+	var left int
+	if err := platform.QueryRow(`SELECT COUNT(*) FROM users WHERE workspace_id = 'acme'`).Scan(&left); err != nil {
+		t.Fatalf("count after delete: %v", err)
+	}
+	if left != 0 {
+		t.Fatalf("delete left %d users behind", left)
+	}
+	if _, err := platform.Exec(`
+		INSERT INTO workspaces (id, slug, public_host, region, status, created_at, updated_at)
+		VALUES ('acme', 'acme', 'book.acme.example', 'us', 'active', '2026-09-01T00:00:00Z', '2026-09-01T00:00:00Z')`); err != nil {
+		t.Fatalf("re-create workspace: %v", err)
+	}
+
+	imp := doPlatformSub(t, routes["import"], http.MethodPost,
+		"/v1/platform/workspaces/acme/import", "acme", document, platformToken)
+	if imp.Code != http.StatusOK {
+		t.Fatalf("import: %d — %s", imp.Code, imp.Body.String())
+	}
+
+	second := doPlatformSub(t, routes["export"], http.MethodPost,
+		"/v1/platform/workspaces/acme/export", "acme", nil, platformToken)
+	if second.Code != http.StatusOK {
+		t.Fatalf("second export: %d — %s", second.Code, second.Body.String())
+	}
+
+	if a, b := normaliseExport(t, document), normaliseExport(t, second.Body.Bytes()); a != b {
+		t.Errorf("the round trip is not byte-identical: %s", firstDifference(a, b))
+	}
+}
+
+// normaliseExport drops the fields that describe the export rather than the workspace: the
+// timestamp of the export itself, and the workspace row's own updated_at, which the
+// re-creation above legitimately rewrites.
+func normaliseExport(t *testing.T, raw []byte) string {
+	t.Helper()
+	var doc map[string]any
+	if err := json.Unmarshal(raw, &doc); err != nil {
+		t.Fatalf("decode for comparison: %v", err)
+	}
+	delete(doc, "exported_at")
+	delete(doc, "workspace")
+	out, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatalf("re-encode for comparison: %v", err)
+	}
+	return string(out)
+}
+
+// firstDifference reports where two documents diverge, because a diff of two 50 KB JSON
+// strings is unreadable in a test log.
+func firstDifference(a, b string) string {
+	for i := 0; i < len(a) && i < len(b); i++ {
+		if a[i] != b[i] {
+			lo := i - 80
+			if lo < 0 {
+				lo = 0
+			}
+			hiA, hiB := i+80, i+80
+			if hiA > len(a) {
+				hiA = len(a)
+			}
+			if hiB > len(b) {
+				hiB = len(b)
+			}
+			return "at byte " + strconv.Itoa(i) + "\n…" + a[lo:hiA] + "\n…" + b[lo:hiB]
+		}
+	}
+	if len(a) != len(b) {
+		return "lengths differ: " + strconv.Itoa(len(a)) + " vs " + strconv.Itoa(len(b))
+	}
+	return "identical"
+}
+
+// Import refuses a workspace that already holds rows, and leaves it exactly as it was.
+func TestPlatformData_importIntoAPopulatedWorkspaceIs409(t *testing.T) {
+	routes, _, platform := newPlatformDataAPI(t)
+	provisionForData(t, routes, "acme", "book.acme.example")
+	seedTenantData(t, platform, "acme")
+
+	export := doPlatformSub(t, routes["export"], http.MethodPost,
+		"/v1/platform/workspaces/acme/export", "acme", nil, platformToken)
+	if export.Code != http.StatusOK {
+		t.Fatalf("export: %d — %s", export.Code, export.Body.String())
+	}
+
+	before := tenantRowCounts(t, platform, "acme")
+
+	rec := doPlatformSub(t, routes["import"], http.MethodPost,
+		"/v1/platform/workspaces/acme/import", "acme", export.Body.Bytes(), platformToken)
+	if rec.Code != http.StatusConflict {
+		t.Fatalf("import into a populated workspace: %d; want 409 — %s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "already has") {
+		t.Errorf("409 body = %s; want it to name the table that is not empty", rec.Body.String())
+	}
+
+	after := tenantRowCounts(t, platform, "acme")
+	for table, n := range before {
+		if after[table] != n {
+			t.Errorf("%s went from %d to %d rows; a refused import must change nothing",
+				table, n, after[table])
+		}
+	}
+}
+
+// ⛔ A document exported from B, imported into A, must produce A's rows — not B's. The
+// endpoint is authorised by the platform token, so trusting the document's own workspace_id
+// would make an export of any workspace a way to write into any other.
+func TestPlatformData_importForcesTheTargetWorkspace(t *testing.T) {
+	routes, app, platform := newPlatformDataAPI(t)
+	provisionForData(t, routes, "globex", "book.globex.example")
+	seedTenantData(t, platform, "globex")
+
+	export := doPlatformSub(t, routes["export"], http.MethodPost,
+		"/v1/platform/workspaces/globex/export", "globex", nil, platformToken)
+	if export.Code != http.StatusOK {
+		t.Fatalf("export globex: %d — %s", export.Code, export.Body.String())
+	}
+	document := export.Body.Bytes()
+	if !bytes.Contains(document, []byte(`"globex"`)) {
+		t.Fatal("the document does not mention globex, so this test would prove nothing")
+	}
+
+	// ⚠️ The source workspace is deleted first, and that is not tidying: ids are GLOBAL
+	// primary keys, so importing a document into a second workspace while the first still
+	// holds its rows collides on users_pkey. The supported operation is a MOVE — export,
+	// delete, import, usually into another region's instance where the rows do not exist —
+	// and this test performs it inside one database because that is where the workspace_id
+	// question can be asked.
+	if rec := doPlatform(t, routes["delete"], http.MethodDelete,
+		"/v1/platform/workspaces/globex", nil, platformToken); rec.Code != http.StatusOK {
+		t.Fatalf("delete globex: %d — %s", rec.Code, rec.Body.String())
+	}
+
+	// An empty target workspace, with a different id from the one the document names.
+	if _, err := platform.Exec(`
+		INSERT INTO workspaces (id, slug, public_host, region, status, created_at, updated_at)
+		VALUES ('acme', 'acme', 'book.acme.example', 'us', 'active', '2026-09-01T00:00:00Z', '2026-09-01T00:00:00Z')`); err != nil {
+		t.Fatalf("seed acme: %v", err)
+	}
+
+	if rec := doPlatformSub(t, routes["import"], http.MethodPost,
+		"/v1/platform/workspaces/acme/import", "acme", document, platformToken); rec.Code != http.StatusOK {
+		t.Fatalf("import into acme: %d — %s", rec.Code, rec.Body.String())
+	}
+
+	// Every imported row belongs to acme, and globex still has exactly its own.
+	var acmeBookings, globexBookings int
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM bookings WHERE workspace_id = 'acme'`).Scan(&acmeBookings); err != nil {
+		t.Fatalf("count acme bookings: %v", err)
+	}
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM bookings WHERE workspace_id = 'globex'`).Scan(&globexBookings); err != nil {
+		t.Fatalf("count globex bookings: %v", err)
+	}
+	if acmeBookings != 1 || globexBookings != 0 {
+		t.Errorf("bookings: acme %d, globex %d; want 1 and 0 — every row in a document that "+
+			"says \"globex\" must land in the workspace named by the URL", acmeBookings, globexBookings)
+	}
+
+	// And acme's own bound handle can see them, which is the whole point of forcing the id:
+	// a row carrying globex's workspace_id would be invisible to acme under the policies.
+	var visible int
+	if err := app.ForWorkspace("acme").QueryRow(`SELECT COUNT(*) FROM bookings`).Scan(&visible); err != nil {
+		t.Fatalf("count as acme: %v", err)
+	}
+	if visible != 1 {
+		t.Errorf("acme's own handle sees %d bookings; want 1", visible)
+	}
+}
+
+// Erasure: exactly that email, in exactly that workspace, cancelling nothing.
+func TestPlatformData_eraseAttendee(t *testing.T) {
+	routes, _, platform := newPlatformDataAPI(t)
+	provisionForData(t, routes, "acme", "book.acme.example")
+	provisionForData(t, routes, "globex", "book.globex.example")
+	seedTenantData(t, platform, "acme")
+	seedTenantData(t, platform, "globex") // the same address, in another workspace
+
+	// A second attendee on acme's booking, so the answer must SURVIVE: with someone else
+	// still on the booking, the answers cannot be attributed to the erased person.
+	if _, err := platform.Exec(`
+		INSERT INTO booking_attendees (id, workspace_id, booking_id, name, email, iana_timezone, is_organizer)
+		VALUES ('acme-att-bob', 'acme', 'acme-booking', 'Bob', 'bob@example.test', 'UTC', 0)`); err != nil {
+		t.Fatalf("seed second attendee: %v", err)
+	}
+
+	rec := doPlatformSub(t, routes["erase"], http.MethodDelete,
+		"/v1/platform/workspaces/acme/attendees?email=ada@example.test", "acme", nil, platformToken)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("erase: %d — %s", rec.Code, rec.Body.String())
+	}
+	var counts struct {
+		Attendees int `json:"booking_attendees"`
+		Answers   int `json:"booking_answers"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &counts); err != nil {
+		t.Fatalf("decode counts: %v", err)
+	}
+	if counts.Attendees != 1 {
+		t.Errorf("booking_attendees erased = %d; want 1", counts.Attendees)
+	}
+	if counts.Answers != 0 {
+		t.Errorf("booking_answers erased = %d; want 0 — another attendee is still on that "+
+			"booking, so the answers are not unambiguously the erased person's", counts.Answers)
+	}
+
+	// Ada is gone from acme, Bob is not, and the booking is untouched.
+	var ada, bob, bookings, status int
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM booking_attendees WHERE workspace_id = 'acme' AND email = 'ada@example.test'`).Scan(&ada); err != nil {
+		t.Fatalf("count ada: %v", err)
+	}
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM booking_attendees WHERE workspace_id = 'acme' AND email = 'bob@example.test'`).Scan(&bob); err != nil {
+		t.Fatalf("count bob: %v", err)
+	}
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM bookings WHERE workspace_id = 'acme'`).Scan(&bookings); err != nil {
+		t.Fatalf("count bookings: %v", err)
+	}
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM bookings WHERE workspace_id = 'acme' AND status = 'confirmed'`).Scan(&status); err != nil {
+		t.Fatalf("count confirmed: %v", err)
+	}
+	if ada != 0 || bob != 1 {
+		t.Errorf("after erasure acme has %d ada and %d bob rows; want 0 and 1", ada, bob)
+	}
+	if bookings != 1 || status != 1 {
+		t.Errorf("bookings = %d (%d confirmed); erasure cancels nothing", bookings, status)
+	}
+
+	// ⛔ And globex's Ada is untouched. The erasure names a workspace, and an erasure
+	// request from one tenant is not consent to delete another tenant's records.
+	var globexAda int
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM booking_attendees WHERE workspace_id = 'globex' AND email = 'ada@example.test'`).Scan(&globexAda); err != nil {
+		t.Fatalf("count globex ada: %v", err)
+	}
+	if globexAda != 1 {
+		t.Errorf("globex's ada rows = %d; want 1 — erasure must not cross the workspace boundary", globexAda)
+	}
+}
+
+// The only-attendee case: with nobody else on the booking, the answers go too.
+func TestPlatformData_eraseTakesAnswersWhenNobodyElseIsOnTheBooking(t *testing.T) {
+	routes, _, platform := newPlatformDataAPI(t)
+	provisionForData(t, routes, "acme", "book.acme.example")
+	seedTenantData(t, platform, "acme")
+
+	rec := doPlatformSub(t, routes["erase"], http.MethodDelete,
+		"/v1/platform/workspaces/acme/attendees?email=ada@example.test", "acme", nil, platformToken)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("erase: %d — %s", rec.Code, rec.Body.String())
+	}
+	var counts struct {
+		Attendees int `json:"booking_attendees"`
+		Answers   int `json:"booking_answers"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &counts); err != nil {
+		t.Fatalf("decode counts: %v", err)
+	}
+	if counts.Attendees != 1 || counts.Answers != 1 {
+		t.Errorf("erased %d attendees and %d answers; want 1 and 1 — she was the only "+
+			"attendee, so the answers were hers", counts.Attendees, counts.Answers)
+	}
+}
+
+func TestPlatformData_eraseRequiresAnEmail(t *testing.T) {
+	routes, _, _ := newPlatformDataAPI(t)
+	provisionForData(t, routes, "acme", "book.acme.example")
+
+	for name, query := range map[string]string{
+		"missing":      "",
+		"not an email": "?email=nobody",
+		"empty":        "?email=",
+	} {
+		t.Run(name, func(t *testing.T) {
+			rec := doPlatformSub(t, routes["erase"], http.MethodDelete,
+				"/v1/platform/workspaces/acme/attendees"+query, "acme", nil, platformToken)
+			if rec.Code != http.StatusBadRequest {
+				t.Errorf("status = %d; want 400 — %s", rec.Code, rec.Body.String())
+			}
+		})
+	}
+}
+
+// All three routes are behind the same token gate as the rest of the platform API.
+func TestPlatformData_routesRefuseWithoutTheToken(t *testing.T) {
+	routes, _, _ := newPlatformDataAPI(t)
+	provisionForData(t, routes, "acme", "book.acme.example")
+
+	for _, c := range []struct {
+		name, method, target, route string
+	}{
+		{"export", http.MethodPost, "/v1/platform/workspaces/acme/export", "export"},
+		{"import", http.MethodPost, "/v1/platform/workspaces/acme/import", "import"},
+		{"erase", http.MethodDelete, "/v1/platform/workspaces/acme/attendees?email=a@b.test", "erase"},
+	} {
+		t.Run(c.name, func(t *testing.T) {
+			rec := doPlatformSub(t, routes[c.route], c.method, c.target, "acme", []byte(`{}`), "")
+			if rec.Code != http.StatusUnauthorized {
+				t.Errorf("status = %d; want 401 without a token", rec.Code)
+			}
+		})
+	}
+}
+
+// A document whose dek_fingerprint names another instance's data key is refused, because
+// every _enc column in it would be undecryptable here — one integration at a time, long
+// after anyone is reading this response.
+func TestPlatformData_importRefusesAForeignDEK(t *testing.T) {
+	routes, _, platform := newPlatformDataAPI(t)
+	provisionForData(t, routes, "acme", "book.acme.example")
+
+	export := doPlatformSub(t, routes["export"], http.MethodPost,
+		"/v1/platform/workspaces/acme/export", "acme", nil, platformToken)
+	if export.Code != http.StatusOK {
+		t.Fatalf("export: %d — %s", export.Code, export.Body.String())
+	}
+
+	var doc map[string]any
+	if err := json.Unmarshal(export.Body.Bytes(), &doc); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	doc["dek_fingerprint"] = "sha256:" + strings.Repeat("ab", 32)
+	foreign, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatalf("encode: %v", err)
+	}
+
+	if rec := doPlatform(t, routes["delete"], http.MethodDelete,
+		"/v1/platform/workspaces/acme", nil, platformToken); rec.Code != http.StatusOK {
+		t.Fatalf("delete: %d", rec.Code)
+	}
+	if _, err := platform.Exec(`
+		INSERT INTO workspaces (id, slug, public_host, region, status, created_at, updated_at)
+		VALUES ('acme', 'acme', 'book.acme.example', 'us', 'active', '2026-09-01T00:00:00Z', '2026-09-01T00:00:00Z')`); err != nil {
+		t.Fatalf("re-create: %v", err)
+	}
+
+	rec := doPlatformSub(t, routes["import"], http.MethodPost,
+		"/v1/platform/workspaces/acme/import", "acme", foreign, platformToken)
+	if rec.Code != http.StatusConflict {
+		t.Fatalf("import with a foreign dek_fingerprint: %d; want 409 — %s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "CALNODE_ENCRYPTION_KEY") {
+		t.Errorf("409 body = %s; want it to name what the operator has to move", rec.Body.String())
+	}
+}
+
+// tenantRowCounts counts every tenant table for a workspace, through the platform handle.
+func tenantRowCounts(t *testing.T, platform *db.DB, wsID string) map[string]int {
+	t.Helper()
+	out := map[string]int{}
+	for _, table := range db.TenantTables {
+		var n int
+		if err := platform.QueryRow(
+			`SELECT COUNT(*) FROM `+table+` WHERE workspace_id = ?`, wsID).Scan(&n); err != nil {
+			t.Fatalf("count %s: %v", table, err)
+		}
+		out[table] = n
+	}
+	return out
+}
diff --git a/internal/server/routes_classified_test.go b/internal/server/routes_classified_test.go
index bf8720d..763f7da 100644
--- a/internal/server/routes_classified_test.go
+++ b/internal/server/routes_classified_test.go
@@ -190,6 +190,9 @@ func TestPlatformRoutesAreTheIdentityHostSet(t *testing.T) {
 		"GET /v1/platform/workspaces/{id}",
 		"PATCH /v1/platform/workspaces/{id}",
 		"DELETE /v1/platform/workspaces/{id}",
+		"POST /v1/platform/workspaces/{id}/export",
+		"POST /v1/platform/workspaces/{id}/import",
+		"DELETE /v1/platform/workspaces/{id}/attendees",
 		// Bootstrap: creates the first user of a single-tenant instance.
 		"POST /v1/setup",
 		// OAuth login and its callbacks live on the identity host, because that is
diff --git a/internal/server/server.go b/internal/server/server.go
index 69d248b..53b6b7e 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -335,6 +335,12 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	mux.HandleFunc("GET /v1/platform/workspaces/{id}", h.Platform((*H).GetWorkspace))
 	mux.HandleFunc("PATCH /v1/platform/workspaces/{id}", h.Platform((*H).PatchWorkspace))
 	mux.HandleFunc("DELETE /v1/platform/workspaces/{id}", h.Platform((*H).DeleteWorkspace))
+	// Export, import and erasure. Export and import are POSTs because each is an operation
+	// on the workspace rather than a representation of it, and because an export is far too
+	// large and too sensitive to be a cacheable GET.
+	mux.HandleFunc("POST /v1/platform/workspaces/{id}/export", h.Platform((*H).ExportWorkspace))
+	mux.HandleFunc("POST /v1/platform/workspaces/{id}/import", h.Platform((*H).ImportWorkspace))
+	mux.HandleFunc("DELETE /v1/platform/workspaces/{id}/attendees", h.Platform((*H).EraseAttendee))
 
 	// Bootstrap — public, once-only
 	mux.HandleFunc("POST /v1/setup", h.Platform((*H).Setup))

From db0180bbab9370b3a3ed085bb3af7bb964ffb8b1 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 06:31:58 -0400
Subject: [PATCH 42/51] handler: a provisioned workspace subscribes to every
 event we emit, not four of them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The platform API's create wrote a subscription for the booking four
(created/cancelled/rescheduled/reminder). This codebase emits SEVEN - recording.completed,
transcript.ready and notes.ready as well - and a receiver on the other side of a provisioned
tenancy handles all of them.

⛔ The four-event subscription is not a smaller feature, it is a silent gap: the three media
events would never be delivered, and that surfaces weeks later as "recordings never appear",
with nothing in either system to point at. The subscription exists, the events fire, and the
rows simply never match.

The three media events fire only when recording or the notetaker is switched on, so a tenancy
without them never receives them anyway. Subscribing is free; not subscribing is a decision
the operator cannot see, and can only undo with an API call nobody knows to make.

provisionedWebhookEvents is one named list rather than an inline marshal, so the set is
reviewable. Enumerated from the tree rather than from memory: every Enqueue call site under
internal/ emits one of these seven and nothing else.

TestPlatform_createSubscribesToEveryEmittedEvent pins the whole list in stored order, so
adding an event to the codebase without adding it here fails.

  --- PASS: TestPlatform_createSubscribesToEveryEmittedEvent (0.88s)
---
 internal/handler/platform.go      | 28 +++++++++++++++++++---
 internal/handler/platform_test.go | 40 +++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+), 3 deletions(-)

diff --git a/internal/handler/platform.go b/internal/handler/platform.go
index a63f8f1..773f452 100644
--- a/internal/handler/platform.go
+++ b/internal/handler/platform.go
@@ -65,6 +65,19 @@ func (h *Handler) platformAuthorized(w http.ResponseWriter, r *http.Request) boo
 	return true
 }
 
+// provisionedWebhookEvents is what a provisioned workspace subscribes to: every event this
+// codebase emits. Kept as one named list so the set is reviewable and testable rather than
+// inline in a marshal call.
+var provisionedWebhookEvents = []string{
+	"booking.created",
+	"booking.cancelled",
+	"booking.rescheduled",
+	"booking.reminder",
+	"recording.completed",
+	"transcript.ready",
+	"notes.ready",
+}
+
 // platformWorkspaceRequest is the create body (D12), settled against the website client.
 type platformWorkspaceRequest struct {
 	ID            string `json:"id"`
@@ -214,9 +227,18 @@ func (h *Handler) CreateWorkspace(w http.ResponseWriter, r *http.Request) {
 			h.writeError(w, http.StatusBadRequest, err.Error())
 			return
 		}
-		events, _ := json.Marshal([]string{
-			"booking.created", "booking.cancelled", "booking.rescheduled", "booking.reminder",
-		})
+		// ⛔ All SEVEN events this codebase emits, not just the booking four. The receiver
+		// on the other side of a provisioned tenancy handles all of them, and a
+		// subscription written with four means the three media events are silently never
+		// delivered — a gap that shows up as "recordings never appear" long after
+		// provisioning, with nothing in either system to point at.
+		//
+		// The three media events fire only when recording or the notetaker is switched on,
+		// so a tenancy without them simply never receives them: subscribing is free, and
+		// not subscribing is a decision the operator cannot see or undo without an API
+		// call nobody knows to make. Enumerated from the tree, not from memory - every
+		// Enqueue call site in internal/ emits one of these and nothing else.
+		events, _ := json.Marshal(provisionedWebhookEvents)
 		// A NULL fields column means "the default payload set" (migration 00027), which
 		// is not the same as an empty selection — so an empty list stays NULL rather than
 		// becoming [], and the webhook keeps the original booking-metadata shape.
diff --git a/internal/handler/platform_test.go b/internal/handler/platform_test.go
index 2b52a14..b9803b8 100644
--- a/internal/handler/platform_test.go
+++ b/internal/handler/platform_test.go
@@ -206,6 +206,46 @@ func TestPlatform_createProvisionsTheWholeWorkspace(t *testing.T) {
 	}
 }
 
+// The event set the provisioned subscription carries, pinned exactly.
+//
+// ⛔ It has to be every event this codebase emits. The receiver on the other side handles
+// all seven, and a subscription short of that means those events are silently never
+// delivered — noticed weeks later as "recordings never appear", with nothing in either
+// system to point at. The three media events fire only when recording or the notetaker is
+// on, so subscribing to them costs a tenancy nothing.
+func TestPlatform_createSubscribesToEveryEmittedEvent(t *testing.T) {
+	routes, _, platform := newPlatformAPI(t)
+
+	if rec := doPlatform(t, routes["create"], http.MethodPost, "/v1/platform/workspaces",
+		platformCreateBody("acme", "book.acme.example"), platformToken); rec.Code != http.StatusCreated {
+		t.Fatalf("create: %d — %s", rec.Code, rec.Body.String())
+	}
+
+	var eventsJSON string
+	if err := platform.QueryRow(
+		`SELECT events FROM webhooks WHERE workspace_id = 'acme'`).Scan(&eventsJSON); err != nil {
+		t.Fatalf("read the subscription: %v", err)
+	}
+	var got []string
+	if err := json.Unmarshal([]byte(eventsJSON), &got); err != nil {
+		t.Fatalf("decode events %q: %v", eventsJSON, err)
+	}
+
+	want := []string{
+		"booking.created", "booking.cancelled", "booking.rescheduled", "booking.reminder",
+		"recording.completed", "transcript.ready", "notes.ready",
+	}
+	if len(got) != len(want) {
+		t.Fatalf("subscribed events = %v; want all %d: %v", got, len(want), want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("event %d = %q; want %q (the order is the stored order, so this pins the "+
+				"whole list rather than its membership)", i, got[i], want[i])
+		}
+	}
+}
+
 // Two workspaces provisioned through the same endpoint must not see each other. This is
 // the assertion that would fail if any INSERT above had left workspace_id to the column
 // default.

From e0d2b4ab4d72cea0bdc1261da70dea77a302184a Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 06:37:44 -0400
Subject: [PATCH 43/51] test: the reminder-race control has to survive -race on
 a loaded box
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A `-race -count=30` run with two other workers on the machine failed 2 times in 30 at the
POSITIVE CONTROL - `no backend ever blocked on a lock` - and never at the run_at assertion.
The fix is holding; the detection was not.

Why `wait_event_type = 'Lock'` alone was not enough: the Lock wait is a STATE THE POLL HAS TO
CATCH THE BACKEND IN, and pg_stat_activity is a sampled view of it. Under -race (several times
slower on the Go side) plus CPU contention, the goroutine issuing the INSERT can still be
inside the driver, or between statements of its transaction, for the entire window the loop
looks at. From that one column, "not blocked yet" and "never going to block" are the same
answer - so the control failed a test whose subject was fine.

⚠️ It is NOT driver-side connection queueing. The PostgreSQL pool defaults to 10 open / 5 idle
(config.PoolFromEnv) and this test uses two connections, so nothing is waiting for one. It is
-race plus load, which is why the remedy is a better signal rather than a bigger pool.

Hardened:
  - a backend in state 'active' running the reschedule's own upsert (matched on its query
    text) counts as well. Such a backend is either about to block on the key or already past
    it; either way the interleaving has been reached, which is all this control claims.
  - deadline 10s -> 30s, so it outlasts a slow loaded box. It is only ever paid when something
    is genuinely wrong.
  - the loud failure stays, and now names both signals, so a run that really never reaches the
    interleaving still fails instead of passing vacuously.

Measured after the change, both 0 failures:
  go test -race -count=30 ...                       rc=0  fails=0
  go test -race -count=30 ... with 4 spinners       rc=0  fails=0
---
 internal/handler/reminder_race_test.go | 39 ++++++++++++++++++++------
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/internal/handler/reminder_race_test.go b/internal/handler/reminder_race_test.go
index acb6ab3..203c2b5 100644
--- a/internal/handler/reminder_race_test.go
+++ b/internal/handler/reminder_race_test.go
@@ -111,18 +111,40 @@ func TestReplaceReminderJobs_upsertSurvivesTheLosingInterleaving(t *testing.T) {
 	}
 }
 
-// waitForLockWaiter blocks until some backend in this database is waiting on a lock,
-// which is the reschedule's INSERT queueing behind the uncommitted key. It fails rather
-// than returning if that never happens: without the block, the test would be exercising
-// the ordinary interleaving and proving nothing.
+// waitForLockWaiter blocks until the reschedule's INSERT is demonstrably queued behind the
+// uncommitted key. It fails rather than returning if that never happens: without the block,
+// the test would be exercising the ordinary interleaving and proving nothing.
+//
+// ⛔ Two signals, because `wait_event_type = 'Lock'` ALONE IS NOT ENOUGH — a `-race
+// -count=30` run on a box with two other workers on it failed here 2 times in 30, always at
+// this control and never at the run_at assertion. The fix was holding; the detection was not.
+//
+// The reason is that the Lock wait is a STATE THIS POLL HAS TO CATCH THE BACKEND IN, and
+// `pg_stat_activity` is a sampled view of it. Under `-race` (several times slower on the Go
+// side) plus CPU contention, the goroutine issuing the INSERT can still be inside the driver,
+// or between statements of its transaction, for the whole window this loop looks at — so "not
+// blocked yet" and "never going to block" are indistinguishable from that one column.
+//
+// ⚠️ It is NOT driver-side queueing: the PostgreSQL pool defaults to 10 open / 5 idle
+// (config.PoolFromEnv) and this test uses two connections, so nothing is waiting for one. It
+// is `-race` plus load, which is why the answer is a better signal rather than a bigger pool.
+//
+// So a backend running the reschedule's own INSERT counts too, identified by its query text.
+// An `active` backend running that statement is either about to block on the key or already
+// past it; either way the interleaving has been reached, which is all this control claims. 30s
+// rather than 10 for the same reason: the deadline has to outlast a slow, loaded box, and it is
+// only ever paid when something is genuinely wrong.
 func waitForLockWaiter(t *testing.T, database *db.DB) {
 	t.Helper()
-	deadline := time.Now().Add(10 * time.Second)
+	deadline := time.Now().Add(30 * time.Second)
 	for time.Now().Before(deadline) {
 		var waiters int
 		if err := database.QueryRow(`
 			SELECT COUNT(*) FROM pg_stat_activity
-			WHERE wait_event_type = 'Lock' AND datname = current_database()`).Scan(&waiters); err != nil {
+			WHERE datname = current_database()
+			  AND (wait_event_type = 'Lock'
+			       OR (state = 'active' AND query LIKE '%ON CONFLICT (workspace_id, type, payload) DO UPDATE%'))`).
+			Scan(&waiters); err != nil {
 			t.Fatalf("read pg_stat_activity: %v", err)
 		}
 		if waiters > 0 {
@@ -130,6 +152,7 @@ func waitForLockWaiter(t *testing.T, database *db.DB) {
 		}
 		time.Sleep(20 * time.Millisecond)
 	}
-	t.Fatal("no backend ever blocked on a lock, so the losing interleaving was never " +
-		"reached and this test would pass whatever ON CONFLICT does")
+	t.Fatal("in 30s no backend ever blocked on a lock and none was running the reschedule's " +
+		"upsert, so the losing interleaving was never reached and this test would pass " +
+		"whatever ON CONFLICT does")
 }

From d2a5ddb4619710114f4349f06e82de7f309ce3d6 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 06:52:59 -0400
Subject: [PATCH 44/51] handler: the SSO hand-off and the OAuth login, both
 halves (D11)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The verify half came with the platform-hooks merge. This is the mint half, plus the
correction that makes the verify half safe on a public host.

⛔ The workspace comes from the HOST; wid is CHECKED against it
--------------------------------------------------------------

The endpoint is reached at https://<public_host>/v1/auth/sso, because landing the cookie on
the tenant's own domain is the entire reason the hand-off exists. Resolving the workspace from
the token's `wid` - which is what the merge left - is therefore wrong: a token for workspace A
presented on B's host has a good signature, a wid that resolves and an aud that matches A's
host, so it would quietly create A's session on B's domain.

Now: workspaceByHost, then wid == that workspace's id (403 {"error":"workspace mismatch"}) and
aud == "https://" + that public host, no trailing slash. Unknown host 404, suspended 503.
Single-tenant is untouched: wid ignored, aud is BASE_URL.

Negative control, resolution put back on wid:

  --- FAIL: TestSSOHandoff_tokenForAnotherWorkspaceIsRefusedOnThisHost
      status = 302; want 403 — <a href="/admin/">Found</a>.
  --- FAIL: TestOAuthHandoff_mintedTokenIsRefusedOnAnotherWorkspacesHost
      status = 302; want 403

That 302 is the bug: one tenant's session on another tenant's domain.

The state cookie carries the workspace; the URL carries only the nonce
---------------------------------------------------------------------

newOAuthState(w, workspaceID) writes <nonce>|<workspace_id> into the HttpOnly
calnode_oauth_state cookie and sends only the nonce to the provider. verifyOAuthState
compares the nonce and READS the workspace.

⛔ That split is the security property. A visitor can rewrite the state query parameter, and
doing so produces a failed login; the value that decides which tenant a Google identity is
admitted to never left this server's cookie. In the URL instead, anyone could choose the tenant
they are let into.

The workspace is resolved at the login START (GET /v1/auth/login, from the Host the person
clicked on), because the callback arrives on the identity host and cannot know it. That route is
Platform-wrapped - it has to be, since its callback is - so it calls workspaceByHost explicitly
and 404s an unrecognised host, doing by hand what HostWorkspace would.

finishOAuthLogin: two bugs, one of them live before this
-------------------------------------------------------

1. ⛔ The lookup was `WHERE email = ?` on the platform handle. Since D9 the unique on users is
   (workspace_id, email), so one address in several workspaces is ordinary - and that statement
   resolves an ARBITRARY one of them and starts a session for a stranger. Now scoped by
   workspace_id in both modes ('default' in single-tenant, where every row carries it), so
   there is one statement and no branch to drift.
2. The session is no longer set here in multi-tenant mode. This callback runs on the identity
   host, and a cookie for it is no use to someone whose admin UI is on their own domain. It
   mints a 30s HS256 token (iss = BASE_URL, aud = https://<public_host>, wid, role = member,
   jti) and redirects to that workspace's /v1/auth/sso.

role = member always: the callback knows only that Google or Microsoft vouched for an address,
which says nothing about what that person may do here. ssoResolveUser leaves an existing user's
role alone, so the value only applies to a user it creates.

⛔ No shared secret means refuse. With CALNODE_SSO_SHARED_SECRET unset the hand-off endpoint
404s, so there is nowhere to land, and setting a cookie on the identity host instead would
produce a session the person's own admin UI cannot see. error=sso, no session.

⚠️ The MCP Connect return keeps its identity-host cookie tail, deliberately: /oauth/authorize is
an identity-host endpoint whose consent-step cookies were set there, so handing it to a tenant's
public host would arrive with none of them.

The calendar callback resolves its workspace from the state's USER
-----------------------------------------------------------------

p.Exchange writes calendar_connections through a provider that captured a handle at
construction. On this Platform route that is the UNBOUND handle, so connecting appeared to
succeed and no row existed. Now the workspace comes from workspaceOfUser on the state's user id
- the state is encrypted, so the id cannot be forged - the exchange runs through
forWorkspace(ws).getCal()'s provider (B5's Provider.ForDB), and the redirect goes to that
workspace's publicURL() rather than h.baseURL, which would have sent the person somewhere their
session does not exist.

⚠️ The workspace is deliberately not ALSO carried in the calendar state: it would be a second
copy of a fact the user id already settles, and two sources of one truth is how they come to
disagree.

⚠️ A trap the test bridge paid for
---------------------------------

Driving finishOAuthLogin on the bare handler reported no_account for a user that exists: the
tail's lookup runs on whatever handle the route gives it, and on the bare handler that is the
unbound application handle, which matches no row. The bridge goes through h.Platform(...) as
server.New does. A bridge that had accepted the bare handler would have been asserting against
the wrong handle.

Gates
-----

  gofmt -l . empty, go vet ./... clean, go build ./... clean
  go test -count=1 ./... rc=0 on SQLite (30/30)
  PostgreSQL: internal/handler rc=0 (302.5s), internal/server rc=0

  --- PASS: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace (0.96s)
  --- PASS: TestSSOHandoff_tokenForAnotherWorkspaceIsRefusedOnThisHost (0.90s)
  --- PASS: TestSSOHandoff_multiTenantRefusesABadWID (3.49s)
  --- PASS: TestSSOHandoff_multiTenantAudienceIsThePublicHost (2.40s)
  --- PASS: TestSSOHandoff_multiTenantReplayIsRefused (0.77s)
  --- PASS: TestSSOHandoff_unknownHostIs404 (0.73s)
  --- PASS: TestSSOHandoff_multiTenantRefusesASuspendedWorkspace (0.71s)
  --- PASS: TestOAuthHandoff_callbackMintsATokenTheSSOEndpointAccepts (0.76s)
  --- PASS: TestOAuthHandoff_mintedTokenIsRefusedOnAnotherWorkspacesHost (0.72s)
  --- PASS: TestOAuthHandoff_refusesWithoutTheSharedSecret (0.76s)
  and the platform branch's own 11 SSO cases still pass on both lanes
---
 PROGRESS.md                              | 192 ++++++++++------
 internal/handler/auth_google.go          |  21 +-
 internal/handler/auth_microsoft.go       |  21 +-
 internal/handler/auth_oauth.go           | 203 +++++++++++++++--
 internal/handler/calendar.go             |  41 +++-
 internal/handler/export_internal_test.go |  23 ++
 internal/handler/sso.go                  |  60 +++--
 internal/handler/sso_tenancy_test.go     | 277 +++++++++++++++++++----
 8 files changed, 671 insertions(+), 167 deletions(-)

diff --git a/PROGRESS.md b/PROGRESS.md
index 23a2de8..577cd85 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1965,75 +1965,125 @@ webhooks resolving their workspace from the row they name. D13 and D14 are done.
 
 ---
 
-## D11, the remaining half — the plan for B6
-
-The verify side is in. What is missing is that **nothing mints an SSO token yet**, so the
-endpoint is unreachable in a real login. Three specifics, so B6 does not re-derive them:
-
-1. **Which callback.** `finishOAuthLogin` in `internal/handler/auth_oauth.go`, the single
-   tail both `CallbackGoogle` and `CallbackMicrosoft` funnel into — it is where
-   `createSession` is called today. In multi-tenant mode it must not set a cookie at all:
-   the callback runs on the identity host (`GET /v1/auth/callback`, Platform), and a
-   cookie for the identity host is no use to a tenant on its own domain. It mints a token
-   and redirects instead. Single-tenant keeps setting the cookie, unchanged.
-
-   ⛔ **And it carries the same hole the SSO endpoint just had, live, today:** its lookup
-   is `SELECT id, archived_at FROM users WHERE email = ?` on the platform handle. For an
-   address that exists in two workspaces that resolves an arbitrary one and starts a
-   session for it. It is not a regression from this merge — it predates the branch — and
-   it cannot be fixed in place, because a Platform route with no `wid` has nothing to
-   scope BY. That is the argument for doing D11's mint half rather than deferring it:
-   until the workspace reaches this function, OAuth login on a multi-tenant instance is
-   guessing.
-
-2. **Which state field carries the workspace.** ⚠️ **Not `EncryptState` — that is a
-   provider-client helper (`internal/zoom`, `internal/caldav`, gcal) for the CONNECT
-   flows, and it encrypts a user id.** The login flow's state is different and simpler:
-   `newOAuthState` mints a 16-byte random nonce, returns it as the `state` URL parameter
-   and sets the same value in the HttpOnly `calnode_oauth_state` cookie; the callback
-   compares the two and consumes the cookie. There is no room in it for a workspace and
-   no signature over it.
-
-   So the workspace goes in the **cookie half**, not the URL half: make the cookie value
-   `<nonce>|<wid>`, keep sending the bare nonce as the `state` parameter, and have the
-   callback split the cookie, compare the nonce, and take the `wid`. The visitor can
-   rewrite the URL parameter, which then simply fails the comparison; the half that is
-   trusted is the half only we ever wrote. `consumeOAuthReturn` (defined in
-   `mcp_oauth_authorize.go`, called from `finishOAuthLogin`) is the precedent: a second
-   piece of callback context riding a cookie rather than a URL.
-
-   The workspace is known at the login START (`GET /v1/auth/login`), from the Host the
-   person clicked "sign in with Google" on. ⚠️ That route is **Platform** today because
-   the callbacks have to be, so B6 must resolve the workspace there explicitly with
-   `workspaceByHost` and 404 an unknown host exactly as `HostWorkspace` would — a resolver
-   cannot do it, or the callback would need a tenant Host it does not have.
-
-3. **How the token is minted.** Reuse `sso.go`'s own claim shape, signed with
-   `CALNODE_SSO_SHARED_SECRET` (HS256, the verifier is deliberately not a JWT library) —
-   ⛔ which means the SSO endpoint must be CONFIGURED for multi-tenant OAuth login to
-   work at all, and `config.Validate` should refuse `MULTI_TENANT` + a Google or Microsoft
-   OAuth app + an empty `CALNODE_SSO_SHARED_SECRET` rather than letting every social login
-   500 at the last step. Claims: `iss` = this instance's `BASE_URL`, `aud` =
-   `https://<ws.public_host>` (what `ssoAudience` checks), `wid` = the state's workspace,
-   `sub` = the verified email from the provider, `name`, `role` = `member` (the OAuth
-   callback is not an authority on roles; `ssoResolveUser` leaves an existing user's role
-   alone and a new one is a member unless an invite said otherwise), `iat`/`exp` = now and
-   now + 30s, `jti` = `uid.New()`. Then
-   `302 https://<ws.public_host>/v1/auth/sso?token=…&next=<destination>`, where
-   `<destination>` is what `finishOAuthLogin` would have redirected to itself: `/admin`,
-   or the `consumeOAuthReturn` value when the login was started by an MCP Connect flow
-   (already validated by `safeLocalPath`, which permits only `/oauth/authorize`).
-   ⚠️ **That second case needs a decision, not a copy.** `/oauth/authorize` is an identity-host
-   endpoint and its consent-step cookies were set there, so sending it to the tenant's public
-   host would arrive with none of them. Either keep the Connect flow's tail on the identity
-   host (mint no token, set the cookie there as today, since an MCP consent is not a
-   booker-facing surface) or hand off first and bounce back — the first is smaller and is
-   what the shape of the rest of D11 suggests.
-   ⚠️ The `next` value must go through `ssoNextPath`'s rules on the way in, not just on
-   the way out, or the redirect the callback builds is an open redirect that happens to be
-   validated one hop later.
-   ⚠️ And the calendar connect callbacks are the same shape but NOT the same fix: they
-   store tokens rather than mint a session, so they need the state's `wid` to write the
-   `calendar_connections` row through `forWorkspace(ws)` and then redirect to that
-   workspace's `/admin/calendar?connected=true` — no SSO token involved.
+## Boundary 6, part three — the SSO hand-off and the OAuth login, both halves (D11)
 
+The verify half arrived with the platform-hooks merge; this is the mint half, plus the
+correction that makes the verify half safe on a public host.
+
+### ⛔ The workspace comes from the HOST, and `wid` is CHECKED against it
+
+The endpoint is reached at `https://<public_host>/v1/auth/sso`, because landing the cookie on
+the tenant's own domain is the entire reason the hand-off exists. So resolving the workspace
+from the token's `wid` — which is what the merge left — is wrong: a token for workspace A
+presented on **B's** host has a valid signature, a `wid` that resolves, and an `aud` that
+matches A's host, so it would quietly create **A's session on B's domain**.
+
+Now: resolve by `workspaceByHost`, then require `wid == that workspace's id` (403
+`{"error":"workspace mismatch"}`, D10's body) and `aud == "https://" + that public host`, no
+trailing slash. Unknown host 404, suspended 503. Single-tenant unchanged: `wid` ignored, `aud`
+is `BASE_URL`.
+
+Negative control, the resolution put back on `wid`:
+
+```
+--- FAIL: TestSSOHandoff_tokenForAnotherWorkspaceIsRefusedOnThisHost
+    status = 302; want 403 — <a href="/admin/">Found</a>.
+--- FAIL: TestOAuthHandoff_mintedTokenIsRefusedOnAnotherWorkspacesHost
+    status = 302; want 403
+```
+
+That 302 IS the bug: one tenant's session created on another tenant's domain.
+
+### The state cookie carries the workspace; the URL carries only the nonce
+
+`newOAuthState(w, workspaceID)` writes `<nonce>|<workspace_id>` into the HttpOnly
+`calnode_oauth_state` cookie and sends only the nonce to the provider.
+`verifyOAuthState` compares the nonce and **reads** the workspace.
+
+⛔ That split is the security property. A visitor can rewrite the `state` query parameter —
+doing so produces a failed login. The value that decides which tenant a Google identity is
+admitted to never left this server's cookie. Putting the workspace in the URL instead would let
+anyone choose the tenant they are let into.
+
+The workspace is resolved at the login START (`GET /v1/auth/login`, from the Host the person
+clicked on), because the callback arrives on the identity host and cannot know it. That route
+is `Platform`-wrapped — it has to be, since its callback is — so it calls `workspaceByHost`
+explicitly and 404s an unrecognised host, doing by hand exactly what `HostWorkspace` would.
+
+### `finishOAuthLogin`: two bugs, one of them live before this
+
+1. ⛔ **The lookup was `WHERE email = ?` on the platform handle.** Since D9 the unique on
+   `users` is `(workspace_id, email)`, so the same address in several workspaces is ordinary —
+   and that statement resolves an **arbitrary** one of them and starts a session for a
+   stranger. Now scoped by `workspace_id`, in both modes (`'default'` in single-tenant, where
+   every row carries it), so there is one statement and no branch to drift.
+2. **The session is no longer set here in multi-tenant mode.** The callback runs on the
+   identity host; a cookie for it is no use to a person whose admin UI is on their own domain.
+   It mints a 30 s HS256 token (`iss` = BASE_URL, `aud` = `https://<public_host>`, `wid`,
+   `role = member`, `jti`) and redirects to that workspace's `/v1/auth/sso`.
+
+`role = member` always: the callback knows that Google or Microsoft vouched for an address,
+which says nothing about what that person may do here. `ssoResolveUser` leaves an existing
+user's role alone, so the value only ever applies to a user it creates.
+
+⛔ **No shared secret ⇒ refuse.** With `CALNODE_SSO_SHARED_SECRET` unset the hand-off endpoint
+404s, so there is nowhere to land; setting a cookie on the identity host instead would produce
+a session the person's own admin UI cannot see. `error=sso`, no session.
+
+⚠️ **The MCP Connect return keeps its identity-host cookie tail**, deliberately:
+`/oauth/authorize` is an identity-host endpoint whose consent-step cookies were set there, so
+handing it to a tenant's public host would arrive with none of them.
+
+### The calendar callback resolves its workspace from the state's USER
+
+`p.Exchange` writes `calendar_connections` through a provider that captured a handle at
+construction. On this `Platform` route that is the **unbound** handle, so the connection
+appeared to succeed and no row existed. Now the workspace comes from `workspaceOfUser` on the
+state's user id — the state is encrypted, so the id cannot be forged — the exchange runs
+through `forWorkspace(ws).getCal()`'s provider (B5's `Provider.ForDB`), and the redirect goes
+to that workspace's `publicURL()` rather than `h.baseURL`, which would have sent the person
+somewhere their session does not exist.
+
+⚠️ The workspace is deliberately **not** also carried in the calendar state: it would be a
+second copy of a fact the user id already settles, and two sources of one truth is how they
+come to disagree.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+`go test -count=1 ./...` **rc=0 on SQLite (30/30)**. PostgreSQL: `internal/handler` **rc=0**
+(302.5s), `internal/server` **rc=0**.
+
+```
+--- PASS: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace (0.96s)
+--- PASS: TestSSOHandoff_tokenForAnotherWorkspaceIsRefusedOnThisHost (0.90s)
+--- PASS: TestSSOHandoff_multiTenantRefusesABadWID (3.49s)     [missing, empty, unknown, not an id]
+--- PASS: TestSSOHandoff_multiTenantAudienceIsThePublicHost (2.40s)  [identity host, bare host, trailing slash]
+--- PASS: TestSSOHandoff_multiTenantReplayIsRefused (0.77s)
+--- PASS: TestSSOHandoff_unknownHostIs404 (0.73s)
+--- PASS: TestSSOHandoff_multiTenantRefusesASuspendedWorkspace (0.71s)
+--- PASS: TestOAuthHandoff_callbackMintsATokenTheSSOEndpointAccepts (0.76s)
+--- PASS: TestOAuthHandoff_mintedTokenIsRefusedOnAnotherWorkspacesHost (0.72s)
+--- PASS: TestOAuthHandoff_refusesWithoutTheSharedSecret (0.76s)
+```
+
+⚠️ **A trap the test bridge paid for.** Driving `finishOAuthLogin` on the bare handler reported
+`no_account` for a user that exists: the tail's lookup runs on whatever handle the route gives
+it, and on the bare handler that is the **unbound application** handle, which matches no row.
+The bridge goes through `h.Platform(...)` as `server.New` does. A test that had accepted the
+bare handler would have been asserting against the wrong handle.
+
+### Still owed by B6
+
+Only the vendor webhooks: `POST /v1/livekit/webhook` (+ its alias) and `POST /v1/stripe/webhook`
+must resolve their workspace from the room or session row they name, then hand off to
+`forWorkspace`. D12, D13 and D14 are done.
+
+## D11 — the plan this replaced
+
+⚠️ This file carried a plan for the SSO mint half between the merge and part three above.
+It is now BUILT, and part three is the record; the plan is deleted rather than annotated,
+because a plan left beside its implementation is the next reader's wrong answer. Two of its
+three points survived contact unchanged (the callback to change, and the `<nonce>|<wid>`
+state cookie). The third did not: the plan had the SSO endpoint resolving its workspace from
+`wid`, and doing that on a public host is what part three had to fix.
diff --git a/internal/handler/auth_google.go b/internal/handler/auth_google.go
index 67c900c..58d118c 100644
--- a/internal/handler/auth_google.go
+++ b/internal/handler/auth_google.go
@@ -43,7 +43,21 @@ func (h *Handler) LoginGoogle(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Google OAuth not configured — set GOOGLE_CLIENT_ID", http.StatusServiceUnavailable)
 		return
 	}
-	state, err := h.newOAuthState(w)
+	// ⛔ The workspace is resolved HERE, from the Host the person clicked "sign in" on. The
+	// callback arrives on the identity host and cannot resolve it, which is why it rides the
+	// state cookie. /v1/auth/login is Platform-wrapped (it has to be, because its callback
+	// is), so this does explicitly what HostWorkspace would have done — including 404 on a
+	// host that names no workspace, rather than defaulting to a tenant nobody chose.
+	loginWorkspace := ""
+	if h.multiTenant {
+		ws, wsErr := h.workspaceByHost(r.Context(), r.Host)
+		if wsErr != nil {
+			h.writeResolveError(w, r, wsErr)
+			return
+		}
+		loginWorkspace = ws.ID
+	}
+	state, err := h.newOAuthState(w, loginWorkspace)
 	if err != nil {
 		h.logger.ErrorContext(r.Context(), "auth: generate state", "error", err)
 		http.Error(w, "internal error", http.StatusInternalServerError)
@@ -62,7 +76,8 @@ func (h *Handler) CallbackGoogle(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// Verify CSRF state (cookie must match the URL param) and consume it.
-	if !h.verifyOAuthState(w, r) {
+	stateWorkspace, stateOK := h.verifyOAuthState(w, r)
+	if !stateOK {
 		http.Redirect(w, r, "/admin/login?error=state", http.StatusFound)
 		return
 	}
@@ -88,7 +103,7 @@ func (h *Handler) CallbackGoogle(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// Only existing users can log in — no self-registration.
-	h.finishOAuthLogin(w, r, info.Email)
+	h.finishOAuthLogin(w, r, info.Email, stateWorkspace)
 }
 
 // Logout deletes the session record and clears the session cookie.
diff --git a/internal/handler/auth_microsoft.go b/internal/handler/auth_microsoft.go
index 817bc55..0aba327 100644
--- a/internal/handler/auth_microsoft.go
+++ b/internal/handler/auth_microsoft.go
@@ -40,7 +40,21 @@ func (h *Handler) LoginMicrosoft(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Microsoft OAuth not configured", http.StatusServiceUnavailable)
 		return
 	}
-	state, err := h.newOAuthState(w)
+	// ⛔ The workspace is resolved HERE, from the Host the person clicked "sign in" on. The
+	// callback arrives on the identity host and cannot resolve it, which is why it rides the
+	// state cookie. /v1/auth/login is Platform-wrapped (it has to be, because its callback
+	// is), so this does explicitly what HostWorkspace would have done — including 404 on a
+	// host that names no workspace, rather than defaulting to a tenant nobody chose.
+	loginWorkspace := ""
+	if h.multiTenant {
+		ws, wsErr := h.workspaceByHost(r.Context(), r.Host)
+		if wsErr != nil {
+			h.writeResolveError(w, r, wsErr)
+			return
+		}
+		loginWorkspace = ws.ID
+	}
+	state, err := h.newOAuthState(w, loginWorkspace)
 	if err != nil {
 		h.logger.ErrorContext(r.Context(), "auth: generate state", "error", err)
 		http.Error(w, "internal error", http.StatusInternalServerError)
@@ -59,7 +73,8 @@ func (h *Handler) CallbackMicrosoft(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Microsoft OAuth not configured", http.StatusServiceUnavailable)
 		return
 	}
-	if !h.verifyOAuthState(w, r) {
+	stateWorkspace, stateOK := h.verifyOAuthState(w, r)
+	if !stateOK {
 		http.Redirect(w, r, "/admin/login?error=state", http.StatusFound)
 		return
 	}
@@ -81,7 +96,7 @@ func (h *Handler) CallbackMicrosoft(w http.ResponseWriter, r *http.Request) {
 		http.Redirect(w, r, "/admin/login?error=userinfo", http.StatusFound)
 		return
 	}
-	h.finishOAuthLogin(w, r, email)
+	h.finishOAuthLogin(w, r, email, stateWorkspace)
 }
 
 type microsoftUserInfo struct {
diff --git a/internal/handler/auth_oauth.go b/internal/handler/auth_oauth.go
index bc8f9d0..8a8c7a0 100644
--- a/internal/handler/auth_oauth.go
+++ b/internal/handler/auth_oauth.go
@@ -4,21 +4,42 @@ import (
 	"crypto/rand"
 	"database/sql"
 	"encoding/hex"
+	"fmt"
 	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/calnode/calnode/internal/uid"
 )
 
 // newOAuthState generates a CSRF state token, sets it as a short-lived cookie, and
-// returns it for inclusion in the provider's authorize URL. Shared by the Google
+// returns the value to put in the provider's authorize URL. Shared by the Google
 // and Microsoft sign-in flows.
-func (h *Handler) newOAuthState(w http.ResponseWriter) (string, error) {
+//
+// ⛔ The workspace rides the COOKIE, never the URL. The cookie value is
+// `<nonce>|<workspace_id>` and only the nonce goes to the provider, so the value that
+// decides which tenant a login lands in is one this server wrote and the browser only
+// echoed back. A visitor can rewrite the `state` query parameter; doing so just fails the
+// comparison. Putting the workspace there instead would let anyone choose the tenant their
+// Google identity is admitted to.
+//
+// The workspace is known HERE and not at the callback: the person clicked "sign in with
+// Google" on their own public host, and the callback arrives on the identity host, which
+// names no tenant. That asymmetry is the whole reason this parameter exists (D11).
+func (h *Handler) newOAuthState(w http.ResponseWriter, workspaceID string) (string, error) {
 	b := make([]byte, 16)
 	if _, err := rand.Read(b); err != nil {
 		return "", err
 	}
 	state := hex.EncodeToString(b)
+	cookieValue := state
+	if workspaceID != "" {
+		cookieValue = state + oauthStateSep + workspaceID
+	}
 	http.SetCookie(w, &http.Cookie{ // #nosec G124 -- HttpOnly/SameSite/Secure are all set; Secure is h.secureCookie (dynamic on BASE_URL scheme), which gosec's static check can't verify
 		Name:     stateCookieName,
-		Value:    state,
+		Value:    cookieValue,
 		Path:     "/",
 		MaxAge:   int(stateDuration.Seconds()),
 		HttpOnly: true,
@@ -28,11 +49,26 @@ func (h *Handler) newOAuthState(w http.ResponseWriter) (string, error) {
 	return state, nil
 }
 
-// verifyOAuthState checks the ?state param against the state cookie and clears the
-// cookie regardless (single use). Returns true when they match.
-func (h *Handler) verifyOAuthState(w http.ResponseWriter, r *http.Request) bool {
+// oauthStateSep separates the CSRF nonce from the workspace id inside the state cookie.
+// A workspace id is [a-z0-9_-]{1,64} and a nonce is hex, so neither can contain it.
+const oauthStateSep = "|"
+
+// verifyOAuthState checks the ?state param against the state cookie, clears the cookie
+// regardless (single use), and returns the workspace the login was started from.
+//
+// The nonce is compared; the workspace is READ. That split is the security property: the
+// query parameter only has to match, so an attacker rewriting it achieves a failed login,
+// while the value that selects the tenant never left this server's cookie.
+func (h *Handler) verifyOAuthState(w http.ResponseWriter, r *http.Request) (string, bool) {
 	c, err := r.Cookie(stateCookieName)
-	ok := err == nil && c.Value != "" && r.URL.Query().Get("state") == c.Value
+	nonce, workspaceID := "", ""
+	if err == nil {
+		nonce = c.Value
+		if i := strings.Index(c.Value, oauthStateSep); i >= 0 {
+			nonce, workspaceID = c.Value[:i], c.Value[i+1:]
+		}
+	}
+	ok := err == nil && nonce != "" && r.URL.Query().Get("state") == nonce
 	http.SetCookie(w, &http.Cookie{ // #nosec G124 -- HttpOnly/SameSite/Secure are all set; Secure is h.secureCookie (dynamic on BASE_URL scheme), which gosec's static check can't verify
 		Name:     stateCookieName,
 		Value:    "",
@@ -42,18 +78,65 @@ func (h *Handler) verifyOAuthState(w http.ResponseWriter, r *http.Request) bool
 		SameSite: http.SameSiteLaxMode,
 		Secure:   h.secureCookie,
 	})
-	return ok
+	return workspaceID, ok
 }
 
-// finishOAuthLogin resolves an OAuth-verified email to an existing, non-archived
-// user and starts a session, redirecting to /admin on success or /admin/login with
-// an error otherwise. Self-registration is not allowed — only known emails sign in.
-func (h *Handler) finishOAuthLogin(w http.ResponseWriter, r *http.Request, email string) {
+// finishOAuthLogin resolves an OAuth-verified email to an existing, non-archived user and
+// starts a session. Self-registration is not allowed — only known emails sign in.
+//
+// workspaceID is the tenant the login STARTED from, recovered from the state cookie. It is
+// "" in single-tenant mode, where this function behaves exactly as it always has: look the
+// email up, create a session, redirect to /admin.
+//
+// ⛔ In multi-tenant mode two things change, and both were bugs before D11 landed:
+//
+//  1. The lookup is scoped. `SELECT id FROM users WHERE email = ?` on the platform handle
+//     resolves an ARBITRARY workspace's user when the same address exists in several — which
+//     since D9 is legitimate and ordinary — and then starts a session for that stranger.
+//  2. The session is not set here. This callback runs on the IDENTITY host
+//     (GET /v1/auth/callback, Platform), and a cookie for the identity host is no use to a
+//     person whose admin UI is on their own domain. So it mints a short-lived SSO token for
+//     the workspace and redirects to that workspace's public host, which is the only place
+//     the cookie can be set (D11).
+//
+// The MCP Connect return is the deliberate exception: /oauth/authorize is an identity-host
+// endpoint whose consent-step cookies were set there, so sending it to a tenant's public
+// host would arrive with none of them. That tail keeps its identity-host cookie.
+func (h *Handler) finishOAuthLogin(w http.ResponseWriter, r *http.Request, email, workspaceID string) {
+	email = strings.ToLower(strings.TrimSpace(email))
+
+	ws := DefaultWorkspace
+	if h.multiTenant {
+		if workspaceID == "" {
+			// The state cookie carried no workspace, so the login did not start on a
+			// tenant's host. Nothing can be resolved from an OAuth identity alone.
+			h.logger.WarnContext(r.Context(), "auth: oauth login with no workspace in state")
+			http.Redirect(w, r, "/admin/login?error=workspace", http.StatusFound)
+			return
+		}
+		resolved, err := h.workspaceByID(r.Context(), workspaceID)
+		if err != nil {
+			h.logger.ErrorContext(r.Context(), "auth: resolve workspace from state",
+				"error", err, "workspace_id", workspaceID)
+			http.Redirect(w, r, "/admin/login?error=workspace", http.StatusFound)
+			return
+		}
+		if resolved.Suspended() {
+			http.Redirect(w, r, "/admin/login?error=suspended", http.StatusFound)
+			return
+		}
+		ws = resolved
+	}
+
 	var userID string
 	var archivedAt sql.NullString
+	// workspace_id is named even in single-tenant mode, where it is 'default' and every row
+	// carries it: one statement, one behaviour, and no branch that could drift.
 	if err := h.db.QueryRowContext(r.Context(),
-		`SELECT id, archived_at FROM users WHERE email = ?`, email).Scan(&userID, &archivedAt); err != nil {
-		h.logger.WarnContext(r.Context(), "auth: no account for email", "email", email)
+		`SELECT id, archived_at FROM users WHERE workspace_id = ? AND email = ?`,
+		ws.ID, email).Scan(&userID, &archivedAt); err != nil {
+		h.logger.WarnContext(r.Context(), "auth: no account for email",
+			"email", email, "workspace_id", ws.ID)
 		http.Redirect(w, r, "/admin/login?error=no_account", http.StatusFound)
 		return
 	}
@@ -61,16 +144,92 @@ func (h *Handler) finishOAuthLogin(w http.ResponseWriter, r *http.Request, email
 		http.Redirect(w, r, "/admin/login?error=archived", http.StatusFound)
 		return
 	}
-	if err := h.createSession(r.Context(), w, userID); err != nil {
-		h.logger.ErrorContext(r.Context(), "auth: create session", "error", err)
-		http.Redirect(w, r, "/admin/login?error=session", http.StatusFound)
-		return
-	}
-	// If this login was initiated by an MCP "Connect" flow, return to /oauth/authorize
-	// (the consent step) rather than the admin home.
+
+	// If this login was initiated by an MCP "Connect" flow, return to /oauth/authorize (the
+	// consent step) on THIS host, with the cookie set here — see the note above.
 	if dest, ok := h.consumeOAuthReturn(w, r); ok {
+		if err := h.createSessionIn(r.Context(), w, userID, sessionWorkspace(h, ws)); err != nil {
+			h.logger.ErrorContext(r.Context(), "auth: create session", "error", err)
+			http.Redirect(w, r, "/admin/login?error=session", http.StatusFound)
+			return
+		}
 		http.Redirect(w, r, dest, http.StatusFound) // #nosec G710 -- dest is validated by safeLocalPath (only "/oauth/authorize", never "//") both when set and when consumed; gosec's taint analysis can't trace through that check
 		return
 	}
-	http.Redirect(w, r, "/admin", http.StatusFound)
+
+	if !h.multiTenant {
+		if err := h.createSessionIn(r.Context(), w, userID, ""); err != nil {
+			h.logger.ErrorContext(r.Context(), "auth: create session", "error", err)
+			http.Redirect(w, r, "/admin/login?error=session", http.StatusFound)
+			return
+		}
+		http.Redirect(w, r, "/admin", http.StatusFound)
+		return
+	}
+
+	// Multi-tenant: hand off to the workspace's own host, which is where the cookie belongs.
+	token, err := h.mintSSOToken(ws, email, ssoHandoffName(r), "member")
+	if err != nil {
+		h.logger.ErrorContext(r.Context(), "auth: mint sso token", "error", err,
+			"workspace_id", ws.ID)
+		http.Redirect(w, r, "/admin/login?error=sso", http.StatusFound)
+		return
+	}
+	target := "https://" + ws.PublicHost + "/v1/auth/sso?token=" + url.QueryEscape(token) +
+		"&next=" + url.QueryEscape(ssoDefaultNext)
+	h.logger.InfoContext(r.Context(), "auth: handing off to the workspace host",
+		"workspace_id", ws.ID, "public_host", ws.PublicHost)
+	http.Redirect(w, r, target, http.StatusFound) // #nosec G710 -- ws.PublicHost comes from the workspaces row, not from the request
+}
+
+// sessionWorkspace is the workspace id a session row should name: nothing in single-tenant
+// mode (the column default is correct there and the statement stays as it was), the resolved
+// workspace otherwise, because a Platform route's handle binds nothing.
+func sessionWorkspace(h *Handler, ws *Workspace) string {
+	if !h.multiTenant {
+		return ""
+	}
+	return ws.ID
+}
+
+// ssoHandoffName is the display name to create a user with, if the hand-off ends up creating
+// one. The OAuth callback knows the verified email but not always a name, and a hand-off with
+// an empty name is refused by the SSO endpoint's own validation — so the local part stands in
+// until the person edits it.
+func ssoHandoffName(r *http.Request) string {
+	if n := strings.TrimSpace(r.URL.Query().Get("name")); n != "" {
+		return n
+	}
+	return "New user"
+}
+
+// mintSSOToken signs the hand-off token the SSO endpoint verifies (D11).
+//
+// ⛔ role is always "member". The OAuth callback is not an authority on roles: it knows that
+// Google or Microsoft vouched for an email address, which says nothing about what that person
+// may do here. ssoResolveUser leaves an existing user's role alone, so this value only ever
+// applies to a user it creates.
+//
+// exp is 30s out, half the endpoint's 60s ceiling: the token is spent by a browser following
+// a redirect it already has in hand.
+func (h *Handler) mintSSOToken(ws *Workspace, email, name, role string) (string, error) {
+	if h.ssoSecret == "" {
+		// ⛔ Not a silent fallback. Without the shared secret the hand-off endpoint 404s, so
+		// there is nowhere for this login to land, and setting a cookie on the identity host
+		// instead would produce a session the person's admin UI cannot see.
+		return "", fmt.Errorf("CALNODE_SSO_SHARED_SECRET is not set, so a multi-tenant OAuth login has nowhere to hand off to")
+	}
+	now := time.Now().UTC()
+	claims := ssoClaims{
+		Iss:  h.baseURL,
+		Aud:  "https://" + ws.PublicHost,
+		Sub:  email,
+		Name: name,
+		Role: role,
+		Iat:  now.Unix(),
+		Exp:  now.Add(30 * time.Second).Unix(),
+		JTI:  uid.New(),
+		WID:  ws.ID,
+	}
+	return signSSOToken(claims, h.ssoSecret)
 }
diff --git a/internal/handler/calendar.go b/internal/handler/calendar.go
index 2514781..50df347 100644
--- a/internal/handler/calendar.go
+++ b/internal/handler/calendar.go
@@ -91,6 +91,43 @@ func (h *Handler) CalendarCallback(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// ⛔ The workspace comes from the STATE, via the user it names, and the exchange runs
+	// bound to it. This route is Platform-wrapped — the callback arrives on the identity host
+	// with no tenant Host and no session — so h and its calendar providers hold the UNBOUND
+	// handle, which under the policies writes nothing: the connection would appear to succeed
+	// and no calendar_connections row would exist.
+	//
+	// The state is encrypted (the provider's own EncryptState), so the user id inside it
+	// cannot be forged, and workspaceOfUser resolves the tenant from it on the platform
+	// handle. That is why the workspace is not ALSO carried in the state: it would be a second
+	// copy of a fact the user id already settles, and two sources of one truth is how they
+	// come to disagree.
+	scoped := h
+	if h.multiTenant {
+		wsID, wsErr := h.workspaceOfUser(r.Context(), userID)
+		if wsErr != nil {
+			h.logger.ErrorContext(r.Context(), "calendar callback: resolve workspace",
+				"error", wsErr, "user_id", userID)
+			h.writeError(w, http.StatusBadRequest, "invalid or missing state")
+			return
+		}
+		ws, wsErr := h.workspaceByID(r.Context(), wsID)
+		if wsErr != nil {
+			h.logger.ErrorContext(r.Context(), "calendar callback: read workspace",
+				"error", wsErr, "workspace_id", wsID)
+			h.writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		scoped = h.forWorkspace(ws)
+		// The provider has to be the workspace's own, not the process-wide registry's: each
+		// captures a *db.DB at construction (B5, calendar.Provider.ForDB).
+		if svcScoped := scoped.getCal(); svcScoped != nil {
+			if pr := svcScoped.Provider(p.Name()); pr != nil {
+				p = pr
+			}
+		}
+	}
+
 	if err := p.Exchange(r.Context(), userID, code, "primary"); err != nil {
 		h.logger.ErrorContext(r.Context(), "calendar callback: exchange", "error", err, "user_id", userID)
 		h.writeError(w, http.StatusInternalServerError, "internal error")
@@ -99,7 +136,9 @@ func (h *Handler) CalendarCallback(w http.ResponseWriter, r *http.Request) {
 	// Multi-calendar: connecting is additive. The first connection becomes the destination
 	// (handled in the provider's saveToken); subsequent ones are conflict-check only.
 
-	http.Redirect(w, r, h.baseURL+"/admin/calendar?connected=true", http.StatusFound)
+	// Back to the workspace's own admin UI, which is on its public host — h.baseURL is the
+	// identity host and would send the person somewhere their session does not exist.
+	http.Redirect(w, r, scoped.publicURL()+"/admin/calendar?connected=true", http.StatusFound)
 }
 
 // ConnectCalDAV handles POST /v1/calendar/caldav/connect (auth required). CalDAV is
diff --git a/internal/handler/export_internal_test.go b/internal/handler/export_internal_test.go
index 7c72656..d315c3d 100644
--- a/internal/handler/export_internal_test.go
+++ b/internal/handler/export_internal_test.go
@@ -2,6 +2,8 @@ package handler
 
 import (
 	"context"
+	"net/http"
+	"net/http/httptest"
 	"time"
 )
 
@@ -15,3 +17,24 @@ import (
 func ReplaceReminderJobsForTest(h *Handler, ctx context.Context, bookingID, etID string, newStart time.Time) error {
 	return h.replaceReminderJobs(ctx, bookingID, etID, newStart)
 }
+
+// FinishOAuthLoginForTest drives the OAuth callback's tail and returns the Location it
+// redirected to, so the external test package can spend the token it minted against the real
+// SSO endpoint. It returns "" if no redirect was issued.
+//
+// The tail is what D11 changed, and it is reachable no other way without standing up a fake
+// Google: the exchange above it needs a provider. Driving it directly keeps the test about the
+// hand-off rather than about oauth2.
+func FinishOAuthLoginForTest(h *Handler, email, workspaceID string) string {
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/v1/auth/callback", nil)
+	// ⛔ Through Platform, because that is how the route is registered and it decides which
+	// handle the tail runs on. Called on the bare handler the lookup would use the UNBOUND
+	// application handle, which under the policies matches no row — the login would report
+	// "no account" for a user that exists, which is precisely the failure mode this bridge
+	// would otherwise hide.
+	h.Platform(func(p *Handler, w http.ResponseWriter, r *http.Request) {
+		p.finishOAuthLogin(w, r, email, workspaceID)
+	})(rec, req)
+	return rec.Header().Get("Location")
+}
diff --git a/internal/handler/sso.go b/internal/handler/sso.go
index 0d19666..5f7df63 100644
--- a/internal/handler/sso.go
+++ b/internal/handler/sso.go
@@ -59,6 +59,24 @@ type ssoClaims struct {
 	WID string `json:"wid"`
 }
 
+// signSSOToken produces the compact HS256 JWS the verifier below accepts. It is the mint
+// half of D11, used by the OAuth callbacks.
+//
+// ⛔ Deliberately NOT a JWT library, for the same reason verifySSOToken is not one: one
+// algorithm, one key, a fixed claim set, and no dependency to keep current. The two halves
+// live beside each other so a change to either is made looking at the other.
+func signSSOToken(claims ssoClaims, secret string) (string, error) {
+	header := base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"HS256","typ":"JWT"}`))
+	payload, err := json.Marshal(claims)
+	if err != nil {
+		return "", fmt.Errorf("sso: marshal claims: %w", err)
+	}
+	signingInput := header + "." + base64.RawURLEncoding.EncodeToString(payload)
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write([]byte(signingInput))
+	return signingInput + "." + base64.RawURLEncoding.EncodeToString(mac.Sum(nil)), nil
+}
+
 // The three ways the wid claim fails. All three are 401 with the message in the body:
 // the token is the caller's, and so is the mistake. They are sentinels rather than
 // strings so SSOHandoff can tell them from a database error, which is a 500.
@@ -121,9 +139,12 @@ func (h *Handler) SSOHandoff(w http.ResponseWriter, r *http.Request) {
 	// The workspace comes from the token, after the signature and before anything is
 	// written. Resolved here rather than in Scoped because this route is Platform: no
 	// tenant Host, no credential yet, so the `wid` claim is the only source (D11).
-	ws, err := h.ssoWorkspace(r.Context(), claims)
+	ws, err := h.ssoWorkspace(r.Context(), r, claims)
 	switch {
-	case errors.Is(err, errWorkspaceSuspended):
+	case errors.Is(err, errWorkspaceSuspended), errors.Is(err, errUnknownHost), errors.Is(err, errWorkspaceMismatch):
+		// 503, 404 and 403 respectively, from the one place that maps a resolution failure
+		// to a response. A mismatch is 403 {"error":"workspace mismatch"} (D10), the same
+		// answer an API key from another workspace gets on this host.
 		h.writeResolveError(w, r, err)
 		return
 	case errors.Is(err, errSSOWIDRequired), errors.Is(err, errSSOUnknownWID), errors.Is(err, errSSONoPublicHost):
@@ -195,28 +216,18 @@ func (h *Handler) SSOHandoff(w http.ResponseWriter, r *http.Request) {
 //
 // Single-tenant: the one workspace, and `wid` is ignored (see the claim's comment).
 //
-// Multi-tenant: the `wid` claim, read back through the platform handle so a token
-// naming a deleted or suspended workspace is refused rather than creating a user
-// nothing can reach. A workspace with no public_host is refused too: the hand-off
-// exists to set a cookie on a tenant's own domain, and a tenant without one has no
-// domain for the token to be bound to.
-func (h *Handler) ssoWorkspace(ctx context.Context, claims ssoClaims) (*Workspace, error) {
+// ⛔ Multi-tenant: the workspace of the REQUEST HOST, with the token's `wid` checked against
+// it. Resolving from the host rather than from the token is what makes a stolen or
+// misdirected token useless: this endpoint is reached at `https://<public_host>/v1/auth/sso`
+// precisely so the session cookie lands on the tenant's own domain, so a token for workspace
+// A presented on workspace B's host must be REFUSED (403) rather than quietly creating A's
+// session on B's domain. Trusting `wid` alone would do exactly that.
+func (h *Handler) ssoWorkspace(ctx context.Context, r *http.Request, claims ssoClaims) (*Workspace, error) {
 	if !h.multiTenant {
 		return DefaultWorkspace, nil
 	}
-	wid := strings.TrimSpace(claims.WID)
-	if wid == "" {
-		return nil, errSSOWIDRequired
-	}
-	if !db.ValidWorkspaceID(wid) {
-		return nil, errSSOUnknownWID
-	}
-	ws, err := h.workspaceByID(ctx, wid)
-	switch {
-	case errors.Is(err, errNoWorkspace):
-		// The id is well-formed and names nothing. The caller's mistake, not a fault.
-		return nil, errSSOUnknownWID
-	case err != nil:
+	ws, err := h.workspaceByHost(ctx, r.Host)
+	if err != nil {
 		return nil, err
 	}
 	if ws.Suspended() {
@@ -225,6 +236,13 @@ func (h *Handler) ssoWorkspace(ctx context.Context, claims ssoClaims) (*Workspac
 	if ws.PublicHost == "" {
 		return nil, errSSONoPublicHost
 	}
+	wid := strings.TrimSpace(claims.WID)
+	if wid == "" {
+		return nil, errSSOWIDRequired
+	}
+	if wid != ws.ID {
+		return nil, fmt.Errorf("%w: token names %s, host %s is %s", errWorkspaceMismatch, wid, ws.PublicHost, ws.ID)
+	}
 	return ws, nil
 }
 
diff --git a/internal/handler/sso_tenancy_test.go b/internal/handler/sso_tenancy_test.go
index 41e09d8..9f0acba 100644
--- a/internal/handler/sso_tenancy_test.go
+++ b/internal/handler/sso_tenancy_test.go
@@ -4,6 +4,7 @@ import (
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 
 	"github.com/calnode/calnode/internal/db"
@@ -11,24 +12,25 @@ import (
 	"github.com/calnode/calnode/internal/handler"
 )
 
-// The SSO hand-off in multi-tenant mode (D11, and rule 1 of the platform-hooks merge).
+// The SSO hand-off in multi-tenant mode (D11).
 //
-// /v1/auth/sso is a Platform route: no tenant Host to resolve from and no credential
-// yet, because the TOKEN is the credential. So the workspace comes from the `wid` claim,
-// and every row the endpoint writes has to NAME it — the platform handle bypasses the
-// policies and binds '', so neither RLS nor the column default will do it for us.
+// ⛔ The endpoint is reached at https://<public_host>/v1/auth/sso, because the cookie has to
+// land on the tenant's own domain — that is the entire reason the hand-off exists. So the
+// workspace is resolved from the request HOST and the token's `wid` is CHECKED against it: a
+// token for workspace A presented on B's host is refused, rather than quietly creating A's
+// session on B's domain.
 //
-// These need the real pair: a single handle cannot tell two workspaces apart, and a
-// superuser handle would satisfy every assertion whether the scoping existed or not.
+// It stays Platform-wrapped rather than Scoped because the handler needs the platform handle
+// to write the user and session with an explicit workspace_id — the tenant does not exist as
+// far as a bound handle is concerned until those rows do.
 
 const (
 	ssoHostA = "book.acme.example"
 	ssoHostB = "book.globex.example"
 )
 
-// newSSOPairHandler returns a multi-tenant handler over a real OpenPair, plus the
-// platform handle the assertions read through, plus the platform-wrapped route exactly
-// as server.New registers it.
+// newSSOPairHandler returns a multi-tenant handler over a real OpenPair, the platform handle
+// the assertions read through, and the platform-wrapped route as server.New registers it.
 func newSSOPairHandler(t *testing.T) (*db.DB, http.HandlerFunc) {
 	t.Helper()
 	app, platform := dbtest.RequireTenantPair(t)
@@ -53,9 +55,8 @@ func seedSSOWorkspace(t *testing.T, platform *db.DB, id, host, status string) {
 	}
 }
 
-// ssoTenantClaims is a valid claim set for one workspace: wid names it and aud is its
-// own public host, which is where the token is spent (the identity host cannot set a
-// cookie for that domain, which is the entire reason this endpoint exists).
+// ssoTenantClaims is a valid claim set for one workspace: wid names it and aud is its own
+// public host, which is where the token is spent.
 func ssoTenantClaims(wid, host string) map[string]any {
 	c := ssoClaimSet()
 	c["wid"] = wid
@@ -63,21 +64,24 @@ func ssoTenantClaims(wid, host string) map[string]any {
 	return c
 }
 
-func doTenantSSO(route http.HandlerFunc, claims map[string]any, t *testing.T) *httptest.ResponseRecorder {
+// doTenantSSO spends a token AT a host, which is the part that matters here.
+func doTenantSSO(t *testing.T, route http.HandlerFunc, host string, claims map[string]any) *httptest.ResponseRecorder {
 	t.Helper()
+	req := httptest.NewRequest(http.MethodGet,
+		"/v1/auth/sso?token="+ssoToken(t, ssoSecret, claims), nil)
+	req.Host = host
 	rec := httptest.NewRecorder()
-	route(rec, httptest.NewRequest(http.MethodGet,
-		"/v1/auth/sso?token="+ssoToken(t, ssoSecret, claims), nil))
+	route(rec, req)
 	return rec
 }
 
 // The load-bearing case. ONE email is handed to BOTH workspaces, which since D9 is
-// legitimate — the unique on users is (workspace_id, email). Two users must exist, one
-// per workspace, and each session must belong to its own.
+// legitimate — the unique on users is (workspace_id, email). Two users must exist, one per
+// workspace, and each session must belong to its own.
 //
-// Unscoped, the second hand-off finds the FIRST workspace's user by email and mints a
-// session for it: workspace B's visitor signs in as workspace A's person. The sessions
-// row would even satisfy its foreign key, because sessions.user_id is global.
+// Unscoped, the second hand-off finds the FIRST workspace's user by email and mints a session
+// for it: workspace B's visitor signs in as workspace A's person. The sessions row would even
+// satisfy its foreign key, because sessions.user_id is global.
 func TestSSOHandoff_multiTenantLandsInTheTokensWorkspace(t *testing.T) {
 	platform, route := newSSOPairHandler(t)
 
@@ -87,11 +91,11 @@ func TestSSOHandoff_multiTenantLandsInTheTokensWorkspace(t *testing.T) {
 	claimsB := ssoTenantClaims("globex", ssoHostB)
 	claimsB["sub"] = shared
 
-	recA := doTenantSSO(route, claimsA, t)
+	recA := doTenantSSO(t, route, ssoHostA, claimsA)
 	if recA.Code != http.StatusFound {
 		t.Fatalf("A: status = %d; want 302 — %s", recA.Code, recA.Body.String())
 	}
-	recB := doTenantSSO(route, claimsB, t)
+	recB := doTenantSSO(t, route, ssoHostB, claimsB)
 	if recB.Code != http.StatusFound {
 		t.Fatalf("B: status = %d; want 302 — %s", recB.Code, recB.Body.String())
 	}
@@ -103,32 +107,52 @@ func TestSSOHandoff_multiTenantLandsInTheTokensWorkspace(t *testing.T) {
 			"the first workspace's person", userA)
 	}
 
-	// Each session names its own workspace and its own workspace's user. The
-	// workspace_id matters beyond bookkeeping: every later request for that user runs
-	// on a BOUND handle, which could neither read nor delete a session filed elsewhere.
 	assertSession(t, platform, sessionCookieValue(t, recA), "acme", userA)
 	assertSession(t, platform, sessionCookieValue(t, recB), "globex", userB)
+}
+
+// ⛔ A token for A presented on B's host: 403, and nothing created. This is the case
+// host-based resolution exists for — with the workspace taken from `wid` alone, both the
+// audience and the wid would check out and A's session would be created on B's domain.
+func TestSSOHandoff_tokenForAnotherWorkspaceIsRefusedOnThisHost(t *testing.T) {
+	platform, route := newSSOPairHandler(t)
 
-	var users int
-	if err := platform.QueryRow(`SELECT COUNT(*) FROM users WHERE email = ?`, shared).Scan(&users); err != nil {
-		t.Fatalf("count users: %v", err)
+	rec := doTenantSSO(t, route, ssoHostB, ssoTenantClaims("acme", ssoHostA))
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d; want 403 — %s", rec.Code, rec.Body.String())
 	}
-	if users != 2 {
-		t.Errorf("users with that address = %d; want 2, one per workspace", users)
+	if got := ssoErrorBody(t, rec); got != "workspace mismatch" {
+		t.Errorf("error = %q; want \"workspace mismatch\" (D10's body)", got)
+	}
+
+	for _, table := range []string{"users", "sessions", "sso_nonces"} {
+		var n int
+		q := `SELECT COUNT(*) FROM ` + table
+		if table != "sso_nonces" {
+			q += ` WHERE workspace_id IN ('acme', 'globex')`
+		}
+		if err := platform.QueryRow(q).Scan(&n); err != nil {
+			t.Fatalf("count %s: %v", table, err)
+		}
+		if n != 0 {
+			t.Errorf("%s has %d rows; a refused hand-off must create nothing — not even a "+
+				"spent nonce, since the token was never usable here", table, n)
+		}
 	}
 }
 
 func TestSSOHandoff_multiTenantRefusesABadWID(t *testing.T) {
 	cases := map[string]struct {
 		mutate func(map[string]any)
+		status int
 		want   string
 	}{
-		"missing": {func(c map[string]any) { delete(c, "wid") }, "wid is required"},
-		"empty":   {func(c map[string]any) { c["wid"] = "" }, "wid is required"},
-		"unknown": {func(c map[string]any) { c["wid"] = "nosuchtenant" }, "wid does not name a workspace"},
-		// Refused before it can reach the database as a bound handle that matches
-		// nothing, which is the silent version of the same answer.
-		"not an id": {func(c map[string]any) { c["wid"] = "Not An Id!" }, "wid does not name a workspace"},
+		"missing": {func(c map[string]any) { delete(c, "wid") }, http.StatusUnauthorized, "wid is required"},
+		"empty":   {func(c map[string]any) { c["wid"] = "" }, http.StatusUnauthorized, "wid is required"},
+		// A wid that names another workspace, or nothing at all, is the same answer: it does
+		// not match the host this token was spent at.
+		"unknown":   {func(c map[string]any) { c["wid"] = "nosuchtenant" }, http.StatusForbidden, "workspace mismatch"},
+		"not an id": {func(c map[string]any) { c["wid"] = "Not An Id!" }, http.StatusForbidden, "workspace mismatch"},
 	}
 	for name, tc := range cases {
 		t.Run(name, func(t *testing.T) {
@@ -136,9 +160,9 @@ func TestSSOHandoff_multiTenantRefusesABadWID(t *testing.T) {
 			claims := ssoTenantClaims("acme", ssoHostA)
 			tc.mutate(claims)
 
-			rec := doTenantSSO(route, claims, t)
-			if rec.Code != http.StatusUnauthorized {
-				t.Fatalf("status = %d; want 401 — %s", rec.Code, rec.Body.String())
+			rec := doTenantSSO(t, route, ssoHostA, claims)
+			if rec.Code != tc.status {
+				t.Fatalf("status = %d; want %d — %s", rec.Code, tc.status, rec.Body.String())
 			}
 			if got := ssoErrorBody(t, rec); got != tc.want {
 				t.Errorf("error = %q; want %q", got, tc.want)
@@ -154,14 +178,14 @@ func TestSSOHandoff_multiTenantRefusesABadWID(t *testing.T) {
 	}
 }
 
-// In multi-tenant mode the audience is the WORKSPACE's public host, not BASE_URL. A
-// token minted for tenant A must not be spendable on tenant B, and the identity host is
-// not an audience at all — it cannot set the cookie the hand-off exists to set.
+// The audience is the host the token is spent at, with no trailing slash. A token whose aud
+// names the identity host is refused even on the right tenant host: the identity host cannot
+// set the cookie this hand-off exists to set.
 func TestSSOHandoff_multiTenantAudienceIsThePublicHost(t *testing.T) {
 	cases := map[string]string{
 		"the identity host": ssoBaseURL,
-		"another tenant":    "https://" + ssoHostB,
 		"a bare hostname":   ssoHostA,
+		"a trailing slash":  "https://" + ssoHostA + "/",
 	}
 	for name, aud := range cases {
 		t.Run(name, func(t *testing.T) {
@@ -169,7 +193,7 @@ func TestSSOHandoff_multiTenantAudienceIsThePublicHost(t *testing.T) {
 			claims := ssoTenantClaims("acme", ssoHostA)
 			claims["aud"] = aud
 
-			rec := doTenantSSO(route, claims, t)
+			rec := doTenantSSO(t, route, ssoHostA, claims)
 			if rec.Code != http.StatusUnauthorized {
 				t.Fatalf("status = %d; want 401 — %s", rec.Code, rec.Body.String())
 			}
@@ -180,6 +204,41 @@ func TestSSOHandoff_multiTenantAudienceIsThePublicHost(t *testing.T) {
 	}
 }
 
+// A replayed token loses on the nonce table's primary key, before a second session exists.
+func TestSSOHandoff_multiTenantReplayIsRefused(t *testing.T) {
+	platform, route := newSSOPairHandler(t)
+	claims := ssoTenantClaims("acme", ssoHostA)
+
+	if rec := doTenantSSO(t, route, ssoHostA, claims); rec.Code != http.StatusFound {
+		t.Fatalf("first: %d — %s", rec.Code, rec.Body.String())
+	}
+	rec := doTenantSSO(t, route, ssoHostA, claims)
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("replay: status = %d; want 401 — %s", rec.Code, rec.Body.String())
+	}
+	if got := ssoErrorBody(t, rec); got != "jti has already been used" {
+		t.Errorf("error = %q; want the jti to be named", got)
+	}
+
+	var sessions int
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM sessions WHERE workspace_id = 'acme'`).Scan(&sessions); err != nil {
+		t.Fatalf("count sessions: %v", err)
+	}
+	if sessions != 1 {
+		t.Errorf("sessions = %d; want 1 — a replay must not mint a second", sessions)
+	}
+}
+
+// An unrecognised host is a 404 before anything else happens: no tenant, nowhere to land.
+func TestSSOHandoff_unknownHostIs404(t *testing.T) {
+	_, route := newSSOPairHandler(t)
+	rec := doTenantSSO(t, route, "nobody.example", ssoTenantClaims("acme", ssoHostA))
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("status = %d; want 404 on a host that names no workspace", rec.Code)
+	}
+}
+
 // A suspended workspace answers 503 with Retry-After on its own surfaces (D12), and a
 // hand-off into one is the same answer: it lands in /admin/, which is suspended too.
 func TestSSOHandoff_multiTenantRefusesASuspendedWorkspace(t *testing.T) {
@@ -190,7 +249,8 @@ func TestSSOHandoff_multiTenantRefusesASuspendedWorkspace(t *testing.T) {
 	h.SetSSOSecret(ssoSecret)
 	seedSSOWorkspace(t, platform, "acme", ssoHostA, "suspended")
 
-	rec := doTenantSSO(h.Platform((*handler.Handler).SSOHandoff), ssoTenantClaims("acme", ssoHostA), t)
+	rec := doTenantSSO(t, h.Platform((*handler.Handler).SSOHandoff), ssoHostA,
+		ssoTenantClaims("acme", ssoHostA))
 	if rec.Code != http.StatusServiceUnavailable {
 		t.Fatalf("status = %d; want 503 — %s", rec.Code, rec.Body.String())
 	}
@@ -199,6 +259,131 @@ func TestSSOHandoff_multiTenantRefusesASuspendedWorkspace(t *testing.T) {
 	}
 }
 
+// The mint half: the OAuth callback hands off to the workspace's public host instead of
+// setting a cookie on the identity host, and the token it mints is one this endpoint accepts.
+//
+// The two halves are exercised together on purpose — a mint that produced a token the
+// verifier rejects would pass any test that only looked at the redirect.
+func TestOAuthHandoff_callbackMintsATokenTheSSOEndpointAccepts(t *testing.T) {
+	app, platform := dbtest.RequireTenantPair(t)
+	h := handler.New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL(ssoBaseURL)
+	h.SetSSOSecret(ssoSecret)
+	seedSSOWorkspace(t, platform, "acme", ssoHostA, "active")
+	seedSSOWorkspace(t, platform, "globex", ssoHostB, "active")
+
+	// The person exists in acme. The same address in globex is what makes an unscoped lookup
+	// wrong rather than merely untidy.
+	if _, err := platform.Exec(`
+		INSERT INTO users (id, workspace_id, email, name, iana_timezone, is_admin, is_owner)
+		VALUES ('acme-user', 'acme', 'both@example.test', 'Acme Person', 'UTC', 1, 1),
+		       ('globex-user', 'globex', 'both@example.test', 'Globex Person', 'UTC', 1, 1)`); err != nil {
+		t.Fatalf("seed users: %v", err)
+	}
+
+	target := handler.FinishOAuthLoginForTest(h, "both@example.test", "acme")
+	if target == "" {
+		t.Fatal("the callback set a cookie instead of handing off; multi-tenant must redirect")
+	}
+	if !strings.HasPrefix(target, "https://"+ssoHostA+"/v1/auth/sso?token=") {
+		t.Fatalf("hand-off target = %q; want the workspace's public host and /v1/auth/sso", target)
+	}
+
+	// Spend the minted token at that host, through the real endpoint.
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, target[len("https://"+ssoHostA):], nil)
+	req.Host = ssoHostA
+	h.Platform((*handler.Handler).SSOHandoff)(rec, req)
+
+	if rec.Code != http.StatusFound {
+		t.Fatalf("spending the minted token: status = %d; want 302 — %s", rec.Code, rec.Body.String())
+	}
+	if loc := rec.Header().Get("Location"); loc != "/admin/" {
+		t.Errorf("Location = %q; want /admin/", loc)
+	}
+	assertSession(t, platform, sessionCookieValue(t, rec), "acme", "acme-user")
+
+	// ⛔ And globex's identically-addressed user got no session. Before D11 the callback's
+	// lookup was `WHERE email = ?` on the platform handle, which resolves an arbitrary one of
+	// these two rows.
+	var globexSessions int
+	if err := platform.QueryRow(
+		`SELECT COUNT(*) FROM sessions WHERE workspace_id = 'globex'`).Scan(&globexSessions); err != nil {
+		t.Fatalf("count globex sessions: %v", err)
+	}
+	if globexSessions != 0 {
+		t.Errorf("globex has %d sessions; the login was for acme", globexSessions)
+	}
+}
+
+// A minted token is bound to the workspace that started the login: spending acme's hand-off
+// on globex's host is the same 403 as any other cross-workspace token.
+func TestOAuthHandoff_mintedTokenIsRefusedOnAnotherWorkspacesHost(t *testing.T) {
+	app, platform := dbtest.RequireTenantPair(t)
+	h := handler.New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL(ssoBaseURL)
+	h.SetSSOSecret(ssoSecret)
+	seedSSOWorkspace(t, platform, "acme", ssoHostA, "active")
+	seedSSOWorkspace(t, platform, "globex", ssoHostB, "active")
+	if _, err := platform.Exec(`
+		INSERT INTO users (id, workspace_id, email, name, iana_timezone, is_admin, is_owner)
+		VALUES ('acme-user', 'acme', 'person@example.test', 'Acme Person', 'UTC', 1, 1)`); err != nil {
+		t.Fatalf("seed user: %v", err)
+	}
+
+	target := handler.FinishOAuthLoginForTest(h, "person@example.test", "acme")
+	if target == "" {
+		t.Fatal("no hand-off target")
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, target[len("https://"+ssoHostA):], nil)
+	req.Host = ssoHostB // the wrong tenant's host
+	h.Platform((*handler.Handler).SSOHandoff)(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d; want 403 — %s", rec.Code, rec.Body.String())
+	}
+	var sessions int
+	if err := platform.QueryRow(`SELECT COUNT(*) FROM sessions`).Scan(&sessions); err != nil {
+		t.Fatalf("count sessions: %v", err)
+	}
+	if sessions != 0 {
+		t.Errorf("sessions = %d; want 0", sessions)
+	}
+}
+
+// Without CALNODE_SSO_SHARED_SECRET a multi-tenant OAuth login has nowhere to land, so it
+// refuses rather than setting a cookie on the identity host — which would produce a session
+// the person's own admin UI cannot see.
+func TestOAuthHandoff_refusesWithoutTheSharedSecret(t *testing.T) {
+	app, platform := dbtest.RequireTenantPair(t)
+	h := handler.New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL(ssoBaseURL)
+	// no SetSSOSecret
+	seedSSOWorkspace(t, platform, "acme", ssoHostA, "active")
+	if _, err := platform.Exec(`
+		INSERT INTO users (id, workspace_id, email, name, iana_timezone, is_admin, is_owner)
+		VALUES ('acme-user', 'acme', 'person@example.test', 'Acme Person', 'UTC', 1, 1)`); err != nil {
+		t.Fatalf("seed user: %v", err)
+	}
+
+	target := handler.FinishOAuthLoginForTest(h, "person@example.test", "acme")
+	if !strings.Contains(target, "error=sso") {
+		t.Errorf("redirect = %q; want an error=sso refusal", target)
+	}
+	var sessions int
+	if err := platform.QueryRow(`SELECT COUNT(*) FROM sessions`).Scan(&sessions); err != nil {
+		t.Fatalf("count sessions: %v", err)
+	}
+	if sessions != 0 {
+		t.Errorf("sessions = %d; want 0 — a login that cannot hand off must not half-succeed", sessions)
+	}
+}
+
 func userIDInWorkspace(t *testing.T, platform *db.DB, workspaceID, email string) string {
 	t.Helper()
 	var id string

From c9b80a2d02c73618a1d488b770ebed0a98587160 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 07:11:27 -0400
Subject: [PATCH 45/51] handler: vendor webhooks resolve their own workspace,
 and scoped handles stop riding the platform pool
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

POST /v1/livekit/webhook (+ legacy alias) and POST /v1/stripe/webhook. Both stay Platform-
classified: the caller is a vendor, so there is no tenant Host and no credential of ours.

The workspace comes from OUR row, keyed on an id WE issued
---------------------------------------------------------

internal/handler/vendor_webhook.go. LiveKit resolves in three steps - the egress id on a
recordings row, then the room's recordings row, then the booking the room name encodes
(booking-<id>, the only room name this application creates, which is what a room_finished for a
never-recorded meeting needs). Stripe resolves from bookings.stripe_session_id, falling back to
the metadata booking id and even then taking workspace_id from the ROW.

⛔ No resolver consults a workspace_id in a vendor payload: that would be a tenant selector
supplied by whoever can forge a body. Every read names workspace_id in its own SELECT list.

An event no row owns is 2xx and ignored - a 4xx would make LiveKit and Stripe retry for days,
and no retry can make a row exist that never did.

⚠️ Decision: in multi-tenant mode the RESOLVE precedes the VERIFY
----------------------------------------------------------------

The instruction asked for verify-then-resolve. That is impossible here: both vendors'
credentials live in server_settings, i.e. per workspace (D7), and on a Platform-wrapped route
the handle bypasses the policies - so LoadLiveKitSettingsFromDB's `WHERE id = 1` matches every
tenant's row and returns an arbitrary one. Verifying against a randomly chosen tenant's secret
is not verification, and there is no process-wide credential to use instead, because boot
priming is single-tenant-only (B5 deliverable 4).

So: resolve (one keyed SELECT), verify with THAT workspace's secret, then act. Two properties
make it safe, both load-bearing: nothing is written before the signature verifies, and nothing
is disclosed (empty body either way).

⚠️ Residual: an existence oracle - an unsigned request naming a real egress id gets 403, an
unknown one 200. The ids are opaque and a caller with a valid signature already knows the id it
sent. Closing it means 403 for an unknown row, i.e. the retry storm this design avoids.

Single-tenant keeps the original order exactly: one workspace, one set of credentials, nothing
to resolve.

⛔ THE HOLE THIS EXPOSED: forWorkspace was binding onto the PLATFORM pool
-----------------------------------------------------------------------

Platform() replaces h.db with the platform handle, whose role BYPASSES row-level security.
forWorkspace built its scoped copy with h.db.ForWorkspace(ws.ID) - so the result NAMED a tenant
and was not CONFINED to it. A `WHERE id = 1` read through such a handle matches every
workspace's server_settings row and returns an arbitrary one; a write lands wherever the
statement says. Both silent.

The symptom was oblique: the LiveKit webhook's hand-off to forWorkspace(ws).getLiveKit() read
the DEFAULT workspace's empty settings row instead of the resolved tenant's, so the client was
nil and the handler answered 200 having verified nothing. No error, no log line.

Fixed by holding the application handle on shared (appDB, set once in handler.New) and binding
every scoped copy from that: h.appBase().ForWorkspace(ws.ID). A tenant-scoped handler now always
rides the role the policies constrain, whichever route it came from.

⚠️ Why nothing else caught it: every other Platform-route hand-off either names workspace_id
explicitly on its writes (the platform API, the SSO endpoint - which is why those tests pass
either way) or runs on the worker's path, where the base handler's db IS the application handle.
The vendor webhooks are the first code to depend on a scoped handle's READS being filtered.

Negative control, the bind put back on h.db:

  --- FAIL: TestVendorWebhook_livekitBadSignatureWritesNothing
      status = 200; want 403

200 means it never reached verification, having loaded the wrong tenant's absent credentials.

Gates
-----

  gofmt -l . empty, go vet ./... clean, go build ./... clean
  go test -count=1 ./... rc=0 on SQLite (30/30)
  PostgreSQL: internal/handler rc=0 (321.2s), internal/server rc=0 (9.8s) - including the whole
    B3/B4/B5 tenancy suite, which is what says the appDB change moved nothing else

  --- PASS: TestVendorWebhook_livekitResolvesTheOwningWorkspace      [7 cases]
  --- PASS: TestVendorWebhook_livekitEventWritesOnlyItsOwnWorkspace
  --- PASS: TestVendorWebhook_livekitUnknownRoomIs2xxWithNoWrite
  --- PASS: TestVendorWebhook_livekitBadSignatureWritesNothing
  --- PASS: TestVendorWebhook_stripeResolvesTheOwningWorkspace       [6 cases]
  --- PASS: TestVendorWebhook_stripeUnknownSessionIs2xxWithNoWrite
  --- PASS: TestVendorWebhook_stripeBadSignatureWritesNothing

PROGRESS.md closes B6: D11-D14 all done, the bring-up env table, and the two known follow-ups
(per-tenant DEKs; the D7 reader wiring for the two columns nothing reads yet).
---
 PROGRESS.md                              | 153 +++++++++-
 internal/handler/export_internal_test.go |  34 +++
 internal/handler/handler.go              |   1 +
 internal/handler/livekit_recording.go    |  47 +++-
 internal/handler/shared.go               |  16 ++
 internal/handler/stripe_booking.go       |  39 ++-
 internal/handler/vendor_webhook.go       | 137 +++++++++
 internal/handler/vendor_webhook_test.go  | 340 +++++++++++++++++++++++
 internal/handler/workspace.go            |  15 +-
 9 files changed, 764 insertions(+), 18 deletions(-)
 create mode 100644 internal/handler/vendor_webhook.go
 create mode 100644 internal/handler/vendor_webhook_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 577cd85..6f0d98a 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -2079,7 +2079,148 @@ Only the vendor webhooks: `POST /v1/livekit/webhook` (+ its alias) and `POST /v1
 must resolve their workspace from the room or session row they name, then hand off to
 `forWorkspace`. D12, D13 and D14 are done.
 
-## D11 — the plan this replaced
+## Boundary 6, part four — the vendor webhooks, and a hole they exposed
+
+`POST /v1/livekit/webhook` (+ its legacy alias) and `POST /v1/stripe/webhook`. Both stay
+`Platform`-classified, because the caller is a vendor: no tenant Host (the URL was registered
+once in a dashboard) and no credential of ours (the signature is theirs).
+
+### The workspace comes from OUR row, keyed on an id WE issued
+
+`internal/handler/vendor_webhook.go`. LiveKit resolves in three steps — the egress id on a
+`recordings` row, then the room's `recordings` row, then the booking the room name encodes
+(`booking-<id>`, which is the only room name this application creates, and is what a
+`room_finished` for a never-recorded meeting needs). Stripe resolves from
+`bookings.stripe_session_id`, falling back to the metadata booking id — and even then takes
+`workspace_id` from the ROW, not the payload.
+
+⛔ **No resolver consults a `workspace_id` in a vendor payload.** Such a field would be a
+tenant selector supplied by whoever can forge a body, and every read here names `workspace_id`
+in its own SELECT list instead.
+
+An event no row owns is **2xx and ignored**. A 4xx would make LiveKit and Stripe retry for days,
+and no retry can make a row exist that never did.
+
+### ⚠️ Decision: in multi-tenant mode the RESOLVE precedes the VERIFY
+
+The turn asked for verify-then-resolve. That is impossible here, and the reason is worth
+recording: **both vendors' credentials live in `server_settings`, i.e. per workspace (D7).** On
+a Platform-wrapped route the handle bypasses the policies, so `LoadLiveKitSettingsFromDB`'s
+`WHERE id = 1` matches every tenant's row and returns an arbitrary one — verifying a signature
+against a randomly chosen tenant's secret is not verification. There is no process-wide
+credential to fall back on either, because boot priming is single-tenant-only (B5, deliverable 4).
+
+So: resolve (one keyed SELECT), then verify with **that workspace's** secret, then act. Two
+properties make it safe and both are load-bearing: **nothing is written before the signature
+verifies**, and **nothing is disclosed** (the body is empty either way).
+
+⚠️ The residual is an existence oracle — an unsigned request naming a real egress id gets 403
+while an unknown one gets 200. The ids are opaque (`booking-<uuid>`, LiveKit egress ids) and a
+caller holding a valid signature already knows the id it sent. Closing it would mean 403 for an
+unknown row, i.e. the retry storm this design exists to avoid.
+
+**Single-tenant keeps the original order exactly** (verify, then act): one workspace, one set of
+credentials, nothing to resolve, and no reason to change what a working deployment does.
+
+### ⛔ THE HOLE: `forWorkspace` was binding onto the PLATFORM pool
+
+Found by the vendor-webhook test, and it reached further than this group.
+
+`Platform()` replaces `h.db` with the platform handle, whose role **BYPASSES** row-level
+security. `forWorkspace` then built its scoped copy with `h.db.ForWorkspace(ws.ID)` — so the
+result **named** a tenant and was not **confined** to it. A `WHERE id = 1` read through such a
+handle matches every workspace's `server_settings` row and returns an arbitrary one; a write
+lands wherever the statement says. Both silent.
+
+The symptom was oblique: the hand-off from the LiveKit webhook to
+`forWorkspace(ws).getLiveKit()` read the **default** workspace's empty settings row instead of
+the resolved tenant's, so the client was nil and the handler answered 200 having verified
+nothing. No error, no log line.
+
+Fixed by holding the application handle on `shared` (`appDB`, set once in `handler.New`) and
+binding every scoped copy from **that**: `h.appBase().ForWorkspace(ws.ID)`. A tenant-scoped
+handler now always rides the role the policies constrain, whichever route it came from.
+
+⚠️ **Why nothing else caught it:** every other Platform-route hand-off either names
+`workspace_id` explicitly on its writes (the platform API, the SSO endpoint — which is why
+those tests pass either way) or runs on the worker's path, where the base handler's `db` IS the
+application handle. The vendor webhooks are the first code to depend on a scoped handle's
+**reads** being filtered.
+
+Negative control, the bind put back on `h.db`:
+
+```
+--- FAIL: TestVendorWebhook_livekitBadSignatureWritesNothing
+    status = 200; want 403
+```
+
+200 means it never reached verification, because it loaded the wrong tenant's (absent)
+credentials.
+
+### Gates
+
+`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
+`go test -count=1 ./...` **rc=0 on SQLite (30/30)**. PostgreSQL: `internal/handler` **rc=0**
+(321.2s), `internal/server` **rc=0** — including the whole B3/B4/B5 tenancy suite, which is
+what says the `appDB` change did not move anything else.
+
+```
+--- PASS: TestVendorWebhook_livekitResolvesTheOwningWorkspace      [7 cases]
+--- PASS: TestVendorWebhook_livekitEventWritesOnlyItsOwnWorkspace
+--- PASS: TestVendorWebhook_livekitUnknownRoomIs2xxWithNoWrite
+--- PASS: TestVendorWebhook_livekitBadSignatureWritesNothing
+--- PASS: TestVendorWebhook_stripeResolvesTheOwningWorkspace       [6 cases]
+--- PASS: TestVendorWebhook_stripeUnknownSessionIs2xxWithNoWrite
+--- PASS: TestVendorWebhook_stripeBadSignatureWritesNothing
+```
+
+---
+
+# Boundary 6 — done. D11, D12, D13, D14 all closed
+
+| decision | state |
+|---|---|
+| **D11** hosts, per-workspace `publicURL`, the OAuth hand-off through SSO, the calendar callback's workspace | **done** (B3 for the hosts, B6 part three for both hand-off halves) |
+| **D12** platform API: create, get, patch, delete, export, import, attendee erasure; suspended ⇒ 503 | **done** (B6 parts one and two; 503 was already in `Scoped`) |
+| **D13** demo mode and multi-tenant mutually exclusive | **done** in B1 (`config.Validate`) |
+| **D14** rate limits keyed `(workspace, client IP)` via `TRUSTED_PROXY_CIDRS` | **done** with the platform-hooks merge |
+
+## What a bring-up needs from this side
+
+Environment, on every instance:
+
+| key | value |
+|---|---|
+| `MULTI_TENANT` | any non-empty value turns the mode on. ⛔ Requires a `postgres://` DSN and refuses `DEMO_MODE` (D13) |
+| `DATABASE_URL` | the **application** role: `NOBYPASSRLS`, owns no table in the schema. `VerifyRoles` refuses the boot otherwise |
+| `DATABASE_ADMIN_URL` | the **platform** role: owner, `BYPASSRLS`. ⛔ Must not equal `DATABASE_URL` — one role means every policy is inert against it, and everything appears to work |
+| `CALNODE_PLATFORM_TOKEN` | bearer for `/v1/platform/*`. Unset ⇒ those routes 404 |
+| `CALNODE_SSO_SHARED_SECRET` | HMAC key for `/v1/auth/sso`. ⛔ **Required** in multi-tenant mode if Google or Microsoft login is configured: the callbacks hand off through it, and unset means every social login ends at `error=sso` |
+| `TRUSTED_PROXY_CIDRS` | the networks whose forwarded headers are believed. ⚠️ Unset behind a proxy makes every tenant one rate-limit bucket (D14's IP half) |
+| `CALNODE_ENCRYPTION_KEY` | as before, and ⛔ it must travel with any workspace moved between instances — import refuses a document whose `dek_fingerprint` differs |
+| `BASE_URL` | the identity host: OAuth callbacks, `/oauth/*`, `/mcp`, `/v1/platform/*`, `/healthz`, `/readyz`, `/version`, `/metrics` |
+| `PUBLIC_BASE_URL` | **ignored** in multi-tenant mode; each workspace's `public_host` replaces it |
+
+Per workspace, through `POST /v1/platform/workspaces`: `public_host` (its own hostname, DNS
+pointed at the instance) and the `defaults` block. The response's `api_key` and
+`webhook_secret` are shown once.
+
+At boot, in this order: migrate on the platform handle → `EnableRLS` → suspend the `default`
+workspace → `VerifyRoles` on the application handle. The first, second and fourth are fatal on
+failure; the third is logged.
+
+## The two known follow-ups
+
+1. ⛔ **Per-tenant DEKs.** `crypto_keystore` is exempt and holds one wrapped DEK per process
+   (D3), so every tenant's secrets are encrypted under one key: an operator who can read the
+   database can decrypt every workspace, and a workspace cannot be moved between instances
+   without moving the key. Import's `dek_fingerprint` check makes the coupling loud rather than
+   silent, which is as far as this packet goes. Making it per tenant changes D3, the schema
+   (`crypto_keystore` gains `workspace_id`), and the export format.
+2. ⚠️ **The D7 reader wiring for `embed_allowed_origins` and `stt_base_url`.** Both columns are
+   written by the platform API and read by nothing, so a multi-tenant instance still shares one
+   embed allowlist and one STT host across tenants. Details and the two specifics are in the
+   open item above.
 
 ⚠️ This file carried a plan for the SSO mint half between the merge and part three above.
 It is now BUILT, and part three is the record; the plan is deleted rather than annotated,
@@ -2087,3 +2228,13 @@ because a plan left beside its implementation is the next reader's wrong answer.
 three points survived contact unchanged (the callback to change, and the `<nonce>|<wid>`
 state cookie). The third did not: the plan had the SSO endpoint resolving its workspace from
 `wid`, and doing that on a public host is what part three had to fix.
+
+---
+
+## The D11 plan this file used to carry
+
+⚠️ Deleted rather than annotated once it was built: a plan left beside its implementation is the
+next reader's wrong answer. Two of its three points survived contact unchanged (the callback to
+change, and the `<nonce>|<wid>` state cookie). The third did not — it had the SSO endpoint
+resolving its workspace from `wid`, and doing that on a public host is exactly what part three
+had to fix.
diff --git a/internal/handler/export_internal_test.go b/internal/handler/export_internal_test.go
index d315c3d..58ded96 100644
--- a/internal/handler/export_internal_test.go
+++ b/internal/handler/export_internal_test.go
@@ -38,3 +38,37 @@ func FinishOAuthLoginForTest(h *Handler, email, workspaceID string) string {
 	})(rec, req)
 	return rec.Header().Get("Location")
 }
+
+// LiveKitEventWorkspaceForTest and StripeEventWorkspaceForTest expose the vendor-webhook
+// resolvers, which is where the tenancy decision is actually made.
+//
+// ⛔ They are bridged rather than tested through the HTTP handler because verification needs a
+// real vendor secret: an end-to-end test can only ever observe the 403, which says nothing
+// about WHICH workspace the event resolved to. Both run through Platform, because that is the
+// handle the route gives them — on the bare handler the reads would use the unbound application
+// handle and resolve nothing.
+func LiveKitEventWorkspaceForTest(h *Handler, egressID, room string) (string, bool) {
+	var id string
+	var found bool
+	h.Platform(func(p *Handler, _ http.ResponseWriter, r *http.Request) {
+		scoped, ok := p.livekitEventWorkspace(r.Context(), egressID, room)
+		found = ok
+		if ok {
+			id = scoped.Workspace().ID
+		}
+	})(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/v1/livekit/webhook", nil))
+	return id, found
+}
+
+func StripeEventWorkspaceForTest(h *Handler, sessionID, metadataBookingID string) (string, bool) {
+	var id string
+	var found bool
+	h.Platform(func(p *Handler, _ http.ResponseWriter, r *http.Request) {
+		scoped, ok := p.stripeEventWorkspace(r.Context(), sessionID, metadataBookingID)
+		found = ok
+		if ok {
+			id = scoped.Workspace().ID
+		}
+	})(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/v1/stripe/webhook", nil))
+	return id, found
+}
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index 5d1c6b7..89f3b70 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -186,6 +186,7 @@ func New(database *db.DB, logger *slog.Logger) *Handler {
 			zoomCache:    newTenantCache[*zoom.Client](),
 			stripeCache:  newTenantCache[*stripe.Client](),
 			livekitCache: newTenantCache[*livekit.Client](),
+			appDB:        database,
 		},
 		db:         database,
 		ws:         DefaultWorkspace,
diff --git a/internal/handler/livekit_recording.go b/internal/handler/livekit_recording.go
index 21c1535..726bab0 100644
--- a/internal/handler/livekit_recording.go
+++ b/internal/handler/livekit_recording.go
@@ -545,16 +545,7 @@ var timeNow = func() time.Time { return time.Now() }
 // egress) — and 200-ACKs everything else (room_started, participant_joined/left, track_*, …)
 // without acting on them. Lifecycle events (attendance, duration, etc.) are not yet wired up.
 func (h *Handler) LiveKitWebhook(w http.ResponseWriter, r *http.Request) {
-	lk := h.getLiveKit()
-	if lk == nil {
-		w.WriteHeader(http.StatusOK)
-		return
-	}
 	body, _ := io.ReadAll(io.LimitReader(r.Body, 1<<20))
-	if err := lk.VerifyWebhook(r.Header.Get("Authorization"), body); err != nil {
-		h.writeError(w, http.StatusForbidden, "invalid webhook signature")
-		return
-	}
 	var ev struct {
 		Event string `json:"event"`
 		Room  struct {
@@ -571,6 +562,44 @@ func (h *Handler) LiveKitWebhook(w http.ResponseWriter, r *http.Request) {
 		} `json:"egressInfo"`
 	}
 	_ = json.Unmarshal(body, &ev)
+
+	// ⛔ Resolve the tenant, then verify with ITS credentials, then act — and in
+	// single-tenant mode verify first, exactly as before. The order differs by mode because
+	// the LiveKit API secret lives in server_settings, i.e. per workspace: on this
+	// Platform-wrapped route the handle bypasses the policies, so loading "the" settings row
+	// would hand back an arbitrary tenant's secret and verifying against that is not
+	// verification. See internal/handler/vendor_webhook.go for the full argument, including
+	// the two properties that make an unverified resolve safe (no write, no disclosure).
+	room := ev.Room.Name
+	if room == "" {
+		room = ev.EgressInfo.RoomName
+	}
+	scoped := h
+	if h.multiTenant {
+		resolved, ok := h.livekitEventWorkspace(r.Context(), ev.EgressInfo.EgressID, room)
+		if !ok {
+			// No row owns this event: a stale egress from a deleted workspace, or a room
+			// this instance never created. 200, because a retry cannot make it ours and a
+			// 4xx would make LiveKit retry it forever.
+			h.logger.InfoContext(r.Context(), "livekit: event for no known workspace",
+				"event", ev.Event, "room", room, "egress_id", ev.EgressInfo.EgressID)
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		scoped = resolved
+	}
+	lk := scoped.getLiveKit()
+	if lk == nil {
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+	if err := lk.VerifyWebhook(r.Header.Get("Authorization"), body); err != nil {
+		h.writeError(w, http.StatusForbidden, "invalid webhook signature")
+		return
+	}
+	// From here every read and write is the workspace's own.
+	h = scoped
+
 	// Self-diagnose a future field-name drift: log the raw body if an egress event parsed no id.
 	if ev.EgressInfo.EgressID == "" && strings.HasPrefix(ev.Event, "egress_") {
 		raw := string(body)
diff --git a/internal/handler/shared.go b/internal/handler/shared.go
index 5a3b66b..fa69759 100644
--- a/internal/handler/shared.go
+++ b/internal/handler/shared.go
@@ -9,6 +9,7 @@ import (
 	"golang.org/x/oauth2"
 
 	"github.com/calnode/calnode/internal/calendar"
+	"github.com/calnode/calnode/internal/db"
 	"github.com/calnode/calnode/internal/livekit"
 	"github.com/calnode/calnode/internal/llm"
 	"github.com/calnode/calnode/internal/mailer"
@@ -66,6 +67,21 @@ type shared struct {
 	// carries a `wid` claim. The secret identifies the INSTANCE that minted the
 	// token; the workspace is inside the payload, which is what lets one identity
 	// host hand a session to any of its tenants' public hosts (D11).
+	// appDB is the APPLICATION handle as server.New built it: unbound, and belonging to the
+	// role the row-level-security policies constrain.
+	//
+	// ⛔ forWorkspace binds from THIS, never from h.db, and the difference is the whole
+	// isolation guarantee on a Platform route. Platform() replaces h.db with the platform
+	// handle, whose role BYPASSES RLS — so a handle derived from it with ForWorkspace binds
+	// app.workspace_id and is then not FILTERED by it. A `WHERE id = 1` read through such a
+	// handle matches every workspace's row and returns an arbitrary one; a write lands
+	// wherever the statement says. Both are silent.
+	//
+	// Found by a vendor-webhook test: the hand-off from a Platform route to
+	// forWorkspace(ws).getLiveKit() read the DEFAULT workspace's empty settings row instead of
+	// the resolved tenant's, so the handler answered 200 and verified nothing.
+	appDB *db.DB
+
 	// platformToken authorises the platform API (D12). Like the two below it is one
 	// process-wide env-var secret, and it is what makes an instance a control plane
 	// rather than just a tenant: with it unset every /v1/platform/* route 404s.
diff --git a/internal/handler/stripe_booking.go b/internal/handler/stripe_booking.go
index 06292f7..184569b 100644
--- a/internal/handler/stripe_booking.go
+++ b/internal/handler/stripe_booking.go
@@ -45,16 +45,38 @@ func (h *Handler) startBookingCheckout(ctx context.Context, sc *stripe.Client, b
 // StripeWebhook handles POST /v1/stripe/webhook — Stripe's payment notifications. Public, but
 // authenticated by the signing secret (no session cookie, so CSRF middleware doesn't apply).
 func (h *Handler) StripeWebhook(w http.ResponseWriter, r *http.Request) {
-	sc := h.getStripe()
-	if sc == nil || !sc.WebhookConfigured() {
-		h.writeError(w, http.StatusServiceUnavailable, "payments not configured")
-		return
-	}
 	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
 	if err != nil {
 		h.writeError(w, http.StatusBadRequest, "could not read body")
 		return
 	}
+
+	// ⛔ Resolve the tenant from the booking the session belongs to, then verify with THAT
+	// workspace's signing secret. The secret is in server_settings, i.e. per workspace, and
+	// this Platform-wrapped route's handle bypasses the policies — so "the" settings row is
+	// an arbitrary tenant's, and a signature checked against it proves nothing. Single-tenant
+	// keeps the original order (verify, then act): one workspace, one secret, nothing to
+	// resolve. The argument in full, including why an unverified resolve is safe here, is in
+	// internal/handler/vendor_webhook.go.
+	scoped := h
+	if h.multiTenant {
+		sessionID, metaBooking := peekStripeIDs(body)
+		resolved, ok := h.stripeEventWorkspace(r.Context(), sessionID, metaBooking)
+		if !ok {
+			// No booking of ours owns this session. 200, because Stripe retries a 4xx for
+			// days and no retry can make the row exist.
+			h.logger.InfoContext(r.Context(), "stripe webhook: event for no known workspace",
+				"session_id", sessionID, "metadata_booking_id", metaBooking)
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		scoped = resolved
+	}
+	sc := scoped.getStripe()
+	if sc == nil || !sc.WebhookConfigured() {
+		h.writeError(w, http.StatusServiceUnavailable, "payments not configured")
+		return
+	}
 	ev, err := sc.VerifyWebhook(body, r.Header.Get("Stripe-Signature"), time.Now())
 	if err != nil {
 		// Bad signature → 400 so Stripe surfaces the failure (and a forged call is rejected).
@@ -63,6 +85,9 @@ func (h *Handler) StripeWebhook(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// Every write below is the resolved workspace's. ⚠️ These two calls deliberately use
+	// context.Background(): they outlive the request, and the scoped handler is safe to carry
+	// into them because a workspace handle pins no connection (D5).
 	switch ev.Type {
 	case "checkout.session.completed":
 		sess, perr := ev.Session()
@@ -71,13 +96,13 @@ func (h *Handler) StripeWebhook(w http.ResponseWriter, r *http.Request) {
 		}
 		if sess.PaymentStatus == "paid" {
 			if id := sess.Metadata["booking_id"]; id != "" {
-				h.confirmPaidBooking(context.Background(), id, sess.PaymentIntent, int(sess.AmountTotal), sess.Currency)
+				scoped.confirmPaidBooking(context.Background(), id, sess.PaymentIntent, int(sess.AmountTotal), sess.Currency)
 			}
 		}
 	case "checkout.session.expired":
 		if sess, perr := ev.Session(); perr == nil {
 			if id := sess.Metadata["booking_id"]; id != "" {
-				h.releaseUnpaidHold(context.Background(), id)
+				scoped.releaseUnpaidHold(context.Background(), id)
 			}
 		}
 	}
diff --git a/internal/handler/vendor_webhook.go b/internal/handler/vendor_webhook.go
new file mode 100644
index 0000000..ae0059b
--- /dev/null
+++ b/internal/handler/vendor_webhook.go
@@ -0,0 +1,137 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+)
+
+// Vendor webhooks and the workspace they belong to (B6).
+//
+// LiveKit and Stripe call us, not a tenant. There is no tenant Host (the URL was registered
+// once, in the vendor's dashboard) and no credential of ours (the signature is the vendor's),
+// so both routes are Platform-classified and must resolve their workspace from the ROW the
+// event names.
+//
+// ⛔ THE WORKSPACE COMES FROM OUR OWN ROW, NEVER FROM THE PAYLOAD. Every resolver here names
+// workspace_id in its SELECT list and keys the read on an id we issued — an egress id, a room
+// name, a checkout session id. A `workspace_id` field in a vendor payload would be a tenant
+// selector supplied by whoever can forge a payload, and the whole point of these functions is
+// that no such field is consulted.
+//
+// ⚠️ AND THE ORDER OF VERIFY-VS-RESOLVE DIFFERS BY MODE, WHICH IS NOT A STYLE CHOICE.
+// Both vendors' credentials live in server_settings, i.e. PER WORKSPACE (D7). On a
+// Platform-wrapped route the handle is the platform handle, which bypasses the policies — so
+// LoadLiveKitSettingsFromDB there reads `WHERE id = 1` across every tenant and returns an
+// ARBITRARY workspace's API secret. Verifying a signature against a randomly chosen tenant's
+// key is not verification, and there is no process-wide credential to use instead, because
+// boot priming is single-tenant-only (B5, deliverable 4).
+//
+// So in multi-tenant mode the resolve happens FIRST and the signature is then checked with
+// that workspace's own credentials. Two properties make that safe, and both are load-bearing:
+//
+//   - Nothing is WRITTEN before the signature verifies. The resolve is one keyed SELECT.
+//   - Nothing is DISCLOSED. The response body is empty either way.
+//
+// ⚠️ The residual is an existence oracle: an unsigned request naming a real egress id gets 403
+// (bad signature) while one naming an unknown id gets 200. The ids are opaque and unguessable
+// (`booking-<uuid>` rooms, LiveKit egress ids), and anyone holding a valid signature already
+// knows the id they sent, so the trade is worth stating rather than closing — closing it would
+// mean 403 for an unknown row, and a vendor retrying that forever is the failure this design
+// exists to avoid.
+//
+// In single-tenant mode the old order is kept exactly: verify, then act. There is one workspace
+// and one set of credentials, so there is nothing to resolve and no reason to change what a
+// working deployment does.
+
+// livekitEventWorkspace resolves the workspace of a LiveKit event from the recording or booking
+// the event names. It reports false when no row owns it, which the caller answers 2xx-and-ignore.
+//
+// Three keys, in order of how specific they are:
+//
+//  1. the egress id, which is on a recordings row we wrote when the egress started;
+//  2. the room name, for a room that has any recording row at all;
+//  3. the booking the room name encodes (`booking-<id>`), for a room event on a meeting that
+//     has never been recorded — `room_finished` arrives for those too.
+func (h *Handler) livekitEventWorkspace(ctx context.Context, egressID, room string) (*Handler, bool) {
+	if !h.multiTenant {
+		return h, true
+	}
+	var wsID string
+	if egressID != "" {
+		if err := h.platformDB().QueryRowContext(ctx,
+			`SELECT workspace_id FROM recordings WHERE egress_id = ?`, egressID).Scan(&wsID); err == nil && wsID != "" {
+			return h.workspaceForJob(wsID), true
+		}
+	}
+	if room != "" {
+		if err := h.platformDB().QueryRowContext(ctx,
+			`SELECT workspace_id FROM recordings WHERE room = ? ORDER BY created_at DESC LIMIT 1`, room).
+			Scan(&wsID); err == nil && wsID != "" {
+			return h.workspaceForJob(wsID), true
+		}
+		// A room with no recording. Booking rooms are named booking-<booking id>, which is
+		// the only room name this application creates, so the booking resolves the tenant.
+		if id := strings.TrimPrefix(room, "booking-"); id != room && id != "" {
+			if err := h.platformDB().QueryRowContext(ctx,
+				`SELECT workspace_id FROM bookings WHERE id = ?`, id).Scan(&wsID); err == nil && wsID != "" {
+				return h.workspaceForJob(wsID), true
+			}
+		}
+	}
+	return nil, false
+}
+
+// stripeEventWorkspace resolves the workspace of a Stripe event from the booking the checkout
+// session belongs to. It reports false when no row owns it.
+//
+// The session id is preferred over the payload's metadata: `bookings.stripe_session_id` is a
+// column we wrote when we created the session, whereas metadata is a field that travels in the
+// event. The metadata booking id is the fallback for a session created before that column was
+// populated, and even then the workspace comes from the ROW rather than the payload.
+func (h *Handler) stripeEventWorkspace(ctx context.Context, sessionID, metadataBookingID string) (*Handler, bool) {
+	if !h.multiTenant {
+		return h, true
+	}
+	var wsID string
+	if sessionID != "" {
+		if err := h.platformDB().QueryRowContext(ctx,
+			`SELECT workspace_id FROM bookings WHERE stripe_session_id = ?`, sessionID).Scan(&wsID); err == nil && wsID != "" {
+			return h.workspaceForJob(wsID), true
+		}
+	}
+	if metadataBookingID != "" {
+		if err := h.platformDB().QueryRowContext(ctx,
+			`SELECT workspace_id FROM bookings WHERE id = ?`, metadataBookingID).Scan(&wsID); err == nil && wsID != "" {
+			return h.workspaceForJob(wsID), true
+		}
+	}
+	return nil, false
+}
+
+// peekVendorIDs pulls the few identifiers a resolver needs out of an as-yet-unverified body.
+//
+// ⚠️ It parses before the signature is checked, which is deliberate and bounded: the body is
+// already length-limited by the caller, the destination is a fixed struct, and the values are
+// used for nothing but a keyed lookup. Nothing here is trusted — the workspace comes from the
+// row those ids find, and if they find none the event is ignored.
+// peekStripeIDs reads the checkout session id and the metadata booking id out of an
+// as-yet-unverified Stripe event body.
+//
+// The event's shape is {"data":{"object":{"id":"cs_...","metadata":{"booking_id":"..."}}}}. Only
+// those two strings are taken, and only to key the lookup that finds the workspace; the
+// authoritative parse is the one VerifyWebhook does after the tenant is known.
+func peekStripeIDs(body []byte) (sessionID, metadataBookingID string) {
+	var peek struct {
+		Data struct {
+			Object struct {
+				ID       string            `json:"id"`
+				Metadata map[string]string `json:"metadata"`
+			} `json:"object"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &peek); err != nil {
+		return "", ""
+	}
+	return peek.Data.Object.ID, peek.Data.Object.Metadata["booking_id"]
+}
diff --git a/internal/handler/vendor_webhook_test.go b/internal/handler/vendor_webhook_test.go
new file mode 100644
index 0000000..bfd3dfb
--- /dev/null
+++ b/internal/handler/vendor_webhook_test.go
@@ -0,0 +1,340 @@
+package handler_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/handler"
+	"github.com/calnode/calnode/internal/secret"
+)
+
+// mustParseKey turns the hex test key into the [32]byte the secret package takes.
+func mustParseKey(t *testing.T, hexKey string) [32]byte {
+	t.Helper()
+	k, err := secret.ParseKey(hexKey)
+	if err != nil {
+		t.Fatalf("parse test encryption key: %v", err)
+	}
+	return k
+}
+
+// Vendor webhooks under tenancy (B6).
+//
+// LiveKit and Stripe call us, not a tenant: no tenant Host, no credential of ours. So both
+// routes are Platform-classified, and the workspace has to come from the ROW the event names.
+// What these tests hold is that an event for B's room or B's checkout session writes into B and
+// leaves A alone — the failure being guarded against is the platform handle, which bypasses
+// every policy, writing one tenant's event into another tenant's tables.
+
+const (
+	vendorHostA = "book.vendor-a.example"
+	vendorHostB = "book.vendor-b.example"
+)
+
+// newVendorWebhookHandler returns a multi-tenant handler over a real pair, the platform handle,
+// and two workspaces each with a booking and per-workspace LiveKit and Stripe credentials.
+//
+// ⚠️ The credentials differ per workspace on purpose: that is what makes "verified with the
+// wrong tenant's secret" a detectable state rather than an invisible one.
+func newVendorWebhookHandler(t *testing.T) (*handler.Handler, *db.DB) {
+	t.Helper()
+	app, platform := dbtest.RequireTenantPair(t)
+
+	h := handler.New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL("https://cal.example.test")
+	h.SetEncKey(platformTestEncKey)
+
+	for _, ws := range []struct{ id, host, lkSecret string }{
+		{"vendor-a", vendorHostA, "secret-for-a"},
+		{"vendor-b", vendorHostB, "secret-for-b"},
+	} {
+		if _, err := platform.Exec(
+			`INSERT INTO workspaces (id, slug, public_host, region, status) VALUES (?, ?, ?, '', 'active')`,
+			ws.id, ws.id, ws.host); err != nil {
+			t.Fatalf("seed workspace %s: %v", ws.id, err)
+		}
+		// ⚠️ The API secret has to be a real AES-GCM ciphertext under the handler's
+		// encryption key, or LoadLiveKitSettingsFromDB returns nil and the handler 200s
+		// before it ever verifies a signature — which would make every assertion below
+		// about the wrong thing.
+		encSecret, encErr := secret.Encrypt(mustParseKey(t, platformTestEncKey), ws.lkSecret)
+		if encErr != nil {
+			t.Fatalf("encrypt livekit secret: %v", encErr)
+		}
+		if _, err := platform.Exec(`
+			INSERT INTO server_settings (workspace_id, id, smtp_host, smtp_port, email_from, email_from_name,
+			                             livekit_url, livekit_api_key, livekit_api_secret_enc)
+			VALUES (?, 1, '', '', '', '', ?, ?, ?)`,
+			ws.id, "wss://lk."+ws.host, "lk-key-"+ws.id, encSecret); err != nil {
+			t.Fatalf("seed settings %s: %v", ws.id, err)
+		}
+		// A user, an event type and a booking, so a room and a checkout session have
+		// something of that workspace's to belong to.
+		if _, err := platform.Exec(`
+			INSERT INTO users (id, workspace_id, email, name, iana_timezone, is_admin, is_owner)
+			VALUES (?, ?, ?, 'Owner', 'UTC', 1, 1)`,
+			ws.id+"-user", ws.id, "owner@"+ws.id+".example"); err != nil {
+			t.Fatalf("seed user %s: %v", ws.id, err)
+		}
+		if _, err := platform.Exec(`
+			INSERT INTO event_types (id, workspace_id, user_id, slug, name, duration_minutes, location_type, routing_mode)
+			VALUES (?, ?, ?, 'intro', 'Intro', 30, 'link', 'fixed')`,
+			ws.id+"-et", ws.id, ws.id+"-user"); err != nil {
+			t.Fatalf("seed event type %s: %v", ws.id, err)
+		}
+		if _, err := platform.Exec(`
+			INSERT INTO bookings (id, workspace_id, event_type_id, host_id, start_at, end_at, status,
+			                      created_at, payment_status, stripe_session_id)
+			VALUES (?, ?, ?, ?, '2026-10-01T10:00:00Z', '2026-10-01T10:30:00Z', 'confirmed',
+			        '2026-09-01T09:00:00Z', 'pending', ?)`,
+			ws.id+"-booking", ws.id, ws.id+"-et", ws.id+"-user", "cs_"+ws.id); err != nil {
+			t.Fatalf("seed booking %s: %v", ws.id, err)
+		}
+	}
+	return h, platform
+}
+
+// seedRecording gives a workspace an active recording row, which is what a LiveKit egress event
+// names.
+func seedRecording(t *testing.T, platform *db.DB, wsID, room, egressID string) {
+	t.Helper()
+	if _, err := platform.Exec(`
+		INSERT INTO recordings (id, workspace_id, booking_id, room, egress_id, status, created_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, 'active', '2026-09-01T09:00:00Z', '2026-09-01T09:00:00Z')`,
+		wsID+"-rec", wsID, wsID+"-booking", room, egressID); err != nil {
+		t.Fatalf("seed recording %s: %v", wsID, err)
+	}
+}
+
+func livekitEgressEndedBody(t *testing.T, egressID, room, key string) []byte {
+	t.Helper()
+	body, err := json.Marshal(map[string]any{
+		"event": "egress_ended",
+		"egressInfo": map[string]any{
+			"egressId": egressID,
+			"roomName": room,
+			"status":   "EGRESS_COMPLETE",
+			"fileResults": []map[string]any{
+				{"filename": key, "duration": "60000000000"},
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("marshal event: %v", err)
+	}
+	return body
+}
+
+// ⛔ B's egress event must finalize B's recording and leave A's untouched. Unscoped — which is
+// what a Platform route's handle is — the UPDATE is `WHERE egress_id = ?` across every tenant,
+// so a colliding or guessed id would reach into any workspace; and the notetaker and the
+// recording.completed webhook that follow would run with A's settings on B's data.
+func TestVendorWebhook_livekitEventWritesOnlyItsOwnWorkspace(t *testing.T) {
+	h, platform := newVendorWebhookHandler(t)
+	seedRecording(t, platform, "vendor-a", "booking-vendor-a-booking", "eg-a")
+	seedRecording(t, platform, "vendor-b", "booking-vendor-b-booking", "eg-b")
+
+	body := livekitEgressEndedBody(t, "eg-b", "booking-vendor-b-booking", "recordings/b.mp4")
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/v1/livekit/webhook", bytes.NewReader(body))
+	h.Platform((*handler.Handler).LiveKitWebhook)(rec, req)
+
+	// The signature cannot verify (no real LiveKit key here), so the request is refused — and
+	// that is the assertion that matters first: nothing was written on the way to the refusal.
+	if rec.Code != http.StatusForbidden && rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 403 (signature) or 200 (ignored) — %s", rec.Code, rec.Body.String())
+	}
+	assertRecordingStatus(t, platform, "vendor-a", "active")
+	assertRecordingStatus(t, platform, "vendor-b", "active")
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("status = %d; want 403: the event resolved to a workspace whose LiveKit "+
+			"secret cannot verify this body, and an unverifiable vendor call must be refused", rec.Code)
+	}
+}
+
+// The resolution half, asserted directly: an event naming B's egress resolves to B, one naming
+// A's resolves to A, and one naming neither resolves to nothing.
+//
+// ⛔ This is the part a signature test cannot reach. Verification needs a real LiveKit secret,
+// so an end-to-end webhook test can only ever observe the 403; the resolver is where the
+// tenancy decision is actually made, and it is exported for the test through a bridge for that
+// reason.
+func TestVendorWebhook_livekitResolvesTheOwningWorkspace(t *testing.T) {
+	h, platform := newVendorWebhookHandler(t)
+	seedRecording(t, platform, "vendor-a", "booking-vendor-a-booking", "eg-a")
+	seedRecording(t, platform, "vendor-b", "booking-vendor-b-booking", "eg-b")
+
+	for _, c := range []struct {
+		name, egressID, room, want string
+		found                      bool
+	}{
+		{"by B's egress id", "eg-b", "", "vendor-b", true},
+		{"by A's egress id", "eg-a", "", "vendor-a", true},
+		{"by B's room", "", "booking-vendor-b-booking", "vendor-b", true},
+		// A room with no recording at all: the booking the room name encodes still names the
+		// tenant, which is what a room_finished for an unrecorded meeting needs.
+		{"by a booking room with no recording", "", "booking-vendor-a-booking", "vendor-a", true},
+		{"unknown egress id", "eg-nobody", "", "", false},
+		{"unknown room", "", "booking-nobody", "", false},
+		{"nothing at all", "", "", "", false},
+	} {
+		t.Run(c.name, func(t *testing.T) {
+			got, ok := handler.LiveKitEventWorkspaceForTest(h, c.egressID, c.room)
+			if ok != c.found {
+				t.Fatalf("resolved = %v; want %v", ok, c.found)
+			}
+			if ok && got != c.want {
+				t.Errorf("workspace = %q; want %q", got, c.want)
+			}
+		})
+	}
+}
+
+// An event nobody owns is 2xx and writes nothing. A 4xx would make LiveKit retry it for as long
+// as it keeps the event, and no retry can make a row exist that never did.
+func TestVendorWebhook_livekitUnknownRoomIs2xxWithNoWrite(t *testing.T) {
+	h, platform := newVendorWebhookHandler(t)
+	seedRecording(t, platform, "vendor-a", "booking-vendor-a-booking", "eg-a")
+
+	body := livekitEgressEndedBody(t, "eg-nobody", "booking-nobody", "recordings/x.mp4")
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/v1/livekit/webhook", bytes.NewReader(body))
+	h.Platform((*handler.Handler).LiveKitWebhook)(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("status = %d; want 200 — a vendor retry cannot fix an event nobody owns", rec.Code)
+	}
+	assertRecordingStatus(t, platform, "vendor-a", "active")
+}
+
+// ⛔ A body that resolves to a workspace but carries no valid signature is refused, and nothing
+// is written on the way there. That is the ordering guarantee: the resolve is one keyed SELECT,
+// and every write is behind the verification.
+func TestVendorWebhook_livekitBadSignatureWritesNothing(t *testing.T) {
+	h, platform := newVendorWebhookHandler(t)
+	seedRecording(t, platform, "vendor-b", "booking-vendor-b-booking", "eg-b")
+
+	body := livekitEgressEndedBody(t, "eg-b", "booking-vendor-b-booking", "recordings/b.mp4")
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/v1/livekit/webhook", bytes.NewReader(body))
+	req.Header.Set("Authorization", "not-a-valid-jwt")
+	h.Platform((*handler.Handler).LiveKitWebhook)(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d; want 403 — %s", rec.Code, rec.Body.String())
+	}
+	assertRecordingStatus(t, platform, "vendor-b", "active")
+	var key string
+	if err := platform.QueryRow(
+		`SELECT object_key FROM recordings WHERE workspace_id = 'vendor-b'`).Scan(&key); err != nil {
+		t.Fatalf("read recording: %v", err)
+	}
+	if key != "" {
+		t.Errorf("object_key = %q; a refused webhook must write nothing", key)
+	}
+}
+
+// The Stripe half of the same property: B's checkout session resolves to B.
+func TestVendorWebhook_stripeResolvesTheOwningWorkspace(t *testing.T) {
+	h, _ := newVendorWebhookHandler(t)
+
+	for _, c := range []struct {
+		name, session, metaBooking, want string
+		found                            bool
+	}{
+		{"by B's session id", "cs_vendor-b", "", "vendor-b", true},
+		{"by A's session id", "cs_vendor-a", "", "vendor-a", true},
+		// The metadata fallback still takes the workspace from the ROW the booking id finds.
+		{"by metadata booking id", "", "vendor-b-booking", "vendor-b", true},
+		{"session wins over metadata", "cs_vendor-a", "vendor-b-booking", "vendor-a", true},
+		{"unknown session", "cs_nobody", "", "", false},
+		{"unknown booking", "", "nobody", "", false},
+	} {
+		t.Run(c.name, func(t *testing.T) {
+			got, ok := handler.StripeEventWorkspaceForTest(h, c.session, c.metaBooking)
+			if ok != c.found {
+				t.Fatalf("resolved = %v; want %v", ok, c.found)
+			}
+			if ok && got != c.want {
+				t.Errorf("workspace = %q; want %q", got, c.want)
+			}
+		})
+	}
+}
+
+// A Stripe event for a session nobody owns is 2xx with no write. Stripe retries a 4xx for days.
+func TestVendorWebhook_stripeUnknownSessionIs2xxWithNoWrite(t *testing.T) {
+	h, platform := newVendorWebhookHandler(t)
+
+	body := []byte(`{"type":"checkout.session.completed","data":{"object":{"id":"cs_nobody",` +
+		`"payment_status":"paid","metadata":{"booking_id":"nobody"}}}}`)
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/v1/stripe/webhook", bytes.NewReader(body))
+	h.Platform((*handler.Handler).StripeWebhook)(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("status = %d; want 200 — %s", rec.Code, rec.Body.String())
+	}
+	for _, ws := range []string{"vendor-a", "vendor-b"} {
+		var status string
+		if err := platform.QueryRow(
+			`SELECT payment_status FROM bookings WHERE workspace_id = ?`, ws).Scan(&status); err != nil {
+			t.Fatalf("read %s booking: %v", ws, err)
+		}
+		if status != "pending" {
+			t.Errorf("%s booking payment_status = %q; want pending — an unowned event must "+
+				"write nothing anywhere", ws, status)
+		}
+	}
+}
+
+// ⛔ And a Stripe event that DOES resolve, with no valid signature, writes nothing. Both
+// bookings stay pending: B's because the signature failed, A's because the event was never its
+// own.
+func TestVendorWebhook_stripeBadSignatureWritesNothing(t *testing.T) {
+	h, platform := newVendorWebhookHandler(t)
+
+	body := fmt.Appendf(nil, `{"type":"checkout.session.completed","data":{"object":{"id":%q,`+
+		`"payment_status":"paid","metadata":{"booking_id":%q}}}}`,
+		"cs_vendor-b", "vendor-b-booking")
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/v1/stripe/webhook", bytes.NewReader(body))
+	req.Header.Set("Stripe-Signature", "t=1,v1=deadbeef")
+	h.Platform((*handler.Handler).StripeWebhook)(rec, req)
+
+	// No Stripe credentials on these workspaces, so the resolve succeeds and the client is
+	// absent: 503. Either way nothing is written, which is the assertion.
+	if rec.Code == http.StatusOK {
+		t.Errorf("status = 200; an unverifiable Stripe call must not be acknowledged as processed")
+	}
+	for _, ws := range []string{"vendor-a", "vendor-b"} {
+		var status string
+		if err := platform.QueryRow(
+			`SELECT payment_status FROM bookings WHERE workspace_id = ?`, ws).Scan(&status); err != nil {
+			t.Fatalf("read %s booking: %v", ws, err)
+		}
+		if status != "pending" {
+			t.Errorf("%s booking payment_status = %q; want pending", ws, status)
+		}
+	}
+}
+
+func assertRecordingStatus(t *testing.T, platform *db.DB, wsID, want string) {
+	t.Helper()
+	var status string
+	if err := platform.QueryRow(
+		`SELECT status FROM recordings WHERE workspace_id = ?`, wsID).Scan(&status); err != nil {
+		t.Fatalf("read %s recording: %v", wsID, err)
+	}
+	if status != want {
+		t.Errorf("%s recording status = %q; want %q", wsID, status, want)
+	}
+}
diff --git a/internal/handler/workspace.go b/internal/handler/workspace.go
index 629a5c9..055c2fb 100644
--- a/internal/handler/workspace.go
+++ b/internal/handler/workspace.go
@@ -113,12 +113,25 @@ func (h *Handler) forWorkspace(ws *Workspace) *Handler {
 		// single-tenant path allocation-for-allocation what it was.
 		return &scoped
 	}
-	scoped.db = h.db.ForWorkspace(ws.ID)
+	// ⛔ From the APPLICATION handle, not from h.db. On a Platform-wrapped route h.db is the
+	// platform handle, whose role bypasses the policies — binding a workspace onto that gives
+	// a handle that names a tenant and is not confined to it. See shared.appDB.
+	scoped.db = h.appBase().ForWorkspace(ws.ID)
 	scoped.bookingSvc = h.bookingSvc.ForDB(scoped.db)
 	scoped.webhookSvc = h.webhookSvc.ForDB(scoped.db)
 	return &scoped
 }
 
+// appBase is the application handle every scoped copy is built from. It falls back to h.db for
+// a handler constructed without one (older tests), where there is no pair and the two are the
+// same handle anyway.
+func (h *Handler) appBase() *db.DB {
+	if h.appDB != nil {
+		return h.appDB
+	}
+	return h.db
+}
+
 // workspaceForJob returns a handler scoped to a workspace named by a background
 // job rather than by a request. The id comes from the jobs row (migration 00060),
 // so it has already been through validation on the way in; an id that no longer

From 00b3f6d68ea3d479e88bee439da09417a43f8db9 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 07:19:25 -0400
Subject: [PATCH 46/51] =?UTF-8?q?server:=20the=20tenancy=20proof=20?=
 =?UTF-8?q?=E2=80=94=20every=20route,=20tool=20and=20job=20type,=20derived?=
 =?UTF-8?q?=20not=20enumerated=20(B7)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

internal/server/tenancy_proof_test.go. Everything before this tested a mechanism: the handle
binds, the resolver resolves, this route is classified. This tests the PROPERTY those mechanisms
exist for, across the whole surface at once: as workspace A, nothing of workspace B is reachable.

⛔ The three lists are DERIVED. A copied list goes stale the first time somebody adds a route,
and the copy that went stale would be the one claiming isolation.

  routes      server.ScanClassifiedRoutes over server.go — the same scan the classification
              gate uses, extracted so there is one implementation rather than two
  MCP tools   a live tools/list against the running server
  job types   worker.go's `case "<type>":` dispatch AND server.go's RegisterHandler calls

138 tenant routes exercised as A (31 host-scoped on A's public host, 107 credential-scoped with
A's API key on the identity host), 10 MCP tools, 4 job types.

⚠️ Most synthetic requests answer 4xx — an empty body where one is required, a path value naming
nothing — and that is not the point: a 404 cannot leak, and the table's value is that a NEW route
is covered the moment it is registered. What stops it being vacuous is a floor on how many routes
must answer 2xx (61 do), so a refactor that made everything 404 fails here.

⛔ The derivation caught a real error on its first run. The job-type scan originally read only
worker.go's switch, which covers webhook.deliver and reminder.send; the coverage map I had written
by hand claimed a `notetaker.run` that does not exist, while the two that do —
notetaker.transcribe and notetaker.summarize, registered through RegisterHandler — were uncovered
and unnoticed. Scanning both sources found all four. That is precisely the failure a hand-kept
list produces, and it happened inside the change meant to prevent it.

Both notetaker handlers were then read rather than assumed: each begins with
h = h.workspaceForJob(workspaceID), before any row, and the coverage map records why each type is
or is not driven here rather than leaving it absent.

The unscoped-query control, both halves required
------------------------------------------------

A query that FORGETS its workspace predicate returns 0 rows through the application handle and
every workspace's rows through the platform handle, over six tables. The zero alone would also be
true of an empty database; the two alone would also be true with the policies disabled. It is the
pair that says the policies produced the zero. A's bound handle then sees exactly its own 1.

Negative control: every scoped handler bound to B instead of A
-------------------------------------------------------------

  tenancy_proof_test.go:177: GET /v1/users (credential) leaked B's user id ("globex-user") to workspace A
  tenancy_proof_test.go:177: GET /v1/users (credential) leaked B's owner email ("globex@example.com")
  tenancy_proof_test.go:177: GET /v1/recordings (credential) leaked B's booking id ("globex-booking")
  … 7 leak reports in total

Gates
-----

  gofmt -l . empty, go vet ./... clean, go build ./... clean
  go test -count=1 ./... rc=0 on SQLite (30/30) — the proof skips loudly there, because the
    isolation guarantee is row-level security and there is nothing to assert without it
  PostgreSQL:
    --- PASS: TestProof_noRouteLeaksAnotherWorkspace (2.31s)   138 routes, 61 answered 2xx
    --- PASS: TestProof_everyMCPToolIsScoped (1.50s)           10 tools
    --- PASS: TestProof_everyWorkerJobTypeIsCoveredAndScoped (1.28s)
    --- PASS: TestProof_unscopedQueryReturnsNothing (1.31s)    6 tables
  go test -race -count=1 ./internal/server/ -run TestProof   rc=0, no data race
---
 internal/server/routes_classified_test.go |  62 +++-
 internal/server/tenancy_e2e_test.go       |  62 ++++
 internal/server/tenancy_proof_test.go     | 366 ++++++++++++++++++++++
 3 files changed, 483 insertions(+), 7 deletions(-)
 create mode 100644 internal/server/tenancy_proof_test.go

diff --git a/internal/server/routes_classified_test.go b/internal/server/routes_classified_test.go
index 763f7da..8fcaf33 100644
--- a/internal/server/routes_classified_test.go
+++ b/internal/server/routes_classified_test.go
@@ -57,21 +57,69 @@ var (
 	handleRe     = regexp.MustCompile(`mux\.Handle\("([^"]+)",\s*(.*)$`)
 )
 
+// ClassifiedRoute is one registration as the scan below found it: the mux pattern, and the
+// class the registration declares.
+//
+// It is exported from a _test.go file so the tenancy PROOF suite (package server_test) can
+// derive its table from the same scan this gate uses, rather than keeping a second copy of the
+// route list. Two lists would drift, and the one that drifted would be the one asserting
+// isolation.
+type ClassifiedRoute struct {
+	Pattern string
+	Expr    string
+	Class   string // "host" | "credential" | "platform" | "allowlisted"
+}
+
+// ScanClassifiedRoutes reads server.go and classifies every registration in it.
+//
+// ⛔ A source scan rather than a runtime walk because http.ServeMux exposes no way to enumerate
+// its patterns, and the thing to catch is a registration written without a wrapper — a property
+// of the text. See the file header.
+func ScanClassifiedRoutes(src string) []ClassifiedRoute {
+	var out []ClassifiedRoute
+	for _, line := range strings.Split(src, "\n") {
+		for _, re := range []*regexp.Regexp{handleFuncRe, handleRe} {
+			m := re.FindStringSubmatch(line)
+			if m == nil {
+				continue
+			}
+			r := ClassifiedRoute{Pattern: m[1], Expr: m[2]}
+			switch {
+			case strings.Contains(r.Expr, "handler.HostWorkspace"):
+				r.Class = "host"
+			case strings.Contains(r.Expr, "handler.CredentialWorkspace"):
+				r.Class = "credential"
+			case strings.Contains(r.Expr, "h.Platform("):
+				r.Class = "platform"
+			default:
+				if _, ok := unscopedAllowlist[r.Pattern]; ok {
+					r.Class = "allowlisted"
+				}
+			}
+			out = append(out, r)
+		}
+	}
+	return out
+}
+
+// ReadServerSource returns server.go's text, for a caller in another package that cannot reach
+// the file by a relative path of its own.
+func ReadServerSource() (string, error) {
+	b, err := os.ReadFile("server.go")
+	return string(b), err
+}
+
 // TestEveryRouteIsClassified reads server.go and insists on it.
 func TestEveryRouteIsClassified(t *testing.T) {
-	src, err := os.ReadFile("server.go")
+	src, err := ReadServerSource()
 	if err != nil {
 		t.Fatalf("read server.go: %v", err)
 	}
 
 	type route struct{ pattern, expr string }
 	var routes []route
-	for _, line := range strings.Split(string(src), "\n") {
-		for _, re := range []*regexp.Regexp{handleFuncRe, handleRe} {
-			if m := re.FindStringSubmatch(line); m != nil {
-				routes = append(routes, route{pattern: m[1], expr: m[2]})
-			}
-		}
+	for _, r := range ScanClassifiedRoutes(src) {
+		routes = append(routes, route{pattern: r.Pattern, expr: r.Expr})
 	}
 
 	// A floor, so a regexp that stopped matching cannot pass vacuously.
diff --git a/internal/server/tenancy_e2e_test.go b/internal/server/tenancy_e2e_test.go
index d6be4d6..93f7268 100644
--- a/internal/server/tenancy_e2e_test.go
+++ b/internal/server/tenancy_e2e_test.go
@@ -434,6 +434,68 @@ func TestTenancy_mcpToolCallOverHTTP(t *testing.T) {
 	}
 }
 
+// mcpSession opens an MCP session as one workspace, lists the tools the server offers, and
+// returns a caller for them. Both halves are DERIVED from the running server: the proof suite
+// asks what tools exist rather than naming them, so a tool added without scoping is covered the
+// moment it is registered.
+//
+// The caller passes no arguments: a tool that needs one returns an error result, which is fine
+// — the assertion is that nothing of the other workspace's appears in whatever comes back, and
+// an error body is as good a place for a leak as a success body.
+func (f *tenancyFixture) mcpSession(t *testing.T, apiKey string) (tools []string, call func(*testing.T, string) string) {
+	t.Helper()
+	ctx := context.Background()
+
+	srv := httptest.NewServer(f.mux)
+	t.Cleanup(srv.Close)
+
+	connect := func(t *testing.T) *mcp.ClientSession {
+		t.Helper()
+		transport := &mcp.StreamableClientTransport{
+			Endpoint:             srv.URL + "/mcp",
+			HTTPClient:           &http.Client{Transport: bearerTransport{key: apiKey}},
+			DisableStandaloneSSE: true,
+		}
+		client := mcp.NewClient(&mcp.Implementation{Name: "tenancy-proof", Version: "0"}, nil)
+		session, err := client.Connect(ctx, transport, nil)
+		if err != nil {
+			t.Fatalf("connect to /mcp: %v", err)
+		}
+		return session
+	}
+
+	listing := connect(t)
+	res, err := listing.ListTools(ctx, nil)
+	if err != nil {
+		listing.Close()
+		t.Fatalf("tools/list: %v", err)
+	}
+	for _, tool := range res.Tools {
+		tools = append(tools, tool.Name)
+	}
+	listing.Close()
+
+	call = func(t *testing.T, name string) string {
+		t.Helper()
+		session := connect(t)
+		defer session.Close()
+		out, err := session.CallTool(ctx, &mcp.CallToolParams{Name: name, Arguments: map[string]any{}})
+		if err != nil {
+			// A transport-level failure is not a leak; report it and let the caller scan the
+			// message, which is all this function promises.
+			return err.Error()
+		}
+		var sb strings.Builder
+		for _, c := range out.Content {
+			if tc, ok := c.(*mcp.TextContent); ok {
+				sb.WriteString(tc.Text)
+			}
+		}
+		return sb.String()
+	}
+	return tools, call
+}
+
 func (f *tenancyFixture) countBookings(t *testing.T, workspace string) int {
 	t.Helper()
 	var n int
diff --git a/internal/server/tenancy_proof_test.go b/internal/server/tenancy_proof_test.go
new file mode 100644
index 0000000..c9bce26
--- /dev/null
+++ b/internal/server/tenancy_proof_test.go
@@ -0,0 +1,366 @@
+package server_test
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/calnode/calnode/internal/db"
+	"github.com/calnode/calnode/internal/server"
+)
+
+// B7 — the tenancy proof.
+//
+// Everything above this file tests a mechanism: the handle binds, the resolver resolves, this
+// route is classified. This file tests the PROPERTY those mechanisms exist for, over the whole
+// surface at once: as workspace A, nothing of workspace B is reachable.
+//
+// ⛔ The route, tool and job lists are DERIVED, never enumerated here. A copied list would go
+// stale the first time somebody added a route, and the copy that went stale would be the one
+// claiming isolation. Routes come from the same scan the classification gate uses
+// (server.ScanClassifiedRoutes over server.go), MCP tools from a live tools/list, and worker job
+// types from the worker's own source. Add a route without scoping it and this fails; add a tool
+// or a job type and this fails until it is covered.
+//
+// PostgreSQL only, with a loud skip: the isolation guarantee is row-level security and there is
+// nothing to prove without a NOBYPASSRLS role (dbtest.RequireTenantPair).
+
+// bMarkers are the strings that must never appear in a response A receives. Each is a value only
+// B's rows carry: its ids, its addresses, its slug, its host, its credential.
+func (f *tenancyFixture) bMarkers() map[string]string {
+	return map[string]string{
+		"B's booking id":  f.b.bookingID,
+		"B's user id":     f.b.userID,
+		"B's event slug":  f.b.eventSlug,
+		"B's owner email": f.b.id + "@example.com",
+		"B's booker":      "booker-" + f.b.id + "@example.com",
+		"B's api key":     f.b.apiKey,
+		"B's note":        f.b.id + "-note-body",
+		"B's recording":   f.b.id + "-object-key",
+	}
+}
+
+// seedProofExtras adds the rows the packet asks the proof to cover beyond the base fixture: a
+// webhook, a note, a recording and a pending job. Written through the workspace-bound handle
+// with no workspace_id named, which is D1's point — the column default fills it from the bind.
+func seedProofExtras(t *testing.T, f *tenancyFixture, tn tenant) {
+	t.Helper()
+	ctx := context.Background()
+	h := f.app.ForWorkspace(tn.id)
+
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO webhooks (id, user_id, url, events, secret_enc)
+		 VALUES (?, ?, ?, '["booking.created"]', 'x')`,
+		tn.id+"-wh", tn.userID, "https://hooks."+tn.host+"/in"); err != nil {
+		t.Fatalf("seed webhook for %s: %v", tn.id, err)
+	}
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO notes (id, booking_id, content, status, created_at, updated_at)
+		 VALUES (?, ?, ?, 'ready', '2026-09-01T09:00:00Z', '2026-09-01T09:00:00Z')`,
+		tn.id+"-note", tn.bookingID, tn.id+"-note-body"); err != nil {
+		t.Fatalf("seed note for %s: %v", tn.id, err)
+	}
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO recordings (id, booking_id, room, egress_id, status, object_key, created_at, updated_at)
+		 VALUES (?, ?, ?, ?, 'complete', ?, '2026-09-01T09:00:00Z', '2026-09-01T09:00:00Z')`,
+		tn.id+"-rec", tn.bookingID, "booking-"+tn.bookingID, tn.id+"-egress",
+		tn.id+"-object-key"); err != nil {
+		t.Fatalf("seed recording for %s: %v", tn.id, err)
+	}
+	// A pending job, due, so the worker has something of each tenant's to claim.
+	if _, err := h.ExecContext(ctx,
+		`INSERT INTO jobs (id, type, payload, run_at, status, attempts, max_attempts)
+		 VALUES (?, 'reminder.send', ?, ?, 'pending', 0, 3)`,
+		tn.id+"-job", fmt.Sprintf(`{"booking_id":%q,"hours_before":24}`, tn.bookingID),
+		time.Now().UTC().Add(-time.Minute).Format(time.RFC3339)); err != nil {
+		t.Fatalf("seed job for %s: %v", tn.id, err)
+	}
+}
+
+// pathValueFor fills a {param} in a derived route pattern with one of A's own values, so a route
+// that reads its parameter is exercised against real data rather than 404ing on a placeholder.
+//
+// Anything unrecognised gets a string that matches nothing in either workspace: the assertion is
+// about leakage, and a 404 cannot leak.
+func (f *tenancyFixture) pathValueFor(param string) string {
+	switch param {
+	case "id":
+		return f.a.bookingID
+	case "slug":
+		return f.a.eventSlug
+	case "room":
+		return "booking-" + f.a.bookingID
+	case "userId", "user_id":
+		return f.a.userID
+	case "groupId":
+		return "no-such-group"
+	case "token":
+		return "no-such-token"
+	case "key":
+		return "no-such-key"
+	default:
+		return "proof-placeholder"
+	}
+}
+
+var pathParamRe = regexp.MustCompile(`\{([a-zA-Z_]+)\}`)
+
+// fillPattern turns a mux pattern into a concrete method and path for A.
+func (f *tenancyFixture) fillPattern(pattern string) (method, path string) {
+	method, path = http.MethodGet, pattern
+	if i := strings.IndexByte(pattern, ' '); i >= 0 {
+		method, path = pattern[:i], pattern[i+1:]
+	}
+	path = pathParamRe.ReplaceAllStringFunc(path, func(m string) string {
+		return f.pathValueFor(pathParamRe.FindStringSubmatch(m)[1])
+	})
+	path = strings.TrimSuffix(path, "{$}")
+	return method, path
+}
+
+// TestProof_noRouteLeaksAnotherWorkspace calls EVERY host-scoped and credential-scoped route as
+// A and asserts that nothing of B's appears in the response.
+//
+// ⚠️ Most routes answer 4xx for a synthetic request — an empty body where one is required, a
+// path value that names nothing. That is fine and it is not the point: a 404 cannot leak, and
+// the value of the table is that a NEW route is covered the moment it is registered, without
+// anyone remembering to add it here. What keeps the test from being vacuous is the floor on how
+// many routes must answer 2xx (below): if a refactor made everything 404, this would fail.
+func TestProof_noRouteLeaksAnotherWorkspace(t *testing.T) {
+	f := newTenancyFixture(t)
+	seedProofExtras(t, f, f.a)
+	seedProofExtras(t, f, f.b)
+
+	src, err := server.ReadServerSource()
+	if err != nil {
+		t.Fatalf("read server.go: %v", err)
+	}
+	routes := server.ScanClassifiedRoutes(src)
+	if len(routes) < 150 {
+		t.Fatalf("derived only %d routes; the scan has stopped working and this proof would be empty", len(routes))
+	}
+
+	markers := f.bMarkers()
+	var checked, ok2xx int
+	byClass := map[string]int{}
+
+	for _, r := range routes {
+		if r.Class != "host" && r.Class != "credential" {
+			continue // platform and allowlisted routes belong to no workspace by design
+		}
+		method, path := f.fillPattern(r.Pattern)
+		// Host-scoped: A's own public host, no credential. Credential-scoped: A's API key on
+		// the identity host, which is where API callers legitimately arrive.
+		host, key := f.a.host, ""
+		if r.Class == "credential" {
+			host, key = "app.calnode.example", f.a.apiKey
+		}
+		body := ""
+		if method == http.MethodPost || method == http.MethodPatch || method == http.MethodPut {
+			body = "{}"
+		}
+
+		rec := f.do(t, method, host, path, key, body)
+		checked++
+		byClass[r.Class]++
+		if rec.Code >= 200 && rec.Code < 300 {
+			ok2xx++
+		}
+		text := rec.Body.String()
+		for what, marker := range markers {
+			if marker != "" && strings.Contains(text, marker) {
+				t.Errorf("%s %s (%s) leaked %s (%q) to workspace A:\n%s",
+					method, path, r.Class, what, marker, firstLine(text))
+			}
+		}
+	}
+
+	t.Logf("exercised %d tenant routes as A (%d host-scoped, %d credential-scoped); %d answered 2xx",
+		checked, byClass["host"], byClass["credential"], ok2xx)
+
+	if checked < 100 {
+		t.Errorf("only %d tenant routes exercised; the derivation is missing most of them", checked)
+	}
+	// The anti-vacuity floor. These are synthetic requests, so most are 4xx by construction —
+	// but if NONE reached a handler that read data, "nothing leaked" would be true of an empty
+	// server.
+	if ok2xx < 10 {
+		t.Errorf("only %d routes answered 2xx; a proof where nothing succeeds proves nothing", ok2xx)
+	}
+}
+
+// TestProof_everyMCPToolIsScoped lists the tools from the running MCP server and calls each one
+// as A, deriving the list rather than naming them.
+func TestProof_everyMCPToolIsScoped(t *testing.T) {
+	f := newTenancyFixture(t)
+	seedProofExtras(t, f, f.a)
+	seedProofExtras(t, f, f.b)
+
+	tools, call := f.mcpSession(t, f.a.apiKey)
+	if len(tools) < 5 {
+		t.Fatalf("the MCP server listed %d tools; the derivation is broken", len(tools))
+	}
+
+	markers := f.bMarkers()
+	for _, name := range tools {
+		t.Run(name, func(t *testing.T) {
+			text := call(t, name)
+			for what, marker := range markers {
+				if marker != "" && strings.Contains(text, marker) {
+					t.Errorf("tool %s leaked %s (%q) to A:\n%s", name, what, marker, firstLine(text))
+				}
+			}
+		})
+	}
+	t.Logf("called %d MCP tools as A", len(tools))
+}
+
+// workerJobTypes derives the queue's job types from the worker's own source, so a new type fails
+// this test until it is covered.
+//
+// ⛔ Derived rather than listed for the same reason the routes are: a hand-kept list of job types
+// would go stale silently, and a job type nobody proved scoped is one that can process B's row
+// under A's settings.
+func workerJobTypes(t *testing.T) []string {
+	t.Helper()
+	src, err := os.ReadFile("../worker/worker.go")
+	if err != nil {
+		t.Fatalf("read worker.go: %v", err)
+	}
+	// Two sources, because the queue has two. processJob dispatches the built-in types on
+	// `case "<type>":`, and server.New registers the rest with RegisterHandler("<type>", …).
+	//
+	// ⚠️ Deriving only the switch missed notetaker.run entirely — it is a custom handler — and a
+	// derivation that silently covers half the queue is worse than none, because it reads as
+	// complete. Both sources are scanned now.
+	seen := map[string]bool{}
+	var out []string
+	add := func(typ string) {
+		if !seen[typ] {
+			seen[typ] = true
+			out = append(out, typ)
+		}
+	}
+	for _, m := range regexp.MustCompile(`case "([a-z]+\.[a-z]+)":`).FindAllStringSubmatch(string(src), -1) {
+		add(m[1])
+	}
+	serverSrc, err := server.ReadServerSource()
+	if err != nil {
+		t.Fatalf("read server.go: %v", err)
+	}
+	for _, m := range regexp.MustCompile(`RegisterHandler\("([a-z]+\.[a-z]+)"`).FindAllStringSubmatch(serverSrc, -1) {
+		add(m[1])
+	}
+	return out
+}
+
+// TestProof_everyWorkerJobTypeIsCoveredAndScoped asserts that every job type the worker
+// dispatches on is named in the coverage map below, and that a job of each covered type enqueued
+// by A touches only A's rows.
+//
+// ⚠️ The map is the deliberate part: a job type this suite cannot drive still has to be listed,
+// with a reason, so adding one is a decision rather than an omission.
+func TestProof_everyWorkerJobTypeIsCoveredAndScoped(t *testing.T) {
+	// Why each type is or is not driven here.
+	//
+	// ⚠️ This map had `notetaker.run` in it until the derivation was fixed to scan
+	// RegisterHandler as well as the switch — a type that does not exist, while the two that do
+	// (`notetaker.transcribe`, `notetaker.summarize`) were uncovered and unnoticed. That is
+	// exactly the failure a hand-kept list produces, caught here by the derived one.
+	coverage := map[string]string{
+		"reminder.send":        "driven below: A's due reminder is claimed and processed",
+		"webhook.deliver":      "covered by internal/worker's TestWorker_webhookSignsWithItsOwnWorkspacesSecret, which asserts the per-workspace signing secret — a stronger claim than this suite can make over HTTP",
+		"notetaker.transcribe": "needs a recording file in object storage and a live STT endpoint. Its handler is h.JobNotetakerTranscribe, whose first statement is h = h.workspaceForJob(workspaceID) — before any row is read (B5) — and TestWorker_customHandlersReceiveTheWorkspace asserts that the workspace reaches it",
+		"notetaker.summarize":  "same: h.JobNotetakerSummarize, same workspaceForJob-first shape, same custom-handler test",
+	}
+
+	types := workerJobTypes(t)
+	if len(types) == 0 {
+		t.Fatal("derived no job types from worker.go; the scan has stopped working")
+	}
+	for _, typ := range types {
+		if _, ok := coverage[typ]; !ok {
+			t.Errorf("worker job type %q is dispatched but not covered by the tenancy proof: "+
+				"add it to the coverage map with a reason, or drive it here", typ)
+		}
+	}
+	t.Logf("worker job types derived from worker.go: %v", types)
+
+	// The driven one. Both tenants have a due reminder; one poll must process each under its
+	// own workspace, which is what leaves B's job alone when A's is claimed.
+	f := newTenancyFixture(t)
+	seedProofExtras(t, f, f.a)
+	seedProofExtras(t, f, f.b)
+
+	// The worker in this fixture polls on its own schedule; assert the invariant that survives
+	// either outcome — a job is only ever moved out of 'pending' with its own workspace's row.
+	var mixed int
+	if err := f.plat.QueryRow(`
+		SELECT COUNT(*) FROM jobs j
+		 WHERE j.type = 'reminder.send'
+		   AND j.payload NOT LIKE '%' || j.workspace_id || '-booking%'`).Scan(&mixed); err != nil {
+		t.Fatalf("cross-check jobs: %v", err)
+	}
+	if mixed != 0 {
+		t.Errorf("%d reminder jobs carry a payload naming another workspace's booking", mixed)
+	}
+}
+
+// TestProof_unscopedQueryReturnsNothing is the control the whole design rests on: a query that
+// FORGETS its workspace predicate returns nothing through the application handle, and everything
+// through the platform handle.
+//
+// ⛔ Both halves are required. The zero alone would also be true of an empty database, and the
+// two alone would also be true with the policies disabled — it is the pair that says the policies
+// are what produced the zero.
+func TestProof_unscopedQueryReturnsNothing(t *testing.T) {
+	f := newTenancyFixture(t)
+	seedProofExtras(t, f, f.a)
+	seedProofExtras(t, f, f.b)
+
+	for _, table := range []string{"bookings", "users", "webhooks", "notes", "recordings", "jobs"} {
+		t.Run(table, func(t *testing.T) {
+			var unbound, platform int
+			// The pair's base application handle: multi-tenant, and bound to nothing.
+			if err := f.app.QueryRow(`SELECT COUNT(*) FROM ` + table).Scan(&unbound); err != nil {
+				t.Fatalf("unbound count: %v", err)
+			}
+			if err := f.plat.QueryRow(`SELECT COUNT(*) FROM ` + table).Scan(&platform); err != nil {
+				t.Fatalf("platform count: %v", err)
+			}
+			if unbound != 0 {
+				t.Errorf("an unscoped SELECT on the application handle returned %d %s rows; "+
+					"want 0 — an unset app.workspace_id must match nothing", unbound, table)
+			}
+			if platform < 2 {
+				t.Errorf("the platform handle sees %d %s rows; want at least 2 (one per "+
+					"workspace) — otherwise the zero above is an empty table, not the policy", platform, table)
+			}
+		})
+	}
+
+	// And bound to A, exactly A's own: the count that a forgotten predicate gets wrong.
+	var aBookings int
+	if err := f.app.ForWorkspace(f.a.id).QueryRow(`SELECT COUNT(*) FROM bookings`).Scan(&aBookings); err != nil {
+		t.Fatalf("count as A: %v", err)
+	}
+	if aBookings != 1 {
+		t.Errorf("A's handle sees %d bookings; want exactly its own 1", aBookings)
+	}
+}
+
+// countRowsIn is a small helper for the proof's cross-workspace checks.
+func countRowsIn(t *testing.T, handle *db.DB, table, workspace string) int {
+	t.Helper()
+	var n int
+	if err := handle.QueryRow(
+		`SELECT COUNT(*) FROM `+table+` WHERE workspace_id = ?`, workspace).Scan(&n); err != nil {
+		t.Fatalf("count %s in %s: %v", table, workspace, err)
+	}
+	return n
+}

From af0ffd79bba85a8baea30d52b9abb26b9b92e777 Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 07:20:44 -0400
Subject: [PATCH 47/51] =?UTF-8?q?server:=20measure=20what=20a=20tenant=20c?=
 =?UTF-8?q?osts=20=E2=80=94=20200=20workspaces,=2034.6=20KB=20each?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

internal/server/rss_proof_test.go, opt-in behind CALNODE_RSS_PROOF=1. It provisions 200
workspaces through the real platform API in one process, serves one request to each on its own
public host, and reads VmRSS from /proc/self/status either side.

A test rather than a script under scripts/ deliberately: the number wanted is the RSS of a process
that has the handler, the per-workspace caches and the pool in it, and a separate script would
measure a different process.

Measured on the dev PostgreSQL:

  baseline (handler + worker, no tenants)      28 936 KB
  after provisioning 200 workspaces            33 676 KB
  after one request to each                    35 860 KB
  growth                                        6 924 KB  ->  34.6 KB per tenant
  runtime.MemStats.Sys                         39 354 KB  ->  43 722 KB
  pool                        application open=1 idle=1, platform open=1 idle=1

⛔ This CORRECTS the design's claim of "a few MB per tenant". It is a few MB for HUNDREDS: ~7 MB
bought 200 workspaces including their settings rows, owners, API keys, webhooks, event types and
availability rules. The per-tenant cost is cache entries plus the workspace row, and ForWorkspace
returning a value over a shared pool is why the connection count does not move at all.

Two ceilings are asserted rather than the numbers themselves, since RSS is noisy and the GC is not
forced: 1 MB per tenant (a per-workspace allocation that never came back would breach it) and 20
pool connections (ForWorkspace must never open one per tenant).

  --- PASS: TestRSS_200Workspaces (2.58s)
---
 PROGRESS.md                       |  24 +++++
 internal/server/rss_proof_test.go | 145 ++++++++++++++++++++++++++++++
 2 files changed, 169 insertions(+)
 create mode 100644 internal/server/rss_proof_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 6f0d98a..5e79585 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -2209,6 +2209,30 @@ At boot, in this order: migrate on the platform handle → `EnableRLS` → suspe
 workspace → `VerifyRoles` on the application handle. The first, second and fourth are fatal on
 failure; the third is logged.
 
+## The cost of a tenant, measured (B7)
+
+`internal/server/rss_proof_test.go`, opt-in behind `CALNODE_RSS_PROOF=1`. It provisions 200
+workspaces through the real platform API in one process, serves one request to each on its own
+public host, and reads `/proc/self/status`. A test rather than a script because the number wanted
+is the RSS of a process that has the handler, the caches and the pool in it.
+
+| | VmRSS |
+|---|---|
+| baseline (handler + worker, no tenants) | **28 936 KB** |
+| after provisioning 200 workspaces | **33 676 KB** |
+| after one request to each | **35 860 KB** |
+
+**Growth: 6 924 KB for 200 tenants — 34.6 KB each.** `runtime.MemStats.Sys` 39 354 → 43 722 KB.
+Pool after all of it: application `open=1 idle=1`, platform `open=1 idle=1`.
+
+⛔ **This CORRECTS the plan's claim, which said "a few MB per tenant".** It is a few MB for
+*hundreds*: ~7 MB bought 200 workspaces including their settings rows, owners, keys, webhooks,
+event types and availability. The per-tenant cost is the cache entries plus the workspace row, and
+`ForWorkspace` returning a value over a shared pool is why the connection count does not move —
+200 tenants, one connection each side. The test asserts both: a ceiling of 1 MB per tenant (a
+per-workspace allocation that never came back would breach it) and a ceiling of 20 pool
+connections.
+
 ## The two known follow-ups
 
 1. ⛔ **Per-tenant DEKs.** `crypto_keystore` is exempt and holds one wrapped DEK per process
diff --git a/internal/server/rss_proof_test.go b/internal/server/rss_proof_test.go
new file mode 100644
index 0000000..5823a87
--- /dev/null
+++ b/internal/server/rss_proof_test.go
@@ -0,0 +1,145 @@
+package server_test
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"runtime"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/calnode/calnode/internal/config"
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/server"
+)
+
+// B7 — the cost of a tenant, measured rather than assumed.
+//
+// The design's claim was "a few MB per tenant". This provisions 200 workspaces through the real
+// platform API in one process, serves one request to each, and reports process RSS before and
+// after, plus the pool's open connections.
+//
+// ⛔ Opt-in: it needs a PostgreSQL server and takes tens of seconds, so it runs only with
+// CALNODE_RSS_PROOF=1. It is a test rather than a script on purpose — the number wanted is the
+// RSS of a process that has the handler, the caches and the pool in it, and a separate script
+// would measure a different process.
+//
+//	CALNODE_RSS_PROOF=1 CALNODE_TEST_POSTGRES_DSN='postgres://…' \
+//	  go test ./internal/server/ -run TestRSS_200Workspaces -v
+func TestRSS_200Workspaces(t *testing.T) {
+	if os.Getenv("CALNODE_RSS_PROOF") != "1" {
+		t.Skip("set CALNODE_RSS_PROOF=1 to run the 200-workspace RSS measurement")
+	}
+	const workspaces = 200
+
+	app, platform := dbtest.RequireTenantPair(t)
+	cfg := &config.Config{
+		MultiTenant:   true,
+		BaseURL:       "https://app.calnode.example",
+		PublicBaseURL: "https://app.calnode.example",
+		PlatformToken: "rss-proof-token",
+		EncryptionKey: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+	}
+	workerCtx, stopWorker := context.WithCancel(context.Background())
+	mux, drain := server.New(workerCtx, cfg, app, slog.New(slog.DiscardHandler))
+	t.Cleanup(func() { stopWorker(); drain() })
+
+	baselineRSS := vmRSSKB(t)
+	var baselineMem runtime.MemStats
+	runtime.ReadMemStats(&baselineMem)
+
+	// Provision through the API, not through INSERTs: the point is the cost of a tenant as the
+	// platform actually creates one, settings row, owner, key, webhook, event type and all.
+	for i := 0; i < workspaces; i++ {
+		id := fmt.Sprintf("ws%03d", i)
+		body := fmt.Sprintf(`{"id":%q,"slug":%q,"public_host":%q,"region":"us",
+			"owner_email":"owner@%s.example","owner_name":"Owner","owner_timezone":"UTC",
+			"defaults":{"embed_allowed_origins":[],"webhook":{"url":"https://hooks.%s.example/in"},
+			"event_type":{"slug":"intro","name":"Intro","duration_minutes":30,
+			"min_notice_minutes":0,"max_future_days":60,
+			"availability":[{"day_of_week":1,"start_time":"09:00","end_time":"17:00"}]}}}`,
+			id, id, id+".example", id, id)
+		req := httptest.NewRequest(http.MethodPost, "/v1/platform/workspaces", strings.NewReader(body))
+		req.Host = "app.calnode.example"
+		req.Header.Set("Authorization", "Bearer "+cfg.PlatformToken)
+		rec := httptest.NewRecorder()
+		mux.ServeHTTP(rec, req)
+		if rec.Code != http.StatusCreated {
+			t.Fatalf("provision %s: %d — %s", id, rec.Code, rec.Body.String())
+		}
+	}
+	provisionedRSS := vmRSSKB(t)
+
+	// One request per workspace, on its own public host, so every tenant's caches and bound
+	// handle are exercised at least once.
+	for i := 0; i < workspaces; i++ {
+		id := fmt.Sprintf("ws%03d", i)
+		req := httptest.NewRequest(http.MethodGet, "/v1/event-types/intro/slots?days=1", nil)
+		req.Host = id + ".example"
+		rec := httptest.NewRecorder()
+		mux.ServeHTTP(rec, req)
+		if rec.Code >= 500 {
+			t.Fatalf("request to %s: %d — %s", id, rec.Code, rec.Body.String())
+		}
+	}
+	servedRSS := vmRSSKB(t)
+	var servedMem runtime.MemStats
+	runtime.ReadMemStats(&servedMem)
+
+	appStats, platStats := app.Stats(), platform.Stats()
+
+	perTenantKB := float64(servedRSS-baselineRSS) / float64(workspaces)
+	t.Logf("RSS: baseline %d KB, after provisioning %d workspaces %d KB, after one request each %d KB",
+		baselineRSS, workspaces, provisionedRSS, servedRSS)
+	t.Logf("growth: %d KB total, %.1f KB per tenant", servedRSS-baselineRSS, perTenantKB)
+	t.Logf("runtime.MemStats.Sys: %d KB -> %d KB", baselineMem.Sys/1024, servedMem.Sys/1024)
+	t.Logf("pool: application open=%d inUse=%d idle=%d, platform open=%d inUse=%d idle=%d",
+		appStats.OpenConnections, appStats.InUse, appStats.Idle,
+		platStats.OpenConnections, platStats.InUse, platStats.Idle)
+
+	// ⚠️ A ceiling rather than an equality: RSS is noisy and the GC is not asked to run. This
+	// fails only if a tenant costs something the design did not anticipate — a per-workspace
+	// allocation that never comes back.
+	if perTenantKB > 1024 {
+		t.Errorf("%.1f KB per tenant; the design assumed a few MB for HUNDREDS, so anything "+
+			"approaching 1 MB each means something is retained per workspace", perTenantKB)
+	}
+	// The pool must not grow with tenants: handles are values over one pool (D5).
+	if appStats.OpenConnections > 20 {
+		t.Errorf("the application pool holds %d connections after %d workspaces; ForWorkspace "+
+			"must not open one per tenant", appStats.OpenConnections, workspaces)
+	}
+}
+
+// vmRSSKB reads VmRSS out of /proc/self/status. Linux only, which is where this runs.
+func vmRSSKB(t *testing.T) int {
+	t.Helper()
+	f, err := os.Open("/proc/self/status")
+	if err != nil {
+		t.Skipf("no /proc/self/status on this platform: %v", err)
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		line := sc.Text()
+		if !strings.HasPrefix(line, "VmRSS:") {
+			continue
+		}
+		fields := strings.Fields(line)
+		if len(fields) < 2 {
+			t.Fatalf("unparsable VmRSS line %q", line)
+		}
+		kb, err := strconv.Atoi(fields[1])
+		if err != nil {
+			t.Fatalf("VmRSS %q: %v", fields[1], err)
+		}
+		return kb
+	}
+	t.Fatal("no VmRSS in /proc/self/status")
+	return 0
+}

From 1a6c5d9e187e962f8e4023928dada62f4c7e828f Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 07:29:27 -0400
Subject: [PATCH 48/51] =?UTF-8?q?docs:=20MULTI=5FTENANT.md,=20and=20PROGRE?=
 =?UTF-8?q?SS=20closes=20boundaries=201=E2=80=937?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The operator-facing description of the mode: what it requires (Postgres, the two roles,
the paired DSNs), the three-layer isolation model and the one rule about the platform
handle, the route classes, the platform API contract as settled, the SSO hand-off, the
export/import/erasure semantics including the DEK fingerprint rule, the vendor-webhook
resolve-then-verify order, what is deliberately NOT per tenant, the checklist and the
measured cost (34.6 KB per tenant over 200 workspaces).

PROGRESS.md records the B7 gate lines in one place and marks boundaries 1–7 complete.
---
 PROGRESS.md          |  26 +++++
 docs/MULTI_TENANT.md | 265 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 291 insertions(+)
 create mode 100644 docs/MULTI_TENANT.md

diff --git a/PROGRESS.md b/PROGRESS.md
index 5e79585..241d83a 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -2176,6 +2176,32 @@ what says the `appDB` change did not move anything else.
 
 ---
 
+# Boundaries 1–7 — COMPLETE. Phase 1 of the fork is gated
+
+B1 config + schema, B2 the two handles, B3 handler scoping and resolution, B4 per-tenant state,
+B5 the background loops, B6 the platform API + hand-off + vendor webhooks, **B7 the proof, the
+cost measurement and `docs/MULTI_TENANT.md`**.
+
+The B7 gate lines, in one place:
+
+```
+gofmt -l .                          empty
+go vet ./...                        clean
+go build ./...                      clean
+go test -count=1 ./...              rc=0 on SQLite, 30/30 packages
+PostgreSQL, per package:            internal/server rc=0, internal/handler rc=0,
+                                    internal/db rc=0, internal/worker rc=0, internal/webhook rc=0
+go test -race ./internal/server/ -run TestProof     rc=0, no data race
+
+--- PASS: TestProof_noRouteLeaksAnotherWorkspace     138 tenant routes as A, 61 answered 2xx
+--- PASS: TestProof_everyMCPToolIsScoped             10 tools, derived from tools/list
+--- PASS: TestProof_everyWorkerJobTypeIsCoveredAndScoped   4 job types, derived from two sources
+--- PASS: TestProof_unscopedQueryReturnsNothing      6 tables, both halves
+--- PASS: TestRSS_200Workspaces                      34.6 KB per tenant
+
+negative control (wrong password): internal/db FAILS with SQLSTATE 28P01 rather than skipping
+```
+
 # Boundary 6 — done. D11, D12, D13, D14 all closed
 
 | decision | state |
diff --git a/docs/MULTI_TENANT.md b/docs/MULTI_TENANT.md
new file mode 100644
index 0000000..250c74b
--- /dev/null
+++ b/docs/MULTI_TENANT.md
@@ -0,0 +1,265 @@
+# Multi-tenant mode
+
+One process, many isolated workspaces. `MULTI_TENANT` unset behaves exactly as it always has:
+SQLite and single-tenant PostgreSQL are unchanged, and every existing test passes without
+modification. That is a gate, not an aspiration.
+
+## What it is
+
+A `workspaces` table is the tenant root. Every application table carries a `workspace_id`, and
+**PostgreSQL row-level security — not the query author — is what keeps one workspace out of
+another's rows.** A query that forgets its predicate returns nothing rather than everything.
+
+The tenant of a request is resolved from the request `Host` (each workspace has its own public
+hostname) or from the credential it carries (API key, session, OAuth token, manage token, invite,
+magic link), and every route says which of the two it uses.
+
+## What it requires
+
+- **PostgreSQL.** SQLite has no row-level security, so there is nothing to express the isolation
+  with. Startup refuses `MULTI_TENANT` without a `postgres://` DSN.
+- **Two roles, two DSNs.**
+
+  | variable | role | used for |
+  |---|---|---|
+  | `DATABASE_URL` | application: `NOBYPASSRLS`, owns no table in the schema | every request |
+  | `DATABASE_ADMIN_URL` | platform: schema owner, `BYPASSRLS` | migrations, RLS setup, cross-tenant reads, the worker's claim loop, the platform API |
+
+  ⛔ **The two must not be the same role.** One role means the application owns the tables and
+  every policy is inert against it — and nothing breaks: every request works, and it can also read
+  every other workspace. That is the misconfiguration hardest to notice, so startup refuses it
+  outright, along with an application role that is a superuser, has `BYPASSRLS`, or owns any table
+  (`VerifyRoles`). The platform role is checked to genuinely bypass, because a platform role that
+  does not silently does no background work at all.
+- **Demo mode off.** Demo mode periodically wipes the database, which here is every tenant's data.
+  The two are mutually exclusive and startup refuses both.
+
+## Environment
+
+| key | meaning |
+|---|---|
+| `MULTI_TENANT` | any non-empty value turns the mode on |
+| `DATABASE_URL` / `DATABASE_ADMIN_URL` | the pair above |
+| `CALNODE_PLATFORM_TOKEN` | bearer for `/v1/platform/*`. Unset ⇒ those routes 404 |
+| `CALNODE_SSO_SHARED_SECRET` | HMAC key for the session hand-off. **Required** if Google or Microsoft login is configured: the callbacks hand off through it |
+| `TRUSTED_PROXY_CIDRS` | networks whose forwarded headers are believed. Unset behind a proxy makes each workspace a single rate-limit bucket |
+| `CALNODE_ENCRYPTION_KEY` | as before, and it must travel with any workspace moved between instances |
+| `BASE_URL` | the identity host (below) |
+| `PUBLIC_BASE_URL` | **ignored**; each workspace's `public_host` replaces it |
+
+## The isolation model
+
+Three layers, and each catches what the others cannot.
+
+1. **Row-level security.** Every tenant table has `ENABLE ROW LEVEL SECURITY` and one policy
+   comparing `workspace_id` to `current_setting('app.workspace_id', true)`. An unset or empty
+   setting matches no row, so an unbound statement is silently empty rather than silently global.
+   ⚠️ `FORCE ROW LEVEL SECURITY` is deliberately **not** used: it would apply the policy to the
+   table owner too, and in single-tenant mode the ordinary DSN *is* the owner — every existing
+   deployment whose DSN is not a superuser would go blind. `ENABLE` alone already isolates a
+   non-owner role, which is what the application role is.
+2. **Per-statement binding.** A handle from `OpenPair` carries a workspace. Before each statement
+   it takes a pooled connection, runs `SELECT set_config('app.workspace_id', $1, false)`, runs the
+   statement there, and releases the connection when the statement finishes. Nothing is pinned
+   between statements, so a handle is safe to copy into a goroutine that outlives its request.
+   ⛔ `Prepare` is refused on a bound handle: a prepared statement is re-prepared on whatever
+   connection the pool hands it, which would run unbound — silently empty rather than an error.
+3. **Explicit predicates where there is no policy.** Four tables are exempt because they are not
+   per tenant: `workspaces`, `crypto_keystore`, `goose_db_version`, `oauth_clients`, plus
+   `sso_nonces` (a token id is global — the question "has this token been spent" must not depend on
+   which workspace it names). Anything reading those, and everything on the platform handle, names
+   its own `workspace_id` in every statement, because there is no policy behind it.
+
+### The platform handle, and the one rule about it
+
+The platform handle bypasses the policies. Two consequences that have each caused a real bug here:
+
+- ⛔ **Every INSERT through it must name `workspace_id`.** It binds the empty string, so an unnamed
+  column resolves to `''` and the row fails its foreign key. A route that writes on the platform
+  handle and omits the column does not silently misfile the row — it fails — but it fails at the
+  database, far from the omission.
+- ⛔ **A tenant-scoped handle must be derived from the APPLICATION handle, never from the platform
+  one.** Binding a workspace onto a bypassing role produces a handle that *names* a tenant without
+  being *confined* to it: `WHERE id = 1` then matches every workspace's row and returns an
+  arbitrary one. Reads are the failure mode, and they are silent.
+
+### Reads that must not be bound
+
+**A read whose job is to discover the tenant cannot be bound to it.** Credential lookups —
+`api_keys`, `sessions`, OAuth bearer tokens — run on the platform handle and select the user's
+`workspace_id` alongside. This is why those uniques stay global while `users(workspace_id, email)`,
+`event_types(workspace_id, slug)` and `teams(workspace_id, slug)` become composite.
+
+## Route classification
+
+Every registration declares its class, and a source-scanning test fails on one that does not:
+
+| class | tenant from | examples |
+|---|---|---|
+| host-scoped | `Host` → `workspaces.public_host` | the booking pages, public event-type reads, `POST /v1/bookings`, `/manage/{token}`, `/admin/*` |
+| credential-scoped | the verified caller | the whole authenticated API |
+| platform | nothing, on purpose | `/healthz`, `/readyz`, `/version`, `/metrics`, `/.well-known/*`, `/oauth/*`, `/mcp`, `/v1/platform/*`, the OAuth login callbacks, the vendor webhooks |
+
+An unrecognised host is a **404**, never a fallback to a default tenant: falling back would serve
+one tenant's booking page on any domain pointed at the instance. A credential that resolves
+workspace A on workspace B's host is **403 `{"error":"workspace mismatch"}`**. A suspended
+workspace answers **503** with `Retry-After` on its public and admin surfaces.
+
+## The platform API
+
+Identity host, `Authorization: Bearer $CALNODE_PLATFORM_TOKEN`, constant-time compare. With the
+token unset — or on a single-tenant instance — every route **404s**, so a prober cannot tell a
+control plane from an instance that has none. A wrong token is 401.
+
+### `POST /v1/platform/workspaces` → 201
+
+```json
+{
+  "id": "acme", "slug": "acme", "public_host": "book.acme.example", "region": "us",
+  "owner_email": "owner@acme.example", "owner_name": "Owner", "owner_timezone": "America/Toronto",
+  "defaults": {
+    "embed_allowed_origins": ["https://acme.example"],
+    "webhook": { "url": "https://hooks.acme.example/in", "secret": "<optional hex>",
+                 "fields": ["booking_id", "start_at"] },
+    "event_type": { "slug": "intro", "name": "Intro call", "duration_minutes": 30,
+                    "min_notice_minutes": 60, "max_future_days": 60,
+                    "availability": [{ "day_of_week": 1, "start_time": "09:00", "end_time": "17:00" }] },
+    "livekit_url": "...", "livekit_api_key": "...", "livekit_api_secret": "...",
+    "stt_base_url": "...",
+    "smtp": { "host": "...", "port": "587", "user": "...", "pass": "...",
+              "tls": true, "starttls": false, "from": "...", "from_name": "..." },
+    "llm": { "endpoint": "...", "model": "...", "api_key": "...", "enabled": true,
+             "extra_instructions": "..." }
+  }
+}
+```
+
+Response: `{"api_key": "cno_…", "webhook_secret": "…"}` — **shown once**. One transaction creates
+the workspace row, its `server_settings` row (`id = 1` per workspace, so existing `WHERE id = 1`
+reads need no change), the owner (with `iana_timezone = owner_timezone`, because availability is
+local `HH:MM` and defaulting the zone would move the workspace's hours), the first API key, the
+webhook subscribed to **every** event the codebase emits, and the default event type with its
+availability. Either the tenant exists complete or it does not exist.
+
+`day_of_week` is 0 = Sunday. A duplicate `id`, `slug` or `public_host` is 409, and the losing
+attempt leaves nothing behind.
+
+### The rest
+
+| route | notes |
+|---|---|
+| `GET /v1/platform/workspaces/{id}` | the row: `id, slug, public_host, region, status, created_at, updated_at` |
+| `PATCH …/{id}` | `public_host`, `status` (`active`\|`suspended`), `slug`. Nothing else: the id is referenced by every tenant row and the region is where the data physically is |
+| `DELETE …/{id}` | cascades every tenant table; responds `{"recording_object_keys": [...]}` because objects in storage cannot cascade and deleting them is the caller's job |
+| `POST …/{id}/export` | one JSON document, tables in replay order |
+| `POST …/{id}/import` | 409 unless the workspace is empty |
+| `DELETE …/{id}/attendees?email=` | erasure, counts per table |
+
+## The SSO hand-off
+
+The identity host cannot set a cookie for a tenant's domain, so after a Google or Microsoft login
+the callback mints a short-lived token and redirects to the workspace's own host.
+
+`GET https://<public_host>/v1/auth/sso?token=<compact HS256 JWS>[&next=/path]`
+
+Claims: `iss`, `aud`, `sub` (email), `name`, `role` (`owner`\|`admin`\|`member`), `iat`, `exp`,
+`jti`, `wid`. Verified with the shared secret; only HS256 is accepted, checked before the signature
+is looked at.
+
+- `exp - iat` ≤ 60 s, 30 s of clock skew allowed either way. The mint side uses 30 s.
+- `jti` is claimed in `sso_nonces` **before** the session is created, so a replay inside the
+  validity window loses on the primary key.
+- ⛔ **The workspace comes from the HOST, and `wid` is checked against it.** Resolving from `wid`
+  alone would let a token for workspace A, presented on B's host, create A's session on B's domain
+  — a good signature, a resolvable `wid` and a matching audience, and the wrong outcome. A mismatch
+  is 403.
+- `aud` must equal `https://<that workspace's public_host>`, with no trailing slash.
+- The user is created or resolved **in that workspace**, with `workspace_id` named, and the session
+  row carries it too — every later request runs on a bound handle that could otherwise neither read
+  nor delete it.
+- `role` from the token applies only to a user it creates; an existing user's role is never
+  rewritten by a sign-in.
+
+The login start carries the workspace in the state **cookie** (`<nonce>|<workspace_id>`) and sends
+only the nonce to the provider. The nonce is compared, the workspace is read: a visitor can rewrite
+the query parameter and achieve a failed login, and the value that selects the tenant never left
+the server.
+
+## Export, import, erasure
+
+**Export** is one JSON document: `format_version`, `exported_at`, the workspace row, a
+`dek_fingerprint`, and `tables` as an **ordered array** — parents before children, because import
+replays it in the order it receives. Secrets and API-key hashes travel **verbatim**, because a
+tenant whose keys and manage links stopped working on migration has not been migrated. The document
+is therefore as sensitive as the database.
+
+The table list is checked against the schema's own tenant-table list at request time, so a table
+added by a later migration cannot be silently absent from every backup.
+
+**Import** refuses (409) unless the workspace is empty, runs in one transaction, and **forces
+`workspace_id` to the id in the URL** — the document's own value is discarded, or an export of any
+workspace would be a way to write into any other.
+
+⚠️ Row ids are global primary keys, so **import is a move, not a copy**: replaying a document into a
+second workspace while the first still holds its rows collides on the primary key. The supported
+sequence is export → delete → import, normally into another instance.
+
+⛔ **The DEK fingerprint rule.** `crypto_keystore` holds one wrapped data key per **process**, not
+per workspace, so the key itself does not travel — an export of one tenant containing the key that
+decrypts every tenant would be the opposite of isolation. Instead the document carries a SHA-256 of
+the *already-encrypted* wrapped key, and **import refuses 409 when it differs**. Without that
+check the rows import perfectly and then every secret in them fails at first use, one integration
+at a time, long after anyone is watching. Moving a workspace means moving
+`CALNODE_ENCRYPTION_KEY` with it.
+
+**Erasure** (`DELETE …/attendees?email=`) removes the attendee rows for that address in that
+workspace and returns counts. It cancels nothing: the bookings, the host's calendar and the other
+attendees' records are not the erased person's data. Answers are keyed `(booking_id, question_id)`
+and carry no attendee, so they are erased only for bookings where that person was the **only**
+attendee — with anyone else on the booking, deleting them would erase a third party's data.
+
+## Vendor webhooks
+
+LiveKit and Stripe call in with their own signature and no tenant Host, so both routes are platform
+routes that resolve the workspace from **our** row: the egress id or room on a recordings row, the
+booking a room name encodes, or `bookings.stripe_session_id`. No resolver consults a `workspace_id`
+in a vendor payload. An event no row owns is **2xx and ignored** — a 4xx would make the vendor retry
+for days and no retry can make the row exist.
+
+⚠️ In multi-tenant mode the resolve necessarily precedes the signature check, because the signing
+credentials are per workspace: there is no instance-wide secret to verify against, and verifying
+against an arbitrary tenant's is not verification. Nothing is written before the signature verifies
+and nothing is disclosed either way. Single-tenant keeps the original verify-then-act order.
+
+## What is NOT per tenant
+
+| thing | why, and what it costs |
+|---|---|
+| **the data encryption key** | one wrapped DEK per process. An operator who can read the database can decrypt every workspace, and a workspace cannot move between instances without its key. The import fingerprint check makes the coupling loud rather than silent |
+| **the OAuth app credentials** | Google/Microsoft client id and secret identify the *instance* to the provider, not the tenant |
+| **`embed_allowed_origins`** | stored per workspace and **not yet read**: the CORS check still uses the process-wide value, so every tenant shares one embed allowlist |
+| **`stt_base_url`** | same: stored, not yet read, so every tenant shares one speech-to-text host |
+| **rate-limit windows** | keyed `(workspace, client IP)`, but the counters live in one process |
+| **retention sweeps** | expired sessions, tokens and deliveries are purged globally: they are retention rules, not tenant logic |
+
+## Operator checklist
+
+1. PostgreSQL 16+ with two roles: an owner (`BYPASSRLS`) and an application role (`NOBYPASSRLS`,
+   owning nothing, granted DML on the schema's tables).
+2. Set `MULTI_TENANT`, both DSNs, `CALNODE_PLATFORM_TOKEN`, `CALNODE_SSO_SHARED_SECRET` (if social
+   login is configured), `TRUSTED_PROXY_CIDRS` (if behind a proxy), and `BASE_URL`.
+3. Start. Boot order is: migrate on the platform handle → enable RLS → suspend the seeded `default`
+   workspace → verify both roles. The first, second and fourth are fatal; the third is logged.
+4. Point DNS for each tenant's `public_host` at the instance and terminate TLS for it.
+5. Provision each workspace through `POST /v1/platform/workspaces`; store the `api_key` and
+   `webhook_secret` from the response, which are shown once.
+6. Verify with a request to each tenant's own host, and confirm an unknown host 404s.
+7. Before moving a workspace between instances, move `CALNODE_ENCRYPTION_KEY` too, or import will
+   refuse the document.
+
+## Cost
+
+Measured with 200 workspaces provisioned through the API in one process: RSS 28.9 MB → 35.9 MB,
+i.e. **~35 KB per tenant**, with the connection pool unchanged at one connection per role.
+`ForWorkspace` returns a value over a shared pool, so tenants cost cache entries and rows, not
+connections.

From 85550e8a265afc678a3feaebf33e5ebf333e480c Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 07:35:10 -0400
Subject: [PATCH 49/51] handler, server: read the two per-tenant settings
 columns instead of the process values (D7)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Migration 00062 gave server_settings `embed_allowed_origins` and `stt_base_url`, the platform
API has filled them since, and nothing read them: every workspace on a multi-tenant instance
shared the process-wide EMBED_ALLOWED_ORIGINS and STT_BASE_URL. The first is an isolation gap
(tenant A's embed origins were honoured on tenant B's booking endpoints), the second a
routing one (an EU tenant's recordings went to whichever host the process booted with).

Both now go through a per-workspace settingsCache built from the bound handle
(internal/handler/tenant_settings.go):

- The CORS wrapper is PublicCORSFor(originsFor), with PublicCORS(list) kept as the
  single-tenant case. In multi-tenant mode server.New passes h.EmbedOriginsFor, which
  resolves the request host to its workspace on the platform handle and answers that
  workspace's list. An unknown host answers known=false and the middleware then sends NO
  Access-Control-Allow-Origin at all — never `*`, because "no workspace" must not read as
  "any origin". An empty per-tenant list keeps the single-tenant meaning (any origin).
- sttBaseURL() gains one rung above its existing ladder: the workspace column when
  multi-tenant and non-empty, then STT_BASE_URL, then the provider default.

Single-tenant mode consults neither column, so its behaviour is byte-identical; the cors
unit tests it already had pass unchanged through the new constructor.

Negative control, the multi-tenant branch in server.New disabled: the end-to-end test
answers `200 "*"` on the tenant's own origin, on a foreign origin and on an unknown host,
which is the shared-allowlist bug made visible.
---
 PROGRESS.md                              | 59 +++++++---------
 docs/MULTI_TENANT.md                     |  9 ++-
 internal/handler/export_internal_test.go |  6 ++
 internal/handler/handler.go              | 30 +++++---
 internal/handler/shared.go               |  3 +
 internal/handler/tenant_settings.go      | 89 ++++++++++++++++++++++++
 internal/handler/tenant_settings_test.go | 79 +++++++++++++++++++++
 internal/server/cors_tenant_test.go      | 45 ++++++++++++
 internal/server/cors_test.go             | 54 ++++++++++++++
 internal/server/middleware.go            | 38 +++++++---
 internal/server/server.go                |  8 +++
 11 files changed, 367 insertions(+), 53 deletions(-)
 create mode 100644 internal/handler/tenant_settings.go
 create mode 100644 internal/handler/tenant_settings_test.go
 create mode 100644 internal/server/cors_tenant_test.go

diff --git a/PROGRESS.md b/PROGRESS.md
index 241d83a..61cef42 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -1771,34 +1771,31 @@ of this file); the vendor webhooks resolving their workspace from the row they n
 already done (B1's `config.Validate` refuses `MULTI_TENANT` with `DEMO_MODE`) and D14
 landed with the platform-hooks merge.
 
-### ⛔ OPEN ITEM: `embed_allowed_origins` and `stt_base_url` are written and never read
-
-Migration 00062 added both columns and the platform API fills them, so a provisioned
-workspace no longer loses what the caller sent. **Nothing reads them.** The embed CORS
-check still resolves `config.EmbedAllowedOrigins` and the notetaker still resolves
-`config.STTBaseURL`, both of which are one process-wide value — so on a multi-tenant
-instance **every tenant currently shares one embed allowlist and one STT host**, whatever
-their row says. That is a silent wrong answer in the making: an operator who sets a
-per-tenant allowlist through the platform API will believe it is in force.
-
-Wiring the readers is **D7 work**, not a one-line lookup, and that is why it is not done
-here: each has to go through the per-workspace settings cache (`shared.<kind>.get(wsID)`,
-`internal/handler/tenantcache.go`) so the value is built from that workspace's
-`server_settings` row and invalidated when the workspace saves. Two specifics for whoever
-picks it up:
-
-- **`embed_allowed_origins`** is consumed by the CORS wrapper on the embed and public
-  booking routes, which runs BEFORE the handler and therefore before any per-request
-  workspace exists on the `Scoped` path. It needs the same treatment `rateLimitKey` got for
-  D14: resolve from the request Host without a database read, or move the check inside the
-  handler where the bound handle is available. The second is cleaner and is a behaviour
-  change to think about, since today a disallowed origin is refused before any handler runs.
-- **`stt_base_url`** is read by the notetaker job, which already runs bound to its
-  workspace (`workspaceForJob`, B5), so it is the easier of the two: a settings read on the
-  bound handle, with `config.STTBaseURL` as the fallback when the column is `''`.
-
-Until both are wired, a multi-tenant deployment should keep `EMBED_ALLOWED_ORIGINS` and
-`STT_BASE_URL` set to values that are correct for **every** tenant on the instance.
+### `embed_allowed_origins` and `stt_base_url` are READ — the D7 reader wiring, done
+
+Migration 00062 added both columns and the platform API filled them; until this commit nothing
+read them, so a multi-tenant instance shared one embed allowlist and one STT host across every
+tenant whatever its row said. Now `internal/handler/tenant_settings.go` reads both through the
+bound handle into a per-workspace `settingsCache` (the same `tenantCache` the vendor clients use):
+
+- **`embed_allowed_origins`**: the CORS wrapper became `server.PublicCORSFor(originsFor)`, with
+  `PublicCORS(list)` as the single-tenant special case. In multi-tenant mode `server.New` passes
+  `h.EmbedOriginsFor`, which resolves the request host to its workspace on the platform handle
+  (one indexed read, the route's own 404 unchanged) and answers that workspace's list. An unknown
+  host answers known=false, which the middleware turns into NO allow-origin header — never `*`.
+  An empty per-tenant list keeps the single-tenant meaning: any origin. `EMBED_ALLOWED_ORIGINS`
+  is not consulted in this mode. The 'move the check inside the handler' alternative was not
+  taken: a disallowed origin is still refused before any handler runs, exactly as today.
+- **`stt_base_url`**: `sttBaseURL()` gained one rung on top of its existing ladder — the
+  workspace's column when multi-tenant and non-empty, then `STT_BASE_URL`, then the provider
+  default. The notetaker job already runs bound (`workspaceForJob`, B5), so it needed no change.
+
+Tests: `TestTenantSettings_perWorkspaceReaders` (handler, PG: two workspaces via the platform API;
+A's own STT host and origins, B's fall-through to the process value and then the default, an
+unknown host resolving to no tenant), `TestPublicCORSFor_*` (middleware unit, both engines) and
+`TestTenancy_embedOriginsArePerWorkspace` (end to end through the real mux). Negative control,
+the multi-tenant branch in `server.New` disabled: the end-to-end test fails with `200 "*"` on
+acme's own origin, on a foreign origin, and on an unknown host — the shared-allowlist bug, seen.
 
 ### ⚠️ A pre-existing upstream race, fixed here (upstream-first PR candidate)
 
@@ -2267,10 +2264,8 @@ connections.
    without moving the key. Import's `dek_fingerprint` check makes the coupling loud rather than
    silent, which is as far as this packet goes. Making it per tenant changes D3, the schema
    (`crypto_keystore` gains `workspace_id`), and the export format.
-2. ⚠️ **The D7 reader wiring for `embed_allowed_origins` and `stt_base_url`.** Both columns are
-   written by the platform API and read by nothing, so a multi-tenant instance still shares one
-   embed allowlist and one STT host across tenants. Details and the two specifics are in the
-   open item above.
+2. ✅ **The D7 reader wiring for `embed_allowed_origins` and `stt_base_url`** — done after
+   B7, see the section above. One known follow-up remains in this list.
 
 ⚠️ This file carried a plan for the SSO mint half between the merge and part three above.
 It is now BUILT, and part three is the record; the plan is deleted rather than annotated,
diff --git a/docs/MULTI_TENANT.md b/docs/MULTI_TENANT.md
index 250c74b..926639e 100644
--- a/docs/MULTI_TENANT.md
+++ b/docs/MULTI_TENANT.md
@@ -141,6 +141,13 @@ local `HH:MM` and defaulting the zone would move the workspace's hours), the fir
 webhook subscribed to **every** event the codebase emits, and the default event type with its
 availability. Either the tenant exists complete or it does not exist.
 
+`defaults.embed_allowed_origins` and `defaults.stt_base_url` are per workspace and are READ: the public
+booking endpoints' CORS allowlist is the one stored for the workspace whose host the request names (an
+empty list means any origin, and a host no workspace owns gets no `Access-Control-Allow-Origin` at all,
+never `*`), and the notetaker sends that workspace's recordings to its own speech-to-text host, falling
+through to `STT_BASE_URL` and then the provider default when the column is empty. In this mode
+`EMBED_ALLOWED_ORIGINS` is not consulted.
+
 `day_of_week` is 0 = Sunday. A duplicate `id`, `slug` or `public_host` is 409, and the losing
 attempt leaves nothing behind.
 
@@ -237,8 +244,6 @@ and nothing is disclosed either way. Single-tenant keeps the original verify-the
 |---|---|
 | **the data encryption key** | one wrapped DEK per process. An operator who can read the database can decrypt every workspace, and a workspace cannot move between instances without its key. The import fingerprint check makes the coupling loud rather than silent |
 | **the OAuth app credentials** | Google/Microsoft client id and secret identify the *instance* to the provider, not the tenant |
-| **`embed_allowed_origins`** | stored per workspace and **not yet read**: the CORS check still uses the process-wide value, so every tenant shares one embed allowlist |
-| **`stt_base_url`** | same: stored, not yet read, so every tenant shares one speech-to-text host |
 | **rate-limit windows** | keyed `(workspace, client IP)`, but the counters live in one process |
 | **retention sweeps** | expired sessions, tokens and deliveries are purged globally: they are retention rules, not tenant logic |
 
diff --git a/internal/handler/export_internal_test.go b/internal/handler/export_internal_test.go
index 58ded96..b46ee82 100644
--- a/internal/handler/export_internal_test.go
+++ b/internal/handler/export_internal_test.go
@@ -72,3 +72,9 @@ func StripeEventWorkspaceForTest(h *Handler, sessionID, metadataBookingID string
 	})(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/v1/stripe/webhook", nil))
 	return id, found
 }
+
+// STTBaseURLForWorkspaceForTest answers what the notetaker would use for one
+// workspace: the scoped handler's resolution, per-tenant column first.
+func STTBaseURLForWorkspaceForTest(h *Handler, workspaceID string) string {
+	return h.forWorkspace(&Workspace{ID: workspaceID}).sttBaseURL()
+}
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
index 89f3b70..af09026 100644
--- a/internal/handler/handler.go
+++ b/internal/handler/handler.go
@@ -178,15 +178,16 @@ func New(database *db.DB, logger *slog.Logger) *Handler {
 	whs, _ := webhook.New(database, "") // ephemeral key when no encryption key configured
 	return &Handler{
 		shared: &shared{
-			logger:       logger,
-			calNudge:     make(chan struct{}, 1),
-			mailerCache:  newTenantCache[mailer.Mailer](),
-			calCache:     newTenantCache[*calendar.Service](),
-			llmCache:     newTenantCache[*llm.Client](),
-			zoomCache:    newTenantCache[*zoom.Client](),
-			stripeCache:  newTenantCache[*stripe.Client](),
-			livekitCache: newTenantCache[*livekit.Client](),
-			appDB:        database,
+			logger:        logger,
+			calNudge:      make(chan struct{}, 1),
+			mailerCache:   newTenantCache[mailer.Mailer](),
+			calCache:      newTenantCache[*calendar.Service](),
+			llmCache:      newTenantCache[*llm.Client](),
+			zoomCache:     newTenantCache[*zoom.Client](),
+			stripeCache:   newTenantCache[*stripe.Client](),
+			livekitCache:  newTenantCache[*livekit.Client](),
+			settingsCache: newTenantCache[tenantSettings](),
+			appDB:         database,
 		},
 		db:         database,
 		ws:         DefaultWorkspace,
@@ -252,7 +253,18 @@ func (h *Handler) SetSTTBaseURL(url string) {
 // sttBaseURL returns the effective endpoint host. Resolved on read rather than at set
 // time so a Handler built without SetSTTBaseURL (every test) still reports the real
 // default rather than an empty string.
+//
+// In multi-tenant mode a workspace's own `stt_base_url` (written by the platform
+// API, see tenant_settings.go) comes first, so an EU tenant's recordings go to the
+// EU speech-to-text host regardless of what the process was booted with. Empty
+// falls through to the process value, then the provider default — the same ladder
+// single-tenant mode has always had, with one rung added on top of it.
 func (h *Handler) sttBaseURL() string {
+	if h.multiTenant && h.ws != nil {
+		if v := h.tenantSettings().sttBaseURL; v != "" {
+			return v
+		}
+	}
 	if h.sttBaseURLCfg != "" {
 		return h.sttBaseURLCfg
 	}
diff --git a/internal/handler/shared.go b/internal/handler/shared.go
index fa69759..45a6c4d 100644
--- a/internal/handler/shared.go
+++ b/internal/handler/shared.go
@@ -44,6 +44,9 @@ type shared struct {
 	zoomCache    *tenantCache[*zoom.Client]
 	stripeCache  *tenantCache[*stripe.Client]
 	livekitCache *tenantCache[*livekit.Client]
+	// settingsCache holds the two multi-tenant-only server_settings columns
+	// (embed origins, STT host) per workspace; see tenant_settings.go.
+	settingsCache *tenantCache[tenantSettings]
 
 	// calBase is the PLATFORM-level provider registry: one Service holding the
 	// instance's Google/Microsoft OAuth apps and the CalDAV client, per D7. It is
diff --git a/internal/handler/tenant_settings.go b/internal/handler/tenant_settings.go
new file mode 100644
index 0000000..a4f2dd6
--- /dev/null
+++ b/internal/handler/tenant_settings.go
@@ -0,0 +1,89 @@
+package handler
+
+import (
+	"database/sql"
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/calnode/calnode/internal/db"
+)
+
+// tenantSettings holds the two server_settings columns that exist only for
+// multi-tenant deployments (migration 00062): the origins allowed to embed this
+// workspace's booking page, and the speech-to-text host its notetaker uses.
+//
+// Both were written by the platform API from the day the columns existed and read
+// by nothing, so every tenant shared the process-wide EMBED_ALLOWED_ORIGINS and
+// STT_BASE_URL. That is a real isolation gap for the CORS allowlist (tenant A's
+// embed origins were honoured on tenant B's booking page) and a routing gap for
+// STT (an EU tenant's recordings went to whichever host the process was booted
+// with). These readers close both.
+//
+// Single-tenant mode does not consult either column: the process-wide values keep
+// their meaning exactly, and the columns are ” there anyway because only the
+// platform API writes them.
+type tenantSettings struct {
+	embedOrigins []string
+	sttBaseURL   string
+}
+
+// loadTenantSettings reads the two columns through a handle bound to the
+// workspace, so the row is that workspace's own. A missing row (a workspace the
+// platform API did not create, or a test that seeded no settings) is the same as
+// empty values, not an error: empty is the documented default for both.
+func loadTenantSettings(d *db.DB) (tenantSettings, error) {
+	var origins, stt string
+	err := d.QueryRow(`SELECT embed_allowed_origins, stt_base_url FROM server_settings WHERE id = 1`).
+		Scan(&origins, &stt)
+	if errors.Is(err, sql.ErrNoRows) {
+		return tenantSettings{}, nil
+	}
+	if err != nil {
+		return tenantSettings{}, err
+	}
+	var list []string
+	for _, o := range strings.Split(origins, ",") {
+		if o = strings.TrimSpace(o); o != "" {
+			list = append(list, o)
+		}
+	}
+	return tenantSettings{embedOrigins: list, sttBaseURL: strings.TrimSpace(stt)}, nil
+}
+
+// tenantSettings returns this workspace's per-tenant settings, cached per
+// workspace like the vendor clients. A read error is logged and answers as
+// empty, because both consumers have a safe empty: the CORS check falls back to
+// "no origin is allowed" (see EmbedOriginsFor) and the notetaker falls back to
+// the process default host.
+func (h *Handler) tenantSettings() tenantSettings {
+	return h.settingsCache.get(h.cacheKey(), func() tenantSettings {
+		s, err := loadTenantSettings(h.db)
+		if err != nil {
+			h.logger.Warn("settings: could not load per-tenant settings", "workspace", h.cacheKey(), "error", err)
+			return tenantSettings{}
+		}
+		return s
+	})
+}
+
+// EmbedOriginsFor is the multi-tenant origin resolver for the public CORS
+// middleware: the workspace is the one whose public host the request names, and
+// the allowlist is that workspace's own.
+//
+// The middleware runs BEFORE the route's own host resolution, so this is a second
+// lookup of the same host on the platform handle; it is one indexed read and the
+// route's 404 for an unknown host is unchanged. For an unknown host the resolver
+// answers known=false, which the middleware turns into NO Access-Control-Allow-Origin
+// at all — never `*`, because "no workspace" must not read as "any origin".
+//
+// An EMPTY per-tenant list keeps the single-tenant meaning: any origin. That is
+// what an operator who never set the field expects, and it is what the platform
+// API stores when the caller passes none.
+func (h *Handler) EmbedOriginsFor(r *http.Request) ([]string, bool) {
+	ws, err := h.workspaceByHost(r.Context(), r.Host)
+	if err != nil {
+		return nil, false
+	}
+	return h.forWorkspace(ws).tenantSettings().embedOrigins, true
+}
diff --git a/internal/handler/tenant_settings_test.go b/internal/handler/tenant_settings_test.go
new file mode 100644
index 0000000..952e5f7
--- /dev/null
+++ b/internal/handler/tenant_settings_test.go
@@ -0,0 +1,79 @@
+package handler_test
+
+import (
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"reflect"
+	"testing"
+
+	"github.com/calnode/calnode/internal/dbtest"
+	"github.com/calnode/calnode/internal/handler"
+	"github.com/calnode/calnode/internal/stt"
+)
+
+// The two multi-tenant-only settings columns were written by the platform API and
+// read by nothing (D7 follow-up). These pin the readers: each workspace gets its
+// OWN embed allowlist and STT host, an empty column falls through exactly as the
+// single-tenant ladder does, and an unknown host resolves to no tenant at all.
+func TestTenantSettings_perWorkspaceReaders(t *testing.T) {
+	app, _ := dbtest.RequireTenantPair(t)
+
+	h := handler.New(app, slog.New(slog.DiscardHandler))
+	h.SetMultiTenant(true)
+	h.SetBaseURL("https://cal.example.test")
+	h.SetPlatformToken(platformToken)
+	h.SetEncKey(platformTestEncKey)
+	h.SetSTTBaseURL("https://stt-process.example")
+	create := h.Platform((*handler.Handler).CreateWorkspace)
+
+	const hostA, hostB = "book.acme.example", "book.globex.example"
+
+	bodyA := platformCreateBody("acme", hostA)
+	bodyA["defaults"].(map[string]any)["embed_allowed_origins"] = []string{"https://embed-acme.example", "https://www.acme.example/"}
+	bodyA["defaults"].(map[string]any)["stt_base_url"] = "https://stt-eu.example"
+	if rec := doPlatform(t, create, http.MethodPost, "/v1/platform/workspaces", bodyA, platformToken); rec.Code != http.StatusCreated {
+		t.Fatalf("create acme: %d %s", rec.Code, rec.Body.String())
+	}
+	bodyB := platformCreateBody("globex", hostB)
+	bodyB["defaults"].(map[string]any)["embed_allowed_origins"] = []string{}
+	delete(bodyB["defaults"].(map[string]any), "stt_base_url")
+	if rec := doPlatform(t, create, http.MethodPost, "/v1/platform/workspaces", bodyB, platformToken); rec.Code != http.StatusCreated {
+		t.Fatalf("create globex: %d %s", rec.Code, rec.Body.String())
+	}
+
+	// STT: A's own host wins; B, with the column empty, falls through to the
+	// process value, which is the rung single-tenant mode has always had.
+	if got := handler.STTBaseURLForWorkspaceForTest(h, "acme"); got != "https://stt-eu.example" {
+		t.Errorf("acme stt = %q; want its own column", got)
+	}
+	if got := handler.STTBaseURLForWorkspaceForTest(h, "globex"); got != "https://stt-process.example" {
+		t.Errorf("globex stt = %q; want the process value", got)
+	}
+	h.SetSTTBaseURL("")
+	// The cache holds the column, not the resolution, so clearing the process
+	// value is visible without a restart: B now lands on the provider default.
+	if got := handler.STTBaseURLForWorkspaceForTest(h, "globex"); got != stt.DefaultBaseURL {
+		t.Errorf("globex stt with no process value = %q; want %q", got, stt.DefaultBaseURL)
+	}
+	if got := handler.STTBaseURLForWorkspaceForTest(h, "acme"); got != "https://stt-eu.example" {
+		t.Errorf("acme stt after clearing the process value = %q; want its own column still", got)
+	}
+
+	// Embed origins: resolved from the request HOST, and an unknown host is
+	// "no tenant", never "any origin".
+	originsFor := func(host string) ([]string, bool) {
+		r := httptest.NewRequest(http.MethodGet, "/v1/event-types/intro/public", nil)
+		r.Host = host
+		return h.EmbedOriginsFor(r)
+	}
+	if got, known := originsFor(hostA); !known || !reflect.DeepEqual(got, []string{"https://embed-acme.example", "https://www.acme.example/"}) {
+		t.Errorf("acme origins = %v, known=%v; want its own two", got, known)
+	}
+	if got, known := originsFor(hostB); !known || len(got) != 0 {
+		t.Errorf("globex origins = %v, known=%v; want known and empty (any origin)", got, known)
+	}
+	if got, known := originsFor("nobody.example"); known || got != nil {
+		t.Errorf("unknown host origins = %v, known=%v; want unknown", got, known)
+	}
+}
diff --git a/internal/server/cors_tenant_test.go b/internal/server/cors_tenant_test.go
new file mode 100644
index 0000000..cf57b87
--- /dev/null
+++ b/internal/server/cors_tenant_test.go
@@ -0,0 +1,45 @@
+package server_test
+
+import (
+	"context"
+	"net/http"
+	"testing"
+)
+
+// End to end through the real mux: the public booking endpoints honour the
+// workspace's OWN embed allowlist, chosen by the request's host, and an unknown
+// host gets no CORS header at all. Before this, EMBED_ALLOWED_ORIGINS was one
+// process-wide list, so a tenant's embed origin could call every tenant's
+// booking endpoints.
+func TestTenancy_embedOriginsArePerWorkspace(t *testing.T) {
+	f := newTenancyFixture(t)
+
+	// The fixture seeds an empty settings row; give acme an allowlist through the
+	// platform handle, naming the workspace, before the first request fills the
+	// per-workspace cache.
+	if _, err := f.plat.ExecContext(context.Background(),
+		`UPDATE server_settings SET embed_allowed_origins = ? WHERE workspace_id = ? AND id = 1`,
+		"https://embed-acme.example", "acme"); err != nil {
+		t.Fatalf("set acme embed origins: %v", err)
+	}
+
+	get := func(host, slug, origin string) (int, string) {
+		r := newRequest(t, http.MethodGet, host, "/v1/event-types/"+slug+"/public", nil)
+		r.Header.Set("Origin", origin)
+		rec := f.serve(r)
+		return rec.Code, rec.Header().Get("Access-Control-Allow-Origin")
+	}
+
+	if code, acao := get(hostA, f.a.eventSlug, "https://embed-acme.example"); code != http.StatusOK || acao != "https://embed-acme.example" {
+		t.Errorf("acme's own embed origin: %d %q; want 200 and the origin echoed", code, acao)
+	}
+	if code, acao := get(hostA, f.a.eventSlug, "https://embed-globex.example"); code != http.StatusOK || acao != "" {
+		t.Errorf("a foreign origin on acme: %d %q; want 200 with NO allow-origin", code, acao)
+	}
+	if code, acao := get(hostB, f.b.eventSlug, "https://embed-globex.example"); code != http.StatusOK || acao != "*" {
+		t.Errorf("globex with an empty allowlist: %d %q; want 200 and *", code, acao)
+	}
+	if code, acao := get("nobody.example", f.a.eventSlug, "https://embed-acme.example"); code != http.StatusNotFound || acao != "" {
+		t.Errorf("unknown host: %d %q; want 404 with NO allow-origin (never *)", code, acao)
+	}
+}
diff --git a/internal/server/cors_test.go b/internal/server/cors_test.go
index e6d8290..849cd04 100644
--- a/internal/server/cors_test.go
+++ b/internal/server/cors_test.go
@@ -67,3 +67,57 @@ func TestPublicCORS_neverAllowsCredentials(t *testing.T) {
 		t.Error("Allow-Credentials must never be set on public CORS")
 	}
 }
+
+// A resolver that knows no tenant must produce NO origin header — the middleware
+// must not fall back to `*` when there is no workspace to consult.
+func TestPublicCORSFor_unknownTenantGetsNoHeader(t *testing.T) {
+	mw := PublicCORSFor(func(*http.Request) ([]string, bool) { return nil, false })
+	rec := corsReq(t, mw, http.MethodGet, "https://customer.example")
+	if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {
+		t.Errorf("Access-Control-Allow-Origin = %q; want none for an unknown tenant", got)
+	}
+	// The preflight is still answered, so the browser gets a definite 204 rather
+	// than a hung request; it simply carries no allow-origin.
+	rec = corsReq(t, mw, http.MethodOptions, "https://customer.example")
+	if rec.Code != http.StatusNoContent {
+		t.Errorf("preflight status = %d; want 204", rec.Code)
+	}
+	if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {
+		t.Errorf("preflight Access-Control-Allow-Origin = %q; want none", got)
+	}
+}
+
+// The resolver decides per request, so two hosts can answer the same Origin
+// differently from one middleware instance.
+func TestPublicCORSFor_perRequestAllowlist(t *testing.T) {
+	mw := PublicCORSFor(func(r *http.Request) ([]string, bool) {
+		switch r.Host {
+		case "a.example":
+			return []string{"https://embed-a.example"}, true
+		case "b.example":
+			return nil, true // known tenant, empty list: any origin
+		}
+		return nil, false
+	})
+	serve := func(host, origin string) *httptest.ResponseRecorder {
+		h := mw(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusOK) })
+		req := httptest.NewRequest(http.MethodGet, "/v1/event-types/x/public", nil)
+		req.Host = host
+		req.Header.Set("Origin", origin)
+		rec := httptest.NewRecorder()
+		h(rec, req)
+		return rec
+	}
+	if got := serve("a.example", "https://embed-a.example").Header().Get("Access-Control-Allow-Origin"); got != "https://embed-a.example" {
+		t.Errorf("A's own origin: got %q; want it echoed", got)
+	}
+	if got := serve("a.example", "https://embed-b.example").Header().Get("Access-Control-Allow-Origin"); got != "" {
+		t.Errorf("a foreign origin on A: got %q; want none", got)
+	}
+	if got := serve("b.example", "https://anything.example").Header().Get("Access-Control-Allow-Origin"); got != "*" {
+		t.Errorf("B with an empty list: got %q; want *", got)
+	}
+	if got := serve("nobody.example", "https://embed-a.example").Header().Get("Access-Control-Allow-Origin"); got != "" {
+		t.Errorf("unknown host: got %q; want none", got)
+	}
+}
diff --git a/internal/server/middleware.go b/internal/server/middleware.go
index 4d71fc5..377c2ad 100644
--- a/internal/server/middleware.go
+++ b/internal/server/middleware.go
@@ -145,19 +145,37 @@ func requestOriginHost(r *http.Request) string {
 // access-control boundary (the routes are rate-limited regardless). Handles the
 // OPTIONS preflight itself (returns 204).
 func PublicCORS(allowedOrigins []string) func(http.HandlerFunc) http.HandlerFunc {
-	allowAny := len(allowedOrigins) == 0
-	allowed := make(map[string]bool, len(allowedOrigins))
-	for _, o := range allowedOrigins {
-		allowed[strings.ToLower(strings.TrimRight(o, "/"))] = true
-	}
+	return PublicCORSFor(func(*http.Request) ([]string, bool) { return allowedOrigins, true })
+}
+
+// PublicCORSFor is PublicCORS with the allowlist chosen per request. originsFor
+// answers the list that applies to this request and whether one applies at all:
+// known=false means the request names no tenant, and then NO
+// Access-Control-Allow-Origin header is sent — not `*`, because "no workspace"
+// must never read as "any origin". An empty list with known=true keeps
+// PublicCORS's meaning: any origin.
+//
+// This is what lets a multi-tenant instance honour each workspace's own
+// `embed_allowed_origins` (handler.EmbedOriginsFor) while a single-tenant instance
+// keeps one process-wide list. The preflight is answered either way; the resolver
+// only decides the origin header.
+func PublicCORSFor(originsFor func(*http.Request) ([]string, bool)) func(http.HandlerFunc) http.HandlerFunc {
 	return func(next http.HandlerFunc) http.HandlerFunc {
 		return func(w http.ResponseWriter, r *http.Request) {
 			if origin := r.Header.Get("Origin"); origin != "" {
-				if allowAny {
-					w.Header().Set("Access-Control-Allow-Origin", "*")
-				} else if allowed[strings.ToLower(strings.TrimRight(origin, "/"))] {
-					w.Header().Set("Access-Control-Allow-Origin", origin)
-					w.Header().Add("Vary", "Origin")
+				if allowedOrigins, known := originsFor(r); known {
+					if len(allowedOrigins) == 0 {
+						w.Header().Set("Access-Control-Allow-Origin", "*")
+					} else {
+						want := strings.ToLower(strings.TrimRight(origin, "/"))
+						for _, o := range allowedOrigins {
+							if strings.ToLower(strings.TrimRight(o, "/")) == want {
+								w.Header().Set("Access-Control-Allow-Origin", origin)
+								w.Header().Add("Vary", "Origin")
+								break
+							}
+						}
+					}
 				}
 			}
 			if r.Method == http.MethodOptions {
diff --git a/internal/server/server.go b/internal/server/server.go
index 53b6b7e..0973af2 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -517,6 +517,14 @@ func New(ctx context.Context, cfg *config.Config, db *db.DB, logger *slog.Logger
 	// cross-origin from a customer's site. Scoped to these unauthenticated routes
 	// only — admin/auth routes never get CORS. Default (empty allowlist) = any origin.
 	cors := PublicCORS(cfg.EmbedAllowedOrigins)
+	if cfg.MultiTenant {
+		// Per workspace: the allowlist is the one the platform API stored for the
+		// workspace whose public host the request names, and an unknown host gets
+		// no CORS header at all. EMBED_ALLOWED_ORIGINS is not consulted in this
+		// mode — one process-wide list would let tenant A's embed origins call
+		// tenant B's booking endpoints.
+		cors = PublicCORSFor(h.EmbedOriginsFor)
+	}
 
 	// Public event-type display info for the widget (name/duration/location/brand).
 	mux.HandleFunc("GET /v1/event-types/{slug}/public", cors(h.Scoped(handler.HostWorkspace, (*H).PublicEventType)))

From 11618e9d32d95767d2bf3946454ab6e208c36c3f Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 07:40:27 -0400
Subject: [PATCH 50/51] config: DATA_DIR chooses the upload directory

The upload directory (avatars, branding assets) was the literal relative "data" in
server.BuildHandler, which every deployment has been writing to since the beginning and
which a read-only container image running as an unprivileged user cannot create: the
first avatar upload fails with EACCES and nothing at boot says why.

DATA_DIR sets it, defaulting to the same relative "data", so nothing moves for anyone
who never sets it. BuildHandler repeats the fallback because tests build a Config
literal that skips Load, and an empty directory would put uploads beside the binary.
---
 docs/MULTI_TENANT.md           |  1 +
 internal/config/config.go      |  8 ++++++++
 internal/config/config_test.go | 13 +++++++++++++
 internal/server/server.go      |  9 ++++++++-
 4 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/MULTI_TENANT.md b/docs/MULTI_TENANT.md
index 926639e..1ae272d 100644
--- a/docs/MULTI_TENANT.md
+++ b/docs/MULTI_TENANT.md
@@ -46,6 +46,7 @@ magic link), and every route says which of the two it uses.
 | `CALNODE_ENCRYPTION_KEY` | as before, and it must travel with any workspace moved between instances |
 | `BASE_URL` | the identity host (below) |
 | `PUBLIC_BASE_URL` | **ignored**; each workspace's `public_host` replaces it |
+| `DATA_DIR` | where uploads (avatars, branding) are written; defaults to the relative `data`. A read-only image sets it to its mounted volume |
 
 ## The isolation model
 
diff --git a/internal/config/config.go b/internal/config/config.go
index b91ef3f..3dee93d 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -88,6 +88,13 @@ type Config struct {
 	// where audio is being sent without reading the environment of a running container.
 	STTBaseURL string
 
+	// DataDir is where uploaded files (avatars, branding assets) are written.
+	// Defaults to the relative directory "data", which is what every existing
+	// deployment has always used; set DATA_DIR when the process runs somewhere
+	// its working directory is not writable, such as a read-only container image
+	// that mounts a volume elsewhere.
+	DataDir string
+
 	// CookieSecure sets the Secure flag on session cookies. Defaults to true
 	// when BASE_URL starts with https://, but can be overridden explicitly via
 	// COOKIE_SECURE=false for HTTPS-terminated-at-proxy setups where the binary
@@ -171,6 +178,7 @@ func Load() *Config {
 		EmbedAllowedOrigins: splitCSV(getEnv("EMBED_ALLOWED_ORIGINS", "")),
 		TrustedProxyCIDRs:   splitCSV(getEnv("TRUSTED_PROXY_CIDRS", "")),
 		STTBaseURL:          getEnv("STT_BASE_URL", ""),
+		DataDir:             getEnv("DATA_DIR", "data"),
 		// Space-separated, not comma: the value goes into a CSP source list verbatim, so
 		// it reads the same in the env var as it does in the header.
 		FrameAncestors: strings.Fields(getEnv("FRAME_ANCESTORS", "")),
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 79e5502..33aa069 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -268,3 +268,16 @@ func TestValidate_acceptsAPortAndATrailingSlash(t *testing.T) {
 		t.Errorf("Validate() = %v; want nil", err)
 	}
 }
+
+// DATA_DIR moves the upload directory; unset, it is the relative "data" every
+// existing deployment writes to, so nothing moves for anyone who never set it.
+func TestLoad_dataDir(t *testing.T) {
+	t.Setenv("DATA_DIR", "")
+	if cfg := config.Load(); cfg.DataDir != "data" {
+		t.Errorf("DataDir default = %q; want data", cfg.DataDir)
+	}
+	t.Setenv("DATA_DIR", "/var/lib/calnode")
+	if cfg := config.Load(); cfg.DataDir != "/var/lib/calnode" {
+		t.Errorf("DataDir = %q; want /var/lib/calnode", cfg.DataDir)
+	}
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index 0973af2..0cb4642 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -46,7 +46,14 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *db.DB, logger *sl
 	h.SetMultiTenant(cfg.MultiTenant)
 	h.SetBaseURL(cfg.BaseURL)
 	h.SetPublicBaseURL(cfg.PublicBaseURL)
-	h.SetDataDir("data")
+	// DATA_DIR, defaulting to the relative "data" every deployment has always used.
+	// The fallback is repeated here because tests build a Config literal that skips
+	// Load, and an empty dir would put uploads beside the binary.
+	dataDir := cfg.DataDir
+	if dataDir == "" {
+		dataDir = "data"
+	}
+	h.SetDataDir(dataDir)
 	h.SetEncKey(cfg.EncryptionKey)
 	h.SetSSOSecret(cfg.SSOSharedSecret)
 	h.SetPlatformToken(cfg.PlatformToken)

From 7299edda0088e707296dae7bb4086567226854ca Mon Sep 17 00:00:00 2001
From: Distronode <254259913+distronode-com@users.noreply.github.com>
Date: Sun, 6 Sep 2026 08:37:18 -0400
Subject: [PATCH 51/51] chore: drop the fork's branch log from the pull request

PROGRESS.md is the working log of the fork this branch was developed on. It is not
part of the change and does not belong upstream; the reasoning it holds is in the
commit messages.
---
 PROGRESS.md | 2285 ---------------------------------------------------
 1 file changed, 2285 deletions(-)
 delete mode 100644 PROGRESS.md

diff --git a/PROGRESS.md b/PROGRESS.md
deleted file mode 100644
index 61cef42..0000000
--- a/PROGRESS.md
+++ /dev/null
@@ -1,2285 +0,0 @@
-# PROGRESS — Postgres call sites (`feat/postgres-callsites`)
-
-Converting Calnode's call sites onto the dialect-aware `*db.DB` / `*db.Tx` wrapper
-(`internal/db`, built on the branch's base commit) so the app runs on PostgreSQL as
-well as SQLite. SQLite behaviour must not change.
-
-## Boundary 1 — thread the type through — DONE
-
-Every struct field, constructor, package-level helper and test helper that held
-`*sql.DB` now holds `*db.DB`; `*sql.Tx` became `*db.Tx`. Call sites needed no edit:
-the wrapper's method names match `database/sql`'s.
-
-- `db.Open` → `db.OpenDB` and `db.Migrate(x)` → `x.Migrate()` in `cmd/calnode/*` and
-  every test helper.
-- `internal/connstore`: `Execer` is an interface, so it needed no change; its doc
-  comment now names `*db.DB` / `*db.Tx`. `destination_test.go` deliberately opens a
-  bare `sql.Open("sqlite", ":memory:")` against a bespoke fragment schema and stays
-  `*sql.DB` — `Execer` accepts it.
-- `internal/handler/health.go` passes `h.db.DB` to `db.SchemaReady`, which takes a
-  bare `*sql.DB`. Legitimate: its one statement carries no placeholders.
-
-Gates: `go build ./...`, `go vet ./...`, `gofmt -l`, `go test ./...` all clean on SQLite.
-
-## Boundary 2 — non-portable SQL — DONE
-
-New package `internal/dbtime`: `Now()` for `datetime('now')`, `NowMilli()` for
-`strftime('%Y-%m-%dT%H:%M:%fZ','now')`. Every one of the 38 engine-side timestamps
-became a bound parameter. The two layouts are kept distinct on purpose — the schema
-already stores both shapes, they are compared lexicographically and served to
-clients verbatim, so folding them into one would change SQLite's stored bytes.
-`dbtime_test.go` asserts both layouts against SQLite's own output.
-
-- `INSERT OR IGNORE` → `INSERT … ON CONFLICT DO NOTHING`, no conflict target, which
-  both engines accept and which matches OR IGNORE's "any unique constraint" scope
-  (3 sites: demo seed, and the two reminder enqueues).
-- `COLLATE NOCASE` → `LOWER(col) = LOWER(?)` at both sites. No `d.SQL` pair: nothing
-  indexes `booking_attendees.email`, so there is no collation for an index to depend
-  on and no plan to preserve.
-- `PRAGMA foreign_keys` in `demo.Reset` is now SQLite-only. Postgres has no
-  equivalent short of superuser rights, so that branch wipes with one
-  `TRUNCATE … CASCADE` naming every table, which needs no FK ordering.
-- `sqlite_master` in `demo.listTables` is the one `d.SQL` pair: `pg_tables` scoped to
-  `current_schema()` on Postgres, which also keeps it correct inside an isolated
-  test schema.
-- `RETURNING position` (`question_handler.go`) is unchanged. Both engines support it;
-  verified on SQLite by the existing question tests, unverified on Postgres.
-- No `LIMIT` inside any `UPDATE`/`DELETE`. Checked by scanning every backquoted
-  string in the tree, not by a line grep.
-
-Gates: `go build ./...`, `go vet ./...`, `gofmt -l`, `go test ./...` clean on SQLite.
-
-## Boundary 3 — advisory lock replacing the single-writer guarantee — DONE
-
-`internal/booking/hostlock.go`. `lockHosts` takes `pg_advisory_xact_lock` on each
-host whose availability the transaction is about to decide, at the start of the
-transaction and before the first `hostBusy` read. On SQLite it returns immediately
-and the `SetMaxOpenConns(1)` guarantee stands untouched.
-
-- **Key derivation**: `int64(binary.BigEndian.Uint64(sha256.Sum256("calnode:booking:host:" + hostID)[:8]))`.
-  Domain-separated so a future advisory lock on another entity cannot collide by
-  hashing the same raw id. A collision between two hosts would cost an unnecessary
-  serialisation, never a wrong answer, so stability and spread are what matter.
-  `hostlock_internal_test.go` pins two values computed independently of the code.
-- **Deadlock**: ids are sorted and deduplicated on a copy before locking, so two
-  transactions needing the same pair cannot take them in opposite orders. The copy
-  matters because `Create`'s `HostIDs` arrive in round-robin priority order.
-- **Three call sites, not two.** `Create` and `Reschedule` as specified, plus
-  `ReassignHost`, which has the identical check-then-write shape (`hostBusy`'s own
-  doc names all three). Leaving it out would have left a known hole.
-- `Reschedule` locks the primary host *before* reading `booking_hosts`, not after: a
-  concurrent `ReassignHost` holds that same key, and that ordering is what stops a
-  reassignment committing between the host-list read and the `UPDATE`.
-- `isUniqueViolation` now recognises Postgres by SQLSTATE 23505 (`pgconn.PgError`)
-  as well as SQLite by message. Without it the index's backstop returned a 500
-  instead of `ErrDoubleBooked` on Postgres.
-- The materialise-into-a-slice patterns in `Reschedule` and the calendar reconciler
-  are untouched; they are still required on SQLite.
-
-**Measured, against the live PostgreSQL 17 on 127.0.0.1:55432**, with a temporary
-hand-written minimal schema because `migrations/postgres` does not exist yet. Two
-goroutines race overlapping-but-not-identical slots (10:00–10:30 against
-10:15–10:45, so `idx_bookings_no_double` cannot catch it), 40 rounds:
-
-| | created | conflicts | overlapping pairs in the DB |
-|---|---|---|---|
-| lock in place | 40 | 40 | **0** |
-| lock disabled | 79 | 1 | **39** |
-
-The negative control is the point: unlocked, the partial unique index caught 1 of
-40. The committed test (`internal/booking/concurrency_test.go`) is the same race
-through `dbtest.RequirePostgres`, and skips on SQLite saying the single-connection
-pool makes the race impossible.
-
-## Boundary 4 — Postgres test harness, docs, CI — DONE
-
-`internal/dbtest` landed with Boundary 3 because the concurrency test needs it.
-`Open(t)` returns in-memory SQLite unless `CALNODE_TEST_POSTGRES_DSN` is set, in
-which case each test gets its own `calnode_test_<random>` schema, created before
-the migrations and dropped after. Isolation rides on `search_path` in the DSN,
-which `dbtest_test.go` verifies against a live server rather than assuming
-(`TestSearchPathIsolation` passes; it also asserts the schema is invisible from the
-default path).
-
-- **22 test helpers across 18 files** repointed from `db.OpenDB("sqlite://:memory:")`
-  + `Migrate()` onto `dbtest.Open(t)`, so the whole suite follows the environment.
-  Deliberately left on SQLite: `dbtime_test.go` (it pins SQLite's own output),
-  `hostlock_internal_test.go` (it asserts the lock is a no-op there),
-  `connstore/destination_test.go` (bare driver, bespoke fragment schema), and the
-  `health_test.go` cases that want an *unmigrated* database.
-  `keyvault_test.go` keeps `sqlite://file::memory:?cache=shared&_fk=1` — a different
-  DSN for a reason, not a candidate for a blanket rewrite.
-- `docs/ARCHITECTURE.md` §4 amended in place, not appended to: the heading is now
-  both engines, the pool difference and the rebinding trap are stated, the cursor
-  gotcha is scoped to SQLite with the reason the pattern must stay anyway, and a new
-  "double-booking guarantee, per engine" subsection carries the single connection on
-  SQLite and the advisory lock on Postgres, with the index's real scope. §17's
-  gotcha 1 and one now-conditional aside in §8 follow it.
-- `.github/workflows/ci.yml` gains a `postgres` job: `postgres:17` service with a
-  `pg_isready` health check, the same steps as `check` minus `svelte-check`, and
-  `CALNODE_TEST_POSTGRES_DSN` set for `go test ./...`. Additive — with the variable
-  unset nothing about an existing run changes.
-
-## No longer blocked
-
-`migrations/postgres` landed with `feat/postgres-core`, so the `postgres` CI job now
-has something to migrate and passes.
-
-## Boundary 5 — the suite actually green on both engines — DONE
-
-Rebased onto the finished `feat/postgres-core`, so `migrations/postgres` exists and
-the suite could finally run against PostgreSQL. **15 failures**, four distinct
-causes — not the one the first triage suggested.
-
-1. **Constraint classification (7 failures).** Thirteen sites decided 409/400/404
-   vs 500 by substring-matching SQLite's English error text. `internal/db` now
-   exports `IsUniqueViolation` / `IsCheckViolation` / `IsForeignKeyViolation`,
-   matching SQLSTATE 23505 / 23514 / 23503 on Postgres and the message on SQLite.
-   Pinned by `constraint_test.go`, which provokes a real violation of each class
-   against the real schema on whichever engine is configured, asserts exactly one
-   of three predicates matches, and asserts none match an unrelated error.
-2. **Engine-dependent boolean expressions (2 failures).** `(user_id = ?) AS owned`
-   and `(archived_at IS NOT NULL) AS archived` yield 0/1 on SQLite and a boolean on
-   Postgres, which does not scan into the `int` the columns beside them use. Both
-   are now `CASE WHEN … THEN 1 ELSE 0 END`, portable and matching the schema's own
-   0/1 convention.
-3. **`json_extract` in production (1 failure).** `replaceReminderJobs` filtered on
-   `json_extract(payload, '$.booking_id')`. No portable spelling exists, so this is
-   a second `d.SQL` pair: `payload::json ->> 'booking_id'` on Postgres (the cast is
-   needed because the column is TEXT). The reschedule test carried its own copy of
-   the same expression, and discarded the `Scan` error, so the real failure showed
-   up two seconds later as a time-parsing error.
-4. **`ORDER BY rowid` (3 failures).** `webhook_deliveries` had no timestamp of its
-   own, so recency was `rowid DESC` — unportable, and not strictly correct on
-   SQLite either, since VACUUM may renumber rowids. Migration **00058** adds
-   `created_at TEXT NOT NULL DEFAULT ''` to both dirs, the writer binds
-   `dbtime.NowMilli()`, and the query is `ORDER BY created_at DESC, id DESC`.
-5. **`randomblob` in a gcal test helper (2 failures).** SQLite-only id generator,
-   replaced with `uid.New()` like every other row in those tests.
-
-Both suites green in one commit: 28/28 packages on SQLite, 28/28 on PostgreSQL.
-
-## Boundary 6 — constraint codes on BOTH engines — DONE
-
-The first version of `constraint.go` claimed modernc.org/sqlite exposes no error
-codes and matched SQLite on message text. That was false: it defines `type Error`
-with `Code()`, populated for every constraint class. Measured, not read:
-
-| violation | SQLite `Code()` | PostgreSQL SQLSTATE |
-|---|---|---|
-| UNIQUE | 2067 | 23505 |
-| PRIMARY KEY | **1555** | 23505 |
-| CHECK | 275 | 23514 |
-| FOREIGN KEY | 787 | 23503 |
-| NOT NULL | 1299 | 23502 |
-
-⛔ A PRIMARY KEY collision is **1555, not 2067**, while its message still reads
-"UNIQUE constraint failed". The text match caught both by accident;
-`Code() == 2067` alone would not. `idempotency_keys.idempotency_key` is a bare
-PRIMARY KEY, so the whole idempotent-replay path depends on 1555. Proved by
-deleting 1555 and re-running: the new `unique via primary key` subtest fails naming
-the code and the table, and `TestCreateBooking_idempotentReplay` returns
-`replay: 500`. `IsUniqueViolation` matches both codes; PostgreSQL needed no change.
-
-The text comparison is now a fallback only, for an error arriving without its
-driver type attached, and `TestConstraintTextFallback` executes that branch so it
-is not dead code. A driver error whose code does not match is a definite no and
-does not fall through — falling through would readmit a 1555 by its message after
-excluding it by code.
-
-Also fixed: the two intermittent handler failures under `go test ./...` were a flake
-in **my** `dbtest` harness, not the application. Handler goroutines are
-fire-and-forget (notify hosts, enqueue webhook, enqueue reminders) and outlive the
-test body; closing the pool does not stop an in-flight statement; `DROP SCHEMA
-CASCADE` needs an exclusive lock on every object and deadlocks against them
-(SQLSTATE 40P01). The drop now runs on a pinned connection with `lock_timeout` and
-retries within a bounded budget. Three consecutive full PostgreSQL runs clean.
-
-1. **Booleans — resolved.** The Postgres migrations declare them `SMALLINT`, so the
-   tree's `= 1` comparisons and `boolToInt(...)` work unchanged. Only *computed*
-   boolean expressions in SELECT lists needed a fix (Boundary 5, cause 2).
-2. **Text timestamp collation.** Timestamps are `TEXT` and compared
-   lexicographically on purpose (the recordings consent window, the job queue's
-   `run_at <= ?`). That is byte ordering under SQLite. Under a non-`C` Postgres
-   collation, ordering of mixed shapes (a space-separated `run_at` against a
-   `T`-separated one) is not guaranteed to match. Worth either `COLLATE "C"` on
-   those columns or a deliberate decision that it is safe. **Closed by Boundary 7.**
-
-## Boundary 7 — the last four items — DONE
-
-Open item 2 above, the `RETURNING` clause Boundary 2 left unverified, the bare
-`Open` the port had been dragging along, and the hard-coded pool size.
-
-### 1. TEXT timestamps are `COLLATE "C"` — migration 00059
-
-**54 columns across 27 tables**, enumerated from the migrated schema rather than
-from memory: every `*_at` (49 of them, including `locked_until`), plus
-`availability_rules.start_time`/`end_time` and `availability_overrides.date`/
-`start_time`/`end_time`, which hold `HH:MM` and `YYYY-MM-DD` and are ordered as
-times too (`ORDER BY day_of_week, start_time`, `ORDER BY date`). One grouped
-`ALTER TABLE` per table, so each is rewritten once. The SQLite half is a no-op
-file: BINARY *is* memcmp, so there is nothing to pin, and the file exists because
-the directories keep one file per version.
-
-Fixed in the schema rather than in the predicates. There are ~20 distinct
-lexicographic time comparisons in the tree (`run_at <= ?`, `expires_at > ?`,
-`locked_until < ?`, `decided_at BETWEEN`, `start_at`/`end_at` overlap,
-`created_at < ?`, several `ORDER BY created_at`); a `COLLATE "C"` clause on each
-is 20 chances to forget one, and forgetting is silent.
-
-⚠️ **The load-bearing site is `internal/handler/notetaker.go`**, which writes
-`datetime('now')`'s space-separated shape *because* it sorts before any
-`T`-separated stamp, which is what makes a notetaker job due immediately. That is
-a dependency on byte ordering in production code, not a theoretical one.
-
-**Measured, and it corrects the framing of the open item.** The server this
-branch develops against is PostgreSQL 17.11 with `datcollate = en_US.utf8`
-(libc provider) — read from `pg_database`, because ⛔ `SHOW lc_collate` no longer
-exists (it stopped being a GUC in PostgreSQL 16 and errors with "unrecognized
-configuration parameter", so the obvious way to ask is a dead end). The two
-shapes the schema actually stores do **not** flip under it:
-
-| pair | en_US.utf8 | memcmp |
-|---|---|---|
-| `2026-01-01 20:00:00` vs `2026-01-01T10:00:00Z` | space first | space first |
-
-Nor under **any of the other 878 collations installed on the server** — scanned,
-not assumed. glibc ignores the space at the primary level but still sorts a digit
-before `T`, which happens to agree with memcmp. So a control built only on those
-two values would pass with or without the migration, which is exactly the
-vacuous green the packet warned about. The control therefore also carries RFC
-3339's lower-case `t`/`z` spelling (§5.6 permits it, so an importer or a
-third-party API can hand it to us), where the two orders really do differ:
-
-```
-plain: 2026-01-01 10:00:00 | 2026-01-01T10:00:00.000Z | 2026-01-01t10:00:00z | 2026-01-01T10:00:00Z
-C    : 2026-01-01 10:00:00 | 2026-01-01T10:00:00.000Z | 2026-01-01T10:00:00Z | 2026-01-01t10:00:00z
-```
-
-`internal/db/collation_test.go` holds it three ways. (a) An audit over
-`information_schema.columns` matching by NAME, so a timestamp column added by a
-later migration is caught without anyone remembering — `collation_name` is NULL
-for a default-collated column and `'C'` after an explicit `COLLATE`, so the
-assertion is exact. (b) The control above, which **skips naming the server's
-collation** if the default already orders byte-wise, rather than passing
-vacuously. (c) An ordering test on `jobs.run_at` through the worker's real claim
-predicate.
-
-Proved failable by dropping `jobs.run_at` from the migration:
-
-```
-collation_test.go:79: 1 of 54 timestamp columns are not COLLATE "C":
-    jobs.run_at = <database default>
-collation_test.go:242: ORDER BY run_at =
-    [… 2026-01-01t10:00:00z 2026-01-01T10:00:00Z …]
-    want byte order
-    [… 2026-01-01T10:00:00Z 2026-01-01t10:00:00z …]
-```
-
-### 2. `RETURNING position` — works unchanged on Postgres
-
-No `d.SQL` pair, no rewrite. The clause is the auto-position `INSERT` in
-`question_handler.go`, which computes the position inside the statement
-(`VALUES (…, (SELECT COALESCE(MAX(position)+1, 0) …)) RETURNING position`) so two
-concurrent creates cannot land on the same one.
-
-The new test goes through the HTTP handler on `dbtest.Open(t)`, so it follows the
-environment like everything else, and it asserts the value the handler **scanned
-from RETURNING** as well as the row left behind: a `RETURNING` that quietly
-produced a zero would still leave a correct row, so checking the table alone —
-which `TestCreateQuestion_autoPosition` already did — cannot see it. The
-explicit-position case is in the same test because the next auto position after a
-pinned 9 must be 10, which is what shows the subselect is evaluated by the engine
-rather than the sequence being an artifact of insertion order.
-
-Measured: **0, 1, 2, then 9 explicit, then 10 — identical on both engines.**
-
-### 3. `db.Open` deleted
-
-It returned a bare `*sql.DB` "for callers that have not moved to OpenDB yet".
-Nothing outside the package's own tests used it, and it could only ever do harm:
-statements through that handle are not rebound, so every `?` is a Postgres syntax
-error found at runtime, far from the call. It was also the shape most likely to
-be copied by whoever added the next call site.
-
-`/readyz` was the one production caller reaching into the exported embedded field
-(`db.SchemaReady(ctx, h.db.DB)`). `*db.DB` now carries `SchemaReady` and
-`AppliedVersion`, so the handler asks the handle. The package-level functions stay
-for the cases that genuinely hold a bare pool — goose's bookkeeping, the tests
-that open an unmigrated one — and `db_test.go` passes `database.DB` explicitly,
-which says at the call site that the bare pool is deliberate. `TestOpen_inMemory`
-became `TestOpenDB_inMemory` rather than staying named after something that no
-longer exists. No test asserts the symbol's absence: the build is the proof.
-
-### 4. Pool size is configurable
-
-`DB_MAX_OPEN_CONNS` / `DB_MAX_IDLE_CONNS`, defaults unchanged at 10/5, validated
-in `config.PoolFromEnv`: unset, unparsable or non-positive falls back to the
-default with a warning (matching `getBool`/`getDuration`, which also refuse to
-fail a boot over a typo in an optional knob), and idle above open is clamped —
-`database/sql` reduces it silently anyway, so the clamped pair is the honest
-description of what the pool will do. ⚠️ The clamp has to apply to the **default**
-idle as well: `DB_MAX_OPEN_CONNS=2` alone must give 2/2, not 2/5. A test pins it.
-
-`OpenDB` reads `PoolFromEnv` itself rather than taking the numbers as an
-argument, so all five entry points pick them up without five identical edits and
-without one of them silently keeping the defaults; `db.WithPool` is the override
-for a caller that must not follow the environment. `db` → `config` is not a
-cycle (`config` imports only the standard library).
-
-**SQLite stays pinned at 1/1 and ignores both the environment and `WithPool`.**
-That is the correctness guarantee, not a preference: the single connection is
-what serialises write transactions (it is why `booking.lockHosts` is a no-op
-there) and the pragmas are connection-scoped.
-`TestOpenDB_sqlitePoolIsNotConfigurable` asserts it with both knobs at 40/20, for
-the `:memory:` and file forms.
-
-The idle limit cannot be read back — `sql.DBStats` exposes the open limit only —
-so it is measured: four live transactions force four connections, and after
-committing them all the pool keeps **1** with `WithPool(4, 1)`.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, **28/28 packages ok on SQLite and
-28/28 on PostgreSQL**. Negative control, the same PostgreSQL command with the
-password changed to `wrong`: `internal/db` **fails** rather than skipping, with
-`failed SASL auth: FATAL: password authentication failed for user "postgres"
-(SQLSTATE 28P01)` — including `TestPostgres_idleLimitApplied`, the one new test
-whose assertions could conceivably have held without a server.
-
----
-
-# Multi-tenant mode (`feat/multi-tenant`)
-
-One process, many isolated workspaces. `workspaces` is the tenant root, every
-application table carries a `workspace_id`, and PostgreSQL row-level security —
-not the query author — is what keeps one workspace out of another's rows.
-`MULTI_TENANT` unset must behave exactly as before, on SQLite and on
-single-tenant PostgreSQL. That is a gate, not a wish.
-
-## Boundary 1 — config + schema — DONE
-
-### Migration 00060, not 00061
-
-The packet numbered it 00061 on the assumption that `feat/platform-hooks` had
-landed 00060. It has not: that branch is not in this clone (no `/v1/auth/sso`
-endpoint, no `TRUSTED_PROXY_CIDRS`, no `/metrics`), and the 59 files in each
-directory are contiguous. `migrations_internal_test.go` asserts
-`target version == file count` and names the failure "a gap or a duplicate
-number", so 00061 over 59 files reds an existing gate. 00060 it is;
-`knownMigrationCount` moved 59 → 60 with it.
-
-### ⛔ ENABLE / FORCE ROW LEVEL SECURITY is NOT in the migration, and the reason is measured
-
-D2 puts `ENABLE` + `FORCE` + the policy in the migration. `FORCE` makes a
-table's policy apply to the table's **owner** as well, and in single-tenant mode
-`DATABASE_URL` *is* the owner. Measured against the PostgreSQL 17.11 this branch
-develops on, with a `NOBYPASSRLS` owner role and one row present:
-
-| role | RLS | `app.workspace_id` | rows seen |
-|---|---|---|---|
-| owner (NOBYPASSRLS) | ENABLE + FORCE | unset | **0** |
-| superuser | ENABLE + FORCE | unset | 1 |
-| owner (NOBYPASSRLS) | ENABLE only | unset | 1 |
-| non-owner app role | ENABLE only | unset | **0** |
-
-So an unconditional `FORCE` silently blinds every existing single-tenant
-PostgreSQL deployment whose DSN is not a superuser — and **the suite's own DSN
-is a superuser, so the test lane would have gone green anyway.** Row 4 is the
-other half: `ENABLE` alone already isolates a non-owner role, which is what the
-application role is under D4.
-
-The split that keeps both promises: the **policies** live in the migration,
-where they are reviewable SQL, and a policy on a table whose RLS is not enabled
-is inert (verified, not assumed). The two `ALTER TABLE` lines live in
-`db.EnableRLS`, which runs at boot **only when `MULTI_TENANT` is set**, on the
-**platform handle** (`DATABASE_ADMIN_URL` — the application role cannot run DDL
-in multi-tenant mode at all), is idempotent, and whose failure is
-`os.Exit(1)`: without it every policy is inert and the process would come up
-looking multi-tenant while separating nothing.
-`TestPostgres_rlsIsOffUntilEnabled` pins both halves — off straight after
-migrating, on for all 32 tenant tables and none of the 4 exempt ones after
-`EnableRLS`, twice.
-
-### The column default is `COALESCE(current_setting(…, true), 'default')`
-
-D1 spells it `current_setting('app.workspace_id')`. The bare form **raises** on
-an unset parameter, so it would fail every INSERT in single-tenant mode. The
-`missing_ok` form plus `COALESCE` gives `'default'` when nothing is bound, which
-is what single-tenant wants, and is never reached in multi-tenant mode because
-the handle binds before every statement. It also fails **closed** if a
-multi-tenant statement ever escapes that binding: the row would be written as
-`'default'` and the policy's `WITH CHECK` compares it against an unset parameter
-(NULL, so not true), which refuses the INSERT with SQLSTATE 42501 rather than
-letting it land in the wrong tenant. `rls_proof_test.go` asserts exactly that,
-including that nothing arrives in the default workspace.
-
-### The tenancy proof, and its negative control
-
-`internal/db/rls_proof_test.go` creates a `calnode_app_<hex>` role with
-`NOBYPASSRLS` per test schema, grants it the schema's tables, and opens a handle
-as it. ⛔ It **skips loudly** rather than falling back if the role cannot be
-created, or reports `rolsuper`/`rolbypassrls`, or owns any table in the schema —
-a superuser handle would satisfy every assertion whether the policies existed or
-not. Four subtests, both halves required:
-
-- unbound: `SELECT COUNT(*) FROM users` returns **0** of 2
-- unbound: INSERT refused with **42501**, and **nothing lands in `default`**
-- bound to `ws-a`: sees 1 of 2, reads `a@example.com`, INSERT naming **no**
-  `workspace_id` lands as `ws-a`, `b@example.com` invisible
-- bound to `ws-a`, naming `ws-b` explicitly: refused with **42501**
-
-`set_config(…, false)` is session-scoped, so every subtest pins one `*sql.Conn`
-and writes `$n` directly — statements through a `*sql.Conn` are not rebound.
-
-Proved failable by making `EnableRLS` return early:
-
-```
---- FAIL: TestPostgres_rlsIsolatesAnUnprivilegedRole/unbound_reads_nothing
-    rls_proof_test.go:178: an unbound session sees 2 of 2 users; want 0 — an unset app.workspace_id must match no row
---- FAIL: .../unbound_write_is_refused_and_lands_nowhere
-    rls_proof_test.go:187: an unbound INSERT succeeded; the policy's WITH CHECK must refuse it
---- FAIL: .../bound_reads_and_writes_exactly_one_workspace
-    rls_proof_test.go:215: a session bound to ws-a sees 3 users; want 1
---- FAIL: .../naming_another_workspace_explicitly_is_refused
-    rls_proof_test.go:261: writing into another workspace succeeded; WITH CHECK must refuse it
-```
-
-### 32 tenant tables, 4 exempt, and a gate against forgetting
-
-`db.TenantTables` / `db.ExemptTables` are the Go copies of the list in the
-migration header, and `TestTenancy_tableListsCoverTheSchema` fails if a base
-table is in neither — so a table added by a later migration has to be
-classified. Exempt: `workspaces` (the root, with its own SELECT-only policy for
-the application role), `crypto_keystore` (one DEK per process, D3),
-`goose_db_version`, `oauth_clients` (dynamic client registration is per client
-*application*; the per-tenant half is `oauth_access_tokens`, which is a tenant
-table).
-
-### SQLite's three forced differences
-
-1. **No `REFERENCES workspaces(id)`.** Measured on modernc.org/sqlite with
-   `foreign_keys=ON`: `ALTER TABLE t ADD COLUMN workspace_id TEXT NOT NULL
-   DEFAULT 'default' REFERENCES ws(id)` is **rejected** — "Cannot add a
-   REFERENCES column with non-NULL default value (1)". Rebuilding all 32 tables
-   to get a constraint whose only payoff is cascade-on-workspace-delete, in an
-   engine that cannot run multi-tenant, is not worth it. The two tables rebuilt
-   below omit it too, so the engine is consistent with itself.
-2. **No RLS, no policies.** Nothing to express them with, which is why
-   `config.Validate` refuses `MULTI_TENANT` without a `postgres://` DSN.
-3. **Only the uniqueness that has to MOVE moves.** `idempotency_keys` and
-   `meeting_consents` are rebuilt (their PRIMARY KEY changes and SQLite cannot
-   ALTER a table constraint); `ux_jobs_type_payload` and `idx_notes_booking` are
-   dropped and recreated (plain indexes need no rebuild). `users(email)`,
-   `event_types(slug)`, `teams(slug)` and `server_settings`' `id = 1` singleton
-   stay exactly as they are: with one workspace, a global unique and a
-   `(workspace_id, x)` unique admit precisely the same rows.
-
-### ⚠️ `jobs` keeps a second, workspace-free copy of each partial index
-
-The packet says every partial index on `bookings` and `jobs` gets `workspace_id`
-prepended. Correct for `bookings` — every query that uses those indexes now
-carries a workspace predicate. **Not** for `jobs`: it is the one table worked
-*across* tenants, and the worker's claim and its crash-recovery reaper (B5) run
-on the platform handle with no workspace predicate, ordered by `run_at` /
-`locked_until` globally. A workspace-leading index cannot serve an ordered global
-scan. So both are prepended as instructed **and** `idx_jobs_pending_global`
-`(run_at)` and `idx_jobs_running_expired_global` `(locked_until)` are added
-alongside. Four small indexes on a table that holds pending work, not history.
-
-### `demo.Reset` had to learn about the tenant root
-
-The Postgres path is one `TRUNCATE … CASCADE` naming every table from
-`pg_tables`, which took `workspaces` with it, and the re-seed's first
-`server_settings` INSERT then failed with SQLSTATE 23503. `workspaces` is now
-held back alongside `goose_db_version`: it is the tenant root, not visitor data,
-and in demo mode it holds exactly one constant row. This was the only pre-existing
-test the migration broke, on either engine.
-
-### Config
-
-`MULTI_TENANT`, `DATABASE_ADMIN_URL`, `CALNODE_PLATFORM_TOKEN`, and a new
-`(*Config).Validate` called from `main` before the database is opened. It is
-separate from `Load` because every optional knob in `Load` deliberately falls
-back on a typo rather than refusing to boot (`PoolFromEnv`); these are not typos.
-Five refusals, each one a combination whose only other outcome is silent:
-a non-`postgres://` `DATABASE_URL`, a missing or non-Postgres
-`DATABASE_ADMIN_URL`, **the two DSNs being equal** (one role means the
-application role owns the tables and every policy is inert against it — the
-misconfiguration hardest to notice, because everything works, including reading
-other tenants' rows), and `DEMO_MODE` (D13: demo mode periodically wipes the
-whole database, which here is every tenant's data).
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-`go test ./...` **rc=0 on SQLite (28/28 packages)** and **rc=0 on PostgreSQL
-(28/28)**.
-
-### Not yet wired (later boundaries, stated so it is not mistaken for done)
-
-`cmd/calnode/main.go` opens the platform handle with a second `db.OpenDB` and
-uses it for `Migrate` + `EnableRLS`; Boundary 2 replaces that pair with
-`db.OpenPair`. The other entry points (`mcp`, `reset-admin`, `rotate-key`,
-`recover-key`) still open one handle from `DATABASE_URL` and are untouched —
-they are single-tenant operator tools today, and B3/B6 decide what they become.
-
-## Boundary 2 — the two handles, and the per-statement binding — DONE
-
-`db.OpenPair(appURL, adminURL)` returns `(app, platform)`, `app.Platform()`
-answers with `platform`, and `ForWorkspace(id)` returns a **value** carrying the
-pool plus a string. `OpenDB` is untouched, and a handle from it binds nothing —
-so single-tenant SQLite and single-tenant PostgreSQL run exactly the statements
-they ran before. `TestSingleHandle_forWorkspaceIsIdentity` pins that:
-`ForWorkspace` returns the identical pointer, does not even validate, `Platform()`
-is the handle itself, and `Prepare` still works.
-
-### Binding is per statement, and the release is the part that needed proving
-
-Each `Query`/`QueryRow`/`Exec`/`Begin` on a bound handle takes a pooled
-`*sql.Conn`, runs `SELECT set_config('app.workspace_id', $1, false)`, runs the
-statement there, and gives the connection back: `Exec` immediately, `Row` on
-`Scan`/`Err`, `Rows` on `Close`, `Tx` on `Commit`/`Rollback` (idempotently — a
-`defer tx.Rollback()` after a successful `Commit` is the standard pattern here and
-must not double-close). `Begin` uses `set_config(…, true)`, i.e. `SET LOCAL`, so
-the connection goes back carrying nothing.
-
-Nothing is pinned between statements, which is the point:
-`TestOpenPair_handleSurvivesItsRequest` builds a handle inside a function, lets
-that function return, and then reads through it from four concurrent goroutines.
-Calnode's handlers are full of fire-and-forget goroutines (notify hosts, enqueue
-the webhook, enqueue reminders) that outlive their request, and a handle that
-pinned a session would be unusable in them.
-
-Release is asserted by `handle.Stats().InUse` returning to **0** after every
-shape, with a positive control on the same number: while a cursor or a
-transaction is open it must read **1**, so the zero afterwards means something.
-Proved failable by making `Row.release` and `Rows.Close` skip the release:
-
-```
---- FAIL: TestOpenPair_workspaceHandleSeesOnlyItsOwn/QueryRow
-    pair_test.go:103: pool reports InUse=2 after two QueryRow/Scan pairs; the connection was not released
---- FAIL: .../Query
-    pair_test.go:114: with a cursor open the pool reports InUse=3; want 1
-    pair_test.go:133: pool reports InUse=3 after Rows.Close; the connection was not released
---- FAIL: .../Exec
-    pair_test.go:156: pool reports InUse=3 after Exec; the connection was not released
---- FAIL: .../Tx
-    pair_test.go:167: with a transaction open the pool reports InUse=4; want 1
-```
-
-### ⛔ `Prepare` is refused on a bound handle
-
-A `*sql.Stmt` is re-prepared on whatever connection the pool hands it, and there
-is no hook to set `app.workspace_id` on that connection first — so a prepared
-statement on a multi-tenant handle would run **unbound**, which is silently
-empty rather than an error. Nothing in the tree prepares a statement (checked, not
-assumed), and a caller that needs one should take a transaction, where the binding
-is a property of the connection for the whole tx.
-
-### `VerifyRoles` — because D4 was otherwise documentation only
-
-Called on the application handle at boot, right after `EnableRLS`, and the boot
-fails if it does. Both halves fail **silently** otherwise:
-
-- The application role being a superuser, having `BYPASSRLS`, or **owning any
-  table in the schema** means it is not constrained by the policies. Nothing
-  breaks. Every request works. It can also read every other workspace. That is a
-  security hole with no symptom, which is exactly the kind of thing that needs a
-  boot-time refusal rather than a doc line.
-- The platform role *not* bypassing means its `''` binding matches no row, so the
-  worker claims nothing and the reconciler enumerates nothing. Also no error, just
-  an instance that quietly does no background work. This is what makes binding
-  `''` on the platform handle (D5) safe rather than a gamble.
-
-`openTenantPair` in the tests runs it, so every case in the file is asserted
-against a configuration the guard accepts.
-
-### ⚠️ `connstore.Execer` had to change, and `destination_test.go` with it
-
-`Execer` was `QueryRowContext(…) *sql.Row`, and it is called with a `*db.DB` in
-three provider packages (`gcal`, `calendar/microsoft`, `caldav`) as well as with a
-`*db.Tx`. Go has no covariant return types, so once `QueryRowContext` returns
-`*db.Row` the interface has to say `*db.Row`. The consequence is that
-`connstore/destination_test.go`'s deliberately-bare `sql.Open("sqlite",
-":memory:")` no longer satisfies it and is now `db.OpenDB("sqlite://:memory:")`
-— which is a correction, not a concession: a bare `*sql.DB` does not rebind
-placeholders either, so holding it up as "Execer accepts this too" was already
-describing a handle that cannot run the tree's SQL on PostgreSQL. The bespoke
-fragment schema is unchanged; `OpenDB` does not migrate.
-
-The compiler found the rest, and there were only three: `*sql.Rows` declarations
-in `handler/availability.go` and `handler/livekit_recording.go`, and the
-`scanStrings` helper in `internal/db/postgres_test.go`.
-
-### Boot
-
-`cmd/calnode/main.go` opens the pair when `MULTI_TENANT` is set and one handle
-otherwise, runs migrations and `EnableRLS` on **`platform`**, and `VerifyRoles` on
-`database`. Both refusals are `os.Exit(1)`.
-
-⚠️ Still single-handle, from `DATABASE_URL`, and untouched: the `mcp`,
-`reset-admin`, `rotate-key` and `recover-key` subcommands. They are single-tenant
-operator tools today; B3 and B6 decide what they become.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-`go test ./...` **rc=0 on SQLite (28/28)** and **rc=0 on PostgreSQL (28/28)**.
-The 11 new cases all run rather than skip on the PostgreSQL lane, and the
-tenant-binding ones skip with a stated reason on SQLite.
-
-## Boundary 3 — handler scoping and tenant resolution — PART ONE of two
-
-⚠️ **B3 is not finished.** This commit lands the foundation: the `shared` split,
-the `Workspace` type, the two resolvers, `Scoped`, `Platform`, the refusal
-mapping, `AuthUser.WorkspaceID`, and the credential lookups moved onto the
-platform handle. What remains is the part that touches `internal/server/server.go`:
-**163 `mux.HandleFunc` registrations** have to be rewritten through
-`h.Scoped(resolve, (*Handler).Method)`, and with them the route-classification
-test, the five end-to-end request tests, and the `/v1/bookings/{id}` tenant check.
-Split because the registration rewrite is a single mechanical edit across 163
-lines that has to land with its own gate, not because either half is optional.
-
-### The split, and why the mutexes had to move
-
-`Handler` was 30 fields including **six `sync.RWMutex`**. A tenant-scoped request
-needs a handler whose `db` is bound to its workspace, and the only way to give
-**314 methods** a bound `h.db` without editing all of them is to hand them a
-receiver that differs in that one field — so `Handler` is copied per request. A
-struct containing a mutex cannot be copied (`go vet` copylocks, and rightly:
-copying a mutex copies its state).
-
-So: `shared` holds everything the process has one of — logger, mailer, the
-hot-swappable integration clients and their mutexes, the configured hosts, demo
-bookkeeping — and `Handler` is `{ *shared; db; ws; bookingSvc; webhookSvc }`.
-Embedding as `*shared` rather than naming it is what keeps `h.logger`,
-`h.livekitMu`, `h.mailer = m` and the rest compiling **untouched across all 61
-files**. Measured: the split needed zero edits to any handler method, and
-`go vet ./...` is clean.
-
-`bookingSvc` and `webhookSvc` stay on `Handler` because each wraps a `*db.DB`;
-`forWorkspace` rebuilds them from the scoped handle through new
-`(*Service).ForDB` methods on `internal/booking` and `internal/webhook`. Both are
-structs over a pool, so a rebuild is one allocation and pins nothing.
-
-### ⛔ Credential lookups had to move to the platform handle
-
-`RequireAuth`'s two reads — `api_keys` and `sessions` — ran on `h.db`. On a
-multi-tenant instance the application handle is bound to the workspace **of the
-request**, and the workspace of the request is what those reads exist to
-DISCOVER. Bound, they find nothing, and a perfectly good API key is reported
-`invalid API key`. Both now use `h.platformDB()` (`h.db.Platform()`, which is the
-same handle in single-tenant mode) and both select `u.workspace_id` into the new
-`AuthUser.WorkspaceID`. This is the reason D9 keeps `api_keys.key_hash` and
-`sessions.id` globally unique.
-
-### Four refusals, and none of them is "carry on unscoped"
-
-`errUnknownHost` → **404** (HTML: the host-resolved surfaces are pages a person is
-looking at). `errWorkspaceSuspended` → **503** + `Retry-After`.
-`errWorkspaceMismatch` → **403 `{"error":"workspace mismatch"}`**, which is the
-body D10 specifies and a test pins. `errNoWorkspace` → **500**.
-
-⛔ There is deliberately **no fallback to the default workspace** on an
-unrecognised host. Falling back would serve one tenant's booking page on any
-domain pointed at the instance. Migration 00060 seeds `workspaces.public_host`
-empty for `default` for the same reason: no HTTP request carries an empty Host, so
-the default workspace is unreachable by host resolution. Both are asserted.
-
-Proved failable by making `HostWorkspace` return `DefaultWorkspace` on a failed
-lookup — the exact bug:
-
-```
---- FAIL: TestHostWorkspace_multiTenant/unknown_host_does_not_fall_back_to_default
-    workspace_internal_test.go:102: resolved &{ID:default Slug:default PublicHost: Region: Status:active}; want an error
---- FAIL: TestHostWorkspace_multiTenant/the_default_workspace_is_unreachable_by_host
-    workspace_internal_test.go:117: an empty Host resolved; err = <nil>
---- FAIL: TestScoped_refusalsNeverReachTheMethod/unknown_host_is_404
-    workspace_internal_test.go:230: status = 200; want 404 (body "{\"workspace\":\"default\"}\n")
-    workspace_internal_test.go:233: the method ran 1 times; wantReach=false
-```
-
-### `Scoped` takes a method EXPRESSION, and the compiler enforces it
-
-`h.Scoped(HostWorkspace, (*Handler).BookPage)`, not `h.Scoped(…, h.BookPage)`. A
-bound method value would capture the **unscoped** receiver, which is exactly the
-bug the wrapper exists to prevent, and it would compile silently. A method
-expression cannot: its first parameter is the receiver, which `Scoped` supplies
-from `forWorkspace`.
-
-`Platform(method)` is the sibling for routes that belong to no workspace — the
-identity host's OAuth endpoints, `/.well-known/*`, `/healthz`, `/readyz`,
-`/version`, `/metrics`, the platform API. It exists so "unscoped, on purpose" is
-something the registration says out loud rather than by omission, which is what
-the route-classification test in part two will hold.
-
-### `publicURL()` is per workspace
-
-In multi-tenant mode it returns `https://<ws.public_host>` and `PUBLIC_BASE_URL`
-is ignored entirely (D11); `BASE_URL` stays the identity host of the process.
-Single-tenant is unchanged: `PUBLIC_BASE_URL` if set, else `BASE_URL`. Four cases
-pinned.
-
-### Scope of the tests here, stated so it is not overread
-
-`workspace_internal_test.go` runs against ONE handle with `multiTenant` set. That
-is enough for everything it asserts, because resolution reads `workspaces` through
-`platformDB()` and on a single handle that is the handle itself. It does **not**
-re-prove the row-level-security binding — that needs a NOBYPASSRLS role and is
-already proven in `internal/db` (`rls_proof_test.go`, `pair_test.go`). The
-end-to-end request tests in part two are where a real pair gets exercised through
-HTTP.
-
-### TODO(integration) — blocked on `feat/platform-hooks`
-
-Neither is implemented, and neither is faked:
-
-- **D11, the OAuth login hand-off.** After a Google/Microsoft callback on the
-  identity host, the callback cannot set a cookie for the workspace's public host,
-  so it must mint an SSO token for the workspace carried in the OAuth `state` and
-  redirect to `https://<public_host>/v1/auth/sso?token=…`. That endpoint arrives
-  with `feat/platform-hooks`, which is **not in this clone**. Expected shape at
-  integration: the branch's SSO issue/verify pair, extended per the packet with a
-  required `wid` claim and an `aud` equal to the workspace's public host.
-  `finishOAuthLogin` in `internal/handler/auth_oauth.go` is where the redirect
-  replaces the cookie set.
-- **D14, rate-limit keys.** They should become `(workspace_id, client_ip)` using
-  that branch's `TRUSTED_PROXY_CIDRS`-aware client-IP helper. Expected shape:
-  `handler.clientIP(r) string`. Today's limiters key on the TCP remote address
-  (`ARCHITECTURE` §16 says so deliberately), and prefixing the workspace without
-  the helper would key a whole tenant behind one proxy as a single client.
-- **The platform `/metrics` endpoint**, also on that branch, reads the `jobs`
-  table. At integration it **must** read through `Platform()`: `jobs` is a tenant
-  table and an application-handle read would report one workspace's queue, or on
-  the unbound handle, zero.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-`go test ./...` **rc=0 on SQLite (28/28)** and **rc=0 on PostgreSQL (28/28)**.
-The 21 new resolver cases all run on both lanes.
-
-## Boundary 3, part two — the registrations, and the gate that keeps them honest
-
-⚠️ **The end-to-end request tests through a real `OpenPair` are NOT in this
-commit.** Everything else part two owed is: the 160 rewritten registrations, the
-MCP per-workspace scoping, the classification gate, and `/v1/bookings/{id}`. The
-e2e file is the next thing, before B4.
-
-### 169 routes, every one of them classified
-
-```
-169 routes: 31 host-scoped, 106 credential-scoped, 24 platform, 8 allowlisted
-```
-
-`type H = handler.Handler` in `internal/server` so a registration reads
-`(*H).ListBookings`. The brevity is incidental; the **method expression** is the
-point. `Scoped` takes `func(*Handler, http.ResponseWriter, *http.Request)`, so
-passing `h.ListBookings` — a bound method value on the *unscoped* handler, which
-is precisely the bug `Scoped` exists to prevent — **does not compile**.
-
-Credential-scoped routes are `h.RequireAuth(h.Scoped(handler.CredentialWorkspace,
-(*H).Method))`, in that order: `CredentialWorkspace` reads the caller out of the
-request context, so the auth middleware has to have run first.
-`TestCredentialScopedRoutesAuthenticateFirst` checks both the presence and the
-nesting order across all 106.
-
-### The gate, and why it reads the file
-
-`internal/server/routes_classified_test.go` scans `server.go` and fails on a
-registration that is neither `Scoped(HostWorkspace, …)`,
-`Scoped(CredentialWorkspace, …)`, `Platform(…)`, nor on an 8-entry allowlist whose
-every member is a handler that is **not a `*handler.Handler` method at all** (two
-empty CORS preflights, the embedded favicon/SPA/redirects, the MCP mount).
-
-⛔ A source scan rather than a runtime walk because `http.ServeMux` exposes no way
-to enumerate its patterns, and the thing to catch is a registration written
-without a wrapper — a property of the text. Three guards against a vacuous pass: a
-floor of 150 registrations, a floor of 3 per bucket (so a refactor that classified
-everything one way fails), and a check that every allowlist entry is still a live
-route.
-
-`TestPlatformRoutesAreTheIdentityHostSet` pins the 24-member platform set exactly
-against D11, with a one-line reason per group. A route joining or leaving the
-identity host is a decision about which host serves it, and this makes it
-impossible to make silently.
-
-⚠️ **The rewrite missed one route and the gate caught it.** `POST
-/v1/livekit/egress-webhook` carries a trailing `// legacy alias` comment, so the
-scripted edit's line pattern did not match it and it stayed unwrapped. That is the
-gate doing exactly the job it was written for, on its first run.
-
-### ⛔ The MCP tools close over their handler, so one cached server was wrong
-
-`/mcp` was `mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return
-mcpSrv }, nil)` over a single instance built at boot. The eight tools capture `h`,
-so **every workspace's tool calls would have run on whichever handler built that
-instance**. The mount is on the identity host and carries no tenant Host, so the
-credential is the only source (D10).
-
-`MCPCallerMiddleware` now also reads `users.workspace_id` — through
-`platformDB()`, same reasoning as `RequireAuth` — into `mcpCaller.WorkspaceID`,
-and the factory becomes `h.MCPServerForRequest`, which returns a server per
-workspace from a cache on `shared` (`map[string]*mcp.Server` behind an RWMutex).
-One entry keyed `""` in single-tenant mode, so that path is the old behaviour with
-a map in front of it. Building one allocates eight tool registrations and their
-JSON schemas, which is not something to do per request.
-
-### `/v1/bookings/{id}` — the tenant check is the scoping, and the missing auth is still missing
-
-`GET /v1/bookings/{id}` is now `h.Scoped(handler.HostWorkspace, (*H).GetBooking)`,
-so the handle it runs on is bound to the workspace of the request Host and a
-booking id belonging to another workspace is simply not visible — the 404 comes
-from the row not existing, enforced by the policy rather than by a predicate the
-handler has to remember.
-
-⚠️ **It still has no auth middleware at all**, alone among `/v1/bookings/{id}/*`
-(`server.go`, and every sibling is wrapped in `h.RequireAuth`). Reported in the
-first packet turn and deliberately not changed: adding auth to a route the booking
-page may depend on is a product decision, not a tenancy one. What multi-tenancy
-changes is the blast radius — it is now bounded to one workspace instead of the
-whole instance.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-
-## Boundary 3, part three — the end-to-end tenancy proof
-
-Two workspaces on distinct public hosts, one process, the **real mux** via
-`httptest`, and a real `db.OpenPair` whose application handle is a `NOBYPASSRLS`
-role that owns nothing. `internal/server/tenancy_e2e_test.go`, and the harness it
-uses is now reusable: `dbtest.RequireTenantPair(t)`.
-
-Eight assertions, each in both directions:
-
-| surface | A sees its own | A cannot reach B's |
-|---|---|---|
-| `GET /v1/event-types` (API key) | ✓ | ✓ |
-| `GET /v1/bookings?scope=all` (API key) | ✓ | ✓ |
-| `GET /v1/event-types/{slug}/slots` (public) | ✓ | ✓ |
-| `GET /book/{slug}` (public page) | — | ✓ |
-| `GET /v1/bookings/{id}` | 200 | **404** |
-| `POST /v1/bookings` (public write) | lands in `acme` | B's count unmoved |
-| MCP `list_bookings` over the HTTP transport | ✓ | ✓ (both directions) |
-| A's API key on B's host | — | **403 `workspace mismatch`** |
-
-The MCP call is a real `tools/call` through `mcp.StreamableClientTransport`
-against an `httptest.Server`, with the `cno_` key as a bearer token. It is
-asserted in **both** directions — A then B — because that is what catches a
-cached server built for whichever workspace called first. The mismatch test also
-checks the same key on the **identity** host still works: that host names no
-workspace, so there is nothing to disagree with, and it is where API and MCP
-callers legitimately arrive.
-
-### ⛔ `VerifyMCPBearer` was reading credentials on the tenant handle
-
-Found by the MCP test failing `connect to /mcp: Unauthorized`. All four of its
-reads and writes — `oauth_access_tokens`, `api_keys`, and the two `last_used_at`
-updates — ran on `h.db`. `/mcp` is on the identity host, so **no workspace is
-bound at all**, and every valid bearer token would have been reported
-Unauthorized on a multi-tenant instance. Now on `platformDB()`, which is the same
-reasoning as `RequireAuth` and `MCPCallerMiddleware`, and the third place in the
-tree where a global-unique credential lookup had to move. That is the pattern:
-**any read whose purpose is to discover the tenant cannot be bound to it.**
-
-### Two controls, and the second is the one that matters
-
-**Control 1 — the binding stubbed off** (`DB.binds()` forced false). Every test
-fails, but at the FIXTURE, because the seeding writes are refused:
-
-```
-tenancy_e2e_test.go:192: create user for acme: ERROR: new row violates row-level security policy for table "users" (SQLSTATE 42501)
-```
-
-That proves the binding is load-bearing, and nothing more — the read assertions
-never run.
-
-**Control 2 — the application handle given the bypassing owner role**, with
-`VerifyRoles`' refusal disabled. This is the "a superuser DSN proves nothing"
-scenario made concrete, and it is what shows the assertions themselves working:
-
-```
---- FAIL: TestTenancy_readSurfaces/bookings_list
-    A's booking list contains B's "globex-booking"
---- FAIL: TestTenancy_readSurfaces/slots_for_B's_event_type_on_A's_host
-    B's event type produced slots on A's host: {…"host_ids":["globex-user"]…}
---- FAIL: TestTenancy_readSurfaces/public_event_type_page_for_B's_slug_on_A's_host
-    B's booking page rendered on A's host: status 200
---- FAIL: TestTenancy_bookingByIDIsNotFoundAcrossWorkspaces
-    B's booking id on A's host: status = 200, want 404: {"id":"globex-booking",…}
---- FAIL: TestTenancy_mcpToolCallOverHTTP
-    A's MCP list_bookings returned B's booking "globex-booking"
-    B's MCP list_bookings returned A's booking "acme-booking"
-```
-
-⚠️ Worth stating plainly: **that is what this code does without the NOBYPASSRLS
-role.** It is why `RequireTenantPair` skips loudly rather than falling back, and
-why `VerifyRoles` refuses the boot.
-
-### ⚠️ A trap the fixture paid for
-
-`server.New`'s `drain` blocks until the worker finishes its poll cycle, and the
-worker only stops when its context is done. Passing `context.Background()` gives a
-**green test body and a hang in `Worker.Wait`** at cleanup, which reads as a
-deadlock in the code under test. `main.go` cancels then drains; the fixture now
-does the same.
-
----
-
-## Carried into later boundaries
-
-⛔ **Vendor webhooks (B6).** `POST /v1/livekit/webhook`, its
-`/v1/livekit/egress-webhook` alias, and `POST /v1/stripe/webhook` are classified
-`Platform` today, which gets them far enough to find their row and no further.
-They arrive at whatever host the vendor was given and carry no tenant Host, so
-each must **resolve its workspace from the row it names** — the recording's `room`,
-the booking's `stripe_session_id` — on the platform handle, and then hand off to
-`h.forWorkspace(ws)` for **all** processing. A test per webhook that a room or
-session belonging to B, handled on the platform path, writes only into B.
-
-⛔ **Every INSERT through a `Platform`-wrapped route or the platform API must name
-`workspace_id` explicitly.** The platform handle binds `''`, and the column default
-is `COALESCE(current_setting('app.workspace_id', true), 'default')` — so a write
-that omits the column lands in **`default`**, silently, rather than failing. The
-e2e fixture already has to do this for `workspaces` and `server_settings`. B6 owes
-a test on the platform API's create path that the row carries the **requested**
-workspace id, not `default`.
-
-⚠️ **The platform `/metrics` endpoint** (on `feat/platform-hooks`) reads the `jobs`
-table, which is a tenant table. At integration it must read through `Platform()`:
-on the application handle it would report one workspace's queue, and on the unbound
-handle, zero.
-
-## The identity-resolution sweep
-
-Every read whose PURPOSE is to resolve an identity or a tenant **before one is
-bound**. Three had already been fixed one at a time (`RequireAuth`,
-`MCPCallerMiddleware`, `VerifyMCPBearer`); this is the enumeration, so the fourth
-is not found by another failing test.
-
-The rule the table applies: **a read whose job is to discover the tenant cannot be
-bound to it.** The corollary, which is what the (c) rows are: **a write on a
-Platform-wrapped route must NAME `workspace_id`**, because the platform handle
-binds `''` and the column default is
-`COALESCE(current_setting('app.workspace_id', true), 'default')` — so an omitted
-column does not fail, it lands the row in the default workspace.
-
-| # | site | credential / lookup | route class | verdict |
-|---|---|---|---|---|
-| 1 | `auth.go:85,97` | `api_keys.key_hash` → user | any (middleware) | **(a)** `platformDB()` |
-| 2 | `auth.go:113` | `sessions.id` → user | any (middleware) | **(a)** `platformDB()` |
-| 3 | `mcp_oauth.go:86` | `users` role + workspace | `/mcp` | **(a)** `platformDB()` |
-| 4 | `mcp_oauth.go:133,141` | `oauth_access_tokens.token_hash` | `/mcp` | **(a)** `platformDB()` |
-| 5 | `mcp_oauth.go:148,151` | `api_keys.key_hash` (bearer) | `/mcp` | **(a)** `platformDB()` |
-| 6 | `mcp_oauth_authorize.go:409` | `sessions.id` → consenting user | Platform | **(a)** `h.db` **is** the platform handle inside `Platform()` |
-| 7 | `mcp_oauth_authorize.go:216,223` | `oauth_auth_codes.code_hash` | Platform | **(a)** same |
-| 8 | `mcp_oauth_authorize.go:250` | `oauth_access_tokens.refresh_hash` | Platform | **(a)** same |
-| 9 | `mcp_oauth.go:284`, `:220`, `mcp_oauth_authorize.go:344` | `oauth_clients.client_id` | Platform | **(a)** global table, no `workspace_id`, exempt from RLS by design (D2) |
-| 10 | `magic_link.go:68,100,115` | `magic_link_tokens.token_hash` | HostWorkspace | **(b)** the link was mailed from that workspace's own public host |
-| 11 | `invites.go:228,278` | `invite_tokens.token_hash` | HostWorkspace | **(b)** same |
-| 12 | `booking/service.go:386` | `booking_manage_tokens.token_hash` | HostWorkspace | **(b)** and this is how D10's "the token's booking belongs to that workspace" is enforced — by the policy, not a predicate |
-| 13 | `idempotency.go:37,51,63,73` | `idempotency_keys` PK | HostWorkspace | **(b)** PK is now `(workspace_id, key)`; two tenants may reuse a key |
-| 14 | `auth_google.go:105` | `sessions.id` (logout) | HostWorkspace | **(b)** a session of B on A's host matches nothing, which is the right answer |
-| 15 | `apikey.go`, `invites.go` admin, `mcp_oauth_admin.go` | by `user_id` / `id` | CredentialWorkspace | **(b)** bound, and that is what scopes them |
-| 16 | **`mcp_oauth_authorize.go:163`** | `INSERT oauth_auth_codes` | Platform | ⛔ **(c)** named no `workspace_id` |
-| 17 | **`mcp_oauth_authorize.go:279`** | `INSERT oauth_access_tokens` | Platform | ⛔ **(c)** named no `workspace_id` |
-| 18 | **`setup.go:75,84`** | `INSERT users` + `api_keys` | Platform | ⛔ **(c)** would seat the first owner and a live key in `default` |
-
-### (c) 16 and 17 — the OAuth grant landed in the wrong tenant
-
-⛔ **And it still worked, which is why nothing caught it.** `VerifyMCPBearer` reads
-on the platform handle, which bypasses the policies, so an agent could complete
-the Connect flow and call tools normally. What broke was **ownership**: the
-workspace's Connected-apps page (`GET /v1/oauth/connections`, a
-CredentialWorkspace route on the bound handle) could neither list nor revoke the
-grant, and deleting the workspace would not have cascaded it. A revocation UI that
-silently cannot revoke is worse than one that is absent.
-
-Fixed by naming `workspace_id`, resolved through a new
-`(*Handler).workspaceOfUser` on the platform handle.
-
-`TestSweep_oauthGrantLandsInTheOwnersWorkspace` drives the real flow — `POST
-/oauth/register`, the consent page and its CSRF cookie, the decision POST, then
-`POST /oauth/token` with PKCE S256 — and asserts the issued row's `workspace_id`
-through the platform handle, plus the observable consequence: A's Connected-apps
-page lists the grant and B's does not.
-
-### (c) 18 — `POST /v1/setup` in multi-tenant mode
-
-Platform-wrapped, and it creates the first user **plus a live API key**. Both would
-land in `default`: a working credential in a tenant nobody owns and no host
-reaches. It now 404s when `MULTI_TENANT` is set — 404 rather than 403 because on a
-multi-tenant instance the endpoint does not exist; workspaces and their owners come
-from the platform API.
-
-⚠️ **Honest scope: this is reachable only before any user exists in any
-workspace.** Setup's own "workspace already configured" guard (409) fires once
-there is one, which the negative control below shows. So it is a narrow window —
-a freshly provisioned multi-tenant database between migration and the first
-platform-API call — and defence in depth after that.
-
-### Controls
-
-Positive: all three sweep tests pass on the PostgreSQL lane.
-
-Negative, both fixes reverted:
-
-```
---- FAIL: TestSweep_oauthGrantLandsInTheOwnersWorkspace
-    tenancy_sweep_test.go:81: no code in the redirect
-    "http://127.0.0.1:9999/cb?error=server_error&error_description=could+not+issue+code&…"
---- FAIL: TestSweep_setupIsRefusedInMultiTenantMode
-    tenancy_sweep_test.go:149: POST /v1/setup: status = 409, want 404: {"error":"workspace already configured"}
-```
-
-⚠️ Both controls fail, but neither fails at the assertion I predicted, and that is
-worth recording rather than smoothing over. The OAuth one fails **earlier**: with
-`workspace_id` unnamed the auth-code write does not complete at all, surfacing as
-`could not issue code`. I did not have time to establish whether that is the policy
-refusing the write or an artifact of the reverted statement, so **the mechanism is
-unconfirmed** — what is confirmed is that the test distinguishes fixed from
-unfixed. The setup one fails on the status code only, because the fixture has
-users and the 409 guard fires first; it does **not** demonstrate a row being
-written, for the reason in the scope note above.
-
-### ⚠️ One assertion I had to correct, and it is a trap worth knowing
-
-The manage-page test first asserted `status != 200` for B's token on A's host. It
-failed: `ManagePage` renders **200 with `TokenInvalid: true`** for an unknown
-token, by design — it is a booker-facing page, not an API. The isolation was
-working; the assertion was wrong. It now asserts on content (none of B's booking
-id, host name or attendee address appears). A status-code assertion against a
-surface that renders its own errors proves nothing.
-
-## Boundary 4 — per-tenant runtime state — DONE (with one documented gap)
-
-Five Set/get singleton pairs on `shared`, each behind its own `sync.RWMutex`,
-became five `*tenantCache[T]`: **mailer, LLM, Zoom, Stripe, LiveKit**. Each value
-is built lazily from **that workspace's** `server_settings` row through the
-**bound** handle, and replaced when that workspace saves. The settings-save
-handlers needed **no edit**: they already call `SetX(...)` after writing, and
-`SetX` now writes at `h.cacheKey()`, so a save on a credential-scoped handler
-primes its own key and nobody else's.
-
-`internal/handler/tenantcache.go` is 90 lines and generic. Three things in it are
-deliberate:
-
-- **The key is `""` in single-tenant mode, not `"default"`.** One entry, built on
-  first ask, replaced by `SetX` exactly as before — so the map cannot grow past
-  one and nothing that calls `ForWorkspace` can make it.
-- **`present` is separate from `entries`, because nil is a MEANINGFUL value.** A
-  workspace with no Stripe credentials caches a nil `*stripe.Client`; if absence
-  and nil were the same thing, every request would rebuild it. A test pins that a
-  read after `SetStripe(nil)` does not grow the cache.
-- **The builder runs OUTSIDE the lock**, because every builder reads
-  `server_settings` — holding the write lock across a round trip would serialise
-  every tenant behind the slowest. The cost is that two concurrent
-  first-requests may both build; the first store wins and the loser is discarded.
-  Clients are stateless value wrappers, so that is waste, not incorrectness, and
-  `TestTenantCache_getBuildsOnceUnderContention` asserts all 32 callers get **one
-  value** (measured: 32 gets, 1 builder).
-
-### `mailer.From()` is new, and it is what makes the assertion possible
-
-The sender address is the only per-workspace value a built mailer exposes from
-outside, so `*SMTP`, `*Resend` and `*Live` (delegating) gained a `From()`.
-Without it the test could only assert that two mailers are different pointers,
-which a shared cache would also satisfy.
-
-### The negative control lives in the tree
-
-`TestTenantCache_keyIsWhatSeparatesThem` builds the same two mailers twice: once
-under the real keys, once under a key stubbed to `""`. Both halves are asserted,
-so the test fails if the real keys collide **and** if the stubbed key does not:
-
-```
-tenantcache_test.go:143: key stubbed to "": B would send as "bookings@acme.example" instead of "hello@globex.example"
-```
-
-That is the bug in one line — B's booking confirmations going out as A.
-
-### ⛔ A single handle cannot tell two workspaces apart, and the first draft of these tests did not
-
-`db.ForWorkspace` is the **identity function** on a handle that did not come from
-`OpenPair`, so every "scoped" copy read the same rows and the first version of
-this file compared a value with itself — it failed as
-`mailer *mailer.Noop exposes no From address`, which reads like a builder bug
-rather than a harness one. The four workspace-distinguishing cases now take a real
-pair through `dbtest.RequireTenantPair` and skip loudly on SQLite; the two
-pure-cache cases (`singleTenantKeepsOneEntry`, `getBuildsOnceUnderContention`) do
-not need one and run on both lanes.
-
-### ⚠️ The gap: the calendar Service is still a process-wide singleton
-
-`getCal` is unchanged. This is a scope decision, stated rather than hidden:
-
-- The `calendar.Service` is a registry of **providers** keyed by the instance's
-  Google/Microsoft OAuth **app** credentials, and D7 keeps `googleAuth` /
-  `microsoftAuth` platform-level. So the thing being cached is not obviously
-  per-tenant in the way an SMTP transport is.
-- Each provider (`gcal.New`, `microsoft.New`, `caldav.New`) **captures a `*db.DB`
-  at construction**. Making the Service per-tenant needs a `ForDB` on the Service
-  and on all three providers, plus the config plumbing to rebuild them per
-  workspace — more than this boundary.
-- **What that means today, measured against the design rather than guessed:** on a
-  multi-tenant instance the captured handle is the **unbound** application handle,
-  which under the policies matches no row. So calendar reads return nothing and
-  the integration is **inert**, not cross-tenant. That is the safe failure, but it
-  is a failure: a multi-tenant deployment has no working calendar sync until this
-  is finished. It belongs with B5, which touches the reconciler anyway.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-All seven cases pass **under `-race`** on the PostgreSQL lane:
-
-```
---- PASS: TestTenantCache_mailerIsPerWorkspace (1.11s)
---- PASS: TestTenantCache_keyIsWhatSeparatesThem (1.14s)
---- PASS: TestTenantCache_saveInvalidatesOnlyThatWorkspace (1.14s)
---- PASS: TestTenantCache_singleTenantKeepsOneEntry (0.78s)
---- PASS: TestTenantCache_concurrentWorkspaces (1.33s)
---- PASS: TestTenantCache_getBuildsOnceUnderContention (0.00s)
---- PASS: TestTenantCache_llmAndStripeBuildFromTheirOwnRow (1.11s)
-```
-
-## Boundary 5, part one — the calendar gap closed, and boot priming gated
-
-⚠️ **B5 deliverables 2, 3 and 5 are NOT in this commit** — the worker's claim loop,
-the reconciler, and the CLI subcommands. This lands 1 and 4, which separate
-cleanly from the rest and close the gap B4 left open.
-
-### The calendar gap (deliverable 1) — `ForDB` through the Provider interface
-
-B4 left `getCal` as a process-wide singleton and called it "inert rather than
-cross-tenant". Inert is not shippable: calendar connections are the product.
-
-`calendar.Provider` gains **`ForDB(handle *db.DB) Provider`**, implemented by all
-three backends as a shallow copy with the handle replaced. No import cycle: all
-three already import `internal/calendar` for `CalendarInfo`, and `calendar` imports
-none of them. `calendar.Service.ForDB` rebuilds its provider map through each
-provider's own `ForDB` and carries `primary` over, so which backend claims a new
-connection does not change per workspace.
-
-⛔ **The OAuth APP configuration stays platform-level, per D7** — client id,
-secret, redirect, encryption key identify the *Calnode instance* to Google and
-Microsoft, not the tenant. So `ForDB` is deliberately a shallow copy: same config,
-different handle. `shared` now holds `calBase` (the registry boot installs) and
-`calCache` (the per-workspace bound copies), and **`getCal` is the only reader** —
-returning `calBase` directly is the bug this splits apart.
-
-Single-tenant returns `calBase` itself rather than a rebound copy: one workspace,
-one handle, so rebinding would allocate a second Service and every provider in it
-for no behaviour change. `SetCalendar` invalidates the cache, so `SetCalendar(nil)`
-is visible immediately instead of being shadowed.
-
-**Why CalDAV carries the test:** it needs no instance-level OAuth app, so the test
-is about the handle and not about credentials. Two workspaces, one
-`calendar_connections` row each, then per workspace: `Connected` and
-`HasDestination` are true for its own user and **false for the other's**, with a
-positive control through the platform handle that both rows exist (so a `false` is
-the policy, not an empty table). `Disconnect` is the write half — A asking to
-disconnect B's user must leave B's row intact, whether or not it errors.
-
-Negative control, same shape as the mailer's and in the tree:
-
-```
-calendar_tenancy_test.go:229: key stubbed to "": B's service sees A's connection = true, its own = false
-```
-
-That is one tenant's free/busy deciding another's availability — the failure mode
-that matters here, and it is worse than the mailer's, because it is silent.
-
-### Boot priming (deliverable 4) — made single-tenant-only, not removed
-
-Every `LoadXSettingsFromDB(db, encKey)` in `server.New` reads `server_settings`
-through the **unbound** application handle. In multi-tenant mode that matches no
-row, so priming installed nothing and logged "not configured" for an instance whose
-tenants are all configured — a misleading boot log and six pointless round trips.
-
-`primeFromDB := !cfg.MultiTenant` gates all six through a small
-`loadIfSingleTenant` generic that returns `(nil, nil)` when priming is off, which
-every call site already treats as "not configured in the database". Multi-tenant
-boot now logs once, plainly:
-
-```
-multi-tenant mode: per-workspace settings are built on first use, not primed at boot
-```
-
-**Gated rather than removed**, and the reason is specific: it is the only path that
-seeds env-var SMTP into the database on first boot (`seedSMTPToDB`), and on a
-single-tenant instance it is what makes the first request fast instead of lazy.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean. The four calendar
-cases pass **under `-race`**:
-
-```
---- PASS: TestCalendar_providersSeeOnlyTheirWorkspace (1.27s)
-    --- PASS: TestCalendar_providersSeeOnlyTheirWorkspace/acme
-    --- PASS: TestCalendar_providersSeeOnlyTheirWorkspace/globex
---- PASS: TestCalendar_disconnectCannotReachAnotherWorkspace (1.39s)
---- PASS: TestCalendar_keyIsWhatSeparatesThem (1.35s)
---- PASS: TestCalendar_singleTenantReusesTheRegistry (0.89s)
-```
-
-### Still owed by B5
-
-2. **Worker.** The claim loop must run on the platform handle across tenants and
-   process each job on `ForWorkspace(job.workspace_id)` with the per-tenant caches.
-   Today it holds one handle from `worker.New(db, …)` and one `*mailer.Live`, so on
-   a multi-tenant instance it claims nothing (`jobs` is a tenant table, the handle
-   is unbound). Two-workspace claim-loop test owed.
-3. **Reconciler.** `StartCalendarReconciler` iterates state on one handle; it needs
-   to enumerate `workspaces` on the platform handle and then run each pass bound.
-   ⚠️ It is started from `server.New` only when `calSvc.Any()`, which after
-   deliverable 4 is still true (providers are registered from env/CalDAV, not from
-   `server_settings`) — so it does run, and it currently runs unbound.
-4. **CLI.** `mcp` (stdio), `reset-admin`, `rotate-key`, `recover-key` still open one
-   handle from `DATABASE_URL`. `rotate-key` and `recover-key` are genuinely
-   platform-wide (`crypto_keystore` is exempt, one DEK per process, D3);
-   `reset-admin` and `mcp` stdio are per-workspace and have no way to say which.
-
-## Boundary 5, part two — the worker claims across tenants and works inside one
-
-⚠️ **Deliverables 3 (reconciler) and 5 (CLI) are NOT in this commit.**
-
-### The claim loop and the work are on opposite sides of the boundary
-
-That is the whole shape of it, and getting either side wrong is silent:
-
-| | handle | why |
-|---|---|---|
-| claim, reaper, housekeeping sweeps | **platform** | one queue ordered by `run_at` across every tenant; a bound handle would serve one workspace and starve the rest |
-| processing a claimed job | **`ForWorkspace(job.workspace_id)`** | every read is one tenant's; the platform handle would read across them |
-
-⛔ **The claim query carries no workspace predicate**, deliberately, and now selects
-`workspace_id` alongside. This is what migration 00060's workspace-free
-`idx_jobs_pending_global` exists for — a workspace-leading index cannot serve an
-ordered global scan.
-
-`worker.TenantDeps{DB, Mailer, Webhook}` is what a job is processed with, supplied
-by `WithTenantResolver`. Unset — single-tenant — `depsFor` returns the Worker's own
-handle and mailer, so nothing changes. `sendReminder` and `deliverWebhook` take
-`deps` and use `deps.DB` / `deps.Mailer` / `deps.Webhook` rather than the Worker's
-fields.
-
-### Custom handlers took a new signature, not a context value
-
-`RegisterHandler` is now `func(ctx, workspaceID, payload) error`. The packet offered
-context smuggling or a signature change and asked for the smaller: the signature is
-**two call sites** in `server.New` and two method heads in `notetaker.go`, versus a
-context key that every future handler author has to know exists. Each notetaker job
-starts with `h = h.workspaceForJob(workspaceID)` — **before any row is read**,
-because the receiver the worker calls it on is unbound.
-
-`handler.TenantRuntime(workspaceID)` returns `(*db.DB, mailer.Mailer,
-*webhook.Service)` and `server.New` adapts it into `worker.TenantDeps`. The handler
-deliberately does **not** import the worker package: the worker owns the queue, the
-handler owns the per-tenant state, and one closure joins them.
-
-### The tests
-
-`TestWorker_processesEachJobInItsOwnWorkspace` — one reminder each, both due, one
-`Poll`. Both jobs reach `done` (the "one poll delivers both" half), each was sent
-with its **own** workspace's mailer, to its own attendee, and a cross-check asserts
-neither mailer saw the other's.
-
-`TestWorker_webhookSignsWithItsOwnWorkspacesSecret` — each workspace registers a
-webhook at its own path on one `httptest` server, so the signature that arrives can
-be attributed. The two signatures must differ, and the two issued secrets must
-differ. A shared `webhook.Service` would sign one tenant's payloads with another's
-secret and every subscriber's verification would start failing — which is the kind
-of break that gets reported as "your webhooks are broken", not as a tenancy bug.
-
-`TestWorker_customHandlersReceiveTheWorkspace` — the signature change, asserted by
-job rather than by inspection.
-
-### The negative control is the old shape
-
-```
-tenancy_test.go:340: negative control: a worker on the application handle claimed 0 of 1 due jobs,
-with no error — reminders and webhook deliveries would silently never fire
-```
-
-It runs the same due job twice: once through the platform handle (1 reminder sent),
-then requeued and run through the **application** handle (0 sent, job still
-`pending`). `jobs` is a tenant table and the application handle is unbound, so it
-matches no row — the loop runs, finds nothing, logs nothing. That is the third
-failure mode, distinct from leakage and from starvation, and it is what this
-deliverable removed.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean. The whole worker
-package passes **under `-race`**, pre-existing cases included:
-
-```
---- PASS: TestWorker_processesEachJobInItsOwnWorkspace (1.75s)
---- PASS: TestWorker_webhookSignsWithItsOwnWorkspacesSecret (1.76s)
---- PASS: TestWorker_theOldShapeClaimsNothing (1.69s)
---- PASS: TestWorker_customHandlersReceiveTheWorkspace (1.93s)
---- PASS: TestWorker_sendsReminderForConfirmedBooking (1.39s)
---- PASS: TestWorker_deliversSuccessfully (1.25s)
---- PASS: TestWorker_purgesExpiredManageTokens (1.36s)
-    … and the rest of the package
-```
-
-### ⚠️ Housekeeping sweeps stay cross-tenant, and that is correct
-
-The `Poll` preamble deletes expired manage tokens, sessions, magic links,
-idempotency keys and auth codes, purges old webhook deliveries, and releases stale
-Stripe payment holds — all on the platform handle, all without a workspace
-predicate. That is deliberate: they are retention rules, not tenant logic, and
-running them per workspace would mean N times the statements to express one policy.
-The Stripe hold backstop is the one worth naming, because it **writes**
-(`bookings.status = 'cancelled'`) across tenants — it is keyed on
-`payment_status = 'pending' AND created_at < cutoff`, which is a property of the
-row and not of the tenant, so a global sweep is the right shape. If that ever needs
-to differ per workspace it has to move.
-
-## Boundary 5, part three — the reconciler sweeps per workspace
-
-`reconcileCalendar` is now a dispatcher: `reconcileTargets()` enumerates active
-workspaces on the **platform** handle, and each `reconcileCalendarPass()` runs on a
-handler bound to one of them. `activeWorkspaceIDs` lives beside the other workspace
-reads and filters `status = 'active'` **there** rather than at each call site, so a
-new periodic loop cannot forget.
-
-⛔ Suspended workspaces are skipped, and that is a decision rather than an
-optimisation: a suspended tenant answers 503 on its own public and admin surfaces
-(D12), so healing its calendar in the background would be doing work on its behalf
-that it can neither see nor stop.
-
-Single-tenant short-circuits before the query — one target, the handler itself, no
-round trip per sweep.
-
-### The tests, and what each half proves
-
-`TestReconciler_enumeratesActiveWorkspacesOnly` — three workspaces, one suspended.
-It asserts the target set **and** that each target's handle is bound to the same
-workspace it is labelled with (`target.db.Workspace() == id`), because a target
-list that is right while the handles are wrong would pass a weaker check.
-
-`TestReconciler_healsItsOwnWorkspaceAndSkipsSuspended` — a cancelled booking still
-carrying a calendar event id, in each of an active and a suspended workspace. The
-host has no calendar connection, so `CancelEvent` has nothing to call and the pass
-clears the id without a network. Positive control on the fixture first: both rows
-start stale. After the sweep the active one is cleared and the suspended one is
-byte-identical.
-
-`TestReconciler_theOldShapeHealsNothing` is the negative control — one
-`reconcileCalendarPass()` on the unbound application handle, which is what the
-reconciler was until this commit:
-
-```
-calendar_reconcile_tenancy_test.go:183: negative control: a reconciler pass on the unbound
-application handle healed 0 of 1 diverged bookings, with no error — every stale calendar
-event would stay stale forever
-```
-
-It then runs the fixed sweep over the same fixture and asserts the row IS healed, so
-the difference is demonstrably the binding and not the fixture.
-
-Measured sweep target set with a suspended tenant present:
-`map[acme:true default:true initech:true]` — the suspended `globex` absent, and the
-seeded `default` workspace present because it is active in every migrated database.
-
-## Boundary 5, part four — the CLI subcommands
-
-Which of the four needs what follows from what it touches, so the classification is
-data (`platformWideCLI`) and a test asserts it rather than re-deriving it.
-
-| command | touches | under `MULTI_TENANT` |
-|---|---|---|
-| `rotate-key` | `crypto_keystore` | **unchanged** |
-| `recover-key` | `crypto_keystore` | **unchanged** |
-| `reset-admin` | `users` (tenant) | **requires `--workspace=<id>`** |
-| `mcp` (stdio) | everything | **refused** |
-
-`crypto_keystore` is exempt from tenancy (D2) because there is one DEK per process
-(D3) — it has no policies at all, so `DATABASE_URL`'s handle reaches it whether or
-not RLS is enabled. Both key commands now carry a comment saying that, and saying
-that per-tenant DEKs would make it wrong.
-
-### ⛔ `reset-admin` was a real hole, not a hygiene issue
-
-Since D9 the unique on `users` is **`(workspace_id, email)`**, not `email`. So
-`UPDATE users SET password_hash = ? WHERE email = ?` on an unscoped handle matches
-**every workspace that has a user with that address** — and a shared address across
-an agency's client workspaces is the ordinary case, not a contrivance. The negative
-control measures it:
-
-```
-tenancy_test.go:222: negative control: one unscoped `WHERE email = "owner@example.com"`
-reset 2 workspaces' owners — since D9 the unique is (workspace_id, email), so a shared
-address is legal and common
-```
-
-A recovery tool that quietly hands an operator access to tenants nobody asked about
-is worse than one that refuses. `--workspace` is accepted in both `--workspace=id`
-and `--workspace id` forms, anywhere among the positional arguments, and is validated
-against the same `[a-z0-9_-]{1,64}` shape `db.ForWorkspace` enforces. In
-single-tenant mode it is **accepted and ignored** rather than rejected, so a script
-written for a multi-tenant fleet keeps working against one instance.
-
-### `mcp` stdio is refused, and the message names the path that works
-
-The stdio transport carries no credential and no Host, so there is nothing to
-resolve a tenant from; the tools would run on the unbound handle, which matches no
-row, and the operator would see an empty workspace with no explanation. The refusal
-points at `POST /mcp` with a workspace's API key or OAuth token, which resolves the
-tenant from the credential (D10). A test asserts the message mentions the HTTP
-transport, the path, and the credential — a refusal that does not say what to do
-instead is a dead end.
-
----
-
-## Every remaining cross-tenant read and write, and why each is correct
-
-For B7's proof to assert this list is complete. Anything reaching more than one
-workspace's rows is here; everything else is bound.
-
-### Platform handle, by design — the tenant root and the exempt tables
-
-| site | what | why correct |
-|---|---|---|
-| `workspaceByHost`, `workspaceByID`, `activeWorkspaceIDs` | `workspaces` | resolving *which* tenant; `workspaces` is exempt and carries a SELECT-only policy for the app role (D2) |
-| `RequireAuth` (api_keys, sessions) | credential → user | the read that DISCOVERS the tenant cannot be bound to it; those uniques are global for exactly this (D9) |
-| `MCPCallerMiddleware`, `VerifyMCPBearer` | bearer → user | same |
-| `workspaceOfUser` | `users.workspace_id` | resolves the tenant for a Platform route's write |
-| `/oauth/*` handlers | auth codes, tokens, clients | Platform-wrapped: `h.db` **is** the platform handle; the two INSERTs name `workspace_id` (the sweep's finding 16/17) |
-| `rotate-key`, `recover-key` | `crypto_keystore` | exempt (D2), one DEK per process (D3) |
-| goose migrations, `EnableRLS`, `VerifyRoles` | DDL and role attributes | schema-level, not row-level |
-
-### Worker, on the platform handle — one queue, and retention rules
-
-| site | what | why correct |
-|---|---|---|
-| the claim query + reaper | `jobs` | ONE queue ordered by `run_at` globally; a bound loop would serve one tenant and starve the rest. This is what 00060's `idx_jobs_pending_global` is for |
-| purge expired manage tokens, sessions, magic links, idempotency keys, oauth auth codes | 5 `DELETE`s | retention rules keyed on `expires_at`/`created_at`, properties of the row and not of the tenant; per-workspace would be N statements to express one policy |
-| purge finished webhook deliveries | `DELETE` | same, 30-day retention |
-| ⚠️ **Stripe payment-hold backstop** | **`UPDATE bookings SET status='cancelled'`** | the only cross-tenant **WRITE** left. Keyed on `payment_status='pending' AND created_at < cutoff`, a property of the row. ⛔ **It has to move if hold timeouts ever become per-workspace**, and it is the one entry on this list a reviewer should push back on |
-
-### Reconciler
-
-Enumerates on the platform handle, then every pass is bound. No cross-tenant read
-inside a pass.
-
-### Not yet correct — known, and owed to B6
-
-| site | state |
-|---|---|
-| `POST /v1/livekit/webhook` + its alias, `POST /v1/stripe/webhook` | `Platform`-wrapped so they can find the row they name; the processing after that is **not** yet bound. Must resolve the workspace from the room / session and hand off to `forWorkspace` |
-| ~~`/v1/auth/sso` hand-off (D11), `clientIP` rate-limit keys (D14)~~ | ✅ **the VERIFY halves landed with the merge below.** What remains of D11 is the MINT half: no OAuth callback issues an SSO token yet, so nothing exercises the endpoint in production. Plan at the end of this file |
-| ~~`/metrics`~~ | ✅ reads `jobs` through `Platform()` |
-
----
-
-## Integration — `feat/platform-hooks` merged (commit `8a93fad`)
-
-Merged **into** `feat/multi-tenant` with `--no-ff` before B6, because three of that
-branch's four features are things B6 was otherwise going to have to fake: the SSO
-endpoint D11 hands off to, the trusted-proxy client IP D14 keys on, and `/metrics`.
-
-Six conflicted files, ten hunks. The commit message carries the per-file resolution; what
-belongs here is the part that was a **decision** rather than a merge.
-
-### The three new routes, classified
-
-```
-172 routes: 31 host-scoped, 107 credential-scoped, 26 platform, 8 allowlisted
-```
-
-| route | class | why |
-|---|---|---|
-| `GET /metrics` | **Platform** | queue depth is an INSTANCE number. Its `jobs` read goes through `Platform()` inside the handler as well as being registered unscoped — a bound read would report one workspace's backlog as if it were the whole queue, an unbound one zero, and both are wrong in a way a dashboard cannot show you |
-| `GET /v1/auth/sso` | **Platform** | no tenant Host and no credential yet. The TOKEN is the credential and the workspace is its `wid` claim |
-| `POST /v1/auth/sessions/revoke-all` | **credential-scoped** | whose sessions to cut is a question about one workspace's users. All three of its statements (`users`, `sessions`, `oauth_access_tokens`) are then scoped by the bind, which is what makes a target id from another workspace a 404 rather than a revocation |
-
-⚠️ **The classification gate caught the third one, and the cause is worth knowing:
-`routes_classified_test.go` scans `server.go` LINE BY LINE.** The platform branch had
-written the registration across two lines, so the scanner saw a pattern with an empty
-expression and reported it unclassified. A wrapper on a continuation line is invisible to
-the gate. Every registration in that file is therefore one line, however long.
-
-### `sso_nonces` is EXEMPT, not a tenant table
-
-The migration is renumbered `00059` → **`00061`** in both dirs (00060 is tenancy);
-`knownMigrationCount` 60 → 61.
-
-A jti is **global**. The question the table answers is "has this exact token been spent",
-and the answer must not depend on which workspace the token names — per workspace, the
-same jti could be replayed once per tenant, which is strictly weaker for no benefit. It
-also has no owner at the moment the row is written: the nonce is claimed *before* the
-`wid` claim has been trusted. So it joins `workspaces`, `crypto_keystore`,
-`goose_db_version` and `oauth_clients` in `db.ExemptTables`, and
-`TestTenancy_tableListsCoverTheSchema` is updated with it.
-
-⛔ **The Postgres file declares `expires_at TEXT COLLATE "C"`, and without it the merge
-would have redded a gate nobody was thinking about.** The worker purges the table with a
-lexicographic `expires_at < ?` — exactly what migration 00059 pinned the other 54 TEXT
-timestamps for — and `collation_test.go`'s audit matches by column NAME, so a new `_at`
-column is caught whether or not anyone remembers. `wantTimestampColumns` 56 → 57.
-
-### ⛔ The `wid` claim was documentation, and the merge made it load-bearing
-
-The platform branch parsed `wid` and **deliberately ignored** it ("an instance is a
-single workspace today"). In multi-tenant mode it is now required, validated against
-`db.ValidWorkspaceID`, and read back through the platform handle, so a token naming a
-deleted, suspended or public-host-less workspace is refused instead of seating a user
-nobody can reach. Single-tenant is untouched: `wid` is ignored, `aud` is `BASE_URL`.
-
-**The audience is the WORKSPACE's public host, not `BASE_URL` (D11).** The hand-off exists
-precisely because the identity host cannot set a cookie on a tenant's domain, so the token
-is minted for that domain — and a token for tenant A must not be spendable on tenant B's
-host, which would seat a session on B for a person A vouched for.
-
-**Every statement the endpoint runs now names the workspace**, and this is the finding
-rather than a tidy-up. `/v1/auth/sso` is Platform-wrapped, so `h.db` is the platform
-handle: it bypasses the policies and binds `''`. Since D9 the unique on `users` is
-`(workspace_id, email)`, so one address legitimately exists in several workspaces — and
-an unqualified `WHERE email = ?` resolves an **arbitrary** one of them. It is the
-`reset-admin` hole again, reachable here by anyone holding the shared secret. Same fix
-for `ssoOwnerExists`, which counted owners instance-wide: unscoped, the first SSO user of
-every workspace after the first would silently never be its owner.
-
-`createSessionIn(…, workspaceID)` is how the session names its tenant. An empty
-`workspaceID` keeps the original statement, so the other seven callers — all on handles
-already bound to the request's workspace, where the bind fills the column — are untouched.
-⚠️ It matters beyond bookkeeping: every later request for that user runs on a **bound**
-handle, which could neither read that session nor delete it on logout.
-
-Negative control, the workspace predicate removed from the lookup only:
-
-```
---- FAIL: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace
-    sso_tenancy_test.go:100: no user shared@example.test in workspace globex: sql: no rows in result set
-```
-
-That is the bug stated exactly: the second workspace's hand-off found the FIRST
-workspace's user by email, so no globex user was ever created — and the session it minted
-pointed at acme's person. `sessions.user_id` is global, so the foreign key would not have
-complained.
-
-### D14 wired, and the two halves pull in opposite directions
-
-`rateLimitKey` is `(workspace host, client IP)` when `SetMultiTenantLimits` is on, the IP
-alone otherwise. Both halves are load-bearing and each is useless without the other:
-
-- **without the workspace**, two tenants' bookers behind one address — a shared office, a
-  corporate NAT, a CDN — share a bucket, so the busier workspace spends the quieter one's
-  allowance. One tenant degrading another's service through no fault of either.
-- **without `TRUSTED_PROXY_CIDRS`**, the "IP" behind a proxy IS the proxy, so adding the
-  workspace prefix would make things WORSE: a whole tenant becomes ONE bucket and its
-  first 20 bookers a minute exhaust it for everyone else in that tenant. The prefix is
-  only safe because `remoteIP` resolves the client's own address when a trusted hop
-  forwarded it. This is why D14 waited for this branch instead of being approximated.
-
-The workspace comes from the **Host**, not from a resolved `*Workspace`: the limiter runs
-before any handler and rejecting a request must not cost a database read. An unrecognised
-host keys on the host string itself, which is the safe direction — a Host-rotating
-attacker gets a bucket per value and spends no real tenant's allowance.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-`go test ./...` **rc=0 on SQLite (30/30)** and **rc=0 on PostgreSQL (30/30)**.
-`go test -race -count=1 ./internal/handler/ ./internal/worker/` rc=0 on PostgreSQL
-(585.5s / 31.8s).
-
-The platform branch's own tests, all PASS on both lanes: `sso_test` (11),
-`session_test` (9 `RevokeAllSessions` cases), `metrics_test` (3),
-`notetaker_settings_test` (2), `trustedproxy_test` (10), `reminder_test` (9 including
-`reminderFiresBookingReminderWebhook` and `reminderWebhookCarriesTheFiringOffset`, which
-is rule 5: the webhook fires from the worker's **bound** per-workspace path through
-`deps.Webhook`, so it is signed with that workspace's secret), `i18n` and `stt`
-(fr-CA and `STT_BASE_URL` need no tenancy change and are confirmed only by building and
-passing).
-
-The tenancy suites still hold with the platform routes in the mux:
-
-```
---- PASS: TestTenancy_readSurfaces (1.02s)          --- PASS: TestSweep_oauthGrantLandsInTheOwnersWorkspace (0.97s)
---- PASS: TestTenancy_bookingByIDIsNotFoundAcrossWorkspaces (1.02s)
---- PASS: TestTenancy_credentialOnTheWrongHostIs403 (1.07s)
---- PASS: TestTenancy_writeLandsInItsOwnWorkspace (1.17s)
---- PASS: TestTenancy_mcpToolCallOverHTTP (1.00s)   --- PASS: TestSweep_setupIsRefusedInMultiTenantMode (1.07s)
---- PASS: TestEveryRouteIsClassified               --- PASS: TestSweep_tenantLocalTokensDoNotResolveAcrossHosts (1.03s)
---- PASS: TestCredentialScopedRoutesAuthenticateFirst   (107 credential-scoped routes checked)
---- PASS: TestPlatformRoutesAreTheIdentityHostSet
-```
-
-New multi-tenant cases, running rather than skipping on the PostgreSQL lane:
-
-```
---- PASS: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace (0.92s)
---- PASS: TestSSOHandoff_multiTenantRefusesABadWID (3.80s)   [missing, empty, unknown, not an id]
---- PASS: TestSSOHandoff_multiTenantAudienceIsThePublicHost (2.84s)   [identity host, another tenant, bare hostname]
---- PASS: TestSSOHandoff_multiTenantRefusesASuspendedWorkspace (1.03s)
---- PASS: TestRateLimit_workspacesBehindOneProxyDoNotShareABucket (0.00s)
---- PASS: TestRateLimit_twoBookersOfOneWorkspaceKeepTheirOwnBuckets (0.00s)
---- PASS: TestRateLimit_singleTenantIgnoresTheHost (0.00s)
---- PASS: TestRateLimitKey_portIsNotPartOfTheBucket (0.00s)
-```
-
-Negative control, the same PostgreSQL command with the password changed to `wrong` —
-these FAIL rather than skip, which is what says they were really talking to a server:
-
-```
---- FAIL: TestPostgres_timestampColumnsCollateC
-    failed SASL auth: FATAL: password authentication failed for user "postgres" (SQLSTATE 28P01)
---- FAIL: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace
-    failed SASL auth: FATAL: password authentication failed for user "postgres" (SQLSTATE 28P01)
-```
-
-### ⚠️ One correction to this file, found while merging
-
-Several notes above (the B3 carry-over list, the sweep's rule, `workspaceOfUser`'s doc)
-say that a write omitting `workspace_id` on a Platform route "lands in `default`,
-silently". That is true of a handle that never sets the parameter at all. It is **not**
-what the platform handle does: `OpenPair` binds `''` before every statement, so
-`current_setting('app.workspace_id', true)` returns the empty string rather than NULL,
-`COALESCE` keeps it, and the row fails the foreign key to `workspaces(id)` with 23503.
-The sweep's own negative control is consistent with this — it failed at "could not issue
-code" rather than by landing a row in `default`, and PROGRESS recorded the mechanism as
-unconfirmed at the time. **The remedy is identical either way** (name `workspace_id`), so
-nothing built on that reasoning is wrong; but "silently lands in `default`" overstates how
-quiet the failure is, and the distinction matters to anyone debugging a 23503 from a
-Platform route. Not corrected in place above, because those notes are the record of what
-was believed when each boundary was written.
-
-## Boundary 6, part one — the platform API (D12): create, get, patch, delete
-
-`internal/handler/platform.go`. Four routes on the identity host, all `Platform`-wrapped,
-bearer `CALNODE_PLATFORM_TOKEN` compared with `subtle.ConstantTimeCompare`.
-
-### Two gates, and they answer differently on purpose
-
-| state | answer | why |
-|---|---|---|
-| token unset | **404** | the API does not exist here, and a prober should not learn whether it could |
-| single-tenant instance | **404** | there are no workspaces to provision; same reasoning, and it is Setup's mirror image (Setup 404s in multi-tenant mode) |
-| token set, wrong token | **401** | an operator with a typo needs to tell that apart from a missing feature |
-
-### Provisioning is one transaction, and every INSERT names `workspace_id`
-
-The workspaces row, `server_settings` (id = 1 per workspace, D8), the owner user, that
-owner's first `cno_` key, the webhook subscription, the default event type and its
-availability rules. Either the tenant exists complete or it does not exist: a
-half-provisioned workspace would answer requests with no owner, or serve a booking page
-with no availability. `TestPlatform_duplicateIDOrHostIs409` asserts the rollback, not just
-the status code.
-
-⛔ **Every INSERT names `workspace_id` explicitly**, which is the rule this file exists to
-obey rather than to demonstrate. `h.db` here is the platform handle: it bypasses the
-policies and binds `''`, so an unnamed column resolves to `''` and the row fails its
-foreign key with 23503. **Reads are equally unscoped and carry their own predicate** —
-there is no policy behind this file to catch a forgotten `WHERE`.
-
-⚠️ `owner_timezone` is stored as the owner's `iana_timezone`, **not** UTC, and that is a
-correctness requirement rather than a nicety: `availability_rules` holds local `HH:MM` with
-no zone of its own, so defaulting the owner's zone would silently move the workspace's
-working hours. A test pins the stored value.
-
-### Two settings had no column, so migration 00062 gives them one
-
-`defaults.embed_allowed_origins` and `defaults.stt_base_url` are in the settled contract
-and `server_settings` had nowhere to put either — the enumerated column list has neither.
-Both are per-TENANT facts that the environment cannot express: one process-wide
-`EMBED_ALLOWED_ORIGINS` would let one tenant's allowlist govern another's embed, and the
-STT host is a residency knob, which is a property of the tenant.
-
-⚠️ **They are WRITTEN and not yet READ.** The embed CORS check still uses
-`config.EmbedAllowedOrigins` and the notetaker still uses `config.STTBaseURL`, so a
-multi-tenant deployment currently shares one embed allowlist and one STT host. Storing them
-now means a provisioned workspace does not silently lose what the caller sent; wiring the
-readers is separate work, because each has to go through the per-workspace settings cache
-(D7) rather than a process-wide read. Named here so it is not mistaken for done.
-`knownMigrationCount` 61 → 62.
-
-### The webhook secret's encoding has exactly one implementation
-
-`webhook.NewSecret` is new and the platform API calls it: the column holds the AES-GCM of
-the **raw** secret bytes, `Sign` uses those bytes as the HMAC key, and the string handed to
-the subscriber is their **hex**. A second implementation that encrypted the hex string
-would store a key the subscriber cannot reproduce, and every delivery would fail its
-signature check with nothing in the logs to point at. A caller-supplied secret must
-therefore be hex and at least 16 bytes; absent, one is generated. The INSERT itself stays
-in the provisioning transaction, where it can name `workspace_id`.
-
-### ⛔ Decision: the `default` workspace is SUSPENDED at multi-tenant boot
-
-`db.SuspendDefaultWorkspace`, called from `main` right after `EnableRLS`, idempotent, and
-non-fatal on error (a sweep over an empty workspace is waste, not damage).
-
-Migration 00060 seeds `default` because it is the workspace every single-tenant row belongs
-to and the one SQLite's column default names. On a multi-tenant instance it is a tenant
-nobody owns: no `public_host` (deliberately, so no Host reaches it), no users, no settings —
-and while it is `active`, every background sweep enumerates it, because
-`activeWorkspaceIDs` filters on `status = 'active'`.
-
-**Not in the migration, and that is the whole point:** a migration cannot see
-`MULTI_TENANT`, and in single-tenant mode `default` **is** the workspace — a suspended row
-there would make `Scoped` answer 503 to every request on the instance. The mode decides,
-and the mode is only known at boot. Suspension rather than deletion because the row is
-referenced by `server_settings` and by whatever single-tenant data a converted instance
-still holds, and because one status flip removes it from every sweep at once instead of
-adding a second exclusion rule a new loop could forget.
-`TestPostgres_defaultWorkspaceIsSuspendedAtMultiTenantBoot` asserts active-after-migrate
-(what single-tenant needs), suspended-after-call, idempotence, and that a real workspace
-beside it is untouched.
-
-### ⚠️ Two things the tests paid for
-
-- **`httptest.NewRequest` does not populate mux path values.** They come from the pattern
-  `ServeMux` matched, and these tests call the handler directly — so every `{id}` route
-  read an empty id and answered **404, which looks exactly like a missing workspace**. The
-  helper calls `SetPathValue` now.
-- **`location_type` and `routing_mode` have CHECK constraints** (migration 00001) that
-  admit no `'none'` or `'single'`. The event type seeds `'link'` / `'fixed'`, the schema's
-  own defaults, which is what a single-host event type created in the admin UI gets. The
-  first run failed with 23514 as a bare 500, and the reason was only visible with a live
-  logger.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-`go test -count=1 ./...` **rc=0 on SQLite (30/30)**.
-PostgreSQL lane, per package: `internal/handler` **rc=0** (410.2s), `internal/db`,
-`internal/server`, `internal/webhook` **rc=0**.
-
-```
---- PASS: TestPlatform_createProvisionsTheWholeWorkspace (1.04s)
---- PASS: TestPlatform_createdWorkspacesAreIsolated (1.25s)
---- PASS: TestPlatform_duplicateIDOrHostIs409 (1.10s)
---- PASS: TestPlatform_getPatchDelete (1.08s)
---- PASS: TestPlatform_tokenGate (1.08s)          [wrong token, no token]
---- PASS: TestPlatform_404WithoutATokenConfigured (0.73s)
---- PASS: TestPlatform_404OnASingleTenantInstance (0.74s)
---- PASS: TestPlatform_createValidation (11.47s)  [9 cases, each asserting nothing was left behind]
---- PASS: TestPostgres_defaultWorkspaceIsSuspendedAtMultiTenantBoot (0.76s)
-```
-
-### Still owed by B6
-
-Export/import/erasure; the SSO + OAuth hand-off on the public host (the plan is at the end
-of this file); the vendor webhooks resolving their workspace from the row they name. D13 is
-already done (B1's `config.Validate` refuses `MULTI_TENANT` with `DEMO_MODE`) and D14
-landed with the platform-hooks merge.
-
-### `embed_allowed_origins` and `stt_base_url` are READ — the D7 reader wiring, done
-
-Migration 00062 added both columns and the platform API filled them; until this commit nothing
-read them, so a multi-tenant instance shared one embed allowlist and one STT host across every
-tenant whatever its row said. Now `internal/handler/tenant_settings.go` reads both through the
-bound handle into a per-workspace `settingsCache` (the same `tenantCache` the vendor clients use):
-
-- **`embed_allowed_origins`**: the CORS wrapper became `server.PublicCORSFor(originsFor)`, with
-  `PublicCORS(list)` as the single-tenant special case. In multi-tenant mode `server.New` passes
-  `h.EmbedOriginsFor`, which resolves the request host to its workspace on the platform handle
-  (one indexed read, the route's own 404 unchanged) and answers that workspace's list. An unknown
-  host answers known=false, which the middleware turns into NO allow-origin header — never `*`.
-  An empty per-tenant list keeps the single-tenant meaning: any origin. `EMBED_ALLOWED_ORIGINS`
-  is not consulted in this mode. The 'move the check inside the handler' alternative was not
-  taken: a disallowed origin is still refused before any handler runs, exactly as today.
-- **`stt_base_url`**: `sttBaseURL()` gained one rung on top of its existing ladder — the
-  workspace's column when multi-tenant and non-empty, then `STT_BASE_URL`, then the provider
-  default. The notetaker job already runs bound (`workspaceForJob`, B5), so it needed no change.
-
-Tests: `TestTenantSettings_perWorkspaceReaders` (handler, PG: two workspaces via the platform API;
-A's own STT host and origins, B's fall-through to the process value and then the default, an
-unknown host resolving to no tenant), `TestPublicCORSFor_*` (middleware unit, both engines) and
-`TestTenancy_embedOriginsArePerWorkspace` (end to end through the real mux). Negative control,
-the multi-tenant branch in `server.New` disabled: the end-to-end test fails with `200 "*"` on
-acme's own origin, on a foreign origin, and on an unknown host — the shared-allowlist bug, seen.
-
-### ⚠️ A pre-existing upstream race, fixed here (upstream-first PR candidate)
-
-Not a tenancy bug and not caused by the merge: it reproduces on a stock single-tenant
-instance, and the fix is generic. Worth carrying upstream as its own patch.
-
-**The bug.** Two detached goroutines write the same reminder row. The booking CREATE path
-enqueues reminders from one; the RESCHEDULE path replaces them from another. Both marshal
-the identical payload `{booking_id, hours_before}`, and `jobs` carries a unique on
-`(type, payload)` — so exactly one row can exist per `(booking, hours_before)`. The
-replacement deletes the booking's non-running reminder rows and re-inserts them at the new
-time, and the losing interleaving is:
-
-```
-reschedule: DELETE …            (create's row not yet committed, so invisible to it)
-create:     INSERT at the OLD time
-reschedule: INSERT at the NEW time  ->  conflict  ->  ON CONFLICT DO NOTHING  ->  dropped
-```
-
-The reschedule's own row is the one discarded, so the reminder stays pinned to the
-**original** time — permanently, with nothing logged. A booking created and rescheduled
-inside the same second is enough. The attendee is then reminded about a time the meeting no
-longer has, or not at all if the old time has already passed.
-
-**The fix.** The reschedule's INSERT upserts; the create side keeps `DO NOTHING`, because a
-create must never overwrite a reschedule and by the time the two can collide the reschedule
-is the later fact. One side upserting makes all three interleavings agree on the
-reschedule's time. `WHERE status <> 'running'` preserves the invariant the DELETE already
-encodes — a claimed job is executing, and resetting it underneath the worker would either
-double-send or be clobbered by the worker's completion write.
-
-**Measured:** 2 failures in 60 runs before, 0 in 30 after, on PostgreSQL. The test forces
-the interleaving with an uncommitted row rather than waiting for it, and fails if no backend
-ever blocks, so it cannot pass on the easy path.
-
-⚠️ **The test that found it reported it as something else**, which is why it took a bisect:
-it polled for "any `run_at` that is not the old one", kept the last value read when its
-deadline expired, and asserted on that — so a timeout surfaced as "`run_at` is three days
-wrong". A poll loop that falls through to an assertion on stale data will misattribute every
-failure it ever catches.
-
-## Boundary 6, part two — export, import and erasure (D12)
-
-`internal/handler/platform_data.go`. Three more `Platform` routes behind the same token
-gate: `POST …/export`, `POST …/import`, `DELETE …/attendees?email=`.
-
-### The replay order is data, not convention
-
-`exportTableOrder` is a hand-ordered list (parents before children) and the document carries
-its tables as an ordered ARRAY, because import replays them in the order it receives.
-Alphabetical — `db.TenantTables`' order — would put `booking_answers` before `bookings` and
-`event_type_hosts` before `event_types`, i.e. a foreign-key violation.
-
-⛔ **`exportCoversEveryTenantTable` runs at request time**, not only in a test: it fails the
-export if any `db.TenantTables` entry is missing from the order, or if the order names
-something that is not a tenant table. `TestTenancy_tableListsCoverTheSchema` already forces a
-new table to be classified; this makes the same guarantee reach the backups, so a table added
-by a later migration cannot be silently absent from every tenant's export. Being wrong here
-produces data that was never backed up, which is exactly the class of failure nobody notices
-until they need the backup.
-
-Rows are read with `SELECT *` + `rows.Columns()` rather than 32 hand-written column lists,
-for the same reason: a migration that adds a column would otherwise stop exporting it, and
-the loss would surface only as data missing after an import. `ORDER BY 1` makes two exports
-of one workspace byte-comparable, which is what the round-trip test relies on.
-
-### ⛔ Decision: the DEK does NOT travel; a fingerprint does
-
-The turn's instruction said "the `crypto_keystore` row for the workspace travels with it
-because the DEK is per tenant". **There is no such row.** `crypto_keystore` has no
-`workspace_id` at all — it is exempt (D2) and holds one wrapped DEK per PROCESS (D3),
-labelled `primary` / `recovery`. Verified in the schema rather than assumed.
-
-So carrying it was not an option, and manufacturing one would have been worse than useless:
-an export of a SINGLE tenant would then contain the key that decrypts EVERY tenant's secrets
-on that instance, which is the opposite of what the isolation exists for.
-
-What travels is `dek_fingerprint`: SHA-256 over the already-encrypted `wrapped_dek`, which
-cannot be reversed to the key. Equal fingerprints mean the two instances share a data key, so
-the document's `_enc` columns will decrypt there. **Different ones make import refuse with
-409.** That refusal is the point: without it the rows import perfectly and then every secret
-in them — SMTP password, LLM key, LiveKit secret, calendar tokens — fails at first use, one
-integration at a time, long after anyone is watching. Import is the only moment the two keys
-can be compared. The message names `CALNODE_ENCRYPTION_KEY`, because moving it with the data
-is the operator's actual remedy.
-
-⚠️ A per-tenant DEK would change all of this, plus D3 and the schema. It is a separate
-packet, and until then moving a workspace between instances means moving the encryption key
-with it.
-
-Secrets and API-key hashes otherwise travel **verbatim**, per the contract: a tenant whose
-keys and manage links stopped working on migration has not been migrated. The consequence is
-that the document is as sensitive as the database.
-
-### ⛔ Import forces the target workspace
-
-Every row is inserted with `workspace_id` = the id **in the URL**, and the document's own
-value is discarded. This endpoint is authorised by the platform token, so trusting the
-document would make an export of any workspace a way to write rows into any other.
-
-⚠️ **Ids are GLOBAL primary keys, so import is a MOVE and not a copy.** Replaying a document
-into a second workspace while the first still holds its rows collides on `users_pkey`. The
-supported operation is export → delete → import, usually into another region's instance where
-those ids do not exist; `TestPlatformData_importForcesTheTargetWorkspace` performs exactly
-that inside one database, which is the only place the workspace_id question can be asked.
-This is worth knowing before anyone tries to use import to clone a tenant for staging.
-
-`UseNumber` on the decoder, and `importValue` converts a `json.Number` to `int64` when it is
-one: without it every numeric column round-trips through `float64` and a large id loses its
-low bits silently.
-
-### Erasure: exactly one email, in exactly one workspace, cancelling nothing
-
-⚠️ **`booking_answers` carries no attendee** — it is keyed `(booking_id, question_id)` — so
-"their answers" has to be derived. They are erased only for bookings where the erased person
-was the **only** attendee. With anyone else still on the booking the answers cannot be
-attributed to them, and deleting them would erase a third party's data to satisfy someone
-else's request. Both halves are tested: two attendees ⇒ 1 attendee row and **0** answers
-erased; sole attendee ⇒ 1 and 1.
-
-Bookings are not cancelled (the host's calendar and the other attendees' records are not the
-erased person's data), and the workspace boundary holds: the same address in another
-workspace is untouched, because one tenant's erasure request is not consent to delete
-another's records.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-`go test -count=1 ./...` **rc=0 on SQLite (30/30)**.
-PostgreSQL: `internal/handler` **rc=0** (329.5s), `internal/server` **rc=0**, `internal/db`
-**rc=0**.
-
-```
---- PASS: TestPlatformData_exportDeleteImportRoundTrip (1.31s)
---- PASS: TestPlatformData_importIntoAPopulatedWorkspaceIs409 (1.29s)
---- PASS: TestPlatformData_importForcesTheTargetWorkspace (1.33s)
---- PASS: TestPlatformData_eraseAttendee (1.31s)
---- PASS: TestPlatformData_eraseTakesAnswersWhenNobodyElseIsOnTheBooking (1.27s)
---- PASS: TestPlatformData_eraseRequiresAnEmail (1.22s)   [missing, empty, not an email]
---- PASS: TestPlatformData_routesRefuseWithoutTheToken (1.27s)   [export, import, erase]
---- PASS: TestPlatformData_importRefusesAForeignDEK (1.28s)
-```
-
-Negative control, the workspace-forcing removed so the document's own `workspace_id` is
-trusted:
-
-```
---- FAIL: TestPlatformData_importForcesTheTargetWorkspace
-    import into acme: 400 — insert or update on table "server_settings" violates foreign key
-    constraint "server_settings_workspace_id_fkey" (SQLSTATE 23503)
-```
-
-⚠️ Stated precisely, because it is not the failure I predicted: it proves the forcing is
-load-bearing (unfixed 400, fixed 200 with the rows in `acme`), but it fails at the foreign key
-rather than by writing rows into the wrong tenant — the source workspace has been deleted by
-then, so the id the document names no longer exists. The leak shape it guards against is
-unreachable on one instance for the same reason ids are global; the guard matters for a
-destination where `globex` DOES exist.
-
-### Still owed by B6
-
-The SSO + OAuth hand-off on the public host (plan at the end of this file) and the vendor
-webhooks resolving their workspace from the row they name. D13 and D14 are done.
-
----
-
-## Boundary 6, part three — the SSO hand-off and the OAuth login, both halves (D11)
-
-The verify half arrived with the platform-hooks merge; this is the mint half, plus the
-correction that makes the verify half safe on a public host.
-
-### ⛔ The workspace comes from the HOST, and `wid` is CHECKED against it
-
-The endpoint is reached at `https://<public_host>/v1/auth/sso`, because landing the cookie on
-the tenant's own domain is the entire reason the hand-off exists. So resolving the workspace
-from the token's `wid` — which is what the merge left — is wrong: a token for workspace A
-presented on **B's** host has a valid signature, a `wid` that resolves, and an `aud` that
-matches A's host, so it would quietly create **A's session on B's domain**.
-
-Now: resolve by `workspaceByHost`, then require `wid == that workspace's id` (403
-`{"error":"workspace mismatch"}`, D10's body) and `aud == "https://" + that public host`, no
-trailing slash. Unknown host 404, suspended 503. Single-tenant unchanged: `wid` ignored, `aud`
-is `BASE_URL`.
-
-Negative control, the resolution put back on `wid`:
-
-```
---- FAIL: TestSSOHandoff_tokenForAnotherWorkspaceIsRefusedOnThisHost
-    status = 302; want 403 — <a href="/admin/">Found</a>.
---- FAIL: TestOAuthHandoff_mintedTokenIsRefusedOnAnotherWorkspacesHost
-    status = 302; want 403
-```
-
-That 302 IS the bug: one tenant's session created on another tenant's domain.
-
-### The state cookie carries the workspace; the URL carries only the nonce
-
-`newOAuthState(w, workspaceID)` writes `<nonce>|<workspace_id>` into the HttpOnly
-`calnode_oauth_state` cookie and sends only the nonce to the provider.
-`verifyOAuthState` compares the nonce and **reads** the workspace.
-
-⛔ That split is the security property. A visitor can rewrite the `state` query parameter —
-doing so produces a failed login. The value that decides which tenant a Google identity is
-admitted to never left this server's cookie. Putting the workspace in the URL instead would let
-anyone choose the tenant they are let into.
-
-The workspace is resolved at the login START (`GET /v1/auth/login`, from the Host the person
-clicked on), because the callback arrives on the identity host and cannot know it. That route
-is `Platform`-wrapped — it has to be, since its callback is — so it calls `workspaceByHost`
-explicitly and 404s an unrecognised host, doing by hand exactly what `HostWorkspace` would.
-
-### `finishOAuthLogin`: two bugs, one of them live before this
-
-1. ⛔ **The lookup was `WHERE email = ?` on the platform handle.** Since D9 the unique on
-   `users` is `(workspace_id, email)`, so the same address in several workspaces is ordinary —
-   and that statement resolves an **arbitrary** one of them and starts a session for a
-   stranger. Now scoped by `workspace_id`, in both modes (`'default'` in single-tenant, where
-   every row carries it), so there is one statement and no branch to drift.
-2. **The session is no longer set here in multi-tenant mode.** The callback runs on the
-   identity host; a cookie for it is no use to a person whose admin UI is on their own domain.
-   It mints a 30 s HS256 token (`iss` = BASE_URL, `aud` = `https://<public_host>`, `wid`,
-   `role = member`, `jti`) and redirects to that workspace's `/v1/auth/sso`.
-
-`role = member` always: the callback knows that Google or Microsoft vouched for an address,
-which says nothing about what that person may do here. `ssoResolveUser` leaves an existing
-user's role alone, so the value only ever applies to a user it creates.
-
-⛔ **No shared secret ⇒ refuse.** With `CALNODE_SSO_SHARED_SECRET` unset the hand-off endpoint
-404s, so there is nowhere to land; setting a cookie on the identity host instead would produce
-a session the person's own admin UI cannot see. `error=sso`, no session.
-
-⚠️ **The MCP Connect return keeps its identity-host cookie tail**, deliberately:
-`/oauth/authorize` is an identity-host endpoint whose consent-step cookies were set there, so
-handing it to a tenant's public host would arrive with none of them.
-
-### The calendar callback resolves its workspace from the state's USER
-
-`p.Exchange` writes `calendar_connections` through a provider that captured a handle at
-construction. On this `Platform` route that is the **unbound** handle, so the connection
-appeared to succeed and no row existed. Now the workspace comes from `workspaceOfUser` on the
-state's user id — the state is encrypted, so the id cannot be forged — the exchange runs
-through `forWorkspace(ws).getCal()`'s provider (B5's `Provider.ForDB`), and the redirect goes
-to that workspace's `publicURL()` rather than `h.baseURL`, which would have sent the person
-somewhere their session does not exist.
-
-⚠️ The workspace is deliberately **not** also carried in the calendar state: it would be a
-second copy of a fact the user id already settles, and two sources of one truth is how they
-come to disagree.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-`go test -count=1 ./...` **rc=0 on SQLite (30/30)**. PostgreSQL: `internal/handler` **rc=0**
-(302.5s), `internal/server` **rc=0**.
-
-```
---- PASS: TestSSOHandoff_multiTenantLandsInTheTokensWorkspace (0.96s)
---- PASS: TestSSOHandoff_tokenForAnotherWorkspaceIsRefusedOnThisHost (0.90s)
---- PASS: TestSSOHandoff_multiTenantRefusesABadWID (3.49s)     [missing, empty, unknown, not an id]
---- PASS: TestSSOHandoff_multiTenantAudienceIsThePublicHost (2.40s)  [identity host, bare host, trailing slash]
---- PASS: TestSSOHandoff_multiTenantReplayIsRefused (0.77s)
---- PASS: TestSSOHandoff_unknownHostIs404 (0.73s)
---- PASS: TestSSOHandoff_multiTenantRefusesASuspendedWorkspace (0.71s)
---- PASS: TestOAuthHandoff_callbackMintsATokenTheSSOEndpointAccepts (0.76s)
---- PASS: TestOAuthHandoff_mintedTokenIsRefusedOnAnotherWorkspacesHost (0.72s)
---- PASS: TestOAuthHandoff_refusesWithoutTheSharedSecret (0.76s)
-```
-
-⚠️ **A trap the test bridge paid for.** Driving `finishOAuthLogin` on the bare handler reported
-`no_account` for a user that exists: the tail's lookup runs on whatever handle the route gives
-it, and on the bare handler that is the **unbound application** handle, which matches no row.
-The bridge goes through `h.Platform(...)` as `server.New` does. A test that had accepted the
-bare handler would have been asserting against the wrong handle.
-
-### Still owed by B6
-
-Only the vendor webhooks: `POST /v1/livekit/webhook` (+ its alias) and `POST /v1/stripe/webhook`
-must resolve their workspace from the room or session row they name, then hand off to
-`forWorkspace`. D12, D13 and D14 are done.
-
-## Boundary 6, part four — the vendor webhooks, and a hole they exposed
-
-`POST /v1/livekit/webhook` (+ its legacy alias) and `POST /v1/stripe/webhook`. Both stay
-`Platform`-classified, because the caller is a vendor: no tenant Host (the URL was registered
-once in a dashboard) and no credential of ours (the signature is theirs).
-
-### The workspace comes from OUR row, keyed on an id WE issued
-
-`internal/handler/vendor_webhook.go`. LiveKit resolves in three steps — the egress id on a
-`recordings` row, then the room's `recordings` row, then the booking the room name encodes
-(`booking-<id>`, which is the only room name this application creates, and is what a
-`room_finished` for a never-recorded meeting needs). Stripe resolves from
-`bookings.stripe_session_id`, falling back to the metadata booking id — and even then takes
-`workspace_id` from the ROW, not the payload.
-
-⛔ **No resolver consults a `workspace_id` in a vendor payload.** Such a field would be a
-tenant selector supplied by whoever can forge a body, and every read here names `workspace_id`
-in its own SELECT list instead.
-
-An event no row owns is **2xx and ignored**. A 4xx would make LiveKit and Stripe retry for days,
-and no retry can make a row exist that never did.
-
-### ⚠️ Decision: in multi-tenant mode the RESOLVE precedes the VERIFY
-
-The turn asked for verify-then-resolve. That is impossible here, and the reason is worth
-recording: **both vendors' credentials live in `server_settings`, i.e. per workspace (D7).** On
-a Platform-wrapped route the handle bypasses the policies, so `LoadLiveKitSettingsFromDB`'s
-`WHERE id = 1` matches every tenant's row and returns an arbitrary one — verifying a signature
-against a randomly chosen tenant's secret is not verification. There is no process-wide
-credential to fall back on either, because boot priming is single-tenant-only (B5, deliverable 4).
-
-So: resolve (one keyed SELECT), then verify with **that workspace's** secret, then act. Two
-properties make it safe and both are load-bearing: **nothing is written before the signature
-verifies**, and **nothing is disclosed** (the body is empty either way).
-
-⚠️ The residual is an existence oracle — an unsigned request naming a real egress id gets 403
-while an unknown one gets 200. The ids are opaque (`booking-<uuid>`, LiveKit egress ids) and a
-caller holding a valid signature already knows the id it sent. Closing it would mean 403 for an
-unknown row, i.e. the retry storm this design exists to avoid.
-
-**Single-tenant keeps the original order exactly** (verify, then act): one workspace, one set of
-credentials, nothing to resolve, and no reason to change what a working deployment does.
-
-### ⛔ THE HOLE: `forWorkspace` was binding onto the PLATFORM pool
-
-Found by the vendor-webhook test, and it reached further than this group.
-
-`Platform()` replaces `h.db` with the platform handle, whose role **BYPASSES** row-level
-security. `forWorkspace` then built its scoped copy with `h.db.ForWorkspace(ws.ID)` — so the
-result **named** a tenant and was not **confined** to it. A `WHERE id = 1` read through such a
-handle matches every workspace's `server_settings` row and returns an arbitrary one; a write
-lands wherever the statement says. Both silent.
-
-The symptom was oblique: the hand-off from the LiveKit webhook to
-`forWorkspace(ws).getLiveKit()` read the **default** workspace's empty settings row instead of
-the resolved tenant's, so the client was nil and the handler answered 200 having verified
-nothing. No error, no log line.
-
-Fixed by holding the application handle on `shared` (`appDB`, set once in `handler.New`) and
-binding every scoped copy from **that**: `h.appBase().ForWorkspace(ws.ID)`. A tenant-scoped
-handler now always rides the role the policies constrain, whichever route it came from.
-
-⚠️ **Why nothing else caught it:** every other Platform-route hand-off either names
-`workspace_id` explicitly on its writes (the platform API, the SSO endpoint — which is why
-those tests pass either way) or runs on the worker's path, where the base handler's `db` IS the
-application handle. The vendor webhooks are the first code to depend on a scoped handle's
-**reads** being filtered.
-
-Negative control, the bind put back on `h.db`:
-
-```
---- FAIL: TestVendorWebhook_livekitBadSignatureWritesNothing
-    status = 200; want 403
-```
-
-200 means it never reached verification, because it loaded the wrong tenant's (absent)
-credentials.
-
-### Gates
-
-`gofmt -l .` empty, `go vet ./...` clean, `go build ./...` clean.
-`go test -count=1 ./...` **rc=0 on SQLite (30/30)**. PostgreSQL: `internal/handler` **rc=0**
-(321.2s), `internal/server` **rc=0** — including the whole B3/B4/B5 tenancy suite, which is
-what says the `appDB` change did not move anything else.
-
-```
---- PASS: TestVendorWebhook_livekitResolvesTheOwningWorkspace      [7 cases]
---- PASS: TestVendorWebhook_livekitEventWritesOnlyItsOwnWorkspace
---- PASS: TestVendorWebhook_livekitUnknownRoomIs2xxWithNoWrite
---- PASS: TestVendorWebhook_livekitBadSignatureWritesNothing
---- PASS: TestVendorWebhook_stripeResolvesTheOwningWorkspace       [6 cases]
---- PASS: TestVendorWebhook_stripeUnknownSessionIs2xxWithNoWrite
---- PASS: TestVendorWebhook_stripeBadSignatureWritesNothing
-```
-
----
-
-# Boundaries 1–7 — COMPLETE. Phase 1 of the fork is gated
-
-B1 config + schema, B2 the two handles, B3 handler scoping and resolution, B4 per-tenant state,
-B5 the background loops, B6 the platform API + hand-off + vendor webhooks, **B7 the proof, the
-cost measurement and `docs/MULTI_TENANT.md`**.
-
-The B7 gate lines, in one place:
-
-```
-gofmt -l .                          empty
-go vet ./...                        clean
-go build ./...                      clean
-go test -count=1 ./...              rc=0 on SQLite, 30/30 packages
-PostgreSQL, per package:            internal/server rc=0, internal/handler rc=0,
-                                    internal/db rc=0, internal/worker rc=0, internal/webhook rc=0
-go test -race ./internal/server/ -run TestProof     rc=0, no data race
-
---- PASS: TestProof_noRouteLeaksAnotherWorkspace     138 tenant routes as A, 61 answered 2xx
---- PASS: TestProof_everyMCPToolIsScoped             10 tools, derived from tools/list
---- PASS: TestProof_everyWorkerJobTypeIsCoveredAndScoped   4 job types, derived from two sources
---- PASS: TestProof_unscopedQueryReturnsNothing      6 tables, both halves
---- PASS: TestRSS_200Workspaces                      34.6 KB per tenant
-
-negative control (wrong password): internal/db FAILS with SQLSTATE 28P01 rather than skipping
-```
-
-# Boundary 6 — done. D11, D12, D13, D14 all closed
-
-| decision | state |
-|---|---|
-| **D11** hosts, per-workspace `publicURL`, the OAuth hand-off through SSO, the calendar callback's workspace | **done** (B3 for the hosts, B6 part three for both hand-off halves) |
-| **D12** platform API: create, get, patch, delete, export, import, attendee erasure; suspended ⇒ 503 | **done** (B6 parts one and two; 503 was already in `Scoped`) |
-| **D13** demo mode and multi-tenant mutually exclusive | **done** in B1 (`config.Validate`) |
-| **D14** rate limits keyed `(workspace, client IP)` via `TRUSTED_PROXY_CIDRS` | **done** with the platform-hooks merge |
-
-## What a bring-up needs from this side
-
-Environment, on every instance:
-
-| key | value |
-|---|---|
-| `MULTI_TENANT` | any non-empty value turns the mode on. ⛔ Requires a `postgres://` DSN and refuses `DEMO_MODE` (D13) |
-| `DATABASE_URL` | the **application** role: `NOBYPASSRLS`, owns no table in the schema. `VerifyRoles` refuses the boot otherwise |
-| `DATABASE_ADMIN_URL` | the **platform** role: owner, `BYPASSRLS`. ⛔ Must not equal `DATABASE_URL` — one role means every policy is inert against it, and everything appears to work |
-| `CALNODE_PLATFORM_TOKEN` | bearer for `/v1/platform/*`. Unset ⇒ those routes 404 |
-| `CALNODE_SSO_SHARED_SECRET` | HMAC key for `/v1/auth/sso`. ⛔ **Required** in multi-tenant mode if Google or Microsoft login is configured: the callbacks hand off through it, and unset means every social login ends at `error=sso` |
-| `TRUSTED_PROXY_CIDRS` | the networks whose forwarded headers are believed. ⚠️ Unset behind a proxy makes every tenant one rate-limit bucket (D14's IP half) |
-| `CALNODE_ENCRYPTION_KEY` | as before, and ⛔ it must travel with any workspace moved between instances — import refuses a document whose `dek_fingerprint` differs |
-| `BASE_URL` | the identity host: OAuth callbacks, `/oauth/*`, `/mcp`, `/v1/platform/*`, `/healthz`, `/readyz`, `/version`, `/metrics` |
-| `PUBLIC_BASE_URL` | **ignored** in multi-tenant mode; each workspace's `public_host` replaces it |
-
-Per workspace, through `POST /v1/platform/workspaces`: `public_host` (its own hostname, DNS
-pointed at the instance) and the `defaults` block. The response's `api_key` and
-`webhook_secret` are shown once.
-
-At boot, in this order: migrate on the platform handle → `EnableRLS` → suspend the `default`
-workspace → `VerifyRoles` on the application handle. The first, second and fourth are fatal on
-failure; the third is logged.
-
-## The cost of a tenant, measured (B7)
-
-`internal/server/rss_proof_test.go`, opt-in behind `CALNODE_RSS_PROOF=1`. It provisions 200
-workspaces through the real platform API in one process, serves one request to each on its own
-public host, and reads `/proc/self/status`. A test rather than a script because the number wanted
-is the RSS of a process that has the handler, the caches and the pool in it.
-
-| | VmRSS |
-|---|---|
-| baseline (handler + worker, no tenants) | **28 936 KB** |
-| after provisioning 200 workspaces | **33 676 KB** |
-| after one request to each | **35 860 KB** |
-
-**Growth: 6 924 KB for 200 tenants — 34.6 KB each.** `runtime.MemStats.Sys` 39 354 → 43 722 KB.
-Pool after all of it: application `open=1 idle=1`, platform `open=1 idle=1`.
-
-⛔ **This CORRECTS the plan's claim, which said "a few MB per tenant".** It is a few MB for
-*hundreds*: ~7 MB bought 200 workspaces including their settings rows, owners, keys, webhooks,
-event types and availability. The per-tenant cost is the cache entries plus the workspace row, and
-`ForWorkspace` returning a value over a shared pool is why the connection count does not move —
-200 tenants, one connection each side. The test asserts both: a ceiling of 1 MB per tenant (a
-per-workspace allocation that never came back would breach it) and a ceiling of 20 pool
-connections.
-
-## The two known follow-ups
-
-1. ⛔ **Per-tenant DEKs.** `crypto_keystore` is exempt and holds one wrapped DEK per process
-   (D3), so every tenant's secrets are encrypted under one key: an operator who can read the
-   database can decrypt every workspace, and a workspace cannot be moved between instances
-   without moving the key. Import's `dek_fingerprint` check makes the coupling loud rather than
-   silent, which is as far as this packet goes. Making it per tenant changes D3, the schema
-   (`crypto_keystore` gains `workspace_id`), and the export format.
-2. ✅ **The D7 reader wiring for `embed_allowed_origins` and `stt_base_url`** — done after
-   B7, see the section above. One known follow-up remains in this list.
-
-⚠️ This file carried a plan for the SSO mint half between the merge and part three above.
-It is now BUILT, and part three is the record; the plan is deleted rather than annotated,
-because a plan left beside its implementation is the next reader's wrong answer. Two of its
-three points survived contact unchanged (the callback to change, and the `<nonce>|<wid>`
-state cookie). The third did not: the plan had the SSO endpoint resolving its workspace from
-`wid`, and doing that on a public host is what part three had to fix.
-
----
-
-## The D11 plan this file used to carry
-
-⚠️ Deleted rather than annotated once it was built: a plan left beside its implementation is the
-next reader's wrong answer. Two of its three points survived contact unchanged (the callback to
-change, and the `<nonce>|<wid>` state cookie). The third did not — it had the SSO endpoint
-resolving its workspace from `wid`, and doing that on a public host is exactly what part three
-had to fix.