diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index c469b8cf2..0d3740b16 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -617,12 +617,11 @@ func (b *boot) loadCatalog(ctx context.Context, cfgPath string) { b.log.Info("model catalog loaded", "providers", len(catalog.Providers), "models", len(models)) } -// seedSoul writes the starter SOUL beside the config on first run, and upgrades -// a file that is still exactly a shipped template, so the identity a user can -// edit exists before the SOUL loader (#439) reads it. It runs on the full -// process's boot tail rather than in loadConfig: an offline command such as -// `-requeue` reads the config but must not write the operator's files. A -// failure is logged, not fatal -- the loader falls back to the embedded +// seedSoul writes the starter SOUL beside the config on first run, so the +// identity a user can edit exists before the SOUL loader (#439) reads it. It +// runs on the full process's boot tail rather than in loadConfig: an offline +// command such as `-requeue` reads the config but must not write the operator's +// files. A failure is logged, not fatal -- the loader falls back to the embedded // default, so a read-only config directory must not stop the process // (docs/prds/soul.md, "Prompt and failure contract"). func (b *boot) seedSoul(cfgPath string) { @@ -631,8 +630,7 @@ func (b *boot) seedSoul(cfgPath string) { b.log.Warn("soul: starter file unavailable", "err", err) return } - switch result.Action { - case configuration.SoulCreated, configuration.SoulUpgraded: + if result.Action == configuration.SoulCreated { b.log.Info("soul: starter file written", "path", result.Path, "action", result.Action) } } diff --git a/internal/domain/agent/soul.go b/internal/domain/agent/soul.go index 1ac9d819d..8596bd3a1 100644 --- a/internal/domain/agent/soul.go +++ b/internal/domain/agent/soul.go @@ -20,61 +20,26 @@ asked. Do not claim tools, files, memories, actions, or results you have not verified. Do not impersonate another assistant, provider, or vendor. ` -// SoulMatch classifies a SOUL body against the documents a build ships. -type SoulMatch int - -const ( - // SoulEdit is content no build shipped: a user edit, which must never be - // replaced. - SoulEdit SoulMatch = iota - // SoulCurrent is content identical to the build's Default once transport - // noise is normalised away; there is nothing to upgrade. - SoulCurrent - // SoulSuperseded is a body this build recognises as a shipped template - // that is not the current Default. It carries zero user intent, so it may - // be upgraded in place. - SoulSuperseded -) - -// SoulDocument is the set of SOUL bodies one build recognises as its own. -type SoulDocument struct { - // Default is written when no SOUL file exists, and replaces a superseded - // template during an upgrade. - Default string - // Legacy lists earlier shipped SOUL bodies this build still recognises. A - // file that matches one is an untouched scaffolding document rather than a - // user edit. The Default is always recognised and need not be repeated. - Legacy []string -} - // ShippedSoul returns the SOUL document this build ships. -func ShippedSoul() SoulDocument { - return SoulDocument{Default: DefaultSoul} +// +// Exactly one body is shipped, so the seeder recognises only this text as +// untouched scaffolding. A build that supersedes it adds the old body next to +// this one together with the in-place upgrade that consumes it; a branch that +// rewrites a file for matching a template no build ever shipped has no +// producer and must not be kept ahead of one. +func ShippedSoul() string { + return DefaultSoul } -// Match classifies a body against the build's shipped documents. +// SoulMatchesShipped reports whether content is the same body as shipped, once +// transport noise is normalised away. // // Comparison is on normalised content, so a CRLF checkout or an editor that // left trailing whitespace still matches the template it came from. Only a // body that is identical to a shipped document after that normalisation is // eligible for replacement; any other difference is treated as user intent. -func (d SoulDocument) Match(content string) SoulMatch { - if d.Default == "" { - return SoulEdit - } - normalized := normalizeSoul(content) - if normalized == normalizeSoul(d.Default) { - return SoulCurrent - } - for _, legacy := range d.Legacy { - if legacy == "" { - continue - } - if normalized == normalizeSoul(legacy) { - return SoulSuperseded - } - } - return SoulEdit +func SoulMatchesShipped(content, shipped string) bool { + return normalizeSoul(content) == normalizeSoul(shipped) } // normalizeSoul reduces a SOUL body to the content a user authored: a UTF-8 diff --git a/internal/domain/agent/soul_test.go b/internal/domain/agent/soul_test.go index 120693895..05ec1ac0a 100644 --- a/internal/domain/agent/soul_test.go +++ b/internal/domain/agent/soul_test.go @@ -6,11 +6,11 @@ func TestShippedSoulShipsAStarter(t *testing.T) { t.Parallel() shipped := ShippedSoul() - if shipped.Default == "" { - t.Fatal("ShippedSoul().Default is empty; first run would seed nothing") + if shipped == "" { + t.Fatal("ShippedSoul() is empty; first run would seed nothing") } - if got := shipped.Match(shipped.Default); got != SoulCurrent { - t.Fatalf("Match(shipped default) = %v, want SoulCurrent", got) + if !SoulMatchesShipped(shipped, shipped) { + t.Fatal("ShippedSoul() does not match itself") } } @@ -27,47 +27,45 @@ func TestShippedSoulIsIndependentOfPersonas(t *testing.T) { } } -func TestSoulMatch(t *testing.T) { +func TestSoulMatchesShippedNormalisesTransportNoise(t *testing.T) { t.Parallel() - const legacy = "# Archie\n\nOld starter identity.\n" - doc := SoulDocument{Default: "current\nidentity\n", Legacy: []string{legacy}} - + const shipped = "current\nidentity\n" tests := []struct { name string content string - want SoulMatch + want bool }{ - {name: "exact default", content: doc.Default, want: SoulCurrent}, - {name: "default with crlf", content: "current\r\nidentity\r\n", want: SoulCurrent}, - {name: "default with lone cr", content: "current\ridentity\r", want: SoulCurrent}, - {name: "default with trailing spaces", content: "current \nidentity\t\n", want: SoulCurrent}, - {name: "default with trailing blank lines", content: "current\nidentity\n\n\n", want: SoulCurrent}, - {name: "default with utf8 bom", content: "\ufeffcurrent\nidentity\n", want: SoulCurrent}, - {name: "legacy template", content: legacy, want: SoulSuperseded}, - {name: "legacy template with crlf", content: "# Archie\r\n\r\nOld starter identity.\r\n", want: SoulSuperseded}, - {name: "legacy template with trailing whitespace", content: "# Archie\n\nOld starter identity. \n", want: SoulSuperseded}, - {name: "an edited word", content: "current\nIDENTITY\n", want: SoulEdit}, - {name: "leading indent is content", content: "current\n identity\n", want: SoulEdit}, - {name: "one word removed", content: "current\n", want: SoulEdit}, - {name: "empty", content: "", want: SoulEdit}, - {name: "whitespace only", content: "\n\t \n", want: SoulEdit}, + {name: "exact", content: shipped, want: true}, + {name: "crlf", content: "current\r\nidentity\r\n", want: true}, + {name: "lone cr", content: "current\ridentity\r", want: true}, + {name: "trailing spaces", content: "current \nidentity\t\n", want: true}, + {name: "trailing blank lines", content: "current\nidentity\n\n\n", want: true}, + {name: "utf8 bom", content: "\ufeffcurrent\nidentity\n", want: true}, + {name: "an edited word", content: "current\nIDENTITY\n", want: false}, + {name: "leading indent is content", content: "current\n identity\n", want: false}, + {name: "one word removed", content: "current\n", want: false}, + {name: "empty", content: "", want: false}, + {name: "whitespace only", content: "\n\t \n", want: false}, } for _, test := range tests { t.Run(test.name, func(t *testing.T) { t.Parallel() - if got := doc.Match(test.content); got != test.want { - t.Fatalf("Match(%q) = %v, want %v", test.content, got, test.want) + if got := SoulMatchesShipped(test.content, shipped); got != test.want { + t.Fatalf("SoulMatchesShipped(%q, %q) = %v, want %v", test.content, shipped, got, test.want) } }) } } -func TestSoulMatchTreatsMissingDefaultAsEdited(t *testing.T) { +// A body is a user edit until a build actually ships it. Recognising a +// template-shaped body no build ever shipped is the dead producer that left an +// upgrade branch reachable only from tests; this fails if it comes back. +func TestSoulDoesNotRecogniseAnUnshippedTemplate(t *testing.T) { t.Parallel() - var doc SoulDocument - if got := doc.Match("anything"); got != SoulEdit { - t.Fatalf("empty document Match = %v, want SoulEdit", got) + const unshipped = "# Archie\n\nOld starter identity.\n" + if SoulMatchesShipped(unshipped, ShippedSoul()) { + t.Fatal("an unshipped template body was treated as untouched scaffolding") } } diff --git a/internal/infrastructure/configuration/soul.go b/internal/infrastructure/configuration/soul.go index 1cf95175a..3039bf567 100644 --- a/internal/infrastructure/configuration/soul.go +++ b/internal/infrastructure/configuration/soul.go @@ -15,7 +15,7 @@ import ( // later concern and are not invented here. const SoulFilename = "SOUL.md" -// maxSoulReadBytes bounds how much of an existing SOUL file the upgrade check +// maxSoulReadBytes bounds how much of an existing SOUL file the seed check // reads. A SOUL is at most 8 KiB once validated, so a larger file cannot be a // shipped template and is treated as a user edit without reading it in full. const maxSoulReadBytes = 64 << 10 @@ -26,8 +26,6 @@ type SoulSeedAction string const ( // SoulCreated wrote the starter because no file existed. SoulCreated SoulSeedAction = "created" - // SoulUpgraded replaced a file that was still exactly a shipped template. - SoulUpgraded SoulSeedAction = "upgraded" // SoulCurrent found the build's current document already in place. SoulCurrent SoulSeedAction = "current" // SoulPreserved left a user edit (or an unreadable/oversized file) alone. @@ -59,32 +57,31 @@ func SoulPath(configPath string) string { } // SeedSoul writes the starter SOUL into the configuration directory when no -// file exists, upgrades a file whose content is still exactly a shipped -// template, and leaves anything else untouched. It never overwrites a user +// file exists and leaves an existing file untouched. It never overwrites a user // edit, including an empty file. // // The check is content, not provenance, because the only durable copy of a // file-owned SOUL is the file itself: an operator who edited it by hand leaves -// no writer identity to consult, so a body that differs from every shipped -// template in any way is treated as theirs. +// no writer identity to consult, so a body that differs from the build's +// shipped document is treated as theirs. // // The caller owns the decision to seed at all. A failure is returned rather // than suppressed, because whether a missing starter is fatal belongs to the // caller that needs the file, not to the seeder. -func SeedSoul(configPath string, doc agent.SoulDocument) (SoulSeedResult, error) { +func SeedSoul(configPath, shipped string) (SoulSeedResult, error) { dir := ConfigDir(configPath) if err := os.MkdirAll(dir, 0o700); err != nil { return SoulSeedResult{}, fmt.Errorf("soul: create config dir %s: %w", dir, err) } - return seedSoulFile(filepath.Join(dir, SoulFilename), doc) + return seedSoulFile(filepath.Join(dir, SoulFilename), shipped) } -// seedSoulFile applies the seed/upgrade/preserve decision to one path. -func seedSoulFile(path string, doc agent.SoulDocument) (SoulSeedResult, error) { +// seedSoulFile applies the seed/preserve decision to one path. +func seedSoulFile(path, shipped string) (SoulSeedResult, error) { info, err := os.Lstat(path) switch { case errors.Is(err, fs.ErrNotExist): - if err := createSoulExclusive(path, doc.Default); err != nil { + if err := createSoulExclusive(path, shipped); err != nil { if !errors.Is(err, fs.ErrExist) { return SoulSeedResult{Path: path}, err } @@ -102,16 +99,15 @@ func seedSoulFile(path string, doc agent.SoulDocument) (SoulSeedResult, error) { case err != nil: return SoulSeedResult{Path: path}, fmt.Errorf("soul: stat %s: %w", path, err) } - return classifyExistingSoul(path, info, doc) + return classifyExistingSoul(path, info, shipped) } // classifyExistingSoul decides what to do with a SOUL file that is already on -// disk: leave the build's current document, upgrade an untouched shipped -// template, and preserve everything else. -func classifyExistingSoul(path string, info fs.FileInfo, doc agent.SoulDocument) (SoulSeedResult, error) { +// disk: leave the build's current document in place and preserve everything +// else. +func classifyExistingSoul(path string, info fs.FileInfo, shipped string) (SoulSeedResult, error) { // A symlink or any other non-regular file was not created by this seeder. - // Replacing it (an upgrade writes by rename) would destroy a user-managed - // indirection, so it is preserved. + // A rewrite would destroy a user-managed indirection, so it is preserved. if !info.Mode().IsRegular() { return SoulSeedResult{Path: path, Action: SoulPreserved}, nil } @@ -124,17 +120,10 @@ func classifyExistingSoul(path string, info fs.FileInfo, doc agent.SoulDocument) return SoulSeedResult{Path: path}, fmt.Errorf("soul: read %s: %w", path, err) } - switch doc.Match(string(content)) { - case agent.SoulCurrent: + if agent.SoulMatchesShipped(string(content), shipped) { return SoulSeedResult{Path: path, Action: SoulCurrent}, nil - case agent.SoulSuperseded: - if err := replaceSoul(path, doc.Default); err != nil { - return SoulSeedResult{Path: path}, err - } - return SoulSeedResult{Path: path, Action: SoulUpgraded}, nil - default: - return SoulSeedResult{Path: path, Action: SoulPreserved}, nil } + return SoulSeedResult{Path: path, Action: SoulPreserved}, nil } // createSoulExclusive writes the starter without ever replacing a file that @@ -153,33 +142,3 @@ func createSoulExclusive(path, content string) error { } return nil } - -// replaceSoul swaps in the current document atomically, so a reader never -// observes a half-written SOUL and an interrupted upgrade leaves the previous -// content intact. -func replaceSoul(path, content string) error { - dir := filepath.Dir(path) - temp, err := os.CreateTemp(dir, ".SOUL.md.*") - if err != nil { - return fmt.Errorf("soul: create temp beside %s: %w", path, err) - } - tempName := temp.Name() - // Best-effort: a successful rename has already moved the file away. - defer func() { _ = os.Remove(tempName) }() - - if err := temp.Chmod(0o600); err != nil { - _ = temp.Close() - return fmt.Errorf("soul: chmod %s: %w", tempName, err) - } - if _, err := temp.WriteString(content); err != nil { - _ = temp.Close() - return fmt.Errorf("soul: write %s: %w", tempName, err) - } - if err := temp.Close(); err != nil { - return fmt.Errorf("soul: close %s: %w", tempName, err) - } - if err := os.Rename(tempName, path); err != nil { - return fmt.Errorf("soul: replace %s: %w", path, err) - } - return nil -} diff --git a/internal/infrastructure/configuration/soul_test.go b/internal/infrastructure/configuration/soul_test.go index cbb287b29..bb0bd71ab 100644 --- a/internal/infrastructure/configuration/soul_test.go +++ b/internal/infrastructure/configuration/soul_test.go @@ -68,7 +68,7 @@ func TestSeedSoulCreatesStarterWhenAbsent(t *testing.T) { if err != nil { t.Fatal(err) } - if string(got) != agent.ShippedSoul().Default { + if string(got) != agent.ShippedSoul() { t.Fatalf("seeded SOUL = %q, want the shipped default", got) } info, err := os.Stat(result.Path) @@ -124,7 +124,7 @@ func TestSeedSoulLeavesACurrentDocumentUntouched(t *testing.T) { // A CRLF checkout of the current document is still current: normalising // line endings must not make it look like a user edit, and it must not // provoke a rewrite on every boot. - existing := strings.ReplaceAll(agent.ShippedSoul().Default, "\n", "\r\n") + existing := strings.ReplaceAll(agent.ShippedSoul(), "\n", "\r\n") writeSoulTestFile(t, dir, existing) result, err := SeedSoul(dir, agent.ShippedSoul()) @@ -139,36 +139,25 @@ func TestSeedSoulLeavesACurrentDocumentUntouched(t *testing.T) { } } -func TestSeedSoulUpgradesASupersededTemplate(t *testing.T) { +// A body that merely looks like a starter template is the user's until a build +// ships it: the seeder must not rewrite content no upgrade produced. This fails +// if an unshipped body is ever added to the recognised templates. +func TestSeedSoulPreservesATemplateShapedUserEdit(t *testing.T) { t.Parallel() - const legacy = "# Archie\n\nOld starter identity.\n" - const current = "# Archie\n\nNew starter identity.\n" - doc := agent.SoulDocument{Default: current, Legacy: []string{legacy}} - dir := t.TempDir() - writeSoulTestFile(t, dir, strings.ReplaceAll(legacy, "\n", "\r\n")) + existing := "# Archie\n\nOld starter identity.\n" + writeSoulTestFile(t, dir, existing) - result, err := SeedSoul(dir, doc) + result, err := SeedSoul(dir, agent.ShippedSoul()) if err != nil { t.Fatalf("SeedSoul() error = %v", err) } - if result.Action != SoulUpgraded { - t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulUpgraded) + if result.Action != SoulPreserved { + t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulPreserved) } - if got := readSoulTestFile(t, dir); got != current { - t.Fatalf("upgraded SOUL = %q, want %q", got, current) - } - entries, err := os.ReadDir(dir) - if err != nil { - t.Fatal(err) - } - if len(entries) != 1 { - names := make([]string, 0, len(entries)) - for _, entry := range entries { - names = append(names, entry.Name()) - } - t.Fatalf("upgrade left files behind: %v", names) + if got := readSoulTestFile(t, dir); got != existing { + t.Fatalf("template-shaped edit was changed:\n got %q\nwant %q", got, existing) } } @@ -213,7 +202,7 @@ func TestSeedSoulTreatsAnOversizedFileAsAUserEdit(t *testing.T) { t.Parallel() dir := t.TempDir() - oversized := agent.ShippedSoul().Default + strings.Repeat("padding line\n", maxSoulReadBytes/8) + oversized := agent.ShippedSoul() + strings.Repeat("padding line\n", maxSoulReadBytes/8) writeSoulTestFile(t, dir, oversized) result, err := SeedSoul(dir, agent.ShippedSoul())