Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

docs: decide project scope for sheets, and history on transfer

Danny1c943ebeb592
diff --git a/docs/design/sheet-blob-scoping.md b/docs/design/sheet-blob-scoping.md
index 64fe3d2fd8..9964b22b1b 100644
--- a/docs/design/sheet-blob-scoping.md
+++ b/docs/design/sheet-blob-scoping.md
@@ -1,100 +1,125 @@
-# Scoping `sheet_blob` — fixing the global-by-SHA256 read
+# Scoping `sheet_blob` to its project
Fixes T5 in `docs/design/v1-api-audit-2026-08.md`.
-## Problem
+Sheet content is fetched by SHA256 with no scope predicate, so any principal holding
+`bb.sheets.get` on any one project can read any sheet in the deployment — across projects and
+across tenants — given the hash. A `sheet_blob_ref(project, sha256)` edge table makes ownership an
+explicit stored fact, and an API-layer gate enforces it.
+
+## Background
`sheet_blob` is `(sha256 PRIMARY KEY, content)` — no project column, no workspace column.
`getSheet` selects `WHERE sha256 = decode(?, 'hex')` with no scope predicate
(`backend/store/sheet.go:60-71`), while the ACL authorizes `bb.sheets.get` against the
-caller-named project, correctly pinned to the caller's workspace
-(`backend/api/v1/acl.go:397`).
-
-Authorization is per-tenant; the data fetch is deployment-global. Anyone holding
-`bb.sheets.get` on any one project reads any blob in the deployment, across projects and
-across workspaces, given the hash.
+caller-named project, correctly pinned to the caller's workspace (`backend/api/v1/acl.go:397`).
+Authorization is per-tenant; the data fetch is deployment-global.
This is a regression, not an oversight. Commit `bee2080737` (#18552, Dec 2025) dropped the
project-scoped `sheet` table — which carried `project text NOT NULL REFERENCES
-project(resource_id)` — and promoted the `sheet_blob` dedup side-table to primary store. Its
-design doc's Non-Goals recorded "Change authorization model (already project-scoped, no
-changes needed)", which was true before the cutover and false after. The assumption is still
-in the tree as a justification for skipping checks, at `backend/api/v1/release_service.go:331`
-and `:405`.
+project(resource_id)` and `idx_sheet_project` — and promoted the `sheet_blob` dedup side-table to
+primary store. Its design doc recorded "Change authorization model (already project-scoped, no
+changes needed)" as a non-goal, true before the cutover and false after. The assumption survives in
+the tree as a justification for skipping checks, at `backend/api/v1/release_service.go:331` and
+`:405`.
-## The model is per-project
+## Requirements
-This is not a new decision — it is the model the rest of the code already implements, and
-sheets are the one thing that fell out of it.
+**R1 — Close cross-tenant read.** A principal in workspace W1 must not read sheet content belonging
+to workspace W2. In Bytebase Cloud this is tenant isolation; it is the severe half of the finding
+and is non-negotiable.
-`validateSpecs` rejects a release whose project differs from the plan's project
-(`backend/api/v1/plan_service.go:759`). Three lines above, the sheet check is
-`HasSheets(ctx, sheetSha256s...)` with no project, and `:642` discards the project segment of
-a caller-supplied sheet name outright. Same function, two resources, opposite treatment. The
-dropped `sheet` table carried `project text NOT NULL REFERENCES project(resource_id)`, and the
-resource name is still `projects/{project}/sheets/{sha}`.
+**R2 — Preserve authoring governance.** Customers restrict who may author change SQL under a given
+project. `CreateSheet` is gated on `bb.sheets.create` against the parent project, and that must
+remain expressible.
-So the fix restores project scoping rather than inventing a scope.
+**R3 — Preserve content-addressed dedup.** Identical SQL must not be stored twice. This was the
+point of the refactor that introduced the bug and must not be undone to fix it.
-Scoping on `project` alone is sufficient for tenant isolation too: `project.resource_id` is a
-global primary key carrying a `workspace` column, and the ACL already pins the caller-named
-project to the caller's workspace (`backend/api/v1/acl.go:397`). One predicate closes both
-boundaries.
+**R4 — No silent breakage of existing reads.** The fix rests on a backfill whose completeness
+cannot be established by construction. A missed reference source must not become a production
+NotFound with no signal.
-## Design decision: an ownership edge, not a column
+**R5 — Bounded round-trips.** Requests routinely carry many sheets; a release can have hundreds of
+files. The scope check must not be O(n) in queries.
-Adding `project` directly to `sheet_blob` would break the content-addressed dedup that
-motivated the refactor — the same statement in two projects would need two rows, and the
-migration would have to split existing shared rows.
+**R6 — Projects remain a confidentiality boundary.** Many customers separate projects specifically
+so teams cannot read each other's SQL — regulated separation where a PCI- or HIPAA-scoped project
+is walled off and audited, and agency or multi-end-customer workspaces where one workspace holds
+databases belonging to different clients.
-Instead, keep `sheet_blob` as pure content storage and add an edge table recording which
-projects may read a given hash. Two projects that independently author identical SQL share one
-blob and hold one ref row each. Dedup survives; "who can read this hash" becomes an explicit
-stored fact rather than an implicit one.
+**R7 — The resource name states the truth.** Across this API the prefix in a resource name
+identifies the resource's actual owner, never a scope the caller selected. A scope that disagrees
+with the name is the defect being fixed, not a fix for it.
-### Schema
+## Decision
-`backend/migrator/migration/3.22/0005##scope_sheet_blob.sql` (current head is 3.22.4;
-`TestLatestVersion` in `backend/migrator/migrator_test.go` needs updating).
+**A sheet is owned by a project.** The resource is the pair (project, content): two projects that
+independently author identical SQL own two distinct sheets that happen to share storage.
+Content-addressed dedup becomes a storage optimization invisible at the API layer.
-```sql
-CREATE TABLE sheet_blob_ref (
- project text NOT NULL REFERENCES project(resource_id),
- sha256 bytea NOT NULL REFERENCES sheet_blob(sha256),
- PRIMARY KEY (project, sha256)
-);
-```
+Everything else follows from that one commitment. `projects/{project}/sheets/{sha}` is an honest
+name, `parent = projects/{project}` on `CreateSheet` is a real parent, project-level
+`bb.sheets.create` is coherent, read is project-scoped, and no part of the public contract changes.
-Mirror into `backend/migrator/migration/LATEST.sql`.
+The alternative — treating the resource as the content, shared tenant-wide — is examined under
+[Alternatives](#alternatives-considered). It fails R2 and R6 and requires a breaking rename.
-### Project purge
+### Why the name forces this
+
+The API has one consistent rule and it is unbroken. Project-owned resources use a single
+project-prefixed pattern: `AccessGrant` (`projects/{project}/accessGrants/{access_grant}`),
+`DatabaseGroup`, `Plan`, `PlanCheckRun`, `Issue`, `Release`. Workspace-global resources use a bare
+collection with the workspace implicit from the JWT: `Group` (`groups/{group}`), `IdP`
+(`idps/{idp}`), `ReviewConfig` (`reviewConfigs/{reviewConfig}`). Resources with two legitimate
+addressings declare both patterns — `Database`, `DatabaseChangelog`, `DatabaseCatalog`,
+`DatabaseMetadata`, `InstanceRole`, `Instance` all carry `instances/{instance}/…` alongside
+`projects/{project}/instances/{instance}/…`, and `Policy` carries three.
-The `project` foreign key makes `sheet_blob_ref` a dependent of `project`, and project purge
-ends with `DELETE FROM project WHERE resource_id = ?` (`backend/store/project.go:826`) after
-clearing every other dependent table. Add
+In every case the prefix names the **actual owner**. A project instance really is owned by that
+project; a database's `projects/{p}/…` form names the project in `db.project`, not one the caller
+picked. Nowhere else in this API does a name prefix identify a caller-supplied scope. `Sheet`
+declaring `projects/{project}/sheets/{sheet}` while the lookup ignores the project *is* T5, stated
+as a naming defect rather than an authorization one.
+
+The create side is equally strict: a create request's `parent` is always exactly the prefix of the
+created resource's name. Workspace-scoped resources therefore have no parent at all —
+`CreateGroup` is `POST /v1/groups`, `CreateReviewConfig` is `POST /v1/reviewConfigs`,
+`CreateIdentityProvider` is `POST /v1/idps`. `CreatePolicyRequest.parent` is `workspaces/{workspace}`
+or `environments/{environment}` or `projects/{project}`, and the resulting `Policy` name is that
+parent plus `/policies/{policy}`.
+
+So project-parented creation and a workspace-scoped resource cannot coexist. Keeping
+`parent = projects/{project}` while naming the resource `sheets/{sha}` would make the parent a
+permission argument wearing a parent's name; dropping the parent to match the name moves
+`bb.sheets.create` to the workspace and loses R2. Project ownership is the only shape in which
+creation, naming, and access all agree.
+
+## Design
+
+### An ownership edge, not a column
+
+Adding `project` directly to `sheet_blob` would break dedup (R3): the same statement in two projects
+would need two rows, and the migration would have to split existing shared rows. Keep `sheet_blob`
+as pure content storage and record ownership beside it.
```sql
-DELETE FROM sheet_blob_ref WHERE project = ?
+CREATE TABLE sheet_blob_ref (
+ project text NOT NULL REFERENCES project(resource_id),
+ sha256 bytea NOT NULL REFERENCES sheet_blob(sha256),
+ PRIMARY KEY (project, sha256)
+);
```
-to that sequence at the position established under transaction lock ordering below — after the
-`db` delete (`:704`) and before `project_webhook` (`:739`). Without it, purging any project fails
-on the foreign key, a hard breakage of a shipped path.
-
-Blobs whose only ref belonged to the purged project are left behind with zero refs. That is
-consistent with today's behavior (nothing has ever deleted from `sheet_blob`) and is the state
-a future GC would collect; see the GC note under independent fixes.
+Migration slot `backend/migrator/migration/3.22/0005##scope_sheet_blob.sql`; `TestLatestVersion` in
+`backend/migrator/migrator_test.go` needs updating, and `LATEST.sql` mirrored.
### Backfill
-Derive `(project, sha256)` from every surviving reference. All of them live inside JSONB
-payloads, and `protojson` camelCases the keys — `sheetSha256`, not `sheet_sha256`.
-
-The authoritative source list is `grep -rn "sheet_sha256" proto/store/`, which returns exactly
-five messages. Re-run it before writing the migration rather than trusting this table — and for
-each hit, confirm two things the grep does not tell you: the **column name** in `LATEST.sql`
-(it is not always `payload`) and the **nesting** of the field inside its message (it is not
-always top-level).
+Five reference sources, and only five. `grep -rn "sheet_sha256" proto/store/` returns exactly these
+messages; re-run it before writing the migration, and for each hit confirm two things the grep does
+not give you — the column name in `LATEST.sql` (not always `payload`) and the nesting of the field
+inside its message (not always top-level). `protojson` camelCases keys.
| Source | Column | Path to the hash | Route to project |
|---|---|---|---|
@@ -104,427 +129,283 @@ always top-level).
| `plan_check_run` | `result` | `results[].sheetSha256` | `plan_check_run.project` |
| `revision` | `payload` | `sheetSha256` | `db(instance, db_name)` → `db.project` |
-`plan_check_run` is the one that punishes assumption: the column is `result`, not `payload`, and
-the hash lives on `PlanCheckRunResult.Result` inside the repeated `results` array, so the path is
-`result->'results'` with a `jsonb_array_elements` expansion — the same shape as `plan` and
-`release`, not the flat shape of `task` and `revision`.
-
-The first four carry `project` directly. Only `revision` needs the join through `db`, because
-it keys on `(instance, db_name)` and inherits its project from the database.
+`plan_check_run` punishes assumption: the column is `result`, not `payload`, and the hash sits on
+`PlanCheckRunResult.Result` inside the repeated `results` array.
Two tables that look like sources are not. `ChangelogPayload` carries only `task_run` and
-`git_commit` — a changelog reaches SQL transitively through its task run, and the v1
-`Changelog` message exposes no statement or sheet field. `issue_comment` has no sheet reference
-of any kind.
-
-Representative statement for the plan source; the others follow the same shape and are
-`UNION`ed into one insert:
+`git_commit`, and the v1 `Changelog` message exposes no statement or sheet field. `issue_comment`
+has no sheet reference of any kind.
-```sql
-INSERT INTO sheet_blob_ref (project, sha256)
-SELECT DISTINCT pl.project, decode(x.sha, 'hex')
-FROM plan pl
-CROSS JOIN LATERAL jsonb_array_elements(COALESCE(pl.config->'specs', '[]'::jsonb)) spec
-CROSS JOIN LATERAL (SELECT spec->'changeDatabaseConfig'->>'sheetSha256' AS sha) x
-WHERE x.sha IS NOT NULL
- AND EXISTS (SELECT 1 FROM sheet_blob b WHERE b.sha256 = decode(x.sha, 'hex'))
-ON CONFLICT DO NOTHING;
-```
+Guard every derivation with `EXISTS (SELECT 1 FROM sheet_blob …)` so a payload naming a hash with no
+blob cannot violate the foreign key.
-The `EXISTS` guard keeps the foreign key satisfiable if any payload ever names a hash with no
-blob.
+**Unreferenced blobs become unreadable.** A blob referenced by nothing has no derivable project. In
+practice this is a sheet created but never attached to a plan or release; the UI attaches
+immediately, and `createSheet` caches content client-side (`frontend/src/stores/app/sheet.ts:91`) so
+a fresh draft does not re-fetch. Leaving orphans globally readable would reproduce the bug, so the
+gap is accepted and noted in the migration comment.
-**Known gap.** A blob referenced by nothing has no derivable project — there is no information
-anywhere that ties it to one. Those rows get no ref and become unreadable. In practice this is
-a sheet created but never attached to a plan or release; the UI attaches immediately, and
-`createSheet` caches the content client-side (`frontend/src/stores/app/sheet.ts:91`) so a fresh
-draft does not re-fetch. The alternative — leaving orphans globally readable — reproduces the
-bug, so accept the gap and note it in the migration comment.
-
-**Observed references are not authorization.** This is the sharpest limitation of the whole
-approach and it needs a decision before the migration runs.
-
-The backfill reconstructs which project *referenced* a hash. That is not the same as which
-project was *entitled* to it, and today's unscoped paths let the two diverge.
+**Observed references are not authorization.** The backfill reconstructs which project *referenced*
+a hash, which is not the same as which project was *entitled* to it.
`convertPlanSpecChangeDatabaseConfig` (`backend/api/v1/plan_service.go:1157`) parses a
-caller-supplied `projects/{project}/sheets/{sha}` and stores only the hash, discarding the
-project; `HasSheets` currently validates existence with no scope. So a plan in project B can
-already hold a reference to a hash owned by project A, and after the write nothing distinguishes
-it from a legitimate one. Backfilling `(B, sha)` would mint a permanent grant out of exactly the
-access this change exists to close.
+caller-supplied `projects/{project}/sheets/{sha}` and stores only the hash, and `HasSheets`
+currently validates existence with no scope — so a plan in project B may already reference a hash
+owned by project A, indistinguishable after the write from a legitimate one. Backfilling `(B, sha)`
+would mint a permanent grant out of the access being closed, and shadow mode cannot see it because
+the ref row exists.
-Shadow mode does not catch this. The ref row exists, so the gate neither logs nor denies — it
-is invisible to the safety net described below.
-
-There is no clean automated fix: the refactor that created this bug deleted the sheet's creator
-and project metadata, so no ground truth for "who owned this hash" survives anywhere. What can
-be done is to size the population and decide deliberately:
-
-```sql
-SELECT sha256, count(DISTINCT project) AS projects, array_agg(DISTINCT project)
-FROM sheet_blob_ref
-GROUP BY sha256
-HAVING count(DISTINCT project) > 1;
-```
-
-Run this immediately after the backfill, before enforcement. A hash claimed by more than one
-project is either honest dedup — two projects independently authored identical SQL, and both
-claims are real — or a laundered cross-project reference. They are indistinguishable from the
-data, so this is a review list, not an automatic filter. In most deployments it should be short
-or empty; if it is long, that is itself a finding worth reporting before proceeding.
-
-One timing note: this design is public on the PR, including the rule that a reference becomes an
-ownership edge. Between publication and the migration there is a window in which references could
-be planted deliberately. Capture the multi-project list at a known-good point rather than only
-after upgrade.
+No ground truth survives: the refactor that caused this bug deleted the sheet's creator and project
+metadata. The population is therefore sized and reviewed rather than filtered — see
+[Rollout](#rollout).
### Store API
-`sheet_blob_ref` is an ACL fact, enforced at the API layer. Content retrieval and access
-control are separate operations and the store API keeps them separate.
+`sheet_blob_ref` is an ACL fact enforced at the API layer; content retrieval and access control stay
+separate operations. The runners are why that distinction is real rather than cosmetic: when
+`database_migrate_executor` reads a sheet it is executing work authorized when the plan was created,
+not making an access decision. Threading a project through it to satisfy a signature would be
+authorization theater.
-The runners are the reason this distinction is real rather than cosmetic. When
-`database_migrate_executor` reads a sheet, it is executing work that was authorized when the
-plan was created; it is not making an access-control decision. Threading a project through it
-purely to satisfy a signature would be authorization theater.
-
-Every primitive is set-shaped. Requests routinely carry many sheets — a release can have
-hundreds of files — so nothing here may be O(n) in round-trips. See "Batch shape" below.
+Every primitive is set-shaped (R5).
```go
-// Content only. A hash fully determines the content, so no scope is involved.
-// Returns a map keyed by hex hash; an absent key means no such blob.
-func (s *Store) GetSheetsFull(ctx context.Context, sha256Hexes ...string) (map[string]*SheetMessage, error)
-func (s *Store) GetSheetsTruncated(ctx context.Context, sha256Hexes ...string) (map[string]*SheetMessage, error)
+// Content only. A hash fully determines content, so no scope is involved.
+func (s *Store) GetSheetsFull(ctx, sha256Hexes ...string) (map[string]*SheetMessage, error)
+func (s *Store) GetSheetsTruncated(ctx, sha256Hexes ...string) (map[string]*SheetMessage, error)
// Scoped: which of these hashes may this project read? One query.
-func (s *Store) FilterSheetsForProject(ctx context.Context, projectID string, sha256Hexes ...string) (map[string]bool, error)
-
-// Scoped: a validation predicate, not a content read. Already batched today.
-func (s *Store) HasSheets(ctx context.Context, projectID string, sha256Hexes ...string) (bool, error)
-
-// Scoped: writes blobs and ref rows, both as set inserts.
-func (s *Store) CreateSheets(ctx context.Context, projectID string, creates ...*SheetMessage) ([]*SheetMessage, error)
-```
+func (s *Store) FilterSheetsForProject(ctx, projectID string, sha256Hexes ...string) (map[string]bool, error)
-The singular `GetSheetFull`/`GetSheetTruncated` can stay as thin wrappers for the genuinely
-single-sheet callers in the runners, but the batch form is the primitive.
+// Scoped: validation predicate, not a content read.
+func (s *Store) HasSheets(ctx, projectID string, sha256Hexes ...string) (bool, error)
-`HasSheets` gains the join and stops being a deployment-wide existence oracle:
-
-```sql
-SELECT COUNT(*)
-FROM sheet_blob b
-JOIN sheet_blob_ref r ON r.sha256 = b.sha256
-WHERE b.sha256 IN (...) AND r.project = ?
+// Scoped: writes blobs and ref rows, both as set inserts, in one transaction.
+func (s *Store) CreateSheets(ctx, projectID string, creates ...*SheetMessage) ([]*SheetMessage, error)
```
-`CreateSheets` writes blobs and ref rows in one transaction. It currently issues a bare
-`ExecContext`; it needs a transaction so a blob cannot land without its ref. The ref insert
-mirrors the existing blob insert's array shape — one statement, not a loop:
-
-```sql
-INSERT INTO sheet_blob_ref (project, sha256)
-SELECT ?, unnest(CAST(? AS BYTEA[]))
-ON CONFLICT DO NOTHING
-```
+`CreateSheets` needs a transaction so a blob cannot land without its ref; it currently issues a bare
+`ExecContext`. The ref insert mirrors the blob insert's array shape rather than looping.
-Three of its four call sites have a project to hand — `sheet_service.go:54` and `:97` (the
-resolved parent) and `release_service.go:96`. The fourth does not:
-`rollout_service_task.go:143` stores generated `CREATE DATABASE` boilerplate from inside
-`getTaskCreatesFromCreateDatabaseConfig(ctx, s *store.Store, spec, c)`, which takes no project,
-and neither does its caller `getTaskCreatesFromSpec`. Thread it down from
-`rollout_service.go:1279`, which has the plan's project — two signature changes.
+Three of its four call sites have a project to hand — `sheet_service.go:54` and `:97`, and
+`release_service.go:96`. The fourth does not: `rollout_service_task.go:143` stores generated
+`CREATE DATABASE` boilerplate from inside `getTaskCreatesFromCreateDatabaseConfig`, which takes no
+project, and neither does its caller `getTaskCreatesFromSpec`. Thread it down from
+`rollout_service.go:1279`, which has the plan's project.
-### Cache
+### Cache ordering
-`sheetFullCache` stays keyed by hex hash alone (`backend/store/store.go:51,82,110`, a 10-entry
-LRU). Because content is a pure function of the hash, a hash-keyed content cache is always
-correct, and the dominant consumer — a runner reading the same sheet repeatedly — keeps full
-hit rate.
+`sheetFullCache` stays keyed by hex hash alone (`backend/store/store.go:51,82,110`, a 10-entry LRU).
+Content is a pure function of the hash, so a hash-keyed content cache is always correct, and the
+dominant consumer — a runner reading the same sheet repeatedly — keeps full hit rate.
-This is safe only because the ACL check is a separate step that runs first. The cache read at
-`backend/store/sheet.go:43` returns before any query executes, so a scope predicate placed
-inside `getSheet` would be skipped on a cache hit. Enforcement must not live there.
+This is safe **only** because the scope check is a separate step that runs first. The cache read at
+`backend/store/sheet.go:43` returns before any query executes, so a scope predicate placed inside
+`getSheet` would be skipped on a cache hit. Enforcement must not live there, and the check and the
+fetch must not be fused into one join.
-Ten entries is sized for the runner pattern — one sheet read repeatedly — not for batch reads,
-and a release with hundreds of files will miss on nearly all of them. That is fine and not a
-reason to grow it: the batch path collapses those misses into a single query, so the cache is an
-optimization for the repeated-single-sheet case rather than load-bearing for throughput.
+Ten entries is sized for the runner pattern, not for batch reads, and a release with hundreds of
+files will miss on nearly all of them. That is not a reason to grow it: the batch path collapses
+those misses into a single query.
### API-layer gate
-Moving enforcement out of the store means the compiler no longer finds missed call sites — and
-a forgotten check is exactly how `release_service.go:398` and `plan_service.go:642` ended up
-unscoped. Replace the compiler with structure:
-
-Add one helper in `backend/api/v1/` that does check-then-fetch. It has to be a package-level
-function, not a method — three of the four routed call sites live in `ReleaseService` and
-`RolloutService`, not `SheetService` — and it takes a set, because its heaviest caller iterates
-over release files:
-
-```go
-func sheetsForProject(ctx context.Context, s *store.Store, projectID string, sha256Hexes []string, raw bool) (map[string]*store.SheetMessage, error)
-```
-
-It filters the requested hashes through `sheet_blob_ref` for `projectID`, and any hash that does
-not survive yields NotFound — NotFound rather than PermissionDenied, so the response does not
-confirm that a hash exists somewhere else. Only the surviving hashes reach the content getter.
-Every v1 sheet read routes through it:
-
-- `backend/api/v1/sheet_service.go:136,138` — `project.ResourceID`, already resolved and
- workspace-checked at `:119-131`
-- `backend/api/v1/release_service.go:398` — where `validateAndSanitizeReleaseFiles` currently
- discards the project outright
-- `backend/api/v1/rollout_service.go:1233`, `rollout_service_task.go:463` — the resolved project
-
-`HasSheets` call sites pass a project directly: `release_service.go:144`,
-`revision_service.go:158` (`database.ProjectID`), `plan_service.go:746` (`plan.ProjectID` — the
-same value already used to validate the release at `:759`).
-
-Runner and component call sites keep the unscoped content getters:
-`backend/runner/taskrun/*`, `backend/runner/plancheck/*`, `backend/component/review/evaluator.go:710`.
-
-Hold the line with a test asserting that nothing under `backend/api/v1/` calls any store sheet
-content getter directly except the gate helper. Six call sites today, so it is cheap.
-
-### Batch shape
-
-The gate must cost a bounded number of round-trips regardless of how many sheets a request
-carries. A release with two hundred files must not produce two hundred queries — still less four
-hundred, which a naive check-then-fetch per file would give.
-
-`sheetsForProject` is therefore two queries, whatever the input size:
-
-1. **One ref query** returning the subset of requested hashes readable by this project:
+Moving enforcement out of the store means the compiler no longer finds missed call sites, and a
+forgotten check is exactly how `release_service.go:398` and `plan_service.go:642` ended up unscoped.
+Structure replaces the compiler: one package-level helper doing check-then-fetch — package-level
+because most routed call sites live in `ReleaseService` and `RolloutService`, not `SheetService` —
+taking a set and costing two queries whatever the input size.
- ```sql
- SELECT encode(sha256, 'hex')
- FROM sheet_blob_ref
- WHERE project = ?
- AND sha256 IN (SELECT decode(unnest(CAST(? AS TEXT[])), 'hex'))
- ```
+1. One ref query returning the subset of requested hashes the project may read.
+2. Cache lookups for survivors, then one content query for the misses.
- Anything requested but absent from the result is NotFound. This runs first, which is what
- preserves the cache-ordering invariant above.
+A hash that does not survive yields NotFound rather than PermissionDenied, so the response does not
+confirm the hash exists in another project. Fusing the two steps into a single join is rejected: it
+would put the content read in the same statement as the permission check, which is exactly the
+arrangement a cache hit can skip.
-2. **Cache lookups** for the surviving hashes, then **one content query** for the misses, using
- the same `unnest` shape.
+A test asserts nothing under `backend/api/v1/` calls a store content getter outside the gate.
+Runner and component call sites keep the unscoped getters.
-Note that fusing both into a single join would be tempting and is wrong: it would make the
-content read the same statement as the permission check, which is exactly the arrangement that
-lets a cache hit skip the check. Keeping them as two steps is deliberate.
+Three existing call patterns need reshaping to feed it. `validateAndSanitizeReleaseFiles`
+(`release_service.go:377-413`) fetches once per file inside its loop — a pre-existing N+1 that a
+per-file scope check would double. `rollout_service_task.go:214` fetches a loop-invariant hash once
+per target database, masked today only by the LRU. `plan_service.go:746` is already correct and
+worth copying: it collects across every spec and makes one call.
-Three existing call patterns need reshaping to feed it:
-
-- **`validateAndSanitizeReleaseFiles`** (`release_service.go:377-413`) calls `GetSheetFull` once
- per file inside its loop. It already has all the files up front, so hoist a single collect pass
- for every `f.Sheet`, one `sheetsForProject` call, then loop over the map. This path is O(n)
- today, before this change — the fix is not new debt, it is a pre-existing N+1 that the scope
- check would otherwise double.
-- **`rollout_service_task.go:214`** calls `getSheetContentBySha256(ctx, s, c.SheetSha256)` inside
- a loop over target databases, but `c.SheetSha256` is loop-invariant — a spec targeting a
- hundred databases fetches the same hash a hundred times. Hoist it above the loop. Only the
- 10-entry LRU keeps this from being a hundred queries today, which is a fragile reason for it to
- be fast.
-- **`plan_service.go:746`** is already correct and worth copying: it collects `sheetSha256s`
- across every spec and makes one `HasSheets` call.
-
-The write paths are already set-shaped and stay that way: `CreateSheets` uses array `unnest` for
-both inserts, the backfill is `INSERT ... SELECT`, and the transfer handler below is a single
-`INSERT ... SELECT` rather than a per-revision loop.
-
-## Rollout safety
-
-This is a read-path change to a shipped multi-tenant product whose correctness rests entirely
-on backfill completeness, and completeness cannot be established by construction. A missed
-source means sheets silently return NotFound in production with no signal.
-
-Treat that as a live risk rather than a hypothetical: the first draft of the source table above
-listed seven sources, two of which do not exist. The list is now verified, but the failure mode
-it illustrates is the one to design against.
-
-**Ship the gate in shadow mode.** It evaluates the ref check and logs a miss — project, hash,
-call site — but still returns the content. Run it for a full release. Flip to denying only once
-the log is clean.
+### Project purge
-**Verify the backfill before that.** After the migration, for each of the five sources, compare
-the count of distinct `(project, sha256)` pairs derivable from it against the ref rows present,
-and count blobs with zero refs:
+The `project` foreign key makes `sheet_blob_ref` a dependent of `project`, and purge ends with
+`DELETE FROM project WHERE resource_id = ?` (`backend/store/project.go:826`) after clearing every
+other dependent table. Add `DELETE FROM sheet_blob_ref WHERE project = ?` after the `db` delete
+(`:704`) and before `project_webhook` (`:739`), matching the position established under
+[lock ordering](#transaction-lock-ordering). Without it, purging any project fails on the foreign
+key.
+
+Blobs whose only ref belonged to the purged project are left with zero refs, consistent with today's
+behavior — nothing has ever deleted from `sheet_blob` — and the state a future GC would collect.
+
+### Database transfer
+
+No sheet references are carried when a database changes project. Change history follows the
+database; statement content stays with the project that authored it. The four code paths that move a
+database between projects therefore need no changes here.
+[`sheet-history-on-database-transfer.md`](sheet-history-on-database-transfer.md) records that
+decision and its requirements.
+
+## Alternatives considered
+
+**Workspace scope.** Make sheets shared within a tenant: `sheet_blob_ref(workspace, sha256)`, the
+resource renamed to a bare `sheets/{sheet}` collection, and `CreateSheet` parentless with
+`bb.sheets.create` checked at workspace level. This is internally consistent and it is attractive on
+cost — databases cannot move between workspaces (`UpdateProject`'s mask has no `workspace` case), so
+the transfer question never arises; the ref table would reference `workspace` rather than `project`,
+so purge would not touch it; and the laundering problem would shrink to cross-workspace references,
+which cannot be created legitimately and should audit to zero.
+
+It fails R2 and R6. Parentless creation moves authoring governance to the workspace, so "this user
+may write change SQL for project A only" stops being expressible. Cross-project read inside a
+workspace stays open, which is a policy violation for regulated-separation and agency customers, and
+it leaves sheets inconsistent with `worksheet`, which already applies `PRIVATE` / `PROJECT_READ` /
+`PROJECT_WRITE` visibility to SQL text.
+
+It is also a breaking API change across four proto sites — the `Sheet` pattern
+(`proto/v1/v1/sheet_service.proto:92`), `GetSheetRequest.name` (`:83`), `Release_File.sheet`
+(`proto/v1/v1/release_service.proto:331`), `Revision.sheet`
+(`proto/v1/v1/revision_service.proto:183`) — plus the shape of `CreateSheet`. Storage is unaffected,
+since only the hash persists and the resource name is constructed on read, so this is a contract
+break rather than a data migration; it would still need the `breaking` label and a dual-accept
+deprecation window.
+
+The asymmetry decides it. Project scope costs no API change in either direction and can be relaxed
+later behind a stable contract. Workspace scope costs one breaking change to adopt and a second, in
+the opposite direction, to reverse.
+
+**Workspace scope keeping the project prefix.** Rejected outright. It would make `Sheet` the only
+resource in the API whose name prefix is a caller-chosen scope, and it aliases — the same sheet
+answering to `projects/A/sheets/X` and `projects/B/sheets/X`, with `name` echoing whichever was
+asked. That is the decorative prefix the audit named, preserved deliberately.
+
+**A `project` column on `sheet_blob`.** Fails R3. The same statement in two projects would need two
+rows, and the migration would have to split existing shared rows.
+
+**Enforcement inside the store.** Attractive because a required parameter is compiler-checked at
+every call site, which is stronger than a convention. Rejected because the content cache is keyed by
+hash and returns before any query runs, so a predicate inside `getSheet` is skipped on a cache hit —
+and because the runners would be forced to supply a project purely to satisfy a signature, when they
+are executing already-authorized work rather than making an access decision.
+
+## Rollout
+
+Correctness rests on backfill completeness, which cannot be established by construction; a missed
+source is a silent NotFound (R4). Treat that as demonstrated risk rather than hypothesis — two
+drafts of this document got the source list wrong, first inventing two sources that do not exist,
+then naming the wrong column and nesting for `plan_check_run`.
+
+**Ship the gate in shadow mode.** It evaluates the scope check and logs a miss — project, hash, call
+site — but still returns content. Run one full release; flip to enforcing only once logs are clean.
+
+**Verify the backfill first.** Blobs with zero refs should be a small, non-growing population:
```sql
SELECT count(*) FROM sheet_blob b
WHERE NOT EXISTS (SELECT 1 FROM sheet_blob_ref r WHERE r.sha256 = b.sha256);
```
-A non-zero result is expected — it is the orphan-draft population noted under the backfill — but
-it should be small and should not grow once the shadow period begins. A large number means a
-source was missed.
-
-## Database project transfer
-
-The one case where a hash legitimately needs to become readable under a second project.
-
-`revision` has no project column — it keys on `(instance, db_name)` and inherits its project
-through `db`. When `BatchUpdateDatabases` sets `project = ?` (`backend/store/database.go:403`),
-a database's revision history follows it, and `convertToRevision` then formats the sheet name
-with the *new* project (`backend/api/v1/revision_service.go:304`). Under a strict check those
-reads would start returning NotFound for history that was readable before the transfer.
-
-Revisions are the only case. `changelog` also keys on `(instance, db_name)`, but carries no
-sheet reference at all, so it moves without implicating any hash.
-
-Handle it in the transfer path: when a database changes project, insert ref rows for the
-destination project covering every hash in that database's revisions, inside the transaction
-that already locks the project (`backend/store/database.go:512`). One statement, not a loop over
-revisions, and it stays one statement for a batch transfer of many databases:
+**Review multi-project hashes before enforcing.** Each is either honest dedup or a laundered
+reference, and the data cannot distinguish them, so this is a review list rather than a filter:
```sql
-INSERT INTO sheet_blob_ref (project, sha256)
-SELECT ?, decode(r.payload->>'sheetSha256', 'hex')
-FROM revision r
-WHERE (r.instance, r.db_name) IN (...)
- AND r.payload->>'sheetSha256' IS NOT NULL
- AND EXISTS (
- SELECT 1 FROM sheet_blob b
- WHERE b.sha256 = decode(r.payload->>'sheetSha256', 'hex')
- )
-ON CONFLICT DO NOTHING
+SELECT encode(sha256, 'hex'), count(DISTINCT project), array_agg(DISTINCT project)
+FROM sheet_blob_ref GROUP BY sha256 HAVING count(DISTINCT project) > 1;
```
-The `EXISTS` guard is the same one the backfill uses, and it matters more here. A revision naming
-a hash with no blob would otherwise violate the new foreign key and abort the whole
-`BatchUpdateDatabases` call — turning a scoping change into a regression on database transfer,
-a path that reads no sheet blobs today and has no reason to start failing.
-
-Ref rows for the source project stay — the content was genuinely authored there.
-
-This keeps the resource name honest rather than weakening the predicate to match the looser
-behavior.
+A long list means cross-project references are already widespread and the plan needs revisiting,
+since the backfill would make them permanent. Capture it at a known-good point: this design is
+public, including the rule that turns a reference into an ownership edge.
## Transaction lock ordering
-Two new multi-table write paths fall under the canonical ordering in
-`backend/store/README.md#transaction-row-lock-ordering`, which `AGENTS.md` requires be settled
-before the code is written.
-
-### Position in the canonical sibling order
-
-The README requires a new project-owned branch to establish its position in the canonical order
-before implementation, and to update that list, `DeleteProject`, and `DeleteInstance` together.
-`sheet_blob_ref` is a direct child of `project` with no descendants and no dependents, and every
-table that can reference a hash (`plan`, `task`, `release`, `plan_check_run`, `revision`) sits
-earlier in the list. Place it immediately after `db`:
+`sheet_blob_ref` is a project-owned branch and takes a position in the canonical sibling order in
+`backend/store/README.md`, updating that list, `DeleteProject`, and `DeleteInstance` together. It is
+a direct child of `project` with no descendants, and every table that can reference a hash sits
+earlier, so it belongs immediately after `db` and before `project_webhook` — the same position as
+the purge delete.
```text
... -> changelog -> sync_history -> revision -> db_schema -> db
-> sheet_blob_ref -> project_webhook -> service_account -> ...
```
-That is also where the purge delete belongs — between the `db` delete
-(`backend/store/project.go:704`) and `project_webhook` (`:739`) — so the purge sequence and the
-canonical list stay consistent.
-
-### Lifecycle policy
-
-`sheet_blob_ref` is purge-managed data, so the README requires its writers to state whether they
-need an **active** project or merely an **existing** one, and to serialize that against project
-deletion.
-
-**`CreateSheets` requires an active project.** A sheet ref is a new resource; there is no
-deleted-project continuation case for it. The API create paths check the project before calling
-the store, but that check is not serialized with purge — a concurrent purge between the check and
-the insert would surface as a raw foreign-key violation rather than a controlled NotFound. So
-`CreateSheets` takes the same transaction-scoped purge fence before any row lock that database
-creation, batch database updates, and task-run creation already take.
-
-The transfer path needs nothing extra here: `BatchUpdateDatabases` already locks every involved
-project `FOR UPDATE` (`backend/store/database.go:509-517`) and fails NotFound on a missing one.
-
-### Ordering of the two paths
-
-- **`CreateSheets`** spans `sheet_blob` and `sheet_blob_ref`. Insert the blob first, then the
- ref: the ref's foreign key requires the blob to exist, so the order is forced. Both are
- `ON CONFLICT DO NOTHING` — new-row-only inserts, not upserts that can update an existing row,
- so the README's rule 4 upsert clause does not apply to them. The foreign-key checks on
- `project` and `sheet_blob` do count as locks and are covered by the purge fence above.
-- **The transfer path** inserts refs inside the existing `BatchUpdateDatabases` transaction,
- which has already taken `FOR UPDATE` on every involved project. Note this is *not* an instance
- of the child-to-parent rule — that rule governs locking **existing** rows, and these refs are
- new rows with nothing to lock beforehand. The insert is safe here because the transaction
- already holds a stronger lock on the parent than the foreign-key check needs, not because
- parent-then-child is the required order. It is not; an earlier draft of this doc claimed
- otherwise.
+`CreateSheets` becomes a transaction spanning `sheet_blob` and `sheet_blob_ref`. Insert the blob
+first: the ref's foreign key requires it, so the order is forced. Both are `ON CONFLICT DO NOTHING`
+— new-row-only inserts, not upserts that can update an existing row, so the README's rule 4 upsert
+clause does not apply.
+
+As a writer of purge-managed data, `CreateSheets` must declare a lifecycle policy. **It requires an
+active project**: a sheet ref is a new resource with no deleted-project continuation case. The API
+create paths check the project before calling the store, but that check is not serialized with
+purge, so a concurrent purge would surface as a raw foreign-key violation rather than a controlled
+NotFound. `CreateSheets` therefore takes the same transaction-scoped purge fence that database
+creation and task-run creation already take; `withDatabasePurgeFence`
+(`backend/store/database.go:798-820`) is the pattern to mirror.
Both need the deterministic real-PostgreSQL regression tests that section mandates, asserting
-terminal outcomes in both lock-acquisition directions rather than merely the absence of
-SQLSTATE `40P01`, and covering the create-versus-purge race named above.
+terminal outcomes in both lock-acquisition directions rather than merely the absence of SQLSTATE
+`40P01`.
-## Independent fixes, no schema needed
+## Independent fixes
-These are worth landing separately and first — none needs a migration.
+No schema needed; worth landing separately and first.
1. **The T6 hash echo.** `backend/api/v1/revision_service.go:203` takes `projectID` from the
attacker-supplied `revision.File` and uses it as a store key without comparing it to
`database.ProjectID`. `FindReleaseMessage` has no `Workspace` field
(`backend/store/release.go:30-37`), so this reaches any project in any workspace, and `:223`
- echoes the real hash. Add the comparison; drop the hash from the error string. The same
- missing comparison appears for `revision.TaskRun` at `:167-186`.
-2. **Delete the two stale comments** at `release_service.go:331` and `:405`
- (`// Sheets are now project-agnostic, no need to check projectID`). They are now false and
- will mislead the next reader into repeating the mistake.
-3. **Add audit annotations** to `proto/v1/v1/sheet_service.proto`. It declares none, while 20
- other v1 services do — so sheet reads and enumeration are currently unlogged.
-4. **Drop `bb.sheets.update`.** Granted to four roles in `backend/store/predefined_roles.go`,
- declared by no RPC; dead since sheets became immutable.
-5. **Comment the GC hazard on `sheet_blob`.** Nothing deletes from it today — not the cleaner,
- not project purge, and there is no `DeleteSheet` RPC. The only foreign key that ever pointed
- at it (`task_run.sheet_sha256`, migration 3.14) was dropped in `7192406c5f`, so every
- surviving reference now lives in JSONB and is invisible to referential integrity. A future GC
- written the obvious way — "delete blobs no FK points at" — would empty the table.
- `sheet_blob_ref` makes a correct GC possible later, but that is out of scope here.
+ echoes the real hash. Add the comparison, drop the hash from the error. The same missing
+ comparison appears for `revision.TaskRun` at `:167-186`. This is the cheapest way to obtain a hash
+ today and should go first.
+2. **Delete the stale comments** at `release_service.go:331` and `:405`
+ (`// Sheets are now project-agnostic, no need to check projectID`) — the original wrong assumption,
+ sitting where it will talk the next reader into repeating it.
+3. **Add audit annotations** to `proto/v1/v1/sheet_service.proto`, which declares none while 20 other
+ v1 services do, leaving sheet reads and enumeration unlogged.
+4. **Drop `bb.sheets.update`** — granted to four roles, declared by no RPC, dead since sheets became
+ immutable.
+5. **Comment the GC hazard on `sheet_blob`.** Nothing deletes from it; the only foreign key that ever
+ pointed at it (`task_run.sheet_sha256`, migration 3.14) was dropped in `7192406c5f`, so every
+ surviving reference lives in JSONB and is invisible to referential integrity. A GC written the
+ obvious way — delete blobs no FK points at — would empty the table. `sheet_blob_ref` makes a
+ correct GC possible later.
## Tests
-- **Cross-project read** — seed a blob in project A, request it under project B, expect
- NotFound. This is the regression test for the whole finding. Run it with A and B in the same
- workspace *and* in different workspaces; the second is the tenant-isolation case.
-- **Cache ordering** — request a blob under its owning project to warm the cache, then request
- the same hash under a foreign project and assert NotFound. This is the test that fails if
- enforcement ever migrates back into `getSheet` behind the cache read.
-- **Gate coverage** — assert nothing under `backend/api/v1/` calls a store sheet content getter
- outside the gate helper.
-- **Query count** — create a release with many files and assert the gate issues a bounded number
- of queries, not one per file. A count assertion is the only thing that actually holds the batch
- shape; a correctness test passes just as happily against an N+1 implementation.
-- **Backfill** — build a metadata DB exercising each of the five reference sources, run the
- migration, assert every referenced hash resolves under its project and no unreferenced hash
- does.
-- **Project purge** — purge a project that owns sheet refs and assert it succeeds. This is the
- direct regression test for the new foreign key.
-- **Transfer** — create a revision under project A, move the database to project B, assert the
- statement is still readable under B. Add a variant where a revision names a hash with no blob
- and assert the transfer still succeeds, covering the `EXISTS` guard.
-- **Create versus purge** — the deterministic race required by the lifecycle policy: a
- `CreateSheets` concurrent with a purge of its project must end in a controlled NotFound, not a
- foreign-key error, in both lock-acquisition directions.
-- **Multi-project hashes** — seed a plan in project B referencing a hash created in project A
- (the pre-existing unscoped path), run the backfill, and assert the audit query reports it.
- The point is that the row is *detected*, not that it is silently blessed.
+- **Cross-tenant read** — seed a blob in workspace W1, request it under a project in W2, expect
+ NotFound. The regression test for the severe half.
+- **Cross-project read** — same workspace, different project, expect NotFound. The regression test
+ for R6.
+- **Cache ordering** — warm the cache under the owning project, then request the same hash under a
+ foreign project and assert NotFound. Fails if enforcement ever migrates into `getSheet` behind the
+ cache read.
+- **Gate confinement** — nothing under `backend/api/v1/` calls a store content getter outside the
+ gate.
+- **Query count** — a release with many files must issue a bounded number of queries. A correctness
+ test passes just as happily against an N+1.
+- **Backfill** — exercise all five sources; every referenced hash resolves under its project and no
+ unreferenced hash does.
+- **Multi-project hashes** — seed a plan in project B referencing a hash created in project A, run
+ the backfill, assert the audit query reports it. The point is that it is detected, not blessed.
+- **Project purge** — purge a project holding sheet refs and assert it succeeds. Direct regression
+ test for the new foreign key.
+- **Create versus purge** — `CreateSheets` concurrent with a purge of its project ends in a
+ controlled NotFound, not a foreign-key error, in both lock-acquisition directions.
- **`HasSheets`** no longer answers for a foreign project's hash.
-- **`TestCollision_Sheet`** in `backend/tests/`, per the composite-PK convention in `AGENTS.md`.
- Note that the shared `setupCollidingProjects` fixture and `assertProjectUnchanged` helper do
- not currently cover sheets — extend them first rather than writing a table-specific variant.
-- **Lock ordering** — the deterministic real-PostgreSQL tests required by the section above, for
- `CreateSheets` and for the transfer path.
+- **`TestCollision_Sheet`** per the composite-PK convention in `AGENTS.md`. The shared
+ `setupCollidingProjects` fixture and `assertProjectUnchanged` helper do not currently cover sheets;
+ extend them rather than writing a table-specific variant.
## Order
-1. The five no-schema fixes above — T6 first, since it is the cheapest way to obtain a hash.
-2. Migration, backfill, purge delete, backfill verification query.
-3. Run the multi-project audit query and review its output. This is a gate, not a report: a long
- list means cross-project references are already widespread and the plan needs revisiting
- before enforcement, since the backfill would otherwise make them permanent.
-4. Store API split, gate helper, call sites, transfer handling, tests — gate shipping in shadow
- mode.
-5. Flip the gate to denying, one release later, once the shadow log is clean.
+1. The five independent fixes, T6 first.
+2. Migration and backfill; run both verification queries and review the multi-project list.
+3. Store API, gate, call sites, purge delete, tests — gate shipping in shadow mode.
+4. Flip to enforcing one release later, once shadow logs are clean.
diff --git a/docs/design/sheet-history-on-database-transfer.md b/docs/design/sheet-history-on-database-transfer.md
new file mode 100644
index 0000000000..eec386bca7
--- /dev/null
+++ b/docs/design/sheet-history-on-database-transfer.md
@@ -0,0 +1,176 @@
+# Database change history across project transfers
+
+Companion to [`sheet-blob-scoping.md`](sheet-blob-scoping.md), which scopes sheet content to the
+owning project. This document decides what a project sees of a database's change history after the
+database is transferred into it: **the history list follows the database, the statement text does
+not.**
+
+## Background
+
+`revision` and `changelog` have no project column. They key on `(instance, db_name)` and inherit
+their project through `db.project`, so when `UPDATE db SET project = ?` runs, the history moves with
+the database. This was never a design decision; it falls out of the schema. `convertToRevision` then
+formats the sheet name with the database's new project
+(`backend/api/v1/revision_service.go:304`), so a project-scoped sheet gate denies statements that
+were readable moments earlier.
+
+Four code paths move a database between projects, only one of which is a user-facing transfer:
+
+| Path | Location | Scope |
+|---|---|---|
+| `UpdateDatabase` | `backend/store/database.go:332-380` | one database |
+| `BatchUpdateDatabases` | `backend/store/database.go:397-560` | a batch |
+| `updateInstanceLifecycle` | `backend/store/instance.go:438-455` | every database of an instance, on project-instance archive |
+| `DeleteProject` | `backend/store/project.go:722-729` | workspace-instance databases, reassigned to the default project |
+
+The last is easy to miss: purge does not delete workspace-instance databases, it reassigns them to
+the default project, and the `revision` delete at `:702` covers only project instances — so those
+revisions survive a purge with their hashes intact.
+
+## Requirements
+
+**R1 — The applied-version ledger stays complete regardless of project.** `revision` carries a
+`version` column and serves as Bytebase's equivalent of `flyway_schema_history`: the record of which
+versioned migrations have already run against a database. Hiding revisions from the project
+currently holding the database risks a versioned release re-running migrations that already applied.
+This is a correctness constraint, not a preference.
+
+**R2 — The audit record survives reorgs intact.** Regulated customers must answer "what changed on
+this database, when, and by whom" for the full life of the database, across ownership changes. A
+database moving between teams is an administrative event and must not create a gap in the compliance
+record.
+
+**R3 — The inheriting team can operate the database.** Whoever takes ownership needs to know what has
+been applied. Handing a team a production database whose history is a black box is a worse outcome
+than the disclosure it avoids.
+
+**R4 — Projects remain a confidentiality boundary.** A database transfer that silently grants the
+destination project read access to statements the source project authored is a policy violation, and
+one performed by an operation that does not present itself as an access change. The principals who
+gain access are not the person performing the transfer — who already holds rights on both sides —
+but the destination project's other members.
+
+R1 through R3 are satisfied by any design that keeps the history list complete. R4 is the only
+requirement that discriminates, and it concerns statement text rather than the list.
+
+## Current behavior
+
+### Changelogs carry no SQL
+
+The v1 `Changelog` message (`proto/v1/v1/changelog_service.proto:105`) carries `name`, `create_time`,
+`status`, `schema` and `schema_size`, `task_run`, and `plan_title`. There is no statement and no
+sheet field; fields 4–6, 9–10 and 12–14 are reserved, having been removed as the model evolved.
+`backend/api/v1/changelog_service.go` populates no statement either.
+
+A changelog therefore answers when a change ran, whether it succeeded, what the schema looked like
+afterwards, and which rollout produced it — entirely from its own row. The `schema` snapshot is the
+load-bearing part: consecutive changelogs diff to show what changed structurally without reference
+to the SQL text. R2 rests almost entirely on this record, and no part of it depends on sheet scoping.
+
+### Changelog SQL already stops at the project boundary
+
+The statement behind a changelog is reachable only through `task_run` → `task.payload.sheetSha256`.
+`task` is project-scoped with its own column and does not move with the database. The stored pointer
+keeps naming the source project (`FormatTaskRun(database.ProjectID, ...)` at
+`backend/runner/taskrun/database_migrate_executor.go:273`), and resolving it requires rights on that
+project.
+
+Changelogs already implement *metadata follows the database, SQL stays with the authoring project*.
+That behavior predates this work.
+
+### Revisions carry a hash directly
+
+`RevisionPayload.sheet_sha256` names the sheet inline, so revisions — unlike changelogs — surface
+statement content through the sheet gate. They are the only history record this decision affects.
+
+## Design
+
+Change history follows the database; statement content does not.
+
+- Revision and changelog lists are returned in full after a transfer, including entries created under
+ a previous project. Versions, timestamps, authors, status, schema snapshots, and the sheet *name*
+ are all present.
+- When a revision's sheet is not readable by the current project, the statement is withheld and the
+ response says so explicitly, naming the owning project, rather than returning NotFound for the
+ sheet.
+- No sheet references are carried between projects. A database transfer grants no new read access,
+ and the four reassignment paths above need no changes.
+
+This satisfies R1 through R3 by keeping the list intact and R4 by leaving statement text with the
+project that authored it. It also makes revisions consistent with how changelogs already behave,
+rather than introducing two rules for two views of the same history.
+
+The explicit withholding matters as much as the withholding itself. A destination team that sees
+"statement owned by project `payments-core`" can make an informed request to the right owner. A team
+that sees a list of failed content loads sees a broken product.
+
+The owning project is derivable without new storage: `sheet_blob_ref` records which projects hold a
+ref for a hash, so the withheld response can name them. This discloses that some other project holds
+SQL with that hash, which is acceptable within a workspace and is strictly less than the content
+itself.
+
+## Alternatives considered
+
+**Carry sheet references on transfer.** On any project change, insert ref rows for the destination
+covering every hash in that database's revisions. Preserves current behavior exactly and grants
+narrowly — only hashes that database's own revisions reference. It fails R4: it widens access as a
+side effect of an operation that is not about access, for principals who were not party to it.
+
+It is also the most machinery of any option, and the machinery is where the risk lives. A carry
+helper must be wired into all four paths, purge additionally requires carrying before the source
+project's refs are deleted, and each path needs its own test because the failure is silent until a
+later read. Three of the four paths were missed on first analysis; only `BatchUpdateDatabases` is an
+obvious transfer, and the other three are consequences of unrelated operations.
+
+**Withhold with no signal.** Carry nothing and let the gate return NotFound. Costs nothing and
+satisfies R4, but produces a history list where every statement fails to load with no indication of
+why or where to look. This is the default outcome if the decision is not made explicitly, which is
+the main reason to make it explicitly.
+
+**Project-scope revisions and changelogs.** Add a `project` column to both, set at creation, and
+filter reads to the caller's project, so a database transferred into project B shows only history
+created while it was in B. This is the cleanest authorization story — history becomes project-scoped
+like `plan`, `task`, `issue`, and `release` — and it would also resolve the dangling `taskRun`
+pointer noted below. It fails R1: a transferred database would appear to have no applied versions,
+and a versioned release would re-run migrations that already ran. A reorg-triggered path to data
+corruption outweighs the modelling improvement.
+
+> This rejection rests on revisions being what determines whether a version is already applied.
+> Confirm against `runVersionedRelease` in
+> `backend/runner/taskrun/database_migrate_executor.go` before treating it as settled. If revisions
+> do not drive version-skip logic, this alternative becomes considerably more attractive.
+
+**Delete history on transfer.** Fails R1, R2, and R3 simultaneously. Recorded for completeness.
+
+## Implementation
+
+- A field on the revision response carrying the withheld-content reason and the owning project, plus
+ the handler change to populate it from `sheet_blob_ref`.
+- A UI affordance for the withheld state that names the owning project rather than rendering an
+ error.
+- No changes to `UpdateDatabase`, `BatchUpdateDatabases`, `updateInstanceLifecycle`, or
+ `DeleteProject`.
+
+Tests: create a revision under project A, move the database to project B, then assert the revision
+list is complete under B while the statement is withheld with A named. Repeat for the purge path,
+where a workspace-instance database is reassigned to the default project — the case most likely to
+regress, since it is not a user-facing transfer.
+
+## Open items
+
+**Sheet name attribution.** `convertToRevision` formats the sheet name with the database's current
+project, which is incorrect after a transfer: it names the destination as owner of a sheet the source
+authored. Deriving the owner from `sheet_blob_ref` covers the withheld-content response, but the
+`name` field itself remains wrong. Recording the authoring project on the revision at creation would
+fix it for new rows; rows predating the migration cannot recover it.
+
+**Workspace-level roles have no escape hatch.** The gate checks the ref table for the named project,
+so workspace admins and DBAs are refused as well, despite holding `bb.sheets.get` broadly. Whether
+workspace-scoped roles should bypass project scoping is a policy decision worth making deliberately
+rather than inheriting from the mechanism.
+
+**`plan_title` crosses the boundary today.** It is derived by parsing the source project out of the
+stored `taskRun` string and joining through it (`backend/store/changelog.go:163-168`), so a changelog
+in the destination project surfaces the source project's plan title. Minor and pre-existing, but it
+is the one place changelog display crosses a project line, and it should be fixed or accepted
+deliberately.