package state

import (
	"errors"
	"io/fs"
	"os"
	"path/filepath"
	"slices"
	"strings"
	"testing"
)

func TestWorkspaceObservationInventoryCanonicalArtifactsOnce(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	wantPaths := []ArtifactPath{
		"state.md",
		"brief.md",
		"spec.md",
		"decisions.md",
		"assumptions.md",
		"questions.md",
		"decision-coverage.md",
		"architecture.md",
		"plan.md",
		"tasks.md",
		"traceability.md",
		"eng-review.md",
		"test-plan.md",
		"gates.md",
		"evidence.md",
		"touched-files.md",
		"review.md",
		"seal.md",
		"strategy.md",
		"design-brief.md",
		"ai-spec.md",
		".devrites/principles.md",
	}
	for _, path := range wantPaths {
		body := []byte("# Artifact\n\nsubstantive content\n")
		switch path {
		case LedgerFile:
			body = []byte("- Phase: build\n")
		case ".devrites/principles.md":
			body = []byte("root principles\n")
		}
		writeObservationArtifact(t, root, slug, path, body)
	}
	writeFile(t, filepath.Join(root, "work", slug, "principles.md"), []byte("workspace principles decoy\n"))
	writeFile(t, filepath.Join(root, "work", slug, ".devrites", "principles.md"), []byte("workspace .devrites principles decoy\n"))
	physicalRoot, err := filepath.EvalSymlinks(root)
	if err != nil {
		t.Fatal(err)
	}
	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(physicalRoot, "work", slug))

	opens := make(map[ArtifactPath]int)
	reads := make(map[ArtifactPath]int)
	observation, err := observeWorkspace(physicalRoot, slug, func(stage observationStage, path ArtifactPath) error {
		switch stage {
		case observationBeforeOpen:
			opens[path]++
		case observationBeforeRead:
			reads[path]++
		}
		return nil
	})
	if err != nil {
		t.Fatal(err)
	}
	if observation.Slug() != slug {
		t.Fatalf("Slug() = %q, want %q", observation.Slug(), slug)
	}
	facts := observation.Facts()
	gotPaths := make([]ArtifactPath, len(facts))
	for i, fact := range facts {
		gotPaths[i] = fact.Path()
	}
	if !slices.Equal(gotPaths, wantPaths) {
		t.Fatalf("Facts paths = %v, want %v", gotPaths, wantPaths)
	}
	for _, path := range wantPaths {
		if opens[path] != 1 || reads[path] != 1 {
			t.Errorf("%s opened/read = %d/%d, want 1/1", path, opens[path], reads[path])
		}
	}
	principles, ok := observation.Fact(".devrites/principles.md")
	if !ok || string(principles.Bytes()) != "root principles\n" {
		t.Fatalf("root principles fact = (%q, %v), want selected-root principles", principles.Bytes(), ok)
	}
}

func TestWorkspaceObservationPathAcceptsCanonicalRelativeOverride(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
	physicalRoot, err := filepath.EvalSymlinks(root)
	if err != nil {
		t.Fatal(err)
	}
	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(filepath.Base(physicalRoot), "work", slug))

	observation, err := ObserveWorkspace(physicalRoot, slug)
	if err != nil {
		t.Fatal(err)
	}
	if observation.Slug() != slug {
		t.Fatalf("Slug() = %q, want %q", observation.Slug(), slug)
	}
}

func TestWorkspaceObservationPathRejectsWorkspaceOverrideWhitespace(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
	physicalRoot, err := filepath.EvalSymlinks(root)
	if err != nil {
		t.Fatal(err)
	}
	canonical := filepath.Join(physicalRoot, "work", slug)
	tests := []struct {
		name     string
		override string
	}{
		{name: "leading", override: " " + canonical},
		{name: "trailing", override: canonical + " "},
	}

	for _, test := range tests {
		t.Run(test.name, func(t *testing.T) {
			t.Setenv("DEVRITES_WORKSPACE", test.override)
			observation, err := ObserveWorkspace(physicalRoot, slug)
			if observation != nil {
				t.Fatalf("observation = %+v, want nil", observation)
			}
			assertObservationFailure(t, err, ObservationWorkspaceInvalid, "workspace observation: workspace_invalid: workspace is unavailable; verify the selected logical workspace and canonical workspace override, then retry")
		})
	}
}

func TestWorkspaceObservationPathRejectsLeadingParentRelativeOverride(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
	physicalRoot, err := filepath.EvalSymlinks(root)
	if err != nil {
		t.Fatal(err)
	}
	rootParent := filepath.Dir(physicalRoot)
	override := filepath.Join("..", filepath.Base(rootParent), filepath.Base(physicalRoot), "work", slug)
	if filepath.IsAbs(override) || !strings.HasPrefix(override, ".."+string(filepath.Separator)) {
		t.Fatalf("override = %q, want leading-parent relative path", override)
	}
	if filepath.Clean(override) != override {
		t.Fatalf("filepath.Clean(%q) changed fixture", override)
	}
	if filepath.IsLocal(override) {
		t.Fatalf("filepath.IsLocal(%q) = true, want false", override)
	}
	want := filepath.Join(physicalRoot, "work", slug)
	if resolved := filepath.Join(rootParent, override); resolved != want {
		t.Fatalf("filepath.Join(%q, %q) = %q, want %q", rootParent, override, resolved, want)
	}
	t.Setenv("DEVRITES_WORKSPACE", override)

	observation, err := ObserveWorkspace(physicalRoot, slug)
	if observation != nil {
		t.Fatalf("observation = %+v, want nil", observation)
	}
	assertObservationFailure(t, err, ObservationWorkspaceInvalid, "workspace observation: workspace_invalid: workspace is unavailable; verify the selected logical workspace and canonical workspace override, then retry")
}

func TestWorkspaceObservationPathRejectsWorkspaceOverrideAliases(t *testing.T) {
	aliases := []struct {
		name string
		path func(root string) string
	}{
		{
			name: "in-root symlink alias",
			path: func(root string) string {
				return filepath.Join(root, "work", "alias")
			},
		},
		{
			name: "outside-root symlink alias",
			path: func(string) string {
				return filepath.Join(t.TempDir(), "alias")
			},
		},
	}
	overrides := []struct {
		name string
		path func(t *testing.T, root, slug, alias string) string
	}{
		{
			name: "direct absolute",
			path: func(_ *testing.T, _, _, alias string) string {
				return alias
			},
		},
		{
			name: "wrapped relative",
			path: func(t *testing.T, root, slug, alias string) string {
				aliasFromRootParent, err := filepath.Rel(filepath.Dir(root), alias)
				if err != nil {
					t.Fatal(err)
				}
				targetFromAliasParent, err := filepath.Rel(filepath.Dir(alias), filepath.Join(root, "work", slug))
				if err != nil {
					t.Fatal(err)
				}
				separator := string(filepath.Separator)
				return aliasFromRootParent + separator + ".." + separator + targetFromAliasParent
			},
		},
		{
			name: "wrapped absolute",
			path: func(t *testing.T, root, slug, alias string) string {
				targetFromAliasParent, err := filepath.Rel(filepath.Dir(alias), filepath.Join(root, "work", slug))
				if err != nil {
					t.Fatal(err)
				}
				separator := string(filepath.Separator)
				return alias + separator + ".." + separator + targetFromAliasParent
			},
		},
	}

	for _, aliasCase := range aliases {
		for _, overrideCase := range overrides {
			t.Run(aliasCase.name+"/"+overrideCase.name, func(t *testing.T) {
				root, slug := newObservationWorkspace(t)
				writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
				physicalRoot, err := filepath.EvalSymlinks(root)
				if err != nil {
					t.Fatal(err)
				}
				alias := aliasCase.path(physicalRoot)
				if err := os.Symlink(filepath.Join(physicalRoot, "work", slug), alias); err != nil {
					t.Fatal(err)
				}
				aliasInfo, err := os.Lstat(alias)
				if err != nil {
					t.Fatal(err)
				}
				if aliasInfo.Mode()&os.ModeSymlink == 0 {
					t.Fatalf("alias mode = %v, want symlink", aliasInfo.Mode())
				}
				t.Setenv("DEVRITES_WORKSPACE", overrideCase.path(t, physicalRoot, slug, alias))

				observation, err := ObserveWorkspace(physicalRoot, slug)
				if observation != nil {
					t.Fatalf("observation = %+v, want nil", observation)
				}
				assertObservationFailure(t, err, ObservationWorkspaceInvalid, "workspace observation: workspace_invalid: workspace is unavailable; verify the selected logical workspace and canonical workspace override, then retry")
			})
		}
	}
}

func TestWorkspaceObservationSymlinkClassifiesRootPrinciplesFinalLink(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
	target := filepath.Join(t.TempDir(), "principles.md")
	writeFile(t, target, []byte("outside principles\n"))
	if err := os.Symlink(target, filepath.Join(root, "principles.md")); err != nil {
		t.Fatal(err)
	}

	observation, err := ObserveWorkspace(root, slug)
	if err != nil {
		t.Fatal(err)
	}
	assertArtifactFact(t, observation, ".devrites/principles.md", ArtifactUnsafe, DiagnosticFinalSymlink, nil)
}

func TestWorkspaceObservationStateClassifiesCodesAndRetention(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
	writeObservationArtifact(t, root, slug, "spec.md", []byte("# Empty\n\n"))
	malformed := []byte("hostile-secret\xff\n")
	writeObservationArtifact(t, root, slug, "decisions.md", malformed)

	target := filepath.Join(t.TempDir(), "outside.md")
	if err := os.WriteFile(target, []byte("outside\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	if err := os.Symlink(target, observationArtifactPath(root, slug, "assumptions.md")); err != nil {
		t.Fatal(err)
	}
	if err := os.Mkdir(observationArtifactPath(root, slug, "questions.md"), 0o755); err != nil {
		t.Fatal(err)
	}
	writeObservationArtifact(t, root, slug, "decision-coverage.md", sizedMarkdown("coverage\n", (1<<20)+1))
	writeObservationArtifact(t, root, slug, "architecture.md", []byte("architecture\n"))
	writeObservationArtifact(t, root, slug, "plan.md", []byte("plan\n"))
	writeObservationArtifact(t, root, slug, "traceability.md", []byte{})
	present := []byte("# Tasks\n\n- [ ] retained\n")
	writeObservationArtifact(t, root, slug, "tasks.md", present)

	observation, err := observeWorkspace(root, slug, func(stage observationStage, path ArtifactPath) error {
		if stage == observationBeforeOpen && path == "architecture.md" {
			return fs.ErrPermission
		}
		if stage == observationBeforeRead && path == "plan.md" {
			return errors.New("hostile read failure at /physical/path")
		}
		return nil
	})
	if err != nil {
		t.Fatal(err)
	}

	assertArtifactFact(t, observation, "brief.md", ArtifactAbsent, "", nil)
	assertArtifactFact(t, observation, "spec.md", ArtifactEmpty, "", []byte("# Empty\n\n"))
	assertArtifactFact(t, observation, "decisions.md", ArtifactMalformed, DiagnosticMalformedMarkdown, malformed)
	assertArtifactFact(t, observation, "assumptions.md", ArtifactUnsafe, DiagnosticFinalSymlink, nil)
	assertArtifactFact(t, observation, "questions.md", ArtifactUnsafe, DiagnosticNonRegular, nil)
	assertArtifactFact(t, observation, "decision-coverage.md", ArtifactUnsafe, DiagnosticFileTooLarge, nil)
	assertArtifactFact(t, observation, "architecture.md", ArtifactUnreadable, DiagnosticPermissionDenied, nil)
	assertArtifactFact(t, observation, "plan.md", ArtifactUnreadable, DiagnosticReadFailure, nil)
	assertArtifactFact(t, observation, "tasks.md", ArtifactPresent, "", present)
	assertArtifactFact(t, observation, "traceability.md", ArtifactEmpty, "", []byte{})
	zeroByteFact, _ := observation.Fact("traceability.md")
	if zeroByteFact.Bytes() == nil {
		t.Fatal("zero-byte empty artifact did not retain a copied empty byte slice")
	}
}

func TestWorkspaceObservationSymlinkClassifiesParent(t *testing.T) {
	base := t.TempDir()
	target := t.TempDir()
	if err := os.WriteFile(filepath.Join(target, "spec.md"), []byte("content\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	if err := os.Symlink(target, filepath.Join(base, "nested")); err != nil {
		t.Fatal(err)
	}
	root, err := os.OpenRoot(base)
	if err != nil {
		t.Fatal(err)
	}
	defer func() { _ = root.Close() }()

	fact, _, err := observeArtifact(artifactLocation{
		path: ArtifactPath("spec.md"),
		root: root,
		name: "nested/spec.md",
	}, nil)
	if err != nil {
		t.Fatal(err)
	}
	if fact.State() != ArtifactUnsafe {
		t.Fatalf("State() = %q, want %q", fact.State(), ArtifactUnsafe)
	}
	diagnostic, ok := fact.Diagnostic()
	if !ok || diagnostic.Code != DiagnosticParentSymlink {
		t.Fatalf("Diagnostic() = (%+v, %v), want parent symlink", diagnostic, ok)
	}
	if fact.Bytes() != nil {
		t.Fatalf("Bytes() = %q, want nil", fact.Bytes())
	}
}

func TestWorkspaceObservationDefensiveCopies(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	body := []byte("- Phase: build\n")
	writeObservationArtifact(t, root, slug, LedgerFile, body)
	observation, err := ObserveWorkspace(root, slug)
	if err != nil {
		t.Fatal(err)
	}

	facts := observation.Facts()
	facts[0].path = "mutated.md"
	facts[0].state = ArtifactUnsafe
	facts[0].bytes[0] = 'X'
	facts[0] = ArtifactFact{}

	fact, ok := observation.Fact(LedgerFile)
	if !ok {
		t.Fatal("Fact(state.md) returned ok=false")
	}
	returned := fact.Bytes()
	returned[0] = 'Y'
	fresh, ok := observation.Fact(LedgerFile)
	if !ok || fresh.Path() != LedgerFile || fresh.State() != ArtifactPresent || !slices.Equal(fresh.Bytes(), body) {
		t.Fatalf("fresh fact = (%q, %q, %q, %v), want retained state fact", fresh.Path(), fresh.State(), fresh.Bytes(), ok)
	}
}

func TestWorkspaceObservationUnknownLookupHasNoSideEffects(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
	callbacks := 0
	observation, err := observeWorkspace(root, slug, func(observationStage, ArtifactPath) error {
		callbacks++
		return nil
	})
	if err != nil {
		t.Fatal(err)
	}
	beforeCallbacks := callbacks
	beforeFacts := observation.Facts()

	fact, ok := observation.Fact("not-in-inventory.md")
	if ok || fact.path != "" || fact.state != "" || fact.code != "" || fact.bytes != nil {
		t.Fatalf("Fact(uninventoried) = (%+v, %v), want zero/false", fact, ok)
	}
	if fact.Bytes() != nil {
		t.Fatalf("zero fact Bytes() = %q, want nil", fact.Bytes())
	}
	if diagnostic, diagnosticOK := fact.Diagnostic(); diagnosticOK || diagnostic != (ArtifactDiagnostic{}) {
		t.Fatalf("zero fact Diagnostic() = (%+v, %v), want zero/false", diagnostic, diagnosticOK)
	}
	if callbacks != beforeCallbacks || !slices.EqualFunc(observation.Facts(), beforeFacts, equalArtifactFact) {
		t.Fatal("uninventoried lookup performed I/O or mutated the observation")
	}
}

func TestWorkspaceObservationStateMissingPreservesCallerOrderAndSelectedDiagnostics(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
	writeObservationArtifact(t, root, slug, "brief.md", []byte("# Heading\n"))
	writeObservationArtifact(t, root, slug, "spec.md", []byte("bad\x00markdown"))
	writeObservationArtifact(t, root, slug, "plan.md", []byte("real\n"))
	observation, err := ObserveWorkspace(root, slug)
	if err != nil {
		t.Fatal(err)
	}

	required := []ArtifactPath{"plan.md", "spec.md", "questions.md", "brief.md"}
	missing, diagnostics := observation.Missing(required)
	wantMissing := []ArtifactPath{"spec.md", "questions.md", "brief.md"}
	if !slices.Equal(missing, wantMissing) {
		t.Fatalf("Missing() paths = %v, want %v", missing, wantMissing)
	}
	wantDiagnostics := []ArtifactDiagnostic{{Path: "spec.md", State: ArtifactMalformed, Code: DiagnosticMalformedMarkdown}}
	if !slices.Equal(diagnostics, wantDiagnostics) {
		t.Fatalf("Missing() diagnostics = %+v, want %+v", diagnostics, wantDiagnostics)
	}
}

func TestWorkspaceObservationDisclosureRejectsInvalidWorkspace(t *testing.T) {
	root := filepath.Join(t.TempDir(), "hostile-root-secret", ".devrites")
	observation, err := ObserveWorkspace(root, "missing")
	if observation != nil {
		t.Fatalf("observation = %+v, want nil", observation)
	}
	assertObservationFailure(t, err, ObservationWorkspaceInvalid, "workspace observation: workspace_invalid: workspace is unavailable; verify the selected logical workspace and canonical workspace override, then retry")
	if strings.Contains(err.Error(), root) || strings.Contains(err.Error(), "hostile-root-secret") {
		t.Fatalf("error disclosed physical input: %v", err)
	}
}

func TestWorkspaceObservationRejectsCanonicalWorkspaceSymlinkWithoutDisclosure(t *testing.T) {
	for _, test := range []struct {
		name   string
		target func(t *testing.T, root string) string
	}{
		{
			name: "inside root",
			target: func(t *testing.T, root string) string {
				t.Helper()
				return filepath.Join(root, "retained-target-secret")
			},
		},
		{
			name: "outside root",
			target: func(t *testing.T, _ string) string {
				t.Helper()
				return filepath.Join(t.TempDir(), "retained-target-secret")
			},
		},
	} {
		t.Run(test.name, func(t *testing.T) {
			root := filepath.Join(t.TempDir(), ".devrites")
			slug := "linked"
			target := test.target(t, root)
			writeFile(t, filepath.Join(target, LedgerFile), []byte("- Phase: build\ntarget-content-secret\n"))
			if err := os.MkdirAll(filepath.Join(root, "work"), 0o755); err != nil {
				t.Fatal(err)
			}
			workspace := filepath.Join(root, "work", slug)
			if err := os.Symlink(target, workspace); err != nil {
				t.Fatal(err)
			}
			t.Setenv("DEVRITES_WORKSPACE", "")

			observation, err := ObserveWorkspace(root, slug)
			if observation != nil {
				t.Fatalf("observation = %+v, want nil", observation)
			}
			assertObservationFailure(t, err, ObservationWorkspaceInvalid, "workspace observation: workspace_invalid: workspace is unavailable; verify the selected logical workspace and canonical workspace override, then retry")
			if strings.Contains(err.Error(), target) || strings.Contains(err.Error(), "retained-target-secret") || strings.Contains(err.Error(), "target-content-secret") {
				t.Fatalf("error disclosed target path or content: %v", err)
			}
		})
	}
}

func TestWorkspaceObservationRootRejectsIdentityChanges(t *testing.T) {
	for _, tc := range []struct {
		name   string
		mutate func(t *testing.T, root, slug string)
	}{
		{
			name: "root replaced",
			mutate: func(t *testing.T, root, slug string) {
				t.Helper()
				if err := os.Rename(root, root+"-moved"); err != nil {
					t.Fatal(err)
				}
				// Replace with a regular file so OpenRoot fails closed on every
				// platform, including Windows directory file-ID reuse across
				// rename/recreate of an empty directory at the same path.
				if err := os.WriteFile(root, []byte("replaced-root\n"), 0o644); err != nil {
					t.Fatal(err)
				}
			},
		},
		{
			name: "workspace replaced",
			mutate: func(t *testing.T, root, slug string) {
				t.Helper()
				workspace := filepath.Join(root, "work", slug)
				if err := os.Rename(workspace, workspace+"-moved"); err != nil {
					t.Fatal(err)
				}
				if err := os.WriteFile(workspace, []byte("replaced-workspace\n"), 0o644); err != nil {
					t.Fatal(err)
				}
			},
		},
	} {
		t.Run(tc.name, func(t *testing.T) {
			root, slug := newObservationWorkspace(t)
			writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
			calls := 0
			observation, err := observeWorkspace(root, slug, func(stage observationStage, _ ArtifactPath) error {
				if stage == observationAfterResolve {
					calls++
					tc.mutate(t, root, slug)
				}
				return nil
			})
			if calls != 1 {
				t.Fatalf("after-resolve calls = %d, want 1", calls)
			}
			if observation != nil {
				t.Fatalf("observation = %+v, want nil", observation)
			}
			assertObservationFailure(t, err, ObservationWorkspaceInvalid, "workspace observation: workspace_invalid: workspace is unavailable; verify the selected logical workspace and canonical workspace override, then retry")
		})
	}
}

func TestWorkspaceObservationLimitsPerFile(t *testing.T) {
	for _, tc := range []struct {
		name      string
		size      int
		wantState ArtifactState
		wantCode  DiagnosticCode
		wantBytes int
	}{
		{name: "exactly one MiB", size: 1 << 20, wantState: ArtifactPresent, wantBytes: 1 << 20},
		{name: "one MiB plus one", size: (1 << 20) + 1, wantState: ArtifactUnsafe, wantCode: DiagnosticFileTooLarge},
	} {
		t.Run(tc.name, func(t *testing.T) {
			root, slug := newObservationWorkspace(t)
			writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
			writeObservationArtifact(t, root, slug, "ai-spec.md", sizedMarkdown("optional input\n", tc.size))
			observation, err := ObserveWorkspace(root, slug)
			if err != nil {
				t.Fatal(err)
			}
			fact, ok := observation.Fact("ai-spec.md")
			if !ok || fact.State() != tc.wantState || len(fact.Bytes()) != tc.wantBytes {
				t.Fatalf("ai-spec fact = (%q, %d bytes, %v), want (%q, %d bytes)", fact.State(), len(fact.Bytes()), ok, tc.wantState, tc.wantBytes)
			}
			diagnostic, diagnosticOK := fact.Diagnostic()
			if tc.wantCode == "" {
				if diagnosticOK {
					t.Fatalf("Diagnostic() = %+v, want none", diagnostic)
				}
			} else if !diagnosticOK || diagnostic.Code != tc.wantCode {
				t.Fatalf("Diagnostic() = (%+v, %v), want %q", diagnostic, diagnosticOK, tc.wantCode)
			}
		})
	}
}

func TestWorkspaceObservationLimitsAggregateIncludingLaterOptionalFacts(t *testing.T) {
	for _, tc := range []struct {
		name     string
		overflow bool
	}{
		{name: "exactly eight MiB"},
		{name: "eight MiB plus one in later optional fact", overflow: true},
	} {
		t.Run(tc.name, func(t *testing.T) {
			root, slug := newObservationWorkspace(t)
			paths := []ArtifactPath{LedgerFile, "brief.md", "spec.md", "decisions.md", "assumptions.md", "questions.md", "decision-coverage.md", "strategy.md"}
			for _, path := range paths {
				prefix := "retained content\n"
				if path == LedgerFile {
					prefix = "- Phase: build\n"
				}
				writeObservationArtifact(t, root, slug, path, sizedMarkdown(prefix, 1<<20))
			}
			if tc.overflow {
				writeObservationArtifact(t, root, slug, "ai-spec.md", []byte("x"))
			}

			observation, err := ObserveWorkspace(root, slug)
			if !tc.overflow {
				if err != nil || observation == nil {
					t.Fatalf("ObserveWorkspace() = (%+v, %v), want observation", observation, err)
				}
				return
			}
			if observation != nil {
				t.Fatalf("observation = %+v, want nil", observation)
			}
			assertObservationFailure(t, err, ObservationAggregateTooLarge, "workspace observation: aggregate_too_large: retained content exceeds the 8 MiB aggregate limit; reduce retained Markdown below 8 MiB, then retry")
		})
	}
}

func TestWorkspaceObservationLimitsCountEmptyAndMalformedBytes(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	presentPaths := []ArtifactPath{LedgerFile, "brief.md", "decisions.md", "assumptions.md", "questions.md", "decision-coverage.md", "strategy.md"}
	for _, path := range presentPaths {
		prefix := "retained content\n"
		if path == LedgerFile {
			prefix = "- Phase: build\n"
		}
		writeObservationArtifact(t, root, slug, path, sizedMarkdown(prefix, 1<<20))
	}
	writeObservationArtifact(t, root, slug, "design-brief.md", bytesOf(' ', 1<<20))
	writeObservationArtifact(t, root, slug, "ai-spec.md", []byte{0xff})

	observation, err := ObserveWorkspace(root, slug)
	if observation != nil {
		t.Fatalf("observation = %+v, want nil", observation)
	}
	assertObservationFailure(t, err, ObservationAggregateTooLarge, "workspace observation: aggregate_too_large: retained content exceeds the 8 MiB aggregate limit; reduce retained Markdown below 8 MiB, then retry")
}

func TestWorkspaceObservationConcurrentChangeOutranksCallbackErrorsAfterDetectedMutation(t *testing.T) {
	sentinel := errors.New("sentinel callback failure")
	for _, stage := range []observationStage{
		observationAfterInspect,
		observationBeforeOpen,
		observationBeforeRead,
		observationAfterRead,
	} {
		t.Run(observationStageName(stage), func(t *testing.T) {
			root, slug := newObservationWorkspace(t)
			writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
			writeObservationArtifact(t, root, slug, "brief.md", []byte("before\n"))
			artifactPath := observationArtifactPath(root, slug, "brief.md")
			calls := make(map[observationStage]int)

			observation, err := observeWorkspace(root, slug, func(current observationStage, artifact ArtifactPath) error {
				if artifact != "brief.md" {
					return nil
				}
				calls[current]++
				if current != stage {
					return nil
				}
				writeFile(t, artifactPath, []byte("detectably larger content\n"))
				return sentinel
			})
			if observation != nil {
				t.Fatalf("observation = %+v, want nil", observation)
			}
			assertObservationFailure(t, err, ObservationConcurrentChange, "workspace observation: concurrent_change: workspace changed during acquisition; retry")
			assertSingleObservationAttempt(t, calls, stage)
		})
	}
}

func TestWorkspaceObservationConcurrentChangeRejectsDetectedArtifactChangesWithoutRetry(t *testing.T) {
	for _, tc := range []struct {
		name   string
		stage  observationStage
		setup  func(t *testing.T, path string)
		mutate func(t *testing.T, path string)
	}{
		{
			name:   "appearance",
			stage:  observationAfterInspect,
			setup:  func(*testing.T, string) {},
			mutate: func(t *testing.T, path string) { writeFile(t, path, []byte("appeared\n")) },
		},
		{
			name:  "disappearance",
			stage: observationBeforeOpen,
			setup: func(t *testing.T, path string) { writeFile(t, path, []byte("before\n")) },
			mutate: func(t *testing.T, path string) {
				if err := os.Remove(path); err != nil {
					t.Fatal(err)
				}
			},
		},
		{
			name:  "identity replacement",
			stage: observationBeforeOpen,
			setup: func(t *testing.T, path string) { writeFile(t, path, []byte("before\n")) },
			mutate: func(t *testing.T, path string) {
				if err := os.Rename(path, path+".old"); err != nil {
					t.Fatal(err)
				}
				writeFile(t, path, []byte("after!\n"))
			},
		},
		{
			name:  "type change",
			stage: observationBeforeOpen,
			setup: func(t *testing.T, path string) { writeFile(t, path, []byte("before\n")) },
			mutate: func(t *testing.T, path string) {
				if err := os.Remove(path); err != nil {
					t.Fatal(err)
				}
				if err := os.Mkdir(path, 0o755); err != nil {
					t.Fatal(err)
				}
			},
		},
		{
			name:   "size change",
			stage:  observationBeforeOpen,
			setup:  func(t *testing.T, path string) { writeFile(t, path, []byte("before\n")) },
			mutate: func(t *testing.T, path string) { writeFile(t, path, []byte("larger content\n")) },
		},
		{
			name:  "replacement after read",
			stage: observationAfterRead,
			setup: func(t *testing.T, path string) { writeFile(t, path, []byte("before\n")) },
			mutate: func(t *testing.T, path string) {
				if err := os.Rename(path, path+".old"); err != nil {
					t.Fatal(err)
				}
				writeFile(t, path, []byte("after!\n"))
			},
		},
	} {
		t.Run(tc.name, func(t *testing.T) {
			root, slug := newObservationWorkspace(t)
			writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
			artifactPath := observationArtifactPath(root, slug, "brief.md")
			tc.setup(t, artifactPath)
			stageCalls := make(map[observationStage]int)
			mutated := false
			observation, err := observeWorkspace(root, slug, func(stage observationStage, path ArtifactPath) error {
				if path != "brief.md" {
					return nil
				}
				stageCalls[stage]++
				if !mutated && stage == tc.stage {
					mutated = true
					tc.mutate(t, artifactPath)
				}
				return nil
			})
			if !mutated {
				t.Fatal("target artifact was not mutated")
			}
			assertSingleObservationAttempt(t, stageCalls, tc.stage)
			if observation != nil {
				t.Fatalf("observation = %+v, want nil", observation)
			}
			assertObservationFailure(t, err, ObservationConcurrentChange, "workspace observation: concurrent_change: workspace changed during acquisition; retry")
		})
	}
}

func TestWorkspaceObservationConcurrentChangeDoesNotClaimSameSizeOrTransientDetection(t *testing.T) {
	t.Run("same identity and size", func(t *testing.T) {
		root, slug := newObservationWorkspace(t)
		writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
		before := []byte("before\n")
		after := []byte("after!\n")
		writeObservationArtifact(t, root, slug, "brief.md", before)
		artifactPath := observationArtifactPath(root, slug, "brief.md")
		observation, err := observeWorkspace(root, slug, func(stage observationStage, artifact ArtifactPath) error {
			if stage == observationAfterRead && artifact == "brief.md" {
				writeFile(t, artifactPath, after)
			}
			return nil
		})
		if err != nil {
			if observation != nil {
				t.Fatalf("observation = %+v with error %v, want nil", observation, err)
			}
			assertObservationFailure(t, err, ObservationConcurrentChange, "workspace observation: concurrent_change: workspace changed during acquisition; retry")
			return
		}
		fact, ok := observation.Fact("brief.md")
		if !ok || fact.State() != ArtifactPresent || (!slices.Equal(fact.Bytes(), before) && !slices.Equal(fact.Bytes(), after)) {
			t.Fatalf("successful same-size acquisition returned incoherent fact: state=%q bytes=%q ok=%v", fact.State(), fact.Bytes(), ok)
		}
	})

	t.Run("transient appearance between probes", func(t *testing.T) {
		root, slug := newObservationWorkspace(t)
		writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
		artifactPath := observationArtifactPath(root, slug, "brief.md")
		observation, err := observeWorkspace(root, slug, func(stage observationStage, artifact ArtifactPath) error {
			if stage == observationAfterInspect && artifact == "brief.md" {
				writeFile(t, artifactPath, []byte("transient\n"))
				if removeErr := os.Remove(artifactPath); removeErr != nil {
					t.Fatal(removeErr)
				}
			}
			return nil
		})
		if err != nil {
			if observation != nil {
				t.Fatalf("observation = %+v with error %v, want nil", observation, err)
			}
			assertObservationFailure(t, err, ObservationConcurrentChange, "workspace observation: concurrent_change: workspace changed during acquisition; retry")
			return
		}
		fact, ok := observation.Fact("brief.md")
		if !ok || fact.State() != ArtifactAbsent || fact.Bytes() != nil {
			t.Fatalf("successful transient acquisition returned incoherent fact: state=%q bytes=%q ok=%v", fact.State(), fact.Bytes(), ok)
		}
	})
}

func TestWorkspaceObservationConcurrentChangeDoesNotApplyAfterReturn(t *testing.T) {
	root, slug := newObservationWorkspace(t)
	writeObservationArtifact(t, root, slug, LedgerFile, []byte("- Phase: build\n"))
	before := []byte("retained before return\n")
	writeObservationArtifact(t, root, slug, "brief.md", before)

	observation, err := ObserveWorkspace(root, slug)
	if err != nil {
		t.Fatal(err)
	}
	writeObservationArtifact(t, root, slug, "brief.md", []byte("changed after return\n"))

	fact, ok := observation.Fact("brief.md")
	if !ok || fact.State() != ArtifactPresent || !slices.Equal(fact.Bytes(), before) {
		t.Fatalf("post-return mutation changed retained fact: state=%q bytes=%q ok=%v", fact.State(), fact.Bytes(), ok)
	}
}

func assertSingleObservationAttempt(t *testing.T, calls map[observationStage]int, trigger observationStage) {
	t.Helper()
	if calls[trigger] != 1 {
		t.Fatalf("triggering stage %s calls = %d, want 1", observationStageName(trigger), calls[trigger])
	}
	for stage, count := range calls {
		if count > 1 {
			t.Fatalf("stage %s calls = %d, want at most 1", observationStageName(stage), count)
		}
	}
}

func observationStageName(stage observationStage) string {
	switch stage {
	case observationAfterResolve:
		return "after_resolve"
	case observationAfterInspect:
		return "after_inspect"
	case observationBeforeOpen:
		return "before_open"
	case observationBeforeRead:
		return "before_read"
	case observationAfterRead:
		return "after_read"
	case observationBeforeFinalSweep:
		return "before_final_sweep"
	default:
		return "unknown"
	}
}

func assertArtifactFact(t *testing.T, observation *WorkspaceObservation, path ArtifactPath, state ArtifactState, code DiagnosticCode, wantBytes []byte) {
	t.Helper()
	fact, ok := observation.Fact(path)
	if !ok {
		t.Fatalf("Fact(%q) returned ok=false", path)
	}
	if fact.Path() != path || fact.State() != state || !slices.Equal(fact.Bytes(), wantBytes) {
		t.Fatalf("Fact(%q) = (path %q, state %q, bytes %q), want (%q, %q, %q)", path, fact.Path(), fact.State(), fact.Bytes(), path, state, wantBytes)
	}
	diagnostic, diagnosticOK := fact.Diagnostic()
	if code == "" {
		if diagnosticOK || diagnostic != (ArtifactDiagnostic{}) {
			t.Fatalf("Fact(%q).Diagnostic() = (%+v, %v), want zero/false", path, diagnostic, diagnosticOK)
		}
		return
	}
	wantDiagnostic := ArtifactDiagnostic{Path: path, State: state, Code: code}
	if !diagnosticOK || diagnostic != wantDiagnostic {
		t.Fatalf("Fact(%q).Diagnostic() = (%+v, %v), want (%+v, true)", path, diagnostic, diagnosticOK, wantDiagnostic)
	}
}

func assertObservationFailure(t *testing.T, err error, want ObservationFailure, wantMessage string) {
	t.Helper()
	if err == nil || err.Error() != wantMessage {
		t.Fatalf("error = %v, want %q", err, wantMessage)
	}
	var failure ObservationFailure
	if !errors.As(err, &failure) || failure != want {
		t.Fatalf("errors.As(%v) = %q, want %q", err, failure, want)
	}
}

func equalArtifactFact(left, right ArtifactFact) bool {
	return left.path == right.path && left.state == right.state && left.code == right.code && slices.Equal(left.bytes, right.bytes)
}

func newObservationWorkspace(t *testing.T) (string, string) {
	t.Helper()
	root := filepath.Join(t.TempDir(), ".devrites")
	slug := "observed"
	if err := os.MkdirAll(filepath.Join(root, "work", slug), 0o755); err != nil {
		t.Fatal(err)
	}
	return root, slug
}

func writeObservationArtifact(t *testing.T, root, slug string, path ArtifactPath, body []byte) {
	t.Helper()
	writeFile(t, observationArtifactPath(root, slug, path), body)
}

func observationArtifactPath(root, slug string, path ArtifactPath) string {
	if path == ".devrites/principles.md" {
		return filepath.Join(root, "principles.md")
	}
	return filepath.Join(root, "work", slug, filepath.FromSlash(string(path)))
}

func writeFile(t *testing.T, path string, body []byte) {
	t.Helper()
	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
		t.Fatal(err)
	}
	if err := os.WriteFile(path, body, 0o644); err != nil {
		t.Fatal(err)
	}
}

func sizedMarkdown(prefix string, size int) []byte {
	body := bytesOf('x', size)
	copy(body, prefix)
	return body
}

func bytesOf(value byte, size int) []byte {
	body := make([]byte, size)
	for i := range body {
		body[i] = value
	}
	return body
}