Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
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.mdindex 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 projectFixes 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 theproject-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:```sqlSELECT count(*) FROM sheet_blob bWHERE 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 theattacker-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.mdnew file mode 100644index 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.