feat(resource): Stage B config resources: block + up-saga resources phase (spec 27)

- internal/config: additive ResourceDecl on Project, cross-ref validated (uses
  targets a declared shared instance, kind supported by the engine, no
  (engine,kind,name) collision); forward-tolerant to unknown keys.
- internal/orchestrate: new 'resources' saga phase provisions every declared
  resource via the engine Provisioner under the flock, records ledger + event,
  and REPORTS drift without auto-dropping. Wired into BuildUp after the implicit
  postgres provision phase; gated on --no-provision. Provision phase untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gustavobertoi

internal/config/model.go

@@ -103,7 +103,24 @@ type Project struct {
 	Kind       string             `yaml:"kind" validate:"required,eq=Project"`
 	Name       string             `yaml:"name" validate:"required,dsname"`
 	Services   map[string]Service `yaml:"services" validate:"required,dive"`
-	Hooks      Hooks              `yaml:"hooks"` // spec 11 — project-scope lifecycle hooks
+	Hooks      Hooks              `yaml:"hooks"`                     // spec 11 — project-scope lifecycle hooks
+	Resources  []ResourceDecl     `yaml:"resources" validate:"dive"` // spec 27 — declarative data-plane resources
+}
+
+// ResourceDecl is one declarative data-plane resource a project needs INSIDE a
+// shared engine (spec 27): a database, bucket, lifecycle policy, queue, … `up`
+// provisions each idempotently. The block is additive and forward-tolerant
+// (unknown keys are ignored, never fatal); the cross-ref resolver checks `uses`
+// targets a declared shared instance, `kind` is one the engine supports, and no
+// two resources collide on (engine, name). Removing an entry NEVER auto-drops the
+// resource (Q-RESOURCE-DRIFT) — teardown is always explicit + confirmed.
+type ResourceDecl struct {
+	Uses        string         `yaml:"uses" validate:"required"` // workspace.shared.<name>
+	Kind        string         `yaml:"kind" validate:"required"` // database|user|bucket|lifecycle|queue|stream|topic
+	Name        string         `yaml:"name"`                     // engine-level identifier (default: project name)
+	Engine      string         `yaml:"engine"`                   // optional; inferred from the uses target's template
+	Params      map[string]any `yaml:"params"`                   // kind-specific knobs
+	Credentials string         `yaml:"credentials" validate:"omitempty,oneof=predictable generated"`
 }
 
 // Service is one container in a project stack.

internal/config/resources_test.go

@@ -0,0 +1,119 @@
+package config
+
+import (
+	"strings"
+	"testing"
+)
+
+const resWorkspace = `apiVersion: devstack/v1
+kind: Workspace
+name: acme
+shared:
+  postgres: { template: postgres }
+  minio: { template: minio }
+projects:
+  - { name: api, path: api }
+`
+
+func projectWithResources(body string) map[string]string {
+	return map[string]string{
+		"workspace.yaml":    resWorkspace,
+		"api/devstack.yaml": "apiVersion: devstack/v1\nkind: Project\nname: api\nservices:\n  api: { template: t }\n" + body,
+	}
+}
+
+func TestResourcesValid(t *testing.T) {
+	root := writeTree(t, projectWithResources(`resources:
+  - { uses: workspace.shared.postgres, kind: database }
+  - { uses: workspace.shared.minio, kind: bucket, name: api-uploads, credentials: generated }
+  - { uses: workspace.shared.minio, kind: lifecycle, name: api-uploads, params: { expireDays: 7 } }
+`))
+	m, err := LoadAt(root)
+	if err != nil {
+		t.Fatalf("LoadAt: %v", err)
+	}
+	rs := m.Projects["api"].Resources
+	if len(rs) != 3 {
+		t.Fatalf("resources = %d, want 3", len(rs))
+	}
+	if rs[0].Kind != "database" || rs[0].Uses != "workspace.shared.postgres" {
+		t.Errorf("resource[0] = %+v", rs[0])
+	}
+	if rs[1].Credentials != "generated" || rs[1].Name != "api-uploads" {
+		t.Errorf("resource[1] = %+v", rs[1])
+	}
+}
+
+func TestResourcesUnknownShared(t *testing.T) {
+	root := writeTree(t, projectWithResources(`resources:
+  - { uses: workspace.shared.ghost, kind: database }
+`))
+	_, err := LoadAt(root)
+	if err == nil || !strings.Contains(err.Error(), "ghost") {
+		t.Fatalf("want an unknown-shared error naming ghost, got %v", err)
+	}
+}
+
+func TestResourcesBadUsesForm(t *testing.T) {
+	root := writeTree(t, projectWithResources(`resources:
+  - { uses: postgres, kind: database }
+`))
+	_, err := LoadAt(root)
+	if err == nil || !strings.Contains(err.Error(), "workspace.shared.<name>") {
+		t.Fatalf("want a uses-form error, got %v", err)
+	}
+}
+
+func TestResourcesKindNotSupportedByEngine(t *testing.T) {
+	// A bucket on postgres is rejected (postgres provisioner lists no bucket kind).
+	root := writeTree(t, projectWithResources(`resources:
+  - { uses: workspace.shared.postgres, kind: bucket }
+`))
+	_, err := LoadAt(root)
+	if err == nil || !strings.Contains(err.Error(), "not supported by engine") {
+		t.Fatalf("want a kind/engine error, got %v", err)
+	}
+}
+
+func TestResourcesDuplicateCollision(t *testing.T) {
+	// Two databases defaulting to the project name collide on (engine, name).
+	root := writeTree(t, projectWithResources(`resources:
+  - { uses: workspace.shared.postgres, kind: database }
+  - { uses: workspace.shared.postgres, kind: database }
+`))
+	_, err := LoadAt(root)
+	if err == nil || !strings.Contains(err.Error(), "duplicate database resource") {
+		t.Fatalf("want a duplicate-resource error, got %v", err)
+	}
+}
+
+func TestResourcesBadCredentials(t *testing.T) {
+	root := writeTree(t, projectWithResources(`resources:
+  - { uses: workspace.shared.postgres, kind: database, credentials: bogus }
+`))
+	_, err := LoadAt(root)
+	if err == nil || !strings.Contains(err.Error(), "predictable, generated") {
+		t.Fatalf("want a credentials oneof error, got %v", err)
+	}
+}
+
+func TestResourcesForwardTolerantUnknownKeys(t *testing.T) {
+	// Unknown keys inside a resource entry are ignored, never fatal (additive block).
+	root := writeTree(t, projectWithResources(`resources:
+  - { uses: workspace.shared.postgres, kind: database, futureField: whatever }
+`))
+	if _, err := LoadAt(root); err != nil {
+		t.Fatalf("unknown resource keys must be tolerated, got %v", err)
+	}
+}
+
+func TestResourcesExplicitEngineOverride(t *testing.T) {
+	// An explicit engine that supports the kind is accepted even if it differs from
+	// the inferred template (forward-tolerance for custom shared templates).
+	root := writeTree(t, projectWithResources(`resources:
+  - { uses: workspace.shared.postgres, kind: bucket, engine: minio, name: api-uploads }
+`))
+	if _, err := LoadAt(root); err != nil {
+		t.Fatalf("explicit valid engine override should pass, got %v", err)
+	}
+}

internal/config/validate.go

@@ -9,6 +9,8 @@ import (
 	"time"
 
 	"github.com/go-playground/validator/v10"
+
+	"github.com/open-source-cloud/devstack/internal/resource"
 )
 
 // dsNameRE is the safe-identifier pattern for workspace/project/service/alias
@@ -64,9 +66,61 @@ func validateModel(m *Model, ws *source, projSrc map[string]*source) error {
 	if err := validateProfiles(m, ws); err != nil {
 		return err
 	}
+	if err := validateResources(m, projSrc); err != nil {
+		return err
+	}
 	return detectCycles(m)
 }
 
+// validateResources checks the spec-27 declarative `resources:` block on each
+// project: every `uses` targets a declared shared instance, `kind` is one the
+// target engine's provisioner supports (for known engines — unknown/custom
+// engines are forward-tolerant), and no two resources collide on (engine, name)
+// within a project (tenant-scoping: names are per-project). Positioned to the
+// project file.
+func validateResources(m *Model, projSrc map[string]*source) error {
+	for _, pname := range sortedKeys(m.Projects) {
+		p := m.Projects[pname]
+		src := projSrc[pname]
+		seen := map[string]bool{}
+		for i, d := range p.Resources {
+			r := parseRef(d.Uses)
+			if r.kind != refShared || r.attr != "" {
+				return src.errAt(fmt.Sprintf("$.resources[%d].uses", i),
+					"resources: uses %q must be a shared service reference of the form workspace.shared.<name>", d.Uses)
+			}
+			svc, ok := m.Workspace.Shared[r.name]
+			if !ok {
+				return src.errAt(fmt.Sprintf("$.resources[%d].uses", i),
+					"resources: shared service %q does not exist%s", r.name, suggest(r.name, m.SharedNames()))
+			}
+			engine := d.Engine
+			if engine == "" {
+				engine = svc.Template // inferred: the shared template name == its engine capability
+			}
+			if !resource.SupportsKind(engine, d.Kind) {
+				return src.errAt(fmt.Sprintf("$.resources[%d].kind", i),
+					"resources: kind %q is not supported by engine %q (supported: %s)",
+					d.Kind, engine, strings.Join(resource.Kinds(engine), ", "))
+			}
+			name := d.Name
+			if name == "" {
+				name = pname // default: the project name
+			}
+			// Collide on (engine, kind, name): a bucket and its lifecycle may share a
+			// name (they reference the same object), but two databases of the same
+			// name may not.
+			key := engine + "\x00" + d.Kind + "\x00" + name
+			if seen[key] {
+				return src.errAt(fmt.Sprintf("$.resources[%d].name", i),
+					"resources: duplicate %s resource %q on engine %q (a project may declare it once)", d.Kind, name, engine)
+			}
+			seen[key] = true
+		}
+	}
+	return nil
+}
+
 // validateProfiles checks the spec-12 service-slice config: every group's
 // services reference a real service, and defaultProfile (if set) names a defined
 // group (or the reserved "all"). Positioned to the workspace file.