Skip to content

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

feat: scope sheet content to its owning project (T5)

Dannya4c2dc47aaf0
diff --git a/AGENTS.md b/AGENTS.md
index b357d88b03..3fcd73aeb1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -212,12 +212,14 @@ When writing or modifying queries on these tables:
- When adding a new store method touching a composite-PK table, add a corresponding
`TestCollision_*` test in `backend/tests/`. The existing `setupCollidingProjects`
fixture and `assertProjectUnchanged` helper cover `plan`, `issue`, `task`, `task_run`,
- `plan_check_run`, `task_run_log`, `db_group`, and `release` (the snapshot reads the
- last three through public APIs where one exists). `plan_webhook_delivery` has no
- public read API and uses a table-specific raw metadata-DB read; its rows are
+ `plan_check_run`, `task_run_log`, `db_group`, `release`, and `sheet_blob_ref` (the
+ snapshot reads the last four through public APIs where one exists). `plan_webhook_delivery`
+ has no public read API and uses a table-specific raw metadata-DB read; its rows are
claimed asynchronously after rollout completion, so raw-read collision tests
must stabilize before snapshotting and compare the table separately (see
- `backend/tests/README.md`). For any future composite-PK table outside that set,
+ `backend/tests/README.md`). `sheet_blob_ref` also has no public read API and is
+ read raw, but its rows are written synchronously, so `assertProjectUnchanged`
+ compares them directly. For any future composite-PK table outside that set,
write table-specific seed and assertion helpers — or extend the shared helper
first
- Collision tests use `setupCollidingProjects` + `fixture.completeRolloutB` for setup
diff --git a/backend/api/v1/audit.go b/backend/api/v1/audit.go
index 1b8ce37842..07c7925def 100644
--- a/backend/api/v1/audit.go
+++ b/backend/api/v1/audit.go
@@ -463,6 +463,10 @@ func getRequestResource(request any) string {
return r.Name
case *v1pb.ExportRequest:
return r.Name
+ case *v1pb.CreateSheetRequest:
+ return r.GetParent()
+ case *v1pb.BatchCreateSheetsRequest:
+ return r.GetParent()
case *v1pb.UpdateDatabaseRequest:
return r.Database.Name
case *v1pb.BatchUpdateDatabasesRequest:
@@ -560,6 +564,22 @@ func getRequestString(request any) (string, error) {
r = proto.CloneOf(r)
r.IdentityProvider = redactIdentityProvider(r.IdentityProvider)
return r
+ case *v1pb.CreateSheetRequest:
+ // The clone is already private; drop the content in place instead
+ // of cloning the potentially large sheet a second time.
+ r = proto.CloneOf(r)
+ if r.Sheet != nil {
+ r.Sheet.Content = nil
+ }
+ return r
+ case *v1pb.BatchCreateSheetsRequest:
+ r = proto.CloneOf(r)
+ for _, cr := range r.Requests {
+ if cr.Sheet != nil {
+ cr.Sheet.Content = nil
+ }
+ }
+ return r
case *v1pb.UpdateIdentityProviderRequest:
r = proto.CloneOf(r)
r.IdentityProvider = redactIdentityProvider(r.IdentityProvider)
@@ -610,6 +630,14 @@ func getResponseString(response any) (string, error) {
return redactUser(r)
case *v1pb.Instance:
return redactInstance(r)
+ case *v1pb.Sheet:
+ return redactSheet(r)
+ case *v1pb.BatchCreateSheetsResponse:
+ n := &v1pb.BatchCreateSheetsResponse{}
+ for _, sheet := range r.Sheets {
+ n.Sheets = append(n.Sheets, redactSheet(sheet))
+ }
+ return n
default:
if p, ok := r.(protoreflect.ProtoMessage); ok {
return p
@@ -850,6 +878,18 @@ func redactUser(r *v1pb.User) *v1pb.User {
}
}
+// redactSheet strips the sheet content from audit payloads. Sheets carry full
+// SQL statements (potentially megabytes); the audit record keeps the resource
+// name and content size.
+func redactSheet(s *v1pb.Sheet) *v1pb.Sheet {
+ if s == nil {
+ return nil
+ }
+ cloned := proto.CloneOf(s)
+ cloned.Content = nil
+ return cloned
+}
+
func redactInstance(i *v1pb.Instance) *v1pb.Instance {
if i == nil {
return nil
diff --git a/backend/api/v1/plan_service.go b/backend/api/v1/plan_service.go
index e7b1930040..7c64b68c02 100644
--- a/backend/api/v1/plan_service.go
+++ b/backend/api/v1/plan_service.go
@@ -741,17 +741,6 @@ func validateSpecs(ctx context.Context, s *store.Store, projectID string, specs
}
}
- // Validate sheets existence.
- if len(sheetSha256s) > 0 {
- exist, err := s.HasSheets(ctx, sheetSha256s...)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to check sheets: %v", err))
- }
- if !exist {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("some sheets are not found"))
- }
- }
-
// Validate release existence.
if releaseString != "" {
releaseProjectID, releaseID, err := common.GetProjectReleaseID(releaseString)
@@ -771,6 +760,21 @@ func validateSpecs(ctx context.Context, s *store.Store, projectID string, specs
if release == nil {
return nil, errors.Errorf("release %s not found", releaseID)
}
+ // The release's files were validated against this project when the
+ // release was created (releases are immutable — UpdateRelease is
+ // Unimplemented), and refs are deleted only by project purge, which
+ // deletes the release too. No per-use recheck of its files.
+ }
+
+ // Validate sheets existence.
+ if len(sheetSha256s) > 0 {
+ missing, err := s.MissingSheetsForProject(ctx, projectID, sheetSha256s...)
+ if err != nil {
+ return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to check sheets: %v", err))
+ }
+ if len(missing) > 0 {
+ return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("sheet %q not found", common.FormatSheet(projectID, missing[0])))
+ }
}
return databaseGroup, nil
}
diff --git a/backend/api/v1/release_service.go b/backend/api/v1/release_service.go
index 6fc31b9dbc..58540ed82f 100644
--- a/backend/api/v1/release_service.go
+++ b/backend/api/v1/release_service.go
@@ -72,38 +72,33 @@ func (s *ReleaseService) CreateRelease(ctx context.Context, req *connect.Request
return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("project %s not found", projectID))
}
- sanitizedFiles, err := validateAndSanitizeReleaseFiles(ctx, s.store, req.Msg.Release.Files, req.Msg.Release.Type)
+ sanitizedFiles, err := validateAndSanitizeReleaseFiles(req.Msg.Release.Files, req.Msg.Release.Type)
if err != nil {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.Wrapf(err, "invalid release files"))
}
- sheetsToCreate := []*store.SheetMessage{}
- var filesWithoutSheet []*v1pb.Release_File
- // Prepare sheets to create for files with missing sheets.
- // Check versions.
+ var sheetsToCreate []*store.SheetMessage
+ var referencedSheetSha256s []string
for _, file := range sanitizedFiles {
if file.Sheet == "" {
// statement must be present due to validation in validateAndSanitizeReleaseFiles
- sheet := &store.SheetMessage{
+ sheetsToCreate = append(sheetsToCreate, &store.SheetMessage{
Statement: string(file.Statement),
- }
- sheetsToCreate = append(sheetsToCreate, sheet)
- filesWithoutSheet = append(filesWithoutSheet, file)
+ })
+ } else {
+ referencedSheetSha256s = append(referencedSheetSha256s, file.SheetSha256)
}
}
- // Batch create sheets if needed.
- if len(sheetsToCreate) > 0 {
- createdSheets, err := s.store.CreateSheets(ctx, sheetsToCreate...)
+ // Referenced sheets must carry this project's ref. This is the only gate:
+ // releases are immutable, so nothing rechecks the files after creation.
+ // One batched ref check, no content read.
+ if len(referencedSheetSha256s) > 0 {
+ missing, err := s.store.MissingSheetsForProject(ctx, project.ResourceID, referencedSheetSha256s...)
if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to create sheets"))
+ return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to check sheets"))
}
- if len(createdSheets) != len(sheetsToCreate) {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to create all sheets, expected %d but got %d", len(sheetsToCreate), len(createdSheets)))
- }
-
- // Map created sheets back to files.
- for i, sheet := range createdSheets {
- filesWithoutSheet[i].Sheet = common.FormatSheet(project.ResourceID, sheet.Sha256)
+ if len(missing) > 0 {
+ return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("sheet %q not found", common.FormatSheet(project.ResourceID, missing[0])))
}
}
@@ -117,12 +112,22 @@ func (s *ReleaseService) CreateRelease(ctx context.Context, req *connect.Request
releaseIDTimezone = "UTC"
}
- // Compute train from template and timezone.
+ // Compute train from template and timezone. Rendering can reject the
+ // template, so it runs before any write.
train, err := renderTrain(releaseIDTemplate, releaseIDTimezone, time.Now())
if err != nil {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.Wrapf(err, "failed to render train"))
}
+ // Create sheets for files that carried inline statements. The hashes were
+ // already computed by validateAndSanitizeReleaseFiles; CreateSheets stamps
+ // the same content hash and mints this project's refs.
+ if len(sheetsToCreate) > 0 {
+ if _, err := s.store.CreateSheets(ctx, project.ResourceID, sheetsToCreate...); err != nil {
+ return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to create sheets"))
+ }
+ }
+
releaseMessage := &store.ReleaseMessage{
ProjectID: project.ResourceID,
Train: train,
@@ -133,26 +138,13 @@ func (s *ReleaseService) CreateRelease(ctx context.Context, req *connect.Request
},
}
- var sheetSha256s []string
+ // Every file's SheetSha256 is populated and project-scoped by now — ref
+ // checked above or computed for a sheet created under this project — so
+ // the payload builds from it directly.
for _, f := range sanitizedFiles {
- _, sheetSha256, err := common.GetProjectResourceIDSheetSha256(f.Sheet)
- if err != nil {
- return nil, errors.Wrapf(err, "failed to get sheetSha256 from %q", f.Sheet)
- }
- sheetSha256s = append(sheetSha256s, sheetSha256)
- }
- exist, err := s.store.HasSheets(ctx, sheetSha256s...)
- if err != nil {
- return nil, errors.Wrapf(err, "failed to check sheets")
- }
- if !exist {
- return nil, errors.Errorf("some sheets are not found")
- }
-
- for i, f := range sanitizedFiles {
releaseMessage.Payload.Files = append(releaseMessage.Payload.Files, &storepb.ReleasePayload_File{
Path: f.Path,
- SheetSha256: sheetSha256s[i],
+ SheetSha256: f.SheetSha256,
Version: f.Version,
})
}
@@ -329,7 +321,6 @@ func convertToRelease(release *store.ReleaseMessage) *v1pb.Release {
}
for _, f := range release.Payload.Files {
- // Sheets are now project-agnostic, no need to check projectID
r.Files = append(r.Files, &v1pb.Release_File{
Path: f.Path,
Sheet: common.FormatSheet(release.ProjectID, f.SheetSha256),
@@ -360,14 +351,15 @@ func convertReleaseVcsSource(vs *v1pb.Release_VCSSource) *storepb.ReleasePayload
}
}
-// validateAndSanitizeReleaseFiles validates and sanitizes the release files inputs.
-// It ensures that each file has either a sheet or a statement, and that the sheet is valid.
-// It also checks for duplicate versions in versioned releases and sorts the files by version.
+// validateAndSanitizeReleaseFiles validates and sanitizes the release files
+// inputs: each file has either a sheet or a statement, versions are unique for
+// versioned releases, and files come back sorted by version. SheetSha256 is
+// populated in place from the sheet name or computed from the statement.
//
-// The input files are modified in place.
-// If a sheet is provided, it populates the statement from the sheet.
-// If a statement is provided, it computes the sheetSha256 from the statement.
-func validateAndSanitizeReleaseFiles(ctx context.Context, s *store.Store, files []*v1pb.Release_File, releaseType v1pb.Release_Type) ([]*v1pb.Release_File, error) {
+// No store reads happen here. Callers enforce sheet scope themselves:
+// CreateRelease checks the project's refs with MissingSheetsForProject before
+// persisting; CheckRelease reads content through the project-scoped accessor.
+func validateAndSanitizeReleaseFiles(files []*v1pb.Release_File, releaseType v1pb.Release_Type) ([]*v1pb.Release_File, error) {
if len(files) == 0 {
return nil, errors.Errorf("release files cannot be empty")
}
@@ -388,23 +380,12 @@ func validateAndSanitizeReleaseFiles(ctx context.Context, s *store.Store, files
f.SheetSha256 = hex.EncodeToString(h[:])
case f.Sheet != "" && len(f.Statement) > 0:
return nil, errors.Errorf("cannot set both sheet and statement for file %q", f.Path)
-
- // If sheet is provided but statement is not, populate statement from sheet
case f.Sheet != "":
_, sheetSha256, err := common.GetProjectResourceIDSheetSha256(f.Sheet)
if err != nil {
return nil, errors.Wrapf(err, "failed to get sheet SHA256 from %q", f.Sheet)
}
- sheet, err := s.GetSheetFull(ctx, sheetSha256)
- if err != nil {
- return nil, errors.Wrapf(err, "failed to get sheet %q", f.Sheet)
- }
- if sheet == nil {
- return nil, errors.Errorf("sheet %q not found", f.Sheet)
- }
- // Sheets are now project-agnostic, no need to check projectID
- f.Statement = []byte(sheet.Statement)
- f.SheetSha256 = sheet.Sha256
+ f.SheetSha256 = sheetSha256
case len(f.Statement) > 0:
// populate sheetSha256 from statement
h := sha256.Sum256(f.Statement)
diff --git a/backend/api/v1/release_service_check.go b/backend/api/v1/release_service_check.go
index 12f84ee69d..b0577df20c 100644
--- a/backend/api/v1/release_service_check.go
+++ b/backend/api/v1/release_service_check.go
@@ -157,13 +157,17 @@ func (s *ReleaseService) CheckRelease(ctx context.Context, req *connect.Request[
}
// Validate and sanitize release files.
- sanitizedFiles, err := validateAndSanitizeReleaseFiles(ctx, s.store, request.Release.Files, request.Release.Type)
+ sanitizedFiles, err := validateAndSanitizeReleaseFiles(request.Release.Files, request.Release.Type)
if err != nil {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.Wrapf(err, "invalid release files"))
}
if len(sanitizedFiles) == 0 {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.New("release files cannot be empty"))
}
+ // The checks below run over the SQL itself, so load sheet content here.
+ if err := loadReleaseFileStatements(ctx, s.store, projectID, sanitizedFiles); err != nil {
+ return nil, err
+ }
if err := s.touchVCSProviderUser(ctx, workspaceID, request.GetVcsUser()); err != nil {
return nil, err
@@ -190,6 +194,37 @@ func (s *ReleaseService) CheckRelease(ctx context.Context, req *connect.Request[
return connect.NewResponse(response), nil
}
+// loadReleaseFileStatements populates Statement for files that reference a
+// sheet, reading full content through the project-scoped accessor. The scoped
+// read is also what scopes CheckRelease: a sheet without this project's ref
+// comes back absent and errors as not found.
+func loadReleaseFileStatements(ctx context.Context, s *store.Store, projectID string, files []*v1pb.Release_File) error {
+ var sheetSha256s []string
+ for _, f := range files {
+ if f.Sheet != "" {
+ sheetSha256s = append(sheetSha256s, f.SheetSha256)
+ }
+ }
+ if len(sheetSha256s) == 0 {
+ return nil
+ }
+ sheets, err := s.GetSheetsForProject(ctx, projectID, sheetSha256s, true)
+ if err != nil {
+ return connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to get sheets"))
+ }
+ for _, f := range files {
+ if f.Sheet == "" {
+ continue
+ }
+ sheet, ok := sheets[f.SheetSha256]
+ if !ok {
+ return connect.NewError(connect.CodeNotFound, errors.Errorf("sheet %q not found", f.Sheet))
+ }
+ f.Statement = []byte(sheet.Statement)
+ }
+ return nil
+}
+
func (s *ReleaseService) touchVCSProviderUser(ctx context.Context, workspaceID string, vcsUser *v1pb.VCSUser) error {
if vcsUser == nil {
return nil
@@ -372,7 +407,7 @@ loop:
File: file.Path,
Target: target.name,
}
- // statement is guaranteed to be populated by validateAndSanitizeReleaseFiles
+ // statement is guaranteed to be populated by loadReleaseFileStatements
statement := string(file.Statement)
// Check if any syntax error in the statement.
if common.EngineSupportSyntaxCheck(engine) {
@@ -617,7 +652,7 @@ func (s *ReleaseService) checkReleaseDeclarative(ctx context.Context, files []*v
Target: target.name,
}
- // statement is guaranteed to be populated by validateAndSanitizeReleaseFiles
+ // statement is guaranteed to be populated by loadReleaseFileStatements
statement := string(file.Statement)
// Check if any syntax error in the statement.
diff --git a/backend/api/v1/revision_service.go b/backend/api/v1/revision_service.go
index 288c5b10ec..3c03280c03 100644
--- a/backend/api/v1/revision_service.go
+++ b/backend/api/v1/revision_service.go
@@ -73,7 +73,7 @@ func (s *RevisionService) ListRevisions(
revisions = revisions[:offset.limit]
}
- converted := convertToRevisions(formatDatabaseParent(instance, database), database.ProjectID, revisions)
+ converted := convertToRevisions(formatDatabaseParent(instance, database), revisions)
return connect.NewResponse(&v1pb.ListRevisionsResponse{
Revisions: converted,
@@ -97,9 +97,12 @@ func (s *RevisionService) GetRevision(
revision, err := s.store.GetRevision(ctx, revisionID, database.InstanceID, database.DatabaseName)
if err != nil {
+ if common.ErrorCode(err) == common.NotFound {
+ return nil, connect.NewError(connect.CodeNotFound, errors.Wrapf(err, "revision %v not found", request.Name))
+ }
return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to get revision %v", request.Name))
}
- converted := convertToRevision(formatDatabaseParent(instance, database), database.ProjectID, revision)
+ converted := convertToRevision(formatDatabaseParent(instance, database), revision)
return connect.NewResponse(converted), nil
}
@@ -155,12 +158,12 @@ func (s *RevisionService) createRevisions(
sheetSha256s = append(sheetSha256s, sha)
}
- exist, err := s.store.HasSheets(ctx, sheetSha256s...)
+ missing, err := s.store.MissingSheetsForProject(ctx, database.ProjectID, sheetSha256s...)
if err != nil {
return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to check sheets: %v", err))
}
- if !exist {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("some sheets are not found"))
+ if len(missing) > 0 {
+ return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("sheet %q not found", common.FormatSheet(database.ProjectID, missing[0])))
}
var createdRevisions []*v1pb.Revision
@@ -170,6 +173,9 @@ func (s *RevisionService) createRevisions(
if err != nil {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.Errorf("failed to get taskRun from %q", revision.TaskRun))
}
+ if projectID != database.ProjectID {
+ return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("taskRun %q not found", revision.TaskRun))
+ }
taskRun, err := s.store.GetTaskRunV1(ctx, &store.FindTaskRunMessage{
Workspace: common.GetWorkspaceIDFromContext(ctx),
ProjectID: projectID,
@@ -204,6 +210,9 @@ func (s *RevisionService) createRevisions(
if err != nil {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.Errorf("failed to get release and file from %q", revision.File))
}
+ if projectID != database.ProjectID {
+ return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("release %q not found", revision.Release))
+ }
release, err := s.store.GetRelease(ctx, &store.FindReleaseMessage{
ProjectID: &projectID,
ReleaseID: &releaseID,
@@ -220,7 +229,9 @@ func (s *RevisionService) createRevisions(
foundFile = true
fileSheet := common.FormatSheet(release.ProjectID, f.SheetSha256)
if fileSheet != revision.Sheet {
- return nil, connect.NewError(connect.CodeInvalidArgument, errors.Errorf("The sheet in file %q is %q which is different from revision.sheet %q", fileID, fileSheet, revision.Sheet))
+ // Do not echo fileSheet: it embeds the real hash and would
+ // turn this validation into a hash oracle.
+ return nil, connect.NewError(connect.CodeInvalidArgument, errors.Errorf("the sheet in file %q is different from revision.sheet %q", fileID, revision.Sheet))
}
break
}
@@ -235,8 +246,7 @@ func (s *RevisionService) createRevisions(
if err != nil {
return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to create revision"))
}
- converted := convertToRevision(parent, database.ProjectID, revisionM)
- createdRevisions = append(createdRevisions, converted)
+ createdRevisions = append(createdRevisions, convertToRevision(parent, revisionM))
}
return createdRevisions, nil
}
@@ -282,26 +292,35 @@ func formatDatabaseParent(instance *store.InstanceMessage, database *store.Datab
return common.FormatDatabase(database.InstanceID, database.DatabaseName)
}
-func convertToRevisions(parent string, projectID string, revisions []*store.RevisionMessage) []*v1pb.Revision {
+func convertToRevisions(parent string, revisions []*store.RevisionMessage) []*v1pb.Revision {
var rs []*v1pb.Revision
for _, revision := range revisions {
- r := convertToRevision(parent, projectID, revision)
+ r := convertToRevision(parent, revision)
rs = append(rs, r)
}
return rs
}
-func convertToRevision(parent string, projectID string, revision *store.RevisionMessage) *v1pb.Revision {
+func convertToRevision(parent string, revision *store.RevisionMessage) *v1pb.Revision {
taskRunName := revision.Payload.TaskRun
file := revision.Payload.File
if file != "" && revision.Payload.Release != "" {
file = common.FormatReleaseFile(revision.Payload.Release, file)
}
+ // The sheet is named under the authoring project stamped in the payload,
+ // which may differ from the database's current project after a transfer —
+ // never under the current project, where the name would 404. A revision
+ // with no stamp (pre-migration provenance that did not corroborate)
+ // carries no sheet name.
+ sheetName := ""
+ if projectID := revision.Payload.GetProject(); projectID != "" {
+ sheetName = common.FormatSheet(projectID, revision.Payload.SheetSha256)
+ }
r := &v1pb.Revision{
Name: fmt.Sprintf("%s/%s%s", parent, common.RevisionNamePrefix, revision.ResourceID),
Release: revision.Payload.Release,
CreateTime: timestamppb.New(revision.CreatedAt),
- Sheet: common.FormatSheet(projectID, revision.Payload.SheetSha256),
+ Sheet: sheetName,
SheetSha256: revision.Payload.SheetSha256,
Version: revision.Version,
File: file,
@@ -351,6 +370,11 @@ func convertRevision(revision *v1pb.Revision, database *store.DatabaseMessage, s
SheetSha256: sheetSha256,
TaskRun: revision.TaskRun,
Type: convertRevisionType(revision.Type),
+ // The authoring project, stamped by the server: validation above
+ // checked the sheet is readable by this project. History follows
+ // the database on transfer; this stamp is what keeps the
+ // statement's sheet name pointing at the project that ran it.
+ Project: database.ProjectID,
},
}
return r
diff --git a/backend/api/v1/rollout_service.go b/backend/api/v1/rollout_service.go
index 7488cb1d27..6781df4da8 100644
--- a/backend/api/v1/rollout_service.go
+++ b/backend/api/v1/rollout_service.go
@@ -1230,10 +1230,13 @@ func (s *RolloutService) PreviewTaskRunRollback(ctx context.Context, req *connec
if sheetSha256 == "" {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.Errorf("task %v has no sheet", task.ID))
}
- sheet, err := s.store.GetSheetFull(ctx, sheetSha256)
+ sheet, err := s.store.GetSheetForProject(ctx, projectID, sheetSha256, true)
if err != nil {
return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to get sheet statements"))
}
+ if sheet == nil {
+ return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("sheet not found for task %v", task.ID))
+ }
statements := sheet.Statement
var results []string
@@ -1276,7 +1279,7 @@ func GetPipelineCreate(ctx context.Context, s *store.Store, specs []*storepb.Pla
// Step 2 - convert all task creates.
var taskCreates []*store.TaskMessage
for _, spec := range transformedSpecs {
- tcs, err := getTaskCreatesFromSpec(ctx, s, spec)
+ tcs, err := getTaskCreatesFromSpec(ctx, s, spec, projectID)
if err != nil {
return nil, errors.Wrap(err, "failed to get task creates from spec")
}
diff --git a/backend/api/v1/rollout_service_task.go b/backend/api/v1/rollout_service_task.go
index e1265e6390..195f1e51a2 100644
--- a/backend/api/v1/rollout_service_task.go
+++ b/backend/api/v1/rollout_service_task.go
@@ -61,18 +61,18 @@ func applyDatabaseGroupSpecTransformations(ctx context.Context, s *store.Store,
return result, nil
}
-func getTaskCreatesFromSpec(ctx context.Context, s *store.Store, spec *storepb.PlanConfig_Spec) ([]*store.TaskMessage, error) {
+func getTaskCreatesFromSpec(ctx context.Context, s *store.Store, spec *storepb.PlanConfig_Spec, projectID string) ([]*store.TaskMessage, error) {
switch config := spec.Config.(type) {
case *storepb.PlanConfig_Spec_CreateDatabaseConfig:
- return getTaskCreatesFromCreateDatabaseConfig(ctx, s, spec, config.CreateDatabaseConfig)
+ return getTaskCreatesFromCreateDatabaseConfig(ctx, s, spec, config.CreateDatabaseConfig, projectID)
case *storepb.PlanConfig_Spec_ChangeDatabaseConfig:
- return getTaskCreatesFromChangeDatabaseConfig(ctx, s, spec, config.ChangeDatabaseConfig)
+ return getTaskCreatesFromChangeDatabaseConfig(ctx, s, spec, config.ChangeDatabaseConfig, projectID)
}
return nil, errors.Errorf("invalid spec config type %T", spec.Config)
}
-func getTaskCreatesFromCreateDatabaseConfig(ctx context.Context, s *store.Store, spec *storepb.PlanConfig_Spec, c *storepb.PlanConfig_CreateDatabaseConfig) ([]*store.TaskMessage, error) {
+func getTaskCreatesFromCreateDatabaseConfig(ctx context.Context, s *store.Store, spec *storepb.PlanConfig_Spec, c *storepb.PlanConfig_CreateDatabaseConfig, projectID string) ([]*store.TaskMessage, error) {
if c.Database == "" {
return nil, errors.Errorf("database name is required")
}
@@ -140,7 +140,7 @@ func getTaskCreatesFromCreateDatabaseConfig(ctx context.Context, s *store.Store,
if err != nil {
return nil, err
}
- sheets, err := s.CreateSheets(ctx, &store.SheetMessage{
+ sheets, err := s.CreateSheets(ctx, projectID, &store.SheetMessage{
Statement: statement,
})
if err != nil {
@@ -176,12 +176,33 @@ func getTaskCreatesFromChangeDatabaseConfig(
s *store.Store,
spec *storepb.PlanConfig_Spec,
c *storepb.PlanConfig_ChangeDatabaseConfig,
+ projectID string,
) ([]*store.TaskMessage, error) {
databases, err := getDatabaseMessagesByTargets(ctx, s, c.Targets)
if err != nil {
return nil, err
}
+ // Validate ghost directive at task creation time (parsed at execution
+ // time). c.SheetSha256 is loop-invariant: fetch it once, not once per
+ // target database.
+ if c.SheetSha256 != "" {
+ sheetContent, err := getSheetContentBySha256(ctx, s, projectID, c.SheetSha256)
+ if err != nil {
+ return nil, errors.Wrapf(err, "failed to get sheet content")
+ }
+
+ if ghost.IsGhostEnabled(sheetContent) {
+ ghostFlags, err := ghost.ParseGhostDirective(sheetContent)
+ if err != nil {
+ return nil, errors.Wrapf(err, "failed to parse ghost directive")
+ }
+ if _, err := ghost.GetUserFlags(ghostFlags); err != nil {
+ return nil, errors.Wrapf(err, "invalid ghost flags %q", ghostFlags)
+ }
+ }
+ }
+
var tasks []*store.TaskMessage
for _, database := range databases {
if database.EffectiveEnvironmentID == nil {
@@ -209,24 +230,6 @@ func getTaskCreatesFromChangeDatabaseConfig(
}
}
- // Validate ghost directive at task creation time (parsed at execution time)
- if c.SheetSha256 != "" {
- sheetContent, err := getSheetContentBySha256(ctx, s, c.SheetSha256)
- if err != nil {
- return nil, errors.Wrapf(err, "failed to get sheet content")
- }
-
- if ghost.IsGhostEnabled(sheetContent) {
- ghostFlags, err := ghost.ParseGhostDirective(sheetContent)
- if err != nil {
- return nil, errors.Wrapf(err, "failed to parse ghost directive")
- }
- if _, err := ghost.GetUserFlags(ghostFlags); err != nil {
- return nil, errors.Wrapf(err, "invalid ghost flags %q", ghostFlags)
- }
- }
- }
-
taskCreate := &store.TaskMessage{
InstanceID: database.InstanceID,
DatabaseName: &database.DatabaseName,
@@ -459,8 +462,8 @@ func getCreateDatabaseStatement(dbType storepb.Engine, c *storepb.PlanConfig_Cre
}
}
-func getSheetContentBySha256(ctx context.Context, s *store.Store, sha256 string) (string, error) {
- sheet, err := s.GetSheetFull(ctx, sha256)
+func getSheetContentBySha256(ctx context.Context, s *store.Store, projectID, sha256 string) (string, error) {
+ sheet, err := s.GetSheetForProject(ctx, projectID, sha256, true)
if err != nil {
return "", err
}
diff --git a/backend/api/v1/sheet_service.go b/backend/api/v1/sheet_service.go
index dca946d09b..2d1c5bd7e3 100644
--- a/backend/api/v1/sheet_service.go
+++ b/backend/api/v1/sheet_service.go
@@ -51,7 +51,7 @@ func (s *SheetService) CreateSheet(ctx context.Context, request *connect.Request
}
storeSheetCreate := convertToStoreSheetMessage(request.Msg.Sheet)
- sheets, err := s.store.CreateSheets(ctx, storeSheetCreate)
+ sheets, err := s.store.CreateSheets(ctx, project.ResourceID, storeSheetCreate)
if err != nil {
return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to create sheet"))
}
@@ -94,7 +94,7 @@ func (s *SheetService) BatchCreateSheets(ctx context.Context, request *connect.R
sheetCreates = append(sheetCreates, storeSheetCreate)
}
- sheets, err := s.store.CreateSheets(ctx, sheetCreates...)
+ sheets, err := s.store.CreateSheets(ctx, project.ResourceID, sheetCreates...)
if err != nil {
return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to create sheet"))
}
@@ -130,15 +130,9 @@ func (s *SheetService) GetSheet(ctx context.Context, request *connect.Request[v1
return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("project with resource id %q had deleted", projectResourceID))
}
- var sheet *store.SheetMessage
- var sheetErr error
- if request.Msg.Raw {
- sheet, sheetErr = s.store.GetSheetFull(ctx, sheetSha256)
- } else {
- sheet, sheetErr = s.store.GetSheetTruncated(ctx, sheetSha256)
- }
- if sheetErr != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(sheetErr, "failed to get sheet"))
+ sheet, err := s.store.GetSheetForProject(ctx, project.ResourceID, sheetSha256, request.Msg.Raw)
+ if err != nil {
+ return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to get sheet"))
}
if sheet == nil {
return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("cannot find the sheet"))
diff --git a/backend/api/v1/sheet_test.go b/backend/api/v1/sheet_test.go
new file mode 100644
index 0000000000..0eebcd9802
--- /dev/null
+++ b/backend/api/v1/sheet_test.go
@@ -0,0 +1,50 @@
+package v1
+
+import (
+ "go/ast"
+ "go/parser"
+ "go/token"
+ "os"
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+// TestSheetContentGetterConfinement asserts nothing under backend/api/v1
+// calls the unscoped sheet getter: user-facing reads go through the
+// project-scoped store accessors (GetSheetsForProject and friends), and
+// GetSheetFull exists for runners and components only. The scoped/unscoped
+// split is otherwise compiler-enforced — the raw batch getters and the ref
+// filter are unexported from the store.
+func TestSheetContentGetterConfinement(t *testing.T) {
+ forbidden := map[string]bool{
+ "GetSheetFull": true,
+ }
+ fset := token.NewFileSet()
+ entries, err := os.ReadDir(".")
+ require.NoError(t, err)
+ for _, entry := range entries {
+ name := entry.Name()
+ if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
+ continue
+ }
+ file, err := parser.ParseFile(fset, name, nil, 0)
+ require.NoError(t, err)
+ ast.Inspect(file, func(n ast.Node) bool {
+ call, ok := n.(*ast.CallExpr)
+ if !ok {
+ return true
+ }
+ sel, ok := call.Fun.(*ast.SelectorExpr)
+ if !ok {
+ return true
+ }
+ if forbidden[sel.Sel.Name] {
+ t.Errorf("%s: %s is the unscoped runner getter; user-facing reads must use the project-scoped store accessors",
+ fset.Position(call.Pos()), sel.Sel.Name)
+ }
+ return true
+ })
+ }
+}
diff --git a/backend/common/permission/permission.go b/backend/common/permission/permission.go
index 4009676e5b..4e42c0aa4a 100644
--- a/backend/common/permission/permission.go
+++ b/backend/common/permission/permission.go
@@ -123,7 +123,6 @@ const (
WorkspaceProfileSettingsSet Permission = "bb.settings.setWorkspaceProfile"
SheetsCreate Permission = "bb.sheets.create"
SheetsGet Permission = "bb.sheets.get"
- SheetsUpdate Permission = "bb.sheets.update"
SQLSelect Permission = "bb.sql.select"
SQLDdl Permission = "bb.sql.ddl"
SQLDml Permission = "bb.sql.dml"
diff --git a/backend/common/permission/permission.yaml b/backend/common/permission/permission.yaml
index 24930136c5..8aeba2cfa9 100644
--- a/backend/common/permission/permission.yaml
+++ b/backend/common/permission/permission.yaml
@@ -114,7 +114,6 @@ permissions:
- bb.settings.setWorkspaceProfile
- bb.sheets.create
- bb.sheets.get
- - bb.sheets.update
- bb.subscription.manage
- bb.sql.select
- bb.sql.ddl
diff --git a/backend/generated-go/store/revision.pb.go b/backend/generated-go/store/revision.pb.go
index ac3b36d1e0..aa058c62a3 100644
--- a/backend/generated-go/store/revision.pb.go
+++ b/backend/generated-go/store/revision.pb.go
@@ -37,7 +37,16 @@ type RevisionPayload struct {
// Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun}
TaskRun string `protobuf:"bytes,5,opt,name=task_run,json=taskRun,proto3" json:"task_run,omitempty"`
// The type of the revision.
- Type SchemaChangeType `protobuf:"varint,6,opt,name=type,proto3,enum=bytebase.store.SchemaChangeType" json:"type,omitempty"`
+ Type SchemaChangeType `protobuf:"varint,6,opt,name=type,proto3,enum=bytebase.store.SchemaChangeType" json:"type,omitempty"`
+ // The project that authored this revision's change — where the plan or
+ // release that produced it ran. Stamped by the server at creation from the
+ // database's then-current project; rows predating the field are backfilled
+ // from corroborated provenance (migration 3.22.5). Not a scope: revisions
+ // stay keyed by (instance, db_name) and follow the database across project
+ // transfers, while the statement's sheet stays readable under this project.
+ // Can be empty when no owner could be corroborated; such statements are
+ // unreadable and the revision carries no sheet name.
+ Project string `protobuf:"bytes,7,opt,name=project,proto3" json:"project,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
@@ -107,11 +116,18 @@ func (x *RevisionPayload) GetType() SchemaChangeType {
return SchemaChangeType_SCHEMA_CHANGE_TYPE_UNSPECIFIED
}
+func (x *RevisionPayload) GetProject() string {
+ if x != nil {
+ return x.Project
+ }
+ return ""
+}
+
var File_store_revision_proto protoreflect.FileDescriptor
const file_store_revision_proto_rawDesc = "" +
"\n" +
- "\x14store/revision.proto\x12\x0ebytebase.store\x1a\x19google/api/resource.proto\x1a\x12store/common.proto\"\xef\x01\n" +
+ "\x14store/revision.proto\x12\x0ebytebase.store\x1a\x19google/api/resource.proto\x1a\x12store/common.proto\"\x89\x02\n" +
"\x0fRevisionPayload\x123\n" +
"\arelease\x18\x01 \x01(\tB\x19\xfaA\x16\n" +
"\x14bytebase.com/ReleaseR\arelease\x12\x12\n" +
@@ -119,7 +135,8 @@ const file_store_revision_proto_rawDesc = "" +
"\fsheet_sha256\x18\x04 \x01(\tR\vsheetSha256\x124\n" +
"\btask_run\x18\x05 \x01(\tB\x19\xfaA\x16\n" +
"\x14bytebase.com/TaskRunR\ataskRun\x124\n" +
- "\x04type\x18\x06 \x01(\x0e2 .bytebase.store.SchemaChangeTypeR\x04typeJ\x04\b\x03\x10\x04B\x90\x01\n" +
+ "\x04type\x18\x06 \x01(\x0e2 .bytebase.store.SchemaChangeTypeR\x04type\x12\x18\n" +
+ "\aproject\x18\a \x01(\tR\aprojectJ\x04\b\x03\x10\x04B\x90\x01\n" +
"\x12com.bytebase.storeB\rRevisionProtoP\x01Z\x12generated-go/store\xa2\x02\x03BSX\xaa\x02\x0eBytebase.Store\xca\x02\x0eBytebase\\Store\xe2\x02\x1aBytebase\\Store\\GPBMetadata\xea\x02\x0fBytebase::Storeb\x06proto3"
var (
diff --git a/backend/generated-go/store/revision_equal.pb.go b/backend/generated-go/store/revision_equal.pb.go
index 233ad306ea..dbef754924 100644
--- a/backend/generated-go/store/revision_equal.pb.go
+++ b/backend/generated-go/store/revision_equal.pb.go
@@ -25,5 +25,8 @@ func (x *RevisionPayload) Equal(y *RevisionPayload) bool {
if x.Type != y.Type {
return false
}
+ if x.Project != y.Project {
+ return false
+ }
return true
}
diff --git a/backend/generated-go/v1/sheet_service.pb.go b/backend/generated-go/v1/sheet_service.pb.go
index 9b6781c39d..5f759b3190 100644
--- a/backend/generated-go/v1/sheet_service.pb.go
+++ b/backend/generated-go/v1/sheet_service.pb.go
@@ -320,10 +320,10 @@ const file_v1_sheet_service_proto_rawDesc = "" +
"\x04name\x18\x01 \x01(\tB\x06\xe0A\x02\xe0A\x05R\x04name\x12\x1d\n" +
"\acontent\x18\x02 \x01(\fB\x03\xe0A\x02R\acontent\x12&\n" +
"\fcontent_size\x18\x03 \x01(\x03B\x03\xe0A\x03R\vcontentSize::\xeaA7\n" +
- "\x12bytebase.com/Sheet\x12!projects/{project}/sheets/{sheet}2\xe0\x03\n" +
- "\fSheetService\x12\x98\x01\n" +
- "\vCreateSheet\x12\x1f.bytebase.v1.CreateSheetRequest\x1a\x12.bytebase.v1.Sheet\"T\xdaA\fparent,sheet\x8a\xea0\x10bb.sheets.create\x90\xea0\x01\x82\xd3\xe4\x93\x02':\x05sheet\"\x1e/v1/{parent=projects/*}/sheets\x12\xb1\x01\n" +
- "\x11BatchCreateSheets\x12%.bytebase.v1.BatchCreateSheetsRequest\x1a&.bytebase.v1.BatchCreateSheetsResponse\"M\x8a\xea0\x10bb.sheets.create\x90\xea0\x01\x82\xd3\xe4\x93\x02/:\x01*\"*/v1/{parent=projects/*}/sheets:batchCreate\x12\x80\x01\n" +
+ "\x12bytebase.com/Sheet\x12!projects/{project}/sheets/{sheet}2\xe8\x03\n" +
+ "\fSheetService\x12\x9c\x01\n" +
+ "\vCreateSheet\x12\x1f.bytebase.v1.CreateSheetRequest\x1a\x12.bytebase.v1.Sheet\"X\xdaA\fparent,sheet\x8a\xea0\x10bb.sheets.create\x90\xea0\x01\x98\xea0\x01\x82\xd3\xe4\x93\x02':\x05sheet\"\x1e/v1/{parent=projects/*}/sheets\x12\xb5\x01\n" +
+ "\x11BatchCreateSheets\x12%.bytebase.v1.BatchCreateSheetsRequest\x1a&.bytebase.v1.BatchCreateSheetsResponse\"Q\x8a\xea0\x10bb.sheets.create\x90\xea0\x01\x98\xea0\x01\x82\xd3\xe4\x93\x02/:\x01*\"*/v1/{parent=projects/*}/sheets:batchCreate\x12\x80\x01\n" +
"\bGetSheet\x12\x1c.bytebase.v1.GetSheetRequest\x1a\x12.bytebase.v1.Sheet\"B\xdaA\x04name\x8a\xea0\rbb.sheets.get\x90\xea0\x01\x82\xd3\xe4\x93\x02 \x12\x1e/v1/{name=projects/*/sheets/*}B\xa7\x01\n" +
"\x0fcom.bytebase.v1B\x11SheetServiceProtoP\x01Z4github.com/bytebase/bytebase/backend/generated-go/v1\xa2\x02\x03BXX\xaa\x02\vBytebase.V1\xca\x02\vBytebase\\V1\xe2\x02\x17Bytebase\\V1\\GPBMetadata\xea\x02\fBytebase::V1b\x06proto3"
diff --git a/backend/migrator/migration/3.22/0005##scope_sheet_blob.sql b/backend/migrator/migration/3.22/0005##scope_sheet_blob.sql
new file mode 100644
index 0000000000..2e5a547444
--- /dev/null
+++ b/backend/migrator/migration/3.22/0005##scope_sheet_blob.sql
@@ -0,0 +1,201 @@
+-- sheet_blob is content-addressed shared storage with no scope of its own, and
+-- nothing has ever deleted from it: project purge does not touch it and no
+-- foreign key points at it, so every surviving reference lives inside JSONB
+-- payloads (plan.config, task.payload, release.payload, plan_check_run.result,
+-- revision.payload), invisible to referential integrity. sheet_blob_ref makes
+-- "which projects may read this hash" an explicit stored fact: it restores the
+-- project scoping lost when the sheet table was dropped (#18552) and makes a
+-- correct GC possible later. See docs/design/sheet-blob-scoping.md.
+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)
+);
+
+-- For the zero-ref verification audit and a future GC, which start from a
+-- hash with no project in hand. Request-path queries always lead with
+-- project and use the primary key.
+CREATE INDEX idx_sheet_blob_ref_sha256 ON sheet_blob_ref(sha256);
+
+-- Backfill one ref per (project, hash) pair derivable from the four
+-- project-scoped reference sources. protojson camelCases keys:
+-- sheet_sha256 -> sheetSha256. The EXISTS guard skips references naming a
+-- hash with no blob so the foreign key stays satisfiable.
+--
+-- Known gap: a blob referenced by nothing (a sheet created but never attached
+-- to a plan or release) has no derivable project, gets no ref, and becomes
+-- unreadable. The alternative - leaving orphans globally readable -
+-- reproduces the cross-project read this table closes.
+-- The MATERIALIZED fence guarantees the hex-shape filter runs before any
+-- decode(), so a malformed stored value is skipped instead of aborting the
+-- migration. The jsonb_typeof guards do the same for the array expansions:
+-- jsonb_array_elements errors on a non-array, and COALESCE alone would pass
+-- a stored JSON null through, so anything that is not an array expands to
+-- nothing instead.
+WITH src AS MATERIALIZED (
+ SELECT project, sha
+ FROM (
+ SELECT pl.project AS project, spec->'changeDatabaseConfig'->>'sheetSha256' AS sha
+ FROM plan pl
+ CROSS JOIN LATERAL jsonb_array_elements(
+ CASE WHEN jsonb_typeof(pl.config->'specs') = 'array' THEN pl.config->'specs' ELSE '[]'::jsonb END) AS spec
+ UNION ALL
+ SELECT t.project, t.payload->>'sheetSha256'
+ FROM task t
+ UNION ALL
+ SELECT r.project, f->>'sheetSha256'
+ FROM release r
+ CROSS JOIN LATERAL jsonb_array_elements(
+ CASE WHEN jsonb_typeof(r.payload->'files') = 'array' THEN r.payload->'files' ELSE '[]'::jsonb END) AS f
+ UNION ALL
+ SELECT pcr.project, res->>'sheetSha256'
+ FROM plan_check_run pcr
+ CROSS JOIN LATERAL jsonb_array_elements(
+ CASE WHEN jsonb_typeof(pcr.result->'results') = 'array' THEN pcr.result->'results' ELSE '[]'::jsonb END) AS res
+ ) raw
+ WHERE raw.sha ~ '^[0-9a-fA-F]{64}$'
+)
+INSERT INTO sheet_blob_ref (project, sha256)
+SELECT DISTINCT src.project, decode(src.sha, 'hex')
+FROM src
+WHERE EXISTS (SELECT 1 FROM sheet_blob b WHERE b.sha256 = decode(src.sha, 'hex'))
+ON CONFLICT DO NOTHING;
+
+-- revision predates the payload.project stamp that new writers set at
+-- creation, and it must NOT be backfilled from db.project: that is the
+-- database's *current* project, so a database transferred before this
+-- migration would grant its destination access to SQL the source authored -
+-- an over-grant no audit could flag, because the ref row looks legitimate.
+--
+-- Derive the authoring project from the revision's own provenance instead
+-- (payload.release, else payload.taskRun), and only when the named row
+-- corroborates it: single-row identity, created no later than the revision,
+-- and actually referencing this revision's hash. (project, release_id) is not
+-- a declared unique key, so the release test requires exactly one matching
+-- row; the task-run test matches the (project, id) primary key plus the task
+-- ID in the name, and accepts the hash directly on the task or through the
+-- task's release's files under the same exactly-one/age/hash test. The
+-- temporal test defeats project-ID reuse after a purge; the hash test defeats
+-- laundered provenance.
+--
+-- Corroborated rows get payload.project stamped - the same stored fact new
+-- revisions carry - and a ref for that project. Revisions with absent or
+-- uncorroborated provenance stay unstamped and get no ref: their statements
+-- are unreadable and carry no sheet name until an operator grants access
+-- deliberately, guided by the audits in
+-- docs/design/sheet-blob-scoping.md#rollout.
+--
+-- The intermediate sets are session temp tables rather than CTEs, indexed and
+-- ANALYZEd before use: CTE materializations carry no statistics and no
+-- indexes, which at deployment scale sent the planner into nested loops over
+-- hundreds of thousands of rows (measured: minutes-to-hours as CTEs, seconds
+-- as temp tables). ON COMMIT DROP keeps them inside the migration
+-- transaction, so atomicity and retry-on-failure are unchanged.
+CREATE TEMP TABLE _sheet_scope_rev ON COMMIT DROP AS
+SELECT r.resource_id,
+ r.created_at,
+ r.payload->>'sheetSha256' AS sha,
+ (regexp_match(r.payload->>'release', 'projects/([^/]+)/'))[1] AS rel_project,
+ (regexp_match(r.payload->>'release', 'releases/([^/]+)'))[1] AS rel_id,
+ -- The digit bound keeps the bigint casts total: a malformed name
+ -- with a >18-digit run fails the match and leaves the row
+ -- uncorroborated instead of aborting the migration on overflow.
+ (regexp_match(r.payload->>'taskRun', 'projects/([^/]+)/'))[1] AS tr_project,
+ ((regexp_match(r.payload->>'taskRun', 'taskRuns/(\d{1,18})$'))[1])::bigint AS tr_id,
+ ((regexp_match(r.payload->>'taskRun', 'tasks/(\d{1,18})/'))[1])::bigint AS task_id
+FROM revision r
+WHERE r.payload->>'sheetSha256' ~ '^[0-9a-fA-F]{64}$';
+
+CREATE INDEX ON _sheet_scope_rev (rel_project, rel_id, sha);
+CREATE INDEX ON _sheet_scope_rev (tr_project, tr_id, task_id);
+ANALYZE _sheet_scope_rev;
+
+-- Files of releases whose (project, release_id) matches exactly one row.
+-- (project, release_id) is not a declared unique key, so provenance that
+-- does not identify a single release has not identified anything. Both
+-- corroboration branches test against this one statement of the rule:
+-- single-row identity, release no newer than the revision, file carrying
+-- the revision's hash.
+CREATE TEMP TABLE _sheet_scope_srf ON COMMIT DROP AS
+SELECT rel.project, rel.release_id, rel.created_at, f->>'sheetSha256' AS sha
+FROM release rel
+JOIN (
+ SELECT project, release_id
+ FROM release
+ GROUP BY project, release_id
+ HAVING count(*) = 1
+) single USING (project, release_id)
+CROSS JOIN LATERAL jsonb_array_elements(
+ CASE WHEN jsonb_typeof(rel.payload->'files') = 'array' THEN rel.payload->'files' ELSE '[]'::jsonb END) AS f;
+
+CREATE INDEX ON _sheet_scope_srf (project, release_id, sha);
+ANALYZE _sheet_scope_srf;
+
+-- Release branch first: it is the preferred provenance.
+CREATE TEMP TABLE _sheet_scope_corroborated ON COMMIT DROP AS
+SELECT DISTINCT rev.resource_id, rev.rel_project AS project, rev.sha
+FROM _sheet_scope_rev rev
+JOIN _sheet_scope_srf srf
+ ON srf.project = rev.rel_project
+ AND srf.release_id = rev.rel_id
+ AND srf.created_at <= rev.created_at
+ AND srf.sha = rev.sha;
+
+CREATE INDEX ON _sheet_scope_corroborated (resource_id);
+ANALYZE _sheet_scope_corroborated;
+
+-- Task-run branch for the rest. The statement's snapshot sees only the
+-- release-branch rows inserted above, so NOT EXISTS implements the
+-- release-over-task-run preference. task_run and task are probed by primary
+-- key; the LEFT JOIN can multiply rows (several files may carry the same
+-- hash), and DISTINCT collapses them - the projected columns are fixed per
+-- revision, so at most one corroborated row per revision survives.
+INSERT INTO _sheet_scope_corroborated
+SELECT DISTINCT rev.resource_id, rev.tr_project AS project, rev.sha
+FROM _sheet_scope_rev rev
+JOIN task_run tr
+ ON tr.project = rev.tr_project
+ AND tr.id = rev.tr_id
+ AND tr.task_id = rev.task_id
+ AND tr.created_at <= rev.created_at
+JOIN task t ON t.project = tr.project AND t.id = tr.task_id
+LEFT JOIN _sheet_scope_srf srf
+ ON srf.project = (regexp_match(t.payload->>'release', 'projects/([^/]+)/'))[1]
+ AND srf.release_id = (regexp_match(t.payload->>'release', 'releases/([^/]+)'))[1]
+ AND srf.created_at <= rev.created_at
+ AND srf.sha = rev.sha
+WHERE rev.tr_project IS NOT NULL AND rev.tr_id IS NOT NULL AND rev.task_id IS NOT NULL
+ AND NOT EXISTS (SELECT 1 FROM _sheet_scope_corroborated c WHERE c.resource_id = rev.resource_id)
+ AND (t.payload->>'sheetSha256' = rev.sha OR srf.project IS NOT NULL);
+
+ANALYZE _sheet_scope_corroborated;
+
+UPDATE revision r
+SET payload = r.payload || jsonb_build_object('project', c.project)
+FROM _sheet_scope_corroborated c
+WHERE r.resource_id = c.resource_id;
+
+-- Grant each stamped revision's authoring project read access to its hash.
+-- The MATERIALIZED fence keeps decode() behind the hex-shape filter. This
+-- reads payload.project back rather than reusing the corroborated set, so it
+-- also sees any pre-existing project key; the project EXISTS guard keeps a
+-- value naming no live project row from aborting the migration on the
+-- foreign key (corroborated stamps always pass it - they came from FK-backed
+-- release/task_run rows).
+WITH stamped AS MATERIALIZED (
+ SELECT r.payload->>'project' AS project, r.payload->>'sheetSha256' AS sha
+ FROM revision r
+ WHERE r.payload->>'project' IS NOT NULL
+ AND r.payload->>'sheetSha256' ~ '^[0-9a-fA-F]{64}$'
+)
+INSERT INTO sheet_blob_ref (project, sha256)
+SELECT DISTINCT stamped.project, decode(stamped.sha, 'hex')
+FROM stamped
+WHERE EXISTS (SELECT 1 FROM sheet_blob b WHERE b.sha256 = decode(stamped.sha, 'hex'))
+ AND EXISTS (SELECT 1 FROM project p WHERE p.resource_id = stamped.project)
+ON CONFLICT DO NOTHING;
+
+-- Post-upgrade verification and review queries for operators - the zero-ref
+-- count, the multi-project hash review, the source-level missing-ref audit,
+-- and the ambiguous-provenance revision list - are maintained in
+-- docs/design/sheet-blob-scoping.md#rollout.
diff --git a/backend/migrator/migration/LATEST.sql b/backend/migrator/migration/LATEST.sql
index 51ce6009e2..4b53ed01ea 100644
--- a/backend/migrator/migration/LATEST.sql
+++ b/backend/migrator/migration/LATEST.sql
@@ -234,11 +234,34 @@ CREATE TABLE project_webhook (
CREATE INDEX idx_project_webhook_project ON project_webhook(project);
+-- sheet_blob is content-addressed shared storage; nothing deletes from it and
+-- every reference lives inside JSONB payloads (plan.config, task.payload,
+-- release.payload, plan_check_run.result, revision.payload), invisible to
+-- referential integrity. A GC written as "delete blobs no FK points at" would
+-- empty the table; a correct GC must consult sheet_blob_ref and the JSONB
+-- references.
CREATE TABLE sheet_blob (
sha256 bytea NOT NULL PRIMARY KEY,
content text NOT NULL
);
+-- Records which projects may read a hash. Two projects that independently
+-- author identical SQL share one blob and hold one ref row each. Written by
+-- sheet creation, deleted by project purge, and enforced by the store's
+-- project-scoped sheet accessors. A database transfer carries no refs:
+-- change history follows
+-- the database, statement content stays with the authoring project
+-- (docs/design/sheet-history-on-database-transfer.md).
+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)
+);
+
+-- For the zero-ref audit and a future GC, which start from a hash with no
+-- project in hand. Request-path queries lead with project and use the PK.
+CREATE INDEX idx_sheet_blob_ref_sha256 ON sheet_blob_ref(sha256);
+
-- plan table stores the plan for a project
CREATE TABLE plan (
-- unique and auto-increase per project
diff --git a/backend/migrator/migrator_test.go b/backend/migrator/migrator_test.go
index 35f8673ec9..a26dd38998 100644
--- a/backend/migrator/migrator_test.go
+++ b/backend/migrator/migrator_test.go
@@ -2,6 +2,10 @@ package migrator
import (
"context"
+ "crypto/sha256"
+ "encoding/hex"
+ "fmt"
+ "strings"
"testing"
"time"
@@ -17,8 +21,8 @@ import (
func TestLatestVersion(t *testing.T) {
files, err := getSortedVersionedFiles()
require.NoError(t, err)
- require.Equal(t, semver.MustParse("3.22.4"), *files[len(files)-1].version)
- require.Equal(t, "migration/3.22/0004##drop_task_run_log_pkey.sql", files[len(files)-1].path)
+ require.Equal(t, semver.MustParse("3.22.5"), *files[len(files)-1].version)
+ require.Equal(t, "migration/3.22/0005##scope_sheet_blob.sql", files[len(files)-1].path)
}
func TestVersionUnique(t *testing.T) {
@@ -817,3 +821,361 @@ func TestMigration3_7_20_ScalarTaskUpdateTasks(t *testing.T) {
require.NoError(t, err)
assert.Contains(t, nullPayload, "null", "null row should be unchanged")
}
+
+// TestMigration3_22_5_ScopeSheetBlob verifies the sheet_blob_ref backfill.
+//
+// The four project-scoped sources (plan, task, release, plan_check_run) each
+// yield one (project, hash) ref; references naming a hash with no blob are
+// skipped; unreferenced blobs end with zero refs; and a hash claimed by more
+// than one project is recorded per project so the multi-project audit reports
+// it — detected, not silently merged.
+//
+// The revision branch derives the authoring project from corroborated
+// provenance (never db.project). A corroborating row is almost always itself
+// a source granting the same (project, hash), so the observable probe for
+// each corroboration rule is the one additive shape: task-run provenance
+// whose task routes its hash through a release in a DIFFERENT project. There
+// the revision branch grants (task-run project, hash), which no source scan
+// produces, so a rule failure is visible as that ref's absence.
+func TestMigration3_22_5_ScopeSheetBlob(t *testing.T) {
+ ctx := context.Background()
+ container := testcontainer.GetTestPgContainer(ctx, t)
+ t.Cleanup(func() { container.Close(ctx) })
+ db := container.GetDB()
+
+ _, err := db.ExecContext(ctx, `
+ CREATE TABLE project (resource_id TEXT PRIMARY KEY);
+ CREATE TABLE sheet_blob (sha256 BYTEA NOT NULL PRIMARY KEY, content TEXT NOT NULL);
+ CREATE TABLE plan (project TEXT NOT NULL, config JSONB NOT NULL DEFAULT '{}');
+ CREATE TABLE task (project TEXT NOT NULL, id BIGINT NOT NULL, payload JSONB NOT NULL DEFAULT '{}');
+ CREATE TABLE task_run (project TEXT NOT NULL, id BIGINT NOT NULL, task_id INTEGER NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now());
+ CREATE TABLE release (project TEXT NOT NULL, release_id TEXT NOT NULL DEFAULT '', created_at TIMESTAMPTZ NOT NULL DEFAULT now(), payload JSONB NOT NULL DEFAULT '{}');
+ CREATE TABLE plan_check_run (project TEXT NOT NULL, result JSONB NOT NULL DEFAULT '{}');
+ CREATE TABLE revision (resource_id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text, instance TEXT NOT NULL, db_name TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), payload JSONB NOT NULL DEFAULT '{}');
+ INSERT INTO project VALUES
+ ('p1'), ('p2'), ('p3'), ('p4'),
+ ('rel-ok'), ('tr-ok'), ('rel-old'), ('tr-late'), ('rel-mismatch'), ('tr-mismatch'),
+ ('rel-dup'), ('tr-dup'), ('rel-task'), ('rel-taskid'), ('tr-taskid'), ('tr-direct'),
+ ('rel-prefer'), ('rel-nest-prefer'), ('tr-prefer'),
+ ('rel-newer'), ('rel-nest-fb'), ('tr-fb');
+ `)
+ require.NoError(t, err)
+
+ sheetHex := func(content string) string {
+ h := sha256.Sum256([]byte(content))
+ return hex.EncodeToString(h[:])
+ }
+ blobs := map[string]string{}
+ for _, name := range []string{
+ "plan", "task", "release", "pcr", "shared", "orphan",
+ "rev-rel", "rev-nest", "rev-late", "rev-mismatch", "rev-other",
+ "rev-dup", "rev-taskid", "rev-direct", "rev-prefer", "rev-fb", "rev-ghost", "rev-bare",
+ "rev-overflow", "rev-stale-stamp", "rev-empty-stamp",
+ } {
+ content := "SELECT '" + name + "';"
+ blobs[name] = sheetHex(content)
+ _, err := db.ExecContext(ctx,
+ "INSERT INTO sheet_blob VALUES (decode($1, 'hex'), $2)", blobs[name], content)
+ require.NoError(t, err)
+ }
+ missingBlob := strings.Repeat("f", 64)
+
+ const (
+ older = "2026-01-01 00:00:00+00" // predates every revision
+ rev = "2026-02-01 00:00:00+00" // every revision's created_at
+ newer = "2026-03-01 00:00:00+00" // postdates every revision
+ )
+ taskRunName := func(project string, taskID, taskRunID int) string {
+ return fmt.Sprintf("projects/%s/plans/1/rollout/stages/prod/tasks/%d/taskRuns/%d", project, taskID, taskRunID)
+ }
+
+ type seed struct {
+ query string
+ args []any
+ }
+ seeds := []seed{
+ // The four project-scoped sources.
+ {"INSERT INTO plan (project, config) VALUES ('p1', $1::jsonb)",
+ []any{fmt.Sprintf(`{"specs":[{"changeDatabaseConfig":{"sheetSha256":%q}},{"createDatabaseConfig":{}}]}`, blobs["plan"])}},
+ // The same hash referenced from two projects: honest dedup or a
+ // laundered reference — indistinguishable, so both refs are
+ // backfilled and the multi-project audit reports the hash.
+ {"INSERT INTO plan (project, config) VALUES ('p1', $1::jsonb)",
+ []any{fmt.Sprintf(`{"specs":[{"changeDatabaseConfig":{"sheetSha256":%q}}]}`, blobs["shared"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('p2', 1, $1::jsonb)",
+ []any{fmt.Sprintf(`{"sheetSha256":%q}`, blobs["task"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('p2', 2, $1::jsonb)",
+ []any{fmt.Sprintf(`{"sheetSha256":%q}`, blobs["shared"])}},
+ // A reference naming a hash with no blob is skipped by the EXISTS
+ // guard, not a foreign-key abort.
+ {"INSERT INTO task (project, id, payload) VALUES ('p2', 3, $1::jsonb)",
+ []any{fmt.Sprintf(`{"sheetSha256":%q}`, missingBlob)}},
+ {"INSERT INTO task (project, id, payload) VALUES ('p2', 4, '{}')", nil},
+ {"INSERT INTO release (project, release_id, payload) VALUES ('p3', 'r1', $1::jsonb)",
+ []any{fmt.Sprintf(`{"files":[{"path":"a.sql","sheetSha256":%q},{"path":"no-sheet.sql"}]}`, blobs["release"])}},
+ {"INSERT INTO plan_check_run (project, result) VALUES ('p4', $1::jsonb)",
+ []any{fmt.Sprintf(`{"results":[{"sheetSha256":%q},{"title":"no sheet"}]}`, blobs["pcr"])}},
+
+ // Null and malformed shapes: every one must expand to nothing, not
+ // abort. JSON null in place of an array is the case COALESCE alone
+ // would pass through to jsonb_array_elements.
+ {"INSERT INTO plan (project, config) VALUES ('p1', '{}')", nil},
+ {`INSERT INTO plan (project, config) VALUES ('p1', '{"specs": null}')`, nil},
+ {`INSERT INTO plan (project, config) VALUES ('p1', '{"specs": []}')`, nil},
+ {`INSERT INTO plan (project, config) VALUES ('p1', '{"specs": ["garbage", null]}')`, nil},
+ {"INSERT INTO task (project, id, payload) VALUES ('p2', 5, 'null'::jsonb)", nil},
+ {`INSERT INTO release (project, release_id, payload) VALUES ('p3', 'r-null', '{"files": null}')`, nil},
+ {`INSERT INTO release (project, release_id, payload) VALUES ('p3', 'r-nullelem', '{"files": [null]}')`, nil},
+ {`INSERT INTO plan_check_run (project, result) VALUES ('p4', '{"results": null}')`, nil},
+
+ // Revision: release provenance corroborates (exactly one row, older,
+ // carries the hash) → (rel-ok, rev-rel). Redundant with the release
+ // source, so presence-only.
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-ok', 'r', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-rel"])}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"release":"projects/rel-ok/releases/r"}`, blobs["rev-rel"])}},
+
+ // Observable probe, all constraints satisfied: task-run provenance in
+ // tr-ok whose task routes the hash through a release in rel-task.
+ // Expect the additive (tr-ok, rev-nest) alongside the source-derived
+ // (rel-task, rev-nest).
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-task', 'nest', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-nest"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('tr-ok', 10, $1::jsonb)",
+ []any{`{"release":"projects/rel-task/releases/nest"}`}},
+ {"INSERT INTO task_run (project, id, task_id, created_at) VALUES ('tr-ok', 100, 10, $1)", []any{older}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"taskRun":%q}`, blobs["rev-nest"], taskRunName("tr-ok", 10, 100))}},
+
+ // Temporal violation: the task run postdates the revision (the ID-reuse
+ // shape after a purge). No (tr-late, rev-late).
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-old', 'nest', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-late"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('tr-late', 10, $1::jsonb)",
+ []any{`{"release":"projects/rel-old/releases/nest"}`}},
+ {"INSERT INTO task_run (project, id, task_id, created_at) VALUES ('tr-late', 100, 10, $1)", []any{newer}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"taskRun":%q}`, blobs["rev-late"], taskRunName("tr-late", 10, 100))}},
+
+ // Hash mismatch: the nested release carries a different hash than the
+ // revision claims (laundered provenance). No (tr-mismatch, rev-mismatch).
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-mismatch', 'nest', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-other"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('tr-mismatch', 10, $1::jsonb)",
+ []any{`{"release":"projects/rel-mismatch/releases/nest"}`}},
+ {"INSERT INTO task_run (project, id, task_id, created_at) VALUES ('tr-mismatch', 100, 10, $1)", []any{older}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"taskRun":%q}`, blobs["rev-mismatch"], taskRunName("tr-mismatch", 10, 100))}},
+
+ // (project, release_id) matching two rows: not a unique key, so
+ // exactly-one fails even though both rows carry the hash and predate
+ // the revision. No (tr-dup, rev-dup).
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-dup', 'nest', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-dup"])}},
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-dup', 'nest', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-dup"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('tr-dup', 10, $1::jsonb)",
+ []any{`{"release":"projects/rel-dup/releases/nest"}`}},
+ {"INSERT INTO task_run (project, id, task_id, created_at) VALUES ('tr-dup', 100, 10, $1)", []any{older}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"taskRun":%q}`, blobs["rev-dup"], taskRunName("tr-dup", 10, 100))}},
+
+ // Task-ID mismatch: the task run exists on (project, id) but belongs
+ // to a different task than the name claims. No (tr-taskid, rev-taskid).
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-taskid', 'nest', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-taskid"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('tr-taskid', 11, $1::jsonb)",
+ []any{`{"release":"projects/rel-taskid/releases/nest"}`}},
+ {"INSERT INTO task_run (project, id, task_id, created_at) VALUES ('tr-taskid', 100, 11, $1)", []any{older}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"taskRun":%q}`, blobs["rev-taskid"], taskRunName("tr-taskid", 10, 100))}},
+
+ // Direct task hash: corroborates through task.payload.sheetSha256.
+ // Redundant with the task source, so presence-only.
+ {"INSERT INTO task (project, id, payload) VALUES ('tr-direct', 10, $1::jsonb)",
+ []any{fmt.Sprintf(`{"sheetSha256":%q}`, blobs["rev-direct"])}},
+ {"INSERT INTO task_run (project, id, task_id, created_at) VALUES ('tr-direct', 100, 10, $1)", []any{older}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"taskRun":%q}`, blobs["rev-direct"], taskRunName("tr-direct", 10, 100))}},
+
+ // Preference: both release and task-run provenance corroborate. The
+ // release wins, so the task-run fallback's additive grant
+ // (tr-prefer, rev-prefer) must NOT appear.
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-prefer', 'r', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-prefer"])}},
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-nest-prefer', 'nest', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-prefer"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('tr-prefer', 10, $1::jsonb)",
+ []any{`{"release":"projects/rel-nest-prefer/releases/nest"}`}},
+ {"INSERT INTO task_run (project, id, task_id, created_at) VALUES ('tr-prefer', 100, 10, $1)", []any{older}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"release":"projects/rel-prefer/releases/r","taskRun":%q}`,
+ blobs["rev-prefer"], taskRunName("tr-prefer", 10, 100))}},
+
+ // Fallback: the release provenance fails on age (the release postdates
+ // the revision), so the corroborated task run supplies the grant —
+ // (tr-fb, rev-fb) must appear.
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-newer', 'r', $1, $2::jsonb)",
+ []any{newer, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-fb"])}},
+ {"INSERT INTO release (project, release_id, created_at, payload) VALUES ('rel-nest-fb', 'nest', $1, $2::jsonb)",
+ []any{older, fmt.Sprintf(`{"files":[{"sheetSha256":%q}]}`, blobs["rev-fb"])}},
+ {"INSERT INTO task (project, id, payload) VALUES ('tr-fb', 10, $1::jsonb)",
+ []any{`{"release":"projects/rel-nest-fb/releases/nest"}`}},
+ {"INSERT INTO task_run (project, id, task_id, created_at) VALUES ('tr-fb', 100, 10, $1)", []any{older}},
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"release":"projects/rel-newer/releases/r","taskRun":%q}`,
+ blobs["rev-fb"], taskRunName("tr-fb", 10, 100))}},
+
+ // Provenance naming rows that no longer exist (purged authoring
+ // project): no ref at all, the hash stays zero-ref.
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"release":"projects/ghost/releases/r","taskRun":%q}`,
+ blobs["rev-ghost"], taskRunName("ghost", 10, 100))}},
+
+ // No provenance at all: no ref, the hash stays zero-ref.
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q}`, blobs["rev-bare"])}},
+
+ // Abort hazards: neither row may fail the migration.
+ // A taskRun name whose IDs overflow bigint fails the bounded digit
+ // match and stays uncorroborated instead of erroring the cast.
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"taskRun":"projects/tr-ok/plans/1/rollout/stages/prod/tasks/99999999999999999999999/taskRuns/99999999999999999999999"}`,
+ blobs["rev-overflow"])}},
+ // A pre-existing payload.project naming no live project row is kept
+ // as-is but granted no ref: the project EXISTS guard skips it instead
+ // of aborting on the foreign key.
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"project":"stale-ghost"}`, blobs["rev-stale-stamp"])}},
+ // Same for the empty string, which survives the IS NOT NULL filter.
+ {"INSERT INTO revision (instance, db_name, created_at, payload) VALUES ('i', 'd', $1, $2::jsonb)",
+ []any{rev, fmt.Sprintf(`{"sheetSha256":%q,"project":""}`, blobs["rev-empty-stamp"])}},
+ }
+ for _, s := range seeds {
+ _, err := db.ExecContext(ctx, s.query, s.args...)
+ require.NoError(t, err, s.query)
+ }
+
+ statement, err := migrationFS.ReadFile("migration/3.22/0005##scope_sheet_blob.sql")
+ require.NoError(t, err)
+ _, err = db.ExecContext(ctx, string(statement))
+ require.NoError(t, err)
+
+ rows, err := db.QueryContext(ctx,
+ "SELECT project, encode(sha256, 'hex') FROM sheet_blob_ref ORDER BY project, sha256")
+ require.NoError(t, err)
+ defer rows.Close()
+ var got []string
+ for rows.Next() {
+ var project, sha string
+ require.NoError(t, rows.Scan(&project, &sha))
+ got = append(got, project+"|"+sha)
+ }
+ require.NoError(t, rows.Err())
+ require.ElementsMatch(t, []string{
+ // The four project-scoped sources.
+ "p1|" + blobs["plan"],
+ "p1|" + blobs["shared"],
+ "p2|" + blobs["task"],
+ "p2|" + blobs["shared"],
+ "p3|" + blobs["release"],
+ "p4|" + blobs["pcr"],
+ // Release rows seeded as corroboration targets are sources themselves.
+ "rel-ok|" + blobs["rev-rel"],
+ "rel-task|" + blobs["rev-nest"],
+ "rel-old|" + blobs["rev-late"],
+ "rel-mismatch|" + blobs["rev-other"],
+ "rel-dup|" + blobs["rev-dup"],
+ "rel-taskid|" + blobs["rev-taskid"],
+ "tr-direct|" + blobs["rev-direct"],
+ "rel-prefer|" + blobs["rev-prefer"],
+ "rel-nest-prefer|" + blobs["rev-prefer"],
+ "rel-newer|" + blobs["rev-fb"],
+ "rel-nest-fb|" + blobs["rev-fb"],
+ // The revision branch's observable grants: corroborated task-run
+ // provenance routing through another project's release, and the
+ // age-based fallback. Every negative scenario is covered by this
+ // list's exactness: tr-late, tr-mismatch, tr-dup, tr-taskid and
+ // tr-prefer hold no refs.
+ "tr-ok|" + blobs["rev-nest"],
+ "tr-fb|" + blobs["rev-fb"],
+ }, got)
+
+ // Corroboration also stamps payload.project — the stored fact new
+ // revision writers set at creation. Each scenario's revision is
+ // identified by its unique hash; an empty stamp means the provenance did
+ // not corroborate. rev-prefer pins the release-over-taskRun preference
+ // directly: both branches corroborate and the release's project wins.
+ for sha, want := range map[string]string{
+ blobs["rev-rel"]: "rel-ok",
+ blobs["rev-nest"]: "tr-ok",
+ blobs["rev-late"]: "",
+ blobs["rev-mismatch"]: "",
+ blobs["rev-dup"]: "",
+ blobs["rev-taskid"]: "",
+ blobs["rev-direct"]: "tr-direct",
+ blobs["rev-prefer"]: "rel-prefer",
+ blobs["rev-fb"]: "tr-fb",
+ blobs["rev-ghost"]: "",
+ blobs["rev-bare"]: "",
+ blobs["rev-overflow"]: "",
+ blobs["rev-stale-stamp"]: "stale-ghost",
+ blobs["rev-empty-stamp"]: "",
+ } {
+ var got string
+ require.NoError(t, db.QueryRowContext(ctx,
+ "SELECT COALESCE(payload->>'project', '') FROM revision WHERE payload->>'sheetSha256' = $1", sha).Scan(&got))
+ require.Equal(t, want, got, "stamped project for hash %s", sha)
+ }
+
+ // The zero-ref audit counts the never-referenced blob plus the revisions
+ // whose provenance was absent or uncorroborated with no other source.
+ var zeroRefBlobs int
+ require.NoError(t, db.QueryRowContext(ctx, `
+ SELECT count(*) FROM sheet_blob b
+ WHERE NOT EXISTS (SELECT 1 FROM sheet_blob_ref r WHERE r.sha256 = b.sha256)
+ `).Scan(&zeroRefBlobs))
+ require.Equal(t, 7, zeroRefBlobs, "orphan, rev-mismatch, rev-ghost, rev-bare, rev-overflow, rev-stale-stamp, and rev-empty-stamp have zero refs")
+
+ // The multi-project audit reports every hash claimed by more than one
+ // project, including the deliberately shared one.
+ auditRows, err := db.QueryContext(ctx, `
+ SELECT encode(sha256, 'hex')
+ FROM sheet_blob_ref
+ GROUP BY sha256
+ HAVING count(DISTINCT project) > 1
+ `)
+ require.NoError(t, err)
+ defer auditRows.Close()
+ multiProject := map[string]bool{}
+ for auditRows.Next() {
+ var sha string
+ require.NoError(t, auditRows.Scan(&sha))
+ multiProject[sha] = true
+ }
+ require.NoError(t, auditRows.Err())
+ require.True(t, multiProject[blobs["shared"]], "the cross-project reference must be reported, not blessed")
+
+ // The source-level missing-ref audit from the design doc: a plan that
+ // references a pre-existing foreign hash AFTER the backfill invokes no
+ // CreateSheets and writes no ref, so only this query can see it.
+ _, err = db.ExecContext(ctx, "INSERT INTO plan (project, config) VALUES ('p1', $1::jsonb)",
+ fmt.Sprintf(`{"specs":[{"changeDatabaseConfig":{"sheetSha256":%q}}]}`, blobs["pcr"]))
+ require.NoError(t, err)
+ var missingProject, missingSha string
+ require.NoError(t, db.QueryRowContext(ctx, `
+ SELECT DISTINCT pl.project, spec->'changeDatabaseConfig'->>'sheetSha256' AS sha
+ FROM plan pl
+ CROSS JOIN LATERAL jsonb_array_elements(
+ CASE WHEN jsonb_typeof(pl.config->'specs') = 'array' THEN pl.config->'specs' ELSE '[]'::jsonb END) AS spec
+ WHERE spec->'changeDatabaseConfig'->>'sheetSha256' ~ '^[0-9a-fA-F]{64}$'
+ AND NOT EXISTS (
+ SELECT 1 FROM sheet_blob_ref r
+ WHERE r.project = pl.project
+ AND r.sha256 = decode(spec->'changeDatabaseConfig'->>'sheetSha256', 'hex')
+ )
+ `).Scan(&missingProject, &missingSha))
+ require.Equal(t, "p1", missingProject)
+ require.Equal(t, blobs["pcr"], missingSha)
+}
diff --git a/backend/runner/taskrun/database_migrate_executor.go b/backend/runner/taskrun/database_migrate_executor.go
index f5864ba62c..f292529d8f 100644
--- a/backend/runner/taskrun/database_migrate_executor.go
+++ b/backend/runner/taskrun/database_migrate_executor.go
@@ -589,6 +589,8 @@ func (exec *DatabaseMigrateExecutor) runVersionedRelease(ctx context.Context, dr
SheetSha256: file.SheetSha256,
TaskRun: taskRunName,
Type: storepb.SchemaChangeType_VERSIONED,
+ // The authoring project: where this rollout ran.
+ Project: task.ProjectID,
},
}
diff --git a/backend/store/README.md b/backend/store/README.md
index 306660a169..5d703e0e84 100644
--- a/backend/store/README.md
+++ b/backend/store/README.md
@@ -27,9 +27,9 @@ writers that call it; it is not a repository-wide purge fence because other
writers bypass `nextProjectID`.
Database creation, database-sync, batch database updates, task-run creation,
-and Query History writers, together with direct instance archive and direct
-project/instance purge, additionally take the matching transaction-scoped purge
-fence before any row lock. This closes absent-descendant gaps; writers then
+sheet creation, and Query History writers, together with direct instance
+archive and direct project/instance purge, additionally take the matching
+transaction-scoped purge fence before any row lock. This closes absent-descendant gaps; writers then
retain the normal child-to-parent row-lock order. Database sync may continue for
an archived project while its row exists, but never through a soft-deleted
instance. Direct instance archive and restore fail while any targeting task run
@@ -47,7 +47,7 @@ query_history -> policy -> worksheet_organizer -> worksheet
-> issue_comment -> issue -> plan_webhook_delivery -> plan_check_run
-> task_run_log -> task_run -> task -> plan -> access_grant -> release
-> db_group -> changelog -> sync_history -> revision -> db_schema -> db
--> project_webhook -> service_account -> workload_identity -> instance -> project
+-> sheet_blob_ref -> project_webhook -> service_account -> workload_identity -> instance -> project
```
Update this list, `DeleteProject`, and `DeleteInstance` together. A transaction that needs another sibling branch must establish its position here before implementation. When one table is touched by multiple predicates, keep those mutations contiguous at that table's position. Keep transactions short and preserve this order whether locks are acquired explicitly or by `UPDATE` and `DELETE` statements.
diff --git a/backend/store/batch_update_database_purge_test.go b/backend/store/batch_update_database_purge_test.go
index 2b35f4fd4c..91c8b353d2 100644
--- a/backend/store/batch_update_database_purge_test.go
+++ b/backend/store/batch_update_database_purge_test.go
@@ -23,7 +23,7 @@ func batchMoveDatabaseIntoProjectA(fixture *projectDeletionLockOrderFixture) err
func requireProjectPurgeTerminalState(t *testing.T, fixture *projectDeletionLockOrderFixture) {
t.Helper()
- var projectCount, orphanCount, databaseCount int
+ var projectCount, orphanCount, databaseCount, sheetRefCount int
var project string
require.NoError(t, fixture.db.QueryRowContext(fixture.ctx,
"SELECT COUNT(*) FROM project WHERE resource_id = 'project-a'").Scan(&projectCount))
@@ -33,20 +33,27 @@ func requireProjectPurgeTerminalState(t *testing.T, fixture *projectDeletionLock
"SELECT COUNT(*) FROM db WHERE instance = 'instance-a' AND name = 'db-a'").Scan(&databaseCount))
require.NoError(t, fixture.db.QueryRowContext(fixture.ctx,
"SELECT project FROM db WHERE instance = 'instance-a' AND name = 'db-a'").Scan(&project))
+ require.NoError(t, fixture.db.QueryRowContext(fixture.ctx,
+ "SELECT COUNT(*) FROM sheet_blob_ref WHERE project = 'project-a'").Scan(&sheetRefCount))
require.Zero(t, projectCount, "project purge must remove the archived project")
require.Zero(t, orphanCount, "no database row may reference the purged project")
require.Equal(t, 1, databaseCount, "the workspace-instance database must survive")
require.Equal(t, "default", project, "the workspace-instance database must be reassigned to the default project")
+ require.Zero(t, sheetRefCount, "no sheet ref may reference the purged project")
}
func TestBatchUpdateDatabasesAndDeleteProjectSerialize(t *testing.T) {
// The batch moves a workspace-instance database into the archived project
// while that project is being purged. Without purge fencing the terminal
- // project deletion fails on db.project's foreign key.
+ // project deletion fails on db.project's foreign key. The archived project
+ // also owns a sheet ref, so the purge must clear sheet_blob_ref or fail on
+ // its foreign key.
const seedSQL = `
INSERT INTO instance (resource_id, workspace, project)
VALUES ('instance-a', 'default', NULL);
INSERT INTO db (instance, name, project) VALUES ('instance-a', 'db-a', 'default');
+ INSERT INTO sheet_blob (sha256, content) VALUES (sha256('SELECT transfer;'::bytea), 'SELECT transfer;');
+ INSERT INTO sheet_blob_ref (project, sha256) VALUES ('project-a', sha256('SELECT transfer;'::bytea));
`
purgeProjectA := func(fixture *projectDeletionLockOrderFixture) error {
return fixture.store.DeleteProject(fixture.ctx, "default", "project-a")
diff --git a/backend/store/id.go b/backend/store/id.go
index 4cb7fe4870..17bb457417 100644
--- a/backend/store/id.go
+++ b/backend/store/id.go
@@ -15,22 +15,34 @@ import (
// reserving IDs below 101 for seed/test data.
const idMinValue int64 = 101
-// nextProjectID returns the next per-project auto-increment ID for the given table.
-// Must be called within a transaction. Locks and validates the active project row to
-// serialize concurrent inserts with project deletion.
-// Callers must first lock existing child rows as described in backend/store/README.md.
-// Returns at least idMinValue (101) for new projects.
-func nextProjectID(ctx context.Context, tx *sql.Tx, table, projectID string) (int64, error) {
+// lockActiveProject locks the project row and requires it to be active,
+// serializing the caller with project deletion. Creation is rejected with
+// NotFound when the project is missing or deleted. This is the "requires an
+// active project" lifecycle policy from backend/store/README.md; call it
+// after locking any existing child rows.
+func lockActiveProject(ctx context.Context, tx *sql.Tx, projectID string) error {
var deleted bool
if err := tx.QueryRowContext(ctx,
"SELECT deleted FROM project WHERE resource_id = $1 FOR UPDATE", projectID).Scan(&deleted); err != nil {
if errors.Is(err, sql.ErrNoRows) {
- return 0, common.Errorf(common.NotFound, "project %s not found", projectID)
+ return common.Errorf(common.NotFound, "project %s not found", projectID)
}
- return 0, errors.Wrapf(err, "failed to lock project %s", projectID)
+ return errors.Wrapf(err, "failed to lock project %s", projectID)
}
if deleted {
- return 0, common.Errorf(common.NotFound, "project %s is deleted", projectID)
+ return common.Errorf(common.NotFound, "project %s is deleted", projectID)
+ }
+ return nil
+}
+
+// nextProjectID returns the next per-project auto-increment ID for the given table.
+// Must be called within a transaction. Locks and validates the active project row to
+// serialize concurrent inserts with project deletion.
+// Callers must first lock existing child rows as described in backend/store/README.md.
+// Returns at least idMinValue (101) for new projects.
+func nextProjectID(ctx context.Context, tx *sql.Tx, table, projectID string) (int64, error) {
+ if err := lockActiveProject(ctx, tx, projectID); err != nil {
+ return 0, err
}
var maxID int64
diff --git a/backend/store/predefined_roles.go b/backend/store/predefined_roles.go
index 665f01384d..80acfa1e19 100644
--- a/backend/store/predefined_roles.go
+++ b/backend/store/predefined_roles.go
@@ -135,7 +135,6 @@ var PredefinedRoles = []*RoleMessage{
permission.WorkspaceProfileSettingsSet,
permission.SheetsCreate,
permission.SheetsGet,
- permission.SheetsUpdate,
permission.TaskRunsCreate,
permission.TaskRunsList,
permission.GroupsCreate,
@@ -282,7 +281,6 @@ var PredefinedRoles = []*RoleMessage{
permission.WorkspaceProfileSettingsSet,
permission.SheetsCreate,
permission.SheetsGet,
- permission.SheetsUpdate,
permission.SQLAdmin,
permission.SQLDdl,
permission.SQLDml,
@@ -413,7 +411,6 @@ var PredefinedRoles = []*RoleMessage{
permission.RolloutsList,
permission.SheetsCreate,
permission.SheetsGet,
- permission.SheetsUpdate,
permission.SQLDdl,
permission.SQLDml,
permission.SQLExplain,
@@ -478,7 +475,6 @@ var PredefinedRoles = []*RoleMessage{
permission.RolloutsList,
permission.SheetsCreate,
permission.SheetsGet,
- permission.SheetsUpdate,
permission.TaskRunsList,
),
},
diff --git a/backend/store/project.go b/backend/store/project.go
index 2338191bf3..4b108f5c30 100644
--- a/backend/store/project.go
+++ b/backend/store/project.go
@@ -735,6 +735,18 @@ func (s *Store) DeleteProject(ctx context.Context, workspace string, resourceID
return errors.Wrapf(err, "failed to move workspace databases to default project for project %s", resourceID)
}
+ // Delete sheet refs owned by this project. Blobs stay: content-addressed
+ // rows may be shared with other projects, and unreferenced blobs are a
+ // future GC's concern (see the sheet_blob comment in LATEST.sql).
+ q = qb.Q().Space("DELETE FROM sheet_blob_ref WHERE project = ?", resourceID)
+ sql, args, err = q.ToSQL()
+ if err != nil {
+ return errors.Wrap(err, "failed to build sheet_blob_ref delete query")
+ }
+ if _, err := tx.ExecContext(ctx, sql, args...); err != nil {
+ return errors.Wrapf(err, "failed to delete sheet_blob_ref for project %s", resourceID)
+ }
+
// Delete project webhooks
q = qb.Q().Space("DELETE FROM project_webhook WHERE project = ?", resourceID)
sql, args, err = q.ToSQL()
diff --git a/backend/store/revision.go b/backend/store/revision.go
index 3dd4fd7dd3..c4a3ca9ea6 100644
--- a/backend/store/revision.go
+++ b/backend/store/revision.go
@@ -139,7 +139,7 @@ func (s *Store) GetRevision(ctx context.Context, resourceID, instanceID, databas
return nil, err
}
if len(revisions) == 0 {
- return nil, errors.Errorf("revision not found: %s", resourceID)
+ return nil, common.Errorf(common.NotFound, "revision not found: %s", resourceID)
}
if len(revisions) > 1 {
return nil, errors.Errorf("found multiple revisions for resource_id: %s", resourceID)
diff --git a/backend/store/sheet.go b/backend/store/sheet.go
index 8130962320..fa3d5a616e 100644
--- a/backend/store/sheet.go
+++ b/backend/store/sheet.go
@@ -5,6 +5,8 @@ import (
"crypto/sha256"
"encoding/hex"
"fmt"
+ "maps"
+ "slices"
"github.com/pkg/errors"
@@ -22,42 +24,139 @@ type SheetMessage struct {
Size int64
}
-// GetSheetTruncated gets a sheet by SHA256 hash with truncated statement (max 2MB).
-// Statement field will be truncated to MaxSheetSize (2MB).
-// Results are cached by SHA256 hex string.
-func (s *Store) GetSheetTruncated(ctx context.Context, sha256Hex string) (*SheetMessage, error) {
- sheet, err := s.getSheet(ctx, sha256Hex, false)
+// validSheetSha256Hexes filters to well-formed 32-byte hex hashes. Stored
+// payloads are not trusted to carry valid hex; a malformed value can never
+// match a blob, so callers treat it as absent rather than letting decode()
+// turn it into a SQL error.
+func validSheetSha256Hexes(sha256Hexes []string) []string {
+ valid := make([]string, 0, len(sha256Hexes))
+ for _, sha256Hex := range sha256Hexes {
+ if len(sha256Hex) != 64 {
+ continue
+ }
+ if _, err := hex.DecodeString(sha256Hex); err != nil {
+ continue
+ }
+ valid = append(valid, sha256Hex)
+ }
+ return valid
+}
+
+// GetSheetFull gets a sheet by SHA256 hash with the complete statement, with
+// no project scope. It serves the runners and components, which execute work
+// that was authorized when its plan or release was created; user-facing reads
+// go through the scoped accessors below.
+func (s *Store) GetSheetFull(ctx context.Context, sha256Hex string) (*SheetMessage, error) {
+ sheets, err := s.getSheetsFull(ctx, sha256Hex)
+ if err != nil {
+ return nil, err
+ }
+ return sheets[sha256Hex], nil
+}
+
+// GetSheetsForProject is the sheet gate: a project may access a sheet only
+// when it holds a sheet_blob_ref for its hash. It filters the requested
+// hashes through the project's refs and fetches content only for those that
+// survive; a hash absent from the result does not exist as far as the caller
+// is concerned (NotFound rather than PermissionDenied, so the response does
+// not confirm the hash exists in some other project).
+//
+// The ref check runs before any content read on purpose: the full-content
+// cache is keyed by hash alone and a cache hit issues no query, so a scope
+// predicate placed with the content fetch would be skipped. Do not fuse the
+// check and the fetch into one query, and do not reorder them. Both steps are
+// batched: one ref query plus one content query for the cache misses,
+// whatever the input size.
+func (s *Store) GetSheetsForProject(ctx context.Context, projectID string, sha256Hexes []string, raw bool) (map[string]*SheetMessage, error) {
+ allowed, err := s.filterSheetsForProject(ctx, projectID, common.Uniq(sha256Hexes))
if err != nil {
return nil, err
}
- if sheet == nil {
- return nil, nil
+ granted := slices.Collect(maps.Keys(allowed))
+ if len(granted) == 0 {
+ return map[string]*SheetMessage{}, nil
}
- return sheet, nil
+ if raw {
+ return s.getSheetsFull(ctx, granted...)
+ }
+ return s.getSheets(ctx, granted, false)
}
-// GetSheetFull gets a sheet by SHA256 hash with the complete statement.
-// Statement field contains the complete content regardless of size.
-// Results are cached by SHA256 hex string.
-func (s *Store) GetSheetFull(ctx context.Context, sha256Hex string) (*SheetMessage, error) {
- if v, ok := s.sheetFullCache.Get(sha256Hex); ok && s.enableCache {
- return v, nil
+// GetSheetForProject is the single-sheet form of GetSheetsForProject. A nil
+// result means the project may not read the hash (or no such blob exists).
+func (s *Store) GetSheetForProject(ctx context.Context, projectID, sha256Hex string, raw bool) (*SheetMessage, error) {
+ sheets, err := s.GetSheetsForProject(ctx, projectID, []string{sha256Hex}, raw)
+ if err != nil {
+ return nil, err
}
+ return sheets[sha256Hex], nil
+}
- sheet, err := s.getSheet(ctx, sha256Hex, true)
+// MissingSheetsForProject returns the hashes, in input order, for which the
+// project holds no ref — a ref implies its blob through the foreign key, and
+// a malformed hash matches nothing, so it comes back missing. An empty result
+// means every hash is readable. Run when a plan or revision is created, never
+// per use: sheets are never deleted, and refs are deleted only by project
+// purge, which deletes the referencing rows too.
+func (s *Store) MissingSheetsForProject(ctx context.Context, projectID string, sha256Hexes ...string) ([]string, error) {
+ sha256Hexes = common.Uniq(sha256Hexes)
+ allowed, err := s.filterSheetsForProject(ctx, projectID, sha256Hexes)
if err != nil {
return nil, err
}
- if sheet == nil {
- return nil, nil
+ var missing []string
+ for _, sha256Hex := range sha256Hexes {
+ if !allowed[sha256Hex] {
+ missing = append(missing, sha256Hex)
+ }
+ }
+ return missing, nil
+}
+
+// getSheetsFull gets sheets by SHA256 hashes with complete statements in one
+// query for all cache misses. The result is keyed by hex hash; an absent key
+// means no such blob. Content is a pure function of the hash, so the cache is
+// keyed by hex hash alone; scoping runs before content retrieval (a cache hit
+// issues no query).
+func (s *Store) getSheetsFull(ctx context.Context, sha256Hexes ...string) (map[string]*SheetMessage, error) {
+ sha256Hexes = common.Uniq(sha256Hexes)
+ result := make(map[string]*SheetMessage, len(sha256Hexes))
+ misses := sha256Hexes
+ if s.enableCache {
+ misses = nil
+ for _, sha256Hex := range sha256Hexes {
+ if v, ok := s.sheetFullCache.Get(sha256Hex); ok {
+ result[sha256Hex] = v
+ } else {
+ misses = append(misses, sha256Hex)
+ }
+ }
+ }
+ if len(misses) == 0 {
+ return result, nil
}
- s.sheetFullCache.Add(sha256Hex, sheet)
- return sheet, nil
+ fetched, err := s.getSheets(ctx, misses, true)
+ if err != nil {
+ return nil, err
+ }
+ for sha256Hex, sheet := range fetched {
+ result[sha256Hex] = sheet
+ if s.enableCache {
+ s.sheetFullCache.Add(sha256Hex, sheet)
+ }
+ }
+ return result, nil
}
-// getSheet is the internal helper for fetching a single sheet by SHA256.
-func (s *Store) getSheet(ctx context.Context, sha256Hex string, loadFull bool) (*SheetMessage, error) {
+// getSheets is the internal helper for fetching sheets by SHA256 in one query.
+func (s *Store) getSheets(ctx context.Context, sha256Hexes []string, loadFull bool) (map[string]*SheetMessage, error) {
+ result := map[string]*SheetMessage{}
+ sha256Hexes = validSheetSha256Hexes(sha256Hexes)
+ if len(sha256Hexes) == 0 {
+ return result, nil
+ }
+
statementField := fmt.Sprintf("LEFT(content, %d)", common.MaxSheetSize)
if loadFull {
statementField = "content"
@@ -65,10 +164,11 @@ func (s *Store) getSheet(ctx context.Context, sha256Hex string, loadFull bool) (
q := qb.Q().Space(fmt.Sprintf(`
SELECT
+ encode(sha256, 'hex'),
%s,
OCTET_LENGTH(content)
FROM sheet_blob
- WHERE sha256 = decode(?, 'hex')`, statementField), sha256Hex)
+ WHERE sha256 IN (SELECT decode(unnest(CAST(? AS TEXT[])), 'hex'))`, statementField), sha256Hexes)
query, args, err := q.ToSQL()
if err != nil {
@@ -81,37 +181,89 @@ func (s *Store) getSheet(ctx context.Context, sha256Hex string, loadFull bool) (
}
defer rows.Close()
- var sheet *SheetMessage
- if rows.Next() {
- sheet = &SheetMessage{
- Sha256: sha256Hex,
- }
+ for rows.Next() {
+ sheet := &SheetMessage{}
if err := rows.Scan(
+ &sheet.Sha256,
&sheet.Statement,
&sheet.Size,
); err != nil {
return nil, err
}
+ result[sheet.Sha256] = sheet
}
if err := rows.Err(); err != nil {
return nil, err
}
- if sheet == nil {
- return nil, nil
+ return result, nil
+}
+
+// filterSheetsForProject returns which of the given hashes carry a
+// sheet_blob_ref row for the project. This is the stored ACL fact behind the
+// scoped accessors; it reads no content.
+func (s *Store) filterSheetsForProject(ctx context.Context, projectID string, sha256Hexes []string) (map[string]bool, error) {
+ result := map[string]bool{}
+ sha256Hexes = validSheetSha256Hexes(sha256Hexes)
+ if len(sha256Hexes) == 0 {
+ return result, nil
}
- return sheet, nil
+ q := qb.Q().Space(`
+ SELECT encode(sha256, 'hex')
+ FROM sheet_blob_ref
+ WHERE project = ?
+ AND sha256 IN (SELECT decode(unnest(CAST(? AS TEXT[])), 'hex'))`,
+ projectID, sha256Hexes)
+
+ query, args, err := q.ToSQL()
+ if err != nil {
+ return nil, errors.Wrapf(err, "failed to build sql")
+ }
+
+ rows, err := s.GetDB().QueryContext(ctx, query, args...)
+ if err != nil {
+ return nil, err
+ }
+ defer rows.Close()
+
+ for rows.Next() {
+ var sha256Hex string
+ if err := rows.Scan(&sha256Hex); err != nil {
+ return nil, err
+ }
+ result[sha256Hex] = true
+ }
+
+ if err := rows.Err(); err != nil {
+ return nil, err
+ }
+
+ return result, nil
}
-// CreateSheets creates sheet blobs using content-addressed storage.
-// Each sheet is identified by the SHA256 hash of its statement.
-// Duplicate statements share the same blob (ON CONFLICT DO NOTHING).
-func (s *Store) CreateSheets(ctx context.Context, creates ...*SheetMessage) ([]*SheetMessage, error) {
+// CreateSheets creates sheet blobs using content-addressed storage and records
+// a sheet_blob_ref row granting the project read access to each hash.
+// Duplicate statements share the same blob (ON CONFLICT DO NOTHING); refs are
+// per project.
+//
+// Lifecycle policy: creating a sheet requires an active project. The
+// transaction takes the project purge fence before any row lock, then locks
+// the project row and rejects a missing or deleted project with NotFound,
+// serializing against project purge in both directions. Both inserts are
+// new-row-only; the foreign-key checks on project and sheet_blob are covered
+// by the fence and the project row lock.
+func (s *Store) CreateSheets(ctx context.Context, projectID string, creates ...*SheetMessage) ([]*SheetMessage, error) {
+ if projectID == "" {
+ return nil, errors.New("project is required to create sheets")
+ }
+ if len(creates) == 0 {
+ return creates, nil
+ }
+
var statements []string
var sha256s [][]byte
-
for _, c := range creates {
statements = append(statements, c.Statement)
h := sha256.Sum256([]byte(c.Statement))
@@ -120,6 +272,19 @@ func (s *Store) CreateSheets(ctx context.Context, creates ...*SheetMessage) ([]*
c.Size = int64(len(c.Statement))
}
+ tx, err := s.GetDB().BeginTx(ctx, nil)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to begin transaction")
+ }
+ defer tx.Rollback()
+
+ if err := acquireProjectPurgeLock(ctx, tx, projectID); err != nil {
+ return nil, errors.Wrapf(err, "failed to lock project purge fence for %s", projectID)
+ }
+ if err := lockActiveProject(ctx, tx, projectID); err != nil {
+ return nil, err
+ }
+
q := qb.Q().Space(`
INSERT INTO sheet_blob (
sha256,
@@ -129,43 +294,29 @@ func (s *Store) CreateSheets(ctx context.Context, creates ...*SheetMessage) ([]*
unnest(CAST(? AS TEXT[]))
ON CONFLICT DO NOTHING
`, sha256s, statements)
-
query, args, err := q.ToSQL()
if err != nil {
return nil, errors.Wrapf(err, "failed to build sql")
}
-
- if _, err := s.GetDB().ExecContext(ctx, query, args...); err != nil {
- return nil, errors.Wrapf(err, "failed to exec")
+ if _, err := tx.ExecContext(ctx, query, args...); err != nil {
+ return nil, errors.Wrapf(err, "failed to insert sheet blobs")
}
- return creates, nil
-}
-
-// HasSheets checks if all sheets exist by SHA256 hashes.
-func (s *Store) HasSheets(ctx context.Context, sha256Hexes ...string) (bool, error) {
- if len(sha256Hexes) == 0 {
- return true, nil
- }
-
- // Remove duplicates
- sha256Hexes = common.Uniq(sha256Hexes)
-
- q := qb.Q().Space(`
- SELECT COUNT(*)
- FROM sheet_blob
- WHERE sha256 IN (SELECT decode(unnest(CAST(? AS TEXT[])), 'hex'))`,
- sha256Hexes)
-
- query, args, err := q.ToSQL()
+ q = qb.Q().Space(`
+ INSERT INTO sheet_blob_ref (project, sha256)
+ SELECT ?, unnest(CAST(? AS BYTEA[]))
+ ON CONFLICT DO NOTHING
+ `, projectID, sha256s)
+ query, args, err = q.ToSQL()
if err != nil {
- return false, errors.Wrapf(err, "failed to build sql")
+ return nil, errors.Wrapf(err, "failed to build sql")
}
-
- var count int
- if err := s.GetDB().QueryRowContext(ctx, query, args...).Scan(&count); err != nil {
- return false, err
+ if _, err := tx.ExecContext(ctx, query, args...); err != nil {
+ return nil, errors.Wrapf(err, "failed to insert sheet blob refs")
}
- return count == len(sha256Hexes), nil
+ if err := tx.Commit(); err != nil {
+ return nil, errors.Wrap(err, "failed to commit transaction")
+ }
+ return creates, nil
}
diff --git a/backend/store/sheet_lock_order_test.go b/backend/store/sheet_lock_order_test.go
new file mode 100644
index 0000000000..23dd82c3c8
--- /dev/null
+++ b/backend/store/sheet_lock_order_test.go
@@ -0,0 +1,44 @@
+package store_test
+
+import (
+ "context"
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/common"
+ "github.com/bytebase/bytebase/backend/store"
+)
+
+func createSheetInProjectA(ctx context.Context, s *store.Store) error {
+ _, err := s.CreateSheets(ctx, "project-a", &store.SheetMessage{Statement: "SELECT 1;"})
+ return err
+}
+
+const sheetLockOrderSeedSQL = `
+ INSERT INTO sheet_blob (sha256, content) VALUES (sha256('SELECT seed;'::bytea), 'SELECT seed;');
+ INSERT INTO sheet_blob_ref (project, sha256) VALUES ('project-a', sha256('SELECT seed;'::bytea));
+`
+
+// Purge first: project deletion wedges inside its sheet_blob_ref delete while
+// CreateSheets queues behind the project purge fence. The create must end in
+// a clean NotFound once the purge wins — no deadlock, no FK failure — and the
+// purge itself must succeed against the seeded refs.
+func TestCreateSheetsDoesNotDeadlockWithProjectDeletion(t *testing.T) {
+ err := runWithConcurrentProjectDeletion(t, sheetLockOrderSeedSQL, "sheet_blob_ref", 9905, createSheetInProjectA)
+ require.Equal(t, common.NotFound, common.ErrorCode(err))
+ require.NotContains(t, strings.ToLower(err.Error()), "foreign key",
+ "the create must reject the purged project cleanly, not with an FK failure")
+}
+
+// Writer first: CreateSheets holds the purge fence and waits on the project
+// row; project deletion queues behind the fence. The create must reject the
+// soft-deleted project with NotFound, and the purge must then complete.
+func TestCreateSheetsRejectsDeletedProjectDuringProjectDeletion(t *testing.T) {
+ operationErr, deleteErr := runWithCreationBeforeProjectDeletion(t, sheetLockOrderSeedSQL, "sheet_blob_ref", createSheetInProjectA)
+ require.NoError(t, deleteErr)
+ require.Equal(t, common.NotFound, common.ErrorCode(operationErr))
+ require.NotContains(t, strings.ToLower(operationErr.Error()), "foreign key",
+ "the create must reject the deleted project cleanly, not with an FK failure")
+}
diff --git a/backend/tests/README.md b/backend/tests/README.md
index f5f135eda1..15fe30ecc9 100644
--- a/backend/tests/README.md
+++ b/backend/tests/README.md
@@ -22,3 +22,19 @@ test for a writer of this table:
Without them, a raw-row snapshot that only calls `assertProjectUnchanged`
produces false-positive coverage: a cross-project write to this composite-PK
table would go undetected.
+
+## sheet_blob_ref collision coverage
+
+`sheet_blob_ref` also has no public gRPC read API (sheets are content-addressed
+and nothing enumerates them), so the snapshot reads it directly from the
+metadata DB via `listSheetBlobRefs`. Unlike `plan_webhook_delivery`, refs are
+written synchronously on the create paths (CreateSheet, CreateRelease, task
+creation), so no stabilization wait is needed and `assertProjectUnchanged`
+compares the `SheetBlobRefs` field directly. `TestCollision_SheetWrite` is the
+dedicated writer test: identical content in two projects shares one blob while
+each project holds its own `(project, sha256)` ref row.
+
+Sheet scoping always enforces: a project reads a sheet only when it holds a
+`sheet_blob_ref` for its hash. Every legitimate flow in the suite therefore
+proves it holds the refs it needs, and the cross-project tests assert real
+denials.
diff --git a/backend/tests/collision_helper_test.go b/backend/tests/collision_helper_test.go
index 48c5a4dfcc..66f8c6ec18 100644
--- a/backend/tests/collision_helper_test.go
+++ b/backend/tests/collision_helper_test.go
@@ -541,13 +541,20 @@ type projectSnapshot struct {
IssueComments []*v1pb.IssueComment
Releases []*v1pb.Release
DatabaseGroups []*v1pb.DatabaseGroup
- // PlanWebhookDeliveries is the only snapshot field read directly from
- // the metadata DB — plan_webhook_delivery has no public gRPC read API.
+ // PlanWebhookDeliveries is read directly from the metadata DB —
+ // plan_webhook_delivery has no public gRPC read API.
// It is NOT compared in assertProjectUnchanged: delivery rows are
// claimed asynchronously after rollout completion, so only the dedicated
// webhook collision test compares them, after explicitly waiting for the
// row set to stabilize.
PlanWebhookDeliveries []*planWebhookDelivery
+ // SheetBlobRefs is also read directly from the metadata DB —
+ // sheet_blob_ref has no public gRPC read API (sheets are content-
+ // addressed; nothing enumerates them). Unlike webhook deliveries, refs
+ // are written synchronously on the create paths, so
+ // assertProjectUnchanged compares them directly. Each entry is a hex
+ // hash the project may read.
+ SheetBlobRefs []string
}
// planWebhookDelivery is one row of the plan_webhook_delivery table, which
@@ -590,6 +597,35 @@ func listPlanWebhookDeliveries(ctx context.Context, t *testing.T, ctl *controlle
return out
}
+// listSheetBlobRefs reads every sheet_blob_ref hash for the project directly
+// from the test metadata database, following the same raw-read allowance as
+// listPlanWebhookDeliveries.
+func listSheetBlobRefs(ctx context.Context, t *testing.T, ctl *controller, projectID string) []string {
+ t.Helper()
+ a := require.New(t)
+ db, err := sql.Open("pgx", ctl.profile.PgURL)
+ a.NoError(err, "open metadata DB")
+ defer db.Close()
+
+ rows, err := db.QueryContext(ctx, `
+ SELECT encode(sha256, 'hex')
+ FROM sheet_blob_ref
+ WHERE project = $1
+ ORDER BY sha256
+ `, projectID)
+ a.NoError(err, "query sheet_blob_ref for project %s", projectID)
+ defer rows.Close()
+
+ var out []string
+ for rows.Next() {
+ var sha256Hex string
+ a.NoError(rows.Scan(&sha256Hex))
+ out = append(out, sha256Hex)
+ }
+ a.NoError(rows.Err())
+ return out
+}
+
// snapshotProject captures every plan/issue/task_run/task_run_log/
// plan_check_run/issue_comment/release/database_group row visible to the
// public gRPC API for the given project, plus the project's raw
@@ -721,6 +757,7 @@ func snapshotProject(
Releases: releasesResp.Msg.Releases,
DatabaseGroups: groupsResp.Msg.DatabaseGroups,
PlanWebhookDeliveries: listPlanWebhookDeliveries(ctx, t, ctl, projectID),
+ SheetBlobRefs: listSheetBlobRefs(ctx, t, ctl, projectID),
}
}
@@ -803,6 +840,14 @@ func assertProjectUnchanged(
a.True(proto.Equal(b.DatabaseExpr, af.DatabaseExpr), "%s: database group %s expression changed", label, b.Name)
},
label, "db_group")
+
+ // sheet_blob_ref is keyed by composite (project, sha256) and written
+ // synchronously by the create paths; a delta here means a sheet write in
+ // one project leaked a ref into (or removed one from) another.
+ assertNoChange(t, before.SheetBlobRefs, after.SheetBlobRefs,
+ func(sha256Hex string) string { return sha256Hex },
+ func(_, _ string) {},
+ label, "sheet_blob_ref")
}
// assertNoChange compares two row slices keyed by name, fails if any
diff --git a/backend/tests/sheet_scope_test.go b/backend/tests/sheet_scope_test.go
new file mode 100644
index 0000000000..987e402172
--- /dev/null
+++ b/backend/tests/sheet_scope_test.go
@@ -0,0 +1,352 @@
+package tests
+
+import (
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "fmt"
+ "testing"
+ "time"
+
+ "connectrpc.com/connect"
+ "github.com/stretchr/testify/require"
+ "google.golang.org/protobuf/types/known/fieldmaskpb"
+
+ "github.com/bytebase/bytebase/backend/common"
+ v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
+)
+
+// TestSheetProjectScope is the regression test for the global-by-SHA256 sheet
+// read: a sheet created in project A must not resolve under project B's name,
+// and project B must not be able to mint a reference to A's hash.
+func TestSheetProjectScope(t *testing.T) {
+ t.Parallel()
+ a := require.New(t)
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+ defer cancel()
+ ctl := &controller{}
+ ctx, err := ctl.StartServerWithExternalPg(ctx)
+ a.NoError(err)
+ defer ctl.Close(ctx)
+
+ projectA := ctl.project
+ projectBResp, err := ctl.projectServiceClient.CreateProject(ctx, connect.NewRequest(&v1pb.CreateProjectRequest{
+ ProjectId: generateRandomString("sheet-scope-b"),
+ Project: &v1pb.Project{Title: "Sheet Scope B"},
+ }))
+ a.NoError(err)
+ projectB := projectBResp.Msg
+
+ content := []byte("SELECT 'sheet scope';")
+ sheetResp, err := ctl.sheetServiceClient.CreateSheet(ctx, connect.NewRequest(&v1pb.CreateSheetRequest{
+ Parent: projectA.Name,
+ Sheet: &v1pb.Sheet{Content: content},
+ }))
+ a.NoError(err)
+ _, sheetSha256, err := common.GetProjectResourceIDSheetSha256(sheetResp.Msg.Name)
+ a.NoError(err)
+
+ // Readable under the owning project — raw and truncated. The raw read
+ // warms the store's hash-keyed content cache.
+ for _, raw := range []bool{true, false} {
+ resp, err := ctl.sheetServiceClient.GetSheet(ctx, connect.NewRequest(&v1pb.GetSheetRequest{
+ Name: sheetResp.Msg.Name,
+ Raw: raw,
+ }))
+ a.NoError(err, "GetSheet raw=%v under the owning project", raw)
+ a.Equal(content, resp.Msg.Content)
+ }
+
+ // The same hash under project B is NotFound. The raw variant is the
+ // cache-ordering case: the content cache was warmed above, so this fails
+ // if enforcement ever runs behind the cache read instead of before it.
+ foreignName := fmt.Sprintf("%s/sheets/%s", projectB.Name, sheetSha256)
+ for _, raw := range []bool{true, false} {
+ _, err := ctl.sheetServiceClient.GetSheet(ctx, connect.NewRequest(&v1pb.GetSheetRequest{
+ Name: foreignName,
+ Raw: raw,
+ }))
+ a.Equal(connect.CodeNotFound, connect.CodeOf(err), "GetSheet raw=%v under a foreign project", raw)
+ }
+
+ // Project B cannot mint a reference to A's hash: a release file naming
+ // the foreign sheet is rejected as not found.
+ crossRelease := &v1pb.Release{
+ Type: v1pb.Release_VERSIONED,
+ Files: []*v1pb.Release_File{{
+ Path: "V0001__cross.sql",
+ Version: "1",
+ Sheet: foreignName,
+ }},
+ }
+ _, err = ctl.releaseServiceClient.CreateRelease(ctx, connect.NewRequest(&v1pb.CreateReleaseRequest{
+ Parent: projectB.Name,
+ Release: crossRelease,
+ }))
+ a.Error(err, "a release in project B must not reference project A's sheet")
+ a.Equal(connect.CodeNotFound, connect.CodeOf(err))
+
+ // The owning project can make the same reference.
+ _, err = ctl.releaseServiceClient.CreateRelease(ctx, connect.NewRequest(&v1pb.CreateReleaseRequest{
+ Parent: projectA.Name,
+ Release: &v1pb.Release{
+ Type: v1pb.Release_VERSIONED,
+ Files: []*v1pb.Release_File{{
+ Path: "V0001__own.sql",
+ Version: "1",
+ Sheet: sheetResp.Msg.Name,
+ }},
+ },
+ }))
+ a.NoError(err, "the owning project must still reference its own sheet")
+
+ // CheckRelease loads statements from sheet references (CreateRelease does
+ // not — it stores only the hash). A sheet holding broken SQL proves the
+ // content actually flowed: only a hydrated statement can produce a syntax
+ // error advice.
+ instance := createPgInstance(ctx, t, ctl, "sheet-scope")
+ dbName := "sheet_scope_db"
+ err = ctl.createDatabase(ctx, projectA, instance, nil, dbName, "")
+ a.NoError(err)
+ brokenResp, err := ctl.sheetServiceClient.CreateSheet(ctx, connect.NewRequest(&v1pb.CreateSheetRequest{
+ Parent: projectA.Name,
+ Sheet: &v1pb.Sheet{Content: []byte("SELEC 'broken on purpose';")},
+ }))
+ a.NoError(err)
+ checkResp, err := ctl.releaseServiceClient.CheckRelease(ctx, connect.NewRequest(&v1pb.CheckReleaseRequest{
+ Parent: projectA.Name,
+ Release: &v1pb.Release{
+ Type: v1pb.Release_VERSIONED,
+ Files: []*v1pb.Release_File{{
+ Path: "V0002__broken.sql",
+ Version: "2",
+ Sheet: brokenResp.Msg.Name,
+ }},
+ },
+ Targets: []string{fmt.Sprintf("%s/databases/%s", instance.Name, dbName)},
+ }))
+ a.NoError(err)
+ foundSyntaxError := false
+ for _, result := range checkResp.Msg.Results {
+ for _, advice := range result.Advices {
+ if advice.Status == v1pb.Advice_ERROR {
+ foundSyntaxError = true
+ }
+ }
+ }
+ a.True(foundSyntaxError, "the check must run over the sheet's content, not an empty statement")
+}
+
+// TestSheetHistoryOnDatabaseTransfer pins the transfer decision in
+// docs/design/sheet-history-on-database-transfer.md: the revision list follows
+// the database, the statement text does not. After the move the revision is
+// listed under the destination project with its sheet named under the stamped
+// authoring project, and the destination project gains no read access of its
+// own.
+func TestSheetHistoryOnDatabaseTransfer(t *testing.T) {
+ t.Parallel()
+ a := require.New(t)
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+ defer cancel()
+ ctl := &controller{}
+ ctx, err := ctl.StartServerWithExternalPg(ctx)
+ a.NoError(err)
+ defer ctl.Close(ctx)
+
+ projectA := ctl.project
+ projectBResp, err := ctl.projectServiceClient.CreateProject(ctx, connect.NewRequest(&v1pb.CreateProjectRequest{
+ ProjectId: generateRandomString("sheet-mv-b"),
+ Project: &v1pb.Project{Title: "Sheet Transfer B", AllowSelfApproval: true},
+ }))
+ a.NoError(err)
+ projectB := projectBResp.Msg
+
+ instance := createPgInstance(ctx, t, ctl, "sheet-transfer")
+ dbName := "sheet_transfer_db"
+ err = ctl.createDatabase(ctx, projectA, instance, nil, dbName, "")
+ a.NoError(err)
+ databaseName := fmt.Sprintf("%s/databases/%s", instance.Name, dbName)
+
+ // Author a release in A; the file's sheet is created under A with a ref.
+ statement := []byte("CREATE TABLE moved (id int);")
+ created, sheetName, sheetSha256 := createReleaseRevision(ctx, t, ctl, projectA.Name, databaseName, statement)
+ a.Equal(sheetName, created.Sheet, "the sheet is named under the stamped authoring project")
+
+ // Before the transfer the hash does not resolve under project B.
+ foreignName := fmt.Sprintf("%s/sheets/%s", projectB.Name, sheetSha256)
+ _, err = ctl.sheetServiceClient.GetSheet(ctx, connect.NewRequest(&v1pb.GetSheetRequest{Name: foreignName}))
+ a.Equal(connect.CodeNotFound, connect.CodeOf(err))
+
+ // Move the database to project B.
+ _, err = ctl.databaseServiceClient.UpdateDatabase(ctx, connect.NewRequest(&v1pb.UpdateDatabaseRequest{
+ Database: &v1pb.Database{Name: databaseName, Project: projectB.Name},
+ UpdateMask: &fieldmaskpb.FieldMask{Paths: []string{"project"}},
+ }))
+ a.NoError(err)
+
+ // The revision list is complete under project B, with the sheet still
+ // named under project A — the resolved owner, not the database's current
+ // project.
+ listResp, err := ctl.revisionServiceClient.ListRevisions(ctx, connect.NewRequest(&v1pb.ListRevisionsRequest{
+ Parent: databaseName,
+ }))
+ a.NoError(err)
+ a.Len(listResp.Msg.Revisions, 1, "the history list follows the database")
+ moved := listResp.Msg.Revisions[0]
+ a.Equal(sheetName, moved.Sheet, "the sheet is named under the authoring project, not the database's current project")
+ a.Equal(sheetSha256, moved.SheetSha256)
+
+ // A caller with rights on A reads the statement through the owner's name;
+ // the transfer granted project B no read access of its own.
+ resp, err := ctl.sheetServiceClient.GetSheet(ctx, connect.NewRequest(&v1pb.GetSheetRequest{Name: sheetName, Raw: true}))
+ a.NoError(err)
+ a.Equal(statement, resp.Msg.Content)
+ _, err = ctl.sheetServiceClient.GetSheet(ctx, connect.NewRequest(&v1pb.GetSheetRequest{Name: foreignName}))
+ a.Equal(connect.CodeNotFound, connect.CodeOf(err), "a transfer must not grant the destination read access")
+}
+
+// createReleaseRevision authors a one-file release in the project and records
+// it on the database's history as a revision with release provenance. It
+// returns the created revision, the sheet's resource name under the authoring
+// project, and the hash.
+func createReleaseRevision(ctx context.Context, t *testing.T, ctl *controller, projectName, databaseName string, statement []byte) (*v1pb.Revision, string, string) {
+ t.Helper()
+ a := require.New(t)
+
+ releaseResp, err := ctl.releaseServiceClient.CreateRelease(ctx, connect.NewRequest(&v1pb.CreateReleaseRequest{
+ Parent: projectName,
+ Release: &v1pb.Release{
+ Type: v1pb.Release_VERSIONED,
+ Files: []*v1pb.Release_File{{
+ Path: "V0001__history.sql",
+ Version: "1",
+ Statement: statement,
+ }},
+ },
+ }))
+ a.NoError(err)
+ file := releaseResp.Msg.Files[0]
+
+ revResp, err := ctl.revisionServiceClient.BatchCreateRevisions(ctx, connect.NewRequest(&v1pb.BatchCreateRevisionsRequest{
+ Parent: databaseName,
+ Requests: []*v1pb.CreateRevisionRequest{{
+ Parent: databaseName,
+ Revision: &v1pb.Revision{
+ Sheet: file.Sheet,
+ Version: file.Version,
+ Type: v1pb.Revision_VERSIONED,
+ Release: releaseResp.Msg.Name,
+ File: common.FormatReleaseFile(releaseResp.Msg.Name, file.Path),
+ },
+ }},
+ }))
+ a.NoError(err)
+ a.Len(revResp.Msg.Revisions, 1)
+ return revResp.Msg.Revisions[0], file.Sheet, file.SheetSha256
+}
+
+// TestSheetHistoryAfterOwnerPurge covers the path most likely to regress:
+// project purge reassigns workspace-instance databases to the default project
+// and hard-deletes the purged project's rows and sheet refs. The revision
+// list stays complete and the sheet stays named under the stamped authoring
+// project, but the name no longer resolves — the project and its refs are
+// gone, so the content is unreadable by anyone.
+func TestSheetHistoryAfterOwnerPurge(t *testing.T) {
+ t.Parallel()
+ a := require.New(t)
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+ defer cancel()
+ ctl := &controller{}
+ ctx, err := ctl.StartServerWithExternalPg(ctx)
+ a.NoError(err)
+ defer ctl.Close(ctx)
+
+ purgedResp, err := ctl.projectServiceClient.CreateProject(ctx, connect.NewRequest(&v1pb.CreateProjectRequest{
+ ProjectId: generateRandomString("sheet-purge"),
+ Project: &v1pb.Project{Title: "Sheet Purge", AllowSelfApproval: true},
+ }))
+ a.NoError(err)
+ purged := purgedResp.Msg
+
+ instance := createPgInstance(ctx, t, ctl, "sheet-purge")
+ dbName := "sheet_purge_db"
+ err = ctl.createDatabase(ctx, purged, instance, nil, dbName, "")
+ a.NoError(err)
+ databaseName := fmt.Sprintf("%s/databases/%s", instance.Name, dbName)
+
+ created, createdSheetName, sheetSha256 := createReleaseRevision(ctx, t, ctl, purged.Name, databaseName, []byte("CREATE TABLE gone (id int);"))
+ a.Equal(createdSheetName, created.Sheet)
+
+ // Project purge is an explicit archive-then-purge lifecycle.
+ _, err = ctl.projectServiceClient.DeleteProject(ctx,
+ connect.NewRequest(&v1pb.DeleteProjectRequest{Name: purged.Name}))
+ a.NoError(err)
+ _, err = ctl.projectServiceClient.DeleteProject(ctx,
+ connect.NewRequest(&v1pb.DeleteProjectRequest{Name: purged.Name, Purge: true}))
+ a.NoError(err)
+
+ // The workspace-instance database now belongs to the default project and
+ // its history is intact. The sheet keeps the stamped authoring project's
+ // name, which now dangles: reading through it is NotFound.
+ listResp, err := ctl.revisionServiceClient.ListRevisions(ctx, connect.NewRequest(&v1pb.ListRevisionsRequest{
+ Parent: databaseName,
+ }))
+ a.NoError(err)
+ a.Len(listResp.Msg.Revisions, 1, "the history list survives the purge")
+ rev := listResp.Msg.Revisions[0]
+ a.Equal(createdSheetName, rev.Sheet, "the sheet stays named under the stamped authoring project")
+ a.Equal(sheetSha256, rev.SheetSha256)
+ _, err = ctl.sheetServiceClient.GetSheet(ctx, connect.NewRequest(&v1pb.GetSheetRequest{Name: rev.Sheet}))
+ a.Equal(connect.CodeNotFound, connect.CodeOf(err), "the purged owner's name no longer resolves")
+
+ // The purged project's refs are gone; the content is unreadable by
+ // anyone, including the default project now holding the database.
+ database, err := ctl.databaseServiceClient.GetDatabase(ctx, connect.NewRequest(&v1pb.GetDatabaseRequest{Name: databaseName}))
+ a.NoError(err)
+ _, err = ctl.sheetServiceClient.GetSheet(ctx, connect.NewRequest(&v1pb.GetSheetRequest{
+ Name: fmt.Sprintf("%s/sheets/%s", database.Msg.Project, sheetSha256),
+ }))
+ a.Equal(connect.CodeNotFound, connect.CodeOf(err))
+}
+
+// TestCollision_SheetWrite verifies that sheet writes in project A —
+// including one whose content, and therefore sha256, is identical to a sheet
+// in project B — never disturb project B's sheet refs. The shared blob is the
+// collision: (project, sha256) rows differ only in the project column.
+func TestCollision_SheetWrite(t *testing.T) {
+ t.Parallel()
+ a := require.New(t)
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+ defer cancel()
+ ctl := &controller{}
+ ctx, err := ctl.StartServerWithExternalPg(ctx)
+ a.NoError(err)
+ defer ctl.Close(ctx)
+
+ fixture := setupCollidingProjects(ctx, t, ctl)
+
+ beforeB := snapshotProject(ctx, t, ctl, fixture.ProjectB)
+ a.NotEmpty(beforeB.SheetBlobRefs, "the fixture seeds a sheet per project")
+
+ // The fixture's sheets in A and B share the exact content "SELECT 1;",
+ // so re-creating it in A collides with B's ref on the shared blob.
+ // The second sheet is unique to A.
+ sharedContent := "SELECT 1;"
+ for _, content := range []string{sharedContent, "SELECT 'only A';"} {
+ _, err := ctl.sheetServiceClient.CreateSheet(ctx, connect.NewRequest(&v1pb.CreateSheetRequest{
+ Parent: fixture.ProjectA.Name,
+ Sheet: &v1pb.Sheet{Content: []byte(content)},
+ }))
+ a.NoError(err, "CreateSheet(%s)", content)
+ }
+
+ // Read A's shared-content sheet through the public API.
+ sharedHash := sha256.Sum256([]byte(sharedContent))
+ _, err = ctl.sheetServiceClient.GetSheet(ctx, connect.NewRequest(&v1pb.GetSheetRequest{
+ Name: fmt.Sprintf("%s/sheets/%s", fixture.ProjectA.Name, hex.EncodeToString(sharedHash[:])),
+ }))
+ a.NoError(err)
+
+ afterB := snapshotProject(ctx, t, ctl, fixture.ProjectB)
+ assertProjectUnchanged(t, beforeB, afterB, "project B after sheet writes in project A")
+}
diff --git a/docs/design/sheet-blob-scoping.md b/docs/design/sheet-blob-scoping.md
index f9deb81767..97ae98b5cb 100644
--- a/docs/design/sheet-blob-scoping.md
+++ b/docs/design/sheet-blob-scoping.md
@@ -5,7 +5,7 @@ Fixes T5 in `docs/design/v1-api-audit-2026-08.md`.
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.
+explicit stored fact, and the store's project-scoped sheet accessors enforce it.
## Background
@@ -19,9 +19,9 @@ This is a regression, not an oversight. Commit `bee2080737` (#18552, Dec 2025) d
project-scoped `sheet` table — which carried `project text NOT NULL REFERENCES
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`.
+changes needed)" as a non-goal, true before the cutover and false after. The assumption survived in
+the tree as stale comments justifying skipped checks in `release_service.go` until this work
+deleted them.
## Requirements
@@ -117,12 +117,13 @@ CREATE INDEX idx_sheet_blob_ref_sha256 ON sheet_blob_ref(sha256);
so project IDs are one global namespace across every workspace, and a project resolves to exactly
one workspace through `project.workspace`.
-The gate, `HasSheets` and the source-level missing-ref audit all query
+The scoped accessors, `MissingSheetsForProject` and the source-level missing-ref audit all query
`WHERE project = ? AND sha256 …`, which the project-leading primary key serves directly. The
secondary index exists for the one query that starts from a hash with no project in hand: the
-zero-ref verification in [Rollout](#rollout), which PostgreSQL can only satisfy by full-scanning a
-`(project, sha256)` btree. That is an operator query rather than a hot path, but it runs over the
-whole table and a future `sheet_blob` GC would need the same access shape.
+zero-ref verification in [Post-upgrade audits](#post-upgrade-audits), which PostgreSQL can only
+satisfy by full-scanning a `(project, sha256)` btree. That is an operator query rather than a hot
+path, but it runs over the whole table and a future `sheet_blob` GC would need the same access
+shape.
That query is a deliberate exception to the composite-PK predicate rule in `AGENTS.md`: it asks
which blobs have no ref at all, so there is no scope column to supply. It is an offline audit, not a
@@ -154,7 +155,7 @@ that never move, so their `project` column is the authoring project. `revision`
project column and inherits one through `db.project`, which is the database's *current* project. A
database transferred before this migration would backfill its revisions to the destination, granting
that project's members access to SQL the source authored — precisely the grant
-[the transfer decision](sheet-history-on-database-transfer.md) refuses, and invisible to shadow mode
+[the transfer decision](sheet-history-on-database-transfer.md) refuses, and invisible to any audit
because the ref row exists.
Derive the authoring project from the revision's own provenance instead. `RevisionPayload` carries
@@ -170,22 +171,29 @@ their content is unreadable until an operator grants it deliberately.
| Provenance | Action |
|---|---|
-| Corroborated — the named `release` or `task_run` row still exists under that project | Insert `(that project, sha)` |
-| Present but not corroborated | No ref |
-| Absent — both fields empty | No ref |
-
-**There is no `db.project` fallback because shadow mode cannot see an over-grant.** Falling back
-would be correct for every database that never moved, which is most of them, and wrong only for
-transferred ones — a tempting trade until you notice the asymmetry in how the two errors surface.
-Under-granting produces a shadow miss: a log line, during a full release in which content is still
-returned, with the requesting project right there in the log. Over-granting produces nothing at all,
-because the ref exists and the gate is satisfied. A guess that fails loudly and correctably beats a
-guess that fails silently and permanently.
-
-So the operational path for these rows is: no ref, shadow misses during the enforcement-deferred
-release, operator reviews the log, and tops up `(requesting project, sha)` for the ones they confirm.
-That is an informed grant rather than an inferred one, and the operator has context the migration
-does not — whether a database was transferred, and who should see its history.
+| Corroborated — the named `release` or `task_run` row still exists under that project | Stamp `payload.project`, insert `(that project, sha)` |
+| Present but not corroborated | No stamp, no ref |
+| Absent — both fields empty | No stamp, no ref |
+
+**Corroboration is a one-time event, and its result is stored.** The migration stamps each
+corroborated revision's `payload.project` — the same field new revision writers set at creation
+from the database's then-current project — and derives the ref from the stamp. Read time never
+re-corroborates: `convertToRevision` formats the sheet name from the stamp, and an empty stamp
+means no name. The stored fact is what keeps naming and access consistent after transfers; see
+[naming the owner](sheet-history-on-database-transfer.md#naming-the-owner).
+
+**There is no `db.project` fallback because an over-grant is invisible.** Falling back would be
+correct for every database that never moved, which is most of them, and wrong only for transferred
+ones — a tempting trade until you notice the asymmetry in how the two errors surface.
+Under-granting produces a NotFound and a row on the ambiguous-provenance audit, with the affected
+revision right there in the list. Over-granting produces nothing at all, because the ref exists and
+the gate is satisfied, and no audit could flag it — the ref row looks legitimate. A guess that
+fails loudly and correctably beats a guess that fails silently and permanently.
+
+So the operational path for these rows is: no ref, a row on the ambiguous-provenance audit, and an
+operator who tops up `(requesting project, sha)` for the ones they confirm. That is an informed
+grant rather than an inferred one, and the operator has context the migration does not — whether a
+database was transferred, and who should see its history.
**Corroboration is checked on the referenced row, not on the project.** `DeleteProject` hard-deletes
the `project` row and `CreateProject` accepts a caller-supplied `ProjectId`
@@ -235,13 +243,12 @@ Three constraints together close it:
establishes that the row has anything to do with the sheet being attributed to it.
**The hash match is what makes provenance mean something.** Without it, corroboration proves a task
-run exists and is old enough, and nothing more. `createRevisions` validates a `taskRun` thoroughly —
-project, plan, environment and task all have to line up, and `:173` even requires the task run to
-belong to the database's own project — but it never compares the task's sheet to `revision.Sheet`
-(`backend/api/v1/revision_service.go:167-192`), while `HasSheets` at `:158` is still deployment-wide.
-So a revision in project B can name a genuine B task run alongside an unrelated project A hash, and
-a corroboration that only checks identity would insert `(B, shaA)` — a laundered grant, permanent,
-and invisible to shadow mode because the ref exists.
+run exists and is old enough, and nothing more. Pre-fix `createRevisions` validated a `taskRun`'s
+identity — project, plan, environment and task all had to line up — but it never compared the
+task's sheet to `revision.Sheet`, and its sheet-existence check was deployment-wide. So a
+historical revision in project B can name a genuine B task run alongside an unrelated project A
+hash, and a corroboration that only checks identity would insert `(B, shaA)` — a laundered grant,
+permanent, and invisible to any audit because the ref exists.
Matching the hash costs one more join and closes it. `task.payload` is a oneof
(`proto/store/store/task.proto:27-36`), so the task branch has two shapes: `sheetSha256` equal to
@@ -249,30 +256,48 @@ the revision's hash, or `release` naming a release whose `payload.files[]` conta
branch is the single-hop form of the same test.
Apply it to the release branch too, even though `createRevisions` already enforces
-`fileSheet == revision.Sheet` there (`:222`). Uniformity is worth more than the saved join: it
-removes any need to reason about which creation-time validation happened to run, on a path where T6
-shows those validations can be steered.
+`fileSheet == revision.Sheet` there. Uniformity is worth more than the saved join: it removes any
+need to reason about which creation-time validation happened to run, on a path where T6 shows those
+validations can be steered.
The temporal test defeats ID reuse, the full chain narrows the window it must cover, and the hash
match defeats laundering. Residual risk after all three is limited to clock anomalies, and
uncorroborated rows fail closed to no ref — an unreadable statement rather than a wrong grant.
Their content then becomes unreadable, which is the intended outcome: the authoring project is gone,
-so there is nobody left to ask. The withheld-statement response reports the owner as unknown rather
-than echoing the parsed ID — an ID that failed corroboration cannot be verified against any
-workspace, so it is not safe to surface. See
+so there is nobody left to ask. An unstamped revision carries no sheet name rather than one that
+echoes the parsed ID — an ID that failed corroboration cannot be verified against any workspace, so
+it is not safe to surface. See
[naming the owner](sheet-history-on-database-transfer.md#naming-the-owner).
-A revision with no provenance at all is treated the same way: no ref, surfaced as a shadow miss, and
-granted only if an operator confirms it. Both populations appear together on the review list in
-[Rollout](#rollout).
+A revision with no provenance at all is treated the same way: no stamp, no ref, and a grant only if
+an operator confirms it. Both populations appear together on the ambiguous-provenance list in
+[Post-upgrade audits](#post-upgrade-audits).
Two tables that look like sources are not. `ChangelogPayload` carries only `task_run` and
`git_commit`, and the v1 `Changelog` message exposes no statement or sheet field. `issue_comment`
-has no sheet reference of any kind.
-
-Guard every derivation with `EXISTS (SELECT 1 FROM sheet_blob …)` so a payload naming a hash with no
-blob cannot violate the foreign key.
+has no sheet reference of any kind. Four *historical* locations also held hashes and are all dead:
+`task_run.sheet_sha256` (column added and dropped within 3.14), `plan_check_run.config` (column
+gone), and `changelog.payload.sheetSha256` / `issue_comment.planSpecUpdate.*SheetSha256` (proto
+fields removed; the JSONB keys linger in old rows, invisible under `DiscardUnknown` unmarshaling,
+with zero readers).
+
+**The migration must not abort on data, whatever is stored.** Every data-dependent hazard is
+guarded: hex-shape fences ahead of every `decode()`; `jsonb_typeof` checks ahead of every
+`jsonb_array_elements` (COALESCE alone passes a stored JSON `null` through); `EXISTS` against
+`sheet_blob` so a payload naming a hash with no blob cannot violate the foreign key; `EXISTS`
+against `project` on the stamped-refs insert so a pre-existing bogus `payload.project` cannot
+either; and bounded digit matches (`\d{1,18}`) so a malformed name cannot overflow the bigint
+casts. Each guard has a migration-test probe seeding the hostile shape. The migration runs as one
+transaction under the migrator's advisory lock, so any environmental failure rolls back completely
+and retries at next startup — fail-stop, never fail-corrupt.
+
+**Scale is addressed with indexed temp tables, not CTEs.** The corroboration intermediates are
+`CREATE TEMP TABLE … ON COMMIT DROP`, indexed and `ANALYZE`d before use. CTE materializations carry
+no statistics and no indexes, which sent the planner into nested loops — measured at ~15 minutes
+over a ~1M-row synthetic deployment as CTEs, 19.5 seconds total as temp tables, with every
+statement linear in table size. `ON COMMIT DROP` keeps the intermediates inside the migration
+transaction, so atomicity is unchanged.
**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
@@ -282,158 +307,128 @@ gap is accepted and noted in the migration comment.
**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, 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.
+`convertPlanSpecChangeDatabaseConfig` parses a caller-supplied `projects/{project}/sheets/{sha}`
+and stores only the hash, and the pre-fix existence check had no scope — so a historical plan in
+project B may reference a hash owned by project A, indistinguishable after the write from a
+legitimate one. Backfilling `(B, sha)` mints a permanent grant out of the access being closed, and
+no audit can prove it wrong because the ref row exists.
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).
+[Post-upgrade audits](#post-upgrade-audits).
### Store API
-`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.
+`sheet_blob_ref` is an ACL fact enforced by the store's scoped accessors; content retrieval and
+access control stay separate steps inside them. The runners are why the split is real rather than
+cosmetic: when `database_migrate_executor` reads a sheet it is executing work authorized when the
+plan or release was created, not making an access decision. Threading a project through it to
+satisfy a signature would be authorization theater, so the unscoped getter stays — exported,
+documented as runner-only, and confined out of `backend/api/v1` by a static test.
-**That exemption is conditional, and the condition is not free.** It holds only if the stored plan
-was authorized against the same rule the gate enforces. Plans created before enforcement were not:
-`HasSheets` was deployment-wide, so a plan in project B can reference a hash owned by project A, and
-`validateSpecs` runs only at `CreatePlan` (`backend/api/v1/plan_service.go:196`) and `UpdatePlan`
-(`:325`) — never again. Every path that turns stored plan state into runner work therefore
-revalidates; see [Revalidating stored plans](#revalidating-stored-plans).
-
-Every primitive is set-shaped (R5).
+Every primitive is set-shaped (R5), and everything else is unexported so the compiler enforces the
+split:
```go
-// 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)
+// Unscoped, runners and components only. A hash fully determines content.
+func (s *Store) GetSheetFull(ctx, sha256Hex string) (*SheetMessage, error)
-// Scoped: which of these hashes may this project read? One query.
-func (s *Store) FilterSheetsForProject(ctx, projectID string, sha256Hexes ...string) (map[string]bool, error)
+// Scoped reads: filter the hashes through the project's refs, then fetch
+// content only for the survivors. Two queries whatever the input size.
+func (s *Store) GetSheetsForProject(ctx, projectID string, sha256Hexes []string, raw bool) (map[string]*SheetMessage, error)
+func (s *Store) GetSheetForProject(ctx, projectID, sha256Hex string, raw bool) (*SheetMessage, error)
-// Scoped: validation predicate, not a content read.
-func (s *Store) HasSheets(ctx, projectID string, sha256Hexes ...string) (bool, error)
+// Scoped validation predicate, not a content read: the hashes, in input
+// order, for which the project holds no ref. Callers name the first missing
+// sheet in their error.
+func (s *Store) MissingSheetsForProject(ctx, projectID string, sha256Hexes ...string) ([]string, error)
-// Scoped: writes blobs and ref rows, both as set inserts, in one transaction.
+// Scoped creation: writes blobs and ref rows, both as set inserts, in one
+// transaction behind the project purge fence.
func (s *Store) CreateSheets(ctx, projectID string, creates ...*SheetMessage) ([]*SheetMessage, error)
-```
-`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.
+// Unexported internals: filterSheetsForProject (the ref query),
+// getSheetsFull (cache-aware batch fetch), getSheets (single content query).
+```
-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.
+A malformed hash is filtered before any SQL runs — it can never match a blob, so it is treated as
+absent rather than becoming a decode error. `CreateSheets` is a transaction so a blob cannot land
+without its ref, with the blob inserted first because the ref's foreign key requires it; both
+inserts are set-shaped `ON CONFLICT DO NOTHING`. Its four call sites all pass the owning project:
+the sheet service's two create RPCs, `CreateRelease` for statement-carrying files, and the
+create-database task path, which threads the plan's project down from `GetPipelineCreate`.
### Cache ordering
-`sheetFullCache` stays keyed by hex hash alone (`backend/store/store.go:51,82,110`, a 10-entry LRU).
+`sheetFullCache` stays keyed by hex hash alone (a 10-entry LRU in `backend/store/store.go`).
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 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.
+This is safe **only** because the ref check is a separate step that runs first, inside
+`GetSheetsForProject`, ahead of the cache-aware fetch. A cache hit returns before any query
+executes, so a scope predicate placed with the content fetch would be skipped. The check and the
+fetch must not be fused into one join, and must not be reordered; the store method carries that
+warning, and the cache-ordering integration test fails if it ever regresses.
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
+### The gate lives in the store
-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.
+Enforcement sits in the scoped store accessors, and the compiler does most of the confinement: the
+raw batch getters and the ref filter are unexported, so nothing outside the store can fetch content
+around the check. The one exported unscoped getter, `GetSheetFull`, exists for the runners, and a
+static AST test asserts nothing under `backend/api/v1/` calls it — the single boundary the compiler
+cannot enforce, since runners live in other packages.
-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.
+A hash the project may not read yields NotFound rather than PermissionDenied, so the response does
+not confirm the hash exists in another project.
-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.
-
-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.
-
-**Every v1 call site, enumerated.** `git grep -n 'GetSheetFull\|GetSheetTruncated\|HasSheets' -- backend/api/v1`
-returns exactly these seven on `main`; re-run it before implementing, since a route added since this
-was written would otherwise slip past the gate:
+**Every v1 consumer, enumerated.** All user-facing paths route through the scoped accessors:
| Call site | Path | Routes to |
|---|---|---|
-| `sheet_service.go:136,138` | `GetSheet` | gate |
-| `release_service.go:398` | `validateAndSanitizeReleaseFiles`, via `CreateRelease` and `CheckRelease` | gate |
-| `rollout_service.go:1233` | `PreviewTaskRunRollback` | gate |
-| `rollout_service_task.go:463` | `getSheetContentBySha256` | gate |
-| `release_service.go:144` | `CreateRelease` validation | scoped `HasSheets` |
-| `revision_service.go:158` | `BatchCreateRevisions` validation | scoped `HasSheets` |
-| `plan_service.go:746` | `validateSpecs` | scoped `HasSheets` |
+| `sheet_service.go` | `GetSheet` | `GetSheetForProject` |
+| `release_service_check.go` | `loadReleaseFileStatements`, via `CheckRelease` | `GetSheetsForProject` |
+| `rollout_service.go` | `PreviewTaskRunRollback` | `GetSheetForProject` |
+| `rollout_service_task.go` | `getSheetContentBySha256` (ghost directive) | `GetSheetForProject` |
+| `release_service.go` | `CreateRelease` validation | `MissingSheetsForProject` |
+| `revision_service.go` | `BatchCreateRevisions` validation | `MissingSheetsForProject` |
+| `plan_service.go` | `validateSpecs` | `MissingSheetsForProject` |
`PreviewTaskRunRollback` is the one most easily missed — it is a content read that does not look
like one, reached through a rollback-preview route rather than through anything named for sheets.
-The confinement test is what keeps this table from going stale.
-Three of these call sites also need reshaping for batching, which is a separate concern from routing. `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.
+Two batching notes that fell out of the rewiring: `validateAndSanitizeReleaseFiles` is now a pure
+function — `CreateRelease` persists only hashes, so its old full-content prefetch (potentially
+megabytes per file) is gone entirely, replaced by one ref check; only `CheckRelease`, which runs
+advisors over the SQL, hydrates statements, in one batched scoped read. The ghost-directive check
+fetches its loop-invariant hash once instead of once per target database.
-### Revalidating stored plans
+### Creation-time validation only
-The runner exemption assumes creation-time authorization. Historical data does not satisfy it, so
-the assumption has to be re-established at the point a user asks to act on a stored plan rather than
-assumed from the fact that the plan exists.
+References are validated when the referencing object is created, and never re-checked per use:
-Three API entry points materialize stored plan state into runner work, and none of them re-runs
-`validateSpecs`:
+- `CreateRelease` checks every referenced sheet against the project's refs before persisting, and
+ creates sheets (with refs) for inline statements. Releases are immutable — `UpdateRelease` is
+ `Unimplemented` — so the check cannot go stale.
+- `validateSpecs` runs at `CreatePlan` and `UpdatePlan` and checks the specs' direct hashes; for a
+ release reference it verifies the release exists in the same project, whose files were themselves
+ validated at `CreateRelease`.
+- `BatchCreateRevisions` checks the revision's hash against the database's project.
-| Entry point | Location | Produces |
-|---|---|---|
-| `CreateRollout` | `backend/api/v1/rollout_service.go:238` | tasks, via `GetPipelineCreate` from the stored specs |
-| `RunPlanChecks` | `backend/api/v1/plan_service.go:442` | plan check runs, which read the sheet at `backend/runner/plancheck/derive.go:49` |
-| `BatchRunTasks` | `backend/api/v1/rollout_service.go:746` | task runs — this is where the SQL actually executes |
-
-Without revalidation, a project-B user can take an old plan that references project A's hash and,
-after enforcement, still have A's SQL parsed and summarized by plan checks or executed against a
-database of their own — through the front door, with the gate untouched. Plan-check advices quote
-object names and statement fragments, so this is a disclosure path as well as an execution one.
-
-Each of the three revalidates the plan's sheets against the plan's project, and is shadow-gated on
-the same switch as everything else.
-
-**Revalidation must expand releases; reusing `CreatePlan`'s check is not enough.** `validateSpecs`
-collects only the direct `ChangeDatabaseConfig.Sheet` hashes into `HasSheets`, and for a release it
-verifies the project matches and the row exists — it never touches `release.Payload.Files[]`
-(`backend/api/v1/plan_service.go:755-774`). The release runners then read every file's hash by bare
-`GetSheetFull` (`backend/runner/taskrun/database_migrate_executor.go:543`, `:654`). So a release in
-project B whose files reference project A's hash — creatable today, since
-`validateAndSanitizeReleaseFiles` discards the project and `HasSheets` is deployment-wide — passes a
-`CreatePlan`-shaped check with nothing to test, and the runner still executes A's SQL.
-
-Revalidation therefore expands each referenced release and checks every `files[].sheetSha256`
-against the plan's project, not just the spec's direct sheet. `validateSpecs` gains the same
-expansion so the two agree: new releases cannot carry foreign hashes once `CreateRelease` uses
-scoped `HasSheets`, but plans may reference releases created before that. Shadow mode
-matters here more than elsewhere: these are *stored* objects, so a miss identifies a plan that will
-stop working at enforcement, and the operator needs that list while content is still being served.
-
-`BatchRunTasks` is the one to get right even though it never mentions sheets — it resolves a project
-and creates task runs from tasks whose payloads already carry the hash, so it is the last gate
-before execution and the easiest to overlook.
+What makes one-time checks durable is the deletion story: sheets are never deleted, and refs are
+deleted only by project purge, which deletes every referencing row — plan, task, release,
+plan_check_run — in the same transaction. There is no state in which a previously-valid stored
+reference silently loses its ref while the referencing object survives.
+
+Historical objects created before enforcement need no revalidation either, because the backfill
+resolves them: every stored `(project, hash)` reference in the four sources received a ref, so
+pre-existing plans and releases keep working, and any cross-project reference among them is a ref
+row the multi-project audit surfaces for review rather than a runtime failure. A stored reference
+that got no ref (a hash whose blob never existed) fails closed at the scoped reads on the rollout
+path.
### Project purge
@@ -491,27 +486,35 @@ 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.
+**Enforcement as a predicate inside the content getter.** Rejected, though store-level enforcement
+was ultimately adopted in a different shape. The rejected form puts the scope predicate in the
+content query itself, which the hash-keyed cache skips on a hit; the adopted form keeps the ref
+check a separate first step inside the scoped accessors, ahead of the cache, which preserves the
+compiler-checked-parameter advantage without the cache hazard. The runners are not forced to supply
+a project to satisfy a signature: the unscoped getter remains for them, confined out of the API
+layer by a static test rather than by threading authorization theater through executors.
-## Rollout
+## Post-upgrade audits
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 every scope check in shadow mode, not just the read gate.** The gate evaluates the check and
-logs a miss — project, hash, call site — but still returns content. `HasSheets` needs the same
-treatment and is easy to overlook, because it is a *validation* predicate rather than a read: it
-backs plan, release and revision validation and fails the request outright with "some sheets are not
-found". Left unshadowed, any pre-existing blob without a ref would turn into a spurious validation
-error on a write path — a worse failure than a withheld read, since it blocks work rather than
-hiding content. In shadow mode it falls back to the deployment-wide existence check and logs the
-miss. Run one full release; flip to enforcing only once logs are clean.
+**Enforcement ships on, with no shadow mode.** An earlier draft staged enforcement behind a
+shadow-logging release. That staging was dropped along with the per-use checks it instrumented:
+with creation-time-only validation there is no per-request check to shadow, and the risk it hedged
+is addressed directly instead. Completeness is proven rather than observed — the proto sweep pins
+exactly five live hash locations, all covered; the four historical locations are verified dead
+(columns dropped or fields removed, zero readers); and the migration's output is asserted exactly,
+scenario by scenario, in `TestMigration3_22_5_ScopeSheetBlob`. What remains after that proof is the
+designed-unreadable population — orphan drafts and uncorroborated revisions — which shadow logging
+would only have observed at request time anyway. The audits below identify it exhaustively up
+front, which strictly dominates a traffic-dependent log.
+
+The queries carry the same robustness guards as the migration — `jsonb_typeof` ahead of every array
+expansion, a hex-shape test ahead of every `decode()`, bounded digit matches — so they cannot error
+on a malformed stored payload.
**Verify the backfill first.** Blobs with zero refs should be a small, non-growing population:
@@ -533,68 +536,27 @@ since the backfill would make them permanent. Capture it at a known-good point:
public, including the rule that turns a reference into an ownership edge.
**Review revisions that produced no ref.** These are the rows whose statements are now unreadable —
-absent provenance, or provenance the backfill could not corroborate. They will appear as shadow
-misses during the deferred-enforcement release; this query is the same population identified up
-front, so a top-up can be prepared before the log accumulates.
-
-The test must repeat the corroboration check rather than asking whether the hash has any ref at all.
-The design expects hashes to be shared, so a revision whose own provenance failed may still have a
-ref from an unrelated project that authored identical SQL — and a ref-existence proxy would silently
-drop exactly the rows this list exists to surface.
+absent provenance, or provenance the backfill could not corroborate. The migration stamped every
+corroborated row's `payload.project`, so the population is simply the unstamped rows that carry a
+hash — no need to repeat the corroboration test, since its outcome is stored:
```sql
-SELECT r.instance, r.db_name,
+SELECT r.instance, r.db_name, r.resource_id,
(regexp_match(COALESCE(NULLIF(r.payload->>'release', ''),
r.payload->>'taskRun'), 'projects/([^/]+)/'))[1] AS named_project
FROM revision r
-WHERE r.payload->>'sheetSha256' IS NOT NULL
- -- the corroboration test from the backfill, repeated verbatim:
- -- single-row identity, age, and the hash the row actually references.
- -- (project, release_id) is not a declared unique key, so require exactly one match.
- AND NOT (
- (SELECT count(*) FROM release rel
- WHERE rel.project = (regexp_match(r.payload->>'release', 'projects/([^/]+)/'))[1]
- AND rel.release_id = (regexp_match(r.payload->>'release', 'releases/([^/]+)'))[1]) = 1
- AND EXISTS (
- SELECT 1 FROM release rel
- CROSS JOIN LATERAL jsonb_array_elements(COALESCE(rel.payload->'files', '[]'::jsonb)) AS f
- WHERE rel.project = (regexp_match(r.payload->>'release', 'projects/([^/]+)/'))[1]
- AND rel.release_id = (regexp_match(r.payload->>'release', 'releases/([^/]+)'))[1]
- AND rel.created_at <= r.created_at
- AND f->>'sheetSha256' = r.payload->>'sheetSha256'
- )
- )
- AND NOT EXISTS (
- SELECT 1 FROM task_run tr
- JOIN task t ON t.project = tr.project AND t.id = tr.task_id
- WHERE tr.project = (regexp_match(r.payload->>'taskRun', 'projects/([^/]+)/'))[1]
- AND tr.id = (regexp_match(r.payload->>'taskRun', 'taskRuns/(\d+)$'))[1]::bigint
- AND tr.task_id = (regexp_match(r.payload->>'taskRun', 'tasks/(\d+)/'))[1]::int
- AND tr.created_at <= r.created_at
- AND (
- -- task.payload.source is a oneof: a sheet hash, or a release naming one
- t.payload->>'sheetSha256' = r.payload->>'sheetSha256'
- OR (
- -- same exactly-one / age / hash test as the direct release branch
- (SELECT count(*) FROM release rel2
- WHERE rel2.project = (regexp_match(t.payload->>'release', 'projects/([^/]+)/'))[1]
- AND rel2.release_id = (regexp_match(t.payload->>'release', 'releases/([^/]+)'))[1]) = 1
- AND EXISTS (
- SELECT 1 FROM release rel2
- CROSS JOIN LATERAL jsonb_array_elements(COALESCE(rel2.payload->'files', '[]'::jsonb)) AS f2
- WHERE rel2.project = (regexp_match(t.payload->>'release', 'projects/([^/]+)/'))[1]
- AND rel2.release_id = (regexp_match(t.payload->>'release', 'releases/([^/]+)'))[1]
- AND rel2.created_at <= r.created_at
- AND f2->>'sheetSha256' = r.payload->>'sheetSha256'
- )
- )
- )
- );
+WHERE r.payload->>'sheetSha256' ~ '^[0-9a-fA-F]{64}$'
+ AND r.payload->>'project' IS NULL;
```
+`named_project` is the project the provenance *claims*, surfaced for the operator's investigation
+only — it failed corroboration, so it must not be granted (or shown to end users) on the query's
+say-so. To grant one after review: stamp `payload.project` and insert the ref in one transaction,
+which is exactly what the migration does for corroborated rows.
+
A large count means either widespread project purges, reused project IDs, or a population of
-revisions created without provenance — each worth understanding before enforcing, since all of them
-end in unreadable statements.
+revisions created without provenance — each worth understanding, since all of them end in
+unreadable statements.
## Transaction lock ordering
@@ -628,7 +590,7 @@ terminal outcomes in both lock-acquisition directions rather than merely the abs
## Independent fixes
-No schema needed; worth landing separately and first.
+No schema needed; landed with the change.
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
@@ -640,8 +602,10 @@ No schema needed; worth landing separately and 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.
+3. **Add audit annotations** to `proto/v1/v1/sheet_service.proto`'s create RPCs, which declare none
+ while 20 other v1 services do, leaving sheet authoring unlogged. `GetSheet` stays unaudited
+ deliberately: it is a high-volume content fetch, and the convention across the API audits
+ mutations plus the SQL query/export paths, not plain Gets.
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
@@ -650,93 +614,17 @@ No schema needed; worth landing separately and first.
obvious way — delete blobs no FK points at — would empty the table. `sheet_blob_ref` makes a
correct GC possible later.
-## Tests
-
-- **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.
-- **Stored-plan revalidation** — create a plan in project B referencing project A's hash while
- `HasSheets` is unscoped, then enforce, then assert each of `CreateRollout`, `RunPlanChecks` and
- `BatchRunTasks` refuses it. Run it twice: once with the hash on the spec directly, and once with
- the hash inside a referenced release's `files[]`, which is the shape a `CreatePlan`-style check
- does not look at. Without this the runner exemption is a bypass: the runners read by bare
- hash, so anything these three admit is executed or summarized 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.
-- **Missing-ref audit** — create a plan in project B referencing a pre-existing hash owned by A
- *after* the backfill has run, and assert the source-level audit reports it. This is the case the
- shadow log cannot see, because no `CreateSheets` runs and nothing revalidates the plan.
-- **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`** 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 independent fixes, T6 first.
-2. Create `sheet_blob_ref` and land the ref *writers* — the transactional `CreateSheets` and the
- purge delete. No scope check reads the table yet.
-3. Ship the backfill **and** the shadow-mode scope checks in the same release, so the migration runs
- at startup and the binary that then serves traffic is already instrumented. Run the verification
- queries.
-4. Before flipping: run the **missing-ref audit** below, review the shadow-miss log, and top up refs
- deliberately. Re-run the multi-project and ambiguous-provenance audits afterwards.
-5. Flip to enforcing, one release after step 3.
-
-**Writers must precede the backfill, or new sheets fall into the gap.** A one-shot backfill scans
-history; it cannot cover a sheet created after it runs. If the migration ships before `CreateSheets`
-writes refs, every sheet created in between lands in `sheet_blob` with no ref and appears in no
-historical source, so it becomes a zero-ref miss and a NotFound at enforcement. A rolling upgrade
-widens the same gap even when both ship together, since old replicas keep serving the old
-`CreateSheets` against the new schema until the rollout completes.
-
-The backfill is idempotent (`ON CONFLICT DO NOTHING`), so run it once the rollout has fully
-converged. Shadow-mode misses are the backstop: anything it missed shows up as a log line rather
-than a production NotFound.
-
-**Do not re-run the backfill blindly before enforcing.** By step 5 the writers have been live for a
-release, so every genuinely new sheet already has a ref from `CreateSheets`. The only rows a second
-backfill would add are references made to *pre-existing* blobs during the shadow window — which is
-exactly the unscoped-reference shape this design exists to close. Shadow-mode `HasSheets` falls back
-to the deployment-wide existence check, so a plan or release written during that window can
-reference a foreign hash and succeed with only a log line; a blind re-run would then mint
-`(that project, sha)`, clean the subsequent shadow logs, and carry an unreviewed grant into
-enforcement.
-
-Instead, close the window deliberately: review the shadow-miss log, grant the entries that are
-legitimate, and re-run the multi-project and ambiguous-provenance audits afterwards so anything
-added since the backfill is seen before the flip. This is the same posture taken for
-provenance-less revisions — an operator confirms, rather than a query inferring.
-
-**The shadow log is not sufficient on its own, because it only sees traffic.** A reference created
-while the check was not yet instrumented — or created once and never revalidated — produces no log
-line, so relying on shadow alone reproduces exactly the silent NotFound R4 forbids. Concretely: a
-plan or release in project B can reference a *pre-existing* hash owned by project A, which invokes
-no `CreateSheets` and therefore writes no ref, and which the multi-project audit cannot see because
-that audit reads `sheet_blob_ref` and no row was ever created.
-
-So audit the sources directly rather than inferring from refs. For each of the four project-scoped
-sources, find `(project, hash)` pairs with no matching ref:
+**Audit the sources directly rather than inferring from refs.** A reference to a *pre-existing*
+blob made through a stored payload invokes no `CreateSheets` and writes no ref, and the
+multi-project audit cannot see it because that audit reads `sheet_blob_ref`. For each of the four
+project-scoped sources, find `(project, hash)` pairs with no matching ref:
```sql
SELECT DISTINCT pl.project, spec->'changeDatabaseConfig'->>'sheetSha256' AS sha
FROM plan pl
-CROSS JOIN LATERAL jsonb_array_elements(COALESCE(pl.config->'specs', '[]'::jsonb)) AS spec
-WHERE spec->'changeDatabaseConfig'->>'sheetSha256' IS NOT NULL
+CROSS JOIN LATERAL jsonb_array_elements(
+ CASE WHEN jsonb_typeof(pl.config->'specs') = 'array' THEN pl.config->'specs' ELSE '[]'::jsonb END) AS spec
+WHERE spec->'changeDatabaseConfig'->>'sheetSha256' ~ '^[0-9a-fA-F]{64}$'
AND NOT EXISTS (
SELECT 1 FROM sheet_blob_ref r
WHERE r.project = pl.project
@@ -746,9 +634,69 @@ WHERE spec->'changeDatabaseConfig'->>'sheetSha256' IS NOT NULL
;
```
-Every row is something that will 404 at enforcement. It is exhaustive rather than traffic-dependent,
-so it strictly dominates the shadow log for these four sources, and it needs no assumption about
-when a reference was created or whether anything has revalidated it since.
+Every row is something that will 404 on a scoped read. Immediately after the upgrade this should
+return only references whose blob never existed — the backfill covers everything else — and it is
+exhaustive rather than traffic-dependent, needing no assumption about when a reference was created.
`revision` is deliberately excluded: uncorroborated revisions produce no ref *by design*, so they
would flood this query with expected rows. They have their own list above.
+
+## Tests
+
+Integration coverage is four tests in `backend/tests/sheet_scope_test.go`, one per independent
+decision, plus the migration matrix and the lock-order pair:
+
+- **Cross-project read and cache ordering** — `TestSheetProjectScope`: a sheet created in project A
+ is readable there (raw and truncated), NotFound under project B — with the raw foreign read
+ running *after* the owner's raw read warmed the hash-keyed content cache, so the test fails if
+ enforcement ever moves behind the cache. The same test pins the CreateRelease minting gate
+ (naming A's sheet from B is refused), the owning project's own reference succeeding, and
+ CheckRelease hydrating real content (a sheet holding broken SQL must surface a syntax-error
+ advice — only hydrated content can). Cross-*tenant* reads are subsumed mechanically: refs are
+ per-project and the scoped accessors consult nothing else, so there is no workspace-dependent
+ code path to test separately.
+- **Transfer semantics** — `TestSheetHistoryOnDatabaseTransfer`: the runtime half of the companion
+ doc's decision. History follows the database; the sheet stays named under the stamped authoring
+ project; the destination gains no read access.
+- **Purge semantics** — `TestSheetHistoryAfterOwnerPurge`: after the authoring project is purged,
+ the revision list survives, the dangling sheet name still renders, and reading it 404s — the
+ contract the frontend's withheld-statement panel is built on.
+- **Write non-interference** — `TestCollision_SheetWrite` per the composite-PK convention in
+ `AGENTS.md`, through the shared `setupCollidingProjects` fixture: a sheet write in one project
+ whose content (and therefore sha256) equals another project's leaves that project's refs
+ bit-identical.
+- **Backfill** — `TestMigration3_22_5_ScopeSheetBlob`: all five sources, the full corroboration
+ matrix (identity, exactly-one, age, hash, preference, fallback — every negative asserted by an
+ exact ref-set match), the stamp outcomes per scenario, the three audits, and a probe per
+ abort-hazard guard (dangling blob, ghost project, bigint overflow, stale stamp, JSON null and
+ malformed array shapes).
+- **Create versus purge** — the deterministic lock-order pair mandated by
+ `backend/store/README.md`: `CreateSheets` concurrent with a purge of its project ends in a
+ controlled NotFound, not a foreign-key error, in both lock-acquisition directions.
+- **Gate confinement** — a static AST test asserts nothing under `backend/api/v1/` calls
+ `GetSheetFull`; the rest of the split is compiler-enforced by unexported store internals.
+
+## Order
+
+Everything ships in one release: the independent fixes, the schema, the ref writers, the backfill,
+and enforcement. The migration creates the table, backfills, and stamps atomically at startup
+before the binary serves traffic, and every scoped code path is live from the first request. The
+staging that an earlier draft spread across three releases collapsed along with shadow mode — with
+creation-time-only validation and a proven-complete backfill there is no instrumentation period to
+stage.
+
+Two windows remain, both narrow and both documented:
+
+- **Rolling upgrade.** Old replicas keep serving the pre-fix writers while the first new replica
+ migrates. A sheet created by an old replica in that window lands in `sheet_blob` with no ref (an
+ orphan draft — readable again the moment anything references it through a new-binary create
+ path, since `CreateSheets` upserts), and a revision written by an old replica lands unstamped —
+ its content stays readable through the release/task-source refs, and it appears on the
+ ambiguous-provenance audit for a manual stamp. Neither corrupts anything; both self-identify.
+- **Re-running the backfill.** It is idempotent (`ON CONFLICT DO NOTHING`, stamp merge writes the
+ same value), but do not re-run it blindly to "top up": any reference created *after* enforcement
+ went live was validated by the creation-time gates, so a re-run adds nothing legitimate — and
+ the migration's version tracking prevents accidental re-execution anyway.
+
+Run the three audits after the upgrade; grant survivors deliberately, per
+[Post-upgrade audits](#post-upgrade-audits).
diff --git a/docs/design/sheet-history-on-database-transfer.md b/docs/design/sheet-history-on-database-transfer.md
index 8244645c4b..3305dcd8c1 100644
--- a/docs/design/sheet-history-on-database-transfer.md
+++ b/docs/design/sheet-history-on-database-transfer.md
@@ -101,10 +101,11 @@ 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 where that can be verified — rather than
- returning NotFound for the sheet.
-- The sheet *name* is formatted from that same resolved owner, not from the database's current
+- When a revision's sheet is not readable by the caller, the statement is withheld and the UI says
+ so explicitly — naming the owning project when the revision carries one — rather than rendering a
+ failed content load. The sheet read itself still returns NotFound, per the scoping doc's
+ no-existence-confirmation rule; the *revision* response is what carries the truthful owner.
+- The sheet *name* is formatted from the stored authoring project, not from the database's current
project. A name is emitted only when it is true.
- No sheet references are carried between projects. A database transfer grants no new read access,
and the four reassignment paths above need no changes.
@@ -119,47 +120,39 @@ that sees a list of failed content loads sees a broken product.
### Naming the owner
-The owning project is derivable without new storage, from the revision's own provenance.
-`RevisionPayload` carries `release` (`projects/{project}/releases/{release}`) and `task_run`
-(`projects/{project}/plans/…/taskRuns/{taskRun}`), both embedding the authoring project in the
-resource name; `backend/store/changelog.go:163-168` already parses a project out of a stored
-`taskRun` this way. Resolution order:
-
-1. The revision's `release`, else its `taskRun` — **corroborated by exactly the rule the backfill
- uses**, and resolving to a project in the caller's workspace.
-2. Anything else — report the owner as unknown, and never echo a project ID that failed the test.
-
-**Provenance is a hint, not an assertion.** Both fields are stored verbatim from the caller:
-`convertRevision` writes `Release: revision.Release` and `TaskRun: revision.TaskRun` straight through
-(`backend/api/v1/revision_service.go:352-364`). Until the T6 fix lands, `createRevisions` resolves
-`revision.Release` with no workspace or database-project comparison (`:207-223`), and it never
-compares a `taskRun`'s task to `revision.Sheet` at all — so a revision can carry provenance naming
-another tenant's project, or naming a perfectly real project in the caller's own workspace that had
-nothing to do with the sheet.
-
-**Naming therefore uses the same corroboration rule as the backfill, not a weaker one.** Identity,
-age, and hash match, exactly as specified in
-[the backfill section](sheet-blob-scoping.md#backfill). A design in which the backfill trusts
-corroborated provenance while the response trusts raw provenance has two different notions of
-provenance in it, and the weaker one would be the user-visible one.
-
-| Provenance | Response |
+The owner is a stored fact, not a read-time derivation. `RevisionPayload.project` carries the
+authoring project: the server stamps it at creation from the database's then-current project —
+after validating that the project holds a ref for the revision's hash — and the runners stamp it
+the same way when recording completed task runs. `convertToRevision` formats `Revision.sheet` from
+the stamp and nothing else; an empty stamp means no sheet name.
+
+Rows predating the field are backfilled once, by migration, from the revision's own provenance —
+`release` (`projects/{project}/releases/{release}`), else `taskRun`
+(`projects/{project}/plans/…/taskRuns/{taskRun}`) — **corroborated by exactly the rule the backfill
+uses**: single-row identity, age, and hash match, as specified in
+[the backfill section](sheet-blob-scoping.md#backfill). Corroborated rows get the stamp and a ref;
+everything else stays unstamped.
+
+**Provenance is a hint, not an assertion, which is why the backfill corroborates it.** Both fields
+are stored verbatim from the caller. Before the T6 fix, `createRevisions` resolved a
+`revision.Release` with no database-project comparison and never compared a `taskRun`'s task to
+`revision.Sheet` — so a historical revision can carry provenance naming another tenant's project,
+or naming a perfectly real project in the caller's own workspace that had nothing to do with the
+sheet. A backfill that trusted raw provenance would turn either into a stamp; corroboration is what
+makes the stored fact trustworthy. New writers need no corroboration because the server stamps from
+its own knowledge, and the T6 checks now reject cross-project provenance at creation.
+
+| Row | Sheet name in the response |
|---|---|
-| Corroborated, project in the caller's workspace | Name it |
-| Corroborated, project in another workspace | Owner unknown |
-| Present but not corroborated — stale, purged, or fabricated | Owner unknown |
-| Absent | Owner unknown |
-
-The response may still distinguish *why* it is unavailable — no provenance, provenance that cannot
-be verified, an owner outside the caller's workspace — since a reason is not an identifier. What it
-must never do is echo a project ID that failed a check. Misattribution is not a harmless default: a
-user told that project `payments-core` owns a statement it never authored will go and ask them for
-it, and may be granted access on a false premise.
-
-This applies to *naming*, not to the backfill's use of the same fields. Granting a ref to the project
-that genuinely authored a sheet is correct regardless of which workspace the referencing revision
-sits in — the backfill's corroboration check is about attributing ownership, while this is about what
-a caller is allowed to be told.
+| Stamped at creation, or backfill-corroborated | Named under the stamp |
+| Backfill could not corroborate — stale, purged, or fabricated provenance | No name |
+| No provenance to corroborate | No name |
+
+An unstamped row's response must never echo a project ID that failed the check — a reason is not an
+identifier, and misattribution is not a harmless default: a user told that project `payments-core`
+owns a statement it never authored will go and ask them for it, and may be granted access on a
+false premise. The stamp makes this cheap to honor: naming reads a stored field rather than
+re-running a resolution that could disagree with the one that granted refs.
**`sheet_blob_ref` is not a fallback for authorship.** An earlier draft resolved a provenance-less
revision by finding which projects hold a ref for its hash and naming the one candidate in the
@@ -174,23 +167,22 @@ which is the misattribution this section already rejects for uncorroborated prov
corroboration standard to provenance and a weaker inference to the ref table would be the same
inconsistency in a different place.
-So there is no ref-table fallback. A revision names an owner when its own provenance corroborates
-one, and reports unknown otherwise.
-
-A purged authoring project resolves to unknown, not to a name. `DeleteProject` hard-deletes the
-`release`, `task` and `plan` rows along with the project, so provenance naming it can no longer
-corroborate. That is the correct outcome rather than a gap: the statement is permanently
-unavailable, there is nobody left to ask, and the only thing withheld beyond the content is an ID
-that can no longer be verified against any workspace.
+So there is no ref-table fallback. A revision names an owner when it carries a stamp, and carries a
+stamp only when the server knew the owner at creation or the backfill corroborated one.
-Provenance resolution is attribution only and never implies access. A purged project holds no refs and cannot be
-granted any, since `sheet_blob_ref.project` has a live foreign key, and the backfill skips
-uncorroborated provenance for the same reason.
+**Purge timing splits into two outcomes, deliberately.** A project purged *before* the migration
+leaves its surviving revisions unstampable — provenance naming it can no longer corroborate, since
+`DeleteProject` hard-deletes the `release`, `task` and `plan` rows — so those rows carry no name.
+A project purged *after* its revisions were stamped leaves the stamp behind: the revision keeps
+naming the purged project, the name 404s on read (purge deleted the refs), and the UI reports the
+statement as owned by a project the caller cannot read. The dangling name is accepted rather than
+scrubbed — purge does not rewrite revision payloads, the name was true when stamped, and access
+fails closed regardless. The residual is misattribution-by-reuse: a new project created under the
+purged ID inherits the dangling names' *labels* (never their content — it holds no refs for those
+hashes). The corroboration age test keeps the same reuse from minting stamps in the backfill.
-The response should distinguish the two outcomes rather than flattening them: a live project the
-caller can ask, versus an authoring project that no longer exists and whose content is now
-unreadable by anyone. The second is a permanent consequence of purging a project, consistent with
-the zero-ref blobs described in the scoping doc.
+Attribution never implies access. A purged project holds no refs and cannot be granted any, since
+`sheet_blob_ref.project` has a live foreign key.
Naming the owner discloses that some other project holds SQL with that hash. That is acceptable
within a workspace and strictly less than the content itself.
@@ -230,57 +222,51 @@ corruption outweighs the modelling improvement.
## Implementation
-- A field on the revision response carrying the withheld-content reason and the owning project,
- populated by the resolution above — corroborated provenance, else unknown.
-- `convertToRevision` formats `Revision.sheet` from the resolved owner rather than from
- `database.ProjectID` (`backend/api/v1/revision_service.go:304`), and emits no sheet name when the
- owner does not resolve. Leaving it built from the current project would keep exactly the false
- resource name R7 exists to eliminate — a response asserting that project A owns the statement while
- handing the client `projects/B/sheets/{sha}` to follow, which then 404s. The owner is already
- computed for the withheld-content field, so this costs nothing extra.
-- A UI affordance for the withheld state that names the owning project rather than rendering an
- error, and says the project no longer exists when that is the case.
+- No new response field. The withheld state is derivable client-side from fields that already
+ exist: a revision with `sheet_sha256` but no `sheet` name has no known owner, and a named sheet
+ whose `GetSheet` fails is owned by the named project. `RevisionDetailPanel` renders each as an
+ informational alert — naming the owning project in the second case — rather than an error.
+- `RevisionPayload.project` (`proto/store/store/revision.proto`) stores the authoring project.
+ `convertRevision` and the task-run executor stamp it at creation; migration 3.22.5 backfills
+ corroborated rows.
+- `convertToRevision` formats `Revision.sheet` from the stamp rather than from
+ `database.ProjectID`, and emits no sheet name when the stamp is empty. Leaving it built from the
+ current project would keep exactly the false resource name the scoping doc's R7 exists to
+ eliminate — a response handing the client `projects/B/sheets/{sha}` to follow, which then 404s.
- No *carry* logic in `UpdateDatabase`, `BatchUpdateDatabases`, `updateInstanceLifecycle`, or
`DeleteProject` — nothing moves refs between projects. `DeleteProject` still needs its
`DELETE FROM sheet_blob_ref WHERE project = ?` from the scoping doc: `sheet_blob_ref(project)` has
a plain foreign key with no `ON DELETE CASCADE`, so purging a project that owns refs fails without
it. "No changes" here means no transfer behavior, not no purge cleanup.
-Tests:
-
-- Create a revision under project A, move the database to project B, assert the revision list is
- complete under B while the statement is withheld with A named — A's provenance corroborates, and A
- is in the caller's workspace.
-- Purge path: put a database on a *workspace* instance in project A, create a revision, purge A, then
- assert that under the default project the list is still complete, the statement is withheld, and
- the response reports the owner as unknown and names no project.
- This is the case most likely to regress — it is not a user-facing transfer, and it is the one
- where `sheet_blob_ref` has already been deleted, so it exercises the provenance path specifically.
-- Instance archive: put a database on a **workspace** instance in project A, create a revision, then
- archive the instance with `MoveDatabasesToProjectID` set to project B, and assert the revision list
- is complete under B while the statement is withheld with A named. Archiving a *project* instance is
- the wrong path — `backend/store/instance.go:434` rejects it — so a test written that way would pass
- vacuously without exercising any transfer.
-- A revision carrying neither `release` nor `taskRun` reports unknown, even when exactly one project
- in the caller's workspace holds a ref for that hash — that ref proves identical content, not
- authorship.
-- Cross-tenant leak guard, both paths: (a) seed identical SQL in two workspaces so one blob carries
- refs from both, then request a withheld statement from one and assert the response never names the
- other workspace's project; (b) seed a revision whose `release` provenance names a project in
- another workspace — the state T6 permits — and assert the response reports unknown rather than
- echoing it; (c) seed a revision naming a real project in the caller's *own* workspace that never
- authored the sheet, and assert the response reports unknown rather than misattributing it. Generated `CREATE DATABASE` boilerplate makes this collision realistic, so it
- is a regression test rather than a contrived one.
-- Sheet name: after a transfer, `Revision.sheet` names the resolved owner and resolves to that
- project's readable sheet for a caller who holds rights there; when the owner is unknown, no sheet
- name is emitted rather than one pointing at the current project.
+Tests, as implemented:
+
+- `TestSheetHistoryOnDatabaseTransfer` — a revision authored under project A, database moved to B:
+ the list is complete under B, the sheet stays named under A, a caller with rights on A reads the
+ statement through that name, and B gains no read access of its own.
+- `TestSheetHistoryAfterOwnerPurge` — the authoring project is purged after stamping, the database
+ lands in the default project: the list is complete, the dangling name still renders, and reading
+ it returns NotFound. This is the case most likely to regress — not a user-facing transfer, and
+ the one where `sheet_blob_ref` has already been deleted.
+- The backfill matrix (`TestMigration3_22_5_ScopeSheetBlob`) carries the naming negatives that were
+ previously listed as read-path tests, since naming is now decided where the stamp is written: a
+ revision with no provenance stays unstamped even when another project holds a ref for the
+ identical hash; provenance naming a ghost project, a project that never authored the hash, or a
+ reused ID (the age test) stays unstamped rather than misattributed. The instance-archive transfer
+ path needs no dedicated test because no per-path logic exists — naming reads the stamp and no
+ path carries refs, so all four reassignment paths share one behavior by construction.
## Open items
-**Revisions with no resolvable owner have no sheet name.** Where the owner resolves, the name is
-correct and unchanged for every database that never moved. Where it does not, the response carries
-no sheet name at all — a behavior change for clients that assume the field is always populated, and
-the residual cost of refusing to emit a name that is not true.
+**Revisions with no stamp have no sheet name.** Where the stamp exists, the name is correct and
+unchanged for every database that never moved. Where it does not, the response carries no sheet
+name at all — a behavior change for clients that assume the field is always populated, and the
+residual cost of refusing to emit a name that is not true.
+
+**Stamped names can dangle after a purge.** A post-migration purge leaves stamped revisions naming
+a project that no longer exists; the name 404s and the UI reports an owner the caller cannot read.
+Accepted deliberately — see [Naming the owner](#naming-the-owner) — with ID reuse inheriting labels
+but never content.
**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
diff --git a/docs/pre-pr-checklist.md b/docs/pre-pr-checklist.md
index 2981888a6d..3f10810af8 100644
--- a/docs/pre-pr-checklist.md
+++ b/docs/pre-pr-checklist.md
@@ -60,6 +60,7 @@ Read `backend/migrator/migration/LATEST.sql` and find every table with a multi-c
- `task_run (project, id)`
- `db_group (project, resource_id)`
- `release (project, train, iteration)`
+- `sheet_blob_ref (project, sha256)`
`task_run_log` deliberately has no primary key (append-only log; entries for one
task run can share a `created_at` microsecond — BYT-10035), but it is equally
@@ -93,13 +94,15 @@ If the diff adds or modifies a store method that touches a composite-PK table:
1. Check if a corresponding `TestCollision*` or `TestClaim*` test exists in `backend/tests/`
2. If not, add one using `setupCollidingProjects` and `assertProjectUnchanged` from
`backend/tests/collision_helper_test.go`. The shared snapshot covers `plan`,
- `issue`, `task`, `task_run`, `plan_check_run`, `task_run_log`, `db_group`, and
- `release` (public APIs where one exists). `plan_webhook_delivery` has no public
- read API and uses a table-specific raw metadata-DB read; its rows are claimed
+ `issue`, `task`, `task_run`, `plan_check_run`, `task_run_log`, `db_group`,
+ `release`, and `sheet_blob_ref` (public APIs where one exists). `plan_webhook_delivery`
+ has no public read API and uses a table-specific raw metadata-DB read; its rows are claimed
asynchronously after rollout completion, so raw-read tests must stabilize the
row set before snapshotting and compare the table separately —
`assertProjectUnchanged` does not compare `PlanWebhookDeliveries`. See
- `backend/tests/README.md` for the pattern. For methods touching any future
+ `backend/tests/README.md` for the pattern. `sheet_blob_ref` is also read raw
+ (no public API) but written synchronously, so `assertProjectUnchanged`
+ compares it directly. For methods touching any future
table outside that set, add table-specific assertions inline — or extend the
shared helper first
3. If your test needs project B rolled out (to create task/task_run/plan_check_run
diff --git a/frontend/src/components/revision/RevisionDetailPanel.tsx b/frontend/src/components/revision/RevisionDetailPanel.tsx
index 8311b4ea99..cee59632aa 100644
--- a/frontend/src/components/revision/RevisionDetailPanel.tsx
+++ b/frontend/src/components/revision/RevisionDetailPanel.tsx
@@ -5,17 +5,28 @@ import { sheetServiceClientConnect } from "@/api";
import { ReadonlyMonaco } from "@/components/monaco";
import { RouterLink } from "@/components/RouterLink";
import { TaskRunLogViewer } from "@/components/task-run-log";
+import { Alert } from "@/components/ui/alert";
import { CopyButton } from "@/components/ui/copy-button";
import { useRevisionByName } from "@/hooks/useAppState";
import { useAppStore } from "@/stores/app";
import { getTimeForPbTimestampProtoEs } from "@/types";
import { bytesToString, formatAbsoluteDateTime } from "@/utils";
+import { extractProjectResourceName } from "@/utils/v1/project";
import { extractTaskLink, getRevisionType } from "@/utils/v1/revision";
export interface RevisionDetailPanelProps {
revisionName: string;
}
+// The statement behind a revision stays with the project that authored it
+// when a database moves between projects, so it can be unavailable here:
+// either the sheet names an owner the caller lacks access to (request it
+// there), or the revision carries no sheet name because the owner can no
+// longer be determined.
+interface WithheldStatement {
+ ownerProject?: string;
+}
+
export function RevisionDetailPanel({
revisionName,
}: RevisionDetailPanelProps) {
@@ -24,11 +35,13 @@ export function RevisionDetailPanel({
const revision = useRevisionByName(revisionName);
const [loading, setLoading] = useState(false);
const [statement, setStatement] = useState("");
+ const [withheld, setWithheld] = useState<WithheldStatement | null>(null);
useEffect(() => {
if (!revisionName) {
setLoading(false);
setStatement("");
+ setWithheld(null);
return;
}
@@ -36,10 +49,19 @@ export function RevisionDetailPanel({
setLoading(true);
setStatement("");
+ setWithheld(null);
void fetchRevision(revisionName)
.then(async (rev) => {
- if (!rev?.sheet) {
+ if (!rev) {
+ return;
+ }
+ if (!rev.sheet) {
+ // No sheet name is emitted when the revision carries no authoring
+ // project (pre-migration provenance that did not corroborate).
+ if (rev.sheetSha256 && !cancelled) {
+ setWithheld({});
+ }
return;
}
@@ -53,6 +75,12 @@ export function RevisionDetailPanel({
}
} catch (error) {
console.error("Failed to fetch sheet content", error);
+ if (!cancelled) {
+ // The owner is named but this caller has no read access there.
+ setWithheld({
+ ownerProject: extractProjectResourceName(rev.sheet),
+ });
+ }
}
})
.catch((error) => {
@@ -69,6 +97,18 @@ export function RevisionDetailPanel({
};
}, [fetchRevision, revisionName]);
+ const withheldMessage = (() => {
+ if (!withheld) {
+ return "";
+ }
+ if (withheld.ownerProject) {
+ return t("revision.statement-withheld.owned-by-project", {
+ project: withheld.ownerProject,
+ });
+ }
+ return t("revision.statement-withheld.unknown-owner");
+ })();
+
const taskFullLink = revision?.taskRun
? extractTaskLink(revision.taskRun)
: "";
@@ -132,14 +172,18 @@ export function RevisionDetailPanel({
({formattedStatementSize})
</span>
) : null}
- <CopyButton content={statement} />
+ {statement ? <CopyButton content={statement} /> : null}
</p>
- <div className="overflow-hidden rounded-sm border border-control-border bg-white">
- <ReadonlyMonaco
- content={statement}
- className="relative h-auto max-h-[600px] min-h-[120px]"
- />
- </div>
+ {withheld && !statement ? (
+ <Alert variant="info" description={withheldMessage} />
+ ) : (
+ <div className="overflow-hidden rounded-sm border border-control-border bg-white">
+ <ReadonlyMonaco
+ content={statement}
+ className="relative h-auto max-h-[600px] min-h-[120px]"
+ />
+ </div>
+ )}
</div>
</div>
</main>
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index 577b2f2257..b3bf3a1eff 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -2068,6 +2068,12 @@
"pattern": "The {{resource}} ID can have lowercase letters, digits, or hyphens. It must start with a lowercase letter and end with a letter or number."
}
},
+ "revision": {
+ "statement-withheld": {
+ "owned-by-project": "The statement is owned by project {{project}}. Request access there to view it.",
+ "unknown-owner": "The statement is unavailable: the project that authored it can no longer be determined."
+ }
+ },
"role": {
"custom-roles": {
"self": "Custom roles"
diff --git a/frontend/src/locales/es-ES.json b/frontend/src/locales/es-ES.json
index 09f12aeeb1..139ffc0fe5 100644
--- a/frontend/src/locales/es-ES.json
+++ b/frontend/src/locales/es-ES.json
@@ -2068,6 +2068,12 @@
"pattern": "La identificación {{resource}} puede tener letras, dígitos o guiones minúsculas. Debe comenzar con una letra minúscula y terminar con una letra o número."
}
},
+ "revision": {
+ "statement-withheld": {
+ "owned-by-project": "La sentencia pertenece al proyecto {{project}}. Solicita acceso allí para verla.",
+ "unknown-owner": "La sentencia no está disponible: ya no se puede determinar el proyecto que la creó."
+ }
+ },
"role": {
"custom-roles": {
"self": "Roles personalizados"
diff --git a/frontend/src/locales/ja-JP.json b/frontend/src/locales/ja-JP.json
index 53f40e8960..0f044b5f12 100644
--- a/frontend/src/locales/ja-JP.json
+++ b/frontend/src/locales/ja-JP.json
@@ -2068,6 +2068,12 @@
"pattern": "{{resource}} ID には、小文字、数字、またはハイフンを持つことができます。\n小文字から始めて、文字または番号で終わる必要があります。"
}
},
+ "revision": {
+ "statement-withheld": {
+ "owned-by-project": "このステートメントはプロジェクト {{project}} が所有しています。閲覧するには、そのプロジェクトでアクセス権を申請してください。",
+ "unknown-owner": "このステートメントは利用できません。作成元のプロジェクトを特定できなくなりました。"
+ }
+ },
"role": {
"custom-roles": {
"self": "カスタムロール"
diff --git a/frontend/src/locales/vi-VN.json b/frontend/src/locales/vi-VN.json
index f190a4c2b3..bf5388b4fa 100644
--- a/frontend/src/locales/vi-VN.json
+++ b/frontend/src/locales/vi-VN.json
@@ -2068,6 +2068,12 @@
"pattern": "ID {{resource}} có thể có chữ thường, chữ số hoặc dấu gạch nối. \nNó phải bắt đầu với một chữ cái viết thường và kết thúc bằng một chữ cái hoặc số."
}
},
+ "revision": {
+ "statement-withheld": {
+ "owned-by-project": "Câu lệnh thuộc sở hữu của dự án {{project}}. Hãy yêu cầu quyền truy cập tại đó để xem.",
+ "unknown-owner": "Câu lệnh không khả dụng: không thể xác định dự án đã tạo ra nó."
+ }
+ },
"role": {
"custom-roles": {
"self": "Vai trò tùy chỉnh"
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 47b101ca28..5756fb2be3 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -2068,6 +2068,12 @@
"pattern": "{{resource}} ID 可以具有小写字母,数字或连字符。\n它必须从小写字母开始,并以字母或数字结尾。"
}
},
+ "revision": {
+ "statement-withheld": {
+ "owned-by-project": "该语句由项目 {{project}} 所有。请向该项目申请访问权限后查看。",
+ "unknown-owner": "该语句不可用:无法确定创建它的项目。"
+ }
+ },
"role": {
"custom-roles": {
"self": "自定义角色"
diff --git a/frontend/src/types/iam/permission-generated.ts b/frontend/src/types/iam/permission-generated.ts
index e3acce6a4d..d44fafcc7b 100644
--- a/frontend/src/types/iam/permission-generated.ts
+++ b/frontend/src/types/iam/permission-generated.ts
@@ -117,7 +117,6 @@ export type Permission =
| "bb.settings.setWorkspaceProfile"
| "bb.sheets.create"
| "bb.sheets.get"
- | "bb.sheets.update"
| "bb.subscription.manage"
| "bb.sql.select"
| "bb.sql.ddl"
diff --git a/frontend/src/types/proto-es/v1/sheet_service_pb.js b/frontend/src/types/proto-es/v1/sheet_service_pb.js
index de2a1c3093..5e1c4ab110 100644
--- a/frontend/src/types/proto-es/v1/sheet_service_pb.js
+++ b/frontend/src/types/proto-es/v1/sheet_service_pb.js
@@ -13,7 +13,7 @@ import { file_v1_annotation } from "./annotation_pb";
* Describes the file v1/sheet_service.proto.
*/
export const file_v1_sheet_service = /*@__PURE__*/
- fileDesc("ChZ2MS9zaGVldF9zZXJ2aWNlLnByb3RvEgtieXRlYmFzZS52MSJqChJDcmVhdGVTaGVldFJlcXVlc3QSLAoGcGFyZW50GAEgASgJQhzgQQL6QRYKFGJ5dGViYXNlLmNvbS9Qcm9qZWN0EiYKBXNoZWV0GAIgASgLMhIuYnl0ZWJhc2UudjEuU2hlZXRCA+BBAiKAAQoYQmF0Y2hDcmVhdGVTaGVldHNSZXF1ZXN0EiwKBnBhcmVudBgBIAEoCUIc4EEC+kEWChRieXRlYmFzZS5jb20vUHJvamVjdBI2CghyZXF1ZXN0cxgCIAMoCzIfLmJ5dGViYXNlLnYxLkNyZWF0ZVNoZWV0UmVxdWVzdEID4EECIj8KGUJhdGNoQ3JlYXRlU2hlZXRzUmVzcG9uc2USIgoGc2hlZXRzGAEgAygLMhIuYnl0ZWJhc2UudjEuU2hlZXQiSAoPR2V0U2hlZXRSZXF1ZXN0EigKBG5hbWUYASABKAlCGuBBAvpBFAoSYnl0ZWJhc2UuY29tL1NoZWV0EgsKA3JhdxgCIAEoCCKKAQoFU2hlZXQSFAoEbmFtZRgBIAEoCUIG4EEC4EEFEhQKB2NvbnRlbnQYAiABKAxCA+BBAhIZCgxjb250ZW50X3NpemUYAyABKANCA+BBAzo66kE3ChJieXRlYmFzZS5jb20vU2hlZXQSIXByb2plY3RzL3twcm9qZWN0fS9zaGVldHMve3NoZWV0fTLgAwoMU2hlZXRTZXJ2aWNlEpgBCgtDcmVhdGVTaGVldBIfLmJ5dGViYXNlLnYxLkNyZWF0ZVNoZWV0UmVxdWVzdBoSLmJ5dGViYXNlLnYxLlNoZWV0IlTaQQxwYXJlbnQsc2hlZXSK6jAQYmIuc2hlZXRzLmNyZWF0ZZDqMAGC0+STAic6BXNoZWV0Ih4vdjEve3BhcmVudD1wcm9qZWN0cy8qfS9zaGVldHMSsQEKEUJhdGNoQ3JlYXRlU2hlZXRzEiUuYnl0ZWJhc2UudjEuQmF0Y2hDcmVhdGVTaGVldHNSZXF1ZXN0GiYuYnl0ZWJhc2UudjEuQmF0Y2hDcmVhdGVTaGVldHNSZXNwb25zZSJNiuowEGJiLnNoZWV0cy5jcmVhdGWQ6jABgtPkkwIvOgEqIiovdjEve3BhcmVudD1wcm9qZWN0cy8qfS9zaGVldHM6YmF0Y2hDcmVhdGUSgAEKCEdldFNoZWV0EhwuYnl0ZWJhc2UudjEuR2V0U2hlZXRSZXF1ZXN0GhIuYnl0ZWJhc2UudjEuU2hlZXQiQtpBBG5hbWWK6jANYmIuc2hlZXRzLmdldJDqMAGC0+STAiASHi92MS97bmFtZT1wcm9qZWN0cy8qL3NoZWV0cy8qfUKnAQoPY29tLmJ5dGViYXNlLnYxQhFTaGVldFNlcnZpY2VQcm90b1ABWjRnaXRodWIuY29tL2J5dGViYXNlL2J5dGViYXNlL2JhY2tlbmQvZ2VuZXJhdGVkLWdvL3YxogIDQlhYqgILQnl0ZWJhc2UuVjHKAgtCeXRlYmFzZVxWMeICF0J5dGViYXNlXFYxXEdQQk1ldGFkYXRh6gIMQnl0ZWJhc2U6OlYxYgZwcm90bzM", [file_google_api_annotations, file_google_api_client, file_google_api_field_behavior, file_google_api_resource, file_v1_annotation]);
+ fileDesc("ChZ2MS9zaGVldF9zZXJ2aWNlLnByb3RvEgtieXRlYmFzZS52MSJqChJDcmVhdGVTaGVldFJlcXVlc3QSLAoGcGFyZW50GAEgASgJQhzgQQL6QRYKFGJ5dGViYXNlLmNvbS9Qcm9qZWN0EiYKBXNoZWV0GAIgASgLMhIuYnl0ZWJhc2UudjEuU2hlZXRCA+BBAiKAAQoYQmF0Y2hDcmVhdGVTaGVldHNSZXF1ZXN0EiwKBnBhcmVudBgBIAEoCUIc4EEC+kEWChRieXRlYmFzZS5jb20vUHJvamVjdBI2CghyZXF1ZXN0cxgCIAMoCzIfLmJ5dGViYXNlLnYxLkNyZWF0ZVNoZWV0UmVxdWVzdEID4EECIj8KGUJhdGNoQ3JlYXRlU2hlZXRzUmVzcG9uc2USIgoGc2hlZXRzGAEgAygLMhIuYnl0ZWJhc2UudjEuU2hlZXQiSAoPR2V0U2hlZXRSZXF1ZXN0EigKBG5hbWUYASABKAlCGuBBAvpBFAoSYnl0ZWJhc2UuY29tL1NoZWV0EgsKA3JhdxgCIAEoCCKKAQoFU2hlZXQSFAoEbmFtZRgBIAEoCUIG4EEC4EEFEhQKB2NvbnRlbnQYAiABKAxCA+BBAhIZCgxjb250ZW50X3NpemUYAyABKANCA+BBAzo66kE3ChJieXRlYmFzZS5jb20vU2hlZXQSIXByb2plY3RzL3twcm9qZWN0fS9zaGVldHMve3NoZWV0fTLoAwoMU2hlZXRTZXJ2aWNlEpwBCgtDcmVhdGVTaGVldBIfLmJ5dGViYXNlLnYxLkNyZWF0ZVNoZWV0UmVxdWVzdBoSLmJ5dGViYXNlLnYxLlNoZWV0IljaQQxwYXJlbnQsc2hlZXSK6jAQYmIuc2hlZXRzLmNyZWF0ZZDqMAGY6jABgtPkkwInOgVzaGVldCIeL3YxL3twYXJlbnQ9cHJvamVjdHMvKn0vc2hlZXRzErUBChFCYXRjaENyZWF0ZVNoZWV0cxIlLmJ5dGViYXNlLnYxLkJhdGNoQ3JlYXRlU2hlZXRzUmVxdWVzdBomLmJ5dGViYXNlLnYxLkJhdGNoQ3JlYXRlU2hlZXRzUmVzcG9uc2UiUYrqMBBiYi5zaGVldHMuY3JlYXRlkOowAZjqMAGC0+STAi86ASoiKi92MS97cGFyZW50PXByb2plY3RzLyp9L3NoZWV0czpiYXRjaENyZWF0ZRKAAQoIR2V0U2hlZXQSHC5ieXRlYmFzZS52MS5HZXRTaGVldFJlcXVlc3QaEi5ieXRlYmFzZS52MS5TaGVldCJC2kEEbmFtZYrqMA1iYi5zaGVldHMuZ2V0kOowAYLT5JMCIBIeL3YxL3tuYW1lPXByb2plY3RzLyovc2hlZXRzLyp9QqcBCg9jb20uYnl0ZWJhc2UudjFCEVNoZWV0U2VydmljZVByb3RvUAFaNGdpdGh1Yi5jb20vYnl0ZWJhc2UvYnl0ZWJhc2UvYmFja2VuZC9nZW5lcmF0ZWQtZ28vdjGiAgNCWFiqAgtCeXRlYmFzZS5WMcoCC0J5dGViYXNlXFYx4gIXQnl0ZWJhc2VcVjFcR1BCTWV0YWRhdGHqAgxCeXRlYmFzZTo6VjFiBnByb3RvMw", [file_google_api_annotations, file_google_api_client, file_google_api_field_behavior, file_google_api_resource, file_v1_annotation]);
/**
* Describes the message bytebase.v1.CreateSheetRequest.
diff --git a/proto/store/store/revision.proto b/proto/store/store/revision.proto
index 735cac36f5..3a260f5abb 100644
--- a/proto/store/store/revision.proto
+++ b/proto/store/store/revision.proto
@@ -27,4 +27,14 @@ message RevisionPayload {
// The type of the revision.
SchemaChangeType type = 6;
+
+ // The project that authored this revision's change — where the plan or
+ // release that produced it ran. Stamped by the server at creation from the
+ // database's then-current project; rows predating the field are backfilled
+ // from corroborated provenance (migration 3.22.5). Not a scope: revisions
+ // stay keyed by (instance, db_name) and follow the database across project
+ // transfers, while the statement's sheet stays readable under this project.
+ // Can be empty when no owner could be corroborated; such statements are
+ // unreadable and the revision carries no sheet name.
+ string project = 7;
}
diff --git a/proto/v1/v1/sheet_service.proto b/proto/v1/v1/sheet_service.proto
index f7c479f803..18911ba2cd 100644
--- a/proto/v1/v1/sheet_service.proto
+++ b/proto/v1/v1/sheet_service.proto
@@ -22,6 +22,7 @@ service SheetService {
option (google.api.method_signature) = "parent,sheet";
option (bytebase.v1.permission) = "bb.sheets.create";
option (bytebase.v1.auth_method) = IAM;
+ option (bytebase.v1.audit) = true;
}
// Creates multiple SQL sheets in a single operation.
@@ -33,6 +34,7 @@ service SheetService {
};
option (bytebase.v1.permission) = "bb.sheets.create";
option (bytebase.v1.auth_method) = IAM;
+ option (bytebase.v1.audit) = true;
}
// Retrieves a SQL sheet by name.