amadan

carlos / platform Public

park: home gets its own engine region, outside the placement alphabet

The home placement's code is "", which the engine and the claim read as
unset. HomeRegion ("@home") is home's engine region; PlacementRegion maps
a placement code to it once, at the boundary where a box's or a record's
code becomes an engine region. "" keeps its meaning everywhere. No engine
logic changes: the tests show, through Engine.Run, Sweep, Decide and
LiveGenerations, that home and named regions (one named "home" among
them) never stand for each other, that home's archive keys carry no region
or empty segment, and that unset and invalid regions still refuse.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
claude 6dd7297f38780803aabab92065df8699b4721617 parent bc25674
2 files changed, +298 −0
  • internal/park/home_region_test.go +262 −0
  • internal/park/region.go +36 −0
diff --git a/internal/park/home_region_test.go b/internal/park/home_region_test.go
new file mode 100644
index 000000000..256e8b6fd
--- /dev/null
+++ b/internal/park/home_region_test.go
@@ -0,0 +1,262 @@
+package park
+
+import (
+ "context"
+ "errors"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/carlosframework/platform/internal/hostclaim"
+ "github.com/carlosframework/platform/internal/provision"
+)
+
+// Home-region parks, part 1 (Paul, 2026-10-11). The home placement's code is
+// "", which the engine has always read as unset and refused. Home gets its
+// own engine region, HomeRegion, outside the placement-code alphabet, mapped
+// once from the placement code (PlacementRegion); "" keeps its meaning.
+
+// TestHomeRegionIsReserved: HomeRegion is not a placement code, so no named
+// region can ever equal it, and PlacementRegion agrees with the placement
+// validator on what a code is.
+func TestHomeRegionIsReserved(t *testing.T) {
+ if HomeRegion == "" || provision.ValidRegion(HomeRegion) {
+ t.Fatalf("HomeRegion %q is a placement code", HomeRegion)
+ }
+ if got := PlacementRegion(""); got != HomeRegion {
+ t.Fatalf("the home's code maps to %q, want %q", got, HomeRegion)
+ }
+ for _, code := range []string{"ie", "uk", "home", "none", "0", "a-b", "eu-west-1", strings.Repeat("a", 16)} {
+ if got := PlacementRegion(code); got != code || got == HomeRegion {
+ t.Fatalf("named code %q maps to %q", code, got)
+ }
+ }
+ for _, code := range []string{HomeRegion, hostclaim.RootGeneration, "IE", "ie/", "/", "a b", "ie\x00", "..", "région", strings.Repeat("a", 17)} {
+ if got := PlacementRegion(code); got != "" {
+ t.Fatalf("invalid code %q maps to %q, want unset", code, got)
+ }
+ }
+ // The local alphabet is the validator's, never wider.
+ for _, code := range []string{"", "a", "-", "z9", "ie", "IE", "@home", "@", "a_b", "a.b", strings.Repeat("x", 16), strings.Repeat("x", 17)} {
+ if (PlacementRegion(code) != "") != provision.ValidRegion(code) {
+ t.Fatalf("PlacementRegion(%q) = %q disagrees with provision.ValidRegion = %v", code, PlacementRegion(code), provision.ValidRegion(code))
+ }
+ }
+}
+
+// choreIn rewrites the fixture's one chore (and the claim's touched region)
+// to region.
+func choreIn(t *testing.T, f *fixture, region string) {
+ t.Helper()
+ obs, err := hostclaim.Read(t.Context(), f.e.Claims, f.w.Host)
+ if err != nil {
+ t.Fatal(err)
+ }
+ f.ob.Region, f.ob.Owner = region, "region:"+region
+ if _, err := hostclaim.Update(t.Context(), f.e.Claims, obs, func(c *hostclaim.Claim) error {
+ c.Obligations = []hostclaim.Obligation{f.ob}
+ c.Touched.Regions = []string{region}
+ return nil
+ }); err != nil {
+ t.Fatal(err)
+ }
+}
+
+// engineIn points the fixture's engine at region, its view seen from seen.
+func engineIn(f *fixture, region, seen string) {
+ f.e.Region = region
+ f.e.View = func(_ context.Context, o hostclaim.Observed) (View, error) {
+ return View{ClaimETag: o.ETag, Region: seen, AuthoritativeRegion: "uk"}, nil
+ }
+}
+
+// TestHomeAndNamedEnginesNeverRunEachOthersChores: through Engine.Run, an
+// engine for home never acts on a named region's chore, a named region's
+// engine (one named "home" among them) never acts on home's, and a home
+// engine whose view is seen from another region acts on nothing. Each
+// refusal leaves the bucket and the claim as they were.
+func TestHomeAndNamedEnginesNeverRunEachOthersChores(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ chore, engine, view string
+ want error
+ }{
+ {"home engine, named chore", "ie", HomeRegion, HomeRegion, ErrUnsafe},
+ {"named engine, home chore", HomeRegion, "ie", "ie", ErrUnsafe},
+ {"engine named home, home chore", HomeRegion, "home", "home", ErrUnsafe},
+ {"home engine, home chore, view from ie", HomeRegion, HomeRegion, "ie", ErrChanged},
+ {"unset engine, unset view, home chore", HomeRegion, "", "", ErrUnsafe},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ f := newFixture(t)
+ f.seed()
+ choreIn(t, f, tc.chore)
+ engineIn(f, tc.engine, tc.view)
+ before := f.b.Snapshot()
+ if err := f.e.Run(t.Context(), f.w); !errors.Is(err, tc.want) {
+ t.Fatalf("run: %v, want %v", err, tc.want)
+ }
+ if f.b.Snapshot() != before {
+ t.Fatal("the bucket changed")
+ }
+ obs, err := hostclaim.Read(t.Context(), f.e.Claims, f.w.Host)
+ if err != nil || len(obs.Claim.Obligations) != 1 || obs.Claim.Obligations[0].Region != tc.chore || len(obs.Claim.QuietAfter) != 0 {
+ t.Fatalf("the claim changed: %+v %v", obs.Claim, err)
+ }
+ })
+ }
+}
+
+// TestHomeEngineParksUnderItsOwnRegion: a home engine runs a home chore to
+// its acknowledgement. The archive's keys carry no region and no empty
+// segment; the manifest, the quiet window and the coverage name HomeRegion,
+// never "" and never a named region.
+func TestHomeEngineParksUnderItsOwnRegion(t *testing.T) {
+ f := newFixture(t)
+ source := f.seed()
+ choreIn(t, f, HomeRegion)
+ engineIn(f, HomeRegion, HomeRegion)
+ if err := f.e.Run(t.Context(), f.w); err != nil {
+ t.Fatal(err)
+ }
+ obs, err := hostclaim.Read(t.Context(), f.e.Claims, f.w.Host)
+ if err != nil || len(obs.Claim.Obligations) != 0 {
+ t.Fatalf("still owed: %+v %v", obs.Claim, err)
+ }
+ if got, want := obs.Claim.QuietAfter[HomeRegion], f.ob.Park.EvidenceAt.Add(SignatureAge+time.Second); !got.Equal(want) || len(obs.Claim.QuietAfter) != 1 {
+ t.Fatalf("quiet_after %v, want only %s at %v", obs.Claim.QuietAfter, HomeRegion, want)
+ }
+ m, err := f.e.manifest(t.Context(), f.w, f.ob)
+ if err != nil || m == nil || m.Region != HomeRegion || len(m.Delete) != len(source) {
+ t.Fatalf("manifest %+v %v", m, err)
+ }
+ base := "parked/" + f.ob.Park.Incarnation + "/" + f.w.Host + "/" + f.ob.Retirement + "/"
+ for _, a := range m.Archive {
+ k := a.Destination.Key
+ if !strings.HasPrefix(k, base+"instances/") || strings.Contains(k, "//") || strings.Contains(k, HomeRegion) {
+ t.Fatalf("archive key %q is not under %sinstances/ or carries a region", k, base)
+ }
+ }
+ if vs, err := f.e.list(t.Context(), f.w.Host, f.ob.Park.Location); err != nil || len(vs) != 0 {
+ t.Fatalf("residue %v %v", vs, err)
+ }
+}
+
+// TestHomeLiveSetIsRegionQualified: the live set the engine protects is
+// qualified by HomeRegion. Admissions recorded in HomeRegion form the home's
+// unfinished chain; the same admissions recorded in a named region spelled
+// "home" do not, and a view seen from a named region protects nothing of
+// home's. A pending chore in a named region never stands for home's.
+func TestHomeLiveSetIsRegionQualified(t *testing.T) {
+ inRegion := func(t *testing.T, region string) (*fixture, hostclaim.Observed, View) {
+ f, obs, v, _ := sweepFixture(t)
+ obs, err := hostclaim.Update(t.Context(), f.e.Claims, obs, func(c *hostclaim.Claim) error {
+ for i := range c.Holder.Admissions {
+ c.Holder.Admissions[i].Region, c.Holder.Admissions[i].PredecessorRegion = region, region
+ }
+ return nil
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ v.ClaimETag, v.Region, v.AuthoritativeRegion = obs.ETag, HomeRegion, HomeRegion
+ return f, obs, v
+ }
+ _, obs, v := inRegion(t, HomeRegion)
+ live, err := LiveGenerations(obs.Claim, v, "")
+ if err != nil || !live["g3"] || !live["g2"] || !live["g1"] {
+ t.Fatalf("home's own chain: %v %v", live, err)
+ }
+ _, obs, v = inRegion(t, "home")
+ if live, err := LiveGenerations(obs.Claim, v, ""); !errors.Is(err, ErrUnsafe) {
+ t.Fatalf("a chain recorded in the named region home stood for HomeRegion's: %v %v", live, err)
+ }
+ _, obs, v = inRegion(t, HomeRegion)
+ v.Region = "ie"
+ if live, err := LiveGenerations(obs.Claim, v, ""); err != nil || len(live) != 0 {
+ t.Fatalf("seen from ie, home's live set: %v %v", live, err)
+ }
+
+ // A pending chore blocks Decide only in its own region.
+ f, obs, v := inRegion(t, HomeRegion)
+ vs, err := f.e.Discover(t.Context(), f.w.Host)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, region := range []string{"ie", "home", HomeRegion} {
+ ob := f.ob
+ ob.Region, ob.Owner = region, "region:"+region
+ c := *obs.Claim
+ c.Obligations = []hostclaim.Obligation{ob}
+ d, err := Decide(hostclaim.Observed{Host: obs.Host, Claim: &c, ETag: obs.ETag}, v, vs, f.ob.Park.Incarnation)
+ if err != nil {
+ t.Fatalf("%s: %v", region, err)
+ }
+ if blocked := len(d.Candidates) == 0; blocked != (region == HomeRegion) {
+ t.Fatalf("a pending chore in %s: candidates %+v", region, d.Candidates)
+ }
+ }
+}
+
+// TestHomeSweepQueuesUnderHomeRegion: a home engine's sweep queues its
+// chores as HomeRegion's, owned by region:HomeRegion, runs them and keys the
+// quiet window by HomeRegion.
+func TestHomeSweepQueuesUnderHomeRegion(t *testing.T) {
+ f := newFixture(t)
+ f.seed()
+ obs, _ := hostclaim.Read(t.Context(), f.e.Claims, f.w.Host)
+ if _, err := hostclaim.Update(t.Context(), f.e.Claims, obs, func(c *hostclaim.Claim) error {
+ c.Obligations = nil
+ return hostclaim.FreeAfterPark("op")(c)
+ }); err != nil {
+ t.Fatal(err)
+ }
+ engineIn(f, HomeRegion, HomeRegion)
+ var queued []hostclaim.Obligation
+ f.e.Authorize = func(_ context.Context, _ hostclaim.Observed, o hostclaim.Obligation) error {
+ queued = append(queued, o)
+ return nil
+ }
+ d, err := f.e.Sweep(t.Context(), f.w.Host, f.ob.Park.Incarnation, f.ob.Park.EvidenceAt, time.Second)
+ if err != nil || len(d.Candidates) != 1 {
+ t.Fatalf("%+v %v", d, err)
+ }
+ if len(queued) == 0 {
+ t.Fatal("nothing was queued")
+ }
+ for _, o := range queued {
+ if o.Region != HomeRegion || o.Owner != "region:"+HomeRegion {
+ t.Fatalf("queued %+v, want region %s", o, HomeRegion)
+ }
+ }
+ obs, err = hostclaim.Read(t.Context(), f.e.Claims, f.w.Host)
+ if err != nil || !obs.Claim.Free() || len(obs.Claim.Obligations) != 0 {
+ t.Fatalf("%+v %v", obs, err)
+ }
+ if _, ok := obs.Claim.QuietAfter[HomeRegion]; !ok || len(obs.Claim.QuietAfter) != 1 {
+ t.Fatalf("quiet_after %v", obs.Claim.QuietAfter)
+ }
+}
+
+// TestUnsetRegionStillRefuses: "" is still unset at every engine entry, and
+// an invalid placement code maps to it.
+func TestUnsetRegionStillRefuses(t *testing.T) {
+ f, obs, v, vs := sweepFixture(t)
+ v.Region = ""
+ if _, err := Decide(obs, v, vs, f.ob.Park.Incarnation); !errors.Is(err, ErrUnsafe) {
+ t.Fatalf("decide from an unset region: %v", err)
+ }
+ v.Region, v.AuthoritativeRegion = "ie", ""
+ if _, err := LiveGenerations(obs.Claim, v, ""); !errors.Is(err, ErrUnsafe) {
+ t.Fatalf("an unset authoritative region: %v", err)
+ }
+ g := newFixture(t)
+ g.seed()
+ for _, code := range []string{"IE", "@home", "a/b"} {
+ engineIn(g, PlacementRegion(code), PlacementRegion(code))
+ before := g.b.Snapshot()
+ if err := g.e.Run(t.Context(), g.w); !errors.Is(err, ErrUnsafe) || g.b.Snapshot() != before {
+ t.Fatalf("an engine for invalid code %q: %v", code, err)
+ }
+ }
+}
diff --git a/internal/park/region.go b/internal/park/region.go
new file mode 100644
index 000000000..c5bd073aa
--- /dev/null
+++ b/internal/park/region.go
@@ -0,0 +1,36 @@
+package park
+
+import "regexp"
+
+// HomeRegion is the engine region of the home placement (home-region parks,
+// part 1, Paul 2026-10-11). The home's placement code is "", and "" already
+// means unset to the engine and to the claim: an engine, view, chore or
+// admission with region "" is refused or read as "holds nothing anywhere".
+// So home is never "" here. It is this token, mapped once from the placement
+// code by PlacementRegion where a box's or a record's code becomes an engine
+// region.
+//
+// The "@" is outside the placement-code alphabet (provision.ValidRegion:
+// lowercase a-z, 0-9 and hyphen), so no named region, one named "home"
+// included, can ever equal it. It reaches the claim's obligation region, its
+// "region:" owner and its quiet_after key. It never reaches an object key or
+// a path: the archive is parked/<incarnation>/<host>/<retirement>/.
+const HomeRegion = "@home"
+
+// placementCode is a named placement code: provision.ValidRegion without the
+// empty code. TestHomeRegionIsReserved holds the two together.
+var placementCode = regexp.MustCompile(`^[a-z0-9-]{1,16}$`)
+
+// PlacementRegion is the engine region of a placement code: HomeRegion for
+// the home's "", a named code unchanged, and "" (unset, which every engine
+// entry refuses) for anything that is not a placement code, HomeRegion
+// itself included.
+func PlacementRegion(code string) string {
+ switch {
+ case code == "":
+ return HomeRegion
+ case placementCode.MatchString(code):
+ return code
+ }
+ return ""
+}