refactor(agent): drop the SOUL upgrade branch with no shipped template
ShippedSoul returned an empty SoulDocument.Legacy, so SoulSuperseded,
replaceSoul and SoulUpgraded had no production producer: the only body the
build ships is its current default, which classifies as SoulCurrent, and only
tests constructed a Legacy document. No earlier SOUL ever shipped (the file was
introduced with the starter in cc83c9ae), so the upgrade path has nothing to
consume.
Remove the speculative machinery and keep the behaviour that is real: seed the
starter when no file exists, recognise the shipped default as current, and
preserve every other body, including a template-shaped edit. A build that
supersedes the starter reintroduces the upgrade together with the old body it
consumes.
This commit is contained in:
1 parent
656d21520f
commit
457da2e97d
5 files changed
+75
-166
No files matched your search
@@ -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)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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")
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
@@ -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())
|
||||
|
||||
Reference in new issue
Block a user