Merge pull request #90 from LAA-Software-Engineering/feat/apply-exit-code-3-78

feat(apply): exit code 3 for plan/apply deployment conflicts (#78)

Author: leo-aa88

README.md

@@ -148,7 +148,7 @@ Notes:
 | `-o` / `--output` | `table`, `json`, or `yaml` |
 | `--no-color` | ASCII-friendly validate output |
 
-Exit codes are summarized in **section 11.2** of [`docs/DESIGN_DOC.md`](docs/DESIGN_DOC.md) (`0` success, `2` validation, `4` execution, `5` policy denial, …).
+Exit codes are summarized in **section 11.2** of [`docs/DESIGN_DOC.md`](docs/DESIGN_DOC.md) (`0` success, `2` validation, **`3` plan/apply conflict** when deployment state changed after `plan`, `4` execution, `5` policy denial, …).
 
 ---
 

internal/apply/applier.go

@@ -50,6 +50,9 @@ func (a *Applier) ApplyPlan(ctx context.Context, env string, g *spec.ProjectGrap
 	at = at.UTC()
 
 	run := func(ctx context.Context, dep state.DeploymentStore) error {
+		if err := assertDeploymentBaseline(ctx, dep, env, projectName, p); err != nil {
+			return err
+		}
 		return executePlan(ctx, dep, env, p, at, projectName, projectVersion)
 	}
 	if tx, ok := a.Deploy.(state.TransactionalDeployment); ok {

internal/apply/applier_test.go

@@ -127,3 +127,47 @@ func TestApplyPlan_deleteRemovesRow(t *testing.T) {
 		t.Fatalf("want project only, got %+v", list)
 	}
 }
+
+func TestApplyPlan_rejectsStaleDeploymentBaseline(t *testing.T) {
+	ctx := context.Background()
+	st, err := sqlite.Open(ctx, filepath.Join(t.TempDir(), "apply-stale.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+
+	pl := plan.NewPlanner(st)
+	ap := NewApplier(st)
+	t0 := time.Date(2026, 4, 11, 10, 0, 0, 0, time.UTC)
+
+	gFull := graphWithAgent()
+	pCreate, err := pl.ComputePlan(ctx, "dev", gFull)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(pCreate.Operations) == 0 || pCreate.DeploymentBaseline == "" {
+		t.Fatalf("want non-empty plan with baseline, got ops=%d baseline=%q", len(pCreate.Operations), pCreate.DeploymentBaseline)
+	}
+	if err := ap.ApplyPlan(ctx, "dev", gFull, pCreate, t0); err != nil {
+		t.Fatal(err)
+	}
+
+	gOnly := minimalGraph()
+	pDelete, err := pl.ComputePlan(ctx, "dev", gOnly)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if pDelete.DeploymentBaseline == "" {
+		t.Fatal("missing baseline")
+	}
+
+	// Simulate another writer: deployment no longer matches the fingerprint embedded in pDelete.
+	if err := st.DeleteAppliedResource(ctx, "dev", spec.ResourceID{Kind: spec.KindAgent, Name: "rev"}); err != nil {
+		t.Fatal(err)
+	}
+
+	err = ap.ApplyPlan(ctx, "dev", gOnly, pDelete, t0.Add(time.Hour))
+	if !errors.Is(err, ErrDeploymentStateChanged) {
+		t.Fatalf("want ErrDeploymentStateChanged, got %v", err)
+	}
+}

internal/apply/baseline.go

@@ -0,0 +1,29 @@
+package apply
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/plan"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state"
+)
+
+func assertDeploymentBaseline(ctx context.Context, dep state.DeploymentStore, env, projectName string, p *plan.Plan) error {
+	if p == nil {
+		return errors.New("apply: nil plan")
+	}
+	want := strings.TrimSpace(p.DeploymentBaseline)
+	if want == "" {
+		// Plans from [plan.Planner.ComputePlan] always set a baseline; empty skips the check for tests/synthetics.
+		return nil
+	}
+	got, err := plan.DeploymentStateFingerprint(ctx, dep, env, projectName)
+	if err != nil {
+		return err
+	}
+	if got != want {
+		return ErrDeploymentStateChanged
+	}
+	return nil
+}

internal/apply/errors.go

@@ -0,0 +1,7 @@
+package apply
+
+import "errors"
+
+// ErrDeploymentStateChanged means SQLite deployment state changed after the plan was computed.
+// Scripts should re-run plan, then apply. Surfaces as CLI exit code 3 (issue #78).
+var ErrDeploymentStateChanged = errors.New("deployment state changed since plan was computed; re-run plan")

internal/cli/apply.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"bufio"
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -33,14 +34,18 @@ then persist changes unless you decline at the prompt.
 Use --auto-approve to skip confirmation, or set ` + EnvAutoApprove + `=1 for non-interactive runs
 (CI, scripts). When stdin is not a terminal and the plan is non-empty, one of those is required.
 
+The plan is computed, then (after any prompt) applied in a single run. If another writer changes the
+same state database between those steps—e.g. a second terminal applying the same --state file while
+this process waits at the confirmation prompt—apply fails with exit code 3.
+
 The state database defaults to .agentic/state.db under --project, or project.spec.state.dsn,
 unless overridden by global --state.
 
 Exit codes (section 11.2):
   0 — success (including nothing to apply)
   1 — generic failure (e.g. cannot open SQLite, non-interactive without approval, cancelled)
   2 — validation failure (invalid project), or non-table output without approval when the plan is non-empty
-  3 — plan/apply conflict (reserved for optimistic concurrency; not used in this MVP)`,
+  3 — plan/apply conflict: deployment store changed after this plan was computed (re-run plan, then apply)`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			_ = args
 			return runApply(cmd, autoApprove)
@@ -122,6 +127,9 @@ func runApply(cmd *cobra.Command, flagAutoApprove bool) error {
 
 	at := time.Now().UTC()
 	if err := apply.NewApplier(st).ApplyPlan(ctx, env, graph, pl, at); err != nil {
+		if errors.Is(err, apply.ErrDeploymentStateChanged) {
+			return NewExitError(ExitPlanApplyConflict, err)
+		}
 		return fmt.Errorf("apply: %w", err)
 	}
 

internal/cli/apply_test.go

@@ -9,6 +9,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/apply"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state/sqlite"
 )
 
@@ -188,3 +189,10 @@ func TestApply_jsonAutoApprove_validJSON(t *testing.T) {
 		t.Fatalf("operations: %v", m["operations"])
 	}
 }
+
+func TestApply_exitCode_planApplyConflict(t *testing.T) {
+	err := NewExitError(ExitPlanApplyConflict, apply.ErrDeploymentStateChanged)
+	if ExitCodeOf(err) != ExitPlanApplyConflict {
+		t.Fatalf("exit code = %d want %d", ExitCodeOf(err), ExitPlanApplyConflict)
+	}
+}

internal/cli/diff.go

@@ -150,7 +150,7 @@ func runDiff(cmd *cobra.Command, args []string) error {
 		if op == nil {
 			return writeDiffInSync(cmd, env, dsn, id, g)
 		}
-		pl = &plan.Plan{Operations: []plan.Operation{*op}, Risk: plan.RiskSummary{}}
+		pl = &plan.Plan{Operations: []plan.Operation{*op}, Risk: plan.RiskSummary{}, DeploymentBaseline: pl.DeploymentBaseline}
 	}
 
 	entries := buildDiffEntries(pl, appliedByKey)

internal/cli/plan.go

@@ -121,7 +121,7 @@ func planJSONModel(env, dsn string, p *plan.Plan) map[string]any {
 		}
 		ops = append(ops, entry)
 	}
-	return map[string]any{
+	m := map[string]any{
 		"environment": env,
 		"statePath":   dsn,
 		"summary": map[string]any{
@@ -132,6 +132,10 @@ func planJSONModel(env, dsn string, p *plan.Plan) map[string]any {
 		"operations": ops,
 		"risk":       riskStrings(p),
 	}
+	if p != nil && p.DeploymentBaseline != "" {
+		m["deploymentBaseline"] = p.DeploymentBaseline
+	}
+	return m
 }
 
 func riskStrings(p *plan.Plan) []string {

internal/plan/fingerprint.go

@@ -0,0 +1,58 @@
+package plan
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state"
+)
+
+// DeploymentStateFingerprint returns a stable SHA-256 hex digest of deployment rows for env.
+// It covers every applied_resources row for env (kind, name, spec hash, normalized JSON) and
+// the applied_projects row for (env, projectName), or a sentinel when that row is missing.
+// Used for optimistic concurrency between plan and apply (issue #78).
+func DeploymentStateFingerprint(ctx context.Context, dep state.DeploymentStore, env, projectName string) (string, error) {
+	if dep == nil {
+		return "", errors.New("plan: nil deployment store")
+	}
+	env = strings.TrimSpace(env)
+	projectName = strings.TrimSpace(projectName)
+	if env == "" || projectName == "" {
+		return "", errors.New("plan: empty env or project name")
+	}
+	list, err := dep.ListAppliedResourcesByEnv(ctx, env)
+	if err != nil {
+		return "", err
+	}
+	sort.Slice(list, func(i, j int) bool {
+		if list[i].Kind != list[j].Kind {
+			return list[i].Kind < list[j].Kind
+		}
+		return list[i].Name < list[j].Name
+	})
+	var b strings.Builder
+	for _, r := range list {
+		fmt.Fprintf(&b, "%s\x00%s\x00%s\x00%s\n", r.Kind, r.Name, r.SpecHash, r.NormalizedSpecJSON)
+	}
+	proj, err := dep.GetAppliedProject(ctx, env, projectName)
+	switch {
+	case err != nil && errors.Is(err, sql.ErrNoRows):
+		b.WriteString("applied_projects\x00MISSING\n")
+	case err != nil:
+		return "", err
+	default:
+		if proj == nil {
+			b.WriteString("applied_projects\x00MISSING\n")
+		} else {
+			fmt.Fprintf(&b, "applied_projects\x00%s\x00%s\x00%s\n", proj.ProjectName, proj.Env, proj.Version)
+		}
+	}
+	sum := sha256.Sum256([]byte(b.String()))
+	return hex.EncodeToString(sum[:]), nil
+}