feat(api): soft-delete build layers in DB on user delete

packages/api/internal/cache/templates/cache.go

@@ -175,7 +175,7 @@ func (c *TemplateCache) fetchTemplateWithBuild(templateID string, tag *string) f
 		}
 
 		build := &result.EnvBuild
-		template := result.Env
+		template := result.ActiveEnv
 		clusterID := clusters.WithClusterFallback(template.ClusterID)
 
 		tagValue := sharedUtils.DerefOrDefault(tag, id.DefaultTag)

packages/api/internal/cache/templates/template_build.go

@@ -84,12 +84,12 @@ func (c *TemplatesBuildCache) fetchFromDB(templateID string, buildID uuid.UUID)
 		}
 
 		return TemplateBuildInfo{
-			TeamID:      result.Env.TeamID,
-			TemplateID:  result.Env.ID,
+			TeamID:      result.ActiveEnv.TeamID,
+			TemplateID:  result.ActiveEnv.ID,
 			BuildStatus: result.EnvBuild.StatusGroup,
 			Reason:      result.EnvBuild.Reason,
 			Version:     result.EnvBuild.Version,
-			ClusterID:   clusters.WithClusterFallback(result.Env.ClusterID),
+			ClusterID:   clusters.WithClusterFallback(result.ActiveEnv.ClusterID),
 			NodeID:      result.EnvBuild.ClusterNodeID,
 		}, nil
 	}

packages/api/internal/handlers/deprecated_template_request_build.go

@@ -107,7 +107,7 @@ func (a *APIStore) PostTemplatesTemplateID(c *gin.Context, rawTemplateID api.Tem
 		return
 	}
 
-	templateDB, err := a.sqlcDB.GetTemplateByID(ctx, templateID)
+	templateDB, err := a.sqlcDB.GetTemplateById(ctx, templateID)
 	switch {
 	case err == nil:
 		if templateDB.TeamID != team.ID {

packages/api/internal/handlers/deprecated_template_start_build.go

@@ -120,7 +120,7 @@ func (a *APIStore) PostTemplatesTemplateIDBuildsBuildID(c *gin.Context, template
 	var team *types.Team
 	// Check if the user has access to the template
 	for _, t := range teams {
-		if t.Team.ID == templateBuildDB.Env.TeamID {
+		if t.Team.ID == templateBuildDB.ActiveEnv.TeamID {
 			team = t.Team
 
 			break

packages/api/internal/handlers/template_delete.go

@@ -80,11 +80,7 @@ func (a *APIStore) DeleteTemplatesTemplateID(c *gin.Context, aliasOrTemplateID a
 		return
 	}
 
-	// Delete the template from DB (cascades to env_build_assignments, env_aliases, snapshot_templates).
-	// Returns alias cache keys captured before cascade deletion for cache invalidation.
-	// Build artifacts are intentionally NOT deleted from storage here because builds are layered diffs
-	// that may be referenced by other builds' header mappings.
-	// [ENG-3477] a future GC mechanism will handle orphaned storage.
+	// Soft-deletes the env and releases aliases.
 	aliasKeys, err := a.sqlcDB.DeleteTemplate(ctx, queries.DeleteTemplateParams{
 		TemplateID: templateID,
 		TeamID:     team.ID,

packages/api/internal/handlers/template_layer_files_upload.go

@@ -26,8 +26,8 @@ func (a *APIStore) GetTemplatesTemplateIDFilesHash(c *gin.Context, templateID ap
 		return
 	}
 
-	// Check if the user has access to the template
-	templateDB, err := a.sqlcDB.GetTemplateByID(ctx, templateID)
+	// Resolve via the active-envs view so a soft-deleted template is not found.
+	templateDB, err := a.sqlcDB.GetTemplateById(ctx, templateID)
 	if err != nil {
 		a.sendAPIStoreError(c, http.StatusNotFound, fmt.Sprintf("Error when getting template: %s", err))
 		telemetry.ReportCriticalError(ctx, "error when getting env", err, telemetry.WithTemplateID(templateID))

packages/api/internal/handlers/template_start_build_v2.go

@@ -71,7 +71,7 @@ func (a *APIStore) PostV2TemplatesTemplateIDBuildsBuildID(c *gin.Context, templa
 		return
 	}
 
-	dbTeamID := templateBuildDB.Env.TeamID.String()
+	dbTeamID := templateBuildDB.ActiveEnv.TeamID.String()
 	team, apiErr := a.GetTeam(ctx, c, &dbTeamID)
 	if apiErr != nil {
 		a.sendAPIStoreError(c, apiErr.Code, apiErr.ClientMsg)
@@ -80,7 +80,7 @@ func (a *APIStore) PostV2TemplatesTemplateIDBuildsBuildID(c *gin.Context, templa
 		return
 	}
 
-	if team.ID != templateBuildDB.Env.TeamID {
+	if team.ID != templateBuildDB.ActiveEnv.TeamID {
 		a.sendAPIStoreError(c, http.StatusForbidden, "User does not have access to the template")
 
 		telemetry.ReportCriticalError(ctx, "user does not have access to the template", err, telemetry.WithTemplateID(templateID))

packages/api/internal/handlers/template_tags.go

@@ -103,7 +103,7 @@ func (a *APIStore) PostTemplatesTags(c *gin.Context) {
 		return
 	}
 
-	template := result.Env
+	template := result.ActiveEnv
 	buildID := result.EnvBuild.ID
 
 	telemetry.SetAttributes(ctx,
@@ -129,7 +129,7 @@ func (a *APIStore) PostTemplatesTags(c *gin.Context) {
 
 	// Create the tag assignments
 	for _, tag := range tags {
-		err = client.CreateTemplateBuildAssignment(ctx, queries.CreateTemplateBuildAssignmentParams{
+		rows, err := client.CreateTemplateBuildAssignment(ctx, queries.CreateTemplateBuildAssignmentParams{
 			TemplateID: template.ID,
 			BuildID:    buildID,
 			Tag:        tag,
@@ -138,6 +138,11 @@ func (a *APIStore) PostTemplatesTags(c *gin.Context) {
 			telemetry.ReportCriticalError(ctx, "error when creating tag assignment", err)
 			a.sendAPIStoreError(c, http.StatusInternalServerError, "Error creating tag assignment")
 
+			return
+		}
+		if rows == 0 {
+			a.sendAPIStoreError(c, http.StatusNotFound, fmt.Sprintf("Template '%s' not found", template.ID))
+
 			return
 		}
 	}

packages/api/internal/handlers/templates_list.go

@@ -69,19 +69,19 @@ func (a *APIStore) GetTemplates(c *gin.Context, params api.GetTemplatesParams) {
 		}
 
 		templates = append(templates, &api.Template{
-			TemplateID:    item.Env.ID,
+			TemplateID:    item.ActiveEnv.ID,
 			BuildID:       item.BuildID.String(),
 			CpuCount:      api.CPUCount(item.BuildVcpu),
 			MemoryMB:      api.MemoryMB(item.BuildRamMb),
 			DiskSizeMB:    api.DiskSizeMB(diskMB),
-			Public:        item.Env.Public,
+			Public:        item.ActiveEnv.Public,
 			Aliases:       item.Aliases,
 			Names:         item.Names,
-			CreatedAt:     item.Env.CreatedAt,
-			UpdatedAt:     item.Env.UpdatedAt,
-			LastSpawnedAt: item.Env.LastSpawnedAt,
-			SpawnCount:    item.Env.SpawnCount,
-			BuildCount:    item.Env.BuildCount,
+			CreatedAt:     item.ActiveEnv.CreatedAt,
+			UpdatedAt:     item.ActiveEnv.UpdatedAt,
+			LastSpawnedAt: item.ActiveEnv.LastSpawnedAt,
+			SpawnCount:    item.ActiveEnv.SpawnCount,
+			BuildCount:    item.ActiveEnv.BuildCount,
 			BuildStatus:   getCorrespondingTemplateBuildStatus(ctx, item.BuildStatus),
 			CreatedBy:     createdBy,
 			EnvdVersion:   envdVersion,

packages/api/internal/orchestrator/snapshot_template.go

@@ -152,14 +152,17 @@ func (o *Orchestrator) resolveOrCreateSnapshotTemplate(
 ) (string, error) {
 	// Existing template — just assign the build
 	if opts.ExistingTemplateID != nil {
-		err := o.sqlcDB.CreateTemplateBuildAssignment(ctx, queries.CreateTemplateBuildAssignmentParams{
+		rows, err := o.sqlcDB.CreateTemplateBuildAssignment(ctx, queries.CreateTemplateBuildAssignmentParams{
 			TemplateID: *opts.ExistingTemplateID,
 			BuildID:    buildID,
 			Tag:        opts.Tag,
 		})
 		if err != nil {
 			return "", fmt.Errorf("error assigning build to existing template: %w", err)
 		}
+		if rows == 0 {
+			return "", fmt.Errorf("template '%s' not found", *opts.ExistingTemplateID)
+		}
 
 		return *opts.ExistingTemplateID, nil
 	}

packages/api/internal/template-manager/template_manager.go

@@ -96,7 +96,7 @@ func (tm *TemplateManager) BuildsStatusPeriodicalSync(ctx context.Context) {
 			logger.L().Info(ctx, "Running periodical sync of builds statuses", zap.Int("count", len(buildsRunning)))
 			for _, b := range buildsRunning {
 				go func(b queries.GetInProgressTemplateBuildsRow) {
-					err := tm.BuildStatusSync(ctx, b.EnvBuild.ID, b.Env.ID, clustersshared.WithClusterFallback(b.TeamClusterID), b.EnvBuild.ClusterNodeID)
+					err := tm.BuildStatusSync(ctx, b.EnvBuild.ID, b.ActiveEnv.ID, clustersshared.WithClusterFallback(b.TeamClusterID), b.EnvBuild.ClusterNodeID)
 					if err != nil {
 						logger.L().Error(ctx, "Error syncing build status", zap.Error(err), zap.String("buildID", b.EnvBuild.ID.String()))
 					}

packages/api/internal/template/register_build.go

@@ -165,14 +165,23 @@ func RegisterBuild(
 		clusterID = &data.ClusterID
 	}
 
-	// Create the template / or update the build count
-	err = client.CreateOrUpdateTemplate(ctx, queries.CreateOrUpdateTemplateParams{
+	// Create the template / or update the build count. A soft-deleted template
+	// is not reactivated: the query returns no row, so the rebuild fails.
+	_, err = client.CreateOrUpdateTemplate(ctx, queries.CreateOrUpdateTemplateParams{
 		TemplateID: data.TemplateID,
 		TeamID:     data.Team.ID,
 		CreatedBy:  data.UserID,
 		ClusterID:  clusterID,
 	})
 	if err != nil {
+		if dberrors.IsNotFoundError(err) {
+			return nil, &api.APIError{
+				Err:       err,
+				ClientMsg: fmt.Sprintf("Template '%s' has been deleted and cannot be rebuilt", data.TemplateID),
+				Code:      http.StatusNotFound,
+			}
+		}
+
 		telemetry.ReportCriticalError(ctx, "error when updating env", err)
 
 		return nil, &api.APIError{
@@ -327,7 +336,9 @@ func RegisterBuild(
 	}
 
 	for _, tag := range tags {
-		err = client.CreateTemplateBuildAssignment(ctx, queries.CreateTemplateBuildAssignmentParams{
+		// Env is active in this tx (CreateOrUpdateTemplate succeeded above), so
+		// the active_envs guard always matches here; rows is ignored.
+		_, err = client.CreateTemplateBuildAssignment(ctx, queries.CreateTemplateBuildAssignmentParams{
 			TemplateID: data.TemplateID,
 			BuildID:    buildID,
 			Tag:        tag,

packages/dashboard-api/internal/handlers/template_get.go

@@ -47,16 +47,16 @@ func (s *APIStore) GetTemplatesTemplateID(c *gin.Context, templateID api.Templat
 	}
 
 	resp := api.TemplateDetail{
-		TemplateID:    row.Env.ID,
+		TemplateID:    row.ActiveEnv.ID,
 		BuildID:       row.BuildID.String(),
-		Public:        row.Env.Public,
+		Public:        row.ActiveEnv.Public,
 		Aliases:       row.Aliases,
 		Names:         row.Names,
-		CreatedAt:     row.Env.CreatedAt,
-		UpdatedAt:     row.Env.UpdatedAt,
-		LastSpawnedAt: row.Env.LastSpawnedAt,
-		SpawnCount:    row.Env.SpawnCount,
-		BuildCount:    row.Env.BuildCount,
+		CreatedAt:     row.ActiveEnv.CreatedAt,
+		UpdatedAt:     row.ActiveEnv.UpdatedAt,
+		LastSpawnedAt: row.ActiveEnv.LastSpawnedAt,
+		SpawnCount:    row.ActiveEnv.SpawnCount,
+		BuildCount:    row.ActiveEnv.BuildCount,
 	}
 
 	if row.BuildID != uuid.Nil {

packages/db/migrations/20260628120000_add_env_deleted_at.sql

@@ -0,0 +1,25 @@
+-- +goose Up
+-- Soft-delete marker for envs: deleting a template/snapshot stamps deleted_at
+-- instead of cascading its rows away. The active_envs view is the canonical
+-- read path so callers don't repeat the deleted_at IS NULL filter.
+ALTER TABLE "public"."envs" ADD COLUMN IF NOT EXISTS deleted_at timestamptz NULL;
+
+CREATE OR REPLACE VIEW "public"."active_envs" AS
+SELECT
+    id,
+    created_at,
+    updated_at,
+    public,
+    build_count,
+    spawn_count,
+    last_spawned_at,
+    team_id,
+    created_by,
+    cluster_id,
+    source
+FROM "public"."envs"
+WHERE deleted_at IS NULL;
+
+-- +goose Down
+DROP VIEW IF EXISTS "public"."active_envs";
+ALTER TABLE "public"."envs" DROP COLUMN IF EXISTS deleted_at;

packages/db/pkg/dashboard/sql_queries/templates/get_default_templates.sql

@@ -11,7 +11,7 @@ SELECT
     b.total_disk_size_mb,
     b.envd_version
 FROM public.env_defaults ed
-JOIN public.envs e ON e.id = ed.env_id
+JOIN public.active_envs e ON e.id = ed.env_id
 JOIN LATERAL (
     SELECT a.build_id
     FROM public.env_build_assignments a