feat(deployer): configurable per-workload deploy strategy (blue-green for built sources)

Add a deploy_strategy field to each source's config blob — "" (default),
"recreate", or "blue-green" — validated in each source's Validate and read on
the deploy path. No new DB column, no migration: the field rides inside the
existing SourceConfig JSON and every existing workload decodes "" to its
historical behavior (image -> blue-green, others -> recreate).

The real gap this closes: dockerfile and static stopped the old container
before creating the new one on every redeploy — a downtime window image never
had. Their blue-green branch now:
- names the new "green" container with a unique suffix so it coexists with the
  still-serving blue (plumbed into both the container name AND the proxy
  forwardHost);
- skips the collision teardown that destroyed blue early;
- gates green — an HTTP readiness probe (deps.Health.Check) when a healthcheck
  is configured, else the existing liveness window;
- swaps the route via a pure upsert (no pre-DeleteRoute) so NPM repoints in
  place with no gap;
- persists green into the single runtime-state row BEFORE reaping blue, so a
  crash mid-swap can never orphan green or leave the row pointing at a removed
  container (state.go/teardown.go/reconcile.go stay untouched).

image honors explicit "recreate" (reap existing containers after pull, before
cutover); its default blue-green path is unchanged. compose stays
stack-managed and rejects "blue-green" at Validate so the contract is honest.
static forces recreate for storage-backed deno sites — blue-green would mount
the same RW volume into both containers at once.

Shared helper internal/workload/plugin/strategy.go (ValidateStrategy +
BuildGreenName). Backend-only (phase 1); the field is usable today via the
app's advanced-JSON editor — a friendly toggle + i18n follow in phase 2.
Tests: ValidateStrategy matrix, per-source Validate (incl. the empty-key
backward-compat lock), and effectiveStrategy defaults + the deno gate. Design
+ adversarial review: docs/plans/DEPLOY_STRATEGY_PLAN.md.

internal/workload/plugin/source/compose/compose.go

@@ -28,6 +28,12 @@ import (
 type Config struct {
 	ComposeYAML        string `json:"compose_yaml"`
 	ComposeProjectName string `json:"compose_project_name"`
+	// DeployStrategy is accepted for parity with the other sources but a
+	// compose stack only supports recreate (docker compose up -d
+	// --remove-orphans). "" and "recreate" are honored; "blue-green" is
+	// rejected at Validate so the contract is honest in the UI rather than
+	// silently accepting a value compose can't deliver.
+	DeployStrategy string `json:"deploy_strategy,omitempty"`
 }
 
 type source struct{}
@@ -70,6 +76,11 @@ func (*source) Validate(cfg json.RawMessage) error {
 	if strings.TrimSpace(c.ComposeYAML) == "" {
 		return fmt.Errorf("compose source: compose_yaml is required")
 	}
+	// allowBlueGreen=false: a whole-stack blue-green is not implemented, so
+	// reject it here rather than silently running recreate.
+	if err := plugin.ValidateStrategy(c.DeployStrategy, false); err != nil {
+		return fmt.Errorf("compose source: %w", err)
+	}
 	spec, err := stack.Parse(c.ComposeYAML)
 	if err != nil {
 		return fmt.Errorf("compose source: parse yaml: %w", err)

internal/workload/plugin/source/compose/strategy_test.go

@@ -0,0 +1,37 @@
+package compose
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+const validComposeYAML = "services:\n  web:\n    image: nginx:alpine\n    ports:\n      - \"80\"\n"
+
+func composeCfg(strategy string) json.RawMessage {
+	m := map[string]any{"compose_yaml": validComposeYAML}
+	if strategy != "" {
+		m["deploy_strategy"] = strategy
+	}
+	b, _ := json.Marshal(m)
+	return b
+}
+
+func TestValidate_Strategy_RejectsBlueGreen(t *testing.T) {
+	cases := []struct {
+		strategy string
+		wantErr  bool
+	}{
+		{"", false},          // backward-compat
+		{"recreate", false},  // the only thing compose can do
+		{"blue-green", true}, // not supported for a whole stack
+		{"rolling", true},
+	}
+	for _, c := range cases {
+		t.Run("strategy="+c.strategy, func(t *testing.T) {
+			err := (&source{}).Validate(composeCfg(c.strategy))
+			if (err != nil) != c.wantErr {
+				t.Fatalf("Validate(strategy=%q) err=%v, wantErr=%v", c.strategy, err, c.wantErr)
+			}
+		})
+	}
+}

internal/workload/plugin/source/dockerfile/deploy.go

@@ -48,6 +48,11 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 		return fmt.Errorf("dockerfile source: decode config: %w", err)
 	}
 
+	// bg selects the zero-downtime path: a unique green name so the new
+	// container coexists with the still-serving blue, an in-place route
+	// upsert, and blue reaped only AFTER green is persisted + routed.
+	bg := effectiveStrategy(cfg) == plugin.StrategyBlueGreen
+
 	prev, prevContainer, err := loadState(deps, w)
 	if err != nil {
 		return err
@@ -224,6 +229,13 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 	}
 
 	containerName := containerNameFor(w)
+	if bg {
+		// Unique green name so the new container coexists with the still-
+		// serving blue one — the deterministic name would collide on
+		// Docker's per-daemon unique-name constraint. This name is also the
+		// proxy forwardHost below, so green receives traffic after cutover.
+		containerName = plugin.BuildGreenName(containerName, time.Now())
+	}
 
 	// Per-face proxy labels (Traefik consumes these; NPM ignores them).
 	labels := map[string]string{}
@@ -254,8 +266,16 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 
 	containerID, err := deps.Docker.CreateContainer(ctx, cc)
 	if err != nil {
-		// Name conflict — best-effort cleanup of any prior container
-		// (by ID first; by name as a fallback) and one retry.
+		if bg {
+			// Green has a unique name, so this is a genuine create failure, not
+			// a name conflict — must NOT remove the still-serving blue.
+			updateStatus(deps, w, "failed", latestSHA,
+				sanitizeError(fmt.Sprintf("create container: %v", err), token))
+			return fmt.Errorf("create container: %w", err)
+		}
+		// recreate: the deterministic name may still be held by the prior
+		// container — best-effort cleanup (by ID first; by name fallback) and
+		// one retry. This is the recreate downtime window.
 		if prevContainerID != "" {
 			deps.Docker.StopContainer(ctx, prevContainerID, 10)
 			deps.Docker.RemoveContainer(ctx, prevContainerID, true)
@@ -308,6 +328,22 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 		return fmt.Errorf("container not running: %s", logMsg)
 	}
 
+	// Blue-green readiness gate: the 3s window above only proves green did not
+	// crash, not that it is SERVING. Before swapping the route, probe green's
+	// healthcheck over the network (when configured) so traffic never flips to
+	// a not-yet-listening container. On failure, remove green and leave blue +
+	// its route untouched — a non-disruptive rollback. recreate skips this (it
+	// already removed blue, so there is no live fallback to protect).
+	if bg && cfg.Healthcheck != "" && deps.Health != nil {
+		healthURL := fmt.Sprintf("http://%s:%d%s", containerName, cfg.Port, cfg.Healthcheck)
+		if herr := deps.Health.Check(ctx, healthURL); herr != nil {
+			deps.Docker.RemoveContainer(ctx, containerID, true)
+			updateStatus(deps, w, "failed", latestSHA,
+				sanitizeError(fmt.Sprintf("readiness check %s: %v", cfg.Healthcheck, herr), token))
+			return fmt.Errorf("readiness check failed: %w", herr)
+		}
+	}
+
 	// Resolve proxy target: in-network DNS by default, NPM-remote
 	// override uses (settings.ServerIP, hostPort).
 	forwardHost := containerName
@@ -329,7 +365,12 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 	// in-place so traffic shifts atomically over to the new container.
 	proxyRouteID := prevProxyRouteID
 	if domain != "" {
-		if prevProxyRouteID != "" {
+		// Blue-green relies on ConfigureRoute being an upsert-by-FQDN (NPM
+		// finds the host by domain and repoints it in place, gap-free), so we
+		// must NOT delete blue's route first — that would open a window.
+		// recreate already removed blue, so the pre-delete is harmless there
+		// but kept to preserve its exact prior behavior.
+		if !bg && prevProxyRouteID != "" {
 			deps.Proxy.DeleteRoute(ctx, prevProxyRouteID)
 		}
 		routeID, rerr := deps.Proxy.ConfigureRoute(ctx, domain, forwardHost, forwardPort, proxy.RouteOptions{
@@ -347,10 +388,12 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 		}
 	}
 
-	// Drop the previous container only after the new one is healthy
-	// + routed. Different-ID-than-previous tells us we created a
-	// fresh one (vs returning the same ID via UpsertContainer reuse).
-	if prevContainerID != "" && prevContainerID != containerID {
+	// recreate: drop the previous container now that the new one is healthy +
+	// routed. Blue-green DEFERS this until AFTER saveState (below) so the
+	// persisted single row always points at a running container — a crash
+	// between cutover and saveState must not orphan green or leave the row
+	// pointing at a reaped blue (which the reconciler would then flag failed).
+	if !bg && prevContainerID != "" && prevContainerID != containerID {
 		deps.Docker.StopContainer(ctx, prevContainerID, 10)
 		deps.Docker.RemoveContainer(ctx, prevContainerID, true)
 	}
@@ -384,6 +427,14 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 		return fmt.Errorf("persist deploy state: %w", err)
 	}
 
+	// Blue-green: green is now persisted in the single row AND serving behind
+	// the swapped route — only now is it safe to reap blue. (recreate already
+	// removed blue before saveState.)
+	if bg && prevContainerID != "" && prevContainerID != containerID {
+		deps.Docker.StopContainer(ctx, prevContainerID, 10)
+		deps.Docker.RemoveContainer(ctx, prevContainerID, true)
+	}
+
 	publishEvent(deps, w, "deployed")
 	dispatchBuildNotification(deps, w, domain, "deployed", "")
 

internal/workload/plugin/source/dockerfile/dockerfile.go

@@ -64,6 +64,23 @@ type Config struct {
 	// git provider as a commit status (pending/success/failure) on the
 	// built SHA. Best-effort — a reporting failure never fails a deploy.
 	ReportCommitStatus bool `json:"report_commit_status"`
+
+	// DeployStrategy selects how a redeploy cuts over. "" (default) and
+	// "recreate" stop the old container before starting the new one (a brief
+	// downtime window). "blue-green" starts the new build alongside the old,
+	// gates it, swaps the proxy route in place, then reaps the old —
+	// zero-downtime under NPM. Validated via plugin.ValidateStrategy.
+	DeployStrategy string `json:"deploy_strategy,omitempty"`
+}
+
+// effectiveStrategy resolves the configured strategy for the dockerfile
+// source. Empty maps to recreate — the source's historical behavior — so
+// existing workloads are unchanged.
+func effectiveStrategy(cfg Config) string {
+	if cfg.DeployStrategy == "" {
+		return plugin.StrategyRecreate
+	}
+	return cfg.DeployStrategy
 }
 
 type source struct{}
@@ -120,6 +137,9 @@ func (*source) Validate(cfg json.RawMessage) error {
 			return fmt.Errorf("dockerfile source: %q must not contain '..'", p)
 		}
 	}
+	if err := plugin.ValidateStrategy(c.DeployStrategy, true); err != nil {
+		return fmt.Errorf("dockerfile source: %w", err)
+	}
 	return nil
 }
 

internal/workload/plugin/source/dockerfile/strategy_test.go

@@ -0,0 +1,49 @@
+package dockerfile
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/alexei/tinyforge/internal/workload/plugin"
+)
+
+// validCfg is the smallest config that passes the non-strategy checks, so a
+// test isolates the deploy_strategy behavior.
+func validCfg(strategy string) json.RawMessage {
+	m := map[string]any{"repo_owner": "o", "repo_name": "r", "port": 8080}
+	if strategy != "" {
+		m["deploy_strategy"] = strategy
+	}
+	b, _ := json.Marshal(m)
+	return b
+}
+
+func TestValidate_Strategy(t *testing.T) {
+	cases := []struct {
+		strategy string
+		wantErr  bool
+	}{
+		{"", false}, // backward-compat: no key -> valid
+		{"recreate", false},
+		{"blue-green", false}, // dockerfile supports blue-green
+		{"rolling", true},     // reserved, not yet implemented
+		{"junk", true},
+	}
+	for _, c := range cases {
+		t.Run("strategy="+c.strategy, func(t *testing.T) {
+			err := (&source{}).Validate(validCfg(c.strategy))
+			if (err != nil) != c.wantErr {
+				t.Fatalf("Validate(strategy=%q) err=%v, wantErr=%v", c.strategy, err, c.wantErr)
+			}
+		})
+	}
+}
+
+func TestEffectiveStrategy_Default(t *testing.T) {
+	if got := effectiveStrategy(Config{}); got != plugin.StrategyRecreate {
+		t.Fatalf("empty strategy = %q, want recreate (historical default)", got)
+	}
+	if got := effectiveStrategy(Config{DeployStrategy: plugin.StrategyBlueGreen}); got != plugin.StrategyBlueGreen {
+		t.Fatalf("explicit blue-green = %q, want blue-green", got)
+	}
+}

internal/workload/plugin/source/image/image.go

@@ -40,6 +40,21 @@ type Config struct {
 	MemoryLimit  int               `json:"memory_limit"`  // megabytes; 0 = unlimited
 	DefaultTag   string            `json:"default_tag"`   // tag used when intent.Reference is empty
 	MaxInstances int               `json:"max_instances"` // simultaneous containers to keep; 0/1 = strict blue-green
+	// DeployStrategy selects how a redeploy cuts over. "" defaults to the
+	// image source's native zero-downtime blue-green; "recreate" reaps the
+	// old container before the new one comes up (opt-in downtime). Validated
+	// via plugin.ValidateStrategy. Orthogonal to MaxInstances.
+	DeployStrategy string `json:"deploy_strategy,omitempty"`
+}
+
+// effectiveStrategy resolves the configured strategy for the image source.
+// Empty maps to blue-green so every existing image workload keeps its
+// current zero-downtime behavior byte-for-byte.
+func effectiveStrategy(cfg Config) string {
+	if cfg.DeployStrategy == "" {
+		return plugin.StrategyBlueGreen
+	}
+	return cfg.DeployStrategy
 }
 
 // VolumeMount mirrors the existing store.Volume scope shape but as a flat
@@ -88,6 +103,9 @@ func (*source) Validate(cfg json.RawMessage) error {
 	if c.Port < 0 || c.Port > 65535 {
 		return fmt.Errorf("image source: port must be 0-65535")
 	}
+	if err := plugin.ValidateStrategy(c.DeployStrategy, true); err != nil {
+		return fmt.Errorf("image source: %w", err)
+	}
 	for i, v := range c.Volumes {
 		if strings.TrimSpace(v.Target) == "" {
 			return fmt.Errorf("image source: volumes[%d].target is required", i)
@@ -189,6 +207,33 @@ func (*source) Deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload,
 		return fmt.Errorf("image source: ensure network: %w", err)
 	}
 
+	// recreate strategy (opt-in): tear down the existing containers BEFORE
+	// the new one comes up — the operator chose a downtime window. The
+	// default blue-green path skips this; its new container coexists with
+	// the old and the proxy route swaps atomically (enforceMaxInstances
+	// reaps the old AFTER cutover). Reaped here (after a successful pull, so
+	// a pull failure doesn't take the workload down for nothing). On a
+	// later create/health/route failure the recreate path has no blue to
+	// fall back to — inherent to recreate, distinct from blue-green's
+	// non-disruptive rollbackNew.
+	if effectiveStrategy(cfg) == plugin.StrategyRecreate {
+		for _, c := range existing {
+			if c.ContainerID != "" {
+				_ = deps.Docker.RemoveContainer(ctx, c.ContainerID, true)
+			}
+			if c.ProxyRouteID != "" {
+				_ = deps.Proxy.DeleteRoute(ctx, c.ProxyRouteID)
+			}
+			if delErr := deps.Store.DeleteContainer(c.ID); delErr != nil && !errors.Is(delErr, store.ErrNotFound) {
+				slog.Warn("image source: recreate reap old row", "workload", w.ID, "row", c.ID, "error", delErr)
+			}
+		}
+		if len(existing) > 0 {
+			slog.Info("image source: recreate strategy reaped old containers before cutover",
+				"workload", w.ID, "count", len(existing))
+		}
+	}
+
 	// Unique-per-deploy name so the new container can run alongside the
 	// old one. The suffix is monotonic ms; collisions are not a real
 	// concern for human-driven or webhook-driven deploys.

internal/workload/plugin/source/image/strategy_test.go

@@ -0,0 +1,49 @@
+package image
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/alexei/tinyforge/internal/workload/plugin"
+)
+
+func imageCfg(strategy string) json.RawMessage {
+	m := map[string]any{"image": "registry.example.com/o/app", "port": 8080}
+	if strategy != "" {
+		m["deploy_strategy"] = strategy
+	}
+	b, _ := json.Marshal(m)
+	return b
+}
+
+func TestValidate_Strategy(t *testing.T) {
+	cases := []struct {
+		strategy string
+		wantErr  bool
+	}{
+		{"", false},
+		{"recreate", false},
+		{"blue-green", false},
+		{"rolling", true},
+		{"junk", true},
+	}
+	for _, c := range cases {
+		t.Run("strategy="+c.strategy, func(t *testing.T) {
+			err := (&source{}).Validate(imageCfg(c.strategy))
+			if (err != nil) != c.wantErr {
+				t.Fatalf("Validate(strategy=%q) err=%v, wantErr=%v", c.strategy, err, c.wantErr)
+			}
+		})
+	}
+}
+
+func TestEffectiveStrategy_DefaultsToBlueGreen(t *testing.T) {
+	// image's historical default is blue-green — empty must NOT flip it to
+	// recreate (the load-bearing per-source default).
+	if got := effectiveStrategy(Config{}); got != plugin.StrategyBlueGreen {
+		t.Fatalf("empty strategy = %q, want blue-green (image default)", got)
+	}
+	if got := effectiveStrategy(Config{DeployStrategy: plugin.StrategyRecreate}); got != plugin.StrategyRecreate {
+		t.Fatalf("explicit recreate = %q, want recreate", got)
+	}
+}

internal/workload/plugin/source/static/deploy.go

@@ -44,6 +44,12 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 		return fmt.Errorf("static source: decode config: %w", err)
 	}
 
+	// bg selects the zero-downtime path: a unique green name so the new
+	// container coexists with the still-serving blue, an in-place route
+	// upsert, and blue reaped only AFTER green is persisted + routed.
+	// effectiveStrategy forces recreate for storage-backed deno sites.
+	bg := effectiveStrategy(cfg) == plugin.StrategyBlueGreen
+
 	prev, prevContainer, err := loadState(deps, w)
 	if err != nil {
 		return err
@@ -238,6 +244,13 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 	}
 
 	containerName := containerNameFor(w)
+	if bg {
+		// Unique green name so the new container coexists with the still-
+		// serving blue one — the deterministic name would collide on
+		// Docker's per-daemon unique-name constraint. This name is also the
+		// proxy forwardHost below, so green receives traffic after cutover.
+		containerName = plugin.BuildGreenName(containerName, time.Now())
+	}
 
 	var mounts []mount.Mount
 	if cfg.StorageEnabled && mode == "deno" {
@@ -283,8 +296,16 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 
 	containerID, err := deps.Docker.CreateContainer(ctx, cc)
 	if err != nil {
-		// Container with this name might already exist — best-effort
-		// cleanup of any prior container by ID and by name, then retry.
+		if bg {
+			// Green has a unique name, so this is a genuine create failure, not
+			// a name conflict — must NOT remove the still-serving blue.
+			updateStatus(deps, w, "failed", latestSHA,
+				sanitizeError(fmt.Sprintf("create container: %v", err), token))
+			return fmt.Errorf("create container: %w", err)
+		}
+		// recreate: the deterministic name might still be held by the prior
+		// container — best-effort cleanup (by ID, then by name) and one retry.
+		// This is the recreate downtime window.
 		if prevContainerID != "" {
 			deps.Docker.StopContainer(ctx, prevContainerID, 10)
 			deps.Docker.RemoveContainer(ctx, prevContainerID, true)
@@ -353,7 +374,11 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 	// place so traffic shifts atomically.
 	proxyRouteID := prevProxyRouteID
 	if domain != "" {
-		if prevProxyRouteID != "" {
+		// Blue-green relies on ConfigureRoute being an upsert-by-FQDN (NPM
+		// repoints the host in place, gap-free), so we must NOT delete blue's
+		// route first. recreate already removed blue, so the pre-delete is
+		// harmless there but kept to preserve its exact prior behavior.
+		if !bg && prevProxyRouteID != "" {
 			deps.Proxy.DeleteRoute(ctx, prevProxyRouteID)
 		}
 		routeID, rerr := deps.Proxy.ConfigureRoute(ctx, domain, forwardHost, forwardPort, proxy.RouteOptions{
@@ -371,8 +396,12 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 		}
 	}
 
-	// Drop the old container if a fresh one was created (different ID).
-	if prevContainerID != "" && prevContainerID != containerID {
+	// recreate: drop the old container now that the new one is healthy +
+	// routed. Blue-green DEFERS this until AFTER saveState (below) so the
+	// persisted single row always points at a running container — a crash
+	// between cutover and saveState must not orphan green or leave the row
+	// pointing at a reaped blue (which the reconciler would then flag failed).
+	if !bg && prevContainerID != "" && prevContainerID != containerID {
 		deps.Docker.StopContainer(ctx, prevContainerID, 10)
 		deps.Docker.RemoveContainer(ctx, prevContainerID, true)
 	}
@@ -409,6 +438,14 @@ func deploy(ctx context.Context, deps plugin.Deps, w plugin.Workload, intent plu
 		return fmt.Errorf("persist deploy state: %w", err)
 	}
 
+	// Blue-green: green is now persisted in the single row AND serving behind
+	// the swapped route — only now is it safe to reap blue. (recreate already
+	// removed blue before saveState.)
+	if bg && prevContainerID != "" && prevContainerID != containerID {
+		deps.Docker.StopContainer(ctx, prevContainerID, 10)
+		deps.Docker.RemoveContainer(ctx, prevContainerID, true)
+	}
+
 	publishEvent(deps, w, "deployed")
 
 	// updateStatus normally fires the terminal-state notification; the

internal/workload/plugin/source/static/static.go

@@ -41,6 +41,30 @@ type Config struct {
 	// git provider as a commit status (pending/success/failure) on the
 	// deployed SHA. Best-effort — a reporting failure never fails a deploy.
 	ReportCommitStatus bool `json:"report_commit_status"`
+
+	// DeployStrategy selects how a redeploy cuts over. "" (default) and
+	// "recreate" stop the old container before the new one comes up (a brief
+	// downtime window). "blue-green" starts the new container alongside the
+	// old, gates it, swaps the proxy route in place, then reaps the old —
+	// zero-downtime under NPM. Validated via plugin.ValidateStrategy.
+	DeployStrategy string `json:"deploy_strategy,omitempty"`
+}
+
+// effectiveStrategy resolves the configured strategy for the static source.
+// Empty maps to recreate — the source's historical behavior. Storage-backed
+// deno sites are forced to recreate even when blue-green is requested: a
+// blue-green overlap would mount the same RW named volume into BOTH
+// containers at once (a concurrent-writer window recreate never has, since
+// recreate stops blue before green starts).
+func effectiveStrategy(cfg Config) string {
+	s := cfg.DeployStrategy
+	if s == "" {
+		s = plugin.StrategyRecreate
+	}
+	if s == plugin.StrategyBlueGreen && cfg.StorageEnabled && cfg.Mode == "deno" {
+		return plugin.StrategyRecreate
+	}
+	return s
 }
 
 type source struct{}
@@ -78,6 +102,9 @@ func (*source) Validate(cfg json.RawMessage) error {
 	if c.Mode != "" && c.Mode != "static" && c.Mode != "deno" {
 		return fmt.Errorf("static source: mode must be \"static\" or \"deno\"")
 	}
+	if err := plugin.ValidateStrategy(c.DeployStrategy, true); err != nil {
+		return fmt.Errorf("static source: %w", err)
+	}
 	return nil
 }
 

internal/workload/plugin/source/static/strategy_test.go

@@ -0,0 +1,58 @@
+package static
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/alexei/tinyforge/internal/workload/plugin"
+)
+
+func validCfg(extra map[string]any) json.RawMessage {
+	m := map[string]any{"repo_owner": "o", "repo_name": "r"}
+	for k, v := range extra {
+		m[k] = v
+	}
+	b, _ := json.Marshal(m)
+	return b
+}
+
+func TestValidate_Strategy(t *testing.T) {
+	cases := []struct {
+		strategy string
+		wantErr  bool
+	}{
+		{"", false},
+		{"recreate", false},
+		{"blue-green", false},
+		{"rolling", true},
+		{"junk", true},
+	}
+	for _, c := range cases {
+		t.Run("strategy="+c.strategy, func(t *testing.T) {
+			err := (&source{}).Validate(validCfg(map[string]any{"deploy_strategy": c.strategy}))
+			if (err != nil) != c.wantErr {
+				t.Fatalf("Validate(strategy=%q) err=%v, wantErr=%v", c.strategy, err, c.wantErr)
+			}
+		})
+	}
+}
+
+func TestEffectiveStrategy_DefaultAndDenoGate(t *testing.T) {
+	if got := effectiveStrategy(Config{}); got != plugin.StrategyRecreate {
+		t.Fatalf("empty strategy = %q, want recreate", got)
+	}
+	if got := effectiveStrategy(Config{DeployStrategy: plugin.StrategyBlueGreen}); got != plugin.StrategyBlueGreen {
+		t.Fatalf("plain blue-green = %q, want blue-green", got)
+	}
+	// Storage-backed deno site requesting blue-green is forced to recreate to
+	// avoid a concurrent-writer overlap on the shared /app/data volume.
+	denoStorage := Config{DeployStrategy: plugin.StrategyBlueGreen, StorageEnabled: true, Mode: "deno"}
+	if got := effectiveStrategy(denoStorage); got != plugin.StrategyRecreate {
+		t.Fatalf("deno+storage blue-green = %q, want recreate (forced)", got)
+	}
+	// A deno site WITHOUT storage may use blue-green.
+	denoNoStorage := Config{DeployStrategy: plugin.StrategyBlueGreen, Mode: "deno"}
+	if got := effectiveStrategy(denoNoStorage); got != plugin.StrategyBlueGreen {
+		t.Fatalf("deno (no storage) blue-green = %q, want blue-green", got)
+	}
+}

internal/workload/plugin/strategy.go

@@ -0,0 +1,50 @@
+package plugin
+
+import (
+	"fmt"
+	"time"
+)
+
+// Deploy strategy values for a source's DeployStrategy config field.
+//
+//   - "" (empty)      — back-compat default; each source resolves it to its
+//     historical behavior (image -> blue-green, others -> recreate). Every
+//     pre-existing workload row decodes to this.
+//   - StrategyRecreate — stop the old container, then start the new one
+//     (a brief downtime window; what dockerfile/static/compose do today).
+//   - StrategyBlueGreen — start the new container alongside the old, gate it,
+//     swap the proxy route, then reap the old (zero-downtime under NPM).
+const (
+	StrategyRecreate  = "recreate"
+	StrategyBlueGreen = "blue-green"
+)
+
+// ValidateStrategy checks a deploy_strategy config value. "" is always valid
+// (the back-compat default). StrategyRecreate is always valid. StrategyBlueGreen
+// is valid only when the source supports it (allowBlueGreen) — compose passes
+// false because a whole-stack blue-green is not implemented. Reserved values
+// such as "rolling" are rejected until implemented so a config can't silently
+// claim a behavior the deployer won't honor.
+func ValidateStrategy(value string, allowBlueGreen bool) error {
+	switch value {
+	case "", StrategyRecreate:
+		return nil
+	case StrategyBlueGreen:
+		if allowBlueGreen {
+			return nil
+		}
+		return fmt.Errorf("deploy_strategy %q is not supported for this source kind; use \"recreate\"", value)
+	default:
+		return fmt.Errorf("invalid deploy_strategy %q (valid: \"\", %q, %q)", value, StrategyRecreate, StrategyBlueGreen)
+	}
+}
+
+// BuildGreenName appends a unique millisecond-hex suffix to a source's
+// otherwise-deterministic container name so a new "green" container can run
+// alongside the old "blue" during a blue-green cutover. Sources whose names
+// are deterministic (dockerfile, static) collide on Docker's per-daemon
+// unique-name constraint without this; the suffix lets both coexist until the
+// route swaps and blue is reaped. Mirrors the image source's ms-hex scheme.
+func BuildGreenName(base string, ts time.Time) string {
+	return fmt.Sprintf("%s-%x", base, ts.UnixMilli())
+}

internal/workload/plugin/strategy_test.go

@@ -0,0 +1,48 @@
+package plugin
+
+import (
+	"testing"
+	"time"
+)
+
+func TestValidateStrategy(t *testing.T) {
+	cases := []struct {
+		name           string
+		value          string
+		allowBlueGreen bool
+		wantErr        bool
+	}{
+		{"empty always ok (backward compat)", "", true, false},
+		{"empty ok when blue-green disallowed", "", false, false},
+		{"recreate ok", StrategyRecreate, true, false},
+		{"recreate ok when blue-green disallowed", StrategyRecreate, false, false},
+		{"blue-green ok when allowed", StrategyBlueGreen, true, false},
+		{"blue-green rejected when disallowed (compose)", StrategyBlueGreen, false, true},
+		{"reserved rolling rejected (allowed)", "rolling", true, true},
+		{"reserved rolling rejected (disallowed)", "rolling", false, true},
+		{"junk rejected", "banana", true, true},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			err := ValidateStrategy(c.value, c.allowBlueGreen)
+			if (err != nil) != c.wantErr {
+				t.Fatalf("ValidateStrategy(%q, %v) err=%v, wantErr=%v", c.value, c.allowBlueGreen, err, c.wantErr)
+			}
+		})
+	}
+}
+
+func TestBuildGreenName_UniqueSuffixAndDistinct(t *testing.T) {
+	base := "tf-build-app-1234abcd"
+	a := BuildGreenName(base, time.Unix(1000, 0))
+	b := BuildGreenName(base, time.Unix(2000, 0))
+	if a == base || b == base {
+		t.Fatal("green name must differ from the deterministic base")
+	}
+	if a == b {
+		t.Fatal("different timestamps must yield different green names")
+	}
+	if len(a) <= len(base) {
+		t.Fatalf("green name %q should extend the base %q", a, base)
+	}
+}